From 06435413a530140207644bdfdd3a25021a1821b0 Mon Sep 17 00:00:00 2001 From: bailuk Date: Mon, 17 Mar 2025 15:57:10 +0100 Subject: [PATCH 1/5] Update changelog and copyright notice --- CHANGELOG.md | 8 +++++++- LICENSE | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 20c04de..62c89c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,10 @@ -# Release (0.5.0) +# Next + +- Generator: Add markdown summary logs +- Generator: Add gstreamer support +- Library: Add PropertyHolder to accesss GObject properties + +# 0.5.0 - Add `shell.nix` as documentation - Support JDK21 diff --git a/LICENSE b/LICENSE index feac28e..a04856c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2021 - 2024 Lukas Bai +Copyright (c) 2021 - 2025 Lukas Bai Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From 0abc36a1035005f2d4eb4f7db0e373424e259c65 Mon Sep 17 00:00:00 2001 From: bailuk Date: Mon, 17 Mar 2025 16:19:41 +0100 Subject: [PATCH 2/5] Update gradle to verion 8.13 and update release plugin to version 1.15.0 --- build.gradle.kts | 2 +- generator/build.gradle.kts | 9 ++++++--- gradle/wrapper/gradle-wrapper.jar | Bin 62076 -> 43462 bytes gradle/wrapper/gradle-wrapper.properties | 3 ++- gradlew | 22 +++++++++++++--------- java-gtk/build.gradle.kts | 12 ++++++++---- 6 files changed, 30 insertions(+), 18 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index 70c8f5b..380b6a5 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -6,7 +6,7 @@ plugins { * ./gradlew cV * */ - id ("pl.allegro.tech.build.axion-release") version "1.15.0" + id ("pl.allegro.tech.build.axion-release") version "1.18.18" } project.version = scmVersion.version diff --git a/generator/build.gradle.kts b/generator/build.gradle.kts index 1628b1a..be22d24 100644 --- a/generator/build.gradle.kts +++ b/generator/build.gradle.kts @@ -19,11 +19,14 @@ dependencies { } -tasks.test { - useJUnitPlatform() +testing { + suites { + val test by getting(JvmTestSuite::class) { + useJUnitJupiter() + } + } } - tasks.register("generate-update-doc", JavaExec::class) { description = "Generate source code from introspective files and update meta documentation" registerGeneratorTask(this) diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar index c1962a79e29d3e0ab67b14947c167a862655af9b..d64cd4917707c1f8861d8cb53dd15194d4248596 100644 GIT binary patch literal 43462 zcma&NWl&^owk(X(xVyW%ySuwf;qI=D6|RlDJ2cR^yEKh!@I- zp9QeisK*rlxC>+~7Dk4IxIRsKBHqdR9b3+fyL=ynHmIDe&|>O*VlvO+%z5;9Z$|DJ zb4dO}-R=MKr^6EKJiOrJdLnCJn>np?~vU-1sSFgPu;pthGwf}bG z(1db%xwr#x)r+`4AGu$j7~u2MpVs3VpLp|mx&;>`0p0vH6kF+D2CY0fVdQOZ@h;A` z{infNyvmFUiu*XG}RNMNwXrbec_*a3N=2zJ|Wh5z* z5rAX$JJR{#zP>KY**>xHTuw?|-Rg|o24V)74HcfVT;WtQHXlE+_4iPE8QE#DUm%x0 zEKr75ur~W%w#-My3Tj`hH6EuEW+8K-^5P62$7Sc5OK+22qj&Pd1;)1#4tKihi=~8C zHiQSst0cpri6%OeaR`PY>HH_;CPaRNty%WTm4{wDK8V6gCZlG@U3$~JQZ;HPvDJcT1V{ z?>H@13MJcCNe#5z+MecYNi@VT5|&UiN1D4ATT+%M+h4c$t;C#UAs3O_q=GxK0}8%8 z8J(_M9bayxN}69ex4dzM_P3oh@ZGREjVvn%%r7=xjkqxJP4kj}5tlf;QosR=%4L5y zWhgejO=vao5oX%mOHbhJ8V+SG&K5dABn6!WiKl{|oPkq(9z8l&Mm%(=qGcFzI=eLu zWc_oCLyf;hVlB@dnwY98?75B20=n$>u3b|NB28H0u-6Rpl((%KWEBOfElVWJx+5yg z#SGqwza7f}$z;n~g%4HDU{;V{gXIhft*q2=4zSezGK~nBgu9-Q*rZ#2f=Q}i2|qOp z!!y4p)4o=LVUNhlkp#JL{tfkhXNbB=Ox>M=n6soptJw-IDI|_$is2w}(XY>a=H52d z3zE$tjPUhWWS+5h=KVH&uqQS=$v3nRs&p$%11b%5qtF}S2#Pc`IiyBIF4%A!;AVoI zXU8-Rpv!DQNcF~(qQnyyMy=-AN~U>#&X1j5BLDP{?K!%h!;hfJI>$mdLSvktEr*89 zdJHvby^$xEX0^l9g$xW-d?J;L0#(`UT~zpL&*cEh$L|HPAu=P8`OQZV!-}l`noSp_ zQ-1$q$R-gDL)?6YaM!=8H=QGW$NT2SeZlb8PKJdc=F-cT@j7Xags+Pr*jPtlHFnf- zh?q<6;)27IdPc^Wdy-mX%2s84C1xZq9Xms+==F4);O`VUASmu3(RlgE#0+#giLh-& zcxm3_e}n4{%|X zJp{G_j+%`j_q5}k{eW&TlP}J2wtZ2^<^E(O)4OQX8FDp6RJq!F{(6eHWSD3=f~(h} zJXCf7=r<16X{pHkm%yzYI_=VDP&9bmI1*)YXZeB}F? z(%QsB5fo*FUZxK$oX~X^69;x~j7ms8xlzpt-T15e9}$4T-pC z6PFg@;B-j|Ywajpe4~bk#S6(fO^|mm1hKOPfA%8-_iGCfICE|=P_~e;Wz6my&)h_~ zkv&_xSAw7AZ%ThYF(4jADW4vg=oEdJGVOs>FqamoL3Np8>?!W#!R-0%2Bg4h?kz5I zKV-rKN2n(vUL%D<4oj@|`eJ>0i#TmYBtYmfla;c!ATW%;xGQ0*TW@PTlGG><@dxUI zg>+3SiGdZ%?5N=8uoLA|$4isK$aJ%i{hECP$bK{J#0W2gQ3YEa zZQ50Stn6hqdfxJ*9#NuSLwKFCUGk@c=(igyVL;;2^wi4o30YXSIb2g_ud$ zgpCr@H0qWtk2hK8Q|&wx)}4+hTYlf;$a4#oUM=V@Cw#!$(nOFFpZ;0lc!qd=c$S}Z zGGI-0jg~S~cgVT=4Vo)b)|4phjStD49*EqC)IPwyeKBLcN;Wu@Aeph;emROAwJ-0< z_#>wVm$)ygH|qyxZaet&(Vf%pVdnvKWJn9`%DAxj3ot;v>S$I}jJ$FLBF*~iZ!ZXE zkvui&p}fI0Y=IDX)mm0@tAd|fEHl~J&K}ZX(Mm3cm1UAuwJ42+AO5@HwYfDH7ipIc zmI;1J;J@+aCNG1M`Btf>YT>~c&3j~Qi@Py5JT6;zjx$cvOQW@3oQ>|}GH?TW-E z1R;q^QFjm5W~7f}c3Ww|awg1BAJ^slEV~Pk`Kd`PS$7;SqJZNj->it4DW2l15}xP6 zoCl$kyEF%yJni0(L!Z&14m!1urXh6Btj_5JYt1{#+H8w?5QI%% zo-$KYWNMJVH?Hh@1n7OSu~QhSswL8x0=$<8QG_zepi_`y_79=nK=_ZP_`Em2UI*tyQoB+r{1QYZCpb?2OrgUw#oRH$?^Tj!Req>XiE#~B|~ z+%HB;=ic+R@px4Ld8mwpY;W^A%8%l8$@B@1m5n`TlKI6bz2mp*^^^1mK$COW$HOfp zUGTz-cN9?BGEp}5A!mDFjaiWa2_J2Iq8qj0mXzk; z66JBKRP{p%wN7XobR0YjhAuW9T1Gw3FDvR5dWJ8ElNYF94eF3ebu+QwKjtvVu4L zI9ip#mQ@4uqVdkl-TUQMb^XBJVLW(-$s;Nq;@5gr4`UfLgF$adIhd?rHOa%D);whv z=;krPp~@I+-Z|r#s3yCH+c1US?dnm+C*)r{m+86sTJusLdNu^sqLrfWed^ndHXH`m zd3#cOe3>w-ga(Dus_^ppG9AC>Iq{y%%CK+Cro_sqLCs{VLuK=dev>OL1dis4(PQ5R zcz)>DjEkfV+MO;~>VUlYF00SgfUo~@(&9$Iy2|G0T9BSP?&T22>K46D zL*~j#yJ?)^*%J3!16f)@Y2Z^kS*BzwfAQ7K96rFRIh>#$*$_Io;z>ux@}G98!fWR@ zGTFxv4r~v)Gsd|pF91*-eaZ3Qw1MH$K^7JhWIdX%o$2kCbvGDXy)a?@8T&1dY4`;L z4Kn+f%SSFWE_rpEpL9bnlmYq`D!6F%di<&Hh=+!VI~j)2mfil03T#jJ_s?}VV0_hp z7T9bWxc>Jm2Z0WMU?`Z$xE74Gu~%s{mW!d4uvKCx@WD+gPUQ zV0vQS(Ig++z=EHN)BR44*EDSWIyT~R4$FcF*VEY*8@l=218Q05D2$|fXKFhRgBIEE zdDFB}1dKkoO^7}{5crKX!p?dZWNz$m>1icsXG2N+((x0OIST9Zo^DW_tytvlwXGpn zs8?pJXjEG;T@qrZi%#h93?FP$!&P4JA(&H61tqQi=opRzNpm zkrG}$^t9&XduK*Qa1?355wd8G2CI6QEh@Ua>AsD;7oRUNLPb76m4HG3K?)wF~IyS3`fXuNM>${?wmB zpVz;?6_(Fiadfd{vUCBM*_kt$+F3J+IojI;9L(gc9n3{sEZyzR9o!_mOwFC#tQ{Q~ zP3-`#uK#tP3Q7~Q;4H|wjZHO8h7e4IuBxl&vz2w~D8)w=Wtg31zpZhz%+kzSzL*dV zwp@{WU4i;hJ7c2f1O;7Mz6qRKeASoIv0_bV=i@NMG*l<#+;INk-^`5w@}Dj~;k=|}qM1vq_P z|GpBGe_IKq|LNy9SJhKOQ$c=5L{Dv|Q_lZl=-ky*BFBJLW9&y_C|!vyM~rQx=!vun z?rZJQB5t}Dctmui5i31C_;_}CEn}_W%>oSXtt>@kE1=JW*4*v4tPp;O6 zmAk{)m!)}34pTWg8{i>($%NQ(Tl;QC@J@FfBoc%Gr&m560^kgSfodAFrIjF}aIw)X zoXZ`@IsMkc8_=w%-7`D6Y4e*CG8k%Ud=GXhsTR50jUnm+R*0A(O3UKFg0`K;qp1bl z7``HN=?39ic_kR|^R^~w-*pa?Vj#7|e9F1iRx{GN2?wK!xR1GW!qa=~pjJb-#u1K8 zeR?Y2i-pt}yJq;SCiVHODIvQJX|ZJaT8nO+(?HXbLefulKKgM^B(UIO1r+S=7;kLJ zcH}1J=Px2jsh3Tec&v8Jcbng8;V-`#*UHt?hB(pmOipKwf3Lz8rG$heEB30Sg*2rx zV<|KN86$soN(I!BwO`1n^^uF2*x&vJ$2d$>+`(romzHP|)K_KkO6Hc>_dwMW-M(#S zK(~SiXT1@fvc#U+?|?PniDRm01)f^#55;nhM|wi?oG>yBsa?~?^xTU|fX-R(sTA+5 zaq}-8Tx7zrOy#3*JLIIVsBmHYLdD}!0NP!+ITW+Thn0)8SS!$@)HXwB3tY!fMxc#1 zMp3H?q3eD?u&Njx4;KQ5G>32+GRp1Ee5qMO0lZjaRRu&{W<&~DoJNGkcYF<5(Ab+J zgO>VhBl{okDPn78<%&e2mR{jwVCz5Og;*Z;;3%VvoGo_;HaGLWYF7q#jDX=Z#Ml`H z858YVV$%J|e<1n`%6Vsvq7GmnAV0wW4$5qQ3uR@1i>tW{xrl|ExywIc?fNgYlA?C5 zh$ezAFb5{rQu6i7BSS5*J-|9DQ{6^BVQ{b*lq`xS@RyrsJN?-t=MTMPY;WYeKBCNg z^2|pN!Q^WPJuuO4!|P@jzt&tY1Y8d%FNK5xK(!@`jO2aEA*4 zkO6b|UVBipci?){-Ke=+1;mGlND8)6+P;8sq}UXw2hn;fc7nM>g}GSMWu&v&fqh

iViYT=fZ(|3Ox^$aWPp4a8h24tD<|8-!aK0lHgL$N7Efw}J zVIB!7=T$U`ao1?upi5V4Et*-lTG0XvExbf!ya{cua==$WJyVG(CmA6Of*8E@DSE%L z`V^$qz&RU$7G5mg;8;=#`@rRG`-uS18$0WPN@!v2d{H2sOqP|!(cQ@ zUHo!d>>yFArLPf1q`uBvY32miqShLT1B@gDL4XoVTK&@owOoD)OIHXrYK-a1d$B{v zF^}8D3Y^g%^cnvScOSJR5QNH+BI%d|;J;wWM3~l>${fb8DNPg)wrf|GBP8p%LNGN# z3EaIiItgwtGgT&iYCFy9-LG}bMI|4LdmmJt@V@% zb6B)1kc=T)(|L@0;wr<>=?r04N;E&ef+7C^`wPWtyQe(*pD1pI_&XHy|0gIGHMekd zF_*M4yi6J&Z4LQj65)S zXwdM{SwUo%3SbPwFsHgqF@V|6afT|R6?&S;lw=8% z3}@9B=#JI3@B*#4s!O))~z zc>2_4Q_#&+5V`GFd?88^;c1i7;Vv_I*qt!_Yx*n=;rj!82rrR2rQ8u5(Ejlo{15P% zs~!{%XJ>FmJ})H^I9bn^Re&38H{xA!0l3^89k(oU;bZWXM@kn$#aoS&Y4l^-WEn-fH39Jb9lA%s*WsKJQl?n9B7_~P z-XM&WL7Z!PcoF6_D>V@$CvUIEy=+Z&0kt{szMk=f1|M+r*a43^$$B^MidrT0J;RI` z(?f!O<8UZkm$_Ny$Hth1J#^4ni+im8M9mr&k|3cIgwvjAgjH z8`N&h25xV#v*d$qBX5jkI|xOhQn!>IYZK7l5#^P4M&twe9&Ey@@GxYMxBZq2e7?`q z$~Szs0!g{2fGcp9PZEt|rdQ6bhAgpcLHPz?f-vB?$dc*!9OL?Q8mn7->bFD2Si60* z!O%y)fCdMSV|lkF9w%x~J*A&srMyYY3{=&$}H zGQ4VG_?$2X(0|vT0{=;W$~icCI{b6W{B!Q8xdGhF|D{25G_5_+%s(46lhvNLkik~R z>nr(&C#5wwOzJZQo9m|U<;&Wk!_#q|V>fsmj1g<6%hB{jGoNUPjgJslld>xmODzGjYc?7JSuA?A_QzjDw5AsRgi@Y|Z0{F{!1=!NES-#*f^s4l0Hu zz468))2IY5dmD9pa*(yT5{EyP^G>@ZWumealS-*WeRcZ}B%gxq{MiJ|RyX-^C1V=0 z@iKdrGi1jTe8Ya^x7yyH$kBNvM4R~`fbPq$BzHum-3Zo8C6=KW@||>zsA8-Y9uV5V z#oq-f5L5}V<&wF4@X@<3^C%ptp6+Ce)~hGl`kwj)bsAjmo_GU^r940Z-|`<)oGnh7 zFF0Tde3>ui?8Yj{sF-Z@)yQd~CGZ*w-6p2U<8}JO-sRsVI5dBji`01W8A&3$?}lxBaC&vn0E$c5tW* zX>5(zzZ=qn&!J~KdsPl;P@bmA-Pr8T*)eh_+Dv5=Ma|XSle6t(k8qcgNyar{*ReQ8 zTXwi=8vr>!3Ywr+BhggHDw8ke==NTQVMCK`$69fhzEFB*4+H9LIvdt-#IbhZvpS}} zO3lz;P?zr0*0$%-Rq_y^k(?I{Mk}h@w}cZpMUp|ucs55bcloL2)($u%mXQw({Wzc~ z;6nu5MkjP)0C(@%6Q_I_vsWrfhl7Zpoxw#WoE~r&GOSCz;_ro6i(^hM>I$8y>`!wW z*U^@?B!MMmb89I}2(hcE4zN2G^kwyWCZp5JG>$Ez7zP~D=J^LMjSM)27_0B_X^C(M z`fFT+%DcKlu?^)FCK>QzSnV%IsXVcUFhFdBP!6~se&xxrIxsvySAWu++IrH;FbcY$ z2DWTvSBRfLwdhr0nMx+URA$j3i7_*6BWv#DXfym?ZRDcX9C?cY9sD3q)uBDR3uWg= z(lUIzB)G$Hr!){>E{s4Dew+tb9kvToZp-1&c?y2wn@Z~(VBhqz`cB;{E4(P3N2*nJ z_>~g@;UF2iG{Kt(<1PyePTKahF8<)pozZ*xH~U-kfoAayCwJViIrnqwqO}7{0pHw$ zs2Kx?s#vQr7XZ264>5RNKSL8|Ty^=PsIx^}QqOOcfpGUU4tRkUc|kc7-!Ae6!+B{o~7nFpm3|G5^=0#Bnm6`V}oSQlrX(u%OWnC zoLPy&Q;1Jui&7ST0~#+}I^&?vcE*t47~Xq#YwvA^6^} z`WkC)$AkNub|t@S!$8CBlwbV~?yp&@9h{D|3z-vJXgzRC5^nYm+PyPcgRzAnEi6Q^gslXYRv4nycsy-SJu?lMps-? zV`U*#WnFsdPLL)Q$AmD|0`UaC4ND07+&UmOu!eHruzV|OUox<+Jl|Mr@6~C`T@P%s zW7sgXLF2SSe9Fl^O(I*{9wsFSYb2l%-;&Pi^dpv!{)C3d0AlNY6!4fgmSgj_wQ*7Am7&$z;Jg&wgR-Ih;lUvWS|KTSg!&s_E9_bXBkZvGiC6bFKDWZxsD$*NZ#_8bl zG1P-#@?OQzED7@jlMJTH@V!6k;W>auvft)}g zhoV{7$q=*;=l{O>Q4a@ ziMjf_u*o^PsO)#BjC%0^h>Xp@;5$p{JSYDt)zbb}s{Kbt!T*I@Pk@X0zds6wsefuU zW$XY%yyRGC94=6mf?x+bbA5CDQ2AgW1T-jVAJbm7K(gp+;v6E0WI#kuACgV$r}6L? zd|Tj?^%^*N&b>Dd{Wr$FS2qI#Ucs1yd4N+RBUQiSZGujH`#I)mG&VKoDh=KKFl4=G z&MagXl6*<)$6P}*Tiebpz5L=oMaPrN+caUXRJ`D?=K9!e0f{@D&cZLKN?iNP@X0aF zE(^pl+;*T5qt?1jRC=5PMgV!XNITRLS_=9{CJExaQj;lt!&pdzpK?8p>%Mb+D z?yO*uSung=-`QQ@yX@Hyd4@CI^r{2oiu`%^bNkz+Nkk!IunjwNC|WcqvX~k=><-I3 zDQdbdb|!v+Iz01$w@aMl!R)koD77Xp;eZwzSl-AT zr@Vu{=xvgfq9akRrrM)}=!=xcs+U1JO}{t(avgz`6RqiiX<|hGG1pmop8k6Q+G_mv zJv|RfDheUp2L3=^C=4aCBMBn0aRCU(DQwX-W(RkRwmLeuJYF<0urcaf(=7)JPg<3P zQs!~G)9CT18o!J4{zX{_e}4eS)U-E)0FAt}wEI(c0%HkxgggW;(1E=>J17_hsH^sP z%lT0LGgbUXHx-K*CI-MCrP66UP0PvGqM$MkeLyqHdbgP|_Cm!7te~b8p+e6sQ_3k| zVcwTh6d83ltdnR>D^)BYQpDKlLk3g0Hdcgz2}%qUs9~~Rie)A-BV1mS&naYai#xcZ z(d{8=-LVpTp}2*y)|gR~;qc7fp26}lPcLZ#=JpYcn3AT9(UIdOyg+d(P5T7D&*P}# zQCYplZO5|7+r19%9e`v^vfSS1sbX1c%=w1;oyruXB%Kl$ACgKQ6=qNWLsc=28xJjg zwvsI5-%SGU|3p>&zXVl^vVtQT3o-#$UT9LI@Npz~6=4!>mc431VRNN8od&Ul^+G_kHC`G=6WVWM z%9eWNyy(FTO|A+@x}Ou3CH)oi;t#7rAxdIXfNFwOj_@Y&TGz6P_sqiB`Q6Lxy|Q{`|fgmRG(k+!#b*M+Z9zFce)f-7;?Km5O=LHV9f9_87; zF7%R2B+$?@sH&&-$@tzaPYkw0;=i|;vWdI|Wl3q_Zu>l;XdIw2FjV=;Mq5t1Q0|f< zs08j54Bp`3RzqE=2enlkZxmX6OF+@|2<)A^RNQpBd6o@OXl+i)zO%D4iGiQNuXd+zIR{_lb96{lc~bxsBveIw6umhShTX+3@ZJ=YHh@ zWY3(d0azg;7oHn>H<>?4@*RQbi>SmM=JrHvIG(~BrvI)#W(EAeO6fS+}mxxcc+X~W6&YVl86W9WFSS}Vz-f9vS?XUDBk)3TcF z8V?$4Q)`uKFq>xT=)Y9mMFVTUk*NIA!0$?RP6Ig0TBmUFrq*Q-Agq~DzxjStQyJ({ zBeZ;o5qUUKg=4Hypm|}>>L=XKsZ!F$yNTDO)jt4H0gdQ5$f|d&bnVCMMXhNh)~mN z@_UV6D7MVlsWz+zM+inZZp&P4fj=tm6fX)SG5H>OsQf_I8c~uGCig$GzuwViK54bcgL;VN|FnyQl>Ed7(@>=8$a_UKIz|V6CeVSd2(P z0Uu>A8A+muM%HLFJQ9UZ5c)BSAv_zH#1f02x?h9C}@pN@6{>UiAp>({Fn(T9Q8B z^`zB;kJ5b`>%dLm+Ol}ty!3;8f1XDSVX0AUe5P#@I+FQ-`$(a;zNgz)4x5hz$Hfbg z!Q(z26wHLXko(1`;(BAOg_wShpX0ixfWq3ponndY+u%1gyX)_h=v1zR#V}#q{au6; z!3K=7fQwnRfg6FXtNQmP>`<;!N137paFS%y?;lb1@BEdbvQHYC{976l`cLqn;b8lp zIDY>~m{gDj(wfnK!lpW6pli)HyLEiUrNc%eXTil|F2s(AY+LW5hkKb>TQ3|Q4S9rr zpDs4uK_co6XPsn_z$LeS{K4jFF`2>U`tbgKdyDne`xmR<@6AA+_hPNKCOR-Zqv;xk zu5!HsBUb^!4uJ7v0RuH-7?l?}b=w5lzzXJ~gZcxRKOovSk@|#V+MuX%Y+=;14i*%{)_gSW9(#4%)AV#3__kac1|qUy!uyP{>?U#5wYNq}y$S9pCc zFc~4mgSC*G~j0u#qqp9 z${>3HV~@->GqEhr_Xwoxq?Hjn#=s2;i~g^&Hn|aDKpA>Oc%HlW(KA1?BXqpxB;Ydx)w;2z^MpjJ(Qi(X!$5RC z*P{~%JGDQqojV>2JbEeCE*OEu!$XJ>bWA9Oa_Hd;y)F%MhBRi*LPcdqR8X`NQ&1L# z5#9L*@qxrx8n}LfeB^J{%-?SU{FCwiWyHp682F+|pa+CQa3ZLzBqN1{)h4d6+vBbV zC#NEbQLC;}me3eeYnOG*nXOJZEU$xLZ1<1Y=7r0(-U0P6-AqwMAM`a(Ed#7vJkn6plb4eI4?2y3yOTGmmDQ!z9`wzbf z_OY#0@5=bnep;MV0X_;;SJJWEf^E6Bd^tVJ9znWx&Ks8t*B>AM@?;D4oWUGc z!H*`6d7Cxo6VuyS4Eye&L1ZRhrRmN6Lr`{NL(wDbif|y&z)JN>Fl5#Wi&mMIr5i;x zBx}3YfF>>8EC(fYnmpu~)CYHuHCyr5*`ECap%t@y=jD>!_%3iiE|LN$mK9>- zHdtpy8fGZtkZF?%TW~29JIAfi2jZT8>OA7=h;8T{{k?c2`nCEx9$r zS+*&vt~2o^^J+}RDG@+9&M^K*z4p{5#IEVbz`1%`m5c2};aGt=V?~vIM}ZdPECDI)47|CWBCfDWUbxBCnmYivQ*0Nu_xb*C>~C9(VjHM zxe<*D<#dQ8TlpMX2c@M<9$w!RP$hpG4cs%AI){jp*Sj|*`m)5(Bw*A0$*i-(CA5#%>a)$+jI2C9r6|(>J8InryENI z$NohnxDUB;wAYDwrb*!N3noBTKPpPN}~09SEL18tkG zxgz(RYU_;DPT{l?Q$+eaZaxnsWCA^ds^0PVRkIM%bOd|G2IEBBiz{&^JtNsODs;5z zICt_Zj8wo^KT$7Bg4H+y!Df#3mbl%%?|EXe!&(Vmac1DJ*y~3+kRKAD=Ovde4^^%~ zw<9av18HLyrf*_>Slp;^i`Uy~`mvBjZ|?Ad63yQa#YK`4+c6;pW4?XIY9G1(Xh9WO8{F-Aju+nS9Vmv=$Ac0ienZ+p9*O%NG zMZKy5?%Z6TAJTE?o5vEr0r>f>hb#2w2U3DL64*au_@P!J!TL`oH2r*{>ffu6|A7tv zL4juf$DZ1MW5ZPsG!5)`k8d8c$J$o;%EIL0va9&GzWvkS%ZsGb#S(?{!UFOZ9<$a| zY|a+5kmD5N&{vRqkgY>aHsBT&`rg|&kezoD)gP0fsNYHsO#TRc_$n6Lf1Z{?+DLziXlHrq4sf(!>O{?Tj;Eh@%)+nRE_2VxbN&&%%caU#JDU%vL3}Cb zsb4AazPI{>8H&d=jUaZDS$-0^AxE@utGs;-Ez_F(qC9T=UZX=>ok2k2 ziTn{K?y~a5reD2A)P${NoI^>JXn>`IeArow(41c-Wm~)wiryEP(OS{YXWi7;%dG9v zI?mwu1MxD{yp_rrk!j^cKM)dc4@p4Ezyo%lRN|XyD}}>v=Xoib0gOcdXrQ^*61HNj z=NP|pd>@yfvr-=m{8$3A8TQGMTE7g=z!%yt`8`Bk-0MMwW~h^++;qyUP!J~ykh1GO z(FZ59xuFR$(WE;F@UUyE@Sp>`aVNjyj=Ty>_Vo}xf`e7`F;j-IgL5`1~-#70$9_=uBMq!2&1l zomRgpD58@)YYfvLtPW}{C5B35R;ZVvB<<#)x%srmc_S=A7F@DW8>QOEGwD6suhwCg z>Pa+YyULhmw%BA*4yjDp|2{!T98~<6Yfd(wo1mQ!KWwq0eg+6)o1>W~f~kL<-S+P@$wx*zeI|1t7z#Sxr5 zt6w+;YblPQNplq4Z#T$GLX#j6yldXAqj>4gAnnWtBICUnA&-dtnlh=t0Ho_vEKwV` z)DlJi#!@nkYV#$!)@>udAU*hF?V`2$Hf=V&6PP_|r#Iv*J$9)pF@X3`k;5})9^o4y z&)~?EjX5yX12O(BsFy-l6}nYeuKkiq`u9145&3Ssg^y{5G3Pse z9w(YVa0)N-fLaBq1`P!_#>SS(8fh_5!f{UrgZ~uEdeMJIz7DzI5!NHHqQtm~#CPij z?=N|J>nPR6_sL7!f4hD_|KH`vf8(Wpnj-(gPWH+ZvID}%?~68SwhPTC3u1_cB`otq z)U?6qo!ZLi5b>*KnYHWW=3F!p%h1;h{L&(Q&{qY6)_qxNfbP6E3yYpW!EO+IW3?@J z);4>g4gnl^8klu7uA>eGF6rIGSynacogr)KUwE_R4E5Xzi*Qir@b-jy55-JPC8c~( zo!W8y9OGZ&`xmc8;=4-U9=h{vCqfCNzYirONmGbRQlR`WWlgnY+1wCXbMz&NT~9*| z6@FrzP!LX&{no2!Ln_3|I==_4`@}V?4a;YZKTdw;vT<+K+z=uWbW(&bXEaWJ^W8Td z-3&1bY^Z*oM<=M}LVt>_j+p=2Iu7pZmbXrhQ_k)ysE9yXKygFNw$5hwDn(M>H+e1&9BM5!|81vd%r%vEm zqxY3?F@fb6O#5UunwgAHR9jp_W2zZ}NGp2%mTW@(hz7$^+a`A?mb8|_G*GNMJ) zjqegXQio=i@AINre&%ofexAr95aop5C+0MZ0m-l=MeO8m3epm7U%vZB8+I+C*iNFM z#T3l`gknX;D$-`2XT^Cg*vrv=RH+P;_dfF++cP?B_msQI4j+lt&rX2)3GaJx%W*Nn zkML%D{z5tpHH=dksQ*gzc|}gzW;lwAbxoR07VNgS*-c3d&8J|;@3t^ zVUz*J*&r7DFRuFVDCJDK8V9NN5hvpgGjwx+5n)qa;YCKe8TKtdnh{I7NU9BCN!0dq zczrBk8pE{{@vJa9ywR@mq*J=v+PG;?fwqlJVhijG!3VmIKs>9T6r7MJpC)m!Tc#>g zMtVsU>wbwFJEfwZ{vB|ZlttNe83)$iz`~#8UJ^r)lJ@HA&G#}W&ZH*;k{=TavpjWE z7hdyLZPf*X%Gm}i`Y{OGeeu^~nB8=`{r#TUrM-`;1cBvEd#d!kPqIgYySYhN-*1;L z^byj%Yi}Gx)Wnkosi337BKs}+5H5dth1JA{Ir-JKN$7zC)*}hqeoD(WfaUDPT>0`- z(6sa0AoIqASwF`>hP}^|)a_j2s^PQn*qVC{Q}htR z5-)duBFXT_V56-+UohKXlq~^6uf!6sA#ttk1o~*QEy_Y-S$gAvq47J9Vtk$5oA$Ct zYhYJ@8{hsC^98${!#Ho?4y5MCa7iGnfz}b9jE~h%EAAv~Qxu)_rAV;^cygV~5r_~?l=B`zObj7S=H=~$W zPtI_m%g$`kL_fVUk9J@>EiBH zOO&jtn~&`hIFMS5S`g8w94R4H40mdNUH4W@@XQk1sr17b{@y|JB*G9z1|CrQjd+GX z6+KyURG3;!*BQrentw{B2R&@2&`2}n(z-2&X7#r!{yg@Soy}cRD~j zj9@UBW+N|4HW4AWapy4wfUI- zZ`gSL6DUlgj*f1hSOGXG0IVH8HxK?o2|3HZ;KW{K+yPAlxtb)NV_2AwJm|E)FRs&& z=c^e7bvUsztY|+f^k7NXs$o1EUq>cR7C0$UKi6IooHWlK_#?IWDkvywnzg&ThWo^? z2O_N{5X39#?eV9l)xI(>@!vSB{DLt*oY!K1R8}_?%+0^C{d9a%N4 zoxHVT1&Lm|uDX%$QrBun5e-F`HJ^T$ zmzv)p@4ZHd_w9!%Hf9UYNvGCw2TTTbrj9pl+T9%-_-}L(tES>Or-}Z4F*{##n3~L~TuxjirGuIY#H7{%$E${?p{Q01 zi6T`n;rbK1yIB9jmQNycD~yZq&mbIsFWHo|ZAChSFPQa<(%d8mGw*V3fh|yFoxOOiWJd(qvVb!Z$b88cg->N=qO*4k~6;R==|9ihg&riu#P~s4Oap9O7f%crSr^rljeIfXDEg>wi)&v*a%7zpz<9w z*r!3q9J|390x`Zk;g$&OeN&ctp)VKRpDSV@kU2Q>jtok($Y-*x8_$2piTxun81@vt z!Vj?COa0fg2RPXMSIo26T=~0d`{oGP*eV+$!0I<(4azk&Vj3SiG=Q!6mX0p$z7I}; z9BJUFgT-K9MQQ-0@Z=^7R<{bn2Fm48endsSs`V7_@%8?Bxkqv>BDoVcj?K#dV#uUP zL1ND~?D-|VGKe3Rw_7-Idpht>H6XRLh*U7epS6byiGvJpr%d}XwfusjH9g;Z98H`x zyde%%5mhGOiL4wljCaWCk-&uE4_OOccb9c!ZaWt4B(wYl!?vyzl%7n~QepN&eFUrw zFIOl9c({``6~QD+43*_tzP{f2x41h(?b43^y6=iwyB)2os5hBE!@YUS5?N_tXd=h( z)WE286Fbd>R4M^P{!G)f;h<3Q>Fipuy+d2q-)!RyTgt;wr$(?9ox3;q+{E*ZQHhOn;lM`cjnu9 zXa48ks-v(~b*;MAI<>YZH(^NV8vjb34beE<_cwKlJoR;k6lJNSP6v}uiyRD?|0w+X@o1ONrH8a$fCxXpf? z?$DL0)7|X}Oc%h^zrMKWc-NS9I0Utu@>*j}b@tJ=ixQSJ={4@854wzW@E>VSL+Y{i z#0b=WpbCZS>kUCO_iQz)LoE>P5LIG-hv9E+oG}DtlIDF>$tJ1aw9^LuhLEHt?BCj& z(O4I8v1s#HUi5A>nIS-JK{v!7dJx)^Yg%XjNmlkWAq2*cv#tHgz`Y(bETc6CuO1VkN^L-L3j_x<4NqYb5rzrLC-7uOv z!5e`GZt%B782C5-fGnn*GhDF$%(qP<74Z}3xx+{$4cYKy2ikxI7B2N+2r07DN;|-T->nU&!=Cm#rZt%O_5c&1Z%nlWq3TKAW0w zQqemZw_ue--2uKQsx+niCUou?HjD`xhEjjQd3%rrBi82crq*~#uA4+>vR<_S{~5ce z-2EIl?~s z1=GVL{NxP1N3%=AOaC}j_Fv=ur&THz zyO!d9kHq|c73kpq`$+t+8Bw7MgeR5~`d7ChYyGCBWSteTB>8WAU(NPYt2Dk`@#+}= zI4SvLlyk#pBgVigEe`?NG*vl7V6m+<}%FwPV=~PvvA)=#ths==DRTDEYh4V5}Cf$z@#;< zyWfLY_5sP$gc3LLl2x+Ii)#b2nhNXJ{R~vk`s5U7Nyu^3yFg&D%Txwj6QezMX`V(x z=C`{76*mNb!qHHs)#GgGZ_7|vkt9izl_&PBrsu@}L`X{95-2jf99K)0=*N)VxBX2q z((vkpP2RneSIiIUEnGb?VqbMb=Zia+rF~+iqslydE34cSLJ&BJW^3knX@M;t*b=EA zNvGzv41Ld_T+WT#XjDB840vovUU^FtN_)G}7v)1lPetgpEK9YS^OWFkPoE{ovj^=@ zO9N$S=G$1ecndT_=5ehth2Lmd1II-PuT~C9`XVePw$y8J#dpZ?Tss<6wtVglm(Ok7 z3?^oi@pPio6l&!z8JY(pJvG=*pI?GIOu}e^EB6QYk$#FJQ%^AIK$I4epJ+9t?KjqA+bkj&PQ*|vLttme+`9G=L% ziadyMw_7-M)hS(3E$QGNCu|o23|%O+VN7;Qggp?PB3K-iSeBa2b}V4_wY`G1Jsfz4 z9|SdB^;|I8E8gWqHKx!vj_@SMY^hLEIbSMCuE?WKq=c2mJK z8LoG-pnY!uhqFv&L?yEuxo{dpMTsmCn)95xanqBrNPTgXP((H$9N${Ow~Is-FBg%h z53;|Y5$MUN)9W2HBe2TD`ct^LHI<(xWrw}$qSoei?}s)&w$;&!14w6B6>Yr6Y8b)S z0r71`WmAvJJ`1h&poLftLUS6Ir zC$bG9!Im_4Zjse)#K=oJM9mHW1{%l8sz$1o?ltdKlLTxWWPB>Vk22czVt|1%^wnN@*!l)}?EgtvhC>vlHm^t+ogpgHI1_$1ox9e;>0!+b(tBrmXRB`PY1vp-R**8N7 zGP|QqI$m(Rdu#=(?!(N}G9QhQ%o!aXE=aN{&wtGP8|_qh+7a_j_sU5|J^)vxq;# zjvzLn%_QPHZZIWu1&mRAj;Sa_97p_lLq_{~j!M9N^1yp3U_SxRqK&JnR%6VI#^E12 z>CdOVI^_9aPK2eZ4h&^{pQs}xsijXgFYRIxJ~N7&BB9jUR1fm!(xl)mvy|3e6-B3j zJn#ajL;bFTYJ2+Q)tDjx=3IklO@Q+FFM}6UJr6km7hj7th9n_&JR7fnqC!hTZoM~T zBeaVFp%)0cbPhejX<8pf5HyRUj2>aXnXBqDJe73~J%P(2C?-RT{c3NjE`)om! zl$uewSgWkE66$Kb34+QZZvRn`fob~Cl9=cRk@Es}KQm=?E~CE%spXaMO6YmrMl%9Q zlA3Q$3|L1QJ4?->UjT&CBd!~ru{Ih^in&JXO=|<6J!&qp zRe*OZ*cj5bHYlz!!~iEKcuE|;U4vN1rk$xq6>bUWD*u(V@8sG^7>kVuo(QL@Ki;yL zWC!FT(q{E8#on>%1iAS0HMZDJg{Z{^!De(vSIq&;1$+b)oRMwA3nc3mdTSG#3uYO_ z>+x;7p4I;uHz?ZB>dA-BKl+t-3IB!jBRgdvAbW!aJ(Q{aT>+iz?91`C-xbe)IBoND z9_Xth{6?(y3rddwY$GD65IT#f3<(0o#`di{sh2gm{dw*#-Vnc3r=4==&PU^hCv$qd zjw;>i&?L*Wq#TxG$mFIUf>eK+170KG;~+o&1;Tom9}}mKo23KwdEM6UonXgc z!6N(@k8q@HPw{O8O!lAyi{rZv|DpgfU{py+j(X_cwpKqcalcqKIr0kM^%Br3SdeD> zHSKV94Yxw;pjzDHo!Q?8^0bb%L|wC;4U^9I#pd5O&eexX+Im{ z?jKnCcsE|H?{uGMqVie_C~w7GX)kYGWAg%-?8|N_1#W-|4F)3YTDC+QSq1s!DnOML3@d`mG%o2YbYd#jww|jD$gotpa)kntakp#K;+yo-_ZF9qrNZw<%#C zuPE@#3RocLgPyiBZ+R_-FJ_$xP!RzWm|aN)S+{$LY9vvN+IW~Kf3TsEIvP+B9Mtm! zpfNNxObWQpLoaO&cJh5>%slZnHl_Q~(-Tfh!DMz(dTWld@LG1VRF`9`DYKhyNv z2pU|UZ$#_yUx_B_|MxUq^glT}O5Xt(Vm4Mr02><%C)@v;vPb@pT$*yzJ4aPc_FZ3z z3}PLoMBIM>q_9U2rl^sGhk1VUJ89=*?7|v`{!Z{6bqFMq(mYiA?%KbsI~JwuqVA9$H5vDE+VocjX+G^%bieqx->s;XWlKcuv(s%y%D5Xbc9+ zc(_2nYS1&^yL*ey664&4`IoOeDIig}y-E~_GS?m;D!xv5-xwz+G`5l6V+}CpeJDi^ z%4ed$qowm88=iYG+(`ld5Uh&>Dgs4uPHSJ^TngXP_V6fPyl~>2bhi20QB%lSd#yYn zO05?KT1z@?^-bqO8Cg`;ft>ilejsw@2%RR7;`$Vs;FmO(Yr3Fp`pHGr@P2hC%QcA|X&N2Dn zYf`MqXdHi%cGR@%y7Rg7?d3?an){s$zA{!H;Ie5exE#c~@NhQUFG8V=SQh%UxUeiV zd7#UcYqD=lk-}sEwlpu&H^T_V0{#G?lZMxL7ih_&{(g)MWBnCZxtXg znr#}>U^6!jA%e}@Gj49LWG@*&t0V>Cxc3?oO7LSG%~)Y5}f7vqUUnQ;STjdDU}P9IF9d9<$;=QaXc zL1^X7>fa^jHBu_}9}J~#-oz3Oq^JmGR#?GO7b9a(=R@fw@}Q{{@`Wy1vIQ#Bw?>@X z-_RGG@wt|%u`XUc%W{J z>iSeiz8C3H7@St3mOr_mU+&bL#Uif;+Xw-aZdNYUpdf>Rvu0i0t6k*}vwU`XNO2he z%miH|1tQ8~ZK!zmL&wa3E;l?!!XzgV#%PMVU!0xrDsNNZUWKlbiOjzH-1Uoxm8E#r`#2Sz;-o&qcqB zC-O_R{QGuynW14@)7&@yw1U}uP(1cov)twxeLus0s|7ayrtT8c#`&2~Fiu2=R;1_4bCaD=*E@cYI>7YSnt)nQc zohw5CsK%m?8Ack)qNx`W0_v$5S}nO|(V|RZKBD+btO?JXe|~^Qqur%@eO~<8-L^9d z=GA3-V14ng9L29~XJ>a5k~xT2152zLhM*@zlp2P5Eu}bywkcqR;ISbas&#T#;HZSf z2m69qTV(V@EkY(1Dk3`}j)JMo%ZVJ*5eB zYOjIisi+igK0#yW*gBGj?@I{~mUOvRFQR^pJbEbzFxTubnrw(Muk%}jI+vXmJ;{Q6 zrSobKD>T%}jV4Ub?L1+MGOD~0Ir%-`iTnWZN^~YPrcP5y3VMAzQ+&en^VzKEb$K!Q z<7Dbg&DNXuow*eD5yMr+#08nF!;%4vGrJI++5HdCFcGLfMW!KS*Oi@=7hFwDG!h2< zPunUEAF+HncQkbfFj&pbzp|MU*~60Z(|Ik%Tn{BXMN!hZOosNIseT?R;A`W?=d?5X zK(FB=9mZusYahp|K-wyb={rOpdn=@;4YI2W0EcbMKyo~-#^?h`BA9~o285%oY zfifCh5Lk$SY@|2A@a!T2V+{^!psQkx4?x0HSV`(w9{l75QxMk!)U52Lbhn{8ol?S) zCKo*7R(z!uk<6*qO=wh!Pul{(qq6g6xW;X68GI_CXp`XwO zxuSgPRAtM8K7}5E#-GM!*ydOOG_{A{)hkCII<|2=ma*71ci_-}VPARm3crFQjLYV! z9zbz82$|l01mv`$WahE2$=fAGWkd^X2kY(J7iz}WGS z@%MyBEO=A?HB9=^?nX`@nh;7;laAjs+fbo!|K^mE!tOB>$2a_O0y-*uaIn8k^6Y zSbuv;5~##*4Y~+y7Z5O*3w4qgI5V^17u*ZeupVGH^nM&$qmAk|anf*>r zWc5CV;-JY-Z@Uq1Irpb^O`L_7AGiqd*YpGUShb==os$uN3yYvb`wm6d=?T*it&pDk zo`vhw)RZX|91^^Wa_ti2zBFyWy4cJu#g)_S6~jT}CC{DJ_kKpT`$oAL%b^!2M;JgT zM3ZNbUB?}kP(*YYvXDIH8^7LUxz5oE%kMhF!rnPqv!GiY0o}NR$OD=ITDo9r%4E>E0Y^R(rS^~XjWyVI6 zMOR5rPXhTp*G*M&X#NTL`Hu*R+u*QNoiOKg4CtNPrjgH>c?Hi4MUG#I917fx**+pJfOo!zFM&*da&G_x)L(`k&TPI*t3e^{crd zX<4I$5nBQ8Ax_lmNRa~E*zS-R0sxkz`|>7q_?*e%7bxqNm3_eRG#1ae3gtV9!fQpY z+!^a38o4ZGy9!J5sylDxZTx$JmG!wg7;>&5H1)>f4dXj;B+@6tMlL=)cLl={jLMxY zbbf1ax3S4>bwB9-$;SN2?+GULu;UA-35;VY*^9Blx)Jwyb$=U!D>HhB&=jSsd^6yw zL)?a|>GxU!W}ocTC(?-%z3!IUhw^uzc`Vz_g>-tv)(XA#JK^)ZnC|l1`@CdX1@|!| z_9gQ)7uOf?cR@KDp97*>6X|;t@Y`k_N@)aH7gY27)COv^P3ya9I{4z~vUjLR9~z1Z z5=G{mVtKH*&$*t0@}-i_v|3B$AHHYale7>E+jP`ClqG%L{u;*ff_h@)al?RuL7tOO z->;I}>%WI{;vbLP3VIQ^iA$4wl6@0sDj|~112Y4OFjMs`13!$JGkp%b&E8QzJw_L5 zOnw9joc0^;O%OpF$Qp)W1HI!$4BaXX84`%@#^dk^hFp^pQ@rx4g(8Xjy#!X%+X5Jd@fs3amGT`}mhq#L97R>OwT5-m|h#yT_-v@(k$q7P*9X~T*3)LTdzP!*B} z+SldbVWrrwQo9wX*%FyK+sRXTa@O?WM^FGWOE?S`R(0P{<6p#f?0NJvnBia?k^fX2 zNQs7K-?EijgHJY}&zsr;qJ<*PCZUd*x|dD=IQPUK_nn)@X4KWtqoJNHkT?ZWL_hF? zS8lp2(q>;RXR|F;1O}EE#}gCrY~#n^O`_I&?&z5~7N;zL0)3Tup`%)oHMK-^r$NT% zbFg|o?b9w(q@)6w5V%si<$!U<#}s#x@0aX-hP>zwS#9*75VXA4K*%gUc>+yzupTDBOKH8WR4V0pM(HrfbQ&eJ79>HdCvE=F z|J>s;;iDLB^3(9}?biKbxf1$lI!*Z%*0&8UUq}wMyPs_hclyQQi4;NUY+x2qy|0J; zhn8;5)4ED1oHwg+VZF|80<4MrL97tGGXc5Sw$wAI#|2*cvQ=jB5+{AjMiDHmhUC*a zlmiZ`LAuAn_}hftXh;`Kq0zblDk8?O-`tnilIh|;3lZp@F_osJUV9`*R29M?7H{Fy z`nfVEIDIWXmU&YW;NjU8)EJpXhxe5t+scf|VXM!^bBlwNh)~7|3?fWwo_~ZFk(22% zTMesYw+LNx3J-_|DM~`v93yXe=jPD{q;li;5PD?Dyk+b? zo21|XpT@)$BM$%F=P9J19Vi&1#{jM3!^Y&fr&_`toi`XB1!n>sbL%U9I5<7!@?t)~ z;&H%z>bAaQ4f$wIzkjH70;<8tpUoxzKrPhn#IQfS%9l5=Iu))^XC<58D!-O z{B+o5R^Z21H0T9JQ5gNJnqh#qH^na|z92=hONIM~@_iuOi|F>jBh-?aA20}Qx~EpDGElELNn~|7WRXRFnw+Wdo`|# zBpU=Cz3z%cUJ0mx_1($X<40XEIYz(`noWeO+x#yb_pwj6)R(__%@_Cf>txOQ74wSJ z0#F3(zWWaR-jMEY$7C*3HJrohc79>MCUu26mfYN)f4M~4gD`}EX4e}A!U}QV8!S47 z6y-U-%+h`1n`*pQuKE%Av0@)+wBZr9mH}@vH@i{v(m-6QK7Ncf17x_D=)32`FOjjo zg|^VPf5c6-!FxN{25dvVh#fog=NNpXz zfB$o+0jbRkHH{!TKhE709f+jI^$3#v1Nmf80w`@7-5$1Iv_`)W^px8P-({xwb;D0y z7LKDAHgX<84?l!I*Dvi2#D@oAE^J|g$3!)x1Ua;_;<@#l1fD}lqU2_tS^6Ht$1Wl} zBESo7o^)9-Tjuz$8YQSGhfs{BQV6zW7dA?0b(Dbt=UnQs&4zHfe_sj{RJ4uS-vQpC zX;Bbsuju4%!o8?&m4UZU@~ZZjeFF6ex2ss5_60_JS_|iNc+R0GIjH1@Z z=rLT9%B|WWgOrR7IiIwr2=T;Ne?30M!@{%Qf8o`!>=s<2CBpCK_TWc(DX51>e^xh8 z&@$^b6CgOd7KXQV&Y4%}_#uN*mbanXq(2=Nj`L7H7*k(6F8s6{FOw@(DzU`4-*77{ zF+dxpv}%mFpYK?>N_2*#Y?oB*qEKB}VoQ@bzm>ptmVS_EC(#}Lxxx730trt0G)#$b zE=wVvtqOct1%*9}U{q<)2?{+0TzZzP0jgf9*)arV)*e!f`|jgT{7_9iS@e)recI#z zbzolURQ+TOzE!ymqvBY7+5NnAbWxvMLsLTwEbFqW=CPyCsmJ}P1^V30|D5E|p3BC5 z)3|qgw@ra7aXb-wsa|l^in~1_fm{7bS9jhVRkYVO#U{qMp z)Wce+|DJ}4<2gp8r0_xfZpMo#{Hl2MfjLcZdRB9(B(A(f;+4s*FxV{1F|4d`*sRNd zp4#@sEY|?^FIJ;tmH{@keZ$P(sLh5IdOk@k^0uB^BWr@pk6mHy$qf&~rI>P*a;h0C{%oA*i!VjWn&D~O#MxN&f@1Po# zKN+ zrGrkSjcr?^R#nGl<#Q722^wbYcgW@{+6CBS<1@%dPA8HC!~a`jTz<`g_l5N1M@9wn9GOAZ>nqNgq!yOCbZ@1z`U_N`Z>}+1HIZxk*5RDc&rd5{3qjRh8QmT$VyS;jK z;AF+r6XnnCp=wQYoG|rT2@8&IvKq*IB_WvS%nt%e{MCFm`&W*#LXc|HrD?nVBo=(8*=Aq?u$sDA_sC_RPDUiQ+wnIJET8vx$&fxkW~kP9qXKt zozR)@xGC!P)CTkjeWvXW5&@2?)qt)jiYWWBU?AUtzAN}{JE1I)dfz~7$;}~BmQF`k zpn11qmObXwRB8&rnEG*#4Xax3XBkKlw(;tb?Np^i+H8m(Wyz9k{~ogba@laiEk;2! zV*QV^6g6(QG%vX5Um#^sT&_e`B1pBW5yVth~xUs#0}nv?~C#l?W+9Lsb_5)!71rirGvY zTIJ$OPOY516Y|_014sNv+Z8cc5t_V=i>lWV=vNu#!58y9Zl&GsMEW#pPYPYGHQ|;vFvd*9eM==$_=vc7xnyz0~ zY}r??$<`wAO?JQk@?RGvkWVJlq2dk9vB(yV^vm{=NVI8dhsX<)O(#nr9YD?I?(VmQ z^r7VfUBn<~p3()8yOBjm$#KWx!5hRW)5Jl7wY@ky9lNM^jaT##8QGVsYeaVywmpv>X|Xj7gWE1Ezai&wVLt3p)k4w~yrskT-!PR!kiyQlaxl(( zXhF%Q9x}1TMt3~u@|#wWm-Vq?ZerK={8@~&@9r5JW}r#45#rWii};t`{5#&3$W)|@ zbAf2yDNe0q}NEUvq_Quq3cTjcw z@H_;$hu&xllCI9CFDLuScEMg|x{S7GdV8<&Mq=ezDnRZAyX-8gv97YTm0bg=d)(>N z+B2FcqvI9>jGtnK%eO%y zoBPkJTk%y`8TLf4)IXPBn`U|9>O~WL2C~C$z~9|0m*YH<-vg2CD^SX#&)B4ngOSG$ zV^wmy_iQk>dfN@Pv(ckfy&#ak@MLC7&Q6Ro#!ezM*VEh`+b3Jt%m(^T&p&WJ2Oqvj zs-4nq0TW6cv~(YI$n0UkfwN}kg3_fp?(ijSV#tR9L0}l2qjc7W?i*q01=St0eZ=4h zyGQbEw`9OEH>NMuIe)hVwYHsGERWOD;JxEiO7cQv%pFCeR+IyhwQ|y@&^24k+|8fD zLiOWFNJ2&vu2&`Jv96_z-Cd5RLgmeY3*4rDOQo?Jm`;I_(+ejsPM03!ly!*Cu}Cco zrQSrEDHNyzT(D5s1rZq!8#?f6@v6dB7a-aWs(Qk>N?UGAo{gytlh$%_IhyL7h?DLXDGx zgxGEBQoCAWo-$LRvM=F5MTle`M})t3vVv;2j0HZY&G z22^iGhV@uaJh(XyyY%} zd4iH_UfdV#T=3n}(Lj^|n;O4|$;xhu*8T3hR1mc_A}fK}jfZ7LX~*n5+`8N2q#rI$ z@<_2VANlYF$vIH$ zl<)+*tIWW78IIINA7Rr7i{<;#^yzxoLNkXL)eSs=%|P>$YQIh+ea_3k z_s7r4%j7%&*NHSl?R4k%1>Z=M9o#zxY!n8sL5>BO-ZP;T3Gut>iLS@U%IBrX6BA3k z)&@q}V8a{X<5B}K5s(c(LQ=%v1ocr`t$EqqY0EqVjr65usa=0bkf|O#ky{j3)WBR(((L^wmyHRzoWuL2~WTC=`yZ zn%VX`L=|Ok0v7?s>IHg?yArBcync5rG#^+u)>a%qjES%dRZoIyA8gQ;StH z1Ao7{<&}6U=5}4v<)1T7t!J_CL%U}CKNs-0xWoTTeqj{5{?Be$L0_tk>M9o8 zo371}S#30rKZFM{`H_(L`EM9DGp+Mifk&IP|C2Zu_)Ghr4Qtpmkm1osCf@%Z$%t+7 zYH$Cr)Ro@3-QDeQJ8m+x6%;?YYT;k6Z0E-?kr>x33`H%*ueBD7Zx~3&HtWn0?2Wt} zTG}*|v?{$ajzt}xPzV%lL1t-URi8*Zn)YljXNGDb>;!905Td|mpa@mHjIH%VIiGx- zd@MqhpYFu4_?y5N4xiHn3vX&|e6r~Xt> zZG`aGq|yTNjv;9E+Txuoa@A(9V7g?1_T5FzRI;!=NP1Kqou1z5?%X~Wwb{trRfd>i z8&y^H)8YnKyA_Fyx>}RNmQIczT?w2J4SNvI{5J&}Wto|8FR(W;Qw#b1G<1%#tmYzQ zQ2mZA-PAdi%RQOhkHy9Ea#TPSw?WxwL@H@cbkZwIq0B!@ns}niALidmn&W?!Vd4Gj zO7FiuV4*6Mr^2xlFSvM;Cp_#r8UaqIzHJQg_z^rEJw&OMm_8NGAY2)rKvki|o1bH~ z$2IbfVeY2L(^*rMRU1lM5Y_sgrDS`Z??nR2lX;zyR=c%UyGb*%TC-Dil?SihkjrQy~TMv6;BMs7P8il`H7DmpVm@rJ;b)hW)BL)GjS154b*xq-NXq2cwE z^;VP7ua2pxvCmxrnqUYQMH%a%nHmwmI33nJM(>4LznvY*k&C0{8f*%?zggpDgkuz&JBx{9mfb@wegEl2v!=}Sq2Gaty0<)UrOT0{MZtZ~j5y&w zXlYa_jY)I_+VA-^#mEox#+G>UgvM!Ac8zI<%JRXM_73Q!#i3O|)lOP*qBeJG#BST0 zqohi)O!|$|2SeJQo(w6w7%*92S})XfnhrH_Z8qe!G5>CglP=nI7JAOW?(Z29;pXJ9 zR9`KzQ=WEhy*)WH>$;7Cdz|>*i>=##0bB)oU0OR>>N<21e4rMCHDemNi2LD>Nc$;& zQRFthpWniC1J6@Zh~iJCoLOxN`oCKD5Q4r%ynwgUKPlIEd#?QViIqovY|czyK8>6B zSP%{2-<;%;1`#0mG^B(8KbtXF;Nf>K#Di72UWE4gQ%(_26Koiad)q$xRL~?pN71ZZ zujaaCx~jXjygw;rI!WB=xrOJO6HJ!!w}7eiivtCg5K|F6$EXa)=xUC za^JXSX98W`7g-tm@uo|BKj39Dl;sg5ta;4qjo^pCh~{-HdLl6qI9Ix6f$+qiZ$}s= zNguKrU;u+T@ko(Vr1>)Q%h$?UKXCY>3se%&;h2osl2D zE4A9bd7_|^njDd)6cI*FupHpE3){4NQ*$k*cOWZ_?CZ>Z4_fl@n(mMnYK62Q1d@+I zr&O))G4hMihgBqRIAJkLdk(p(D~X{-oBUA+If@B}j& zsHbeJ3RzTq96lB7d($h$xTeZ^gP0c{t!Y0c)aQE;$FY2!mACg!GDEMKXFOPI^)nHZ z`aSPJpvV0|bbrzhWWkuPURlDeN%VT8tndV8?d)eN*i4I@u zVKl^6{?}A?P)Fsy?3oi#clf}L18t;TjNI2>eI&(ezDK7RyqFxcv%>?oxUlonv(px) z$vnPzRH`y5A(x!yOIfL0bmgeMQB$H5wenx~!ujQK*nUBW;@Em&6Xv2%s(~H5WcU2R z;%Nw<$tI)a`Ve!>x+qegJnQsN2N7HaKzrFqM>`6R*gvh%O*-%THt zrB$Nk;lE;z{s{r^PPm5qz(&lM{sO*g+W{sK+m3M_z=4=&CC>T`{X}1Vg2PEfSj2x_ zmT*(x;ov%3F?qoEeeM>dUn$a*?SIGyO8m806J1W1o+4HRhc2`9$s6hM#qAm zChQ87b~GEw{ADfs+5}FJ8+|bIlIv(jT$Ap#hSHoXdd9#w<#cA<1Rkq^*EEkknUd4& zoIWIY)sAswy6fSERVm&!SO~#iN$OgOX*{9@_BWFyJTvC%S++ilSfCrO(?u=Dc?CXZ zzCG&0yVR{Z`|ZF0eEApWEo#s9osV>F{uK{QA@BES#&;#KsScf>y zvs?vIbI>VrT<*!;XmQS=bhq%46-aambZ(8KU-wOO2=en~D}MCToB_u;Yz{)1ySrPZ z@=$}EvjTdzTWU7c0ZI6L8=yP+YRD_eMMos}b5vY^S*~VZysrkq<`cK3>>v%uy7jgq z0ilW9KjVDHLv0b<1K_`1IkbTOINs0=m-22c%M~l=^S}%hbli-3?BnNq?b`hx^HX2J zIe6ECljRL0uBWb`%{EA=%!i^4sMcj+U_TaTZRb+~GOk z^ZW!nky0n*Wb*r+Q|9H@ml@Z5gU&W`(z4-j!OzC1wOke`TRAYGZVl$PmQ16{3196( zO*?`--I}Qf(2HIwb2&1FB^!faPA2=sLg(@6P4mN)>Dc3i(B0;@O-y2;lM4akD>@^v z=u>*|!s&9zem70g7zfw9FXl1bpJW(C#5w#uy5!V?Q(U35A~$dR%LDVnq@}kQm13{} zd53q3N(s$Eu{R}k2esbftfjfOITCL;jWa$}(mmm}d(&7JZ6d3%IABCapFFYjdEjdK z&4Edqf$G^MNAtL=uCDRs&Fu@FXRgX{*0<(@c3|PNHa>L%zvxWS={L8%qw`STm+=Rd zA}FLspESSIpE_^41~#5yI2bJ=9`oc;GIL!JuW&7YetZ?0H}$$%8rW@*J37L-~Rsx!)8($nI4 zZhcZ2^=Y+p4YPl%j!nFJA|*M^gc(0o$i3nlphe+~-_m}jVkRN{spFs(o0ajW@f3K{ zDV!#BwL322CET$}Y}^0ixYj2w>&Xh12|R8&yEw|wLDvF!lZ#dOTHM9pK6@Nm-@9Lnng4ZHBgBSrr7KI8YCC9DX5Kg|`HsiwJHg2(7#nS;A{b3tVO?Z% za{m5b3rFV6EpX;=;n#wltDv1LE*|g5pQ+OY&*6qCJZc5oDS6Z6JD#6F)bWxZSF@q% z+1WV;m!lRB!n^PC>RgQCI#D1br_o^#iPk>;K2hB~0^<~)?p}LG%kigm@moD#q3PE+ zA^Qca)(xnqw6x>XFhV6ku9r$E>bWNrVH9fum0?4s?Rn2LG{Vm_+QJHse6xa%nzQ?k zKug4PW~#Gtb;#5+9!QBgyB@q=sk9=$S{4T>wjFICStOM?__fr+Kei1 z3j~xPqW;W@YkiUM;HngG!;>@AITg}vAE`M2Pj9Irl4w1fo4w<|Bu!%rh%a(Ai^Zhi zs92>v5;@Y(Zi#RI*ua*h`d_7;byQSa*v9E{2x$<-_=5Z<7{%)}4XExANcz@rK69T0x3%H<@frW>RA8^swA+^a(FxK| zFl3LD*ImHN=XDUkrRhp6RY5$rQ{bRgSO*(vEHYV)3Mo6Jy3puiLmU&g82p{qr0F?ohmbz)f2r{X2|T2 z$4fdQ=>0BeKbiVM!e-lIIs8wVTuC_m7}y4A_%ikI;Wm5$9j(^Y z(cD%U%k)X>_>9~t8;pGzL6L-fmQO@K; zo&vQzMlgY95;1BSkngY)e{`n0!NfVgf}2mB3t}D9@*N;FQ{HZ3Pb%BK6;5#-O|WI( zb6h@qTLU~AbVW#_6?c!?Dj65Now7*pU{h!1+eCV^KCuPAGs28~3k@ueL5+u|Z-7}t z9|lskE`4B7W8wMs@xJa{#bsCGDFoRSNSnmNYB&U7 zVGKWe%+kFB6kb)e;TyHfqtU6~fRg)f|>=5(N36)0+C z`hv65J<$B}WUc!wFAb^QtY31yNleq4dzmG`1wHTj=c*=hay9iD071Hc?oYoUk|M*_ zU1GihAMBsM@5rUJ(qS?9ZYJ6@{bNqJ`2Mr+5#hKf?doa?F|+^IR!8lq9)wS3tF_9n zW_?hm)G(M+MYb?V9YoX^_mu5h-LP^TL^!Q9Z7|@sO(rg_4+@=PdI)WL(B7`!K^ND- z-uIuVDCVEdH_C@c71YGYT^_Scf_dhB8Z2Xy6vGtBSlYud9vggOqv^L~F{BraSE_t} zIkP+Hp2&nH^-MNEs}^`oMLy11`PQW$T|K(`Bu*(f@)mv1-qY(_YG&J2M2<7k;;RK~ zL{Fqj9yCz8(S{}@c)S!65aF<=&eLI{hAMErCx&>i7OeDN>okvegO87OaG{Jmi<|}D zaT@b|0X{d@OIJ7zvT>r+eTzgLq~|Dpu)Z&db-P4z*`M$UL51lf>FLlq6rfG)%doyp z)3kk_YIM!03eQ8Vu_2fg{+osaEJPtJ-s36R+5_AEG12`NG)IQ#TF9c@$99%0iye+ zUzZ57=m2)$D(5Nx!n)=5Au&O0BBgwxIBaeI(mro$#&UGCr<;C{UjJVAbVi%|+WP(a zL$U@TYCxJ=1{Z~}rnW;7UVb7+ZnzgmrogDxhjLGo>c~MiJAWs&&;AGg@%U?Y^0JhL ze(x6Z74JG6FlOFK(T}SXQfhr}RIFl@QXKnIcXYF)5|V~e-}suHILKT-k|<*~Ij|VF zC;t@=uj=hot~*!C68G8hTA%8SzOfETOXQ|3FSaIEjvBJp(A)7SWUi5!Eu#yWgY+;n zlm<$+UDou*V+246_o#V4kMdto8hF%%Lki#zPh}KYXmMf?hrN0;>Mv%`@{0Qn`Ujp) z=lZe+13>^Q!9zT);H<(#bIeRWz%#*}sgUX9P|9($kexOyKIOc`dLux}c$7It4u|Rl z6SSkY*V~g_B-hMPo_ak>>z@AVQ(_N)VY2kB3IZ0G(iDUYw+2d7W^~(Jq}KY=JnWS( z#rzEa&0uNhJ>QE8iiyz;n2H|SV#Og+wEZv=f2%1ELX!SX-(d3tEj$5$1}70Mp<&eI zCkfbByL7af=qQE@5vDVxx1}FSGt_a1DoE3SDI+G)mBAna)KBG4p8Epxl9QZ4BfdAN zFnF|Y(umr;gRgG6NLQ$?ZWgllEeeq~z^ZS7L?<(~O&$5|y)Al^iMKy}&W+eMm1W z7EMU)u^ke(A1#XCV>CZ71}P}0x)4wtHO8#JRG3MA-6g=`ZM!FcICCZ{IEw8Dm2&LQ z1|r)BUG^0GzI6f946RrBlfB1Vs)~8toZf~7)+G;pv&XiUO(%5bm)pl=p>nV^o*;&T z;}@oZSibzto$arQgfkp|z4Z($P>dTXE{4O=vY0!)kDO* zGF8a4wq#VaFpLfK!iELy@?-SeRrdz%F*}hjKcA*y@mj~VD3!it9lhRhX}5YOaR9$} z3mS%$2Be7{l(+MVx3 z(4?h;P!jnRmX9J9sYN#7i=iyj_5q7n#X(!cdqI2lnr8T$IfOW<_v`eB!d9xY1P=2q&WtOXY=D9QYteP)De?S4}FK6#6Ma z=E*V+#s8>L;8aVroK^6iKo=MH{4yEZ_>N-N z`(|;aOATba1^asjxlILk<4}f~`39dBFlxj>Dw(hMYKPO3EEt1@S`1lxFNM+J@uB7T zZ8WKjz7HF1-5&2=l=fqF-*@>n5J}jIxdDwpT?oKM3s8Nr`x8JnN-kCE?~aM1H!hAE z%%w(3kHfGwMnMmNj(SU(w42OrC-euI>Dsjk&jz3ts}WHqmMpzQ3vZrsXrZ|}+MHA7 z068obeXZTsO*6RS@o3x80E4ok``rV^Y3hr&C1;|ZZ0|*EKO`$lECUYG2gVFtUTw)R z4Um<0ZzlON`zTdvVdL#KFoMFQX*a5wM0Czp%wTtfK4Sjs)P**RW&?lP$(<}q%r68Z zS53Y!d@&~ne9O)A^tNrXHhXBkj~$8j%pT1%%mypa9AW5E&s9)rjF4@O3ytH{0z6riz|@< zB~UPh*wRFg2^7EbQrHf0y?E~dHlkOxof_a?M{LqQ^C!i2dawHTPYUE=X@2(3<=OOxs8qn_(y>pU>u^}3y&df{JarR0@VJn0f+U%UiF=$Wyq zQvnVHESil@d|8&R<%}uidGh7@u^(%?$#|&J$pvFC-n8&A>utA=n3#)yMkz+qnG3wd zP7xCnF|$9Dif@N~L)Vde3hW8W!UY0BgT2v(wzp;tlLmyk2%N|0jfG$%<;A&IVrOI< z!L)o>j>;dFaqA3pL}b-Je(bB@VJ4%!JeX@3x!i{yIeIso^=n?fDX`3bU=eG7sTc%g%ye8$v8P@yKE^XD=NYxTb zbf!Mk=h|otpqjFaA-vs5YOF-*GwWPc7VbaOW&stlANnCN8iftFMMrUdYNJ_Bnn5Vt zxfz@Ah|+4&P;reZxp;MmEI7C|FOv8NKUm8njF7Wb6Gi7DeODLl&G~}G4be&*Hi0Qw z5}77vL0P+7-B%UL@3n1&JPxW^d@vVwp?u#gVcJqY9#@-3X{ok#UfW3<1fb%FT`|)V~ggq z(3AUoUS-;7)^hCjdT0Kf{i}h)mBg4qhtHHBti=~h^n^OTH5U*XMgDLIR@sre`AaB$ zg)IGBET_4??m@cx&c~bA80O7B8CHR7(LX7%HThkeC*@vi{-pL%e)yXp!B2InafbDF zjPXf1mko3h59{lT6EEbxKO1Z5GF71)WwowO6kY|6tjSVSWdQ}NsK2x{>i|MKZK8%Q zfu&_0D;CO-Jg0#YmyfctyJ!mRJp)e#@O0mYdp|8x;G1%OZQ3Q847YWTyy|%^cpA;m zze0(5p{tMu^lDkpe?HynyO?a1$_LJl2L&mpeKu%8YvgRNr=%2z${%WThHG=vrWY@4 zsA`OP#O&)TetZ>s%h!=+CE15lOOls&nvC~$Qz0Ph7tHiP;O$i|eDwpT{cp>+)0-|; zY$|bB+Gbel>5aRN3>c0x)4U=|X+z+{ zn*_p*EQoquRL+=+p;=lm`d71&1NqBz&_ph)MXu(Nv6&XE7(RsS)^MGj5Q?Fwude-(sq zjJ>aOq!7!EN>@(fK7EE#;i_BGvli`5U;r!YA{JRodLBc6-`n8K+Fjgwb%sX;j=qHQ z7&Tr!)!{HXoO<2BQrV9Sw?JRaLXV8HrsNevvnf>Y-6|{T!pYLl7jp$-nEE z#X!4G4L#K0qG_4Z;Cj6=;b|Be$hi4JvMH!-voxqx^@8cXp`B??eFBz2lLD8RRaRGh zn7kUfy!YV~p(R|p7iC1Rdgt$_24i0cd-S8HpG|`@my70g^y`gu%#Tf_L21-k?sRRZHK&at(*ED0P8iw{7?R$9~OF$Ko;Iu5)ur5<->x!m93Eb zFYpIx60s=Wxxw=`$aS-O&dCO_9?b1yKiPCQmSQb>T)963`*U+Ydj5kI(B(B?HNP8r z*bfSBpSu)w(Z3j7HQoRjUG(+d=IaE~tv}y14zHHs|0UcN52fT8V_<@2ep_ee{QgZG zmgp8iv4V{k;~8@I%M3<#B;2R>Ef(Gg_cQM7%}0s*^)SK6!Ym+~P^58*wnwV1BW@eG z4sZLqsUvBbFsr#8u7S1r4teQ;t)Y@jnn_m5jS$CsW1um!p&PqAcc8!zyiXHVta9QC zY~wCwCF0U%xiQPD_INKtTb;A|Zf29(mu9NI;E zc-e>*1%(LSXB`g}kd`#}O;veb<(sk~RWL|f3ljxCnEZDdNSTDV6#Td({6l&y4IjKF z^}lIUq*ZUqgTPumD)RrCN{M^jhY>E~1pn|KOZ5((%F)G|*ZQ|r4zIbrEiV%42hJV8 z3xS)=!X1+=olbdGJ=yZil?oXLct8FM{(6ikLL3E%=q#O6(H$p~gQu6T8N!plf!96| z&Q3=`L~>U0zZh;z(pGR2^S^{#PrPxTRHD1RQOON&f)Siaf`GLj#UOk&(|@0?zm;Sx ztsGt8=29-MZs5CSf1l1jNFtNt5rFNZxJPvkNu~2}7*9468TWm>nN9TP&^!;J{-h)_ z7WsHH9|F%I`Pb!>KAS3jQWKfGivTVkMJLO-HUGM_a4UQ_%RgL6WZvrW+Z4ujZn;y@ zz9$=oO!7qVTaQAA^BhX&ZxS*|5dj803M=k&2%QrXda`-Q#IoZL6E(g+tN!6CA!CP* zCpWtCujIea)ENl0liwVfj)Nc<9mV%+e@=d`haoZ*`B7+PNjEbXBkv=B+Pi^~L#EO$D$ZqTiD8f<5$eyb54-(=3 zh)6i8i|jp(@OnRrY5B8t|LFXFQVQ895n*P16cEKTrT*~yLH6Z4e*bZ5otpRDri&+A zfNbK1D5@O=sm`fN=WzWyse!za5n%^+6dHPGX#8DyIK>?9qyX}2XvBWVqbP%%D)7$= z=#$WulZlZR<{m#gU7lwqK4WS1Ne$#_P{b17qe$~UOXCl>5b|6WVh;5vVnR<%d+Lnp z$uEmML38}U4vaW8>shm6CzB(Wei3s#NAWE3)a2)z@i{4jTn;;aQS)O@l{rUM`J@K& l00vQ5JBs~;vo!vr%%-k{2_Fq1Mn4QF81S)AQ99zk{{c4yR+0b! literal 62076 zcmb5VV{~QRw)Y#`wrv{~+qP{x72B%VwzFc}c2cp;N~)5ZbDrJayPv(!dGEd-##*zr z)#n-$y^sH|_dchh3@8{H5D*j;5D<{i*8l5IFJ|DjL!e)upfGNX(kojugZ3I`oH1PvW`wFW_ske0j@lB9bX zO;2)`y+|!@X(fZ1<2n!Qx*)_^Ai@Cv-dF&(vnudG?0CsddG_&Wtae(n|K59ew)6St z#dj7_(Cfwzh$H$5M!$UDd8=4>IQsD3xV=lXUq($;(h*$0^yd+b{qq63f0r_de#!o_ zXDngc>zy`uor)4A^2M#U*DC~i+dc<)Tb1Tv&~Ev@oM)5iJ4Sn#8iRw16XXuV50BS7 zdBL5Mefch(&^{luE{*5qtCZk$oFr3RH=H!c3wGR=HJ(yKc_re_X9pD` zJ;uxPzUfVpgU>DSq?J;I@a+10l0ONXPcDkiYcihREt5~T5Gb}sT0+6Q;AWHl`S5dV>lv%-p9l#xNNy7ZCr%cyqHY%TZ8Q4 zbp&#ov1*$#grNG#1vgfFOLJCaNG@K|2!W&HSh@3@Y%T?3YI75bJp!VP*$*!< z;(ffNS_;@RJ`=c7yX04!u3JP*<8jeqLHVJu#WV&v6wA!OYJS4h<_}^QI&97-;=ojW zQ-1t)7wnxG*5I%U4)9$wlv5Fr;cIizft@&N+32O%B{R1POm$oap@&f| zh+5J{>U6ftv|vAeKGc|zC=kO(+l7_cLpV}-D#oUltScw})N>~JOZLU_0{Ka2e1evz z{^a*ZrLr+JUj;)K&u2CoCAXLC2=fVScI(m_p~0FmF>>&3DHziouln?;sxW`NB}cSX z8?IsJB)Z=aYRz!X=yJn$kyOWK%rCYf-YarNqKzmWu$ZvkP12b4qH zhS9Q>j<}(*frr?z<%9hl*i^#@*O2q(Z^CN)c2c z>1B~D;@YpG?G!Yk+*yn4vM4sO-_!&m6+`k|3zd;8DJnxsBYtI;W3We+FN@|tQ5EW= z!VU>jtim0Mw#iaT8t_<+qKIEB-WwE04lBd%Letbml9N!?SLrEG$nmn7&W(W`VB@5S zaY=sEw2}i@F_1P4OtEw?xj4@D6>_e=m=797#hg}f*l^`AB|Y0# z9=)o|%TZFCY$SzgSjS|8AI-%J4x}J)!IMxY3_KYze`_I=c1nmrk@E8c9?MVRu)7+Ue79|)rBX7tVB7U|w4*h(;Gi3D9le49B38`wuv zp7{4X^p+K4*$@gU(Tq3K1a#3SmYhvI42)GzG4f|u zwQFT1n_=n|jpi=70-yE9LA+d*T8u z`=VmmXJ_f6WmZveZPct$Cgu^~gFiyL>Lnpj*6ee>*0pz=t$IJ}+rE zsf@>jlcG%Wx;Cp5x)YSVvB1$yyY1l&o zvwX=D7k)Dn;ciX?Z)Pn8$flC8#m`nB&(8?RSdBvr?>T9?E$U3uIX7T?$v4dWCa46 z+&`ot8ZTEgp7G+c52oHJ8nw5}a^dwb_l%MOh(ebVj9>_koQP^$2B~eUfSbw9RY$_< z&DDWf2LW;b0ZDOaZ&2^i^g+5uTd;GwO(-bbo|P^;CNL-%?9mRmxEw~5&z=X^Rvbo^WJW=n_%*7974RY}JhFv46> zd}`2|qkd;89l}R;i~9T)V-Q%K)O=yfVKNM4Gbacc7AOd>#^&W&)Xx!Uy5!BHnp9kh z`a(7MO6+Ren#>R^D0K)1sE{Bv>}s6Rb9MT14u!(NpZOe-?4V=>qZ>}uS)!y~;jEUK z&!U7Fj&{WdgU#L0%bM}SYXRtM5z!6M+kgaMKt%3FkjWYh=#QUpt$XX1!*XkpSq-pl zhMe{muh#knk{9_V3%qdDcWDv}v)m4t9 zQhv{;} zc{}#V^N3H>9mFM8`i`0p+fN@GqX+kl|M94$BK3J-X`Hyj8r!#x6Vt(PXjn?N)qedP z=o1T^#?1^a{;bZ&x`U{f?}TMo8ToN zkHj5v|}r}wDEi7I@)Gj+S1aE-GdnLN+$hw!=DzglMaj#{qjXi_dwpr|HL(gcCXwGLEmi|{4&4#OZ4ChceA zKVd4K!D>_N=_X;{poT~4Q+!Le+ZV>=H7v1*l%w`|`Dx8{)McN@NDlQyln&N3@bFpV z_1w~O4EH3fF@IzJ9kDk@7@QctFq8FbkbaH7K$iX=bV~o#gfh?2JD6lZf(XP>~DACF)fGFt)X%-h1yY~MJU{nA5 ze2zxWMs{YdX3q5XU*9hOH0!_S24DOBA5usB+Ws$6{|AMe*joJ?RxfV}*7AKN9V*~J zK+OMcE@bTD>TG1*yc?*qGqjBN8mgg@h1cJLDv)0!WRPIkC` zZrWXrceVw;fB%3`6kq=a!pq|hFIsQ%ZSlo~)D z|64!aCnw-?>}AG|*iOl44KVf8@|joXi&|)1rB;EQWgm+iHfVbgllP$f!$Wf42%NO5b(j9Bw6L z;0dpUUK$5GX4QbMlTmLM_jJt!ur`_0~$b#BB7FL*%XFf<b__1o)Ao3rlobbN8-(T!1d-bR8D3S0@d zLI!*GMb5s~Q<&sjd}lBb8Nr0>PqE6_!3!2d(KAWFxa{hm`@u|a(%#i(#f8{BP2wbs zt+N_slWF4IF_O|{w`c~)Xvh&R{Au~CFmW#0+}MBd2~X}t9lz6*E7uAD`@EBDe$>7W zzPUkJx<`f$0VA$=>R57^(K^h86>09?>_@M(R4q($!Ck6GG@pnu-x*exAx1jOv|>KH zjNfG5pwm`E-=ydcb+3BJwuU;V&OS=6yM^4Jq{%AVqnTTLwV`AorIDD}T&jWr8pB&j28fVtk_y*JRP^t@l*($UZ z6(B^-PBNZ+z!p?+e8@$&jCv^EWLb$WO=}Scr$6SM*&~B95El~;W_0(Bvoha|uQ1T< zO$%_oLAwf1bW*rKWmlD+@CP&$ObiDy=nh1b2ejz%LO9937N{LDe7gle4i!{}I$;&Y zkexJ9Ybr+lrCmKWg&}p=`2&Gf10orS?4$VrzWidT=*6{KzOGMo?KI0>GL0{iFWc;C z+LPq%VH5g}6V@-tg2m{C!-$fapJ9y}c$U}aUmS{9#0CM*8pC|sfer!)nG7Ji>mfRh z+~6CxNb>6eWKMHBz-w2{mLLwdA7dA-qfTu^A2yG1+9s5k zcF=le_UPYG&q!t5Zd_*E_P3Cf5T6821bO`daa`;DODm8Ih8k89=RN;-asHIigj`n=ux>*f!OC5#;X5i;Q z+V!GUy0|&Y_*8k_QRUA8$lHP;GJ3UUD08P|ALknng|YY13)}!!HW@0z$q+kCH%xet zlWf@BXQ=b=4}QO5eNnN~CzWBbHGUivG=`&eWK}beuV*;?zt=P#pM*eTuy3 zP}c#}AXJ0OIaqXji78l;YrP4sQe#^pOqwZUiiN6^0RCd#D271XCbEKpk`HI0IsN^s zES7YtU#7=8gTn#lkrc~6)R9u&SX6*Jk4GFX7){E)WE?pT8a-%6P+zS6o&A#ml{$WX zABFz#i7`DDlo{34)oo?bOa4Z_lNH>n;f0nbt$JfAl~;4QY@}NH!X|A$KgMmEsd^&Y zt;pi=>AID7ROQfr;MsMtClr5b0)xo|fwhc=qk33wQ|}$@?{}qXcmECh>#kUQ-If0$ zseb{Wf4VFGLNc*Rax#P8ko*=`MwaR-DQ8L8V8r=2N{Gaips2_^cS|oC$+yScRo*uF zUO|5=?Q?{p$inDpx*t#Xyo6=s?bbN}y>NNVxj9NZCdtwRI70jxvm3!5R7yiWjREEd zDUjrsZhS|P&|Ng5r+f^kA6BNN#|Se}_GF>P6sy^e8kBrgMv3#vk%m}9PCwUWJg-AD zFnZ=}lbi*mN-AOm zCs)r=*YQAA!`e#1N>aHF=bb*z*hXH#Wl$z^o}x##ZrUc=kh%OHWhp=7;?8%Xj||@V?1c ziWoaC$^&04;A|T)!Zd9sUzE&$ODyJaBpvqsw19Uiuq{i#VK1!htkdRWBnb z`{rat=nHArT%^R>u#CjjCkw-7%g53|&7z-;X+ewb?OLWiV|#nuc8mp*LuGSi3IP<<*Wyo9GKV7l0Noa4Jr0g3p_$ z*R9{qn=?IXC#WU>48-k5V2Oc_>P;4_)J@bo1|pf=%Rcbgk=5m)CJZ`caHBTm3%!Z9 z_?7LHr_BXbKKr=JD!%?KhwdYSdu8XxPoA{n8^%_lh5cjRHuCY9Zlpz8g+$f@bw@0V z+6DRMT9c|>1^3D|$Vzc(C?M~iZurGH2pXPT%F!JSaAMdO%!5o0uc&iqHx?ImcX6fI zCApkzc~OOnfzAd_+-DcMp&AOQxE_EsMqKM{%dRMI5`5CT&%mQO?-@F6tE*xL?aEGZ z8^wH@wRl`Izx4sDmU>}Ym{ybUm@F83qqZPD6nFm?t?(7>h*?`fw)L3t*l%*iw0Qu#?$5eq!Qc zpQvqgSxrd83NsdO@lL6#{%lsYXWen~d3p4fGBb7&5xqNYJ)yn84!e1PmPo7ChVd%4 zHUsV0Mh?VpzZD=A6%)Qrd~i7 z96*RPbid;BN{Wh?adeD_p8YU``kOrGkNox3D9~!K?w>#kFz!4lzOWR}puS(DmfjJD z`x0z|qB33*^0mZdM&6$|+T>fq>M%yoy(BEjuh9L0>{P&XJ3enGpoQRx`v6$txXt#c z0#N?b5%srj(4xmPvJxrlF3H%OMB!jvfy z;wx8RzU~lb?h_}@V=bh6p8PSb-dG|-T#A?`c&H2`_!u+uenIZe`6f~A7r)`9m8atC zt(b|6Eg#!Q*DfRU=Ix`#B_dK)nnJ_+>Q<1d7W)eynaVn`FNuN~%B;uO2}vXr5^zi2 z!ifIF5@Zlo0^h~8+ixFBGqtweFc`C~JkSq}&*a3C}L?b5Mh-bW=e)({F_g4O3 zb@SFTK3VD9QuFgFnK4Ve_pXc3{S$=+Z;;4+;*{H}Rc;845rP?DLK6G5Y-xdUKkA6E3Dz&5f{F^FjJQ(NSpZ8q-_!L3LL@H* zxbDF{gd^U3uD;)a)sJwAVi}7@%pRM&?5IaUH%+m{E)DlA_$IA1=&jr{KrhD5q&lTC zAa3c)A(K!{#nOvenH6XrR-y>*4M#DpTTOGQEO5Jr6kni9pDW`rvY*fs|ItV;CVITh z=`rxcH2nEJpkQ^(;1c^hfb8vGN;{{oR=qNyKtR1;J>CByul*+=`NydWnSWJR#I2lN zTvgnR|MBx*XFsfdA&;tr^dYaqRZp*2NwkAZE6kV@1f{76e56eUmGrZ>MDId)oqSWw z7d&r3qfazg+W2?bT}F)4jD6sWaw`_fXZGY&wnGm$FRPFL$HzVTH^MYBHWGCOk-89y zA+n+Q6EVSSCpgC~%uHfvyg@ufE^#u?JH?<73A}jj5iILz4Qqk5$+^U(SX(-qv5agK znUkfpke(KDn~dU0>gdKqjTkVk`0`9^0n_wzXO7R!0Thd@S;U`y)VVP&mOd-2 z(hT(|$=>4FY;CBY9#_lB$;|Wd$aOMT5O_3}DYXEHn&Jrc3`2JiB`b6X@EUOD zVl0S{ijm65@n^19T3l%>*;F(?3r3s?zY{thc4%AD30CeL_4{8x6&cN}zN3fE+x<9; zt2j1RRVy5j22-8U8a6$pyT+<`f+x2l$fd_{qEp_bfxfzu>ORJsXaJn4>U6oNJ#|~p z`*ZC&NPXl&=vq2{Ne79AkQncuxvbOG+28*2wU$R=GOmns3W@HE%^r)Fu%Utj=r9t` zd;SVOnA(=MXgnOzI2@3SGKHz8HN~Vpx&!Ea+Df~`*n@8O=0!b4m?7cE^K*~@fqv9q zF*uk#1@6Re_<^9eElgJD!nTA@K9C732tV~;B`hzZ321Ph=^BH?zXddiu{Du5*IPg} zqDM=QxjT!Rp|#Bkp$(mL)aar)f(dOAXUiw81pX0DC|Y4;>Vz>>DMshoips^8Frdv} zlTD=cKa48M>dR<>(YlLPOW%rokJZNF2gp8fwc8b2sN+i6&-pHr?$rj|uFgktK@jg~ zIFS(%=r|QJ=$kvm_~@n=ai1lA{7Z}i+zj&yzY+!t$iGUy|9jH#&oTNJ;JW-3n>DF+ z3aCOzqn|$X-Olu_p7brzn`uk1F*N4@=b=m;S_C?#hy{&NE#3HkATrg?enaVGT^$qIjvgc61y!T$9<1B@?_ibtDZ{G zeXInVr5?OD_nS_O|CK3|RzzMmu+8!#Zb8Ik;rkIAR%6?$pN@d<0dKD2c@k2quB%s( zQL^<_EM6ow8F6^wJN1QcPOm|ehA+dP(!>IX=Euz5qqIq}Y3;ibQtJnkDmZ8c8=Cf3 zu`mJ!Q6wI7EblC5RvP*@)j?}W=WxwCvF3*5Up_`3*a~z$`wHwCy)2risye=1mSp%p zu+tD6NAK3o@)4VBsM!@);qgsjgB$kkCZhaimHg&+k69~drbvRTacWKH;YCK(!rC?8 zP#cK5JPHSw;V;{Yji=55X~S+)%(8fuz}O>*F3)hR;STU`z6T1aM#Wd+FP(M5*@T1P z^06O;I20Sk!bxW<-O;E081KRdHZrtsGJflFRRFS zdi5w9OVDGSL3 zNrC7GVsGN=b;YH9jp8Z2$^!K@h=r-xV(aEH@#JicPy;A0k1>g1g^XeR`YV2HfmqXY zYbRwaxHvf}OlCAwHoVI&QBLr5R|THf?nAevV-=~V8;gCsX>jndvNOcFA+DI+zbh~# zZ7`qNk&w+_+Yp!}j;OYxIfx_{f0-ONc?mHCiCUak=>j>~>YR4#w# zuKz~UhT!L~GfW^CPqG8Lg)&Rc6y^{%3H7iLa%^l}cw_8UuG;8nn9)kbPGXS}p3!L_ zd#9~5CrH8xtUd?{d2y^PJg+z(xIfRU;`}^=OlehGN2=?}9yH$4Rag}*+AWotyxfCJ zHx=r7ZH>j2kV?%7WTtp+-HMa0)_*DBBmC{sd$)np&GEJ__kEd`xB5a2A z*J+yx>4o#ZxwA{;NjhU*1KT~=ZK~GAA;KZHDyBNTaWQ1+;tOFFthnD)DrCn`DjBZ% zk$N5B4^$`n^jNSOr=t(zi8TN4fpaccsb`zOPD~iY=UEK$0Y70bG{idLx@IL)7^(pL z{??Bnu=lDeguDrd%qW1)H)H`9otsOL-f4bSu};o9OXybo6J!Lek`a4ff>*O)BDT_g z<6@SrI|C9klY(>_PfA^qai7A_)VNE4c^ZjFcE$Isp>`e5fLc)rg@8Q_d^Uk24$2bn z9#}6kZ2ZxS9sI(RqT7?El2@B+($>eBQrNi_k#CDJ8D9}8$mmm z4oSKO^F$i+NG)-HE$O6s1--6EzJa?C{x=QgK&c=)b(Q9OVoAXYEEH20G|q$}Hue%~ zO3B^bF=t7t48sN zWh_zA`w~|){-!^g?6Mqf6ieV zFx~aPUOJGR=4{KsW7I?<=J2|lY`NTU=lt=%JE9H1vBpkcn=uq(q~=?iBt_-r(PLBM zP-0dxljJO>4Wq-;stY)CLB4q`-r*T$!K2o}?E-w_i>3_aEbA^MB7P5piwt1dI-6o!qWCy0 ztYy!x9arGTS?kabkkyv*yxvsPQ7Vx)twkS6z2T@kZ|kb8yjm+^$|sEBmvACeqbz)RmxkkDQX-A*K!YFziuhwb|ym>C$}U|J)4y z$(z#)GH%uV6{ec%Zy~AhK|+GtG8u@c884Nq%w`O^wv2#A(&xH@c5M`Vjk*SR_tJnq z0trB#aY)!EKW_}{#L3lph5ow=@|D5LzJYUFD6 z7XnUeo_V0DVSIKMFD_T0AqAO|#VFDc7c?c-Q%#u00F%!_TW1@JVnsfvm@_9HKWflBOUD~)RL``-!P;(bCON_4eVdduMO>?IrQ__*zE@7(OX zUtfH@AX*53&xJW*Pu9zcqxGiM>xol0I~QL5B%Toog3Jlenc^WbVgeBvV8C8AX^Vj& z^I}H})B=VboO%q1;aU5ACMh{yK4J;xlMc`jCnZR^!~LDs_MP&8;dd@4LDWw~*>#OT zeZHwdQWS!tt5MJQI~cw|Ka^b4c|qyd_ly(+Ql2m&AAw^ zQeSXDOOH!!mAgzAp0z)DD>6Xo``b6QwzUV@w%h}Yo>)a|xRi$jGuHQhJVA%>)PUvK zBQ!l0hq<3VZ*RnrDODP)>&iS^wf64C;MGqDvx>|p;35%6(u+IHoNbK z;Gb;TneFo*`zUKS6kwF*&b!U8e5m4YAo03a_e^!5BP42+r)LFhEy?_7U1IR<; z^0v|DhCYMSj<-;MtY%R@Fg;9Kky^pz_t2nJfKWfh5Eu@_l{^ph%1z{jkg5jQrkvD< z#vdK!nku*RrH~TdN~`wDs;d>XY1PH?O<4^U4lmA|wUW{Crrv#r%N>7k#{Gc44Fr|t z@UZP}Y-TrAmnEZ39A*@6;ccsR>)$A)S>$-Cj!=x$rz7IvjHIPM(TB+JFf{ehuIvY$ zsDAwREg*%|=>Hw$`us~RP&3{QJg%}RjJKS^mC_!U;E5u>`X`jW$}P`Mf}?7G7FX#{ zE(9u1SO;3q@ZhDL9O({-RD+SqqPX)`0l5IQu4q)49TUTkxR(czeT}4`WV~pV*KY&i zAl3~X%D2cPVD^B43*~&f%+Op)wl<&|D{;=SZwImydWL6@_RJjxP2g)s=dH)u9Npki zs~z9A+3fj0l?yu4N0^4aC5x)Osnm0qrhz@?nwG_`h(71P znbIewljU%T*cC=~NJy|)#hT+lx#^5MuDDnkaMb*Efw9eThXo|*WOQzJ*#3dmRWm@! zfuSc@#kY{Um^gBc^_Xdxnl!n&y&}R4yAbK&RMc+P^Ti;YIUh|C+K1|=Z^{nZ}}rxH*v{xR!i%qO~o zTr`WDE@k$M9o0r4YUFFeQO7xCu_Zgy)==;fCJ94M_rLAv&~NhfvcLWCoaGg2ao~3e zBG?Ms9B+efMkp}7BhmISGWmJsKI@a8b}4lLI48oWKY|8?zuuNc$lt5Npr+p7a#sWu zh!@2nnLBVJK!$S~>r2-pN||^w|fY`CT{TFnJy`B|e5;=+_v4l8O-fkN&UQbA4NKTyntd zqK{xEKh}U{NHoQUf!M=2(&w+eef77VtYr;xs%^cPfKLObyOV_9q<(%76-J%vR>w9!us-0c-~Y?_EVS%v!* z15s2s3eTs$Osz$JayyH|5nPAIPEX=U;r&p;K14G<1)bvn@?bM5kC{am|C5%hyxv}a z(DeSKI5ZfZ1*%dl8frIX2?);R^^~LuDOpNpk-2R8U1w92HmG1m&|j&J{EK=|p$;f9 z7Rs5|jr4r8k5El&qcuM+YRlKny%t+1CgqEWO>3;BSRZi(LA3U%Jm{@{y+A+w(gzA< z7dBq6a1sEWa4cD0W7=Ld9z0H7RI^Z7vl(bfA;72j?SWCo`#5mVC$l1Q2--%V)-uN* z9ha*s-AdfbDZ8R8*fpwjzx=WvOtmSzGFjC#X)hD%Caeo^OWjS(3h|d9_*U)l%{Ab8 zfv$yoP{OuUl@$(-sEVNt{*=qi5P=lpxWVuz2?I7Dc%BRc+NGNw+323^ z5BXGfS71oP^%apUo(Y#xkxE)y?>BFzEBZ}UBbr~R4$%b7h3iZu3S(|A;&HqBR{nK& z$;GApNnz=kNO^FL&nYcfpB7Qg;hGJPsCW44CbkG1@l9pn0`~oKy5S777uH)l{irK!ru|X+;4&0D;VE*Ii|<3P zUx#xUqvZT5kVQxsF#~MwKnv7;1pR^0;PW@$@T7I?s`_rD1EGUdSA5Q(C<>5SzE!vw z;{L&kKFM-MO>hy#-8z`sdVx})^(Dc-dw;k-h*9O2_YZw}|9^y-|8RQ`BWJUJL(Cer zP5Z@fNc>pTXABbTRY-B5*MphpZv6#i802giwV&SkFCR zGMETyUm(KJbh+&$8X*RB#+{surjr;8^REEt`2&Dubw3$mx>|~B5IKZJ`s_6fw zKAZx9&PwBqW1Oz0r0A4GtnZd7XTKViX2%kPfv+^X3|_}RrQ2e3l=KG_VyY`H?I5&CS+lAX5HbA%TD9u6&s#v!G> zzW9n4J%d5ye7x0y`*{KZvqyXUfMEE^ZIffzI=Hh|3J}^yx7eL=s+TPH(Q2GT-sJ~3 zI463C{(ag7-hS1ETtU;_&+49ABt5!A7CwLwe z=SoA8mYZIQeU;9txI=zcQVbuO%q@E)JI+6Q!3lMc=Gbj(ASg-{V27u>z2e8n;Nc*pf}AqKz1D>p9G#QA+7mqqrEjGfw+85Uyh!=tTFTv3|O z+)-kFe_8FF_EkTw!YzwK^Hi^_dV5x-Ob*UWmD-})qKj9@aE8g240nUh=g|j28^?v7 zHRTBo{0KGaWBbyX2+lx$wgXW{3aUab6Bhm1G1{jTC7ota*JM6t+qy)c5<@ zpc&(jVdTJf(q3xB=JotgF$X>cxh7k*(T`-V~AR+`%e?YOeALQ2Qud( zz35YizXt(aW3qndR}fTw1p()Ol4t!D1pitGNL95{SX4ywzh0SF;=!wf=?Q?_h6!f* zh7<+GFi)q|XBsvXZ^qVCY$LUa{5?!CgwY?EG;*)0ceFe&=A;!~o`ae}Z+6me#^sv- z1F6=WNd6>M(~ z+092z>?Clrcp)lYNQl9jN-JF6n&Y0mp7|I0dpPx+4*RRK+VQI~>en0Dc;Zfl+x z_e_b7s`t1_A`RP3$H}y7F9_na%D7EM+**G_Z0l_nwE+&d_kc35n$Fxkd4r=ltRZhh zr9zER8>j(EdV&Jgh(+i}ltESBK62m0nGH6tCBr90!4)-`HeBmz54p~QP#dsu%nb~W z7sS|(Iydi>C@6ZM(Us!jyIiszMkd)^u<1D+R@~O>HqZIW&kearPWmT>63%_t2B{_G zX{&a(gOYJx!Hq=!T$RZ&<8LDnxsmx9+TBL0gTk$|vz9O5GkK_Yx+55^R=2g!K}NJ3 zW?C;XQCHZl7H`K5^BF!Q5X2^Mj93&0l_O3Ea3!Ave|ixx+~bS@Iv18v2ctpSt4zO{ zp#7pj!AtDmti$T`e9{s^jf(ku&E|83JIJO5Qo9weT6g?@vX!{7)cNwymo1+u(YQ94 zopuz-L@|5=h8A!(g-MXgLJC0MA|CgQF8qlonnu#j z;uCeq9ny9QSD|p)9sp3ebgY3rk#y0DA(SHdh$DUm^?GI<>%e1?&}w(b zdip1;P2Z=1wM+$q=TgLP$}svd!vk+BZ@h<^4R=GS2+sri7Z*2f`9 z5_?i)xj?m#pSVchk-SR!2&uNhzEi+#5t1Z$o0PoLGz*pT64%+|Wa+rd5Z}60(j?X= z{NLjtgRb|W?CUADqOS@(*MA-l|E342NxRaxLTDqsOyfWWe%N(jjBh}G zm7WPel6jXijaTiNita+z(5GCO0NM=Melxud57PP^d_U## zbA;9iVi<@wr0DGB8=T9Ab#2K_#zi=$igyK48@;V|W`fg~7;+!q8)aCOo{HA@vpSy-4`^!ze6-~8|QE||hC{ICKllG9fbg_Y7v z$jn{00!ob3!@~-Z%!rSZ0JO#@>|3k10mLK0JRKP-Cc8UYFu>z93=Ab-r^oL2 zl`-&VBh#=-?{l1TatC;VweM^=M7-DUE>m+xO7Xi6vTEsReyLs8KJ+2GZ&rxw$d4IT zPXy6pu^4#e;;ZTsgmG+ZPx>piodegkx2n0}SM77+Y*j^~ICvp#2wj^BuqRY*&cjmL zcKp78aZt>e{3YBb4!J_2|K~A`lN=u&5j!byw`1itV(+Q_?RvV7&Z5XS1HF)L2v6ji z&kOEPmv+k_lSXb{$)of~(BkO^py&7oOzpjdG>vI1kcm_oPFHy38%D4&A4h_CSo#lX z2#oqMCTEP7UvUR3mwkPxbl8AMW(e{ARi@HCYLPSHE^L<1I}OgZD{I#YH#GKnpRmW3 z2jkz~Sa(D)f?V?$gNi?6)Y;Sm{&?~2p=0&BUl_(@hYeX8YjaRO=IqO7neK0RsSNdYjD zaw$g2sG(>JR=8Iz1SK4`*kqd_3-?;_BIcaaMd^}<@MYbYisWZm2C2|Np_l|8r9yM|JkUngSo@?wci(7&O9a z%|V(4C1c9pps0xxzPbXH=}QTxc2rr7fXk$9`a6TbWKPCz&p=VsB8^W96W=BsB|7bc zf(QR8&Ktj*iz)wK&mW`#V%4XTM&jWNnDF56O+2bo<3|NyUhQ%#OZE8$Uv2a@J>D%t zMVMiHh?es!Ex19q&6eC&L=XDU_BA&uR^^w>fpz2_`U87q_?N2y;!Z!bjoeKrzfC)} z?m^PM=(z{%n9K`p|7Bz$LuC7!>tFOuN74MFELm}OD9?%jpT>38J;=1Y-VWtZAscaI z_8jUZ#GwWz{JqvGEUmL?G#l5E=*m>`cY?m*XOc*yOCNtpuIGD+Z|kn4Xww=BLrNYS zGO=wQh}Gtr|7DGXLF%|`G>J~l{k^*{;S-Zhq|&HO7rC_r;o`gTB7)uMZ|WWIn@e0( zX$MccUMv3ABg^$%_lNrgU{EVi8O^UyGHPNRt%R!1#MQJn41aD|_93NsBQhP80yP<9 zG4(&0u7AtJJXLPcqzjv`S~5;Q|5TVGccN=Uzm}K{v)?f7W!230C<``9(64}D2raRU zAW5bp%}VEo{4Rko`bD%Ehf=0voW?-4Mk#d3_pXTF!-TyIt6U+({6OXWVAa;s-`Ta5 zTqx&8msH3+DLrVmQOTBOAj=uoxKYT3DS1^zBXM?1W+7gI!aQNPYfUl{3;PzS9*F7g zWJN8x?KjBDx^V&6iCY8o_gslO16=kh(|Gp)kz8qlQ`dzxQv;)V&t+B}wwdi~uBs4? zu~G|}y!`3;8#vIMUdyC7YEx6bb^1o}G!Jky4cN?BV9ejBfN<&!4M)L&lRKiuMS#3} z_B}Nkv+zzxhy{dYCW$oGC&J(Ty&7%=5B$sD0bkuPmj7g>|962`(Q{ZZMDv%YMuT^KweiRDvYTEop3IgFv#)(w>1 zSzH>J`q!LK)c(AK>&Ib)A{g`Fdykxqd`Yq@yB}E{gnQV$K!}RsgMGWqC3DKE(=!{}ekB3+(1?g}xF>^icEJbc z5bdxAPkW90atZT+&*7qoLqL#p=>t-(-lsnl2XMpZcYeW|o|a322&)yO_8p(&Sw{|b zn(tY$xn5yS$DD)UYS%sP?c|z>1dp!QUD)l;aW#`%qMtQJjE!s2z`+bTSZmLK7SvCR z=@I4|U^sCwZLQSfd*ACw9B@`1c1|&i^W_OD(570SDLK`MD0wTiR8|$7+%{cF&){$G zU~|$^Ed?TIxyw{1$e|D$050n8AjJvvOWhLtLHbSB|HIfjMp+gu>DraHZJRrdO53(= z+o-f{+qNog+qSLB%KY;5>Av6X(>-qYk3IIEwZ5~6a+P9lMpC^ z8CJ0q>rEpjlsxCvJm=kms@tlN4+sv}He`xkr`S}bGih4t`+#VEIt{1veE z{ZLtb_pSbcfcYPf4=T1+|BtR!x5|X#x2TZEEkUB6kslKAE;x)*0x~ES0kl4Dex4e- zT2P~|lT^vUnMp{7e4OExfxak0EE$Hcw;D$ehTV4a6hqxru0$|Mo``>*a5=1Ym0u>BDJKO|=TEWJ5jZu!W}t$Kv{1!q`4Sn7 zrxRQOt>^6}Iz@%gA3&=5r;Lp=N@WKW;>O!eGIj#J;&>+3va^~GXRHCY2}*g#9ULab zitCJt-OV0*D_Q3Q`p1_+GbPxRtV_T`jyATjax<;zZ?;S+VD}a(aN7j?4<~>BkHK7bO8_Vqfdq1#W&p~2H z&w-gJB4?;Q&pG9%8P(oOGZ#`!m>qAeE)SeL*t8KL|1oe;#+uOK6w&PqSDhw^9-&Fa zuEzbi!!7|YhlWhqmiUm!muO(F8-F7|r#5lU8d0+=;<`{$mS=AnAo4Zb^{%p}*gZL! zeE!#-zg0FWsSnablw!9$<&K(#z!XOW z;*BVx2_+H#`1b@>RtY@=KqD)63brP+`Cm$L1@ArAddNS1oP8UE$p05R=bvZoYz+^6 z<)!v7pRvi!u_-V?!d}XWQR1~0q(H3{d^4JGa=W#^Z<@TvI6J*lk!A zZ*UIKj*hyO#5akL*Bx6iPKvR3_2-^2mw|Rh-3O_SGN3V9GRo52Q;JnW{iTGqb9W99 z7_+F(Op6>~3P-?Q8LTZ-lwB}xh*@J2Ni5HhUI3`ct|*W#pqb>8i*TXOLn~GlYECIj zhLaa_rBH|1jgi(S%~31Xm{NB!30*mcsF_wgOY2N0XjG_`kFB+uQuJbBm3bIM$qhUyE&$_u$gb zpK_r{99svp3N3p4yHHS=#csK@j9ql*>j0X=+cD2dj<^Wiu@i>c_v zK|ovi7}@4sVB#bzq$n3`EgI?~xDmkCW=2&^tD5RuaSNHf@Y!5C(Is$hd6cuyoK|;d zO}w2AqJPS`Zq+(mc*^%6qe>1d&(n&~()6-ZATASNPsJ|XnxelLkz8r1x@c2XS)R*H(_B=IN>JeQUR;T=i3<^~;$<+8W*eRKWGt7c#>N`@;#!`kZ!P!&{9J1>_g8Zj zXEXxmA=^{8A|3=Au+LfxIWra)4p<}1LYd_$1KI0r3o~s1N(x#QYgvL4#2{z8`=mXy zQD#iJ0itk1d@Iy*DtXw)Wz!H@G2St?QZFz zVPkM%H8Cd2EZS?teQN*Ecnu|PrC!a7F_XX}AzfZl3fXfhBtc2-)zaC2eKx*{XdM~QUo4IwcGgVdW69 z1UrSAqqMALf^2|(I}hgo38l|Ur=-SC*^Bo5ej`hb;C$@3%NFxx5{cxXUMnTyaX{>~ zjL~xm;*`d08bG_K3-E+TI>#oqIN2=An(C6aJ*MrKlxj?-;G zICL$hi>`F%{xd%V{$NhisHSL~R>f!F7AWR&7b~TgLu6!3s#~8|VKIX)KtqTH5aZ8j zY?wY)XH~1_a3&>#j7N}0az+HZ;is;Zw(Am{MX}YhDTe(t{ZZ;TG}2qWYO+hdX}vp9 z@uIRR8g#y~-^E`Qyem(31{H0&V?GLdq9LEOb2(ea#e-$_`5Q{T%E?W(6 z(XbX*Ck%TQM;9V2LL}*Tf`yzai{0@pYMwBu%(I@wTY!;kMrzcfq0w?X`+y@0ah510 zQX5SU(I!*Fag4U6a7Lw%LL;L*PQ}2v2WwYF(lHx_Uz2ceI$mnZ7*eZ?RFO8UvKI0H z9Pq-mB`mEqn6n_W9(s~Jt_D~j!Ln9HA)P;owD-l~9FYszs)oEKShF9Zzcmnb8kZ7% zQ`>}ki1kwUO3j~ zEmh140sOkA9v>j@#56ymn_RnSF`p@9cO1XkQy6_Kog?0ivZDb`QWOX@tjMd@^Qr(p z!sFN=A)QZm!sTh(#q%O{Ovl{IxkF!&+A)w2@50=?a-+VuZt6On1;d4YtUDW{YNDN_ zG@_jZi1IlW8cck{uHg^g=H58lPQ^HwnybWy@@8iw%G! zwB9qVGt_?~M*nFAKd|{cGg+8`+w{j_^;nD>IrPf-S%YjBslSEDxgKH{5p)3LNr!lD z4ii)^%d&cCXIU7UK?^ZQwmD(RCd=?OxmY(Ko#+#CsTLT;p#A%{;t5YpHFWgl+@)N1 zZ5VDyB;+TN+g@u~{UrWrv)&#u~k$S&GeW)G{M#&Di)LdYk?{($Cq zZGMKeYW)aMtjmKgvF0Tg>Mmkf9IB#2tYmH-s%D_9y3{tfFmX1BSMtbe<(yqAyWX60 zzkgSgKb3c{QPG2MalYp`7mIrYg|Y<4Jk?XvJK)?|Ecr+)oNf}XLPuTZK%W>;<|r+% zTNViRI|{sf1v7CsWHvFrkQ$F7+FbqPQ#Bj7XX=#M(a~9^80}~l-DueX#;b}Ajn3VE z{BWI}$q{XcQ3g{(p>IOzFcAMDG0xL)H%wA)<(gl3I-oVhK~u_m=hAr&oeo|4lZbf} z+pe)c34Am<=z@5!2;_lwya;l?xV5&kWe}*5uBvckm(d|7R>&(iJNa6Y05SvlZcWBlE{{%2- z`86)Y5?H!**?{QbzGG~|k2O%eA8q=gxx-3}&Csf6<9BsiXC)T;x4YmbBIkNf;0Nd5 z%whM^!K+9zH>on_<&>Ws?^v-EyNE)}4g$Fk?Z#748e+GFp)QrQQETx@u6(1fk2!(W zWiCF~MomG*y4@Zk;h#2H8S@&@xwBIs|82R*^K(i*0MTE%Rz4rgO&$R zo9Neb;}_ulaCcdn3i17MO3NxzyJ=l;LU*N9ztBJ30j=+?6>N4{9YXg$m=^9@Cl9VY zbo^{yS@gU=)EpQ#;UIQBpf&zfCA;00H-ee=1+TRw@(h%W=)7WYSb5a%$UqNS@oI@= zDrq|+Y9e&SmZrH^iA>Of8(9~Cf-G(P^5Xb%dDgMMIl8gk6zdyh`D3OGNVV4P9X|EvIhplXDld8d z^YWtYUz@tpg*38Xys2?zj$F8%ivA47cGSl;hjD23#*62w3+fwxNE7M7zVK?x_`dBSgPK zWY_~wF~OEZi9|~CSH8}Xi>#8G73!QLCAh58W+KMJJC81{60?&~BM_0t-u|VsPBxn* zW7viEKwBBTsn_A{g@1!wnJ8@&h&d>!qAe+j_$$Vk;OJq`hrjzEE8Wjtm)Z>h=*M25 zOgETOM9-8xuuZ&^@rLObtcz>%iWe%!uGV09nUZ*nxJAY%&KAYGY}U1WChFik7HIw% zZP$3Bx|TG_`~19XV7kfi2GaBEhKap&)Q<9`aPs#^!kMjtPb|+-fX66z3^E)iwyXK7 z8)_p<)O{|i&!qxtgBvWXx8*69WO$5zACl++1qa;)0zlXf`eKWl!0zV&I`8?sG)OD2Vy?reNN<{eK+_ za4M;Hh%&IszR%)&gpgRCP}yheQ+l#AS-GnY81M!kzhWxIR?PW`G3G?} z$d%J28uQIuK@QxzGMKU_;r8P0+oIjM+k)&lZ39i#(ntY)*B$fdJnQ3Hw3Lsi8z&V+ zZly2}(Uzpt2aOubRjttzqrvinBFH4jrN)f0hy)tj4__UTwN)#1fj3-&dC_Vh7}ri* zfJ=oqLMJ-_<#rwVyN}_a-rFBe2>U;;1(7UKH!$L??zTbbzP#bvyg7OQBGQklJ~DgP zd<1?RJ<}8lWwSL)`jM53iG+}y2`_yUvC!JkMpbZyb&50V3sR~u+lok zT0uFRS-yx@8q4fPRZ%KIpLp8R#;2%c&Ra4p(GWRT4)qLaPNxa&?8!LRVdOUZ)2vrh zBSx&kB%#Y4!+>~)<&c>D$O}!$o{<1AB$M7-^`h!eW;c(3J~ztoOgy6Ek8Pwu5Y`Xion zFl9fb!k2`3uHPAbd(D^IZmwR5d8D$495nN2`Ue&`W;M-nlb8T-OVKt|fHk zBpjX$a(IR6*-swdNk@#}G?k6F-~c{AE0EWoZ?H|ZpkBxqU<0NUtvubJtwJ1mHV%9v?GdDw; zAyXZiD}f0Zdt-cl9(P1la+vQ$Er0~v}gYJVwQazv zH#+Z%2CIfOf90fNMGos|{zf&N`c0@x0N`tkFv|_9af3~<0z@mnf*e;%r*Fbuwl-IW z{}B3=(mJ#iwLIPiUP`J3SoP~#)6v;aRXJ)A-pD2?_2_CZ#}SAZ<#v7&Vk6{*i(~|5 z9v^nC`T6o`CN*n%&9+bopj^r|E(|pul;|q6m7Tx+U|UMjWK8o-lBSgc3ZF=rP{|l9 zc&R$4+-UG6i}c==!;I#8aDIbAvgLuB66CQLRoTMu~jdw`fPlKy@AKYWS-xyZzPg&JRAa@m-H43*+ne!8B7)HkQY4 zIh}NL4Q79a-`x;I_^>s$Z4J4-Ngq=XNWQ>yAUCoe&SMAYowP>r_O}S=V+3=3&(O=h zNJDYNs*R3Y{WLmBHc?mFEeA4`0Y`_CN%?8qbDvG2m}kMAiqCv`_BK z_6a@n`$#w6Csr@e2YsMx8udNWtNt=kcqDZdWZ-lGA$?1PA*f4?X*)hjn{sSo8!bHz zb&lGdAgBx@iTNPK#T_wy`KvOIZvTWqSHb=gWUCKXAiB5ckQI`1KkPx{{%1R*F2)Oc z(9p@yG{fRSWE*M9cdbrO^)8vQ2U`H6M>V$gK*rz!&f%@3t*d-r3mSW>D;wYxOhUul zk~~&ip5B$mZ~-F1orsq<|1bc3Zpw6)Ws5;4)HilsN;1tx;N6)tuePw& z==OlmaN*ybM&-V`yt|;vDz(_+UZ0m&&9#{9O|?0I|4j1YCMW;fXm}YT$0%EZ5^YEI z4i9WV*JBmEU{qz5O{#bs`R1wU%W$qKx?bC|e-iS&d*Qm7S=l~bMT{~m3iZl+PIXq{ zn-c~|l)*|NWLM%ysfTV-oR0AJ3O>=uB-vpld{V|cWFhI~sx>ciV9sPkC*3i0Gg_9G!=4ar*-W?D9)?EFL1=;O+W8}WGdp8TT!Fgv z{HKD`W>t(`Cds_qliEzuE!r{ihwEv1l5o~iqlgjAyGBi)$%zNvl~fSlg@M=C{TE;V zQkH`zS8b&!ut(m)%4n2E6MB>p*4(oV>+PT51#I{OXs9j1vo>9I<4CL1kv1aurV*AFZ^w_qfVL*G2rG@D2 zrs87oV3#mf8^E5hd_b$IXfH6vHe&lm@7On~Nkcq~YtE!}ad~?5*?X*>y`o;6Q9lkk zmf%TYonZM`{vJg$`lt@MXsg%*&zZZ0uUSse8o=!=bfr&DV)9Y6$c!2$NHyYAQf*Rs zk{^?gl9E z5Im8wlAsvQ6C2?DyG@95gUXZ3?pPijug25g;#(esF_~3uCj3~94}b*L>N2GSk%Qst z=w|Z>UX$m!ZOd(xV*2xvWjN&c5BVEdVZ0wvmk)I+YxnyK%l~caR=7uNQ=+cnNTLZ@&M!I$Mj-r{!P=; z`C2)D=VmvK8@T5S9JZoRtN!S*D_oqOxyy!q6Zk|~4aT|*iRN)fL)c>-yycR>-is0X zKrko-iZw(f(!}dEa?hef5yl%p0-v-8#8CX8!W#n2KNyT--^3hq6r&`)5Y@>}e^4h- zlPiDT^zt}Ynk&x@F8R&=)k8j$=N{w9qUcIc&)Qo9u4Y(Ae@9tA`3oglxjj6c{^pN( zQH+Uds2=9WKjH#KBIwrQI%bbs`mP=7V>rs$KG4|}>dxl_k!}3ZSKeEen4Iswt96GGw`E6^5Ov)VyyY}@itlj&sao|>Sb5 zeY+#1EK(}iaYI~EaHQkh7Uh>DnzcfIKv8ygx1Dv`8N8a6m+AcTa-f;17RiEed>?RT zk=dAksmFYPMV1vIS(Qc6tUO+`1jRZ}tcDP? zt)=7B?yK2RcAd1+Y!$K5*ds=SD;EEqCMG6+OqPoj{&8Y5IqP(&@zq@=A7+X|JBRi4 zMv!czlMPz)gt-St2VZwDD=w_S>gRpc-g zUd*J3>bXeZ?Psjohe;z7k|d<*T21PA1i)AOi8iMRwTBSCd0ses{)Q`9o&p9rsKeLaiY zluBw{1r_IFKR76YCAfl&_S1*(yFW8HM^T()&p#6y%{(j7Qu56^ZJx1LnN`-RTwimdnuo*M8N1ISl+$C-%=HLG-s} zc99>IXRG#FEWqSV9@GFW$V8!{>=lSO%v@X*pz*7()xb>=yz{E$3VE;e)_Ok@A*~El zV$sYm=}uNlUxV~6e<6LtYli1!^X!Ii$L~j4e{sI$tq_A(OkGquC$+>Rw3NFObV2Z)3Rt~Jr{oYGnZaFZ^g5TDZlg;gaeIP} z!7;T{(9h7mv{s@piF{-35L=Ea%kOp;^j|b5ZC#xvD^^n#vPH=)lopYz1n?Kt;vZmJ z!FP>Gs7=W{sva+aO9S}jh0vBs+|(B6Jf7t4F^jO3su;M13I{2rd8PJjQe1JyBUJ5v zcT%>D?8^Kp-70bP8*rulxlm)SySQhG$Pz*bo@mb5bvpLAEp${?r^2!Wl*6d7+0Hs_ zGPaC~w0E!bf1qFLDM@}zso7i~(``)H)zRgcExT_2#!YOPtBVN5Hf5~Ll3f~rWZ(UsJtM?O*cA1_W0)&qz%{bDoA}{$S&-r;0iIkIjbY~ zaAqH45I&ALpP=9Vof4OapFB`+_PLDd-0hMqCQq08>6G+C;9R~}Ug_nm?hhdkK$xpI zgXl24{4jq(!gPr2bGtq+hyd3%Fg%nofK`psHMs}EFh@}sdWCd!5NMs)eZg`ZlS#O0 zru6b8#NClS(25tXqnl{|Ax@RvzEG!+esNW-VRxba(f`}hGoqci$U(g30i}2w9`&z= zb8XjQLGN!REzGx)mg~RSBaU{KCPvQx8)|TNf|Oi8KWgv{7^tu}pZq|BS&S<53fC2K4Fw6>M^s$R$}LD*sUxdy6Pf5YKDbVet;P!bw5Al-8I1Nr(`SAubX5^D9hk6$agWpF}T#Bdf{b9-F#2WVO*5N zp+5uGgADy7m!hAcFz{-sS0kM7O)qq*rC!>W@St~^OW@R1wr{ajyYZq5H!T?P0e+)a zaQ%IL@X_`hzp~vRH0yUblo`#g`LMC%9}P;TGt+I7qNcBSe&tLGL4zqZqB!Bfl%SUa z6-J_XLrnm*WA`34&mF+&e1sPCP9=deazrM=Pc4Bn(nV;X%HG^4%Afv4CI~&l!Sjzb z{rHZ3od0!Al{}oBO>F*mOFAJrz>gX-vs!7>+_G%BB(ljWh$252j1h;9p~xVA=9_`P z5KoFiz96_QsTK%B&>MSXEYh`|U5PjX1(+4b#1PufXRJ*uZ*KWdth1<0 zsAmgjT%bowLyNDv7bTUGy|g~N34I-?lqxOUtFpTLSV6?o?<7-UFy*`-BEUsrdANh} zBWkDt2SAcGHRiqz)x!iVoB~&t?$yn6b#T=SP6Ou8lW=B>=>@ik93LaBL56ub`>Uo!>0@O8?e)$t(sgy$I z6tk3nS@yFFBC#aFf?!d_3;%>wHR;A3f2SP?Na8~$r5C1N(>-ME@HOpv4B|Ty7%jAv zR}GJwsiJZ5@H+D$^Cwj#0XA_(m^COZl8y7Vv(k=iav1=%QgBOVzeAiw zaDzzdrxzj%sE^c9_uM5D;$A_7)Ln}BvBx^=)fO+${ou%B*u$(IzVr-gH3=zL6La;G zu0Kzy5CLyNGoKRtK=G0-w|tnwI)puPDOakRzG(}R9fl7#<|oQEX;E#yCWVg95 z;NzWbyF&wGg_k+_4x4=z1GUcn6JrdX4nOVGaAQ8#^Ga>aFvajQN{!+9rgO-dHP zIp@%&ebVg}IqnRWwZRTNxLds+gz2@~VU(HI=?Epw>?yiEdZ>MjajqlO>2KDxA>)cj z2|k%dhh%d8SijIo1~20*5YT1eZTDkN2rc^zWr!2`5}f<2f%M_$to*3?Ok>e9$X>AV z2jYmfAd)s|(h?|B(XYrIfl=Wa_lBvk9R1KaP{90-z{xKi+&8=dI$W0+qzX|ZovWGOotP+vvYR(o=jo?k1=oG?%;pSqxcU* zWVGVMw?z__XQ9mnP!hziHC`ChGD{k#SqEn*ph6l46PZVkm>JF^Q{p&0=MKy_6apts z`}%_y+Tl_dSP(;Ja&sih$>qBH;bG;4;75)jUoVqw^}ee=ciV;0#t09AOhB^Py7`NC z-m+ybq1>_OO+V*Z>dhk}QFKA8V?9Mc4WSpzj{6IWfFpF7l^au#r7&^BK2Ac7vCkCn{m0uuN93Ee&rXfl1NBY4NnO9lFUp zY++C1I;_{#OH#TeP2Dp?l4KOF8ub?m6zE@XOB5Aiu$E~QNBM@;r+A5mF2W1-c7>ex zHiB=WJ&|`6wDq*+xv8UNLVUy4uW1OT>ey~Xgj@MMpS@wQbHAh>ysYvdl-1YH@&+Q! z075(Qd4C!V`9Q9jI4 zSt{HJRvZec>vaL_brKhQQwbpQd4_Lmmr0@1GdUeU-QcC{{8o=@nwwf>+dIKFVzPriGNX4VjHCa zTbL9w{Y2V87c2ofX%`(48A+4~mYTiFFl!e{3K^C_k%{&QTsgOd0*95KmWN)P}m zTRr{`f7@=v#+z_&fKYkQT!mJn{*crj%ZJz#(+c?>cD&2Lo~FFAWy&UG*Op^pV`BR^I|g?T>4l5;b|5OQ@t*?_Slp`*~Y3`&RfKD^1uLezIW(cE-Dq2z%I zBi8bWsz0857`6e!ahet}1>`9cYyIa{pe53Kl?8|Qg2RGrx@AlvG3HAL-^9c^1GW;)vQt8IK+ zM>!IW*~682A~MDlyCukldMd;8P|JCZ&oNL(;HZgJ>ie1PlaInK7C@Jg{3kMKYui?e!b`(&?t6PTb5UPrW-6DVU%^@^E`*y-Fd(p|`+JH&MzfEq;kikdse ziFOiDWH(D< zyV7Rxt^D0_N{v?O53N$a2gu%1pxbeK;&ua`ZkgSic~$+zvt~|1Yb=UfKJW2F7wC^evlPf(*El+#}ZBy0d4kbVJsK- z05>;>?HZO(YBF&v5tNv_WcI@O@LKFl*VO?L(!BAd!KbkVzo;v@~3v`-816GG?P zY+H3ujC>5=Am3RIZDdT#0G5A6xe`vGCNq88ZC1aVXafJkUlcYmHE^+Z{*S->ol%-O znm9R0TYTr2w*N8Vs#s-5=^w*{Y}qp5GG)Yt1oLNsH7y~N@>Eghms|K*Sdt_u!&I}$ z+GSdFTpbz%KH+?B%Ncy;C`uW6oWI46(tk>r|5|-K6)?O0d_neghUUOa9BXHP*>vi; z={&jIGMn-92HvInCMJcyXwHTJ42FZp&Wxu+9Rx;1x(EcIQwPUQ@YEQQ`bbMy4q3hP zNFoq~Qd0=|xS-R}k1Im3;8s{BnS!iaHIMLx)aITl)+)?Yt#fov|Eh>}dv@o6R{tG>uHsy&jGmWN5+*wAik|78(b?jtysPHC#e+Bzz~V zS3eEXv7!Qn4uWi!FS3B?afdD*{fr9>B~&tc671fi--V}~E4un;Q|PzZRwk-azprM$4AesvUb5`S`(5x#5VJ~4%ET6&%GR$}muHV-5lTsCi_R|6KM(g2PCD@|yOpKluT zakH!1V7nKN)?6JmC-zJoA#ciFux8!)ajiY%K#RtEg$gm1#oKUKX_Ms^%hvKWi|B=~ zLbl-L)-=`bfhl`>m!^sRR{}cP`Oim-{7}oz4p@>Y(FF5FUEOfMwO!ft6YytF`iZRq zfFr{!&0Efqa{1k|bZ4KLox;&V@ZW$997;+Ld8Yle91he{BfjRhjFTFv&^YuBr^&Pe zswA|Bn$vtifycN8Lxr`D7!Kygd7CuQyWqf}Q_PM}cX~S1$-6xUD%-jrSi24sBTFNz(Fy{QL2AmNbaVggWOhP;UY4D>S zqKr!UggZ9Pl9Nh_H;qI`-WoH{ceXj?m8y==MGY`AOJ7l0Uu z)>M%?dtaz2rjn1SW3k+p`1vs&lwb%msw8R!5nLS;upDSxViY98IIbxnh{}mRfEp=9 zbrPl>HEJeN7J=KnB6?dwEA6YMs~chHNG?pJsEj#&iUubdf3JJwu=C(t?JpE6xMyhA3e}SRhunDC zn-~83*9=mADUsk^sCc%&&G1q5T^HR9$P#2DejaG`Ui*z1hI#h7dwpIXg)C{8s< z%^#@uQRAg-$z&fmnYc$Duw63_Zopx|n{Bv*9Xau{a)2%?H<6D>kYY7_)e>OFT<6TT z0A}MQLgXbC2uf`;67`mhlcUhtXd)Kbc$PMm=|V}h;*_%vCw4L6r>3Vi)lE5`8hkSg zNGmW-BAOO)(W((6*e_tW&I>Nt9B$xynx|sj^ux~?q?J@F$L4;rnm_xy8E*JYwO-02u9_@@W0_2@?B@1J{y~Q39N3NX^t7#`=34Wh)X~sU&uZWgS1Z09%_k|EjA4w_QqPdY`oIdv$dJZ;(!k)#U8L+|y~gCzn+6WmFt#d{OUuKHqh1-uX_p*Af8pFYkYvKPKBxyid4KHc}H` z*KcyY;=@wzXYR{`d{6RYPhapShXIV?0cg_?ahZ7do)Ot#mxgXYJYx}<%E1pX;zqHd zf!c(onm{~#!O$2`VIXezECAHVd|`vyP)Uyt^-075X@NZDBaQt<>trA3nY-Dayki4S zZ^j6CCmx1r46`4G9794j-WC0&R9(G7kskS>=y${j-2;(BuIZTLDmAyWTG~`0)Bxqk zd{NkDe9ug|ms@0A>JVmB-IDuse9h?z9nw!U6tr7t-Lri5H`?TjpV~8(gZWFq4Vru4 z!86bDB;3lpV%{rZ`3gtmcRH1hjj!loI9jN>6stN6A*ujt!~s!2Q+U1(EFQEQb(h4E z6VKuRouEH`G6+8Qv2C)K@^;ldIuMVXdDDu}-!7FS8~k^&+}e9EXgx~)4V4~o6P^52 z)a|`J-fOirL^oK}tqD@pqBZi_;7N43%{IQ{v&G9^Y^1?SesL`;Z(dt!nn9Oj5Odde%opv&t zxJ><~b#m+^KV&b?R#)fRi;eyqAJ_0(nL*61yPkJGt;gZxSHY#t>ATnEl-E%q$E16% zZdQfvhm5B((y4E3Hk6cBdwGdDy?i5CqBlCVHZr-rI$B#>Tbi4}Gcvyg_~2=6O9D-8 zY2|tKrNzbVR$h57R?Pe+gUU_il}ZaWu|Az#QO@};=|(L-RVf0AIW zq#pO+RfM7tdV`9lI6g;{qABNId`fG%U9Va^ravVT^)CklDcx)YJKeJdGpM{W1v8jg z@&N+mR?BPB=K1}kNwXk_pj44sd>&^;d!Z~P>O78emE@Qp@&8PyB^^4^2f7e)gekMv z2aZNvP@;%i{+_~>jK7*2wQc6nseT^n6St9KG#1~Y@$~zR_=AcO2hF5lCoH|M&c{vR zSp(GRVVl=T*m~dIA;HvYm8HOdCkW&&4M~UDd^H)`p__!4k+6b)yG0Zcek8OLw$C^K z3-BbLiG_%qX|ZYpXJ$(c@aa7b4-*IQkDF}=gZSV`*ljP|5mWuHSCcf$5qqhZTv&P?I$z^>}qP(q!Aku2yA5vu38d8x*q{6-1`%PrE_r0-9Qo?a#7Zbz#iGI7K<(@k^|i4QJ1H z4jx?{rZbgV!me2VT72@nBjucoT zUM9;Y%TCoDop?Q5fEQ35bCYk7!;gH*;t9t-QHLXGmUF;|vm365#X)6b2Njsyf1h9JW#x$;@x5Nx2$K$Z-O3txa%;OEbOn6xBzd4n4v)Va=sj5 z%rb#j7{_??Tjb8(Hac<^&s^V{yO-BL*uSUk2;X4xt%NC8SjO-3?;Lzld{gM5A=9AV z)DBu-Z8rRvXXwSVDH|dL-3FODWhfe1C_iF``F05e{dl(MmS|W%k-j)!7(ARkV?6r~ zF=o42y+VapxdZn;GnzZfGu<6oG-gQ7j7Zvgo7Am@jYxC2FpS@I;Jb%EyaJDBQC(q% zKlZ}TVu!>;i3t~OAgl@QYy1X|T~D{HOyaS*Bh}A}S#a9MYS{XV{R-|niEB*W%GPW! zP^NU(L<}>Uab<;)#H)rYbnqt|dOK(-DCnY==%d~y(1*{D{Eo1cqIV8*iMfx&J*%yh zx=+WHjt0q2m*pLx8=--UqfM6ZWjkev>W-*}_*$Y(bikH`#-Gn#!6_ zIA&kxn;XYI;eN9yvqztK-a113A%97in5CL5Z&#VsQ4=fyf&3MeKu70)(x^z_uw*RG zo2Pv&+81u*DjMO6>Mrr7vKE2CONqR6C0(*;@4FBM;jPIiuTuhQ-0&C)JIzo_k>TaS zN_hB;_G=JJJvGGpB?uGgSeKaix~AkNtYky4P7GDTW6{rW{}V9K)Cn^vBYKe*OmP!; zohJs=l-0sv5&phSCi&8JSrokrKP$LVa!LbtlN#T^cedgH@ijt5T-Acxd9{fQY z4qsg1O{|U5Rzh_j;9QD(g*j+*=xULyi-FY|-mUXl7-2O`TYQny<@jSQ%^ye*VW_N< z4mmvhrDYBJ;QSoPvwgi<`7g*Pwg5ANA8i%Kum;<=i|4lwEdN+`)U3f2%bcRZRK!P z70kd~`b0vX=j20UM5rBO#$V~+grM)WRhmzb15ya^Vba{SlSB4Kn}zf#EmEEhGruj| zBn0T2n9G2_GZXnyHcFkUlzdRZEZ0m&bP-MxNr zd;kl7=@l^9TVrg;Y6J(%!p#NV*Lo}xV^Nz0#B*~XRk0K2hgu5;7R9}O=t+R(r_U%j z$`CgPL|7CPH&1cK5vnBo<1$P{WFp8#YUP%W)rS*a_s8kKE@5zdiAh*cjmLiiKVoWD z!y$@Cc5=Wj^VDr$!04FI#%pu6(a9 zM_FAE+?2tp2<$Sqp5VtADB>yY*cRR+{OeZ5g2zW=`>(tA~*-T)X|ahF{xQmypWp%2X{385+=0S|Jyf`XA-c7wAx`#5n2b-s*R>m zP30qtS8aUXa1%8KT8p{=(yEvm2Gvux5z22;isLuY5kN{IIGwYE1Pj);?AS@ex~FEt zQ`Gc|)o-eOyCams!|F0_;YF$nxcMl^+z0sSs@ry01hpsy3p<|xOliR zr-dxK0`DlAydK!br?|Xi(>buASy4@C8)ccRCJ3w;v&tA1WOCaieifLl#(J% zODPi5fr~ASdz$Hln~PVE6xekE{Xb286t(UtYhDWo8JWN6sNyRVkIvC$unIl8QMe@^ z;1c<0RO5~Jv@@gtDGPDOdqnECOurq@l02NC#N98-suyq_)k(`G=O`dJU8I8LcP!4z z8fkgqViqFbR+3IkwLa)^>Z@O{qxTLU63~^lod{@${q;-l?S|4Tq0)As-Gz!D(*P)Vf6wm6B8GGWi7B)Q^~T?sseZeI+}LyBAG!LRZn_ktDlht1j2ok@ljteyuNUkG67 zipkCx-7k(FZQhYjZ%T9X7`tO99$Wj~K`9r0IkWhPul`Q_t1YnVK=YI1dMc_b!FEU4 zkv=PGf{5$P#w{|m92tfVnsnfd%%KW;1a*cLmga4bSYl^*49M4cs+Fe>P!n=$G6hL6 z>IM&0+c(Nvr0I!5CGx7WK*Z3V^w0+QcF=hU0B4=+;=tn*+XDxKa;NB-z4O~I zf}TSb^Z;L_Og>!D1`;w@zf@GCqCUNY%N?IPmEkTco^}bX~BWM_Hamu05>#B zBh%QfUeHPu`MsYVQQ3hOT;HmP_C|nOl zjluk7vaSICyQ01h`^c)DWp>cxPjGEc6D^~2L79hyK_J#<9H#8o`&XM4=aB`@< z<|1oR6Djf))P1l2C{qSwa4u-&LDG{FLz#ym_@I+vo}D}#%;vNN%& zW&9||THv_^B!1Fo+$3A6hEAed$I-{a^6FVvwMtT~e%*&RvY5mj<@(-{y^xn6ZCYqNK|#v^xbWpy15YL18z#Y&5YwOnd!A*@>k^7CaX0~4*6QB{Bgh$KJqesFc(lSQ{iQAKY%Ge}2CeuFJ{4YmgrP(gpcH zXJQjSH^cw`Z0tV^axT&RkOBP2A~#fvmMFrL&mwdDn<*l3;3A425_lzHL`+6sT9LeY zu@TH0u4tj199jQBzz*~Up5)7=4OP%Ok{rxQYNb!hphAoW-BFJn>O=%ov*$ir?dIx% z56Y`>?(1YQ8Fc(D7pq2`9swz@*RIoTAvMT%CPbt;$P%eG(P%*ZMjklLoXqTE*Jg^T zlEQbMi@_E|ll_>pTJ!(-x41R}4sY<5A2VVQ^#4eE{imHt#NEi+#p#EBC2C=9B4A|n zqe03T*czDqQ-VxZ+jPQG!}!M0SlFm^@wTW?otBZ+q~xkk29u1i7Q|kaJ(9{AiP1`p zbEe5&!>V;1wnQ1-Qpyn2B5!S(lh=38hl6IilCC6n4|yz~q94S9_5+Od*$c)%r|)f~ z;^-lf=6POs>Ur4i-F>-wm;3(v7Y_itzt)*M!b~&oK%;re(p^>zS#QZ+Rt$T#Y%q1{ zx+?@~+FjR1MkGr~N`OYBSsVr}lcBZ+ij!0SY{^w((2&U*M`AcfSV9apro+J{>F&tX zT~e zMvsv$Q)AQl_~);g8OOt4plYESr8}9?T!yO(Wb?b~1n0^xVG;gAP}d}#%^9wqN7~F5 z!jWIpqxZ28LyT|UFH!u?V>F6&Hd~H|<(3w*o{Ps>G|4=z`Ws9oX5~)V=uc?Wmg6y< zJKnB4Opz^9v>vAI)ZLf2$pJdm>ZwOzCX@Yw0;-fqB}Ow+u`wglzwznQAP(xbs`fA7 zylmol=ea)g}&;8;)q0h7>xCJA+01w+RY`x`RO% z9g1`ypy?w-lF8e5xJXS4(I^=k1zA46V)=lkCv?k-3hR9q?oZPzwJl$yOHWeMc9wFuE6;SObNsmC4L6;eWPuAcfHoxd59gD7^Xsb$lS_@xI|S-gb? z*;u@#_|4vo*IUEL2Fxci+@yQY6<&t=oNcWTVtfi1Ltveqijf``a!Do0s5e#BEhn5C zBXCHZJY-?lZAEx>nv3k1lE=AN10vz!hpeUY9gy4Xuy940j#Rq^yH`H0W2SgXtn=X1 zV6cY>fVbQhGwQIaEG!O#p)aE8&{gAS z^oVa-0M`bG`0DE;mV)ATVNrt;?j-o*?Tdl=M&+WrW12B{+5Um)qKHd_HIv@xPE+;& zPI|zXfrErYzDD2mOhtrZLAQ zP#f9e!vqBSyoKZ#{n6R1MAW$n8wH~)P3L~CSeBrk4T0dzIp&g9^(_5zY*7$@l%%nL zG$Z}u8pu^Mw}%{_KDBaDjp$NWes|DGAn~WKg{Msbp*uPiH9V|tJ_pLQROQY?T0Pmt zs4^NBZbn7B^L%o#q!-`*+cicZS9Ycu+m)rDb98CJ+m1u}e5ccKwbc0|q)ICBEnLN# zV)8P1s;r@hE3sG2wID0@`M9XIn~hm+W1(scCZr^Vs)w4PKIW_qasyjbOBC`ixG8K$ z9xu^v(xNy4HV{wu2z-B87XG#yWu~B6@|*X#BhR!_jeF*DG@n_RupAvc{DsC3VCHT# za6Z&9k#<*y?O0UoK3MLlSX6wRh`q&E>DOZTG=zRxj0pR0c3vskjPOqkh9;o>a1>!P zxD|LU0qw6S4~iN8EIM2^$k72(=a6-Tk?%1uSj@0;u$0f*LhC%|mC`m`w#%W)IK zN_UvJkmzdP84ZV7CP|@k>j^ zPa%;PDu1TLyNvLQdo!i1XA|49nN}DuTho6=z>Vfduv@}mpM({Jh289V%W@9opFELb z?R}D#CqVew1@W=XY-SoMNul(J)zX(BFP?#@9x<&R!D1X&d|-P;VS5Gmd?Nvu$eRNM zG;u~o*~9&A2k&w}IX}@x>LMHv`ith+t6`uQGZP8JyVimg>d}n$0dDw$Av{?qU=vRq zU@e2worL8vTFtK@%pdbaGdUK*BEe$XE=pYxE_q{(hUR_Gzkn=c#==}ZS^C6fKBIfG z@hc);p+atn`3yrTY^x+<y`F0>p02jUL8cgLa|&yknDj;g73m&Sm&@ju91?uG*w?^d%Yap&d2Bp3v7KlQmh z(N<38o-iRk9*UV?wFirV>|46JqxOZ_o8xv_eJ1dv} zw&zDHZOU%`U{9ckU8DS$lB6J!B`JuThCnwKphODv`3bd?_=~tjNHstM>xoA53-p#F zLCVB^E`@r_D>yHLr10Sm4NRX8FQ+&zw)wt)VsPmLK|vLwB-}}jwEIE!5fLE;(~|DA ztMr8D0w^FPKp{trPYHXI7-;UJf;2+DOpHt%*qRgdWawy1qdsj%#7|aRSfRmaT=a1> zJ8U>fcn-W$l-~R3oikH+W$kRR&a$L!*HdKD_g}2eu*3p)twz`D+NbtVCD|-IQdJlFnZ0%@=!g`nRA(f!)EnC0 zm+420FOSRm?OJ;~8D2w5HD2m8iH|diz%%gCWR|EjYI^n7vRN@vcBrsyQ;zha15{uh zJ^HJ`lo+k&C~bcjhccoiB77-5=SS%s7UC*H!clrU$4QY@aPf<9 z0JGDeI(6S%|K-f@U#%SP`{>6NKP~I#&rSHBTUUvHn#ul4*A@BcRR`#yL%yfZj*$_% zAa$P%`!8xJp+N-Zy|yRT$gj#4->h+eV)-R6l}+)9_3lq*A6)zZ)bnogF9`5o!)ub3 zxCx|7GPCqJlnRVPb&!227Ok@-5N2Y6^j#uF6ihXjTRfbf&ZOP zVc$!`$ns;pPW_=n|8Kw4*2&qx+WMb9!DQ7lC1f@DZyr|zeQcC|B6ma*0}X%BSmFJ6 zeDNWGf=Pmmw5b{1)OZ6^CMK$kw2z*fqN+oup2J8E^)mHj?>nWhBIN|hm#Km4eMyL= zXRqzro9k7(ulJi5J^<`KHJAh-(@W=5x>9+YMFcx$6A5dP-5i6u!k*o-zD z37IkyZqjlNh*%-)rAQrCjJo)u9Hf9Yb1f3-#a=nY&M%a{t0g7w6>{AybZ9IY46i4+%^u zwq}TCN@~S>i7_2T>GdvrCkf&=-OvQV9V3$RR_Gk7$t}63L}Y6d_4l{3b#f9vup-7s z3yKz5)54OVLzH~Ty=HwVC=c$Tl=cvi1L?R>*#ki4t6pgqdB$sx6O(IIvYO8Q>&kq;c3Y-T?b z*6XAc?orv>?V7#vxmD7geKjf%v~%yjbp%^`%e>dw96!JAm4ybAJLo0+4=TB% zShgMl)@@lgdotD?C1Ok^o&hFRYfMbmlbfk677k%%Qy-BG3V9txEjZmK+QY5nlL2D$Wq~04&rwN`-ujpp)wUm5YQc}&tK#zUR zW?HbbHFfSDsT{Xh&RoKiGp)7WPX4 zD^3(}^!TS|hm?YC16YV59v9ir>ypihBLmr?LAY87PIHgRv*SS>FqZwNJKgf6hy8?9 zaGTxa*_r`ZhE|U9S*pn5Mngb7&%!as3%^ifE@zDvX`GP+=oz@p)rAl2KL}ZO1!-us zY`+7ln`|c!2=?tVsO{C}=``aibcdc1N#;c^$BfJr84=5DCy+OT4AB1BUWkDw1R$=FneVh*ajD&(j2IcWH8stMShVcMe zAi6d7p)>hgPJbcb(=NMw$Bo;gQ}3=hCQsi{6{2s~=ZEOizY(j{zYY-W8RiNjycv00 z8(JpE{}=CHx0ib3(nZgo776X=wBUbfk$y2r*}aNG@A0_zOa4k3?1EeH7Z43{@IP>{^M+M`M)0w*@Go z>kg~UfgP1{vH+IU(0p(VRVlLNMHN1C&3cFnp*}4d1a*kwHJL)rjf`Fi5z)#RGTr7E zOhWfTtQyCo&8_N(zIYEugQI}_k|2X(=dMA43Nt*e93&otv`ha-i;ACB$tIK% zRDOtU^1CD5>7?&Vbh<+cz)(CBM}@a)qZ^ld?uYfp3OjiZOCP7u6~H# zMU;=U=1&DQ9Qp|7j4qpN5Dr7sH(p^&Sqy|{uH)lIv3wk?xoVuN`ILg}HUCLs1Bp2^ za8&M?ZQVWFX>Rg4_i$C$U`89i6O(RmWQ4&O=?B6@6`a8fI)Q6q0t{&o%)|n7jN)7V z{S;u+{UzXnUJN}bCE&4u5wBxaFv7De0huAjhy#o~6NH&1X{OA4Y>v0$F-G*gZqFym zhTZ7~nfaMdN8I&2ri;fk*`LhES$vkyq-dBuRF!BC)q%;lt0`Z(*=Sl>uvU`LAvbyt zL1|M@Jas<@1hK!prK}$@&fbf70o7>3&CovCKi815v$6T7R&1GOG~R4pEu2B z%bxG{n`u$7ps(}Tt(P608J@{+>X(?=-j8CkF!T79c`1@E%?vOL%TYrMe1ozi<##IsIC1YRojP!gD%|+7|z^-Vj$a85gbmtB#unyoy%gw9m1yB z|L^-wylT%}=pNpq!QYz9zoV7>zM2g2d9lm{Q zP|dx3=De3NSNGuMWRdO_ctQJUud?_96HbrHiSKmp;{MHZhX#*L+^I11#r;grJ8_21 zt6b*wmCaAw(>A`ftjlL@vi06Z7xF<&xNOrTHrDeMHk*$$+pGK0p+|}H=Kgl{=naBy zclyQsRTraO4!uo})OTSp_x`^0jj7>|H=FOGnAbKT_LuSUiSd3QuCMq>sEhB=V63Nm zZxrtB0)U@x2A#VHqo2ab=pn~tu>kJ;TVASb_&ePAgVcic@>^YM?^LYRLr^O12>~45 z-EE?-Z$xjxsN92EaBi)~D~1OzRVH`o!)kYv7IIx??(B)>R|xa&(wmlU2gdV0+N+3% z7r$w5(L<|?@46ITJZS5koAELgVV_&KHj(9KG??A);@gL`s1th*c#t5>U(*+nb0+H% zOhJG5tth59%*>S~JIi%<0VAi;k>}&(Ojg!fyH0(fza!1kA~a}Vt{|3z{`Pt@VuYyB zFUt(kR$<`X_J&UQ%;ui2zob1!H{PL8X>>wbpGn~@&h__AfBit)4`D^#->1+Qn^MH9 zYD?%)Pa)D-xQzVGm!g)N$^_z`9)(>)gyQ+(7N@k4GO?~43wcE-|77;CPwPXHQcfcJ^I&IOOah zzL|dhoR*#m5sw{b&L=@<-30s9F|{@V05;4Wf6Z_1gpZnJ*SVN}3O7)-=yYuj2)O0d zX=I9TzzTK%QG&ujvS!F*aJ8eqt4|#VE;``yKqCx7#8QC7AmVn+zW9km3L5TN=R>{5 zLcW`6NKkTz`c{`-w!X9zMG;JZP|skLGs7qBHaWj7Ew!VR=`>n30NX)7j~-RbDmQ6b zHr)zVcn^~e2xqFCBG4P$ZCcRDml-&1^5fqN=CHgBVu1yTg32_N>tZ;N%h*TwOf^1lE#w1$yF$kXaP|V$2XuZ+3wH4Ws6%U;^iP|c6`#etHogQ+E@+~PZ1zdGAty6qTmBM z>!)Wfgq~%lD)m>avXMm)ReN}s9!T_>ic6xA|m7$(&n(Z&j} zHC=}~I(^-*PS2pc7%>)6w}F1il&p*0jX1z)jSvG%S{I3d9w$A|5;TS)4w81yzq5f8 zZVfF~`74m1KXQg|`OS>;FCgZw!AL;2PV{&8%~rG!;`eD=g!luE0k40GjIgjD!JSDNf$eW zZtPMF)&EH_#?IwVLEx&Tosh9K8Ln4Pb$`j2=><6MAezsQvhP#YNnw&cL>12xf)dPz z1tk;{SH6HDcbV0x(+5=2n;A->&iYDa5Zr9$&j?2iAz-(l1;#Vc3-ULyqRV9d0*psG7QHE! z*J=*^sKK?iTO$g*+j~C?QzzIu`6Z{2N-ANrd5*?o%x& z&WMin)$Wq%G!?{EH(2}A?Wx@ zn8|q7xPad4Gu>l^&SBl|mhUxp;S+Cb125`h5aBz9pM34$7n-GHGx*=yqAphZKkds7 z$=5Jnt*6&8@y80jNXm|>2IR<$D5frk;c2f5zLS5xe*^W>kkZa5R1+Am34;mo{Gr=Z zD=z8fgTHwx%)7hzjOo9*Cogbru8GgDzrE;3y%TR+u`|zz%c0Tyd8;#EQXdr4Rgx(2LPRzVI2FwsbXwnF;DP^fg zdYOd|zU&AqgCJ;R+?oSgEgZM`ZX>7&$A-j2m|Tcz4ictXoQkz6Tr<2zhOudU16k<7 zLdk&FCL>=a^>0gV@m#9SnMd)R$5&1mh8p2McnUbk;1|C;`7pPkYjf|o>|a6`x`z1O zt>8~Q%zHX%C=D2!;_1eo3qfbB4QQK^{ON_f*7XhLk{6sr2(KIVmax}fUtF-zHZiUd zHPb9jidV`dE;lsw?1uQH!b%MvPE|lh9-8R_z4^PC8{XAf?S73(n*FvYPoMES+LfOx zcjm4ZZOmKY>M2e${QBVT+XnBQ(oC0fAYcXi7+=}_!hS9m>Y%G@zxn3z#Pb;bJ~-kI zAHNmWgQJp$e8L-uKQ|c4B;#0BTsfRB+}pl7xe=2_1U7pahx5S$TVbRnU0oi1?Wh|A zR7ebg9TK1GgKa4@ic#q_*<;c8?CkjX zMMyq`J()_&(j-FZY7q%z6CN^a0%V{UL)jmrvEg{doZd?qIjgJ^UPr(QUs`68;qkdI zzj_XBQ|#K2U!5?fmIEtXX6^rFY;h4=Vx<-C(d;W6Bi_Xsg{ZJPL*K;I?5U$=V-BNP zn9pKiMc=hZNe**GZBw1kVs#-8c2ZRjol}}^V@^}BqY7c0=!mA;v0`d|(d;R-iT|GK z>zt>Tt3oV09%Y;^RM6=p9C-ys_a``HB_D-pnyX(CeA(GiJqx7xxFE52Y`j~iMv;sP z%jPmx#8p%5`flAU(b!c9XBvV+fygn`BP-C#lyRa;9%>YyW6~A_g?@2J+oY0HAg{qO znT4%ViCgw&eE=W8yt-0{cw`tMieWOG3wyNX#3a^qPhE8TH1?QhwhR~}Ic zZ^q$TF8$p0b0=L8aw&qaTjuAYPmr-6x;U*k*vRnOaBwb_( z5+ls5b(E!(71*l)M&(7ZEgBCtB{6Kh#ArV4u0iNnK!ml!nK5=3;9e76yD9oU4xTAK zPGsGkjtFMMY3pRP5u07;#af?b0C7u) zD^=9X@DRasHaf#c>4rF5GAT!Ggj0!7!z?Q-1_X6ZP2g|+?nVutp|rp}eFlKc8}Q&_ z17$NpDQvQolMWZfj0W0|WKm`nd_KXYH_#wRRzs1aRBYqo#feM}a?joONn30Z4Z9PG zg1c!_<52-9D53Wq4z8pUzGkEFm1@Ws(kp4}CO7csZ-7+b)^)M)(xo}_IpTLl7}5BmbBCI{4>rw>4c_gBQHtRd5Z=SW&6Qp2qMOjr3W+ZRmP;S(U+h=^BHKohhRp6Zgf zwt&$zQXhMm@kh1@SB%dIE*kFDZym3Mky$NRljX?}&JGK`PIV1C;Pf!JV{hb4y;Ju- zlpfEPUd+mV5XQH<#BRFhZ}>b#IdF?a?x;rBg-v)@fZpA?+J{3WZjbl3E zv(a&1=pGYPxP@K!6Qg5Vx=-jwc=BA{xL3+QWb&9~DGS1EFkIC+>55{dvY4LV@s5$C zKJmCjigp7?m27*GN_GROz}y+y5%iIj=*JTYccaFjvD&VN%ewfSp=0P zspdFfDqj?gs!N64cEy5uR~wD>af!1PE*xo{^a^8BPIL2=U>B!m2AM0Jf<8qWLoHxi zxQfkbbwkRXgJgLW_j{ZkCxHLBU{@D6T5u90UNs5P769Zei|C$@nA5$L$4ZvxQl1i? z8vLHg17}e{zM$=&h%8Swbfz7yw~X^N|7Chp1bC(oV72l#R8&%Ne5>F=7wR(dB; zkDX!%&fxS19JBjP<6H7+!dO`nPLvB~xn{aDh#^iHKP|A5UQlCG%v%x9@q1w2fa#&% za^UwHu!~(qrv99G%9_e4OBbJ-CkB*1M_?t6UXZ#}4JFDzB|x(1Z}ckuiY}${zj`eVo})!rN8Je z%h2CVJG1$K$2deXx^h8trLs~Han^e>_-M6@0o4C7d548|#mKtm@DvdVAX5ZzA8=*! zKq5C+cM9u)qJ%YBJ1UAcG}6Ji4=$piaZ(K@>1BiD;$R9bR*QP`dH2T=)dgW#f7U)S zZ~i#VYLOnUZt^~Iu3x8QPJaHVUxtRyipQ+tbmWKl14iW1!f6JSDvT$xt8>~7-1ZlJ zU|)Ab*lhvz-JO!$a}RBH9u8$=R)*qeD@iS@(px~OVvML-qqO5&Ujnhw1>G~**Ld{W zE+7h|!{rDZ#;ipZx4^Tcr9vnO)0>WFPzpFu*MYST(`GFzCq*@Gqse6VwDH#x?-{rs z+=dqd$W0*AuAEhzM@GC&!oZa1*lRsx>>mP>DNYigdm^A~xzo}=uV$w#iadO+!&q_~ zT>AsHXOEGsNyfcJt2V$rhGxaIcTEvZr7CMVEu=>l30N~52^71U^<_uw6h@v@`BA2! z)ViU+wF#^$=5o44TpOj?#eyq*+A&c0ghrt8%}SiK)FgLk-;-^+ zXt|1}1vcKAAuR|?L*a8;04p%!M~U2~UC-OJK)DMtBQ#+ZttJgDFNA4zchA*T)cN(E zmpIMLU*c*NrCSV^qdLXD751DsO`#V#K1BVX4qI-B3Rg(zcvlg^mgY^V3Q*5RRQ4-8 z_kAlUisma2SNEx47euK5Y#eu_-gwRW0}M90hEI}eIJ9aU?t11^jSCn4>e~XLSF7Y3 z7JF)1ZbS_P<$<#y(*u@w!jF4FW_f~bxzi%cgP~B1K5N6GFYSAf=D_s5XomU0G9I%Y zPWc{&MItPR#^Le)?zsRkQMmHx^Cnn&;TrPzRVG`wyNH*U;|r3^2NY(z0lwikP}cWF z`p%R@?dy*7H~0&3ST>L9)b7#kwg+|n0#E&-FNf+Z_t7tpa711FogBPV`S3MW_FMGQ zJ@8Z}qXR4-l%p76mvcH`{Fu(^O;8H2@#LZUH#9p6!EX$AEYV$c`s zkPimL3kv>y=WQ+?KIAuim``%cAeBhA6g8}p_*FBH(#{vKi)CIz_D)DFXPql*ccC}O zRW;+Y6V@=&*d6QJUbRxPX+-_24tc-hYHEFaP-IAj*|-P5%xbWujQvu#TF>xigr_r! znuu7b(!PyYX=O#>;+0cGRx>Sy39(3y=TCf_BZ$<%m#inup$>o(3dA1Byfsip8S975-iVe7UklFm|$4&kaJ!n66_k-7-k}Z_?){LQe&wTeJ^CR{u6p+U#4_iSZZ1wjB-1gVGNQqnkk*-wFLj(eK8Ut{waU zb1jwb2I?Wg&98jSQWom8c?2>BWt*!3WQ?>fB$KguB9_sStno%x=JXPEFrT|hh~Po2 zSPzu3IL10O?9U(3{X8OLN-!l6DJVtgr$yYXeAPh~%(FECDe;$mIY7R4Miv1GEFk9x zpw`}E5M)qTr60D^;a#OCd0xP*w8y+my1^l8Qd*V`wLoj)GFFj;;esW2PMO=sbas{yX6asXIJ$|LW< zts$A+JaxoM({kv+2d@#bhl?#V#FZn_=8tTTvup?Vq!p!46W{be)EP=VlYE|UzAU}) zz})UzJVWi;9br0k&5>}sqwa_`TP*c}^$9+q)Dks#qEVg>p)71sqKF-YLP@UF{(>lp7;CHAWK;K0TZ_+?>EtZKprfU@;52a1IU8HNx-mnoZrb8| zP8FPb#T$0VE+G-l508;d{DSfC6#dbp(j|^i^I3z9?Qmkr+(dw^w??h}WTN{_ls-GuE~lF;1Urgbtq|Ud_r>wecb@?{{z? zX>X$&Ud+(I(5}5d^>&Z2m+qy=h#vR*lS084ATwUWZLg6PX1Ft+YI`0iI)ynij}{4X zrQE!Mr1m^-?kw<|VT0mG+5J{!;j;zJT`?_=P*09n+=e``CN|7rC$u~Ksg7LSMS(Q~ z51!n1htcK0q7*K-*u0?c8ZlvPXcNwXmFe0Or2}}R@?j@{ECCNZ6va1tZ>|ZOgGZ1j z9?mRkeSK%{X4O>J$@hyFsD)7s67Uldb>O93wQQiV%-FfbEY_@q>1VUstIJs|QgB`o1z**F#s z^joAYN~5{EQ_wZ~R6-nEV#HsQbNU59dT;G zovb$}pb=LdR^{W2Nh~8yWfq*vC_DvJxM=)2N`5x+N6Sl`3{Wl@$*BYol#0^idTuM` zJ=prt$REkxn6%dimg%99{(Dt6D67sTUR6l1F@9&Z9<)XgWK#x zVohUH6>_xRuw1^V**+BCZ@dZj97T*67OBO>6UUivH`<@ray~ym^E?bO=vKqFfK3Kv z`RKxs4raHacB<(XAeH`@0G*K2@ill_U@m=icT@F{k1PU3j4VBde`ThtW8%Z~A>)45ARjQCDXbH}_rS^IxHGp#utBEj3W3KSAU+$6I4s~9OWueETo!J-f~+DV8< z+VMtdcQ?M+?S}kl&uImYiIUJ-K0-te7W4sdWpS6Fqs-I!Tj{8Qp6lMn$Zm8uU)s{X z8|O}HN%8sEl4em&qv{VBq{}$@cCG{B z5~3DY$WRYSkO~z=sxRct5^G5bPZW;LF)(zY)HREgpRrkYV@H3^BTD6u+bJE~$cqr< zw@Gb3^|n*kHZ%Vnu6~B7pB4iM0C4kDuk8Q1R^<(x%>|sCOl%CTe^N)K?Tiepg?|#m z94!og0*38u|67h%*!)SJhUdvFimsktaqp#im9IpH-$fQc79gi259qPkEZ)XU?2uWW zRg?$8`vl;V%-Tk+rwpTGaxy)h%3AmF^78<#i+Q6~M4#>J4`NNEEzy~xZ&O*9q%}@7 zs9XBO#vSKSM<-OjPIDzO9JiAYFWrK14Am{uZT=S3zaCu~K%kZo&u*=k9L#xi6vyaG zQFD76MOE&=c1G;7Zivp<%%fRq+@3wgZg>k@AYQf|*Qyzy$tqc20m?F5nGbG@V#gW` z8RMb2oBxgiqa?)_G6&-;L#(HCoaJrs_ED{IUZ^$~)+e#0iZT!AJDb2V{Sen*70TO& zyI`*~#ZdLFhYP_#DTuoqQ0OS6j0o15r{}O&YoT5wCp|x_dD{#Y;Y}0P1ta?2VEh4* ztrRN5tL6UvoH@M9L z=%FKpf@iSp2P>C(*o<-Ng4qF#A?i!AxjXLG8%Gm`$rZxw;ZqSvv5@@sZ|N*~do5fb zKWR)T_>`kxaS|MHFh`-`fc`C%=i@EFk$O&)*_OVrgP4MWsZkE2RJB(WC>w}him zb3KV>1I&nHP9};o8Kw-K$wF8`(R?UMzNB22kSIn#dEe|V-CuMw8I7|#`qSB6dpYg$ zoaDHj%zV6*;`u`VVdsTBKv&g75Q`68rdQU6O>_wkMT9d!z@)q2E)R3(j$*C4jp$Fo z2pE>*ih{4Xzh}W+5!Qw)#M*^E(0X-6-!%wj@4*^)8F=N*0Y5Or+>d= zhMNs@R~>R9;KmyP@I@bpU3&w?)jj0rGrb@q)P>wLVbz1!TZY$#+H-mK6B^0{vdvt0 zaJ0~7p%I#1PpPm1DvBzh7*UsCl^I5^`@XzPzbg+v3T_WyKN?TJ9J=57v^IUO`aQN} z@>Y>WIj+gT@-sobU-tW%L5GP(qY?Eep&I;@osY}O*3i1Ar?Sv|EI6S-pK_!~*A$K| zs-hHESqd`vv;zIzgv2ho5-hsIL5Ke~siJ(v0`Qm7W_Rms2rB67=p&HGRhA-)$p-BS zvXSmgGIGgeJMBcsgp=L8U3Ep$VPBFhvJ!3M5{pocGBS~iZj0({9Jt9nbC{Z$LVb%= zGqzRBjlqkAU{#sOX56})^QjX;jQ26M`poAFIZ#H31td9sQlgBBrfIYgDC9+kO~}s{ zb1i*{#{5tPWhv4pecAZygXG>?5xKx7iPXd?nR;QaIfhlhqNBaLDy>9Yd1Sf3P!s4~ zhfHaFGsIFy&ZM=6^qc>>V>o!zk%5Lk5BtS7oU=YfjWUN;c zrh$6Cyr%KC@QNTzTZvb)QXQkV)01MEY+EzC%CJx)Q&6MM={paB}Dp=qCn^eJ}5LeXG9Gqynt0ir>DvSIZ=i?*_xR3=% zppf1w51ypF2KL6ug zCm}eCi>&>xT;Idzh^PmtDWrU(&eC2hAt(nmd#?;W)*&4lb2Z2Ykv*XLNDEm`_1n3C z`l!wZwiF9b?mN@z?s~>v%hT01C{E3md6M5_Xi3fKD6s26Tt~Z>8|~Ao9ds!cF_Y1| zRG>!=TD0k0`|T*)oX!SlSt8g4Uh@nc(QosCoen@i*ZCSyh|IliliuhEw$8?4ZL9N2 zMQ%%S=3Tj_QilhHW@cSr1UYTtDem{A-ZxyCa$K9A%(!`X_?ieJzXbfERST|JxqmbL zHe!hSqYk|!=!$8CJ5>q}Pj63@Q#PO{gpVb+0-qHFM`j5x_s#~dxvy5u62vywq8upP z_)N)3n9cn7YEf2D8L}x0#_B_~>HT8;;8JC5q+}1gEyd%XqYvY?deQzwD1Lx{ghI3; zv?f;&6CY$H&dDL$k#)hb)5lIqUZ~oU!z)hMI!B9THhw?9!}ykqpFJ|hB?JjV9uwqb z3_70pMV^C7I<3Cg&yMi8JJ3V2gYTOMV=IopfZ#1o>&+j-mB-V${Ok(f?I3{+vR~zE_RR$?9xI~^% z53~ z&bCl+6UeKkUWJ-%mnK{9K>?(3BM3C`@xi}v8)q#;YJhMr5dWvMtAL7X``!bHv~(%m zH8d#Q4N6G~lEW}aGn9ZZNT?v9bV$emf)dg#ASDV?(nu+wpu!_X;(vL<<1zBo-~X&N z>keyizVGaP&c65DbIyEwFn2%(L`P424ZI3nFBA%w{yJ?E} zlwSKF;jIhs(!TFOdMUW|(=qHjr#U-k>`>1u1_yL5Gyy;7@WTOt_)nfIp{D9kwR8f0 z;^Fq=iF(&yd|z30&+I`FBM-P6ouHQ@96TkIe@9=pDDL#_zgXos)-ri5lX-&2D~DsI z4R>xVM$c&aFLgFjwq{1I;jpODOx|n*#@e2+Wgdkm(E(Fad_)peD`1^CJ2TpglmgoC)F(Z)F7y2rzzDU^4wvO{bzw{mzSs4tF;*qabKkC?D!j!tbF z4D_6zbqFVI>n@2-Qmg1BiDdD}>E(72)aMv1Y9duOxwlG|E!L(QmQ#j5vmN@a7v{zIt3qQSP?96^$ITE=h~sLn|N|v8YqmA~-0HWgcPHZ@!3Dzm2X{Bozc{qm>J`Ehp}`FQ%Ecbw%+|H8f`pykvo-%&0a z?&ZtJF*{#AYs8Z|z(IFI8sBiZs)L!C9#1W@;hEInZZZdPz2ZnmhoSP9VHQt7mzZUZ zhM!!5IJbe4Z@zEoMjKaxH&Px8p}1<0YmtWwcG@ZPY@*oQSteU zRy+W=Rs>sJ##v^8EJJt0=5---o<@^?fOEp=N<~xXvcf?$gXD0zVHziRMMmC#Mp3o ze(eT!dvjmXp9_C%pV_>{H=nsqYO)n1J?Ihi zjy7f00`|S<;)I!ZyUO{~#+wXX)z(BWsN|$7n9s}H%ZzE8YQv#vRTHjq@D%tYyfe=3)|7jYxRT#E16nFk&1jFC6CH5d4kiJCVq+%r_$Rec7=G!GuZ-0*$5N2GqXB(dqWPS1Um4{xgi2k=;eO_LDy&GR=Q!)bjKY{f!0yoc0Rol&!E`2BkI$5y4U^*k0=GyL-m8XJL%8prM%;fwyX9M^ zs48n3Oh#a>FVWI7dsm~*l0$^J)lxnfTTw~1ceZ73yNvNurwd`;+^1XuucaFN85M8? z$fNl!D9g*O>6IE^POaoDq`86Sw0t4%jIi`&*EEZI?wwOiEvH8(qpfyDvAe`4pWf7k z3-pFgeT{qtj)B!1ZamZ5g3z6Nd40P(%^Kf@#!uzbIk~8w`9wbhWc~1E|sw6-FsOqrhb2DLDwlaq@)Y zAi$KoA=Vyn=Yxqxtf7wu*$47Ht>WZi{AdeN79#9ws~CtE;~gC$q7T>*5yKK3VT)Q=sllRR}lBIGd17+bOu| zeUeUrMgF=Gjk-{epAyUd_KNgwZK_Pz=H$+{4~E_ZRa3IJpU~IZ5U4Z3l%u3{Ls~`H z(iysmm+!HBJTC-$EpHM9yrXUM^_FZ(3sdmsyZ6=lU8bb3V(WK>P0$l~#QA&NMj@OA z*OQ>^-s_D-bda022~!G!bTh7@FR>t!1r`Js1;4$(^_*hH-_pUPf5C}K-v$%i#KBB! zU{~a7)R>ix z#LA|<6v#rwKkB1JBLWkWu#M0#8i1J0e4dFDP3jrlFfxhkDs%Q~)e6e7fR$U?e$<{x zfZb0?UMsB|E}Fk)@|^{)_^L7O%rp1GRNig@bUX(^6}6HoGi8IXoSKpI1A(GV)uA=7 zOXG&KjZYVjYn6}2YV0yfnKsnpDlF)h$Gv--|6$BsWFg|IWnp|#sk}zOAb6Bb?vb@t zs^7=4IdiKE_rUT@rG!D4Zy zcnas#XT77V&%igMXY(lQS|)lgO{pN9!P-94KeZH_+PK5jESYCSPMN)=D(JIAVeB%D zI_>_lvD;pylkZ#Ral0IzC6ei$J$4NnGw(pnVd`&aaNT5mfq-4)aPjj(v;`VvJ6Xxjm@3DX+Kju z@9-h++s7x>idTEL zd)ptYy?P2$S*_DI;eMR0ZdAuS)~fGEZEguO&+3AwW@Sw$&KvgJr6aGK*Ar;0wx`lr z7V&!+9C7`VcV^t+Wj~AweOGQL!)0)serr$8Fez7kC(VSVRdjqpQuq964RW^2euIre zh10&Tv)|dj*CoRozrW<4y_+5}3EGRok+G7ODl3-CF1r?JYDdw&NbcVT=7ljq_K+8bMeG3uRw@3=cof?j+v+WaKI`WqwByf#7aFK3 z0+R34xQ-6nxQ&9xJKl}`C9FlUe1-h^i?5fr5kjot#MA-$%k106t>*gM+yF3m2X#=1tt07`cK)37dA^A4d8%6R>@0U-UZ~wSvzMlK$tlm~aK`%e8|quXyH`aLM0#Dcu%sqEsKV%i zVn_*W-Qbnl)h?RP>)$rZ5JL!*H;Z{ zk7(FB`lo~h&zB|S6j-Na;y$QM*rn^tkO{>#DWZN@IwJps3*Nm&ox0{{;=J~hvPb-* zvAOEPImrdq()yl~`j`Q;R1Y%CdLKKw*;gtNaM~WDO95YXsTjKCOdRD2Is@aVRTYFD zpS=_EB!@Ub&c*JmNMF=F+)Bq)52|=83IEG;M5(Ol*97!W(S-5X-5w&7->`1Pw-0Ml zpA>jaofnyPQTCzoIG}OK9j^nn>F>jC#$iSnJY8y6ue4nxs@3HtfNx01XVK7NcX#Cu z34g-z=0!7ip&@wI>>6ynJYyFTEgH6DA?b>~V%2s_@NPDza5&6cno!S(|85*74}6_M z%s1c4`B{lqMu``(4~Jk#_`^=tu36TgXPv_}{lhhyi(rrSM_uoVVNuZOuxCXom9|wg zNf&BtzX=hVi*4dG&1J!^QW;O%fQ$jVH=W74B8WR)*tM1{(@cHRqiS_W6R^h8uxd@zV>KNI zR(-LNNkLqh>e=CmL|q9sRHm#15%q$o7_GQMp8FLX-HGnJ<+(;k{Q%+Sk+!^mM+2#1y9+gG2IDZGt%;Cfk{+ zT5}^x=!i2$tnH_se6eC zkn;kK>%ICpo=X&=cSsbxQ|AjJ;5Ff;AyIj>$YA8cw*?W^Nn}S|1jrbf@Bd zr82I8KlOh4#5C0sw3oVvuC0NFPKH4S0$~F$U4JM1Im$B%%oGm_5$Lnr{#Pv}eL1k& zMP(pG$MI^8&!nYffq#$zJ^3GF|cC%2d4V@qKV#fu6u2O

k)oKu82Fu=RODzQrHPEC+Mz{hW(G7VuCl8g1ou-Ot!41bp_>OC1&@A_6e*hc)1X zMuDvzEZyB*fW1^+7dL0%ofr;-xT6B@0~|VazatI{60!X=po^uOr6UB$1POKmuI_&b zOL&O+w*!>`k+y%?Z|wm4$@_1|WC|pKM(F{k8TR$-4hs?i|GBc9)qa{vYq)~5qa(2N zsR?s}0Pp^ufVGEB8oE9VCFa0K$x0HSpem!tIyR69y0rnjg8cqjmWyz7*Kx3~X> z|BZX}Y;oVB1HX@l9_-y7dI*WgruY@?rC&64`}3W`ECA>O@Y#Q@JS<4WBF(QbwJqHM zt)fE#6jTSyZ^E8y0INaIf!omWjvS=@15`O%V2CKg+}z=M9##kLKRN0uJuK250bXVU zwzT&n@30^dzKnlL^us;wClg?CKWEtiEb#zhPVx{PxFQiwEPp^C53zN21EdZAz?3D& zC6fK|_!S5Mq&0z;xWGLEv}!zjfpRg_orp7|fXMx=uP!@X`yT@5(N_Hza}p5fBk&|)J7fZ`NQ9Nz@5xT? zi?iV$q+bG!2LZUpF)>Yl!u;DEHV3!i{ipcJm_8Gj@Dac%N3|SQVGqRhrJ;WOR|CtrwzPTW^&$A6!A$E)h7xohm>hA8p{PUZ~ z_&zeg@OL3PxPtzkfsNZAqXCZ8Is7yQ+plm~8;}|~DEkv&f@?q5hB*OGQYXuwVQOp0 z?QQ`6qyp|-$47wjuV74IE_x2I17$+grwMBE^25d<5!lYhnszuh|5Yk;RB+Uk*hk=m zu73=E^7ul{40{A^?Rg^fq0ZfZO@C1HupR*_d;J>lkFv6&x&}4N;t}1T@2}~AC^<3b zA}RxFPPZe5R{_6dIN9N-GT29Oa}RzA2ekKuEVZbuMOB?Xf**`N5&m}?)TjigdY(rF z?~+a=`0);TlDa1j)1G`AfW? zRl883QPq=w zbB|bHEx%_u*$t@Yl#Vc;y*?2W^|^NJ)DmioQFr~1&>MSBL_b(YIpGWdDm3bT=Mgm1 e+h0K+-~H6qzyuy}`;+tYAZFmzUSVSYum1yJqxCBQ diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 3499ded..37f853b 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,7 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip networkTimeout=10000 +validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists diff --git a/gradlew b/gradlew index aeb74cb..1aa94a4 100755 --- a/gradlew +++ b/gradlew @@ -83,7 +83,8 @@ done # This is normally unused # shellcheck disable=SC2034 APP_BASE_NAME=${0##*/} -APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit +# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036) +APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit # Use the maximum available, or set MAX_FD != -1 to use that value. MAX_FD=maximum @@ -130,10 +131,13 @@ location of your Java installation." fi else JAVACMD=java - which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + if ! command -v java >/dev/null 2>&1 + then + die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. Please set the JAVA_HOME variable in your environment to match the location of your Java installation." + fi fi # Increase the maximum file descriptors if we can. @@ -141,7 +145,7 @@ if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then case $MAX_FD in #( max*) # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked. - # shellcheck disable=SC3045 + # shellcheck disable=SC2039,SC3045 MAX_FD=$( ulimit -H -n ) || warn "Could not query maximum file descriptor limit" esac @@ -149,7 +153,7 @@ if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then '' | soft) :;; #( *) # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked. - # shellcheck disable=SC3045 + # shellcheck disable=SC2039,SC3045 ulimit -n "$MAX_FD" || warn "Could not set maximum file descriptor limit to $MAX_FD" esac @@ -198,11 +202,11 @@ fi # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' -# Collect all arguments for the java command; -# * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of -# shell script including quotes and variable substitutions, so put them in -# double quotes to make sure that they get re-expanded; and -# * put everything else in single quotes, so that it's not re-expanded. +# Collect all arguments for the java command: +# * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, +# and any embedded shellness will be escaped. +# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be +# treated as '${Hostname}' itself on the command line. set -- \ "-Dorg.gradle.appname=$APP_BASE_NAME" \ diff --git a/java-gtk/build.gradle.kts b/java-gtk/build.gradle.kts index cf22280..d8c2a78 100644 --- a/java-gtk/build.gradle.kts +++ b/java-gtk/build.gradle.kts @@ -50,16 +50,20 @@ dependencies { } -tasks.test { - useJUnitPlatform() +testing { + suites { + val test by getting(JvmTestSuite::class) { + useJUnitJupiter() + } + } } - /** add generated code and C library to source set **/ sourceSets { main { java { - val src = File(project(":java-gtk").buildDir,"generated/src/main/java") + val buildDir = layout.buildDirectory.get().asFile + val src = File(buildDir, "generated/src/main/java") srcDir(src) } } From 09d2271d115cf71f9ed1d360b412bed30570c664 Mon Sep 17 00:00:00 2001 From: bailuk Date: Mon, 17 Mar 2025 16:54:25 +0100 Subject: [PATCH 3/5] Update dependencies --- CHANGELOG.md | 6 ++++++ generator/build.gradle.kts | 5 +++-- java-gtk/build.gradle.kts | 11 ++++++----- 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 62c89c4..0371baa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,13 @@ - Generator: Add markdown summary logs - Generator: Add gstreamer support +- Generator: Update Kotlin to 2.1.10 - Library: Add PropertyHolder to accesss GObject properties +- Library: Update findbugs to spotbugs-annotations:4.9.3 +- Library: Update jna to 5.17.0 +- CI: Update gradle to version 8.13 +- CI: Update release plugin to version 1.18.18 +- CI: Update JUnit to 5.12.1 # 0.5.0 diff --git a/generator/build.gradle.kts b/generator/build.gradle.kts index be22d24..2a0b5cb 100644 --- a/generator/build.gradle.kts +++ b/generator/build.gradle.kts @@ -3,7 +3,7 @@ plugins { java // https://kotlinlang.org/docs/gradle-configure-project.html - kotlin("jvm") version "1.9.22" + kotlin("jvm") version "2.1.10" } repositories { @@ -11,7 +11,8 @@ repositories { } dependencies { - testImplementation("org.junit.jupiter:junit-jupiter:5.10.2") + // https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter + testImplementation("org.junit.jupiter:junit-jupiter:5.12.1") // https://mvnrepository.com/artifact/net.sf.kxml/kxml2 // xml parser implementation diff --git a/java-gtk/build.gradle.kts b/java-gtk/build.gradle.kts index d8c2a78..a2d655b 100644 --- a/java-gtk/build.gradle.kts +++ b/java-gtk/build.gradle.kts @@ -38,15 +38,16 @@ repositories { dependencies { // implementation of javax.annotation:javax.annotation-api - // https://mvnrepository.com/artifact/com.google.code.findbugs/jsr305 - api("com.google.code.findbugs:jsr305:3.0.2") + // https://mvnrepository.com/artifact/com.github.spotbugs/spotbugs-annotations + api("com.github.spotbugs:spotbugs-annotations:4.9.3") + // https://github.com/java-native-access/jna // https://mvnrepository.com/artifact/net.java.dev.jna/jna - api("net.java.dev.jna:jna:5.13.0") + api("net.java.dev.jna:jna:5.17.0") - //https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter-api - testImplementation("org.junit.jupiter:junit-jupiter:5.9.2") + // https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter-api + testImplementation("org.junit.jupiter:junit-jupiter:5.12.1") } From b91b8c9b18c9287412f2aa9acc42444c74d46122 Mon Sep 17 00:00:00 2001 From: bailuk Date: Mon, 17 Mar 2025 17:10:24 +0100 Subject: [PATCH 4/5] Update gir files (sync with debian testing) --- doc/gen/alias_table.md | 1 - doc/gen/callback_table.md | 19 + doc/gen/enum_table.md | 82 +- doc/gen/structure_table.md | 128 +- generator/src/main/resources/gir/Adw-1.gir | 64194 ++++++++------ generator/src/main/resources/gir/GLib-2.0.gir | 56391 ++++++------ .../src/main/resources/gir/GObject-2.0.gir | 16202 ++-- generator/src/main/resources/gir/Gdk-4.0.gir | 15714 ++-- .../src/main/resources/gir/GdkPixbuf-2.0.gir | 63 +- .../src/main/resources/gir/Geoclue-2.0.gir | 265 +- generator/src/main/resources/gir/Gio-2.0.gir | 70772 +++++++++------- generator/src/main/resources/gir/Gsk-4.0.gir | 8875 +- generator/src/main/resources/gir/Gst-1.0.gir | 18323 ++-- generator/src/main/resources/gir/Gtk-4.0.gir | 42683 +++++----- .../src/main/resources/gir/Pango-1.0.gir | 3051 +- 15 files changed, 169460 insertions(+), 127303 deletions(-) diff --git a/doc/gen/alias_table.md b/doc/gen/alias_table.md index ffd312d..03a6788 100644 --- a/doc/gen/alias_table.md +++ b/doc/gen/alias_table.md @@ -9,7 +9,6 @@ | glib.Quark | glib.guint32 | pango.LayoutRun | pango.GlyphItem | gst.ElementFactoryListType | gst.guint64 -| glib.Type | glib.gsize | gst.MemoryMapInfo | gst.MapInfo | gobject.Type | gobject.gsize | gst.ClockTimeDiff | gst.gint64 diff --git a/doc/gen/callback_table.md b/doc/gen/callback_table.md index 770a130..e6c4635 100644 --- a/doc/gen/callback_table.md +++ b/doc/gen/callback_table.md @@ -73,6 +73,7 @@ | MetaInitFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):MetaInitFunction:(ParameterTag:Meta:GstMeta*:):(ParameterTag:gpointer:gpointer:):(ParameterTag:Buffer:GstBuffer*:)) | BufferForeachMetaFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):BufferForeachMetaFunc:(ParameterTag:Buffer:GstBuffer*:):(ParameterTag:Meta:GstMeta**:):(ParameterTag:gpointer:gpointer:)) | CapsFilterMapFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):CapsFilterMapFunc:(ParameterTag:CapsFeatures:GstCapsFeatures*:):(ParameterTag:Structure:GstStructure*:):(ParameterTag:gpointer:gpointer:)) +| MetaSerializeFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):MetaSerializeFunction:(ParameterTag:Meta:const GstMeta*:):(ParameterTag:ByteArrayInterface:GstByteArrayInterface*:):(ParameterTag:guint8:guint8*:)) | PadActivateFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):PadActivateFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:)) | ValueSerializeFunc | (CallbackTag:(ParameterTag:utf8:gchar*:):ValueSerializeFunc:(ParameterTag:GObject.Value:const GValue*:)) | TaskThreadFunc | (CallbackTag:(ParameterTag:none:void:):TaskThreadFunc:(ParameterTag:Task:GstTask*:):(ParameterTag:GLib.Thread:GThread*:):(ParameterTag:gpointer:gpointer:)) @@ -92,6 +93,8 @@ | MiniObjectDisposeFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):MiniObjectDisposeFunction:(ParameterTag:MiniObject:GstMiniObject*:)) | PadProbeCallback | (CallbackTag:(ParameterTag:PadProbeReturn:GstPadProbeReturn:):PadProbeCallback:(ParameterTag:Pad:GstPad*:):(ParameterTag:PadProbeInfo:GstPadProbeInfo*:):(ParameterTag:gpointer:gpointer:)) | CapsMapFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):CapsMapFunc:(ParameterTag:CapsFeatures:GstCapsFeatures*:):(ParameterTag:Structure:GstStructure*:):(ParameterTag:gpointer:gpointer:)) +| MetaClearFunction | (CallbackTag:(ParameterTag:none:void:):MetaClearFunction:(ParameterTag:Buffer:GstBuffer*:):(ParameterTag:Meta:GstMeta*:)) +| MetaDeserializeFunction | (CallbackTag:(ParameterTag:Meta:GstMeta*:):MetaDeserializeFunction:(ParameterTag:MetaInfo:const GstMetaInfo*:):(ParameterTag:Buffer:GstBuffer*:):(ParameterTag:guint8:const guint8*:):(ParameterTag:gsize:gsize:):(ParameterTag:guint8:guint8:)) | TagMergeFunc | (CallbackTag:(ParameterTag:none:void:):TagMergeFunc:(ParameterTag:GObject.Value:GValue*:):(ParameterTag:GObject.Value:const GValue*:)) | TaskFunction | (CallbackTag:(ParameterTag:none:void:):TaskFunction:(ParameterTag:gpointer:gpointer:)) | TaskPoolFunction | (CallbackTag:(ParameterTag:none:void:):TaskPoolFunction:(ParameterTag:gpointer:void*:)) @@ -100,6 +103,7 @@ | IteratorNextFunction | (CallbackTag:(ParameterTag:IteratorResult:GstIteratorResult:):IteratorNextFunction:(ParameterTag:Iterator:GstIterator*:):(ParameterTag:GObject.Value:GValue*:)) | PadChainFunction | (CallbackTag:(ParameterTag:FlowReturn:GstFlowReturn:):PadChainFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:):(ParameterTag:Buffer:GstBuffer*:)) | MemoryMapFunction | (CallbackTag:(ParameterTag:gpointer:gpointer:):MemoryMapFunction:(ParameterTag:Memory:GstMemory*:):(ParameterTag:gsize:gsize:):(ParameterTag:MapFlags:GstMapFlags:)) +| StructureForeachIdStrFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):StructureForeachIdStrFunc:(ParameterTag:IdStr:const GstIdStr*:):(ParameterTag:GObject.Value:const GValue*:):(ParameterTag:gpointer:gpointer:)) | PadChainListFunction | (CallbackTag:(ParameterTag:FlowReturn:GstFlowReturn:):PadChainListFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:):(ParameterTag:BufferList:GstBufferList*:)) | PadGetRangeFunction | (CallbackTag:(ParameterTag:FlowReturn:GstFlowReturn:):PadGetRangeFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:):(ParameterTag:guint64:guint64:):(ParameterTag:guint:guint:):(ParameterTag:Buffer:GstBuffer**:)) | PluginInitFullFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):PluginInitFullFunc:(ParameterTag:Plugin:GstPlugin*:):(ParameterTag:gpointer:gpointer:)) @@ -111,6 +115,7 @@ | ValueCompareFunc | (CallbackTag:(ParameterTag:gint:gint:):ValueCompareFunc:(ParameterTag:GObject.Value:const GValue*:):(ParameterTag:GObject.Value:const GValue*:)) | ValueDeserializeFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):ValueDeserializeFunc:(ParameterTag:GObject.Value:GValue*:):(ParameterTag:utf8:const gchar*:)) | TagForeachFunc | (CallbackTag:(ParameterTag:none:void:):TagForeachFunc:(ParameterTag:TagList:const GstTagList*:):(ParameterTag:utf8:const gchar*:):(ParameterTag:gpointer:gpointer:)) +| StructureFilterMapIdStrFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):StructureFilterMapIdStrFunc:(ParameterTag:IdStr:const GstIdStr*:):(ParameterTag:GObject.Value:GValue*:):(ParameterTag:gpointer:gpointer:)) | PadUnlinkFunction | (CallbackTag:(ParameterTag:none:void:):PadUnlinkFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:)) | StructureMapFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):StructureMapFunc:(ParameterTag:GLib.Quark:GQuark:):(ParameterTag:GObject.Value:GValue*:):(ParameterTag:gpointer:gpointer:)) | ElementCallAsyncFunc | (CallbackTag:(ParameterTag:none:void:):ElementCallAsyncFunc:(ParameterTag:Element:GstElement*:):(ParameterTag:gpointer:gpointer:)) @@ -118,6 +123,7 @@ | IteratorResyncFunction | (CallbackTag:(ParameterTag:none:void:):IteratorResyncFunction:(ParameterTag:Iterator:GstIterator*:)) | PadStickyEventsForeachFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):PadStickyEventsForeachFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Event:GstEvent**:):(ParameterTag:gpointer:gpointer:)) | PadEventFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):PadEventFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:):(ParameterTag:Event:GstEvent*:)) +| StructureMapIdStrFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):StructureMapIdStrFunc:(ParameterTag:IdStr:const GstIdStr*:):(ParameterTag:GObject.Value:GValue*:):(ParameterTag:gpointer:gpointer:)) | IteratorForeachFunction | (CallbackTag:(ParameterTag:none:void:):IteratorForeachFunction:(ParameterTag:GObject.Value:const GValue*:):(ParameterTag:gpointer:gpointer:)) | CustomMetaTransformFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):CustomMetaTransformFunction:(ParameterTag:Buffer:GstBuffer*:):(ParameterTag:CustomMeta:GstCustomMeta*:):(ParameterTag:Buffer:GstBuffer*:):(ParameterTag:GLib.Quark:GQuark:):(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:)) | PluginFilter | (CallbackTag:(ParameterTag:gboolean:gboolean:):PluginFilter:(ParameterTag:Plugin:GstPlugin*:):(ParameterTag:gpointer:gpointer:)) @@ -128,6 +134,7 @@ | PadIterIntLinkFunction | (CallbackTag:(ParameterTag:Iterator:GstIterator*:):PadIterIntLinkFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:)) | MemoryUnmapFullFunction | (CallbackTag:(ParameterTag:none:void:):MemoryUnmapFullFunction:(ParameterTag:Memory:GstMemory*:):(ParameterTag:MapInfo:GstMapInfo*:)) | PadActivateModeFunction | (CallbackTag:(ParameterTag:gboolean:gboolean:):PadActivateModeFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:):(ParameterTag:PadMode:GstPadMode:):(ParameterTag:gboolean:gboolean:)) +| AllocationMetaParamsAggregator | (CallbackTag:(ParameterTag:gboolean:gboolean:):AllocationMetaParamsAggregator:(ParameterTag:Structure:GstStructure**:):(ParameterTag:Structure:const GstStructure*:):(ParameterTag:Structure:const GstStructure*:)) | BufferListFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):BufferListFunc:(ParameterTag:Buffer:GstBuffer**:):(ParameterTag:guint:guint:):(ParameterTag:gpointer:gpointer:)) | LogFunction | (CallbackTag:(ParameterTag:none:void:):LogFunction:(ParameterTag:DebugCategory:GstDebugCategory*:):(ParameterTag:DebugLevel:GstDebugLevel:):(ParameterTag:utf8:const gchar*:):(ParameterTag:utf8:const gchar*:):(ParameterTag:gint:gint:):(ParameterTag:GObject.Object:GObject*:):(ParameterTag:DebugMessage:GstDebugMessage*:):(ParameterTag:gpointer:gpointer:)) | PadEventFullFunction | (CallbackTag:(ParameterTag:FlowReturn:GstFlowReturn:):PadEventFullFunction:(ParameterTag:Pad:GstPad*:):(ParameterTag:Object:GstObject*:):(ParameterTag:Event:GstEvent*:)) @@ -188,6 +195,7 @@ | Name | Detailed |------------------------------------------|--------- +| PathForeachFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):PathForeachFunc:(ParameterTag:PathOperation:GskPathOperation:):(ParameterTag:Graphene.Point:const graphene_point_t*:):(ParameterTag:gsize:gsize:):(ParameterTag:gfloat:float:):(ParameterTag:gpointer:gpointer:)) | ParseErrorFunc | (CallbackTag:(ParameterTag:none:void:):ParseErrorFunc:(ParameterTag:ParseLocation:const GskParseLocation*:):(ParameterTag:ParseLocation:const GskParseLocation*:):(ParameterTag:GLib.Error:const GError*:):(ParameterTag:gpointer:gpointer:)) ## pangocairo @@ -204,6 +212,7 @@ | TestLogFatalFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):TestLogFatalFunc:(ParameterTag:utf8:const gchar*:):(ParameterTag:LogLevelFlags:GLogLevelFlags:):(ParameterTag:utf8:const gchar*:):(ParameterTag:gpointer:gpointer:)) | DestroyNotify | (CallbackTag:(ParameterTag:none:void:):DestroyNotify:(ParameterTag:gpointer:gpointer:)) | HookCheckFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):HookCheckFunc:(ParameterTag:gpointer:gpointer:)) +| SourceFuncsCheckFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):SourceFuncsCheckFunc:(ParameterTag:Source:GSource*:)) | IOFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):IOFunc:(ParameterTag:IOChannel:GIOChannel*:):(ParameterTag:IOCondition:GIOCondition:):(ParameterTag:gpointer:gpointer:)) | SourceFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):SourceFunc:(ParameterTag:gpointer:gpointer:)) | ErrorInitFunc | (CallbackTag:(ParameterTag:none:void:):ErrorInitFunc:(ParameterTag:Error:GError*:)) @@ -211,7 +220,9 @@ | ChildWatchFunc | (CallbackTag:(ParameterTag:none:void:):ChildWatchFunc:(ParameterTag:Pid:GPid:):(ParameterTag:gint:gint:):(ParameterTag:gpointer:gpointer:)) | LogFunc | (CallbackTag:(ParameterTag:none:void:):LogFunc:(ParameterTag:utf8:const gchar*:):(ParameterTag:LogLevelFlags:GLogLevelFlags:):(ParameterTag:utf8:const gchar*:):(ParameterTag:gpointer:gpointer:)) | TestDataFunc | (CallbackTag:(ParameterTag:none:void:):TestDataFunc:(ParameterTag:gpointer:gconstpointer:)) +| CacheNewFunc | (CallbackTag:(ParameterTag:gpointer:gpointer:):CacheNewFunc:(ParameterTag:gpointer:gpointer:)) | CompareDataFunc | (CallbackTag:(ParameterTag:gint:gint:):CompareDataFunc:(ParameterTag:gpointer:gconstpointer:):(ParameterTag:gpointer:gconstpointer:):(ParameterTag:gpointer:gpointer:)) +| SourceFuncsPrepareFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):SourceFuncsPrepareFunc:(ParameterTag:Source:GSource*:):(ParameterTag:gint:gint*:)) | ErrorCopyFunc | (CallbackTag:(ParameterTag:none:void:):ErrorCopyFunc:(ParameterTag:Error:const GError*:):(ParameterTag:Error:GError*:)) | PrintFunc | (CallbackTag:(ParameterTag:none:void:):PrintFunc:(ParameterTag:utf8:const gchar*:)) | ThreadFunc | (CallbackTag:(ParameterTag:gpointer:gpointer:):ThreadFunc:(ParameterTag:gpointer:gpointer:)) @@ -227,6 +238,7 @@ | HookCompareFunc | (CallbackTag:(ParameterTag:gint:gint:):HookCompareFunc:(ParameterTag:Hook:GHook*:):(ParameterTag:Hook:GHook*:)) | TraverseFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):TraverseFunc:(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:)) | HashFunc | (CallbackTag:(ParameterTag:guint:guint:):HashFunc:(ParameterTag:gpointer:gconstpointer:)) +| CacheDestroyFunc | (CallbackTag:(ParameterTag:none:void:):CacheDestroyFunc:(ParameterTag:gpointer:gpointer:)) | DataForeachFunc | (CallbackTag:(ParameterTag:none:void:):DataForeachFunc:(ParameterTag:Quark:GQuark:):(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:)) | DuplicateFunc | (CallbackTag:(ParameterTag:gpointer:gpointer:):DuplicateFunc:(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:)) | Func | (CallbackTag:(ParameterTag:none:void:):Func:(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:)) @@ -241,15 +253,20 @@ | SequenceIterCompareFunc | (CallbackTag:(ParameterTag:gint:gint:):SequenceIterCompareFunc:(ParameterTag:SequenceIter:GSequenceIter*:):(ParameterTag:SequenceIter:GSequenceIter*:):(ParameterTag:gpointer:gpointer:)) | HookMarshaller | (CallbackTag:(ParameterTag:none:void:):HookMarshaller:(ParameterTag:Hook:GHook*:):(ParameterTag:gpointer:gpointer:)) | OptionParseFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):OptionParseFunc:(ParameterTag:OptionContext:GOptionContext*:):(ParameterTag:OptionGroup:GOptionGroup*:):(ParameterTag:gpointer:gpointer:)) +| CompletionStrncmpFunc | (CallbackTag:(ParameterTag:gint:gint:):CompletionStrncmpFunc:(ParameterTag:utf8:const gchar*:):(ParameterTag:utf8:const gchar*:):(ParameterTag:gsize:gsize:)) | ScannerMsgFunc | (CallbackTag:(ParameterTag:none:void:):ScannerMsgFunc:(ParameterTag:Scanner:GScanner*:):(ParameterTag:utf8:gchar*:):(ParameterTag:gboolean:gboolean:)) | CompareFunc | (CallbackTag:(ParameterTag:gint:gint:):CompareFunc:(ParameterTag:gpointer:gconstpointer:):(ParameterTag:gpointer:gconstpointer:)) +| CacheDupFunc | (CallbackTag:(ParameterTag:gpointer:gpointer:):CacheDupFunc:(ParameterTag:gpointer:gpointer:)) | HookFindFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):HookFindFunc:(ParameterTag:Hook:GHook*:):(ParameterTag:gpointer:gpointer:)) | ErrorClearFunc | (CallbackTag:(ParameterTag:none:void:):ErrorClearFunc:(ParameterTag:Error:GError*:)) | HRFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):HRFunc:(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:):(ParameterTag:gpointer:gpointer:)) +| SourceFuncsDispatchFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):SourceFuncsDispatchFunc:(ParameterTag:Source:GSource*:):(ParameterTag:SourceFunc:GSourceFunc:):(ParameterTag:gpointer:gpointer:)) | TestFunc | (CallbackTag:(ParameterTag:none:void:):TestFunc) | SourceOnceFunc | (CallbackTag:(ParameterTag:none:void:):SourceOnceFunc:(ParameterTag:gpointer:gpointer:)) | RegexEvalCallback | (CallbackTag:(ParameterTag:gboolean:gboolean:):RegexEvalCallback:(ParameterTag:MatchInfo:const GMatchInfo*:):(ParameterTag:String:GString*:):(ParameterTag:gpointer:gpointer:)) +| CompletionFunc | (CallbackTag:(ParameterTag:utf8:gchar*:):CompletionFunc:(ParameterTag:gpointer:gpointer:)) | OptionArgFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):OptionArgFunc:(ParameterTag:utf8:const gchar*:):(ParameterTag:utf8:const gchar*:):(ParameterTag:gpointer:gpointer:)) +| SourceFuncsFinalizeFunc | (CallbackTag:(ParameterTag:none:void:):SourceFuncsFinalizeFunc:(ParameterTag:Source:GSource*:)) | UnixFDSourceFunc | (CallbackTag:(ParameterTag:gboolean:gboolean:):UnixFDSourceFunc:(ParameterTag:gint:gint:):(ParameterTag:IOCondition:GIOCondition:):(ParameterTag:gpointer:gpointer:)) | SpawnChildSetupFunc | (CallbackTag:(ParameterTag:none:void:):SpawnChildSetupFunc:(ParameterTag:gpointer:gpointer:)) | TranslateFunc | (CallbackTag:(ParameterTag:utf8:const gchar*:):TranslateFunc:(ParameterTag:utf8:const gchar*:):(ParameterTag:gpointer:gpointer:)) @@ -295,6 +312,7 @@ | IconViewForeachFunc | (CallbackTag:(ParameterTag:none:void:):IconViewForeachFunc:(ParameterTag:IconView:GtkIconView*:):(ParameterTag:TreePath:GtkTreePath*:):(ParameterTag:gpointer:gpointer:)) | TreeModelFilterModifyFunc | (CallbackTag:(ParameterTag:none:void:):TreeModelFilterModifyFunc:(ParameterTag:TreeModel:GtkTreeModel*:):(ParameterTag:TreeIter:GtkTreeIter*:):(ParameterTag:GObject.Value:GValue*:):(ParameterTag:gint:int:):(ParameterTag:gpointer:gpointer:)) | ListBoxSortFunc | (CallbackTag:(ParameterTag:gint:int:):ListBoxSortFunc:(ParameterTag:ListBoxRow:GtkListBoxRow*:):(ParameterTag:ListBoxRow:GtkListBoxRow*:):(ParameterTag:gpointer:gpointer:)) +| TextBufferCommitNotify | (CallbackTag:(ParameterTag:none:void:):TextBufferCommitNotify:(ParameterTag:TextBuffer:GtkTextBuffer*:):(ParameterTag:TextBufferNotifyFlags:GtkTextBufferNotifyFlags:):(ParameterTag:guint:guint:):(ParameterTag:guint:guint:):(ParameterTag:gpointer:gpointer:)) | CustomRequestModeFunc | (CallbackTag:(ParameterTag:SizeRequestMode:GtkSizeRequestMode:):CustomRequestModeFunc:(ParameterTag:Widget:GtkWidget*:)) | DrawingAreaDrawFunc | (CallbackTag:(ParameterTag:none:void:):DrawingAreaDrawFunc:(ParameterTag:DrawingArea:GtkDrawingArea*:):(ParameterTag:cairo.Context:cairo_t*:):(ParameterTag:gint:int:):(ParameterTag:gint:int:):(ParameterTag:gpointer:gpointer:)) | MenuButtonCreatePopupFunc | (CallbackTag:(ParameterTag:none:void:):MenuButtonCreatePopupFunc:(ParameterTag:MenuButton:GtkMenuButton*:):(ParameterTag:gpointer:gpointer:)) @@ -311,3 +329,4 @@ |------------------------------------------|--------- | ContentSerializeFunc | (CallbackTag:(ParameterTag:none:void:):ContentSerializeFunc:(ParameterTag:ContentSerializer:GdkContentSerializer*:)) | ContentDeserializeFunc | (CallbackTag:(ParameterTag:none:void:):ContentDeserializeFunc:(ParameterTag:ContentDeserializer:GdkContentDeserializer*:)) +| CursorGetTextureCallback | (CallbackTag:(ParameterTag:Texture:GdkTexture*:):CursorGetTextureCallback:(ParameterTag:Cursor:GdkCursor*:):(ParameterTag:gint:int:):(ParameterTag:gdouble:double:):(ParameterTag:gint:int*:):(ParameterTag:gint:int*:):(ParameterTag:gint:int*:):(ParameterTag:gint:int*:):(ParameterTag:gpointer:gpointer:)) diff --git a/doc/gen/enum_table.md b/doc/gen/enum_table.md index 4efe4bf..30a349a 100644 --- a/doc/gen/enum_table.md +++ b/doc/gen/enum_table.md @@ -7,10 +7,12 @@ | ConnectFlags | SignalMatchType | GTypeFlags +| IOCondition | GTypeDebugFlags | ParamFlags | TypeDebugFlags | TypeFlags +| GIOCondition | GSignalFlags | TypeFundamentalFlags | GConnectFlags @@ -437,6 +439,7 @@ | Name | ----- | GMarkupCollectType +| GUnixPipeEnd | GUserDirectory | GTestSubprocessFlags | ChecksumType @@ -445,6 +448,7 @@ | GThreadError | GDateMonth | GShellError +| UnixPipeEnd | GUriError | FormatSizeFlags | LogLevelFlags @@ -519,6 +523,7 @@ | SpawnError | AsciiType | GOptionFlags +| ThreadPriority | LogWriterOutput | GSliceConfig | GErrorType @@ -537,6 +542,7 @@ | GLogWriterOutput | GKeyFileError | GOptionArg +| GThreadPriority | GNumberParserError | VariantParseError | NumberParserError @@ -573,6 +579,7 @@ | GdkPaintableFlags | GdkGLError | GdkFrameClockPhase +| CicpRange | GdkEventType | ModifierType | DevicePadFeature @@ -594,6 +601,8 @@ | AxisUse | GdkKeyMatch | GdkMemoryFormat +| GdkDmabufError +| DmabufError | ScrollDirection | GdkGravity | PaintableFlags @@ -601,6 +610,7 @@ | DragCancelReason | GdkCrossingMode | ScrollUnit +| GdkCicpRange | GdkModifierType | GdkAxisUse | TouchpadGesturePhase @@ -648,36 +658,50 @@ | LeafletTransitionType | AdwNavigationDirection | AdwToolbarStyle -| AdwLengthUnit -| FlapFoldPolicy | AdwLeafletTransitionType -| ToastPriority | BreakpointConditionRatioType -| ColorScheme | ResponseAppearance | AdwSqueezerTransitionType -| BreakpointConditionLengthType +| InlineViewSwitcherDisplayMode | NavigationDirection -| AdwBreakpointConditionLengthType +| AdwInlineViewSwitcherDisplayMode | FlapTransitionType +| JustifyMode +| AccentColor +| AdwTabViewShortcuts +| AdwWrapPolicy +| AdwAccentColor +| FoldThresholdPolicy +| AdwBreakpointConditionRatioType +| AdwColorScheme +| LengthUnit +| CenteringPolicy +| PackDirection +| DialogPresentationMode +| AdwDialogPresentationMode +| AdwLengthUnit +| FlapFoldPolicy +| ToastPriority +| ColorScheme +| BreakpointConditionLengthType +| AdwBreakpointConditionLengthType +| AdwJustifyMode | AdwToastPriority | AnimationState | SqueezerTransitionType | AdwFlapTransitionType -| AdwTabViewShortcuts +| AdwBannerButtonStyle | AdwAnimationState | AdwResponseAppearance -| FoldThresholdPolicy -| AdwBreakpointConditionRatioType -| AdwColorScheme +| BannerButtonStyle | AdwCenteringPolicy | TabViewShortcuts -| LengthUnit -| CenteringPolicy +| WrapPolicy | ViewSwitcherPolicy | AdwEasing | AdwFlapFoldPolicy | AdwFoldThresholdPolicy +| AdwPackDirection | ToolbarStyle ## pango @@ -743,21 +767,33 @@ | Name | ----- +| PathForeachFlags +| GskLineJoin +| TransformCategory +| ScalingFilter +| Corner +| GskCorner +| RenderNodeType +| FillRule +| LineCap +| GskPathOperation +| GskLineCap | GskTransformCategory | BlendMode -| TransformCategory +| PathOperation | GskMaskMode -| ScalingFilter | GskScalingFilter +| GskPathForeachFlags | GskRenderNodeType +| PathDirection +| LineJoin | GskBlendMode | SerializationError -| Corner | MaskMode +| GskFillRule | GLUniformType -| GskCorner -| RenderNodeType | GskSerializationError +| GskPathDirection | GskGLUniformType ## gtk @@ -768,10 +804,12 @@ | GtkSymbolicColor | EventSequenceState | ShortcutScope +| GtkGraphicsOffloadEnabled | ScrollablePolicy | PopoverMenuFlags | GtkCssParserWarning | ImageType +| AccessibleTextContentChange | TextDirection | GtkIconSize | ListTabBehavior @@ -803,6 +841,7 @@ | PanDirection | GtkStackTransitionType | FilterMatch +| GtkTextBufferNotifyFlags | GtkFileChooserAction | DeleteType | GtkInputHints @@ -851,6 +890,7 @@ | GtkEventSequenceState | MessageType | TreeViewGridLines +| FontRendering | SpinType | PageOrientation | GtkBuilderClosureFlags @@ -901,12 +941,14 @@ | PrintPages | GtkPolicyType | GtkStringFilterMatchMode +| GtkAccessibleTextGranularity | StackTransitionType | GtkWrapMode | GtkRecentManagerError | CellRendererAccelMode | GtkTextViewLayer | GtkSortType +| AccessibleAnnouncementPriority | Align | AccessibleState | DirectionType @@ -935,6 +977,8 @@ | TextExtendSelection | PropagationLimit | PrintStatus +| GtkAccessibleAnnouncementPriority +| AccessibleTextGranularity | GtkPrintOperationResult | BaselinePosition | GtkArrowType @@ -957,6 +1001,7 @@ | GtkResponseType | GtkAccessibleTristate | CellRendererMode +| GtkFontRendering | Unit | FontChooserLevel | GtkOverflow @@ -969,6 +1014,7 @@ | GtkPrintQuality | GtkPageSet | BorderStyle +| TextBufferNotifyFlags | DebugFlags | ButtonsType | CornerType @@ -979,11 +1025,13 @@ | GtkMovementStep | CellRendererState | GtkConstraintAttribute +| GtkAccessibleTextContentChange | GtkJustification | GtkShortcutActionFlags | GtkSizeRequestMode | GtkFontChooserLevel | GtkPrintDuplex +| GraphicsOffloadEnabled | ShortcutType | GtkCellRendererMode | TreeViewColumnSizing diff --git a/doc/gen/structure_table.md b/doc/gen/structure_table.md index dc4a630..dcb317f 100644 --- a/doc/gen/structure_table.md +++ b/doc/gen/structure_table.md @@ -120,6 +120,7 @@ | Int64Range | true | | Promise | true | | TracerPrivate | | +| ByteArrayInterface | | | TypeFindFactory | true | | ControlBindingClass | | ControlBinding | DebugCategory | | @@ -190,8 +191,8 @@ | ControlSource | true | | DynamicTypeFactory | true | | StreamCollectionClass | | StreamCollection -| TypeFind | | -| StaticCaps | | +| TypeFind | true | +| StaticCaps | true | | GhostPadPrivate | | | PluginClass | | Plugin | ReferenceTimestampMeta | | @@ -204,6 +205,7 @@ | BinClass | | Bin | Message | true | | BufferPoolPrivate | | +| IdStr | true | | Element | true | | SharedTaskPoolPrivate | | | TracerFactory | true | @@ -213,6 +215,7 @@ | CapsFeatures | true | | DynamicTypeFactoryClass | | DynamicTypeFactory | PluginFeatureClass | | PluginFeature +| VecDeque | | | BusPrivate | | | ParamFraction | true | | Iterator | true | @@ -223,7 +226,7 @@ | ObjectClass | | Object | ControlSourceClass | | ControlSource | PadClass | | Pad -| StaticPadTemplate | | +| StaticPadTemplate | true | | Bin | true | | Sample | true | | AllocationParams | true | @@ -480,7 +483,9 @@ | UnixSocketAddressPrivate | | | VolumeMonitor | true | | NetworkMonitorInterface | | NetworkMonitor +| ThreadedResolverClass | | ThreadedResolver | Application | true | +| ThreadedResolver | true | | NetworkAddressPrivate | | | DBusMenuModel | true | | SocketClientPrivate | | @@ -699,12 +704,14 @@ | List | | | Private | | | HookList | | +| StaticPrivate | | | OptionContext | | | MarkupParser | | | PatternSpec | true | | TestConfig | | | SList | | -| Hmac | | +| StaticMutex | | +| Hmac | true | | VariantBuilder | true | | PtrArray | true | | Mutex | | @@ -717,13 +724,16 @@ | TimeZone | true | | RecMutex | | | DoubleIEEE754 | | +| Tuples | | | IConv | | | IOChannel | true | +| Cache | | | TrashStack | | | Scanner | | | OptionEntry | | | VariantType | true | | ThreadPool | | +| MemChunk | | | SourceFuncs | | | VariantDict | true | | MainLoop | true | @@ -736,32 +746,39 @@ | Source | true | | TokenValue | | | MappedFile | true | +| StaticRWLock | | +| Relation | | | OptionGroup | true | | SourceCallbackFuncs | | | HashTableIter | | +| StaticRecMutex | | | Queue | | | BookmarkFile | true | | TestLogMsg | | +| Allocator | | | Hook | | +| ThreadFunctions | | | Cond | | -| Rand | | +| Rand | true | | PathBuf | | | Error | true | +| UnixPipe | | | Data | | -| Dir | | +| Dir | true | | Date | true | | VariantIter | | | StringChunk | | | Thread | true | | UriParamsIter | | | Array | true | +| Completion | | | SequenceIter | | | Timer | | | MatchInfo | true | | TestCase | | | MainContext | true | | StatBuf | | -| StrvBuilder | | +| StrvBuilder | true | | TestLogBuffer | | ## gdk @@ -772,16 +789,19 @@ | DragSurface | true | | Rectangle | true | | TouchEvent | true | +| ColorState | true | | FrameClockPrivate | | | Cursor | true | | FocusEvent | true | | SnapshotClass | | Snapshot | DeleteEvent | true | +| MemoryTextureBuilder | true | | EventSequence | true | | RGBA | true | | PaintableInterface | | Paintable | GLTextureBuilder | true | | Popup | true | +| CicpParamsClass | | CicpParams | Toplevel | true | | ContentSerializer | true | | TimeCoord | | @@ -798,13 +818,14 @@ | MemoryTextureClass | | MemoryTexture | ProximityEvent | true | | GLTextureClass | | GLTexture -| DragSurfaceSize | | +| DragSurfaceSize | true | | Drop | true | | Snapshot | true | | FrameClockClass | | FrameClock | ScrollEvent | true | | CairoContext | true | | ToplevelInterface | | Toplevel +| MemoryTextureBuilderClass | | MemoryTextureBuilder | ContentDeserializer | true | | TouchpadEvent | true | | AppLaunchContext | true | @@ -813,13 +834,16 @@ | SurfaceClass | | Surface | ContentProvider | true | | GLContext | true | -| ToplevelSize | | +| ToplevelSize | true | +| DmabufFormats | true | | Texture | true | | DevicePad | true | | DeviceTool | true | | Surface | true | | KeyEvent | true | | ContentFormats | true | +| DmabufTextureClass | | DmabufTexture +| DmabufTextureBuilder | true | | Monitor | true | | ContentFormatsBuilder | true | | DrawContext | true | @@ -827,9 +851,12 @@ | FrameClock | true | | VulkanContext | true | | PopupInterface | | Popup +| DmabufTexture | true | +| DmabufTextureBuilderClass | | DmabufTextureBuilder | MemoryTexture | true | | MotionEvent | true | | Paintable | true | +| CicpParams | true | | Drag | true | | ButtonEvent | true | | PopupLayout | true | @@ -865,10 +892,16 @@ | Name | getType | isTypeStructFor |--------------------------------|---------|---------------- +| AlertDialog | true | | AnimationClass | | Animation | TimedAnimation | true | +| AboutDialog | true | +| AlertDialogClass | | AlertDialog +| ToggleClass | | Toggle | ToolbarView | true | | CarouselIndicatorLines | true | +| PreferencesDialog | true | +| ButtonRow | true | | EntryRowClass | | EntryRow | PreferencesPageClass | | PreferencesPage | FlapClass | | Flap @@ -877,21 +910,25 @@ | PreferencesGroup | true | | CarouselIndicatorDotsClass | | CarouselIndicatorDots | ExpanderRowClass | | ExpanderRow +| ToggleGroupClass | | ToggleGroup | SplitButtonClass | | SplitButton | ViewStackPageClass | | ViewStackPage | LeafletClass | | Leaflet | ViewSwitcherBarClass | | ViewSwitcherBar +| BottomSheetClass | | BottomSheet | TabView | true | | EntryRow | true | | NavigationSplitView | true | | OverlaySplitViewClass | | OverlaySplitView | PreferencesRow | true | +| PreferencesDialogClass | | PreferencesDialog | CallbackAnimationTargetClass | | CallbackAnimationTarget | ComboRowClass | | ComboRow | NavigationSplitViewClass | | NavigationSplitView | SqueezerPage | true | | AboutWindowClass | | AboutWindow | BreakpointCondition | true | +| LayoutSlotClass | | LayoutSlot | TabButton | true | | TabPage | true | | SwitchRow | true | @@ -904,7 +941,10 @@ | BreakpointClass | | Breakpoint | ViewStackClass | | ViewStack | SqueezerPageClass | | SqueezerPage +| LayoutSlot | true | +| Spinner | true | | NavigationViewClass | | NavigationView +| WrapBox | true | | Swipeable | true | | PreferencesWindow | true | | OverlaySplitView | true | @@ -921,10 +961,13 @@ | CarouselClass | | Carousel | CallbackAnimationTarget | true | | Banner | true | +| ButtonRowClass | | ButtonRow | ApplicationClass | | Application | StyleManagerClass | | StyleManager | PreferencesGroupClass | | PreferencesGroup | ToastOverlay | true | +| WrapBoxClass | | WrapBox +| Layout | true | | PreferencesRowClass | | PreferencesRow | Animation | true | | Clamp | true | @@ -935,13 +978,19 @@ | ClampScrollable | true | | CarouselIndicatorDots | true | | NavigationView | true | +| MultiLayoutViewClass | | MultiLayoutView +| SpinnerPaintable | true | | TabBar | true | | Carousel | true | | TabOverview | true | | LeafletPage | true | | BreakpointBinClass | | BreakpointBin +| WrapLayout | true | +| LayoutClass | | Layout | PasswordEntryRow | true | +| InlineViewSwitcherClass | | InlineViewSwitcher | NavigationPage | true | +| Dialog | true | | TabPageClass | | TabPage | PropertyAnimationTargetClass | | PropertyAnimationTarget | SpringAnimation | true | @@ -958,7 +1007,10 @@ | ApplicationWindow | true | | Flap | true | | WindowClass | | Window +| DialogClass | | Dialog | Squeezer | true | +| AboutDialogClass | | AboutDialog +| BottomSheet | true | | AnimationTargetClass | | AnimationTarget | BannerClass | | Banner | AnimationTarget | true | @@ -971,14 +1023,18 @@ | SpringParams | true | | CarouselIndicatorLinesClass | | CarouselIndicatorLines | ViewSwitcher | true | +| SpinnerClass | | Spinner | ViewStackPagesClass | | ViewStackPages | ViewSwitcherTitleClass | | ViewSwitcherTitle +| WrapLayoutClass | | WrapLayout | Toast | true | | ComboRow | true | | SplitButton | true | +| Toggle | true | | ClampLayoutClass | | ClampLayout | TabButtonClass | | TabButton | ExpanderRow | true | +| InlineViewSwitcher | true | | SwipeTracker | true | | PreferencesPage | true | | TabOverviewClass | | TabOverview @@ -987,6 +1043,7 @@ | Bin | true | | EnumListModel | true | | ActionRow | true | +| SpinnerPaintableClass | | SpinnerPaintable | ToastClass | | Toast | StatusPageClass | | StatusPage | Avatar | true | @@ -996,7 +1053,9 @@ | SpringAnimationClass | | SpringAnimation | AvatarClass | | Avatar | EnumListItem | true | +| MultiLayoutView | true | | ViewSwitcherBar | true | +| ToggleGroup | true | | ButtonContent | true | | ButtonContentClass | | ButtonContent @@ -1064,46 +1123,56 @@ | GLShaderNode | true | | RoundedRect | | | OutsetShadowNode | true | -| GLRenderer | true | | LinearGradientNode | true | +| SubsurfaceNode | true | | BlendNode | true | +| TextureNode | true | +| MaskNode | true | +| ShadowNode | true | +| ClipNode | true | +| RepeatingRadialGradientNode | true | +| RenderNode | true | +| FillNode | true | +| CairoRenderer | true | +| ParseLocation | | +| TransformNode | true | +| GLRendererClass | | GLRenderer +| CrossFadeNode | true | +| VulkanRenderer | true | +| RepeatNode | true | +| PathMeasure | true | +| Renderer | true | +| CairoNode | true | +| ColorMatrixNode | true | +| GLRenderer | true | | Shadow | | | DebugNode | true | | RadialGradientNode | true | -| TextureNode | true | -| MaskNode | true | +| StrokeNode | true | +| PathPoint | true | +| PathBuilder | true | | ConicGradientNode | true | | ContainerNode | true | -| ShadowNode | true | | RendererClass | | Renderer | GLShaderClass | | GLShader -| ClipNode | true | -| RepeatingRadialGradientNode | true | | RepeatingLinearGradientNode | true | | RoundedClipNode | true | +| Path | true | | ColorStop | | +| Stroke | true | | NglRenderer | true | -| RenderNode | true | | ShaderArgsBuilder | true | | CairoRendererClass | | CairoRenderer | ColorNode | true | | BlurNode | true | -| CairoRenderer | true | | OpacityNode | true | -| ParseLocation | | -| TransformNode | true | | TextNode | true | -| GLRendererClass | | GLRenderer | BroadwayRenderer | true | -| CrossFadeNode | true | -| RepeatNode | true | +| VulkanRendererClass | | VulkanRenderer | InsetShadowNode | true | | TextureScaleNode | true | -| Renderer | true | | BroadwayRendererClass | | BroadwayRenderer -| CairoNode | true | | BorderNode | true | -| ColorMatrixNode | true | | GLShader | true | | Transform | true | @@ -1251,6 +1320,7 @@ | AlertDialog | true | | BookmarkList | true | | IconView | true | +| AccessibleText | true | | DropDownClass | | DropDown | FlattenListModel | true | | ColumnViewCellClass | | ColumnViewCell @@ -1261,6 +1331,7 @@ | Image | true | | PrintOperationPreview | true | | ShortcutLabel | true | +| PrintDialogClass | | PrintDialog | TextViewPrivate | | | CellRendererText | true | | Sorter | true | @@ -1274,6 +1345,7 @@ | Root | true | | AppChooserButton | true | | TextChildAnchor | true | +| GraphicsOffload | true | | FileChooserNativeClass | | FileChooserNative | CellRendererToggle | true | | Snapshot | true | @@ -1335,6 +1407,7 @@ | FontChooserIface | | FontChooser | FixedClass | | Fixed | ColumnViewColumn | true | +| PrintSetup | true | | SelectionModel | true | | TreeDragSource | true | | WindowControls | true | @@ -1389,6 +1462,7 @@ | ColorChooser | true | | Scale | true | | OrientableIface | | Orientable +| AccessibleTextRange | | | ShortcutManagerInterface | | ShortcutManager | IMMulticontextClass | | IMMulticontext | CallbackAction | true | @@ -1506,6 +1580,7 @@ | SymbolicPaintable | true | | KeyvalTrigger | true | | PrintOperationPreviewIface | | PrintOperationPreview +| AccessibleList | true | | SignalListItemFactoryClass | | SignalListItemFactory | PaperSize | true | | Border | true | @@ -1575,6 +1650,7 @@ | LockButton | true | | ConstraintLayoutChild | true | | EventControllerScroll | true | +| GraphicsOffloadClass | | GraphicsOffload | FileFilter | true | | Buildable | true | | Fixed | true | @@ -1582,6 +1658,7 @@ | TextTagTable | true | | CellLayoutIface | | CellLayout | GestureDrag | true | +| PrintDialog | true | | FileChooserNative | true | | MultiSelectionClass | | MultiSelection | MediaControls | true | @@ -1622,6 +1699,7 @@ | ConstraintTargetInterface | | ConstraintTarget | EventControllerScrollClass | | EventControllerScroll | AccessibleInterface | | Accessible +| AccessibleTextInterface | | AccessibleText | DropTarget | true | | ATContextClass | | ATContext | TreeDragSourceIface | | TreeDragSource diff --git a/generator/src/main/resources/gir/Adw-1.gir b/generator/src/main/resources/gir/Adw-1.gir index 7e8ebe0..ee1e8e5 100644 --- a/generator/src/main/resources/gir/Adw-1.gir +++ b/generator/src/main/resources/gir/Adw-1.gir @@ -5,49 +5,51 @@ and/or use gtk-doc annotations. --> + - + glib:type-name="AdwAboutDialog" + glib:get-type="adw_about_dialog_get_type" + glib:type-struct="AboutDialogClass"> A window showing information about the application. + filename="src/adw-about-dialog.c" + line="23">A dialog showing information about the application. <picture> - <source srcset="about-window-dark.png" media="(prefers-color-scheme: dark)"> - <img src="about-window.png" alt="about-window"> + <source srcset="about-dialog-dark.png" media="(prefers-color-scheme: dark)"> + <img src="about-dialog.png" alt="about-dialog"> </picture> -An about window is typically opened when the user activates the `About …` -item in the application's primary menu. All parts of the window are optional. +an about dialog is typically opened when the user activates the `About …` +item in the application's primary menu. All parts of the dialog are optional. ## Main page -`AdwAboutWindow` prominently displays the application's icon, name, developer -name and version. They can be set with the [property@AboutWindow:application-icon], -[property@AboutWindow:application-name], -[property@AboutWindow:developer-name] and [property@AboutWindow:version] +`AdwAboutDialog` prominently displays the application's icon, name, developer +name and version. They can be set with the [property@AboutDialog:application-icon], +[property@AboutDialog:application-name], +[property@AboutDialog:developer-name] and [property@AboutDialog:version] respectively. ## What's New -`AdwAboutWindow` provides a way for applications to display their release -notes, set with the [property@AboutWindow:release-notes] property. +`AdwAboutDialog` provides a way for applications to display their release +notes, set with the [property@AboutDialog:release-notes] property. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). @@ -67,50 +69,50 @@ Any text outside paragraphs or list items is ignored. Nested lists are not supported. Only one version can be shown at a time. By default, the displayed version -number matches [property@AboutWindow:version]. Use -[property@AboutWindow:release-notes-version] to override it. +number matches [property@AboutDialog:version]. Use +[property@AboutDialog:release-notes-version] to override it. ## Details The Details page displays the application comments and links. -The comments can be set with the [property@AboutWindow:comments] property. +The comments can be set with the [property@AboutDialog:comments] property. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. -To set the application website, use [property@AboutWindow:website]. -To add extra links below the website, use [method@AboutWindow.add_link]. +To set the application website, use [property@AboutDialog:website]. +To add extra links below the website, use [method@AboutDialog.add_link]. If the Details page doesn't have any other content besides website, the website will be displayed on the main page instead. ## Troubleshooting -`AdwAboutWindow` displays the following two links on the main page: +`AdwAboutDialog` displays the following two links on the main page: -* Support Questions, set with the [property@AboutWindow:support-url] property, -* Report an Issue, set with the [property@AboutWindow:issue-url] property. +* Support Questions, set with the [property@AboutDialog:support-url] property, +* Report an Issue, set with the [property@AboutDialog:issue-url] property. Additionally, applications can provide debugging information. It will be shown separately on the Troubleshooting page. Use the -[property@AboutWindow:debug-info] property to specify it. +[property@AboutDialog:debug-info] property to specify it. It's intended to be attached to issue reports when reporting issues against the application. As such, it cannot contain markup or links. -`AdwAboutWindow` provides a quick way to save debug information to a file. -When saving, [property@AboutWindow:debug-info-filename] would be used as +`AdwAboutDialog` provides a quick way to save debug information to a file. +When saving, [property@AboutDialog:debug-info-filename] would be used as the suggested filename. ## Credits and Acknowledgements The Credits page has the following default sections: -* Developers, set with the [property@AboutWindow:developers] property, -* Designers, set with the [property@AboutWindow:designers] property, -* Artists, set with the [property@AboutWindow:artists] property, -* Documenters, set with the [property@AboutWindow:documenters] property, -* Translators, set with the [property@AboutWindow:translator-credits] property. +* Developers, set with the [property@AboutDialog:developers] property, +* Designers, set with the [property@AboutDialog:designers] property, +* Artists, set with the [property@AboutDialog:artists] property, +* Documenters, set with the [property@AboutDialog:documenters] property, +* Translators, set with the [property@AboutDialog:translator-credits] property. When setting translator credits, use the strings `"translator-credits"` or `"translator_credits"` and mark them as translatable. @@ -118,11 +120,11 @@ When setting translator credits, use the strings `"translator-credits"` or The default sections that don't contain any names won't be displayed. The Credits page can also contain an arbitrary number of extra sections below -the default ones. Use [method@AboutWindow.add_credit_section] to add them. +the default ones. Use [method@AboutDialog.add_credit_section] to add them. The Acknowledgements page can be used to acknowledge additional people and organizations for their non-development contributions. Use -[method@AboutWindow.add_acknowledgement_section] to add sections to it. For +[method@AboutDialog.add_acknowledgement_section] to add sections to it. For example, it can be used to list backers in a crowdfunded project or to give special thanks. @@ -132,8 +134,8 @@ specified. To add a email address, use a string like string like `The GNOME Project https://www.gnome.org`: <picture> - <source srcset="about-window-credits-dark.png" media="(prefers-color-scheme: dark)"> - <img src="about-window-credits.png" alt="about-window-credits"> + <source srcset="about-dialog-credits-dark.png" media="(prefers-color-scheme: dark)"> + <img src="about-dialog-credits.png" alt="about-dialog-credits"> </picture> ## Legal @@ -141,23 +143,28 @@ string like `The GNOME Project https://www.gnome.org`: The Legal page displays the copyright and licensing information for the application and other modules. -The copyright string is set with the [property@AboutWindow:copyright] +The copyright string is set with the [property@AboutDialog:copyright] property and should be a short string of one or two lines, for example: `© 2022 Example`. Licensing information can be quickly set from a list of known licenses with -the [property@AboutWindow:license-type] property. If the application's -license is not in the list, [property@AboutWindow:license] can be used +the [property@AboutDialog:license-type] property. If the application's +license is not in the list, [property@AboutDialog:license] can be used instead. To add information about other modules, such as application dependencies or -data, use [method@AboutWindow.add_legal_section]. +data, use [method@AboutDialog.add_legal_section]. + +## Other applications + +`AdwAboutDialog` can show links to your other apps at the end of the main +page. To add them, use [method@AboutDialog.add_other_app]. ## Constructing -To make constructing an `AdwAboutWindow` as convenient as possible, you can -use the function [func@show_about_window] which constructs and shows a -window. +To make constructing an `AdwAboutDialog` as convenient as possible, you can +use the function [func@show_about_dialog] which constructs and shows a +dialog. ```c static void @@ -173,12 +180,12 @@ show_about (GtkApplication *app) NULL }; - adw_show_about_window (gtk_application_get_active_window (app), + adw_show_about_dialog (GTK_WIDGET (gtk_application_get_active_window (app)), "application-name", _("Example"), "application-icon", "org.example.App", "version", "1.2.3", "copyright", "© 2022 Angela Avery", - "issue-url", "https://gitlab.gnome.org/example/example/-/issues/new", + "issue-url", "https://gitlab.gnome.org/example/example/-/issues/", "license-type", GTK_LICENSE_GPL_3_0, "developers", developers, "designers", designers, @@ -189,66 +196,65 @@ show_about (GtkApplication *app) ## CSS nodes -`AdwAboutWindow` has a main CSS node with the name `window` and the +`AdwAboutDialog` has a main CSS node with the name `dialog` and the style class `.about`. - + - - + c:identifier="adw_about_dialog_new" + version="1.5"> Creates a new `AdwAboutWindow`. - + filename="src/adw-about-dialog.c" + line="1966">Creates a new `AdwAboutDialog`. + the newly created `AdwAboutWindow` - + filename="src/adw-about-dialog.c" + line="1971">the newly created `AdwAboutDialog` + + c:identifier="adw_about_dialog_new_from_appdata" + version="1.5"> Creates a new `AdwAboutWindow` using AppStream metadata. + filename="src/adw-about-dialog.c" + line="1981">Creates a new `AdwAboutDialog` using AppStream metadata. This automatically sets the following properties with the following AppStream values: -* [property@AboutWindow:application-icon] is set from the `<id>` -* [property@AboutWindow:application-name] is set from the `<name>` -* [property@AboutWindow:developer-name] is set from the `<developer_name>` -* [property@AboutWindow:version] is set from the version of the latest release -* [property@AboutWindow:website] is set from the `<url type="homepage">` -* [property@AboutWindow:support-url] is set from the `<url type="help">` -* [property@AboutWindow:issue-url] is set from the `<url type="bugtracker">` -* [property@AboutWindow:license-type] is set from the `<project_license>` - If the license type retrieved from AppStream is not listed in - [enum@Gtk.License], it will be set to `GTK_LICENCE_CUSTOM`. +* [property@AboutDialog:application-icon] is set from the `<id>` +* [property@AboutDialog:application-name] is set from the `<name>` +* [property@AboutDialog:developer-name] is set from the `<name>` within + `<developer>` +* [property@AboutDialog:version] is set from the version of the latest release +* [property@AboutDialog:website] is set from the `<url type="homepage">` +* [property@AboutDialog:support-url] is set from the `<url type="help">` +* [property@AboutDialog:issue-url] is set from the `<url type="bugtracker">` +* [property@AboutDialog:license-type] is set from the `<project_license>`. + If the license type retrieved from AppStream is not listed in + [enum@Gtk.License], it will be set to `GTK_LICENCE_CUSTOM`. If @release_notes_version is not `NULL`, -[property@AboutWindow:release-notes-version] is set to match it, while -[property@AboutWindow:release-notes] is set from the AppStream release +[property@AboutDialog:release-notes-version] is set to match it, while +[property@AboutDialog:release-notes] is set from the AppStream release description for that version. - + the newly created `AdwAboutWindow` - + filename="src/adw-about-dialog.c" + line="2008">the newly created `AdwAboutDialog` + The resource to use + filename="src/adw-about-dialog.c" + line="1983">The resource to use nullable="1" allow-none="1"> The version to retrieve release notes for + filename="src/adw-about-dialog.c" + line="1984">The version to retrieve release notes for + c:identifier="adw_about_dialog_add_acknowledgement_section" + version="1.5"> Adds a section to the Acknowledgements page. + filename="src/adw-about-dialog.c" + line="3144">Adds a section to the Acknowledgements page. This can be used to acknowledge additional people and organizations for their non-development contributions - for example, backers in a crowdfunded @@ -278,36 +284,36 @@ details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] - +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] + an about window - + filename="src/adw-about-dialog.c" + line="3146">an about dialog + the section name + filename="src/adw-about-dialog.c" + line="3147">the section name the list of names + filename="src/adw-about-dialog.c" + line="3148">the list of names @@ -315,11 +321,11 @@ See also: + c:identifier="adw_about_dialog_add_credit_section" + version="1.5"> Adds an extra section to the Credits page. + filename="src/adw-about-dialog.c" + line="3101">Adds an extra section to the Credits page. Extra sections are displayed below the standard categories. @@ -328,36 +334,36 @@ details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_acknowledgement_section] - +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_acknowledgement_section] + an about window - + filename="src/adw-about-dialog.c" + line="3103">an about dialog + the section name + filename="src/adw-about-dialog.c" + line="3104">the section name the list of names + filename="src/adw-about-dialog.c" + line="3105">the list of names @@ -365,17 +371,17 @@ See also: + c:identifier="adw_about_dialog_add_legal_section" + version="1.5"> Adds an extra section to the Legal page. + filename="src/adw-about-dialog.c" + line="3364">Adds an extra section to the Legal page. Extra sections will be displayed below the application's own information. The parameters @copyright, @license_type and @license will be used to present -the it the same way as [property@AboutWindow:copyright], -[property@AboutWindow:license-type] and [property@AboutWindow:license] are +the it the same way as [property@AboutDialog:copyright], +[property@AboutDialog:license-type] and [property@AboutDialog:license] are for the application's own information. See those properties for more details. @@ -385,45 +391,45 @@ This can be useful to attribute the application dependencies or data. Examples: ```c -adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), +adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Copyright and a known license"), "© 2022 Example", GTK_LICENSE_LGPL_2_1, NULL); -adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), +adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Copyright and custom license"), "© 2022 Example", GTK_LICENSE_CUSTOM, "Custom license text"); -adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), +adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Copyright only"), "© 2022 Example", GTK_LICENSE_UNKNOWN, NULL); -adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), +adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Custom license only"), NULL, GTK_LICENSE_CUSTOM, "Something completely custom here."); ``` - + an about window - + filename="src/adw-about-dialog.c" + line="3366">an about dialog + the name of the section + filename="src/adw-about-dialog.c" + line="3367">the name of the section a copyright string + filename="src/adw-about-dialog.c" + line="3368">a copyright string the type of license + filename="src/adw-about-dialog.c" + line="3369">the type of license custom license information + filename="src/adw-about-dialog.c" + line="3370">custom license information + c:identifier="adw_about_dialog_add_link" + version="1.5"> Adds an extra link to the Details page. + filename="src/adw-about-dialog.c" + line="2662">Adds an extra link to the Details page. Extra links are displayed under the comment and website. Underlines in @title will be interpreted as indicating a mnemonic. -See [property@AboutWindow:website]. - +See [property@AboutDialog:website]. + an about window - + filename="src/adw-about-dialog.c" + line="2664">an about dialog + the link title + filename="src/adw-about-dialog.c" + line="2665">the link title the link URL + filename="src/adw-about-dialog.c" + line="2666">the link URL + + + + + + Adds another application to @self. + +The application will be displayed at the bottom of the main page, in a +separate section. Each added application will be presented as a row with +@title and @summary, as well as an icon with the name @appid. Clicking the +row will show @appid in the software center app. + +This can be used to link to your other applications if you have multiple. + +Example: + +```c +adw_about_dialog_add_other_app (ADW_ABOUT_DIALOG (about), + "org.gnome.Boxes", + _("Boxes"), + _("Virtualization made simple")); +``` + + + + + + + an about dialog + + + + the application ID + + + + the application name + + + + the application summary - + version="1.5"> Gets the name of the application icon for @self. - + filename="src/adw-about-dialog.c" + line="2163">Gets the name of the application icon for @self. + the application icon name + filename="src/adw-about-dialog.c" + line="2169">the application icon name an about window - + filename="src/adw-about-dialog.c" + line="2165">an about dialog + - + version="1.5"> Gets the application name for @self. - + filename="src/adw-about-dialog.c" + line="2208">Gets the application name for @self. + the application name + filename="src/adw-about-dialog.c" + line="2214">the application name an about window - + filename="src/adw-about-dialog.c" + line="2210">an about dialog + - + version="1.5"> Gets the list of artists of the application. - + filename="src/adw-about-dialog.c" + line="2926">Gets the list of artists of the application. + The list of artists + filename="src/adw-about-dialog.c" + line="2932">The list of artists @@ -559,122 +613,116 @@ See [property@AboutWindow:website]. an about window - + filename="src/adw-about-dialog.c" + line="2928">an about dialog + - + version="1.5"> Gets the comments about the application. - + filename="src/adw-about-dialog.c" + line="2480">Gets the comments about the application. + the comments + filename="src/adw-about-dialog.c" + line="2486">the comments an about window - + filename="src/adw-about-dialog.c" + line="2482">an about dialog + - + version="1.5"> Gets the copyright information for @self. - + filename="src/adw-about-dialog.c" + line="3185">Gets the copyright information for @self. + the copyright information + filename="src/adw-about-dialog.c" + line="3191">the copyright information an about window - + filename="src/adw-about-dialog.c" + line="3187">an about dialog + - + version="1.5"> Gets the debug information for @self. - + filename="src/adw-about-dialog.c" + line="2713">Gets the debug information for @self. + the debug information + filename="src/adw-about-dialog.c" + line="2719">the debug information an about window - + filename="src/adw-about-dialog.c" + line="2715">an about dialog + - + version="1.5"> Gets the debug information filename for @self. - + filename="src/adw-about-dialog.c" + line="2765">Gets the debug information filename for @self. + the debug information filename + filename="src/adw-about-dialog.c" + line="2771">the debug information filename an about window - + filename="src/adw-about-dialog.c" + line="2767">an about dialog + - + version="1.5"> Gets the list of designers of the application. - + filename="src/adw-about-dialog.c" + line="2868">Gets the list of designers of the application. + The list of designers + filename="src/adw-about-dialog.c" + line="2874">The list of designers @@ -682,49 +730,47 @@ See [property@AboutWindow:website]. an about window - + filename="src/adw-about-dialog.c" + line="2870">an about dialog + - + version="1.5"> Gets the developer name for @self. - + filename="src/adw-about-dialog.c" + line="2253">Gets the developer name for @self. + the developer_name + filename="src/adw-about-dialog.c" + line="2259">the developer_name an about window - + filename="src/adw-about-dialog.c" + line="2255">an about dialog + - + version="1.5"> Gets the list of developers of the application. - + filename="src/adw-about-dialog.c" + line="2810">Gets the list of developers of the application. + The list of developers + filename="src/adw-about-dialog.c" + line="2816">The list of developers @@ -732,25 +778,24 @@ See [property@AboutWindow:website]. an about window - + filename="src/adw-about-dialog.c" + line="2812">an about dialog + - + version="1.5"> Gets the list of documenters of the application. - + filename="src/adw-about-dialog.c" + line="2984">Gets the list of documenters of the application. + The list of documenters + filename="src/adw-about-dialog.c" + line="2990">The list of documenters @@ -758,298 +803,282 @@ See [property@AboutWindow:website]. an about window - + filename="src/adw-about-dialog.c" + line="2986">an about dialog + - + version="1.5"> Gets the issue tracker URL for @self. - + filename="src/adw-about-dialog.c" + line="2618">Gets the issue tracker URL for @self. + the issue tracker URL + filename="src/adw-about-dialog.c" + line="2624">the issue tracker URL an about window - + filename="src/adw-about-dialog.c" + line="2620">an about dialog + - + version="1.5"> Gets the license for @self. - + filename="src/adw-about-dialog.c" + line="3300">Gets the license for @self. + the license + filename="src/adw-about-dialog.c" + line="3306">the license an about window - + filename="src/adw-about-dialog.c" + line="3302">an about dialog + - + version="1.5"> Gets the license type for @self. - + filename="src/adw-about-dialog.c" + line="3236">Gets the license type for @self. + the license type + filename="src/adw-about-dialog.c" + line="3242">the license type an about window - + filename="src/adw-about-dialog.c" + line="3238">an about dialog + - + version="1.5"> Gets the release notes for @self. - + filename="src/adw-about-dialog.c" + line="2414">Gets the release notes for @self. + the release notes + filename="src/adw-about-dialog.c" + line="2420">the release notes an about window - + filename="src/adw-about-dialog.c" + line="2416">an about dialog + - + version="1.5"> Gets the version described by the application's release notes. - + filename="src/adw-about-dialog.c" + line="2360">Gets the version described by the application's release notes. + the release notes version + filename="src/adw-about-dialog.c" + line="2366">the release notes version an about window - + filename="src/adw-about-dialog.c" + line="2362">an about dialog + - + version="1.5"> Gets the URL of the support page for @self. - + filename="src/adw-about-dialog.c" + line="2574">Gets the URL of the support page for @self. + the support page URL + filename="src/adw-about-dialog.c" + line="2580">the support page URL an about window - + filename="src/adw-about-dialog.c" + line="2576">an about dialog + - + version="1.5"> Gets the translator credits string. - + filename="src/adw-about-dialog.c" + line="3042">Gets the translator credits string. + The translator credits string + filename="src/adw-about-dialog.c" + line="3048">The translator credits string an about window - + filename="src/adw-about-dialog.c" + line="3044">an about dialog + - + version="1.5"> Gets the version for @self. - + filename="src/adw-about-dialog.c" + line="2313">Gets the version for @self. + the version + filename="src/adw-about-dialog.c" + line="2319">the version an about window - + filename="src/adw-about-dialog.c" + line="2315">an about dialog + - + version="1.5"> Gets the application website URL for @self. - + filename="src/adw-about-dialog.c" + line="2527">Gets the application website URL for @self. + the website URL + filename="src/adw-about-dialog.c" + line="2533">the website URL an about window - + filename="src/adw-about-dialog.c" + line="2529">an about dialog + - + version="1.5"> Sets the name of the application icon for @self. + filename="src/adw-about-dialog.c" + line="2181">Sets the name of the application icon for @self. The icon is displayed at the top of the main page. - + an about window - + filename="src/adw-about-dialog.c" + line="2183">an about dialog + the application icon name + filename="src/adw-about-dialog.c" + line="2184">the application icon name - + version="1.5"> Sets the application name for @self. + filename="src/adw-about-dialog.c" + line="2226">Sets the application name for @self. The name is displayed at the top of the main page. - + an about window - + filename="src/adw-about-dialog.c" + line="2228">an about dialog + the application name + filename="src/adw-about-dialog.c" + line="2229">the application name - + version="1.5"> Sets the list of artists of the application. + filename="src/adw-about-dialog.c" + line="2944">Sets the list of artists of the application. It will be displayed on the Credits page. @@ -1058,30 +1087,30 @@ details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] - +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] + an about window - + filename="src/adw-about-dialog.c" + line="2946">an about dialog + the list of artists + filename="src/adw-about-dialog.c" + line="2947">the list of artists @@ -1089,45 +1118,43 @@ See also: - + version="1.5"> Sets the comments about the application. + filename="src/adw-about-dialog.c" + line="2498">Sets the comments about the application. Comments will be shown on the Details page, above links. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. - + an about window - + filename="src/adw-about-dialog.c" + line="2500">an about dialog + the comments + filename="src/adw-about-dialog.c" + line="2501">the comments - + version="1.5"> Sets the copyright information for @self. + filename="src/adw-about-dialog.c" + line="3203">Sets the copyright information for @self. This should be a short string of one or two lines, for example: `© 2022 Example`. @@ -1135,104 +1162,101 @@ This should be a short string of one or two lines, for example: The copyright information will be displayed on the Legal page, before the application license. -[method@AboutWindow.add_legal_section] can be used to add copyright +[method@AboutDialog.add_legal_section] can be used to add copyright information for the application dependencies or other components. - + an about window - + filename="src/adw-about-dialog.c" + line="3205">an about dialog + the copyright information + filename="src/adw-about-dialog.c" + line="3206">the copyright information - + version="1.5"> Sets the debug information for @self. + filename="src/adw-about-dialog.c" + line="2731">Sets the debug information for @self. Debug information will be shown on the Troubleshooting page. It's intended to be attached to issue reports when reporting issues against the application. -`AdwAboutWindow` provides a quick way to save debug information to a file. -When saving, [property@AboutWindow:debug-info-filename] would be used as +`AdwAboutDialog` provides a quick way to save debug information to a file. +When saving, [property@AboutDialog:debug-info-filename] would be used as the suggested filename. Debug information cannot contain markup or links. - + an about window - + filename="src/adw-about-dialog.c" + line="2733">an about dialog + the debug information + filename="src/adw-about-dialog.c" + line="2734">the debug information - + version="1.5"> Sets the debug information filename for @self. + filename="src/adw-about-dialog.c" + line="2783">Sets the debug information filename for @self. It will be used as the suggested filename when saving debug information to a file. -See [property@AboutWindow:debug-info]. - +See [property@AboutDialog:debug-info]. + an about window - + filename="src/adw-about-dialog.c" + line="2785">an about dialog + the debug info filename + filename="src/adw-about-dialog.c" + line="2786">the debug info filename - + version="1.5"> Sets the list of designers of the application. + filename="src/adw-about-dialog.c" + line="2886">Sets the list of designers of the application. It will be displayed on the Credits page. @@ -1241,30 +1265,30 @@ details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] - +* [property@AboutDialog:developers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] + an about window - + filename="src/adw-about-dialog.c" + line="2888">an about dialog + the list of designers + filename="src/adw-about-dialog.c" + line="2889">the list of designers @@ -1272,47 +1296,45 @@ See also: - + version="1.5"> Sets the developer name for @self. + filename="src/adw-about-dialog.c" + line="2271">Sets the developer name for @self. The developer name is displayed on the main page, under the application name. If the application is developed by multiple people, the developer name can be set to values like "AppName team", "AppName developers" or "The AppName project", and the individual contributors can be listed on the -Credits page, with [property@AboutWindow:developers] and related properties. - +Credits page, with [property@AboutDialog:developers] and related properties. + an about window - + filename="src/adw-about-dialog.c" + line="2273">an about dialog + the developer name + filename="src/adw-about-dialog.c" + line="2274">the developer name - + version="1.5"> Sets the list of developers of the application. + filename="src/adw-about-dialog.c" + line="2828">Sets the list of developers of the application. It will be displayed on the Credits page. @@ -1321,30 +1343,30 @@ details. See also: -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] - +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] + an about window - + filename="src/adw-about-dialog.c" + line="2830">an about dialog + the list of developers + filename="src/adw-about-dialog.c" + line="2831">the list of developers @@ -1352,13 +1374,12 @@ See also: - + version="1.5"> Sets the list of documenters of the application. + filename="src/adw-about-dialog.c" + line="3002">Sets the list of documenters of the application. It will be displayed on the Credits page. @@ -1367,30 +1388,30 @@ details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] - +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] + an about window - + filename="src/adw-about-dialog.c" + line="3004">an about dialog + the list of documenters + filename="src/adw-about-dialog.c" + line="3005">the list of documenters @@ -1398,47 +1419,45 @@ See also: - + version="1.5"> Sets the issue tracker URL for @self. + filename="src/adw-about-dialog.c" + line="2636">Sets the issue tracker URL for @self. The issue tracker link is displayed on the main page. - + an about window - + filename="src/adw-about-dialog.c" + line="2638">an about dialog + the issue tracker URL + filename="src/adw-about-dialog.c" + line="2639">the issue tracker URL - + version="1.5"> Sets the license for @self. + filename="src/adw-about-dialog.c" + line="3318">Sets the license for @self. This can be used to set a custom text for the license if it can't be set via -[property@AboutWindow:license-type]. +[property@AboutDialog:license-type]. -When set, [property@AboutWindow:license-type] will be set to +When set, [property@AboutDialog:license-type] will be set to `GTK_LICENSE_CUSTOM`. The license text will be displayed on the Legal page, below the copyright @@ -1446,77 +1465,75 @@ information. License text can contain Pango markup and links. -[method@AboutWindow.add_legal_section] can be used to add license information +[method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. - + an about window - + filename="src/adw-about-dialog.c" + line="3320">an about dialog + the license + filename="src/adw-about-dialog.c" + line="3321">the license - + version="1.5"> Sets the license for @self from a list of known licenses. + filename="src/adw-about-dialog.c" + line="3254">Sets the license for @self from a list of known licenses. If the application's license is not in the list, -[property@AboutWindow:license] can be used instead. The license type will be +[property@AboutDialog:license] can be used instead. The license type will be automatically set to `GTK_LICENSE_CUSTOM` in that case. If @license_type is `GTK_LICENSE_UNKNOWN`, no information will be displayed. If @license_type is different from `GTK_LICENSE_CUSTOM`. -[property@AboutWindow:license] will be cleared out. +[property@AboutDialog:license] will be cleared out. The license description will be displayed on the Legal page, below the copyright information. -[method@AboutWindow.add_legal_section] can be used to add license information +[method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. - + an about window - + filename="src/adw-about-dialog.c" + line="3256">an about dialog + the license type + filename="src/adw-about-dialog.c" + line="3257">the license type - + version="1.5"> Sets the release notes for @self. + filename="src/adw-about-dialog.c" + line="2432">Sets the release notes for @self. Release notes are displayed on the the What's New page. @@ -1537,105 +1554,100 @@ Any text outside paragraphs or list items is ignored. Nested lists are not supported. -`AdwAboutWindow` displays the version above the release notes. If set, the -[property@AboutWindow:release-notes-version] of the property will be used -as the version; otherwise, [property@AboutWindow:version] is used. - +`AdwAboutDialog` displays the version above the release notes. If set, the +[property@AboutDialog:release-notes-version] of the property will be used +as the version; otherwise, [property@AboutDialog:version] is used. + an about window - + filename="src/adw-about-dialog.c" + line="2434">an about dialog + the release notes + filename="src/adw-about-dialog.c" + line="2435">the release notes - + version="1.5"> Sets the version described by the application's release notes. + filename="src/adw-about-dialog.c" + line="2378">Sets the version described by the application's release notes. The release notes version is displayed on the What's New page, above the release notes. -If not set, [property@AboutWindow:version] will be used instead. +If not set, [property@AboutDialog:version] will be used instead. For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly. -See [property@AboutWindow:release-notes]. - +See [property@AboutDialog:release-notes]. + an about window - + filename="src/adw-about-dialog.c" + line="2380">an about dialog + the release notes version + filename="src/adw-about-dialog.c" + line="2381">the release notes version - + version="1.5"> Sets the URL of the support page for @self. + filename="src/adw-about-dialog.c" + line="2592">Sets the URL of the support page for @self. The support page link is displayed on the main page. - + an about window - + filename="src/adw-about-dialog.c" + line="2594">an about dialog + the support page URL + filename="src/adw-about-dialog.c" + line="2595">the support page URL - + version="1.5"> Sets the translator credits string. + filename="src/adw-about-dialog.c" + line="3060">Sets the translator credits string. It will be displayed on the Credits page. @@ -1647,142 +1659,128 @@ more details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] - +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] + an about window - + filename="src/adw-about-dialog.c" + line="3062">an about dialog + the translator credits + filename="src/adw-about-dialog.c" + line="3063">the translator credits - + version="1.5"> Sets the version for @self. + filename="src/adw-about-dialog.c" + line="2331">Sets the version for @self. The version is displayed on the main page. -If [property@AboutWindow:release-notes-version] is not set, the version will +If [property@AboutDialog:release-notes-version] is not set, the version will also be displayed above the release notes on the What's New page. - + an about window - + filename="src/adw-about-dialog.c" + line="2333">an about dialog + the version + filename="src/adw-about-dialog.c" + line="2334">the version - + version="1.5"> Sets the application website URL for @self. + filename="src/adw-about-dialog.c" + line="2545">Sets the application website URL for @self. Website is displayed on the Details page, below comments, or on the main page if the Details page doesn't have any other content. -Applications can add other links below, see [method@AboutWindow.add_link]. - +Applications can add other links below, see [method@AboutDialog.add_link]. + an about window - + filename="src/adw-about-dialog.c" + line="2547">an about dialog + the website URL + filename="src/adw-about-dialog.c" + line="2548">the website URL - - The name of the application icon. + filename="src/adw-about-dialog.c" + line="1395">The name of the application icon. The icon is displayed at the top of the main page. - - The name of the application. + filename="src/adw-about-dialog.c" + line="1409">The name of the application. The name is displayed at the top of the main page. - - The list of artists of the application. + filename="src/adw-about-dialog.c" + line="1672">The list of artists of the application. It will be displayed on the Credits page. @@ -1791,29 +1789,25 @@ more details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] - - The comments about the application. + filename="src/adw-about-dialog.c" + line="1519">The comments about the application. Comments will be shown on the Details page, above links. @@ -1822,18 +1816,14 @@ detailed. It can also contain links and Pango markup. - - The copyright information. + filename="src/adw-about-dialog.c" + line="1753">The copyright information. This should be a short string of one or two lines, for example: `© 2022 Example`. @@ -1841,68 +1831,56 @@ This should be a short string of one or two lines, for example: The copyright information will be displayed on the Legal page, above the application license. -[method@AboutWindow.add_legal_section] can be used to add copyright +[method@AboutDialog.add_legal_section] can be used to add copyright information for the application dependencies or other components. - - The debug information. + filename="src/adw-about-dialog.c" + line="1581">The debug information. Debug information will be shown on the Troubleshooting page. It's intended to be attached to issue reports when reporting issues against the application. -`AdwAboutWindow` provides a quick way to save debug information to a file. -When saving, [property@AboutWindow:debug-info-filename] would be used as +`AdwAboutDialog` provides a quick way to save debug information to a file. +When saving, [property@AboutDialog:debug-info-filename] would be used as the suggested filename. Debug information cannot contain markup or links. - - The debug information filename. + filename="src/adw-about-dialog.c" + line="1603">The debug information filename. It will be used as the suggested filename when saving debug information to a file. -See [property@AboutWindow:debug-info]. +See [property@AboutDialog:debug-info]. - - The list of designers of the application. + filename="src/adw-about-dialog.c" + line="1646">The list of designers of the application. It will be displayed on the Credits page. @@ -1911,29 +1889,25 @@ more details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] +* [property@AboutDialog:developers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] - - The developer name. + filename="src/adw-about-dialog.c" + line="1423">The developer name. The developer name is displayed on the main page, under the application name. @@ -1941,23 +1915,19 @@ name. If the application is developed by multiple people, the developer name can be set to values like "AppName team", "AppName developers" or "The AppName project", and the individual contributors can be listed on the -Credits page, with [property@AboutWindow:developers] and related +Credits page, with [property@AboutDialog:developers] and related properties. - - The list of developers of the application. + filename="src/adw-about-dialog.c" + line="1620">The list of developers of the application. It will be displayed on the Credits page. @@ -1966,29 +1936,25 @@ more details. See also: -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] - - The list of documenters of the application. + filename="src/adw-about-dialog.c" + line="1698">The list of documenters of the application. It will be displayed on the Credits page. @@ -1997,51 +1963,43 @@ more details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:translator-credits] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:translator-credits] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] - - The URL for the application's issue tracker. + filename="src/adw-about-dialog.c" + line="1567">The URL for the application's issue tracker. The issue tracker link is displayed on the main page. - - The license text. + filename="src/adw-about-dialog.c" + line="1804">The license text. This can be used to set a custom text for the license if it can't be set -via [property@AboutWindow:license-type]. +via [property@AboutDialog:license-type]. -When set, [property@AboutWindow:license-type] will be set to +When set, [property@AboutDialog:license-type] will be set to `GTK_LICENSE_CUSTOM`. The license text will be displayed on the Legal page, below the copyright @@ -2049,56 +2007,48 @@ information. License text can contain Pango markup and links. -[method@AboutWindow.add_legal_section] can be used to add license +[method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. - - The license type. + filename="src/adw-about-dialog.c" + line="1774">The license type. Allows to set the application's license froma list of known licenses. If the application's license is not in the list, -[property@AboutWindow:license] can be used instead. The license type will +[property@AboutDialog:license] can be used instead. The license type will be automatically set to `GTK_LICENSE_CUSTOM` in that case. If set to `GTK_LICENSE_UNKNOWN`, no information will be displayed. If the license type is different from `GTK_LICENSE_CUSTOM`. -[property@AboutWindow:license] will be cleared out. +[property@AboutDialog:license] will be cleared out. The license description will be displayed on the Legal page, below the copyright information. -[method@AboutWindow.add_legal_section] can be used to add license +[method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. - - The release notes of the application. + filename="src/adw-about-dialog.c" + line="1484">The release notes of the application. Release notes are displayed on the the What's New page. @@ -2119,67 +2069,55 @@ Any text outside paragraphs or list items is ignored. Nested lists are not supported. -`AdwAboutWindow` displays the version above the release notes. If set, the -[property@AboutWindow:release-notes-version] of the property will be used -as the version; otherwise, [property@AboutWindow:version] is used. +`AdwAboutDialog` displays the version above the release notes. If set, the +[property@AboutDialog:release-notes-version] of the property will be used +as the version; otherwise, [property@AboutDialog:version] is used. - - The version described by the application's release notes. + filename="src/adw-about-dialog.c" + line="1461">The version described by the application's release notes. The release notes version is displayed on the What's New page, above the release notes. -If not set, [property@AboutWindow:version] will be used instead. +If not set, [property@AboutDialog:version] will be used instead. For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly. -See [property@AboutWindow:release-notes]. +See [property@AboutDialog:release-notes]. - - The URL of the application's support page. + filename="src/adw-about-dialog.c" + line="1553">The URL of the application's support page. The support page link is displayed on the main page. - - The translator credits string. + filename="src/adw-about-dialog.c" + line="1724">The translator credits string. It will be displayed on the Credits page. @@ -2191,14116 +2129,25203 @@ more details. See also: -* [property@AboutWindow:developers] -* [property@AboutWindow:designers] -* [property@AboutWindow:artists] -* [property@AboutWindow:documenters] -* [method@AboutWindow.add_credit_section] -* [method@AboutWindow.add_acknowledgement_section] +* [property@AboutDialog:developers] +* [property@AboutDialog:designers] +* [property@AboutDialog:artists] +* [property@AboutDialog:documenters] +* [method@AboutDialog.add_credit_section] +* [method@AboutDialog.add_acknowledgement_section] - - The version of the application. + filename="src/adw-about-dialog.c" + line="1444">The version of the application. The version is displayed on the main page. -If [property@AboutWindow:release-notes-version] is not set, the version +If [property@AboutDialog:release-notes-version] is not set, the version will also be displayed above the release notes on the What's New page. - - The URL of the application's website. + filename="src/adw-about-dialog.c" + line="1536">The URL of the application's website. Website is displayed on the Details page, below comments, or on the main page if the Details page doesn't have any other content. -Applications can add other links below, see [method@AboutWindow.add_link]. +Applications can add other links below, see [method@AboutDialog.add_link]. - + Emitted when a URL is activated. + filename="src/adw-about-dialog.c" + line="1832">Emitted when a URL is activated. Applications may connect to it to override the default behavior, which is to call [func@Gtk.show_uri]. `TRUE` if the link has been activated + filename="src/adw-about-dialog.c" + line="1842">`TRUE` if the link has been activated the URI to activate + filename="src/adw-about-dialog.c" + line="1835">the URI to activate - - + + - + - + A [class@Gtk.ListBoxRow] used to present actions. + filename="src/adw-about-window.c" + line="22">A window showing information about the application. <picture> - <source srcset="action-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="action-row.png" alt="action-row"> + <source srcset="about-window-dark.png" media="(prefers-color-scheme: dark)"> + <img src="about-window.png" alt="about-window"> </picture> -The `AdwActionRow` widget can have a title, a subtitle and an icon. The row -can receive additional widgets at its end, or prefix widgets at its start. +An about window is typically opened when the user activates the `About …` +item in the application's primary menu. All parts of the window are optional. -It is convenient to present a preference and its related actions. +## Main page -`AdwActionRow` is unactivatable by default, giving it an activatable widget -will automatically make it activatable, but unsetting it won't change the -row's activatability. +`AdwAboutWindow` prominently displays the application's icon, name, developer +name and version. They can be set with the [property@AboutWindow:application-icon], +[property@AboutWindow:application-name], +[property@AboutWindow:developer-name] and [property@AboutWindow:version] +respectively. -## AdwActionRow as GtkBuildable +## What's New -The `AdwActionRow` implementation of the [iface@Gtk.Buildable] interface -supports adding a child at its end by specifying “suffix” or omitting the -“type” attribute of a <child> element. +`AdwAboutWindow` provides a way for applications to display their release +notes, set with the [property@AboutWindow:release-notes] property. -It also supports adding a child as a prefix widget by specifying “prefix” as -the “type” attribute of a <child> element. +Release notes are formatted the same way as +[AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). -## CSS nodes +The supported formatting options are: -`AdwActionRow` has a main CSS node with name `row`. +* Paragraph (`<p>`) +* Ordered list (`<ol>`), with list items (`<li>`) +* Unordered list (`<ul>`), with list items (`<li>`) -It contains the subnode `box.header` for its main horizontal box, and -`box.title` for the vertical box containing the title and subtitle labels. +Within paragraphs and list items, emphasis (`<em>`) and inline code +(`<code>`) text styles are supported. The emphasis is rendered in italic, +while inline code is shown in a monospaced font. -It contains subnodes `label.title` and `label.subtitle` representing -respectively the title label and subtitle label. - +Any text outside paragraphs or list items is ignored. + +Nested lists are not supported. + +Only one version can be shown at a time. By default, the displayed version +number matches [property@AboutWindow:version]. Use +[property@AboutWindow:release-notes-version] to override it. + +## Details + +The Details page displays the application comments and links. + +The comments can be set with the [property@AboutWindow:comments] property. +Unlike [property@Gtk.AboutDialog:comments], this string can be long and +detailed. It can also contain links and Pango markup. + +To set the application website, use [property@AboutWindow:website]. +To add extra links below the website, use [method@AboutWindow.add_link]. + +If the Details page doesn't have any other content besides website, the +website will be displayed on the main page instead. + +## Troubleshooting + +`AdwAboutWindow` displays the following two links on the main page: + +* Support Questions, set with the [property@AboutWindow:support-url] property, +* Report an Issue, set with the [property@AboutWindow:issue-url] property. + +Additionally, applications can provide debugging information. It will be +shown separately on the Troubleshooting page. Use the +[property@AboutWindow:debug-info] property to specify it. + +It's intended to be attached to issue reports when reporting issues against +the application. As such, it cannot contain markup or links. + +`AdwAboutWindow` provides a quick way to save debug information to a file. +When saving, [property@AboutWindow:debug-info-filename] would be used as +the suggested filename. + +## Credits and Acknowledgements + +The Credits page has the following default sections: + +* Developers, set with the [property@AboutWindow:developers] property, +* Designers, set with the [property@AboutWindow:designers] property, +* Artists, set with the [property@AboutWindow:artists] property, +* Documenters, set with the [property@AboutWindow:documenters] property, +* Translators, set with the [property@AboutWindow:translator-credits] property. + +When setting translator credits, use the strings `"translator-credits"` or +`"translator_credits"` and mark them as translatable. + +The default sections that don't contain any names won't be displayed. + +The Credits page can also contain an arbitrary number of extra sections below +the default ones. Use [method@AboutWindow.add_credit_section] to add them. + +The Acknowledgements page can be used to acknowledge additional people and +organizations for their non-development contributions. Use +[method@AboutWindow.add_acknowledgement_section] to add sections to it. For +example, it can be used to list backers in a crowdfunded project or to give +special thanks. + +Each of the people or organizations can have an email address or a website +specified. To add a email address, use a string like +`Edgar Allan Poe <edgar@poe.com>`. To specify a website with a title, use a +string like `The GNOME Project https://www.gnome.org`: + +<picture> + <source srcset="about-window-credits-dark.png" media="(prefers-color-scheme: dark)"> + <img src="about-window-credits.png" alt="about-window-credits"> +</picture> + +## Legal + +The Legal page displays the copyright and licensing information for the +application and other modules. + +The copyright string is set with the [property@AboutWindow:copyright] +property and should be a short string of one or two lines, for example: +`© 2022 Example`. + +Licensing information can be quickly set from a list of known licenses with +the [property@AboutWindow:license-type] property. If the application's +license is not in the list, [property@AboutWindow:license] can be used +instead. + +To add information about other modules, such as application dependencies or +data, use [method@AboutWindow.add_legal_section]. + +## Constructing + +To make constructing an `AdwAboutWindow` as convenient as possible, you can +use the function [func@show_about_window] which constructs and shows a +window. + +```c +static void +show_about (GtkApplication *app) +{ + const char *developers[] = { + "Angela Avery", + NULL + }; + + const char *designers[] = { + "GNOME Design Team", + NULL + }; + + adw_show_about_window (gtk_application_get_active_window (app), + "application-name", _("Example"), + "application-icon", "org.example.App", + "version", "1.2.3", + "copyright", "© 2022 Angela Avery", + "issue-url", "https://gitlab.gnome.org/example/example/-/issues/", + "license-type", GTK_LICENSE_GPL_3_0, + "developers", developers, + "designers", designers, + "translator-credits", _("translator-credits"), + NULL); +} +``` + +## CSS nodes + +`AdwAboutWindow` has a main CSS node with the name `window` and the +style class `.about`. + Use [class@AboutDialog]. + - - + + + + Creates a new `AdwActionRow`. - + filename="src/adw-about-window.c" + line="1978">Creates a new `AdwAboutWindow`. + Use [class@AboutDialog]. + the newly created `AdwActionRow` + filename="src/adw-about-window.c" + line="1983">the newly created `AdwAboutWindow` - + Activates @self. - + filename="src/adw-about-window.c" + line="1994">Creates a new `AdwAboutWindow` using AppStream metadata. + +This automatically sets the following properties with the following AppStream +values: + +* [property@AboutWindow:application-icon] is set from the `<id>` +* [property@AboutWindow:application-name] is set from the `<name>` +* [property@AboutWindow:developer-name] is set from the `<name>` within + `<developer>` +* [property@AboutWindow:version] is set from the version of the latest release +* [property@AboutWindow:website] is set from the `<url type="homepage">` +* [property@AboutWindow:support-url] is set from the `<url type="help">` +* [property@AboutWindow:issue-url] is set from the `<url type="bugtracker">` +* [property@AboutWindow:license-type] is set from the `<project_license>`. + If the license type retrieved from AppStream is not listed in + [enum@Gtk.License], it will be set to `GTK_LICENCE_CUSTOM`. + +If @release_notes_version is not `NULL`, +[property@AboutWindow:release-notes-version] is set to match it, while +[property@AboutWindow:release-notes] is set from the AppStream release +description for that version. + Use [class@AboutDialog]. + - + the newly created `AdwAboutWindow` + - + an action row - - + filename="src/adw-about-window.c" + line="1996">The resource to use + + + + The version to retrieve release notes for + + - - + + Activates @self. - + filename="src/adw-about-window.c" + line="3184">Adds a section to the Acknowledgements page. + +This can be used to acknowledge additional people and organizations for their +non-development contributions - for example, backers in a crowdfunded +project. + +Each name may contain email addresses and URLs, see the introduction for more +details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] + Use [class@AboutDialog]. + an action row - + filename="src/adw-about-window.c" + line="3186">an about window + + + the section name + + + + the list of names + + + + - + Adds a prefix widget to @self. - + filename="src/adw-about-window.c" + line="3140">Adds an extra section to the Credits page. + +Extra sections are displayed below the standard categories. + +Each name may contain email addresses and URLs, see the introduction for more +details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + an action row - + filename="src/adw-about-window.c" + line="3142">an about window + - + a widget - + filename="src/adw-about-window.c" + line="3143">the section name + + + + the list of names + + + - + Adds a suffix widget to @self. - + filename="src/adw-about-window.c" + line="3411">Adds an extra section to the Legal page. + +Extra sections will be displayed below the application's own information. + +The parameters @copyright, @license_type and @license will be used to present +the it the same way as [property@AboutWindow:copyright], +[property@AboutWindow:license-type] and [property@AboutWindow:license] are +for the application's own information. + +See those properties for more details. + +This can be useful to attribute the application dependencies or data. + +Examples: + +```c +adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), + _("Copyright and a known license"), + "© 2022 Example", + GTK_LICENSE_LGPL_2_1, + NULL); + +adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), + _("Copyright and custom license"), + "© 2022 Example", + GTK_LICENSE_CUSTOM, + "Custom license text"); + +adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), + _("Copyright only"), + "© 2022 Example", + GTK_LICENSE_UNKNOWN, + NULL); + +adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), + _("Custom license only"), + NULL, + GTK_LICENSE_CUSTOM, + "Something completely custom here."); +``` + Use [class@AboutDialog]. + an action row - + filename="src/adw-about-window.c" + line="3413">an about window + - + a widget - + filename="src/adw-about-window.c" + line="3414">the name of the section + + + + a copyright string + + + + the type of license + + + + custom license information + - - + Gets the widget activated when @self is activated. - - - the activatable widget for @self - + filename="src/adw-about-window.c" + line="2686">Adds an extra link to the Details page. + +Extra links are displayed under the comment and website. + +Underlines in @title will be interpreted as indicating a mnemonic. + +See [property@AboutWindow:website]. + Use [class@AboutDialog]. + + + an action row - + filename="src/adw-about-window.c" + line="2688">an about window + + + the link title + + + + the link URL + + - - + deprecated-version="1.6"> Gets the icon name for @self. - Use [method@ActionRow.add_prefix] to add an icon. - - + filename="src/adw-about-window.c" + line="2177">Gets the name of the application icon for @self. + Use [class@AboutDialog]. + + the icon name for @self + filename="src/adw-about-window.c" + line="2183">the application icon name an action row - + filename="src/adw-about-window.c" + line="2179">an about window + - - + Gets the subtitle for @self. - - + filename="src/adw-about-window.c" + line="2224">Gets the application name for @self. + Use [class@AboutDialog]. + + the subtitle for @self + filename="src/adw-about-window.c" + line="2230">the application name an action row - + filename="src/adw-about-window.c" + line="2226">an about window + - - + Gets the number of lines at the end of which the subtitle label will be -ellipsized. - + filename="src/adw-about-window.c" + line="2959">Gets the list of artists of the application. + Use [class@AboutDialog]. + + + The list of artists + + + + + + + an about window + + + + + + Gets the comments about the application. + Use [class@AboutDialog]. + the number of lines at the end of which the subtitle label will be - ellipsized - + filename="src/adw-about-window.c" + line="2502">the comments + an action row - + filename="src/adw-about-window.c" + line="2498">an about window + - - + Gets whether the user can copy the subtitle from the label - + filename="src/adw-about-window.c" + line="3226">Gets the copyright information for @self. + Use [class@AboutDialog]. + whether the user can copy the subtitle from the label - + filename="src/adw-about-window.c" + line="3232">the copyright information + a `AdwActionRow` - + filename="src/adw-about-window.c" + line="3228">an about window + - - + Gets the number of lines at the end of which the title label will be -ellipsized. - + filename="src/adw-about-window.c" + line="2738">Gets the debug information for @self. + Use [class@AboutDialog]. + the number of lines at the end of which the title label will be - ellipsized - + filename="src/adw-about-window.c" + line="2744">the debug information + an action row - + filename="src/adw-about-window.c" + line="2740">an about window + - + Removes a child from @self. - + filename="src/adw-about-window.c" + line="2792">Gets the debug information filename for @self. + Use [class@AboutDialog]. + - + the debug information filename + an action row - + filename="src/adw-about-window.c" + line="2794">an about window + - + + + + Gets the list of designers of the application. + Use [class@AboutDialog]. + + + The list of designers + + + + + + the child to be removed - - + filename="src/adw-about-window.c" + line="2901">an about window + + - - + Sets the widget to activate when @self is activated. - -The row can be activated either by clicking on it, calling -[method@ActionRow.activate], or via mnemonics in the title. -See the [property@PreferencesRow:use-underline] property to enable mnemonics. - -The target widget will be activated by emitting the -[signal@Gtk.Widget::mnemonic-activate] signal on it. - + filename="src/adw-about-window.c" + line="2271">Gets the developer name for @self. + Use [class@AboutDialog]. + - + the developer_name + an action row - + filename="src/adw-about-window.c" + line="2273">an about window + - + + + + Gets the list of developers of the application. + Use [class@AboutDialog]. + + + The list of developers + + + + + + the target widget - - + filename="src/adw-about-window.c" + line="2841">an about window + + - - + deprecated-version="1.6"> Sets the icon name for @self. - Use [method@ActionRow.add_prefix] to add an icon. - + filename="src/adw-about-window.c" + line="3019">Gets the list of documenters of the application. + Use [class@AboutDialog]. + + + The list of documenters + + + + + + + an about window + + + + + + Gets the issue tracker URL for @self. + Use [class@AboutDialog]. + - + the issue tracker URL + an action row - + filename="src/adw-about-window.c" + line="2642">an about window + - + + + + Gets the license for @self. + Use [class@AboutDialog]. + + + the license + + + + the icon name - - + filename="src/adw-about-window.c" + line="3347">an about window + + - - + Sets the subtitle for @self. - -The subtitle is interpreted as Pango markup unless -[property@PreferencesRow:use-markup] is set to `FALSE`. - + filename="src/adw-about-window.c" + line="3279">Gets the license type for @self. + Use [class@AboutDialog]. + - + the license type + an action row - + filename="src/adw-about-window.c" + line="3281">an about window + - + + + + Gets the release notes for @self. + Use [class@AboutDialog]. + + + the release notes + + + + the subtitle - - + filename="src/adw-about-window.c" + line="2430">an about window + + - - + Sets the number of lines at the end of which the subtitle label will be -ellipsized. - -If the value is 0, the number of lines won't be limited. - + filename="src/adw-about-window.c" + line="2372">Gets the version described by the application's release notes. + Use [class@AboutDialog]. + - + the release notes version + an action row - + filename="src/adw-about-window.c" + line="2374">an about window + - + + + + Gets the URL of the support page for @self. + Use [class@AboutDialog]. + + + the support page URL + + + + the number of lines at the end of which the subtitle label will be ellipsized - - + filename="src/adw-about-window.c" + line="2596">an about window + + - - + Sets whether the user can copy the subtitle from the label - -See also [property@Gtk.Label:selectable]. - + filename="src/adw-about-window.c" + line="3079">Gets the translator credits string. + Use [class@AboutDialog]. + - + The translator credits string + a `AdwActionRow` - + filename="src/adw-about-window.c" + line="3081">an about window + - + + + + Gets the version for @self. + Use [class@AboutDialog]. + + + the version + + + + `TRUE` if the user can copy the subtitle from the label - - + filename="src/adw-about-window.c" + line="2325">an about window + + - - + Sets the number of lines at the end of which the title label will be -ellipsized. + filename="src/adw-about-window.c" + line="2545">Gets the application website URL for @self. + Use [class@AboutDialog]. + + + the website URL + + + + + an about window + + + + + + Sets the name of the application icon for @self. -If the value is 0, the number of lines won't be limited. - +The icon is displayed at the top of the main page. + Use [class@AboutDialog]. + an action row - + filename="src/adw-about-window.c" + line="2198">an about window + - + the number of lines at the end of which the title label will be ellipsized - + filename="src/adw-about-window.c" + line="2199">the application icon name + - - - + The widget to activate when the row is activated. + filename="src/adw-about-window.c" + line="2243">Sets the application name for @self. -The row can be activated either by clicking on it, calling -[method@ActionRow.activate], or via mnemonics in the title. -See the [property@PreferencesRow:use-underline] property to enable -mnemonics. - -The target widget will be activated by emitting the -[signal@Gtk.Widget::mnemonic-activate] signal on it. - - - - - - The icon name for this row. - Use [method@ActionRow.add_prefix] to add an icon. - - - - - - The subtitle for this row. - -The subtitle is interpreted as Pango markup unless -[property@PreferencesRow:use-markup] is set to `FALSE`. - - - - - - The number of lines at the end of which the subtitle label will be -ellipsized. - -If the value is 0, the number of lines won't be limited. - - - - - - Whether the user can copy the subtitle from the label. - -See also [property@Gtk.Label:selectable]. - - - - - - The number of lines at the end of which the title label will be ellipsized. - -If the value is 0, the number of lines won't be limited. - - - - - - - This signal is emitted after the row has been activated. +The name is displayed at the top of the main page. + Use [class@AboutDialog]. + - - - - - - The parent class - - - - - - - - - - - an action row - - - - - - - - - - - - - A base class for animations. - -`AdwAnimation` represents an animation on a widget. It has a target that -provides a value to animate, and a state indicating whether the -animation hasn't been started yet, is playing, paused or finished. - -Currently there are two concrete animation types: -[class@TimedAnimation] and [class@SpringAnimation]. - -`AdwAnimation` will automatically skip the animation if -[property@Animation:widget] is unmapped, or if -[property@Gtk.Settings:gtk-enable-animations] is `FALSE`. - -The [signal@Animation::done] signal can be used to perform an action after -the animation ends, for example hiding a widget after animating its -[property@Gtk.Widget:opacity] to 0. - -`AdwAnimation` will be kept alive while the animation is playing. As such, -it's safe to create an animation, start it and immediately unref it: -A fire-and-forget animation: - -```c -static void -animation_cb (double value, - MyObject *self) -{ - // Do something with @value -} - -static void -my_object_animate (MyObject *self) -{ - AdwAnimationTarget *target = - adw_callback_animation_target_new ((AdwAnimationTargetFunc) animation_cb, - self, NULL); - g_autoptr (AdwAnimation) animation = - adw_timed_animation_new (widget, 0, 1, 250, target); - - adw_animation_play (animation); -} -``` - -If there's a chance the previous animation for the same target hasn't yet -finished, the previous animation should be stopped first, or the existing -`AdwAnimation` object can be reused. - - - - Gets whether @self should be skipped when animations are globally disabled. - - - whether to follow the global setting - - an animation - + filename="src/adw-about-window.c" + line="2245">an about window + + + the application name + + - - + Gets the current value of @self. + filename="src/adw-about-window.c" + line="2978">Sets the list of artists of the application. -The state indicates whether @self is currently playing, paused, finished or -hasn't been started yet. - +It will be displayed on the Credits page. + +Each name may contain email addresses and URLs, see the introduction for more +details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + - the animation value - + an animation - + filename="src/adw-about-window.c" + line="2980">an about window + + + the list of artists + + + + - - + Gets the target @self animates. - + filename="src/adw-about-window.c" + line="2515">Sets the comments about the application. + +Comments will be shown on the Details page, above links. + +Unlike [property@Gtk.AboutDialog:comments], this string can be long and +detailed. It can also contain links and Pango markup. + Use [class@AboutDialog]. + - the animation target - + an animation - + filename="src/adw-about-window.c" + line="2517">an about window + + + the comments + + - - + Gets the current value of @self. - + filename="src/adw-about-window.c" + line="3245">Sets the copyright information for @self. + +This should be a short string of one or two lines, for example: +`© 2022 Example`. + +The copyright information will be displayed on the Legal page, before the +application license. + +[method@AboutWindow.add_legal_section] can be used to add copyright +information for the application dependencies or other components. + Use [class@AboutDialog]. + - the current value - + an animation - + filename="src/adw-about-window.c" + line="3247">an about window + + + the copyright information + + - - + Gets the widget @self was created for. + filename="src/adw-about-window.c" + line="2757">Sets the debug information for @self. -It provides the frame clock for the animation. It's not strictly necessary -for this widget to be same as the one being animated. +Debug information will be shown on the Troubleshooting page. It's intended +to be attached to issue reports when reporting issues against the +application. -The widget must be mapped in order for the animation to work. If it's not -mapped, or if it gets unmapped during an ongoing animation, the animation -will be automatically skipped. - +`AdwAboutWindow` provides a quick way to save debug information to a file. +When saving, [property@AboutWindow:debug-info-filename] would be used as +the suggested filename. + +Debug information cannot contain markup or links. + Use [class@AboutDialog]. + - the animation widget - + an animation - + filename="src/adw-about-window.c" + line="2759">an about window + + + the debug information + + - + Pauses a playing animation for @self. + filename="src/adw-about-window.c" + line="2811">Sets the debug information filename for @self. -Does nothing if the current state of @self isn't `ADW_ANIMATION_PLAYING`. +It will be used as the suggested filename when saving debug information to a +file. -Sets [property@Animation:state] to `ADW_ANIMATION_PAUSED`. - +See [property@AboutWindow:debug-info]. + Use [class@AboutDialog]. + an animation - + filename="src/adw-about-window.c" + line="2813">an about window + + + the debug info filename + + - + Starts the animation for @self. + filename="src/adw-about-window.c" + line="2918">Sets the list of designers of the application. -If the animation is playing, paused or has been completed, restarts it from -the beginning. This allows to easily play an animation regardless of whether -it's already playing or not. +It will be displayed on the Credits page. -Sets [property@Animation:state] to `ADW_ANIMATION_PLAYING`. +Each name may contain email addresses and URLs, see the introduction for more +details. -The animation will be automatically skipped if [property@Animation:widget] is -unmapped, or if [property@Gtk.Settings:gtk-enable-animations] is `FALSE`. +See also: -As such, it's not guaranteed that the animation will actually run. For -example, when using [func@GLib.idle_add] and starting an animation -immediately afterwards, it's entirely possible that the idle callback will -run after the animation has already finished, and not while it's playing. - +* [property@AboutWindow:developers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + an animation - + filename="src/adw-about-window.c" + line="2920">an about window + + + the list of designers + + + + - + Resets the animation for @self. + filename="src/adw-about-window.c" + line="2290">Sets the developer name for @self. -Sets [property@Animation:state] to `ADW_ANIMATION_IDLE`. - +The developer name is displayed on the main page, under the application name. + +If the application is developed by multiple people, the developer name can be +set to values like "AppName team", "AppName developers" or +"The AppName project", and the individual contributors can be listed on the +Credits page, with [property@AboutWindow:developers] and related properties. + Use [class@AboutDialog]. + an animation - + filename="src/adw-about-window.c" + line="2292">an about window + + + the developer name + + - + Resumes a paused animation for @self. + filename="src/adw-about-window.c" + line="2858">Sets the list of developers of the application. -This function must only be used if the animation has been paused with -[method@Animation.pause]. +It will be displayed on the Credits page. -Sets [property@Animation:state] to `ADW_ANIMATION_PLAYING`. - +Each name may contain email addresses and URLs, see the introduction for more +details. + +See also: + +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + an animation - + filename="src/adw-about-window.c" + line="2860">an about window + + + the list of developers + + + + - - + Sets whether to skip @self when animations are globally disabled. + filename="src/adw-about-window.c" + line="3038">Sets the list of documenters of the application. -The default behavior is to skip the animation. Set to `FALSE` to disable this -behavior. +It will be displayed on the Credits page. -This can be useful for cases where animation is essential, like spinners, or -in demo applications. Most other animations should keep it enabled. +Each name may contain email addresses and URLs, see the introduction for more +details. -See [property@Gtk.Settings:gtk-enable-animations]. - - +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + + an animation - + filename="src/adw-about-window.c" + line="3040">an about window + - + whether to follow the global setting - + filename="src/adw-about-window.c" + line="3041">the list of documenters + + + - - + Sets the target @self animates to @target. - + filename="src/adw-about-window.c" + line="2659">Sets the issue tracker URL for @self. + +The issue tracker link is displayed on the main page. + Use [class@AboutDialog]. + an animation - + filename="src/adw-about-window.c" + line="2661">an about window + - + an animation target - + filename="src/adw-about-window.c" + line="2662">the issue tracker URL + - + Skips the animation for @self. + filename="src/adw-about-window.c" + line="3364">Sets the license for @self. -If the animation hasn't been started yet, is playing, or is paused, instantly -skips the animation to the end and causes [signal@Animation::done] to be -emitted. +This can be used to set a custom text for the license if it can't be set via +[property@AboutWindow:license-type]. -Sets [property@Animation:state] to `ADW_ANIMATION_FINISHED`. - +When set, [property@AboutWindow:license-type] will be set to +`GTK_LICENSE_CUSTOM`. + +The license text will be displayed on the Legal page, below the copyright +information. + +License text can contain Pango markup and links. + +[method@AboutWindow.add_legal_section] can be used to add license information +for the application dependencies or other components. + Use [class@AboutDialog]. + an animation - + filename="src/adw-about-window.c" + line="3366">an about window + + + the license + + - - - + Whether to skip the animation when animations are globally disabled. - -The default behavior is to skip the animation. Set to `FALSE` to disable -this behavior. + filename="src/adw-about-window.c" + line="3298">Sets the license for @self from a list of known licenses. -This can be useful for cases where animation is essential, like spinners, -or in demo applications. Most other animations should keep it enabled. +If the application's license is not in the list, +[property@AboutWindow:license] can be used instead. The license type will be +automatically set to `GTK_LICENSE_CUSTOM` in that case. -See [property@Gtk.Settings:gtk-enable-animations]. - - - - - The animation state. +If @license_type is `GTK_LICENSE_UNKNOWN`, no information will be displayed. -The state indicates whether the animation is currently playing, paused, -finished or hasn't been started yet. - - - - - - The target to animate. - - - - - The current value of the animation. - - - - - The animation widget. +If @license_type is different from `GTK_LICENSE_CUSTOM`. +[property@AboutWindow:license] will be cleared out. -It provides the frame clock for the animation. It's not strictly necessary -for this widget to be same as the one being animated. +The license description will be displayed on the Legal page, below the +copyright information. -The widget must be mapped in order for the animation to work. If it's not -mapped, or if it gets unmapped during an ongoing animation, the animation -will be automatically skipped. - - - - - - - This signal is emitted when the animation has been completed, either on its -own or via calling [method@Animation.skip]. +[method@AboutWindow.add_legal_section] can be used to add license information +for the application dependencies or other components. + Use [class@AboutDialog]. + - - - - - - - Describes the possible states of an [class@Animation]. - -The state can be controlled with [method@Animation.play], -[method@Animation.pause], [method@Animation.resume], -[method@Animation.reset] and [method@Animation.skip]. - - The animation hasn't started yet. - - - The animation has been paused. - - - The animation is currently playing. - - + + + an about window + + + + the license type + + + + + The animation has finished. - - - - Represents a value [class@Animation] can animate. - - - - - - - Prototype for animation targets based on user callbacks. - - - - - - - The animation value - - - - The user data provided when creating the target - - - - - - A base class for Adwaita applications. + filename="src/adw-about-window.c" + line="2447">Sets the release notes for @self. -`AdwApplication` handles library initialization by calling [func@init] in the -default [signal@Gio.Application::startup] signal handler, in turn chaining up -as required by [class@Gtk.Application]. Therefore, any subclass of -`AdwApplication` should always chain up its `startup` handler before using -any Adwaita or GTK API. +Release notes are displayed on the the What's New page. -## Automatic Resources +Release notes are formatted the same way as +[AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). -`AdwApplication` will automatically load stylesheets located in the -application's resource base path (see -[method@Gio.Application.set_resource_base_path], if they're present. +The supported formatting options are: -They can be used to add custom styles to the application, as follows: +* Paragraph (`<p>`) +* Ordered list (`<ol>`), with list items (`<li>`) +* Unordered list (`<ul>`), with list items (`<li>`) -- `style.css` contains styles that are always present. +Within paragraphs and list items, emphasis (`<em>`) and inline code +(`<code>`) text styles are supported. The emphasis is rendered in italic, +while inline code is shown in a monospaced font. -- `style-dark.css` contains styles only used when -[property@StyleManager:dark] is `TRUE`. +Any text outside paragraphs or list items is ignored. -- `style-hc.css` contains styles used when the system high contrast - preference is enabled. +Nested lists are not supported. -- `style-hc-dark.css` contains styles used when the system high contrast - preference is enabled and [property@StyleManager:dark] is `TRUE`. - - - - +`AdwAboutWindow` displays the version above the release notes. If set, the +[property@AboutWindow:release-notes-version] of the property will be used +as the version; otherwise, [property@AboutWindow:version] is used. + Use [class@AboutDialog]. + + + + + + + an about window + + + + the release notes + + + + + Creates a new `AdwApplication`. + filename="src/adw-about-window.c" + line="2391">Sets the version described by the application's release notes. -If `application_id` is not `NULL`, then it must be valid. See -[func@Gio.Application.id_is_valid]. +The release notes version is displayed on the What's New page, above the +release notes. -If no application ID is given then some features (most notably application -uniqueness) will be disabled. - - - the newly created `AdwApplication` - +If not set, [property@AboutWindow:version] will be used instead. + +For example, an application with the current version 2.0.2 might want to +keep the release notes from 2.0.0, and set the release notes version +accordingly. + +See [property@AboutWindow:release-notes]. + Use [class@AboutDialog]. + + + - + The application ID - - - + filename="src/adw-about-window.c" + line="2393">an about window + + + The application flags - + filename="src/adw-about-window.c" + line="2394">the release notes version + - - - + + Gets the style manager for @self. + filename="src/adw-about-window.c" + line="2613">Sets the URL of the support page for @self. -This is a convenience property allowing to access `AdwStyleManager` through -property bindings or expressions. - +The support page link is displayed on the main page. + Use [class@AboutDialog]. + - the style manager - + an application - + filename="src/adw-about-window.c" + line="2615">an about window + + + the support page URL + + - - - The style manager for this application. - -This is a convenience property allowing to access `AdwStyleManager` through -property bindings or expressions. - - - - - - - - - + The parent class - - - - - - - - - - A freeform application window. + filename="src/adw-about-window.c" + line="3098">Sets the translator credits string. -<picture> - <source srcset="application-window-dark.png" media="(prefers-color-scheme: dark)"> - <img src="application-window.png" alt="application-window"> -</picture> +It will be displayed on the Credits page. -`AdwApplicationWindow` is a [class@Gtk.ApplicationWindow] subclass providing -the same features as [class@Window]. +This string should be `"translator-credits"` or `"translator_credits"` and +should be marked as translatable. -See [class@Window] for details. +The string may contain email addresses and URLs, see the introduction for +more details. -Example of an `AdwApplicationWindow` UI definition: +See also: -```xml -<object class="AdwApplicationWindow"> - <property name="content"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"/> - </child> - <property name="content"> - <!-- ... --> - </property> - </object> - </property> -</object> -``` - -Using [property@Gtk.Application:menubar] is not supported and may result in -visual glitches. - - - - - - - - - - - Creates a new `AdwApplicationWindow` for @app. - - - the newly created `AdwApplicationWindow` - - - - - an application instance - - - - - - Adds @breakpoint to @self. - +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + an application window - + filename="src/adw-about-window.c" + line="3100">an about window + - + the breakpoint to add - + filename="src/adw-about-window.c" + line="3101">the translator credits + - - + Gets the content widget of @self. + filename="src/adw-about-window.c" + line="2342">Sets the version for @self. -This method should always be used instead of [method@Gtk.Window.get_child]. - - - the content widget of @self - +The version is displayed on the main page. + +If [property@AboutWindow:release-notes-version] is not set, the version will +also be displayed above the release notes on the What's New page. + Use [class@AboutDialog]. + + + an application window - + filename="src/adw-about-window.c" + line="2344">an about window + - - - - - Gets the current breakpoint. - - - the current breakpoint - - - - + an application window - - + filename="src/adw-about-window.c" + line="2345">the version + + - - + Sets the content widget of @self. + filename="src/adw-about-window.c" + line="2564">Sets the application website URL for @self. -This method should always be used instead of [method@Gtk.Window.set_child]. - +Website is displayed on the Details page, below comments, or on the main page +if the Details page doesn't have any other content. + +Applications can add other links below, see [method@AboutWindow.add_link]. + Use [class@AboutDialog]. + an application window - + filename="src/adw-about-window.c" + line="2566">an about window + - + the content widget - + filename="src/adw-about-window.c" + line="2567">the website URL + - - - + setter="set_application_icon" + getter="get_application_icon"> The content widget. + filename="src/adw-about-window.c" + line="1387">The name of the application icon. -This property should always be used instead of [property@Gtk.Window:child]. - +The icon is displayed at the top of the main page. + Use [class@AboutDialog]. + - - + setter="set_application_name" + getter="get_application_name"> The current breakpoint. - + filename="src/adw-about-window.c" + line="1402">The name of the application. + +The name is displayed at the top of the main page. + Use [class@AboutDialog]. + - - - - - - - - - - - - + + The list of artists of the application. + +It will be displayed on the Credits page. + +Each name may contain email addresses and URLs, see the introduction for +more details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + + - - - - A widget displaying an image, with a generated fallback. + + + The comments about the application. -<picture> - <source srcset="avatar-dark.png" media="(prefers-color-scheme: dark)"> - <img src="avatar.png" alt="avatar"> -</picture> +Comments will be shown on the Details page, above links. -`AdwAvatar` is a widget that shows a round avatar. +Unlike [property@Gtk.AboutDialog:comments], this string can be long and +detailed. It can also contain links and Pango markup. + Use [class@AboutDialog]. + + + + The copyright information. -`AdwAvatar` generates an avatar with the initials of the -[property@Avatar:text] on top of a colored background. +This should be a short string of one or two lines, for example: +`© 2022 Example`. -The color is picked based on the hash of the [property@Avatar:text]. +The copyright information will be displayed on the Legal page, above the +application license. -If [property@Avatar:show-initials] is set to `FALSE`, -[property@Avatar:icon-name] or `avatar-default-symbolic` is shown instead of -the initials. +[method@AboutWindow.add_legal_section] can be used to add copyright +information for the application dependencies or other components. + Use [class@AboutDialog]. + + + + The debug information. -Use [property@Avatar:custom-image] to set a custom image. +Debug information will be shown on the Troubleshooting page. It's intended +to be attached to issue reports when reporting issues against the +application. -## CSS nodes +`AdwAboutWindow` provides a quick way to save debug information to a file. +When saving, [property@AboutWindow:debug-info-filename] would be used as +the suggested filename. -`AdwAvatar` has a single CSS node with name `avatar`. - - - - - +Debug information cannot contain markup or links. + Use [class@AboutDialog]. + + + Creates a new `AdwAvatar`. - - - the newly created `AdwAvatar` - - - - - The size of the avatar - - - - the text used to get the initials and color - - - - whether to use initials instead of an icon as fallback - - - - - + filename="src/adw-about-window.c" + line="1606">The debug information filename. + +It will be used as the suggested filename when saving debug information to +a file. + +See [property@AboutWindow:debug-info]. + Use [class@AboutDialog]. + + + Renders @self into a [class@Gdk.Texture] at @scale_factor. + filename="src/adw-about-window.c" + line="1651">The list of designers of the application. -This can be used to export the fallback avatar. - - - the texture - - - - - an avatar - - - - The scale factor - - - - - - +It will be displayed on the Credits page. + +Each name may contain email addresses and URLs, see the introduction for +more details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + + + + + Gets the custom image paintable. - - - the custom image - - - - - an avatar - - - - - - + filename="src/adw-about-window.c" + line="1417">The developer name. + +The developer name is displayed on the main page, under the application +name. + +If the application is developed by multiple people, the developer name can +be set to values like "AppName team", "AppName developers" or +"The AppName project", and the individual contributors can be listed on the +Credits page, with [property@AboutWindow:developers] and related +properties. + Use [class@AboutDialog]. + + + Gets the name of an icon to use as a fallback. - - - the icon name - - - - - an avatar - - - - - - + filename="src/adw-about-window.c" + line="1624">The list of developers of the application. + +It will be displayed on the Credits page. + +Each name may contain email addresses and URLs, see the introduction for +more details. + +See also: + +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + + + + + Gets whether initials are used instead of an icon on the fallback avatar. - - - whether initials are used instead of an icon as fallback - - - - - an avatar - - - - - - + filename="src/adw-about-window.c" + line="1705">The list of documenters of the application. + +It will be displayed on the Credits page. + +Each name may contain email addresses and URLs, see the introduction for +more details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:translator-credits] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + + + + + Gets the size of the avatar. - - - the size of the avatar - + filename="src/adw-about-window.c" + line="1568">The URL for the application's issue tracker. + +The issue tracker link is displayed on the main page. + Use [class@AboutDialog]. + + + + The license text. + +This can be used to set a custom text for the license if it can't be set +via [property@AboutWindow:license-type]. + +When set, [property@AboutWindow:license-type] will be set to +`GTK_LICENSE_CUSTOM`. + +The license text will be displayed on the Legal page, below the copyright +information. + +License text can contain Pango markup and links. + +[method@AboutWindow.add_legal_section] can be used to add license +information for the application dependencies or other components. + Use [class@AboutDialog]. + + + + The license type. + +Allows to set the application's license froma list of known licenses. + +If the application's license is not in the list, +[property@AboutWindow:license] can be used instead. The license type will +be automatically set to `GTK_LICENSE_CUSTOM` in that case. + +If set to `GTK_LICENSE_UNKNOWN`, no information will be displayed. + +If the license type is different from `GTK_LICENSE_CUSTOM`. +[property@AboutWindow:license] will be cleared out. + +The license description will be displayed on the Legal page, below the +copyright information. + +[method@AboutWindow.add_legal_section] can be used to add license +information for the application dependencies or other components. + Use [class@AboutDialog]. + + + + The release notes of the application. + +Release notes are displayed on the the What's New page. + +Release notes are formatted the same way as +[AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). + +The supported formatting options are: + +* Paragraph (`<p>`) +* Ordered list (`<ol>`), with list items (`<li>`) +* Unordered list (`<ul>`), with list items (`<li>`) + +Within paragraphs and list items, emphasis (`<em>`) and inline code +(`<code>`) text styles are supported. The emphasis is rendered in italic, +while inline code is shown in a monospaced font. + +Any text outside paragraphs or list items is ignored. + +Nested lists are not supported. + +`AdwAboutWindow` displays the version above the release notes. If set, the +[property@AboutWindow:release-notes-version] of the property will be used +as the version; otherwise, [property@AboutWindow:version] is used. + Use [class@AboutDialog]. + + + + The version described by the application's release notes. + +The release notes version is displayed on the What's New page, above the +release notes. + +If not set, [property@AboutWindow:version] will be used instead. + +For example, an application with the current version 2.0.2 might want to +keep the release notes from 2.0.0, and set the release notes version +accordingly. + +See [property@AboutWindow:release-notes]. + Use [class@AboutDialog]. + + + + The URL of the application's support page. + +The support page link is displayed on the main page. + Use [class@AboutDialog]. + + + + The translator credits string. + +It will be displayed on the Credits page. + +This string should be `"translator-credits"` or `"translator_credits"` and +should be marked as translatable. + +The string may contain email addresses and URLs, see the introduction for +more details. + +See also: + +* [property@AboutWindow:developers] +* [property@AboutWindow:designers] +* [property@AboutWindow:artists] +* [property@AboutWindow:documenters] +* [method@AboutWindow.add_credit_section] +* [method@AboutWindow.add_acknowledgement_section] + Use [class@AboutDialog]. + + + + The version of the application. + +The version is displayed on the main page. + +If [property@AboutWindow:release-notes-version] is not set, the version +will also be displayed above the release notes on the What's New page. + Use [class@AboutDialog]. + + + + The URL of the application's website. + +Website is displayed on the Details page, below comments, or on the main +page if the Details page doesn't have any other content. + +Applications can add other links below, see [method@AboutWindow.add_link]. + Use [class@AboutDialog]. + + + + Emitted when a URL is activated. + +Applications may connect to it to override the default behavior, which is +to call [func@Gtk.show_uri]. + Use [class@AboutDialog]. + + `TRUE` if the link has been activated + - + an avatar - - + filename="src/adw-about-window.c" + line="1847">the URI to activate + + - - - + + + + + + + + + + Describes the available system accent colors. + Gets the text used to generate the fallback initials and color. - - - the text used to generate the fallback initials and - color - + filename="src/adw-accent-color.c" + line="16">Use a blue color (`#3584e4`). This is the default value. + + + Use a teal color (`#2190a4`). + + + Use a green color (`#3a944a`). + + + Use a yellow color (`#c88800`). + + + Use a orange color (`#ed5b00`). + + + Use a red color (`#e62d42`). + + + Use a pink color (`#d56199`). + + + Use a purple color (`#9141ac`). + + + Use a slate color (`#6f8396`). + + + Converts @self to a `GdkRGBA` representing its background color. + +The matching foreground color is white. + + + - + an avatar - - + filename="src/adw-accent-color.c" + line="33">an accent color + + + + return location for the color + + - - - + + Sets the custom image paintable. + filename="src/adw-accent-color.c" + line="88">Converts @self to a `GdkRGBA` representing its standalone color. -Custom image is displayed instead of initials or icon. - +It will typically be darker for light background, and lighter for dark +background, ensuring contrast. + - + an avatar - - - + filename="src/adw-accent-color.c" + line="90">an accent color + + + a custom image - + filename="src/adw-accent-color.c" + line="91">Whether to calculate standalone color for light or dark background + + + + return location for the color + - - - - Sets the name of an icon to use as a fallback. + + + + A [class@Gtk.ListBoxRow] used to present actions. -If no name is set, `avatar-default-symbolic` will be used. - +<picture> + <source srcset="action-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="action-row.png" alt="action-row"> +</picture> + +The `AdwActionRow` widget can have a title, a subtitle and an icon. The row +can receive additional widgets at its end, or prefix widgets at its start. + +It is convenient to present a preference and its related actions. + +`AdwActionRow` is unactivatable by default, giving it an activatable widget +will automatically make it activatable, but unsetting it won't change the +row's activatability. + +## AdwActionRow as GtkBuildable + +The `AdwActionRow` implementation of the [iface@Gtk.Buildable] interface +supports adding a child at its end by specifying “suffix” or omitting the +“type” attribute of a <child> element. + +It also supports adding a child as a prefix widget by specifying “prefix” as +the “type” attribute of a <child> element. + +## CSS nodes + +`AdwActionRow` has a main CSS node with name `row`. + +It contains the subnode `box.header` for its main horizontal box, and +`box.title` for the vertical box containing the title and subtitle labels. + +It contains subnodes `label.title` and `label.subtitle` representing +respectively the title label and subtitle label. + +## Style classes + +`AdwActionRow` can use the [`.property`](style-classes.html#property-rows) +style class to emphasize the row subtitle instead of the row title, which is +useful for displaying read-only properties. + +<picture> + <source srcset="property-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="property-row.png" alt="property-row"> +</picture> + +When used together with the `.monospace` style class, only the subtitle +becomes monospace, not the title or any extra widgets. + + + + + + + Creates a new `AdwActionRow`. + + + the newly created `AdwActionRow` + + + + + Activates @self. + an avatar - + filename="src/adw-action-row.c" + line="887">an action row + - - the icon name - - - - - + + Sets whether to use initials instead of an icon on the fallback avatar. - -See [property@Avatar:icon-name] for how to change the fallback icon. - + filename="src/adw-action-row.c" + line="885">Activates @self. + an avatar - + filename="src/adw-action-row.c" + line="887">an action row + - - whether to use initials instead of an icon as fallback - - - - + Sets the size of the avatar. - + filename="src/adw-action-row.c" + line="458">Adds a prefix widget to @self. + an avatar - + filename="src/adw-action-row.c" + line="460">an action row + - + The size of the avatar - + filename="src/adw-action-row.c" + line="461">a widget + - - + Sets the text used to generate the fallback initials and color. - -It's only used to generate the color if [property@Avatar:show-initials] is -`FALSE`. - + filename="src/adw-action-row.c" + line="481">Adds a suffix widget to @self. + an avatar - + filename="src/adw-action-row.c" + line="483">an action row + - + the text used to get the initials and color - + filename="src/adw-action-row.c" + line="484">a widget + - - - - A custom image paintable. - -Custom image is displayed instead of initials or icon. - - - - - - The name of an icon to use as a fallback. - -If no name is set, `avatar-default-symbolic` will be used. - - - - - + Whether initials are used instead of an icon on the fallback avatar. - -See [property@Avatar:icon-name] for how to change the fallback icon. - - - - - + filename="src/adw-action-row.c" + line="633">Gets the widget activated when @self is activated. + + + the activatable widget for @self + + + + + an action row + + + + + The size of the avatar. - - - - - - Sets the text used to generate the fallback initials and color. - -It's only used to generate the color if [property@Avatar:show-initials] is -`FALSE`. - - - - - - - - - - - A bar with contextual information. - -<picture> - <source srcset="banner-dark.png" media="(prefers-color-scheme: dark)"> - <img src="banner.png" alt="banner"> -</picture> - -Banners are hidden by default, use [property@Banner:revealed] to show them. - -Banners have a title, set with [property@Banner:title]. Titles can be marked -up with Pango markup, use [property@Banner:use-markup] to enable it. - -The title will be shown centered or left-aligned depending on available -space. - -Banners can optionally have a button with text on it, set through -[property@Banner:button-label]. The button can be used with a `GAction`, -or with the [signal@Banner::button-clicked] signal. - -## CSS nodes - -`AdwBanner` has a main CSS node with the name `banner`. - - - - - - - Creates a new `AdwBanner`. - - + filename="src/adw-action-row.c" + line="582">Gets the icon name for @self. + Use [method@ActionRow.add_prefix] to add an icon. + + the newly created `AdwBanner` - + filename="src/adw-action-row.c" + line="588">the icon name for @self + - + the banner title - - + filename="src/adw-action-row.c" + line="584">an action row + + - - - + + Gets the button label for @self. - + filename="src/adw-action-row.c" + line="534">Gets the subtitle for @self. + the button label for @self + filename="src/adw-action-row.c" + line="540">the subtitle for @self a banner - + filename="src/adw-action-row.c" + line="536">an action row + - - + Gets if a banner is revealed - + filename="src/adw-action-row.c" + line="782">Gets the number of lines at the end of which the subtitle label will be +ellipsized. + Whether a banner is revealed - + filename="src/adw-action-row.c" + line="789">the number of lines at the end of which the subtitle label will be + ellipsized + a banner - + filename="src/adw-action-row.c" + line="784">an action row + - - Gets the title for @self. - + filename="src/adw-action-row.c" + line="836">Gets whether the user can copy the subtitle from the label + the title for @self - + filename="src/adw-action-row.c" + line="842">whether the user can copy the subtitle from the label + a banner - + filename="src/adw-action-row.c" + line="838">an action row + - - + Gets whether to use Pango markup for the banner title. - + filename="src/adw-action-row.c" + line="728">Gets the number of lines at the end of which the title label will be +ellipsized. + whether to use markup - + filename="src/adw-action-row.c" + line="735">the number of lines at the end of which the title label will be + ellipsized + a banner - + filename="src/adw-action-row.c" + line="730">an action row + - - + Sets the button label for @self. + filename="src/adw-action-row.c" + line="504">Removes a child from @self. + + + + + + + an action row + + + + the child to be removed + + + + + + Sets the widget to activate when @self is activated. -If set to `""` or `NULL`, the button won't be shown. +The row can be activated either by clicking on it, calling +[method@ActionRow.activate], or via mnemonics in the title. +See the [property@PreferencesRow:use-underline] property to enable mnemonics. -The button can be used with a `GAction`, or with the -[signal@Banner::button-clicked] signal. - +The target widget will be activated by emitting the +[signal@Gtk.Widget::mnemonic-activate] signal on it. + a banner - + filename="src/adw-action-row.c" + line="668">an action row + - the label - + filename="src/adw-action-row.c" + line="669">the target widget + - - + Sets whether a banner should be revealed - + filename="src/adw-action-row.c" + line="604">Sets the icon name for @self. + Use [method@ActionRow.add_prefix] to add an icon. + a banner - + filename="src/adw-action-row.c" + line="606">an action row + - + whether a banner should be revealed - + filename="src/adw-action-row.c" + line="607">the icon name + - - + Sets the title for this banner. + filename="src/adw-action-row.c" + line="554">Sets the subtitle for @self. -See also: [property@Banner:use-markup]. - +The subtitle is interpreted as Pango markup unless +[property@PreferencesRow:use-markup] is set to `FALSE`. + a banner - + filename="src/adw-action-row.c" + line="556">an action row + - + the title + filename="src/adw-action-row.c" + line="557">the subtitle - + Sets the number of lines at the end of which the subtitle label will be +ellipsized. + +If the value is 0, the number of lines won't be limited. + + + + + + + an action row + + + + the number of lines at the end of which the subtitle label will be ellipsized + + + + + - Sets whether to use Pango markup for the banner title. + filename="src/adw-action-row.c" + line="856">Sets whether the user can copy the subtitle from the label -See also [func@Pango.parse_markup]. - +See also [property@Gtk.Label:selectable]. + a banner - + filename="src/adw-action-row.c" + line="858">an action row + - + whether to use markup + filename="src/adw-action-row.c" + line="859">`TRUE` if the user can copy the subtitle from the label - + Sets the number of lines at the end of which the title label will be +ellipsized. + +If the value is 0, the number of lines won't be limited. + + + + + + + an action row + + + + the number of lines at the end of which the title label will be ellipsized + + + + + - - + setter="set_activatable_widget" + getter="get_activatable_widget"> The label to show on the button. + filename="src/adw-action-row.c" + line="317">The widget to activate when the row is activated. -If set to `""` or `NULL`, the button won't be shown. +The row can be activated either by clicking on it, calling +[method@ActionRow.activate], or via mnemonics in the title. +See the [property@PreferencesRow:use-underline] property to enable +mnemonics. -The button can be used with a `GAction`, or with the -[signal@Banner::button-clicked] signal. - +The target widget will be activated by emitting the +[signal@Gtk.Widget::mnemonic-activate] signal on it. + - - - + setter="set_icon_name" + getter="get_icon_name"> Whether the banner is currently revealed. - + filename="src/adw-action-row.c" + line="305">The icon name for this row. + Use [method@ActionRow.add_prefix] to add an icon. + - - - + setter="set_subtitle" + getter="get_subtitle"> The title for this banner. + filename="src/adw-action-row.c" + line="292">The subtitle for this row. -See also: [property@Banner:use-markup]. +The subtitle is interpreted as Pango markup unless +[property@PreferencesRow:use-markup] is set to `FALSE`. - + The number of lines at the end of which the subtitle label will be +ellipsized. + +If the value is 0, the number of lines won't be limited. + + + - - + setter="set_subtitle_selectable" + getter="get_subtitle_selectable" + default-value="FALSE"> Whether to use Pango markup for the banner title. + filename="src/adw-action-row.c" + line="362">Whether the user can copy the subtitle from the label. -See also [func@Pango.parse_markup]. +See also [property@Gtk.Label:selectable]. - + This signal is emitted after the action button has been clicked. + filename="src/adw-action-row.c" + line="335">The number of lines at the end of which the title label will be ellipsized. -It can be used as an alternative to setting an action. +If the value is 0, the number of lines won't be limited. + + + + + + + This signal is emitted after the row has been activated. - - + + - + The parent class + + + + Activates the row to trigger its main action. + + + + + + + + an action row + + + + + + + + + - + A widget with one child. + filename="src/adw-alert-dialog.c" + line="22">A dialog presenting a message or a question. <picture> - <source srcset="bin-dark.png" media="(prefers-color-scheme: dark)"> - <img src="bin.png" alt="bin"> + <source srcset="alert-dialog-dark.png" media="(prefers-color-scheme: dark)"> + <img src="alert-dialog.png" alt="alert-dialog"> </picture> -The `AdwBin` widget has only one child, set with the [property@Bin:child] -property. +Alert dialogs have a heading, a body, an optional child widget, and one or +multiple responses, each presented as a button. -It is useful for deriving subclasses, since it provides common code needed -for handling a single child widget. - - - - - - Creates a new `AdwBin`. - - - the new created `AdwBin` - - - - - - Gets the child widget of @self. - - - the child widget of @self - - - - - a bin - - - - - - - Sets the child widget of @self. - - - - - - - a bin - - - - the child widget - - - - - - - - The child widget of the `AdwBin`. - - - - - - - - - - - - - - Describes a breakpoint for [class@Window]. +Each response has a unique string ID, and a button label. Additionally, each +response can be enabled or disabled, and can have a suggested or destructive +appearance. -Breakpoints are used to create adaptive UI, allowing to change the layout -depending on available size. +When one of the responses is activated, or the dialog is closed, the +[signal@AlertDialog::response] signal will be emitted. This signal is +detailed, and the detail, as well as the `response` parameter will be set to +the ID of the activated response, or to the value of the +[property@AlertDialog:close-response] property if the dialog had been closed +without activating any of the responses. -Breakpoint is a size threshold, specified by its condition, as well as one or -more setters. +Response buttons can be presented horizontally or vertically depending on +available space. -Each setter has a target object, a property and a value. When a breakpoint -is applied, each setter sets the target property on their target object to -the specified value, and reset it back to the original value when it's -unapplied. +When a response is activated, `AdwAlertDialog` is closed automatically. -For more complicated scenarios, [signal@Breakpoint::apply] and -[signal@Breakpoint::unapply] can be used instead. +An example of using an alert dialog: -Breakpoints can be used within [class@Window], [class@ApplicationWindow] or -[class@BreakpointBin]. +```c +AdwDialog *dialog; -## `AdwBreakpoint` as `GtkBuildable`: +dialog = adw_alert_dialog_new (_("Replace File?"), NULL); -`AdwBreakpoint` supports specifying its condition via the `<condition>` -element. The contents of the element must be a string in a format accepted by -[func@BreakpointCondition.parse]. +adw_alert_dialog_format_body (ADW_ALERT_DIALOG (dialog), + _("A file named “%s” already exists. Do you want to replace it?"), + filename); -It also supports adding setters via the `<setter>` element. Each `<setter>` -element must have the `object` attribute specifying the target object, and -the `property` attribute specifying the property name. The contents of the -element are used as the setter value. +adw_alert_dialog_add_responses (ADW_ALERT_DIALOG (dialog), + "cancel", _("_Cancel"), + "replace", _("_Replace"), + NULL); -For `G_TYPE_OBJECT` and `G_TYPE_BOXED` derived properties, empty contents are -treated as `NULL`. +adw_alert_dialog_set_response_appearance (ADW_ALERT_DIALOG (dialog), + "replace", + ADW_RESPONSE_DESTRUCTIVE); -Setter values can be translated with the usual `translatable`, `context` and -`comments` attributes. +adw_alert_dialog_set_default_response (ADW_ALERT_DIALOG (dialog), "cancel"); +adw_alert_dialog_set_close_response (ADW_ALERT_DIALOG (dialog), "cancel"); -Example of an `AdwBreakpoint` UI definition: +g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self); + +adw_dialog_present (dialog, parent); +``` + +## Async API + +`AdwAlertDialog` can also be used via the [method@AlertDialog.choose] method. +This API follows the GIO async pattern, for example: + +```c +static void +dialog_cb (AdwAlertDialog *dialog, + GAsyncResult *result, + MyWindow *self) +{ + const char *response = adw_alert_dialog_choose_finish (dialog, result); + + // ... +} + +static void +show_dialog (MyWindow *self) +{ + AdwDialog *dialog; + + dialog = adw_alert_dialog_new (_("Replace File?"), NULL); + + adw_alert_dialog_format_body (ADW_ALERT_DIALOG (dialog), + _("A file named “%s” already exists. Do you want to replace it?"), + filename); + + adw_alert_dialog_add_responses (ADW_ALERT_DIALOG (dialog), + "cancel", _("_Cancel"), + "replace", _("_Replace"), + NULL); + + adw_alert_dialog_set_response_appearance (ADW_ALERT_DIALOG (dialog), + "replace", + ADW_RESPONSE_DESTRUCTIVE); + + adw_alert_dialog_set_default_response (ADW_ALERT_DIALOG (dialog), "cancel"); + adw_alert_dialog_set_close_response (ADW_ALERT_DIALOG (dialog), "cancel"); + + adw_alert_dialog_choose (ADW_ALERT_DIALOG (dialog), GTK_WIDGET (self), + NULL, (GAsyncReadyCallback) dialog_cb, self); +} +``` + +## AdwAlertDialog as GtkBuildable + +`AdwAlertDialog` supports adding responses in UI definitions by via the +`<responses>` element that may contain multiple `<response>` elements, each +representing a response. + +Each of the `<response>` elements must have the `id` attribute specifying the +response ID. The contents of the element are used as the response label. + +Response labels can be translated with the usual `translatable`, `context` +and `comments` attributes. + +The `<response>` elements can also have `enabled` and/or `appearance` +attributes. See [method@AlertDialog.set_response_enabled] and +[method@AlertDialog.set_response_appearance] for details. + +Example of an `AdwAlertDialog` UI definition: ```xml -<object class="AdwBreakpoint"> - <condition>max-width: 400px</condition> - <setter object="button" property="visible">True</setter> - <setter object="box" property="orientation">vertical</setter> - <setter object="page" property="title" translatable="yes">Example</setter> +<object class="AdwAlertDialog" id="dialog"> + <property name="heading" translatable="yes">Save Changes?</property> + <property name="body" translatable="yes">Open documents contain unsaved changes. Changes which are not saved will be permanently lost.</property> + <property name="default-response">save</property> + <property name="close-response">cancel</property> + <signal name="response" handler="response_cb"/> + <responses> + <response id="cancel" translatable="yes">_Cancel</response> + <response id="discard" translatable="yes" appearance="destructive">_Discard</response> + <response id="save" translatable="yes" appearance="suggested" enabled="false">_Save</response> + </responses> </object> ``` - + + - + + + Creates a new `AdwBreakpoint` with @condition. - - + filename="src/adw-alert-dialog.c" + line="1339">Creates a new `AdwAlertDialog`. + +@heading and @body can be set to `NULL`. This can be useful if they need to +be formatted or use markup. In that case, set them to `NULL` and call +[method@AlertDialog.format_body] or similar methods afterwards: + +```c +AdwDialog *dialog; + +dialog = adw_alert_dialog_new (_("Replace File?"), NULL); +adw_alert_dialog_format_body (ADW_ALERT_DIALOG (dialog), + _("A file named “%s” already exists. Do you want to replace it?"), + filename); +``` + + the newly created `AdwBreakpoint` - + filename="src/adw-alert-dialog.c" + line="1359">the newly created `AdwAlertDialog` + - + the condition - + filename="src/adw-alert-dialog.c" + line="1341">the heading + + + + the body text + - + + + + + + + + + + + + + + + Adds a setter to @self. - -The setter will automatically set @property on @object to @value when -applying the breakpoint, and set it back to its original value upon -unapplying it. - -Note that setting properties to their original values does not work for -properties that have irreversible side effects. For example, changing -[property@Gtk.Button:label] while [property@Gtk.Button:icon-name] is set will -reset the icon. However, resetting the label will not set icon-name to its -original value. + filename="src/adw-alert-dialog.c" + line="1907">Adds a response with @id and @label to @self. -Use the [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] signals -for those properties instead, as follows: +Responses are represented as buttons in the dialog. -```c -static void -breakpoint_apply_cb (MyWidget *self) -{ - gtk_button_set_icon_name (self->button, "go-previous-symbolic"); -} +Response ID must be unique. It will be used in [signal@AlertDialog::response] +to tell which response had been activated, as well as to inspect and modify +the response later. -static void -breakpoint_apply_cb (MyWidget *self) -{ - gtk_button_set_label (self->button, _("_Back")); -} +An embedded underline in @label indicates a mnemonic. -// ... +[method@AlertDialog.set_response_label] can be used to change the response +label after it had been added. -g_signal_connect_swapped (breakpoint, "apply", - G_CALLBACK (breakpoint_apply_cb), self); -g_signal_connect_swapped (breakpoint, "unapply", - G_CALLBACK (breakpoint_unapply_cb), self); -``` - +[method@AlertDialog.set_response_enabled] and +[method@AlertDialog.set_response_appearance] can be used to customize the +responses further. + a breakpoint - + filename="src/adw-alert-dialog.c" + line="1909">an alert dialog + - - the target object - - - + the target property + filename="src/adw-alert-dialog.c" + line="1910">the response ID - + the value to set - + filename="src/adw-alert-dialog.c" + line="1911">the response label + - Adds multiple setters to @self. + filename="src/adw-alert-dialog.c" + line="1970">Adds multiple responses to @self. -See [method@Breakpoint.add_setter]. +This is the same as calling [method@AlertDialog.add_response] repeatedly. The +variable argument list should be `NULL`-terminated list of response IDs and +labels. Example: ```c -adw_breakpoint_add_setters (breakpoint, - G_OBJECT (box), "orientation", GTK_ORIENTATION_VERTICAL, - G_OBJECT (button), "halign", GTK_ALIGN_FILL, - G_OBJECT (button), "valign", GTK_ALIGN_END, - NULL); +adw_alert_dialog_add_responses (dialog, + "cancel", _("_Cancel"), + "discard", _("_Discard"), + "save", _("_Save"), + NULL); ``` - + a breakpoint - + filename="src/adw-alert-dialog.c" + line="1972">an alert dialog + - - the first target object - - - + the first target property + filename="src/adw-alert-dialog.c" + line="1973">response id the value of the first setter, followed by a list of object, property - and value triplets, terminated by `NULL` + filename="src/adw-alert-dialog.c" + line="1974">label for first response, then more id-label pairs - + Adds multiple setters to @self. + filename="src/adw-alert-dialog.c" + line="2454">This function shows @self to the user. -See [method@Breakpoint.add_setters]. - +If the window is an [class@Window] or [class@ApplicationWindow], the dialog +will be shown within it. Otherwise, it will be a separate window. + a breakpoint - + filename="src/adw-alert-dialog.c" + line="2456">an alert dialog + - + the first target object - + filename="src/adw-alert-dialog.c" + line="2457">the parent widget + - + the first target property - + filename="src/adw-alert-dialog.c" + line="2458">a `GCancellable` to cancel the operation + - + the value of the first setter, followed by a list of object, property - and value triplets, terminated by `NULL` - + filename="src/adw-alert-dialog.c" + line="2459">a callback to call when the operation is complete + + + + data to pass to @callback + - + Adds @n_setters setters to @self. - -This is a convenience function for adding multiple setters at once. - -See [method@Breakpoint.add_setter]. + filename="src/adw-alert-dialog.c" + line="2492">Finishes the [method@AlertDialog.choose] call and returns the response ID. + + + the ID of the response that was selected, or + [property@AlertDialog:close-response] if the call was cancelled. + + + + + an alert dialog + + + + a `GAsyncResult` + + + + + + Sets the formatted body text of @self. -This function is meant to be used by language bindings. - +See [property@AlertDialog:body]. + a breakpoint - + filename="src/adw-alert-dialog.c" + line="1704">an alert dialog + - + the number of setters to add - + filename="src/adw-alert-dialog.c" + line="1705">the formatted string for the body text + - + setter target object - - - + filename="src/adw-alert-dialog.c" + line="1706">the parameters to insert into @format + - + + + + Sets the formatted body text of @self with Pango markup. + +The @format is assumed to contain Pango markup. + +Special XML characters in the `printf()` arguments passed to this function +will automatically be escaped as necessary, see +[func@GLib.markup_printf_escaped]. + +See [property@AlertDialog:body]. + + + + + + setter target properties - - - + filename="src/adw-alert-dialog.c" + line="1747">an alert dialog + + + + the formatted string for the body text with Pango markup + - + setter values - - - + filename="src/adw-alert-dialog.c" + line="1749">the parameters to insert into @format + - - + Gets the condition for @self. - - - the condition - + filename="src/adw-alert-dialog.c" + line="1499">Sets the formatted heading of @self. + +See [property@AlertDialog:heading]. + + + a breakpoint - + filename="src/adw-alert-dialog.c" + line="1501">an alert dialog + + + the formatted string for the heading + + + + the parameters to insert into @format + + - - + Sets the condition for @self. - + filename="src/adw-alert-dialog.c" + line="1542">Sets the formatted heading of @self with Pango markup. + +The @format is assumed to contain Pango markup. + +Special XML characters in the `printf()` arguments passed to this function +will automatically be escaped as necessary, see +[func@GLib.markup_printf_escaped]. + +See [property@AlertDialog:heading]. + a breakpoint - + filename="src/adw-alert-dialog.c" + line="1544">an alert dialog + - + the new condition - + filename="src/adw-alert-dialog.c" + line="1545">the formatted string for the heading with Pango markup + + + + the parameters to insert into @format + - - - + The breakpoint's condition. - - - + filename="src/adw-alert-dialog.c" + line="1591">Gets the body text of @self. + + + the body of @self. + + + + + an alert dialog + + + + + Emitted when the breakpoint is applied. - -This signal is emitted after the setters have been applied. + filename="src/adw-alert-dialog.c" + line="1647">Gets whether the body text of @self includes Pango markup. + - + whether @self uses markup for body text + - - + + + an alert dialog + + + + + Emitted when the breakpoint is unapplied. - -This signal is emitted before resetting the setter values. + filename="src/adw-alert-dialog.c" + line="2345">Gets the ID of the close response of @self. + - + the close response ID + - - - - A widget that changes layout based on available size. - -<picture> - <source srcset="breakpoint-bin-dark.png" media="(prefers-color-scheme: dark)"> - <img src="breakpoint-bin.png" alt="breakpoint-bin"> -</picture> - -`AdwBreakpointBin` provides a way to use breakpoints without [class@Window] -or [class@ApplicationWindow]. It can be useful for limiting breakpoints to a -single page and similar purposes. Most applications shouldn't need it. - -`AdwBreakpointBin` is similar to [class@Bin]. It has one child, set via the -[property@BreakpointBin:child] property. - -When `AdwBreakpointBin` is resized, its child widget can rearrange its layout -at specific thresholds. - -The thresholds and layout changes are defined via [class@Breakpoint] objects. -They can be added using [method@BreakpointBin.add_breakpoint]. - -Each breakpoint has a condition, specifying the bin's size and/or aspect -ratio, and setters that automatically set object properties when that -happens. The [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] can -be used instead for more complex scenarios. - -Breakpoints are only allowed to modify widgets inside the `AdwBreakpointBin`, -but not on the `AdwBreakpointBin` itself or any other widgets. - -If multiple breakpoints can be used for the current size, the last one is -always picked. The current breakpoint can be tracked using the -[property@BreakpointBin:current-breakpoint] property. - -If none of the breakpoints can be used, that property will be set to `NULL`, -and the original property values will be used instead. - -## Minimum Size - -Adding a breakpoint to `AdwBreakpointBin` will result in it having no minimum -size. The [property@Gtk.Widget:width-request] and -[property@Gtk.Widget:height-request] properties must always be set when using -breakpoints, indicating the smallest size you want to support. - -The minimum size and breakpoint conditions must be carefully selected so that -the child widget completely fits. If it doesn't, it will overflow and a -warning message will be printed. - -When choosing minimum size, consider translations and text scale factor -changes. Make sure to leave enough space for text labels, and enable -ellipsizing or wrapping if they might not fit. - -For [class@Gtk.Label] this can be done via [property@Gtk.Label:ellipsize], or -via [property@Gtk.Label:wrap] together with [property@Gtk.Label:wrap-mode]. - -For buttons, use [property@Gtk.Button:can-shrink], -[property@Gtk.MenuButton:can-shrink], [property@Adw.SplitButton:can-shrink], -or [property@Adw.ButtonContent:can-shrink]. - -## Example - -```c -GtkWidget *bin, *child; -AdwBreakpoint *breakpoint; - -bin = adw_breakpoint_bin_new (); -gtk_widget_set_size_request (bin, 150, 150); - -child = gtk_label_new ("Wide"); -gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END); -gtk_widget_add_css_class (child, "title-1"); -adw_breakpoint_bin_set_child (ADW_BREAKPOINT_BIN (bin), child); - -breakpoint = adw_breakpoint_new (adw_breakpoint_condition_parse ("max-width: 200px")); -adw_breakpoint_add_setters (breakpoint, - G_OBJECT (child), "label", "Narrow", - NULL); -adw_breakpoint_bin_add_breakpoint (ADW_BREAKPOINT_BIN (bin), breakpoint); -``` - -The bin has a single label inside it, displaying "Wide". When the bin's width -is smaller than or equal to 200px, it changes to "Narrow". - -## `AdwBreakpointBin` as `GtkBuildable` - -`AdwBreakpointBin` allows adding `AdwBreakpoint` objects as children. - -Example of an `AdwBreakpointBin` UI definition: - -```xml -<object class="AdwBreakpointBin"> - <property name="width-request">150</property> - <property name="height-request">150</property> - <property name="child"> - <object class="GtkLabel" id="child"> - <property name="label">Wide</property> - <property name="ellipsize">end</property> - <style> - <class name="title-1"/> - </style> - </object> - </property> - <child> - <object class="AdwBreakpoint"> - <condition>max-width: 200px</condition> - <setter object="child" property="label">Narrow</setter> - </object> - </child> -</object> -``` - -See [class@Breakpoint] documentation for details. - - - - - + + + an alert dialog + + + + + Creates a new `AdwBreakpointBin`. - - + filename="src/adw-alert-dialog.c" + line="2280">Gets the ID of the default response of @self. + + the newly created `AdwBreakpointBin` - - - - - Adds @breakpoint to @self. - - - + filename="src/adw-alert-dialog.c" + line="2286">the default response ID + a breakpoint bin - + filename="src/adw-alert-dialog.c" + line="2282">an alert dialog + - - the breakpoint to add - - - - + Gets the child widget of @self. - + filename="src/adw-alert-dialog.c" + line="1794">Gets the child widget of @self. + the child widget of @self + filename="src/adw-alert-dialog.c" + line="1800">the child widget of @self. a breakpoint bin - + filename="src/adw-alert-dialog.c" + line="1796">an alert dialog + - - + Gets the current breakpoint. - + filename="src/adw-alert-dialog.c" + line="1380">Gets the heading of @self. + the current breakpoint - + filename="src/adw-alert-dialog.c" + line="1386">the heading of @self. + a breakpoint bin - + filename="src/adw-alert-dialog.c" + line="1382">an alert dialog + - - + Sets the child widget of @self. - + filename="src/adw-alert-dialog.c" + line="1440">Gets whether the heading of @self includes Pango markup. + - + whether @self uses markup for heading + a breakpoint bin - + filename="src/adw-alert-dialog.c" + line="1442">an alert dialog + - - the child widget - - - - - - The child widget. - - - - - The current breakpoint. - - - - - - - - - - - - - - - - - - - - - - - - - Describes condition for an [class@Breakpoint]. - - + Creates a condition that triggers when @condition_1 and @condition_2 are both -true. - - + filename="src/adw-alert-dialog.c" + line="1851">Gets whether @self prefers wide layout. + + the newly created condition - + filename="src/adw-alert-dialog.c" + line="1857">whether to prefer wide layout + - - first condition - - - + second condition - - + filename="src/adw-alert-dialog.c" + line="1853">an alert dialog + + - - + + Creates a condition that triggers on length changes. - - + filename="src/adw-alert-dialog.c" + line="2125">Gets the appearance of @response. + +See [method@AlertDialog.set_response_appearance]. + + the newly created condition - + filename="src/adw-alert-dialog.c" + line="2134">the appearance of @response + - - the length type - - - + the length value - - - + filename="src/adw-alert-dialog.c" + line="2127">an alert dialog + + + the length unit - + filename="src/adw-alert-dialog.c" + line="2128">a response ID + - - + + Creates a condition that triggers when either @condition_1 or @condition_2 is -true. - - + filename="src/adw-alert-dialog.c" + line="2210">Gets whether @response is enabled. + +See [method@AlertDialog.set_response_enabled]. + + the newly created condition - + filename="src/adw-alert-dialog.c" + line="2219">whether @response is enabled + - + first condition - - - + filename="src/adw-alert-dialog.c" + line="2212">an alert dialog + + + second condition - + filename="src/adw-alert-dialog.c" + line="2213">a response ID + - - + + Creates a condition that triggers on ratio changes. + filename="src/adw-alert-dialog.c" + line="2065">Gets the label of @response. -The ratio is represented as @width divided by @height. - - +See [method@AlertDialog.set_response_label]. + + the newly created condition - + filename="src/adw-alert-dialog.c" + line="2074">the label of @response + - + the ratio type - - - + filename="src/adw-alert-dialog.c" + line="2067">an alert dialog + + + ratio width - + filename="src/adw-alert-dialog.c" + line="2068">a response ID + - + + + + Gets whether @self has a response with the ID @response. + + + whether @self has a response with the ID @response. + + + + ratio height - + filename="src/adw-alert-dialog.c" + line="2406">an alert dialog + + + + response ID + - - + + Copies @self. - - - a copy of @self - + filename="src/adw-alert-dialog.c" + line="2025">Removes a response from @self. + + + a breakpoint condition - + filename="src/adw-alert-dialog.c" + line="2027">an alert dialog + + + the response ID + + - + Frees @self. - + filename="src/adw-alert-dialog.c" + line="1613">Sets the body text of @self. + a breakpoint condition - + filename="src/adw-alert-dialog.c" + line="1615">an alert dialog + + + the body of @self + + - + Returns a textual representation of @self. + filename="src/adw-alert-dialog.c" + line="1669">Sets whether the body text of @self includes Pango markup. -The returned string can be parsed by [func@BreakpointCondition.parse]. - - - A newly allocated text string - +See [func@Pango.parse_markup]. + + + a breakpoint condition - + filename="src/adw-alert-dialog.c" + line="1671">an alert dialog + + + whether to use markup for body text + + - + Parses a condition from a string. - -Length conditions are specified as `<type>: <value>[<unit>]`, where: - -- `<type>` can be `min-width`, `max-width`, `min-height` or `max-height` -- `<value>` is a fractional number -- `<unit>` can be `px`, `pt` or `sp` - -If the unit is omitted, `px` is assumed. - -See [ctor@BreakpointCondition.new_length]. - -Examples: - -- `min-width: 500px` -- `min-height: 400pt` -- `max-width: 100sp` -- `max-height: 500` - -Ratio conditions are specified as `<type>: <width>[/<height>]`, where: - -- `<type>` can be `min-aspect-ratio` or `max-aspect-ratio` -- `<width>` and `<height>` are integer numbers - -See [ctor@BreakpointCondition.new_ratio]. - -The ratio is represented as `<width>` divided by `<height>`. - -If `<height>` is omitted, it's assumed to be 1. - -Examples: - -- `min-aspect-ratio: 4/3` -- `max-aspect-ratio: 1` - -The logical operators `and`, `or` can be used to compose a complex condition -as follows: + filename="src/adw-alert-dialog.c" + line="2367">Sets the ID of the close response of @self. -- `<condition> and <condition>`: the condition is true when both - `<condition>`s are true, same as when using - [ctor@BreakpointCondition.new_and] -- `<condition> or <condition>`: the condition is true when either of the - `<condition>`s is true, same as when using - [ctor@BreakpointCondition.new_or] - -Examples: +It will be passed to [signal@AlertDialog::response] if the dialog is closed +by pressing <kbd>Escape</kbd> or with a system action. -- `min-width: 400px and max-aspect-ratio: 4/3` -- `max-width: 360sp or max-width: 360px` +It doesn't have to correspond to any of the responses in the dialog. -Conditions can be further nested using parentheses, for example: +The default close response is `close`. + + + + + + + an alert dialog + + + + the close response ID + + + + + + Sets the ID of the default response of @self. -- `min-width: 400px and (max-aspect-ratio: 4/3 or max-height: 400px)` +If set, pressing <kbd>Enter</kbd> will activate the corresponding button. -If parentheses are omitted, the first operator takes priority. - - - the parsed condition - +If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd> +will do nothing. + + + - + the string specifying the condition + filename="src/adw-alert-dialog.c" + line="2307">an alert dialog + + + + the default response ID - - - - Describes length types for [struct@BreakpointCondition]. + + + Sets the child widget of @self. -See [ctor@BreakpointCondition.new_length]. - -New values may be added to this enumeration over time. - - true if the width is greater than or - equal to the condition value - - - true if the width is less than or - equal to the condition value - - - true if the height is greater than or - equal to the condition value - - - true if the height is less than or - equal to the condition value - - - - Describes ratio types for [struct@BreakpointCondition]. - -See [ctor@BreakpointCondition.new_ratio]. - -New values may be added to this enumeration over time. - - true if the aspect ratio is - greater than or equal to the condition value - - - true if the aspect ratio is - less than or equal to the condition value - - - - A helper widget for creating buttons. - -<picture> - <source srcset="button-content-dark.png" media="(prefers-color-scheme: dark)"> - <img src="button-content.png" alt="button-content"> -</picture> - -`AdwButtonContent` is a box-like widget with an icon and a label. - -It's intended to be used as a direct child of [class@Gtk.Button], -[class@Gtk.MenuButton] or [class@SplitButton], when they need to have both an -icon and a label, as follows: - -```xml -<object class="GtkButton"> - <property name="child"> - <object class="AdwButtonContent"> - <property name="icon-name">document-open-symbolic</property> - <property name="label" translatable="yes">_Open</property> - <property name="use-underline">True</property> - </object> - </property> -</object> -``` - -`AdwButtonContent` handles style classes and connecting the mnemonic to the -button automatically. - -## CSS nodes - -``` -buttoncontent -├── image -╰── label -``` - -`AdwButtonContent`'s CSS node is called `buttoncontent`. It contains the -subnodes `image` and `label`. - -When inside a `GtkButton` or `AdwSplitButton`, the button will receive the -`.image-text-button` style class. When inside a `GtkMenuButton`, the -internal `GtkButton` will receive it instead. - -## Accessibility - -`AdwButtonContent` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - - - - - - Creates a new `AdwButtonContent`. - - - the new created `AdwButtonContent` - - - - - - gets whether the button can be smaller than the natural size of its contents. - +The child widget is displayed below the heading and body. + - whether the button can shrink - + a button content - + filename="src/adw-alert-dialog.c" + line="1818">an alert dialog + - - - - - Gets the name of the displayed icon. - - - the icon name - - - - + a button content - - + filename="src/adw-alert-dialog.c" + line="1819">the child widget + + - - + Gets the displayed label. - + filename="src/adw-alert-dialog.c" + line="1402">Sets the heading of @self. + - the label - + a button content - + filename="src/adw-alert-dialog.c" + line="1404">an alert dialog + + + the heading of @self + + - - + Gets whether an underline in the text indicates a mnemonic. - + filename="src/adw-alert-dialog.c" + line="1462">Sets whether the heading of @self includes Pango markup. + +See [func@Pango.parse_markup]. + - whether an underline in the text indicates a mnemonic - + a button content - + filename="src/adw-alert-dialog.c" + line="1464">an alert dialog + + + whether to use markup for heading + + - - + Sets whether the button can be smaller than the natural size of its contents. - -If set to `TRUE`, the label will ellipsize. + filename="src/adw-alert-dialog.c" + line="1873">Sets whether @self prefers wide layout. -See [method@Gtk.Button.set_can_shrink]. - +Prefer horizontal button layout when possible, and wider dialog width +otherwise. + a button content - + filename="src/adw-alert-dialog.c" + line="1875">an alert dialog + - + whether the button can shrink + filename="src/adw-alert-dialog.c" + line="1876">whether to prefer wide layout - - + Sets the name of the displayed icon. + filename="src/adw-alert-dialog.c" + line="2153">Sets the appearance for @response. -If empty, the icon is not shown. - +<picture> + <source srcset="alert-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)"> + <img src="alert-dialog-appearance.png" alt="alert-dialog-appearance"> +</picture> + +Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the +affirmative action, like the Save button in the example. + +Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging +consequences of using @response. This appearance acts as a warning to the +user. The Discard button in the example is using this appearance. + +The default appearance is `ADW_RESPONSE_DEFAULT`. + +Negative responses like Cancel or Close should use the default appearance. + a button content - + filename="src/adw-alert-dialog.c" + line="2155">an alert dialog + - + the new icon name + filename="src/adw-alert-dialog.c" + line="2156">a response ID + + appearance for @response + + - - + Sets the displayed label. - + filename="src/adw-alert-dialog.c" + line="2238">Sets whether @response is enabled. + +If @response is not enabled, the corresponding button will have +[property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as +a default response. + +@response can still be used as [property@AlertDialog:close-response] while +it's not enabled. + +Responses are enabled by default. + a button content - + filename="src/adw-alert-dialog.c" + line="2240">an alert dialog + - + the new label + filename="src/adw-alert-dialog.c" + line="2241">a response ID + + whether to enable @response + + - - + Sets whether an underline in the text indicates a mnemonic. - -The mnemonic can be used to activate the parent button. + filename="src/adw-alert-dialog.c" + line="2093">Sets the label of @response to @label. -See [property@ButtonContent:label]. - +Labels are displayed on the dialog buttons. An embedded underline in @label +indicates a mnemonic. + a button content - + filename="src/adw-alert-dialog.c" + line="2095">an alert dialog + - + whether an underline in the text indicates a mnemonic - + filename="src/adw-alert-dialog.c" + line="2096">a response ID + + + + the label of @response + - + The body text of the dialog. + + + - - Whether the button can be smaller than the natural size of its contents. - -If set to `TRUE`, the label will ellipsize. + filename="src/adw-alert-dialog.c" + line="927">Whether the body text includes Pango markup. -See [property@Gtk.Button:can-shrink]. +See [func@Pango.parse_markup]. - - - + setter="set_close_response" + getter="get_close_response" + default-value="close"> The name of the displayed icon. + filename="src/adw-alert-dialog.c" + line="987">The ID of the close response. -If empty, the icon is not shown. +It will be passed to [signal@AlertDialog::response] if the dialog is +closed by pressing <kbd>Escape</kbd> or with a system action. + +It doesn't have to correspond to any of the responses in the dialog. + +The default close response is `close`. - - - + setter="set_default_response" + getter="get_default_response" + default-value="NULL"> The displayed label. + filename="src/adw-alert-dialog.c" + line="970">The response ID of the default response. + +If set, pressing <kbd>Enter</kbd> will activate the corresponding button. + +If set to `NULL` or a non-existent response ID, pressing <kbd>Enter</kbd> +will do nothing. - + The child widget. + +Displayed below the heading and body. + + + + The heading of the dialog. + + + - - Whether an underline in the text indicates a mnemonic. + filename="src/adw-alert-dialog.c" + line="901">Whether the heading includes Pango markup. -The mnemonic can be used to activate the parent button. +See [func@Pango.parse_markup]. + + + + Whether to prefer wide layout. -See [property@ButtonContent:label]. +Prefer horizontal button layout when possible, and wider dialog width +otherwise. - - - - - + + - - - Compile-time version checking. Evaluates to `TRUE` if the version -of Adwaita is greater than the required one. - - - - required major version - - - required minor version - - - required micro version - - - - - An [class@AnimationTarget] that calls a given callback during the -animation. - - + Creates a new `AdwAnimationTarget` that calls the given @callback during -the animation. - - - the newly created callback target - + filename="src/adw-alert-dialog.c" + line="1008">This signal is emitted when the dialog is closed. + +@response will be set to the response ID of the button that had been +activated. + +if the dialog was closed by pressing <kbd>Escape</kbd> or with a system +action, @response will be set to the value of +[property@AlertDialog:close-response]. + + - - the callback to call - - - - the data to be passed to @callback - - - + the function to be called when the - callback action is finalized - + filename="src/adw-alert-dialog.c" + line="1011">the response ID + - + - - - - - A paginated scrolling widget. - -<picture> - <source srcset="carousel-dark.png" media="(prefers-color-scheme: dark)"> - <img src="carousel.png" alt="carousel"> -</picture> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A base class for animations. -The `AdwCarousel` widget can be used to display a set of pages with -swipe-based navigation between them. +`AdwAnimation` represents an animation on a widget. It has a target that +provides a value to animate, and a state indicating whether the +animation hasn't been started yet, is playing, paused or finished. -[class@CarouselIndicatorDots] and [class@CarouselIndicatorLines] can be used -to provide page indicators for `AdwCarousel`. +Currently there are two concrete animation types: +[class@TimedAnimation] and [class@SpringAnimation]. -## CSS nodes +`AdwAnimation` will automatically skip the animation if +[property@Animation:widget] is unmapped, or if +[property@Gtk.Settings:gtk-enable-animations] is `FALSE`. -`AdwCarousel` has a single CSS node with name `carousel`. - - - - - - - - Creates a new `AdwCarousel`. - - - the newly created `AdwCarousel` - - - - - Appends @child to @self. - - - - - - - a carousel - - - - a widget to add - - - - - - - Gets whether to allow swiping for more than one page at a time. - - - `TRUE` if long swipes are allowed - - - - - a carousel - - - - - - +The [signal@Animation::done] signal can be used to perform an action after +the animation ends, for example hiding a widget after animating its +[property@Gtk.Widget:opacity] to 0. + +`AdwAnimation` will be kept alive while the animation is playing. As such, +it's safe to create an animation, start it and immediately unref it: +A fire-and-forget animation: + +```c +static void +animation_cb (double value, + MyObject *self) +{ + // Do something with @value +} + +static void +my_object_animate (MyObject *self) +{ + AdwAnimationTarget *target = + adw_callback_animation_target_new ((AdwAnimationTargetFunc) animation_cb, + self, NULL); + g_autoptr (AdwAnimation) animation = + adw_timed_animation_new (widget, 0, 1, 250, target); + + adw_animation_play (animation); +} +``` + +If there's a chance the previous animation for the same target hasn't yet +finished, the previous animation should be stopped first, or the existing +`AdwAnimation` object can be reused. + + Sets whether @self can be dragged with mouse pointer. - + filename="src/adw-animation.c" + line="762">Gets whether @self should be skipped when animations are globally disabled. + whether @self can be dragged with mouse pointer + filename="src/adw-animation.c" + line="768">whether to follow the global setting a carousel - + filename="src/adw-animation.c" + line="764">an animation + - - + Gets whether @self will respond to scroll wheel events. - + filename="src/adw-animation.c" + line="549">Gets the current value of @self. + +The state indicates whether @self is currently playing, paused, finished or +hasn't been started yet. + `TRUE` if @self will respond to scroll wheel events - + filename="src/adw-animation.c" + line="558">the animation value + a carousel - + filename="src/adw-animation.c" + line="551">an animation + - - + Gets whether @self can be navigated. - + filename="src/adw-animation.c" + line="483">Gets the target @self animates. + whether @self can be navigated - + filename="src/adw-animation.c" + line="489">the animation target + a carousel - + filename="src/adw-animation.c" + line="485">an animation + - - + Gets the number of pages in @self. - + filename="src/adw-animation.c" + line="529">Gets the current value of @self. + the number of pages in @self - + filename="src/adw-animation.c" + line="535">the current value + a carousel - + filename="src/adw-animation.c" + line="531">an animation + - + Gets the page at position @n. - + filename="src/adw-animation.c" + line="456">Gets the widget @self was created for. + +It provides the frame clock for the animation. It's not strictly necessary +for this widget to be same as the one being animated. + +The widget must be mapped in order for the animation to work. If it's not +mapped, or if it gets unmapped during an ongoing animation, the animation +will be automatically skipped. + the page + filename="src/adw-animation.c" + line="469">the animation widget a carousel - + filename="src/adw-animation.c" + line="458">an animation + - - index of the page - - - - + Gets current scroll position in @self, unitless. + filename="src/adw-animation.c" + line="610">Pauses a playing animation for @self. -1 matches 1 page. Use [method@Carousel.scroll_to] for changing it. - - - the scroll position - - - - - a carousel - - - - - - - Gets the page reveal duration, in milliseconds. - - - the duration - - - - - a carousel - - - - - - - Gets the scroll animation spring parameters for @self. - - - the animation parameters - - - - - a carousel - - - - - - - Gets spacing between pages in pixels. - +Does nothing if the current state of @self isn't `ADW_ANIMATION_PLAYING`. + +Sets [property@Animation:state] to `ADW_ANIMATION_PAUSED`. + - spacing between pages - + a carousel - + filename="src/adw-animation.c" + line="612">an animation + - + Inserts @child into @self at position @position. + filename="src/adw-animation.c" + line="572">Starts the animation for @self. -If position is -1, or larger than the number of pages, -@child will be appended to the end. - +If the animation is playing, paused or has been completed, restarts it from +the beginning. This allows to easily play an animation regardless of whether +it's already playing or not. + +Sets [property@Animation:state] to `ADW_ANIMATION_PLAYING`. + +The animation will be automatically skipped if [property@Animation:widget] is +unmapped, or if [property@Gtk.Settings:gtk-enable-animations] is `FALSE`. + +As such, it's not guaranteed that the animation will actually run. For +example, when using [func@GLib.idle_add] and starting an animation +immediately afterwards, it's entirely possible that the idle callback will +run after the animation has already finished, and not while it's playing. + a carousel - + filename="src/adw-animation.c" + line="574">an animation + - - a widget to add - - - - the position to insert @child at - - - + Prepends @child to @self. - + filename="src/adw-animation.c" + line="722">Resets the animation for @self. + +Sets [property@Animation:state] to `ADW_ANIMATION_IDLE`. + a carousel - + filename="src/adw-animation.c" + line="724">an animation + - - a widget to add - - - + Removes @child from @self. - + filename="src/adw-animation.c" + line="646">Resumes a paused animation for @self. + +This function must only be used if the animation has been paused with +[method@Animation.pause]. + +Sets [property@Animation:state] to `ADW_ANIMATION_PLAYING`. + a carousel - + filename="src/adw-animation.c" + line="648">an animation + - - a widget to remove - - - + Moves @child into position @position. + filename="src/adw-animation.c" + line="784">Sets whether to skip @self when animations are globally disabled. -If position is -1, or larger than the number of pages, @child will be moved -at the end. - +The default behavior is to skip the animation. Set to `FALSE` to disable this +behavior. + +This can be useful for cases where animation is essential, like spinners, or +in demo applications. Most other animations should keep it enabled. + +See [property@Gtk.Settings:gtk-enable-animations]. + a carousel - + filename="src/adw-animation.c" + line="786">an animation + - - a widget to add - - - + the position to move @child to - + filename="src/adw-animation.c" + line="787">whether to follow the global setting + - + Scrolls to @widget. - -If @animate is `TRUE`, the transition will be animated. - + filename="src/adw-animation.c" + line="503">Sets the target @self animates to @target. + a carousel - + filename="src/adw-animation.c" + line="505">an animation + - - a child of @self - - - + whether to animate the transition - + filename="src/adw-animation.c" + line="506">an animation target + - - + Sets whether to allow swiping for more than one page at a time. + filename="src/adw-animation.c" + line="675">Skips the animation for @self. -If @allow_long_swipes is `FALSE`, each swipe can only move to the adjacent -pages. - +If the animation hasn't been started yet, is playing, or is paused, instantly +skips the animation to the end and causes [signal@Animation::done] to be +emitted. + +Sets [property@Animation:state] to `ADW_ANIMATION_FINISHED`. + a carousel - + filename="src/adw-animation.c" + line="677">an animation + - - whether to allow long swipes - - - - + Sets whether @self can be dragged with mouse pointer. + filename="src/adw-animation.c" + line="405">Whether to skip the animation when animations are globally disabled. -If @allow_mouse_drag is `FALSE`, dragging is only available on touch. - +The default behavior is to skip the animation. Set to `FALSE` to disable +this behavior. + +This can be useful for cases where animation is essential, like spinners, +or in demo applications. Most other animations should keep it enabled. + +See [property@Gtk.Settings:gtk-enable-animations]. + + + + The animation state. + +The state indicates whether the animation is currently playing, paused, +finished or hasn't been started yet. + + + + The target to animate. + + + + The current value of the animation. + + + + The animation widget. + +It provides the frame clock for the animation. It's not strictly necessary +for this widget to be same as the one being animated. + +The widget must be mapped in order for the animation to work. If it's not +mapped, or if it gets unmapped during an ongoing animation, the animation +will be automatically skipped. + + + + + + + This signal is emitted when the animation has been completed, either on its +own or via calling [method@Animation.skip]. + + + + + + + Describes the possible states of an [class@Animation]. + +The state can be controlled with [method@Animation.play], +[method@Animation.pause], [method@Animation.resume], +[method@Animation.reset] and [method@Animation.skip]. + + The animation hasn't started yet. + + + The animation has been paused. + + + The animation is currently playing. + + + The animation has finished. + + + + Represents a value [class@Animation] can animate. + + + + + + + Prototype for animation targets based on user callbacks. + + + + + + + The animation value + + + + The user data provided when creating the target + + + + + + A base class for Adwaita applications. + +`AdwApplication` handles library initialization by calling [func@init] in the +default [signal@Gio.Application::startup] signal handler, in turn chaining up +as required by [class@Gtk.Application]. Therefore, any subclass of +`AdwApplication` should always chain up its `startup` handler before using +any Adwaita or GTK API. + +## Automatic Resources + +`AdwApplication` will automatically load stylesheets located in the +application's resource base path (see +[method@Gio.Application.set_resource_base_path], if they're present. + +They can be used to add custom styles to the application, as follows: + +- `style.css` contains styles that are always present. + +- `style-dark.css` contains styles only used when +[property@StyleManager:dark] is `TRUE`. + +- `style-hc.css` contains styles used when the system high contrast + preference is enabled. + +- `style-hc-dark.css` contains styles used when the system high contrast + preference is enabled and [property@StyleManager:dark] is `TRUE`. + + + + + Creates a new `AdwApplication`. + +If `application_id` is not `NULL`, then it must be valid. See +[func@Gio.Application.id_is_valid]. + +If no application ID is given then some features (most notably application +uniqueness) will be disabled. + + + the newly created `AdwApplication` + + - + a carousel - - - + filename="src/adw-application.c" + line="250">The application ID + + + whether @self can be dragged with mouse pointer - + filename="src/adw-application.c" + line="251">The application flags + + + + Gets the style manager for @self. + +This is a convenience property allowing to access `AdwStyleManager` through +property bindings or expressions. + + + the style manager + + + + + an application + + + - - + Sets whether @self will respond to scroll wheel events. + filename="src/adw-application.c" + line="227">The style manager for this application. -If @allow_scroll_wheel is `FALSE`, wheel events will be ignored. - +This is a convenience property allowing to access `AdwStyleManager` through +property bindings or expressions. + + + + + + + + + + The parent class + + + + + + + + + + A freeform application window. + +<picture> + <source srcset="application-window-dark.png" media="(prefers-color-scheme: dark)"> + <img src="application-window.png" alt="application-window"> +</picture> + +`AdwApplicationWindow` is a [class@Gtk.ApplicationWindow] subclass providing +the same features as [class@Window]. + +See [class@Window] for details. + +Example of an `AdwApplicationWindow` UI definition: + +```xml +<object class="AdwApplicationWindow"> + <property name="content"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"/> + </child> + <property name="content"> + <!-- ... --> + </property> + </object> + </property> +</object> +``` + +Using [property@Gtk.Application:menubar] is not supported and may result in +visual glitches. + + + + + + + + + + + Creates a new `AdwApplicationWindow` for @app. + + + the newly created `AdwApplicationWindow` + + + + + an application instance + + + + + + Adds @breakpoint to @self. + a carousel - + filename="src/adw-application-window.c" + line="407">an application window + - + whether @self will respond to scroll wheel events - + filename="src/adw-application-window.c" + line="408">the breakpoint to add + - - + Sets whether @self can be navigated. - -This can be used to temporarily disable the carousel to only allow navigating -it in a certain state. - + filename="src/adw-application-window.c" + line="496">Gets whether adaptive preview for @self is currently open. + - + whether adaptive preview is open. + a carousel - + filename="src/adw-application-window.c" + line="498">an application window + - + + + + Gets the content widget of @self. + +This method should always be used instead of [method@Gtk.Window.get_child]. + + + the content widget of @self + + + + whether @self can be navigated - - + filename="src/adw-application-window.c" + line="385">an application window + + - - + Sets the page reveal duration, in milliseconds. + filename="src/adw-application-window.c" + line="428">Gets the current breakpoint. + + + the current breakpoint + + + + + an application window + + + + + + Returns a [iface@Gio.ListModel] that contains the open dialogs of @self. -Reveal duration is used when animating adding or removing pages. - - - +This can be used to keep an up-to-date view. + + + a list model for the dialogs of @self + a carousel - + filename="src/adw-application-window.c" + line="452">an application window + - + + + + Returns the currently visible dialog in @self, if there's one. + + + the visible dialog + + + + the new reveal duration value - - + filename="src/adw-application-window.c" + line="476">an application window + + - - + Sets the scroll animation spring parameters for @self. + filename="src/adw-application-window.c" + line="518">Sets whether adaptive preview for @self is currently open. -The default value is equivalent to: +Adaptive preview is a debugging tool used for testing the window +contents at specific screen sizes, simulating mobile environment. -```c -adw_spring_params_new (1, 0.5, 500) -``` - +Adaptive preview can always be accessed from inspector. This function +allows applications to open it manually. + +Most applications should not use this function. + a carousel - + filename="src/adw-application-window.c" + line="520">an application window + - + the new parameters - + filename="src/adw-application-window.c" + line="521">whether to open adaptive preview + - - + Sets spacing between pages in pixels. - + filename="src/adw-application-window.c" + line="352">Sets the content widget of @self. + +This method should always be used instead of [method@Gtk.Window.set_child]. + a carousel - + filename="src/adw-application-window.c" + line="354">an application window + - + the new spacing value - + filename="src/adw-application-window.c" + line="355">the content widget + - - - Whether to allow swiping for more than one page at a time. + filename="src/adw-application-window.c" + line="246">Whether adaptive preview is currently open. -If the value is `FALSE`, each swipe can only move to the adjacent pages. - - - - - - Sets whether the `AdwCarousel` can be dragged with mouse pointer. +Adaptive preview is a debugging tool used for testing the window +contents at specific screen sizes, simulating mobile environment. -If the value is `FALSE`, dragging is only available on touch. - - - - - - Whether the widget will respond to scroll wheel events. +Adaptive preview can always be accessed from inspector. This function +allows applications to open it manually. -If the value is `FALSE`, wheel events will be ignored. +Most applications should not use this property. - - - - Whether the carousel can be navigated. - -This can be used to temporarily disable the carousel to only allow -navigating it in a certain state. - - - - - The number of pages in a `AdwCarousel`. - - - - + setter="set_content" + getter="get_content"> Current scrolling position, unitless. + filename="src/adw-application-window.c" + line="198">The content widget. -1 matches 1 page. Use [method@Carousel.scroll_to] for changing it. - +This property should always be used instead of [property@Gtk.Window:child]. + - + getter="get_current_breakpoint"> Page reveal duration, in milliseconds. - -Reveal duration is used when animating adding or removing pages. - + filename="src/adw-application-window.c" + line="210">The current breakpoint. + - - - + getter="get_dialogs"> Scroll animation spring parameters. - -The default value is equivalent to: - -```c -adw_spring_params_new (1, 0.5, 500) -``` - + filename="src/adw-application-window.c" + line="222">The open dialogs. + - - - + getter="get_visible_dialog"> Spacing between pages in pixels. - + filename="src/adw-application-window.c" + line="234">The currently visible dialog + - - This signal is emitted after a page has been changed. - -It can be used to implement "infinite scrolling" by amending the pages -after every scroll. Note that an empty carousel is indicated by -`(int)index == -1`. - - - - - - current page - - - - + + + - - + + - + + + + + + - + glib:type-name="AdwAvatar" + glib:get-type="adw_avatar_get_type" + glib:type-struct="AvatarClass"> A dots indicator for [class@Carousel]. + filename="src/adw-avatar.c" + line="22">A widget displaying an image, with a generated fallback. <picture> - <source srcset="carousel-indicator-dots-dark.png" media="(prefers-color-scheme: dark)"> - <img src="carousel-indicator-dots.png" alt="carousel-indicator-dots"> + <source srcset="avatar-dark.png" media="(prefers-color-scheme: dark)"> + <img src="avatar.png" alt="avatar"> </picture> -The `AdwCarouselIndicatorDots` widget shows a set of dots for each page of a -given [class@Carousel]. The dot representing the carousel's active page is -larger and more opaque than the others, the transition to the active and -inactive state is gradual to match the carousel's position. +`AdwAvatar` is a widget that shows a round avatar. -See also [class@CarouselIndicatorLines]. +`AdwAvatar` generates an avatar with the initials of the +[property@Avatar:text] on top of a colored background. + +The color is picked based on the hash of the [property@Avatar:text]. + +If [property@Avatar:show-initials] is set to `FALSE`, +[property@Avatar:icon-name] or `avatar-default-symbolic` is shown instead of +the initials. + +Use [property@Avatar:custom-image] to set a custom image. ## CSS nodes -`AdwCarouselIndicatorDots` has a single CSS node with name -`carouselindicatordots`. - +`AdwAvatar` has a single CSS node with name `avatar`. + +## Accessibility + +`AdwAvatar` uses the `GTK_ACCESSIBLE_ROLE_IMG` role. + - - + Creates a new `AdwCarouselIndicatorDots`. - + filename="src/adw-avatar.c" + line="503">Creates a new `AdwAvatar`. + the newly created `AdwCarouselIndicatorDots` + filename="src/adw-avatar.c" + line="511">the newly created `AdwAvatar` - - - - Gets the displayed carousel. - - - the displayed carousel - - - - - an indicator - - - - - - - Sets the displayed carousel. - - - - - + an indicator - - - The size of the avatar + + + a carousel - + filename="src/adw-avatar.c" + line="506">the text used to get the initials and color + + + + whether to use initials instead of an icon as fallback + - - - - - The displayed carousel. - - - - - - - - - - - A lines indicator for [class@Carousel]. - -<picture> - <source srcset="carousel-indicator-dots-lines.png" media="(prefers-color-scheme: dark)"> - <img src="carousel-indicator-lines.png" alt="carousel-indicator-lines"> -</picture> - -The `AdwCarouselIndicatorLines` widget shows a set of lines for each page of -a given [class@Carousel]. The carousel's active page is shown as another line -that moves between them to match the carousel's position. - -See also [class@CarouselIndicatorDots]. - -## CSS nodes - -`AdwCarouselIndicatorLines` has a single CSS node with name -`carouselindicatorlines`. - - - - - - - Creates a new `AdwCarouselIndicatorLines`. - - - the newly created `AdwCarouselIndicatorLines` - - - - + Gets the displayed carousel. - - + filename="src/adw-avatar.c" + line="768">Renders @self into a [class@Gdk.Texture] at @scale_factor. + +This can be used to export the fallback avatar. + + the displayed carousel - + filename="src/adw-avatar.c" + line="777">the texture + an indicator - + filename="src/adw-avatar.c" + line="770">an avatar + + + The scale factor + + - - + Sets the displayed carousel. - - - + filename="src/adw-avatar.c" + line="652">Gets the custom image paintable. + + + the custom image + an indicator - + filename="src/adw-avatar.c" + line="654">an avatar + - - a carousel - - - - - - The displayed carousel. - - - - - - - - - - - Describes title centering behavior of a [class@HeaderBar] widget. - - Keep the title centered when possible - - - Keep the title centered at all cost - - - - A widget constraining its child to a given size. - -<picture> - <source srcset="clamp-wide-dark.png" media="(prefers-color-scheme: dark)"> - <img src="clamp-wide.png" alt="clamp-wide"> -</picture> -<picture> - <source srcset="clamp-narrow-dark.png" media="(prefers-color-scheme: dark)"> - <img src="clamp-narrow.png" alt="clamp-narrow"> -</picture> - -The `AdwClamp` widget constrains the size of the widget it contains to a -given maximum size. It will constrain the width if it is horizontal, or the -height if it is vertical. The expansion of the child from its minimum to its -maximum size is eased out for a smooth transition. - -If the child requires more than the requested maximum size, it will be -allocated the minimum size it can fit in instead. - -`AdwClamp` can scale with the text scale factor, use the -[property@ClampLayout:unit] property to enable that behavior. - -## CSS nodes - -`AdwClamp` has a single CSS node with name `clamp`. - - - - - - - Creates a new `AdwClamp`. - - - the newly created `AdwClamp` - - - - - + Gets the child widget of @self. - + filename="src/adw-avatar.c" + line="525">Gets the name of an icon to use as a fallback. + the child widget of @self - + filename="src/adw-avatar.c" + line="531">the icon name + a clamp - + filename="src/adw-avatar.c" + line="527">an avatar + - - + Gets the maximum size allocated to the child. - + filename="src/adw-avatar.c" + line="609">Gets whether initials are used instead of an icon on the fallback avatar. + the maximum size to allocate to the child - + filename="src/adw-avatar.c" + line="615">whether initials are used instead of an icon as fallback + a clamp - + filename="src/adw-avatar.c" + line="611">an avatar + - - + Gets the size above which the child is clamped. - + filename="src/adw-avatar.c" + line="718">Gets the size of the avatar. + the size above which the child is clamped + filename="src/adw-avatar.c" + line="724">the size of the avatar a clamp - + filename="src/adw-avatar.c" + line="720">an avatar + - - + Gets the length unit for maximum size and tightening threshold. - - + filename="src/adw-avatar.c" + line="564">Gets the text used to generate the fallback initials and color. + + the length unit - + filename="src/adw-avatar.c" + line="570">the text used to generate the fallback initials and + color + a clamp - + filename="src/adw-avatar.c" + line="566">an avatar + - - + Sets the child widget of @self. - + filename="src/adw-avatar.c" + line="668">Sets the custom image paintable. + +Custom image is displayed instead of initials or icon. + a clamp - + filename="src/adw-avatar.c" + line="670">an avatar + - the child widget - + filename="src/adw-avatar.c" + line="671">a custom image + - - + Sets the maximum size allocated to the child. + filename="src/adw-avatar.c" + line="541">Sets the name of an icon to use as a fallback. -It is the width if the clamp is horizontal, or the height if it is vertical. - +If no name is set, `avatar-default-symbolic` will be used. + a clamp - + filename="src/adw-avatar.c" + line="543">an avatar + - + the maximum size - + filename="src/adw-avatar.c" + line="544">the icon name + - - + Sets the size above which the child is clamped. - -Starting from this size, the clamp will tighten its grip on the child, slowly -allocating less and less of the available size up to the maximum allocated -size. Below that threshold and below the maximum size, the child will be -allocated all the available size. - -If the threshold is greater than the maximum size to allocate to the child, -the child will be allocated all the size up to the maximum. If the threshold -is lower than the minimum size to allocate to the child, that size will be -used as the tightening threshold. + filename="src/adw-avatar.c" + line="625">Sets whether to use initials instead of an icon on the fallback avatar. -Effectively, tightening the grip on the child before it reaches its maximum -size makes transitions to and from the maximum size smoother when resizing. - +See [property@Avatar:icon-name] for how to change the fallback icon. + a clamp - + filename="src/adw-avatar.c" + line="627">an avatar + - + the tightening threshold + filename="src/adw-avatar.c" + line="628">whether to use initials instead of an icon as fallback + + + + + + Sets the size of the avatar. + + + + + + + an avatar + + + + The size of the avatar - - + Sets the length unit for maximum size and tightening threshold. + filename="src/adw-avatar.c" + line="581">Sets the text used to generate the fallback initials and color. -Allows the sizes to vary depending on the text scale factor. - +It's only used to generate the color if [property@Avatar:show-initials] is +`FALSE`. + a clamp - + filename="src/adw-avatar.c" + line="583">an avatar + - + the length unit - + filename="src/adw-avatar.c" + line="584">the text used to get the initials and color + - - - + setter="set_custom_image" + getter="get_custom_image"> The child widget of the `AdwClamp`. - + filename="src/adw-avatar.c" + line="436">A custom image paintable. + +Custom image is displayed instead of initials or icon. + - - - + setter="set_icon_name" + getter="get_icon_name" + default-value="NULL"> The maximum size allocated to the child. + filename="src/adw-avatar.c" + line="399">The name of an icon to use as a fallback. -It is the width if the clamp is horizontal, or the height if it is vertical. - +If no name is set, `avatar-default-symbolic` will be used. + - - - + setter="set_show_initials" + getter="get_show_initials" + default-value="FALSE"> The size above which the child is clamped. - -Starting from this size, the clamp will tighten its grip on the child, -slowly allocating less and less of the available size up to the maximum -allocated size. Below that threshold and below the maximum size, the child -will be allocated all the available size. - -If the threshold is greater than the maximum size to allocate to the child, -the child will be allocated all the size up to the maximum. -If the threshold is lower than the minimum size to allocate to the child, -that size will be used as the tightening threshold. + filename="src/adw-avatar.c" + line="424">Whether initials are used instead of an icon on the fallback avatar. -Effectively, tightening the grip on the child before it reaches its maximum -size makes transitions to and from the maximum size smoother when resizing. +See [property@Avatar:icon-name] for how to change the fallback icon. + + + + The size of the avatar. - - - + setter="set_text" + getter="get_text"> The length unit for maximum size and tightening threshold. + filename="src/adw-avatar.c" + line="411">Sets the text used to generate the fallback initials and color. -Allows the sizes to vary depending on the text scale factor. - +It's only used to generate the color if [property@Avatar:show-initials] is +`FALSE`. + - - + + - + glib:type-name="AdwBanner" + glib:get-type="adw_banner_get_type" + glib:type-struct="BannerClass"> A layout manager constraining its children to a given size. + filename="src/adw-banner.c" + line="37">A bar with contextual information. <picture> - <source srcset="clamp-wide-dark.png" media="(prefers-color-scheme: dark)"> - <img src="clamp-wide.png" alt="clamp-wide"> + <source srcset="banner-dark.png" media="(prefers-color-scheme: dark)"> + <img src="banner.png" alt="banner"> </picture> + +Banners are hidden by default, use [property@Banner:revealed] to show them. + +Banners have a title, set with [property@Banner:title]. Titles can be marked +up with Pango markup, use [property@Banner:use-markup] to enable it. + +The title will be shown centered or left-aligned depending on available +space. + +Banners can optionally have a button with text on it, set through +[property@Banner:button-label]. The button can be used with a `GAction`, +or with the [signal@Banner::button-clicked] signal. The button can have +different styles, a gray style and a suggested style. + <picture> - <source srcset="clamp-narrow-dark.png" media="(prefers-color-scheme: dark)"> - <img src="clamp-narrow.png" alt="clamp-narrow"> + <source srcset="banner-suggested-dark.png" media="(prefers-color-scheme: dark)"> + <img src="banner-suggested.png" alt="banner with suggested button style"> </picture> -`AdwClampLayout` constraints the size of the widgets it contains to a given -maximum size. It will constrain the width if it is horizontal, or the height -if it is vertical. The expansion of the children from their minimum to their -maximum size is eased out for a smooth transition. - -If a child requires more than the requested maximum size, it will be -allocated the minimum size it can fit in instead. +## CSS nodes -`AdwClampLayout` can scale with the text scale factor, use the -[property@ClampLayout:unit] property to enable that behavior. - - - +`AdwBanner` has a main CSS node with the name `banner`. + + + + + + Creates a new `AdwClampLayout`. - - + filename="src/adw-banner.c" + line="557">Creates a new `AdwBanner`. + + the newly created `AdwClampLayout` - + filename="src/adw-banner.c" + line="563">the newly created `AdwBanner` + + + + the banner title + + + - - + Gets the maximum size allocated to the children. - + filename="src/adw-banner.c" + line="621">Gets the button label for @self. + + + the button label for @self + + + + + a banner + + + + + + Gets the style class in use for the banner button. + the maximum size to allocate to the children - + filename="src/adw-banner.c" + line="720">the current button style + a clamp layout - + filename="src/adw-banner.c" + line="716">a banner + - - + Gets the size above which the children are clamped. - + filename="src/adw-banner.c" + line="777">Gets if a banner is revealed + the size above which the children are clamped - + filename="src/adw-banner.c" + line="783">Whether a banner is revealed + a clamp layout - + filename="src/adw-banner.c" + line="779">a banner + - - + Gets the length unit for maximum size and tightening threshold. - + filename="src/adw-banner.c" + line="577">Gets the title for @self. + the length unit - + filename="src/adw-banner.c" + line="583">the title for @self + a clamp layout - + filename="src/adw-banner.c" + line="579">a banner + - - + Sets the maximum size allocated to the children. + filename="src/adw-banner.c" + line="669">Gets whether to use Pango markup for the banner title. + + + whether to use markup + + + + + a banner + + + + + + Sets the button label for @self. -It is the width if the layout is horizontal, or the height if it is vertical. - +If set to `""` or `NULL`, the button won't be shown. + +The button can be used with a `GAction`, or with the +[signal@Banner::button-clicked] signal. + a clamp layout - + filename="src/adw-banner.c" + line="641">a banner + - + the maximum size - + filename="src/adw-banner.c" + line="642">the label + - - + Sets the size above which the children are clamped. - -Starting from this size, the layout will tighten its grip on the children, -slowly allocating less and less of the available size up to the maximum -allocated size. Below that threshold and below the maximum size, the children -will be allocated all the available size. + filename="src/adw-banner.c" + line="732">Sets the style class to use for the banner button. -If the threshold is greater than the maximum size to allocate to the -children, they will be allocated the whole size up to the maximum. If the -threshold is lower than the minimum size to allocate to the children, that -size will be used as the tightening threshold. +When set to `ADW_BANNER_BUTTON_DEFAULT`, the button stays grey. +When set to `ADW_BANNER_BUTTON_SUGGESTED`, the button follows the [`.suggested-action`](style-classes.html#suggested-action) style -Effectively, tightening the grip on a child before it reaches its maximum -size makes transitions to and from the maximum size smoother when resizing. - +<picture> + <source srcset="banner-suggested-dark.png" media="(prefers-color-scheme: dark)"> + <img src="banner-suggested.png" alt="banner with suggested button style"> +</picture> + a clamp layout - + filename="src/adw-banner.c" + line="734">a banner + - + the tightening threshold - + filename="src/adw-banner.c" + line="735">a button style + - - + Sets the length unit for maximum size and tightening threshold. - -Allows the sizes to vary depending on the text scale factor. - + filename="src/adw-banner.c" + line="795">Sets whether a banner should be revealed + a clamp layout - + filename="src/adw-banner.c" + line="797">a banner + - + the length unit - + filename="src/adw-banner.c" + line="798">whether a banner should be revealed + - - - + The maximum size to allocate to the children. + filename="src/adw-banner.c" + line="595">Sets the title for this banner. -It is the width if the layout is horizontal, or the height if it is -vertical. - - - - - +See also: [property@Banner:use-markup]. + + + + + + + a banner + + + + the title + + + + + The size above which the children are clamped. + filename="src/adw-banner.c" + line="687">Sets whether to use Pango markup for the banner title. -Starting from this size, the layout will tighten its grip on the children, -slowly allocating less and less of the available size up to the maximum -allocated size. Below that threshold and below the maximum size, the -children will be allocated all the available size. +See also [func@Pango.parse_markup]. + + + + + + + a banner + + + + whether to use markup + + + + + + The label to show on the button. -If the threshold is greater than the maximum size to allocate to the -children, they will be allocated the whole size up to the maximum. If the -threshold is lower than the minimum size to allocate to the children, that -size will be used as the tightening threshold. +If set to `""` or `NULL`, the button won't be shown. -Effectively, tightening the grip on a child before it reaches its maximum -size makes transitions to and from the maximum size smoother when resizing. - +The button can be used with a `GAction`, or with the +[signal@Banner::button-clicked] signal. + - - - + setter="set_button_style" + getter="get_button_style" + default-value="ADW_BANNER_BUTTON_DEFAULT"> The length unit for maximum size and tightening threshold. + filename="src/adw-banner.c" + line="427">The style class to use for the banner button. -Allows the sizes to vary depending on the text scale factor. - +When set to `ADW_BANNER_BUTTON_DEFAULT`, the button stays grey. +When set to `ADW_BANNER_BUTTON_SUGGESTED`, the button follows the [`.suggested-action`](style-classes.html#suggested-action) style + +<picture> + <source srcset="banner-suggested-dark.png" media="(prefers-color-scheme: dark)"> + <img src="banner-suggested.png" alt="banner with suggested button style"> +</picture> + + + + Whether the banner is currently revealed. + + + + The title for this banner. + +See also: [property@Banner:use-markup]. + + + + Whether to use Pango markup for the banner title. + +See also [func@Pango.parse_markup]. + + + This signal is emitted after the action button has been clicked. + +It can be used as an alternative to setting an action. + + + + - - + + Describes the available button styles for [class@Banner]. + +New values may be added to this enumeration over time. + +See [property@Banner:button-style]. + + The default button style. + + + A button in the suggested action style. + + + + - + - + glib:type-name="AdwBin" + glib:get-type="adw_bin_get_type" + glib:type-struct="BinClass"> A scrollable [class@Clamp]. + filename="src/adw-bin.c" + line="14">A widget with one child. -`AdwClampScrollable` is a variant of [class@Clamp] that implements the -[iface@Gtk.Scrollable] interface. +<picture> + <source srcset="bin-dark.png" media="(prefers-color-scheme: dark)"> + <img src="bin.png" alt="bin"> +</picture> -The primary use case for `AdwClampScrollable` is clamping -[class@Gtk.ListView]. - +The `AdwBin` widget has only one child, set with the [property@Bin:child] +property. + +It is useful for deriving subclasses, since it provides common code needed +for handling a single child widget. + - - - + Creates a new `AdwClampScrollable`. - + filename="src/adw-bin.c" + line="150">Creates a new `AdwBin`. + the newly created `AdwClampScrollable` + filename="src/adw-bin.c" + line="155">the new created `AdwBin` - Gets the child widget of @self. - + filename="src/adw-bin.c" + line="163">Gets the child widget of @self. + the child widget of @self + filename="src/adw-bin.c" + line="169">the child widget of @self a clamp scrollable - + filename="src/adw-bin.c" + line="165">a bin + - - + Gets the maximum size allocated to the child. - + filename="src/adw-bin.c" + line="183">Sets the child widget of @self. + + + + + + + a bin + + + + the child widget + + + + + + The child widget of the `AdwBin`. + + + + + + + + + + + + + + A bottom sheet with an optional bottom bar. + +<picture> + <source srcset="bottom-sheet-dark.png" media="(prefers-color-scheme: dark)"> + <img src="bottom-sheet.png" alt="bottom-sheet"> +</picture> + +`AdwBottomSheet` has three child widgets. [property@BottomSheet:content] is +shown persistently. [property@BottomSheet:sheet] is displayed above it when +it's open, and [property@BottomSheet:bottom-bar] is displayed when it's not. + +Bottom sheet and bottom bar are attached to the bottom edge of the widget. +They take the full width by default, but can only take a portion of it if +[property@BottomSheet:full-width] is set to `FALSE`. In this case, +[property@BottomSheet:align] determines where along the bottom edge they are +placed. + +Bottom bar can be hidden using the [property@BottomSheet:reveal-bottom-bar] +property. + +`AdwBottomSheet` can be useful for applications such as music players, that +want to have a persistent bottom bar that expands into a bottom sheet when +clicked. It's meant for cases where a bottom sheet is tightly integrated into +the UI. For more transient bottom sheets, see [class@Dialog]. + +To open or close the bottom sheet, use the [property@BottomSheet:open] +property. + +By default, the bottom sheet has an overlaid drag handle. It can be disabled +by setting [property@BottomSheet:show-drag-handle] to `FALSE`. Note that the +handle also controls whether the sheet can be dragged using a pointer. + +Bottom sheets are modal by default, meaning that the content is dimmed and +cannot be accessed while the sheet is open. Set [property@BottomSheet:modal] +to `FALSE` if this behavior is unwanted. + +To disable user interactions for opening or closing the bottom sheet (such as +swipes or clicking the bottom bar or close button), set +[property@BottomSheet:can-open] or [property@BottomSheet:can-close] to +`FALSE`. + +In some cases, particularly when using a full-width bottom bar, it may be +necessary to shift [property@BottomSheet:content] upwards. Use the +[property@BottomSheet:bottom-bar-height] and +[property@BottomSheet:sheet-height] for that. + +`AdwBottomSheet` is not adaptive, and for larger window sizes applications +may want to replace it with another UI, such as a sidebar. This can be done +using [class@MultiLayoutView]. + +## Sizing + +Unlike [class@Dialog] presented as a bottom sheet, `AdwBottomSheet` just +follows the content's natural size, and it's up to the applications to make +sure their content provides one. For example, when using +[class@Gtk.ScrolledWindow], make sure to set +[property@Gtk.ScrolledWindow:propagate-natural-height] to `TRUE`. + +## Header Bar Integration + +When placed inside an `AdwBottomSheet`, [class@HeaderBar] will not show the +title when [property@BottomSheet:show-drag-handle] is `TRUE`, regardless of +[property@HeaderBar:show-title]. This only applies to the default title, +titles set with [property@HeaderBar:title-widget] will still be shown. + +## `AdwBottomSheet` as `GtkBuildable`: + +The `AdwBottomSheet` implementation of the [iface@Gtk.Buildable] interface +supports setting the sheet widget by specifying “sheet” as the “type” +attribute of a `<child>` element, and the bottom bar by specifying +“bottom-bar”. Specifying “content” or omitting the child type results in +setting the content child. + + + + + + + Creates a new `AdwBottomSheet`. + the maximum size to allocate to the child + filename="src/adw-bottom-sheet.c" + line="1412">the new created `AdwBottomSheet` + + + + + Gets horizontal alignment of the bottom sheet. + + + the horizontal alignment + + + + + a bottom sheet + + + + + + Gets the bottom bar widget for @self. + + + the bottom bar widget + + + + + a bottom sheet + + + + + + Gets the current bottom bar height. + +It can be used to shift the content upwards permanently to accommodate for +the bottom bar. + + + the bottom bar height a clamp scrollable - + filename="src/adw-bottom-sheet.c" + line="2070">a bottom sheet + - - + Gets the size above which the child is clamped. - + filename="src/adw-bottom-sheet.c" + line="1998">Gets whether the bottom sheet can be closed by user. + the size above which the child is clamped + filename="src/adw-bottom-sheet.c" + line="2004">whether the sheet can be closed by user + + + + + a bottom sheet + + + + + + Gets whether the bottom sheet can be opened by user. + + + whether the sheet can be opened by user. + + + + + a bottom sheet + + + + + + Gets the content widget for @self. + + + the content widget + + + + + a bottom sheet + + + + + + Gets whether the bottom sheet takes the full width. + + + whether the sheet takes up the full width + + + + + a bottom sheet + + + + + + Gets whether the bottom sheet is modal. + + + whether the sheet is modal + + + + + a bottom sheet + + + + + + Gets whether the bottom sheet is open. + + + whether the sheet is open + + + + + a bottom sheet + + + + + + Gets whether the bottom bar is revealed. + + + whether the bottom bar is revealed + + + + + a bottom sheet + + + + + + Gets the bottom sheet widget for @self. + + + the sheet widget + + + + + a bottom sheet + + + + + + Gets the current bottom sheet height. + +It can be used to shift the content upwards when the bottom sheet is open. + + + the sheet height a clamp scrollable - + filename="src/adw-bottom-sheet.c" + line="2050">a bottom sheet + - - + Gets the length unit for maximum size and tightening threshold. - + filename="src/adw-bottom-sheet.c" + line="1830">Gets whether to show a drag handle in the bottom sheet. + the length unit - + filename="src/adw-bottom-sheet.c" + line="1836">whether to show the drag handle + a clamp scrollable - + filename="src/adw-bottom-sheet.c" + line="1832">a bottom sheet + - - + Sets the child widget of @self. - + filename="src/adw-bottom-sheet.c" + line="1753">Sets horizontal alignment of the bottom sheet. + +0 means the bottom sheet is flush with the start edge, 1 means it's flush +with the end edge. 0.5 means it's centered. + +Only used when [property@BottomSheet:full-width] is set to `FALSE`. + a clamp scrollable - + filename="src/adw-bottom-sheet.c" + line="1755">a bottom sheet + - + the new alignment + + + + + + Sets the bottom bar widget for @self. + +Shown when [property@BottomSheet:open] is `FALSE`. When open, morphs into +the [property@BottomSheet:sheet]. + +Bottom bar can be temporarily hidden using the +[property@BottomSheet:reveal-bottom-bar] property. + + + + + + + a bottom sheet + + + the child widget + filename="src/adw-bottom-sheet.c" + line="1546">the bottom bar widget - - + Sets the maximum size allocated to the child. + filename="src/adw-bottom-sheet.c" + line="2016">Sets whether the bottom sheet can be closed by user. -It is the width if the clamp is horizontal, or the height if it is vertical. - +It can be closed via the close button, swiping down, pressing +<kbd>Escape</kbd> or clicking the content dimming (when modal). + +Bottom sheet can still be closed using [property@BottomSheet:open]. + a clamp scrollable - + filename="src/adw-bottom-sheet.c" + line="2018">a bottom sheet + - + the maximum size - + filename="src/adw-bottom-sheet.c" + line="2019">whether the sheet can be closed by user + - - + Sets the size above which the child is clamped. + filename="src/adw-bottom-sheet.c" + line="1960">Sets whether the bottom sheet can be opened by user. -Starting from this size, the clamp will tighten its grip on the child, slowly -allocating less and less of the available size up to the maximum allocated -size. Below that threshold and below the maximum width, the child will be -allocated all the available size. +It can be opened via clicking or swiping up from the bottom bar. -If the threshold is greater than the maximum size to allocate to the child, -the child will be allocated all the width up to the maximum. If the threshold -is lower than the minimum size to allocate to the child, that size will be -used as the tightening threshold. +Does nothing if [property@BottomSheet:bottom-bar] is not set. -Effectively, tightening the grip on the child before it reaches its maximum -size makes transitions to and from the maximum size smoother when resizing. - +Bottom sheet can still be opened using [property@BottomSheet:open]. + a clamp scrollable - + filename="src/adw-bottom-sheet.c" + line="1962">a bottom sheet + - + the tightening threshold - + filename="src/adw-bottom-sheet.c" + line="1963">whether the sheet can be opened by user. + - - + Sets the length unit for maximum size and tightening threshold. + filename="src/adw-bottom-sheet.c" + line="1440">Sets the content widget for @self. -Allows the sizes to vary depending on the text scale factor. - +It's always shown, and the bottom sheet is overlaid over it. + a clamp - + filename="src/adw-bottom-sheet.c" + line="1442">a bottom sheet + - + the length unit - + filename="src/adw-bottom-sheet.c" + line="1443">the content widget + - - - - The child widget of the `AdwClampScrollable`. - - - - - - The maximum size allocated to the child. - -It is the width if the clamp is horizontal, or the height if it is vertical. - - - - - + The size above which the child is clamped. + filename="src/adw-bottom-sheet.c" + line="1801">Sets whether the bottom sheet takes the full width. -Starting from this size, the clamp will tighten its grip on the child, -slowly allocating less and less of the available size up to the maximum -allocated size. Below that threshold and below the maximum width, the child -will be allocated all the available size. - -If the threshold is greater than the maximum size to allocate to the child, -the child will be allocated all the width up to the maximum. -If the threshold is lower than the minimum size to allocate to the child, -that size will be used as the tightening threshold. - -Effectively, tightening the grip on the child before it reaches its maximum -size makes transitions to and from the maximum size smoother when resizing. - - - - - - The length unit for maximum size and tightening threshold. - -Allows the sizes to vary depending on the text scale factor. - - - - - - - - - - - Application color schemes for [property@StyleManager:color-scheme]. - - Inherit the parent color-scheme. When set on the - `AdwStyleManager` returned by [func@StyleManager.get_default], it's - equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT`. - - - Always use light appearance. - - - Use light appearance unless the system - prefers dark colors. - - - Use dark appearance unless the system prefers - prefers light colors. - - - Always use dark appearance. - - - - A [class@Gtk.ListBoxRow] used to choose from a list of items. - -<picture> - <source srcset="combo-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="combo-row.png" alt="combo-row"> -</picture> - -The `AdwComboRow` widget allows the user to choose from a list of valid -choices. The row displays the selected choice. When activated, the row -displays a popover which allows the user to make a new choice. - -Example of an `AdwComboRow` UI definition: -```xml -<object class="AdwComboRow"> - <property name="title" translatable="yes">Combo Row</property> - <property name="model"> - <object class="GtkStringList"> - <items> - <item translatable="yes">Foo</item> - <item translatable="yes">Bar</item> - <item translatable="yes">Baz</item> - </items> - </object> - </property> -</object> -``` - -The [property@ComboRow:selected] and [property@ComboRow:selected-item] -properties can be used to keep track of the selected item and react to their -changes. - -`AdwComboRow` mirrors [class@Gtk.DropDown], see that widget for details. - -`AdwComboRow` is [property@Gtk.ListBoxRow:activatable] if a model is set. - -## CSS nodes - -`AdwComboRow` has a main CSS node with name `row` and the `.combo` style -class. - -Its popover has the node named `popover` with the `.menu` style class, it -contains a [class@Gtk.ScrolledWindow], which in turn contains a -[class@Gtk.ListView], both are accessible via their regular nodes. - -## Accessibility - -`AdwComboRow` uses the `GTK_ACCESSIBLE_ROLE_COMBO_BOX` role. - - - - - - - Creates a new `AdwComboRow`. - - - the newly created `AdwComboRow` - - - - - - Gets whether search is enabled. - -If set to `TRUE`, a search entry will be shown in the popup that -allows to search for items in the list. - -Search requires [property@ComboRow:expression] to be set. - - - whether the popup includes a search entry - - - - - a combo row - - - - - - - Gets the expression used to obtain strings from items. - - - the expression used to obtain strings from items - - - - - a combo row - - - - - - - Gets the factory for populating list items. - - - the factory in use - - - - - a combo row - - - - - - - Gets the factory for populating list items in the popup. - - - the factory in use - - - - - a combo row - - - - - - - Gets the model that provides the displayed items. - - - The model in use - - - - - a combo row - - - - - - - Gets the position of the selected item. - - - the position of the selected item, or - [const@Gtk.INVALID_LIST_POSITION] if no item is selected - - - - - a combo row - - - - - - - Gets the selected item. - - - the selected item - - - - - a combo row - - - - - - - Gets whether to use the current value as the subtitle. - - - whether to use the current value as the subtitle - - - - - a combo row - - - - - - - Sets whether to enable search. - -If set to `TRUE`, a search entry will be shown in the popup that -allows to search for items in the list. - -Search requires [property@ComboRow:expression] to be set. - +When full width, [property@BottomSheet:align] is ignored. + a combo row - + filename="src/adw-bottom-sheet.c" + line="1803">a bottom sheet + - + whether to enable search + filename="src/adw-bottom-sheet.c" + line="1804">whether the sheet takes up the full width - - + Sets the expression used to obtain strings from items. + filename="src/adw-bottom-sheet.c" + line="1908">Sets whether the bottom sheet is modal. -The expression must have a value type of `G_TYPE_STRING`. +When modal, [property@BottomSheet:content] will be dimmed when the bottom +sheet is open, and clicking it will close the bottom sheet. It also cannot be +focused with keyboard. -It's used to bind strings to labels produced by the default factory if -[property@ComboRow:factory] is not set, or when -[property@ComboRow:use-subtitle] is set to `TRUE`. - +Otherwise, the content is accessible even when the bottom sheet is open. + a combo row - + filename="src/adw-bottom-sheet.c" + line="1910">a bottom sheet + - + an expression - + filename="src/adw-bottom-sheet.c" + line="1911">whether the sheet is modal + - - + Sets the factory for populating list items. - -This factory is always used for the item in the row. It is also used for -items in the popup unless [property@ComboRow:list-factory] is set. - + filename="src/adw-bottom-sheet.c" + line="1613">Sets whether the bottom sheet is open. + a combo row - + filename="src/adw-bottom-sheet.c" + line="1615">a bottom sheet + - + the factory to use - + filename="src/adw-bottom-sheet.c" + line="1616">whether to open the sheet + - - + Sets the factory for populating list items in the popup. + filename="src/adw-bottom-sheet.c" + line="2107">Sets whether to reveal the bottom bar. -If this is not set, [property@ComboRow:factory] is used. - +The transition will be animated. + +See [property@BottomSheet:bottom-bar] and +[property@BottomSheet:bottom-bar-height]. + a combo row - + filename="src/adw-bottom-sheet.c" + line="2109">a bottom sheet + - + the factory to use - + filename="src/adw-bottom-sheet.c" + line="2110">whether to reveal the bottom bar + - - + Sets the model that provides the displayed items. - + filename="src/adw-bottom-sheet.c" + line="1490">Sets the bottom sheet widget for @self. + +Only shown when [property@BottomSheet:open] is `TRUE`. + a combo row - + filename="src/adw-bottom-sheet.c" + line="1492">a bottom sheet + - the model to use - - - - - - - Selects the item at the given position. - - - - - - - a combo row - - - - the position of the item to select, or - [const@Gtk.INVALID_LIST_POSITION] - + filename="src/adw-bottom-sheet.c" + line="1493">the sheet widget + - - + Sets whether to use the current value as the subtitle. + filename="src/adw-bottom-sheet.c" + line="1848">Sets whether to show a drag handle in the bottom sheet. -If you use a custom list item factory, you will need to give the row a -name conversion expression with [property@ComboRow:expression]. +The handle will be overlaid over [property@BottomSheet:sheet]. -If set to `TRUE`, you should not access [property@ActionRow:subtitle]. +When the handle is shown, [class@HeaderBar] will hide its default title, and +[class@ToolbarView] will reserve space if there are no top bars. -The subtitle is interpreted as Pango markup if -[property@PreferencesRow:use-markup] is set to `TRUE`. - +Showing drag handle also allows to swipe the bottom sheet down (and to swipe +the bottom bar up) with a pointer, instead of just touchscreen. + a combo row - + filename="src/adw-bottom-sheet.c" + line="1850">a bottom sheet + - + whether to use the current value as the subtitle + filename="src/adw-bottom-sheet.c" + line="1851">whether to show the drag handle - - - + setter="set_align" + getter="get_align" + default-value="0.500000"> Whether to show a search entry in the popup. + filename="src/adw-bottom-sheet.c" + line="826">Horizontal alignment of the bottom sheet. -If set to `TRUE`, a search entry will be shown in the popup that -allows to search for items in the list. +0 means the bottom sheet is flush with the start edge, 1 means it's flush +with the end edge. 0.5 means it's centered. -Search requires [property@ComboRow:expression] to be set. - +Only used when [property@BottomSheet:full-width] is set to `FALSE`. + - - - + setter="set_bottom_bar" + getter="get_bottom_bar"> An expression used to obtain strings from items. + filename="src/adw-bottom-sheet.c" + line="796">The bottom bar widget. -The expression must have a value type of `G_TYPE_STRING`. +Shown when [property@BottomSheet:open] is `FALSE`. When open, morphs into +the [property@BottomSheet:sheet]. -It's used to bind strings to labels produced by the default factory if -[property@ComboRow:factory] is not set, or when -[property@ComboRow:use-subtitle] is set to `TRUE`. - +Bottom bar can be temporarily hidden using the +[property@BottomSheet:reveal-bottom-bar] property. + - - - + getter="get_bottom_bar_height" + default-value="0"> Factory for populating list items. + filename="src/adw-bottom-sheet.c" + line="944">The current bottom bar height. -This factory is always used for the item in the row. It is also used for -items in the popup unless [property@ComboRow:list-factory] is set. - +It can be used to shift the content upwards permanently to accommodate for +the bottom bar. + - - - + setter="set_can_close" + getter="get_can_close" + default-value="TRUE"> The factory for populating list items in the popup. + filename="src/adw-bottom-sheet.c" + line="913">Whether the bottom sheet can be closed by user. -If this is not set, [property@ComboRow:factory] is used. - +It can be closed via the close button, swiping down, pressing +<kbd>Escape</kbd> or clicking the content dimming (when modal). + +Bottom sheet can still be closed using [property@BottomSheet:open]. + - - - + setter="set_can_open" + getter="get_can_open" + default-value="TRUE"> The model that provides the displayed items. - + filename="src/adw-bottom-sheet.c" + line="895">Whether the bottom sheet can be opened by user. + +It can be opened via clicking or swiping up from the bottom bar. + +Does nothing if [property@BottomSheet:bottom-bar] is not set. + +Bottom sheet can still be opened using [property@BottomSheet:open]. + - - - + setter="set_content" + getter="get_content"> The position of the selected item. + filename="src/adw-bottom-sheet.c" + line="768">The content widget. -If no item is selected, the property has the value -[const@Gtk.INVALID_LIST_POSITION] - +It's always shown, and the bottom sheet is overlaid over it. + - - + setter="set_full_width" + getter="get_full_width" + default-value="TRUE"> The selected item. - - - Whether the bottom sheet takes the full width. + +When full width, [property@BottomSheet:align] is ignored. + + + + Whether the bottom sheet is modal. + +When modal, [property@BottomSheet:content] will be dimmed when the bottom +sheet is open, and clicking it will close the bottom sheet. It also cannot +be focused with keyboard. + +Otherwise, the content is accessible even when the bottom sheet is open. + + + - - Whether to use the current value as the subtitle. + filename="src/adw-bottom-sheet.c" + line="814">Whether the bottom sheet is open. + + + + Whether to reveal the bottom bar. -If you use a custom list item factory, you will need to give the row a -name conversion expression with [property@ComboRow:expression]. +The transition will be animated. -If set to `TRUE`, you should not access [property@ActionRow:subtitle]. +See [property@BottomSheet:bottom-bar] and +[property@BottomSheet:bottom-bar-height]. + + + + The bottom sheet widget. -The subtitle is interpreted as Pango markup if -[property@PreferencesRow:use-markup] is set to `TRUE`. +Only shown when [property@BottomSheet:open] is `TRUE`. + + + + The current bottom sheet height. + +It can be used to shift the content upwards when the bottom sheet is open. + + + + Whether to overlay a drag handle in the bottom sheet. + +The handle will be overlaid over [property@BottomSheet:sheet]. + +When the handle is shown, [class@HeaderBar] will hide its default title, +and [class@ToolbarView] will reserve space if there are no top bars. + +Showing drag handle also allows to swipe the bottom sheet down (and to +swipe the bottom bar up) with a pointer, instead of just touchscreen. - - - + + Emitted when the close button or shortcut is used while +[property@Dialog:can-close] is set to `FALSE`. + + + + - - + + - The parent class - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + Indicates an [class@Animation] with an infinite duration. + filename="src/adw-breakpoint.c" + line="19">Describes a breakpoint for [class@Window] or [class@Dialog]. -This value is mostly used internally. - - - - - - - - - - - - - - - - Describes the available easing functions for use with -[class@TimedAnimation]. +Breakpoints are used to create adaptive UI, allowing to change the layout +depending on available size. -New values may be added to this enumeration over time. - +Breakpoint is a size threshold, specified by its condition, as well as one or +more setters. + +Each setter has a target object, a property and a value. When a breakpoint +is applied, each setter sets the target property on their target object to +the specified value, and reset it back to the original value when it's +unapplied. + +For more complicated scenarios, [signal@Breakpoint::apply] and +[signal@Breakpoint::unapply] can be used instead. + +Breakpoints can be used within [class@Window], [class@ApplicationWindow], +[class@Dialog] or [class@BreakpointBin]. + +## `AdwBreakpoint` as `GtkBuildable`: + +`AdwBreakpoint` supports specifying its condition via the `<condition>` +element. The contents of the element must be a string in a format accepted by +[func@BreakpointCondition.parse]. + +It also supports adding setters via the `<setter>` element. Each `<setter>` +element must have the `object` attribute specifying the target object, and +the `property` attribute specifying the property name. The contents of the +element are used as the setter value. + +For `G_TYPE_OBJECT` and `G_TYPE_BOXED` derived properties, empty contents are +treated as `NULL`. + +Setter values can be translated with the usual `translatable`, `context` and +`comments` attributes. + +Example of an `AdwBreakpoint` UI definition: + +```xml +<object class="AdwBreakpoint"> + <condition>max-width: 400px</condition> + <setter object="button" property="visible">True</setter> + <setter object="box" property="orientation">vertical</setter> + <setter object="page" property="title" translatable="yes">Example</setter> +</object> +``` + + + Linear tweening. - - + filename="src/adw-breakpoint.c" + line="1462">Creates a new `AdwBreakpoint` with @condition. + + + the newly created `AdwBreakpoint` + + + + + the condition + + + + + Quadratic tweening. - - + filename="src/adw-breakpoint.c" + line="1532">Adds a setter to @self. + +The setter will automatically set @property on @object to @value when +applying the breakpoint, and set it back to its original value upon +unapplying it. + +::: note + Setting properties to their original values does not work for properties + that have irreversible side effects. For example, changing + [property@Gtk.Button:label] while [property@Gtk.Button:icon-name] is set + will reset the icon. However, resetting the label will not set + `icon-name` to its original value. + +Use the [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] signals +for those properties instead, as follows: + +```c +static void +breakpoint_apply_cb (MyWidget *self) +{ + gtk_button_set_icon_name (self->button, "go-previous-symbolic"); +} + +static void +breakpoint_apply_cb (MyWidget *self) +{ + gtk_button_set_label (self->button, _("_Back")); +} + +// ... + +g_signal_connect_swapped (breakpoint, "apply", + G_CALLBACK (breakpoint_apply_cb), self); +g_signal_connect_swapped (breakpoint, "unapply", + G_CALLBACK (breakpoint_unapply_cb), self); +``` + + + + + + + a breakpoint + + + + the target object + + + + the target property + + + + the value to set + + + + + Quadratic tweening, inverse of `ADW_EASE_IN_QUAD`. - - + filename="src/adw-breakpoint.c" + line="1649">Adds multiple setters to @self. + +See [method@Breakpoint.add_setter]. + +Example: + +```c +adw_breakpoint_add_setters (breakpoint, + G_OBJECT (box), "orientation", GTK_ORIENTATION_VERTICAL, + G_OBJECT (button), "halign", GTK_ALIGN_FILL, + G_OBJECT (button), "valign", GTK_ALIGN_END, + NULL); +``` + + + + + + + a breakpoint + + + + the first target object + + + + the first target property + + + + the value of the first setter, followed by a list of object, property + and value triplets, terminated by `NULL` + + + + + Quadratic tweening, combining `ADW_EASE_IN_QUAD` and - `ADW_EASE_OUT_QUAD`. - - + filename="src/adw-breakpoint.c" + line="1723">Adds multiple setters to @self. + +See [method@Breakpoint.add_setters]. + + + + + + + a breakpoint + + + + the first target object + + + + the first target property + + + + the value of the first setter, followed by a list of object, property + and value triplets, terminated by `NULL` + + + + + Cubic tweening. - - + filename="src/adw-breakpoint.c" + line="1690">Adds @n_setters setters to @self. + +This is a convenience function for adding multiple setters at once. + +See [method@Breakpoint.add_setter]. + +This function is meant to be used by language bindings. + + + + + + + a breakpoint + + + + the number of setters to add + + + + setter target object + + + + + + setter target properties + + + + + + setter values + + + + + + + Cubic tweening, inverse of `ADW_EASE_IN_CUBIC`. - - + filename="src/adw-breakpoint.c" + line="1488">Gets the condition for @self. + + + the condition + + + + + a breakpoint + + + + + Cubic tweening, combining `ADW_EASE_IN_CUBIC` and - `ADW_EASE_OUT_CUBIC`. - + filename="src/adw-breakpoint.c" + line="1506">Sets the condition for @self. + + + + + + + a breakpoint + + + + the new condition + + + + + + The breakpoint's condition. + + + + Emitted when the breakpoint is applied. + +This signal is emitted after the setters have been applied. + + + + + + Emitted when the breakpoint is unapplied. + +This signal is emitted before resetting the setter values. + + + + + + + A widget that changes layout based on available size. + +<picture> + <source srcset="breakpoint-bin-dark.png" media="(prefers-color-scheme: dark)"> + <img src="breakpoint-bin.png" alt="breakpoint-bin"> +</picture> + +`AdwBreakpointBin` provides a way to use breakpoints without [class@Window], +[class@ApplicationWindow] or [class@Dialog]. It can be useful for limiting +breakpoints to a single page and similar purposes. Most applications +shouldn't need it. + +`AdwBreakpointBin` is similar to [class@Bin]. It has one child, set via the +[property@BreakpointBin:child] property. + +When `AdwBreakpointBin` is resized, its child widget can rearrange its layout +at specific thresholds. + +The thresholds and layout changes are defined via [class@Breakpoint] objects. +They can be added using [method@BreakpointBin.add_breakpoint]. + +Each breakpoint has a condition, specifying the bin's size and/or aspect +ratio, and setters that automatically set object properties when that +happens. The [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] can +be used instead for more complex scenarios. + +Breakpoints are only allowed to modify widgets inside the `AdwBreakpointBin`, +but not on the `AdwBreakpointBin` itself or any other widgets. + +If multiple breakpoints can be used for the current size, the last one is +always picked. The current breakpoint can be tracked using the +[property@BreakpointBin:current-breakpoint] property. + +If none of the breakpoints can be used, that property will be set to `NULL`, +and the original property values will be used instead. + +## Minimum Size + +Adding a breakpoint to `AdwBreakpointBin` will result in it having no minimum +size. The [property@Gtk.Widget:width-request] and +[property@Gtk.Widget:height-request] properties must always be set when using +breakpoints, indicating the smallest size you want to support. + +The minimum size and breakpoint conditions must be carefully selected so that +the child widget completely fits. If it doesn't, it will overflow and a +warning message will be printed. + +When choosing minimum size, consider translations and text scale factor +changes. Make sure to leave enough space for text labels, and enable +ellipsizing or wrapping if they might not fit. + +For [class@Gtk.Label] this can be done via [property@Gtk.Label:ellipsize], or +via [property@Gtk.Label:wrap] together with [property@Gtk.Label:wrap-mode]. + +For buttons, use [property@Gtk.Button:can-shrink], +[property@Gtk.MenuButton:can-shrink], [property@Adw.SplitButton:can-shrink], +or [property@Adw.ButtonContent:can-shrink]. + +## Example + +```c +GtkWidget *bin, *child; +AdwBreakpoint *breakpoint; + +bin = adw_breakpoint_bin_new (); +gtk_widget_set_size_request (bin, 150, 150); + +child = gtk_label_new ("Wide"); +gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END); +gtk_widget_add_css_class (child, "title-1"); +adw_breakpoint_bin_set_child (ADW_BREAKPOINT_BIN (bin), child); + +breakpoint = adw_breakpoint_new (adw_breakpoint_condition_parse ("max-width: 200px")); +adw_breakpoint_add_setters (breakpoint, + G_OBJECT (child), "label", "Narrow", + NULL); +adw_breakpoint_bin_add_breakpoint (ADW_BREAKPOINT_BIN (bin), breakpoint); +``` + +The bin has a single label inside it, displaying "Wide". When the bin's width +is smaller than or equal to 200px, it changes to "Narrow". + +## `AdwBreakpointBin` as `GtkBuildable` + +`AdwBreakpointBin` allows adding `AdwBreakpoint` objects as children. + +Example of an `AdwBreakpointBin` UI definition: + +```xml +<object class="AdwBreakpointBin"> + <property name="width-request">150</property> + <property name="height-request">150</property> + <property name="child"> + <object class="GtkLabel" id="child"> + <property name="label">Wide</property> + <property name="ellipsize">end</property> + <style> + <class name="title-1"/> + </style> + </object> + </property> + <child> + <object class="AdwBreakpoint"> + <condition>max-width: 200px</condition> + <setter object="child" property="label">Narrow</setter> + </object> + </child> +</object> +``` + +See [class@Breakpoint] documentation for details. + + + + + + Creates a new `AdwBreakpointBin`. + + + the newly created `AdwBreakpointBin` + + + + + Adds @breakpoint to @self. + + + + + + + a breakpoint bin + + + + the breakpoint to add + + + + + + Gets the child widget of @self. + + + the child widget of @self + + + + + a breakpoint bin + + + + + + Gets the current breakpoint. + + + the current breakpoint + + + + + a breakpoint bin + + + + + + Removes @breakpoint from @self. + + + + + + + a breakpoint bin + + + + a breakpoint to remove + + + + + + Sets the child widget of @self. + + + + + + + a breakpoint bin + + + + the child widget + + + + + + The child widget. + + + + The current breakpoint. + + + + + + + + + + + + + + + + + + + + + + + + + Describes condition for an [class@Breakpoint]. + + + Creates a condition that triggers when @condition_1 and @condition_2 are both +true. + + + the newly created condition + + + + + first condition + + + + second condition + + + + + + Creates a condition that triggers on length changes. + + + the newly created condition + + + + + the length type + + + + the length value + + + + the length unit + + + + + + Creates a condition that triggers when either @condition_1 or @condition_2 is +true. + + + the newly created condition + + + + + first condition + + + + second condition + + + + + + Creates a condition that triggers on ratio changes. + +The ratio is represented as @width divided by @height. + + + the newly created condition + + + + + the ratio type + + + + ratio width + + + + ratio height + + + + + + Copies @self. + + + a copy of @self + + + + + a breakpoint condition + + + + + + Frees @self. + + + + + + + a breakpoint condition + + + + + + Returns a textual representation of @self. + +The returned string can be parsed by [func@BreakpointCondition.parse]. + + + A newly allocated text string + + + + + a breakpoint condition + + + + + + Parses a condition from a string. + +Length conditions are specified as `<type>: <value>[<unit>]`, where: + +- `<type>` can be `min-width`, `max-width`, `min-height` or `max-height` +- `<value>` is a fractional number +- `<unit>` can be `px`, `pt` or `sp` + +If the unit is omitted, `px` is assumed. + +See [ctor@BreakpointCondition.new_length]. + +Examples: + +- `min-width: 500px` +- `min-height: 400pt` +- `max-width: 100sp` +- `max-height: 500` + +Ratio conditions are specified as `<type>: <width>[/<height>]`, where: + +- `<type>` can be `min-aspect-ratio` or `max-aspect-ratio` +- `<width>` and `<height>` are integer numbers + +See [ctor@BreakpointCondition.new_ratio]. + +The ratio is represented as `<width>` divided by `<height>`. + +If `<height>` is omitted, it's assumed to be 1. + +Examples: + +- `min-aspect-ratio: 4/3` +- `max-aspect-ratio: 1` + +The logical operators `and`, `or` can be used to compose a complex condition +as follows: + +- `<condition> and <condition>`: the condition is true when both + `<condition>`s are true, same as when using + [ctor@BreakpointCondition.new_and] +- `<condition> or <condition>`: the condition is true when either of the + `<condition>`s is true, same as when using + [ctor@BreakpointCondition.new_or] + +Examples: + +- `min-width: 400px and max-aspect-ratio: 4/3` +- `max-width: 360sp or max-width: 360px` + +Conditions can be further nested using parentheses, for example: + +- `min-width: 400px and (max-aspect-ratio: 4/3 or max-height: 400px)` + +If parentheses are omitted, the first operator takes priority. + + + the parsed condition + + + + + the string specifying the condition + + + + + + + Describes length types for [struct@BreakpointCondition]. + +See [ctor@BreakpointCondition.new_length]. + +New values may be added to this enumeration over time. + + true if the width is greater than or + equal to the condition value + + + true if the width is less than or + equal to the condition value + + + true if the height is greater than or + equal to the condition value + + + true if the height is less than or + equal to the condition value + + + + Describes ratio types for [struct@BreakpointCondition]. + +See [ctor@BreakpointCondition.new_ratio]. + +New values may be added to this enumeration over time. + + true if the aspect ratio is + greater than or equal to the condition value + + + true if the aspect ratio is + less than or equal to the condition value + + + + A helper widget for creating buttons. + +<picture> + <source srcset="button-content-dark.png" media="(prefers-color-scheme: dark)"> + <img src="button-content.png" alt="button-content"> +</picture> + +`AdwButtonContent` is a box-like widget with an icon and a label. + +It's intended to be used as a direct child of [class@Gtk.Button], +[class@Gtk.MenuButton] or [class@SplitButton], when they need to have both an +icon and a label, as follows: + +```xml +<object class="GtkButton"> + <property name="child"> + <object class="AdwButtonContent"> + <property name="icon-name">document-open-symbolic</property> + <property name="label" translatable="yes">_Open</property> + <property name="use-underline">True</property> + </object> + </property> +</object> +``` + +`AdwButtonContent` handles style classes and connecting the mnemonic to the +button automatically. + +## CSS nodes + +``` +buttoncontent +╰── box + ├── image + ╰── label +``` + +`AdwButtonContent`'s CSS node is called `buttoncontent`. It contains a `box` +subnode that serves as a container for the `image` and `label` nodes. + +When inside a `GtkButton` or `AdwSplitButton`, the button will receive the +`.image-text-button` style class. When inside a `GtkMenuButton`, the +internal `GtkButton` will receive it instead. + +## Accessibility + +`AdwButtonContent` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + + + + + Creates a new `AdwButtonContent`. + + + the new created `AdwButtonContent` + + + + + gets whether the button can be smaller than the natural size of its contents. + + + whether the button can shrink + + + + + a button content + + + + + + Gets the name of the displayed icon. + + + the icon name + + + + + a button content + + + + + + Gets the displayed label. + + + the label + + + + + a button content + + + + + + Gets whether an underline in the text indicates a mnemonic. + + + whether an underline in the text indicates a mnemonic + + + + + a button content + + + + + + Sets whether the button can be smaller than the natural size of its contents. + +If set to `TRUE`, the label will ellipsize. + +See [method@Gtk.Button.set_can_shrink]. + + + + + + + a button content + + + + whether the button can shrink + + + + + + Sets the name of the displayed icon. + +If empty, the icon is not shown. + + + + + + + a button content + + + + the new icon name + + + + + + Sets the displayed label. + + + + + + + a button content + + + + the new label + + + + + + Sets whether an underline in the text indicates a mnemonic. + +The mnemonic can be used to activate the parent button. + +See [property@ButtonContent:label]. + + + + + + + a button content + + + + whether an underline in the text indicates a mnemonic + + + + + + Whether the button can be smaller than the natural size of its contents. + +If set to `TRUE`, the label will ellipsize. + +See [property@Gtk.Button:can-shrink]. + + + + The name of the displayed icon. + +If empty, the icon is not shown. + + + + The displayed label. + + + + Whether an underline in the text indicates a mnemonic. + +The mnemonic can be used to activate the parent button. + +See [property@ButtonContent:label]. + + + + + + + + + + + A [class@Gtk.ListBoxRow] that looks like a button. + +<picture> + <source srcset="button-rows-dark.png" media="(prefers-color-scheme: dark)"> + <img src="button-rows.png" alt="button-rows"> +</picture> + +The `AdwButtonRow` widget has a title and two icons: before and after the +title. + +It is convenient for presenting actions like "Delete" at the end of a boxed +list. + +`AdwButtonRow` is always activatable. + +## CSS nodes + +`AdwButtonRow` has a main CSS node with name `row` and the style class +`.button`. + +It contains the subnode `box` for its main horizontal box, which contains the +nodes: `image.icon.start` for the start icon, `label.title` for the title, +and `image.icon.end` for the end icon. + +## Style classes + +The [`.suggested-action`](style-classes.html#suggested-action) style class +makes `AdwButtonRow` use accent color for its background. It should be used +very sparingly to denote important buttons. + +<picture> + <source srcset="button-row-suggested-action-dark.png" media="(prefers-color-scheme: dark)"> + <img src="button-row-suggested-action.png" alt="button-row-suggested-action"> +</picture> + +The [`.destructive-action`](style-classes.html#destructive-action) style +makes the row use destructive colors. It can be used to draw attention to the +potentially damaging consequences of using it. This style acts as a warning +to the user. + +<picture> + <source srcset="button-row-destructive-action-dark.png" media="(prefers-color-scheme: dark)"> + <img src="button-row-destructive-action.png" alt="button-row-destructive-action"> +</picture> + + + + + + + Creates a new `AdwButtonRow`. + + + the newly created `AdwButtonRow` + + + + + Gets the end icon name for @self. + + + the end icon name for @self + + + + + a button row + + + + + + Gets the start icon name for @self. + + + the start icon name for @self + + + + + a button row + + + + + + Sets the end icon name for @self. + + + + + + + a button row + + + + the end icon name + + + + + + Sets the start icon name for @self. + + + + + + + a button row + + + + the start icon name + + + + + + The icon name to show after the title. + + + + The icon name to show before the title. + + + + This signal is emitted after the row has been activated. + + + + + + + + + + + + + Compile-time version checking. Evaluates to `TRUE` if the version +of Adwaita is greater than the required one. + + + + required major version + + + required minor version + + + required micro version + + + + + An [class@AnimationTarget] that calls a given callback during the +animation. + + + Creates a new `AdwAnimationTarget` that calls the given @callback during +the animation. + + + the newly created callback target + + + + + the callback to call + + + + the data to be passed to @callback + + + + the function to be called when the + callback action is finalized + + + + + + + + + + A paginated scrolling widget. + +<picture> + <source srcset="carousel-dark.png" media="(prefers-color-scheme: dark)"> + <img src="carousel.png" alt="carousel"> +</picture> + +The `AdwCarousel` widget can be used to display a set of pages with +swipe-based navigation between them. + +[class@CarouselIndicatorDots] and [class@CarouselIndicatorLines] can be used +to provide page indicators for `AdwCarousel`. + +## CSS nodes + +`AdwCarousel` has a single CSS node with name `carousel`. + + + + + + + + Creates a new `AdwCarousel`. + + + the newly created `AdwCarousel` + + + + + Appends @child to @self. + + + + + + + a carousel + + + + a widget to add + + + + + + Gets whether to allow swiping for more than one page at a time. + + + `TRUE` if long swipes are allowed + + + + + a carousel + + + + + + Sets whether @self can be dragged with mouse pointer. + + + whether @self can be dragged with mouse pointer + + + + + a carousel + + + + + + Gets whether @self will respond to scroll wheel events. + + + `TRUE` if @self will respond to scroll wheel events + + + + + a carousel + + + + + + Gets whether @self can be navigated. + + + whether @self can be navigated + + + + + a carousel + + + + + + Gets the number of pages in @self. + + + the number of pages in @self + + + + + a carousel + + + + + + Gets the page at position @n. + + + the page + + + + + a carousel + + + + index of the page + + + + + + Gets current scroll position in @self, unitless. + +1 matches 1 page. Use [method@Carousel.scroll_to] for changing it. + + + the scroll position + + + + + a carousel + + + + + + Gets the page reveal duration, in milliseconds. + + + the duration + + + + + a carousel + + + + + + Gets the scroll animation spring parameters for @self. + + + the animation parameters + + + + + a carousel + + + + + + Gets spacing between pages in pixels. + + + spacing between pages + + + + + a carousel + + + + + + Inserts @child into @self at position @position. + +If position is -1, or larger than the number of pages, +@child will be appended to the end. + + + + + + + a carousel + + + + a widget to add + + + + the position to insert @child at + + + + + + Prepends @child to @self. + + + + + + + a carousel + + + + a widget to add + + + + + + Removes @child from @self. + + + + + + + a carousel + + + + a widget to remove + + + + + + Moves @child into position @position. + +If position is -1, or larger than the number of pages, @child will be moved +at the end. + + + + + + + a carousel + + + + a widget to add + + + + the position to move @child to + + + + + + Scrolls to @widget. + +If @animate is `TRUE`, the transition will be animated. + + + + + + + a carousel + + + + a child of @self + + + + whether to animate the transition + + + + + + Sets whether to allow swiping for more than one page at a time. + +If @allow_long_swipes is `FALSE`, each swipe can only move to the adjacent +pages. + + + + + + + a carousel + + + + whether to allow long swipes + + + + + + Sets whether @self can be dragged with mouse pointer. + +If @allow_mouse_drag is `FALSE`, dragging is only available on touch. + + + + + + + a carousel + + + + whether @self can be dragged with mouse pointer + + + + + + Sets whether @self will respond to scroll wheel events. + +If @allow_scroll_wheel is `FALSE`, wheel events will be ignored. + + + + + + + a carousel + + + + whether @self will respond to scroll wheel events + + + + + + Sets whether @self can be navigated. + +This can be used to temporarily disable the carousel to only allow navigating +it in a certain state. + + + + + + + a carousel + + + + whether @self can be navigated + + + + + + Sets the page reveal duration, in milliseconds. + +Reveal duration is used when animating adding or removing pages. + + + + + + + a carousel + + + + the new reveal duration value + + + + + + Sets the scroll animation spring parameters for @self. + +The default value is equivalent to: + +```c +adw_spring_params_new (1, 0.5, 500) +``` + + + + + + + a carousel + + + + the new parameters + + + + + + Sets spacing between pages in pixels. + + + + + + + a carousel + + + + the new spacing value + + + + + + Whether to allow swiping for more than one page at a time. + +If the value is `FALSE`, each swipe can only move to the adjacent pages. + + + + Sets whether the `AdwCarousel` can be dragged with mouse pointer. + +If the value is `FALSE`, dragging is only available on touch. + + + + Whether the widget will respond to scroll wheel events. + +If the value is `FALSE`, wheel events will be ignored. + + + + Whether the carousel can be navigated. + +This can be used to temporarily disable the carousel to only allow +navigating it in a certain state. + + + + The number of pages in a `AdwCarousel`. + + + + Current scrolling position, unitless. + +1 matches 1 page. Use [method@Carousel.scroll_to] for changing it. + + + + Page reveal duration, in milliseconds. + +Reveal duration is used when animating adding or removing pages. + + + + Scroll animation spring parameters. + +The default value is equivalent to: + +```c +adw_spring_params_new (1, 0.5, 500) +``` + + + + Spacing between pages in pixels. + + + + This signal is emitted after a page has been changed. + +It can be used to implement "infinite scrolling" by amending the pages +after every scroll. + +::: note + An empty carousel is indicated by `(int)index == -1`. + + + + + + current page + + + + + + + + + + + + + A dots indicator for [class@Carousel]. + +<picture> + <source srcset="carousel-indicator-dots-dark.png" media="(prefers-color-scheme: dark)"> + <img src="carousel-indicator-dots.png" alt="carousel-indicator-dots"> +</picture> + +The `AdwCarouselIndicatorDots` widget shows a set of dots for each page of a +given [class@Carousel]. The dot representing the carousel's active page is +larger and more opaque than the others, the transition to the active and +inactive state is gradual to match the carousel's position. + +See also [class@CarouselIndicatorLines]. + +## CSS nodes + +`AdwCarouselIndicatorDots` has a single CSS node with name +`carouselindicatordots`. + + + + + + + Creates a new `AdwCarouselIndicatorDots`. + + + the newly created `AdwCarouselIndicatorDots` + + + + + Gets the displayed carousel. + + + the displayed carousel + + + + + an indicator + + + + + + Sets the displayed carousel. + + + + + + + an indicator + + + + a carousel + + + + + + The displayed carousel. + + + + + + + + + + + A lines indicator for [class@Carousel]. + +<picture> + <source srcset="carousel-indicator-dots-lines.png" media="(prefers-color-scheme: dark)"> + <img src="carousel-indicator-lines.png" alt="carousel-indicator-lines"> +</picture> + +The `AdwCarouselIndicatorLines` widget shows a set of lines for each page of +a given [class@Carousel]. The carousel's active page is shown as another line +that moves between them to match the carousel's position. + +See also [class@CarouselIndicatorDots]. + +## CSS nodes + +`AdwCarouselIndicatorLines` has a single CSS node with name +`carouselindicatorlines`. + + + + + + + Creates a new `AdwCarouselIndicatorLines`. + + + the newly created `AdwCarouselIndicatorLines` + + + + + Gets the displayed carousel. + + + the displayed carousel + + + + + an indicator + + + + + + Sets the displayed carousel. + + + + + + + an indicator + + + + a carousel + + + + + + The displayed carousel. + + + + + + + + + + + Describes title centering behavior of a [class@HeaderBar] widget. + + Keep the title centered when possible + + + Keep the title centered at all cost + + + + A widget constraining its child to a given size. + +<picture> + <source srcset="clamp-wide-dark.png" media="(prefers-color-scheme: dark)"> + <img src="clamp-wide.png" alt="clamp-wide"> +</picture> +<picture> + <source srcset="clamp-narrow-dark.png" media="(prefers-color-scheme: dark)"> + <img src="clamp-narrow.png" alt="clamp-narrow"> +</picture> + +The `AdwClamp` widget constrains the size of the widget it contains to a +given maximum size. It will constrain the width if it is horizontal, or the +height if it is vertical. The expansion of the child from its minimum to its +maximum size is eased out for a smooth transition. + +If the child requires more than the requested maximum size, it will be +allocated the minimum size it can fit in instead. + +`AdwClamp` can scale with the text scale factor, use the +[property@Clamp:unit] property to enable that behavior. + +See also: [class@ClampLayout], [class@ClampScrollable]. + +## CSS nodes + +`AdwClamp` has a single CSS node with name `clamp`. + + + + + + + Creates a new `AdwClamp`. + + + the newly created `AdwClamp` + + + + + Gets the child widget of @self. + + + the child widget of @self + + + + + a clamp + + + + + + Gets the maximum size allocated to the child. + + + the maximum size to allocate to the child + + + + + a clamp + + + + + + Gets the size above which the child is clamped. + + + the size above which the child is clamped + + + + + a clamp + + + + + + Gets the length unit for maximum size and tightening threshold. + + + the length unit + + + + + a clamp + + + + + + Sets the child widget of @self. + + + + + + + a clamp + + + + the child widget + + + + + + Sets the maximum size allocated to the child. + +It is the width if the clamp is horizontal, or the height if it is vertical. + + + + + + + a clamp + + + + the maximum size + + + + + + Sets the size above which the child is clamped. + +Starting from this size, the clamp will tighten its grip on the child, slowly +allocating less and less of the available size up to the maximum allocated +size. Below that threshold and below the maximum size, the child will be +allocated all the available size. + +If the threshold is greater than the maximum size to allocate to the child, +the child will be allocated all the size up to the maximum. If the threshold +is lower than the minimum size to allocate to the child, that size will be +used as the tightening threshold. + +Effectively, tightening the grip on the child before it reaches its maximum +size makes transitions to and from the maximum size smoother when resizing. + + + + + + + a clamp + + + + the tightening threshold + + + + + + Sets the length unit for maximum size and tightening threshold. + +Allows the sizes to vary depending on the text scale factor. + + + + + + + a clamp + + + + the length unit + + + + + + The child widget of the `AdwClamp`. + + + + The maximum size allocated to the child. + +It is the width if the clamp is horizontal, or the height if it is vertical. + + + + The size above which the child is clamped. + +Starting from this size, the clamp will tighten its grip on the child, +slowly allocating less and less of the available size up to the maximum +allocated size. Below that threshold and below the maximum size, the child +will be allocated all the available size. + +If the threshold is greater than the maximum size to allocate to the child, +the child will be allocated all the size up to the maximum. +If the threshold is lower than the minimum size to allocate to the child, +that size will be used as the tightening threshold. + +Effectively, tightening the grip on the child before it reaches its maximum +size makes transitions to and from the maximum size smoother when resizing. + + + + The length unit for maximum size and tightening threshold. + +Allows the sizes to vary depending on the text scale factor. + + + + + + + + + + + A layout manager constraining its children to a given size. + +<picture> + <source srcset="clamp-wide-dark.png" media="(prefers-color-scheme: dark)"> + <img src="clamp-wide.png" alt="clamp-wide"> +</picture> +<picture> + <source srcset="clamp-narrow-dark.png" media="(prefers-color-scheme: dark)"> + <img src="clamp-narrow.png" alt="clamp-narrow"> +</picture> + +`AdwClampLayout` constraints the size of the widgets it contains to a given +maximum size. It will constrain the width if it is horizontal, or the height +if it is vertical. The expansion of the children from their minimum to their +maximum size is eased out for a smooth transition. + +If a child requires more than the requested maximum size, it will be +allocated the minimum size it can fit in instead. + +`AdwClampLayout` can scale with the text scale factor, use the +[property@ClampLayout:unit] property to enable that behavior. + +See also: [class@Clamp], [class@ClampScrollable]. + + + + Creates a new `AdwClampLayout`. + + + the newly created `AdwClampLayout` + + + + + Gets the maximum size allocated to the children. + + + the maximum size to allocate to the children + + + + + a clamp layout + + + + + + Gets the size above which the children are clamped. + + + the size above which the children are clamped + + + + + a clamp layout + + + + + + Gets the length unit for maximum size and tightening threshold. + + + the length unit + + + + + a clamp layout + + + + + + Sets the maximum size allocated to the children. + +It is the width if the layout is horizontal, or the height if it is vertical. + + + + + + + a clamp layout + + + + the maximum size + + + + + + Sets the size above which the children are clamped. + +Starting from this size, the layout will tighten its grip on the children, +slowly allocating less and less of the available size up to the maximum +allocated size. Below that threshold and below the maximum size, the children +will be allocated all the available size. + +If the threshold is greater than the maximum size to allocate to the +children, they will be allocated the whole size up to the maximum. If the +threshold is lower than the minimum size to allocate to the children, that +size will be used as the tightening threshold. + +Effectively, tightening the grip on a child before it reaches its maximum +size makes transitions to and from the maximum size smoother when resizing. + + + + + + + a clamp layout + + + + the tightening threshold + + + + + + Sets the length unit for maximum size and tightening threshold. + +Allows the sizes to vary depending on the text scale factor. + + + + + + + a clamp layout + + + + the length unit + + + + + + The maximum size to allocate to the children. + +It is the width if the layout is horizontal, or the height if it is +vertical. + + + + The size above which the children are clamped. + +Starting from this size, the layout will tighten its grip on the children, +slowly allocating less and less of the available size up to the maximum +allocated size. Below that threshold and below the maximum size, the +children will be allocated all the available size. + +If the threshold is greater than the maximum size to allocate to the +children, they will be allocated the whole size up to the maximum. If the +threshold is lower than the minimum size to allocate to the children, that +size will be used as the tightening threshold. + +Effectively, tightening the grip on a child before it reaches its maximum +size makes transitions to and from the maximum size smoother when resizing. + + + + The length unit for maximum size and tightening threshold. + +Allows the sizes to vary depending on the text scale factor. + + + + + + + + + + + A scrollable [class@Clamp]. + +`AdwClampScrollable` is a variant of [class@Clamp] that implements the +[iface@Gtk.Scrollable] interface. + +The primary use case for `AdwClampScrollable` is clamping +[class@Gtk.ListView]. + +See also: [class@ClampLayout]. + + + + + + + + Creates a new `AdwClampScrollable`. + + + the newly created `AdwClampScrollable` + + + + + Gets the child widget of @self. + + + the child widget of @self + + + + + a clamp scrollable + + + + + + Gets the maximum size allocated to the child. + + + the maximum size to allocate to the child + + + + + a clamp scrollable + + + + + + Gets the size above which the child is clamped. + + + the size above which the child is clamped + + + + + a clamp scrollable + + + + + + Gets the length unit for maximum size and tightening threshold. + + + the length unit + + + + + a clamp scrollable + + + + + + Sets the child widget of @self. + + + + + + + a clamp scrollable + + + + the child widget + + + + + + Sets the maximum size allocated to the child. + +It is the width if the clamp is horizontal, or the height if it is vertical. + + + + + + + a clamp scrollable + + + + the maximum size + + + + + + Sets the size above which the child is clamped. + +Starting from this size, the clamp will tighten its grip on the child, slowly +allocating less and less of the available size up to the maximum allocated +size. Below that threshold and below the maximum width, the child will be +allocated all the available size. + +If the threshold is greater than the maximum size to allocate to the child, +the child will be allocated all the width up to the maximum. If the threshold +is lower than the minimum size to allocate to the child, that size will be +used as the tightening threshold. + +Effectively, tightening the grip on the child before it reaches its maximum +size makes transitions to and from the maximum size smoother when resizing. + + + + + + + a clamp scrollable + + + + the tightening threshold + + + + + + Sets the length unit for maximum size and tightening threshold. + +Allows the sizes to vary depending on the text scale factor. + + + + + + + a clamp + + + + the length unit + + + + + + The child widget of the `AdwClampScrollable`. + + + + The maximum size allocated to the child. + +It is the width if the clamp is horizontal, or the height if it is vertical. + + + + The size above which the child is clamped. + +Starting from this size, the clamp will tighten its grip on the child, +slowly allocating less and less of the available size up to the maximum +allocated size. Below that threshold and below the maximum width, the child +will be allocated all the available size. + +If the threshold is greater than the maximum size to allocate to the child, +the child will be allocated all the width up to the maximum. +If the threshold is lower than the minimum size to allocate to the child, +that size will be used as the tightening threshold. + +Effectively, tightening the grip on the child before it reaches its maximum +size makes transitions to and from the maximum size smoother when resizing. + + + + The length unit for maximum size and tightening threshold. + +Allows the sizes to vary depending on the text scale factor. + + + + + + + + + + + Application color schemes for [property@StyleManager:color-scheme]. + + Inherit the parent color-scheme. When set on the + `AdwStyleManager` returned by [func@StyleManager.get_default], it's + equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT`. + + + Always use light appearance. + + + Use light appearance unless the system + prefers dark colors. + + + Use dark appearance unless the system prefers + prefers light colors. + + + Always use dark appearance. + + + + A [class@Gtk.ListBoxRow] used to choose from a list of items. + +<picture> + <source srcset="combo-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="combo-row.png" alt="combo-row"> +</picture> + +The `AdwComboRow` widget allows the user to choose from a list of valid +choices. The row displays the selected choice. When activated, the row +displays a popover which allows the user to make a new choice. + +Example of an `AdwComboRow` UI definition: +```xml +<object class="AdwComboRow"> + <property name="title" translatable="yes">Combo Row</property> + <property name="model"> + <object class="GtkStringList"> + <items> + <item translatable="yes">Foo</item> + <item translatable="yes">Bar</item> + <item translatable="yes">Baz</item> + </items> + </object> + </property> +</object> +``` + +The [property@ComboRow:selected] and [property@ComboRow:selected-item] +properties can be used to keep track of the selected item and react to their +changes. + +`AdwComboRow` mirrors [class@Gtk.DropDown], see that widget for details. + +`AdwComboRow` is [property@Gtk.ListBoxRow:activatable] if a model is set. + +## CSS nodes + +`AdwComboRow` has a main CSS node with name `row` and the `.combo` style +class. + +Its popover has the node named `popover` with the `.menu` style class, it +contains a [class@Gtk.ScrolledWindow], which in turn contains a +[class@Gtk.ListView], both are accessible via their regular nodes. + +## Accessibility + +`AdwComboRow` uses the `GTK_ACCESSIBLE_ROLE_COMBO_BOX` role. + + + + + + + Creates a new `AdwComboRow`. + + + the newly created `AdwComboRow` + + + + + Gets whether search is enabled. + +If set to `TRUE`, a search entry will be shown in the popup that +allows to search for items in the list. + +Search requires [property@ComboRow:expression] to be set. + + + whether the popup includes a search entry + + + + + a combo row + + + + + + Gets the expression used to obtain strings from items. + + + the expression used to obtain strings from items + + + + + a combo row + + + + + + Gets the factory for populating list items. + + + the factory in use + + + + + a combo row + + + + + + Gets the factory that's currently used to create header widgets for the popup. + + + The factory in use + + + + + a combo row + + + + + + Gets the factory for populating list items in the popup. + + + the factory in use + + + + + a combo row + + + + + + Gets the model that provides the displayed items. + + + The model in use + + + + + a combo row + + + + + + Returns the match mode that the search filter is using. + + + the match mode of the search filter + + + + + a combo row + + + + + + Gets the position of the selected item. + + + the position of the selected item, or + [const@Gtk.INVALID_LIST_POSITION] if no item is selected + + + + + a combo row + + + + + + Gets the selected item. + + + the selected item + + + + + a combo row + + + + + + Gets whether to use the current value as the subtitle. + + + whether to use the current value as the subtitle + + + + + a combo row + + + + + + Sets whether to enable search. + +If set to `TRUE`, a search entry will be shown in the popup that +allows to search for items in the list. + +Search requires [property@ComboRow:expression] to be set. + + + + + + + a combo row + + + + whether to enable search + + + + + + Sets the expression used to obtain strings from items. + +The expression must have a value type of `G_TYPE_STRING`. + +It's used to bind strings to labels produced by the default factory if +[property@ComboRow:factory] is not set, or when +[property@ComboRow:use-subtitle] is set to `TRUE`. + + + + + + + a combo row + + + + an expression + + + + + + Sets the factory for populating list items. + +This factory is always used for the item in the row. It is also used for +items in the popup unless [property@ComboRow:list-factory] is set. + + + + + + + a combo row + + + + the factory to use + + + + + + Sets the factory to use for creating header widgets for the popup. + + + + + + + a combo row + + + + the factory to use + + + + + + Sets the factory for populating list items in the popup. + +If this is not set, [property@ComboRow:factory] is used. + + + + + + + a combo row + + + + the factory to use + + + + + + Sets the model that provides the displayed items. + + + + + + + a combo row + + + + the model to use + + + + + + Sets the match mode for the search filter. + + + + + + + a combo row + + + + the new match mode + + + + + + Selects the item at the given position. + + + + + + + a combo row + + + + the position of the item to select, or + [const@Gtk.INVALID_LIST_POSITION] + + + + + + Sets whether to use the current value as the subtitle. + +If you use a custom list item factory, you will need to give the row a +name conversion expression with [property@ComboRow:expression]. + +If set to `TRUE`, you should not access [property@ActionRow:subtitle]. + +The subtitle is interpreted as Pango markup if +[property@PreferencesRow:use-markup] is set to `TRUE`. + + + + + + + a combo row + + + + whether to use the current value as the subtitle + + + + + + Whether to show a search entry in the popup. + +If set to `TRUE`, a search entry will be shown in the popup that +allows to search for items in the list. + +Search requires [property@ComboRow:expression] to be set. + + + + An expression used to obtain strings from items. + +The expression must have a value type of `G_TYPE_STRING`. + +It's used to bind strings to labels produced by the default factory if +[property@ComboRow:factory] is not set, or when +[property@ComboRow:use-subtitle] is set to `TRUE`. + + + + Factory for populating list items. + +This factory is always used for the item in the row. It is also used for +items in the popup unless [property@ComboRow:list-factory] is set. + + + + The factory for creating header widgets for the popup. + + + + The factory for populating list items in the popup. + +If this is not set, [property@ComboRow:factory] is used. + + + + The model that provides the displayed items. + + + + The match mode for the search filter. + + + + The position of the selected item. + +If no item is selected, the property has the value +[const@Gtk.INVALID_LIST_POSITION] + + + + The selected item. + + + + Whether to use the current value as the subtitle. + +If you use a custom list item factory, you will need to give the row a +name conversion expression with [property@ComboRow:expression]. + +If set to `TRUE`, you should not access [property@ActionRow:subtitle]. + +The subtitle is interpreted as Pango markup if +[property@PreferencesRow:use-markup] is set to `TRUE`. + + + + + + + + + + The parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Indicates an [class@Animation] with an infinite duration. + +This value is mostly used internally. + + + + + An adaptive dialog container. + +<picture> + <source srcset="dialog-floating-dark.png" media="(prefers-color-scheme: dark)"> + <img src="dialog-floating.png" alt="dialog-floating"> +</picture> +<picture> + <source srcset="dialog-bottom-dark.png" media="(prefers-color-scheme: dark)"> + <img src="dialog-bottom.png" alt="dialog-bottom"> +</picture> + +`AdwDialog` is similar to a window, but is shown within another window. It +can be used with [class@Window] and [class@ApplicationWindow], use +[method@Dialog.present] to show it. + +`AdwDialog` is not resizable. Use the [property@Dialog:content-width] and +[property@Dialog:content-height] properties to set its size, or set +[property@Dialog:follows-content-size] to `TRUE` to make the dialog track the +content's size as it changes. `AdwDialog` can never be larger than its parent +window. + +`AdwDialog` can be presented as a centered floating window or a bottom sheet. +By default it's automatic depending on the available size. +[property@Dialog:presentation-mode] can be used to change that. + +`AdwDialog` can be closed via [method@Dialog.close]. + +When presented as a bottom sheet, `AdwDialog` can also be closed via swiping +it down. + +The [property@Dialog:can-close] can be used to prevent closing. In that case, +[signal@Dialog::close-attempt] gets emitted instead. + +Use [method@Dialog.force_close] to close the dialog even when `can-close` is set to +`FALSE`. + +`AdwDialog` is transient and doesn't integrate with the window below it, for +example it's not possible to collapse it into a bottom bar. See +[class@BottomSheet] for persistent and more tightly integrated bottom sheets. + +## Header Bar Integration + +When placed inside an `AdwDialog`, [class@HeaderBar] will display the dialog +title instead of window title. It will also adjust the decoration layout to +ensure it always has a close button and nothing else. Set +[property@HeaderBar:show-start-title-buttons] and +[property@HeaderBar:show-end-title-buttons] to `FALSE` to remove it if it's +unwanted. + +## Breakpoints + +`AdwDialog` can be used with [class@Breakpoint] the same way as +[class@BreakpointBin]. Refer to that widget's documentation for details. + +Like `AdwBreakpointBin`, if breakpoints are used, `AdwDialog` doesn't have a +minimum size, and [property@Gtk.Widget:width-request] and +[property@Gtk.Widget:height-request] properties must be set manually. + + + + + + + Creates a new `AdwDialog`. + + + the new created `AdwDialog` + + + + + + + + + + + + + + + + + + + + + + + + + + + Adds @breakpoint to @self. + + + + + + + a dialog + + + + the breakpoint to add + + + + + + Attempts to close @self. + +If the [property@Dialog:can-close] property is set to `FALSE`, the +[signal@Dialog::close-attempt] signal is emitted. + +See also: [method@Dialog.force_close]. + + + whether @self was successfully closed + + + + + a dialog + + + + + + Closes @self. + +Unlike [method@Dialog.close], it succeeds even if [property@Dialog:can-close] +is set to `FALSE`. + + + + + + + a dialog + + + + + + Gets whether @self can be closed. + + + whether the dialog can be closed + + + + + a dialog + + + + + + Gets the child widget of @self. + + + the child widget of @self + + + + + a dialog + + + + + + Gets the height of the dialog's contents. + + + the content height + + + + + a dialog + + + + + + Gets the width of the dialog's contents. + + + the content width + + + + + a dialog + + + + + + Gets the current breakpoint. + + + the current breakpoint + + + + + a dialog + + + + + + Gets the default widget for @self. + + + the default widget + + + + + a dialog + + + + + + Gets the focus widget for @self. + + + the focus widget + + + + + a dialog + + + + + + Gets whether to size content of @self automatically. + + + whether to size content automatically + + + + + a dialog + + + + + + Gets presentation mode for @self. + + + the presentation mode + + + + + a dialog + + + + + + Gets the title of @self. + + + the title + + + + + a dialog + + + + + + Presents @self within @parent's window. + +If @self is already shown, raises it to the top instead. + +If the window is an [class@Window] or [class@ApplicationWindow], the dialog +will be shown within it. Otherwise, it will be a separate window. + + + + + + + a dialog + + + + a widget within the toplevel + + + + + + Sets whether @self can be closed. + +If set to `FALSE`, the close button, shortcuts and +[method@Dialog.close] will result in [signal@Dialog::close-attempt] being +emitted instead, and bottom sheet close swipe will be disabled. +[method@Dialog.force_close] still works. + + + + + + + a dialog + + + + whether to allow closing + + + + + + Sets the child widget of @self. + + + + + + + a dialog + + + + the child widget + + + + + + Sets the height of the dialog's contents. + +Set it to -1 to reset it to the content's natural height. + +See also: [property@Gtk.Window:default-height] + + + + + + + a dialog + + + + the content height + + + + + + Sets the width of the dialog's contents. + +Set it to -1 to reset it to the content's natural width. + +See also: [property@Gtk.Window:default-width] + + + + + + + a dialog + + + + the content width + + + + + + Sets the default widget for @self. + +It's activated when the user presses Enter. + + + + + + + a dialog + + + + the default widget + + + + + + Sets the focus widget for @self. + +If @focus is not the current focus widget, and is focusable, sets it as the +focus widget for the dialog. + +If focus is `NULL`, unsets the focus widget for this dialog. To set the focus +to a particular widget in the dialog, it is usually more convenient to use +[method@Gtk.Widget.grab_focus] instead of this function. + + + + + + + a dialog + + + + the focus widget + + + + + + Sets whether to size content of @self automatically. + +If set to `TRUE`, always use the content's natural size instead of +[property@Dialog:content-width] and [property@Dialog:content-height]. If +the content resizes, the dialog will immediately resize as well. + +See also: [property@Gtk.Window:resizable] + + + + + + + a dialog + + + + whether to size content automatically + + + + + + Sets presentation mode for @self. + +When set to `ADW_DIALOG_AUTO`, the dialog appears as a bottom sheet when the +following condition is met: `max-width: 450px or max-height: 360px`, and as a +floating window otherwise. + +Set it to `ADW_DIALOG_FLOATING` or `ADW_DIALOG_BOTTOM_SHEET` to always +present it a floating window or a bottom sheet respectively, regardless of +available size. + +Presentation mode does nothing for dialogs presented as a window. + + + + + + + a dialog + + + + the new presentation mode + + + + + + Sets the title of @self. + + + + + + + a dialog + + + + the new title + + + + + + Whether the dialog can be closed. + +If set to `FALSE`, the close button, shortcuts and +[method@Dialog.close] will result in [signal@Dialog::close-attempt] being +emitted instead, and bottom sheet close swipe will be disabled. +[method@Dialog.force_close] still works. + + + + The child widget of the `AdwDialog`. + + + + The height of the dialog's contents. + +Set it to -1 to reset it to the content's natural height. + +See also: [property@Gtk.Window:default-height] + + + + The width of the dialog's contents. + +Set it to -1 to reset it to the content's natural width. + +See also: [property@Gtk.Window:default-width] + + + + The current breakpoint. + + + + The default widget. + +It's activated when the user presses Enter. + + + + The focus widget. + + + + Whether to size content automatically. + +If set to `TRUE`, always use the content's natural size instead of +[property@Dialog:content-width] and [property@Dialog:content-height]. If +the content resizes, the dialog will immediately resize as well. + +See also: [property@Gtk.Window:resizable] + + + + The dialog's presentation mode. + +When set to `ADW_DIALOG_AUTO`, the dialog appears as a bottom sheet when +the following condition is met: `max-width: 450px or max-height: 360px`, +and as a floating window otherwise. + +Set it to `ADW_DIALOG_FLOATING` or `ADW_DIALOG_BOTTOM_SHEET` to always +present it a floating window or a bottom sheet respectively, regardless of +available size. + +Presentation mode does nothing for dialogs presented as a window. + + + + The title of the dialog. + + + + + + + Emitted when the close button or shortcut is used, or +[method@Dialog.close] is called while [property@Dialog:can-close] is set to +`FALSE`. + + + + + + Emitted when the dialog is successfully closed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Describes the available presentation modes for [class@Dialog]. + +New values may be added to this enumeration over time. + +See [property@Dialog:presentation-mode]. + + Switch between `ADW_DIALOG_FLOATING` and + `ADW_DIALOG_BOTTOM_SHEET` depending on available size. + + + Present dialog as a centered floating window. + + + Present dialog as a bottom sheet. + + + + + + + + + + + + + + + Describes the available easing functions for use with +[class@TimedAnimation]. + +New values may be added to this enumeration over time. + + Linear tweening. + + + Quadratic tweening. + + + Quadratic tweening, inverse of `ADW_EASE_IN_QUAD`. + + + Quadratic tweening, combining `ADW_EASE_IN_QUAD` and + `ADW_EASE_OUT_QUAD`. + + + Cubic tweening. + + + Cubic tweening, inverse of `ADW_EASE_IN_CUBIC`. + + + Cubic tweening, combining `ADW_EASE_IN_CUBIC` and + `ADW_EASE_OUT_CUBIC`. + Quartic tweening. - - + filename="src/adw-easing.c" + line="33">Quartic tweening. + + + Quartic tweening, inverse of `ADW_EASE_IN_QUART`. + + + Quartic tweening, combining `ADW_EASE_IN_QUART` and + `ADW_EASE_OUT_QUART`. + + + Quintic tweening. + + + Quintic tweening, inverse of `ADW_EASE_IN_QUINT`. + + + Quintic tweening, combining `ADW_EASE_IN_QUINT` and + `ADW_EASE_OUT_QUINT`. + + + Sine wave tweening. + + + Sine wave tweening, inverse of `ADW_EASE_IN_SINE`. + + + Sine wave tweening, combining `ADW_EASE_IN_SINE` and + `ADW_EASE_OUT_SINE`. + + + Exponential tweening. + + + Exponential tweening, inverse of `ADW_EASE_IN_EXPO`. + + + Exponential tweening, combining `ADW_EASE_IN_EXPO` and + `ADW_EASE_OUT_EXPO`. + + + Circular tweening. + + + Circular tweening, inverse of `ADW_EASE_IN_CIRC`. + + + Circular tweening, combining `ADW_EASE_IN_CIRC` and + `ADW_EASE_OUT_CIRC`. + + + Elastic tweening, with offshoot on start. + + + Elastic tweening, with offshoot on end, inverse of + `ADW_EASE_IN_ELASTIC`. + + + Elastic tweening, with offshoot on both ends, + combining `ADW_EASE_IN_ELASTIC` and `ADW_EASE_OUT_ELASTIC`. + + + Overshooting cubic tweening, with backtracking on start. + + + Overshooting cubic tweening, with backtracking on end, + inverse of `ADW_EASE_IN_BACK`. + + + Overshooting cubic tweening, with backtracking on both + ends, combining `ADW_EASE_IN_BACK` and `ADW_EASE_OUT_BACK`. + + + Exponentially decaying parabolic (bounce) tweening, + on start. + + + Exponentially decaying parabolic (bounce) tweening, + with bounce on end, inverse of `ADW_EASE_IN_BOUNCE`. + + + Exponentially decaying parabolic (bounce) tweening, + with bounce on both ends, combining `ADW_EASE_IN_BOUNCE` and + `ADW_EASE_OUT_BOUNCE`. + + + Cubic bezier tweening, with control points in (0.25, 0.1) and (0.25, 1.0). + +Increases in velocity towards the middle of the animation, slowing back down +at the end. + + + Cubic bezier tweening, with control points in (0.42, 0.0) and (1.0, 1.0). + +Starts off slowly, with the speed of the animation increasing until complete. + + + Cubic bezier tweening, with control points in (0.0, 0.0) and (0.58, 1.0). + +Starts quickly, slowing down the animation until complete. + + + Cubic bezier tweening, with control points in (0.42, 0.0) and (0.58, 1.0). + +Starts off slowly, speeds up in the middle, and then slows down again. + + + Computes easing with @easing for @value. + +@value should generally be in the [0, 1] range. + + + the easing for @value + + + + + an easing value + + + + a value to ease + + + + + + + A [class@Gtk.ListBoxRow] with an embedded text entry. + +<picture> + <source srcset="entry-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="entry-row.png" alt="entry-row"> +</picture> + +`AdwEntryRow` has a title that doubles as placeholder text. It shows an icon +indicating that it's editable and can receive additional widgets before or +after the editable part. + +If [property@EntryRow:show-apply-button] is set to `TRUE`, `AdwEntryRow` can +show an apply button when editing its contents. This can be useful if +changing its contents can result in an expensive operation, such as network +activity. + +`AdwEntryRow` provides only minimal API and should be used with the +[iface@Gtk.Editable] API. + +See also [class@PasswordEntryRow]. + +## AdwEntryRow as GtkBuildable + +The `AdwEntryRow` implementation of the [iface@Gtk.Buildable] interface +supports adding a child at its end by specifying “suffix” or omitting the +“type” attribute of a <child> element. + +It also supports adding a child as a prefix widget by specifying “prefix” as +the “type” attribute of a <child> element. + +## CSS nodes + +`AdwEntryRow` has a single CSS node with name `row` and the `.entry` style +class. + + + + + + + + Creates a new `AdwEntryRow`. + + + the newly created `AdwEntryRow` + + + + + Adds a prefix widget to @self. + + + + + + + an entry row + + + + a widget + + + + + + Adds a suffix widget to @self. + + + + + + + an entry row + + + + a widget + + + + + + Gets whether activating the embedded entry can activate the default widget. + + + whether to activate the default widget + + + + + an entry row + + + + + + Gets Pango attributes applied to the text of the embedded entry. + + + the list of attributes + + + + + an entry row + + + + + + Gets whether to suggest emoji replacements on @self. + + + whether or not emoji completion is enabled + + + + + an entry row + + + + + + Gets the additional input hints of @self. + + + The input hints + + + + + an entry row + + + + + + Gets the input purpose of @self. + + + the input purpose + + + + + an entry row + + + + + + Retrieves the maximum length of the entry. + + + The maximum length of the entry. + + + + + an entry row + + + + + + Gets whether @self can show the apply button. + + + whether to show the apply button + + + + + an entry row + + + + + + Retrieves the current length of the text in @self. + + + The current number of characters in @self, or 0 if there are none. + + + + + an entry row + + + + + + Causes @self to have keyboard focus without selecting the text. + +See [method@Gtk.Text.grab_focus_without_selecting] for more information. + + + whether the focus is now inside @self + + + + + an entry row + + + + + + Removes a child from @self. + + + + + + + an entry row + + + + the child to be removed + + + + + + Sets whether activating the embedded entry can activate the default widget. + + + + + + + an entry row + + + + whether to activate the default widget + + + + + + Sets Pango attributes to apply to the text of the embedded entry. + +The [struct@Pango.Attribute]'s `start_index` and `end_index` must refer to +the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. + + + + + + + an entry row + + + + a list of attributes + + + + + + Sets whether to suggest emoji replacements on @self. + +Emoji replacement is done with :-delimited names, like `:heart:`. + + + + + + + an entry row + + + + Whether emoji completion should be enabled or not + + + + + + Set additional input hints for @self. + +Input hints allow input methods to fine-tune their behavior. + +See also: [property@AdwEntryRow:input-purpose] + + + + + + + an entry row + + + + the hints + + + + + + Sets the input purpose of @self. + +The input purpose can be used by input methods to adjust their behavior. + + + + + + + an entry row + + + + the purpose + + + + + + Sets the maximum length of the entry. + + + + + + + an entry row + + + + maximum length of the entry + + + + + + Sets whether @self can show the apply button. + +When set to `TRUE`, typing text in the entry will reveal an apply button. +Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and +emit the [signal@EntryRow::apply] signal. + +This is useful if changing the entry contents can trigger an expensive +operation, e.g. network activity, to avoid triggering it after typing every +character. + + + + + + + an entry row + + + + whether to show the apply button + + + + + + Whether activating the embedded entry can activate the default widget. + + + + A list of Pango attributes to apply to the text of the embedded entry. + +The [struct@Pango.Attribute]'s `start_index` and `end_index` must refer to +the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. + + + + Whether to suggest emoji replacements on the entry row. + +Emoji replacement is done with :-delimited names, like `:heart:`. + + + + Additional input hints for the entry row. + +Input hints allow input methods to fine-tune their behavior. + +See also: [property@Adw.EntryRow:input-purpose] + + + + The input purpose of the entry row. + +The input purpose can be used by input methods to adjust their behavior. + + + + Maximum number of characters for the entry. + + + + Whether to show the apply button. + +When set to `TRUE`, typing text in the entry will reveal an apply button. +Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and +emit the [signal@EntryRow::apply] signal. + +This is useful if changing the entry contents can trigger an expensive +operation, e.g. network activity, to avoid triggering it after typing every +character. + + + + The length of the text in the entry row. + + + + + + + Emitted when the apply button is pressed. + +See [property@EntryRow:show-apply-button]. + + + + + + Emitted when the embedded entry is activated. + + + + + + + + + The parent class + + + + + `AdwEnumListItem` is the type of items in a [class@EnumListModel]. + + + Gets the enum value name. + + + the enum value name + + + + + + + + + + Gets the enum value nick. + + + the enum value nick + + + + + + + + + + Gets the enum value. + + + the enum value + + + + + + + + + + The enum value name. + + + + The enum value nick. + + + + The enum value. + + + + + + + + + + + A [iface@Gio.ListModel] representing values of a given enum. + +`AdwEnumListModel` contains objects of type [class@EnumListItem]. + + + + Creates a new `AdwEnumListModel` for @enum_type. + + + the newly created `AdwEnumListModel` + + + + + the type of the enum to construct the model from + + + + + + Finds the position of a given enum value in @self. + +If the value is not found, `GTK_INVALID_LIST_POSITION` is returned. + + + the position of the value + + + + + + + + an enum value + + + + + + Gets the type of the enum represented by @self. + + + the enum type + + + + + + + + + + The type of the enum represented by the model. + + + + + + + + + + + A [class@Gtk.ListBoxRow] used to reveal widgets. + +<picture> + <source srcset="expander-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="expander-row.png" alt="expander-row"> +</picture> + +The `AdwExpanderRow` widget allows the user to reveal or hide widgets below +it. It also allows the user to enable the expansion of the row, allowing to +disable all that the row contains. + +## AdwExpanderRow as GtkBuildable + +The `AdwExpanderRow` implementation of the [iface@Gtk.Buildable] interface +supports adding a child as an suffix widget by specifying “suffix” as the +“type” attribute of a <child> element. + +It also supports adding it as a prefix widget by specifying “prefix” as the +“type” attribute of a <child> element. + +## CSS nodes + +`AdwExpanderRow` has a main CSS node with name `row` and the `.expander` +style class. It has the `.empty` style class when it contains no children. + +It contains the subnodes `row.header` for its main embedded row, +`list.nested` for the list it can expand, and `image.expander-row-arrow` for +its arrow. + +## Style classes + +`AdwExpanderRow` can use the [`.`](style-classes.html#property-rows) +style class to emphasize the row subtitle instead of the row title, which is +useful for displaying read-only properties. + +When used together with the `.monospace` style class, only the subtitle +becomes monospace, not the title or any extra widgets. + + + + + + + Creates a new `AdwExpanderRow`. + + + the newly created `AdwExpanderRow` + + + + + Adds an action widget to @self. + Use [method@ExpanderRow.add_suffix] to add a suffix. + + + + + + + an expander row + + + + a widget + + + + + + Adds a prefix widget to @self. + + + + + + + an expander row + + + + a widget + + + + + + Adds a widget to @self. + +The widget will appear in the expanding list below @self. + + + + + + + an expander row + + + + a widget + + + + + + Adds an suffix widget to @self. + + + + + + + an expander row + + + + a widget + + + + + + Gets whether the expansion of @self is enabled. + + + whether the expansion of @self is enabled. + + + + + an expander row + + + + + + Gets whether @self is expanded. + + + whether @self is expanded + + + + + an expander row + + + + + + Gets the icon name for @self. + Use [method@ExpanderRow.add_prefix] to add an icon. + + + the icon name for @self + + + + + an expander row + + + + + + Gets whether the switch enabling the expansion of @self is visible. + + + whether the switch enabling the expansion is visible + + + + + an expander row + + + + + + Gets the subtitle for @self. + + + the subtitle for @self + + + + + an expander row + + + + + + Gets the number of lines at the end of which the subtitle label will be +ellipsized. + + + the number of lines at the end of which the subtitle label will be + ellipsized + + + + + an expander row + + + + + + Gets the number of lines at the end of which the title label will be +ellipsized. + + + the number of lines at the end of which the title label will be + ellipsized + + + + + an expander row + + + + + + Removes a child from @self. + + + + + + + an expander row + + + + the child to be removed + + + + + + Sets whether the expansion of @self is enabled. + + + + + + + an expander row + + + + whether to enable the expansion + + + + + + Sets whether @self is expanded. + + + + + + + an expander row + + + + whether to expand the row + + + + + + Sets the icon name for @self. + Use [method@ExpanderRow.add_prefix] to add an icon. + + + + + + + an expander row + + + + the icon name + + + + + + Sets whether the switch enabling the expansion of @self is visible. + + + + + + + an expander row + + + + whether to show the switch enabling the expansion + + + + + + Sets the subtitle for @self. + +The subtitle is interpreted as Pango markup unless +[property@PreferencesRow:use-markup] is set to `FALSE`. + + + + + + + an expander row + + + + the subtitle + + + + + + Sets the number of lines at the end of which the subtitle label will be +ellipsized. + +If the value is 0, the number of lines won't be limited. + + + + + + + an expander row + + + + the number of lines at the end of which the subtitle label will be ellipsized + + + + + + Sets the number of lines at the end of which the title label will be +ellipsized. + +If the value is 0, the number of lines won't be limited. + + + + + + + an expander row + + + + the number of lines at the end of which the title label will be ellipsized + + + + + + Whether expansion is enabled. + + + + Whether the row is expanded. + + + + The icon name for this row. + Use [method@ExpanderRow.add_prefix] to add an icon. + + + + Whether the switch enabling the expansion is visible. + + + + The subtitle for this row. + +The subtitle is interpreted as Pango markup unless +[property@PreferencesRow:use-markup] is set to `FALSE`. + + + + The number of lines at the end of which the subtitle label will be +ellipsized. + +If the value is 0, the number of lines won't be limited. + + + + The number of lines at the end of which the title label will be ellipsized. + +If the value is 0, the number of lines won't be limited. + + + + + + + + + + The parent class + + + + + + + + + + An adaptive container acting like a box or an overlay. + +<picture> + <source srcset="flap-wide-dark.png" media="(prefers-color-scheme: dark)"> + <img src="flap-wide.png" alt="flap-wide"> +</picture> +<picture> + <source srcset="flap-narrow-dark.png" media="(prefers-color-scheme: dark)"> + <img src="flap-narrow.png" alt="flap-narrow"> +</picture> + +The `AdwFlap` widget can display its children like a [class@Gtk.Box] does or +like a [class@Gtk.Overlay] does, according to the +[property@Flap:fold-policy] value. + +`AdwFlap` has at most three children: [property@Flap:content], +[property@Flap:flap] and [property@Flap:separator]. Content is the primary +child, flap is displayed next to it when unfolded, or overlays it when +folded. Flap can be shown or hidden by changing the +[property@Flap:reveal-flap] value, as well as via swipe gestures if +[property@Flap:swipe-to-open] and/or [property@Flap:swipe-to-close] are set +to `TRUE`. + +Optionally, a separator can be provided, which would be displayed between +the content and the flap when there's no shadow to separate them, depending +on the transition type. + +[property@Flap:flap] is transparent by default; add the +[`.background`](style-classes.html#background) style class to it if this is +unwanted. + +If [property@Flap:modal] is set to `TRUE`, content becomes completely +inaccessible when the flap is revealed while folded. + +The position of the flap and separator children relative to the content is +determined by orientation, as well as the [property@Flap:flap-position] +value. + +Folding the flap will automatically hide the flap widget, and unfolding it +will automatically reveal it. If this behavior is not desired, the +[property@Flap:locked] property can be used to override it. + +Common use cases include sidebars, header bars that need to be able to +overlap the window content (for example, in fullscreen mode) and bottom +sheets. + +## AdwFlap as GtkBuildable + +The `AdwFlap` implementation of the [iface@Gtk.Buildable] interface supports +setting the flap child by specifying “flap” as the “type” attribute of a +`<child>` element, and separator by specifying “separator”. Specifying +“content” child type or omitting it results in setting the content child. + +## CSS nodes + +`AdwFlap` has a single CSS node with name `flap`. The node will get the style +classes `.folded` when it is folded, and `.unfolded` when it's not. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + + Creates a new `AdwFlap`. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the newly created `AdwFlap` + + + + + Gets the content widget for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the content widget for @self + + + + + a flap + + + + + + Gets the flap widget for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the flap widget for @self + + + + + a flap + + + + + + Gets the flap position for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the flap position for @self + + + + + a flap + + + + + + Gets the fold transition animation duration for @self, in milliseconds. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the fold transition duration + + + + + a flap + + + + + + Gets the fold policy for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the fold policy for @self + + + + + a flap + + + + + + Gets the fold threshold policy for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the fold threshold policy + + + + + a flap + + + + + + Gets whether @self is currently folded. + +See [property@Flap:fold-policy]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + `TRUE` if @self is currently folded + + + + + a flap + + + + + + Gets whether @self is locked. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + `TRUE` if @self is locked + + + + + a flap + + + + + + Gets whether @self is modal. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + `TRUE` if @self is modal + + + + + a flap + + + + + + Gets whether the flap widget is revealed for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + `TRUE` if the flap widget is revealed + + + + + a flap + + + + + + Gets the reveal animation spring parameters for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the reveal animation parameters + + + + + a flap + + + + + + Gets the current reveal progress for @self. + +0 means fully hidden, 1 means fully revealed. + +See [property@Flap:reveal-flap]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the current reveal progress for @self + + + + + a flap + + + + + + Gets the separator widget for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the separator widget for @self + + + + + a flap + + + + + + Gets whether @self can be closed with a swipe gesture. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + `TRUE` if @self can be closed with a swipe gesture + + + + + a flap + + + + + + Gets whether @self can be opened with a swipe gesture. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + `TRUE` if @self can be opened with a swipe gesture + + + + + a flap + + + + + + Gets the type of animation used for reveal and fold transitions in @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + the current transition type of @self + + + + + a flap + + + + + + Sets the content widget for @self. + +It's always displayed when unfolded, and partially visible when folded. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the content widget + + + + + + Sets the flap widget for @self. + +It's only visible when [property@Flap:reveal-progress] is greater than 0. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the flap widget + + + + + + Sets the flap position for @self. + +If it's set to `GTK_PACK_START`, the flap is displayed before the content, +if `GTK_PACK_END`, it's displayed after the content. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the new value + + + + + + Sets the fold transition animation duration for @self, in milliseconds. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the new duration, in milliseconds + + + + + + Sets the fold policy for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the fold policy + + + + + + Sets the fold threshold policy for @self. + +If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when the +children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it +will fold as soon as children don't get their natural size. + +This can be useful if you have a long ellipsizing label and want to let it +ellipsize instead of immediately folding. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the policy to use + + + + + + Sets whether @self 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`, +[property@Flap:reveal-flap] value never changes on its own. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the new value + + + + + + Sets whether @self is modal. + +If `TRUE`, clicking the content widget while flap is revealed, as well as +pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks are +passed through to the content widget. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + whether @self is modal + + + + + + Sets whether the flap widget is revealed for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + whether to reveal the flap widget + + + + + + Sets the reveal animation spring parameters for @self. + +The default value is equivalent to: + +```c +adw_spring_params_new (1, 0.5, 500) +``` + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the new parameters + + + + + + Sets the separator widget for @self. + +It's displayed between content and flap when there's no shadow to display. +When exactly it's visible depends on the [property@Flap:transition-type] +value. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the separator widget + + + + + + Sets whether @self can be closed with a swipe gesture. + +The area that can be swiped depends on the [property@Flap:transition-type] +value. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + whether @self can be closed with a swipe gesture + + + + + + Sets whether @self can be opened with a swipe gesture. + +The area that can be swiped depends on the [property@Flap:transition-type] +value. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + whether @self can be opened with a swipe gesture + + + + + + Sets the type of animation used for reveal and fold transitions in @self. + +[property@Flap:flap] is transparent by default, which means the content will +be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; add the +[`.background`](style-classes.html#background) style class to it if this is +unwanted. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + a flap + + + + the new transition type + + + + + + The content widget. + +It's always displayed when unfolded, and partially visible when folded. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The flap widget. + +It's only visible when [property@Flap:reveal-progress] is greater than 0. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The flap position. + +If it's set to `GTK_PACK_START`, the flap is displayed before the content, +if `GTK_PACK_END`, it's displayed after the content. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The fold transition animation duration, in milliseconds. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The fold policy for the flap. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + Determines when the flap will fold. + +If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when +the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, +it will fold as soon as children don't get their natural size. + +This can be useful if you have a long ellipsizing label and want to let it +ellipsize instead of immediately folding. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + Whether the flap is currently folded. + +See [property@Flap:fold-policy]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + 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`, +[property@Flap:reveal-flap] value never changes on its own. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + Whether the flap is modal. + +If `TRUE`, clicking the content widget while flap is revealed, as well as +pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks +are passed through to the content widget. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + Whether the flap widget is revealed. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The reveal animation spring parameters. + +The default value is equivalent to: + +```c +adw_spring_params_new (1, 0.5, 500) +``` + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The current reveal transition progress. + +0 means fully hidden, 1 means fully revealed. + +See [property@Flap:reveal-flap]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + The separator widget. + +It's displayed between content and flap when there's no shadow to display. +When exactly it's visible depends on the [property@Flap:transition-type] +value. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + Whether the flap can be closed with a swipe gesture. + +The area that can be swiped depends on the [property@Flap:transition-type] +value. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + Whether the flap can be opened with a swipe gesture. + +The area that can be swiped depends on the [property@Flap:transition-type] +value. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + the type of animation used for reveal and fold transitions. + +[property@Flap:flap] is transparent by default, which means the content +will be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; +add the [`.background`](style-classes.html#background) style class to it if +this is unwanted. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + + + + + + + + + + Describes the possible folding behavior of a [class@Flap] widget. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + Disable folding, the flap cannot reach narrow + sizes. + + + Keep the flap always folded. + + + Fold and unfold the flap based on available + space. + + + + Describes transitions types of a [class@Flap] widget. + +It determines the type of animation when transitioning between children in a +[class@Flap] widget, as well as which areas can be swiped via +[property@Flap:swipe-to-open] and [property@Flap:swipe-to-close]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + + The flap slides over the content, which is + dimmed. When folded, only the flap can be swiped. + + + The content slides over the flap. Only the + content can be swiped. + + + The flap slides offscreen when hidden, + neither the flap nor content overlap each other. Both widgets can be + swiped. + + + + Determines when [class@Flap] and [class@Leaflet] will fold. + Stop using `AdwLeaflet` and `AdwFlap` + + Folding is based on the minimum size + + + Folding is based on the natural size + + + + A title bar widget. + +<picture> + <source srcset="header-bar-dark.png" media="(prefers-color-scheme: dark)"> + <img src="header-bar.png" alt="header-bar"> +</picture> + +`AdwHeaderBar` is similar to [class@Gtk.HeaderBar], but provides additional +features compared to it. Refer to `GtkHeaderBar` for details. It is typically +used as a top bar within [class@ToolbarView]. + +## Dialog Integration + +When placed inside an [class@Dialog], `AdwHeaderBar` will display the dialog +title instead of window title. It will also adjust the decoration layout to +ensure it always has a close button and nothing else. Set +[property@HeaderBar:show-start-title-buttons] and +[property@HeaderBar:show-end-title-buttons] to `FALSE` to remove it if it's +unwanted. + +## Navigation View Integration + +When placed inside an [class@NavigationPage], `AdwHeaderBar` will display the +page title instead of window title. + +When used together with [class@NavigationView] or [class@NavigationSplitView], +it will also display a back button that can be used to go back to the previous +page. The button also has a context menu, allowing to pop multiple pages at +once, potentially across multiple navigation views. + +Set [property@HeaderBar:show-back-button] to `FALSE` to disable this behavior +in rare scenarios where it's unwanted. + +## Split View Integration + +When placed inside [class@NavigationSplitView] or [class@OverlaySplitView], +`AdwHeaderBar` will automatically hide the title buttons other than at the +edges of the window. + +## Bottom Sheet Integration + +When played inside [class@BottomSheet], `AdwHeaderBar` will not show the title +unless [property@BottomSheet:show-drag-handle] is set to `FALSE`, regardless +of [property@HeaderBar:show-title]. This only applies to the default title, +titles set with [property@HeaderBar:title-widget] will still be shown. + +## Centering Policy + +[property@HeaderBar:centering-policy] allows to enforce strict centering of +the title widget. This can be useful for entries inside [class@Clamp]. + +## Title Buttons + +Unlike `GtkHeaderBar`, `AdwHeaderBar` allows to toggle title button +visibility for each side individually, using the +[property@HeaderBar:show-start-title-buttons] and +[property@HeaderBar:show-end-title-buttons] properties. + +## CSS nodes + +``` +headerbar +╰── windowhandle + ╰── box + ├── widget + │ ╰── box.start + │ ├── windowcontrols.start + │ ├── widget + │ │ ╰── [button.back] + │ ╰── [other children] + ├── widget + │ ╰── [Title Widget] + ╰── widget + ╰── box.end + ├── [other children] + ╰── windowcontrols.end +``` + +`AdwHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle` +subnode, which contains a `box` subnode, which contains three `widget` +subnodes at the start, center and end of the header bar. The start and end +subnodes contain a `box` subnode with the `.start` and `.end` style classes +respectively, and the center node contains a node that represents the title. + +Each of the boxes contains a `windowcontrols` subnode, see +[class@Gtk.WindowControls] for details, as well as other children. + +When [property@HeaderBar:show-back-button] is `TRUE`, the start box also +contains a node with the name `widget` that contains a node with the name +`button` and `.back` style class. + +## Accessibility + +`AdwHeaderBar` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + + + + + Creates a new `AdwHeaderBar`. + + + the newly created `AdwHeaderBar`. + + + + + Gets the policy for aligning the center widget. + + + the centering policy + + + + + a header bar + + + + + + Gets the decoration layout for @self. + + + the decoration layout + + + + + a header bar + + + + + + Gets whether @self can show the back button. + + + whether to show the back button + + + + + a header bar + + + + + + Gets whether to show title buttons at the end of @self. + + + `TRUE` if title buttons at the end are shown + + + + + a header bar + + + + + + Gets whether to show title buttons at the start of @self. + + + `TRUE` if title buttons at the start are shown + + + + + a header bar + + + + + + Gets whether the title widget should be shown. + + + whether the title widget should be shown. + + + + + a header bar + + + + + Quartic tweening, inverse of `ADW_EASE_IN_QUART`. - - + filename="src/adw-header-bar.c" + line="1094">Gets the title widget widget of @self. + + + the title widget + + + + + a header bar + + + + + Quartic tweening, combining `ADW_EASE_IN_QUART` and - `ADW_EASE_OUT_QUART`. - - + filename="src/adw-header-bar.c" + line="1035">Adds @child to @self, packed with reference to the end of @self. + + + + + + + a header bar + + + + the widget to be added to @self + + + + + + Adds @child to @self, packed with reference to the start of the @self. + + + + + + + a header bar + + + + the widget to be added to @self + + + + + + Removes a child from @self. + +The child must have been added with [method@HeaderBar.pack_start], +[method@HeaderBar.pack_end] or [property@HeaderBar:title-widget]. + + + + + + + a header bar + + + + the child to remove + + + + + + Sets the policy for aligning the center widget. + + + + + + + a header bar + + + + the centering policy + + + + + + Sets the decoration layout for @self. + +If this property is not set, the +[property@Gtk.Settings:gtk-decoration-layout] setting is used. + +The format of the string is button names, separated by commas. A colon +separates the buttons that should appear at the start from those at the end. +Recognized button names are minimize, maximize, close and icon (the window +icon). + +For example, “icon:minimize,maximize,close” specifies an icon at the start, +and minimize, maximize and close buttons at the end. + + + + + + + a header bar + + + + a decoration layout + + + + + + Sets whether @self can show the back button. + +The back button will never be shown unless the header bar is placed inside an +[class@NavigationView]. Usually, there is no reason to set it to `FALSE`. + + + + + + + a header bar + + + + whether to show the back button + + + + + + Sets whether to show title buttons at the end of @self. + +See [property@HeaderBar:show-start-title-buttons] for the other side. + +Which buttons are actually shown and where is determined by the +[property@HeaderBar:decoration-layout] property, and by the state of the +window (e.g. a close button will not be shown if the window can't be closed). + + + + + + + a header bar + + + + `TRUE` to show standard title buttons + + + + + + Sets whether to show title buttons at the start of @self. + +See [property@HeaderBar:show-end-title-buttons] for the other side. + +Which buttons are actually shown and where is determined by the +[property@HeaderBar:decoration-layout] property, and by the state of the +window (e.g. a close button will not be shown if the window can't be closed). + + + + + + + a header bar + + + + `TRUE` to show standard title buttons + + + + + + Sets whether the title widget should be shown. + + + + + + + a header bar + + + + whether the title widget is visible + + + + + + Sets the title widget for @self. + +When set to `NULL`, the header bar will display the title of the window it +is contained in. + +To use a different title, use [class@WindowTitle]: + +```xml +<object class="AdwHeaderBar"> + <property name="title-widget"> + <object class="AdwWindowTitle"> + <property name="title" translatable="yes">Title</property> + </object> + </property> +</object> +``` + + + + + + + a header bar + + + + a widget to use for a title + + + + + + The policy for aligning the center widget. + + + + The decoration layout for buttons. + +If this property is not set, the +[property@Gtk.Settings:gtk-decoration-layout] setting is used. + +The format of the string is button names, separated by commas. A colon +separates the buttons that should appear at the start from those at the +end. Recognized button names are minimize, maximize, close and icon (the +window icon). + +For example, “icon:minimize,maximize,close” specifies an icon at the start, +and minimize, maximize and close buttons at the end. + + + + Whether the header bar can show the back button. + +The back button will never be shown unless the header bar is placed inside an +[class@NavigationView]. Usually, there is no reason to set this to `FALSE`. + + + + Whether to show title buttons at the end of the header bar. + +See [property@HeaderBar:show-start-title-buttons] for the other side. + +Which buttons are actually shown and where is determined by the +[property@HeaderBar:decoration-layout] property, and by the state of the +window (e.g. a close button will not be shown if the window can't be +closed). + + + + Whether to show title buttons at the start of the header bar. + +See [property@HeaderBar:show-end-title-buttons] for the other side. + +Which buttons are actually shown and where is determined by the +[property@HeaderBar:decoration-layout] property, and by the state of the +window (e.g. a close button will not be shown if the window can't be +closed). + + + + Whether the title widget should be shown. + + + + The title widget to display. + +When set to `NULL`, the header bar will display the title of the window it +is contained in. + +To use a different title, use [class@WindowTitle]: + +```xml +<object class="AdwHeaderBar"> + <property name="title-widget"> + <object class="AdwWindowTitle"> + <property name="title" translatable="yes">Title</property> + </object> + </property> +</object> +``` + + + + + + + + + + + A view switcher that uses a toggle group. + +<picture> + <source srcset="inline-view-switcher-dark.png" media="(prefers-color-scheme: dark)"> + <img src="inline-view-switcher.png" alt="inline-view-switcher"> +</picture> + +A view switcher showing pages of an [class@ViewStack] within an +[class@ToggleGroup], similar to [class@ViewSwitcher]. + +The toggles can display either an icon, a label or both. Use the +[property@InlineViewSwitcher:display-mode] to control this. + +<picture> + <source srcset="inline-view-switcher-display-modes-dark.png" media="(prefers-color-scheme: dark)"> + <img src="inline-view-switcher-display-modes.png" alt="inline-view-switcher-display-modes"> +</picture> + +## CSS nodes + +`AdwInlineViewSwitcher` has a single CSS node with the name +`inline-view-switcher`. + +## Style classes + +Like `AdwToggleGroup`, it can accept the [`.flat`](style-classes.html#flat_1) +and [`.round`](style-classes.html#round) style classes. + +<picture> + <source srcset="inline-view-switcher-style-classes-dark.png" media="(prefers-color-scheme: dark)"> + <img src="inline-view-switcher-style-classes.png" alt="inline-view-switcher-style-classes"> +</picture> + +## Accessibility + +The internal toggle group uses the `GTK_ACCESSIBLE_ROLE_TAB_LIST` role. Its +toggles use the `GTK_ACCESSIBLE_ROLE_TAB` role. + + + + + + + Creates a new `AdwInlineViewSwitcher`. + + + the newly created `AdwInlineViewSwitcher` + + + + + Gets whether the toggles can be smaller than the natural size of their +contents. + + + whether the toggles can shrink + + + + + an inline stack switcher + + + + + + Gets the display mode of @self. + + + the display mode + + + + + an inline stack switcher + + + + + Quintic tweening. - - + filename="src/adw-inline-view-switcher.c" + line="869">Gets whether all toggles within @self take the same size. + + + whether all toggles take the same size + + + + + an inline stack switcher + + + + + Quintic tweening, inverse of `ADW_EASE_IN_QUINT`. - - + filename="src/adw-inline-view-switcher.c" + line="743">Gets the stack @self controls. + + + The stack of @self + + + + + an inline stack switcher + + + + + Quintic tweening, combining `ADW_EASE_IN_QUINT` and - `ADW_EASE_OUT_QUINT`. - - + filename="src/adw-inline-view-switcher.c" + line="932">Sets whether the toggles can be smaller than the natural size of their +contents. + +If @can_shrink is `TRUE`, the toggle labels will ellipsize. + +See [property@ToggleGroup:can-shrink]. + + + + + + + an inline stack switcher + + + + whether the toggles can shrink + + + + + Sine wave tweening. - - + filename="src/adw-inline-view-switcher.c" + line="804">Sets the display mode of @self. + +Determines what the toggles display: a label, an icon or both. + +<picture> + <source srcset="inline-view-switcher-display-modes-dark.png" media="(prefers-color-scheme: dark)"> + <img src="inline-view-switcher-display-modes.png" alt="inline-view-switcher-display-modes"> +</picture> + + + + + + + an inline stack switcher + + + + the display mode + + + + + Sine wave tweening, inverse of `ADW_EASE_IN_SINE`. - - + filename="src/adw-inline-view-switcher.c" + line="887">Sets whether all toggles within @self take the same size. + + + + + + + an inline stack switcher + + + + whether all toggles should take the same size + + + + + Sine wave tweening, combining `ADW_EASE_IN_SINE` and - `ADW_EASE_OUT_SINE`. - - + filename="src/adw-inline-view-switcher.c" + line="761">Sets the stack to control. + + + + + + + an inline stack switcher + + + + a stack + + + + + Exponential tweening. - - + filename="src/adw-inline-view-switcher.c" + line="682">Whether the toggles can be smaller than the natural size of their contents. + +If set to `TRUE`, the toggle labels will ellipsize. + +See [property@ToggleGroup:can-shrink]. + + + Exponential tweening, inverse of `ADW_EASE_IN_EXPO`. - - + filename="src/adw-inline-view-switcher.c" + line="650">The display mode. + +Determines what the toggles display: a label, an icon or both. + +<picture> + <source srcset="inline-view-switcher-display-modes-dark.png" media="(prefers-color-scheme: dark)"> + <img src="inline-view-switcher-display-modes.png" alt="inline-view-switcher-display-modes"> +</picture> + + + Exponential tweening, combining `ADW_EASE_IN_EXPO` and - `ADW_EASE_OUT_EXPO`. - - + filename="src/adw-inline-view-switcher.c" + line="670">Whether all toggles take the same size. + + + Circular tweening. - - + filename="src/adw-inline-view-switcher.c" + line="638">The stack the view switcher controls. + + + + + + + + + + + Describes what [class@InlineViewSwitcher] toggles display. + +<picture> + <source srcset="inline-view-switcher-display-modes-dark.png" media="(prefers-color-scheme: dark)"> + <img src="inline-view-switcher-display-modes.png" alt="inline-view-switcher-display-modes"> +</picture> + Circular tweening, inverse of `ADW_EASE_IN_CIRC`. + filename="src/adw-inline-view-switcher.c" + line="19">Toggles only display labels. - + Circular tweening, combining `ADW_EASE_IN_CIRC` and - `ADW_EASE_OUT_CIRC`. + filename="src/adw-inline-view-switcher.c" + line="20">Toggles only display icons. - + Elastic tweening, with offshoot on start. + filename="src/adw-inline-view-switcher.c" + line="21">Toggles display both icons and labels. - + + + Describes line justify behaviors in a [class@WrapLayout] or [class@WrapBox]. + +See [property@WrapLayout:justify] and [property@WrapBox:justify]. + Elastic tweening, with offshoot on end, inverse of - `ADW_EASE_IN_ELASTIC`. + filename="src/adw-wrap-layout.c" + line="76">Don't justify children within a line. - + Elastic tweening, with offshoot on both ends, - combining `ADW_EASE_IN_ELASTIC` and `ADW_EASE_OUT_ELASTIC`. + filename="src/adw-wrap-layout.c" + line="77">Stretch each child within the line, keeping consistent + spacing, so that the line fills the entire length. - - Overshooting cubic tweening, with backtracking on start. + + Increase spacing between children, moving the children + so that the first and last child are aligned with the beginning and end + of the line. If the line only contains a single widget, it will be + stretched regardless. - + + + An individual layout in [class@MultiLayoutView]. + + + Overshooting cubic tweening, with backtracking on end, - inverse of `ADW_EASE_IN_BACK`. - - + filename="src/adw-layout.c" + line="185">Creates a new `AdwLayout` that contains @content. + + + a new `AdwLayout` + + + + + the content widget to use + + + + + Overshooting cubic tweening, with backtracking on both - ends, combining `ADW_EASE_IN_BACK` and `ADW_EASE_OUT_BACK`. - - + filename="src/adw-layout.c" + line="203">Gets the content widget. + + + The content + + + + + a layout + + + + + Exponentially decaying parabolic (bounce) tweening, - on start. - - + filename="src/adw-layout.c" + line="221">Gets the name of the layout. + + + the name of the layout + + + + + a layout + + + + + Exponentially decaying parabolic (bounce) tweening, - with bounce on end, inverse of `ADW_EASE_IN_BOUNCE`. - - + filename="src/adw-layout.c" + line="239">Sets the name of the layout. + + + + + + + a layout + + + + the layout name + + + + + Exponentially decaying parabolic (bounce) tweening, - with bounce on both ends, combining `ADW_EASE_IN_BOUNCE` and - `ADW_EASE_OUT_BOUNCE`. - - + filename="src/adw-layout.c" + line="133">The content widget. + + + Computes easing with @easing for @value. + filename="src/adw-layout.c" + line="145">The name of the layout. + + + + + + + + + + + A child slot within [class@Layout]. -@value should generally be in the [0, 1] range. - +While it contains a layout child, the [property@Gtk.Widget:visible] property +of the slot is updated to match that of the layout child. + +See [class@MultiLayoutView]. + + + + + + Creates a new `AdwLayoutSlot` with its ID set to @id. + the easing for @value - + filename="src/adw-layout-slot.c" + line="149">a new `AdwLayoutSlot` + - + an easing value - + filename="src/adw-layout-slot.c" + line="145">the slot ID + - + + + + Gets the slot id of @self. + + + the slot ID + + + + a value to ease - - + filename="src/adw-layout-slot.c" + line="163">a layout slot + + - - - + + + The slot ID. + +See [method@MultiLayoutView.set_child]. + + + + + + + + + + A [class@Gtk.ListBoxRow] with an embedded text entry. + filename="src/adw-leaflet.c" + line="21">An adaptive container acting like a box or a stack. <picture> - <source srcset="entry-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="entry-row.png" alt="entry-row"> + <source srcset="leaflet-wide-dark.png" media="(prefers-color-scheme: dark)"> + <img src="leaflet-wide.png" alt="leaflet-wide"> +</picture> +<picture> + <source srcset="leaflet-narrow-dark.png" media="(prefers-color-scheme: dark)"> + <img src="leaflet-narrow.png" alt="leaflet-narrow"> </picture> -`AdwEntryRow` has a title that doubles as placeholder text. It shows an icon -indicating that it's editable and can receive additional widgets before or -after the editable part. - -If [property@EntryRow:show-apply-button] is set to `TRUE`, `AdwEntryRow` can -show an apply button when editing its contents. This can be useful if -changing its contents can result in an expensive operation, such as network -activity. - -`AdwEntryRow` provides only minimal API and should be used with the -[iface@Gtk.Editable] API. - -See also [class@PasswordEntryRow]. - -## AdwEntryRow as GtkBuildable - -The `AdwEntryRow` implementation of the [iface@Gtk.Buildable] interface -supports adding a child at its end by specifying “suffix” or omitting the -“type” attribute of a <child> element. +The `AdwLeaflet` widget can display its children like a [class@Gtk.Box] does +or like a [class@Gtk.Stack] does, adapting to size changes by switching +between the two modes. -It also supports adding a child as a prefix widget by specifying “prefix” as -the “type” attribute of a <child> element. +When there is enough space the children are displayed side by side, otherwise +only one is displayed and the leaflet is said to be “folded”. +The threshold is dictated by the preferred minimum sizes of the children. +When a leaflet is folded, the children can be navigated using swipe gestures. -## CSS nodes +The “over” and “under” transition types stack the children one on top of the +other, while the “slide” transition puts the children side by side. While +navigating to a child on the side or below can be performed by swiping the +current child away, navigating to an upper child requires dragging it from +the edge where it resides. This doesn't affect non-dragging swipes. -`AdwEntryRow` has a single CSS node with name `row` and the `.entry` style -class. - +## CSS nodes + +`AdwLeaflet` has a single CSS node with name `leaflet`. The node will get the +style classes `.folded` when it is folded, `.unfolded` when it's not, or none +if it hasn't computed its fold yet. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + - - - + + Creates a new `AdwEntryRow`. - + filename="src/adw-leaflet.c" + line="2803">Creates a new `AdwLeaflet`. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + the newly created `AdwEntryRow` + filename="src/adw-leaflet.c" + line="2808">the new created `AdwLeaflet` - + Adds a prefix widget to @self. - + filename="src/adw-leaflet.c" + line="2818">Adds a child to @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - + the [class@LeafletPage] for @child + an entry row - + filename="src/adw-leaflet.c" + line="2820">a leaflet + - + a widget + filename="src/adw-leaflet.c" + line="2821">the widget to add - + Adds a suffix widget to @self. - - - + filename="src/adw-leaflet.c" + line="3593">Finds the previous or next navigatable child. + +This will be the same child [method@Leaflet.navigate] or swipe gestures will +navigate to. + +If there's no child to navigate to, `NULL` will be returned instead. + +See [property@LeafletPage:navigatable]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the previous or next child + an entry row - + filename="src/adw-leaflet.c" + line="3595">a leaflet + - + a widget - + filename="src/adw-leaflet.c" + line="3596">the direction + - - + Gets whether activating the embedded entry can activate the default widget. - + filename="src/adw-leaflet.c" + line="3473">Gets whether gestures and shortcuts for navigating backward are enabled. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + whether to activate the default widget + filename="src/adw-leaflet.c" + line="3479">Whether gestures and shortcuts are enabled. an entry row - + filename="src/adw-leaflet.c" + line="3475">a leaflet + - - + Gets Pango attributes applied to the text of the embedded entry. - - + filename="src/adw-leaflet.c" + line="3533">Gets whether gestures and shortcuts for navigating forward are enabled. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + the list of attributes - + filename="src/adw-leaflet.c" + line="3539">Whether gestures and shortcuts are enabled. + an entry row - + filename="src/adw-leaflet.c" + line="3535">a leaflet + - - + Gets whether to suggest emoji replacements on @self. - + filename="src/adw-leaflet.c" + line="3059">Gets whether @self can unfold. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + whether or not emoji completion is enabled + filename="src/adw-leaflet.c" + line="3065">whether @self can unfold an entry row - + filename="src/adw-leaflet.c" + line="3061">a leaflet + - - + Gets the additional input hints of @self. - + filename="src/adw-leaflet.c" + line="3661">Finds the child of @self with @name. + +Returns `NULL` if there is no child with this name. + +See [property@LeafletPage:name]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the requested child of @self + + + + + a leaflet + + + + the name of the child to find + + + + + + Gets the child transition spring parameters for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the child transition parameters + + + + + a leaflet + + + + + + Gets whether a child transition is currently running for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + The input hints - + filename="src/adw-leaflet.c" + line="3461">whether a transition is currently running + an entry row - + filename="src/adw-leaflet.c" + line="3457">a leaflet + - - + Gets the input purpose of @self. - + filename="src/adw-leaflet.c" + line="3099">Gets the fold threshold policy for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + the input purpose - + filename="src/adw-leaflet.c" + line="3105">the fold threshold policy + an entry row - + filename="src/adw-leaflet.c" + line="3101">a leaflet + - - + Gets whether @self can show the apply button. - + filename="src/adw-leaflet.c" + line="3077">Gets whether @self is folded. + +The leaflet will be folded if the size allocated to it is smaller than the +sum of the minimum or natural sizes of the children (see +[property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + whether to show the apply button + filename="src/adw-leaflet.c" + line="3087">whether @self is folded. an entry row - + filename="src/adw-leaflet.c" + line="3079">a leaflet + - + Causes @self to have keyboard focus without selecting the text. - -See [method@Gtk.Text.grab_focus_without_selecting] for more information. - + filename="src/adw-leaflet.c" + line="3151">Gets whether @self is homogeneous. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + whether the focus is now inside @self + filename="src/adw-leaflet.c" + line="3157">whether @self is homogeneous an entry row - + filename="src/adw-leaflet.c" + line="3153">a leaflet + - + Removes a child from @self. - + filename="src/adw-leaflet.c" + line="3361">Gets the mode transition animation duration for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - + the mode transition duration, in milliseconds. + an entry row - + filename="src/adw-leaflet.c" + line="3363">a leaflet + - + + + + Returns the [class@LeafletPage] object for @child. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the page object for @child + + + + the child to be removed + filename="src/adw-leaflet.c" + line="3013">a leaflet + + + + a child of @self - - + Sets whether activating the embedded entry can activate the default widget. - + filename="src/adw-leaflet.c" + line="3690">Returns a [iface@Gio.ListModel] that contains the pages of the leaflet. + +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the visible +page. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + a `GtkSelectionModel` for the leaflet's children + + + + + a leaflet + + + + + + Gets the type of animation used for transitions between modes and children. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - + the current transition type of @self + an entry row - + filename="src/adw-leaflet.c" + line="3305">a leaflet + - + + + + Gets the widget currently visible when the leaflet is folded. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the visible child + + + + whether to activate the default widget - - + filename="src/adw-leaflet.c" + line="3201">a leaflet + + - - + Sets Pango attributes to apply to the text of the embedded entry. + filename="src/adw-leaflet.c" + line="3253">Gets the name of the currently visible child widget. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the name of the visible child + + + + + a leaflet + + + + + + Inserts @child in the position after @sibling in the list of children. -The [struct@Pango.Attribute]'s `start_index` and `end_index` must refer to -the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. - +If @sibling is `NULL`, inserts @child at the first position. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - + the [class@LeafletPage] for @child + an entry row - + filename="src/adw-leaflet.c" + line="2871">a leaflet + - + the widget to insert + + + a list of attributes - + filename="src/adw-leaflet.c" + line="2873">the sibling after which to insert @child + - - + Sets whether to suggest emoji replacements on @self. + filename="src/adw-leaflet.c" + line="3624">Navigates to the previous or next child. -Emoji replacement is done with :-delimited names, like `:heart:`. - +The child must have the [property@LeafletPage:navigatable] property set to +`TRUE`, otherwise it will be skipped. + +This will be the same child as returned by +[method@Leaflet.get_adjacent_child] or navigated to via swipe gestures. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - + whether the visible child was changed + + + + + a leaflet + + + + the direction + + + + + + Inserts @child at the first position in @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + the [class@LeafletPage] for @child + an entry row - + filename="src/adw-leaflet.c" + line="2849">a leaflet + - + Whether emoji completion should be enabled or not - + filename="src/adw-leaflet.c" + line="2850">the widget to prepend + - - + Set additional input hints for @self. - -Input hints allow input methods to fine-tune their behavior. - -See also: [property@AdwEntryRow:input-purpose] - + filename="src/adw-leaflet.c" + line="2978">Removes a child widget from @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an entry row - + filename="src/adw-leaflet.c" + line="2980">a leaflet + - + the hints - + filename="src/adw-leaflet.c" + line="2981">the child to remove + - - + Sets the input purpose of @self. + filename="src/adw-leaflet.c" + line="2908">Moves @child to the position after @sibling in the list of children. -The input purpose can be used by input methods to adjust their behavior. - +If @sibling is `NULL`, moves @child to the first position. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an entry row - + filename="src/adw-leaflet.c" + line="2910">a leaflet + - + the purpose - + filename="src/adw-leaflet.c" + line="2911">the widget to move, must be a child of @self + + + + the sibling to move @child after + - - + Sets whether @self can show the apply button. + filename="src/adw-leaflet.c" + line="3491">Sets whether gestures and shortcuts for navigating backward are enabled. -When set to `TRUE`, typing text in the entry will reveal an apply button. -Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and -emit the [signal@EntryRow::apply] signal. +The supported gestures are: -This is useful if changing the entry contents can trigger an expensive -operation, e.g. network activity, to avoid triggering it after typing every -character. - +- One-finger swipe on touchscreens +- Horizontal scrolling on touchpads (usually two-finger swipe) +- Back/forward mouse buttons + +The keyboard back/forward keys are also supported, as well as the +<kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or +<kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation. + +If the orientation is horizontal, for right-to-left locales, gestures and +shortcuts are reversed. + +Only children that have [property@LeafletPage:navigatable] set to `TRUE` can +be navigated to. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an entry row - + filename="src/adw-leaflet.c" + line="3493">a leaflet + - + whether to show the apply button + filename="src/adw-leaflet.c" + line="3494">the new value - - - - Whether activating the embedded entry can activate the default widget. - - - - - - A list of Pango attributes to apply to the text of the embedded entry. - -The [struct@Pango.Attribute]'s `start_index` and `end_index` must refer to -the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. - - - - - - Whether to suggest emoji replacements on the entry row. - -Emoji replacement is done with :-delimited names, like `:heart:`. - - - - - + Additional input hints for the entry row. - -Input hints allow input methods to fine-tune their behavior. + filename="src/adw-leaflet.c" + line="3551">Sets whether gestures and shortcuts for navigating forward are enabled. -See also: [property@Adw.EntryRow:input-purpose] - - - - - - The input purpose of the entry row. +The supported gestures are: -The input purpose can be used by input methods to adjust their behavior. - - - - - - Whether to show the apply button. +- One-finger swipe on touchscreens +- Horizontal scrolling on touchpads (usually two-finger swipe) +- Back/forward mouse buttons -When set to `TRUE`, typing text in the entry will reveal an apply button. -Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and -emit the [signal@EntryRow::apply] signal. +The keyboard back/forward keys are also supported, as well as the +<kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or +<kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation. -This is useful if changing the entry contents can trigger an expensive -operation, e.g. network activity, to avoid triggering it after typing every -character. - - - - - - - Emitted when the apply button is pressed. +If the orientation is horizontal, for right-to-left locales, gestures and +shortcuts are reversed. -See [property@EntryRow:show-apply-button]. - - - - - - Emitted when the embedded entry is activated. +Only children that have [property@LeafletPage:navigatable] set to `TRUE` can +be navigated to. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - - - - - - The parent class - - - - - `AdwEnumListItem` is the type of items in a [class@EnumListModel]. - - - - Gets the enum value name. - - - the enum value name - - - - - - - - - - - Gets the enum value nick. - - - the enum value nick - - - - - - - - - - - Gets the enum value. - - - the enum value - - - - - - - - - The enum value name. - - - - - The enum value nick. - - - - - The enum value. - - - - - - - - - - - A [iface@Gio.ListModel] representing values of a given enum. - -`AdwEnumListModel` contains objects of type [class@EnumListItem]. - - - - Creates a new `AdwEnumListModel` for @enum_type. - - - the newly created `AdwEnumListModel` - - - - the type of the enum to construct the model from - - - - - - Finds the position of a given enum value in @self. - -If the value is not found, `GTK_INVALID_LIST_POSITION` is returned. - - - - - - - + filename="src/adw-leaflet.c" + line="3553">a leaflet + - + an enum value - + filename="src/adw-leaflet.c" + line="3554">the new value + - - + Gets the type of the enum represented by @self. - + filename="src/adw-leaflet.c" + line="3032">Sets whether @self can unfold. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - the enum type - + - + a leaflet + + + whether @self can unfold + + - - - The type of the enum represented by the model. - - - - - - - - - - - A [class@Gtk.ListBoxRow] used to reveal widgets. - -<picture> - <source srcset="expander-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="expander-row.png" alt="expander-row"> -</picture> - -The `AdwExpanderRow` widget allows the user to reveal or hide widgets below -it. It also allows the user to enable the expansion of the row, allowing to -disable all that the row contains. - -## AdwExpanderRow as GtkBuildable - -The `AdwExpanderRow` implementation of the [iface@Gtk.Buildable] interface -supports adding a child as an suffix widget by specifying “suffix” as the -“type” attribute of a <child> element. - -It also supports adding it as a prefix widget by specifying “prefix” as the -“type” attribute of a <child> element. - -## CSS nodes - -`AdwExpanderRow` has a main CSS node with name `row` and the `.expander` -style class. It has the `.empty` style class when it contains no children. - -It contains the subnodes `row.header` for its main embedded row, -`list.nested` for the list it can expand, and `image.expander-row-arrow` for -its arrow. - - - - - - - Creates a new `AdwExpanderRow`. - - - the newly created `AdwExpanderRow` - - - - Adds an action widget to @self. - Use [method@ExpanderRow.add_suffix] to add a suffix. - + filename="src/adw-leaflet.c" + line="3424">Sets the child transition spring parameters for @self. + +The default value is equivalent to: + +```c +adw_spring_params_new (1, 0.5, 500) +``` + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an expander row - + filename="src/adw-leaflet.c" + line="3426">a leaflet + - + a widget - + filename="src/adw-leaflet.c" + line="3427">the new parameters + - + Adds a prefix widget to @self. - + filename="src/adw-leaflet.c" + line="3118">Sets the fold threshold policy for @self. + +If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the +children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it +will fold as soon as children don't get their natural size. + +This can be useful if you have a long ellipsizing label and want to let it +ellipsize instead of immediately folding. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an expander row - + filename="src/adw-leaflet.c" + line="3120">a leaflet + - + a widget - + filename="src/adw-leaflet.c" + line="3121">the policy to use + - + Adds a widget to @self. + filename="src/adw-leaflet.c" + line="3169">Sets @self to be homogeneous or not. -The widget will appear in the expanding list below @self. - +If set to `FALSE`, different children can have different size along the +opposite orientation. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an expander row - + filename="src/adw-leaflet.c" + line="3171">a leaflet + - + a widget - + filename="src/adw-leaflet.c" + line="3172">whether to make @self homogeneous + - + Adds an suffix widget to @self. - + filename="src/adw-leaflet.c" + line="3379">Sets the mode transition animation duration for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an expander row - + filename="src/adw-leaflet.c" + line="3381">a leaflet + - + a widget - + filename="src/adw-leaflet.c" + line="3382">the new duration, in milliseconds + - - + Gets whether the expansion of @self is enabled. - + filename="src/adw-leaflet.c" + line="3321">Sets the type of animation used for transitions between modes and children. + +The transition type can be changed without problems at runtime, so it is +possible to change the animation based on the mode or child that is about to +become current. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - whether the expansion of @self is enabled. - + an expander row - + filename="src/adw-leaflet.c" + line="3323">a leaflet + - - - - - Gets whether @self is expanded. - - - whether @self is expanded - - - - + an expander row - - + filename="src/adw-leaflet.c" + line="3324">the new transition type + + - - - Gets the icon name for @self. - Use [method@ExpanderRow.add_prefix] to add an icon. - - - the icon name for @self - - - - - an expander row - - - - - - + deprecated-version="1.4"> Gets whether the switch enabling the expansion of @self is visible. - + filename="src/adw-leaflet.c" + line="3220">Sets the widget currently visible when the leaflet is folded. + +The transition is determined by [property@Leaflet:transition-type] and +[property@Leaflet:child-transition-params]. The transition can be cancelled +by the user, in which case visible child will change back to the previously +visible child. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - whether the switch enabling the expansion is visible - + an expander row - + filename="src/adw-leaflet.c" + line="3222">a leaflet + + + the new child + + - - + Gets the subtitle for @self. - + filename="src/adw-leaflet.c" + line="3274">Makes the child with the name @name visible. + +See [property@Leaflet:visible-child]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - the subtitle for @self - + an expander row - + filename="src/adw-leaflet.c" + line="3276">a leaflet + + + the name of a child + + - - + Gets the number of lines at the end of which the subtitle label will be -ellipsized. - + filename="src/adw-leaflet.c" + line="2331">Whether gestures and shortcuts for navigating backward are enabled. + +The supported gestures are: + +- One-finger swipe on touchscreens +- Horizontal scrolling on touchpads (usually two-finger swipe) +- Back/forward mouse buttons + +The keyboard back/forward keys are also supported, as well as the +<kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or +<kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation. + +If the orientation is horizontal, for right-to-left locales, gestures and +shortcuts are reversed. + +Only children that have [property@LeafletPage:navigatable] set to `TRUE` +can be navigated to. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Whether gestures and shortcuts for navigating forward are enabled. + +The supported gestures are: + +- One-finger swipe on touchscreens +- Horizontal scrolling on touchpads (usually two-finger swipe) +- Back/forward mouse buttons + +The keyboard back/forward keys are also supported, as well as the +<kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or +<kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation. + +If the orientation is horizontal, for right-to-left locales, gestures and +shortcuts are reversed. + +Only children that have [property@LeafletPage:navigatable] set to `TRUE` +can be navigated to. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Whether or not the leaflet can unfold. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + The child transition spring parameters. + +The default value is equivalent to: + +```c +adw_spring_params_new (1, 0.5, 500) +``` + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Whether a child transition is currently running. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Determines when the leaflet will fold. + +If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the +children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it +will fold as soon as children don't get their natural size. + +This can be useful if you have a long ellipsizing label and want to let it +ellipsize instead of immediately folding. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Whether the leaflet is folded. + +The leaflet will be folded if the size allocated to it is smaller than the +sum of the minimum or natural sizes of the children (see +[property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Whether the leaflet allocates the same size for all children when folded. + +If set to `FALSE`, different children can have different size along the +opposite orientation. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + The mode transition animation duration, in milliseconds. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + A selection model with the leaflet's pages. + +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the visible +page. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + The type of animation used for transitions between modes and children. + +The transition type can be changed without problems at runtime, so it is +possible to change the animation based on the mode or child that is about +to become current. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + The widget currently visible when the leaflet is folded. + +The transition is determined by [property@Leaflet:transition-type] and +[property@Leaflet:child-transition-params]. The transition can be cancelled +by the user, in which case visible child will change back to the previously +visible child. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + The name of the widget currently visible when the leaflet is folded. + +See [property@Leaflet:visible-child]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + + + + + + + + An auxiliary class used by [class@Leaflet]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + Gets the leaflet child to which @self belongs. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + the number of lines at the end of which the subtitle label will be - ellipsized - + filename="src/adw-leaflet.c" + line="2671">the child to which @self belongs + an expander row - + filename="src/adw-leaflet.c" + line="2667">a leaflet page + - - + Gets the number of lines at the end of which the title label will be -ellipsized. - - + filename="src/adw-leaflet.c" + line="2683">Gets the name of @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + the number of lines at the end of which the title label will be - ellipsized - + filename="src/adw-leaflet.c" + line="2689">the name of @self. + - an expander row - + a leaflet page + - - + + Gets whether the child can be navigated to when folded. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + - + whether @self can be navigated to when folded + - + a leaflet page + - - - - - + Sets whether the expansion of @self is enabled. - + filename="src/adw-leaflet.c" + line="2701">Sets the name of the @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an expander row - + filename="src/adw-leaflet.c" + line="2703">a leaflet page + - + whether to enable the expansion - + filename="src/adw-leaflet.c" + line="2704">the new value to set + - - + Sets whether @self is expanded. - + filename="src/adw-leaflet.c" + line="2766">Sets whether @self can be navigated to when folded. + +If `FALSE`, the child will be ignored by [method@Leaflet.get_adjacent_child], +[method@Leaflet.navigate], and swipe gestures. + +This can be used used to prevent switching to widgets like separators. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + an expander row - + filename="src/adw-leaflet.c" + line="2768">a leaflet page + - + whether to expand the row + filename="src/adw-leaflet.c" + line="2769">whether @self can be navigated to when folded - - + Sets the icon name for @self. - Use [method@ExpanderRow.add_prefix] to add an icon. - + filename="src/adw-leaflet.c" + line="275">The leaflet child to which the page belongs. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + The name of the child page. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + Whether the child can be navigated to when folded. + +If `FALSE`, the child will be ignored by +[method@Leaflet.get_adjacent_child], [method@Leaflet.navigate], and swipe +gestures. + +This can be used used to prevent switching to widgets like separators. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + + + + + + + + + + Describes the possible transitions in a [class@Leaflet] widget. + +New values may be added to this enumeration over time. + See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + + Cover the old page or uncover the new page, sliding from or towards the end according to orientation, text direction and children order + + + Uncover the new page or cover the old page, sliding from or towards the start according to orientation, text direction and children order + + + Slide from left, right, up or down according to the orientation, text direction and the children order + + + + Describes length units. + +| Unit | Regular Text | Large Text | +| ---- | ------------ | ---------- | +| 1px | 1px | 1px | +| 1pt | 1.333333px | 1.666667px | +| 1sp | 1px | 1.25px | + +New values may be added to this enumeration over time. + + pixels + + + points, changes with text scale factor + + + scale independent pixels, changes with text scale factor + + + Converts @value from pixels to @unit. + - + the length in @unit + - + an expander row - - - a length unit + + + + a value in pixels + + + the icon name - + filename="src/adw-length-unit.c" + line="88">settings to use, or `NULL` for default settings + - - - + + Sets whether the switch enabling the expansion of @self is visible. - + filename="src/adw-length-unit.c" + line="45">Converts @value from @unit to pixels. + - + the length in pixels + - + an expander row - - - + filename="src/adw-length-unit.c" + line="47">a length unit + + + whether to show the switch enabling the expansion - + filename="src/adw-length-unit.c" + line="48">a value in @unit + + + + settings to use, or `NULL` for default settings + - - - + + + + Adwaita major version component (e.g. 1 if the version is 1.2.3). + + + + + Adwaita micro version component (e.g. 3 if the version is 1.2.3). + + + + + Adwaita minor version component (e.g. 2 if the version is 1.2.3). + + + + + A dialog presenting a message or a question. + +<picture> + <source srcset="message-dialog-dark.png" media="(prefers-color-scheme: dark)"> + <img src="message-dialog.png" alt="message-dialog"> +</picture> + +Message dialogs have a heading, a body, an optional child widget, and one or +multiple responses, each presented as a button. + +Each response has a unique string ID, and a button label. Additionally, each +response can be enabled or disabled, and can have a suggested or destructive +appearance. + +When one of the responses is activated, or the dialog is closed, the +[signal@MessageDialog::response] signal will be emitted. This signal is +detailed, and the detail, as well as the `response` parameter will be set to +the ID of the activated response, or to the value of the +[property@MessageDialog:close-response] property if the dialog had been +closed without activating any of the responses. + +Response buttons can be presented horizontally or vertically depending on +available space. + +When a response is activated, `AdwMessageDialog` is closed automatically. + +An example of using a message dialog: + +```c +GtkWidget *dialog; + +dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL); + +adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), + _("A file named “%s” already exists. Do you want to replace it?"), + filename); + +adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), + "cancel", _("_Cancel"), + "replace", _("_Replace"), + NULL); + +adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); + +adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); +adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); + +g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self); + +gtk_window_present (GTK_WINDOW (dialog)); +``` + +## Async API + +`AdwMessageDialog` can also be used via the [method@MessageDialog.choose] +method. This API follows the GIO async pattern, for example: + +```c +static void +dialog_cb (AdwMessageDialog *dialog, + GAsyncResult *result, + MyWindow *self) +{ + const char *response = adw_message_dialog_choose_finish (dialog, result); + + // ... +} + +static void +show_dialog (MyWindow *self) +{ + GtkWidget *dialog; + + dialog = adw_message_dialog_new (GTK_WINDOW (self), _("Replace File?"), NULL); + + adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), + _("A file named “%s” already exists. Do you want to replace it?"), + filename); + + adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), + "cancel", _("_Cancel"), + "replace", _("_Replace"), + NULL); + + adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); + + adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); + adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); + + adw_message_dialog_choose (ADW_MESSAGE_DIALOG (dialog), NULL, (GAsyncReadyCallback) dialog_cb, self); +} +``` + +## AdwMessageDialog as GtkBuildable + +`AdwMessageDialog` supports adding responses in UI definitions by via the +`<responses>` element that may contain multiple `<response>` elements, each +representing a response. + +Each of the `<response>` elements must have the `id` attribute specifying the +response ID. The contents of the element are used as the response label. + +Response labels can be translated with the usual `translatable`, `context` +and `comments` attributes. + +The `<response>` elements can also have `enabled` and/or `appearance` +attributes. See [method@MessageDialog.set_response_enabled] and +[method@MessageDialog.set_response_appearance] for details. + +Example of an `AdwMessageDialog` UI definition: + +```xml +<object class="AdwMessageDialog" id="dialog"> + <property name="heading" translatable="yes">Save Changes?</property> + <property name="body" translatable="yes">Open documents contain unsaved changes. Changes which are not saved will be permanently lost.</property> + <property name="default-response">save</property> + <property name="close-response">cancel</property> + <signal name="response" handler="response_cb"/> + <responses> + <response id="cancel" translatable="yes">_Cancel</response> + <response id="discard" translatable="yes" appearance="destructive">_Discard</response> + <response id="save" translatable="yes" appearance="suggested" enabled="false">_Save</response> + </responses> +</object> +``` + +## Accessibility + +`AdwMessageDialog` uses the `GTK_ACCESSIBLE_ROLE_DIALOG` role. + Use [class@AlertDialog]. + + + + + + + + Sets the subtitle for @self. + filename="src/adw-message-dialog.c" + line="1432">Creates a new `AdwMessageDialog`. -The subtitle is interpreted as Pango markup unless -[property@PreferencesRow:use-markup] is set to `FALSE`. - +@heading and @body can be set to `NULL`. This can be useful if they need to +be formatted or use markup. In that case, set them to `NULL` and call +[method@MessageDialog.format_body] or similar methods afterwards: + +```c +GtkWidget *dialog; + +dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL); +adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), + _("A file named “%s” already exists. Do you want to replace it?"), + filename); +``` + Use [class@AlertDialog]. + - + the newly created `AdwMessageDialog` + - + an expander row - - - + filename="src/adw-message-dialog.c" + line="1434">transient parent + + + the subtitle + filename="src/adw-message-dialog.c" + line="1435">the heading + + + + the body text - - - + + + Sets the number of lines at the end of which the subtitle label will be -ellipsized. + filename="src/adw-message-dialog.c" + line="2475">Emits the [signal@MessageDialog::response] signal with the given response ID. -If the value is 0, the number of lines won't be limited. - +Used to indicate that the user has responded to the dialog in some way. + Use [class@AlertDialog]. + an expander row - + filename="src/adw-message-dialog.c" + line="2477">a message dialog + - + the number of lines at the end of which the subtitle label will be ellipsized - + filename="src/adw-message-dialog.c" + line="2478">response ID + - - - + + Sets the number of lines at the end of which the title label will be -ellipsized. + filename="src/adw-message-dialog.c" + line="1965">Adds a response with @id and @label to @self. -If the value is 0, the number of lines won't be limited. - +Responses are represented as buttons in the dialog. + +Response ID must be unique. It will be used in +[signal@MessageDialog::response] to tell which response had been activated, +as well as to inspect and modify the response later. + +An embedded underline in @label indicates a mnemonic. + +[method@MessageDialog.set_response_label] can be used to change the response +label after it had been added. + +[method@MessageDialog.set_response_enabled] and +[method@MessageDialog.set_response_appearance] can be used to customize the +responses further. + Use [class@AlertDialog]. + an expander row - + filename="src/adw-message-dialog.c" + line="1967">a message dialog + - + the number of lines at the end of which the title label will be ellipsized - + filename="src/adw-message-dialog.c" + line="1968">the response ID + + + + the response label + - - - - Whether expansion is enabled. - - - - - - Whether the row is expanded. - - - - - - The icon name for this row. - Use [method@ExpanderRow.add_prefix] to add an icon. - - - - - - Whether the switch enabling the expansion is visible. - - - - - - The subtitle for this row. - -The subtitle is interpreted as Pango markup unless -[property@PreferencesRow:use-markup] is set to `FALSE`. - - - - - - The number of lines at the end of which the subtitle label will be -ellipsized. - -If the value is 0, the number of lines won't be limited. - - - - - - The number of lines at the end of which the title label will be ellipsized. - -If the value is 0, the number of lines won't be limited. - - - - - - - - - + The parent class - - - - - - - - - - An adaptive container acting like a box or an overlay. - -<picture> - <source srcset="flap-wide-dark.png" media="(prefers-color-scheme: dark)"> - <img src="flap-wide.png" alt="flap-wide"> -</picture> -<picture> - <source srcset="flap-narrow-dark.png" media="(prefers-color-scheme: dark)"> - <img src="flap-narrow.png" alt="flap-narrow"> -</picture> - -The `AdwFlap` widget can display its children like a [class@Gtk.Box] does or -like a [class@Gtk.Overlay] does, according to the -[property@Flap:fold-policy] value. - -`AdwFlap` has at most three children: [property@Flap:content], -[property@Flap:flap] and [property@Flap:separator]. Content is the primary -child, flap is displayed next to it when unfolded, or overlays it when -folded. Flap can be shown or hidden by changing the -[property@Flap:reveal-flap] value, as well as via swipe gestures if -[property@Flap:swipe-to-open] and/or [property@Flap:swipe-to-close] are set -to `TRUE`. - -Optionally, a separator can be provided, which would be displayed between -the content and the flap when there's no shadow to separate them, depending -on the transition type. - -[property@Flap:flap] is transparent by default; add the -[`.background`](style-classes.html#background) style class to it if this is -unwanted. - -If [property@Flap:modal] is set to `TRUE`, content becomes completely -inaccessible when the flap is revealed while folded. - -The position of the flap and separator children relative to the content is -determined by orientation, as well as the [property@Flap:flap-position] -value. - -Folding the flap will automatically hide the flap widget, and unfolding it -will automatically reveal it. If this behavior is not desired, the -[property@Flap:locked] property can be used to override it. - -Common use cases include sidebars, header bars that need to be able to -overlap the window content (for example, in fullscreen mode) and bottom -sheets. - -## AdwFlap as GtkBuildable + filename="src/adw-message-dialog.c" + line="2029">Adds multiple responses to @self. -The `AdwFlap` implementation of the [iface@Gtk.Buildable] interface supports -setting the flap child by specifying “flap” as the “type” attribute of a -`<child>` element, and separator by specifying “separator”. Specifying -“content” child type or omitting it results in setting the content child. +This is the same as calling [method@MessageDialog.add_response] repeatedly. +The variable argument list should be `NULL`-terminated list of response IDs +and labels. -## CSS nodes +Example: -`AdwFlap` has a single CSS node with name `flap`. The node will get the style -classes `.folded` when it is folded, and `.unfolded` when it's not. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - - - - Creates a new `AdwFlap`. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +```c +adw_message_dialog_add_responses (dialog, + "cancel", _("_Cancel"), + "discard", _("_Discard"), + "save", _("_Save"), + NULL); +``` + Use [class@AlertDialog]. + - the newly created `AdwFlap` - - - - - - Gets the content widget for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - the content widget for @self - + a flap - + filename="src/adw-message-dialog.c" + line="2031">a message dialog + + + response id + + + + label for first response, then more id-label pairs + + - - + deprecated-version="1.6" + glib:finish-func="choose_finish"> Gets the flap widget for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - the flap widget for @self - + filename="src/adw-message-dialog.c" + line="2549">This function shows @self to the user. + Use [class@AlertDialog]. + + + a flap - + filename="src/adw-message-dialog.c" + line="2551">a message dialog + + + a `GCancellable` to cancel the operation + + + + a callback to call when the operation is complete + + + + data to pass to @callback + + - - + deprecated-version="1.6"> Gets the flap position for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2582">Finishes the [method@MessageDialog.choose] call and returns the response ID. + Use [class@AlertDialog]. + the flap position for @self - + filename="src/adw-message-dialog.c" + line="2589">the ID of the response that was selected, or + [property@MessageDialog:close-response] if the call was cancelled. + a flap - + filename="src/adw-message-dialog.c" + line="2584">a message dialog + + + a `GAsyncResult` + + - - + deprecated-version="1.6"> Gets the fold transition animation duration for @self, in milliseconds. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1812">Sets the formatted body text of @self. + +See [property@MessageDialog:body]. + Use [class@AlertDialog]. + - the fold transition duration - + a flap - + filename="src/adw-message-dialog.c" + line="1814">a message dialog + + + the formatted string for the body text + + + + the parameters to insert into @format + + - - + deprecated-version="1.6"> Gets the fold policy for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1856">Sets the formatted body text of @self with Pango markup. + +The @format is assumed to contain Pango markup. + +Special XML characters in the `printf()` arguments passed to this function +will automatically be escaped as necessary, see +[func@GLib.markup_printf_escaped]. + +See [property@MessageDialog:body]. + Use [class@AlertDialog]. + - the fold policy for @self - + a flap - + filename="src/adw-message-dialog.c" + line="1858">a message dialog + + + the formatted string for the body text with Pango markup + + + + the parameters to insert into @format + + - - + deprecated-version="1.6"> Gets the fold threshold policy for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1603">Sets the formatted heading of @self. + +See [property@MessageDialog:heading]. + Use [class@AlertDialog]. + - + a flap - + filename="src/adw-message-dialog.c" + line="1605">a message dialog + + + the formatted string for the heading + + + + the parameters to insert into @format + + - - + deprecated-version="1.6"> Gets whether @self is currently folded. + filename="src/adw-message-dialog.c" + line="1647">Sets the formatted heading of @self with Pango markup. -See [property@Flap:fold-policy]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +The @format is assumed to contain Pango markup. + +Special XML characters in the `printf()` arguments passed to this function +will automatically be escaped as necessary, see +[func@GLib.markup_printf_escaped]. + +See [property@MessageDialog:heading]. + Use [class@AlertDialog]. + - `TRUE` if @self is currently folded - + a flap - + filename="src/adw-message-dialog.c" + line="1649">a message dialog + + + the formatted string for the heading with Pango markup + + + + the parameters to insert into @format + + - - + deprecated-version="1.6"> Gets whether @self is locked. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1697">Gets the body text of @self. + Use [class@AlertDialog]. + `TRUE` if @self is locked - + filename="src/adw-message-dialog.c" + line="1703">the body of @self. + a flap - + filename="src/adw-message-dialog.c" + line="1699">a message dialog + - - + deprecated-version="1.6"> Gets whether @self is modal. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1755">Gets whether the body text of @self includes Pango markup. + Use [class@AlertDialog]. + `TRUE` if @self is modal + filename="src/adw-message-dialog.c" + line="1761">whether @self uses markup for body text a flap - + filename="src/adw-message-dialog.c" + line="1757">a message dialog + - - + deprecated-version="1.6"> Gets whether the flap widget is revealed for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2414">Gets the ID of the close response of @self. + Use [class@AlertDialog]. + `TRUE` if the flap widget is revealed - + filename="src/adw-message-dialog.c" + line="2420">the close response ID + a flap - + filename="src/adw-message-dialog.c" + line="2416">a message dialog + - - + deprecated-version="1.6"> Gets the reveal animation spring parameters for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - + filename="src/adw-message-dialog.c" + line="2347">Gets the ID of the default response of @self. + Use [class@AlertDialog]. + + the reveal animation parameters - + filename="src/adw-message-dialog.c" + line="2353">the default response ID + a flap - + filename="src/adw-message-dialog.c" + line="2349">a message dialog + - - + deprecated-version="1.6"> Gets the current reveal progress for @self. - -0 means fully hidden, 1 means fully revealed. - -See [property@Flap:reveal-flap]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - + filename="src/adw-message-dialog.c" + line="1906">Gets the child widget of @self. + Use [class@AlertDialog]. + + the current reveal progress for @self - + filename="src/adw-message-dialog.c" + line="1912">the child widget of @self. + a flap - + filename="src/adw-message-dialog.c" + line="1908">a message dialog + - - + deprecated-version="1.6"> Gets the separator widget for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1480">Gets the heading of @self. + Use [class@AlertDialog]. + the separator widget for @self - + filename="src/adw-message-dialog.c" + line="1486">the heading of @self. + a flap - + filename="src/adw-message-dialog.c" + line="1482">a message dialog + - - + deprecated-version="1.6"> Gets whether @self can be closed with a swipe gesture. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1542">Gets whether the heading of @self includes Pango markup. + Use [class@AlertDialog]. + `TRUE` if @self can be closed with a swipe gesture + filename="src/adw-message-dialog.c" + line="1548">whether @self uses markup for heading a flap - + filename="src/adw-message-dialog.c" + line="1544">a message dialog + - - + deprecated-version="1.6"> Gets whether @self can be opened with a swipe gesture. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2188">Gets the appearance of @response. + +See [method@MessageDialog.set_response_appearance]. + Use [class@AlertDialog]. + `TRUE` if @self can be opened with a swipe gesture - + filename="src/adw-message-dialog.c" + line="2197">the appearance of @response + a flap - + filename="src/adw-message-dialog.c" + line="2190">a message dialog + + + a response ID + + - - + deprecated-version="1.6"> Gets the type of animation used for reveal and fold transitions in @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2275">Gets whether @response is enabled. + +See [method@MessageDialog.set_response_enabled]. + Use [class@AlertDialog]. + the current transition type of @self - + filename="src/adw-message-dialog.c" + line="2284">whether @response is enabled + a flap - + filename="src/adw-message-dialog.c" + line="2277">a message dialog + + + a response ID + + - - + deprecated-version="1.6"> Sets the content widget for @self. + filename="src/adw-message-dialog.c" + line="2126">Gets the label of @response. -It's always displayed when unfolded, and partially visible when folded. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +See [method@MessageDialog.set_response_label]. + Use [class@AlertDialog]. + - + the label of @response + a flap - + filename="src/adw-message-dialog.c" + line="2128">a message dialog + - + the content widget - + filename="src/adw-message-dialog.c" + line="2129">a response ID + - - + deprecated-version="1.6"> Sets the flap widget for @self. - -It's only visible when [property@Flap:reveal-progress] is greater than 0. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2498">Gets whether @self has a response with the ID @response. + Use [class@AlertDialog]. + - + whether @self has a response with the ID @response. + a flap - + filename="src/adw-message-dialog.c" + line="2500">a message dialog + - + the flap widget - + filename="src/adw-message-dialog.c" + line="2501">response ID + - - + deprecated-version="1.6"> Sets the flap position for @self. - -If it's set to `GTK_PACK_START`, the flap is displayed before the content, -if `GTK_PACK_END`, it's displayed after the content. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2085">Removes a response from @self. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2087">a message dialog + - + the new value - + filename="src/adw-message-dialog.c" + line="2088">the response ID + - - + deprecated-version="1.6"> + Sets the fold transition animation duration for @self, in milliseconds. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="2475">Emits the [signal@MessageDialog::response] signal with the given response ID. + +Used to indicate that the user has responded to the dialog in some way. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2477">a message dialog + - + the new duration, in milliseconds - + filename="src/adw-message-dialog.c" + line="2478">response ID + - - + deprecated-version="1.6"> Sets the fold policy for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1720">Sets the body text of @self. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="1722">a message dialog + - + the fold policy - + filename="src/adw-message-dialog.c" + line="1723">the body of @self + - - + deprecated-version="1.6"> Sets the fold threshold policy for @self. - -If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when the -children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it -will fold as soon as children don't get their natural size. + filename="src/adw-message-dialog.c" + line="1778">Sets whether the body text of @self includes Pango markup. -This can be useful if you have a long ellipsizing label and want to let it -ellipsize instead of immediately folding. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +See [func@Pango.parse_markup]. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="1780">a message dialog + - + the policy to use - + filename="src/adw-message-dialog.c" + line="1781">whether to use markup for body text + - - + deprecated-version="1.6"> Sets whether @self is locked. + filename="src/adw-message-dialog.c" + line="2437">Sets the ID of the close response of @self. -If `FALSE`, folding when the flap is revealed automatically closes it, and -unfolding it when the flap is not revealed opens it. If `TRUE`, -[property@Flap:reveal-flap] value never changes on its own. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +It will be passed to [signal@MessageDialog::response] if the window is +closed by pressing <kbd>Escape</kbd> or with a system action. + +It doesn't have to correspond to any of the responses in the dialog. + +The default close response is `close`. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2439">a message dialog + - + the new value - + filename="src/adw-message-dialog.c" + line="2440">the close response ID + - - + deprecated-version="1.6"> Sets whether @self is modal. + filename="src/adw-message-dialog.c" + line="2373">Sets the ID of the default response of @self. -If `TRUE`, clicking the content widget while flap is revealed, as well as -pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks are -passed through to the content widget. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +If set, pressing <kbd>Enter</kbd> will activate the corresponding button. + +If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd> +will do nothing. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2375">a message dialog + - + whether @self is modal - + filename="src/adw-message-dialog.c" + line="2376">the default response ID + - - + deprecated-version="1.6"> Sets whether the flap widget is revealed for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1929">Sets the child widget of @self. + +The child widget is displayed below the heading and body. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="1931">a message dialog + - + whether to reveal the flap widget - + filename="src/adw-message-dialog.c" + line="1932">the child widget + - - + deprecated-version="1.6"> Sets the reveal animation spring parameters for @self. - -The default value is equivalent to: - -```c -adw_spring_params_new (1, 0.5, 500) -``` - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1503">Sets the heading of @self. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="1505">a message dialog + - + the new parameters - + filename="src/adw-message-dialog.c" + line="1506">the heading of @self + - - + deprecated-version="1.6"> Sets the separator widget for @self. + filename="src/adw-message-dialog.c" + line="1565">Sets whether the heading of @self includes Pango markup. -It's displayed between content and flap when there's no shadow to display. -When exactly it's visible depends on the [property@Flap:transition-type] -value. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +See [func@Pango.parse_markup]. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="1567">a message dialog + - + the separator widget - + filename="src/adw-message-dialog.c" + line="1568">whether to use markup for heading + - - + deprecated-version="1.6"> Sets whether @self can be closed with a swipe gesture. + filename="src/adw-message-dialog.c" + line="2217">Sets the appearance for @response. + +<picture> + <source srcset="message-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)"> + <img src="message-dialog-appearance.png" alt="message-dialog-appearance"> +</picture> + +Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the +affirmative action, like the Save button in the example. + +Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging +consequences of using @response. This appearance acts as a warning to the +user. The Discard button in the example is using this appearance. -The area that can be swiped depends on the [property@Flap:transition-type] -value. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +The default appearance is `ADW_RESPONSE_DEFAULT`. + +Negative responses like Cancel or Close should use the default appearance. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2219">a message dialog + - + whether @self can be closed with a swipe gesture - + filename="src/adw-message-dialog.c" + line="2220">a response ID + + + + appearance for @response + - - + deprecated-version="1.6"> Sets whether @self can be opened with a swipe gesture. + filename="src/adw-message-dialog.c" + line="2304">Sets whether @response is enabled. -The area that can be swiped depends on the [property@Flap:transition-type] -value. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +If @response is not enabled, the corresponding button will have +[property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as +a default response. + +@response can still be used as [property@MessageDialog:close-response] while +it's not enabled. + +Responses are enabled by default. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2306">a message dialog + - + whether @self can be opened with a swipe gesture + filename="src/adw-message-dialog.c" + line="2307">a response ID + + + + whether to enable @response - - + deprecated-version="1.6"> Sets the type of animation used for reveal and fold transitions in @self. + filename="src/adw-message-dialog.c" + line="2155">Sets the label of @response to @label. -[property@Flap:flap] is transparent by default, which means the content will -be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; add the -[`.background`](style-classes.html#background) style class to it if this is -unwanted. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +Labels are displayed on the dialog buttons. An embedded underline in @label +indicates a mnemonic. + Use [class@AlertDialog]. + a flap - + filename="src/adw-message-dialog.c" + line="2157">a message dialog + - + the new transition type - + filename="src/adw-message-dialog.c" + line="2158">a response ID + + + + the label of @response + - - - + setter="set_body" + getter="get_body"> The content widget. - -It's always displayed when unfolded, and partially visible when folded. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="1027">The body text of the dialog. + Use [class@AlertDialog]. + - - - + setter="set_body_use_markup" + getter="get_body_use_markup" + default-value="FALSE"> The flap widget. + filename="src/adw-message-dialog.c" + line="1040">Whether the body text includes Pango markup. -It's only visible when [property@Flap:reveal-progress] is greater than 0. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +See [func@Pango.parse_markup]. + Use [class@AlertDialog]. + - - - + setter="set_close_response" + getter="get_close_response" + default-value="close"> The flap position. + filename="src/adw-message-dialog.c" + line="1088">The ID of the close response. -If it's set to `GTK_PACK_START`, the flap is displayed before the content, -if `GTK_PACK_END`, it's displayed after the content. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - - The fold transition animation duration, in milliseconds. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - - The fold policy for the flap. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - - Determines when the flap will fold. +It will be passed to [signal@MessageDialog::response] if the window is +closed by pressing <kbd>Escape</kbd> or with a system action. -If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when -the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, -it will fold as soon as children don't get their natural size. +It doesn't have to correspond to any of the responses in the dialog. -This can be useful if you have a long ellipsizing label and want to let it -ellipsize instead of immediately folding. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +The default close response is `close`. + Use [class@AlertDialog]. + - - + setter="set_default_response" + getter="get_default_response" + default-value="NULL"> Whether the flap is currently folded. + filename="src/adw-message-dialog.c" + line="1070">The response ID of the default response. -See [property@Flap:fold-policy]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +If set, pressing <kbd>Enter</kbd> will activate the corresponding button. + +If set to `NULL` or a non-existent response ID, pressing <kbd>Enter</kbd> +will do nothing. + Use [class@AlertDialog]. + - - - + setter="set_extra_child" + getter="get_extra_child"> Whether the flap is locked. + filename="src/adw-message-dialog.c" + line="1055">The child widget. -If `FALSE`, folding when the flap is revealed automatically closes it, and -unfolding it when the flap is not revealed opens it. If `TRUE`, -[property@Flap:reveal-flap] value never changes on its own. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +Displayed below the heading and body. + Use [class@AlertDialog]. + - - - + setter="set_heading" + getter="get_heading"> Whether the flap is modal. - -If `TRUE`, clicking the content widget while flap is revealed, as well as -pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks -are passed through to the content widget. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-message-dialog.c" + line="999">The heading of the dialog. + Use [class@AlertDialog]. + - - - + setter="set_heading_use_markup" + getter="get_heading_use_markup" + default-value="FALSE"> Whether the flap widget is revealed. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) + filename="src/adw-message-dialog.c" + line="1012">Whether the heading includes Pango markup. + +See [func@Pango.parse_markup]. + Use [class@AlertDialog]. - - - + + + + The reveal animation spring parameters. + filename="src/adw-message-dialog.c" + line="1110">This signal is emitted when the dialog is closed. -The default value is equivalent to: +@response will be set to the response ID of the button that had been +activated. -```c -adw_spring_params_new (1, 0.5, 500) -``` - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - The current reveal transition progress. +if the dialog was closed by pressing <kbd>Escape</kbd> or with a system +action, @response will be set to the value of +[property@MessageDialog:close-response]. + Use [class@AlertDialog]. + + + + + + the response ID + + + + + + + + + + + + + + + + + + + a message dialog + + + + response ID + + + + + + + + + + + + + A widget for switching between different layouts. -0 means fully hidden, 1 means fully revealed. +`AdwMultiLayoutView` contains layouts and children. Each child has +an ID, each layout has slots inside it, each slot also has an ID. When +switching layouts, children are inserted into slots with matching IDs. The +[property@Gtk.Widget:visible] property of each slot is updated to match +that of the inserted child. -See [property@Flap:reveal-flap]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - +This can be useful for rearranging children when it's difficult to do so +otherwise, for example to move a child from a sidebar to a bottom bar. + +The currently used layout can be switched using the +[property@MultiLayoutView:layout] or [property@MultiLayoutView:layout-name] +properties. For example, it can be done via a [class@Adw.Breakpoint] setter +to change layouts depending on the window size. + +## AdwMultiLayoutView as GtkBuildable + +The `AdwMultiLayoutView` implementation of the [iface@Gtk.Buildable] +interface supports adding layouts via `<child>` element with the `type` +attribute omitted. + +It also supports setting children via `<child type="ID">`. + +Example of an `AdwMultiLayoutView` UI definition that can display a secondary +child as either a sidebar or a bottom sheet. + +```xml +<object class="AdwMultiLayoutView"> + <child> + <object class="AdwLayout"> + <property name="name">sidebar</property> + <property name="content"> + <object class="AdwOverlaySplitView"> + <property name="sidebar"> + <object class="AdwLayoutSlot"> + <property name="id">secondary</property> + </object> + </property> + <property name="content"> + <object class="AdwLayoutSlot"> + <property name="id">primary</property> + </object> + </property> + </object> + </property> + </object> + </child> + <child> + <object class="AdwLayout"> + <property name="name">bottom-sheet</property> + <property name="content"> + <object class="AdwBottomSheet"> + <property name="open">True</property> + <property name="content"> + <object class="AdwLayoutSlot"> + <property name="id">primary</property> + </object> + </property> + <property name="sheet"> + <object class="AdwLayoutSlot"> + <property name="id">secondary</property> + </object> + </property> + </object> + </property> + </object> + </child> + <child type="primary"> + <!-- ... --> + </child> + <child type="secondary"> + <!-- ... --> + </child> +</object> +``` + +## CSS nodes + +`AdwMultiLayoutView` has a single CSS node with name `multi-layout-view`. + + + + + The separator widget. + filename="src/adw-multi-layout-view.c" + line="426">Creates a new `AdwMultiLayoutView`. + + + the newly created `AdwMultiLayoutView` + + + + + Adds @layout to @self. + + + + + + + a multi-layout view + + + + the layout to add + + + + + + Gets the child for @id to @self. + + + the child for @id + + + + + a multi-layout view + + + + the id of the child + + + + + + Gets the currently used layout of @self. + + + the current layout + + + + + a multi-layout view + + + + + + Gets layout with the name @name from @self, or `NULL` if it doesn't exist. -It's displayed between content and flap when there's no shadow to display. -When exactly it's visible depends on the [property@Flap:transition-type] -value. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - - - +See [property@Layout:name]. + + + the layout with @name + + + + + a multi-layout view + + + + the name of the layout + + + + + + Returns the name of the currently used layout of @self. + + + the name of the current layout + + + + + a multi-layout view + + + + + + Removes @layout from @self. + + + + + + + a multi-layout view + + + + the layout to add + + + + + + Sets @child as the child for @id in @self. + +When changing layouts, it will be inserted into the slot with @id. + + + + + + + a multi-layout view + + + + the id of the child + + + + the child to set + + + + + Whether the flap can be closed with a swipe gesture. + filename="src/adw-multi-layout-view.c" + line="459">Makes @layout the current layout of @self. + + + + + + + a multi-layout view + + + + a layout in @self + + + + + + Makes the layout with @name the current layout of @self. -The area that can be swiped depends on the [property@Flap:transition-type] -value. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - - + + + + + + + a multi-layout view + + + + the name of the layout + + + + + - - + setter="set_layout" + getter="get_layout"> Whether the flap can be opened with a swipe gesture. - -The area that can be swiped depends on the [property@Flap:transition-type] -value. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - + filename="src/adw-multi-layout-view.c" + line="361">The currently used layout. + - - - + setter="set_layout_name" + getter="get_layout_name" + default-value="NULL"> the type of animation used for reveal and fold transitions. + filename="src/adw-multi-layout-view.c" + line="373">The name of the currently used layout. -[property@Flap:flap] is transparent by default, which means the content -will be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; -add the [`.background`](style-classes.html#background) style class to it if -this is unwanted. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - +See [property@Layout:name]. + - - + + - - Describes the possible folding behavior of a [class@Flap] widget. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - Disable folding, the flap cannot reach narrow - sizes. - - - Keep the flap always folded. - - - Fold and unfold the flap based on available - space. - - - - Describes transitions types of a [class@Flap] widget. - -It determines the type of animation when transitioning between children in a -[class@Flap] widget, as well as which areas can be swiped via -[property@Flap:swipe-to-open] and [property@Flap:swipe-to-close]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) - - The flap slides over the content, which is - dimmed. When folded, only the flap can be swiped. - - - The content slides over the flap. Only the - content can be swiped. - - - The flap slides offscreen when hidden, - neither the flap nor content overlap each other. Both widgets can be - swiped. - - - + Determines when [class@Flap] and [class@Leaflet] will fold. - Stop using `AdwLeaflet` and `AdwFlap` - Describes the direction of a swipe navigation gesture. + + c:identifier="ADW_NAVIGATION_DIRECTION_BACK" + glib:nick="back" + glib:name="ADW_NAVIGATION_DIRECTION_BACK"> Folding is based on the minimum size + filename="src/adw-navigation-direction.c" + line="12">Corresponds to start or top, depending on orientation and text direction - + c:identifier="ADW_NAVIGATION_DIRECTION_FORWARD" + glib:nick="forward" + glib:name="ADW_NAVIGATION_DIRECTION_FORWARD"> Folding is based on the natural size + filename="src/adw-navigation-direction.c" + line="13">Corresponds to end or bottom, depending on orientation and text direction - + glib:type-name="AdwNavigationPage" + glib:get-type="adw_navigation_page_get_type" + glib:type-struct="NavigationPageClass"> A title bar widget. + filename="src/adw-navigation-view.c" + line="184">A page within [class@NavigationView] or [class@NavigationSplitView]. -<picture> - <source srcset="header-bar-dark.png" media="(prefers-color-scheme: dark)"> - <img src="header-bar.png" alt="header-bar"> -</picture> +Each page has a child widget, a title and optionally a tag. -`AdwHeaderBar` is similar to [class@Gtk.HeaderBar], but provides additional -features compared to it. Refer to `GtkHeaderBar` for details. It is typically -used as a top bar within [class@ToolbarView]. +The [signal@NavigationPage::showing], [signal@NavigationPage::shown], +[signal@NavigationPage::hiding] and [signal@NavigationPage::hidden] signals +can be used to track the page's visibility within its `AdwNavigationView`. -## Navigation View Integration +## Header Bar Integration -When placed inside an [class@NavigationPage], `AdwHeaderBar` will display the +When placed inside `AdwNavigationPage`, [class@HeaderBar] will display the page title instead of window title. -When used together with [class@NavigationView] or [class@NavigationSplitView], -it will also display a back button that can be used to go back to the previous -page. The button also has a context menu, allowing to pop multiple pages at -once, potentially across multiple navigation views. In rare scenarios, set -[property@HeaderBar:show-back-button] to `FALSE` to disable the back button -if it's unwanted (e.g. in an extra header bar on the same page). - -## Split View Integration - -When placed inside `AdwNavigationSplitView` or `AdwOverlaySplitView`, -`AdwHeaderBar` will automatically hide the title buttons other than at the -edges of the window. - -## Centering Policy - -[property@HeaderBar:centering-policy] allows to enforce strict centering of -the title widget. This can be useful for entries inside [class@Clamp]. - -## Title Buttons - -Unlike `GtkHeaderBar`, `AdwHeaderBar` allows to toggle title button -visibility for each side individually, using the -[property@HeaderBar:show-start-title-buttons] and -[property@HeaderBar:show-end-title-buttons] properties. - -## CSS nodes - -``` -headerbar -╰── windowhandle - ╰── box - ├── widget - │ ╰── box.start - │ ├── windowcontrols.start - │ ├── widget - │ │ ╰── [button.back] - │ ╰── [other children] - ├── widget - │ ╰── [Title Widget] - ╰── widget - ╰── box.end - ├── [other children] - ╰── windowcontrols.end -``` - -`AdwHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle` -subnode, which contains a `box` subnode, which contains three `widget` -subnodes at the start, center and end of the header bar. The start and end -subnotes contain a `box` subnode with the `.start` and `.end` style classes -respectively, and the center node contains a node that represents the title. +When used together with [class@NavigationView], it will also display a back +button that can be used to go back to the previous page. Set +[property@HeaderBar:show-back-button] to `FALSE` to disable that behavior if +it's unwanted. -Each of the boxes contains a `windowcontrols` subnode, see -[class@Gtk.WindowControls] for details, as well as other children. +## CSS Nodes -When [property@HeaderBar:show-back-button] is `TRUE`, the start box also -contains a node with the name `widget` that contains a node with the name -`button` and `.back` style class. +`AdwNavigationPage` has a single CSS node with name +`navigation-view-page`. ## Accessibility -`AdwHeaderBar` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - +`AdwNavigationPage` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + - + Creates a new `AdwHeaderBar`. - + filename="src/adw-navigation-view.c" + line="2138">Creates a new `AdwNavigationPage`. + the newly created `AdwHeaderBar`. - + filename="src/adw-navigation-view.c" + line="2145">the new created `AdwNavigationPage` + + + + the child widget + + + + the page title + + + - - + Gets the policy for aligning the center widget. - + filename="src/adw-navigation-view.c" + line="2162">Creates a new `AdwNavigationPage` with provided tag. + the centering policy - + filename="src/adw-navigation-view.c" + line="2170">the new created `AdwNavigationPage` + + + + + the child widget + + + + the page title + + + + the page tag + + + + + + Called when the navigation view transition has been completed and the page +is fully hidden. + + + a header bar - + filename="src/adw-navigation-view.h" + line="65">a navigation page + - - - + + Gets the decoration layout for @self. - - - the decoration layout - + filename="src/adw-navigation-view.h" + line="52">Called when the page starts hiding at the beginning of the navigation view +transition. + + + a header bar - + filename="src/adw-navigation-view.h" + line="54">a navigation page + - - - + + Gets whether @self can show the back button. - + filename="src/adw-navigation-view.h" + line="30">Called when the page shows at the beginning of the navigation view +transition. + - whether to show the back button - + a header bar - + filename="src/adw-navigation-view.h" + line="32">a navigation page + - - - + + Gets whether to show title buttons at the end of @self. - + filename="src/adw-navigation-view.h" + line="41">Called when the navigation view transition has been completed and the page +is fully shown. + - `TRUE` if title buttons at the end are shown - + a header bar - + filename="src/adw-navigation-view.h" + line="43">a navigation page + - - - + + Gets whether to show title buttons at the start of @self. - + filename="src/adw-navigation-view.c" + line="2386">Gets whether @self can be popped from navigation stack. + `TRUE` if title buttons at the start are shown + filename="src/adw-navigation-view.c" + line="2392">whether the page can be popped from navigation stack a header bar - + filename="src/adw-navigation-view.c" + line="2388">a navigation page + - - Gets whether the title widget should be shown. - - + filename="src/adw-navigation-view.c" + line="2190">Gets the child widget of @self. + + whether the title widget should be shown. - + filename="src/adw-navigation-view.c" + line="2196">the child widget of @self + a header bar - + filename="src/adw-navigation-view.c" + line="2192">a navigation page + - - + Gets the title widget widget of @self. - + filename="src/adw-navigation-view.c" + line="2253">Gets the tag of @self. + the title widget - + filename="src/adw-navigation-view.c" + line="2259">the page tag + a header bar - + filename="src/adw-navigation-view.c" + line="2255">a navigation page + - + Adds @child to @self, packed with reference to the end of @self. - + filename="src/adw-navigation-view.c" + line="2331">Gets the title of @self. + + + the title of @self + + + + + a navigation page + + + + + + Sets whether @self can be popped from navigation stack. + +Set it to `FALSE` to disable shortcuts and gestures, as well as remove the +back button from [class@HeaderBar]. + +Manually calling [method@NavigationView.pop] or using the `navigation.pop` +action will still work. + +See [property@HeaderBar:show-back-button] for removing only the back button, +but not shortcuts. + a header bar - + filename="src/adw-navigation-view.c" + line="2410">a navigation page + - + the widget to be added to @self - + filename="src/adw-navigation-view.c" + line="2411">whether the page can be popped from navigation stack + - + Adds @child to @self, packed with reference to the start of the @self. - + filename="src/adw-navigation-view.c" + line="2212">Sets the child widget of @self. + a header bar - + filename="src/adw-navigation-view.c" + line="2214">a navigation page + - + the widget to be added to @self + filename="src/adw-navigation-view.c" + line="2215">the child widget - + Removes a child from @self. + filename="src/adw-navigation-view.c" + line="2275">Sets the tag for @self. -The child must have been added with [method@HeaderBar.pack_start], -[method@HeaderBar.pack_end] or [property@HeaderBar:title-widget]. - +The tag can be used to retrieve the page with +[method@NavigationView.find_page], as well as with +[method@NavigationView.push_by_tag], [method@NavigationView.pop_to_tag] or +[method@NavigationView.replace_with_tags]. + +Tags must be unique within each [class@NavigationView]. + +The tag also must be set to use the `navigation.push` action. + a header bar - + filename="src/adw-navigation-view.c" + line="2277">a navigation page + - + the child to remove - + filename="src/adw-navigation-view.c" + line="2278">the page tag + - - + Sets the policy for aligning the center widget. - + filename="src/adw-navigation-view.c" + line="2353">Sets the title of @self. + +It's displayed in [class@HeaderBar] instead of the window title, and used as +the tooltip on the next page's back button, as well as by screen reader. + a header bar - + filename="src/adw-navigation-view.c" + line="2355">a navigation page + - + the centering policy - + filename="src/adw-navigation-view.c" + line="2356">the title + - - + Sets the decoration layout for @self. + filename="src/adw-navigation-view.c" + line="583">Whether the page can be popped from navigation stack. -If this property is not set, the -[property@Gtk.Settings:gtk-decoration-layout] setting is used. +Set it to `FALSE` to disable shortcuts and gestures, as well as remove the +back button from [class@HeaderBar]. -The format of the string is button names, separated by commas. A colon -separates the buttons that should appear at the start from those at the end. -Recognized button names are minimize, maximize, close and icon (the window -icon). +Manually calling [method@NavigationView.pop] or using the `navigation.pop` +action will still work. -For example, “icon:minimize,maximize,close” specifies an icon at the start, -and minimize, maximize and close buttons at the end. - +See [property@HeaderBar:show-back-button] for removing only the back +button, but not shortcuts. + + + + The child widget. + + + + The page tag. + +The tag can be used to retrieve the page with +[method@NavigationView.find_page], as well as with +[method@NavigationView.push_by_tag], [method@NavigationView.pop_to_tag] or +[method@NavigationView.replace_with_tags]. + +Tags must be unique within each [class@NavigationView]. + +The tag also must be set to use the `navigation.push` action. + + + + The page title. + +It's displayed in [class@HeaderBar] instead of the window title, and used +as the tooltip on the next page's back button, as well as by screen reader. + + + + + + + Emitted when the navigation view transition has been completed and the page +is fully hidden. + +It will always be preceded by [signal@NavigationPage::hiding] or +[signal@NavigationPage::showing]. + + + + + + Emitted when the page starts hiding at the beginning of the navigation view +transition. + +It will always be followed by [signal@NavigationPage::hidden] or +[signal@NavigationPage::shown]. + + + + + + Emitted when the page shows at the beginning of the navigation view +transition. + +It will always be followed by [signal@NavigationPage::shown] or +[signal@NavigationPage::hidden]. + + + + + + Emitted when the navigation view transition has been completed and the page +is fully shown. + +It will always be preceded by [signal@NavigationPage::showing] or +[signal@NavigationPage::hiding]. + + + + + + + + + + + + + + + + a navigation page + + + + + + + + + + + + + + a navigation page + + + + + + + + + + + + + + a navigation page + + + + + + + + + + + + + + a navigation page + + + + + + + + + + + + + A widget presenting sidebar and content side by side or as a navigation view. + +<picture> + <source srcset="navigation-split-view-dark.png" media="(prefers-color-scheme: dark)"> + <img src="navigation-split-view.png" alt="navigation-split-view"> +</picture> +<picture> + <source srcset="navigation-split-view-collapsed-dark.png" media="(prefers-color-scheme: dark)"> + <img src="navigation-split-view-collapsed.png" alt="navigation-split-view-collapsed"> +</picture> + +`AdwNavigationSplitView` has two [class@NavigationPage] children: sidebar and +content, and displays them side by side. + +When [property@NavigationSplitView:collapsed] is set to `TRUE`, it instead +puts both children inside an [class@NavigationView]. The +[property@NavigationSplitView:show-content] controls which child is visible +while collapsed. + +See also [class@OverlaySplitView]. + +`AdwNavigationSplitView` is typically used together with an [class@Breakpoint] +setting the `collapsed` property to `TRUE` on small widths, as follows: + +```xml +<object class="AdwWindow"> + <property name="width-request">280</property> + <property name="height-request">200</property> + <property name="default-width">800</property> + <property name="default-height">800</property> + <child> + <object class="AdwBreakpoint"> + <condition>max-width: 400sp</condition> + <setter object="split_view" property="collapsed">True</setter> + </object> + </child> + <property name="content"> + <object class="AdwNavigationSplitView" id="split_view"> + <property name="sidebar"> + <object class="AdwNavigationPage"> + <property name="title" translatable="yes">Sidebar</property> + <property name="child"> + <!-- ... --> + </property> + </object> + </property> + <property name="content"> + <object class="AdwNavigationPage"> + <property name="title" translatable="yes">Content</property> + <property name="child"> + <!-- ... --> + </property> + </object> + </property> + </object> + </property> +</object> +``` + +## Sizing + +When not collapsed, `AdwNavigationSplitView` changes the sidebar width +depending on its own width. + +If possible, it tries to allocate a fraction of the total width, controlled +with the [property@NavigationSplitView:sidebar-width-fraction] property. + +The sidebar also has minimum and maximum sizes, controlled with the +[property@NavigationSplitView:min-sidebar-width] and +[property@NavigationSplitView:max-sidebar-width] properties. + +The minimum and maximum sizes are using the length unit specified with the +[property@NavigationSplitView:sidebar-width-unit]. + +By default, sidebar is using 25% of the total width, with 180sp as the +minimum size and 280sp as the maximum size. + +## Header Bar Integration + +When used inside `AdwNavigationSplitView`, [class@HeaderBar] will +automatically hide the window buttons in the middle. + +When collapsed, it also displays a back button for the content widget, as +well as the page titles. See [class@NavigationView] documentation for details. + +## Actions + +`AdwNavigationSplitView` defines the same actions as `AdwNavigationView`, but +they can be used even when the split view is not collapsed: + +- `navigation.push` takes a string parameter specifying the tag of the page +to push. If it matches the tag of the content widget, it sets +[property@NavigationSplitView:show-content] to `TRUE`. + +- `navigation.pop` doesn't take any parameters and sets +[property@NavigationSplitView:show-content] to `FALSE`. + +## `AdwNavigationSplitView` as `GtkBuildable` + +The `AdwNavigationSplitView` implementation of the [iface@Gtk.Buildable] +interface supports setting the sidebar widget by specifying “sidebar” as the +“type” attribute of a `<child>` element, Specifying “content” child type or +omitting it results in setting the content widget. + +## CSS nodes + +`AdwNavigationSplitView` has a single CSS node with the name +`navigation-split-view`. + +When collapsed, it contains a child node with the name `navigation-view` +containing both children. + +``` +navigation-split-view +╰── navigation-view + ├── [sidebar child] + ╰── [content child] +``` + +When not collapsed, it contains two nodes with the name `widget`, one with +the `.sidebar-pane` style class, the other one with `.content-view` style +class, containing the sidebar and content children respectively. + +``` +navigation-split-view +├── widget.sidebar-pane +│ ╰── [sidebar child] +╰── widget.content-pane + ╰── [content child] +``` + +## Accessibility + +`AdwNavigationSplitView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + + + + + Creates a new `AdwNavigationSplitView`. + + + the newly created `AdwNavigationSplitView` + + + + + Gets whether @self is collapsed. + + + whether @self is collapsed + + a header bar - + filename="src/adw-navigation-split-view.c" + line="1291">a navigation split view + - + + + + Sets the content widget for @self. + + + the content widget + + + + a decoration layout - - + filename="src/adw-navigation-split-view.c" + line="1139">a navigation split view + + - - Sets whether @self can show the back button. - -The back button will never be shown unless the header bar is placed inside an -[class@NavigationView]. Usually, there is no reason to set it to `FALSE`. - + filename="src/adw-navigation-split-view.c" + line="1463">Gets the maximum sidebar width for @self. + - + the maximum width + a header bar - + filename="src/adw-navigation-split-view.c" + line="1465">a navigation split view + - - whether to show the back button - - - - + Sets whether to show title buttons at the end of @self. - -See [property@HeaderBar:show-start-title-buttons] for the other side. - -Which buttons are actually shown and where is determined by the -[property@HeaderBar:decoration-layout] property, and by the state of the -window (e.g. a close button will not be shown if the window can't be closed). - + filename="src/adw-navigation-split-view.c" + line="1413">Gets the minimum sidebar width for @self. + - + the minimum width + a header bar - + filename="src/adw-navigation-split-view.c" + line="1415">a navigation split view + - - `TRUE` to show standard title buttons - - - - + Sets whether to show title buttons at the start of @self. - -See [property@HeaderBar:show-end-title-buttons] for the other side. - -Which buttons are actually shown and where is determined by the -[property@HeaderBar:decoration-layout] property, and by the state of the -window (e.g. a close button will not be shown if the window can't be closed). - + filename="src/adw-navigation-split-view.c" + line="1341">Gets which page is visible when @self is collapsed. + - + whether to show content when collapsed + a header bar - + filename="src/adw-navigation-split-view.c" + line="1343">a navigation split view + - - `TRUE` to show standard title buttons - - - - Sets whether the title widget should be shown. - - - + filename="src/adw-navigation-split-view.c" + line="1044">Gets the sidebar widget for @self. + + + the sidebar widget + a header bar - + filename="src/adw-navigation-split-view.c" + line="1046">a navigation split view + - - whether the title widget is visible - - - - + Sets the title widget for @self. - -When set to `NULL`, the header bar will display the title of the window it -is contained in. - -To use a different title, use [class@WindowTitle]: - -```xml -<object class="AdwHeaderBar"> - <property name="title-widget"> - <object class="AdwWindowTitle"> - <property name="title" translatable="yes">Title</property> - </object> - </property> -</object> -``` - + filename="src/adw-navigation-split-view.c" + line="1230">Gets the sidebar position for @self. + - + the sidebar position for @self + a header bar - + filename="src/adw-navigation-split-view.c" + line="1232">a navigation split view + - - a widget to use for a title - - - - - - The policy for aligning the center widget. - - - - - - The decoration layout for buttons. - -If this property is not set, the -[property@Gtk.Settings:gtk-decoration-layout] setting is used. - -The format of the string is button names, separated by commas. A colon -separates the buttons that should appear at the start from those at the -end. Recognized button names are minimize, maximize, close and icon (the -window icon). - -For example, “icon:minimize,maximize,close” specifies an icon at the start, -and minimize, maximize and close buttons at the end. - - - - - - Whether the header bar can show the back button. - -The back button will never be shown unless the header bar is placed inside an -[class@NavigationView]. Usually, there is no reason to set this to `FALSE`. - - - - - - Whether to show title buttons at the end of the header bar. - -See [property@HeaderBar:show-start-title-buttons] for the other side. - -Which buttons are actually shown and where is determined by the -[property@HeaderBar:decoration-layout] property, and by the state of the -window (e.g. a close button will not be shown if the window can't be -closed). - - - - - - Whether to show title buttons at the start of the header bar. - -See [property@HeaderBar:show-end-title-buttons] for the other side. - -Which buttons are actually shown and where is determined by the -[property@HeaderBar:decoration-layout] property, and by the state of the -window (e.g. a close button will not be shown if the window can't be -closed). - - - - - - Whether the title widget should be shown. - - - - - - The title widget to display. - -When set to `NULL`, the header bar will display the title of the window it -is contained in. - -To use a different title, use [class@WindowTitle]: - -```xml -<object class="AdwHeaderBar"> - <property name="title-widget"> - <object class="AdwWindowTitle"> - <property name="title" translatable="yes">Title</property> - </object> - </property> -</object> -``` - - - - - - - - - - - An adaptive container acting like a box or a stack. - -<picture> - <source srcset="leaflet-wide-dark.png" media="(prefers-color-scheme: dark)"> - <img src="leaflet-wide.png" alt="leaflet-wide"> -</picture> -<picture> - <source srcset="leaflet-narrow-dark.png" media="(prefers-color-scheme: dark)"> - <img src="leaflet-narrow.png" alt="leaflet-narrow"> -</picture> - -The `AdwLeaflet` widget can display its children like a [class@Gtk.Box] does -or like a [class@Gtk.Stack] does, adapting to size changes by switching -between the two modes. - -When there is enough space the children are displayed side by side, otherwise -only one is displayed and the leaflet is said to be “folded”. -The threshold is dictated by the preferred minimum sizes of the children. -When a leaflet is folded, the children can be navigated using swipe gestures. - -The “over” and “under” transition types stack the children one on top of the -other, while the “slide” transition puts the children side by side. While -navigating to a child on the side or below can be performed by swiping the -current child away, navigating to an upper child requires dragging it from -the edge where it resides. This doesn't affect non-dragging swipes. - -## CSS nodes - -`AdwLeaflet` has a single CSS node with name `leaflet`. The node will get the -style classes `.folded` when it is folded, `.unfolded` when it's not, or none -if it hasn't computed its fold yet. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - - + Creates a new `AdwLeaflet`. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1513">Gets the preferred sidebar width fraction for @self. + the new created `AdwLeaflet` - + filename="src/adw-navigation-split-view.c" + line="1519">the preferred width fraction + - - + + + a navigation split view + + + + + Adds a child to @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1564">Gets the length unit for minimum and maximum sidebar widths. + the [class@LeafletPage] for @child - + filename="src/adw-navigation-split-view.c" + line="1570">the length unit + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1566">a navigation split view + - - the widget to add - - - + Finds the previous or next navigatable child. - -This will be the same child [method@Leaflet.navigate] or swipe gestures will -navigate to. + filename="src/adw-navigation-split-view.c" + line="1307">Sets whether @self is collapsed. -If there's no child to navigate to, `NULL` will be returned instead. +When collapsed, the children are put inside an [class@NavigationView], +otherwise they are displayed side by side. -See [property@LeafletPage:navigatable]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - the previous or next child - +The [property@NavigationSplitView:show-content] controls which child is +visible while collapsed. + + + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1309">a navigation split view + - + the direction - + filename="src/adw-navigation-split-view.c" + line="1310">whether @self is collapsed + - - + Gets whether gestures and shortcuts for navigating backward are enabled. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1155">Sets the content widget for @self. + - Whether gestures and shortcuts are enabled. - + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1157">a navigation split view + + + the content widget + + - - + Gets whether gestures and shortcuts for navigating forward are enabled. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1481">Sets the maximum sidebar width for @self. + +Maximum width is affected by +[property@NavigationSplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + - Whether gestures and shortcuts are enabled. - + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1483">a navigation split view + + + the maximum width + + - - + Gets whether @self can unfold. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1431">Sets the minimum sidebar width for @self. + +Minimum width is affected by +[property@NavigationSplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + - whether @self can unfold - + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1433">a navigation split view + + + the minimum width + + - + Finds the child of @self with @name. + filename="src/adw-navigation-split-view.c" + line="1359">Sets which page is visible when @self is collapsed. -Returns `NULL` if there is no child with this name. +If set to `TRUE`, the content widget will be the visible page when +[property@NavigationSplitView:collapsed] is `TRUE`; otherwise the sidebar +widget will be visible. -See [property@LeafletPage:name]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - the requested child of @self - +If the split view is already collapsed, the visible page changes immediately. + + + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1361">a navigation split view + - + the name of the child to find - + filename="src/adw-navigation-split-view.c" + line="1362">whether to show content when collapsed + - - + Gets the child transition spring parameters for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - the child transition parameters - + filename="src/adw-navigation-split-view.c" + line="1062">Sets the sidebar widget for @self. + + + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1064">a navigation split view + + + the sidebar widget + + - - + Gets whether a child transition is currently running for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1248">Sets the sidebar position for @self. + +If set to `GTK_PACK_START`, the sidebar is displayed before the content, +and the sidebar will be the root page when collapsed. + +If set to `GTK_PACK_END`, the sidebar is displayed after the content, +and the content will be the root page. + - whether a transition is currently running - + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1250">a navigation split view + + + the new position + + - - + Gets the fold threshold policy for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="1531">Sets the preferred sidebar width as a fraction of the total width of @self. + +The preferred width is additionally limited by +[property@NavigationSplitView:min-sidebar-width] and +[property@NavigationSplitView:max-sidebar-width]. + +The sidebar widget can be allocated with larger width if its own minimum +width exceeds the preferred width. + - + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1533">a navigation split view + + + the preferred width fraction + + - - + Gets whether @self is folded. + filename="src/adw-navigation-split-view.c" + line="1582">Sets the length unit for minimum and maximum sidebar widths. -The leaflet will be folded if the size allocated to it is smaller than the -sum of the minimum or natural sizes of the children (see -[property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +See [property@NavigationSplitView:min-sidebar-width] and +[property@NavigationSplitView:max-sidebar-width]. + - whether @self is folded. - + a leaflet - + filename="src/adw-navigation-split-view.c" + line="1584">a navigation split view + + + the length unit + + - - + Gets whether @self is homogeneous. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-split-view.c" + line="868">Whether the split view is collapsed. + +When collapsed, the children are put inside an [class@NavigationView], +otherwise they are displayed side by side. + +The [property@NavigationSplitView:show-content] controls which child is +visible while collapsed. + + + + The content widget. + + + + The maximum sidebar width. + +Maximum width is affected by +[property@NavigationSplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + + + + The minimum sidebar width. + +Minimum width is affected by +[property@NavigationSplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + + + + Determines the visible page when collapsed. + +If set to `TRUE`, the content widget will be the visible page when +[property@NavigationSplitView:collapsed] is `TRUE`; otherwise the sidebar +widget will be visible. + +If the split view is already collapsed, the visible page changes +immediately. + + + + The sidebar widget. + + + + The sidebar position. + +If set to `GTK_PACK_START`, the sidebar is displayed before the content, +and the sidebar will be the root page when collapsed. + +If set to `GTK_PACK_END`, the sidebar is displayed after the content, +and the content will be the root page. + + + + The preferred sidebar width as a fraction of the total width. + +The preferred width is additionally limited by +[property@NavigationSplitView:min-sidebar-width] and +[property@NavigationSplitView:max-sidebar-width]. + +The sidebar widget can be allocated with larger width if its own minimum +width exceeds the preferred width. + + + + The length unit for minimum and maximum sidebar widths. + +See [property@NavigationSplitView:min-sidebar-width] and +[property@NavigationSplitView:max-sidebar-width]. + + + + + + + + + + + A page-based navigation container. + +<picture> + <source srcset="navigation-view-dark.png" media="(prefers-color-scheme: dark)"> + <img src="navigation-view.png" alt="navigation-view"> +</picture> + +`AdwNavigationView` presents one child at a time, similar to +[class@Gtk.Stack]. + +`AdwNavigationView` can only contain [class@NavigationPage] children. + +It maintains a navigation stack that can be controlled with +[method@NavigationView.push] and [method@NavigationView.pop]. The whole +navigation stack can also be replaced using [method@NavigationView.replace]. + +`AdwNavigationView` allows to manage pages statically or dynamically. + +Static pages can be added using the [method@NavigationView.add] method. The +`AdwNavigationView` will keep a reference to these pages, but they aren't +accessible to the user until [method@NavigationView.push] is called (except +for the first page, which is pushed automatically). Use the +[method@NavigationView.remove] method to remove them. This is useful for +applications that have a small number of unique pages and just need +navigation between them. + +Dynamic pages are automatically destroyed once they are popped off the +navigation stack. To add a page like this, push it using the +[method@NavigationView.push] method without calling +[method@NavigationView.add] first. + +## Tags + +Static pages, as well as any pages in the navigation stack, can be accessed +by their [property@NavigationPage:tag]. For example, +[method@NavigationView.push_by_tag] can be used to push a static page that's +not in the navigation stack without having to keep a reference to it manually. + +## Header Bar Integration + +When used inside `AdwNavigationView`, [class@HeaderBar] will automatically +display a back button that can be used to go back to the previous page when +possible. The button also has a context menu, allowing to pop multiple pages +at once, potentially across multiple navigation views. + +Set [property@HeaderBar:show-back-button] to `FALSE` to disable this behavior +in rare scenarios where it's unwanted. + +`AdwHeaderBar` will also display the title of the `AdwNavigationPage` it's +placed into, so most applications shouldn't need to customize it at all. + +## Shortcuts and Gestures + +`AdwNavigationView` supports the following shortcuts for going to the +previous page: + +- <kbd>Escape</kbd> (unless [property@NavigationView:pop-on-escape] is set to + `FALSE`) +- <kbd>Alt</kbd>+<kbd>←</kbd> +- Back mouse button + +Additionally, it supports interactive gestures: + +- One-finger swipe towards the right on touchscreens +- Scrolling towards the right on touchpads (usually two-finger swipe) + +These gestures have transitions enabled regardless of the +[property@NavigationView:animate-transitions] value. + +Applications can also enable shortcuts for pushing another page onto the +navigation stack via connecting to the [signal@NavigationView::get-next-page] +signal, in that case the following shortcuts are supported: + +- <kbd>Alt</kbd>+<kbd>→</kbd> +- Forward mouse button +- Swipe/scrolling towards the left + +For right-to-left locales, the gestures and shortcuts are reversed. + +[property@NavigationPage:can-pop] can be used to disable them, along with the +header bar back buttons. + +## Actions + +`AdwNavigationView` defines actions for controlling the navigation stack. +actions for controlling the navigation stack: + +- `navigation.push` takes a string parameter specifying the tag of the page to +push, and is equivalent to calling [method@NavigationView.push_by_tag]. + +- `navigation.pop` doesn't take any parameters and pops the current page from +the navigation stack, equivalent to calling [method@NavigationView.pop]. + +## `AdwNavigationView` as `GtkBuildable` + +`AdwNavigationView` allows to add pages as children, equivalent to using the +[method@NavigationView.add] method. + +Example of an `AdwNavigationView` UI definition: + +```xml +<object class="AdwNavigationView"> + <child> + <object class="AdwNavigationPage"> + <property name="title" translatable="yes">Page 1</property> + <property name="child"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"/> + </child> + <property name="content"> + <object class="GtkButton"> + <property name="label" translatable="yes">Open Page 2</property> + <property name="halign">center</property> + <property name="valign">center</property> + <property name="action-name">navigation.push</property> + <property name="action-target">'page-2'</property> + <style> + <class name="pill"/> + </style> + </object> + </property> + </object> + </property> + </object> + </child> + <child> + <object class="AdwNavigationPage"> + <property name="title" translatable="yes">Page 2</property> + <property name="tag">page-2</property> + <property name="child"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"/> + </child> + <property name="content"> + <!-- ... --> + </property> + </object> + </property> + </object> + </child> +</object> +``` + +<picture> + <source srcset="navigation-view-example-dark.png" media="(prefers-color-scheme: dark)"> + <img src="navigation-view-example.png" alt="navigation-view-example"> +</picture> + +## CSS nodes + +`AdwNavigationView` has a single CSS node with the name `navigation-view`. + +## Accessibility + +`AdwNavigationView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + + + + + + Creates a new `AdwNavigationView`. + whether @self is homogeneous - + filename="src/adw-navigation-view.c" + line="2549">the new created `AdwNavigationView` + - - - a leaflet - - - - - - + + Gets the mode transition animation duration for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="2559">Permanently adds @page to @self. + +Any page that has been added will stay in @self even after being popped from +the navigation stack. + +Adding a page while no page is visible will automatically push it to the +navigation stack. + +See [method@NavigationView.remove]. + - the mode transition duration, in milliseconds. - + a leaflet - + filename="src/adw-navigation-view.c" + line="2561">a navigation view + + + the page to add + + - + Returns the [class@LeafletPage] object for @child. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - + filename="src/adw-navigation-view.c" + line="2618">Finds a page in @self by its tag. + +See [property@NavigationPage:tag]. + + the page object for @child - + filename="src/adw-navigation-view.c" + line="2627">the page with the given tag + a leaflet - + filename="src/adw-navigation-view.c" + line="2620">a navigation view + - + a child of @self - + filename="src/adw-navigation-view.c" + line="2621">a page tag + - - + Returns a [iface@Gio.ListModel] that contains the pages of the leaflet. - -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track and change the visible -page. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - + filename="src/adw-navigation-view.c" + line="3210">Gets whether @self animates page transitions. + + a `GtkSelectionModel` for the leaflet's children - + filename="src/adw-navigation-view.c" + line="3216">whether to animate page transitions + a leaflet - + filename="src/adw-navigation-view.c" + line="3212">a navigation view + - - + Gets the type of animation used for transitions between modes and children. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="3107">Gets whether @self is horizontally homogeneous. + the current transition type of @self - + filename="src/adw-navigation-view.c" + line="3113">whether @self is horizontally homogeneous + a leaflet - + filename="src/adw-navigation-view.c" + line="3109">a navigation view + - - + Gets the widget currently visible when the leaflet is folded. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - + filename="src/adw-navigation-view.c" + line="3301">Returns a [iface@Gio.ListModel] that contains the pages in navigation stack. + +The pages are sorted from root page to visible page. + +This can be used to keep an up-to-date view. + + the visible child - + filename="src/adw-navigation-view.c" + line="3311">a list model for the navigation stack + a leaflet - + filename="src/adw-navigation-view.c" + line="3303">a navigation view + - - + Gets the name of the currently visible child widget. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - + filename="src/adw-navigation-view.c" + line="3255">Gets whether pressing Escape pops the current page on @self. + + the name of the visible child - + filename="src/adw-navigation-view.c" + line="3261">whether to pop the current page + a leaflet - + filename="src/adw-navigation-view.c" + line="3257">a navigation view + - + Inserts @child in the position after @sibling in the list of children. + filename="src/adw-navigation-view.c" + line="3068">Gets the previous page for @page. -If @sibling is `NULL`, inserts @child at the first position. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - +If @page is in the navigation stack, returns the page popping @page will +reveal. + +If @page is the root page or is not in the navigation stack, returns `NULL`. + + the [class@LeafletPage] for @child - + filename="src/adw-navigation-view.c" + line="3080">the previous page + a leaflet - + filename="src/adw-navigation-view.c" + line="3070">a navigation view + - - the widget to insert - - - + the sibling after which to insert @child - + filename="src/adw-navigation-view.c" + line="3071">a page in @self + - + Navigates to the previous or next child. - -The child must have the [property@LeafletPage:navigatable] property set to -`TRUE`, otherwise it will be skipped. - -This will be the same child as returned by -[method@Leaflet.get_adjacent_child] or navigated to via swipe gestures. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="3158">Gets whether @self is vertically homogeneous. + whether the visible child was changed + filename="src/adw-navigation-view.c" + line="3164">whether @self is vertically homogeneous a leaflet - + filename="src/adw-navigation-view.c" + line="3160">a navigation view + - - the direction - - - + Inserts @child at the first position in @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - + filename="src/adw-navigation-view.c" + line="3011">Gets the currently visible page in @self. + + the [class@LeafletPage] for @child - + filename="src/adw-navigation-view.c" + line="3017">the currently visible page + a leaflet - + filename="src/adw-navigation-view.c" + line="3013">a navigation view + - + + + + Gets the tag of the currently visible page in @self. + + + the tag of the currently visible page + + + + the widget to prepend - - + filename="src/adw-navigation-view.c" + line="3043">a navigation view + + - + Removes a child widget from @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="2706">Pops the visible page from the navigation stack. + +Does nothing if the navigation stack contains less than two pages. + +If [method@NavigationView.add] hasn't been called, the page is automatically +removed. + +[signal@NavigationView::popped] will be emitted for the current visible page. + +See [method@NavigationView.pop_to_page] and +[method@NavigationView.pop_to_tag]. + - + `TRUE` if a page has been popped + a leaflet - + filename="src/adw-navigation-view.c" + line="2708">a navigation view + - - the child to remove - - - + Moves @child to the position after @sibling in the list of children. + filename="src/adw-navigation-view.c" + line="2749">Pops pages from the navigation stack until @page is visible. -If @sibling is `NULL`, moves @child to the first position. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +@page must be in the navigation stack. + +If [method@NavigationView.add] hasn't been called for any of the popped pages, +they are automatically removed. + +[signal@NavigationView::popped] will be be emitted for each of the popped +pages. + +See [method@NavigationView.pop] and [method@NavigationView.pop_to_tag]. + - + `TRUE` if any pages have been popped + a leaflet - + filename="src/adw-navigation-view.c" + line="2751">a navigation view + - - the widget to move, must be a child of @self - - - + the sibling to move @child after - + filename="src/adw-navigation-view.c" + line="2752">the page to pop to + - - + Sets whether gestures and shortcuts for navigating backward are enabled. - -The supported gestures are: + filename="src/adw-navigation-view.c" + line="2795">Pops pages from the navigation stack until page with the tag @tag is visible. -- One-finger swipe on touchscreens -- Horizontal scrolling on touchpads (usually two-finger swipe) -- Back/forward mouse buttons +The page must be in the navigation stack. -The keyboard back/forward keys are also supported, as well as the -<kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or -<kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation. +If [method@NavigationView.add] hasn't been called for any of the popped pages, +they are automatically removed. -If the orientation is horizontal, for right-to-left locales, gestures and -shortcuts are reversed. +[signal@NavigationView::popped] will be emitted for each of the popped pages. -Only children that have [property@LeafletPage:navigatable] set to `TRUE` can -be navigated to. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +See [method@NavigationView.pop_to_page] and [property@NavigationPage:tag]. + - + `TRUE` if any pages have been popped + a leaflet - + filename="src/adw-navigation-view.c" + line="2797">a navigation view + - + the new value - + filename="src/adw-navigation-view.c" + line="2798">a page tag + - - + Sets whether gestures and shortcuts for navigating forward are enabled. - -The supported gestures are: - -- One-finger swipe on touchscreens -- Horizontal scrolling on touchpads (usually two-finger swipe) -- Back/forward mouse buttons + filename="src/adw-navigation-view.c" + line="2641">Pushes @page onto the navigation stack. -The keyboard back/forward keys are also supported, as well as the -<kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or -<kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation. +If [method@NavigationView.add] hasn't been called, the page is automatically +removed once it's popped. -If the orientation is horizontal, for right-to-left locales, gestures and -shortcuts are reversed. +[signal@NavigationView::pushed] will be emitted for @page. -Only children that have [property@LeafletPage:navigatable] set to `TRUE` can -be navigated to. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +See [method@NavigationView.push_by_tag]. + a leaflet - + filename="src/adw-navigation-view.c" + line="2643">a navigation view + - + the new value - + filename="src/adw-navigation-view.c" + line="2644">the page to push + - - + Sets whether @self can unfold. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="2670">Pushes the page with the tag @tag onto the navigation stack. + +If [method@NavigationView.add] hasn't been called, the page is automatically +removed once it's popped. + +[signal@NavigationView::pushed] will be emitted for the page. + +See [method@NavigationView.push] and [property@NavigationPage:tag]. + a leaflet - + filename="src/adw-navigation-view.c" + line="2672">a navigation view + - + whether @self can unfold - + filename="src/adw-navigation-view.c" + line="2673">the page tag + - - + Sets the child transition spring parameters for @self. + filename="src/adw-navigation-view.c" + line="2593">Removes @page from @self. -The default value is equivalent to: +If @page is currently in the navigation stack, it will be removed once it's +popped. Otherwise, it's removed immediately. -```c -adw_spring_params_new (1, 0.5, 500) -``` - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +See [method@NavigationView.add]. + a leaflet - + filename="src/adw-navigation-view.c" + line="2595">a navigation view + - + the new parameters - + filename="src/adw-navigation-view.c" + line="2596">the page to remove + - - + Sets the fold threshold policy for @self. + filename="src/adw-navigation-view.c" + line="2835">Replaces the current navigation stack with @pages. -If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the -children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it -will fold as soon as children don't get their natural size. +The last page becomes the visible page. -This can be useful if you have a long ellipsizing label and want to let it -ellipsize instead of immediately folding. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +Replacing the navigation stack has no animation. + +If [method@NavigationView.add] hasn't been called for any pages that are no +longer in the navigation stack, they are automatically removed. + +@n_pages can be 0, in that case no page will be visible after calling this +method. This can be useful for removing all pages from @self. + +The [signal@NavigationView::replaced] signal will be emitted. + +See [method@NavigationView.replace_with_tags]. + a leaflet - + filename="src/adw-navigation-view.c" + line="2837">a navigation view + - + the policy to use - + filename="src/adw-navigation-view.c" + line="2838">the new navigation stack + + + + + + the number of pages in @pages + - - + Sets @self to be homogeneous or not. + filename="src/adw-navigation-view.c" + line="2955">Replaces the current navigation stack with pages with the tags @tags. + +The last page becomes the visible page. + +Replacing the navigation stack has no animation. + +If [method@NavigationView.add] hasn't been called for any pages that are no +longer in the navigation stack, they are automatically removed. -If set to `FALSE`, different children can have different size along the -opposite orientation. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +@n_tags can be 0, in that case no page will be visible after calling this +method. This can be useful for removing all pages from @self. + +The [signal@NavigationView::replaced] signal will be emitted. + +See [method@NavigationView.replace] and [property@NavigationPage:tag]. + a leaflet - + filename="src/adw-navigation-view.c" + line="2957">a navigation view + - + whether to make @self homogeneous - + filename="src/adw-navigation-view.c" + line="2958">tags of the pages in the + navigation stack + + + + + + the number of tags + - - + Sets the mode transition animation duration for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="3228">Sets whether @self should animate page transitions. + +Gesture-based transitions are always animated. + a leaflet - + filename="src/adw-navigation-view.c" + line="3230">a navigation view + - + the new duration, in milliseconds - + filename="src/adw-navigation-view.c" + line="3231">whether to animate page transitions + - - + Sets the type of animation used for transitions between modes and children. + filename="src/adw-navigation-view.c" + line="3125">Sets @self to be horizontally homogeneous or not. -The transition type can be changed without problems at runtime, so it is -possible to change the animation based on the mode or child that is about to -become current. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +If the view is horizontally homogeneous, it allocates the same width for +all pages. + +If it's not, the view may change width when a different page becomes visible. + a leaflet - + filename="src/adw-navigation-view.c" + line="3127">a navigation view + - + the new transition type - + filename="src/adw-navigation-view.c" + line="3128">whether to make @self horizontally homogeneous + - - + Sets the widget currently visible when the leaflet is folded. + filename="src/adw-navigation-view.c" + line="3273">Sets whether pressing Escape pops the current page on @self. -The transition is determined by [property@Leaflet:transition-type] and -[property@Leaflet:child-transition-params]. The transition can be cancelled -by the user, in which case visible child will change back to the previously -visible child. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +Applications using `AdwNavigationView` to implement a browser may want to +disable it. + a leaflet - + filename="src/adw-navigation-view.c" + line="3275">a navigation view + - + the new child - + filename="src/adw-navigation-view.c" + line="3276">whether to pop the current page when pressing Escape + - - + Makes the child with the name @name visible. + filename="src/adw-navigation-view.c" + line="3176">Sets @self to be vertically homogeneous or not. -See [property@Leaflet:visible-child]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +If the view is vertically homogeneous, it allocates the same height for +all pages. + +If it's not, the view may change height when a different page becomes +visible. + a leaflet - + filename="src/adw-navigation-view.c" + line="3178">a navigation view + - + the name of a child - + filename="src/adw-navigation-view.c" + line="3179">whether to make @self vertically homogeneous + - - - + setter="set_animate_transitions" + getter="get_animate_transitions" + default-value="TRUE"> Whether gestures and shortcuts for navigating backward are enabled. - -The supported gestures are: - -- One-finger swipe on touchscreens -- Horizontal scrolling on touchpads (usually two-finger swipe) -- Back/forward mouse buttons - -The keyboard back/forward keys are also supported, as well as the -<kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or -<kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation. - -If the orientation is horizontal, for right-to-left locales, gestures and -shortcuts are reversed. + filename="src/adw-navigation-view.c" + line="1824">Whether to animate page transitions. -Only children that have [property@LeafletPage:navigatable] set to `TRUE` -can be navigated to. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) +Gesture-based transitions are always animated. - - - - Whether gestures and shortcuts for navigating forward are enabled. - -The supported gestures are: - -- One-finger swipe on touchscreens -- Horizontal scrolling on touchpads (usually two-finger swipe) -- Back/forward mouse buttons - -The keyboard back/forward keys are also supported, as well as the -<kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or -<kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation. - -If the orientation is horizontal, for right-to-left locales, gestures and -shortcuts are reversed. - -Only children that have [property@LeafletPage:navigatable] set to `TRUE` -can be navigated to. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - Whether or not the leaflet can unfold. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - The child transition spring parameters. + filename="src/adw-navigation-view.c" + line="1788">Whether the view is horizontally homogeneous. -The default value is equivalent to: +If the view is horizontally homogeneous, it allocates the same width for +all pages. -```c -adw_spring_params_new (1, 0.5, 500) -``` - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - Whether a child transition is currently running. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) +If it's not, the page may change width when a different page becomes +visible. - - - + getter="get_navigation_stack"> Determines when the leaflet will fold. - -If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the -children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it -will fold as soon as children don't get their natural size. + filename="src/adw-navigation-view.c" + line="1853">A list model that contains the pages in navigation stack. -This can be useful if you have a long ellipsizing label and want to let it -ellipsize instead of immediately folding. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - Whether the leaflet is folded. +The pages are sorted from root page to visible page. -The leaflet will be folded if the size allocated to it is smaller than the -sum of the minimum or natural sizes of the children (see -[property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - +This can be used to keep an up-to-date view. + - - - Whether the leaflet allocates the same size for all children when folded. + filename="src/adw-navigation-view.c" + line="1838">Whether pressing Escape pops the current page. -If set to `FALSE`, different children can have different size along the -opposite orientation. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) +Applications using `AdwNavigationView` to implement a browser may want to +disable it. - - - - The mode transition animation duration, in milliseconds. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - A selection model with the leaflet's pages. - -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track and change the visible -page. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - The type of animation used for transitions between modes and children. - -The transition type can be changed without problems at runtime, so it is -possible to change the animation based on the mode or child that is about -to become current. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - The widget currently visible when the leaflet is folded. - -The transition is determined by [property@Leaflet:transition-type] and -[property@Leaflet:child-transition-params]. The transition can be cancelled -by the user, in which case visible child will change back to the previously -visible child. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - The name of the widget currently visible when the leaflet is folded. - -See [property@Leaflet:visible-child]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - - - - - - An auxiliary class used by [class@Leaflet]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - Gets the leaflet child to which @self belongs. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - the child to which @self belongs - - - - - a leaflet page - - - - - - - Gets the name of @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - the name of @self. - - - - - a leaflet page - - - - - - - Gets whether the child can be navigated to when folded. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - whether @self can be navigated to when folded - - - - - a leaflet page - - - - - - - Sets the name of the @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - - a leaflet page - - - - the new value to set - - - - - - + setter="set_vhomogeneous" + getter="get_vhomogeneous" + default-value="FALSE"> Sets whether @self can be navigated to when folded. + filename="src/adw-navigation-view.c" + line="1806">Whether the view is vertically homogeneous. -If `FALSE`, the child will be ignored by [method@Leaflet.get_adjacent_child], -[method@Leaflet.navigate], and swipe gestures. +If the view is vertically homogeneous, it allocates the same height for +all pages. -This can be used used to prevent switching to widgets like separators. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - - a leaflet page - - - - whether @self can be navigated to when folded - - - - - + + + - + getter="get_visible_page"> The leaflet child to which the page belongs. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - + filename="src/adw-navigation-view.c" + line="1764">The currently visible page. + - - - The name of the child page. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) + filename="src/adw-navigation-view.c" + line="1776">The tag of the currently visible page. - - - + Whether the child can be navigated to when folded. + filename="src/adw-navigation-view.c" + line="1944">Emitted when a push shortcut or a gesture is triggered. -If `FALSE`, the child will be ignored by -[method@Leaflet.get_adjacent_child], [method@Leaflet.navigate], and swipe -gestures. +To support the push shortcuts and gestures, the application is expected to +return the page to push in the handler. -This can be used used to prevent switching to widgets like separators. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - - - - - - - - - - Describes the possible transitions in a [class@Leaflet] widget. +This signal can be emitted multiple times for the gestures, for example +when the gesture is cancelled by the user. As such, the application must +not make any irreversible changes in the handler, such as removing the page +from a forward stack. -New values may be added to this enumeration over time. - See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) - - Cover the old page or uncover the new page, sliding from or towards the end according to orientation, text direction and children order - - - Uncover the new page or cover the old page, sliding from or towards the start according to orientation, text direction and children order - - +Instead, it should be done in the [signal@NavigationView::pushed] handler. + + the page to push + + + + Slide from left, right, up or down according to the orientation, text direction and the children order - - - - Describes length units. + filename="src/adw-navigation-view.c" + line="1893">Emitted after @page has been popped from the navigation stack. -| Unit | Regular Text | Large Text | -| ---- | ------------ | ---------- | -| 1px | 1px | 1px | -| 1pt | 1.333333px | 1.666667px | -| 1sp | 1px | 1.25px | +See [method@NavigationView.pop]. -New values may be added to this enumeration over time. - - pixels - - - points, changes with text scale factor - - - scale independent pixels, changes with text scale factor - - - Converts @value from pixels to @unit. - +When using [method@NavigationView.pop_to_page] or +[method@NavigationView.pop_to_tag], this signal is emitted for each of the +popped pages. - the length in @unit - + - - a length unit - - - - a value in pixels - - - + settings to use, or `NULL` for default settings - + filename="src/adw-navigation-view.c" + line="1896">the popped page + - - + + Converts @value from @unit to pixels. - + filename="src/adw-navigation-view.c" + line="1871">Emitted after a page has been pushed to the navigation stack. + +See [method@NavigationView.push]. - the length in pixels - + - - - a length unit - - - - a value in @unit - - - - settings to use, or `NULL` for default settings - - - - - - - Adwaita major version component (e.g. 1 if the version is 1.2.3). - - - - - Adwaita micro version component (e.g. 3 if the version is 1.2.3). - - - - - Adwaita minor version component (e.g. 2 if the version is 1.2.3). - - - - + + + Emitted after the navigation stack has been replaced. + +See [method@NavigationView.replace]. + + + + + + + + + + + + A dialog presenting a message or a question. + filename="src/adw-overlay-split-view.c" + line="23">A widget presenting sidebar and content side by side or as an overlay. <picture> - <source srcset="message-dialog-dark.png" media="(prefers-color-scheme: dark)"> - <img src="message-dialog.png" alt="message-dialog"> + <source srcset="overlay-split-view-dark.png" media="(prefers-color-scheme: dark)"> + <img src="overlay-split-view.png" alt="overlay-split-view"> +</picture> +<picture> + <source srcset="overlay-split-view-collapsed-dark.png" media="(prefers-color-scheme: dark)"> + <img src="overlay-split-view-collapsed.png" alt="overlay-split-view-collapsed"> </picture> -Message dialogs have a heading, a body, an optional child widget, and one or -multiple responses, each presented as a button. - -Each response has a unique string ID, and a button label. Additionally, each -response can be enabled or disabled, and can have a suggested or destructive -appearance. - -When one of the responses is activated, or the dialog is closed, the -[signal@MessageDialog::response] signal will be emitted. This signal is -detailed, and the detail, as well as the `response` parameter will be set to -the ID of the activated response, or to the value of the -[property@MessageDialog:close-response] property if the dialog had been -closed without activating any of the responses. - -Response buttons can be presented horizontally or vertically depending on -available space. - -When a response is activated, `AdwMessageDialog` is closed automatically. - -An example of using a message dialog: +`AdwOverlaySplitView` has two children: sidebar and content, and displays +them side by side. -```c -GtkWidget *dialog; +When [property@OverlaySplitView:collapsed] is set to `TRUE`, the sidebar is +instead shown as an overlay above the content widget. -dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL); +The sidebar can be hidden or shown using the +[property@OverlaySplitView:show-sidebar] property. -adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), - _("A file named “%s” already exists. Do you want to replace it?"), - filename); +Sidebar can be displayed before or after the content, this can be controlled +with the [property@OverlaySplitView:sidebar-position] property. -adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), - "cancel", _("_Cancel"), - "replace", _("_Replace"), - NULL); +Collapsing the split view automatically hides the sidebar widget, and +uncollapsing it shows the sidebar. If this behavior is not desired, the +[property@OverlaySplitView:pin-sidebar] property can be used to override it. -adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); +`AdwOverlaySplitView` supports an edge swipe gesture for showing the sidebar, +and a swipe from the sidebar for hiding it. Gestures are only supported on +touchscreen, but not touchpad. Gestures can be controlled with the +[property@OverlaySplitView:enable-show-gesture] and +[property@OverlaySplitView:enable-hide-gesture] properties. -adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); -adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); +See also [class@NavigationSplitView]. -g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self); +`AdwOverlaySplitView` is typically used together with an [class@Breakpoint] +setting the `collapsed` property to `TRUE` on small widths, as follows: -gtk_window_present (GTK_WINDOW (dialog)); +```xml +<object class="AdwWindow"> + <property name="default-width">800</property> + <property name="default-height">800</property> + <child> + <object class="AdwBreakpoint"> + <condition>max-width: 400sp</condition> + <setter object="split_view" property="collapsed">True</setter> + </object> + </child> + <property name="content"> + <object class="AdwOverlaySplitView" id="split_view"> + <property name="sidebar"> + <!-- ... --> + </property> + <property name="content"> + <!-- ... --> + </property> + </object> + </property> +</object> ``` -## Async API +`AdwOverlaySplitView` is often used for implementing the +[utility pane](https://developer.gnome.org/hig/patterns/containers/utility-panes.html) +pattern. -`AdwMessageDialog` can also be used via the [method@MessageDialog.choose] -method. This API follows the GIO async pattern, and the result can be -obtained by calling [method@MessageDialog.choose_finish], for example: +## Sizing -```c -static void -dialog_cb (AdwMessageDialog *dialog, - GAsyncResult *result, - MyWindow *self) -{ - const char *response = adw_message_dialog_choose_finish (dialog, result); +When not collapsed, `AdwOverlaySplitView` changes the sidebar width +depending on its own width. - // ... -} +If possible, it tries to allocate a fraction of the total width, controlled +with the [property@OverlaySplitView:sidebar-width-fraction] property. -static void -show_dialog (MyWindow *self) -{ - GtkWidget *dialog; +The sidebar also has minimum and maximum sizes, controlled with the +[property@OverlaySplitView:min-sidebar-width] and +[property@OverlaySplitView:max-sidebar-width] properties. - dialog = adw_message_dialog_new (GTK_WINDOW (self), _("Replace File?"), NULL); +The minimum and maximum sizes are using the length unit specified with the +[property@OverlaySplitView:sidebar-width-unit]. - adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), - _("A file named “%s” already exists. Do you want to replace it?"), - filename); +By default, sidebar is using 25% of the total width, with 180sp as the +minimum size and 280sp as the maximum size. - adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), - "cancel", _("_Cancel"), - "replace", _("_Replace"), - NULL); +When collapsed, the preferred width fraction is ignored and the sidebar uses +[property@OverlaySplitView:max-sidebar-width] when possible. - adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); +## Header Bar Integration - adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); - adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); +When used inside `AdwOverlaySplitView`, [class@HeaderBar] will automatically +hide the window buttons in the middle. - adw_message_dialog_choose (ADW_MESSAGE_DIALOG (dialog), NULL, (GAsyncReadyCallback) dialog_cb, self); -} -``` +## `AdwOverlaySplitView` as `GtkBuildable` -## AdwMessageDialog as GtkBuildable +The `AdwOverlaySplitView` implementation of the [iface@Gtk.Buildable] +interface supports setting the sidebar widget by specifying “sidebar” as the +“type” attribute of a `<child>` element, Specifying “content” child type or +omitting it results in setting the content widget. -`AdwMessageDialog` supports adding responses in UI definitions by via the -`<responses>` element that may contain multiple `<response>` elements, each -respresenting a response. +## CSS nodes -Each of the `<response>` elements must have the `id` attribute specifying the -response ID. The contents of the element are used as the response label. +`AdwOverlaySplitView` has a single CSS node with the name +`overlay-split-view`. -Response labels can be translated with the usual `translatable`, `context` -and `comments` attributes. +It contains two nodes with the name `widget`, containing the sidebar and +content children. -The `<response>` elements can also have `enabled` and/or `appearance` -attributes. See [method@MessageDialog.set_response_enabled] and -[method@MessageDialog.set_response_appearance] for details. +When not collapsed, they have the `.sidebar-view` and `.content-view` style +classes respectively. -Example of an `AdwMessageDialog` UI definition: +``` +overlay-split-view +├── widget.sidebar-pane +│ ╰── [sidebar child] +╰── widget.content-pane + ╰── [content child] +``` + +When collapsed, the one containing the sidebar child has the `.background` +style class and the other one has no style classes. -```xml -<object class="AdwMessageDialog" id="dialog"> - <property name="heading" translatable="yes">Save Changes?</property> - <property name="body" translatable="yes">Open documents contain unsaved changes. Changes which are not saved will be permanently lost.</property> - <property name="default-response">save</property> - <property name="close-response">cancel</property> - <signal name="response" handler="response_cb"/> - <responses> - <response id="cancel" translatable="yes">_Cancel</response> - <response id="discard" translatable="yes" appearance="destructive">_Discard</response> - <response id="save" translatable="yes" appearance="suggested" enabled="false">_Save</response> - </responses> -</object> +``` +overlay-split-view +├── widget.background +│ ╰── [sidebar child] +╰── widget + ╰── [content child] ``` ## Accessibility -`AdwMessageDialog` uses the `GTK_ACCESSIBLE_ROLE_DIALOG` role. - +`AdwOverlaySplitView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + - - - + c:identifier="adw_overlay_split_view_new" + version="1.4"> Creates a new `AdwMessageDialog`. - -@heading and @body can be set to `NULL`. This can be useful if they need to -be formatted or use markup. In that case, set them to `NULL` and call -[method@MessageDialog.format_body] or similar methods afterwards: - -```c -GtkWidget *dialog; - -dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL); -adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), - _("A file named “%s” already exists. Do you want to replace it?"), - filename); -``` - + filename="src/adw-overlay-split-view.c" + line="1306">Creates a new `AdwOverlaySplitView`. + + + the newly created `AdwOverlaySplitView` + + + + + Gets whether @self is collapsed. + the newly created `AdwMessageDialog` + filename="src/adw-overlay-split-view.c" + line="1419">whether @self is collapsed + + + + + an overlay split view + + + + + + Gets the content widget for @self. + + + the content widget for @self - - transient parent - - - - the heading - - - + the body text - - + filename="src/adw-overlay-split-view.c" + line="1370">an overlay split view + + - - - + + Emits the [signal@MessageDialog::response] signal with the given response ID. - -Used to indicate that the user has responded to the dialog in some way. - + filename="src/adw-overlay-split-view.c" + line="1675">Gets whether @self can be closed with a swipe gesture. + - + `TRUE` if @self can be closed with a swipe gesture + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1677">an overlay split view + - - response ID - - - - + + Adds a response with @id and @label to @self. - -Responses are represented as buttons in the dialog. - -Response ID must be unique. It will be used in -[signal@MessageDialog::response] to tell which response had been activated, -as well as to inspect and modify the response later. - -An embedded underline in @label indicates a mnemonic. - -[method@MessageDialog.set_response_label] can be used to change the response -label after it had been added. - -[method@MessageDialog.set_response_enabled] and -[method@MessageDialog.set_response_appearance] can be used to customize the -responses further. - + filename="src/adw-overlay-split-view.c" + line="1628">Gets whether @self can be opened with an edge swipe gesture. + - + `TRUE` if @self can be opened with a swipe gesture + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1630">an overlay split view + - - the response ID - - - - the response label - - - + Adds multiple responses to @self. - -This is the same as calling [method@MessageDialog.add_response] repeatedly. -The variable argument list should be `NULL`-terminated list of response IDs -and labels. - -Example: - -```c -adw_message_dialog_add_responses (dialog, - "cancel", _("_Cancel"), - "discard", _("_Discard"), - "save", _("_Save"), - NULL); -``` - + filename="src/adw-overlay-split-view.c" + line="1770">Gets the maximum sidebar width for @self. + - + the maximum width + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1772">an overlay split view + - - response id - - - - label for first response, then more id-label pairs - - - + This function shows @self to the user. - -The @callback will be called when the alert is dismissed. It should call -[method@MessageDialog.choose_finish] to obtain the result. - + filename="src/adw-overlay-split-view.c" + line="1722">Gets the minimum sidebar width for @self. + - + the minimum width + - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1724">an overlay split view + - - a `GCancellable` to cancel the operation - - - - a callback to call when the operation is complete - - - - data to pass to @callback - - - + Finishes the [method@MessageDialog.choose] call and returns the response ID. - + filename="src/adw-overlay-split-view.c" + line="1581">Gets whether the sidebar widget is pinned for @self. + the ID of the response that was selected, or - [property@MessageDialog:close-response] if the call was cancelled. - + filename="src/adw-overlay-split-view.c" + line="1587">whether if the sidebar widget is pinned + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1583">an overlay split view + - - a `GAsyncResult` - - - + Sets the formatted body text of @self. - -See [property@MessageDialog:body]. - + filename="src/adw-overlay-split-view.c" + line="1545">Gets whether the sidebar widget is shown for @self. + - + `TRUE` if the sidebar widget is shown + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1547">an overlay split view + - - the formatted string for the body text - - - + + + + Gets the sidebar widget for @self. + + + the sidebar widget for @self + + + + the parameters to insert into @format - - + filename="src/adw-overlay-split-view.c" + line="1323">an overlay split view + + - + Sets the formatted body text of @self with Pango markup. - -The @format is assumed to contain Pango markup. - -Special XML characters in the `printf()` arguments passed to this function -will automatically be escaped as necessary, see -[func@GLib.markup_printf_escaped]. - -See [property@MessageDialog:body]. - + filename="src/adw-overlay-split-view.c" + line="1490">Gets the sidebar position for @self. + - + the sidebar position for @self + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1492">an overlay split view + - - the formatted string for the body text with Pango markup - - - - the parameters to insert into @format - - - + Sets the formatted heading of @self. - -See [property@MessageDialog:heading]. - + filename="src/adw-overlay-split-view.c" + line="1818">Gets the preferred sidebar width fraction for @self. + - + the preferred width fraction + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1820">an overlay split view + - - the formatted string for the heading - - - - the parameters to insert into @format - - - + Sets the formatted heading of @self with Pango markup. - -The @format is assumed to contain Pango markup. - -Special XML characters in the `printf()` arguments passed to this function -will automatically be escaped as necessary, see -[func@GLib.markup_printf_escaped]. - -See [property@MessageDialog:heading]. - + filename="src/adw-overlay-split-view.c" + line="1869">Gets the length unit for minimum and maximum sidebar widths. + - + the length unit + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1871">an overlay split view + - - the formatted string for the heading with Pango markup - - - - the parameters to insert into @format - - - - + Gets the body text of @self. - + filename="src/adw-overlay-split-view.c" + line="1431">Sets whether @self view is collapsed. + +When collapsed, the sidebar widget is presented as an overlay above the +content widget, otherwise they are displayed side by side. + - the body of @self. - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1433">an overlay split view + + + whether @self is collapsed + + - - + Gets whether the body text of @self includes Pango markup. - + filename="src/adw-overlay-split-view.c" + line="1386">Sets the content widget for @self. + - whether @self uses markup for body text - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1388">an overlay split view + + + the content widget + + - - + Gets the ID of the close response of @self. - + filename="src/adw-overlay-split-view.c" + line="1693">Sets whether @self can be closed with a swipe gesture. + +Only touchscreen swipes are supported. + - the close response ID - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1695">an overlay split view + + + whether @self can be closed with a swipe gesture + + - - + Gets the ID of the default response of @self. - - - the default response ID - + filename="src/adw-overlay-split-view.c" + line="1646">Sets whether @self can be opened with an edge swipe gesture. + +Only touchscreen swipes are supported. + + + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1648">an overlay split view + + + whether @self can be opened with a swipe gesture + + - - + Gets the child widget of @self. - - - the child widget of @self. - + filename="src/adw-overlay-split-view.c" + line="1788">Sets the maximum sidebar width for @self. + +Maximum width is affected by [property@OverlaySplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + + + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1790">an overlay split view + + + the maximum width + + - - + Gets the heading of @self. - - - the heading of @self. - + filename="src/adw-overlay-split-view.c" + line="1740">Sets the minimum sidebar width for @self. + +Minimum width is affected by [property@OverlaySplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + + + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1742">an overlay split view + + + the minimum width + + - - + Gets whether the heading of @self includes Pango markup. - + filename="src/adw-overlay-split-view.c" + line="1599">Sets whether the sidebar widget is pinned for @self. + +By default, collapsing @self automatically hides the sidebar widget, and +uncollapsing it shows the sidebar. If set to `TRUE`, sidebar visibility never +changes on its own. + - whether @self uses markup for heading - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1601">an overlay split view + + + whether to pin the sidebar widget + + - + Gets the appearance of @response. - -See [method@MessageDialog.set_response_appearance]. - + filename="src/adw-overlay-split-view.c" + line="1563">Sets whether the sidebar widget is shown for @self. + - the appearance of @response - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1565">an overlay split view + - + a response ID - + filename="src/adw-overlay-split-view.c" + line="1566">whether to show the sidebar widget + - + Gets whether @response is enabled. - -See [method@MessageDialog.set_response_enabled]. - + filename="src/adw-overlay-split-view.c" + line="1339">Sets the sidebar widget for @self. + - whether @response is enabled - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1341">an overlay split view + - + a response ID - + filename="src/adw-overlay-split-view.c" + line="1342">the sidebar widget + - + Gets the label of @response. + filename="src/adw-overlay-split-view.c" + line="1508">Sets the sidebar position for @self. -See [method@MessageDialog.set_response_label]. - +If it's set to `GTK_PACK_START`, the sidebar is displayed before the content, +if `GTK_PACK_END`, it's displayed after the content. + - the label of @response - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1510">an overlay split view + - + a response ID - + filename="src/adw-overlay-split-view.c" + line="1511">the new position + - + Gets whether @self has a response with the ID @response. - + filename="src/adw-overlay-split-view.c" + line="1836">Sets the preferred sidebar width as a fraction of the total width of @self. + +The preferred width is additionally limited by +[property@OverlaySplitView:min-sidebar-width] and +[property@OverlaySplitView:max-sidebar-width]. + +The sidebar widget can be allocated with larger width if its own minimum +width exceeds the preferred width. + - whether @self has a response with the ID @response. - + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1838">an overlay split view + - + response ID - + filename="src/adw-overlay-split-view.c" + line="1839">the preferred width fraction + - - + Emits the [signal@MessageDialog::response] signal with the given response ID. + filename="src/adw-overlay-split-view.c" + line="1887">Sets the length unit for minimum and maximum sidebar widths. -Used to indicate that the user has responded to the dialog in some way. - +See [property@OverlaySplitView:min-sidebar-width] and +[property@OverlaySplitView:max-sidebar-width]. + a message dialog - + filename="src/adw-overlay-split-view.c" + line="1889">an overlay split view + - + response ID - + filename="src/adw-overlay-split-view.c" + line="1890">the length unit + - - + Sets the body text of @self. - + filename="src/adw-overlay-split-view.c" + line="943">Whether the split view is collapsed. + +When collapsed, the sidebar widget is presented as an overlay above the +content widget, otherwise they are displayed side by side. + + + + The content widget. + + + + Whether the sidebar can be closed with a swipe gesture. + +Only touchscreen swipes are supported. + + + + Whether the sidebar can be opened with an edge swipe gesture. + +Only touchscreen swipes are supported. + + + + The maximum sidebar width. + +Maximum width is affected by +[property@OverlaySplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + + + + The minimum sidebar width. + +Minimum width is affected by +[property@OverlaySplitView:sidebar-width-unit]. + +The sidebar widget can still be allocated with larger width if its own +minimum width exceeds it. + + + + Whether the sidebar widget is pinned. + +By default, collapsing @self automatically hides the sidebar widget, and +uncollapsing it shows the sidebar. If set to `TRUE`, sidebar visibility +never changes on its own. + + + + Whether the sidebar widget is shown. + + + + The sidebar widget. + + + + The sidebar position. + +If it's set to `GTK_PACK_START`, the sidebar is displayed before the content, +if `GTK_PACK_END`, it's displayed after the content. + + + + The preferred sidebar width as a fraction of the total width. + +The preferred width is additionally limited by +[property@OverlaySplitView:min-sidebar-width] and +[property@OverlaySplitView:max-sidebar-width]. + +The sidebar widget can be allocated with larger width if its own minimum +width exceeds the preferred width. + + + + The length unit for minimum and maximum sidebar widths. + +See [property@OverlaySplitView:min-sidebar-width] and +[property@OverlaySplitView:max-sidebar-width]. + + + + + + + + + + + Describes child packing behavior in a [class@WrapLayout] or [class@WrapBox]. + +See [property@WrapLayout:pack-direction] and +[property@WrapBox:pack-direction]. + + Pack children from left to right for LTR languages, + or top to bottom vertically. + + + Pack children from right to left for LTR languages, + or bottom to top vertically. + + + + A [class@EntryRow] tailored for entering secrets. + +<picture> + <source srcset="password-entry-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="password-entry-row.png" alt="password-entry-row"> +</picture> + +It does not show its contents in clear text, does not allow to copy it to the +clipboard, and shows a warning when Caps Lock is engaged. If the underlying +platform allows it, `AdwPasswordEntryRow` will also place the text in a +non-pageable memory area, to avoid it being written out to disk by the +operating system. + +It offer a way to reveal the contents in clear text. + +## CSS Nodes + +`AdwPasswordEntryRow` has a single CSS node with name `row` that carries +`.entry` and `.password` style classes. + + + + + + + + Creates a new `AdwPasswordEntryRow`. + + + the newly created `AdwPasswordEntryRow` + + + + + + + + + + + + A dialog showing application's preferences. + +<picture> + <source srcset="preferences-dialog-dark.png" media="(prefers-color-scheme: dark)"> + <img src="preferences-dialog.png" alt="preferences-dialog"> +</picture> + +The `AdwPreferencesDialog` widget presents an application's preferences +gathered into pages and groups. The preferences are searchable by the user. + +## Actions + +`AdwPrefencesDialog` defines the `navigation.pop` action, it doesn't take any +parameters and pops the current subpage from the navigation stack, equivalent +to calling [method@PreferencesDialog.pop_subpage]. + +## CSS nodes + +`AdwPreferencesDialog` has a main CSS node with the name `dialog` and the +style class `.preferences`. + + + + + + + Creates a new `AdwPreferencesDialog`. + + + the newly created `AdwPreferencesDialog` + + + + + Adds a preferences page to @self. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="656">a preferences dialog + - + the body of @self - + filename="src/adw-preferences-dialog.c" + line="657">the page to add + - - + Sets whether the body text of @self includes Pango markup. + filename="src/adw-preferences-dialog.c" + line="912">Displays @toast. -See [func@Pango.parse_markup]. - +See [method@ToastOverlay.add_toast]. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="914">a preferences dialog + - + whether to use markup for body text - + filename="src/adw-preferences-dialog.c" + line="915">a toast + - - + Sets the ID of the close response of @self. - -It will be passed to [signal@MessageDialog::response] if the window is -closed by pressing <kbd>Escape</kbd> or with a system action. - -It doesn't have to correspond to any of the responses in the dialog. - -The default close response is `close`. - + filename="src/adw-preferences-dialog.c" + line="807">Gets whether search is enabled for @self. + - + whether search is enabled for @self. + + + + + a preferences dialog + + + + + + Gets the currently visible page of @self. + + + the visible page + a message dialog - + filename="src/adw-preferences-dialog.c" + line="718">a preferences dialog + - - the close response ID - - - - + Sets the ID of the default response of @self. - -If set, pressing <kbd>Enter</kbd> will activate the corresponding button. - -If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd> -will do nothing. - - - + filename="src/adw-preferences-dialog.c" + line="761">Gets the name of currently visible page of @self. + + + the name of the visible page + a message dialog - + filename="src/adw-preferences-dialog.c" + line="763">a preferences dialog + - - the default response ID - - - - + Sets the child widget of @self. - -The child widget is displayed below the heading and body. - + filename="src/adw-preferences-dialog.c" + line="890">Pop the visible page from the subpage stack of @self. + - + `TRUE` if a page has been popped + a message dialog - + filename="src/adw-preferences-dialog.c" + line="892">a preferences dialog + - - the child widget - - - - + Sets the heading of @self. - + filename="src/adw-preferences-dialog.c" + line="865">Pushes @page onto the subpage stack of @self. + +The page will be automatically removed when popped. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="867">a preferences dialog + - + the heading of @self - + filename="src/adw-preferences-dialog.c" + line="868">the subpage + - - + Sets whether the heading of @self includes Pango markup. - -See [func@Pango.parse_markup]. - + filename="src/adw-preferences-dialog.c" + line="688">Removes a page from @self. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="690">a preferences dialog + - + whether to use markup for heading - + filename="src/adw-preferences-dialog.c" + line="691">the page to remove + - + Sets the appearance for @response. - -<picture> - <source srcset="message-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)"> - <img src="message-dialog-appearance.png" alt="message-dialog-appearance"> -</picture> - -Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the -affirmative action, like the Save button in the example. - -Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging -consequences of using @response. This appearance acts as a warning to the -user. The Discard button in the example is using this appearance. - -The default appearance is `ADW_RESPONSE_DEFAULT`. - -Negative responses like Cancel or Close should use the default appearance. - + filename="src/adw-preferences-dialog.c" + line="829">Sets whether search is enabled for @self. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="831">a preferences dialog + - - a response ID - - - + appearance for @response - + filename="src/adw-preferences-dialog.c" + line="832">whether search is enabled + - + Sets whether @response is enabled. - -If @response is not enabled, the corresponding button will have -[property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as -a default response. - -@response can still be used as [property@MessageDialog:close-response] while -it's not enabled. - -Responses are enabled by default. - + filename="src/adw-preferences-dialog.c" + line="738">Makes @page the visible page of @self. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="740">a preferences dialog + - - a response ID - - - + whether to enable @response - + filename="src/adw-preferences-dialog.c" + line="741">a page of @self + - + Sets the label of @response to @label. + filename="src/adw-preferences-dialog.c" + line="783">Makes the page with the given name visible. -Labels are displayed on the dialog buttons. An embedded underline in @label -indicates a mnemonic. - +See [property@PreferencesDialog:visible-page]. + a message dialog - + filename="src/adw-preferences-dialog.c" + line="785">a preferences dialog + - - a response ID - - - + the label of @response + filename="src/adw-preferences-dialog.c" + line="786">the name of the page to make visible - - - - The body text of the dialog. - - - - - Whether the body text includes Pango markup. - -See [func@Pango.parse_markup]. + filename="src/adw-preferences-dialog.c" + line="529">Whether search is enabled. - - - + setter="set_visible_page" + getter="get_visible_page"> The ID of the close response. - -It will be passed to [signal@MessageDialog::response] if the window is -closed by pressing <kbd>Escape</kbd> or with a system action. - -It doesn't have to correspond to any of the responses in the dialog. - -The default close response is `close`. - + filename="src/adw-preferences-dialog.c" + line="503">The currently visible page. + - - - - The response ID of the default response. - -If set, pressing <kbd>Enter</kbd> will activate the corresponding button. - -If set to `NULL` or a non-existent response ID, pressing <kbd>Enter</kbd> -will do nothing. - - - - - The child widget. + filename="src/adw-preferences-dialog.c" + line="515">The name of the currently visible page. -Displayed below the heading and body. - - - - - - The heading of the dialog. +See [property@AdwPreferencesDialog:visible-page]. - - - - Whether the heading includes Pango markup. - -See [func@Pango.parse_markup]. - - - + - - This signal is emitted when the dialog is closed. - -@response will be set to the response ID of the button that had been -activated. - -if the dialog was closed by pressing <kbd>Escape</kbd> or with a system -action, @response will be set to the value of -[property@MessageDialog:close-response]. - - - - - - the response ID - - - - - - + + - - - - - - - - - - - a message dialog - - - - response ID - - - - + The parent class + @@ -16308,4515 +27333,3703 @@ action, @response will be set to the value of - - Describes the direction of a swipe navigation gesture. - - Corresponds to start or top, depending on orientation and text direction - - - Corresponds to end or bottom, depending on orientation and text direction - - - + glib:type-name="AdwPreferencesGroup" + glib:get-type="adw_preferences_group_get_type" + glib:type-struct="PreferencesGroupClass"> A page within [class@NavigationView] or [class@NavigationSplitView]. + filename="src/adw-preferences-group.c" + line="14">A group of preference rows. -Each page has a child widget, a title and optionally a tag. +<picture> + <source srcset="preferences-group-dark.png" media="(prefers-color-scheme: dark)"> + <img src="preferences-group.png" alt="preferences-group"> +</picture> -The [signal@NavigationPage::showing], [signal@NavigationPage::shown], -[signal@NavigationPage::hiding] and [signal@NavigationPage::hidden] signals -can be used to track the page's visibility within its `AdwNavigationView`. +An `AdwPreferencesGroup` represents a group or tightly related preferences, +which in turn are represented by [class@PreferencesRow]. -## Header Bar Integration +To summarize the role of the preferences it gathers, a group can have both a +title and a description. The title will be used by [class@PreferencesDialog] +to let the user look for a preference. -When placed inside `AdwNavigationPage`, [class@HeaderBar] will display the -page title instead of window title. +The [property@PreferencesGroup:separate-rows] property can be used to +separate the rows within the group, same as when using the +[`.boxed-list-separate`](style-classes.html#boxed-lists-cards) style class +instead of `.boxed-list`. -When used together with [class@NavigationView], it will also display a back -button that can be used to go back to the previous page. Set -[property@HeaderBar:show-back-button] to `FALSE` to disable that behavior if -it's unwanted. +## AdwPreferencesGroup as GtkBuildable -## CSS Nodes +The `AdwPreferencesGroup` implementation of the [iface@Gtk.Buildable] interface +supports adding [class@PreferencesRow]s to the list by omitting "type". If "type" +is omitted and the widget isn't a [class@PreferencesRow] the child is added to +a box below the list. -`AdwNavigationPage` has a single CSS node with name -`navigation-view-page`. +When the "type" attribute of a child is `header-suffix`, the child +is set as the suffix on the end of the title and description. + +## CSS nodes + +`AdwPreferencesGroup` has a single CSS node with name `preferencesgroup`. ## Accessibility -`AdwNavigationPage` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - +`AdwPreferencesGroup` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + - - Creates a new `AdwNavigationPage`. - - - the new created `AdwNavigationPage` - - - - - the child widget - - - - the page title - - - - - + Creates a new `AdwNavigationPage` with provided tag. - + filename="src/adw-preferences-group.c" + line="378">Creates a new `AdwPreferencesGroup`. + the new created `AdwNavigationPage` - + filename="src/adw-preferences-group.c" + line="383">the newly created `AdwPreferencesGroup` + - - - the child widget - - - - the page title - - - - the page tag - - - - - Called when the navigation view transition has been completed and the page -is fully hidden. - - - - - - - a navigation page - - - - - - Called when the page starts hiding at the beginning of the navigation view -transition. - - - - - - - a navigation page - - - - - + Called when the page shows at the beginning of the navigation view -transition. - + filename="src/adw-preferences-group.c" + line="391">Adds a child to @self. + a navigation page - + filename="src/adw-preferences-group.c" + line="393">a preferences group + - - - - Called when the navigation view transition has been completed and the page -is fully shown. - - - - - - + a navigation page - - + filename="src/adw-preferences-group.c" + line="394">the widget to add + + - - - + + Gets whether @self can be popped from navigation stack. - - + filename="src/adw-preferences-group.c" + line="492">Gets the description of @self. + + whether the page can be popped from navigation stack - + filename="src/adw-preferences-group.c" + line="498">the description of @self + a navigation page - + filename="src/adw-preferences-group.c" + line="494">a preferences group + - - + Gets the child widget of @self. - + filename="src/adw-preferences-group.c" + line="539">Gets the suffix for @self's header. + the child widget of @self + filename="src/adw-preferences-group.c" + line="545">the suffix for @self's header. a navigation page - + filename="src/adw-preferences-group.c" + line="541">a preferences group + - - + Gets the tag of @self. - - + filename="src/adw-preferences-group.c" + line="604">Gets whether @self's rows are separated. + + the page tag - + filename="src/adw-preferences-group.c" + line="610">whether rows are separated + a navigation page - + filename="src/adw-preferences-group.c" + line="606">a preferences group + - + c:identifier="adw_preferences_group_get_title" + glib:get-property="title"> Gets the title of @self. - + filename="src/adw-preferences-group.c" + line="445">Gets the title of @self. + the title of @self + filename="src/adw-preferences-group.c" + line="451">the title of @self a navigation page - + filename="src/adw-preferences-group.c" + line="447">a preferences group + - - + Sets whether @self can be popped from navigation stack. - -Set it to `FALSE` to disable shortcuts and gestures, as well as remove the -back button from [class@HeaderBar]. - -Manually calling [method@NavigationView.pop] or using the `navigation.pop` -action will still work. - -See [property@HeaderBar:show-back-button] for removing only the back button, -but not shortcuts. - + filename="src/adw-preferences-group.c" + line="416">Removes a child from @self. + a navigation page - + filename="src/adw-preferences-group.c" + line="418">a preferences group + - + whether the page can be popped from navigation stack - + filename="src/adw-preferences-group.c" + line="419">the child to remove + - - + Sets the child widget of @self. - + filename="src/adw-preferences-group.c" + line="512">Sets the description for @self. + a navigation page - + filename="src/adw-preferences-group.c" + line="514">a preferences group + - the child widget - + filename="src/adw-preferences-group.c" + line="515">the description + - - + Sets the tag for @self. - -The tag can be used to retrieve the page with -[method@NavigationView.find_page], as well as with -[method@NavigationView.push_by_tag], [method@NavigationView.pop_to_tag] or -[method@NavigationView.replace_with_tags]. + filename="src/adw-preferences-group.c" + line="561">Sets the suffix for @self's header. -Tags must be unique within each [class@NavigationView]. +Displayed above the list, next to the title and description. -The tag also must be set to use the `navigation.push` action. - +Suffixes are commonly used to show a button or a spinner for the whole group. + a navigation page - + filename="src/adw-preferences-group.c" + line="563">a preferences group + - the page tag - + filename="src/adw-preferences-group.c" + line="564">the suffix to set + - - + Sets the title of @self. + filename="src/adw-preferences-group.c" + line="626">Sets whether @self's rows are separated. -It's displayed in [class@HeaderBar] instead of the window title, and used as -the tooltip on the next page's back button, as well as by screen reader. - +Equivalent to using the +[`.boxed-list-separate`](style-classes.html#boxed-lists-cards) style class +on a [class@Gtk.ListBox] instead of `.boxed-list`. + a navigation page - + filename="src/adw-preferences-group.c" + line="628">a preferences group + + + + whether to separate rows + + + + + + Sets the title for @self. + + + + + + + a preferences group + the title + filename="src/adw-preferences-group.c" + line="468">the title - - - + setter="set_description" + getter="get_description"> Whether the page can be popped from navigation stack. - -Set it to `FALSE` to disable shortcuts and gestures, as well as remove the -back button from [class@HeaderBar]. - -Manually calling [method@NavigationView.pop] or using the `navigation.pop` -action will still work. - -See [property@HeaderBar:show-back-button] for removing only the back -button, but not shortcuts. - + filename="src/adw-preferences-group.c" + line="275">The description for this group of preferences. + - - - + setter="set_header_suffix" + getter="get_header_suffix"> The child widget. + filename="src/adw-preferences-group.c" + line="285">The header suffix widget. + +Displayed above the list, next to the title and description. + +Suffixes are commonly used to show a button or a spinner for the whole +group. - - - + setter="set_separate_rows" + getter="get_separate_rows" + default-value="FALSE"> The page tag. - -The tag can be used to retrieve the page with -[method@NavigationView.find_page], as well as with -[method@NavigationView.push_by_tag], [method@NavigationView.pop_to_tag] or -[method@NavigationView.replace_with_tags]. - -Tags must be unique within each [class@NavigationView]. + filename="src/adw-preferences-group.c" + line="302">Whether to separate rows. -The tag also must be set to use the `navigation.push` action. - +Equivalent to using the +[`.boxed-list-separate`](style-classes.html#boxed-lists-cards) style class +on a [class@Gtk.ListBox] instead of `.boxed-list`. + - - The page title. - -It's displayed in [class@HeaderBar] instead of the window title, and used -as the tooltip on the next page's back button, as well as by screen reader. + filename="src/adw-preferences-group.c" + line="265">The title for this group of preferences. - - Emitted when the navigation view transition has been completed and the page -is fully hidden. - -It will always be preceded by [signal@NavigationPage::hiding] or -[signal@NavigationPage::showing]. - - - - - - Emitted when the page starts hiding at the beginning of the navigation view -transition. - -It will always be followed by [signal@NavigationPage::hidden] or -[signal@NavigationPage::shown]. - - - - - - Emitted when the page shows at the beginning of the navigation view -transition. - -It will always be followed by [signal@NavigationPage::shown] or -[signal@NavigationPage::hidden]. - - - - - - Emitted when the navigation view transition has been completed and the page -is fully shown. - -It will always be preceded by [signal@NavigationPage::showing] or -[signal@NavigationPage::hiding]. - - - - - - + + + The parent class - - - - - - - - - a navigation page - - - - - - - - - - - - - - a navigation page - - - - - - - - - - - - - - a navigation page - - - - - - - - - - - - - - a navigation page - - - - - - + - + glib:type-name="AdwPreferencesPage" + glib:get-type="adw_preferences_page_get_type" + glib:type-struct="PreferencesPageClass"> A widget presenting sidebar and content side by side or as a navigation view. + filename="src/adw-preferences-page.c" + line="14">A page from [class@PreferencesDialog]. <picture> - <source srcset="navigation-split-view-dark.png" media="(prefers-color-scheme: dark)"> - <img src="navigation-split-view.png" alt="navigation-split-view"> -</picture> -<picture> - <source srcset="navigation-split-view-collapsed-dark.png" media="(prefers-color-scheme: dark)"> - <img src="navigation-split-view-collapsed.png" alt="navigation-split-view-collapsed"> + <source srcset="preferences-page-dark.png" media="(prefers-color-scheme: dark)"> + <img src="preferences-page.png" alt="preferences-page"> </picture> -`AdwNavigationSplitView` has two [class@NavigationPage] children: sidebar and -content, and displays them side by side. - -When [property@NavigationSplitView:collapsed] is set to `TRUE`, it instead -puts both children inside an [class@NavigationView]. The -[property@NavigationSplitView:show-content] controls which child is visible -while collapsed. - -See also [class@OverlaySplitView]. - -`AdwNavigationSplitView` is typically used together with an [class@Breakpoint] -setting the `collapsed` property to `TRUE` on small widths, as follows: - -```xml -<object class="AdwWindow"> - <property name="width-request">280</property> - <property name="height-request">200</property> - <property name="default-width">800</property> - <property name="default-height">800</property> - <child> - <object class="AdwBreakpoint"> - <condition>max-width: 400sp</condition> - <setter object="split_view" property="collapsed">True</setter> - </object> - </child> - <property name="content"> - <object class="AdwNavigationSplitView" id="split_view"> - <property name="sidebar"> - <object class="AdwNavigationPage"> - <property name="title" translatable="yes">Sidebar</property> - <property name="child"> - <!-- ... --> - </property> - </object> - </property> - <property name="content"> - <object class="AdwNavigationPage"> - <property name="title" translatable="yes">Content</property> - <property name="child"> - <!-- ... --> - </property> - </object> - </property> - </object> - </property> -</object> -``` - -## Sizing - -When not collapsed, `AdwNavigationSplitView` changes the sidebar width -depending on its own width. - -If possible, it tries to allocate a fraction of the total width, controlled -with the [property@NavigationSplitView:sidebar-width-fraction] property. - -The sidebar also has minimum and maximum sizes, controlled with the -[property@NavigationSplitView:min-sidebar-width] and -[property@NavigationSplitView:max-sidebar-width] properties. - -The minimum and maximum sizes are using the length unit specified with the -[property@NavigationSplitView:sidebar-width-unit]. - -By default, sidebar is using 25% of the total width, with 180sp as the -minimum size and 280sp as the maximum size. - -## Header Bar Integration - -When used inside `AdwNavigationSplitView`, [class@HeaderBar] will -automatically hide the window buttons in the middle. - -When collapsed, it also displays a back button for the content widget, as -well as the page titles. See [class@NavigationView] documentation for details. - -## Actions - -`AdwNavigationSplitView` defines the same actions as `AdwNavigationView`, but -they can be used even when the split view is not collapsed: - -- `navigation.push` takes a string parameter specifying the tag of the page -to push. If it matches the tag of the content widget, it sets -[property@NavigationSplitView:show-content] to `TRUE`. - -- `navigation.pop` doesn't take any parameters and sets -[property@NavigationSplitView:show-content] to `FALSE`. - -## `AdwNavigationSplitView` as `GtkBuildable` - -The `AdwNavigationSplitView` implementation of the [iface@Gtk.Buildable] -interface supports setting the sidebar widget by specifying “sidebar” as the -“type” attribute of a `<child>` element, Specifying “content” child type or -omitting it results in setting the content widget. - -## CSS nodes - -`AdwNavigationSplitView` has a single CSS node with the name -`navigation-split-view`. - -When collapsed, it contains a child node with the name `navigation-view` -containing both children. - -``` -navigation-split-view -╰── navigation-view - ├── [sidebar child] - ╰── [content child] -``` - -When not collapsed, it contains two nodes with the name `widget`, one with -the `.sidebar-pane` style class, the other one with `.content-view` style -class, containing the sidebar and content children respectively. - -``` -navigation-split-view -├── widget.sidebar-pane -│ ╰── [sidebar child] -╰── widget.content-pane - ╰── [content child] -``` +The `AdwPreferencesPage` widget gathers preferences groups into a single page +of a preferences window. + +## CSS nodes + +`AdwPreferencesPage` has a single CSS node with name `preferencespage`. ## Accessibility -`AdwNavigationSplitView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - +`AdwPreferencesPage` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + - + Creates a new `AdwNavigationSplitView`. - + filename="src/adw-preferences-page.c" + line="316">Creates a new `AdwPreferencesPage`. + the newly created `AdwNavigationSplitView` + filename="src/adw-preferences-page.c" + line="321">the newly created `AdwPreferencesPage` - - + Gets whether @self is collapsed. - + filename="src/adw-preferences-page.c" + line="329">Adds a preferences group to @self. + - whether @self is collapsed - + a navigation split view - + filename="src/adw-preferences-page.c" + line="331">a preferences page + + + the group to add + + - - + Sets the content widget for @self. - + filename="src/adw-preferences-page.c" + line="660">Gets the banner displayed at the top of the page. + the content widget - + filename="src/adw-preferences-page.c" + line="666">the banner for @self + a navigation split view - + filename="src/adw-preferences-page.c" + line="662">a preferences page + - - Gets the maximum sidebar width for @self. - + filename="src/adw-preferences-page.c" + line="460">Gets the description of @self. + the maximum width - + filename="src/adw-preferences-page.c" + line="466">the description of @self. + a navigation split view - + filename="src/adw-preferences-page.c" + line="462">a preferences page + - - + Gets the minimum sidebar width for @self. - + filename="src/adw-preferences-page.c" + line="603">Gets whether the description is centered. + the minimum width - + filename="src/adw-preferences-page.c" + line="609">whether the description is centered. + a navigation split view - + filename="src/adw-preferences-page.c" + line="605">a preferences page + - - + Gets which page is visible when @self is collapsed. - - + filename="src/adw-preferences-page.c" + line="374">Gets the icon name for @self. + + whether to show content when collapsed - + filename="src/adw-preferences-page.c" + line="380">the icon name for @self + a navigation split view - + filename="src/adw-preferences-page.c" + line="376">a preferences page + - - + Gets the sidebar widget for @self. - + filename="src/adw-preferences-page.c" + line="513">Gets the name of @self. + the sidebar widget - + filename="src/adw-preferences-page.c" + line="519">the name of @self + a navigation split view - + filename="src/adw-preferences-page.c" + line="515">a preferences page + - - + Gets the preferred sidebar width fraction for @self. - + filename="src/adw-preferences-page.c" + line="417">Gets the title of @self. + the preferred width fraction - + filename="src/adw-preferences-page.c" + line="423">the title of @self. + a navigation split view - + filename="src/adw-preferences-page.c" + line="419">a preferences page + - - + Gets the length unit for minimum and maximum sidebar widths. - + filename="src/adw-preferences-page.c" + line="556">Gets whether an embedded underline in the title indicates a mnemonic. + the length unit - + filename="src/adw-preferences-page.c" + line="562">whether an embedded underline in the title indicates a mnemonic + a navigation split view - + filename="src/adw-preferences-page.c" + line="558">a preferences page + - + Removes a group from @self. + + + + + + + a preferences page + + + + the group to remove + + + + + + Scrolls the scrolled window of @self to the top. + + + + + + + a preferences page + + + + + + Sets the banner displayed at the top of the page. + + + + + + + a preferences page + + + + the banner to display at the top of the page + + + + + - Sets whether @self is collapsed. - -When collapsed, the children are put inside an [class@NavigationView], -otherwise they are displayed side by side. + filename="src/adw-preferences-page.c" + line="482">Sets the description of @self. -The [property@NavigationSplitView:show-content] controls which child is -visible while collapsed. - +The description is displayed at the top of the page. + a navigation split view - + filename="src/adw-preferences-page.c" + line="484">a preferences page + - + whether @self is collapsed + filename="src/adw-preferences-page.c" + line="485">the description + + + + + + Sets whether the description should be centered. + + + + + + + a preferences page + + + + If the description should be centered - - + Sets the content widget for @self. - + filename="src/adw-preferences-page.c" + line="394">Sets the icon name for @self. + a navigation split view - + filename="src/adw-preferences-page.c" + line="396">a preferences page + - the content widget - + filename="src/adw-preferences-page.c" + line="397">the icon name + - - + Sets the maximum sidebar width for @self. + filename="src/adw-preferences-page.c" + line="533">Sets the name of @self. + + + + + + + a preferences page + + + + the name + + + + + + Sets the title of @self. + + + + + + + a preferences page + + + + the title + + + + + + Sets whether an embedded underline in the title indicates a mnemonic. + + + + + + + a preferences page + + + + `TRUE` if underlines in the text indicate mnemonics + + + + + + A [class@Banner] displayed at the top of the page. + + + + The description to be displayed at the top of the page. + + + + Whether the description should be centered. + + + + The icon name for this page. + + + + The name of this page. + + + + The title for this page. + + + + Whether an embedded underline in the title indicates a mnemonic. + + + + + + + + + + The parent class + + + + + + + + + + A [class@Gtk.ListBoxRow] used to present preferences. -Maximum width is affected by -[property@NavigationSplitView:sidebar-width-unit]. +The `AdwPreferencesRow` widget has a title that [class@PreferencesDialog] +will use to let the user look for a preference. It doesn't present the title +in any way and lets you present the preference as you please. -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - +[class@ActionRow] and its derivatives are convenient to use as preference +rows as they take care of presenting the preference's title while letting you +compose the inputs of the preference around it. + + + + + + + Creates a new `AdwPreferencesRow`. + + + the newly created `AdwPreferencesRow` + + + + + Gets the title of the preference represented by @self. + + + the title + + + + + a preferences row + + + + + + Gets whether the user can copy the title from the label + + + whether the user can copy the title from the label + + + + + a preferences row + + + + + + Gets whether to use Pango markup for the title label. + - + whether to use markup + a navigation split view - + filename="src/adw-preferences-row.c" + line="339">a preferences row + - - the maximum width - - - - + Sets the minimum sidebar width for @self. - -Minimum width is affected by -[property@NavigationSplitView:sidebar-width-unit]. - -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - + filename="src/adw-preferences-row.c" + line="241">Gets whether an embedded underline in the title indicates a mnemonic. + - + whether an embedded underline in the title indicates a mnemonic + a navigation split view - + filename="src/adw-preferences-row.c" + line="243">a preferences row + - - the minimum width - - - - + Sets which page is visible when @self is collapsed. - -If set to `TRUE`, the content widget will be the visible page when -[property@NavigationSplitView:collapsed] is `TRUE`; otherwise the sidebar -widget will be visible. + filename="src/adw-preferences-row.c" + line="215">Sets the title of the preference represented by @self. -If the split view is already collapsed, the visible page changes immediately. - +The title is interpreted as Pango markup unless +[property@PreferencesRow:use-markup] is set to `FALSE`. + a navigation split view - + filename="src/adw-preferences-row.c" + line="217">a preferences row + - + whether to show content when collapsed - + filename="src/adw-preferences-row.c" + line="218">the title + - - + Sets the sidebar widget for @self. - + filename="src/adw-preferences-row.c" + line="308">Sets whether the user can copy the title from the label + +See also [property@Gtk.Label:selectable]. + a navigation split view - + filename="src/adw-preferences-row.c" + line="310">a preferences row + - + the sidebar widget - + filename="src/adw-preferences-row.c" + line="311">`TRUE` if the user can copy the title from the label + - - + Sets the preferred sidebar width as a fraction of the total width of @self. + filename="src/adw-preferences-row.c" + line="359">Sets whether to use Pango markup for the title label. -The preferred width is additionally limited by -[property@NavigationSplitView:min-sidebar-width] and -[property@NavigationSplitView:max-sidebar-width]. +Subclasses may also use it for other labels, such as subtitle. -The sidebar widget can be allocated with larger width if its own minimum -width exceeds the preferred width. - +See also [func@Pango.parse_markup]. + a navigation split view - + filename="src/adw-preferences-row.c" + line="361">a preferences row + - + the preferred width fraction - + filename="src/adw-preferences-row.c" + line="362">whether to use markup + - - + Sets the length unit for minimum and maximum sidebar widths. - -See [property@NavigationSplitView:min-sidebar-width] and -[property@NavigationSplitView:max-sidebar-width]. - + filename="src/adw-preferences-row.c" + line="261">Sets whether an embedded underline in the title indicates a mnemonic. + a navigation split view - + filename="src/adw-preferences-row.c" + line="263">a preferences row + - + the length unit - + filename="src/adw-preferences-row.c" + line="264">`TRUE` if underlines in the text indicate mnemonics + - - - - Whether the split view is collapsed. - -When collapsed, the children are put inside an [class@NavigationView], -otherwise they are displayed side by side. - -The [property@NavigationSplitView:show-content] controls which child is -visible while collapsed. - - - - - - The content widget. - - - - - - The maximum sidebar width. - -Maximum width is affected by -[property@NavigationSplitView:sidebar-width-unit]. - -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - - - - - + setter="set_title" + getter="get_title"> The minimum sidebar width. - -Minimum width is affected by -[property@NavigationSplitView:sidebar-width-unit]. + filename="src/adw-preferences-row.c" + line="118">The title of the preference represented by this row. -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - +The title is interpreted as Pango markup unless +[property@PreferencesRow:use-markup] is set to `FALSE`. + - - - Determines the visible page when collapsed. - -If set to `TRUE`, the content widget will be the visible page when -[property@NavigationSplitView:collapsed] is `TRUE`; otherwise the sidebar -widget will be visible. + filename="src/adw-preferences-row.c" + line="141">Whether the user can copy the title from the label. -If the split view is already collapsed, the visible page changes -immediately. +See also [property@Gtk.Label:selectable]. - - - - The sidebar widget. - - - - - + setter="set_use_markup" + getter="get_use_markup" + default-value="TRUE"> The preferred sidebar width as a fraction of the total width. + filename="src/adw-preferences-row.c" + line="155">Whether to use Pango markup for the title label. -The preferred width is additionally limited by -[property@NavigationSplitView:min-sidebar-width] and -[property@NavigationSplitView:max-sidebar-width]. +Subclasses may also use it for other labels, such as subtitle. -The sidebar widget can be allocated with larger width if its own minimum -width exceeds the preferred width. - +See also [func@Pango.parse_markup]. + - - - + setter="set_use_underline" + getter="get_use_underline" + default-value="FALSE"> The length unit for minimum and maximum sidebar widths. - -See [property@NavigationSplitView:min-sidebar-width] and -[property@NavigationSplitView:max-sidebar-width]. - + filename="src/adw-preferences-row.c" + line="131">Whether an embedded underline in the title indicates a mnemonic. + + + + - - + + - + The parent class + + + + + + - + A page-based navigation container. + filename="src/adw-preferences-window.c" + line="26">A window to present an application's preferences. <picture> - <source srcset="navigation-view-dark.png" media="(prefers-color-scheme: dark)"> - <img src="navigation-view.png" alt="navigation-view"> + <source srcset="preferences-window-dark.png" media="(prefers-color-scheme: dark)"> + <img src="preferences-window.png" alt="preferences-window"> </picture> -`AdwNavigationView` presents one child at a time, similar to -[class@Gtk.Stack]. - -`AdwNavigationView` can only contain [class@NavigationPage] children. - -It maintains a navigation stack that can be controlled with -[method@NavigationView.push] and [method@NavigationView.pop]. The whole -navigation stack can also be replaced using [method@NavigationView.replace]. - -`AdwNavigationView` allows to manage pages statically or dynamically. - -Static pages can be added using the [method@NavigationView.add] method. The -`AdwNavigationView` will keep a reference to these pages, but they aren't -accessible to the user until [method@NavigationView.push] is called (except -for the first page, which is pushed automatically). Use the -[method@NavigationView.remove] method to remove them. This is useful for -applications that have a small number of unique pages and just need -navigation between them. - -Dynamic pages are automatically destroyed once they are popped off the -navigation stack. To add a page like this, push it using the -[method@NavigationView.push] method without calling -[method@NavigationView.add] first. - -## Tags - -Static pages, as well as any pages in the navigation stack, can be accessed -by their [property@NavigationPage:tag]. For example, -[method@NavigationView.push_by_tag] can be used to push a static page that's -not in the navigation stack without having to keep a reference to it manually. - -## Header Bar Integration - -When used inside `AdwNavigationView`, [class@HeaderBar] will automatically -display a back button that can be used to go back to the previous page when -possible. The button also has a context menu, allowing to pop multiple pages -at once, potentially across multiple navigation views. - -Set [property@HeaderBar:show-back-button] to `FALSE` to disable this behavior -if it's unwanted. - -`AdwHeaderBar` will also display the title of the `AdwNavigationPage` it's -placed into, so most applications shouldn't need to customize it at all. - -## Shortcuts and Gestures - -`AdwNavigationView` supports the following shortcuts for going to the -previous page: - -- <kbd>Escape</kbd> (unless [property@NavigationView:pop-on-escape] is set to - `FALSE`) -- <kbd>Alt</kbd>+<kbd>←</kbd> -- Back mouse button - -Additionally, it supports interactive gestures: - -- One-finger swipe towards the right on touchscreens -- Scrolling towards the right on touchpads (usually two-finger swipe) - -These gestures have transitions enabled regardless of the -[property@NavigationView:animate-transitions] value. - -Applications can also enable shortcuts for pushing another page onto the -navigation stack via connecting to the [signal@NavigationView::get-next-page] -signal, in that case the following shortcuts are supported: - -- <kbd>Alt</kbd>+<kbd>→</kbd> -- Forward mouse button -- Swipe/scrolling towards the left - -For right-to-left locales, the gestures and shortcuts are reversed. - -[property@NavigationPage:can-pop] can be used to disable them, along with the -header bar back buttons. - -## Actions - -`AdwNavigationView` defines actions for controlling the navigation stack. -actions for controlling the navigation stack: - -- `navigation.push` takes a string parameter specifying the tag of the page to -push, and is equivalent to calling [method@NavigationView.push_by_tag]. - -- `navigation.pop` doesn't take any parameters and pops the current page from -the navigation stack, equivalent to calling [method@NavigationView.pop]. - -## `AdwNavigationView` as `GtkBuildable` - -`AdwNavigationView` allows to add pages as children, equivalent to using the -[method@NavigationView.add] method. - -Example of an `AdwNavigationView` UI definition: - -```xml -<object class="AdwNavigationView"> - <child> - <object class="AdwNavigationPage"> - <property name="title" translatable="yes">Page 1</property> - <property name="child"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"/> - </child> - <property name="content"> - <object class="GtkButton"> - <property name="label" translatable="yes">Open Page 2</property> - <property name="halign">center</property> - <property name="valign">center</property> - <property name="action-name">navigation.push</property> - <property name="action-target">'page-2'</property> - <style> - <class name="pill"/> - </style> - </object> - </property> - </object> - </property> - </object> - </child> - <child> - <object class="AdwNavigationPage"> - <property name="title" translatable="yes">Page 2</property> - <property name="tag">page-2</property> - <property name="child"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"/> - </child> - <property name="content"> - <!-- ... --> - </property> - </object> - </property> - </object> - </child> -</object> -``` - -<picture> - <source srcset="navigation-view-example-dark.png" media="(prefers-color-scheme: dark)"> - <img src="navigation-view-example.png" alt="navigation-view-example"> -</picture> +The `AdwPreferencesWindow` widget presents an application's preferences +gathered into pages and groups. The preferences are searchable by the user. ## CSS nodes -`AdwNavigationView` has a single CSS node with the name `navigation-view`. - -## Accessibility - -`AdwNavigationView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - - +`AdwPreferencesWindow` has a main CSS node with the name `window` and the +style class `.preferences`. + Use [class@PreferencesDialog]. + + + + + c:identifier="adw_preferences_window_new" + deprecated="1" + deprecated-version="1.6"> Creates a new `AdwNavigationView`. - + filename="src/adw-preferences-window.c" + line="715">Creates a new `AdwPreferencesWindow`. + Use [class@PreferencesDialog]. + the new created `AdwNavigationView` + filename="src/adw-preferences-window.c" + line="720">the newly created `AdwPreferencesWindow` - + Permanently adds @page to @self. - -Any page that has been added will stay in @self even after being popped from -the navigation stack. - -Adding a page while no page is visible will automatically push it to the -navigation stack. - -See [method@NavigationView.remove]. - + filename="src/adw-preferences-window.c" + line="730">Adds a preferences page to @self. + Use [class@PreferencesDialog]. + a navigation view - + filename="src/adw-preferences-window.c" + line="732">a preferences window + the page to add - + filename="src/adw-preferences-window.c" + line="733">the page to add + - + Finds a page in @self by its tag. + filename="src/adw-preferences-window.c" + line="1115">Displays @toast. -See [property@NavigationPage:tag]. - - - the page with the given tag - +See [method@ToastOverlay.add_toast]. + Use [class@PreferencesDialog]. + + + a navigation view - + filename="src/adw-preferences-window.c" + line="1117">a preferences window + - + a page tag - + filename="src/adw-preferences-window.c" + line="1118">a toast + - - + Gets whether @self animates page transitions. - + filename="src/adw-preferences-window.c" + line="1041">Closes the current subpage. + +If there is no presented subpage, this does nothing. + Use [method@PreferencesWindow.pop_subpage] instead. + - whether to animate page transitions - + a navigation view - + filename="src/adw-preferences-window.c" + line="1043">a preferences window + - - + Returns a [iface@Gio.ListModel] that contains the pages in navigation stack. - -The pages are sorted from root page to visible page. - -This can be used to keep an up-to-date view. - - + filename="src/adw-preferences-window.c" + line="982">Gets whether gestures and shortcuts for closing subpages are enabled. + Use [method@NavigationPage.get_can_pop] instead. + + a list model for the navigation stack - + filename="src/adw-preferences-window.c" + line="988">whether gestures and shortcuts are enabled. + a navigation view - + filename="src/adw-preferences-window.c" + line="984">a preferences window + - - + Gets whether pressing Escape pops the current page on @self. - + filename="src/adw-preferences-window.c" + line="882">Gets whether search is enabled for @self. + Use [class@PreferencesDialog]. + whether to pop the current page + filename="src/adw-preferences-window.c" + line="888">whether search is enabled for @self. a navigation view - + filename="src/adw-preferences-window.c" + line="884">a preferences window + - + Gets the previous page for @page. - -If @page is in the navigation stack, returns the page popping @page will -reveal. - -If @page is the root page or is not in the navigation stack, returns `NULL`. - + filename="src/adw-preferences-window.c" + line="791">Gets the currently visible page of @self. + Use [class@PreferencesDialog]. + the previous page - + filename="src/adw-preferences-window.c" + line="797">the visible page + a navigation view - + filename="src/adw-preferences-window.c" + line="793">a preferences window + - - a page in @self - - - - + Gets the currently visible page in @self. - + filename="src/adw-preferences-window.c" + line="836">Gets the name of currently visible page of @self. + Use [class@PreferencesDialog]. + the currently visible page - + filename="src/adw-preferences-window.c" + line="842">the name of the visible page + a navigation view - + filename="src/adw-preferences-window.c" + line="838">a preferences window + - + Pops the visible page from the navigation stack. - -Does nothing if the navigation stack contains less than two pages. - -If [method@NavigationView.add] hasn't been called, the page is automatically -removed. - -[signal@NavigationView::popped] will be emitted for the current visible page. - -See [method@NavigationView.pop_to_page] and -[method@NavigationView.pop_to_tag]. - + filename="src/adw-preferences-window.c" + line="1092">Pop the visible page from the subpage stack of @self. + Use [class@PreferencesDialog]. + `TRUE` if a page has been popped + filename="src/adw-preferences-window.c" + line="1098">`TRUE` if a page has been popped a navigation view - + filename="src/adw-preferences-window.c" + line="1094">a preferences window + - + Pops pages from the navigation stack until @page is visible. - -@page must be in the navigation stack. - -If [method@NavigationView.add] hasn't been called for any of the popped pages, -they are automatically removed. + filename="src/adw-preferences-window.c" + line="1004">Sets @subpage as the window's subpage and opens it. -[signal@NavigationView::popped] will be be emitted for each of the popped -pages. +The transition can be cancelled by the user, in which case visible child will +change back to the previously visible child. + Use [method@PreferencesWindow.push_subpage] instead. + + + + + + + a preferences window + + + + the subpage + + + + + + Pushes @page onto the subpage stack of @self. -See [method@NavigationView.pop] and [method@NavigationView.pop_to_tag]. - +The page will be automatically removed when popped. + Use [class@PreferencesDialog]. + - `TRUE` if any pages have been popped - + a navigation view - + filename="src/adw-preferences-window.c" + line="1068">a preferences window + the page to pop to + filename="src/adw-preferences-window.c" + line="1069">the subpage - + Pops pages from the navigation stack until page with the tag @tag is visible. - -The page must be in the navigation stack. - -If [method@NavigationView.add] hasn't been called for any of the popped pages, -they are automatically removed. - -[signal@NavigationView::popped] will be emitted for each of the popped pages. - -See [method@NavigationView.pop_to_page] and [property@NavigationPage:tag]. - + filename="src/adw-preferences-window.c" + line="762">Removes a page from @self. + Use [class@PreferencesDialog]. + - `TRUE` if any pages have been popped - + a navigation view - + filename="src/adw-preferences-window.c" + line="764">a preferences window + - + a page tag - + filename="src/adw-preferences-window.c" + line="765">the page to remove + - + Pushes @page onto the navigation stack. + filename="src/adw-preferences-window.c" + line="940">Sets whether gestures and shortcuts for closing subpages are enabled. -If [method@NavigationView.add] hasn't been called, the page is automatically -removed once it's popped. +The supported gestures are: + +- One-finger swipe on touchscreens +- Horizontal scrolling on touchpads (usually two-finger swipe) +- Back mouse button + +The keyboard back key is also supported, as well as the +<kbd>Alt</kbd>+<kbd>←</kbd> shortcut. -[signal@NavigationView::popped] will be emitted for @page. +For right-to-left locales, gestures and shortcuts are reversed. -See [method@NavigationView.push_by_tag]. - +Has no effect for subpages added with [method@PreferencesWindow.push_subpage]. + Use [method@NavigationPage.set_can_pop] instead. + a navigation view - + filename="src/adw-preferences-window.c" + line="942">a preferences window + - + the page to push - + filename="src/adw-preferences-window.c" + line="943">the new value + - + Pushes the page with the tag @tag onto the navigation stack. - -If [method@NavigationView.add] hasn't been called, the page is automatically -removed once it's popped. - -[signal@NavigationView::popped] will be emitted for pushed page. - -See [method@NavigationView.push] and [property@NavigationPage:tag]. - + filename="src/adw-preferences-window.c" + line="904">Sets whether search is enabled for @self. + Use [class@PreferencesDialog]. + a navigation view - + filename="src/adw-preferences-window.c" + line="906">a preferences window + - + the page tag - + filename="src/adw-preferences-window.c" + line="907">whether search is enabled + - + Removes @page from @self. - -If @page is currently in the navigation stack, it will be removed once it's -popped. Otherwise, it's removed immediately. - -See [method@NavigationView.add]. - + filename="src/adw-preferences-window.c" + line="813">Makes @page the visible page of @self. + Use [class@PreferencesDialog]. + a navigation view - + filename="src/adw-preferences-window.c" + line="815">a preferences window + the page to remove - + filename="src/adw-preferences-window.c" + line="816">a page of @self + - + Replaces the current navigation stack with @pages. - -The last page becomes the visible page. - -Replacing the navigation stack has no animation. - -If [method@NavigationView.add] hasn't been called for any pages that are no -longer in the navigation stack, they are automatically removed. - -@n_pages can be 0, in that case no page will be visible after calling this -method. This can be useful for removing all pages from @self. - -The [signal@NavigationView::replaced] signal will be emitted. + filename="src/adw-preferences-window.c" + line="858">Makes the page with the given name visible. -See [method@NavigationView.replace_with_tags]. - +See [property@PreferencesWindow:visible-page]. + Use [class@PreferencesDialog]. + a navigation view - + filename="src/adw-preferences-window.c" + line="860">a preferences window + - - the new navigation stack - - - - - + the number of pages in @pages - + filename="src/adw-preferences-window.c" + line="861">the name of the page to make visible + - + Replaces the current navigation stack with pages with the tags @tags. + filename="src/adw-preferences-window.c" + line="587">Whether gestures and shortcuts for closing subpages are enabled. -The last page becomes the visible page. +The supported gestures are: -Replacing the navigation stack has no animation. +- One-finger swipe on touchscreens +- Horizontal scrolling on touchpads (usually two-finger swipe) +- Back mouse button -If [method@NavigationView.add] hasn't been called for any pages that are no -longer in the navigation stack, they are automatically removed. +The keyboard back key is also supported, as well as the +<kbd>Alt</kbd>+<kbd>←</kbd> shortcut. -@n_tags can be 0, in that case no page will be visible after calling this -method. This can be useful for removing all pages from @self. +For right-to-left locales, gestures and shortcuts are reversed. -The [signal@NavigationView::replaced] signal will be emitted. +Has no effect for subpages added with +[method@PreferencesWindow.push_subpage]. + Use [property@NavigationPage:can-pop] instead. + + + + Whether search is enabled. + Use [class@PreferencesDialog]. + + + + The currently visible page. + Use [class@PreferencesDialog]. + + + + The name of the currently visible page. -See [method@NavigationView.replace] and [property@NavigationPage:tag]. - - - +See [property@PreferencesWindow:visible-page]. + Use [class@PreferencesDialog]. + + + + + + + + + + The parent class + + + + + + + + + + An [class@AnimationTarget] changing the value of a property of a +[class@GObject.Object] instance. + + + Creates a new `AdwPropertyAnimationTarget` for the @property_name property on +@object. + + + the newly created `AdwPropertyAnimationTarget` + + + + + an object to be animated + + + + the name of the property on @object to animate + + + + + + Creates a new `AdwPropertyAnimationTarget` for the @pspec property on +@object. + + + new newly created `AdwPropertyAnimationTarget` + - - a navigation view - - - + tags of the pages in the - navigation stack - - - + filename="src/adw-animation-target.c" + line="380">an object to be animated + - + the number of tags - + filename="src/adw-animation-target.c" + line="381">the param spec of the property on @object to animate + - - - + + Sets whether @self should animate page transitions. + filename="src/adw-animation-target.c" + line="403">Gets the object animated by @self. -Gesture-based transitions are always animated. - +The `AdwPropertyAnimationTarget` instance does not hold a strong reference on +the object; make sure the object is kept alive throughout the target's +lifetime. + - + the animated object + a navigation view - + filename="src/adw-animation-target.c" + line="405">a property animation target + - - whether to animate page transitions - - - - + Sets whether pressing Escape pops the current page on @self. - -Applications using `AdwNavigationView` to implement a browser may want to -disable it. - + filename="src/adw-animation-target.c" + line="425">Gets the `GParamSpec` of the property animated by @self. + - + the animated property's `GParamSpec` + a navigation view - + filename="src/adw-animation-target.c" + line="427">a property animation target + - - whether to pop the current page when pressing Escape - - - - - - Whether to animate page transitions. - -Gesture-based transitions are always animated. - - - - + getter="get_object"> A list model that contains the pages in navigation stack. - -The pages are sorted from root page to visible page. + filename="src/adw-animation-target.c" + line="310">The object whose property will be animated. -This can be used to keep an up-to-date view. - +The `AdwPropertyAnimationTarget` instance does not hold a strong reference +on the object; make sure the object is kept alive throughout the target's +lifetime. + - - - - Whether pressing Escape pops the current page. - -Applications using `AdwNavigationView` to implement a browser may want to -disable it. - - - - + getter="get_pspec"> The currently visible page. - + filename="src/adw-animation-target.c" + line="326">The `GParamSpec` of the property to be animated. + - - Emitted when a push shortcut or a gesture is triggered. - -To support the push shortcuts and gestures, the application is expected to -return the page to push in the handler. - -This signal can be emitted multiple times for the gestures, for example -when the gesture is cancelled by the user. As such, the application must -not make any irreversible changes in the handler, such as removing the page -from a forward stack. + + + + + + Describes the possible styles of [class@AlertDialog] response buttons. -Instead, it should be done in the [signal@NavigationView::pushed] handler. - - the page to push - - - - +See [method@AlertDialog.set_response_appearance]. + Emitted after @page has been popped from the navigation stack. - -See [method@NavigationView.pop]. - -When using [method@NavigationView.pop_to_page] or -[method@NavigationView.pop_to_tag], this signal is emitted for each of the -popped pages. - - - - - - the popped page - - - - - + filename="src/adw-alert-dialog.c" + line="161">the default appearance. + + Emitted after a page has been pushed to the navigation stack. - -See [method@NavigationView.push]. - - - - - + filename="src/adw-alert-dialog.c" + line="162">used to denote important responses such as the + affirmative action. + + Emitted after the navigation stack has been replaced. - -See [method@NavigationView.replace]. - - - - - - - - - - - - used to draw attention to the potentially damaging + consequences of using the response. This appearance acts as a warning to + the user. + + + + glib:type-name="AdwSpinRow" + glib:get-type="adw_spin_row_get_type" + glib:type-struct="SpinRowClass"> A widget presenting sidebar and content side by side or as an overlay. + filename="src/adw-spin-row.c" + line="19">An [class@ActionRow] with an embedded spin button. <picture> - <source srcset="overlay-split-view-dark.png" media="(prefers-color-scheme: dark)"> - <img src="overlay-split-view.png" alt="overlay-split-view"> -</picture> -<picture> - <source srcset="overlay-split-view-collapsed-dark.png" media="(prefers-color-scheme: dark)"> - <img src="overlay-split-view-collapsed.png" alt="overlay-split-view-collapsed"> + <source srcset="spin-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="spin-row.png" alt="spin-row"> </picture> -`AdwOverlaySplitView` has two children: sidebar and content, and displays -them side by side. - -When [property@OverlaySplitView:collapsed] is set to `TRUE`, the sidebar is -instead shown as an overlay above the content widget. - -The sidebar can be hidden or shown using the -[property@OverlaySplitView:show-sidebar] property. - -Sidebar can be displayed before or after the content, this can be controlled -with the [property@OverlaySplitView:sidebar-position] property. - -Collapsing the split view automatically hides the sidebar widget, and -uncollapsing it shows the sidebar. If this behavior is not desired, the -[property@OverlaySplitView:pin-sidebar] property can be used to override it. - -`AdwOverlaySplitView` supports an edge swipe gesture for showing the sidebar, -and a swipe from the sidebar for hiding it. Gestures are only supported on -touchscreen, but not touchpad. Gestures can be controlled with the -[property@OverlaySplitView:enable-show-gesture] and -[property@OverlaySplitView:enable-hide-gesture] properties. - -See also [class@NavigationSplitView]. - -`AdwOverlaySplitView` is typically used together with an [class@Breakpoint] -setting the `collapsed` property to `TRUE` on small widths, as follows: +Example of an `AdwSpinRow` UI definition: ```xml -<object class="AdwWindow"> - <property name="width-request">360</property> - <property name="height-request">200</property> - <property name="default-width">800</property> - <property name="default-height">800</property> - <child> - <object class="AdwBreakpoint"> - <condition>max-width: 400sp</condition> - <setter object="split_view" property="collapsed">True</setter> - </object> - </child> - <property name="content"> - <object class="AdwOverlaySplitView" id="split_view"> - <property name="sidebar"> - <!-- ... --> - </property> - <property name="content"> - <!-- ... --> - </property> +<object class="AdwSpinRow"> + <property name="title" translatable="yes">Spin Row</property> + <property name="adjustment"> + <object class="GtkAdjustment"> + <property name="lower">0</property> + <property name="upper">100</property> + <property name="value">50</property> + <property name="page-increment">10</property> + <property name="step-increment">1</property> </object> </property> </object> ``` -`AdwOverlaySplitView` is often used for implementing the -[utility pane](https://developer.gnome.org/hig/patterns/containers/utility-panes.html) -pattern. - -## Sizing - -When not collapsed, `AdwOverlaySplitView` changes the sidebar width -depending on its own width. - -If possible, it tries to allocate a fraction of the total width, controlled -with the [property@OverlaySplitView:sidebar-width-fraction] property. - -The sidebar also has minimum and maximum sizes, controlled with the -[property@OverlaySplitView:min-sidebar-width] and -[property@OverlaySplitView:max-sidebar-width] properties. - -The minimum and maximum sizes are using the length unit specified with the -[property@OverlaySplitView:sidebar-width-unit]. - -By default, sidebar is using 25% of the total width, with 180sp as the -minimum size and 280sp as the maximum size. - -When collapsed, the preferred width fraction is ignored and the sidebar uses -[property@OverlaySplitView:max-sidebar-width] when possible. - -## Header Bar Integration - -When used inside `AdwOverlaySplitView`, [class@HeaderBar] will automatically -hide the window buttons in the middle. - -## `AdwOverlaySplitView` as `GtkBuildable` - -The `AdwOverlaySplitView` implementation of the [iface@Gtk.Buildable] -interface supports setting the sidebar widget by specifying “sidebar” as the -“type” attribute of a `<child>` element, Specifying “content” child type or -omitting it results in setting the content widget. +See [class@Gtk.SpinButton] for details. ## CSS nodes -`AdwOverlaySplitView` has a single CSS node with the name -`overlay-split-view`. - -It contains two nodes with the name `widget`, containing the sidebar and -content children. - -When not collapsed, they have the `.sidebar-view` and `.content-view` style -classes respectively. - -``` -overlay-split-view -├── widget.sidebar-pane -│ ╰── [sidebar child] -╰── widget.content-pane - ╰── [content child] -``` - -When collapsed, the one containing the sidebar child has the `.background` -style class and the other one has no style classes. - -``` -overlay-split-view -├── widget.background -│ ╰── [sidebar child] -╰── widget - ╰── [content child] -``` +`AdwSpinRow` has the same structure as [class@ActionRow], as well as the +`.spin` style class on the main node. ## Accessibility -`AdwOverlaySplitView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - - +`AdwSpinRow` uses an internal `GtkSpinButton` with the +`GTK_ACCESSIBLE_ROLE_SPIN_BUTTON` role. + + - + + Creates a new `AdwOverlaySplitView`. - + filename="src/adw-spin-row.c" + line="518">Creates a new `AdwSpinRow`. + the newly created `AdwOverlaySplitView` + filename="src/adw-spin-row.c" + line="526">the newly created `AdwSpinRow` - - - - Gets whether @self is collapsed. - - - whether @self is collapsed - - - + an overlay split view - - - - - - - Gets the content widget for @self. - - - the content widget for @self - - - - + filename="src/adw-spin-row.c" + line="520">the adjustment that this spin row should use + + + an overlay split view - - + filename="src/adw-spin-row.c" + line="521">the rate the value changes when holding a button or key + + + + the number of decimal places to display + + - - - + + Gets whether @self can be closed with a swipe gesture. - + filename="src/adw-spin-row.c" + line="545">Creates a new `AdwSpinRow` with the given properties. + +This is a convenience constructor that allows creation of a numeric +`AdwSpinRow` without manually creating an adjustment. The value is initially +set to the minimum value and a page increment of 10 * @step is the default. +The precision of the spin row is equivalent to the precisions of @step. + +::: note + The way in which the precision is derived works best if @step is a power + of ten. If the resulting precision is not suitable for your needs, use + [method@SpinRow.set_digits] to correct it. + `TRUE` if @self can be closed with a swipe gesture - + filename="src/adw-spin-row.c" + line="563">the new `AdwSpinRow` + - + + minimum allowable value + + + + maximum allowable value + + + an overlay split view - - + filename="src/adw-spin-row.c" + line="549">increment added or subtracted by spinning the widget + + - - + - Gets whether @self can be opened with an edge swipe gesture. - + filename="src/adw-spin-row.c" + line="597">Changes the properties of an existing spin row. + +The adjustment, climb rate, and number of decimal places are updated +accordingly. + - `TRUE` if @self can be opened with a swipe gesture - + an overlay split view - + filename="src/adw-spin-row.c" + line="599">a spin row + + + the adjustment that this spin row should use + + + + the new climb rate + + + + the number of decimal places to display + + - - Gets the maximum sidebar width for @self. - + filename="src/adw-spin-row.c" + line="630">Gets the adjustment that holds the value for the spin row. + the maximum width - + filename="src/adw-spin-row.c" + line="636">the adjustment that holds the spin row's value + an overlay split view - + filename="src/adw-spin-row.c" + line="632">a spin row + - - Gets the minimum sidebar width for @self. - + filename="src/adw-spin-row.c" + line="674">Gets the acceleration rate when you hold down a button or key. + the minimum width + filename="src/adw-spin-row.c" + line="680">the acceleration rate when you hold down a button or key an overlay split view - + filename="src/adw-spin-row.c" + line="676">a spin row + - - Gets whether the sidebar widget is pinned for @self. - + filename="src/adw-spin-row.c" + line="716">Gets the number of decimal places to display. + whether if the sidebar widget is pinned - + filename="src/adw-spin-row.c" + line="722">the number of decimal places to display + an overlay split view - + filename="src/adw-spin-row.c" + line="718">a spin row + - - Gets whether the sidebar widget is shown for @self. - + filename="src/adw-spin-row.c" + line="757">Gets whether non-numeric characters should be ignored. + `TRUE` if the sidebar widget is shown + filename="src/adw-spin-row.c" + line="763">whether non-numeric characters should be ignored. an overlay split view - + filename="src/adw-spin-row.c" + line="759">a spin row + - - Gets the sidebar widget for @self. - - + filename="src/adw-spin-row.c" + line="800">Gets whether invalid values are snapped to nearest step increment. + + the sidebar widget for @self - + filename="src/adw-spin-row.c" + line="806">whether invalid values are snapped to the nearest step increment + an overlay split view - + filename="src/adw-spin-row.c" + line="802">a spin row + - - Gets the sidebar position for @self. - + filename="src/adw-spin-row.c" + line="843">Gets the policy for updating the spin row. + the sidebar position for @self - + filename="src/adw-spin-row.c" + line="849">the policy for updating the spin row + an overlay split view - + filename="src/adw-spin-row.c" + line="845">a spin row + - - Gets the preferred sidebar width fraction for @self. - + filename="src/adw-spin-row.c" + line="886">Gets the current value. + the preferred width fraction + filename="src/adw-spin-row.c" + line="892">the current value an overlay split view - + filename="src/adw-spin-row.c" + line="888">a spin row + - - Gets the length unit for minimum and maximum sidebar widths. - + filename="src/adw-spin-row.c" + line="925">Gets whether the spin row should wrap upon reaching its limits. + the length unit - - - - - an overlay split view - - - - - - - Sets whether @self view is collapsed. - -When collapsed, the sidebar widget is presented as an overlay above the -content widget, otherwise they are displayed side by side. - - - + filename="src/adw-spin-row.c" + line="931">whether the spin row should wrap upon reaching its limits + an overlay split view - + filename="src/adw-spin-row.c" + line="927">a spin row + - - whether @self is collapsed - - - - Sets the content widget for @self. - + filename="src/adw-spin-row.c" + line="650">Sets the adjustment that holds the value for the spin row. + an overlay split view - + filename="src/adw-spin-row.c" + line="652">a spin row + - the content widget - + filename="src/adw-spin-row.c" + line="653">an adjustment + - - Sets whether @self can be closed with a swipe gesture. - -Only touchscreen swipes are supported. - + filename="src/adw-spin-row.c" + line="692">Sets the acceleration rate when you hold down a button or key. + an overlay split view - + filename="src/adw-spin-row.c" + line="694">a spin row + - + whether @self can be closed with a swipe gesture - + filename="src/adw-spin-row.c" + line="695">the acceleration rate when you hold down a button or key + - - Sets whether @self can be opened with an edge swipe gesture. - -Only touchscreen swipes are supported. - + filename="src/adw-spin-row.c" + line="734">Sets the number of decimal places to display. + an overlay split view - + filename="src/adw-spin-row.c" + line="736">a spin row + - + whether @self can be opened with a swipe gesture - + filename="src/adw-spin-row.c" + line="737">the number of decimal places to display + - - Sets the maximum sidebar width for @self. - -Maximum width is affected by [property@OverlaySplitView:sidebar-width-unit]. - -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - + filename="src/adw-spin-row.c" + line="775">Sets whether non-numeric characters should be ignored. + an overlay split view - + filename="src/adw-spin-row.c" + line="777">a spin row + - + the maximum width - + filename="src/adw-spin-row.c" + line="778">whether non-numeric characters should be ignored + - - Sets the minimum sidebar width for @self. - -Minimum width is affected by [property@OverlaySplitView:sidebar-width-unit]. + filename="src/adw-spin-row.c" + line="984">Sets the minimum and maximum allowable values for @self. -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - +If the current value is outside this range, it will be adjusted +to fit within the range, otherwise it will remain unchanged. + an overlay split view - + filename="src/adw-spin-row.c" + line="986">a spin row + - + the minimum width + filename="src/adw-spin-row.c" + line="987">minimum allowable value - - - - - Sets whether the sidebar widget is pinned for @self. - -By default, collapsing @self automatically hides the sidebar widget, and -uncollapsing it shows the sidebar. If set to `TRUE`, sidebar visibility never -changes on its own. - - - - - - - an overlay split view - - - + whether to pin the sidebar widget - + filename="src/adw-spin-row.c" + line="988">maximum allowable value + - - Sets whether the sidebar widget is shown for @self. - + filename="src/adw-spin-row.c" + line="818">Sets whether invalid values are snapped to the nearest step increment. + an overlay split view - + filename="src/adw-spin-row.c" + line="820">a spin row + - + whether to show the sidebar widget + filename="src/adw-spin-row.c" + line="821">whether invalid values are snapped to the nearest step increment - - Sets the sidebar widget for @self. - + filename="src/adw-spin-row.c" + line="861">Sets the policy for updating the spin row. + +The options are always, or only when the value is invalid. + an overlay split view - + filename="src/adw-spin-row.c" + line="863">a spin row + - + the sidebar widget - + filename="src/adw-spin-row.c" + line="864">the policy for updating the spin row + - - Sets the sidebar position for @self. - -If it's set to `GTK_PACK_START`, the sidebar is displayed before the content, -if `GTK_PACK_END`, it's displayed after the content. - + filename="src/adw-spin-row.c" + line="904">Sets the current value. + an overlay split view - + filename="src/adw-spin-row.c" + line="906">a spin row + - + the new position - + filename="src/adw-spin-row.c" + line="907">a new value + - - Sets the preferred sidebar width as a fraction of the total width of @self. - -The preferred width is additionally limited by -[property@OverlaySplitView:min-sidebar-width] and -[property@OverlaySplitView:max-sidebar-width]. - -The sidebar widget can be allocated with larger width if its own minimum -width exceeds the preferred width. - + filename="src/adw-spin-row.c" + line="943">Sets whether the spin row should wrap upon reaching its limits. + an overlay split view - + filename="src/adw-spin-row.c" + line="945">a spin row + - + the preferred width fraction - + filename="src/adw-spin-row.c" + line="946">whether the spin row should wrap upon reaching its limits + - - + Sets the length unit for minimum and maximum sidebar widths. - -See [property@OverlaySplitView:min-sidebar-width] and -[property@OverlaySplitView:max-sidebar-width]. - + filename="src/adw-spin-row.c" + line="968">Manually force an update of the spin row. + an overlay split view - - - - the length unit - - - - - - - - Whether the split view is collapsed. - -When collapsed, the sidebar widget is presented as an overlay above the -content widget, otherwise they are displayed side by side. - - - - - - The content widget. - - - - - - Whether the sidebar can be closed with a swipe gesture. - -Only touchscreen swipes are supported. - - - a spin row + + + + + - - + setter="set_adjustment" + getter="get_adjustment"> Whether the sidebar can be opened with an edge swipe gesture. - -Only touchscreen swipes are supported. - + filename="src/adw-spin-row.c" + line="269">The adjustment that holds the value of the spin row. + - - - + setter="set_climb_rate" + getter="get_climb_rate" + default-value="0.000000"> The maximum sidebar width. - -Maximum width is affected by -[property@OverlaySplitView:sidebar-width-unit]. - -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. + filename="src/adw-spin-row.c" + line="281">The acceleration rate when you hold down a button or key. - - - + setter="set_digits" + getter="get_digits" + default-value="0"> The minimum sidebar width. - -Minimum width is affected by -[property@OverlaySplitView:sidebar-width-unit]. - -The sidebar widget can still be allocated with larger width if its own -minimum width exceeds it. - + filename="src/adw-spin-row.c" + line="293">The number of decimal places to display. + - - - Whether the sidebar widget is pinned. - -By default, collapsing @self automatically hides the sidebar widget, and -uncollapsing it shows the sidebar. If set to `TRUE`, sidebar visibility -never changes on its own. + filename="src/adw-spin-row.c" + line="305">Whether non-numeric characters should be ignored. - - - + setter="set_snap_to_ticks" + getter="get_snap_to_ticks" + default-value="FALSE"> Whether the sidebar widget is shown. + filename="src/adw-spin-row.c" + line="317">Whether invalid values are snapped to the nearest step increment. - - - + setter="set_update_policy" + getter="get_update_policy" + default-value="GTK_UPDATE_ALWAYS"> The sidebar widget. - + filename="src/adw-spin-row.c" + line="329">The policy for updating the spin row. + +The options are always, or only when the value is invalid. + - - - + setter="set_value" + getter="get_value" + default-value="0.000000"> The sidebar position. - -If it's set to `GTK_PACK_START`, the sidebar is displayed before the content, -if `GTK_PACK_END`, it's displayed after the content. - + filename="src/adw-spin-row.c" + line="344">The current value. + - - - + setter="set_wrap" + getter="get_wrap" + default-value="FALSE"> The preferred sidebar width as a fraction of the total width. + filename="src/adw-spin-row.c" + line="356">Whether the spin row should wrap upon reaching its limits. + + + + Emitted to convert the user's input into a double value. -The preferred width is additionally limited by -[property@OverlaySplitView:min-sidebar-width] and -[property@OverlaySplitView:max-sidebar-width]. +The signal handler is expected to use [method@Gtk.Editable.get_text] to +retrieve the text of the spinbutton and set new_value to the new value. -The sidebar widget can be allocated with larger width if its own minimum -width exceeds the preferred width. - - - - - +The default conversion uses [func@GLib.strtod]. + +See [signal@Gtk.SpinButton::input]. + + `TRUE` for a successful conversion, `FALSE` if the input was not + handled, and `GTK_INPUT_ERROR` if the conversion failed. + + + + + return location for the new value + + + + + The length unit for minimum and maximum sidebar widths. + filename="src/adw-spin-row.c" + line="404">Emitted to tweak the formatting of the value for display. -See [property@OverlaySplitView:min-sidebar-width] and -[property@OverlaySplitView:max-sidebar-width]. - - +See [signal@Gtk.SpinButton::output]. + + `TRUE` if the value has been displayed + + + + + Emitted right after the spinbutton wraps. + +See [signal@Gtk.SpinButton::wrapped]. + + + + - - + + - + - + glib:type-name="AdwSpinner" + glib:get-type="adw_spinner_get_type" + glib:type-struct="SpinnerClass"> A [class@EntryRow] tailored for entering secrets. + filename="src/adw-spinner.c" + line="17">A widget showing a loading spinner. <picture> - <source srcset="password-entry-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="password-entry-row.png" alt="password-entry-row"> + <source srcset="spinner-dark.png" media="(prefers-color-scheme: dark)"> + <img src="spinner.png" alt="spinner"> </picture> -It does not show its contents in clear text, does not allow to copy it to the -clipboard, and shows a warning when Caps Lock is engaged. If the underlying -platform allows it, `AdwPasswordEntryRow` will also place the text in a -non-pageable memory area, to avoid it being written out to disk by the -operating system. +The size of the spinner depends on the available size, never smaller than +16×16 pixels and never larger than 64×64 pixels. -It offer a way to reveal the contents in clear text. +Use the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] +properties in combination with [property@Gtk.Widget:width-request] and +[property@Gtk.Widget:height-request] for fine sizing control. -## CSS Nodes +For example, the following snippet shows the spinner at 48×48 pixels: -`AdwPasswordEntryRow` has a single CSS node with name `row` that carries -`.entry` and `.password` style classes. - +```xml +<object class="AdwSpinner"> + <property name="halign">center</property> + <property name="valign">center</property> + <property name="width-request">48</property> + <property name="height-request">48</property> +</object> +``` + +See [class@SpinnerPaintable] for cases where using a widget is impractical or +impossible, such as [property@StatusPage:paintable]. + +## CSS nodes + +`AdwSpinner` has a single node with the name `image` and the style class +`.spinner`. + - - - + Creates a new `AdwPasswordEntryRow`. - + filename="src/adw-spinner.c" + line="135">Creates a new `AdwSpinner`. + the newly created `AdwPasswordEntryRow` + filename="src/adw-spinner.c" + line="140">the newly created `AdwSpinner` - - + + - + - + A group of preference rows. + filename="src/adw-spinner-paintable.c" + line="37">A paintable showing a loading spinner. <picture> - <source srcset="preferences-group-dark.png" media="(prefers-color-scheme: dark)"> - <img src="preferences-group.png" alt="preferences-group"> + <source srcset="spinner-dark.png" media="(prefers-color-scheme: dark)"> + <img src="spinner.png" alt="spinner"> </picture> -An `AdwPreferencesGroup` represents a group or tightly related preferences, -which in turn are represented by [class@PreferencesRow]. - -To summarize the role of the preferences it gathers, a group can have both a -title and a description. The title will be used by [class@PreferencesWindow] -to let the user look for a preference. - -## AdwPreferencesGroup as GtkBuildable - -The `AdwPreferencesGroup` implementation of the [iface@Gtk.Buildable] interface -supports adding [class@PreferencesRow]s to the list by omitting "type". If "type" -is omitted and the widget isn't a [class@PreferencesRow] the child is added to -a box below the list. - -When the "type" attribute of a child is `header-suffix`, the child -is set as the suffix on the end of the title and description. - -## CSS nodes +`AdwSpinnerPaintable` size varies depending on the available space, but is +capped at 64×64 pixels. -`AdwPreferencesGroup` has a single CSS node with name `preferencesgroup`. +To be able to animate, `AdwSpinnerPaintable` needs a widget. It will be +animated according to that widget's frame clock, and only if that widget is +mapped. Ideally it should be the same widget the paintable is displayed in, +but that's not a requirement. -## Accessibility +Most applications should be using [class@Spinner] instead. +`AdwSpinnerPaintable` is provided for the cases where using a widget is +impractical or impossible, such as [property@StatusPage:paintable]: -`AdwPreferencesGroup` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - - - - - +```xml +<object class="AdwStatusPage" id="status_page"> + <property name="paintable"> + <object class="AdwSpinnerPaintable"> + <property name="widget">status_page</property> + </object> + </property> + <!-- ... --> +</object> +``` + + + + Creates a new `AdwPreferencesGroup`. - - + filename="src/adw-spinner-paintable.c" + line="419">Creates a new `AdwSpinnerPaintable` for @widget. + + the newly created `AdwPreferencesGroup` - - - - - Adds a child to @self. - - - + filename="src/adw-spinner-paintable.c" + line="425">the newly created `AdwSpinnerPaintable` + - - a preferences group - - - + the widget to add + filename="src/adw-spinner-paintable.c" + line="421">the widget used for frame clock - - - - Gets the description of @self. - - - the description of @self - - - - - a preferences group - - - - - + + Gets the suffix for @self's header. - + filename="src/adw-spinner-paintable.c" + line="439">Gets the widget used for frame clock. + the suffix for @self's header. + filename="src/adw-spinner-paintable.c" + line="445">the widget a `AdwPreferencesGroup` - - - - - - - Gets the title of @self. - - - the title of @self - - - - - a preferences group - - - - - - Removes a child from @self. - - - - - - - a preferences group - - - - the child to remove - - - - - - - Sets the description for @self. - - - - - - - a preferences group - + filename="src/adw-spinner-paintable.c" + line="441">a spinner paintable + - - the description - - - + Sets the suffix for @self's header. - -Displayed above the list, next to the title and description. - -Suffixes are commonly used to show a button or a spinner for the whole group. - + filename="src/adw-spinner-paintable.c" + line="457">Sets the widget used for frame clock. + a `AdwPreferencesGroup` - + filename="src/adw-spinner-paintable.c" + line="459">a spinner paintable + - the suffix to set + filename="src/adw-spinner-paintable.c" + line="460">the widget to use for frame clock - - - Sets the title for @self. - - - - - - - a preferences group - - - - the title - - - - - - - - The description for this group of preferences. - - - - - + setter="set_widget" + getter="get_widget"> The header suffix widget. - -Displayed above the list, next to the title and description. - -Suffixes are commonly used to show a button or a spinner for the whole -group. + filename="src/adw-spinner-paintable.c" + line="265">The widget the spinner uses for frame clock. - - - - The title for this group of preferences. - - - - - - - + + - The parent class - - - - - - + - + final="1" + glib:type-name="AdwSplitButton" + glib:get-type="adw_split_button_get_type" + glib:type-struct="SplitButtonClass"> A page from [class@PreferencesWindow]. + filename="src/adw-split-button.c" + line="15">A combined button and dropdown widget. + +<picture> + <source srcset="split-button-dark.png" media="(prefers-color-scheme: dark)"> + <img src="split-button.png" alt="split-button"> +</picture> + +`AdwSplitButton` is typically used to present a set of actions in a menu, +but allow access to one of them with a single click. + +The API is very similar to [class@Gtk.Button] and [class@Gtk.MenuButton], see +their documentation for details. + +## CSS nodes + +``` +splitbutton[.image-button][.text-button] +├── button +│ ╰── <content> +├── separator +╰── menubutton + ╰── button.toggle + ╰── arrow +``` -<picture> - <source srcset="preferences-page-dark.png" media="(prefers-color-scheme: dark)"> - <img src="preferences-page.png" alt="preferences-page"> -</picture> +`AdwSplitButton`'s CSS node is called `splitbutton`. It contains the css +nodes: `button`, `separator`, `menubutton`. See [class@Gtk.MenuButton] +documentation for the `menubutton` contents. -The `AdwPreferencesPage` widget gathers preferences groups into a single page -of a preferences window. +The main CSS node will contain the `.image-button` or `.text-button` style +classes matching the button contents. The nested button nodes will never +contain them. -## CSS nodes +## Style classes -`AdwPreferencesPage` has a single CSS node with name `preferencespage`. +`AdwSplitButton` can use some of the same style classes as [class@Gtk.Button]: + +- [`.suggested-action`](style-classes.html#suggested-action) +- [`.destructive-action`](style-classes.html#destructive-action) +- [`.flat`](style-classes.html#flat) +- [`.raised`](style-classes.html#raised) + +Other style classes, like `.pill`, cannot be used. ## Accessibility -`AdwPreferencesPage` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - +`AdwSplitButton` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + - + Creates a new `AdwPreferencesPage`. - + filename="src/adw-split-button.c" + line="617">Creates a new `AdwSplitButton`. + the newly created `AdwPreferencesPage` + filename="src/adw-split-button.c" + line="622">the newly created `AdwSplitButton` - + Adds a preferences group to @self. - + filename="src/adw-split-button.c" + line="821">gets whether the button can be smaller than the natural size of its contents. + - + whether the button can shrink + a preferences page - + filename="src/adw-split-button.c" + line="823">a split button + - - the group to add - - - - + Gets the description of @self. - - + filename="src/adw-split-button.c" + line="768">Gets the child widget. + + the description of @self. - + filename="src/adw-split-button.c" + line="774">the child widget + a preferences page - + filename="src/adw-split-button.c" + line="770">a split button + - - + Gets the icon name for @self. - - + filename="src/adw-split-button.c" + line="953">Gets the direction in which the popup will be popped up. + + the icon name for @self - + filename="src/adw-split-button.c" + line="959">the direction + a preferences page - + filename="src/adw-split-button.c" + line="955">a split button + - - + Gets the name of @self. - - + filename="src/adw-split-button.c" + line="997">Gets the tooltip of the dropdown button of @self. + + the name of @self + filename="src/adw-split-button.c" + line="1003">the dropdown tooltip of @self a preferences page - + filename="src/adw-split-button.c" + line="999">a split button + - - + Gets the title of @self. - - + filename="src/adw-split-button.c" + line="718">Gets the name of the icon used to automatically populate the button. + + the title of @self. + filename="src/adw-split-button.c" + line="724">the icon name a preferences page - + filename="src/adw-split-button.c" + line="720">a split button + - - + Gets whether an embedded underline in the title indicates a mnemonic. - - + filename="src/adw-split-button.c" + line="630">Gets the label for @self. + + whether an embedded underline in the title indicates a mnemonic - + filename="src/adw-split-button.c" + line="636">the label for @self + a preferences page - + filename="src/adw-split-button.c" + line="632">a split button + - + Removes a group from @self. - - - + filename="src/adw-split-button.c" + line="869">Gets the menu model from which the popup will be created. + + + the menu model + a preferences page - + filename="src/adw-split-button.c" + line="871">a split button + - - the group to remove - - - + Scrolls the scrolled window of @self to the top. - - - + filename="src/adw-split-button.c" + line="913">Gets the popover that will be popped up when the dropdown is clicked. + + + the popover + a preferences page - + filename="src/adw-split-button.c" + line="915">a split button + - - + Sets the description of @self. - -The description is displayed at the top of the page. - + filename="src/adw-split-button.c" + line="679">Gets whether an underline in the text indicates a mnemonic. + - + whether an underline in the text indicates a mnemonic + a preferences page - + filename="src/adw-split-button.c" + line="681">a split button + - - the description - - - - + Sets the icon name for @self. - + filename="src/adw-split-button.c" + line="1063">Dismisses the menu. + a preferences page - + filename="src/adw-split-button.c" + line="1065">a split button + - - the icon name - - - - + Sets the name of @self. - + filename="src/adw-split-button.c" + line="1049">Pops up the menu. + a preferences page - + filename="src/adw-split-button.c" + line="1051">a split button + - - the name - - - - + Sets the title of @self. - + filename="src/adw-split-button.c" + line="839">Sets whether the button can be smaller than the natural size of its contents. + +If set to `TRUE`, the label will ellipsize. + +See [method@Gtk.Button.set_can_shrink] and +[method@Gtk.MenuButton.set_can_shrink]. + a preferences page - + filename="src/adw-split-button.c" + line="841">a split button + - + the title - + filename="src/adw-split-button.c" + line="842">whether the button can shrink + - - + Sets whether an embedded underline in the title indicates a mnemonic. - + filename="src/adw-split-button.c" + line="784">Sets the child widget. + +Setting the child widget will set [property@SplitButton:label] and +[property@SplitButton:icon-name] to `NULL`. + a preferences page - + filename="src/adw-split-button.c" + line="786">a split button + - + `TRUE` if underlines in the text indicate mnemonics - + filename="src/adw-split-button.c" + line="787">the new child widget + - - - - The description to be displayed at the top of the page. - - - - - - The icon name for this page. - - - - - - The name of this page. - - - - - - The title for this page. - - - - - - Whether an embedded underline in the title indicates a mnemonic. - - - - - - - - - + The parent class - - - - - - - - - - A [class@Gtk.ListBoxRow] used to present preferences. + filename="src/adw-split-button.c" + line="969">Sets the direction in which the popup will be popped up. -The `AdwPreferencesRow` widget has a title that [class@PreferencesWindow] -will use to let the user look for a preference. It doesn't present the title -in any way and lets you present the preference as you please. +The dropdown arrow icon will point at the same direction. -[class@ActionRow] and its derivatives are convenient to use as preference -rows as they take care of presenting the preference's title while letting you -compose the inputs of the preference around it. - - - - - - - Creates a new `AdwPreferencesRow`. - - - the newly created `AdwPreferencesRow` - - - - - - Gets the title of the preference represented by @self. - +If the does not fit in the available space in the given direction, GTK will +try its best to keep it inside the screen and fully visible. + +If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`. + - the title - + a preferences row - + filename="src/adw-split-button.c" + line="971">a split button + - - - - - Gets whether the user can copy the title from the label - - - whether the user can copy the title from the label - - - - + a `AdwPreferencesRow` - - + filename="src/adw-split-button.c" + line="972">the direction + + - - Gets whether to use Pango markup for the title label. - + filename="src/adw-split-button.c" + line="1018">Sets the tooltip of the dropdown button of @self. + +The tooltip can be marked up with the Pango text markup language. + - whether to use markup - + a preferences row - + filename="src/adw-split-button.c" + line="1020">a split button + + + the dropdown tooltip of @self + + - - + Gets whether an embedded underline in the title indicates a mnemonic. - + filename="src/adw-split-button.c" + line="734">Sets the name of the icon used to automatically populate the button. + +Setting the icon name will set [property@SplitButton:label] and +[property@SplitButton:child] to `NULL`. + - whether an embedded underline in the title indicates a mnemonic - + a preferences row - + filename="src/adw-split-button.c" + line="736">a split button + + + the icon name to set + + - - + Sets the title of the preference represented by @self. + filename="src/adw-split-button.c" + line="646">Sets the label for @self. -The title is interpreted as Pango markup unless -[property@PreferencesRow:use-markup] is set to `FALSE`. - +Setting the label will set [property@SplitButton:icon-name] and +[property@SplitButton:child] to `NULL`. + a preferences row - + filename="src/adw-split-button.c" + line="648">a split button + - + the title + filename="src/adw-split-button.c" + line="649">the label to set - - + Sets whether the user can copy the title from the label + filename="src/adw-split-button.c" + line="885">Sets the menu model from which the popup will be created. -See also [property@Gtk.Label:selectable]. - +If the menu model is `NULL`, the dropdown is disabled. + +A [class@Gtk.Popover] will be created from the menu model with +[ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as +documented for this function. + +If [property@SplitButton:popover] is already set, it will be dissociated from +the button, and the property is set to `NULL`. + a `AdwPreferencesRow` - + filename="src/adw-split-button.c" + line="887">a split button + - + `TRUE` if the user can copy the title from the label - + filename="src/adw-split-button.c" + line="888">the menu model + - - + Sets whether to use Pango markup for the title label. + filename="src/adw-split-button.c" + line="929">Sets the popover that will be popped up when the dropdown is clicked. -Subclasses may also use it for other labels, such as subtitle. +If the popover is `NULL`, the dropdown is disabled. -See also [func@Pango.parse_markup]. - +If [property@SplitButton:menu-model] is set, the menu model is dissociated +from the button, and the property is set to `NULL`. + a preferences row - + filename="src/adw-split-button.c" + line="931">a split button + - + whether to use markup - + filename="src/adw-split-button.c" + line="932">the popover + - Sets whether an embedded underline in the title indicates a mnemonic. - + filename="src/adw-split-button.c" + line="695">Sets whether an underline in the text indicates a mnemonic. + +See [property@SplitButton:label]. + a preferences row - + filename="src/adw-split-button.c" + line="697">a split button + `TRUE` if underlines in the text indicate mnemonics + filename="src/adw-split-button.c" + line="698">whether an underline in the text indicates a mnemonic - - - + setter="set_can_shrink" + getter="get_can_shrink" + default-value="FALSE"> The title of the preference represented by this row. + filename="src/adw-split-button.c" + line="353">Whether the button can be smaller than the natural size of its contents. -The title is interpreted as Pango markup unless -[property@PreferencesRow:use-markup] is set to `FALSE`. - +If set to `TRUE`, the label will ellipsize. + +See [property@Gtk.Button:can-shrink] and +[property@Gtk.MenuButton:can-shrink]. + - - - + setter="set_child" + getter="get_child"> Whether the user can copy the title from the label. + filename="src/adw-split-button.c" + line="340">The child widget. -See also [property@Gtk.Label:selectable]. - +Setting the child widget will set [property@SplitButton:label] and +[property@SplitButton:icon-name] to `NULL`. + - + The direction in which the popup will be popped up. + +The dropdown arrow icon will point at the same direction. + +If the does not fit in the available space in the given direction, GTK will +try its best to keep it inside the screen and fully visible. + +If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`. + + + - - + setter="set_dropdown_tooltip" + getter="get_dropdown_tooltip"> Whether to use Pango markup for the title label. + filename="src/adw-split-button.c" + line="422">The tooltip of the dropdown button. -Subclasses may also use it for other labels, such as subtitle. +The tooltip can be marked up with the Pango text markup language. + + + + The name of the icon used to automatically populate the button. -See also [func@Pango.parse_markup]. - +Setting the icon name will set [property@SplitButton:label] and +[property@SplitButton:child] to `NULL`. + + + + The label for the button. + +Setting the label will set [property@SplitButton:icon-name] and +[property@SplitButton:child] to `NULL`. + + + + The `GMenuModel` from which the popup will be created. + +If the menu model is `NULL`, the dropdown is disabled. + +A [class@Gtk.Popover] will be created from the menu model with +[ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as +documented for this function. + +If [property@SplitButton:popover] is already set, it will be dissociated +from the button, and the property is set to `NULL`. + + + + The `GtkPopover` that will be popped up when the dropdown is clicked. + +If the popover is `NULL`, the dropdown is disabled. + +If [property@SplitButton:menu-model] is set, the menu model is dissociated +from the button, and the property is set to `NULL`. + setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - Whether an embedded underline in the title indicates a mnemonic. + filename="src/adw-split-button.c" + line="315">Whether an underline in the text indicates a mnemonic. + +See [property@SplitButton:label]. - - - + + Emitted to animate press then release. + +This is an action signal. Applications should never connect to this signal, +but use the [signal@SplitButton::clicked] signal. + + + + + + Emitted when the button has been activated (pressed and released). + + + + - - + + - The parent class - - - - - - + - + A window to present an application's preferences. + filename="src/adw-spring-animation.c" + line="18">A spring-based [class@Animation]. -<picture> - <source srcset="preferences-window-dark.png" media="(prefers-color-scheme: dark)"> - <img src="preferences-window.png" alt="preferences-window"> -</picture> +`AdwSpringAnimation` implements an animation driven by a physical model of a +spring described by [struct@SpringParams], with a resting position in +[property@SpringAnimation:value-to], stretched to +[property@SpringAnimation:value-from]. -The `AdwPreferencesWindow` widget presents an application's preferences -gathered into pages and groups. The preferences are searchable by the user. +Since the animation is physically simulated, spring animations don't have a +fixed duration. The animation will stop when the simulated spring comes to a +rest - when the amplitude of the oscillations becomes smaller than +[property@SpringAnimation:epsilon], or immediately when it reaches +[property@SpringAnimation:value-to] if +[property@SpringAnimation:clamp] is set to `TRUE`. The estimated duration can +be obtained with [property@SpringAnimation:estimated-duration]. -## CSS nodes +Due to the nature of spring-driven motion the animation can overshoot +[property@SpringAnimation:value-to] before coming to a rest. Whether the +animation will overshoot or not depends on the damping ratio of the spring. +See [struct@SpringParams] for more information about specific damping ratio +values. -`AdwPreferencesWindow` has a main CSS node with the name `window` and the -style class `.preferences`. - - - - - - - - +If [property@SpringAnimation:clamp] is `TRUE`, the animation will abruptly +end as soon as it reaches the final value, preventing overshooting. + +Animations can have an initial velocity value, set via +[property@SpringAnimation:initial-velocity], which adjusts the curve without +changing the duration. This makes spring animations useful for deceleration +at the end of gestures. + +If the initial and final values are equal, and the initial velocity is not 0, +the animation value will bounce and return to its resting position. + + Creates a new `AdwPreferencesWindow`. - + filename="src/adw-spring-animation.c" + line="531">Creates a new `AdwSpringAnimation` on @widget. + +The animation will animate @target from @from to @to with the dynamics of a +spring described by @spring_params. + the newly created `AdwPreferencesWindow` - + filename="src/adw-spring-animation.c" + line="544">the newly created animation + + + + a widget to create animation on + + + + a value to animate from + + + + a value to animate to + + + + physical parameters of the spring + + + + a target value to animate + + + - + Adds a preferences page to @self. - + filename="src/adw-spring-animation.c" + line="835">Calculates the value @self will have at @time. + +The time starts at 0 and ends at +[property@SpringAnimation:estimated_duration]. + +See also [method@SpringAnimation.calculate_velocity]. + - + the value at @time + a preferences window - + filename="src/adw-spring-animation.c" + line="837">a spring animation + - + the page to add - + filename="src/adw-spring-animation.c" + line="838">elapsed time, in milliseconds + - + Displays @toast. + filename="src/adw-spring-animation.c" + line="860">Calculates the velocity @self will have at @time. -See [method@ToastOverlay.add_toast]. - +The time starts at 0 and ends at +[property@SpringAnimation:estimated_duration]. + +See also [method@SpringAnimation.calculate_value]. + - + the velocity at @time + a preferences window - + filename="src/adw-spring-animation.c" + line="862">a spring animation + - + a toast - + filename="src/adw-spring-animation.c" + line="863">elapsed time, in milliseconds + - + Closes the current subpage. - -If there is no presented subpage, this does nothing. - Use [method@PreferencesWindow.pop_subpage] instead. - + filename="src/adw-spring-animation.c" + line="790">Gets whether @self should be clamped. + - + whether @self is clamped + a preferences window - + filename="src/adw-spring-animation.c" + line="792">a spring animation + - - + Gets whether gestures and shortcuts for closing subpages are enabled. - Use [method@NavigationPage.get_can_pop] instead. - + filename="src/adw-spring-animation.c" + line="739">Gets the precision of the spring. + whether gestures and shortcuts are enabled. - + filename="src/adw-spring-animation.c" + line="745">the epsilon value + a preferences window - + filename="src/adw-spring-animation.c" + line="741">a spring animation + + + + + + Gets the estimated duration of @self, in milliseconds. + +Can be [const@DURATION_INFINITE] if the spring damping is set to 0. + + + the estimated duration + + + + + a spring animation + - - + Gets whether search is enabled for @self. - + filename="src/adw-spring-animation.c" + line="698">Gets the initial velocity of @self. + whether search is enabled for @self. - + filename="src/adw-spring-animation.c" + line="704">the initial velocity + a preferences window - + filename="src/adw-spring-animation.c" + line="700">a spring animation + - + Gets the currently visible page of @self. - - + filename="src/adw-spring-animation.c" + line="657">Gets the physical parameters of the spring of @self. + + the visible page - + filename="src/adw-spring-animation.c" + line="663">the spring parameters + a preferences window - + filename="src/adw-spring-animation.c" + line="659">a spring animation + - + Gets the name of currently visible page of @self. - - + filename="src/adw-spring-animation.c" + line="573">Gets the value @self will animate from. + + the name of the visible page - + filename="src/adw-spring-animation.c" + line="579">the value to animate from + a preferences window - + filename="src/adw-spring-animation.c" + line="575">a spring animation + - + Pop the visible page from the subpage stack of @self. - + filename="src/adw-spring-animation.c" + line="615">Gets the value @self will animate to. + `TRUE` if a page has been popped - + filename="src/adw-spring-animation.c" + line="621">the value to animate to + a preferences window - + filename="src/adw-spring-animation.c" + line="617">a spring animation + - + Sets @subpage as the window's subpage and opens it. - -The transition can be cancelled by the user, in which case visible child will -change back to the previously visible child. - Use [method@PreferencesWindow.push_subpage] instead. - + filename="src/adw-spring-animation.c" + line="907">Gets the current velocity of @self. + - + the current velocity + a preferences window - + filename="src/adw-spring-animation.c" + line="909">a spring animation + - - the subpage - - - + Pushes @page onto the subpage stack of @self. + filename="src/adw-spring-animation.c" + line="806">Sets whether @self should be clamped. -The page will be automatically removed when popped. - +If set to `TRUE`, the animation will abruptly end as soon as it reaches the +final value, preventing overshooting. + +It won't prevent overshooting [property@SpringAnimation:value-from] if a +relative negative [property@SpringAnimation:initial-velocity] is set. + a preferences window - + filename="src/adw-spring-animation.c" + line="808">a spring animation + - + the subpage - + filename="src/adw-spring-animation.c" + line="809">the new value + - + Removes a page from @self. - + filename="src/adw-spring-animation.c" + line="755">Sets the precision of the spring. + +The level of precision used to determine when the animation has come to a +rest, that is, when the amplitude of the oscillations becomes smaller than +this value. + +If the epsilon value is too small, the animation will take a long time to +stop after the animated value has stopped visibly changing. + +If the epsilon value is too large, the animation will end prematurely. + +The default value is 0.001. + a preferences window - + filename="src/adw-spring-animation.c" + line="757">a spring animation + - + the page to remove - + filename="src/adw-spring-animation.c" + line="758">the new value + - - + Sets whether gestures and shortcuts for closing subpages are enabled. - -The supported gestures are: - -- One-finger swipe on touchscreens -- Horizontal scrolling on touchpads (usually two-finger swipe) -- Back mouse button - -The keyboard back key is also supported, as well as the -<kbd>Alt</kbd>+<kbd>←</kbd> shortcut. - -For right-to-left locales, gestures and shortcuts are reversed. - Use [method@NavigationPage.set_can_pop] instead. + filename="src/adw-spring-animation.c" + line="714">Sets the initial velocity of @self. -Has no effect for subpages added with [method@PreferencesWindow.push_subpage]. - +Initial velocity affects only the animation curve, but not its duration. + a preferences window - + filename="src/adw-spring-animation.c" + line="716">a spring animation + - + the new value - + filename="src/adw-spring-animation.c" + line="717">the initial velocity + - - + Sets whether search is enabled for @self. - + filename="src/adw-spring-animation.c" + line="673">Sets the physical parameters of the spring of @self. + a preferences window - + filename="src/adw-spring-animation.c" + line="675">a spring animation + - + whether search is enabled - + filename="src/adw-spring-animation.c" + line="676">the new spring parameters + - + Makes @page the visible page of @self. - + filename="src/adw-spring-animation.c" + line="589">Sets the value @self will animate from. + +The animation will start at this value and end at +[property@SpringAnimation:value-to]. + a preferences window - + filename="src/adw-spring-animation.c" + line="591">a spring animation + - + a page of @self - + filename="src/adw-spring-animation.c" + line="592">the value to animate from + - + Makes the page with the given name visible. + filename="src/adw-spring-animation.c" + line="631">Sets the value @self will animate to. -See [property@ViewStack:visible-child]. - +The animation will start at [property@SpringAnimation:value-from] and end at +this value. + a preferences window - + filename="src/adw-spring-animation.c" + line="633">a spring animation + - + the name of the page to make visible - + filename="src/adw-spring-animation.c" + line="634">the value to animate to + - - - Whether gestures and shortcuts for closing subpages are enabled. + filename="src/adw-spring-animation.c" + line="480">Whether the animation should be clamped. -The supported gestures are: +If set to `TRUE`, the animation will abruptly end as soon as it reaches the +final value, preventing overshooting. -- One-finger swipe on touchscreens -- Horizontal scrolling on touchpads (usually two-finger swipe) -- Back mouse button +It won't prevent overshooting [property@SpringAnimation:value-from] if a +relative negative [property@SpringAnimation:initial-velocity] is set. + + + + Precision of the spring. -The keyboard back key is also supported, as well as the -<kbd>Alt</kbd>+<kbd>←</kbd> shortcut. +The level of precision used to determine when the animation has come to a +rest, that is, when the amplitude of the oscillations becomes smaller than +this value. -For right-to-left locales, gestures and shortcuts are reversed. - Use [property@NavigationPage:can-pop] instead. +If the epsilon value is too small, the animation will take a long time to +stop after the animated value has stopped visibly changing. -Has no effect for subpages added with -[method@PreferencesWindow.push_subpage]. - +If the epsilon value is too large, the animation will end prematurely. + +The default value is 0.001. + - + Estimated duration of the animation, in milliseconds. + +Can be [const@DURATION_INFINITE] if the spring damping is set to 0. + + + - - + setter="set_initial_velocity" + getter="get_initial_velocity" + default-value="0.000000"> Whether search is enabled. - + filename="src/adw-spring-animation.c" + line="443">The initial velocity to start the animation with. + +Initial velocity affects only the animation curve, but not its duration. + - - + setter="set_spring_params" + getter="get_spring_params"> + Physical parameters describing the spring. + - - + setter="set_value_from" + getter="get_value_from" + default-value="0.000000"> + The value to animate from. + +The animation will start at this value and end at +[property@SpringAnimation:value-to]. + - - - - - - - + The parent class - - - - - - - + filename="src/adw-spring-animation.c" + line="418">The value to animate to. + +The animation will start at [property@SpringAnimation:value-from] and end +at this value. + + + + Current velocity of the animation. + + + + + - + An [class@AnimationTarget] changing the value of a property of a -[class@GObject.Object] instance. - - + filename="src/adw-spring-params.c" + line="16">Physical parameters of a spring for [class@SpringAnimation]. + +Any spring can be described by three parameters: mass, stiffness and damping. + +An undamped spring will produce an oscillatory motion which will go on +forever. + +The frequency and amplitude of the oscillations will be determined by the +stiffness (how "strong" the spring is) and its mass (how much "inertia" it +has). + +If damping is larger than 0, the amplitude of that oscillating motion will +exponientally decrease over time. If that damping is strong enough that the +spring can't complete a full oscillation, it's called an overdamped spring. + +If we the spring can oscillate, it's called an underdamped spring. + +The value between these two behaviors is called critical damping; a +critically damped spring will comes to rest in the minimum possible time +without producing oscillations. + +The damping can be replaced by damping ratio, which produces the following +springs: + +* 0: an undamped spring. +* Between 0 and 1: an underdamped spring. +* 1: a critically damped spring. +* Larger than 1: an overdamped spring. + +As such + + Creates a new `AdwPropertyAnimationTarget` for the @property_name property on -@object. - + filename="src/adw-spring-params.c" + line="60">Creates a new `AdwSpringParams` from @mass, @stiffness and @damping_ratio. + +The damping value is calculated from @damping_ratio and the other two +parameters. + +* If @damping_ratio is 0, the spring will not be damped and will oscillate + endlessly. +* If @damping_ratio is between 0 and 1, the spring is underdamped and will + always overshoot. +* If @damping_ratio is 1, the spring is critically damped and will reach its + resting position the quickest way possible. +* If @damping_ratio is larger than 1, the spring is overdamped and will reach + its resting position faster than it can complete an oscillation. + +[ctor@SpringParams.new_full] allows to pass a raw damping value instead. + the newly created `AdwPropertyAnimationTarget` - + filename="src/adw-spring-params.c" + line="82">the newly created spring parameters + - + an object to be animated - + filename="src/adw-spring-params.c" + line="62">the damping ratio of the spring + - + the name of the property on @object to animate - + filename="src/adw-spring-params.c" + line="63">the mass of the spring + + + + the stiffness of the spring + - + Creates a new `AdwPropertyAnimationTarget` for the @pspec property on -@object. - + filename="src/adw-spring-params.c" + line="99">Creates a new `AdwSpringParams` from @mass, @stiffness and @damping. + +See [ctor@SpringParams.new] for a simplified constructor using damping ratio +instead of @damping. + new newly created `AdwPropertyAnimationTarget` - + filename="src/adw-spring-params.c" + line="110">the newly created spring parameters + - + an object to be animated - + filename="src/adw-spring-params.c" + line="101">the damping of the spring + - + the param spec of the property on @object to animate - + filename="src/adw-spring-params.c" + line="102">the mass of the spring + + + + the stiffness of the spring + - - + Gets the object animated by @self. - -The `AdwPropertyAnimationTarget` instance does not hold a strong reference on -the object; make sure the object is kept alive throughout the target's -lifetime. - + filename="src/adw-spring-params.c" + line="169">Gets the damping of @self. + the animated object - + filename="src/adw-spring-params.c" + line="175">the damping + a property animation target - + filename="src/adw-spring-params.c" + line="171">spring params + - - + Gets the `GParamSpec` of the property animated by @self. - + filename="src/adw-spring-params.c" + line="185">Gets the damping ratio of @self. + the animated property's `GParamSpec` - + filename="src/adw-spring-params.c" + line="191">the damping ratio + a property animation target - + filename="src/adw-spring-params.c" + line="187">spring params + - - - The object whose property will be animated. - -The `AdwPropertyAnimationTarget` instance does not hold a strong reference -on the object; make sure the object is kept alive throughout the target's -lifetime. - - - - + The `GParamSpec` of the property to be animated. - - - - - - - - Describes the possible styles of [class@MessageDialog] response buttons. - -See [method@MessageDialog.set_response_appearance]. - + filename="src/adw-spring-params.c" + line="205">Gets the mass of @self. + + + the mass + + + + + spring params + + + + + the default appearance. - - + filename="src/adw-spring-params.c" + line="221">Gets the stiffness of @self. + + + the stiffness + + + + + spring params + + + + + used to denote important responses such as the - affirmative action. - - + filename="src/adw-spring-params.c" + line="134">Increases the reference count of @self. + + + @self + + + + + spring params + + + + + used to draw attention to the potentially damaging - consequences of using the response. This appearance acts as a warning to - the user. - - - Decreases the reference count of @self. + +If the last reference is dropped, the structure is freed. + + + + + + + spring params + + + + + + + glib:type-name="AdwSqueezer" + glib:get-type="adw_squeezer_get_type" + glib:type-struct="SqueezerClass"> An [class@ActionRow] with an embedded spin button. + filename="src/adw-squeezer.c" + line="26">A best fit container. <picture> - <source srcset="spin-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="spin-row.png" alt="spin-row"> + <source srcset="squeezer-wide-dark.png" media="(prefers-color-scheme: dark)"> + <img src="squeezer-wide.png" alt="squeezer-wide"> +</picture> +<picture> + <source srcset="squeezer-narrow-dark.png" media="(prefers-color-scheme: dark)"> + <img src="squeezer-narrow.png" alt="squeezer-narrow"> </picture> -Example of an `AdwSpinRow` UI definition: - -```xml -<object class="AdwSpinRow"> - <property name="title" translatable="yes">Spin Row</property> - <property name="adjustment"> - <object class="GtkAdjustment"> - <property name="lower">0</property> - <property name="upper">100</property> - <property name="value">50</property> - <property name="page-increment">10</property> - <property name="step-increment">1</property> - </object> - </property> -</object> -``` +The `AdwSqueezer` widget is a container which only shows the first of its +children that fits in the available size. It is convenient to offer different +widgets to represent the same data with different levels of detail, making +the widget seem to squeeze itself to fit in the available space. -See [class@Gtk.SpinButton] for details. +Transitions between children can be animated as fades. This can be controlled +with [property@Squeezer:transition-type]. ## CSS nodes -`AdwSpinRow` has the same structure as [class@ActionRow], as well as the -`.spin` style class on the main node. - +`AdwSqueezer` has a single CSS node with name `squeezer`. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - - - + + Creates a new `AdwSpinRow`. - + filename="src/adw-squeezer.c" + line="1335">Creates a new `AdwSqueezer`. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + the newly created `AdwSpinRow` + filename="src/adw-squeezer.c" + line="1340">the newly created `AdwSqueezer` + + + Adds a child to @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + the [class@SqueezerPage] for @child + + - - the adjustment that this spin row should use - - - + the rate the value changes when holding a button or key - - - + filename="src/adw-squeezer.c" + line="1352">a squeezer + + + the number of decimal places to display - + filename="src/adw-squeezer.c" + line="1353">the widget to add + - - + + Creates a new `AdwSpinRow` with the given properties. - -This is a convenience constructor that allows creation of a numeric -`AdwSpinRow` without manually creating an adjustment. The value is initially -set to the minimum value and a page increment of 10 * @step is the default. -The precision of the spin row is equivalent to the precisions of @step. - -Note that the way in which the precision is derived works best if @step is a -power of ten. If the resulting precision is not suitable for your needs, -use [method@SpinRow.set_digits] to correct it. - + filename="src/adw-squeezer.c" + line="1556">Gets whether to allow squeezing beyond the last child's minimum size. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + the new `AdwSpinRow` - + filename="src/adw-squeezer.c" + line="1562">whether @self allows squeezing beyond the last child + - - minimum allowable value - - - - maximum allowable value - - - + increment added or subtracted by spinning the widget - - + filename="src/adw-squeezer.c" + line="1558">a squeezer + + - - + + Changes the properties of an existing spin row. - -The adjustment, climb rate, and number of decimal places are updated -accordingly. - + filename="src/adw-squeezer.c" + line="1452">Gets whether all children have the same size for the opposite orientation. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - + whether @self is homogeneous + a spin row - + filename="src/adw-squeezer.c" + line="1454">a squeezer + - + + + + Gets whether @self interpolates its size when changing the visible child. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + whether the size is interpolated + + + + the adjustment that this spin row should use - - - + filename="src/adw-squeezer.c" + line="1710">A squeezer + + + + + + Returns the [class@SqueezerPage] object for @child. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + the page object for @child + + + + the new climb rate - - - + filename="src/adw-squeezer.c" + line="1415">a squeezer + + + the number of decimal places to display - + filename="src/adw-squeezer.c" + line="1416">a child of @self + - - + Gets the adjustment that holds the value for the spin row. - - + filename="src/adw-squeezer.c" + line="1853">Returns a [iface@Gio.ListModel] that contains the pages of @self. + +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track the visible page. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + the adjustment that holds the spin row's value - + filename="src/adw-squeezer.c" + line="1862">a `GtkSelectionModel` for the squeezer's children + a spin row - + filename="src/adw-squeezer.c" + line="1855">a squeezer + - - + Gets the acceleration rate when you hold down a button or key. - + filename="src/adw-squeezer.c" + line="1502">Gets the switch threshold policy for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + the acceleration rate when you hold down a button or key - + filename="src/adw-squeezer.c" + line="1508">the fold threshold policy + a spin row - + filename="src/adw-squeezer.c" + line="1504">a squeezer + - - + Gets the number of decimal places to display. - + filename="src/adw-squeezer.c" + line="1605">Gets the transition animation duration for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + the number of decimal places to display + filename="src/adw-squeezer.c" + line="1611">the transition duration, in milliseconds a spin row - + filename="src/adw-squeezer.c" + line="1607">a squeezer + - - + Gets whether non-numeric characters should be ignored. - + filename="src/adw-squeezer.c" + line="1686">Gets whether a transition is currently running for @self. + +If a transition is impossible, the property value will be set to `TRUE` and +then immediately to `FALSE`, so it's possible to rely on its notifications +to know that a transition has happened. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + whether non-numeric characters should be ignored. + filename="src/adw-squeezer.c" + line="1696">whether a transition is currently running a spin row - + filename="src/adw-squeezer.c" + line="1688">a squeezer + - - + Gets whether invalid values are snapped to nearest step increment. - + filename="src/adw-squeezer.c" + line="1646">Gets the type of animation used for transitions between children in @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + whether invalid values are snapped to the nearest step increment - + filename="src/adw-squeezer.c" + line="1652">the current transition type of @self + a spin row - + filename="src/adw-squeezer.c" + line="1648">a squeezer + - - + Gets the policy for updating the spin row. - - + filename="src/adw-squeezer.c" + line="1434">Gets the currently visible child of @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + the policy for updating the spin row - + filename="src/adw-squeezer.c" + line="1440">the visible child + a spin row - + filename="src/adw-squeezer.c" + line="1436">a squeezer + - - + Gets the current value. - + filename="src/adw-squeezer.c" + line="1755">Gets the horizontal alignment, from 0 (start) to 1 (end). + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + the current value - + filename="src/adw-squeezer.c" + line="1761">the alignment value + a spin row - + filename="src/adw-squeezer.c" + line="1757">a squeezer + - - + Gets whether the spin row should wrap upon reaching its limits. - + filename="src/adw-squeezer.c" + line="1804">Gets the vertical alignment, from 0 (top) to 1 (bottom). + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + whether the spin row should wrap upon reaching its limits - + filename="src/adw-squeezer.c" + line="1810">the alignment value + a spin row - + filename="src/adw-squeezer.c" + line="1806">a squeezer + - - + Sets the adjustment that holds the value for the spin row. - + filename="src/adw-squeezer.c" + line="1380">Removes a child widget from @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1382">a squeezer + - + an adjustment - + filename="src/adw-squeezer.c" + line="1383">the child to remove + - - + Sets the acceleration rate when you hold down a button or key. - + filename="src/adw-squeezer.c" + line="1574">Sets whether to allow squeezing beyond the last child's minimum size. + +If set to `TRUE`, the squeezer can shrink to the point where no child can be +shown. This is functionally equivalent to appending a widget with 0×0 minimum +size. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1576">a squeezer + - + the acceleration rate when you hold down a button or key - + filename="src/adw-squeezer.c" + line="1577">whether @self allows squeezing beyond the last child + - - + Sets the number of decimal places to display. - + filename="src/adw-squeezer.c" + line="1470">Sets whether all children have the same size for the opposite orientation. + +For example, if a squeezer is horizontal and is homogeneous, it will request +the same height for all its children. If it isn't, the squeezer may change +size when a different child becomes visible. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1472">a squeezer + - + the number of decimal places to display - + filename="src/adw-squeezer.c" + line="1473">whether @self is homogeneous + - - + Sets whether non-numeric characters should be ignored. - + filename="src/adw-squeezer.c" + line="1726">Sets whether @self interpolates its size when changing the visible child. + +If `TRUE`, the squeezer will interpolate its size between the one of the +previous visible child and the one of the new visible child, according to the +set transition duration and the orientation, e.g. if the squeezer is +horizontal, it will interpolate the its height. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1728">A squeezer + - + whether non-numeric characters should be ignored + filename="src/adw-squeezer.c" + line="1729">whether to interpolate the size - + Sets the minimum and maximum allowable values for @self. + filename="src/adw-squeezer.c" + line="1521">Sets the switch threshold policy for @self. -If the current value is outside this range, it will be adjusted -to fit within the range, otherwise it will remain unchanged. - +Determines when the squeezer will switch children. + +If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the +visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, +it will switch as soon as the visible child doesn't get their natural size. + +This can be useful if you have a long ellipsizing label and want to let it +ellipsize instead of immediately switching. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1523">a squeezer + - - minimum allowable value - - - + maximum allowable value - + filename="src/adw-squeezer.c" + line="1524">the policy to use + - - + Sets whether invalid values are snapped to the nearest step increment. - + filename="src/adw-squeezer.c" + line="1623">Sets the transition animation duration for @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1625">a squeezer + - + whether invalid values are snapped to the nearest step increment - + filename="src/adw-squeezer.c" + line="1626">the new duration, in milliseconds + - - + Sets the policy for updating the spin row. - -The options are always, or only when the value is invalid. - + filename="src/adw-squeezer.c" + line="1664">Sets the type of animation used for transitions between children in @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1666">a squeezer + - + the policy for updating the spin row - + filename="src/adw-squeezer.c" + line="1667">the new transition type + - - + Sets the current value. - + filename="src/adw-squeezer.c" + line="1773">Sets the horizontal alignment, from 0 (start) to 1 (end). + +This affects the children allocation during transitions, when they exceed the +size of the squeezer. + +For example, 0.5 means the child will be centered, 0 means it will keep the +start side aligned and overflow the end side, and 1 means the opposite. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1775">a squeezer + - + a new value - + filename="src/adw-squeezer.c" + line="1776">the new alignment value + - - + Sets whether the spin row should wrap upon reaching its limits. - + filename="src/adw-squeezer.c" + line="1822">Sets the vertical alignment, from 0 (top) to 1 (bottom). + +This affects the children allocation during transitions, when they exceed the +size of the squeezer. + +For example, 0.5 means the child will be centered, 0 means it will keep the +top side aligned and overflow the bottom side, and 1 means the opposite. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + a spin row - + filename="src/adw-squeezer.c" + line="1824">a squeezer + - + whether the spin row should wrap upon reaching its limits - + filename="src/adw-squeezer.c" + line="1825">the new alignment value + - + Manually force an update of the spin row. - - - - - - - a spin row - - - - - Whether to allow squeezing beyond the last child's minimum size. + +If set to `TRUE`, the squeezer can shrink to the point where no child can +be shown. This is functionally equivalent to appending a widget with 0×0 +minimum size. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + - - + setter="set_homogeneous" + getter="get_homogeneous" + default-value="FALSE"> The adjustment that holds the value of the spin row. - + filename="src/adw-squeezer.c" + line="1044">Whether all children have the same size for the opposite orientation. + +For example, if a squeezer is horizontal and is homogeneous, it will +request the same height for all its children. If it isn't, the squeezer may +change size when a different child becomes visible. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - + Whether the squeezer interpolates its size when changing the visible child. + +If `TRUE`, the squeezer will interpolate its size between the one of the +previous visible child and the one of the new visible child, according to +the set transition duration and the orientation, e.g. if the squeezer is +horizontal, it will interpolate the its height. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + + A selection model with the squeezer's pages. + +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track the visible page. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + - - + setter="set_switch_threshold_policy" + getter="get_switch_threshold_policy" + default-value="ADW_FOLD_THRESHOLD_POLICY_NATURAL"> The acceleration rate when you hold down a button or key. - + filename="src/adw-squeezer.c" + line="1060">The switch threshold policy. + +Determines when the squeezer will switch children. + +If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the +visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, +it will switch as soon as the visible child doesn't get their natural size. + +This can be useful if you have a long ellipsizing label and want to let it +ellipsize instead of immediately switching. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - - - + setter="set_transition_duration" + getter="get_transition_duration" + default-value="200"> The number of decimal places to display. + filename="src/adw-squeezer.c" + line="1098">The transition animation duration, in milliseconds. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - Whether non-numeric characters should be ignored. + filename="src/adw-squeezer.c" + line="1123">Whether a transition is currently running. + +If a transition is impossible, the property value will be set to `TRUE` and +then immediately to `FALSE`, so it's possible to rely on its notifications +to know that a transition has happened. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - + setter="set_transition_type" + getter="get_transition_type" + default-value="ADW_SQUEEZER_TRANSITION_TYPE_NONE"> Whether invalid values are snapped to the nearest step increment. - + filename="src/adw-squeezer.c" + line="1110">The type of animation used for transitions between children. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - - - + getter="get_visible_child"> The policy for updating the spin row. - -The options are always, or only when the value is invalid. - + filename="src/adw-squeezer.c" + line="1032">The currently visible child. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - - - + setter="set_xalign" + getter="get_xalign" + default-value="0.500000"> The current value. - + filename="src/adw-squeezer.c" + line="1156">The horizontal alignment, from 0 (start) to 1 (end). + +This affects the children allocation during transitions, when they exceed +the size of the squeezer. + +For example, 0.5 means the child will be centered, 0 means it will keep the +start side aligned and overflow the end side, and 1 means the opposite. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - - - - Whether the spin row should wrap upon reaching its limits. - - - + setter="set_yalign" + getter="get_yalign" + default-value="0.500000"> Emitted to convert the user's input into a double value. - -The signal handler is expected to use [method@Gtk.Editable.get_text] to -retrieve the text of the spinbutton and set new_value to the new value. + filename="src/adw-squeezer.c" + line="1175">The vertical alignment, from 0 (top) to 1 (bottom). -The default conversion uses [func@GLib.strtod]. +This affects the children allocation during transitions, when they exceed +the size of the squeezer. -See [signal@Gtk.SpinButton::input]. +For example, 0.5 means the child will be centered, 0 means it will keep the +top side aligned and overflow the bottom side, and 1 means the opposite. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + + + + + + + + + An auxiliary class used by [class@Squeezer]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + Returns the squeezer child to which @self belongs. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + `TRUE` for a successful conversion, `FALSE` if the input was not - handled, and `GTK_INPUT_ERROR` if the conversion failed. - + filename="src/adw-squeezer.c" + line="1264">the child to which @self belongs + - + return location for the new value - - + filename="src/adw-squeezer.c" + line="1260">a squeezer page + + - - + + Emitted to tweak the formatting of the value for display. - -See [signal@Gtk.SpinButton::output]. + filename="src/adw-squeezer.c" + line="1276">Gets whether @self is enabled. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + `TRUE` if the value has been displayed + filename="src/adw-squeezer.c" + line="1282">whether @self is enabled - - + + + a squeezer page + + + + + Emitted right after the spinbutton wraps. + filename="src/adw-squeezer.c" + line="1294">Sets whether @self is enabled. -See [signal@Gtk.SpinButton::wrapped]. +If a child is disabled, it will be ignored when looking for the child +fitting the available size best. + +This allows to programmatically and prematurely hide a child even if it fits +in the available space. + +This can be used e.g. to ensure a certain child is hidden below a certain +window width, or any other constraint you find suitable. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + - + + + a squeezer page + + + + whether @self is enabled + + + + + + The the squeezer child to which the page belongs. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + + + Whether the child is enabled. + +If a child is disabled, it will be ignored when looking for the child +fitting the available size best. + +This allows to programmatically and prematurely hide a child even if it +fits in the available space. + +This can be used e.g. to ensure a certain child is hidden below a certain +window width, or any other constraint you find suitable. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + - - + + - + - + Describes the possible transitions in a [class@Squeezer] widget. + See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) + + No transition + + + A cross-fade + + + + glib:type-name="AdwStatusPage" + glib:get-type="adw_status_page_get_type" + glib:type-struct="StatusPageClass"> A combined button and dropdown widget. + filename="src/adw-status-page.c" + line="14">A page used for empty/error states and similar use-cases. <picture> - <source srcset="split-button-dark.png" media="(prefers-color-scheme: dark)"> - <img src="split-button.png" alt="split-button"> + <source srcset="status-page-dark.png" media="(prefers-color-scheme: dark)"> + <img src="status-page.png" alt="status-page"> </picture> -`AdwSplitButton` is typically used to present a set of actions in a menu, -but allow access to one of them with a single click. - -The API is very similar to [class@Gtk.Button] and [class@Gtk.MenuButton], see -their documentation for details. +The `AdwStatusPage` widget can have an icon, a title, a description and a +custom widget which is displayed below them. ## CSS nodes -``` -splitbutton[.image-button][.text-button] -├── button -│ ╰── <content> -├── separator -╰── menubutton - ╰── button.toggle - ╰── arrow -``` +`AdwStatusPage` has a main CSS node with name `statuspage`. -`AdwSplitButton`'s CSS node is called `splitbutton`. It contains the css -nodes: `button`, `separator`, `menubutton`. See [class@Gtk.MenuButton] -documentation for the `menubutton` contents. +When setting an [class@SpinnerPaintable] as [property@StatusPage:paintable], +the main nodes gains the `.spinner` style class for a more compact +appearance. -The main CSS node will contain the `.image-button` or `.text-button` style -classes matching the button contents. The nested button nodes will never -contain them. +## Style classes -## Accessibility +`AdwStatusPage` can use the +[`.compact`](style-classes.html#compact-status-page) style class for when it +needs to fit into a small space such a sidebar or a popover, similar to when +using a spinner as the paintable. -`AdwSplitButton` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - +<picture> + <source srcset="status-page-compact-dark.png" media="(prefers-color-scheme: dark)"> + <img src="status-page-compact.png" alt="status-page-compact"> +</picture> + - - + Creates a new `AdwSplitButton`. - + filename="src/adw-status-page.c" + line="307">Creates a new `AdwStatusPage`. + the newly created `AdwSplitButton` + filename="src/adw-status-page.c" + line="312">the newly created `AdwStatusPage` - - - gets whether the button can be smaller than the natural size of its contents. - - - whether the button can shrink - - - - - a split button - - - - - Gets the child widget. - + filename="src/adw-status-page.c" + line="501">Gets the child widget of @self. + the child widget + filename="src/adw-status-page.c" + line="507">the child widget of @self a split button - - - - - - - Gets the direction in which the popup will be popped up. - - - the direction - - - - - a split button - + filename="src/adw-status-page.c" + line="503">a status page + - - + Gets the tooltip of the dropdown button of @self. - - + filename="src/adw-status-page.c" + line="462">Gets the description markup for @self. + + the dropdown tooltip of @self + filename="src/adw-status-page.c" + line="468">the description a split button - + filename="src/adw-status-page.c" + line="464">a status page + - - Gets the name of the icon used to automatically populate the button. - - - the icon name - - - - - a split button - - - - - - Gets the label for @self. - + filename="src/adw-status-page.c" + line="320">Gets the icon name for @self. + the label for @self + filename="src/adw-status-page.c" + line="326">the icon name a split button - - - - - - - Gets the menu model from which the popup will be created. - - - the menu model - - - - - a split button - + filename="src/adw-status-page.c" + line="322">a status page + - - + Gets the popover that will be popped up when the dropdown is clicked. - + filename="src/adw-status-page.c" + line="368">Gets the paintable for @self. + the popover - + filename="src/adw-status-page.c" + line="374">the paintable + a split button - + filename="src/adw-status-page.c" + line="370">a status page + - - + Gets whether an underline in the text indicates a mnemonic. - + filename="src/adw-status-page.c" + line="423">Gets the title for @self. + whether an underline in the text indicates a mnemonic - + filename="src/adw-status-page.c" + line="429">the title + a split button - + filename="src/adw-status-page.c" + line="425">a status page + - + Dismisses the menu. - + filename="src/adw-status-page.c" + line="517">Sets the child widget of @self. + a split button - + filename="src/adw-status-page.c" + line="519">a status page + + + the child widget + + - + Pops up the menu. - + filename="src/adw-status-page.c" + line="478">Sets the description markup for @self. + +The description is displayed below the title. It is parsed as Pango markup. + a split button - + filename="src/adw-status-page.c" + line="480">a status page + + + the description + + - - + Sets whether the button can be smaller than the natural size of its contents. - -If set to `TRUE`, the label will ellipsize. + filename="src/adw-status-page.c" + line="336">Sets the icon name for @self. -See [method@Gtk.Button.set_can_shrink] and -[method@Gtk.MenuButton.set_can_shrink]. - +Changing this will set [property@StatusPage:paintable] to `NULL`. + a split button - + filename="src/adw-status-page.c" + line="338">a status page + - + whether the button can shrink - + filename="src/adw-status-page.c" + line="339">the icon name + - - + Sets the child widget. + filename="src/adw-status-page.c" + line="384">Sets the paintable for @self. -Setting the child widget will set [property@SplitButton:label] and -[property@SplitButton:icon-name] to `NULL`. - +Changing this will set [property@StatusPage:icon-name] to `NULL`. + a split button - + filename="src/adw-status-page.c" + line="386">a status page + - the new child widget - + filename="src/adw-status-page.c" + line="387">the paintable + - - + Sets the direction in which the popup will be popped up. - -The dropdown arrow icon will point at the same direction. - -If the does not fit in the available space in the given direction, GTK will -try its best to keep it inside the screen and fully visible. + filename="src/adw-status-page.c" + line="439">Sets the title for @self. -If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`. - +The title is displayed below the icon. It is not parsed as Pango markup. + a split button - + filename="src/adw-status-page.c" + line="441">a status page + - + the direction - + filename="src/adw-status-page.c" + line="442">the title + - - + Sets the tooltip of the dropdown button of @self. + filename="src/adw-status-page.c" + line="249">The child widget. + + + + The description markup to be displayed below the title. + + + + The name of the icon to be used. -The tooltip can be marked up with the Pango text markup language. - +Changing this will set [property@StatusPage:paintable] to `NULL`. + + + + The paintable to be used. + +Changing this will set [property@StatusPage:icon-name] to `NULL`. + + + + The title to be displayed below the icon. + +It is not parsed as Pango markup. + + + + + + + + + + + A class for managing application-wide styling. + +`AdwStyleManager` provides a way to query and influence the application +styles, such as whether to use dark style, the system accent color or high +contrast appearance. + +It allows to set the color scheme via the +[property@StyleManager:color-scheme] property, and to query the current +appearance, as well as whether a system-wide color scheme and accent color +preferences exists. + + + Gets the default `AdwStyleManager` instance. + +It manages all [class@Gdk.Display] instances unless the style manager for +that display has an override. + +See [func@StyleManager.get_for_display]. + - + the default style manager + + + + + Gets the `AdwStyleManager` instance managing @display. + +It can be used to override styles for that specific display instead of the +whole application. + +Most applications should use [func@StyleManager.get_default] instead. + + + the style manager for @display + + + + + a `GdkDisplay` + + + + + + Gets the current system accent color. + +See also [property@StyleManager:accent-color-rgba]. + + + the current system accent color + a split button - + filename="src/adw-style-manager.c" + line="1093">a style manager + - - the dropdown tooltip of @self - - - - + Sets the name of the icon used to automatically populate the button. + filename="src/adw-style-manager.c" + line="1111">Gets the current system accent color as a `GdkRGBA`. -Setting the icon name will set [property@SplitButton:label] and -[property@SplitButton:child] to `NULL`. - - - +Equivalent to calling [func@AccentColor.to_rgba] on the value of +[property@StyleManager:accent-color]. + +This is a background color. The matching foreground color is white. + + + the current system accent color + a split button - + filename="src/adw-style-manager.c" + line="1113">a style manager + - + + + + Gets the requested application color scheme. + + + the color scheme + + + + the icon name to set - - + filename="src/adw-style-manager.c" + line="928">a style manager + + - - + Sets the label for @self. + filename="src/adw-style-manager.c" + line="1030">Gets whether the application is using dark appearance. -Setting the label will set [property@SplitButton:icon-name] and -[property@SplitButton:child] to `NULL`. - +This can be used to query the current appearance, as requested via +[property@StyleManager:color-scheme]. + - + whether the application is using dark appearance + a split button - + filename="src/adw-style-manager.c" + line="1032">a style manager + - + + + + Gets the display the style manager is associated with. + +The display will be `NULL` for the style manager returned by +[func@StyleManager.get_default]. + + + the display + + + + the label to set - - + filename="src/adw-style-manager.c" + line="909">a style manager + + - - + Sets the menu model from which the popup will be created. + filename="src/adw-style-manager.c" + line="1141">Gets the system document font. -If the menu model is `NULL`, the dropdown is disabled. +The font is in the same format as [property@Gtk.Settings:gtk-font-name], +e.g. "Adwaita Sans 11". -A [class@Gtk.Popover] will be created from the menu model with -[ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as -documented for this function. +Use [func@Pango.FontDescription.to_string] to parse it. + + + the system document font + + + + + a style manager + + + + + + Gets whether the application is using high contrast appearance. -If [property@SplitButton:popover] is already set, it will be dissociated from -the button, and the property is set to `NULL`. - +This cannot be overridden by applications. + - + whether the application is using high contrast appearance + a split button - + filename="src/adw-style-manager.c" + line="1051">a style manager + - + + + + Gets the system monospace font. + +The font is in the same format as [property@Gtk.Settings:gtk-font-name], +e.g. "Adwaita Mono 11". + +Use [func@Pango.FontDescription.to_string] to parse it. + + + the system monospace font + + + + the menu model - - + filename="src/adw-style-manager.c" + line="1169">a style manager + + - - + Sets the popover that will be popped up when the dropdown is clicked. + filename="src/adw-style-manager.c" + line="1067">Gets whether the system supports accent colors. -If the popover is `NULL`, the dropdown is disabled. +This can be used to check if the current environment provides an accent color +preference. For example, applications might want to show a preference for +choosing accent color if it's set to `FALSE`. -If [property@SplitButton:menu-model] is set, the menu model is dissociated -from the button, and the property is set to `NULL`. - +See [property@StyleManager:accent-color]. + - + whether the system supports accent colors + a split button - + filename="src/adw-style-manager.c" + line="1069">a style manager + - + + + + Gets whether the system supports color schemes. + +This can be used to check if the current environment provides a color scheme +preference. For example, applications might want to show a separate +appearance switcher if it's set to `FALSE`. + + + whether the system supports color schemes + + + + the popover - - + filename="src/adw-style-manager.c" + line="1012">a style manager + + - - + Sets whether an underline in the text indicates a mnemonic. + filename="src/adw-style-manager.c" + line="942">Sets the requested application color scheme. -See [property@SplitButton:label]. - +The effective appearance will be decided based on the application color +scheme and the system preferred color scheme. The +[property@StyleManager:dark] property can be used to query the current +effective appearance. + +The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application +using light appearance unless the system prefers dark colors. This is the +default value. + +The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application +using dark appearance, but can still switch to the light appearance if the +system can prefers it, for example, when the high contrast preference is +enabled. + +The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values +ignore the system preference entirely. They are useful if the application +wants to match its UI to its content or to provide a separate color scheme +switcher. + +If a per-[class@Gdk.Display] style manager has its color scheme set to +`ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the +default style manager. + +For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to +`ADW_COLOR_SCHEME_PREFER_LIGHT`. + +The [property@StyleManager:system-supports-color-schemes] property can be +used to check if the current environment provides a color scheme +preference. + - a split button - + a style manager + - + whether an underline in the text indicates a mnemonic - + filename="src/adw-style-manager.c" + line="945">the color scheme + - - - + getter="get_accent_color" + default-value="ADW_ACCENT_COLOR_BLUE"> Whether the button can be smaller than the natural size of its contents. - -If set to `TRUE`, the label will ellipsize. + filename="src/adw-style-manager.c" + line="756">The current system accent color. -See [property@Gtk.Button:can-shrink] and -[property@Gtk.MenuButton:can-shrink]. - +See also [property@StyleManager:accent-color-rgba]. + - - - + getter="get_accent_color_rgba"> The child widget. + filename="src/adw-style-manager.c" + line="771">The current system accent color as a `GdkRGBA`. -Setting the child widget will set [property@SplitButton:label] and -[property@SplitButton:icon-name] to `NULL`. - +Equivalent to calling [func@AccentColor.to_rgba] on the value of +[property@StyleManager:accent-color]. + +This is a background color. The matching foreground color is white. + - - - + setter="set_color_scheme" + getter="get_color_scheme" + default-value="ADW_COLOR_SCHEME_DEFAULT"> The direction in which the popup will be popped up. + filename="src/adw-style-manager.c" + line="656">The requested application color scheme. -The dropdown arrow icon will point at the same direction. +The effective appearance will be decided based on the application color +scheme and the system preferred color scheme. The +[property@StyleManager:dark] property can be used to query the current +effective appearance. -If the does not fit in the available space in the given direction, GTK will -try its best to keep it inside the screen and fully visible. +The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application +using light appearance unless the system prefers dark colors. This is the +default value. -If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`. - +The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application +using dark appearance, but can still switch to the light appearance if the +system can prefers it, for example, when the high contrast preference is +enabled. + +The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values +ignore the system preference entirely. They are useful if the application +wants to match its UI to its content or to provide a separate color scheme +switcher. + +If a per-[class@Gdk.Display] style manager has its color scheme set to +`ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the +default style manager. + +For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to +`ADW_COLOR_SCHEME_PREFER_LIGHT`. + +The [property@StyleManager:system-supports-color-schemes] property can be +used to check if the current environment provides a color scheme +preference. + - - - + getter="get_dark" + default-value="FALSE"> The tooltip of the dropdown button. + filename="src/adw-style-manager.c" + line="713">Whether the application is using dark appearance. -The tooltip can be marked up with the Pango text markup language. - +This property can be used to query the current appearance, as requested via +[property@StyleManager:color-scheme]. + - - - + getter="get_display"> The name of the icon used to automatically populate the button. + filename="src/adw-style-manager.c" + line="643">The display the style manager is associated with. -Setting the icon name will set [property@SplitButton:label] and -[property@SplitButton:child] to `NULL`. - +The display will be `NULL` for the style manager returned by +[func@StyleManager.get_default]. + - - - + getter="get_document_font_name" + default-value="Sans 10"> The label for the button. + filename="src/adw-style-manager.c" + line="788">The system document font. -Setting the label will set [property@SplitButton:icon-name] and -[property@SplitButton:child] to `NULL`. +The font is in the same format as [property@Gtk.Settings:gtk-font-name], +e.g. "Adwaita Sans 11". + +Use [func@Pango.FontDescription.to_string] to parse it. - - - + getter="get_high_contrast" + default-value="FALSE"> The `GMenuModel` from which the popup will be created. - -If the menu model is `NULL`, the dropdown is disabled. - -A [class@Gtk.Popover] will be created from the menu model with -[ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as -documented for this function. + filename="src/adw-style-manager.c" + line="726">Whether the application is using high contrast appearance. -If [property@SplitButton:popover] is already set, it will be dissociated -from the button, and the property is set to `NULL`. - +This cannot be overridden by applications. + - - - + getter="get_monospace_font_name" + default-value="Monospace 10"> The `GtkPopover` that will be popped up when the dropdown is clicked. + filename="src/adw-style-manager.c" + line="805">The system monospace font. -If the popover is `NULL`, the dropdown is disabled. +The font is in the same format as [property@Gtk.Settings:gtk-font-name], +e.g. "Adwaita Mono 11". -If [property@SplitButton:menu-model] is set, the menu model is dissociated -from the button, and the property is set to `NULL`. - +Use [func@Pango.FontDescription.to_string] to parse it. + - - - Whether an underline in the text indicates a mnemonic. + filename="src/adw-style-manager.c" + line="738">Whether the system supports accent colors. -See [property@SplitButton:label]. +This property can be used to check if the current environment provides an +accent color preference. For example, applications might want to show a +preference for choosing accent color if it's set to `FALSE`. + +See [property@StyleManager:accent-color]. - + Emitted to animate press then release. + filename="src/adw-style-manager.c" + line="697">Whether the system supports color schemes. -This is an action signal. Applications should never connect to this signal, -but use the [signal@SplitButton::clicked] signal. - - - - - - Emitted when the button has been activated (pressed and released). - - - - +This property can be used to check if the current environment provides a +color scheme preference. For example, applications might want to show a +separate appearance switcher if it's set to `FALSE`. + +See [property@StyleManager:color-scheme]. + + - - + + - + - + glib:type-name="AdwSwipeTracker" + glib:get-type="adw_swipe_tracker_get_type" + glib:type-struct="SwipeTrackerClass"> A spring-based [class@Animation]. - -`AdwSpringAnimation` implements an animation driven by a physical model of a -spring described by [struct@SpringParams], with a resting position in -[property@SpringAnimation:value-to], stretched to -[property@SpringAnimation:value-from]. - -Since the animation is physically simulated, spring animations don't have a -fixed duration. The animation will stop when the simulated spring comes to a -rest - when the amplitude of the oscillations becomes smaller than -[property@SpringAnimation:epsilon], or immediately when it reaches -[property@SpringAnimation:value-to] if -[property@SpringAnimation:clamp] is set to `TRUE`. The estimated duration can -be obtained with [property@SpringAnimation:estimated-duration]. - -Due to the nature of spring-driven motion the animation can overshoot -[property@SpringAnimation:value-to] before coming to a rest. Whether the -animation will overshoot or not depends on the damping ratio of the spring. -See [struct@SpringParams] for more information about specific damping ratio -values. - -If [property@SpringAnimation:clamp] is `TRUE`, the animation will abruptly -end as soon as it reaches the final value, preventing overshooting. + filename="src/adw-swipe-tracker.c" + line="35">A swipe tracker used in [class@Carousel], [class@NavigationView] and +[class@OverlaySplitView]. -Animations can have an initial velocity value, set via -[property@SpringAnimation:initial-velocity], which adjusts the curve without -changing the duration. This makes spring animations useful for deceleration -at the end of gestures. +The `AdwSwipeTracker` object can be used for implementing widgets with swipe +gestures. It supports touch-based swipes, pointer dragging, and touchpad +scrolling. -If the initial and final values are equal, and the initial velocity is not 0, -the animation value will bounce and return to its resting position. - - +The widgets will probably want to expose the [property@SwipeTracker:enabled] +property. If they expect to use horizontal orientation, +[property@SwipeTracker:reversed] can be used for supporting RTL text +direction. + + + Creates a new `AdwSpringAnimation` on @widget. - -The animation will animate @target from @from to @to with the dynamics of a -spring described by @spring_params. - - + filename="src/adw-swipe-tracker.c" + line="1392">Creates a new `AdwSwipeTracker` for @widget. + + the newly created animation - + filename="src/adw-swipe-tracker.c" + line="1398">the newly created `AdwSwipeTracker` + - - a widget to create animation on - - - - a value to animate from - - - - a value to animate to - - - - physical parameters of the spring - - - + a target value to animate - + filename="src/adw-swipe-tracker.c" + line="1394">a widget to add the tracker on + - + Calculates the value @self will have at @time. - -The time starts at 0 and ends at -[property@SpringAnimation:estimated_duration]. - -See also [method@SpringAnimation.calculate_velocity]. - + filename="src/adw-swipe-tracker.c" + line="1555">Gets whether to allow swiping for more than one snap point at a time. + the value at @time - + filename="src/adw-swipe-tracker.c" + line="1561">whether long swipes are allowed + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1557">a swipe tracker + - - elapsed time, in milliseconds - - - + Calculates the velocity @self will have at @time. - -The time starts at 0 and ends at -[property@SpringAnimation:estimated_duration]. - -See also [method@SpringAnimation.calculate_value]. - + filename="src/adw-swipe-tracker.c" + line="1514">Gets whether @self can be dragged with mouse pointer. + the velocity at @time - + filename="src/adw-swipe-tracker.c" + line="1520">whether mouse dragging is allowed + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1516">a swipe tracker + - - elapsed time, in milliseconds - - - - + Gets whether @self should be clamped. - + filename="src/adw-swipe-tracker.c" + line="1683">Gets whether to allow touchscreen swiping from `GtkWindowHandle`. + whether @self is clamped + filename="src/adw-swipe-tracker.c" + line="1689">whether swiping from window handles is allowed a spring animation - + filename="src/adw-swipe-tracker.c" + line="1685">a swipe tracker + - - + Gets the precision of the spring. - + filename="src/adw-swipe-tracker.c" + line="1426">Gets whether @self is enabled. + the epsilon value - + filename="src/adw-swipe-tracker.c" + line="1432">whether @self is enabled + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1428">a swipe tracker + - - + Gets the estimated duration of @self, in milliseconds. - -Can be [const@DURATION_INFINITE] if the spring damping is set to 0. - + filename="src/adw-swipe-tracker.c" + line="1597">Gets whether to allow swiping past the first available snap point. + the estimated duration - + filename="src/adw-swipe-tracker.c" + line="1603">whether to allow swiping past the first available snap point + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1599">a swipe tracker + - - + Gets the initial velocity of @self. - + filename="src/adw-swipe-tracker.c" + line="1473">Gets whether @self is reversing the swipe direction. + the initial velocity - + filename="src/adw-swipe-tracker.c" + line="1479">whether the direction is reversed + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1475">a swipe tracker + - - + Gets the physical parameters of the spring of @self. - + filename="src/adw-swipe-tracker.c" + line="1410">Get the widget @self is attached to. + the spring parameters - + filename="src/adw-swipe-tracker.c" + line="1416">the swipeable widget + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1412">a swipe tracker + - - + Gets the value @self will animate from. - + filename="src/adw-swipe-tracker.c" + line="1640">Gets whether to allow swiping past the last available snap point. + the value to animate from - + filename="src/adw-swipe-tracker.c" + line="1646">whether to allow swiping past the last available snap point + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1642">a swipe tracker + - - + Gets the value @self will animate to. - + filename="src/adw-swipe-tracker.c" + line="1571">Sets whether to allow swiping for more than one snap point at a time. + +If the value is `FALSE`, each swipe can only move to the adjacent snap +points. + - the value to animate to - + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1573">a swipe tracker + + + whether to allow long swipes + + - - + Gets the current velocity of @self. - + filename="src/adw-swipe-tracker.c" + line="1530">Sets whether @self can be dragged with mouse pointer. + - the current velocity - + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1532">a swipe tracker + + + whether to allow mouse dragging + + - - + Sets whether @self should be clamped. - -If set to `TRUE`, the animation will abruptly end as soon as it reaches the -final value, preventing overshooting. + filename="src/adw-swipe-tracker.c" + line="1701">Sets whether to allow touchscreen swiping from `GtkWindowHandle`. -It won't prevent overshooting [property@SpringAnimation:value-from] if a -relative negative [property@SpringAnimation:initial-velocity] is set. - +Setting it to `TRUE` will make dragging the window impossible. + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1703">a swipe tracker + - + the new value + filename="src/adw-swipe-tracker.c" + line="1704">whether to allow swiping from window handles - - + Sets the precision of the spring. - -The level of precision used to determine when the animation has come to a -rest, that is, when the amplitude of the oscillations becomes smaller than -this value. - -If the epsilon value is too small, the animation will take a long time to -stop after the animated value has stopped visibly changing. - -If the epsilon value is too large, the animation will end prematurely. + filename="src/adw-swipe-tracker.c" + line="1442">Sets whether @self is enabled. -The default value is 0.001. - +When it's not enabled, no events will be processed. Usually widgets will want +to expose this via a property. + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1444">a swipe tracker + - + the new value - + filename="src/adw-swipe-tracker.c" + line="1445">whether @self is enabled + - - + Sets the initial velocity of @self. - -Initial velocity affects only the animation curve, but not its duration. - + filename="src/adw-swipe-tracker.c" + line="1615">Sets whether to allow swiping past the first available snap point. + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1617">a swipe tracker + - + the initial velocity - + filename="src/adw-swipe-tracker.c" + line="1618">whether to allow swiping past the first available snap point + - - + Sets the physical parameters of the spring of @self. - + filename="src/adw-swipe-tracker.c" + line="1489">Sets whether to reverse the swipe direction. + +If the swipe tracker is horizontal, it can be used for supporting RTL text +direction. + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1491">a swipe tracker + - + the new spring parameters - + filename="src/adw-swipe-tracker.c" + line="1492">whether to reverse the swipe direction + - - + Sets the value @self will animate from. - -The animation will start at this value and end at -[property@SpringAnimation:value-to]. - + filename="src/adw-swipe-tracker.c" + line="1658">Sets whether to allow swiping past the last available snap point. + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1660">a swipe tracker + - + the value to animate from - + filename="src/adw-swipe-tracker.c" + line="1661">whether to allow swiping past the last available snap point + - - + Sets the value @self will animate to. + filename="src/adw-swipe-tracker.c" + line="1728">Moves the current progress value by @delta. -The animation will start at [property@SpringAnimation:value-from] and end at -this value. - +This can be used to adjust the current position if snap points move during +the gesture. + a spring animation - + filename="src/adw-swipe-tracker.c" + line="1730">a swipe tracker + - + the value to animate to + filename="src/adw-swipe-tracker.c" + line="1731">the position delta - - - Whether the animation should be clamped. - -If set to `TRUE`, the animation will abruptly end as soon as it reaches the -final value, preventing overshooting. + filename="src/adw-swipe-tracker.c" + line="1233">Whether to allow swiping for more than one snap point at a time. -It won't prevent overshooting [property@SpringAnimation:value-from] if a -relative negative [property@SpringAnimation:initial-velocity] is set. +If the value is `FALSE`, each swipe can only move to the adjacent snap +points. - - - + setter="set_allow_mouse_drag" + getter="get_allow_mouse_drag" + default-value="FALSE"> Precision of the spring. - -The level of precision used to determine when the animation has come to a -rest, that is, when the amplitude of the oscillations becomes smaller than -this value. - -If the epsilon value is too small, the animation will take a long time to -stop after the animated value has stopped visibly changing. - -If the epsilon value is too large, the animation will end prematurely. - -The default value is 0.001. - + filename="src/adw-swipe-tracker.c" + line="1223">Whether to allow dragging with mouse pointer. + - - + setter="set_allow_window_handle" + getter="get_allow_window_handle" + default-value="FALSE"> Estimated duration of the animation, in milliseconds. + filename="src/adw-swipe-tracker.c" + line="1270">Whether to allow touchscreen swiping from `GtkWindowHandle`. -Can be [const@DURATION_INFINITE] if the spring damping is set to 0. - +This will make dragging the window impossible. + - - - + setter="set_enabled" + getter="get_enabled" + default-value="TRUE"> The initial velocity to start the animation with. + filename="src/adw-swipe-tracker.c" + line="1197">Whether the swipe tracker is enabled. -Initial velocity affects only the animation curve, but not its duration. - +When it's not enabled, no events will be processed. Usually widgets will +want to expose this via a property. + - - - + setter="set_lower_overshoot" + getter="get_lower_overshoot" + default-value="FALSE"> Physical parameters describing the spring. - + filename="src/adw-swipe-tracker.c" + line="1246">Whether to allow swiping past the first available snap point. + - - - + setter="set_reversed" + getter="get_reversed" + default-value="FALSE"> The value to animate from. + filename="src/adw-swipe-tracker.c" + line="1210">Whether to reverse the swipe direction. -The animation will start at this value and end at -[property@SpringAnimation:value-to]. - +If the swipe tracker is horizontal, it can be used for supporting RTL text +direction. + - - - + getter="get_swipeable"> The value to animate to. - -The animation will start at [property@SpringAnimation:value-from] and end -at this value. - + filename="src/adw-swipe-tracker.c" + line="1187">The widget the swipe tracker is attached to. + - - + setter="set_upper_overshoot" + getter="get_upper_overshoot" + default-value="FALSE"> Current velocity of the animation. - + filename="src/adw-swipe-tracker.c" + line="1258">Whether to allow swiping past the last available snap point. + + + This signal is emitted right before a swipe will be started, after the +drag threshold has been passed. + + + + + + This signal is emitted as soon as the gesture has stopped. + +The user is expected to animate the deceleration from the current progress +value to @to with an animation using @velocity as the initial velocity, +provided in pixels per second. [class@SpringAnimation] is usually a good +fit for this. + + + + + + the velocity of the swipe + + + + the progress value to animate to + + + + + + This signal is emitted when a possible swipe is detected. + +The @direction value can be used to restrict the swipe to a certain +direction. + + + + + + the direction of the swipe + + + + + + This signal is emitted every time the progress value changes. + + + + + + the current animation progress value + + + + - - + + + + + - + Physical parameters of a spring for [class@SpringAnimation]. - -Any spring can be described by three parameters: mass, stiffness and damping. - -An undamped spring will produce an oscillatory motion which will go on -forever. - -The frequency and amplitude of the oscillations will be determined by the -stiffness (how "strong" the spring is) and its mass (how much "inertia" it -has). - -If damping is larger than 0, the amplitude of that oscillating motion will -exponientally decrease over time. If that damping is strong enough that the -spring can't complete a full oscillation, it's called an overdamped spring. - -If we the spring can oscillate, it's called an underdamped spring. - -The value between these two behaviors is called critical damping; a -critically damped spring will comes to rest in the minimum possible time -without producing oscillations. - -The damping can be replaced by damping ratio, which produces the following -springs: + filename="src/adw-swipeable.c" + line="11">An interface for swipeable widgets. -* 0: an undamped spring. -* Between 0 and 1: an underdamped spring. -* 1: a critically damped spring. -* Larger than 1: an overdamped spring. +The `AdwSwipeable` interface is implemented by all swipeable widgets. -As such - - +See [class@SwipeTracker] for details about implementing it. + + + Creates a new `AdwSpringParams` from @mass, @stiffness and @damping_ratio. - -The damping value is calculated from @damping_ratio and the other two -parameters. - -* If @damping_ratio is 0, the spring will not be damped and will oscillate - endlessly. -* If @damping_ratio is between 0 and 1, the spring is underdamped and will - always overshoot. -* If @damping_ratio is 1, the spring is critically damped and will reach its - resting position the quickest way possible. -* If @damping_ratio is larger than 1, the spring is overdamped and will reach - its resting position faster than it can complete an oscillation. - -[ctor@SpringParams.new_full] allows to pass a raw damping value instead. - - + filename="src/adw-swipeable.c" + line="111">Gets the progress @self will snap back to after the gesture is canceled. + + the newly created spring parameters - + filename="src/adw-swipeable.c" + line="117">the cancel progress, unitless + - + the damping ratio of the spring - - - + filename="src/adw-swipeable.c" + line="113">a swipeable + + + + + + Gets the swipe distance of @self. + +This corresponds to how many pixels 1 unit represents. + + + the swipe distance in pixels + + + + the mass of the spring - - - + filename="src/adw-swipeable.c" + line="43">a swipeable + + + + + + Gets the current progress of @self. + + + the current progress, unitless + + + + the stiffness of the spring - - + filename="src/adw-swipeable.c" + line="92">a swipeable + + - - + + Creates a new `AdwSpringParams` from @mass, @stiffness and @damping. + filename="src/adw-swipeable.c" + line="64">Gets the snap points of @self. -See [ctor@SpringParams.new] for a simplified constructor using damping ratio -instead of @damping. - +Each snap point represents a progress value that is considered acceptable to +end the swipe on. + the newly created spring parameters - + filename="src/adw-swipeable.c" + line="74">the snap points + + + - - the damping of the spring - - - + the mass of the spring - - - + filename="src/adw-swipeable.c" + line="66">a swipeable + + + the stiffness of the spring - + filename="src/adw-swipeable.c" + line="67">location to return the number of the snap points + - - + + Gets the damping of @self. - + filename="src/adw-swipeable.c" + line="132">Gets the area @self can start a swipe from for the given direction and +gesture type. + +This can be used to restrict swipes to only be possible from a certain area, +for example, to only allow edge swipes, or to have a draggable element and +ignore swipes elsewhere. + +If not implemented, the default implementation returns the allocation of +@self, allowing swipes from anywhere. + - the damping - + spring params - + filename="src/adw-swipeable.c" + line="134">a swipeable + + + the direction of the swipe + + + + whether the swipe is caused by a dragging gesture + + + + a pointer to a rectangle to store the swipe area + + - - + + Gets the damping ratio of @self. - + filename="src/adw-swipeable.c" + line="111">Gets the progress @self will snap back to after the gesture is canceled. + the damping ratio + filename="src/adw-swipeable.c" + line="117">the cancel progress, unitless spring params - + filename="src/adw-swipeable.c" + line="113">a swipeable + - + Gets the mass of @self. - + filename="src/adw-swipeable.c" + line="41">Gets the swipe distance of @self. + +This corresponds to how many pixels 1 unit represents. + the mass + filename="src/adw-swipeable.c" + line="49">the swipe distance in pixels spring params - + filename="src/adw-swipeable.c" + line="43">a swipeable + - + Gets the stiffness of @self. - + filename="src/adw-swipeable.c" + line="90">Gets the current progress of @self. + the stiffness + filename="src/adw-swipeable.c" + line="96">the current progress, unitless spring params - + filename="src/adw-swipeable.c" + line="92">a swipeable + - + Increases the reference count of @self. - + filename="src/adw-swipeable.c" + line="64">Gets the snap points of @self. + +Each snap point represents a progress value that is considered acceptable to +end the swipe on. + @self - + filename="src/adw-swipeable.c" + line="74">the snap points + + + spring params - + filename="src/adw-swipeable.c" + line="66">a swipeable + + + location to return the number of the snap points + + - + Decreases the reference count of @self. + filename="src/adw-swipeable.c" + line="132">Gets the area @self can start a swipe from for the given direction and +gesture type. -If the last reference is dropped, the structure is freed. - +This can be used to restrict swipes to only be possible from a certain area, +for example, to only allow edge swipes, or to have a draggable element and +ignore swipes elsewhere. + +If not implemented, the default implementation returns the allocation of +@self, allowing swipes from anywhere. + spring params - + filename="src/adw-swipeable.c" + line="134">a swipeable + + + the direction of the swipe + + + + whether the swipe is caused by a dragging gesture + + + + a pointer to a rectangle to store the swipe area + + + + + An interface for swipeable widgets. + + + The parent interface. + + + + Gets the swipe distance. + + + + the swipe distance in pixels + + + + + a swipeable + + + + + + + Gets the snap points. + + + + the snap points + + + + + + + a swipeable + + + + location to return the number of the snap points + + + + + + + Gets the current progress. + + + + the current progress, unitless + + + + + a swipeable + + + + + + + Gets the cancel progress. + + + + the cancel progress, unitless + + + + + a swipeable + + + + + + + Gets the swipeable rectangle. + + + + + + + + a swipeable + + + + the direction of the swipe + + + + whether the swipe is caused by a dragging gesture + + + + a pointer to a rectangle to store the swipe area + + + + + + + + + + - + glib:type-name="AdwSwitchRow" + glib:get-type="adw_switch_row_get_type" + glib:type-struct="SwitchRowClass"> A best fit container. + filename="src/adw-switch-row.c" + line="11">A [class@Gtk.ListBoxRow] used to represent two states. <picture> - <source srcset="squeezer-wide-dark.png" media="(prefers-color-scheme: dark)"> - <img src="squeezer-wide.png" alt="squeezer-wide"> -</picture> -<picture> - <source srcset="squeezer-narrow-dark.png" media="(prefers-color-scheme: dark)"> - <img src="squeezer-narrow.png" alt="squeezer-narrow"> + <source srcset="switch-row-dark.png" media="(prefers-color-scheme: dark)"> + <img src="switch-row.png" alt="switch-row"> </picture> -The `AdwSqueezer` widget is a container which only shows the first of its -children that fits in the available size. It is convenient to offer different -widgets to represent the same data with different levels of detail, making -the widget seem to squeeze itself to fit in the available space. +The `AdwSwitchRow` widget contains a [class@Gtk.Switch] that allows the user +to select between two states: "on" or "off". When activated, the row will +invert its active state. -Transitions between children can be animated as fades. This can be controlled -with [property@Squeezer:transition-type]. +The user can control the switch by activating the row or by dragging on the +switch handle. -## CSS nodes +See [class@Gtk.Switch] for details. -`AdwSqueezer` has a single CSS node with name `squeezer`. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +Example of an `AdwSwitchRow` UI definition: +```xml +<object class="AdwSwitchRow"> + <property name="title" translatable="yes">Switch Row</property> + <signal name="notify::active" handler="switch_row_notify_active_cb"/> +</object> +``` + +The [property@SwitchRow:active] property should be connected to in order to +monitor changes to the active state. + +## Accessibility + +`AdwSwitchRow` uses the `GTK_ACCESSIBLE_ROLE_SWITCH` role. + + - - + Creates a new `AdwSqueezer`. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-switch-row.c" + line="174">Creates a new `AdwSwitchRow`. + the newly created `AdwSqueezer` + filename="src/adw-switch-row.c" + line="179">the newly created `AdwSwitchRow` - - Adds a child to @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - the [class@SqueezerPage] for @child - - - - - a squeezer - - - - the widget to add - - - - - - + Gets whether to allow squeezing beyond the last child's minimum size. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-switch-row.c" + line="189">Gets whether @self is in its "on" or "off" position. + whether @self allows squeezing beyond the last child + filename="src/adw-switch-row.c" + line="195">whether @self is active or not a squeezer - + filename="src/adw-switch-row.c" + line="191">a switch row + - - + Gets whether all children have the same size for the opposite orientation. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-switch-row.c" + line="207">Sets whether @self is in its "on" or "off" position + - whether @self is homogeneous - + a squeezer - + filename="src/adw-switch-row.c" + line="209">a switch row + + + whether @self should be active + + - - + Gets whether @self interpolates its size when changing the visible child. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-switch-row.c" + line="133">Whether the switch row is in the "on" or "off" position. + + + + + + + + + + + A tab bar for [class@TabView]. + +<picture> + <source srcset="tab-bar-dark.png" media="(prefers-color-scheme: dark)"> + <img src="tab-bar.png" alt="tab-bar"> +</picture> + +The `AdwTabBar` widget is a tab bar that can be used with conjunction with +`AdwTabView`. It is typically used as a top bar within [class@ToolbarView]. + +`AdwTabBar` can autohide and can optionally contain action widgets on both +sides of the tabs. + +When there's not enough space to show all the tabs, `AdwTabBar` will scroll +them. Pinned tabs always stay visible and aren't a part of the scrollable +area. + +## CSS nodes + +`AdwTabBar` has a single CSS node with name `tabbar`. + +## Style classes + +By default `AdwTabBar` look like a part of an `AdwHeaderBar` and is intended +to be used directly attached to one or used as a [class@ToolbarView] toolbar. +The [`.inline`](style-classes.html#inline) style class removes its background, +so that it can be used in different contexts instead. + +<picture> + <source srcset="tab-bar-inline-dark.png" media="(prefers-color-scheme: dark)"> + <img src="tab-bar-inline.png" alt="tab-bar-inline"> +</picture> + + + + + + Creates a new `AdwTabBar`. + whether the size is interpolated - + filename="src/adw-tab-bar.c" + line="752">the newly created `AdwTabBar` + - - - A squeezer - - - - - + + Returns the [class@SqueezerPage] object for @child. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="938">Gets whether the tabs automatically hide. + the page object for @child - + filename="src/adw-tab-bar.c" + line="944">whether the tabs automatically hide + a squeezer - + filename="src/adw-tab-bar.c" + line="940">a tab bar + - - a child of @self - - - - + Returns a [iface@Gio.ListModel] that contains the pages of @self. - -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track the visible page. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - + filename="src/adw-tab-bar.c" + line="895">Gets the widget shown after the tabs. + + a `GtkSelectionModel` for the squeezer's children - + filename="src/adw-tab-bar.c" + line="901">the widget shown after the tabs + a squeezer - + filename="src/adw-tab-bar.c" + line="897">a tab bar + - - + Gets the switch threshold policy for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="1002">Gets whether tabs expand to full width. + - + whether tabs expand to full width. + a squeezer - + filename="src/adw-tab-bar.c" + line="1004">a tab bar + - - + Gets the transition animation duration for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="1119">Gets the current action during a drop on the extra_drop_target. + the transition duration, in milliseconds - + filename="src/adw-tab-bar.c" + line="1125">the drag action of the current drop. + a squeezer - + filename="src/adw-tab-bar.c" + line="1121">a tab bar + - - + Gets whether a transition is currently running for @self. - -If a transition is impossible, the property value will be set to `TRUE` and -then immediately to `FALSE`, so it's possible to rely on its notifications -to know that a transition has happened. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="1137">Gets whether drop data should be preloaded on hover. + whether a transition is currently running + filename="src/adw-tab-bar.c" + line="1143">whether drop data should be preloaded on hover a squeezer - + filename="src/adw-tab-bar.c" + line="1139">a tab bar + - - + Gets the type of animation used for transitions between children in @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="1044">Gets whether tabs use inverted layout. + the current transition type of @self - + filename="src/adw-tab-bar.c" + line="1050">whether tabs use inverted layout + a squeezer - + filename="src/adw-tab-bar.c" + line="1046">a tab bar + - - + Gets the currently visible child of @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - + filename="src/adw-tab-bar.c" + line="1181">Gets whether @self is overflowing. + +If `TRUE`, all tabs cannot be displayed at once and require scrolling. + + the visible child - + filename="src/adw-tab-bar.c" + line="1189">whether @self is overflowing + a squeezer - + filename="src/adw-tab-bar.c" + line="1183">a tab bar + - - + Gets the horizontal alignment, from 0 (start) to 1 (end). - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - + filename="src/adw-tab-bar.c" + line="852">Gets the widget shown before the tabs. + + the alignment value - + filename="src/adw-tab-bar.c" + line="858">the widget shown before the tabs + a squeezer - + filename="src/adw-tab-bar.c" + line="854">a tab bar + - - + Gets the vertical alignment, from 0 (top) to 1 (bottom). - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="984">Gets whether the tabs are currently revealed. + +See [property@TabBar:autohide]. + the alignment value - + filename="src/adw-tab-bar.c" + line="992">whether the tabs are currently revealed + a squeezer - + filename="src/adw-tab-bar.c" + line="986">a tab bar + - + Removes a child widget from @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - + filename="src/adw-tab-bar.c" + line="760">Gets the tab view @self controls. + + + the view @self controls + a squeezer - + filename="src/adw-tab-bar.c" + line="762">a tab bar + - - the child to remove - - - - + Sets whether to allow squeezing beyond the last child's minimum size. + filename="src/adw-tab-bar.c" + line="954">Sets whether the tabs automatically hide. -If set to `TRUE`, the squeezer can shrink to the point where no child can be -shown. This is functionally equivalent to appending a widget with 0×0 minimum -size. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0 +or 1 tab, no pinned tabs, and no tab is being transferred. + +See [property@TabBar:tabs-revealed]. + a squeezer - + filename="src/adw-tab-bar.c" + line="956">a tab bar + - + whether @self allows squeezing beyond the last child + filename="src/adw-tab-bar.c" + line="957">whether the tabs automatically hide - - + Sets whether all children have the same size for the opposite orientation. - -For example, if a squeezer is horizontal and is homogeneous, it will request -the same height for all its children. If it isn't, the squeezer may change -size when a different child becomes visible. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="911">Sets the widget to show after the tabs. + a squeezer - + filename="src/adw-tab-bar.c" + line="913">a tab bar + - + whether @self is homogeneous - + filename="src/adw-tab-bar.c" + line="914">the widget to show after the tabs + - - + Sets whether @self interpolates its size when changing the visible child. + filename="src/adw-tab-bar.c" + line="1018">Sets whether tabs expand to full width. -If `TRUE`, the squeezer will interpolate its size between the one of the -previous visible child and the one of the new visible child, according to the -set transition duration and the orientation, e.g. if the squeezer is -horizontal, it will interpolate the its height. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +If set to `TRUE`, the tabs will always vary width filling the whole width +when possible, otherwise tabs will always have the minimum possible size. + A squeezer - + filename="src/adw-tab-bar.c" + line="1020">a tab bar + - + whether to interpolate the size + filename="src/adw-tab-bar.c" + line="1021">whether to expand tabs - - + Sets the switch threshold policy for @self. - -Determines when the squeezer will switch children. - -If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the -visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, -it will switch as soon as the visible child doesn't get their natural size. + filename="src/adw-tab-bar.c" + line="1155">Sets whether drop data should be preloaded on hover. -This can be useful if you have a long ellipsizing label and want to let it -ellipsize instead of immediately switching. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +See [property@Gtk.DropTarget:preload]. + a squeezer - + filename="src/adw-tab-bar.c" + line="1157">a tab bar + - + the policy to use - + filename="src/adw-tab-bar.c" + line="1158">whether to preload drop data + - - + Sets the transition animation duration for @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="1060">Sets whether tabs tabs use inverted layout. + +If set to `TRUE`, non-pinned tabs will have the close button at the beginning +and the indicator at the end rather than the opposite. + a squeezer - + filename="src/adw-tab-bar.c" + line="1062">a tab bar + - + the new duration, in milliseconds - + filename="src/adw-tab-bar.c" + line="1063">whether tabs use inverted layout + - - - + + Sets the type of animation used for transitions between children in @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="868">Sets the widget to show before the tabs. + a squeezer - + filename="src/adw-tab-bar.c" + line="870">a tab bar + - + the new transition type - + filename="src/adw-tab-bar.c" + line="871">the widget to show before the tabs + - - + Sets the horizontal alignment, from 0 (start) to 1 (end). - -This affects the children allocation during transitions, when they exceed the -size of the squeezer. - -For example, 0.5 means the child will be centered, 0 means it will keep the -start side aligned and overflow the end side, and 1 means the opposite. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="776">Sets the tab view @self controls. + a squeezer - + filename="src/adw-tab-bar.c" + line="778">a tab bar + - + the new alignment value - + filename="src/adw-tab-bar.c" + line="779">a tab view + - - + Sets the vertical alignment, from 0 (top) to 1 (bottom). + filename="src/adw-tab-bar.c" + line="1086">Sets the supported types for this drop target. -This affects the children allocation during transitions, when they exceed the -size of the squeezer. +Sets up an extra drop target on tabs. -For example, 0.5 means the child will be centered, 0 means it will keep the -top side aligned and overflow the bottom side, and 1 means the opposite. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +This allows to drag arbitrary content onto tabs, for example URLs in a web +browser. + +If a tab is hovered for a certain period of time while dragging the content, +it will be automatically selected. + +The [signal@TabBar::extra-drag-drop] signal can be used to handle the drop. + a squeezer - + filename="src/adw-tab-bar.c" + line="1088">a tab bar + - + the new alignment value - + filename="src/adw-tab-bar.c" + line="1089">the supported actions + + + + + all supported `GType`s that can be dropped + + + + + + number of @types + - - - + setter="set_autohide" + getter="get_autohide" + default-value="TRUE"> Whether to allow squeezing beyond the last child's minimum size. + filename="src/adw-tab-bar.c" + line="493">Whether the tabs automatically hide. -If set to `TRUE`, the squeezer can shrink to the point where no child can -be shown. This is functionally equivalent to appending a widget with 0×0 -minimum size. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) +If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0 +or 1 tab, no pinned tabs, and no tab is being transferred. + +See [property@TabBar:tabs-revealed]. - - - + setter="set_end_action_widget" + getter="get_end_action_widget"> Whether all children have the same size for the opposite orientation. - -For example, if a squeezer is horizontal and is homogeneous, it will -request the same height for all its children. If it isn't, the squeezer may -change size when a different child becomes visible. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="483">The widget shown after the tabs. + - - - + setter="set_expand_tabs" + getter="get_expand_tabs" + default-value="TRUE"> Whether the squeezer interpolates its size when changing the visible child. + filename="src/adw-tab-bar.c" + line="520">Whether tabs expand to full width. -If `TRUE`, the squeezer will interpolate its size between the one of the -previous visible child and the one of the new visible child, according to -the set transition duration and the orientation, e.g. if the squeezer is -horizontal, it will interpolate the its height. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) +If set to `TRUE`, the tabs will always vary width filling the whole width +when possible, otherwise tabs will always have the minimum possible size. - - + getter="get_extra_drag_preferred_action" + default-value="0"> A selection model with the squeezer's pages. + filename="src/adw-tab-bar.c" + line="558">The unique action on the `current-drop` of the +[signal@TabBar::extra-drag-drop]. -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track the visible page. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +This property should only be used during a [signal@TabBar::extra-drag-drop] +and is always a subset of what was originally passed to +[method@TabBar.setup_extra_drop_target]. + - - - + setter="set_extra_drag_preload" + getter="get_extra_drag_preload" + default-value="FALSE"> The switch threshold policy. - -Determines when the squeezer will switch children. - -If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the -visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, -it will switch as soon as the visible child doesn't get their natural size. + filename="src/adw-tab-bar.c" + line="575">Whether the drop data should be preloaded on hover. -This can be useful if you have a long ellipsizing label and want to let it -ellipsize instead of immediately switching. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - +See [property@Gtk.DropTarget:preload]. + - - - + setter="set_inverted" + getter="get_inverted" + default-value="FALSE"> The transition animation duration, in milliseconds. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="533">Whether tabs use inverted layout. + +If set to `TRUE`, non-pinned tabs will have the close button at the +beginning and the indicator at the end rather than the opposite. + - - Whether a transition is currently running. + filename="src/adw-tab-bar.c" + line="546">Whether the tab bar is overflowing. -If a transition is impossible, the property value will be set to `TRUE` and -then immediately to `FALSE`, so it's possible to rely on its notifications -to know that a transition has happened. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) +If `TRUE`, all tabs cannot be displayed at once and require scrolling. - - - + setter="set_start_action_widget" + getter="get_start_action_widget"> The type of animation used for transitions between children. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="473">The widget shown before the tabs. + - - + getter="get_tabs_revealed" + default-value="FALSE"> The currently visible child. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-bar.c" + line="508">Whether the tabs are currently revealed. + +See [property@TabBar:autohide]. + - - - + setter="set_view" + getter="get_view"> The horizontal alignment, from 0 (start) to 1 (end). + filename="src/adw-tab-bar.c" + line="463">The tab view the tab bar controls. + + + + This signal is emitted when content is dropped onto a tab. -This affects the children allocation during transitions, when they exceed -the size of the squeezer. +The content must be of one of the types set up via +[method@TabBar.setup_extra_drop_target]. -For example, 0.5 means the child will be centered, 0 means it will keep the -start side aligned and overflow the end side, and 1 means the opposite. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - - - +See [signal@Gtk.DropTarget::drop]. + + whether the drop was accepted for @page + + + + + the page matching the tab the content was dropped onto + + + + the `GValue` being dropped + + + + + The vertical alignment, from 0 (top) to 1 (bottom). + filename="src/adw-tab-bar.c" + line="618">This signal is emitted when the dropped content is preloaded. -This affects the children allocation during transitions, when they exceed -the size of the squeezer. +In order for data to be preloaded, [property@TabBar:extra-drag-preload] +must be set to `TRUE`. -For example, 0.5 means the child will be centered, 0 means it will keep the -top side aligned and overflow the bottom side, and 1 means the opposite. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - +The content must be of one of the types set up via +[method@TabBar.setup_extra_drop_target]. + +See [property@Gtk.DropTarget:value]. + + the preferred action for the drop on @page + + + + + the page matching the tab the content was dropped onto + + + + the `GValue` being dropped + + + + - - + + - + glib:type-name="AdwTabButton" + glib:get-type="adw_tab_button_get_type" + glib:type-struct="TabButtonClass"> An auxiliary class used by [class@Squeezer]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - + filename="src/adw-tab-button.c" + line="18">A button that displays the number of [class@TabView] pages. + +<picture> + <source srcset="tab-button-dark.png" media="(prefers-color-scheme: dark)"> + <img src="tab-button.png" alt="tab-button"> +</picture> + +`AdwTabButton` is a button that displays the number of pages in a given +`AdwTabView`, as well as whether one of the inactive pages needs attention. + +It's intended to be used as a visible indicator when there's no visible tab +bar, typically opening an [class@TabOverview] on click, e.g. via the +`overview.open` action name: + +```xml +<object class="AdwTabButton"> + <property name="view">view</property> + <property name="action-name">overview.open</property> +</object> +``` + +## CSS nodes + +`AdwTabButton` has a main CSS node with name `tabbutton`. + +# Accessibility + +`AdwTabButton` uses the `GTK_ACCESSIBLE_ROLE_BUTTON` role. + + + + + + Returns the squeezer child to which @self belongs. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-button.c" + line="388">Creates a new `AdwTabButton`. + the child to which @self belongs + filename="src/adw-tab-button.c" + line="393">the newly created `AdwTabButton` - - - a squeezer page - - - - - - + + Gets whether @self is enabled. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - + filename="src/adw-tab-button.c" + line="403">Gets the tab view @self displays. + + whether @self is enabled - + filename="src/adw-tab-button.c" + line="409">the tab view + a squeezer page - + filename="src/adw-tab-button.c" + line="405">a tab button + - - + Sets whether @self is enabled. - -If a child is disabled, it will be ignored when looking for the child -fitting the available size best. - -This allows to programmatically and prematurely hide a child even if it fits -in the available space. - -This can be used e.g. to ensure a certain child is hidden below a certain -window width, or any other constraint you find suitable. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-button.c" + line="421">Sets the tab view to display. + a squeezer page - + filename="src/adw-tab-button.c" + line="423">a tab button + - + whether @self is enabled - + filename="src/adw-tab-button.c" + line="424">a tab view + - - - - - The the squeezer child to which the page belongs. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - - + + - - + setter="set_view" + getter="get_view"> Whether the child is enabled. - -If a child is disabled, it will be ignored when looking for the child -fitting the available size best. - -This allows to programmatically and prematurely hide a child even if it -fits in the available space. - -This can be used e.g. to ensure a certain child is hidden below a certain -window width, or any other constraint you find suitable. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - + filename="src/adw-tab-button.c" + line="251">The view the tab button displays. + + + Emitted to animate press then release. + +This is an action signal. Applications should never connect to this signal, +but use the [signal@TabButton::clicked] signal. + + + + + + Emitted when the button has been activated (pressed and released). + + + + - - + + - + - - Describes the possible transitions in a [class@Squeezer] widget. - See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) - - No transition - - - A cross-fade - - - + glib:type-name="AdwTabOverview" + glib:get-type="adw_tab_overview_get_type" + glib:type-struct="TabOverviewClass"> A page used for empty/error states and similar use-cases. + filename="src/adw-tab-overview.c" + line="31">A tab overview for [class@TabView]. <picture> - <source srcset="status-page-dark.png" media="(prefers-color-scheme: dark)"> - <img src="status-page.png" alt="status-page"> + <source srcset="tab-overview-dark.png" media="(prefers-color-scheme: dark)"> + <img src="tab-overview.png" alt="tab-overview"> </picture> -The `AdwStatusPage` widget can have an icon, a title, a description and a -custom widget which is displayed below them. +`AdwTabOverview` is a widget that can display tabs from an `AdwTabView` in a +grid. -## CSS nodes +`AdwTabOverview` shows a thumbnail for each tab. By default thumbnails are +static for all pages except the selected one. They can be made always live +by setting [property@TabPage:live-thumbnail] to `TRUE`, or refreshed with +[method@TabPage.invalidate_thumbnail] or +[method@TabView.invalidate_thumbnails] otherwise. -`AdwStatusPage` has a main CSS node with name `statuspage`. +If the pages are too tall or too wide, the thumbnails will be cropped; use +[property@TabPage:thumbnail-xalign] and [property@TabPage:thumbnail-yalign] to +control which part of the page should be visible in this case. -`AdwStatusPage` can use the -[`.compact`](style-classes.html#compact-status-page) style class for when it -needs to fit into a small space such a sidebar or a popover. - +Pinned tabs are shown as smaller cards without thumbnails above the other +tabs. Unlike in [class@TabBar], they still have titles, as well as an unpin +button. + +`AdwTabOverview` provides search in open tabs. It searches in tab titles and +tooltips, as well as [property@TabPage:keyword]. + +If [property@TabOverview:enable-new-tab] is set to `TRUE`, a new tab button +will be shown. Connect to the [signal@TabOverview::create-tab] signal to use +it. + +[property@TabOverview:secondary-menu] can be used to provide a secondary menu +for the overview. Use it to add extra actions, e.g. to open a new window or +undo closed tab. + +`AdwTabOverview` is intended to be used as the direct child of the window, +with the rest of the window contents set as the [property@TabOverview:child]. +The child is expected to contain an [class@TabView]. + +`AdwTabOverview` shows window buttons by default. They can be disabled by +setting [property@TabOverview:show-start-title-buttons] and/or +[property@TabOverview:show-start-title-buttons] and/or +[property@TabOverview:show-end-title-buttons] to `FALSE`. + +If search and window buttons are disabled, and secondary menu is not set, the +header bar will be hidden. + +## Actions + +`AdwTabOverview` defines the `overview.open` and `overview.close` actions for +opening and closing itself. They can be convenient when used together with +[class@TabButton]. + +## CSS nodes + +`AdwTabOverview` has a single CSS node with name `taboverview`. + - + Creates a new `AdwStatusPage`. - + filename="src/adw-tab-overview.c" + line="1912">Creates a new `AdwTabOverview`. + the newly created `AdwStatusPage` + filename="src/adw-tab-overview.c" + line="1917">the newly created `AdwTabOverview` - + c:identifier="adw_tab_overview_get_child" + glib:get-property="child" + version="1.3"> Gets the child widget of @self. - + filename="src/adw-tab-overview.c" + line="2023">Gets the child widget of @self. + the child widget of @self + filename="src/adw-tab-overview.c" + line="2029">the child widget of @self a status page - + filename="src/adw-tab-overview.c" + line="2025">a tab overview + - - + Gets the description markup for @self. - - + filename="src/adw-tab-overview.c" + line="2303">Gets whether to new tab button is enabled for @self. + + the description - + filename="src/adw-tab-overview.c" + line="2309">whether new tab button is enabled + a status page - + filename="src/adw-tab-overview.c" + line="2305">a tab overview + - - + Gets the icon name for @self. - - + filename="src/adw-tab-overview.c" + line="2223">Gets whether search in tabs is enabled for @self. + + the icon name - + filename="src/adw-tab-overview.c" + line="2229">whether search is enabled + a status page - + filename="src/adw-tab-overview.c" + line="2225">a tab overview + - - + Gets the paintable for @self. - - + filename="src/adw-tab-overview.c" + line="2545">Gets the current action during a drop on the extra_drop_target. + + the paintable - + filename="src/adw-tab-overview.c" + line="2551">the drag action of the current drop. + a status page - + filename="src/adw-tab-overview.c" + line="2547">a tab overview + - - + Gets the title for @self. - + filename="src/adw-tab-overview.c" + line="2563">Gets whether drop data should be preloaded on hover. + the title - + filename="src/adw-tab-overview.c" + line="2569">whether drop data should be preloaded on hover + a status page - + filename="src/adw-tab-overview.c" + line="2565">a tab overview + - - + Sets the child widget of @self. - + filename="src/adw-tab-overview.c" + line="2176">Gets whether thumbnails use inverted layout. + - + whether thumbnails use inverted layout + a status page - + filename="src/adw-tab-overview.c" + line="2178">a tab overview + - + + + + Gets whether @self is open. + + + whether the overview is open + + + + the child widget - - + filename="src/adw-tab-overview.c" + line="2070">a tab overview + + - - + Sets the description markup for @self. + filename="src/adw-tab-overview.c" + line="2283">Gets whether search is currently active for @self. -The description is displayed below the title. It is parsed as Pango markup. - +See [property@TabOverview:enable-search]. + - + whether search is active + a status page - + filename="src/adw-tab-overview.c" + line="2285">a tab overview + - + + + + Gets the secondary menu model for @self. + + + the secondary menu model + + + + the description - - + filename="src/adw-tab-overview.c" + line="2352">a tab overview + + - - + Sets the icon name for @self. - -Changing this will set [property@StatusPage:paintable] to `NULL`. - + filename="src/adw-tab-overview.c" + line="2445">Gets whether end title buttons are shown in @self's header bar. + - + whether end title buttons are shown + a status page - + filename="src/adw-tab-overview.c" + line="2447">a tab overview + - + + + + Gets whether start title buttons are shown in @self's header bar. + + + whether start title buttons are shown + + + + the icon name - - + filename="src/adw-tab-overview.c" + line="2399">a tab overview + + - - + Sets the paintable for @self. - -Changing this will set [property@StatusPage:icon-name] to `NULL`. - + filename="src/adw-tab-overview.c" + line="1927">Gets the tab view @self controls. + + + the tab view + + + + + a tab overview + + + + + + Sets the child widget of @self. + a status page - + filename="src/adw-tab-overview.c" + line="2043">a tab overview + - the paintable - + filename="src/adw-tab-overview.c" + line="2044">the child widget + - - + Sets the title for @self. + filename="src/adw-tab-overview.c" + line="2321">Sets whether to enable new tab button for @self. -The title is displayed below the icon. It is not parsed as Pango markup. - +Connect to the [signal@TabOverview::create-tab] signal to use it. + a status page - + filename="src/adw-tab-overview.c" + line="2323">a tab overview + - + the title - + filename="src/adw-tab-overview.c" + line="2324">whether to enable new tab button + - - - - The child widget. - - - - - - The description markup to be displayed below the title. - - - - - - The name of the icon to be used. - -Changing this will set [property@StatusPage:paintable] to `NULL`. - - - - - - The paintable to be used. - -Changing this will set [property@StatusPage:icon-name] to `NULL`. - - - - - + The title to be displayed below the icon. + filename="src/adw-tab-overview.c" + line="2241">Sets whether to enable search in tabs for @self. -It is not parsed as Pango markup. - - - - - - - - - - - A class for managing application-wide styling. +Search matches tab titles and tooltips, as well as keywords, set via +[property@TabPage:keyword]. Use keywords to search in e.g. page URLs in a web +browser. -`AdwStyleManager` provides a way to query and influence the application -styles, such as whether to use dark or high contrast appearance. +During search, tab reordering and drag-n-drop are disabled. -It allows to set the color scheme via the -[property@StyleManager:color-scheme] property, and to query the current -appearance, as well as whether a system-wide color scheme preference exists. - - +Use [property@TabOverview:search-active] to check out if search is currently +active. + + + + + + + a tab overview + + + + whether to enable search + + + + + Gets the default `AdwStyleManager` instance. - -It manages all [class@Gdk.Display] instances unless the style manager for -that display has an override. + filename="src/adw-tab-overview.c" + line="2581">Sets whether drop data should be preloaded on hover. -See [func@StyleManager.get_for_display]. - +See [property@Gtk.DropTarget:preload]. + - the default style manager - + - - + + + a tab overview + + + + whether to preload drop data + + + + + Gets the `AdwStyleManager` instance managing @display. - -It can be used to override styles for that specific display instead of the -whole application. + filename="src/adw-tab-overview.c" + line="2194">Sets whether thumbnails use inverted layout. -Most applications should use [func@StyleManager.get_default] instead. - +If set to `TRUE`, thumbnails will have the close or unpin button at the +beginning and the indicator at the end rather than the other way around. + - the style manager for @display - + - + a `GdkDisplay` - + filename="src/adw-tab-overview.c" + line="2196">a tab overview + + + + whether thumbnails use inverted layout + - - - + + Gets the requested application color scheme. - + filename="src/adw-tab-overview.c" + line="2086">Sets whether the to open @self. + - the color scheme - + a style manager - + filename="src/adw-tab-overview.c" + line="2088">a tab overview + + + whether the overview is open + + - - + Gets whether the application is using dark appearance. + filename="src/adw-tab-overview.c" + line="2368">Sets the secondary menu model for @self. -This can be used to query the current appearance, as requested via -[property@StyleManager:color-scheme]. - +Use it to add extra actions, e.g. to open a new window or undo closed tab. + - whether the application is using dark appearance - + a style manager - + filename="src/adw-tab-overview.c" + line="2370">a tab overview + + + a menu model + + - - + Gets the display the style manager is associated with. + filename="src/adw-tab-overview.c" + line="2463">Sets whether to show end title buttons in @self's header bar. -The display will be `NULL` for the style manager returned by -[func@StyleManager.get_default]. - - - the display - +See [property@HeaderBar:show-start-title-buttons] for the other side. + + + a style manager - + filename="src/adw-tab-overview.c" + line="2465">a tab overview + + + whether to show end title buttons + + - - + Gets whether the application is using high contrast appearance. + filename="src/adw-tab-overview.c" + line="2415">Sets whether to show start title buttons in @self's header bar. -This cannot be overridden by applications. - +See [property@HeaderBar:show-end-title-buttons] for the other side. + - whether the application is using high contrast appearance - + a style manager - + filename="src/adw-tab-overview.c" + line="2417">a tab overview + + + whether to show start title buttons + + - - + Gets whether the system supports color schemes. + filename="src/adw-tab-overview.c" + line="1945">Sets the tab view to control. -This can be used to check if the current environment provides a color scheme -preference. For example, applications might want to show a separate -appearance switcher if it's set to `FALSE`. - +The view must be inside @self, see [property@TabOverview:child]. + - whether the system supports color schemes - + a style manager - + filename="src/adw-tab-overview.c" + line="1947">a tab overview + + + a tab view + + - - + Sets the requested application color scheme. - -The effective appearance will be decided based on the application color -scheme and the system preferred color scheme. The -[property@StyleManager:dark] property can be used to query the current -effective appearance. - -The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application -using light appearance unless the system prefers dark colors. This is the -default value. - -The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application -using dark appearance, but can still switch to the light appearance if the -system can prefers it, for example, when the high contrast preference is -enabled. + filename="src/adw-tab-overview.c" + line="2493">Sets the supported types for this drop target. -The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values -ignore the system preference entirely. They are useful if the application -wants to match its UI to its content or to provide a separate color scheme -switcher. +Sets up an extra drop target on tabs. -If a per-[class@Gdk.Display] style manager has its color scheme set to -`ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the -default style manager. +This allows to drag arbitrary content onto tabs, for example URLs in a web +browser. -For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to -`ADW_COLOR_SCHEME_PREFER_LIGHT`. +If a tab is hovered for a certain period of time while dragging the content, +it will be automatically selected. -The [property@StyleManager:system-supports-color-schemes] property can be -used to check if the current environment provides a color scheme -preference. - +The [signal@TabOverview::extra-drag-drop] signal can be used to handle the +drop. + a style manager - + filename="src/adw-tab-overview.c" + line="2495">a tab overview + - + the color scheme - + filename="src/adw-tab-overview.c" + line="2496">the supported actions + + + + + all supported `GType`s that can be dropped + + + + + + number of @types + - - - + setter="set_child" + getter="get_child"> The requested application color scheme. + filename="src/adw-tab-overview.c" + line="1557">The child widget. + + + + Whether to enable new tab button. -The effective appearance will be decided based on the application color -scheme and the system preferred color scheme. The -[property@StyleManager:dark] property can be used to query the current -effective appearance. +Connect to the [signal@TabOverview::create-tab] signal to use it. + + + + Whether to enable search in tabs. -The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application -using light appearance unless the system prefers dark colors. This is the -default value. +Search matches tab titles and tooltips, as well as keywords, set via +[property@TabPage:keyword]. Use keywords to search in e.g. page URLs in a +web browser. -The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application -using dark appearance, but can still switch to the light appearance if the -system can prefers it, for example, when the high contrast preference is -enabled. +During search, tab reordering and drag-n-drop are disabled. -The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values -ignore the system preference entirely. They are useful if the application -wants to match its UI to its content or to provide a separate color scheme -switcher. +Use [property@TabOverview:search-active] to check out if search is +currently active. + + + + The unique action on the `current-drop` of the +[signal@TabOverview::extra-drag-drop]. -If a per-[class@Gdk.Display] style manager has its color scheme set to -`ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the -default style manager. +This property should only be used during a +[signal@TabOverview::extra-drag-drop] and is always a subset of what was +originally passed to [method@TabOverview.setup_extra_drop_target]. + + + + Whether the drop data should be preloaded on hover. -For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to -`ADW_COLOR_SCHEME_PREFER_LIGHT`. +See [property@Gtk.DropTarget:preload]. + + + + Whether thumbnails use inverted layout. -The [property@StyleManager:system-supports-color-schemes] property can be -used to check if the current environment provides a color scheme -preference. - +If set to `TRUE`, thumbnails will have the close or unpin buttons at the +beginning and the indicator at the end rather than the other way around. + - - Whether the application is using dark appearance. + filename="src/adw-tab-overview.c" + line="1569">Whether the overview is open. + + + + Whether search is currently active. -This property can be used to query the current appearance, as requested via -[property@StyleManager:color-scheme]. +See [property@TabOverview:enable-search]. - - + setter="set_secondary_menu" + getter="get_secondary_menu"> The display the style manager is associated with. + filename="src/adw-tab-overview.c" + line="1645">The secondary menu model. -The display will be `NULL` for the style manager returned by -[func@StyleManager.get_default]. - +Use it to add extra actions, e.g. to open a new window or undo closed tab. + - - + setter="set_show_end_title_buttons" + getter="get_show_end_title_buttons" + default-value="TRUE"> Whether the application is using high contrast appearance. + filename="src/adw-tab-overview.c" + line="1673">Whether to show end title buttons in the overview's header bar. -This cannot be overridden by applications. +See [property@HeaderBar:show-start-title-buttons] for the other side. - - + setter="set_show_start_title_buttons" + getter="get_show_start_title_buttons" + default-value="TRUE"> + Whether to show start title buttons in the overview's header bar. + +See [property@HeaderBar:show-end-title-buttons] for the other side. + + + + The tab view the overview controls. + +The view must be inside the tab overview, see [property@TabOverview:child]. + + + + Emitted when a tab needs to be created. + +This can happen after the new tab button has been pressed, see +[property@TabOverview:enable-new-tab]. + +The signal handler is expected to create a new page in the corresponding +[class@TabView] and return it. + + the newly created page + + + + Whether the system supports color schemes. + filename="src/adw-tab-overview.c" + line="1750">This signal is emitted when content is dropped onto a tab. -This property can be used to check if the current environment provides a -color scheme preference. For example, applications might want to show a -separate appearance switcher if it's set to `FALSE`. +The content must be of one of the types set up via +[method@TabOverview.setup_extra_drop_target]. -See [property@StyleManager:color-scheme]. - - - - - - - - - - - A swipe tracker used in [class@Carousel], [class@NavigationView] and -[class@OverlaySplitView]. +See [signal@Gtk.DropTarget::drop]. + + whether the drop was accepted for @page + + + + + the page matching the tab the content was dropped onto + + + + the `GValue` being dropped + + + + + + This signal is emitted when the dropped content is preloaded. -The `AdwSwipeTracker` object can be used for implementing widgets with swipe -gestures. It supports touch-based swipes, pointer dragging, and touchpad -scrolling. +In order for data to be preloaded, [property@TabOverview:extra-drag-preload] +must be set to `TRUE`. -The widgets will probably want to expose the [property@SwipeTracker:enabled] -property. If they expect to use horizontal orientation, -[property@SwipeTracker:reversed] can be used for supporting RTL text -direction. - - - - Creates a new `AdwSwipeTracker` for @widget. - - +The content must be of one of the types set up via +[method@TabOverview.setup_extra_drop_target]. + +See [property@Gtk.DropTarget:value]. + the newly created `AdwSwipeTracker` - + filename="src/adw-tab-overview.c" + line="1795">the preferred action for the drop on @page + - + a widget to add the tracker on - + filename="src/adw-tab-overview.c" + line="1782">the page matching the tab the content was dropped onto + + + + the `GValue` being dropped + - - - + + + + + + + + + + An auxiliary class used by [class@TabView]. + + + Gets whether to allow swiping for more than one snap point at a time. - + filename="src/adw-tab-view.c" + line="2813">Gets the child of @self. + whether long swipes are allowed - + filename="src/adw-tab-view.c" + line="2819">the child of @self + a swipe tracker - + filename="src/adw-tab-view.c" + line="2815">a tab page + - - + Gets whether @self can be dragged with mouse pointer. - - + filename="src/adw-tab-view.c" + line="2967">Gets the icon of @self. + + whether mouse dragging is allowed - + filename="src/adw-tab-view.c" + line="2973">the icon of @self + a swipe tracker - + filename="src/adw-tab-view.c" + line="2969">a tab page + - - + Gets whether @self is enabled. - + filename="src/adw-tab-view.c" + line="3150">Gets whether the indicator of @self is activatable. + whether @self is enabled + filename="src/adw-tab-view.c" + line="3157">whether the indicator is activatable a swipe tracker - + filename="src/adw-tab-view.c" + line="3152">a tab page + - - + Gets whether to allow swiping past the first available snap point. - - + filename="src/adw-tab-view.c" + line="3054">Gets the indicator icon of @self. + + whether to allow swiping past the first available snap point - + filename="src/adw-tab-view.c" + line="3060">the indicator icon of @self + a swipe tracker - + filename="src/adw-tab-view.c" + line="3056">a tab page + - - + Gets whether @self is reversing the swipe direction. - + filename="src/adw-tab-view.c" + line="3106">Gets the tooltip of the indicator icon of @self. + whether the direction is reversed - + filename="src/adw-tab-view.c" + line="3112">the indicator tooltip of @self + a swipe tracker - + filename="src/adw-tab-view.c" + line="3108">a tab page + - - + Get the widget @self is attached to. - - + filename="src/adw-tab-view.c" + line="3244">Gets the search keyword of @self. + + the swipeable widget - + filename="src/adw-tab-view.c" + line="3250">the search keyword of @self + a swipe tracker - + filename="src/adw-tab-view.c" + line="3246">a tab page + - - + Gets whether to allow swiping past the last available snap point. - + filename="src/adw-tab-view.c" + line="3392">Gets whether to live thumbnail is enabled @self. + whether to allow swiping past the last available snap point + filename="src/adw-tab-view.c" + line="3398">whether live thumbnail is enabled a swipe tracker - + filename="src/adw-tab-view.c" + line="3394">a tab overview + - - + Sets whether to allow swiping for more than one snap point at a time. - -If the value is `FALSE`, each swipe can only move to the adjacent snap -points. - + filename="src/adw-tab-view.c" + line="3009">Gets whether @self is loading. + - + whether @self is loading + a swipe tracker - + filename="src/adw-tab-view.c" + line="3011">a tab page + - - whether to allow long swipes - - - - + Sets whether @self can be dragged with mouse pointer. - + filename="src/adw-tab-view.c" + line="3195">Gets whether @self needs attention. + - + whether @self needs attention + a swipe tracker - + filename="src/adw-tab-view.c" + line="3197">a tab page + - - whether to allow mouse dragging - - - - + Sets whether @self is enabled. + filename="src/adw-tab-view.c" + line="2829">Gets the parent page of @self. -When it's not enabled, no events will be processed. Usually widgets will want -to expose this via a property. - - - +See [method@TabView.add_page] and [method@TabView.close_page]. + + + the parent page + a swipe tracker - + filename="src/adw-tab-view.c" + line="2831">a tab page + - - whether @self is enabled - - - - + Sets whether to allow swiping past the first available snap point. - + filename="src/adw-tab-view.c" + line="2863">Gets whether @self is pinned. + +See [method@TabView.set_page_pinned]. + - + whether @self is pinned + a swipe tracker - + filename="src/adw-tab-view.c" + line="2865">a tab page + - - whether to allow swiping past the first available snap point - - - - + Sets whether to reverse the swipe direction. - -If the swipe tracker is horizontal, it can be used for supporting RTL text -direction. - + filename="src/adw-tab-view.c" + line="2847">Gets whether @self is selected. + - + whether @self is selected + a swipe tracker - + filename="src/adw-tab-view.c" + line="2849">a tab page + - - whether to reverse the swipe direction - - - - + Sets whether to allow swiping past the last available snap point. - + filename="src/adw-tab-view.c" + line="3288">Gets the horizontal alignment of the thumbnail for @self. + - + the horizontal alignment + a swipe tracker - + filename="src/adw-tab-view.c" + line="3290">a tab page + - - whether to allow swiping past the last available snap point - - - + Moves the current progress value by @delta. - -This can be used to adjust the current position if snap points move during -the gesture. - + filename="src/adw-tab-view.c" + line="3340">Gets the vertical alignment of the thumbnail for @self. + - + the vertical alignment + a swipe tracker - - - - the position delta - - - - - - - - Whether to allow swiping for more than one snap point at a time. - -If the value is `FALSE`, each swipe can only move to the adjacent snap -points. - - - - - - Whether to allow dragging with mouse pointer. - - - - - - Whether the swipe tracker is enabled. - -When it's not enabled, no events will be processed. Usually widgets will -want to expose this via a property. - - - - - - Whether to allow swiping past the first available snap point. - - - - - - Whether to reverse the swipe direction. - -If the swipe tracker is horizontal, it can be used for supporting RTL text -direction. - - - - - The widget the swipe tracker is attached to. - - - - - - Whether to allow swiping past the last available snap point. - - - + filename="src/adw-tab-view.c" + line="3342">a tab overview + + + + + This signal is emitted right before a swipe will be started, after the -drag threshold has been passed. + filename="src/adw-tab-view.c" + line="2881">Gets the title of @self. + - + the title of @self + - - + + + a tab page + + + + + This signal is emitted as soon as the gesture has stopped. + filename="src/adw-tab-view.c" + line="2927">Gets the tooltip of @self. + + + the tooltip of @self + + + + + a tab page + + + + + + Invalidates thumbnail for @self. -The user is expected to animate the deceleration from the current progress -value to @to with an animation using @velocity as the initial velocity, -provided in pixels per second. [class@SpringAnimation] is usually a good -fit for this. +If an [class@TabOverview] is open, the thumbnail representing @self will be +immediately updated. Otherwise it will be update when opening the overview. + +Does nothing if [property@TabPage:live-thumbnail] is set to `TRUE`. + +See also [method@TabView.invalidate_thumbnails]. + - - the velocity of the swipe - - - + the progress value to animate to - - + filename="src/adw-tab-view.c" + line="3448">a tab page + + - - + + This signal is emitted when a possible swipe is detected. + filename="src/adw-tab-view.c" + line="2983">Sets the icon of @self. -The @direction value can be used to restrict the swipe to a certain -direction. +[class@TabBar] and [class@TabOverview] display the icon next to the title, +unless [property@TabPage:loading] is set to `TRUE`. + +`AdwTabBar` also won't show the icon if the page is pinned and +[propertyTabPage:indicator-icon] is set. + - + the direction of the swipe - + filename="src/adw-tab-view.c" + line="2985">a tab page + + + + the icon of @self + - - + + This signal is emitted every time the progress value changes. + filename="src/adw-tab-view.c" + line="3167">Sets whether the indicator of @self is activatable. + +If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted +when the indicator icon is clicked. + +If [property@TabPage:indicator-icon] is not set, does nothing. + - + the current animation progress value - + filename="src/adw-tab-view.c" + line="3169">a tab page + + + + whether the indicator is activatable + - - - - - - - - - - An interface for swipeable widgets. + + + Sets the indicator icon of @self. -The `AdwSwipeable` interface is implemented by all swipeable widgets. +A common use case is an audio or camera indicator in a web browser. -See [class@SwipeTracker] for details about implementing it. - - - - Gets the progress @self will snap back to after the gesture is canceled. - +[class@TabBar] will show it at the beginning of the tab, alongside icon +representing [property@TabPage:icon] or loading spinner. + +If the page is pinned, the indicator will be shown instead of icon or +spinner. + +[class@TabOverview] will show it at the at the top part of the thumbnail. + +[property@TabPage:indicator-tooltip] can be used to set the tooltip on the +indicator icon. + +If [property@TabPage:indicator-activatable] is set to `TRUE`, the +indicator icon can act as a button. + - the cancel progress, unitless - + a swipeable - + filename="src/adw-tab-view.c" + line="3072">a tab page + + + the indicator icon of @self + + - - + + Gets the swipe distance of @self. + filename="src/adw-tab-view.c" + line="3124">Sets the tooltip of the indicator icon of @self. -This corresponds to how many pixels 1 unit represents. - +The tooltip can be marked up with the Pango text markup language. + +See [property@TabPage:indicator-icon]. + - the swipe distance in pixels - + a swipeable - + filename="src/adw-tab-view.c" + line="3126">a tab page + + + the indicator tooltip of @self + + - - + + Gets the current progress of @self. - + filename="src/adw-tab-view.c" + line="3262">Sets the search keyword for @self. + +[class@TabOverview] can search pages by their keywords in addition to their +titles and tooltips. + +Keywords allow to include e.g. page URLs into tab search in a web browser. + - the current progress, unitless - + a swipeable - + filename="src/adw-tab-view.c" + line="3264">a tab page + + + the search keyword + + - - + + Gets the snap points of @self. + filename="src/adw-tab-view.c" + line="3410">Sets whether to enable live thumbnail for @self. -Each snap point represents a progress value that is considered acceptable to -end the swipe on. - - - the snap points - - - +When set to `TRUE`, @self's thumbnail in [class@TabOverview] will update +immediately when @self is redrawn or resized. + +If it's set to `FALSE`, the thumbnail will only be live when the @self is +selected, and otherwise it will be static and will only update when +[method@TabPage.invalidate_thumbnail] or +[method@TabView.invalidate_thumbnails] is called. + + + a swipeable - + filename="src/adw-tab-view.c" + line="3412">a tab page + - + location to return the number of the snap points - + filename="src/adw-tab-view.c" + line="3413">whether to enable live thumbnail + - - + + Gets the area @self can start a swipe from for the given direction and -gesture type. + filename="src/adw-tab-view.c" + line="3025">Sets whether @self is loading. -This can be used to restrict swipes to only be possible from a certain area, -for example, to only allow edge swipes, or to have a draggable element and -ignore swipes elsewhere. +If set to `TRUE`, [class@TabBar] and [class@TabOverview] will display a +spinner in place of icon. -If not implemented, the default implementation returns the allocation of -@self, allowing swipes from anywhere. - +If the page is pinned and [property@TabPage:indicator-icon] is set, loading +status will not be visible with `AdwTabBar`. + a swipeable - + filename="src/adw-tab-view.c" + line="3027">a tab page + - - the direction of the swipe - - - + whether the swipe is caused by a dragging gesture + filename="src/adw-tab-view.c" + line="3028">whether @self is loading - - a pointer to a rectangle to store the swipe area - - - - + + Gets the progress @self will snap back to after the gesture is canceled. - + filename="src/adw-tab-view.c" + line="3211">Sets whether @self needs attention. + +[class@TabBar] will display a line under the tab representing the page if +set to `TRUE`. If the tab is not visible, the corresponding edge of the tab +bar will be highlighted. + +[class@TabOverview] will display a dot in the corner of the thumbnail if set +to `TRUE`. + +[class@TabButton] will display a dot if any of the pages that aren't +selected have [property@TabPage:needs-attention] set to `TRUE`. + - the cancel progress, unitless - + a swipeable - + filename="src/adw-tab-view.c" + line="3213">a tab page + + + whether @self needs attention + + - + Gets the swipe distance of @self. + filename="src/adw-tab-view.c" + line="3306">Sets the horizontal alignment of the thumbnail for @self. -This corresponds to how many pixels 1 unit represents. - +If the page is so wide that [class@TabOverview] can't display it completely +and has to crop it, horizontal alignment will determine which part of the +page will be visible. + +For example, 0.5 means the center of the page will be visible, 0 means the +start edge will be visible and 1 means the end edge will be visible. + +The default horizontal alignment is 0. + - the swipe distance in pixels - + a swipeable - + filename="src/adw-tab-view.c" + line="3308">a tab page + + + the new value + + - + Gets the current progress of @self. - + filename="src/adw-tab-view.c" + line="3358">Sets the vertical alignment of the thumbnail for @self. + +If the page is so tall that [class@TabOverview] can't display it completely +and has to crop it, vertical alignment will determine which part of the page +will be visible. + +For example, 0.5 means the center of the page will be visible, 0 means the +top edge will be visible and 1 means the bottom edge will be visible. + +The default vertical alignment is 0. + - the current progress, unitless - + a swipeable - + filename="src/adw-tab-view.c" + line="3360">a tab page + + + the new value + + - + Gets the snap points of @self. + filename="src/adw-tab-view.c" + line="2897">[class@TabBar] will display it in the center of the tab unless it's pinned, +and will use it as a tooltip unless [property@TabPage:tooltip] is set. -Each snap point represents a progress value that is considered acceptable to -end the swipe on. - - - the snap points - - - +[class@TabOverview] will display it below the thumbnail unless it's pinned, +or inside the card otherwise, and will use it as a tooltip unless +[property@TabPage:tooltip] is set. + +Sets the title of @self. + + + a swipeable - + filename="src/adw-tab-view.c" + line="2899">a tab page + - + location to return the number of the snap points - + filename="src/adw-tab-view.c" + line="2900">the title of @self + - + Gets the area @self can start a swipe from for the given direction and -gesture type. + filename="src/adw-tab-view.c" + line="2943">Sets the tooltip of @self. -This can be used to restrict swipes to only be possible from a certain area, -for example, to only allow edge swipes, or to have a draggable element and -ignore swipes elsewhere. +The tooltip can be marked up with the Pango text markup language. -If not implemented, the default implementation returns the allocation of -@self, allowing swipes from anywhere. - +If not set, [class@TabBar] and [class@TabOverview] will use +[property@TabPage:title] as a tooltip instead. + a swipeable - + filename="src/adw-tab-view.c" + line="2945">a tab page + - - the direction of the swipe - - - - whether the swipe is caused by a dragging gesture - - - + a pointer to a rectangle to store the swipe area - + filename="src/adw-tab-view.c" + line="2946">the tooltip of @self + - - - An interface for swipeable widgets. - - + The parent interface. - - - - - - - the swipe distance in pixels - - - - - a swipeable - - - - - - - - - - the snap points - - - - - - - a swipeable - - - - location to return the number of the snap points - - - - - - - - - - the current progress, unitless - - - - - a swipeable - - - - - - - - - - the cancel progress, unitless - - - - - a swipeable - - - - - - - - - - - - - - a swipeable - - - - the direction of the swipe - - - - whether the swipe is caused by a dragging gesture - - - - a pointer to a rectangle to store the swipe area - - - - - - - - - + filename="src/adw-tab-view.c" + line="558">The child of the page. + + + + The icon of the page. + +[class@TabBar] and [class@TabOverview] display the icon next to the title, +unless [property@TabPage:loading] is set to `TRUE`. + +`AdwTabBar` also won't show the icon if the page is pinned and +[propertyTabPage:indicator-icon] is set. + + + + Whether the indicator icon is activatable. + +If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted +when the indicator icon is clicked. + +If [property@TabPage:indicator-icon] is not set, does nothing. + + + + An indicator icon for the page. + +A common use case is an audio or camera indicator in a web browser. + +[class@TabBar] will show it at the beginning of the tab, alongside icon +representing [property@TabPage:icon] or loading spinner. + +If the page is pinned, the indicator will be shown instead of icon or +spinner. + +[class@TabOverview] will show it at the at the top part of the thumbnail. + +[property@TabPage:indicator-tooltip] can be used to set the tooltip on the +indicator icon. + +If [property@TabPage:indicator-activatable] is set to `TRUE`, the +indicator icon can act as a button. + + + + The tooltip of the indicator icon. + +The tooltip can be marked up with the Pango text markup language. + +See [property@TabPage:indicator-icon]. + + + + The search keyboard of the page. + +[class@TabOverview] can search pages by their keywords in addition to their +titles and tooltips. + +Keywords allow to include e.g. page URLs into tab search in a web browser. + + + + Whether to enable live thumbnail for this page. + +When set to `TRUE`, the page's thumbnail in [class@TabOverview] will update +immediately when the page is redrawn or resized. + +If it's set to `FALSE`, the thumbnail will only be live when the page is +selected, and otherwise it will be static and will only update when +[method@TabPage.invalidate_thumbnail] or +[method@TabView.invalidate_thumbnails] is called. + + + + Whether the page is loading. + +If set to `TRUE`, [class@TabBar] and [class@TabOverview] will display a +spinner in place of icon. + +If the page is pinned and [property@TabPage:indicator-icon] is set, +loading status will not be visible with `AdwTabBar`. + + + + Whether the page needs attention. + +[class@TabBar] will display a line under the tab representing the page if +set to `TRUE`. If the tab is not visible, the corresponding edge of the tab +bar will be highlighted. + +[class@TabOverview] will display a dot in the corner of the thumbnail if set +to `TRUE`. + +[class@TabButton] will display a dot if any of the pages that aren't +selected have this property set to `TRUE`. + + + + The parent page of the page. + +See [method@TabView.add_page] and [method@TabView.close_page]. + + + + Whether the page is pinned. + +See [method@TabView.set_page_pinned]. + + + + Whether the page is selected. + + + + The horizontal alignment of the page thumbnail. + +If the page is so wide that [class@TabOverview] can't display it completely +and has to crop it, horizontal alignment will determine which part of the +page will be visible. + +For example, 0.5 means the center of the page will be visible, 0 means the +start edge will be visible and 1 means the end edge will be visible. + +The default horizontal alignment is 0. + + + + The vertical alignment of the page thumbnail. + +If the page is so tall that [class@TabOverview] can't display it completely +and has to crop it, vertical alignment will determine which part of the +page will be visible. + +For example, 0.5 means the center of the page will be visible, 0 means the +top edge will be visible and 1 means the bottom edge will be visible. + +The default vertical alignment is 0. + + + + The title of the page. + +[class@TabBar] will display it in the center of the tab unless it's pinned, +and will use it as a tooltip unless [property@TabPage:tooltip] is set. + +[class@TabOverview] will display it below the thumbnail unless it's pinned, +or inside the card otherwise, and will use it as a tooltip unless +[property@TabPage:tooltip] is set. + + + + The tooltip of the page. + +The tooltip can be marked up with the Pango text markup language. + +If not set, [class@TabBar] and [class@TabOverview] will use +[property@TabPage:title] as a tooltip instead. + + + + + + + - + glib:type-name="AdwTabView" + glib:get-type="adw_tab_view_get_type" + glib:type-struct="TabViewClass"> A [class@Gtk.ListBoxRow] used to represent two states. + filename="src/adw-tab-view.c" + line="31">A dynamic tabbed container. -<picture> - <source srcset="switch-row-dark.png" media="(prefers-color-scheme: dark)"> - <img src="switch-row.png" alt="switch-row"> -</picture> +`AdwTabView` is a container which shows one child at a time. While it +provides keyboard shortcuts for switching between pages, it does not provide +a visible tab switcher and relies on external widgets for that, such as +[class@TabBar], [class@TabOverview] and [class@TabButton]. -The `AdwSwitchRow` widget contains a [class@Gtk.Switch] that allows the user -to select between two states: "on" or "off". When activated, the row will -invert its active state. +`AdwTabView` maintains a [class@TabPage] object for each page, which holds +additional per-page properties. You can obtain the `AdwTabPage` for a page +with [method@TabView.get_page], and as the return value for +[method@TabView.append] and other functions for adding children. -The user can control the switch by activating the row or by dragging on the -switch handle. +`AdwTabView` only aims to be useful for dynamic tabs in multi-window +document-based applications, such as web browsers, file managers, text +editors or terminals. It does not aim to replace [class@Gtk.Notebook] for use +cases such as tabbed dialogs. -See [class@Gtk.Switch] for details. +As such, it does not support disabling page reordering or detaching. -Example of an `AdwSwitchRow` UI definition: -```xml -<object class="AdwSwitchRow"> - <property name="title" translatable="yes">Switch Row</property> - <signal name="notify::active" handler="switch_row_notify_active_cb"/> -</object> +`AdwTabView` adds a number of global page switching and reordering shortcuts. +The [property@TabView:shortcuts] property can be used to manage them. + +See [flags@TabViewShortcuts] for the list of the available shortcuts. All of +the shortcuts are enabled by default. + +[method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] can be +used to manage shortcuts in a convenient way, for example: + +```c +adw_tab_view_remove_shortcuts (view, ADW_TAB_VIEW_SHORTCUT_CONTROL_HOME | + ADW_TAB_VIEW_SHORTCUT_CONTROL_END); ``` -The [property@SwitchRow:active] property should be connected to in order to -monitor changes to the active state. - +## CSS nodes + +`AdwTabView` has a main CSS node with the name `tabview`. + +## Accessibility + +`AdwTabView` uses the `GTK_ACCESSIBLE_ROLE_TAB_PANEL` for the tab pages which +are the accessible parent objects of the child widgets. + - - + Creates a new `AdwSwitchRow`. - + filename="src/adw-tab-view.c" + line="3485">Creates a new `AdwTabView`. + the newly created `AdwSwitchRow` - + filename="src/adw-tab-view.c" + line="3490">the newly created `AdwTabView` + - - - + + Gets whether @self is in its "on" or "off" position. - + filename="src/adw-tab-view.c" + line="4068">Adds @child to @self with @parent as the parent. + +This function can be used to automatically position new pages, and to select +the correct page when this page is closed while being selected (see +[method@TabView.close_page]). + +If @parent is `NULL`, this function is equivalent to [method@TabView.append]. + whether @self is active or not - + filename="src/adw-tab-view.c" + line="4082">the page object representing @child + a switch row - + filename="src/adw-tab-view.c" + line="4070">a tab view + + + a widget to add + + + + a parent page for @child + + - - + Sets whether @self is in its "on" or "off" position - + filename="src/adw-tab-view.c" + line="3864">Adds @shortcuts for @self. + +See [property@TabView:shortcuts] for details. + a switch row - + filename="src/adw-tab-view.c" + line="3866">a tab view + - + whether @self should be active - + filename="src/adw-tab-view.c" + line="3867">the shortcuts to add + - - - - Whether the switch row is in the "on" or "off" position. - - - - - - - - - - - A tab bar for [class@TabView]. - -<picture> - <source srcset="tab-bar-dark.png" media="(prefers-color-scheme: dark)"> - <img src="tab-bar.png" alt="tab-bar"> -</picture> - -The `AdwTabBar` widget is a tab bar that can be used with conjunction with -`AdwTabView`. It is typically used as a top bar within [class@ToolbarView]. - -`AdwTabBar` can autohide and can optionally contain action widgets on both -sides of the tabs. - -When there's not enough space to show all the tabs, `AdwTabBar` will scroll -them. Pinned tabs always stay visible and aren't a part of the scrollable -area. - -## CSS nodes - -`AdwTabBar` has a single CSS node with name `tabbar`. - - - - - - Creates a new `AdwTabBar`. - - - the newly created `AdwTabBar` - - - - - + Gets whether the tabs automatically hide. - + filename="src/adw-tab-view.c" + line="4168">Inserts @child as the last non-pinned page. + whether the tabs automatically hide - + filename="src/adw-tab-view.c" + line="4175">the page object representing @child + a tab bar - + filename="src/adw-tab-view.c" + line="4170">a tab view + + + a widget to add + + - - + Gets the widget shown after the tabs. - - + filename="src/adw-tab-view.c" + line="4234">Inserts @child as the last pinned page. + + the widget shown after the tabs - + filename="src/adw-tab-view.c" + line="4241">the page object representing @child + a tab bar - + filename="src/adw-tab-view.c" + line="4236">a tab view + + + a widget to add + + - - + Gets whether tabs expand to full width. - + filename="src/adw-tab-view.c" + line="4335">Requests to close all pages other than @page. + - whether tabs expand to full width. - + a tab bar - + filename="src/adw-tab-view.c" + line="4337">a tab view + + + a page of @self + + - + Gets the current action during a drop on the extra_drop_target. - + filename="src/adw-tab-view.c" + line="4254">Requests to close @page. + +Calling this function will result in the [signal@TabView::close-page] signal +being emitted for @page. Closing the page can then be confirmed or +denied via [method@TabView.close_page_finish]. + +If the page is waiting for a [method@TabView.close_page_finish] call, this +function will do nothing. + +The default handler for [signal@TabView::close-page] will immediately confirm +closing the page if it's non-pinned, or reject it if it's pinned. This +behavior can be changed by registering your own handler for that signal. + +If @page was selected, another page will be selected instead: + +If the [property@TabPage:parent] value is `NULL`, the next page will be +selected when possible, or if the page was already last, the previous page +will be selected instead. + +If it's not `NULL`, the previous page will be selected if it's a descendant +(possibly indirect) of the parent. If both the previous page and the parent +are pinned, the parent will be selected instead. + - the drag action of the current drop. - + a tab bar - + filename="src/adw-tab-view.c" + line="4256">a tab view + + + a page of @self + + - + Gets whether drop data should be preloaded on hover. - + filename="src/adw-tab-view.c" + line="4299">Completes a [method@TabView.close_page] call for @page. + +If @confirm is `TRUE`, @page will be closed. If it's `FALSE`, it will be +reverted to its previous state and [method@TabView.close_page] can be called +for it again. + +This function should not be called unless a custom handler for +[signal@TabView::close-page] is used. + - whether drop data should be preloaded on hover - + a tab bar - + filename="src/adw-tab-view.c" + line="4301">a tab view + + + a page of @self + + + + whether to confirm or deny closing @page + + - - + Gets whether tabs use inverted layout. - + filename="src/adw-tab-view.c" + line="4388">Requests to close all pages after @page. + - whether tabs use inverted layout - + a tab bar - + filename="src/adw-tab-view.c" + line="4390">a tab view + + + a page of @self + + - - + Gets whether @self is overflowing. - -If `TRUE`, all tabs cannot be displayed at once and require scrolling. - + filename="src/adw-tab-view.c" + line="4362">Requests to close all pages before @page. + - whether @self is overflowing - + a tab bar - + filename="src/adw-tab-view.c" + line="4364">a tab view + + + a page of @self + + - - + Gets the widget shown before the tabs. - - + filename="src/adw-tab-view.c" + line="3717">Gets the default icon of @self. + + the widget shown before the tabs - + filename="src/adw-tab-view.c" + line="3723">the default icon of @self. + a tab bar - + filename="src/adw-tab-view.c" + line="3719">a tab view + - - + Gets whether the tabs are currently revealed. + filename="src/adw-tab-view.c" + line="3532">Whether a page is being transferred. -See [property@TabBar:autohide]. - +The corresponding property will be set to `TRUE` when a drag-n-drop tab +transfer starts on any `AdwTabView`, and to `FALSE` after it ends. + +During the transfer, children cannot receive pointer input and a tab can +be safely dropped on the tab view. + whether the tabs are currently revealed + filename="src/adw-tab-view.c" + line="3544">whether a page is being transferred a tab bar - + filename="src/adw-tab-view.c" + line="3534">a tab view + - - + Gets the tab view @self controls. - + filename="src/adw-tab-view.c" + line="3774">Gets the tab context menu model for @self. + the view @self controls - + filename="src/adw-tab-view.c" + line="3780">the tab context menu model for @self + a tab bar - + filename="src/adw-tab-view.c" + line="3776">a tab view + - - + Sets whether the tabs automatically hide. - -If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0 -or 1 tab, no pinned tabs, and no tab is being transferred. - -See [property@TabBar:tabs-revealed]. - + filename="src/adw-tab-view.c" + line="3498">Gets the number of pages in @self. + - + the number of pages in @self + a tab bar - + filename="src/adw-tab-view.c" + line="3500">a tab view + - - whether the tabs automatically hide - - - - + Sets the widget to show after the tabs. - + filename="src/adw-tab-view.c" + line="3514">Gets the number of pinned pages in @self. + +See [method@TabView.set_page_pinned]. + - + the number of pinned pages in @self + a tab bar - + filename="src/adw-tab-view.c" + line="3516">a tab view + - - the widget to show after the tabs - - - - + Sets whether tabs expand to full width. - -If set to `TRUE`, the tabs will always vary width filling the whole width -when possible, otherwise tabs will always have the minimum possible size. - + filename="src/adw-tab-view.c" + line="4013">Gets the [class@TabPage] representing the child at @position. + - + the page object at @position + a tab bar - + filename="src/adw-tab-view.c" + line="4015">a tab view + - + whether to expand tabs - + filename="src/adw-tab-view.c" + line="4016">the index of the page in @self, starting from 0 + - + Sets whether drop data should be preloaded on hover. - -See [property@Gtk.DropTarget:preload]. - + filename="src/adw-tab-view.c" + line="3984">Gets the [class@TabPage] object representing @child. + - + the page object for @child + a tab bar - + filename="src/adw-tab-view.c" + line="3986">a tab view + - + whether to preload drop data - + filename="src/adw-tab-view.c" + line="3987">a child in @self + - - + Sets whether tabs tabs use inverted layout. - -If set to `TRUE`, non-pinned tabs will have the close button at the beginning -and the indicator at the end rather than the opposite. - + filename="src/adw-tab-view.c" + line="4039">Finds the position of @page in @self, starting from 0. + - + the position of @page in @self + a tab bar - + filename="src/adw-tab-view.c" + line="4041">a tab view + - + whether tabs use inverted layout - + filename="src/adw-tab-view.c" + line="4042">a page of @self + - - - Sets the widget to show before the tabs. - - - + + Returns a [iface@Gio.ListModel] that contains the pages of @self. + +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the selected +page. + + + a `GtkSelectionModel` for the pages of @self + a tab bar - + filename="src/adw-tab-view.c" + line="4662">a tab view + - - the widget to show before the tabs - - - - + Sets the tab view @self controls. - - - + filename="src/adw-tab-view.c" + line="3554">Gets the currently selected page in @self. + + + the selected page + a tab bar - - - - a tab view + filename="src/adw-tab-view.c" + line="3556">a tab view - + - + Sets the supported types for this drop target. - -Sets up an extra drop target on tabs. - -This allows to drag arbitrary content onto tabs, for example URLs in a web -browser. - -If a tab is hovered for a certain period of time while dragging the content, -it will be automatically selected. - -The [signal@TabBar::extra-drag-drop] signal can be used to handle the drop. - + filename="src/adw-tab-view.c" + line="3816">Gets the enabled shortcuts for @self. + - + the shortcut mask + a tab bar - + filename="src/adw-tab-view.c" + line="3818">a tab view + - - the supported actions - - - - - all supported `GType`s that can be dropped - - - - - - number of @types - - - - - - Whether the tabs automatically hide. - -If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0 -or 1 tab, no pinned tabs, and no tab is being transferred. - -See [property@TabBar:tabs-revealed]. - - - - - - The widget shown after the tabs. - - - - - - Whether tabs expand to full width. - -If set to `TRUE`, the tabs will always vary width filling the whole width -when possible, otherwise tabs will always have the minimum possible size. - - - - - The unique action on the `current-drop` of the -[signal@TabBar::extra-drag-drop]. - -This property should only be used during a [signal@TabBar::extra-drag-drop] -and is always a subset of what was originally passed to -[method@TabBar.setup_extra_drop_target]. - - - - - - Whether the drop data should be preloaded on hover. - -See [property@Gtk.DropTarget:preload]. - - - - - - Whether tabs use inverted layout. - -If set to `TRUE`, non-pinned tabs will have the close button at the -beginning and the indicator at the end rather than the opposite. - - - - - Whether the tab bar is overflowing. - -If `TRUE`, all tabs cannot be displayed at once and require scrolling. - - - - - - The widget shown before the tabs. - - - - - Whether the tabs are currently revealed. - -See [property@TabBar:autohide]. - - - - - - The tab view the tab bar controls. - - - + This signal is emitted when content is dropped onto a tab. - -The content must be of one of the types set up via -[method@TabBar.setup_extra_drop_target]. + filename="src/adw-tab-view.c" + line="4121">Inserts a non-pinned page at @position. -See [signal@Gtk.DropTarget::drop]. +It's an error to try to insert a page before a pinned page, in that case +[method@TabView.insert_pinned] should be used instead. + whether the drop was accepted for @page - + filename="src/adw-tab-view.c" + line="4132">the page object representing @child + - + the page matching the tab the content was dropped onto - + filename="src/adw-tab-view.c" + line="4123">a tab view + + + + a widget to add + - + the `GValue` being dropped - + filename="src/adw-tab-view.c" + line="4125">the position to add @child at, starting from 0 + - - + + This signal is emitted when the dropped content is preloaded. - -In order for data to be preloaded, [property@TabBar:extra-drag-preload] -must be set to `TRUE`. - -The content must be of one of the types set up via -[method@TabBar.setup_extra_drop_target]. + filename="src/adw-tab-view.c" + line="4188">Inserts a pinned page at @position. -See [property@Gtk.DropTarget:value]. +It's an error to try to insert a pinned page after a non-pinned page, in +that case [method@TabView.insert] should be used instead. + the preferred action for the drop on @page - + filename="src/adw-tab-view.c" + line="4199">the page object representing @child + - + the page matching the tab the content was dropped onto - + filename="src/adw-tab-view.c" + line="4190">a tab view + + + + a widget to add + - + the `GValue` being dropped - + filename="src/adw-tab-view.c" + line="4192">the position to add @child at, starting from 0 + - - - - - - - - - - A button that displays the number of [class@TabView] pages. - -<picture> - <source srcset="tab-button-dark.png" media="(prefers-color-scheme: dark)"> - <img src="tab-button.png" alt="tab-button"> -</picture> - -`AdwTabButton` is a button that displays the number of pages in a given -`AdwTabView`, as well as whether one of the inactive pages needs attention. - -It's intended to be used as a visible indicator when there's no visible tab -bar, typically opening an [class@TabOverview] on click, e.g. via the -`overview.open` action name: - -```xml -<object class="AdwTabButton"> - <property name="view">view</property> - <property name="action-name">overview.open</property> -</object> -``` - -## CSS nodes - -`AdwTabButton` has a main CSS node with name `tabbutton`. - -# Accessibility - -`AdwTabButton` uses the `GTK_ACCESSIBLE_ROLE_BUTTON` role. - - - - - - - Creates a new `AdwTabButton`. - - - the newly created `AdwTabButton` - - - - + - Gets the tab view @self displays. - - - the tab view - + filename="src/adw-tab-view.c" + line="4685">Invalidates thumbnails for all pages in @self. + +This is a convenience method, equivalent to calling +[method@TabPage.invalidate_thumbnail] on each page. + + + a tab button - + filename="src/adw-tab-view.c" + line="4687">a tab view + - - + Sets the tab view to display. - + filename="src/adw-tab-view.c" + line="4148">Inserts @child as the first non-pinned page. + - + the page object representing @child + a tab button - + filename="src/adw-tab-view.c" + line="4150">a tab view + - + a tab view - + filename="src/adw-tab-view.c" + line="4151">a widget to add + - - - - The view the tab button displays. - - - - Emitted to animate press then release. - -This is an action signal. Applications should never connect to this signal, -but use the [signal@TabButton::clicked] signal. - - - - - - Emitted when the button has been activated (pressed and released). - - - - - - - - - - - - - A tab overview for [class@TabView]. - -<picture> - <source srcset="tab-overview-dark.png" media="(prefers-color-scheme: dark)"> - <img src="tab-overview.png" alt="tab-overview"> -</picture> - -`AdwTabOverview` is a widget that can display tabs from an `AdwTabView` in a -grid. - -`AdwTabOverview` shows a thumbnail for each tab. By default thumbnails are -static for all pages except the selected one. They can be made always live -by setting [property@TabPage:live-thumbnail] to `TRUE`, or refreshed with -[method@TabPage.invalidate_thumbnail] or -[method@TabView.invalidate_thumbnails] otherwise. - -If the pages are too tall or too wide, the thumbnails will be cropped; use -[property@TabPage:thumbnail-xalign] and [property@TabPage:thumbnail-yalign] to -control which part of the page should be visible in this case. - -Pinned tabs are shown as smaller cards without thumbnails above the other -tabs. Unlike in [class@TabBar], they still have titles, as well as an unpin -button. - -`AdwTabOverview` provides search in open tabs. It searches in tab titles and -tooltips, as well as [property@TabPage:keyword]. - -If [property@TabOverview:enable-new-tab] is set to `TRUE`, a new tab button -will be shown. Connect to the [signal@TabOverview::create-tab] signal to use -it. - -[property@TabOverview:secondary-menu] can be used to provide a secondary menu -for the overview. Use it to add extra actions, e.g. to open a new window or -undo closed tab. - -`AdwTabOverview` is intended to be used as the direct child of the window, -with the rest of the window contents set as the [property@TabOverview:child]. -The child is expected to contain an [class@TabView]. - -`AdwTabOverview` shows window buttons by default. They can be disabled by -setting [property@TabOverview:show-start-title-buttons] and/or -[property@TabOverview:show-start-title-buttons] and/or -[property@TabOverview:show-end-title-buttons] to `FALSE`. - -If search and window buttons are disabled, and secondary menu is not set, the -header bar will be hidden. - -## Actions - -`AdwTabOverview` defines the `overview.open` and `overview.close` actions for -opening and closing itself. They can be convenient when used together with -[class@TabButton]. - -## CSS nodes - -`AdwTabOverview` has a single CSS node with name `taboverview`. - - - - - - Creates a new `AdwTabOverview`. - + + Inserts @child as the first pinned page. + the newly created `AdwTabOverview` - + filename="src/adw-tab-view.c" + line="4221">the page object representing @child + - - - + + + a tab view + + + + a widget to add + + + + + Gets the child widget of @self. - - - the child widget of @self - + filename="src/adw-tab-view.c" + line="3885">Removes @shortcuts from @self. + +See [property@TabView:shortcuts] for details. + + + a `AdwTabOveview` - + filename="src/adw-tab-view.c" + line="3887">a tab view + + + the shortcuts to remove + + - - + Gets whether to new tab button is enabled for @self. - + filename="src/adw-tab-view.c" + line="4470">Reorders @page to before its previous page if possible. + whether new tab button is enabled + filename="src/adw-tab-view.c" + line="4477">whether @page was moved a tab overview - + filename="src/adw-tab-view.c" + line="4472">a tab view + + + a page of @self + + - - + Gets whether search in tabs is enabled for @self. - + filename="src/adw-tab-view.c" + line="4532">Reorders @page to the first possible position. + whether search is enabled + filename="src/adw-tab-view.c" + line="4539">whether @page was moved a tab overview - + filename="src/adw-tab-view.c" + line="4534">a tab view + + + a page of @self + + - + Gets the current action during a drop on the extra_drop_target. - + filename="src/adw-tab-view.c" + line="4501">Reorders @page to after its next page if possible. + the drag action of the current drop. - + filename="src/adw-tab-view.c" + line="4508">whether @page was moved + a tab overview - + filename="src/adw-tab-view.c" + line="4503">a tab view + + + a page of @self + + - - + Gets whether drop data should be preloaded on hover. - + filename="src/adw-tab-view.c" + line="4558">Reorders @page to the last possible position. + whether drop data should be preloaded on hover + filename="src/adw-tab-view.c" + line="4565">whether @page was moved a tab overview - + filename="src/adw-tab-view.c" + line="4560">a tab view + + + a page of @self + + - - + Gets whether thumbnails use inverted layout. - + filename="src/adw-tab-view.c" + line="4414">Reorders @page to @position. + +It's a programmer error to try to reorder a pinned page after a non-pinned +one, or a non-pinned page before a pinned one. + whether thumbnails use inverted layout + filename="src/adw-tab-view.c" + line="4425">whether @page was moved a tab overview - + filename="src/adw-tab-view.c" + line="4416">a tab view + + + a page of @self + + + + the position to insert the page at, starting at 0 + + - - + Gets whether @self is open. - + filename="src/adw-tab-view.c" + line="3626">Selects the page after the currently selected page. + +If the last page was already selected, this function does nothing. + whether the overview is open + filename="src/adw-tab-view.c" + line="3634">whether the selected page was changed a tab overview - + filename="src/adw-tab-view.c" + line="3628">a tab view + - - + Gets whether search is currently active for @self. + filename="src/adw-tab-view.c" + line="3593">Selects the page before the currently selected page. -See [property@TabOverview:enable-search]. - +If the first page was already selected, this function does nothing. + whether search is active + filename="src/adw-tab-view.c" + line="3601">whether the selected page was changed a tab overview - + filename="src/adw-tab-view.c" + line="3595">a tab view + - - + Gets the secondary menu model for @self. - - - the secondary menu model - + filename="src/adw-tab-view.c" + line="3733">Sets the default page icon for @self. + +If a page doesn't provide its own icon via [property@TabPage:icon], a default +icon may be used instead for contexts where having an icon is necessary. + +[class@TabBar] will use default icon for pinned tabs in case the page is not +loading, doesn't have an icon and an indicator. Default icon is never used +for tabs that aren't pinned. + +[class@TabOverview] will use default icon for pages with missing thumbnails. + +By default, the `adw-tab-icon-missing-symbolic` icon is used. + + + a tab overview - + filename="src/adw-tab-view.c" + line="3735">a tab view + + + the default icon + + - - + Gets whether end title buttons are shown in @self's header bar. - + filename="src/adw-tab-view.c" + line="3790">Sets the tab context menu model for @self. + +When a context menu is shown for a tab, it will be constructed from the +provided menu model. Use the [signal@TabView::setup-menu] signal to set up +the menu actions for the particular tab. + - whether end title buttons are shown - + a tab overview - + filename="src/adw-tab-view.c" + line="3792">a tab view + + + a menu model + + - - + + Pins or unpins @page. + +Pinned pages are guaranteed to be placed before all non-pinned pages; at any +given moment the first [property@TabView:n-pinned-pages] pages in @self are +guaranteed to be pinned. + +When a page is pinned or unpinned, it's automatically reordered: pinning a +page moves it after other pinned pages; unpinning a page moves it before +other non-pinned pages. + +Pinned pages can still be reordered between each other. + +[class@TabBar] will display pinned pages in a compact form, never showing the +title or close button, and only showing a single icon, selected in the +following order: + +1. [property@TabPage:indicator-icon] +2. A spinner if [property@TabPage:loading] is `TRUE` +3. [property@TabPage:icon] +4. [property@TabView:default-icon] + +[class@TabOverview] will not show a thumbnail for pinned pages, and replace +the close button with an unpin button. Unlike `AdwTabBar`, it will still +display the page's title, icon and indicator separately. + +Pinned pages cannot be closed by default, see [signal@TabView::close-page] +for how to override that behavior. + +Changes the value of the [property@TabPage:pinned] property. + + + + + + + a tab view + + + + a page of @self + + + + whether @page should be pinned + + + + + + Sets the currently selected page in @self. + + + + + + + a tab view + + + + a page in @self + + + + + + Sets the enabled shortcuts for @self. + +See [flags@TabViewShortcuts] for the list of the available shortcuts. All of +the shortcuts are enabled by default. + +[method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] provide +a convenient way to manage individual shortcuts. + + + + + + + a tab view + + + + the new shortcuts + + + + + + Transfers @page from @self to @other_view. + +The @page object will be reused. + +It's a programmer error to try to insert a pinned page after a non-pinned +one, or a non-pinned page before a pinned one. + + + + + + + a tab view + + + + a page of @self + + + + the tab view to transfer the page to + + + + the position to insert the page at, starting at 0 + + + + + + Default page icon. + +If a page doesn't provide its own icon via [property@TabPage:icon], a +default icon may be used instead for contexts where having an icon is +necessary. + +[class@TabBar] will use default icon for pinned tabs in case the page is +not loading, doesn't have an icon and an indicator. Default icon is never +used for tabs that aren't pinned. + +[class@TabOverview] will use default icon for pages with missing +thumbnails. + +By default, the `adw-tab-icon-missing-symbolic` icon is used. + + + + Whether a page is being transferred. + +This property will be set to `TRUE` when a drag-n-drop tab transfer starts +on any `AdwTabView`, and to `FALSE` after it ends. + +During the transfer, children cannot receive pointer input and a tab can +be safely dropped on the tab view. + + + + Tab context menu model. + +When a context menu is shown for a tab, it will be constructed from the +provided menu model. Use the [signal@TabView::setup-menu] signal to set up +the menu actions for the particular tab. + + + + The number of pages in the tab view. + + + + The number of pinned pages in the tab view. + +See [method@TabView.set_page_pinned]. + + + + A selection model with the tab view's pages. + +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the selected +page. + + + + The currently selected page. + + + + The enabled shortcuts. + +See [flags@TabViewShortcuts] for the list of the available shortcuts. All +of the shortcuts are enabled by default. + +[method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] +provide a convenient way to manage individual shortcuts. + + + Gets whether start title buttons are shown in @self's header bar. - + filename="src/adw-tab-view.c" + line="2614">Emitted after [method@TabView.close_page] has been called for @page. + +The handler is expected to call [method@TabView.close_page_finish] to +confirm or reject the closing. + +The default handler will immediately confirm closing for non-pinned pages, +or reject it for pinned pages, equivalent to the following example: + +```c +static gboolean +close_page_cb (AdwTabView *view, + AdwTabPage *page, + gpointer user_data) +{ + adw_tab_view_close_page_finish (view, page, !adw_tab_page_get_pinned (page)); + + return GDK_EVENT_STOP; +} +``` + +The [method@TabView.close_page_finish] call doesn't have to happen inside +the handler, so can be used to do asynchronous checks before confirming the +closing. + +A typical reason to connect to this signal is to show a confirmation dialog +for closing a tab. + +The signal handler should return `GDK_EVENT_STOP` to stop propagation or +`GDK_EVENT_CONTINUE` to invoke the default handler. whether start title buttons are shown + filename="src/adw-tab-view.c" + line="2649">whether propagation should be stopped - + a tab overview - - + filename="src/adw-tab-view.c" + line="2617">a page of @self + + - - - + + Gets the tab view @self controls. - + filename="src/adw-tab-view.c" + line="2692">Emitted when a tab should be transferred into a new window. + +This can happen after a tab has been dropped on desktop. + +The signal handler is expected to create a new window, position it as +needed and return its `AdwTabView` that the page will be transferred into. the tab view - + filename="src/adw-tab-view.c" + line="2703">the `AdwTabView` from the new window + - - - a tab overview - - - - - - + + Sets the child widget of @self. - + filename="src/adw-tab-view.c" + line="2719">Emitted after the indicator icon on @page has been activated. + +See [property@TabPage:indicator-icon] and +[property@TabPage:indicator-activatable]. - - a tab overview - - - + the child widget - + filename="src/adw-tab-view.c" + line="2722">a page of @self + - - - + + Sets whether to enable new tab button for @self. + filename="src/adw-tab-view.c" + line="2537">Emitted when a page has been created or transferred to @self. -Connect to the [signal@TabOverview::create-tab] signal to use it. - +A typical reason to connect to this signal would be to connect to page +signals for things such as updating window title. - + a tab overview - - - + filename="src/adw-tab-view.c" + line="2540">a page of @self + + + whether to enable new tab button - + filename="src/adw-tab-view.c" + line="2541">the position of the page, starting from 0 + - - - + + Sets whether to enable search in tabs for @self. - -Search matches tab titles and tooltips, as well as keywords, set via -[property@TabPage:keyword]. Use keywords to search in e.g. page URLs in a web -browser. + filename="src/adw-tab-view.c" + line="2562">Emitted when a page has been removed or transferred to another view. -During search, tab reordering and drag-n-drop are disabled. +A typical reason to connect to this signal would be to disconnect signal +handlers connected in the [signal@TabView::page-attached] handler. -Use [property@TabOverview:search-active] to check out if search is currently -active. - +It is important not to try and destroy the page child in the handler of +this function as the child might merely be moved to another window; use +child dispose handler for that or do it in sync with your +[method@TabView.close_page_finish] calls. - - a tab overview - - - + whether to enable search - + filename="src/adw-tab-view.c" + line="2565">a page of @self + - - - - - Sets whether drop data should be preloaded on hover. - -See [property@Gtk.DropTarget:preload]. - - - - - - - a tab overview - - - + whether to preload drop data - + filename="src/adw-tab-view.c" + line="2566">the position of the removed page, starting from 0 + - - - + + Sets whether thumbnails use inverted layout. - -If set to `TRUE`, thumbnails will have the close or unpin button at the -beginning and the indicator at the end rather than the other way around. - + filename="src/adw-tab-view.c" + line="2592">Emitted after @page has been reordered to @position. - - a tab overview - - - + whether thumbnails use inverted layout - + filename="src/adw-tab-view.c" + line="2595">a page of @self + - - - - - Sets whether the to open @self. - - - - - - - a tab overview - - - + whether the overview is open - + filename="src/adw-tab-view.c" + line="2596">the position @page was moved to, starting at 0 + - - - + + Sets the secondary menu model for @self. + filename="src/adw-tab-view.c" + line="2666">Emitted when a context menu is opened or closed for @page. -Use it to add extra actions, e.g. to open a new window or undo closed tab. - +If the menu has been closed, @page will be set to `NULL`. + +It can be used to set up menu actions before showing the menu, for example +disable actions not applicable to @page. - - a tab overview - - - a menu model - + filename="src/adw-tab-view.c" + line="2669">a page of @self + - - - + + + + + + + + + + Describes available shortcuts in an [class@TabView]. + +Shortcuts can be set with [property@TabView:shortcuts], or added/removed +individually with [method@TabView.add_shortcuts] and +[method@TabView.remove_shortcuts]. + +New values may be added to this enumeration over time. + Sets whether to show end title buttons in @self's header bar. + filename="src/adw-tab-view.c" + line="85">No shortcuts + + + <kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the next page + + + <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the previous + page + + + <kbd>Ctrl</kbd>+<kbd>Page Up</kbd> - switch to the previous page + + + <kbd>Ctrl</kbd>+<kbd>Page Down</kbd> - switch to the next page + + + <kbd>Ctrl</kbd>+<kbd>Home</kbd> - switch to the first page + + + <kbd>Ctrl</kbd>+<kbd>End</kbd> - switch to the last page + + + <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Up</kbd> - move the selected + page backward + + + <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Down</kbd> - move the selected + page forward + + + <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Home</kbd> - move the selected page + at the start + + + <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>End</kbd> - move the current page at + the end + + + <kbd>Alt</kbd>+<kbd>1</kbd>⋯<kbd>9</kbd> - switch to pages 1-9 + + + <kbd>Alt</kbd>+<kbd>0</kbd> - switch to page 10 + + + All of the shortcuts + + + + A time-based [class@Animation]. -See [property@HeaderBar:show-start-title-buttons] for the other side. - +`AdwTimedAnimation` implements a simple animation interpolating the given +value from [property@TimedAnimation:value-from] to +[property@TimedAnimation:value-to] over +[property@TimedAnimation:duration] milliseconds using the curve described by +[property@TimedAnimation:easing]. + +If [property@TimedAnimation:reverse] is set to `TRUE`, `AdwTimedAnimation` +will instead animate from [property@TimedAnimation:value-to] to +[property@TimedAnimation:value-from], and the easing curve will be inverted. + +The animation can repeat a certain amount of times, or endlessly, depending +on the [property@TimedAnimation:repeat-count] value. If +[property@TimedAnimation:alternate] is set to `TRUE`, it will also change the +direction every other iteration. + + + Creates a new `AdwTimedAnimation` on @widget to animate @target from @from +to @to. + - + the newly created animation + - + a tab overview - - - + filename="src/adw-timed-animation.c" + line="322">a widget to create animation on + + + whether to show end title buttons - + filename="src/adw-timed-animation.c" + line="323">a value to animate from + - - - - - Sets whether to show start title buttons in @self's header bar. - -See [property@HeaderBar:show-end-title-buttons] for the other side. - - - - - - + a tab overview - - - + filename="src/adw-timed-animation.c" + line="324">a value to animate to + + + whether to show start title buttons - + filename="src/adw-timed-animation.c" + line="325">a duration for the animation + + + + a target value to animate + - - - + + Sets the tab view to control. - -The view must be inside @self, see [property@TabOverview:child]. - + filename="src/adw-timed-animation.c" + line="600">Gets whether @self changes direction on every iteration. + - + whether @self alternates + a tab overview - + filename="src/adw-timed-animation.c" + line="602">a timed animation + - - a tab view - - - + Sets the supported types for this drop target. - -Sets up an extra drop target on tabs. - -This allows to drag arbitrary content onto tabs, for example URLs in a web -browser. - -If a tab is hovered for a certain period of time while dragging the content, -it will be automatically selected. - -The [signal@TabOverview::extra-drag-drop] signal can be used to handle the -drop. - + filename="src/adw-timed-animation.c" + line="444">Gets the duration of @self. + - + the duration of @self, in milliseconds + a tab overview - + filename="src/adw-timed-animation.c" + line="446">a timed animation + - - the supported actions - - - - - all supported `GType`s that can be dropped - - - - - - number of @types - - - - - - The child widget. - - - - - - Whether to enable new tab button. - -Connect to the [signal@TabOverview::create-tab] signal to use it. - - - - - - Whether to enable search in tabs. - -Search matches tab titles and tooltips, as well as keywords, set via -[property@TabPage:keyword]. Use keywords to search in e.g. page URLs in a -web browser. - -During search, tab reordering and drag-n-drop are disabled. - -Use [property@TabOverview:search-active] to check out if search is -currently active. - - - - - The unique action on the `current-drop` of the -[signal@TabOverview::extra-drag-drop]. - -This property should only be used during a -[signal@TabOverview::extra-drag-drop] and is always a subset of what was -originally passed to [method@TabOverview.setup_extra_drop_target]. - - - - - - Whether the drop data should be preloaded on hover. - -See [property@Gtk.DropTarget:preload]. - - - - - - Whether thumbnails use inverted layout. - -If set to `TRUE`, thumbnails will have the close or unpin buttons at the -beginning and the indicator at the end rather than the other way around. - - - - - - Whether the overview is open. - - - - - Whether search is currently active. - -See [property@TabOverview:enable-search]. - - - - - - The secondary menu model. - -Use it to add extra actions, e.g. to open a new window or undo closed tab. - - - - - - Whether to show end title buttons in the overview's header bar. - -See [property@HeaderBar:show-start-title-buttons] for the other side. - - - - - - Whether to show start title buttons in the overview's header bar. - -See [property@HeaderBar:show-end-title-buttons] for the other side. - - - - - - The tab view the overview controls. - -The view must be inside the tab overview, see [property@TabOverview:child]. - - - + Emitted when a tab needs to be created; - -This can happen after the new tab button has been pressed, see -[property@TabOverview:enable-new-tab]. - -The signal handler is expected to create a new page in the corresponding -[class@TabView] and return it. + filename="src/adw-timed-animation.c" + line="483">Gets the easing function @self uses. + the newly created page - + filename="src/adw-timed-animation.c" + line="489">the easing function @self uses + - - + + + a timed animation + + + + + This signal is emitted when content is dropped onto a tab. - -The content must be of one of the types set up via -[method@TabOverview.setup_extra_drop_target]. - -See [signal@Gtk.DropTarget::drop]. + filename="src/adw-timed-animation.c" + line="524">Gets the number of times @self will play. + whether the drop was accepted for @page - + filename="src/adw-timed-animation.c" + line="530">the number of times @self will play + - - the page matching the tab the content was dropped onto - - - + the `GValue` being dropped - - + filename="src/adw-timed-animation.c" + line="526">a timed animation + + - - + + This signal is emitted when the dropped content is preloaded. - -In order for data to be preloaded, [property@TabOverview:extra-drag-preload] -must be set to `TRUE`. - -The content must be of one of the types set up via -[method@TabOverview.setup_extra_drop_target]. - -See [property@Gtk.DropTarget:value]. + filename="src/adw-timed-animation.c" + line="563">Gets whether @self plays backwards. + the preferred action for the drop on @page - + filename="src/adw-timed-animation.c" + line="569">whether @self plays backwards + - - the page matching the tab the content was dropped onto - - - + the `GValue` being dropped - - + filename="src/adw-timed-animation.c" + line="565">a timed animation + + - - - - - - - - - - An auxiliary class used by [class@TabView]. - - - - + + Gets the child of @self. - + filename="src/adw-timed-animation.c" + line="358">Gets the value @self will animate from. + the child of @self - + filename="src/adw-timed-animation.c" + line="364">the value to animate from + a tab page - + filename="src/adw-timed-animation.c" + line="360">a timed animation + - - + Gets the icon of @self. - - + filename="src/adw-timed-animation.c" + line="401">Gets the value @self will animate to. + + the icon of @self - + filename="src/adw-timed-animation.c" + line="407">the value to animate to + a tab page - + filename="src/adw-timed-animation.c" + line="403">a timed animation + - - + Gets whether the indicator of @self is activatable. - + filename="src/adw-timed-animation.c" + line="616">Sets whether @self changes direction on every iteration. + - whether the indicator is activatable - + a tab page - + filename="src/adw-timed-animation.c" + line="618">a timed animation + + + whether @self alternates + + - - + Gets the indicator icon of @self. - - - the indicator icon of @self - + filename="src/adw-timed-animation.c" + line="460">Sets the duration of @self. + +If the animation repeats more than once, sets the duration of one iteration. + + + a tab page - + filename="src/adw-timed-animation.c" + line="462">a timed animation + + + the duration to use, in milliseconds + + - - + Gets the tooltip of the indicator icon of @self. - + filename="src/adw-timed-animation.c" + line="500">Sets the easing function @self will use. + +See [enum@Easing] for the description of specific easing functions. + - the indicator tooltip of @self - + a tab page - + filename="src/adw-timed-animation.c" + line="502">a timed animation + + + the easing function to use + + - - + Gets the search keyword of @self. - - - the search keyword of @self - + filename="src/adw-timed-animation.c" + line="540">Sets the number of times @self will play. + +If set to 0, @self will repeat endlessly. + + + a tab page - + filename="src/adw-timed-animation.c" + line="542">a timed animation + + + the number of times @self will play + + - - + Gets whether to live thumbnail is enabled @self. - + filename="src/adw-timed-animation.c" + line="579">Sets whether @self plays backwards. + - whether live thumbnail is enabled - + a tab overview - + filename="src/adw-timed-animation.c" + line="581">a timed animation + + + whether @self plays backwards + + - - + Gets whether @self is loading. - + filename="src/adw-timed-animation.c" + line="374">Sets the value @self will animate from. + +The animation will start at this value and end at +[property@TimedAnimation:value-to]. + +If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at +this value instead. + - whether @self is loading - + a tab page - + filename="src/adw-timed-animation.c" + line="376">a timed animation + + + the value to animate from + + - - + Gets whether @self needs attention. - + filename="src/adw-timed-animation.c" + line="417">Sets the value @self will animate to. + +The animation will start at [property@TimedAnimation:value-from] and end at +this value. + +If [property@TimedAnimation:reverse] is `TRUE`, the animation will start +at this value instead. + - whether @self needs attention - + a tab page - + filename="src/adw-timed-animation.c" + line="419">a timed animation + + + the value to animate to + + - - + Gets the parent page of @self. + filename="src/adw-timed-animation.c" + line="302">Whether the animation changes direction on every iteration. + + + + Duration of the animation, in milliseconds. -See [method@TabView.add_page] and [method@TabView.close_page]. - - +Describes how much time the animation will take. + +If the animation repeats more than once, describes the duration of one +iteration. + + + + Easing function used in the animation. + +Describes the curve the value is interpolated on. + +See [enum@Easing] for the description of specific easing functions. + + + + Number of times the animation will play. + +If set to 0, the animation will repeat endlessly. + + + + Whether the animation plays backwards. + + + + The value to animate from. + +The animation will start at this value and end at +[property@TimedAnimation:value-to]. + +If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at +this value instead. + + + + The value to animate to. + +The animation will start at [property@TimedAnimation:value-from] and end at +this value. + +If [property@TimedAnimation:reverse] is `TRUE`, the animation will start +at this value instead. + + + + + + + + A helper object for [class@ToastOverlay]. + +Toasts are meant to be passed into [method@ToastOverlay.add_toast] as +follows: + +```c +adw_toast_overlay_add_toast (overlay, adw_toast_new (_("Simple Toast"))); +``` + +<picture> + <source srcset="toast-simple-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toast-simple.png" alt="toast-simple"> +</picture> + +Toasts always have a close button. They emit the [signal@Toast::dismissed] +signal when disappearing. + +[property@Toast:timeout] determines how long the toast stays on screen, while +[property@Toast:priority] determines how it behaves if another toast is +already being displayed. + +Toast titles use Pango markup by default, set [property@Toast:use-markup] to +`FALSE` if this is unwanted. + +[property@Toast:custom-title] can be used to replace the title label with a +custom widget. + +## Actions + +Toasts can have one button on them, with a label and an attached +[iface@Gio.Action]. + +```c +AdwToast *toast = adw_toast_new (_("Toast with Action")); + +adw_toast_set_button_label (toast, _("_Example")); +adw_toast_set_action_name (toast, "win.example"); + +adw_toast_overlay_add_toast (overlay, toast); +``` + +<picture> + <source srcset="toast-action-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toast-action.png" alt="toast-action"> +</picture> + +## Modifying toasts + +Toasts can be modified after they have been shown. For this, an `AdwToast` +reference must be kept around while the toast is visible. + +A common use case for this is using toasts as undo prompts that stack with +each other, allowing to batch undo the last deleted items: + +```c + +static void +toast_undo_cb (GtkWidget *sender, + const char *action, + GVariant *param) +{ + // Undo the deletion +} + +static void +dismissed_cb (MyWindow *self) +{ + self->undo_toast = NULL; + + // Permanently delete the items +} + +static void +delete_item (MyWindow *self, + MyItem *item) +{ + g_autofree char *title = NULL; + int n_items; + + // Mark the item as waiting for deletion + n_items = ... // The number of waiting items + + if (!self->undo_toast) { + self->undo_toast = adw_toast_new_format (_("‘%s’ deleted"), ...); + + adw_toast_set_priority (self->undo_toast, ADW_TOAST_PRIORITY_HIGH); + adw_toast_set_button_label (self->undo_toast, _("_Undo")); + adw_toast_set_action_name (self->undo_toast, "toast.undo"); + + g_signal_connect_swapped (self->undo_toast, "dismissed", + G_CALLBACK (dismissed_cb), self); + + adw_toast_overlay_add_toast (self->toast_overlay, self->undo_toast); + + return; + } + + title = + g_strdup_printf (ngettext ("<span font_features='tnum=1'>%d</span> item deleted", + "<span font_features='tnum=1'>%d</span> items deleted", + n_items), n_items); + + adw_toast_set_title (self->undo_toast, title); + + // Bump the toast timeout + adw_toast_overlay_add_toast (self->toast_overlay, g_object_ref (self->undo_toast)); +} + +static void +my_window_class_init (MyWindowClass *klass) +{ + GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass); + + gtk_widget_class_install_action (widget_class, "toast.undo", NULL, toast_undo_cb); +} +``` + +<picture> + <source srcset="toast-undo-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toast-undo.png" alt="toast-undo"> +</picture> + + + Creates a new `AdwToast`. + +The toast will use @title as its title. + +@title can be marked up with the Pango text markup language. + + the parent page - + filename="src/adw-toast.c" + line="491">the new created `AdwToast` + - + a tab page - - + filename="src/adw-toast.c" + line="483">the title to be displayed + + - - - + + Gets whether @self is pinned. + filename="src/adw-toast.c" + line="503">Creates a new `AdwToast`. -See [method@TabView.set_page_pinned]. - - +The toast will use the format string as its title. + +See also: [ctor@Toast.new] + + whether @self is pinned - + filename="src/adw-toast.c" + line="514">the newly created toast object + - + a tab page - - + filename="src/adw-toast.c" + line="505">the formatted string for the toast title + + + + the parameters to insert into the format string + + - - - + + Gets whether @self is selected. - + filename="src/adw-toast.c" + line="936">Dismisses @self. + +Does nothing if @self has already been dismissed, or hasn't been added to an +[class@ToastOverlay]. + - whether @self is selected - + a tab page - + filename="src/adw-toast.c" + line="938">a toast + - - + Gets the horizontal alignment of the thumbnail for @self. - - + filename="src/adw-toast.c" + line="636">Gets the name of the associated action. + + the horizontal alignment - + filename="src/adw-toast.c" + line="642">the action name + a tab page - + filename="src/adw-toast.c" + line="638">a toast + - - + Gets the vertical alignment of the thumbnail for @self. - - + filename="src/adw-toast.c" + line="675">Gets the parameter for action invocations. + + the vertical alignment - + filename="src/adw-toast.c" + line="681">the action target + a tab overview - + filename="src/adw-toast.c" + line="677">a toast + - - + Gets the title of @self. - - + filename="src/adw-toast.c" + line="595">Gets the label to show on the button. + + the title of @self + filename="src/adw-toast.c" + line="601">the button label a tab page - + filename="src/adw-toast.c" + line="597">a toast + - - + Gets the tooltip of @self. - + filename="src/adw-toast.c" + line="880">Gets the custom title widget of @self. + the tooltip of @self - + filename="src/adw-toast.c" + line="886">the custom title widget + a tab page - + filename="src/adw-toast.c" + line="882">a toast + - + Invalidates thumbnail for @self. - -If an [class@TabOverview] is open, the thumbnail representing @self will be -immediately updated. Otherwise it will be update when opening the overview. - -Does nothing if [property@TabPage:live-thumbnail] is set to `TRUE`. - -See also [method@TabView.invalidate_thumbnails]. - + filename="src/adw-toast.c" + line="790">Gets priority for @self. + - + the priority + a tab page - + filename="src/adw-toast.c" + line="792">a toast + - - + Sets the icon of @self. - -[class@TabBar] and [class@TabOverview] display the icon next to the title, -unless [property@TabPage:loading] is set to `TRUE`. - -`AdwTabBar` also won't show the icon if the page is pinned and -[propertyTabPage:indicator-icon] is set. - + filename="src/adw-toast.c" + line="837">Gets timeout for @self. + - + the timeout + a tab page - + filename="src/adw-toast.c" + line="839">a toast + - - the icon of @self - - - - + Sets whether the indicator of @self is activatable. - -If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted -when the indicator icon is clicked. + filename="src/adw-toast.c" + line="539">Gets the title that will be displayed on the toast. -If [property@TabPage:indicator-icon] is not set, does nothing. - - - +If a custom title has been set with [method@Adw.Toast.set_custom_title] +the return value will be %NULL. + + + the title + a tab page - + filename="src/adw-toast.c" + line="541">a toast + - - whether the indicator is activatable - - - - + Sets the indicator icon of @self. - -A common use case is an audio or camera indicator in a web browser. - -[class@TabBar] will show it at the beginning of the tab, alongside icon -representing [property@TabPage:icon] or loading spinner. - -If the page is pinned, the indicator will be shown instead of icon or -spinner. - -[class@TabOverview] will show it at the at the top part of the thumbnail. - -[property@TabPage:indicator-tooltip] can be used to set the tooltip on the -indicator icon. - -If [property@TabPage:indicator-activatable] is set to `TRUE`, the -indicator icon can act as a button. - + filename="src/adw-toast.c" + line="974">Gets whether to use Pango markup for the toast title. + - + whether the toast uses markup + a tab page - + filename="src/adw-toast.c" + line="976">a toast + - - the indicator icon of @self - - - - + Sets the tooltip of the indicator icon of @self. + filename="src/adw-toast.c" + line="652">Sets the name of the associated action. -The tooltip can be marked up with the Pango text markup language. +It will be activated when clicking the button. -See [property@TabPage:indicator-icon]. - +See [property@Toast:action-target]. + a tab page - + filename="src/adw-toast.c" + line="654">a toast + - + the indicator tooltip of @self + filename="src/adw-toast.c" + line="655">the action name - - + Sets the search keyword for @self. + filename="src/adw-toast.c" + line="721">Sets the parameter for action invocations. -[class@TabOverview] can search pages by their keywords in addition to their -titles and tooltips. +This is a convenience function that calls [ctor@GLib.Variant.new] for +@format_string and uses the result to call +[method@Toast.set_action_target_value]. -Keywords allow to include e.g. page URLs into tab search in a web browser. - +If you are setting a string-valued target and want to set +the action name at the same time, you can use +[method@Toast.set_detailed_action_name]. + a tab page - + filename="src/adw-toast.c" + line="723">a toast + - + the search keyword + filename="src/adw-toast.c" + line="724">a variant format string - - - - - Sets whether to enable live thumbnail for @self. - -When set to `TRUE`, @self's thumbnail in [class@TabOverview] will update -immediately when @self is redrawn or resized. - -If it's set to `FALSE`, the thumbnail will only be live when the @self is -selected, and otherwise it will be static and will only update when -[method@TabPage.invalidate_thumbnail] or -[method@TabView.invalidate_thumbnails] is called. - - - - - - - a tab page - - - + whether to enable live thumbnail - + filename="src/adw-toast.c" + line="725">arguments appropriate for @target_format + - - + Sets whether @self is loading. - -If set to `TRUE`, [class@TabBar] and [class@TabOverview] will display a -spinner in place of icon. + filename="src/adw-toast.c" + line="691">Sets the parameter for action invocations. -If the page is pinned and [property@TabPage:indicator-icon] is set, loading -status will not be visible with `AdwTabBar`. - +If the @action_target variant has a floating reference this function +will sink it. + a tab page - + filename="src/adw-toast.c" + line="693">a toast + - + whether @self is loading - + filename="src/adw-toast.c" + line="694">the action target + - - + Sets whether @self needs attention. + filename="src/adw-toast.c" + line="611">Sets the label to show on the button. -[class@TabBar] will display a line under the tab representing the page if -set to `TRUE`. If the tab is not visible, the corresponding edge of the tab -bar will be highlighted. +Underlines in the button text can be used to indicate a mnemonic. -[class@TabOverview] will display a dot in the corner of the thumbnail if set -to `TRUE`. +If set to `NULL`, the button won't be shown. -[class@TabButton] will display a dot if any of the pages that aren't -selected have [property@TabPage:needs-attention] set to `TRUE`. - +See [property@Toast:action-name]. + a tab page - + filename="src/adw-toast.c" + line="613">a toast + - + whether @self needs attention - + filename="src/adw-toast.c" + line="614">a button label + - - + Sets the horizontal alignment of the thumbnail for @self. - -If the page is so wide that [class@TabOverview] can't display it completely -and has to crop it, horizontal alignment will determine which part of the -page will be visible. + filename="src/adw-toast.c" + line="898">Sets the custom title widget of @self. -For example, 0.5 means the center of the page will be visible, 0 means the -start edge will be visible and 1 means the end edge will be visible. +It will be displayed instead of the title if set. In this case, +[property@Toast:title] is ignored. -The default horizontal alignment is 0. - +Setting a custom title will unset [property@Toast:title]. + a tab page - + filename="src/adw-toast.c" + line="900">a toast + - + the new value - + filename="src/adw-toast.c" + line="901">the custom title widget + - - + Sets the vertical alignment of the thumbnail for @self. - -If the page is so tall that [class@TabOverview] can't display it completely -and has to crop it, vertical alignment will determine which part of the page -will be visible. - -For example, 0.5 means the center of the page will be visible, 0 means the -top edge will be visible and 1 means the bottom edge will be visible. + filename="src/adw-toast.c" + line="751">Sets the action name and its parameter. -The default vertical alignment is 0. - +@detailed_action_name is a string in the format accepted by +[func@Gio.Action.parse_detailed_name]. + a tab page - + filename="src/adw-toast.c" + line="753">a toast + - + the new value - + filename="src/adw-toast.c" + line="754">the detailed action name + - - + [class@TabBar] will display it in the center of the tab unless it's pinned, -and will use it as a tooltip unless [property@TabPage:tooltip] is set. + filename="src/adw-toast.c" + line="806">Sets priority for @self. -[class@TabOverview] will display it below the thumbnail unless it's pinned, -or inside the card otherwise, and will use it as a tooltip unless -[property@TabPage:tooltip] is set. +Priority controls how the toast behaves when another toast is already +being displayed. -Sets the title of @self. - +If @priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued. + +If @priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed +immediately, pushing the previous toast into the queue instead. + a tab page - + filename="src/adw-toast.c" + line="808">a toast + - + the title of @self - + filename="src/adw-toast.c" + line="809">the priority + - - + Sets the tooltip of @self. + filename="src/adw-toast.c" + line="853">Sets timeout for @self. -The tooltip can be marked up with the Pango text markup language. +If @timeout is 0, the toast is displayed indefinitely until manually +dismissed. -If not set, [class@TabBar] and [class@TabOverview] will use -[property@TabPage:title] as a tooltip instead. - +Toasts cannot disappear while being hovered, pressed (on touchscreen), or +have keyboard focus inside them. + a tab page - + filename="src/adw-toast.c" + line="855">a toast + - + the tooltip of @self - + filename="src/adw-toast.c" + line="856">the timeout + - - - - The child of the page. - - - - - - The icon of the page. - -[class@TabBar] and [class@TabOverview] display the icon next to the title, -unless [property@TabPage:loading] is set to `TRUE`. - -`AdwTabBar` also won't show the icon if the page is pinned and -[propertyTabPage:indicator-icon] is set. - - - - - - Whether the indicator icon is activatable. - -If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted -when the indicator icon is clicked. - -If [property@TabPage:indicator-icon] is not set, does nothing. - - - - - - An indicator icon for the page. - -A common use case is an audio or camera indicator in a web browser. - -[class@TabBar] will show it at the beginning of the tab, alongside icon -representing [property@TabPage:icon] or loading spinner. - -If the page is pinned, the indicator will be shown instead of icon or -spinner. + + + Sets the title that will be displayed on the toast. -[class@TabOverview] will show it at the at the top part of the thumbnail. +The title can be marked up with the Pango text markup language. -[property@TabPage:indicator-tooltip] can be used to set the tooltip on the -indicator icon. +Setting a title will unset [property@Toast:custom-title]. -If [property@TabPage:indicator-activatable] is set to `TRUE`, the -indicator icon can act as a button. - - - - - +If [property@Toast:custom-title] is set, it will be used instead. + + + + + + + a toast + + + + a title + + + + + The tooltip of the indicator icon. - -The tooltip can be marked up with the Pango text markup language. + filename="src/adw-toast.c" + line="992">Whether to use Pango markup for the toast title. -See [property@TabPage:indicator-icon]. - - - + + + + + + + a toast + + + + whether to use markup + + + + + - - + setter="set_action_name" + getter="get_action_name" + default-value="NULL"> The search keyboard of the page. + filename="src/adw-toast.c" + line="337">The name of the associated action. -[class@TabOverview] can search pages by their keywords in addition to their -titles and tooltips. +It will be activated when clicking the button. -Keywords allow to include e.g. page URLs into tab search in a web browser. +See [property@Toast:action-target]. - - - - Whether to enable live thumbnail for this page. - -When set to `TRUE`, the page's thumbnail in [class@TabOverview] will update -immediately when the page is redrawn or resized. - -If it's set to `FALSE`, the thumbnail will only be live when the page is -selected, and otherwise it will be static and will only update when -[method@TabPage.invalidate_thumbnail] or -[method@TabView.invalidate_thumbnails] is called. - - - - - + setter="set_action_target_value" + getter="get_action_target_value"> Whether the page is loading. - -If set to `TRUE`, [class@TabBar] and [class@TabOverview] will display a -spinner in place of icon. - -If the page is pinned and [property@TabPage:indicator-icon] is set, -loading status will not be visible with `AdwTabBar`. - + filename="src/adw-toast.c" + line="351">The parameter for action invocations. + - - - + setter="set_button_label" + getter="get_button_label" + default-value="NULL"> Whether the page needs attention. + filename="src/adw-toast.c" + line="321">The label to show on the button. -[class@TabBar] will display a line under the tab representing the page if -set to `TRUE`. If the tab is not visible, the corresponding edge of the tab -bar will be highlighted. +Underlines in the button text can be used to indicate a mnemonic. -[class@TabOverview] will display a dot in the corner of the thumbnail if set -to `TRUE`. +If set to `NULL`, the button won't be shown. -[class@TabButton] will display a dot if any of the pages that aren't -selected have this property set to `TRUE`. - +See [property@Toast:action-name]. + - - + setter="set_custom_title" + getter="get_custom_title"> The parent page of the page. + filename="src/adw-toast.c" + line="397">The custom title widget. -See [method@TabView.add_page] and [method@TabView.close_page]. - - - - - Whether the page is pinned. +It will be displayed instead of the title if set. In this case, +[property@Toast:title] is ignored. -See [method@TabView.set_page_pinned]. - - - - - Whether the page is selected. - +Setting a custom title will unset [property@Toast:title]. + - - - + setter="set_priority" + getter="get_priority" + default-value="ADW_TOAST_PRIORITY_NORMAL"> The horizontal alignment of the page thumbnail. + filename="src/adw-toast.c" + line="362">The priority of the toast. -If the page is so wide that [class@TabOverview] can't display it completely -and has to crop it, horizontal alignment will determine which part of the -page will be visible. +Priority controls how the toast behaves when another toast is already +being displayed. -For example, 0.5 means the center of the page will be visible, 0 means the -start edge will be visible and 1 means the end edge will be visible. +If the priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued. -The default horizontal alignment is 0. - +If the priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed +immediately, pushing the previous toast into the queue instead. + - - - + setter="set_timeout" + getter="get_timeout" + default-value="5"> The vertical alignment of the page thumbnail. - -If the page is so tall that [class@TabOverview] can't display it completely -and has to crop it, vertical alignment will determine which part of the -page will be visible. + filename="src/adw-toast.c" + line="381">The timeout of the toast, in seconds. -For example, 0.5 means the center of the page will be visible, 0 means the -top edge will be visible and 1 means the bottom edge will be visible. +If timeout is 0, the toast is displayed indefinitely until manually +dismissed. -The default vertical alignment is 0. - +Toasts cannot disappear while being hovered, pressed (on touchscreen), or +have keyboard focus inside them. + - - The title of the page. + filename="src/adw-toast.c" + line="305">The title of the toast. -[class@TabBar] will display it in the center of the tab unless it's pinned, -and will use it as a tooltip unless [property@TabPage:tooltip] is set. +The title can be marked up with the Pango text markup language. -[class@TabOverview] will display it below the thumbnail unless it's pinned, -or inside the card otherwise, and will use it as a tooltip unless -[property@TabPage:tooltip] is set. +Setting a title will unset [property@Toast:custom-title]. + +If [property@Toast:custom-title] is set, it will be used instead. - - - + setter="set_use_markup" + getter="get_use_markup" + default-value="TRUE"> The tooltip of the page. - -The tooltip can be marked up with the Pango text markup language. + filename="src/adw-toast.c" + line="414">Whether to use Pango markup for the toast title. -If not set, [class@TabBar] and [class@TabOverview] will use -[property@TabPage:title] as a tooltip instead. - +See also [func@Pango.parse_markup]. + + + Emitted after the button has been clicked. + +It can be used as an alternative to setting an action. + + + + + + Emitted when the toast has been dismissed. + + + + - - + + - + glib:type-name="AdwToastOverlay" + glib:get-type="adw_toast_overlay_get_type" + glib:type-struct="ToastOverlayClass"> A dynamic tabbed container. - -`AdwTabView` is a container which shows one child at a time. While it -provides keyboard shortcuts for switching between pages, it does not provide -a visible tab switcher and relies on external widgets for that, such as -[class@TabBar], [class@TabOverview] and [class@TabButton]. - -`AdwTabView` maintains a [class@TabPage] object for each page, which holds -additional per-page properties. You can obtain the `AdwTabPage` for a page -with [method@TabView.get_page], and as the return value for -[method@TabView.append] and other functions for adding children. + filename="src/adw-toast-overlay.c" + line="25">A widget showing toasts above its content. -`AdwTabView` only aims to be useful for dynamic tabs in multi-window -document-based applications, such as web browsers, file managers, text -editors or terminals. It does not aim to replace [class@Gtk.Notebook] for use -cases such as tabbed dialogs. +<picture> + <source srcset="toast-overlay-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toast-overlay.png" alt="toast-overlay"> +</picture> -As such, it does not support disabling page reordering or detaching. +Much like [class@Gtk.Overlay], `AdwToastOverlay` is a container with a single +main child, on top of which it can display a [class@Toast], overlaid. +Toasts can be shown with [method@ToastOverlay.add_toast]. -`AdwTabView` adds a number of global page switching and reordering shortcuts. -The [property@TabView:shortcuts] property can be used to manage them. +Use [method@ToastOverlay.dismiss_all] to dismiss all toasts at once, or +[method@Toast.dismiss] to dismiss a single toast. -See [flags@TabViewShortcuts] for the list of the available shortcuts. All of -the shortcuts are enabled by default. +See [class@Toast] for details. -[method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] can be -used to manage shortcuts in a convenient way, for example: +## CSS nodes -```c -adw_tab_view_remove_shortcuts (view, ADW_TAB_VIEW_SHORTCUT_CONTROL_HOME | - ADW_TAB_VIEW_SHORTCUT_CONTROL_END); +``` +toastoverlay +├── [child] +├── toast +┊ ├── widget +┊ │ ├── [label.heading] + │ ╰── [custom title] + ├── [button] + ╰── button.circular.flat ``` -## CSS nodes +`AdwToastOverlay`'s CSS node is called `toastoverlay`. It contains the child, +as well as zero or more `toast` subnodes. -`AdwTabView` has a main CSS node with the name `tabview`. +Each of the `toast` nodes contains a `widget` subnode, optionally a `button` +subnode, and another `button` subnode with `.circular` and `.flat` style +classes. + +The `widget` subnode contains a `label` subnode with the `.heading` style +class, or a custom widget provided by the application. ## Accessibility -`AdwTabView` uses the `GTK_ACCESSIBLE_ROLE_TAB_PANEL` for the tab pages which -are the accessible parent objects of the child widgets. - +`AdwToastOverlay` uses the `GTK_ACCESSIBLE_ROLE_TAB_GROUP` role. + - + Creates a new `AdwTabView`. - + filename="src/adw-toast-overlay.c" + line="581">Creates a new `AdwToastOverlay`. + the newly created `AdwTabView` - + filename="src/adw-toast-overlay.c" + line="586">the new created `AdwToastOverlay` + - - Adds @child to @self with @parent as the parent. - -This function can be used to automatically position new pages, and to select -the correct page when this page is closed while being selected (see -[method@TabView.close_page]). - -If @parent is `NULL`, this function is equivalent to [method@TabView.append]. - - - the page object representing @child - - - - - a tab view - - - - a widget to add - - - - a parent page for @child - - - - - - Adds @shortcuts for @self. - -See [property@TabView:shortcuts] for details. - - - - - - - a tab view - - - - the shortcuts to add - - - - - - Inserts @child as the last non-pinned page. - - - the page object representing @child - - - - - a tab view - - - - a widget to add - - - - - - Inserts @child as the last pinned page. - - - the page object representing @child - - - - - a tab view - - - - a widget to add - - - - - - Requests to close all pages other than @page. - - - - - - - a tab view - - - - a page of @self - - - - - + Requests to close @page. - -Calling this function will result in the [signal@TabView::close-page] signal -being emitted for @page. Closing the page can then be confirmed or -denied via [method@TabView.close_page_finish]. - -If the page is waiting for a [method@TabView.close_page_finish] call, this -function will do nothing. - -The default handler for [signal@TabView::close-page] will immediately confirm -closing the page if it's non-pinned, or reject it if it's pinned. This -behavior can be changed by registering your own handler for that signal. + filename="src/adw-toast-overlay.c" + line="641">Displays @toast. -If @page was selected, another page will be selected instead: +Only one toast can be shown at a time; if a toast is already being displayed, +either @toast or the original toast will be placed in a queue, depending on +the priority of @toast. See [property@Toast:priority]. -If the [property@TabPage:parent] value is `NULL`, the next page will be -selected when possible, or if the page was already last, the previous page -will be selected instead. +If called on a toast that's already displayed, its timeout will be reset. -If it's not `NULL`, the previous page will be selected if it's a descendant -(possibly indirect) of the parent. If both the previous page and the parent -are pinned, the parent will be selected instead. - +If called on a toast currently in the queue, the toast will be bumped +forward to be shown as soon as possible. + a tab view - + filename="src/adw-toast-overlay.c" + line="643">a toast overlay + - + a page of @self - + filename="src/adw-toast-overlay.c" + line="644">a toast + - + Completes a [method@TabView.close_page] call for @page. - -If @confirm is `TRUE`, @page will be closed. If it's `FALSE`, it will be -reverted to its previous state and [method@TabView.close_page] can be called -for it again. + filename="src/adw-toast-overlay.c" + line="723">Dismisses all displayed toasts. -This function should not be called unless a custom handler for -[signal@TabView::close-page] is used. - +Use [method@Toast.dismiss] to dismiss a single toast. + a tab view - + filename="src/adw-toast-overlay.c" + line="725">a toast overlay + - - a page of @self - - - - whether to confirm or deny closing @page - - - + Requests to close all pages after @page. - - - + filename="src/adw-toast-overlay.c" + line="594">Gets the child widget of @self. + + + the child widget of @self + a tab view - + filename="src/adw-toast-overlay.c" + line="596">a toast overlay + - - a page of @self - - - + Requests to close all pages before @page. - + filename="src/adw-toast-overlay.c" + line="610">Sets the child widget of @self. + a tab view - + filename="src/adw-toast-overlay.c" + line="612">a toast overlay + - + a page of @self - + filename="src/adw-toast-overlay.c" + line="613">the child widget + - - + Gets the default icon of @self. - - + filename="src/adw-toast-overlay.c" + line="531">The child widget. + + + + + + + + + + + [class@Toast] behavior when another toast is already displayed. + + the toast will be queued if another toast is + already displayed. + + + the toast will be displayed immediately, pushing + the previous toast into the queue instead. + + + + A toggle within [class@ToggleGroup]. + +`AdwToggle` can optionally have a name, set with [property@Toggle:name]. +If the name is set, [property@ToggleGroup:active-name] can be used to access +toggles instead of index. + + + Creates a new `AdwToggle`. + + the default icon of @self. - + filename="src/adw-toggle-group.c" + line="1172">the newly created `AdwToggle` + + + + + Gets the child widget of @self. + + + the toggle child + a tab view - + filename="src/adw-toggle-group.c" + line="1424">a toggle + - - + Whether a page is being transferred. - -The corresponding property will be set to `TRUE` when a drag-n-drop tab -transfer starts on any `AdwTabView`, and to `FALSE` after it ends. - -During the transfer, children cannot receive pointer input and a tab can -be safely dropped on the tab view. - + filename="src/adw-toggle-group.c" + line="1473">Gets whether @self is enabled. + whether a page is being transferred + filename="src/adw-toggle-group.c" + line="1479">whether the toggle is enabled a tab view - + filename="src/adw-toggle-group.c" + line="1475">a toggle + - - + Gets the tab context menu model for @self. - + filename="src/adw-toggle-group.c" + line="1335">Gets the icon name of @self. + the tab context menu model for @self - + filename="src/adw-toggle-group.c" + line="1341">the toggle icon name + a tab view - + filename="src/adw-toggle-group.c" + line="1337">a toggle + - - + Gets the number of pages in @self. - + filename="src/adw-toggle-group.c" + line="1522">Gets the index of @self within its toggle group. + the number of pages in @self - + filename="src/adw-toggle-group.c" + line="1528">the index, or `GTK_INVALID_LIST_POSITION` if it's not in a group + a tab view - + filename="src/adw-toggle-group.c" + line="1524">a toggle + - - + Gets the number of pinned pages in @self. - -See [method@TabView.set_page_pinned]. - - + filename="src/adw-toggle-group.c" + line="1243">Gets the label of @self. + + the number of pinned pages in @self - + filename="src/adw-toggle-group.c" + line="1249">the toggle label + a tab view - + filename="src/adw-toggle-group.c" + line="1245">a toggle + - + Gets the [class@TabPage] representing the child at @position. - + filename="src/adw-toggle-group.c" + line="1182">Gets the name of @self. + the page object at @position - + filename="src/adw-toggle-group.c" + line="1188">the toggle name + a tab view - + filename="src/adw-toggle-group.c" + line="1184">a toggle + - - the index of the page in @self, starting from 0 - - - + Gets the [class@TabPage] object representing @child. - + filename="src/adw-toggle-group.c" + line="1379">Gets the tooltip of @self. + the page object for @child - + filename="src/adw-toggle-group.c" + line="1385">the toggle tooltip + a tab view - + filename="src/adw-toggle-group.c" + line="1381">a toggle + - - a child in @self - - - + Finds the position of @page in @self, starting from 0. - + filename="src/adw-toggle-group.c" + line="1288">Gets whether @self uses underlines. + the position of @page in @self - + filename="src/adw-toggle-group.c" + line="1294">whether the toggle uses underlines + a tab view - + filename="src/adw-toggle-group.c" + line="1290">a toggle + - - a page of @self - - - - + Returns a [iface@Gio.ListModel] that contains the pages of @self. + filename="src/adw-toggle-group.c" + line="1440">Sets the child of @self to @child. -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track and change the selected -page. - - - a `GtkSelectionModel` for the pages of @self - +When the child is set, icon and label are not displayed. + +It's recommended to still set the label, as it can still be used by the +screen reader. + + + a tab view - + filename="src/adw-toggle-group.c" + line="1442">a toggle + + + a child widget + + - - + Gets the currently selected page in @self. - - - the selected page - + filename="src/adw-toggle-group.c" + line="1491">Sets whether @self is enabled. + + + a tab view - + filename="src/adw-toggle-group.c" + line="1493">a toggle + + + whether the toggle should be enbled + + - - + Gets the enabled shortcuts for @self. - + filename="src/adw-toggle-group.c" + line="1353">Sets the icon name of @self to @icon_name. + +The icon will be displayed alone or next to the label, unless +[property@Toggle:child] is set. + - the shortcut mask - + a tab view - + filename="src/adw-toggle-group.c" + line="1355">a toggle + + + the icon name + + - + Inserts a non-pinned page at @position. + filename="src/adw-toggle-group.c" + line="1261">Sets the label of @self to @label. -It's an error to try to insert a page before a pinned page, in that case -[method@TabView.insert_pinned] should be used instead. - +The label will be displayed alone or next to the icon, unless +[property@Toggle:child] is set, but will still be read out by the screen +reader. + - the page object representing @child - + a tab view - + filename="src/adw-toggle-group.c" + line="1263">a toggle + - - a widget to add - - - + the position to add @child at, starting from 0 - + filename="src/adw-toggle-group.c" + line="1264">a label + - + Inserts a pinned page at @position. + filename="src/adw-toggle-group.c" + line="1200">Sets the name of @self to @name. -It's an error to try to insert a pinned page after a non-pinned page, in -that case [method@TabView.insert] should be used instead. - +Allows accessing @self by its name instead of index. + +See [property@ToggleGroup:active-name]. + - the page object representing @child - + a tab view - + filename="src/adw-toggle-group.c" + line="1202">a toggle + - + a widget to add - + filename="src/adw-toggle-group.c" + line="1203">a name + - + + + + Sets the tooltip of @self to @tooltip. + +@tooltip can be marked up with the Pango text markup language. + + + + + + the position to add @child at, starting from 0 - + filename="src/adw-toggle-group.c" + line="1399">a toggle + + + + the tooltip + - + Invalidates thumbnails for all pages in @self. + filename="src/adw-toggle-group.c" + line="1306">Sets whether an embedded underline in the label indicates a mnemonic. -This is a convenience method, equivalent to calling -[method@TabPage.invalidate_thumbnail] on each page. - +See [property@Toggle:label]. + a tab view - + filename="src/adw-toggle-group.c" + line="1308">a toggle + + + whether an underline in the label indicates a mnemonic + + - + + The toggle child. + +When the child is set, icon and label are not displayed. + +It's recommended to still set the label, as it can still be used by the +screen reader. + + + + Whether this toggle is enabled. + + + + The toggle icon name. + +The icon will be displayed alone or next to the label, unless +[property@Toggle:child] is set. + + + + The toggle label. + +The label will be displayed alone or next to the icon, unless +[property@Toggle:child] is set, but will still be read out by the screen +reader. + + + + The toggle name. + +Allows accessing the toggle by its name instead of index. + +See [property@ToggleGroup:active-name]. + + + + The tooltip of the toggle. + +The tooltip can be marked up with the Pango text markup language. + + + + Whether an embedded underline in the label indicates a mnemonic. + +See [property@Toggle:label]. + + + + + + + + + + + A group of exclusive toggles. + +<picture> + <source srcset="toggle-group-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toggle-group.png" alt="toggle-group"> +</picture> + +`AdwToggleGroup` presents a set of exclusive toggles, represented as +[class@Toggle] objects. Each toggle can display an icon, a label, an icon +and a label, or a custom child. + +Toggles are indexed by their position, with the first toggle being equivalent +to 0, and so on. Use the [property@ToggleGroup:active] to get that position. + +Toggles can also have optional names, set via the [property@Toggle:name] +property. The name of the active toggle can be accessed via the +[property@ToggleGroup:active-name] property. + +`AdwToggle` objects can be retrieved via their index or name, using +[method@ToggleGroup.get_toggle] or [method@ToggleGroup.get_toggle_by_name] +respectively. `AdwToggleGroup` also provides a [iface@Gtk.SelectionModel] of +its toggles via the [property@ToggleGroup:toggles] property. + +`AdwToggleGroup` is orientable, and the toggles can be displayed horizontally +or vertically. This is mostly useful for icon-only toggles. + +Use the [property@ToggleGroup:homogeneous] property to make the toggles take +the same size, and the [property@ToggleGroup:can-shrink] to control whether +the toggles can ellipsize. + +Example of an `AdwToggleGroup` UI definition: + +```xml + <object class="AdwToggleGroup"> + <property name="active-name">picture</property> + <child> + <object class="AdwToggle"> + <property name="icon-name">camera-photo-symbolic</property> + <property name="tooltip" translatable="yes">Picture Mode</property> + <property name="name">picture</property> + </object> + </child> + <child> + <object class="AdwToggle"> + <property name="icon-name">camera-video-symbolic</property> + <property name="tooltip" translatable="yes">Recording Mode</property> + <property name="name">recording</property> + </object> + </child> + </object> +``` + +See also: [class@InlineViewSwitcher]. + +## CSS nodes + +`AdwToggleGroup` has a main CSS node with the name `toggle-group`. + +Its toggles have CSS nodes with the name `toggle`, and its separators have nodes +with the name `separator`. + +Toggle nodes will have a different style classes depending on their content: +`.text-button` for labels, `.image-button` for icons, `.image-text-button` +for both or no style class for custom children. + +The hidden separators use the `.hidden` style class. + +## Style classes + +`AdwToggleGroup` can use the [`.flat`](style-classes.html#flat_1) style class +to remove its background and make it look like a group of buttons. + +<picture> + <source srcset="toggle-group-flat-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toggle-group-flat.png" alt="toggle-group-flat"> +</picture> + +It can also use the [`.round`](style-classes.html#round) style class to make +its toggles and the group itself rounded. + +<picture> + <source srcset="toggle-group-round-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toggle-group-round.png" alt="toggle-group-round"> +</picture> + +They can also be combined with each other. + +<picture> + <source srcset="toggle-group-flat-round-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toggle-group-flat-round.png" alt="toggle-group-flat-round"> +</picture> + +## Accessibility + +`AdwToggleGroup` uses the `GTK_ACCESSIBLE_ROLE_RADIO_GROUP` role. Its toggles +use the `GTK_ACCESSIBLE_ROLE_RADIO` role. + + + + + + Inserts @child as the first non-pinned page. - + filename="src/adw-toggle-group.c" + line="1540">Creates a new `AdwToggleGroup`. + the page object representing @child - + filename="src/adw-toggle-group.c" + line="1545">the newly created `AdwToggleGroup` + - - - a tab view - - - - a widget to add - - - - - + + Inserts @child as the first pinned page. - + filename="src/adw-toggle-group.c" + line="1555">Adds a toggle to @self. + - the page object representing @child - + a tab view - + filename="src/adw-toggle-group.c" + line="1557">a toggle group + - + a widget to add - + filename="src/adw-toggle-group.c" + line="1558">the toggle to add + - + Removes @shortcuts from @self. + filename="src/adw-toggle-group.c" + line="1749">Gets the index of the active toggle in @self. -See [property@TabView:shortcuts] for details. - +Returns `GTK_INVALID_LIST_POSITION` if no toggle is active. + - + the active toggle index + a tab view - + filename="src/adw-toggle-group.c" + line="1751">a toggle group + - - the shortcuts to reomve - - - + Reorders @page to before its previous page if possible. - - + filename="src/adw-toggle-group.c" + line="1794">Gets the name of the active toggle in @self. + +Can be `NULL` if the currently active toggle doesn't have a name. + +See [property@Toggle:name]. + + whether @page was moved - + filename="src/adw-toggle-group.c" + line="1804">the active toggle name + a tab view - + filename="src/adw-toggle-group.c" + line="1796">a toggle group + - - a page of @self - - - + Reorders @page to the first possible position. - + filename="src/adw-toggle-group.c" + line="1920">Gets whether the toggles can be smaller than the natural size of their +contents. + whether @page was moved + filename="src/adw-toggle-group.c" + line="1927">whether the toggles can shrink a tab view - + filename="src/adw-toggle-group.c" + line="1922">a toggle group + - - a page of @self - - - + Reorders @page to after its next page if possible. - + filename="src/adw-toggle-group.c" + line="1859">Gets whether all toggles take the same size. + whether @page was moved + filename="src/adw-toggle-group.c" + line="1865">whether all toggles take the same size a tab view - + filename="src/adw-toggle-group.c" + line="1861">a toggle group + - - a page of @self - - - + Reorders @page to the last possible position. - + filename="src/adw-toggle-group.c" + line="1731">Gets the number of toggles within @self. + whether @page was moved - + filename="src/adw-toggle-group.c" + line="1737">the number of toggles + a tab view - + filename="src/adw-toggle-group.c" + line="1733">a toggle group + - - a page of @self - - - + Reorders @page to @position. - -It's a programmer error to try to reorder a pinned page after a non-pinned -one, or a non-pinned page before a pinned one. - - + filename="src/adw-toggle-group.c" + line="1687">Gets the toggle with @index from @self. + + whether @page was moved - + filename="src/adw-toggle-group.c" + line="1694">the toggle + a tab view - + filename="src/adw-toggle-group.c" + line="1689">a toggle group + - - a page of @self - - - + the position to insert the page at, starting at 0 - + filename="src/adw-toggle-group.c" + line="1690">toggle's index + - + Selects the page after the currently selected page. - -If the last page was already selected, this function does nothing. - - + filename="src/adw-toggle-group.c" + line="1710">Gets the toggle with the name @name from @self. + + whether the selected page was changed - + filename="src/adw-toggle-group.c" + line="1717">the toggle + a tab view - + filename="src/adw-toggle-group.c" + line="1712">a toggle group + + + toggle name + + - + Selects the page before the currently selected page. + filename="src/adw-toggle-group.c" + line="1977">Returns a [iface@Gio.ListModel] that contains the toggles of the group. -If the first page was already selected, this function does nothing. - - +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the active +toggle. + + whether the selected page was changed - + filename="src/adw-toggle-group.c" + line="1987">a `GtkSelectionModel` for the group's toggles + a tab view - + filename="src/adw-toggle-group.c" + line="1979">a toggle group + - - + Sets the default page icon for @self. - -If a page doesn't provide its own icon via [property@TabPage:icon], a default -icon may be used instead for contexts where having an icon is necessary. - -[class@TabBar] will use default icon for pinned tabs in case the page is not -loading, doesn't have an icon and an indicator. Default icon is never used -for tabs that aren't pinned. - -[class@TabOverview] will use default icon for pages with missing thumbnails. - -By default, the `adw-tab-icon-missing-symbolic` icon is used. - + filename="src/adw-toggle-group.c" + line="1575">Removes @toggle from @self. + a tab view - + filename="src/adw-toggle-group.c" + line="1577">a toggle group + - + the default icon - + filename="src/adw-toggle-group.c" + line="1578">a toggle to remove + - - + Sets the tab context menu model for @self. - -When a context menu is shown for a tab, it will be constructed from the -provided menu model. Use the [signal@TabView::setup-menu] signal to set up -the menu actions for the particular tab. - + filename="src/adw-toggle-group.c" + line="1642">Removes all toggles from @self. + a tab view - + filename="src/adw-toggle-group.c" + line="1644">a toggle group + - - a menu model - - - + Pins or unpins @page. - -Pinned pages are guaranteed to be placed before all non-pinned pages; at any -given moment the first [property@TabView:n-pinned-pages] pages in @self are -guaranteed to be pinned. - -When a page is pinned or unpinned, it's automatically reordered: pinning a -page moves it after other pinned pages; unpinning a page moves it before -other non-pinned pages. - -Pinned pages can still be reordered between each other. - -[class@TabBar] will display pinned pages in a compact form, never showing the -title or close button, and only showing a single icon, selected in the -following order: - -1. [property@TabPage:indicator-icon] -2. A spinner if [property@TabPage:loading] is `TRUE` -3. [property@TabPage:icon] -4. [property@TabView:default-icon] - -[class@TabOverview] will not show a thumbnail for pinned pages, and replace -the close button with an unpin button. Unlike `AdwTabBar`, it will still -display the page's title, icon and indicator separately. + filename="src/adw-toggle-group.c" + line="1769">Sets the active toggle for @self. -Pinned pages cannot be closed by default, see [signal@TabView::close-page] -for how to override that behavior. - -Changes the value of the [property@TabPage:pinned] property. - +If the index is larger than the number of toggles in @self, unsets the +current active toggle. + a tab view - + filename="src/adw-toggle-group.c" + line="1771">a toggle group + - + a page of @self - - - - whether @page should be pinned - + filename="src/adw-toggle-group.c" + line="1772">toggle index + - - + Sets the currently selected page in @self. - + filename="src/adw-toggle-group.c" + line="1824">Sets the active toggle for @self. + +The name can be set via [property@Toggle:name]. + +If @name is `NULL`, unset the current active toggle instead. + a tab view - + filename="src/adw-toggle-group.c" + line="1826">a toggle group + - + a page in @self - + filename="src/adw-toggle-group.c" + line="1827">toggle name + - - + Sets the enabled shortcuts for @self. + filename="src/adw-toggle-group.c" + line="1939">Sets whether the toggles can be smaller than the natural size of their +contents. -See [flags@TabViewShortcuts] for the list of the available shortcuts. All of -the shortcuts are enabled by default. +If @can_shrink is `TRUE`, the toggle labels will ellipsize. -[method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] provide -a convenient way to manage individual shortcuts. - +See [property@Gtk.Button:can-shrink]. + a tab view - + filename="src/adw-toggle-group.c" + line="1941">a toggle group + - + the new shortcuts - + filename="src/adw-toggle-group.c" + line="1942">whether the toggles can shrink + - + Transfers @page from @self to @other_view. - -The @page object will be reused. - -It's a programmer error to try to insert a pinned page after a non-pinned -one, or a non-pinned page before a pinned one. - + filename="src/adw-toggle-group.c" + line="1877">Sets whether all toggles take the same size. + a tab view - + filename="src/adw-toggle-group.c" + line="1879">a toggle group + - - a page of @self - - - - the tab view to transfer the page to - - - + the position to insert the page at, starting at 0 - + filename="src/adw-toggle-group.c" + line="1880">whether all toggles should take the same size + - - - + setter="set_active" + getter="get_active" + default-value="4294967295"> Default page icon. + filename="src/adw-toggle-group.c" + line="1006">The index of the active toggle. -If a page doesn't provide its own icon via [property@TabPage:icon], a -default icon may be used instead for contexts where having an icon is -necessary. +Setting the index to a larger value than the number of toggles in the group +unsets the current active toggle. -[class@TabBar] will use default icon for pinned tabs in case the page is -not loading, doesn't have an icon and an indicator. Default icon is never -used for tabs that aren't pinned. +If no toggle is active, the property will be set to +[const@Gtk.INVALID_LIST_POSITION]. + + + + The name of the active toggle. -[class@TabOverview] will use default icon for pages with missing -thumbnails. +The name can be set via [property@Toggle:name]. If the currently active +toggle doesn't have a name, the property will be set to `NULL`. -By default, the `adw-tab-icon-missing-symbolic` icon is used. - +Set it to `NULL` to unset the current active toggle. + - - + setter="set_can_shrink" + getter="get_can_shrink" + default-value="TRUE"> Whether a page is being transferred. + filename="src/adw-toggle-group.c" + line="1053">Whether the toggles can be smaller than the natural size of their contents. -This property will be set to `TRUE` when a drag-n-drop tab transfer starts -on any `AdwTabView`, and to `FALSE` after it ends. +If set to `TRUE`, the toggle labels will ellipsize. -During the transfer, children cannot receive pointer input and a tab can -be safely dropped on the tab view. +See [property@Gtk.Button:can-shrink]. - - - + setter="set_homogeneous" + getter="get_homogeneous" + default-value="FALSE"> Tab context menu model. - -When a context menu is shown for a tab, it will be constructed from the -provided menu model. Use the [signal@TabView::setup-menu] signal to set up -the menu actions for the particular tab. - + filename="src/adw-toggle-group.c" + line="1041">Whether all toggles take the same size. + - - The number of pages in the tab view. - + filename="src/adw-toggle-group.c" + line="994">The number of toggles within the group. + - - + getter="get_toggles"> The number of pinned pages in the tab view. + filename="src/adw-toggle-group.c" + line="1069">A selection model with the groups's toggles. -See [method@TabView.set_page_pinned]. - +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the active +toggle. + - - + + + + + + + + + Describes the possible top or bottom bar styles in an [class@ToolbarView] +widget. + +`ADW_TOOLBAR_FLAT` is suitable for simple content, such as +[class@StatusPage] or [class@PreferencesPage], where the background at the +top and bottom parts of the page is uniform. Additionally, windows with +sidebars should always use this style. + +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1"> +</picture> +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2"> +</picture> + +`ADW_TOOLBAR_RAISED` style is suitable for content such as +[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +where some elements are directly adjacent to the top/bottom bars, or +[class@TabView], where each page can have a different background. + +`ADW_TOOLBAR_RAISED_BORDER` style is similar to `ADW_TOOLBAR_RAISED`, but +with the shadow replaced with a more subtle border. It's intended to be used +in applications like image viewers, where a shadow over the content might be +undesired. + +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-raised.png" alt="toolbar-view-raised"> +</picture> +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-raised-border-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-raised-border.png" alt="toolbar-view-raised-border"> +</picture> + +See [property@ToolbarView:top-bar-style] and +[property@ToolbarView:bottom-bar-style]. + +New values may be added to this enumeration over time. + A selection model with the tab view's pages. + filename="src/adw-toolbar-view.c" + line="121">No background, shadow only for scrolled content + + + Opaque background with a persistent shadow + + + Opaque background with a persistent border + + + + A widget containing a page, as well as top and/or bottom bars. + +<picture> + <source srcset="toolbar-view-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view.png" alt="toolbar-view"> +</picture> + +`AdwToolbarView` has a single content widget and one or multiple top and +bottom bars, shown at the top and bottom sides respectively. + +Example of an `AdwToolbarView` UI definition: +```xml +<object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"/> + </child> + <property name="content"> + <object class="AdwPreferencesPage"> + <!-- ... --> + </object> + </property> +</object> +``` + +The following kinds of top and bottom bars are supported: + +- [class@HeaderBar] +- [class@TabBar] +- [class@ViewSwitcherBar] +- [class@Gtk.ActionBar] +- [class@Gtk.HeaderBar] +- [class@Gtk.PopoverMenuBar] +- [class@Gtk.SearchBar] +- Any [class@Gtk.Box] or a similar widget with the + [`.toolbar`](style-classes.html#toolbars) style class -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track and change the selected -page. - - - - - - The currently selected page. - - - - - - The enabled shortcuts. +By default, top and bottom bars are flat and scrolling content has a subtle +undershoot shadow, same as when using the +[`.undershoot-top`](style-classes.html#undershoot-indicators) and +[`.undershoot-bottom`](style-classes.html#undershoot-indicators) style +classes. This works well in most cases, e.g. with [class@StatusPage] or +[class@PreferencesPage], where the background at the top and bottom parts of +the page is uniform. Additionally, windows with sidebars should always use +this style. -See [flags@TabViewShortcuts] for the list of the available shortcuts. All -of the shortcuts are enabled by default. +[property@ToolbarView:top-bar-style] and +[property@ToolbarView:bottom-bar-style] properties can be used add an opaque +background and a persistent shadow to top and bottom bars, this can be useful +for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +where some elements are adjacent to the top/bottom bars, or [class@TabView], +where each page can have a different background. -[method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] -provide a convenient way to manage individual shortcuts. - - - - Emitted after [method@TabView.close_page] has been called for @page. +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1"> +</picture> +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2"> +</picture> +<picture style="min-width: 33%; display: inline-block;"> + <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-raised.png" alt="toolbar-view-raised"> +</picture> -The handler is expected to call [method@TabView.close_page_finish] to -confirm or reject the closing. +`AdwToolbarView` ensures the top and bottom bars have consistent backdrop +styles and vertical spacing. For comparison: -The default handler will immediately confirm closing for non-pinned pages, -or reject it for pinned pages, equivalent to the following example: +<picture style="min-width: 40%; display: inline-block;"> + <source srcset="toolbar-view-spacing-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-spacing.png" alt="toolbar-view-spacing"> +</picture> +<picture style="min-width: 40%; display: inline-block;"> + <source srcset="toolbar-view-spacing-box-dark.png" media="(prefers-color-scheme: dark)"> + <img src="toolbar-view-spacing-box.png" alt="toolbar-view-spacing-box"> +</picture> -```c -static gboolean -close_page_cb (AdwTabView *view, - AdwTabPage *page, - gpointer user_data) -{ - adw_tab_view_close_page_finish (view, page, !adw_tab_page_get_pinned (page)); +Any top and bottom bars can also be dragged to move the window, equivalent +to putting them into a [class@Gtk.WindowHandle]. - return GDK_EVENT_STOP; -} -``` +Content is typically place between top and bottom bars, but can also extend +behind them. This is controlled with the +[property@ToolbarView:extend-content-to-top-edge] and +[property@ToolbarView:extend-content-to-bottom-edge] properties. -The [method@TabView.close_page_finish] call doesn't have to happen inside -the handler, so can be used to do asynchronous checks before confirming the -closing. +Top and bottom bars can be hidden and revealed with an animation using the +[property@ToolbarView:reveal-top-bars] and +[property@ToolbarView:reveal-bottom-bars] properties. -A typical reason to connect to this signal is to show a confirmation dialog -for closing a tab. - - - - - - a page of @self - - - - - - Emitted when a tab should be transferred into a new window. +## `AdwToolbarView` as `GtkBuildable` -This can happen after a tab has been dropped on desktop. +The `AdwToolbarView` implementation of the [iface@Gtk.Buildable] interface +supports adding a top bar by specifying “top” as the “type” attribute of a +`<child>` element, or adding a bottom bar by specifying “bottom”. -The signal handler is expected to create a new window, position it as -needed and return its `AdwTabView` that the page will be transferred into. - - the `AdwTabView` from the new window - - - - - Emitted after the indicator icon on @page has been activated. +## Accessibility -See [property@TabPage:indicator-icon] and -[property@TabPage:indicator-activatable]. +`AdwToolbarView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + + + + + + Creates a new `AdwToolbarView`. + - + the newly created `AdwToolbarView` + - - - a page of @self - - - - - + + Emitted when a page has been created or transferred to @self. - -A typical reason to connect to this signal would be to connect to page -signals for things such as updating window title. + filename="src/adw-toolbar-view.c" + line="881">Adds a bottom bar to @self. + - + a page of @self - - - + filename="src/adw-toolbar-view.c" + line="883">a toolbar view + + + the position of the page, starting from 0 - + filename="src/adw-toolbar-view.c" + line="884">a widget + - - + + Emitted when a page has been removed or transferred to another view. - -A typical reason to connect to this signal would be to disconnect signal -handlers connected in the [signal@TabView::page-attached] handler. - -It is important not to try and destroy the page child in the handler of -this function as the child might merely be moved to another window; use -child dispose handler for that or do it in sync with your -[method@TabView.close_page_finish] calls. + filename="src/adw-toolbar-view.c" + line="856">Adds a top bar to @self. + - + a page of @self - - - + filename="src/adw-toolbar-view.c" + line="858">a toolbar view + + + the position of the removed page, starting from 0 - + filename="src/adw-toolbar-view.c" + line="859">a widget + - - + + Emitted after @page has been reordered to @position. + filename="src/adw-toolbar-view.c" + line="1347">Gets the current bottom bar height for @self. + +Bottom bar height does change depending on +[property@ToolbarView:reveal-bottom-bars], including during the transition. + +See [method@ToolbarView.get_top_bar_height]. + - + the current bottom bar height + - - a page of @self - - - + the position @page was moved to, starting at 0 - - + filename="src/adw-toolbar-view.c" + line="1349">a toolbar view + + - - + + Emitted when a context menu is opened or closed for @page. - -If the menu has been closed, @page will be set to `NULL`. - -It can be used to set up menu actions before showing the menu, for example -disable actions not applicable to @page. + filename="src/adw-toolbar-view.c" + line="1032">Gets appearance of the bottom bars for @self. + - + bottom bar style + - + a page of @self - - + filename="src/adw-toolbar-view.c" + line="1034">a toolbar view + + - - - - - - - - - - Describes available shortcuts in an [class@TabView]. - -Shortcuts can be set with [property@TabView:shortcuts], or added/removed -individually with [method@TabView.add_shortcuts] and -[method@TabView.remove_shortcuts]. - -New values may be added to this enumeration over time. - - No shortcuts - - - <kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the next page - - - <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the previous - page - - - <kbd>Ctrl</kbd>+<kbd>Page Up</kbd> - switch to the previous page - - - <kbd>Ctrl</kbd>+<kbd>Page Down</kbd> - switch to the next page - - - <kbd>Ctrl</kbd>+<kbd>Home</kbd> - switch to the first page - - - <kbd>Ctrl</kbd>+<kbd>End</kbd> - switch to the last page - - - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Up</kbd> - move the selected - page backward - - - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Down</kbd> - move the selected - page forward - - - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Home</kbd> - move the selected page - at the start - - - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>End</kbd> - move the current page at - the end - - - <kbd>Alt</kbd>+<kbd>1</kbd>⋯<kbd>9</kbd> - switch to pages 1-9 - - - <kbd>Alt</kbd>+<kbd>0</kbd> - switch to page 10 - - - All of the shortcuts - - - - A time-based [class@Animation]. - -`AdwTimedAnimation` implements a simple animation interpolating the given -value from [property@TimedAnimation:value-from] to -[property@TimedAnimation:value-to] over -[property@TimedAnimation:duration] milliseconds using the curve described by -[property@TimedAnimation:easing]. - -If [property@TimedAnimation:reverse] is set to `TRUE`, `AdwTimedAnimation` -will instead animate from [property@TimedAnimation:value-to] to -[property@TimedAnimation:value-from], and the easing curve will be inverted. - -The animation can repeat a certain amount of times, or endlessly, depending -on the [property@TimedAnimation:repeat-count] value. If -[property@TimedAnimation:alternate] is set to `TRUE`, it will also change the -direction every other iteration. - - + + Creates a new `AdwTimedAnimation` on @widget to animate @target from @from -to @to. - - + filename="src/adw-toolbar-view.c" + line="805">Gets the content widget for @self. + + the newly created animation - + filename="src/adw-toolbar-view.c" + line="811">the content widget + - - a widget to create animation on - - - - a value to animate from - - - - a value to animate to - - - - a duration for the animation - - - + a target value to animate - - + filename="src/adw-toolbar-view.c" + line="807">a toolbar view + + - - - + + Gets whether @self changes direction on every iteration. - + filename="src/adw-toolbar-view.c" + line="1272">Gets whether the content widget can extend behind bottom bars. + whether @self alternates + filename="src/adw-toolbar-view.c" + line="1278">whether content extends behind bottom bars a timed animation - + filename="src/adw-toolbar-view.c" + line="1274">a toolbar view + - - + Gets the duration of @self. - + filename="src/adw-toolbar-view.c" + line="1220">Gets whether the content widget can extend behind top bars. + the duration of @self, in milliseconds - + filename="src/adw-toolbar-view.c" + line="1226">whether content extends behind top bars + a timed animation - + filename="src/adw-toolbar-view.c" + line="1222">a toolbar view + - - + Gets the easing function @self uses. - + filename="src/adw-toolbar-view.c" + line="1169">Gets whether bottom bars are revealed for @self. + the easing function @self uses - + filename="src/adw-toolbar-view.c" + line="1175">whether bottom bars are revealed + a timed animation - + filename="src/adw-toolbar-view.c" + line="1171">a toolbar view + - - + Gets the number of times @self will play. - + filename="src/adw-toolbar-view.c" + line="1118">Gets whether top bars are revealed for @self. + the number of times @self will play - + filename="src/adw-toolbar-view.c" + line="1124">whether top bars are revealed + a timed animation - + filename="src/adw-toolbar-view.c" + line="1120">a toolbar view + - - + Gets whether @self plays backwards. - + filename="src/adw-toolbar-view.c" + line="1324">Gets the current top bar height for @self. + +Top bar height does change depending on +[property@ToolbarView:reveal-top-bars], including during the transition. + +See [method@ToolbarView.get_bottom_bar_height]. + whether @self plays backwards - + filename="src/adw-toolbar-view.c" + line="1335">the current top bar height + a timed animation - + filename="src/adw-toolbar-view.c" + line="1326">a toolbar view + - - + Gets the value @self will animate from. - + filename="src/adw-toolbar-view.c" + line="946">Gets appearance of the top bars for @self. + the value to animate from - + filename="src/adw-toolbar-view.c" + line="952">top bar style + a timed animation - + filename="src/adw-toolbar-view.c" + line="948">a toolbar view + - - + Gets the value @self will animate to. - + filename="src/adw-toolbar-view.c" + line="906">Removes a child from @self. + - the value to animate to - + a timed animation - + filename="src/adw-toolbar-view.c" + line="908">a toolbar view + + + the child to be removed + + - - + Sets whether @self changes direction on every iteration. - + filename="src/adw-toolbar-view.c" + line="1050">Sets appearance of the bottom bars for @self. + +If set to `ADW_TOOLBAR_FLAT`, bottom bars are flat and scrolling content has +a subtle undershoot shadow when touching them, same as the +[`.undershoot-bottom`](style-classes.html#undershoot-indicators) +style class. This works well for simple content, e.g. [class@StatusPage] or +[class@PreferencesPage], where the background at the bottom of the page is +uniform. Additionally, windows with sidebars should always use this style. + +Undershoot shadow is only present if a bottom bar is actually present and +visible. It is also never present if +[property@ToolbarView:extend-content-to-bottom-edge] is set to `TRUE`. + +If set to `ADW_TOOLBAR_RAISED`, bottom bars have an opaque background and a +persistent shadow, this is suitable for content such as +[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +where some elements are directly adjacent to the bottom bars, or +[class@TabView], where each page can have a different background. + +`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the +shadow is replaced with a more subtle border. This can be useful for +applications like image viewers. + +See also [method@ToolbarView.set_top_bar_style]. + a timed animation - + filename="src/adw-toolbar-view.c" + line="1052">a toolbar view + - + whether @self alternates - + filename="src/adw-toolbar-view.c" + line="1053">bottom bar style + - - + Sets the duration of @self. - -If the animation repeats more than once, sets the duration of one iteration. - + filename="src/adw-toolbar-view.c" + line="823">Sets the content widget for @self. + a timed animation - + filename="src/adw-toolbar-view.c" + line="825">a toolbar view + - + the duration to use, in milliseconds - + filename="src/adw-toolbar-view.c" + line="826">the content widget + - - + Sets the easing function @self will use. + filename="src/adw-toolbar-view.c" + line="1290">Sets whether the content widget can extend behind bottom bars. -See [enum@Easing] for the description of specific easing functions. - +This can be used in combination with [property@ToolbarView:reveal-bottom-bars] +to show and hide toolbars in fullscreen. + +See [method@ToolbarView.set_extend_content_to_top_edge]. + a timed animation - + filename="src/adw-toolbar-view.c" + line="1292">a toolbar view + - + the easing function to use - + filename="src/adw-toolbar-view.c" + line="1293">whether content extends behind bottom bars + - - + Sets the number of times @self will play. + filename="src/adw-toolbar-view.c" + line="1238">Sets whether the content widget can extend behind top bars. -If set to 0, @self will repeat endlessly. - +This can be used in combination with [property@ToolbarView:reveal-top-bars] +to show and hide toolbars in fullscreen. + +See [method@ToolbarView.set_extend_content_to_bottom_edge]. + a timed animation - + filename="src/adw-toolbar-view.c" + line="1240">a toolbar view + - + the number of times @self will play - + filename="src/adw-toolbar-view.c" + line="1241">whether content extends behind top bars + - - + Sets whether @self plays backwards. - + filename="src/adw-toolbar-view.c" + line="1187">Sets whether bottom bars are revealed for @self. + +The transition will be animated. + +This can be used in combination with +[property@ToolbarView:extend-content-to-bottom-edge] to show and hide +toolbars in fullscreen. + +See [method@ToolbarView.set_reveal_top_bars]. + a timed animation - + filename="src/adw-toolbar-view.c" + line="1189">a toolbar view + - + whether @self plays backwards + filename="src/adw-toolbar-view.c" + line="1190">whether to reveal bottom bars - - + Sets the value @self will animate from. + filename="src/adw-toolbar-view.c" + line="1136">Sets whether top bars are revealed for @self. -The animation will start at this value and end at -[property@TimedAnimation:value-to]. +The transition will be animated. -If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at -this value instead. - +This can be used in combination with +[property@ToolbarView:extend-content-to-top-edge] to show and hide toolbars +in fullscreen. + +See [method@ToolbarView.set_reveal_bottom_bars]. + a timed animation - + filename="src/adw-toolbar-view.c" + line="1138">a toolbar view + - + the value to animate from - + filename="src/adw-toolbar-view.c" + line="1139">whether to reveal top bars + - - + Sets the value @self will animate to. + filename="src/adw-toolbar-view.c" + line="964">Sets appearance of the top bars for @self. -The animation will start at [property@TimedAnimation:value-from] and end at -this value. +If set to `ADW_TOOLBAR_FLAT`, top bars are flat and scrolling content has a +subtle undershoot shadow when touching them, same as the +[`.undershoot-top`](style-classes.html#undershoot-indicators) +style class. This works well for simple content, e.g. [class@StatusPage] or +[class@PreferencesPage], where the background at the top of the page is +uniform. Additionally, windows with sidebars should always use this style. -If [property@TimedAnimation:reverse] is `TRUE`, the animation will start -at this value instead. - +Undershoot shadow is only present if a top bar is actually present and +visible. It is also never present if +[property@ToolbarView:extend-content-to-top-edge] is set to `TRUE`. + +If set to `ADW_TOOLBAR_RAISED`, top bars have an opaque background and a +persistent shadow, this is suitable for content such as +[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +where some elements are directly adjacent to the top bars, or +[class@TabView], where each page can have a different background. + +`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the +shadow is replaced with a more subtle border. This can be useful for +applications like image viewers. + +See also [method@ToolbarView.set_bottom_bar_style]. + a timed animation - + filename="src/adw-toolbar-view.c" + line="966">a toolbar view + - + the value to animate to - + filename="src/adw-toolbar-view.c" + line="967">top bar style + - + The current bottom bar height. + +Bottom bar height does change depending on +[property@ToolbarView:reveal-bottom-bars], including during the transition. + +See [property@ToolbarView:top-bar-height]. + + + - - + setter="set_bottom_bar_style" + getter="get_bottom_bar_style" + default-value="ADW_TOOLBAR_FLAT"> Whether the animation changes direction on every iteration. - + filename="src/adw-toolbar-view.c" + line="574">Appearance of the bottom bars. + +If set to `ADW_TOOLBAR_FLAT`, bottom bars are flat and scrolling content +has a subtle undershoot shadow when touching them, same as the +[`.undershoot-bottom`](style-classes.html#undershoot-indicators) +style class. This works well for simple content, e.g. [class@StatusPage] or +[class@PreferencesPage], where the background at the bottom of the page is +uniform. Additionally, windows with sidebars should always use this style. + +Undershoot shadow is only present if a bottom bar is actually present and +visible. It is also never present if +[property@ToolbarView:extend-content-to-bottom-edge] is set to `TRUE`. + +If set to `ADW_TOOLBAR_RAISED`, bottom bars have an opaque background and a +persistent shadow, this is suitable for content such as +[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +where some elements are directly adjacent to the bottom bars, or +[class@TabView], where each page can have a different background. + +`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the +shadow is replaced with a more subtle border. This can be useful for +applications like image viewers. + +See also [property@ToolbarView:top-bar-style]. + - - - + setter="set_content" + getter="get_content"> Duration of the animation, in milliseconds. + filename="src/adw-toolbar-view.c" + line="526">The content widget. + + + + Whether the content widget can extend behind bottom bars. -Describes how much time the animation will take. +This can be used in combination with +[property@ToolbarView:reveal-bottom-bars] to show and hide toolbars in +fullscreen. -If the animation repeats more than once, describes the duration of one -iteration. - +See [property@ToolbarView:extend-content-to-top-edge]. + - - - + setter="set_extend_content_to_top_edge" + getter="get_extend_content_to_top_edge" + default-value="FALSE"> Easing function used in the animation. + filename="src/adw-toolbar-view.c" + line="650">Whether the content widget can extend behind top bars. -Describes the curve the value is interpolated on. +This can be used in combination with [property@ToolbarView:reveal-top-bars] +to show and hide toolbars in fullscreen. -See [enum@Easing] for the description of specific easing functions. - +See [property@ToolbarView:extend-content-to-bottom-edge]. + - - - + setter="set_reveal_bottom_bars" + getter="get_reveal_bottom_bars" + default-value="TRUE"> Number of times the animation will play. + filename="src/adw-toolbar-view.c" + line="630">Whether bottom bars are visible. -If set to 0, the animation will repeat endlessly. - +The transition will be animated. + +This can be used in combination with +[property@ToolbarView:extend-content-to-bottom-edge] to show and hide +toolbars in fullscreen. + +See [property@ToolbarView:reveal-top-bars]. + - - - + setter="set_reveal_top_bars" + getter="get_reveal_top_bars" + default-value="TRUE"> Whether the animation plays backwards. + filename="src/adw-toolbar-view.c" + line="610">Whether top bars are revealed. + +The transition will be animated. + +This can be used in combination with +[property@ToolbarView:extend-content-to-top-edge] to show and hide toolbars +in fullscreen. + +See [property@ToolbarView:reveal-bottom-bars]. - - - + getter="get_top_bar_height" + default-value="0"> The value to animate from. + filename="src/adw-toolbar-view.c" + line="685">The current top bar height. -The animation will start at this value and end at -[property@TimedAnimation:value-to]. +Top bar height does change depending [property@ToolbarView:reveal-top-bars], +including during the transition. -If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at -this value instead. - +See [property@ToolbarView:bottom-bar-height]. + - - - + setter="set_top_bar_style" + getter="get_top_bar_style" + default-value="ADW_TOOLBAR_FLAT"> The value to animate to. + filename="src/adw-toolbar-view.c" + line="538">Appearance of the top bars. -The animation will start at [property@TimedAnimation:value-from] and end at -this value. +If set to `ADW_TOOLBAR_FLAT`, top bars are flat and scrolling content has a +subtle undershoot shadow when touching them, same as the +[`.undershoot-top`](style-classes.html#undershoot-indicators) +style class. This works well for simple content, e.g. [class@StatusPage] or +[class@PreferencesPage], where the background at the top of the page is +uniform. Additionally, windows with sidebars should always use this style. -If [property@TimedAnimation:reverse] is `TRUE`, the animation will start -at this value instead. - +Undershoot shadow is only present if a top bar is actually present and +visible. It is also never present if +[property@ToolbarView:extend-content-to-top-edge] is set to `TRUE`. + +If set to `ADW_TOOLBAR_RAISED`, top bars have an opaque background and a +persistent shadow, this is suitable for content such as +[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +where some elements are directly adjacent to the top bars, or +[class@TabView], where each page can have a different background. + +`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the +shadow is replaced with a more subtle border. This can be useful for +applications like image viewers. + +See also [property@ToolbarView:bottom-bar-style]. + - - + + + + + - + + + + + + + + + + Adwaita version, encoded as a string, useful for printing and +concatenation. + + + + + glib:type-name="AdwViewStack" + glib:get-type="adw_view_stack_get_type" + glib:type-struct="ViewStackClass"> A helper object for [class@ToastOverlay]. - -Toasts are meant to be passed into [method@ToastOverlay.add_toast] as -follows: - -```c -adw_toast_overlay_add_toast (overlay, adw_toast_new (_("Simple Toast"))); -``` - -<picture> - <source srcset="toast-simple-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toast-simple.png" alt="toast-simple"> -</picture> - -Toasts always have a close button. They emit the [signal@Toast::dismissed] -signal when disappearing. + filename="src/adw-view-stack.c" + line="22">A view container for [class@ViewSwitcher]. -[property@Toast:timeout] determines how long the toast stays on screen, while -[property@Toast:priority] determines how it behaves if another toast is -already being displayed. +`AdwViewStack` is a container which only shows one page at a time. +It is typically used to hold an application's main views. -Toast titles use Pango markup by default, set [property@Toast:use-markup] to -`FALSE` if this is unwanted. +It doesn't provide a way to transition between pages. +Instead, a separate widget such as [class@ViewSwitcher] can be used with +`AdwViewStack` to provide this functionality. -[property@Toast:custom-title] can be used to replace the title label with a -custom widget. +`AdwViewStack` pages can have a title, an icon, an attention request, and a +numbered badge that [class@ViewSwitcher] will use to let users identify which +page is which. Set them using the [property@ViewStackPage:title], +[property@ViewStackPage:icon-name], +[property@ViewStackPage:needs-attention], and +[property@ViewStackPage:badge-number] properties. -## Actions +Unlike [class@Gtk.Stack], transitions between views can only be animated via +a crossfade and size changes are always interpolated. Animations are disabled +by default. Use [property@ViewStack:enable-transitions] to enable them. -Toasts can have one button on them, with a label and an attached -[iface@Gio.Action]. +`AdwViewStack` maintains a [class@ViewStackPage] object for each added child, +which holds additional per-child properties. You obtain the +[class@ViewStackPage] for a child with [method@ViewStack.get_page] and you +can obtain a [iface@Gtk.SelectionModel] containing all the pages with +[method@ViewStack.get_pages]. -```c -AdwToast *toast = adw_toast_new (_("Toast with Action")); +## AdwViewStack as GtkBuildable -adw_toast_set_button_label (toast, _("_Example")); -adw_toast_set_action_name (toast, "win.example"); +To set child-specific properties in a .ui file, create +[class@ViewStackPage] objects explicitly, and set the child widget as a +property on it: -adw_toast_overlay_add_toast (overlay, toast); +```xml + <object class="AdwViewStack" id="stack"> + <child> + <object class="AdwViewStackPage"> + <property name="name">overview</property> + <property name="title">Overview</property> + <property name="child"> + <object class="AdwStatusPage"> + <property name="title">Welcome!</property> + </object> + </property> + </object> + </child> + </object> ``` -<picture> - <source srcset="toast-action-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toast-action.png" alt="toast-action"> -</picture> - -## Modifying toasts - -Toasts can be modified after they have been shown. For this, an `AdwToast` -reference must be kept around while the toast is visible. - -A common use case for this is using toasts as undo prompts that stack with -each other, allowing to batch undo the last deleted items: - -```c - -static void -toast_undo_cb (GtkWidget *sender, - const char *action, - GVariant *param) -{ - // Undo the deletion -} - -static void -dismissed_cb (MyWindow *self) -{ - self->undo_toast = NULL; - - // Permanently delete the items -} - -static void -delete_item (MyWindow *self, - MyItem *item) -{ - g_autofree char *title = NULL; - int n_items; - - // Mark the item as waiting for deletion - n_items = ... // The number of waiting items - - if (!self->undo_toast) { - self->undo_toast = adw_toast_new_format (_("‘%s’ deleted"), ...); - - adw_toast_set_priority (self->undo_toast, ADW_TOAST_PRIORITY_HIGH); - adw_toast_set_button_label (self->undo_toast, _("_Undo")); - adw_toast_set_action_name (self->undo_toast, "toast.undo"); - - g_signal_connect_swapped (self->undo_toast, "dismissed", - G_CALLBACK (dismissed_cb), self); - - adw_toast_overlay_add_toast (self->toast_overlay, self->undo_toast); - - return; - } - - title = - g_strdup_printf (ngettext ("<span font_features='tnum=1'>%d</span> item deleted", - "<span font_features='tnum=1'>%d</span> items deleted", - n_items), n_items); - - adw_toast_set_title (self->undo_toast, title); - - // Bump the toast timeout - adw_toast_overlay_add_toast (self->toast_overlay, g_object_ref (self->undo_toast)); -} +## CSS nodes -static void -my_window_class_init (MyWindowClass *klass) -{ - GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass); +`AdwViewStack` has a single CSS node named `stack`. - gtk_widget_class_install_action (widget_class, "toast.undo", NULL, toast_undo_cb); -} -``` +## Accessibility -<picture> - <source srcset="toast-undo-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toast-undo.png" alt="toast-undo"> -</picture> - - +`AdwViewStack` uses the `GTK_ACCESSIBLE_ROLE_TAB_PANEL` for the stack pages +which are the accessible parent objects of the child widgets. + + + + + Creates a new `AdwToast`. - -The toast will use @title as its title. - -@title can be marked up with the Pango text markup language. - - + filename="src/adw-view-stack.c" + line="1875">Creates a new `AdwViewStack`. + + the new created `AdwToast` - + filename="src/adw-view-stack.c" + line="1880">the newly created `AdwViewStack` + - - - the title to be displayed - - - - + Creates a new `AdwToast`. - -The toast will use the format string as its title. - -See also: [ctor@Toast.new] - - + filename="src/adw-view-stack.c" + line="1888">Adds a child to @self. + + the newly created toast object - + filename="src/adw-view-stack.c" + line="1895">the [class@ViewStackPage] for @child + - + the formatted string for the toast title - - - + filename="src/adw-view-stack.c" + line="1890">a view stack + + + the parameters to insert into the format string - + filename="src/adw-view-stack.c" + line="1891">the widget to add + - - + + Dismisses @self. + filename="src/adw-view-stack.c" + line="1908">Adds a child to @self. -Does nothing if @self has already been dismissed, or hasn't been added to an -[class@ToastOverlay]. - +The child is identified by the @name. + - + the `AdwViewStackPage` for @child + a toast - + filename="src/adw-view-stack.c" + line="1910">a view stack + + + the widget to add + + + + the name for @child + + - - + Gets the name of the associated action. - - + filename="src/adw-view-stack.c" + line="1932">Adds a child to @self. + +The child is identified by the @name. The @title will be used by +[class@ViewSwitcher] to represent @child, so it should be short. + + the action name - + filename="src/adw-view-stack.c" + line="1944">the `AdwViewStackPage` for @child + a toast - + filename="src/adw-view-stack.c" + line="1934">a view stack + + + the widget to add + + + + the name for @child + + + + a human-readable title for @child + + - - + Gets the parameter for action invocations. - - + filename="src/adw-view-stack.c" + line="1959">Adds a child to @self. + +The child is identified by the @name. The @title and @icon_name will be used +by [class@ViewSwitcher] to represent @child. + + the action target - + filename="src/adw-view-stack.c" + line="1972">the `AdwViewStackPage` for @child + a toast - + filename="src/adw-view-stack.c" + line="1961">a view stack + + + the widget to add + + + + the name for @child + + + + a human-readable title for @child + + + + an icon name for @child + + - - + Gets the label to show on the button. - + filename="src/adw-view-stack.c" + line="2040">Finds the child with @name in @self. + the button label - + filename="src/adw-view-stack.c" + line="2047">the requested child + a toast - + filename="src/adw-view-stack.c" + line="2042">a view stack + + + the name of the child to find + + - - + Gets the custom title widget of @self. - - + filename="src/adw-view-stack.c" + line="2251">Gets whether @self uses a crossfade transition between pages. + +Use [property@ViewStack:transition-duration] to control the duration, and +[property@ViewStack:transition-running] to know when the transition is +running. + + the custom title widget - + filename="src/adw-view-stack.c" + line="2261">whether to enable page transitions + a toast - + filename="src/adw-view-stack.c" + line="2253">a view stack + - - + Gets priority for @self. - + filename="src/adw-view-stack.c" + line="2155">Gets whether @self is horizontally homogeneous. + the priority - + filename="src/adw-view-stack.c" + line="2161">whether @self is horizontally homogeneous + a toast - + filename="src/adw-view-stack.c" + line="2157">a view stack + - - + Gets timeout for @self. - + filename="src/adw-view-stack.c" + line="2021">Gets the [class@ViewStackPage] object for @child. + the timeout - + filename="src/adw-view-stack.c" + line="2028">the page object for @child + a toast - + filename="src/adw-view-stack.c" + line="2023">a view stack + + + a child of @self + + - - + Gets the title that will be displayed on the toast. + filename="src/adw-view-stack.c" + line="2377">Returns a [iface@Gio.ListModel] that contains the pages of the stack. -If a custom title has been set with [method@Adw.Toast.set_custom_title] -the return value will be %NULL. - - +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the visible +page. + + the title - + filename="src/adw-view-stack.c" + line="2387">a `GtkSelectionModel` for the stack's children + a toast - + filename="src/adw-view-stack.c" + line="2379">a view stack + - - + Gets whether to use Pango markup for the toast title. - + filename="src/adw-view-stack.c" + line="2305">Gets the transition animation duration for @self. + whether the toast uses markup - + filename="src/adw-view-stack.c" + line="2311">the transition duration, in milliseconds + a toast - + filename="src/adw-view-stack.c" + line="2307">a view stack + - - + Sets the name of the associated action. - -It will be activated when clicking the button. + filename="src/adw-view-stack.c" + line="2355">Gets whether a transition is currently running for @self. -See [property@Toast:action-target]. - +If a transition is impossible, the property value will be set to `TRUE` and +then immediately to `FALSE`, so it's possible to rely on its notifications +to know that a transition has happened. + - + whether a transition is currently running + a toast - + filename="src/adw-view-stack.c" + line="2357">a view stack + - - the action name - - - + Sets the parameter for action invocations. - -This is a convenience function that calls [ctor@GLib.Variant.new] for -@format_string and uses the result to call -[method@Toast.set_action_target_value]. - -If you are setting a string-valued target and want to set -the action name at the same time, you can use -[method@Toast.set_detailed_action_name]. - + filename="src/adw-view-stack.c" + line="2203">Gets whether @self is vertically homogeneous. + - + whether @self is vertically homogeneous + a toast - + filename="src/adw-view-stack.c" + line="2205">a view stack + - - a variant format string - - - - arguments appropriate for @target_format - - - - + Sets the parameter for action invocations. - -If the @action_target variant has a floating reference this function -will sink it. - - - + filename="src/adw-view-stack.c" + line="2063">Gets the currently visible child of @self. + + + the visible child + a toast - + filename="src/adw-view-stack.c" + line="2065">a view stack + - + + + + Returns the name of the currently visible child of @self. + + + the name of the visible child + + + + the action target - - + filename="src/adw-view-stack.c" + line="2109">a view stack + + - - + Sets the label to show on the button. - -Underlines in the button text can be used to indicate a mnemonic. - -If set to `NULL`, the button won't be shown. - -See [property@Toast:action-name]. - + filename="src/adw-view-stack.c" + line="1990">Removes a child widget from @self. + a toast - + filename="src/adw-view-stack.c" + line="1992">a view stack + - + a button label - + filename="src/adw-view-stack.c" + line="1993">the child to remove + - - + Sets the custom title widget of @self. - -It will be displayed instead of the title if set. In this case, -[property@Toast:title] is ignored. - -Setting a custom title will unset [property@Toast:title]. - + filename="src/adw-view-stack.c" + line="2273">Sets whether @self uses a crossfade transition between pages. + a toast - + filename="src/adw-view-stack.c" + line="2275">a view stack + - + the custom title widget - + filename="src/adw-view-stack.c" + line="2276">whether to enable page transitions + - + Sets the action name and its parameter. + filename="src/adw-view-stack.c" + line="2171">Sets @self to be horizontally homogeneous or not. -@detailed_action_name is a string in the format accepted by -[func@Gio.Action.parse_detailed_name]. - +If the stack is horizontally homogeneous, it allocates the same width for +all children. + +If it's `FALSE`, the stack may change width when a different child becomes +visible. + a toast - + filename="src/adw-view-stack.c" + line="2173">a view stack + - + the detailed action name - + filename="src/adw-view-stack.c" + line="2174">whether to make @self horizontally homogeneous + - - + Sets priority for @self. - -Priority controls how the toast behaves when another toast is already -being displayed. - -If @priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued. + filename="src/adw-view-stack.c" + line="2323">Sets the transition animation duration for @self. -If @priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed -immediately, pushing the previous toast into the queue instead. - +Only used when [property@ViewStack:enable-transitions] is set to `TRUE`. + a toast - + filename="src/adw-view-stack.c" + line="2325">a view stack + - + the priority - + filename="src/adw-view-stack.c" + line="2326">the new duration, in milliseconds + - - + Sets timeout for @self. + filename="src/adw-view-stack.c" + line="2219">Sets @self to be vertically homogeneous or not. -If @timeout is 0, the toast is displayed indefinitely until manually -dismissed. +If the stack is vertically homogeneous, it allocates the same height for +all children. -Toasts cannot disappear while being hovered, pressed (on touchscreen), or -have keyboard focus inside them. - +If it's `FALSE`, the stack may change height when a different child becomes +visible. + a toast - + filename="src/adw-view-stack.c" + line="2221">a view stack + - + the timeout - + filename="src/adw-view-stack.c" + line="2222">whether to make @self vertically homogeneous + - - + Sets the title that will be displayed on the toast. - -The title can be marked up with the Pango text markup language. - -Setting a title will unset [property@Toast:custom-title]. - -If [property@Toast:custom-title] is set, it will be used instead. - + filename="src/adw-view-stack.c" + line="2079">Makes @child the visible child of @self. + a toast - + filename="src/adw-view-stack.c" + line="2081">a view stack + - + a title - + filename="src/adw-view-stack.c" + line="2082">a child of @self + - - + Whether to use Pango markup for the toast title. + filename="src/adw-view-stack.c" + line="2123">Makes the child with @name visible. -See also [func@Pango.parse_markup]. - +See [property@ViewStack:visible-child]. + a toast - + filename="src/adw-view-stack.c" + line="2125">a view stack + - + whether to use markup - + filename="src/adw-view-stack.c" + line="2126">the name of the child + - - - - The name of the associated action. - -It will be activated when clicking the button. - -See [property@Toast:action-target]. - - - - - - The parameter for action invocations. - - - - - + setter="set_enable_transitions" + getter="get_enable_transitions" + default-value="FALSE"> The label to show on the button. - -Underlines in the button text can be used to indicate a mnemonic. - -If set to `NULL`, the button won't be shown. + filename="src/adw-view-stack.c" + line="1432">Whether the stack uses a crossfade transition between pages. -See [property@Toast:action-name]. - +Use [property@ViewStack:transition-duration] to control the duration, and +[property@ViewStack:transition-running] to know when the transition is +running. + - - - + setter="set_hhomogeneous" + getter="get_hhomogeneous" + default-value="TRUE"> The custom title widget. + filename="src/adw-view-stack.c" + line="1378">Whether the stack is horizontally homogeneous. -It will be displayed instead of the title if set. In this case, -[property@Toast:title] is ignored. +If the stack is horizontally homogeneous, it allocates the same width for +all children. -Setting a custom title will unset [property@Toast:title]. - +If it's `FALSE`, the stack may change width when a different child becomes +visible. + - - - + The priority of the toast. - -Priority controls how the toast behaves when another toast is already -being displayed. - -If the priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued. + filename="src/adw-view-stack.c" + line="1478">A selection model with the stack's pages. -If the priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed -immediately, pushing the previous toast into the queue instead. - +This can be used to keep an up-to-date view. The model also implements +[iface@Gtk.SelectionModel] and can be used to track and change the visible +page. + - - - + setter="set_transition_duration" + getter="get_transition_duration" + default-value="200"> The timeout of the toast, in seconds. - -If timeout is 0, the toast is displayed indefinitely until manually -dismissed. + filename="src/adw-view-stack.c" + line="1448">The transition animation duration, in milliseconds. -Toasts cannot disappear while being hovered, pressed (on touchscreen), or -have keyboard focus inside them. +Only used when [property@ViewStack:enable-transitions] is set to `TRUE`. - - - + getter="get_transition_running" + default-value="FALSE"> The title of the toast. - -The title can be marked up with the Pango text markup language. - -Setting a title will unset [property@Toast:custom-title]. + filename="src/adw-view-stack.c" + line="1462">Whether a transition is currently running. -If [property@Toast:custom-title] is set, it will be used instead. - +If a transition is impossible, the property value will be set to `TRUE` and +then immediately to `FALSE`, so it's possible to rely on its notifications +to know that a transition has happened. + - - - Whether to use Pango markup for the toast title. + filename="src/adw-view-stack.c" + line="1394">Whether the stack is vertically homogeneous. -See also [func@Pango.parse_markup]. +If the stack is vertically homogeneous, it allocates the same height for +all children. + +If it's `FALSE`, the stack may change height when a different child becomes +visible. - + Emitted after the button has been clicked. - -It can be used as an alternative to setting an action. - - - - - + filename="src/adw-view-stack.c" + line="1410">The widget currently visible in the stack. + + + Emitted when the toast has been dismissed. - - - - + filename="src/adw-view-stack.c" + line="1420">The name of the widget currently visible in the stack. + +See [property@ViewStack:visible-child]. + + - - + + - + - + glib:type-name="AdwViewStackPage" + glib:get-type="adw_view_stack_page_get_type" + glib:type-struct="ViewStackPageClass"> A widget showing toasts above its content. - -<picture> - <source srcset="toast-overlay-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toast-overlay.png" alt="toast-overlay"> -</picture> - -Much like [class@Gtk.Overlay], `AdwToastOverlay` is a container with a single -main child, on top of which it can display a [class@Toast], overlaid. -Toasts can be shown with [method@ToastOverlay.add_toast]. - -See [class@Toast] for details. - -## CSS nodes - -``` -toastoverlay -├── [child] -├── toast -┊ ├── widget -┊ │ ├── [label.heading] - │ ╰── [custom title] - ├── [button] - ╰── button.circular.flat -``` - -`AdwToastOverlay`'s CSS node is called `toastoverlay`. It contains the child, -as well as zero or more `toast` subnodes. - -Each of the `toast` nodes contains a `widget` subnode, optionally a `button` -subnode, and another `button` subnode with `.circular` and `.flat` style -classes. - -The `widget` subnode contains a `label` subnode with the `.heading` style -class, or a custom widget provided by the application. - -## Accessibility - -`AdwToastOverlay` uses the `GTK_ACCESSIBLE_ROLE_TAB_GROUP` role. - + filename="src/adw-view-stack.c" + line="83">An auxiliary class used by [class@ViewStack]. + - - - + Creates a new `AdwToastOverlay`. - + filename="src/adw-view-stack.c" + line="1785">Gets the badge number for this page. + the new created `AdwToastOverlay` - - - - - Displays @toast. - -Only one toast can be shown at a time; if a toast is already being displayed, -either @toast or the original toast will be placed in a queue, depending on -the priority of @toast. See [property@Toast:priority]. - -If called on a toast that's already displayed, its timeout will be reset. - -If called on a toast currently in the queue, the toast will be bumped -forward to be shown as soon as possible. - - - + filename="src/adw-view-stack.c" + line="1791">the badge number for this page + a toast overlay - + filename="src/adw-view-stack.c" + line="1787">a view stack page + - - a toast - - - Gets the child widget of @self. - - + filename="src/adw-view-stack.c" + line="1558">Gets the stack child to which @self belongs. + + the child widget of @self + filename="src/adw-view-stack.c" + line="1564">the child to which @self belongs a toast overlay - + filename="src/adw-view-stack.c" + line="1560">a view stack page + - - + Sets the child widget of @self. - - - + filename="src/adw-view-stack.c" + line="1709">Gets the icon name of the page. + + + the icon name of the page + a toast overlay - + filename="src/adw-view-stack.c" + line="1711">a view stack page + - - the child widget - - - - - - The child widget. - - - - - - - - - - - [class@Toast] behavior when another toast is already displayed. - - the toast will be queued if another toast is - already displayed. - - - the toast will be displayed immediately, pushing - the previous toast into the queue instead. - - - - Describes the possible top or bottom bar styles in an [class@ToolbarView] -widget. - -`ADW_TOOLBAR_FLAT` is suitable for simple content, such as -[class@StatusPage] or [class@PreferencesPage], where the background at the -top and bottom parts of the page is uniform. Additionally, windows with -sidebars should always use this style. - -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1"> -</picture> -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2"> -</picture> - -`ADW_TOOLBAR_RAISED` style is suitable for content such as -[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), -where some elements are directly adjacent to the top/bottom bars, or -[class@TabView], where each page can have a different background. - -`ADW_TOOLBAR_RAISED_BORDER` style is similar to `ADW_TOOLBAR_RAISED`, but -with the shadow replaced with a more subtle border. It's intended to be used -in applications like image viewers, where a shadow over the content might be -undesired. - -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-raised.png" alt="toolbar-view-raised"> -</picture> -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-raised-border-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-raised-border.png" alt="toolbar-view-raised-border"> -</picture> - -See [property@ToolbarView:top-bar-style] and -[property@ToolbarView:bottom-bar-style]. - -New values may be added to this enumeration over time. - - No background, shadow only for scrolled content - - - Opaque background with a persistent shadow - - + Opaque background with a persistent border - - - - A widget containing a page, as well as top and/or bottom bars. - -<picture> - <source srcset="toolbar-view-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view.png" alt="toolbar-view"> -</picture> - -`AdwToolbarView` has a single content widget and one or multiple top and -bottom bars, shown at the top and bottom sides respectively. - -Example of an `AdwToolbarView` UI definition: -```xml -<object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"/> - </child> - <property name="content"> - <object class="AdwPreferencesPage"> - <!-- ... --> - </object> - </property> -</object> -``` - -The following kinds of top and bottom bars are supported: - -- [class@HeaderBar] -- [class@TabBar] -- [class@ViewSwitcherBar] -- [class@Gtk.ActionBar] -- [class@Gtk.HeaderBar] -- [class@Gtk.PopoverMenuBar] -- [class@Gtk.SearchBar] -- Any [class@Gtk.Box] or a similar widget with the - [`.toolbar`](style-classes.html#toolbars) style class - -By default, top and bottom bars are flat and scrolling content has a subtle -undershoot shadow, same as when using the -[`.undershoot-top`](style-classes.html#undershot-indicators) and -[`.undershoot-bottom`](style-classes.html#undershot-indicators) style -classes. This works well in most cases, e.g. with [class@StatusPage] or -[class@PreferencesPage], where the background at the top and bottom parts of -the page is uniform. Additionally, windows with sidebars should always use -this style. - -[property@ToolbarView:top-bar-style] and -[property@ToolbarView:bottom-bar-style] properties can be used add an opaque -background and a persistent shadow to top and bottom bars, this can be useful -for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), -where some elements are adjacent to the top/bottom bars, or [class@TabView], -where each page can have a different background. - -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1"> -</picture> -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2"> -</picture> -<picture style="min-width: 33%; display: inline-block;"> - <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-raised.png" alt="toolbar-view-raised"> -</picture> - -`AdwToolbarView` ensures the top and bottom bars have consistent backdrop -styles and vertical spacing. For comparison: - -<picture style="min-width: 40%; display: inline-block;"> - <source srcset="toolbar-view-spacing-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-spacing.png" alt="toolbar-view-spacing"> -</picture> -<picture style="min-width: 40%; display: inline-block;"> - <source srcset="toolbar-view-spacing-box-dark.png" media="(prefers-color-scheme: dark)"> - <img src="toolbar-view-spacing-box.png" alt="toolbar-view-spacing-box"> -</picture> - -Any top and bottom bars can also be dragged to move the window, equivalent -to putting them into a [class@Gtk.WindowHandle]. - -Content is typically place between top and bottom bars, but can also extend -behind them. This is controlled with the -[property@ToolbarView:extend-content-to-top-edge] and -[property@ToolbarView:extend-content-to-bottom-edge] properties. - -Top and bottom bars can be hidden and revealed with an animation using the -[property@ToolbarView:reveal-top-bars] and -[property@ToolbarView:reveal-bottom-bars] properties. - -## `AdwToolbarView` as `GtkBuildable` - -The `AdwToolbarView` implementation of the [iface@Gtk.Buildable] interface -supports adding a top bar by specifying “top” as the “type” attribute of a -`<child>` element, or adding a bottom bar by specifying “bottom”. - -## Accessibility - -`AdwToolbarView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. - - - - - + filename="src/adw-view-stack.c" + line="1574">Gets the name of the page. + + + the name of the page + + + + + a view stack page + + + + + Creates a new `AdwToolbarView`. - + filename="src/adw-view-stack.c" + line="1744">Gets whether the page requires the user attention. + the newly created `AdwToolbarView` - + filename="src/adw-view-stack.c" + line="1750">whether the page needs attention + - - + + + a view stack page + + + + + Adds a bottom bar to @self. - - - + filename="src/adw-view-stack.c" + line="1635">Gets the page title. + + + the page title + a toolbar view - + filename="src/adw-view-stack.c" + line="1637">a view stack page + - - a widget - - - + Adds a top bar to @self. - + filename="src/adw-view-stack.c" + line="1674">Gets whether underlines in the page title indicate mnemonics. + - + whether underlines in the page title indicate mnemonics + a toolbar view - + filename="src/adw-view-stack.c" + line="1676">a view stack page + - - a widget - - - - + Gets the current bottom bar height for @self. - -Bottom bar height does change depending on -[property@ToolbarView:reveal-bottom-bars], including during the transition. + filename="src/adw-view-stack.c" + line="1827">Gets whether @self is visible in its `AdwViewStack`. -See [method@ToolbarView.get_top_bar_height]. - +This is independent from the [property@Gtk.Widget:visible] +property of its widget. + the current bottom bar height - + filename="src/adw-view-stack.c" + line="1836">whether @self is visible + a toolbar view - + filename="src/adw-view-stack.c" + line="1829">a view stack page + - - + Gets appearance of the botom bars for @self. - + filename="src/adw-view-stack.c" + line="1801">Sets the badge number for this page. + +[class@ViewSwitcher] can display it as a badge next to the page icon. It is +commonly used to display a number of unread items within the page. + +It can be used together with [property@ViewStack{age}:needs-attention]. + - bottom bar style - + a toolbar view - + filename="src/adw-view-stack.c" + line="1803">a view stack page + + + the new value to set + + - - + Gets the content widget for @self. - - - the content widget - + filename="src/adw-view-stack.c" + line="1725">Sets the icon name of the page. + + + a toolbar view - + filename="src/adw-view-stack.c" + line="1727">a view stack page + + + the icon name + + - - + Gets whether the content widget can extend behind bottom bars. - + filename="src/adw-view-stack.c" + line="1590">Sets the name of the page. + - whether content extends behind bottom bars - + a toolbar view - + filename="src/adw-view-stack.c" + line="1592">a view stack page + + + the page name + + - - + Gets whether the content widget can extend behind top bars. - + filename="src/adw-view-stack.c" + line="1760">Sets whether the page requires the user attention. + +[class@ViewSwitcher] will display it as a dot next to the page icon. + - whether content extends behind top bars - + a toolbar view - + filename="src/adw-view-stack.c" + line="1762">a view stack page + + + the new value to set + + - - + Gets whether bottom bars are revealed for @self. - + filename="src/adw-view-stack.c" + line="1651">Sets the page title. + - whether bottom bars are revealed - + a toolbar view - + filename="src/adw-view-stack.c" + line="1653">a view stack page + + + the page title + + - - + Gets whether top bars are revealed for @self. - + filename="src/adw-view-stack.c" + line="1688">Sets whether underlines in the page title indicate mnemonics. + - whether top bars are revealed - + a toolbar view - + filename="src/adw-view-stack.c" + line="1690">a view stack page + + + the new value to set + + - - + Gets the current top bar height for @self. - -Top bar height does change depending on -[property@ToolbarView:reveal-top-bars], including during the transition. + filename="src/adw-view-stack.c" + line="1846">Sets whether @page is visible in its `AdwViewStack`. -See [method@ToolbarView.get_bottom_bar_height]. - +This is independent from the [property@Gtk.Widget:visible] property of +[property@ViewStackPage:child]. + - the current top bar height - + a toolbar view - + filename="src/adw-view-stack.c" + line="1848">a view stack page + + + whether @self is visible + + - + The badge number for this page. + +[class@ViewSwitcher] can display it as a badge next to the page icon. It is +commonly used to display a number of unread items within the page. + +It can be used together with [property@ViewStack{age}:needs-attention]. + + + + The stack child to which the page belongs. + + + + The icon name of the child page. + + + + The name of the child page. + + + + Whether the page requires the user attention. + +[class@ViewSwitcher] will display it as a dot next to the page icon. + + + + The title of the child page. + + + + Whether an embedded underline in the title indicates a mnemonic. + + + + Whether this page is visible. + +This is independent from the [property@Gtk.Widget:visible] property of +[property@ViewStackPage:child]. + + + + + + + + + + + An auxiliary class used by [class@ViewStack]. + +See [property@ViewStack:pages]. + + + + - Gets appearance of the top bars for @self. - - + filename="src/adw-view-stack.c" + line="593">Gets the [class@ViewStackPage] for the visible child of a view stack + +Gets the [class@ViewStackPage] for the visible child of the associated stack. + +Returns `NULL` if there's no selected page. + + top bar style - + filename="src/adw-view-stack.c" + line="603">the stack page + a toolbar view - + filename="src/adw-view-stack.c" + line="595">a [class@ViewStackPages] + - Removes a child from @self. - + filename="src/adw-view-stack.c" + line="623">Sets the visible child in the associated [class@ViewStack]. + +See [property@ViewStack:visible-child]. + a toolbar view - + filename="src/adw-view-stack.c" + line="625">a [class@ViewStackPages] + - + the child to be removed - + filename="src/adw-view-stack.c" + line="626">a stack page within the associated stack + - - + Sets appearance of the bottom bars for @self. + filename="src/adw-view-stack.c" + line="702">The selected [class@ViewStackPage] within the [class@ViewStackPages]. -If set to `ADW_TOOLBAR_FLAT`, bottom bars are flat and scrolling content has -a subtle undershoot shadow when touching them, same as the -[`.undershoot-bottom`](style-classes.html#undershot-indicators) -style class. This works well for simple content, e.g. [class@StatusPage] or -[class@PreferencesPage], where the background at the bottom of the page is -uniform. Additionally, windows with sidebars should always use this style. +This can be used to keep an up-to-date view of the [class@ViewStackPage] for +The visible [class@ViewStackPage] within the associated [class@ViewStackPages]. + +This can be used to keep an up-to-date view of the visible child. + + + + + + + + + + + An adaptive view switcher. + +<picture> + <source srcset="view-switcher-dark.png" media="(prefers-color-scheme: dark)"> + <img src="view-switcher.png" alt="view-switcher"> +</picture> + +An adaptive view switcher designed to switch between multiple views +contained in a [class@ViewStack] in a similar fashion to +[class@Gtk.StackSwitcher]. + +`AdwViewSwitcher` buttons always have an icon and a label. They can be +displayed side by side, or icon on top of the label. This can be controlled +via the [property@ViewSwitcher:policy] property. + +`AdwViewSwitcher` is intended to be used in a header bar together with +[class@ViewSwitcherBar] at the bottom of the window, and a [class@Breakpoint] +showing the view switcher bar on narrow sizes, while removing the view +switcher from the header bar, as follows: + +```xml +<object class="AdwWindow"> + <child> + <object class="AdwBreakpoint"> + <condition>max-width: 550sp</condition> + <setter object="switcher_bar" property="reveal">True</setter> + <setter object="header_bar" property="title-widget"/> + </object> + </child> + <property name="content"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar" id="header_bar"> + <property name="title-widget"> + <object class="AdwViewSwitcher"> + <property name="stack">stack</property> + <property name="policy">wide</property> + </object> + </property> + </object> + </child> + <property name="content"> + <object class="AdwViewStack" id="stack"/> + </property> + <child type="bottom"> + <object class="AdwViewSwitcherBar" id="switcher_bar"> + <property name="stack">stack</property> + </object> + </child> + </object> + </property> +</object> +``` -Undershoot shadow is only present if a bottom bar is actually present and -visible. It is also never present if -[property@ToolbarView:extend-content-to-bottom-edge] is set to `TRUE`. +It's recommended to set [property@ViewSwitcher:policy] to +`ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. -If set to `ADW_TOOLBAR_RAISED`, bottom bars have an opaque background and a -persistent shadow, this is suitable for content such as -[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), -where some elements are directly adjacent to the bottom bars, or -[class@TabView], where each page can have a different background. +You may have to adjust the breakpoint condition for your specific pages. -`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the -shadow is replaced with a more subtle border. This can be useful for -applications like image viewers. +## CSS nodes -See also [method@ToolbarView.set_top_bar_style]. - - - - - - - a toolbar view - - - - bottom bar style - - - - - - - Sets the content widget for @self. - - - - - - - a toolbar view - - - - the content widget - - - - - - - Sets whether the content widget can extend behind bottom bars. +`AdwViewSwitcher` has a single CSS node with name `viewswitcher`. It can have +the style classes `.wide` and `.narrow`, matching its policy. -This can be used in combination with [property@ToolbarView:reveal-bottom-bars] -to show and hide toolbars in fullscreen. +## Accessibility -See [method@ToolbarView.set_extend_content_to_top_edge]. - +`AdwViewSwitcher` uses the `GTK_ACCESSIBLE_ROLE_TAB_LIST` role and uses the +`GTK_ACCESSIBLE_ROLE_TAB` for its buttons. + + + + + + Creates a new `AdwViewSwitcher`. + - + the newly created `AdwViewSwitcher` + - - - a toolbar view - - - - whether content extends behind bottom bars - - - - - - + + Sets whether the content widget can extend behind top bars. - -This can be used in combination with [property@ToolbarView:reveal-top-bars] -to show and hide toolbars in fullscreen. - -See [method@ToolbarView.set_extend_content_to_bottom_edge]. - + filename="src/adw-view-switcher.c" + line="492">Gets the policy of @self. + - + the policy of @self + a toolbar view - + filename="src/adw-view-switcher.c" + line="494">a view switcher + - - whether content extends behind top bars - - - - + Sets whether bottom bars are revealed for @self. - -The transition will be animated. - -This can be used in combination with -[property@ToolbarView:extend-content-to-bottom-edge] to show and hide -toolbars in fullscreen. - -See [method@ToolbarView.set_reveal_top_bars]. - - - + filename="src/adw-view-switcher.c" + line="547">Gets the stack controlled by @self. + + + the stack + a toolbar view - + filename="src/adw-view-switcher.c" + line="549">a view switcher + - - whether to reveal bottom bars - - - - + Sets whether top bars are revealed for @self. - -The transition will be animated. - -This can be used in combination with -[property@ToolbarView:extend-content-to-top-edge] to show and hide toolbars -in fullscreen. - -See [method@ToolbarView.set_reveal_bottom_bars]. - + filename="src/adw-view-switcher.c" + line="508">Sets the policy of @self. + a toolbar view - + filename="src/adw-view-switcher.c" + line="510">a view switcher + - + whether to reveal top bars - + filename="src/adw-view-switcher.c" + line="511">the new policy + - - + Sets appearance of the top bars for @self. - -If set to `ADW_TOOLBAR_FLAT`, top bars are flat and scrolling content has a -subtle undershoot shadow when touching them, same as the -[`.undershoot-top`](style-classes.html#undershot-indicators) -style class. This works well for simple content, e.g. [class@StatusPage] or -[class@PreferencesPage], where the background at the top of the page is -uniform. Additionally, windows with sidebars should always use this style. - -Undershoot shadow is only present if a top bar is actually present and -visible. It is also never present if -[property@ToolbarView:extend-content-to-top-edge] is set to `TRUE`. - -If set to `ADW_TOOLBAR_RAISED`, top bars have an opaque background and a -persistent shadow, this is suitable for content such as -[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), -where some elements are directly adjacent to the top bars, or -[class@TabView], where each page can have a different background. - -`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the -shadow is replaced with a more subtle border. This can be useful for -applications like image viewers. - -See also [method@ToolbarView.set_bottom_bar_style]. - + filename="src/adw-view-switcher.c" + line="563">Sets the stack controlled by @self. + a toolbar view - + filename="src/adw-view-switcher.c" + line="565">a view switcher + - + top bar style - + filename="src/adw-view-switcher.c" + line="566">a stack + - - - The current bottom bar height. - -Bottom bar height does change depending on -[property@ToolbarView:reveal-bottom-bars], including during the transition. - -See [property@ToolbarView:top-bar-height]. - - - - - - Appearance of the bottom bars. - -If set to `ADW_TOOLBAR_FLAT`, bottom bars are flat and scrolling content -has a subtle undershoot shadow when touching them, same as the -[`.undershoot-bottom`](style-classes.html#undershot-indicators) -style class. This works well for simple content, e.g. [class@StatusPage] or -[class@PreferencesPage], where the background at the bottom of the page is -uniform. Additionally, windows with sidebars should always use this style. - -Undershoot shadow is only present if a bottom bar is actually present and -visible. It is also never present if -[property@ToolbarView:extend-content-to-bottom-edge] is set to `TRUE`. - -If set to `ADW_TOOLBAR_RAISED`, bottom bars have an opaque background and a -persistent shadow, this is suitable for content such as -[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), -where some elements are directly adjacent to the bottom bars, or -[class@TabView], where each page can have a different background. - -`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the -shadow is replaced with a more subtle border. This can be useful for -applications like image viewers. - -See also [property@ToolbarView:top-bar-style]. - - - - - - The content widget. - - - - - - Whether the content widget can extend behind bottom bars. - -This can be used in combination with -[property@ToolbarView:reveal-bottom-bars] to show and hide toolbars in -fullscreen. - -See [property@ToolbarView:extend-content-to-top-edge]. - - - - - - Whether the content widget can extend behind top bars. - -This can be used in combination with [property@ToolbarView:reveal-top-bars] -to show and hide toolbars in fullscreen. - -See [property@ToolbarView:extend-content-to-bottom-edge]. - - - - - - Whether bottom bars are visible. - -The transition will be animated. - -This can be used in combination with -[property@ToolbarView:extend-content-to-bottom-edge] to show and hide -toolbars in fullscreen. - -See [property@ToolbarView:reveal-top-bars]. - - - - - - Whether top bars are revealed. - -The transition will be animated. - -This can be used in combination with -[property@ToolbarView:extend-content-to-top-edge] to show and hide toolbars -in fullscreen. - -See [property@ToolbarView:reveal-bottom-bars]. - - - - + setter="set_policy" + getter="get_policy" + default-value="ADW_VIEW_SWITCHER_POLICY_NARROW"> The current top bar height. - -Top bar height does change depending [property@ToolbarView:reveal-top-bars], -including during the transition. - -See [property@ToolbarView:bottom-bar-height]. - + filename="src/adw-view-switcher.c" + line="439">The policy to determine which mode to use. + - - - + setter="set_stack" + getter="get_stack"> Appearance of the top bars. - -If set to `ADW_TOOLBAR_FLAT`, top bars are flat and scrolling content has a -subtle undershoot shadow when touching them, same as the -[`.undershoot-top`](style-classes.html#undershot-indicators) -style class. This works well for simple content, e.g. [class@StatusPage] or -[class@PreferencesPage], where the background at the top of the page is -uniform. Additionally, windows with sidebars should always use this style. - -Undershoot shadow is only present if a top bar is actually present and -visible. It is also never present if -[property@ToolbarView:extend-content-to-top-edge] is set to `TRUE`. - -If set to `ADW_TOOLBAR_RAISED`, top bars have an opaque background and a -persistent shadow, this is suitable for content such as -[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), -where some elements are directly adjacent to the top bars, or -[class@TabView], where each page can have a different background. - -`ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the -shadow is replaced with a more subtle border. This can be useful for -applications like image viewers. - -See also [property@ToolbarView:bottom-bar-style]. - + filename="src/adw-view-switcher.c" + line="450">The stack the view switcher controls. + - - - - - - - - - - - - - - - - - Adwaita version, encoded as a string, useful for printing and -concatenation. - - - - + glib:type-name="AdwViewSwitcherBar" + glib:get-type="adw_view_switcher_bar_get_type" + glib:type-struct="ViewSwitcherBarClass"> A view container for [class@ViewSwitcher]. - -`AdwViewStack` is a container which only shows one page at a time. -It is typically used to hold an application's main views. - -It doesn't provide a way to transition between pages. -Instead, a separate widget such as [class@ViewSwitcher] can be used with -`AdwViewStack` to provide this functionality. - -`AdwViewStack` pages can have a title, an icon, an attention request, and a -numbered badge that [class@ViewSwitcher] will use to let users identify which -page is which. Set them using the [property@ViewStackPage:title], -[property@ViewStackPage:icon-name], -[property@ViewStackPage:needs-attention], and -[property@ViewStackPage:badge-number] properties. - -Unlike [class@Gtk.Stack], transitions between views are not animated. + filename="src/adw-view-switcher-bar.c" + line="14">A view switcher action bar. -`AdwViewStack` maintains a [class@ViewStackPage] object for each added child, -which holds additional per-child properties. You obtain the -[class@ViewStackPage] for a child with [method@ViewStack.get_page] and you -can obtain a [iface@Gtk.SelectionModel] containing all the pages with -[method@ViewStack.get_pages]. +<picture> + <source srcset="view-switcher-bar-dark.png" media="(prefers-color-scheme: dark)"> + <img src="view-switcher-bar.png" alt="view-switcher-bar"> +</picture> -## AdwViewStack as GtkBuildable +An action bar letting you switch between multiple views contained in a +[class@ViewStack], via an [class@ViewSwitcher]. It is designed to be put at +the bottom of a window and to be revealed only on really narrow windows, e.g. +on mobile phones. It can't be revealed if there are less than two pages. -To set child-specific properties in a .ui file, create -[class@ViewStackPage] objects explicitly, and set the child widget as a -property on it: +`AdwViewSwitcherBar` is intended to be used together with +`AdwViewSwitcher` in a header bar, and a [class@Breakpoint] showing the view +switcher bar on narrow sizes, while removing the view switcher from the +header bar, as follows: -```xml - <object class="AdwViewStack" id="stack"> - <child> - <object class="AdwViewStackPage"> - <property name="name">overview</property> - <property name="title">Overview</property> - <property name="child"> - <object class="AdwStatusPage"> - <property name="title">Welcome!</property> - </object> - </property> - </object> - </child> - </object> +```xml +<object class="AdwWindow"> + <child> + <object class="AdwBreakpoint"> + <condition>max-width: 550sp</condition> + <setter object="switcher_bar" property="reveal">True</setter> + <setter object="header_bar" property="title-widget"/> + </object> + </child> + <property name="content"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar" id="header_bar"> + <property name="title-widget"> + <object class="AdwViewSwitcher"> + <property name="stack">stack</property> + <property name="policy">wide</property> + </object> + </property> + </object> + </child> + <property name="content"> + <object class="AdwViewStack" id="stack"/> + </property> + <child type="bottom"> + <object class="AdwViewSwitcherBar" id="switcher_bar"> + <property name="stack">stack</property> + </object> + </child> + </object> + </property> +</object> ``` -## CSS nodes +It's recommended to set [property@ViewSwitcher:policy] to +`ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. -`AdwViewStack` has a single CSS node named `stack`. +You may have to adjust the breakpoint condition for your specific pages. -## Accessibility +## CSS nodes -`AdwViewStack` uses the `GTK_ACCESSIBLE_ROLE_TAB_PANEL` for the stack pages -which are the accessible parent objects of the child widgets. - +`AdwViewSwitcherBar` has a single CSS node with name` viewswitcherbar`. + - + Creates a new `AdwViewStack`. - + filename="src/adw-view-switcher-bar.c" + line="277">Creates a new `AdwViewSwitcherBar`. + the newly created `AdwViewStack` + filename="src/adw-view-switcher-bar.c" + line="282">the newly created `AdwViewSwitcherBar` - + Adds a child to @self. - + filename="src/adw-view-switcher-bar.c" + line="345">Gets whether @self should be revealed or hidden. + the [class@ViewStackPage] for @child - + filename="src/adw-view-switcher-bar.c" + line="351">whether @self is revealed + a view stack - + filename="src/adw-view-switcher-bar.c" + line="347">a view switcher bar + - - the widget to add - - - + Adds a child to @self. - -The child is identified by the @name. - - + filename="src/adw-view-switcher-bar.c" + line="290">Gets the stack controlled by @self. + + the `AdwViewStackPage` for @child - + filename="src/adw-view-switcher-bar.c" + line="296">the stack + a view stack - + filename="src/adw-view-switcher-bar.c" + line="292">a view switcher bar + - - the widget to add - - - - the name for @child - - - + Adds a child to @self. - -The child is identified by the @name. The @title will be used by -[class@ViewSwitcher] to represent @child, so it should be short. - + filename="src/adw-view-switcher-bar.c" + line="361">Sets whether @self should be revealed or hidden. + - the `AdwViewStackPage` for @child - + a view stack - + filename="src/adw-view-switcher-bar.c" + line="363">a view switcher bar + - - the widget to add - - - - the name for @child - - - + a human-readable title for @child - + filename="src/adw-view-switcher-bar.c" + line="364">whether to reveal @self + - + Adds a child to @self. - -The child is identified by the @name. The @title and @icon_name will be used -by [class@ViewSwitcher] to represent @child. - + filename="src/adw-view-switcher-bar.c" + line="306">Sets the stack controlled by @self. + - the `AdwViewStackPage` for @child - + a view stack - + filename="src/adw-view-switcher-bar.c" + line="308">a view switcher bar + - - the widget to add - - - the name for @child - - - - a human-readable title for @child - - - - an icon name for @child - - - - - - Finds the child with @name in @self. - - - the requested child - - - - - a view stack + filename="src/adw-view-switcher-bar.c" + line="309">a stack - - - the name of the child to find - - - + Gets whether @self is horizontally homogeneous. - - - whether @self is horizontally homogeneous - - - - - a view stack - - - - - + filename="src/adw-view-switcher-bar.c" + line="248">Whether the bar should be revealed or hidden. + + + Gets the [class@ViewStackPage] object for @child. - + filename="src/adw-view-switcher-bar.c" + line="238">The stack the view switcher controls. + + + + + + + + + + + + + + + + + Describes the adaptive modes of [class@ViewSwitcher]. + + Force the narrow mode + + + Force the wide mode + + + + A view switcher title. + +<picture> + <source srcset="view-switcher-title-dark.png" media="(prefers-color-scheme: dark)"> + <img src="view-switcher-title.png" alt="view-switcher-title"> +</picture> + +A widget letting you switch between multiple views contained by a +[class@ViewStack] via an [class@ViewSwitcher]. + +It is designed to be used as the title widget of a [class@HeaderBar], and +will display the window's title when the window is too narrow to fit the view +switcher e.g. on mobile phones, or if there are less than two views. + +In order to center the title in narrow windows, the header bar should have +[property@HeaderBar:centering-policy] set to +`ADW_CENTERING_POLICY_STRICT`. + +`AdwViewSwitcherTitle` is intended to be used together with +[class@ViewSwitcherBar]. + +A common use case is to bind the [property@ViewSwitcherBar:reveal] property +to [property@ViewSwitcherTitle:title-visible] to automatically reveal the +view switcher bar when the title label is displayed in place of the view +switcher, as follows: + +```xml +<object class="AdwWindow"> + <property name="content"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"> + <property name="centering-policy">strict</property> + <property name="title-widget"> + <object class="AdwViewSwitcherTitle" id="title"> + <property name="stack">stack</property> + </object> + </property> + </object> + </child> + <property name="content"> + <object class="AdwViewStack" id="stack"/> + </property> + <child type="bottom"> + <object class="AdwViewSwitcherBar"> + <property name="stack">stack</property> + <binding name="reveal"> + <lookup name="title-visible">title</lookup> + </binding> + </object> + </child> + </object> + </property> +</object> +``` + +## CSS nodes + +`AdwViewSwitcherTitle` has a single CSS node with name `viewswitchertitle`. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + + + + + + Creates a new `AdwViewSwitcherTitle`. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + the page object for @child - + filename="src/adw-view-switcher-title.c" + line="392">the newly created `AdwViewSwitcherTitle` + - - - a view stack - - - - a child of @self - - - - - - + + Returns a [iface@Gio.ListModel] that contains the pages of the stack. - -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track and change the visible -page. - - + filename="src/adw-view-switcher-title.c" + line="402">Gets the stack controlled by @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + + a `GtkSelectionModel` for the stack's children - + filename="src/adw-view-switcher-title.c" + line="408">the stack + a view stack - + filename="src/adw-view-switcher-title.c" + line="404">a view switcher title + - - + Gets whether @self is vertically homogeneous. - + filename="src/adw-view-switcher-title.c" + line="506">Gets the subtitle of @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + whether @self is vertically homogeneous - + filename="src/adw-view-switcher-title.c" + line="512">the subtitle + a view stack - + filename="src/adw-view-switcher-title.c" + line="508">a view switcher title + - - + Gets the currently visible child of @self, . - - + filename="src/adw-view-switcher-title.c" + line="462">Gets the title of @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + + the visible child - + filename="src/adw-view-switcher-title.c" + line="468">the title + a view stack - + filename="src/adw-view-switcher-title.c" + line="464">a view switcher title + - - + Returns the name of the currently visible child of @self. - - + filename="src/adw-view-switcher-title.c" + line="600">Gets whether the title of @self is currently visible. + +If the title is visible, it means the view switcher is hidden an it may be +wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + + the name of the visible child - + filename="src/adw-view-switcher-title.c" + line="609">whether the title of @self is currently visible + a view stack - + filename="src/adw-view-switcher-title.c" + line="602">a view switcher title + - + Removes a child widget from @self. - + filename="src/adw-view-switcher-title.c" + line="549">Gets whether @self's view switcher is enabled. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + - + whether the view switcher is enabled + a view stack - + filename="src/adw-view-switcher-title.c" + line="551">a view switcher title + - - the child to remove - - - - + Sets @self to be horizontally homogeneous or not. - -If the stack is horizontally homogeneous, it allocates the same width for -all children. - -If it's `FALSE`, the stack may change width when a different child becomes -visible. - + filename="src/adw-view-switcher-title.c" + line="420">Sets the stack controlled by @self. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + a view stack - + filename="src/adw-view-switcher-title.c" + line="422">a view switcher title + - + whether to make @self horizontally homogeneous - + filename="src/adw-view-switcher-title.c" + line="423">a stack + - - + Sets @self to be vertically homogeneous or not. - -If the stack is vertically homogeneous, it allocates the same height for -all children. + filename="src/adw-view-switcher-title.c" + line="524">Sets the subtitle of @self. -If it's `FALSE`, the stack may change height when a different child becomes -visible. - +The subtitle should give the user additional details. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + a view stack - + filename="src/adw-view-switcher-title.c" + line="526">a view switcher title + - + whether to make @self vertically homogeneous - + filename="src/adw-view-switcher-title.c" + line="527">a subtitle + - - + Makes @child the visible child of @self. - + filename="src/adw-view-switcher-title.c" + line="480">Sets the title of @self. + +The title typically identifies the current view or content item, and +generally does not use the application name. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + a view stack - + filename="src/adw-view-switcher-title.c" + line="482">a view switcher title + - + a child of @self - + filename="src/adw-view-switcher-title.c" + line="483">a title + - - + Makes the child with @name visible. + filename="src/adw-view-switcher-title.c" + line="567">Sets whether @self's view switcher is enabled. -See [property@ViewStack:visible-child]. - +If it is disabled, the title will be displayed instead. This allows to +programmatically hide the view switcher even if it fits in the available +space. + +This can be used e.g. to ensure the view switcher is hidden below a certain +window width, or any other constraint you find suitable. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + a view stack - + filename="src/adw-view-switcher-title.c" + line="569">a view switcher title + - + the name of the child - + filename="src/adw-view-switcher-title.c" + line="570">whether the view switcher is enabled + - - - + setter="set_stack" + getter="get_stack"> Whether the stack is horizontally homogeneous. - -If the stack is horizontally homogeneous, it allocates the same width for -all children. - -If it's `FALSE`, the stack may change width when a different child becomes -visible. - + filename="src/adw-view-switcher-title.c" + line="285">The stack the view switcher controls. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + - - + A selection model with the stack's pages. + filename="src/adw-view-switcher-title.c" + line="312">The subtitle to display. -This can be used to keep an up-to-date view. The model also implements -[iface@Gtk.SelectionModel] and can be used to track and change the visible -page. - +The subtitle should give the user additional details. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + - - - + setter="set_title" + getter="get_title"> Whether the stack is vertically homogeneous. - -If the stack is vertically homogeneous, it allocates the same height for -all children. + filename="src/adw-view-switcher-title.c" + line="297">The title to display. -If it's `FALSE`, the stack may change height when a different child becomes -visible. - +The title typically identifies the current view or content item, and +generally does not use the application name. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + - - - + getter="get_title_visible" + default-value="TRUE"> The widget currently visible in the stack. - + filename="src/adw-view-switcher-title.c" + line="345">Whether the title is currently visible. + +If the title is visible, it means the view switcher is hidden an it may be +wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar]. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + - - - + setter="set_view_switcher_enabled" + getter="get_view_switcher_enabled" + default-value="TRUE"> The name of the widget currently visible in the stack. + filename="src/adw-view-switcher-title.c" + line="326">Whether the view switcher is enabled. -See [property@ViewStack:visible-child]. - +If it is disabled, the title will be displayed instead. This allows to +programmatically hide the view switcher even if it fits in the available +space. + +This can be used e.g. to ensure the view switcher is hidden below a certain +window width, or any other constraint you find suitable. + See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) + - - + + - + An auxiliary class used by [class@ViewStack]. - + filename="src/adw-window.c" + line="20">A freeform window. + +<picture> + <source srcset="window-dark.png" media="(prefers-color-scheme: dark)"> + <img src="window.png" alt="window"> +</picture> + +The `AdwWindow` widget is a subclass of [class@Gtk.Window] which has no +titlebar area. Instead, [class@ToolbarView] can be used together with +[class@HeaderBar] or [class@Gtk.HeaderBar] as follows: + +```xml +<object class="AdwWindow"> + <property name="content"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"/> + </child> + <property name="content"> + <!-- ... --> + </property> + </object> + </property> +</object> +``` + +Using [property@Gtk.Window:titlebar] or [property@Gtk.Window:child] +is not supported and will result in a crash. Use [property@Window:content] +instead. + +## Dialogs + +`AdwWindow` can contain [class@Dialog]. Use [method@Dialog.present] with the +window or a widget within a window to show a dialog. + +## Breakpoints + +`AdwWindow` can be used with [class@Breakpoint] the same way as +[class@BreakpointBin]. Refer to that widget's documentation for details. + +Example: + +```xml +<object class="AdwWindow"> + <property name="content"> + <object class="AdwToolbarView"> + <child type="top"> + <object class="AdwHeaderBar"/> + </child> + <property name="content"> + <!-- ... --> + </property> + <child type="bottom"> + <object class="GtkActionBar" id="bottom_bar"> + <property name="revealed">True</property> + <property name="visible">False</property> + </object> + </child> + </object> + </property> + <child> + <object class="AdwBreakpoint"> + <condition>max-width: 500px</condition> + <setter object="bottom_bar" property="visible">True</setter> + </object> + </child> +</object> +``` + +When breakpoints are used, the minimum size must be larger than the smallest +UI state. `AdwWindow` defaults to the minimum size of 360×200 px. If that's +too small, set the [property@Gtk.Widget:width-request] and +[property@Gtk.Widget:height-request] properties manually. + +## Adaptive Preview + +`AdwWindow` has a debug tool called adaptive preview. It can be opened from +GTK Inspector or by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>, +and controlled via the [property@Window:adaptive-preview] property. + - - - Gets the badge number for this page. - - - the badge number for this page - - - - - a view stack page - - - - - - + + + + + + Gets the stack child to which @self belongs. - + filename="src/adw-window.c" + line="382">Creates a new `AdwWindow`. + the child to which @self belongs + filename="src/adw-window.c" + line="387">the newly created `AdwWindow` - - - a view stack page - - - - - - - Gets the icon name of the page. - - - the icon name of the page - - - - - a view stack page - - - - - - - Gets the name of the page. - - - the name of the page - - - - - a view stack page - - - - - - + + Gets whether the page requires the user attention. - + filename="src/adw-window.c" + line="448">Adds @breakpoint to @self. + - whether the page needs attention - - - - - a view stack page - - - - - - - Gets the page title. - - - the page title - + a view stack page - + filename="src/adw-window.c" + line="450">a window + - - - - - Gets whether underlines in the page title indicate mnemonics. - - - whether underlines in the page title indicate mnemonics - - - - + a view stack page - - + filename="src/adw-window.c" + line="451">the breakpoint to add + + - - + Gets whether @self is visible in its `AdwViewStack`. - -This is independent from the [property@Gtk.Widget:visible] -property of its widget. - + filename="src/adw-window.c" + line="539">Gets whether adaptive preview for @self is currently open. + whether @self is visible + filename="src/adw-window.c" + line="545">whether adaptive preview is open. a view stack page - - - - - - - Sets the badge number for this page. - -[class@ViewSwitcher] can display it as a badge next to the page icon. It is -commonly used to display a number of unread items within the page. - -It can be used together with [property@ViewStack{age}:needs-attention]. - - - - - - - a view stack page - + filename="src/adw-window.c" + line="541">a window + - - the new value to set - - - - + Sets the icon name of the page. - - - + filename="src/adw-window.c" + line="426">Gets the content widget of @self. + +This method should always be used instead of [method@Gtk.Window.get_child]. + + + the content widget of @self + a view stack page - + filename="src/adw-window.c" + line="428">a window + - - the icon name - - - - + Sets the name of the page. - - - + filename="src/adw-window.c" + line="471">Gets the current breakpoint. + + + the current breakpoint + a view stack page - + filename="src/adw-window.c" + line="473">a window + - - the page name - - - - + Sets whether the page requires the user attention. + filename="src/adw-window.c" + line="493">Returns a [iface@Gio.ListModel] that contains the open dialogs of @self. -[class@ViewSwitcher] will display it as a dot next to the page icon. - - - +This can be used to keep an up-to-date view. + + + a list model for the dialogs of @self + a view stack page - + filename="src/adw-window.c" + line="495">a window + - - the new value to set - - - - + Sets the page title. - - - + filename="src/adw-window.c" + line="517">Returns the currently visible dialog in @self, if there's one. + + + the visible dialog + a view stack page - + filename="src/adw-window.c" + line="519">a window + - - the page title - - - - + Sets whether underlines in the page title indicate mnemonics. - + filename="src/adw-window.c" + line="561">Sets whether adaptive preview for @self is currently open. + +Adaptive preview is a debugging tool used for testing the window +contents at specific screen sizes, simulating mobile environment. + +Adaptive preview can always be accessed from inspector. This function +allows applications to open it manually. + +Most applications should not use this function. + a view stack page - + filename="src/adw-window.c" + line="563">a window + - + the new value to set + filename="src/adw-window.c" + line="564">whether to open adaptive preview - - + Sets whether @page is visible in its `AdwViewStack`. + filename="src/adw-window.c" + line="395">Sets the content widget of @self. -This is independent from the [property@Gtk.Widget:visible] property of -[property@ViewStackPage:child]. - +This method should always be used instead of [method@Gtk.Window.set_child]. + a view stack page - + filename="src/adw-window.c" + line="397">a window + - + whether @self is visible - + filename="src/adw-window.c" + line="398">the content widget + - - - + setter="set_adaptive_preview" + getter="get_adaptive_preview" + default-value="FALSE"> The badge number for this page. + filename="src/adw-window.c" + line="294">Whether adaptive preview is currently open. -[class@ViewSwitcher] can display it as a badge next to the page icon. It is -commonly used to display a number of unread items within the page. +Adaptive preview is a debugging tool used for testing the window +contents at specific screen sizes, simulating mobile environment. -It can be used together with [property@ViewStack{age}:needs-attention]. - - - - - The stack child to which the page belongs. - - - - - - The icon name of the child page. - - - - - - The name of the child page. - +Adaptive preview can always be accessed from inspector. This function +allows applications to open it manually. + +Most applications should not use this property. + - - - + setter="set_content" + getter="get_content"> Whether the page requires the user attention. + filename="src/adw-window.c" + line="246">The content widget. -[class@ViewSwitcher] will display it as a dot next to the page icon. - +This property should always be used instead of [property@Gtk.Window:child]. + - - - + getter="get_current_breakpoint"> The title of the child page. - + filename="src/adw-window.c" + line="258">The current breakpoint. + - - - + getter="get_dialogs"> Whether an embedded underline in the title indicates a mnemonic. - + filename="src/adw-window.c" + line="270">The open dialogs. + - - - + getter="get_visible_dialog"> Whether this page is visible. - -This is independent from the [property@Gtk.Widget:visible] property of -[property@ViewStackPage:child]. - + filename="src/adw-window.c" + line="282">The currently visible dialog + + + + - - + + - + + + + + + - + glib:type-name="AdwWindowTitle" + glib:get-type="adw_window_title_get_type" + glib:type-struct="WindowTitleClass"> An auxiliary class used by [class@ViewStack]. + filename="src/adw-window-title.c" + line="11">A helper widget for setting a window's title and subtitle. -See [property@ViewStack:pages]. - - - - - - Gets the [class@ViewStackPage] for the visible child of a view stack +<picture> + <source srcset="window-title-dark.png" media="(prefers-color-scheme: dark)"> + <img src="window-title.png" alt="window-title"> +</picture> -Gets the [class@ViewStackPage] for the visible child of the associated stack. +`AdwWindowTitle` shows a title and subtitle. It's intended to be used as the +title child of [class@Gtk.HeaderBar] or [class@HeaderBar]. -Returns `NULL` if there's no selected page. - - +## CSS nodes + +`AdwWindowTitle` has a single CSS node with name `windowtitle`. + + + + + + Creates a new `AdwWindowTitle`. + + the stack page - + filename="src/adw-window-title.c" + line="159">the newly created `AdwWindowTitle` + + + + + a title + + + + a subtitle + + + + + + Gets the subtitle of @self. + + + the subtitle + a [class@ViewStackPages] - + filename="src/adw-window-title.c" + line="215">a window title + - - + Sets the visible child in the associated [class@ViewStack]. + filename="src/adw-window-title.c" + line="171">Gets the title of @self. + + + the title + + + + + a window title + + + + + + Sets the subtitle of @self. -See [property@ViewStack:visible-child]. - +The subtitle should give the user additional details. + a [class@ViewStackPages] - + filename="src/adw-window-title.c" + line="231">a window title + - + a stack page within the associated stack - + filename="src/adw-window-title.c" + line="232">a subtitle + - + Sets the title of @self. + +The title typically identifies the current view or content item, and +generally does not use the application name. + + + + + + + a window title + + + + a title + + + + + - - + setter="set_subtitle" + getter="get_subtitle"> The selected [class@ViewStackPage] within the [class@ViewStackPages]. + filename="src/adw-window-title.c" + line="128">The subtitle to display. -This can be used to keep an up-to-date view of the [class@ViewStackPage] for -The visible [class@ViewStackPage] within the associated [class@ViewStackPages]. +The subtitle should give the user additional details. + + + + The title to display. -This can be used to keep an up-to-date view of the visible child. - +The title typically identifies the current view or content item, and +generally does not use the application name. + - - + + - + - + glib:type-name="AdwWrapBox" + glib:get-type="adw_wrap_box_get_type" + glib:type-struct="WrapBoxClass"> An adaptive view switcher. + filename="src/adw-wrap-box.c" + line="17">A box-like widget that can wrap into multiple lines. <picture> - <source srcset="view-switcher-dark.png" media="(prefers-color-scheme: dark)"> - <img src="view-switcher.png" alt="view-switcher"> + <source srcset="wrap-box-dark.png" media="(prefers-color-scheme: dark)"> + <img src="wrap-box.png" alt="wrap-box"> </picture> -An adaptive view switcher designed to switch between multiple views -contained in a [class@ViewStack] in a similar fashion to -[class@Gtk.StackSwitcher]. +`AdwWrapBox` is similar to [class@Gtk.Box], but can wrap lines when the +widgets cannot fit otherwise. Unlike [class@Gtk.FlowBox], the children aren't +arranged into a grid and behave more like words in a wrapping label. -`AdwViewSwitcher` buttons always have an icon and a label. They can be -displayed side by side, or icon on top of the label. This can be controlled -via the [property@ViewSwitcher:policy] property. +Like `GtkBox`, `AdwWrapBox` is orientable and has spacing: -`AdwViewSwitcher` is intended to be used in a header bar together with -[class@ViewSwitcherBar] at the bottom of the window, and a [class@Breakpoint] -showing the view switcher bar on narrow sizes, while removing the view -switcher from the header bar, as follows: +- [property@WrapBox:child-spacing] between children in the same line; +- [property@WrapBox:line-spacing] between lines. -```xml -<object class="AdwWindow"> - <property name="width-request">360</property> - <property name="height-request">200</property> - <child> - <object class="AdwBreakpoint"> - <condition>max-width: 550sp</condition> - <setter object="switcher_bar" property="reveal">True</setter> - <setter object="header_bar" property="title-widget"/> - </object> - </child> - <property name="content"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar" id="header_bar"> - <property name="title-widget"> - <object class="AdwViewSwitcher"> - <property name="stack">stack</property> - <property name="policy">wide</property> - </object> - </property> - </object> - </child> - <property name="content"> - <object class="AdwViewStack" id="stack"/> - </property> - <child type="bottom"> - <object class="AdwViewSwitcherBar" id="switcher_bar"> - <property name="stack">stack</property> - </object> - </child> - </object> - </property> -</object> -``` +::: note + Unlike `GtkBox`, `AdwWrapBox` cannot follow the CSS `border-spacing` + property. + +Use the [property@WrapBox:natural-line-length] property to determine the +layout's natural size, e.g. when using it in a [class@Gtk.Popover]. + +Normally, a horizontal `AdwWrapBox` wraps left to right and top to bottom +for left-to-right languages. Both of these directions can be reversed, using +the [property@WrapBox:pack-direction] and [property@WrapBox:wrap-reverse] +properties. Additionally, the alignment of each line can be controlled with +the [property@WrapBox:align] property. + +Lines can be justified using the [property@WrapBox:justify] property, filling +the entire line by either increasing child size or spacing depending on the +value. Set [property@WrapBox:justify-last-line] to justify the last line as +well. + +By default, `AdwWrapBox` wraps as soon as the previous line cannot fit any +more children without shrinking them past their natural size. Set +[property@WrapBox:wrap-policy] to [enum@Adw.WrapPolicy.MINIMUM] to only wrap +once all the children in the previous line have been shrunk to their minimum +size. + +To make each line take the same amount of space, set +[property@WrapBox:line-homogeneous] to `TRUE`. -It's recommended to set [property@ViewSwitcher:policy] to -`ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. +Spacing and natural line length can scale with the text scale factor, use the +[property@WrapBox:child-spacing-unit], [property@WrapBox:line-spacing-unit] +and/or [property@WrapBox:natural-line-length-unit] properties to enable that +behavior. -You may have to adjust the breakpoint condition for your specific pages. +See [class@WrapLayout]. ## CSS nodes -`AdwViewSwitcher` has a single CSS node with name `viewswitcher`. It can have -the style classes `.wide` and `.narrow`, matching its policy. +`AdwWrapBox` uses a single CSS node with name `wrap-box`. ## Accessibility -`AdwViewSwitcher` uses the `GTK_ACCESSIBLE_ROLE_TAB_LIST` role and uses the -`GTK_ACCESSIBLE_ROLE_TAB` for its buttons. - +`AdwWrapBox` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. + - + + Creates a new `AdwViewSwitcher`. - + filename="src/adw-wrap-box.c" + line="530">Creates a new `AdwWrapBox`. + the newly created `AdwViewSwitcher` + filename="src/adw-wrap-box.c" + line="535">the newly created `AdwWrapBox` - - + Gets the policy of @self. - + filename="src/adw-wrap-box.c" + line="1332">Adds @child as the last child to @self. + - the policy of @self - + a view switcher - + filename="src/adw-wrap-box.c" + line="1334">a wrap box + + + the widget to append + + - - + Gets the stack controlled by @self. - - + filename="src/adw-wrap-box.c" + line="705">Gets the alignment of the children within each line. + + the stack - + filename="src/adw-wrap-box.c" + line="711">the child alignment + a view switcher - + filename="src/adw-wrap-box.c" + line="707">a wrap box + - - + Sets the policy of @self. - + filename="src/adw-wrap-box.c" + line="545">Gets spacing between widgets on the same line. + - + spacing between widgets on the same line + a view switcher - + filename="src/adw-wrap-box.c" + line="547">a wrap box + - + + + + Gets the length unit for child spacing. + + + the length unit + + + + the new policy - - + filename="src/adw-wrap-box.c" + line="601">a wrap box + + - - + Sets the stack controlled by @self. - + filename="src/adw-wrap-box.c" + line="762">Gets whether and how each complete line is stretched to fill the entire widget. + - + the justify mode + a view switcher - + filename="src/adw-wrap-box.c" + line="764">a wrap box + - + + + + Gets whether the last line should be stretched to fill the entire widget. + + + whether the last line is justified + + + + a stack - - + filename="src/adw-wrap-box.c" + line="831">a wrap box + + - - - + The policy to determine which mode to use. - - - - - + filename="src/adw-wrap-box.c" + line="991">Gets whether all lines should take the same amount of space. + + + whether lines should be homogeneous + + + + + a wrap box + + + + + The stack the view switcher controls. - - - - - A view switcher action bar. - -<picture> - <source srcset="view-switcher-bar-dark.png" media="(prefers-color-scheme: dark)"> - <img src="view-switcher-bar.png" alt="view-switcher-bar"> -</picture> - -An action bar letting you switch between multiple views contained in a -[class@ViewStack], via an [class@ViewSwitcher]. It is designed to be put at -the bottom of a window and to be revealed only on really narrow windows, e.g. -on mobile phones. It can't be revealed if there are less than two pages. - -`AdwViewSwitcherBar` is intended to be used together with -`AdwViewSwitcher` in a header bar, and a [class@Breakpoint] showing the view -switcher bar on narrow sizes, while removing the view switcher from the -header bar, as follows: - -```xml -<object class="AdwWindow"> - <property name="width-request">360</property> - <property name="height-request">200</property> - <child> - <object class="AdwBreakpoint"> - <condition>max-width: 550sp</condition> - <setter object="switcher_bar" property="reveal">True</setter> - <setter object="header_bar" property="title-widget"/> - </object> - </child> - <property name="content"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar" id="header_bar"> - <property name="title-widget"> - <object class="AdwViewSwitcher"> - <property name="stack">stack</property> - <property name="policy">wide</property> - </object> - </property> - </object> - </child> - <property name="content"> - <object class="AdwViewStack" id="stack"/> - </property> - <child type="bottom"> - <object class="AdwViewSwitcherBar" id="switcher_bar"> - <property name="stack">stack</property> - </object> - </child> - </object> - </property> -</object> -``` - -It's recommended to set [property@ViewSwitcher:policy] to -`ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. - -You may have to adjust the breakpoint condition for your specific pages. - -## CSS nodes + filename="src/adw-wrap-box.c" + line="882">Gets the spacing between lines. -`AdwViewSwitcherBar` has a single CSS node with name` viewswitcherbar`. - - - - - +See [property@WrapBox:line-spacing-unit]. + + + the line spacing + + + + + a wrap box + + + + + Creates a new `AdwViewSwitcherBar`. - + filename="src/adw-wrap-box.c" + line="936">Gets the length unit for line spacing. + the newly created `AdwViewSwitcherBar` - + filename="src/adw-wrap-box.c" + line="942">the length unit + - - - + + + a wrap box + + + + + Gets whether @self should be revealed or hidden. - + filename="src/adw-wrap-box.c" + line="1042">Gets the natural size for each line. + whether @self is revealed - + filename="src/adw-wrap-box.c" + line="1048">the natural length + a view switcher bar - + filename="src/adw-wrap-box.c" + line="1044">a wrap box + - - + Gets the stack controlled by @self. - - + filename="src/adw-wrap-box.c" + line="1099">Gets the length unit for line spacing. + + the stack - + filename="src/adw-wrap-box.c" + line="1105">the length unit + a view switcher bar - + filename="src/adw-wrap-box.c" + line="1101">a wrap box + - - + Sets whether @self should be revealed or hidden. - + filename="src/adw-wrap-box.c" + line="654">Gets the direction children are packed in each line. + - + the line direction + a view switcher bar - + filename="src/adw-wrap-box.c" + line="656">a wrap box + - + + + + Gets the policy for line wrapping. + + + the wrap policy + + + + whether to reveal @self - - + filename="src/adw-wrap-box.c" + line="1211">a wrap box + + - - + Sets the stack controlled by @self. - + filename="src/adw-wrap-box.c" + line="1154">Gets whether wrap direction is reversed. + + + whether wrap direction is reversed + + + + + a wrap box + + + + + + Inserts @child in the position after @sibling in the list of @self children. + +If @sibling is `NULL`, inserts @child at the first position. + a view switcher bar - + filename="src/adw-wrap-box.c" + line="1270">a wrap box + - + the widget to insert + + + a stack - + filename="src/adw-wrap-box.c" + line="1272">the sibling after which to insert @child + - - - - Whether the bar should be revealed or hidden. - - - - - - The stack the view switcher controls. - - - - - - - - - - - - - - - - - Describes the adaptive modes of [class@ViewSwitcher]. - + Force the narrow mode - - + filename="src/adw-wrap-box.c" + line="1352">Adds @child as the first child to @self. + + + + + + + a wrap box + + + + the widget to prepend + + + + + Force the wide mode - - - - A view switcher title. + filename="src/adw-wrap-box.c" + line="1372">Removes a child widget from @self. -<picture> - <source srcset="view-switcher-title-dark.png" media="(prefers-color-scheme: dark)"> - <img src="view-switcher-title.png" alt="view-switcher-title"> -</picture> +The child must have been added before with [method@Adw.WrapBox.append], +[method@Adw.WrapBox.prepend], or [method@Adw.WrapBox.insert_child_after]. + + + + + + + a wrap box + + + + the child to remove + + + + + + Moves @child to the position after @sibling in the list of @self children. -A widget letting you switch between multiple views contained by a -[class@ViewStack] via an [class@ViewSwitcher]. +If @sibling is `NULL`, moves @child to the first position. + + + + + + + a wrap box + + + + the widget to move, must be a child of @self + + + + the sibling to move @child after + + + + + + Sets the alignment of the children within each line. -It is designed to be used as the title widget of a [class@HeaderBar], and -will display the window's title when the window is too narrow to fit the view -switcher e.g. on mobile phones, or if there are less than two views. +0 means the children are placed at the start of the line, 1 means they are +placed at the end of the line. 0.5 means they are placed in the middle of the +line. -In order to center the title in narrow windows, the header bar should have -[property@HeaderBar:centering-policy] set to -`ADW_CENTERING_POLICY_STRICT`. +Alignment is only used when [property@WrapBox:justify] is set to +`ADW_JUSTIFY_NONE`, or on the last line when the +[property@WrapBox:justify-last-line] is `FALSE`. + + + + + + + a wrap box + + + + the child alignment + + + + + + Sets the spacing between widgets on the same line. -`AdwViewSwitcherTitle` is intended to be used together with -[class@ViewSwitcherBar]. +See [property@WrapBox:child-spacing-unit]. + + + + + + + a wrap box + + + + the child spacing + + + + + + Sets the length unit for child spacing. -A common use case is to bind the [property@ViewSwitcherBar:reveal] property -to [property@ViewSwitcherTitle:title-visible] to automatically reveal the -view switcher bar when the title label is displayed in place of the view -switcher, as follows: +Allows the spacing to vary depending on the text scale factor. -```xml -<object class="AdwWindow"> - <property name="content"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"> - <property name="centering-policy">strict</property> - <property name="title-widget"> - <object class="AdwViewSwitcherTitle" id="title"> - <property name="stack">stack</property> - </object> - </property> - </object> - </child> - <property name="content"> - <object class="AdwViewStack" id="stack"/> - </property> - <child type="bottom"> - <object class="AdwViewSwitcherBar"> - <property name="stack">stack</property> - <binding name="reveal"> - <lookup name="title-visible">title</lookup> - </binding> - </object> - </child> - </object> - </property> -</object> -``` +See [property@WrapBox:child-spacing]. + + + + + + + a wrap box + + + + the length unit + + + + + + Determines whether and how each complete line should be stretched to fill +the entire widget. -## CSS nodes +If set to `ADW_JUSTIFY_FILL`, each widget in the line will be stretched, +keeping consistent spacing, so that the line fills the entire widget. -`AdwViewSwitcherTitle` has a single CSS node with name `viewswitchertitle`. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - - - - - - Creates a new `AdwViewSwitcherTitle`. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - +If set to `ADW_JUSTIFY_SPREAD`, the spacing between widgets will be +increased, keeping widget sizes intact. The first and last widget will be +aligned with the beginning and end of the line. If the line only contains a +single widget, it will be stretched regardless. + +If set to `ADW_JUSTIFY_NONE`, the line will not be stretched and the children +will be placed together within the line, according to +[property@WrapBox:align]. + +By default this doesn't affect the last line, as it will be incomplete. Use +[property@WrapBox:justify-last-line] to justify it as well. + - the newly created `AdwViewSwitcherTitle` - + - - - + + + a wrap box + + + + the justify mode + + + + + Gets the stack controlled by @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - - - the stack - + filename="src/adw-wrap-box.c" + line="851">Sets whether the last line should be stretched to fill the entire widget. + +See [property@WrapBox:justify]. + + + a view switcher title - + filename="src/adw-wrap-box.c" + line="853">a wrap box + + + whether to justify the last line + + - - + Gets the subtitle of @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - + filename="src/adw-wrap-box.c" + line="1013">Sets whether all lines should take the same amount of space. + - the subtitle - + a view switcher title - + filename="src/adw-wrap-box.c" + line="1015">a wrap box + + + whether lines should be homogeneous + + - - + Gets the title of @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - + filename="src/adw-wrap-box.c" + line="906">Sets the spacing between lines. + - the title - + a view switcher title - + filename="src/adw-wrap-box.c" + line="908">a wrap box + + + the line spacing + + - - + Gets whether the title of @self is currently visible. + filename="src/adw-wrap-box.c" + line="958">Sets the length unit for line spacing. -If the title is visible, it means the view switcher is hidden an it may be -wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - +Allows the spacing to vary depending on the text scale factor. + +See [property@WrapBox:line-spacing]. + - whether the title of @self is currently visible - + a view switcher title - + filename="src/adw-wrap-box.c" + line="960">a wrap box + + + the length unit + + - - + Gets whether @self's view switcher is enabled. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - + filename="src/adw-wrap-box.c" + line="1064">Sets the natural size for each line. + +It should be used to limit the line lengths, for example when used in +popovers. + +See [property@WrapBox:natural-line-length-unit]. + - whether the view switcher is enabled - + a view switcher title - + filename="src/adw-wrap-box.c" + line="1066">a wrap box + + + the natural length + + - - + Sets the stack controlled by @self. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - + filename="src/adw-wrap-box.c" + line="1121">Sets the length unit for natural line length. + +Allows the length to vary depending on the text scale factor. + +See [property@WrapBox:natural-line-length]. + a view switcher title - + filename="src/adw-wrap-box.c" + line="1123">a wrap box + - + a stack - + filename="src/adw-wrap-box.c" + line="1124">the length unit + - - + Sets the subtitle of @self. - -The subtitle should give the user additional details. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - + filename="src/adw-wrap-box.c" + line="676">Sets the direction children are packed in each line. + a view switcher title - + filename="src/adw-wrap-box.c" + line="678">a wrap box + - + a subtitle - + filename="src/adw-wrap-box.c" + line="679">the new line direction + - - + Sets the title of @self. + filename="src/adw-wrap-box.c" + line="1231">Sets the policy for line wrapping. -The title typically identifies the current view or content item, and -generally does not use the application name. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - +If set to `ADW_WRAP_NATURAL`, the box will wrap to the next line as soon as +the previous line cannot fit any more children without shrinking them past +their natural size. + +If set to `ADW_WRAP_MINIMUM`, the box will try to fit as many children into +each line as possible, shrinking them down to their minimum size before +wrapping to the next line. + a view switcher title - + filename="src/adw-wrap-box.c" + line="1233">a wrap box + - + a title - + filename="src/adw-wrap-box.c" + line="1234">the new wrap policy + - - + Sets whether @self's view switcher is enabled. - -If it is disabled, the title will be displayed instead. This allows to -programmatically hide the view switcher even if it fits in the available -space. + filename="src/adw-wrap-box.c" + line="1176">Sets whether wrap direction should be reversed. -This can be used e.g. to ensure the view switcher is hidden below a certain -window width, or any other constraint you find suitable. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - +By default, lines wrap downwards in a horizontal box, and towards the end +in a vertical box. If set to `TRUE`, they wrap upwards or towards the start +respectively. + a view switcher title - + filename="src/adw-wrap-box.c" + line="1178">a wrap box + - + whether the view switcher is enabled + filename="src/adw-wrap-box.c" + line="1179">whether to reverse wrap direction - - - + setter="set_align" + getter="get_align" + default-value="0.000000"> The stack the view switcher controls. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - + filename="src/adw-wrap-box.c" + line="319">The alignment of the children within each line. + +0 means the children are placed at the start of the line, 1 means they are +placed at the end of the line. 0.5 means they are placed in the middle of +the line. + +Alignment is only used when [property@WrapBox:justify] is set to +`ADW_JUSTIFY_NONE`, or on the last line when the +[property@WrapBox:justify-last-line] is `FALSE`. + - - - + setter="set_child_spacing" + getter="get_child_spacing" + default-value="0"> The subtitle to display. + filename="src/adw-wrap-box.c" + line="275">The spacing between widgets on the same line. -The subtitle should give the user additional details. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - +See [property@WrapBox:child-spacing-unit]. + - - - + setter="set_child_spacing_unit" + getter="get_child_spacing_unit" + default-value="ADW_LENGTH_UNIT_PX"> The title to display. + filename="src/adw-wrap-box.c" + line="289">The length unit for child spacing. -The title typically identifies the current view or content item, and -generally does not use the application name. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) - +Allows the spacing to vary depending on the text scale factor. + +See [property@WrapBox:child-spacing]. + - - + setter="set_justify" + getter="get_justify" + default-value="ADW_JUSTIFY_NONE"> Whether the title is currently visible. + filename="src/adw-wrap-box.c" + line="339">Determines whether and how each complete line should be stretched to fill +the entire widget. -If the title is visible, it means the view switcher is hidden an it may be -wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar]. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) +If set to `ADW_JUSTIFY_FILL`, each widget in the line will be stretched, +keeping consistent spacing, so that the line fills the entire widget. + +If set to `ADW_JUSTIFY_SPREAD`, the spacing between widgets will be +increased, keeping widget sizes intact. The first and last widget will be +aligned with the beginning and end of the line. If the line only contains +a single widget, it will be stretched regardless. + +If set to `ADW_JUSTIFY_NONE`, the line will not be stretched and the +children will be placed together within the line, according to +[property@WrapBox:align]. + +By default this doesn't affect the last line, as it will be incomplete. Use +[property@WrapBox:justify-last-line] to justify it as well. + + + + Whether the last line should be stretched to fill the entire widget. + +See [property@WrapBox:justify]. - - - + setter="set_line_homogeneous" + getter="get_line_homogeneous" + default-value="FALSE"> Whether the view switcher is enabled. + filename="src/adw-wrap-box.c" + line="413">Whether all lines should take the same amount of space. + + + + The spacing between lines. -If it is disabled, the title will be displayed instead. This allows to -programmatically hide the view switcher even if it fits in the available -space. +See [property@WrapBox:line-spacing-unit]. + + + + The length unit for line spacing. -This can be used e.g. to ensure the view switcher is hidden below a certain -window width, or any other constraint you find suitable. - See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) +Allows the spacing to vary depending on the text scale factor. + +See [property@WrapBox:line-spacing]. + + + + Determines the natural size for each line. + +It should be used to limit the line lengths, for example when used in +popovers. + +See [property@WrapBox:natural-line-length-unit]. + + + + The length unit for natural line length. + +Allows the length to vary depending on the text scale factor. + +See [property@WrapBox:natural-line-length]. + + + + The direction children are packed in each line. + + + + The policy for line wrapping. + + + If set to `ADW_WRAP_NATURAL`, the box will wrap to the next line as soon as +the previous line cannot fit any more children without shrinking them past +their natural size. + +If set to `ADW_WRAP_MINIMUM`, the box will try to fit as many children into +each line as possible, shrinking them down to their minimum size before +wrapping to the next line. + + + + Whether wrap direction should be reversed. + +By default, lines wrap downwards in a horizontal box, and towards the end +in a vertical box. If set to `TRUE`, they wrap upwards or towards the start +respectively. - - + + - + A freeform window. + filename="src/adw-wrap-layout.c" + line="17">A box-like layout that can wrap into multiple lines. <picture> - <source srcset="window-dark.png" media="(prefers-color-scheme: dark)"> - <img src="window.png" alt="window"> + <source srcset="wrap-box-dark.png" media="(prefers-color-scheme: dark)"> + <img src="wrap-box.png" alt="wrap-box"> </picture> -The `AdwWindow` widget is a subclass of [class@Gtk.Window] which has no -titlebar area. Instead, [class@ToolbarView] can be used together with -[class@HeaderBar] or [class@Gtk.HeaderBar] as follows: +`AdwWrapLayout` is similar to [class@Gtk.BoxLayout], but can wrap lines when +the widgets cannot fit otherwise. Unlike [class@Gtk.FlowBox], the children +aren't arranged into a grid and behave more like words in a wrapping label. -```xml -<object class="AdwWindow"> - <property name="content"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"/> - </child> - <property name="content"> - <!-- ... --> - </property> - </object> - </property> -</object> -``` +Like `GtkBoxLayout`, `AdwWrapLayout` is orientable and has spacing: -Using [property@Gtk.Window:titlebar] or [property@Gtk.Window:child] -is not supported and will result in a crash. Use [property@Window:content] -instead. +- [property@WrapLayout:child-spacing] between children in the same line; +- [property@WrapLayout:line-spacing] between lines. -## Breakpoints +::: note + Unlike `GtkBoxLayout`, `AdwWrapLayout` cannot follow the CSS + `border-spacing` property. -`AdwWindow` can be used with [class@Breakpoint] the same way as -[class@BreakpointBin]. Refer to that widget's documentation for details. +Use the [property@WrapLayout:natural-line-length] property to determine the +layout's natural size, e.g. when using it in a [class@Gtk.Popover]. -Example: +Normally, a horizontal `AdwWrapLayout` wraps left to right and top to bottom +for left-to-right languages. Both of these directions can be reversed, using +the [property@WrapLayout:pack-direction] and +[property@WrapLayout:wrap-reverse] properties. Additionally, the alignment +of each line can be controlled with the [property@WrapLayout:align] property. -```xml -<object class="AdwWindow"> - <property name="width-request">360</property> - <property name="height-request">200</property> - <property name="content"> - <object class="AdwToolbarView"> - <child type="top"> - <object class="AdwHeaderBar"/> - </child> - <property name="content"> - <!-- ... --> - </property> - <child type="bottom"> - <object class="GtkActionBar" id="bottom_bar"> - <property name="revealed">True</property> - <property name="visible">False</property> - </object> - </child> - </object> - </property> - <child> - <object class="AdwBreakpoint"> - <condition>max-width: 500px</condition> - <setter object="bottom_bar" property="visible">True</setter> - </object> - </child> -</object> -``` +Lines can be justified using the [property@WrapLayout:justify] property, +filling the entire line by either increasing child size or spacing depending +on the value. Set [property@WrapLayout:justify-last-line] to justify the last +line as well. -Like `AdwBreakpointBin`, if breakpoints are used, `AdwWindow` doesn't have a -minimum size, and [property@Gtk.Widget:width-request] and -[property@Gtk.Widget:height-request] properties must be set manually. - - - - - - - - +By default, `AdwWrapLayout` wraps as soon as the previous line cannot fit +any more children without shrinking them past their natural size. Set +[property@WrapLayout:wrap-policy] to [enum@Adw.WrapPolicy.MINIMUM] to only +wrap once all the children in the previous line have been shrunk to their +minimum size. + +To make each line take the same amount of space, set +[property@WrapLayout:line-homogeneous] to `TRUE`. + +Spacing and natural line length can scale with the text scale factor, use the +[property@WrapLayout:child-spacing-unit], +[property@WrapLayout:line-spacing-unit] and/or +[property@WrapLayout:natural-line-length-unit] properties to enable that +behavior. + +See [class@WrapBox]. + + + + Creates a new `AdwWrapLayout`. + + + the newly created `AdwWrapLayout` + + + + + Gets the alignment of the children within each line. + + + the child alignment + + + + + a wrap layout + + + + + + Gets spacing between widgets on the same line. + + + spacing between widgets on the same line + + + + + a wrap layout + + + + + + Gets the length unit for child spacing. + + + the length unit + + + + + a wrap layout + + + + + + Gets whether and how each complete line is stretched to fill the entire widget. + + + the justify mode + + + + + a wrap layout + + + + + + Gets whether the last line should be stretched to fill the entire widget. + + + whether the last line is justified + + + + + a wrap layout + + + + + + Gets whether all lines should take the same amount of space. + + + whether lines should be homogeneous + + + + + a wrap layout + + + + + + Gets the spacing between lines. + + + the line spacing + + + + + a wrap layout + + + + + + Gets the length unit for line spacing. + + + the length unit + + + + + a wrap layout + + + + + + Gets the natural size for each line. + + + the natural length + + + + + a wrap layout + + + + + + Gets the length unit for line spacing. + + + the length unit + + + + + a wrap layout + + + + + Creates a new `AdwWindow`. - + filename="src/adw-wrap-layout.c" + line="1333">Gets the direction children are packed in each line. + the newly created `AdwWindow` - + filename="src/adw-wrap-layout.c" + line="1339">the line direction + - - + + + a wrap layout + + + + + Adds @breakpoint to @self. - + filename="src/adw-wrap-layout.c" + line="1828">Gets the policy for line wrapping. + + + the wrap policy + + + + + a wrap layout + + + + + + Gets whether wrap direction is reversed. + + + whether wrap direction is reversed + + + + + a wrap layout + + + + + + Sets the alignment of the children within each line. + +0 means the children are placed at the start of the line, 1 means they are +placed at the end of the line. 0.5 means they are placed in the middle of the +line. + +Alignment is only used when [property@WrapLayout:justify] is set to +`ADW_JUSTIFY_NONE`, or on the last line when the +[property@WrapLayout:justify-last-line] is `FALSE`. + a window - + filename="src/adw-wrap-layout.c" + line="1398">a wrap layout + - + the breakpoint to add - + filename="src/adw-wrap-layout.c" + line="1399">the child alignment + - - + Gets the content widget of @self. + filename="src/adw-wrap-layout.c" + line="1254">Sets the spacing between widgets on the same line. -This method should always be used instead of [method@Gtk.Window.get_child]. - - - the content widget of @self - +See [property@WrapLayout:child-spacing-unit]. + + + a window - + filename="src/adw-wrap-layout.c" + line="1256">a wrap layout + + + the child spacing + + - - + Gets the current breakpoint. - - - the current breakpoint - + filename="src/adw-wrap-layout.c" + line="1302">Sets the length unit for child spacing. + +Allows the spacing to vary depending on the text scale factor. + +See [property@WrapLayout:child-spacing]. + + + a window - + filename="src/adw-wrap-layout.c" + line="1304">a wrap layout + + + the length unit + + - - + Sets the content widget of @self. + filename="src/adw-wrap-layout.c" + line="1447">Sets whether and how each complete line should be stretched to fill the +entire widget. -This method should always be used instead of [method@Gtk.Window.set_child]. - +If set to `ADW_JUSTIFY_FILL`, each widget in the line will be stretched, +keeping consistent spacing, so that the line fills the entire widget. + +If set to `ADW_JUSTIFY_SPREAD`, the spacing between widgets will be +increased, keeping widget sizes intact. The first and last widget will be +aligned with the beginning and end of the line. If the line only contains a +single widget, it will be stretched regardless. + +If set to `ADW_JUSTIFY_NONE`, the line will not be stretched and the children +will be placed together within the line, according to +[property@WrapLayout:align]. + +By default this doesn't affect the last line, as it will be incomplete. Use +[property@WrapLayout:justify-last-line] to justify it as well. + a window - + filename="src/adw-wrap-layout.c" + line="1449">a wrap layout + - + the content widget - + filename="src/adw-wrap-layout.c" + line="1450">the justify mode + - - - + The content widget. + filename="src/adw-wrap-layout.c" + line="1508">Sets whether the last line should be stretched to fill the entire widget. -This property should always be used instead of [property@Gtk.Window:child]. - - - - +See [property@WrapLayout:justify]. + + + + + + + a wrap layout + + + + whether to justify the last line + + + + + The current breakpoint. - - - - - - - - - - - - - - - - - - - A helper widget for setting a window's title and subtitle. - -<picture> - <source srcset="window-title-dark.png" media="(prefers-color-scheme: dark)"> - <img src="window-title.png" alt="window-title"> -</picture> + filename="src/adw-wrap-layout.c" + line="1652">Sets whether all lines should take the same amount of space. + + + + + + + a wrap layout + + + + whether lines should be homogeneous + + + + + + Sets the spacing between lines. -`AdwWindowTitle` shows a title and subtitle. It's intended to be used as the -title child of [class@Gtk.HeaderBar] or [class@HeaderBar]. +See [property@WrapLayout:line-spacing-unit]. + + + + + + + a wrap layout + + + + the line spacing + + + + + + Sets the length unit for line spacing. -## CSS nodes +Allows the spacing to vary depending on the text scale factor. -`AdwWindowTitle` has a single CSS node with name `windowtitle`. - - - - - - Creates a new `AdwWindowTitle`. - +See [property@WrapLayout:line-spacing]. + - the newly created `AdwWindowTitle` - + - + a title - + filename="src/adw-wrap-layout.c" + line="1605">a wrap layout + + + + the length unit + - + + + + Sets the natural size for each line. + +It should be used to limit the line lengths, for example when used in +popovers. + +See [property@WrapLayout:natural-line-length-unit]. + + + + + + a subtitle - + filename="src/adw-wrap-layout.c" + line="1699">a wrap layout + + + + the natural length + - - - + + Gets the subtitle of @self. - + filename="src/adw-wrap-layout.c" + line="1748">Sets the length unit for natural line length. + +Allows the length to vary depending on the text scale factor. + +See [property@WrapLayout:natural-line-length]. + - the subtitle - + a window title - + filename="src/adw-wrap-layout.c" + line="1750">a wrap layout + + + the length unit + + - - + Gets the title of @self. - + filename="src/adw-wrap-layout.c" + line="1351">Sets the direction children are packed in each line. + - the title - + a window title - + filename="src/adw-wrap-layout.c" + line="1353">a wrap layout + + + the new line direction + + - - + Sets the subtitle of @self. + filename="src/adw-wrap-layout.c" + line="1846">Sets the policy for line wrapping. -The subtitle should give the user additional details. - +If set to `ADW_WRAP_NATURAL`, the box will wrap to the next line as soon as +the previous line cannot fit any more children without shrinking them past +their natural size. + +If set to `ADW_WRAP_MINIMUM`, the box will try to fit as many children into +each line as possible, shrinking them down to their minimum size before +wrapping to the next line. + a window title - + filename="src/adw-wrap-layout.c" + line="1848">a wrap layout + - + a subtitle - + filename="src/adw-wrap-layout.c" + line="1849">the new wrap policy + - - + Sets the title of @self. + filename="src/adw-wrap-layout.c" + line="1797">Sets whether wrap direction should be reversed. -The title typically identifies the current view or content item, and -generally does not use the application name. - +By default, lines wrap downwards in a horizontal box, and towards the end +in a vertical box. If set to `TRUE`, they wrap upwards or towards the start +respectively. + a window title - + filename="src/adw-wrap-layout.c" + line="1799">a wrap layout + - + a title - + filename="src/adw-wrap-layout.c" + line="1800">whether to reverse wrap direction + - - - + setter="set_align" + getter="get_align" + default-value="0.000000"> The subtitle to display. + filename="src/adw-wrap-layout.c" + line="1026">The alignment of the children within each line. -The subtitle should give the user additional details. - +0 means the children are placed at the start of the line, 1 means they are +placed at the end of the line. 0.5 means they are placed in the middle of +the line. + +Alignment is only used when [property@WrapLayout:justify] is set to +`ADW_JUSTIFY_NONE`, or on the last line when the +[property@WrapLayout:justify-last-line] is `FALSE`. + - - - + setter="set_child_spacing" + getter="get_child_spacing" + default-value="0"> The title to display. + filename="src/adw-wrap-layout.c" + line="982">The spacing between widgets on the same line. -The title typically identifies the current view or content item, and -generally does not use the application name. - +See [property@WrapLayout:child-spacing-unit]. + + + + The length unit for child spacing. + +Allows the spacing to vary depending on the text scale factor. + +See [property@WrapLayout:child-spacing]. + + + + Determines whether and how each complete line should be stretched to fill +the entire widget. + +If set to `ADW_JUSTIFY_FILL`, each widget in the line will be stretched, +keeping consistent spacing, so that the line fills the entire widget. + +If set to `ADW_JUSTIFY_SPREAD`, the spacing between widgets will be +increased, keeping widget sizes intact. The first and last widget will be +aligned with the beginning and end of the line. If the line only contains a +single widget, it will be stretched regardless. + +If set to `ADW_JUSTIFY_NONE`, the line will not be stretched and the +children will be placed together within the line, according to +[property@WrapLayout:align]. + +By default this doesn't affect the last line, as it will be incomplete. Use +[property@WrapLayout:justify-last-line] to justify it as well. + + + + Whether the last line should be stretched to fill the entire widget. + +See [property@WrapLayout:justify]. + + + + Whether all lines should take the same amount of space. + + + + The spacing between lines. + +See [property@WrapLayout:line-spacing-unit]. + + + + The length unit for line spacing. + +Allows the spacing to vary depending on the text scale factor. + +See [property@WrapLayout:line-spacing]. + + + + Determines the natural size for each line. + +It should be used to limit the line lengths, for example when used in +popovers. + +See [property@WrapLayout:natural-line-length-unit]. + + + + The length unit for natural line length. + +Allows the length to vary depending on the text scale factor. + +See [property@WrapLayout:natural-line-length]. + + + + The direction children are packed in each line. + + + + The policy for line wrapping. + +If set to `ADW_WRAP_NATURAL`, the box will wrap to the next line as soon as +the previous line cannot fit any more children without shrinking them past +their natural size. + +If set to `ADW_WRAP_MINIMUM`, the box will try to fit as many children into +each line as possible, shrinking them down to their minimum size before +wrapping to the next line. + + + + Whether wrap direction should be reversed. + +By default, lines wrap downwards in a horizontal box, and towards the end +in a vertical box. If set to `TRUE`, they wrap upwards or towards the start +respectively. + - - + + - + + + Describes line wrapping behavior in a [class@WrapLayout] or [class@WrapBox]. + +See [property@WrapLayout:wrap-policy] and [property@WrapBox:wrap-policy]. + + Fit as many children into each line as possible, shrinking + them down to their minimum size before wrapping to the next line. + + + Wrap to the next line as soon as the previous line cannot + fit any more children without shrinking them past their natural size. + + + + Converts @self to a `GdkRGBA` representing its background color. + +The matching foreground color is white. + + + + + + + an accent color + + + + return location for the color + + + + + + Converts @self to a `GdkRGBA` representing its standalone color. + +It will typically be darker for light background, and lighter for dark +background, ensuring contrast. + + + + + + + an accent color + + + + Whether to calculate standalone color for light or dark background + + + + return location for the color + + + + Parses a condition from a string. + line="709">Parses a condition from a string. Length conditions are specified as `<type>: <value>[<unit>]`, where: @@ -37393,14 +48588,14 @@ If parentheses are omitted, the first operator takes priority. the parsed condition + line="769">the parsed condition the string specifying the condition + line="711">the string specifying the condition @@ -37410,27 +48605,27 @@ If parentheses are omitted, the first operator takes priority. moved-to="Easing.ease"> Computes easing with @easing for @value. + line="533">Computes easing with @easing for @value. @value should generally be in the [0, 1] range. - + the easing for @value + line="542">the easing for @value an easing value + line="535">an easing value a value to ease + line="536">a value to ease @@ -37470,7 +48665,7 @@ This function is in the library, so it represents the libadwaita library your code is running against. Contrast with the [const@MAJOR_VERSION] constant, which represents the major version of the libadwaita headers you have included when compiling your code. - + - + - + Initializes Libadwaita. + line="34">Initializes Libadwaita. This function can be used instead of [func@Gtk.init] as it initializes GTK implicitly. @@ -37538,13 +48733,13 @@ library are set up properly. Use this function to check if libadwaita has been initialized with + line="79">Use this function to check if libadwaita has been initialized with [func@init]. the initialization status + line="85">the initialization status @@ -37554,25 +48749,25 @@ library are set up properly. version="1.4"> Converts @value from pixels to @unit. + line="84">Converts @value from pixels to @unit. the length in @unit + line="92">the length in @unit a length unit + line="86">a length unit a value in pixels + line="87">a value in pixels allow-none="1"> settings to use, or `NULL` for default settings + line="88">settings to use, or `NULL` for default settings @@ -37592,25 +48787,25 @@ library are set up properly. version="1.4"> Converts @value from @unit to pixels. + line="45">Converts @value from @unit to pixels. the length in pixels + line="53">the length in pixels a length unit + line="47">a length unit a value in @unit + line="48">a value in @unit allow-none="1"> settings to use, or `NULL` for default settings + line="49">settings to use, or `NULL` for default settings @@ -37656,13 +48851,137 @@ library are set up properly. + + Adjusts @rgba to be suitable as a standalone color. + +It will typically be darker for light background, and lighter for dark +background, ensuring contrast. + + + + + + + a background color + + + + Whether to calculate standalone color for light or dark background + + + + return location for the standalone color + + + + + + A convenience function for showing an application’s about dialog. + + + + + + + the parent widget + + + + the name of the first property + + + + value of first property, followed by more pairs of property name and + value, `NULL`-terminated + + + + + + A convenience function for showing an application’s about dialog from +AppStream metadata. + +See [ctor@AboutDialog.new_from_appdata] for details. + + + + + + + the parent widget + + + + The resource to use + + + + The version to retrieve release notes for + + + + the name of the first property + + + + value of first property, followed by more pairs of property name and + value, `NULL`-terminated + + + + + introspectable="0" + deprecated="1" + deprecated-version="1.6"> A convenience function for showing an application’s about window. + line="3488">A convenience function for showing an application’s about window. + Use [func@show_about_dialog]. @@ -37674,19 +48993,19 @@ library are set up properly. allow-none="1"> the parent top-level window + line="3490">the parent top-level window the name of the first property + line="3491">the name of the first property value of first property, followed by more pairs of property name and + line="3492">value of first property, followed by more pairs of property name and value, `NULL`-terminated @@ -37695,13 +49014,16 @@ library are set up properly. + introspectable="0" + deprecated="1" + deprecated-version="1.6"> A convenience function for showing an application’s about window from + line="3520">A convenience function for showing an application’s about window from AppStream metadata. See [ctor@AboutWindow.new_from_appdata] for details. + Use [func@show_about_dialog_from_appdata]. @@ -37713,13 +49035,13 @@ See [ctor@AboutWindow.new_from_appdata] for details. allow-none="1"> the parent top-level window + line="3522">the parent top-level window The resource to use + line="3523">The resource to use allow-none="1"> The version to retrieve release notes for + line="3524">The version to retrieve release notes for the name of the first property + line="3525">the name of the first property value of first property, followed by more pairs of property name and + line="3526">value of first property, followed by more pairs of property name and value, `NULL`-terminated diff --git a/generator/src/main/resources/gir/GLib-2.0.gir b/generator/src/main/resources/gir/GLib-2.0.gir index c4b5af0..796fb6c 100644 --- a/generator/src/main/resources/gir/GLib-2.0.gir +++ b/generator/src/main/resources/gir/GLib-2.0.gir @@ -5,95 +5,121 @@ and/or use gtk-doc annotations. --> + + c:symbol-prefixes="glib,g"> Integer representing a day of the month; between 1 and 31. + filename="glib/gdate.c" + line="179">Integer representing a day of the month; between 1 and 31. The %G_DATE_BAD_DAY value represents an invalid day of the month. - + Integer type representing a year. + filename="glib/gdate.c" + line="207">Integer type representing a year. The %G_DATE_BAD_YEAR value is the invalid value. The year must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era)) years are not allowed. The year is represented with four digits. - + Opaque type. See g_main_context_pusher_new() for details. - + filename="glib/gmain.h" + line="582">Opaque type. See g_main_context_pusher_new() for details. + Opaque type. See g_mutex_locker_new() for details. - + filename="glib/gthread.h" + line="312">Opaque type. See g_mutex_locker_new() for details. + A type which is used to hold a process identification. + filename="glib/gmain.h" + line="159">A type which is used to hold a process identification. On UNIX, processes are identified by a process id (an integer), while Windows uses process handles (which are pointers). GPid is used in GLib only for descendant processes spawned with the g_spawn functions. - + A GQuark is a non-zero integer which uniquely identifies a -particular string. A GQuark value of zero is associated to %NULL. - + filename="glib/gquark.c" + line="70">A GQuark is a non-zero integer which uniquely identifies a +particular string. + +A GQuark value of zero is associated to `NULL`. + +Given either the string or the `GQuark` identifier it is possible to +retrieve the other. + +Quarks are used for both +[datasets and keyed data lists](datalist-and-dataset.html). + +To create a new quark from a string, use [func@GLib.quark_from_string] +or [func@GLib.quark_from_static_string]. + +To find the string corresponding to a given `GQuark`, use +[func@GLib.quark_to_string]. + +To find the `GQuark` corresponding to a given string, use +[func@GLib.quark_try_string]. + +Another use for the string pool maintained for the quark functions +is string interning, using [func@GLib.intern_string] or +[func@GLib.intern_static_string]. An interned string is a canonical +representation for a string. One important advantage of interned +strings is that they can be compared for equality by a simple +pointer comparison, rather than using `strcmp()`. + Opaque type. See g_rw_lock_reader_locker_new() for details. - + filename="glib/gthread.h" + line="718">Opaque type. See g_rw_lock_reader_locker_new() for details. + Opaque type. See g_rw_lock_writer_locker_new() for details. - + filename="glib/gthread.h" + line="560">Opaque type. See g_rw_lock_writer_locker_new() for details. + Opaque type. See g_rec_mutex_locker_new() for details. - + filename="glib/gthread.h" + line="434">Opaque type. See g_rec_mutex_locker_new() for details. + A typedef for a reference-counted string. A pointer to a #GRefString can be treated like a standard `char*` array by all code, but can additionally have `g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be @@ -101,21 +127,21 @@ called on `char*` arrays not allocated using g_ref_string_new(). If using #GRefString with autocleanups, g_autoptr() must be used rather than g_autofree(), so that the reference counting metadata is also freed. - + A typedef alias for gchar**. This is mostly useful when used together with -g_auto(). - + filename="glib/gstrfuncs.c" + line="2535">A typedef alias for gchar**. This is mostly useful when used together with +`g_auto()`. + Simply a replacement for `time_t`. It has been deprecated + filename="glib/gdate.c" + line="140">Simply a replacement for `time_t`. It has been deprecated since it is not equivalent to `time_t` on 64-bit platforms with a 64-bit `time_t`. @@ -138,27 +164,23 @@ gtime = (GTime)ttime; ]| This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem). Use #GDateTime or #time_t instead. - + A value representing an interval of time, in microseconds. - + - - - - Return the minimal alignment required by the platform ABI for values of the given + filename="glib/gmacros.h" + line="1010">Return the minimal alignment required by the platform ABI for values of the given type. The address of a variable or struct member of the given type must always be a multiple of this alignment. For example, most platforms require int variables to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms. @@ -167,19 +189,39 @@ Note this is not necessarily the same as the value returned by GCC’s `__alignof__` operator, which returns the preferred alignment for a type. The preferred alignment may be a stricter alignment than the minimal alignment. - + a type-name + filename="glib/gmacros.h" + line="1012">a type-name + + + + + + + + + + + + + + + + + + + + - + version="2.58" introspectable="0"> Evaluates to a truth value if the absolute difference between @a and @b is + filename="glib/docs.c" + line="993">Evaluates to a truth value if the absolute difference between @a and @b is smaller than @epsilon, and to a false value otherwise. For example, @@ -196,22 +238,22 @@ For example, - `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false - `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within the single precision floating point epsilon from zero - + a numeric value + filename="glib/docs.c" + line="995">a numeric value a numeric value + filename="glib/docs.c" + line="996">a numeric value a numeric value that expresses the tolerance between @a and @b + filename="glib/docs.c" + line="997">a numeric value that expresses the tolerance between @a and @b @@ -219,22 +261,22 @@ For example, value="39" c:type="G_ASCII_DTOSTR_BUF_SIZE"> A good size for a buffer to be passed into g_ascii_dtostr(). + filename="glib/gstrfuncs.c" + line="230">A good size for a buffer to be passed into [func@GLib.ascii_dtostr]. It is guaranteed to be enough for all output of that function on systems with 64bit IEEE-compatible doubles. The typical usage would be something like: -|[<!-- language="C" --> - char buf[G_ASCII_DTOSTR_BUF_SIZE]; +```C +char buf[G_ASCII_DTOSTR_BUF_SIZE]; - fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); -]| - +fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); +``` + - + @@ -245,7 +287,7 @@ The typical usage would be something like: c:type="G_ATOMIC_REF_COUNT_INIT" version="2.78"> Evaluates to the initial reference count for `gatomicrefcount`. This macro is useful for initializing `gatomicrefcount` fields inside @@ -264,29 +306,78 @@ static const Person default_person = { .address = "Default address", }; ]| - + + + Works like [func@GLib.MUTEX_AUTO_LOCK], but for a lock defined with +[func@GLib.LOCK_DEFINE]. + +This feature is only supported on GCC and clang. This macro is not defined on +other compilers and should not be used in programs that are intended to be +portable to those compilers. + + + + the name of the lock + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Contains the public fields of a GArray. - + filename="glib/garray.c" + line="54">Contains the public fields of a GArray. + a pointer to the element data. The data may be moved as + filename="glib/garray.c" + line="56">a pointer to the element data. The data may be moved as elements are added to the #GArray. the number of elements in the #GArray not including the + filename="glib/garray.c" + line="58">the number of elements in the #GArray not including the possible terminating zero element. @@ -294,13 +385,13 @@ static const Person default_person = { c:identifier="g_array_append_vals" introspectable="0"> Adds @len elements onto the end of the array. - + filename="glib/garray.c" + line="564">Adds @len elements onto the end of the array. + the #GArray + filename="glib/garray.c" + line="572">the #GArray @@ -308,22 +399,22 @@ static const Person default_person = { a #GArray + filename="glib/garray.c" + line="566">a #GArray a pointer to the elements to append to the end of the array + filename="glib/garray.c" + line="567">a pointer to the elements to append to the end of the array the number of elements to append + filename="glib/garray.c" + line="568">the number of elements to append @@ -333,8 +424,8 @@ static const Person default_person = { version="2.62" introspectable="0"> Checks whether @target exists in @array by performing a binary + filename="glib/garray.c" + line="967">Checks whether @target exists in @array by performing a binary search based on the given comparison function @compare_func which get pointers to items as arguments. If the element is found, %TRUE is returned and the element’s index is returned in @out_match_index @@ -360,18 +451,18 @@ guint matched_index; gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index); ... ]| - + %TRUE if @target is one of the elements of @array, %FALSE otherwise. + filename="glib/garray.c" + line="1002">%TRUE if @target is one of the elements of @array, %FALSE otherwise. a #GArray. + filename="glib/garray.c" + line="969">a #GArray. @@ -381,14 +472,14 @@ gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_in nullable="1" allow-none="1"> a pointer to the item to look up. + filename="glib/garray.c" + line="970">a pointer to the item to look up. A #GCompareFunc used to locate @target. + filename="glib/garray.c" + line="971">A #GCompareFunc used to locate @target. return location + filename="glib/garray.c" + line="972">return location for the index of the element, if found. @@ -410,14 +501,14 @@ gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_in version="2.62" introspectable="0"> Create a shallow copy of a #GArray. If the array elements consist of + filename="glib/garray.c" + line="1569">Create a shallow copy of a #GArray. If the array elements consist of pointers to data, the pointers are copied but the actual data is not. - + A copy of @array. + filename="glib/garray.c" + line="1576">A copy of @array. @@ -425,8 +516,8 @@ pointers to data, the pointers are copied but the actual data is not. A #GArray. + filename="glib/garray.c" + line="1571">A #GArray. @@ -435,8 +526,8 @@ pointers to data, the pointers are copied but the actual data is not. Frees the memory allocated for the #GArray. If @free_segment is + filename="glib/garray.c" + line="487">Frees the memory allocated for the #GArray. If @free_segment is %TRUE it frees the memory block holding the elements as well. Pass %FALSE if you want to free the #GArray wrapper but preserve the underlying array for use elsewhere. If the reference count of @@ -444,33 +535,33 @@ underlying array for use elsewhere. If the reference count of the size of @array will be set to zero. If array contents point to dynamically-allocated memory, they should -be freed separately if @free_seg is %TRUE and no @clear_func +be freed separately if @free_segment is %TRUE and no @clear_func function has been set for @array. This function is not thread-safe. If using a #GArray from multiple threads, use only the atomic g_array_ref() and g_array_unref() functions. - + the element data if @free_segment is %FALSE, otherwise + filename="glib/garray.c" + line="507">the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free(). a #GArray + filename="glib/garray.c" + line="489">a #GArray if %TRUE the actual element data is freed as well + filename="glib/garray.c" + line="490">if %TRUE the actual element data is freed as well @@ -480,20 +571,20 @@ functions. version="2.22" introspectable="0"> Gets the size of the elements in @array. - + filename="glib/garray.c" + line="467">Gets the size of the elements in @array. + Size of each element, in bytes + filename="glib/garray.c" + line="473">Size of each element, in bytes A #GArray + filename="glib/garray.c" + line="469">A #GArray @@ -504,8 +595,8 @@ functions. c:identifier="g_array_insert_vals" introspectable="0"> Inserts @len elements into a #GArray at the given index. + filename="glib/garray.c" + line="673">Inserts @len elements into a #GArray at the given index. If @index_ is greater than the array’s current length, the array is expanded. The elements between the old end of the array and the newly inserted elements @@ -518,11 +609,11 @@ upwards. @data may be %NULL if (and only if) @len is zero. If @len is zero, this function is a no-op. - + the #GArray + filename="glib/garray.c" + line="694">the #GArray @@ -530,16 +621,16 @@ function is a no-op. a #GArray + filename="glib/garray.c" + line="675">a #GArray the index to place the elements at + filename="glib/garray.c" + line="676">the index to place the elements at nullable="1" allow-none="1"> a pointer to the elements to insert + filename="glib/garray.c" + line="677">a pointer to the elements to insert the number of elements to insert + filename="glib/garray.c" + line="678">the number of elements to insert Creates a new #GArray with a reference count of 1. - + filename="glib/garray.c" + line="122">Creates a new #GArray with a reference count of 1. + the new #GArray + filename="glib/garray.c" + line="132">the new #GArray @@ -575,22 +666,22 @@ function is a no-op. %TRUE if the array should have an extra element at + filename="glib/garray.c" + line="124">%TRUE if the array should have an extra element at the end which is set to 0 %TRUE if #GArray elements should be automatically cleared + filename="glib/garray.c" + line="126">%TRUE if #GArray elements should be automatically cleared to 0 when they are allocated the size of each element in bytes + filename="glib/garray.c" + line="128">the size of each element in bytes @@ -600,8 +691,8 @@ function is a no-op. version="2.76" introspectable="0"> Creates a new #GArray with @data as array data, @len as length and a + filename="glib/garray.c" + line="147">Creates a new #GArray with @data as array data, @len as length and a reference count of 1. This avoids having to copy the data manually, when it can just be @@ -617,11 +708,11 @@ such task. Do not use it if @len or @element_size are greater than %G_MAXUINT. #GArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GArray + filename="glib/garray.c" + line="173">A new #GArray @@ -632,8 +723,8 @@ than #gsize. nullable="1" allow-none="1"> an array of + filename="glib/garray.c" + line="149">an array of elements of @element_size, or %NULL for an empty array @@ -641,21 +732,21 @@ than #gsize. the number of elements in @data + filename="glib/garray.c" + line="151">the number of elements in @data %TRUE if #GArray elements should be automatically cleared + filename="glib/garray.c" + line="152">%TRUE if #GArray elements should be automatically cleared to 0 when they are allocated the size of each element in bytes + filename="glib/garray.c" + line="154">the size of each element in bytes @@ -665,8 +756,8 @@ than #gsize. version="2.76" introspectable="0"> Creates a new #GArray with @data as array data, computing the length of it + filename="glib/garray.c" + line="199">Creates a new #GArray with @data as array data, computing the length of it and setting the reference count to 1. This avoids having to copy the data manually, when it can just be @@ -685,11 +776,11 @@ such task. Do not use it if @data length or @element_size are greater than %G_MAXUINT. #GArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GArray + filename="glib/garray.c" + line="226">A new #GArray @@ -697,23 +788,23 @@ than #gsize. an array of elements of @element_size + filename="glib/garray.c" + line="201">an array of elements of @element_size %TRUE if #GArray elements should be automatically cleared + filename="glib/garray.c" + line="202">%TRUE if #GArray elements should be automatically cleared to 0 when they are allocated the size of each element in bytes + filename="glib/garray.c" + line="204">the size of each element in bytes @@ -722,8 +813,8 @@ than #gsize. c:identifier="g_array_prepend_vals" introspectable="0"> Adds @len elements onto the start of the array. + filename="glib/garray.c" + line="612">Adds @len elements onto the start of the array. @data may be %NULL if (and only if) @len is zero. If @len is zero, this function is a no-op. @@ -731,11 +822,11 @@ function is a no-op. This operation is slower than g_array_append_vals() since the existing elements in the array have to be moved to make space for the new elements. - + the #GArray + filename="glib/garray.c" + line="627">the #GArray @@ -743,8 +834,8 @@ the new elements. a #GArray + filename="glib/garray.c" + line="614">a #GArray @@ -754,14 +845,14 @@ the new elements. nullable="1" allow-none="1"> a pointer to the elements to prepend to the start of the array + filename="glib/garray.c" + line="615">a pointer to the elements to prepend to the start of the array the number of elements to prepend, which may be zero + filename="glib/garray.c" + line="616">the number of elements to prepend, which may be zero @@ -771,14 +862,14 @@ the new elements. version="2.22" introspectable="0"> Atomically increments the reference count of @array by one. + filename="glib/garray.c" + line="416">Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. - + The passed in #GArray + filename="glib/garray.c" + line="423">The passed in #GArray @@ -786,8 +877,8 @@ This function is thread-safe and may be called from any thread. A #GArray + filename="glib/garray.c" + line="418">A #GArray @@ -798,14 +889,14 @@ This function is thread-safe and may be called from any thread. c:identifier="g_array_remove_index" introspectable="0"> Removes the element at the given index from a #GArray. The following + filename="glib/garray.c" + line="781">Removes the element at the given index from a #GArray. The following elements are moved down one place. - + the #GArray + filename="glib/garray.c" + line="789">the #GArray @@ -813,16 +904,16 @@ elements are moved down one place. a #GArray + filename="glib/garray.c" + line="783">a #GArray the index of the element to remove + filename="glib/garray.c" + line="784">the index of the element to remove @@ -831,16 +922,16 @@ elements are moved down one place. c:identifier="g_array_remove_index_fast" introspectable="0"> Removes the element at the given index from a #GArray. The last + filename="glib/garray.c" + line="819">Removes the element at the given index from a #GArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the #GArray. But it is faster than g_array_remove_index(). - + the #GArray + filename="glib/garray.c" + line="829">the #GArray @@ -848,16 +939,16 @@ g_array_remove_index(). a @GArray + filename="glib/garray.c" + line="821">a @GArray the index of the element to remove + filename="glib/garray.c" + line="822">the index of the element to remove @@ -867,14 +958,14 @@ g_array_remove_index(). version="2.4" introspectable="0"> Removes the given number of elements starting at the given index + filename="glib/garray.c" + line="859">Removes the given number of elements starting at the given index from a #GArray. The following elements are moved to close the gap. - + the #GArray + filename="glib/garray.c" + line="868">the #GArray @@ -882,22 +973,22 @@ from a #GArray. The following elements are moved to close the gap. a @GArray + filename="glib/garray.c" + line="861">a @GArray the index of the first element to remove + filename="glib/garray.c" + line="862">the index of the first element to remove the number of elements to remove + filename="glib/garray.c" + line="863">the number of elements to remove @@ -907,8 +998,8 @@ from a #GArray. The following elements are moved to close the gap. version="2.32" introspectable="0"> Sets a function to clear an element of @array. + filename="glib/garray.c" + line="366">Sets a function to clear an element of @array. The @clear_func will be called when an element in the array data segment is removed and when the array is freed and data @@ -939,23 +1030,23 @@ g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear); // assign data to the structure g_array_free (garray, TRUE); ]| - + A #GArray + filename="glib/garray.c" + line="368">A #GArray a function to clear an element of @array + filename="glib/garray.c" + line="369">a function to clear an element of @array @@ -964,14 +1055,14 @@ g_array_free (garray, TRUE); c:identifier="g_array_set_size" introspectable="0"> Sets the size of the array, expanding it if necessary. If the array + filename="glib/garray.c" + line="746">Sets the size of the array, expanding it if necessary. If the array was created with @clear_ set to %TRUE, the new elements are set to 0. - + the #GArray + filename="glib/garray.c" + line="754">the #GArray @@ -979,16 +1070,16 @@ was created with @clear_ set to %TRUE, the new elements are set to 0. a #GArray + filename="glib/garray.c" + line="748">a #GArray the new size of the #GArray + filename="glib/garray.c" + line="749">the new size of the #GArray @@ -997,16 +1088,16 @@ was created with @clear_ set to %TRUE, the new elements are set to 0. c:identifier="g_array_sized_new" introspectable="0"> Creates a new #GArray with @reserved_size elements preallocated and + filename="glib/garray.c" + line="315">Creates a new #GArray with @reserved_size elements preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many elements to the array. Note however that the size of the array is still 0. - + the new #GArray + filename="glib/garray.c" + line="329">the new #GArray @@ -1014,58 +1105,58 @@ size of the array is still 0. %TRUE if the array should have an extra element at + filename="glib/garray.c" + line="317">%TRUE if the array should have an extra element at the end with all bits cleared %TRUE if all bits in the array should be cleared to 0 on + filename="glib/garray.c" + line="319">%TRUE if all bits in the array should be cleared to 0 on allocation size of each element in the array + filename="glib/garray.c" + line="321">size of each element in the array number of elements preallocated + filename="glib/garray.c" + line="322">number of elements preallocated Sorts a #GArray using @compare_func which should be a qsort()-style + filename="glib/garray.c" + line="906">Sorts a #GArray using @compare_func which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater zero if first arg is greater than second arg). This is guaranteed to be a stable sort since version 2.32. - + a #GArray + filename="glib/garray.c" + line="908">a #GArray comparison function + filename="glib/garray.c" + line="909">comparison function @@ -1074,8 +1165,8 @@ This is guaranteed to be a stable sort since version 2.32. c:identifier="g_array_sort_with_data" introspectable="0"> Like g_array_sort(), but the comparison function receives an extra + filename="glib/garray.c" + line="935">Like g_array_sort(), but the comparison function receives an extra user data argument. This is guaranteed to be a stable sort since version 2.32. @@ -1083,23 +1174,23 @@ This is guaranteed to be a stable sort since version 2.32. There used to be a comment here about making the sort stable by using the addresses of the elements in the comparison function. This did not actually work, so any such code should be removed. - + a #GArray + filename="glib/garray.c" + line="937">a #GArray comparison function + filename="glib/garray.c" + line="938">comparison function nullable="1" allow-none="1"> data to pass to @compare_func + filename="glib/garray.c" + line="939">data to pass to @compare_func @@ -1118,8 +1209,8 @@ This did not actually work, so any such code should be removed. version="2.64" introspectable="0"> Frees the data in the array and resets the size to zero, while + filename="glib/garray.c" + line="264">Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. @@ -1137,19 +1228,19 @@ gsize data_len; data = g_array_steal (some_array, &data_len); ... ]| - + the element data, which should be + filename="glib/garray.c" + line="289">the element data, which should be freed using g_free(). a #GArray. + filename="glib/garray.c" + line="266">a #GArray. @@ -1161,8 +1252,8 @@ data = g_array_steal (some_array, &data_len); optional="1" allow-none="1"> pointer to retrieve the number of + filename="glib/garray.c" + line="267">pointer to retrieve the number of elements of the original array @@ -1173,20 +1264,20 @@ data = g_array_steal (some_array, &data_len); version="2.22" introspectable="0"> Atomically decrements the reference count of @array by one. If the -reference count drops to 0, all memory allocated by the array is -released. This function is thread-safe and may be called from any -thread. - + filename="glib/garray.c" + line="446">Atomically decrements the reference count of @array by one. If the +reference count drops to 0, the effect is the same as calling +g_array_free() with @free_segment set to %TRUE. This function is +thread-safe and may be called from any thread. + A #GArray + filename="glib/garray.c" + line="448">A #GArray @@ -1195,7 +1286,7 @@ thread. - + @@ -1219,17 +1310,22 @@ thread. - + An opaque data structure which represents an asynchronous queue. + filename="glib/gasyncqueue.c" + line="40">An opaque data structure which represents an asynchronous queue. It should only be accessed through the `g_async_queue_*` functions. - + Returns the length of the queue. + filename="glib/gasyncqueue.c" + line="618">Returns the length of the queue. Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative @@ -1237,18 +1333,18 @@ value means waiting threads, and a positive value means available entries in the @queue. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling. - + the length of the @queue + filename="glib/gasyncqueue.c" + line="631">the length of the @queue a #GAsyncQueue. + filename="glib/gasyncqueue.c" + line="620">a #GAsyncQueue. @@ -1256,8 +1352,8 @@ of the queue or due to scheduling. Returns the length of the queue. + filename="glib/gasyncqueue.c" + line="647">Returns the length of the queue. Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative @@ -1267,26 +1363,26 @@ in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling. This function must be called while holding the @queue's lock. - + the length of the @queue. + filename="glib/gasyncqueue.c" + line="662">the length of the @queue. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="649">a #GAsyncQueue Acquires the @queue's lock. If another thread is already + filename="glib/gasyncqueue.c" + line="191">Acquires the @queue's lock. If another thread is already holding the lock, this call will block until the lock becomes available. @@ -1295,84 +1391,84 @@ Call g_async_queue_unlock() to drop the lock again. While holding the lock, you can only call the g_async_queue_*_unlocked() functions on @queue. Otherwise, deadlock may occur. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="193">a #GAsyncQueue Pops data from the @queue. If @queue is empty, this function + filename="glib/gasyncqueue.c" + line="392">Pops data from the @queue. If @queue is empty, this function blocks until data becomes available. - + data from the queue + filename="glib/gasyncqueue.c" + line="399">data from the queue a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="394">a #GAsyncQueue Pops data from the @queue. If @queue is empty, this function + filename="glib/gasyncqueue.c" + line="415">Pops data from the @queue. If @queue is empty, this function blocks until data becomes available. This function must be called while holding the @queue's lock. - + data from the queue. + filename="glib/gasyncqueue.c" + line="424">data from the queue. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="417">a #GAsyncQueue Pushes the @data into the @queue. + filename="glib/gasyncqueue.c" + line="231">Pushes the @data into the @queue. The @data parameter must not be %NULL. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="233">a #GAsyncQueue data to push onto the @queue + filename="glib/gasyncqueue.c" + line="234">data to push onto the @queue @@ -1381,26 +1477,26 @@ The @data parameter must not be %NULL. c:identifier="g_async_queue_push_front" version="2.46"> Pushes the @item into the @queue. @item must not be %NULL. + filename="glib/gasyncqueue.c" + line="802">Pushes the @item into the @queue. @item must not be %NULL. In contrast to g_async_queue_push(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="804">a #GAsyncQueue data to push into the @queue + filename="glib/gasyncqueue.c" + line="805">data to push into the @queue @@ -1409,39 +1505,38 @@ so that it will be the next one to be popped off the queue. c:identifier="g_async_queue_push_front_unlocked" version="2.46"> Pushes the @item into the @queue. @item must not be %NULL. + filename="glib/gasyncqueue.c" + line="826">Pushes the @item into the @queue. @item must not be %NULL. In contrast to g_async_queue_push_unlocked(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue. This function must be called while holding the @queue's lock. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="828">a #GAsyncQueue data to push into the @queue + filename="glib/gasyncqueue.c" + line="829">data to push into the @queue + version="2.10"> Inserts @data into @queue using @func to determine the new + filename="glib/gasyncqueue.c" + line="275">Inserts @data into @queue using @func to determine the new position. This function requires that the @queue is sorted before pushing on @@ -1451,27 +1546,30 @@ This function will lock @queue before it sorts the queue and unlock it when it is finished. For an example of @func see g_async_queue_sort(). - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="277">a #GAsyncQueue the @data to push into the @queue + filename="glib/gasyncqueue.c" + line="278">the @data to push into the @queue - + the #GCompareDataFunc is used to sort @queue + filename="glib/gasyncqueue.c" + line="279">the #GCompareDataFunc is used to sort @queue nullable="1" allow-none="1"> user data passed to @func. + filename="glib/gasyncqueue.c" + line="280">user data passed to @func. + version="2.10"> Inserts @data into @queue using @func to determine the new + filename="glib/gasyncqueue.c" + line="316">Inserts @data into @queue using @func to determine the new position. The sort function @func is passed two elements of the @queue. @@ -1506,15 +1603,15 @@ new elements, see g_async_queue_sort(). This function must be called while holding the @queue's lock. For an example of @func see g_async_queue_sort(). - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="318">a #GAsyncQueue nullable="1" allow-none="1"> the data to push into the @queue + filename="glib/gasyncqueue.c" + line="319">the data to push into the @queue - + the #GCompareDataFunc is used to sort @queue + filename="glib/gasyncqueue.c" + line="320">the #GCompareDataFunc is used to sort @queue nullable="1" allow-none="1"> user data passed to @func. + filename="glib/gasyncqueue.c" + line="321">user data passed to @func. Pushes the @data into the @queue. + filename="glib/gasyncqueue.c" + line="252">Pushes the @data into the @queue. The @data parameter must not be %NULL. This function must be called while holding the @queue's lock. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="254">a #GAsyncQueue data to push onto the @queue + filename="glib/gasyncqueue.c" + line="255">data to push onto the @queue - + Increases the reference count of the asynchronous @queue by 1. + filename="glib/gasyncqueue.c" + line="104">Increases the reference count of the asynchronous @queue by 1. You do not need to hold the lock to call this function. - - + + the @queue that was passed in (since 2.6) + filename="glib/gasyncqueue.c" + line="111">the @queue that was passed in (since 2.6) a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="106">a #GAsyncQueue @@ -1596,46 +1696,46 @@ You do not need to hold the lock to call this function. deprecated="1" deprecated-version="2.8"> Increases the reference count of the asynchronous @queue by 1. + filename="glib/gasyncqueue.c" + line="123">Increases the reference count of the asynchronous @queue by 1. Reference counting is done atomically. so g_async_queue_ref() can be used regardless of the @queue's lock. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="125">a #GAsyncQueue Remove an item from the queue. - + filename="glib/gasyncqueue.c" + line="752">Remove an item from the queue. + %TRUE if the item was removed + filename="glib/gasyncqueue.c" + line="759">%TRUE if the item was removed a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="754">a #GAsyncQueue the data to remove from the @queue + filename="glib/gasyncqueue.c" + line="755">the data to remove from the @queue @@ -1644,22 +1744,22 @@ lock. c:identifier="g_async_queue_remove_unlocked" version="2.46"> Remove an item from the queue. + filename="glib/gasyncqueue.c" + line="779">Remove an item from the queue. This function must be called while holding the @queue's lock. - + %TRUE if the item was removed + filename="glib/gasyncqueue.c" + line="788">%TRUE if the item was removed a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="781">a #GAsyncQueue nullable="1" allow-none="1"> the data to remove from the @queue + filename="glib/gasyncqueue.c" + line="782">the data to remove from the @queue - + Sorts @queue using @func. + filename="glib/gasyncqueue.c" + line="672">Sorts @queue using @func. The sort function @func is passed two elements of the @queue. It should return 0 if they are equal, a negative value if the @@ -1701,21 +1798,24 @@ lowest priority would be at the top of the queue, you could use: return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); ]| - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="674">a #GAsyncQueue - + the #GCompareDataFunc is used to sort @queue + filename="glib/gasyncqueue.c" + line="675">the #GCompareDataFunc is used to sort @queue user data passed to @func + filename="glib/gasyncqueue.c" + line="676">user data passed to @func + version="2.10"> Sorts @queue using @func. + filename="glib/gasyncqueue.c" + line="716">Sorts @queue using @func. The sort function @func is passed two elements of the @queue. It should return 0 if they are equal, a negative value if the @@ -1744,21 +1843,24 @@ if the first element should be lower in the @queue than the second element. This function must be called while holding the @queue's lock. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="718">a #GAsyncQueue - + the #GCompareDataFunc is used to sort @queue + filename="glib/gasyncqueue.c" + line="719">the #GCompareDataFunc is used to sort @queue nullable="1" allow-none="1"> user data passed to @func + filename="glib/gasyncqueue.c" + line="720">user data passed to @func @@ -1776,8 +1878,8 @@ This function must be called while holding the @queue's lock. c:identifier="g_async_queue_timed_pop" deprecated="1"> Pops data from the @queue. If the queue is empty, blocks until + filename="glib/gasyncqueue.c" + line="533">Pops data from the @queue. If the queue is empty, blocks until @end_time or until data becomes available. If no data is received before @end_time, %NULL is returned. @@ -1785,25 +1887,25 @@ If no data is received before @end_time, %NULL is returned. To easily calculate @end_time, a combination of g_get_real_time() and g_time_val_add() can be used. use g_async_queue_timeout_pop(). - + data from the queue or %NULL, when no data is + filename="glib/gasyncqueue.c" + line="546">data from the queue or %NULL, when no data is received before @end_time. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="535">a #GAsyncQueue a #GTimeVal, determining the final time + filename="glib/gasyncqueue.c" + line="536">a #GTimeVal, determining the final time @@ -1812,8 +1914,8 @@ and g_time_val_add() can be used. c:identifier="g_async_queue_timed_pop_unlocked" deprecated="1"> Pops data from the @queue. If the queue is empty, blocks until + filename="glib/gasyncqueue.c" + line="577">Pops data from the @queue. If the queue is empty, blocks until @end_time or until data becomes available. If no data is received before @end_time, %NULL is returned. @@ -1823,55 +1925,55 @@ and g_time_val_add() can be used. This function must be called while holding the @queue's lock. use g_async_queue_timeout_pop_unlocked(). - + data from the queue or %NULL, when no data is + filename="glib/gasyncqueue.c" + line="592">data from the queue or %NULL, when no data is received before @end_time. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="579">a #GAsyncQueue a #GTimeVal, determining the final time + filename="glib/gasyncqueue.c" + line="580">a #GTimeVal, determining the final time Pops data from the @queue. If the queue is empty, blocks for + filename="glib/gasyncqueue.c" + line="478">Pops data from the @queue. If the queue is empty, blocks for @timeout microseconds, or until data becomes available. If no data is received before the timeout, %NULL is returned. - + data from the queue or %NULL, when no data is + filename="glib/gasyncqueue.c" + line="488">data from the queue or %NULL, when no data is received before the timeout. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="480">a #GAsyncQueue the number of microseconds to wait + filename="glib/gasyncqueue.c" + line="481">the number of microseconds to wait @@ -1879,54 +1981,54 @@ If no data is received before the timeout, %NULL is returned. Pops data from the @queue. If the queue is empty, blocks for + filename="glib/gasyncqueue.c" + line="507">Pops data from the @queue. If the queue is empty, blocks for @timeout microseconds, or until data becomes available. If no data is received before the timeout, %NULL is returned. This function must be called while holding the @queue's lock. - + data from the queue or %NULL, when no data is + filename="glib/gasyncqueue.c" + line="519">data from the queue or %NULL, when no data is received before the timeout. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="509">a #GAsyncQueue the number of microseconds to wait + filename="glib/gasyncqueue.c" + line="510">the number of microseconds to wait Tries to pop data from the @queue. If no data is available, + filename="glib/gasyncqueue.c" + line="434">Tries to pop data from the @queue. If no data is available, %NULL is returned. - + data from the queue or %NULL, when no data is + filename="glib/gasyncqueue.c" + line="441">data from the queue or %NULL, when no data is available immediately. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="436">a #GAsyncQueue @@ -1934,67 +2036,67 @@ This function must be called while holding the @queue's lock. Tries to pop data from the @queue. If no data is available, + filename="glib/gasyncqueue.c" + line="458">Tries to pop data from the @queue. If no data is available, %NULL is returned. This function must be called while holding the @queue's lock. - + data from the queue or %NULL, when no data is + filename="glib/gasyncqueue.c" + line="467">data from the queue or %NULL, when no data is available immediately. a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="460">a #GAsyncQueue Releases the queue's lock. + filename="glib/gasyncqueue.c" + line="213">Releases the queue's lock. Calling this function when you have not acquired the with g_async_queue_lock() leads to undefined behaviour. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="215">a #GAsyncQueue Decreases the reference count of the asynchronous @queue by 1. + filename="glib/gasyncqueue.c" + line="163">Decreases the reference count of the asynchronous @queue by 1. If the reference count went to 0, the @queue will be destroyed and the memory allocated will be freed. So you are not allowed to use the @queue afterwards, as it might have disappeared. You do not need to hold the lock to call this function. - + - + a #GAsyncQueue. + filename="glib/gasyncqueue.c" + line="165">a #GAsyncQueue. @@ -2004,53 +2106,52 @@ You do not need to hold the lock to call this function. deprecated="1" deprecated-version="2.8"> Decreases the reference count of the asynchronous @queue by 1 + filename="glib/gasyncqueue.c" + line="141">Decreases the reference count of the asynchronous @queue by 1 and releases the lock. This function must be called while holding the @queue's lock. If the reference count went to 0, the @queue will be destroyed and the memory allocated will be freed. Reference counting is done atomically. so g_async_queue_unref() can be used regardless of the @queue's lock. - + a #GAsyncQueue + filename="glib/gasyncqueue.c" + line="143">a #GAsyncQueue - + Creates a new asynchronous queue. - - + filename="glib/gasyncqueue.c" + line="63">Creates a new asynchronous queue. + + a new #GAsyncQueue. Free with g_async_queue_unref() + filename="glib/gasyncqueue.c" + line="68">a new #GAsyncQueue. Free with g_async_queue_unref() + version="2.16"> Creates a new asynchronous queue and sets up a destroy notify + filename="glib/gasyncqueue.c" + line="76">Creates a new asynchronous queue and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref. - - + + a new #GAsyncQueue. Free with g_async_queue_unref() + filename="glib/gasyncqueue.c" + line="84">a new #GAsyncQueue. Free with g_async_queue_unref() @@ -2060,8 +2161,8 @@ the queue is destroyed after the final unref. allow-none="1" scope="async"> function to free queue elements + filename="glib/gasyncqueue.c" + line="78">function to free queue elements @@ -2069,17 +2170,17 @@ the queue is destroyed after the final unref. Specifies one of the possible types of byte order. + filename="glib/docs.c" + line="116">Specifies one of the possible types of byte order. See %G_BYTE_ORDER. - + Inserts a breakpoint instruction into the code. On architectures which support it, this is implemented as a soft interrupt @@ -2087,32 +2188,34 @@ and on other architectures it raises a `SIGTRAP` signal. `SIGTRAP` is used rather than abort() to allow breakpoints to be skipped past in a debugger if they are not the desired target of debugging. - + GBookmarkFile lets you parse, edit or create files containing bookmarks -to URI, along with some meta-data about the resource pointed by the URI -like its MIME type, the application that is registering the bookmark and -the icon that should be used to represent the bookmark. The data is stored -using the -[Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). + filename="glib/gbookmarkfile.h" + line="75">`GBookmarkFile` lets you parse, edit or create files containing bookmarks. + +Bookmarks refer to a URI, along with some meta-data about the resource +pointed by the URI like its MIME type, the application that is registering +the bookmark and the icon that should be used to represent the bookmark. +The data is stored using the +[Desktop Bookmark Specification](https://www.freedesktop.org/wiki/Specifications/desktop-bookmark-spec/). The syntax of the bookmark files is described in detail inside the Desktop Bookmark Specification, here is a quick summary: bookmark files use a sub-class of the XML Bookmark Exchange Language specification, consisting of valid UTF-8 encoded XML, under the -<xbel> root element; each bookmark is stored inside a -<bookmark> element, using its URI: no relative paths can +`<xbel>` root element; each bookmark is stored inside a +`<bookmark>` element, using its URI: no relative paths can be used inside a bookmark file. The bookmark may have a user defined title and description, to be used instead of the URI. Under the -<metadata> element, with its owner attribute set to +`<metadata>` element, with its owner attribute set to `http://freedesktop.org`, is stored the meta-data about a resource pointed by its URI. The meta-data consists of the resource's MIME type; the applications that have registered a bookmark; the groups @@ -2129,28 +2232,26 @@ is accessed through its URI. The important caveat of bookmark files is that when you add a new bookmark you must also add the application that is registering it, using -g_bookmark_file_add_application() or g_bookmark_file_set_application_info(). +[method@GLib.BookmarkFile.add_application] or [method@GLib.BookmarkFile.set_application_info]. If a bookmark has no applications then it won't be dumped when creating -the on disk representation, using g_bookmark_file_to_data() or -g_bookmark_file_to_file(). - -The #GBookmarkFile parser was added in GLib 2.12. - +the on disk representation, using [method@GLib.BookmarkFile.to_data] or +[method@GLib.BookmarkFile.to_file]. + Creates a new empty #GBookmarkFile object. + filename="glib/gbookmarkfile.c" + line="1686">Creates a new empty #GBookmarkFile object. Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() or g_bookmark_file_load_from_data_dirs() to read an existing bookmark file. - + an empty #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="1695">an empty #GBookmarkFile @@ -2158,8 +2259,8 @@ file. c:identifier="g_bookmark_file_add_application" version="2.12"> Adds the application with @name and @exec to the list of + filename="glib/gbookmarkfile.c" + line="3264">Adds the application with @name and @exec to the list of applications that have registered a bookmark for @uri into @bookmark. @@ -2181,21 +2282,21 @@ with the same @name had already registered a bookmark for @uri inside @bookmark. If no bookmark for @uri is found, one is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3266">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3267">a valid URI nullable="1" allow-none="1"> the name of the application registering the bookmark + filename="glib/gbookmarkfile.c" + line="3268">the name of the application registering the bookmark or %NULL @@ -2213,8 +2314,8 @@ If no bookmark for @uri is found, one is created. nullable="1" allow-none="1"> command line to be used to launch the bookmark or %NULL + filename="glib/gbookmarkfile.c" + line="3270">command line to be used to launch the bookmark or %NULL @@ -2223,70 +2324,70 @@ If no bookmark for @uri is found, one is created. c:identifier="g_bookmark_file_add_group" version="2.12"> Adds @group to the list of groups to which the bookmark for @uri + filename="glib/gbookmarkfile.c" + line="3031">Adds @group to the list of groups to which the bookmark for @uri belongs to. If no bookmark for @uri is found then it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3033">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3034">a valid URI the group name to be added + filename="glib/gbookmarkfile.c" + line="3035">the group name to be added Deeply copies a @bookmark #GBookmarkFile object to a new one. - + filename="glib/gbookmarkfile.c" + line="1711">Deeply copies a @bookmark #GBookmarkFile object to a new one. + the copy of @bookmark. Use + filename="glib/gbookmarkfile.c" + line="1717">the copy of @bookmark. Use g_bookmark_free() when finished using it. A #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="1713">A #GBookmarkFile Frees a #GBookmarkFile. - + filename="glib/gbookmarkfile.c" + line="1747">Frees a #GBookmarkFile. + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="1749">a #GBookmarkFile @@ -2298,31 +2399,31 @@ If no bookmark for @uri is found then it is created. deprecated-version="2.66" throws="1"> Gets the time the bookmark for @uri was added to @bookmark + filename="glib/gbookmarkfile.c" + line="2646">Gets the time the bookmark for @uri was added to @bookmark In the event the URI cannot be found, -1 is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. Use g_bookmark_file_get_added_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. - + a timestamp - + filename="glib/gbookmarkfile.c" + line="2657">a timestamp + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2648">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2649">a valid URI @@ -2332,29 +2433,29 @@ In the event the URI cannot be found, -1 is returned and version="2.66" throws="1"> Gets the time the bookmark for @uri was added to @bookmark + filename="glib/gbookmarkfile.c" + line="2672">Gets the time the bookmark for @uri was added to @bookmark In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + a #GDateTime + filename="glib/gbookmarkfile.c" + line="2683">a #GDateTime a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2674">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2675">a valid URI @@ -2366,8 +2467,8 @@ In the event the URI cannot be found, %NULL is returned and deprecated-version="2.66" throws="1"> Gets the registration information of @app_name for the bookmark for + filename="glib/gbookmarkfile.c" + line="3683">Gets the registration information of @app_name for the bookmark for @uri. See g_bookmark_file_set_application_info() for more information about the returned data. @@ -2382,30 +2483,30 @@ the command line fails, an error of the %G_SHELL_ERROR domain is set and %FALSE is returned. Use g_bookmark_file_get_application_info() instead, as `time_t` is deprecated due to the year 2038 problem. - + %TRUE on success. + filename="glib/gbookmarkfile.c" + line="3707">%TRUE on success. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3685">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3686">a valid URI an application's name + filename="glib/gbookmarkfile.c" + line="3687">an application's name optional="1" allow-none="1"> return location for the command line of the application, or %NULL + filename="glib/gbookmarkfile.c" + line="3688">return location for the command line of the application, or %NULL optional="1" allow-none="1"> return location for the registration count, or %NULL + filename="glib/gbookmarkfile.c" + line="3689">return location for the registration count, or %NULL optional="1" allow-none="1"> return location for the last registration time, or %NULL - + filename="glib/gbookmarkfile.c" + line="3690">return location for the last registration time, or %NULL + @@ -2448,8 +2549,8 @@ set and %FALSE is returned. version="2.66" throws="1"> Gets the registration information of @app_name for the bookmark for + filename="glib/gbookmarkfile.c" + line="3735">Gets the registration information of @app_name for the bookmark for @uri. See g_bookmark_file_set_application_info() for more information about the returned data. @@ -2462,30 +2563,30 @@ for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the %G_SHELL_ERROR domain is set and %FALSE is returned. - + %TRUE on success. + filename="glib/gbookmarkfile.c" + line="3759">%TRUE on success. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3737">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3738">a valid URI an application's name + filename="glib/gbookmarkfile.c" + line="3739">an application's name optional="1" allow-none="1"> return location for the command line of the application, or %NULL + filename="glib/gbookmarkfile.c" + line="3740">return location for the command line of the application, or %NULL optional="1" allow-none="1"> return location for the registration count, or %NULL + filename="glib/gbookmarkfile.c" + line="3741">return location for the registration count, or %NULL optional="1" allow-none="1"> return location for the last registration time, or %NULL + filename="glib/gbookmarkfile.c" + line="3742">return location for the last registration time, or %NULL @@ -2528,17 +2629,17 @@ set and %FALSE is returned. version="2.12" throws="1"> Retrieves the names of the applications that have registered the + filename="glib/gbookmarkfile.c" + line="3837">Retrieves the names of the applications that have registered the bookmark for @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + a newly allocated %NULL-terminated array of strings. + filename="glib/gbookmarkfile.c" + line="3850">a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. @@ -2547,14 +2648,14 @@ In the event the URI cannot be found, %NULL is returned and a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3839">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3840">a valid URI return location of the length of the returned list, or %NULL + filename="glib/gbookmarkfile.c" + line="3841">return location of the length of the returned list, or %NULL @@ -2575,30 +2676,30 @@ In the event the URI cannot be found, %NULL is returned and version="2.12" throws="1"> Retrieves the description of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="2371">Retrieves the description of the bookmark for @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + a newly allocated string or %NULL if the specified + filename="glib/gbookmarkfile.c" + line="2382">a newly allocated string or %NULL if the specified URI cannot be found. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2373">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2374">a valid URI @@ -2608,19 +2709,19 @@ In the event the URI cannot be found, %NULL is returned and version="2.12" throws="1"> Retrieves the list of group names of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="3192">Retrieves the list of group names of the bookmark for @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. The returned array is %NULL terminated, so @length may optionally be %NULL. - + a newly allocated %NULL-terminated array of group names. + filename="glib/gbookmarkfile.c" + line="3207">a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. @@ -2629,14 +2730,14 @@ be %NULL. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3194">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3195">a valid URI optional="1" allow-none="1"> return location for the length of the returned string, or %NULL + filename="glib/gbookmarkfile.c" + line="3196">return location for the length of the returned string, or %NULL @@ -2657,30 +2758,30 @@ be %NULL. version="2.12" throws="1"> Gets the icon of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="4047">Gets the icon of the bookmark for @uri. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + %TRUE if the icon for the bookmark for the URI was found. + filename="glib/gbookmarkfile.c" + line="4060">%TRUE if the icon for the bookmark for the URI was found. You should free the returned strings. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="4049">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="4050">a valid URI return location for the icon's location or %NULL + filename="glib/gbookmarkfile.c" + line="4051">return location for the icon's location or %NULL return location for the icon's MIME type or %NULL + filename="glib/gbookmarkfile.c" + line="4052">return location for the icon's MIME type or %NULL @@ -2712,31 +2813,31 @@ In the event the URI cannot be found, %FALSE is returned and version="2.12" throws="1"> Gets whether the private flag of the bookmark for @uri is set. + filename="glib/gbookmarkfile.c" + line="2537">Gets whether the private flag of the bookmark for @uri is set. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that the private flag cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - + %TRUE if the private flag is set, %FALSE otherwise. + filename="glib/gbookmarkfile.c" + line="2550">%TRUE if the private flag is set, %FALSE otherwise. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2539">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2540">a valid URI @@ -2746,32 +2847,32 @@ event that the private flag cannot be found, %FALSE is returned and version="2.12" throws="1"> Retrieves the MIME type of the resource pointed by @uri. + filename="glib/gbookmarkfile.c" + line="2451">Retrieves the MIME type of the resource pointed by @uri. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that the MIME type cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - + a newly allocated string or %NULL if the specified + filename="glib/gbookmarkfile.c" + line="2464">a newly allocated string or %NULL if the specified URI cannot be found. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2453">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2454">a valid URI @@ -2783,31 +2884,31 @@ event that the MIME type cannot be found, %NULL is returned and deprecated-version="2.66" throws="1"> Gets the time when the bookmark for @uri was last modified. + filename="glib/gbookmarkfile.c" + line="2779">Gets the time when the bookmark for @uri was last modified. In the event the URI cannot be found, -1 is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. Use g_bookmark_file_get_modified_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. - + a timestamp - + filename="glib/gbookmarkfile.c" + line="2790">a timestamp + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2781">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2782">a valid URI @@ -2817,29 +2918,29 @@ In the event the URI cannot be found, -1 is returned and version="2.66" throws="1"> Gets the time when the bookmark for @uri was last modified. + filename="glib/gbookmarkfile.c" + line="2805">Gets the time when the bookmark for @uri was last modified. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + a #GDateTime + filename="glib/gbookmarkfile.c" + line="2816">a #GDateTime a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2807">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2808">a valid URI @@ -2848,20 +2949,20 @@ In the event the URI cannot be found, %NULL is returned and c:identifier="g_bookmark_file_get_size" version="2.12"> Gets the number of bookmarks inside @bookmark. - + filename="glib/gbookmarkfile.c" + line="3911">Gets the number of bookmarks inside @bookmark. + the number of bookmarks + filename="glib/gbookmarkfile.c" + line="3917">the number of bookmarks a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3913">a #GBookmarkFile @@ -2871,26 +2972,26 @@ In the event the URI cannot be found, %NULL is returned and version="2.12" throws="1"> Returns the title of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="2284">Returns the title of the bookmark for @uri. If @uri is %NULL, the title of @bookmark is returned. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + a newly allocated string or %NULL if the specified + filename="glib/gbookmarkfile.c" + line="2297">a newly allocated string or %NULL if the specified URI cannot be found. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2286">a #GBookmarkFile a valid URI or %NULL + filename="glib/gbookmarkfile.c" + line="2287">a valid URI or %NULL @@ -2908,15 +3009,15 @@ In the event the URI cannot be found, %NULL is returned and c:identifier="g_bookmark_file_get_uris" version="2.12"> Returns all URIs of the bookmarks in the bookmark file @bookmark. + filename="glib/gbookmarkfile.c" + line="2195">Returns all URIs of the bookmarks in the bookmark file @bookmark. The array of returned URIs will be %NULL-terminated, so @length may optionally be %NULL. - + a newly allocated %NULL-terminated array of strings. + filename="glib/gbookmarkfile.c" + line="2204">a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. @@ -2925,8 +3026,8 @@ optionally be %NULL. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2197">a #GBookmarkFile optional="1" allow-none="1"> return location for the number of returned URIs, or %NULL + filename="glib/gbookmarkfile.c" + line="2198">return location for the number of returned URIs, or %NULL @@ -2949,31 +3050,31 @@ optionally be %NULL. deprecated-version="2.66" throws="1"> Gets the time the bookmark for @uri was last visited. + filename="glib/gbookmarkfile.c" + line="2914">Gets the time the bookmark for @uri was last visited. In the event the URI cannot be found, -1 is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. Use g_bookmark_file_get_visited_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. - + a timestamp. - + filename="glib/gbookmarkfile.c" + line="2925">a timestamp. + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2916">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2917">a valid URI @@ -2983,29 +3084,29 @@ In the event the URI cannot be found, -1 is returned and version="2.66" throws="1"> Gets the time the bookmark for @uri was last visited. + filename="glib/gbookmarkfile.c" + line="2940">Gets the time the bookmark for @uri was last visited. In the event the URI cannot be found, %NULL is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + a #GDateTime + filename="glib/gbookmarkfile.c" + line="2951">a #GDateTime a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2942">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2943">a valid URI @@ -3015,36 +3116,36 @@ In the event the URI cannot be found, %NULL is returned and version="2.12" throws="1"> Checks whether the bookmark for @uri inside @bookmark has been + filename="glib/gbookmarkfile.c" + line="3391">Checks whether the bookmark for @uri inside @bookmark has been registered by application @name. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + %TRUE if the application @name was found + filename="glib/gbookmarkfile.c" + line="3404">%TRUE if the application @name was found a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3393">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3394">a valid URI the name of the application + filename="glib/gbookmarkfile.c" + line="3395">the name of the application @@ -3054,36 +3155,36 @@ In the event the URI cannot be found, %FALSE is returned and version="2.12" throws="1"> Checks whether @group appears in the list of groups to which + filename="glib/gbookmarkfile.c" + line="2979">Checks whether @group appears in the list of groups to which the bookmark for @uri belongs to. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + %TRUE if @group was found. + filename="glib/gbookmarkfile.c" + line="2992">%TRUE if @group was found. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2981">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2982">a valid URI the group name to be searched + filename="glib/gbookmarkfile.c" + line="2983">the group name to be searched @@ -3092,26 +3193,26 @@ In the event the URI cannot be found, %FALSE is returned and c:identifier="g_bookmark_file_has_item" version="2.12"> Looks whether the desktop bookmark has an item with its URI set to @uri. - + filename="glib/gbookmarkfile.c" + line="2174">Looks whether the desktop bookmark has an item with its URI set to @uri. + %TRUE if @uri is inside @bookmark, %FALSE otherwise + filename="glib/gbookmarkfile.c" + line="2181">%TRUE if @uri is inside @bookmark, %FALSE otherwise a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2176">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2177">a valid URI @@ -3121,28 +3222,28 @@ In the event the URI cannot be found, %FALSE is returned and version="2.12" throws="1"> Loads a bookmark file from memory into an empty #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="1766">Loads a bookmark file from memory into an empty #GBookmarkFile structure. If the object cannot be created then @error is set to a #GBookmarkFileError. - + %TRUE if a desktop bookmark could be loaded. + filename="glib/gbookmarkfile.c" + line="1778">%TRUE if a desktop bookmark could be loaded. an empty #GBookmarkFile struct + filename="glib/gbookmarkfile.c" + line="1768">an empty #GBookmarkFile struct desktop bookmarks + filename="glib/gbookmarkfile.c" + line="1769">desktop bookmarks loaded in memory @@ -3150,8 +3251,8 @@ structure. If the object cannot be created then @error is set to a the length of @data in bytes + filename="glib/gbookmarkfile.c" + line="1771">the length of @data in bytes @@ -3161,30 +3262,30 @@ structure. If the object cannot be created then @error is set to a version="2.12" throws="1"> This function looks for a desktop bookmark file named @file in the + filename="glib/gbookmarkfile.c" + line="1920">This function looks for a desktop bookmark file named @file in the paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), loads the file into @bookmark and returns the file's full path in @full_path. If the file could not be loaded then @error is set to either a #GFileError or #GBookmarkFileError. - + %TRUE if a key file could be loaded, %FALSE otherwise + filename="glib/gbookmarkfile.c" + line="1934">%TRUE if a key file could be loaded, %FALSE otherwise a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="1922">a #GBookmarkFile a relative path to a filename to open and parse + filename="glib/gbookmarkfile.c" + line="1923">a relative path to a filename to open and parse optional="1" allow-none="1"> return location for a string + filename="glib/gbookmarkfile.c" + line="1924">return location for a string containing the full path of the file, or %NULL @@ -3206,28 +3307,28 @@ set to either a #GFileError or #GBookmarkFileError. version="2.12" throws="1"> Loads a desktop bookmark file into an empty #GBookmarkFile structure. + filename="glib/gbookmarkfile.c" + line="1811">Loads a desktop bookmark file into an empty #GBookmarkFile structure. If the file could not be loaded then @error is set to either a #GFileError or #GBookmarkFileError. - + %TRUE if a desktop bookmark file could be loaded + filename="glib/gbookmarkfile.c" + line="1822">%TRUE if a desktop bookmark file could be loaded an empty #GBookmarkFile struct + filename="glib/gbookmarkfile.c" + line="1813">an empty #GBookmarkFile struct the path of a filename to load, in the + filename="glib/gbookmarkfile.c" + line="1814">the path of a filename to load, in the GLib file name encoding @@ -3238,31 +3339,31 @@ or #GBookmarkFileError. version="2.12" throws="1"> Changes the URI of a bookmark item from @old_uri to @new_uri. Any + filename="glib/gbookmarkfile.c" + line="3929">Changes the URI of a bookmark item from @old_uri to @new_uri. Any existing bookmark for @new_uri will be overwritten. If @new_uri is %NULL, then the bookmark is removed. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - + %TRUE if the URI was successfully changed + filename="glib/gbookmarkfile.c" + line="3943">%TRUE if the URI was successfully changed a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3931">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3932">a valid URI a valid URI, or %NULL + filename="glib/gbookmarkfile.c" + line="3933">a valid URI, or %NULL @@ -3281,8 +3382,8 @@ In the event the URI cannot be found, %FALSE is returned and version="2.12" throws="1"> Removes application registered with @name from the list of applications + filename="glib/gbookmarkfile.c" + line="3341">Removes application registered with @name from the list of applications that have registered a bookmark for @uri inside @bookmark. In the event the URI cannot be found, %FALSE is returned and @@ -3290,30 +3391,30 @@ In the event the URI cannot be found, %FALSE is returned and In the event that no application with name @app_name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. - + %TRUE if the application was successfully removed. + filename="glib/gbookmarkfile.c" + line="3357">%TRUE if the application was successfully removed. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3343">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3344">a valid URI the name of the application + filename="glib/gbookmarkfile.c" + line="3345">the name of the application @@ -3323,38 +3424,38 @@ a bookmark for @uri, %FALSE is returned and error is set to version="2.12" throws="1"> Removes @group from the list of groups to which the bookmark + filename="glib/gbookmarkfile.c" + line="3074">Removes @group from the list of groups to which the bookmark for @uri belongs to. In the event the URI cannot be found, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event no group was defined, %FALSE is returned and @error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - + %TRUE if @group was successfully removed. + filename="glib/gbookmarkfile.c" + line="3089">%TRUE if @group was successfully removed. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3076">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3077">a valid URI the group name to be removed + filename="glib/gbookmarkfile.c" + line="3078">the group name to be removed @@ -3364,26 +3465,26 @@ In the event no group was defined, %FALSE is returned and version="2.12" throws="1"> Removes the bookmark for @uri from the bookmark file @bookmark. - + filename="glib/gbookmarkfile.c" + line="2133">Removes the bookmark for @uri from the bookmark file @bookmark. + %TRUE if the bookmark was removed successfully. + filename="glib/gbookmarkfile.c" + line="2141">%TRUE if the bookmark was removed successfully. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2135">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2136">a valid URI @@ -3394,34 +3495,34 @@ In the event no group was defined, %FALSE is returned and deprecated="1" deprecated-version="2.66"> Sets the time the bookmark for @uri was added into @bookmark. + filename="glib/gbookmarkfile.c" + line="2586">Sets the time the bookmark for @uri was added into @bookmark. If no bookmark for @uri is found then it is created. Use g_bookmark_file_set_added_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2588">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2589">a valid URI a timestamp or -1 to use the current time - + filename="glib/gbookmarkfile.c" + line="2590">a timestamp or -1 to use the current time + @@ -3429,31 +3530,31 @@ If no bookmark for @uri is found then it is created. c:identifier="g_bookmark_file_set_added_date_time" version="2.66"> Sets the time the bookmark for @uri was added into @bookmark. + filename="glib/gbookmarkfile.c" + line="2610">Sets the time the bookmark for @uri was added into @bookmark. If no bookmark for @uri is found then it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2612">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2613">a valid URI a #GDateTime + filename="glib/gbookmarkfile.c" + line="2614">a #GDateTime @@ -3465,8 +3566,8 @@ If no bookmark for @uri is found then it is created. deprecated-version="2.66" throws="1"> Sets the meta-data of application @name inside the list of + filename="glib/gbookmarkfile.c" + line="3433">Sets the meta-data of application @name inside the list of applications that have registered a bookmark for @uri inside @bookmark. @@ -3496,50 +3597,50 @@ for @uri, %FALSE is returned and error is set to for @uri is found, one is created. Use g_bookmark_file_set_application_info() instead, as `time_t` is deprecated due to the year 2038 problem. - + %TRUE if the application's meta-data was successfully + filename="glib/gbookmarkfile.c" + line="3472">%TRUE if the application's meta-data was successfully changed. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3435">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3436">a valid URI an application's name + filename="glib/gbookmarkfile.c" + line="3437">an application's name an application's command line + filename="glib/gbookmarkfile.c" + line="3438">an application's command line the number of registrations done for this application + filename="glib/gbookmarkfile.c" + line="3439">the number of registrations done for this application the time of the last registration for this application - + filename="glib/gbookmarkfile.c" + line="3440">the time of the last registration for this application + @@ -3548,8 +3649,8 @@ for @uri is found, one is created. version="2.66" throws="1"> Sets the meta-data of application @name inside the list of + filename="glib/gbookmarkfile.c" + line="3496">Sets the meta-data of application @name inside the list of applications that have registered a bookmark for @uri inside @bookmark. @@ -3576,43 +3677,43 @@ in the event that no application @name has registered a bookmark for @uri, %FALSE is returned and error is set to %G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark for @uri is found, one is created. - + %TRUE if the application's meta-data was successfully + filename="glib/gbookmarkfile.c" + line="3535">%TRUE if the application's meta-data was successfully changed. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3498">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="3499">a valid URI an application's name + filename="glib/gbookmarkfile.c" + line="3500">an application's name an application's command line + filename="glib/gbookmarkfile.c" + line="3501">an application's command line the number of registrations done for this application + filename="glib/gbookmarkfile.c" + line="3502">the number of registrations done for this application nullable="1" allow-none="1"> the time of the last registration for this application, + filename="glib/gbookmarkfile.c" + line="3503">the time of the last registration for this application, which may be %NULL if @count is 0 @@ -3631,21 +3732,21 @@ for @uri is found, one is created. c:identifier="g_bookmark_file_set_description" version="2.12"> Sets @description as the description of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="2327">Sets @description as the description of the bookmark for @uri. If @uri is %NULL, the description of @bookmark is set. If a bookmark for @uri cannot be found then it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2329">a #GBookmarkFile nullable="1" allow-none="1"> a valid URI or %NULL + filename="glib/gbookmarkfile.c" + line="2330">a valid URI or %NULL a string + filename="glib/gbookmarkfile.c" + line="2331">a string @@ -3669,26 +3770,26 @@ If a bookmark for @uri cannot be found then it is created. c:identifier="g_bookmark_file_set_groups" version="2.12"> Sets a list of group names for the item with URI @uri. Each previously + filename="glib/gbookmarkfile.c" + line="3141">Sets a list of group names for the item with URI @uri. Each previously set group name list is removed. If @uri cannot be found then an item for it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="3143">a #GBookmarkFile an item's URI + filename="glib/gbookmarkfile.c" + line="3144">an item's URI nullable="1" allow-none="1"> an array of + filename="glib/gbookmarkfile.c" + line="3145">an array of group names, or %NULL to remove all groups @@ -3705,8 +3806,8 @@ If @uri cannot be found then an item for it is created. number of group name values in @groups + filename="glib/gbookmarkfile.c" + line="3147">number of group name values in @groups @@ -3715,27 +3816,27 @@ If @uri cannot be found then an item for it is created. c:identifier="g_bookmark_file_set_icon" version="2.12"> Sets the icon for the bookmark for @uri. If @href is %NULL, unsets + filename="glib/gbookmarkfile.c" + line="3998">Sets the icon for the bookmark for @uri. If @href is %NULL, unsets the currently set icon. @href can either be a full URL for the icon file or the icon name following the Icon Naming specification. If no bookmark for @uri is found one is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="4000">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="4001">a valid URI nullable="1" allow-none="1"> the URI of the icon for the bookmark, or %NULL + filename="glib/gbookmarkfile.c" + line="4002">the URI of the icon for the bookmark, or %NULL the MIME type of the icon for the bookmark + filename="glib/gbookmarkfile.c" + line="4003">the MIME type of the icon for the bookmark @@ -3759,31 +3860,31 @@ If no bookmark for @uri is found one is created. c:identifier="g_bookmark_file_set_is_private" version="2.12"> Sets the private flag of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="2501">Sets the private flag of the bookmark for @uri. If a bookmark for @uri cannot be found then it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2503">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2504">a valid URI %TRUE if the bookmark should be marked as private + filename="glib/gbookmarkfile.c" + line="2505">%TRUE if the bookmark should be marked as private @@ -3792,31 +3893,31 @@ If a bookmark for @uri cannot be found then it is created. c:identifier="g_bookmark_file_set_mime_type" version="2.12"> Sets @mime_type as the MIME type of the bookmark for @uri. + filename="glib/gbookmarkfile.c" + line="2412">Sets @mime_type as the MIME type of the bookmark for @uri. If a bookmark for @uri cannot be found then it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2414">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2415">a valid URI a MIME type + filename="glib/gbookmarkfile.c" + line="2416">a MIME type @@ -3827,8 +3928,8 @@ If a bookmark for @uri cannot be found then it is created. deprecated="1" deprecated-version="2.66"> Sets the last time the bookmark for @uri was last modified. + filename="glib/gbookmarkfile.c" + line="2711">Sets the last time the bookmark for @uri was last modified. If no bookmark for @uri is found then it is created. @@ -3838,28 +3939,28 @@ modifies a bookmark also changes the modification time, except for g_bookmark_file_set_visited_date_time(). Use g_bookmark_file_set_modified_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2713">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2714">a valid URI a timestamp or -1 to use the current time - + filename="glib/gbookmarkfile.c" + line="2715">a timestamp or -1 to use the current time + @@ -3867,8 +3968,8 @@ g_bookmark_file_set_visited_date_time(). c:identifier="g_bookmark_file_set_modified_date_time" version="2.66"> Sets the last time the bookmark for @uri was last modified. + filename="glib/gbookmarkfile.c" + line="2740">Sets the last time the bookmark for @uri was last modified. If no bookmark for @uri is found then it is created. @@ -3876,27 +3977,27 @@ The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of #GBookmarkFile that modifies a bookmark also changes the modification time, except for g_bookmark_file_set_visited_date_time(). - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2742">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2743">a valid URI a #GDateTime + filename="glib/gbookmarkfile.c" + line="2744">a #GDateTime @@ -3905,22 +4006,22 @@ g_bookmark_file_set_visited_date_time(). c:identifier="g_bookmark_file_set_title" version="2.12"> Sets @title as the title of the bookmark for @uri inside the + filename="glib/gbookmarkfile.c" + line="2239">Sets @title as the title of the bookmark for @uri inside the bookmark file @bookmark. If @uri is %NULL, the title of @bookmark is set. If a bookmark for @uri cannot be found then it is created. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2241">a #GBookmarkFile nullable="1" allow-none="1"> a valid URI or %NULL + filename="glib/gbookmarkfile.c" + line="2242">a valid URI or %NULL a UTF-8 encoded string + filename="glib/gbookmarkfile.c" + line="2243">a UTF-8 encoded string @@ -3946,8 +4047,8 @@ If a bookmark for @uri cannot be found then it is created. deprecated="1" deprecated-version="2.66"> Sets the time the bookmark for @uri was last visited. + filename="glib/gbookmarkfile.c" + line="2844">Sets the time the bookmark for @uri was last visited. If no bookmark for @uri is found then it is created. @@ -3958,28 +4059,28 @@ using g_bookmark_file_get_mime_type(). Changing the "visited" time does not affect the "modified" time. Use g_bookmark_file_set_visited_date_time() instead, as `time_t` is deprecated due to the year 2038 problem. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2846">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2847">a valid URI a timestamp or -1 to use the current time - + filename="glib/gbookmarkfile.c" + line="2848">a timestamp or -1 to use the current time + @@ -3987,8 +4088,8 @@ does not affect the "modified" time. c:identifier="g_bookmark_file_set_visited_date_time" version="2.66"> Sets the time the bookmark for @uri was last visited. + filename="glib/gbookmarkfile.c" + line="2874">Sets the time the bookmark for @uri was last visited. If no bookmark for @uri is found then it is created. @@ -3997,27 +4098,27 @@ either using the command line retrieved by g_bookmark_file_get_application_info( or by the default application for the bookmark's MIME type, retrieved using g_bookmark_file_get_mime_type(). Changing the "visited" time does not affect the "modified" time. - + a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2876">a #GBookmarkFile a valid URI + filename="glib/gbookmarkfile.c" + line="2877">a valid URI a #GDateTime + filename="glib/gbookmarkfile.c" + line="2878">a #GDateTime @@ -4027,13 +4128,13 @@ does not affect the "modified" time. version="2.12" throws="1"> This function outputs @bookmark as a string. - + filename="glib/gbookmarkfile.c" + line="2002">This function outputs @bookmark as a string. + + filename="glib/gbookmarkfile.c" + line="2010"> a newly allocated string holding the contents of the #GBookmarkFile @@ -4042,8 +4143,8 @@ does not affect the "modified" time. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2004">a #GBookmarkFile optional="1" allow-none="1"> return location for the length of the returned string, or %NULL + filename="glib/gbookmarkfile.c" + line="2005">return location for the length of the returned string, or %NULL @@ -4064,27 +4165,27 @@ does not affect the "modified" time. version="2.12" throws="1"> This function outputs @bookmark into a file. The write process is + filename="glib/gbookmarkfile.c" + line="2036">This function outputs @bookmark into a file. The write process is guaranteed to be atomic by using g_file_set_contents() internally. - + %TRUE if the file was successfully written. + filename="glib/gbookmarkfile.c" + line="2045">%TRUE if the file was successfully written. a #GBookmarkFile + filename="glib/gbookmarkfile.c" + line="2038">a #GBookmarkFile path of the output file + filename="glib/gbookmarkfile.c" + line="2039">path of the output file @@ -4099,28 +4200,28 @@ guaranteed to be atomic by using g_file_set_contents() internally. c:type="GBookmarkFileError" glib:error-domain="g-bookmark-file-error-quark"> Error codes returned by bookmark file parsing. - + URI was ill-formed a requested field was not found a requested application did not register a bookmark @@ -4128,19 +4229,19 @@ guaranteed to be atomic by using g_file_set_contents() internally. value="3" c:identifier="G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND"> a requested URI was not found document was ill formed the text being parsed was in an unknown encoding @@ -4148,14 +4249,14 @@ guaranteed to be atomic by using g_file_set_contents() internally. value="6" c:identifier="G_BOOKMARK_FILE_ERROR_WRITE"> an error occurred while writing requested file was not found @@ -4165,34 +4266,32 @@ guaranteed to be atomic by using g_file_set_contents() internally. glib:get-type="g_byte_array_get_type" c:symbol-prefix="byte_array"> Contains the public fields of a GByteArray. - + filename="glib/garray.c" + line="2676">Contains the public fields of a GByteArray. + a pointer to the element data. The data may be moved as + filename="glib/garray.c" + line="2678">a pointer to the element data. The data may be moved as elements are added to the #GByteArray the number of elements in the #GByteArray + filename="glib/garray.c" + line="2680">the number of elements in the #GByteArray - + Adds the given bytes to the end of the #GByteArray. + filename="glib/garray.c" + line="2858">Adds the given bytes to the end of the #GByteArray. The array will grow in size automatically if necessary. - - + + the #GByteArray + filename="glib/garray.c" + line="2867">the #GByteArray @@ -4200,54 +4299,54 @@ The array will grow in size automatically if necessary. a #GByteArray + filename="glib/garray.c" + line="2860">a #GByteArray the byte data to be added + filename="glib/garray.c" + line="2861">the byte data to be added the number of bytes to add + filename="glib/garray.c" + line="2862">the number of bytes to add Frees the memory allocated by the #GByteArray. If @free_segment is + filename="glib/garray.c" + line="2775">Frees the memory allocated by the #GByteArray. If @free_segment is %TRUE it frees the actual byte data. If the reference count of @array is greater than one, the #GByteArray wrapper is preserved but the size of @array will be set to zero. - + the element data if @free_segment is %FALSE, otherwise + filename="glib/garray.c" + line="2785">the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free(). a #GByteArray + filename="glib/garray.c" + line="2777">a #GByteArray if %TRUE the actual byte data is freed as well + filename="glib/garray.c" + line="2778">if %TRUE the actual byte data is freed as well @@ -4256,8 +4355,8 @@ the size of @array will be set to zero. c:identifier="g_byte_array_free_to_bytes" version="2.32"> Transfers the data from the #GByteArray into a new immutable #GBytes. + filename="glib/garray.c" + line="2795">Transfers the data from the #GByteArray into a new immutable #GBytes. The #GByteArray is freed unless the reference count of @array is greater than one, the #GByteArray wrapper is preserved but the size of @array @@ -4265,19 +4364,19 @@ will be set to zero. This is identical to using g_bytes_new_take() and g_byte_array_free() together. - + a new immutable #GBytes representing same + filename="glib/garray.c" + line="2810">a new immutable #GBytes representing same byte data that was in the array a #GByteArray + filename="glib/garray.c" + line="2797">a #GByteArray @@ -4286,13 +4385,13 @@ together. Creates a new #GByteArray with a reference count of 1. - + filename="glib/garray.c" + line="2685">Creates a new #GByteArray with a reference count of 1. + the new #GByteArray + filename="glib/garray.c" + line="2690">the new #GByteArray @@ -4302,8 +4401,8 @@ together. c:identifier="g_byte_array_new_take" version="2.32"> Creates a byte array containing the @data. + filename="glib/garray.c" + line="2720">Creates a byte array containing the @data. After this call, @data belongs to the #GByteArray and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with g_free(). @@ -4311,11 +4410,11 @@ allocated and will eventually be freed with g_free(). Do not use it if @len is greater than %G_MAXUINT. #GByteArray stores the length of its data in #guint, which may be shorter than #gsize. - + a new #GByteArray + filename="glib/garray.c" + line="2736">a new #GByteArray @@ -4323,32 +4422,30 @@ stores the length of its data in #guint, which may be shorter than byte data for the array + filename="glib/garray.c" + line="2722">byte data for the array length of @data + filename="glib/garray.c" + line="2723">length of @data - + Adds the given data to the start of the #GByteArray. + filename="glib/garray.c" + line="2879">Adds the given data to the start of the #GByteArray. The array will grow in size automatically if necessary. - - + + the #GByteArray + filename="glib/garray.c" + line="2888">the #GByteArray @@ -4356,39 +4453,36 @@ The array will grow in size automatically if necessary. a #GByteArray + filename="glib/garray.c" + line="2881">a #GByteArray the byte data to be added + filename="glib/garray.c" + line="2882">the byte data to be added the number of bytes to add + filename="glib/garray.c" + line="2883">the number of bytes to add - + Atomically increments the reference count of @array by one. + filename="glib/garray.c" + line="2824">Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. - - + + The passed in #GByteArray + filename="glib/garray.c" + line="2831">The passed in #GByteArray @@ -4396,26 +4490,24 @@ This function is thread-safe and may be called from any thread. A #GByteArray + filename="glib/garray.c" + line="2826">A #GByteArray - + Removes the byte at the given index from a #GByteArray. + filename="glib/garray.c" + line="2918">Removes the byte at the given index from a #GByteArray. The following bytes are moved down one place. - - + + the #GByteArray + filename="glib/garray.c" + line="2926">the #GByteArray @@ -4423,34 +4515,33 @@ The following bytes are moved down one place. a #GByteArray + filename="glib/garray.c" + line="2920">a #GByteArray the index of the byte to remove + filename="glib/garray.c" + line="2921">the index of the byte to remove + c:identifier="g_byte_array_remove_index_fast"> Removes the byte at the given index from a #GByteArray. The last + filename="glib/garray.c" + line="2937">Removes the byte at the given index from a #GByteArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the #GByteArray. But it is faster than g_byte_array_remove_index(). - - + + the #GByteArray + filename="glib/garray.c" + line="2947">the #GByteArray @@ -4458,33 +4549,32 @@ than g_byte_array_remove_index(). a #GByteArray + filename="glib/garray.c" + line="2939">a #GByteArray the index of the byte to remove + filename="glib/garray.c" + line="2940">the index of the byte to remove + version="2.4"> Removes the given number of bytes starting at the given index from a + filename="glib/garray.c" + line="2958">Removes the given number of bytes starting at the given index from a #GByteArray. The following elements are moved to close the gap. - - + + the #GByteArray + filename="glib/garray.c" + line="2967">the #GByteArray @@ -4492,37 +4582,35 @@ than g_byte_array_remove_index(). a @GByteArray + filename="glib/garray.c" + line="2960">a @GByteArray the index of the first byte to remove + filename="glib/garray.c" + line="2961">the index of the first byte to remove the number of bytes to remove + filename="glib/garray.c" + line="2962">the number of bytes to remove - + Sets the size of the #GByteArray, expanding it if necessary. - - + filename="glib/garray.c" + line="2900">Sets the size of the #GByteArray, expanding it if necessary. + + the #GByteArray + filename="glib/garray.c" + line="2907">the #GByteArray @@ -4530,34 +4618,32 @@ than g_byte_array_remove_index(). a #GByteArray + filename="glib/garray.c" + line="2902">a #GByteArray the new size of the #GByteArray + filename="glib/garray.c" + line="2903">the new size of the #GByteArray - + Creates a new #GByteArray with @reserved_size bytes preallocated. + filename="glib/garray.c" + line="2758">Creates a new #GByteArray with @reserved_size bytes preallocated. This avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0. - - + + the new #GByteArray + filename="glib/garray.c" + line="2767">the new #GByteArray @@ -4565,18 +4651,16 @@ bytes to the array. Note however that the size of the array is still number of bytes preallocated + filename="glib/garray.c" + line="2760">number of bytes preallocated - + Sorts a byte array, using @compare_func which should be a + filename="glib/garray.c" + line="2984">Sorts a byte array, using @compare_func which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). @@ -4586,51 +4670,55 @@ is undefined. If you want equal elements to keep their order (i.e. you want a stable sort) you can write a comparison function that, if two elements would otherwise compare equal, compares them by their addresses. - + a #GByteArray + filename="glib/garray.c" + line="2986">a #GByteArray - + comparison function + filename="glib/garray.c" + line="2987">comparison function + c:identifier="g_byte_array_sort_with_data"> Like g_byte_array_sort(), but the comparison function takes an extra + filename="glib/garray.c" + line="3007">Like g_byte_array_sort(), but the comparison function takes an extra user data argument. - + a #GByteArray + filename="glib/garray.c" + line="3009">a #GByteArray - + comparison function + filename="glib/garray.c" + line="3010">comparison function nullable="1" allow-none="1"> data to pass to @compare_func + filename="glib/garray.c" + line="3011">data to pass to @compare_func Frees the data in the array and resets the size to zero, while + filename="glib/garray.c" + line="2698">Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. - + the element data, which should be + filename="glib/garray.c" + line="2708">the element data, which should be freed using g_free(). a #GByteArray. + filename="glib/garray.c" + line="2700">a #GByteArray. @@ -4674,8 +4762,8 @@ to the caller. optional="1" allow-none="1"> pointer to retrieve the number of + filename="glib/garray.c" + line="2701">pointer to retrieve the number of elements of the original array @@ -4683,20 +4771,20 @@ to the caller. Atomically decrements the reference count of @array by one. If the + filename="glib/garray.c" + line="2841">Atomically decrements the reference count of @array by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread. - + A #GByteArray + filename="glib/garray.c" + line="2843">A #GByteArray @@ -4707,48 +4795,57 @@ thread. A simple refcounted data type representing an immutable sequence of zero or -more bytes from an unspecified origin. + filename="glib/gbytes.c" + line="44">A simple reference counted data type representing an immutable sequence of +zero or more bytes from an unspecified origin. -The purpose of a #GBytes is to keep the memory region that it holds +The purpose of a `GBytes` is to keep the memory region that it holds alive for as long as anyone holds a reference to the bytes. When the last reference count is dropped, the memory is released. Multiple -unrelated callers can use byte data in the #GBytes without coordinating +unrelated callers can use byte data in the `GBytes` without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference. -A #GBytes can come from many different origins that may have +A `GBytes` can come from many different origins that may have different procedures for freeing the memory region. Examples are -memory from g_malloc(), from memory slices, from a #GMappedFile or -memory from other allocators. +memory from [func@GLib.malloc], from memory slices, from a +[struct@GLib.MappedFile] or memory from other allocators. -#GBytes work well as keys in #GHashTable. Use g_bytes_equal() and -g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). -#GBytes can also be used as keys in a #GTree by passing the g_bytes_compare() -function to g_tree_new(). +`GBytes` work well as keys in [struct@GLib.HashTable]. Use +[method@GLib.Bytes.equal] and [method@GLib.Bytes.hash] as parameters to +[func@GLib.HashTable.new] or [func@GLib.HashTable.new_full]. +`GBytes` can also be used as keys in a [struct@GLib.Tree] by passing the +[method@GLib.Bytes.compare] function to [ctor@GLib.Tree.new]. The data pointed to by this bytes must not be modified. For a mutable -array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a -mutable array for a #GBytes sequence. To create an immutable #GBytes from -a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. - +array of bytes see [struct@GLib.ByteArray]. Use +[method@GLib.Bytes.unref_to_array] to create a mutable array for a `GBytes` +sequence. To create an immutable `GBytes` from a mutable +[struct@GLib.ByteArray], use the [func@GLib.ByteArray.free_to_bytes] +function. + Creates a new #GBytes from @data. + filename="glib/gbytes.c" + line="103">Creates a new [struct@GLib.Bytes] from @data. -@data is copied. If @size is 0, @data may be %NULL. - +@data is copied. If @size is 0, @data may be `NULL`. + +As an optimization, [ctor@GLib.Bytes.new] may avoid an extra allocation by +copying the data within the resulting bytes structure if sufficiently small +(since GLib 2.84). + a new #GBytes + filename="glib/gbytes.c" + line="117">a new [struct@GLib.Bytes] @@ -4757,17 +4854,17 @@ a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. nullable="1" allow-none="1"> - the data to be used for the bytes + filename="glib/gbytes.c" + line="105"> + the data to be used for the bytes the size of @data + filename="glib/gbytes.c" + line="107">the size of @data @@ -4777,16 +4874,16 @@ a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. version="2.32" introspectable="0"> Creates a new #GBytes from static data. + filename="glib/gbytes.c" + line="173">Creates a new [struct@GLib.Bytes] from static data. -@data must be static (ie: never modified or freed). It may be %NULL if @size +@data must be static (ie: never modified or freed). It may be `NULL` if @size is 0. - + a new #GBytes + filename="glib/gbytes.c" + line="184">a new [struct@GLib.Bytes] @@ -4795,17 +4892,17 @@ is 0. nullable="1" allow-none="1"> - the data to be used for the bytes + filename="glib/gbytes.c" + line="175"> + the data to be used for the bytes the size of @data + filename="glib/gbytes.c" + line="177">the size of @data @@ -4814,22 +4911,22 @@ is 0. c:identifier="g_bytes_new_take" version="2.32"> Creates a new #GBytes from @data. + filename="glib/gbytes.c" + line="145">Creates a new [struct@GLib.Bytes] from @data. -After this call, @data belongs to the #GBytes and may no longer be +After this call, @data belongs to the `GBytes` and may no longer be modified by the caller. The memory of @data has to be dynamically -allocated and will eventually be freed with g_free(). +allocated and will eventually be freed with [func@GLib.free]. -For creating #GBytes with memory from other allocators, see -g_bytes_new_with_free_func(). +For creating `GBytes` with memory from other allocators, see +[ctor@GLib.Bytes.new_with_free_func]. -@data may be %NULL if @size is 0. - +@data may be `NULL` if @size is 0. + a new #GBytes + filename="glib/gbytes.c" + line="162">a new [struct@GLib.Bytes] @@ -4838,17 +4935,17 @@ g_bytes_new_with_free_func(). nullable="1" allow-none="1"> - the data to be used for the bytes + filename="glib/gbytes.c" + line="147"> + the data to be used for the bytes the size of @data + filename="glib/gbytes.c" + line="149">the size of @data @@ -4858,8 +4955,8 @@ g_bytes_new_with_free_func(). version="2.32" introspectable="0"> Creates a #GBytes from @data. + filename="glib/gbytes.c" + line="194">Creates a [struct@GLib.Bytes] from @data. When the last reference is dropped, @free_func will be called with the @user_data argument. @@ -4867,12 +4964,12 @@ When the last reference is dropped, @free_func will be called with the @data must not be modified after this call is made until @free_func has been called to indicate that the bytes is no longer in use. -@data may be %NULL if @size is 0. - +@data may be `NULL` if @size is 0. + a new #GBytes + filename="glib/gbytes.c" + line="212">a new [struct@GLib.Bytes] @@ -4881,23 +4978,23 @@ been called to indicate that the bytes is no longer in use. nullable="1" allow-none="1"> - the data to be used for the bytes + filename="glib/gbytes.c" + line="196"> + the data to be used for the bytes the size of @data + filename="glib/gbytes.c" + line="198">the size of @data the function to call to release the data + filename="glib/gbytes.c" + line="199">the function to call to release the data data to pass to @free_func + filename="glib/gbytes.c" + line="200">data to pass to @free_func Compares the two #GBytes values. + filename="glib/gbytes.c" + line="439">Compares the two [struct@GLib.Bytes] values. -This function can be used to sort GBytes instances in lexicographical order. +This function can be used to sort `GBytes` instances in lexicographical +order. If @bytes1 and @bytes2 have different length but the shorter one is a prefix of the longer one then the shorter one is considered to be less than the longer one. Otherwise the first byte where both differ is used for comparison. If @bytes1 has a smaller value at that position it is considered less, otherwise greater than @bytes2. - + a negative value if @bytes1 is less than @bytes2, a positive value - if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to - @bytes2 + filename="glib/gbytes.c" + line="455">a negative value if @bytes1 is less than @bytes2, a positive value + if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to @bytes2 a pointer to a #GBytes + filename="glib/gbytes.c" + line="441">a pointer to a [struct@GLib.Bytes] a pointer to a #GBytes to compare with @bytes1 + filename="glib/gbytes.c" + line="442">a pointer to a [struct@GLib.Bytes] to compare with @bytes1 Compares the two #GBytes values being pointed to and returns -%TRUE if they are equal. + filename="glib/gbytes.c" + line="382">Compares the two [struct@GLib.Bytes] values being pointed to and returns +`TRUE` if they are equal. -This function can be passed to g_hash_table_new() as the @key_equal_func -parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. - +This function can be passed to [func@GLib.HashTable.new] as the +@key_equal_func parameter, when using non-`NULL` `GBytes` pointers as keys in +a [struct@GLib.HashTable]. + %TRUE if the two keys match. + filename="glib/gbytes.c" + line="394">`TRUE` if the two keys match. a pointer to a #GBytes + filename="glib/gbytes.c" + line="384">a pointer to a [struct@GLib.Bytes] a pointer to a #GBytes to compare with @bytes1 + filename="glib/gbytes.c" + line="385">a pointer to a [struct@GLib.Bytes] to compare with @bytes1 Get the byte data in the #GBytes. This data should not be modified. + filename="glib/gbytes.c" + line="290">Get the byte data in the [struct@GLib.Bytes]. -This function will always return the same pointer for a given #GBytes. +This data should not be modified. -%NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes -may represent an empty string with @data non-%NULL and @size as 0. %NULL will -not be returned if @size is non-zero. - +This function will always return the same pointer for a given `GBytes`. + +`NULL` may be returned if @size is 0. This is not guaranteed, as the `GBytes` +may represent an empty string with @data non-`NULL` and @size as 0. `NULL` +will not be returned if @size is non-zero. + - a pointer to the byte data, or %NULL + filename="glib/gbytes.c" + line="305"> + a pointer to the byte data @@ -5000,8 +5100,8 @@ not be returned if @size is non-zero. a #GBytes + filename="glib/gbytes.c" + line="292">a [struct@GLib.Bytes] optional="1" allow-none="1"> location to return size of byte data + filename="glib/gbytes.c" + line="293">location to return size of byte data @@ -5021,102 +5121,103 @@ not be returned if @size is non-zero. c:identifier="g_bytes_get_region" version="2.70"> Gets a pointer to a region in @bytes. + filename="glib/gbytes.c" + line="583">Gets a pointer to a region in @bytes. The region starts at @offset many bytes from the start of the data and contains @n_elements many elements of @element_size size. @n_elements may be zero, but @element_size must always be non-zero. -Ideally, @element_size is a static constant (eg: sizeof a struct). +Ideally, @element_size is a static constant (eg: `sizeof` a struct). This function does careful bounds checking (including checking for -arithmetic overflows) and returns a non-%NULL pointer if the +arithmetic overflows) and returns a non-`NULL` pointer if the specified region lies entirely within the @bytes. If the region is -in some way out of range, or if an overflow has occurred, then %NULL +in some way out of range, or if an overflow has occurred, then `NULL` is returned. Note: it is possible to have a valid zero-size region. In this case, the returned pointer will be equal to the base pointer of the data of -@bytes, plus @offset. This will be non-%NULL except for the case +@bytes, plus @offset. This will be non-`NULL` except for the case where @bytes itself was a zero-sized region. Since it is unlikely that you will be using this function to check for a zero-sized region -in a zero-sized @bytes, %NULL effectively always means "error". - +in a zero-sized @bytes, `NULL` effectively always means ‘error’. + the requested region, or %NULL in case of an error + filename="glib/gbytes.c" + line="611">the requested region, or `NULL` in case of an error a #GBytes + filename="glib/gbytes.c" + line="585">a [struct@GLib.Bytes] a non-zero element size + filename="glib/gbytes.c" + line="586">a non-zero element size an offset to the start of the region within the @bytes + filename="glib/gbytes.c" + line="587">an offset to the start of the region within the @bytes the number of elements in the region + filename="glib/gbytes.c" + line="588">the number of elements in the region Get the size of the byte data in the #GBytes. + filename="glib/gbytes.c" + line="319">Get the size of the byte data in the [struct@GLib.Bytes]. -This function will always return the same value for a given #GBytes. - +This function will always return the same value for a given `GBytes`. + the size + filename="glib/gbytes.c" + line="327">the size a #GBytes + filename="glib/gbytes.c" + line="321">a [struct@GLib.Bytes] Creates an integer hash code for the byte data in the #GBytes. + filename="glib/gbytes.c" + line="411">Creates an integer hash code for the byte data in the [struct@GLib.Bytes]. -This function can be passed to g_hash_table_new() as the @key_hash_func -parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. - +This function can be passed to [func@GLib.HashTable.new] as the +@key_hash_func parameter, when using non-`NULL` `GBytes` pointers as keys in +a [struct@GLib.HashTable]. + a hash value corresponding to the key. + filename="glib/gbytes.c" + line="421">a hash value corresponding to the key. a pointer to a #GBytes key + filename="glib/gbytes.c" + line="413">a pointer to a [struct@GLib.Bytes] key @@ -5125,72 +5226,75 @@ parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. c:identifier="g_bytes_new_from_bytes" version="2.32"> Creates a #GBytes which is a subsection of another #GBytes. The @offset + -@length may not be longer than the size of @bytes. + filename="glib/gbytes.c" + line="235">Creates a [struct@GLib.Bytes] which is a subsection of another `GBytes`. + +The @offset + @length may not be longer than the size of @bytes. -A reference to @bytes will be held by the newly created #GBytes until +A reference to @bytes will be held by the newly created `GBytes` until the byte data is no longer needed. Since 2.56, if @offset is 0 and @length matches the size of @bytes, then @bytes will be returned with the reference count incremented by 1. If @bytes -is a slice of another #GBytes, then the resulting #GBytes will reference -the same #GBytes instead of @bytes. This allows consumers to simplify the -usage of #GBytes when asynchronously writing to streams. - +is a slice of another `GBytes`, then the resulting `GBytes` will reference +the same `GBytes` instead of @bytes. This allows consumers to simplify the +usage of `GBytes` when asynchronously writing to streams. + a new #GBytes + filename="glib/gbytes.c" + line="254">a new [struct@GLib.Bytes] a #GBytes + filename="glib/gbytes.c" + line="237">a [struct@GLib.Bytes] offset which subsection starts at + filename="glib/gbytes.c" + line="238">offset which subsection starts at length of subsection + filename="glib/gbytes.c" + line="239">length of subsection Increase the reference count on @bytes. - + filename="glib/gbytes.c" + line="338">Increase the reference count on @bytes. + the #GBytes + filename="glib/gbytes.c" + line="344">the [struct@GLib.Bytes] a #GBytes + filename="glib/gbytes.c" + line="340">a [struct@GLib.Bytes] Releases a reference on @bytes. This may result in the bytes being -freed. If @bytes is %NULL, it will return immediately. - + filename="glib/gbytes.c" + line="357">Releases a reference on @bytes. + +This may result in the bytes being freed. If @bytes is `NULL`, it will +return immediately. + @@ -5200,8 +5304,8 @@ freed. If @bytes is %NULL, it will return immediately. nullable="1" allow-none="1"> a #GBytes + filename="glib/gbytes.c" + line="359">a [struct@GLib.Bytes] @@ -5210,23 +5314,26 @@ freed. If @bytes is %NULL, it will return immediately. c:identifier="g_bytes_unref_to_array" version="2.32"> Unreferences the bytes, and returns a new mutable #GByteArray containing -the same byte data. + filename="glib/gbytes.c" + line="549">Unreferences the bytes, and returns a new mutable [struct@GLib.ByteArray] +containing the same byte data. As an optimization, the byte data is transferred to the array without copying -if this was the last reference to bytes and bytes was created with -g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all -other cases the data is copied. +if this was the last reference to @bytes and @bytes was created with +[ctor@GLib.Bytes.new], [ctor@GLib.Bytes.new_take] or +[func@GLib.ByteArray.free_to_bytes] and the buffer was larger than the size +[struct@GLib.Bytes] may internalize within its allocation. In all other cases +the data is copied. Do not use it if @bytes contains more than %G_MAXUINT -bytes. #GByteArray stores the length of its data in #guint, which -may be shorter than #gsize, that @bytes is using. - +bytes. [struct@GLib.ByteArray] stores the length of its data in `guint`, +which may be shorter than `gsize`, that @bytes is using. + a new mutable #GByteArray containing the same byte data + filename="glib/gbytes.c" + line="567">a new mutable [struct@GLib.ByteArray] containing + the same byte data @@ -5234,8 +5341,8 @@ may be shorter than #gsize, that @bytes is using. a #GBytes + filename="glib/gbytes.c" + line="551">a [struct@GLib.Bytes] @@ -5244,20 +5351,22 @@ may be shorter than #gsize, that @bytes is using. c:identifier="g_bytes_unref_to_data" version="2.32"> Unreferences the bytes, and returns a pointer the same byte data + filename="glib/gbytes.c" + line="501">Unreferences the bytes, and returns a pointer the same byte data contents. As an optimization, the byte data is returned without copying if this was -the last reference to bytes and bytes was created with g_bytes_new(), -g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the -data is copied. - +the last reference to @bytes and @bytes was created with +[ctor@GLib.Bytes.new], [ctor@GLib.Bytes.new_take] or +[func@GLib.ByteArray.free_to_bytes] and the buffer was larger than the size +[struct@GLib.Bytes] may internalize within its allocation. In all other cases +the data is copied. + a pointer to the same byte data, which should be - freed with g_free() + filename="glib/gbytes.c" + line="516"> + a pointer to the same byte data, which should be freed with [func@GLib.free] @@ -5265,8 +5374,8 @@ data is copied. a #GBytes + filename="glib/gbytes.c" + line="503">a [struct@GLib.Bytes] caller-allocates="0" transfer-ownership="full"> location to place the length of the returned data + filename="glib/gbytes.c" + line="504">location to place the length of the returned data @@ -5285,27 +5394,27 @@ data is copied. c:identifier="GLIB_CHECK_VERSION" introspectable="0"> Checks whether the version of the GLib library that is being compiled + filename="glib/gversion.c" + line="88">Checks whether the version of the GLib library that is being compiled against is greater than or equal to the given one. See glib_check_version() for a runtime check. - + the major version to check for + filename="glib/gversion.c" + line="90">the major version to check for the minor version to check for + filename="glib/gversion.c" + line="91">the minor version to check for the micro version to check for + filename="glib/gversion.c" + line="92">the micro version to check for @@ -5313,31 +5422,31 @@ See glib_check_version() for a runtime check. value="ABCDEFGHIJKLMNOPQRSTUVWXYZ" c:type="G_CSET_A_2_Z"> The set of uppercase ASCII alphabet characters. + filename="glib/gscanner.c" + line="75">The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig. - + The set of ASCII digits. + filename="glib/gscanner.c" + line="83">The set of ASCII digits. Used for specifying valid identifier characters in #GScannerConfig. - + The set of lowercase ASCII alphabet characters. + filename="glib/gscanner.c" + line="67">The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig. - + version="2.76" introspectable="0"> Macro to check if the current compiler supports a specified @version + filename="glib/docs.c" + line="1435">Macro to check if the current compiler supports a specified @version of the C++ standard. Such value must be numeric and can be provided both in the short form for the well-known versions (e.g. `11`, `17`...) or in the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...). @@ -5361,12 +5470,12 @@ This value is compared against %G_CXX_STD_VERSION. ]| See also: %G_C_STD_CHECK_VERSION - + The C++ version to be checked for compatibility + filename="glib/docs.c" + line="1437">The C++ version to be checked for compatibility @@ -5375,8 +5484,8 @@ See also: %G_C_STD_CHECK_VERSION version="2.76" introspectable="0"> Macro to check if the current compiler supports a specified @version + filename="glib/docs.c" + line="1395">Macro to check if the current compiler supports a specified @version of the C standard. Such value must be numeric and can be provided both in the short form for the well-known versions (e.g. `90`, `99`...) or in the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...). @@ -5391,12 +5500,12 @@ This value is compared against %G_C_STD_VERSION. ]| See also: %G_CXX_STD_CHECK_VERSION - + The C version to be checked for compatibility + filename="glib/docs.c" + line="1397">The C version to be checked for compatibility @@ -5405,8 +5514,8 @@ See also: %G_CXX_STD_CHECK_VERSION c:type="G_C_STD_VERSION" version="2.76"> The C standard version the code is compiling against, it's normally + filename="glib/docs.c" + line="1379">The C standard version the code is compiling against, it's normally defined with the same value of `__STDC_VERSION__` for C standard compatible compilers, while it uses the lowest standard version in pure MSVC, given that in such compiler the definition depends on @@ -5415,9 +5524,366 @@ a compilation flag. This is granted to be undefined when compiling with a C++ compiler. See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION - + + + A `GCache` allows sharing of complex data structures, in order to +save system resources. + +`GCache` uses keys and values. A `GCache` key describes the properties +of a particular resource. A `GCache` value is the actual resource. + +`GCache` has been marked as deprecated, since this API is rarely +used and not very actively maintained. + Use a #GHashTable instead + + + Frees the memory allocated for the #GCache. + +Note that it does not destroy the keys and values which were +contained in the #GCache. + Use a #GHashTable instead + + + + + + + a #GCache + + + + + + Gets the value corresponding to the given key, creating it if +necessary. It first checks if the value already exists in the +#GCache, by using the @key_equal_func function passed to +g_cache_new(). If it does already exist it is returned, and its +reference count is increased by one. If the value does not currently +exist, if is created by calling the @value_new_func. The key is +duplicated by calling @key_dup_func and the duplicated key and value +are inserted into the #GCache. + Use a #GHashTable instead + + + a pointer to a #GCache value + + + + + a #GCache + + + + a key describing a #GCache object + + + + + + Calls the given function for each of the keys in the #GCache. + +NOTE @func is passed three parameters, the value and key of a cache +entry and the @user_data. The order of value and key is different +from the order in which g_hash_table_foreach() passes key-value +pairs to its callback function ! + Use a #GHashTable instead + + + + + + + a #GCache + + + + the function to call with each #GCache key + + + + user data to pass to the function + + + + + + Decreases the reference count of the given value. If it drops to 0 +then the value and its corresponding key are destroyed, using the +@value_destroy_func and @key_destroy_func passed to g_cache_new(). + Use a #GHashTable instead + + + + + + + a #GCache + + + + the value to remove + + + + + + Calls the given function for each of the values in the #GCache. + The reason is that it passes pointers to internal + data structures to @func; use g_cache_key_foreach() instead + + + + + + + a #GCache + + + + the function to call with each #GCache value + + + + user data to pass to the function + + + + + + Creates a new #GCache. + Use a #GHashTable instead + + + a new #GCache + + + + + a function to create a new object given a key. + This is called by g_cache_insert() if an object + with the given key does not already exist + + + + a function to destroy an object. It is called + by g_cache_remove() when the object is no + longer needed (i.e. its reference count drops + to 0) + + + + a function to copy a key. It is called by + g_cache_insert() if the key does not already exist in + the #GCache + + + + a function to destroy a key. It is called by + g_cache_remove() when the object is no longer + needed (i.e. its reference count drops to 0) + + + + a function to create a hash value from a key + + + + a function to create a hash value from a value + + + + a function to compare two keys. It should return + %TRUE if the two keys are equivalent + + + + + + + Specifies the type of the @value_destroy_func and @key_destroy_func +functions passed to g_cache_new(). The functions are passed a +pointer to the #GCache key or #GCache value and should free any +memory and other resources associated with it. + Use a #GHashTable instead + + + + + + + the #GCache value to destroy + + + + + + Specifies the type of the @key_dup_func function passed to +g_cache_new(). The function is passed a key +(__not__ a value as the prototype implies) and +should return a duplicate of the key. + Use a #GHashTable instead + + + a copy of the #GCache key + + + + + the #GCache key to destroy (__not__ a + #GCache value as it seems) + + + + + + Specifies the type of the @value_new_func function passed to +g_cache_new(). It is passed a #GCache key and should create the +value corresponding to the key. + Use a #GHashTable instead + + + a new #GCache value corresponding to the key. + + + + + a #GCache key + + + + glib:get-type="g_checksum_get_type" c:symbol-prefix="checksum"> An opaque structure representing a checksumming operation. + filename="glib/gchecksum.c" + line="35">GLib provides a generic API for computing checksums (or ‘digests’) +for a sequence of arbitrary bytes, using various hashing algorithms +like MD5, SHA-1 and SHA-256. Checksums are commonly used in various +environments and specifications. -To create a new GChecksum, use g_checksum_new(). To free -a GChecksum, use g_checksum_free(). - +To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free +a `GChecksum`, use [method@GLib.Checksum.free]. + +GLib supports incremental checksums using the `GChecksum` data +structure, by calling [method@GLib.Checksum.update] as long as there’s data +available and then using [method@GLib.Checksum.get_string] or +[method@GLib.Checksum.get_digest] to compute the checksum and return it +either as a string in hexadecimal form, or as a raw sequence of bytes. To +compute the checksum for binary blobs and nul-terminated strings in +one go, use the convenience functions [func@GLib.compute_checksum_for_data] +and [func@GLib.compute_checksum_for_string], respectively. + Creates a new #GChecksum, using the checksum algorithm @checksum_type. + filename="glib/gchecksum.c" + line="1449">Creates a new #GChecksum, using the checksum algorithm @checksum_type. If the @checksum_type is not known, %NULL is returned. A #GChecksum can be used to compute the checksum, or digest, of an arbitrary binary blob, using different hashing algorithms. @@ -5448,59 +5926,59 @@ vector of raw bytes. Once either g_checksum_get_string() or g_checksum_get_digest() have been called on a #GChecksum, the checksum will be closed and it won't be possible to call g_checksum_update() on it anymore. - + the newly created #GChecksum, or %NULL. + filename="glib/gchecksum.c" + line="1467">the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. the desired type of checksum + filename="glib/gchecksum.c" + line="1451">the desired type of checksum Copies a #GChecksum. If @checksum has been closed, by calling + filename="glib/gchecksum.c" + line="1527">Copies a #GChecksum. If @checksum has been closed, by calling g_checksum_get_string() or g_checksum_get_digest(), the copied checksum will be closed as well. - + the copy of the passed #GChecksum. Use + filename="glib/gchecksum.c" + line="1535">the copy of the passed #GChecksum. Use g_checksum_free() when finished using it. the #GChecksum to copy + filename="glib/gchecksum.c" + line="1529">the #GChecksum to copy Frees the memory allocated for @checksum. - + filename="glib/gchecksum.c" + line="1555">Frees the memory allocated for @checksum. + a #GChecksum + filename="glib/gchecksum.c" + line="1557">a #GChecksum @@ -5510,27 +5988,27 @@ checksum will be closed as well. version="2.16" introspectable="0"> Gets the digest from @checksum as a raw binary vector and places it + filename="glib/gchecksum.c" + line="1685">Gets the digest from @checksum as a raw binary vector and places it into @buffer. The size of the digest depends on the type of checksum. Once this function has been called, the #GChecksum is closed and can no longer be updated with g_checksum_update(). - + a #GChecksum + filename="glib/gchecksum.c" + line="1687">a #GChecksum output buffer + filename="glib/gchecksum.c" + line="1688">output buffer @@ -5540,8 +6018,8 @@ no longer be updated with g_checksum_update(). caller-allocates="0" transfer-ownership="full"> an inout parameter. The caller initializes it to the size of @buffer. + filename="glib/gchecksum.c" + line="1689">an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. @@ -5551,18 +6029,18 @@ no longer be updated with g_checksum_update(). c:identifier="g_checksum_get_string" version="2.16"> Gets the digest as a hexadecimal string. + filename="glib/gchecksum.c" + line="1626">Gets the digest as a hexadecimal string. Once this function has been called the #GChecksum can no longer be updated with g_checksum_update(). The hexadecimal characters will be lower case. - + the hexadecimal representation of the checksum. The + filename="glib/gchecksum.c" + line="1637">the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed. @@ -5570,58 +6048,58 @@ The hexadecimal characters will be lower case. a #GChecksum + filename="glib/gchecksum.c" + line="1628">a #GChecksum Resets the state of the @checksum back to its initial state. - + filename="glib/gchecksum.c" + line="1488">Resets the state of the @checksum back to its initial state. + the #GChecksum to reset + filename="glib/gchecksum.c" + line="1490">the #GChecksum to reset Feeds @data into an existing #GChecksum. The checksum must still be + filename="glib/gchecksum.c" + line="1574">Feeds @data into an existing #GChecksum. The checksum must still be open, that is g_checksum_get_string() or g_checksum_get_digest() must not have been called on @checksum. - + a #GChecksum + filename="glib/gchecksum.c" + line="1576">a #GChecksum buffer used to compute the checksum + filename="glib/gchecksum.c" + line="1577">buffer used to compute the checksum size of the buffer, or -1 if it is a null-terminated string. + filename="glib/gchecksum.c" + line="1578">size of the buffer, or -1 if it is a null-terminated string. @@ -5630,21 +6108,21 @@ not have been called on @checksum. c:identifier="g_checksum_type_get_length" version="2.16"> Gets the length in bytes of digests of type @checksum_type - + filename="glib/gchecksum.c" + line="1408">Gets the length in bytes of digests of type @checksum_type + the checksum length, or -1 if @checksum_type is + filename="glib/gchecksum.c" + line="1414">the checksum length, or -1 if @checksum_type is not supported. a #GChecksumType + filename="glib/gchecksum.c" + line="1410">a #GChecksumType @@ -5652,64 +6130,64 @@ not supported. The hashing algorithm to be used by #GChecksum when performing the digest of some data. Note that the #GChecksumType enumeration may be extended at a later date to include new hashing algorithm types. - + Use the MD5 hashing algorithm Use the SHA-1 hashing algorithm Use the SHA-256 hashing algorithm Use the SHA-512 hashing algorithm (Since: 2.36) Use the SHA-384 hashing algorithm (Since: 2.51) Prototype of a #GChildWatchSource callback, called when a child + filename="glib/gmain.h" + line="234">Prototype of a #GChildWatchSource callback, called when a child process has exited. -To interpret @wait_status, see the documentation -for g_spawn_check_wait_status(). In particular, +To interpret @wait_status, see the documentation for +[func@GLib.spawn_check_wait_status]. In particular, on Unix platforms, note that it is usually not equal to the integer passed to `exit()` or returned from `main()`. - + the process id of the child process + filename="glib/gmain.h" + line="236">the process id of the child process Status information about the child process, encoded + filename="glib/gmain.h" + line="237">Status information about the child process, encoded in a platform-specific manner @@ -5719,44 +6197,44 @@ to the integer passed to `exit()` or returned from `main()`. allow-none="1" closure="2"> user data passed to g_child_watch_add() + filename="glib/gmain.h" + line="239">user data passed to [func@GLib.child_watch_add] Specifies the type of function passed to g_clear_handle_id(). -The implementation is expected to free the resource identified -by @handle_id; for instance, if @handle_id is a #GSource ID, -g_source_remove() can be used. - + filename="glib/gmain.h" + line="843">Specifies the type of function passed to [func@GLib.clear_handle_id] The +implementation is expected to free the resource identified by @handle_id; +for instance, if @handle_id is a [struct@GLib.Source] ID, +[func@GLib.Source.remove] can be used. + the handle ID to clear + filename="glib/gmain.h" + line="845">the handle ID to clear Specifies the type of a comparison function used to compare two + filename="glib/glist.c" + line="1234">Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second. - + negative value if @a < @b; zero if @a = @b; positive + filename="glib/glist.c" + line="1245">negative value if @a < @b; zero if @a = @b; positive value if @a > @b @@ -5766,8 +6244,8 @@ integer if the first value comes after the second. nullable="1" allow-none="1"> a value + filename="glib/glist.c" + line="1236">a value nullable="1" allow-none="1"> a value to compare with + filename="glib/glist.c" + line="1237">a value to compare with allow-none="1" closure="2"> user data + filename="glib/glist.c" + line="1238">user data Specifies the type of a comparison function used to compare two + filename="glib/glist.c" + line="1203">Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second. - + negative value if @a < @b; zero if @a = @b; positive + filename="glib/glist.c" + line="1213">negative value if @a < @b; zero if @a = @b; positive value if @a > @b @@ -5812,8 +6290,8 @@ integer if the first value comes after the second. nullable="1" allow-none="1"> a value + filename="glib/glist.c" + line="1205">a value nullable="1" allow-none="1"> a value to compare with + filename="glib/glist.c" + line="1206">a value to compare with + + `GCompletion` provides support for automatic completion of a string +using any group of target strings. It is typically used for file +name completion as is common in many UNIX shells. + +A `GCompletion` is created using [func@GLib.Completion.new]. Target items are +added and removed with [method@GLib.Completion.add_items], +[method@GLib.Completion.remove_items] and +[method@GLib.Completion.clear_items]. A completion attempt is requested with +[method@GLib.Completion.complete] or [method@GLib.Completion.complete_utf8]. +When no longer needed, the `GCompletion` is freed with +[method@GLib.Completion.free]. + +Items in the completion can be simple strings (e.g. filenames), or +pointers to arbitrary data structures. If data structures are used +you must provide a [type@GLib.CompletionFunc] in [func@GLib.Completion.new], +which retrieves the item’s string from the data structure. You can change +the way in which strings are compared by setting a different +[type@GLib.CompletionStrncmpFunc] in [method@GLib.Completion.set_compare]. + +`GCompletion` has been marked as deprecated, since this API is rarely +used and not very actively maintained. + Rarely used API + + + list of target items (strings or data structures). + + + + + + function which is called to get the string associated with a + target item. It is %NULL if the target items are strings. + + + + the last prefix passed to g_completion_complete() or + g_completion_complete_utf8(). + + + + the list of items which begin with @prefix. + + + + + + The function to use when comparing strings. Use + g_completion_set_compare() to modify this function. + + + + Adds items to the #GCompletion. + Rarely used API + + + + + + + the #GCompletion. + + + + the list of items to add. + + + + + + + + Removes all items from the #GCompletion. The items are not freed, so if the +memory was dynamically allocated, it should be freed after calling this +function. + Rarely used API + + + + + + + the #GCompletion. + + + + + + Attempts to complete the string @prefix using the #GCompletion +target items. + Rarely used API + + + the list of items whose strings begin with + @prefix. This should not be changed. + + + + + + + the #GCompletion. + + + + the prefix string, typically typed by the user, which is + compared with each of the items. + + + + if non-%NULL, returns the longest prefix which is + common to all items that matched @prefix, or %NULL if + no items matched @prefix. This string should be freed + when no longer needed. + + + + + + Attempts to complete the string @prefix using the #GCompletion target items. +In contrast to g_completion_complete(), this function returns the largest common +prefix that is a valid UTF-8 string, omitting a possible common partial +character. + +You should use this function instead of g_completion_complete() if your +items are UTF-8 strings. + Rarely used API + + + the list of items whose strings begin with @prefix. This should +not be changed. + + + + + + + the #GCompletion + + + + the prefix string, typically used by the user, which is compared + with each of the items + + + + if non-%NULL, returns the longest prefix which is common to all + items that matched @prefix, or %NULL if no items matched @prefix. + This string should be freed when no longer needed. + + + + + + Frees all memory used by the #GCompletion. The items are not freed, so if +the memory was dynamically allocated, it should be freed after calling this +function. + Rarely used API + + + + + + + the #GCompletion. + + + + + + Removes items from a #GCompletion. The items are not freed, so if the memory +was dynamically allocated, free @items with g_list_free_full() after calling +this function. + Rarely used API + + + + + + + the #GCompletion. + + + + the items to remove. + + + + + + + + Sets the function to use for string comparisons. The default string +comparison function is strncmp(). + Rarely used API + + + + + + + a #GCompletion. + + + + the string comparison function. + + + + + + Creates a new #GCompletion. + Rarely used API + + + the new #GCompletion. + + + + + the function to be called to return the string representing + an item in the #GCompletion, or %NULL if strings are going to + be used as the #GCompletion items. + + + + + + + Specifies the type of the function passed to g_completion_new(). It +should return the string corresponding to the given target item. +This is used when you use data structures as #GCompletion items. + Rarely used API + + + the string corresponding to the item. + + + + + the completion item. + + + + + + Specifies the type of the function passed to +g_completion_set_compare(). This is used when you use strings as +#GCompletion items. + Rarely used API + + + an integer less than, equal to, or greater than zero if + the first @n bytes of @s1 is found, respectively, to be + less than, to match, or to be greater than the first @n + bytes of @s2. + + + + + string to compare with @s2. + + + + string to compare with @s1. + + + + maximal number of bytes to compare. + + + + The #GCond struct is an opaque data structure that represents a + filename="glib/gthread.c" + line="362">The #GCond struct is an opaque data structure that represents a condition. Threads can block on a #GCond if they find a certain condition to be false. If other threads change the state of this condition they signal the #GCond, and that causes the waiting @@ -5895,7 +6769,7 @@ without initialisation. Otherwise, you should call g_cond_init() on it and g_cond_clear() when done. A #GCond should only be accessed via the g_cond_ functions. - + @@ -5906,51 +6780,77 @@ A #GCond should only be accessed via the g_cond_ functions. If threads are waiting for @cond, all of them are unblocked. + filename="glib/gthread.c" + line="1701">If threads are waiting for @cond, all of them are unblocked. If no threads are waiting for @cond, this function has no effect. It is good practice to lock the same mutex as the waiting threads while calling this function, though not required. - + a #GCond + filename="glib/gthread.c" + line="1703">a #GCond Frees the resources allocated to a #GCond with g_cond_init(). + filename="glib/gthread.c" + line="1639">Frees the resources allocated to a #GCond with g_cond_init(). This function should not be used with a #GCond that has been statically allocated. Calling g_cond_clear() for a #GCond on which threads are blocking leads to undefined behaviour. - + an initialised #GCond + filename="glib/gthread.c" + line="1641">an initialised #GCond + + + + + + Destroys a #GCond that has been created with g_cond_new(). + +Calling g_cond_free() for a #GCond on which threads are +blocking leads to undefined behaviour. + GCond can now be statically allocated, or embedded +in structures and initialised with g_cond_init(). + + + + + + + a #GCond Initialises a #GCond so that it can be used. + filename="glib/gthread.c" + line="1615">Initialises a #GCond so that it can be used. This function is useful to initialise a #GCond that has been allocated as part of a larger structure. It is not necessary to @@ -5961,43 +6861,90 @@ needed, use g_cond_clear(). Calling g_cond_init() on an already-initialised #GCond leads to undefined behaviour. - + an uninitialized #GCond + filename="glib/gthread.c" + line="1617">an uninitialized #GCond If threads are waiting for @cond, at least one of them is unblocked. + filename="glib/gthread.c" + line="1686">If threads are waiting for @cond, at least one of them is unblocked. If no threads are waiting for @cond, this function has no effect. It is good practice to hold the same lock as the waiting thread while calling this function, though not required. - + a #GCond + filename="glib/gthread.c" + line="1688">a #GCond + + Waits until this thread is woken up on @cond, but not longer than +until the time specified by @abs_time. The @mutex is unlocked before +falling asleep and locked again before resuming. + +If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait(). + +This function can be used even if g_thread_init() has not yet been +called, and, in that case, will immediately return %TRUE. + +To easily calculate @abs_time a combination of g_get_real_time() +and g_time_val_add() can be used. + Use g_cond_wait_until() instead. + + + %TRUE if @cond was signalled, or %FALSE on timeout + + + + + a #GCond + + + + a #GMutex that is currently locked + + + + a #GTimeVal, determining the final time + + + + Atomically releases @mutex and waits until @cond is signalled. + filename="glib/gthread.c" + line="1659">Atomically releases @mutex and waits until @cond is signalled. When this function returns, @mutex is locked again and owned by the calling thread. @@ -6011,21 +6958,21 @@ condition is no longer met. For this reason, g_cond_wait() must always be used in a loop. See the documentation for #GCond for a complete example. - + a #GCond + filename="glib/gthread.c" + line="1661">a #GCond a #GMutex that is currently locked + filename="glib/gthread.c" + line="1662">a #GMutex that is currently locked @@ -6034,8 +6981,8 @@ the documentation for #GCond for a complete example. c:identifier="g_cond_wait_until" version="2.32"> Waits until either @cond is signalled or @end_time has passed. + filename="glib/gthread.c" + line="1716">Waits until either @cond is signalled or @end_time has passed. As with g_cond_wait() it is possible that a spurious or stolen wakeup could occur. For that reason, waiting on a condition variable should @@ -6083,47 +7030,65 @@ time on this API -- if a relative time of 5 seconds were passed directly to the call and a spurious wakeup occurred, the program would have to start over waiting again (which would lead to a total wait time of more than 5 seconds). - + %TRUE on a signal, %FALSE on a timeout + filename="glib/gthread.c" + line="1771">%TRUE on a signal, %FALSE on a timeout a #GCond + filename="glib/gthread.c" + line="1718">a #GCond a #GMutex that is currently locked + filename="glib/gthread.c" + line="1719">a #GMutex that is currently locked the monotonic time to wait until + filename="glib/gthread.c" + line="1720">the monotonic time to wait until + + Allocates and initializes a new #GCond. + GCond can now be statically allocated, or embedded +in structures and initialised with g_cond_init(). + + + a newly allocated #GCond. Free with g_cond_free() + + + Error codes returned by character set conversion routines. - + Conversion between the requested character sets is not supported. @@ -6131,47 +7096,47 @@ time of more than 5 seconds). value="1" c:identifier="G_CONVERT_ERROR_ILLEGAL_SEQUENCE"> Invalid byte sequence in conversion input; or the character sequence could not be represented in the target character set. Conversion failed for some reason. Partial character sequence at end of input. URI is invalid. Pathname is not an absolute path. No memory available. Since: 2.40 An embedded NUL character is present in conversion output where a NUL-terminated string is expected. Since: 2.56 @@ -6179,20 +7144,20 @@ time of more than 5 seconds). A function of this signature is used to copy the node data when doing a deep-copy of a tree. - + A pointer to the copy A pointer to the data which should be copied @@ -6201,7 +7166,7 @@ when doing a deep-copy of a tree. nullable="1" allow-none="1"> Additional data @@ -6211,32 +7176,32 @@ when doing a deep-copy of a tree. value="3" c:type="G_DATALIST_FLAGS_MASK"> A bitmask that restricts the possible flags passed to g_datalist_set_flags(). Passing a flags value where flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. - + Represents an invalid #GDateDay. - + filename="glib/gdate.c" + line="234">Represents an invalid #GDateDay. + Represents an invalid Julian day number. - + filename="glib/gdate.c" + line="240">Represents an invalid Julian day number. + Represents an invalid year. - + filename="glib/gdate.c" + line="246">Represents an invalid year. + version="2.50" introspectable="0"> A convenience form of g_log_structured(), recommended to be added to + filename="glib/gmessages.h" + line="268">A convenience form of g_log_structured(), recommended to be added to functions when debugging. It prints the current monotonic time and the code location using %G_STRLOC. - + Defines the appropriate cleanup function for a pointer type. + filename="glib/docs.c" + line="1752">Defines the appropriate cleanup function for a pointer type. The function will not be called if the variable to be cleaned up contains %NULL. @@ -6273,17 +7238,17 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) This macro should be used unconditionally; it is a no-op on compilers where cleanup is not supported. - + a type name to define a g_autoptr() cleanup function for + filename="glib/docs.c" + line="1754">a type name to define a g_autoptr() cleanup function for the cleanup function + filename="glib/docs.c" + line="1755">the cleanup function @@ -6292,8 +7257,8 @@ where cleanup is not supported. version="2.44" introspectable="0"> Defines the appropriate cleanup function for a type. + filename="glib/docs.c" + line="1778">Defines the appropriate cleanup function for a type. This will typically be the `_clear()` function for the given type. @@ -6306,17 +7271,17 @@ G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) This macro should be used unconditionally; it is a no-op on compilers where cleanup is not supported. - + a type name to define a g_auto() cleanup function for + filename="glib/docs.c" + line="1780">a type name to define a g_auto() cleanup function for the clear function + filename="glib/docs.c" + line="1781">the clear function @@ -6325,8 +7290,8 @@ where cleanup is not supported. version="2.44" introspectable="0"> Defines the appropriate cleanup function for a type. + filename="glib/docs.c" + line="1800">Defines the appropriate cleanup function for a type. With this definition, it will be possible to use g_auto() with @TypeName. @@ -6346,22 +7311,22 @@ G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) This macro should be used unconditionally; it is a no-op on compilers where cleanup is not supported. - + a type name to define a g_auto() cleanup function for + filename="glib/docs.c" + line="1802">a type name to define a g_auto() cleanup function for the free function + filename="glib/docs.c" + line="1803">the free function the "none" value for the type + filename="glib/docs.c" + line="1804">the "none" value for the type @@ -6370,7 +7335,7 @@ where cleanup is not supported. version="2.68" introspectable="0"> A convenience macro which defines two functions. First, returning the #GQuark for the extended error type @ErrorType; it is called `error_type_quark()`. Second, returning the private data from a @@ -6384,17 +7349,17 @@ declared or defined. The functions should be similar to respectively, but they should receive the private data type instead of #GError. -See [Extended #GError Domains][gerror-extended-domains] for an example. - +See [Extended #GError Domains](error-reporting.html#extended-gerror-domains) for an example. + name to return a #GQuark for prefix for the function name @@ -6404,31 +7369,31 @@ See [Extended #GError Domains][gerror-extended-domains] for an example. version="2.34" introspectable="0"> A convenience macro which defines a function returning the + filename="glib/gquark.c" + line="101">A convenience macro which defines a function returning the #GQuark for the name @QN. The function will be named @q_n_quark(). Note that the quark name will be stringified automatically in the macro, so you shouldn't use double quotes. - + the name to return a #GQuark for + filename="glib/gquark.c" + line="103">the name to return a #GQuark for prefix for the function name + filename="glib/gquark.c" + line="104">prefix for the function name - + @@ -6437,7 +7402,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6446,7 +7411,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6455,7 +7420,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6464,7 +7429,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6473,7 +7438,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6482,7 +7447,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6491,7 +7456,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6500,7 +7465,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6509,7 +7474,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6518,7 +7483,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6527,7 +7492,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6536,7 +7501,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6545,7 +7510,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6554,7 +7519,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6563,7 +7528,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6572,7 +7537,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6581,7 +7546,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6590,7 +7555,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6599,7 +7564,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6608,7 +7573,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6617,7 +7582,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6626,7 +7591,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6635,7 +7600,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6644,7 +7609,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6653,7 +7618,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6662,7 +7627,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6671,7 +7636,34 @@ in the macro, so you shouldn't use double quotes. - + + + + + + + + + + + + + + + + + + + + + + @@ -6680,7 +7672,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6689,7 +7681,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6698,7 +7690,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6707,7 +7699,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6716,7 +7708,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6725,7 +7717,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6734,7 +7726,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6743,7 +7735,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6752,7 +7744,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6761,7 +7753,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6770,7 +7762,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6779,7 +7771,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6788,7 +7780,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6797,7 +7789,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6806,7 +7798,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6815,7 +7807,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6824,7 +7816,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6833,7 +7825,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6842,7 +7834,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6851,7 +7843,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6860,7 +7852,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6869,7 +7861,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6878,7 +7870,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6887,7 +7879,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6896,7 +7888,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6905,7 +7897,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6914,7 +7906,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6923,7 +7915,34 @@ in the macro, so you shouldn't use double quotes. - + + + + + + + + + + + + + + + + + + + + + + @@ -6932,7 +7951,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6941,7 +7960,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6950,7 +7969,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6959,7 +7978,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6968,7 +7987,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6977,7 +7996,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6986,7 +8005,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -6995,7 +8014,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7004,7 +8023,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7013,7 +8032,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7022,7 +8041,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7031,7 +8050,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7040,7 +8059,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7049,7 +8068,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7058,7 +8077,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7067,7 +8086,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7076,7 +8095,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7085,7 +8104,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7094,7 +8113,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7103,7 +8122,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7112,7 +8131,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7121,7 +8140,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7130,7 +8149,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7139,7 +8158,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7148,7 +8167,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7157,7 +8176,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7166,7 +8185,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7175,7 +8194,34 @@ in the macro, so you shouldn't use double quotes. - + + + + + + + + + + + + + + + + + + + + + + @@ -7184,7 +8230,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7193,7 +8239,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7202,7 +8248,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7211,7 +8257,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7220,7 +8266,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7229,7 +8275,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7238,7 +8284,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7247,7 +8293,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7256,7 +8302,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7265,7 +8311,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7274,7 +8320,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7283,7 +8329,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7292,7 +8338,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7301,7 +8347,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7310,7 +8356,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7319,7 +8365,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7328,7 +8374,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7337,7 +8383,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7346,7 +8392,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7355,7 +8401,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7364,7 +8410,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7373,7 +8419,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7382,7 +8428,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7391,7 +8437,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7400,7 +8446,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7409,7 +8455,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7418,7 +8464,7 @@ in the macro, so you shouldn't use double quotes. - + @@ -7427,7 +8473,34 @@ in the macro, so you shouldn't use double quotes. - + + + + + + + + + + + + + + + + + + + + + + @@ -7435,43 +8508,45 @@ in the macro, so you shouldn't use double quotes. The directory separator character. -This is '/' on UNIX machines and '\' under Windows. - + filename="glib/docs.c" + line="882">The directory separator character. + +This is `'/'` on UNIX machines and `'\'` under Windows. + The directory separator as a string. -This is "/" on UNIX machines and "\" under Windows. - + filename="glib/docs.c" + line="890">The directory separator as a string. + +This is `"/"` on UNIX machines and `"\"` under Windows. + An opaque data structure that represents a keyed data list. + filename="glib/gdataset.c" + line="52">An opaque data structure that represents a keyed data list. -See also: [Keyed data lists][glib-Keyed-Data-Lists]. - +See also: [Keyed data lists](datalist-and-dataset.html). + Specifies the type of function passed to g_dataset_foreach(). It is + filename="glib/gdataset.c" + line="1452">Specifies the type of function passed to g_dataset_foreach(). It is called with each #GQuark id and associated data element, together with the @user_data parameter supplied to g_dataset_foreach(). - + the #GQuark id to identifying the data element. + filename="glib/gdataset.c" + line="1454">the #GQuark id to identifying the data element. nullable="1" allow-none="1"> the data element. + filename="glib/gdataset.c" + line="1455">the data element. allow-none="1" closure="2"> user data passed to g_dataset_foreach(). + filename="glib/gdataset.c" + line="1456">user data passed to g_dataset_foreach(). @@ -7501,403 +8576,431 @@ with the @user_data parameter supplied to g_dataset_foreach(). glib:get-type="g_date_get_type" c:symbol-prefix="date"> Represents a day between January 1, Year 1 and a few thousand years in -the future. None of its members should be accessed directly. + filename="glib/gdate.c" + line="62">`GDate` is a struct for calendrical calculations. -If the `GDate` is obtained from g_date_new(), it will be safe -to mutate but invalid and thus not safe for calendrical computations. +The `GDate` data structure represents a day between January 1, Year 1, +and sometime a few thousand years in the future (right now it will go +to the year 65535 or so, but [method@GLib.Date.set_parse] only parses up to the +year 8000 or so - just count on "a few thousand"). `GDate` is meant to +represent everyday dates, not astronomical dates or historical dates +or ISO timestamps or the like. It extrapolates the current Gregorian +calendar forward and backward in time; there is no attempt to change +the calendar to match time periods or locations. `GDate` does not store +time information; it represents a day. -If it's declared on the stack, it will contain garbage so must be -initialized with g_date_clear(). g_date_clear() makes the date invalid -but safe. An invalid date doesn't represent a day, it's "empty." A date -becomes valid after you set it to a Julian day or you set a day, month, -and year. - +The `GDate` implementation has several nice features; it is only a +64-bit struct, so storing large numbers of dates is very efficient. It +can keep both a Julian and day-month-year representation of the date, +since some calculations are much easier with one representation or the +other. A Julian representation is simply a count of days since some +fixed day in the past; for #GDate the fixed day is January 1, 1 AD. +("Julian" dates in the #GDate API aren't really Julian dates in the +technical sense; technically, Julian dates count from the start of the +Julian period, Jan 1, 4713 BC). + +`GDate` is simple to use. First you need a "blank" date; you can get a +dynamically allocated date from [ctor@GLib.Date.new], or you can declare an +automatic variable or array and initialize it by calling [method@GLib.Date.clear]. +A cleared date is safe; it's safe to call [method@GLib.Date.set_dmy] and the other +mutator functions to initialize the value of a cleared date. However, a cleared date +is initially invalid, meaning that it doesn't represent a day that exists. +It is undefined to call any of the date calculation routines on an invalid date. +If you obtain a date from a user or other unpredictable source, you should check +its validity with the [method@GLib.Date.valid] predicate. [method@GLib.Date.valid] +is also used to check for errors with [method@GLib.Date.set_parse] and other functions +that can fail. Dates can be invalidated by calling [method@GLib.Date.clear] again. + +It is very important to use the API to access the `GDate` struct. Often only the +day-month-year or only the Julian representation is valid. Sometimes neither is valid. +Use the API. + +GLib also features `GDateTime` which represents a precise time. + the Julian representation of the date + filename="glib/gdate.c" + line="64">the Julian representation of the date this bit is set if @julian_days is valid + filename="glib/gdate.c" + line="65">this bit is set if @julian_days is valid this is set if @day, @month and @year are valid + filename="glib/gdate.c" + line="66">this is set if @day, @month and @year are valid the day of the day-month-year representation of the date, + filename="glib/gdate.c" + line="67">the day of the day-month-year representation of the date, as a number between 1 and 31 the day of the day-month-year representation of the date, + filename="glib/gdate.c" + line="69">the month of the day-month-year representation of the date, as a number between 1 and 12 the day of the day-month-year representation of the date + filename="glib/gdate.c" + line="71">the year of the day-month-year representation of the date Allocates a #GDate and initializes + filename="glib/gdate.c" + line="252">Allocates a #GDate and initializes it to a safe state. The new date will be cleared (as if you'd called g_date_clear()) but invalid (it won't represent an existing day). Free the return value with g_date_free(). - + a newly-allocated #GDate + filename="glib/gdate.c" + line="260">a newly-allocated #GDate Create a new #GDate representing the given day-month-year triplet. + filename="glib/gdate.c" + line="270">Create a new #GDate representing the given day-month-year triplet. The triplet you pass in must represent a valid date. Use g_date_valid_dmy() if needed to validate it. The returned #GDate is guaranteed to be non-%NULL and valid. - + a newly-allocated #GDate + filename="glib/gdate.c" + line="282">a newly-allocated #GDate initialized with @day, @month, and @year day of the month + filename="glib/gdate.c" + line="272">day of the month month of the year + filename="glib/gdate.c" + line="273">month of the year year + filename="glib/gdate.c" + line="274">year Create a new #GDate representing the given Julian date. + filename="glib/gdate.c" + line="307">Create a new #GDate representing the given Julian date. The @julian_day you pass in must be valid. Use g_date_valid_julian() if needed to validate it. The returned #GDate is guaranteed to be non-%NULL and valid. - + a newly-allocated #GDate initialized + filename="glib/gdate.c" + line="317">a newly-allocated #GDate initialized with @julian_day days since January 1, Year 1 + filename="glib/gdate.c" + line="309">days since January 1, Year 1 Increments a date some number of days. + filename="glib/gdate.c" + line="1692">Increments a date some number of days. To move forward by weeks, add weeks*7 days. The date must be valid. - + a #GDate to increment + filename="glib/gdate.c" + line="1694">a #GDate to increment number of days to move the date forward + filename="glib/gdate.c" + line="1695">number of days to move the date forward Increments a date by some number of months. + filename="glib/gdate.c" + line="1742">Increments a date by some number of months. If the day of the month is greater than 28, this routine may change the day of the month (because the destination month may not have the current day in it). The date must be valid. - + a #GDate to increment + filename="glib/gdate.c" + line="1744">a #GDate to increment number of months to move forward + filename="glib/gdate.c" + line="1745">number of months to move forward Increments a date by some number of years. + filename="glib/gdate.c" + line="1837">Increments a date by some number of years. If the date is February 29, and the destination year is not a leap year, the date will be changed to February 28. The date must be valid. - + a #GDate to increment + filename="glib/gdate.c" + line="1839">a #GDate to increment number of years to move forward + filename="glib/gdate.c" + line="1840">number of years to move forward If @date is prior to @min_date, sets @date equal to @min_date. + filename="glib/gdate.c" + line="2127">If @date is prior to @min_date, sets @date equal to @min_date. If @date falls after @max_date, sets @date equal to @max_date. Otherwise, @date is unchanged. Either of @min_date and @max_date may be %NULL. All non-%NULL dates must be valid. - + a #GDate to clamp + filename="glib/gdate.c" + line="2129">a #GDate to clamp minimum accepted value for @date + filename="glib/gdate.c" + line="2130">minimum accepted value for @date maximum accepted value for @date + filename="glib/gdate.c" + line="2131">maximum accepted value for @date Initializes one or more #GDate structs to a safe but invalid + filename="glib/gdate.c" + line="860">Initializes one or more #GDate structs to a safe but invalid state. The cleared dates will not represent an existing date, but will not contain garbage. Useful to init a date declared on the stack. Validity can be tested with g_date_valid(). - + pointer to one or more dates to clear + filename="glib/gdate.c" + line="862">pointer to one or more dates to clear number of dates to clear + filename="glib/gdate.c" + line="863">number of dates to clear qsort()-style comparison function for dates. + filename="glib/gdate.c" + line="2022">qsort()-style comparison function for dates. Both dates must be valid. - + 0 for equal, less than zero if @lhs is less than @rhs, + filename="glib/gdate.c" + line="2030">0 for equal, less than zero if @lhs is less than @rhs, greater than zero if @lhs is greater than @rhs first date to compare + filename="glib/gdate.c" + line="2024">first date to compare second date to compare + filename="glib/gdate.c" + line="2025">second date to compare Copies a GDate to a newly-allocated GDate. If the input was invalid + filename="glib/gdate.c" + line="352">Copies a GDate to a newly-allocated GDate. If the input was invalid (as determined by g_date_valid()), the invalid state will be copied as is into the new object. - + a newly-allocated #GDate initialized from @date + filename="glib/gdate.c" + line="360">a newly-allocated #GDate initialized from @date a #GDate to copy + filename="glib/gdate.c" + line="354">a #GDate to copy Computes the number of days between two dates. + filename="glib/gdate.c" + line="839">Computes the number of days between two dates. If @date2 is prior to @date1, the returned value is negative. Both dates must be valid. - + the number of days between @date1 and @date2 + filename="glib/gdate.c" + line="848">the number of days between @date1 and @date2 the first date + filename="glib/gdate.c" + line="841">the first date the second date + filename="glib/gdate.c" + line="842">the second date Frees a #GDate returned from g_date_new(). - + filename="glib/gdate.c" + line="338">Frees a #GDate returned from g_date_new(). + a #GDate to free + filename="glib/gdate.c" + line="340">a #GDate to free Returns the day of the month. The date must be valid. - + filename="glib/gdate.c" + line="663">Returns the day of the month. The date must be valid. + day of the month + filename="glib/gdate.c" + line="669">day of the month a #GDate to extract the day of the month from + filename="glib/gdate.c" + line="665">a #GDate to extract the day of the month from Returns the day of the year, where Jan 1 is the first day of the + filename="glib/gdate.c" + line="708">Returns the day of the year, where Jan 1 is the first day of the year. The date must be valid. - + day of the year + filename="glib/gdate.c" + line="715">day of the year a #GDate to extract day of year from + filename="glib/gdate.c" + line="710">a #GDate to extract day of year from @@ -7906,44 +9009,44 @@ year. The date must be valid. c:identifier="g_date_get_iso8601_week_of_year" version="2.6"> Returns the week of the year, where weeks are interpreted according + filename="glib/gdate.c" + line="803">Returns the week of the year, where weeks are interpreted according to ISO 8601. - + ISO 8601 week number of the year. + filename="glib/gdate.c" + line="810">ISO 8601 week number of the year. a valid #GDate + filename="glib/gdate.c" + line="805">a valid #GDate Returns the Julian day or "serial number" of the #GDate. The + filename="glib/gdate.c" + line="684">Returns the Julian day or "serial number" of the #GDate. The Julian day is simply the number of days since January 1, Year 1; i.e., January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, etc. The date must be valid. - + Julian day + filename="glib/gdate.c" + line="693">Julian day a #GDate to extract the Julian day from + filename="glib/gdate.c" + line="686">a #GDate to extract the Julian day from @@ -7951,42 +9054,42 @@ etc. The date must be valid. Returns the week of the year, where weeks are understood to start on + filename="glib/gdate.c" + line="734">Returns the week of the year, where weeks are understood to start on Monday. If the date is before the first Monday of the year, return 0. The date must be valid. - + week of the year + filename="glib/gdate.c" + line="742">week of the year a #GDate + filename="glib/gdate.c" + line="736">a #GDate Returns the month of the year. The date must be valid. - + filename="glib/gdate.c" + line="621">Returns the month of the year. The date must be valid. + month of the year as a #GDateMonth + filename="glib/gdate.c" + line="627">month of the year as a #GDateMonth a #GDate to get the month from + filename="glib/gdate.c" + line="623">a #GDate to get the month from @@ -7994,270 +9097,270 @@ The date must be valid. Returns the week of the year during which this date falls, if + filename="glib/gdate.c" + line="768">Returns the week of the year during which this date falls, if weeks are understood to begin on Sunday. The date must be valid. Can return 0 if the day is before the first Sunday of the year. - + week number + filename="glib/gdate.c" + line="776">week number a #GDate + filename="glib/gdate.c" + line="770">a #GDate Returns the day of the week for a #GDate. The date must be valid. - + filename="glib/gdate.c" + line="600">Returns the day of the week for a #GDate. The date must be valid. + day of the week as a #GDateWeekday. + filename="glib/gdate.c" + line="606">day of the week as a #GDateWeekday. a #GDate + filename="glib/gdate.c" + line="602">a #GDate Returns the year of a #GDate. The date must be valid. - + filename="glib/gdate.c" + line="642">Returns the year of a #GDate. The date must be valid. + year in which the date falls + filename="glib/gdate.c" + line="648">year in which the date falls a #GDate + filename="glib/gdate.c" + line="644">a #GDate Returns %TRUE if the date is on the first of a month. + filename="glib/gdate.c" + line="1642">Returns %TRUE if the date is on the first of a month. The date must be valid. - + %TRUE if the date is the first of the month + filename="glib/gdate.c" + line="1649">%TRUE if the date is the first of the month a #GDate to check + filename="glib/gdate.c" + line="1644">a #GDate to check Returns %TRUE if the date is the last day of the month. + filename="glib/gdate.c" + line="1665">Returns %TRUE if the date is the last day of the month. The date must be valid. - + %TRUE if the date is the last day of the month + filename="glib/gdate.c" + line="1672">%TRUE if the date is the last day of the month a #GDate to check + filename="glib/gdate.c" + line="1667">a #GDate to check Checks if @date1 is less than or equal to @date2, + filename="glib/gdate.c" + line="2162">Checks if @date1 is less than or equal to @date2, and swap the values if this is not the case. - + the first date + filename="glib/gdate.c" + line="2164">the first date the second date + filename="glib/gdate.c" + line="2165">the second date Sets the day of the month for a #GDate. If the resulting + filename="glib/gdate.c" + line="1541">Sets the day of the month for a #GDate. If the resulting day-month-year triplet is invalid, the date will be invalid. - + a #GDate + filename="glib/gdate.c" + line="1543">a #GDate day to set + filename="glib/gdate.c" + line="1544">day to set Sets the value of a #GDate from a day, month, and year. + filename="glib/gdate.c" + line="1593">Sets the value of a #GDate from a day, month, and year. The day-month-year triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to check before you set it. - + a #GDate + filename="glib/gdate.c" + line="1595">a #GDate day + filename="glib/gdate.c" + line="1596">day month + filename="glib/gdate.c" + line="1597">month year + filename="glib/gdate.c" + line="1598">year Sets the value of a #GDate from a Julian day number. - + filename="glib/gdate.c" + line="1623">Sets the value of a #GDate from a Julian day number. + a #GDate + filename="glib/gdate.c" + line="1625">a #GDate Julian day number (days since January 1, Year 1) + filename="glib/gdate.c" + line="1626">Julian day number (days since January 1, Year 1) Sets the month of the year for a #GDate. If the resulting + filename="glib/gdate.c" + line="1515">Sets the month of the year for a #GDate. If the resulting day-month-year triplet is invalid, the date will be invalid. - + a #GDate + filename="glib/gdate.c" + line="1517">a #GDate month to set + filename="glib/gdate.c" + line="1518">month to set Parses a user-inputted string @str, and try to figure out what date it -represents, taking the [current locale][setlocale] into account. If the -string is successfully parsed, the date will be valid after the call. -Otherwise, it will be invalid. You should check using g_date_valid() -to see whether the parsing succeeded. + filename="glib/gdate.c" + line="1225">Parses a user-inputted string @str, and try to figure out what date it +represents, taking the [current locale](running.html#locale) +into account. If the string is successfully parsed, the date will be +valid after the call. Otherwise, it will be invalid. You should check +using g_date_valid() to see whether the parsing succeeded. This function is not appropriate for file formats and the like; it isn't very precise, and its exact behavior varies with the locale. It's intended to be a heuristic routine that guesses what the user means by a given string (and it does work pretty well in that capacity). - + a #GDate to fill in + filename="glib/gdate.c" + line="1227">a #GDate to fill in string to parse + filename="glib/gdate.c" + line="1228">string to parse @@ -8267,25 +9370,25 @@ capacity). deprecated="1" deprecated-version="2.10"> Sets the value of a date from a #GTime value. + filename="glib/gdate.c" + line="1472">Sets the value of a date from a #GTime value. The time to date conversion is done using the user's current timezone. Use g_date_set_time_t() instead. - + a #GDate. + filename="glib/gdate.c" + line="1474">a #GDate. #GTime value to set. + filename="glib/gdate.c" + line="1475">#GTime value to set. @@ -8294,8 +9397,8 @@ The time to date conversion is done using the user's current timezone. c:identifier="g_date_set_time_t" version="2.10"> Sets the value of a date to the date corresponding to a time + filename="glib/gdate.c" + line="1416">Sets the value of a date to the date corresponding to a time specified as a time_t. The time to date conversion is done using the user's current timezone. @@ -8306,22 +9409,22 @@ To set the value of a date to the current day, you could write: // handle the error g_date_set_time_t (date, now); ]| - + a #GDate + filename="glib/gdate.c" + line="1418">a #GDate time_t value to set - + filename="glib/gdate.c" + line="1419">time_t value to set + @@ -8331,177 +9434,177 @@ To set the value of a date to the current day, you could write: deprecated="1" deprecated-version="2.62"> Sets the value of a date from a #GTimeVal value. Note that the + filename="glib/gdate.c" + line="1491">Sets the value of a date from a #GTimeVal value. Note that the @tv_usec member is ignored, because #GDate can't make use of the additional precision. The time to date conversion is done using the user's current timezone. #GTimeVal is not year-2038-safe. Use g_date_set_time_t() instead. - + a #GDate + filename="glib/gdate.c" + line="1493">a #GDate #GTimeVal value to set + filename="glib/gdate.c" + line="1494">#GTimeVal value to set Sets the year for a #GDate. If the resulting day-month-year + filename="glib/gdate.c" + line="1567">Sets the year for a #GDate. If the resulting day-month-year triplet is invalid, the date will be invalid. - + a #GDate + filename="glib/gdate.c" + line="1569">a #GDate year to set + filename="glib/gdate.c" + line="1570">year to set Moves a date some number of days into the past. + filename="glib/gdate.c" + line="1717">Moves a date some number of days into the past. To move by weeks, just move by weeks*7 days. The date must be valid. - + a #GDate to decrement + filename="glib/gdate.c" + line="1719">a #GDate to decrement number of days to move + filename="glib/gdate.c" + line="1720">number of days to move Moves a date some number of months into the past. + filename="glib/gdate.c" + line="1788">Moves a date some number of months into the past. If the current day of the month doesn't exist in the destination month, the day of the month may change. The date must be valid. - + a #GDate to decrement + filename="glib/gdate.c" + line="1790">a #GDate to decrement number of months to move + filename="glib/gdate.c" + line="1791">number of months to move Moves a date some number of years into the past. + filename="glib/gdate.c" + line="1870">Moves a date some number of years into the past. If the current day doesn't exist in the destination year (i.e. it's February 29 and you move to a non-leap-year) then the day is changed to February 29. The date must be valid. - + a #GDate to decrement + filename="glib/gdate.c" + line="1872">a #GDate to decrement number of years to move + filename="glib/gdate.c" + line="1873">number of years to move Fills in the date-related bits of a struct tm using the @date value. + filename="glib/gdate.c" + line="2082">Fills in the date-related bits of a struct tm using the @date value. Initializes the non-date parts with something safe but meaningless. - + a #GDate to set the struct tm from + filename="glib/gdate.c" + line="2084">a #GDate to set the struct tm from struct tm to fill + filename="glib/gdate.c" + line="2085">struct tm to fill Returns %TRUE if the #GDate represents an existing day. The date must not + filename="glib/gdate.c" + line="381">Returns %TRUE if the #GDate represents an existing day. The date must not contain garbage; it should have been initialized with g_date_clear() if it wasn't allocated by one of the g_date_new() variants. - + Whether the date is valid + filename="glib/gdate.c" + line="389">Whether the date is valid a #GDate to check + filename="glib/gdate.c" + line="383">a #GDate to check @@ -8509,27 +9612,27 @@ if it wasn't allocated by one of the g_date_new() variants. Returns the number of days in a month, taking leap + filename="glib/gdate.c" + line="1926">Returns the number of days in a month, taking leap years into account. - + number of days in @month during the @year + filename="glib/gdate.c" + line="1934">number of days in @month during the @year month + filename="glib/gdate.c" + line="1928">month year + filename="glib/gdate.c" + line="1929">year @@ -8537,26 +9640,26 @@ years into account. Returns the number of weeks in the year, where weeks + filename="glib/gdate.c" + line="1950">Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.) - + number of Mondays in the year + filename="glib/gdate.c" + line="1962">number of Mondays in the year a year + filename="glib/gdate.c" + line="1952">a year @@ -8564,60 +9667,60 @@ one of the extra days happens to be a Monday.) Returns the number of weeks in the year, where weeks + filename="glib/gdate.c" + line="1986">Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.) - + the number of weeks in @year + filename="glib/gdate.c" + line="1998">the number of weeks in @year year to count weeks in + filename="glib/gdate.c" + line="1988">year to count weeks in Returns %TRUE if the year is a leap year. + filename="glib/gdate.c" + line="1904">Returns %TRUE if the year is a leap year. For the purposes of this function, leap year is every year divisible by 4 unless that year is divisible by 100. If it is divisible by 100 it would be a leap year only if that year is also divisible by 400. - + %TRUE if the year is a leap year + filename="glib/gdate.c" + line="1915">%TRUE if the year is a leap year year to check + filename="glib/gdate.c" + line="1906">year to check Generates a printed representation of the date, in a -[locale][setlocale]-specific way. + filename="glib/gdate.c" + line="2625">Generates a printed representation of the date, in a +[locale](running.html#locale)-specific way. Works just like the platform's C library strftime() function, but only accepts date-related formats; time-related formats give undefined results. Date must be valid. Unlike strftime() @@ -8629,175 +9732,175 @@ addition to those implemented by the platform's C library. For example, don't expect that using g_date_strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89. - + number of characters written to the buffer, or 0 the buffer was too small + filename="glib/gdate.c" + line="2646">number of characters written to the buffer, or `0` if the buffer was too small destination buffer + filename="glib/gdate.c" + line="2627">destination buffer buffer size + filename="glib/gdate.c" + line="2628">buffer size format string + filename="glib/gdate.c" + line="2629">format string valid #GDate + filename="glib/gdate.c" + line="2630">valid #GDate Returns %TRUE if the day of the month is valid (a day is valid if it's + filename="glib/gdate.c" + line="441">Returns %TRUE if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive). - + %TRUE if the day is valid + filename="glib/gdate.c" + line="448">%TRUE if the day is valid day to check + filename="glib/gdate.c" + line="443">day to check Returns %TRUE if the day-month-year triplet forms a valid, existing day + filename="glib/gdate.c" + line="487">Returns %TRUE if the day-month-year triplet forms a valid, existing day in the range of days #GDate understands (Year 1 or later, no more than a few thousand years in the future). - + %TRUE if the date is a valid one + filename="glib/gdate.c" + line="497">%TRUE if the date is a valid one day + filename="glib/gdate.c" + line="489">day month + filename="glib/gdate.c" + line="490">month year + filename="glib/gdate.c" + line="491">year Returns %TRUE if the Julian day is valid. Anything greater than zero + filename="glib/gdate.c" + line="472">Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit. - + %TRUE if the Julian day is valid + filename="glib/gdate.c" + line="479">%TRUE if the Julian day is valid Julian day to check + filename="glib/gdate.c" + line="474">Julian day to check Returns %TRUE if the month value is valid. The 12 #GDateMonth + filename="glib/gdate.c" + line="411">Returns %TRUE if the month value is valid. The 12 #GDateMonth enumeration values are the only valid months. - + %TRUE if the month is valid + filename="glib/gdate.c" + line="418">%TRUE if the month is valid month + filename="glib/gdate.c" + line="413">month Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration + filename="glib/gdate.c" + line="457">Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration values are the only valid weekdays. - + %TRUE if the weekday is valid + filename="glib/gdate.c" + line="464">%TRUE if the weekday is valid weekday + filename="glib/gdate.c" + line="459">weekday Returns %TRUE if the year is valid. Any year greater than 0 is valid, + filename="glib/gdate.c" + line="426">Returns %TRUE if the year is valid. Any year greater than 0 is valid, though there is a 16-bit limit to what #GDate will understand. - + %TRUE if the year is valid + filename="glib/gdate.c" + line="433">%TRUE if the year is valid year + filename="glib/gdate.c" + line="428">year @@ -8805,80 +9908,90 @@ though there is a 16-bit limit to what #GDate will understand. This enumeration isn't used in the API, but may be useful if you need + filename="glib/gdate.c" + line="169">This enumeration isn't used in the API, but may be useful if you need to mark a number as a day, month, or year. - + - a day + a day a month + filename="glib/gdate.c" + line="172">a month - a year + a year Enumeration representing a month; values are %G_DATE_JANUARY, + filename="glib/gdate.c" + line="187">Enumeration representing a month; values are %G_DATE_JANUARY, %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value. - + invalid value + filename="glib/gdate.c" + line="189">invalid value January + filename="glib/gdate.c" + line="190">January February + filename="glib/gdate.c" + line="191">February - March + March - April + April - May + May - June + June - July + July - August + August September + filename="glib/gdate.c" + line="198">September October + filename="glib/gdate.c" + line="199">October November + filename="glib/gdate.c" + line="200">November December + filename="glib/gdate.c" + line="201">December glib:get-type="g_date_time_get_type" c:symbol-prefix="date_time"> An opaque structure that represents a date and time, including a time zone. - + filename="glib/gdatetime.h" + line="91">`GDateTime` is a structure that combines a Gregorian date and time +into a single structure. + +`GDateTime` provides many conversion and methods to manipulate dates and times. +Time precision is provided down to microseconds and the time can range +(proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999. +`GDateTime` follows POSIX time in the sense that it is oblivious to leap +seconds. + +`GDateTime` is an immutable object; once it has been created it cannot +be modified further. All modifiers will create a new `GDateTime`. +Nearly all such functions can fail due to the date or time going out +of range, in which case %NULL will be returned. + +`GDateTime` is reference counted: the reference count is increased by calling +[method@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref]. +When the reference count drops to 0, the resources allocated by the `GDateTime` +structure are released. + +Many parts of the API may produce non-obvious results. As an +example, adding two months to January 31st will yield March 31st +whereas adding one month and then one month again will yield either +March 28th or March 29th. Also note that adding 24 hours is not +always the same as adding one day (since days containing daylight +savings time transitions are either 23 or 25 hours in length). + Creates a new #GDateTime corresponding to the given date and time in + filename="glib/gdatetime.c" + line="1585">Creates a new #GDateTime corresponding to the given date and time in the time zone @tz. The @year must be between 1 and 9999, @month between 1 and 12 and @day @@ -8923,54 +10060,54 @@ return %NULL. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1624">a new #GDateTime, or %NULL a #GTimeZone + filename="glib/gdatetime.c" + line="1587">a #GTimeZone the year component of the date + filename="glib/gdatetime.c" + line="1588">the year component of the date the month component of the date + filename="glib/gdatetime.c" + line="1589">the month component of the date the day component of the date + filename="glib/gdatetime.c" + line="1590">the day component of the date the hour component of the date + filename="glib/gdatetime.c" + line="1591">the hour component of the date the minute component of the date + filename="glib/gdatetime.c" + line="1592">the minute component of the date the number of seconds past the minute + filename="glib/gdatetime.c" + line="1593">the number of seconds past the minute @@ -8979,10 +10116,10 @@ when you are done with it. c:identifier="g_date_time_new_from_iso8601" version="2.56"> Creates a #GDateTime corresponding to the given + filename="glib/gdatetime.c" + line="1490">Creates a #GDateTime corresponding to the given [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) -@text. ISO 8601 strings of the form <date><sep><time><tz> are supported, with +@text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as mentioned below. @@ -8990,11 +10127,11 @@ Note that as #GDateTime "is oblivious to leap seconds", leap seconds information in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as `23:59:59`. -<sep> is the separator and can be either 'T', 't' or ' '. The latter two +`<sep>` is the separator and can be either 'T', 't' or ' '. The latter two separators are an extension from [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6). -<date> is in the form: +`<date>` is in the form: - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24. - `YYYYMMDD` - Same as above without dividers. @@ -9004,12 +10141,12 @@ separators are an extension from e.g. 2016-W34-3. - `YYYYWwwD` - Same as above without dividers. -<time> is in the form: +`<time>` is in the form: - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123. - `hhmmss(.sss)` - Same as above without dividers. -<tz> is an optional timezone suffix of the form: +`<tz>` is an optional timezone suffix of the form: - `Z` - UTC. - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00. @@ -9023,18 +10160,18 @@ formatted string. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1540">a new #GDateTime, or %NULL an ISO 8601 formatted time string. + filename="glib/gdatetime.c" + line="1492">an ISO 8601 formatted time string. nullable="1" allow-none="1"> a #GTimeZone to use if the text doesn't contain a + filename="glib/gdatetime.c" + line="1493">a #GTimeZone to use if the text doesn't contain a timezone, or %NULL. @@ -9055,8 +10192,8 @@ when you are done with it. deprecated="1" deprecated-version="2.62"> Creates a #GDateTime corresponding to the given #GTimeVal @tv in the + filename="glib/gdatetime.c" + line="1136">Creates a #GDateTime corresponding to the given #GTimeVal @tv in the local time zone. The time contained in a #GTimeVal is always stored in the form of @@ -9070,18 +10207,18 @@ You should release the return value by calling g_date_time_unref() when you are done with it. #GTimeVal is not year-2038-safe. Use g_date_time_new_from_unix_local() instead. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1153">a new #GDateTime, or %NULL a #GTimeVal + filename="glib/gdatetime.c" + line="1138">a #GTimeVal @@ -9092,8 +10229,8 @@ when you are done with it. deprecated="1" deprecated-version="2.62"> Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. + filename="glib/gdatetime.c" + line="1174">Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. The time contained in a #GTimeVal is always stored in the form of seconds elapsed since 1970-01-01 00:00:00 UTC. @@ -9105,18 +10242,18 @@ You should release the return value by calling g_date_time_unref() when you are done with it. #GTimeVal is not year-2038-safe. Use g_date_time_new_from_unix_utc() instead. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1189">a new #GDateTime, or %NULL a #GTimeVal + filename="glib/gdatetime.c" + line="1176">a #GTimeVal @@ -9125,8 +10262,8 @@ when you are done with it. c:identifier="g_date_time_new_from_unix_local" version="2.26"> Creates a #GDateTime corresponding to the given Unix time @t in the + filename="glib/gdatetime.c" + line="1012">Creates a #GDateTime corresponding to the given Unix time @t in the local time zone. Unix time is the number of seconds that have elapsed since 1970-01-01 @@ -9137,18 +10274,50 @@ of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1028">a new #GDateTime, or %NULL the Unix time + filename="glib/gdatetime.c" + line="1014">the Unix time + + + + + + Creates a [struct@GLib.DateTime] corresponding to the given Unix time @t in the +local time zone. + +Unix time is the number of microseconds that have elapsed since 1970-01-01 +00:00:00 UTC, regardless of the local time offset. + +This call can fail (returning `NULL`) if @t represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling [method@GLib.DateTime.unref] +when you are done with it. + + + a new [struct@GLib.DateTime], or `NULL` + + + + + the Unix time in microseconds @@ -9157,8 +10326,8 @@ when you are done with it. c:identifier="g_date_time_new_from_unix_utc" version="2.26"> Creates a #GDateTime corresponding to the given Unix time @t in UTC. + filename="glib/gdatetime.c" + line="1075">Creates a #GDateTime corresponding to the given Unix time @t in UTC. Unix time is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC. @@ -9168,18 +10337,49 @@ of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1090">a new #GDateTime, or %NULL the Unix time + filename="glib/gdatetime.c" + line="1077">the Unix time + + + + + + Creates a [struct@GLib.DateTime] corresponding to the given Unix time @t in UTC. + +Unix time is the number of microseconds that have elapsed since 1970-01-01 +00:00:00 UTC. + +This call can fail (returning `NULL`) if @t represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling [method@GLib.DateTime.unref] +when you are done with it. + + + a new [struct@GLib.DateTime], or `NULL` + + + + + the Unix time in microseconds @@ -9188,54 +10388,54 @@ when you are done with it. c:identifier="g_date_time_new_local" version="2.26"> Creates a new #GDateTime corresponding to the given date and time in + filename="glib/gdatetime.c" + line="1691">Creates a new #GDateTime corresponding to the given date and time in the local time zone. This call is equivalent to calling g_date_time_new() with the time zone returned by g_time_zone_new_local(). - + a #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1706">a #GDateTime, or %NULL the year component of the date + filename="glib/gdatetime.c" + line="1693">the year component of the date the month component of the date + filename="glib/gdatetime.c" + line="1694">the month component of the date the day component of the date + filename="glib/gdatetime.c" + line="1695">the day component of the date the hour component of the date + filename="glib/gdatetime.c" + line="1696">the hour component of the date the minute component of the date + filename="glib/gdatetime.c" + line="1697">the minute component of the date the number of seconds past the minute + filename="glib/gdatetime.c" + line="1698">the number of seconds past the minute @@ -9244,8 +10444,8 @@ zone returned by g_time_zone_new_local(). c:identifier="g_date_time_new_now" version="2.26"> Creates a #GDateTime corresponding to this exact instant in the given + filename="glib/gdatetime.c" + line="931">Creates a #GDateTime corresponding to this exact instant in the given time zone @tz. The time is as accurate as the system allows, to a maximum accuracy of 1 microsecond. @@ -9254,18 +10454,18 @@ year 9999. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="945">a new #GDateTime, or %NULL a #GTimeZone + filename="glib/gdatetime.c" + line="933">a #GTimeZone @@ -9274,17 +10474,17 @@ when you are done with it. c:identifier="g_date_time_new_now_local" version="2.26"> Creates a #GDateTime corresponding to this exact instant in the local + filename="glib/gdatetime.c" + line="961">Creates a #GDateTime corresponding to this exact instant in the local time zone. This is equivalent to calling g_date_time_new_now() with the time zone returned by g_time_zone_new_local(). - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="970">a new #GDateTime, or %NULL @@ -9292,16 +10492,16 @@ zone returned by g_time_zone_new_local(). c:identifier="g_date_time_new_now_utc" version="2.26"> Creates a #GDateTime corresponding to this exact instant in UTC. + filename="glib/gdatetime.c" + line="987">Creates a #GDateTime corresponding to this exact instant in UTC. This is equivalent to calling g_date_time_new_now() with the time zone returned by g_time_zone_new_utc(). - + a new #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="995">a new #GDateTime, or %NULL @@ -9309,81 +10509,81 @@ zone returned by g_time_zone_new_utc(). c:identifier="g_date_time_new_utc" version="2.26"> Creates a new #GDateTime corresponding to the given date and time in + filename="glib/gdatetime.c" + line="1728">Creates a new #GDateTime corresponding to the given date and time in UTC. This call is equivalent to calling g_date_time_new() with the time zone returned by g_time_zone_new_utc(). - + a #GDateTime, or %NULL + filename="glib/gdatetime.c" + line="1743">a #GDateTime, or %NULL the year component of the date + filename="glib/gdatetime.c" + line="1730">the year component of the date the month component of the date + filename="glib/gdatetime.c" + line="1731">the month component of the date the day component of the date + filename="glib/gdatetime.c" + line="1732">the day component of the date the hour component of the date + filename="glib/gdatetime.c" + line="1733">the hour component of the date the minute component of the date + filename="glib/gdatetime.c" + line="1734">the minute component of the date the number of seconds past the minute + filename="glib/gdatetime.c" + line="1735">the number of seconds past the minute Creates a copy of @datetime and adds the specified timespan to the copy. - + filename="glib/gdatetime.c" + line="1767">Creates a copy of @datetime and adds the specified timespan to the copy. + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1774">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1769">a #GDateTime a #GTimeSpan + filename="glib/gdatetime.c" + line="1770">a #GTimeSpan @@ -9392,28 +10592,28 @@ zone returned by g_time_zone_new_utc(). c:identifier="g_date_time_add_days" version="2.26"> Creates a copy of @datetime and adds the specified number of days to the + filename="glib/gdatetime.c" + line="1897">Creates a copy of @datetime and adds the specified number of days to the copy. Add negative values to subtract days. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1905">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1899">a #GDateTime the number of days + filename="glib/gdatetime.c" + line="1900">the number of days @@ -9422,58 +10622,58 @@ copy. Add negative values to subtract days. c:identifier="g_date_time_add_full" version="2.26"> Creates a new #GDateTime adding the specified values to the current date and + filename="glib/gdatetime.c" + line="1983">Creates a new #GDateTime adding the specified values to the current date and time in @datetime. Add negative values to subtract. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1996">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1985">a #GDateTime the number of years to add + filename="glib/gdatetime.c" + line="1986">the number of years to add the number of months to add + filename="glib/gdatetime.c" + line="1987">the number of months to add the number of days to add + filename="glib/gdatetime.c" + line="1988">the number of days to add the number of hours to add + filename="glib/gdatetime.c" + line="1989">the number of hours to add the number of minutes to add + filename="glib/gdatetime.c" + line="1990">the number of minutes to add the number of seconds to add + filename="glib/gdatetime.c" + line="1991">the number of seconds to add @@ -9482,28 +10682,28 @@ time in @datetime. Add negative values to subtract. c:identifier="g_date_time_add_hours" version="2.26"> Creates a copy of @datetime and adds the specified number of hours. + filename="glib/gdatetime.c" + line="1922">Creates a copy of @datetime and adds the specified number of hours. Add negative values to subtract hours. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1930">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1924">a #GDateTime the number of hours to add + filename="glib/gdatetime.c" + line="1925">the number of hours to add @@ -9512,28 +10712,28 @@ Add negative values to subtract hours. c:identifier="g_date_time_add_minutes" version="2.26"> Creates a copy of @datetime adding the specified number of minutes. + filename="glib/gdatetime.c" + line="1942">Creates a copy of @datetime adding the specified number of minutes. Add negative values to subtract minutes. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1950">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1944">a #GDateTime the number of minutes to add + filename="glib/gdatetime.c" + line="1945">the number of minutes to add @@ -9542,33 +10742,33 @@ Add negative values to subtract minutes. c:identifier="g_date_time_add_months" version="2.26"> Creates a copy of @datetime and adds the specified number of months to the + filename="glib/gdatetime.c" + line="1827">Creates a copy of @datetime and adds the specified number of months to the copy. Add negative values to subtract months. The day of the month of the resulting #GDateTime is clamped to the number of days in the updated calendar month. For example, if adding 1 month to 31st January 2018, the result would be 28th February 2018. In 2020 (a leap year), the result would be 29th February. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1840">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1829">a #GDateTime the number of months + filename="glib/gdatetime.c" + line="1830">the number of months @@ -9577,28 +10777,28 @@ year), the result would be 29th February. c:identifier="g_date_time_add_seconds" version="2.26"> Creates a copy of @datetime and adds the specified number of seconds. + filename="glib/gdatetime.c" + line="1963">Creates a copy of @datetime and adds the specified number of seconds. Add negative values to subtract seconds. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1971">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1965">a #GDateTime the number of seconds to add + filename="glib/gdatetime.c" + line="1966">the number of seconds to add @@ -9607,28 +10807,28 @@ Add negative values to subtract seconds. c:identifier="g_date_time_add_weeks" version="2.26"> Creates a copy of @datetime and adds the specified number of weeks to the + filename="glib/gdatetime.c" + line="1875">Creates a copy of @datetime and adds the specified number of weeks to the copy. Add negative values to subtract weeks. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1883">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1877">a #GDateTime the number of weeks + filename="glib/gdatetime.c" + line="1878">the number of weeks @@ -9637,59 +10837,59 @@ copy. Add negative values to subtract weeks. c:identifier="g_date_time_add_years" version="2.26"> Creates a copy of @datetime and adds the specified number of years to the + filename="glib/gdatetime.c" + line="1789">Creates a copy of @datetime and adds the specified number of years to the copy. Add negative values to subtract years. As with g_date_time_add_months(), if the resulting date would be 29th February on a non-leap year, the day will be clamped to 28th February. - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="1800">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="1791">a #GDateTime the number of years + filename="glib/gdatetime.c" + line="1792">the number of years A comparison function for #GDateTimes that is suitable + filename="glib/gdatetime.c" + line="2084">A comparison function for #GDateTimes that is suitable as a #GCompareFunc. Both #GDateTimes must be non-%NULL. - + -1, 0 or 1 if @dt1 is less than, equal to or greater + filename="glib/gdatetime.c" + line="2092">-1, 0 or 1 if @dt1 is less than, equal to or greater than @dt2. first #GDateTime to compare + filename="glib/gdatetime.c" + line="2086">first #GDateTime to compare second #GDateTime to compare + filename="glib/gdatetime.c" + line="2087">second #GDateTime to compare @@ -9698,66 +10898,66 @@ as a #GCompareFunc. Both #GDateTimes must be non-%NULL. c:identifier="g_date_time_difference" version="2.26"> Calculates the difference in time between @end and @begin. The + filename="glib/gdatetime.c" + line="2115">Calculates the difference in time between @end and @begin. The #GTimeSpan that is returned is effectively @end - @begin (ie: positive if the first parameter is larger). - + the difference between the two #GDateTime, as a time + filename="glib/gdatetime.c" + line="2124">the difference between the two #GDateTime, as a time span expressed in microseconds. a #GDateTime + filename="glib/gdatetime.c" + line="2117">a #GDateTime a #GDateTime + filename="glib/gdatetime.c" + line="2118">a #GDateTime Checks to see if @dt1 and @dt2 are equal. + filename="glib/gdatetime.c" + line="2158">Checks to see if @dt1 and @dt2 are equal. Equal here means that they represent the same moment after converting them to the same time zone. - + %TRUE if @dt1 and @dt2 are equal + filename="glib/gdatetime.c" + line="2168">%TRUE if @dt1 and @dt2 are equal a #GDateTime + filename="glib/gdatetime.c" + line="2160">a #GDateTime a #GDateTime + filename="glib/gdatetime.c" + line="2161">a #GDateTime Creates a newly allocated string representing the requested @format. + filename="glib/gdatetime.c" + line="3653">Creates a newly allocated string representing the requested @format. The format strings understood by this function are a subset of the `strftime()` format language as specified by C99. The `%D`, `%U` and `%W` @@ -9838,8 +11038,9 @@ The following format specifiers are supported: - `%%`: a literal `%` character Some conversion specifications can be modified by preceding the -conversion specifier by one or more modifier characters. The -following modifiers are supported for many of the numeric +conversion specifier by one or more modifier characters. + +The following modifiers are supported for many of the numeric conversions: - `O`: Use alternative numeric symbols, if the current locale supports those. @@ -9850,18 +11051,41 @@ conversions: - `0`: Pad a numeric result with zeros. This overrides the default padding for the specifier. +The following modifiers are supported for many of the alphabetic conversions: + +- `^`: Use upper case if possible. This is a gnulib `strftime()` extension. + Since: 2.80 +- `#`: Use opposite case if possible. This is a gnulib `strftime()` + extension. Since: 2.80 + Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative form of a month name. The alternative form should be used when the month name is used without a day number (e.g., standalone). It is required in some languages (Baltic, Slavic, Greek, and more) due to their grammatical rules. For other languages there is no difference. `%OB` is a GNU and BSD `strftime()` extension expected to be added to the future POSIX specification, -`%Ob` and `%Oh` are GNU `strftime()` extensions. Since: 2.56 - +`%Ob` and `%Oh` are GNU `strftime()` extensions. Since: 2.56 + +Since GLib 2.80, when `E` is used with `%c`, `%C`, `%x`, `%X`, `%y` or `%Y`, +the date is formatted using an alternate era representation specific to the +locale. This is typically used for the Thai solar calendar or Japanese era +names, for example. + +- `%Ec`: the preferred date and time representation for the current locale, + using the alternate era representation +- `%EC`: the name of the era +- `%Ex`: the preferred date representation for the current locale without + the time, using the alternate era representation +- `%EX`: the preferred time representation for the current locale without + the date, using the alternate era representation +- `%Ey`: the year since the beginning of the era denoted by the `%EC` + specifier +- `%EY`: the full alternative year representation + a newly allocated string formatted to + filename="glib/gdatetime.c" + line="3784">a newly allocated string formatted to the requested format or %NULL in the case that there was an error (such as a format specifier not being supported in the current locale). The string should be freed with g_free(). @@ -9870,14 +11094,14 @@ rules. For other languages there is no difference. `%OB` is a GNU and BSD A #GDateTime + filename="glib/gdatetime.c" + line="3655">A #GDateTime a valid UTF-8 string, containing the format for the + filename="glib/gdatetime.c" + line="3656">a valid UTF-8 string, containing the format for the #GDateTime @@ -9887,17 +11111,17 @@ rules. For other languages there is no difference. `%OB` is a GNU and BSD c:identifier="g_date_time_format_iso8601" version="2.62"> Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), + filename="glib/gdatetime.c" + line="3821">Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), including the date, time and time zone, and return that as a UTF-8 encoded string. Since GLib 2.66, this will output to sub-second precision if needed. - + a newly allocated string formatted in + filename="glib/gdatetime.c" + line="3831">a newly allocated string formatted in ISO 8601 format or %NULL in the case that there was an error. The string should be freed with g_free(). @@ -9905,8 +11129,8 @@ Since GLib 2.66, this will output to sub-second precision if needed. A #GDateTime + filename="glib/gdatetime.c" + line="3823">A #GDateTime @@ -9915,21 +11139,21 @@ Since GLib 2.66, this will output to sub-second precision if needed. c:identifier="g_date_time_get_day_of_month" version="2.26"> Retrieves the day of the month represented by @datetime in the gregorian + filename="glib/gdatetime.c" + line="2321">Retrieves the day of the month represented by @datetime in the gregorian calendar. - + the day of the month + filename="glib/gdatetime.c" + line="2328">the day of the month a #GDateTime + filename="glib/gdatetime.c" + line="2323">a #GDateTime @@ -9938,21 +11162,21 @@ calendar. c:identifier="g_date_time_get_day_of_week" version="2.26"> Retrieves the ISO 8601 day of the week on which @datetime falls (1 is + filename="glib/gdatetime.c" + line="2469">Retrieves the ISO 8601 day of the week on which @datetime falls (1 is Monday, 2 is Tuesday... 7 is Sunday). - + the day of the week + filename="glib/gdatetime.c" + line="2476">the day of the week a #GDateTime + filename="glib/gdatetime.c" + line="2471">a #GDateTime @@ -9961,21 +11185,21 @@ Monday, 2 is Tuesday... 7 is Sunday). c:identifier="g_date_time_get_day_of_year" version="2.26"> Retrieves the day of the year represented by @datetime in the Gregorian + filename="glib/gdatetime.c" + line="2489">Retrieves the day of the year represented by @datetime in the Gregorian calendar. - + the day of the year + filename="glib/gdatetime.c" + line="2496">the day of the year a #GDateTime + filename="glib/gdatetime.c" + line="2491">a #GDateTime @@ -9984,20 +11208,20 @@ calendar. c:identifier="g_date_time_get_hour" version="2.26"> Retrieves the hour of the day represented by @datetime - + filename="glib/gdatetime.c" + line="2513">Retrieves the hour of the day represented by @datetime + the hour of the day + filename="glib/gdatetime.c" + line="2519">the hour of the day a #GDateTime + filename="glib/gdatetime.c" + line="2515">a #GDateTime @@ -10006,20 +11230,20 @@ calendar. c:identifier="g_date_time_get_microsecond" version="2.26"> Retrieves the microsecond of the date represented by @datetime - + filename="glib/gdatetime.c" + line="2567">Retrieves the microsecond of the date represented by @datetime + the microsecond of the second + filename="glib/gdatetime.c" + line="2573">the microsecond of the second a #GDateTime + filename="glib/gdatetime.c" + line="2569">a #GDateTime @@ -10028,20 +11252,20 @@ calendar. c:identifier="g_date_time_get_minute" version="2.26"> Retrieves the minute of the hour represented by @datetime - + filename="glib/gdatetime.c" + line="2531">Retrieves the minute of the hour represented by @datetime + the minute of the hour + filename="glib/gdatetime.c" + line="2537">the minute of the hour a #GDateTime + filename="glib/gdatetime.c" + line="2533">a #GDateTime @@ -10050,21 +11274,21 @@ calendar. c:identifier="g_date_time_get_month" version="2.26"> Retrieves the month of the year represented by @datetime in the Gregorian + filename="glib/gdatetime.c" + line="2298">Retrieves the month of the year represented by @datetime in the Gregorian calendar. - + the month represented by @datetime + filename="glib/gdatetime.c" + line="2305">the month represented by @datetime a #GDateTime + filename="glib/gdatetime.c" + line="2300">a #GDateTime @@ -10073,20 +11297,20 @@ calendar. c:identifier="g_date_time_get_second" version="2.26"> Retrieves the second of the minute represented by @datetime - + filename="glib/gdatetime.c" + line="2549">Retrieves the second of the minute represented by @datetime + the second represented by @datetime + filename="glib/gdatetime.c" + line="2555">the second represented by @datetime a #GDateTime + filename="glib/gdatetime.c" + line="2551">a #GDateTime @@ -10095,21 +11319,21 @@ calendar. c:identifier="g_date_time_get_seconds" version="2.26"> Retrieves the number of seconds since the start of the last minute, + filename="glib/gdatetime.c" + line="2585">Retrieves the number of seconds since the start of the last minute, including the fractional part. - + the number of seconds + filename="glib/gdatetime.c" + line="2592">the number of seconds a #GDateTime + filename="glib/gdatetime.c" + line="2587">a #GDateTime @@ -10118,20 +11342,20 @@ including the fractional part. c:identifier="g_date_time_get_timezone" version="2.58"> Get the time zone for this @datetime. - + filename="glib/gdatetime.c" + line="2718">Get the time zone for this @datetime. + the time zone + filename="glib/gdatetime.c" + line="2724">the time zone a #GDateTime + filename="glib/gdatetime.c" + line="2720">a #GDateTime @@ -10140,18 +11364,18 @@ including the fractional part. c:identifier="g_date_time_get_timezone_abbreviation" version="2.26"> Determines the time zone abbreviation to be used at the time and in + filename="glib/gdatetime.c" + line="2736">Determines the time zone abbreviation to be used at the time and in the time zone of @datetime. For example, in Toronto this is currently "EST" during the winter months and "EDT" during the summer months when daylight savings time is in effect. - + the time zone abbreviation. The returned + filename="glib/gdatetime.c" + line="2747">the time zone abbreviation. The returned string is owned by the #GDateTime and it should not be modified or freed @@ -10159,8 +11383,8 @@ time is in effect. a #GDateTime + filename="glib/gdatetime.c" + line="2738">a #GDateTime @@ -10169,8 +11393,8 @@ time is in effect. c:identifier="g_date_time_get_utc_offset" version="2.26"> Determines the offset to UTC in effect at the time and in the time + filename="glib/gdatetime.c" + line="2688">Determines the offset to UTC in effect at the time and in the time zone of @datetime. The offset is the number of microseconds that you add to UTC time to @@ -10178,19 +11402,19 @@ arrive at local time for the time zone (ie: negative numbers for time zones west of GMT, positive numbers for east). If @datetime represents UTC time, then the offset is always zero. - + the number of microseconds that should be added to UTC to + filename="glib/gdatetime.c" + line="2701">the number of microseconds that should be added to UTC to get the local time a #GDateTime + filename="glib/gdatetime.c" + line="2690">a #GDateTime @@ -10199,8 +11423,8 @@ If @datetime represents UTC time, then the offset is always zero. c:identifier="g_date_time_get_week_numbering_year" version="2.26"> Returns the ISO 8601 week-numbering year in which the week containing + filename="glib/gdatetime.c" + line="2357">Returns the ISO 8601 week-numbering year in which the week containing @datetime falls. This function, taken together with g_date_time_get_week_of_year() and @@ -10231,18 +11455,18 @@ week (Monday to Sunday). Note that January 1 0001 in the proleptic Gregorian calendar is a Monday, so this function never returns 0. - + the ISO 8601 week-numbering year for @datetime + filename="glib/gdatetime.c" + line="2393">the ISO 8601 week-numbering year for @datetime a #GDateTime + filename="glib/gdatetime.c" + line="2359">a #GDateTime @@ -10251,8 +11475,8 @@ Monday, so this function never returns 0. c:identifier="g_date_time_get_week_of_year" version="2.26"> Returns the ISO 8601 week number for the week containing @datetime. + filename="glib/gdatetime.c" + line="2433">Returns the ISO 8601 week number for the week containing @datetime. The ISO 8601 week number is the same for every day of the week (from Moday through Sunday). That can produce some unusual results (described below). @@ -10267,18 +11491,18 @@ year are considered as being contained in the last week of the previous year. Similarly, the final days of a calendar year may be considered as being part of the first ISO 8601 week of the next year if 4 or more days of that week are contained within the new year. - + the ISO 8601 week number for @datetime. + filename="glib/gdatetime.c" + line="2453">the ISO 8601 week number for @datetime. a #GDateTime + filename="glib/gdatetime.c" + line="2435">a #GDateTime @@ -10287,37 +11511,37 @@ if 4 or more days of that week are contained within the new year. c:identifier="g_date_time_get_year" version="2.26"> Retrieves the year represented by @datetime in the Gregorian calendar. - + filename="glib/gdatetime.c" + line="2276">Retrieves the year represented by @datetime in the Gregorian calendar. + the year represented by @datetime + filename="glib/gdatetime.c" + line="2282">the year represented by @datetime A #GDateTime + filename="glib/gdatetime.c" + line="2278">A #GDateTime Retrieves the Gregorian day, month, and year of a given #GDateTime. - + filename="glib/gdatetime.c" + line="2180">Retrieves the Gregorian day, month, and year of a given #GDateTime. + a #GDateTime. + filename="glib/gdatetime.c" + line="2182">a #GDateTime. optional="1" allow-none="1"> the return location for the gregorian year, or %NULL. + filename="glib/gdatetime.c" + line="2183">the return location for the gregorian year, or %NULL. optional="1" allow-none="1"> the return location for the month of the year, or %NULL. + filename="glib/gdatetime.c" + line="2184">the return location for the month of the year, or %NULL. optional="1" allow-none="1"> the return location for the day of the month, or %NULL. + filename="glib/gdatetime.c" + line="2185">the return location for the day of the month, or %NULL. Hashes @datetime into a #guint, suitable for use within #GHashTable. - + filename="glib/gdatetime.c" + line="2140">Hashes @datetime into a #guint, suitable for use within #GHashTable. + a #guint containing the hash + filename="glib/gdatetime.c" + line="2146">a #guint containing the hash a #GDateTime + filename="glib/gdatetime.c" + line="2142">a #GDateTime @@ -10379,41 +11603,41 @@ if 4 or more days of that week are contained within the new year. c:identifier="g_date_time_is_daylight_savings" version="2.26"> Determines if daylight savings time is in effect at the time and in + filename="glib/gdatetime.c" + line="2761">Determines if daylight savings time is in effect at the time and in the time zone of @datetime. - + %TRUE if daylight savings time is in effect + filename="glib/gdatetime.c" + line="2768">%TRUE if daylight savings time is in effect a #GDateTime + filename="glib/gdatetime.c" + line="2763">a #GDateTime Atomically increments the reference count of @datetime by one. - + filename="glib/gdatetime.c" + line="677">Atomically increments the reference count of @datetime by one. + the #GDateTime with the reference count increased + filename="glib/gdatetime.c" + line="683">the #GDateTime with the reference count increased a #GDateTime + filename="glib/gdatetime.c" + line="679">a #GDateTime @@ -10422,25 +11646,25 @@ the time zone of @datetime. c:identifier="g_date_time_to_local" version="2.26"> Creates a new #GDateTime corresponding to the same instant in time as + filename="glib/gdatetime.c" + line="2808">Creates a new #GDateTime corresponding to the same instant in time as @datetime, but in the local time zone. This call is equivalent to calling g_date_time_to_timezone() with the time zone returned by g_time_zone_new_local(). - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="2818">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="2810">a #GDateTime @@ -10451,8 +11675,8 @@ time zone returned by g_time_zone_new_local(). deprecated="1" deprecated-version="2.62"> Stores the instant in time that @datetime represents into @tv. + filename="glib/gdatetime.c" + line="2648">Stores the instant in time that @datetime represents into @tv. The time contained in a #GTimeVal is always stored in the form of seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time @@ -10467,24 +11691,24 @@ out of range. On systems where 'long' is 64bit, this function never fails. #GTimeVal is not year-2038-safe. Use g_date_time_to_unix() instead. - + %TRUE if successful, else %FALSE + filename="glib/gdatetime.c" + line="2667">%TRUE if successful, else %FALSE a #GDateTime + filename="glib/gdatetime.c" + line="2650">a #GDateTime a #GTimeVal to modify + filename="glib/gdatetime.c" + line="2651">a #GTimeVal to modify @@ -10493,101 +11717,126 @@ On systems where 'long' is 64bit, this function never fails. c:identifier="g_date_time_to_timezone" version="2.26"> Create a new #GDateTime corresponding to the same instant in time as + filename="glib/gdatetime.c" + line="2781">Create a new #GDateTime corresponding to the same instant in time as @datetime, but in the time zone @tz. This call can fail in the case that the time goes out of bounds. For example, converting 0001-01-01 00:00:00 UTC to a time zone west of Greenwich will fail (due to the year 0 being out of range). - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="2793">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="2783">a #GDateTime the new #GTimeZone + filename="glib/gdatetime.c" + line="2784">the new #GTimeZone Gives the Unix time corresponding to @datetime, rounding down to the + filename="glib/gdatetime.c" + line="2605">Gives the Unix time corresponding to @datetime, rounding down to the nearest second. Unix time is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC, regardless of the time zone associated with @datetime. - + the Unix time corresponding to @datetime + filename="glib/gdatetime.c" + line="2615">the Unix time corresponding to @datetime a #GDateTime + filename="glib/gdatetime.c" + line="2607">a #GDateTime + + + + + + Gives the Unix time corresponding to @datetime, in microseconds. + +Unix time is the number of microseconds that have elapsed since 1970-01-01 +00:00:00 UTC, regardless of the time zone associated with @datetime. + + + the Unix time corresponding to @datetime + + + + + a #GDateTime Creates a new #GDateTime corresponding to the same instant in time as + filename="glib/gdatetime.c" + line="2836">Creates a new #GDateTime corresponding to the same instant in time as @datetime, but in UTC. This call is equivalent to calling g_date_time_to_timezone() with the time zone returned by g_time_zone_new_utc(). - + the newly created #GDateTime which + filename="glib/gdatetime.c" + line="2846">the newly created #GDateTime which should be freed with g_date_time_unref(), or %NULL a #GDateTime + filename="glib/gdatetime.c" + line="2838">a #GDateTime Atomically decrements the reference count of @datetime by one. + filename="glib/gdatetime.c" + line="698">Atomically decrements the reference count of @datetime by one. When the reference count reaches zero, the resources allocated by @datetime are freed - + a #GDateTime + filename="glib/gdatetime.c" + line="700">a #GDateTime @@ -10595,69 +11844,77 @@ When the reference count reaches zero, the resources allocated by Enumeration representing a day of the week; %G_DATE_MONDAY, + filename="glib/gdate.c" + line="219">Enumeration representing a day of the week; %G_DATE_MONDAY, %G_DATE_TUESDAY, etc. %G_DATE_BAD_WEEKDAY is an invalid weekday. - + invalid value + filename="glib/gdate.c" + line="221">invalid value - Monday + Monday Tuesday + filename="glib/gdate.c" + line="223">Tuesday Wednesday + filename="glib/gdate.c" + line="224">Wednesday Thursday + filename="glib/gdate.c" + line="225">Thursday - Friday + Friday Saturday + filename="glib/gdate.c" + line="227">Saturday - Sunday + Sunday Associates a string with a bit flag. Used in g_parse_debug_string(). - + the string - the flag + the flag Specifies the type of function which is called when a data element + filename="glib/gdataset.c" + line="60">Specifies the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it. - + @@ -10667,38 +11924,81 @@ should free any memory and resources allocated for it. nullable="1" allow-none="1"> the data element. + filename="glib/gdataset.c" + line="62">the data element. - + An opaque structure representing an opened directory. - + filename="glib/gdir.c" + line="51">An opaque structure representing an opened directory. + + + Opens a directory for reading. The names of the files in the +directory can then be retrieved using g_dir_read_name(). Note +that the ordering is not defined. + + + a newly allocated #GDir on success, %NULL on failure. + If non-%NULL, you must free the result with g_dir_close() + when you are finished with it. + + + + + the path to the directory you are interested in. On Unix + in the on-disk encoding. On Windows in UTF-8 + + + + Currently must be set to 0. Reserved for future use. + + + + Closes the directory and deallocates all related resources. - + filename="glib/gdir.c" + line="311">Closes the directory immediately and decrements the reference count. + +Once the reference count reaches zero, the `GDir` structure itself will be +freed. Prior to GLib 2.80, `GDir` was not reference counted. + +It is an error to call any of the `GDir` methods other than +[method@GLib.Dir.ref] and [method@GLib.Dir.unref] on a `GDir` after calling +[method@GLib.Dir.close] on it. + - + a #GDir* created by g_dir_open() + filename="glib/gdir.c" + line="313">a #GDir* created by g_dir_open() Retrieves the name of another entry in the directory, or %NULL. + filename="glib/gdir.c" + line="212">Retrieves the name of another entry in the directory, or %NULL. The order of entries returned from this function is not defined, and may vary by file system or other operating-system dependent factors. @@ -10711,11 +12011,11 @@ name is in the on-disk encoding. On Windows, as is true of all GLib functions which operate on filenames, the returned name is in UTF-8. - + The entry's name or %NULL if there are no + filename="glib/gdir.c" + line="230">The entry's name or %NULL if there are no more entries. The return value is owned by GLib and must not be modified or freed. @@ -10723,26 +12023,73 @@ filenames, the returned name is in UTF-8. a #GDir* created by g_dir_open() + filename="glib/gdir.c" + line="214">a #GDir* created by g_dir_open() + + + + + + Increment the reference count of `dir`. + + + the same pointer as `dir` + + + + + a `GDir` Resets the given directory. The next call to g_dir_read_name() + filename="glib/gdir.c" + line="282">Resets the given directory. The next call to g_dir_read_name() will return the first entry again. - + a #GDir* created by g_dir_open() + filename="glib/gdir.c" + line="284">a #GDir* created by g_dir_open() + + + + + + Decrements the reference count of `dir`. + +Once the reference count reaches zero, the directory will be closed and all +resources associated with it will be freed. If [method@GLib.Dir.close] is +called when the reference count is greater than zero, the directory is closed +but the `GDir` structure will not be freed until its reference count reaches +zero. + +It is an error to call any of the `GDir` methods other than +[method@GLib.Dir.ref] and [method@GLib.Dir.unref] on a `GDir` after calling +[method@GLib.Dir.close] on it. + + + + + + + a `GDir` @@ -10752,8 +12099,8 @@ will return the first entry again. version="2.30" throws="1"> Creates a subdirectory in the preferred directory for temporary + filename="glib/gfileutils.c" + line="1860">Creates a subdirectory in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @tmpl should be a string in the GLib file name encoding containing @@ -10764,11 +12111,11 @@ basename, no directory components are allowed. If template is Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not modified, and might thus be a read-only literal string. - + The actual name used. This string + filename="glib/gfileutils.c" + line="1878">The actual name used. This string should be freed with g_free() when not needed any longer and is is in the GLib file name encoding. In case of errors, %NULL is returned and @error will be set. @@ -10780,64 +12127,30 @@ modified, and might thus be a read-only literal string. nullable="1" allow-none="1"> Template for directory name, + filename="glib/gfileutils.c" + line="1862">Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template - - Opens a directory for reading. The names of the files in the -directory can then be retrieved using g_dir_read_name(). Note -that the ordering is not defined. - - - a newly allocated #GDir on success, %NULL on failure. - If non-%NULL, you must free the result with g_dir_close() - when you are finished with it. - - - - - the path to the directory you are interested in. On Unix - in the on-disk encoding. On Windows in UTF-8 - - - - Currently must be set to 0. Reserved for future use. - - - - The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, + filename="glib/docs.c" + line="795">The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for storage) by at least Intel, PPC and Sparc. - + the double value + filename="glib/docs.c" + line="797">the double value - + @@ -10854,16 +12167,16 @@ as appropriate for a given platform. IEEE floats and doubles are supported The type of functions that are used to 'duplicate' an object. + filename="glib/gdataset.c" + line="1224">The type of functions that are used to 'duplicate' an object. What this means depends on the context, it could just be incrementing the reference count, if @data is a ref-counted object. - + a duplicate of data + filename="glib/gdataset.c" + line="1235">a duplicate of data @@ -10872,8 +12185,8 @@ object. nullable="1" allow-none="1"> the data to duplicate + filename="glib/gdataset.c" + line="1226">the data to duplicate allow-none="1" closure="1"> user data that was specified in + filename="glib/gdataset.c" + line="1227">user data that was specified in g_datalist_id_dup_data() @@ -10891,15 +12204,15 @@ object. The base of natural logarithms. - + filename="glib/docs.c" + line="805">The base of natural logarithms. + - + @@ -10909,15 +12222,15 @@ object. Specifies the type of a function used to test two values for + filename="glib/ghash.c" + line="144">Specifies the type of a function used to test two values for equality. The function should return %TRUE if both values are equal and %FALSE otherwise. - + %TRUE if @a = @b; %FALSE otherwise + filename="glib/ghash.c" + line="153">%TRUE if @a = @b; %FALSE otherwise @@ -10926,8 +12239,8 @@ and %FALSE otherwise. nullable="1" allow-none="1"> a value + filename="glib/ghash.c" + line="146">a value nullable="1" allow-none="1"> a value to compare with + filename="glib/ghash.c" + line="147">a value to compare with Specifies the type of a function used to test two values for equality. The function should return %TRUE if both values are equal and %FALSE otherwise. This is a version of #GEqualFunc which provides a @user_data closure from the caller. - + %TRUE if @a = @b; %FALSE otherwise @@ -10963,7 +12276,7 @@ the caller. nullable="1" allow-none="1"> a value @@ -10972,7 +12285,7 @@ the caller. nullable="1" allow-none="1"> a value to compare with @@ -10982,7 +12295,7 @@ the caller. allow-none="1" closure="2"> user data provided by the caller @@ -10994,98 +12307,98 @@ the caller. glib:get-type="g_error_get_type" c:symbol-prefix="error"> The `GError` structure contains information about an error that has occurred. - + error domain, e.g. %G_FILE_ERROR error code, e.g. %G_FILE_ERROR_NOENT human-readable informative error message Creates a new #GError with the given @domain and @code, + filename="glib/gerror.c" + line="295">Creates a new #GError with the given @domain and @code, and a message formatted with @format. - + a new #GError + filename="glib/gerror.c" + line="305">a new #GError error domain + filename="glib/gerror.c" + line="297">error domain error code + filename="glib/gerror.c" + line="298">error code printf()-style format for error message + filename="glib/gerror.c" + line="299">printf()-style format for error message parameters for message format + filename="glib/gerror.c" + line="300">parameters for message format Creates a new #GError; unlike g_error_new(), @message is + filename="glib/gerror.c" + line="326">Creates a new #GError; unlike g_error_new(), @message is not a printf()-style format string. Use this function if @message contains text you don't have control over, that could include printf() escape sequences. - + a new #GError + filename="glib/gerror.c" + line="337">a new #GError error domain + filename="glib/gerror.c" + line="328">error domain error code + filename="glib/gerror.c" + line="329">error code error message + filename="glib/gerror.c" + line="330">error message @@ -11095,84 +12408,84 @@ that could include printf() escape sequences. version="2.22" introspectable="0"> Creates a new #GError with the given @domain and @code, + filename="glib/gerror.c" + line="263">Creates a new #GError with the given @domain and @code, and a message formatted with @format. - + a new #GError + filename="glib/gerror.c" + line="273">a new #GError error domain + filename="glib/gerror.c" + line="265">error domain error code + filename="glib/gerror.c" + line="266">error code printf()-style format for error message + filename="glib/gerror.c" + line="267">printf()-style format for error message #va_list of parameters for the message format + filename="glib/gerror.c" + line="268">#va_list of parameters for the message format Makes a copy of @error. - + filename="glib/gerror.c" + line="401">Makes a copy of @error. + a new #GError + filename="glib/gerror.c" + line="407">a new #GError a #GError + filename="glib/gerror.c" + line="403">a #GError Frees a #GError and associated resources. - + filename="glib/gerror.c" + line="350">Frees a #GError and associated resources. + a #GError + filename="glib/gerror.c" + line="352">a #GError Returns %TRUE if @error matches @domain and @code, %FALSE + filename="glib/gerror.c" + line="431">Returns %TRUE if @error matches @domain and @code, %FALSE otherwise. In particular, when @error is %NULL, %FALSE will be returned. @@ -11182,11 +12495,11 @@ instead treat any not-explicitly-recognized error code as being equivalent to the `FAILED` code. This way, if the domain is extended in the future to provide a more specific error code for a certain case, your code will still work. - + whether @error has @domain and @code + filename="glib/gerror.c" + line="448">whether @error has @domain and @code @@ -11195,80 +12508,84 @@ a certain case, your code will still work. nullable="1" allow-none="1"> a #GError + filename="glib/gerror.c" + line="433">a #GError an error domain + filename="glib/gerror.c" + line="434">an error domain an error code + filename="glib/gerror.c" + line="435">an error code + version="2.68"> This function registers an extended #GError domain. + filename="glib/gerror.c" + line="158">This function registers an extended #GError domain. @error_type_name will be duplicated. Otherwise does the same as g_error_domain_register_static(). - + #GQuark representing the error domain + filename="glib/gerror.c" + line="170">#GQuark representing the error domain string to create a #GQuark from + filename="glib/gerror.c" + line="160">string to create a #GQuark from size of the private error data in bytes + filename="glib/gerror.c" + line="161">size of the private error data in bytes - + function initializing fields of the private error data + filename="glib/gerror.c" + line="162">function initializing fields of the private error data - + function copying fields of the private error data + filename="glib/gerror.c" + line="163">function copying fields of the private error data - + function freeing fields of the private error data + filename="glib/gerror.c" + line="164">function freeing fields of the private error data + version="2.68"> This function registers an extended #GError domain. + filename="glib/gerror.c" + line="105">This function registers an extended #GError domain. @error_type_name should not be freed. @error_type_private_size must be greater than 0. @@ -11285,42 +12602,48 @@ fields of the private error data. It should not free the struct itself though. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function. - + #GQuark representing the error domain + filename="glib/gerror.c" + line="131">#GQuark representing the error domain static string to create a #GQuark from + filename="glib/gerror.c" + line="107">static string to create a #GQuark from size of the private error data in bytes + filename="glib/gerror.c" + line="108">size of the private error data in bytes - + function initializing fields of the private error data + filename="glib/gerror.c" + line="109">function initializing fields of the private error data - + function copying fields of the private error data + filename="glib/gerror.c" + line="110">function copying fields of the private error data - + function freeing fields of the private error data + filename="glib/gerror.c" + line="111">function freeing fields of the private error data @@ -11328,21 +12651,21 @@ already takes care of passing valid information to this function. Specifies the type of function which is called when an extended error instance is freed. It is passed the error pointer about to be freed, and should free the error's private data fields. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from @error. - + extended error to clear @@ -11350,7 +12673,7 @@ already takes care of getting the private data from @error. Specifies the type of function which is called when an extended error instance is copied. It is passed the pointer to the destination error and source error, and should copy only the fields @@ -11359,20 +12682,20 @@ of the private data from @src_error to @dest_error. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from @src_error and @dest_error. - + source extended error destination extended error @@ -11380,7 +12703,7 @@ already takes care of getting the private data from @src_error and Specifies the type of function which is called just after an extended error instance is created and its fields filled. It should only initialize the fields in the private data, which can be @@ -11388,14 +12711,14 @@ received with the generated `*_get_private()` function. Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from @error. - + extended error @@ -11403,65 +12726,65 @@ already takes care of getting the private data from @error. The possible errors, used in the @v_error field + filename="glib/gscanner.c" + line="157">The possible errors, used in the @v_error field of #GTokenValue, when the token is a %G_TOKEN_ERROR. - + unknown error + filename="glib/gscanner.c" + line="159">unknown error unexpected end of file + filename="glib/gscanner.c" + line="160">unexpected end of file unterminated string constant + filename="glib/gscanner.c" + line="161">unterminated string constant unterminated comment + filename="glib/gscanner.c" + line="162">unterminated comment non-digit character in a number + filename="glib/gscanner.c" + line="163">non-digit character in a number digit beyond radix in a number + filename="glib/gscanner.c" + line="164">digit beyond radix in a number non-decimal floating point number + filename="glib/gscanner.c" + line="165">non-decimal floating point number malformed floating point number + filename="glib/gscanner.c" + line="166">malformed floating point number Values corresponding to @errno codes returned from file operations + filename="glib/gfileutils.c" + line="62">Values corresponding to @errno codes returned from file operations on UNIX. Unlike @errno codes, GFileError values are available on all systems, even Windows. The exact meaning of each code depends on what sort of file operation you were performing; the UNIX @@ -11473,50 +12796,50 @@ It's not very portable to make detailed assumptions about exactly which errors will be returned from a given operation. Some errors don't occur on some systems, etc., sometimes there are subtle differences in when a system will report a given error, etc. - + Operation not permitted; only the owner of + filename="glib/gfileutils.c" + line="64">Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. File is a directory; you cannot open a directory + filename="glib/gfileutils.c" + line="67">File is a directory; you cannot open a directory for writing, or create or remove hard links to it. Permission denied; the file permissions do not + filename="glib/gfileutils.c" + line="69">Permission denied; the file permissions do not allow the attempted operation. Filename too long. + filename="glib/gfileutils.c" + line="71">Filename too long. No such file or directory. This is a "file + filename="glib/gfileutils.c" + line="72">No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist. A file that isn't a directory was specified when + filename="glib/gfileutils.c" + line="75">A file that isn't a directory was specified when a directory is required. No such device or address. The system tried to + filename="glib/gfileutils.c" + line="77">No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or @@ -11524,78 +12847,78 @@ differences in when a system will report a given error, etc. The underlying file system of the specified file + filename="glib/gfileutils.c" + line="82">The underlying file system of the specified file does not support memory mapping. The directory containing the new link can't be + filename="glib/gfileutils.c" + line="84">The directory containing the new link can't be modified because it's on a read-only file system. Text file busy. + filename="glib/gfileutils.c" + line="86">Text file busy. You passed in a pointer to bad memory. + filename="glib/gfileutils.c" + line="87">You passed in a pointer to bad memory. (GLib won't reliably return this, don't pass in pointers to bad memory.) Too many levels of symbolic links were encountered + filename="glib/gfileutils.c" + line="90">Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links. No space left on device; write operation on a + filename="glib/gfileutils.c" + line="93">No space left on device; write operation on a file failed because the disk is full. No memory available. The system cannot allocate + filename="glib/gfileutils.c" + line="95">No memory available. The system cannot allocate more virtual memory because its capacity is full. The current process has too many files open and + filename="glib/gfileutils.c" + line="97">The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. There are too many distinct file openings in the + filename="glib/gfileutils.c" + line="100">There are too many distinct file openings in the entire system. Bad file descriptor; for example, I/O on a + filename="glib/gfileutils.c" + line="102">Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa). Invalid argument. This is used to indicate + filename="glib/gfileutils.c" + line="105">Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function. Broken pipe; there is no process reading from the + filename="glib/gfileutils.c" + line="108">Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a 'SIGPIPE' signal; this signal terminates the program if not handled or blocked. Thus, your @@ -11604,41 +12927,41 @@ differences in when a system will report a given error, etc. Resource temporarily unavailable; the call might + filename="glib/gfileutils.c" + line="114">Resource temporarily unavailable; the call might work if you try again later. Interrupted function call; an asynchronous signal + filename="glib/gfileutils.c" + line="116">Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again. Input/output error; usually used for physical read + filename="glib/gfileutils.c" + line="119">Input/output error; usually used for physical read or write errors. i.e. the disk or other physical device hardware is returning errors. Operation not permitted; only the owner of the + filename="glib/gfileutils.c" + line="122">Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. Function not implemented; this indicates that + filename="glib/gfileutils.c" + line="125">Function not implemented; this indicates that the system is missing some functionality. Does not correspond to a UNIX error code; this + filename="glib/gfileutils.c" + line="127">Does not correspond to a UNIX error code; this is the standard "failed for unspecified reason" error code present in all #GError error code enumerations. Returned if no specific code applies. @@ -11648,13 +12971,13 @@ differences in when a system will report a given error, etc. version="2.66" c:type="GFileSetContentsFlags"> Flags to pass to g_file_set_contents_full() to affect its safety and performance. - + No guarantees about file consistency or durability. The most dangerous setting, which is slightly faster than other settings. @@ -11662,7 +12985,7 @@ performance. value="1" c:identifier="G_FILE_SET_CONTENTS_CONSISTENT"> Guarantee file consistency: after a crash, either the old version of the file or the new version of the file will be available, but not a mixture. On Unix systems this equates to an `fsync()` @@ -11673,7 +12996,7 @@ performance. value="2" c:identifier="G_FILE_SET_CONTENTS_DURABLE"> Guarantee file durability: after a crash, the new version of the file will be available. On Unix systems this equates to an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or @@ -11684,7 +13007,7 @@ performance. value="4" c:identifier="G_FILE_SET_CONTENTS_ONLY_EXISTING"> Only apply consistency and durability guarantees if the file already exists. This may speed up file operations if the file doesn’t currently exist, but may result in a corrupted version @@ -11693,15 +13016,15 @@ performance. A test to perform on a file using g_file_test(). - + filename="glib/gfileutils.c" + line="154">A test to perform on a file using g_file_test(). + %TRUE if the file is a regular file + filename="glib/gfileutils.c" + line="156">%TRUE if the file is a regular file (not a directory). Note that this test will also return %TRUE if the tested file is a symlink to a regular file. @@ -11709,44 +13032,44 @@ performance. value="2" c:identifier="G_FILE_TEST_IS_SYMLINK"> %TRUE if the file is a symlink. + filename="glib/gfileutils.c" + line="159">%TRUE if the file is a symlink. %TRUE if the file is a directory. + filename="glib/gfileutils.c" + line="160">%TRUE if the file is a directory. %TRUE if the file is executable. + filename="glib/gfileutils.c" + line="161">%TRUE if the file is executable. %TRUE if the file exists. It may or may not + filename="glib/gfileutils.c" + line="162">%TRUE if the file exists. It may or may not be a regular file. The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, + filename="glib/docs.c" + line="785">The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for storage) by at least Intel, PPC and Sparc. - + the double value + filename="glib/docs.c" + line="787">the double value - + @@ -11760,44 +13083,44 @@ as appropriate for a given platform. IEEE floats and doubles are supported Flags to modify the format of the string returned by g_format_size_full(). - + filename="glib/gutils.c" + line="2909">Flags to modify the format of the string returned by g_format_size_full(). + behave the same as g_format_size() + filename="glib/gutils.c" + line="2911">behave the same as g_format_size() include the exact number of bytes as part + filename="glib/gutils.c" + line="2912">include the exact number of bytes as part of the returned string. For example, "45.6 kB (45,612 bytes)". use IEC (base 1024) units with "KiB"-style + filename="glib/gutils.c" + line="2914">use IEC (base 1024) units with "KiB"-style suffixes. IEC units should only be used for reporting things with a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. Network and storage sizes should be reported in the normal SI units. set the size as a quantity in bits, rather than - bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’. + filename="glib/gutils.c" + line="2918">set the size as a quantity in bits, rather than + bytes, and return units in bits. For example, ‘Mbit’ rather than ‘MB’. return only value, without unit; this should + filename="glib/gutils.c" + line="2920">return only value, without unit; this should not be used together with @G_FORMAT_SIZE_LONG_FORMAT nor @G_FORMAT_SIZE_ONLY_UNIT. Since: 2.74 @@ -11805,19 +13128,19 @@ as appropriate for a given platform. IEEE floats and doubles are supported value="16" c:identifier="G_FORMAT_SIZE_ONLY_UNIT"> return only unit, without value; this should + filename="glib/gutils.c" + line="2923">return only unit, without value; this should not be used together with @G_FORMAT_SIZE_LONG_FORMAT nor @G_FORMAT_SIZE_ONLY_VALUE. Since: 2.74 Declares a type of function which takes an arbitrary data pointer argument and has no return value. It is not currently used in GLib or GTK. - + @@ -11827,7 +13150,7 @@ not currently used in GLib or GTK. nullable="1" allow-none="1"> a data pointer @@ -11835,10 +13158,10 @@ not currently used in GLib or GTK. Specifies the type of functions passed to g_list_foreach() and + filename="glib/glist.c" + line="992">Specifies the type of functions passed to g_list_foreach() and g_slist_foreach(). - + @@ -11848,8 +13171,8 @@ g_slist_foreach(). nullable="1" allow-none="1"> the element's data + filename="glib/glist.c" + line="994">the element's data allow-none="1" closure="1"> user data passed to g_list_foreach() or g_slist_foreach() + filename="glib/glist.c" + line="995">user data passed to g_list_foreach() or g_slist_foreach() - This is the platform dependent conversion specifier for scanning and -printing values of type #gint16. It is a string literal, but doesn't -include the percent-sign, such that you can add precision and length -modifiers between percent-sign and conversion specifier. - -|[<!-- language="C" --> -gint16 in; -gint32 out; -sscanf ("42", "%" G_GINT16_FORMAT, &in) -out = in * 1000; -g_print ("%" G_GINT32_FORMAT, out); - -This is not necessarily the correct format for printing and scanning -`int16_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. -]| - + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint16 or #guint16. It -is a string literal, but doesn't include the percent-sign, such -that you can add precision and length modifiers between percent-sign -and conversion specifier and append a conversion specifier. - -The following example prints "0x7b"; -|[<!-- language="C" --> -gint16 value = 123; -g_print ("%#" G_GINT16_MODIFIER "x", value); -]| - -This is not necessarily the correct modifier for printing and scanning -`int16_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. - + + - This is the platform dependent conversion specifier for scanning -and printing values of type #gint32. See also %G_GINT16_FORMAT. - -This is not necessarily the correct modifier for printing and scanning -`int32_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. - + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint32 or #guint32. It -is a string literal. See also %G_GINT16_MODIFIER. - -This is not necessarily the correct modifier for printing and scanning -`int32_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. - + + - This macro is used to insert 64-bit integer literals -into the source code. - -It is similar to the standard C `INT64_C` macro, -which should be preferred in new code. - + - a literal integer value, e.g. 0x1d636b02300a7aa7 - This is the platform dependent conversion specifier for scanning -and printing values of type #gint64. See also %G_GINT16_FORMAT. - -Some platforms do not support scanning and printing 64-bit integers, -even though the types are supported. On such platforms %G_GINT64_FORMAT -is not defined. Note that scanf() may not support 64-bit integers, even -if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() -is not recommended for parsing anyway; consider using g_ascii_strtoull() -instead. - -This is not necessarily the correct format for printing and scanning -`int64_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. - + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint64 or #guint64. -It is a string literal. - -Some platforms do not support printing 64-bit integers, even -though the types are supported. On such platforms %G_GINT64_MODIFIER -is not defined. - -This is not necessarily the correct modifier for printing and scanning -`int64_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. - + + - - This is the platform dependent conversion specifier for scanning -and printing values of type #gintptr. - -Note that this is not necessarily the correct format to scan or -print an `intptr_t`, even though the in-memory representation is the -same. -Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for -`intptr_t`. - + + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gintptr or #guintptr. -It is a string literal. - -Note that this is not necessarily the correct modifier to scan or -print an `intptr_t`, even though the in-memory representation is the -same. -Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for -`intptr_t`. - + + Expands to the GNU C `alloc_size` function attribute if the compiler + filename="glib/gmacros.h" + line="359">Expands to the GNU C `alloc_size` function attribute if the compiler is a new enough gcc. This attribute tells the compiler that the function returns a pointer to memory of a size that is specified by the @xth function parameter. @@ -12050,12 +13247,12 @@ gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1); ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. - + the index of the argument specifying the allocation size + filename="glib/gmacros.h" + line="361">the index of the argument specifying the allocation size @@ -12064,8 +13261,8 @@ See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function version="2.18" introspectable="0"> Expands to the GNU C `alloc_size` function attribute if the compiler is a + filename="glib/gmacros.h" + line="380">Expands to the GNU C `alloc_size` function attribute if the compiler is a new enough gcc. This attribute tells the compiler that the function returns a pointer to memory of a size that is specified by the product of two function parameters. @@ -12079,17 +13276,17 @@ gpointer g_malloc_n (gsize n_blocks, ]| See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. - + the index of the argument specifying one factor of the allocation size + filename="glib/gmacros.h" + line="382">the index of the argument specifying one factor of the allocation size the index of the argument specifying the second factor of the allocation size + filename="glib/gmacros.h" + line="383">the index of the argument specifying the second factor of the allocation size @@ -12098,8 +13295,8 @@ See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function version="2.42" introspectable="0"> Expands to a check for a compiler with __GNUC__ defined and a version + filename="glib/docs.c" + line="1202">Expands to a check for a compiler with __GNUC__ defined and a version greater than or equal to the major and minor numbers provided. For example, the following would only match on compilers such as GCC 4.8 or newer. @@ -12107,17 +13304,17 @@ the following would only match on compilers such as GCC 4.8 or newer. #if G_GNUC_CHECK_VERSION(4, 8) #endif ]| - + major version to check against + filename="glib/docs.c" + line="1204">major version to check against minor version to check against + filename="glib/docs.c" + line="1205">minor version to check against @@ -12126,8 +13323,8 @@ the following would only match on compilers such as GCC 4.8 or newer. version="2.26" introspectable="0"> Like %G_GNUC_DEPRECATED, but names the intended replacement for the + filename="glib/gmacros.h" + line="716">Like %G_GNUC_DEPRECATED, but names the intended replacement for the deprecated symbol if the version of gcc in use is new enough to support custom deprecation messages. @@ -12142,12 +13339,12 @@ See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function Note that if @f is a macro, it will be expanded in the warning message. You can enclose it in quotes to prevent this. (The quotes will show up in the warning, but it's better than showing the macro expansion.) - + the intended replacement for the deprecated symbol, + filename="glib/gmacros.h" + line="718">the intended replacement for the deprecated symbol, such as the name of a function @@ -12156,8 +13353,8 @@ in the warning, but it's better than showing the macro expansion.) c:identifier="G_GNUC_FORMAT" introspectable="0"> Expands to the GNU C `format_arg` function attribute if the compiler + filename="glib/gmacros.h" + line="486">Expands to the GNU C `format_arg` function attribute if the compiler is gcc. This function attribute specifies that a function takes a format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style function and modifies it, so that the result can be passed to a `printf()`, @@ -12173,12 +13370,12 @@ See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function |[<!-- language="C" --> gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); ]| - + the index of the argument + filename="glib/gmacros.h" + line="488">the index of the argument @@ -12188,11 +13385,11 @@ gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); deprecated="1" deprecated-version="2.16"> Expands to "" on all modern compilers, and to __FUNCTION__ on gcc + filename="glib/gmacros.h" + line="819">Expands to "" on all modern compilers, and to __FUNCTION__ on gcc version 2.x. Don't use it. Use G_STRFUNC() instead - + deprecated="1" deprecated-version="2.16"> Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ + filename="glib/gmacros.h" + line="828">Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ on gcc version 2.x. Don't use it. Use G_STRFUNC() instead - + Expands to the GNU C `format` function attribute if the compiler is gcc. + filename="glib/gmacros.h" + line="410">Expands to the GNU C `format` function attribute if the compiler is gcc. This is used for declaring functions which take a variable number of arguments, with the same syntax as `printf()`. It allows the compiler to type-check the arguments passed to the function. @@ -12231,18 +13428,18 @@ gint g_snprintf (gchar *string, gchar const *format, ...) G_GNUC_PRINTF (3, 4); ]| - + the index of the argument corresponding to the + filename="glib/gmacros.h" + line="412">the index of the argument corresponding to the format string (the arguments are numbered from 1) the index of the first of the format arguments, or 0 if + filename="glib/gmacros.h" + line="414">the index of the first of the format arguments, or 0 if there are no format arguments @@ -12251,8 +13448,8 @@ gint g_snprintf (gchar *string, c:identifier="G_GNUC_SCANF" introspectable="0"> Expands to the GNU C `format` function attribute if the compiler is gcc. + filename="glib/gmacros.h" + line="437">Expands to the GNU C `format` function attribute if the compiler is gcc. This is used for declaring functions which take a variable number of arguments, with the same syntax as `scanf()`. It allows the compiler to type-check the arguments passed to the function. @@ -12269,18 +13466,18 @@ int my_vscanf (MyStream *stream, See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) for details. - + the index of the argument corresponding to + filename="glib/gmacros.h" + line="439">the index of the argument corresponding to the format string (the arguments are numbered from 1) the index of the first of the format arguments, or 0 if + filename="glib/gmacros.h" + line="441">the index of the first of the format arguments, or 0 if there are no format arguments @@ -12290,8 +13487,8 @@ for details. version="2.60" introspectable="0"> Expands to the GNU C `strftime` format function attribute if the compiler + filename="glib/gmacros.h" + line="463">Expands to the GNU C `strftime` format function attribute if the compiler is gcc. This is used for declaring functions which take a format argument which is passed to `strftime()` or an API implementing its formats. It allows the compiler check the format passed to the function. @@ -12305,215 +13502,100 @@ gsize my_strftime (MyBuffer *buffer, See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) for details. - + the index of the argument corresponding to + filename="glib/gmacros.h" + line="465">the index of the argument corresponding to the format string (the arguments are numbered from 1) - This macro is used to insert #goffset 64-bit integer literals -into the source code. - -See also G_GINT64_CONSTANT(). - + - a literal integer value, e.g. 0x1d636b02300a7aa7 - - This is the platform dependent conversion specifier for scanning -and printing values of type #gsize. See also %G_GINT16_FORMAT. - -Note that this is not necessarily the correct format to scan or -print a `size_t`, even though the in-memory representation is the -same. The standard C `"zu"` format should be used for `size_t`, -assuming a C99-compliant `printf` implementation is available. - + + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gsize. It -is a string literal. - -Note that this is not necessarily the correct modifier to scan or -print a `size_t`, even though the in-memory representation is the -same. The Standard C `"z"` modifier should be used for `size_t`, -assuming a C99-compliant `printf` implementation is available. - + + - - This is the platform dependent conversion specifier for scanning -and printing values of type #gssize. See also %G_GINT16_FORMAT. - -Note that this is not necessarily the correct format to scan or print -a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory -representation is the same. -On POSIX platforms, the `"zd"` format should be used for `ssize_t`. - + + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gssize. It -is a string literal. - -Note that this is not necessarily the correct modifier to scan or print -a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory -representation is the same. -On POSIX platforms, the `"z"` modifier should be used for `ssize_t`. - + + - This is the platform dependent conversion specifier for scanning -and printing values of type #guint16. See also %G_GINT16_FORMAT - -This is not necessarily the correct modifier for printing and scanning -`uint16_t` values, even though the in-memory representation is the same. -Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`. - + - This is the platform dependent conversion specifier for scanning -and printing values of type #guint32. See also %G_GINT16_FORMAT. - -This is not necessarily the correct modifier for printing and scanning -`uint32_t` values, even though the in-memory representation is the same. -Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`. - + - This macro is used to insert 64-bit unsigned integer -literals into the source code. - -It is similar to the standard C `UINT64_C` macro, -which should be preferred in new code. - + - a literal integer value, e.g. 0x1d636b02300a7aa7U - This is the platform dependent conversion specifier for scanning -and printing values of type #guint64. See also %G_GINT16_FORMAT. - -Some platforms do not support scanning and printing 64-bit integers, -even though the types are supported. On such platforms %G_GUINT64_FORMAT -is not defined. Note that scanf() may not support 64-bit integers, even -if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() -is not recommended for parsing anyway; consider using g_ascii_strtoull() -instead. - -This is not necessarily the correct modifier for printing and scanning -`uint64_t` values, even though the in-memory representation is the same. -Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`. - + - - This is the platform dependent conversion specifier -for scanning and printing values of type #guintptr. - -Note that this is not necessarily the correct format to scan or -print a `uintptr_t`, even though the in-memory representation is the -same. -Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for -`uintptr_t`. - + + - + - + Defined to 1 if gcc-style visibility handling is supported. - + filename="glib/docs.c" + line="1508">Defined to 1 if gcc-style visibility handling is supported. + - + - + Specifies the type of the function passed to g_hash_table_foreach(). + filename="glib/ghash.c" + line="112">Specifies the type of the function passed to g_hash_table_foreach(). It is called with each key/value pair, together with the @user_data parameter which is passed to g_hash_table_foreach(). - + @@ -12523,8 +13605,8 @@ parameter which is passed to g_hash_table_foreach(). nullable="1" allow-none="1"> a key + filename="glib/ghash.c" + line="114">a key nullable="1" allow-none="1"> the value corresponding to the key + filename="glib/ghash.c" + line="115">the value corresponding to the key allow-none="1" closure="2"> user data passed to g_hash_table_foreach() + filename="glib/ghash.c" + line="116">user data passed to g_hash_table_foreach() Casts a pointer to a `GHook*`. - + filename="glib/ghook.c" + line="90">Casts a pointer to a `GHook*`. + a pointer + filename="glib/ghook.c" + line="92">a pointer @@ -12565,15 +13647,15 @@ parameter which is passed to g_hash_table_foreach(). c:identifier="G_HOOK_ACTIVE" introspectable="0"> Returns %TRUE if the #GHook is active, which is normally the case + filename="glib/ghook.c" + line="107">Returns %TRUE if the #GHook is active, which is normally the case until the #GHook is destroyed. - + a #GHook + filename="glib/ghook.c" + line="109">a #GHook @@ -12581,14 +13663,14 @@ until the #GHook is destroyed. c:identifier="G_HOOK_FLAGS" introspectable="0"> Gets the flags of a hook. - + filename="glib/ghook.c" + line="74">Gets the flags of a hook. + a #GHook + filename="glib/ghook.c" + line="76">a #GHook @@ -12596,26 +13678,26 @@ until the #GHook is destroyed. value="4" c:type="G_HOOK_FLAG_USER_SHIFT"> The position of the first bit which is not reserved for internal + filename="glib/ghook.c" + line="81">The position of the first bit which is not reserved for internal use be the #GHook implementation, i.e. `1 << G_HOOK_FLAG_USER_SHIFT` is the first bit which can be used for application-defined flags. - + Returns %TRUE if the #GHook function is currently executing. - + filename="glib/ghook.c" + line="117">Returns %TRUE if the #GHook function is currently executing. + a #GHook + filename="glib/ghook.c" + line="119">a #GHook @@ -12623,14 +13705,14 @@ bit which can be used for application-defined flags. c:identifier="G_HOOK_IS_UNLINKED" introspectable="0"> Returns %TRUE if the #GHook is not in a #GHookList. - + filename="glib/ghook.c" + line="126">Returns %TRUE if the #GHook is not in a #GHookList. + a #GHook + filename="glib/ghook.c" + line="128">a #GHook @@ -12638,32 +13720,37 @@ bit which can be used for application-defined flags. c:identifier="G_HOOK_IS_VALID" introspectable="0"> Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, + filename="glib/ghook.c" + line="97">Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active and it has not been destroyed. - + a #GHook + filename="glib/ghook.c" + line="99">a #GHook Specifies the type of the function passed to -g_hash_table_foreach_remove(). It is called with each key/value -pair, together with the @user_data parameter passed to -g_hash_table_foreach_remove(). It should return %TRUE if the -key/value pair should be removed from the #GHashTable. - + filename="glib/ghash.c" + line="123">Specifies the type of the function passed to +[func@GLib.HashTable.find], [func@GLib.HashTable.foreach_remove], and +[func@GLib.HashTable.foreach_steal]. + +The function is called with each key/value pair, together with +the @user_data parameter passed to the calling function. + +The function should return true if the key/value pair should be +selected, meaning it has been found or it should be removed from the +[struct@GLib.HashTable], depending on the calling function. + %TRUE if the key/value pair should be removed from the - #GHashTable + filename="glib/ghash.c" + line="140">true if the key/value pair should be selected, and + false otherwise @@ -12672,8 +13759,8 @@ key/value pair should be removed from the #GHashTable. nullable="1" allow-none="1"> a key + filename="glib/ghash.c" + line="125">a key nullable="1" allow-none="1"> the value associated with the key + filename="glib/ghash.c" + line="126">the value associated with the key allow-none="1" closure="2"> user data passed to g_hash_table_remove() + filename="glib/ghash.c" + line="127">user data passed to the calling function Specifies the type of the hash function which is passed to + filename="glib/ghash.c" + line="74">Specifies the type of the hash function which is passed to g_hash_table_new() when a #GHashTable is created. The function is passed a key and should return a #guint hash value. @@ -12730,11 +13817,11 @@ The key to choosing a good hash is unpredictability. Even cryptographic hashes are very easy to find collisions for when the remainder is taken modulo a somewhat predictable prime number. There must be an element of randomness that an attacker is unable to guess. - + the hash value corresponding to the key + filename="glib/ghash.c" + line="109">the hash value corresponding to the key @@ -12743,8 +13830,8 @@ must be an element of randomness that an attacker is unable to guess. nullable="1" allow-none="1"> a key + filename="glib/ghash.c" + line="76">a key @@ -12756,15 +13843,15 @@ must be an element of randomness that an attacker is unable to guess. glib:get-type="g_hash_table_get_type" c:symbol-prefix="hash_table"> The #GHashTable struct is an opaque data structure to represent a -[Hash Table][glib-Hash-Tables]. It should only be accessed via the + filename="glib/ghash.c" + line="66">The #GHashTable struct is an opaque data structure to represent a +[Hash Table](data-structures.html#hash-tables). It should only be accessed via the following functions. - + This is a convenience function for using a #GHashTable as a set. It + filename="glib/ghash.c" + line="1637">This is a convenience function for using a #GHashTable as a set. It is equivalent to calling g_hash_table_replace() with @key as both the key and the value. @@ -12779,18 +13866,18 @@ the discussion in the section description. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. - + %TRUE if the key did not exist yet + filename="glib/ghash.c" + line="1658">%TRUE if the key did not exist yet a #GHashTable + filename="glib/ghash.c" + line="1639">a #GHashTable @@ -12801,8 +13888,8 @@ or not. nullable="1" allow-none="1"> a key to insert + filename="glib/ghash.c" + line="1640">a key to insert @@ -12811,20 +13898,20 @@ or not. c:identifier="g_hash_table_contains" version="2.32"> Checks if @key is in @hash_table. - + filename="glib/ghash.c" + line="1669">Checks if @key is in @hash_table. + %TRUE if @key is in @hash_table, %FALSE otherwise. + filename="glib/ghash.c" + line="1676">%TRUE if @key is in @hash_table, %FALSE otherwise. a #GHashTable + filename="glib/ghash.c" + line="1671">a #GHashTable @@ -12835,30 +13922,30 @@ or not. nullable="1" allow-none="1"> a key to check + filename="glib/ghash.c" + line="1672">a key to check Destroys all keys and values in the #GHashTable and decrements its + filename="glib/ghash.c" + line="1447">Destroys all keys and values in the #GHashTable and decrements its reference count by 1. If keys and/or values are dynamically allocated, you should either free them first or create the #GHashTable with destroy notifiers using g_hash_table_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values during the destruction phase. - + a #GHashTable + filename="glib/ghash.c" + line="1449">a #GHashTable @@ -12866,13 +13953,10 @@ destruction phase. - + Calls the given function for key/value pairs in the #GHashTable + filename="glib/ghash.c" + line="2136">Calls the given function for key/value pairs in the #GHashTable until @predicate returns %TRUE. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not be modified while iterating over it (you can't @@ -12885,11 +13969,11 @@ once per every entry in a hash table) should probably be reworked to use additional or different data structures for reverse lookups (keep in mind that an O(n) find/foreach operation issued for all n values in a hash table ends up needing O(n*n) operations). - + The value of the first key/value pair is returned, + filename="glib/ghash.c" + line="2156">The value of the first key/value pair is returned, for which @predicate evaluates to %TRUE. If no pair with the requested property is found, %NULL is returned. @@ -12897,17 +13981,20 @@ values in a hash table ends up needing O(n*n) operations). a #GHashTable + filename="glib/ghash.c" + line="2138">a #GHashTable - + function to test the key/value pairs for a certain property + filename="glib/ghash.c" + line="2139">function to test the key/value pairs for a certain property nullable="1" allow-none="1"> user data to pass to the function + filename="glib/ghash.c" + line="2140">user data to pass to the function - + Calls the given function for each of the key/value pairs in the + filename="glib/ghash.c" + line="2085">Calls the given function for each of the key/value pairs in the #GHashTable. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not be modified while iterating over it (you can't add/remove @@ -12938,24 +14023,27 @@ the hash table is not defined. See g_hash_table_find() for performance caveats for linear order searches in contrast to g_hash_table_lookup(). - + a #GHashTable + filename="glib/ghash.c" + line="2087">a #GHashTable - + the function to call for each key/value pair + filename="glib/ghash.c" + line="2088">the function to call for each key/value pair nullable="1" allow-none="1"> user data to pass to the function + filename="glib/ghash.c" + line="2089">user data to pass to the function + c:identifier="g_hash_table_foreach_remove"> Calls the given function for each key/value pair in the + filename="glib/ghash.c" + line="2030">Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable. If you supplied key or value destroy functions when creating the #GHashTable, they are @@ -12982,27 +14069,30 @@ used to free the memory allocated for the removed keys and values. See #GHashTableIter for an alternative way to loop over the key/value pairs in the hash table. - + the number of key/value pairs removed + filename="glib/ghash.c" + line="2045">the number of key/value pairs removed a #GHashTable + filename="glib/ghash.c" + line="2032">a #GHashTable - + the function to call for each key/value pair + filename="glib/ghash.c" + line="2033">the function to call for each key/value pair nullable="1" allow-none="1"> user data to pass to the function + filename="glib/ghash.c" + line="2034">user data to pass to the function - + Calls the given function for each key/value pair in the + filename="glib/ghash.c" + line="2058">Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable, but no key or value destroy functions are called. See #GHashTableIter for an alternative way to loop over the key/value pairs in the hash table. - + the number of key/value pairs removed. + filename="glib/ghash.c" + line="2072">the number of key/value pairs removed. a #GHashTable + filename="glib/ghash.c" + line="2060">a #GHashTable - + the function to call for each key/value pair + filename="glib/ghash.c" + line="2061">the function to call for each key/value pair nullable="1" allow-none="1"> user data to pass to the function + filename="glib/ghash.c" + line="2062">user data to pass to the function @@ -13067,18 +14158,18 @@ key/value pairs in the hash table. version="2.14" introspectable="0"> Retrieves every key inside @hash_table. The returned data is valid + filename="glib/ghash.c" + line="2218">Retrieves every key inside @hash_table. The returned data is valid until changes to the hash release those keys. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. - + a #GList containing all the keys + filename="glib/ghash.c" + line="2229">a #GList containing all the keys inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. @@ -13089,8 +14180,8 @@ To iterate over the entries in a #GHashTable more efficiently, use a a #GHashTable + filename="glib/ghash.c" + line="2220">a #GHashTable @@ -13103,8 +14194,8 @@ To iterate over the entries in a #GHashTable more efficiently, use a version="2.40" introspectable="0"> Retrieves every key inside @hash_table, as an array. + filename="glib/ghash.c" + line="2254">Retrieves every key inside @hash_table, as an array. The returned array is %NULL-terminated but may contain %NULL as a key. Use @length to determine the true length if it's possible that @@ -13121,11 +14212,11 @@ You should always free the return result with g_free(). In the above-mentioned case of a string-keyed hash table, it may be appropriate to use g_strfreev() if you call g_hash_table_steal_all() first to transfer ownership of the keys. - + a + filename="glib/ghash.c" + line="2277">a %NULL-terminated array containing each key from the table. @@ -13134,8 +14225,8 @@ first to transfer ownership of the keys. a #GHashTable + filename="glib/ghash.c" + line="2256">a #GHashTable @@ -13148,8 +14239,8 @@ first to transfer ownership of the keys. optional="1" allow-none="1"> the length of the returned array + filename="glib/ghash.c" + line="2257">the length of the returned array @@ -13159,8 +14250,8 @@ first to transfer ownership of the keys. version="2.76" introspectable="0"> Retrieves every key inside @hash_table, as a #GPtrArray. + filename="glib/ghash.c" + line="2304">Retrieves every key inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those keys. This iterates over every entry in the hash table to build its return value. @@ -13168,11 +14259,11 @@ To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). - + a #GPtrArray containing each key from + filename="glib/ghash.c" + line="2317">a #GPtrArray containing each key from the table. Unref with with g_ptr_array_unref() when done. @@ -13181,8 +14272,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="2306">a #GHashTable @@ -13195,18 +14286,18 @@ the table. Unref with with g_ptr_array_unref() when done. version="2.14" introspectable="0"> Retrieves every value inside @hash_table. The returned data + filename="glib/ghash.c" + line="2343">Retrieves every value inside @hash_table. The returned data is valid until @hash_table is modified. This iterates over every entry in the hash table to build its return value. To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. - + a #GList containing all the values + filename="glib/ghash.c" + line="2354">a #GList containing all the values inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. @@ -13217,8 +14308,8 @@ To iterate over the entries in a #GHashTable more efficiently, use a a #GHashTable + filename="glib/ghash.c" + line="2345">a #GHashTable @@ -13231,8 +14322,8 @@ To iterate over the entries in a #GHashTable more efficiently, use a version="2.76" introspectable="0"> Retrieves every value inside @hash_table, as a #GPtrArray. + filename="glib/ghash.c" + line="2379">Retrieves every value inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those values. This iterates over every entry in the hash table to build its return value. @@ -13240,11 +14331,11 @@ To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). - + a #GPtrArray containing each value from + filename="glib/ghash.c" + line="2392">a #GPtrArray containing each value from the table. Unref with with g_ptr_array_unref() when done. @@ -13253,8 +14344,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="2381">a #GHashTable @@ -13264,8 +14355,8 @@ the table. Unref with with g_ptr_array_unref() when done. Inserts a new key and value into a #GHashTable. + filename="glib/ghash.c" + line="1580">Inserts a new key and value into a #GHashTable. If the key already exists in the #GHashTable its current value is replaced with the new value. If you supplied a @@ -13277,18 +14368,18 @@ key is freed using that function. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. - + %TRUE if the key did not exist yet + filename="glib/ghash.c" + line="1599">%TRUE if the key did not exist yet a #GHashTable + filename="glib/ghash.c" + line="1582">a #GHashTable @@ -13299,8 +14390,8 @@ or not. nullable="1" allow-none="1"> a key to insert + filename="glib/ghash.c" + line="1583">a key to insert nullable="1" allow-none="1"> the value to associate with the key + filename="glib/ghash.c" + line="1584">the value to associate with the key Looks up a key in a #GHashTable. Note that this function cannot + filename="glib/ghash.c" + line="1467">Looks up a key in a #GHashTable. Note that this function cannot distinguish between a key that is not present and one which is present and has the value %NULL. If you need this distinction, use g_hash_table_lookup_extended(). - + the associated value, or %NULL if the key is not found + filename="glib/ghash.c" + line="1477">the associated value, or %NULL if the key is not found a #GHashTable + filename="glib/ghash.c" + line="1469">a #GHashTable @@ -13343,8 +14434,8 @@ g_hash_table_lookup_extended(). nullable="1" allow-none="1"> the key to look up + filename="glib/ghash.c" + line="1470">the key to look up @@ -13352,8 +14443,8 @@ g_hash_table_lookup_extended(). Looks up a key in the #GHashTable, returning the original key and the + filename="glib/ghash.c" + line="1495">Looks up a key in the #GHashTable, returning the original key and the associated value and a #gboolean which is %TRUE if the key was found. This is useful if you need to free the memory allocated for the original key, for example before calling g_hash_table_remove(). @@ -13361,18 +14452,18 @@ for example before calling g_hash_table_remove(). You can actually pass %NULL for @lookup_key to test whether the %NULL key exists, provided the hash and equal functions of @hash_table are %NULL-safe. - + %TRUE if the key was found in the #GHashTable + filename="glib/ghash.c" + line="1512">%TRUE if the key was found in the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1497">a #GHashTable @@ -13383,8 +14474,8 @@ of @hash_table are %NULL-safe. nullable="1" allow-none="1"> the key to look up + filename="glib/ghash.c" + line="1498">the key to look up optional="1" allow-none="1"> return location for the original key + filename="glib/ghash.c" + line="1499">return location for the original key optional="1" allow-none="1"> return location for the value associated + filename="glib/ghash.c" + line="1500">return location for the value associated with the key @@ -13416,8 +14507,8 @@ with the key Creates a new #GHashTable with a reference count of 1. + filename="glib/ghash.c" + line="956">Creates a new #GHashTable with a reference count of 1. Hash values returned by @hash_func are used to determine where keys are stored within the #GHashTable data structure. The g_direct_hash(), @@ -13433,11 +14524,11 @@ a similar fashion to g_direct_equal(), but without the overhead of a function call. @key_equal_func is called with the key from the hash table as its first parameter, and the user-provided key to check against as its second. - - + + a new #GHashTable + filename="glib/ghash.c" + line="978">a new #GHashTable @@ -13446,14 +14537,14 @@ its second. a function to create a hash value from a key + filename="glib/ghash.c" + line="958">a function to create a hash value from a key a function to check two keys for equality + filename="glib/ghash.c" + line="959">a function to check two keys for equality @@ -13462,8 +14553,8 @@ its second. c:identifier="g_hash_table_new_full" introspectable="0"> Creates a new #GHashTable like g_hash_table_new() with a reference + filename="glib/ghash.c" + line="988">Creates a new #GHashTable like g_hash_table_new() with a reference count of 1 and allows to specify functions to free the memory allocated for the key and value that get called when removing the entry from the #GHashTable. @@ -13474,11 +14565,11 @@ permissible if the application still holds a reference to the hash table. This means that you may need to ensure that the hash table is empty by calling g_hash_table_remove_all() before releasing the last reference using g_hash_table_unref(). - - + + a new #GHashTable + filename="glib/ghash.c" + line="1011">a new #GHashTable @@ -13487,8 +14578,8 @@ g_hash_table_unref(). a function to create a hash value from a key + filename="glib/ghash.c" + line="990">a function to create a hash value from a key scope="notified" destroy="3"> a function to check two keys for equality + filename="glib/ghash.c" + line="991">a function to check two keys for equality allow-none="1" scope="async"> a function to free the memory allocated for the key + filename="glib/ghash.c" + line="992">a function to free the memory allocated for the key used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. @@ -13518,8 +14609,8 @@ g_hash_table_unref(). allow-none="1" scope="async"> a function to free the memory allocated for the + filename="glib/ghash.c" + line="995">a function to free the memory allocated for the value used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. @@ -13530,8 +14621,8 @@ g_hash_table_unref(). c:identifier="g_hash_table_new_similar" version="2.72"> Creates a new #GHashTable like g_hash_table_new_full() with a reference + filename="glib/ghash.c" + line="1038">Creates a new #GHashTable like g_hash_table_new_full() with a reference count of 1. It inherits the hash function, the key equal function, the key destroy function, @@ -13539,11 +14630,11 @@ as well as the value destroy function, from @other_hash_table. The returned hash table will be empty; it will not contain the keys or values from @other_hash_table. - + a new #GHashTable + filename="glib/ghash.c" + line="1051">a new #GHashTable @@ -13552,8 +14643,8 @@ or values from @other_hash_table. Another #GHashTable + filename="glib/ghash.c" + line="1040">Another #GHashTable @@ -13561,19 +14652,16 @@ or values from @other_hash_table. - + Atomically increments the reference count of @hash_table by one. + filename="glib/ghash.c" + line="1399">Atomically increments the reference count of @hash_table by one. This function is MT-safe and may be called from any thread. - - + + the passed in #GHashTable + filename="glib/ghash.c" + line="1406">the passed in #GHashTable @@ -13582,8 +14670,8 @@ This function is MT-safe and may be called from any thread. a valid #GHashTable + filename="glib/ghash.c" + line="1401">a valid #GHashTable @@ -13593,25 +14681,25 @@ This function is MT-safe and may be called from any thread. Removes a key and its associated value from a #GHashTable. + filename="glib/ghash.c" + line="1732">Removes a key and its associated value from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. - + %TRUE if the key was found and removed from the #GHashTable + filename="glib/ghash.c" + line="1744">%TRUE if the key was found and removed from the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1734">a #GHashTable @@ -13622,8 +14710,8 @@ yourself. nullable="1" allow-none="1"> the key to remove + filename="glib/ghash.c" + line="1735">the key to remove @@ -13632,22 +14720,22 @@ yourself. c:identifier="g_hash_table_remove_all" version="2.12"> Removes all keys and their associated values from a #GHashTable. + filename="glib/ghash.c" + line="1849">Removes all keys and their associated values from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the keys and values are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. - + a #GHashTable + filename="glib/ghash.c" + line="1851">a #GHashTable @@ -13657,8 +14745,8 @@ values are freed yourself. Inserts a new key and value into a #GHashTable similar to + filename="glib/ghash.c" + line="1609">Inserts a new key and value into a #GHashTable similar to g_hash_table_insert(). The difference is that if the key already exists in the #GHashTable, it gets replaced by the new key. If you supplied a @value_destroy_func when creating @@ -13669,18 +14757,18 @@ If you supplied a @key_destroy_func when creating the Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. - + %TRUE if the key did not exist yet + filename="glib/ghash.c" + line="1627">%TRUE if the key did not exist yet a #GHashTable + filename="glib/ghash.c" + line="1611">a #GHashTable @@ -13691,8 +14779,8 @@ or not. nullable="1" allow-none="1"> a key to insert + filename="glib/ghash.c" + line="1612">a key to insert nullable="1" allow-none="1"> the value to associate with the key + filename="glib/ghash.c" + line="1613">the value to associate with the key Returns the number of elements contained in the #GHashTable. - + filename="glib/ghash.c" + line="2202">Returns the number of elements contained in the #GHashTable. + the number of key/value pairs in the #GHashTable. + filename="glib/ghash.c" + line="2208">the number of key/value pairs in the #GHashTable. a #GHashTable + filename="glib/ghash.c" + line="2204">a #GHashTable @@ -13731,21 +14819,21 @@ or not. Removes a key and its associated value from a #GHashTable without + filename="glib/ghash.c" + line="1753">Removes a key and its associated value from a #GHashTable without calling the key and value destroy functions. - + %TRUE if the key was found and removed from the #GHashTable + filename="glib/ghash.c" + line="1761">%TRUE if the key was found and removed from the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1755">a #GHashTable @@ -13756,8 +14844,8 @@ calling the key and value destroy functions. nullable="1" allow-none="1"> the key to remove + filename="glib/ghash.c" + line="1756">the key to remove @@ -13766,18 +14854,18 @@ calling the key and value destroy functions. c:identifier="g_hash_table_steal_all" version="2.12"> Removes all keys and their associated values from a #GHashTable + filename="glib/ghash.c" + line="1876">Removes all keys and their associated values from a #GHashTable without calling the key and value destroy functions. - + a #GHashTable + filename="glib/ghash.c" + line="1878">a #GHashTable @@ -13790,16 +14878,16 @@ without calling the key and value destroy functions. version="2.76" introspectable="0"> Removes all keys and their associated values from a #GHashTable + filename="glib/ghash.c" + line="1899">Removes all keys and their associated values from a #GHashTable without calling the key destroy functions, returning the keys as a #GPtrArray with the free func set to the @hash_table key destroy function. - + a #GPtrArray containing each key of + filename="glib/ghash.c" + line="1908">a #GPtrArray containing each key of the table. Unref with with g_ptr_array_unref() when done. @@ -13808,8 +14896,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="1901">a #GHashTable @@ -13822,16 +14910,16 @@ the table. Unref with with g_ptr_array_unref() when done. version="2.76" introspectable="0"> Removes all keys and their associated values from a #GHashTable + filename="glib/ghash.c" + line="1936">Removes all keys and their associated values from a #GHashTable without calling the value destroy functions, returning the values as a #GPtrArray with the free func set to the @hash_table value destroy function. - + a #GPtrArray containing each value of + filename="glib/ghash.c" + line="1945">a #GPtrArray containing each value of the table. Unref with with g_ptr_array_unref() when done. @@ -13840,8 +14928,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="1938">a #GHashTable @@ -13853,8 +14941,8 @@ the table. Unref with with g_ptr_array_unref() when done. c:identifier="g_hash_table_steal_extended" version="2.58"> Looks up a key in the #GHashTable, stealing the original key and the + filename="glib/ghash.c" + line="1770">Looks up a key in the #GHashTable, stealing the original key and the associated value and returning %TRUE if the key was found. If the key was not found, %FALSE is returned. @@ -13868,20 +14956,21 @@ You can pass %NULL for @lookup_key, provided the hash and equal functions of @hash_table are %NULL-safe. The dictionary implementation optimizes for having all values identical to -their keys, for example by using g_hash_table_add(). When stealing both the -key and the value from such a dictionary, the value will be %NULL. - +their keys, for example by using g_hash_table_add(). Before 2.82, when +stealing both the key and the value from such a dictionary, the value was +%NULL. Since 2.82, the returned value and key will be the same. + %TRUE if the key was found in the #GHashTable + filename="glib/ghash.c" + line="1797">%TRUE if the key was found in the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1772">a #GHashTable @@ -13892,8 +14981,8 @@ key and the value from such a dictionary, the value will be %NULL. nullable="1" allow-none="1"> the key to look up + filename="glib/ghash.c" + line="1773">the key to look up optional="1" allow-none="1"> return location for the + filename="glib/ghash.c" + line="1774">return location for the original key @@ -13917,8 +15006,8 @@ key and the value from such a dictionary, the value will be %NULL. optional="1" allow-none="1"> return location + filename="glib/ghash.c" + line="1776">return location for the value associated with the key @@ -13926,20 +15015,20 @@ key and the value from such a dictionary, the value will be %NULL. Atomically decrements the reference count of @hash_table by one. + filename="glib/ghash.c" + line="1420">Atomically decrements the reference count of @hash_table by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. - + - + a valid #GHashTable + filename="glib/ghash.c" + line="1422">a valid #GHashTable @@ -13950,15 +15039,15 @@ This function is MT-safe and may be called from any thread. A GHashTableIter structure represents an iterator that can be used + filename="glib/ghash.c" + line="156">A GHashTableIter structure represents an iterator that can be used to iterate over the elements of a #GHashTable. GHashTableIter structures are typically allocated on the stack and then initialized with g_hash_table_iter_init(). The iteration order of a #GHashTableIter over the keys/values in a hash table is not defined. - + @@ -13979,16 +15068,15 @@ table is not defined. + version="2.16"> Returns the #GHashTable associated with @iter. - - + filename="glib/ghash.c" + line="1156">Returns the #GHashTable associated with @iter. + + the #GHashTable associated with @iter. + filename="glib/ghash.c" + line="1162">the #GHashTable associated with @iter. @@ -13997,16 +15085,16 @@ table is not defined. an initialized #GHashTableIter + filename="glib/ghash.c" + line="1158">an initialized #GHashTableIter Initializes a key/value pair iterator and associates it with + filename="glib/ghash.c" + line="1065">Initializes a key/value pair iterator and associates it with @hash_table. Modifying the hash table after calling this function invalidates the returned iterator. @@ -14023,21 +15111,21 @@ while (g_hash_table_iter_next (&iter, &key, &value)) // do something with key and value } ]| - + an uninitialized #GHashTableIter + filename="glib/ghash.c" + line="1067">an uninitialized #GHashTableIter a #GHashTable + filename="glib/ghash.c" + line="1068">a #GHashTable @@ -14047,22 +15135,22 @@ while (g_hash_table_iter_next (&iter, &key, &value)) Advances @iter and retrieves the key and/or value that are now + filename="glib/ghash.c" + line="1106">Advances @iter and retrieves the key and/or value that are now pointed to as a result of this advancement. If %FALSE is returned, @key and @value are not set, and the iterator becomes invalid. - + %FALSE if the end of the #GHashTable has been reached. + filename="glib/ghash.c" + line="1116">%FALSE if the end of the #GHashTable has been reached. an initialized #GHashTableIter + filename="glib/ghash.c" + line="1108">an initialized #GHashTableIter a location to store the key + filename="glib/ghash.c" + line="1109">a location to store the key a location to store the value + filename="glib/ghash.c" + line="1110">a location to store the value @@ -14095,8 +15183,8 @@ pointed to as a result of this advancement. If %FALSE is returned, c:identifier="g_hash_table_iter_remove" version="2.16"> Removes the key/value pair currently pointed to by the iterator + filename="glib/ghash.c" + line="1192">Removes the key/value pair currently pointed to by the iterator from its associated #GHashTable. Can only be called after g_hash_table_iter_next() returned %TRUE, and cannot be called more than once for the same key/value pair. @@ -14114,15 +15202,15 @@ while (g_hash_table_iter_next (&iter, &key, &value)) g_hash_table_iter_remove (&iter); } ]| - + an initialized #GHashTableIter + filename="glib/ghash.c" + line="1194">an initialized #GHashTableIter @@ -14131,22 +15219,22 @@ while (g_hash_table_iter_next (&iter, &key, &value)) c:identifier="g_hash_table_iter_replace" version="2.30"> Replaces the value currently pointed to by the iterator + filename="glib/ghash.c" + line="1337">Replaces the value currently pointed to by the iterator from its associated #GHashTable. Can only be called after g_hash_table_iter_next() returned %TRUE. If you supplied a @value_destroy_func when creating the #GHashTable, the old value is freed using that function. - + an initialized #GHashTableIter + filename="glib/ghash.c" + line="1339">an initialized #GHashTableIter the value to replace with + filename="glib/ghash.c" + line="1340">the value to replace with @@ -14164,55 +15252,120 @@ If you supplied a @value_destroy_func when creating the c:identifier="g_hash_table_iter_steal" version="2.16"> Removes the key/value pair currently pointed to by the + filename="glib/ghash.c" + line="1380">Removes the key/value pair currently pointed to by the iterator from its associated #GHashTable, without calling the key and value destroy functions. Can only be called after g_hash_table_iter_next() returned %TRUE, and cannot be called more than once for the same key/value pair. - + an initialized #GHashTableIter + filename="glib/ghash.c" + line="1382">an initialized #GHashTableIter - + An opaque structure representing a HMAC operation. -To create a new GHmac, use g_hmac_new(). To free -a GHmac, use g_hmac_unref(). - - + filename="glib/ghmac.c" + line="39">HMACs should be used when producing a cookie or hash based on data +and a key. Simple mechanisms for using SHA1 and other algorithms to +digest a key and data together are vulnerable to various security +issues. +[HMAC](http://en.wikipedia.org/wiki/HMAC) +uses algorithms like SHA1 in a secure way to produce a digest of a +key and data. + +Both the key and data are arbitrary byte arrays of bytes or characters. + +Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 +in GLib 2.42. Support for SHA-384 was added in GLib 2.52. + +To create a new `GHmac`, use [ctor@GLib.Hmac.new]. To free a `GHmac`, use +[method@GLib.Hmac.unref]. + + Copies a #GHmac. If @hmac has been closed, by calling + filename="glib/ghmac.c" + line="69">Creates a new #GHmac, using the digest algorithm @digest_type. +If the @digest_type is not known, %NULL is returned. +A #GHmac can be used to compute the HMAC of a key and an +arbitrary binary blob, using different hashing algorithms. + +A #GHmac works by feeding a binary blob through g_hmac_update() +until the data is complete; the digest can then be extracted +using g_hmac_get_string(), which will return the checksum as a +hexadecimal string; or g_hmac_get_digest(), which will return a +array of raw bytes. Once either g_hmac_get_string() or +g_hmac_get_digest() have been called on a #GHmac, the HMAC +will be closed and it won't be possible to call g_hmac_update() +on it anymore. + +Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. +Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. + + + the newly created #GHmac, or %NULL. + Use g_hmac_unref() to free the memory allocated by it. + + + + + the desired type of digest + + + + the key for the HMAC + + + + + + the length of the keys + + + + + + Copies a #GHmac. If @hmac has been closed, by calling g_hmac_get_string() or g_hmac_get_digest(), the copied HMAC will be closed as well. - - + + the copy of the passed #GHmac. Use g_hmac_unref() + filename="glib/ghmac.c" + line="183">the copy of the passed #GHmac. Use g_hmac_unref() when finished using it. the #GHmac to copy + filename="glib/ghmac.c" + line="177">the #GHmac to copy @@ -14221,27 +15374,27 @@ HMAC will be closed as well. c:identifier="g_hmac_get_digest" version="2.30"> Gets the digest from @checksum as a raw binary array and places it + filename="glib/ghmac.c" + line="318">Gets the digest from @checksum as a raw binary array and places it into @buffer. The size of the digest depends on the type of checksum. Once this function has been called, the #GHmac is closed and can no longer be updated with g_checksum_update(). - + a #GHmac + filename="glib/ghmac.c" + line="320">a #GHmac output buffer + filename="glib/ghmac.c" + line="321">output buffer @@ -14251,8 +15404,8 @@ no longer be updated with g_checksum_update(). caller-allocates="0" transfer-ownership="full"> an inout parameter. The caller initializes it to the + filename="glib/ghmac.c" + line="322">an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest @@ -14262,18 +15415,18 @@ no longer be updated with g_checksum_update(). c:identifier="g_hmac_get_string" version="2.30"> Gets the HMAC as a hexadecimal string. + filename="glib/ghmac.c" + line="276">Gets the HMAC as a hexadecimal string. Once this function has been called the #GHmac can no longer be updated with g_hmac_update(). The hexadecimal characters will be lower case. - + the hexadecimal representation of the HMAC. The + filename="glib/ghmac.c" + line="287">the hexadecimal representation of the HMAC. The returned string is owned by the HMAC and should not be modified or freed. @@ -14281,330 +15434,277 @@ The hexadecimal characters will be lower case. a #GHmac + filename="glib/ghmac.c" + line="278">a #GHmac - + Atomically increments the reference count of @hmac by one. + filename="glib/ghmac.c" + line="204">Atomically increments the reference count of @hmac by one. This function is MT-safe and may be called from any thread. - - + + the passed in #GHmac. + filename="glib/ghmac.c" + line="212">the passed in #GHmac. a valid #GHmac + filename="glib/ghmac.c" + line="206">a valid #GHmac Atomically decrements the reference count of @hmac by one. + filename="glib/ghmac.c" + line="226">Atomically decrements the reference count of @hmac by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. Frees the memory allocated for @hmac. - + - + a #GHmac + filename="glib/ghmac.c" + line="228">a #GHmac Feeds @data into an existing #GHmac. + filename="glib/ghmac.c" + line="252">Feeds @data into an existing #GHmac. The HMAC must still be open, that is g_hmac_get_string() or g_hmac_get_digest() must not have been called on @hmac. - + a #GHmac + filename="glib/ghmac.c" + line="254">a #GHmac buffer used to compute the checksum + filename="glib/ghmac.c" + line="255">buffer used to compute the checksum size of the buffer, or -1 if it is a nul-terminated string + filename="glib/ghmac.c" + line="256">size of the buffer, or -1 if it is a nul-terminated string - - Creates a new #GHmac, using the digest algorithm @digest_type. -If the @digest_type is not known, %NULL is returned. -A #GHmac can be used to compute the HMAC of a key and an -arbitrary binary blob, using different hashing algorithms. - -A #GHmac works by feeding a binary blob through g_hmac_update() -until the data is complete; the digest can then be extracted -using g_hmac_get_string(), which will return the checksum as a -hexadecimal string; or g_hmac_get_digest(), which will return a -array of raw bytes. Once either g_hmac_get_string() or -g_hmac_get_digest() have been called on a #GHmac, the HMAC -will be closed and it won't be possible to call g_hmac_update() -on it anymore. - -Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. -Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. - - - the newly created #GHmac, or %NULL. - Use g_hmac_unref() to free the memory allocated by it. - - - - - the desired type of digest - - - - the key for the HMAC - - - - - - the length of the keys - - - - The #GHook struct represents a single hook function in a #GHookList. - + filename="glib/ghook.c" + line="135">The #GHook struct represents a single hook function in a #GHookList. + data which is passed to func when this hook is invoked + filename="glib/ghook.c" + line="137">data which is passed to func when this hook is invoked pointer to the next hook in the list + filename="glib/ghook.c" + line="138">pointer to the next hook in the list pointer to the previous hook in the list + filename="glib/ghook.c" + line="139">pointer to the previous hook in the list the reference count of this hook + filename="glib/ghook.c" + line="140">the reference count of this hook the id of this hook, which is unique within its list + filename="glib/ghook.c" + line="141">the id of this hook, which is unique within its list flags which are set for this hook. See #GHookFlagMask for + filename="glib/ghook.c" + line="142">flags which are set for this hook. See #GHookFlagMask for predefined flags the function to call when this hook is invoked. The possible + filename="glib/ghook.c" + line="144">the function to call when this hook is invoked. The possible signatures for this function are #GHookFunc and #GHookCheckFunc the default @finalize_hook function of a #GHookList calls + filename="glib/ghook.c" + line="146">the default @finalize_hook function of a #GHookList calls this member of the hook that is being finalized Compares the ids of two #GHook elements, returning a negative value + filename="glib/ghook.c" + line="1022">Compares the ids of two #GHook elements, returning a negative value if the second id is greater than the first. - + a value <= 0 if the id of @sibling is >= the id of @new_hook + filename="glib/ghook.c" + line="1030">a value <= 0 if the id of @sibling is >= the id of @new_hook a #GHook + filename="glib/ghook.c" + line="1024">a #GHook a #GHook to compare with @new_hook + filename="glib/ghook.c" + line="1025">a #GHook to compare with @new_hook Allocates space for a #GHook and initializes it. - + filename="glib/ghook.c" + line="247">Allocates space for a #GHook and initializes it. + a new #GHook + filename="glib/ghook.c" + line="253">a new #GHook a #GHookList + filename="glib/ghook.c" + line="249">a #GHookList Destroys a #GHook, given its ID. - + filename="glib/ghook.c" + line="321">Destroys a #GHook, given its ID. + %TRUE if the #GHook was found in the #GHookList and destroyed + filename="glib/ghook.c" + line="328">%TRUE if the #GHook was found in the #GHookList and destroyed a #GHookList + filename="glib/ghook.c" + line="323">a #GHookList a hook ID + filename="glib/ghook.c" + line="324">a hook ID Removes one #GHook from a #GHookList, marking it + filename="glib/ghook.c" + line="298">Removes one #GHook from a #GHookList, marking it inactive and calling g_hook_unref() on it. - + a #GHookList + filename="glib/ghook.c" + line="300">a #GHookList the #GHook to remove + filename="glib/ghook.c" + line="301">the #GHook to remove Finds a #GHook in a #GHookList using the given function to + filename="glib/ghook.c" + line="793">Finds a #GHook in a #GHookList using the given function to test for a match. - + the found #GHook or %NULL if no matching #GHook is found + filename="glib/ghook.c" + line="805">the found #GHook or %NULL if no matching #GHook is found a #GHookList + filename="glib/ghook.c" + line="795">a #GHookList %TRUE if #GHook elements which have been destroyed + filename="glib/ghook.c" + line="796">%TRUE if #GHook elements which have been destroyed should be skipped - + the function to call for each #GHook, which should return + filename="glib/ghook.c" + line="798">the function to call for each #GHook, which should return %TRUE when the #GHook has been found @@ -14613,8 +15713,8 @@ test for a match. nullable="1" allow-none="1"> the data to pass to @func + filename="glib/ghook.c" + line="800">the data to pass to @func @@ -14623,27 +15723,27 @@ test for a match. c:identifier="g_hook_find_data" introspectable="0"> Finds a #GHook in a #GHookList with the given data. - + filename="glib/ghook.c" + line="847">Finds a #GHook in a #GHookList with the given data. + the #GHook with the given @data or %NULL if no matching + filename="glib/ghook.c" + line="856">the #GHook with the given @data or %NULL if no matching #GHook is found a #GHookList + filename="glib/ghook.c" + line="849">a #GHookList %TRUE if #GHook elements which have been destroyed + filename="glib/ghook.c" + line="850">%TRUE if #GHook elements which have been destroyed should be skipped @@ -14652,8 +15752,8 @@ test for a match. nullable="1" allow-none="1"> the data to find + filename="glib/ghook.c" + line="852">the data to find @@ -14662,27 +15762,27 @@ test for a match. c:identifier="g_hook_find_func" introspectable="0"> Finds a #GHook in a #GHookList with the given function. - + filename="glib/ghook.c" + line="883">Finds a #GHook in a #GHookList with the given function. + the #GHook with the given @func or %NULL if no matching + filename="glib/ghook.c" + line="892">the #GHook with the given @func or %NULL if no matching #GHook is found a #GHookList + filename="glib/ghook.c" + line="885">a #GHookList %TRUE if #GHook elements which have been destroyed + filename="glib/ghook.c" + line="886">%TRUE if #GHook elements which have been destroyed should be skipped @@ -14691,8 +15791,8 @@ test for a match. nullable="1" allow-none="1"> the function to find + filename="glib/ghook.c" + line="888">the function to find @@ -14701,34 +15801,34 @@ test for a match. c:identifier="g_hook_find_func_data" introspectable="0"> Finds a #GHook in a #GHookList with the given function and data. - + filename="glib/ghook.c" + line="920">Finds a #GHook in a #GHookList with the given function and data. + the #GHook with the given @func and @data or %NULL if + filename="glib/ghook.c" + line="930">the #GHook with the given @func and @data or %NULL if no matching #GHook is found a #GHookList + filename="glib/ghook.c" + line="922">a #GHookList %TRUE if #GHook elements which have been destroyed + filename="glib/ghook.c" + line="923">%TRUE if #GHook elements which have been destroyed should be skipped the function to find + filename="glib/ghook.c" + line="925">the function to find nullable="1" allow-none="1"> the data to find + filename="glib/ghook.c" + line="926">the data to find @@ -14746,29 +15846,29 @@ test for a match. c:identifier="g_hook_first_valid" introspectable="0"> Returns the first #GHook in a #GHookList which has not been destroyed. + filename="glib/ghook.c" + line="672">Returns the first #GHook in a #GHookList which has not been destroyed. The reference count for the #GHook is incremented, so you must call g_hook_unref() to restore it when no longer needed. (Or call g_hook_next_valid() if you are stepping through the #GHookList.) - + the first valid #GHook, or %NULL if none are valid + filename="glib/ghook.c" + line="684">the first valid #GHook, or %NULL if none are valid a #GHookList + filename="glib/ghook.c" + line="674">a #GHookList %TRUE if hooks which are currently running + filename="glib/ghook.c" + line="675">%TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped @@ -14777,67 +15877,67 @@ g_hook_next_valid() if you are stepping through the #GHookList.) Calls the #GHookList @finalize_hook function if it exists, + filename="glib/ghook.c" + line="275">Calls the #GHookList @finalize_hook function if it exists, and frees the memory allocated for the #GHook. - + a #GHookList + filename="glib/ghook.c" + line="277">a #GHookList the #GHook to free + filename="glib/ghook.c" + line="278">the #GHook to free Returns the #GHook with the given id, or %NULL if it is not found. - + filename="glib/ghook.c" + line="754">Returns the #GHook with the given id, or %NULL if it is not found. + the #GHook with the given id, or %NULL if it is not found + filename="glib/ghook.c" + line="761">the #GHook with the given id, or %NULL if it is not found a #GHookList + filename="glib/ghook.c" + line="756">a #GHookList a hook id + filename="glib/ghook.c" + line="757">a hook id Inserts a #GHook into a #GHookList, before a given #GHook. - + filename="glib/ghook.c" + line="445">Inserts a #GHook into a #GHookList, before a given #GHook. + a #GHookList + filename="glib/ghook.c" + line="447">a #GHookList nullable="1" allow-none="1"> the #GHook to insert the new #GHook before + filename="glib/ghook.c" + line="448">the #GHook to insert the new #GHook before the #GHook to insert + filename="glib/ghook.c" + line="449">the #GHook to insert - + Inserts a #GHook into a #GHookList, sorted by the given function. - + filename="glib/ghook.c" + line="971">Inserts a #GHook into a #GHookList, sorted by the given function. + a #GHookList + filename="glib/ghook.c" + line="973">a #GHookList the #GHook to insert + filename="glib/ghook.c" + line="974">the #GHook to insert - + the comparison function used to sort the #GHook elements + filename="glib/ghook.c" + line="975">the comparison function used to sort the #GHook elements @@ -14892,35 +15990,35 @@ and frees the memory allocated for the #GHook. c:identifier="g_hook_next_valid" introspectable="0"> Returns the next #GHook in a #GHookList which has not been destroyed. + filename="glib/ghook.c" + line="710">Returns the next #GHook in a #GHookList which has not been destroyed. The reference count for the #GHook is incremented, so you must call g_hook_unref() to restore it when no longer needed. (Or continue to call g_hook_next_valid() until %NULL is returned.) - + the next valid #GHook, or %NULL if none are valid + filename="glib/ghook.c" + line="723">the next valid #GHook, or %NULL if none are valid a #GHookList + filename="glib/ghook.c" + line="712">a #GHookList the current #GHook + filename="glib/ghook.c" + line="713">the current #GHook %TRUE if hooks which are currently running + filename="glib/ghook.c" + line="714">%TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped @@ -14929,74 +16027,74 @@ g_hook_next_valid() until %NULL is returned.) Prepends a #GHook on the start of a #GHookList. - + filename="glib/ghook.c" + line="429">Prepends a #GHook on the start of a #GHookList. + a #GHookList + filename="glib/ghook.c" + line="431">a #GHookList the #GHook to add to the start of @hook_list + filename="glib/ghook.c" + line="432">the #GHook to add to the start of @hook_list Increments the reference count for a #GHook. - + filename="glib/ghook.c" + line="399">Increments the reference count for a #GHook. + the @hook that was passed in (since 2.6) + filename="glib/ghook.c" + line="406">the @hook that was passed in (since 2.6) a #GHookList + filename="glib/ghook.c" + line="401">a #GHookList the #GHook to increment the reference count of + filename="glib/ghook.c" + line="402">the #GHook to increment the reference count of Decrements the reference count of a #GHook. + filename="glib/ghook.c" + line="349">Decrements the reference count of a #GHook. If the reference count falls to 0, the #GHook is removed from the #GHookList and g_hook_free() is called to free it. - + a #GHookList + filename="glib/ghook.c" + line="351">a #GHookList the #GHook to unref + filename="glib/ghook.c" + line="352">the #GHook to unref @@ -15004,14 +16102,14 @@ from the #GHookList and g_hook_free() is called to free it. Defines the type of a hook function that can be invoked + filename="glib/ghook.c" + line="160">Defines the type of a hook function that can be invoked by g_hook_list_invoke_check(). - + %FALSE if the #GHook should be destroyed + filename="glib/ghook.c" + line="167">%FALSE if the #GHook should be destroyed @@ -15020,28 +16118,28 @@ by g_hook_list_invoke_check(). nullable="1" allow-none="1"> the data field of the #GHook is passed to the hook function here + filename="glib/ghook.c" + line="162">the data field of the #GHook is passed to the hook function here Defines the type of function used by g_hook_list_marshal_check(). - + filename="glib/ghook.c" + line="574">Defines the type of function used by g_hook_list_marshal_check(). + %FALSE if @hook should be destroyed + filename="glib/ghook.c" + line="581">%FALSE if @hook should be destroyed a #GHook + filename="glib/ghook.c" + line="576">a #GHook nullable="1" allow-none="1"> user data + filename="glib/ghook.c" + line="577">user data Defines the type of function used to compare #GHook elements in + filename="glib/ghook.c" + line="960">Defines the type of function used to compare #GHook elements in g_hook_insert_sorted(). - + a value <= 0 if @new_hook should be before @sibling + filename="glib/ghook.c" + line="968">a value <= 0 if @new_hook should be before @sibling the #GHook being inserted + filename="glib/ghook.c" + line="962">the #GHook being inserted the #GHook to compare with @new_hook + filename="glib/ghook.c" + line="963">the #GHook to compare with @new_hook Defines the type of function to be called when a hook in a + filename="glib/ghook.c" + line="55">Defines the type of function to be called when a hook in a list of hooks gets finalized. - + a #GHookList + filename="glib/ghook.c" + line="57">a #GHookList the hook in @hook_list that gets finalized + filename="glib/ghook.c" + line="58">the hook in @hook_list that gets finalized Defines the type of the function passed to g_hook_find(). - + filename="glib/ghook.c" + line="783">Defines the type of the function passed to g_hook_find(). + %TRUE if the required #GHook has been found + filename="glib/ghook.c" + line="790">%TRUE if the required #GHook has been found a #GHook + filename="glib/ghook.c" + line="785">a #GHook nullable="1" allow-none="1"> user data passed to g_hook_find_func() + filename="glib/ghook.c" + line="786">user data passed to g_hook_find_func() Flags used internally in the #GHook implementation. - + filename="glib/ghook.c" + line="64">Flags used internally in the #GHook implementation. + set if the hook has not been destroyed + filename="glib/ghook.c" + line="66">set if the hook has not been destroyed set if the hook is currently being run + filename="glib/ghook.c" + line="67">set if the hook is currently being run A mask covering all bits reserved for + filename="glib/ghook.c" + line="68">A mask covering all bits reserved for hook flags; see %G_HOOK_FLAG_USER_SHIFT Defines the type of a hook function that can be invoked + filename="glib/ghook.c" + line="152">Defines the type of a hook function that can be invoked by g_hook_list_invoke(). - + @@ -15172,95 +16270,99 @@ by g_hook_list_invoke(). nullable="1" allow-none="1"> the data field of the #GHook is passed to the hook function here + filename="glib/ghook.c" + line="154">the data field of the #GHook is passed to the hook function here The #GHookList struct represents a list of hook functions. - + filename="glib/ghook.c" + line="41">The #GHookList struct represents a list of hook functions. + the next free #GHook id + filename="glib/ghook.c" + line="43">the next free #GHook id the size of the #GHookList elements, in bytes + filename="glib/ghook.c" + line="44">the size of the #GHookList elements, in bytes 1 if the #GHookList has been initialized + filename="glib/ghook.c" + line="45">1 if the #GHookList has been initialized the first #GHook element in the list + filename="glib/ghook.c" + line="46">the first #GHook element in the list - unused + unused the function to call to finalize a #GHook element. + filename="glib/ghook.c" + line="48">the function to call to finalize a #GHook element. The default behaviour is to call the hooks @destroy function - unused + unused Removes all the #GHook elements from a #GHookList. - + filename="glib/ghook.c" + line="210">Removes all the #GHook elements from a #GHookList. + a #GHookList + filename="glib/ghook.c" + line="212">a #GHookList Initializes a #GHookList. + filename="glib/ghook.c" + line="184">Initializes a #GHookList. This must be called before the #GHookList is used. - + a #GHookList + filename="glib/ghook.c" + line="186">a #GHookList the size of each element in the #GHookList, + filename="glib/ghook.c" + line="187">the size of each element in the #GHookList, typically `sizeof (GHook)`. @@ -15268,23 +16370,23 @@ This must be called before the #GHookList is used. Calls all of the #GHook functions in a #GHookList. - + filename="glib/ghook.c" + line="498">Calls all of the #GHook functions in a #GHookList. + a #GHookList + filename="glib/ghook.c" + line="500">a #GHookList %TRUE if functions which are already running + filename="glib/ghook.c" + line="501">%TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped @@ -15293,59 +16395,60 @@ This must be called before the #GHookList is used. Calls all of the #GHook functions in a #GHookList. + filename="glib/ghook.c" + line="534">Calls all of the #GHook functions in a #GHookList. Any function which returns %FALSE is removed from the #GHookList. - + a #GHookList + filename="glib/ghook.c" + line="536">a #GHookList %TRUE if functions which are already running + filename="glib/ghook.c" + line="537">%TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped - + Calls a function on each valid #GHook. - + filename="glib/ghook.c" + line="634">Calls a function on each valid #GHook. + a #GHookList + filename="glib/ghook.c" + line="636">a #GHookList %TRUE if hooks which are currently running + filename="glib/ghook.c" + line="637">%TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped - + the function to call for each #GHook + filename="glib/ghook.c" + line="640">the function to call for each #GHook nullable="1" allow-none="1"> data to pass to @marshaller + filename="glib/ghook.c" + line="641">data to pass to @marshaller - + Calls a function on each valid #GHook and destroys it if the + filename="glib/ghook.c" + line="584">Calls a function on each valid #GHook and destroys it if the function returns %FALSE. - + a #GHookList + filename="glib/ghook.c" + line="586">a #GHookList %TRUE if hooks which are currently running + filename="glib/ghook.c" + line="587">%TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped - + the function to call for each #GHook + filename="glib/ghook.c" + line="590">the function to call for each #GHook nullable="1" allow-none="1"> data to pass to @marshaller + filename="glib/ghook.c" + line="591">data to pass to @marshaller @@ -15405,17 +16509,17 @@ function returns %FALSE. Defines the type of function used by g_hook_list_marshal(). - + filename="glib/ghook.c" + line="626">Defines the type of function used by g_hook_list_marshal(). + a #GHook + filename="glib/ghook.c" + line="628">a #GHook nullable="1" allow-none="1"> user data + filename="glib/ghook.c" + line="629">user data @@ -15435,17 +16539,17 @@ function returns %FALSE. pointer="1" introspectable="0"> The GIConv struct wraps an iconv() conversion descriptor. It contains private data and should only be accessed using the following functions. - + Same as the standard UNIX routine iconv(), but + filename="glib/gconvert.c" + line="153">Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. @@ -15457,25 +16561,28 @@ input character set, but which have no representation in the output character set, is implementation defined. This function may return success (with a positive number of non-reversible conversions as replacement characters were used), or it may return -1 and set an error such as %EILSEQ, in such a -situation. - +situation. + +See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an +error occurs. + count of non-reversible conversions, or -1 on error + filename="glib/gconvert.c" + line="178">count of non-reversible conversions, or -1 on error conversion descriptor from g_iconv_open() + filename="glib/gconvert.c" + line="155">conversion descriptor from g_iconv_open() bytes to convert + filename="glib/gconvert.c" + line="156">bytes to convert caller-allocates="0" transfer-ownership="full"> inout parameter, bytes remaining to convert in @inbuf + filename="glib/gconvert.c" + line="157">inout parameter, bytes remaining to convert in @inbuf converted output bytes + filename="glib/gconvert.c" + line="158">converted output bytes caller-allocates="0" transfer-ownership="full"> inout parameter, bytes available to fill in @outbuf + filename="glib/gconvert.c" + line="159">inout parameter, bytes available to fill in @outbuf Same as the standard UNIX routine iconv_close(), but + filename="glib/gconvert.c" + line="192">Same as the standard UNIX routine iconv_close(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. Should be called to clean up the conversion descriptor from g_iconv_open() when @@ -15515,50 +16622,50 @@ you are done converting things. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. - + -1 on error, 0 on success + filename="glib/gconvert.c" + line="205">-1 on error, 0 on success a conversion descriptor from g_iconv_open() + filename="glib/gconvert.c" + line="194">a conversion descriptor from g_iconv_open() Same as the standard UNIX routine iconv_open(), but + filename="glib/gconvert.c" + line="104">Same as the standard UNIX routine iconv_open(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. - + a "conversion descriptor", or (GIConv)-1 if + filename="glib/gconvert.c" + line="116">a "conversion descriptor", or (GIConv)-1 if opening the converter failed. destination codeset + filename="glib/gconvert.c" + line="106">destination codeset source codeset + filename="glib/gconvert.c" + line="107">source codeset @@ -15568,18 +16675,18 @@ more convenient than the raw iconv wrappers. value="1023" c:type="G_IEEE754_DOUBLE_BIAS"> The bias by which exponents in double-precision floats are offset. - + filename="glib/docs.c" + line="779">The bias by which exponents in double-precision floats are offset. + The bias by which exponents in single-precision floats are offset. - + filename="glib/docs.c" + line="773">The bias by which exponents in single-precision floats are offset. + glib:get-type="g_io_channel_get_type" c:symbol-prefix="io_channel"> A data structure representing an IO Channel. The fields should be -considered private and should only be accessed with the following -functions. - + filename="glib/giochannel.c" + line="46">The `GIOChannel` data type aims to provide a portable method for +using file descriptors, pipes, and sockets, and integrating them +into the main event loop (see [struct@GLib.MainContext]). Currently, +full support is available on UNIX platforms; support for Windows +is only partially complete. + +To create a new `GIOChannel` on UNIX systems use +[ctor@GLib.IOChannel.unix_new]. This works for plain file descriptors, +pipes and sockets. Alternatively, a channel can be created for a +file in a system independent manner using [ctor@GLib.IOChannel.new_file]. + +Once a `GIOChannel` has been created, it can be used in a generic +manner with the functions [method@GLib.IOChannel.read_chars], +[method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position], +and [method@GLib.IOChannel.shutdown]. + +To add a `GIOChannel` to the main event loop, use [func@GLib.io_add_watch] or +[func@GLib.io_add_watch_full]. Here you specify which events you are +interested in on the `GIOChannel`, and provide a function to be called +whenever these events occur. + +`GIOChannel` instances are created with an initial reference count of 1. +[method@GLib.IOChannel.ref] and [method@GLib.IOChannel.unref] can be used to +increment or decrement the reference count respectively. When the +reference count falls to 0, the `GIOChannel` is freed. (Though it +isn’t closed automatically, unless it was created using +[ctor@GLib.IOChannel.new_file].) Using [func@GLib.io_add_watch] or +[func@GLib.io_add_watch_full] increments a channel’s reference count. + +The new functions [method@GLib.IOChannel.read_chars], +[method@GLib.IOChannel.read_line], [method@GLib.IOChannel.read_line_string], +[method@GLib.IOChannel.read_to_end], [method@GLib.IOChannel.write_chars], +[method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.flush] +should not be mixed with the deprecated functions +[method@GLib.IOChannel.read], [method@GLib.IOChannel.write], and +[method@GLib.IOChannel.seek] on the same channel. + @@ -15659,30 +16799,30 @@ functions. c:identifier="g_io_channel_new_file" throws="1"> Open a file @filename as a #GIOChannel using mode @mode. This + filename="glib/giochannel.c" + line="413">Open a file @filename as a #GIOChannel using mode @mode. This channel will be closed when the last reference to it is dropped, so there is no need to call g_io_channel_close() (though doing so will not cause problems, as long as no attempt is made to access the channel after it is closed). - + A #GIOChannel on success, %NULL on failure. + filename="glib/giochannel.c" + line="426">A #GIOChannel on success, %NULL on failure. A string containing the name of a file + filename="glib/giochannel.c" + line="415">A string containing the name of a file One of "r", "w", "a", "r+", "w+", "a+". These have + filename="glib/giochannel.c" + line="416">One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen() @@ -15690,8 +16830,8 @@ access the channel after it is closed). Creates a new #GIOChannel given a file descriptor. On UNIX systems + filename="glib/giounix.c" + line="587">Creates a new #GIOChannel given a file descriptor. On UNIX systems this works for plain files, pipes, and sockets. The returned #GIOChannel has a reference count of 1. @@ -15713,18 +16853,18 @@ sockets overlap. There is no way for GLib to know which one you mean in case the argument you pass to this function happens to be both a valid file descriptor and socket. If that happens a warning is issued, and GLib assumes that it is the file descriptor you mean. - + a new #GIOChannel. + filename="glib/giounix.c" + line="614">a new #GIOChannel. a file descriptor. + filename="glib/giounix.c" + line="589">a file descriptor. @@ -15734,33 +16874,33 @@ issued, and GLib assumes that it is the file descriptor you mean. deprecated="1" deprecated-version="2.2"> Close an IO channel. Any pending data to be written will be + filename="glib/giochannel.c" + line="429">Close an IO channel. Any pending data to be written will be flushed, ignoring errors. The channel will not be freed until the last reference is dropped using g_io_channel_unref(). Use g_io_channel_shutdown() instead. - + A #GIOChannel + filename="glib/giochannel.c" + line="431">A #GIOChannel Flushes the write buffer for the GIOChannel. - + filename="glib/giochannel.c" + line="1173">Flushes the write buffer for the GIOChannel. + the status of the operation: One of + filename="glib/giochannel.c" + line="1180">the status of the operation: One of %G_IO_STATUS_NORMAL, %G_IO_STATUS_AGAIN, or %G_IO_STATUS_ERROR. @@ -15768,8 +16908,8 @@ last reference is dropped using g_io_channel_unref(). a #GIOChannel + filename="glib/giochannel.c" + line="1175">a #GIOChannel @@ -15777,22 +16917,22 @@ last reference is dropped using g_io_channel_unref(). This function returns a #GIOCondition depending on whether there + filename="glib/giochannel.c" + line="702">This function returns a #GIOCondition depending on whether there is data to be read/space to write data in the internal buffers in the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. - + A #GIOCondition + filename="glib/giochannel.c" + line="710">A #GIOCondition A #GIOChannel + filename="glib/giochannel.c" + line="704">A #GIOChannel @@ -15800,40 +16940,40 @@ the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. Gets the buffer size. - + filename="glib/giochannel.c" + line="845">Gets the buffer size. + the size of the buffer. + filename="glib/giochannel.c" + line="851">the size of the buffer. a #GIOChannel + filename="glib/giochannel.c" + line="847">a #GIOChannel Returns whether @channel is buffered. - + filename="glib/giochannel.c" + line="1259">Returns whether @channel is buffered. + %TRUE if the @channel is buffered. + filename="glib/giochannel.c" + line="1265">%TRUE if the @channel is buffered. a #GIOChannel + filename="glib/giochannel.c" + line="1261">a #GIOChannel @@ -15841,54 +16981,54 @@ the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. Returns whether the file/socket/whatever associated with @channel + filename="glib/giochannel.c" + line="1043">Returns whether the file/socket/whatever associated with @channel will be closed when @channel receives its final unref and is destroyed. The default value of this is %TRUE for channels created by g_io_channel_new_file (), and %FALSE for all other channels. - + %TRUE if the channel will be closed, %FALSE otherwise. + filename="glib/giochannel.c" + line="1052">%TRUE if the channel will be closed, %FALSE otherwise. a #GIOChannel. + filename="glib/giochannel.c" + line="1045">a #GIOChannel. Gets the encoding for the input/output of the channel. + filename="glib/giochannel.c" + line="1446">Gets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The encoding %NULL makes the channel safe for binary data. - + A string containing the encoding, this string is + filename="glib/giochannel.c" + line="1454">A string containing the encoding, this string is owned by GLib and must not be freed. a #GIOChannel + filename="glib/giochannel.c" + line="1448">a #GIOChannel Gets the current flags for a #GIOChannel, including read-only + filename="glib/giochannel.c" + line="984">Gets the current flags for a #GIOChannel, including read-only flags such as %G_IO_FLAG_IS_READABLE. The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE @@ -15897,41 +17037,42 @@ If they should change at some later point (e.g. partial shutdown of a socket with the UNIX shutdown() function), the user should immediately call g_io_channel_get_flags() to update the internal values of these flags. - + the flags which are set on the channel + filename="glib/giochannel.c" + line="998">the flags which are set on the channel a #GIOChannel + filename="glib/giochannel.c" + line="986">a #GIOChannel This returns the string that #GIOChannel uses to determine + filename="glib/giochannel.c" + line="907">This returns the string that #GIOChannel uses to determine where in the file a line break occurs. A value of %NULL -indicates autodetection. - +indicates autodetection. Since 2.84, the return value is always +nul-terminated. + The line termination string. This value + filename="glib/giochannel.c" + line="917">The line termination string. This value is owned by GLib and must not be freed. a #GIOChannel + filename="glib/giochannel.c" + line="909">a #GIOChannel optional="1" allow-none="1"> a location to return the length of the line terminator + filename="glib/giochannel.c" + line="910">a location to return the length of the line terminator Initializes a #GIOChannel struct. + filename="glib/giochannel.c" + line="166">Initializes a #GIOChannel struct. This is called by each of the above functions when creating a #GIOChannel, and so is not often needed by the application programmer (unless you are creating a new type of #GIOChannel). - + a #GIOChannel + filename="glib/giochannel.c" + line="168">a #GIOChannel @@ -15973,40 +17114,40 @@ programmer (unless you are creating a new type of #GIOChannel). deprecated="1" deprecated-version="2.2"> Reads data from a #GIOChannel. + filename="glib/giochannel.c" + line="278">Reads data from a #GIOChannel. Use g_io_channel_read_chars() instead. - + %G_IO_ERROR_NONE if the operation was successful. + filename="glib/giochannel.c" + line="288">%G_IO_ERROR_NONE if the operation was successful. a #GIOChannel + filename="glib/giochannel.c" + line="280">a #GIOChannel a buffer to read the data into (which should be at least + filename="glib/giochannel.c" + line="281">a buffer to read the data into (which should be at least count bytes long) the number of bytes to read from the #GIOChannel + filename="glib/giochannel.c" + line="283">the number of bytes to read from the #GIOChannel returns the number of bytes actually read + filename="glib/giochannel.c" + line="284">returns the number of bytes actually read @@ -16015,20 +17156,20 @@ programmer (unless you are creating a new type of #GIOChannel). c:identifier="g_io_channel_read_chars" throws="1"> Replacement for g_io_channel_read() with the new API. - + filename="glib/giochannel.c" + line="1990">Replacement for g_io_channel_read() with the new API. + the status of the operation. + filename="glib/giochannel.c" + line="2007">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="1992">a #GIOChannel caller-allocates="1" transfer-ownership="none"> + filename="glib/giochannel.c" + line="1993"> a buffer to read data into @@ -16045,8 +17186,8 @@ programmer (unless you are creating a new type of #GIOChannel). the size of the buffer. Note that the buffer may not be + filename="glib/giochannel.c" + line="1995">the size of the buffer. Note that the buffer may not be completely filled even if there is data in the buffer if the remaining data is not a complete character. @@ -16058,8 +17199,8 @@ programmer (unless you are creating a new type of #GIOChannel). optional="1" allow-none="1"> The number of bytes read. This may be + filename="glib/giochannel.c" + line="1998">The number of bytes read. This may be zero even on success if count < 6 and the channel's encoding is non-%NULL. This indicates that the next UTF-8 character is too wide for the buffer. @@ -16071,23 +17212,23 @@ programmer (unless you are creating a new type of #GIOChannel). c:identifier="g_io_channel_read_line" throws="1"> Reads a line, including the terminating character(s), + filename="glib/giochannel.c" + line="1637">Reads a line, including the terminating character(s), from a #GIOChannel into a newly-allocated string. @str_return will contain allocated memory if the return is %G_IO_STATUS_NORMAL. - + the status of the operation. + filename="glib/giochannel.c" + line="1654">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="1639">a #GIOChannel caller-allocates="0" transfer-ownership="full"> The line read from the #GIOChannel, including the + filename="glib/giochannel.c" + line="1640">The line read from the #GIOChannel, including the line terminator. This data should be freed with g_free() when no longer needed. This is a nul-terminated string. If a @length of zero is returned, this will be %NULL instead. @@ -16109,8 +17250,8 @@ is %G_IO_STATUS_NORMAL. optional="1" allow-none="1"> location to store length of the read data, or %NULL + filename="glib/giochannel.c" + line="1644">location to store length of the read data, or %NULL optional="1" allow-none="1"> location to store position of line terminator, or %NULL + filename="glib/giochannel.c" + line="1645">location to store position of line terminator, or %NULL @@ -16130,26 +17271,26 @@ is %G_IO_STATUS_NORMAL. c:identifier="g_io_channel_read_line_string" throws="1"> Reads a line from a #GIOChannel, using a #GString as a buffer. - + filename="glib/giochannel.c" + line="1697">Reads a line from a #GIOChannel, using a #GString as a buffer. + the status of the operation. + filename="glib/giochannel.c" + line="1709">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="1699">a #GIOChannel a #GString into which the line will be written. + filename="glib/giochannel.c" + line="1700">a #GString into which the line will be written. If @buffer already contains data, the old data will be overwritten. @@ -16159,8 +17300,8 @@ is %G_IO_STATUS_NORMAL. nullable="1" allow-none="1"> location to store position of line terminator, or %NULL + filename="glib/giochannel.c" + line="1703">location to store position of line terminator, or %NULL @@ -16169,21 +17310,21 @@ is %G_IO_STATUS_NORMAL. c:identifier="g_io_channel_read_to_end" throws="1"> Reads all the remaining data from the file. - + filename="glib/giochannel.c" + line="1909">Reads all the remaining data from the file. + %G_IO_STATUS_NORMAL on success. + filename="glib/giochannel.c" + line="1923">%G_IO_STATUS_NORMAL on success. This function never returns %G_IO_STATUS_EOF. a #GIOChannel + filename="glib/giochannel.c" + line="1911">a #GIOChannel caller-allocates="0" transfer-ownership="full"> Location to + filename="glib/giochannel.c" + line="1912">Location to store a pointer to a string holding the remaining data in the #GIOChannel. This data should be freed with g_free() when no longer needed. This data is terminated by an extra nul @@ -16206,8 +17347,8 @@ is %G_IO_STATUS_NORMAL. caller-allocates="0" transfer-ownership="full"> location to store length of the data + filename="glib/giochannel.c" + line="1917">location to store length of the data @@ -16216,21 +17357,21 @@ is %G_IO_STATUS_NORMAL. c:identifier="g_io_channel_read_unichar" throws="1"> Reads a Unicode character from @channel. + filename="glib/giochannel.c" + line="2110">Reads a Unicode character from @channel. This function cannot be called on a channel with %NULL encoding. - + a #GIOStatus + filename="glib/giochannel.c" + line="2120">a #GIOStatus a #GIOChannel + filename="glib/giochannel.c" + line="2112">a #GIOChannel caller-allocates="0" transfer-ownership="full"> a location to return a character + filename="glib/giochannel.c" + line="2113">a location to return a character Increments the reference count of a #GIOChannel. - + filename="glib/giochannel.c" + line="195">Increments the reference count of a #GIOChannel. + the @channel that was passed in (since 2.6) + filename="glib/giochannel.c" + line="201">the @channel that was passed in (since 2.6) a #GIOChannel + filename="glib/giochannel.c" + line="197">a #GIOChannel @@ -16269,35 +17410,35 @@ This function cannot be called on a channel with %NULL encoding. deprecated="1" deprecated-version="2.2"> Sets the current position in the #GIOChannel, similar to the standard + filename="glib/giochannel.c" + line="360">Sets the current position in the #GIOChannel, similar to the standard library function fseek(). Use g_io_channel_seek_position() instead. - + %G_IO_ERROR_NONE if the operation was successful. + filename="glib/giochannel.c" + line="372">%G_IO_ERROR_NONE if the operation was successful. a #GIOChannel + filename="glib/giochannel.c" + line="362">a #GIOChannel an offset, in bytes, which is added to the position specified + filename="glib/giochannel.c" + line="363">an offset, in bytes, which is added to the position specified by @type the position in the file, which can be %G_SEEK_CUR (the current + filename="glib/giochannel.c" + line="365">the position in the file, which can be %G_SEEK_CUR (the current position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the file) @@ -16308,32 +17449,32 @@ library function fseek(). c:identifier="g_io_channel_seek_position" throws="1"> Replacement for g_io_channel_seek() with the new API. - + filename="glib/giochannel.c" + line="1062">Replacement for g_io_channel_seek() with the new API. + the status of the operation. + filename="glib/giochannel.c" + line="1074">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="1064">a #GIOChannel The offset in bytes from the position specified by @type + filename="glib/giochannel.c" + line="1065">The offset in bytes from the position specified by @type a #GSeekType. The type %G_SEEK_CUR is only allowed in those + filename="glib/giochannel.c" + line="1066">a #GSeekType. The type %G_SEEK_CUR is only allowed in those cases where a call to g_io_channel_set_encoding () is allowed. See the documentation for g_io_channel_set_encoding () for details. @@ -16344,31 +17485,31 @@ library function fseek(). Sets the buffer size. - + filename="glib/giochannel.c" + line="823">Sets the buffer size. + a #GIOChannel + filename="glib/giochannel.c" + line="825">a #GIOChannel the size of the buffer, or 0 to let GLib pick a good size + filename="glib/giochannel.c" + line="826">the size of the buffer, or 0 to let GLib pick a good size The buffering state can only be set if the channel's encoding + filename="glib/giochannel.c" + line="1215">The buffering state can only be set if the channel's encoding is %NULL. For any other encoding, the channel must be buffered. A buffered channel can only be set unbuffered if the channel's @@ -16387,21 +17528,21 @@ calls from the new and old APIs, if this is necessary for maintaining old code. The default state of the channel is buffered. - + a #GIOChannel + filename="glib/giochannel.c" + line="1217">a #GIOChannel whether to set the channel buffered or unbuffered + filename="glib/giochannel.c" + line="1218">whether to set the channel buffered or unbuffered @@ -16409,28 +17550,28 @@ The default state of the channel is buffered. Whether to close the channel on the final unref of the #GIOChannel + filename="glib/giochannel.c" + line="1021">Whether to close the channel on the final unref of the #GIOChannel data structure. The default value of this is %TRUE for channels created by g_io_channel_new_file (), and %FALSE for all other channels. Setting this flag to %TRUE for a channel you have already closed can cause problems when the final reference to the #GIOChannel is dropped. - + a #GIOChannel + filename="glib/giochannel.c" + line="1023">a #GIOChannel Whether to close the channel on the final unref of + filename="glib/giochannel.c" + line="1024">Whether to close the channel on the final unref of the GIOChannel data structure. @@ -16440,8 +17581,8 @@ can cause problems when the final reference to the #GIOChannel is dropped. c:identifier="g_io_channel_set_encoding" throws="1"> Sets the encoding for the input/output of the channel. + filename="glib/giochannel.c" + line="1275">Sets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The default encoding for the external file is UTF-8. @@ -16475,18 +17616,18 @@ Channels which do not meet one of the above conditions cannot call g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if they are "seekable", cannot call g_io_channel_write_chars() after calling one of the API "read" functions. - + %G_IO_STATUS_NORMAL if the encoding was successfully set + filename="glib/giochannel.c" + line="1316">%G_IO_STATUS_NORMAL if the encoding was successfully set a #GIOChannel + filename="glib/giochannel.c" + line="1277">a #GIOChannel nullable="1" allow-none="1"> the encoding type + filename="glib/giochannel.c" + line="1278">the encoding type @@ -16504,44 +17645,44 @@ calling one of the API "read" functions. c:identifier="g_io_channel_set_flags" throws="1"> Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). - + filename="glib/giochannel.c" + line="932">Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). + the status of the operation. + filename="glib/giochannel.c" + line="940">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="934">a #GIOChannel the flags to set on the IO channel + filename="glib/giochannel.c" + line="935">the flags to set on the IO channel This sets the string that #GIOChannel uses to determine + filename="glib/giochannel.c" + line="861">This sets the string that #GIOChannel uses to determine where in the file a line break occurs. - + a #GIOChannel + filename="glib/giochannel.c" + line="863">a #GIOChannel nullable="1" allow-none="1"> The line termination string. Use %NULL for + filename="glib/giochannel.c" + line="864">The line termination string. Use %NULL for autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph separator. Autodetection should not be used for anything other than file-based channels. @@ -16558,8 +17699,8 @@ where in the file a line break occurs. The length of the termination string. If -1 is passed, the + filename="glib/giochannel.c" + line="868">The length of the termination string. If -1 is passed, the string is assumed to be nul-terminated. This option allows termination strings with embedded nuls. @@ -16568,68 +17709,68 @@ where in the file a line break occurs. Close an IO channel. Any pending data to be written will be + filename="glib/giochannel.c" + line="462">Close an IO channel. Any pending data to be written will be flushed if @flush is %TRUE. The channel will not be freed until the last reference is dropped using g_io_channel_unref(). - + the status of the operation. + filename="glib/giochannel.c" + line="472">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="464">a #GIOChannel if %TRUE, flush pending + filename="glib/giochannel.c" + line="465">if %TRUE, flush pending Returns the file descriptor of the #GIOChannel. + filename="glib/giounix.c" + line="645">Returns the file descriptor of the #GIOChannel. On Windows this function returns the file descriptor or socket of the #GIOChannel. - + the file descriptor of the #GIOChannel. + filename="glib/giounix.c" + line="654">the file descriptor of the #GIOChannel. a #GIOChannel, created with g_io_channel_unix_new(). + filename="glib/giounix.c" + line="647">a #GIOChannel, created with g_io_channel_unix_new(). Decrements the reference count of a #GIOChannel. - + filename="glib/giochannel.c" + line="213">Decrements the reference count of a #GIOChannel. + a #GIOChannel + filename="glib/giochannel.c" + line="215">a #GIOChannel @@ -16639,39 +17780,39 @@ the #GIOChannel. deprecated="1" deprecated-version="2.2"> Writes data to a #GIOChannel. + filename="glib/giochannel.c" + line="324">Writes data to a #GIOChannel. Use g_io_channel_write_chars() instead. - + %G_IO_ERROR_NONE if the operation was successful. + filename="glib/giochannel.c" + line="333">%G_IO_ERROR_NONE if the operation was successful. a #GIOChannel + filename="glib/giochannel.c" + line="326">a #GIOChannel the buffer containing the data to write + filename="glib/giochannel.c" + line="327">the buffer containing the data to write the number of bytes to write + filename="glib/giochannel.c" + line="328">the number of bytes to write the number of bytes actually written + filename="glib/giochannel.c" + line="329">the number of bytes actually written @@ -16680,39 +17821,39 @@ the #GIOChannel. c:identifier="g_io_channel_write_chars" throws="1"> Replacement for g_io_channel_write() with the new API. + filename="glib/giochannel.c" + line="2171">Replacement for g_io_channel_write() with the new API. On seekable channels with encodings other than %NULL or UTF-8, generic mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () may only be made on a channel from which data has been read in the cases described in the documentation for g_io_channel_set_encoding (). - + the status of the operation. + filename="glib/giochannel.c" + line="2192">the status of the operation. a #GIOChannel + filename="glib/giochannel.c" + line="2173">a #GIOChannel a buffer to write data from + filename="glib/giochannel.c" + line="2174">a buffer to write data from the size of the buffer. If -1, the buffer + filename="glib/giochannel.c" + line="2175">the size of the buffer. If -1, the buffer is taken to be a nul-terminated string. @@ -16721,8 +17862,8 @@ cases described in the documentation for g_io_channel_set_encoding (). caller-allocates="0" transfer-ownership="full"> The number of bytes written. This can be nonzero + filename="glib/giochannel.c" + line="2177">The number of bytes written. This can be nonzero even if the return value is not %G_IO_STATUS_NORMAL. If the return value is %G_IO_STATUS_NORMAL and the channel is blocking, this will always be equal @@ -16735,27 +17876,27 @@ cases described in the documentation for g_io_channel_set_encoding (). c:identifier="g_io_channel_write_unichar" throws="1"> Writes a Unicode character to @channel. + filename="glib/giochannel.c" + line="2520">Writes a Unicode character to @channel. This function cannot be called on a channel with %NULL encoding. - + a #GIOStatus + filename="glib/giochannel.c" + line="2530">a #GIOStatus a #GIOChannel + filename="glib/giochannel.c" + line="2522">a #GIOChannel a character + filename="glib/giochannel.c" + line="2523">a character @@ -16763,21 +17904,21 @@ This function cannot be called on a channel with %NULL encoding. Converts an `errno` error number to a #GIOChannelError. - + filename="glib/giochannel.c" + line="734">Converts an `errno` error number to a #GIOChannelError. + a #GIOChannelError error number, e.g. + filename="glib/giochannel.c" + line="740">a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. an `errno` error number, e.g. `EINVAL` + filename="glib/giochannel.c" + line="736">an `errno` error number, e.g. `EINVAL` @@ -16792,55 +17933,55 @@ This function cannot be called on a channel with %NULL encoding. c:type="GIOChannelError" glib:error-domain="g-io-channel-error-quark"> Error codes returned by #GIOChannel operations. - + filename="glib/giochannel.c" + line="2572">Error codes returned by #GIOChannel operations. + File too large. + filename="glib/giochannel.c" + line="2574">File too large. Invalid argument. + filename="glib/giochannel.c" + line="2575">Invalid argument. IO error. + filename="glib/giochannel.c" + line="2576">IO error. File is a directory. + filename="glib/giochannel.c" + line="2577">File is a directory. No space left on device. + filename="glib/giochannel.c" + line="2578">No space left on device. No such device or address. + filename="glib/giochannel.c" + line="2579">No such device or address. Value too large for defined datatype. + filename="glib/giochannel.c" + line="2580">Value too large for defined datatype. Broken pipe. + filename="glib/giochannel.c" + line="2581">Broken pipe. Some other error. + filename="glib/giochannel.c" + line="2582">Some other error. glib:get-type="g_io_condition_get_type" c:type="GIOCondition"> A bitwise combination representing a condition to watch for on an + filename="glib/giochannel.c" + line="680">A bitwise combination representing a condition to watch for on an event source. glib:nick="in" glib:name="G_IO_IN"> There is data to read. + filename="glib/giochannel.c" + line="682">There is data to read. glib:nick="out" glib:name="G_IO_OUT"> Data can be written (without blocking). + filename="glib/giochannel.c" + line="683">Data can be written (without blocking). glib:nick="pri" glib:name="G_IO_PRI"> There is urgent data to read. + filename="glib/giochannel.c" + line="684">There is urgent data to read. glib:nick="err" glib:name="G_IO_ERR"> Error condition. + filename="glib/giochannel.c" + line="685">Error condition. glib:nick="hup" glib:name="G_IO_HUP"> Hung up (the connection has been broken, usually for + filename="glib/giochannel.c" + line="686">Hung up (the connection has been broken, usually for pipes and sockets). glib:nick="nval" glib:name="G_IO_NVAL"> Invalid request. The file descriptor is not open. + filename="glib/giochannel.c" + line="688">Invalid request. The file descriptor is not open. #GIOError is only used by the deprecated functions + filename="glib/giochannel.c" + line="132">#GIOError is only used by the deprecated functions g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). - + no error + filename="glib/giochannel.c" + line="134">no error an EAGAIN error occurred + filename="glib/giochannel.c" + line="135">an EAGAIN error occurred an EINVAL error occurred + filename="glib/giochannel.c" + line="136">an EINVAL error occurred another error occurred + filename="glib/giochannel.c" + line="137">another error occurred Specifies properties of a #GIOChannel. Some of the flags can only be + filename="glib/giochannel.c" + line="942">Specifies properties of a #GIOChannel. Some of the flags can only be read with g_io_channel_get_flags(), but not changed with g_io_channel_set_flags(). - + no special flags set. Since: 2.74 + filename="glib/giochannel.c" + line="944">no special flags set. Since: 2.74 turns on append mode, corresponds to %O_APPEND + filename="glib/giochannel.c" + line="945">turns on append mode, corresponds to %O_APPEND (see the documentation of the UNIX open() syscall) turns on nonblocking mode, corresponds to + filename="glib/giochannel.c" + line="947">turns on nonblocking mode, corresponds to %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() syscall) @@ -16963,24 +18104,24 @@ g_io_channel_set_flags(). value="4" c:identifier="G_IO_FLAG_IS_READABLE"> indicates that the io channel is readable. + filename="glib/giochannel.c" + line="950">indicates that the io channel is readable. This flag cannot be changed. indicates that the io channel is writable. + filename="glib/giochannel.c" + line="952">indicates that the io channel is writable. This flag cannot be changed. a misspelled version of @G_IO_FLAG_IS_WRITABLE + filename="glib/giochannel.c" + line="954">a misspelled version of @G_IO_FLAG_IS_WRITABLE that existed before the spelling was fixed in GLib 2.30. It is kept here for compatibility reasons. Deprecated since 2.30 @@ -16988,54 +18129,54 @@ g_io_channel_set_flags(). value="16" c:identifier="G_IO_FLAG_IS_SEEKABLE"> indicates that the io channel is seekable, + filename="glib/giochannel.c" + line="957">indicates that the io channel is seekable, i.e. that g_io_channel_seek_position() can be used on it. This flag cannot be changed. the mask that specifies all the valid flags. + filename="glib/giochannel.c" + line="960">the mask that specifies all the valid flags. the mask of the flags that are returned from + filename="glib/giochannel.c" + line="961">the mask of the flags that are returned from g_io_channel_get_flags() the mask of the flags that the user can modify + filename="glib/giochannel.c" + line="963">the mask of the flags that the user can modify with g_io_channel_set_flags() Specifies the type of function passed to g_io_add_watch() or + filename="glib/giochannel.c" + line="667">Specifies the type of function passed to g_io_add_watch() or g_io_add_watch_full(), which is called when the requested condition on a #GIOChannel is satisfied. - + the function should return %FALSE if the event source + filename="glib/giochannel.c" + line="677">the function should return %FALSE if the event source should be removed the #GIOChannel event source + filename="glib/giochannel.c" + line="669">the #GIOChannel event source the condition which has been satisfied + filename="glib/giochannel.c" + line="670">the condition which has been satisfied nullable="1" allow-none="1"> user data set in g_io_add_watch() or g_io_add_watch_full() + filename="glib/giochannel.c" + line="671">user data set in g_io_add_watch() or g_io_add_watch_full() A table of functions used to handle different types of #GIOChannel + filename="glib/giochannel.c" + line="87">A table of functions used to handle different types of #GIOChannel in a generic way. - + + reads raw bytes from the channel. This is called from + various functions such as g_io_channel_read_chars() to + read raw bytes from the channel. Encoding and buffering + issues are dealt with at a higher level. - + @@ -17078,8 +18225,14 @@ in a generic way. + writes raw bytes to the channel. This is called from + various functions such as g_io_channel_write_chars() to + write raw bytes to the channel. Encoding and buffering + issues are dealt with at a higher level. - + @@ -17100,8 +18253,12 @@ in a generic way. + seeks the channel. This is called from + g_io_channel_seek() on channels that support it. - + @@ -17119,8 +18276,12 @@ in a generic way. + closes the channel. This is called from + g_io_channel_close() after flushing the buffers. - + @@ -17132,8 +18293,12 @@ in a generic way. + creates a watch on the channel. This call + corresponds directly to g_io_create_watch(). - + @@ -17148,8 +18313,16 @@ in a generic way. + called from g_io_channel_unref() when the channel needs to + be freed. This function must free the memory associated + with the channel, including freeing the #GIOChannel + structure itself. The channel buffers have been flushed + and possibly @io_close has been called by the time this + function is called. - + @@ -17161,8 +18334,14 @@ in a generic way. + sets the #GIOFlags on the channel. This is called + from g_io_channel_set_flags() with all flags except + for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked + out. - + @@ -17177,8 +18356,14 @@ in a generic way. + gets the #GIOFlags for the channel. This function + need only return the %G_IO_FLAG_APPEND and + %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() + automatically adds the others as appropriate. - + @@ -17192,28 +18377,28 @@ in a generic way. Statuses returned by most of the #GIOFuncs functions. - + filename="glib/giochannel.c" + line="122">Statuses returned by most of the #GIOFuncs functions. + An error occurred. + filename="glib/giochannel.c" + line="124">An error occurred. Success. + filename="glib/giochannel.c" + line="125">Success. End of file. + filename="glib/giochannel.c" + line="126">End of file. Resource temporarily unavailable. + filename="glib/giochannel.c" + line="127">Resource temporarily unavailable. version="2.6" introspectable="0"> Checks whether a character is a directory -separator. It returns %TRUE for '/' on UNIX -machines and for '\' or '/' under Windows. - + filename="glib/docs.c" + line="898">Checks whether a character is a directory separator. + +It returns true for `'/'` on UNIX machines and for `'\'` or `'/'` under +Windows. + a character + filename="glib/docs.c" + line="900">a character @@ -17239,12 +18425,13 @@ machines and for '\' or '/' under Windows. c:type="G_KEY_FILE_DESKTOP_GROUP" version="2.14"> The name of the main group of a desktop entry file, as defined in the -[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). + filename="glib/gkeyfile.c" + line="252">The name of the main group of a desktop entry file, as defined in the +[Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/). + Consult the specification for more details about the meanings of the keys below. - + c:type="G_KEY_FILE_DESKTOP_KEY_ACTIONS" version="2.38"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list + filename="glib/gkeyfile.c" + line="468">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string list giving the available application actions. - + c:type="G_KEY_FILE_DESKTOP_KEY_CATEGORIES" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list + filename="glib/gkeyfile.c" + line="416">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings giving the categories in which the desktop entry should be shown in a menu. - + c:type="G_KEY_FILE_DESKTOP_KEY_COMMENT" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + filename="glib/gkeyfile.c" + line="314">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the tooltip for the desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE" version="2.38"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + filename="glib/gkeyfile.c" + line="459">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean set to true if the application is D-Bus activatable. - + c:type="G_KEY_FILE_DESKTOP_KEY_EXEC" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the command line to execute. It is only valid for desktop -entries with the `Application` type. - + filename="glib/gkeyfile.c" + line="374">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string +giving the command line to execute. + +It is only valid for desktop entries with the `Application` type. + c:type="G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + filename="glib/gkeyfile.c" + line="296">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the generic name of the desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_HIDDEN" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + filename="glib/gkeyfile.c" + line="333">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the desktop entry has been deleted by the user. - + c:type="G_KEY_FILE_DESKTOP_KEY_ICON" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + filename="glib/gkeyfile.c" + line="323">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the name of the icon to be displayed for the desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_MIME_TYPE" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list + filename="glib/gkeyfile.c" + line="407">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings giving the MIME types supported by this desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_NAME" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + filename="glib/gkeyfile.c" + line="287">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a localized string giving the specific name of the desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + filename="glib/gkeyfile.c" + line="352">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings identifying the environments that should not display the desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + filename="glib/gkeyfile.c" + line="305">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the desktop entry should be shown in menus. - + c:type="G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + filename="glib/gkeyfile.c" + line="342">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a list of strings identifying the environments that should display the desktop entry. - + c:type="G_KEY_FILE_DESKTOP_KEY_PATH" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string -containing the working directory to run the program in. It is only -valid for desktop entries with the `Application` type. - + filename="glib/gkeyfile.c" + line="385">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string +containing the working directory to run the program in. + +It is only valid for desktop entries with the `Application` type. + c:type="G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + filename="glib/gkeyfile.c" + line="426">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the application supports the -[Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). - +[Startup Notification Protocol Specification](https://specifications.freedesktop.org/startup-notification-spec/latest/). + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string + filename="glib/gkeyfile.c" + line="436">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is string identifying the WM class or name hint of a window that the application -will create, which can be used to emulate Startup Notification with -older applications. - +will create, which can be used to emulate +[Startup Notification](https://specifications.freedesktop.org/startup-notification-spec/latest/) +with older applications. + c:type="G_KEY_FILE_DESKTOP_KEY_TERMINAL" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + filename="glib/gkeyfile.c" + line="396">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a boolean stating whether the program should be run in a terminal window. It is only valid for desktop entries with the `Application` type. - + c:type="G_KEY_FILE_DESKTOP_KEY_TRY_EXEC" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + filename="glib/gkeyfile.c" + line="362">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the file name of a binary on disk used to determine if the -program is actually installed. It is only valid for desktop entries -with the `Application` type. - +program is actually installed. + +It is only valid for desktop entries with the `Application` type. + c:type="G_KEY_FILE_DESKTOP_KEY_TYPE" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + filename="glib/gkeyfile.c" + line="264">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the type of the desktop entry. -Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION, -%G_KEY_FILE_DESKTOP_TYPE_LINK, or -%G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. - +Usually [const@GLib.KEY_FILE_DESKTOP_TYPE_APPLICATION], +[const@GLib.KEY_FILE_DESKTOP_TYPE_LINK], or +[const@GLib.KEY_FILE_DESKTOP_TYPE_DIRECTORY]. + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the URL to access. It is only valid for desktop entries -with the `Link` type. - + filename="glib/gkeyfile.c" + line="448">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string +giving the URL to access. + +It is only valid for desktop entries with the `Link` type. + c:type="G_KEY_FILE_DESKTOP_KEY_VERSION" version="2.14"> A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + filename="glib/gkeyfile.c" + line="277">A key under [const@GLib.KEY_FILE_DESKTOP_GROUP], whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file. - + c:type="G_KEY_FILE_DESKTOP_TYPE_APPLICATION" version="2.14"> The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + filename="glib/gkeyfile.c" + line="477">The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing applications. - + c:type="G_KEY_FILE_DESKTOP_TYPE_DIRECTORY" version="2.14"> The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + filename="glib/gkeyfile.c" + line="495">The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing directories. - + c:type="G_KEY_FILE_DESKTOP_TYPE_LINK" version="2.14"> The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + filename="glib/gkeyfile.c" + line="486">The value of the [const@GLib.KEY_FILE_DESKTOP_KEY_TYPE], key for desktop entries representing links to documents. - + glib:get-type="g_key_file_get_type" c:symbol-prefix="key_file"> #GKeyFile lets you parse, edit or create files containing groups of -key-value pairs, which we call "key files" for lack of a better name. -Several freedesktop.org specifications use key files now, e.g the -[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) -and the -[Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). + filename="glib/gkeyfile.c" + line="76">`GKeyFile` parses .ini-like config files. + +`GKeyFile` lets you parse, edit or create files containing groups of +key-value pairs, which we call ‘key files’ for lack of a better name. +Several freedesktop.org specifications use key files. For example, the +[Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/) +and the [Icon Theme Specification](https://specifications.freedesktop.org/icon-theme-spec/latest/). The syntax of key files is described in detail in the -[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), -here is a quick summary: Key files -consists of groups of key-value pairs, interspersed with comments. +[Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/), +here is a quick summary: Key files consists of groups of key-value pairs, interspersed +with comments. -|[ +```txt # this is just an example # there can be comments before the first group @@ -17563,41 +18756,40 @@ Welcome=Hello Welcome[de]=Hallo Welcome[fr_FR]=Bonjour Welcome[it]=Ciao -Welcome[be@latin]=Hello [Another Group] Numbers=2;20;-200;0 Booleans=true;false;true;true -]| +``` -Lines beginning with a '#' and blank lines are considered comments. +Lines beginning with a `#` and blank lines are considered comments. Groups are started by a header line containing the group name enclosed -in '[' and ']', and ended implicitly by the start of the next group or +in `[` and `]`, and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group. -Key-value pairs generally have the form `key=value`, with the -exception of localized strings, which have the form -`key[locale]=value`, with a locale identifier of the -form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` -are optional. -Space before and after the '=' character are ignored. Newline, tab, -carriage return and backslash characters in value are escaped as \n, -\t, \r, and \\\\, respectively. To preserve leading spaces in values, -these can also be escaped as \s. +Key-value pairs generally have the form `key=value`, with the exception +of localized strings, which have the form `key[locale]=value`, with a +locale identifier of the form `lang_COUNTRY@MODIFIER` where `COUNTRY` +and `MODIFIER` are optional. As a special case, the locale `C` is associated +with the untranslated pair `key=value` (since GLib 2.84). Space before and +after the `=` character is ignored. Newline, tab, carriage return and +backslash characters in value are escaped as `\n`, `\t`, `\r`, and `\\\\`, +respectively. To preserve leading spaces in values, these can also be escaped +as `\s`. Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, -typically ';' or ','. To use the list separator character in a value in +typically `;` or `,`. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash. This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences: -- .ini files use the ';' character to begin comments, - key files use the '#' character. +- .ini files use the `;` character to begin comments, + key files use the `#` character. - Key files do not allow for ungrouped keys meaning only comments can precede the first group. @@ -17605,23 +18797,22 @@ on Windows, but there are some important differences: - Key files are always encoded in UTF-8. - Key and Group names are case-sensitive. For example, a group called - [GROUP] is a different from [group]. + `[GROUP]` is a different from `[group]`. -- .ini files don't have a strongly typed boolean entry type, - they only have GetProfileInt(). In key files, only - true and false (in lower case) are allowed. +- .ini files don’t have a strongly typed boolean entry type, + they only have `GetProfileInt()`. In key files, only + `true` and `false` (in lower case) are allowed. Note that in contrast to the -[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), -groups in key files may contain the same -key multiple times; the last entry wins. Key files may also contain -multiple groups with the same name; they are merged together. -Another difference is that keys and group names in key files are not +[Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/), +groups in key files may contain the same key multiple times; the last entry wins. +Key files may also contain multiple groups with the same name; they are merged +together. Another difference is that keys and group names in key files are not restricted to ASCII characters. Here is an example of loading a key file and reading a value: -|[<!-- language="C" --> +```c g_autoptr(GError) error = NULL; g_autoptr(GKeyFile) key_file = g_key_file_new (); @@ -17644,11 +18835,11 @@ else if (val == NULL) // Fall back to a default value. val = g_strdup ("default-value"); } -]| +``` Here is an example of creating and saving a key file: -|[<!-- language="C" --> +```c g_autoptr(GKeyFile) key_file = g_key_file_new (); const gchar *val = …; g_autoptr(GError) error = NULL; @@ -17671,20 +18862,22 @@ if (data == NULL) return; } g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); -]| - +``` + Creates a new empty #GKeyFile object. Use -g_key_file_load_from_file(), g_key_file_load_from_data(), -g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to + filename="glib/gkeyfile.c" + line="705">Creates a new empty [struct@GLib.KeyFile] object. + +Use [method@GLib.KeyFile.load_from_file], +[method@GLib.KeyFile.load_from_data], [method@GLib.KeyFile.load_from_dirs] or +[method@GLib.KeyFile.load_from_data_dirs] to read an existing key file. - + an empty #GKeyFile. + filename="glib/gkeyfile.c" + line="715">an empty [struct@GLib.KeyFile]. @@ -17693,19 +18886,21 @@ read an existing key file. version="2.6" introspectable="0"> Clears all keys and groups from @key_file, and decreases the -reference count by 1. If the reference count reaches zero, -frees the key file and all its allocated memory. - + filename="glib/gkeyfile.c" + line="1247">Clears all keys and groups from @key_file, and decreases the +reference count by 1. + +If the reference count reaches zero, frees the key file and all its allocated +memory. + - + a #GKeyFile + filename="glib/gkeyfile.c" + line="1249">a key file @@ -17715,39 +18910,38 @@ frees the key file and all its allocated memory. version="2.6" throws="1"> Returns the value associated with @key under @group_name as a + filename="glib/gkeyfile.c" + line="2627">Returns the value associated with @key under @group_name as a boolean. -If @key cannot be found then %FALSE is returned and @error is set -to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value -associated with @key cannot be interpreted as a boolean then %FALSE -is returned and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. - +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. Likewise, if the value associated with @key cannot be interpreted +as a boolean then [error@GLib.KeyFileError.INVALID_VALUE] is returned. + the value associated with the key as a boolean, - or %FALSE if the key was not found or could not be parsed. + filename="glib/gkeyfile.c" + line="2641">the value associated with the key as a boolean, + or false if the key was not found or could not be parsed. a #GKeyFile + filename="glib/gkeyfile.c" + line="2629">a key file a group name + filename="glib/gkeyfile.c" + line="2630">a group name a key + filename="glib/gkeyfile.c" + line="2631">a key @@ -17757,22 +18951,21 @@ is returned and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. version="2.6" throws="1"> Returns the values associated with @key under @group_name as + filename="glib/gkeyfile.c" + line="2719">Returns the values associated with @key under @group_name as booleans. -If @key cannot be found then %NULL is returned and @error is set to -%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated -with @key cannot be interpreted as booleans then %NULL is returned -and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. - +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. Likewise, if the values associated with @key cannot be interpreted +as booleans then [error@GLib.KeyFileError.INVALID_VALUE] is returned. + - the values associated with the key as a list of booleans, or %NULL if the + filename="glib/gkeyfile.c" + line="2734"> + the values associated with the key as a list of booleans, or `NULL` if the key was not found or could not be parsed. The returned list of booleans - should be freed with g_free() when no longer needed. + should be freed with [func@GLib.free] when no longer needed. @@ -17780,20 +18973,20 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. a #GKeyFile + filename="glib/gkeyfile.c" + line="2721">a key file a group name + filename="glib/gkeyfile.c" + line="2722">a group name a key + filename="glib/gkeyfile.c" + line="2723">a key caller-allocates="0" transfer-ownership="full"> the number of booleans returned + filename="glib/gkeyfile.c" + line="2724">the number of booleans returned @@ -17812,27 +19005,28 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. version="2.6" throws="1"> Retrieves a comment above @key from @group_name. -If @key is %NULL then @comment will be read from above -@group_name. If both @key and @group_name are %NULL, then + filename="glib/gkeyfile.c" + line="3806">Retrieves a comment above @key from @group_name. + +If @key is `NULL` then @comment will be read from above +@group_name. If both @key and @group_name are `NULL`, then @comment will be read from above the first group in the file. -Note that the returned string does not include the '#' comment markers, +Note that the returned string does not include the `#` comment markers, but does include any whitespace after them (on each line). It includes the line breaks between lines, but does not include the final line break. - + a comment that should be freed with g_free() + filename="glib/gkeyfile.c" + line="3823">a comment that should be freed with [func@GLib.free] a #GKeyFile + filename="glib/gkeyfile.c" + line="3808">a key file nullable="1" allow-none="1"> a group name, or %NULL + filename="glib/gkeyfile.c" + line="3809">a group name, or `NULL` to get a top-level comment nullable="1" allow-none="1"> a key + filename="glib/gkeyfile.c" + line="3810">a key, or `NULL` to get a group comment @@ -17860,39 +19054,37 @@ the line breaks between lines, but does not include the final line break. version="2.12" throws="1"> Returns the value associated with @key under @group_name as a -double. If @group_name is %NULL, the start_group is used. + filename="glib/gkeyfile.c" + line="3214">Returns the value associated with @key under @group_name as a double. -If @key cannot be found then 0.0 is returned and @error is set to -%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated -with @key cannot be interpreted as a double then 0.0 is returned -and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. - +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. Likewise, if the value associated with @key cannot be interpreted +as a double then [error@GLib.KeyFileError.INVALID_VALUE] is returned. + the value associated with the key as a double, or - 0.0 if the key was not found or could not be parsed. + filename="glib/gkeyfile.c" + line="3227">the value associated with the key as a double, or + `0.0` if the key was not found or could not be parsed. a #GKeyFile + filename="glib/gkeyfile.c" + line="3216">a key file a group name + filename="glib/gkeyfile.c" + line="3217">a group name a key + filename="glib/gkeyfile.c" + line="3218">a key @@ -17902,22 +19094,21 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. version="2.12" throws="1"> Returns the values associated with @key under @group_name as + filename="glib/gkeyfile.c" + line="3307">Returns the values associated with @key under @group_name as doubles. -If @key cannot be found then %NULL is returned and @error is set to -%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated -with @key cannot be interpreted as doubles then %NULL is returned -and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. - +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. Likewise, if the values associated with @key cannot be interpreted +as doubles then [error@GLib.KeyFileError.INVALID_VALUE] is returned. + - the values associated with the key as a list of doubles, or %NULL if the + filename="glib/gkeyfile.c" + line="3322"> + the values associated with the key as a list of doubles, or `NULL` if the key was not found or could not be parsed. The returned list of doubles - should be freed with g_free() when no longer needed. + should be freed with [func@GLib.free] when no longer needed. @@ -17925,20 +19116,20 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. a #GKeyFile + filename="glib/gkeyfile.c" + line="3309">a key file a group name + filename="glib/gkeyfile.c" + line="3310">a group name a key + filename="glib/gkeyfile.c" + line="3311">a key caller-allocates="0" transfer-ownership="full"> the number of doubles returned + filename="glib/gkeyfile.c" + line="3312">the number of doubles returned @@ -17956,16 +19147,17 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. c:identifier="g_key_file_get_groups" version="2.6"> Returns all groups in the key file loaded with @key_file. -The array of returned groups will be %NULL-terminated, so -@length may optionally be %NULL. - + filename="glib/gkeyfile.c" + line="1797">Returns all groups in the key file loaded with @key_file. + +The array of returned groups will be `NULL`-terminated, so +@length may optionally be `NULL`. + a newly-allocated %NULL-terminated array of strings. - Use g_strfreev() to free it. + filename="glib/gkeyfile.c" + line="1808">a newly-allocated + `NULL`-terminated array of strings. Use [func@GLib.strfreev] to free it. @@ -17973,8 +19165,8 @@ The array of returned groups will be %NULL-terminated, so a #GKeyFile + filename="glib/gkeyfile.c" + line="1799">a key file return location for the number of returned groups, or %NULL + filename="glib/gkeyfile.c" + line="1800">return location for the number of returned groups, + or `NULL` to ignore @@ -17995,35 +19188,37 @@ The array of returned groups will be %NULL-terminated, so version="2.26" throws="1"> Returns the value associated with @key under @group_name as a signed -64-bit integer. This is similar to g_key_file_get_integer() but can return + filename="glib/gkeyfile.c" + line="2934">Returns the value associated with @key under @group_name as a signed +64-bit integer. + +This is similar to [method@GLib.KeyFile.get_integer] but can return 64-bit results without truncation. - + the value associated with the key as a signed 64-bit integer, or -0 if the key was not found or could not be parsed. + filename="glib/gkeyfile.c" + line="2947">the value associated with the key as a signed 64-bit integer, or + `0` if the key was not found or could not be parsed. a non-%NULL #GKeyFile + filename="glib/gkeyfile.c" + line="2936">a key file a non-%NULL group name + filename="glib/gkeyfile.c" + line="2937">a group name a non-%NULL key + filename="glib/gkeyfile.c" + line="2938">a key @@ -18033,40 +19228,39 @@ The array of returned groups will be %NULL-terminated, so version="2.6" throws="1"> Returns the value associated with @key under @group_name as an + filename="glib/gkeyfile.c" + line="2838">Returns the value associated with @key under @group_name as an integer. -If @key cannot be found then 0 is returned and @error is set to -%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated -with @key cannot be interpreted as an integer, or is out of range -for a #gint, then 0 is returned -and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. - +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. Likewise, if the value associated with @key cannot be interpreted +as an integer, or is out of range for a `gint`, then +[error@GLib.KeyFileError.INVALID_VALUE] is returned. + the value associated with the key as an integer, or - 0 if the key was not found or could not be parsed. + filename="glib/gkeyfile.c" + line="2853">the value associated with the key as an integer, or + `0` if the key was not found or could not be parsed. a #GKeyFile + filename="glib/gkeyfile.c" + line="2840">a key file a group name + filename="glib/gkeyfile.c" + line="2841">a group name a key + filename="glib/gkeyfile.c" + line="2842">a key @@ -18076,23 +19270,22 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. version="2.6" throws="1"> Returns the values associated with @key under @group_name as + filename="glib/gkeyfile.c" + line="3094">Returns the values associated with @key under @group_name as integers. -If @key cannot be found then %NULL is returned and @error is set to -%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated -with @key cannot be interpreted as integers, or are out of range for -#gint, then %NULL is returned -and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. - +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. Likewise, if the values associated with @key cannot be interpreted +as integers, or are out of range for `gint`, then +[error@GLib.KeyFileError.INVALID_VALUE] is returned. + - the values associated with the key as a list of integers, or %NULL if + filename="glib/gkeyfile.c" + line="3110"> + the values associated with the key as a list of integers, or `NULL` if the key was not found or could not be parsed. The returned list of - integers should be freed with g_free() when no longer needed. + integers should be freed with [func@GLib.free] when no longer needed. @@ -18100,20 +19293,20 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. a #GKeyFile + filename="glib/gkeyfile.c" + line="3096">a key file a group name + filename="glib/gkeyfile.c" + line="3097">a group name a key + filename="glib/gkeyfile.c" + line="3098">a key caller-allocates="0" transfer-ownership="full"> the number of integers returned + filename="glib/gkeyfile.c" + line="3099">the number of integers returned @@ -18132,18 +19325,18 @@ and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE. version="2.6" throws="1"> Returns all keys for the group name @group_name. The array of -returned keys will be %NULL-terminated, so @length may -optionally be %NULL. In the event that the @group_name cannot -be found, %NULL is returned and @error is set to -%G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - + filename="glib/gkeyfile.c" + line="1697">Returns all keys for the group name @group_name. + +The array of returned keys will be `NULL`-terminated, so @length may +optionally be `NULL`. If the @group_name cannot be found, +[error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. + a newly-allocated %NULL-terminated array of strings. - Use g_strfreev() to free it. + filename="glib/gkeyfile.c" + line="1711">a newly-allocated + `NULL`-terminated array of strings. Use [func@GLib.strfreev] to free it. @@ -18151,14 +19344,14 @@ be found, %NULL is returned and @error is set to a #GKeyFile + filename="glib/gkeyfile.c" + line="1699">a key file a group name + filename="glib/gkeyfile.c" + line="1700">a group name return location for the number of keys returned, or %NULL + filename="glib/gkeyfile.c" + line="1701">return location for the number of keys returned, + or `NULL` to ignore @@ -18178,41 +19372,41 @@ be found, %NULL is returned and @error is set to c:identifier="g_key_file_get_locale_for_key" version="2.56"> Returns the actual locale which the result of -g_key_file_get_locale_string() or g_key_file_get_locale_string_list() -came from. + filename="glib/gkeyfile.c" + line="2421">Returns the actual locale which the result of +[method@GLib.KeyFile.get_locale_string] or +[method@GLib.KeyFile.get_locale_string_list] came from. -If calling g_key_file_get_locale_string() or -g_key_file_get_locale_string_list() with exactly the same @key_file, +If calling [method@GLib.KeyFile.get_locale_string] or +[method@GLib.KeyFile.get_locale_string_list] with exactly the same @key_file, @group_name, @key and @locale, the result of those functions will have originally been tagged with the locale that is the result of this function. - + the locale from the file, or %NULL if the key was not + filename="glib/gkeyfile.c" + line="2438">the locale from the file, or `NULL` if the key was not found or the entry in the file was was untranslated a #GKeyFile + filename="glib/gkeyfile.c" + line="2423">a key file a group name + filename="glib/gkeyfile.c" + line="2424">a group name a key + filename="glib/gkeyfile.c" + line="2425">a key nullable="1" allow-none="1"> a locale identifier or %NULL + filename="glib/gkeyfile.c" + line="2426">a locale identifier or `NULL` to use the current locale @@ -18231,44 +19425,48 @@ this function. version="2.6" throws="1"> Returns the value associated with @key under @group_name -translated in the given @locale if available. If @locale is -%NULL then the current locale is assumed. + filename="glib/gkeyfile.c" + line="2272">Returns the value associated with @key under @group_name +translated in the given @locale if available. + +If @locale is `C` then the untranslated value is returned (since GLib 2.84). -If @locale is to be non-%NULL, or if the current locale will change over -the lifetime of the #GKeyFile, it must be loaded with -%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. +If @locale is `NULL` then the current locale is assumed. -If @key cannot be found then %NULL is returned and @error is set -to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated +If @locale is to be non-`NULL`, or if the current locale will change over +the lifetime of the [struct@GLib.KeyFile], it must be loaded with +[flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all +locales. + +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. If the value associated with @key cannot be interpreted or no suitable translation can be found then the untranslated value is returned. - + a newly allocated string or %NULL if the specified + filename="glib/gkeyfile.c" + line="2297">a newly allocated string or `NULL` if the specified key cannot be found. a #GKeyFile + filename="glib/gkeyfile.c" + line="2274">a key file a group name + filename="glib/gkeyfile.c" + line="2275">a group name a key + filename="glib/gkeyfile.c" + line="2276">a key nullable="1" allow-none="1"> a locale identifier or %NULL + filename="glib/gkeyfile.c" + line="2277">a locale identifier or `NULL` to use the current locale @@ -18287,28 +19485,32 @@ be found then the untranslated value is returned. version="2.6" throws="1"> Returns the values associated with @key under @group_name -translated in the given @locale if available. If @locale is -%NULL then the current locale is assumed. + filename="glib/gkeyfile.c" + line="2489">Returns the values associated with @key under @group_name +translated in the given @locale if available. + +If @locale is `C` then the untranslated value is returned (since GLib 2.84). -If @locale is to be non-%NULL, or if the current locale will change over -the lifetime of the #GKeyFile, it must be loaded with -%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. +If @locale is `NULL` then the current locale is assumed. -If @key cannot be found then %NULL is returned and @error is set -to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated +If @locale is to be non-`NULL`, or if the current locale will change over +the lifetime of the [struct@GLib.KeyFile], it must be loaded with +[flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all +locales. + +If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. If the values associated with @key cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The -returned array is %NULL-terminated, so @length may optionally -be %NULL. - +returned array is `NULL`-terminated, so @length may optionally +be `NULL`. + a newly allocated %NULL-terminated string array - or %NULL if the key isn't found. The string array should be freed - with g_strfreev(). + filename="glib/gkeyfile.c" + line="2518"> + a newly allocated `NULL`-terminated string array or `NULL` if the key + isn’t found. The string array should be freed with [func@GLib.strfreev]. @@ -18316,20 +19518,20 @@ be %NULL. a #GKeyFile + filename="glib/gkeyfile.c" + line="2491">a key file a group name + filename="glib/gkeyfile.c" + line="2492">a group name a key + filename="glib/gkeyfile.c" + line="2493">a key nullable="1" allow-none="1"> a locale identifier or %NULL + filename="glib/gkeyfile.c" + line="2494">a locale identifier or `NULL` to use the current locale optional="1" allow-none="1"> return location for the number of returned strings or %NULL + filename="glib/gkeyfile.c" + line="2495">return location for the number of returned strings + or `NULL` to ignore @@ -18358,20 +19561,20 @@ be %NULL. c:identifier="g_key_file_get_start_group" version="2.6"> Returns the name of the start group of the file. - + filename="glib/gkeyfile.c" + line="1776">Returns the name of the start group of the file. + The start group of the key file. + filename="glib/gkeyfile.c" + line="1782">The start group of the key file. a #GKeyFile + filename="glib/gkeyfile.c" + line="1778">a key file @@ -18381,40 +19584,40 @@ be %NULL. version="2.6" throws="1"> Returns the string value associated with @key under @group_name. -Unlike g_key_file_get_value(), this function handles escape sequences -like \s. + filename="glib/gkeyfile.c" + line="1978">Returns the string value associated with @key under @group_name. + +Unlike [method@GLib.KeyFile.get_value], this function handles escape +sequences like `\s`. -In the event the key cannot be found, %NULL is returned and -@error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the -event that the @group_name cannot be found, %NULL is returned -and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - +If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. If the @group_name cannot be found, +[error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. + a newly allocated string or %NULL if the specified + filename="glib/gkeyfile.c" + line="1994">a newly allocated string or `NULL` if the specified key cannot be found. a #GKeyFile + filename="glib/gkeyfile.c" + line="1980">a key file a group name + filename="glib/gkeyfile.c" + line="1981">a group name a key + filename="glib/gkeyfile.c" + line="1982">a key @@ -18424,20 +19627,19 @@ and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. version="2.6" throws="1"> Returns the values associated with @key under @group_name. + filename="glib/gkeyfile.c" + line="2091">Returns the values associated with @key under @group_name. -In the event the key cannot be found, %NULL is returned and -@error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the -event that the @group_name cannot be found, %NULL is returned -and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - +If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is +returned. If the @group_name cannot be found, +[error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. + - a %NULL-terminated string array or %NULL if the specified - key cannot be found. The array should be freed with g_strfreev(). + filename="glib/gkeyfile.c" + line="2106"> + a `NULL`-terminated string array or `NULL` if the specified + key cannot be found. The array should be freed with [func@GLib.strfreev]. @@ -18445,20 +19647,20 @@ and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. a #GKeyFile + filename="glib/gkeyfile.c" + line="2093">a key file a group name + filename="glib/gkeyfile.c" + line="2094">a group name a key + filename="glib/gkeyfile.c" + line="2095">a key optional="1" allow-none="1"> return location for the number of returned strings, or %NULL + filename="glib/gkeyfile.c" + line="2096">return location for the number of returned + strings, or `NULL` to ignore @@ -18479,35 +19682,37 @@ and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. version="2.26" throws="1"> Returns the value associated with @key under @group_name as an unsigned -64-bit integer. This is similar to g_key_file_get_integer() but can return + filename="glib/gkeyfile.c" + line="3014">Returns the value associated with @key under @group_name as an unsigned +64-bit integer. + +This is similar to [method@GLib.KeyFile.get_integer] but can return large positive results without truncation. - + the value associated with the key as an unsigned 64-bit integer, -or 0 if the key was not found or could not be parsed. + filename="glib/gkeyfile.c" + line="3027">the value associated with the key as an unsigned 64-bit integer, + or `0` if the key was not found or could not be parsed. a non-%NULL #GKeyFile + filename="glib/gkeyfile.c" + line="3016">a key file a non-%NULL group name + filename="glib/gkeyfile.c" + line="3017">a group name a non-%NULL key + filename="glib/gkeyfile.c" + line="3018">a key @@ -18517,39 +19722,39 @@ or 0 if the key was not found or could not be parsed. version="2.6" throws="1"> Returns the raw value associated with @key under @group_name. -Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. + filename="glib/gkeyfile.c" + line="1870">Returns the raw value associated with @key under @group_name. + +Use [method@GLib.KeyFile.get_string] to retrieve an unescaped UTF-8 string. -In the event the key cannot be found, %NULL is returned and -@error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the -event that the @group_name cannot be found, %NULL is returned -and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - +If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] +is returned. If the @group_name cannot be found, +[error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned. + a newly allocated string or %NULL if the specified + filename="glib/gkeyfile.c" + line="1885">a newly allocated string or `NULL` if the specified key cannot be found. a #GKeyFile + filename="glib/gkeyfile.c" + line="1872">a key file a group name + filename="glib/gkeyfile.c" + line="1873">a group name a key + filename="glib/gkeyfile.c" + line="1874">a key @@ -18558,27 +19763,26 @@ and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND. c:identifier="g_key_file_has_group" version="2.6"> Looks whether the key file has the group @group_name. - + filename="glib/gkeyfile.c" + line="3877">Looks whether the key file has the group @group_name. + %TRUE if @group_name is a part of @key_file, %FALSE -otherwise. + filename="glib/gkeyfile.c" + line="3884">true if @group_name is a part of @key_file, false otherwise. a #GKeyFile + filename="glib/gkeyfile.c" + line="3879">a key file a group name + filename="glib/gkeyfile.c" + line="3880">a group name @@ -18589,41 +19793,42 @@ otherwise. introspectable="0" throws="1"> Looks whether the key file has the key @key in the group + filename="glib/gkeyfile.c" + line="3933">Looks whether the key file has the key @key in the group @group_name. -Note that this function does not follow the rules for #GError strictly; +Note that this function does not follow the rules for [struct@GLib.Error] +strictly; the return value both carries meaning and signals an error. To use -this function, you must pass a #GError pointer in @error, and check -whether it is not %NULL to see if an error occurred. +this function, you must pass a [struct@GLib.Error] pointer in @error, and +check whether it is not `NULL` to see if an error occurred. -Language bindings should use g_key_file_get_value() to test whether -or not a key exists. - +Language bindings should use [method@GLib.KeyFile.get_value] to test whether +a key exists. + %TRUE if @key is a part of @group_name, %FALSE otherwise + filename="glib/gkeyfile.c" + line="3952">true if @key is a part of @group_name, false otherwise a #GKeyFile + filename="glib/gkeyfile.c" + line="3935">a key file a group name + filename="glib/gkeyfile.c" + line="3936">a group name a key name + filename="glib/gkeyfile.c" + line="3937">a key name @@ -18633,33 +19838,35 @@ or not a key exists. version="2.50" throws="1"> Loads a key file from the data in @bytes into an empty #GKeyFile structure. -If the object cannot be created then %error is set to a #GKeyFileError. - + filename="glib/gkeyfile.c" + line="1056">Loads a key file from the data in @bytes into an empty [struct@GLib.KeyFile] +structure. + +If the object cannot be created then a [error@GLib.KeyFileError] is returned. + %TRUE if a key file could be loaded, %FALSE otherwise + filename="glib/gkeyfile.c" + line="1068">true if a key file could be loaded, false otherwise an empty #GKeyFile struct + filename="glib/gkeyfile.c" + line="1058">an empty [struct@GLib.KeyFile] struct a #GBytes + filename="glib/gkeyfile.c" + line="1059">a [struct@GLib.Bytes] flags from #GKeyFileFlags + filename="glib/gkeyfile.c" + line="1060">flags from [flags@GLib.KeyFileFlags] @@ -18669,39 +19876,40 @@ If the object cannot be created then %error is set to a #GKeyFileError. version="2.6" throws="1"> Loads a key file from memory into an empty #GKeyFile structure. -If the object cannot be created then %error is set to a #GKeyFileError. - + filename="glib/gkeyfile.c" + line="984">Loads a key file from memory into an empty [struct@GLib.KeyFile] structure. + +If the object cannot be created then a [error@GLib.KeyFileError is returned. + %TRUE if a key file could be loaded, %FALSE otherwise + filename="glib/gkeyfile.c" + line="996">true if a key file could be loaded, false otherwise an empty #GKeyFile struct + filename="glib/gkeyfile.c" + line="986">an empty key file key file loaded in memory + filename="glib/gkeyfile.c" + line="987">key file loaded in memory the length of @data in bytes (or (gsize)-1 if data is nul-terminated) + filename="glib/gkeyfile.c" + line="988">the length of @data in bytes (or `(gsize)-1` if data is nul-terminated) flags from #GKeyFileFlags + filename="glib/gkeyfile.c" + line="989">flags from [flags@GLib.KeyFileFlags] @@ -18711,30 +19919,32 @@ If the object cannot be created then %error is set to a #GKeyFileError. version="2.6" throws="1"> This function looks for a key file named @file in the paths -returned from g_get_user_data_dir() and g_get_system_data_dirs(), -loads the file into @key_file and returns the file's full path in -@full_path. If the file could not be loaded then an %error is -set to either a #GFileError or #GKeyFileError. - + filename="glib/gkeyfile.c" + line="1167">Looks for a key file named @file in the paths returned from +[func@GLib.get_user_data_dir] and [func@GLib.get_system_data_dirs], +loads the file into @key_file and returns the file’s full path in +@full_path. + +If the file could not be loaded then either a [error@GLib.FileError] or +[error@GLib.KeyFileError] is returned. + %TRUE if a key file could be loaded, %FALSE otherwise + filename="glib/gkeyfile.c" + line="1184">true if a key file could be loaded, false otherwise an empty #GKeyFile struct + filename="glib/gkeyfile.c" + line="1169">an empty [struct@GLib.KeyFile] struct a relative path to a filename to open and parse + filename="glib/gkeyfile.c" + line="1170">a relative path to a filename to open and parse optional="1" allow-none="1"> return location for a string containing the full path - of the file, or %NULL + filename="glib/gkeyfile.c" + line="1171">return location for a string + containing the full path of the file, or `NULL` to ignore flags from #GKeyFileFlags + filename="glib/gkeyfile.c" + line="1173">flags from [flags@GLib.KeyFileFlags] @@ -18762,40 +19972,40 @@ set to either a #GFileError or #GKeyFileError. version="2.14" throws="1"> This function looks for a key file named @file in the paths -specified in @search_dirs, loads the file into @key_file and -returns the file's full path in @full_path. + filename="glib/gkeyfile.c" + line="1088">Looks for a key file named @file in the paths specified in @search_dirs, +loads the file into @key_file and returns the file’s full path in @full_path. If the file could not be found in any of the @search_dirs, -%G_KEY_FILE_ERROR_NOT_FOUND is returned. If +[error@GLib.KeyFileError.NOT_FOUND] is returned. If the file is found but the OS returns an error when opening or reading the -file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a -%G_KEY_FILE_ERROR is returned. - +file, a [error@GLib.FileError] is returned. If there is a problem parsing the +file, a [error@GLib.KeyFileError] is returned. + %TRUE if a key file could be loaded, %FALSE otherwise + filename="glib/gkeyfile.c" + line="1108">true if a key file could be loaded, false otherwise an empty #GKeyFile struct + filename="glib/gkeyfile.c" + line="1090">an empty [struct@GLib.KeyFile] struct a relative path to a filename to open and parse + filename="glib/gkeyfile.c" + line="1091">a relative path to a filename to open and parse %NULL-terminated array of directories to search + filename="glib/gkeyfile.c" + line="1092">`NULL`-terminated + array of directories to search @@ -18807,15 +20017,15 @@ file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a optional="1" allow-none="1"> return location for a string containing the full path - of the file, or %NULL + filename="glib/gkeyfile.c" + line="1094">return location for a string + containing the full path of the file, or `NULL` to ignore flags from #GKeyFileFlags + filename="glib/gkeyfile.c" + line="1096">flags from [flags@GLib.KeyFileFlags] @@ -18825,39 +20035,39 @@ file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a version="2.6" throws="1"> Loads a key file into an empty #GKeyFile structure. + filename="glib/gkeyfile.c" + line="928">Loads a key file into an empty [struct@GLib.KeyFile] structure. If the OS returns an error when opening or reading the file, a -%G_FILE_ERROR is returned. If there is a problem parsing the file, a -%G_KEY_FILE_ERROR is returned. +[error@GLib.FileError] is returned. If there is a problem parsing the file, +a [error@GLib.KeyFileError] is returned. -This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the -@file is not found, %G_FILE_ERROR_NOENT is returned. - +This function will never return a [error@GLib.KeyFileError.NOT_FOUND] +error. If the @file is not found, [error@GLib.FileError.NOENT] is returned. + %TRUE if a key file could be loaded, %FALSE otherwise + filename="glib/gkeyfile.c" + line="944">true if a key file could be loaded, false otherwise an empty #GKeyFile struct + filename="glib/gkeyfile.c" + line="930">an empty key file the path of a filename to load, in the GLib filename encoding + filename="glib/gkeyfile.c" + line="931">the path of a filename to load, in the GLib filename encoding flags from #GKeyFileFlags + filename="glib/gkeyfile.c" + line="932">flags from [flags@GLib.KeyFileFlags] @@ -18867,20 +20077,20 @@ This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the version="2.32" introspectable="0"> Increases the reference count of @key_file. - + filename="glib/gkeyfile.c" + line="1227">Increases the reference count of @key_file. + the same @key_file. + filename="glib/gkeyfile.c" + line="1233">the same @key_file. a #GKeyFile + filename="glib/gkeyfile.c" + line="1229">a key file @@ -18890,23 +20100,24 @@ This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the version="2.6" throws="1"> Removes a comment above @key from @group_name. -If @key is %NULL then @comment will be removed above @group_name. -If both @key and @group_name are %NULL, then @comment will + filename="glib/gkeyfile.c" + line="3843">Removes a comment above @key from @group_name. + +If @key is `NULL` then @comment will be removed above @group_name. +If both @key and @group_name are `NULL`, then @comment will be removed above the first group in the file. - + %TRUE if the comment was removed, %FALSE otherwise + filename="glib/gkeyfile.c" + line="3856">true if the comment was removed, false otherwise a #GKeyFile + filename="glib/gkeyfile.c" + line="3845">a key file nullable="1" allow-none="1"> a group name, or %NULL + filename="glib/gkeyfile.c" + line="3846">a group name, or `NULL` to get a top-level comment nullable="1" allow-none="1"> a key + filename="glib/gkeyfile.c" + line="3847">a key, or `NULL` to get a group comment @@ -18934,27 +20145,27 @@ be removed above the first group in the file. version="2.6" throws="1"> Removes the specified group, @group_name, + filename="glib/gkeyfile.c" + line="4141">Removes the specified group, @group_name, from the key file. - + %TRUE if the group was removed, %FALSE otherwise + filename="glib/gkeyfile.c" + line="4150">true if the group was removed, false otherwise a #GKeyFile + filename="glib/gkeyfile.c" + line="4143">a key file a group name + filename="glib/gkeyfile.c" + line="4144">a group name @@ -18964,32 +20175,32 @@ from the key file. version="2.6" throws="1"> Removes @key in @group_name from the key file. - + filename="glib/gkeyfile.c" + line="4211">Removes @key in @group_name from the key file. + %TRUE if the key was removed, %FALSE otherwise + filename="glib/gkeyfile.c" + line="4220">true if the key was removed, false otherwise a #GKeyFile + filename="glib/gkeyfile.c" + line="4213">a key file a group name + filename="glib/gkeyfile.c" + line="4214">a group name a key name to remove + filename="glib/gkeyfile.c" + line="4215">a key name to remove @@ -18999,32 +20210,35 @@ from the key file. version="2.40" throws="1"> Writes the contents of @key_file to @filename using -g_file_set_contents(). If you need stricter guarantees about durability of -the written file than are provided by g_file_set_contents(), use -g_file_set_contents_full() with the return value of g_key_file_to_data(). + filename="glib/gkeyfile.c" + line="4831">Writes the contents of @key_file to @filename using +[func@GLib.file_set_contents]. + +If you need stricter guarantees about durability of +the written file than are provided by [func@GLib.file_set_contents], use +[func@GLib.file_set_contents_full] with the return value of +[method@GLib.KeyFile.to_data]. This function can fail for any of the reasons that -g_file_set_contents() may fail. - +[func@GLib.file_set_contents] may fail. + %TRUE if successful, else %FALSE with @error set + filename="glib/gkeyfile.c" + line="4848">true if successful, false otherwise a #GKeyFile + filename="glib/gkeyfile.c" + line="4833">a key file the name of the file to write to + filename="glib/gkeyfile.c" + line="4834">the name of the file to write to @@ -19033,36 +20247,37 @@ g_file_set_contents() may fail. c:identifier="g_key_file_set_boolean" version="2.6"> Associates a new boolean value with @key under @group_name. + filename="glib/gkeyfile.c" + line="2692">Associates a new boolean value with @key under @group_name. + If @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="2694">a key file a group name + filename="glib/gkeyfile.c" + line="2695">a group name a key + filename="glib/gkeyfile.c" + line="2696">a key %TRUE or %FALSE + filename="glib/gkeyfile.c" + line="2697">true or false @@ -19071,45 +20286,45 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_boolean_list" version="2.6"> Associates a list of boolean values with @key under @group_name. -If @key cannot be found then it is created. -If @group_name is %NULL, the start_group is used. - + filename="glib/gkeyfile.c" + line="2796">Associates a list of boolean values with @key under @group_name. + +If @key cannot be found then it is created. + a #GKeyFile + filename="glib/gkeyfile.c" + line="2798">a key file a group name + filename="glib/gkeyfile.c" + line="2799">a group name a key + filename="glib/gkeyfile.c" + line="2800">a key an array of boolean values + filename="glib/gkeyfile.c" + line="2801">an array of boolean values length of @list + filename="glib/gkeyfile.c" + line="2802">length of @list @@ -19119,27 +20334,27 @@ If @group_name is %NULL, the start_group is used. version="2.6" throws="1"> Places a comment above @key from @group_name. + filename="glib/gkeyfile.c" + line="3579">Places a comment above @key from @group_name. -If @key is %NULL then @comment will be written above @group_name. -If both @key and @group_name are %NULL, then @comment will be +If @key is `NULL` then @comment will be written above @group_name. +If both @key and @group_name are `NULL`, then @comment will be written above the first group in the file. -Note that this function prepends a '#' comment marker to +Note that this function prepends a `#` comment marker to each line of @comment. - + %TRUE if the comment was written, %FALSE otherwise + filename="glib/gkeyfile.c" + line="3596">true if the comment was written, false otherwise a #GKeyFile + filename="glib/gkeyfile.c" + line="3581">a key file nullable="1" allow-none="1"> a group name, or %NULL + filename="glib/gkeyfile.c" + line="3582">a group name, or `NULL` to write a top-level comment nullable="1" allow-none="1"> a key + filename="glib/gkeyfile.c" + line="3583">a key, or `NULL` to write a group comment a comment + filename="glib/gkeyfile.c" + line="3584">a comment @@ -19172,36 +20387,37 @@ each line of @comment. c:identifier="g_key_file_set_double" version="2.12"> Associates a new double value with @key under @group_name. + filename="glib/gkeyfile.c" + line="3280">Associates a new double value with @key under @group_name. + If @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="3282">a key file a group name + filename="glib/gkeyfile.c" + line="3283">a group name a key + filename="glib/gkeyfile.c" + line="3284">a key a double value + filename="glib/gkeyfile.c" + line="3285">a double value @@ -19210,44 +20426,45 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_double_list" version="2.12"> Associates a list of double values with @key under -@group_name. If @key cannot be found then it is created. - + filename="glib/gkeyfile.c" + line="3382">Associates a list of double values with @key under @group_name. + +If @key cannot be found then it is created. + a #GKeyFile + filename="glib/gkeyfile.c" + line="3384">a key file a group name + filename="glib/gkeyfile.c" + line="3385">a group name a key + filename="glib/gkeyfile.c" + line="3386">a key an array of double values + filename="glib/gkeyfile.c" + line="3387">an array of double values number of double values in @list + filename="glib/gkeyfile.c" + line="3388">number of double values in @list @@ -19256,36 +20473,37 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_int64" version="2.26"> Associates a new integer value with @key under @group_name. + filename="glib/gkeyfile.c" + line="2986">Associates a new integer value with @key under @group_name. + If @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="2988">a key file a group name + filename="glib/gkeyfile.c" + line="2989">a group name a key + filename="glib/gkeyfile.c" + line="2990">a key an integer value + filename="glib/gkeyfile.c" + line="2991">an integer value @@ -19294,36 +20512,37 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_integer" version="2.6"> Associates a new integer value with @key under @group_name. + filename="glib/gkeyfile.c" + line="2906">Associates a new integer value with @key under @group_name. + If @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="2908">a key file a group name + filename="glib/gkeyfile.c" + line="2909">a group name a key + filename="glib/gkeyfile.c" + line="2910">a key an integer value + filename="glib/gkeyfile.c" + line="2911">an integer value @@ -19332,44 +20551,45 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_integer_list" version="2.6"> Associates a list of integer values with @key under @group_name. + filename="glib/gkeyfile.c" + line="3170">Associates a list of integer values with @key under @group_name. + If @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="3172">a key file a group name + filename="glib/gkeyfile.c" + line="3173">a group name a key + filename="glib/gkeyfile.c" + line="3174">a key an array of integer values + filename="glib/gkeyfile.c" + line="3175">an array of integer values number of integer values in @list + filename="glib/gkeyfile.c" + line="3176">number of integer values in @list @@ -19378,25 +20598,26 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_list_separator" version="2.6"> Sets the character which is used to separate -values in lists. Typically ';' or ',' are used -as separators. The default list separator is ';'. - + filename="glib/gkeyfile.c" + line="731">Sets the character which is used to separate values in lists. + +Typically `;` or `,` are used as separators. The default list separator +is `;`. + a #GKeyFile + filename="glib/gkeyfile.c" + line="733">a key file the separator + filename="glib/gkeyfile.c" + line="734">the separator @@ -19405,95 +20626,102 @@ as separators. The default list separator is ';'. c:identifier="g_key_file_set_locale_string" version="2.6"> Associates a string value for @key and @locale under @group_name. + filename="glib/gkeyfile.c" + line="2235">Associates a string value for @key and @locale under @group_name. + +If the translation for @key cannot be found then it is created. + +If @locale is `C` then the untranslated value is set (since GLib 2.84). + + + + + + + a key file + + + + a group name + + + + a key + + + + a locale identifier + + + + a string + + + + + + Associates a list of string values for @key and @locale under +@group_name. + +If @locale is `C` then the untranslated value is set (since GLib 2.84). + If the translation for @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="2575">a key file a group name + filename="glib/gkeyfile.c" + line="2576">a group name a key + filename="glib/gkeyfile.c" + line="2577">a key a locale identifier - - - - a string - - - - - - Associates a list of string values for @key and @locale under -@group_name. If the translation for @key cannot be found then -it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a locale identifier + filename="glib/gkeyfile.c" + line="2578">a locale identifier a %NULL-terminated array of locale string values + filename="glib/gkeyfile.c" + line="2579">a `NULL`-terminated array of + locale string values the length of @list + filename="glib/gkeyfile.c" + line="2581">the length of @list @@ -19502,39 +20730,40 @@ it is created. c:identifier="g_key_file_set_string" version="2.6"> Associates a new string value with @key under @group_name. + filename="glib/gkeyfile.c" + line="2059">Associates a new string value with @key under @group_name. + If @key cannot be found then it is created. If @group_name cannot be found then it is created. -Unlike g_key_file_set_value(), this function handles characters +Unlike [method@GLib.KeyFile.set_value], this function handles characters that need escaping, such as newlines. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="2061">a key file a group name + filename="glib/gkeyfile.c" + line="2062">a group name a key + filename="glib/gkeyfile.c" + line="2063">a key a string + filename="glib/gkeyfile.c" + line="2064">a string @@ -19543,45 +20772,47 @@ that need escaping, such as newlines. c:identifier="g_key_file_set_string_list" version="2.6"> Associates a list of string values for @key under @group_name. + filename="glib/gkeyfile.c" + line="2190">Associates a list of string values for @key under @group_name. + If @key cannot be found then it is created. If @group_name cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="2192">a key file a group name + filename="glib/gkeyfile.c" + line="2193">a group name a key + filename="glib/gkeyfile.c" + line="2194">a key an array of string values + filename="glib/gkeyfile.c" + line="2195">an array + of string values number of string values in @list + filename="glib/gkeyfile.c" + line="2197">number of string values in @list @@ -19590,36 +20821,37 @@ If @group_name cannot be found then it is created. c:identifier="g_key_file_set_uint64" version="2.26"> Associates a new integer value with @key under @group_name. + filename="glib/gkeyfile.c" + line="3066">Associates a new integer value with @key under @group_name. + If @key cannot be found then it is created. - + a #GKeyFile + filename="glib/gkeyfile.c" + line="3068">a key file a group name + filename="glib/gkeyfile.c" + line="3069">a group name a key + filename="glib/gkeyfile.c" + line="3070">a key an integer value + filename="glib/gkeyfile.c" + line="3071">an integer value @@ -19628,40 +20860,40 @@ If @key cannot be found then it is created. c:identifier="g_key_file_set_value" version="2.6"> Associates a new value with @key under @group_name. + filename="glib/gkeyfile.c" + line="1925">Associates a new value with @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use -g_key_file_set_string(). - +[method@GLib.KeyFile.set_string]. + a #GKeyFile + filename="glib/gkeyfile.c" + line="1927">a key file a group name + filename="glib/gkeyfile.c" + line="1928">a group name a key + filename="glib/gkeyfile.c" + line="1929">a key a string + filename="glib/gkeyfile.c" + line="1930">a string @@ -19671,24 +20903,22 @@ g_key_file_set_string(). version="2.6" throws="1"> This function outputs @key_file as a string. + filename="glib/gkeyfile.c" + line="1638">Outputs @key_file as a string. -Note that this function never reports an error, -so it is safe to pass %NULL as @error. - +Note that this function never reports an error. + a newly allocated string holding - the contents of the #GKeyFile + filename="glib/gkeyfile.c" + line="1649">a newly allocated string holding the contents of the key file a #GKeyFile + filename="glib/gkeyfile.c" + line="1640">a key file optional="1" allow-none="1"> return location for the length of the - returned string, or %NULL + filename="glib/gkeyfile.c" + line="1641">return location for the length of the + returned string, or `NULL` to ignore Decreases the reference count of @key_file by 1. If the reference count -reaches zero, frees the key file and all its allocated memory. - + filename="glib/gkeyfile.c" + line="1272">Decreases the reference count of @key_file by 1. + +If the reference count reaches zero, frees the key file and all its allocated +memory. + - + a #GKeyFile + filename="glib/gkeyfile.c" + line="1274">a key file @@ -19733,67 +20965,67 @@ reaches zero, frees the key file and all its allocated memory. c:type="GKeyFileError" glib:error-domain="g-key-file-error-quark"> Error codes returned by key file parsing. - + filename="glib/gkeyfile.c" + line="224">Error codes returned by key file parsing. + the text being parsed was in + filename="glib/gkeyfile.c" + line="226">the text being parsed was in an unknown encoding document was ill-formed + filename="glib/gkeyfile.c" + line="228">document was ill-formed the file was not found + filename="glib/gkeyfile.c" + line="229">the file was not found a requested key was not found + filename="glib/gkeyfile.c" + line="230">a requested key was not found a requested group was not found + filename="glib/gkeyfile.c" + line="231">a requested group was not found a value could not be parsed + filename="glib/gkeyfile.c" + line="232">a value could not be parsed Flags which influence the parsing. - + filename="glib/gkeyfile.c" + line="237">Flags which influence the parsing. + No flags, default behaviour + filename="glib/gkeyfile.c" + line="239">No flags, default behaviour Use this flag if you plan to write the + filename="glib/gkeyfile.c" + line="240">Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise all comments will be lost when the key file is written back. @@ -19802,8 +21034,8 @@ reaches zero, frees the key file and all its allocated memory. value="2" c:identifier="G_KEY_FILE_KEEP_TRANSLATIONS"> Use this flag if you plan to write the + filename="glib/gkeyfile.c" + line="244">Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise only the translations for the current language will be written back. @@ -19814,56 +21046,56 @@ reaches zero, frees the key file and all its allocated memory. version="2.2" introspectable="0"> Hints the compiler that the expression is likely to evaluate to + filename="glib/docs.c" + line="1460">Hints the compiler that the expression is likely to evaluate to a true value. The compiler may use this information for optimizations. |[<!-- language="C" --> if (G_LIKELY (random () != 1)) g_print ("not one"); ]| - + the expression + filename="glib/docs.c" + line="1462">the expression Specifies one of the possible types of byte order. + filename="glib/docs.c" + line="109">Specifies one of the possible types of byte order. See %G_BYTE_ORDER. - + The natural logarithm of 10. - + filename="glib/docs.c" + line="817">The natural logarithm of 10. + The natural logarithm of 2. - + filename="glib/docs.c" + line="811">The natural logarithm of 2. + Works like g_mutex_lock(), but for a lock defined with + filename="glib/gthread.c" + line="176">Works like g_mutex_lock(), but for a lock defined with %G_LOCK_DEFINE. - + the name of the lock + filename="glib/gthread.c" + line="178">the name of the lock @@ -19871,8 +21103,8 @@ See %G_BYTE_ORDER. c:identifier="G_LOCK_DEFINE" introspectable="0"> The `G_LOCK_` macros provide a convenient interface to #GMutex. + filename="glib/gthread.c" + line="128">The `G_LOCK_` macros provide a convenient interface to #GMutex. %G_LOCK_DEFINE defines a lock. It can appear in any place where variable definitions may appear in programs, i.e. in the first block of a function or outside of functions. The @name parameter will be @@ -19899,12 +21131,12 @@ Here is an example for using the `G_LOCK` convenience macros: return ret_val; } ]| - + the name of the lock + filename="glib/gthread.c" + line="130">the name of the lock @@ -19912,14 +21144,14 @@ Here is an example for using the `G_LOCK` convenience macros: c:identifier="G_LOCK_DEFINE_STATIC" introspectable="0"> This works like %G_LOCK_DEFINE, but it creates a static object. - + filename="glib/gthread.c" + line="161">This works like %G_LOCK_DEFINE, but it creates a static object. + the name of the lock + filename="glib/gthread.c" + line="163">the name of the lock @@ -19927,22 +21159,22 @@ Here is an example for using the `G_LOCK` convenience macros: c:identifier="G_LOCK_EXTERN" introspectable="0"> This declares a lock, that is defined with %G_LOCK_DEFINE in another + filename="glib/gthread.c" + line="168">This declares a lock, that is defined with %G_LOCK_DEFINE in another module. - + the name of the lock + filename="glib/gthread.c" + line="170">the name of the lock - + @@ -19950,15 +21182,15 @@ module. Multiplying the base 2 exponent by this number yields the base 10 exponent. - + filename="glib/docs.c" + line="847">Multiplying the base 2 exponent by this number yields the base 10 exponent. + Defines the log domain. See [Log Domains](#log-domains). + filename="glib/gmessages.c" + line="91">Defines the log domain. See [Log Domains](#log-domains). Libraries should define this so that any messages which they log can be differentiated from messages from other @@ -19981,69 +21213,69 @@ AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" Applications can choose to leave it as the default %NULL (or `""`) domain. However, defining the domain offers the same advantages as above. - + GLib log levels that are considered fatal by default. + filename="glib/gmessages.c" + line="121">GLib log levels that are considered fatal by default. This is not used if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - +[Using Structured Logging](logging.html#using-structured-logging). + Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. + filename="glib/gmessages.c" + line="174">Log levels below `1<<G_LOG_LEVEL_USER_SHIFT` are used by GLib. Higher bits can be used for user-defined log levels. - + The #GList struct is used for each element in a doubly-linked list. - + filename="glib/glist.c" + line="39">The #GList struct is used for each element in a doubly-linked list. + holds the element's data, which can be a pointer to any kind + filename="glib/glist.c" + line="41">holds the element's data, which can be a pointer to any kind of data, or any integer value using the - [Type Conversion Macros][glib-Type-Conversion-Macros] + [Type Conversion Macros](conversion-macros.html#conversion-macros) contains the link to the next element in the list + filename="glib/glist.c" + line="44">contains the link to the next element in the list contains the link to the previous element in the list + filename="glib/glist.c" + line="45">contains the link to the previous element in the list Allocates space for one #GList element. It is called by + filename="glib/glist.c" + line="77">Allocates space for one #GList element. It is called by g_list_append(), g_list_prepend(), g_list_insert() and g_list_insert_sorted() and so is rarely used on its own. - + a pointer to the newly-allocated #GList element + filename="glib/glist.c" + line="84">a pointer to the newly-allocated #GList element @@ -20051,8 +21283,8 @@ g_list_insert_sorted() and so is rarely used on its own. Adds a new element on to the end of the list. + filename="glib/glist.c" + line="166">Adds a new element on to the end of the list. Note that the return value is the new start of the list, if @list was empty; make sure you store the new value. @@ -20074,11 +21306,11 @@ string_list = g_list_append (string_list, "second"); number_list = g_list_append (number_list, GINT_TO_POINTER (27)); number_list = g_list_append (number_list, GINT_TO_POINTER (14)); ]| - + either @list or the new start of the #GList if @list was %NULL + filename="glib/glist.c" + line="194">either @list or the new start of the #GList if @list was %NULL @@ -20086,8 +21318,8 @@ number_list = g_list_append (number_list, GINT_TO_POINTER (14)); a pointer to a #GList + filename="glib/glist.c" + line="168">a pointer to a #GList @@ -20097,16 +21329,16 @@ number_list = g_list_append (number_list, GINT_TO_POINTER (14)); nullable="1" allow-none="1"> the data for the new element + filename="glib/glist.c" + line="169">the data for the new element Adds the second #GList onto the end of the first #GList. + filename="glib/glist.c" + line="425">Adds the second #GList onto the end of the first #GList. Note that the elements of the second #GList are not copied. They are used directly. @@ -20116,11 +21348,11 @@ The following example moves an element to the top of the list: list = g_list_remove_link (list, llink); list = g_list_concat (llink, list); ]| - + the start of the new #GList, which equals @list1 if not %NULL + filename="glib/glist.c" + line="442">the start of the new #GList, which equals @list1 if not %NULL @@ -20128,16 +21360,16 @@ list = g_list_concat (llink, list); a #GList, this must point to the top of the list + filename="glib/glist.c" + line="427">a #GList, this must point to the top of the list the #GList to add to the end of the first #GList, + filename="glib/glist.c" + line="428">the #GList to add to the end of the first #GList, this must point to the top of the list @@ -20147,18 +21379,18 @@ list = g_list_concat (llink, list); Copies a #GList. + filename="glib/glist.c" + line="615">Copies a #GList. Note that this is a "shallow" copy. If the list elements consist of pointers to data, the pointers are copied but the actual data is not. See g_list_copy_deep() if you need to copy the data as well. - + the start of the new list that holds the same data as @list + filename="glib/glist.c" + line="626">the start of the new list that holds the same data as @list @@ -20166,8 +21398,8 @@ to copy the data as well. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="617">a #GList, this must point to the top of the list @@ -20179,8 +21411,8 @@ to copy the data as well. version="2.34" introspectable="0"> Makes a full (deep) copy of a #GList. + filename="glib/glist.c" + line="634">Makes a full (deep) copy of a #GList. In contrast with g_list_copy(), this function uses @func to make a copy of each list element, in addition to copying the list @@ -20201,11 +21433,11 @@ And, to entirely free the new list, you could do: |[<!-- language="C" --> g_list_free_full (another_list, g_object_unref); ]| - + the start of the new list that holds a full copy of @list, + filename="glib/glist.c" + line="662">the start of the new list that holds a full copy of @list, use g_list_free_full() to free it @@ -20214,16 +21446,19 @@ g_list_free_full (another_list, g_object_unref); a #GList, this must point to the top of the list + filename="glib/glist.c" + line="636">a #GList, this must point to the top of the list - + a copy function used to copy every element in the list + filename="glib/glist.c" + line="637">a copy function used to copy every element in the list user data passed to the copy function @func, or %NULL + filename="glib/glist.c" + line="638">user data passed to the copy function @func, or %NULL @@ -20241,15 +21476,15 @@ g_list_free_full (another_list, g_object_unref); c:identifier="g_list_delete_link" introspectable="0"> Removes the node link_ from the list and frees it. + filename="glib/glist.c" + line="594">Removes the node link_ from the list and frees it. Compare this to g_list_remove_link() which removes the node without freeing it. - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="603">the (possibly changed) start of the #GList @@ -20257,16 +21492,16 @@ without freeing it. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="596">a #GList, this must point to the top of the list node to delete from @list + filename="glib/glist.c" + line="597">node to delete from @list @@ -20275,13 +21510,13 @@ without freeing it. Finds the element in a #GList which contains the given data. - + filename="glib/glist.c" + line="797">Finds the element in a #GList which contains the given data. + the found #GList element, or %NULL if it is not found + filename="glib/glist.c" + line="804">the found #GList element, or %NULL if it is not found @@ -20289,8 +21524,8 @@ without freeing it. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="799">a #GList, this must point to the top of the list @@ -20300,8 +21535,8 @@ without freeing it. nullable="1" allow-none="1"> the element data to find + filename="glib/glist.c" + line="800">the element data to find @@ -20310,18 +21545,18 @@ without freeing it. c:identifier="g_list_find_custom" introspectable="0"> Finds an element in a #GList, using a supplied function to + filename="glib/glist.c" + line="820">Finds an element in a #GList, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two #gconstpointer arguments, the #GList element's data as the first argument and the given user data. - + the found #GList element, or %NULL if it is not found + filename="glib/glist.c" + line="834">the found #GList element, or %NULL if it is not found @@ -20329,8 +21564,8 @@ given user data. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="822">a #GList, this must point to the top of the list @@ -20340,14 +21575,14 @@ given user data. nullable="1" allow-none="1"> user data passed to the function + filename="glib/glist.c" + line="823">user data passed to the function - + the function to call for each element. + filename="glib/glist.c" + line="824">the function to call for each element. It should return 0 when the desired element is found @@ -20355,13 +21590,13 @@ given user data. Gets the first element in a #GList. - + filename="glib/glist.c" + line="932">Gets the first element in a #GList. + the first element in the #GList, + filename="glib/glist.c" + line="938">the first element in the #GList, or %NULL if the #GList has no elements @@ -20370,8 +21605,8 @@ given user data. any #GList element + filename="glib/glist.c" + line="934">any #GList element @@ -20382,28 +21617,31 @@ given user data. c:identifier="g_list_foreach" introspectable="0"> Calls a function for each element of a #GList. + filename="glib/glist.c" + line="981">Calls a function for each element of a #GList. It is safe for @func to remove the element from @list, but it must not modify any part of the list after that element. - + a #GList, this must point to the top of the list + filename="glib/glist.c" + line="983">a #GList, this must point to the top of the list - + the function to call with each element's data + filename="glib/glist.c" + line="984">the function to call with each element's data nullable="1" allow-none="1"> user data to pass to the function + filename="glib/glist.c" + line="985">user data to pass to the function Frees all of the memory used by a #GList. + filename="glib/glist.c" + line="92">Frees all of the memory used by a #GList. The freed elements are returned to the slice allocator. If list elements contain dynamically-allocated memory, you should @@ -20432,15 +21670,15 @@ is not left dangling: GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ g_list_free (g_steal_pointer (&list_of_borrowed_things)); ]| - + the first link of a #GList + filename="glib/glist.c" + line="94">the first link of a #GList @@ -20449,21 +21687,21 @@ g_list_free (g_steal_pointer (&list_of_borrowed_things)); Frees one #GList element, but does not update links from the next and + filename="glib/glist.c" + line="115">Frees one #GList element, but does not update links from the next and previous elements in the list, so you should not call this function on an element that is currently part of a list. It is usually used after g_list_remove_link(). - + a #GList element + filename="glib/glist.c" + line="117">a #GList element @@ -20475,8 +21713,8 @@ It is usually used after g_list_remove_link(). version="2.28" introspectable="0"> Convenience method, which frees all the memory used by a #GList, + filename="glib/glist.c" + line="136">Convenience method, which frees all the memory used by a #GList, and calls @free_func on every element's data. @free_func must not modify the list (eg, by removing the freed @@ -20490,45 +21728,45 @@ from @free_func: GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); ]| - + the first link of a #GList + filename="glib/glist.c" + line="138">the first link of a #GList the function to be called to free each element's data + filename="glib/glist.c" + line="139">the function to be called to free each element's data Gets the position of the element containing + filename="glib/glist.c" + line="882">Gets the position of the element containing the given data (starting from 0). - + the index of the element containing the data, + filename="glib/glist.c" + line="890">the index of the element containing the data, or -1 if the data is not found a #GList, this must point to the top of the list + filename="glib/glist.c" + line="884">a #GList, this must point to the top of the list @@ -20538,21 +21776,21 @@ the given data (starting from 0). nullable="1" allow-none="1"> the data to find + filename="glib/glist.c" + line="885">the data to find Inserts a new element into the list at the given position. - + filename="glib/glist.c" + line="270">Inserts a new element into the list at the given position. + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="280">the (possibly changed) start of the #GList @@ -20560,8 +21798,8 @@ the given data (starting from 0). a pointer to a #GList, this must point to the top of the list + filename="glib/glist.c" + line="272">a pointer to a #GList, this must point to the top of the list @@ -20571,14 +21809,14 @@ the given data (starting from 0). nullable="1" allow-none="1"> the data for the new element + filename="glib/glist.c" + line="273">the data for the new element the position to insert the element. If this is + filename="glib/glist.c" + line="274">the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. @@ -20589,13 +21827,13 @@ the given data (starting from 0). c:identifier="g_list_insert_before" introspectable="0"> Inserts a new element into the list before the given position. - + filename="glib/glist.c" + line="367">Inserts a new element into the list before the given position. + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="376">the (possibly changed) start of the #GList @@ -20603,16 +21841,16 @@ the given data (starting from 0). a pointer to a #GList, this must point to the top of the list + filename="glib/glist.c" + line="369">a pointer to a #GList, this must point to the top of the list the list element before which the new element + filename="glib/glist.c" + line="370">the list element before which the new element is inserted or %NULL to insert at the end of the list @@ -20623,8 +21861,8 @@ the given data (starting from 0). nullable="1" allow-none="1"> the data for the new element + filename="glib/glist.c" + line="372">the data for the new element @@ -20634,13 +21872,13 @@ the given data (starting from 0). version="2.62" introspectable="0"> Inserts @link_ into the list before the given position. - + filename="glib/glist.c" + line="309">Inserts @link_ into the list before the given position. + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="319">the (possibly changed) start of the #GList @@ -20648,8 +21886,8 @@ the given data (starting from 0). a pointer to a #GList, this must point to the top of the list + filename="glib/glist.c" + line="311">a pointer to a #GList, this must point to the top of the list @@ -20659,8 +21897,8 @@ the given data (starting from 0). nullable="1" allow-none="1"> the list element before which the new element + filename="glib/glist.c" + line="312">the list element before which the new element is inserted or %NULL to insert at the end of the list @@ -20668,8 +21906,8 @@ the given data (starting from 0). the list element to be added, which must not be part of + filename="glib/glist.c" + line="314">the list element to be added, which must not be part of any other list @@ -20681,19 +21919,19 @@ the given data (starting from 0). c:identifier="g_list_insert_sorted" introspectable="0"> Inserts a new element into the list, using the given comparison + filename="glib/glist.c" + line="1065">Inserts a new element into the list, using the given comparison function to determine its position. If you are adding many new elements to a list, and the number of new elements is much larger than the length of the list, use g_list_prepend() to add the new items and sort the list afterwards with g_list_sort(). - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="1082">the (possibly changed) start of the #GList @@ -20701,8 +21939,8 @@ with g_list_sort(). a pointer to a #GList, this must point to the top of the + filename="glib/glist.c" + line="1067">a pointer to a #GList, this must point to the top of the already sorted list @@ -20713,14 +21951,14 @@ with g_list_sort(). nullable="1" allow-none="1"> the data for the new element + filename="glib/glist.c" + line="1069">the data for the new element - + the function to compare elements in the list. It should + filename="glib/glist.c" + line="1070">the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -20732,19 +21970,19 @@ with g_list_sort(). version="2.10" introspectable="0"> Inserts a new element into the list, using the given comparison + filename="glib/glist.c" + line="1092">Inserts a new element into the list, using the given comparison function to determine its position. If you are adding many new elements to a list, and the number of new elements is much larger than the length of the list, use g_list_prepend() to add the new items and sort the list afterwards with g_list_sort(). - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="1110">the (possibly changed) start of the #GList @@ -20752,8 +21990,8 @@ with g_list_sort(). a pointer to a #GList, this must point to the top of the + filename="glib/glist.c" + line="1094">a pointer to a #GList, this must point to the top of the already sorted list @@ -20764,14 +22002,17 @@ with g_list_sort(). nullable="1" allow-none="1"> the data for the new element + filename="glib/glist.c" + line="1096">the data for the new element - + the function to compare elements in the list. It should + filename="glib/glist.c" + line="1097">the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -20781,21 +22022,21 @@ with g_list_sort(). nullable="1" allow-none="1"> user data to pass to comparison function + filename="glib/glist.c" + line="1100">user data to pass to comparison function Gets the last element in a #GList. - + filename="glib/glist.c" + line="911">Gets the last element in a #GList. + the last element in the #GList, + filename="glib/glist.c" + line="917">the last element in the #GList, or %NULL if the #GList has no elements @@ -20804,8 +22045,8 @@ with g_list_sort(). any #GList element + filename="glib/glist.c" + line="913">any #GList element @@ -20814,25 +22055,25 @@ with g_list_sort(). Gets the number of elements in a #GList. + filename="glib/glist.c" + line="953">Gets the number of elements in a #GList. This function iterates over the whole list to count its elements. Use a #GQueue instead of a GList if you regularly need the number of items. To check whether the list is non-empty, it is faster to check @list against %NULL. - + the number of elements in the #GList + filename="glib/glist.c" + line="964">the number of elements in the #GList a #GList, this must point to the top of the list + filename="glib/glist.c" + line="955">a #GList, this must point to the top of the list @@ -20841,17 +22082,17 @@ of items. To check whether the list is non-empty, it is faster to check Gets the element at the given position in a #GList. + filename="glib/glist.c" + line="729">Gets the element at the given position in a #GList. This iterates over the list until it reaches the @n-th position. If you intend to iterate over every element, it is better to use a for-loop as described in the #GList introduction. - + the element, or %NULL if the position is off + filename="glib/glist.c" + line="740">the element, or %NULL if the position is off the end of the #GList @@ -20860,16 +22101,16 @@ described in the #GList introduction. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="731">a #GList, this must point to the top of the list the position of the element, counting from 0 + filename="glib/glist.c" + line="732">the position of the element, counting from 0 @@ -20878,33 +22119,33 @@ described in the #GList introduction. c:identifier="g_list_nth_data" introspectable="0"> Gets the data of the element at the given position. + filename="glib/glist.c" + line="773">Gets the data of the element at the given position. This iterates over the list until it reaches the @n-th position. If you intend to iterate over every element, it is better to use a for-loop as described in the #GList introduction. - + the element's data, or %NULL if the position + filename="glib/glist.c" + line="784">the element's data, or %NULL if the position is off the end of the #GList a #GList, this must point to the top of the list + filename="glib/glist.c" + line="775">a #GList, this must point to the top of the list the position of the element + filename="glib/glist.c" + line="776">the position of the element @@ -20913,13 +22154,13 @@ described in the #GList introduction. c:identifier="g_list_nth_prev" introspectable="0"> Gets the element @n places before @list. - + filename="glib/glist.c" + line="753">Gets the element @n places before @list. + the element, or %NULL if the position is + filename="glib/glist.c" + line="760">the element, or %NULL if the position is off the end of the #GList @@ -20928,48 +22169,54 @@ described in the #GList introduction. a #GList + filename="glib/glist.c" + line="755">a #GList the position of the element, counting from 0 + filename="glib/glist.c" + line="756">the position of the element, counting from 0 + + + + + + Gets the position of the given element + filename="glib/glist.c" + line="853">Gets the position of the given element in the #GList (starting from 0). - + the position of the element in the #GList, + filename="glib/glist.c" + line="861">the position of the element in the #GList, or -1 if the element is not found a #GList, this must point to the top of the list + filename="glib/glist.c" + line="855">a #GList, this must point to the top of the list an element in the #GList + filename="glib/glist.c" + line="856">an element in the #GList @@ -20980,8 +22227,8 @@ in the #GList (starting from 0). c:identifier="g_list_prepend" introspectable="0"> Prepends a new element on to the start of the list. + filename="glib/glist.c" + line="223">Prepends a new element on to the start of the list. Note that the return value is the new start of the list, which will have changed, so make sure you store the new value. @@ -20996,11 +22243,11 @@ list = g_list_prepend (list, "first"); Do not use this function to prepend a new element to a different element than the start of the list. Use g_list_insert_before() instead. - + a pointer to the newly prepended element, which is the new + filename="glib/glist.c" + line="244">a pointer to the newly prepended element, which is the new start of the #GList @@ -21009,8 +22256,8 @@ element than the start of the list. Use g_list_insert_before() instead. a pointer to a #GList, this must point to the top of the list + filename="glib/glist.c" + line="225">a pointer to a #GList, this must point to the top of the list @@ -21020,23 +22267,34 @@ element than the start of the list. Use g_list_insert_before() instead. nullable="1" allow-none="1"> the data for the new element + filename="glib/glist.c" + line="226">the data for the new element + + + + + + + + + + + Removes an element from a #GList. + filename="glib/glist.c" + line="494">Removes an element from a #GList. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the #GList is unchanged. - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="503">the (possibly changed) start of the #GList @@ -21044,8 +22302,8 @@ If none of the elements contain the data, the #GList is unchanged. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="496">a #GList, this must point to the top of the list @@ -21055,8 +22313,8 @@ If none of the elements contain the data, the #GList is unchanged. nullable="1" allow-none="1"> the data of the element to remove + filename="glib/glist.c" + line="497">the data of the element to remove @@ -21065,16 +22323,16 @@ If none of the elements contain the data, the #GList is unchanged. c:identifier="g_list_remove_all" introspectable="0"> Removes all list nodes with data equal to @data. + filename="glib/glist.c" + line="527">Removes all list nodes with data equal to @data. Returns the new head of the list. Contrast with g_list_remove() which removes only the first node matching the given data. - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="537">the (possibly changed) start of the #GList @@ -21082,8 +22340,8 @@ matching the given data. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="529">a #GList, this must point to the top of the list @@ -21093,8 +22351,8 @@ matching the given data. nullable="1" allow-none="1"> data to remove + filename="glib/glist.c" + line="530">data to remove @@ -21103,8 +22361,8 @@ matching the given data. c:identifier="g_list_remove_link" introspectable="0"> Removes an element from a #GList, without freeing the element. + filename="glib/glist.c" + line="567">Removes an element from a #GList, without freeing the element. The removed element's prev and next links are set to %NULL, so that it becomes a self-contained list with one element. @@ -21116,11 +22374,11 @@ list = g_list_remove_link (list, llink); free_some_data_that_may_access_the_list_again (llink->data); g_list_free (llink); ]| - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="585">the (possibly changed) start of the #GList @@ -21128,16 +22386,16 @@ g_list_free (llink); a #GList, this must point to the top of the list + filename="glib/glist.c" + line="569">a #GList, this must point to the top of the list an element in the #GList + filename="glib/glist.c" + line="570">an element in the #GList @@ -21148,14 +22406,14 @@ g_list_free (llink); c:identifier="g_list_reverse" introspectable="0"> Reverses a #GList. + filename="glib/glist.c" + line="703">Reverses a #GList. It simply switches the next and prev pointers of each element. - + the start of the reversed #GList + filename="glib/glist.c" + line="710">the start of the reversed #GList @@ -21163,8 +22421,8 @@ It simply switches the next and prev pointers of each element. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="705">a #GList, this must point to the top of the list @@ -21173,14 +22431,14 @@ It simply switches the next and prev pointers of each element. Sorts a #GList using the given comparison function. The algorithm + filename="glib/glist.c" + line="1189">Sorts a #GList using the given comparison function. The algorithm used is a stable sort. - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="1201">the (possibly changed) start of the #GList @@ -21188,16 +22446,18 @@ used is a stable sort. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="1191">a #GList, this must point to the top of the list - + the comparison function used to sort the #GList. + filename="glib/glist.c" + line="1192">the comparison function used to sort the #GList. This function is passed the data from 2 elements of the #GList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if @@ -21210,14 +22470,14 @@ used is a stable sort. c:identifier="g_list_sort_with_data" introspectable="0"> Like g_list_sort(), but the comparison function accepts + filename="glib/glist.c" + line="1223">Like g_list_sort(), but the comparison function accepts a user data argument. - + the (possibly changed) start of the #GList + filename="glib/glist.c" + line="1232">the (possibly changed) start of the #GList @@ -21225,16 +22485,19 @@ a user data argument. a #GList, this must point to the top of the list + filename="glib/glist.c" + line="1225">a #GList, this must point to the top of the list - + comparison function + filename="glib/glist.c" + line="1226">comparison function nullable="1" allow-none="1"> user data to pass to comparison function + filename="glib/glist.c" + line="1227">user data to pass to comparison function @@ -21251,7 +22514,7 @@ a user data argument. Structure representing a single field in a structured log entry. See g_log_structured() for details. @@ -21259,61 +22522,67 @@ Log fields may contain arbitrary values, including binary with embedded nul bytes. If the field contains a string, the string must be UTF-8 encoded and have a trailing nul byte. Otherwise, @length must be set to a non-negative value. - + field name (UTF-8 string) field value (arbitrary bytes) length of @value, in bytes, or -1 if it is nul-terminated Specifies the prototype of log handler functions. + filename="glib/gmessages.c" + line="130">Specifies the prototype of log handler functions. -The default log handler, g_log_default_handler(), automatically appends a +The default log handler, [func@GLib.log_default_handler], automatically appends a new-line character to @message when printing it. It is advised that any custom log handler functions behave similarly, so that logging calls in user code do not need modifying to add a new-line character to the message if the log handler is changed. +The `log_domain` parameter can be set to `NULL` or an empty string to use the default +application domain. + This is not used if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - +[Using Structured Logging](logging.html#using-structured-logging). + - + the log domain of the message + filename="glib/gmessages.c" + line="132">the log domain of the message the log level of the message (including the - fatal and recursion flags) + filename="glib/gmessages.c" + line="133">the log level of the message (including the + fatal and recursion flags) the message to process + filename="glib/gmessages.c" + line="135">the message to process user data, set in g_log_set_handler() + filename="glib/gmessages.c" + line="136">user data, set in [func@GLib.log_set_handler] Flags specifying the level of log messages. + filename="glib/gmessages.c" + line="153">Flags specifying the level of log messages. It is possible to change how GLib treats messages of the various -levels using g_log_set_handler() and g_log_set_fatal_mask(). - +levels using [func@GLib.log_set_handler] and [func@GLib.log_set_fatal_mask]. + internal flag + filename="glib/gmessages.c" + line="155">internal flag internal flag + filename="glib/gmessages.c" + line="156">internal flag log level for errors, see g_error(). - This level is also used for messages produced by g_assert(). + filename="glib/gmessages.c" + line="157">log level for errors, see [func@GLib.error]. + This level is also used for messages produced by [func@GLib.assert]. log level for critical warning messages, see - g_critical(). - This level is also used for messages produced by g_return_if_fail() - and g_return_val_if_fail(). + filename="glib/gmessages.c" + line="159">log level for critical warning messages, see + [func@GLib.critical]. This level is also used for messages produced by + [func@GLib.return_if_fail] and [func@GLib.return_val_if_fail]. log level for warnings, see g_warning() + filename="glib/gmessages.c" + line="162">log level for warnings, see [func@GLib.warning] log level for messages, see g_message() + filename="glib/gmessages.c" + line="163">log level for messages, see [func@GLib.message] log level for informational messages, see g_info() + filename="glib/gmessages.c" + line="164">log level for informational messages, see [func@GLib.info] log level for debug messages, see g_debug() + filename="glib/gmessages.c" + line="165">log level for debug messages, see [func@GLib.debug] a mask including all log levels + filename="glib/gmessages.c" + line="166">a mask including all log levels Writer function for log entries. A log entry is a collection of one or more #GLogFields, using the standard [field names from journal specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html). @@ -21415,10 +22683,10 @@ error handling the message (for example, if the writer function is meant to send messages to a remote logging server and there is a network error), it should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be chained and fall back to simpler handlers in case of failure. - + %G_LOG_WRITER_HANDLED if the log entry was handled successfully; %G_LOG_WRITER_UNHANDLED otherwise @@ -21426,13 +22694,13 @@ chained and fall back to simpler handlers in case of failure. log level of the message fields forming the message @@ -21440,7 +22708,7 @@ chained and fall back to simpler handlers in case of failure. number of @fields @@ -21450,7 +22718,7 @@ chained and fall back to simpler handlers in case of failure. allow-none="1" closure="3"> user data passed to g_log_set_writer_func() @@ -21460,140 +22728,86 @@ chained and fall back to simpler handlers in case of failure. version="2.50" c:type="GLogWriterOutput"> Return values from #GLogWriterFuncs to indicate whether the given log entry was successfully handled by the writer, or whether there was an error in handling it (and hence a fallback writer should be used). If a #GLogWriterFunc ignores a log entry, it should return %G_LOG_WRITER_HANDLED. - + Log writer has handled the log entry. Log writer could not handle the log entry. The major version number of the GLib library. + filename="glib/gversion.c" + line="40">The major version number of the GLib library. Like #glib_major_version, but from the headers used at application compile time, rather than from the library linked against at application run time. - + - - The maximum value which can be held in a #gint16. - -This is the same as standard C `INT16_MAX`, which should be -preferred in new code. - + + - - The maximum value which can be held in a #gint32. - -This is the same as standard C `INT32_MAX`, which should be -preferred in new code. - + + - The maximum value which can be held in a #gint64. - + - - The maximum value which can be held in a #gint8. - -This is the same as standard C `INT8_MAX`, which should be -preferred in new code. - + + - - The maximum value which can be held in a #guint16. - -This is the same as standard C `UINT16_MAX`, which should be -preferred in new code. - + + - - The maximum value which can be held in a #guint32. - -This is the same as standard C `UINT32_MAX`, which should be -preferred in new code. - + + - The maximum value which can be held in a #guint64. - -This is the same as standard C `UINT64_MAX`, which should be -preferred in new code. - + - - The maximum value which can be held in a #guint8. - -This is the same as standard C `UINT8_MAX`, which should be -preferred in new code. - + + - + The micro version number of the GLib library. + filename="glib/gversion.c" + line="78">The micro version number of the GLib library. Like #gtk_micro_version, but from the headers used at application compile time, rather than from the library linked against at application run time. - + The minimum value which can be held in a #gint16. - + c:type="G_MININT32" version="2.4"> The minimum value which can be held in a #gint32. - + The minimum value which can be held in a #gint64. - + The minimum value which can be held in a #gint8. - + - + The minor version number of the GLib library. + filename="glib/gversion.c" + line="59">The minor version number of the GLib library. Like #gtk_minor_version, but from the headers used at application compile time, rather than from the library linked against at application run time. - + - + + + Declare a [type@GLib.MutexLocker] variable with `g_autoptr()` and lock the +mutex. The mutex will be unlocked automatically when leaving the scope. The +variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is +not used in the scope. + +This feature is only supported on GCC and clang. This macro is not defined on +other compilers and should not be used in programs that are intended to be +portable to those compilers. + +Note that this should be used in a place where it is allowed to declare a +variable, which could be before any statement in the case +`-Wdeclaration-after-statement` is used, or C standard prior to C99. + +```c +{ + G_MUTEX_AUTO_LOCK (&obj->mutex, locker); + + obj->stuff_with_lock (); + if (condition) + { + // No need to unlock + return; + } + + // Unlock before end of scope + g_clear_pointer (&locker, g_mutex_locker_free); + obj->stuff_without_lock (); +} +``` + + + + a [type@GLib.Mutex] + + + a variable name to be declared + + + glib:get-type="g_main_context_get_type" c:symbol-prefix="main_context"> The `GMainContext` struct is an opaque data type representing a set of sources to be handled in a main loop. - + Creates a new #GMainContext structure. - + filename="glib/gmain.c" + line="605">Creates a new [struct@GLib.MainContext] structure. + the new #GMainContext + filename="glib/gmain.c" + line="610">the new #GMainContext @@ -21662,20 +22925,20 @@ type representing a set of sources to be handled in a main loop. c:identifier="g_main_context_new_with_flags" version="2.72"> Creates a new #GMainContext structure. - + filename="glib/gmain.c" + line="618">Creates a new [struct@GLib.MainContext] structure. + the new #GMainContext + filename="glib/gmain.c" + line="625">the new #GMainContext a bitwise-OR combination of #GMainContextFlags flags that can only be + filename="glib/gmain.c" + line="620">a bitwise-OR combination of #GMainContextFlags flags that can only be set at creation time. @@ -21683,25 +22946,26 @@ type representing a set of sources to be handled in a main loop. Tries to become the owner of the specified context. + filename="glib/gmain.c" + line="3438">Tries to become the owner of the specified context. If some other thread is the owner of the context, returns %FALSE immediately. Ownership is properly recursive: the owner can require ownership again -and will release ownership when g_main_context_release() -is called as many times as g_main_context_acquire(). +and will release ownership when [method@GLib.MainContext.release] +is called as many times as [method@GLib.MainContext.acquire]. You must be the owner of a context before you -can call g_main_context_prepare(), g_main_context_query(), -g_main_context_check(), g_main_context_dispatch(), g_main_context_release(). +can call [method@GLib.MainContext.prepare], [method@GLib.MainContext.query], +[method@GLib.MainContext.check], [method@GLib.MainContext.dispatch], +[method@GLib.MainContext.release]. Since 2.76 @context can be %NULL to use the global-default main context. - + %TRUE if the operation succeeded, and + filename="glib/gmain.c" + line="3458">%TRUE if the operation succeeded, and this thread is now the owner of @context. @@ -21711,8 +22975,8 @@ main context. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="3440">a #GMainContext (if %NULL, the global-default main context will be used) @@ -21720,11 +22984,11 @@ main context. Adds a file descriptor to the set of file descriptors polled for + filename="glib/gmain.c" + line="4700">Adds a file descriptor to the set of file descriptors polled for this context. This will very seldom be used directly. Instead -a typical event source will use g_source_add_unix_fd() instead. - +a typical event source will use `g_source_add_unix_fd` instead. + @@ -21734,46 +22998,46 @@ a typical event source will use g_source_add_unix_fd() instead. nullable="1" allow-none="1"> a #GMainContext (or %NULL for the global-default + filename="glib/gmain.c" + line="4702">a #GMainContext (or %NULL for the global-default main context) a #GPollFD structure holding information about a file + filename="glib/gmain.c" + line="4704">a #GPollFD structure holding information about a file descriptor to watch. the priority for this file descriptor which should be - the same as the priority used for g_source_attach() to ensure that the - file descriptor is polled whenever the results may be needed. + filename="glib/gmain.c" + line="4706">the priority for this file descriptor which should be + the same as the priority used for [method@GLib.Source.attach] to ensure + that the file descriptor is polled whenever the results may be needed. Passes the results of polling back to the main loop. You should be + filename="glib/gmain.c" + line="3995">Passes the results of polling back to the main loop. You should be careful to pass @fds and its length @n_fds as received from -g_main_context_query(), as this functions relies on assumptions +[method@GLib.MainContext.query], as this functions relies on assumptions on how @fds is filled. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. Since 2.76 @context can be %NULL to use the global-default main context. - + %TRUE if some sources are ready to be dispatched. + filename="glib/gmain.c" + line="4015">%TRUE if some sources are ready to be dispatched. @@ -21782,45 +23046,45 @@ main context. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="3997">a #GMainContext (if %NULL, the global-default main context will be used) the maximum numerical priority of sources to check + filename="glib/gmain.c" + line="3999">the maximum numerical priority of sources to check array of #GPollFD's that was passed to - the last call to g_main_context_query() + filename="glib/gmain.c" + line="4000">array of #GPollFD's that was passed to + the last call to [method@GLib.MainContext.query] return value of g_main_context_query() + filename="glib/gmain.c" + line="4002">return value of [method@GLib.MainContext.query] Dispatches all pending sources. + filename="glib/gmain.c" + line="4216">Dispatches all pending sources. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. Since 2.76 @context can be %NULL to use the global-default main context. - + @@ -21830,8 +23094,8 @@ main context. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4218">a #GMainContext (if %NULL, the global-default main context will be used) @@ -21840,15 +23104,15 @@ main context. Finds a source with the given source functions and user data. If + filename="glib/gmain.c" + line="2424">Finds a source with the given source functions and user data. If multiple sources exist with the same source function and user data, the first one found will be returned. - + the source, if one was found, otherwise %NULL + filename="glib/gmain.c" + line="2435">the source, if one was found, otherwise %NULL @@ -21857,15 +23121,15 @@ the first one found will be returned. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="2426">a #GMainContext (if %NULL, the global-default main context will be used). the @source_funcs passed to g_source_new(). + filename="glib/gmain.c" + line="2428">the @source_funcs passed to [ctor@GLib.Source.new]. nullable="1" allow-none="1"> the user data from the callback. + filename="glib/gmain.c" + line="2429">the user data from the callback. @@ -21882,24 +23146,24 @@ the first one found will be returned. Finds a #GSource given a pair of context and ID. + filename="glib/gmain.c" + line="2378">Finds a #GSource given a pair of context and ID. It is a programmer error to attempt to look up a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. - + the #GSource + filename="glib/gmain.c" + line="2397">the #GSource @@ -21908,15 +23172,15 @@ wrong source. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="2380">a #GMainContext (if %NULL, the global-default main context will be used) the source ID, as returned by g_source_get_id(). + filename="glib/gmain.c" + line="2382">the source ID, as returned by [method@GLib.Source.get_id]. @@ -21924,15 +23188,15 @@ wrong source. Finds a source with the given user data for the callback. If + filename="glib/gmain.c" + line="2475">Finds a source with the given user data for the callback. If multiple sources exist with the same user data, the first one found will be returned. - + the source, if one was found, otherwise %NULL + filename="glib/gmain.c" + line="2485">the source, if one was found, otherwise %NULL @@ -21941,8 +23205,8 @@ one found will be returned. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="2477">a #GMainContext (if %NULL, the global-default main context will be used) @@ -21951,8 +23215,8 @@ one found will be returned. nullable="1" allow-none="1"> the user_data for the callback. + filename="glib/gmain.c" + line="2479">the user_data for the callback. @@ -21961,13 +23225,13 @@ one found will be returned. c:identifier="g_main_context_get_poll_func" introspectable="0"> Gets the poll function set by g_main_context_set_poll_func(). - + filename="glib/gmain.c" + line="4932">Gets the poll function set by [method@GLib.MainContext.set_poll_func]. + the poll function + filename="glib/gmain.c" + line="4939">the poll function @@ -21976,8 +23240,8 @@ one found will be returned. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4934">a #GMainContext (if %NULL, the global-default main context will be used) @@ -21988,29 +23252,29 @@ one found will be returned. version="2.28" introspectable="0"> Invokes a function in such a way that @context is owned during the + filename="glib/gmain.c" + line="6461">Invokes a function in such a way that @context is owned during the invocation of @function. If @context is %NULL then the global-default main context — as -returned by g_main_context_default() — is used. +returned by [func@GLib.MainContext.default] — is used. If @context is owned by the current thread, @function is called directly. Otherwise, if @context is the thread-default main context -of the current thread and g_main_context_acquire() succeeds, then -@function is called and g_main_context_release() is called +of the current thread and [method@GLib.MainContext.acquire] succeeds, then +@function is called and [method@GLib.MainContext.release] is called afterwards. In any other case, an idle source is created to call @function and that source is attached to @context (presumably to be run in another -thread). The idle source is attached with %G_PRIORITY_DEFAULT +thread). The idle source is attached with [const@GLib.PRIORITY_DEFAULT] priority. If you want a different priority, use -g_main_context_invoke_full(). +[method@GLib.MainContext.invoke_full]. Note that, as with normal idle functions, @function should probably return %FALSE. If it returns %TRUE, it will be continuously run in a loop (and may prevent this call from returning). - + @@ -22020,15 +23284,15 @@ loop (and may prevent this call from returning). nullable="1" allow-none="1"> a #GMainContext, or %NULL for the global-default + filename="glib/gmain.c" + line="6463">a #GMainContext, or %NULL for the global-default main context function to call + filename="glib/gmain.c" + line="6465">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="6466">data to pass to @function @@ -22046,17 +23310,17 @@ loop (and may prevent this call from returning). c:identifier="g_main_context_invoke_full" version="2.28"> Invokes a function in such a way that @context is owned during the + filename="glib/gmain.c" + line="6502">Invokes a function in such a way that @context is owned during the invocation of @function. -This function is the same as g_main_context_invoke() except that it +This function is the same as [method@GLib.MainContext.invoke] except that it lets you specify the priority in case @function ends up being scheduled as an idle and also lets you give a #GDestroyNotify for @data. @notify should not assume that it is called from any particular thread or with any particular context acquired. - + @@ -22066,15 +23330,15 @@ thread or with any particular context acquired. nullable="1" allow-none="1"> a #GMainContext, or %NULL for the global-default + filename="glib/gmain.c" + line="6504">a #GMainContext, or %NULL for the global-default main context the priority at which to run @function + filename="glib/gmain.c" + line="6506">the priority at which to run @function closure="2" destroy="3"> function to call + filename="glib/gmain.c" + line="6507">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="6508">data to pass to @function allow-none="1" scope="async"> a function to call when @data is no longer in use, or %NULL. + filename="glib/gmain.c" + line="6509">a function to call when @data is no longer in use, or %NULL. @@ -22112,16 +23376,16 @@ thread or with any particular context acquired. c:identifier="g_main_context_is_owner" version="2.10"> Determines whether this thread holds the (recursive) -ownership of this #GMainContext. This is useful to + filename="glib/gmain.c" + line="5005">Determines whether this thread holds the (recursive) +ownership of this [struct@GLib.MainContext]. This is useful to know before waiting on another thread that may be blocking to get ownership of @context. - + %TRUE if current thread is owner of @context. + filename="glib/gmain.c" + line="5015">%TRUE if current thread is owner of @context. @@ -22130,8 +23394,8 @@ blocking to get ownership of @context. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="5007">a #GMainContext (if %NULL, the global-default main context will be used) @@ -22139,8 +23403,8 @@ blocking to get ownership of @context. Runs a single iteration for the given main loop. This involves + filename="glib/gmain.c" + line="4349">Runs a single iteration for the given main loop. This involves checking to see if any event sources are ready to be processed, then if no events sources are ready and @may_block is %TRUE, waiting for a source to become ready, then dispatching the highest priority @@ -22150,13 +23414,13 @@ events sources will be dispatched (if any), that are ready at this given moment without further waiting. Note that even when @may_block is %TRUE, it is still possible for -g_main_context_iteration() to return %FALSE, since the wait may +[method@GLib.MainContext.iteration] to return %FALSE, since the wait may be interrupted for other reasons than an event source becoming ready. - + %TRUE if events were dispatched. + filename="glib/gmain.c" + line="4368">%TRUE if events were dispatched. @@ -22165,28 +23429,28 @@ be interrupted for other reasons than an event source becoming ready. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4351">a #GMainContext (if %NULL, the global-default main context will be used) whether the call may block. + filename="glib/gmain.c" + line="4353">whether the call may block. Checks if any sources have pending events for the given context. - + filename="glib/gmain.c" + line="4325">Checks if any sources have pending events for the given context. + %TRUE if events are pending. + filename="glib/gmain.c" + line="4332">%TRUE if events are pending. @@ -22195,8 +23459,8 @@ be interrupted for other reasons than an event source becoming ready. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4327">a #GMainContext (if %NULL, the global-default main context will be used) @@ -22206,10 +23470,10 @@ be interrupted for other reasons than an event source becoming ready. c:identifier="g_main_context_pop_thread_default" version="2.22"> Pops @context off the thread-default context stack (verifying that + filename="glib/gmain.c" + line="814">Pops @context off the thread-default context stack (verifying that it was on the top of the stack). - + @@ -22219,8 +23483,8 @@ it was on the top of the stack). nullable="1" allow-none="1"> a #GMainContext, or %NULL for the global-default + filename="glib/gmain.c" + line="816">a #GMainContext, or %NULL for the global-default main context @@ -22228,17 +23492,17 @@ it was on the top of the stack). Prepares to poll sources within a main loop. The resulting information -for polling is determined by calling g_main_context_query (). + filename="glib/gmain.c" + line="3658">Prepares to poll sources within a main loop. The resulting information +for polling is determined by calling [method@GLib.MainContext.query]. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - +[method@GLib.MainContext.acquire] before you may call this function. + %TRUE if some source is ready to be dispatched + filename="glib/gmain.c" + line="3671">%TRUE if some source is ready to be dispatched prior to polling. @@ -22248,8 +23512,8 @@ g_main_context_acquire() before you may call this function. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="3660">a #GMainContext (if %NULL, the global-default main context will be used) @@ -22260,8 +23524,8 @@ g_main_context_acquire() before you may call this function. optional="1" allow-none="1"> location to store priority of highest priority + filename="glib/gmain.c" + line="3662">location to store priority of highest priority source already ready. @@ -22271,46 +23535,47 @@ g_main_context_acquire() before you may call this function. c:identifier="g_main_context_push_thread_default" version="2.22"> Acquires @context and sets it as the thread-default context for the + filename="glib/gmain.c" + line="741">Acquires @context and sets it as the thread-default context for the current thread. This will cause certain asynchronous operations -(such as most [gio][gio]-based I/O) which are +(such as most [Gio](../gio/index.html)-based I/O) which are started in this thread to run under @context and deliver their results to its main loop, rather than running under the global default main context in the main thread. Note that calling this function -changes the context returned by g_main_context_get_thread_default(), -not the one returned by g_main_context_default(), so it does not affect -the context used by functions like g_idle_add(). +changes the context returned by [func@GLib.MainContext.get_thread_default], +not the one returned by [func@GLib.MainContext.default], so it does not +affect the context used by functions like [func@GLib.idle_add]. Normally you would call this function shortly after creating a new -thread, passing it a #GMainContext which will be run by a -#GMainLoop in that thread, to set a new default context for all +thread, passing it a [struct@GLib.MainContext] which will be run by a +[struct@GLib.MainLoop] in that thread, to set a new default context for all async operations in that thread. In this case you may not need to -ever call g_main_context_pop_thread_default(), assuming you want the -new #GMainContext to be the default for the whole lifecycle of the -thread. +ever call [method@GLib.MainContext.pop_thread_default], assuming you want +the new [struct@GLib.MainContext] to be the default for the whole lifecycle +of the thread. If you don't have control over how the new thread was created (e.g. in the new thread isn't newly created, or if the thread life cycle is managed by a #GThreadPool), it is always suggested to wrap -the logic that needs to use the new #GMainContext inside a -g_main_context_push_thread_default() / g_main_context_pop_thread_default() -pair, otherwise threads that are re-used will end up never explicitly -releasing the #GMainContext reference they hold. +the logic that needs to use the new [struct@GLib.MainContext] inside a +[method@GLib.MainContext.push_thread_default] / +[method@GLib.MainContext.pop_thread_default] pair, otherwise threads that +are re-used will end up never explicitly releasing the +[struct@GLib.MainContext] reference they hold. In some cases you may want to schedule a single operation in a non-default context, or temporarily use a non-default context in the main thread. In that case, you can wrap the call to the asynchronous operation inside a -g_main_context_push_thread_default() / -g_main_context_pop_thread_default() pair, but it is up to you to +[method@GLib.MainContext.push_thread_default] / +[method@GLib.MainContext.pop_thread_default] pair, but it is up to you to ensure that no other asynchronous operations accidentally get started while the non-default context is active. Beware that libraries that predate this function may not correctly handle being used from a thread with a thread-default context. Eg, see g_file_supports_thread_contexts(). - + @@ -22320,28 +23585,86 @@ see g_file_supports_thread_contexts(). nullable="1" allow-none="1"> a #GMainContext, or %NULL for the global-default + filename="glib/gmain.c" + line="743">a #GMainContext, or %NULL for the global-default main context + + Push @main_context as the new thread-default main context for the current +thread, using [method@GLib.MainContext.push_thread_default], and return a +new [alias@GLib.MainContextPusher]. Pop with g_main_context_pusher_free(). +Using [method@GLib.MainContext.pop_thread_default] on @main_context while a +[alias@GLib.MainContextPusher] exists for it can lead to undefined behaviour. + +Using two [alias@GLib.MainContextPusher]s in the same scope is not allowed, +as it leads to an undefined pop order. + +This is intended to be used with g_autoptr(). Note that g_autoptr() +is only available when using GCC or clang, so the following example +will only work with those compilers: +|[ +typedef struct +{ + ... + GMainContext *context; + ... +} MyObject; + +static void +my_object_do_stuff (MyObject *self) +{ + g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context); + + // Code with main context as the thread default here + + if (cond) + // No need to pop + return; + + // Optionally early pop + g_clear_pointer (&pusher, g_main_context_pusher_free); + + // Code with main context no longer the thread default here +} +]| + + + a #GMainContextPusher + + + + + a main context to push + + + + Determines information necessary to poll this main loop. You should + filename="glib/gmain.c" + line="3878">Determines information necessary to poll this main loop. You should be careful to pass the resulting @fds array and its length @n_fds -as is when calling g_main_context_check(), as this function relies +as is when calling [method@GLib.MainContext.check], as this function relies on assumptions made when the array is filled. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - +[method@GLib.MainContext.acquire] before you may call this function. + the number of records actually stored in @fds, + filename="glib/gmain.c" + line="3896">the number of records actually stored in @fds, or, if more than @n_fds records need to be stored, the number of records that need to be stored. @@ -22352,15 +23675,15 @@ g_main_context_acquire() before you may call this function. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="3880">a #GMainContext (if %NULL, the global-default main context will be used) maximum priority source to check + filename="glib/gmain.c" + line="3882">maximum priority source to check caller-allocates="0" transfer-ownership="full"> location to store timeout to be used in polling + filename="glib/gmain.c" + line="3883">location to store timeout to be used in polling caller-allocates="1" transfer-ownership="none"> location to + filename="glib/gmain.c" + line="3884">location to store #GPollFD records that need to be polled. @@ -22386,43 +23709,43 @@ g_main_context_acquire() before you may call this function. length of @fds. + filename="glib/gmain.c" + line="3886">length of @fds. Increases the reference count on a #GMainContext object by one. - + filename="glib/gmain.c" + line="468">Increases the reference count on a [struct@GLib.MainContext] object by one. + the @context that was passed in (since 2.6) + filename="glib/gmain.c" + line="474">the @context that was passed in (since 2.6) a #GMainContext + filename="glib/gmain.c" + line="470">a #GMainContext Releases ownership of a context previously acquired by this thread -with g_main_context_acquire(). If the context was acquired multiple -times, the ownership will be released only when g_main_context_release() + filename="glib/gmain.c" + line="3502">Releases ownership of a context previously acquired by this thread +with [method@GLib.MainContext.acquire]. If the context was acquired multiple +times, the ownership will be released only when [method@GLib.MainContext.release] is called as many times as it was acquired. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - +[method@GLib.MainContext.acquire] before you may call this function. + @@ -22432,8 +23755,8 @@ g_main_context_acquire() before you may call this function. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="3504">a #GMainContext (if %NULL, the global-default main context will be used) @@ -22441,10 +23764,10 @@ g_main_context_acquire() before you may call this function. Removes file descriptor from the set of file descriptors to be + filename="glib/gmain.c" + line="4775">Removes file descriptor from the set of file descriptors to be polled for a particular context. - + @@ -22454,15 +23777,16 @@ polled for a particular context. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4777">a #GMainContext (if %NULL, the global-default main context will be used) a #GPollFD descriptor previously added with g_main_context_add_poll() + filename="glib/gmain.c" + line="4779">a #GPollFD descriptor previously added with + [method@GLib.MainContext.add_poll] @@ -22471,15 +23795,15 @@ polled for a particular context. c:identifier="g_main_context_set_poll_func" introspectable="0"> Sets the function to use to handle polling of file descriptors. It + filename="glib/gmain.c" + line="4899">Sets the function to use to handle polling of file descriptors. It will be used instead of the poll() system call (or GLib's replacement function, which is used where poll() isn't available). This function could possibly be used to integrate the GLib event loop with an external event loop. - + @@ -22489,33 +23813,34 @@ loop with an external event loop. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4901">a #GMainContext (if %NULL, the global-default main context will be used) the function to call to poll all file descriptors + filename="glib/gmain.c" + line="4903">the function to call to poll all file descriptors Decreases the reference count on a #GMainContext object by one. If + filename="glib/gmain.c" + line="496">Decreases the reference count on a [struct@GLib.MainContext] object by one. +If the result is zero, free the context and free all associated memory. - + a #GMainContext + filename="glib/gmain.c" + line="498">a #GMainContext @@ -22525,18 +23850,19 @@ the result is zero, free the context and free all associated memory. deprecated="1" deprecated-version="2.58"> Tries to become the owner of the specified context, -as with g_main_context_acquire(). But if another thread + filename="glib/gmain.c" + line="3617">Tries to become the owner of the specified context, +as with [method@GLib.MainContext.acquire]. But if another thread is the owner, atomically drop @mutex and wait on @cond until that owner releases ownership or until @cond is signaled, then try again (once) to become the owner. - Use g_main_context_is_owner() and separate locking instead. - + Use [method@GLib.MainContext.is_owner] and separate + locking instead. + %TRUE if the operation succeeded, and + filename="glib/gmain.c" + line="3630">%TRUE if the operation succeeded, and this thread is now the owner of @context. @@ -22546,36 +23872,36 @@ try again (once) to become the owner. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="3619">a #GMainContext (if %NULL, the global-default main context will be used) a condition variable + filename="glib/gmain.c" + line="3621">a condition variable a mutex, currently held + filename="glib/gmain.c" + line="3622">a mutex, currently held If @context is currently blocking in g_main_context_iteration() + filename="glib/gmain.c" + line="4958">If @context is currently blocking in [method@GLib.MainContext.iteration] waiting for a source to become ready, cause it to stop blocking and return. Otherwise, cause the next invocation of -g_main_context_iteration() to return without blocking. +[method@GLib.MainContext.iteration] to return without blocking. -This API is useful for low-level control over #GMainContext; for +This API is useful for low-level control over [struct@GLib.MainContext]; for example, integrating it with main loop implementations such as -#GMainLoop. +[struct@GLib.MainLoop]. Another related use for this function is when implementing a main loop with a termination condition, computed from multiple threads: @@ -22596,7 +23922,7 @@ Then in a thread: if (g_atomic_int_dec_and_test (&tasks_remaining)) g_main_context_wakeup (NULL); ]| - + @@ -22606,8 +23932,8 @@ Then in a thread: nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4960">a #GMainContext (if %NULL, the global-default main context will be used) @@ -22615,16 +23941,16 @@ Then in a thread: Returns the global-default main context. This is the main context + filename="glib/gmain.c" + line="687">Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the "main" main loop. See also -g_main_context_get_thread_default(). - +[func@GLib.MainContext.get_thread_default]. + the global-default main context. + filename="glib/gmain.c" + line="695">the global-default main context. @@ -22632,44 +23958,69 @@ g_main_context_get_thread_default(). c:identifier="g_main_context_get_thread_default" version="2.22"> Gets the thread-default #GMainContext for this thread. Asynchronous + filename="glib/gmain.c" + line="846">Gets the thread-default #GMainContext for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or -g_main_context_ref_thread_default() to get a #GMainContext to add -their #GSources to. (Note that even in single-threaded -programs applications may sometimes want to temporarily push a -non-default context, so it is not safe to assume that this will -always return %NULL if you are running in the default thread.) +[func@GLib.MainContext.ref_thread_default] to get a +[struct@GLib.MainContext] to add their [struct@GLib.Source]s to. (Note that +even in single-threaded programs applications may sometimes want to +temporarily push a non-default context, so it is not safe to assume that +this will always return %NULL if you are running in the default thread.) If you need to hold a reference on the context, use -g_main_context_ref_thread_default() instead. - +[func@GLib.MainContext.ref_thread_default] instead. + the thread-default #GMainContext, or + filename="glib/gmain.c" + line="861">the thread-default #GMainContext, or %NULL if the thread-default context is the global-default main context. + + Pop @pusher’s main context as the thread default main context. +See g_main_context_pusher_new() for details. + +This will pop the [struct@GLib.MainContext] as the current thread-default +main context, but will not call [method@GLib.MainContext.unref] on it. + + + + + + + a #GMainContextPusher + + + + Gets the thread-default #GMainContext for this thread, as with -g_main_context_get_thread_default(), but also adds a reference to -it with g_main_context_ref(). In addition, unlike -g_main_context_get_thread_default(), if the thread-default context -is the global-default context, this will return that #GMainContext -(with a ref added to it) rather than returning %NULL. - + filename="glib/gmain.c" + line="878">Gets the thread-default [struct@GLib.MainContext] for this thread, as with +[func@GLib.MainContext.get_thread_default], but also adds a reference to +it with [method@GLib.MainContext.ref]. In addition, unlike +[func@GLib.MainContext.get_thread_default], if the thread-default context +is the global-default context, this will return that +[struct@GLib.MainContext] (with a ref added to it) rather than returning +%NULL. + the thread-default #GMainContext. Unref - with g_main_context_unref() when you are done with it. + filename="glib/gmain.c" + line="889">the thread-default #GMainContext. Unref + with [method@GLib.MainContext.unref] when you are done with it. @@ -22678,20 +24029,20 @@ is the global-default context, this will return that #GMainContext version="2.72" c:type="GMainContextFlags"> Flags to pass to g_main_context_new_with_flags() which affect the behaviour -of a #GMainContext. - + filename="glib/gmain.h" + line="43">Flags to pass to [ctor@GLib.MainContext.new_with_flags] which affect the +behaviour of a [struct@GLib.MainContext]. + Default behaviour. Assume that polling for events will free the thread to process other jobs. That's useful if you're using `g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in @@ -22705,19 +24056,19 @@ other event loops. glib:get-type="g_main_loop_get_type" c:symbol-prefix="main_loop"> The `GMainLoop` struct is an opaque data type representing the main event loop of a GLib or GTK application. - + Creates a new #GMainLoop structure. - + filename="glib/gmain.c" + line="4385">Creates a new [struct@GLib.MainLoop] structure. + a new #GMainLoop. + filename="glib/gmain.c" + line="4395">a new #GMainLoop. @@ -22726,136 +24077,137 @@ representing the main event loop of a GLib or GTK application. nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="4387">a #GMainContext (if %NULL, the global-default main context will be used). set to %TRUE to indicate that the loop is running. This -is not very important since calling g_main_loop_run() will set this to -%TRUE anyway. + filename="glib/gmain.c" + line="4389">set to %TRUE to indicate that the loop is running. This +is not very important since calling [method@GLib.MainLoop.run] will set this +to %TRUE anyway. Returns the #GMainContext of @loop. - + filename="glib/gmain.c" + line="4570">Returns the [struct@GLib.MainContext] of @loop. + the #GMainContext of @loop + filename="glib/gmain.c" + line="4576">the [struct@GLib.MainContext] of @loop a #GMainLoop. + filename="glib/gmain.c" + line="4572">a #GMainLoop. Checks to see if the main loop is currently being run via g_main_loop_run(). - + filename="glib/gmain.c" + line="4552">Checks to see if the main loop is currently being run via +[method@GLib.MainLoop.run]. + %TRUE if the mainloop is currently being run. + filename="glib/gmain.c" + line="4559">%TRUE if the mainloop is currently being run. a #GMainLoop. + filename="glib/gmain.c" + line="4554">a #GMainLoop. Stops a #GMainLoop from running. Any calls to g_main_loop_run() -for the loop will return. + filename="glib/gmain.c" + line="4525">Stops a [struct@GLib.MainLoop] from running. Any calls to +[method@GLib.MainLoop.run] for the loop will return. Note that sources that have already been dispatched when -g_main_loop_quit() is called will still be executed. - +[method@GLib.MainLoop.quit] is called will still be executed. + a #GMainLoop + filename="glib/gmain.c" + line="4527">a #GMainLoop Increases the reference count on a #GMainLoop object by one. - + filename="glib/gmain.c" + line="4418">Increases the reference count on a [struct@GLib.MainLoop] object by one. + @loop + filename="glib/gmain.c" + line="4424">@loop a #GMainLoop + filename="glib/gmain.c" + line="4420">a #GMainLoop Runs a main loop until g_main_loop_quit() is called on the loop. + filename="glib/gmain.c" + line="4457">Runs a main loop until [method@GLib.MainLoop.quit] is called on the loop. If this is called for the thread of the loop's #GMainContext, it will process events from the loop, otherwise it will simply wait. - + a #GMainLoop + filename="glib/gmain.c" + line="4459">a #GMainLoop Decreases the reference count on a #GMainLoop object by one. If + filename="glib/gmain.c" + line="4437">Decreases the reference count on a [struct@GLib.MainLoop] object by one. If the result is zero, free the loop and free all associated memory. - + a #GMainLoop + filename="glib/gmain.c" + line="4439">a #GMainLoop @@ -22868,18 +24220,18 @@ the result is zero, free the loop and free all associated memory. glib:get-type="g_mapped_file_get_type" c:symbol-prefix="mapped_file"> The #GMappedFile represents a file mapping created with + filename="glib/gmappedfile.c" + line="78">The #GMappedFile represents a file mapping created with g_mapped_file_new(). It has only private members and should not be accessed directly. - + Maps a file into memory. On UNIX, this is using the mmap() function. + filename="glib/gmappedfile.c" + line="219">Maps a file into memory. On UNIX, this is using the mmap() function. If @writable is %TRUE, the mapped buffer may be modified, otherwise it is an error to modify the mapped buffer. Modifications to the buffer @@ -22895,26 +24247,26 @@ If @filename is the name of an empty, regular file, the function will successfully return an empty #GMappedFile. In other cases of size 0 (e.g. device files such as /dev/null), @error will be set to the #GFileError value %G_FILE_ERROR_INVAL. - + a newly allocated #GMappedFile which must be unref'd + filename="glib/gmappedfile.c" + line="243">a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. The path of the file to load, in the GLib + filename="glib/gmappedfile.c" + line="221">The path of the file to load, in the GLib filename encoding whether the mapping should be writable + filename="glib/gmappedfile.c" + line="223">whether the mapping should be writable @@ -22924,8 +24276,8 @@ to the #GFileError value %G_FILE_ERROR_INVAL. version="2.32" throws="1"> Maps a file into memory. On UNIX, this is using the mmap() function. + filename="glib/gmappedfile.c" + line="283">Maps a file into memory. On UNIX, this is using the mmap() function. If @writable is %TRUE, the mapped buffer may be modified, otherwise it is an error to modify the mapped buffer. Modifications to the buffer @@ -22936,25 +24288,25 @@ Note that modifications of the underlying file might affect the contents of the #GMappedFile. Therefore, mapping should only be used if the file will not be modified, or if all modifications of the file are done atomically (e.g. using g_file_set_contents()). - + a newly allocated #GMappedFile which must be unref'd + filename="glib/gmappedfile.c" + line="301">a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. The file descriptor of the file to load + filename="glib/gmappedfile.c" + line="285">The file descriptor of the file to load whether the mapping should be writable + filename="glib/gmappedfile.c" + line="286">whether the mapping should be writable @@ -22965,19 +24317,19 @@ atomically (e.g. using g_file_set_contents()). deprecated="1" deprecated-version="2.22"> This call existed before #GMappedFile had refcounting and is currently + filename="glib/gmappedfile.c" + line="355">This call existed before #GMappedFile had refcounting and is currently exactly the same as g_mapped_file_unref(). Use g_mapped_file_unref() instead. - + a #GMappedFile + filename="glib/gmappedfile.c" + line="357">a #GMappedFile @@ -22986,23 +24338,23 @@ exactly the same as g_mapped_file_unref(). c:identifier="g_mapped_file_get_bytes" version="2.34"> Creates a new #GBytes which references the data mapped from @file. + filename="glib/gmappedfile.c" + line="412">Creates a new #GBytes which references the data mapped from @file. The mapped contents of the file must not be modified after creating this bytes object, because a #GBytes should be immutable. - + A newly allocated #GBytes referencing data + filename="glib/gmappedfile.c" + line="420">A newly allocated #GBytes referencing data from @file a #GMappedFile + filename="glib/gmappedfile.c" + line="414">a #GMappedFile @@ -23011,25 +24363,25 @@ bytes object, because a #GBytes should be immutable. c:identifier="g_mapped_file_get_contents" version="2.8"> Returns the contents of a #GMappedFile. + filename="glib/gmappedfile.c" + line="332">Returns the contents of a #GMappedFile. Note that the contents may not be zero-terminated, even if the #GMappedFile is backed by a text file. If the file is empty then %NULL is returned. - - + + the contents of @file, or %NULL. + filename="glib/gmappedfile.c" + line="343">the contents of @file, or %NULL. a #GMappedFile + filename="glib/gmappedfile.c" + line="334">a #GMappedFile @@ -23038,63 +24390,63 @@ If the file is empty then %NULL is returned. c:identifier="g_mapped_file_get_length" version="2.8"> Returns the length of the contents of a #GMappedFile. - + filename="glib/gmappedfile.c" + line="314">Returns the length of the contents of a #GMappedFile. + the length of the contents of @file. + filename="glib/gmappedfile.c" + line="320">the length of the contents of @file. a #GMappedFile + filename="glib/gmappedfile.c" + line="316">a #GMappedFile Increments the reference count of @file by one. It is safe to call + filename="glib/gmappedfile.c" + line="371">Increments the reference count of @file by one. It is safe to call this function from any thread. - + the passed in #GMappedFile. + filename="glib/gmappedfile.c" + line="378">the passed in #GMappedFile. a #GMappedFile + filename="glib/gmappedfile.c" + line="373">a #GMappedFile Decrements the reference count of @file by one. If the reference count + filename="glib/gmappedfile.c" + line="392">Decrements the reference count of @file by one. If the reference count drops to 0, unmaps the buffer of @file and frees it. It is safe to call this function from any thread. Since 2.22 - + a #GMappedFile + filename="glib/gmappedfile.c" + line="394">a #GMappedFile @@ -23102,39 +24454,39 @@ Since 2.22 A mixed enumerated type and flags field. You must specify one type + filename="glib/gmarkup.c" + line="2619">A mixed enumerated type and flags field. You must specify one type (string, strdup, boolean, tristate). Additionally, you may optionally bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. It is likely that this enum will be extended in the future to support other types. - + used to terminate the list of attributes + filename="glib/gmarkup.c" + line="2621">used to terminate the list of attributes to collect collect the string pointer directly from + filename="glib/gmarkup.c" + line="2623">collect the string pointer directly from the attribute_values[] array. Expects a parameter of type (const char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the attribute isn't present then the pointer will be set to %NULL as with %G_MARKUP_COLLECT_STRING, but + filename="glib/gmarkup.c" + line="2627">as with %G_MARKUP_COLLECT_STRING, but expects a parameter of type (char **) and g_strdup()s the returned pointer. The pointer must be freed with g_free() expects a parameter of type (gboolean *) + filename="glib/gmarkup.c" + line="2630">expects a parameter of type (`gboolean *`) and parses the attribute value as a boolean. Sets %FALSE if the attribute isn't present. Valid boolean values consist of (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", @@ -23144,18 +24496,18 @@ support other types. value="4" c:identifier="G_MARKUP_COLLECT_TRISTATE"> as with %G_MARKUP_COLLECT_BOOLEAN, but + filename="glib/gmarkup.c" + line="2635">as with %G_MARKUP_COLLECT_BOOLEAN, but in the case of a missing attribute a value is set that compares - equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is + equal to neither %FALSE nor %TRUE %G_MARKUP_COLLECT_OPTIONAL is implied can be bitwise ORed with the other fields. + filename="glib/gmarkup.c" + line="2639">can be bitwise ORed with the other fields. If present, allows the attribute not to appear. A default value is set depending on what value type is used @@ -23164,29 +24516,29 @@ support other types. c:type="GMarkupError" glib:error-domain="g-markup-error-quark"> Error codes returned by markup parsing. - + text being parsed was not valid UTF-8 document contained nothing, or only whitespace document was ill-formed error should be set by #GMarkupParser functions; element wasn't known @@ -23194,7 +24546,7 @@ support other types. value="4" c:identifier="G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE"> error should be set by #GMarkupParser functions; attribute wasn't known @@ -23202,7 +24554,7 @@ support other types. value="5" c:identifier="G_MARKUP_ERROR_INVALID_CONTENT"> error should be set by #GMarkupParser functions; content was invalid @@ -23210,7 +24562,7 @@ support other types. value="6" c:identifier="G_MARKUP_ERROR_MISSING_ATTRIBUTE"> error should be set by #GMarkupParser functions; a required attribute was missing @@ -23222,39 +24574,39 @@ support other types. glib:get-type="g_markup_parse_context_get_type" c:symbol-prefix="markup_parse_context"> A parse context is used to parse a stream of bytes that you expect to contain marked-up text. See g_markup_parse_context_new(), #GMarkupParser, and so on for more details. - + Creates a new parse context. A parse context is used to parse + filename="glib/gmarkup.c" + line="149">Creates a new parse context. A parse context is used to parse marked-up documents. You can feed any number of documents into a context, as long as no errors occur; once an error occurs, the parse context can't continue to parse text (you have to free it and create a new parse context). - + a new #GMarkupParseContext + filename="glib/gmarkup.c" + line="163">a new #GMarkupParseContext a #GMarkupParser + filename="glib/gmarkup.c" + line="151">a #GMarkupParser one or more #GMarkupParseFlags + filename="glib/gmarkup.c" + line="152">one or more #GMarkupParseFlags nullable="1" allow-none="1"> user data to pass to #GMarkupParser functions + filename="glib/gmarkup.c" + line="153">user data to pass to #GMarkupParser functions user data destroy notifier called when + filename="glib/gmarkup.c" + line="154">user data destroy notifier called when the parse context is freed @@ -23281,44 +24633,44 @@ free it and create a new parse context). c:identifier="g_markup_parse_context_end_parse" throws="1"> Signals to the #GMarkupParseContext that all data has been + filename="glib/gmarkup.c" + line="1715">Signals to the #GMarkupParseContext that all data has been fed into the parse context with g_markup_parse_context_parse(). This function reports an error if the document isn't complete, for example if elements are still open. - + %TRUE on success, %FALSE if an error was set + filename="glib/gmarkup.c" + line="1726">%TRUE on success, %FALSE if an error was set a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1717">a #GMarkupParseContext Frees a #GMarkupParseContext. + filename="glib/gmarkup.c" + line="268">Frees a #GMarkupParseContext. This function can't be called from inside one of the #GMarkupParser functions or while a subparser is pushed. - + a #GMarkupParseContext + filename="glib/gmarkup.c" + line="270">a #GMarkupParseContext @@ -23327,35 +24679,34 @@ This function can't be called from inside one of the c:identifier="g_markup_parse_context_get_element" version="2.2"> Retrieves the name of the currently open element. + filename="glib/gmarkup.c" + line="1847">Retrieves the name of the currently open element. If called from the start_element or end_element handlers this will give the element_name as passed to those functions. For the parent elements, see g_markup_parse_context_get_element_stack(). - + the name of the currently open element, or %NULL + filename="glib/gmarkup.c" + line="1857">the name of the currently open element, or %NULL a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1849">a #GMarkupParseContext + version="2.16"> Retrieves the element stack from the internal state of the parser. + filename="glib/gmarkup.c" + line="1872">Retrieves the element stack from the internal state of the parser. The returned #GSList is a list of strings where the first item is the currently open tag (as would be returned by @@ -23366,20 +24717,20 @@ This function is intended to be used in the start_element and end_element handlers where g_markup_parse_context_get_element() would merely return the name of the element that is being processed. - + the element stack, which must not be modified + filename="glib/gmarkup.c" + line="1888">the element stack, which must not be modified - + a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1874">a #GMarkupParseContext @@ -23387,20 +24738,20 @@ processed. Retrieves the current line number and the number of the character on + filename="glib/gmarkup.c" + line="1899">Retrieves the current line number and the number of the character on that line. Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages." - + a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1901">a #GMarkupParseContext return location for a line number, or %NULL + filename="glib/gmarkup.c" + line="1902">return location for a line number, or %NULL return location for a char-on-line number, or %NULL + filename="glib/gmarkup.c" + line="1903">return location for a char-on-line number, or %NULL @@ -23431,17 +24782,17 @@ semantics for what constitutes the "current" line number other than c:identifier="g_markup_parse_context_get_user_data" version="2.18"> Returns the user_data associated with @context. + filename="glib/gmarkup.c" + line="1924">Returns the user_data associated with @context. This will either be the user_data that was provided to g_markup_parse_context_new() or to the most recent call of g_markup_parse_context_push(). - + the provided user_data. The returned data belongs to + filename="glib/gmarkup.c" + line="1934">the provided user_data. The returned data belongs to the markup context and will be freed when g_markup_parse_context_free() is called. @@ -23449,8 +24800,8 @@ of g_markup_parse_context_push(). a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1926">a #GMarkupParseContext @@ -23459,8 +24810,8 @@ of g_markup_parse_context_push(). c:identifier="g_markup_parse_context_parse" throws="1"> Feed some data to the #GMarkupParseContext. + filename="glib/gmarkup.c" + line="1061">Feed some data to the #GMarkupParseContext. The data need not be valid UTF-8; an error will be signaled if it's invalid. The data need not be an entire document; you can @@ -23470,30 +24821,30 @@ connection or file, you feed each received chunk of data into this function, aborting the process if an error occurs. Once an error is reported, no further data may be fed to the #GMarkupParseContext; all errors are fatal. - + %FALSE if an error occurred, %TRUE on success + filename="glib/gmarkup.c" + line="1079">%FALSE if an error occurred, %TRUE on success a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1063">a #GMarkupParseContext chunk of text to parse + filename="glib/gmarkup.c" + line="1064">chunk of text to parse length of @text in bytes + filename="glib/gmarkup.c" + line="1065">length of @text in bytes @@ -23502,8 +24853,8 @@ all errors are fatal. c:identifier="g_markup_parse_context_pop" version="2.18"> Completes the process of a temporary sub-parser redirection. + filename="glib/gmarkup.c" + line="2089">Completes the process of a temporary sub-parser redirection. This function exists to collect the user_data allocated by a matching call to g_markup_parse_context_push(). It must be called @@ -23516,18 +24867,18 @@ This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. - + the user data passed to g_markup_parse_context_push() + filename="glib/gmarkup.c" + line="2107">the user data passed to g_markup_parse_context_push() a #GMarkupParseContext + filename="glib/gmarkup.c" + line="2091">a #GMarkupParseContext @@ -23536,8 +24887,8 @@ interface. c:identifier="g_markup_parse_context_push" version="2.18"> Temporarily redirects markup data to a sub-parser. + filename="glib/gmarkup.c" + line="1946">Temporarily redirects markup data to a sub-parser. This function may only be called from the start_element handler of a #GMarkupParser. It must be matched with a corresponding call to @@ -23651,21 +25002,21 @@ static void end_element (context, element_name, ...) // else, handle other tags... } ]| - + a #GMarkupParseContext + filename="glib/gmarkup.c" + line="1948">a #GMarkupParseContext a #GMarkupParser + filename="glib/gmarkup.c" + line="1949">a #GMarkupParser user data to pass to #GMarkupParser functions + filename="glib/gmarkup.c" + line="1950">user data to pass to #GMarkupParser functions @@ -23683,20 +25034,20 @@ static void end_element (context, element_name, ...) c:identifier="g_markup_parse_context_ref" version="2.36"> Increases the reference count of @context. - + filename="glib/gmarkup.c" + line="220">Increases the reference count of @context. + the same @context + filename="glib/gmarkup.c" + line="226">the same @context a #GMarkupParseContext + filename="glib/gmarkup.c" + line="222">a #GMarkupParseContext @@ -23705,18 +25056,18 @@ static void end_element (context, element_name, ...) c:identifier="g_markup_parse_context_unref" version="2.36"> Decreases the reference count of @context. When its reference count + filename="glib/gmarkup.c" + line="241">Decreases the reference count of @context. When its reference count drops to 0, it is freed. - + a #GMarkupParseContext + filename="glib/gmarkup.c" + line="243">a #GMarkupParseContext @@ -23724,28 +25075,28 @@ drops to 0, it is freed. Flags that affect the behaviour of the parser. - + No special behaviour. Since: 2.74 flag you should not use When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the @@ -23756,7 +25107,7 @@ drops to 0, it is freed. value="4" c:identifier="G_MARKUP_PREFIX_ERROR_POSITION"> Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the @@ -23767,7 +25118,7 @@ drops to 0, it is freed. value="8" c:identifier="G_MARKUP_IGNORE_QUALIFIED"> Ignore (don't report) qualified attributes and tags, along with their contents. A qualified attribute or tag is one that contains ':' in its name (ie: is in @@ -23776,7 +25127,7 @@ drops to 0, it is freed. Any of the fields in #GMarkupParser can be %NULL, in which case they will be ignored. Except for the @error function, any of these callbacks can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, @@ -23784,10 +25135,15 @@ can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, errors are intended to be set from these callbacks. If you set an error from a callback, g_markup_parse_context_parse() will report that error back to its caller. - + + Callback to invoke when the opening tag of an element + is seen. The callback's @attribute_names and @attribute_values parameters + are %NULL-terminated. - + @@ -23815,8 +25171,13 @@ back to its caller. + Callback to invoke when the closing tag of an element + is seen. Note that this is also called for empty tags like + `<empty/>`. - + @@ -23838,8 +25199,15 @@ back to its caller. + Callback to invoke when some text is seen (text is always + inside an element). Note that the text of an element may be spread + over multiple calls of this function. If the + %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also + called for the content of CDATA marked sections. - + @@ -23864,8 +25232,15 @@ back to its caller. + Callback to invoke for comments, processing instructions + and doctype declarations; if you're re-writing the parsed document, + write the passthrough text back out in the same position. If the + %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also + called for CDATA marked sections. - + @@ -23890,8 +25265,11 @@ back to its caller. + Callback to invoke when an error occurs. - + @@ -23920,17 +25298,17 @@ back to its caller. glib:get-type="g_match_info_get_type" c:symbol-prefix="match_info"> A GMatchInfo is an opaque struct used to return information about + filename="glib/gregex.h" + line="419">A GMatchInfo is an opaque struct used to return information about matches. - + Returns a new string containing the text in @string_to_expand with + filename="glib/gregex.c" + line="1329">Returns a new string containing the text in @string_to_expand with references and escape sequences expanded. References refer to the last match done with @string against @regex and have the same syntax used by g_regex_replace(). @@ -23947,11 +25325,11 @@ pattern and '\n' merely will be replaced with \n character, while to expand "\0" (whole match) one needs the result of a match. Use g_regex_check_replacement() to find out whether @string_to_expand contains references. - + the expanded string, or %NULL if an error occurred + filename="glib/gregex.c" + line="1353">the expanded string, or %NULL if an error occurred @@ -23960,22 +25338,22 @@ contains references. nullable="1" allow-none="1"> a #GMatchInfo or %NULL + filename="glib/gregex.c" + line="1331">a #GMatchInfo or %NULL the string to expand + filename="glib/gregex.c" + line="1332">the string to expand Retrieves the text matching the @match_num'th capturing + filename="glib/gregex.c" + line="1392">Retrieves the text matching the @match_num'th capturing parentheses. 0 is the full text of the match, 1 is the first paren set, 2 the second, and so on. @@ -23991,25 +25369,25 @@ substring. Substrings are matched in reverse order of length, so The string is fetched from the string passed to the match function, so you cannot call this function after freeing the string. - + The matched substring, or %NULL if an error + filename="glib/gregex.c" + line="1414">The matched substring, or %NULL if an error occurred. You have to free the string yourself #GMatchInfo structure + filename="glib/gregex.c" + line="1394">#GMatchInfo structure number of the sub expression + filename="glib/gregex.c" + line="1395">number of the sub expression @@ -24018,8 +25396,8 @@ so you cannot call this function after freeing the string. c:identifier="g_match_info_fetch_all" version="2.14"> Bundles up pointers to each of the matching substrings from a match + filename="glib/gregex.c" + line="1609">Bundles up pointers to each of the matching substrings from a match and stores them in an array of gchar pointers. The first element in the returned array is the match number 0, i.e. the entire matched text. @@ -24035,11 +25413,11 @@ so the first one is the longest match. The strings are fetched from the string passed to the match function, so you cannot call this function after freeing the string. - + a %NULL-terminated array of gchar * + filename="glib/gregex.c" + line="1630">a %NULL-terminated array of gchar * pointers. It must be freed using g_strfreev(). If the previous match failed %NULL is returned @@ -24049,8 +25427,8 @@ so you cannot call this function after freeing the string. a #GMatchInfo structure + filename="glib/gregex.c" + line="1611">a #GMatchInfo structure @@ -24059,34 +25437,34 @@ so you cannot call this function after freeing the string. c:identifier="g_match_info_fetch_named" version="2.14"> Retrieves the text matching the capturing parentheses named @name. + filename="glib/gregex.c" + line="1535">Retrieves the text matching the capturing parentheses named @name. If @name is a valid sub pattern name but it didn't match anything -(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") +(e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`) then an empty string is returned. The string is fetched from the string passed to the match function, so you cannot call this function after freeing the string. - + The matched substring, or %NULL if an error + filename="glib/gregex.c" + line="1549">The matched substring, or %NULL if an error occurred. You have to free the string yourself #GMatchInfo structure + filename="glib/gregex.c" + line="1537">#GMatchInfo structure name of the subexpression + filename="glib/gregex.c" + line="1538">name of the subexpression @@ -24095,17 +25473,17 @@ so you cannot call this function after freeing the string. c:identifier="g_match_info_fetch_named_pos" version="2.14"> Retrieves the position in bytes of the capturing parentheses named @name. + filename="glib/gregex.c" + line="1570">Retrieves the position in bytes of the capturing parentheses named @name. If @name is a valid sub pattern name but it didn't match anything -(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") +(e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`) then @start_pos and @end_pos are set to -1 and %TRUE is returned. - + %TRUE if the position was fetched, %FALSE otherwise. + filename="glib/gregex.c" + line="1585">%TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged. @@ -24113,14 +25491,14 @@ then @start_pos and @end_pos are set to -1 and %TRUE is returned. #GMatchInfo structure + filename="glib/gregex.c" + line="1572">#GMatchInfo structure name of the subexpression + filename="glib/gregex.c" + line="1573">name of the subexpression optional="1" allow-none="1"> pointer to location where to store + filename="glib/gregex.c" + line="1574">pointer to location where to store the start position, or %NULL @@ -24142,8 +25520,8 @@ then @start_pos and @end_pos are set to -1 and %TRUE is returned. optional="1" allow-none="1"> pointer to location where to store + filename="glib/gregex.c" + line="1576">pointer to location where to store the end position, or %NULL @@ -24153,8 +25531,8 @@ then @start_pos and @end_pos are set to -1 and %TRUE is returned. c:identifier="g_match_info_fetch_pos" version="2.14"> Retrieves the position in bytes of the @match_num'th capturing + filename="glib/gregex.c" + line="1441">Retrieves the position in bytes of the @match_num'th capturing parentheses. 0 is the full text of the match, 1 is the first paren set, 2 the second, and so on. @@ -24167,11 +25545,11 @@ g_regex_match_all() or g_regex_match_all_full(), the retrieved position is not that of a set of parentheses but that of a matched substring. Substrings are matched in reverse order of length, so 0 is the longest match. - + %TRUE if the position was fetched, %FALSE otherwise. If + filename="glib/gregex.c" + line="1464">%TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged @@ -24179,14 +25557,14 @@ substring. Substrings are matched in reverse order of length, so #GMatchInfo structure + filename="glib/gregex.c" + line="1443">#GMatchInfo structure number of the sub expression + filename="glib/gregex.c" + line="1444">number of the sub expression pointer to location where to store + filename="glib/gregex.c" + line="1445">pointer to location where to store the start position, or %NULL @@ -24208,8 +25586,8 @@ substring. Substrings are matched in reverse order of length, so optional="1" allow-none="1"> pointer to location where to store + filename="glib/gregex.c" + line="1447">pointer to location where to store the end position, or %NULL @@ -24217,10 +25595,10 @@ substring. Substrings are matched in reverse order of length, so If @match_info is not %NULL, calls g_match_info_unref(); otherwise does + filename="glib/gregex.c" + line="1056">If @match_info is not %NULL, calls g_match_info_unref(); otherwise does nothing. - + @@ -24230,8 +25608,8 @@ nothing. nullable="1" allow-none="1"> a #GMatchInfo, or %NULL + filename="glib/gregex.c" + line="1058">a #GMatchInfo, or %NULL @@ -24240,8 +25618,8 @@ nothing. c:identifier="g_match_info_get_match_count" version="2.14"> Retrieves the number of matched substrings (including substring 0, + filename="glib/gregex.c" + line="1246">Retrieves the number of matched substrings (including substring 0, that is the whole matched text), so 1 is returned if the pattern has no substrings in it and 0 is returned if the match failed. @@ -24249,18 +25627,18 @@ If the last match was obtained using the DFA algorithm, that is using g_regex_match_all() or g_regex_match_all_full(), the retrieved count is not that of the number of capturing parentheses but that of the number of matched substrings. - + Number of matched substrings, or -1 if an error occurred + filename="glib/gregex.c" + line="1259">Number of matched substrings, or -1 if an error occurred a #GMatchInfo structure + filename="glib/gregex.c" + line="1248">a #GMatchInfo structure @@ -24269,22 +25647,22 @@ the number of matched substrings. c:identifier="g_match_info_get_regex" version="2.14"> Returns #GRegex object used in @match_info. It belongs to Glib + filename="glib/gregex.c" + line="973">Returns #GRegex object used in @match_info. It belongs to Glib and must not be freed. Use g_regex_ref() if you need to keep it after you free @match_info object. - + #GRegex object used in @match_info + filename="glib/gregex.c" + line="981">#GRegex object used in @match_info a #GMatchInfo + filename="glib/gregex.c" + line="975">a #GMatchInfo @@ -24293,22 +25671,22 @@ after you free @match_info object. c:identifier="g_match_info_get_string" version="2.14"> Returns the string searched with @match_info. This is the + filename="glib/gregex.c" + line="992">Returns the string searched with @match_info. This is the string passed to g_regex_match() or g_regex_replace() so you may not free it before calling this function. - + the string searched with @match_info + filename="glib/gregex.c" + line="1000">the string searched with @match_info a #GMatchInfo + filename="glib/gregex.c" + line="994">a #GMatchInfo @@ -24317,8 +25695,8 @@ you may not free it before calling this function. c:identifier="g_match_info_is_partial_match" version="2.14"> Usually if the string passed to g_regex_match*() matches as far as + filename="glib/gregex.c" + line="1279">Usually if the string passed to g_regex_match*() matches as far as it goes, but is too short to match the entire pattern, %FALSE is returned. There are circumstances where it might be helpful to distinguish this case from other cases in which there is no match. @@ -24351,18 +25729,18 @@ There were formerly some restrictions on the pattern for partial matching. The restrictions no longer apply. See pcrepartial(3) for more information on partial matching. - + %TRUE if the match was partial, %FALSE otherwise + filename="glib/gregex.c" + line="1317">%TRUE if the match was partial, %FALSE otherwise a #GMatchInfo structure + filename="glib/gregex.c" + line="1281">a #GMatchInfo structure @@ -24371,21 +25749,21 @@ See pcrepartial(3) for more information on partial matching. c:identifier="g_match_info_matches" version="2.14"> Returns whether the previous match operation succeeded. - + filename="glib/gregex.c" + line="1227">Returns whether the previous match operation succeeded. + %TRUE if the previous match operation succeeded, + filename="glib/gregex.c" + line="1233">%TRUE if the previous match operation succeeded, %FALSE otherwise a #GMatchInfo structure + filename="glib/gregex.c" + line="1229">a #GMatchInfo structure @@ -24395,80 +25773,195 @@ See pcrepartial(3) for more information on partial matching. version="2.14" throws="1"> Scans for the next match using the same parameters of the previous + filename="glib/gregex.c" + line="1074">Scans for the next match using the same parameters of the previous call to g_regex_match_full() or g_regex_match() that returned @match_info. The match is done on the string passed to the match function, so you cannot free it before calling this function. - + %TRUE is the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="1086">%TRUE is the string matched, %FALSE otherwise a #GMatchInfo structure + filename="glib/gregex.c" + line="1076">a #GMatchInfo structure Increases reference count of @match_info by 1. - + filename="glib/gregex.c" + line="1011">Increases reference count of @match_info by 1. + @match_info + filename="glib/gregex.c" + line="1017">@match_info a #GMatchInfo + filename="glib/gregex.c" + line="1013">a #GMatchInfo Decreases reference count of @match_info by 1. When reference count drops + filename="glib/gregex.c" + line="1029">Decreases reference count of @match_info by 1. When reference count drops to zero, it frees all the memory associated with the match_info structure. - + a #GMatchInfo + filename="glib/gregex.c" + line="1031">a #GMatchInfo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A set of functions used to perform memory allocation. The same #GMemVTable must be used for all allocations in the same program; a call to g_mem_set_vtable(), if it exists, should be prior to any use of GLib. This functions related to this has been deprecated in 2.46, and no longer work. - + + function to use for allocating memory. - + @@ -24480,8 +25973,11 @@ This functions related to this has been deprecated in 2.46, and no longer work.< + function to use for reallocating memory. - + @@ -24496,8 +25992,11 @@ This functions related to this has been deprecated in 2.46, and no longer work.< + function to use to free memory. - + @@ -24509,8 +26008,11 @@ This functions related to this has been deprecated in 2.46, and no longer work.< + function to use for allocating zero-filled memory. - + @@ -24525,8 +26027,11 @@ This functions related to this has been deprecated in 2.46, and no longer work.< + function to use for allocating memory without a default error handler. - + @@ -24538,8 +26043,11 @@ This functions related to this has been deprecated in 2.46, and no longer work.< + function to use for reallocating memory without a default error handler. - + @@ -24556,8 +26064,8 @@ This functions related to this has been deprecated in 2.46, and no longer work.< The #GMutex struct is an opaque data structure to represent a mutex + filename="glib/gthread.c" + line="218">The #GMutex struct is an opaque data structure to represent a mutex (mutual exclusion). It can be used to protect data against shared access. @@ -24601,7 +26109,7 @@ If a #GMutex is placed in other contexts (eg: embedded in a struct) then it must be explicitly initialised using g_mutex_init(). A #GMutex should only be accessed via g_mutex_ functions. - + @@ -24612,31 +26120,57 @@ A #GMutex should only be accessed via g_mutex_ functions. Frees the resources allocated to a mutex with g_mutex_init(). + filename="glib/gthread.c" + line="1244">Frees the resources allocated to a mutex with g_mutex_init(). This function should not be used with a #GMutex that has been statically allocated. Calling g_mutex_clear() on a locked mutex leads to undefined behaviour. - + an initialized #GMutex + filename="glib/gthread.c" + line="1246">an initialized #GMutex + + + + + + Destroys a @mutex that has been created with g_mutex_new(). + +Calling g_mutex_free() on a locked mutex may result +in undefined behaviour. + GMutex can now be statically allocated, or embedded +in structures and initialised with g_mutex_init(). + + + + + + + a #GMutex Initializes a #GMutex so that it can be used. + filename="glib/gthread.c" + line="1207">Initializes a #GMutex so that it can be used. This function is useful to initialize a mutex that has been allocated on the stack, or as part of a larger structure. @@ -24660,23 +26194,23 @@ needed, use g_mutex_clear(). Calling g_mutex_init() on an already initialized #GMutex leads to undefined behaviour. - + an uninitialized #GMutex + filename="glib/gthread.c" + line="1209">an uninitialized #GMutex Locks @mutex. If @mutex is already locked by another thread, the + filename="glib/gthread.c" + line="1264">Locks @mutex. If @mutex is already locked by another thread, the current thread will block until @mutex is unlocked by the other thread. @@ -24684,23 +26218,23 @@ thread. non-recursive. As such, calling g_mutex_lock() on a #GMutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks). - + a #GMutex + filename="glib/gthread.c" + line="1266">a #GMutex Tries to lock @mutex. If @mutex is already locked by another thread, + filename="glib/gthread.c" + line="1299">Tries to lock @mutex. If @mutex is already locked by another thread, it immediately returns %FALSE. Otherwise it locks @mutex and returns %TRUE. @@ -24708,54 +26242,74 @@ it immediately returns %FALSE. Otherwise it locks @mutex and returns non-recursive. As such, calling g_mutex_lock() on a #GMutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks or arbitrary return values). - + %TRUE if @mutex could be locked + filename="glib/gthread.c" + line="1312">%TRUE if @mutex could be locked a #GMutex + filename="glib/gthread.c" + line="1301">a #GMutex Unlocks @mutex. If another thread is blocked in a g_mutex_lock() + filename="glib/gthread.c" + line="1283">Unlocks @mutex. If another thread is blocked in a g_mutex_lock() call for @mutex, it will become unblocked and can lock @mutex itself. Calling g_mutex_unlock() on a mutex that is not locked by the current thread leads to undefined behaviour. - + a #GMutex + filename="glib/gthread.c" + line="1285">a #GMutex + + Allocates and initializes a new #GMutex. + GMutex can now be statically allocated, or embedded +in structures and initialised with g_mutex_init(). + + + a newly allocated #GMutex. Use g_mutex_free() to free + + + Returns %TRUE if a #GNode is a leaf node. - + - a #GNode + a #GNode @@ -24763,12 +26317,14 @@ current thread leads to undefined behaviour. c:identifier="G_NODE_IS_ROOT" introspectable="0"> Returns %TRUE if a #GNode is the root of a tree. - + - a #GNode + a #GNode @@ -24776,77 +26332,77 @@ current thread leads to undefined behaviour. c:identifier="G_N_ELEMENTS" introspectable="0"> Determines the number of elements in an array. The array must be + filename="glib/docs.c" + line="1050">Determines the number of elements in an array. The array must be declared so the compiler knows its size at compile-time; this macro will not work on an array allocated on the heap, only static arrays or arrays on the stack. - + the array + filename="glib/docs.c" + line="1052">the array The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. - + filename="glib/gnode.c" + line="42">The #GNode struct represents one node in a [n-ary tree](data-structures.html#n-ary-trees). + contains the actual data of the node. + filename="glib/gnode.c" + line="44">contains the actual data of the node. points to the node's next sibling (a sibling is another + filename="glib/gnode.c" + line="45">points to the node's next sibling (a sibling is another #GNode with the same parent). points to the node's previous sibling. + filename="glib/gnode.c" + line="47">points to the node's previous sibling. points to the parent of the #GNode, or is %NULL if the + filename="glib/gnode.c" + line="48">points to the parent of the #GNode, or is %NULL if the #GNode is the root of the tree. points to the first child of the #GNode. The other + filename="glib/gnode.c" + line="50">points to the first child of the #GNode. The other children are accessed by using the @next pointer of each child. Gets the position of the first child of a #GNode + filename="glib/gnode.c" + line="1144">Gets the position of the first child of a #GNode which contains the given data. - + the index of the child of @node which contains + filename="glib/gnode.c" + line="1152">the index of the child of @node which contains @data, or -1 if the data is not found a #GNode + filename="glib/gnode.c" + line="1146">a #GNode nullable="1" allow-none="1"> the data to find + filename="glib/gnode.c" + line="1147">the data to find Gets the position of a #GNode with respect to its siblings. + filename="glib/gnode.c" + line="1111">Gets the position of a #GNode with respect to its siblings. @child must be a child of @node. The first child is numbered 0, the second 1, and so on. - + the position of @child with respect to its siblings + filename="glib/gnode.c" + line="1120">the position of @child with respect to its siblings a #GNode + filename="glib/gnode.c" + line="1113">a #GNode a child of @node + filename="glib/gnode.c" + line="1114">a child of @node - + Calls a function for each of the children of a #GNode. Note that it + filename="glib/gnode.c" + line="1218">Calls a function for each of the children of a #GNode. Note that it doesn't descend beneath the child nodes. @func must not do anything that would modify the structure of the tree. - + a #GNode + filename="glib/gnode.c" + line="1220">a #GNode which types of children are to be visited, one of + filename="glib/gnode.c" + line="1221">which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - + the function to call for each visited node + filename="glib/gnode.c" + line="1223">the function to call for each visited node nullable="1" allow-none="1"> user data to pass to the function + filename="glib/gnode.c" + line="1224">user data to pass to the function Recursively copies a #GNode (but does not deep-copy the data inside the + filename="glib/gnode.c" + line="172">Recursively copies a #GNode (but does not deep-copy the data inside the nodes, see g_node_copy_deep() if you need that). - + a new #GNode containing the same data pointers + filename="glib/gnode.c" + line="179">a new #GNode containing the same data pointers a #GNode + filename="glib/gnode.c" + line="174">a #GNode @@ -24957,27 +26514,30 @@ nodes, see g_node_copy_deep() if you need that). version="2.4" introspectable="0"> Recursively copies a #GNode and its data. - + filename="glib/gnode.c" + line="133">Recursively copies a #GNode and its data. + a new #GNode containing copies of the data in @node. + filename="glib/gnode.c" + line="142">a new #GNode containing copies of the data in @node. a #GNode + filename="glib/gnode.c" + line="135">a #GNode - + the function which is called to copy the data inside each node, - or %NULL to use the original data. + filename="glib/gnode.c" + line="136">the function which is called to copy the data + inside each node, or %NULL to use the original data. nullable="1" allow-none="1"> data to pass to @copy_func + filename="glib/gnode.c" + line="138">data to pass to @copy_func Gets the depth of a #GNode. + filename="glib/gnode.c" + line="399">Gets the depth of a #GNode. If @node is %NULL the depth is 0. The root node has a depth of 1. For the children of the root node the depth is 2. And so on. - + the depth of the #GNode + filename="glib/gnode.c" + line="408">the depth of the #GNode a #GNode + filename="glib/gnode.c" + line="401">a #GNode Removes @root and its children from the tree, freeing any memory + filename="glib/gnode.c" + line="91">Removes @root and its children from the tree, freeing any memory allocated. - + the root of the tree/subtree to destroy + filename="glib/gnode.c" + line="93">the root of the tree/subtree to destroy Finds a #GNode in a tree. - + filename="glib/gnode.c" + line="919">Finds a #GNode in a tree. + the found #GNode, or %NULL if the data is not found + filename="glib/gnode.c" + line="930">the found #GNode, or %NULL if the data is not found the root #GNode of the tree to search + filename="glib/gnode.c" + line="921">the root #GNode of the tree to search the order in which nodes are visited - %G_IN_ORDER, + filename="glib/gnode.c" + line="922">the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER which types of children are to be searched, one of + filename="glib/gnode.c" + line="924">which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES @@ -25069,8 +26629,8 @@ allocated. nullable="1" allow-none="1"> the data to find + filename="glib/gnode.c" + line="926">the data to find @@ -25079,26 +26639,26 @@ allocated. c:identifier="g_node_find_child" introspectable="0"> Finds the first child of a #GNode with the given data. - + filename="glib/gnode.c" + line="1070">Finds the first child of a #GNode with the given data. + the found child #GNode, or %NULL if the data is not found + filename="glib/gnode.c" + line="1079">the found child #GNode, or %NULL if the data is not found a #GNode + filename="glib/gnode.c" + line="1072">a #GNode which types of children are to be searched, one of + filename="glib/gnode.c" + line="1073">which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES @@ -25107,8 +26667,8 @@ allocated. nullable="1" allow-none="1"> the data to find + filename="glib/gnode.c" + line="1075">the data to find @@ -25117,21 +26677,21 @@ allocated. c:identifier="g_node_first_sibling" introspectable="0"> Gets the first sibling of a #GNode. + filename="glib/gnode.c" + line="1175">Gets the first sibling of a #GNode. This could possibly be the node itself. - + the first sibling of @node + filename="glib/gnode.c" + line="1182">the first sibling of @node a #GNode + filename="glib/gnode.c" + line="1177">a #GNode @@ -25140,53 +26700,53 @@ This could possibly be the node itself. c:identifier="g_node_get_root" introspectable="0"> Gets the root of a tree. - + filename="glib/gnode.c" + line="351">Gets the root of a tree. + the root of the tree + filename="glib/gnode.c" + line="357">the root of the tree a #GNode + filename="glib/gnode.c" + line="353">a #GNode Inserts a #GNode beneath the parent at the given position. - + filename="glib/gnode.c" + line="199">Inserts a #GNode beneath the parent at the given position. + the inserted #GNode + filename="glib/gnode.c" + line="208">the inserted #GNode the #GNode to place @node under + filename="glib/gnode.c" + line="201">the #GNode to place @node under the position to place @node at, with respect to its siblings + filename="glib/gnode.c" + line="202">the position to place @node at, with respect to its siblings If position is -1, @node is inserted as the last child of @parent the #GNode to insert + filename="glib/gnode.c" + line="204">the #GNode to insert @@ -25195,33 +26755,33 @@ This could possibly be the node itself. c:identifier="g_node_insert_after" introspectable="0"> Inserts a #GNode beneath the parent after the given sibling. - + filename="glib/gnode.c" + line="286">Inserts a #GNode beneath the parent after the given sibling. + the inserted #GNode + filename="glib/gnode.c" + line="295">the inserted #GNode the #GNode to place @node under + filename="glib/gnode.c" + line="288">the #GNode to place @node under the sibling #GNode to place @node after. + filename="glib/gnode.c" + line="289">the sibling #GNode to place @node after. If sibling is %NULL, the node is inserted as the first child of @parent. the #GNode to insert + filename="glib/gnode.c" + line="291">the #GNode to insert @@ -25230,61 +26790,61 @@ This could possibly be the node itself. c:identifier="g_node_insert_before" introspectable="0"> Inserts a #GNode beneath the parent before the given sibling. - + filename="glib/gnode.c" + line="229">Inserts a #GNode beneath the parent before the given sibling. + the inserted #GNode + filename="glib/gnode.c" + line="238">the inserted #GNode the #GNode to place @node under + filename="glib/gnode.c" + line="231">the #GNode to place @node under the sibling #GNode to place @node before. + filename="glib/gnode.c" + line="232">the sibling #GNode to place @node before. If sibling is %NULL, the node is inserted as the last child of @parent. the #GNode to insert + filename="glib/gnode.c" + line="234">the #GNode to insert Returns %TRUE if @node is an ancestor of @descendant. + filename="glib/gnode.c" + line="370">Returns %TRUE if @node is an ancestor of @descendant. This is true if node is the parent of @descendant, or if node is the grandparent of @descendant etc. - + %TRUE if @node is an ancestor of @descendant + filename="glib/gnode.c" + line="379">%TRUE if @node is an ancestor of @descendant a #GNode + filename="glib/gnode.c" + line="372">a #GNode a #GNode + filename="glib/gnode.c" + line="373">a #GNode @@ -25293,20 +26853,20 @@ or if node is the grandparent of @descendant etc. c:identifier="g_node_last_child" introspectable="0"> Gets the last child of a #GNode. - + filename="glib/gnode.c" + line="999">Gets the last child of a #GNode. + the last child of @node, or %NULL if @node has no children + filename="glib/gnode.c" + line="1005">the last child of @node, or %NULL if @node has no children a #GNode (must not be %NULL) + filename="glib/gnode.c" + line="1001">a #GNode (must not be %NULL) @@ -25315,91 +26875,91 @@ or if node is the grandparent of @descendant etc. c:identifier="g_node_last_sibling" introspectable="0"> Gets the last sibling of a #GNode. + filename="glib/gnode.c" + line="1198">Gets the last sibling of a #GNode. This could possibly be the node itself. - + the last sibling of @node + filename="glib/gnode.c" + line="1205">the last sibling of @node a #GNode + filename="glib/gnode.c" + line="1200">a #GNode Gets the maximum height of all branches beneath a #GNode. + filename="glib/gnode.c" + line="451">Gets the maximum height of all branches beneath a #GNode. This is the maximum distance from the #GNode to all leaf nodes. If @root is %NULL, 0 is returned. If @root has no children, 1 is returned. If @root has children, 2 is returned. And so on. - + the maximum height of the tree beneath @root + filename="glib/gnode.c" + line="461">the maximum height of the tree beneath @root a #GNode + filename="glib/gnode.c" + line="453">a #GNode Gets the number of children of a #GNode. - + filename="glib/gnode.c" + line="1045">Gets the number of children of a #GNode. + the number of children of @node + filename="glib/gnode.c" + line="1051">the number of children of @node a #GNode + filename="glib/gnode.c" + line="1047">a #GNode Gets the number of nodes in a tree. - + filename="glib/gnode.c" + line="975">Gets the number of nodes in a tree. + the number of nodes in the tree + filename="glib/gnode.c" + line="983">the number of nodes in the tree a #GNode + filename="glib/gnode.c" + line="977">a #GNode which types of children are to be counted, one of + filename="glib/gnode.c" + line="978">which types of children are to be counted, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES @@ -25409,123 +26969,124 @@ If @root is %NULL, 0 is returned. If @root has no children, c:identifier="g_node_nth_child" introspectable="0"> Gets a child of a #GNode, using the given index. + filename="glib/gnode.c" + line="1020">Gets a child of a #GNode, using the given index. The first child is at index 0. If the index is too big, %NULL is returned. - + the child of @node at index @n + filename="glib/gnode.c" + line="1029">the child of @node at index @n a #GNode + filename="glib/gnode.c" + line="1022">a #GNode the index of the desired child + filename="glib/gnode.c" + line="1023">the index of the desired child Inserts a #GNode as the first child of the given parent. - + filename="glib/gnode.c" + line="333">Inserts a #GNode as the first child of the given parent. + the inserted #GNode + filename="glib/gnode.c" + line="340">the inserted #GNode the #GNode to place the new #GNode under + filename="glib/gnode.c" + line="335">the #GNode to place the new #GNode under the #GNode to insert + filename="glib/gnode.c" + line="336">the #GNode to insert Reverses the order of the children of a #GNode. + filename="glib/gnode.c" + line="424">Reverses the order of the children of a #GNode. (It doesn't change the order of the grandchildren.) - + a #GNode. + filename="glib/gnode.c" + line="426">a #GNode. - + Traverses a tree starting at the given root #GNode. + filename="glib/gnode.c" + line="767">Traverses a tree starting at the given root #GNode. It calls the given function for each node visited. The traversal can be halted at any point by returning %TRUE from @func. @func must not do anything that would modify the structure of the tree. - + the root #GNode of the tree to traverse + filename="glib/gnode.c" + line="769">the root #GNode of the tree to traverse the order in which nodes are visited - %G_IN_ORDER, + filename="glib/gnode.c" + line="770">the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. which types of children are to be visited, one of + filename="glib/gnode.c" + line="772">which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES the maximum depth of the traversal. Nodes below this + filename="glib/gnode.c" + line="774">the maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If depth is 1, only the root is visited. If depth is 2, the root and its children are visited. And so on. - + the function to call for each visited #GNode + filename="glib/gnode.c" + line="778">the function to call for each visited #GNode user data to pass to the function + filename="glib/gnode.c" + line="779">user data to pass to the function Unlinks a #GNode from a tree, resulting in two separate trees. - + filename="glib/gnode.c" + line="109">Unlinks a #GNode from a tree, resulting in two separate trees. + the #GNode to unlink, which becomes the root of a new tree + filename="glib/gnode.c" + line="111">the #GNode to unlink, which becomes the root of a new tree Creates a new #GNode containing the given data. + filename="glib/gnode.c" + line="61">Creates a new #GNode containing the given data. Used to create the first node in a tree. - + a new #GNode + filename="glib/gnode.c" + line="68">a new #GNode @@ -25574,28 +27135,45 @@ Used to create the first node in a tree. nullable="1" allow-none="1"> the data of the new node + filename="glib/gnode.c" + line="63">the data of the new node + + + + + + + + + + + + + + + + + Specifies the type of function passed to g_node_children_foreach(). + filename="glib/gnode.c" + line="1230">Specifies the type of function passed to g_node_children_foreach(). The function is called with each child node, together with the user data passed to g_node_children_foreach(). - + a #GNode. + filename="glib/gnode.c" + line="1232">a #GNode. nullable="1" allow-none="1"> user data passed to g_node_children_foreach(). + filename="glib/gnode.c" + line="1233">user data passed to g_node_children_foreach(). Specifies the type of function passed to g_node_traverse(). The + filename="glib/gnode.c" + line="853">Specifies the type of function passed to g_node_traverse(). The function is called with each of the nodes visited, together with the user data passed to g_node_traverse(). If the function returns %TRUE, then the traversal is stopped. - + %TRUE to stop the traversal. + filename="glib/gnode.c" + line="863">%TRUE to stop the traversal. a #GNode. + filename="glib/gnode.c" + line="855">a #GNode. user data passed to g_node_traverse(). + filename="glib/gnode.c" + line="856">user data passed to g_node_traverse(). - + Defines how a Unicode string is transformed in a canonical + filename="glib/gunicode.h" + line="944">Defines how a Unicode string is transformed in a canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. Unicode strings should generally be normalized before comparing them. - - + standardize differences that do not affect the + filename="glib/gunicode.h" + line="946">standardize differences that do not affect the text content, such as the above-mentioned accent representation - + another name for %G_NORMALIZE_DEFAULT + filename="glib/gunicode.h" + line="948">another name for %G_NORMALIZE_DEFAULT + c:identifier="G_NORMALIZE_DEFAULT_COMPOSE" + glib:nick="default-compose" + glib:name="G_NORMALIZE_DEFAULT_COMPOSE"> like %G_NORMALIZE_DEFAULT, but with + filename="glib/gunicode.h" + line="949">like %G_NORMALIZE_DEFAULT, but with composed forms rather than a maximally decomposed form - + another name for %G_NORMALIZE_DEFAULT_COMPOSE + filename="glib/gunicode.h" + line="951">another name for %G_NORMALIZE_DEFAULT_COMPOSE - + beyond %G_NORMALIZE_DEFAULT also standardize the + filename="glib/gunicode.h" + line="952">beyond %G_NORMALIZE_DEFAULT also standardize the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same - + another name for %G_NORMALIZE_ALL + filename="glib/gunicode.h" + line="957">another name for %G_NORMALIZE_ALL + c:identifier="G_NORMALIZE_ALL_COMPOSE" + glib:nick="all-compose" + glib:name="G_NORMALIZE_ALL_COMPOSE"> like %G_NORMALIZE_ALL, but with composed + filename="glib/gunicode.h" + line="958">like %G_NORMALIZE_ALL, but with composed forms rather than a maximally decomposed form - + another name for %G_NORMALIZE_ALL_COMPOSE + filename="glib/gunicode.h" + line="960">another name for %G_NORMALIZE_ALL_COMPOSE c:type="GNumberParserError" glib:error-domain="g-number-parser-error-quark"> Error codes returned by functions converting a string to a number. - + filename="glib/gstrfuncs.h" + line="401">Error codes returned by functions converting a string to a number. + String was not a valid number. + filename="glib/gstrfuncs.h" + line="403">string was not a valid number String was a number, but out of bounds. + filename="glib/gstrfuncs.h" + line="404">string was a number, but out of bounds c:type="G_OPTION_REMAINING" version="2.6"> If a long option in the main group has this name, it is not treated as a + filename="glib/goption.h" + line="296">If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in `argv`. The option must be of type %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY @@ -25741,31 +27349,31 @@ or %G_OPTION_ARG_FILENAME_ARRAY. Using %G_OPTION_REMAINING instead of simply scanning `argv` for leftover arguments has the advantage that GOption takes care of necessary encoding conversions for strings or filenames. - + A #GOnce struct controls a one-time initialization function. Any + filename="glib/gthread.c" + line="530">A #GOnce struct controls a one-time initialization function. Any one-time initialization function must have its own unique #GOnce struct. - + the status of the #GOnce + filename="glib/gthread.c" + line="532">the status of the #GOnce the value returned by the call to the function, if @status + filename="glib/gthread.c" + line="533">the value returned by the call to the function, if @status is %G_ONCE_STATUS_READY - + @@ -25788,8 +27396,8 @@ struct. c:identifier="g_once_init_enter" version="2.14"> Function to be called when starting a critical initialization + filename="glib/gthread.c" + line="641">Function to be called when starting a critical initialization section. The argument @location must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with @@ -25814,30 +27422,82 @@ like this: While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + %TRUE if the initialization section should be entered, + filename="glib/gthread.c" + line="672">%TRUE if the initialization section should be entered, %FALSE and blocks otherwise - + location of a static initializable variable + filename="glib/gthread.c" + line="643">location of a static initializable variable containing 0 + + + + + + + + + + + + + This functions behaves in the same way as g_once_init_enter(), but can +can be used to initialize pointers (or #guintptr) instead of #gsize. + +|[<!-- language="C" --> + static MyStruct *interesting_struct = NULL; + + if (g_once_init_enter_pointer (&interesting_struct)) + { + MyStruct *setup_value = allocate_my_struct (); // initialization code here + + g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value)); + } + + // use interesting_struct here +]| + + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing `NULL` + + + + Counterpart to g_once_init_enter(). Expects a location of a static + filename="glib/gthread.c" + line="747">Counterpart to g_once_init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter() on this @@ -25845,144 +27505,183 @@ initialization variable. While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + - + location of a static initializable variable + filename="glib/gthread.c" + line="749">location of a static initializable variable containing 0 new non-0 value for *@value_location + filename="glib/gthread.c" + line="751">new non-0 value for `*value_location` + + Counterpart to g_once_init_enter_pointer(). Expects a location of a static +`NULL`-initialized initialization variable, and an initialization value +other than `NULL`. Sets the variable to the initialization value, and +releases concurrent threads blocking in g_once_init_enter_pointer() on this +initialization variable. + +This functions behaves in the same way as g_once_init_leave(), but +can be used to initialize pointers (or #guintptr) instead of #gsize. + + + + + + + location of a static initializable variable + containing `NULL` + + + + new non-`NULL` value for `*location` + + + + The possible statuses of a one-time initialization function + filename="glib/gthread.c" + line="555">The possible statuses of a one-time initialization function controlled by a #GOnce struct. - + the function has not been called yet. + filename="glib/gthread.c" + line="557">the function has not been called yet. the function call is currently in progress. + filename="glib/gthread.c" + line="558">the function call is currently in progress. the function has been called. + filename="glib/gthread.c" + line="559">the function has been called. The #GOptionArg enum values determine which type of extra argument the + filename="glib/goption.h" + line="116">The #GOptionArg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option: `-x arg`, with a long option: `--name arg` or combined in a single argument: `--name=arg`. - + No extra argument. This is useful for simple flags or booleans. + filename="glib/goption.h" + line="118">No extra argument. This is useful for simple flags or booleans. The option takes a UTF-8 string argument. + filename="glib/goption.h" + line="119">The option takes a UTF-8 string argument. The option takes an integer argument. + filename="glib/goption.h" + line="120">The option takes an integer argument. The option provides a callback (of type - #GOptionArgFunc) to parse the extra argument. + filename="glib/goption.h" + line="121">The option provides a callback (of type #GOptionArgFunc) + to parse the extra argument. The option takes a filename as argument, which will - be in the GLib filename encoding rather than UTF-8. + filename="glib/goption.h" + line="123">The option takes a filename as argument, which will + be in the GLib filename encoding rather than UTF-8. The option takes a string argument, multiple - uses of the option are collected into an array of strings. + filename="glib/goption.h" + line="125">The option takes a string argument, multiple + uses of the option are collected into an array of strings. The option takes a filename as argument, - multiple uses of the option are collected into an array of strings. + filename="glib/goption.h" + line="127">The option takes a filename as argument, + multiple uses of the option are collected into an array of strings. The option takes a double argument. The argument - can be formatted either for the user's locale or for the "C" locale. - Since 2.12 + filename="glib/goption.h" + line="129">The option takes a double argument. The argument + can be formatted either for the user's locale or for the "C" locale. + Since 2.12 The option takes a 64-bit integer. Like - %G_OPTION_ARG_INT but for larger numbers. The number can be in - decimal base, or in hexadecimal (when prefixed with `0x`, for - example, `0xffffffff`). Since 2.12 + filename="glib/goption.h" + line="132">The option takes a 64-bit integer. Like + %G_OPTION_ARG_INT but for larger numbers. The number can be in + decimal base, or in hexadecimal (when prefixed with `0x`, for + example, `0xffffffff`). Since 2.12 The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK + filename="glib/goption.h" + line="155">The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK options. - + %TRUE if the option was successfully parsed, %FALSE if an error + filename="glib/goption.h" + line="169">%TRUE if the option was successfully parsed, %FALSE if an error occurred, in which case @error should be set with g_set_error() The name of the option being parsed. This will be either a + filename="glib/goption.h" + line="157">The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. The value to be parsed. + filename="glib/goption.h" + line="160">The value to be parsed. nullable="1" allow-none="1"> User data added to the #GOptionGroup containing the option when it + filename="glib/goption.h" + line="161">User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() @@ -26002,184 +27701,34 @@ options. disguised="1" opaque="1"> The GOption commandline parser is intended to be a simpler replacement -for the popt library. It supports short and long commandline options, -as shown in the following example: - -`testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` - -The example demonstrates a number of features of the GOption -commandline parser: - -- Options can be single letters, prefixed by a single dash. - -- Multiple short options can be grouped behind a single dash. - -- Long options are prefixed by two consecutive dashes. - -- Options can have an extra argument, which can be a number, a string or - a filename. For long options, the extra argument can be appended with - an equals sign after the option name, which is useful if the extra - argument starts with a dash, which would otherwise cause it to be - interpreted as another option. - -- Non-option arguments are returned to the application as rest arguments. - -- An argument consisting solely of two dashes turns off further parsing, - any remaining arguments (even those starting with a dash) are returned - to the application as rest arguments. - -Another important feature of GOption is that it can automatically -generate nicely formatted help output. Unless it is explicitly turned -off with g_option_context_set_help_enabled(), GOption will recognize -the `--help`, `-?`, `--help-all` and `--help-groupname` options -(where `groupname` is the name of a #GOptionGroup) and write a text -similar to the one shown in the following example to stdout. - -|[ -Usage: - testtreemodel [OPTION...] - test tree model performance - -Help Options: - -h, --help Show help options - --help-all Show all help options - --help-gtk Show GTK Options - -Application Options: - -r, --repeats=N Average over N repetitions - -m, --max-size=M Test up to 2^M items - --display=DISPLAY X display to use - -v, --verbose Be verbose - -b, --beep Beep when done - --rand Randomize the data -]| - -GOption groups options in #GOptionGroups, which makes it easy to -incorporate options from multiple sources. The intended use for this is -to let applications collect option groups from the libraries it uses, -add them to their #GOptionContext, and parse all options by a single call -to g_option_context_parse(). See gtk_get_option_group() for an example. - -If an option is declared to be of type string or filename, GOption takes -care of converting it to the right encoding; strings are returned in -UTF-8, filenames are returned in the GLib filename encoding. Note that -this only works if setlocale() has been called before -g_option_context_parse(). - -Here is a complete example of setting up GOption to parse the example -commandline above and produce the example help output. -|[<!-- language="C" --> -static gint repeats = 2; -static gint max_size = 8; -static gboolean verbose = FALSE; -static gboolean beep = FALSE; -static gboolean randomize = FALSE; - -static GOptionEntry entries[] = -{ - { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" }, - { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, - { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, - { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, - { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, - G_OPTION_ENTRY_NULL -}; - -int -main (int argc, char *argv[]) -{ - GError *error = NULL; - GOptionContext *context; - - context = g_option_context_new ("- test tree model performance"); - g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); - g_option_context_add_group (context, gtk_get_option_group (TRUE)); - if (!g_option_context_parse (context, &argc, &argv, &error)) - { - g_print ("option parsing failed: %s\n", error->message); - exit (1); - } - - ... - -} -]| - -On UNIX systems, the argv that is passed to main() has no particular -encoding, even to the extent that different parts of it may have -different encodings. In general, normal arguments and flags will be -in the current locale and filenames should be considered to be opaque -byte strings. Proper use of %G_OPTION_ARG_FILENAME vs -%G_OPTION_ARG_STRING is therefore important. - -Note that on Windows, filenames do have an encoding, but using -#GOptionContext with the argv as passed to main() will result in a -program that can only accept commandline arguments with characters -from the system codepage. This can cause problems when attempting to -deal with filenames containing Unicode characters that fall outside -of the codepage. - -A solution to this is to use g_win32_get_command_line() and -g_option_context_parse_strv() which will properly handle full Unicode -filenames. If you are using #GApplication, this is done -automatically for you. - -The following example shows how you can use #GOptionContext directly -in order to correctly deal with Unicode filenames on Windows: - -|[<!-- language="C" --> -int -main (int argc, char **argv) -{ - GError *error = NULL; - GOptionContext *context; - gchar **args; - -#ifdef G_OS_WIN32 - args = g_win32_get_command_line (); -#else - args = g_strdupv (argv); -#endif - - // set up context - - if (!g_option_context_parse_strv (context, &args, &error)) - { - // error happened - } - - ... - - g_strfreev (args); - - ... -} -]| - + filename="glib/goption.h" + line="33">A `GOptionContext` struct defines which options +are accepted by the commandline option parser. The struct has only private +fields and should not be directly accessed. + Adds a #GOptionGroup to the @context, so that parsing with @context + filename="glib/goption.c" + line="403">Adds a #GOptionGroup to the @context, so that parsing with @context will recognize the options in the group. Note that this will take ownership of the @group and thus the @group should not be freed. - + a #GOptionContext + filename="glib/goption.c" + line="405">a #GOptionContext the group to add + filename="glib/goption.c" + line="406">the group to add @@ -26188,24 +27737,24 @@ ownership of the @group and thus the @group should not be freed. c:identifier="g_option_context_add_main_entries" version="2.6"> A convenience function which creates a main group if it doesn't + filename="glib/goption.c" + line="488">A convenience function which creates a main group if it doesn't exist, adds the @entries to it and sets the translation domain. - + a #GOptionContext + filename="glib/goption.c" + line="490">a #GOptionContext a %NULL-terminated array of #GOptionEntrys + filename="glib/goption.c" + line="491">a %NULL-terminated array of #GOptionEntrys @@ -26215,8 +27764,8 @@ exist, adds the @entries to it and sets the translation domain. nullable="1" allow-none="1"> a translation domain to use for translating + filename="glib/goption.c" + line="492">a translation domain to use for translating the `--help` output for the options in @entries with gettext(), or %NULL @@ -26225,21 +27774,21 @@ exist, adds the @entries to it and sets the translation domain. Frees context and all the groups which have been + filename="glib/goption.c" + line="223">Frees context and all the groups which have been added to it. Please note that parsed arguments need to be freed separately (see #GOptionEntry). - + - + a #GOptionContext + filename="glib/goption.c" + line="225">a #GOptionContext @@ -26248,20 +27797,20 @@ Please note that parsed arguments need to be freed separately (see c:identifier="g_option_context_get_description" version="2.12"> Returns the description. See g_option_context_set_description(). - + filename="glib/goption.c" + line="2552">Returns the description. See g_option_context_set_description(). + the description + filename="glib/goption.c" + line="2558">the description a #GOptionContext + filename="glib/goption.c" + line="2554">a #GOptionContext @@ -26270,32 +27819,32 @@ Please note that parsed arguments need to be freed separately (see c:identifier="g_option_context_get_help" version="2.14"> Returns a formatted, translated help text for the given context. + filename="glib/goption.c" + line="670">Returns a formatted, translated help text for the given context. To obtain the text produced by `--help`, call `g_option_context_get_help (context, TRUE, NULL)`. To obtain the text produced by `--help-all`, call `g_option_context_get_help (context, FALSE, NULL)`. To obtain the help text for an option group, call `g_option_context_get_help (context, FALSE, group)`. - + A newly allocated string containing the help text + filename="glib/goption.c" + line="684">A newly allocated string containing the help text a #GOptionContext + filename="glib/goption.c" + line="672">a #GOptionContext if %TRUE, only include the main group + filename="glib/goption.c" + line="673">if %TRUE, only include the main group the #GOptionGroup to create help for, or %NULL + filename="glib/goption.c" + line="674">the #GOptionGroup to create help for, or %NULL @@ -26313,21 +27862,21 @@ To obtain the help text for an option group, call c:identifier="g_option_context_get_help_enabled" version="2.6"> Returns whether automatic `--help` generation + filename="glib/goption.c" + line="279">Returns whether automatic `--help` generation is turned on for @context. See g_option_context_set_help_enabled(). - + %TRUE if automatic help generation is turned on. + filename="glib/goption.c" + line="286">%TRUE if automatic help generation is turned on. a #GOptionContext + filename="glib/goption.c" + line="281">a #GOptionContext @@ -26336,21 +27885,21 @@ is turned on for @context. See g_option_context_set_help_enabled(). c:identifier="g_option_context_get_ignore_unknown_options" version="2.6"> Returns whether unknown options are ignored or not. See + filename="glib/goption.c" + line="323">Returns whether unknown options are ignored or not. See g_option_context_set_ignore_unknown_options(). - + %TRUE if unknown options are ignored. + filename="glib/goption.c" + line="330">%TRUE if unknown options are ignored. a #GOptionContext + filename="glib/goption.c" + line="325">a #GOptionContext @@ -26359,13 +27908,13 @@ g_option_context_set_ignore_unknown_options(). c:identifier="g_option_context_get_main_group" version="2.6"> Returns a pointer to the main group of @context. - + filename="glib/goption.c" + line="468">Returns a pointer to the main group of @context. + the main group of @context, or %NULL if + filename="glib/goption.c" + line="474">the main group of @context, or %NULL if @context doesn't have a main group. Note that group belongs to @context and should not be modified or freed. @@ -26373,8 +27922,8 @@ g_option_context_set_ignore_unknown_options(). a #GOptionContext + filename="glib/goption.c" + line="470">a #GOptionContext @@ -26383,22 +27932,22 @@ g_option_context_set_ignore_unknown_options(). c:identifier="g_option_context_get_strict_posix" version="2.44"> Returns whether strict POSIX code is enabled. + filename="glib/goption.c" + line="383">Returns whether strict POSIX code is enabled. See g_option_context_set_strict_posix() for more information. - + %TRUE if strict POSIX is enabled, %FALSE otherwise. + filename="glib/goption.c" + line="391">%TRUE if strict POSIX is enabled, %FALSE otherwise. a #GOptionContext + filename="glib/goption.c" + line="385">a #GOptionContext @@ -26407,20 +27956,20 @@ See g_option_context_set_strict_posix() for more information. c:identifier="g_option_context_get_summary" version="2.12"> Returns the summary. See g_option_context_set_summary(). - + filename="glib/goption.c" + line="2509">Returns the summary. See g_option_context_set_summary(). + the summary + filename="glib/goption.c" + line="2515">the summary a #GOptionContext + filename="glib/goption.c" + line="2511">a #GOptionContext @@ -26430,8 +27979,8 @@ See g_option_context_set_strict_posix() for more information. version="2.6" throws="1"> Parses the command line arguments, recognizing options + filename="glib/goption.c" + line="1773">Parses the command line arguments, recognizing options which have been added to @context. A side-effect of calling this function is that g_set_prgname() will be called. @@ -26449,22 +27998,22 @@ If automatic `--help` support is enabled this function will produce help output to stdout and call `exit (0)`. -Note that function depends on the [current locale][setlocale] for -automatic character set conversion of string and filename -arguments. - +Note that function depends on the +[current locale](running.html#locale) for automatic +character set conversion of string and filename arguments. + %TRUE if the parsing was successful, + filename="glib/goption.c" + line="1802">%TRUE if the parsing was successful, %FALSE if an error occurred a #GOptionContext + filename="glib/goption.c" + line="1775">a #GOptionContext transfer-ownership="full" optional="1"> a pointer to the number of command line arguments + filename="glib/goption.c" + line="1776">a pointer to the number of command line arguments transfer-ownership="full" optional="1"> a pointer to the array of command line arguments + filename="glib/goption.c" + line="1777">a pointer to the array of command line arguments @@ -26496,8 +28045,8 @@ arguments. version="2.40" throws="1"> Parses the command line arguments. + filename="glib/goption.c" + line="2570">Parses the command line arguments. This function is similar to g_option_context_parse() except that it respects the normal memory rules when dealing with a strv instead of @@ -26513,19 +28062,19 @@ See g_win32_get_command_line() for a solution. This function is useful if you are trying to use #GOptionContext with #GApplication. - + %TRUE if the parsing was successful, + filename="glib/goption.c" + line="2596">%TRUE if the parsing was successful, %FALSE if an error occurred a #GOptionContext + filename="glib/goption.c" + line="2572">a #GOptionContext a pointer + filename="glib/goption.c" + line="2573">a pointer to the command line arguments (which must be in UTF-8 on Windows). Starting with GLib 2.62, @arguments can be %NULL, which matches g_option_context_parse(). - + @@ -26549,21 +28098,21 @@ This function is useful if you are trying to use #GOptionContext with c:identifier="g_option_context_set_description" version="2.12"> Adds a string to be displayed in `--help` output after the list + filename="glib/goption.c" + line="2527">Adds a string to be displayed in `--help` output after the list of options. This text often includes a bug reporting address. Note that the summary is translated (see g_option_context_set_translate_func()). - + a #GOptionContext + filename="glib/goption.c" + line="2529">a #GOptionContext nullable="1" allow-none="1"> a string to be shown in `--help` output + filename="glib/goption.c" + line="2530">a string to be shown in `--help` output after the list of options, or %NULL @@ -26582,26 +28131,26 @@ g_option_context_set_translate_func()). c:identifier="g_option_context_set_help_enabled" version="2.6"> Enables or disables automatic generation of `--help` output. + filename="glib/goption.c" + line="258">Enables or disables automatic generation of `--help` output. By default, g_option_context_parse() recognizes `--help`, `-h`, `-?`, `--help-all` and `--help-groupname` and creates suitable output to stdout. - + a #GOptionContext + filename="glib/goption.c" + line="260">a #GOptionContext %TRUE to enable `--help`, %FALSE to disable it + filename="glib/goption.c" + line="261">%TRUE to enable `--help`, %FALSE to disable it @@ -26610,29 +28159,29 @@ output to stdout. c:identifier="g_option_context_set_ignore_unknown_options" version="2.6"> Sets whether to ignore unknown options or not. If an argument is + filename="glib/goption.c" + line="298">Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the @argv array after parsing. By default, g_option_context_parse() treats unknown options as error. This setting does not affect non-option arguments (i.e. arguments which don't start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option. - + a #GOptionContext + filename="glib/goption.c" + line="300">a #GOptionContext %TRUE to ignore unknown options, %FALSE to produce + filename="glib/goption.c" + line="301">%TRUE to ignore unknown options, %FALSE to produce an error when unknown options are met @@ -26642,26 +28191,26 @@ determine whether a non-option belongs to a preceding unknown option. c:identifier="g_option_context_set_main_group" version="2.6"> Sets a #GOptionGroup as main group of the @context. + filename="glib/goption.c" + line="439">Sets a #GOptionGroup as main group of the @context. This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating `--help` output. - + a #GOptionContext + filename="glib/goption.c" + line="441">a #GOptionContext the group to set as main group + filename="glib/goption.c" + line="442">the group to set as main group @@ -26670,8 +28219,8 @@ treated differently when generating `--help` output. c:identifier="g_option_context_set_strict_posix" version="2.44"> Sets strict POSIX mode. + filename="glib/goption.c" + line="342">Sets strict POSIX mode. By default, this mode is disabled. @@ -26695,21 +28244,21 @@ options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand (which can be determined by examining the verb name, which should be present in argv[1] after parsing). - + a #GOptionContext + filename="glib/goption.c" + line="344">a #GOptionContext the new value + filename="glib/goption.c" + line="345">the new value @@ -26718,22 +28267,22 @@ parsing). c:identifier="g_option_context_set_summary" version="2.12"> Adds a string to be displayed in `--help` output before the list + filename="glib/goption.c" + line="2483">Adds a string to be displayed in `--help` output before the list of options. This is typically a summary of the program functionality. Note that the summary is translated (see g_option_context_set_translate_func() and g_option_context_set_translation_domain()). - + a #GOptionContext + filename="glib/goption.c" + line="2485">a #GOptionContext nullable="1" allow-none="1"> a string to be shown in `--help` output + filename="glib/goption.c" + line="2486">a string to be shown in `--help` output before the list of options, or %NULL @@ -26752,8 +28301,8 @@ g_option_context_set_translation_domain()). c:identifier="g_option_context_set_translate_func" version="2.12"> Sets the function which is used to translate the contexts + filename="glib/goption.c" + line="2424">Sets the function which is used to translate the contexts user-visible strings, for `--help` output. If @func is %NULL, strings are not translated. @@ -26764,15 +28313,15 @@ the summary (see g_option_context_set_summary()) and the description If you are using gettext(), you only need to set the translation domain, see g_option_context_set_translation_domain(). - + a #GOptionContext + filename="glib/goption.c" + line="2426">a #GOptionContext closure="1" destroy="2"> the #GTranslateFunc, or %NULL + filename="glib/goption.c" + line="2427">the #GTranslateFunc, or %NULL nullable="1" allow-none="1"> user data to pass to @func, or %NULL + filename="glib/goption.c" + line="2428">user data to pass to @func, or %NULL allow-none="1" scope="async"> a function which gets called to free @data, or %NULL + filename="glib/goption.c" + line="2429">a function which gets called to free @data, or %NULL @@ -26812,24 +28361,24 @@ domain, see g_option_context_set_translation_domain(). c:identifier="g_option_context_set_translation_domain" version="2.12"> A convenience function to use gettext() for translating + filename="glib/goption.c" + line="2461">A convenience function to use gettext() for translating user-visible strings. - + a #GOptionContext + filename="glib/goption.c" + line="2463">a #GOptionContext the domain to use + filename="glib/goption.c" + line="2464">the domain to use @@ -26839,8 +28388,8 @@ user-visible strings. version="2.6" introspectable="0"> Creates a new option context. + filename="glib/goption.c" + line="171">Creates a new option context. The @parameter_string can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by @@ -26859,11 +28408,11 @@ below the usage line, use g_option_context_set_summary(). Note that the @parameter_string is translated using the function set with g_option_context_set_translate_func(), so it should normally be passed untranslated. - - + + a newly created #GOptionContext, which must be + filename="glib/goption.c" + line="197">a newly created #GOptionContext, which must be freed with g_option_context_free() after use. @@ -26873,8 +28422,8 @@ it should normally be passed untranslated. nullable="1" allow-none="1"> a string which is displayed in + filename="glib/goption.c" + line="173">a string which is displayed in the first line of `--help` output, after the usage summary `programname [OPTION...]` @@ -26884,15 +28433,28 @@ it should normally be passed untranslated. A GOptionEntry struct defines a single option. To have an effect, they + filename="glib/goption.h" + line="239">- %G_OPTION_ARG_NONE: %gboolean + - %G_OPTION_ARG_STRING: %gchar* + - %G_OPTION_ARG_INT: %gint + - %G_OPTION_ARG_FILENAME: %gchar* + - %G_OPTION_ARG_STRING_ARRAY: %gchar** + - %G_OPTION_ARG_FILENAME_ARRAY: %gchar** + - %G_OPTION_ARG_DOUBLE: %gdouble + + If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME, + the location will contain a newly allocated string if the option + was given. That string needs to be freed by the callee using g_free(). + Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or + %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). +A GOptionEntry struct defines a single option. To have an effect, they must be added to a #GOptionGroup with g_option_context_add_main_entries() or g_option_group_add_entries(). - + The long name of an option can be used to specify it + filename="glib/goption.h" + line="241">The long name of an option can be used to specify it in a commandline as `--long_name`. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as @@ -26901,8 +28463,8 @@ or g_option_group_add_entries(). If an option has a short name, it can be specified + filename="glib/goption.h" + line="246">If an option has a short name, it can be specified `-short_name` in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. @@ -26910,50 +28472,38 @@ or g_option_group_add_entries(). Flags from #GOptionFlags + filename="glib/goption.h" + line="250">Flags from #GOptionFlags The type of the option, as a #GOptionArg + filename="glib/goption.h" + line="251">The type of the option, as a #GOptionArg If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data + filename="glib/goption.h" + line="252">If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of - the location depends on the @arg type: - - %G_OPTION_ARG_NONE: %gboolean - - %G_OPTION_ARG_STRING: %gchar* - - %G_OPTION_ARG_INT: %gint - - %G_OPTION_ARG_FILENAME: %gchar* - - %G_OPTION_ARG_STRING_ARRAY: %gchar** - - %G_OPTION_ARG_FILENAME_ARRAY: %gchar** - - %G_OPTION_ARG_DOUBLE: %gdouble - If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME, - the location will contain a newly allocated string if the option - was given. That string needs to be freed by the callee using g_free(). - Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or - %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). + the location depends on the @arg type: the description for the option in `--help` + filename="glib/goption.h" + line="271">the description for the option in `--help` output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). The placeholder to use for the extra argument parsed + filename="glib/goption.h" + line="274">The placeholder to use for the extra argument parsed by the option in `--help` output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). @@ -26964,15 +28514,15 @@ or g_option_group_add_entries(). c:type="GOptionError" glib:error-domain="g-option-context-error-quark"> Error codes returned by option parsing. - + filename="glib/goption.h" + line="219">Error codes returned by option parsing. + An option was not known to the parser. + filename="glib/goption.h" + line="221">An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). @@ -26980,34 +28530,34 @@ or g_option_group_add_entries(). value="1" c:identifier="G_OPTION_ERROR_BAD_VALUE"> A value couldn't be parsed. + filename="glib/goption.h" + line="224">A value couldn't be parsed. A #GOptionArgFunc callback failed. + filename="glib/goption.h" + line="225">A #GOptionArgFunc callback failed. The type of function to be used as callback when a parse error occurs. - + filename="glib/goption.h" + line="195">The type of function to be used as callback when a parse error occurs. + The active #GOptionContext + filename="glib/goption.h" + line="197">The active #GOptionContext The group to which the function belongs + filename="glib/goption.h" + line="198">The group to which the function belongs nullable="1" allow-none="1"> User data added to the #GOptionGroup containing the option when it + filename="glib/goption.h" + line="199">User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() @@ -27024,65 +28574,80 @@ or g_option_group_add_entries(). Flags which modify individual options. - - + + No flags. Since: 2.42. + filename="glib/goption.h" + line="84">No flags. The option doesn't appear in `--help` output. + filename="glib/goption.h" + line="58">The option doesn't appear in `--help` output. The option appears in the main section of the - `--help` output, even if it is defined in a group. + filename="glib/goption.h" + line="59">The option appears in the main section of the + `--help` output, even if it is defined in a group. For options of the %G_OPTION_ARG_NONE kind, this - flag indicates that the sense of the option is reversed. i.e. %FALSE will - be stored into the argument rather than %TRUE. + filename="glib/goption.h" + line="61">For options of the %G_OPTION_ARG_NONE kind, this + flag indicates that the sense of the option is reversed. i.e. %FALSE will + be stored into the argument rather than %TRUE. For options of the %G_OPTION_ARG_CALLBACK kind, - this flag indicates that the callback does not take any argument - (like a %G_OPTION_ARG_NONE option). Since 2.8 + filename="glib/goption.h" + line="64">For options of the %G_OPTION_ARG_CALLBACK kind, + this flag indicates that the callback does not take any argument + (like a %G_OPTION_ARG_NONE option). Since 2.8 For options of the %G_OPTION_ARG_CALLBACK - kind, this flag indicates that the argument should be passed to the - callback in the GLib filename encoding rather than UTF-8. Since 2.8 + filename="glib/goption.h" + line="67">For options of the %G_OPTION_ARG_CALLBACK + kind, this flag indicates that the argument should be passed to the + callback in the GLib filename encoding rather than UTF-8. Since 2.8 For options of the %G_OPTION_ARG_CALLBACK - kind, this flag indicates that the argument supply is optional. - If no argument is given then data of %GOptionParseFunc will be - set to NULL. Since 2.8 + filename="glib/goption.h" + line="70">For options of the %G_OPTION_ARG_CALLBACK + kind, this flag indicates that the argument supply is optional. + If no argument is given then data of %GOptionParseFunc will be + set to NULL. Since 2.8 This flag turns off the automatic conflict - resolution which prefixes long option names with `groupname-` if - there is a conflict. This option should only be used in situations - where aliasing is necessary to model some legacy commandline interface. - It is not safe to use this option, unless all option groups are under - your direct control. Since 2.8. + filename="glib/goption.h" + line="74">This flag turns off the automatic conflict + resolution which prefixes long option names with `groupname-` if + there is a conflict. This option should only be used in situations + where aliasing is necessary to model some legacy commandline interface. + It is not safe to use this option, unless all option groups are under + your direct control. Since 2.8. + + + This flag marks the option as deprecated in the `--help`. + +You should update the description of the option to describe what +the user should do in response to the deprecation, for instance: +remove the option, or replace it with another one. glib:get-type="g_option_group_get_type" c:symbol-prefix="option_group"> A `GOptionGroup` struct defines the options in a single group. The struct has only private fields and should not be directly accessed. @@ -27100,44 +28665,44 @@ All options in a group share the same translation function. Libraries which need to parse commandline options are expected to provide a function for getting a `GOptionGroup` holding their options, which the application can then add to its #GOptionContext. - + Creates a new #GOptionGroup. + filename="glib/goption.c" + line="2133">Creates a new #GOptionGroup. @description is typically used to provide a title for the group. If so, it is recommended that it’s written in title case, and has a trailing colon so that it matches the style of built-in GLib group titles such as ‘Application Options:’. - + a newly created option group. It should be added + filename="glib/goption.c" + line="2154">a newly created option group. It should be added to a #GOptionContext or freed with g_option_group_unref(). the name for the option group, this is used to provide + filename="glib/goption.c" + line="2135">the name for the option group, this is used to provide help for the options in this group with `--help-`@name a description for this group to be shown in + filename="glib/goption.c" + line="2137">a description for this group to be shown in `--help`. This string is translated using the translation domain or translation function of the group a description for the `--help-`@name option. + filename="glib/goption.c" + line="2140">a description for the `--help-`@name option. This string is translated using the translation domain or translation function of the group @@ -27147,8 +28712,8 @@ that it matches the style of built-in GLib group titles such as nullable="1" allow-none="1"> user data that will be passed to the pre- and post-parse hooks, + filename="glib/goption.c" + line="2143">user data that will be passed to the pre- and post-parse hooks, the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL @@ -27158,8 +28723,8 @@ that it matches the style of built-in GLib group titles such as allow-none="1" scope="async"> a function that will be called to free @user_data, or %NULL + filename="glib/goption.c" + line="2145">a function that will be called to free @user_data, or %NULL @@ -27168,23 +28733,23 @@ that it matches the style of built-in GLib group titles such as c:identifier="g_option_group_add_entries" version="2.6"> Adds the options specified in @entries to @group. - + filename="glib/goption.c" + line="2251">Adds the options specified in @entries to @group. + a #GOptionGroup + filename="glib/goption.c" + line="2253">a #GOptionGroup a %NULL-terminated array of #GOptionEntrys + filename="glib/goption.c" + line="2254">a %NULL-terminated array of #GOptionEntrys @@ -27197,39 +28762,39 @@ that it matches the style of built-in GLib group titles such as deprecated="1" deprecated-version="2.44"> Frees a #GOptionGroup. Note that you must not free groups + filename="glib/goption.c" + line="2181">Frees a #GOptionGroup. Note that you must not free groups which have been added to a #GOptionContext. Use g_option_group_unref() instead. - + a #GOptionGroup + filename="glib/goption.c" + line="2183">a #GOptionGroup Increments the reference count of @group by one. - + filename="glib/goption.c" + line="2198">Increments the reference count of @group by one. + a #GOptionGroup + filename="glib/goption.c" + line="2204">a #GOptionGroup a #GOptionGroup + filename="glib/goption.c" + line="2200">a #GOptionGroup @@ -27239,27 +28804,27 @@ which have been added to a #GOptionContext. version="2.6" introspectable="0"> Associates a function with @group which will be called + filename="glib/goption.c" + line="2340">Associates a function with @group which will be called from g_option_context_parse() when an error occurs. Note that the user data to be passed to @error_func can be specified when constructing the group with g_option_group_new(). - + a #GOptionGroup + filename="glib/goption.c" + line="2342">a #GOptionGroup a function to call when an error occurs + filename="glib/goption.c" + line="2343">a function to call when an error occurs @@ -27269,23 +28834,23 @@ specified when constructing the group with g_option_group_new(). version="2.6" introspectable="0"> Associates two functions with @group which will be called + filename="glib/goption.c" + line="2313">Associates two functions with @group which will be called from g_option_context_parse() before the first option is parsed and after the last option has been parsed, respectively. Note that the user data to be passed to @pre_parse_func and @post_parse_func can be specified when constructing the group with g_option_group_new(). - + a #GOptionGroup + filename="glib/goption.c" + line="2315">a #GOptionGroup nullable="1" allow-none="1"> a function to call before parsing, or %NULL + filename="glib/goption.c" + line="2316">a function to call before parsing, or %NULL nullable="1" allow-none="1"> a function to call after parsing, or %NULL + filename="glib/goption.c" + line="2317">a function to call after parsing, or %NULL @@ -27312,22 +28877,22 @@ with g_option_group_new(). c:identifier="g_option_group_set_translate_func" version="2.6"> Sets the function which is used to translate user-visible strings, + filename="glib/goption.c" + line="2363">Sets the function which is used to translate user-visible strings, for `--help` output. Different groups can use different #GTranslateFuncs. If @func is %NULL, strings are not translated. If you are using gettext(), you only need to set the translation domain, see g_option_group_set_translation_domain(). - + a #GOptionGroup + filename="glib/goption.c" + line="2365">a #GOptionGroup closure="1" destroy="2"> the #GTranslateFunc, or %NULL + filename="glib/goption.c" + line="2366">the #GTranslateFunc, or %NULL nullable="1" allow-none="1"> user data to pass to @func, or %NULL + filename="glib/goption.c" + line="2367">user data to pass to @func, or %NULL allow-none="1" scope="async"> a function which gets called to free @data, or %NULL + filename="glib/goption.c" + line="2368">a function which gets called to free @data, or %NULL @@ -27367,43 +28932,43 @@ domain, see g_option_group_set_translation_domain(). c:identifier="g_option_group_set_translation_domain" version="2.6"> A convenience function to use gettext() for translating + filename="glib/goption.c" + line="2402">A convenience function to use gettext() for translating user-visible strings. - + a #GOptionGroup + filename="glib/goption.c" + line="2404">a #GOptionGroup the domain to use + filename="glib/goption.c" + line="2405">the domain to use Decrements the reference count of @group by one. + filename="glib/goption.c" + line="2218">Decrements the reference count of @group by one. If the reference count drops to 0, the @group will be freed. and all memory allocated by the @group is released. - + a #GOptionGroup + filename="glib/goption.c" + line="2220">a #GOptionGroup @@ -27411,27 +28976,27 @@ and all memory allocated by the @group is released. The type of function that can be called before and after parsing. - + filename="glib/goption.h" + line="177">The type of function that can be called before and after parsing. + %TRUE if the function completed successfully, %FALSE if an error + filename="glib/goption.h" + line="187">%TRUE if the function completed successfully, %FALSE if an error occurred, in which case @error should be set with g_set_error() The active #GOptionContext + filename="glib/goption.h" + line="179">The active #GOptionContext The group to which the function belongs + filename="glib/goption.h" + line="180">The group to which the function belongs nullable="1" allow-none="1"> User data added to the #GOptionGroup containing the option when it + filename="glib/goption.h" + line="181">User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + + Yields a new preprocessor pasted identifier +@identifier1identifier2 from its expanded +arguments @identifier1 and @identifier2. For example, +the following code: +|[<!-- language="C" --> +#define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) +const gchar *name = GET (traveller, name); +const gchar *quest = GET (traveller, quest); +GdkColor *favourite = GET (traveller, favourite_colour); +]| + +is transformed by the preprocessor into: +|[<!-- language="C" --> +const gchar *name = traveller_get_name (traveller); +const gchar *quest = traveller_get_quest (traveller); +GdkColor *favourite = traveller_get_favourite_colour (traveller); +]| + + + + an identifier + + + an identifier + + + + + + + + + + + + Specifies one of the possible types of byte order + filename="glib/docs.c" + line="123">Specifies one of the possible types of byte order (currently unused). See %G_BYTE_ORDER. - + The value of pi (ratio of circle's circumference to its diameter). - + filename="glib/docs.c" + line="823">The value of pi (ratio of circle's circumference to its diameter). + A format specifier that can be used in printf()-style format strings + filename="glib/gmain.h" + line="172">A format specifier that can be used in printf()-style format strings when printing a #GPid. - + Pi divided by 2. - + filename="glib/docs.c" + line="829">Pi divided by 2. + Pi divided by 4. - + filename="glib/docs.c" + line="835">Pi divided by 4. + A format specifier that can be used in printf()-style format strings when printing the @fd member of a #GPollFD. - + Use this for default priority event sources. + filename="glib/gmain.h" + line="422">Use this for default priority event sources. In GLib this priority is used when adding timeout functions -with g_timeout_add(). In GDK this priority is used for events +with [func@GLib.timeout_add]. In GDK this priority is used for events from the X server. - + Use this for default priority idle functions. + filename="glib/gmain.h" + line="445">Use this for default priority idle functions. In GLib this priority is used when adding idle functions with -g_idle_add(). - +[func@GLib.idle_add]. + Use this for high priority event sources. + filename="glib/gmain.h" + line="413">Use this for high priority event sources. It is not used within GLib or GTK. - + Use this for high priority idle functions. + filename="glib/gmain.h" + line="433">Use this for high priority idle functions. GTK uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and %G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to ensure that any pending resizes are processed before any pending redraws, so that widgets are not redrawn twice unnecessarily.) - + Use this for very low priority background tasks. + filename="glib/gmain.h" + line="455">Use this for very low priority background tasks. It is not used within GLib or GTK. - + version="2.32" introspectable="0"> A macro to assist with the static initialisation of a #GPrivate. + filename="glib/gthread.c" + line="1806">A macro to assist with the static initialisation of a #GPrivate. This macro is useful for the case that a #GDestroyNotify function should be associated with the key. This is needed when the key will be @@ -27598,27 +29211,23 @@ set_local_count (gint count) g_private_set (&count_key, GINT_TO_POINTER (count)); } ]| - + a #GDestroyNotify + filename="glib/gthread.c" + line="1808">a #GDestroyNotify - - `GPathBuf` is a helper type that allows you to easily build paths from + + `GPathBuf` is a helper type that allows you to easily build paths from individual elements, using the platform specific conventions for path separators. -|[<!-- language="C" --> +```c g_auto (GPathBuf) path; g_path_buf_init (&path); @@ -27629,11 +29238,11 @@ g_path_buf_push (&path, "echo"); g_autofree char *echo = g_path_buf_to_path (&path); g_assert_cmpstr (echo, ==, "/usr/bin/echo"); -]| +``` You can also load a full path and then operate on its components: -|[<!-- language="C" --> +```c g_auto (GPathBuf) path; g_path_buf_init_from_path (&path, "/usr/bin/echo"); @@ -27643,10 +29252,8 @@ g_path_buf_push (&path, "sh"); g_autofree char *sh = g_path_buf_to_path (&path); g_assert_cmpstr (sh, ==, "/usr/bin/sh"); -]| - -`GPathBuf` is available since GLib 2.76. - +``` + @@ -27654,21 +29261,21 @@ g_assert_cmpstr (sh, ==, "/usr/bin/sh"); Clears the contents of the path buffer. + filename="glib/gpathbuf.c" + line="115">Clears the contents of the path buffer. This function should be use to free the resources in a stack-allocated `GPathBuf` initialized using g_path_buf_init() or g_path_buf_init_from_path(). - + a path buffer + filename="glib/gpathbuf.c" + line="117">a path buffer @@ -27677,24 +29284,24 @@ g_path_buf_init_from_path(). c:identifier="g_path_buf_clear_to_path" version="2.76"> Clears the contents of the path buffer and returns the built path. + filename="glib/gpathbuf.c" + line="138">Clears the contents of the path buffer and returns the built path. This function returns `NULL` if the `GPathBuf` is empty. See also: g_path_buf_to_path() - + the built path + filename="glib/gpathbuf.c" + line="148">the built path a path buffer + filename="glib/gpathbuf.c" + line="140">a path buffer @@ -27704,37 +29311,37 @@ See also: g_path_buf_to_path() version="2.76" introspectable="0"> Copies the contents of a path buffer into a new `GPathBuf`. - + filename="glib/gpathbuf.c" + line="241">Copies the contents of a path buffer into a new `GPathBuf`. + the newly allocated path buffer + filename="glib/gpathbuf.c" + line="247">the newly allocated path buffer a path buffer + filename="glib/gpathbuf.c" + line="243">a path buffer Frees a `GPathBuf` allocated by g_path_buf_new(). - + filename="glib/gpathbuf.c" + line="196">Frees a `GPathBuf` allocated by g_path_buf_new(). + a path buffer + filename="glib/gpathbuf.c" + line="198">a path buffer @@ -27743,45 +29350,45 @@ See also: g_path_buf_to_path() c:identifier="g_path_buf_free_to_path" version="2.76"> Frees a `GPathBuf` allocated by g_path_buf_new(), and + filename="glib/gpathbuf.c" + line="213">Frees a `GPathBuf` allocated by g_path_buf_new(), and returns the path inside the buffer. This function returns `NULL` if the `GPathBuf` is empty. See also: g_path_buf_to_path() - + the path + filename="glib/gpathbuf.c" + line="224">the path a path buffer + filename="glib/gpathbuf.c" + line="215">a path buffer Initializes a `GPathBuf` instance. - + filename="glib/gpathbuf.c" + line="68">Initializes a `GPathBuf` instance. + the initialized path builder + filename="glib/gpathbuf.c" + line="74">the initialized path builder a path buffer + filename="glib/gpathbuf.c" + line="70">a path buffer @@ -27790,20 +29397,20 @@ See also: g_path_buf_to_path() c:identifier="g_path_buf_init_from_path" version="2.76"> Initializes a `GPathBuf` instance with the given path. - + filename="glib/gpathbuf.c" + line="89">Initializes a `GPathBuf` instance with the given path. + the initialized path builder + filename="glib/gpathbuf.c" + line="96">the initialized path builder a path buffer + filename="glib/gpathbuf.c" + line="91">a path buffer nullable="1" allow-none="1"> a file system path + filename="glib/gpathbuf.c" + line="92">a file system path Removes the last element of the path buffer. + filename="glib/gpathbuf.c" + line="382">Removes the last element of the path buffer. If there is only one element in the path buffer (for example, `/` on Unix-like operating systems or the drive on Windows systems), it will @@ -27843,26 +29450,26 @@ g_path_buf_clear (&cmp); g_path_buf_clear (&buf); ]| - + `TRUE` if the buffer was modified and `FALSE` otherwise + filename="glib/gpathbuf.c" + line="410">`TRUE` if the buffer was modified and `FALSE` otherwise a path buffer + filename="glib/gpathbuf.c" + line="384">a path buffer Extends the given path buffer with @path. + filename="glib/gpathbuf.c" + line="280">Extends the given path buffer with @path. If @path is absolute, it replaces the current path. @@ -27889,24 +29496,24 @@ g_path_buf_clear (&cmp); g_path_buf_clear (&buf); ]| - + the same pointer to @buf, for convenience + filename="glib/gpathbuf.c" + line="313">the same pointer to @buf, for convenience a path buffer + filename="glib/gpathbuf.c" + line="282">a path buffer a path + filename="glib/gpathbuf.c" + line="283">a path @@ -27915,25 +29522,25 @@ g_path_buf_clear (&buf); c:identifier="g_path_buf_set_extension" version="2.76"> Adds an extension to the file name in the path buffer. + filename="glib/gpathbuf.c" + line="488">Adds an extension to the file name in the path buffer. If @extension is `NULL`, the extension will be unset. If the path buffer does not have a file name set, this function returns `FALSE` and leaves the path buffer unmodified. - + `TRUE` if the extension was replaced, and `FALSE` otherwise + filename="glib/gpathbuf.c" + line="500">`TRUE` if the extension was replaced, and `FALSE` otherwise a path buffer + filename="glib/gpathbuf.c" + line="490">a path buffer the file extension + filename="glib/gpathbuf.c" + line="491">the file extension @@ -27951,8 +29558,8 @@ If the path buffer does not have a file name set, this function returns c:identifier="g_path_buf_set_filename" version="2.76"> Sets the file name of the path. + filename="glib/gpathbuf.c" + line="432">Sets the file name of the path. If the path buffer is empty, the filename is left unset and this function returns `FALSE`. @@ -27982,57 +29589,57 @@ g_path_buf_clear (&cmp); g_path_buf_clear (&buf); ]| - + `TRUE` if the file name was replaced, and `FALSE` otherwise + filename="glib/gpathbuf.c" + line="468">`TRUE` if the file name was replaced, and `FALSE` otherwise a path buffer + filename="glib/gpathbuf.c" + line="434">a path buffer the file name in the path + filename="glib/gpathbuf.c" + line="435">the file name in the path Retrieves the built path from the path buffer. + filename="glib/gpathbuf.c" + line="518">Retrieves the built path from the path buffer. On Windows, the result contains backslashes as directory separators, even if forward slashes were used in input. If the path buffer is empty, this function returns `NULL`. - + the path + filename="glib/gpathbuf.c" + line="529">the path a path buffer + filename="glib/gpathbuf.c" + line="520">a path buffer Compares two path buffers for equality and returns `TRUE` + filename="glib/gpathbuf.c" + line="555">Compares two path buffers for equality and returns `TRUE` if they are equal. The path inside the paths buffers are not going to be normalized, @@ -28041,25 +29648,25 @@ equal. This function can be passed to g_hash_table_new() as the `key_equal_func` parameter. - + `TRUE` if the two path buffers are equal, + filename="glib/gpathbuf.c" + line="570">`TRUE` if the two path buffers are equal, and `FALSE` otherwise a path buffer to compare + filename="glib/gpathbuf.c" + line="557">a path buffer to compare a path buffer to compare + filename="glib/gpathbuf.c" + line="558">a path buffer to compare @@ -28069,13 +29676,13 @@ This function can be passed to g_hash_table_new() as the version="2.76" introspectable="0"> Allocates a new `GPathBuf`. - + filename="glib/gpathbuf.c" + line="165">Allocates a new `GPathBuf`. + the newly allocated path buffer + filename="glib/gpathbuf.c" + line="170">the newly allocated path buffer @@ -28084,13 +29691,13 @@ This function can be passed to g_hash_table_new() as the version="2.76" introspectable="0"> Allocates a new `GPathBuf` with the given @path. - + filename="glib/gpathbuf.c" + line="180">Allocates a new `GPathBuf` with the given @path. + the newly allocated path buffer + filename="glib/gpathbuf.c" + line="186">the newly allocated path buffer @@ -28099,8 +29706,8 @@ This function can be passed to g_hash_table_new() as the nullable="1" allow-none="1"> the path used to initialize the buffer + filename="glib/gpathbuf.c" + line="182">the path used to initialize the buffer @@ -28113,139 +29720,155 @@ This function can be passed to g_hash_table_new() as the glib:get-type="g_pattern_spec_get_type" c:symbol-prefix="pattern_spec"> A GPatternSpec struct is the 'compiled' form of a pattern. This -structure is opaque and its fields cannot be accessed directly. - + filename="glib/gpattern.c" + line="33">A `GPatternSpec` struct is the ‘compiled’ form of a glob-style pattern. + +The [func@GLib.pattern_match_simple] and [method@GLib.PatternSpec.match] functions +match a string against a pattern containing `*` and `?` wildcards with similar +semantics as the standard `glob()` function: `*` matches an arbitrary, +possibly empty, string, `?` matches an arbitrary character. + +Note that in contrast to [`glob()`](man:glob(3)), the `/` character can be +matched by the wildcards, there are no `[…]` character ranges and `*` and `?` +can not be escaped to include them literally in a pattern. + +When multiple strings must be matched against the same pattern, it is better +to compile the pattern to a [struct@GLib.PatternSpec] using +[ctor@GLib.PatternSpec.new] and use [method@GLib.PatternSpec.match_string] +instead of [func@GLib.pattern_match_simple]. This avoids the overhead of repeated +pattern compilation. + Compiles a pattern to a #GPatternSpec. - + filename="glib/gpattern.c" + line="279">Compiles a pattern to a [type@GLib.PatternSpec]. + a newly-allocated #GPatternSpec + filename="glib/gpattern.c" + line="285">a newly-allocated [type@GLib.PatternSpec] a zero-terminated UTF-8 encoded string + filename="glib/gpattern.c" + line="281">a zero-terminated UTF-8 encoded string Copies @pspec in a new #GPatternSpec. - + filename="glib/gpattern.c" + line="395">Copies @pspec in a new [type@GLib.PatternSpec]. + a copy of @pspec. + filename="glib/gpattern.c" + line="401">a copy of @pspec. a #GPatternSpec + filename="glib/gpattern.c" + line="397">a #GPatternSpec Compares two compiled pattern specs and returns whether they will + filename="glib/gpattern.c" + line="434">Compares two compiled pattern specs and returns whether they will match the same set of strings. - + Whether the compiled patterns are equal + filename="glib/gpattern.c" + line="442">Whether the compiled patterns are equal a #GPatternSpec + filename="glib/gpattern.c" + line="436">a #GPatternSpec another #GPatternSpec + filename="glib/gpattern.c" + line="437">another #GPatternSpec Frees the memory allocated for the #GPatternSpec. - + filename="glib/gpattern.c" + line="419">Frees the memory allocated for the [type@GLib.PatternSpec]. + a #GPatternSpec + filename="glib/gpattern.c" + line="421">a #GPatternSpec Matches a string against a compiled pattern. Passing the correct + filename="glib/gpattern.c" + line="154">Matches a string against a compiled pattern. + +Passing the correct length of the string given is mandatory. The reversed string can be -omitted by passing %NULL, this is more efficient if the reversed +omitted by passing `NULL`, this is more efficient if the reversed version of the string to be matched is not at hand, as -g_pattern_match() will only construct it if the compiled pattern +[method@GLib.PatternSpec.match] will only construct it if the compiled pattern requires reverse matches. Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that -some patterns will require a reversed string. In this case, it's +some patterns will require a reversed string. In this case, it’s more efficient to provide the reversed string to avoid multiple -constructions thereof in the various calls to g_pattern_match(). +constructions thereof in the various calls to [method@GLib.PatternSpec.match]. Note also that the reverse of a UTF-8 encoded string can in general -not be obtained by g_strreverse(). This works only if the string +not be obtained by [func@GLib.strreverse]. This works only if the string does not contain any multibyte characters. GLib offers the -g_utf8_strreverse() function to reverse UTF-8 encoded strings. - +[func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings. + %TRUE if @string matches @pspec + filename="glib/gpattern.c" + line="182">%TRUE if @string matches @pspec a #GPatternSpec + filename="glib/gpattern.c" + line="156">a #GPatternSpec the length of @string (in bytes, i.e. strlen(), - not g_utf8_strlen()) + filename="glib/gpattern.c" + line="157">the length of @string (in bytes, i.e. `strlen()`, + not [func@GLib.utf8_strlen]) the UTF-8 encoded string to match + filename="glib/gpattern.c" + line="159">the UTF-8 encoded string to match nullable="1" allow-none="1"> the reverse of @string or %NULL + filename="glib/gpattern.c" + line="160">the reverse of @string @@ -28263,28 +29886,30 @@ g_utf8_strreverse() function to reverse UTF-8 encoded strings. c:identifier="g_pattern_spec_match_string" version="2.70"> Matches a string against a compiled pattern. If the string is to be + filename="glib/gpattern.c" + line="456">Matches a string against a compiled pattern. + +If the string is to be matched against more than one pattern, consider using -g_pattern_match() instead while supplying the reversed string. - +[method@GLib.PatternSpec.match] instead while supplying the reversed string. + %TRUE if @string matches @pspec + filename="glib/gpattern.c" + line="467">%TRUE if @string matches @pspec a #GPatternSpec + filename="glib/gpattern.c" + line="458">a #GPatternSpec the UTF-8 encoded string to match + filename="glib/gpattern.c" + line="459">the UTF-8 encoded string to match @@ -28296,19 +29921,19 @@ g_pattern_match() instead while supplying the reversed string. glib:get-type="g_pollfd_get_type" c:symbol-prefix="pollfd"> Represents a file descriptor, which events to poll for, and which events occurred. - + the file descriptor to poll (or a HANDLE on Win32) a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and @@ -28317,7 +29942,7 @@ occurred. a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. @@ -28325,13 +29950,13 @@ occurred. Specifies the type of function passed to g_main_context_set_poll_func(). The semantics of the function should match those of the poll() system call. - + the number of #GPollFD elements which have events or errors reported, or -1 if an error occurred. @@ -28339,19 +29964,19 @@ The semantics of the function should match those of the poll() system call. an array of #GPollFD elements the number of elements in @ufds the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. @@ -28360,26 +29985,26 @@ The semantics of the function should match those of the poll() system call. Specifies the type of the print handler functions. + filename="glib/gmessages.h" + line="518">Specifies the type of the print handler functions. These are called with the complete formatted string to output. - + the message to output + filename="glib/gmessages.h" + line="520">the message to output The #GPrivate struct is an opaque data structure to represent a + filename="glib/gthread.c" + line="1784">The #GPrivate struct is an opaque data structure to represent a thread-local data key. It is approximately equivalent to the pthread_setspecific()/pthread_getspecific() APIs on POSIX and to TlsSetValue()/TlsGetValue() on Windows. @@ -28396,7 +30021,7 @@ See G_PRIVATE_INIT() for a couple of examples. The #GPrivate structure should be considered opaque. It should only be accessed via the g_private_ functions. - + @@ -28410,46 +30035,46 @@ be accessed via the g_private_ functions. Returns the current value of the thread local variable @key. + filename="glib/gthread.c" + line="1860">Returns the current value of the thread local variable @key. If the value has not yet been set in this thread, %NULL is returned. Values are never copied between threads (when a new thread is created, for example). - + the thread-local value + filename="glib/gthread.c" + line="1870">the thread-local value a #GPrivate + filename="glib/gthread.c" + line="1862">a #GPrivate Sets the thread local variable @key to have the value @value in the + filename="glib/gthread.c" + line="1896">Sets the thread local variable @key to have the value @value in the current thread. This function differs from g_private_set() in the following way: if the previous value was non-%NULL then the #GDestroyNotify handler for @key is run on it. - + a #GPrivate + filename="glib/gthread.c" + line="1898">a #GPrivate the new value + filename="glib/gthread.c" + line="1899">the new value Sets the thread local variable @key to have the value @value in the + filename="glib/gthread.c" + line="1878">Sets the thread local variable @key to have the value @value in the current thread. This function differs from g_private_replace() in the following way: the #GDestroyNotify for @key is not called on the old value. - + a #GPrivate + filename="glib/gthread.c" + line="1880">a #GPrivate nullable="1" allow-none="1"> the new value + filename="glib/gthread.c" + line="1881">the new value + + Creates a new #GPrivate. + dynamic allocation of #GPrivate is a bad idea. Use + static storage and G_PRIVATE_INIT() instead. + + + a newly allocated #GPrivate (which can never be destroyed) + + + + + a #GDestroyNotify + + + + glib:get-type="g_ptr_array_get_type" c:symbol-prefix="ptr_array"> Contains the public fields of a pointer array. - + filename="glib/garray.c" + line="1086">Contains the public fields of a pointer array. + points to the array of pointers, which may be moved when the + filename="glib/garray.c" + line="1088">points to the array of pointers, which may be moved when the array grows number of pointers in the array + filename="glib/garray.c" + line="1090">number of pointers in the array Adds a pointer to the end of the pointer array. The array will grow + filename="glib/garray.c" + line="2204">Adds a pointer to the end of the pointer array. The array will grow in size automatically if necessary. - + a #GPtrArray + filename="glib/garray.c" + line="2206">a #GPtrArray @@ -28539,8 +30190,8 @@ in size automatically if necessary. nullable="1" allow-none="1"> the pointer to add + filename="glib/garray.c" + line="2207">the pointer to add @@ -28550,8 +30201,8 @@ in size automatically if necessary. version="2.62" introspectable="0"> Makes a full (deep) copy of a #GPtrArray. + filename="glib/garray.c" + line="1485">Makes a full (deep) copy of a #GPtrArray. @func, as a #GCopyFunc, takes two arguments, the data to be copied and a @user_data pointer. On common processor architectures, it's safe to @@ -28565,11 +30216,11 @@ pointing to) are copied to the new #GPtrArray. The copy of @array will have the same #GDestroyNotify for its elements as @array. The copy will also be %NULL terminated if (and only if) the source array is. - + a deep copy of the initial #GPtrArray. + filename="glib/garray.c" + line="1506">a deep copy of the initial #GPtrArray. @@ -28577,8 +30228,8 @@ array is. #GPtrArray to duplicate + filename="glib/garray.c" + line="1487">#GPtrArray to duplicate @@ -28589,8 +30240,8 @@ array is. allow-none="1" closure="2"> a copy function used to copy every element in the array + filename="glib/garray.c" + line="1488">a copy function used to copy every element in the array nullable="1" allow-none="1"> user data passed to the copy function @func, or %NULL + filename="glib/garray.c" + line="1489">user data passed to the copy function @func, or %NULL @@ -28609,8 +30260,8 @@ array is. version="2.62" introspectable="0"> Adds all pointers of @array to the end of the array @array_to_extend. + filename="glib/garray.c" + line="2228">Adds all pointers of @array to the end of the array @array_to_extend. The array will grow in size automatically if needed. @array_to_extend is modified in-place. @@ -28624,23 +30275,23 @@ If @func is %NULL, then only the pointers (and not what they are pointing to) are copied to the new #GPtrArray. Whether @array_to_extend is %NULL terminated stays unchanged by this function. - + a #GPtrArray. + filename="glib/garray.c" + line="2230">a #GPtrArray. a #GPtrArray to add to the end of @array_to_extend. + filename="glib/garray.c" + line="2231">a #GPtrArray to add to the end of @array_to_extend. @@ -28651,8 +30302,8 @@ Whether @array_to_extend is %NULL terminated stays unchanged by this function. a copy function used to copy every element in the array + filename="glib/garray.c" + line="2232">a copy function used to copy every element in the array user data passed to the copy function @func, or %NULL + filename="glib/garray.c" + line="2233">user data passed to the copy function @func, or %NULL @@ -28671,31 +30322,31 @@ Whether @array_to_extend is %NULL terminated stays unchanged by this function. Adds all the pointers in @array to the end of @array_to_extend, transferring + filename="glib/garray.c" + line="2291">Adds all the pointers in @array to the end of @array_to_extend, transferring ownership of each element from @array to @array_to_extend and modifying @array_to_extend in-place. @array is then freed. As with g_ptr_array_free(), @array will be destroyed if its reference count is 1. If its reference count is higher, it will be decremented and the length of @array set to zero. - + a #GPtrArray. + filename="glib/garray.c" + line="2293">a #GPtrArray. a #GPtrArray to add to the end of + filename="glib/garray.c" + line="2294">a #GPtrArray to add to the end of @array_to_extend. @@ -28708,26 +30359,26 @@ length of @array set to zero. version="2.54" introspectable="0"> Checks whether @needle exists in @haystack. If the element is found, %TRUE is + filename="glib/garray.c" + line="2601">Checks whether @needle exists in @haystack. If the element is found, %TRUE is returned and the element’s index is returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of the first instance is returned. This does pointer comparisons only. If you want to use more complex equality checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). - + %TRUE if @needle is one of the elements of @haystack + filename="glib/garray.c" + line="2616">%TRUE if @needle is one of the elements of @haystack pointer array to be searched + filename="glib/garray.c" + line="2603">pointer array to be searched @@ -28737,8 +30388,8 @@ checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). pointer to look for + filename="glib/garray.c" + line="2604">pointer to look for return location for the index of + filename="glib/garray.c" + line="2605">return location for the index of the element, if found @@ -28760,8 +30411,8 @@ checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). Checks whether @needle exists in @haystack, using the given @equal_func. + filename="glib/garray.c" + line="2627">Checks whether @needle exists in @haystack, using the given @equal_func. If the element is found, %TRUE is returned and the element’s index is returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of @@ -28770,18 +30421,18 @@ the first instance is returned. @equal_func is called with the element from the array as its first parameter, and @needle as its second parameter. If @equal_func is %NULL, pointer equality is used. - + %TRUE if @needle is one of the elements of @haystack + filename="glib/garray.c" + line="2647">%TRUE if @needle is one of the elements of @haystack pointer array to be searched + filename="glib/garray.c" + line="2629">pointer array to be searched @@ -28791,8 +30442,8 @@ equality is used. nullable="1" allow-none="1"> pointer to look for + filename="glib/garray.c" + line="2630">pointer to look for nullable="1" allow-none="1"> the function to call for each element, which should + filename="glib/garray.c" + line="2631">the function to call for each element, which should return %TRUE when the desired element is found; or %NULL to use pointer equality @@ -28813,8 +30464,8 @@ equality is used. optional="1" allow-none="1"> return location for the index of + filename="glib/garray.c" + line="2634">return location for the index of the element, if found @@ -28825,26 +30476,26 @@ equality is used. version="2.4" introspectable="0"> Calls a function for each element of a #GPtrArray. @func must not + filename="glib/garray.c" + line="2577">Calls a function for each element of a #GPtrArray. @func must not add elements to or remove elements from the array. - + a #GPtrArray + filename="glib/garray.c" + line="2579">a #GPtrArray the function to call for each array element + filename="glib/garray.c" + line="2580">the function to call for each array element nullable="1" allow-none="1"> user data to pass to the function + filename="glib/garray.c" + line="2581">user data to pass to the function Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE + filename="glib/garray.c" + line="1776">Frees the memory allocated for the #GPtrArray. If @free_segment is %TRUE it frees the memory block holding the elements as well. Pass %FALSE if you want to free the #GPtrArray wrapper but preserve the underlying array for use elsewhere. If the reference count of @array @@ -28869,37 +30520,37 @@ is greater than one, the #GPtrArray wrapper is preserved but the size of @array will be set to zero. If array contents point to dynamically-allocated memory, they should -be freed separately if @free_seg is %TRUE and no #GDestroyNotify +be freed separately if @free_segment is %TRUE and no #GDestroyNotify function has been set for @array. -Note that if the array is %NULL terminated and @free_seg is %FALSE +Note that if the array is %NULL terminated and @free_segment is %FALSE then this will always return an allocated %NULL terminated buffer. If pdata is previously %NULL, a new buffer will be allocated. This function is not thread-safe. If using a #GPtrArray from multiple threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() functions. - + the pointer array if @free_seg is + filename="glib/garray.c" + line="1800">the pointer array if @free_segment is %FALSE, otherwise %NULL. The pointer array should be freed using g_free(). a #GPtrArray + filename="glib/garray.c" + line="1778">a #GPtrArray - + if %TRUE the actual pointer array is freed as well + filename="glib/garray.c" + line="1779">if %TRUE the actual pointer array is freed as well @@ -28909,26 +30560,26 @@ functions. version="2.40" introspectable="0"> Inserts an element into the pointer array at the given index. The + filename="glib/garray.c" + line="2324">Inserts an element into the pointer array at the given index. The array will grow in size automatically if necessary. - + a #GPtrArray + filename="glib/garray.c" + line="2326">a #GPtrArray the index to place the new element at, or -1 to append + filename="glib/garray.c" + line="2327">the index to place the new element at, or -1 to append nullable="1" allow-none="1"> the pointer to add. + filename="glib/garray.c" + line="2328">the pointer to add. @@ -28947,25 +30598,25 @@ array will grow in size automatically if necessary. version="2.74" introspectable="0"> Gets whether the @array was constructed as %NULL-terminated. + filename="glib/garray.c" + line="1706">Gets whether the @array was constructed as %NULL-terminated. This will only return %TRUE for arrays constructed by passing %TRUE to the `null_terminated` argument of g_ptr_array_new_null_terminated(). It will not return %TRUE for normal arrays which have had a %NULL element appended to them. - + %TRUE if the array is made to be %NULL terminated. + filename="glib/garray.c" + line="1717">%TRUE if the array is made to be %NULL terminated. the #GPtrArray + filename="glib/garray.c" + line="1708">the #GPtrArray @@ -28974,13 +30625,13 @@ them. Creates a new #GPtrArray with a reference count of 1. - + filename="glib/garray.c" + line="1165">Creates a new #GPtrArray with a reference count of 1. + the new #GPtrArray + filename="glib/garray.c" + line="1170">the new #GPtrArray @@ -28991,8 +30642,8 @@ them. version="2.76" introspectable="0"> Creates a new #GPtrArray, copying @len pointers from @data, and setting + filename="glib/garray.c" + line="1313">Creates a new #GPtrArray, copying @len pointers from @data, and setting the array’s reference count to 1. This avoids having to manually add each element one by one. @@ -29008,11 +30659,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if @len is greater than %G_MAXUINT. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1341">A new #GPtrArray @@ -29023,8 +30674,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array of pointers, + filename="glib/garray.c" + line="1315">an array of pointers, or %NULL for an empty array @@ -29032,8 +30683,8 @@ or %NULL for an empty array the number of pointers in @data + filename="glib/garray.c" + line="1317">the number of pointers in @data closure="3" destroy="4"> a copy function used to copy every element in the + filename="glib/garray.c" + line="1318">a copy function used to copy every element in the array or %NULL. @@ -29054,8 +30705,8 @@ or %NULL for an empty array nullable="1" allow-none="1"> user data passed to @copy_func, or %NULL + filename="glib/garray.c" + line="1320">user data passed to @copy_func, or %NULL allow-none="1" scope="async"> a function to free elements on @array + filename="glib/garray.c" + line="1321">a function to free elements on @array destruction or %NULL @@ -29076,8 +30727,8 @@ or %NULL for an empty array version="2.76" introspectable="0"> Creates a new #GPtrArray copying the pointers from @data after having + filename="glib/garray.c" + line="1359">Creates a new #GPtrArray copying the pointers from @data after having computed the length of it and with a reference count of 1. This avoids having to manually add each element one by one. If @copy_func is provided, then it is used to copy the data in the new @@ -29089,11 +30740,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if the @data has more than %G_MAXUINT elements. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1382">A new #GPtrArray @@ -29104,8 +30755,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array of + filename="glib/garray.c" + line="1361">an array of pointers, %NULL terminated; or %NULL for an empty array @@ -29119,8 +30770,8 @@ stores the length of its data in #guint, which may be shorter than closure="2" destroy="3"> a copy function used to copy every element in the + filename="glib/garray.c" + line="1363">a copy function used to copy every element in the array or %NULL. @@ -29129,8 +30780,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> user data passed to @copy_func, or %NULL + filename="glib/garray.c" + line="1365">user data passed to @copy_func, or %NULL a function to free elements on @array + filename="glib/garray.c" + line="1366">a function to free elements on @array destruction or %NULL @@ -29151,19 +30802,19 @@ stores the length of its data in #guint, which may be shorter than version="2.30" introspectable="0"> Creates a new #GPtrArray with @reserved_size pointers preallocated + filename="glib/garray.c" + line="1620">Creates a new #GPtrArray with @reserved_size pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. It also set @element_free_func for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment set to %TRUE or when removing elements. - + A new #GPtrArray + filename="glib/garray.c" + line="1634">A new #GPtrArray @@ -29171,8 +30822,8 @@ g_ptr_array_unref(), when g_ptr_array_free() is called with number of pointers preallocated + filename="glib/garray.c" + line="1622">number of pointers preallocated A function to free elements with + filename="glib/garray.c" + line="1623">A function to free elements with destroy @array or %NULL @@ -29193,8 +30844,8 @@ g_ptr_array_unref(), when g_ptr_array_free() is called with version="2.74" introspectable="0"> Like g_ptr_array_new_full() but also allows to set the array to + filename="glib/garray.c" + line="1645">Like g_ptr_array_new_full() but also allows to set the array to be %NULL terminated. A %NULL terminated pointer array has an additional %NULL pointer after the last element, beyond the current length. @@ -29209,11 +30860,11 @@ array is allocated. It does not guarantee that an array is always allocated. In other words, if the length is zero, then pdata may either point to a %NULL terminated array of length zero or be %NULL. - + A new #GPtrArray + filename="glib/garray.c" + line="1671">A new #GPtrArray @@ -29221,8 +30872,8 @@ zero or be %NULL. number of pointers preallocated. + filename="glib/garray.c" + line="1647">number of pointers preallocated. If @null_terminated is %TRUE, the actually allocated buffer size is @reserved_size plus 1, unless @reserved_size is zero, in which case no initial buffer gets allocated. @@ -29234,15 +30885,15 @@ zero or be %NULL. allow-none="1" scope="async"> A function to free elements with + filename="glib/garray.c" + line="1651">A function to free elements with destroy @array or %NULL whether to make the array as %NULL terminated. + filename="glib/garray.c" + line="1653">whether to make the array as %NULL terminated. @@ -29252,8 +30903,8 @@ zero or be %NULL. version="2.76" introspectable="0"> Creates a new #GPtrArray with @data as pointers, @len as length and a + filename="glib/garray.c" + line="1178">Creates a new #GPtrArray with @data as pointers, @len as length and a reference count of 1. This avoids having to copy such data manually. @@ -29268,11 +30919,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if @len is greater than %G_MAXUINT. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1202">A new #GPtrArray @@ -29283,8 +30934,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array of pointers, + filename="glib/garray.c" + line="1180">an array of pointers, or %NULL for an empty array @@ -29292,8 +30943,8 @@ stores the length of its data in #guint, which may be shorter than the number of pointers in @data + filename="glib/garray.c" + line="1182">the number of pointers in @data A function to free elements on @array + filename="glib/garray.c" + line="1183">A function to free elements on @array destruction or %NULL @@ -29314,8 +30965,8 @@ stores the length of its data in #guint, which may be shorter than version="2.76" introspectable="0"> Creates a new #GPtrArray with @data as pointers, computing the length of it + filename="glib/garray.c" + line="1227">Creates a new #GPtrArray with @data as pointers, computing the length of it and setting the reference count to 1. This avoids having to copy such data manually. @@ -29333,11 +30984,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if the @data length is greater than %G_MAXUINT. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1253">A new #GPtrArray @@ -29348,8 +30999,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array + filename="glib/garray.c" + line="1229">an array of pointers, %NULL terminated, or %NULL for an empty array @@ -29361,8 +31012,8 @@ stores the length of its data in #guint, which may be shorter than allow-none="1" scope="async"> a function to free elements on @array + filename="glib/garray.c" + line="1231">a function to free elements on @array destruction or %NULL @@ -29373,16 +31024,16 @@ stores the length of its data in #guint, which may be shorter than version="2.22" introspectable="0"> Creates a new #GPtrArray with a reference count of 1 and use + filename="glib/garray.c" + line="1600">Creates a new #GPtrArray with a reference count of 1 and use @element_free_func for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment set to %TRUE or when removing elements. - + A new #GPtrArray + filename="glib/garray.c" + line="1610">A new #GPtrArray @@ -29394,8 +31045,8 @@ either via g_ptr_array_unref(), when g_ptr_array_free() is called with allow-none="1" scope="async"> A function to free elements with + filename="glib/garray.c" + line="1602">A function to free elements with destroy @array or %NULL @@ -29406,14 +31057,14 @@ either via g_ptr_array_unref(), when g_ptr_array_free() is called with version="2.22" introspectable="0"> Atomically increments the reference count of @array by one. + filename="glib/garray.c" + line="1729">Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. - + The passed in #GPtrArray + filename="glib/garray.c" + line="1736">The passed in #GPtrArray @@ -29421,8 +31072,8 @@ This function is thread-safe and may be called from any thread. a #GPtrArray + filename="glib/garray.c" + line="1731">a #GPtrArray @@ -29433,27 +31084,27 @@ This function is thread-safe and may be called from any thread. c:identifier="g_ptr_array_remove" introspectable="0"> Removes the first occurrence of the given pointer from the pointer + filename="glib/garray.c" + line="2129">Removes the first occurrence of the given pointer from the pointer array. The following elements are moved down one place. If @array has a non-%NULL #GDestroyNotify function it is called for the removed element. It returns %TRUE if the pointer was removed, or %FALSE if the pointer was not found. - + %TRUE if the pointer is removed, %FALSE if the pointer + filename="glib/garray.c" + line="2142">%TRUE if the pointer is removed, %FALSE if the pointer is not found in the array a #GPtrArray + filename="glib/garray.c" + line="2131">a #GPtrArray @@ -29463,8 +31114,8 @@ pointer was not found. nullable="1" allow-none="1"> the pointer to remove + filename="glib/garray.c" + line="2132">the pointer to remove @@ -29473,8 +31124,8 @@ pointer was not found. c:identifier="g_ptr_array_remove_fast" introspectable="0"> Removes the first occurrence of the given pointer from the pointer + filename="glib/garray.c" + line="2166">Removes the first occurrence of the given pointer from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than g_ptr_array_remove(). If @array has a non-%NULL @@ -29482,18 +31133,18 @@ is faster than g_ptr_array_remove(). If @array has a non-%NULL It returns %TRUE if the pointer was removed, or %FALSE if the pointer was not found. - + %TRUE if the pointer was found in the array + filename="glib/garray.c" + line="2180">%TRUE if the pointer was found in the array a #GPtrArray + filename="glib/garray.c" + line="2168">a #GPtrArray @@ -29503,8 +31154,8 @@ pointer was not found. nullable="1" allow-none="1"> the pointer to remove + filename="glib/garray.c" + line="2169">the pointer to remove @@ -29513,32 +31164,32 @@ pointer was not found. c:identifier="g_ptr_array_remove_index" introspectable="0"> Removes the pointer at the given index from the pointer array. + filename="glib/garray.c" + line="1988">Removes the pointer at the given index from the pointer array. The following elements are moved down one place. If @array has a non-%NULL #GDestroyNotify function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the #GDestroyNotify implementation). - + the pointer which was removed + filename="glib/garray.c" + line="1999">the pointer which was removed a #GPtrArray + filename="glib/garray.c" + line="1990">a #GPtrArray the index of the pointer to remove + filename="glib/garray.c" + line="1991">the index of the pointer to remove @@ -29547,34 +31198,34 @@ to freed memory (depending on the #GDestroyNotify implementation). c:identifier="g_ptr_array_remove_index_fast" introspectable="0"> Removes the pointer at the given index from the pointer array. + filename="glib/garray.c" + line="2008">Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than g_ptr_array_remove_index(). If @array has a non-%NULL #GDestroyNotify function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the #GDestroyNotify implementation). - + the pointer which was removed + filename="glib/garray.c" + line="2021">the pointer which was removed a #GPtrArray + filename="glib/garray.c" + line="2010">a #GPtrArray the index of the pointer to remove + filename="glib/garray.c" + line="2011">the index of the pointer to remove @@ -29584,16 +31235,16 @@ return value from this function will potentially point to freed memory version="2.4" introspectable="0"> Removes the given number of pointers starting at the given index + filename="glib/garray.c" + line="2072">Removes the given number of pointers starting at the given index from a #GPtrArray. The following elements are moved to close the gap. If @array has a non-%NULL #GDestroyNotify function it is called for the removed elements. - + the @array + filename="glib/garray.c" + line="2083">the @array @@ -29601,22 +31252,22 @@ called for the removed elements. a @GPtrArray + filename="glib/garray.c" + line="2074">a @GPtrArray the index of the first pointer to remove + filename="glib/garray.c" + line="2075">the index of the first pointer to remove the number of pointers to remove + filename="glib/garray.c" + line="2076">the number of pointers to remove @@ -29626,19 +31277,19 @@ called for the removed elements. version="2.22" introspectable="0"> Sets a function for freeing each element when @array is destroyed + filename="glib/garray.c" + line="1683">Sets a function for freeing each element when @array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment set to %TRUE or when removing elements. - + A #GPtrArray + filename="glib/garray.c" + line="1685">A #GPtrArray @@ -29649,8 +31300,8 @@ with @free_segment set to %TRUE or when removing elements. allow-none="1" scope="async"> A function to free elements with + filename="glib/garray.c" + line="1686">A function to free elements with destroy @array or %NULL @@ -29660,28 +31311,28 @@ with @free_segment set to %TRUE or when removing elements. c:identifier="g_ptr_array_set_size" introspectable="0"> Sets the size of the array. When making the array larger, + filename="glib/garray.c" + line="1905">Sets the size of the array. When making the array larger, newly-added elements will be set to %NULL. When making it smaller, if @array has a non-%NULL #GDestroyNotify function then it will be called for the removed elements. - + a #GPtrArray + filename="glib/garray.c" + line="1907">a #GPtrArray the new length of the pointer array + filename="glib/garray.c" + line="1908">the new length of the pointer array @@ -29690,16 +31341,16 @@ called for the removed elements. c:identifier="g_ptr_array_sized_new" introspectable="0"> Creates a new #GPtrArray with @reserved_size pointers preallocated + filename="glib/garray.c" + line="1552">Creates a new #GPtrArray with @reserved_size pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. - + the new #GPtrArray + filename="glib/garray.c" + line="1561">the new #GPtrArray @@ -29707,16 +31358,16 @@ the size of the array is still 0. number of pointers preallocated + filename="glib/garray.c" + line="1554">number of pointers preallocated Sorts the array, using @compare_func which should be a qsort()-style + filename="glib/garray.c" + line="2364">Sorts the array, using @compare_func which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). @@ -29754,23 +31405,23 @@ g_ptr_array_sort (file_list, sort_filelist); ]| This is guaranteed to be a stable sort since version 2.32. - + a #GPtrArray + filename="glib/garray.c" + line="2366">a #GPtrArray comparison function + filename="glib/garray.c" + line="2367">comparison function @@ -29780,30 +31431,30 @@ This is guaranteed to be a stable sort since version 2.32. version="2.76" introspectable="0"> Sorts the array, using @compare_func which should be a qsort()-style + filename="glib/garray.c" + line="2513">Sorts the array, using @compare_func which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). This is guaranteed to be a stable sort. - + a #GPtrArray + filename="glib/garray.c" + line="2515">a #GPtrArray a #GCompareFunc comparison function + filename="glib/garray.c" + line="2516">a #GCompareFunc comparison function @@ -29813,28 +31464,28 @@ This is guaranteed to be a stable sort. version="2.76" introspectable="0"> Like g_ptr_array_sort_values(), but the comparison function has an extra + filename="glib/garray.c" + line="2552">Like g_ptr_array_sort_values(), but the comparison function has an extra user data argument. This is guaranteed to be a stable sort. - + a #GPtrArray + filename="glib/garray.c" + line="2554">a #GPtrArray a #GCompareDataFunc comparison function + filename="glib/garray.c" + line="2555">a #GCompareDataFunc comparison function nullable="1" allow-none="1"> data to pass to @compare_func + filename="glib/garray.c" + line="2556">data to pass to @compare_func @@ -29852,8 +31503,8 @@ This is guaranteed to be a stable sort. c:identifier="g_ptr_array_sort_with_data" introspectable="0"> Like g_ptr_array_sort(), but the comparison function has an extra + filename="glib/garray.c" + line="2425">Like g_ptr_array_sort(), but the comparison function has an extra user data argument. Note that the comparison function for g_ptr_array_sort_with_data() @@ -29909,23 +31560,23 @@ g_ptr_array_sort_with_data (file_list, ]| This is guaranteed to be a stable sort since version 2.32. - + a #GPtrArray + filename="glib/garray.c" + line="2427">a #GPtrArray comparison function + filename="glib/garray.c" + line="2428">comparison function nullable="1" allow-none="1"> data to pass to @compare_func + filename="glib/garray.c" + line="2429">data to pass to @compare_func @@ -29944,8 +31595,8 @@ This is guaranteed to be a stable sort since version 2.32. version="2.64" introspectable="0"> Frees the data in the array and resets the size to zero, while + filename="glib/garray.c" + line="1407">Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. @@ -29989,11 +31640,11 @@ g_free (chunks); // next set of chunks. g_assert (chunk_buffer->len == 0); ]| - + the element data, which should be + filename="glib/garray.c" + line="1458">the element data, which should be freed using g_free(). This may be %NULL if the array doesn’t have any elements (i.e. if `*len` is zero). @@ -30001,8 +31652,8 @@ g_assert (chunk_buffer->len == 0); a #GPtrArray. + filename="glib/garray.c" + line="1409">a #GPtrArray. @@ -30014,8 +31665,8 @@ g_assert (chunk_buffer->len == 0); optional="1" allow-none="1"> pointer to retrieve the number of + filename="glib/garray.c" + line="1410">pointer to retrieve the number of elements of the original array @@ -30026,31 +31677,31 @@ g_assert (chunk_buffer->len == 0); version="2.58" introspectable="0"> Removes the pointer at the given index from the pointer array. + filename="glib/garray.c" + line="2030">Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The #GDestroyNotify for @array is *not* called on the removed element; ownership is transferred to the caller of this function. - + the pointer which was removed + filename="glib/garray.c" + line="2040">the pointer which was removed a #GPtrArray + filename="glib/garray.c" + line="2032">a #GPtrArray the index of the pointer to steal + filename="glib/garray.c" + line="2033">the index of the pointer to steal @@ -30060,33 +31711,33 @@ the caller of this function. version="2.58" introspectable="0"> Removes the pointer at the given index from the pointer array. + filename="glib/garray.c" + line="2050">Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is *not* called on the removed element; ownership is transferred to the caller of this function. - + the pointer which was removed + filename="glib/garray.c" + line="2062">the pointer which was removed a #GPtrArray + filename="glib/garray.c" + line="2052">a #GPtrArray the index of the pointer to steal + filename="glib/garray.c" + line="2053">the index of the pointer to steal @@ -30096,20 +31747,20 @@ of this function. version="2.22" introspectable="0"> Atomically decrements the reference count of @array by one. If the + filename="glib/garray.c" + line="1754">Atomically decrements the reference count of @array by one. If the reference count drops to 0, the effect is the same as calling g_ptr_array_free() with @free_segment set to %TRUE. This function is thread-safe and may be called from any thread. - + A #GPtrArray + filename="glib/garray.c" + line="1756">A #GPtrArray @@ -30119,13 +31770,13 @@ is thread-safe and may be called from any thread. Contains the public fields of a -[Queue][glib-Double-ended-Queues]. - +[Queue](data-structures.html#double-ended-queues). + a pointer to the first element of the queue @@ -30133,7 +31784,7 @@ is thread-safe and may be called from any thread. a pointer to the last element of the queue @@ -30141,24 +31792,24 @@ is thread-safe and may be called from any thread. the number of elements in the queue Removes all the elements in @queue. If queue elements contain + filename="glib/gqueue.c" + line="108">Removes all the elements in @queue. If queue elements contain dynamically-allocated memory, they should be freed first. - + a #GQueue + filename="glib/gqueue.c" + line="110">a #GQueue @@ -30167,18 +31818,18 @@ dynamically-allocated memory, they should be freed first. c:identifier="g_queue_clear_full" version="2.60"> Convenience method, which frees all the memory used by a #GQueue, + filename="glib/gqueue.c" + line="126">Convenience method, which frees all the memory used by a #GQueue, and calls the provided @free_func on each item in the #GQueue. - + a pointer to a #GQueue + filename="glib/gqueue.c" + line="128">a pointer to a #GQueue allow-none="1" scope="async"> the function to be called to free memory allocated + filename="glib/gqueue.c" + line="129">the function to be called to free memory allocated @@ -30198,22 +31849,22 @@ and calls the provided @free_func on each item in the #GQueue. version="2.4" introspectable="0"> Copies a @queue. Note that is a shallow copy. If the elements in the + filename="glib/gqueue.c" + line="199">Copies a @queue. Note that is a shallow copy. If the elements in the queue consist of pointers to data, the pointers are copied, but the actual data is not. - + a copy of @queue + filename="glib/gqueue.c" + line="207">a copy of @queue a #GQueue + filename="glib/gqueue.c" + line="201">a #GQueue @@ -30223,25 +31874,25 @@ actual data is not. version="2.4" introspectable="0"> Removes @link_ from @queue and frees it. + filename="glib/gqueue.c" + line="822">Removes @link_ from @queue and frees it. @link_ must be part of @queue. - + a #GQueue + filename="glib/gqueue.c" + line="824">a #GQueue a #GList link that must be part of @queue + filename="glib/gqueue.c" + line="825">a #GList link that must be part of @queue @@ -30253,13 +31904,13 @@ actual data is not. version="2.4" introspectable="0"> Finds the first link in @queue which contains @data. - + filename="glib/gqueue.c" + line="260">Finds the first link in @queue which contains @data. + the first link in @queue which contains @data + filename="glib/gqueue.c" + line="267">the first link in @queue which contains @data @@ -30267,8 +31918,8 @@ actual data is not. a #GQueue + filename="glib/gqueue.c" + line="262">a #GQueue nullable="1" allow-none="1"> data to find + filename="glib/gqueue.c" + line="263">data to find @@ -30287,17 +31938,17 @@ actual data is not. version="2.4" introspectable="0"> Finds an element in a #GQueue, using a supplied function to find the + filename="glib/gqueue.c" + line="280">Finds an element in a #GQueue, using a supplied function to find the desired element. It iterates over the queue, calling the given function which should return 0 when the desired element is found. The function takes two gconstpointer arguments, the #GQueue element's data as the first argument and the given user data as the second argument. - + the found link, or %NULL if it wasn't found + filename="glib/gqueue.c" + line="293">the found link, or %NULL if it wasn't found @@ -30305,8 +31956,8 @@ first argument and the given user data as the second argument. a #GQueue + filename="glib/gqueue.c" + line="282">a #GQueue nullable="1" allow-none="1"> user data passed to @func + filename="glib/gqueue.c" + line="283">user data passed to @func - + a #GCompareFunc to call for each element. It should return 0 + filename="glib/gqueue.c" + line="284">a #GCompareFunc to call for each element. It should return 0 when the desired element is found - + Calls @func for each element in the queue passing @user_data to the + filename="glib/gqueue.c" + line="227">Calls @func for each element in the queue passing @user_data to the function. It is safe for @func to remove the element from @queue, but it must not modify any part of the queue after that element. - + a #GQueue + filename="glib/gqueue.c" + line="229">a #GQueue - + the function to call for each element's data + filename="glib/gqueue.c" + line="230">the function to call for each element's data nullable="1" allow-none="1"> user data to pass to @func + filename="glib/gqueue.c" + line="231">user data to pass to @func Frees the memory allocated for the #GQueue. Only call this function + filename="glib/gqueue.c" + line="47">Frees the memory allocated for the #GQueue. Only call this function if @queue was created with g_queue_new(). If queue elements contain dynamically-allocated memory, they should be freed first. If queue elements contain dynamically-allocated memory, you should either use g_queue_free_full() or free them manually first. - + a #GQueue + filename="glib/gqueue.c" + line="49">a #GQueue Convenience method, which frees all the memory used by a #GQueue, + filename="glib/gqueue.c" + line="67">Convenience method, which frees all the memory used by a #GQueue, and calls the specified destroy function on every element's data. @free_func should not modify the queue (eg, by removing the freed element from it). - + a pointer to a #GQueue + filename="glib/gqueue.c" + line="69">a pointer to a #GQueue the function to be called to free each element's data + filename="glib/gqueue.c" + line="70">the function to be called to free each element's data @@ -30419,41 +32070,41 @@ element from it). c:identifier="g_queue_get_length" version="2.4"> Returns the number of items in @queue. - + filename="glib/gqueue.c" + line="164">Returns the number of items in @queue. + the number of items in @queue + filename="glib/gqueue.c" + line="170">the number of items in @queue a #GQueue + filename="glib/gqueue.c" + line="166">a #GQueue Returns the position of the first element in @queue which contains @data. - + filename="glib/gqueue.c" + line="906">Returns the position of the first element in @queue which contains @data. + the position of the first element in @queue which + filename="glib/gqueue.c" + line="913">the position of the first element in @queue which contains @data, or -1 if no element in @queue contains @data a #GQueue + filename="glib/gqueue.c" + line="908">a #GQueue nullable="1" allow-none="1"> the data to find + filename="glib/gqueue.c" + line="909">the data to find A statically-allocated #GQueue must be initialized with this function + filename="glib/gqueue.c" + line="88">A statically-allocated #GQueue must be initialized with this function before it can be used. Alternatively you can initialize it with %G_QUEUE_INIT. It is not necessary to initialize queues created with g_queue_new(). - + an uninitialized #GQueue + filename="glib/gqueue.c" + line="90">an uninitialized #GQueue @@ -30492,20 +32143,20 @@ g_queue_new(). version="2.4" introspectable="0"> Inserts @data into @queue after @sibling. + filename="glib/gqueue.c" + line="1064">Inserts @data into @queue after @sibling. @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the data at the head of the queue. - + a #GQueue + filename="glib/gqueue.c" + line="1066">a #GQueue nullable="1" allow-none="1"> a #GList link that must be part of @queue, or %NULL to + filename="glib/gqueue.c" + line="1067">a #GList link that must be part of @queue, or %NULL to push at the head of the queue. @@ -30525,8 +32176,8 @@ data at the head of the queue. nullable="1" allow-none="1"> the data to insert + filename="glib/gqueue.c" + line="1069">the data to insert @@ -30536,19 +32187,19 @@ data at the head of the queue. version="2.62" introspectable="0"> Inserts @link_ into @queue after @sibling. + filename="glib/gqueue.c" + line="1091">Inserts @link_ into @queue after @sibling. @sibling must be part of @queue. - + a #GQueue + filename="glib/gqueue.c" + line="1093">a #GQueue nullable="1" allow-none="1"> a #GList link that must be part of @queue, or %NULL to + filename="glib/gqueue.c" + line="1094">a #GList link that must be part of @queue, or %NULL to push at the head of the queue. @@ -30565,8 +32216,8 @@ data at the head of the queue. a #GList link to insert which must not be part of any other list. + filename="glib/gqueue.c" + line="1096">a #GList link to insert which must not be part of any other list. @@ -30578,20 +32229,20 @@ data at the head of the queue. version="2.4" introspectable="0"> Inserts @data into @queue before @sibling. + filename="glib/gqueue.c" + line="990">Inserts @data into @queue before @sibling. @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the data at the tail of the queue. - + a #GQueue + filename="glib/gqueue.c" + line="992">a #GQueue nullable="1" allow-none="1"> a #GList link that must be part of @queue, or %NULL to + filename="glib/gqueue.c" + line="993">a #GList link that must be part of @queue, or %NULL to push at the tail of the queue. @@ -30611,8 +32262,8 @@ data at the tail of the queue. nullable="1" allow-none="1"> the data to insert + filename="glib/gqueue.c" + line="995">the data to insert @@ -30622,19 +32273,19 @@ data at the tail of the queue. version="2.62" introspectable="0"> Inserts @link_ into @queue before @sibling. + filename="glib/gqueue.c" + line="1026">Inserts @link_ into @queue before @sibling. @sibling must be part of @queue. - + a #GQueue + filename="glib/gqueue.c" + line="1028">a #GQueue nullable="1" allow-none="1"> a #GList link that must be part of @queue, or %NULL to + filename="glib/gqueue.c" + line="1029">a #GList link that must be part of @queue, or %NULL to push at the tail of the queue. @@ -30651,8 +32302,8 @@ data at the tail of the queue. a #GList link to insert which must not be part of any other list. + filename="glib/gqueue.c" + line="1031">a #GList link to insert which must not be part of any other list. @@ -30661,20 +32312,19 @@ data at the tail of the queue. + version="2.4"> Inserts @data into @queue using @func to determine the new position. - + filename="glib/gqueue.c" + line="1120">Inserts @data into @queue using @func to determine the new position. + a #GQueue + filename="glib/gqueue.c" + line="1122">a #GQueue nullable="1" allow-none="1"> the data to insert + filename="glib/gqueue.c" + line="1123">the data to insert - + the #GCompareDataFunc used to compare elements in the queue. It is + filename="glib/gqueue.c" + line="1124">the #GCompareDataFunc used to compare elements in the queue. It is called with two elements of the @queue and @user_data. It should return 0 if the elements are equal, a negative value if the first element comes before the second, and a positive value if the second @@ -30701,28 +32354,28 @@ data at the tail of the queue. nullable="1" allow-none="1"> user data passed to @func + filename="glib/gqueue.c" + line="1129">user data passed to @func Returns %TRUE if the queue is empty. - + filename="glib/gqueue.c" + line="148">Returns %TRUE if the queue is empty. + %TRUE if the queue is empty + filename="glib/gqueue.c" + line="154">%TRUE if the queue is empty a #GQueue. + filename="glib/gqueue.c" + line="150">a #GQueue. @@ -30732,27 +32385,27 @@ data at the tail of the queue. version="2.4" introspectable="0"> Returns the position of @link_ in @queue. - + filename="glib/gqueue.c" + line="775">Returns the position of @link_ in @queue. + the position of @link_, or -1 if the link is + filename="glib/gqueue.c" + line="782">the position of @link_, or -1 if the link is not part of @queue a #GQueue + filename="glib/gqueue.c" + line="777">a #GQueue a #GList link + filename="glib/gqueue.c" + line="778">a #GList link @@ -30761,21 +32414,21 @@ data at the tail of the queue. Returns the first element of the queue. - + filename="glib/gqueue.c" + line="844">Returns the first element of the queue. + the data of the first element in the queue, or %NULL + filename="glib/gqueue.c" + line="850">the data of the first element in the queue, or %NULL if the queue is empty a #GQueue + filename="glib/gqueue.c" + line="846">a #GQueue @@ -30785,13 +32438,13 @@ data at the tail of the queue. version="2.4" introspectable="0"> Returns the first link in @queue. - + filename="glib/gqueue.c" + line="571">Returns the first link in @queue. + the first link in @queue, or %NULL if @queue is empty + filename="glib/gqueue.c" + line="577">the first link in @queue, or %NULL if @queue is empty @@ -30799,35 +32452,35 @@ data at the tail of the queue. a #GQueue + filename="glib/gqueue.c" + line="573">a #GQueue Returns the @n'th element of @queue. - + filename="glib/gqueue.c" + line="878">Returns the @n'th element of @queue. + the data for the @n'th element of @queue, + filename="glib/gqueue.c" + line="885">the data for the @n'th element of @queue, or %NULL if @n is off the end of @queue a #GQueue + filename="glib/gqueue.c" + line="880">a #GQueue the position of the element + filename="glib/gqueue.c" + line="881">the position of the element @@ -30837,13 +32490,13 @@ data at the tail of the queue. version="2.4" introspectable="0"> Returns the link at the given position - + filename="glib/gqueue.c" + line="733">Returns the link at the given position + the link at the @n'th position, or %NULL + filename="glib/gqueue.c" + line="740">the link at the @n'th position, or %NULL if @n is off the end of the list @@ -30852,35 +32505,35 @@ data at the tail of the queue. a #GQueue + filename="glib/gqueue.c" + line="735">a #GQueue the position of the link + filename="glib/gqueue.c" + line="736">the position of the link Returns the last element of the queue. - + filename="glib/gqueue.c" + line="861">Returns the last element of the queue. + the data of the last element in the queue, or %NULL + filename="glib/gqueue.c" + line="867">the data of the last element in the queue, or %NULL if the queue is empty a #GQueue + filename="glib/gqueue.c" + line="863">a #GQueue @@ -30890,13 +32543,13 @@ data at the tail of the queue. version="2.4" introspectable="0"> Returns the last link in @queue. - + filename="glib/gqueue.c" + line="589">Returns the last link in @queue. + the last link in @queue, or %NULL if @queue is empty + filename="glib/gqueue.c" + line="595">the last link in @queue, or %NULL if @queue is empty @@ -30904,29 +32557,29 @@ data at the tail of the queue. a #GQueue + filename="glib/gqueue.c" + line="591">a #GQueue Removes the first element of the queue and returns its data. - + filename="glib/gqueue.c" + line="504">Removes the first element of the queue and returns its data. + the data of the first element in the queue, or %NULL + filename="glib/gqueue.c" + line="510">the data of the first element in the queue, or %NULL if the queue is empty a #GQueue + filename="glib/gqueue.c" + line="506">a #GQueue @@ -30935,13 +32588,13 @@ data at the tail of the queue. c:identifier="g_queue_pop_head_link" introspectable="0"> Removes and returns the first element of the queue. - + filename="glib/gqueue.c" + line="537">Removes and returns the first element of the queue. + the #GList element at the head of the queue, or %NULL + filename="glib/gqueue.c" + line="543">the #GList element at the head of the queue, or %NULL if the queue is empty @@ -30950,34 +32603,34 @@ data at the tail of the queue. a #GQueue + filename="glib/gqueue.c" + line="539">a #GQueue Removes the @n'th element of @queue and returns its data. - + filename="glib/gqueue.c" + line="640">Removes the @n'th element of @queue and returns its data. + the element's data, or %NULL if @n is off the end of @queue + filename="glib/gqueue.c" + line="647">the element's data, or %NULL if @n is off the end of @queue a #GQueue + filename="glib/gqueue.c" + line="642">a #GQueue the position of the element + filename="glib/gqueue.c" + line="643">the position of the element @@ -30987,13 +32640,13 @@ data at the tail of the queue. version="2.4" introspectable="0"> Removes and returns the link at the given position. - + filename="glib/gqueue.c" + line="705">Removes and returns the link at the given position. + the @n'th link, or %NULL if @n is off the end of @queue + filename="glib/gqueue.c" + line="712">the @n'th link, or %NULL if @n is off the end of @queue @@ -31001,35 +32654,35 @@ data at the tail of the queue. a #GQueue + filename="glib/gqueue.c" + line="707">a #GQueue the link's position + filename="glib/gqueue.c" + line="708">the link's position Removes the last element of the queue and returns its data. - + filename="glib/gqueue.c" + line="607">Removes the last element of the queue and returns its data. + the data of the last element in the queue, or %NULL + filename="glib/gqueue.c" + line="613">the data of the last element in the queue, or %NULL if the queue is empty a #GQueue + filename="glib/gqueue.c" + line="609">a #GQueue @@ -31038,13 +32691,13 @@ data at the tail of the queue. c:identifier="g_queue_pop_tail_link" introspectable="0"> Removes and returns the last element of the queue. - + filename="glib/gqueue.c" + line="671">Removes and returns the last element of the queue. + the #GList element at the tail of the queue, or %NULL + filename="glib/gqueue.c" + line="677">the #GList element at the tail of the queue, or %NULL if the queue is empty @@ -31053,25 +32706,25 @@ data at the tail of the queue. a #GQueue + filename="glib/gqueue.c" + line="673">a #GQueue Adds a new element at the head of the queue. - + filename="glib/gqueue.c" + line="333">Adds a new element at the head of the queue. + a #GQueue. + filename="glib/gqueue.c" + line="335">a #GQueue. nullable="1" allow-none="1"> the data for the new element. + filename="glib/gqueue.c" + line="336">the data for the new element. @@ -31089,23 +32742,23 @@ data at the tail of the queue. c:identifier="g_queue_push_head_link" introspectable="0"> Adds a new element at the head of the queue. - + filename="glib/gqueue.c" + line="380">Adds a new element at the head of the queue. + a #GQueue + filename="glib/gqueue.c" + line="382">a #GQueue a single #GList element, not a list with more than one element + filename="glib/gqueue.c" + line="383">a single #GList element, not a list with more than one element @@ -31114,17 +32767,17 @@ data at the tail of the queue. Inserts a new element into @queue at the given position. - + filename="glib/gqueue.c" + line="352">Inserts a new element into @queue at the given position. + a #GQueue + filename="glib/gqueue.c" + line="354">a #GQueue nullable="1" allow-none="1"> the data for the new element + filename="glib/gqueue.c" + line="355">the data for the new element the position to insert the new element. If @n is negative or + filename="glib/gqueue.c" + line="356">the position to insert the new element. If @n is negative or larger than the number of elements in the @queue, the element is added to the end of the queue. @@ -31151,31 +32804,31 @@ data at the tail of the queue. version="2.4" introspectable="0"> Inserts @link into @queue at the given position. - + filename="glib/gqueue.c" + line="451">Inserts @link into @queue at the given position. + a #GQueue + filename="glib/gqueue.c" + line="453">a #GQueue the position to insert the link. If this is negative or larger than + filename="glib/gqueue.c" + line="454">the position to insert the link. If this is negative or larger than the number of elements in @queue, the link is added to the end of @queue. the link to add to @queue + filename="glib/gqueue.c" + line="457">the link to add to @queue @@ -31184,17 +32837,17 @@ data at the tail of the queue. Adds a new element at the tail of the queue. - + filename="glib/gqueue.c" + line="405">Adds a new element at the tail of the queue. + a #GQueue + filename="glib/gqueue.c" + line="407">a #GQueue nullable="1" allow-none="1"> the data for the new element + filename="glib/gqueue.c" + line="408">the data for the new element @@ -31212,23 +32865,23 @@ data at the tail of the queue. c:identifier="g_queue_push_tail_link" introspectable="0"> Adds a new element at the tail of the queue. - + filename="glib/gqueue.c" + line="426">Adds a new element at the tail of the queue. + a #GQueue + filename="glib/gqueue.c" + line="428">a #GQueue a single #GList element, not a list with more than one element + filename="glib/gqueue.c" + line="429">a single #GList element, not a list with more than one element @@ -31237,20 +32890,20 @@ data at the tail of the queue. Removes the first element in @queue that contains @data. - + filename="glib/gqueue.c" + line="927">Removes the first element in @queue that contains @data. + %TRUE if @data was found and removed from @queue + filename="glib/gqueue.c" + line="934">%TRUE if @data was found and removed from @queue a #GQueue + filename="glib/gqueue.c" + line="929">a #GQueue nullable="1" allow-none="1"> the data to remove + filename="glib/gqueue.c" + line="930">the data to remove @@ -31268,20 +32921,20 @@ data at the tail of the queue. c:identifier="g_queue_remove_all" version="2.4"> Remove all elements whose data equals @data from @queue. - + filename="glib/gqueue.c" + line="954">Remove all elements whose data equals @data from @queue. + the number of elements removed from @queue + filename="glib/gqueue.c" + line="961">the number of elements removed from @queue a #GQueue + filename="glib/gqueue.c" + line="956">a #GQueue nullable="1" allow-none="1"> the data to remove + filename="glib/gqueue.c" + line="957">the data to remove Reverses the order of the items in @queue. - + filename="glib/gqueue.c" + line="182">Reverses the order of the items in @queue. + a #GQueue + filename="glib/gqueue.c" + line="184">a #GQueue - + Sorts @queue using @compare_func. - + filename="glib/gqueue.c" + line="308">Sorts @queue using @compare_func. + a #GQueue + filename="glib/gqueue.c" + line="310">a #GQueue - + the #GCompareDataFunc used to sort @queue. This function + filename="glib/gqueue.c" + line="311">the #GCompareDataFunc used to sort @queue. This function is passed two elements of the queue and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first. @@ -31344,8 +32997,8 @@ data at the tail of the queue. nullable="1" allow-none="1"> user data passed to @compare_func + filename="glib/gqueue.c" + line="315">user data passed to @compare_func @@ -31355,26 +33008,26 @@ data at the tail of the queue. version="2.4" introspectable="0"> Unlinks @link_ so that it will no longer be part of @queue. + filename="glib/gqueue.c" + line="796">Unlinks @link_ so that it will no longer be part of @queue. The link is not freed. @link_ must be part of @queue. - + a #GQueue + filename="glib/gqueue.c" + line="798">a #GQueue a #GList link that must be part of @queue + filename="glib/gqueue.c" + line="799">a #GList link that must be part of @queue @@ -31383,23 +33036,72 @@ The link is not freed. Creates a new #GQueue. - + filename="glib/gqueue.c" + line="34">Creates a new #GQueue. + a newly allocated #GQueue + filename="glib/gqueue.c" + line="39">a newly allocated #GQueue + + Declare a [type@GLib.RecMutexLocker] variable with `g_autoptr()` and lock the +mutex. The mutex will be unlocked automatically when leaving the scope. The +variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is +not used in the scope. + +This feature is only supported on GCC and clang. This macro is not defined on +other compilers and should not be used in programs that are intended to be +portable to those compilers. + +Note that this should be used in a place where it is allowed to declare a +variable, which could be before any statement in the case +`-Wdeclaration-after-statement` is used, or C standard prior to C99. + +```c +{ + G_REC_MUTEX_AUTO_LOCK (&obj->rec_mutex, locker); + + obj->stuff_with_lock (); + if (condition) + { + // No need to unlock + return; + } + + // Unlock before end of scope + g_clear_pointer (&locker, g_rec_mutex_locker_free); + obj->stuff_without_lock (); +} +``` + + + + a [type@GLib.RecMutex] + + + a variable name to be declared + + + Evaluates to the initial reference count for `grefcount`. This macro is useful for initializing `grefcount` fields inside @@ -31418,13 +33120,13 @@ static const Person default_person = { .address = "Default address", }; ]| - + The GRWLock struct is an opaque data structure to represent a + filename="glib/gthread.c" + line="290">The GRWLock struct is an opaque data structure to represent a reader-writer lock. It is similar to a #GMutex in that it allows multiple threads to coordinate access to a shared resource. @@ -31487,7 +33189,7 @@ without initialisation. Otherwise, you should call g_rw_lock_init() on it and g_rw_lock_clear() when done. A GRWLock should only be accessed with the g_rw_lock_ functions. - + @@ -31498,31 +33200,31 @@ A GRWLock should only be accessed with the g_rw_lock_ functions. Frees the resources allocated to a lock with g_rw_lock_init(). + filename="glib/gthread.c" + line="1475">Frees the resources allocated to a lock with g_rw_lock_init(). This function should not be used with a #GRWLock that has been statically allocated. Calling g_rw_lock_clear() when any thread holds the lock leads to undefined behaviour. - + an initialized #GRWLock + filename="glib/gthread.c" + line="1477">an initialized #GRWLock Initializes a #GRWLock so that it can be used. + filename="glib/gthread.c" + line="1438">Initializes a #GRWLock so that it can be used. This function is useful to initialize a lock that has been allocated on the stack, or as part of a larger structure. It is not @@ -31546,15 +33248,15 @@ needed, use g_rw_lock_clear(). Calling g_rw_lock_init() on an already initialized #GRWLock leads to undefined behaviour. - + an uninitialized #GRWLock + filename="glib/gthread.c" + line="1440">an uninitialized #GRWLock @@ -31563,8 +33265,8 @@ to undefined behaviour. c:identifier="g_rw_lock_reader_lock" version="2.32"> Obtain a read lock on @rw_lock. If another thread currently holds + filename="glib/gthread.c" + line="1550">Obtain a read lock on @rw_lock. If another thread currently holds the write lock on @rw_lock, the current thread will block until the write lock was (held and) released. If another thread does not hold the write lock, but is waiting for it, it is implementation defined @@ -31579,15 +33281,15 @@ call g_rw_lock_reader_unlock() the same amount of times. It is implementation-defined how many read locks are allowed to be held on the same lock simultaneously. If the limit is hit, or if a deadlock is detected, a critical warning will be emitted. - + a #GRWLock + filename="glib/gthread.c" + line="1552">a #GRWLock @@ -31596,22 +33298,22 @@ or if a deadlock is detected, a critical warning will be emitted. c:identifier="g_rw_lock_reader_trylock" version="2.32"> Tries to obtain a read lock on @rw_lock and returns %TRUE if + filename="glib/gthread.c" + line="1578">Tries to obtain a read lock on @rw_lock and returns %TRUE if the read lock was successfully obtained. Otherwise it returns %FALSE. - + %TRUE if @rw_lock could be locked + filename="glib/gthread.c" + line="1586">%TRUE if @rw_lock could be locked a #GRWLock + filename="glib/gthread.c" + line="1580">a #GRWLock @@ -31620,20 +33322,20 @@ returns %FALSE. c:identifier="g_rw_lock_reader_unlock" version="2.32"> Release a read lock on @rw_lock. + filename="glib/gthread.c" + line="1596">Release a read lock on @rw_lock. Calling g_rw_lock_reader_unlock() on a lock that is not held by the current thread leads to undefined behaviour. - + a #GRWLock + filename="glib/gthread.c" + line="1598">a #GRWLock @@ -31642,22 +33344,22 @@ by the current thread leads to undefined behaviour. c:identifier="g_rw_lock_writer_lock" version="2.32"> Obtain a write lock on @rw_lock. If another thread currently holds + filename="glib/gthread.c" + line="1495">Obtain a write lock on @rw_lock. If another thread currently holds a read or write lock on @rw_lock, the current thread will block until all other threads have dropped their locks on @rw_lock. Calling g_rw_lock_writer_lock() while the current thread already owns a read or write lock on @rw_lock leads to undefined behaviour. - + a #GRWLock + filename="glib/gthread.c" + line="1497">a #GRWLock @@ -31666,23 +33368,23 @@ owns a read or write lock on @rw_lock leads to undefined behaviour. c:identifier="g_rw_lock_writer_trylock" version="2.32"> Tries to obtain a write lock on @rw_lock. If another thread + filename="glib/gthread.c" + line="1514">Tries to obtain a write lock on @rw_lock. If another thread currently holds a read or write lock on @rw_lock, it immediately returns %FALSE. Otherwise it locks @rw_lock and returns %TRUE. - + %TRUE if @rw_lock could be locked + filename="glib/gthread.c" + line="1523">%TRUE if @rw_lock could be locked a #GRWLock + filename="glib/gthread.c" + line="1516">a #GRWLock @@ -31691,200 +33393,365 @@ Otherwise it locks @rw_lock and returns %TRUE. c:identifier="g_rw_lock_writer_unlock" version="2.32"> Release a write lock on @rw_lock. + filename="glib/gthread.c" + line="1533">Release a write lock on @rw_lock. Calling g_rw_lock_writer_unlock() on a lock that is not held by the current thread leads to undefined behaviour. - + a #GRWLock + filename="glib/gthread.c" + line="1535">a #GRWLock - + The GRand struct is an opaque data structure. It should only be + filename="glib/gthread.h" + line="773">Declare a [type@GLib.RWLockReaderLocker] variable with `g_autoptr()` and lock +for reading. The mutex will be unlocked automatically when leaving the scope. +The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it +is not used in the scope. + +This feature is only supported on GCC and clang. This macro is not defined on +other compilers and should not be used in programs that are intended to be +portable to those compilers. + +Note that this should be used in a place where it is allowed to declare a +variable, which could be before any statement in the case +`-Wdeclaration-after-statement` is used, or C standard prior to C99. + +```c +{ + G_RW_LOCK_READER_AUTO_LOCK (&obj->rw_lock, locker); + + obj->stuff_with_lock (); + if (condition) + { + // No need to unlock + return; + } + + // Unlock before end of scope + g_clear_pointer (&locker, g_rw_lock_reader_locker_free); + obj->stuff_without_lock (); +} +``` + + + + a [type@GLib.RWLock] + + + a variable name to be declared + + + + + Declare a [type@GLib.RWLockWriterLocker] variable with `g_autoptr()` and lock +for writing. The mutex will be unlocked automatically when leaving the scope. +The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it +is not used in the scope. + +This feature is only supported on GCC and clang. This macro is not defined on +other compilers and should not be used in programs that are intended to be +portable to those compilers. + +Note that this should be used in a place where it is allowed to declare a +variable, which could be before any statement in the case +`-Wdeclaration-after-statement` is used, or C standard prior to C99. + +```c +{ + G_RW_LOCK_WRITER_AUTO_LOCK (&obj->rw_lock, locker); + + obj->stuff_with_lock (); + if (condition) + { + // No need to unlock + return; + } + + // Unlock before end of scope + g_clear_pointer (&locker, g_rw_lock_writer_locker_free); + obj->stuff_without_lock (); +} +``` + + + + a [type@GLib.RWLock] + + + a variable name to be declared + + + + + The GRand struct is an opaque data structure. It should only be accessed through the g_rand_* functions. - - + + Copies a #GRand into a new one with the same exact state as before. + filename="glib/grand.c" + line="158">Creates a new random number generator initialized with a seed taken +either from `/dev/urandom` (if existing) or from the current time +(as a fallback). + +On Windows, the seed is taken from rand_s(). + + + the new #GRand + + + + + Creates a new random number generator initialized with @seed. + + + the new #GRand + + + + + a value to initialize the random number generator + + + + + + Creates a new random number generator initialized with @seed. + + + the new #GRand + + + + + an array of seeds to initialize the random number generator + + + + an array of seeds to initialize the random number + generator + + + + + + Copies a #GRand into a new one with the same exact state as before. This way you can take a snapshot of the random number generator for replaying later. - - + + the new #GRand + filename="glib/grand.c" + line="262">the new #GRand a #GRand + filename="glib/grand.c" + line="256">a #GRand Returns the next random #gdouble from @rand_ equally distributed over + filename="glib/grand.c" + line="523">Returns the next random #gdouble from @rand_ equally distributed over the range [0..1). - + a random number + filename="glib/grand.c" + line="530">a random number a #GRand + filename="glib/grand.c" + line="525">a #GRand Returns the next random #gdouble from @rand_ equally distributed over + filename="glib/grand.c" + line="548">Returns the next random #gdouble from @rand_ equally distributed over the range [@begin..@end). - + a random number + filename="glib/grand.c" + line="557">a random number a #GRand + filename="glib/grand.c" + line="550">a #GRand lower closed bound of the interval + filename="glib/grand.c" + line="551">lower closed bound of the interval upper open bound of the interval + filename="glib/grand.c" + line="552">upper open bound of the interval Frees the memory allocated for the #GRand. - + filename="glib/grand.c" + line="240">Frees the memory allocated for the #GRand. + a #GRand + filename="glib/grand.c" + line="242">a #GRand Returns the next random #guint32 from @rand_ equally distributed over + filename="glib/grand.c" + line="392">Returns the next random #guint32 from @rand_ equally distributed over the range [0..2^32-1]. - + a random number + filename="glib/grand.c" + line="399">a random number a #GRand + filename="glib/grand.c" + line="394">a #GRand Returns the next random #gint32 from @rand_ equally distributed over + filename="glib/grand.c" + line="439">Returns the next random #gint32 from @rand_ equally distributed over the range [@begin..@end-1]. - + a random number + filename="glib/grand.c" + line="448">a random number a #GRand + filename="glib/grand.c" + line="441">a #GRand lower closed bound of the interval + filename="glib/grand.c" + line="442">lower closed bound of the interval upper open bound of the interval + filename="glib/grand.c" + line="443">upper open bound of the interval Sets the seed for the random number generator #GRand to @seed. - + filename="glib/grand.c" + line="279">Sets the seed for the random number generator #GRand to @seed. + a #GRand + filename="glib/grand.c" + line="281">a #GRand a value to reinitialize the random number generator + filename="glib/grand.c" + line="282">a value to reinitialize the random number generator @@ -31893,110 +33760,42 @@ the range [@begin..@end-1]. c:identifier="g_rand_set_seed_array" version="2.4"> Initializes the random number generator by an array of longs. + filename="glib/grand.c" + line="323">Initializes the random number generator by an array of longs. Array can be of arbitrary size, though only the first 624 values are taken. This function is useful if you have many low entropy seeds, or if you require more then 32 bits of actual entropy for your application. - + a #GRand + filename="glib/grand.c" + line="325">a #GRand array to initialize with + filename="glib/grand.c" + line="326">array to initialize with length of array + filename="glib/grand.c" + line="327">length of array - - Creates a new random number generator initialized with a seed taken -either from `/dev/urandom` (if existing) or from the current time -(as a fallback). - -On Windows, the seed is taken from rand_s(). - - - the new #GRand - - - - - Creates a new random number generator initialized with @seed. - - - the new #GRand - - - - - a value to initialize the random number generator - - - - - - Creates a new random number generator initialized with @seed. - - - the new #GRand - - - - - an array of seeds to initialize the random number generator - - - - an array of seeds to initialize the random number - generator - - - - The GRecMutex struct is an opaque data structure to represent a + filename="glib/gthread.c" + line="269">The GRecMutex struct is an opaque data structure to represent a recursive mutex. It is similar to a #GMutex with the difference that it is possible to lock a GRecMutex multiple times in the same thread without deadlock. When doing so, care has to be taken to @@ -32008,7 +33807,7 @@ g_rec_mutex_init() on it and g_rec_mutex_clear() when done. A GRecMutex should only be accessed with the g_rec_mutex_ functions. - + @@ -32019,8 +33818,8 @@ g_rec_mutex_ functions. Frees the resources allocated to a recursive mutex with + filename="glib/gthread.c" + line="1359">Frees the resources allocated to a recursive mutex with g_rec_mutex_init(). This function should not be used with a #GRecMutex that has been @@ -32028,23 +33827,23 @@ statically allocated. Calling g_rec_mutex_clear() on a locked recursive mutex leads to undefined behaviour. - + an initialized #GRecMutex + filename="glib/gthread.c" + line="1361">an initialized #GRecMutex Initializes a #GRecMutex so that it can be used. + filename="glib/gthread.c" + line="1320">Initializes a #GRecMutex so that it can be used. This function is useful to initialize a recursive mutex that has been allocated on the stack, or as part of a larger @@ -32070,81 +33869,81 @@ leads to undefined behaviour. To undo the effect of g_rec_mutex_init() when a recursive mutex is no longer needed, use g_rec_mutex_clear(). - + an uninitialized #GRecMutex + filename="glib/gthread.c" + line="1322">an uninitialized #GRecMutex Locks @rec_mutex. If @rec_mutex is already locked by another + filename="glib/gthread.c" + line="1380">Locks @rec_mutex. If @rec_mutex is already locked by another thread, the current thread will block until @rec_mutex is unlocked by the other thread. If @rec_mutex is already locked by the current thread, the 'lock count' of @rec_mutex is increased. The mutex will only become available again when it is unlocked as many times as it has been locked. - + a #GRecMutex + filename="glib/gthread.c" + line="1382">a #GRecMutex Tries to lock @rec_mutex. If @rec_mutex is already locked + filename="glib/gthread.c" + line="1418">Tries to lock @rec_mutex. If @rec_mutex is already locked by another thread, it immediately returns %FALSE. Otherwise it locks @rec_mutex and returns %TRUE. - + %TRUE if @rec_mutex could be locked + filename="glib/gthread.c" + line="1426">%TRUE if @rec_mutex could be locked a #GRecMutex + filename="glib/gthread.c" + line="1420">a #GRecMutex Unlocks @rec_mutex. If another thread is blocked in a + filename="glib/gthread.c" + line="1399">Unlocks @rec_mutex. If another thread is blocked in a g_rec_mutex_lock() call for @rec_mutex, it will become unblocked and can lock @rec_mutex itself. Calling g_rec_mutex_unlock() on a recursive mutex that is not locked by the current thread leads to undefined behaviour. - + a #GRecMutex + filename="glib/gthread.c" + line="1401">a #GRecMutex @@ -32158,10 +33957,12 @@ locked by the current thread leads to undefined behaviour. glib:get-type="g_regex_get_type" c:symbol-prefix="regex"> The g_regex_*() functions implement regular -expression pattern matching using syntax and semantics similar to -Perl regular expression. + filename="glib/gregex.c" + line="42">A `GRegex` is the "compiled" form of a regular expression pattern. + +`GRegex` implements regular expression pattern matching using syntax and +semantics similar to Perl regular expression. See the +[PCRE documentation](man:pcrepattern(3)) for the syntax definition. Some functions accept a @start_position argument, setting it differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL @@ -32195,57 +33996,55 @@ separator, U+2028), or PS (paragraph separator, U+2029). The behaviour of the dot, circumflex, and dollar metacharacters are affected by newline characters, the default is to recognize any newline character (the same characters recognized by "\R"). This can be changed -with %G_REGEX_NEWLINE_CR, %G_REGEX_NEWLINE_LF and %G_REGEX_NEWLINE_CRLF -compile options, and with %G_REGEX_MATCH_NEWLINE_ANY, -%G_REGEX_MATCH_NEWLINE_CR, %G_REGEX_MATCH_NEWLINE_LF and -%G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also -relevant when compiling a pattern if %G_REGEX_EXTENDED is set, and an +with `G_REGEX_NEWLINE_CR`, `G_REGEX_NEWLINE_LF` and `G_REGEX_NEWLINE_CRLF` +compile options, and with `G_REGEX_MATCH_NEWLINE_ANY`, +`G_REGEX_MATCH_NEWLINE_CR`, `G_REGEX_MATCH_NEWLINE_LF` and +`G_REGEX_MATCH_NEWLINE_CRLF` match options. These settings are also +relevant when compiling a pattern if `G_REGEX_EXTENDED` is set, and an unescaped "#" outside a character class is encountered. This indicates a comment that lasts until after the next newline. -Creating and manipulating the same #GRegex structure from different -threads is not a problem as #GRegex does not modify its internal -state between creation and destruction, on the other hand #GMatchInfo +Creating and manipulating the same `GRegex` structure from different +threads is not a problem as `GRegex` does not modify its internal +state between creation and destruction, on the other hand `GMatchInfo` is not threadsafe. The regular expressions low-level functionalities are obtained through -the excellent -[PCRE](http://www.pcre.org/) -library written by Philip Hazel. - +the excellent [PCRE](http://www.pcre.org/) library written by Philip Hazel. + Compiles the regular expression to an internal form, and does + filename="glib/gregex.c" + line="1710">Compiles the regular expression to an internal form, and does the initial setup of the #GRegex structure. - + a #GRegex structure or %NULL if an error occurred. Call + filename="glib/gregex.c" + line="1720">a #GRegex structure or %NULL if an error occurred. Call g_regex_unref() when you are done with it the regular expression + filename="glib/gregex.c" + line="1712">the regular expression compile options for the regular expression, or 0 + filename="glib/gregex.c" + line="1713">compile options for the regular expression, or 0 match options for the regular expression, or 0 + filename="glib/gregex.c" + line="1714">match options for the regular expression, or 0 @@ -32254,20 +34053,20 @@ the initial setup of the #GRegex structure. c:identifier="g_regex_get_capture_count" version="2.14"> Returns the number of capturing subpatterns in the pattern. - + filename="glib/gregex.c" + line="1959">Returns the number of capturing subpatterns in the pattern. + the number of capturing subpatterns + filename="glib/gregex.c" + line="1965">the number of capturing subpatterns a #GRegex + filename="glib/gregex.c" + line="1961">a #GRegex @@ -32276,24 +34075,24 @@ the initial setup of the #GRegex structure. c:identifier="g_regex_get_compile_flags" version="2.26"> Returns the compile options that @regex was created with. + filename="glib/gregex.c" + line="2022">Returns the compile options that @regex was created with. Depending on the version of PCRE that is used, this may or may not include flags set by option expressions such as `(?i)` found at the top-level within the compiled pattern. - + flags from #GRegexCompileFlags + filename="glib/gregex.c" + line="2032">flags from #GRegexCompileFlags a #GRegex + filename="glib/gregex.c" + line="2024">a #GRegex @@ -32302,20 +34101,20 @@ top-level within the compiled pattern. c:identifier="g_regex_get_has_cr_or_lf" version="2.34"> Checks whether the pattern contains explicit CR or LF references. - + filename="glib/gregex.c" + line="1979">Checks whether the pattern contains explicit CR or LF references. + %TRUE if the pattern contains explicit CR or LF references + filename="glib/gregex.c" + line="1985">%TRUE if the pattern contains explicit CR or LF references a #GRegex structure + filename="glib/gregex.c" + line="1981">a #GRegex structure @@ -32324,20 +34123,20 @@ top-level within the compiled pattern. c:identifier="g_regex_get_match_flags" version="2.26"> Returns the match options that @regex was created with. - + filename="glib/gregex.c" + line="2081">Returns the match options that @regex was created with. + flags from #GRegexMatchFlags + filename="glib/gregex.c" + line="2087">flags from #GRegexMatchFlags a #GRegex + filename="glib/gregex.c" + line="2083">a #GRegex @@ -32346,22 +34145,22 @@ top-level within the compiled pattern. c:identifier="g_regex_get_max_backref" version="2.14"> Returns the number of the highest back reference + filename="glib/gregex.c" + line="1937">Returns the number of the highest back reference in the pattern, or 0 if the pattern does not contain back references. - + the number of the highest back reference + filename="glib/gregex.c" + line="1945">the number of the highest back reference a #GRegex + filename="glib/gregex.c" + line="1939">a #GRegex @@ -32370,22 +34169,22 @@ back references. c:identifier="g_regex_get_max_lookbehind" version="2.38"> Gets the number of characters in the longest lookbehind assertion in the + filename="glib/gregex.c" + line="1999">Gets the number of characters in the longest lookbehind assertion in the pattern. This information is useful when doing multi-segment matching using the partial matching facilities. - + the number of characters in the longest lookbehind assertion. + filename="glib/gregex.c" + line="2007">the number of characters in the longest lookbehind assertion. a #GRegex structure + filename="glib/gregex.c" + line="2001">a #GRegex structure @@ -32394,21 +34193,21 @@ the partial matching facilities. c:identifier="g_regex_get_pattern" version="2.14"> Gets the pattern string associated with @regex, i.e. a copy of + filename="glib/gregex.c" + line="1918">Gets the pattern string associated with @regex, i.e. a copy of the string passed to g_regex_new(). - + the pattern of @regex + filename="glib/gregex.c" + line="1925">the pattern of @regex a #GRegex structure + filename="glib/gregex.c" + line="1920">a #GRegex structure @@ -32417,35 +34216,35 @@ the string passed to g_regex_new(). c:identifier="g_regex_get_string_number" version="2.14"> Retrieves the number of the subexpression named @name. - + filename="glib/gregex.c" + line="2503">Retrieves the number of the subexpression named @name. + The number of the subexpression or -1 if @name + filename="glib/gregex.c" + line="2510">The number of the subexpression or -1 if @name does not exists #GRegex structure + filename="glib/gregex.c" + line="2505">#GRegex structure name of the subexpression + filename="glib/gregex.c" + line="2506">name of the subexpression Scans for a match in @string for the pattern in @regex. + filename="glib/gregex.c" + line="2144">Scans for a match in @string for the pattern in @regex. The @match_options are combined with the match options specified when the @regex structure was created, letting you have more flexibility in reusing #GRegex structures. @@ -32485,30 +34284,30 @@ print_uppercase_words (const gchar *string) @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. - + %TRUE is the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="2193">%TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() + filename="glib/gregex.c" + line="2146">a #GRegex structure from g_regex_new() the string to scan for matches + filename="glib/gregex.c" + line="2147">the string to scan for matches match options + filename="glib/gregex.c" + line="2148">match options optional="1" allow-none="1"> pointer to location where to store + filename="glib/gregex.c" + line="2149">pointer to location where to store the #GMatchInfo, or %NULL if you do not need it @@ -32527,8 +34326,8 @@ freeing or modifying @string then the behaviour is undefined. Using the standard algorithm for regular expression matching only + filename="glib/gregex.c" + line="2303">Using the standard algorithm for regular expression matching only the longest match in the string is retrieved. This function uses a different algorithm so it can retrieve all the possible matches. For more documentation see g_regex_match_all_full(). @@ -32542,30 +34341,30 @@ matched. @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. - + %TRUE is the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="2326">%TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() + filename="glib/gregex.c" + line="2305">a #GRegex structure from g_regex_new() the string to scan for matches + filename="glib/gregex.c" + line="2306">the string to scan for matches match options + filename="glib/gregex.c" + line="2307">match options optional="1" allow-none="1"> pointer to location where to store + filename="glib/gregex.c" + line="2308">pointer to location where to store the #GMatchInfo, or %NULL if you do not need it @@ -32587,19 +34386,19 @@ freeing or modifying @string then the behaviour is undefined. version="2.14" throws="1"> Using the standard algorithm for regular expression matching only + filename="glib/gregex.c" + line="2340">Using the standard algorithm for regular expression matching only the longest match in the @string is retrieved, it is not possible to obtain all the available matches. For instance matching -"<a> <b> <c>" against the pattern "<.*>" -you get "<a> <b> <c>". +`"<a> <b> <c>"` against the pattern `"<.*>"` +you get `"<a> <b> <c>"`. This function uses a different algorithm (called DFA, i.e. deterministic finite automaton), so it can retrieve all the possible matches, all starting at the same point in the string. For instance matching -"<a> <b> <c>" against the pattern "<.*>;" -you would obtain three matches: "<a> <b> <c>", -"<a> <b>" and "<a>". +`"<a> <b> <c>"` against the pattern `"<.*>"` +you would obtain three matches: `"<a> <b> <c>"`, +`"<a> <b>"` and `"<a>"`. The number of matched strings is retrieved using g_match_info_get_match_count(). To obtain the matched strings and @@ -32626,44 +34425,44 @@ matched. @string is not copied and is used in #GMatchInfo internally. If you use any #GMatchInfo method (except g_match_info_free()) after freeing or modifying @string then the behaviour is undefined. - + %TRUE is the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="2390">%TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() + filename="glib/gregex.c" + line="2342">a #GRegex structure from g_regex_new() the string to scan for matches + filename="glib/gregex.c" + line="2343">the string to scan for matches the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="2344">the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes + filename="glib/gregex.c" + line="2345">starting index of the string to match, in bytes match options + filename="glib/gregex.c" + line="2346">match options optional="1" allow-none="1"> pointer to location where to store + filename="glib/gregex.c" + line="2347">pointer to location where to store the #GMatchInfo, or %NULL if you do not need it @@ -32685,8 +34484,8 @@ freeing or modifying @string then the behaviour is undefined. version="2.14" throws="1"> Scans for a match in @string for the pattern in @regex. + filename="glib/gregex.c" + line="2207">Scans for a match in @string for the pattern in @regex. The @match_options are combined with the match options specified when the @regex structure was created, letting you have more flexibility in reusing #GRegex structures. @@ -32737,44 +34536,44 @@ print_uppercase_words (const gchar *string) } } ]| - + %TRUE is the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="2270">%TRUE is the string matched, %FALSE otherwise a #GRegex structure from g_regex_new() + filename="glib/gregex.c" + line="2209">a #GRegex structure from g_regex_new() the string to scan for matches + filename="glib/gregex.c" + line="2210">the string to scan for matches the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="2211">the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes + filename="glib/gregex.c" + line="2212">starting index of the string to match, in bytes match options + filename="glib/gregex.c" + line="2213">match options pointer to location where to store + filename="glib/gregex.c" + line="2214">pointer to location where to store the #GMatchInfo, or %NULL if you do not need it @@ -32793,20 +34592,20 @@ print_uppercase_words (const gchar *string) Increases reference count of @regex by 1. - + filename="glib/gregex.c" + line="1660">Increases reference count of @regex by 1. + @regex + filename="glib/gregex.c" + line="1666">@regex a #GRegex + filename="glib/gregex.c" + line="1662">a #GRegex @@ -32816,15 +34615,15 @@ print_uppercase_words (const gchar *string) version="2.14" throws="1"> Replaces all occurrences of the pattern in @regex with the -replacement text. Backreferences of the form '\number' or -'\g<number>' in the replacement text are interpolated by the -number-th captured subexpression of the match, '\g<name>' refers -to the captured subexpression with the given name. '\0' refers -to the complete match, but '\0' followed by a number is the octal -representation of a character. To include a literal '\' in the -replacement, write '\\\\'. + filename="glib/gregex.c" + line="3257">Replaces all occurrences of the pattern in @regex with the +replacement text. Backreferences of the form `\number` or +`\g<number>` in the replacement text are interpolated by the +number-th captured subexpression of the match, `\g<name>` refers +to the captured subexpression with the given name. `\0` refers +to the complete match, but `\0` followed by a number is the octal +representation of a character. To include a literal `\` in the +replacement, write `\\\\`. There are also escapes that changes the case of the following text: @@ -32843,50 +34642,50 @@ you can use g_regex_replace_literal(). Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". - + a newly allocated string containing the replacements + filename="glib/gregex.c" + line="3294">a newly allocated string containing the replacements a #GRegex structure + filename="glib/gregex.c" + line="3259">a #GRegex structure the string to perform matches against + filename="glib/gregex.c" + line="3260">the string to perform matches against the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="3261">the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes + filename="glib/gregex.c" + line="3262">starting index of the string to match, in bytes text to replace each match with + filename="glib/gregex.c" + line="3263">text to replace each match with options for the match + filename="glib/gregex.c" + line="3264">options for the match @@ -32894,11 +34693,10 @@ begins with any kind of lookbehind assertion, such as "\b". Replaces occurrences of the pattern in regex with the output of + filename="glib/gregex.c" + line="3391">Replaces occurrences of the pattern in regex with the output of @eval for that occurrence. Setting @start_position differs from just passing over a shortened @@ -32943,50 +34741,53 @@ g_hash_table_destroy (h); ... ]| - + a newly allocated string containing the replacements + filename="glib/gregex.c" + line="3448">a newly allocated string containing the replacements a #GRegex structure from g_regex_new() + filename="glib/gregex.c" + line="3393">a #GRegex structure from g_regex_new() string to perform matches against + filename="glib/gregex.c" + line="3394">string to perform matches against the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="3395">the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes + filename="glib/gregex.c" + line="3396">starting index of the string to match, in bytes options for the match + filename="glib/gregex.c" + line="3397">options for the match - + a function to call for each match + filename="glib/gregex.c" + line="3398">a function to call for each match user data to pass to the function + filename="glib/gregex.c" + line="3399">user data to pass to the function @@ -33005,8 +34806,8 @@ g_hash_table_destroy (h); version="2.14" throws="1"> Replaces all occurrences of the pattern in @regex with the + filename="glib/gregex.c" + line="3348">Replaces all occurrences of the pattern in @regex with the replacement text. @replacement is replaced literally, to include backreferences use g_regex_replace(). @@ -33014,58 +34815,58 @@ Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". - + a newly allocated string containing the replacements + filename="glib/gregex.c" + line="3367">a newly allocated string containing the replacements a #GRegex structure + filename="glib/gregex.c" + line="3350">a #GRegex structure the string to perform matches against + filename="glib/gregex.c" + line="3351">the string to perform matches against the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="3352">the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes + filename="glib/gregex.c" + line="3353">starting index of the string to match, in bytes text to replace each match with + filename="glib/gregex.c" + line="3354">text to replace each match with options for the match + filename="glib/gregex.c" + line="3355">options for the match Breaks the string on the pattern, and returns an array of the tokens. + filename="glib/gregex.c" + line="2589">Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first @@ -33082,11 +34883,11 @@ A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". - + a %NULL-terminated gchar ** array. Free + filename="glib/gregex.c" + line="2613">a %NULL-terminated gchar ** array. Free it using g_strfreev() @@ -33095,20 +34896,20 @@ it using g_strfreev() a #GRegex structure + filename="glib/gregex.c" + line="2591">a #GRegex structure the string to split with the pattern + filename="glib/gregex.c" + line="2592">the string to split with the pattern match time option flags + filename="glib/gregex.c" + line="2593">match time option flags @@ -33118,8 +34919,8 @@ it using g_strfreev() version="2.14" throws="1"> Breaks the string on the pattern, and returns an array of the tokens. + filename="glib/gregex.c" + line="2627">Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the whole string is returned as the first @@ -33140,11 +34941,11 @@ For example splitting "ab c" using as a separator "\s*", you will get Setting @start_position differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b". - + a %NULL-terminated gchar ** array. Free + filename="glib/gregex.c" + line="2660">a %NULL-terminated gchar ** array. Free it using g_strfreev() @@ -33153,40 +34954,40 @@ it using g_strfreev() a #GRegex structure + filename="glib/gregex.c" + line="2629">a #GRegex structure the string to split with the pattern + filename="glib/gregex.c" + line="2630">the string to split with the pattern the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="2631">the length of @string, in bytes, or -1 if @string is nul-terminated starting index of the string to match, in bytes + filename="glib/gregex.c" + line="2632">starting index of the string to match, in bytes match time option flags + filename="glib/gregex.c" + line="2633">match time option flags the maximum number of tokens to split @string into. + filename="glib/gregex.c" + line="2634">the maximum number of tokens to split @string into. If this is less than 1, the string is split completely @@ -33194,18 +34995,18 @@ it using g_strfreev() Decreases reference count of @regex by 1. When reference count drops + filename="glib/gregex.c" + line="1678">Decreases reference count of @regex by 1. When reference count drops to zero, it frees all the memory associated with the regex structure. - + a #GRegex + filename="glib/gregex.c" + line="1680">a #GRegex @@ -33215,8 +35016,8 @@ to zero, it frees all the memory associated with the regex structure. version="2.14" throws="1"> Checks whether @replacement is a valid replacement string + filename="glib/gregex.c" + line="3503">Checks whether @replacement is a valid replacement string (see g_regex_replace()), i.e. that all escape sequences in it are valid. @@ -33225,18 +35026,18 @@ for pattern references. For instance, replacement text 'foo\n' does not contain references and may be evaluated without information about actual match, but '\0\1' (whole match followed by first subpattern) requires valid #GMatchInfo object. - + whether @replacement is a valid replacement string + filename="glib/gregex.c" + line="3520">whether @replacement is a valid replacement string the replacement string + filename="glib/gregex.c" + line="3505">the replacement string optional="1" allow-none="1"> location to store information about + filename="glib/gregex.c" + line="3506">location to store information about references in @replacement or %NULL @@ -33262,30 +35063,30 @@ subpattern) requires valid #GMatchInfo object. c:identifier="g_regex_escape_nul" version="2.30"> Escapes the nul characters in @string to "\x00". It can be used + filename="glib/gregex.c" + line="3548">Escapes the nul characters in @string to "\x00". It can be used to compile a regex with embedded nul characters. For completeness, @length can be -1 for a nul-terminated string. In this case the output string will be of course equal to @string. - + a newly-allocated escaped string + filename="glib/gregex.c" + line="3559">a newly-allocated escaped string the string to escape + filename="glib/gregex.c" + line="3550">the string to escape the length of @string + filename="glib/gregex.c" + line="3551">the length of @string @@ -33294,32 +35095,32 @@ In this case the output string will be of course equal to @string. c:identifier="g_regex_escape_string" version="2.14"> Escapes the special characters used for regular expressions + filename="glib/gregex.c" + line="3616">Escapes the special characters used for regular expressions in @string, for instance "a.b*c" becomes "a\.b\*c". This function is useful to dynamically generate regular expressions. @string can contain nul characters that are replaced with "\0", in this case remember to specify the correct length of @string in @length. - + a newly-allocated escaped string + filename="glib/gregex.c" + line="3629">a newly-allocated escaped string the string to escape + filename="glib/gregex.c" + line="3618">the string to escape the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="3619">the length of @string, in bytes, or -1 if @string is nul-terminated @@ -33328,8 +35129,8 @@ in @length. c:identifier="g_regex_match_simple" version="2.14"> Scans for a match in @string for @pattern. + filename="glib/gregex.c" + line="2105">Scans for a match in @string for @pattern. This function is equivalent to g_regex_match() but it does not require to compile the pattern with g_regex_new(), avoiding some @@ -33339,36 +35140,36 @@ substrings, capture counts, and so on. If this function is to be called on the same @pattern more than once, it's more efficient to compile the pattern once with g_regex_new() and then use g_regex_match(). - + %TRUE if the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="2123">%TRUE if the string matched, %FALSE otherwise the regular expression + filename="glib/gregex.c" + line="2107">the regular expression the string to scan for matches + filename="glib/gregex.c" + line="2108">the string to scan for matches compile options for the regular expression, or 0 + filename="glib/gregex.c" + line="2109">compile options for the regular expression, or 0 match options, or 0 + filename="glib/gregex.c" + line="2110">match options, or 0 @@ -33377,8 +35178,8 @@ g_regex_new() and then use g_regex_match(). c:identifier="g_regex_split_simple" version="2.14"> Breaks the string on the pattern, and returns an array of + filename="glib/gregex.c" + line="2531">Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the @@ -33405,11 +35206,11 @@ A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". - + a %NULL-terminated array of strings. Free + filename="glib/gregex.c" + line="2566">a %NULL-terminated array of strings. Free it using g_strfreev() @@ -33418,26 +35219,26 @@ it using g_strfreev() the regular expression + filename="glib/gregex.c" + line="2533">the regular expression the string to scan for matches + filename="glib/gregex.c" + line="2534">the string to scan for matches compile options for the regular expression, or 0 + filename="glib/gregex.c" + line="2535">compile options for the regular expression, or 0 match options, or 0 + filename="glib/gregex.c" + line="2536">match options, or 0 @@ -33447,24 +35248,24 @@ it using g_strfreev() version="2.14" c:type="GRegexCompileFlags"> Flags specifying compile-time options. - + No special options set. Since: 2.74 Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only @@ -33479,14 +35280,14 @@ it using g_strfreev() A dot metacharacter (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, @@ -33496,7 +35297,7 @@ it using g_strfreev() The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by @@ -33507,7 +35308,7 @@ it using g_strfreev() value="32" c:identifier="G_REGEX_DOLLAR_ENDONLY"> A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if @@ -33516,14 +35317,14 @@ it using g_strfreev() Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @@ -33531,7 +35332,7 @@ it using g_strfreev() value="4096" c:identifier="G_REGEX_NO_AUTO_CAPTURE"> Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named @@ -33540,7 +35341,7 @@ it using g_strfreev() Since 2.74 and the port to pcre2, requests JIT compilation, which, if the just-in-time compiler is available, further processes a compiled pattern into machine code that executes much @@ -33551,13 +35352,13 @@ it using g_strfreev() Limits an unanchored pattern to match before (or at) the first newline. Since: 2.34 Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be @@ -33567,7 +35368,7 @@ it using g_strfreev() value="1048576" c:identifier="G_REGEX_NEWLINE_CR"> Usually any newline character or character sequence is recognized. If this option is set, the only recognized newline character is '\r'. @@ -33576,7 +35377,7 @@ it using g_strfreev() value="2097152" c:identifier="G_REGEX_NEWLINE_LF"> Usually any newline character or character sequence is recognized. If this option is set, the only recognized newline character is '\n'. @@ -33585,7 +35386,7 @@ it using g_strfreev() value="3145728" c:identifier="G_REGEX_NEWLINE_CRLF"> Usually any newline character or character sequence is recognized. If this option is set, the only recognized newline character sequence is '\r\n'. @@ -33594,7 +35395,7 @@ it using g_strfreev() value="5242880" c:identifier="G_REGEX_NEWLINE_ANYCRLF"> Usually any newline character or character sequence is recognized. If this option is set, the only recognized newline character sequences are '\r', '\n', and '\r\n'. Since: 2.34 @@ -33603,7 +35404,7 @@ it using g_strfreev() value="8388608" c:identifier="G_REGEX_BSR_ANYCRLF"> Usually any newline character or character sequence is recognised. If this option is set, then "\R" only recognizes the newline characters '\r', '\n' and '\r\n'. Since: 2.34 @@ -33612,7 +35413,7 @@ it using g_strfreev() value="33554432" c:identifier="G_REGEX_JAVASCRIPT_COMPAT"> Changes behaviour so that it is compatible with JavaScript rather than PCRE. Since GLib 2.74 this is no longer supported, as libpcre2 does not support it. Since: 2.34 Deprecated: 2.74 @@ -33623,33 +35424,33 @@ it using g_strfreev() c:type="GRegexError" glib:error-domain="g-regex-error-quark"> Error codes returned by regular expressions functions. - + Compilation of the regular expression failed. Optimization of the regular expression failed. Replacement failed due to an ill-formed replacement string. The match process failed. Internal error of the regular expression engine. Since 2.16 @@ -33657,21 +35458,21 @@ it using g_strfreev() value="101" c:identifier="G_REGEX_ERROR_STRAY_BACKSLASH"> "\\" at end of pattern. Since 2.16 "\\c" at end of pattern. Since 2.16 Unrecognized character follows "\\". Since 2.16 @@ -33679,7 +35480,7 @@ it using g_strfreev() value="104" c:identifier="G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER"> Numbers out of order in "{}" quantifier. Since 2.16 @@ -33687,7 +35488,7 @@ it using g_strfreev() value="105" c:identifier="G_REGEX_ERROR_QUANTIFIER_TOO_BIG"> Number too big in "{}" quantifier. Since 2.16 @@ -33695,7 +35496,7 @@ it using g_strfreev() value="106" c:identifier="G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS"> Missing terminating "]" for character class. Since 2.16 @@ -33703,7 +35504,7 @@ it using g_strfreev() value="107" c:identifier="G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS"> Invalid escape sequence in character class. Since 2.16 @@ -33711,7 +35512,7 @@ it using g_strfreev() value="108" c:identifier="G_REGEX_ERROR_RANGE_OUT_OF_ORDER"> Range out of order in character class. Since 2.16 @@ -33719,14 +35520,14 @@ it using g_strfreev() value="109" c:identifier="G_REGEX_ERROR_NOTHING_TO_REPEAT"> Nothing to repeat. Since 2.16 Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 @@ -33734,7 +35535,7 @@ it using g_strfreev() value="113" c:identifier="G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS"> POSIX named classes are supported only within a class. Since 2.16 @@ -33742,7 +35543,7 @@ it using g_strfreev() value="114" c:identifier="G_REGEX_ERROR_UNMATCHED_PARENTHESIS"> Missing terminating ")" or ")" without opening "(". Since 2.16 @@ -33750,7 +35551,7 @@ it using g_strfreev() value="115" c:identifier="G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE"> Reference to non-existent subpattern. Since 2.16 @@ -33758,7 +35559,7 @@ it using g_strfreev() value="118" c:identifier="G_REGEX_ERROR_UNTERMINATED_COMMENT"> Missing terminating ")" after comment. Since 2.16 @@ -33766,7 +35567,7 @@ it using g_strfreev() value="120" c:identifier="G_REGEX_ERROR_EXPRESSION_TOO_LARGE"> Regular expression too large. Since 2.16 @@ -33774,14 +35575,14 @@ it using g_strfreev() value="121" c:identifier="G_REGEX_ERROR_MEMORY_ERROR"> Failed to get memory. Since 2.16 Lookbehind assertion is not fixed length. Since 2.16 @@ -33789,7 +35590,7 @@ it using g_strfreev() value="126" c:identifier="G_REGEX_ERROR_MALFORMED_CONDITION"> Malformed number or name after "(?(". Since 2.16 @@ -33797,7 +35598,7 @@ it using g_strfreev() value="127" c:identifier="G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES"> Conditional group contains more than two branches. Since 2.16 @@ -33805,7 +35606,7 @@ it using g_strfreev() value="128" c:identifier="G_REGEX_ERROR_ASSERTION_EXPECTED"> Assertion expected after "(?(". Since 2.16 @@ -33813,7 +35614,7 @@ it using g_strfreev() value="130" c:identifier="G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME"> Unknown POSIX class name. Since 2.16 @@ -33821,7 +35622,7 @@ it using g_strfreev() value="131" c:identifier="G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED"> POSIX collating elements are not supported. Since 2.16 @@ -33829,7 +35630,7 @@ it using g_strfreev() value="134" c:identifier="G_REGEX_ERROR_HEX_CODE_TOO_LARGE"> Character value in "\\x{...}" sequence is too large. Since 2.16 @@ -33837,14 +35638,14 @@ it using g_strfreev() value="135" c:identifier="G_REGEX_ERROR_INVALID_CONDITION"> Invalid condition "(?(0)". Since 2.16 \\C not allowed in lookbehind assertion. Since 2.16 @@ -33852,7 +35653,7 @@ it using g_strfreev() value="140" c:identifier="G_REGEX_ERROR_INFINITE_LOOP"> Recursive call could loop indefinitely. Since 2.16 @@ -33860,7 +35661,7 @@ it using g_strfreev() value="142" c:identifier="G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR"> Missing terminator in subpattern name. Since 2.16 @@ -33868,7 +35669,7 @@ it using g_strfreev() value="143" c:identifier="G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME"> Two named subpatterns have the same name. Since 2.16 @@ -33876,7 +35677,7 @@ it using g_strfreev() value="146" c:identifier="G_REGEX_ERROR_MALFORMED_PROPERTY"> Malformed "\\P" or "\\p" sequence. Since 2.16 @@ -33884,7 +35685,7 @@ it using g_strfreev() value="147" c:identifier="G_REGEX_ERROR_UNKNOWN_PROPERTY"> Unknown property name after "\\P" or "\\p". Since 2.16 @@ -33892,7 +35693,7 @@ it using g_strfreev() value="148" c:identifier="G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG"> Subpattern name is too long (maximum 32 characters). Since 2.16 @@ -33900,7 +35701,7 @@ it using g_strfreev() value="149" c:identifier="G_REGEX_ERROR_TOO_MANY_SUBPATTERNS"> Too many named subpatterns (maximum 10,000). Since 2.16 @@ -33908,7 +35709,7 @@ it using g_strfreev() value="151" c:identifier="G_REGEX_ERROR_INVALID_OCTAL_VALUE"> Octal value is greater than "\\377". Since 2.16 @@ -33916,7 +35717,7 @@ it using g_strfreev() value="154" c:identifier="G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE"> "DEFINE" group contains more than one branch. Since 2.16 @@ -33924,7 +35725,7 @@ it using g_strfreev() value="155" c:identifier="G_REGEX_ERROR_DEFINE_REPETION"> Repeating a "DEFINE" group is not allowed. This error is never raised. Since: 2.16 Deprecated: 2.34 @@ -33932,7 +35733,7 @@ it using g_strfreev() value="156" c:identifier="G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS"> Inconsistent newline options. Since 2.16 @@ -33940,7 +35741,7 @@ it using g_strfreev() value="157" c:identifier="G_REGEX_ERROR_MISSING_BACK_REFERENCE"> "\\g" is not followed by a braced, angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16 @@ -33948,14 +35749,14 @@ it using g_strfreev() value="158" c:identifier="G_REGEX_ERROR_INVALID_RELATIVE_REFERENCE"> relative reference must not be zero. Since: 2.34 the backtracing control verb used does not allow an argument. Since: 2.34 @@ -33963,7 +35764,7 @@ it using g_strfreev() value="160" c:identifier="G_REGEX_ERROR_UNKNOWN_BACKTRACKING_CONTROL_VERB"> unknown backtracing control verb. Since: 2.34 @@ -33971,28 +35772,28 @@ it using g_strfreev() value="161" c:identifier="G_REGEX_ERROR_NUMBER_TOO_BIG"> number is too big in escape sequence. Since: 2.34 Missing subpattern name. Since: 2.34 Missing digit. Since 2.34 In JavaScript compatibility mode, "[" is an invalid data character. Since: 2.34 @@ -34000,7 +35801,7 @@ it using g_strfreev() value="165" c:identifier="G_REGEX_ERROR_EXTRA_SUBPATTERN_NAME"> different names for subpatterns of the same number are not allowed. Since: 2.34 @@ -34008,7 +35809,7 @@ it using g_strfreev() value="166" c:identifier="G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_REQUIRED"> the backtracing control verb requires an argument. Since: 2.34 @@ -34016,7 +35817,7 @@ it using g_strfreev() value="168" c:identifier="G_REGEX_ERROR_INVALID_CONTROL_CHAR"> "\\c" must be followed by an ASCII character. Since: 2.34 @@ -34024,7 +35825,7 @@ it using g_strfreev() value="169" c:identifier="G_REGEX_ERROR_MISSING_NAME"> "\\k" is not followed by a braced, angle-bracketed, or quoted name. Since: 2.34 @@ -34032,21 +35833,21 @@ it using g_strfreev() value="171" c:identifier="G_REGEX_ERROR_NOT_SUPPORTED_IN_CLASS"> "\\N" is not supported in a class. Since: 2.34 too many forward references. Since: 2.34 the name is too long in "(*MARK)", "(*PRUNE)", "(*SKIP)", or "(*THEN)". Since: 2.34 @@ -34054,7 +35855,7 @@ it using g_strfreev() value="176" c:identifier="G_REGEX_ERROR_CHARACTER_VALUE_TOO_LARGE"> the character value in the \\u sequence is too large. Since: 2.34 @@ -34063,31 +35864,31 @@ it using g_strfreev() c:type="GRegexEvalCallback" version="2.14"> Specifies the type of the function passed to g_regex_replace_eval(). + filename="glib/gregex.h" + line="427">Specifies the type of the function passed to g_regex_replace_eval(). It is called for each occurrence of the pattern in the string passed to g_regex_replace_eval(), and it should append the replacement to @result. - + %FALSE to continue the replacement process, %TRUE to stop it + filename="glib/gregex.h" + line="440">%FALSE to continue the replacement process, %TRUE to stop it the #GMatchInfo generated by the match. + filename="glib/gregex.h" + line="429">the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. a #GString containing the new string + filename="glib/gregex.h" + line="432">a #GString containing the new string user data passed to g_regex_replace_eval() + filename="glib/gregex.h" + line="433">user data passed to g_regex_replace_eval() Flags specifying match-time options. - + No special options set. Since: 2.74 The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by @@ -34123,7 +35924,7 @@ to g_regex_replace_eval(), and it should append the replacement to Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without %G_REGEX_MULTILINE (at @@ -34133,7 +35934,7 @@ to g_regex_replace_eval(), and it should append the replacement to Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. @@ -34145,7 +35946,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="1024" c:identifier="G_REGEX_MATCH_NOTEMPTY"> An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the @@ -34159,7 +35960,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="32768" c:identifier="G_REGEX_MATCH_PARTIAL"> Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). @@ -34167,7 +35968,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="1048576" c:identifier="G_REGEX_MATCH_NEWLINE_CR"> Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. @@ -34175,7 +35976,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="2097152" c:identifier="G_REGEX_MATCH_NEWLINE_LF"> Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. @@ -34183,7 +35984,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="3145728" c:identifier="G_REGEX_MATCH_NEWLINE_CRLF"> Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters sequence as line terminator. @@ -34191,7 +35992,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="4194304" c:identifier="G_REGEX_MATCH_NEWLINE_ANY"> Overrides the newline definition set when creating a new #GRegex, any Unicode newline sequence is recognised as a newline. These are '\r', '\n' and '\rn', and the @@ -34203,7 +36004,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="5242880" c:identifier="G_REGEX_MATCH_NEWLINE_ANYCRLF"> Overrides the newline definition set when creating a new #GRegex; any '\r', '\n', or '\r\n' character sequence is recognized as a newline. Since: 2.34 @@ -34212,7 +36013,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="8388608" c:identifier="G_REGEX_MATCH_BSR_ANYCRLF"> Overrides the newline definition for "\R" set when creating a new #GRegex; only '\r', '\n', or '\r\n' character sequences are recognized as a newline by "\R". Since: 2.34 @@ -34221,7 +36022,7 @@ to g_regex_replace_eval(), and it should append the replacement to value="16777216" c:identifier="G_REGEX_MATCH_BSR_ANY"> Overrides the newline definition for "\R" set when creating a new #GRegex; any Unicode newline character or character sequence are recognized as a newline by "\R". These are '\r', '\n' and '\rn', and the @@ -34233,14 +36034,14 @@ to g_regex_replace_eval(), and it should append the replacement to value="32768" c:identifier="G_REGEX_MATCH_PARTIAL_SOFT"> An alias for %G_REGEX_MATCH_PARTIAL. Since: 2.34 Turns on the partial matching feature. In contrast to to %G_REGEX_MATCH_PARTIAL_SOFT, this stops matching as soon as a partial match is found, without continuing to search for a possible complete match. See @@ -34250,34 +36051,382 @@ to g_regex_replace_eval(), and it should append the replacement to value="268435456" c:identifier="G_REGEX_MATCH_NOTEMPTY_ATSTART"> Like %G_REGEX_MATCH_NOTEMPTY, but only applied to the start of the matched string. For anchored patterns this can only happen for pattern containing "\K". Since: 2.34 + + A `GRelation` is a table of data which can be indexed on any number +of fields, rather like simple database tables. A `GRelation` contains +a number of records, called tuples. Each record contains a number of +fields. Records are not ordered, so it is not possible to find the +record at a particular index. + +Note that `GRelation` tables are currently limited to 2 fields. + +To create a `GRelation`, use [func@GLib.Relation.new]. + +To specify which fields should be indexed, use [method@GLib.Relation.index]. +Note that this must be called before any tuples are added to the +`GRelation`. + +To add records to a `GRelation` use [method@GLib.Relation.insert]. + +To determine if a given record appears in a `GRelation`, use +[method@GLib.Relation.exists]. Note that fields are compared directly, so +pointers must point to the exact same position (i.e. different +copies of the same string will not match.) + +To count the number of records which have a particular value in a +given field, use [method@GLib.Relation.count]. + +To get all the records which have a particular value in a given +field, use [method@GLib.Relation.select]. To access fields of the resulting +records, use [method@GLib.Tuples.index]. To free the resulting records use +[method@GLib.Tuples.destroy]. + +To delete all records which have a particular value in a given +field, use [method@GLib.Relation.delete]. + +To destroy the `GRelation`, use [method@GLib.Relation.destroy]. + +To help debug `GRelation` objects, use [method@GLib.Relation.print]. + +`GRelation` has been marked as deprecated, since this API has never +been fully implemented, is not very actively maintained and rarely +used. + Rarely used API + + + Returns the number of tuples in a #GRelation that have the given +value in the given field. + Rarely used API + + + the number of matches. + + + + + a #GRelation. + + + + the value to compare with. + + + + the field of each record to match. + + + + + + Deletes any records from a #GRelation that have the given key value +in the given field. + Rarely used API + + + the number of records deleted. + + + + + a #GRelation. + + + + the value to compare with. + + + + the field of each record to match. + + + + + + Destroys the #GRelation, freeing all memory allocated. However, it +does not free memory allocated for the tuple data, so you should +free that first if appropriate. + Rarely used API + + + + + + + a #GRelation. + + + + + + Returns %TRUE if a record with the given values exists in a +#GRelation. Note that the values are compared directly, so that, for +example, two copies of the same string will not match. + Rarely used API + + + %TRUE if a record matches. + + + + + a #GRelation. + + + + the fields of the record to compare. The number must match + the number of fields in the #GRelation. + + + + + + Creates an index on the given field. Note that this must be called +before any records are added to the #GRelation. + Rarely used API + + + + + + + a #GRelation. + + + + the field to index, counting from 0. + + + + a function to produce a hash value from the field data. + + + + a function to compare two values of the given field. + + + + + + Inserts a record into a #GRelation. + Rarely used API + + + + + + + a #GRelation. + + + + the fields of the record to add. These must match the + number of fields in the #GRelation, and of type #gpointer + or #gconstpointer. + + + + + + Outputs information about all records in a #GRelation, as well as +the indexes. It is for debugging. + Rarely used API + + + + + + + a #GRelation. + + + + + + Returns all of the tuples which have the given key in the given +field. Use g_tuples_index() to access the returned records. The +returned records should be freed with g_tuples_destroy(). + Rarely used API + + + the records (tuples) that matched. + + + + + a #GRelation. + + + + the value to compare with. + + + + the field of each record to match. + + + + + + Creates a new #GRelation with the given number of fields. Note that +currently the number of fields must be 2. + Rarely used API + + + a new #GRelation. + + + + + the number of fields. + + + + + The search path separator character. + filename="glib/docs.c" + line="910">The search path separator character. This is ':' on UNIX machines and ';' under Windows. - + The search path separator as a string. + filename="glib/docs.c" + line="917">The search path separator as a string. This is ":" on UNIX machines and ";" under Windows. - + - + version="2.64" introspectable="0"> Returns the size of @member in the struct definition without having a + filename="glib/gmacros.h" + line="1417">Returns the size of @member in the struct definition without having a declared instance of @struct_type. - + a structure type, e.g. #GOutputVector + filename="glib/gmacros.h" + line="1419">a structure type, e.g. #GOutputVector a field in the structure, e.g. `size` + filename="glib/gmacros.h" + line="1420">a field in the structure, e.g. `size` - + - + - + The #GSList struct is used for each element in the singly-linked + filename="glib/gslist.c" + line="38">The #GSList struct is used for each element in the singly-linked list. - + holds the element's data, which can be a pointer to any kind + filename="glib/gslist.c" + line="40">holds the element's data, which can be a pointer to any kind of data, or any integer value using the - [Type Conversion Macros][glib-Type-Conversion-Macros] + [Type Conversion Macros](conversion-macros.html#conversion-macros) contains the link to the next element in the list. + filename="glib/gslist.c" + line="43">contains the link to the next element in the list. Allocates space for one #GSList element. It is called by the + filename="glib/gslist.c" + line="64">Allocates space for one #GSList element. It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and g_slist_insert_sorted() functions and so is rarely used on its own. - + a pointer to the newly-allocated #GSList element. + filename="glib/gslist.c" + line="71">a pointer to the newly-allocated #GSList element. @@ -34354,8 +36503,8 @@ g_slist_insert_sorted() functions and so is rarely used on its own. Adds a new element on to the end of the list. + filename="glib/gslist.c" + line="153">Adds a new element on to the end of the list. The return value is the new start of the list, which may have changed, so make sure you store the new value. @@ -34377,11 +36526,11 @@ list = g_slist_append (list, "second"); number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); ]| - + the new start of the #GSList + filename="glib/gslist.c" + line="181">the new start of the #GSList @@ -34389,8 +36538,8 @@ number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); a #GSList + filename="glib/gslist.c" + line="155">a #GSList @@ -34400,23 +36549,23 @@ number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); nullable="1" allow-none="1"> the data for the new element + filename="glib/gslist.c" + line="156">the data for the new element Adds the second #GSList onto the end of the first #GSList. + filename="glib/gslist.c" + line="339">Adds the second #GSList onto the end of the first #GSList. Note that the elements of the second #GSList are not copied. They are used directly. - + the start of the new #GSList + filename="glib/gslist.c" + line="348">the start of the new #GSList @@ -34424,16 +36573,16 @@ They are used directly. a #GSList + filename="glib/gslist.c" + line="341">a #GSList the #GSList to add to the end of the first #GSList + filename="glib/gslist.c" + line="342">the #GSList to add to the end of the first #GSList @@ -34442,18 +36591,18 @@ They are used directly. Copies a #GSList. + filename="glib/gslist.c" + line="502">Copies a #GSList. Note that this is a "shallow" copy. If the list elements consist of pointers to data, the pointers are copied but the actual data isn't. See g_slist_copy_deep() if you need to copy the data as well. - + a copy of @list + filename="glib/gslist.c" + line="513">a copy of @list @@ -34461,8 +36610,8 @@ to copy the data as well. a #GSList + filename="glib/gslist.c" + line="504">a #GSList @@ -34474,8 +36623,8 @@ to copy the data as well. version="2.34" introspectable="0"> Makes a full (deep) copy of a #GSList. + filename="glib/gslist.c" + line="521">Makes a full (deep) copy of a #GSList. In contrast with g_slist_copy(), this function uses @func to make a copy of each list element, in addition to copying the list container itself. @@ -34495,11 +36644,11 @@ And, to entirely free the new list, you could do: |[<!-- language="C" --> g_slist_free_full (another_list, g_object_unref); ]| - + a full copy of @list, use g_slist_free_full() to free it + filename="glib/gslist.c" + line="548">a full copy of @list, use g_slist_free_full() to free it @@ -34507,16 +36656,19 @@ g_slist_free_full (another_list, g_object_unref); a #GSList + filename="glib/gslist.c" + line="523">a #GSList - + a copy function used to copy every element in the list + filename="glib/gslist.c" + line="524">a copy function used to copy every element in the list user data passed to the copy function @func, or #NULL + filename="glib/gslist.c" + line="525">user data passed to the copy function @func, or #NULL @@ -34534,8 +36686,8 @@ g_slist_free_full (another_list, g_object_unref); c:identifier="g_slist_delete_link" introspectable="0"> Removes the node link_ from the list and frees it. + filename="glib/gslist.c" + line="475">Removes the node link_ from the list and frees it. Compare this to g_slist_remove_link() which removes the node without freeing it. @@ -34544,11 +36696,11 @@ that is proportional to the length of the list (ie. O(n)). If you find yourself using g_slist_delete_link() frequently, you should consider a different data structure, such as the doubly-linked #GList. - + the new head of @list + filename="glib/gslist.c" + line="490">the new head of @list @@ -34556,16 +36708,16 @@ consider a different data structure, such as the doubly-linked a #GSList + filename="glib/gslist.c" + line="477">a #GSList node to delete + filename="glib/gslist.c" + line="478">node to delete @@ -34574,14 +36726,14 @@ consider a different data structure, such as the doubly-linked Finds the element in a #GSList which + filename="glib/gslist.c" + line="650">Finds the element in a #GSList which contains the given data. - + the found #GSList element, + filename="glib/gslist.c" + line="658">the found #GSList element, or %NULL if it is not found @@ -34590,8 +36742,8 @@ contains the given data. a #GSList + filename="glib/gslist.c" + line="652">a #GSList @@ -34601,8 +36753,8 @@ contains the given data. nullable="1" allow-none="1"> the element data to find + filename="glib/gslist.c" + line="653">the element data to find @@ -34611,18 +36763,18 @@ contains the given data. c:identifier="g_slist_find_custom" introspectable="0"> Finds an element in a #GSList, using a supplied function to + filename="glib/gslist.c" + line="676">Finds an element in a #GSList, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two #gconstpointer arguments, the #GSList element's data as the first argument and the given user data. - + the found #GSList element, or %NULL if it is not found + filename="glib/gslist.c" + line="690">the found #GSList element, or %NULL if it is not found @@ -34630,8 +36782,8 @@ given user data. a #GSList + filename="glib/gslist.c" + line="678">a #GSList @@ -34641,14 +36793,14 @@ given user data. nullable="1" allow-none="1"> user data passed to the function + filename="glib/gslist.c" + line="679">user data passed to the function - + the function to call for each element. + filename="glib/gslist.c" + line="680">the function to call for each element. It should return 0 when the desired element is found @@ -34658,28 +36810,31 @@ given user data. c:identifier="g_slist_foreach" introspectable="0"> Calls a function for each element of a #GSList. + filename="glib/gslist.c" + line="817">Calls a function for each element of a #GSList. It is safe for @func to remove the element from @list, but it must not modify any part of the list after that element. - + a #GSList + filename="glib/gslist.c" + line="819">a #GSList - + the function to call with each element's data + filename="glib/gslist.c" + line="820">the function to call with each element's data nullable="1" allow-none="1"> user data to pass to the function + filename="glib/gslist.c" + line="821">user data to pass to the function Frees all of the memory used by a #GSList. + filename="glib/gslist.c" + line="79">Frees all of the memory used by a #GSList. The freed elements are returned to the slice allocator. If list elements contain dynamically-allocated memory, @@ -34709,15 +36864,15 @@ is not left dangling: GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ g_slist_free (g_steal_pointer (&list_of_borrowed_things)); ]| - + the first link of a #GSList + filename="glib/gslist.c" + line="81">the first link of a #GSList @@ -34726,18 +36881,18 @@ g_slist_free (g_steal_pointer (&list_of_borrowed_things)); Frees one #GSList element. + filename="glib/gslist.c" + line="103">Frees one #GSList element. It is usually used after g_slist_remove_link(). - + a #GSList element + filename="glib/gslist.c" + line="105">a #GSList element @@ -34749,8 +36904,8 @@ It is usually used after g_slist_remove_link(). version="2.28" introspectable="0"> Convenience method, which frees all the memory used by a #GSList, and + filename="glib/gslist.c" + line="123">Convenience method, which frees all the memory used by a #GSList, and calls the specified destroy function on every element's data. @free_func must not modify the list (eg, by removing the freed @@ -34764,45 +36919,45 @@ from @free_func: GSList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); ]| - + the first link of a #GSList + filename="glib/gslist.c" + line="125">the first link of a #GSList the function to be called to free each element's data + filename="glib/gslist.c" + line="126">the function to be called to free each element's data Gets the position of the element containing + filename="glib/gslist.c" + line="738">Gets the position of the element containing the given data (starting from 0). - + the index of the element containing the data, + filename="glib/gslist.c" + line="746">the index of the element containing the data, or -1 if the data is not found a #GSList + filename="glib/gslist.c" + line="740">a #GSList @@ -34812,21 +36967,21 @@ the given data (starting from 0). nullable="1" allow-none="1"> the data to find + filename="glib/gslist.c" + line="741">the data to find Inserts a new element into the list at the given position. - + filename="glib/gslist.c" + line="238">Inserts a new element into the list at the given position. + the new start of the #GSList + filename="glib/gslist.c" + line="249">the new start of the #GSList @@ -34834,8 +36989,8 @@ the given data (starting from 0). a #GSList + filename="glib/gslist.c" + line="240">a #GSList @@ -34845,14 +37000,14 @@ the given data (starting from 0). nullable="1" allow-none="1"> the data for the new element + filename="glib/gslist.c" + line="241">the data for the new element the position to insert the element. + filename="glib/gslist.c" + line="242">the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. @@ -34864,13 +37019,13 @@ the given data (starting from 0). c:identifier="g_slist_insert_before" introspectable="0"> Inserts a node before @sibling containing @data. - + filename="glib/gslist.c" + line="289">Inserts a node before @sibling containing @data. + the new head of the list. + filename="glib/gslist.c" + line="297">the new head of the list. @@ -34878,16 +37033,16 @@ the given data (starting from 0). a #GSList + filename="glib/gslist.c" + line="291">a #GSList node to insert @data before + filename="glib/gslist.c" + line="292">node to insert @data before @@ -34897,8 +37052,8 @@ the given data (starting from 0). nullable="1" allow-none="1"> data to put in the newly-inserted node + filename="glib/gslist.c" + line="293">data to put in the newly-inserted node @@ -34907,14 +37062,14 @@ the given data (starting from 0). c:identifier="g_slist_insert_sorted" introspectable="0"> Inserts a new element into the list, using the given + filename="glib/gslist.c" + line="895">Inserts a new element into the list, using the given comparison function to determine its position. - + the new start of the #GSList + filename="glib/gslist.c" + line="906">the new start of the #GSList @@ -34922,8 +37077,8 @@ comparison function to determine its position. a #GSList + filename="glib/gslist.c" + line="897">a #GSList @@ -34933,14 +37088,14 @@ comparison function to determine its position. nullable="1" allow-none="1"> the data for the new element + filename="glib/gslist.c" + line="898">the data for the new element - + the function to compare elements in the list. + filename="glib/gslist.c" + line="899">the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -34952,14 +37107,14 @@ comparison function to determine its position. version="2.10" introspectable="0"> Inserts a new element into the list, using the given + filename="glib/gslist.c" + line="916">Inserts a new element into the list, using the given comparison function to determine its position. - + the new start of the #GSList + filename="glib/gslist.c" + line="928">the new start of the #GSList @@ -34967,8 +37122,8 @@ comparison function to determine its position. a #GSList + filename="glib/gslist.c" + line="918">a #GSList @@ -34978,14 +37133,17 @@ comparison function to determine its position. nullable="1" allow-none="1"> the data for the new element + filename="glib/gslist.c" + line="919">the data for the new element - + the function to compare elements in the list. + filename="glib/gslist.c" + line="920">the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -34995,23 +37153,23 @@ comparison function to determine its position. nullable="1" allow-none="1"> data to pass to comparison function + filename="glib/gslist.c" + line="923">data to pass to comparison function Gets the last element in a #GSList. + filename="glib/gslist.c" + line="767">Gets the last element in a #GSList. This function iterates over the whole list. - + the last element in the #GSList, + filename="glib/gslist.c" + line="775">the last element in the #GSList, or %NULL if the #GSList has no elements @@ -35020,8 +37178,8 @@ This function iterates over the whole list. a #GSList + filename="glib/gslist.c" + line="769">a #GSList @@ -35030,24 +37188,24 @@ This function iterates over the whole list. Gets the number of elements in a #GSList. + filename="glib/gslist.c" + line="790">Gets the number of elements in a #GSList. This function iterates over the whole list to count its elements. To check whether the list is non-empty, it is faster to check @list against %NULL. - + the number of elements in the #GSList + filename="glib/gslist.c" + line="800">the number of elements in the #GSList a #GSList + filename="glib/gslist.c" + line="792">a #GSList @@ -35056,13 +37214,13 @@ check @list against %NULL. Gets the element at the given position in a #GSList. - + filename="glib/gslist.c" + line="610">Gets the element at the given position in a #GSList. + the element, or %NULL if the position is off + filename="glib/gslist.c" + line="617">the element, or %NULL if the position is off the end of the #GSList @@ -35071,16 +37229,16 @@ check @list against %NULL. a #GSList + filename="glib/gslist.c" + line="612">a #GSList the position of the element, counting from 0 + filename="glib/gslist.c" + line="613">the position of the element, counting from 0 @@ -35089,61 +37247,67 @@ check @list against %NULL. c:identifier="g_slist_nth_data" introspectable="0"> Gets the data of the element at the given position. - + filename="glib/gslist.c" + line="630">Gets the data of the element at the given position. + the element's data, or %NULL if the position + filename="glib/gslist.c" + line="637">the element's data, or %NULL if the position is off the end of the #GSList a #GSList + filename="glib/gslist.c" + line="632">a #GSList the position of the element + filename="glib/gslist.c" + line="633">the position of the element + + + + + + Gets the position of the given element + filename="glib/gslist.c" + line="709">Gets the position of the given element in the #GSList (starting from 0). - + the position of the element in the #GSList, + filename="glib/gslist.c" + line="717">the position of the element in the #GSList, or -1 if the element is not found a #GSList + filename="glib/gslist.c" + line="711">a #GSList an element in the #GSList + filename="glib/gslist.c" + line="712">an element in the #GSList @@ -35154,8 +37318,8 @@ in the #GSList (starting from 0). c:identifier="g_slist_prepend" introspectable="0"> Adds a new element on to the start of the list. + filename="glib/gslist.c" + line="206">Adds a new element on to the start of the list. The return value is the new start of the list, which may have changed, so make sure you store the new value. @@ -35166,11 +37330,11 @@ GSList *list = NULL; list = g_slist_prepend (list, "last"); list = g_slist_prepend (list, "first"); ]| - + the new start of the #GSList + filename="glib/gslist.c" + line="223">the new start of the #GSList @@ -35178,8 +37342,8 @@ list = g_slist_prepend (list, "first"); a #GSList + filename="glib/gslist.c" + line="208">a #GSList @@ -35189,61 +37353,34 @@ list = g_slist_prepend (list, "first"); nullable="1" allow-none="1"> the data for the new element + filename="glib/gslist.c" + line="209">the data for the new element - - Removes an element from a #GSList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GSList is unchanged. - - - the new start of the #GSList - - - + + + + - - a #GSList - - - - - - the data of the element to remove - + + - + Removes all list nodes with data equal to @data. -Returns the new head of the list. Contrast with -g_slist_remove() which removes only the first node -matching the given data. - + filename="glib/gslist.c" + line="390">Removes an element from a #GSList. +If two elements contain the same data, only the first is removed. +If none of the elements contain the data, the #GSList is unchanged. + new head of @list + filename="glib/gslist.c" + line="399">the new start of the #GSList @@ -35251,8 +37388,8 @@ matching the given data. a #GSList + filename="glib/gslist.c" + line="392">a #GSList @@ -35262,8 +37399,46 @@ matching the given data. nullable="1" allow-none="1"> data to remove + filename="glib/gslist.c" + line="393">the data of the element to remove + + + + + + Removes all list nodes with data equal to @data. +Returns the new head of the list. Contrast with +g_slist_remove() which removes only the first node +matching the given data. + + + new head of @list + + + + + + + a #GSList + + + + + + data to remove @@ -35272,8 +37447,8 @@ matching the given data. c:identifier="g_slist_remove_link" introspectable="0"> Removes an element from a #GSList, without + filename="glib/gslist.c" + line="450">Removes an element from a #GSList, without freeing the element. The removed element's next link is set to %NULL, so that it becomes a self-contained list with one element. @@ -35283,11 +37458,11 @@ requires time that is proportional to the length of the list (ie. O(n)). If you find yourself using g_slist_remove_link() frequently, you should consider a different data structure, such as the doubly-linked #GList. - + the new start of the #GSList, without the element + filename="glib/gslist.c" + line="466">the new start of the #GSList, without the element @@ -35295,16 +37470,16 @@ such as the doubly-linked #GList. a #GSList + filename="glib/gslist.c" + line="452">a #GSList an element in the #GSList + filename="glib/gslist.c" + line="453">an element in the #GSList @@ -35315,13 +37490,13 @@ such as the doubly-linked #GList. c:identifier="g_slist_reverse" introspectable="0"> Reverses a #GSList. - + filename="glib/gslist.c" + line="584">Reverses a #GSList. + the start of the reversed #GSList + filename="glib/gslist.c" + line="590">the start of the reversed #GSList @@ -35329,8 +37504,8 @@ such as the doubly-linked #GList. a #GSList + filename="glib/gslist.c" + line="586">a #GSList @@ -35339,14 +37514,14 @@ such as the doubly-linked #GList. Sorts a #GSList using the given comparison function. The algorithm + filename="glib/gslist.c" + line="1002">Sorts a #GSList using the given comparison function. The algorithm used is a stable sort. - + the start of the sorted #GSList + filename="glib/gslist.c" + line="1014">the start of the sorted #GSList @@ -35354,16 +37529,18 @@ used is a stable sort. a #GSList + filename="glib/gslist.c" + line="1004">a #GSList - + the comparison function used to sort the #GSList. + filename="glib/gslist.c" + line="1005">the comparison function used to sort the #GSList. This function is passed the data from 2 elements of the #GSList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if @@ -35376,13 +37553,13 @@ used is a stable sort. c:identifier="g_slist_sort_with_data" introspectable="0"> Like g_slist_sort(), but the sort function accepts a user data argument. - + filename="glib/gslist.c" + line="1023">Like g_slist_sort(), but the sort function accepts a user data argument. + new head of the list + filename="glib/gslist.c" + line="1031">new head of the list @@ -35390,16 +37567,19 @@ used is a stable sort. a #GSList + filename="glib/gslist.c" + line="1025">a #GSList - + comparison function + filename="glib/gslist.c" + line="1026">comparison function nullable="1" allow-none="1"> data to pass to comparison function + filename="glib/gslist.c" + line="1027">data to pass to comparison function @@ -35419,10 +37599,10 @@ used is a stable sort. c:type="G_SOURCE_CONTINUE" version="2.32"> Use this macro as the return value of a #GSourceFunc to leave -the #GSource in the main loop. - + filename="glib/gmain.h" + line="474">Use this macro as the return value of a [callback@GLib.SourceFunc] to leave +the [struct@GLib.Source] in the main loop. + version="2.58" introspectable="0"> Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8 -onwards with `-Wextra` or `-Wcast-function-type` enabled about the function -types being incompatible. + filename="glib/gmain.h" + line="215">Cast a function pointer to a [callback@GLib.SourceFunc], suppressing +warnings from GCC 8 onwards with `-Wextra` or `-Wcast-function-type` enabled +about the function types being incompatible. For example, the correct type of callback for a source created by -g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments -than #GSourceFunc. Casting the function with `(GSourceFunc)` to call -g_source_set_callback() will trigger a warning, even though it will be cast -back to the correct type before it is called by the source. - +[func@GLib.child_watch_source_new] is #GChildWatchFunc, which accepts more +arguments than [callback@GLib.SourceFunc]. Casting the function with +`(GSourceFunc)` to call [method@GLib.Source.set_callback] will trigger a +warning, even though it will be cast back to the correct type before it is +called by the source. + a function pointer. + filename="glib/gmain.h" + line="217">a function pointer. @@ -35454,25 +37635,78 @@ back to the correct type before it is called by the source. c:type="G_SOURCE_REMOVE" version="2.32"> Use this macro as the return value of a #GSourceFunc to remove -the #GSource from the main loop. - + filename="glib/gmain.h" + line="464">Use this macro as the return value of a [callback@GLib.SourceFunc] to remove +the [struct@GLib.Source] from the main loop. + The square root of two. - + filename="glib/docs.c" + line="841">The square root of two. + + + The G_STATIC_ASSERT() macro lets the programmer check +a condition at compile time, the condition needs to +be compile time computable. The macro can be used in +any place where a typedef is valid. + +A typedef is generally allowed in exactly the same places that +a variable declaration is allowed. For this reason, you should +not use G_STATIC_ASSERT() in the middle of blocks of code. + +The macro should only be used once per source code line. + + + + a constant expression + + + + + The G_STATIC_ASSERT_EXPR() macro lets the programmer check +a condition at compile time. The condition needs to be +compile time computable. + +Unlike G_STATIC_ASSERT(), this macro evaluates to an expression +and, as such, can be used in the middle of other expressions. +Its value should be ignored. This can be accomplished by placing +it as the first argument of a comma expression. + +|[<!-- language="C" --> +#define ADD_ONE_TO_INT(x) \ + (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) +]| + + + + a constant expression + + + Accepts a macro or a string and converts it into a string after + filename="glib/docs.c" + line="1110">Accepts a macro or a string and converts it into a string after preprocessor argument expansion. For example, the following code: |[<!-- language="C" --> @@ -35485,19 +37719,19 @@ is transformed by the preprocessor into (code equivalent to): |[<!-- language="C" --> const gchar *greeting = "27 today!"; ]| - + a macro or a string + filename="glib/docs.c" + line="1112">a macro or a string - + @@ -35507,24 +37741,24 @@ const gchar *greeting = "27 today!"; c:identifier="G_STRUCT_MEMBER" introspectable="0"> Returns a member of a structure at a given offset, using the given type. - + filename="glib/docs.c" + line="1013">Returns a member of a structure at a given offset, using the given type. + the type of the struct field + filename="glib/docs.c" + line="1015">the type of the struct field a pointer to a struct + filename="glib/docs.c" + line="1016">a pointer to a struct the offset of the field from the start of the struct, + filename="glib/docs.c" + line="1017">the offset of the field from the start of the struct, in bytes @@ -35533,19 +37767,19 @@ const gchar *greeting = "27 today!"; c:identifier="G_STRUCT_MEMBER_P" introspectable="0"> Returns an untyped pointer to a given offset of a struct. - + filename="glib/docs.c" + line="1025">Returns an untyped pointer to a given offset of a struct. + a pointer to a struct + filename="glib/docs.c" + line="1027">a pointer to a struct the offset from the start of the struct, in bytes + filename="glib/docs.c" + line="1028">the offset from the start of the struct, in bytes @@ -35553,23 +37787,23 @@ const gchar *greeting = "27 today!"; c:identifier="G_STRUCT_OFFSET" introspectable="0"> Returns the offset, in bytes, of a member of a struct. + filename="glib/docs.c" + line="1035">Returns the offset, in bytes, of a member of a struct. Consider using standard C `offsetof()`, available since at least C89 and C++98, in new code (but note that `offsetof()` returns a `size_t` rather than a `long`). - + a structure type, e.g. #GtkWidget + filename="glib/docs.c" + line="1037">a structure type, e.g. #GtkWidget a field in the structure, e.g. @window + filename="glib/docs.c" + line="1038">a field in the structure, e.g. @window @@ -35577,41 +37811,41 @@ rather than a `long`). value="_-|> <." c:type="G_STR_DELIMITERS"> The standard delimiters, used in g_strdelimit(). - + filename="glib/gstrfuncs.c" + line="256">The standard delimiters, used in [func@GLib.strdelimit]. + - + - + - + - + - + - + The data structure representing a lexical scanner. + filename="glib/gscanner.c" + line="172">`GScanner` provides a general-purpose lexical scanner. You should set @input_name after creating the scanner, since it is used by the default message handler when displaying @@ -35625,89 +37859,89 @@ can place them here. If you want to use your own message handler you can set the @msg_handler field. The type of the message handler function is declared by #GScannerMsgFunc. - + unused + filename="glib/gscanner.c" + line="174">unused unused + filename="glib/gscanner.c" + line="175">unused g_scanner_error() increments this field + filename="glib/gscanner.c" + line="176">g_scanner_error() increments this field name of input stream, featured by the default message handler + filename="glib/gscanner.c" + line="177">name of input stream, featured by the default message handler quarked data + filename="glib/gscanner.c" + line="178">quarked data link into the scanner configuration + filename="glib/gscanner.c" + line="179">link into the scanner configuration token parsed by the last g_scanner_get_next_token() + filename="glib/gscanner.c" + line="180">token parsed by the last g_scanner_get_next_token() value of the last token from g_scanner_get_next_token() + filename="glib/gscanner.c" + line="181">value of the last token from g_scanner_get_next_token() line number of the last token from g_scanner_get_next_token() + filename="glib/gscanner.c" + line="182">line number of the last token from g_scanner_get_next_token() char number of the last token from g_scanner_get_next_token() + filename="glib/gscanner.c" + line="183">char number of the last token from g_scanner_get_next_token() token parsed by the last g_scanner_peek_next_token() + filename="glib/gscanner.c" + line="184">token parsed by the last g_scanner_peek_next_token() value of the last token from g_scanner_peek_next_token() + filename="glib/gscanner.c" + line="185">value of the last token from g_scanner_peek_next_token() line number of the last token from g_scanner_peek_next_token() + filename="glib/gscanner.c" + line="186">line number of the last token from g_scanner_peek_next_token() char number of the last token from g_scanner_peek_next_token() + filename="glib/gscanner.c" + line="187">char number of the last token from g_scanner_peek_next_token() @@ -35733,71 +37967,71 @@ is declared by #GScannerMsgFunc. handler function for _warn and _error + filename="glib/gscanner.c" + line="188">handler function for _warn and _error Returns the current line in the input stream (counting + filename="glib/gscanner.c" + line="1038">Returns the current line in the input stream (counting from 1). This is the line of the last token parsed via g_scanner_get_next_token(). - + the current line + filename="glib/gscanner.c" + line="1046">the current line a #GScanner + filename="glib/gscanner.c" + line="1040">a #GScanner Returns the current position in the current line (counting + filename="glib/gscanner.c" + line="1056">Returns the current position in the current line (counting from 0). This is the position of the last token parsed via g_scanner_get_next_token(). - + the current position on the line + filename="glib/gscanner.c" + line="1064">the current position on the line a #GScanner + filename="glib/gscanner.c" + line="1058">a #GScanner Gets the current token type. This is simply the @token + filename="glib/gscanner.c" + line="996">Gets the current token type. This is simply the @token field in the #GScanner structure. - + the current token type + filename="glib/gscanner.c" + line="1003">the current token type a #GScanner + filename="glib/gscanner.c" + line="998">a #GScanner @@ -35806,201 +38040,201 @@ field in the #GScanner structure. c:identifier="g_scanner_cur_value" introspectable="0"> Gets the current token value. This is simply the @value + filename="glib/gscanner.c" + line="1013">Gets the current token value. This is simply the @value field in the #GScanner structure. - + the current token value + filename="glib/gscanner.c" + line="1020">the current token value a #GScanner + filename="glib/gscanner.c" + line="1015">a #GScanner Frees all memory used by the #GScanner. - + filename="glib/gscanner.c" + line="503">Frees all memory used by the #GScanner. + a #GScanner + filename="glib/gscanner.c" + line="505">a #GScanner Returns %TRUE if the scanner has reached the end of + filename="glib/gscanner.c" + line="1074">Returns %TRUE if the scanner has reached the end of the file or text buffer. - + %TRUE if the scanner has reached the end of + filename="glib/gscanner.c" + line="1081">%TRUE if the scanner has reached the end of the file or text buffer a #GScanner + filename="glib/gscanner.c" + line="1076">a #GScanner Outputs an error message, via the #GScanner message handler. - + filename="glib/gscanner.c" + line="540">Outputs an error message, via the #GScanner message handler. + a #GScanner + filename="glib/gscanner.c" + line="542">a #GScanner the message format. See the printf() documentation + filename="glib/gscanner.c" + line="543">the message format. See the printf() documentation the parameters to insert into the format string + filename="glib/gscanner.c" + line="544">the parameters to insert into the format string Parses the next token just like g_scanner_peek_next_token() + filename="glib/gscanner.c" + line="960">Parses the next token just like g_scanner_peek_next_token() and also removes it from the input stream. The token data is placed in the @token, @value, @line, and @position fields of the #GScanner structure. - + the type of the token + filename="glib/gscanner.c" + line="969">the type of the token a #GScanner + filename="glib/gscanner.c" + line="962">a #GScanner Prepares to scan a file. - + filename="glib/gscanner.c" + line="1092">Prepares to scan a file. + a #GScanner + filename="glib/gscanner.c" + line="1094">a #GScanner a file descriptor + filename="glib/gscanner.c" + line="1095">a file descriptor Prepares to scan a text buffer. - + filename="glib/gscanner.c" + line="1123">Prepares to scan a text buffer. + a #GScanner + filename="glib/gscanner.c" + line="1125">a #GScanner the text buffer to scan + filename="glib/gscanner.c" + line="1126">the text buffer to scan the length of the text buffer + filename="glib/gscanner.c" + line="1127">the length of the text buffer Looks up a symbol in the current scope and return its value. + filename="glib/gscanner.c" + line="771">Looks up a symbol in the current scope and return its value. If the symbol is not bound in the current scope, %NULL is returned. - + the value of @symbol in the current scope, or %NULL + filename="glib/gscanner.c" + line="780">the value of @symbol in the current scope, or %NULL if @symbol is not bound in the current scope a #GScanner + filename="glib/gscanner.c" + line="773">a #GScanner the symbol to look up + filename="glib/gscanner.c" + line="774">the symbol to look up Parses the next token, without removing it from the input stream. + filename="glib/gscanner.c" + line="923">Parses the next token, without removing it from the input stream. The token data is placed in the @next_token, @next_value, @next_line, and @next_position fields of the #GScanner structure. @@ -36011,18 +38245,18 @@ results when changing scope or the scanner configuration after peeking the next token. Getting the next token after switching the scope or configuration will return whatever was peeked before, regardless of any symbols that may have been added or removed in the new scope. - + the type of the token + filename="glib/gscanner.c" + line="939">the type of the token a #GScanner + filename="glib/gscanner.c" + line="925">a #GScanner @@ -36030,29 +38264,29 @@ any symbols that may have been added or removed in the new scope. Adds a symbol to the given scope. - + filename="glib/gscanner.c" + line="670">Adds a symbol to the given scope. + a #GScanner + filename="glib/gscanner.c" + line="672">a #GScanner the scope id + filename="glib/gscanner.c" + line="673">the scope id the symbol to add + filename="glib/gscanner.c" + line="674">the symbol to add nullable="1" allow-none="1"> the value of the symbol + filename="glib/gscanner.c" + line="675">the value of the symbol + c:identifier="g_scanner_scope_foreach_symbol"> Calls the given function for each of the symbol/value pairs + filename="glib/gscanner.c" + line="894">Calls the given function for each of the symbol/value pairs in the given scope of the #GScanner. The function is passed the symbol and value of each pair, and the given @user_data parameter. - + a #GScanner + filename="glib/gscanner.c" + line="896">a #GScanner the scope id + filename="glib/gscanner.c" + line="897">the scope id - + the function to call for each symbol/value pair + filename="glib/gscanner.c" + line="898">the function to call for each symbol/value pair nullable="1" allow-none="1"> user data to pass to the function + filename="glib/gscanner.c" + line="899">user data to pass to the function @@ -36112,34 +38348,34 @@ parameter. Looks up a symbol in a scope and return its value. If the + filename="glib/gscanner.c" + line="806">Looks up a symbol in a scope and return its value. If the symbol is not bound in the scope, %NULL is returned. - + the value of @symbol in the given scope, or %NULL + filename="glib/gscanner.c" + line="815">the value of @symbol in the given scope, or %NULL if @symbol is not bound in the given scope. a #GScanner + filename="glib/gscanner.c" + line="808">a #GScanner the scope id + filename="glib/gscanner.c" + line="809">the scope id the symbol to look up + filename="glib/gscanner.c" + line="810">the symbol to look up @@ -36147,55 +38383,55 @@ symbol is not bound in the scope, %NULL is returned. Removes a symbol from a scope. - + filename="glib/gscanner.c" + line="725">Removes a symbol from a scope. + a #GScanner + filename="glib/gscanner.c" + line="727">a #GScanner the scope id + filename="glib/gscanner.c" + line="728">the scope id the symbol to remove + filename="glib/gscanner.c" + line="729">the symbol to remove Sets the current scope. - + filename="glib/gscanner.c" + line="839">Sets the current scope. + the old scope id + filename="glib/gscanner.c" + line="846">the old scope id a #GScanner + filename="glib/gscanner.c" + line="841">a #GScanner the new scope id + filename="glib/gscanner.c" + line="842">the new scope id @@ -36203,55 +38439,55 @@ symbol is not bound in the scope, %NULL is returned. Rewinds the filedescriptor to the current buffer position + filename="glib/gscanner.c" + line="1199">Rewinds the filedescriptor to the current buffer position and blows the file read ahead buffer. This is useful for third party uses of the scanners filedescriptor, which hooks onto the current scanning position. - + a #GScanner + filename="glib/gscanner.c" + line="1201">a #GScanner Outputs a message through the scanner's msg_handler, + filename="glib/gscanner.c" + line="1290">Outputs a message through the scanner's msg_handler, resulting from an unexpected token in the input stream. Note that you should not call g_scanner_peek_next_token() followed by g_scanner_unexp_token() without an intermediate call to g_scanner_get_next_token(), as g_scanner_unexp_token() evaluates the scanner's current token (not the peeked token) to construct part of the message. - + a #GScanner + filename="glib/gscanner.c" + line="1292">a #GScanner the expected token + filename="glib/gscanner.c" + line="1293">the expected token a string describing how the scanner's user + filename="glib/gscanner.c" + line="1294">a string describing how the scanner's user refers to identifiers (%NULL defaults to "identifier"). This is used if @expected_token is %G_TOKEN_IDENTIFIER or %G_TOKEN_IDENTIFIER_NULL. @@ -36259,8 +38495,8 @@ to construct part of the message. a string describing how the scanner's user refers + filename="glib/gscanner.c" + line="1298">a string describing how the scanner's user refers to symbols (%NULL defaults to "symbol"). This is used if @expected_token is %G_TOKEN_SYMBOL or any token value greater than %G_TOKEN_LAST. @@ -36268,22 +38504,22 @@ to construct part of the message. the name of the symbol, if the scanner's current + filename="glib/gscanner.c" + line="1302">the name of the symbol, if the scanner's current token is a symbol. a message string to output at the end of the + filename="glib/gscanner.c" + line="1304">a message string to output at the end of the warning/error, or %NULL. if %TRUE it is output as an error. If %FALSE it is + filename="glib/gscanner.c" + line="1306">if %TRUE it is output as an error. If %FALSE it is output as a warning. @@ -36291,54 +38527,54 @@ to construct part of the message. Outputs a warning message, via the #GScanner message handler. - + filename="glib/gscanner.c" + line="573">Outputs a warning message, via the #GScanner message handler. + a #GScanner + filename="glib/gscanner.c" + line="575">a #GScanner the message format. See the printf() documentation + filename="glib/gscanner.c" + line="576">the message format. See the printf() documentation the parameters to insert into the format string + filename="glib/gscanner.c" + line="577">the parameters to insert into the format string Creates a new #GScanner. + filename="glib/gscanner.c" + line="389">Creates a new #GScanner. The @config_templ structure specifies the initial settings of the scanner, which are copied into the #GScanner @config field. If you pass %NULL then the default settings are used. - + the new #GScanner + filename="glib/gscanner.c" + line="400">the new #GScanner the initial scanner settings + filename="glib/gscanner.c" + line="391">the initial scanner settings @@ -36346,30 +38582,30 @@ are used. Specifies the #GScanner parser configuration. Most settings can + filename="glib/gscanner.c" + line="206">Specifies the #GScanner parser configuration. Most settings can be changed during the parsing phase and will affect the lexical parsing of the next unpeeked token. - + specifies which characters should be skipped + filename="glib/gscanner.c" + line="208">specifies which characters should be skipped by the scanner (the default is the whitespace characters: space, tab, carriage-return and line-feed). specifies the characters which can start + filename="glib/gscanner.c" + line="211">specifies the characters which can start identifiers (the default is %G_CSET_a_2_z, "_", and %G_CSET_A_2_Z). specifies the characters which can be used + filename="glib/gscanner.c" + line="213">specifies the characters which can be used in identifiers, after the first character (the default is %G_CSET_a_2_z, "_0123456789", %G_CSET_A_2_Z, %G_CSET_LATINS, %G_CSET_LATINC). @@ -36377,8 +38613,8 @@ parsing of the next unpeeked token. specifies the characters at the start and + filename="glib/gscanner.c" + line="217">specifies the characters at the start and end of single-line comments. The default is "#\n" which means that single-line comments start with a '#' and continue until a '\n' (end of line). @@ -36386,155 +38622,155 @@ parsing of the next unpeeked token. specifies if symbols are case sensitive (the + filename="glib/gscanner.c" + line="221">specifies if symbols are case sensitive (the default is %FALSE). specifies if multi-line comments are skipped + filename="glib/gscanner.c" + line="223">specifies if multi-line comments are skipped and not returned as tokens (the default is %TRUE). specifies if single-line comments are skipped + filename="glib/gscanner.c" + line="225">specifies if single-line comments are skipped and not returned as tokens (the default is %TRUE). specifies if multi-line comments are recognized + filename="glib/gscanner.c" + line="227">specifies if multi-line comments are recognized (the default is %TRUE). specifies if identifiers are recognized (the + filename="glib/gscanner.c" + line="229">specifies if identifiers are recognized (the default is %TRUE). specifies if single-character + filename="glib/gscanner.c" + line="231">specifies if single-character identifiers are recognized (the default is %FALSE). specifies if %NULL is reported as + filename="glib/gscanner.c" + line="233">specifies if %NULL is reported as %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). specifies if symbols are recognized (the default + filename="glib/gscanner.c" + line="235">specifies if symbols are recognized (the default is %TRUE). specifies if binary numbers are recognized (the + filename="glib/gscanner.c" + line="237">specifies if binary numbers are recognized (the default is %FALSE). specifies if octal numbers are recognized (the + filename="glib/gscanner.c" + line="239">specifies if octal numbers are recognized (the default is %TRUE). specifies if floating point numbers are recognized + filename="glib/gscanner.c" + line="241">specifies if floating point numbers are recognized (the default is %TRUE). specifies if hexadecimal numbers are recognized (the + filename="glib/gscanner.c" + line="243">specifies if hexadecimal numbers are recognized (the default is %TRUE). specifies if '$' is recognized as a prefix for + filename="glib/gscanner.c" + line="245">specifies if '$' is recognized as a prefix for hexadecimal numbers (the default is %FALSE). specifies if strings can be enclosed in single + filename="glib/gscanner.c" + line="247">specifies if strings can be enclosed in single quotes (the default is %TRUE). specifies if strings can be enclosed in double + filename="glib/gscanner.c" + line="249">specifies if strings can be enclosed in double quotes (the default is %TRUE). specifies if binary, octal and hexadecimal numbers + filename="glib/gscanner.c" + line="251">specifies if binary, octal and hexadecimal numbers are reported as %G_TOKEN_INT (the default is %TRUE). specifies if all numbers are reported as %G_TOKEN_FLOAT + filename="glib/gscanner.c" + line="253">specifies if all numbers are reported as %G_TOKEN_FLOAT (the default is %FALSE). specifies if identifiers are reported as strings + filename="glib/gscanner.c" + line="255">specifies if identifiers are reported as strings (the default is %FALSE). specifies if characters are reported by setting + filename="glib/gscanner.c" + line="257">specifies if characters are reported by setting `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). specifies if symbols are reported by setting + filename="glib/gscanner.c" + line="259">specifies if symbols are reported by setting `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). specifies if a symbol is searched for in the + filename="glib/gscanner.c" + line="261">specifies if a symbol is searched for in the default scope in addition to the current scope (the default is %FALSE). use value.v_int64 rather than v_int + filename="glib/gscanner.c" + line="263">use value.v_int64 rather than v_int @@ -36543,29 +38779,29 @@ parsing of the next unpeeked token. Specifies the type of the message handler function. - + filename="glib/gscanner.c" + line="57">Specifies the type of the message handler function. + a #GScanner + filename="glib/gscanner.c" + line="59">a #GScanner the message + filename="glib/gscanner.c" + line="60">the message %TRUE if the message signals an error, + filename="glib/gscanner.c" + line="61">%TRUE if the message signals an error, %FALSE if it signals a warning. @@ -36573,48 +38809,48 @@ parsing of the next unpeeked token. An enumeration specifying the base position for a + filename="glib/giochannel.c" + line="1076">An enumeration specifying the base position for a g_io_channel_seek_position() operation. - + the current position in the file. + filename="glib/giochannel.c" + line="1078">the current position in the file. the start of the file. + filename="glib/giochannel.c" + line="1079">the start of the file. the end of the file. + filename="glib/giochannel.c" + line="1080">the end of the file. The #GSequence struct is an opaque data type representing a -[sequence][glib-Sequences] data type. - + filename="glib/gsequence.c" + line="52">The #GSequence struct is an opaque data type representing a +[sequence](data-structures.html#scalable-lists) data type. + Adds a new item to the end of @seq. - + filename="glib/gsequence.c" + line="403">Adds a new item to the end of @seq. + an iterator pointing to the new item + filename="glib/gsequence.c" + line="410">an iterator pointing to the new item a #GSequence + filename="glib/gsequence.c" + line="405">a #GSequence nullable="1" allow-none="1"> the data for the new item + filename="glib/gsequence.c" + line="406">the data for the new item - + Calls @func for each item in the sequence passing @user_data + filename="glib/gsequence.c" + line="297">Calls @func for each item in the sequence passing @user_data to the function. @func must not modify the sequence itself. - + a #GSequence + filename="glib/gsequence.c" + line="299">a #GSequence - + the function to call for each item in @seq + filename="glib/gsequence.c" + line="300">the function to call for each item in @seq nullable="1" allow-none="1"> user data passed to @func + filename="glib/gsequence.c" + line="301">user data passed to @func Frees the memory allocated for @seq. If @seq has a data destroy + filename="glib/gsequence.c" + line="232">Frees the memory allocated for @seq. If @seq has a data destroy function associated with it, that function is called on all items in @seq. - + a #GSequence + filename="glib/gsequence.c" + line="234">a #GSequence @@ -36687,20 +38923,20 @@ in @seq. c:identifier="g_sequence_get_begin_iter" version="2.14"> Returns the begin iterator for @seq. - + filename="glib/gsequence.c" + line="1265">Returns the begin iterator for @seq. + the begin iterator for @seq. + filename="glib/gsequence.c" + line="1271">the begin iterator for @seq. a #GSequence + filename="glib/gsequence.c" + line="1267">a #GSequence @@ -36709,20 +38945,20 @@ in @seq. c:identifier="g_sequence_get_end_iter" version="2.14"> Returns the end iterator for @seg - + filename="glib/gsequence.c" + line="1247">Returns the end iterator for @seg + the end iterator for @seq + filename="glib/gsequence.c" + line="1253">the end iterator for @seq a #GSequence + filename="glib/gsequence.c" + line="1249">a #GSequence @@ -36731,27 +38967,27 @@ in @seq. c:identifier="g_sequence_get_iter_at_pos" version="2.14"> Returns the iterator at position @pos. If @pos is negative or larger + filename="glib/gsequence.c" + line="1295">Returns the iterator at position @pos. If @pos is negative or larger than the number of items in @seq, the end iterator is returned. - + The #GSequenceIter at position @pos + filename="glib/gsequence.c" + line="1303">The #GSequenceIter at position @pos a #GSequence + filename="glib/gsequence.c" + line="1297">a #GSequence a position in @seq, or -1 for the end + filename="glib/gsequence.c" + line="1298">a position in @seq, or -1 for the end @@ -36760,33 +38996,32 @@ than the number of items in @seq, the end iterator is returned. c:identifier="g_sequence_get_length" version="2.14"> Returns the positive length (>= 0) of @seq. Note that this method is + filename="glib/gsequence.c" + line="1209">Returns the positive length (>= 0) of @seq. Note that this method is O(h) where `h' is the height of the tree. It is thus more efficient to use g_sequence_is_empty() when comparing the length to zero. - + the length of @seq + filename="glib/gsequence.c" + line="1217">the length of @seq a #GSequence + filename="glib/gsequence.c" + line="1211">a #GSequence + version="2.14"> Inserts @data into @seq using @cmp_func to determine the new + filename="glib/gsequence.c" + line="658">Inserts @data into @seq using @cmp_func to determine the new position. The sequence must already be sorted according to @cmp_func; otherwise the new position of @data is undefined. @@ -36798,18 +39033,18 @@ if the second item comes before the first. Note that when adding a large amount of data to a #GSequence, it is more efficient to do unsorted insertions and then call g_sequence_sort() or g_sequence_sort_iter(). - + a #GSequenceIter pointing to the new item. + filename="glib/gsequence.c" + line="678">a #GSequenceIter pointing to the new item. a #GSequence + filename="glib/gsequence.c" + line="660">a #GSequence nullable="1" allow-none="1"> the data to insert + filename="glib/gsequence.c" + line="661">the data to insert - + the function used to compare items in the sequence + filename="glib/gsequence.c" + line="662">the function used to compare items in the sequence nullable="1" allow-none="1"> user data passed to @cmp_func. + filename="glib/gsequence.c" + line="663">user data passed to @cmp_func. + version="2.14"> Like g_sequence_insert_sorted(), but uses + filename="glib/gsequence.c" + line="948">Like g_sequence_insert_sorted(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @@ -36856,18 +39093,18 @@ positive value if the second iterator comes before the first. Note that when adding a large amount of data to a #GSequence, it is more efficient to do unsorted insertions and then call g_sequence_sort() or g_sequence_sort_iter(). - + a #GSequenceIter pointing to the new item + filename="glib/gsequence.c" + line="968">a #GSequenceIter pointing to the new item a #GSequence + filename="glib/gsequence.c" + line="950">a #GSequence nullable="1" allow-none="1"> data for the new item + filename="glib/gsequence.c" + line="951">data for the new item - + the function used to compare iterators in the sequence + filename="glib/gsequence.c" + line="952">the function used to compare iterators in the sequence @@ -36891,8 +39131,8 @@ g_sequence_sort() or g_sequence_sort_iter(). nullable="1" allow-none="1"> user data passed to @iter_cmp + filename="glib/gsequence.c" + line="953">user data passed to @iter_cmp @@ -36901,35 +39141,32 @@ g_sequence_sort() or g_sequence_sort_iter(). c:identifier="g_sequence_is_empty" version="2.48"> Returns %TRUE if the sequence contains zero items. + filename="glib/gsequence.c" + line="1227">Returns %TRUE if the sequence contains zero items. This function is functionally identical to checking the result of g_sequence_get_length() being equal to zero. However this function is implemented in O(1) running time. - + %TRUE if the sequence is empty, otherwise %FALSE. + filename="glib/gsequence.c" + line="1237">%TRUE if the sequence is empty, otherwise %FALSE. a #GSequence + filename="glib/gsequence.c" + line="1229">a #GSequence - + Returns an iterator pointing to the position of the first item found + filename="glib/gsequence.c" + line="785">Returns an iterator pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. If more than one item is equal, it is not guaranteed that it is the first which is returned. In that case, you can use g_sequence_iter_next() and @@ -36942,11 +39179,11 @@ the second item comes before the first. This function will fail if the data contained in the sequence is unsorted. - + an #GSequenceIter pointing to the position of the + filename="glib/gsequence.c" + line="806">an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data, or %NULL if no such item exists @@ -36954,8 +39191,8 @@ unsorted. a #GSequence + filename="glib/gsequence.c" + line="787">a #GSequence nullable="1" allow-none="1"> data to look up + filename="glib/gsequence.c" + line="788">data to look up - + the function used to compare items in the sequence + filename="glib/gsequence.c" + line="789">the function used to compare items in the sequence nullable="1" allow-none="1"> user data passed to @cmp_func + filename="glib/gsequence.c" + line="790">user data passed to @cmp_func + version="2.28"> Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc + filename="glib/gsequence.c" + line="1073">Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into @seq. @@ -37000,11 +39239,11 @@ value if the second iterator comes before the first. This function will fail if the data contained in the sequence is unsorted. - + an #GSequenceIter pointing to the position of + filename="glib/gsequence.c" + line="1091">an #GSequenceIter pointing to the position of the first item found equal to @data according to @iter_cmp and @cmp_data, or %NULL if no such item exists @@ -37012,8 +39251,8 @@ unsorted. a #GSequence + filename="glib/gsequence.c" + line="1075">a #GSequence nullable="1" allow-none="1"> data to look up + filename="glib/gsequence.c" + line="1076">data to look up - + the function used to compare iterators in the sequence + filename="glib/gsequence.c" + line="1077">the function used to compare iterators in the sequence @@ -37037,28 +39279,28 @@ unsorted. nullable="1" allow-none="1"> user data passed to @iter_cmp + filename="glib/gsequence.c" + line="1078">user data passed to @iter_cmp Adds a new item to the front of @seq - + filename="glib/gsequence.c" + line="430">Adds a new item to the front of @seq + an iterator pointing to the new item + filename="glib/gsequence.c" + line="437">an iterator pointing to the new item a #GSequence + filename="glib/gsequence.c" + line="432">a #GSequence nullable="1" allow-none="1"> the data for the new item + filename="glib/gsequence.c" + line="433">the data for the new item - + Returns an iterator pointing to the position where @data would + filename="glib/gsequence.c" + line="741">Returns an iterator pointing to the position where @data would be inserted according to @cmp_func and @cmp_data. @cmp_func is called with two items of the @seq, and @cmp_data. @@ -37091,19 +39330,19 @@ consider using g_sequence_lookup(). This function will fail if the data contained in the sequence is unsorted. - + an #GSequenceIter pointing to the position where @data + filename="glib/gsequence.c" + line="762">an #GSequenceIter pointing to the position where @data would have been inserted according to @cmp_func and @cmp_data a #GSequence + filename="glib/gsequence.c" + line="743">a #GSequence nullable="1" allow-none="1"> data for the new item + filename="glib/gsequence.c" + line="744">data for the new item - + the function used to compare items in the sequence + filename="glib/gsequence.c" + line="745">the function used to compare items in the sequence nullable="1" allow-none="1"> user data passed to @cmp_func + filename="glib/gsequence.c" + line="746">user data passed to @cmp_func + version="2.14"> Like g_sequence_search(), but uses a #GSequenceIterCompareFunc + filename="glib/gsequence.c" + line="1015">Like g_sequence_search(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @iter_cmp is called with two iterators pointing into @seq. @@ -37151,11 +39392,11 @@ consider using g_sequence_lookup_iter(). This function will fail if the data contained in the sequence is unsorted. - + a #GSequenceIter pointing to the position in @seq + filename="glib/gsequence.c" + line="1036">a #GSequenceIter pointing to the position in @seq where @data would have been inserted according to @iter_cmp and @cmp_data @@ -37163,8 +39404,8 @@ unsorted. a #GSequence + filename="glib/gsequence.c" + line="1017">a #GSequence nullable="1" allow-none="1"> data for the new item + filename="glib/gsequence.c" + line="1018">data for the new item - + the function used to compare iterators in the sequence + filename="glib/gsequence.c" + line="1019">the function used to compare iterators in the sequence @@ -37188,39 +39432,39 @@ unsorted. nullable="1" allow-none="1"> user data passed to @iter_cmp + filename="glib/gsequence.c" + line="1020">user data passed to @iter_cmp - + Sorts @seq using @cmp_func. + filename="glib/gsequence.c" + line="627">Sorts @seq using @cmp_func. @cmp_func is passed two items of @seq and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first. - + a #GSequence + filename="glib/gsequence.c" + line="629">a #GSequence - + the function used to sort the sequence + filename="glib/gsequence.c" + line="630">the function used to sort the sequence nullable="1" allow-none="1"> user data passed to @cmp_func + filename="glib/gsequence.c" + line="631">user data passed to @cmp_func + version="2.14"> Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead + filename="glib/gsequence.c" + line="830">Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function @cmp_func is called with two iterators pointing into @seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. - + a #GSequence + filename="glib/gsequence.c" + line="832">a #GSequence - + the function used to compare iterators in the sequence + filename="glib/gsequence.c" + line="833">the function used to compare iterators in the sequence @@ -37270,42 +39516,44 @@ iterator comes before the first. nullable="1" allow-none="1"> user data passed to @cmp_func + filename="glib/gsequence.c" + line="834">user data passed to @cmp_func + version="2.14"> Calls @func for each item in the range (@begin, @end) passing + filename="glib/gsequence.c" + line="254">Calls @func for each item in the range (@begin, @end) passing @user_data to the function. @func must not modify the sequence itself. - + a #GSequenceIter + filename="glib/gsequence.c" + line="256">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="257">a #GSequenceIter - + a #GFunc + filename="glib/gsequence.c" + line="258">a #GFunc nullable="1" allow-none="1"> user data passed to @func + filename="glib/gsequence.c" + line="259">user data passed to @func Returns the data that @iter points to. - + filename="glib/gsequence.c" + line="1153">Returns the data that @iter points to. + the data that @iter points to + filename="glib/gsequence.c" + line="1159">the data that @iter points to a #GSequenceIter + filename="glib/gsequence.c" + line="1155">a #GSequenceIter @@ -37343,20 +39591,20 @@ itself. c:identifier="g_sequence_insert_before" version="2.14"> Inserts a new item just before the item pointed to by @iter. - + filename="glib/gsequence.c" + line="459">Inserts a new item just before the item pointed to by @iter. + an iterator pointing to the new item + filename="glib/gsequence.c" + line="466">an iterator pointing to the new item a #GSequenceIter + filename="glib/gsequence.c" + line="461">a #GSequenceIter nullable="1" allow-none="1"> the data for the new item + filename="glib/gsequence.c" + line="462">the data for the new item Moves the item pointed to by @src to the position indicated by @dest. + filename="glib/gsequence.c" + line="1318">Moves the item pointed to by @src to the position indicated by @dest. After calling this function @dest will point to the position immediately after @src. It is allowed for @src and @dest to point into different sequences. - + a #GSequenceIter pointing to the item to move + filename="glib/gsequence.c" + line="1320">a #GSequenceIter pointing to the item to move a #GSequenceIter pointing to the position to which + filename="glib/gsequence.c" + line="1321">a #GSequenceIter pointing to the position to which the item is moved @@ -37401,8 +39649,8 @@ sequences. c:identifier="g_sequence_move_range" version="2.14"> Inserts the (@begin, @end) range at the destination pointed to by @dest. + filename="glib/gsequence.c" + line="543">Inserts the (@begin, @end) range at the destination pointed to by @dest. The @begin and @end iters must point into the same sequence. It is allowed for @dest to point to a different sequence than the one pointed into by @begin and @end. @@ -37410,27 +39658,27 @@ into by @begin and @end. If @dest is %NULL, the range indicated by @begin and @end is removed from the sequence. If @dest points to a place within the (@begin, @end) range, the range does not move. - + a #GSequenceIter + filename="glib/gsequence.c" + line="545">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="546">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="547">a #GSequenceIter @@ -37440,15 +39688,15 @@ the (@begin, @end) range, the range does not move. version="2.14" introspectable="0"> Creates a new GSequence. The @data_destroy function, if non-%NULL will + filename="glib/gsequence.c" + line="205">Creates a new GSequence. The @data_destroy function, if non-%NULL will be called on all items when the sequence is destroyed and on items that are removed from the sequence. - + a new #GSequence + filename="glib/gsequence.c" + line="213">a new #GSequence @@ -37458,8 +39706,8 @@ are removed from the sequence. allow-none="1" scope="async"> a #GDestroyNotify function, or %NULL + filename="glib/gsequence.c" + line="207">a #GDestroyNotify function, or %NULL @@ -37468,53 +39716,53 @@ are removed from the sequence. c:identifier="g_sequence_range_get_midpoint" version="2.14"> Finds an iterator somewhere in the range (@begin, @end). This + filename="glib/gsequence.c" + line="323">Finds an iterator somewhere in the range (@begin, @end). This iterator will be close to the middle of the range, but is not guaranteed to be exactly in the middle. The @begin and @end iterators must both point to the same sequence and @begin must come before or be equal to @end in the sequence. - + a #GSequenceIter pointing somewhere in the + filename="glib/gsequence.c" + line="335">a #GSequenceIter pointing somewhere in the (@begin, @end) range a #GSequenceIter + filename="glib/gsequence.c" + line="325">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="326">a #GSequenceIter Removes the item pointed to by @iter. It is an error to pass the + filename="glib/gsequence.c" + line="489">Removes the item pointed to by @iter. It is an error to pass the end iterator to this function. If the sequence has a data destroy function associated with it, this function is called on the data for the removed item. - + a #GSequenceIter + filename="glib/gsequence.c" + line="491">a #GSequenceIter @@ -37523,45 +39771,45 @@ function is called on the data for the removed item. c:identifier="g_sequence_remove_range" version="2.14"> Removes all items in the (@begin, @end) range. + filename="glib/gsequence.c" + line="517">Removes all items in the (@begin, @end) range. If the sequence has a data destroy function associated with it, this function is called on the data for the removed items. - + a #GSequenceIter + filename="glib/gsequence.c" + line="519">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="520">a #GSequenceIter Changes the data for the item pointed to by @iter to be @data. If + filename="glib/gsequence.c" + line="1172">Changes the data for the item pointed to by @iter to be @data. If the sequence has a data destroy function associated with it, that function is called on the existing data that @iter pointed to. - + a #GSequenceIter + filename="glib/gsequence.c" + line="1174">a #GSequenceIter nullable="1" allow-none="1"> new data for the item + filename="glib/gsequence.c" + line="1175">new data for the item + version="2.14"> Moves the data pointed to by @iter to a new position as indicated by + filename="glib/gsequence.c" + line="701">Moves the data pointed to by @iter to a new position as indicated by @cmp_func. This function should be called for items in a sequence already sorted according to @cmp_func whenever some aspect of an item changes so that @cmp_func @@ -37591,21 +39838,24 @@ may return different values for that item. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first. - + A #GSequenceIter + filename="glib/gsequence.c" + line="703">A #GSequenceIter - + the function used to compare items in the sequence + filename="glib/gsequence.c" + line="704">the function used to compare items in the sequence nullable="1" allow-none="1"> user data passed to @cmp_func. + filename="glib/gsequence.c" + line="705">user data passed to @cmp_func. + version="2.14"> Like g_sequence_sort_changed(), but uses + filename="glib/gsequence.c" + line="884">Like g_sequence_sort_changed(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @@ -37634,21 +39883,24 @@ the compare function. return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first. - + a #GSequenceIter + filename="glib/gsequence.c" + line="886">a #GSequenceIter - + the function used to compare iterators in the sequence + filename="glib/gsequence.c" + line="887">the function used to compare iterators in the sequence @@ -37657,32 +39909,32 @@ iterator comes before the first. nullable="1" allow-none="1"> user data passed to @cmp_func + filename="glib/gsequence.c" + line="888">user data passed to @cmp_func Swaps the items pointed to by @a and @b. It is allowed for @a and @b + filename="glib/gsequence.c" + line="1477">Swaps the items pointed to by @a and @b. It is allowed for @a and @b to point into difference sequences. - + a #GSequenceIter + filename="glib/gsequence.c" + line="1479">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="1480">a #GSequenceIter @@ -37693,38 +39945,38 @@ to point into difference sequences. disguised="1" opaque="1"> The #GSequenceIter struct is an opaque data type representing an + filename="glib/gsequence.c" + line="29">The #GSequenceIter struct is an opaque data type representing an iterator pointing into a #GSequence. - + Returns a negative number if @a comes before @b, 0 if they are equal, + filename="glib/gsequence.c" + line="360">Returns a negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b. The @a and @b iterators must point into the same sequence. - + a negative number if @a comes before @b, 0 if they are + filename="glib/gsequence.c" + line="370">a negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b a #GSequenceIter + filename="glib/gsequence.c" + line="362">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="363">a #GSequenceIter @@ -37733,20 +39985,20 @@ The @a and @b iterators must point into the same sequence. c:identifier="g_sequence_iter_get_position" version="2.14"> Returns the position of @iter - + filename="glib/gsequence.c" + line="1384">Returns the position of @iter + the position of @iter + filename="glib/gsequence.c" + line="1390">the position of @iter a #GSequenceIter + filename="glib/gsequence.c" + line="1386">a #GSequenceIter @@ -37755,20 +40007,20 @@ The @a and @b iterators must point into the same sequence. c:identifier="g_sequence_iter_get_sequence" version="2.14"> Returns the #GSequence that @iter points into. - + filename="glib/gsequence.c" + line="1128">Returns the #GSequence that @iter points into. + the #GSequence that @iter points into + filename="glib/gsequence.c" + line="1134">the #GSequence that @iter points into a #GSequenceIter + filename="glib/gsequence.c" + line="1130">a #GSequenceIter @@ -37777,20 +40029,20 @@ The @a and @b iterators must point into the same sequence. c:identifier="g_sequence_iter_is_begin" version="2.14"> Returns whether @iter is the begin iterator - + filename="glib/gsequence.c" + line="1366">Returns whether @iter is the begin iterator + whether @iter is the begin iterator + filename="glib/gsequence.c" + line="1372">whether @iter is the begin iterator a #GSequenceIter + filename="glib/gsequence.c" + line="1368">a #GSequenceIter @@ -37799,49 +40051,49 @@ The @a and @b iterators must point into the same sequence. c:identifier="g_sequence_iter_is_end" version="2.14"> Returns whether @iter is the end iterator - + filename="glib/gsequence.c" + line="1348">Returns whether @iter is the end iterator + Whether @iter is the end iterator + filename="glib/gsequence.c" + line="1354">Whether @iter is the end iterator a #GSequenceIter + filename="glib/gsequence.c" + line="1350">a #GSequenceIter Returns the #GSequenceIter which is @delta positions away from @iter. + filename="glib/gsequence.c" + line="1441">Returns the #GSequenceIter which is @delta positions away from @iter. If @iter is closer than -@delta positions to the beginning of the sequence, the begin iterator is returned. If @iter is closer than @delta positions to the end of the sequence, the end iterator is returned. - + a #GSequenceIter which is @delta positions away from @iter + filename="glib/gsequence.c" + line="1452">a #GSequenceIter which is @delta positions away from @iter a #GSequenceIter + filename="glib/gsequence.c" + line="1443">a #GSequenceIter A positive or negative number indicating how many positions away + filename="glib/gsequence.c" + line="1444">A positive or negative number indicating how many positions away from @iter the returned #GSequenceIter will be @@ -37849,43 +40101,43 @@ to the end of the sequence, the end iterator is returned. Returns an iterator pointing to the next position after @iter. + filename="glib/gsequence.c" + line="1402">Returns an iterator pointing to the next position after @iter. If @iter is the end iterator, the end iterator is returned. - + a #GSequenceIter pointing to the next position after @iter + filename="glib/gsequence.c" + line="1409">a #GSequenceIter pointing to the next position after @iter a #GSequenceIter + filename="glib/gsequence.c" + line="1404">a #GSequenceIter Returns an iterator pointing to the previous position before @iter. + filename="glib/gsequence.c" + line="1421">Returns an iterator pointing to the previous position before @iter. If @iter is the begin iterator, the begin iterator is returned. - + a #GSequenceIter pointing to the previous position + filename="glib/gsequence.c" + line="1428">a #GSequenceIter pointing to the previous position before @iter a #GSequenceIter + filename="glib/gsequence.c" + line="1423">a #GSequenceIter @@ -37893,29 +40145,29 @@ If @iter is the begin iterator, the begin iterator is returned. A #GSequenceIterCompareFunc is a function used to compare iterators. + filename="glib/gsequence.c" + line="36">A #GSequenceIterCompareFunc is a function used to compare iterators. It must return zero if the iterators compare equal, a negative value if @a comes before @b, and a positive value if @b comes before @a. - + zero if the iterators are equal, a negative value if @a + filename="glib/gsequence.c" + line="46">zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before @a. a #GSequenceIter + filename="glib/gsequence.c" + line="38">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="39">a #GSequenceIter nullable="1" allow-none="1"> user data + filename="glib/gsequence.c" + line="40">user data @@ -37933,31 +40185,31 @@ if @a comes before @b, and a positive value if @b comes before @a. c:type="GShellError" glib:error-domain="g-shell-error-quark"> Error codes returned by shell functions. - + filename="glib/gshell.c" + line="46">Error codes returned by shell functions. + Mismatched or otherwise mangled quoting. + filename="glib/gshell.c" + line="48">Mismatched or otherwise mangled quoting. String to be parsed was empty. + filename="glib/gshell.c" + line="49">String to be parsed was empty. Some other error. + filename="glib/gshell.c" + line="50">Some other error. - + @@ -37989,10 +40241,10 @@ if @a comes before @b, and a positive value if @b comes before @a. glib:get-type="g_source_get_type" c:symbol-prefix="source"> The `GSource` struct is an opaque data type representing an event source. - + @@ -38036,34 +40288,34 @@ representing an event source. Creates a new #GSource structure. The size is specified to -allow creating structures derived from #GSource that contain + filename="glib/gmain.c" + line="907">Creates a new [struct@GLib.Source] structure. The size is specified to +allow creating structures derived from [struct@GLib.Source] that contain additional data. The size passed in must be at least `sizeof (GSource)`. The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be +and must be added to one with [method@GLib.Source.attach] before it will be executed. - + the newly-created #GSource. + filename="glib/gmain.c" + line="922">the newly-created #GSource. structure containing functions that implement + filename="glib/gmain.c" + line="909">structure containing functions that implement the sources behavior. size of the #GSource structure to create. + filename="glib/gmain.c" + line="911">size of the [struct@GLib.Source] structure to create. @@ -38072,10 +40324,10 @@ executed. c:identifier="g_source_add_child_source" version="2.28"> Adds @child_source to @source as a "polled" source; when @source is -added to a #GMainContext, @child_source will be automatically added -with the same priority, when @child_source is triggered, it will + filename="glib/gmain.c" + line="1514">Adds @child_source to @source as a "polled" source; when @source is +added to a [struct@GLib.MainContext], @child_source will be automatically +added with the same priority, when @child_source is triggered, it will cause @source to dispatch (in addition to calling its own callback), and when @source is destroyed, it will destroy @child_source as well. (@source will also still be dispatched if @@ -38088,57 +40340,58 @@ callback that does nothing (except return %TRUE if appropriate). @source will hold a reference on @child_source while @child_source is attached to it. -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - +This API is only intended to be used by implementations of +[struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that +you did not create. + a #GSource + filename="glib/gmain.c" + line="1516">a #GSource a second #GSource that @source should "poll" + filename="glib/gmain.c" + line="1517">a second #GSource that @source should "poll" Adds a file descriptor to the set of file descriptors polled for -this source. This is usually combined with g_source_new() to add an + filename="glib/gmain.c" + line="1432">Adds a file descriptor to the set of file descriptors polled for +this source. This is usually combined with [ctor@GLib.Source.new] to add an event source. The event source's check function will typically test the @revents field in the #GPollFD struct and return %TRUE if events need to be processed. -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. +This API is only intended to be used by implementations of [struct@GLib.Source]. +Do not call this API on a [struct@GLib.Source] that you did not create. Using this API forces the linear scanning of event sources on each main loop iteration. Newly-written event sources should try to use -g_source_add_unix_fd() instead of this API. - +`g_source_add_unix_fd` instead of this API. + a #GSource + filename="glib/gmain.c" + line="1434">a #GSource a #GPollFD structure holding information about a file + filename="glib/gmain.c" + line="1435">a #GPollFD structure holding information about a file descriptor to watch. @@ -38148,12 +40401,12 @@ g_source_add_unix_fd() instead of this API. c:identifier="g_source_add_unix_fd" version="2.36"> Monitors @fd for the IO events in @events. + filename="glib/gmain.c" + line="2652">Monitors @fd for the IO events in @events. The tag returned by this function can be used to remove or modify the -monitoring of the fd using g_source_remove_unix_fd() or -g_source_modify_unix_fd(). +monitoring of the fd using [method@GLib.Source.remove_unix_fd] or +[method@GLib.Source.modify_unix_fd]. It is not necessary to remove the fd before destroying the source; it will be cleaned up automatically. @@ -38162,55 +40415,55 @@ This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. As the name suggests, this function is not available on Windows. - + an opaque tag + filename="glib/gmain.c" + line="2672">an opaque tag a #GSource + filename="glib/gmain.c" + line="2654">a #GSource the fd to monitor + filename="glib/gmain.c" + line="2655">the fd to monitor an event mask + filename="glib/gmain.c" + line="2656">an event mask Adds a #GSource to a @context so that it will be executed within -that context. Remove it by calling g_source_destroy(). + filename="glib/gmain.c" + line="1237">Adds a [struct@GLib.Source] to a @context so that it will be executed within +that context. Remove it by calling [method@GLib.Source.destroy]. This function is safe to call from any thread, regardless of which thread the @context is running in. - + the ID (greater than 0) for the source within the + filename="glib/gmain.c" + line="1249">the ID (greater than 0) for the source within the #GMainContext. a #GSource + filename="glib/gmain.c" + line="1239">a #GSource nullable="1" allow-none="1"> a #GMainContext (if %NULL, the global-default + filename="glib/gmain.c" + line="1240">a #GMainContext (if %NULL, the global-default main context will be used) @@ -38227,71 +40480,72 @@ the @context is running in. Removes a source from its #GMainContext, if any, and mark it as + filename="glib/gmain.c" + line="1336">Removes a source from its [struct@GLib.MainContext], if any, and mark it as destroyed. The source cannot be subsequently added to another context. It is safe to call this on sources which have already been removed from their context. -This does not unref the #GSource: if you still hold a reference, use -g_source_unref() to drop it. +This does not unref the [struct@GLib.Source]: if you still hold a reference, +use [method@GLib.Source.unref] to drop it. This function is safe to call from any thread, regardless of which thread -the #GMainContext is running in. +the [struct@GLib.MainContext] is running in. -If the source is currently attached to a #GMainContext, destroying it -will effectively unset the callback similar to calling g_source_set_callback(). -This can mean, that the data's #GDestroyNotify gets called right away. - +If the source is currently attached to a [struct@GLib.MainContext], +destroying it will effectively unset the callback similar to calling +[method@GLib.Source.set_callback]. This can mean, that the data's +#GDestroyNotify gets called right away. + a #GSource + filename="glib/gmain.c" + line="1338">a #GSource Checks whether a source is allowed to be called recursively. -see g_source_set_can_recurse(). - + filename="glib/gmain.c" + line="2025">Checks whether a source is allowed to be called recursively. +see [method@GLib.Source.set_can_recurse]. + whether recursion is allowed. + filename="glib/gmain.c" + line="2032">whether recursion is allowed. a #GSource + filename="glib/gmain.c" + line="2027">a #GSource Gets the #GMainContext with which the source is associated. + filename="glib/gmain.c" + line="1405">Gets the [struct@GLib.MainContext] with which the source is associated. You can call this on a source that has been destroyed, provided -that the #GMainContext it was attached to still exists (in which -case it will return that #GMainContext). In particular, you can +that the [struct@GLib.MainContext] it was attached to still exists (in which +case it will return that [struct@GLib.MainContext]). In particular, you can always call this function on the source returned from -g_main_current_source(). But calling this function on a source -whose #GMainContext has been destroyed is an error. - +[func@GLib.main_current_source]. But calling this function on a source +whose [struct@GLib.MainContext] has been destroyed is an error. + the #GMainContext with which the + filename="glib/gmain.c" + line="1418">the #GMainContext with which the source is associated, or %NULL if the context has not yet been added to a source. @@ -38299,8 +40553,8 @@ whose #GMainContext has been destroyed is an error. a #GSource + filename="glib/gmain.c" + line="1407">a #GSource @@ -38310,144 +40564,145 @@ whose #GMainContext has been destroyed is an error. deprecated="1" deprecated-version="2.28"> This function ignores @source and is otherwise the same as -g_get_current_time(). - use g_source_get_time() instead - + filename="glib/gmain.c" + line="4837">This function ignores @source and is otherwise the same as +[func@GLib.get_current_time]. + use [method@GLib.Source.get_time] instead + a #GSource + filename="glib/gmain.c" + line="4839">a #GSource #GTimeVal structure in which to store current time. + filename="glib/gmain.c" + line="4840">#GTimeVal structure in which to store current time. Returns the numeric ID for a particular source. The ID of a source + filename="glib/gmain.c" + line="1372">Returns the numeric ID for a particular source. The ID of a source is a positive integer which is unique within a particular main loop -context. The reverse -mapping from ID to source is done by g_main_context_find_source_by_id(). +context. The reverse mapping from ID to source is done by +[method@GLib.MainContext.find_source_by_id]. You can only call this function while the source is associated to a -#GMainContext instance; calling this function before g_source_attach() -or after g_source_destroy() yields undefined behavior. The ID returned -is unique within the #GMainContext instance passed to g_source_attach(). - +[struct@GLib.MainContext] instance; calling this function before +[method@GLib.Source.attach] or after [method@GLib.Source.destroy] yields +undefined behavior. The ID returned is unique within the +[struct@GLib.MainContext] instance passed to [method@GLib.Source.attach]. + the ID (greater than 0) for the source + filename="glib/gmain.c" + line="1387">the ID (greater than 0) for the source a #GSource + filename="glib/gmain.c" + line="1374">a #GSource Gets a name for the source, used in debugging and profiling. The -name may be #NULL if it has never been set with g_source_set_name(). - + filename="glib/gmain.c" + line="2130">Gets a name for the source, used in debugging and profiling. The +name may be #NULL if it has never been set with [method@GLib.Source.set_name]. + the name of the source + filename="glib/gmain.c" + line="2137">the name of the source a #GSource + filename="glib/gmain.c" + line="2132">a #GSource Gets the priority of a source. - + filename="glib/gmain.c" + line="1888">Gets the priority of a source. + the priority of the source + filename="glib/gmain.c" + line="1894">the priority of the source a #GSource + filename="glib/gmain.c" + line="1890">a #GSource Gets the "ready time" of @source, as set by -g_source_set_ready_time(). + filename="glib/gmain.c" + line="1971">Gets the "ready time" of @source, as set by +[method@GLib.Source.set_ready_time]. -Any time before the current monotonic time (including 0) is an -indication that the source will fire immediately. - +Any time before or equal to the current monotonic time (including 0) +is an indication that the source will fire immediately. + the monotonic ready time, -1 for "never" + filename="glib/gmain.c" + line="1981">the monotonic ready time, -1 for "never" a #GSource + filename="glib/gmain.c" + line="1973">a #GSource Gets the time to be used when checking this source. The advantage of -calling this function over calling g_get_monotonic_time() directly is + filename="glib/gmain.c" + line="4856">Gets the time to be used when checking this source. The advantage of +calling this function over calling [func@GLib.get_monotonic_time] directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system monotonic time. The time here is the system monotonic time, if available, or some -other reasonable alternative otherwise. See g_get_monotonic_time(). - +other reasonable alternative otherwise. See [func@GLib.get_monotonic_time]. + the monotonic time in microseconds + filename="glib/gmain.c" + line="4868">the monotonic time in microseconds a #GSource + filename="glib/gmain.c" + line="4858">a #GSource @@ -38456,8 +40711,8 @@ other reasonable alternative otherwise. See g_get_monotonic_time(). c:identifier="g_source_is_destroyed" version="2.12"> Returns whether @source has been destroyed. + filename="glib/gmain.c" + line="3172">Returns whether @source has been destroyed. This is important when you operate upon your objects from within idle handlers, but may have freed the object @@ -38531,22 +40786,22 @@ idle_callback (gpointer data) ]| Calls to this function from a thread other than the one acquired by the -#GMainContext the #GSource is attached to are typically redundant, as the -source could be destroyed immediately after this function returns. However, -once a source is destroyed it cannot be un-destroyed, so this function can be -used for opportunistic checks from any thread. - +[struct@GLib.MainContext] the #GSource is attached to are typically +redundant, as the source could be destroyed immediately after this function +returns. However, once a source is destroyed it cannot be un-destroyed, so +this function can be used for opportunistic checks from any thread. + %TRUE if the source has been destroyed + filename="glib/gmain.c" + line="3255">%TRUE if the source has been destroyed a #GSource + filename="glib/gmain.c" + line="3174">a #GSource @@ -38555,39 +40810,39 @@ used for opportunistic checks from any thread. c:identifier="g_source_modify_unix_fd" version="2.36"> Updates the event mask to watch for the fd identified by @tag. + filename="glib/gmain.c" + line="2710">Updates the event mask to watch for the fd identified by @tag. -@tag is the tag returned from g_source_add_unix_fd(). +@tag is the tag returned from [method@GLib.Source.add_unix_fd]. If you want to remove a fd, don't set its event mask to zero. -Instead, call g_source_remove_unix_fd(). +Instead, call [method@GLib.Source.remove_unix_fd]. This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. As the name suggests, this function is not available on Windows. - + a #GSource + filename="glib/gmain.c" + line="2712">a #GSource the tag from g_source_add_unix_fd() + filename="glib/gmain.c" + line="2713">the tag from [method@GLib.Source.add_unix_fd] the new event mask to watch + filename="glib/gmain.c" + line="2714">the new event mask to watch @@ -38596,8 +40851,8 @@ As the name suggests, this function is not available on Windows. c:identifier="g_source_query_unix_fd" version="2.36"> Queries the events reported for the fd corresponding to @tag on + filename="glib/gmain.c" + line="2799">Queries the events reported for the fd corresponding to @tag on @source during the last poll. The return value of this function is only defined when the function @@ -38607,44 +40862,44 @@ This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. As the name suggests, this function is not available on Windows. - + the conditions reported on the fd + filename="glib/gmain.c" + line="2815">the conditions reported on the fd a #GSource + filename="glib/gmain.c" + line="2801">a #GSource the tag from g_source_add_unix_fd() + filename="glib/gmain.c" + line="2802">the tag from [method@GLib.Source.add_unix_fd] Increases the reference count on a source by one. - + filename="glib/gmain.c" + line="2190">Increases the reference count on a source by one. + @source + filename="glib/gmain.c" + line="2196">@source a #GSource + filename="glib/gmain.c" + line="2192">a #GSource @@ -38653,54 +40908,54 @@ As the name suggests, this function is not available on Windows. c:identifier="g_source_remove_child_source" version="2.28"> Detaches @child_source from @source and destroys it. + filename="glib/gmain.c" + line="1590">Detaches @child_source from @source and destroys it. This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. - + a #GSource + filename="glib/gmain.c" + line="1592">a #GSource a #GSource previously passed to - g_source_add_child_source(). + filename="glib/gmain.c" + line="1593">a #GSource previously passed to + [method@GLib.Source.add_child_source]. Removes a file descriptor from the set of file descriptors polled for + filename="glib/gmain.c" + line="1477">Removes a file descriptor from the set of file descriptors polled for this source. -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - +This API is only intended to be used by implementations of [struct@GLib.Source]. +Do not call this API on a [struct@GLib.Source] that you did not create. + a #GSource + filename="glib/gmain.c" + line="1479">a #GSource a #GPollFD structure previously passed to g_source_add_poll(). + filename="glib/gmain.c" + line="1480">a #GPollFD structure previously passed to [method@GLib.Source.add_poll]. @@ -38709,8 +40964,8 @@ Do not call this API on a #GSource that you did not create. c:identifier="g_source_remove_unix_fd" version="2.36"> Reverses the effect of a previous call to g_source_add_unix_fd(). + filename="glib/gmain.c" + line="2751">Reverses the effect of a previous call to [method@GLib.Source.add_unix_fd]. You only need to call this if you want to remove an fd from being watched while keeping the same source around. In the normal case you @@ -38720,57 +40975,58 @@ This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. As the name suggests, this function is not available on Windows. - + a #GSource + filename="glib/gmain.c" + line="2753">a #GSource the tag from g_source_add_unix_fd() + filename="glib/gmain.c" + line="2754">the tag from [method@GLib.Source.add_unix_fd] Sets the callback function for a source. The callback for a source is + filename="glib/gmain.c" + line="1724">Sets the callback function for a source. The callback for a source is called from the source's dispatch function. The exact type of @func depends on the type of source; ie. you should not count on @func being called with @data as its first -parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about +parameter. Cast @func with [func@GLib.SOURCE_FUNC] to avoid warnings about incompatible function types. -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle memory management of @data. Typically, you won't use this function. Instead use functions specific -to the type of source you are using, such as g_idle_add() or g_timeout_add(). +to the type of source you are using, such as [func@GLib.idle_add] or +[func@GLib.timeout_add]. It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns. -Note that g_source_destroy() for a currently attached source has the effect +Note that [method@GLib.Source.destroy] for a currently attached source has the effect of also unsetting the callback. - + the source + filename="glib/gmain.c" + line="1726">the source closure="1" destroy="2"> a callback function + filename="glib/gmain.c" + line="1727">a callback function nullable="1" allow-none="1"> the data to pass to callback function + filename="glib/gmain.c" + line="1728">the data to pass to callback function allow-none="1" scope="async"> a function to call when @data is no longer in use, or %NULL. + filename="glib/gmain.c" + line="1729">a function to call when @data is no longer in use, or %NULL. @@ -38807,10 +41063,10 @@ of also unsetting the callback. Sets the callback function storing the data as a refcounted callback + filename="glib/gmain.c" + line="1667">Sets the callback function storing the data as a refcounted callback "object". This is used internally. Note that calling -g_source_set_callback_indirect() assumes +[method@GLib.Source.set_callback_indirect] assumes an initial reference count on @callback_data, and thus @callback_funcs->unref will eventually be called once more than @callback_funcs->ref. @@ -38818,15 +41074,15 @@ than @callback_funcs->ref. It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns. - + the source + filename="glib/gmain.c" + line="1669">the source nullable="1" allow-none="1"> pointer to callback data "object" + filename="glib/gmain.c" + line="1670">pointer to callback data "object" functions for reference counting @callback_data + filename="glib/gmain.c" + line="1671">functions for reference counting @callback_data and getting the callback and data @@ -38849,26 +41105,26 @@ the source is dispatched after this call returns. Sets whether a source can be called recursively. If @can_recurse is + filename="glib/gmain.c" + line="1992">Sets whether a source can be called recursively. If @can_recurse is %TRUE, then while the source is being dispatched then this source will be processed normally. Otherwise, all processing of this source is blocked until the dispatch function returns. - + a #GSource + filename="glib/gmain.c" + line="1994">a #GSource whether recursion is allowed for this source + filename="glib/gmain.c" + line="1995">whether recursion is allowed for this source @@ -38878,13 +41134,14 @@ source is blocked until the dispatch function returns. version="2.64" introspectable="0"> Set @dispose as dispose function on @source. @dispose will be called once + filename="glib/gmain.c" + line="953">Set @dispose as dispose function on @source. @dispose will be called once the reference count of @source reaches 0 but before any of the state of the source is freed, especially before the finalize function is called. -This means that at this point @source is still a valid #GSource and it is -allow for the reference count to increase again until @dispose returns. +This means that at this point @source is still a valid [struct@GLib.Source] +and it is allow for the reference count to increase again until @dispose +returns. The dispose function can be used to clear any "weak" references to the @source in other data structures in a thread-safe way where it is possible @@ -38895,21 +41152,21 @@ The finalize function can not be used for this purpose as at that point @source is already partially freed and not valid anymore. This should only ever be called from #GSource implementations. - + A #GSource to set the dispose function on + filename="glib/gmain.c" + line="955">A #GSource to set the dispose function on #GSourceDisposeFunc to set on the source + filename="glib/gmain.c" + line="956">#GSourceDisposeFunc to set on the source @@ -38918,32 +41175,32 @@ This should only ever be called from #GSource implementations. c:identifier="g_source_set_funcs" version="2.12"> Sets the source functions (can be used to override + filename="glib/gmain.c" + line="1777">Sets the source functions (can be used to override default implementations) of an unattached source. - + a #GSource + filename="glib/gmain.c" + line="1779">a #GSource the new #GSourceFuncs + filename="glib/gmain.c" + line="1780">the new #GSourceFuncs Sets a name for the source, used in debugging and profiling. + filename="glib/gmain.c" + line="2079">Sets a name for the source, used in debugging and profiling. The name defaults to #NULL. The source name should describe in a human-readable way @@ -38956,34 +41213,34 @@ one could change the name in the "check" function of a #GSourceFuncs to include details like the event type in the source name. Use caution if changing the name while another thread may be -accessing it with g_source_get_name(); that function does not copy +accessing it with [method@GLib.Source.get_name]; that function does not copy the value, and changing the value will free it while the other thread may be attempting to use it. -Also see g_source_set_static_name(). - +Also see [method@GLib.Source.set_static_name]. + a #GSource + filename="glib/gmain.c" + line="2081">a #GSource debug name for the source + filename="glib/gmain.c" + line="2082">debug name for the source Sets the priority of a source. While the main loop is being run, a + filename="glib/gmain.c" + line="1855">Sets the priority of a source. While the main loop is being run, a source will be dispatched if it is ready to be dispatched and no sources at a higher (numerically smaller) priority are ready to be dispatched. @@ -38991,21 +41248,21 @@ dispatched. A child source always has the same priority as its parent. It is not permitted to change the priority of a source once it has been added as a child of another source. - + a #GSource + filename="glib/gmain.c" + line="1857">a #GSource the new priority. + filename="glib/gmain.c" + line="1858">the new priority. @@ -39014,8 +41271,8 @@ as a child of another source. c:identifier="g_source_set_ready_time" version="2.36"> Sets a #GSource to be dispatched when the given monotonic time is + filename="glib/gmain.c" + line="1905">Sets a #GSource to be dispatched when the given monotonic time is reached (or passed). If the monotonic time is in the past (as it always will be if @ready_time is 0) then the source will be dispatched immediately. @@ -39033,25 +41290,25 @@ for both sources is reached during the same main context iteration, then the order of dispatch is undefined. It is a no-op to call this function on a #GSource which has already been -destroyed with g_source_destroy(). +destroyed with [method@GLib.Source.destroy]. This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. - + a #GSource + filename="glib/gmain.c" + line="1907">a #GSource the monotonic time at which the source will be ready, + filename="glib/gmain.c" + line="1908">the monotonic time at which the source will be ready, 0 for "immediately", -1 for "never" @@ -39061,82 +41318,83 @@ Do not call this API on a #GSource that you did not create. c:identifier="g_source_set_static_name" version="2.70"> A variant of g_source_set_name() that does not + filename="glib/gmain.c" + line="2112">A variant of [method@GLib.Source.set_name] that does not duplicate the @name, and can only be used with string literals. - + a #GSource + filename="glib/gmain.c" + line="2114">a #GSource debug name for the source + filename="glib/gmain.c" + line="2115">debug name for the source Decreases the reference count of a source by one. If the + filename="glib/gmain.c" + line="2361">Decreases the reference count of a source by one. If the resulting reference count is zero the source and associated memory will be destroyed. - + a #GSource + filename="glib/gmain.c" + line="2363">a #GSource Removes the source with the given ID from the default main context. You must -use g_source_destroy() for sources added to a non-default main context. + filename="glib/gmain.c" + line="2521">Removes the source with the given ID from the default main context. You must +use [method@GLib.Source.destroy] for sources added to a non-default main context. -The ID of a #GSource is given by g_source_get_id(), or will be -returned by the functions g_source_attach(), g_idle_add(), -g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), -g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and -g_io_add_watch_full(). +The ID of a #GSource is given by [method@GLib.Source.get_id], or will be +returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add], +[func@GLib.idle_add_full], [func@GLib.timeout_add], +[func@GLib.timeout_add_full], [func@GLib.child_watch_add], +[func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and +[func@GLib.io_add_watch_full]. It is a programmer error to attempt to remove a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. - + %TRUE if the source was found and removed. + filename="glib/gmain.c" + line="2546">%TRUE if the source was found and removed. the ID of the source to remove. + filename="glib/gmain.c" + line="2523">the ID of the source to remove. @@ -39144,22 +41402,22 @@ wrong source. Removes a source from the default main loop context given the + filename="glib/gmain.c" + line="2589">Removes a source from the default main loop context given the source functions and user data. If multiple sources exist with the same source functions and user data, only one will be destroyed. - + %TRUE if a source was found and removed. + filename="glib/gmain.c" + line="2598">%TRUE if a source was found and removed. The @source_funcs passed to g_source_new() + filename="glib/gmain.c" + line="2591">The @source_funcs passed to [ctor@GLib.Source.new] nullable="1" allow-none="1"> the user data for the callback + filename="glib/gmain.c" + line="2592">the user data for the callback @@ -39176,15 +41434,15 @@ same source functions and user data, only one will be destroyed. Removes a source from the default main loop context given the user + filename="glib/gmain.c" + line="2564">Removes a source from the default main loop context given the user data for the callback. If multiple sources exist with the same user data, only one will be destroyed. - + %TRUE if a source was found and removed. + filename="glib/gmain.c" + line="2572">%TRUE if a source was found and removed. @@ -39193,8 +41451,8 @@ data, only one will be destroyed. nullable="1" allow-none="1"> the user_data for the callback. + filename="glib/gmain.c" + line="2566">the user_data for the callback. @@ -39203,11 +41461,11 @@ data, only one will be destroyed. c:identifier="g_source_set_name_by_id" version="2.26"> Sets the name of a source using its ID. + filename="glib/gmain.c" + line="2150">Sets the name of a source using its ID. This is a convenience utility to set source names from the return -value of g_idle_add(), g_timeout_add(), etc. +value of [func@GLib.idle_add], [func@GLib.timeout_add], etc. It is a programmer error to attempt to set the name of a non-existent source. @@ -39215,26 +41473,26 @@ source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. - + a #GSource ID + filename="glib/gmain.c" + line="2152">a #GSource ID debug name for the source + filename="glib/gmain.c" + line="2153">debug name for the source @@ -39242,13 +41500,16 @@ wrong source. The `GSourceCallbackFuncs` struct contains functions for managing callback objects. - + + Called when a reference is added to the callback object - + @@ -39260,8 +41521,11 @@ functions for managing callback objects. + Called when a reference to the callback object is dropped - + @@ -39273,8 +41537,12 @@ functions for managing callback objects. + Called to extract the callback function and data from the + callback object. - + @@ -39302,47 +41570,49 @@ functions for managing callback objects. c:type="GSourceDisposeFunc" version="2.64"> Dispose function for @source. See g_source_set_dispose_function() for -details. - + filename="glib/gmain.h" + line="254">Dispose function for @source. See [method@GLib.Source.set_dispose_function] +for details. + #GSource that is currently being disposed + filename="glib/gmain.h" + line="256">#GSource that is currently being disposed This is just a placeholder for #GClosureMarshal, + filename="glib/gmain.h" + line="301">This is just a placeholder for #GClosureMarshal, which cannot be used here for dependency reasons. - + Specifies the type of function passed to g_timeout_add(), -g_timeout_add_full(), g_idle_add(), and g_idle_add_full(). + filename="glib/gmain.h" + line="182">Specifies the type of function passed to [func@GLib.timeout_add], +[func@GLib.timeout_add_full], [func@GLib.idle_add], and +[func@GLib.idle_add_full]. -When calling g_source_set_callback(), you may need to cast a function of a -different type to this type. Use G_SOURCE_FUNC() to avoid warnings about -incompatible function types. - +When calling [method@GLib.Source.set_callback], you may need to cast a +function of a different type to this type. Use [func@GLib.SOURCE_FUNC] to +avoid warnings about incompatible function types. + %FALSE if the source should be removed. %G_SOURCE_CONTINUE and -%G_SOURCE_REMOVE are more memorable names for the return value. + filename="glib/gmain.h" + line="195">%FALSE if the source should be removed. +[const@GLib.SOURCE_CONTINUE] and [const@GLib.SOURCE_REMOVE] are more +memorable names for the return value. @@ -39352,8 +41622,8 @@ incompatible function types. allow-none="1" closure="0"> data passed to the function, set when the source was + filename="glib/gmain.h" + line="184">data passed to the function, set when the source was created with one of the above functions @@ -39361,7 +41631,7 @@ incompatible function types. The `GSourceFuncs` struct contains a table of functions used to handle event sources in a generic manner. @@ -39382,71 +41652,60 @@ any events need to be processed. It sets the returned timeout to -1 to indicate that it doesn't mind how long the poll() call blocks. In the check function, it tests the results of the poll() call to see if the required condition has been met, and returns %TRUE if so. - - - - - - - - - - - - - - - - + + + Called before all the file descriptors are polled. If the + source can determine that it is ready here (without waiting for the + results of the poll() call) it should return %TRUE. It can also return + a @timeout_ value which should be the maximum timeout (in milliseconds) + which should be passed to the poll() call. The actual timeout used will + be -1 if all sources returned -1, or it will be the minimum of all + the @timeout_ values returned which were >= 0. Since 2.36 this may + be %NULL, in which case the effect is as if the function always returns + %FALSE with a timeout of -1. If @prepare returns a + timeout and the source also has a ready time set, then the + lower of the two will be used. + - - - - - - - - - - - - + + Called after all the file descriptors are polled. The source + should return %TRUE if it is ready to be dispatched. Note that some + time may have passed since the previous prepare function was called, + so the source should be checked again here. Since 2.36 this may + be %NULL, in which case the effect is as if the function always returns + %FALSE. + - - - - - - - - - - - - - - - - - - + + Called to dispatch the event source, after it has returned + %TRUE in either its @prepare or its @check function, or if a ready time + has been reached. The @dispatch function receives a callback function and + user data. The callback function may be %NULL if the source was never + connected to a callback using [method@GLib.Source.set_callback]. The + @dispatch function should call the callback function with @user_data and + whatever additional parameters are needed for this type of event source. + The return value of the @dispatch function should be + [const@GLib.SOURCE_REMOVE] if the source should be removed or + [const@GLib.SOURCE_CONTINUE] to keep it. + - - - - - - - - - - - - + + Called when the source is finalized. At this point, the source + will have been destroyed, had its callback cleared, and have been removed + from its [struct@GLib.MainContext], but it will still have its final + reference count, so methods can be called on it from within this + function. + @@ -39455,14 +41714,168 @@ required condition has been met, and returns %TRUE if so. + + Checks if the source is ready to be dispatched. + +Called after all the file descriptors are polled. The source +should return %TRUE if it is ready to be dispatched. Note that some +time may have passed since the previous prepare function was called, +so the source should be checked again here. + +Since 2.36 this may be `NULL`, in which case the effect is +as if the function always returns `FALSE`. + + + %TRUE if ready to be dispatched, %FALSE otherwise + + + + + The #GSource + + + + + + Dispatches the source callback. + +Called to dispatch the event source, after it has returned +`TRUE` in either its prepare or its check function, or if a ready time +has been reached. The dispatch function receives a callback function and +user data. The callback function may be `NULL` if the source was never +connected to a callback using [method@GLib.Source.set_callback]. The dispatch +function should call the callback function with @user_data and whatever +additional parameters are needed for this type of event source. The +return value of the dispatch function should be [const@GLib.SOURCE_REMOVE] +if the source should be removed or [const@GLib.SOURCE_CONTINUE] to keep it. + + + [const@GLib.SOURCE_REMOVE] if the source should be removed, + [const@GLib.SOURCE_CONTINUE] otherwise. + + + + + The #GSource + + + + The #GSourceFunc to call + + + + data to pass to @callback + + + + + + Finalizes the source. + +Called when the source is finalized. At this point, the source +will have been destroyed, had its callback cleared, and have been removed +from its [type@GLib.MainContext], but it will still have its final reference +count, so methods can be called on it from within this function. + + + + + + + The #GSource + + + + + + Checks the source for readiness. + +Called before all the file descriptors are polled. If the +source can determine that it is ready here (without waiting for the +results of the poll call) it should return %TRUE. It can also return +a @timeout_ value which should be the maximum timeout (in milliseconds) +which should be passed to the poll call. The actual timeout used will +be `-1` if all sources returned `-1`, or it will be the minimum of all +the @timeout_ values returned which were greater than or equal to `0`. +If the prepare function returns a timeout and the source also has a +ready time set, then the lower of the two will be used. + +Since 2.36 this may be `NULL`, in which case the effect is as if the +function always returns `FALSE` with a timeout of `-1`. + + + %TRUE if the source is ready, %FALSE otherwise + + + + + The #GSource + + + + the maximum timeout (in milliseconds) which should be passed to the poll call + + + + A source function that is only called once before being removed from the main + filename="glib/gmain.h" + line="201">A source function that is only called once before being removed from the main context automatically. -See: g_idle_add_once(), g_timeout_add_once() - +See: [func@GLib.idle_add_once], [func@GLib.timeout_add_once] + @@ -39473,8 +41886,8 @@ See: g_idle_add_once(), g_timeout_add_once() allow-none="1" closure="0"> data passed to the function, set when the source was + filename="glib/gmain.h" + line="203">data passed to the function, set when the source was created @@ -39484,11 +41897,11 @@ See: g_idle_add_once(), g_timeout_add_once() c:type="GSourcePrivate" disguised="1" opaque="1"> - + Specifies the type of the setup function passed to g_spawn_async(), g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very limited ways, be used to affect the child's execution. @@ -39519,7 +41932,7 @@ If you need to set up the child environment differently from the parent, you should use g_get_environ(), g_environ_setenv(), and g_environ_unsetenv(), and then pass the complete environment list to the `g_spawn...` function. - + @@ -39529,7 +41942,7 @@ list to the `g_spawn...` function. nullable="1" allow-none="1"> user data passed to the function. @@ -39539,133 +41952,133 @@ list to the `g_spawn...` function. c:type="GSpawnError" glib:error-domain="g-exec-error-quark"> Error codes returned by spawning processes. - + Fork failed due to lack of memory. Read or select on pipes failed. Changing to working directory failed. execv() returned `EACCES` execv() returned `EPERM` execv() returned `E2BIG` deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32) execv() returned `ENOEXEC` execv() returned `ENAMETOOLONG` execv() returned `ENOENT` execv() returned `ENOMEM` execv() returned `ENOTDIR` execv() returned `ELOOP` execv() returned `ETXTBUSY` execv() returned `EIO` execv() returned `ENFILE` execv() returned `EMFILE` execv() returned `EINVAL` execv() returned `EISDIR` execv() returned `ELIBBAD` Some other fatal failure, `error->message` should explain. Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). - + no flags, default behaviour the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin, stdout and stderr will be closed before calling exec() in the child. @@ -39674,14 +42087,14 @@ list to the `g_spawn...` function. value="2" c:identifier="G_SPAWN_DO_NOT_REAP_CHILD"> the child will not be automatically reaped; you must use g_child_watch_add() yourself (or call waitpid() or handle `SIGCHLD` yourself), or the child will become a zombie. `argv[0]` need not be an absolute path, it will be looked for in the user's `PATH`. @@ -39689,7 +42102,7 @@ list to the `g_spawn...` function. value="8" c:identifier="G_SPAWN_STDOUT_TO_DEV_NULL"> the child's standard output will be discarded, instead of going to the same location as the parent's standard output. @@ -39697,14 +42110,14 @@ list to the `g_spawn...` function. value="16" c:identifier="G_SPAWN_STDERR_TO_DEV_NULL"> the child's standard error will be discarded. the child will inherit the parent's standard input (by default, the child's standard input is attached to `/dev/null`). @@ -39712,7 +42125,7 @@ list to the `g_spawn...` function. value="64" c:identifier="G_SPAWN_FILE_AND_ARGV_ZERO"> the first element of `argv` is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` @@ -39722,7 +42135,7 @@ list to the `g_spawn...` function. value="128" c:identifier="G_SPAWN_SEARCH_PATH_FROM_ENVP"> if `argv[0]` is not an absolute path, it will be looked for in the `PATH` from the passed child environment. Since: 2.34 @@ -39731,7 +42144,7 @@ list to the `g_spawn...` function. value="256" c:identifier="G_SPAWN_CLOEXEC_PIPES"> create all pipes with the `O_CLOEXEC` flag set. Since: 2.40 @@ -39740,7 +42153,7 @@ list to the `g_spawn...` function. c:identifier="G_SPAWN_CHILD_INHERITS_STDOUT" version="2.74"> The child will inherit the parent's standard output. c:identifier="G_SPAWN_CHILD_INHERITS_STDERR" version="2.74"> The child will inherit the parent's standard error. c:identifier="G_SPAWN_STDIN_FROM_DEV_NULL" version="2.74"> The child's standard input is attached to `/dev/null`. A type corresponding to the appropriate struct type for the stat() + filename="glib/gstdio.c" + line="1284">A type corresponding to the appropriate struct type for the stat() system call, depending on the platform and/or compiler being used. See g_stat() for more information. - + + + + A #GStaticMutex works like a #GMutex. + +Prior to GLib 2.32, GStaticMutex had the significant advantage +that it doesn't need to be created at run-time, but can be defined +at compile-time. Since 2.32, #GMutex can be statically allocated +as well, and GStaticMutex has been deprecated. + +Here is a version of our give_me_next_number() example using +a GStaticMutex: +|[ + int + give_me_next_number (void) + { + static int current_number = 0; + int ret_val; + static GStaticMutex mutex = G_STATIC_MUTEX_INIT; + + g_static_mutex_lock (&mutex); + ret_val = current_number = calc_next_number (current_number); + g_static_mutex_unlock (&mutex); + + return ret_val; + } +]| + +Sometimes you would like to dynamically create a mutex. If you don't +want to require prior calling to g_thread_init(), because your code +should also be usable in non-threaded programs, you are not able to +use g_mutex_new() and thus #GMutex, as that requires a prior call to +g_thread_init(). In these cases you can also use a #GStaticMutex. +It must be initialized with g_static_mutex_init() before using it +and freed with with g_static_mutex_free() when not needed anymore to +free up any allocated resources. + +Even though #GStaticMutex is not opaque, it should only be used with +the following functions, as it is defined differently on different +platforms. + +All of the g_static_mutex_* functions apart from +g_static_mutex_get_mutex() can also be used even if g_thread_init() +has not yet been called. Then they do nothing, apart from +g_static_mutex_trylock() which does nothing but returning %TRUE. + +All of the g_static_mutex_* functions are actually macros. Apart from +taking their addresses, you can however use them as if they were +functions. + + + + + + Releases all resources allocated to @mutex. + +You don't have to call this functions for a #GStaticMutex with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticMutex as a member of a structure and the structure is +freed, you should also free the #GStaticMutex. + +Calling g_static_mutex_free() on a locked mutex may result in +undefined behaviour. + Use g_mutex_clear() + + + + + + + a #GStaticMutex to be freed. + + + + + + + + + + + + + + + + + Initializes @mutex. +Alternatively you can initialize it with %G_STATIC_MUTEX_INIT. + Use g_mutex_init() + + + + + + + a #GStaticMutex to be initialized. + + + + + + + A #GStaticPrivate works almost like a #GPrivate, but it has one +significant advantage. It doesn't need to be created at run-time +like a #GPrivate, but can be defined at compile-time. This is +similar to the difference between #GMutex and #GStaticMutex. + +Now look at our give_me_next_number() example with #GStaticPrivate: +|[ + int + give_me_next_number () + { + static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; + int *current_number = g_static_private_get (&current_number_key); + + if (!current_number) + { + current_number = g_new (int, 1); + *current_number = 0; + g_static_private_set (&current_number_key, current_number, g_free); + } + + *current_number = calc_next_number (*current_number); + + return *current_number; + } +]| + + + + + + Releases all resources allocated to @private_key. + +You don't have to call this functions for a #GStaticPrivate with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticPrivate as a member of a structure and the structure is +freed, you should also free the #GStaticPrivate. + + + + + + + a #GStaticPrivate to be freed + + + + + + Works like g_private_get() only for a #GStaticPrivate. + +This function works even if g_thread_init() has not yet been called. + + + the corresponding pointer + + + + + a #GStaticPrivate + + + + + + Initializes @private_key. Alternatively you can initialize it with +%G_STATIC_PRIVATE_INIT. + + + + + + + a #GStaticPrivate to be initialized + + + + + + Sets the pointer keyed to @private_key for the current thread and +the function @notify to be called with that pointer (%NULL or +non-%NULL), whenever the pointer is set again or whenever the +current thread ends. + +This function works even if g_thread_init() has not yet been called. +If g_thread_init() is called later, the @data keyed to @private_key +will be inherited only by the main thread, i.e. the one that called +g_thread_init(). + +@notify is used quite differently from @destructor in g_private_new(). + + + + + + + a #GStaticPrivate + + + + the new pointer + + + + a function to be called with the pointer whenever the + current thread ends or sets this pointer again + + + + + + + The #GStaticRWLock struct represents a read-write lock. A read-write +lock can be used for protecting data that some portions of code only +read from, while others also write. In such situations it is +desirable that several readers can read at once, whereas of course +only one writer may write at a time. + +Take a look at the following example: +|[ + GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT; + GPtrArray *array; + + gpointer + my_array_get (guint index) + { + gpointer retval = NULL; + + if (!array) + return NULL; + + g_static_rw_lock_reader_lock (&rwlock); + if (index < array->len) + retval = g_ptr_array_index (array, index); + g_static_rw_lock_reader_unlock (&rwlock); + + return retval; + } + + void + my_array_set (guint index, gpointer data) + { + g_static_rw_lock_writer_lock (&rwlock); + + if (!array) + array = g_ptr_array_new (); + + if (index >= array->len) + g_ptr_array_set_size (array, index + 1); + g_ptr_array_index (array, index) = data; + + g_static_rw_lock_writer_unlock (&rwlock); + } +]| + +This example shows an array which can be accessed by many readers +(the my_array_get() function) simultaneously, whereas the writers +(the my_array_set() function) will only be allowed once at a time +and only if no readers currently access the array. This is because +of the potentially dangerous resizing of the array. Using these +functions is fully multi-thread safe now. + +Most of the time, writers should have precedence over readers. That +means, for this implementation, that as soon as a writer wants to +lock the data, no other reader is allowed to lock the data, whereas, +of course, the readers that already have locked the data are allowed +to finish their operation. As soon as the last reader unlocks the +data, the writer will lock it. + +Even though #GStaticRWLock is not opaque, it should only be used +with the following functions. + +All of the g_static_rw_lock_* functions can be used even if +g_thread_init() has not been called. Then they do nothing, apart +from g_static_rw_lock_*_trylock, which does nothing but returning %TRUE. + +A read-write lock has a higher overhead than a mutex. For example, both +g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock() have +to lock and unlock a #GStaticMutex, so it takes at least twice the time +to lock and unlock a #GStaticRWLock that it does to lock and unlock a +#GStaticMutex. So only data structures that are accessed by multiple +readers, and which keep the lock for a considerable time justify a +#GStaticRWLock. The above example most probably would fare better with a +#GStaticMutex. + Use a #GRWLock instead + + + + + + + + + + + + + + + + + + + + + + + + Releases all resources allocated to @lock. + +You don't have to call this functions for a #GStaticRWLock with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticRWLock as a member of a structure, and the structure is +freed, you should also free the #GStaticRWLock. + Use a #GRWLock instead + + + + + + + a #GStaticRWLock to be freed. + + + + + + A #GStaticRWLock must be initialized with this function before it +can be used. Alternatively you can initialize it with +%G_STATIC_RW_LOCK_INIT. + Use g_rw_lock_init() instead + + + + + + + a #GStaticRWLock to be initialized. + + + + + + Locks @lock for reading. There may be unlimited concurrent locks for +reading of a #GStaticRWLock at the same time. If @lock is already +locked for writing by another thread or if another thread is already +waiting to lock @lock for writing, this function will block until +@lock is unlocked by the other writing thread and no other writing +threads want to lock @lock. This lock has to be unlocked by +g_static_rw_lock_reader_unlock(). + +#GStaticRWLock is not recursive. It might seem to be possible to +recursively lock for reading, but that can result in a deadlock, due +to writer preference. + Use g_rw_lock_reader_lock() instead + + + + + + + a #GStaticRWLock to lock for reading. + + + + + + Tries to lock @lock for reading. If @lock is already locked for +writing by another thread or if another thread is already waiting to +lock @lock for writing, immediately returns %FALSE. Otherwise locks +@lock for reading and returns %TRUE. This lock has to be unlocked by +g_static_rw_lock_reader_unlock(). + Use g_rw_lock_reader_trylock() instead + + + %TRUE, if @lock could be locked for reading + + + + + a #GStaticRWLock to lock for reading + + + + + + Unlocks @lock. If a thread waits to lock @lock for writing and all +locks for reading have been unlocked, the waiting thread is woken up +and can lock @lock for writing. + Use g_rw_lock_reader_unlock() instead + + + + + + + a #GStaticRWLock to unlock after reading + + + + + + Locks @lock for writing. If @lock is already locked for writing or +reading by other threads, this function will block until @lock is +completely unlocked and then lock @lock for writing. While this +functions waits to lock @lock, no other thread can lock @lock for +reading. When @lock is locked for writing, no other thread can lock +@lock (neither for reading nor writing). This lock has to be +unlocked by g_static_rw_lock_writer_unlock(). + Use g_rw_lock_writer_lock() instead + + + + + + + a #GStaticRWLock to lock for writing + + + + + + Tries to lock @lock for writing. If @lock is already locked (for +either reading or writing) by another thread, it immediately returns +%FALSE. Otherwise it locks @lock for writing and returns %TRUE. This +lock has to be unlocked by g_static_rw_lock_writer_unlock(). + Use g_rw_lock_writer_trylock() instead + + + %TRUE, if @lock could be locked for writing + + + + + a #GStaticRWLock to lock for writing + + + + + + Unlocks @lock. If a thread is waiting to lock @lock for writing and +all locks for reading have been unlocked, the waiting thread is +woken up and can lock @lock for writing. If no thread is waiting to +lock @lock for writing, and some thread or threads are waiting to +lock @lock for reading, the waiting threads are woken up and can +lock @lock for reading. + Use g_rw_lock_writer_unlock() instead + + + + + + + a #GStaticRWLock to unlock after writing. + + + + + + + A #GStaticRecMutex works like a #GStaticMutex, but it can be locked +multiple times by one thread. If you enter it n times, you have to +unlock it n times again to let other threads lock it. An exception +is the function g_static_rec_mutex_unlock_full(): that allows you to +unlock a #GStaticRecMutex completely returning the depth, (i.e. the +number of times this mutex was locked). The depth can later be used +to restore the state of the #GStaticRecMutex by calling +g_static_rec_mutex_lock_full(). In GLib 2.32, #GStaticRecMutex has +been deprecated in favor of #GRecMutex. + +Even though #GStaticRecMutex is not opaque, it should only be used +with the following functions. + +All of the g_static_rec_mutex_* functions can be used even if +g_thread_init() has not been called. Then they do nothing, apart +from g_static_rec_mutex_trylock(), which does nothing but returning +%TRUE. + + + + + + + + + Releases all resources allocated to a #GStaticRecMutex. + +You don't have to call this functions for a #GStaticRecMutex with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticRecMutex as a member of a structure and the structure is +freed, you should also free the #GStaticRecMutex. + Use g_rec_mutex_clear() + + + + + + + a #GStaticRecMutex to be freed. + + + + + + A #GStaticRecMutex must be initialized with this function before it +can be used. Alternatively you can initialize it with +%G_STATIC_REC_MUTEX_INIT. + Use g_rec_mutex_init() + + + + + + + a #GStaticRecMutex to be initialized. + + + + + + Locks @mutex. If @mutex is already locked by another thread, the +current thread will block until @mutex is unlocked by the other +thread. If @mutex is already locked by the calling thread, this +functions increases the depth of @mutex and returns immediately. + Use g_rec_mutex_lock() + + + + + + + a #GStaticRecMutex to lock. + + + + + + Works like calling g_static_rec_mutex_lock() for @mutex @depth times. + Use g_rec_mutex_lock() + + + + + + + a #GStaticRecMutex to lock. + + + + number of times this mutex has to be unlocked to be + completely unlocked. + + + + + + Tries to lock @mutex. If @mutex is already locked by another thread, +it immediately returns %FALSE. Otherwise it locks @mutex and returns +%TRUE. If @mutex is already locked by the calling thread, this +functions increases the depth of @mutex and immediately returns +%TRUE. + Use g_rec_mutex_trylock() + + + %TRUE, if @mutex could be locked. + + + + + a #GStaticRecMutex to lock. + + + + + + Unlocks @mutex. Another thread will be allowed to lock @mutex only +when it has been unlocked as many times as it had been locked +before. If @mutex is completely unlocked and another thread is +blocked in a g_static_rec_mutex_lock() call for @mutex, it will be +woken and can lock @mutex itself. + Use g_rec_mutex_unlock() + + + + + + + a #GStaticRecMutex to unlock. + + + + + + Completely unlocks @mutex. If another thread is blocked in a +g_static_rec_mutex_lock() call for @mutex, it will be woken and can +lock @mutex itself. This function returns the number of times that +@mutex has been locked by the current thread. To restore the state +before the call to g_static_rec_mutex_unlock_full() you can call +g_static_rec_mutex_lock_full() with the depth returned by this +function. + Use g_rec_mutex_unlock() + + + number of times @mutex has been locked by the current + thread. + + + + + a #GStaticRecMutex to completely unlock. + + + + glib:get-type="g_gstring_get_type" c:symbol-prefix="gstring"> The GString struct contains the public fields of a GString. - + filename="glib/gstring.c" + line="45">A `GString` is an object that handles the memory management of a C string. + +The emphasis of `GString` is on text, typically UTF-8. Crucially, the "str" member +of a `GString` is guaranteed to have a trailing nul character, and it is therefore +always safe to call functions such as `strchr()` or `strdup()` on it. + +However, a `GString` can also hold arbitrary binary data, because it has a "len" member, +which includes any possible embedded nul characters in the data. Conceptually then, +`GString` is like a `GByteArray` with the addition of many convenience methods for +text, and a guaranteed nul terminator. + points to the character data. It may move as text is added. + filename="glib/gstring.c" + line="47">points to the character data. It may move as text is added. The @str field is null-terminated and so can be used as an ordinary C string. contains the length of the string, not including the + filename="glib/gstring.c" + line="50">contains the length of the string, not including the terminating nul byte. the number of bytes that can be stored in the + filename="glib/gstring.c" + line="52">the number of bytes that can be stored in the string before it needs to be reallocated. May be larger than @len. Creates a new #GString, initialized with the given string. - + filename="glib/gstring.c" + line="119">Creates a new #GString, initialized with the given string. + the new #GString + filename="glib/gstring.c" + line="126">the new #GString @@ -39817,8 +43046,8 @@ See g_stat() for more information. nullable="1" allow-none="1"> the initial text to copy into the string, or %NULL to + filename="glib/gstring.c" + line="121">the initial text to copy into the string, or %NULL to start with an empty string @@ -39826,32 +43055,32 @@ See g_stat() for more information. Creates a new #GString with @len bytes of the @init buffer. + filename="glib/gstring.c" + line="183">Creates a new #GString with @len bytes of the @init buffer. Because a length is provided, @init need not be nul-terminated, and can contain embedded nul bytes. Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that @init has at least @len addressable bytes. - + a new #GString + filename="glib/gstring.c" + line="196">a new #GString initial contents of the string + filename="glib/gstring.c" + line="185">initial contents of the string length of @init to use + filename="glib/gstring.c" + line="186">length of @init to use @@ -39860,17 +43089,17 @@ bytes. c:identifier="g_string_new_take" version="2.78"> Creates a new #GString, initialized with the given string. + filename="glib/gstring.c" + line="148">Creates a new #GString, initialized with the given string. After this call, @init belongs to the #GString and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with g_free(). - + the new #GString + filename="glib/gstring.c" + line="160">the new #GString @@ -39879,8 +43108,8 @@ allocated and will eventually be freed with g_free(). nullable="1" allow-none="1"> initial text used as the string. + filename="glib/gstring.c" + line="150">initial text used as the string. Ownership of the string is transferred to the #GString. Passing %NULL creates an empty string. @@ -39889,85 +43118,85 @@ allocated and will eventually be freed with g_free(). Creates a new #GString, with enough space for @dfl_size + filename="glib/gstring.c" + line="93">Creates a new #GString, with enough space for @dfl_size bytes. This is useful if you are going to add a lot of text to the string and don't want it to be reallocated too often. - + the new #GString + filename="glib/gstring.c" + line="102">the new #GString the default size of the space allocated to hold the string + filename="glib/gstring.c" + line="95">the default size of the space allocated to hold the string Adds a string onto the end of a #GString, expanding + filename="glib/gstring.c" + line="578">Adds a string onto the end of a #GString, expanding it if necessary. - + @string + filename="glib/gstring.c" + line="586">@string a #GString + filename="glib/gstring.c" + line="580">a #GString the string to append onto the end of @string + filename="glib/gstring.c" + line="581">the string to append onto the end of @string Adds a byte onto the end of a #GString, expanding + filename="glib/gstring.c" + line="621">Adds a byte onto the end of a #GString, expanding it if necessary. - + @string + filename="glib/gstring.c" + line="629">@string a #GString + filename="glib/gstring.c" + line="623">a #GString the byte to append onto the end of @string + filename="glib/gstring.c" + line="624">the byte to append onto the end of @string Appends @len bytes of @val to @string. + filename="glib/gstring.c" + line="595">Appends @len bytes of @val to @string. If @len is positive, @val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to @@ -39976,30 +43205,30 @@ ensure that @val has at least @len addressable bytes. If @len is negative, @val must be nul-terminated and @len is considered to request the entire string length. This makes g_string_append_len() equivalent to g_string_append(). - + @string + filename="glib/gstring.c" + line="611">@string a #GString + filename="glib/gstring.c" + line="597">a #GString bytes to append + filename="glib/gstring.c" + line="598">bytes to append number of bytes of @val to use, or -1 for all of @val + filename="glib/gstring.c" + line="599">number of bytes of @val to use, or -1 for all of @val @@ -40008,58 +43237,58 @@ makes g_string_append_len() equivalent to g_string_append(). c:identifier="g_string_append_printf" introspectable="0"> Appends a formatted string onto the end of a #GString. + filename="glib/gstring.c" + line="1406">Appends a formatted string onto the end of a #GString. This function is similar to g_string_printf() except that the text is appended to the #GString. - + a #GString + filename="glib/gstring.c" + line="1408">a #GString the string format. See the printf() documentation + filename="glib/gstring.c" + line="1409">the string format. See the printf() documentation the parameters to insert into the format string + filename="glib/gstring.c" + line="1410">the parameters to insert into the format string Converts a Unicode character into UTF-8, and appends it + filename="glib/gstring.c" + line="640">Converts a Unicode character into UTF-8, and appends it to the string. - + @string + filename="glib/gstring.c" + line="648">@string a #GString + filename="glib/gstring.c" + line="642">a #GString a Unicode character + filename="glib/gstring.c" + line="643">a Unicode character @@ -40068,40 +43297,40 @@ to the string. c:identifier="g_string_append_uri_escaped" version="2.16"> Appends @unescaped to @string, escaping any characters that + filename="glib/gstring.c" + line="552">Appends @unescaped to @string, escaping any characters that are reserved in URIs using URI-style escape sequences. - + @string + filename="glib/gstring.c" + line="563">@string a #GString + filename="glib/gstring.c" + line="554">a #GString a string + filename="glib/gstring.c" + line="555">a string a string of reserved characters allowed + filename="glib/gstring.c" + line="556">a string of reserved characters allowed to be used, or %NULL set %TRUE if the escaped string may include UTF8 characters + filename="glib/gstring.c" + line="558">set %TRUE if the escaped string may include UTF8 characters @@ -40111,45 +43340,45 @@ are reserved in URIs using URI-style escape sequences. version="2.14" introspectable="0"> Appends a formatted string onto the end of a #GString. + filename="glib/gstring.c" + line="1292">Appends a formatted string onto the end of a #GString. This function is similar to g_string_append_printf() except that the arguments to the format string are passed as a va_list. - + a #GString + filename="glib/gstring.c" + line="1294">a #GString the string format. See the printf() documentation + filename="glib/gstring.c" + line="1295">the string format. See the printf() documentation the list of arguments to insert in the output + filename="glib/gstring.c" + line="1296">the list of arguments to insert in the output Converts all uppercase ASCII letters to lowercase ASCII letters. - + filename="glib/gstring.c" + line="1162">Converts all uppercase ASCII letters to lowercase ASCII letters. + passed-in @string pointer, with all the + filename="glib/gstring.c" + line="1168">passed-in @string pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match g_ascii_tolower(). @@ -40157,21 +43386,21 @@ as a va_list. a GString + filename="glib/gstring.c" + line="1164">a GString Converts all lowercase ASCII letters to uppercase ASCII letters. - + filename="glib/gstring.c" + line="1193">Converts all lowercase ASCII letters to uppercase ASCII letters. + passed-in @string pointer, with all the + filename="glib/gstring.c" + line="1199">passed-in @string pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match g_ascii_toupper(). @@ -40179,38 +43408,38 @@ as a va_list. a GString + filename="glib/gstring.c" + line="1195">a GString Copies the bytes from a string into a #GString, + filename="glib/gstring.c" + line="365">Copies the bytes from a string into a #GString, destroying any previous contents. It is rather like the standard strcpy() function, except that you do not have to worry about having enough space to copy the string. - + @string + filename="glib/gstring.c" + line="376">@string the destination #GString. Its current contents + filename="glib/gstring.c" + line="367">the destination #GString. Its current contents are destroyed. the string to copy into @string + filename="glib/gstring.c" + line="369">the string to copy into @string @@ -40220,84 +43449,84 @@ have to worry about having enough space to copy the string. deprecated="1" deprecated-version="2.2"> Converts a #GString to lowercase. + filename="glib/gstring.c" + line="1224">Converts a #GString to lowercase. This function uses the locale-specific tolower() function, which is almost never the right thing. Use g_string_ascii_down() or g_utf8_strdown() instead. - + the #GString + filename="glib/gstring.c" + line="1230">the #GString a #GString + filename="glib/gstring.c" + line="1226">a #GString Compares two strings for equality, returning %TRUE if they are equal. + filename="glib/gstring.c" + line="304">Compares two strings for equality, returning %TRUE if they are equal. For use with #GHashTable. - + %TRUE if the strings are the same length and contain the + filename="glib/gstring.c" + line="312">%TRUE if the strings are the same length and contain the same bytes a #GString + filename="glib/gstring.c" + line="306">a #GString another #GString + filename="glib/gstring.c" + line="307">another #GString Removes @len bytes from a #GString, starting at position @pos. + filename="glib/gstring.c" + line="953">Removes @len bytes from a #GString, starting at position @pos. The rest of the #GString is shifted down to fill the gap. - + @string + filename="glib/gstring.c" + line="963">@string a #GString + filename="glib/gstring.c" + line="955">a #GString the position of the content to remove + filename="glib/gstring.c" + line="956">the position of the content to remove the number of bytes to remove, or -1 to remove all + filename="glib/gstring.c" + line="957">the number of bytes to remove, or -1 to remove all following bytes @@ -40305,33 +43534,33 @@ The rest of the #GString is shifted down to fill the gap. Frees the memory allocated for the #GString. + filename="glib/gstring.c" + line="217">Frees the memory allocated for the #GString. If @free_segment is %TRUE it also frees the character data. If it's %FALSE, the caller gains ownership of the buffer and must free it after use with g_free(). Instead of passing %FALSE to this function, consider using g_string_free_and_steal(). - + the character data of @string + filename="glib/gstring.c" + line="230">the character data of @string (i.e. %NULL if @free_segment is %TRUE) a #GString + filename="glib/gstring.c" + line="219">a #GString if %TRUE, the actual character data is freed as well + filename="glib/gstring.c" + line="220">if %TRUE, the actual character data is freed as well @@ -40340,23 +43569,23 @@ g_string_free_and_steal(). c:identifier="g_string_free_and_steal" version="2.76"> Frees the memory allocated for the #GString. + filename="glib/gstring.c" + line="254">Frees the memory allocated for the #GString. The caller gains ownership of the buffer and must free it after use with g_free(). - + the character data of @string + filename="glib/gstring.c" + line="263">the character data of @string a #GString + filename="glib/gstring.c" + line="256">a #GString @@ -40365,8 +43594,8 @@ must free it after use with g_free(). c:identifier="g_string_free_to_bytes" version="2.34"> Transfers ownership of the contents of @string to a newly allocated + filename="glib/gstring.c" + line="273">Transfers ownership of the contents of @string to a newly allocated #GBytes. The #GString structure itself is deallocated, and it is therefore invalid to use @string after invoking this function. @@ -40374,111 +43603,111 @@ Note that while #GString ensures that its buffer always has a trailing nul character (not reflected in its "len"), the returned #GBytes does not include this extra nul; i.e. it has length exactly equal to the "len" member. - + A newly allocated #GBytes containing contents of @string; @string itself is freed + filename="glib/gstring.c" + line="286">A newly allocated #GBytes containing contents of @string; @string itself is freed a #GString + filename="glib/gstring.c" + line="275">a #GString Creates a hash code for @str; for use with #GHashTable. - + filename="glib/gstring.c" + line="340">Creates a hash code for @str; for use with #GHashTable. + hash code for @str + filename="glib/gstring.c" + line="346">hash code for @str a string to hash + filename="glib/gstring.c" + line="342">a string to hash Inserts a copy of a string into a #GString, + filename="glib/gstring.c" + line="740">Inserts a copy of a string into a #GString, expanding it if necessary. - + @string + filename="glib/gstring.c" + line="749">@string a #GString + filename="glib/gstring.c" + line="742">a #GString the position to insert the copy of the string + filename="glib/gstring.c" + line="743">the position to insert the copy of the string the string to insert + filename="glib/gstring.c" + line="744">the string to insert Inserts a byte into a #GString, expanding it if necessary. - + filename="glib/gstring.c" + line="759">Inserts a byte into a #GString, expanding it if necessary. + @string + filename="glib/gstring.c" + line="767">@string a #GString + filename="glib/gstring.c" + line="761">a #GString the position to insert the byte + filename="glib/gstring.c" + line="762">the position to insert the byte the byte to insert + filename="glib/gstring.c" + line="763">the byte to insert Inserts @len bytes of @val into @string at @pos. + filename="glib/gstring.c" + line="447">Inserts @len bytes of @val into @string at @pos. If @len is positive, @val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to @@ -40488,71 +43717,71 @@ If @len is negative, @val must be nul-terminated and @len is considered to request the entire string length. If @pos is -1, bytes are inserted at the end of the string. - + @string + filename="glib/gstring.c" + line="466">@string a #GString + filename="glib/gstring.c" + line="449">a #GString position in @string where insertion should + filename="glib/gstring.c" + line="450">position in @string where insertion should happen, or -1 for at the end bytes to insert + filename="glib/gstring.c" + line="452">bytes to insert number of bytes of @val to insert, or -1 for all of @val + filename="glib/gstring.c" + line="453">number of bytes of @val to insert, or -1 for all of @val Converts a Unicode character into UTF-8, and insert it + filename="glib/gstring.c" + line="800">Converts a Unicode character into UTF-8, and insert it into the string at the given position. - + @string + filename="glib/gstring.c" + line="810">@string a #GString + filename="glib/gstring.c" + line="802">a #GString the position at which to insert character, or -1 + filename="glib/gstring.c" + line="803">the position at which to insert character, or -1 to append at the end of the string a Unicode character + filename="glib/gstring.c" + line="805">a Unicode character @@ -40561,32 +43790,32 @@ into the string at the given position. c:identifier="g_string_overwrite" version="2.14"> Overwrites part of a string, lengthening it if necessary. - + filename="glib/gstring.c" + line="883">Overwrites part of a string, lengthening it if necessary. + @string + filename="glib/gstring.c" + line="891">@string a #GString + filename="glib/gstring.c" + line="885">a #GString the position at which to start overwriting + filename="glib/gstring.c" + line="886">the position at which to start overwriting the string that will overwrite the @string starting at @pos + filename="glib/gstring.c" + line="887">the string that will overwrite the @string starting at @pos @@ -40595,101 +43824,101 @@ into the string at the given position. c:identifier="g_string_overwrite_len" version="2.14"> Overwrites part of a string, lengthening it if necessary. + filename="glib/gstring.c" + line="904">Overwrites part of a string, lengthening it if necessary. This function will work with embedded nuls. - + @string + filename="glib/gstring.c" + line="914">@string a #GString + filename="glib/gstring.c" + line="906">a #GString the position at which to start overwriting + filename="glib/gstring.c" + line="907">the position at which to start overwriting the string that will overwrite the @string starting at @pos + filename="glib/gstring.c" + line="908">the string that will overwrite the @string starting at @pos the number of bytes to write from @val + filename="glib/gstring.c" + line="909">the number of bytes to write from @val Adds a string on to the start of a #GString, + filename="glib/gstring.c" + line="659">Adds a string on to the start of a #GString, expanding it if necessary. - + @string + filename="glib/gstring.c" + line="667">@string a #GString + filename="glib/gstring.c" + line="661">a #GString the string to prepend on the start of @string + filename="glib/gstring.c" + line="662">the string to prepend on the start of @string Adds a byte onto the start of a #GString, + filename="glib/gstring.c" + line="702">Adds a byte onto the start of a #GString, expanding it if necessary. - + @string + filename="glib/gstring.c" + line="710">@string a #GString + filename="glib/gstring.c" + line="704">a #GString the byte to prepend on the start of the #GString + filename="glib/gstring.c" + line="705">the byte to prepend on the start of the #GString Prepends @len bytes of @val to @string. + filename="glib/gstring.c" + line="676">Prepends @len bytes of @val to @string. If @len is positive, @val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to @@ -40698,98 +43927,98 @@ ensure that @val has at least @len addressable bytes. If @len is negative, @val must be nul-terminated and @len is considered to request the entire string length. This makes g_string_prepend_len() equivalent to g_string_prepend(). - + @string + filename="glib/gstring.c" + line="692">@string a #GString + filename="glib/gstring.c" + line="678">a #GString bytes to prepend + filename="glib/gstring.c" + line="679">bytes to prepend number of bytes in @val to prepend, or -1 for all of @val + filename="glib/gstring.c" + line="680">number of bytes in @val to prepend, or -1 for all of @val Converts a Unicode character into UTF-8, and prepends it + filename="glib/gstring.c" + line="721">Converts a Unicode character into UTF-8, and prepends it to the string. - + @string + filename="glib/gstring.c" + line="729">@string a #GString + filename="glib/gstring.c" + line="723">a #GString a Unicode character + filename="glib/gstring.c" + line="724">a Unicode character Writes a formatted string into a #GString. + filename="glib/gstring.c" + line="1367">Writes a formatted string into a #GString. This is similar to the standard sprintf() function, except that the #GString buffer automatically expands to contain the results. The previous contents of the #GString are destroyed. - + a #GString + filename="glib/gstring.c" + line="1369">a #GString the string format. See the printf() documentation + filename="glib/gstring.c" + line="1370">the string format. See the printf() documentation the parameters to insert into the format string + filename="glib/gstring.c" + line="1371">the parameters to insert into the format string Replaces the string @find with the string @replace in a #GString up to + filename="glib/gstring.c" + line="998">Replaces the string @find with the string @replace in a #GString up to @limit times. If the number of instances of @find in the #GString is less than @limit, all instances are replaced. If @limit is `0`, all instances of @find are replaced. @@ -40798,36 +44027,36 @@ If @find is the empty string, since versions 2.69.1 and 2.68.4 the replacement will be inserted no more than once per possible position (beginning of string, end of string and between characters). This did not work correctly in earlier versions. - + the number of find and replace operations performed. + filename="glib/gstring.c" + line="1016">the number of find and replace operations performed. a #GString + filename="glib/gstring.c" + line="1000">a #GString the string to find in @string + filename="glib/gstring.c" + line="1001">the string to find in @string the string to insert in place of @find + filename="glib/gstring.c" + line="1002">the string to insert in place of @find the maximum instances of @find to replace with @replace, or `0` for + filename="glib/gstring.c" + line="1003">the maximum instances of @find to replace with @replace, or `0` for no limit @@ -40835,56 +44064,56 @@ no limit Sets the length of a #GString. If the length is less than + filename="glib/gstring.c" + line="419">Sets the length of a #GString. If the length is less than the current length, the string will be truncated. If the length is greater than the current length, the contents of the newly added area are undefined. (However, as always, string->str[string->len] will be a nul byte.) - + @string + filename="glib/gstring.c" + line="430">@string a #GString + filename="glib/gstring.c" + line="421">a #GString the new length + filename="glib/gstring.c" + line="422">the new length Cuts off the end of the GString, leaving the first @len bytes. - + filename="glib/gstring.c" + line="398">Cuts off the end of the GString, leaving the first @len bytes. + @string + filename="glib/gstring.c" + line="405">@string a #GString + filename="glib/gstring.c" + line="400">a #GString the new size of @string + filename="glib/gstring.c" + line="401">the new size of @string @@ -40894,23 +44123,23 @@ always, string->str[string->len] will be a nul byte.) deprecated="1" deprecated-version="2.2"> Converts a #GString to uppercase. + filename="glib/gstring.c" + line="1258">Converts a #GString to uppercase. This function uses the locale-specific toupper() function, which is almost never the right thing. Use g_string_ascii_up() or g_utf8_strup() instead. - + @string + filename="glib/gstring.c" + line="1264">@string a #GString + filename="glib/gstring.c" + line="1260">a #GString @@ -40920,31 +44149,31 @@ always, string->str[string->len] will be a nul byte.) version="2.14" introspectable="0"> Writes a formatted string into a #GString. + filename="glib/gstring.c" + line="1331">Writes a formatted string into a #GString. This function is similar to g_string_printf() except that the arguments to the format string are passed as a va_list. - + a #GString + filename="glib/gstring.c" + line="1333">a #GString the string format. See the printf() documentation + filename="glib/gstring.c" + line="1334">the string format. See the printf() documentation the parameters to insert into the format string + filename="glib/gstring.c" + line="1335">the parameters to insert into the format string @@ -40952,52 +44181,73 @@ the arguments to the format string are passed as a va_list. An opaque data structure representing String Chunks. -It should only be accessed by using the following functions. - + filename="glib/gstringchunk.c" + line="44">`GStringChunk` provides efficient storage of groups of strings + +String chunks are used to store groups of strings. Memory is +allocated in blocks, and as strings are added to the `GStringChunk` +they are copied into the next free position in a block. When a block +is full a new block is allocated. + +When storing a large number of strings, string chunks are more +efficient than using [func@GLib.strdup] since fewer calls to `malloc()` +are needed, and less memory is wasted in memory allocation overheads. + +By adding strings with [method@GLib.StringChunk.insert_const] it is also +possible to remove duplicates. + +To create a new `GStringChunk` use [func@GLib.StringChunk.new]. + +To add strings to a `GStringChunk` use [method@GLib.StringChunk.insert]. + +To add strings to a `GStringChunk`, but without duplicating strings +which are already in the `GStringChunk`, use [method@GLib.StringChunk.insert_const]. + +To free the entire `GStringChunk` use [method@GLib.StringChunk.free]. +It is not possible to free individual strings. + Frees all strings contained within the #GStringChunk. + filename="glib/gstringchunk.c" + line="131">Frees all strings contained within the #GStringChunk. After calling g_string_chunk_clear() it is not safe to access any of the strings which were contained within it. - + a #GStringChunk + filename="glib/gstringchunk.c" + line="133">a #GStringChunk Frees all memory allocated by the #GStringChunk. + filename="glib/gstringchunk.c" + line="109">Frees all memory allocated by the #GStringChunk. After calling g_string_chunk_free() it is not safe to access any of the strings which were contained within it. - + - + a #GStringChunk + filename="glib/gstringchunk.c" + line="111">a #GStringChunk Adds a copy of @string to the #GStringChunk. + filename="glib/gstringchunk.c" + line="159">Adds a copy of @string to the #GStringChunk. It returns a pointer to the new copy of the string in the #GStringChunk. The characters in the string can be changed, if necessary, though you should not @@ -41008,33 +44258,33 @@ does not check for duplicates. Also strings added with g_string_chunk_insert() will not be searched by g_string_chunk_insert_const() when looking for duplicates. - + a pointer to the copy of @string within + filename="glib/gstringchunk.c" + line="176">a pointer to the copy of @string within the #GStringChunk a #GStringChunk + filename="glib/gstringchunk.c" + line="161">a #GStringChunk the string to add + filename="glib/gstringchunk.c" + line="162">the string to add Adds a copy of @string to the #GStringChunk, unless the same + filename="glib/gstringchunk.c" + line="188">Adds a copy of @string to the #GStringChunk, unless the same string has already been added to the #GStringChunk with g_string_chunk_insert_const(). @@ -41047,25 +44297,25 @@ should be done very carefully. Note that g_string_chunk_insert_const() will not return a pointer to a string added with g_string_chunk_insert(), even if they do match. - + a pointer to the new or existing copy of @string + filename="glib/gstringchunk.c" + line="207">a pointer to the new or existing copy of @string within the #GStringChunk a #GStringChunk + filename="glib/gstringchunk.c" + line="190">a #GStringChunk the string to add + filename="glib/gstringchunk.c" + line="191">the string to add @@ -41074,8 +44324,8 @@ if they do match. c:identifier="g_string_chunk_insert_len" version="2.4"> Adds a copy of the first @len bytes of @string to the #GStringChunk. + filename="glib/gstringchunk.c" + line="232">Adds a copy of the first @len bytes of @string to the #GStringChunk. The copy is nul-terminated. Since this function does not stop at nul bytes, it is the caller's @@ -41084,30 +44334,30 @@ bytes. The characters in the returned string can be changed, if necessary, though you should not change anything after the end of the string. - + a pointer to the copy of @string within the #GStringChunk + filename="glib/gstringchunk.c" + line="249">a pointer to the copy of @string within the #GStringChunk a #GStringChunk + filename="glib/gstringchunk.c" + line="234">a #GStringChunk bytes to insert + filename="glib/gstringchunk.c" + line="235">bytes to insert number of bytes of @string to insert, or -1 to insert a + filename="glib/gstringchunk.c" + line="236">number of bytes of @string to insert, or -1 to insert a nul-terminated string @@ -41117,20 +44367,20 @@ though you should not change anything after the end of the string. c:identifier="g_string_chunk_new" introspectable="0"> Creates a new #GStringChunk. - - + filename="glib/gstringchunk.c" + line="81">Creates a new #GStringChunk. + + a new #GStringChunk + filename="glib/gstringchunk.c" + line="90">a new #GStringChunk the default size of the blocks of memory which are + filename="glib/gstringchunk.c" + line="83">the default size of the blocks of memory which are allocated to store the strings. If a particular string is larger than this default size, a larger block of memory will be allocated for it. @@ -41141,44 +44391,61 @@ though you should not change anything after the end of the string. + version="2.68" + glib:type-name="GStrvBuilder" + glib:get-type="g_strv_builder_get_type" + c:symbol-prefix="strv_builder"> #GStrvBuilder is a method of easily building dynamically sized -NULL-terminated string arrays. + filename="glib/gstrvbuilder.c" + line="29">`GStrvBuilder` is a helper object to build a %NULL-terminated string arrays. The following example shows how to build a two element array: -|[<!-- language="C" --> +```c g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); g_strv_builder_add (builder, "hello"); g_strv_builder_add (builder, "world"); + g_auto(GStrv) array = g_strv_builder_end (builder); -]| - + + g_assert_true (g_strv_equal (array, (const char *[]) { "hello", "world", NULL })); +``` + + + Creates a new #GStrvBuilder with a reference count of 1. +Use g_strv_builder_unref() on the returned value when no longer needed. + + + the new #GStrvBuilder + + + Add a string to the end of the array. + filename="glib/gstrvbuilder.c" + line="141">Add a string to the end of the array. Since 2.68 - + a #GStrvBuilder + filename="glib/gstrvbuilder.c" + line="143">a #GStrvBuilder a string. + filename="glib/gstrvbuilder.c" + line="144">a string. @@ -41187,50 +44454,50 @@ Since 2.68 c:identifier="g_strv_builder_add_many" introspectable="0"> Appends all the given strings to the builder. + filename="glib/gstrvbuilder.c" + line="177">Appends all the given strings to the builder. Since 2.70 - + a #GStrvBuilder + filename="glib/gstrvbuilder.c" + line="179">a #GStrvBuilder one or more strings followed by %NULL + filename="glib/gstrvbuilder.c" + line="180">one or more strings followed by %NULL Appends all the strings in the given vector to the builder. + filename="glib/gstrvbuilder.c" + line="157">Appends all the strings in the given vector to the builder. Since 2.70 - + a #GStrvBuilder + filename="glib/gstrvbuilder.c" + line="159">a #GStrvBuilder the vector of strings to add + filename="glib/gstrvbuilder.c" + line="160">the vector of strings to add @@ -41239,15 +44506,15 @@ Since 2.70 Ends the builder process and returns the constructed NULL-terminated string + filename="glib/gstrvbuilder.c" + line="217">Ends the builder process and returns the constructed NULL-terminated string array. The returned value should be freed with g_strfreev() when no longer needed. - + the constructed string array. + filename="glib/gstrvbuilder.c" + line="225">the constructed string array. Since 2.68 @@ -41257,103 +44524,181 @@ Since 2.68 a #GStrvBuilder + filename="glib/gstrvbuilder.c" + line="219">a #GStrvBuilder - + Atomically increments the reference count of @builder by one. + filename="glib/gstrvbuilder.c" + line="124">Atomically increments the reference count of @builder by one. This function is thread-safe and may be called from any thread. - + The passed in #GStrvBuilder + filename="glib/gstrvbuilder.c" + line="131">The passed in #GStrvBuilder a #GStrvBuilder + filename="glib/gstrvbuilder.c" + line="126">a #GStrvBuilder + + + + + + Add a string to the end of the array. After @value belongs to the +#GStrvBuilder and may no longer be modified by the caller. + +Since 2.80 + + + + + + + a #GStrvBuilder + + a string. + Ownership of the string is transferred to the #GStrvBuilder + + Decreases the reference count on @builder. + filename="glib/gstrvbuilder.c" + line="70">Decreases the reference count on @builder. In the event that there are no more references, releases all memory associated with the #GStrvBuilder. - + a #GStrvBuilder allocated by g_strv_builder_new() + filename="glib/gstrvbuilder.c" + line="72">a #GStrvBuilder allocated by g_strv_builder_new() - + Creates a new #GStrvBuilder with a reference count of 1. -Use g_strv_builder_unref() on the returned value when no longer needed. - + filename="glib/gstrvbuilder.c" + line="87">Decreases the reference count on the string vector builder, and returns +its contents as a `NULL`-terminated string array. + +This function is especially useful for cases where it's not possible +to use `g_autoptr()`. + +```c +GStrvBuilder *builder = g_strv_builder_new (); +g_strv_builder_add (builder, "hello"); +g_strv_builder_add (builder, "world"); + +GStrv array = g_strv_builder_unref_to_strv (builder); + +g_assert_true (g_strv_equal (array, (const char *[]) { "hello", "world", NULL })); + +g_strfreev (array); +``` + the new #GStrvBuilder - + filename="glib/gstrvbuilder.c" + line="109">the constructed string + array + + + - + + + a #GStrvBuilder + + + + Creates a unique temporary directory for each unit test and uses -g_set_user_dirs() to set XDG directories to point into subdirectories of it -for the duration of the unit test. The directory tree is cleaned up after the -test finishes successfully. Note that this doesn’t take effect until -g_test_run() is called, so calls to (for example) g_get_user_home_dir() will -return the system-wide value when made in a test program’s main() function. + filename="glib/gtestutils.h" + line="302">A value that can be passed as an option to [func@GLib.test_init]. + +Creates a unique temporary directory for each unit test and uses sets +XDG directories to point into subdirectories of it for the duration of +the unit test. The directory tree is cleaned up after the test finishes +successfully. + +Note that this doesn’t take effect until [func@GLib.test_run] is called, +so calls to (for example) [func@GLib.get_home_dir] will return the +system-wide value when made in a test program’s main() function. The following functions will return subdirectories of the temporary directory when this option is used. The specific subdirectory paths in use are not guaranteed to be stable API — always use a getter function to retrieve them. - - g_get_home_dir() - - g_get_user_cache_dir() - - g_get_system_config_dirs() - - g_get_user_config_dir() - - g_get_system_data_dirs() - - g_get_user_data_dir() - - g_get_user_state_dir() - - g_get_user_runtime_dir() + - [func@GLib.get_home_dir] + - [func@GLib.get_user_cache_dir] + - [func@GLib.get_system_config_dirs] + - [func@GLib.get_user_config_dir] + - [func@GLib.get_system_data_dirs] + - [func@GLib.get_user_data_dir] + - [func@GLib.get_user_state_dir] + - [func@GLib.get_user_runtime_dir] The subdirectories may not be created by the test harness; as with normal -calls to functions like g_get_user_cache_dir(), the caller must be prepared -to create the directory if it doesn’t exist. - +calls to functions like [func@GLib.get_user_cache_dir], the caller must +be prepared to create the directory if it doesn’t exist. + + + + + A value that can be passed as an option to [func@GLib.test_init]. + +If this option is given, assertions will not abort the process, but +call [func@GLib.test_fail]. Equivalent to [func@GLib.test_set_nonfatal_assertions]. + + + + + A value that can be passed as an option to [func@GLib.test_init]. + +If this option is given, [func@GLib.test_init] will not call [func@GLib.set_prgname]. + c:type="G_TIME_SPAN_DAY" version="2.26"> Evaluates to a time span of one day. - + c:type="G_TIME_SPAN_HOUR" version="2.26"> Evaluates to a time span of one hour. - + c:type="G_TIME_SPAN_MILLISECOND" version="2.26"> Evaluates to a time span of one millisecond. - + c:type="G_TIME_SPAN_MINUTE" version="2.26"> Evaluates to a time span of one minute. - + c:type="G_TIME_SPAN_SECOND" version="2.26"> Evaluates to a time span of one second. - + Works like g_mutex_trylock(), but for a lock defined with + filename="glib/gthread.c" + line="184">Works like g_mutex_trylock(), but for a lock defined with %G_LOCK_DEFINE. - + the name of the lock + filename="glib/gthread.c" + line="186">the name of the lock An opaque structure representing a test case. - + filename="glib/gtestutils.c" + line="647">An opaque structure representing a test case. + Free the @test_case. - + filename="glib/gtestutils.c" + line="3318">Free the @test_case. + a #GTestCase + filename="glib/gtestutils.c" + line="3320">a test case - + @@ -41466,10 +44811,10 @@ to create the directory if it doesn’t exist. The type used for test case functions that take an extra pointer + filename="glib/gtestutils.c" + line="2822">The type used for test case functions that take an extra pointer argument. - + @@ -41480,65 +44825,67 @@ argument. allow-none="1" closure="0"> the data provided when registering the test + filename="glib/gtestutils.c" + line="2824">the data provided when registering the test The type of file to return the filename for, when used with -g_test_build_filename(). + filename="glib/gtestutils.c" + line="4661">The type of file to return the filename for, when used with +[func@GLib.test_build_filename]. These two options correspond rather directly to the 'dist' and 'built' terminology that automake uses and are explicitly used to -distinguish between the 'srcdir' and 'builddir' being separate. All -files in your project should either be dist (in the -`EXTRA_DIST` or `dist_schema_DATA` -sense, in which case they will always be in the srcdir) or built (in -the `BUILT_SOURCES` sense, in which case they will -always be in the builddir). - -Note: as a general rule of automake, files that are generated only as +distinguish between the 'srcdir' and 'builddir' being separate. All +files in your project should either be dist (in the `EXTRA_DIST` or +`dist_schema_DATA` sense, in which case they will always be in the +srcdir) or built (in the `BUILT_SOURCES` sense, in which case they +will always be in the builddir). + +Note: As a general rule of automake, files that are generated only as part of the build-from-git process (but then are distributed with the tarball) always go in srcdir (even if doing a srcdir != builddir -build from git) and are considered as distributed files. - +build from git) and are considered as distributed files. + +The same principles apply for other build systems, such as meson. + a file that was included in the distribution tarball + filename="glib/gtestutils.c" + line="4663">a file that was included in the distribution tarball a file that was built on the compiling machine + filename="glib/gtestutils.c" + line="4664">a file that was built on the compiling machine The type used for functions that operate on test fixtures. This is -used for the fixture setup and teardown functions as well as for the -testcases themselves. + filename="glib/gtestutils.c" + line="2492">The type used for functions that operate on test fixtures. + +This is used for the fixture setup and teardown functions +as well as for the testcases themselves. -@user_data is a pointer to the data that was given when registering -the test case. +@user_data is a pointer to the data that was given when +registering the test case. @fixture will be a pointer to the area of memory allocated by the test framework, of the size requested. If the requested size was zero then @fixture will be equal to @user_data. - + the test fixture + filename="glib/gtestutils.c" + line="2494">the test fixture allow-none="1" closure="1"> the data provided when registering the test + filename="glib/gtestutils.c" + line="2495">the data provided when registering the test The type used for test case functions. - + filename="glib/gtestutils.c" + line="2782">The type used for test case functions. + - + @@ -41574,9 +44921,9 @@ zero then @fixture will be equal to @user_data. Internal function for gtester to free test log messages, no ABI guarantees provided. - + filename="glib/gtestutils.c" + line="4529">Internal function for gtester to free test log messages, no ABI guarantees provided. + @@ -41590,9 +44937,9 @@ zero then @fixture will be equal to @user_data. c:identifier="g_test_log_buffer_pop" introspectable="0"> Internal function for gtester to retrieve test log messages, no ABI guarantees provided. - + filename="glib/gtestutils.c" + line="4566">Internal function for gtester to retrieve test log messages, no ABI guarantees provided. + @@ -41604,9 +44951,9 @@ zero then @fixture will be equal to @user_data. Internal function for gtester to decode test log messages, no ABI guarantees provided. - + filename="glib/gtestutils.c" + line="4544">Internal function for gtester to decode test log messages, no ABI guarantees provided. + @@ -41626,9 +44973,9 @@ zero then @fixture will be equal to @user_data. c:identifier="g_test_log_buffer_new" introspectable="0"> Internal function for gtester to decode test log messages, no ABI guarantees provided. - + filename="glib/gtestutils.c" + line="4516">Internal function for gtester to decode test log messages, no ABI guarantees provided. + @@ -41638,32 +44985,32 @@ zero then @fixture will be equal to @user_data. c:type="GTestLogFatalFunc" version="2.22"> Specifies the prototype of fatal log handler functions. - + filename="glib/gtestutils.h" + line="747">Specifies the prototype of fatal log handler functions. + %TRUE if the program should abort, %FALSE otherwise + filename="glib/gtestutils.h" + line="756">%TRUE if the program should abort, %FALSE otherwise the log domain of the message + filename="glib/gtestutils.h" + line="749">the log domain of the message the log level of the message (including the fatal and recursion flags) + filename="glib/gtestutils.h" + line="750">the log level of the message (including the fatal and recursion flags) the message to process + filename="glib/gtestutils.h" + line="751">the message to process allow-none="1" closure="3"> user data, set in g_test_log_set_fatal_handler() + filename="glib/gtestutils.h" + line="752">user data, set in g_test_log_set_fatal_handler() - + @@ -41697,9 +45044,9 @@ zero then @fixture will be equal to @user_data. Internal function for gtester to free test log messages, no ABI guarantees provided. - + filename="glib/gtestutils.c" + line="4585">Internal function for gtester to free test log messages, no ABI guarantees provided. + @@ -41711,7 +45058,7 @@ zero then @fixture will be equal to @user_data. - + @@ -41744,7 +45091,7 @@ zero then @fixture will be equal to @user_data. - + @@ -41756,73 +45103,74 @@ zero then @fixture will be equal to @user_data. Flags to pass to g_test_trap_subprocess() to control input and output. + filename="glib/gtestutils.c" + line="194">Flags to pass to [func@GLib.test_trap_subprocess] to control input and output. -Note that in contrast with g_test_trap_fork(), the default is to -not show stdout and stderr. - +Note that in contrast with [func@GLib.test_trap_fork], the default +behavior of [func@GLib.test_trap_subprocess] is to not show stdout +and stderr. + Default behaviour. Since: 2.74 + filename="glib/gtestutils.c" + line="196">Default behaviour. Since: 2.74 If this flag is given, the child - process will inherit the parent's stdin. Otherwise, the child's - stdin is redirected to `/dev/null`. + filename="glib/gtestutils.c" + line="197">If this flag is given, the child + process will inherit the parent's stdin. Otherwise, the child's + stdin is redirected to `/dev/null`. If this flag is given, the child - process will inherit the parent's stdout. Otherwise, the child's - stdout will not be visible, but it will be captured to allow - later tests with g_test_trap_assert_stdout(). + filename="glib/gtestutils.c" + line="200">If this flag is given, the child + process will inherit the parent's stdout. Otherwise, the child's + stdout will not be visible, but it will be captured to allow + later tests with [func@GLib.test_trap_assert_stdout]. If this flag is given, the child - process will inherit the parent's stderr. Otherwise, the child's - stderr will not be visible, but it will be captured to allow - later tests with g_test_trap_assert_stderr(). + filename="glib/gtestutils.c" + line="204">If this flag is given, the child + process will inherit the parent's stderr. Otherwise, the child's + stderr will not be visible, but it will be captured to allow + later tests with [func@GLib.test_trap_assert_stderr]. An opaque structure representing a test suite. - + filename="glib/gtestutils.c" + line="653">An opaque structure representing a test suite. + Adds @test_case to @suite. - + filename="glib/gtestutils.c" + line="2954">Adds @test_case to @suite. + a #GTestSuite + filename="glib/gtestutils.c" + line="2956">a test suite a #GTestCase + filename="glib/gtestutils.c" + line="2957">a test case @@ -41831,40 +45179,40 @@ not show stdout and stderr. c:identifier="g_test_suite_add_suite" version="2.16"> Adds @nestedsuite to @suite. - + filename="glib/gtestutils.c" + line="2973">Adds @nestedsuite to @suite. + a #GTestSuite + filename="glib/gtestutils.c" + line="2975">a test suite another #GTestSuite + filename="glib/gtestutils.c" + line="2976">another test suite Free the @suite and all nested #GTestSuites. - + filename="glib/gtestutils.c" + line="3340">Frees the @suite and all nested suites. + a #GTestSuite + filename="glib/gtestutils.c" + line="3342">a test suite @@ -41875,24 +45223,25 @@ not show stdout and stderr. deprecated-version="2.38" c:type="GTestTrapFlags"> Test traps are guards around forked tests. -These flags determine what traps to set. - #GTestTrapFlags is used only with g_test_trap_fork(), -which is deprecated. g_test_trap_subprocess() uses -#GTestSubprocessFlags. - + filename="glib/gtestutils.h" + line="501">Flags to pass to [func@GLib.test_trap_fork] to control input and output. + +Test traps are guards around forked tests. These flags determine what traps to set. + `GTestTrapFlags` is used only with [func@GLib.test_trap_fork], + which is deprecated. Its replacement, [func@GLib.test_trap_subprocess] uses + [flags@GLib.TestSubprocessFlags]. + Default behaviour. Since: 2.74 + filename="glib/gtestutils.h" + line="503">Default behaviour. Since: 2.74 Redirect stdout of the test child to + filename="glib/gtestutils.h" + line="504">Redirect stdout of the test child to `/dev/null` so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stdout(). @@ -41901,8 +45250,8 @@ which is deprecated. g_test_trap_subprocess() uses value="256" c:identifier="G_TEST_TRAP_SILENCE_STDERR"> Redirect stderr of the test child to + filename="glib/gtestutils.h" + line="508">Redirect stderr of the test child to `/dev/null` so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stderr(). @@ -41911,21 +45260,20 @@ which is deprecated. g_test_trap_subprocess() uses value="512" c:identifier="G_TEST_TRAP_INHERIT_STDIN"> If this flag is given, stdin of the + filename="glib/gtestutils.h" + line="512">If this flag is given, stdin of the child process is shared with stdin of its parent process. It is redirected to `/dev/null` otherwise. The #GThread struct represents a running thread. This struct + filename="glib/gthread.c" + line="434">The #GThread struct represents a running thread. This struct is returned by g_thread_new() or g_thread_try_new(). You can obtain the #GThread struct representing the current thread by calling g_thread_self(). @@ -41938,11 +45286,23 @@ explicitly. The structure is opaque -- none of its fields may be directly accessed. - + + + + + + + + + + + + + This function creates a new thread. The new thread starts by invoking + filename="glib/gthread.c" + line="901">This function creates a new thread. The new thread starts by invoking @func with the argument data. The thread will run until @func returns or until g_thread_exit() is called from the new thread. The return value of @func becomes the return value of the thread, which can be obtained @@ -41969,11 +45329,11 @@ This behaviour changed in GLib 2.64: before threads on Windows were not inheriting the thread priority but were spawned with the default priority. Starting with GLib 2.64 the behaviour is now consistent between Windows and POSIX and all threads inherit their parent thread's priority. - + the new #GThread + filename="glib/gthread.c" + line="935">the new #GThread @@ -41982,8 +45342,8 @@ POSIX and all threads inherit their parent thread's priority. nullable="1" allow-none="1"> an (optional) name for the new thread + filename="glib/gthread.c" + line="903">an (optional) name for the new thread scope="async" closure="2"> a function to execute in the new thread + filename="glib/gthread.c" + line="904">a function to execute in the new thread nullable="1" allow-none="1"> an argument to supply to the new thread + filename="glib/gthread.c" + line="905">an argument to supply to the new thread @@ -42011,17 +45371,17 @@ POSIX and all threads inherit their parent thread's priority. version="2.32" throws="1"> This function is the same as g_thread_new() except that + filename="glib/gthread.c" + line="955">This function is the same as g_thread_new() except that it allows for the possibility of failure. If a thread can not be created (due to resource limits), @error is set and %NULL is returned. - + the new #GThread, or %NULL if an error occurred + filename="glib/gthread.c" + line="968">the new #GThread, or %NULL if an error occurred @@ -42030,8 +45390,8 @@ If a thread can not be created (due to resource limits), nullable="1" allow-none="1"> an (optional) name for the new thread + filename="glib/gthread.c" + line="957">an (optional) name for the new thread a function to execute in the new thread + filename="glib/gthread.c" + line="958">a function to execute in the new thread an argument to supply to the new thread + filename="glib/gthread.c" + line="959">an argument to supply to the new thread + + Gets the name of the thread. + +This function is intended for debugging purposes. + + + the name of the thread + + + + + a thread + + + + Waits until @thread finishes, i.e. the function @func, as + filename="glib/gthread.c" + line="1028">Waits until @thread finishes, i.e. the function @func, as given to g_thread_new(), returns or g_thread_exit() is called. If @thread has already terminated, then g_thread_join() returns immediately. @@ -42073,64 +45455,204 @@ g_thread_join() consumes the reference to the passed-in @thread. This will usually cause the #GThread struct and associated resources to be freed. Use g_thread_ref() to obtain an extra reference if you want to keep the GThread alive beyond the g_thread_join() call. - + the return value of the thread + filename="glib/gthread.c" + line="1049">the return value of the thread a #GThread + filename="glib/gthread.c" + line="1030">a #GThread Increase the reference count on @thread. - + filename="glib/gthread.c" + line="821">Increase the reference count on @thread. + a new reference to @thread + filename="glib/gthread.c" + line="827">a new reference to @thread a #GThread + filename="glib/gthread.c" + line="823">a #GThread + + This function does nothing. + Thread priorities no longer have any effect. + + + + + + + a #GThread. + + + + ignored + + + + Decrease the reference count on @thread, possibly freeing all + filename="glib/gthread.c" + line="841">Decrease the reference count on @thread, possibly freeing all resources associated with it. Note that each thread holds a reference to its #GThread while it is running, so it is safe to drop your own reference to it if you don't need it anymore. - + a #GThread + filename="glib/gthread.c" + line="843">a #GThread + + This function creates a new thread. + +The new thread executes the function @func with the argument @data. +If the thread was created successfully, it is returned. + +@error can be %NULL to ignore errors, or non-%NULL to report errors. +The error is set, if and only if the function returns %NULL. + +This function returns a reference to the created thread only if +@joinable is %TRUE. In that case, you must free this reference by +calling g_thread_unref() or g_thread_join(). If @joinable is %FALSE +then you should probably not touch the return value. + Use g_thread_new() instead + + + the new #GThread on success + + + + + a function to execute in the new thread + + + + an argument to supply to the new thread + + + + should this thread be joinable? + + + + + + This function creates a new thread. + The @bound and @priority arguments are now ignored. +Use g_thread_new(). + + + the new #GThread on success. + + + + + a function to execute in the new thread. + + + + an argument to supply to the new thread. + + + + a stack size for the new thread. + + + + should this thread be joinable? + + + + ignored + + + + ignored + + + + @@ -42138,8 +45660,8 @@ if you don't need it anymore. Terminates the current thread. + filename="glib/gthread.c" + line="997">Terminates the current thread. If another thread is waiting for us using g_thread_join() then the waiting thread will be woken up and get @retval as the return value @@ -42152,7 +45674,7 @@ You must only call g_thread_exit() from a thread that you created yourself with g_thread_new() or related APIs. You must not call this function from a thread created with another threading library or or from within a #GThreadPool. - + @@ -42162,16 +45684,142 @@ or or from within a #GThreadPool. nullable="1" allow-none="1"> the return value of this thread + filename="glib/gthread.c" + line="999">the return value of this thread + + + + + + Call @thread_func on all #GThreads that have been +created with g_thread_create(). + +Note that threads may decide to exit while @thread_func is +running, so without intimate knowledge about the lifetime of +foreign threads, @thread_func shouldn't access the GThread* +pointer passed in as first argument. However, @thread_func will +not be called for threads which are known to have exited already. + +Due to thread lifetime checks, this function has an execution complexity +which is quadratic in the number of existing threads. + There aren't many things you can do with a #GThread, + except comparing it with one that was returned from g_thread_create(). + There are better ways to find out if your thread is still alive. + + + + + + + function to call for all #GThread structures + + + + second argument to @thread_func + + + + + + Indicates if g_thread_init() has been called. + + + %TRUE if threads have been initialized. + + + + + If you use GLib from more than one thread, you must initialize the +thread system by calling g_thread_init(). + +Since version 2.24, calling g_thread_init() multiple times is allowed, +but nothing happens except for the first call. + +Since version 2.32, GLib does not support custom thread implementations +anymore and the @vtable parameter is ignored and you should pass %NULL. + +::: note + g_thread_init() must not be called directly or indirectly in a + callback from GLib. Also no mutexes may be currently locked + while calling g_thread_init(). + +::: note + To use g_thread_init() in your program, you have to link with + the libraries that the command `pkg-config --libs gthread-2.0` + outputs. This is not the case for all the other thread-related + functions of GLib. Those can be used without having to link + with the thread libraries. + This function is no longer necessary. The GLib + threading system is automatically initialized at the start + of your program. + + + + + + + a function table of type #GThreadFunctions, that provides + the entry points to the thread system to be used. Since 2.32, + this parameter is ignored and should always be %NULL + + + + + + + + + + + This function returns the #GThread corresponding to the + filename="glib/gthread.c" + line="1072">This function returns the #GThread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct. @@ -42180,22 +45828,22 @@ were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as g_thread_join()) on these threads. - + the #GThread representing the current thread + filename="glib/gthread.c" + line="1085">the #GThread representing the current thread Causes the calling thread to voluntarily relinquish the CPU, so + filename="glib/gthread.c" + line="1919">Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run. This function is often used as a method to make busy wait less evil. - + @@ -42205,28 +45853,28 @@ This function is often used as a method to make busy wait less evil. c:type="GThreadError" glib:error-domain="g_thread_error"> Possible errors of thread related functions. - + filename="glib/gthread.c" + line="475">Possible errors of thread related functions. + a thread couldn't be created due to resource + filename="glib/gthread.c" + line="477">a thread couldn't be created due to resource shortage. Try again later. Specifies the type of the @func functions passed to g_thread_new() + filename="glib/gthread.c" + line="452">Specifies the type of the @func functions passed to g_thread_new() or g_thread_try_new(). - + the return value of the thread + filename="glib/gthread.c" + line="459">the return value of the thread @@ -42235,41 +45883,432 @@ or g_thread_try_new(). nullable="1" allow-none="1"> data passed to the thread + filename="glib/gthread.c" + line="454">data passed to the thread + + This function table is no longer used by g_thread_init() +to initialize the thread system. + + + virtual function pointer for g_mutex_new() + + + + + + + + + virtual function pointer for g_mutex_lock() + + + + + + + + + + + + + + virtual function pointer for g_mutex_trylock() + + + + + + + + + + + + + + virtual function pointer for g_mutex_unlock() + + + + + + + + + + + + + + virtual function pointer for g_mutex_free() + + + + + + + + + + + + + + virtual function pointer for g_cond_new() + + + + + + + + + virtual function pointer for g_cond_signal() + + + + + + + + + + + + + + virtual function pointer for g_cond_broadcast() + + + + + + + + + + + + + + virtual function pointer for g_cond_wait() + + + + + + + + + + + + + + + + + virtual function pointer for g_cond_timed_wait() + + + + + + + + + + + + + + + + + + + + virtual function pointer for g_cond_free() + + + + + + + + + + + + + + virtual function pointer for g_private_new() + + + + + + + + + + + + + + virtual function pointer for g_private_get() + + + + + + + + + + + + + + virtual function pointer for g_private_set() + + + + + + + + + + + + + + + + + virtual function pointer for g_thread_create() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + virtual function pointer for g_thread_yield() + + + + + + + + + virtual function pointer for g_thread_join() + + + + + + + + + + + + + + virtual function pointer for g_thread_exit() + + + + + + + + + virtual function pointer for + g_thread_set_priority() + + + + + + + + + + + + + + + + + virtual function pointer for g_thread_self() + + + + + + + + + + + + + + used internally by recursive mutex locks and by some + assertion checks + + + + + + + + + + + + + + + + The #GThreadPool struct represents a thread pool. It has three -public read-only members, but the underlying struct is bigger, -so you must not copy this struct. - + filename="glib/gthreadpool.c" + line="45">The `GThreadPool` struct represents a thread pool. + +A thread pool is useful when you wish to asynchronously fork out the execution of work +and continue working in your own thread. If that will happen often, the overhead of starting +and destroying a thread each time might be too high. In such cases reusing already started +threads seems like a good idea. And it indeed is, but implementing this can be tedious +and error-prone. + +Therefore GLib provides thread pools for your convenience. An added advantage is, that the +threads can be shared between the different subsystems of your program, when they are using GLib. + +To create a new thread pool, you use [func@GLib.ThreadPool.new]. +It is destroyed by [method@GLib.ThreadPool.free]. + +If you want to execute a certain task within a thread pool, use [method@GLib.ThreadPool.push]. + +To get the current number of running threads you call [method@GLib.ThreadPool.get_num_threads]. +To get the number of still unprocessed tasks you call [method@GLib.ThreadPool.unprocessed]. +To control the maximum number of threads for a thread pool, you use +[method@GLib.ThreadPool.get_max_threads]. and [method@GLib.ThreadPool.set_max_threads]. + +Finally you can control the number of unused threads, that are kept alive by GLib for future use. +The current number can be fetched with [func@GLib.ThreadPool.get_num_unused_threads]. +The maximum number can be controlled by [func@GLib.ThreadPool.get_max_unused_threads] and +[func@GLib.ThreadPool.set_max_unused_threads]. All currently unused threads +can be stopped by calling [func@GLib.ThreadPool.stop_unused_threads]. + the function to execute in the threads of this pool + filename="glib/gthreadpool.c" + line="47">the function to execute in the threads of this pool the user data for the threads of this pool + filename="glib/gthreadpool.c" + line="48">the user data for the threads of this pool are all threads exclusive to this pool + filename="glib/gthreadpool.c" + line="49">are all threads exclusive to this pool Frees all resources allocated for @pool. + filename="glib/gthreadpool.c" + line="866">Frees all resources allocated for @pool. If @immediate is %TRUE, no new task is processed for @pool. Otherwise @pool is not freed before the last task is processed. @@ -42283,27 +46322,27 @@ or only the currently running) are ready. Otherwise this function returns immediately. After calling this function @pool must not be used anymore. - + a #GThreadPool + filename="glib/gthreadpool.c" + line="868">a #GThreadPool should @pool shut down immediately? + filename="glib/gthreadpool.c" + line="869">should @pool shut down immediately? should the function wait for all tasks to be finished? + filename="glib/gthreadpool.c" + line="870">should the function wait for all tasks to be finished? @@ -42311,20 +46350,20 @@ After calling this function @pool must not be used anymore. Returns the maximal number of threads for @pool. - + filename="glib/gthreadpool.c" + line="790">Returns the maximal number of threads for @pool. + the maximal number of threads + filename="glib/gthreadpool.c" + line="796">the maximal number of threads a #GThreadPool + filename="glib/gthreadpool.c" + line="792">a #GThreadPool @@ -42332,20 +46371,20 @@ After calling this function @pool must not be used anymore. Returns the number of threads currently running in @pool. - + filename="glib/gthreadpool.c" + line="816">Returns the number of threads currently running in @pool. + the number of threads currently running + filename="glib/gthreadpool.c" + line="822">the number of threads currently running a #GThreadPool + filename="glib/gthreadpool.c" + line="818">a #GThreadPool @@ -42354,21 +46393,21 @@ After calling this function @pool must not be used anymore. c:identifier="g_thread_pool_move_to_front" version="2.46"> Moves the item to the front of the queue of unprocessed + filename="glib/gthreadpool.c" + line="1110">Moves the item to the front of the queue of unprocessed items, so that it will be processed next. - + %TRUE if the item was found and moved + filename="glib/gthreadpool.c" + line="1118">%TRUE if the item was found and moved a #GThreadPool + filename="glib/gthreadpool.c" + line="1112">a #GThreadPool nullable="1" allow-none="1"> an unprocessed item in the pool + filename="glib/gthreadpool.c" + line="1113">an unprocessed item in the pool Inserts @data into the list of tasks to be executed by @pool. + filename="glib/gthreadpool.c" + line="658">Inserts @data into the list of tasks to be executed by @pool. When the number of currently running threads is lower than the maximal allowed number of threads, a new thread is started (or @@ -42399,18 +46438,18 @@ created. In that case @data is simply appended to the queue of work to do. Before version 2.32, this function did not return a success status. - + %TRUE on success, %FALSE if an error occurred + filename="glib/gthreadpool.c" + line="679">%TRUE on success, %FALSE if an error occurred a #GThreadPool + filename="glib/gthreadpool.c" + line="660">a #GThreadPool nullable="1" allow-none="1"> a new task for @pool + filename="glib/gthreadpool.c" + line="661">a new task for @pool @@ -42428,8 +46467,8 @@ Before version 2.32, this function did not return a success status. c:identifier="g_thread_pool_set_max_threads" throws="1"> Sets the maximal allowed number of threads for @pool. + filename="glib/gthreadpool.c" + line="716">Sets the maximal allowed number of threads for @pool. A value of -1 means that the maximal number of threads is unlimited. If @pool is an exclusive thread pool, setting the maximal number of threads to -1 is not allowed. @@ -42449,24 +46488,24 @@ errors. An error can only occur when a new thread couldn't be created. Before version 2.32, this function did not return a success status. - + %TRUE on success, %FALSE if an error occurred + filename="glib/gthreadpool.c" + line="744">%TRUE on success, %FALSE if an error occurred a #GThreadPool + filename="glib/gthreadpool.c" + line="718">a #GThreadPool a new maximal number of threads for @pool, + filename="glib/gthreadpool.c" + line="719">a new maximal number of threads for @pool, or -1 for unlimited @@ -42477,8 +46516,8 @@ Before version 2.32, this function did not return a success status. version="2.10" introspectable="0"> Sets the function used to sort the list of tasks. This allows the + filename="glib/gthreadpool.c" + line="1062">Sets the function used to sort the list of tasks. This allows the tasks to be processed by a priority determined by @func, and not just in the order in which they were added to the pool. @@ -42487,21 +46526,21 @@ that threads are executed cannot be guaranteed 100%. Threads are scheduled by the operating system and are executed at random. It cannot be assumed that threads are executed in the order they are created. - + a #GThreadPool + filename="glib/gthreadpool.c" + line="1064">a #GThreadPool the #GCompareDataFunc used to sort the list of tasks. + filename="glib/gthreadpool.c" + line="1065">the #GCompareDataFunc used to sort the list of tasks. This function is passed two tasks. It should return 0 if the order in which they are handled does not matter, a negative value if the first task should be processed before @@ -42514,28 +46553,28 @@ created. nullable="1" allow-none="1"> user data passed to @func + filename="glib/gthreadpool.c" + line="1071">user data passed to @func Returns the number of tasks still unprocessed in @pool. - + filename="glib/gthreadpool.c" + line="842">Returns the number of tasks still unprocessed in @pool. + the number of unprocessed tasks + filename="glib/gthreadpool.c" + line="848">the number of unprocessed tasks a #GThreadPool + filename="glib/gthreadpool.c" + line="844">a #GThreadPool @@ -42544,18 +46583,18 @@ created. c:identifier="g_thread_pool_get_max_idle_time" version="2.10"> This function will return the maximum @interval that a + filename="glib/gthreadpool.c" + line="1181">This function will return the maximum @interval that a thread will wait in the thread pool for new tasks before being stopped. If this function returns 0, threads waiting in the thread pool for new work are not stopped. - + the maximum @interval (milliseconds) to wait + filename="glib/gthreadpool.c" + line="1191">the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread @@ -42564,26 +46603,26 @@ pool for new work are not stopped. Returns the maximal allowed number of unused threads. - + filename="glib/gthreadpool.c" + line="1018">Returns the maximal allowed number of unused threads. + the maximal number of unused threads + filename="glib/gthreadpool.c" + line="1023">the maximal number of unused threads Returns the number of currently unused threads. - + filename="glib/gthreadpool.c" + line="1031">Returns the number of currently unused threads. + the number of currently unused threads + filename="glib/gthreadpool.c" + line="1036">the number of currently unused threads @@ -42592,8 +46631,8 @@ pool for new work are not stopped. introspectable="0" throws="1"> This function creates a new thread pool. + filename="glib/gthreadpool.c" + line="488">This function creates a new thread pool. Whenever you call g_thread_pool_push(), either a new thread is created or an unused one is reused. At most @max_threads threads @@ -42633,18 +46672,18 @@ errors. An error can only occur when @exclusive is set to %TRUE and not all @max_threads threads could be created. See #GThreadError for possible errors that may occur. Note, even in case of error a valid #GThreadPool is returned. - + the new #GThreadPool + filename="glib/gthreadpool.c" + line="539">the new #GThreadPool a function to execute in the threads of the new thread pool + filename="glib/gthreadpool.c" + line="490">a function to execute in the threads of the new thread pool nullable="1" allow-none="1"> user data that is handed over to @func every time it + filename="glib/gthreadpool.c" + line="491">user data that is handed over to @func every time it is called the maximal number of threads to execute concurrently + filename="glib/gthreadpool.c" + line="493">the maximal number of threads to execute concurrently in the new thread pool, -1 means no limit should this thread pool be exclusive? + filename="glib/gthreadpool.c" + line="495">should this thread pool be exclusive? @@ -42678,19 +46717,19 @@ Note, even in case of error a valid #GThreadPool is returned. introspectable="0" throws="1"> This function creates a new thread pool similar to g_thread_pool_new() + filename="glib/gthreadpool.c" + line="551">This function creates a new thread pool similar to g_thread_pool_new() but allowing @item_free_func to be specified to free the data passed to g_thread_pool_push() in the case that the #GThreadPool is stopped and freed before all tasks have been executed. @item_free_func will *not* be called on items successfully passed to @func. @func is responsible for freeing the items passed to it. - + the new #GThreadPool + filename="glib/gthreadpool.c" + line="571">the new #GThreadPool @@ -42700,8 +46739,8 @@ and freed before all tasks have been executed. closure="1" destroy="2"> a function to execute in the threads of the new thread pool + filename="glib/gthreadpool.c" + line="553">a function to execute in the threads of the new thread pool user data that is handed over to @func every time it + filename="glib/gthreadpool.c" + line="554">user data that is handed over to @func every time it is called @@ -42720,22 +46759,22 @@ and freed before all tasks have been executed. allow-none="1" scope="async"> used to pass as a free function to + filename="glib/gthreadpool.c" + line="556">used to pass as a free function to g_async_queue_new_full() the maximal number of threads to execute concurrently + filename="glib/gthreadpool.c" + line="558">the maximal number of threads to execute concurrently in the new thread pool, `-1` means no limit should this thread pool be exclusive? + filename="glib/gthreadpool.c" + line="560">should this thread pool be exclusive? @@ -42744,8 +46783,8 @@ and freed before all tasks have been executed. c:identifier="g_thread_pool_set_max_idle_time" version="2.10"> This function will set the maximum @interval that a thread + filename="glib/gthreadpool.c" + line="1140">This function will set the maximum @interval that a thread waiting in the pool for new tasks can be idle for before being stopped. This function is similar to calling g_thread_pool_stop_unused_threads() on a regular timeout, @@ -42754,15 +46793,15 @@ except this is done on a per thread basis. By setting @interval to 0, idle threads will not be stopped. The default value is 15000 (15 seconds). - + the maximum @interval (in milliseconds) + filename="glib/gthreadpool.c" + line="1142">the maximum @interval (in milliseconds) a thread can be idle @@ -42771,21 +46810,21 @@ The default value is 15000 (15 seconds). Sets the maximal number of unused threads to @max_threads. + filename="glib/gthreadpool.c" + line="979">Sets the maximal number of unused threads to @max_threads. If @max_threads is -1, no limit is imposed on the number of unused threads. -The default value is 2. - +The default value is 8 since GLib 2.84. Previously the default value was 2. + maximal number of unused threads + filename="glib/gthreadpool.c" + line="981">maximal number of unused threads @@ -42793,19 +46832,50 @@ The default value is 2. Stops all currently unused threads. This does not change the + filename="glib/gthreadpool.c" + line="1044">Stops all currently unused threads. This does not change the maximal number of unused threads. This function can be used to regularly stop all unused threads e.g. from g_timeout_add(). - + + + Thread priorities. + Thread priorities no longer have any effect. + + + a priority lower than normal + + + the default priority + + + a priority higher than normal + + + the highest priority + + Disambiguates a given time in two ways. First, specifies if the given time is in universal or local time. @@ -42814,20 +46884,20 @@ Second, if the time is in local time, specifies if it is local standard time or local daylight time. This is important for the case where the same local time occurs twice (during daylight savings time transitions, for example). - + the time is in local standard time the time is in local daylight time the time is in UTC @@ -42836,8 +46906,8 @@ transitions, for example). deprecated="1" deprecated-version="2.62"> Represents a precise time, with seconds and microseconds. + filename="glib/gdate.c" + line="121">Represents a precise time, with seconds and microseconds. Similar to the struct timeval returned by the `gettimeofday()` UNIX system call. @@ -42848,17 +46918,17 @@ removed from a future version of GLib. A consequence of using `glong` for `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038 problem. Use #GDateTime or #guint64 instead. - + seconds + filename="glib/gdate.c" + line="123">seconds microseconds + filename="glib/gdate.c" + line="124">microseconds deprecated="1" deprecated-version="2.62"> Adds the given number of microseconds to @time_. @microseconds can + filename="glib/gtimer.c" + line="280">Adds the given number of microseconds to @time_. @microseconds can also be negative to decrease the value of @time_. #GTimeVal is not year-2038-safe. Use `guint64` for representing microseconds since the epoch, or use #GDateTime. - + a #GTimeVal + filename="glib/gtimer.c" + line="282">a #GTimeVal number of microseconds to add to @time + filename="glib/gtimer.c" + line="283">number of microseconds to add to @time @@ -42896,8 +46966,8 @@ also be negative to decrease the value of @time_. deprecated="1" deprecated-version="2.62"> Converts @time_ into an RFC 3339 encoded string, relative to the + filename="glib/gtimer.c" + line="549">Converts @time_ into an RFC 3339 encoded string, relative to the Coordinated Universal Time (UTC). This is one of the many formats allowed by ISO 8601. @@ -42933,19 +47003,19 @@ The return value of g_time_val_to_iso8601() has been nullable since GLib 2.54; before then, GLib would crash under the same conditions. #GTimeVal is not year-2038-safe. Use g_date_time_format_iso8601(dt) instead. - + a newly allocated string containing an ISO 8601 date, + filename="glib/gtimer.c" + line="588">a newly allocated string containing an ISO 8601 date, or %NULL if @time_ was too large a #GTimeVal + filename="glib/gtimer.c" + line="551">a #GTimeVal @@ -42956,8 +47026,8 @@ The return value of g_time_val_to_iso8601() has been nullable since GLib deprecated="1" deprecated-version="2.62"> Converts a string containing an ISO 8601 encoded date and time + filename="glib/gtimer.c" + line="357">Converts a string containing an ISO 8601 encoded date and time to a #GTimeVal and puts it into @time_. @iso_date must include year, month, day, hours, minutes, and @@ -42976,18 +47046,18 @@ g_date_time_unref (dt); ]| #GTimeVal is not year-2038-safe. Use g_date_time_new_from_iso8601() instead. - + %TRUE if the conversion was successful. + filename="glib/gtimer.c" + line="380">%TRUE if the conversion was successful. an ISO 8601 encoded date string + filename="glib/gtimer.c" + line="359">an ISO 8601 encoded date string a #GTimeVal + filename="glib/gtimer.c" + line="360">a #GTimeVal @@ -43010,18 +47080,42 @@ g_date_time_unref (dt); glib:get-type="g_time_zone_get_type" c:symbol-prefix="time_zone"> #GTimeZone is an opaque structure whose members cannot be accessed -directly. - + filename="glib/gtimezone.c" + line="53">A `GTimeZone` represents a time zone, at no particular point in time. + +The `GTimeZone` struct is refcounted and immutable. + +Each time zone has an identifier (for example, ‘Europe/London’) which is +platform dependent. See [ctor@GLib.TimeZone.new] for information on the +identifier formats. The identifier of a time zone can be retrieved using +[method@GLib.TimeZone.get_identifier]. + +A time zone contains a number of intervals. Each interval has an abbreviation +to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating +if the daylight savings time is in effect during that interval. A time zone +always has at least one interval — interval 0. Note that interval abbreviations +are not the same as time zone identifiers (apart from ‘UTC’), and cannot be +passed to [ctor@GLib.TimeZone.new]. + +Every UTC time is contained within exactly one interval, but a given +local time may be contained within zero, one or two intervals (due to +incontinuities associated with daylight savings time). + +An interval may refer to a specific period of time (eg: the duration +of daylight savings time during 2010) or it may refer to many periods +of time that share the same properties (eg: all periods of daylight +savings time). It is also possible (usually for political reasons) +that some properties (like the abbreviation) change between intervals +without other properties changing. + A version of g_time_zone_new_identifier() which returns the UTC time zone + filename="glib/gtimezone.c" + line="1725">A version of g_time_zone_new_identifier() which returns the UTC time zone if @identifier could not be parsed or loaded. If you need to check whether @identifier was loaded successfully, use @@ -43029,11 +47123,11 @@ g_time_zone_new_identifier(). Use g_time_zone_new_identifier() instead, as it provides error reporting. Change your code to handle a potentially %NULL return value. - + the requested timezone + filename="glib/gtimezone.c" + line="1735">the requested timezone @@ -43042,8 +47136,8 @@ g_time_zone_new_identifier(). nullable="1" allow-none="1"> a timezone identifier + filename="glib/gtimezone.c" + line="1727">a timezone identifier @@ -43052,8 +47146,8 @@ g_time_zone_new_identifier(). c:identifier="g_time_zone_new_identifier" version="2.68"> Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be + filename="glib/gtimezone.c" + line="1756">Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be parsed or loaded, %NULL is returned. @identifier can either be an RFC3339/ISO 8601 time offset or @@ -43118,11 +47212,11 @@ for the list of time zones on Windows. You should release the return value by calling g_time_zone_unref() when you are done with it. - + the requested timezone, or %NULL on + filename="glib/gtimezone.c" + line="1826">the requested timezone, or %NULL on failure @@ -43132,8 +47226,8 @@ when you are done with it. nullable="1" allow-none="1"> a timezone identifier + filename="glib/gtimezone.c" + line="1758">a timezone identifier @@ -43142,8 +47236,8 @@ when you are done with it. c:identifier="g_time_zone_new_local" version="2.26"> Creates a #GTimeZone corresponding to local time. The local time + filename="glib/gtimezone.c" + line="2011">Creates a #GTimeZone corresponding to local time. The local time zone may change between invocations to this function; for example, if the system administrator changes it. @@ -43152,11 +47246,11 @@ the `TZ` environment variable (including the possibility of %NULL). You should release the return value by calling g_time_zone_unref() when you are done with it. - + the local timezone + filename="glib/gtimezone.c" + line="2024">the local timezone @@ -43164,8 +47258,8 @@ when you are done with it. c:identifier="g_time_zone_new_offset" version="2.58"> Creates a #GTimeZone corresponding to the given constant offset from UTC, + filename="glib/gtimezone.c" + line="2052">Creates a #GTimeZone corresponding to the given constant offset from UTC, in seconds. This is equivalent to calling g_time_zone_new() with a string in the form @@ -43175,19 +47269,19 @@ It is possible for this function to fail if @seconds is too big (greater than 24 hours), in which case this function will return the UTC timezone for backwards compatibility. To detect failures like this, use g_time_zone_new_identifier() directly. - + a timezone at the given offset from UTC, or UTC on + filename="glib/gtimezone.c" + line="2067">a timezone at the given offset from UTC, or UTC on failure offset to UTC, in seconds + filename="glib/gtimezone.c" + line="2054">offset to UTC, in seconds @@ -43196,19 +47290,19 @@ g_time_zone_new_identifier() directly. c:identifier="g_time_zone_new_utc" version="2.26"> Creates a #GTimeZone corresponding to UTC. + filename="glib/gtimezone.c" + line="1980">Creates a #GTimeZone corresponding to UTC. This is equivalent to calling g_time_zone_new() with a value like "Z", "UTC", "+00", etc. You should release the return value by calling g_time_zone_unref() when you are done with it. - + the universal timezone + filename="glib/gtimezone.c" + line="1991">the universal timezone @@ -43216,8 +47310,8 @@ when you are done with it. c:identifier="g_time_zone_adjust_time" version="2.26"> Finds an interval within @tz that corresponds to the given @time_, + filename="glib/gtimezone.c" + line="2213">Finds an interval within @tz that corresponds to the given @time_, possibly adjusting @time_ if required to fit into an interval. The meaning of @time_ depends on @type. @@ -43233,24 +47327,24 @@ non-existent times. If the non-existent local @time_ of 02:30 were requested on March 14th 2010 in Toronto then this function would adjust @time_ to be 03:00 and return the interval containing the adjusted time. - + the interval containing @time_, never -1 + filename="glib/gtimezone.c" + line="2236">the interval containing @time_, never -1 a #GTimeZone + filename="glib/gtimezone.c" + line="2215">a #GTimeZone the #GTimeType of @time_ + filename="glib/gtimezone.c" + line="2216">the #GTimeType of @time_ caller-allocates="0" transfer-ownership="full"> a pointer to a number of seconds since January 1, 1970 + filename="glib/gtimezone.c" + line="2217">a pointer to a number of seconds since January 1, 1970 @@ -43268,8 +47362,8 @@ adjusted time. c:identifier="g_time_zone_find_interval" version="2.26"> Finds an interval within @tz that corresponds to the given @time_. + filename="glib/gtimezone.c" + line="2309">Finds an interval within @tz that corresponds to the given @time_. The meaning of @time_ depends on @type. If @type is %G_TIME_TYPE_UNIVERSAL then this function will always @@ -43287,30 +47381,30 @@ It is still possible for this function to fail. In Toronto, for example, 02:00 on March 14th 2010 does not exist (due to the leap forward to begin daylight savings time). -1 is returned in that case. - + the interval containing @time_, or -1 in case of failure + filename="glib/gtimezone.c" + line="2334">the interval containing @time_, or -1 in case of failure a #GTimeZone + filename="glib/gtimezone.c" + line="2311">a #GTimeZone the #GTimeType of @time_ + filename="glib/gtimezone.c" + line="2312">the #GTimeType of @time_ a number of seconds since January 1, 1970 + filename="glib/gtimezone.c" + line="2313">a number of seconds since January 1, 1970 @@ -43319,31 +47413,31 @@ case. c:identifier="g_time_zone_get_abbreviation" version="2.26"> Determines the time zone abbreviation to be used during a particular + filename="glib/gtimezone.c" + line="2387">Determines the time zone abbreviation to be used during a particular @interval of time in the time zone @tz. For example, in Toronto this is currently "EST" during the winter months and "EDT" during the summer months when daylight savings time is in effect. - + the time zone abbreviation, which belongs to @tz + filename="glib/gtimezone.c" + line="2399">the time zone abbreviation, which belongs to @tz a #GTimeZone + filename="glib/gtimezone.c" + line="2389">a #GTimeZone an interval within the timezone + filename="glib/gtimezone.c" + line="2390">an interval within the timezone @@ -43352,8 +47446,8 @@ is in effect. c:identifier="g_time_zone_get_identifier" version="2.58"> Get the identifier of this #GTimeZone, as passed to g_time_zone_new(). + filename="glib/gtimezone.c" + line="2462">Get the identifier of this #GTimeZone, as passed to g_time_zone_new(). If the identifier passed at construction time was not recognised, `UTC` will be returned. If it was %NULL, the identifier of the local timezone at construction time will be returned. @@ -43361,18 +47455,18 @@ construction time will be returned. The identifier will be returned in the same format as provided at construction time: if provided as a time offset, that will be returned by this function. - + identifier for this timezone + filename="glib/gtimezone.c" + line="2475">identifier for this timezone a #GTimeZone + filename="glib/gtimezone.c" + line="2464">a #GTimeZone @@ -43381,96 +47475,96 @@ this function. c:identifier="g_time_zone_get_offset" version="2.26"> Determines the offset to UTC in effect during a particular @interval + filename="glib/gtimezone.c" + line="2412">Determines the offset to UTC in effect during a particular @interval of time in the time zone @tz. The offset is the number of seconds that you add to UTC time to arrive at local time for @tz (ie: negative numbers for time zones west of GMT, positive numbers for east). - + the number of seconds that should be added to UTC to get the + filename="glib/gtimezone.c" + line="2424">the number of seconds that should be added to UTC to get the local time in @tz a #GTimeZone + filename="glib/gtimezone.c" + line="2414">a #GTimeZone an interval within the timezone + filename="glib/gtimezone.c" + line="2415">an interval within the timezone Determines if daylight savings time is in effect during a particular + filename="glib/gtimezone.c" + line="2438">Determines if daylight savings time is in effect during a particular @interval of time in the time zone @tz. - + %TRUE if daylight savings time is in effect + filename="glib/gtimezone.c" + line="2446">%TRUE if daylight savings time is in effect a #GTimeZone + filename="glib/gtimezone.c" + line="2440">a #GTimeZone an interval within the timezone + filename="glib/gtimezone.c" + line="2441">an interval within the timezone Increases the reference count on @tz. - + filename="glib/gtimezone.c" + line="268">Increases the reference count on @tz. + a new reference to @tz. + filename="glib/gtimezone.c" + line="274">a new reference to @tz. a #GTimeZone + filename="glib/gtimezone.c" + line="270">a #GTimeZone Decreases the reference count on @tz. - + filename="glib/gtimezone.c" + line="209">Decreases the reference count on @tz. + a #GTimeZone + filename="glib/gtimezone.c" + line="211">a #GTimeZone @@ -43478,73 +47572,77 @@ west of GMT, positive numbers for east). Opaque datatype that records a start time. - + filename="glib/gtimer.c" + line="59">`GTimer` records a start time, and counts microseconds elapsed since +that time. + +This is done somewhat differently on different platforms, and can be +tricky to get exactly right, so `GTimer` provides a portable/convenient interface. + Resumes a timer that has previously been stopped with + filename="glib/gtimer.c" + line="163">Resumes a timer that has previously been stopped with g_timer_stop(). g_timer_stop() must be called before using this function. - + a #GTimer. + filename="glib/gtimer.c" + line="165">a #GTimer. Destroys a timer, freeing associated resources. - + filename="glib/gtimer.c" + line="97">Destroys a timer, freeing associated resources. + a #GTimer to destroy. + filename="glib/gtimer.c" + line="99">a #GTimer to destroy. If @timer has been started but not stopped, obtains the time since + filename="glib/gtimer.c" + line="195">If @timer has been started but not stopped, obtains the time since the timer was started. If @timer has been stopped, obtains the elapsed time between the time it was started and the time it was stopped. The return value is the number of seconds elapsed, including any fractional part. The @microseconds out parameter is essentially useless. - + seconds elapsed as a floating point value, including any + filename="glib/gtimer.c" + line="209">seconds elapsed as a floating point value, including any fractional part. a #GTimer. + filename="glib/gtimer.c" + line="197">a #GTimer. return location for the fractional part of seconds + filename="glib/gtimer.c" + line="198">return location for the fractional part of seconds elapsed, in microseconds (that is, the total number of microseconds elapsed, modulo 1000000), or %NULL @@ -43553,312 +47651,312 @@ essentially useless. Exposes whether the timer is currently active. - + filename="glib/gtimer.c" + line="234">Exposes whether the timer is currently active. + %TRUE if the timer is running, %FALSE otherwise + filename="glib/gtimer.c" + line="240">%TRUE if the timer is running, %FALSE otherwise a #GTimer. + filename="glib/gtimer.c" + line="236">a #GTimer. This function is useless; it's fine to call g_timer_start() on an + filename="glib/gtimer.c" + line="147">This function is useless; it's fine to call g_timer_start() on an already-started timer to reset the start time, so g_timer_reset() serves no purpose. - + a #GTimer. + filename="glib/gtimer.c" + line="149">a #GTimer. Marks a start time, so that future calls to g_timer_elapsed() will + filename="glib/gtimer.c" + line="111">Marks a start time, so that future calls to g_timer_elapsed() will report the time since g_timer_start() was called. g_timer_new() automatically marks the start time, so no need to call g_timer_start() immediately after creating the timer. - + a #GTimer. + filename="glib/gtimer.c" + line="113">a #GTimer. Marks an end time, so calls to g_timer_elapsed() will return the + filename="glib/gtimer.c" + line="130">Marks an end time, so calls to g_timer_elapsed() will return the difference between this end time and the start time. - + a #GTimer. + filename="glib/gtimer.c" + line="132">a #GTimer. Creates a new timer, and starts timing (i.e. g_timer_start() is + filename="glib/gtimer.c" + line="76">Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly called for you). - - + + a new #GTimer. + filename="glib/gtimer.c" + line="82">a new #GTimer. The possible types of token returned from each + filename="glib/gscanner.c" + line="109">The possible types of token returned from each g_scanner_get_next_token() call. - + the end of the file + filename="glib/gscanner.c" + line="111">the end of the file a '(' character + filename="glib/gscanner.c" + line="112">a '(' character a ')' character + filename="glib/gscanner.c" + line="116">a ')' character a '{' character + filename="glib/gscanner.c" + line="113">a '{' character a '}' character + filename="glib/gscanner.c" + line="115">a '}' character a '[' character + filename="glib/gscanner.c" + line="114">a '[' character a ']' character + filename="glib/gscanner.c" + line="117">a ']' character a '=' character + filename="glib/gscanner.c" + line="118">a '=' character a ',' character + filename="glib/gscanner.c" + line="119">a ',' character not a token + filename="glib/gscanner.c" + line="120">not a token an error occurred + filename="glib/gscanner.c" + line="121">an error occurred a character + filename="glib/gscanner.c" + line="122">a character a binary integer + filename="glib/gscanner.c" + line="123">a binary integer an octal integer + filename="glib/gscanner.c" + line="124">an octal integer an integer + filename="glib/gscanner.c" + line="125">an integer a hex integer + filename="glib/gscanner.c" + line="126">a hex integer a floating point number + filename="glib/gscanner.c" + line="127">a floating point number a string + filename="glib/gscanner.c" + line="128">a string a symbol + filename="glib/gscanner.c" + line="129">a symbol an identifier + filename="glib/gscanner.c" + line="130">an identifier a null identifier + filename="glib/gscanner.c" + line="131">a null identifier one line comment + filename="glib/gscanner.c" + line="132">one line comment multi line comment + filename="glib/gscanner.c" + line="133">multi line comment A union holding the value of the token. - + filename="glib/gscanner.c" + line="139">A union holding the value of the token. + token symbol value + filename="glib/gscanner.c" + line="141">token symbol value token identifier value + filename="glib/gscanner.c" + line="142">token identifier value token binary integer value + filename="glib/gscanner.c" + line="143">token binary integer value octal integer value + filename="glib/gscanner.c" + line="144">octal integer value integer value + filename="glib/gscanner.c" + line="145">integer value 64-bit integer value + filename="glib/gscanner.c" + line="146">64-bit integer value floating point value + filename="glib/gscanner.c" + line="147">floating point value hex integer value + filename="glib/gscanner.c" + line="148">hex integer value string value + filename="glib/gscanner.c" + line="149">string value comment value + filename="glib/gscanner.c" + line="150">comment value character value + filename="glib/gscanner.c" + line="151">character value error value + filename="glib/gscanner.c" + line="152">error value The type of functions which are used to translate user-visible strings, for <option>--help</option> output. - + a translation of the string for the current locale. The returned string is owned by GLib and must not be freed. @@ -43866,7 +47964,7 @@ strings, for <option>--help</option> output. the untranslated string @@ -43875,7 +47973,7 @@ strings, for <option>--help</option> output. nullable="1" allow-none="1"> user data specified when installing the function, e.g. in g_option_group_set_translate_func() @@ -43887,15 +47985,26 @@ strings, for <option>--help</option> output. deprecated="1" deprecated-version="2.48"> Each piece of memory that is pushed onto the stack -is cast to a GTrashStack*. - #GTrashStack is deprecated without replacement - + filename="glib/gtrashstack.c" + line="36">A `GTrashStack` is an efficient way to keep a stack of unused allocated +memory chunks. Each memory chunk is required to be large enough to hold +a `gpointer`. This allows the stack to be maintained without any space +overhead, since the stack pointers can be stored inside the memory chunks. + +There is no function to create a `GTrashStack`. A `NULL` `GTrashStack*` +is a perfectly valid empty stack. + +Each piece of memory that is pushed onto the stack is cast to a +`GTrashStack*`. + +There is no longer any good reason to use `GTrashStack`. If you have +extra pieces of memory, `free()` them and allocate them again later. + `GTrashStack` is deprecated without replacement + pointer to the previous element of the stack, + filename="glib/gtrashstack.c" + line="38">pointer to the previous element of the stack, gets stored in the first `sizeof (gpointer)` bytes of the element @@ -43905,24 +48014,24 @@ is cast to a GTrashStack*. deprecated="1" deprecated-version="2.48"> Returns the height of a #GTrashStack. + filename="glib/gtrashstack.c" + line="124">Returns the height of a #GTrashStack. Note that execution of this function is of O(N) complexity where N denotes the number of items on the stack. #GTrashStack is deprecated without replacement - + the height of the stack + filename="glib/gtrashstack.c" + line="133">the height of the stack a #GTrashStack + filename="glib/gtrashstack.c" + line="126">a #GTrashStack @@ -43932,22 +48041,22 @@ where N denotes the number of items on the stack. deprecated="1" deprecated-version="2.48"> Returns the element at the top of a #GTrashStack + filename="glib/gtrashstack.c" + line="104">Returns the element at the top of a #GTrashStack which may be %NULL. #GTrashStack is deprecated without replacement - + the element at the top of the stack + filename="glib/gtrashstack.c" + line="111">the element at the top of the stack a #GTrashStack + filename="glib/gtrashstack.c" + line="106">a #GTrashStack @@ -43957,21 +48066,21 @@ which may be %NULL. deprecated="1" deprecated-version="2.48"> Pops a piece of memory off a #GTrashStack. + filename="glib/gtrashstack.c" + line="77">Pops a piece of memory off a #GTrashStack. #GTrashStack is deprecated without replacement - + the element at the top of the stack + filename="glib/gtrashstack.c" + line="83">the element at the top of the stack a #GTrashStack + filename="glib/gtrashstack.c" + line="79">a #GTrashStack @@ -43981,24 +48090,24 @@ which may be %NULL. deprecated="1" deprecated-version="2.48"> Pushes a piece of memory onto a #GTrashStack. + filename="glib/gtrashstack.c" + line="59">Pushes a piece of memory onto a #GTrashStack. #GTrashStack is deprecated without replacement - + a #GTrashStack + filename="glib/gtrashstack.c" + line="61">a #GTrashStack the piece of memory to push on the stack + filename="glib/gtrashstack.c" + line="62">the piece of memory to push on the stack @@ -44006,57 +48115,57 @@ which may be %NULL. Specifies which nodes are visited during several of the tree + filename="glib/gnode.c" + line="837">Specifies which nodes are visited during several of the tree functions, including g_node_traverse() and g_node_find(). - + only leaf nodes should be visited. This name has + filename="glib/gnode.c" + line="839">only leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_LEAFS. only non-leaf nodes should be visited. This + filename="glib/gnode.c" + line="842">only non-leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_NON_LEAFS. all nodes should be visited. + filename="glib/gnode.c" + line="845">all nodes should be visited. a mask of all traverse flags. + filename="glib/gnode.c" + line="846">a mask of all traverse flags. identical to %G_TRAVERSE_LEAVES. + filename="glib/gnode.c" + line="847">identical to %G_TRAVERSE_LEAVES. identical to %G_TRAVERSE_NON_LEAVES. + filename="glib/gnode.c" + line="848">identical to %G_TRAVERSE_NON_LEAVES. Specifies the type of function passed to g_tree_traverse(). It is + filename="glib/gtree.c" + line="1202">Specifies the type of function passed to g_tree_traverse(). It is passed the key and value of each node, together with the @user_data parameter passed to g_tree_traverse(). If the function returns %TRUE, the traversal is stopped. - + %TRUE to stop the traversal + filename="glib/gtree.c" + line="1213">%TRUE to stop the traversal @@ -44065,8 +48174,8 @@ parameter passed to g_tree_traverse(). If the function returns nullable="1" allow-none="1"> a key of a #GTree node + filename="glib/gtree.c" + line="1204">a key of a #GTree node the value corresponding to the key + filename="glib/gtree.c" + line="1205">the value corresponding to the key user data passed to g_tree_traverse() + filename="glib/gtree.c" + line="1206">user data passed to g_tree_traverse() @@ -44093,22 +48202,22 @@ parameter passed to g_tree_traverse(). If the function returns c:type="GTraverseNodeFunc" version="2.68"> Specifies the type of function passed to g_tree_foreach_node(). It is passed each node, together with the @user_data parameter passed to g_tree_foreach_node(). If the function returns %TRUE, the traversal is stopped. - + %TRUE to stop the traversal a #GTreeNode @@ -44117,7 +48226,7 @@ stopped. nullable="1" allow-none="1"> user data passed to g_tree_foreach_node() @@ -44125,44 +48234,66 @@ stopped. Specifies the type of traversal performed by g_tree_traverse(), -g_node_traverse() and g_node_find(). The different orders are -illustrated here: + filename="glib/gnode.c" + line="787">Specifies the type of traversal performed by g_tree_traverse(), +g_node_traverse() and g_node_find(). + +The different orders are illustrated here: + - In order: A, B, C, D, E, F, G, H, I - ![](Sorted_binary_tree_inorder.svg) + <picture> + <source srcset="Sorted_binary_tree_inorder-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_inorder.svg" + alt="Sorted binary tree, in-order traversal"> + </picture> - Pre order: F, B, A, D, C, E, G, I, H - ![](Sorted_binary_tree_preorder.svg) + <picture> + <source srcset="Sorted_binary_tree_preorder-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_preorder.svg" + alt="Sorted binary tree, pre-order traversal"> + </picture> - Post order: A, C, E, D, B, H, I, G, F - ![](Sorted_binary_tree_postorder.svg) + <picture> + <source srcset="Sorted_binary_tree_postorder-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_postorder.svg" + alt="Sorted binary tree, post-order traversal"> + </picture> - Level order: F, B, G, A, D, I, C, E, H - ![](Sorted_binary_tree_breadth-first_traversal.svg) - + <picture> + <source srcset="Sorted_binary_tree_breadth-first_traversal-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_breadth-first_traversal.svg" + alt="Sorted binary tree, breadth-first level order traversal"> + </picture> + vists a node's left child first, then the node itself, + filename="glib/gnode.c" + line="789">visits a node's left child first, then the node itself, then its right child. This is the one to use if you want the output sorted according to the compare function. visits a node, then its children. + filename="glib/gnode.c" + line="793">visits a node, then its children. visits the node's children, then the node itself. + filename="glib/gnode.c" + line="794">visits the node's children, then the node itself. is not implemented for - [balanced binary trees][glib-Balanced-Binary-Trees]. - For [n-ary trees][glib-N-ary-Trees], it - vists the root node first, then its children, then + filename="glib/gnode.c" + line="795">is not implemented for + [balanced binary trees](data-structures.html#binary-trees). + For [n-ary trees](data-structures.html#n-ary-trees), it + visits the root node first, then its children, then its grandchildren, and so on. Note that this is less efficient than the other orders. @@ -44174,27 +48305,27 @@ illustrated here: glib:get-type="g_tree_get_type" c:symbol-prefix="tree"> The GTree struct is an opaque data structure representing a -[balanced binary tree][glib-Balanced-Binary-Trees]. It should be + filename="glib/gtree.c" + line="43">The GTree struct is an opaque data structure representing a +[balanced binary tree](data-structures.html#binary-trees). It should be accessed only by using the following functions. - + Creates a new #GTree. - + filename="glib/gtree.c" + line="122">Creates a new #GTree. + a newly allocated #GTree + filename="glib/gtree.c" + line="132">a newly allocated #GTree the function used to order the nodes in the #GTree. + filename="glib/gtree.c" + line="124">the function used to order the nodes in the #GTree. It should return values similar to the standard strcmp() function - 0 if the two arguments are equal, a negative value if the first argument comes before the second, or a positive value if the first argument comes @@ -44205,15 +48336,15 @@ accessed only by using the following functions. Creates a new #GTree like g_tree_new() and allows to specify functions + filename="glib/gtree.c" + line="163">Creates a new #GTree like g_tree_new() and allows to specify functions to free the memory allocated for the key and value that get called when removing the entry from the #GTree. - + a newly allocated #GTree + filename="glib/gtree.c" + line="178">a newly allocated #GTree @@ -44223,8 +48354,8 @@ removing the entry from the #GTree. closure="1" destroy="3"> qsort()-style comparison function + filename="glib/gtree.c" + line="165">qsort()-style comparison function nullable="1" allow-none="1"> data to pass to comparison function + filename="glib/gtree.c" + line="166">data to pass to comparison function a function to free the memory allocated for the key + filename="glib/gtree.c" + line="167">a function to free the memory allocated for the key used when removing the entry from the #GTree or %NULL if you don't want to supply such a function @@ -44250,8 +48381,8 @@ removing the entry from the #GTree. transfer-ownership="none" scope="async"> a function to free the memory allocated for the + filename="glib/gtree.c" + line="170">a function to free the memory allocated for the value used when removing the entry from the #GTree or %NULL if you don't want to supply such a function @@ -44262,14 +48393,14 @@ removing the entry from the #GTree. c:identifier="g_tree_new_with_data" introspectable="0"> Creates a new #GTree with a comparison function that accepts user data. + filename="glib/gtree.c" + line="143">Creates a new #GTree with a comparison function that accepts user data. See g_tree_new() for more details. - + a newly allocated #GTree + filename="glib/gtree.c" + line="151">a newly allocated #GTree @@ -44277,8 +48408,8 @@ See g_tree_new() for more details. transfer-ownership="none" closure="1"> qsort()-style comparison function + filename="glib/gtree.c" + line="145">qsort()-style comparison function nullable="1" allow-none="1"> data to pass to comparison function + filename="glib/gtree.c" + line="146">data to pass to comparison function Removes all keys and values from the #GTree and decreases its + filename="glib/gtree.c" + line="408">Removes all keys and values from the #GTree and decreases its reference count by one. If keys and/or values are dynamically allocated, you should either free them first or create the #GTree using g_tree_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values before destroying the #GTree. - + a #GTree + filename="glib/gtree.c" + line="410">a #GTree - + Calls the given function for each of the key/value pairs in the #GTree. + filename="glib/gtree.c" + line="1106">Calls the given function for each of the key/value pairs in the #GTree. The function is passed the key and value of each pair, and the given @data parameter. The tree is traversed in sorted order. @@ -44325,21 +48456,24 @@ The tree may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, you need to add each item to a list in your #GTraverseFunc as you walk over the tree, then walk the list and remove each item. - + a #GTree + filename="glib/gtree.c" + line="1108">a #GTree - + the function to call for each node visited. + filename="glib/gtree.c" + line="1109">the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. @@ -44348,19 +48482,18 @@ the tree, then walk the list and remove each item. nullable="1" allow-none="1"> user data to pass to the function + filename="glib/gtree.c" + line="1111">user data to pass to the function + version="2.68"> Calls the given function for each of the nodes in the #GTree. + filename="glib/gtree.c" + line="1145">Calls the given function for each of the nodes in the #GTree. The function is passed the pointer to the particular node, and the given @data parameter. The tree traversal happens in-order. @@ -44368,21 +48501,24 @@ The tree may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, you need to add each item to a list in your #GTraverseFunc as you walk over the tree, then walk the list and remove each item. - + a #GTree + filename="glib/gtree.c" + line="1147">a #GTree - + the function to call for each node visited. + filename="glib/gtree.c" + line="1148">the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. @@ -44391,52 +48527,52 @@ the tree, then walk the list and remove each item. nullable="1" allow-none="1"> user data to pass to the function + filename="glib/gtree.c" + line="1150">user data to pass to the function Gets the height of a #GTree. + filename="glib/gtree.c" + line="1419">Gets the height of a #GTree. If the #GTree contains no nodes, the height is 0. If the #GTree contains only one root node the height is 1. If the root node has children the height is 2, etc. - + the height of @tree + filename="glib/gtree.c" + line="1429">the height of @tree a #GTree + filename="glib/gtree.c" + line="1421">a #GTree Inserts a key/value pair into a #GTree. + filename="glib/gtree.c" + line="481">Inserts a key/value pair into a #GTree. Inserts a new key and value into a #GTree as g_tree_insert_node() does, only this function does not return the inserted or set node. - + a #GTree + filename="glib/gtree.c" + line="483">a #GTree nullable="1" allow-none="1"> the key to insert + filename="glib/gtree.c" + line="484">the key to insert nullable="1" allow-none="1"> the value corresponding to the key + filename="glib/gtree.c" + line="485">the value corresponding to the key @@ -44463,8 +48599,8 @@ only this function does not return the inserted or set node. c:identifier="g_tree_insert_node" version="2.68"> Inserts a key/value pair into a #GTree. + filename="glib/gtree.c" + line="448">Inserts a key/value pair into a #GTree. If the given key already exists in the #GTree its corresponding value is set to the new value. If you supplied a @value_destroy_func when @@ -44477,19 +48613,19 @@ so that the distance from the root to every leaf is as small as possible. The cost of maintaining a balanced tree while inserting new key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)). - + the inserted (or set) node or %NULL + filename="glib/gtree.c" + line="468">the inserted (or set) node or %NULL if insertion would overflow the tree node counter. a #GTree + filename="glib/gtree.c" + line="450">a #GTree nullable="1" allow-none="1"> the key to insert + filename="glib/gtree.c" + line="451">the key to insert nullable="1" allow-none="1"> the value corresponding to the key + filename="glib/gtree.c" + line="452">the value corresponding to the key Gets the value corresponding to the given key. Since a #GTree is + filename="glib/gtree.c" + line="1045">Gets the value corresponding to the given key. Since a #GTree is automatically balanced as key/value pairs are added, key lookup is O(log n) (where n is the number of key/value pairs in the tree). - + the value corresponding to the key, or %NULL + filename="glib/gtree.c" + line="1054">the value corresponding to the key, or %NULL if the key was not found a #GTree + filename="glib/gtree.c" + line="1047">a #GTree nullable="1" allow-none="1"> the key to look up + filename="glib/gtree.c" + line="1048">the key to look up Looks up a key in the #GTree, returning the original key and the + filename="glib/gtree.c" + line="1068">Looks up a key in the #GTree, returning the original key and the associated value. This is useful if you need to free the memory allocated for the original key, for example before calling g_tree_remove(). - + %TRUE if the key was found in the #GTree + filename="glib/gtree.c" + line="1080">%TRUE if the key was found in the #GTree a #GTree + filename="glib/gtree.c" + line="1070">a #GTree nullable="1" allow-none="1"> the key to look up + filename="glib/gtree.c" + line="1071">the key to look up optional="1" allow-none="1"> returns the original key + filename="glib/gtree.c" + line="1072">returns the original key optional="1" allow-none="1"> returns the value associated with the key + filename="glib/gtree.c" + line="1073">returns the value associated with the key @@ -44604,23 +48740,23 @@ g_tree_remove(). c:identifier="g_tree_lookup_node" version="2.68"> Gets the tree node corresponding to the given key. Since a #GTree is + filename="glib/gtree.c" + line="1022">Gets the tree node corresponding to the given key. Since a #GTree is automatically balanced as key/value pairs are added, key lookup is O(log n) (where n is the number of key/value pairs in the tree). - + the tree node corresponding to + filename="glib/gtree.c" + line="1031">the tree node corresponding to the key, or %NULL if the key was not found a #GTree + filename="glib/gtree.c" + line="1024">a #GTree nullable="1" allow-none="1"> the key to look up + filename="glib/gtree.c" + line="1025">the key to look up @@ -44638,18 +48774,18 @@ is O(log n) (where n is the number of key/value pairs in the tree). c:identifier="g_tree_lower_bound" version="2.68"> Gets the lower bound node corresponding to the given key, + filename="glib/gtree.c" + line="1311">Gets the lower bound node corresponding to the given key, or %NULL if the tree is empty or all the nodes in the tree have keys that are strictly lower than the searched key. The lower bound is the first node that has its key greater than or equal to the searched key. - + the tree node corresponding to + filename="glib/gtree.c" + line="1323">the tree node corresponding to the lower bound, or %NULL if the tree is empty or has only keys strictly lower than the searched key. @@ -44657,8 +48793,8 @@ than or equal to the searched key. a #GTree + filename="glib/gtree.c" + line="1313">a #GTree nullable="1" allow-none="1"> the key to calculate the lower bound for + filename="glib/gtree.c" + line="1314">the key to calculate the lower bound for Gets the number of nodes in a #GTree. - + filename="glib/gtree.c" + line="1456">Gets the number of nodes in a #GTree. + the number of nodes in @tree + filename="glib/gtree.c" + line="1462">the number of nodes in @tree The node counter value type is really a #guint, but it is returned as a #gint due to backward @@ -44691,8 +48827,8 @@ support its full range of values). a #GTree + filename="glib/gtree.c" + line="1458">a #GTree @@ -44701,72 +48837,72 @@ support its full range of values). c:identifier="g_tree_node_first" version="2.68"> Returns the first in-order node of the tree, or %NULL + filename="glib/gtree.c" + line="202">Returns the first in-order node of the tree, or %NULL for an empty tree. - + the first node in the tree + filename="glib/gtree.c" + line="209">the first node in the tree a #GTree + filename="glib/gtree.c" + line="204">a #GTree Returns the last in-order node of the tree, or %NULL + filename="glib/gtree.c" + line="231">Returns the last in-order node of the tree, or %NULL for an empty tree. - + the last node in the tree + filename="glib/gtree.c" + line="238">the last node in the tree a #GTree + filename="glib/gtree.c" + line="233">a #GTree Increments the reference count of @tree by one. + filename="glib/gtree.c" + line="361">Increments the reference count of @tree by one. It is safe to call this function from any thread. - + the passed in #GTree + filename="glib/gtree.c" + line="369">the passed in #GTree a #GTree + filename="glib/gtree.c" + line="363">a #GTree Removes a key/value pair from a #GTree. + filename="glib/gtree.c" + line="713">Removes a key/value pair from a #GTree. If the #GTree was created using g_tree_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to @@ -44776,19 +48912,19 @@ If the key does not exist in the #GTree, the function does nothing. The cost of maintaining a balanced tree while removing a key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)). - + %TRUE if the key was found (prior to 2.8, this function + filename="glib/gtree.c" + line="729">%TRUE if the key was found (prior to 2.8, this function returned nothing) a #GTree + filename="glib/gtree.c" + line="715">a #GTree nullable="1" allow-none="1"> the key to remove + filename="glib/gtree.c" + line="716">the key to remove @@ -44806,36 +48942,36 @@ are O(log(n)). c:identifier="g_tree_remove_all" version="2.70"> Removes all nodes from a #GTree and destroys their keys and values, + filename="glib/gtree.c" + line="314">Removes all nodes from a #GTree and destroys their keys and values, then resets the #GTree’s root to %NULL. - + a #GTree + filename="glib/gtree.c" + line="316">a #GTree Inserts a new key and value into a #GTree as g_tree_replace_node() does, + filename="glib/gtree.c" + line="529">Inserts a new key and value into a #GTree as g_tree_replace_node() does, only this function does not return the inserted or set node. - + a #GTree + filename="glib/gtree.c" + line="531">a #GTree nullable="1" allow-none="1"> the key to insert + filename="glib/gtree.c" + line="532">the key to insert nullable="1" allow-none="1"> the value corresponding to the key + filename="glib/gtree.c" + line="533">the value corresponding to the key @@ -44862,8 +48998,8 @@ only this function does not return the inserted or set node. c:identifier="g_tree_replace_node" version="2.68"> Inserts a new key and value into a #GTree similar to g_tree_insert_node(). + filename="glib/gtree.c" + line="500">Inserts a new key and value into a #GTree similar to g_tree_insert_node(). The difference is that if the key already exists in the #GTree, it gets replaced by the new key. If you supplied a @value_destroy_func when creating the #GTree, the old value is freed using that function. If you @@ -44872,19 +49008,19 @@ freed using that function. The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible. - + the inserted (or set) node or %NULL + filename="glib/gtree.c" + line="516">the inserted (or set) node or %NULL if insertion would overflow the tree node counter. a #GTree + filename="glib/gtree.c" + line="502">a #GTree nullable="1" allow-none="1"> the key to insert + filename="glib/gtree.c" + line="503">the key to insert nullable="1" allow-none="1"> the value corresponding to the key + filename="glib/gtree.c" + line="504">the value corresponding to the key - + Searches a #GTree using @search_func. + filename="glib/gtree.c" + line="1280">Searches a #GTree using @search_func. The @search_func is called with a pointer to the key of a key/value pair in the tree, and the passed in @user_data. If @search_func returns @@ -44919,25 +49055,28 @@ the result of g_tree_search(). If @search_func returns -1, searching will proceed among the key/value pairs that have a smaller key; if @search_func returns 1, searching will proceed among the key/value pairs that have a larger key. - + the value corresponding to the found key, or %NULL + filename="glib/gtree.c" + line="1296">the value corresponding to the found key, or %NULL if the key was not found a #GTree + filename="glib/gtree.c" + line="1282">a #GTree - + a function used to search the #GTree + filename="glib/gtree.c" + line="1283">a function used to search the #GTree nullable="1" allow-none="1"> the data passed as the second argument to @search_func + filename="glib/gtree.c" + line="1284">the data passed as the second argument to @search_func + version="2.68"> Searches a #GTree using @search_func. + filename="glib/gtree.c" + line="1246">Searches a #GTree using @search_func. The @search_func is called with a pointer to the key of a key/value pair in the tree, and the passed in @user_data. If @search_func returns @@ -44966,25 +49104,28 @@ the result of g_tree_search(). If @search_func returns -1, searching will proceed among the key/value pairs that have a smaller key; if @search_func returns 1, searching will proceed among the key/value pairs that have a larger key. - + the node corresponding to the + filename="glib/gtree.c" + line="1262">the node corresponding to the found key, or %NULL if the key was not found a #GTree + filename="glib/gtree.c" + line="1248">a #GTree - + a function used to search the #GTree + filename="glib/gtree.c" + line="1249">a function used to search the #GTree nullable="1" allow-none="1"> the data passed as the second argument to @search_func + filename="glib/gtree.c" + line="1250">the data passed as the second argument to @search_func Removes a key and its associated value from a #GTree without calling + filename="glib/gtree.c" + line="749">Removes a key and its associated value from a #GTree without calling the key and value destroy functions. If the key does not exist in the #GTree, the function does nothing. - + %TRUE if the key was found (prior to 2.8, this function + filename="glib/gtree.c" + line="759">%TRUE if the key was found (prior to 2.8, this function returned nothing) a #GTree + filename="glib/gtree.c" + line="751">a #GTree nullable="1" allow-none="1"> the key to remove + filename="glib/gtree.c" + line="752">the key to remove Calls the given function for each node in the #GTree. + filename="glib/gtree.c" + line="1186">Calls the given function for each node in the #GTree. The order of a balanced tree is somewhat arbitrary. If you just want to visit all nodes in sorted order, use g_tree_foreach() instead. If you really need to visit nodes in - a different order, consider using an [n-ary tree][glib-N-ary-Trees]. - + a different order, consider using an [n-ary tree](data-structures.html#n-ary-trees). + a #GTree + filename="glib/gtree.c" + line="1188">a #GTree the function to call for each node visited. If this + filename="glib/gtree.c" + line="1189">the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. the order in which nodes are visited, one of %G_IN_ORDER, + filename="glib/gtree.c" + line="1191">the order in which nodes are visited, one of %G_IN_ORDER, %G_PRE_ORDER and %G_POST_ORDER @@ -45075,30 +49216,30 @@ If the key does not exist in the #GTree, the function does nothing. nullable="1" allow-none="1"> user data to pass to the function + filename="glib/gtree.c" + line="1193">user data to pass to the function Decrements the reference count of @tree by one. + filename="glib/gtree.c" + line="383">Decrements the reference count of @tree by one. If the reference count drops to 0, all keys and values will be destroyed (if destroy functions were specified) and all memory allocated by @tree will be released. It is safe to call this function from any thread. - + a #GTree + filename="glib/gtree.c" + line="385">a #GTree @@ -45107,18 +49248,18 @@ It is safe to call this function from any thread. c:identifier="g_tree_upper_bound" version="2.68"> Gets the upper bound node corresponding to the given key, + filename="glib/gtree.c" + line="1365">Gets the upper bound node corresponding to the given key, or %NULL if the tree is empty or all the nodes in the tree have keys that are lower than or equal to the searched key. The upper bound is the first node that has its key strictly greater than the searched key. - + the tree node corresponding to the + filename="glib/gtree.c" + line="1377">the tree node corresponding to the upper bound, or %NULL if the tree is empty or has only keys lower than or equal to the searched key. @@ -45126,8 +49267,8 @@ than the searched key. a #GTree + filename="glib/gtree.c" + line="1367">a #GTree nullable="1" allow-none="1"> the key to calculate the upper bound for + filename="glib/gtree.c" + line="1368">the key to calculate the upper bound for @@ -45148,46 +49289,46 @@ than the searched key. opaque="1" version="2.68"> An opaque type which identifies a specific node in a #GTree. - + Gets the key stored at a particular tree node. - + filename="glib/gtree.c" + line="986">Gets the key stored at a particular tree node. + the key at the node. + filename="glib/gtree.c" + line="992">the key at the node. a #GTree node + filename="glib/gtree.c" + line="988">a #GTree node Returns the next in-order node of the tree, or %NULL + filename="glib/gtree.c" + line="287">Returns the next in-order node of the tree, or %NULL if the passed node was already the last one. - + the next node in the tree + filename="glib/gtree.c" + line="294">the next node in the tree a #GTree node + filename="glib/gtree.c" + line="289">a #GTree node @@ -45196,50 +49337,131 @@ if the passed node was already the last one. c:identifier="g_tree_node_previous" version="2.68"> Returns the previous in-order node of the tree, or %NULL + filename="glib/gtree.c" + line="260">Returns the previous in-order node of the tree, or %NULL if the passed node was already the first one. - + the previous node in the tree + filename="glib/gtree.c" + line="267">the previous node in the tree a #GTree node + filename="glib/gtree.c" + line="262">a #GTree node Gets the value stored at a particular tree node. - + filename="glib/gtree.c" + line="1004">Gets the value stored at a particular tree node. + the value at the node. + filename="glib/gtree.c" + line="1010">the value at the node. a #GTree node + filename="glib/gtree.c" + line="1006">a #GTree node + + The #GTuples struct is used to return records (or tuples) from the +#GRelation by g_relation_select(). It only contains one public +member - the number of records that matched. To access the matched +records, you must use g_tuples_index(). + Rarely used API + + + the number of records that matched. + + + + Frees the records which were returned by g_relation_select(). This +should always be called after g_relation_select() when you are +finished with the records. The records are not removed from the +#GRelation. + Rarely used API + + + + + + + the tuple data to free. + + + + + + Gets a field from the records returned by g_relation_select(). It +returns the given field of the record at the given index. The +returned value should not be changed. + Rarely used API + + + the field of the record. + + + + + the tuple data, returned by g_relation_select(). + + + + the index of the record. + + + + the field to return. + + + + + - + @@ -45250,7 +49472,7 @@ if the passed node was already the first one. - + @@ -45261,7 +49483,7 @@ if the passed node was already the first one. - + @@ -45272,7 +49494,7 @@ if the passed node was already the first one. - + @@ -45283,7 +49505,7 @@ if the passed node was already the first one. - + @@ -45296,12 +49518,12 @@ if the passed node was already the first one. c:type="G_UNICHAR_MAX_DECOMPOSITION_LENGTH" version="2.32"> The maximum length (in codepoints) of a compatibility or canonical + filename="glib/gunicode.h" + line="781">The maximum length (in codepoints) of a compatibility or canonical decomposition of a single Unicode character. This is as defined by Unicode 6.1. - + version="2.2" introspectable="0"> Hints the compiler that the expression is unlikely to evaluate to + filename="glib/docs.c" + line="1477">Hints the compiler that the expression is unlikely to evaluate to a true value. The compiler may use this information for optimizations. |[<!-- language="C" --> if (G_UNLIKELY (random () == 1)) g_print ("a random one"); ]| - + the expression + filename="glib/docs.c" + line="1479">the expression Works like g_mutex_unlock(), but for a lock defined with + filename="glib/gthread.c" + line="194">Works like g_mutex_unlock(), but for a lock defined with %G_LOCK_DEFINE. - + the name of the lock + filename="glib/gthread.c" + line="196">the name of the lock @@ -45345,10 +49567,10 @@ if (G_UNLIKELY (random () == 1)) c:type="G_URI_RESERVED_CHARS_GENERIC_DELIMITERS" version="2.16"> Generic delimiters characters as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`. - + Subcomponent delimiter characters as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`. - + Number of microseconds in one second (1 million). + filename="glib/gdate.c" + line="114">Number of microseconds in one second (1 million). This macro is provided for code readability. - + - + These are the possible line break classifications. -Since new unicode versions may add new types here, applications should be ready +Since new Unicode versions may add new types here, applications should be ready to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN. See [Unicode Line Breaking Algorithm](https://www.unicode.org/reports/tr14/). - + c:identifier="G_UNICODE_BREAK_MANDATORY" + glib:nick="mandatory" + glib:name="G_UNICODE_BREAK_MANDATORY"> Mandatory Break (BK) + c:identifier="G_UNICODE_BREAK_CARRIAGE_RETURN" + glib:nick="carriage-return" + glib:name="G_UNICODE_BREAK_CARRIAGE_RETURN"> Carriage Return (CR) + c:identifier="G_UNICODE_BREAK_LINE_FEED" + glib:nick="line-feed" + glib:name="G_UNICODE_BREAK_LINE_FEED"> Line Feed (LF) + c:identifier="G_UNICODE_BREAK_COMBINING_MARK" + glib:nick="combining-mark" + glib:name="G_UNICODE_BREAK_COMBINING_MARK"> Attached Characters and Combining Marks (CM) + c:identifier="G_UNICODE_BREAK_SURROGATE" + glib:nick="surrogate" + glib:name="G_UNICODE_BREAK_SURROGATE"> Surrogates (SG) + c:identifier="G_UNICODE_BREAK_ZERO_WIDTH_SPACE" + glib:nick="zero-width-space" + glib:name="G_UNICODE_BREAK_ZERO_WIDTH_SPACE"> Zero Width Space (ZW) + c:identifier="G_UNICODE_BREAK_INSEPARABLE" + glib:nick="inseparable" + glib:name="G_UNICODE_BREAK_INSEPARABLE"> Inseparable (IN) + c:identifier="G_UNICODE_BREAK_NON_BREAKING_GLUE" + glib:nick="non-breaking-glue" + glib:name="G_UNICODE_BREAK_NON_BREAKING_GLUE"> Non-breaking ("Glue") (GL) + c:identifier="G_UNICODE_BREAK_CONTINGENT" + glib:nick="contingent" + glib:name="G_UNICODE_BREAK_CONTINGENT"> Contingent Break Opportunity (CB) - + Space (SP) - + Break Opportunity After (BA) - + Break Opportunity Before (BB) + c:identifier="G_UNICODE_BREAK_BEFORE_AND_AFTER" + glib:nick="before-and-after" + glib:name="G_UNICODE_BREAK_BEFORE_AND_AFTER"> Break Opportunity Before and After (B2) - + Hyphen (HY) + c:identifier="G_UNICODE_BREAK_NON_STARTER" + glib:nick="non-starter" + glib:name="G_UNICODE_BREAK_NON_STARTER"> Nonstarter (NS) + c:identifier="G_UNICODE_BREAK_OPEN_PUNCTUATION" + glib:nick="open-punctuation" + glib:name="G_UNICODE_BREAK_OPEN_PUNCTUATION"> Opening Punctuation (OP) + c:identifier="G_UNICODE_BREAK_CLOSE_PUNCTUATION" + glib:nick="close-punctuation" + glib:name="G_UNICODE_BREAK_CLOSE_PUNCTUATION"> Closing Punctuation (CL) + c:identifier="G_UNICODE_BREAK_QUOTATION" + glib:nick="quotation" + glib:name="G_UNICODE_BREAK_QUOTATION"> Ambiguous Quotation (QU) + c:identifier="G_UNICODE_BREAK_EXCLAMATION" + glib:nick="exclamation" + glib:name="G_UNICODE_BREAK_EXCLAMATION"> Exclamation/Interrogation (EX) + c:identifier="G_UNICODE_BREAK_IDEOGRAPHIC" + glib:nick="ideographic" + glib:name="G_UNICODE_BREAK_IDEOGRAPHIC"> Ideographic (ID) - + Numeric (NU) + c:identifier="G_UNICODE_BREAK_INFIX_SEPARATOR" + glib:nick="infix-separator" + glib:name="G_UNICODE_BREAK_INFIX_SEPARATOR"> Infix Separator (Numeric) (IS) - + Symbols Allowing Break After (SY) + c:identifier="G_UNICODE_BREAK_ALPHABETIC" + glib:nick="alphabetic" + glib:name="G_UNICODE_BREAK_ALPHABETIC"> Ordinary Alphabetic and Symbol Characters (AL) - + Prefix (Numeric) (PR) - + Postfix (Numeric) (PO) + c:identifier="G_UNICODE_BREAK_COMPLEX_CONTEXT" + glib:nick="complex-context" + glib:name="G_UNICODE_BREAK_COMPLEX_CONTEXT"> Complex Content Dependent (South East Asian) (SA) + c:identifier="G_UNICODE_BREAK_AMBIGUOUS" + glib:nick="ambiguous" + glib:name="G_UNICODE_BREAK_AMBIGUOUS"> Ambiguous (Alphabetic or Ideographic) (AI) - + Unknown (XX) + c:identifier="G_UNICODE_BREAK_NEXT_LINE" + glib:nick="next-line" + glib:name="G_UNICODE_BREAK_NEXT_LINE"> Next Line (NL) + c:identifier="G_UNICODE_BREAK_WORD_JOINER" + glib:nick="word-joiner" + glib:name="G_UNICODE_BREAK_WORD_JOINER"> Word Joiner (WJ) + c:identifier="G_UNICODE_BREAK_HANGUL_L_JAMO" + glib:nick="hangul-l-jamo" + glib:name="G_UNICODE_BREAK_HANGUL_L_JAMO"> Hangul L Jamo (JL) + c:identifier="G_UNICODE_BREAK_HANGUL_V_JAMO" + glib:nick="hangul-v-jamo" + glib:name="G_UNICODE_BREAK_HANGUL_V_JAMO"> Hangul V Jamo (JV) + c:identifier="G_UNICODE_BREAK_HANGUL_T_JAMO" + glib:nick="hangul-t-jamo" + glib:name="G_UNICODE_BREAK_HANGUL_T_JAMO"> Hangul T Jamo (JT) + c:identifier="G_UNICODE_BREAK_HANGUL_LV_SYLLABLE" + glib:nick="hangul-lv-syllable" + glib:name="G_UNICODE_BREAK_HANGUL_LV_SYLLABLE"> Hangul LV Syllable (H2) + c:identifier="G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE" + glib:nick="hangul-lvt-syllable" + glib:name="G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE"> Hangul LVT Syllable (H3) + c:identifier="G_UNICODE_BREAK_CLOSE_PARANTHESIS" + glib:nick="close-paranthesis" + glib:name="G_UNICODE_BREAK_CLOSE_PARANTHESIS"> Closing Parenthesis (CP). Since 2.28. Deprecated: 2.70: Use %G_UNICODE_BREAK_CLOSE_PARENTHESIS instead. + c:identifier="G_UNICODE_BREAK_CLOSE_PARENTHESIS" + glib:nick="close-parenthesis" + glib:name="G_UNICODE_BREAK_CLOSE_PARENTHESIS"> Closing Parenthesis (CP). Since 2.70 + c:identifier="G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER" + glib:nick="conditional-japanese-starter" + glib:name="G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER"> Conditional Japanese Starter (CJ). Since: 2.32 + c:identifier="G_UNICODE_BREAK_HEBREW_LETTER" + glib:nick="hebrew-letter" + glib:name="G_UNICODE_BREAK_HEBREW_LETTER"> Hebrew Letter (HL). Since: 2.32 + c:identifier="G_UNICODE_BREAK_REGIONAL_INDICATOR" + glib:nick="regional-indicator" + glib:name="G_UNICODE_BREAK_REGIONAL_INDICATOR"> Regional Indicator (RI). Since: 2.36 + c:identifier="G_UNICODE_BREAK_EMOJI_BASE" + glib:nick="emoji-base" + glib:name="G_UNICODE_BREAK_EMOJI_BASE"> Emoji Base (EB). Since: 2.50 + c:identifier="G_UNICODE_BREAK_EMOJI_MODIFIER" + glib:nick="emoji-modifier" + glib:name="G_UNICODE_BREAK_EMOJI_MODIFIER"> Emoji Modifier (EM). Since: 2.50 + c:identifier="G_UNICODE_BREAK_ZERO_WIDTH_JOINER" + glib:nick="zero-width-joiner" + glib:name="G_UNICODE_BREAK_ZERO_WIDTH_JOINER"> Zero Width Joiner (ZWJ). Since: 2.50 + + Aksara (AK). Since: 2.80 + + + Aksara Pre-Base (AP). Since: 2.80 + + + Aksara Start (AS). Since: 2.80 + + + Virama Final (VF). Since: 2.80 + + + Virama (VI). Since: 2.80 + - + The #GUnicodeScript enumeration identifies different writing + filename="glib/gunicode.h" + line="273">The #GUnicodeScript enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. The enumeration has been added in GLib 2.14, and is interchangeable with #PangoScript. @@ -45682,1242 +50060,1932 @@ and is interchangeable with #PangoScript. Note that new types may be added in the future. Applications should be ready to handle unknown values. See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr24/). - + c:identifier="G_UNICODE_SCRIPT_INVALID_CODE" + glib:nick="invalid-code" + glib:name="G_UNICODE_SCRIPT_INVALID_CODE"> a value never returned from g_unichar_get_script() + filename="glib/gunicode.h" + line="275">a value never returned from g_unichar_get_script() - + a character used by multiple different scripts + filename="glib/gunicode.h" + line="277">a character used by multiple different scripts + c:identifier="G_UNICODE_SCRIPT_INHERITED" + glib:nick="inherited" + glib:name="G_UNICODE_SCRIPT_INHERITED"> a mark glyph that takes its script from the + filename="glib/gunicode.h" + line="278">a mark glyph that takes its script from the base glyph to which it is attached - - Arabic + + Arabic + c:identifier="G_UNICODE_SCRIPT_ARMENIAN" + glib:nick="armenian" + glib:name="G_UNICODE_SCRIPT_ARMENIAN"> Armenian + filename="glib/gunicode.h" + line="281">Armenian - + Bengali + filename="glib/gunicode.h" + line="282">Bengali + c:identifier="G_UNICODE_SCRIPT_BOPOMOFO" + glib:nick="bopomofo" + glib:name="G_UNICODE_SCRIPT_BOPOMOFO"> Bopomofo + filename="glib/gunicode.h" + line="283">Bopomofo + c:identifier="G_UNICODE_SCRIPT_CHEROKEE" + glib:nick="cherokee" + glib:name="G_UNICODE_SCRIPT_CHEROKEE"> Cherokee + filename="glib/gunicode.h" + line="284">Cherokee - - Coptic + + Coptic + c:identifier="G_UNICODE_SCRIPT_CYRILLIC" + glib:nick="cyrillic" + glib:name="G_UNICODE_SCRIPT_CYRILLIC"> Cyrillic + filename="glib/gunicode.h" + line="286">Cyrillic - + Deseret + filename="glib/gunicode.h" + line="287">Deseret + c:identifier="G_UNICODE_SCRIPT_DEVANAGARI" + glib:nick="devanagari" + glib:name="G_UNICODE_SCRIPT_DEVANAGARI"> Devanagari + filename="glib/gunicode.h" + line="288">Devanagari + c:identifier="G_UNICODE_SCRIPT_ETHIOPIC" + glib:nick="ethiopic" + glib:name="G_UNICODE_SCRIPT_ETHIOPIC"> Ethiopic + filename="glib/gunicode.h" + line="289">Ethiopic + c:identifier="G_UNICODE_SCRIPT_GEORGIAN" + glib:nick="georgian" + glib:name="G_UNICODE_SCRIPT_GEORGIAN"> Georgian + filename="glib/gunicode.h" + line="290">Georgian - - Gothic + + Gothic - - Greek + + Greek + c:identifier="G_UNICODE_SCRIPT_GUJARATI" + glib:nick="gujarati" + glib:name="G_UNICODE_SCRIPT_GUJARATI"> Gujarati + filename="glib/gunicode.h" + line="293">Gujarati + c:identifier="G_UNICODE_SCRIPT_GURMUKHI" + glib:nick="gurmukhi" + glib:name="G_UNICODE_SCRIPT_GURMUKHI"> Gurmukhi + filename="glib/gunicode.h" + line="294">Gurmukhi - - Han + + Han - - Hangul + + Hangul - - Hebrew + + Hebrew + c:identifier="G_UNICODE_SCRIPT_HIRAGANA" + glib:nick="hiragana" + glib:name="G_UNICODE_SCRIPT_HIRAGANA"> Hiragana + filename="glib/gunicode.h" + line="298">Hiragana + c:identifier="G_UNICODE_SCRIPT_KANNADA" + glib:nick="kannada" + glib:name="G_UNICODE_SCRIPT_KANNADA"> Kannada + filename="glib/gunicode.h" + line="299">Kannada + c:identifier="G_UNICODE_SCRIPT_KATAKANA" + glib:nick="katakana" + glib:name="G_UNICODE_SCRIPT_KATAKANA"> Katakana + filename="glib/gunicode.h" + line="300">Katakana - - Khmer + + Khmer - - Lao + + Lao - - Latin + + Latin + c:identifier="G_UNICODE_SCRIPT_MALAYALAM" + glib:nick="malayalam" + glib:name="G_UNICODE_SCRIPT_MALAYALAM"> Malayalam + filename="glib/gunicode.h" + line="304">Malayalam + c:identifier="G_UNICODE_SCRIPT_MONGOLIAN" + glib:nick="mongolian" + glib:name="G_UNICODE_SCRIPT_MONGOLIAN"> Mongolian + filename="glib/gunicode.h" + line="305">Mongolian + c:identifier="G_UNICODE_SCRIPT_MYANMAR" + glib:nick="myanmar" + glib:name="G_UNICODE_SCRIPT_MYANMAR"> Myanmar + filename="glib/gunicode.h" + line="306">Myanmar - - Ogham + + Ogham + c:identifier="G_UNICODE_SCRIPT_OLD_ITALIC" + glib:nick="old-italic" + glib:name="G_UNICODE_SCRIPT_OLD_ITALIC"> Old Italic + filename="glib/gunicode.h" + line="308">Old Italic - - Oriya + + Oriya - - Runic + + Runic + c:identifier="G_UNICODE_SCRIPT_SINHALA" + glib:nick="sinhala" + glib:name="G_UNICODE_SCRIPT_SINHALA"> Sinhala + filename="glib/gunicode.h" + line="311">Sinhala - - Syriac + + Syriac - - Tamil + + Tamil - - Telugu + + Telugu - - Thaana + + Thaana - - Thai + + Thai + c:identifier="G_UNICODE_SCRIPT_TIBETAN" + glib:nick="tibetan" + glib:name="G_UNICODE_SCRIPT_TIBETAN"> Tibetan + filename="glib/gunicode.h" + line="317">Tibetan + c:identifier="G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL" + glib:nick="canadian-aboriginal" + glib:name="G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL"> Canadian Aboriginal + filename="glib/gunicode.h" + line="318">Canadian Aboriginal - - Yi + + Yi + c:identifier="G_UNICODE_SCRIPT_TAGALOG" + glib:nick="tagalog" + glib:name="G_UNICODE_SCRIPT_TAGALOG"> Tagalog + filename="glib/gunicode.h" + line="321">Tagalog + c:identifier="G_UNICODE_SCRIPT_HANUNOO" + glib:nick="hanunoo" + glib:name="G_UNICODE_SCRIPT_HANUNOO"> Hanunoo + filename="glib/gunicode.h" + line="322">Hanunoo - - Buhid + + Buhid + c:identifier="G_UNICODE_SCRIPT_TAGBANWA" + glib:nick="tagbanwa" + glib:name="G_UNICODE_SCRIPT_TAGBANWA"> Tagbanwa + filename="glib/gunicode.h" + line="324">Tagbanwa + c:identifier="G_UNICODE_SCRIPT_BRAILLE" + glib:nick="braille" + glib:name="G_UNICODE_SCRIPT_BRAILLE"> Braille + filename="glib/gunicode.h" + line="325">Braille + c:identifier="G_UNICODE_SCRIPT_CYPRIOT" + glib:nick="cypriot" + glib:name="G_UNICODE_SCRIPT_CYPRIOT"> Cypriot + filename="glib/gunicode.h" + line="326">Cypriot - - Limbu + + Limbu + c:identifier="G_UNICODE_SCRIPT_OSMANYA" + glib:nick="osmanya" + glib:name="G_UNICODE_SCRIPT_OSMANYA"> Osmanya + filename="glib/gunicode.h" + line="328">Osmanya + c:identifier="G_UNICODE_SCRIPT_SHAVIAN" + glib:nick="shavian" + glib:name="G_UNICODE_SCRIPT_SHAVIAN"> Shavian + filename="glib/gunicode.h" + line="329">Shavian + c:identifier="G_UNICODE_SCRIPT_LINEAR_B" + glib:nick="linear-b" + glib:name="G_UNICODE_SCRIPT_LINEAR_B"> Linear B + filename="glib/gunicode.h" + line="330">Linear B - - Tai Le + + Tai Le + c:identifier="G_UNICODE_SCRIPT_UGARITIC" + glib:nick="ugaritic" + glib:name="G_UNICODE_SCRIPT_UGARITIC"> Ugaritic + filename="glib/gunicode.h" + line="332">Ugaritic + c:identifier="G_UNICODE_SCRIPT_NEW_TAI_LUE" + glib:nick="new-tai-lue" + glib:name="G_UNICODE_SCRIPT_NEW_TAI_LUE"> New Tai Lue + filename="glib/gunicode.h" + line="333">New Tai Lue + c:identifier="G_UNICODE_SCRIPT_BUGINESE" + glib:nick="buginese" + glib:name="G_UNICODE_SCRIPT_BUGINESE"> Buginese + filename="glib/gunicode.h" + line="335">Buginese + c:identifier="G_UNICODE_SCRIPT_GLAGOLITIC" + glib:nick="glagolitic" + glib:name="G_UNICODE_SCRIPT_GLAGOLITIC"> Glagolitic + filename="glib/gunicode.h" + line="336">Glagolitic + c:identifier="G_UNICODE_SCRIPT_TIFINAGH" + glib:nick="tifinagh" + glib:name="G_UNICODE_SCRIPT_TIFINAGH"> Tifinagh + filename="glib/gunicode.h" + line="337">Tifinagh + c:identifier="G_UNICODE_SCRIPT_SYLOTI_NAGRI" + glib:nick="syloti-nagri" + glib:name="G_UNICODE_SCRIPT_SYLOTI_NAGRI"> Syloti Nagri + filename="glib/gunicode.h" + line="338">Syloti Nagri + c:identifier="G_UNICODE_SCRIPT_OLD_PERSIAN" + glib:nick="old-persian" + glib:name="G_UNICODE_SCRIPT_OLD_PERSIAN"> Old Persian + filename="glib/gunicode.h" + line="340">Old Persian + c:identifier="G_UNICODE_SCRIPT_KHAROSHTHI" + glib:nick="kharoshthi" + glib:name="G_UNICODE_SCRIPT_KHAROSHTHI"> Kharoshthi + filename="glib/gunicode.h" + line="342">Kharoshthi + c:identifier="G_UNICODE_SCRIPT_UNKNOWN" + glib:nick="unknown" + glib:name="G_UNICODE_SCRIPT_UNKNOWN"> an unassigned code point + filename="glib/gunicode.h" + line="343">an unassigned code point + c:identifier="G_UNICODE_SCRIPT_BALINESE" + glib:nick="balinese" + glib:name="G_UNICODE_SCRIPT_BALINESE"> Balinese + filename="glib/gunicode.h" + line="344">Balinese + c:identifier="G_UNICODE_SCRIPT_CUNEIFORM" + glib:nick="cuneiform" + glib:name="G_UNICODE_SCRIPT_CUNEIFORM"> Cuneiform + filename="glib/gunicode.h" + line="345">Cuneiform + c:identifier="G_UNICODE_SCRIPT_PHOENICIAN" + glib:nick="phoenician" + glib:name="G_UNICODE_SCRIPT_PHOENICIAN"> Phoenician + filename="glib/gunicode.h" + line="346">Phoenician + c:identifier="G_UNICODE_SCRIPT_PHAGS_PA" + glib:nick="phags-pa" + glib:name="G_UNICODE_SCRIPT_PHAGS_PA"> Phags-pa + filename="glib/gunicode.h" + line="347">Phags-pa - - N'Ko + + N'Ko + c:identifier="G_UNICODE_SCRIPT_KAYAH_LI" + glib:nick="kayah-li" + glib:name="G_UNICODE_SCRIPT_KAYAH_LI"> Kayah Li. Since 2.16.3 + filename="glib/gunicode.h" + line="349">Kayah Li. Since 2.16.3 - + Lepcha. Since 2.16.3 + filename="glib/gunicode.h" + line="350">Lepcha. Since 2.16.3 - + Rejang. Since 2.16.3 + filename="glib/gunicode.h" + line="351">Rejang. Since 2.16.3 + c:identifier="G_UNICODE_SCRIPT_SUNDANESE" + glib:nick="sundanese" + glib:name="G_UNICODE_SCRIPT_SUNDANESE"> Sundanese. Since 2.16.3 + filename="glib/gunicode.h" + line="352">Sundanese. Since 2.16.3 + c:identifier="G_UNICODE_SCRIPT_SAURASHTRA" + glib:nick="saurashtra" + glib:name="G_UNICODE_SCRIPT_SAURASHTRA"> Saurashtra. Since 2.16.3 + filename="glib/gunicode.h" + line="353">Saurashtra. Since 2.16.3 - + Cham. Since 2.16.3 + filename="glib/gunicode.h" + line="354">Cham. Since 2.16.3 + c:identifier="G_UNICODE_SCRIPT_OL_CHIKI" + glib:nick="ol-chiki" + glib:name="G_UNICODE_SCRIPT_OL_CHIKI"> Ol Chiki. Since 2.16.3 + filename="glib/gunicode.h" + line="355">Ol Chiki. Since 2.16.3 - + Vai. Since 2.16.3 + filename="glib/gunicode.h" + line="356">Vai. Since 2.16.3 - + Carian. Since 2.16.3 + filename="glib/gunicode.h" + line="357">Carian. Since 2.16.3 - + Lycian. Since 2.16.3 + filename="glib/gunicode.h" + line="358">Lycian. Since 2.16.3 - + Lydian. Since 2.16.3 + filename="glib/gunicode.h" + line="359">Lydian. Since 2.16.3 + c:identifier="G_UNICODE_SCRIPT_AVESTAN" + glib:nick="avestan" + glib:name="G_UNICODE_SCRIPT_AVESTAN"> Avestan. Since 2.26 + filename="glib/gunicode.h" + line="360">Avestan. Since 2.26 - + Bamum. Since 2.26 + filename="glib/gunicode.h" + line="361">Bamum. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS" + glib:nick="egyptian-hieroglyphs" + glib:name="G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS"> Egyptian Hieroglpyhs. Since 2.26 + filename="glib/gunicode.h" + line="362">Egyptian Hieroglpyhs. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC" + glib:nick="imperial-aramaic" + glib:name="G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC"> Imperial Aramaic. Since 2.26 + filename="glib/gunicode.h" + line="364">Imperial Aramaic. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI" + glib:nick="inscriptional-pahlavi" + glib:name="G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI"> Inscriptional Pahlavi. Since 2.26 + filename="glib/gunicode.h" + line="366">Inscriptional Pahlavi. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN" + glib:nick="inscriptional-parthian" + glib:name="G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN"> Inscriptional Parthian. Since 2.26 + filename="glib/gunicode.h" + line="368">Inscriptional Parthian. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_JAVANESE" + glib:nick="javanese" + glib:name="G_UNICODE_SCRIPT_JAVANESE"> Javanese. Since 2.26 + filename="glib/gunicode.h" + line="370">Javanese. Since 2.26 - + Kaithi. Since 2.26 + filename="glib/gunicode.h" + line="371">Kaithi. Since 2.26 - + Lisu. Since 2.26 + filename="glib/gunicode.h" + line="372">Lisu. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_MEETEI_MAYEK" + glib:nick="meetei-mayek" + glib:name="G_UNICODE_SCRIPT_MEETEI_MAYEK"> Meetei Mayek. Since 2.26 + filename="glib/gunicode.h" + line="373">Meetei Mayek. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN" + glib:nick="old-south-arabian" + glib:name="G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN"> Old South Arabian. Since 2.26 + filename="glib/gunicode.h" + line="375">Old South Arabian. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_OLD_TURKIC" + glib:nick="old-turkic" + glib:name="G_UNICODE_SCRIPT_OLD_TURKIC"> Old Turkic. Since 2.28 + filename="glib/gunicode.h" + line="377">Old Turkic. Since 2.28 + c:identifier="G_UNICODE_SCRIPT_SAMARITAN" + glib:nick="samaritan" + glib:name="G_UNICODE_SCRIPT_SAMARITAN"> Samaritan. Since 2.26 + filename="glib/gunicode.h" + line="378">Samaritan. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_TAI_THAM" + glib:nick="tai-tham" + glib:name="G_UNICODE_SCRIPT_TAI_THAM"> Tai Tham. Since 2.26 + filename="glib/gunicode.h" + line="379">Tai Tham. Since 2.26 + c:identifier="G_UNICODE_SCRIPT_TAI_VIET" + glib:nick="tai-viet" + glib:name="G_UNICODE_SCRIPT_TAI_VIET"> Tai Viet. Since 2.26 + filename="glib/gunicode.h" + line="380">Tai Viet. Since 2.26 - + Batak. Since 2.28 + filename="glib/gunicode.h" + line="381">Batak. Since 2.28 - + Brahmi. Since 2.28 + filename="glib/gunicode.h" + line="382">Brahmi. Since 2.28 + c:identifier="G_UNICODE_SCRIPT_MANDAIC" + glib:nick="mandaic" + glib:name="G_UNICODE_SCRIPT_MANDAIC"> Mandaic. Since 2.28 + filename="glib/gunicode.h" + line="383">Mandaic. Since 2.28 - + Chakma. Since: 2.32 + filename="glib/gunicode.h" + line="384">Chakma. Since: 2.32 + c:identifier="G_UNICODE_SCRIPT_MEROITIC_CURSIVE" + glib:nick="meroitic-cursive" + glib:name="G_UNICODE_SCRIPT_MEROITIC_CURSIVE"> Meroitic Cursive. Since: 2.32 + filename="glib/gunicode.h" + line="385">Meroitic Cursive. Since: 2.32 + c:identifier="G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS" + glib:nick="meroitic-hieroglyphs" + glib:name="G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS"> Meroitic Hieroglyphs. Since: 2.32 + filename="glib/gunicode.h" + line="386">Meroitic Hieroglyphs. Since: 2.32 - + Miao. Since: 2.32 + filename="glib/gunicode.h" + line="387">Miao. Since: 2.32 + c:identifier="G_UNICODE_SCRIPT_SHARADA" + glib:nick="sharada" + glib:name="G_UNICODE_SCRIPT_SHARADA"> Sharada. Since: 2.32 + filename="glib/gunicode.h" + line="388">Sharada. Since: 2.32 + c:identifier="G_UNICODE_SCRIPT_SORA_SOMPENG" + glib:nick="sora-sompeng" + glib:name="G_UNICODE_SCRIPT_SORA_SOMPENG"> Sora Sompeng. Since: 2.32 + filename="glib/gunicode.h" + line="389">Sora Sompeng. Since: 2.32 - + Takri. Since: 2.32 + filename="glib/gunicode.h" + line="390">Takri. Since: 2.32 + c:identifier="G_UNICODE_SCRIPT_BASSA_VAH" + glib:nick="bassa-vah" + glib:name="G_UNICODE_SCRIPT_BASSA_VAH"> Bassa. Since: 2.42 + filename="glib/gunicode.h" + line="391">Bassa. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_CAUCASIAN_ALBANIAN" + glib:nick="caucasian-albanian" + glib:name="G_UNICODE_SCRIPT_CAUCASIAN_ALBANIAN"> Caucasian Albanian. Since: 2.42 + filename="glib/gunicode.h" + line="392">Caucasian Albanian. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_DUPLOYAN" + glib:nick="duployan" + glib:name="G_UNICODE_SCRIPT_DUPLOYAN"> Duployan. Since: 2.42 + filename="glib/gunicode.h" + line="393">Duployan. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_ELBASAN" + glib:nick="elbasan" + glib:name="G_UNICODE_SCRIPT_ELBASAN"> Elbasan. Since: 2.42 + filename="glib/gunicode.h" + line="394">Elbasan. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_GRANTHA" + glib:nick="grantha" + glib:name="G_UNICODE_SCRIPT_GRANTHA"> Grantha. Since: 2.42 + filename="glib/gunicode.h" + line="395">Grantha. Since: 2.42 - + Kjohki. Since: 2.42 + filename="glib/gunicode.h" + line="396">Kjohki. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_KHUDAWADI" + glib:nick="khudawadi" + glib:name="G_UNICODE_SCRIPT_KHUDAWADI"> Khudawadi, Sindhi. Since: 2.42 + filename="glib/gunicode.h" + line="397">Khudawadi, Sindhi. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_LINEAR_A" + glib:nick="linear-a" + glib:name="G_UNICODE_SCRIPT_LINEAR_A"> Linear A. Since: 2.42 + filename="glib/gunicode.h" + line="398">Linear A. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_MAHAJANI" + glib:nick="mahajani" + glib:name="G_UNICODE_SCRIPT_MAHAJANI"> Mahajani. Since: 2.42 + filename="glib/gunicode.h" + line="399">Mahajani. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_MANICHAEAN" + glib:nick="manichaean" + glib:name="G_UNICODE_SCRIPT_MANICHAEAN"> Manichaean. Since: 2.42 + filename="glib/gunicode.h" + line="400">Manichaean. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_MENDE_KIKAKUI" + glib:nick="mende-kikakui" + glib:name="G_UNICODE_SCRIPT_MENDE_KIKAKUI"> Mende Kikakui. Since: 2.42 + filename="glib/gunicode.h" + line="401">Mende Kikakui. Since: 2.42 - + Modi. Since: 2.42 + filename="glib/gunicode.h" + line="402">Modi. Since: 2.42 - + Mro. Since: 2.42 + filename="glib/gunicode.h" + line="403">Mro. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_NABATAEAN" + glib:nick="nabataean" + glib:name="G_UNICODE_SCRIPT_NABATAEAN"> Nabataean. Since: 2.42 + filename="glib/gunicode.h" + line="404">Nabataean. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_OLD_NORTH_ARABIAN" + glib:nick="old-north-arabian" + glib:name="G_UNICODE_SCRIPT_OLD_NORTH_ARABIAN"> Old North Arabian. Since: 2.42 + filename="glib/gunicode.h" + line="405">Old North Arabian. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_OLD_PERMIC" + glib:nick="old-permic" + glib:name="G_UNICODE_SCRIPT_OLD_PERMIC"> Old Permic. Since: 2.42 + filename="glib/gunicode.h" + line="406">Old Permic. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_PAHAWH_HMONG" + glib:nick="pahawh-hmong" + glib:name="G_UNICODE_SCRIPT_PAHAWH_HMONG"> Pahawh Hmong. Since: 2.42 + filename="glib/gunicode.h" + line="407">Pahawh Hmong. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_PALMYRENE" + glib:nick="palmyrene" + glib:name="G_UNICODE_SCRIPT_PALMYRENE"> Palmyrene. Since: 2.42 + filename="glib/gunicode.h" + line="408">Palmyrene. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_PAU_CIN_HAU" + glib:nick="pau-cin-hau" + glib:name="G_UNICODE_SCRIPT_PAU_CIN_HAU"> Pau Cin Hau. Since: 2.42 + filename="glib/gunicode.h" + line="409">Pau Cin Hau. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_PSALTER_PAHLAVI" + glib:nick="psalter-pahlavi" + glib:name="G_UNICODE_SCRIPT_PSALTER_PAHLAVI"> Psalter Pahlavi. Since: 2.42 + filename="glib/gunicode.h" + line="410">Psalter Pahlavi. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_SIDDHAM" + glib:nick="siddham" + glib:name="G_UNICODE_SCRIPT_SIDDHAM"> Siddham. Since: 2.42 + filename="glib/gunicode.h" + line="411">Siddham. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_TIRHUTA" + glib:nick="tirhuta" + glib:name="G_UNICODE_SCRIPT_TIRHUTA"> Tirhuta. Since: 2.42 + filename="glib/gunicode.h" + line="412">Tirhuta. Since: 2.42 + c:identifier="G_UNICODE_SCRIPT_WARANG_CITI" + glib:nick="warang-citi" + glib:name="G_UNICODE_SCRIPT_WARANG_CITI"> Warang Citi. Since: 2.42 + filename="glib/gunicode.h" + line="413">Warang Citi. Since: 2.42 - + Ahom. Since: 2.48 + filename="glib/gunicode.h" + line="414">Ahom. Since: 2.48 + c:identifier="G_UNICODE_SCRIPT_ANATOLIAN_HIEROGLYPHS" + glib:nick="anatolian-hieroglyphs" + glib:name="G_UNICODE_SCRIPT_ANATOLIAN_HIEROGLYPHS"> Anatolian Hieroglyphs. Since: 2.48 + filename="glib/gunicode.h" + line="415">Anatolian Hieroglyphs. Since: 2.48 - + Hatran. Since: 2.48 + filename="glib/gunicode.h" + line="416">Hatran. Since: 2.48 + c:identifier="G_UNICODE_SCRIPT_MULTANI" + glib:nick="multani" + glib:name="G_UNICODE_SCRIPT_MULTANI"> Multani. Since: 2.48 + filename="glib/gunicode.h" + line="417">Multani. Since: 2.48 + c:identifier="G_UNICODE_SCRIPT_OLD_HUNGARIAN" + glib:nick="old-hungarian" + glib:name="G_UNICODE_SCRIPT_OLD_HUNGARIAN"> Old Hungarian. Since: 2.48 + filename="glib/gunicode.h" + line="418">Old Hungarian. Since: 2.48 + c:identifier="G_UNICODE_SCRIPT_SIGNWRITING" + glib:nick="signwriting" + glib:name="G_UNICODE_SCRIPT_SIGNWRITING"> Signwriting. Since: 2.48 + filename="glib/gunicode.h" + line="419">Signwriting. Since: 2.48 - + Adlam. Since: 2.50 + filename="glib/gunicode.h" + line="420">Adlam. Since: 2.50 + c:identifier="G_UNICODE_SCRIPT_BHAIKSUKI" + glib:nick="bhaiksuki" + glib:name="G_UNICODE_SCRIPT_BHAIKSUKI"> Bhaiksuki. Since: 2.50 + filename="glib/gunicode.h" + line="421">Bhaiksuki. Since: 2.50 + c:identifier="G_UNICODE_SCRIPT_MARCHEN" + glib:nick="marchen" + glib:name="G_UNICODE_SCRIPT_MARCHEN"> Marchen. Since: 2.50 + filename="glib/gunicode.h" + line="422">Marchen. Since: 2.50 - + Newa. Since: 2.50 + filename="glib/gunicode.h" + line="423">Newa. Since: 2.50 - + Osage. Since: 2.50 + filename="glib/gunicode.h" + line="424">Osage. Since: 2.50 - + Tangut. Since: 2.50 + filename="glib/gunicode.h" + line="425">Tangut. Since: 2.50 + c:identifier="G_UNICODE_SCRIPT_MASARAM_GONDI" + glib:nick="masaram-gondi" + glib:name="G_UNICODE_SCRIPT_MASARAM_GONDI"> Masaram Gondi. Since: 2.54 + filename="glib/gunicode.h" + line="426">Masaram Gondi. Since: 2.54 - + Nushu. Since: 2.54 + filename="glib/gunicode.h" + line="427">Nushu. Since: 2.54 + c:identifier="G_UNICODE_SCRIPT_SOYOMBO" + glib:nick="soyombo" + glib:name="G_UNICODE_SCRIPT_SOYOMBO"> Soyombo. Since: 2.54 + filename="glib/gunicode.h" + line="428">Soyombo. Since: 2.54 + c:identifier="G_UNICODE_SCRIPT_ZANABAZAR_SQUARE" + glib:nick="zanabazar-square" + glib:name="G_UNICODE_SCRIPT_ZANABAZAR_SQUARE"> Zanabazar Square. Since: 2.54 + filename="glib/gunicode.h" + line="429">Zanabazar Square. Since: 2.54 - + Dogra. Since: 2.58 + filename="glib/gunicode.h" + line="430">Dogra. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_GUNJALA_GONDI" + glib:nick="gunjala-gondi" + glib:name="G_UNICODE_SCRIPT_GUNJALA_GONDI"> Gunjala Gondi. Since: 2.58 + filename="glib/gunicode.h" + line="431">Gunjala Gondi. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_HANIFI_ROHINGYA" + glib:nick="hanifi-rohingya" + glib:name="G_UNICODE_SCRIPT_HANIFI_ROHINGYA"> Hanifi Rohingya. Since: 2.58 + filename="glib/gunicode.h" + line="432">Hanifi Rohingya. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_MAKASAR" + glib:nick="makasar" + glib:name="G_UNICODE_SCRIPT_MAKASAR"> Makasar. Since: 2.58 + filename="glib/gunicode.h" + line="433">Makasar. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_MEDEFAIDRIN" + glib:nick="medefaidrin" + glib:name="G_UNICODE_SCRIPT_MEDEFAIDRIN"> Medefaidrin. Since: 2.58 + filename="glib/gunicode.h" + line="434">Medefaidrin. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_OLD_SOGDIAN" + glib:nick="old-sogdian" + glib:name="G_UNICODE_SCRIPT_OLD_SOGDIAN"> Old Sogdian. Since: 2.58 + filename="glib/gunicode.h" + line="435">Old Sogdian. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_SOGDIAN" + glib:nick="sogdian" + glib:name="G_UNICODE_SCRIPT_SOGDIAN"> Sogdian. Since: 2.58 + filename="glib/gunicode.h" + line="436">Sogdian. Since: 2.58 + c:identifier="G_UNICODE_SCRIPT_ELYMAIC" + glib:nick="elymaic" + glib:name="G_UNICODE_SCRIPT_ELYMAIC"> Elym. Since: 2.62 + filename="glib/gunicode.h" + line="437">Elym. Since: 2.62 + c:identifier="G_UNICODE_SCRIPT_NANDINAGARI" + glib:nick="nandinagari" + glib:name="G_UNICODE_SCRIPT_NANDINAGARI"> Nand. Since: 2.62 + filename="glib/gunicode.h" + line="438">Nand. Since: 2.62 + c:identifier="G_UNICODE_SCRIPT_NYIAKENG_PUACHUE_HMONG" + glib:nick="nyiakeng-puachue-hmong" + glib:name="G_UNICODE_SCRIPT_NYIAKENG_PUACHUE_HMONG"> Rohg. Since: 2.62 + filename="glib/gunicode.h" + line="439">Rohg. Since: 2.62 - + Wcho. Since: 2.62 + filename="glib/gunicode.h" + line="440">Wcho. Since: 2.62 + c:identifier="G_UNICODE_SCRIPT_CHORASMIAN" + glib:nick="chorasmian" + glib:name="G_UNICODE_SCRIPT_CHORASMIAN"> Chorasmian. Since: 2.66 + filename="glib/gunicode.h" + line="441">Chorasmian. Since: 2.66 + c:identifier="G_UNICODE_SCRIPT_DIVES_AKURU" + glib:nick="dives-akuru" + glib:name="G_UNICODE_SCRIPT_DIVES_AKURU"> Dives Akuru. Since: 2.66 + filename="glib/gunicode.h" + line="442">Dives Akuru. Since: 2.66 + c:identifier="G_UNICODE_SCRIPT_KHITAN_SMALL_SCRIPT" + glib:nick="khitan-small-script" + glib:name="G_UNICODE_SCRIPT_KHITAN_SMALL_SCRIPT"> Khitan small script. Since: 2.66 + filename="glib/gunicode.h" + line="443">Khitan small script. Since: 2.66 - + Yezidi. Since: 2.66 + filename="glib/gunicode.h" + line="444">Yezidi. Since: 2.66 + c:identifier="G_UNICODE_SCRIPT_CYPRO_MINOAN" + glib:nick="cypro-minoan" + glib:name="G_UNICODE_SCRIPT_CYPRO_MINOAN"> Cypro-Minoan. Since: 2.72 + filename="glib/gunicode.h" + line="445">Cypro-Minoan. Since: 2.72 + c:identifier="G_UNICODE_SCRIPT_OLD_UYGHUR" + glib:nick="old-uyghur" + glib:name="G_UNICODE_SCRIPT_OLD_UYGHUR"> Old Uyghur. Since: 2.72 + filename="glib/gunicode.h" + line="446">Old Uyghur. Since: 2.72 - + Tangsa. Since: 2.72 + filename="glib/gunicode.h" + line="447">Tangsa. Since: 2.72 - + Toto. Since: 2.72 + filename="glib/gunicode.h" + line="448">Toto. Since: 2.72 + c:identifier="G_UNICODE_SCRIPT_VITHKUQI" + glib:nick="vithkuqi" + glib:name="G_UNICODE_SCRIPT_VITHKUQI"> Vithkuqi. Since: 2.72 + filename="glib/gunicode.h" + line="449">Vithkuqi. Since: 2.72 - + Mathematical notation. Since: 2.72 + filename="glib/gunicode.h" + line="450">Mathematical notation. Since: 2.72 - + Kawi. Since 2.74 + filename="glib/gunicode.h" + line="451">Kawi. Since 2.74 + c:identifier="G_UNICODE_SCRIPT_NAG_MUNDARI" + glib:nick="nag-mundari" + glib:name="G_UNICODE_SCRIPT_NAG_MUNDARI"> Nag Mundari. Since 2.74 + filename="glib/gunicode.h" + line="452">Nag Mundari. Since 2.74 + + Todhri. Since: 2.84 + + + Garay. Since: 2.84 + + + Tulu-Tigalari. Since: 2.84 + + + Sunuwar. Since: 2.84 + + + Gurung Khema. Since: 2.84 + + + Kirat Rai. Since: 2.84 + + + Ol Onal. Since: 2.84 + + + Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter +codes to scripts. For example, the code for Arabic is 'Arab'. +This function accepts four letter codes encoded as a @guint32 in a +big-endian fashion. That is, the code expected for Arabic is +0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). + +See +[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) +for details. + + + the Unicode script for @iso15924, or + of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and + %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. + + + + + a Unicode script + + + + + + Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter +codes to scripts. For example, the code for Arabic is 'Arab'. The +four letter codes are encoded as a @guint32 by this function in a +big-endian fashion. That is, the code returned for Arabic is +0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). + +See +[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) +for details. + + + the ISO 15924 code for @script, encoded as an integer, + of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or + ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. + + + + + a Unicode script + + + + - + These are the possible character classifications from the Unicode specification. See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values). - - + General category "Other, Control" (Cc) - + General category "Other, Format" (Cf) - + General category "Other, Not Assigned" (Cn) + c:identifier="G_UNICODE_PRIVATE_USE" + glib:nick="private-use" + glib:name="G_UNICODE_PRIVATE_USE"> General category "Other, Private Use" (Co) - + General category "Other, Surrogate" (Cs) + c:identifier="G_UNICODE_LOWERCASE_LETTER" + glib:nick="lowercase-letter" + glib:name="G_UNICODE_LOWERCASE_LETTER"> General category "Letter, Lowercase" (Ll) + c:identifier="G_UNICODE_MODIFIER_LETTER" + glib:nick="modifier-letter" + glib:name="G_UNICODE_MODIFIER_LETTER"> General category "Letter, Modifier" (Lm) + c:identifier="G_UNICODE_OTHER_LETTER" + glib:nick="other-letter" + glib:name="G_UNICODE_OTHER_LETTER"> General category "Letter, Other" (Lo) + c:identifier="G_UNICODE_TITLECASE_LETTER" + glib:nick="titlecase-letter" + glib:name="G_UNICODE_TITLECASE_LETTER"> General category "Letter, Titlecase" (Lt) + c:identifier="G_UNICODE_UPPERCASE_LETTER" + glib:nick="uppercase-letter" + glib:name="G_UNICODE_UPPERCASE_LETTER"> General category "Letter, Uppercase" (Lu) + c:identifier="G_UNICODE_SPACING_MARK" + glib:nick="spacing-mark" + glib:name="G_UNICODE_SPACING_MARK"> General category "Mark, Spacing" (Mc) + c:identifier="G_UNICODE_ENCLOSING_MARK" + glib:nick="enclosing-mark" + glib:name="G_UNICODE_ENCLOSING_MARK"> General category "Mark, Enclosing" (Me) + c:identifier="G_UNICODE_NON_SPACING_MARK" + glib:nick="non-spacing-mark" + glib:name="G_UNICODE_NON_SPACING_MARK"> General category "Mark, Nonspacing" (Mn) + c:identifier="G_UNICODE_DECIMAL_NUMBER" + glib:nick="decimal-number" + glib:name="G_UNICODE_DECIMAL_NUMBER"> General category "Number, Decimal Digit" (Nd) + c:identifier="G_UNICODE_LETTER_NUMBER" + glib:nick="letter-number" + glib:name="G_UNICODE_LETTER_NUMBER"> General category "Number, Letter" (Nl) + c:identifier="G_UNICODE_OTHER_NUMBER" + glib:nick="other-number" + glib:name="G_UNICODE_OTHER_NUMBER"> General category "Number, Other" (No) + c:identifier="G_UNICODE_CONNECT_PUNCTUATION" + glib:nick="connect-punctuation" + glib:name="G_UNICODE_CONNECT_PUNCTUATION"> General category "Punctuation, Connector" (Pc) + c:identifier="G_UNICODE_DASH_PUNCTUATION" + glib:nick="dash-punctuation" + glib:name="G_UNICODE_DASH_PUNCTUATION"> General category "Punctuation, Dash" (Pd) + c:identifier="G_UNICODE_CLOSE_PUNCTUATION" + glib:nick="close-punctuation" + glib:name="G_UNICODE_CLOSE_PUNCTUATION"> General category "Punctuation, Close" (Pe) + c:identifier="G_UNICODE_FINAL_PUNCTUATION" + glib:nick="final-punctuation" + glib:name="G_UNICODE_FINAL_PUNCTUATION"> General category "Punctuation, Final quote" (Pf) + c:identifier="G_UNICODE_INITIAL_PUNCTUATION" + glib:nick="initial-punctuation" + glib:name="G_UNICODE_INITIAL_PUNCTUATION"> General category "Punctuation, Initial quote" (Pi) + c:identifier="G_UNICODE_OTHER_PUNCTUATION" + glib:nick="other-punctuation" + glib:name="G_UNICODE_OTHER_PUNCTUATION"> General category "Punctuation, Other" (Po) + c:identifier="G_UNICODE_OPEN_PUNCTUATION" + glib:nick="open-punctuation" + glib:name="G_UNICODE_OPEN_PUNCTUATION"> General category "Punctuation, Open" (Ps) + c:identifier="G_UNICODE_CURRENCY_SYMBOL" + glib:nick="currency-symbol" + glib:name="G_UNICODE_CURRENCY_SYMBOL"> General category "Symbol, Currency" (Sc) + c:identifier="G_UNICODE_MODIFIER_SYMBOL" + glib:nick="modifier-symbol" + glib:name="G_UNICODE_MODIFIER_SYMBOL"> General category "Symbol, Modifier" (Sk) + c:identifier="G_UNICODE_MATH_SYMBOL" + glib:nick="math-symbol" + glib:name="G_UNICODE_MATH_SYMBOL"> General category "Symbol, Math" (Sm) + c:identifier="G_UNICODE_OTHER_SYMBOL" + glib:nick="other-symbol" + glib:name="G_UNICODE_OTHER_SYMBOL"> General category "Symbol, Other" (So) + c:identifier="G_UNICODE_LINE_SEPARATOR" + glib:nick="line-separator" + glib:name="G_UNICODE_LINE_SEPARATOR"> General category "Separator, Line" (Zl) + c:identifier="G_UNICODE_PARAGRAPH_SEPARATOR" + glib:nick="paragraph-separator" + glib:name="G_UNICODE_PARAGRAPH_SEPARATOR"> General category "Separator, Paragraph" (Zp) + c:identifier="G_UNICODE_SPACE_SEPARATOR" + glib:nick="space-separator" + glib:name="G_UNICODE_SPACE_SEPARATOR"> General category "Separator, Space" (Zs) The type of functions to be called when a UNIX fd watch source + filename="glib/glib-unix.h" + line="88">The type of functions to be called when a UNIX fd watch source triggers. - + %FALSE if the source should be removed + filename="glib/glib-unix.h" + line="97">%FALSE if the source should be removed the fd that triggered the event + filename="glib/glib-unix.h" + line="90">the fd that triggered the event the IO conditions reported on @fd + filename="glib/glib-unix.h" + line="91">the IO conditions reported on @fd allow-none="1" closure="2"> user data passed to g_unix_fd_add() + filename="glib/glib-unix.h" + line="92">user data passed to g_unix_fd_add() + + A Unix pipe. The advantage of this type over `int[2]` is that it can +be closed automatically when it goes out of scope, using `g_auto(GUnixPipe)`, +on compilers that support that feature. + + + A pair of file descriptors, each negative if closed or not yet opened. + The file descriptor with index %G_UNIX_PIPE_END_READ is readable. + The file descriptor with index %G_UNIX_PIPE_END_WRITE is writable. + + + + + + Close both ends of the pipe, unless they have already been closed or +stolen. Any errors are ignored: use g_unix_pipe_close() or g_clear_fd() +if error-handling is required. + +This function is async-signal safe if @error is %NULL and each member +of @fds are either negative or a valid open file descriptor. +As a result, it is safe to call this function or use `g_auto(GUnixPipe)` +(on compilers that support it) in a signal handler or a +#GSpawnChildSetupFunc, as long as those conditions are ensured to be true. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +This function preserves the value of `errno`. + + + + + + + a #GUnixPipe + + + + + + Close one of the ends of the pipe and set the relevant member of @fds +to `-1` before returning, equivalent to g_clear_fd(). + +Like g_close(), if closing the file descriptor fails, the error is +stored in both %errno and @error. If this function succeeds, +%errno is undefined. + +This function is async-signal safe if @error is %NULL and the relevant +member of @fds is either negative or a valid open file descriptor. +This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc +under those conditions. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +To close both file descriptors and ignore any errors, use +g_unix_pipe_clear() instead. + + + %TRUE on success + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + Return one of the ends of the pipe. It remains owned by @self. + +This function is async-signal safe (see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + + a non-negative file descriptor owned by @self, which must not + be closed by the caller, or a negative number if the corresponding + end of the pipe was already closed or stolen + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + Open a pipe. This is the same as g_unix_open_pipe(), but uses the +#GUnixPipe data structure. + + + %TRUE on success + + + + + A pair of file descriptors + + + + Flags to pass to g_unix_open_pipe(), typically `O_CLOEXEC` + + + + + + Return one of the ends of the pipe. It becomes owned by the caller, +and the file descriptor in the data structure is set to `-1`, +similar to g_steal_fd(). + +This function is async-signal safe (see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + + a non-negative file descriptor, which becomes owned by the + caller and must be closed by the caller if required, or a negative + number if the corresponding end of the pipe was already closed or stolen + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + + Mnemonic constants for the ends of a Unix pipe. + + + The readable file descriptor 0 + + + The writable file descriptor 1 + + glib:get-type="g_uri_get_type" c:symbol-prefix="uri"> The #GUri type and related functions can be used to parse URIs into + filename="glib/guri.c" + line="31">The `GUri` type and related functions can be used to parse URIs into their components, and build valid URIs from individual components. -Note that #GUri scope is to help manipulate URIs in various applications, +Since `GUri` only represents absolute URIs, all `GUri`s will have a +URI scheme, so [method@GLib.Uri.get_scheme] will always return a non-`NULL` +answer. Likewise, by definition, all URIs have a path component, so +[method@GLib.Uri.get_path] will always return a non-`NULL` string (which may +be empty). + +If the URI string has an +[‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that +is, if the scheme is followed by `://` rather than just `:`), then the +`GUri` will contain a hostname, and possibly a port and ‘userinfo’. +Additionally, depending on how the `GUri` was constructed/parsed (for example, +using the `G_URI_FLAGS_HAS_PASSWORD` and `G_URI_FLAGS_HAS_AUTH_PARAMS` flags), +the userinfo may be split out into a username, password, and +additional authorization-related parameters. + +Normally, the components of a `GUri` will have all `%`-encoded +characters decoded. However, if you construct/parse a `GUri` with +`G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in +the userinfo, path, and query fields (and in the host field if also +created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if +the URI may contain binary data or non-UTF-8 text, or if decoding +the components might change the interpretation of the URI. + +For example, with the encoded flag: + +```c +g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err); +g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue"); +``` + +While the default `%`-decoding behaviour would give: + +```c +g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err); +g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value"); +``` + +During decoding, if an invalid UTF-8 string is encountered, parsing will fail +with an error indicating the bad string location: + +```c +g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err); +g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY); +``` + +You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you +need to handle that case manually. In particular, if the query string +contains `=` characters that are `%`-encoded, you should let +[func@GLib.Uri.parse_params] do the decoding once of the query. + +`GUri` is immutable once constructed, and can safely be accessed from +multiple threads. Its reference counting is atomic. + +Note that the scope of `GUri` is to help manipulate URIs in various applications, following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, -it doesn't intend to cover web browser needs, and doesn't implement the +it doesn't intend to cover web browser needs, and doesn’t implement the [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to help prevent [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so -#GUri is not suitable for formatting URIs for display to the user for making +`GUri` is not suitable for formatting URIs for display to the user for making security-sensitive decisions. -## Relative and absolute URIs # {#relative-absolute-uris} +## Relative and absolute URIs As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the hierarchical nature of URIs means that they can either be ‘relative references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for clarity, ‘URIs’ are referred to in this documentation as ‘absolute URIs’ — although -[in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), +[in contrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), fragment identifiers are always allowed). Relative references have one or more components of the URI missing. In @@ -46973,127 +52312,127 @@ For example, a valid relative reference is `./path?query`, Absolute URIs have a scheme specified. Any other components of the URI which are missing are specified as explicitly unset in the URI, rather than being -resolved relative to a base URI using g_uri_parse_relative(). +resolved relative to a base URI using [method@GLib.Uri.parse_relative]. For example, a valid absolute URI is `file:///home/bob` or `https://search.com?query=string`. -A #GUri instance is always an absolute URI. A string may be an absolute URI +A `GUri` instance is always an absolute URI. A string may be an absolute URI or a relative reference; see the documentation for individual functions as to what forms they accept. ## Parsing URIs -The most minimalist APIs for parsing URIs are g_uri_split() and -g_uri_split_with_user(). These split a URI into its component +The most minimalist APIs for parsing URIs are [func@GLib.Uri.split] and +[func@GLib.Uri.split_with_user]. These split a URI into its component parts, and return the parts; the difference between the two is that -g_uri_split() treats the ‘userinfo’ component of the URI as a -single element, while g_uri_split_with_user() can (depending on the -#GUriFlags you pass) treat it as containing a username, password, -and authentication parameters. Alternatively, g_uri_split_network() +[func@GLib.Uri.split] treats the ‘userinfo’ component of the URI as a +single element, while [func@GLib.Uri.split_with_user] can (depending on the +[flags@GLib.UriFlags] you pass) treat it as containing a username, password, +and authentication parameters. Alternatively, [func@GLib.Uri.split_network] can be used when you are only interested in the components that are needed to initiate a network connection to the service (scheme, host, and port). -g_uri_parse() is similar to g_uri_split(), but instead of returning -individual strings, it returns a #GUri structure (and it requires +[func@GLib.Uri.parse] is similar to [func@GLib.Uri.split], but instead of +returning individual strings, it returns a `GUri` structure (and it requires that the URI be an absolute URI). -g_uri_resolve_relative() and g_uri_parse_relative() allow you to -resolve a relative URI relative to a base URI. -g_uri_resolve_relative() takes two strings and returns a string, -and g_uri_parse_relative() takes a #GUri and a string and returns a -#GUri. +[func@GLib.Uri.resolve_relative] and [method@GLib.Uri.parse_relative] allow +you to resolve a relative URI relative to a base URI. +[func@GLib.Uri.resolve_relative] takes two strings and returns a string, +and [method@GLib.Uri.parse_relative] takes a `GUri` and a string and returns a +`GUri`. -All of the parsing functions take a #GUriFlags argument describing +All of the parsing functions take a [flags@GLib.UriFlags] argument describing exactly how to parse the URI; see the documentation for that type for more details on the specific flags that you can pass. If you need to choose different flags based on the type of URI, you can -use g_uri_peek_scheme() on the URI string to check the scheme +use [func@GLib.Uri.peek_scheme] on the URI string to check the scheme first, and use that to decide what flags to parse it with. -For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the -params for a web URI, so compare the result of g_uri_peek_scheme() against -`http` and `https`. +For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the +params for a web URI, so compare the result of [func@GLib.Uri.peek_scheme] +against `http` and `https`. ## Building URIs -g_uri_join() and g_uri_join_with_user() can be used to construct +[func@GLib.Uri.join] and [func@GLib.Uri.join_with_user] can be used to construct valid URI strings from a set of component strings. They are the -inverse of g_uri_split() and g_uri_split_with_user(). +inverse of [func@GLib.Uri.split] and [func@GLib.Uri.split_with_user]. -Similarly, g_uri_build() and g_uri_build_with_user() can be used to -construct a #GUri from a set of component strings. +Similarly, [func@GLib.Uri.build] and [func@GLib.Uri.build_with_user] can be +used to construct a `GUri` from a set of component strings. As with the parsing functions, the building functions take a -#GUriFlags argument. In particular, it is important to keep in mind +[flags@GLib.UriFlags] argument. In particular, it is important to keep in mind whether the URI components you are using are already `%`-encoded. If so, -you must pass the %G_URI_FLAGS_ENCODED flag. +you must pass the `G_URI_FLAGS_ENCODED` flag. ## `file://` URIs Note that Windows and Unix both define special rules for parsing `file://` URIs (involving non-UTF-8 character sets on Unix, and the -interpretation of path separators on Windows). #GUri does not -implement these rules. Use g_filename_from_uri() and -g_filename_to_uri() if you want to properly convert between +interpretation of path separators on Windows). `GUri` does not +implement these rules. Use [func@GLib.filename_from_uri] and +[func@GLib.filename_to_uri] if you want to properly convert between `file://` URIs and local filenames. ## URI Equality Note that there is no `g_uri_equal ()` function, because comparing -URIs usefully requires scheme-specific knowledge that #GUri does -not have. #GUri can help with normalization if you use the various -encoded #GUriFlags as well as %G_URI_FLAGS_SCHEME_NORMALIZE however -it is not comprehensive. +URIs usefully requires scheme-specific knowledge that `GUri` does +not have. `GUri` can help with normalization if you use the various +encoded [flags@GLib.UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE` +however it is not comprehensive. For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same thing according to the `data:` URI specification which GLib does not handle. - + Gets @uri's authentication parameters, which may contain + filename="glib/guri.c" + line="2451">Gets @uri's authentication parameters, which may contain `%`-encoding, depending on the flags with which @uri was created. (If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will be %NULL.) Depending on the URI scheme, g_uri_parse_params() may be useful for further parsing this information. - + @uri's authentication parameters. + filename="glib/guri.c" + line="2463">@uri's authentication parameters. a #GUri + filename="glib/guri.c" + line="2453">a #GUri Gets @uri's flags set upon construction. - + filename="glib/guri.c" + line="2583">Gets @uri's flags set upon construction. + @uri's flags. + filename="glib/guri.c" + line="2589">@uri's flags. a #GUri + filename="glib/guri.c" + line="2585">a #GUri @@ -47102,29 +52441,29 @@ further parsing this information. c:identifier="g_uri_get_fragment" version="2.66"> Gets @uri's fragment, which may contain `%`-encoding, depending on + filename="glib/guri.c" + line="2563">Gets @uri's fragment, which may contain `%`-encoding, depending on the flags with which @uri was created. - + @uri's fragment. + filename="glib/guri.c" + line="2570">@uri's fragment. a #GUri + filename="glib/guri.c" + line="2565">a #GUri Gets @uri's host. This will never have `%`-encoded characters, + filename="glib/guri.c" + line="2475">Gets @uri's host. This will never have `%`-encoded characters, unless it is non-UTF-8 (which can only be the case if @uri was created with %G_URI_FLAGS_NON_DNS). @@ -47133,18 +52472,18 @@ that address, without the brackets around it that are necessary in the string form of the URI. Note that in this case there may also be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or `fe80::1234%``25em1` if the string is still encoded). - + @uri's host. + filename="glib/guri.c" + line="2489">@uri's host. a #GUri + filename="glib/guri.c" + line="2477">a #GUri @@ -47153,131 +52492,131 @@ be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or c:identifier="g_uri_get_password" version="2.66"> Gets @uri's password, which may contain `%`-encoding, depending on + filename="glib/guri.c" + line="2431">Gets @uri's password, which may contain `%`-encoding, depending on the flags with which @uri was created. (If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.) - + @uri's password. + filename="glib/guri.c" + line="2439">@uri's password. a #GUri + filename="glib/guri.c" + line="2433">a #GUri Gets @uri's path, which may contain `%`-encoding, depending on the + filename="glib/guri.c" + line="2522">Gets @uri's path, which may contain `%`-encoding, depending on the flags with which @uri was created. - + @uri's path. + filename="glib/guri.c" + line="2529">@uri's path. a #GUri + filename="glib/guri.c" + line="2524">a #GUri Gets @uri's port. - + filename="glib/guri.c" + line="2501">Gets @uri's port. + @uri's port, or `-1` if no port was specified. + filename="glib/guri.c" + line="2507">@uri's port, or `-1` if no port was specified. a #GUri + filename="glib/guri.c" + line="2503">a #GUri Gets @uri's query, which may contain `%`-encoding, depending on the + filename="glib/guri.c" + line="2541">Gets @uri's query, which may contain `%`-encoding, depending on the flags with which @uri was created. For queries consisting of a series of `name=value` parameters, #GUriParamsIter or g_uri_parse_params() may be useful. - + @uri's query. + filename="glib/guri.c" + line="2551">@uri's query. a #GUri + filename="glib/guri.c" + line="2543">a #GUri Gets @uri's scheme. Note that this will always be all-lowercase, + filename="glib/guri.c" + line="2372">Gets @uri's scheme. Note that this will always be all-lowercase, regardless of the string or strings that @uri was created from. - + @uri's scheme. + filename="glib/guri.c" + line="2379">@uri's scheme. a #GUri + filename="glib/guri.c" + line="2374">a #GUri Gets the ‘username’ component of @uri's userinfo, which may contain + filename="glib/guri.c" + line="2410">Gets the ‘username’ component of @uri's userinfo, which may contain `%`-encoding, depending on the flags with which @uri was created. If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or %G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo(). - + @uri's user. + filename="glib/guri.c" + line="2419">@uri's user. a #GUri + filename="glib/guri.c" + line="2412">a #GUri @@ -47286,21 +52625,21 @@ If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or c:identifier="g_uri_get_userinfo" version="2.66"> Gets @uri's userinfo, which may contain `%`-encoding, depending on + filename="glib/guri.c" + line="2391">Gets @uri's userinfo, which may contain `%`-encoding, depending on the flags with which @uri was created. - + @uri's userinfo. + filename="glib/guri.c" + line="2398">@uri's userinfo. a #GUri + filename="glib/guri.c" + line="2393">a #GUri @@ -47310,16 +52649,16 @@ the flags with which @uri was created. version="2.66" throws="1"> Parses @uri_ref according to @flags and, if it is a -[relative URI][relative-absolute-uris], resolves it relative to @base_uri. + filename="glib/guri.c" + line="1410">Parses @uri_ref according to @flags and, if it is a +[relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri. If the result is not a valid absolute URI, it will be discarded, and an error returned. - + a new #GUri, or NULL on error. + filename="glib/guri.c" + line="1422">a new #GUri, or NULL on error. @@ -47328,20 +52667,20 @@ returned. nullable="1" allow-none="1"> a base absolute URI + filename="glib/guri.c" + line="1412">a base absolute URI a string representing a relative or absolute URI + filename="glib/guri.c" + line="1413">a string representing a relative or absolute URI flags describing how to parse @uri_ref + filename="glib/guri.c" + line="1414">flags describing how to parse @uri_ref @@ -47351,28 +52690,28 @@ returned. version="2.66" introspectable="0"> Increments the reference count of @uri by one. - + filename="glib/guri.c" + line="214">Increments the reference count of @uri by one. + @uri + filename="glib/guri.c" + line="220">@uri a #GUri + filename="glib/guri.c" + line="216">a #GUri Returns a string representing @uri. + filename="glib/guri.c" + line="1987">Returns a string representing @uri. This is not guaranteed to return a string which is identical to the string that @uri was parsed from. However, if the source URI was @@ -47384,19 +52723,19 @@ URI (according to RFC 3986). If @uri might contain sensitive details, such as authentication parameters, or private data in its query string, and the returned string is going to be logged, then consider using g_uri_to_string_partial() to redact parts. - + a string representing @uri, + filename="glib/guri.c" + line="2004">a string representing @uri, which the caller must free. a #GUri + filename="glib/guri.c" + line="1989">a #GUri @@ -47405,28 +52744,28 @@ logged, then consider using g_uri_to_string_partial() to redact parts. c:identifier="g_uri_to_string_partial" version="2.66"> Returns a string representing @uri, subject to the options in + filename="glib/guri.c" + line="2017">Returns a string representing @uri, subject to the options in @flags. See g_uri_to_string() and #GUriHideFlags for more details. - + a string representing + filename="glib/guri.c" + line="2025">a string representing @uri, which the caller must free. a #GUri + filename="glib/guri.c" + line="2019">a #GUri flags describing what parts of @uri to hide + filename="glib/guri.c" + line="2020">flags describing what parts of @uri to hide @@ -47436,49 +52775,49 @@ logged, then consider using g_uri_to_string_partial() to redact parts. version="2.66" introspectable="0"> Atomically decrements the reference count of @uri by one. + filename="glib/guri.c" + line="246">Atomically decrements the reference count of @uri by one. When the reference count reaches zero, the resources allocated by @uri are freed - + a #GUri + filename="glib/guri.c" + line="248">a #GUri Creates a new #GUri from the given components according to @flags. + filename="glib/guri.c" + line="1860">Creates a new #GUri from the given components according to @flags. See also g_uri_build_with_user(), which allows specifying the components of the "userinfo" separately. - + a new #GUri + filename="glib/guri.c" + line="1876">a new #GUri flags describing how to build the #GUri + filename="glib/guri.c" + line="1862">flags describing how to build the #GUri the URI scheme + filename="glib/guri.c" + line="1863">the URI scheme nullable="1" allow-none="1"> the userinfo component, or %NULL + filename="glib/guri.c" + line="1864">the userinfo component, or %NULL nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1865">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1866">the port, or `-1` the path component + filename="glib/guri.c" + line="1867">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1868">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1869">the fragment, or %NULL @@ -47535,8 +52874,8 @@ components of the "userinfo" separately. c:identifier="g_uri_build_with_user" version="2.66"> Creates a new #GUri from the given components according to @flags + filename="glib/guri.c" + line="1909">Creates a new #GUri from the given components according to @flags (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be coherent with the passed values, in particular use `%`-encoded values with %G_URI_FLAGS_ENCODED. @@ -47544,24 +52883,24 @@ coherent with the passed values, in particular use `%`-encoded values with In contrast to g_uri_build(), this allows specifying the components of the ‘userinfo’ field separately. Note that @user must be non-%NULL if either @password or @auth_params is non-%NULL. - + a new #GUri + filename="glib/guri.c" + line="1931">a new #GUri flags describing how to build the #GUri + filename="glib/guri.c" + line="1911">flags describing how to build the #GUri the URI scheme + filename="glib/guri.c" + line="1912">the URI scheme nullable="1" allow-none="1"> the user component of the userinfo, or %NULL + filename="glib/guri.c" + line="1913">the user component of the userinfo, or %NULL nullable="1" allow-none="1"> the password component of the userinfo, or %NULL + filename="glib/guri.c" + line="1914">the password component of the userinfo, or %NULL nullable="1" allow-none="1"> the auth params of the userinfo, or %NULL + filename="glib/guri.c" + line="1915">the auth params of the userinfo, or %NULL nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1916">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1917">the port, or `-1` the path component + filename="glib/guri.c" + line="1918">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1919">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1920">the fragment, or %NULL @@ -47641,8 +52980,8 @@ if either @password or @auth_params is non-%NULL. c:identifier="g_uri_escape_bytes" version="2.66"> Escapes arbitrary data for use in a URI. + filename="glib/guri.c" + line="2779">Escapes arbitrary data for use in a URI. Normally all characters that are not ‘unreserved’ (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are @@ -47653,27 +52992,27 @@ portions of a URI. Though technically incorrect, this will also allow escaping nul bytes as `%``00`. - + an escaped version of @unescaped. + filename="glib/guri.c" + line="2798">an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input data. + filename="glib/guri.c" + line="2781">the unescaped input data. the length of @unescaped + filename="glib/guri.c" + line="2782">the length of @unescaped nullable="1" allow-none="1"> a string of reserved + filename="glib/guri.c" + line="2783">a string of reserved characters that are allowed to be used, or %NULL. @@ -47692,8 +53031,8 @@ bytes as `%``00`. c:identifier="g_uri_escape_string" version="2.16"> Escapes a string for use in a URI. + filename="glib/guri.c" + line="2688">Escapes a string for use in a URI. Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are @@ -47701,19 +53040,19 @@ escaped. But if you specify characters in @reserved_chars_allowed they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI. - + an escaped version of @unescaped. The + filename="glib/guri.c" + line="2704">an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input string. + filename="glib/guri.c" + line="2690">the unescaped input string. nullable="1" allow-none="1"> a string of reserved + filename="glib/guri.c" + line="2691">a string of reserved characters that are allowed to be used, or %NULL. %TRUE if the result can include UTF-8 characters. + filename="glib/guri.c" + line="2693">%TRUE if the result can include UTF-8 characters. @@ -47739,41 +53078,41 @@ returned string should be freed when no longer needed. version="2.66" throws="1"> Parses @uri_string according to @flags, to determine whether it is a valid -[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved + filename="glib/guri.c" + line="1247">Parses @uri_string according to @flags, to determine whether it is a valid +[absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved relative to another URI using g_uri_parse_relative(). If it’s not a valid URI, an error is returned explaining how it’s invalid. See g_uri_split(), and the definition of #GUriFlags, for more information on the effect of @flags. - + %TRUE if @uri_string is a valid absolute URI, %FALSE on error. + filename="glib/guri.c" + line="1262">%TRUE if @uri_string is a valid absolute URI, %FALSE on error. a string containing an absolute URI + filename="glib/guri.c" + line="1249">a string containing an absolute URI flags for parsing @uri_string + filename="glib/guri.c" + line="1250">flags for parsing @uri_string Joins the given components together according to @flags to create + filename="glib/guri.c" + line="1753">Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). @@ -47787,18 +53126,18 @@ components of the ‘userinfo’ separately. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. - + an absolute URI string + filename="glib/guri.c" + line="1779">an absolute URI string flags describing how to build the URI string + filename="glib/guri.c" + line="1755">flags describing how to build the URI string nullable="1" allow-none="1"> the URI scheme, or %NULL + filename="glib/guri.c" + line="1756">the URI scheme, or %NULL nullable="1" allow-none="1"> the userinfo component, or %NULL + filename="glib/guri.c" + line="1757">the userinfo component, or %NULL nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1758">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1759">the port, or `-1` the path component + filename="glib/guri.c" + line="1760">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1761">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1762">the fragment, or %NULL @@ -47864,8 +53203,8 @@ in @flags. c:identifier="g_uri_join_with_user" version="2.66"> Joins the given components together according to @flags to create + filename="glib/guri.c" + line="1806">Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). @@ -47874,18 +53213,18 @@ of the ‘userinfo’ separately. It otherwise behaves the same. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. - + an absolute URI string + filename="glib/guri.c" + line="1831">an absolute URI string flags describing how to build the URI string + filename="glib/guri.c" + line="1808">flags describing how to build the URI string nullable="1" allow-none="1"> the URI scheme, or %NULL + filename="glib/guri.c" + line="1809">the URI scheme, or %NULL nullable="1" allow-none="1"> the user component of the userinfo, or %NULL + filename="glib/guri.c" + line="1810">the user component of the userinfo, or %NULL nullable="1" allow-none="1"> the password component of the userinfo, or + filename="glib/guri.c" + line="1811">the password component of the userinfo, or %NULL @@ -47921,8 +53260,8 @@ in @flags. nullable="1" allow-none="1"> the auth params of the userinfo, or + filename="glib/guri.c" + line="1813">the auth params of the userinfo, or %NULL @@ -47931,20 +53270,20 @@ in @flags. nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1815">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1816">the port, or `-1` the path component + filename="glib/guri.c" + line="1817">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1818">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1819">the fragment, or %NULL @@ -47971,15 +53310,15 @@ in @flags. c:identifier="g_uri_list_extract_uris" version="2.6"> Splits an URI list conforming to the text/uri-list + filename="glib/gconvert.c" + line="1765">Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated. - + a newly allocated %NULL-terminated list + filename="glib/gconvert.c" + line="1773">a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev(). @@ -47989,8 +53328,8 @@ discarding any comments. The URIs are not validated. an URI list + filename="glib/gconvert.c" + line="1767">an URI list @@ -48000,28 +53339,28 @@ discarding any comments. The URIs are not validated. version="2.66" throws="1"> Parses @uri_string according to @flags. If the result is not a -valid [absolute URI][relative-absolute-uris], it will be discarded, and an + filename="glib/guri.c" + line="1385">Parses @uri_string according to @flags. If the result is not a +valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an error returned. - + a new #GUri, or NULL on error. + filename="glib/guri.c" + line="1395">a new #GUri, or NULL on error. a string representing an absolute URI + filename="glib/guri.c" + line="1387">a string representing an absolute URI flags describing how to parse @uri_string + filename="glib/guri.c" + line="1388">flags describing how to parse @uri_string @@ -48031,8 +53370,8 @@ error returned. version="2.66" throws="1"> Many URI schemes include one or more attribute/value pairs as part of the URI + filename="glib/guri.c" + line="2284">Many URI schemes include one or more attribute/value pairs as part of the URI value. This method can be used to parse them into a hash table. When an attribute has multiple occurrences, the last value is the final returned value. If you need to handle repeated attributes differently, use @@ -48056,11 +53395,11 @@ the returned attributes. If @params cannot be parsed (for example, it contains two @separators characters in a row), then @error is set and %NULL is returned. - + + filename="glib/guri.c" + line="2322"> A hash table of attribute/value pairs, with both names and values fully-decoded; or %NULL on error. @@ -48071,21 +53410,21 @@ characters in a row), then @error is set and %NULL is returned. a `%`-encoded string containing `attribute=value` + filename="glib/guri.c" + line="2286">a `%`-encoded string containing `attribute=value` parameters the length of @params, or `-1` if it is nul-terminated + filename="glib/guri.c" + line="2288">the length of @params, or `-1` if it is nul-terminated the separator byte character set between parameters. (usually + filename="glib/guri.c" + line="2289">the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case @@ -48094,8 +53433,8 @@ characters in a row), then @error is set and %NULL is returned. flags to modify the way the parameters are handled. + filename="glib/guri.c" + line="2294">flags to modify the way the parameters are handled. @@ -48104,27 +53443,27 @@ characters in a row), then @error is set and %NULL is returned. c:identifier="g_uri_parse_scheme" version="2.16"> Gets the scheme portion of a URI string. + filename="glib/guri.c" + line="2838">Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include `file`, `https`, `svn+ssh`, etc. - + The ‘scheme’ component of the URI, or + filename="glib/guri.c" + line="2850">The ‘scheme’ component of the URI, or %NULL on error. The returned string should be freed when no longer needed. a valid URI. + filename="glib/guri.c" + line="2840">a valid URI. @@ -48133,8 +53472,8 @@ Common schemes include `file`, `https`, `svn+ssh`, etc. c:identifier="g_uri_peek_scheme" version="2.66"> Gets the scheme portion of a URI string. + filename="glib/guri.c" + line="2866">Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ @@ -48144,11 +53483,11 @@ Common schemes include `file`, `https`, `svn+ssh`, etc. Unlike g_uri_parse_scheme(), the returned scheme is normalized to all-lowercase and does not need to be freed. - + The ‘scheme’ component of the URI, or + filename="glib/guri.c" + line="2881">The ‘scheme’ component of the URI, or %NULL on error. The returned string is normalized to all-lowercase, and interned via g_intern_string(), so it does not need to be freed. @@ -48156,8 +53495,8 @@ all-lowercase and does not need to be freed. a valid URI. + filename="glib/guri.c" + line="2868">a valid URI. @@ -48167,19 +53506,19 @@ all-lowercase and does not need to be freed. version="2.66" throws="1"> Parses @uri_ref according to @flags and, if it is a -[relative URI][relative-absolute-uris], resolves it relative to + filename="glib/guri.c" + line="1553">Parses @uri_ref according to @flags and, if it is a +[relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned. (If @base_uri_string is %NULL, this just returns @uri_ref, or %NULL if @uri_ref is invalid or not absolute.) - + the resolved URI string, + filename="glib/guri.c" + line="1568">the resolved URI string, or NULL on error. @@ -48189,20 +53528,20 @@ or NULL on error. nullable="1" allow-none="1"> a string representing a base URI + filename="glib/guri.c" + line="1555">a string representing a base URI a string representing a relative or absolute URI + filename="glib/guri.c" + line="1556">a string representing a relative or absolute URI flags describing how to parse @uri_ref + filename="glib/guri.c" + line="1557">flags describing how to parse @uri_ref @@ -48212,9 +53551,9 @@ or NULL on error. version="2.66" throws="1"> Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and + filename="glib/guri.c" + line="1045">Parses @uri_ref (which can be an +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -48229,25 +53568,25 @@ Note that the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), since it always returns only the full userinfo; use g_uri_split_with_user() if you want it split up. - + %TRUE if @uri_ref parsed successfully, %FALSE + filename="glib/guri.c" + line="1082">%TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI + filename="glib/guri.c" + line="1047">a string containing a relative or absolute URI flags for parsing @uri_ref + filename="glib/guri.c" + line="1048">flags for parsing @uri_ref optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1049">on return, contains the scheme (converted to lowercase), or %NULL @@ -48271,8 +53610,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1051">on return, contains the userinfo, or %NULL @@ -48284,8 +53623,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1053">on return, contains the host, or %NULL @@ -48296,8 +53635,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1055">on return, contains the port, or `-1` @@ -48308,8 +53647,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1057">on return, contains the path @@ -48321,8 +53660,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1059">on return, contains the query, or %NULL @@ -48334,8 +53673,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1061">on return, contains the fragment, or %NULL @@ -48346,32 +53685,32 @@ g_uri_split_with_user() if you want it split up. version="2.66" throws="1"> Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) + filename="glib/guri.c" + line="1173">Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces relevant to connecting to a host. See the documentation for g_uri_split() for more details; this is mostly a wrapper around that function with simpler arguments. However, it will return an error if @uri_string is a relative URI, or does not contain a hostname component. - + %TRUE if @uri_string parsed successfully, + filename="glib/guri.c" + line="1192">%TRUE if @uri_string parsed successfully, %FALSE on error. a string containing an absolute URI + filename="glib/guri.c" + line="1175">a string containing an absolute URI flags for parsing @uri_string + filename="glib/guri.c" + line="1176">flags for parsing @uri_string optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1177">on return, contains the scheme (converted to lowercase), or %NULL @@ -48395,8 +53734,8 @@ or does not contain a hostname component. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1179">on return, contains the host, or %NULL @@ -48407,8 +53746,8 @@ or does not contain a hostname component. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1181">on return, contains the port, or `-1` @@ -48419,9 +53758,9 @@ or does not contain a hostname component. version="2.66" throws="1"> Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and + filename="glib/guri.c" + line="1108">Parses @uri_ref (which can be an +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -48431,25 +53770,25 @@ information on the effect of @flags. Note that @password will only be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and @auth_params will only be parsed out if @flags contains %G_URI_FLAGS_HAS_AUTH_PARAMS. - + %TRUE if @uri_ref parsed successfully, %FALSE + filename="glib/guri.c" + line="1144">%TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI + filename="glib/guri.c" + line="1110">a string containing a relative or absolute URI flags for parsing @uri_ref + filename="glib/guri.c" + line="1111">flags for parsing @uri_ref on return, contains + filename="glib/guri.c" + line="1112">on return, contains the scheme (converted to lowercase), or %NULL @@ -48473,8 +53812,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1114">on return, contains the user, or %NULL @@ -48486,8 +53825,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1116">on return, contains the password, or %NULL @@ -48499,8 +53838,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1118">on return, contains the auth_params, or %NULL @@ -48512,8 +53851,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1120">on return, contains the host, or %NULL @@ -48524,8 +53863,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1122">on return, contains the port, or `-1` @@ -48536,8 +53875,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1124">on return, contains the path @@ -48549,8 +53888,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1126">on return, contains the query, or %NULL @@ -48562,8 +53901,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1128">on return, contains the fragment, or %NULL @@ -48574,8 +53913,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and version="2.66" throws="1"> Unescapes a segment of an escaped string as binary data. + filename="glib/guri.c" + line="2725">Unescapes a segment of an escaped string as binary data. Note that in contrast to g_uri_unescape_string(), this does allow nul bytes to appear in the output. @@ -48585,11 +53924,11 @@ character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - + an unescaped version of @escaped_string + filename="glib/guri.c" + line="2745">an unescaped version of @escaped_string or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error code). The returned #GBytes should be unreffed when no longer needed. @@ -48597,14 +53936,14 @@ handling. A URI-escaped string + filename="glib/guri.c" + line="2727">A URI-escaped string the length (in bytes) of @escaped_string to escape, or `-1` if it + filename="glib/guri.c" + line="2728">the length (in bytes) of @escaped_string to escape, or `-1` if it is nul-terminated. @@ -48613,8 +53952,8 @@ handling. nullable="1" allow-none="1"> a string of illegal characters + filename="glib/guri.c" + line="2730">a string of illegal characters not to be allowed, or %NULL. @@ -48624,8 +53963,8 @@ handling. c:identifier="g_uri_unescape_segment" version="2.16"> Unescapes a segment of an escaped string. + filename="glib/guri.c" + line="2601">Unescapes a segment of an escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then @@ -48635,11 +53974,11 @@ escaped path element, which might confuse pathname handling. Note: `NUL` byte is not accepted in the output, in contrast to g_uri_unescape_bytes(). - + an unescaped version of @escaped_string, + filename="glib/guri.c" + line="2620">an unescaped version of @escaped_string, or %NULL on error. The returned string should be freed when no longer needed. As a special case if %NULL is given for @escaped_string, this function will return %NULL. @@ -48651,8 +53990,8 @@ function will return %NULL. nullable="1" allow-none="1"> A string, may be %NULL + filename="glib/guri.c" + line="2603">A string, may be %NULL nullable="1" allow-none="1"> Pointer to end of @escaped_string, + filename="glib/guri.c" + line="2604">Pointer to end of @escaped_string, may be %NULL @@ -48670,8 +54009,8 @@ function will return %NULL. nullable="1" allow-none="1"> An optional string of illegal + filename="glib/guri.c" + line="2606">An optional string of illegal characters not to be allowed, may be %NULL @@ -48681,27 +54020,27 @@ function will return %NULL. c:identifier="g_uri_unescape_string" version="2.16"> Unescapes a whole escaped string. + filename="glib/guri.c" + line="2662">Unescapes a whole escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - + an unescaped version of @escaped_string. + filename="glib/guri.c" + line="2676">an unescaped version of @escaped_string. The returned string should be freed when no longer needed. an escaped string to be unescaped. + filename="glib/guri.c" + line="2664">an escaped string to be unescaped. nullable="1" allow-none="1"> a string of illegal characters + filename="glib/guri.c" + line="2665">a string of illegal characters not to be allowed, or %NULL. @@ -48722,12 +54061,12 @@ The returned string should be freed when no longer needed. c:type="GUriError" glib:error-domain="g-uri-quark"> Error codes returned by #GUri methods. - + Generic error if no more specific error is available. See the error message for details. @@ -48735,76 +54074,76 @@ The returned string should be freed when no longer needed. value="1" c:identifier="G_URI_ERROR_BAD_SCHEME"> The scheme of a URI could not be parsed. The user/userinfo of a URI could not be parsed. The password of a URI could not be parsed. The authentication parameters of a URI could not be parsed. The host of a URI could not be parsed. The port of a URI could not be parsed. The path of a URI could not be parsed. The query of a URI could not be parsed. The fragment of a URI could not be parsed. Flags that describe a URI. When parsing a URI, if you need to choose different flags based on the type of URI, you can use g_uri_peek_scheme() on the URI string to check the scheme first, and use that to decide what flags to parse it with. - + No flags set. Parse the URI more relaxedly than the [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies, fixing up or ignoring common mistakes in URIs coming from external @@ -48815,7 +54154,7 @@ parse it with. value="2" c:identifier="G_URI_FLAGS_HAS_PASSWORD"> The userinfo field may contain a password, which will be separated from the username by `:`. @@ -48823,14 +54162,14 @@ parse it with. value="4" c:identifier="G_URI_FLAGS_HAS_AUTH_PARAMS"> The userinfo may contain additional authentication-related parameters, which will be separated from the username and/or password by `;`. When parsing a URI, this indicates that `%`-encoded characters in the userinfo, path, query, and fragment fields should not be decoded. (And likewise the host field if @@ -48840,7 +54179,7 @@ parse it with. The host component should not be assumed to be a DNS hostname or IP address (for example, for `smb` URIs with NetBIOS hostnames). @@ -48849,7 +54188,7 @@ parse it with. value="32" c:identifier="G_URI_FLAGS_ENCODED_QUERY"> Same as %G_URI_FLAGS_ENCODED, for the query field only. @@ -48857,14 +54196,14 @@ parse it with. value="64" c:identifier="G_URI_FLAGS_ENCODED_PATH"> Same as %G_URI_FLAGS_ENCODED, for the path only. Same as %G_URI_FLAGS_ENCODED, for the fragment only. @@ -48872,7 +54211,7 @@ parse it with. value="256" c:identifier="G_URI_FLAGS_SCHEME_NORMALIZE"> A scheme-based normalization will be applied. For example, when parsing an HTTP URI changing omitted path to `/` and omitted port to `80`; and when building a URI, changing empty path to `/` @@ -48881,66 +54220,66 @@ parse it with. Flags describing what parts of the URI to hide in g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and %G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with the corresponding flags. - + No flags set. Hide the userinfo. Hide the password. Hide the auth_params. Hide the query. Hide the fragment. Flags modifying the way parameters are handled by g_uri_parse_params() and #GUriParamsIter. - + No flags set. Parameter names are case insensitive. Replace `+` with space character. Only useful for URLs on the web, using the `https` or `http` schemas. @@ -48948,14 +54287,14 @@ the corresponding flags. value="4" c:identifier="G_URI_PARAMS_PARSE_RELAXED"> See %G_URI_FLAGS_PARSE_RELAXED. Many URI schemes include one or more attribute/value pairs as part of the URI + filename="glib/guri.c" + line="2089">Many URI schemes include one or more attribute/value pairs as part of the URI value. For example `scheme://server/path?query=string&is=there` has two attributes – `query=string` and `is=there` – in its query part. @@ -48964,7 +54303,7 @@ iterate over the attribute/value pairs of a URI query string. #GUriParamsIter structures are typically allocated on the stack and then initialized with g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init() for a usage example. - + @@ -48981,8 +54320,8 @@ for a usage example. Initializes an attribute/value pair iterator. + filename="glib/guri.c" + line="2115">Initializes an attribute/value pair iterator. The iterator keeps pointers to the @params and @separators arguments, those variables must thus outlive the iterator and not be modified during the @@ -49015,34 +54354,34 @@ while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, if (error) // handle parsing error ]| - + an uninitialized #GUriParamsIter + filename="glib/guri.c" + line="2117">an uninitialized #GUriParamsIter a `%`-encoded string containing `attribute=value` + filename="glib/guri.c" + line="2118">a `%`-encoded string containing `attribute=value` parameters the length of @params, or `-1` if it is nul-terminated + filename="glib/guri.c" + line="2120">the length of @params, or `-1` if it is nul-terminated the separator byte character set between parameters. (usually + filename="glib/guri.c" + line="2121">the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case @@ -49051,8 +54390,8 @@ if (error) flags to modify the way the parameters are handled. + filename="glib/guri.c" + line="2126">flags to modify the way the parameters are handled. @@ -49062,8 +54401,8 @@ if (error) version="2.66" throws="1"> Advances @iter and retrieves the next attribute/value. %FALSE is returned if + filename="glib/guri.c" + line="2193">Advances @iter and retrieves the next attribute/value. %FALSE is returned if an error has occurred (in which case @error is set), or if the end of the iteration is reached (in which case @attribute and @value are set to %NULL and the iterator becomes invalid). If %TRUE is returned, @@ -49072,19 +54411,19 @@ attribute/value pair. Note that the same @attribute may be returned multiple times, since URIs allow repeated attributes. - + %FALSE if the end of the parameters has been reached or an error was + filename="glib/guri.c" + line="2212">%FALSE if the end of the parameters has been reached or an error was encountered. %TRUE otherwise. an initialized #GUriParamsIter + filename="glib/guri.c" + line="2195">an initialized #GUriParamsIter optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="2196">on return, contains the attribute, or %NULL. @@ -49108,8 +54447,8 @@ allow repeated attributes. optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="2198">on return, contains the value, or %NULL. @@ -49118,7 +54457,7 @@ allow repeated attributes. These are logical ids for special directories which are defined depending on the platform used. You should use g_get_user_special_dir() to retrieve the full path associated to the logical id. @@ -49126,68 +54465,68 @@ to retrieve the full path associated to the logical id. The #GUserDirectory enumeration can be extended at later date. Not every platform has a directory for every logical id in this enumeration. - + the user's Desktop directory the user's Documents directory the user's Downloads directory the user's Music directory the user's Pictures directory the user's shared directory the user's Templates directory the user's Movies directory the number of enum values @@ -49196,40 +54535,71 @@ enumeration. version="2.50" introspectable="0"> A stack-allocated #GVariantBuilder must be initialized if it is -used together with g_auto() to avoid warnings or crashes if -function returns before g_variant_builder_init() is called on the -builder. + filename="glib/gvariant.h" + line="343">A stack-allocated [struct@GLib.VariantBuilder] must be initialized +if it is used together with +[`g_auto()`](auto-cleanup.html#variable-declaration). This macro can +be used as initializer when declaring the builder, but it cannot be +assigned to a variable. -This macro can be used as initializer instead of an -explicit zeroing a variable when declaring it and a following -g_variant_builder_init(), but it cannot be assigned to a variable. +The effects of initializing the builder with +`G_VARIANT_BUILDER_INIT` is the same as initializing it with +[func@GLib.VARIANT_BUILDER_INIT_UNSET], followed by a call to +[method@GLib.VariantBuilder.init]. -The passed @variant_type should be a static GVariantType to avoid -lifetime issues, as copying the @variant_type does not happen in -the G_VARIANT_BUILDER_INIT() call, but rather in functions that -make sure that #GVariantBuilder is valid. +The passed @variant_type should be a static [type@GLib.VariantType] +to avoid lifetime issues, as copying the @variant_type does not +happen in the `G_VARIANT_BUILDER_INIT` call, but rather in functions +that make sure that [struct@GLib.VariantBuilder] is valid. -|[<!-- language="C" --> +```c g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); -]| - +``` + a const GVariantType* + + A stack-allocated [struct@GLib.VariantBuilder] must be initialized +if it is used together with +[`g_auto()`](auto-cleanup.html#variable-declaration). This macro can +be used as initializer when declaring the builder, but it cannot be +assigned to a variable. + +The builder can be initialized to a specific [type@GLib.VariantType] +later with [method@GLib.VariantBuilder.init]. + +Use [func@GLib.VARIANT_BUILDER_INIT] to directly initialize the +builder with a specific [type@GLib.VariantType]. + +```c + g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT_UNSET (); + + if (condition) + return NULL; + + g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{su}")); + return g_variant_ref_sink (g_variant_builder_end (&builder)); +``` + + A stack-allocated #GVariantDict must be initialized if it is used + filename="glib/gvariant.h" + line="499">A stack-allocated #GVariantDict must be initialized if it is used together with g_auto() to avoid warnings or crashes if function returns before g_variant_dict_init() is called on the builder. @@ -49250,12 +54620,12 @@ initialized with G_VARIANT_DICT_INIT(). g_autoptr(GVariant) variant = get_asv_variant (); g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); ]| - + a GVariant* + filename="glib/gvariant.h" + line="501">a GVariant* @@ -49263,27 +54633,28 @@ initialized with G_VARIANT_DICT_INIT(). c:identifier="G_VARIANT_TYPE" introspectable="0"> Converts a string to a const #GVariantType. Depending on the -current debugging level, this function may perform a runtime check -to ensure that @string is a valid GVariant type string. + filename="glib/gvarianttype.h" + line="282">Converts a string to a const [type@GLib.VariantType]. + +Depending on the current debugging level, this function may perform a runtime +check to ensure that @string is a valid [type@GLib.Variant] type string. It is always a programmer error to use this macro with an invalid -type string. If in doubt, use g_variant_type_string_is_valid() to +type string. If in doubt, use [func@GLib.variant_type_string_is_valid] to check if the string is valid. Since 2.24 - + a well-formed #GVariantType type string + filename="glib/gvarianttype.h" + line="284">a well-formed [type@GLib.VariantType] type string - + c:type="GLIB_VERSION_MIN_REQUIRED" version="2.32"> A macro that should be defined by the user prior to including + filename="glib/gversionmacros.h" + line="451">A macro that should be defined by the user prior to including the glib.h header. The definition should be one of the predefined GLib version macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... @@ -49304,122 +54675,126 @@ If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version %GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not). - + #GVariant is a variant datatype; it can contain one or more values + filename="glib/gvariant.c" + line="38">`GVariant` is a variant datatype; it can contain one or more values along with information about the type of the values. -A #GVariant may contain simple types, like an integer, or a boolean value; +A `GVariant` may contain simple types, like an integer, or a boolean value; or complex types, like an array of two strings, or a dictionary of key -value pairs. A #GVariant is also immutable: once it's been created neither +value pairs. A `GVariant` is also immutable: once it’s been created neither its type nor its content can be modified further. -GVariant is useful whenever data needs to be serialized, for example when -sending method parameters in D-Bus, or when saving settings using GSettings. +`GVariant` is useful whenever data needs to be serialized, for example when +sending method parameters in D-Bus, or when saving settings using +[`GSettings`](../gio/class.Settings.html). -When creating a new #GVariant, you pass the data you want to store in it +When creating a new `GVariant`, you pass the data you want to store in it along with a string representing the type of data you wish to pass to it. -For instance, if you want to create a #GVariant holding an integer value you +For instance, if you want to create a `GVariant` holding an integer value you can use: -|[<!-- language="C" --> - GVariant *v = g_variant_new ("u", 40); -]| +```c +GVariant *v = g_variant_new ("u", 40); +``` -The string "u" in the first argument tells #GVariant that the data passed to -the constructor (40) is going to be an unsigned integer. +The string `u` in the first argument tells `GVariant` that the data passed to +the constructor (`40`) is going to be an unsigned integer. -More advanced examples of #GVariant in use can be found in documentation for -[GVariant format strings][gvariant-format-strings-pointers]. +More advanced examples of `GVariant` in use can be found in documentation for +[`GVariant` format strings](gvariant-format-strings.html#pointers). The range of possible values is determined by the type. -The type system used by #GVariant is #GVariantType. +The type system used by `GVariant` is [type@GLib.VariantType]. -#GVariant instances always have a type and a value (which are given -at construction time). The type and value of a #GVariant instance -can never change other than by the #GVariant itself being -destroyed. A #GVariant cannot contain a pointer. +`GVariant` instances always have a type and a value (which are given +at construction time). The type and value of a `GVariant` instance +can never change other than by the `GVariant` itself being +destroyed. A `GVariant` cannot contain a pointer. -#GVariant is reference counted using g_variant_ref() and -g_variant_unref(). #GVariant also has floating reference counts -- -see g_variant_ref_sink(). +`GVariant` is reference counted using [method@GLib.Variant.ref] and +[method@GLib.Variant.unref]. `GVariant` also has floating reference counts — +see [method@GLib.Variant.ref_sink]. -#GVariant is completely threadsafe. A #GVariant instance can be +`GVariant` is completely threadsafe. A `GVariant` instance can be concurrently accessed in any way from any number of threads without problems. -#GVariant is heavily optimised for dealing with data in serialized +`GVariant` is heavily optimised for dealing with data in serialized form. It works particularly well with data located in memory-mapped files. It can perform nearly all deserialization operations in a small constant time, usually touching only a single memory page. -Serialized #GVariant data can also be sent over the network. +Serialized `GVariant` data can also be sent over the network. -#GVariant is largely compatible with D-Bus. Almost all types of -#GVariant instances can be sent over D-Bus. See #GVariantType for -exceptions. (However, #GVariant's serialization format is not the same -as the serialization format of a D-Bus message body: use #GDBusMessage, -in the gio library, for those.) +`GVariant` is largely compatible with D-Bus. Almost all types of +`GVariant` instances can be sent over D-Bus. See [type@GLib.VariantType] for +exceptions. (However, `GVariant`’s serialization format is not the same +as the serialization format of a D-Bus message body: use +[GDBusMessage](../gio/class.DBusMessage.html), in the GIO library, for those.) -For space-efficiency, the #GVariant serialization format does not -automatically include the variant's length, type or endianness, +For space-efficiency, the `GVariant` serialization format does not +automatically include the variant’s length, type or endianness, which must either be implied from context (such as knowledge that a particular file format always contains a little-endian -%G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) +`G_VARIANT_TYPE_VARIANT` which occupies the whole length of the file) or supplied out-of-band (for instance, a length, type and/or endianness indicator could be placed at the beginning of a file, network message or network stream). -A #GVariant's size is limited mainly by any lower level operating -system constraints, such as the number of bits in #gsize. For +A `GVariant`’s size is limited mainly by any lower level operating +system constraints, such as the number of bits in `gsize`. For example, it is reasonable to have a 2GB file mapped into memory -with #GMappedFile, and call g_variant_new_from_data() on it. +with [struct@GLib.MappedFile], and call [ctor@GLib.Variant.new_from_data] on +it. -For convenience to C programmers, #GVariant features powerful +For convenience to C programmers, `GVariant` features powerful varargs-based value construction and destruction. This feature is designed to be embedded in other libraries. -There is a Python-inspired text language for describing #GVariant -values. #GVariant includes a printer for this language and a parser +There is a Python-inspired text language for describing `GVariant` +values. `GVariant` includes a printer for this language and a parser with type inferencing. ## Memory Use -#GVariant tries to be quite efficient with respect to memory use. +`GVariant` tries to be quite efficient with respect to memory use. This section gives a rough idea of how much memory is used by the current implementation. The information here is subject to change in the future. -The memory allocated by #GVariant can be grouped into 4 broad +The memory allocated by `GVariant` can be grouped into 4 broad purposes: memory for serialized data, memory for the type information cache, buffer management memory and memory for the -#GVariant structure itself. +`GVariant` structure itself. ## Serialized Data Memory -This is the memory that is used for storing GVariant data in +This is the memory that is used for storing `GVariant` data in serialized form. This is what would be sent over the network or what would end up on disk, not counting any indicator of the endianness, or of the length or type of the top-level variant. The amount of memory required to store a boolean is 1 byte. 16, 32 and 64 bit integers and double precision floating point numbers -use their "natural" size. Strings (including object path and +use their ‘natural’ size. Strings (including object path and signature strings) are stored with a nul terminator, and as such use the length of the string plus 1 byte. -Maybe types use no space at all to represent the null value and +‘Maybe’ types use no space at all to represent the null value and use the same amount of space (sometimes plus one byte) as the equivalent non-maybe-typed value to represent the non-null case. @@ -49445,39 +54820,39 @@ As an example, consider a dictionary mapping strings to variants. In the case that the dictionary is empty, 0 bytes are required for the serialization. -If we add an item "width" that maps to the int32 value of 500 then -we will use 4 byte to store the int32 (so 6 for the variant +If we add an item ‘width’ that maps to the int32 value of 500 then +we will use 4 bytes to store the int32 (so 6 for the variant containing it) and 6 bytes for the string. The variant must be -aligned to 8 after the 6 bytes of the string, so that's 2 extra +aligned to 8 after the 6 bytes of the string, so that’s 2 extra bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used for the dictionary entry. An additional 1 byte is added to the array as a framing offset making a total of 15 bytes. -If we add another entry, "title" that maps to a nullable string +If we add another entry, ‘title’ that maps to a nullable string that happens to have a value of null, then we use 0 bytes for the null value (and 3 bytes for the variant to contain it along with its type string) plus 6 bytes for the string. Again, we need 2 padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. We now require extra padding between the two items in the array. -After the 14 bytes of the first item, that's 2 bytes required. +After the 14 bytes of the first item, that’s 2 bytes required. We now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item dictionary. ## Type Information Cache -For each GVariant type that currently exists in the program a type +For each `GVariant` type that currently exists in the program a type information structure is kept in the type information cache. The type information structure is required for rapid deserialization. -Continuing with the above example, if a #GVariant exists with the -type "a{sv}" then a type information struct will exist for -"a{sv}", "{sv}", "s", and "v". Multiple uses of the same type +Continuing with the above example, if a `GVariant` exists with the +type `a{sv}` then a type information struct will exist for +`a{sv}`, `{sv}`, `s`, and `v`. Multiple uses of the same type will share the same type information. Additionally, all single-digit types are stored in read-only static memory and do not contribute to the writable memory footprint of a program using -#GVariant. +`GVariant`. Aside from the type information structures stored in read-only memory, there are two forms of type information. One is used for @@ -49485,23 +54860,23 @@ container types where there is a single element type: arrays and maybe types. The other is used for container types where there are multiple element types: tuples and dictionary entries. -Array type info structures are 6 * sizeof (void *), plus the +Array type info structures are `6 * sizeof (void *)`, plus the memory required to store the type string itself. This means that -on 32-bit systems, the cache entry for "a{sv}" would require 30 -bytes of memory (plus malloc overhead). +on 32-bit systems, the cache entry for `a{sv}` would require 30 +bytes of memory (plus allocation overhead). -Tuple type info structures are 6 * sizeof (void *), plus 4 * -sizeof (void *) for each item in the tuple, plus the memory +Tuple type info structures are `6 * sizeof (void *)`, plus `4 * +sizeof (void *)` for each item in the tuple, plus the memory required to store the type string itself. A 2-item tuple, for example, would have a type information structure that consumed -writable memory in the size of 14 * sizeof (void *) (plus type +writable memory in the size of `14 * sizeof (void *)` (plus type string) This means that on 32-bit systems, the cache entry for -"{sv}" would require 61 bytes of memory (plus malloc overhead). +`{sv}` would require 61 bytes of memory (plus allocation overhead). -This means that in total, for our "a{sv}" example, 91 bytes of +This means that in total, for our `a{sv}` example, 91 bytes of type information would be allocated. -The type information cache, additionally, uses a #GHashTable to +The type information cache, additionally, uses a [struct@GLib.HashTable] to store and look up the cached items and stores a pointer to this hash table in static storage. The hash table is freed when there are zero items in the type cache. @@ -49513,34 +54888,34 @@ structure is required for many different values of the same type. ## Buffer Management Memory -#GVariant uses an internal buffer management structure to deal +`GVariant` uses an internal buffer management structure to deal with the various different possible sources of serialized data that it uses. The buffer is responsible for ensuring that the correct call is made when the data is no longer in use by -#GVariant. This may involve a g_free() or a g_slice_free() or -even g_mapped_file_unref(). +`GVariant`. This may involve a [func@GLib.free] or +even [method@GLib.MappedFile.unref]. One buffer management structure is used for each chunk of serialized data. The size of the buffer management structure -is 4 * (void *). On 32-bit systems, that's 16 bytes. +is `4 * (void *)`. On 32-bit systems, that’s 16 bytes. ## GVariant structure -The size of a #GVariant structure is 6 * (void *). On 32-bit -systems, that's 24 bytes. +The size of a `GVariant` structure is `6 * (void *)`. On 32-bit +systems, that’s 24 bytes. -#GVariant structures only exist if they are explicitly created -with API calls. For example, if a #GVariant is constructed out of +`GVariant` structures only exist if they are explicitly created +with API calls. For example, if a `GVariant` is constructed out of serialized data for the example given above (with the dictionary) then although there are 9 individual values that comprise the entire dictionary (two keys, two values, two variants containing the values, two dictionary entries, plus the dictionary itself), -only 1 #GVariant instance exists -- the one referring to the +only 1 `GVariant` instance exists — the one referring to the dictionary. If calls are made to start accessing the other values then -#GVariant instances will exist for those values only for as long -as they are in use (ie: until you call g_variant_unref()). The +`GVariant` instances will exist for those values only for as long +as they are in use (ie: until you call [method@GLib.Variant.unref]). The type information is shared. The serialized data and the buffer management structure for that serialized data is shared by the child. @@ -49551,27 +54926,27 @@ To put the entire example together, for our dictionary mapping strings to variants (with two entries, as given above), we are using 91 bytes of memory for type information, 29 bytes of memory for the serialized data, 16 bytes for buffer management and 24 -bytes for the #GVariant instance, or a total of 160 bytes, plus -malloc overhead. If we were to use g_variant_get_child_value() to -access the two dictionary entries, we would use an additional 48 +bytes for the `GVariant` instance, or a total of 160 bytes, plus +allocation overhead. If we were to use [method@GLib.Variant.get_child_value] +to access the two dictionary entries, we would use an additional 48 bytes. If we were to have other dictionaries of the same type, we would use more memory for the serialized data and buffer management for those dictionaries, but the type information would be shared. - + Creates a new #GVariant instance. + filename="glib/gvariant.c" + line="5429">Creates a new #GVariant instance. Think of this function as an analogue to g_strdup_printf(). The type of the created instance and the arguments that are expected by this function are determined by @format_string. See the section on -[GVariant format strings][gvariant-format-strings]. Please note that +[GVariant format strings](gvariant-format-strings.html). Please note that the syntax of the format string is very likely to be extended in the future. @@ -49581,7 +54956,7 @@ function (and not merely passed through it unmodified). Note that the arguments must be of the correct width for their types specified in @format_string. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. +the [GVariant varargs documentation](gvariant-format-strings.html#varargs). |[<!-- language="C" --> MyFlags some_flags = FLAG_ONE | FLAG_TWO; @@ -49593,24 +54968,24 @@ new_variant = g_variant_new ("(t^as)", (guint64) some_flags, some_strings); ]| - + a new floating #GVariant instance + filename="glib/gvariant.c" + line="5463">a new floating #GVariant instance a #GVariant format string + filename="glib/gvariant.c" + line="5431">a #GVariant format string arguments, as per @format_string + filename="glib/gvariant.c" + line="5432">arguments, as per @format_string @@ -49619,8 +54994,8 @@ new_variant = g_variant_new ("(t^as)", c:identifier="g_variant_new_array" version="2.24"> Creates a new #GVariant array from @children. + filename="glib/gvariant.c" + line="749">Creates a new #GVariant array from @children. @child_type must be non-%NULL if @n_children is zero. Otherwise, the child type is determined by inspecting the first element of the @@ -49635,11 +55010,11 @@ same as @child_type, if given. If the @children are floating references (see g_variant_ref_sink()), the new instance takes ownership of them as if via g_variant_ref_sink(). - + a floating reference to a new #GVariant array + filename="glib/gvariant.c" + line="772">a floating reference to a new #GVariant array @@ -49648,8 +55023,8 @@ new instance takes ownership of them as if via g_variant_ref_sink(). nullable="1" allow-none="1"> the element type of the new array + filename="glib/gvariant.c" + line="751">the element type of the new array nullable="1" allow-none="1"> an array of + filename="glib/gvariant.c" + line="752">an array of #GVariant pointers, the children @@ -49666,8 +55041,8 @@ new instance takes ownership of them as if via g_variant_ref_sink(). the length of @children + filename="glib/gvariant.c" + line="754">the length of @children @@ -49676,20 +55051,20 @@ new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_boolean" version="2.24"> Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. - + filename="glib/gvariant.c" + line="330">Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. + a floating reference to a new boolean #GVariant instance + filename="glib/gvariant.c" + line="336">a floating reference to a new boolean #GVariant instance a #gboolean value + filename="glib/gvariant.c" + line="332">a #gboolean value @@ -49698,20 +55073,20 @@ new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_byte" version="2.24"> Creates a new byte #GVariant instance. - + filename="glib/gvariant.c" + line="390">Creates a new byte #GVariant instance. + a floating reference to a new byte #GVariant instance + filename="glib/gvariant.c" + line="396">a floating reference to a new byte #GVariant instance a #guint8 value + filename="glib/gvariant.c" + line="392">a #guint8 value @@ -49720,25 +55095,25 @@ new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_bytestring" version="2.26"> Creates an array-of-bytes #GVariant with the contents of @string. + filename="glib/gvariant.c" + line="1825">Creates an array-of-bytes #GVariant with the contents of @string. This function is just like g_variant_new_string() except that the string need not be valid UTF-8. The nul terminator character at the end of the string is stored in the array. - + a floating reference to a new bytestring #GVariant instance + filename="glib/gvariant.c" + line="1837">a floating reference to a new bytestring #GVariant instance a normal + filename="glib/gvariant.c" + line="1827">a normal nul-terminated string in no particular encoding @@ -49750,31 +55125,31 @@ the array. c:identifier="g_variant_new_bytestring_array" version="2.26"> Constructs an array of bytestring #GVariant from the given array of + filename="glib/gvariant.c" + line="1931">Constructs an array of bytestring #GVariant from the given array of strings. If @length is -1 then @strv is %NULL-terminated. - + a new floating #GVariant instance + filename="glib/gvariant.c" + line="1941">a new floating #GVariant instance an array of strings + filename="glib/gvariant.c" + line="1933">an array of strings the length of @strv, or -1 + filename="glib/gvariant.c" + line="1934">the length of @strv, or -1 @@ -49783,30 +55158,30 @@ If @length is -1 then @strv is %NULL-terminated. c:identifier="g_variant_new_dict_entry" version="2.24"> Creates a new dictionary entry #GVariant. @key and @value must be + filename="glib/gvariant.c" + line="909">Creates a new dictionary entry #GVariant. @key and @value must be non-%NULL. @key must be a value of a basic type (ie: not a container). If the @key or @value are floating references (see g_variant_ref_sink()), the new instance takes ownership of them as if via g_variant_ref_sink(). - + a floating reference to a new dictionary entry #GVariant + filename="glib/gvariant.c" + line="920">a floating reference to a new dictionary entry #GVariant a basic #GVariant, the key + filename="glib/gvariant.c" + line="911">a basic #GVariant, the key a #GVariant, the value + filename="glib/gvariant.c" + line="912">a #GVariant, the value @@ -49815,20 +55190,20 @@ the new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_double" version="2.24"> Creates a new double #GVariant instance. - + filename="glib/gvariant.c" + line="598">Creates a new double #GVariant instance. + a floating reference to a new double #GVariant instance + filename="glib/gvariant.c" + line="604">a floating reference to a new double #GVariant instance a #gdouble floating point value + filename="glib/gvariant.c" + line="600">a #gdouble floating point value @@ -49837,8 +55212,8 @@ the new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_fixed_array" version="2.32"> Constructs a new array #GVariant instance, where the elements are + filename="glib/gvariant.c" + line="1183">Constructs a new array #GVariant instance, where the elements are of @element_type type. @elements must be an array with fixed-sized elements. Numeric types are @@ -49851,18 +55226,18 @@ of a double-check that the form of the serialized data matches the caller's expectation. @n_elements must be the length of the @elements array. - + a floating reference to a new array #GVariant instance + filename="glib/gvariant.c" + line="1204">a floating reference to a new array #GVariant instance the #GVariantType of each element + filename="glib/gvariant.c" + line="1185">the #GVariantType of each element a pointer to the fixed array of contiguous elements + filename="glib/gvariant.c" + line="1186">a pointer to the fixed array of contiguous elements the number of elements + filename="glib/gvariant.c" + line="1187">the number of elements the size of each element + filename="glib/gvariant.c" + line="1188">the size of each element @@ -49892,8 +55267,8 @@ expectation. c:identifier="g_variant_new_from_bytes" version="2.36"> Constructs a new serialized-mode #GVariant instance. This is the + filename="glib/gvariant-core.c" + line="594">Constructs a new serialized-mode #GVariant instance. This is the inner interface for creation of new serialized values that gets called from various functions in gvariant.c. @@ -49902,30 +55277,30 @@ A reference is taken on @bytes. The data in @bytes must be aligned appropriately for the @type being loaded. Otherwise this function will internally create a copy of the memory (since GLib 2.60) or (in older versions) fail and exit the process. - + a new #GVariant with a floating reference + filename="glib/gvariant-core.c" + line="610">a new #GVariant with a floating reference a #GVariantType + filename="glib/gvariant-core.c" + line="596">a #GVariantType a #GBytes + filename="glib/gvariant-core.c" + line="597">a #GBytes if the contents of @bytes are trusted + filename="glib/gvariant-core.c" + line="598">if the contents of @bytes are trusted @@ -49934,8 +55309,8 @@ GLib 2.60) or (in older versions) fail and exit the process. c:identifier="g_variant_new_from_data" version="2.24"> Creates a new #GVariant instance from serialized data. + filename="glib/gvariant.c" + line="6228">Creates a new #GVariant instance from serialized data. @type is the type of #GVariant instance that will be constructed. The interpretation of @data depends on knowing the type. @@ -49964,44 +55339,44 @@ Note: @data must be backed by memory that is aligned appropriately for the @type being loaded. Otherwise this function will internally create a copy of the memory (since GLib 2.60) or (in older versions) fail and exit the process. - + a new floating #GVariant of type @type + filename="glib/gvariant.c" + line="6267">a new floating #GVariant of type @type a definite #GVariantType + filename="glib/gvariant.c" + line="6230">a definite #GVariantType the serialized data + filename="glib/gvariant.c" + line="6231">the serialized data the size of @data + filename="glib/gvariant.c" + line="6232">the size of @data %TRUE if @data is definitely in normal form + filename="glib/gvariant.c" + line="6233">%TRUE if @data is definitely in normal form function to call when @data is no longer needed + filename="glib/gvariant.c" + line="6234">function to call when @data is no longer needed nullable="1" allow-none="1"> data for @notify + filename="glib/gvariant.c" + line="6235">data for @notify @@ -50019,24 +55394,24 @@ process. c:identifier="g_variant_new_handle" version="2.24"> Creates a new handle #GVariant instance. + filename="glib/gvariant.c" + line="565">Creates a new handle #GVariant instance. By convention, handles are indexes into an array of file descriptors that are sent alongside a D-Bus message. If you're not interacting with D-Bus, you probably don't need them. - + a floating reference to a new handle #GVariant instance + filename="glib/gvariant.c" + line="575">a floating reference to a new handle #GVariant instance a #gint32 value + filename="glib/gvariant.c" + line="567">a #gint32 value @@ -50045,20 +55420,20 @@ with D-Bus, you probably don't need them. c:identifier="g_variant_new_int16" version="2.24"> Creates a new int16 #GVariant instance. - + filename="glib/gvariant.c" + line="415">Creates a new int16 #GVariant instance. + a floating reference to a new int16 #GVariant instance + filename="glib/gvariant.c" + line="421">a floating reference to a new int16 #GVariant instance a #gint16 value + filename="glib/gvariant.c" + line="417">a #gint16 value @@ -50067,20 +55442,20 @@ with D-Bus, you probably don't need them. c:identifier="g_variant_new_int32" version="2.24"> Creates a new int32 #GVariant instance. - + filename="glib/gvariant.c" + line="465">Creates a new int32 #GVariant instance. + a floating reference to a new int32 #GVariant instance + filename="glib/gvariant.c" + line="471">a floating reference to a new int32 #GVariant instance a #gint32 value + filename="glib/gvariant.c" + line="467">a #gint32 value @@ -50089,20 +55464,20 @@ with D-Bus, you probably don't need them. c:identifier="g_variant_new_int64" version="2.24"> Creates a new int64 #GVariant instance. - + filename="glib/gvariant.c" + line="515">Creates a new int64 #GVariant instance. + a floating reference to a new int64 #GVariant instance + filename="glib/gvariant.c" + line="521">a floating reference to a new int64 #GVariant instance a #gint64 value + filename="glib/gvariant.c" + line="517">a #gint64 value @@ -50111,8 +55486,8 @@ with D-Bus, you probably don't need them. c:identifier="g_variant_new_maybe" version="2.24"> Depending on if @child is %NULL, either wraps @child inside of a + filename="glib/gvariant.c" + line="624">Depending on if @child is %NULL, either wraps @child inside of a maybe container or creates a Nothing instance for the given @type. At least one of @child_type and @child must be non-%NULL. @@ -50122,11 +55497,11 @@ of @child. If @child is a floating reference (see g_variant_ref_sink()), the new instance takes ownership of @child. - + a floating reference to a new #GVariant maybe instance + filename="glib/gvariant.c" + line="640">a floating reference to a new #GVariant maybe instance @@ -50135,8 +55510,8 @@ instance takes ownership of @child. nullable="1" allow-none="1"> the #GVariantType of the child, or %NULL + filename="glib/gvariant.c" + line="626">the #GVariantType of the child, or %NULL nullable="1" allow-none="1"> the child value, or %NULL + filename="glib/gvariant.c" + line="627">the child value, or %NULL @@ -50154,22 +55529,22 @@ instance takes ownership of @child. c:identifier="g_variant_new_object_path" version="2.24"> Creates a D-Bus object path #GVariant with the contents of @object_path. + filename="glib/gvariant.c" + line="1356">Creates a D-Bus object path #GVariant with the contents of @object_path. @object_path must be a valid D-Bus object path. Use g_variant_is_object_path() if you're not sure. - + a floating reference to a new object path #GVariant instance + filename="glib/gvariant.c" + line="1364">a floating reference to a new object path #GVariant instance a normal C nul-terminated string + filename="glib/gvariant.c" + line="1358">a normal C nul-terminated string @@ -50178,34 +55553,34 @@ g_variant_is_object_path() if you're not sure. c:identifier="g_variant_new_objv" version="2.30"> Constructs an array of object paths #GVariant from the given array of + filename="glib/gvariant.c" + line="1687">Constructs an array of object paths #GVariant from the given array of strings. Each string must be a valid #GVariant object path; see g_variant_is_object_path(). If @length is -1 then @strv is %NULL-terminated. - + a new floating #GVariant instance + filename="glib/gvariant.c" + line="1700">a new floating #GVariant instance an array of strings + filename="glib/gvariant.c" + line="1689">an array of strings the length of @strv, or -1 + filename="glib/gvariant.c" + line="1690">the length of @strv, or -1 @@ -50214,8 +55589,8 @@ If @length is -1 then @strv is %NULL-terminated. c:identifier="g_variant_new_parsed" introspectable="0"> Parses @format and returns the result. + filename="glib/gvariant-parser.c" + line="2656">Parses @format and returns the result. @format must be a text format #GVariant with one extension: at any point that a value may appear in the text, a '%' character followed @@ -50225,7 +55600,7 @@ g_variant_new() would have collected. Note that the arguments must be of the correct width for their types specified in @format. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. +the [GVariant varargs documentation](gvariant-format-strings.html#varargs). Consider this simple example: |[<!-- language="C" --> @@ -50247,24 +55622,24 @@ You may not use this function to return, unmodified, a single #GVariant pointer from the argument list. ie: @format may not solely be anything along the lines of "%*", "%?", "\%r", or anything starting with "%@". - + a new floating #GVariant instance + filename="glib/gvariant-parser.c" + line="2694">a new floating #GVariant instance a text format #GVariant + filename="glib/gvariant-parser.c" + line="2658">a text format #GVariant arguments as per @format + filename="glib/gvariant-parser.c" + line="2659">arguments as per @format @@ -50273,8 +55648,8 @@ with "%@". c:identifier="g_variant_new_parsed_va" introspectable="0"> Parses @format and returns the result. + filename="glib/gvariant-parser.c" + line="2594">Parses @format and returns the result. This is the version of g_variant_new_parsed() intended to be used from libraries. @@ -50287,7 +55662,7 @@ additional references. Note that the arguments in @app must be of the correct width for their types specified in @format when collected into the #va_list. See -the [GVariant varargs documentation][gvariant-varargs]. +the [GVariant varargs documentation](gvariant-format-strings.html#varargs). In order to behave correctly in all cases it is necessary for the calling function to g_variant_ref_sink() the return result before @@ -50295,24 +55670,24 @@ returning control to the user that originally provided the pointer. At this point, the caller will have their own full reference to the result. This can also be done by adding the result to a container, or by passing it to another g_variant_new() call. - + a new, usually floating, #GVariant + filename="glib/gvariant-parser.c" + line="2621">a new, usually floating, #GVariant a text format #GVariant + filename="glib/gvariant-parser.c" + line="2596">a text format #GVariant a pointer to a #va_list + filename="glib/gvariant-parser.c" + line="2597">a pointer to a #va_list @@ -50322,31 +55697,31 @@ or by passing it to another g_variant_new() call. version="2.38" introspectable="0"> Creates a string-type GVariant using printf formatting. + filename="glib/gvariant.c" + line="1319">Creates a string-type GVariant using printf formatting. This is similar to calling g_strdup_printf() and then g_variant_new_string() but it saves a temporary variable and an unnecessary copy. - + a floating reference to a new string + filename="glib/gvariant.c" + line="1330">a floating reference to a new string #GVariant instance a printf-style format string + filename="glib/gvariant.c" + line="1321">a printf-style format string arguments for @format_string + filename="glib/gvariant.c" + line="1322">arguments for @format_string @@ -50355,22 +55730,22 @@ unnecessary copy. c:identifier="g_variant_new_signature" version="2.24"> Creates a D-Bus type signature #GVariant with the contents of + filename="glib/gvariant.c" + line="1402">Creates a D-Bus type signature #GVariant with the contents of @string. @string must be a valid D-Bus type signature. Use g_variant_is_signature() if you're not sure. - + a floating reference to a new signature #GVariant instance + filename="glib/gvariant.c" + line="1410">a floating reference to a new signature #GVariant instance a normal C nul-terminated string + filename="glib/gvariant.c" + line="1404">a normal C nul-terminated string @@ -50379,24 +55754,24 @@ g_variant_is_signature() if you're not sure. c:identifier="g_variant_new_string" version="2.24"> Creates a string #GVariant with the contents of @string. + filename="glib/gvariant.c" + line="1249">Creates a string #GVariant with the contents of @string. @string must be valid UTF-8, and must not be %NULL. To encode potentially-%NULL strings, use g_variant_new() with `ms` as the -[format string][gvariant-format-strings-maybe-types]. - +[format string](gvariant-format-strings.html#maybe-types). + a floating reference to a new string #GVariant instance + filename="glib/gvariant.c" + line="1259">a floating reference to a new string #GVariant instance a normal UTF-8 nul-terminated string + filename="glib/gvariant.c" + line="1251">a normal UTF-8 nul-terminated string @@ -50405,31 +55780,31 @@ potentially-%NULL strings, use g_variant_new() with `ms` as the c:identifier="g_variant_new_strv" version="2.24"> Constructs an array of strings #GVariant from the given array of + filename="glib/gvariant.c" + line="1553">Constructs an array of strings #GVariant from the given array of strings. If @length is -1 then @strv is %NULL-terminated. - + a new floating #GVariant instance + filename="glib/gvariant.c" + line="1563">a new floating #GVariant instance an array of strings + filename="glib/gvariant.c" + line="1555">an array of strings the length of @strv, or -1 + filename="glib/gvariant.c" + line="1556">the length of @strv, or -1 @@ -50439,8 +55814,8 @@ If @length is -1 then @strv is %NULL-terminated. version="2.38" introspectable="0"> Creates a string #GVariant with the contents of @string. + filename="glib/gvariant.c" + line="1279">Creates a string #GVariant with the contents of @string. @string must be valid UTF-8, and must not be %NULL. To encode potentially-%NULL strings, use this with g_variant_new_maybe(). @@ -50452,19 +55827,19 @@ allocated and will eventually be freed with g_free(). You must not modify or access @string in any other way after passing it to this function. It is even possible that @string is immediately freed. - + a floating reference to a new string + filename="glib/gvariant.c" + line="1296">a floating reference to a new string #GVariant instance a normal UTF-8 nul-terminated string + filename="glib/gvariant.c" + line="1281">a normal UTF-8 nul-terminated string @@ -50473,8 +55848,8 @@ freed. c:identifier="g_variant_new_tuple" version="2.24"> Creates a new tuple #GVariant out of the items in @children. The + filename="glib/gvariant.c" + line="846">Creates a new tuple #GVariant out of the items in @children. The type is determined from the types of @children. No entry in the @children array may be %NULL. @@ -50482,26 +55857,26 @@ If @n_children is 0 then the unit tuple is constructed. If the @children are floating references (see g_variant_ref_sink()), the new instance takes ownership of them as if via g_variant_ref_sink(). - + a floating reference to a new #GVariant tuple + filename="glib/gvariant.c" + line="860">a floating reference to a new #GVariant tuple the items to make the tuple out of + filename="glib/gvariant.c" + line="848">the items to make the tuple out of the length of @children + filename="glib/gvariant.c" + line="849">the length of @children @@ -50510,20 +55885,20 @@ new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_uint16" version="2.24"> Creates a new uint16 #GVariant instance. - + filename="glib/gvariant.c" + line="440">Creates a new uint16 #GVariant instance. + a floating reference to a new uint16 #GVariant instance + filename="glib/gvariant.c" + line="446">a floating reference to a new uint16 #GVariant instance a #guint16 value + filename="glib/gvariant.c" + line="442">a #guint16 value @@ -50532,20 +55907,20 @@ new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_uint32" version="2.24"> Creates a new uint32 #GVariant instance. - + filename="glib/gvariant.c" + line="490">Creates a new uint32 #GVariant instance. + a floating reference to a new uint32 #GVariant instance + filename="glib/gvariant.c" + line="496">a floating reference to a new uint32 #GVariant instance a #guint32 value + filename="glib/gvariant.c" + line="492">a #guint32 value @@ -50554,20 +55929,20 @@ new instance takes ownership of them as if via g_variant_ref_sink(). c:identifier="g_variant_new_uint64" version="2.24"> Creates a new uint64 #GVariant instance. - + filename="glib/gvariant.c" + line="540">Creates a new uint64 #GVariant instance. + a floating reference to a new uint64 #GVariant instance + filename="glib/gvariant.c" + line="546">a floating reference to a new uint64 #GVariant instance a #guint64 value + filename="glib/gvariant.c" + line="542">a #guint64 value @@ -50577,8 +55952,8 @@ new instance takes ownership of them as if via g_variant_ref_sink(). version="2.24" introspectable="0"> This function is intended to be used by libraries based on + filename="glib/gvariant.c" + line="5486">This function is intended to be used by libraries based on #GVariant that want to provide g_variant_new()-like functionality to their users. @@ -50596,7 +55971,7 @@ pointing to the argument following the last. Note that the arguments in @app must be of the correct width for their types specified in @format_string when collected into the #va_list. -See the [GVariant varargs documentation][gvariant-varargs]. +See the [GVariant varargs documentation](gvariant-format-strings.html#varargs). These two generalisations allow mixing of multiple calls to g_variant_new_va() and g_variant_get_va() within a single actual @@ -50614,18 +55989,18 @@ returning control to the user that originally provided the pointer. At this point, the caller will have their own full reference to the result. This can also be done by adding the result to a container, or by passing it to another g_variant_new() call. - + a new, usually floating, #GVariant + filename="glib/gvariant.c" + line="5530">a new, usually floating, #GVariant a string that is prefixed with a format string + filename="glib/gvariant.c" + line="5488">a string that is prefixed with a format string nullable="1" allow-none="1"> location to store the end pointer, + filename="glib/gvariant.c" + line="5489">location to store the end pointer, or %NULL a pointer to a #va_list + filename="glib/gvariant.c" + line="5491">a pointer to a #va_list @@ -50650,32 +56025,32 @@ or by passing it to another g_variant_new() call. c:identifier="g_variant_new_variant" version="2.24"> Boxes @value. The result is a #GVariant instance representing a + filename="glib/gvariant.c" + line="704">Boxes @value. The result is a #GVariant instance representing a variant containing the original value. If @child is a floating reference (see g_variant_ref_sink()), the new instance takes ownership of @child. - + a floating reference to a new variant #GVariant instance + filename="glib/gvariant.c" + line="714">a floating reference to a new variant #GVariant instance a #GVariant instance + filename="glib/gvariant.c" + line="706">a #GVariant instance Performs a byteswapping operation on the contents of @value. The + filename="glib/gvariant.c" + line="6158">Performs a byteswapping operation on the contents of @value. The result is that all multi-byte numeric data contained in @value is byteswapped. That includes 16, 32, and 64bit signed and unsigned integers as well as file handles and double precision floating point @@ -50692,18 +56067,18 @@ application can be strict about what inputs it rejects. The returned value is always in normal form and is marked as trusted. A full, not floating, reference is returned. - + the byteswapped form of @value + filename="glib/gvariant.c" + line="6180">the byteswapped form of @value a #GVariant + filename="glib/gvariant.c" + line="6160">a #GVariant @@ -50712,8 +56087,8 @@ A full, not floating, reference is returned. c:identifier="g_variant_check_format_string" version="2.34"> Checks if calling g_variant_get() with @format_string on @value would + filename="glib/gvariant.c" + line="4540">Checks if calling g_variant_get() with @format_string on @value would be valid from a type-compatibility standpoint. @format_string is assumed to be a valid format string (from a syntactic standpoint). @@ -50727,58 +56102,58 @@ check fails then a g_critical() is printed and %FALSE is returned. This function is meant to be used by functions that wish to provide varargs accessors to #GVariant values of uncertain values (eg: g_variant_lookup() or g_menu_model_get_item_attribute()). - + %TRUE if @format_string is safe to use + filename="glib/gvariant.c" + line="4561">%TRUE if @format_string is safe to use a #GVariant + filename="glib/gvariant.c" + line="4542">a #GVariant a valid #GVariant format string + filename="glib/gvariant.c" + line="4543">a valid #GVariant format string %TRUE to ensure the format string makes deep copies + filename="glib/gvariant.c" + line="4544">%TRUE to ensure the format string makes deep copies Classifies @value according to its top-level type. - + filename="glib/gvariant.c" + line="2151">Classifies @value according to its top-level type. + the #GVariantClass of @value + filename="glib/gvariant.c" + line="2157">the #GVariantClass of @value a #GVariant + filename="glib/gvariant.c" + line="2153">a #GVariant Compares @one and @two. + filename="glib/gvariant.c" + line="2821">Compares @one and @two. The types of @one and @two are #gconstpointer only to allow use of this function with #GTree, #GPtrArray, etc. They must each be a @@ -50797,11 +56172,11 @@ the handling of incomparable values (ie: NaN) is undefined. If you only require an equality comparison, g_variant_equal() is more general. - + negative value if a < b; + filename="glib/gvariant.c" + line="2846">negative value if a < b; zero if a = b; positive value if a > b. @@ -50809,14 +56184,14 @@ general. a basic-typed #GVariant instance + filename="glib/gvariant.c" + line="2823">a basic-typed #GVariant instance a #GVariant instance of the same type + filename="glib/gvariant.c" + line="2824">a #GVariant instance of the same type @@ -50825,16 +56200,16 @@ general. c:identifier="g_variant_dup_bytestring" version="2.26"> Similar to g_variant_get_bytestring() except that instead of + filename="glib/gvariant.c" + line="1896">Similar to g_variant_get_bytestring() except that instead of returning a constant string, the string is duplicated. The return value must be freed using g_free(). - + + filename="glib/gvariant.c" + line="1907"> a newly allocated string @@ -50843,8 +56218,8 @@ The return value must be freed using g_free(). an array-of-bytes #GVariant instance + filename="glib/gvariant.c" + line="1898">an array-of-bytes #GVariant instance optional="1" allow-none="1"> a pointer to a #gsize, to store + filename="glib/gvariant.c" + line="1899">a pointer to a #gsize, to store the length (not including the nul terminator) @@ -50865,8 +56240,8 @@ The return value must be freed using g_free(). c:identifier="g_variant_dup_bytestring_array" version="2.26"> Gets the contents of an array of array of bytes #GVariant. This call + filename="glib/gvariant.c" + line="2016">Gets the contents of an array of array of bytes #GVariant. This call makes a deep copy; the return result should be released with g_strfreev(). @@ -50876,11 +56251,11 @@ stored there. In any case, the resulting array will be For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. - + an array of strings + filename="glib/gvariant.c" + line="2032">an array of strings @@ -50888,8 +56263,8 @@ For an empty array, @length will be set to 0 and a pointer to a an array of array of bytes #GVariant ('aay') + filename="glib/gvariant.c" + line="2018">an array of array of bytes #GVariant ('aay') the length of the result, or %NULL + filename="glib/gvariant.c" + line="2019">the length of the result, or %NULL Gets the contents of an array of object paths #GVariant. This call + filename="glib/gvariant.c" + line="1775">Gets the contents of an array of object paths #GVariant. This call makes a deep copy; the return result should be released with g_strfreev(). @@ -50918,11 +56293,11 @@ is stored there. In any case, the resulting array will be For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. - + an array of strings + filename="glib/gvariant.c" + line="1791">an array of strings @@ -50930,8 +56305,8 @@ For an empty array, @length will be set to 0 and a pointer to a an array of object paths #GVariant + filename="glib/gvariant.c" + line="1777">an array of object paths #GVariant the length of the result, or %NULL + filename="glib/gvariant.c" + line="1778">the length of the result, or %NULL @@ -50951,25 +56326,25 @@ For an empty array, @length will be set to 0 and a pointer to a c:identifier="g_variant_dup_string" version="2.24"> Similar to g_variant_get_string() except that instead of returning + filename="glib/gvariant.c" + line="1530">Similar to g_variant_get_string() except that instead of returning a constant string, the string is duplicated. The string will always be UTF-8 encoded. The return value must be freed using g_free(). - + a newly allocated string, UTF-8 encoded + filename="glib/gvariant.c" + line="1542">a newly allocated string, UTF-8 encoded a string #GVariant instance + filename="glib/gvariant.c" + line="1532">a string #GVariant instance caller-allocates="0" transfer-ownership="full"> a pointer to a #gsize, to store the length + filename="glib/gvariant.c" + line="1533">a pointer to a #gsize, to store the length Gets the contents of an array of strings #GVariant. This call + filename="glib/gvariant.c" + line="1638">Gets the contents of an array of strings #GVariant. This call makes a deep copy; the return result should be released with g_strfreev(). @@ -50996,11 +56371,11 @@ is stored there. In any case, the resulting array will be For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. - + an array of strings + filename="glib/gvariant.c" + line="1654">an array of strings @@ -51008,8 +56383,8 @@ For an empty array, @length will be set to 0 and a pointer to a an array of strings #GVariant + filename="glib/gvariant.c" + line="1640">an array of strings #GVariant the length of the result, or %NULL + filename="glib/gvariant.c" + line="1641">the length of the result, or %NULL Checks if @one and @two have the same type and value. + filename="glib/gvariant.c" + line="2752">Checks if @one and @two have the same type and value. The types of @one and @two are #gconstpointer only to allow use of this function with #GHashTable. They must each be a #GVariant. - + %TRUE if @one and @two are equal + filename="glib/gvariant.c" + line="2762">%TRUE if @one and @two are equal a #GVariant instance + filename="glib/gvariant.c" + line="2754">a #GVariant instance a #GVariant instance + filename="glib/gvariant.c" + line="2755">a #GVariant instance @@ -51059,8 +56434,8 @@ this function with #GHashTable. They must each be a #GVariant. version="2.24" introspectable="0"> Deconstructs a #GVariant instance. + filename="glib/gvariant.c" + line="5553">Deconstructs a #GVariant instance. Think of this function as an analogue to scanf(). @@ -51068,35 +56443,35 @@ The arguments that are expected by this function are entirely determined by @format_string. @format_string also restricts the permissible types of @value. It is an error to give a value with an incompatible type. See the section on -[GVariant format strings][gvariant-format-strings]. +[GVariant format strings](gvariant-format-strings.html). Please note that the syntax of the format string is very likely to be extended in the future. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - +[`GVariant` format strings](gvariant-format-strings.html#pointers). + a #GVariant instance + filename="glib/gvariant.c" + line="5555">a #GVariant instance a #GVariant format string + filename="glib/gvariant.c" + line="5556">a #GVariant format string arguments, as per @format_string + filename="glib/gvariant.c" + line="5557">arguments, as per @format_string @@ -51105,46 +56480,46 @@ see the section on c:identifier="g_variant_get_boolean" version="2.24"> Returns the boolean value of @value. + filename="glib/gvariant.c" + line="348">Returns the boolean value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_BOOLEAN. - + %TRUE or %FALSE + filename="glib/gvariant.c" + line="357">%TRUE or %FALSE a boolean #GVariant instance + filename="glib/gvariant.c" + line="350">a boolean #GVariant instance Returns the byte value of @value. + filename="glib/gvariant.c" + line="400">Returns the byte value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_BYTE. - + a #guint8 + filename="glib/gvariant.c" + line="409">a #guint8 a byte #GVariant instance + filename="glib/gvariant.c" + line="402">a byte #GVariant instance @@ -51153,8 +56528,8 @@ other than %G_VARIANT_TYPE_BYTE. c:identifier="g_variant_get_bytestring" version="2.26"> Returns the string value of a #GVariant instance with an + filename="glib/gvariant.c" + line="1850">Returns the string value of a #GVariant instance with an array-of-bytes type. The string has no particular encoding. If the array does not end with a nul terminator character, the empty @@ -51172,11 +56547,11 @@ It is an error to call this function with a @value that is not an array of bytes. The return value remains valid as long as @value exists. - + + filename="glib/gvariant.c" + line="1873"> the constant string @@ -51185,8 +56560,8 @@ The return value remains valid as long as @value exists. an array-of-bytes #GVariant instance + filename="glib/gvariant.c" + line="1852">an array-of-bytes #GVariant instance @@ -51195,8 +56570,8 @@ The return value remains valid as long as @value exists. c:identifier="g_variant_get_bytestring_array" version="2.26"> Gets the contents of an array of array of bytes #GVariant. This call + filename="glib/gvariant.c" + line="1966">Gets the contents of an array of array of bytes #GVariant. This call makes a shallow copy; the return result should be released with g_free(), but the individual strings must not be modified. @@ -51206,11 +56581,11 @@ stored there. In any case, the resulting array will be For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. - + an array of constant strings + filename="glib/gvariant.c" + line="1982">an array of constant strings @@ -51218,8 +56593,8 @@ For an empty array, @length will be set to 0 and a pointer to a an array of array of bytes #GVariant ('aay') + filename="glib/gvariant.c" + line="1968">an array of array of bytes #GVariant ('aay') the length of the result, or %NULL + filename="glib/gvariant.c" + line="1969">the length of the result, or %NULL @@ -51240,8 +56615,8 @@ For an empty array, @length will be set to 0 and a pointer to a version="2.24" introspectable="0"> Reads a child item out of a container #GVariant instance and + filename="glib/gvariant.c" + line="5708">Reads a child item out of a container #GVariant instance and deconstructs it according to @format_string. This call is essentially a combination of g_variant_get_child_value() and g_variant_get(). @@ -51249,34 +56624,34 @@ g_variant_get(). @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - +[`GVariant` format strings](gvariant-format-strings.html#pointers). + a container #GVariant + filename="glib/gvariant.c" + line="5710">a container #GVariant the index of the child to deconstruct + filename="glib/gvariant.c" + line="5711">the index of the child to deconstruct a #GVariant format string + filename="glib/gvariant.c" + line="5712">a #GVariant format string arguments, as per @format_string + filename="glib/gvariant.c" + line="5713">arguments, as per @format_string @@ -51285,8 +56660,8 @@ see the section on c:identifier="g_variant_get_child_value" version="2.24"> Reads a child item out of a container #GVariant instance. This + filename="glib/gvariant-core.c" + line="1216">Reads a child item out of a container #GVariant instance. This includes variants, maybes, arrays, tuples and dictionary entries. It is an error to call this function on any other type of #GVariant. @@ -51309,32 +56684,32 @@ instead of further nested children. #GVariant is guaranteed to handle nesting up to at least 64 levels. This function is O(1). - + the child at the specified index + filename="glib/gvariant-core.c" + line="1245">the child at the specified index a container #GVariant + filename="glib/gvariant-core.c" + line="1218">a container #GVariant the index of the child to fetch + filename="glib/gvariant-core.c" + line="1219">the index of the child to fetch Returns a pointer to the serialized form of a #GVariant instance. + filename="glib/gvariant-core.c" + line="1085">Returns a pointer to the serialized form of a #GVariant instance. The returned data may not be in fully-normalised form if read from an untrusted source. The returned data must not be freed; it remains valid for as long as @value exists. @@ -51359,18 +56734,18 @@ implicitly (for instance "the file always contains a %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or explicitly (by storing the type and/or endianness in addition to the serialized data). - + the serialized form of @value, or %NULL + filename="glib/gvariant-core.c" + line="1115">the serialized form of @value, or %NULL a #GVariant instance + filename="glib/gvariant-core.c" + line="1087">a #GVariant instance @@ -51379,23 +56754,23 @@ serialized data). c:identifier="g_variant_get_data_as_bytes" version="2.36"> Returns a pointer to the serialized form of a #GVariant instance. + filename="glib/gvariant-core.c" + line="1129">Returns a pointer to the serialized form of a #GVariant instance. The semantics of this function are exactly the same as g_variant_get_data(), except that the returned #GBytes holds a reference to the variant data. - + A new #GBytes representing the variant data + filename="glib/gvariant-core.c" + line="1138">A new #GBytes representing the variant data a #GVariant + filename="glib/gvariant-core.c" + line="1131">a #GVariant @@ -51404,23 +56779,23 @@ a reference to the variant data. c:identifier="g_variant_get_double" version="2.24"> Returns the double precision floating point value of @value. + filename="glib/gvariant.c" + line="608">Returns the double precision floating point value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_DOUBLE. - + a #gdouble + filename="glib/gvariant.c" + line="617">a #gdouble a double #GVariant instance + filename="glib/gvariant.c" + line="610">a double #GVariant instance @@ -51430,8 +56805,8 @@ other than %G_VARIANT_TYPE_DOUBLE. version="2.24" introspectable="0"> Provides access to the serialized data for an array of fixed-sized + filename="glib/gvariant.c" + line="1097">Provides access to the serialized data for an array of fixed-sized items. @value must be an array with fixed-sized elements. Numeric types are @@ -51439,7 +56814,7 @@ fixed-size, as are tuples containing only other fixed-sized types. @element_size must be the size of a single element in the array, as given by the section on -[serialized data memory][gvariant-serialized-data-memory]. +[serialized data memory](struct.Variant.html#serialized-data-memory). In particular, arrays of these fixed-sized types can be interpreted as an array of the given C type, with @element_size set to the size @@ -51457,11 +56832,11 @@ expectation. @n_elements, which must be non-%NULL, is set equal to the number of items in the array. - + a pointer to + filename="glib/gvariant.c" + line="1130">a pointer to the fixed array @@ -51470,8 +56845,8 @@ items in the array. a #GVariant array with fixed-sized elements + filename="glib/gvariant.c" + line="1099">a #GVariant array with fixed-sized elements caller-allocates="0" transfer-ownership="full"> a pointer to the location to store the number of items + filename="glib/gvariant.c" + line="1100">a pointer to the location to store the number of items the size of each element + filename="glib/gvariant.c" + line="1101">the size of each element @@ -51495,8 +56870,8 @@ items in the array. c:identifier="g_variant_get_handle" version="2.24"> Returns the 32-bit signed integer value of @value. + filename="glib/gvariant.c" + line="579">Returns the 32-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_HANDLE. @@ -51504,18 +56879,18 @@ than %G_VARIANT_TYPE_HANDLE. By convention, handles are indexes into an array of file descriptors that are sent alongside a D-Bus message. If you're not interacting with D-Bus, you probably don't need them. - + a #gint32 + filename="glib/gvariant.c" + line="592">a #gint32 a handle #GVariant instance + filename="glib/gvariant.c" + line="581">a handle #GVariant instance @@ -51524,23 +56899,23 @@ with D-Bus, you probably don't need them. c:identifier="g_variant_get_int16" version="2.24"> Returns the 16-bit signed integer value of @value. + filename="glib/gvariant.c" + line="425">Returns the 16-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_INT16. - + a #gint16 + filename="glib/gvariant.c" + line="434">a #gint16 an int16 #GVariant instance + filename="glib/gvariant.c" + line="427">an int16 #GVariant instance @@ -51549,23 +56924,23 @@ other than %G_VARIANT_TYPE_INT16. c:identifier="g_variant_get_int32" version="2.24"> Returns the 32-bit signed integer value of @value. + filename="glib/gvariant.c" + line="475">Returns the 32-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_INT32. - + a #gint32 + filename="glib/gvariant.c" + line="484">a #gint32 an int32 #GVariant instance + filename="glib/gvariant.c" + line="477">an int32 #GVariant instance @@ -51574,23 +56949,23 @@ other than %G_VARIANT_TYPE_INT32. c:identifier="g_variant_get_int64" version="2.24"> Returns the 64-bit signed integer value of @value. + filename="glib/gvariant.c" + line="525">Returns the 64-bit signed integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_INT64. - + a #gint64 + filename="glib/gvariant.c" + line="534">a #gint64 an int64 #GVariant instance + filename="glib/gvariant.c" + line="527">an int64 #GVariant instance @@ -51599,21 +56974,21 @@ other than %G_VARIANT_TYPE_INT64. c:identifier="g_variant_get_maybe" version="2.24"> Given a maybe-typed #GVariant instance, extract its value. If the + filename="glib/gvariant.c" + line="682">Given a maybe-typed #GVariant instance, extract its value. If the value is Nothing, then this function returns %NULL. - + the contents of @value, or %NULL + filename="glib/gvariant.c" + line="689">the contents of @value, or %NULL a maybe-typed value + filename="glib/gvariant.c" + line="684">a maybe-typed value @@ -51622,8 +56997,8 @@ value is Nothing, then this function returns %NULL. c:identifier="g_variant_get_normal_form" version="2.24"> Gets a #GVariant instance that has the same value as @value and is + filename="glib/gvariant.c" + line="6110">Gets a #GVariant instance that has the same value as @value and is trusted to be in normal form. If @value is already trusted to be in normal form then a new @@ -51648,26 +57023,26 @@ the newly created #GVariant will be returned with a single non-floating reference. Typically, g_variant_take_ref() should be called on the return value from this function to guarantee ownership of a single non-floating reference to it. - + a trusted #GVariant + filename="glib/gvariant.c" + line="6140">a trusted #GVariant a #GVariant + filename="glib/gvariant.c" + line="6112">a #GVariant Gets the contents of an array of object paths #GVariant. This call + filename="glib/gvariant.c" + line="1725">Gets the contents of an array of object paths #GVariant. This call makes a shallow copy; the return result should be released with g_free(), but the individual strings must not be modified. @@ -51677,11 +57052,11 @@ is stored there. In any case, the resulting array will be For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. - + an array of constant strings + filename="glib/gvariant.c" + line="1741">an array of constant strings @@ -51689,8 +57064,8 @@ For an empty array, @length will be set to 0 and a pointer to a an array of object paths #GVariant + filename="glib/gvariant.c" + line="1727">an array of object paths #GVariant the length of the result, or %NULL + filename="glib/gvariant.c" + line="1728">the length of the result, or %NULL Determines the number of bytes that would be required to store @value + filename="glib/gvariant-core.c" + line="1055">Determines the number of bytes that would be required to store @value with g_variant_store(). If @value has a fixed-sized type then this function always returned @@ -51720,18 +57095,18 @@ already been calculated (ie: this function has been called before) then this function is O(1). Otherwise, the size is calculated, an operation which is approximately O(n) in the number of values involved. - + the serialized size of @value + filename="glib/gvariant-core.c" + line="1071">the serialized size of @value a #GVariant instance + filename="glib/gvariant-core.c" + line="1057">a #GVariant instance @@ -51740,8 +57115,8 @@ involved. c:identifier="g_variant_get_string" version="2.24"> Returns the string value of a #GVariant instance with a string + filename="glib/gvariant.c" + line="1446">Returns the string value of a #GVariant instance with a string type. This includes the types %G_VARIANT_TYPE_STRING, %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. @@ -51759,18 +57134,18 @@ It is an error to call this function with a @value of any type other than those three. The return value remains valid as long as @value exists. - + the constant string, UTF-8 encoded + filename="glib/gvariant.c" + line="1471">the constant string, UTF-8 encoded a string #GVariant instance + filename="glib/gvariant.c" + line="1448">a string #GVariant instance optional="1" allow-none="1"> a pointer to a #gsize, + filename="glib/gvariant.c" + line="1449">a pointer to a #gsize, to store the length @@ -51789,8 +57164,8 @@ The return value remains valid as long as @value exists. Gets the contents of an array of strings #GVariant. This call + filename="glib/gvariant.c" + line="1588">Gets the contents of an array of strings #GVariant. This call makes a shallow copy; the return result should be released with g_free(), but the individual strings must not be modified. @@ -51800,11 +57175,11 @@ is stored there. In any case, the resulting array will be For an empty array, @length will be set to 0 and a pointer to a %NULL pointer will be returned. - + an array of constant strings + filename="glib/gvariant.c" + line="1604">an array of constant strings @@ -51812,8 +57187,8 @@ For an empty array, @length will be set to 0 and a pointer to a an array of strings #GVariant + filename="glib/gvariant.c" + line="1590">an array of strings #GVariant the length of the result, or %NULL + filename="glib/gvariant.c" + line="1591">the length of the result, or %NULL Determines the type of @value. + filename="glib/gvariant.c" + line="2067">Determines the type of @value. The return value is valid for the lifetime of @value and must not be freed. - + a #GVariantType + filename="glib/gvariant.c" + line="2076">a #GVariantType a #GVariant + filename="glib/gvariant.c" + line="2069">a #GVariant @@ -51856,22 +57231,22 @@ be freed. c:identifier="g_variant_get_type_string" version="2.24"> Returns the type string of @value. Unlike the result of calling + filename="glib/gvariant.c" + line="2092">Returns the type string of @value. Unlike the result of calling g_variant_type_peek_string(), this string is nul-terminated. This string belongs to #GVariant and must not be freed. - + the type string for the type of @value + filename="glib/gvariant.c" + line="2100">the type string for the type of @value a #GVariant + filename="glib/gvariant.c" + line="2094">a #GVariant @@ -51880,23 +57255,23 @@ string belongs to #GVariant and must not be freed. c:identifier="g_variant_get_uint16" version="2.24"> Returns the 16-bit unsigned integer value of @value. + filename="glib/gvariant.c" + line="450">Returns the 16-bit unsigned integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_UINT16. - + a #guint16 + filename="glib/gvariant.c" + line="459">a #guint16 a uint16 #GVariant instance + filename="glib/gvariant.c" + line="452">a uint16 #GVariant instance @@ -51905,23 +57280,23 @@ other than %G_VARIANT_TYPE_UINT16. c:identifier="g_variant_get_uint32" version="2.24"> Returns the 32-bit unsigned integer value of @value. + filename="glib/gvariant.c" + line="500">Returns the 32-bit unsigned integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_UINT32. - + a #guint32 + filename="glib/gvariant.c" + line="509">a #guint32 a uint32 #GVariant instance + filename="glib/gvariant.c" + line="502">a uint32 #GVariant instance @@ -51930,23 +57305,23 @@ other than %G_VARIANT_TYPE_UINT32. c:identifier="g_variant_get_uint64" version="2.24"> Returns the 64-bit unsigned integer value of @value. + filename="glib/gvariant.c" + line="550">Returns the 64-bit unsigned integer value of @value. It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_UINT64. - + a #guint64 + filename="glib/gvariant.c" + line="559">a #guint64 a uint64 #GVariant instance + filename="glib/gvariant.c" + line="552">a uint64 #GVariant instance @@ -51956,8 +57331,8 @@ other than %G_VARIANT_TYPE_UINT64. version="2.24" introspectable="0"> This function is intended to be used by libraries based on #GVariant + filename="glib/gvariant.c" + line="5597">This function is intended to be used by libraries based on #GVariant that want to provide g_variant_get()-like functionality to their users. @@ -51980,22 +57355,22 @@ varargs call by the user. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - +[`GVariant` format strings](gvariant-format-strings.html#pointers). + a #GVariant + filename="glib/gvariant.c" + line="5599">a #GVariant a string that is prefixed with a format string + filename="glib/gvariant.c" + line="5600">a string that is prefixed with a format string location to store the end pointer, + filename="glib/gvariant.c" + line="5601">location to store the end pointer, or %NULL a pointer to a #va_list + filename="glib/gvariant.c" + line="5603">a pointer to a #va_list @@ -52020,29 +57395,29 @@ see the section on c:identifier="g_variant_get_variant" version="2.24"> Unboxes @value. The result is the #GVariant instance that was + filename="glib/gvariant.c" + line="730">Unboxes @value. The result is the #GVariant instance that was contained in @value. - + the item contained in the variant + filename="glib/gvariant.c" + line="737">the item contained in the variant a variant #GVariant instance + filename="glib/gvariant.c" + line="732">a variant #GVariant instance Generates a hash value for a #GVariant instance. + filename="glib/gvariant.c" + line="2665">Generates a hash value for a #GVariant instance. The output of this function is guaranteed to be the same for a given value only per-process. It may change between different processor @@ -52051,18 +57426,18 @@ function as a basis for building protocols or file formats. The type of @value is #gconstpointer only to allow use of this function with #GHashTable. @value must be a #GVariant. - + a hash value corresponding to @value + filename="glib/gvariant.c" + line="2679">a hash value corresponding to @value a basic #GVariant value as a #gconstpointer + filename="glib/gvariant.c" + line="2667">a basic #GVariant value as a #gconstpointer @@ -52071,20 +57446,20 @@ function with #GHashTable. @value must be a #GVariant. c:identifier="g_variant_is_container" version="2.24"> Checks if @value is a container. - + filename="glib/gvariant.c" + line="2134">Checks if @value is a container. + %TRUE if @value is a container + filename="glib/gvariant.c" + line="2140">%TRUE if @value is a container a #GVariant instance + filename="glib/gvariant.c" + line="2136">a #GVariant instance @@ -52093,8 +57468,8 @@ function with #GHashTable. @value must be a #GVariant. c:identifier="g_variant_is_floating" version="2.26"> Checks whether @value has a floating reference count. + filename="glib/gvariant-core.c" + line="1029">Checks whether @value has a floating reference count. This function should only ever be used to assert that a given variant is or is not floating, or for debug purposes. To acquire a reference @@ -52103,18 +57478,18 @@ or g_variant_take_ref(). See g_variant_ref_sink() for more information about floating reference counts. - + whether @value is floating + filename="glib/gvariant-core.c" + line="1043">whether @value is floating a #GVariant + filename="glib/gvariant-core.c" + line="1031">a #GVariant @@ -52123,8 +57498,8 @@ counts. c:identifier="g_variant_is_normal_form" version="2.24"> Checks if @value is in normal form. + filename="glib/gvariant-core.c" + line="1433">Checks if @value is in normal form. The main reason to do this is to detect if a given chunk of serialized data is in normal form: load the data into a #GVariant @@ -52137,18 +57512,18 @@ this function will immediately return %TRUE. There may be implementation specific restrictions on deeply nested values. GVariant is guaranteed to handle nesting up to at least 64 levels. - + %TRUE if @value is in normal form + filename="glib/gvariant-core.c" + line="1451">%TRUE if @value is in normal form a #GVariant instance + filename="glib/gvariant-core.c" + line="1435">a #GVariant instance @@ -52157,26 +57532,26 @@ GVariant is guaranteed to handle nesting up to at least 64 levels. c:identifier="g_variant_is_of_type" version="2.24"> Checks if a value has a type matching the provided type. - + filename="glib/gvariant.c" + line="2116">Checks if a value has a type matching the provided type. + %TRUE if the type of @value matches @type + filename="glib/gvariant.c" + line="2123">%TRUE if the type of @value matches @type a #GVariant instance + filename="glib/gvariant.c" + line="2118">a #GVariant instance a #GVariantType + filename="glib/gvariant.c" + line="2119">a #GVariantType @@ -52186,8 +57561,8 @@ GVariant is guaranteed to handle nesting up to at least 64 levels. version="2.24" introspectable="0"> Creates a heap-allocated #GVariantIter for iterating over the items + filename="glib/gvariant.c" + line="2970">Creates a heap-allocated #GVariantIter for iterating over the items in @value. Use g_variant_iter_free() to free the return value when you no longer @@ -52195,18 +57570,18 @@ need it. A reference is taken to @value and will be released only when g_variant_iter_free() is called. - + a new heap-allocated #GVariantIter + filename="glib/gvariant.c" + line="2983">a new heap-allocated #GVariantIter a container #GVariant + filename="glib/gvariant.c" + line="2972">a container #GVariant @@ -52216,8 +57591,8 @@ g_variant_iter_free() is called. version="2.28" introspectable="0"> Looks up a value in a dictionary #GVariant. + filename="glib/gvariant.c" + line="947">Looks up a value in a dictionary #GVariant. This function is a wrapper around g_variant_lookup_value() and g_variant_get(). In the case that %NULL would have been returned, @@ -52227,40 +57602,40 @@ value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). This function is currently implemented with a linear scan. If you plan to do many lookups then #GVariantDict may be more efficient. - + %TRUE if a value was unpacked + filename="glib/gvariant.c" + line="969">%TRUE if a value was unpacked a dictionary #GVariant + filename="glib/gvariant.c" + line="949">a dictionary #GVariant the key to look up in the dictionary + filename="glib/gvariant.c" + line="950">the key to look up in the dictionary a GVariant format string + filename="glib/gvariant.c" + line="951">a GVariant format string the arguments to unpack the value into + filename="glib/gvariant.c" + line="952">the arguments to unpack the value into @@ -52269,8 +57644,8 @@ plan to do many lookups then #GVariantDict may be more efficient. c:identifier="g_variant_lookup_value" version="2.28"> Looks up a value in a dictionary #GVariant. + filename="glib/gvariant.c" + line="1005">Looks up a value in a dictionary #GVariant. This function works with dictionaries of the type a{s*} (and equally well with type a{o*}, but we only further discuss the string case @@ -52291,24 +57666,24 @@ value will have this type. This function is currently implemented with a linear scan. If you plan to do many lookups then #GVariantDict may be more efficient. - + the value of the dictionary key, or %NULL + filename="glib/gvariant.c" + line="1033">the value of the dictionary key, or %NULL a dictionary #GVariant + filename="glib/gvariant.c" + line="1007">a dictionary #GVariant the key to look up in the dictionary + filename="glib/gvariant.c" + line="1008">the key to look up in the dictionary nullable="1" allow-none="1"> a #GVariantType, or %NULL + filename="glib/gvariant.c" + line="1009">a #GVariantType, or %NULL @@ -52326,8 +57701,8 @@ plan to do many lookups then #GVariantDict may be more efficient. c:identifier="g_variant_n_children" version="2.24"> Determines the number of children in a container #GVariant instance. + filename="glib/gvariant-core.c" + line="1178">Determines the number of children in a container #GVariant instance. This includes variants, maybes, arrays, tuples and dictionary entries. It is an error to call this function on any other type of #GVariant. @@ -52338,49 +57713,49 @@ array. For tuples it is the number of tuple items (which depends only on the type). For dictionary entries, it is always 2 This function is O(1). - + the number of children in the container + filename="glib/gvariant-core.c" + line="1194">the number of children in the container a container #GVariant + filename="glib/gvariant-core.c" + line="1180">a container #GVariant Pretty-prints @value in the format understood by g_variant_parse(). + filename="glib/gvariant.c" + line="2639">Pretty-prints @value in the format understood by g_variant_parse(). -The format is described [here][gvariant-text]. +The format is described [here](gvariant-text-format.html). If @type_annotate is %TRUE, then type information is included in the output. - + a newly-allocated string holding the result. + filename="glib/gvariant.c" + line="2652">a newly-allocated string holding the result. a #GVariant + filename="glib/gvariant.c" + line="2641">a #GVariant %TRUE if type information should be included in + filename="glib/gvariant.c" + line="2642">%TRUE if type information should be included in the output @@ -52391,23 +57766,23 @@ the output. version="2.24" introspectable="0"> Behaves as g_variant_print(), but operates on a #GString. + filename="glib/gvariant.c" + line="2200">Behaves as g_variant_print(), but operates on a #GString. If @string is non-%NULL then it is appended to and returned. Else, a new empty #GString is allocated and it is returned. - + a #GString containing the string + filename="glib/gvariant.c" + line="2212">a #GString containing the string a #GVariant + filename="glib/gvariant.c" + line="2202">a #GVariant nullable="1" allow-none="1"> a #GString, or %NULL + filename="glib/gvariant.c" + line="2203">a #GString, or %NULL %TRUE if type information should be included in + filename="glib/gvariant.c" + line="2204">%TRUE if type information should be included in the output @@ -52430,28 +57805,28 @@ a new empty #GString is allocated and it is returned. Increases the reference count of @value. - + filename="glib/gvariant-core.c" + line="900">Increases the reference count of @value. + the same @value + filename="glib/gvariant-core.c" + line="906">the same @value a #GVariant + filename="glib/gvariant-core.c" + line="902">a #GVariant #GVariant uses a floating reference count system. All functions with + filename="glib/gvariant-core.c" + line="922">#GVariant uses a floating reference count system. All functions with names starting with `g_variant_new_` return floating references. @@ -52473,26 +57848,26 @@ at that point and the caller will not need to unreference it. This makes certain common styles of programming much easier while still maintaining normal refcounting semantics in situations where values are not floating. - + the same @value + filename="glib/gvariant-core.c" + line="949">the same @value a #GVariant + filename="glib/gvariant-core.c" + line="924">a #GVariant Stores the serialized form of @value at @data. @data should be + filename="glib/gvariant-core.c" + line="1394">Stores the serialized form of @value at @data. @data should be large enough. See g_variant_get_size(). The stored data is in machine native byte order but may not be in @@ -52504,29 +57879,29 @@ serialized variant successfully, its type and (if the destination machine might be different) its endianness must also be available. This function is approximately O(n) in the size of @data. - + the #GVariant to store + filename="glib/gvariant-core.c" + line="1396">the #GVariant to store the location to store the serialized data at + filename="glib/gvariant-core.c" + line="1397">the location to store the serialized data at If @value is floating, sink it. Otherwise, do nothing. + filename="glib/gvariant-core.c" + line="978">If @value is floating, sink it. Otherwise, do nothing. Typically you want to use g_variant_ref_sink() in order to automatically do the correct thing with respect to floating or @@ -52558,36 +57933,36 @@ reference. If g_variant_take_ref() runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation. - + the same @value + filename="glib/gvariant-core.c" + line="1015">the same @value a #GVariant + filename="glib/gvariant-core.c" + line="980">a #GVariant Decreases the reference count of @value. When its reference count + filename="glib/gvariant-core.c" + line="864">Decreases the reference count of @value. When its reference count drops to 0, the memory used by the variant is freed. - + a #GVariant + filename="glib/gvariant-core.c" + line="866">a #GVariant @@ -52596,8 +57971,8 @@ drops to 0, the memory used by the variant is freed. c:identifier="g_variant_is_object_path" version="2.24"> Determines if a given string is a valid D-Bus object path. You + filename="glib/gvariant.c" + line="1377">Determines if a given string is a valid D-Bus object path. You should ensure that a string is a valid D-Bus object path before passing it to g_variant_new_object_path(). @@ -52605,18 +57980,18 @@ A valid object path starts with `/` followed by zero or more sequences of characters separated by `/` characters. Each sequence must contain only the characters `[A-Z][a-z][0-9]_`. No sequence (including the one following the final `/` character) may be empty. - + %TRUE if @string is a D-Bus object path + filename="glib/gvariant.c" + line="1390">%TRUE if @string is a D-Bus object path a normal C nul-terminated string + filename="glib/gvariant.c" + line="1379">a normal C nul-terminated string @@ -52625,37 +58000,37 @@ must contain only the characters `[A-Z][a-z][0-9]_`. No sequence c:identifier="g_variant_is_signature" version="2.24"> Determines if a given string is a valid D-Bus type signature. You + filename="glib/gvariant.c" + line="1423">Determines if a given string is a valid D-Bus type signature. You should ensure that a string is a valid D-Bus type signature before passing it to g_variant_new_signature(). D-Bus type signatures consist of zero or more definite #GVariantType strings in sequence. - + %TRUE if @string is a D-Bus type signature + filename="glib/gvariant.c" + line="1434">%TRUE if @string is a D-Bus type signature a normal C nul-terminated string + filename="glib/gvariant.c" + line="1425">a normal C nul-terminated string Parses a #GVariant from a text representation. + filename="glib/gvariant-parser.c" + line="2489">Parses a #GVariant from a text representation. A single #GVariant is parsed from the content of @text. -The format is described [here][gvariant-text]. +The format is described [here](gvariant-text-format.html). The memory at @limit will never be accessed and the parser behaves as if the character at @limit is the nul terminator. This has the @@ -52675,22 +58050,23 @@ with empty arrays). In the event that the parsing is successful, the resulting #GVariant is returned. It is never floating, and must be freed with -g_variant_unref(). +[method@GLib.Variant.unref]. In case of any error, %NULL will be returned. If @error is non-%NULL then it will be set to reflect the error that occurred. -Officially, the language understood by the parser is "any string -produced by g_variant_print()". +Officially, the language understood by the parser is “any string +produced by [method@GLib.Variant.print]”. This explicitly includes +`g_variant_print()`’s annotated types like `int64 -1000`. There may be implementation specific restrictions on deeply nested values, which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is guaranteed to handle nesting up to at least 64 levels. - + a non-floating reference to a #GVariant, or %NULL + filename="glib/gvariant-parser.c" + line="2534">a non-floating reference to a #GVariant, or %NULL @@ -52699,14 +58075,14 @@ guaranteed to handle nesting up to at least 64 levels. nullable="1" allow-none="1"> a #GVariantType, or %NULL + filename="glib/gvariant-parser.c" + line="2491">a #GVariantType, or %NULL a string containing a GVariant in text form + filename="glib/gvariant-parser.c" + line="2492">a string containing a GVariant in text form nullable="1" allow-none="1"> a pointer to the end of @text, or %NULL + filename="glib/gvariant-parser.c" + line="2493">a pointer to the end of @text, or %NULL nullable="1" allow-none="1"> a location to store the end pointer, or %NULL + filename="glib/gvariant-parser.c" + line="2494">a location to store the end pointer, or %NULL @@ -52733,8 +58109,8 @@ guaranteed to handle nesting up to at least 64 levels. c:identifier="g_variant_parse_error_print_context" version="2.40"> Pretty-prints a message showing the context of a #GVariant parse + filename="glib/gvariant-parser.c" + line="2858">Pretty-prints a message showing the context of a #GVariant parse error within the string for which parsing was attempted. The resulting string is suitable for output to the console or other @@ -52763,24 +58139,24 @@ The format of the message may change in a future version. If @source_str was not nul-terminated when you passed it to g_variant_parse() then you must add nul termination before using this function. - + the printed message + filename="glib/gvariant-parser.c" + line="2893">the printed message a #GError from the #GVariantParseError domain + filename="glib/gvariant-parser.c" + line="2860">a #GError from the #GVariantParseError domain the string that was given to the parser + filename="glib/gvariant-parser.c" + line="2861">the string that was given to the parser @@ -52795,8 +58171,8 @@ function. c:identifier="g_variant_parser_get_error_quark" deprecated="1"> Same as g_variant_error_quark(). + filename="glib/gvariant-parser.c" + line="79">Same as g_variant_error_quark(). Use g_variant_parse_error_quark() instead. @@ -52809,19 +58185,19 @@ function. glib:get-type="g_variant_builder_get_type" c:symbol-prefix="variant_builder"> A utility type for constructing container-type #GVariant instances. + filename="glib/gvariant.c" + line="3162">A utility type for constructing container-type #GVariant instances. This is an opaque structure and may only be accessed using the following functions. #GVariantBuilder is not threadsafe in any way. Do not attempt to access it from more than one thread. - + - + - + @@ -52844,8 +58220,8 @@ access it from more than one thread. c:identifier="g_variant_builder_new" version="2.24"> Allocates and initialises a new #GVariantBuilder. + filename="glib/gvariant.c" + line="3275">Allocates and initialises a new #GVariantBuilder. You should call g_variant_builder_unref() on the return value when it is no longer needed. The memory will not be automatically freed by @@ -52853,19 +58229,19 @@ any other call. In most cases it is easier to place a #GVariantBuilder directly on the stack of the calling function and initialise it with -g_variant_builder_init(). - +g_variant_builder_init_static(). + a #GVariantBuilder + filename="glib/gvariant.c" + line="3289">a #GVariantBuilder a container type + filename="glib/gvariant.c" + line="3277">a container type @@ -52875,15 +58251,15 @@ g_variant_builder_init(). version="2.24" introspectable="0"> Adds to a #GVariantBuilder. + filename="glib/gvariant.c" + line="5654">Adds to a #GVariantBuilder. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new() followed by g_variant_builder_add_value(). Note that the arguments must be of the correct width for their types specified in @format_string. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. +the [GVariant varargs documentation](gvariant-format-strings.html#varargs). This function might be used as follows: @@ -52894,7 +58270,7 @@ make_pointless_dictionary (void) GVariantBuilder builder; int i; - g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); for (i = 0; i < 16; i++) { gchar buf[3]; @@ -52906,27 +58282,27 @@ make_pointless_dictionary (void) return g_variant_builder_end (&builder); } ]| - + a #GVariantBuilder + filename="glib/gvariant.c" + line="5656">a #GVariantBuilder a #GVariant varargs format string + filename="glib/gvariant.c" + line="5657">a #GVariant varargs format string arguments, as per @format_string + filename="glib/gvariant.c" + line="5658">arguments, as per @format_string @@ -52936,8 +58312,8 @@ make_pointless_dictionary (void) version="2.26" introspectable="0"> Adds to a #GVariantBuilder. + filename="glib/gvariant-parser.c" + line="2710">Adds to a #GVariantBuilder. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new_parsed() followed by @@ -52945,7 +58321,7 @@ g_variant_builder_add_value(). Note that the arguments must be of the correct width for their types specified in @format_string. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. +the [GVariant varargs documentation](gvariant-format-strings.html#varargs). This function might be used as follows: @@ -52956,34 +58332,34 @@ make_pointless_dictionary (void) GVariantBuilder builder; int i; - g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); return g_variant_builder_end (&builder); } ]| - + a #GVariantBuilder + filename="glib/gvariant-parser.c" + line="2712">a #GVariantBuilder a text format #GVariant + filename="glib/gvariant-parser.c" + line="2713">a text format #GVariant arguments as per @format + filename="glib/gvariant-parser.c" + line="2714">arguments as per @format @@ -52992,8 +58368,8 @@ make_pointless_dictionary (void) c:identifier="g_variant_builder_add_value" version="2.24"> Adds @value to @builder. + filename="glib/gvariant.c" + line="3574">Adds @value to @builder. It is an error to call this function in any way that would create an inconsistent value to be constructed. Some examples of this are @@ -53003,21 +58379,21 @@ a variant, etc. If @value is a floating reference (see g_variant_ref_sink()), the @builder instance takes ownership of @value. - + a #GVariantBuilder + filename="glib/gvariant.c" + line="3576">a #GVariantBuilder a #GVariant + filename="glib/gvariant.c" + line="3577">a #GVariant @@ -53027,8 +58403,8 @@ the @builder instance takes ownership of @value. version="2.24" introspectable="0"> Releases all memory associated with a #GVariantBuilder without + filename="glib/gvariant.c" + line="3357">Releases all memory associated with a #GVariantBuilder without freeing the #GVariantBuilder structure itself. It typically only makes sense to do this on a stack-allocated @@ -53042,15 +58418,15 @@ This function leaves the #GVariantBuilder structure set to all-zeros. It is valid to call this function on either an initialised #GVariantBuilder or one that is set to all-zeros but it is not valid to call this function on uninitialised memory. - + a #GVariantBuilder + filename="glib/gvariant.c" + line="3359">a #GVariantBuilder @@ -53059,30 +58435,30 @@ to call this function on uninitialised memory. c:identifier="g_variant_builder_close" version="2.24"> Closes the subcontainer inside the given @builder that was opened by + filename="glib/gvariant.c" + line="3705">Closes the subcontainer inside the given @builder that was opened by the most recent call to g_variant_builder_open(). It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: too few values added to the subcontainer). - + a #GVariantBuilder + filename="glib/gvariant.c" + line="3707">a #GVariantBuilder Ends the builder process and returns the constructed value. + filename="glib/gvariant.c" + line="3759">Ends the builder process and returns the constructed value. It is not permissible to use @builder in any way after this call except for reference counting operations (in the case of a @@ -53099,18 +58475,18 @@ required). It is also an error to call this function if the builder was created with an indefinite array or maybe type and no children have been added; in this case it is impossible to infer the type of the empty array. - + a new, floating, #GVariant + filename="glib/gvariant.c" + line="3781">a new, floating, #GVariant a #GVariantBuilder + filename="glib/gvariant.c" + line="3761">a #GVariantBuilder @@ -53120,8 +58496,8 @@ the empty array. version="2.24" introspectable="0"> Initialises a #GVariantBuilder structure. + filename="glib/gvariant.c" + line="3494">Initialises a #GVariantBuilder structure. @type must be non-%NULL. It specifies the type of container to construct. It can be an indefinite type such as @@ -53129,6 +58505,10 @@ construct. It can be an indefinite type such as Maybe, array, tuple, dictionary entry and variant-typed values may be constructed. +If using a static type such as one of the `G_VARIANT_TYPE_*` constants +or a `G_VARIANT_TYPE ("(ii)")` macro, it is more performant to use +g_variant_builder_init_static() rather than g_variant_builder_init(). + After the builder is initialised, values are added using g_variant_builder_add_value() or g_variant_builder_add(). @@ -53150,29 +58530,60 @@ with this function. If you ever pass a reference to a should assume that the person receiving that reference may try to use reference counting; you should use g_variant_builder_new() instead of this function. - + + + + + + + a #GVariantBuilder + + + + a container type + + + + + + Initialises a #GVariantBuilder structure. + +This function works exactly like g_variant_builder_init() but does +not make a copy of @type. Therefore, @type must remain valid for the +lifetime of @builder. This is always true of type constants like +`G_VARIANT_TYPE_*` or `G_VARIANT_TYPE ("(ii)")`. + a #GVariantBuilder + filename="glib/gvariant.c" + line="3544">a #GVariantBuilder a container type + filename="glib/gvariant.c" + line="3545">a container type Opens a subcontainer inside the given @builder. When done adding + filename="glib/gvariant.c" + line="3627">Opens a subcontainer inside the given @builder. When done adding items to the subcontainer, g_variant_builder_close() must be called. @type is the type of the container: so to build a tuple of several values, @type must include the tuple itself. @@ -53208,44 +58619,44 @@ g_variant_builder_close (&builder); output = g_variant_builder_end (&builder); ]| - + a #GVariantBuilder + filename="glib/gvariant.c" + line="3629">a #GVariantBuilder the #GVariantType of the container + filename="glib/gvariant.c" + line="3630">the #GVariantType of the container Increases the reference count on @builder. + filename="glib/gvariant.c" + line="3334">Increases the reference count on @builder. Don't call this on stack-allocated #GVariantBuilder instances or bad things will happen. - + a new reference to @builder + filename="glib/gvariant.c" + line="3343">a new reference to @builder a #GVariantBuilder allocated by g_variant_builder_new() + filename="glib/gvariant.c" + line="3336">a #GVariantBuilder allocated by g_variant_builder_new() @@ -53254,23 +58665,23 @@ things will happen. c:identifier="g_variant_builder_unref" version="2.24"> Decreases the reference count on @builder. + filename="glib/gvariant.c" + line="3306">Decreases the reference count on @builder. In the event that there are no more references, releases all memory associated with the #GVariantBuilder. Don't call this on stack-allocated #GVariantBuilder instances or bad things will happen. - + a #GVariantBuilder allocated by g_variant_builder_new() + filename="glib/gvariant.c" + line="3308">a #GVariantBuilder allocated by g_variant_builder_new() @@ -53278,108 +58689,108 @@ things will happen. The range of possible top-level types of #GVariant instances. - + filename="glib/gvariant.c" + line="2161">The range of possible top-level types of #GVariant instances. + The #GVariant is a boolean. + filename="glib/gvariant.c" + line="2163">The #GVariant is a boolean. The #GVariant is a byte. + filename="glib/gvariant.c" + line="2164">The #GVariant is a byte. The #GVariant is a signed 16 bit integer. + filename="glib/gvariant.c" + line="2165">The #GVariant is a signed 16 bit integer. The #GVariant is an unsigned 16 bit integer. + filename="glib/gvariant.c" + line="2166">The #GVariant is an unsigned 16 bit integer. The #GVariant is a signed 32 bit integer. + filename="glib/gvariant.c" + line="2167">The #GVariant is a signed 32 bit integer. The #GVariant is an unsigned 32 bit integer. + filename="glib/gvariant.c" + line="2168">The #GVariant is an unsigned 32 bit integer. The #GVariant is a signed 64 bit integer. + filename="glib/gvariant.c" + line="2169">The #GVariant is a signed 64 bit integer. The #GVariant is an unsigned 64 bit integer. + filename="glib/gvariant.c" + line="2170">The #GVariant is an unsigned 64 bit integer. The #GVariant is a file handle index. + filename="glib/gvariant.c" + line="2171">The #GVariant is a file handle index. The #GVariant is a double precision floating + filename="glib/gvariant.c" + line="2172">The #GVariant is a double precision floating point value. The #GVariant is a normal string. + filename="glib/gvariant.c" + line="2174">The #GVariant is a normal string. The #GVariant is a D-Bus object path + filename="glib/gvariant.c" + line="2175">The #GVariant is a D-Bus object path string. The #GVariant is a D-Bus signature string. + filename="glib/gvariant.c" + line="2177">The #GVariant is a D-Bus signature string. The #GVariant is a variant. + filename="glib/gvariant.c" + line="2178">The #GVariant is a variant. The #GVariant is a maybe-typed value. + filename="glib/gvariant.c" + line="2179">The #GVariant is a maybe-typed value. The #GVariant is an array. + filename="glib/gvariant.c" + line="2180">The #GVariant is an array. The #GVariant is a tuple. + filename="glib/gvariant.c" + line="2181">The #GVariant is a tuple. The #GVariant is a dictionary entry. + filename="glib/gvariant.c" + line="2182">The #GVariant is a dictionary entry. glib:get-type="g_variant_dict_get_type" c:symbol-prefix="variant_dict"> #GVariantDict is a mutable interface to #GVariant dictionaries. + filename="glib/gvariant.c" + line="3843">#GVariantDict is a mutable interface to #GVariant dictionaries. It can be used for doing a sequence of dictionary lookups in an efficient way on an existing #GVariant dictionary or it can be used @@ -53479,11 +58890,11 @@ key is not found. Each returns the new dictionary as a floating return result; } ]| - + - + - + @@ -53504,8 +58915,8 @@ key is not found. Each returns the new dictionary as a floating Allocates and initialises a new #GVariantDict. + filename="glib/gvariant.c" + line="4005">Allocates and initialises a new #GVariantDict. You should call g_variant_dict_unref() on the return value when it is no longer needed. The memory will not be automatically freed by @@ -53515,11 +58926,11 @@ In some cases it may be easier to place a #GVariantDict directly on the stack of the calling function and initialise it with g_variant_dict_init(). This is particularly useful when you are using #GVariantDict to construct a #GVariant. - + a #GVariantDict + filename="glib/gvariant.c" + line="4021">a #GVariantDict @@ -53528,8 +58939,8 @@ using #GVariantDict to construct a #GVariant. nullable="1" allow-none="1"> the #GVariant with which to initialise the + filename="glib/gvariant.c" + line="4007">the #GVariant with which to initialise the dictionary @@ -53537,8 +58948,8 @@ using #GVariantDict to construct a #GVariant. Releases all memory associated with a #GVariantDict without freeing + filename="glib/gvariant.c" + line="4270">Releases all memory associated with a #GVariantDict without freeing the #GVariantDict structure itself. It typically only makes sense to do this on a stack-allocated @@ -53552,15 +58963,15 @@ It is valid to call this function on either an initialised #GVariantDict or one that was previously cleared by an earlier call to g_variant_dict_clear() but it is not valid to call this function on uninitialised memory. - + a #GVariantDict + filename="glib/gvariant.c" + line="4272">a #GVariantDict @@ -53569,52 +58980,52 @@ on uninitialised memory. c:identifier="g_variant_dict_contains" version="2.40"> Checks if @key exists in @dict. - + filename="glib/gvariant.c" + line="4173">Checks if @key exists in @dict. + %TRUE if @key is in @dict + filename="glib/gvariant.c" + line="4180">%TRUE if @key is in @dict a #GVariantDict + filename="glib/gvariant.c" + line="4175">a #GVariantDict the key to look up in the dictionary + filename="glib/gvariant.c" + line="4176">the key to look up in the dictionary Returns the current value of @dict as a #GVariant of type + filename="glib/gvariant.c" + line="4306">Returns the current value of @dict as a #GVariant of type %G_VARIANT_TYPE_VARDICT, clearing it in the process. It is not permissible to use @dict in any way after this call except for reference counting operations (in the case of a heap-allocated #GVariantDict) or by reinitialising it with g_variant_dict_init() (in the case of stack-allocated). - + a new, floating, #GVariant + filename="glib/gvariant.c" + line="4318">a new, floating, #GVariant a #GVariantDict + filename="glib/gvariant.c" + line="4308">a #GVariantDict @@ -53624,8 +59035,8 @@ the case of stack-allocated). version="2.40" introspectable="0"> Initialises a #GVariantDict structure. + filename="glib/gvariant.c" + line="4042">Initialises a #GVariantDict structure. If @from_asv is given, it is used to initialise the dictionary. @@ -53641,15 +59052,15 @@ pass a reference to a #GVariantDict outside of the control of your own code then you should assume that the person receiving that reference may try to use reference counting; you should use g_variant_dict_new() instead of this function. - + a #GVariantDict + filename="glib/gvariant.c" + line="4044">a #GVariantDict nullable="1" allow-none="1"> the initial value for @dict + filename="glib/gvariant.c" + line="4045">the initial value for @dict @@ -53668,38 +59079,38 @@ g_variant_dict_new() instead of this function. version="2.40" introspectable="0"> Inserts a value into a #GVariantDict. + filename="glib/gvariant.c" + line="4194">Inserts a value into a #GVariantDict. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new() followed by g_variant_dict_insert_value(). - + a #GVariantDict + filename="glib/gvariant.c" + line="4196">a #GVariantDict the key to insert a value for + filename="glib/gvariant.c" + line="4197">the key to insert a value for a #GVariant varargs format string + filename="glib/gvariant.c" + line="4198">a #GVariant varargs format string arguments, as per @format_string + filename="glib/gvariant.c" + line="4199">arguments, as per @format_string @@ -53708,31 +59119,31 @@ calling g_variant_new() followed by g_variant_dict_insert_value(). c:identifier="g_variant_dict_insert_value" version="2.40"> Inserts (or replaces) a key in a #GVariantDict. + filename="glib/gvariant.c" + line="4225">Inserts (or replaces) a key in a #GVariantDict. @value is consumed if it is floating. - + a #GVariantDict + filename="glib/gvariant.c" + line="4227">a #GVariantDict the key to insert a value for + filename="glib/gvariant.c" + line="4228">the key to insert a value for the value to insert + filename="glib/gvariant.c" + line="4229">the value to insert @@ -53742,8 +59153,8 @@ calling g_variant_new() followed by g_variant_dict_insert_value(). version="2.40" introspectable="0"> Looks up a value in a #GVariantDict. + filename="glib/gvariant.c" + line="4085">Looks up a value in a #GVariantDict. This function is a wrapper around g_variant_dict_lookup_value() and g_variant_get(). In the case that %NULL would have been returned, @@ -53753,37 +59164,37 @@ value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the -section on [GVariant format strings][gvariant-format-strings-pointers]. - +section on [`GVariant` format strings](gvariant-format-strings.html#pointers). + %TRUE if a value was unpacked + filename="glib/gvariant.c" + line="4104">%TRUE if a value was unpacked a #GVariantDict + filename="glib/gvariant.c" + line="4087">a #GVariantDict the key to look up in the dictionary + filename="glib/gvariant.c" + line="4088">the key to look up in the dictionary a GVariant format string + filename="glib/gvariant.c" + line="4089">a GVariant format string the arguments to unpack the value into + filename="glib/gvariant.c" + line="4090">the arguments to unpack the value into @@ -53792,8 +59203,8 @@ section on [GVariant format strings][gvariant-format-strings-pointers]. c:identifier="g_variant_dict_lookup_value" version="2.40"> Looks up a value in a #GVariantDict. + filename="glib/gvariant.c" + line="4133">Looks up a value in a #GVariantDict. If @key is not found in @dictionary, %NULL is returned. @@ -53804,24 +59215,24 @@ returned. If the key is found and the value has the correct type, it is returned. If @expected_type was specified then any non-%NULL return value will have this type. - + the value of the dictionary key, or %NULL + filename="glib/gvariant.c" + line="4151">the value of the dictionary key, or %NULL a #GVariantDict + filename="glib/gvariant.c" + line="4135">a #GVariantDict the key to look up in the dictionary + filename="glib/gvariant.c" + line="4136">the key to look up in the dictionary nullable="1" allow-none="1"> a #GVariantType, or %NULL + filename="glib/gvariant.c" + line="4137">a #GVariantType, or %NULL Increases the reference count on @dict. + filename="glib/gvariant.c" + line="4342">Increases the reference count on @dict. Don't call this on stack-allocated #GVariantDict instances or bad things will happen. - + a new reference to @dict + filename="glib/gvariant.c" + line="4351">a new reference to @dict a heap-allocated #GVariantDict + filename="glib/gvariant.c" + line="4344">a heap-allocated #GVariantDict @@ -53862,49 +59273,49 @@ things will happen. c:identifier="g_variant_dict_remove" version="2.40"> Removes a key and its associated value from a #GVariantDict. - + filename="glib/gvariant.c" + line="4249">Removes a key and its associated value from a #GVariantDict. + %TRUE if the key was found and removed + filename="glib/gvariant.c" + line="4256">%TRUE if the key was found and removed a #GVariantDict + filename="glib/gvariant.c" + line="4251">a #GVariantDict the key to remove + filename="glib/gvariant.c" + line="4252">the key to remove Decreases the reference count on @dict. + filename="glib/gvariant.c" + line="4365">Decreases the reference count on @dict. In the event that there are no more references, releases all memory associated with the #GVariantDict. Don't call this on stack-allocated #GVariantDict instances or bad things will happen. - + a heap-allocated #GVariantDict + filename="glib/gvariant.c" + line="4367">a heap-allocated #GVariantDict @@ -53912,10 +59323,10 @@ things will happen. #GVariantIter is an opaque data structure and can only be accessed + filename="glib/gvariant.c" + line="2932">#GVariantIter is an opaque data structure and can only be accessed using the following functions. - + @@ -53926,8 +59337,8 @@ using the following functions. version="2.24" introspectable="0"> Creates a new heap-allocated #GVariantIter to iterate over the + filename="glib/gvariant.c" + line="3030">Creates a new heap-allocated #GVariantIter to iterate over the container that was being iterated over by @iter. Iteration begins on the new iterator from the current position of the old iterator but the two copies are independent past that point. @@ -53937,37 +59348,37 @@ need it. A reference is taken to the container that @iter is iterating over and will be related only when g_variant_iter_free() is called. - + a new heap-allocated #GVariantIter + filename="glib/gvariant.c" + line="3045">a new heap-allocated #GVariantIter a #GVariantIter + filename="glib/gvariant.c" + line="3032">a #GVariantIter Frees a heap-allocated #GVariantIter. Only call this function on + filename="glib/gvariant.c" + line="3084">Frees a heap-allocated #GVariantIter. Only call this function on iterators that were returned by g_variant_iter_new() or g_variant_iter_copy(). - + a heap-allocated #GVariantIter + filename="glib/gvariant.c" + line="3086">a heap-allocated #GVariantIter @@ -53977,31 +59388,31 @@ g_variant_iter_copy(). version="2.24" introspectable="0"> Initialises (without allocating) a #GVariantIter. @iter may be + filename="glib/gvariant.c" + line="3001">Initialises (without allocating) a #GVariantIter. @iter may be completely uninitialised prior to this call; its old value is ignored. The iterator remains valid for as long as @value exists, and need not be freed in any way. - + the number of items in @value + filename="glib/gvariant.c" + line="3013">the number of items in @value a pointer to a #GVariantIter + filename="glib/gvariant.c" + line="3003">a pointer to a #GVariantIter a container #GVariant + filename="glib/gvariant.c" + line="3004">a container #GVariant @@ -54011,8 +59422,8 @@ be freed in any way. version="2.24" introspectable="0"> Gets the next item in the container and unpacks it into the variable + filename="glib/gvariant.c" + line="5828">Gets the next item in the container and unpacks it into the variable argument list according to @format_string, returning %TRUE. If no more items remain then %FALSE is returned. @@ -54073,32 +59484,32 @@ thereby avoiding the need to free anything as well). the values and also determines if the values are copied or borrowed. See the section on -[GVariant format strings][gvariant-format-strings-pointers]. - +[`GVariant` format strings](gvariant-format-strings.html#pointers). + %TRUE if a value was unpacked, or %FALSE if there was no + filename="glib/gvariant.c" + line="5897">%TRUE if a value was unpacked, or %FALSE if there was no value a #GVariantIter + filename="glib/gvariant.c" + line="5830">a #GVariantIter a GVariant format string + filename="glib/gvariant.c" + line="5831">a GVariant format string the arguments to unpack the value into + filename="glib/gvariant.c" + line="5832">the arguments to unpack the value into @@ -54107,24 +59518,24 @@ See the section on c:identifier="g_variant_iter_n_children" version="2.24"> Queries the number of child items in the container that we are + filename="glib/gvariant.c" + line="3062">Queries the number of child items in the container that we are iterating over. This is the total number of items -- not the number of items remaining. This function might be useful for preallocation of arrays. - + the number of children in the container + filename="glib/gvariant.c" + line="3072">the number of children in the container a #GVariantIter + filename="glib/gvariant.c" + line="3064">a #GVariantIter @@ -54134,8 +59545,8 @@ This function might be useful for preallocation of arrays. version="2.24" introspectable="0"> Gets the next item in the container and unpacks it into the variable + filename="glib/gvariant.c" + line="5750">Gets the next item in the container and unpacks it into the variable argument list according to @format_string, returning %TRUE. If no more items remain then %FALSE is returned. @@ -54175,31 +59586,31 @@ when dealing with loops, see g_variant_iter_loop(). the values and also determines if the values are copied or borrowed. See the section on -[GVariant format strings][gvariant-format-strings-pointers]. - +[`GVariant` format strings](gvariant-format-strings.html#pointers). + %TRUE if a value was unpacked, or %FALSE if there as no value + filename="glib/gvariant.c" + line="5798">%TRUE if a value was unpacked, or %FALSE if there as no value a #GVariantIter + filename="glib/gvariant.c" + line="5752">a #GVariantIter a GVariant format string + filename="glib/gvariant.c" + line="5753">a GVariant format string the arguments to unpack the value into + filename="glib/gvariant.c" + line="5754">the arguments to unpack the value into @@ -54208,8 +59619,8 @@ See the section on c:identifier="g_variant_iter_next_value" version="2.24"> Gets the next item in the container. If no more items remain then + filename="glib/gvariant.c" + line="3105">Gets the next item in the container. If no more items remain then %NULL is returned. Use g_variant_unref() to drop your reference on the return value when @@ -54236,18 +59647,18 @@ Here is an example for iterating with g_variant_iter_next_value(): } } ]| - + a #GVariant, or %NULL + filename="glib/gvariant.c" + line="3137">a #GVariant, or %NULL a #GVariantIter + filename="glib/gvariant.c" + line="3107">a #GVariantIter @@ -54257,345 +59668,350 @@ Here is an example for iterating with g_variant_iter_next_value(): c:type="GVariantParseError" glib:error-domain="g-variant-parse-error-quark"> Error codes returned by parsing text-format GVariants. - + filename="glib/gvariant-parser.c" + line="53">Error codes returned by parsing text-format GVariants. + generic error (unused) + filename="glib/gvariant-parser.c" + line="55">generic error (unused) a non-basic #GVariantType was given where a basic type was expected + filename="glib/gvariant-parser.c" + line="56">a non-basic #GVariantType was given where a basic type was expected cannot infer the #GVariantType + filename="glib/gvariant-parser.c" + line="57">cannot infer the #GVariantType an indefinite #GVariantType was given where a definite type was expected + filename="glib/gvariant-parser.c" + line="58">an indefinite #GVariantType was given where a definite type was expected extra data after parsing finished + filename="glib/gvariant-parser.c" + line="59">extra data after parsing finished invalid character in number or unicode escape + filename="glib/gvariant-parser.c" + line="60">invalid character in number or unicode escape not a valid #GVariant format string + filename="glib/gvariant-parser.c" + line="61">not a valid #GVariant format string not a valid object path + filename="glib/gvariant-parser.c" + line="62">not a valid object path not a valid type signature + filename="glib/gvariant-parser.c" + line="63">not a valid type signature not a valid #GVariant type string + filename="glib/gvariant-parser.c" + line="64">not a valid #GVariant type string could not find a common type for array entries + filename="glib/gvariant-parser.c" + line="65">could not find a common type for array entries the numerical value is out of range of the given type + filename="glib/gvariant-parser.c" + line="66">the numerical value is out of range of the given type the numerical value is out of range for any type + filename="glib/gvariant-parser.c" + line="67">the numerical value is out of range for any type cannot parse as variant of the specified type + filename="glib/gvariant-parser.c" + line="68">cannot parse as variant of the specified type an unexpected token was encountered + filename="glib/gvariant-parser.c" + line="69">an unexpected token was encountered an unknown keyword was encountered + filename="glib/gvariant-parser.c" + line="70">an unknown keyword was encountered unterminated string constant + filename="glib/gvariant-parser.c" + line="71">unterminated string constant no value given + filename="glib/gvariant-parser.c" + line="72">no value given variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64) + filename="glib/gvariant-parser.c" + line="73">variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64) This section introduces the GVariant type system. It is based, in + filename="glib/gvarianttype.c" + line="34">A type in the [type@GLib.Variant] type system. + +This section introduces the [type@GLib.Variant] type system. It is based, in large part, on the D-Bus type system, with two major changes and some minor lifting of restrictions. The [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), therefore, provides a significant amount of -information that is useful when working with GVariant. +information that is useful when working with [type@GLib.Variant]. The first major change with respect to the D-Bus type system is the -introduction of maybe (or "nullable") types. Any type in GVariant can be -converted to a maybe type, in which case, "nothing" (or "null") becomes a -valid value. Maybe types have been added by introducing the -character "m" to type strings. +introduction of maybe (or ‘nullable’) types. Any type in [type@GLib.Variant] +can be converted to a maybe type, in which case, `nothing` (or `null`) +becomes a valid value. Maybe types have been added by introducing the +character `m` to type strings. -The second major change is that the GVariant type system supports the -concept of "indefinite types" -- types that are less specific than +The second major change is that the [type@GLib.Variant] type system supports +the concept of ‘indefinite types’ — types that are less specific than the normal types found in D-Bus. For example, it is possible to speak -of "an array of any type" in GVariant, where the D-Bus type system -would require you to speak of "an array of integers" or "an array of -strings". Indefinite types have been added by introducing the -characters "*", "?" and "r" to type strings. +of ‘an array of any type’ in [type@GLib.Variant], where the D-Bus type system +would require you to speak of ‘an array of integers’ or ‘an array of +strings’. Indefinite types have been added by introducing the +characters `*`, `?` and `r` to type strings. Finally, all arbitrary restrictions relating to the complexity of types are lifted along with the restriction that dictionary entries may only appear nested inside of arrays. -Just as in D-Bus, GVariant types are described with strings ("type -strings"). Subject to the differences mentioned above, these strings +Just as in D-Bus, [type@GLib.Variant] types are described with strings (‘type +strings’). Subject to the differences mentioned above, these strings are of the same form as those found in D-Bus. Note, however: D-Bus always works in terms of messages and therefore individual type -strings appear nowhere in its interface. Instead, "signatures" +strings appear nowhere in its interface. Instead, ‘signatures’ are a concatenation of the strings of the type of each argument in a -message. GVariant deals with single values directly so GVariant type -strings always describe the type of exactly one value. This means -that a D-Bus signature string is generally not a valid GVariant type -string -- except in the case that it is the signature of a message -containing exactly one argument. +message. [type@GLib.Variant] deals with single values directly so +[type@GLib.Variant] type strings always describe the type of exactly one +value. This means that a D-Bus signature string is generally not a valid +[type@GLib.Variant] type string — except in the case that it is the signature +of a message containing exactly one argument. An indefinite type is similar in spirit to what may be called an abstract type in other type systems. No value can exist that has an indefinite type as its type, but values can exist that have types that are subtypes of indefinite types. That is to say, -g_variant_get_type() will never return an indefinite type, but -calling g_variant_is_of_type() with an indefinite type may return -%TRUE. For example, you cannot have a value that represents "an -array of no particular type", but you can have an "array of integers" -which certainly matches the type of "an array of no particular type", -since "array of integers" is a subtype of "array of no particular -type". +[method@GLib.Variant.get_type] will never return an indefinite type, but +calling [method@GLib.Variant.is_of_type] with an indefinite type may return +true. For example, you cannot have a value that represents ‘an +array of no particular type’, but you can have an ‘array of integers’ +which certainly matches the type of ‘an array of no particular type’, +since ‘array of integers’ is a subtype of ‘array of no particular +type’. This is similar to how instances of abstract classes may not directly exist in other type systems, but instances of their non-abstract subtypes may. For example, in GTK, no object that has -the type of #GtkBin can exist (since #GtkBin is an abstract class), -but a #GtkWindow can certainly be instantiated, and you would say -that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of -#GtkBin). +the type of [`GtkWidget`](https://docs.gtk.org/gtk4/class.Widget.html) can +exist (since `GtkWidget` is an abstract class), but a [`GtkWindow`](https://docs.gtk.org/gtk4/class.Window.html) +can certainly be instantiated, and you would say that a `GtkWindow` is a +`GtkWidget` (since `GtkWindow` is a subclass of `GtkWidget`). + +Two types may not be compared by value; use [method@GLib.VariantType.equal] +or [method@GLib.VariantType.is_subtype_of] May be copied using +[method@GLib.VariantType.copy] and freed using [method@GLib.VariantType.free]. ## GVariant Type Strings -A GVariant type string can be any of the following: +A [type@GLib.Variant] type string can be any of the following: - any basic type string (listed below) - -- "v", "r" or "*" - -- one of the characters 'a' or 'm', followed by another type string - -- the character '(', followed by a concatenation of zero or more other - type strings, followed by the character ')' - -- the character '{', followed by a basic type string (see below), - followed by another type string, followed by the character '}' +- `v`, `r` or `*` +- one of the characters `a` or `m`, followed by another type string +- the character `(`, followed by a concatenation of zero or more other + type strings, followed by the character `)` +- the character `{`, followed by a basic type string (see below), + followed by another type string, followed by the character `}` A basic type string describes a basic type (as per -g_variant_type_is_basic()) and is always a single character in length. -The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", -"h", "d", "s", "o", "g" and "?". - -The above definition is recursive to arbitrary depth. "aaaaai" and -"(ui(nq((y)))s)" are both valid type strings, as is -"a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant -imposes a limit on recursion depth of 65 nested containers. This is the -limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to -be nested in a top-level tuple. +[method@GLib.VariantType.is_basic]) and is always a single character in +length. The valid basic type strings are `b`, `y`, `n`, `q`, `i`, `u`, `x`, +`t`, `h`, `d`, `s`, `o`, `g` and `?`. + +The above definition is recursive to arbitrary depth. `aaaaai` and +`(ui(nq((y)))s)` are both valid type strings, as is +`a(aa(ui)(qna{ya(yd)}))`. In order to not hit memory limits, +[type@GLib.Variant] imposes a limit on recursion depth of 65 nested +containers. This is the limit in the D-Bus specification (64) plus one to +allow a [`GDBusMessage`](../gio/class.DBusMessage.html) to be nested in +a top-level tuple. The meaning of each of the characters is as follows: -- `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. -- `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. -- `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. -- `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. -- `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. -- `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. -- `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. -- `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. -- `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value + +- `b`: the type string of `G_VARIANT_TYPE_BOOLEAN`; a boolean value. +- `y`: the type string of `G_VARIANT_TYPE_BYTE`; a byte. +- `n`: the type string of `G_VARIANT_TYPE_INT16`; a signed 16 bit integer. +- `q`: the type string of `G_VARIANT_TYPE_UINT16`; an unsigned 16 bit integer. +- `i`: the type string of `G_VARIANT_TYPE_INT32`; a signed 32 bit integer. +- `u`: the type string of `G_VARIANT_TYPE_UINT32`; an unsigned 32 bit integer. +- `x`: the type string of `G_VARIANT_TYPE_INT64`; a signed 64 bit integer. +- `t`: the type string of `G_VARIANT_TYPE_UINT64`; an unsigned 64 bit integer. +- `h`: the type string of `G_VARIANT_TYPE_HANDLE`; a signed 32 bit value that, by convention, is used as an index into an array of file descriptors that are sent alongside a D-Bus message. -- `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision +- `d`: the type string of `G_VARIANT_TYPE_DOUBLE`; a double precision floating point value. -- `s`: the type string of %G_VARIANT_TYPE_STRING; a string. -- `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form +- `s`: the type string of `G_VARIANT_TYPE_STRING`; a string. +- `o`: the type string of `G_VARIANT_TYPE_OBJECT_PATH`; a string in the form of a D-Bus object path. -- `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of +- `g`: the type string of `G_VARIANT_TYPE_SIGNATURE`; a string in the form of a D-Bus type signature. -- `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that +- `?`: the type string of `G_VARIANT_TYPE_BASIC`; an indefinite type that is a supertype of any of the basic types. -- `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that +- `v`: the type string of `G_VARIANT_TYPE_VARIANT`; a container type that contain any other type of value. - `a`: used as a prefix on another type string to mean an array of that - type; the type string "ai", for example, is the type of an array of + type; the type string `ai`, for example, is the type of an array of signed 32-bit integers. -- `m`: used as a prefix on another type string to mean a "maybe", or - "nullable", version of that type; the type string "ms", for example, +- `m`: used as a prefix on another type string to mean a ‘maybe’, or + ‘nullable’, version of that type; the type string `ms`, for example, is the type of a value that maybe contains a string, or maybe contains nothing. - `()`: used to enclose zero or more other concatenated type strings to - create a tuple type; the type string "(is)", for example, is the type of + create a tuple type; the type string `(is)`, for example, is the type of a pair of an integer and a string. -- `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is +- `r`: the type string of `G_VARIANT_TYPE_TUPLE`; an indefinite type that is a supertype of any tuple type, regardless of the number of items. - `{}`: used to enclose a basic type string concatenated with another type string to create a dictionary entry type, which usually appears inside of - an array to form a dictionary; the type string "a{sd}", for example, is + an array to form a dictionary; the type string `a{sd}`, for example, is the type of a dictionary that maps strings to double precision floating point values. The first type (the basic type) is the key type and the second type is the value type. The reason that the first type is restricted to being a basic type is so that it can easily be hashed. -- `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is +- `*`: the type string of `G_VARIANT_TYPE_ANY`; the indefinite type that is a supertype of all types. Note that, as with all type strings, this character represents exactly one type. It cannot be used inside of tuples - to mean "any number of items". + to mean ‘any number of items’. Any type string of a container that contains an indefinite type is, -itself, an indefinite type. For example, the type string "a*" -(corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type -that is a supertype of every array type. "(*s)" is a supertype +itself, an indefinite type. For example, the type string `a*` +(corresponding to `G_VARIANT_TYPE_ARRAY`) is an indefinite type +that is a supertype of every array type. `(*s)` is a supertype of all tuples that contain exactly two items where the second item is a string. -"a{?*}" is an indefinite type that is a supertype of all arrays +`a{?*}` is an indefinite type that is a supertype of all arrays containing dictionary entries where the key is any basic type and the value is any type at all. This is, by definition, a dictionary, -so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note +so this type string corresponds to `G_VARIANT_TYPE_DICTIONARY`. Note that, due to the restriction that the key of a dictionary entry must -be a basic type, "{**}" is not a valid type string. - +be a basic type, `{**}` is not a valid type string. + Creates a new #GVariantType corresponding to the type string given -by @type_string. It is appropriate to call g_variant_type_free() on -the return value. + filename="glib/gvarianttype.c" + line="413">Creates a new [type@GLib.VariantType] corresponding to the type string given +by @type_string. + +It is appropriate to call [method@GLib.VariantType.free] on the return value. It is a programmer error to call this function with an invalid type -string. Use g_variant_type_string_is_valid() if you are unsure. - +string. Use [func@GLib.VariantType.string_is_valid] if you are unsure. + a new #GVariantType + filename="glib/gvarianttype.c" + line="425">a new [type@GLib.VariantType] a valid GVariant type string + filename="glib/gvarianttype.c" + line="415">a valid [GVariant type string](./struct.VariantType.html#gvariant-type-strings) Constructs the type corresponding to an array of elements of the + filename="glib/gvarianttype.c" + line="1174">Constructs the type corresponding to an array of elements of the type @type. -It is appropriate to call g_variant_type_free() on the return value. - +It is appropriate to call [method@GLib.VariantType.first] on the return value. + a new array #GVariantType - + filename="glib/gvarianttype.c" + line="1183">a new array type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="1176">an element type @@ -54603,83 +60019,80 @@ Since 2.24 Constructs the type corresponding to a dictionary entry with a key + filename="glib/gvarianttype.c" + line="1232">Constructs the type corresponding to a dictionary entry with a key of type @key and a value of type @value. -It is appropriate to call g_variant_type_free() on the return value. - +It is appropriate to call [method@GLib.VariantType.free] on the return value. + a new dictionary entry #GVariantType - + filename="glib/gvarianttype.c" + line="1242">a new dictionary entry type Since 2.24 a basic #GVariantType + filename="glib/gvarianttype.c" + line="1234">a basic type to use for the key a #GVariantType + filename="glib/gvarianttype.c" + line="1235">a type to use for the value Constructs the type corresponding to a maybe instance containing -type @type or Nothing. + filename="glib/gvarianttype.c" + line="1203">Constructs the type corresponding to a ‘maybe’ instance containing +type @type or `Nothing`. -It is appropriate to call g_variant_type_free() on the return value. - +It is appropriate to call [method@GLib.VariantType.free] on the return value. + a new maybe #GVariantType - + filename="glib/gvarianttype.c" + line="1212">a new ‘maybe’ type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="1205">an element type Constructs a new tuple type, from @items. + filename="glib/gvarianttype.c" + line="1089">Constructs a new tuple type, from @items. -@length is the number of items in @items, or -1 to indicate that -@items is %NULL-terminated. +@length is the number of items in @items, or `-1` to indicate that +@items is `NULL`-terminated. -It is appropriate to call g_variant_type_free() on the return value. - +It is appropriate to call [method@GLib.VariantType.free] on the return value. + a new tuple #GVariantType - + filename="glib/gvarianttype.c" + line="1101">a new tuple type Since 2.24 an array of #GVariantTypes, one for each item + filename="glib/gvarianttype.c" + line="1091">an array of types, one for each item @@ -54688,166 +60101,165 @@ Since 2.24 the length of @items, or -1 + filename="glib/gvarianttype.c" + line="1092">the length of @items, or `-1` Makes a copy of a #GVariantType. It is appropriate to call -g_variant_type_free() on the return value. @type may not be %NULL. - + filename="glib/gvarianttype.c" + line="384">Makes a copy of a [type@GLib.VariantType]. + +It is appropriate to call [method@GLib.VariantType.free] on the return value. +@type may not be `NULL`. + a new #GVariantType - + filename="glib/gvarianttype.c" + line="393">a new [type@GLib.VariantType] Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="386">type to copy Returns a newly-allocated copy of the type string corresponding to -@type. The returned string is nul-terminated. It is appropriate to -call g_free() on the return value. - + filename="glib/gvarianttype.c" + line="501">Returns a newly-allocated copy of the type string corresponding to @type. + +The returned string is nul-terminated. It is appropriate to call +[func@GLib.free] on the return value. + the corresponding type string - + filename="glib/gvarianttype.c" + line="510">the corresponding type string Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="503">type to copy Determines the element type of an array or maybe type. + filename="glib/gvarianttype.c" + line="903">Determines the element type of an array or ‘maybe’ type. -This function may only be used with array or maybe types. - +This function may only be used with array or ‘maybe’ types. + the element type of @type - + filename="glib/gvarianttype.c" + line="911">the element type of @type Since 2.24 an array or maybe #GVariantType + filename="glib/gvarianttype.c" + line="905">an array or ‘maybe’ type Compares @type1 and @type2 for equality. + filename="glib/gvarianttype.c" + line="782">Compares @type1 and @type2 for equality. -Only returns %TRUE if the types are exactly equal. Even if one type -is an indefinite type and the other is a subtype of it, %FALSE will +Only returns true if the types are exactly equal. Even if one type +is an indefinite type and the other is a subtype of it, false will be returned if they are not exactly equal. If you want to check for -subtypes, use g_variant_type_is_subtype_of(). +subtypes, use [method@GLib.VariantType.is_subtype_of]. -The argument types of @type1 and @type2 are only #gconstpointer to -allow use with #GHashTable without function pointer casting. For -both arguments, a valid #GVariantType must be provided. - +The argument types of @type1 and @type2 are only `gconstpointer` to +allow use with [type@GLib.HashTable] without function pointer casting. For +both arguments, a valid [type@GLib.VariantType] must be provided. + %TRUE if @type1 and @type2 are exactly equal - + filename="glib/gvarianttype.c" + line="798">true if @type1 and @type2 are exactly equal Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="784">type to compare a #GVariantType + filename="glib/gvarianttype.c" + line="785">another type to compare Determines the first item type of a tuple or dictionary entry + filename="glib/gvarianttype.c" + line="928">Determines the first item type of a tuple or dictionary entry type. This function may only be used with tuple or dictionary entry types, but must not be used with the generic tuple type -%G_VARIANT_TYPE_TUPLE. +`G_VARIANT_TYPE_TUPLE`. In the case of a dictionary entry type, this returns the type of the key. -%NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. +`NULL` is returned in case of @type being `G_VARIANT_TYPE_UNIT`. -This call, together with g_variant_type_next() provides an iterator +This call, together with [method@GLib.VariantType.next] provides an iterator interface over tuple and dictionary entry types. - - + + the first item type of @type, or %NULL - + filename="glib/gvarianttype.c" + line="947">the first item type of @type, or `NULL` + if the type has no item types Since 2.24 a tuple or dictionary entry #GVariantType + filename="glib/gvarianttype.c" + line="930">a tuple or dictionary entry type Frees a #GVariantType that was allocated with -g_variant_type_copy(), g_variant_type_new() or one of the container -type constructor functions. + filename="glib/gvarianttype.c" + line="364">Frees a [type@GLib.VariantType] that was allocated with +[method@GLib.VariantType.copy], [ctor@GLib.VariantType.new] or one of the +container type constructor functions. -In the case that @type is %NULL, this function does nothing. +In the case that @type is `NULL`, this function does nothing. Since 2.24 - + @@ -54857,8 +60269,8 @@ Since 2.24 nullable="1" allow-none="1"> a #GVariantType, or %NULL + filename="glib/gvarianttype.c" + line="366">type to free @@ -54866,391 +60278,383 @@ Since 2.24 Returns the length of the type string corresponding to the given -@type. This function must be used to determine the valid extent of -the memory region returned by g_variant_type_peek_string(). - + filename="glib/gvarianttype.c" + line="436">Returns the length of the type string corresponding to the given @type. + +This function must be used to determine the valid extent of +the memory region returned by [method@GLib.VariantType.peek_string]. + the length of the corresponding type string - + filename="glib/gvarianttype.c" + line="445">the length of the corresponding type string Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="438">type to measure Hashes @type. + filename="glib/gvarianttype.c" + line="761">Hashes @type. -The argument type of @type is only #gconstpointer to allow use with -#GHashTable without function pointer casting. A valid -#GVariantType must be provided. - +The argument type of @type is only `gconstpointer` to allow use with +[type@GLib.HashTable] without function pointer casting. A valid +[type@GLib.VariantType] must be provided. + the hash value - + filename="glib/gvarianttype.c" + line="771">the hash value Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="763">type to hash Determines if the given @type is an array type. This is true if the -type string for @type starts with an 'a'. + filename="glib/gvarianttype.c" + line="671">Determines if the given @type is an array type. + +This is true if the type string for @type starts with an `a`. -This function returns %TRUE for any indefinite type for which every -definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for +This function returns true for any indefinite type for which every +definite subtype is an array type — `G_VARIANT_TYPE_ARRAY`, for example. - + %TRUE if @type is an array type - + filename="glib/gvarianttype.c" + line="683">true if @type is an array type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="673">type to check Determines if the given @type is a basic type. + filename="glib/gvarianttype.c" + line="600">Determines if the given @type is a basic type. Basic types are booleans, bytes, integers, doubles, strings, object paths and signatures. Only a basic type may be used as the key of a dictionary entry. -This function returns %FALSE for all indefinite types except -%G_VARIANT_TYPE_BASIC. - +This function returns `FALSE` for all indefinite types except +`G_VARIANT_TYPE_BASIC`. + %TRUE if @type is a basic type - + filename="glib/gvarianttype.c" + line="614">true if @type is a basic type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="602">type to check Determines if the given @type is a container type. + filename="glib/gvarianttype.c" + line="561">Determines if the given @type is a container type. Container types are any array, maybe, tuple, or dictionary entry types plus the variant type. -This function returns %TRUE for any indefinite type for which every -definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for +This function returns true for any indefinite type for which every +definite subtype is a container — `G_VARIANT_TYPE_ARRAY`, for example. - + %TRUE if @type is a container type - + filename="glib/gvarianttype.c" + line="574">true if @type is a container type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="563">type to check Determines if the given @type is definite (ie: not indefinite). + filename="glib/gvarianttype.c" + line="522">Determines if the given @type is definite (ie: not indefinite). A type is definite if its type string does not contain any indefinite -type characters ('*', '?', or 'r'). +type characters (`*`, `?`, or `r`). -A #GVariant instance may not have an indefinite type, so calling -this function on the result of g_variant_get_type() will always -result in %TRUE being returned. Calling this function on an -indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in -%FALSE being returned. - +A [type@GLib.Variant] instance may not have an indefinite type, so calling +this function on the result of [method@GLib.Variant.get_type] will always +result in true being returned. Calling this function on an +indefinite type like `G_VARIANT_TYPE_ARRAY`, however, will result in +`FALSE` being returned. + %TRUE if @type is definite - + filename="glib/gvarianttype.c" + line="537">true if @type is definite Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="524">type to check Determines if the given @type is a dictionary entry type. This is -true if the type string for @type starts with a '{'. + filename="glib/gvarianttype.c" + line="721">Determines if the given @type is a dictionary entry type. -This function returns %TRUE for any indefinite type for which every -definite subtype is a dictionary entry type -- -%G_VARIANT_TYPE_DICT_ENTRY, for example. - +This is true if the type string for @type starts with a `{`. + +This function returns true for any indefinite type for which every +definite subtype is a dictionary entry type — +`G_VARIANT_TYPE_DICT_ENTRY`, for example. + %TRUE if @type is a dictionary entry type - + filename="glib/gvarianttype.c" + line="733">true if @type is a dictionary entry type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="723">type to check Determines if the given @type is a maybe type. This is true if the -type string for @type starts with an 'm'. + filename="glib/gvarianttype.c" + line="648">Determines if the given @type is a ‘maybe’ type. -This function returns %TRUE for any indefinite type for which every -definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for +This is true if the type string for @type starts with an `m`. + +This function returns true for any indefinite type for which every +definite subtype is a ‘maybe’ type — `G_VARIANT_TYPE_MAYBE`, for example. - + %TRUE if @type is a maybe type - + filename="glib/gvarianttype.c" + line="660">true if @type is a ‘maybe’ type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="650">type to check Checks if @type is a subtype of @supertype. + filename="glib/gvarianttype.c" + line="811">Checks if @type is a subtype of @supertype. -This function returns %TRUE if @type is a subtype of @supertype. All +This function returns true if @type is a subtype of @supertype. All types are considered to be subtypes of themselves. Aside from that, only indefinite types can have subtypes. - + %TRUE if @type is a subtype of @supertype - + filename="glib/gvarianttype.c" + line="822">true if @type is a subtype of @supertype Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="813">type to check a #GVariantType + filename="glib/gvarianttype.c" + line="814">type of potential supertype Determines if the given @type is a tuple type. This is true if the -type string for @type starts with a '(' or if @type is -%G_VARIANT_TYPE_TUPLE. + filename="glib/gvarianttype.c" + line="694">Determines if the given @type is a tuple type. + +This is true if the type string for @type starts with a `(` or if @type is +`G_VARIANT_TYPE_TUPLE`. -This function returns %TRUE for any indefinite type for which every -definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for +This function returns true for any indefinite type for which every +definite subtype is a tuple type — `G_VARIANT_TYPE_TUPLE`, for example. - + %TRUE if @type is a tuple type - + filename="glib/gvarianttype.c" + line="707">true if @type is a tuple type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="696">type to check Determines if the given @type is the variant type. - + filename="glib/gvarianttype.c" + line="744">Determines if the given @type is the variant type. + %TRUE if @type is the variant type - + filename="glib/gvarianttype.c" + line="750">true if @type is the variant type Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="746">type to check Determines the key type of a dictionary entry type. + filename="glib/gvarianttype.c" + line="1035">Determines the key type of a dictionary entry type. This function may only be used with a dictionary entry type. Other than the additional restriction, this call is equivalent to -g_variant_type_first(). - +[method@GLib.VariantType.first]. + the key type of the dictionary entry - + filename="glib/gvarianttype.c" + line="1045">the key type of the dictionary entry Since 2.24 a dictionary entry #GVariantType + filename="glib/gvarianttype.c" + line="1037">a dictionary entry type Determines the number of items contained in a tuple or + filename="glib/gvarianttype.c" + line="1003">Determines the number of items contained in a tuple or dictionary entry type. This function may only be used with tuple or dictionary entry types, but must not be used with the generic tuple type -%G_VARIANT_TYPE_TUPLE. +`G_VARIANT_TYPE_TUPLE`. In the case of a dictionary entry type, this function will always -return 2. - +return `2`. + the number of items in @type - + filename="glib/gvarianttype.c" + line="1017">the number of items in @type Since 2.24 a tuple or dictionary entry #GVariantType + filename="glib/gvarianttype.c" + line="1005">a tuple or dictionary entry type Determines the next item type of a tuple or dictionary entry + filename="glib/gvarianttype.c" + line="967">Determines the next item type of a tuple or dictionary entry type. @type must be the result of a previous call to -g_variant_type_first() or g_variant_type_next(). +[method@GLib.VariantType.first] or [method@GLib.VariantType.next]. If called on the key type of a dictionary entry then this call returns the value type. If called on the value type of a dictionary -entry then this call returns %NULL. +entry then this call returns `NULL`. -For tuples, %NULL is returned when @type is the last item in a tuple. - - +For tuples, `NULL` is returned when @type is the last item in the tuple. + + the next #GVariantType after @type, or %NULL - + filename="glib/gvarianttype.c" + line="983">the next type after @type, or `NULL` if + there are no further types Since 2.24 a #GVariantType from a previous call + filename="glib/gvarianttype.c" + line="969">a type from a previous call @@ -55259,68 +60663,67 @@ Since 2.24 c:identifier="g_variant_type_peek_string" introspectable="0"> Returns the type string corresponding to the given @type. The -result is not nul-terminated; in order to determine its length you -must call g_variant_type_get_string_length(). + filename="glib/gvarianttype.c" + line="479">Returns the type string corresponding to the given @type. + +The result is not nul-terminated; in order to determine its length you +must call [method@GLib.VariantType.get_string_length]. -To get a nul-terminated string, see g_variant_type_dup_string(). - +To get a nul-terminated string, see [method@GLib.VariantType.dup_string]. + the corresponding type string (not nul-terminated) - + filename="glib/gvarianttype.c" + line="490">the corresponding type string (not nul-terminated) Since 2.24 a #GVariantType + filename="glib/gvarianttype.c" + line="481">type to peek at Determines the value type of a dictionary entry type. + filename="glib/gvarianttype.c" + line="1061">Determines the value type of a dictionary entry type. This function may only be used with a dictionary entry type. - + the value type of the dictionary entry - + filename="glib/gvarianttype.c" + line="1069">the value type of the dictionary entry Since 2.24 a dictionary entry #GVariantType + filename="glib/gvarianttype.c" + line="1063">a dictionary entry type - + - + - + @@ -55333,24 +60736,25 @@ Since 2.24 Checks if @type_string is a valid GVariant type string. This call is -equivalent to calling g_variant_type_string_scan() and confirming -that the following character is a nul terminator. - + filename="glib/gvarianttype.c" + line="338">Checks if @type_string is a valid +[GVariant type string](./struct.VariantType.html#gvariant-type-strings). + +This call is equivalent to calling [func@GLib.VariantType.string_scan] and +confirming that the following character is a nul terminator. + %TRUE if @type_string is exactly one valid type string - + filename="glib/gvarianttype.c" + line="348">true if @type_string is exactly one valid type string Since 2.24 a pointer to any string + filename="glib/gvarianttype.c" + line="340">a pointer to any string @@ -55359,8 +60763,9 @@ Since 2.24 c:identifier="g_variant_type_string_scan" version="2.24"> Scan for a single complete and valid GVariant type string in @string. + filename="glib/gvarianttype.c" + line="276">Scan for a single complete and valid GVariant type string in @string. + The memory pointed to by @limit (or bytes beyond it) is never accessed. @@ -55372,19 +60777,19 @@ If there is no valid type string starting at @string, or if the type string does not end before @limit then %FALSE is returned. For the simple case of checking if a string is a valid type string, -see g_variant_type_string_is_valid(). - +see [func@GLib.VariantType.string_is_valid]. + %TRUE if a valid type string was found + filename="glib/gvarianttype.c" + line="297">true if a valid type string was found a pointer to any string + filename="glib/gvarianttype.c" + line="278">a pointer to any string nullable="1" allow-none="1"> the end of @string, or %NULL + filename="glib/gvarianttype.c" + line="279">the end of @string optional="1" allow-none="1"> location to store the end pointer, or %NULL + filename="glib/gvarianttype.c" + line="280">location to store the end pointer @@ -55412,11 +60817,11 @@ see g_variant_type_string_is_valid(). Declares a type of function which takes no arguments and has no return value. It is used to specify the type function passed to g_atexit(). - + @@ -55425,59 +60830,32 @@ function passed to g_atexit(). c:identifier="G_WIN32_DLLMAIN_FOR_DLL_NAME" introspectable="0"> On Windows, this macro defines a DllMain() function that stores + filename="glib/docs.c" + line="1840">On Windows, this macro defines a DllMain() function that stores the actual DLL name that the code being compiled will be included in. On non-Windows platforms, expands to nothing. - + empty or "static" + filename="glib/docs.c" + line="1842">empty or "static" the name of the (pointer to the) char array where + filename="glib/docs.c" + line="1843">the name of the (pointer to the) char array where the DLL name will be stored. If this is used, you must also include `windows.h`. If you need a more complex DLL entry point function, you cannot use this - - On Windows, this macro defines an expression which evaluates to -%TRUE if the code is running on a version of Windows where the wide -character versions of the Win32 API functions, and the wide character -versions of the C library functions work. (They are always present in -the DLLs, but don't work on Windows 9x and Me.) - -On non-Windows platforms, it is not defined. - - - - On Windows, this macro defines an expression which evaluates to -%TRUE if the code is running on an NT-based Windows operating system. - -On non-Windows platforms, it is not defined. - - - + version="2.50" introspectable="0"> A wrapper for the POSIX abort() function. + filename="glib/gutils.c" + line="3332">A wrapper for the POSIX abort() function. On Windows it is a function that makes extra effort (including a call to abort()) to ensure that a debugger-catchable exception is thrown before the program terminates. See your C library manual for more details about abort(). - + A wrapper for the POSIX access() function. This function is used to + filename="glib/gstdio.c" + line="914">A wrapper for the POSIX access() function. This function is used to test a pathname for one or several of read, write or execute permissions, or just existence. @@ -55510,11 +60888,11 @@ Windows. Software that needs to handle file permissions on Windows more exactly should use the Win32 API. See your C library manual for more details about access(). - + zero if the pathname refers to an existing file system + filename="glib/gstdio.c" + line="933">zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error. @@ -55522,15 +60900,15 @@ See your C library manual for more details about access(). a pathname in the GLib file name encoding + filename="glib/gstdio.c" + line="916">a pathname in the GLib file name encoding (UTF-8 on Windows) as in access() + filename="glib/gstdio.c" + line="918">as in access() @@ -55539,8 +60917,8 @@ See your C library manual for more details about access(). c:identifier="g_aligned_alloc" version="2.72"> This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) + filename="glib/gmem.c" + line="598">This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to align the allocated memory to with the given alignment value. Additionally, it will detect possible overflow during multiplication. @@ -55550,30 +60928,30 @@ the program is terminated. Aligned memory allocations returned by this function can only be freed using g_aligned_free_sized() or g_aligned_free(). - + the allocated memory + filename="glib/gmem.c" + line="616">the allocated memory the number of blocks to allocate + filename="glib/gmem.c" + line="600">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="601">the size of each block in bytes the alignment to be enforced, which must be a positive power of 2 + filename="glib/gmem.c" + line="602">the alignment to be enforced, which must be a positive power of 2 and a multiple of `sizeof(void*)` @@ -55583,33 +60961,33 @@ freed using g_aligned_free_sized() or g_aligned_free(). c:identifier="g_aligned_alloc0" version="2.72"> This function is similar to g_aligned_alloc(), but it will + filename="glib/gmem.c" + line="698">This function is similar to g_aligned_alloc(), but it will also clear the allocated memory before returning it. - + the allocated, cleared memory + filename="glib/gmem.c" + line="708">the allocated, cleared memory the number of blocks to allocate + filename="glib/gmem.c" + line="700">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="701">the size of each block in bytes the alignment to be enforced, which must be a positive power of 2 + filename="glib/gmem.c" + line="702">the alignment to be enforced, which must be a positive power of 2 and a multiple of `sizeof(void*)` @@ -55617,9 +60995,9 @@ also clear the allocated memory before returning it. Frees the memory allocated by g_aligned_alloc(). - + filename="glib/gmem.c" + line="725">Frees the memory allocated by g_aligned_alloc(). + @@ -55629,8 +61007,8 @@ also clear the allocated memory before returning it. nullable="1" allow-none="1"> the memory to deallocate + filename="glib/gmem.c" + line="727">the memory to deallocate @@ -55639,8 +61017,8 @@ also clear the allocated memory before returning it. c:identifier="g_aligned_free_sized" version="2.76"> Frees the memory pointed to by @mem, assuming it is has the given @size and + filename="glib/gmem.c" + line="739">Frees the memory pointed to by @mem, assuming it is has the given @size and @alignment. If @mem is %NULL this is a no-op (and @size is ignored). @@ -55649,7 +61027,7 @@ It is an error if @size doesn’t match the size, or @alignment doesn’t match the alignment, passed when @mem was allocated. @size and @alignment are passed to this function to allow optimizations in the allocator. If you don’t know either of them, use g_aligned_free() instead. - + @@ -55659,27 +61037,27 @@ don’t know either of them, use g_aligned_free() instead. nullable="1" allow-none="1"> the memory to free + filename="glib/gmem.c" + line="741">the memory to free alignment of @mem + filename="glib/gmem.c" + line="742">alignment of @mem size of @mem, in bytes + filename="glib/gmem.c" + line="743">size of @mem, in bytes Allocates @size bytes on the stack; these bytes will be freed when the current stack frame is cleaned up. This macro essentially just wraps the alloca() function present on most UNIX variants. @@ -55709,11 +61087,11 @@ Thus it provides the same advantages and pitfalls as alloca(): Stack space allocated with alloca() in the same scope as a variable sized array will be freed together with the variable sized array upon exit of that scope, and not upon exit of the enclosing function scope. - + number of bytes to allocate. @@ -55723,162 +61101,42 @@ Thus it provides the same advantages and pitfalls as alloca(): version="2.72" introspectable="0"> Wraps g_alloca() and initializes allocated memory to zeroes. If @size is `0` it returns %NULL. Note that the @size argument will be evaluated multiple times. - + number of bytes to allocate. - - An "atomically reference counted box", or "ArcBox", is an opaque wrapper -data type that is guaranteed to be as big as the size of a given data type, -and which augments the given data type with thread safe reference counting -semantics for its memory management. - -ArcBox is useful if you have a plain old data type, like a structure -typically placed on the stack, and you wish to provide additional API -to use it on the heap; or if you want to implement a new type to be -passed around by reference without necessarily implementing copy/free -semantics or your own reference counting. - -The typical use is: - -|[<!-- language="C" --> -typedef struct { - char *name; - char *address; - char *city; - char *state; - int age; -} Person; - -Person * -person_new (void) -{ - return g_atomic_rc_box_new0 (Person); -} -]| - -Every time you wish to acquire a reference on the memory, you should -call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference -you should call g_atomic_rc_box_release(): - -|[<!-- language="C" --> -// Add a Person to the Database; the Database acquires ownership -// of the Person instance -void -add_person_to_database (Database *db, Person *p) -{ - db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p)); -} - -// Removes a Person from the Database; the reference acquired by -// add_person_to_database() is released here -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_atomic_rc_box_release (p); -} -]| - -If you have additional memory allocated inside the structure, you can -use g_atomic_rc_box_release_full(), which takes a function pointer, which -will be called if the reference released was the last: - -|[<!-- language="C" --> -void -person_clear (Person *p) -{ - g_free (p->name); - g_free (p->address); - g_free (p->city); - g_free (p->state); -} - -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear); -} -]| - -If you wish to transfer the ownership of a reference counted data -type without increasing the reference count, you can use g_steal_pointer(): - -|[<!-- language="C" --> - Person *p = g_atomic_rc_box_new (Person); - - fill_person_details (p); - - add_person_to_database (db, g_steal_pointer (&p)); -]| - -## Thread safety - -The reference counting operations on data allocated using g_atomic_rc_box_alloc(), -g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus -can be safely be performed by different threads. It is important to note that -only the reference acquisition and release are atomic; changes to the content -of the data are your responsibility. - -## Automatic pointer clean up - -If you want to add g_autoptr() support to your plain old data type through -reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and -g_atomic_rc_box_release(): - -|[<!-- language="C" --> -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release) -]| - -If you need to clear the contents of the data, you will need to use an -ancillary function that calls g_rc_box_release_full(): - -|[<!-- language="C" --> -static void -my_data_struct_release (MyDataStruct *data) -{ - // my_data_struct_clear() is defined elsewhere - g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); -} - -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) -]| - Adds the value on to the end of the array. The array will grow in + filename="glib/garray.c" + line="574">Adds the value on to the end of the array. The array will grow in size automatically if necessary. g_array_append_val() is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as "27". You must use variables. - + a #GArray + filename="glib/garray.c" + line="576">a #GArray the value to append to the #GArray + filename="glib/garray.c" + line="577">the value to append to the #GArray @@ -55886,8 +61144,8 @@ such as "27". You must use variables. c:identifier="g_array_index" introspectable="0"> Returns the element of a #GArray at the given index. The return + filename="glib/garray.c" + line="75">Returns the element of a #GArray at the given index. The return value is cast to the given type. This is the main way to read or write an element in a #GArray. @@ -55912,22 +61170,22 @@ This example reads from and writes to an array of integers: g_print ("Int at index 1 is %u; decrementing it\n", *my_int); *my_int = *my_int - 1; ]| - + a #GArray + filename="glib/garray.c" + line="77">a #GArray the type of the elements + filename="glib/garray.c" + line="78">the type of the elements the index of the element to return + filename="glib/garray.c" + line="79">the index of the element to return @@ -55935,28 +61193,28 @@ This example reads from and writes to an array of integers: c:identifier="g_array_insert_val" introspectable="0"> Inserts an element into an array at the given index. + filename="glib/garray.c" + line="696">Inserts an element into an array at the given index. g_array_insert_val() is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as "27". You must use variables. - + a #GArray + filename="glib/garray.c" + line="698">a #GArray the index to place the element at + filename="glib/garray.c" + line="699">the index to place the element at the value to insert into the array + filename="glib/garray.c" + line="700">the value to insert into the array @@ -55966,8 +61224,8 @@ such as "27". You must use variables. version="2.76" introspectable="0"> Creates a new #GArray with @data as array data, @len as length and a + filename="glib/garray.c" + line="147">Creates a new #GArray with @data as array data, @len as length and a reference count of 1. This avoids having to copy the data manually, when it can just be @@ -55983,11 +61241,11 @@ such task. Do not use it if @len or @element_size are greater than %G_MAXUINT. #GArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GArray + filename="glib/garray.c" + line="173">A new #GArray @@ -55998,8 +61256,8 @@ than #gsize. nullable="1" allow-none="1"> an array of + filename="glib/garray.c" + line="149">an array of elements of @element_size, or %NULL for an empty array @@ -56007,21 +61265,21 @@ than #gsize. the number of elements in @data + filename="glib/garray.c" + line="151">the number of elements in @data %TRUE if #GArray elements should be automatically cleared + filename="glib/garray.c" + line="152">%TRUE if #GArray elements should be automatically cleared to 0 when they are allocated the size of each element in bytes + filename="glib/garray.c" + line="154">the size of each element in bytes @@ -56032,8 +61290,8 @@ than #gsize. version="2.76" introspectable="0"> Creates a new #GArray with @data as array data, computing the length of it + filename="glib/garray.c" + line="199">Creates a new #GArray with @data as array data, computing the length of it and setting the reference count to 1. This avoids having to copy the data manually, when it can just be @@ -56052,11 +61310,11 @@ such task. Do not use it if @data length or @element_size are greater than %G_MAXUINT. #GArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GArray + filename="glib/garray.c" + line="226">A new #GArray @@ -56064,23 +61322,23 @@ than #gsize. an array of elements of @element_size + filename="glib/garray.c" + line="201">an array of elements of @element_size %TRUE if #GArray elements should be automatically cleared + filename="glib/garray.c" + line="202">%TRUE if #GArray elements should be automatically cleared to 0 when they are allocated the size of each element in bytes + filename="glib/garray.c" + line="204">the size of each element in bytes @@ -56089,8 +61347,8 @@ than #gsize. c:identifier="g_array_prepend_val" introspectable="0"> Adds the value on to the start of the array. The array will grow in + filename="glib/garray.c" + line="629">Adds the value on to the start of the array. The array will grow in size automatically if necessary. This operation is slower than g_array_append_val() since the @@ -56100,252 +61358,131 @@ the new element. g_array_prepend_val() is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as "27". You must use variables. - + a #GArray + filename="glib/garray.c" + line="631">a #GArray the value to prepend to the #GArray + filename="glib/garray.c" + line="632">the value to prepend to the #GArray - - Arrays are similar to standard C arrays, except that they grow -automatically as elements are added. - -Array elements can be of any size (though all elements of one array -are the same size), and the array can be automatically cleared to -'0's and zero-terminated. - -To create a new array use g_array_new(). - -To add elements to an array with a cost of O(n) at worst, use -g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), -g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals(). - -To access an element of an array in O(1) (to read it or to write it), -use g_array_index(). - -To set the size of an array, use g_array_set_size(). - -To free an array, use g_array_unref() or g_array_free(). - -All the sort functions are internally calling a quick-sort (or similar) -function with an average cost of O(n log(n)) and a worst case -cost of O(n^2). - -Here is an example that stores integers in a #GArray: -|[<!-- language="C" --> - GArray *garray; - gint i; - // We create a new array to store gint values. - // We don't want it zero-terminated or cleared to 0's. - garray = g_array_new (FALSE, FALSE, sizeof (gint)); - for (i = 0; i < 10000; i++) - g_array_append_val (garray, i); - for (i = 0; i < 10000; i++) - if (g_array_index (garray, gint, i) != i) - g_print ("ERROR: got %d instead of %d\n", - g_array_index (garray, gint, i), i); - g_array_free (garray, TRUE); -]| - - - #GByteArray is a mutable array of bytes based on #GArray, to provide arrays -of bytes which grow automatically as elements are added. - -To create a new #GByteArray use g_byte_array_new(). To add elements to a -#GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). - -To set the size of a #GByteArray, use g_byte_array_set_size(). - -To free a #GByteArray, use g_byte_array_free(). - -An example for using a #GByteArray: -|[<!-- language="C" --> - GByteArray *gbarray; - gint i; - - gbarray = g_byte_array_new (); - for (i = 0; i < 10000; i++) - g_byte_array_append (gbarray, (guint8*) "abcd", 4); - - for (i = 0; i < 10000; i++) - { - g_assert (gbarray->data[4*i] == 'a'); - g_assert (gbarray->data[4*i+1] == 'b'); - g_assert (gbarray->data[4*i+2] == 'c'); - g_assert (gbarray->data[4*i+3] == 'd'); - } - - g_byte_array_free (gbarray, TRUE); -]| - -See #GBytes if you are interested in an immutable object representing a -sequence of bytes. - - - Pointer Arrays are similar to Arrays but are used only for storing -pointers. - -If you remove elements from the array, elements at the end of the -array are moved into the space previously occupied by the removed -element. This means that you should not rely on the index of particular -elements remaining the same. You should also be careful when deleting -elements while iterating over the array. - -To create a pointer array, use g_ptr_array_new(). - -To add elements to a pointer array, use g_ptr_array_add(). - -To remove elements from a pointer array, use g_ptr_array_remove(), -g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). - -To access an element of a pointer array, use g_ptr_array_index(). - -To set the size of a pointer array, use g_ptr_array_set_size(). - -To free a pointer array, use g_ptr_array_free(). - -An example using a #GPtrArray: -|[<!-- language="C" --> - GPtrArray *array; - gchar *string1 = "one"; - gchar *string2 = "two"; - gchar *string3 = "three"; - - array = g_ptr_array_new (); - g_ptr_array_add (array, (gpointer) string1); - g_ptr_array_add (array, (gpointer) string2); - g_ptr_array_add (array, (gpointer) string3); - - if (g_ptr_array_index (array, 0) != (gpointer) string1) - g_print ("ERROR: got %p instead of %p\n", - g_ptr_array_index (array, 0), string1); - - g_ptr_array_free (array, TRUE); -]| - Determines the numeric value of a character as a decimal digit. -Differs from g_unichar_digit_value() because it takes a char, so + filename="glib/gstrfuncs.c" + line="1755">Determines the numeric value of a character as a decimal digit. If the +character is not a decimal digit according to [func@GLib.ascii_isdigit], +`-1` is returned. + +Differs from [func@GLib.unichar_digit_value] because it takes a char, so there's no worry about sign extension if characters are signed. - + If @c is a decimal digit (according to g_ascii_isdigit()), - its numeric value. Otherwise, -1. + filename="glib/gstrfuncs.c" + line="1766">the numerical value of @c if it is a decimal digit, `-1` otherwise an ASCII character + filename="glib/gstrfuncs.c" + line="1757">an ASCII character Converts a #gdouble to a string, using the '.' as + filename="glib/gstrfuncs.c" + line="858">Converts a `gdouble` to a string, using the '.' as decimal point. This function generates enough precision that converting -the string back using g_ascii_strtod() gives the same machine-number +the string back using [func@GLib.ascii_strtod] gives the same machine-number (on machines with IEEE compatible 64bit doubles). It is guaranteed that the size of the resulting string will never -be larger than %G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating +be larger than [const@GLib.ASCII_DTOSTR_BUF_SIZE] bytes, including the terminating nul character, which is always added. - + The pointer to the buffer with the converted string. + filename="glib/gstrfuncs.c" + line="874">the pointer to the buffer with the converted string A buffer to place the resulting string in + filename="glib/gstrfuncs.c" + line="860">a buffer to place the resulting string in The length of the buffer. + filename="glib/gstrfuncs.c" + line="861">the length of the buffer The #gdouble to convert + filename="glib/gstrfuncs.c" + line="862">the value to convert Converts a #gdouble to a string, using the '.' as + filename="glib/gstrfuncs.c" + line="887">Converts a `gdouble` to a string, using the '.' as decimal point. To format the number you pass in -a printf()-style format string. Allowed conversion +a `printf()`-style format string. Allowed conversion specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. The @format must just be a single format specifier -starting with `%`, expecting a #gdouble argument. +starting with `%`, expecting a `gdouble` argument. The returned buffer is guaranteed to be nul-terminated. If you just want to want to serialize the value into a -string, use g_ascii_dtostr(). - +string, use [func@GLib.ascii_dtostr]. + The pointer to the buffer with the converted string. + filename="glib/gstrfuncs.c" + line="908">the pointer to the buffer with the converted string A buffer to place the resulting string in + filename="glib/gstrfuncs.c" + line="889">a buffer to place the resulting string in The length of the buffer. + filename="glib/gstrfuncs.c" + line="890">the length of the buffer The printf()-style format to use for the + filename="glib/gstrfuncs.c" + line="891">the `printf()`-style format to use for the code to use for converting The #gdouble to convert + filename="glib/gstrfuncs.c" + line="893">the value to convert @@ -56354,21 +61491,21 @@ string, use g_ascii_dtostr(). c:identifier="g_ascii_isalnum" introspectable="0"> Determines whether a character is alphanumeric. + filename="glib/gstrfuncs.c" + line="60">Determines whether a character is alphanumeric. -Unlike the standard C library isalnum() function, this only +Unlike the standard C library `isalnum()` function, this only recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="62">any character @@ -56376,21 +61513,21 @@ passing a possibly non-ASCII character in. c:identifier="g_ascii_isalpha" introspectable="0"> Determines whether a character is alphabetic (i.e. a letter). + filename="glib/gstrfuncs.c" + line="76">Determines whether a character is alphabetic (i.e. a letter). -Unlike the standard C library isalpha() function, this only +Unlike the standard C library `isalpha()` function, this only recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="78">any character @@ -56398,21 +61535,21 @@ passing a possibly non-ASCII character in. c:identifier="g_ascii_iscntrl" introspectable="0"> Determines whether a character is a control character. + filename="glib/gstrfuncs.c" + line="92">Determines whether a character is a control character. -Unlike the standard C library iscntrl() function, this only +Unlike the standard C library `iscntrl()` function, this only recognizes standard ASCII control characters and ignores the -locale, returning %FALSE for all non-ASCII characters. Also, -unlike the standard library function, this takes a char, not -an int, so don't call it on %EOF, but no need to cast to #guchar +locale, returning false for all non-ASCII characters. Also, +unlike the standard library function, this takes a `char`, not +an `int`, so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="94">any character @@ -56420,18 +61557,18 @@ before passing a possibly non-ASCII character in. c:identifier="g_ascii_isdigit" introspectable="0"> Determines whether a character is digit (0-9). + filename="glib/gstrfuncs.c" + line="108">Determines whether a character is digit (0-9). -Unlike the standard C library isdigit() function, this takes -a char, not an int, so don't call it on %EOF, but no need to -cast to #guchar before passing a possibly non-ASCII character in. - +Unlike the standard C library `isdigit()` function, this takes +a `char`, not an `int`, so don't call it on `EOF`, but no need to +cast to `guchar` before passing a possibly non-ASCII character in. + any character + filename="glib/gstrfuncs.c" + line="110">any character @@ -56439,21 +61576,21 @@ cast to #guchar before passing a possibly non-ASCII character in. c:identifier="g_ascii_isgraph" introspectable="0"> Determines whether a character is a printing character and not a space. + filename="glib/gstrfuncs.c" + line="121">Determines whether a character is a printing character and not a space. -Unlike the standard C library isgraph() function, this only +Unlike the standard C library `isgraph()` function, this only recognizes standard ASCII characters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="123">any character @@ -56461,21 +61598,21 @@ passing a possibly non-ASCII character in. c:identifier="g_ascii_islower" introspectable="0"> Determines whether a character is an ASCII lower case letter. + filename="glib/gstrfuncs.c" + line="137">Determines whether a character is an ASCII lower case letter. -Unlike the standard C library islower() function, this only +Unlike the standard C library `islower()` function, this only recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to worry about casting -to #guchar before passing a possibly non-ASCII character in. - +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to worry about casting +to `guchar` before passing a possibly non-ASCII character in. + any character + filename="glib/gstrfuncs.c" + line="139">any character @@ -56483,21 +61620,21 @@ to #guchar before passing a possibly non-ASCII character in. c:identifier="g_ascii_isprint" introspectable="0"> Determines whether a character is a printing character. + filename="glib/gstrfuncs.c" + line="153">Determines whether a character is a printing character. -Unlike the standard C library isprint() function, this only +Unlike the standard C library `isprint()` function, this only recognizes standard ASCII characters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="155">any character @@ -56505,21 +61642,21 @@ passing a possibly non-ASCII character in. c:identifier="g_ascii_ispunct" introspectable="0"> Determines whether a character is a punctuation character. + filename="glib/gstrfuncs.c" + line="169">Determines whether a character is a punctuation character. -Unlike the standard C library ispunct() function, this only +Unlike the standard C library `ispunct()` function, this only recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="171">any character @@ -56527,21 +61664,21 @@ passing a possibly non-ASCII character in. c:identifier="g_ascii_isspace" introspectable="0"> Determines whether a character is a white-space character. + filename="glib/gstrfuncs.c" + line="185">Determines whether a character is a white-space character. -Unlike the standard C library isspace() function, this only +Unlike the standard C library `isspace()` function, this only recognizes standard ASCII white-space and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to cast to `guchar` before passing a possibly non-ASCII character in. - + any character + filename="glib/gstrfuncs.c" + line="187">any character @@ -56549,21 +61686,21 @@ passing a possibly non-ASCII character in. c:identifier="g_ascii_isupper" introspectable="0"> Determines whether a character is an ASCII upper case letter. + filename="glib/gstrfuncs.c" + line="201">Determines whether a character is an ASCII upper case letter. -Unlike the standard C library isupper() function, this only +Unlike the standard C library `isupper()` function, this only recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to worry about casting -to #guchar before passing a possibly non-ASCII character in. - +returning false for all non-ASCII characters. Also, unlike +the standard library function, this takes a `char`, not an `int`, +so don't call it on `EOF`, but no need to worry about casting +to `guchar` before passing a possibly non-ASCII character in. + any character + filename="glib/gstrfuncs.c" + line="203">any character @@ -56571,27 +61708,27 @@ to #guchar before passing a possibly non-ASCII character in. c:identifier="g_ascii_isxdigit" introspectable="0"> Determines whether a character is a hexadecimal-digit character. + filename="glib/gstrfuncs.c" + line="217">Determines whether a character is a hexadecimal-digit character. -Unlike the standard C library isxdigit() function, this takes -a char, not an int, so don't call it on %EOF, but no need to -cast to #guchar before passing a possibly non-ASCII character in. - +Unlike the standard C library `isxdigit()` function, this takes +a `char`, not an `int`, so don't call it on `EOF`, but no need to +cast to `guchar` before passing a possibly non-ASCII character in. + any character + filename="glib/gstrfuncs.c" + line="219">any character Compare two strings, ignoring the case of ASCII characters. + filename="glib/gstrfuncs.c" + line="1802">Compare two strings, ignoring the case of ASCII characters. -Unlike the BSD strcasecmp() function, this only recognizes standard +Unlike the BSD `strcasecmp()` function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII bytes as if they are not letters. @@ -56603,55 +61740,55 @@ Windows Codepage 932, where the trailing bytes of double-byte characters include all ASCII letters. If you compare two CP932 strings using this function, you will get false matches. -Both @s1 and @s2 must be non-%NULL. - +Both @s1 and @s2 must be non-`NULL`. + 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. + filename="glib/gstrfuncs.c" + line="1823">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2 string to compare with @s2 + filename="glib/gstrfuncs.c" + line="1804">string to compare with @s2 string to compare with @s1 + filename="glib/gstrfuncs.c" + line="1805">string to compare with @s1 Converts all upper case ASCII letters to lower case ASCII letters. - + filename="glib/gstrfuncs.c" + line="1545">Converts all upper case ASCII letters to lower case ASCII letters, with +semantics that exactly match [func@GLib.ascii_tolower]. + a newly-allocated string, with all the upper case - characters in @str converted to lower case, with semantics that - exactly match g_ascii_tolower(). (Note that this is unlike the - old g_strdown(), which modified the string in place.) + filename="glib/gstrfuncs.c" + line="1553">a newly-allocated string, with all the upper case characters in + @str converted to lower case. (Note that this is unlike the old + [func@GLib.strdown], which modified the string in place.) a string + filename="glib/gstrfuncs.c" + line="1547">a string length of @str in bytes, or -1 if @str is nul-terminated + filename="glib/gstrfuncs.c" + line="1548">length of @str in bytes, or `-1` if @str is nul-terminated @@ -56661,8 +61798,8 @@ Both @s1 and @s2 must be non-%NULL. version="2.54" throws="1"> A convenience function for converting a string to a signed number. + filename="glib/gstrfuncs.c" + line="3298">A convenience function for converting a string to a signed number. This function assumes that @str contains only a number of the given @base that is within inclusive bounds limited by @min and @max. If @@ -56675,44 +61812,44 @@ not be prefixed with "0x" or "0X". Such a problem does not exist for octal numbers, since they were usually prefixed with a zero which does not change the value of the parsed number. -Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR +Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` domain. If the input is invalid, the error code will be -%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of -bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. +[error@GLib.NumberParserError.INVALID]. If the parsed number is out of +bounds - [error@GLib.NumberParserError.OUT_OF_BOUNDS]. -See g_ascii_strtoll() if you have more complex needs such as +See [func@GLib.ascii_strtoll] if you have more complex needs such as parsing a string which starts with a number, but then has other characters. - + %TRUE if @str was a number, otherwise %FALSE. + filename="glib/gstrfuncs.c" + line="3329">true if @str was a number, false otherwise a string + filename="glib/gstrfuncs.c" + line="3300">a string to convert base of a parsed number + filename="glib/gstrfuncs.c" + line="3301">base of a parsed number a lower bound (inclusive) + filename="glib/gstrfuncs.c" + line="3302">a lower bound (inclusive) an upper bound (inclusive) + filename="glib/gstrfuncs.c" + line="3303">an upper bound (inclusive) optional="1" allow-none="1"> a return location for a number + filename="glib/gstrfuncs.c" + line="3304">a return location for a number @@ -56733,8 +61870,8 @@ characters. version="2.54" throws="1"> A convenience function for converting a string to an unsigned number. + filename="glib/gstrfuncs.c" + line="3399">A convenience function for converting a string to an unsigned number. This function assumes that @str contains only a number of the given @base that is within inclusive bounds limited by @min and @max. If @@ -56748,44 +61885,44 @@ not be prefixed with "0x" or "0X". Such a problem does not exist for octal numbers, since they were usually prefixed with a zero which does not change the value of the parsed number. -Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR +Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` domain. If the input is invalid, the error code will be -%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of -bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. +[error@GLib.NumberParserError.INVALID]. If the parsed number is out of +bounds - [error@GLib.NumberParserError.OUT_OF_BOUNDS]. -See g_ascii_strtoull() if you have more complex needs such as +See [func@GLib.ascii_strtoull] if you have more complex needs such as parsing a string which starts with a number, but then has other characters. - + %TRUE if @str was a number, otherwise %FALSE. + filename="glib/gstrfuncs.c" + line="3431">true if @str was a number, false otherwise a string + filename="glib/gstrfuncs.c" + line="3401">a string base of a parsed number + filename="glib/gstrfuncs.c" + line="3402">base of a parsed number a lower bound (inclusive) + filename="glib/gstrfuncs.c" + line="3403">a lower bound (inclusive) an upper bound (inclusive) + filename="glib/gstrfuncs.c" + line="3404">an upper bound (inclusive) optional="1" allow-none="1"> a return location for a number + filename="glib/gstrfuncs.c" + line="3405">a return location for a number Compare @s1 and @s2, ignoring the case of ASCII characters and any + filename="glib/gstrfuncs.c" + line="1847">Compare @s1 and @s2, ignoring the case of ASCII characters and any characters after the first @n in each string. If either string is less than @n bytes long, comparison will stop at the first nul byte encountered. -Unlike the BSD strcasecmp() function, this only recognizes standard +Unlike the BSD `strncasecmp()` function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII characters as if they are not letters. -The same warning as in g_ascii_strcasecmp() applies: Use this +The same warning as in [func@GLib.ascii_strcasecmp] applies: Use this function only on strings known to be in encodings where bytes corresponding to ASCII letters always represent themselves. - + 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. + filename="glib/gstrfuncs.c" + line="1866">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2 string to compare with @s2 + filename="glib/gstrfuncs.c" + line="1849">string to compare with @s2 string to compare with @s1 + filename="glib/gstrfuncs.c" + line="1850">string to compare with @s1 number of characters to compare + filename="glib/gstrfuncs.c" + line="1851">number of characters to compare Converts a string to a #gdouble value. + filename="glib/gstrfuncs.c" + line="655">Converts a string to a floating point value. -This function behaves like the standard strtod() function +This function behaves like the standard `strtod()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. A limitation of the implementation is that this function @@ -56859,30 +61996,30 @@ will still accept localized versions of infinities and NANs. This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the -locale-sensitive system strtod() function. +locale-sensitive system `strtod()` function. -To convert from a #gdouble to a string in a locale-insensitive -way, use g_ascii_dtostr(). +To convert from a gdouble to a string in a locale-insensitive +way, use [func@GLib.ascii_dtostr]. -If the correct value would cause overflow, plus or minus %HUGE_VAL -is returned (according to the sign of the value), and %ERANGE is -stored in %errno. If the correct value would cause underflow, -zero is returned and %ERANGE is stored in %errno. +If the correct value would cause overflow, plus or minus `HUGE_VAL` +is returned (according to the sign of the value), and `ERANGE` is +stored in `errno`. If the correct value would cause underflow, +zero is returned and `ERANGE` is stored in `errno`. -This function resets %errno before calling strtod() so that +This function resets `errno` before calling `strtod()` so that you can reliably detect overflow and underflow. - + the #gdouble value. + filename="glib/gstrfuncs.c" + line="685">the converted value the string to convert to a numeric value. + filename="glib/gstrfuncs.c" + line="657">the string to convert to a numeric value optional="1" allow-none="1"> if non-%NULL, it returns the - character after the last character used in the conversion. + filename="glib/gstrfuncs.c" + line="658">if non-`NULL`, it returns the + character after the last character used in the conversion @@ -56903,9 +62040,10 @@ you can reliably detect overflow and underflow. c:identifier="g_ascii_strtoll" version="2.12"> Converts a string to a #gint64 value. -This function behaves like the standard strtoll() function + filename="glib/gstrfuncs.c" + line="1196">Converts a string to a `gint64` value. + +This function behaves like the standard `strtoll()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. @@ -56913,26 +62051,26 @@ thread-safe. This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the -locale-sensitive system strtoll() function. +locale-sensitive system `strtoll()` function. -If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 -is returned, and `ERANGE` is stored in `errno`. +If the correct value would cause overflow, [const@GLib.MAXINT64] or +[const@GLib.MININT64] is returned, and `ERANGE` is stored in `errno`. If the base is outside the valid range, zero is returned, and `EINVAL` is stored in `errno`. If the string conversion fails, zero is returned, and @endptr returns @nptr -(if @endptr is non-%NULL). - +(if @endptr is non-`NULL`). + the #gint64 value or zero on error. + filename="glib/gstrfuncs.c" + line="1222">the converted value, or zero on error the string to convert to a numeric value. + filename="glib/gstrfuncs.c" + line="1198">the string to convert to a numeric value if non-%NULL, it returns the - character after the last character used in the conversion. + filename="glib/gstrfuncs.c" + line="1199">if non-`NULL`, it returns the + character after the last character used in the conversion to be used for the conversion, 2..36 or 0 + filename="glib/gstrfuncs.c" + line="1201">to be used for the conversion, 2..36 or 0 @@ -56959,41 +62097,42 @@ string conversion fails, zero is returned, and @endptr returns @nptr c:identifier="g_ascii_strtoull" version="2.2"> Converts a string to a #guint64 value. -This function behaves like the standard strtoull() function + filename="glib/gstrfuncs.c" + line="1140">Converts a string to a `guint64` value. + +This function behaves like the standard `strtoull()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. Note that input with a leading minus sign (`-`) is accepted, and will return -the negation of the parsed number, unless that would overflow a #guint64. +the negation of the parsed number, unless that would overflow a `guint64`. Critically, this means you cannot assume that a short fixed length input will -never result in a low return value, as the input could have a leading `-`. +result in a low return value, as the input could have a leading `-`. This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the -locale-sensitive system strtoull() function. +locale-sensitive system `strtoull()` function. -If the correct value would cause overflow, %G_MAXUINT64 +If the correct value would cause overflow, [const@GLib.MAXUINT64] is returned, and `ERANGE` is stored in `errno`. If the base is outside the valid range, zero is returned, and `EINVAL` is stored in `errno`. If the string conversion fails, zero is returned, and @endptr returns -@nptr (if @endptr is non-%NULL). - +@nptr (if @endptr is non-`NULL`). + the #guint64 value or zero on error. + filename="glib/gstrfuncs.c" + line="1171">the converted value, or zero on error the string to convert to a numeric value. + filename="glib/gstrfuncs.c" + line="1142">the string to convert to a numeric value if non-%NULL, it returns the - character after the last character used in the conversion. + filename="glib/gstrfuncs.c" + line="1143">if non-`NULL`, it returns the + character after the last character used in the conversion to be used for the conversion, 2..36 or 0 + filename="glib/gstrfuncs.c" + line="1145">to be used for the conversion, 2..36 or 0 Converts all lower case ASCII letters to upper case ASCII letters. - + filename="glib/gstrfuncs.c" + line="1576">Converts all lower case ASCII letters to upper case ASCII letters, with +semantics that exactly match [func@GLib.ascii_toupper]. + a newly allocated string, with all the lower case - characters in @str converted to upper case, with semantics that - exactly match g_ascii_toupper(). (Note that this is unlike the - old g_strup(), which modified the string in place.) + filename="glib/gstrfuncs.c" + line="1584">a newly-allocated string, with all the lower case characters + in @str converted to upper case. (Note that this is unlike the old + [func@GLib.strup], which modified the string in place.) a string + filename="glib/gstrfuncs.c" + line="1578">a string length of @str in bytes, or -1 if @str is nul-terminated + filename="glib/gstrfuncs.c" + line="1579">length of @str in bytes, or `-1` if @str is nul-terminated Convert a character to ASCII lower case. + filename="glib/gstrfuncs.c" + line="1709">Convert a character to ASCII lower case. If the character is not an +ASCII upper case letter, it is returned unchanged. -Unlike the standard C library tolower() function, this only +Unlike the standard C library `tolower()` function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are lower case letters in a particular character set. Also unlike the standard library function, this takes and returns a char, not an int, so -don't call it on %EOF but no need to worry about casting to #guchar +don't call it on `EOF` but no need to worry about casting to `guchar` before passing a possibly non-ASCII character in. - + the result of converting @c to lower case. If @c is - not an ASCII upper case letter, @c is returned unchanged. + filename="glib/gstrfuncs.c" + line="1724">the result of the conversion any character + filename="glib/gstrfuncs.c" + line="1711">any character Convert a character to ASCII upper case. + filename="glib/gstrfuncs.c" + line="1732">Convert a character to ASCII upper case. If the character is not an +ASCII lower case letter, it is returned unchanged. -Unlike the standard C library toupper() function, this only +Unlike the standard C library `toupper()` function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are upper case letters in a particular character set. Also unlike the standard library function, this takes and returns a char, not an int, so -don't call it on %EOF but no need to worry about casting to #guchar +don't call it on `EOF` but no need to worry about casting to `guchar` before passing a possibly non-ASCII character in. - + the result of converting @c to upper case. If @c is not - an ASCII lower case letter, @c is returned unchanged. + filename="glib/gstrfuncs.c" + line="1747">the result of the conversion any character + filename="glib/gstrfuncs.c" + line="1734">any character Determines the numeric value of a character as a hexadecimal -digit. Differs from g_unichar_xdigit_value() because it takes -a char, so there's no worry about sign extension if characters -are signed. - + filename="glib/gstrfuncs.c" + line="1776">Determines the numeric value of a character as a hexadecimal digit. If the +character is not a hex digit according to [func@GLib.ascii_isxdigit], +`-1` is returned. + +Differs from [func@GLib.unichar_xdigit_value] because it takes a char, so +there's no worry about sign extension if characters are signed. + +Differs from [func@GLib.unichar_xdigit_value] because it takes a char, so +there's no worry about sign extension if characters are signed. + If @c is a hex digit (according to g_ascii_isxdigit()), - its numeric value. Otherwise, -1. + filename="glib/gstrfuncs.c" + line="1790">the numerical value of @c if it is a hex digit, `-1` otherwise an ASCII character. + filename="glib/gstrfuncs.c" + line="1778">an ASCII character Debugging macro to terminate the application if the assertion -fails. If the assertion fails (i.e. the expression is not true), + filename="glib/gtestutils.c" + line="307">Debugging macro to terminate the application if the assertion +fails. + +If the assertion fails (i.e. the expression is not true), an error message is logged and the application is terminated. The macro can be turned off in final releases of code by defining -`G_DISABLE_ASSERT` when compiling the application, so code must -not depend on any side effects from @expr. Similarly, it must not be used -in unit tests, otherwise the unit tests will be ineffective if compiled with -`G_DISABLE_ASSERT`. Use g_assert_true() and related macros in unit tests -instead. - +`G_DISABLE_ASSERT` when compiling the application, so code must not +depend on any side effects from @expr. Similarly, it must not be used +in unit tests, otherwise the unit tests will be ineffective if compiled +with `G_DISABLE_ASSERT`. Use [func@GLib.assert_true] and related macros +in unit tests instead. + the expression to check + filename="glib/gtestutils.c" + line="309">the expression to check @@ -57154,30 +62299,30 @@ instead. version="2.16" introspectable="0"> Debugging macro to compare two floating point numbers. + filename="glib/gtestutils.c" + line="515">Debugging macro to compare two floating point numbers. -The effect of `g_assert_cmpfloat (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - +The effect of `g_assert_cmpfloat (n1, op, n2)` is the same as +`g_assert_true (n1 op n2)`. The advantage of this macro is +that it can produce a message that includes the actual values +of @n1 and @n2. + a floating point number + filename="glib/gtestutils.c" + line="517">a floating point number The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + filename="glib/gtestutils.c" + line="518">the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another floating point number + filename="glib/gtestutils.c" + line="520">another floating point number @@ -57186,29 +62331,29 @@ actual values of @n1 and @n2. version="2.58" introspectable="0"> Debugging macro to compare two floating point numbers within an epsilon. + filename="glib/gtestutils.c" + line="532">Debugging macro to compare two floating point numbers within an epsilon. The effect of `g_assert_cmpfloat_with_epsilon (n1, n2, epsilon)` is the same as `g_assert_true (abs (n1 - n2) < epsilon)`. The advantage of this macro is that it can produce a message that includes the actual values of @n1 and @n2. - + a floating point number + filename="glib/gtestutils.c" + line="534">a floating point number another floating point number + filename="glib/gtestutils.c" + line="535">another floating point number a numeric value that expresses the expected tolerance + filename="glib/gtestutils.c" + line="536">a numeric value that expresses the expected tolerance between @n1 and @n2 @@ -57218,28 +62363,28 @@ actual values of @n1 and @n2. version="2.16" introspectable="0"> Debugging macro to compare to unsigned integers. + filename="glib/gtestutils.c" + line="500">Debugging macro to compare to unsigned integers. -This is a variant of g_assert_cmpuint() that displays the numbers -in hexadecimal notation in the message. - +This is a variant of [func@GLib.assert_cmpuint] that displays +the numbers in hexadecimal notation in the message. + an unsigned integer + filename="glib/gtestutils.c" + line="502">an unsigned integer The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + filename="glib/gtestutils.c" + line="503">the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another unsigned integer + filename="glib/gtestutils.c" + line="505">another unsigned integer @@ -57248,30 +62393,30 @@ in hexadecimal notation in the message. version="2.16" introspectable="0"> Debugging macro to compare two integers. + filename="glib/gtestutils.c" + line="466">Debugging macro to compare two integers. -The effect of `g_assert_cmpint (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - +The effect of `g_assert_cmpint (n1, op, n2)` is the same as +`g_assert_true (n1 op n2)`. The advantage of this macro is +that it can produce a message that includes the actual values +of @n1 and @n2. + an integer + filename="glib/gtestutils.c" + line="468">an integer The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + filename="glib/gtestutils.c" + line="469">the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another integer + filename="glib/gtestutils.c" + line="471">another integer @@ -57280,42 +62425,43 @@ actual values of @n1 and @n2. version="2.46" introspectable="0"> Debugging macro to compare memory regions. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. + filename="glib/gtestutils.c" + line="567">Debugging macro to compare memory regions. -The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is -the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. -The advantage of this macro is that it can produce a message that -includes the actual values of @l1 and @l2. +If the comparison fails, an error message is logged and the +application is either terminated or the testcase marked as failed. -@m1 may be %NULL if (and only if) @l1 is zero; similarly for @m2 and @l2. +The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is the same as +`g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. The advantage +of this macro is that it can produce a message that includes the actual +values of @l1 and @l2. -|[<!-- language="C" --> +@m1 may be `NULL` if (and only if) @l1 is zero; similarly for @m2 and @l2. + +```c g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); -]| - +``` + pointer to a buffer + filename="glib/gtestutils.c" + line="569">pointer to a buffer length of @m1 + filename="glib/gtestutils.c" + line="570">length of @m1 in bytes pointer to another buffer + filename="glib/gtestutils.c" + line="571">pointer to another buffer length of @m2 + filename="glib/gtestutils.c" + line="572">length of @m2 in bytes @@ -57324,37 +62470,38 @@ includes the actual values of @l1 and @l2. version="2.16" introspectable="0"> Debugging macro to compare two strings. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. -The strings are compared using g_strcmp0(). + filename="glib/gtestutils.c" + line="415">Debugging macro to compare two strings. -The effect of `g_assert_cmpstr (s1, op, s2)` is -the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. -The advantage of this macro is that it can produce a message that -includes the actual values of @s1 and @s2. +If the comparison fails, an error message is logged and the +application is either terminated or the testcase marked as failed. +The strings are compared using [GLib.strcmp0]. -|[<!-- language="C" --> +The effect of `g_assert_cmpstr (s1, op, s2)` is the same as +`g_assert_true (g_strcmp0 (s1, s2) op 0)`. The advantage of this +macro is that it can produce a message that includes the actual +values of @s1 and @s2. + +```c g_assert_cmpstr (mystring, ==, "fubar"); -]| - +``` + a string (may be %NULL) + filename="glib/gtestutils.c" + line="417">a string The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + filename="glib/gtestutils.c" + line="418">the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another string (may be %NULL) + filename="glib/gtestutils.c" + line="420">another string @@ -57363,33 +62510,35 @@ includes the actual values of @s1 and @s2. version="2.68" introspectable="0"> Debugging macro to check if two %NULL-terminated string arrays (i.e. 2 -#GStrv) are equal. If they are not equal, an error message is logged and the -application is either terminated or the testcase marked as failed. -If both arrays are %NULL, the check passes. If one array is %NULL but the -other is not, an error message is logged. + filename="glib/gtestutils.c" + line="440">Debugging macro to check if two `NULL`-terminated string arrays (i.e. 2 +`GStrv`) are equal. + +If they are not equal, an error message is logged and the application is +either terminated or the testcase marked as failed. If both arrays are +`NULL`, the check passes. If one array is `NULL` but the other is not, +an error message is logged. The effect of `g_assert_cmpstrv (strv1, strv2)` is the same as `g_assert_true (g_strv_equal (strv1, strv2))` (if both arrays are not -%NULL). The advantage of this macro is that it can produce a message that +`NULL`). The advantage of this macro is that it can produce a message that includes how @strv1 and @strv2 are different. -|[<!-- language="C" --> +```c const char *expected[] = { "one", "two", "three", NULL }; g_assert_cmpstrv (mystrv, expected); -]| - +``` + a string array (may be %NULL) + filename="glib/gtestutils.c" + line="442">a string array another string array (may be %NULL) + filename="glib/gtestutils.c" + line="443">another string array @@ -57398,30 +62547,30 @@ includes how @strv1 and @strv2 are different. version="2.16" introspectable="0"> Debugging macro to compare two unsigned integers. + filename="glib/gtestutils.c" + line="483">Debugging macro to compare two unsigned integers. -The effect of `g_assert_cmpuint (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - +The effect of `g_assert_cmpuint (n1, op, n2)` is the same as +`g_assert_true (n1 op n2)`. The advantage of this macro is +that it can produce a message that includes the actual values +of @n1 and @n2. + an unsigned integer + filename="glib/gtestutils.c" + line="485">an unsigned integer The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + filename="glib/gtestutils.c" + line="486">the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another unsigned integer + filename="glib/gtestutils.c" + line="488">another unsigned integer @@ -57430,26 +62579,28 @@ actual values of @n1 and @n2. version="2.60" introspectable="0"> Debugging macro to compare two #GVariants. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. The variants are compared using -g_variant_equal(). + filename="glib/gtestutils.c" + line="593">Debugging macro to compare two [struct@GLib.Variant] values. + +If the comparison fails, an error message is logged and the +application is either terminated or the testcase marked as failed. +The variants are compared using [method@GLib.Variant.equal]. The effect of `g_assert_cmpvariant (v1, v2)` is the same as -`g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is -that it can produce a message that includes the actual values of @v1 and @v2. - +`g_assert_true (g_variant_equal (v1, v2))`. The advantage of +this macro is that it can produce a message that includes the +actual values of @v1 and @v2. + pointer to a #GVariant + filename="glib/gtestutils.c" + line="595">pointer to a `GVariant` pointer to another #GVariant + filename="glib/gtestutils.c" + line="596">pointer to another `GVariant` @@ -57458,35 +62609,34 @@ that it can produce a message that includes the actual values of @v1 and @v2. Debugging macro to check that a method has returned -the correct #GError. + filename="glib/gtestutils.c" + line="626">Debugging macro to check that a method has returned +the correct [struct@GLib.Error]. -The effect of `g_assert_error (err, dom, c)` is -the same as `g_assert_true (err != NULL && err->domain -== dom && err->code == c)`. The advantage of this -macro is that it can produce a message that includes the incorrect -error message and code. +The effect of `g_assert_error (err, dom, c)` is the same as +`g_assert_true (err != NULL && err->domain == dom && err->code == c)`. +The advantage of this macro is that it can produce a message that +includes the incorrect error message and code. This can only be used to test for a specific error. If you want to test that @err is set, but don't care what it's set to, just use `g_assert_nonnull (err)`. - + a #GError, possibly %NULL + filename="glib/gtestutils.c" + line="628">a `GError` the expected error domain (a #GQuark) + filename="glib/gtestutils.c" + line="629">the expected error domain (a `GQuark`) the expected error code + filename="glib/gtestutils.c" + line="630">the expected error code @@ -57495,24 +62645,24 @@ test that @err is set, but don't care what it's set to, just use version="2.38" introspectable="0"> Debugging macro to check an expression is false. + filename="glib/gtestutils.c" + line="358">Debugging macro to check an expression is false. If the assertion fails (i.e. the expression is not false), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether +Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +conversely, [func@GLib.assert] should not be used in tests. -See g_test_set_nonfatal_assertions(). - +See [func@GLib.test_set_nonfatal_assertions]. + the expression to check + filename="glib/gtestutils.c" + line="360">the expression to check @@ -57521,23 +62671,23 @@ See g_test_set_nonfatal_assertions(). version="2.66" introspectable="0"> Debugging macro to check that an expression has a non-negative return value, + filename="glib/gtestutils.c" + line="549">Debugging macro to check that an expression has a non-negative return value, as used by traditional POSIX functions (such as `rmdir()`) to indicate success. If the assertion fails (i.e. the @expr returns a negative value), an error message is logged and the testcase is marked as failed. The error message will contain the value of `errno` and its human-readable message from -g_strerror(). +[func@GLib.strerror]. This macro will clear the value of `errno` before executing @expr. - + the expression to check + filename="glib/gtestutils.c" + line="551">the expression to check @@ -57546,19 +62696,19 @@ This macro will clear the value of `errno` before executing @expr. version="2.20" introspectable="0"> Debugging macro to check that a #GError is not set. + filename="glib/gtestutils.c" + line="612">Debugging macro to check that a [struct@GLib.Error] is not set. -The effect of `g_assert_no_error (err)` is -the same as `g_assert_true (err == NULL)`. The advantage -of this macro is that it can produce a message that includes -the error message and code. - +The effect of `g_assert_no_error (err)` is the same as +`g_assert_true (err == NULL)`. The advantage of this macro +is that it can produce a message that includes the error +message and code. + a #GError, possibly %NULL + filename="glib/gtestutils.c" + line="614">a `GError` @@ -57567,24 +62717,24 @@ the error message and code. version="2.40" introspectable="0"> Debugging macro to check an expression is not %NULL. + filename="glib/gtestutils.c" + line="396">Debugging macro to check an expression is not `NULL`. -If the assertion fails (i.e. the expression is %NULL), +If the assertion fails (i.e. the expression is `NULL`), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether +Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +conversely, [func@GLib.assert] should not be used in tests. -See g_test_set_nonfatal_assertions(). - +See [func@GLib.test_set_nonfatal_assertions]. + the expression to check + filename="glib/gtestutils.c" + line="398">the expression to check @@ -57592,39 +62742,40 @@ See g_test_set_nonfatal_assertions(). c:identifier="g_assert_not_reached" introspectable="0"> Debugging macro to terminate the application if it is ever -reached. If it is reached, an error message is logged and the -application is terminated. + filename="glib/gtestutils.c" + line="325">Debugging macro to terminate the application if it is ever reached. + +If it is reached, an error message is logged and the application +is terminated. The macro can be turned off in final releases of code by defining -`G_DISABLE_ASSERT` when compiling the application. Hence, it should not be -used in unit tests, where assertions should always be effective. - +`G_DISABLE_ASSERT` when compiling the application. Hence, it should +not be used in unit tests, where assertions should always be effective. + Debugging macro to check an expression is %NULL. + filename="glib/gtestutils.c" + line="377">Debugging macro to check an expression is `NULL`. -If the assertion fails (i.e. the expression is not %NULL), +If the assertion fails (i.e. the expression is not `NULL`), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether +Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +conversely, [func@GLib.assert] should not be used in tests. -See g_test_set_nonfatal_assertions(). - +See [func@GLib.test_set_nonfatal_assertions]. + the expression to check + filename="glib/gtestutils.c" + line="379">the expression to check @@ -57633,29 +62784,30 @@ See g_test_set_nonfatal_assertions(). version="2.38" introspectable="0"> Debugging macro to check that an expression is true. + filename="glib/gtestutils.c" + line="338">Debugging macro to check that an expression is true. If the assertion fails (i.e. the expression is not true), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether -`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +Note that unlike [func@GLib.assert], this macro is unaffected by +whether `G_DISABLE_ASSERT` is defined. Hence it should only be used +in tests and, conversely, [func@GLib.assert] should not be used +in tests. -See g_test_set_nonfatal_assertions(). - +See [func@GLib.test_set_nonfatal_assertions]. + the expression to check + filename="glib/gtestutils.c" + line="340">the expression to check - + @@ -57678,7 +62830,7 @@ See g_test_set_nonfatal_assertions(). - + @@ -57702,7 +62854,7 @@ See g_test_set_nonfatal_assertions(). - + @@ -57739,7 +62891,7 @@ See g_test_set_nonfatal_assertions(). - + @@ -57775,7 +62927,7 @@ See g_test_set_nonfatal_assertions(). - + @@ -57808,7 +62960,7 @@ See g_test_set_nonfatal_assertions(). - + @@ -57841,7 +62993,7 @@ See g_test_set_nonfatal_assertions(). - + @@ -57876,10 +63028,10 @@ See g_test_set_nonfatal_assertions(). c:identifier="g_assertion_message_expr" introspectable="0"> Internal function used to print messages from the public g_assert() and -g_assert_not_reached() macros. - + filename="glib/gtestutils.c" + line="3462">Internal function used to print messages from the public +g_assert() and g_assert_not_reached() macros. + @@ -57889,26 +63041,26 @@ g_assert_not_reached() macros. nullable="1" allow-none="1"> log domain + filename="glib/gtestutils.c" + line="3464">log domain file containing the assertion + filename="glib/gtestutils.c" + line="3465">file containing the assertion line number of the assertion + filename="glib/gtestutils.c" + line="3466">line number of the assertion function containing the assertion + filename="glib/gtestutils.c" + line="3467">function containing the assertion nullable="1" allow-none="1"> expression which failed + filename="glib/gtestutils.c" + line="3468">expression which failed - + Often you need to communicate between different threads. In general -it's safer not to do this by shared memory, but by explicit message -passing. These messages only make sense asynchronously for -multi-threaded applications though, as a synchronous operation could -as well be done in the same thread. - -Asynchronous queues are an exception from most other GLib data -structures, as they can be used simultaneously from multiple threads -without explicit locking and they bring their own builtin reference -counting. This is because the nature of an asynchronous queue is that -it will always be used by at least 2 concurrent threads. - -For using an asynchronous queue you first have to create one with -g_async_queue_new(). #GAsyncQueue structs are reference counted, -use g_async_queue_ref() and g_async_queue_unref() to manage your -references. - -A thread which wants to send a message to that queue simply calls -g_async_queue_push() to push the message to the queue. - -A thread which is expecting messages from an asynchronous queue -simply calls g_async_queue_pop() for that queue. If no message is -available in the queue at that point, the thread is now put to sleep -until a message arrives. The message will be removed from the queue -and returned. The functions g_async_queue_try_pop() and -g_async_queue_timeout_pop() can be used to only check for the presence -of messages or to only wait a certain time for messages respectively. - -For almost every function there exist two variants, one that locks -the queue and one that doesn't. That way you can hold the queue lock -(acquire it with g_async_queue_lock() and release it with -g_async_queue_unlock()) over multiple queue accessing instructions. -This can be necessary to ensure the integrity of the queue, but should -only be used when really necessary, as it can make your life harder -if used unwisely. Normally you should only use the locking function -variants (those without the _unlocked suffix). - -In many cases, it may be more convenient to use #GThreadPool when -you need to distribute work to a set of worker threads instead of -using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue -internally. - + filename="glib/gasyncqueue.c" + line="63">Creates a new asynchronous queue. + + + a new #GAsyncQueue. Free with g_async_queue_unref() + + + + + Creates a new asynchronous queue and sets up a destroy notify +function that is used to free any remaining queue items when +the queue is destroyed after the final unref. + + + a new #GAsyncQueue. Free with g_async_queue_unref() + + + + + function to free queue elements + + + + Specifies a function to be called at normal program termination. + filename="glib/gutils.c" + line="117">Specifies a function to be called at normal program termination. Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor macro that maps to a call to the atexit() function in the C @@ -58004,15 +63154,15 @@ As can be seen from the above, for portability it's best to avoid calling g_atexit() (or atexit()) except in the main executable of a program. It is best to avoid g_atexit(). - + the function to call on normal program termination. + filename="glib/gutils.c" + line="119">the function to call on normal program termination. @@ -58021,8 +63171,8 @@ program. c:identifier="g_atomic_int_add" version="2.4"> Atomically adds @val to the value of @atomic. + filename="glib/gatomic.c" + line="236">Atomically adds @val to the value of @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic += val; return tmp; }`. @@ -58034,24 +63184,24 @@ Before version 2.30, this function did not return a value While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + the value of @atomic before the add, signed + filename="glib/gatomic.c" + line="254">the value of @atomic before the add, signed a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="238">a pointer to a #gint or #guint the value to add + filename="glib/gatomic.c" + line="239">the value to add @@ -58060,8 +63210,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_and" version="2.30"> Performs an atomic bitwise 'and' of the value of @atomic and @val, + filename="glib/gatomic.c" + line="265">Performs an atomic bitwise 'and' of the value of @atomic and @val, storing the result back in @atomic. This call acts as a full compiler and hardware memory barrier. @@ -58071,24 +63221,24 @@ Think of this operation as an atomic version of While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + the value of @atomic before the operation, unsigned + filename="glib/gatomic.c" + line="281">the value of @atomic before the operation, unsigned a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="267">a pointer to a #gint or #guint the value to 'and' + filename="glib/gatomic.c" + line="268">the value to 'and' @@ -58097,8 +63247,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_compare_and_exchange" version="2.4"> Compares @atomic to @oldval and, if equal, sets it to @newval. + filename="glib/gatomic.c" + line="147">Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. This compare and exchange is done atomically. @@ -58110,30 +63260,30 @@ This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + %TRUE if the exchange took place + filename="glib/gatomic.c" + line="166">%TRUE if the exchange took place a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="149">a pointer to a #gint or #guint the value to compare with + filename="glib/gatomic.c" + line="150">the value to compare with the value to conditionally replace with + filename="glib/gatomic.c" + line="151">the value to conditionally replace with @@ -58142,8 +63292,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_compare_and_exchange_full" version="2.74"> Compares @atomic to @oldval and, if equal, sets it to @newval. + filename="glib/gatomic.c" + line="178">Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. In any case the value of @atomic before this operation is stored in @preval. @@ -58155,30 +63305,30 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. See also g_atomic_int_compare_and_exchange() - + %TRUE if the exchange took place + filename="glib/gatomic.c" + line="198">%TRUE if the exchange took place a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="180">a pointer to a #gint or #guint the value to compare with + filename="glib/gatomic.c" + line="181">the value to compare with the value to conditionally replace with + filename="glib/gatomic.c" + line="182">the value to conditionally replace with caller-allocates="0" transfer-ownership="full"> the contents of @atomic before this operation + filename="glib/gatomic.c" + line="183">the contents of @atomic before this operation @@ -58196,8 +63346,8 @@ See also g_atomic_int_compare_and_exchange() c:identifier="g_atomic_int_dec_and_test" version="2.4"> Decrements the value of @atomic by 1. + filename="glib/gatomic.c" + line="123">Decrements the value of @atomic by 1. Think of this operation as an atomic version of `{ *atomic -= 1; return (*atomic == 0); }`. @@ -58206,18 +63356,18 @@ This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + %TRUE if the resultant value is zero + filename="glib/gatomic.c" + line="137">%TRUE if the resultant value is zero a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="125">a pointer to a #gint or #guint @@ -58226,8 +63376,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_exchange" version="2.74"> Sets the @atomic to @newval and returns the old value from @atomic. + filename="glib/gatomic.c" + line="211">Sets the @atomic to @newval and returns the old value from @atomic. This exchange is done atomically. @@ -58235,24 +63385,24 @@ Think of this operation as an atomic version of `{ tmp = *atomic; *atomic = val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. - + the value of @atomic before the exchange, signed + filename="glib/gatomic.c" + line="225">the value of @atomic before the exchange, signed a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="213">a pointer to a #gint or #guint the value to replace with + filename="glib/gatomic.c" + line="214">the value to replace with @@ -58263,29 +63413,29 @@ This call acts as a full compiler and hardware memory barrier. deprecated="1" deprecated-version="2.30"> This function existed before g_atomic_int_add() returned the prior + filename="glib/gatomic.c" + line="1150">This function existed before g_atomic_int_add() returned the prior value of the integer (which it now does). It is retained only for compatibility reasons. Don't use this function in new code. Use g_atomic_int_add() instead. - + the value of @atomic before the add, signed + filename="glib/gatomic.c" + line="1159">the value of @atomic before the add, signed a pointer to a #gint + filename="glib/gatomic.c" + line="1152">a pointer to a #gint the value to add + filename="glib/gatomic.c" + line="1153">the value to add @@ -58294,26 +63444,26 @@ compatibility reasons. Don't use this function in new code. c:identifier="g_atomic_int_get" version="2.4"> Gets the current value of @atomic. + filename="glib/gatomic.c" + line="58">Gets the current value of @atomic. This call acts as a full compiler and hardware memory barrier (before the get). While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + the value of the integer + filename="glib/gatomic.c" + line="70">the value of the integer a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="60">a pointer to a #gint or #guint @@ -58322,8 +63472,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_inc" version="2.4"> Increments the value of @atomic by 1. + filename="glib/gatomic.c" + line="102">Increments the value of @atomic by 1. Think of this operation as an atomic version of `{ *atomic += 1; }`. @@ -58331,15 +63481,15 @@ This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="104">a pointer to a #gint or #guint @@ -58348,8 +63498,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_or" version="2.30"> Performs an atomic bitwise 'or' of the value of @atomic and @val, + filename="glib/gatomic.c" + line="292">Performs an atomic bitwise 'or' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of @@ -58359,24 +63509,24 @@ This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + the value of @atomic before the operation, unsigned + filename="glib/gatomic.c" + line="308">the value of @atomic before the operation, unsigned a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="294">a pointer to a #gint or #guint the value to 'or' + filename="glib/gatomic.c" + line="295">the value to 'or' @@ -58385,29 +63535,29 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_set" version="2.4"> Sets the value of @atomic to @newval. + filename="glib/gatomic.c" + line="80">Sets the value of @atomic to @newval. This call acts as a full compiler and hardware memory barrier (after the set). While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="82">a pointer to a #gint or #guint a new value to store + filename="glib/gatomic.c" + line="83">a new value to store @@ -58416,8 +63566,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_int_xor" version="2.30"> Performs an atomic bitwise 'xor' of the value of @atomic and @val, + filename="glib/gatomic.c" + line="319">Performs an atomic bitwise 'xor' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of @@ -58427,73 +63577,34 @@ This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + the value of @atomic before the operation, unsigned + filename="glib/gatomic.c" + line="335">the value of @atomic before the operation, unsigned a pointer to a #gint or #guint + filename="glib/gatomic.c" + line="321">a pointer to a #gint or #guint the value to 'xor' + filename="glib/gatomic.c" + line="322">the value to 'xor' - - The following is a collection of compiler macros to provide atomic -access to integer and pointer-sized values. - -The macros that have 'int' in the name will operate on pointers to -#gint and #guint. The macros with 'pointer' in the name will operate -on pointers to any pointer-sized value, including #gsize. There is -no support for 64bit operations on platforms with 32bit pointers -because it is not generally possible to perform these operations -atomically. - -The get, set and exchange operations for integers and pointers -nominally operate on #gint and #gpointer, respectively. Of the -arithmetic operations, the 'add' operation operates on (and returns) -signed integer values (#gint and #gssize) and the 'and', 'or', and -'xor' operations operate on (and return) unsigned integer values -(#guint and #gsize). - -All of the operations act as a full compiler and (where appropriate) -hardware memory barrier. Acquire and release or producer and -consumer barrier semantics are not available through this API. - -It is very important that all accesses to a particular integer or -pointer be performed using only this API and that different sizes of -operation are not mixed or used on overlapping memory regions. Never -read or assign directly from or to a value -- always use this API. - -For simple reference counting purposes you should use -g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that -fall outside of simple reference counting patterns are prone to -subtle bugs and occasionally undefined behaviour. It is also worth -noting that since all of these operations require global -synchronisation of the entire machine, they can be quite slow. In -the case of performing multiple atomic operations it can often be -faster to simply acquire a mutex lock around the critical area, -perform the operations normally and then release the lock. - Atomically adds @val to the value of @atomic. + filename="glib/gatomic.c" + line="483">Atomically adds @val to the value of @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic += val; return tmp; }`. @@ -58501,25 +63612,29 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. - +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gssize to #gintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. + the value of @atomic before the add, signed - + filename="glib/gatomic.c" + line="502">the value of @atomic before the add, signed + a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="485">a pointer to a #gpointer-sized value the value to add + filename="glib/gatomic.c" + line="486">the value to add @@ -58528,8 +63643,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_pointer_and" version="2.30"> Performs an atomic bitwise 'and' of the value of @atomic and @val, + filename="glib/gatomic.c" + line="513">Performs an atomic bitwise 'and' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of @@ -58538,25 +63653,29 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. - +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gsize to #guintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. + the value of @atomic before the operation, unsigned - + filename="glib/gatomic.c" + line="533">the value of @atomic before the operation, unsigned + a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="515">a pointer to a #gpointer-sized value the value to 'and' + filename="glib/gatomic.c" + line="516">the value to 'and' @@ -58565,8 +63684,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_pointer_compare_and_exchange" version="2.4"> Compares @atomic to @oldval and, if equal, sets it to @newval. + filename="glib/gatomic.c" + line="391">Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. This compare and exchange is done atomically. @@ -58578,18 +63697,18 @@ This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + %TRUE if the exchange took place + filename="glib/gatomic.c" + line="410">%TRUE if the exchange took place a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="393">a pointer to a #gpointer-sized value nullable="1" allow-none="1"> the value to compare with + filename="glib/gatomic.c" + line="394">the value to compare with nullable="1" allow-none="1"> the value to conditionally replace with + filename="glib/gatomic.c" + line="395">the value to conditionally replace with @@ -58616,8 +63735,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_pointer_compare_and_exchange_full" version="2.74"> Compares @atomic to @oldval and, if equal, sets it to @newval. + filename="glib/gatomic.c" + line="423">Compares @atomic to @oldval and, if equal, sets it to @newval. If @atomic was not equal to @oldval then no change occurs. In any case the value of @atomic before this operation is stored in @preval. @@ -58629,18 +63748,18 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. See also g_atomic_pointer_compare_and_exchange() - + %TRUE if the exchange took place + filename="glib/gatomic.c" + line="443">%TRUE if the exchange took place a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="425">a pointer to a #gpointer-sized value nullable="1" allow-none="1"> the value to compare with + filename="glib/gatomic.c" + line="426">the value to compare with nullable="1" allow-none="1"> the value to conditionally replace with + filename="glib/gatomic.c" + line="427">the value to conditionally replace with caller-allocates="0" transfer-ownership="full"> the contents of @atomic before this operation + filename="glib/gatomic.c" + line="428">the contents of @atomic before this operation @@ -58676,8 +63795,8 @@ See also g_atomic_pointer_compare_and_exchange() c:identifier="g_atomic_pointer_exchange" version="2.74"> Sets the @atomic to @newval and returns the old value from @atomic. + filename="glib/gatomic.c" + line="458">Sets the @atomic to @newval and returns the old value from @atomic. This exchange is done atomically. @@ -58685,11 +63804,11 @@ Think of this operation as an atomic version of `{ tmp = *atomic; *atomic = val; return tmp; }`. This call acts as a full compiler and hardware memory barrier. - + the value of @atomic before the exchange + filename="glib/gatomic.c" + line="472">the value of @atomic before the exchange @@ -58698,8 +63817,8 @@ This call acts as a full compiler and hardware memory barrier. nullable="1" allow-none="1"> a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="460">a pointer to a #gpointer-sized value nullable="1" allow-none="1"> the value to replace with + filename="glib/gatomic.c" + line="461">the value to replace with @@ -58717,26 +63836,26 @@ This call acts as a full compiler and hardware memory barrier. c:identifier="g_atomic_pointer_get" version="2.4"> Gets the current value of @atomic. + filename="glib/gatomic.c" + line="347">Gets the current value of @atomic. This call acts as a full compiler and hardware memory barrier (before the get). While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + the value of the pointer + filename="glib/gatomic.c" + line="359">the value of the pointer a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="349">a pointer to a #gpointer-sized value @@ -58745,8 +63864,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_pointer_or" version="2.30"> Performs an atomic bitwise 'or' of the value of @atomic and @val, + filename="glib/gatomic.c" + line="544">Performs an atomic bitwise 'or' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of @@ -58755,25 +63874,29 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. - +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gsize to #guintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. + the value of @atomic before the operation, unsigned - + filename="glib/gatomic.c" + line="564">the value of @atomic before the operation, unsigned + a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="546">a pointer to a #gpointer-sized value the value to 'or' + filename="glib/gatomic.c" + line="547">the value to 'or' @@ -58782,23 +63905,23 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_pointer_set" version="2.4"> Sets the value of @atomic to @newval. + filename="glib/gatomic.c" + line="369">Sets the value of @atomic to @newval. This call acts as a full compiler and hardware memory barrier (after the set). While @atomic has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="371">a pointer to a #gpointer-sized value nullable="1" allow-none="1"> a new value to store + filename="glib/gatomic.c" + line="372">a new value to store @@ -58816,8 +63939,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_pointer_xor" version="2.30"> Performs an atomic bitwise 'xor' of the value of @atomic and @val, + filename="glib/gatomic.c" + line="575">Performs an atomic bitwise 'xor' of the value of @atomic and @val, storing the result back in @atomic. Think of this operation as an atomic version of @@ -58826,25 +63949,29 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. - +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gsize to #guintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. + the value of @atomic before the operation, unsigned - + filename="glib/gatomic.c" + line="595">the value of @atomic before the operation, unsigned + a pointer to a #gpointer-sized value + filename="glib/gatomic.c" + line="577">a pointer to a #gpointer-sized value the value to 'xor' + filename="glib/gatomic.c" + line="578">the value to 'xor' @@ -58853,21 +63980,21 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_rc_box_acquire" version="2.58"> Atomically acquires a reference on the data pointed by @mem_block. - + filename="glib/garcbox.c" + line="154">Atomically acquires a reference on the data pointed by @mem_block. + a pointer to the data, + filename="glib/garcbox.c" + line="160">a pointer to the data, with its reference count increased a pointer to reference counted data + filename="glib/garcbox.c" + line="156">a pointer to reference counted data @@ -58876,8 +64003,8 @@ the pointer passed to it should not be `volatile`. c:identifier="g_atomic_rc_box_alloc" version="2.58"> Allocates @block_size bytes of memory, and adds atomic + filename="glib/garcbox.c" + line="38">Allocates @block_size bytes of memory, and adds atomic reference counting semantics to it. The data will be freed when its reference count drops to @@ -58885,18 +64012,18 @@ zero. The allocated data is guaranteed to be suitably aligned for any built-in type. - + a pointer to the allocated memory + filename="glib/garcbox.c" + line="51">a pointer to the allocated memory the size of the allocation, must be greater than 0 + filename="glib/garcbox.c" + line="40">the size of the allocation, must be greater than 0 @@ -58905,8 +64032,8 @@ built-in type. c:identifier="g_atomic_rc_box_alloc0" version="2.58"> Allocates @block_size bytes of memory, and adds atomic + filename="glib/garcbox.c" + line="63">Allocates @block_size bytes of memory, and adds atomic reference counting semantics to it. The contents of the returned data is set to zero. @@ -58916,18 +64043,18 @@ zero. The allocated data is guaranteed to be suitably aligned for any built-in type. - + a pointer to the allocated memory + filename="glib/garcbox.c" + line="78">a pointer to the allocated memory the size of the allocation, must be greater than 0 + filename="glib/garcbox.c" + line="65">the size of the allocation, must be greater than 0 @@ -58936,29 +64063,29 @@ built-in type. c:identifier="g_atomic_rc_box_dup" version="2.58"> Allocates a new block of data with atomic reference counting + filename="glib/garcbox.c" + line="125">Allocates a new block of data with atomic reference counting semantics, and copies @block_size bytes of @mem_block into it. - + a pointer to the allocated + filename="glib/garcbox.c" + line="134">a pointer to the allocated memory the number of bytes to copy, must be greater than 0 + filename="glib/garcbox.c" + line="127">the number of bytes to copy, must be greater than 0 the memory to copy + filename="glib/garcbox.c" + line="128">the memory to copy @@ -58967,20 +64094,20 @@ into it. c:identifier="g_atomic_rc_box_get_size" version="2.58"> Retrieves the size of the reference counted data pointed by @mem_block. - + filename="glib/garcbox.c" + line="242">Retrieves the size of the reference counted data pointed by @mem_block. + the size of the data, in bytes + filename="glib/garcbox.c" + line="248">the size of the data, in bytes a pointer to reference counted data + filename="glib/garcbox.c" + line="244">a pointer to reference counted data @@ -58990,19 +64117,19 @@ into it. version="2.58" introspectable="0"> A convenience macro to allocate atomically reference counted + filename="glib/garcbox.c" + line="90">A convenience macro to allocate atomically reference counted data with the size of the given @type. This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. - + the type to allocate, typically a structure name + filename="glib/garcbox.c" + line="92">the type to allocate, typically a structure name @@ -59011,20 +64138,20 @@ avoiding a type cast in the source code. version="2.58" introspectable="0"> A convenience macro to allocate atomically reference counted + filename="glib/garcbox.c" + line="107">A convenience macro to allocate atomically reference counted data with the size of the given @type, and set its contents to zero. This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. - + the type to allocate, typically a structure name + filename="glib/garcbox.c" + line="109">the type to allocate, typically a structure name @@ -59032,20 +64159,20 @@ avoiding a type cast in the source code. c:identifier="g_atomic_rc_box_release" version="2.58"> Atomically releases a reference on the data pointed by @mem_block. + filename="glib/garcbox.c" + line="182">Atomically releases a reference on the data pointed by @mem_block. If the reference was the last one, it will free the resources allocated for @mem_block. - + a pointer to reference counted data + filename="glib/garcbox.c" + line="184">a pointer to reference counted data @@ -59054,27 +64181,32 @@ resources allocated for @mem_block. c:identifier="g_atomic_rc_box_release_full" version="2.58"> Atomically releases a reference on the data pointed by @mem_block. + filename="glib/garcbox.c" + line="199">Atomically releases a reference on the data pointed by @mem_block. If the reference was the last one, it will call @clear_func to clear the contents of @mem_block, and then will free the -resources allocated for @mem_block. - +resources allocated for @mem_block. + +Note that implementing weak references via @clear_func is not thread-safe: +clearing a pointer to the memory from the callback can race with another +thread trying to access it as @mem_block already has a reference count of 0 +when the callback is called and will be freed. + a pointer to reference counted data + filename="glib/garcbox.c" + line="201">a pointer to reference counted data a function to call when clearing the data + filename="glib/garcbox.c" + line="202">a function to call when clearing the data @@ -59083,27 +64215,27 @@ resources allocated for @mem_block. c:identifier="g_atomic_ref_count_compare" version="2.58"> Atomically compares the current value of @arc with @val. - + filename="glib/grefcount.c" + line="253">Atomically compares the current value of @arc with @val. + %TRUE if the reference count is the same + filename="glib/grefcount.c" + line="260">%TRUE if the reference count is the same as the given value the address of an atomic reference count variable + filename="glib/grefcount.c" + line="255">the address of an atomic reference count variable the value to compare + filename="glib/grefcount.c" + line="256">the value to compare @@ -59112,24 +64244,24 @@ resources allocated for @mem_block. c:identifier="g_atomic_ref_count_dec" version="2.58"> Atomically decreases the reference count. + filename="glib/grefcount.c" + line="227">Atomically decreases the reference count. If %TRUE is returned, the reference count reached 0. After this point, @arc is an undefined state and must be reinitialized with g_atomic_ref_count_init() to be used again. - + %TRUE if the reference count reached 0, and %FALSE otherwise + filename="glib/grefcount.c" + line="237">%TRUE if the reference count reached 0, and %FALSE otherwise the address of an atomic reference count variable + filename="glib/grefcount.c" + line="229">the address of an atomic reference count variable @@ -59138,17 +64270,17 @@ g_atomic_ref_count_init() to be used again. c:identifier="g_atomic_ref_count_inc" version="2.58"> Atomically increases the reference count. - + filename="glib/grefcount.c" + line="206">Atomically increases the reference count. + the address of an atomic reference count variable + filename="glib/grefcount.c" + line="208">the address of an atomic reference count variable @@ -59157,54 +64289,34 @@ g_atomic_ref_count_init() to be used again. c:identifier="g_atomic_ref_count_init" version="2.58"> Initializes a reference count variable to 1. - + filename="glib/grefcount.c" + line="181">Initializes a reference count variable to 1. + the address of an atomic reference count variable + filename="glib/grefcount.c" + line="183">the address of an atomic reference count variable - - Base64 is an encoding that allows a sequence of arbitrary bytes to be -encoded as a sequence of printable ASCII characters. For the definition -of Base64, see -[RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) -or -[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). -Base64 is most commonly used as a MIME transfer encoding -for email. - -GLib supports incremental encoding using g_base64_encode_step() and -g_base64_encode_close(). Incremental decoding can be done with -g_base64_decode_step(). To encode or decode data in one go, use -g_base64_encode() or g_base64_decode(). To avoid memory allocation when -decoding, you can use g_base64_decode_inplace(). - -Support for Base64 encoding has been added in GLib 2.12. - Decode a sequence of Base-64 encoded text into binary data. Note + filename="glib/gbase64.c" + line="370">Decode a sequence of Base-64 encoded text into binary data. Note that the returned binary data is not necessarily zero-terminated, so it should not be used as a character string. - + + filename="glib/gbase64.c" + line="379"> newly allocated buffer containing the binary data that @text represents. The returned buffer must be freed with g_free(). @@ -59215,8 +64327,8 @@ so it should not be used as a character string. zero-terminated string with base64 text to decode + filename="glib/gbase64.c" + line="372">zero-terminated string with base64 text to decode caller-allocates="0" transfer-ownership="full"> The length of the decoded data is written here + filename="glib/gbase64.c" + line="373">The length of the decoded data is written here @@ -59234,14 +64346,14 @@ so it should not be used as a character string. c:identifier="g_base64_decode_inplace" version="2.20"> Decode a sequence of Base-64 encoded text into binary data + filename="glib/gbase64.c" + line="409">Decode a sequence of Base-64 encoded text into binary data by overwriting the input data. - + The binary data that @text responds. This pointer + filename="glib/gbase64.c" + line="418">The binary data that @text responds. This pointer is the same as the input @text. @@ -59251,8 +64363,8 @@ by overwriting the input data. caller-allocates="0" transfer-ownership="full"> zero-terminated + filename="glib/gbase64.c" + line="411">zero-terminated string with base64 text to decode @@ -59263,8 +64375,8 @@ by overwriting the input data. caller-allocates="0" transfer-ownership="none"> The length of the decoded data is written here + filename="glib/gbase64.c" + line="413">The length of the decoded data is written here @@ -59274,8 +64386,8 @@ by overwriting the input data. version="2.12" introspectable="0"> Incrementally decode a sequence of binary data from its Base-64 stringified + filename="glib/gbase64.c" + line="280">Incrementally decode a sequence of binary data from its Base-64 stringified representation. By calling this function multiple times you can convert data in chunks to avoid having to have the full encoded data in memory. @@ -59283,26 +64395,26 @@ The output buffer must be large enough to fit all the data that will be written to it. Since base64 encodes 3 bytes in 4 chars you need at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero state). - + The number of bytes of output that was written + filename="glib/gbase64.c" + line="297">The number of bytes of output that was written binary input data + filename="glib/gbase64.c" + line="282">binary input data max length of @in data to decode + filename="glib/gbase64.c" + line="283">max length of @in data to decode caller-allocates="1" transfer-ownership="none"> output buffer + filename="glib/gbase64.c" + line="284">output buffer @@ -59321,8 +64433,8 @@ state). caller-allocates="0" transfer-ownership="full"> Saved state between steps, initialize to 0 + filename="glib/gbase64.c" + line="285">Saved state between steps, initialize to 0 caller-allocates="0" transfer-ownership="full"> Saved state between steps, initialize to 0 + filename="glib/gbase64.c" + line="286">Saved state between steps, initialize to 0 @@ -59340,14 +64452,14 @@ state). c:identifier="g_base64_encode" version="2.12"> Encode a sequence of binary data into its Base-64 stringified + filename="glib/gbase64.c" + line="224">Encode a sequence of binary data into its Base-64 stringified representation. - + a newly allocated, zero-terminated Base-64 + filename="glib/gbase64.c" + line="232">a newly allocated, zero-terminated Base-64 encoded string representing @data. The returned string must be freed with g_free(). @@ -59358,16 +64470,16 @@ representation. nullable="1" allow-none="1"> the binary data to encode + filename="glib/gbase64.c" + line="226">the binary data to encode the length of @data + filename="glib/gbase64.c" + line="227">the length of @data @@ -59376,26 +64488,26 @@ representation. c:identifier="g_base64_encode_close" version="2.12"> Flush the status from a sequence of calls to g_base64_encode_step(). + filename="glib/gbase64.c" + line="164">Flush the status from a sequence of calls to g_base64_encode_step(). The output buffer must be large enough to fit all the data that will be written to it. It will need up to 4 bytes, or up to 5 bytes if line-breaking is enabled. The @out array will not be automatically nul-terminated. - + The number of bytes of output that was written + filename="glib/gbase64.c" + line="179">The number of bytes of output that was written whether to break long lines + filename="glib/gbase64.c" + line="166">whether to break long lines caller-allocates="0" transfer-ownership="full"> pointer to destination buffer + filename="glib/gbase64.c" + line="167">pointer to destination buffer @@ -59414,8 +64526,8 @@ The @out array will not be automatically nul-terminated. caller-allocates="0" transfer-ownership="full"> Saved state from g_base64_encode_step() + filename="glib/gbase64.c" + line="168">Saved state from g_base64_encode_step() caller-allocates="0" transfer-ownership="full"> Saved state from g_base64_encode_step() + filename="glib/gbase64.c" + line="169">Saved state from g_base64_encode_step() @@ -59433,8 +64545,8 @@ The @out array will not be automatically nul-terminated. c:identifier="g_base64_encode_step" version="2.12"> Incrementally encode a sequence of binary data into its Base-64 stringified + filename="glib/gbase64.c" + line="37">Incrementally encode a sequence of binary data into its Base-64 stringified representation. By calling this function multiple times you can convert data in chunks to avoid having to have the full encoded data in memory. @@ -59453,32 +64565,32 @@ the same line. This avoids problems with long lines in the email system. Note however that it breaks the lines with `LF` characters, not `CR LF` sequences, so the result cannot be passed directly to SMTP or certain other protocols. - + The number of bytes of output that was written + filename="glib/gbase64.c" + line="66">The number of bytes of output that was written the binary data to encode + filename="glib/gbase64.c" + line="39">the binary data to encode the length of @in + filename="glib/gbase64.c" + line="40">the length of @in whether to break long lines + filename="glib/gbase64.c" + line="41">whether to break long lines caller-allocates="0" transfer-ownership="full"> pointer to destination buffer + filename="glib/gbase64.c" + line="42">pointer to destination buffer @@ -59497,8 +64609,8 @@ or certain other protocols. caller-allocates="0" transfer-ownership="full"> Saved state between steps, initialize to 0 + filename="glib/gbase64.c" + line="43">Saved state between steps, initialize to 0 caller-allocates="0" transfer-ownership="full"> Saved state between steps, initialize to 0 + filename="glib/gbase64.c" + line="44">Saved state between steps, initialize to 0 @@ -59517,35 +64629,35 @@ or certain other protocols. deprecated="1" deprecated-version="2.2"> Gets the name of the file without any leading directory + filename="glib/gfileutils.c" + line="2535">Gets the name of the file without any leading directory components. It returns a pointer into the given file name string. Use g_path_get_basename() instead, but notice that g_path_get_basename() allocates new memory for the returned string, unlike this function which returns a pointer into the argument. - + the name of the file without any leading + filename="glib/gfileutils.c" + line="2543">the name of the file without any leading directory components the name of the file + filename="glib/gfileutils.c" + line="2537">the name of the file Sets the indicated @lock_bit in @address. If the bit is already + filename="glib/gbitlock.c" + line="189">Sets the indicated @lock_bit in @address. If the bit is already set, this call will block until g_bit_unlock() unsets the corresponding bit. @@ -59559,111 +64671,111 @@ This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work reliably. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + a pointer to an integer + filename="glib/gbitlock.c" + line="191">a pointer to an integer a bit value between 0 and 31 + filename="glib/gbitlock.c" + line="192">a bit value between 0 and 31 Find the position of the first bit set in @mask, searching + filename="glib/gutils.c" + line="525">Find the position of the first bit set in @mask, searching from (but not including) @nth_bit upwards. Bits are numbered from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the 0th bit, set @nth_bit to -1. - + the index of the first bit set which is higher than @nth_bit, or -1 + filename="glib/gutils.c" + line="535">the index of the first bit set which is higher than @nth_bit, or -1 if no higher bits are set a #gulong containing flags + filename="glib/gutils.c" + line="527">a #gulong containing flags the index of the bit to start the search from + filename="glib/gutils.c" + line="528">the index of the bit to start the search from Find the position of the first bit set in @mask, searching + filename="glib/gutils.c" + line="545">Find the position of the first bit set in @mask, searching from (but not including) @nth_bit downwards. Bits are numbered from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8. - + the index of the first bit set which is lower than @nth_bit, or -1 + filename="glib/gutils.c" + line="556">the index of the first bit set which is lower than @nth_bit, or -1 if no lower bits are set a #gulong containing flags + filename="glib/gutils.c" + line="547">a #gulong containing flags the index of the bit to start the search from + filename="glib/gutils.c" + line="548">the index of the bit to start the search from Gets the number of bits used to hold @number, + filename="glib/gutils.c" + line="567">Gets the number of bits used to hold @number, e.g. if @number is 4, 3 bits are needed. - + the number of bits used to hold @number + filename="glib/gutils.c" + line="574">the number of bits used to hold @number a #guint + filename="glib/gutils.c" + line="569">a #guint Sets the indicated @lock_bit in @address, returning %TRUE if + filename="glib/gbitlock.c" + line="263">Sets the indicated @lock_bit in @address, returning %TRUE if successful. If the bit is already set, returns %FALSE immediately. Attempting to lock on two different bits within the same integer is @@ -59676,32 +64788,32 @@ This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work reliably. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + %TRUE if the lock was acquired + filename="glib/gbitlock.c" + line="282">%TRUE if the lock was acquired a pointer to an integer + filename="glib/gbitlock.c" + line="265">a pointer to an integer a bit value between 0 and 31 + filename="glib/gbitlock.c" + line="266">a bit value between 0 and 31 Clears the indicated @lock_bit in @address. If another thread is + filename="glib/gbitlock.c" + line="312">Clears the indicated @lock_bit in @address. If another thread is currently blocked in g_bit_lock() on this same bit then it will be woken up. @@ -59709,25 +64821,31 @@ This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work reliably. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + a pointer to an integer + filename="glib/gbitlock.c" + line="314">a pointer to an integer a bit value between 0 and 31 + filename="glib/gbitlock.c" + line="315">a bit value between 0 and 31 + + + + + + @@ -59739,8 +64857,8 @@ artifact and the argument passed to it should not be `volatile`. c:identifier="g_build_filename" introspectable="0"> Creates a filename from a series of elements using the correct + filename="glib/gfileutils.c" + line="2267">Creates a filename from a series of elements using the correct separator for the current platform. On Unix, this function behaves identically to `g_build_path @@ -59758,24 +64876,24 @@ be a relative path. If you are building a path programmatically you may want to use #GPathBuf instead. - + the newly allocated path + filename="glib/gfileutils.c" + line="2291">the newly allocated path the first element in the path + filename="glib/gfileutils.c" + line="2269">the first element in the path remaining elements in path, terminated by %NULL + filename="glib/gfileutils.c" + line="2270">remaining elements in path, terminated by %NULL @@ -59785,8 +64903,8 @@ If you are building a path programmatically you may want to use version="2.56" introspectable="0"> Creates a filename from a list of elements using the correct + filename="glib/gfileutils.c" + line="2215">Creates a filename from a list of elements using the correct separator for the current platform. Behaves exactly like g_build_filename(), but takes the path elements @@ -59794,24 +64912,24 @@ as a va_list. This function is mainly meant for implementing other variadic arguments functions. - + the newly allocated path + filename="glib/gfileutils.c" + line="2229">the newly allocated path the first element in the path + filename="glib/gfileutils.c" + line="2217">the first element in the path va_list of remaining elements in path + filename="glib/gfileutils.c" + line="2218">va_list of remaining elements in path @@ -59820,8 +64938,8 @@ functions. c:identifier="g_build_filenamev" version="2.8"> Creates a filename from a vector of elements using the correct + filename="glib/gfileutils.c" + line="2242">Creates a filename from a vector of elements using the correct separator for the current platform. This function behaves exactly like g_build_filename(), but takes the path @@ -59830,18 +64948,18 @@ meant for language bindings. If you are building a path programmatically you may want to use #GPathBuf instead. - + the newly allocated path + filename="glib/gfileutils.c" + line="2257">the newly allocated path %NULL-terminated + filename="glib/gfileutils.c" + line="2244">%NULL-terminated array of strings containing the path elements. @@ -59851,8 +64969,8 @@ If you are building a path programmatically you may want to use Creates a path from a series of elements using @separator as the + filename="glib/gfileutils.c" + line="2029">Creates a path from a series of elements using @separator as the separator between elements. At the boundary between two elements, any trailing occurrences of @@ -59880,60 +64998,60 @@ of that element. Other than for determination of the number of leading and trailing copies of the separator, elements consisting only of copies of the separator are ignored. - + the newly allocated path + filename="glib/gfileutils.c" + line="2064">the newly allocated path a string used to separator the elements of the path. + filename="glib/gfileutils.c" + line="2031">a string used to separator the elements of the path. the first element in the path + filename="glib/gfileutils.c" + line="2032">the first element in the path remaining elements in path, terminated by %NULL + filename="glib/gfileutils.c" + line="2033">remaining elements in path, terminated by %NULL Behaves exactly like g_build_path(), but takes the path elements + filename="glib/gfileutils.c" + line="2002">Behaves exactly like g_build_path(), but takes the path elements as a string array, instead of variadic arguments. This function is mainly meant for language bindings. - + a newly-allocated string that + filename="glib/gfileutils.c" + line="2013">a newly-allocated string that must be freed with g_free(). a string used to separator the elements of the path. + filename="glib/gfileutils.c" + line="2004">a string used to separator the elements of the path. %NULL-terminated + filename="glib/gfileutils.c" + line="2005">%NULL-terminated array of strings containing the path elements. @@ -59941,36 +65059,75 @@ This function is mainly meant for language bindings. + + Adds the given bytes to the end of the #GByteArray. +The array will grow in size automatically if necessary. + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the byte data to be added + + + + the number of bytes to add + + + + Frees the memory allocated by the #GByteArray. If @free_segment is + filename="glib/garray.c" + line="2775">Frees the memory allocated by the #GByteArray. If @free_segment is %TRUE it frees the actual byte data. If the reference count of @array is greater than one, the #GByteArray wrapper is preserved but the size of @array will be set to zero. - + the element data if @free_segment is %FALSE, otherwise + filename="glib/garray.c" + line="2785">the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free(). a #GByteArray + filename="glib/garray.c" + line="2777">a #GByteArray if %TRUE the actual byte data is freed as well + filename="glib/garray.c" + line="2778">if %TRUE the actual byte data is freed as well @@ -59980,8 +65137,8 @@ the size of @array will be set to zero. moved-to="ByteArray.free_to_bytes" version="2.32"> Transfers the data from the #GByteArray into a new immutable #GBytes. + filename="glib/garray.c" + line="2795">Transfers the data from the #GByteArray into a new immutable #GBytes. The #GByteArray is freed unless the reference count of @array is greater than one, the #GByteArray wrapper is preserved but the size of @array @@ -59989,19 +65146,19 @@ will be set to zero. This is identical to using g_bytes_new_take() and g_byte_array_free() together. - + a new immutable #GBytes representing same + filename="glib/garray.c" + line="2810">a new immutable #GBytes representing same byte data that was in the array a #GByteArray + filename="glib/garray.c" + line="2797">a #GByteArray @@ -60012,13 +65169,13 @@ together. c:identifier="g_byte_array_new" moved-to="ByteArray.new"> Creates a new #GByteArray with a reference count of 1. - + filename="glib/garray.c" + line="2685">Creates a new #GByteArray with a reference count of 1. + the new #GByteArray + filename="glib/garray.c" + line="2690">the new #GByteArray @@ -60029,8 +65186,8 @@ together. moved-to="ByteArray.new_take" version="2.32"> Creates a byte array containing the @data. + filename="glib/garray.c" + line="2720">Creates a byte array containing the @data. After this call, @data belongs to the #GByteArray and may no longer be modified by the caller. The memory of @data has to be dynamically allocated and will eventually be freed with g_free(). @@ -60038,11 +65195,11 @@ allocated and will eventually be freed with g_free(). Do not use it if @len is greater than %G_MAXUINT. #GByteArray stores the length of its data in #guint, which may be shorter than #gsize. - + a new #GByteArray + filename="glib/garray.c" + line="2736">a new #GByteArray @@ -60050,42 +65207,352 @@ stores the length of its data in #guint, which may be shorter than byte data for the array + filename="glib/garray.c" + line="2722">byte data for the array length of @data + filename="glib/garray.c" + line="2723">length of @data + + Adds the given data to the start of the #GByteArray. +The array will grow in size automatically if necessary. + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the byte data to be added + + + + the number of bytes to add + + + + + + Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread. + + + The passed in #GByteArray + + + + + + + A #GByteArray + + + + + + + + Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place. + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the index of the byte to remove + + + + + + Removes the byte at the given index from a #GByteArray. The last +element in the array is used to fill in the space, so this function +does not preserve the order of the #GByteArray. But it is faster +than g_byte_array_remove_index(). + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the index of the byte to remove + + + + + + Removes the given number of bytes starting at the given index from a +#GByteArray. The following elements are moved to close the gap. + + + the #GByteArray + + + + + + + a @GByteArray + + + + + + the index of the first byte to remove + + + + the number of bytes to remove + + + + + + Sets the size of the #GByteArray, expanding it if necessary. + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the new size of the #GByteArray + + + + + + Creates a new #GByteArray with @reserved_size bytes preallocated. +This avoids frequent reallocation, if you are going to add many +bytes to the array. Note however that the size of the array is still +0. + + + the new #GByteArray + + + + + + + number of bytes preallocated + + + + + + Sorts a byte array, using @compare_func which should be a +qsort()-style comparison function (returns less than zero for first +arg is less than second arg, zero for equal, greater than zero if +first arg is greater than second arg). + +If two array elements compare equal, their order in the sorted array +is undefined. If you want equal elements to keep their order (i.e. +you want a stable sort) you can write a comparison function that, +if two elements would otherwise compare equal, compares them by +their addresses. + + + + + + + a #GByteArray + + + + + + comparison function + + + + + + Like g_byte_array_sort(), but the comparison function takes an extra +user data argument. + + + + + + + a #GByteArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + Frees the data in the array and resets the size to zero, while + filename="glib/garray.c" + line="2698">Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller. - + the element data, which should be + filename="glib/garray.c" + line="2708">the element data, which should be freed using g_free(). a #GByteArray. + filename="glib/garray.c" + line="2700">a #GByteArray. @@ -60097,8 +65564,8 @@ to the caller. optional="1" allow-none="1"> pointer to retrieve the number of + filename="glib/garray.c" + line="2701">pointer to retrieve the number of elements of the original array @@ -60109,64 +65576,32 @@ to the caller. moved-to="ByteArray.unref" version="2.22"> Atomically decrements the reference count of @array by one. If the + filename="glib/garray.c" + line="2841">Atomically decrements the reference count of @array by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread. - + A #GByteArray + filename="glib/garray.c" + line="2843">A #GByteArray - - These macros provide a portable way to determine the host byte order -and to convert values between different byte orders. - -The byte order is the order in which bytes are stored to create larger -data types such as the #gint and #glong values. -The host byte order is the byte order used on the current machine. - -Some processors store the most significant bytes (i.e. the bytes that -hold the largest part of the value) first. These are known as big-endian -processors. Other processors (notably the x86 family) store the most -significant byte last. These are known as little-endian processors. - -Finally, to complicate matters, some other processors store the bytes in -a rather curious order known as PDP-endian. For a 4-byte word, the 3rd -most significant byte is stored first, then the 4th, then the 1st and -finally the 2nd. - -Obviously there is a problem when these different processors communicate -with each other, for example over networks or by using binary file formats. -This is where these macros come in. They are typically used to convert -values into a byte order which has been agreed on for use when -communicating between different processors. The Internet uses what is -known as 'network byte order' as the standard byte order (which is in -fact the big-endian byte order). - -Note that the byte order conversion macros may evaluate their arguments -multiple times, thus you should not use them with arguments which have -side-effects. - Gets the canonical file name from @filename. All triple slashes are turned into + filename="glib/gfileutils.c" + line="2764">Gets the canonical file name from @filename. All triple slashes are turned into single slashes, and all `..` and `.`s resolved against @relative_to. Symlinks are not followed, and the returned path is guaranteed to be absolute. @@ -60180,19 +65615,19 @@ This function never fails, and will canonicalize file paths even if they don't exist. No file system I/O is done. - + a newly allocated string with the + filename="glib/gfileutils.c" + line="2785">a newly allocated string with the canonical file path the name of the file + filename="glib/gfileutils.c" + line="2766">the name of the file nullable="1" allow-none="1"> the relative directory, or %NULL + filename="glib/gfileutils.c" + line="2767">the relative directory, or %NULL to use the current working directory @@ -60209,23 +65644,23 @@ to use the current working directory A wrapper for the POSIX chdir() function. The function changes the + filename="glib/gstdio.c" + line="1244">A wrapper for the POSIX chdir() function. The function changes the current directory of the process to @path. See your C library manual for more details about chdir(). - + 0 on success, -1 if an error occurred. + filename="glib/gstdio.c" + line="1254">0 on success, -1 if an error occurred. a pathname in the GLib file name encoding + filename="glib/gstdio.c" + line="1246">a pathname in the GLib file name encoding (UTF-8 on Windows) @@ -60235,8 +65670,8 @@ See your C library manual for more details about chdir(). c:identifier="glib_check_version" version="2.6"> Checks that the GLib library in use is compatible with the + filename="glib/gversion.c" + line="129">Checks that the GLib library in use is compatible with the given version. Generally you would pass in the constants %GLIB_MAJOR_VERSION, @@ -60251,11 +65686,11 @@ of the running library is newer than the version the running library must be binary compatible with the version `@required_major.@required_minor.@required_micro` (same major version.) - + %NULL if the GLib library is + filename="glib/gversion.c" + line="151">%NULL if the GLib library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GLib and must not be modified or freed. @@ -60264,80 +65699,44 @@ version `@required_major.@required_minor.@required_micro` the required major version + filename="glib/gversion.c" + line="131">the required major version the required minor version + filename="glib/gversion.c" + line="132">the required minor version the required micro version + filename="glib/gversion.c" + line="133">the required micro version - - GLib offers a set of macros for doing additions and multiplications -of unsigned integers, with checks for overflows. - -The helpers all have three arguments. A pointer to the destination -is always the first argument and the operands to the operation are -the other two. - -Following standard GLib convention, the helpers return %TRUE in case -of success (ie: no overflow). - -The helpers may be macros, normal functions or inlines. They may be -implemented with inline assembly or compiler intrinsics where -available. - - - GLib provides a generic API for computing checksums (or "digests") -for a sequence of arbitrary bytes, using various hashing algorithms -like MD5, SHA-1 and SHA-256. Checksums are commonly used in various -environments and specifications. - -GLib supports incremental checksums using the GChecksum data -structure, by calling g_checksum_update() as long as there's data -available and then using g_checksum_get_string() or -g_checksum_get_digest() to compute the checksum and return it either -as a string in hexadecimal form, or as a raw sequence of bytes. To -compute the checksum for binary blobs and NUL-terminated strings in -one go, use the convenience functions g_compute_checksum_for_data() -and g_compute_checksum_for_string(), respectively. - -Support for checksums has been added in GLib 2.16 - Gets the length in bytes of digests of type @checksum_type - + filename="glib/gchecksum.c" + line="1408">Gets the length in bytes of digests of type @checksum_type + the checksum length, or -1 if @checksum_type is + filename="glib/gchecksum.c" + line="1414">the checksum length, or -1 if @checksum_type is not supported. a #GChecksumType + filename="glib/gchecksum.c" + line="1410">a #GChecksumType @@ -60348,47 +65747,48 @@ not supported. version="2.4" introspectable="0"> Sets a function to be called when the child indicated by @pid -exits, at a default priority, %G_PRIORITY_DEFAULT. + filename="glib/gmain.c" + line="6201">Sets a function to be called when the child indicated by @pid +exits, at a default priority, [const@GLib.PRIORITY_DEFAULT]. -If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to -the spawn function for the child watching to work. +If you obtain @pid from [func@GLib.spawn_async] or +[func@GLib.spawn_async_with_pipes] you will need to pass +%G_SPAWN_DO_NOT_REAP_CHILD as flag to the spawn function for the child +watching to work. Note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the +(see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you will want to call -g_spawn_close_pid() in the callback function for the source. +[func@GLib.spawn_close_pid] in the callback function for the source. GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for -g_child_watch_source_new() apply to this function. +[func@GLib.child_watch_source_new] apply to this function. This internally creates a main loop source using -g_child_watch_source_new() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you +[func@GLib.child_watch_source_new] and attaches it to the main loop context +using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. - + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="6231">the ID (greater than 0) of the event source. process id to watch. On POSIX the positive pid of a child + filename="glib/gmain.c" + line="6203">process id to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child). function to call + filename="glib/gmain.c" + line="6206">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="6207">data to pass to @function @@ -60407,50 +65807,52 @@ need greater control. shadows="child_watch_add" version="2.4"> Sets a function to be called when the child indicated by @pid + filename="glib/gmain.c" + line="6133">Sets a function to be called when the child indicated by @pid exits, at the priority @priority. -If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to -the spawn function for the child watching to work. +If you obtain @pid from [func@GLib.spawn_async] or +[func@GLib.spawn_async_with_pipes] you will need to pass +%G_SPAWN_DO_NOT_REAP_CHILD as flag to the spawn function for the child +watching to work. -In many programs, you will want to call g_spawn_check_wait_status() +In many programs, you will want to call [func@GLib.spawn_check_wait_status] in the callback to determine whether or not the child exited successfully. Also, note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the source -is still active. Typically, you should invoke g_spawn_close_pid() +(see [func@GLib.spawn_close_pid]) @pid must not be closed while the source +is still active. Typically, you should invoke [func@GLib.spawn_close_pid] in the callback function for the source. GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for -g_child_watch_source_new() apply to this function. +[func@GLib.child_watch_source_new] apply to this function. This internally creates a main loop source using -g_child_watch_source_new() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you +[func@GLib.child_watch_source_new] and attaches it to the main loop context +using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. - + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="6170">the ID (greater than 0) of the event source. the priority of the idle source. Typically this will be in the - range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. + filename="glib/gmain.c" + line="6135">the priority of the idle source. Typically this will be in the + range between [const@GLib.PRIORITY_DEFAULT_IDLE] and + [const@GLib.PRIORITY_HIGH_IDLE]. process to watch. On POSIX the positive pid of a child process. On + filename="glib/gmain.c" + line="6138">process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child). @@ -60460,8 +65862,8 @@ Windows a handle for a process (which doesn't have to be a child). closure="3" destroy="4"> function to call + filename="glib/gmain.c" + line="6140">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="6141">data to pass to @function allow-none="1" scope="async"> function to call when the idle is removed, or %NULL + filename="glib/gmain.c" + line="6142">function to call when the idle is removed, or %NULL @@ -60489,20 +65891,20 @@ Windows a handle for a process (which doesn't have to be a child). c:identifier="g_child_watch_source_new" version="2.4"> Creates a new child_watch source. + filename="glib/gmain.c" + line="6017">Creates a new child_watch source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. +The source will not initially be associated with any +[struct@GLib.MainContext] and must be added to one with +[method@GLib.Source.attach] before it will be executed. Note that child watch sources can only be used in conjunction with `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. Note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the +(see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you will want to call -g_spawn_close_pid() in the callback function for the source. +[func@GLib.spawn_close_pid] in the callback function for the source. On POSIX platforms, the following restrictions apply to this API due to limitations in POSIX process interfaces: @@ -60517,8 +65919,8 @@ due to limitations in POSIX process interfaces: * the application must not ignore `SIGCHLD` * Before 2.78, the application could not send a signal (`kill()`) to the watched @pid in a race free manner. Since 2.78, you can do that while the - associated #GMainContext is acquired. -* Before 2.78, even after destroying the #GSource, you could not + associated [struct@GLib.MainContext] is acquired. +* Before 2.78, even after destroying the [struct@GLib.Source], you could not be sure that @pid wasn't already reaped. Hence, it was also not safe to `kill()` or `waitpid()` on the process ID after the child watch source was gone. Destroying the source before it fired made it @@ -60530,64 +65932,211 @@ stating that `ECHILD` was received by `waitpid`. Calling `waitpid` for specific processes other than @pid remains a valid thing to do. - + the newly-created child watch source + filename="glib/gmain.c" + line="6063">the newly-created child watch source process to watch. On POSIX the positive pid of a child process. On + filename="glib/gmain.c" + line="6019">process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child). + + A wrapper for the POSIX chmod() function. The chmod() function is +used to set the permissions of a file system object. + +On Windows the file protection mechanism is not at all POSIX-like, +and the underlying chmod() function in the C library just sets or +clears the FAT-style READONLY attribute. It does not touch any +ACL. Software that needs to manage file permissions on Windows +exactly should use the Win32 API. + +See your C library manual for more details about chmod(). + + + 0 if the operation succeeded, -1 on error + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in chmod() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + If @err or *@err is %NULL, does nothing. Otherwise, -calls g_error_free() on *@err and sets *@err to %NULL. - + filename="glib/gerror.c" + line="569">If @err or `*err` is %NULL, does nothing. Otherwise, +calls g_error_free() on `*err` and sets `*err` to %NULL. + + + If @fd_ptr points to a file descriptor, close it and return +whether closing it was successful, like g_close(). +If @fd_ptr points to a negative number, return %TRUE without closing +anything. +In both cases, set @fd_ptr to `-1` before returning. + +Like g_close(), if closing the file descriptor fails, the error is +stored in both %errno and @error. If this function succeeds, +%errno is undefined. + +On POSIX platforms, this function is async-signal safe +if @error is %NULL and @fd_ptr points to either a negative number or a +valid open file descriptor. +This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc +under those conditions. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +It is a programming error for @fd_ptr to point to a non-negative +number that is not a valid file descriptor. + +A typical use of this function is to clean up a file descriptor at +the end of its scope, whether it has been set successfully or not: + +|[ +gboolean +operate_on_fd (GError **error) +{ + gboolean ret = FALSE; + int fd = -1; + + fd = open_a_fd (error); + + if (fd < 0) + goto out; + + if (!do_something (fd, error)) + goto out; + + if (!g_clear_fd (&fd, error)) + goto out; + + ret = TRUE; + +out: + // OK to call even if fd was never opened or was already closed + g_clear_fd (&fd, NULL); + return ret; +} +]| + +This function is also useful in conjunction with #g_autofd. + + + %TRUE on success + + + + + a pointer to a file descriptor + + + + Clears a numeric handler, such as a #GSource ID. + filename="glib/gmain.c" + line="2618">Clears a numeric handler, such as a #GSource ID. @tag_ptr must be a valid pointer to the variable holding the handler. If the ID is zero then this function does nothing. -Otherwise, clear_func() is called with the ID as a parameter, and the tag is +Otherwise, @clear_func is called with the ID as a parameter, and the tag is set to zero. A macro is also included that allows this function to be used without pointer casts. - + a pointer to the handler ID + filename="glib/gmain.c" + line="2620">a pointer to the handler ID the function to call to clear the handler + filename="glib/gmain.c" + line="2621">the function to call to clear the handler @@ -60597,19 +66146,19 @@ pointer casts. version="2.64" introspectable="0"> Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy. + filename="glib/glist.c" + line="1256">Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy. @list_ptr must be a valid pointer. If @list_ptr points to a null #GList, this does nothing. - + a #GList return location + filename="glib/glist.c" + line="1258">a #GList return location @@ -60620,8 +66169,8 @@ pointer casts. allow-none="1" scope="async"> the function to pass to g_list_free_full() or %NULL to not free elements + filename="glib/glist.c" + line="1259">the function to pass to g_list_free_full() or %NULL to not free elements @@ -60631,8 +66180,8 @@ pointer casts. version="2.34" introspectable="0"> Clears a reference to a variable. + filename="glib/gmem.c" + line="243">Clears a reference to a variable. @pp must not be %NULL. @@ -60643,10 +66192,32 @@ pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. This will mask any warnings about incompatible function types or calling conventions, so you must ensure that your @destroy function is -compatible with being called as `GDestroyNotify` using the standard calling -convention for the platform that GLib was compiled for; otherwise the program -will experience undefined behaviour. - +compatible with being called as [callback@GLib.DestroyNotify] using the +standard calling convention for the platform that GLib was compiled for; +otherwise the program will experience undefined behaviour. + +Examples of this kind of undefined behaviour include using many Windows Win32 +APIs, as well as many if not all OpenGL and Vulkan calls on 32-bit Windows, +which typically use the `__stdcall` calling convention rather than the +`__cdecl` calling convention. + +The affected functions can be used by wrapping them in a +[callback@GLib.DestroyNotify] that is declared with the standard calling +convention: + +```c +// Wrapper needed to avoid mismatched calling conventions on Windows +static void +destroy_sync (void *sync) +{ + glDeleteSync (sync); +} + +// … + +g_clear_pointer (&sync, destroy_sync); +``` + @@ -60656,15 +66227,15 @@ will experience undefined behaviour. caller-allocates="0" transfer-ownership="full"> a pointer to a + filename="glib/gmem.c" + line="245">a pointer to a variable, struct member etc. holding a pointer a function to which a gpointer can be passed, to destroy *@pp + filename="glib/gmem.c" + line="247">a function to which a gpointer can be passed, to destroy `*pp` @@ -60674,19 +66245,19 @@ will experience undefined behaviour. version="2.64" introspectable="0"> Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy. + filename="glib/gslist.c" + line="1041">Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy. @slist_ptr must be a valid pointer. If @slist_ptr points to a null #GSList, this does nothing. - + a #GSList return location + filename="glib/gslist.c" + line="1043">a #GSList return location @@ -60697,16 +66268,16 @@ will experience undefined behaviour. allow-none="1" scope="async"> the function to pass to g_slist_free_full() or %NULL to not free elements + filename="glib/gslist.c" + line="1044">the function to pass to g_slist_free_full() or %NULL to not free elements This wraps the close() call. In case of error, %errno will be + filename="glib/gstdio.c" + line="1747">This wraps the close() call. In case of error, %errno will be preserved, but the error will also be stored as a #GError in @error. In case of success, %errno is undefined. @@ -60723,37 +66294,71 @@ This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc under those conditions. See [`signal(7)`](man:signal(7)) and [`signal-safety(7)`](man:signal-safety(7)) for more details. - + %TRUE on success, %FALSE if there was an error. + filename="glib/gstdio.c" + line="1770">%TRUE on success, %FALSE if there was an error. A file descriptor + filename="glib/gstdio.c" + line="1749">A file descriptor + + Close every file descriptor equal to or greater than @lowfd. + +Typically @lowfd will be 3, to leave standard input, standard output +and standard error open. + +This is the same as Linux `close_range (lowfd, ~0U, 0)`, +but portable to other OSs and to older versions of Linux. +Equivalently, it is the same as BSD `closefrom (lowfd)`, but portable, +and async-signal-safe on all OSs. + +This function is async-signal safe, making it safe to call from a +signal handler or a [callback@GLib.SpawnChildSetupFunc], as long as @lowfd is +non-negative. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + + + 0 on success, -1 with errno set on error + + + + + Minimum fd to close, which must be non-negative + + + + Computes the checksum for a binary @data. This is a + filename="glib/gchecksum.c" + line="1838">Computes the checksum for a binary @data. This is a convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free(). The hexadecimal string returned will be in lower case. - + the digest of the binary data as a + filename="glib/gchecksum.c" + line="1849">the digest of the binary data as a string in hexadecimal, or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. @@ -60762,14 +66367,14 @@ The hexadecimal string returned will be in lower case. a #GChecksumType + filename="glib/gchecksum.c" + line="1840">a #GChecksumType binary blob to compute the digest of + filename="glib/gchecksum.c" + line="1841">binary blob to compute the digest of @@ -60778,17 +66383,17 @@ The hexadecimal string returned will be in lower case. c:identifier="g_compute_checksum_for_data" version="2.16"> Computes the checksum for a binary @data of @length. This is a + filename="glib/gchecksum.c" + line="1769">Computes the checksum for a binary @data of @length. This is a convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free(). The hexadecimal string returned will be in lower case. - + the digest of the binary data as a + filename="glib/gchecksum.c" + line="1781">the digest of the binary data as a string in hexadecimal, or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. @@ -60797,22 +66402,22 @@ The hexadecimal string returned will be in lower case. a #GChecksumType + filename="glib/gchecksum.c" + line="1771">a #GChecksumType binary blob to compute the digest of + filename="glib/gchecksum.c" + line="1772">binary blob to compute the digest of length of @data + filename="glib/gchecksum.c" + line="1773">length of @data @@ -60821,15 +66426,15 @@ The hexadecimal string returned will be in lower case. c:identifier="g_compute_checksum_for_string" version="2.16"> Computes the checksum of a string. + filename="glib/gchecksum.c" + line="1809">Computes the checksum of a string. The hexadecimal string returned will be in lower case. - + the checksum as a hexadecimal string, + filename="glib/gchecksum.c" + line="1819">the checksum as a hexadecimal string, or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. @@ -60837,20 +66442,20 @@ The hexadecimal string returned will be in lower case. a #GChecksumType + filename="glib/gchecksum.c" + line="1811">a #GChecksumType the string to compute the checksum of + filename="glib/gchecksum.c" + line="1812">the string to compute the checksum of the length of the string, or -1 if the string is null-terminated. + filename="glib/gchecksum.c" + line="1813">the length of the string, or -1 if the string is null-terminated. @@ -60859,37 +66464,37 @@ The hexadecimal string returned will be in lower case. c:identifier="g_compute_hmac_for_bytes" version="2.50"> Computes the HMAC for a binary @data. This is a + filename="glib/ghmac.c" + line="402">Computes the HMAC for a binary @data. This is a convenience wrapper for g_hmac_new(), g_hmac_get_string() and g_hmac_unref(). The hexadecimal string returned will be in lower case. - + the HMAC of the binary data as a string in hexadecimal. + filename="glib/ghmac.c" + line="414">the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. a #GChecksumType to use for the HMAC + filename="glib/ghmac.c" + line="404">a #GChecksumType to use for the HMAC the key to use in the HMAC + filename="glib/ghmac.c" + line="405">the key to use in the HMAC binary blob to compute the HMAC of + filename="glib/ghmac.c" + line="406">binary blob to compute the HMAC of @@ -60898,53 +66503,53 @@ The hexadecimal string returned will be in lower case. c:identifier="g_compute_hmac_for_data" version="2.30"> Computes the HMAC for a binary @data of @length. This is a + filename="glib/ghmac.c" + line="360">Computes the HMAC for a binary @data of @length. This is a convenience wrapper for g_hmac_new(), g_hmac_get_string() and g_hmac_unref(). The hexadecimal string returned will be in lower case. - + the HMAC of the binary data as a string in hexadecimal. + filename="glib/ghmac.c" + line="374">the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. a #GChecksumType to use for the HMAC + filename="glib/ghmac.c" + line="362">a #GChecksumType to use for the HMAC the key to use in the HMAC + filename="glib/ghmac.c" + line="363">the key to use in the HMAC the length of the key + filename="glib/ghmac.c" + line="364">the length of the key binary blob to compute the HMAC of + filename="glib/ghmac.c" + line="365">binary blob to compute the HMAC of length of @data + filename="glib/ghmac.c" + line="366">length of @data @@ -60953,15 +66558,15 @@ The hexadecimal string returned will be in lower case. c:identifier="g_compute_hmac_for_string" version="2.30"> Computes the HMAC for a string. + filename="glib/ghmac.c" + line="438">Computes the HMAC for a string. The hexadecimal string returned will be in lower case. - + the HMAC as a hexadecimal string. + filename="glib/ghmac.c" + line="450">the HMAC as a hexadecimal string. The returned string should be freed with g_free() when done using it. @@ -60969,138 +66574,61 @@ The hexadecimal string returned will be in lower case. a #GChecksumType to use for the HMAC + filename="glib/ghmac.c" + line="440">a #GChecksumType to use for the HMAC the key to use in the HMAC + filename="glib/ghmac.c" + line="441">the key to use in the HMAC the length of the key + filename="glib/ghmac.c" + line="442">the length of the key the string to compute the HMAC for + filename="glib/ghmac.c" + line="443">the string to compute the HMAC for the length of the string, or -1 if the string is nul-terminated + filename="glib/ghmac.c" + line="444">the length of the string, or -1 if the string is nul-terminated - + The g_convert() family of function wraps the functionality of iconv(). -In addition to pure character set conversions, GLib has functions to -deal with the extra complications of encodings for file names. - -## File Name Encodings - -Historically, UNIX has not had a defined encoding for file names: -a file name is valid as long as it does not have path separators -in it ("/"). However, displaying file names may require conversion: -from the character set in which they were created, to the character -set in which the application operates. Consider the Spanish file name -"Presentación.sxi". If the application which created it uses -ISO-8859-1 for its encoding, -|[ -Character: P r e s e n t a c i ó n . s x i -Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 -]| -However, if the application use UTF-8, the actual file name on -disk would look like this: -|[ -Character: P r e s e n t a c i ó n . s x i -Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 -]| -GLib uses UTF-8 for its strings, and GUI toolkits like GTK that use -GLib do the same thing. If you get a file name from the file system, -for example, from readdir() or from g_dir_read_name(), and you wish -to display the file name to the user, you will need to convert it -into UTF-8. The opposite case is when the user types the name of a -file they wish to save: the toolkit will give you that string in -UTF-8 encoding, and you will need to convert it to the character -set used for file names before you can create the file with open() -or fopen(). - -By default, GLib assumes that file names on disk are in UTF-8 -encoding. This is a valid assumption for file systems which -were created relatively recently: most applications use UTF-8 -encoding for their strings, and that is also what they use for -the file names they create. However, older file systems may -still contain file names created in "older" encodings, such as -ISO-8859-1. In this case, for compatibility reasons, you may want -to instruct GLib to use that particular encoding for file names -rather than UTF-8. You can do this by specifying the encoding for -file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] -environment variable. For example, if your installation uses -ISO-8859-1 for file names, you can put this in your `~/.profile`: -|[ -export G_FILENAME_ENCODING=ISO-8859-1 -]| -GLib provides the functions g_filename_to_utf8() and -g_filename_from_utf8() to perform the necessary conversions. -These functions convert file names from the encoding specified -in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This -[diagram][file-name-encodings-diagram] illustrates how -these functions are used to convert between UTF-8 and the -encoding for file names in the file system. - -## Conversion between file name encodings # {#file-name-encodings-diagram) - -![](file-name-encodings.png) - -## Checklist for Application Writers - -This section is a practical summary of the detailed -things to do to make sure your applications process file -name encodings correctly. - -1. If you get a file name from the file system from a function - such as readdir() or gtk_file_chooser_get_filename(), you do - not need to do any conversion to pass that file name to - functions like open(), rename(), or fopen() -- those are "raw" - file names which the file system understands. - -2. If you need to display a file name, convert it to UTF-8 first - by using g_filename_to_utf8(). If conversion fails, display a - string like "Unknown file name". Do not convert this string back - into the encoding used for file names if you wish to pass it to - the file system; use the original file name instead. - - For example, the document window of a word processor could display - "Unknown file name" in its title bar but still let the user save - the file, as it would keep the raw file name internally. This - can happen if the user has not set the `G_FILENAME_ENCODING` - environment variable even though they have files whose names are - not encoded in UTF-8. - -3. If your user interface lets the user type a file name for saving - or renaming, convert it to the encoding used for file names in - the file system by using g_filename_from_utf8(). Pass the converted - file name to functions like fopen(). If conversion fails, ask the - user to enter a different file name. This can happen if the user - types Japanese characters when `G_FILENAME_ENCODING` is set to - `ISO-8859-1`, for example. - + filename="glib/deprecated/gthread-deprecated.c" + line="1487">Allocates and initializes a new #GCond. + GCond can now be statically allocated, or embedded +in structures and initialised with g_cond_init(). + + + a newly allocated #GCond. Free with g_cond_free() + + + Converts a string from one character set to another. + filename="glib/gconvert.c" + line="422">Converts a string from one character set to another. Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial @@ -61114,11 +66642,11 @@ could combine with the base character.) Using extensions such as "//TRANSLIT" may not work (or may not work well) on many platforms. Consider using g_str_to_ascii() instead. - + + filename="glib/gconvert.c" + line="460"> If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with g_free(). Otherwise %NULL and @error will be set. @@ -61129,8 +66657,8 @@ well) on many platforms. Consider using g_str_to_ascii() instead. + filename="glib/gconvert.c" + line="424"> the string to convert. @@ -61138,8 +66666,8 @@ well) on many platforms. Consider using g_str_to_ascii() instead. the length of the string in bytes, or -1 if the string is + filename="glib/gconvert.c" + line="426">the length of the string in bytes, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) @@ -61147,14 +66675,14 @@ well) on many platforms. Consider using g_str_to_ascii() instead. name of character set into which to convert @str + filename="glib/gconvert.c" + line="430">name of character set into which to convert @str character set of @str. + filename="glib/gconvert.c" + line="431">character set of @str. optional="1" allow-none="1"> location to store the number of bytes in + filename="glib/gconvert.c" + line="432">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -61182,8 +66710,8 @@ well) on many platforms. Consider using g_str_to_ascii() instead. optional="1" allow-none="1"> the number of bytes stored in + filename="glib/gconvert.c" + line="440">the number of bytes stored in the output buffer (not including the terminating nul). @@ -61198,8 +66726,8 @@ well) on many platforms. Consider using g_str_to_ascii() instead. c:identifier="g_convert_with_fallback" throws="1"> Converts a string from one character set to another, possibly + filename="glib/gconvert.c" + line="503">Converts a string from one character set to another, possibly including fallback sequences for characters not representable in the output. Note that it is not guaranteed that the specification for the fallback sequences in @fallback will be honored. Some @@ -61216,11 +66744,11 @@ g_convert_with_iconv() or g_convert_with_fallback(). (An example of this is the GNU C converter for CP1255 which does not emit a base character until it knows that the next character is not a mark that could combine with the base character.) - + + filename="glib/gconvert.c" + line="546"> If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with g_free(). Otherwise %NULL and @error will be set. @@ -61231,8 +66759,8 @@ could combine with the base character.) + filename="glib/gconvert.c" + line="505"> the string to convert. @@ -61240,8 +66768,8 @@ could combine with the base character.) the length of the string in bytes, or -1 if the string is + filename="glib/gconvert.c" + line="507">the length of the string in bytes, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) @@ -61249,20 +66777,20 @@ could combine with the base character.) name of character set into which to convert @str + filename="glib/gconvert.c" + line="511">name of character set into which to convert @str character set of @str. + filename="glib/gconvert.c" + line="512">character set of @str. UTF-8 string to use in place of characters not + filename="glib/gconvert.c" + line="513">UTF-8 string to use in place of characters not present in the target encoding. (The string must be representable in the target encoding). If %NULL, characters not in the target encoding will @@ -61276,8 +66804,8 @@ could combine with the base character.) optional="1" allow-none="1"> location to store the number of bytes in + filename="glib/gconvert.c" + line="518">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -61291,8 +66819,8 @@ could combine with the base character.) optional="1" allow-none="1"> the number of bytes stored in + filename="glib/gconvert.c" + line="523">the number of bytes stored in the output buffer (not including the terminating nul). @@ -61303,8 +66831,8 @@ could combine with the base character.) introspectable="0" throws="1"> Converts a string from one character set to another. + filename="glib/gconvert.c" + line="252">Converts a string from one character set to another. Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial @@ -61323,11 +66851,11 @@ specification, which leaves this behaviour implementation defined. Note that this is the same error code as is returned for an invalid byte sequence in the input character set. To get defined behaviour for conversion of unrepresentable characters, use g_convert_with_fallback(). - + + filename="glib/gconvert.c" + line="294"> If the conversion was successful, a newly allocated buffer containing the converted string, which must be freed with g_free(). Otherwise %NULL and @error will be set. @@ -61338,8 +66866,8 @@ unrepresentable characters, use g_convert_with_fallback(). + filename="glib/gconvert.c" + line="254"> the string to convert. @@ -61347,8 +66875,8 @@ unrepresentable characters, use g_convert_with_fallback(). the length of the string in bytes, or -1 if the string is + filename="glib/gconvert.c" + line="256">the length of the string in bytes, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) @@ -61356,8 +66884,8 @@ unrepresentable characters, use g_convert_with_fallback(). conversion descriptor from g_iconv_open() + filename="glib/gconvert.c" + line="260">conversion descriptor from g_iconv_open() optional="1" allow-none="1"> location to store the number of bytes in + filename="glib/gconvert.c" + line="261">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -61385,116 +66913,133 @@ unrepresentable characters, use g_convert_with_fallback(). optional="1" allow-none="1"> the number of bytes stored in + filename="glib/gconvert.c" + line="269">the number of bytes stored in the output buffer (not including the terminating nul). + + A wrapper for the POSIX creat() function. The creat() function is +used to convert a pathname into a file descriptor, creating a file +if necessary. + +On POSIX systems file descriptors are implemented by the operating +system. On Windows, it's the C library that implements creat() and +file descriptors. The actual Windows API for opening files is +different, see MSDN documentation for CreateFile(). The Win32 API +uses file handles, which are more randomish integers, not small +integers like file descriptors. + +Because file descriptors are specific to the C library on Windows, +the file descriptor returned by this function makes sense only to +functions in the same C library. Thus if the GLib-using code uses a +different C library than GLib does, the file descriptor returned by +this function cannot be passed to C library functions like write() +or read(). + +See your C library manual for more details about creat(). + + + a new file descriptor, or -1 if an error occurred. + The return value can be used exactly like the return value + from creat(). + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in creat() + + + + Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL). + filename="glib/gmessages.c" + line="240">Logs a ‘critical warning’ ([flags@GLib.LogLevelFlags.LEVEL_CRITICAL]). Critical warnings are intended to be used in the event of an error that originated in the current process (a programmer error). Logging of a critical error is by definition an indication of a bug somewhere in the current program (or its libraries). -g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and -g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL. +[func@GLib.return_if_fail], [func@GLib.return_val_if_fail], [func@GLib.return_if_reached] and +[func@GLib.return_val_if_reached] log at [flags@GLib.LogLevelFlags.LEVEL_CRITICAL]. You can make critical warnings fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](glib-running.html)): -|[ - G_DEBUG=fatal-warnings gdb ./my-program -]| +``` +G_DEBUG=fatal-warnings gdb ./my-program +``` -You can also use g_log_set_always_fatal(). +You can also use [func@GLib.log_set_always_fatal]. Any unrelated failures can be skipped over in [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. The message should typically *not* be translated to the -user's language. +user’s language. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. - +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). + format string, followed by parameters to insert - into the format string (as with printf()) + filename="glib/gmessages.c" + line="242">format string, followed by parameters to insert into the format string + (as with `printf()`) - - Keyed data lists provide lists of arbitrary data elements which can -be accessed either with a string or with a #GQuark corresponding to -the string. - -The #GQuark methods are quicker, since the strings have to be -converted to #GQuarks anyway. - -Data lists are used for associating arbitrary data with #GObjects, -using g_object_set_data() and related functions. - -To create a datalist, use g_datalist_init(). - -To add data elements to a datalist use g_datalist_id_set_data(), -g_datalist_id_set_data_full(), g_datalist_set_data() and -g_datalist_set_data_full(). - -To get data elements from a datalist use g_datalist_id_get_data() -and g_datalist_get_data(). - -To iterate over all data elements in a datalist use -g_datalist_foreach() (not thread-safe). - -To remove data elements from a datalist use -g_datalist_id_remove_data() and g_datalist_remove_data(). - -To remove all data elements from a datalist, use g_datalist_clear(). - Frees all the data elements of the datalist. + filename="glib/gdataset.c" + line="502">Frees all the data elements of the datalist. The data elements' destroy functions are called if they have been set. - + a datalist. + filename="glib/gdataset.c" + line="504">a datalist. Calls the given function for each data element of the datalist. The + filename="glib/gdataset.c" + line="1502">Calls the given function for each data element of the datalist. The function is called with each data element's #GQuark id and data, together with the given @user_data parameter. Note that this function is NOT thread-safe. So unless @datalist can be protected @@ -61504,15 +67049,15 @@ not be called. @func can make changes to @datalist, but the iteration will not reflect changes made during the g_datalist_foreach() call, other than skipping over elements that are removed. - + a datalist. + filename="glib/gdataset.c" + line="1504">a datalist. scope="call" closure="2"> the function to call for each data element. + filename="glib/gdataset.c" + line="1505">the function to call for each data element. nullable="1" allow-none="1"> user data to pass to the function. + filename="glib/gdataset.c" + line="1506">user data to pass to the function. Gets a data element, using its string identifier. This is slower than + filename="glib/gdataset.c" + line="1385">Gets a data element, using its string identifier. This is slower than g_datalist_id_get_data() because it compares strings. - + the data element, or %NULL if it + filename="glib/gdataset.c" + line="1393">the data element, or %NULL if it is not found. a datalist. + filename="glib/gdataset.c" + line="1387">a datalist. the string identifying a data element. + filename="glib/gdataset.c" + line="1388">the string identifying a data element. @@ -61567,21 +67112,21 @@ g_datalist_id_get_data() because it compares strings. c:identifier="g_datalist_get_flags" version="2.8"> Gets flags values packed in together with the datalist. + filename="glib/gdataset.c" + line="1627">Gets flags values packed in together with the datalist. See g_datalist_set_flags(). - + the flags of the datalist + filename="glib/gdataset.c" + line="1634">the flags of the datalist pointer to the location that holds a list + filename="glib/gdataset.c" + line="1629">pointer to the location that holds a list @@ -61591,8 +67136,8 @@ See g_datalist_set_flags(). version="2.34" introspectable="0"> This is a variant of g_datalist_id_get_data() which + filename="glib/gdataset.c" + line="1238">This is a variant of g_datalist_id_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. @@ -61605,11 +67150,11 @@ is not allowed to read or modify the datalist. This function can be useful to avoid races when multiple threads are using the same datalist and the same key. - + the result of calling @dup_func on the value + filename="glib/gdataset.c" + line="1260">the result of calling @dup_func on the value associated with @key_id in @datalist, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. @@ -61617,14 +67162,14 @@ threads are using the same datalist and the same key. location of a datalist + filename="glib/gdataset.c" + line="1240">location of a datalist the #GQuark identifying a data element + filename="glib/gdataset.c" + line="1241">the #GQuark identifying a data element scope="call" closure="3"> function to + filename="glib/gdataset.c" + line="1242">function to duplicate the old value @@ -61644,8 +67189,8 @@ threads are using the same datalist and the same key. nullable="1" allow-none="1"> passed as user_data to @dup_func + filename="glib/gdataset.c" + line="1244">passed as user_data to @dup_func @@ -61653,27 +67198,27 @@ threads are using the same datalist and the same key. Retrieves the data element corresponding to @key_id. - + filename="glib/gdataset.c" + line="1207">Retrieves the data element corresponding to @key_id. + the data element, or %NULL if + filename="glib/gdataset.c" + line="1214">the data element, or %NULL if it is not found. a datalist. + filename="glib/gdataset.c" + line="1209">a datalist. the #GQuark identifying a data element. + filename="glib/gdataset.c" + line="1210">the #GQuark identifying a data element. @@ -61682,19 +67227,19 @@ threads are using the same datalist and the same key. c:identifier="g_datalist_id_remove_data" introspectable="0"> Removes an element, using its #GQuark identifier. - + filename="glib/gdataset.c" + line="951">Removes an element, using its #GQuark identifier. + a datalist. + filename="glib/gdataset.c" + line="953">a datalist. the #GQuark identifying the data element. + filename="glib/gdataset.c" + line="954">the #GQuark identifying the data element. @@ -61702,34 +67247,37 @@ threads are using the same datalist and the same key. c:identifier="g_datalist_id_remove_multiple" version="2.74"> Removes multiple keys from a datalist. + filename="glib/gdataset.c" + line="710">Removes multiple keys from a datalist. This is more efficient than calling g_datalist_id_remove_data() -multiple times in a row. - +multiple times in a row. + +Before 2.80, @n_keys had to be not larger than 16. +Since 2.84, performance is improved for larger number of keys. + a datalist + filename="glib/gdataset.c" + line="712">a datalist keys to remove + filename="glib/gdataset.c" + line="713">keys to remove length of @keys, must be <= 16 + filename="glib/gdataset.c" + line="714">length of @keys. @@ -61738,28 +67286,28 @@ multiple times in a row. c:identifier="g_datalist_id_remove_no_notify" introspectable="0"> Removes an element, without calling its destroy notification + filename="glib/gdataset.c" + line="1026">Removes an element, without calling its destroy notification function. - + the data previously stored at @key_id, + filename="glib/gdataset.c" + line="1034">the data previously stored at @key_id, or %NULL if none. a datalist. + filename="glib/gdataset.c" + line="1028">a datalist. the #GQuark identifying a data element. + filename="glib/gdataset.c" + line="1029">the #GQuark identifying a data element. @@ -61769,8 +67317,8 @@ function. version="2.34" introspectable="0"> Compares the member that is associated with @key_id in + filename="glib/gdataset.c" + line="1293">Compares the member that is associated with @key_id in @datalist to @oldval, and if they are the same, replace @oldval with @newval. @@ -61783,25 +67331,25 @@ the registered destroy notify for it (passed out in @old_destroy). Its up to the caller to free this as they wish, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. - + %TRUE if the existing value for @key_id was replaced + filename="glib/gdataset.c" + line="1316">%TRUE if the existing value for @key_id was replaced by @newval, %FALSE otherwise. location of a datalist + filename="glib/gdataset.c" + line="1295">location of a datalist the #GQuark identifying a data element + filename="glib/gdataset.c" + line="1296">the #GQuark identifying a data element nullable="1" allow-none="1"> the old value to compare against + filename="glib/gdataset.c" + line="1297">the old value to compare against nullable="1" allow-none="1"> the new value to replace it with + filename="glib/gdataset.c" + line="1298">the new value to replace it with allow-none="1" scope="async"> destroy notify for the new value + filename="glib/gdataset.c" + line="1299">destroy notify for the new value allow-none="1" scope="async"> destroy notify for the existing value + filename="glib/gdataset.c" + line="1300">destroy notify for the existing value @@ -61850,26 +67398,26 @@ should not destroy the object in the normal way. c:identifier="g_datalist_id_set_data" introspectable="0"> Sets the data corresponding to the given #GQuark id. Any previous + filename="glib/gdataset.c" + line="931">Sets the data corresponding to the given #GQuark id. Any previous data with the same key is removed, and its destroy function is called. - + a datalist. + filename="glib/gdataset.c" + line="933">a datalist. the #GQuark to identify the data element. + filename="glib/gdataset.c" + line="934">the #GQuark to identify the data element. the data element, or %NULL to remove any previous element + filename="glib/gdataset.c" + line="935">the data element, or %NULL to remove any previous element corresponding to @q. @@ -61878,26 +67426,26 @@ called. c:identifier="g_datalist_id_set_data_full" introspectable="0"> Sets the data corresponding to the given #GQuark id, and the + filename="glib/gdataset.c" + line="900">Sets the data corresponding to the given #GQuark id, and the function to be called when the element is removed from the datalist. Any previous data with the same key is removed, and its destroy function is called. - + a datalist. + filename="glib/gdataset.c" + line="902">a datalist. the #GQuark to identify the data element. + filename="glib/gdataset.c" + line="903">the #GQuark to identify the data element. nullable="1" allow-none="1"> the data element or %NULL to remove any previous element + filename="glib/gdataset.c" + line="904">the data element or %NULL to remove any previous element corresponding to @key_id. @@ -61916,8 +67464,8 @@ function is called. allow-none="1" scope="async"> the function to call when the data element is + filename="glib/gdataset.c" + line="906">the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @data is %NULL, then @destroy_func must @@ -61930,18 +67478,18 @@ function is called. c:identifier="g_datalist_init" introspectable="0"> Resets the datalist to %NULL. It does not free any memory or call + filename="glib/gdataset.c" + line="1561">Resets the datalist to %NULL. It does not free any memory or call any destroy functions. - + a pointer to a pointer to a datalist. + filename="glib/gdataset.c" + line="1563">a pointer to a pointer to a datalist. @@ -61950,20 +67498,20 @@ any destroy functions. c:identifier="g_datalist_remove_data" introspectable="0"> Removes an element using its string identifier. The data element's + filename="glib/gdataset.c" + line="958">Removes an element using its string identifier. The data element's destroy function is called if it has been set. - + a datalist. + filename="glib/gdataset.c" + line="960">a datalist. the string identifying the data element. + filename="glib/gdataset.c" + line="961">the string identifying the data element. @@ -61971,19 +67519,19 @@ destroy function is called if it has been set. c:identifier="g_datalist_remove_no_notify" introspectable="0"> Removes an element, without calling its destroy notifier. - + filename="glib/gdataset.c" + line="1037">Removes an element, without calling its destroy notifier. + a datalist. + filename="glib/gdataset.c" + line="1039">a datalist. the string identifying the data element. + filename="glib/gdataset.c" + line="1040">the string identifying the data element. @@ -61991,24 +67539,24 @@ destroy function is called if it has been set. c:identifier="g_datalist_set_data" introspectable="0"> Sets the data element corresponding to the given string identifier. - + filename="glib/gdataset.c" + line="942">Sets the data element corresponding to the given string identifier. + a datalist. + filename="glib/gdataset.c" + line="944">a datalist. the string to identify the data element. + filename="glib/gdataset.c" + line="945">the string to identify the data element. the data element, or %NULL to remove any previous element + filename="glib/gdataset.c" + line="946">the data element, or %NULL to remove any previous element corresponding to @k. @@ -62017,31 +67565,31 @@ destroy function is called if it has been set. c:identifier="g_datalist_set_data_full" introspectable="0"> Sets the data element corresponding to the given string identifier, + filename="glib/gdataset.c" + line="917">Sets the data element corresponding to the given string identifier, and the function to be called when the data element is removed. - + a datalist. + filename="glib/gdataset.c" + line="919">a datalist. the string to identify the data element. + filename="glib/gdataset.c" + line="920">the string to identify the data element. the data element, or %NULL to remove any previous element + filename="glib/gdataset.c" + line="921">the data element, or %NULL to remove any previous element corresponding to @k. the function to call when the data element is removed. + filename="glib/gdataset.c" + line="923">the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @d is %NULL, then @f must also be %NULL. @@ -62052,28 +67600,28 @@ and the function to be called when the data element is removed. c:identifier="g_datalist_set_flags" version="2.8"> Turns on flag values for a data list. This function is used + filename="glib/gdataset.c" + line="1576">Turns on flag values for a data list. This function is used to keep a small number of boolean flags in an object with a data list without using any additional space. It is not generally useful except in circumstances where space is very tight. (It is used in the base #GObject type, for example.) - + pointer to the location that holds a list + filename="glib/gdataset.c" + line="1578">pointer to the location that holds a list the flags to turn on. The values of the flags are + filename="glib/gdataset.c" + line="1579">the flags to turn on. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3; giving two possible boolean flags). A value for @flags that doesn't fit within the mask is @@ -62086,23 +67634,23 @@ example.) c:identifier="g_datalist_unset_flags" version="2.8"> Turns off flag values for a data list. See g_datalist_unset_flags() - + filename="glib/gdataset.c" + line="1604">Turns off flag values for a data list. See g_datalist_unset_flags() + pointer to the location that holds a list + filename="glib/gdataset.c" + line="1606">pointer to the location that holds a list the flags to turn off. The values of the flags are + filename="glib/gdataset.c" + line="1607">the flags to turn off. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3: giving two possible boolean flags). A value for @flags that doesn't fit within the mask is @@ -62113,26 +67661,26 @@ example.) Destroys the dataset, freeing all memory allocated, and calling any + filename="glib/gdataset.c" + line="579">Destroys the dataset, freeing all memory allocated, and calling any destroy functions set for data elements. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="581">the location identifying the dataset. Calls the given function for each data element which is associated + filename="glib/gdataset.c" + line="1463">Calls the given function for each data element which is associated with the given location. Note that this function is NOT thread-safe. So unless @dataset_location can be protected from any modifications during invocation of this function, it should not be called. @@ -62140,15 +67688,15 @@ during invocation of this function, it should not be called. @func can make changes to the dataset, but the iteration will not reflect changes made during the g_dataset_foreach() call, other than skipping over elements that are removed. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="1465">the location identifying the dataset. scope="call" closure="2"> the function to call for each data element. + filename="glib/gdataset.c" + line="1466">the function to call for each data element. nullable="1" allow-none="1"> user data to pass to the function. + filename="glib/gdataset.c" + line="1467">user data to pass to the function. @@ -62175,45 +67723,45 @@ than skipping over elements that are removed. c:identifier="g_dataset_get_data" introspectable="0"> Gets the data element corresponding to a string. - + filename="glib/gdataset.c" + line="1175">Gets the data element corresponding to a string. + the location identifying the dataset. + filename="glib/gdataset.c" + line="1177">the location identifying the dataset. the string identifying the data element. + filename="glib/gdataset.c" + line="1178">the string identifying the data element. Gets the data element corresponding to a #GQuark. - + filename="glib/gdataset.c" + line="1165">Gets the data element corresponding to a #GQuark. + the data element corresponding to + filename="glib/gdataset.c" + line="1172">the data element corresponding to the #GQuark, or %NULL if it is not found. the location identifying the dataset. + filename="glib/gdataset.c" + line="1167">the location identifying the dataset. the #GQuark id to identify the data element. + filename="glib/gdataset.c" + line="1168">the #GQuark id to identify the data element. @@ -62222,20 +67770,20 @@ than skipping over elements that are removed. c:identifier="g_dataset_id_remove_data" introspectable="0"> Removes a data element from a dataset. The data element's destroy + filename="glib/gdataset.c" + line="846">Removes a data element from a dataset. The data element's destroy function is called if it has been set. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="848">the location identifying the dataset. the #GQuark id identifying the data element. + filename="glib/gdataset.c" + line="849">the #GQuark id identifying the data element. @@ -62243,28 +67791,28 @@ function is called if it has been set. c:identifier="g_dataset_id_remove_no_notify" introspectable="0"> Removes an element, without calling its destroy notification + filename="glib/gdataset.c" + line="986">Removes an element, without calling its destroy notification function. - + the data previously stored at @key_id, + filename="glib/gdataset.c" + line="994">the data previously stored at @key_id, or %NULL if none. the location identifying the dataset. + filename="glib/gdataset.c" + line="988">the location identifying the dataset. the #GQuark ID identifying the data element. + filename="glib/gdataset.c" + line="989">the #GQuark ID identifying the data element. @@ -62273,26 +67821,26 @@ function. c:identifier="g_dataset_id_set_data" introspectable="0"> Sets the data element associated with the given #GQuark id. Any + filename="glib/gdataset.c" + line="828">Sets the data element associated with the given #GQuark id. Any previous data with the same key is removed, and its destroy function is called. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="830">the location identifying the dataset. the #GQuark id to identify the data element. + filename="glib/gdataset.c" + line="831">the #GQuark id to identify the data element. the data element. + filename="glib/gdataset.c" + line="832">the data element. @@ -62300,26 +67848,26 @@ is called. c:identifier="g_dataset_id_set_data_full" introspectable="0"> Sets the data element associated with the given #GQuark id, and also + filename="glib/gdataset.c" + line="801">Sets the data element associated with the given #GQuark id, and also the function to call when the data element is destroyed. Any previous data with the same key is removed, and its destroy function is called. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="803">the location identifying the dataset. the #GQuark id to identify the data element. + filename="glib/gdataset.c" + line="804">the #GQuark id to identify the data element. nullable="1" allow-none="1"> the data element. + filename="glib/gdataset.c" + line="805">the data element. the function to call when the data element is + filename="glib/gdataset.c" + line="806">the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. @@ -62346,20 +67894,20 @@ is called. c:identifier="g_dataset_remove_data" introspectable="0"> Removes a data element corresponding to a string. Its destroy + filename="glib/gdataset.c" + line="854">Removes a data element corresponding to a string. Its destroy function is called if it has been set. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="856">the location identifying the dataset. the string identifying the data element. + filename="glib/gdataset.c" + line="857">the string identifying the data element. @@ -62367,19 +67915,19 @@ function is called if it has been set. c:identifier="g_dataset_remove_no_notify" introspectable="0"> Removes an element, without calling its destroy notifier. - + filename="glib/gdataset.c" + line="997">Removes an element, without calling its destroy notifier. + the location identifying the dataset. + filename="glib/gdataset.c" + line="999">the location identifying the dataset. the string identifying the data element. + filename="glib/gdataset.c" + line="1000">the string identifying the data element. @@ -62387,24 +67935,24 @@ function is called if it has been set. c:identifier="g_dataset_set_data" introspectable="0"> Sets the data corresponding to the given string identifier. - + filename="glib/gdataset.c" + line="838">Sets the data corresponding to the given string identifier. + the location identifying the dataset. + filename="glib/gdataset.c" + line="840">the location identifying the dataset. the string to identify the data element. + filename="glib/gdataset.c" + line="841">the string to identify the data element. the data element. + filename="glib/gdataset.c" + line="842">the data element. @@ -62412,167 +67960,60 @@ function is called if it has been set. c:identifier="g_dataset_set_data_full" introspectable="0"> Sets the data corresponding to the given string identifier, and the + filename="glib/gdataset.c" + line="816">Sets the data corresponding to the given string identifier, and the function to call when the data element is destroyed. - + the location identifying the dataset. + filename="glib/gdataset.c" + line="818">the location identifying the dataset. the string to identify the data element. + filename="glib/gdataset.c" + line="819">the string to identify the data element. the data element. + filename="glib/gdataset.c" + line="820">the data element. the function to call when the data element is removed. This + filename="glib/gdataset.c" + line="821">the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. - - Datasets associate groups of data elements with particular memory -locations. These are useful if you need to associate data with a -structure returned from an external library. Since you cannot modify -the structure, you use its location in memory as the key into a -dataset, where you can associate any number of data elements with it. - -There are two forms of most of the dataset functions. The first form -uses strings to identify the data elements associated with a -location. The second form uses #GQuark identifiers, which are -created with a call to g_quark_from_string() or -g_quark_from_static_string(). The second form is quicker, since it -does not require looking up the string in the hash table of #GQuark -identifiers. - -There is no function to create a dataset. It is automatically -created as soon as you add elements to it. - -To add data elements to a dataset use g_dataset_id_set_data(), -g_dataset_id_set_data_full(), g_dataset_set_data() and -g_dataset_set_data_full(). - -To get data elements from a dataset use g_dataset_id_get_data() and -g_dataset_get_data(). - -To iterate over all data elements in a dataset use -g_dataset_foreach() (not thread-safe). - -To remove data elements from a dataset use -g_dataset_id_remove_data() and g_dataset_remove_data(). - -To destroy a dataset, use g_dataset_destroy(). - - - The #GDate data structure represents a day between January 1, Year 1, -and sometime a few thousand years in the future (right now it will go -to the year 65535 or so, but g_date_set_parse() only parses up to the -year 8000 or so - just count on "a few thousand"). #GDate is meant to -represent everyday dates, not astronomical dates or historical dates -or ISO timestamps or the like. It extrapolates the current Gregorian -calendar forward and backward in time; there is no attempt to change -the calendar to match time periods or locations. #GDate does not store -time information; it represents a day. - -The #GDate implementation has several nice features; it is only a -64-bit struct, so storing large numbers of dates is very efficient. It -can keep both a Julian and day-month-year representation of the date, -since some calculations are much easier with one representation or the -other. A Julian representation is simply a count of days since some -fixed day in the past; for #GDate the fixed day is January 1, 1 AD. -("Julian" dates in the #GDate API aren't really Julian dates in the -technical sense; technically, Julian dates count from the start of the -Julian period, Jan 1, 4713 BC). - -#GDate is simple to use. First you need a "blank" date; you can get a -dynamically allocated date from g_date_new(), or you can declare an -automatic variable or array and initialize it by -calling g_date_clear(). A cleared date is safe; it's safe to call -g_date_set_dmy() and the other mutator functions to initialize the -value of a cleared date. However, a cleared date is initially -invalid, meaning that it doesn't represent a day that exists. -It is undefined to call any of the date calculation routines on an -invalid date. If you obtain a date from a user or other -unpredictable source, you should check its validity with the -g_date_valid() predicate. g_date_valid() is also used to check for -errors with g_date_set_parse() and other functions that can -fail. Dates can be invalidated by calling g_date_clear() again. - -It is very important to use the API to access the #GDate -struct. Often only the day-month-year or only the Julian -representation is valid. Sometimes neither is valid. Use the API. - -GLib also features #GDateTime which represents a precise time. - - - #GDateTime is a structure that combines a Gregorian date and time -into a single structure. It provides many conversion and methods to -manipulate dates and times. Time precision is provided down to -microseconds and the time can range (proleptically) from 0001-01-01 -00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX -time in the sense that it is oblivious to leap seconds. - -#GDateTime is an immutable object; once it has been created it cannot -be modified further. All modifiers will create a new #GDateTime. -Nearly all such functions can fail due to the date or time going out -of range, in which case %NULL will be returned. - -#GDateTime is reference counted: the reference count is increased by calling -g_date_time_ref() and decreased by calling g_date_time_unref(). When the -reference count drops to 0, the resources allocated by the #GDateTime -structure are released. - -Many parts of the API may produce non-obvious results. As an -example, adding two months to January 31st will yield March 31st -whereas adding one month and then one month again will yield either -March 28th or March 29th. Also note that adding 24 hours is not -always the same as adding one day (since days containing daylight -savings time transitions are either 23 or 25 hours in length). - -#GDateTime is available since GLib 2.26. - Returns the number of days in a month, taking leap + filename="glib/gdate.c" + line="1926">Returns the number of days in a month, taking leap years into account. - + number of days in @month during the @year + filename="glib/gdate.c" + line="1934">number of days in @month during the @year month + filename="glib/gdate.c" + line="1928">month year + filename="glib/gdate.c" + line="1929">year @@ -62581,26 +68022,26 @@ years into account. c:identifier="g_date_get_monday_weeks_in_year" moved-to="Date.get_monday_weeks_in_year"> Returns the number of weeks in the year, where weeks + filename="glib/gdate.c" + line="1950">Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.) - + number of Mondays in the year + filename="glib/gdate.c" + line="1962">number of Mondays in the year a year + filename="glib/gdate.c" + line="1952">a year @@ -62609,26 +68050,26 @@ one of the extra days happens to be a Monday.) c:identifier="g_date_get_sunday_weeks_in_year" moved-to="Date.get_sunday_weeks_in_year"> Returns the number of weeks in the year, where weeks + filename="glib/gdate.c" + line="1986">Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.) - + the number of weeks in @year + filename="glib/gdate.c" + line="1998">the number of weeks in @year year to count weeks in + filename="glib/gdate.c" + line="1988">year to count weeks in @@ -62637,25 +68078,25 @@ one of the extra days happens to be a Sunday.) c:identifier="g_date_is_leap_year" moved-to="Date.is_leap_year"> Returns %TRUE if the year is a leap year. + filename="glib/gdate.c" + line="1904">Returns %TRUE if the year is a leap year. For the purposes of this function, leap year is every year divisible by 4 unless that year is divisible by 100. If it is divisible by 100 it would be a leap year only if that year is also divisible by 400. - + %TRUE if the year is a leap year + filename="glib/gdate.c" + line="1915">%TRUE if the year is a leap year year to check + filename="glib/gdate.c" + line="1906">year to check @@ -62664,9 +68105,9 @@ is also divisible by 400. c:identifier="g_date_strftime" moved-to="Date.strftime"> Generates a printed representation of the date, in a -[locale][setlocale]-specific way. + filename="glib/gdate.c" + line="2625">Generates a printed representation of the date, in a +[locale](running.html#locale)-specific way. Works just like the platform's C library strftime() function, but only accepts date-related formats; time-related formats give undefined results. Date must be valid. Unlike strftime() @@ -62678,36 +68119,36 @@ addition to those implemented by the platform's C library. For example, don't expect that using g_date_strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89. - + number of characters written to the buffer, or 0 the buffer was too small + filename="glib/gdate.c" + line="2646">number of characters written to the buffer, or `0` if the buffer was too small destination buffer + filename="glib/gdate.c" + line="2627">destination buffer buffer size + filename="glib/gdate.c" + line="2628">buffer size format string + filename="glib/gdate.c" + line="2629">format string valid #GDate + filename="glib/gdate.c" + line="2630">valid #GDate @@ -62716,21 +68157,21 @@ where the C library only complies to C89. c:identifier="g_date_valid_day" moved-to="Date.valid_day"> Returns %TRUE if the day of the month is valid (a day is valid if it's + filename="glib/gdate.c" + line="441">Returns %TRUE if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive). - + %TRUE if the day is valid + filename="glib/gdate.c" + line="448">%TRUE if the day is valid day to check + filename="glib/gdate.c" + line="443">day to check @@ -62739,34 +68180,34 @@ between 1 and 31 inclusive). c:identifier="g_date_valid_dmy" moved-to="Date.valid_dmy"> Returns %TRUE if the day-month-year triplet forms a valid, existing day + filename="glib/gdate.c" + line="487">Returns %TRUE if the day-month-year triplet forms a valid, existing day in the range of days #GDate understands (Year 1 or later, no more than a few thousand years in the future). - + %TRUE if the date is a valid one + filename="glib/gdate.c" + line="497">%TRUE if the date is a valid one day + filename="glib/gdate.c" + line="489">day month + filename="glib/gdate.c" + line="490">month year + filename="glib/gdate.c" + line="491">year @@ -62775,21 +68216,21 @@ a few thousand years in the future). c:identifier="g_date_valid_julian" moved-to="Date.valid_julian"> Returns %TRUE if the Julian day is valid. Anything greater than zero + filename="glib/gdate.c" + line="472">Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit. - + %TRUE if the Julian day is valid + filename="glib/gdate.c" + line="479">%TRUE if the Julian day is valid Julian day to check + filename="glib/gdate.c" + line="474">Julian day to check @@ -62798,21 +68239,21 @@ is basically a valid Julian, though there is a 32-bit limit. c:identifier="g_date_valid_month" moved-to="Date.valid_month"> Returns %TRUE if the month value is valid. The 12 #GDateMonth + filename="glib/gdate.c" + line="411">Returns %TRUE if the month value is valid. The 12 #GDateMonth enumeration values are the only valid months. - + %TRUE if the month is valid + filename="glib/gdate.c" + line="418">%TRUE if the month is valid month + filename="glib/gdate.c" + line="413">month @@ -62821,21 +68262,21 @@ enumeration values are the only valid months. c:identifier="g_date_valid_weekday" moved-to="Date.valid_weekday"> Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration + filename="glib/gdate.c" + line="457">Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration values are the only valid weekdays. - + %TRUE if the weekday is valid + filename="glib/gdate.c" + line="464">%TRUE if the weekday is valid weekday + filename="glib/gdate.c" + line="459">weekday @@ -62844,37 +68285,37 @@ values are the only valid weekdays. c:identifier="g_date_valid_year" moved-to="Date.valid_year"> Returns %TRUE if the year is valid. Any year greater than 0 is valid, + filename="glib/gdate.c" + line="426">Returns %TRUE if the year is valid. Any year greater than 0 is valid, though there is a 16-bit limit to what #GDate will understand. - + %TRUE if the year is valid + filename="glib/gdate.c" + line="433">%TRUE if the year is valid year + filename="glib/gdate.c" + line="428">year This is a variant of g_dgettext() that allows specifying a locale + filename="glib/ggettext.c" + line="415">This is a variant of g_dgettext() that allows specifying a locale category instead of always using `LC_MESSAGES`. See g_dgettext() for more information about how this functions differs from calling dcgettext() directly. - + the translated string for the given locale category + filename="glib/ggettext.c" + line="427">the translated string for the given locale category @@ -62883,21 +68324,21 @@ dcgettext() directly. nullable="1" allow-none="1"> the translation domain to use, or %NULL to use + filename="glib/ggettext.c" + line="417">the translation domain to use, or %NULL to use the domain set with textdomain() message to translate + filename="glib/ggettext.c" + line="419">message to translate a locale category + filename="glib/ggettext.c" + line="420">a locale category @@ -62907,35 +68348,38 @@ dcgettext() directly. version="2.6" introspectable="0"> A convenience function/macro to log a debug message. The message should -typically *not* be translated to the user's language. + filename="glib/gmessages.c" + line="334">A convenience function/macro to log a debug message. -If g_log_default_handler() is used as the log handler function, a new-line +The message should typically *not* be translated to the user’s language. + +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -Such messages are suppressed by the g_log_default_handler() and -g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is -set appropriately. +Such messages are suppressed by the [func@GLib.log_default_handler] and +[func@GLib.log_writer_default] unless the `G_MESSAGES_DEBUG` or +`DEBUG_INVOCATION` environment variables are set appropriately. If you need +to set the allowed domains at runtime, use +[func@GLib.log_writer_default_set_debug_domains]. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. - +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). + format string, followed by parameters to insert - into the format string (as with printf()) + filename="glib/gmessages.c" + line="336">format string, followed by parameters to insert into the format string + (as with `printf()`) This function is a wrapper of dgettext() which does not translate + filename="glib/ggettext.c" + line="362">This function is a wrapper of dgettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale. @@ -62967,11 +68411,11 @@ cases the application should call textdomain() after initializing GTK. Applications should normally not use this function directly, but use the _() macro for translations. - + The translated string + filename="glib/ggettext.c" + line="401">The translated string @@ -62980,15 +68424,15 @@ but use the _() macro for translations. nullable="1" allow-none="1"> the translation domain to use, or %NULL to use + filename="glib/ggettext.c" + line="364">the translation domain to use, or %NULL to use the domain set with textdomain() message to translate + filename="glib/ggettext.c" + line="366">message to translate @@ -62999,8 +68443,8 @@ but use the _() macro for translations. version="2.30" throws="1"> Creates a subdirectory in the preferred directory for temporary + filename="glib/gfileutils.c" + line="1860">Creates a subdirectory in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @tmpl should be a string in the GLib file name encoding containing @@ -63011,11 +68455,11 @@ basename, no directory components are allowed. If template is Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not modified, and might thus be a read-only literal string. - + The actual name used. This string + filename="glib/gfileutils.c" + line="1878">The actual name used. This string should be freed with g_free() when not needed any longer and is is in the GLib file name encoding. In case of errors, %NULL is returned and @error will be set. @@ -63027,8 +68471,8 @@ modified, and might thus be a read-only literal string. nullable="1" allow-none="1"> Template for directory name, + filename="glib/gfileutils.c" + line="1862">Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template @@ -63036,19 +68480,19 @@ modified, and might thus be a read-only literal string. Compares two #gpointer arguments and returns %TRUE if they are equal. + filename="glib/ghash.c" + line="2500">Compares two #gpointer arguments and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using opaque pointers compared by pointer value as keys in a #GHashTable. This equality function is also appropriate for keys that are integers stored in pointers, such as `GINT_TO_POINTER (n)`. - + %TRUE if the two keys match. + filename="glib/ghash.c" + line="2513">%TRUE if the two keys match. @@ -63057,8 +68501,8 @@ stored in pointers, such as `GINT_TO_POINTER (n)`. nullable="1" allow-none="1"> a key + filename="glib/ghash.c" + line="2502">a key nullable="1" allow-none="1"> a key to compare with @v1 + filename="glib/ghash.c" + line="2503">a key to compare with @v1 Converts a gpointer to a hash value. + filename="glib/ghash.c" + line="2480">Converts a gpointer to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when using opaque pointers compared by pointer value as keys in a #GHashTable. This hash function is also appropriate for keys that are integers stored in pointers, such as `GINT_TO_POINTER (n)`. - + a hash value corresponding to the key. + filename="glib/ghash.c" + line="2492">a hash value corresponding to the key. @@ -63095,26 +68539,26 @@ stored in pointers, such as `GINT_TO_POINTER (n)`. nullable="1" allow-none="1"> a #gpointer key + filename="glib/ghash.c" + line="2482">a #gpointer key This function is a wrapper of dngettext() which does not translate + filename="glib/ggettext.c" + line="442">This function is a wrapper of dngettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale. See g_dgettext() for details of how this differs from dngettext() proper. - + The translated string + filename="glib/ggettext.c" + line="457">The translated string @@ -63123,88 +68567,88 @@ proper. nullable="1" allow-none="1"> the translation domain to use, or %NULL to use + filename="glib/ggettext.c" + line="444">the translation domain to use, or %NULL to use the domain set with textdomain() message to translate + filename="glib/ggettext.c" + line="446">message to translate plural form of the message + filename="glib/ggettext.c" + line="447">plural form of the message the quantity for which translation is needed + filename="glib/ggettext.c" + line="448">the quantity for which translation is needed Compares the two #gdouble values being pointed to and returns + filename="glib/ghash.c" + line="2654">Compares the two #gdouble values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL pointers to doubles as keys in a #GHashTable. - + %TRUE if the two keys match. + filename="glib/ghash.c" + line="2665">%TRUE if the two keys match. a pointer to a #gdouble key + filename="glib/ghash.c" + line="2656">a pointer to a #gdouble key a pointer to a #gdouble key to compare with @v1 + filename="glib/ghash.c" + line="2657">a pointer to a #gdouble key to compare with @v1 Converts a pointer to a #gdouble to a hash value. + filename="glib/ghash.c" + line="2676">Converts a pointer to a #gdouble to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL pointers to doubles as keys in a #GHashTable. - + a hash value corresponding to the key. + filename="glib/ghash.c" + line="2685">a hash value corresponding to the key. a pointer to a #gdouble key + filename="glib/ghash.c" + line="2678">a pointer to a #gdouble key This function is a variant of g_dgettext() which supports + filename="glib/ggettext.c" + line="187">This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in @msgctxtid. @@ -63217,11 +68661,11 @@ with dgettext() proper. Applications should normally not use this function directly, but use the C_() macro for translations with context. - + The translated string + filename="glib/ggettext.c" + line="209">The translated string @@ -63230,30 +68674,30 @@ but use the C_() macro for translations with context. nullable="1" allow-none="1"> the translation domain to use, or %NULL to use + filename="glib/ggettext.c" + line="189">the translation domain to use, or %NULL to use the domain set with textdomain() a combined message context and message id, separated + filename="glib/ggettext.c" + line="191">a combined message context and message id, separated by a \004 character the offset of the message id in @msgctxid + filename="glib/ggettext.c" + line="193">the offset of the message id in @msgctxid This function is a variant of g_dgettext() which supports + filename="glib/ggettext.c" + line="255">This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in @msgctxtid. @@ -63263,11 +68707,11 @@ with dgettext() proper. This function differs from C_() in that it is not a macro and thus you may use non-string-literals as context and msgid arguments. - + The translated string + filename="glib/ggettext.c" + line="273">The translated string @@ -63276,21 +68720,21 @@ thus you may use non-string-literals as context and msgid arguments. nullable="1" allow-none="1"> the translation domain to use, or %NULL to use + filename="glib/ggettext.c" + line="257">the translation domain to use, or %NULL to use the domain set with textdomain() the message context + filename="glib/ggettext.c" + line="259">the message context the message + filename="glib/ggettext.c" + line="260">the message @@ -63299,14 +68743,14 @@ thus you may use non-string-literals as context and msgid arguments. c:identifier="g_environ_getenv" version="2.32"> Returns the value of the environment variable @variable in the + filename="glib/genviron.c" + line="83">Returns the value of the environment variable @variable in the provided list @envp. - + the value of the environment variable, or %NULL if + filename="glib/genviron.c" + line="93">the value of the environment variable, or %NULL if the environment variable is not set in @envp. The returned string is owned by @envp, and will be freed if @variable is set or unset again. @@ -63318,8 +68762,8 @@ provided list @envp. nullable="1" allow-none="1"> + filename="glib/genviron.c" + line="85"> an environment list (eg, as returned from g_get_environ()), or %NULL for an empty environment list @@ -63328,8 +68772,8 @@ provided list @envp. the environment variable to get + filename="glib/genviron.c" + line="88">the environment variable to get @@ -63338,14 +68782,14 @@ provided list @envp. c:identifier="g_environ_setenv" version="2.32"> Sets the environment variable @variable in the provided list + filename="glib/genviron.c" + line="115">Sets the environment variable @variable in the provided list @envp to @value. - + + filename="glib/genviron.c" + line="129"> the updated environment list. Free it using g_strfreev(). @@ -63357,8 +68801,8 @@ provided list @envp. nullable="1" allow-none="1"> + filename="glib/genviron.c" + line="117"> an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list @@ -63368,21 +68812,21 @@ provided list @envp. the environment variable to set, must not + filename="glib/genviron.c" + line="121">the environment variable to set, must not contain '=' the value for to set the variable to + filename="glib/genviron.c" + line="123">the value for to set the variable to whether to change the variable if it already exists + filename="glib/genviron.c" + line="124">whether to change the variable if it already exists @@ -63391,14 +68835,14 @@ provided list @envp. c:identifier="g_environ_unsetenv" version="2.32"> Removes the environment variable @variable from the provided + filename="glib/genviron.c" + line="203">Removes the environment variable @variable from the provided environment @envp. - + + filename="glib/genviron.c" + line="214"> the updated environment list. Free it using g_strfreev(). @@ -63410,8 +68854,8 @@ environment @envp. nullable="1" allow-none="1"> + filename="glib/genviron.c" + line="205"> an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list @@ -63420,8 +68864,8 @@ environment @envp. the environment variable to remove, must not + filename="glib/genviron.c" + line="208">the environment variable to remove, must not contain '=' @@ -63429,514 +68873,202 @@ environment @envp. A convenience function/macro to log an error message. The message should -typically *not* be translated to the user's language. + filename="glib/gmessages.c" + line="280">A convenience function/macro to log an error message. -This is not intended for end user error reporting. Use of #GError is +The message should typically *not* be translated to the user’s language. + +This is not intended for end user error reporting. Use of [type@GLib.Error] is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error. -Error messages are always fatal, resulting in a call to G_BREAKPOINT() +Error messages are always fatal, resulting in a call to [func@GLib.BREAKPOINT] to terminate the application. This function will -result in a core dump; don't use it for errors you expect. +result in a core dump; don’t use it for errors you expect. Using this function indicates a bug in your program, i.e. an assertion failure. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. - +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). + format string, followed by parameters to insert - into the format string (as with printf()) + filename="glib/gmessages.c" + line="282">format string, followed by parameters to insert into the format string + (as with `printf()`) - - GLib provides a standard method of reporting errors from a called -function to the calling code. (This is the same problem solved by -exceptions in other languages.) It's important to understand that -this method is both a data type (the #GError struct) and a [set of -rules][gerror-rules]. If you use #GError incorrectly, then your code will not -properly interoperate with other code that uses #GError, and users -of your API will probably get confused. In most cases, [using #GError is -preferred over numeric error codes][gerror-comparison], but there are -situations where numeric error codes are useful for performance. - -First and foremost: #GError should only be used to report recoverable -runtime errors, never to report programming errors. If the programmer -has screwed up, then you should use g_warning(), g_return_if_fail(), -g_assert(), g_error(), or some similar facility. (Incidentally, -remember that the g_error() function should only be used for -programming errors, it should not be used to print any error -reportable via #GError.) - -Examples of recoverable runtime errors are "file not found" or -"failed to parse input." Examples of programming errors are "NULL -passed to strcmp()" or "attempted to free the same pointer twice." -These two kinds of errors are fundamentally different: runtime errors -should be handled or reported to the user, programming errors should -be eliminated by fixing the bug in the program. This is why most -functions in GLib and GTK do not use the #GError facility. - -Functions that can fail take a return location for a #GError as their -last argument. On error, a new #GError instance will be allocated and -returned to the caller via this argument. For example: -|[<!-- language="C" --> -gboolean g_file_get_contents (const gchar *filename, - gchar **contents, - gsize *length, - GError **error); -]| -If you pass a non-%NULL value for the `error` argument, it should -point to a location where an error can be placed. For example: -|[<!-- language="C" --> -gchar *contents; -GError *err = NULL; - -g_file_get_contents ("foo.txt", &contents, NULL, &err); -g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); -if (err != NULL) - { - // Report error to user, and free error - g_assert (contents == NULL); - fprintf (stderr, "Unable to read file: %s\n", err->message); - g_error_free (err); - } -else - { - // Use file contents - g_assert (contents != NULL); - } -]| -Note that `err != NULL` in this example is a reliable indicator -of whether g_file_get_contents() failed. Additionally, -g_file_get_contents() returns a boolean which -indicates whether it was successful. - -Because g_file_get_contents() returns %FALSE on failure, if you -are only interested in whether it failed and don't need to display -an error message, you can pass %NULL for the @error argument: -|[<!-- language="C" --> -if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors - // no error occurred - ; -else - // error - ; -]| - -The #GError object contains three fields: @domain indicates the module -the error-reporting function is located in, @code indicates the specific -error that occurred, and @message is a user-readable error message with -as many details as possible. Several functions are provided to deal -with an error received from a called function: g_error_matches() -returns %TRUE if the error matches a given domain and code, -g_propagate_error() copies an error into an error location (so the -calling function will receive it), and g_clear_error() clears an -error location by freeing the error and resetting the location to -%NULL. To display an error to the user, simply display the @message, -perhaps along with additional context known only to the calling -function (the file being opened, or whatever - though in the -g_file_get_contents() case, the @message already contains a filename). - -Since error messages may be displayed to the user, they need to be valid -UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in -particular when formatting error messages with filenames, which are in -the 'filename encoding', and need to be turned into UTF-8 using -g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid(). - -Note, however, that many error messages are too technical to display to the -user in an application, so prefer to use g_error_matches() to categorize errors -from called functions, and build an appropriate error message for the context -within your application. Error messages from a #GError are more appropriate -to be printed in system logs or on the command line. They are typically -translated. - -When implementing a function that can report errors, the basic -tool is g_set_error(). Typically, if a fatal error occurs you -want to g_set_error(), then return immediately. g_set_error() -does nothing if the error location passed to it is %NULL. -Here's an example: -|[<!-- language="C" --> -gint -foo_open_file (GError **error) -{ - gint fd; - int saved_errno; - - g_return_val_if_fail (error == NULL || *error == NULL, -1); - - fd = open ("file.txt", O_RDONLY); - saved_errno = errno; - - if (fd < 0) - { - g_set_error (error, - FOO_ERROR, // error domain - FOO_ERROR_BLAH, // error code - "Failed to open file: %s", // error message format string - g_strerror (saved_errno)); - return -1; - } - else - return fd; -} -]| - -Things are somewhat more complicated if you yourself call another -function that can report a #GError. If the sub-function indicates -fatal errors in some way other than reporting a #GError, such as -by returning %TRUE on success, you can simply do the following: -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - if (!sub_function_that_can_fail (err)) - { - // assert that error was set by the sub-function - g_assert (err == NULL || *err != NULL); - return FALSE; - } - - // otherwise continue, no error occurred - g_assert (err == NULL || *err == NULL); -} -]| - -If the sub-function does not indicate errors other than by -reporting a #GError (or if its return value does not reliably indicate -errors) you need to create a temporary #GError -since the passed-in one may be %NULL. g_propagate_error() is -intended for use in this case. -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - GError *tmp_error; - - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - tmp_error = NULL; - sub_function_that_can_fail (&tmp_error); - - if (tmp_error != NULL) - { - // store tmp_error in err, if err != NULL, - // otherwise call g_error_free() on tmp_error - g_propagate_error (err, tmp_error); - return FALSE; - } - - // otherwise continue, no error occurred -} -]| - -Error pileups are always a bug. For example, this code is incorrect: -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - GError *tmp_error; - - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - tmp_error = NULL; - sub_function_that_can_fail (&tmp_error); - other_function_that_can_fail (&tmp_error); - - if (tmp_error != NULL) - { - g_propagate_error (err, tmp_error); - return FALSE; - } -} -]| -@tmp_error should be checked immediately after sub_function_that_can_fail(), -and either cleared or propagated upward. The rule is: after each error, -you must either handle the error, or return it to the calling function. - -Note that passing %NULL for the error location is the equivalent -of handling an error by always doing nothing about it. So the -following code is fine, assuming errors in sub_function_that_can_fail() -are not fatal to my_function_that_can_fail(): -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - GError *tmp_error; - - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - sub_function_that_can_fail (NULL); // ignore errors - - tmp_error = NULL; - other_function_that_can_fail (&tmp_error); - - if (tmp_error != NULL) - { - g_propagate_error (err, tmp_error); - return FALSE; - } -} -]| - -Note that passing %NULL for the error location ignores errors; -it's equivalent to -`try { sub_function_that_can_fail (); } catch (...) {}` -in C++. It does not mean to leave errors unhandled; it means -to handle them by doing nothing. - -Error domains and codes are conventionally named as follows: - -- The error domain is called <NAMESPACE>_<MODULE>_ERROR, - for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - |[<!-- language="C" --> - #define G_SPAWN_ERROR g_spawn_error_quark () - - G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error) - ]| - -- The quark function for the error domain is called - <namespace>_<module>_error_quark, - for example g_spawn_error_quark() or g_thread_error_quark(). - -- The error codes are in an enumeration called - <Namespace><Module>Error; - for example, #GThreadError or #GSpawnError. - -- Members of the error code enumeration are called - <NAMESPACE>_<MODULE>_ERROR_<CODE>, - for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. - -- If there's a "generic" or "unknown" error code for unrecoverable - errors it doesn't make sense to distinguish with specific codes, - it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, - for example %G_SPAWN_ERROR_FAILED. In the case of error code - enumerations that may be extended in future releases, you should - generally not handle this error code explicitly, but should - instead treat any unrecognized error code as equivalent to - FAILED. - -## Comparison of #GError and traditional error handling # {#gerror-comparison} - -#GError has several advantages over traditional numeric error codes: -importantly, tools like -[gobject-introspection](https://developer.gnome.org/gi/stable/) understand -#GErrors and convert them to exceptions in bindings; the message includes -more information than just a code; and use of a domain helps prevent -misinterpretation of error codes. - -#GError has disadvantages though: it requires a memory allocation, and -formatting the error message string has a performance overhead. This makes it -unsuitable for use in retry loops where errors are a common case, rather than -being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these -overheads in the normal control flow. String formatting overhead can be -eliminated by using g_set_error_literal() in some cases. - -These performance issues can be compounded if a function wraps the #GErrors -returned by the functions it calls: this multiplies the number of allocations -and string formatting operations. This can be partially mitigated by using -g_prefix_error(). - -## Rules for use of #GError # {#gerror-rules} - -Summary of rules for use of #GError: - -- Do not report programming errors via #GError. - -- The last argument of a function that returns an error should - be a location where a #GError can be placed (i.e. `GError **error`). - If #GError is used with varargs, the `GError**` should be the last - argument before the `...`. - -- The caller may pass %NULL for the `GError**` if they are not interested - in details of the exact error that occurred. - -- If %NULL is passed for the `GError**` argument, then errors should - not be returned to the caller, but your function should still - abort and return if an error occurs. That is, control flow should - not be affected by whether the caller wants to get a #GError. - -- If a #GError is reported, then your function by definition had a - fatal failure and did not complete whatever it was supposed to do. - If the failure was not fatal, then you handled it and you should not - report it. If it was fatal, then you must report it and discontinue - whatever you were doing immediately. - -- If a #GError is reported, out parameters are not guaranteed to - be set to any defined value. - -- A `GError*` must be initialized to %NULL before passing its address - to a function that can report errors. - -- #GError structs must not be stack-allocated. - -- "Piling up" errors is always a bug. That is, if you assign a - new #GError to a `GError*` that is non-%NULL, thus overwriting - the previous error, it indicates that you should have aborted - the operation instead of continuing. If you were able to continue, - you should have cleared the previous error with g_clear_error(). - g_set_error() will complain if you pile up errors. - -- By convention, if you return a boolean value indicating success - then %TRUE means success and %FALSE means failure. Avoid creating - functions which have a boolean return value and a #GError parameter, - but where the boolean does something other than signal whether the - #GError is set. Among other problems, it requires C callers to allocate - a temporary error. Instead, provide a `gboolean *` out parameter. - There are functions in GLib itself such as g_key_file_has_key() that - are hard to use because of this. If %FALSE is returned, the error must - be set to a non-%NULL value. One exception to this is that in situations - that are already considered to be undefined behaviour (such as when a - g_return_val_if_fail() check fails), the error need not be set. - Instead of checking separately whether the error is set, callers - should ensure that they do not provoke undefined behaviour, then - assume that the error will be set on failure. - -- A %NULL return value is also frequently used to mean that an error - occurred. You should make clear in your documentation whether %NULL - is a valid return value in non-error cases; if %NULL is a valid value, - then users must check whether an error was returned to see if the - function succeeded. - -- When implementing a function that can report errors, you may want - to add a check at the top of your function that the error return - location is either %NULL or contains a %NULL error (e.g. - `g_return_if_fail (error == NULL || *error == NULL);`). - -## Extended #GError Domains # {#gerror-extended-domains} - -Since GLib 2.68 it is possible to extend the #GError type. This is -done with the G_DEFINE_EXTENDED_ERROR() macro. To create an -extended #GError type do something like this in the header file: -|[<!-- language="C" --> -typedef enum -{ - MY_ERROR_BAD_REQUEST, -} MyError; -#define MY_ERROR (my_error_quark ()) -GQuark my_error_quark (void); -int -my_error_get_parse_error_id (GError *error); -const char * -my_error_get_bad_request_details (GError *error); -]| -and in implementation: -|[<!-- language="C" --> -typedef struct -{ - int parse_error_id; - char *bad_request_details; -} MyErrorPrivate; - -static void -my_error_private_init (MyErrorPrivate *priv) -{ - priv->parse_error_id = -1; - // No need to set priv->bad_request_details to NULL, - // the struct is initialized with zeros. -} + + This function registers an extended #GError domain. +@error_type_name will be duplicated. Otherwise does the same as +g_error_domain_register_static(). + + + #GQuark representing the error domain + + + + + string to create a #GQuark from + + + + size of the private error data in bytes + + + + function initializing fields of the private error data + + + + function copying fields of the private error data + + + + function freeing fields of the private error data + + + + + + This function registers an extended #GError domain. -static void -my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv) -{ - dest_priv->parse_error_id = src_priv->parse_error_id; - dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details); -} +@error_type_name should not be freed. @error_type_private_size must +be greater than 0. -static void -my_error_private_clear (MyErrorPrivate *priv) -{ - g_free (priv->bad_request_details); -} +@error_type_init receives an initialized #GError and should then initialize +the private data. -// This defines the my_error_get_private and my_error_quark functions. -G_DEFINE_EXTENDED_ERROR (MyError, my_error) +@error_type_copy is a function that receives both original and a copy +#GError and should copy the fields of the private error data. The standard +#GError fields are already handled. -int -my_error_get_parse_error_id (GError *error) -{ - MyErrorPrivate *priv = my_error_get_private (error); - g_return_val_if_fail (priv != NULL, -1); - return priv->parse_error_id; -} +@error_type_clear receives the pointer to the error, and it should free the +fields of the private error data. It should not free the struct itself though. -const char * -my_error_get_bad_request_details (GError *error) -{ - MyErrorPrivate *priv = my_error_get_private (error); - g_return_val_if_fail (priv != NULL, NULL); - g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL); - return priv->bad_request_details; -} +Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it +already takes care of passing valid information to this function. + + + #GQuark representing the error domain + + + + + static string to create a #GQuark from + + + + size of the private error data in bytes + + + + function initializing fields of the private error data + + + + function copying fields of the private error data + + + + function freeing fields of the private error data + + + + + + Mark every file descriptor equal to or greater than @lowfd to be closed +at the next `execve()` or similar, as if via the `FD_CLOEXEC` flag. -static void -my_error_set_bad_request (GError **error, - const char *reason, - int error_id, - const char *details) -{ - MyErrorPrivate *priv; - g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason); - if (error != NULL && *error != NULL) - { - priv = my_error_get_private (error); - g_return_val_if_fail (priv != NULL, NULL); - priv->parse_error_id = error_id; - priv->bad_request_details = g_strdup (details); - } -} -]| -An example of use of the error could be: -|[<!-- language="C" --> -gboolean -send_request (GBytes *request, GError **error) -{ - ParseFailedStatus *failure = validate_request (request); - if (failure != NULL) - { - my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details); - parse_failed_status_free (failure); - return FALSE; - } +Typically @lowfd will be 3, to leave standard input, standard output +and standard error open after exec. - return send_one (request, error); -} -]| +This is the same as Linux `close_range (lowfd, ~0U, CLOSE_RANGE_CLOEXEC)`, +but portable to other OSs and to older versions of Linux. -Please note that if you are a library author and your library -exposes an existing error domain, then you can't make this error -domain an extended one without breaking ABI. This is because -earlier it was possible to create an error with this error domain -on the stack and then copy it with g_error_copy(). If the new -version of your library makes the error domain an extended one, -then g_error_copy() called by code that allocated the error on the -stack will try to copy more data than it used to, which will lead -to undefined behavior. You must not stack-allocate errors with an -extended error domain, and it is bad practice to stack-allocate any -other #GErrors. - -Extended error domains in unloadable plugins/modules are not -supported. - +This function is async-signal safe, making it safe to call from a +signal handler or a [callback@GLib.SpawnChildSetupFunc], as long as @lowfd is +non-negative. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + + + 0 on success, -1 with errno set on error + + + + + Minimum fd to act on, which must be non-negative + + + + Gets a #GFileError constant based on the passed-in @err_no. + filename="glib/gfileutils.c" + line="478">Gets a #GFileError constant based on the passed-in @err_no. For example, if you pass in `EEXIST` this function returns %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably @@ -63945,18 +69077,18 @@ assume that all #GFileError values will exist. Normally a #GFileError value goes into a #GError returned from a function that manipulates files. So you would use g_file_error_from_errno() when constructing a #GError. - + #GFileError corresponding to the given @err_no + filename="glib/gfileutils.c" + line="492">#GFileError corresponding to the given @err_no an "errno" value + filename="glib/gfileutils.c" + line="480">an "errno" value @@ -63970,8 +69102,8 @@ g_file_error_from_errno() when constructing a #GError. c:identifier="g_file_get_contents" throws="1"> Reads an entire file into allocated memory, with good error + filename="glib/gfileutils.c" + line="993">Reads an entire file into allocated memory, with good error checking. If the call was successful, it returns %TRUE and sets @contents to the file @@ -63981,18 +69113,18 @@ stored in @contents will be nul-terminated, so for text files you can pass %FALSE and sets @error. The error domain is %G_FILE_ERROR. Possible error codes are those in the #GFileError enumeration. In the error case, @contents is set to %NULL and @length is set to zero. - + %TRUE on success, %FALSE if an error occurred + filename="glib/gfileutils.c" + line="1012">%TRUE on success, %FALSE if an error occurred name of a file to read contents from, in the GLib file name encoding + filename="glib/gfileutils.c" + line="995">name of a file to read contents from, in the GLib file name encoding location to store an allocated string, use g_free() to free + filename="glib/gfileutils.c" + line="996">location to store an allocated string, use g_free() to free the returned string @@ -64013,16 +69145,16 @@ codes are those in the #GFileError enumeration. In the error case, transfer-ownership="full" nullable="1"> location to store length in bytes of the contents, or %NULL + filename="glib/gfileutils.c" + line="998">location to store length in bytes of the contents, or %NULL Opens a file for writing in the preferred directory for temporary + filename="glib/gfileutils.c" + line="1804">Opens a file for writing in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @tmpl should be a string in the GLib file name encoding containing @@ -64038,11 +69170,11 @@ Upon success, and if @name_used is non-%NULL, the actual name used is returned in @name_used. This string should be freed with g_free() when not needed any longer. The returned name is in the GLib file name encoding. - + A file handle (as from open()) to the file opened for + filename="glib/gfileutils.c" + line="1829">A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and @error will be set. @@ -64054,8 +69186,8 @@ name encoding. nullable="1" allow-none="1"> Template for file name, as in + filename="glib/gfileutils.c" + line="1806">Template for file name, as in g_mkstemp(), basename only, or %NULL for a default template @@ -64064,8 +69196,8 @@ name encoding. caller-allocates="0" transfer-ownership="full"> location to store actual name used, + filename="glib/gfileutils.c" + line="1808">location to store actual name used, or %NULL @@ -64076,8 +69208,8 @@ name encoding. version="2.4" throws="1"> Reads the contents of the symbolic link @filename like the POSIX + filename="glib/gfileutils.c" + line="2307">Reads the contents of the symbolic link @filename like the POSIX `readlink()` function. The returned string is in the encoding used for filenames. Use @@ -64100,19 +69232,19 @@ if (!g_path_is_absolute (link_target)) link_target = g_steal_pointer (&absolute_link_target); } ]| - + A newly-allocated string with + filename="glib/gfileutils.c" + line="2336">A newly-allocated string with the contents of the symbolic link, or %NULL if an error occurred. the symbolic link + filename="glib/gfileutils.c" + line="2309">the symbolic link @@ -64122,38 +69254,38 @@ if (!g_path_is_absolute (link_target)) version="2.8" throws="1"> Writes all of @contents to a file named @filename. This is a convenience + filename="glib/gfileutils.c" + line="1230">Writes all of @contents to a file named @filename. This is a convenience wrapper around calling g_file_set_contents_full() with `flags` set to `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and `mode` set to `0666`. - + %TRUE on success, %FALSE if an error occurred + filename="glib/gfileutils.c" + line="1243">%TRUE on success, %FALSE if an error occurred name of a file to write @contents to, in the GLib file name + filename="glib/gfileutils.c" + line="1232">name of a file to write @contents to, in the GLib file name encoding string to write to the file + filename="glib/gfileutils.c" + line="1234">string to write to the file length of @contents, or -1 if @contents is a nul-terminated string + filename="glib/gfileutils.c" + line="1235">length of @contents, or -1 if @contents is a nul-terminated string @@ -64163,8 +69295,8 @@ wrapper around calling g_file_set_contents_full() with `flags` set to version="2.66" throws="1"> Writes all of @contents to a file named @filename, with good error checking. + filename="glib/gfileutils.c" + line="1259">Writes all of @contents to a file named @filename, with good error checking. If a file called @filename already exists it will be overwritten. @flags control the properties of the write operation: whether it’s atomic, @@ -64218,53 +69350,53 @@ to 7 characters to @filename. If the file didn’t exist before and is created, it will be given the permissions from @mode. Otherwise, the permissions of the existing file may be changed to @mode depending on @flags, or they may remain unchanged. - + %TRUE on success, %FALSE if an error occurred + filename="glib/gfileutils.c" + line="1324">%TRUE on success, %FALSE if an error occurred name of a file to write @contents to, in the GLib file name + filename="glib/gfileutils.c" + line="1261">name of a file to write @contents to, in the GLib file name encoding string to write to the file + filename="glib/gfileutils.c" + line="1263">string to write to the file length of @contents, or -1 if @contents is a nul-terminated string + filename="glib/gfileutils.c" + line="1264">length of @contents, or -1 if @contents is a nul-terminated string flags controlling the safety vs speed of the operation + filename="glib/gfileutils.c" + line="1265">flags controlling the safety vs speed of the operation file mode, as passed to `open()`; typically this will be `0666` + filename="glib/gfileutils.c" + line="1266">file mode, as passed to `open()`; typically this will be `0666` Returns %TRUE if any of the tests in the bitfield @test are + filename="glib/gfileutils.c" + line="257">Returns %TRUE if any of the tests in the bitfield @test are %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` will return %TRUE if the file exists; the check whether it's a directory doesn't matter since the existence test is %TRUE. With @@ -64323,25 +69455,25 @@ On Windows, there are no symlinks, so testing for %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and its name indicates that it is executable, checking for well-known extensions and those listed in the `PATHEXT` environment variable. - + whether a test was %TRUE + filename="glib/gfileutils.c" + line="323">whether a test was %TRUE a filename to test in the + filename="glib/gfileutils.c" + line="259">a filename to test in the GLib file name encoding bitfield of #GFileTest flags + filename="glib/gfileutils.c" + line="261">bitfield of #GFileTest flags @@ -64350,8 +69482,8 @@ extensions and those listed in the `PATHEXT` environment variable. c:identifier="g_filename_display_basename" version="2.6"> Returns the display basename for the particular filename, guaranteed + filename="glib/gconvert.c" + line="1827">Returns the display basename for the particular filename, guaranteed to be valid UTF-8. The display name might not be identical to the filename, for instance there might be problems converting it to UTF-8, and some files can be translated in the display. @@ -64367,19 +69499,19 @@ translation of well known locations can be done. This function is preferred over g_filename_display_name() if you know the whole path, as it allows translation. - + a newly allocated string containing + filename="glib/gconvert.c" + line="1849">a newly allocated string containing a rendition of the basename of the filename in valid UTF-8 an absolute pathname in the + filename="glib/gconvert.c" + line="1829">an absolute pathname in the GLib file name encoding @@ -64389,8 +69521,8 @@ whole path, as it allows translation. c:identifier="g_filename_display_name" version="2.6"> Converts a filename into a valid UTF-8 string. The conversion is + filename="glib/gconvert.c" + line="1868">Converts a filename into a valid UTF-8 string. The conversion is not necessarily reversible, so you should keep the original around and use the return value of this function only for display purposes. Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL @@ -64405,19 +69537,19 @@ encoding. If you know the whole pathname of the file you should use g_filename_display_basename(), since that allows location-based translation of filenames. - + a newly allocated string containing + filename="glib/gconvert.c" + line="1889">a newly allocated string containing a rendition of the filename in valid UTF-8 a pathname hopefully in the + filename="glib/gconvert.c" + line="1870">a pathname hopefully in the GLib file name encoding @@ -64427,27 +69559,27 @@ translation of filenames. c:identifier="g_filename_from_uri" throws="1"> Converts an escaped ASCII-encoded URI to a local filename in the + filename="glib/gconvert.c" + line="1563">Converts an escaped ASCII-encoded URI to a local filename in the encoding used for filenames. Since GLib 2.78, the query string and fragment can be present in the URI, but are not part of the resulting filename. We take inspiration from https://url.spec.whatwg.org/#file-state, but we don't support the entire standard. - + a newly-allocated string holding + filename="glib/gconvert.c" + line="1580">a newly-allocated string holding the resulting filename, or %NULL on an error. a uri describing a filename (escaped, encoded in ASCII). + filename="glib/gconvert.c" + line="1565">a uri describing a filename (escaped, encoded in ASCII). optional="1" allow-none="1"> Location to store hostname for the URI. + filename="glib/gconvert.c" + line="1566">Location to store hostname for the URI. If there is no hostname in the URI, %NULL will be stored in this location. @@ -64470,36 +69602,36 @@ but we don't support the entire standard. c:identifier="g_filename_from_utf8" throws="1"> Converts a string from UTF-8 to the encoding GLib uses for + filename="glib/gconvert.c" + line="1238">Converts a string from UTF-8 to the encoding GLib uses for filenames. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on the -[current locale][setlocale]. +[current locale](running.html#locale). The input string shall not contain nul characters even if the @len argument is positive. A nul character found inside the string will result in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is not UTF-8 and the conversion output contains a nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. - + + filename="glib/gconvert.c" + line="1267"> The converted string, or %NULL on an error. a UTF-8 encoded string. + filename="glib/gconvert.c" + line="1240">a UTF-8 encoded string. the length of the string, or -1 if the string is + filename="glib/gconvert.c" + line="1241">the length of the string, or -1 if the string is nul-terminated. @@ -64510,8 +69642,8 @@ not UTF-8 and the conversion output contains a nul character, the error optional="1" allow-none="1"> location to store the number of bytes in + filename="glib/gconvert.c" + line="1243">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -64528,8 +69660,8 @@ not UTF-8 and the conversion output contains a nul character, the error optional="1" allow-none="1"> the number of bytes stored in + filename="glib/gconvert.c" + line="1251">the number of bytes stored in the output buffer (not including the terminating nul). @@ -64539,22 +69671,22 @@ not UTF-8 and the conversion output contains a nul character, the error c:identifier="g_filename_to_uri" throws="1"> Converts an absolute filename to an escaped ASCII-encoded URI, with the path + filename="glib/gconvert.c" + line="1713">Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396. - + a newly-allocated string holding the resulting + filename="glib/gconvert.c" + line="1725">a newly-allocated string holding the resulting URI, or %NULL on an error. an absolute filename specified in the GLib file + filename="glib/gconvert.c" + line="1715">an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows @@ -64564,8 +69696,8 @@ component following Section 3.3. of RFC 2396. nullable="1" allow-none="1"> A UTF-8 encoded hostname, or %NULL for none. + filename="glib/gconvert.c" + line="1718">A UTF-8 encoded hostname, or %NULL for none. @@ -64574,11 +69706,11 @@ component following Section 3.3. of RFC 2396. c:identifier="g_filename_to_utf8" throws="1"> Converts a string which is in the encoding used by GLib for + filename="glib/gconvert.c" + line="1183">Converts a string which is in the encoding used by GLib for filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 for filenames; on other platforms, this function indirectly depends on -the [current locale][setlocale]. +the [current locale](running.html#locale). The input string shall not contain nul characters even if the @len argument is positive. A nul character found inside the string will result @@ -64587,24 +69719,24 @@ If the source encoding is not UTF-8 and the conversion output contains a nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. Use g_convert() to produce output that may contain embedded nul characters. - + The converted string, or %NULL on an error. + filename="glib/gconvert.c" + line="1216">The converted string, or %NULL on an error. a string in the encoding for filenames + filename="glib/gconvert.c" + line="1185">a string in the encoding for filenames the length of the string, or -1 if the string is + filename="glib/gconvert.c" + line="1186">the length of the string, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) @@ -64617,8 +69749,8 @@ may contain embedded nul characters. optional="1" allow-none="1"> location to store the number of bytes in the + filename="glib/gconvert.c" + line="1190">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -64635,52 +69767,18 @@ may contain embedded nul characters. optional="1" allow-none="1"> the number of bytes stored in the output + filename="glib/gconvert.c" + line="1198">the number of bytes stored in the output buffer (not including the terminating nul). - - Do not use these APIs unless you are porting a POSIX application to Windows. -A more high-level file access API is provided as GIO — see the documentation -for #GFile. - -There is a group of functions which wrap the common POSIX functions -dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(), -g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these -wrappers is to make it possible to handle file names with any Unicode -characters in them on Windows without having to use ifdefs and the -wide character API in the application code. - -On some Unix systems, these APIs may be defined as identical to their POSIX -counterparts. For this reason, you must check for and include the necessary -header files (such as `fcntl.h`) before using functions like g_creat(). You -must also define the relevant feature test macros. - -The pathname argument should be in the GLib file name encoding. -On POSIX this is the actual on-disk encoding which might correspond -to the locale settings of the process (or the `G_FILENAME_ENCODING` -environment variable), or not. - -On Windows the GLib file name encoding is UTF-8. Note that the -Microsoft C library does not use UTF-8, but has separate APIs for -current system code page and wide characters (UTF-16). The GLib -wrappers call the wide character API if present (on modern Windows -systems), otherwise convert to/from the system code page. - -Another group of functions allows to open and read directories -in the GLib file name encoding. These are g_dir_open(), -g_dir_read_name(), g_dir_rewind(), g_dir_close(). - Locates the first executable named @program in the user's path, in the + filename="glib/gutils.c" + line="237">Locates the first executable named @program in the user's path, in the same way that execvp() would locate it. Returns an allocated string with the absolute path name, or %NULL if the program is not found in the path. If @program is already an absolute path, returns a copy of @@ -64697,27 +69795,70 @@ Windows 32-bit system directory, then in the Windows directory, and finally in the directories in the `PATH` environment variable. If the program is found, the return value contains the full name including the type suffix. - + a newly-allocated + filename="glib/gutils.c" + line="259">a newly-allocated string with the absolute path, or %NULL a program name in the GLib file name encoding + filename="glib/gutils.c" + line="239">a program name in the GLib file name encoding + + + + + + A wrapper for the stdio `fopen()` function. The `fopen()` function +opens a file and associates a new stream with it. + +Because file descriptors are specific to the C library on Windows, +and a file descriptor is part of the `FILE` struct, the `FILE*` returned +by this function makes sense only to functions in the same C library. +Thus if the GLib-using code uses a different C library than GLib does, +the FILE* returned by this function cannot be passed to C library +functions like `fprintf()` or `fread()`. + +See your C library manual for more details about `fopen()`. + +As `close()` and `fclose()` are part of the C library, this implies that it is +currently impossible to close a file if the application C library and the C library +used by GLib are different. Convenience functions like g_file_set_contents_full() +avoid this problem. + + + A `FILE*` if the file was successfully opened, or %NULL if + an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + a string describing the mode in which the file should be opened + + Formats a size (for example the size of a file) into a human readable + filename="glib/gutils.c" + line="2880">Formats a size (for example the size of a file) into a human readable string. Sizes are rounded to the nearest size prefix (kB, MB, GB) and are displayed rounded to the nearest tenth. E.g. the file size 3292528 bytes will be converted into the string "3.2 MB". The returned string @@ -64730,19 +69871,19 @@ This string should be freed with g_free() when not needed any longer. See g_format_size_full() for more options about how the size might be formatted. - + a newly-allocated formatted string containing + filename="glib/gutils.c" + line="2898">a newly-allocated formatted string containing a human readable file size a size in bytes + filename="glib/gutils.c" + line="2882">a size in bytes @@ -64753,8 +69894,8 @@ formatted. deprecated="1" deprecated-version="2.30"> Formats a size (for example the size of a file) into a human + filename="glib/gutils.c" + line="3178">Formats a size (for example the size of a file) into a human readable string. Sizes are rounded to the nearest size prefix (KB, MB, GB) and are displayed rounded to the nearest tenth. E.g. the file size 3292528 bytes will be converted into the @@ -64765,19 +69906,19 @@ The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). This string should be freed with g_free() when not needed any longer. This function is broken due to its use of SI suffixes to denote IEC units. Use g_format_size() instead. - + a newly-allocated formatted string + filename="glib/gutils.c" + line="3192">a newly-allocated formatted string containing a human readable file size a size in bytes + filename="glib/gutils.c" + line="3180">a size in bytes @@ -64786,30 +69927,30 @@ This string should be freed with g_free() when not needed any longer. c:identifier="g_format_size_full" version="2.30"> Formats a size. + filename="glib/gutils.c" + line="2933">Formats a size. This function is similar to g_format_size() but allows for flags that modify the output. See #GFormatSizeFlags. - + a newly-allocated formatted string + filename="glib/gutils.c" + line="2943">a newly-allocated formatted string containing a human readable file size a size in bytes + filename="glib/gutils.c" + line="2935">a size in bytes #GFormatSizeFlags to modify the output + filename="glib/gutils.c" + line="2936">#GFormatSizeFlags to modify the output @@ -64819,44 +69960,44 @@ that modify the output. See #GFormatSizeFlags. version="2.2" introspectable="0"> An implementation of the standard fprintf() function which supports + filename="glib/gprintf.c" + line="64">An implementation of the standard `fprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. - + the number of bytes printed. + filename="glib/gprintf.c" + line="76">the number of bytes printed the stream to write to. + filename="glib/gprintf.c" + line="66">the stream to write to a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="67">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output. + filename="glib/gprintf.c" + line="69">the arguments to insert in the output Frees the memory pointed to by @mem. + filename="glib/gmem.c" + line="187">Frees the memory pointed to by @mem. If you know the allocated size of @mem, calling g_free_sized() may be faster, depending on the libc implementation in use. @@ -64869,7 +70010,7 @@ to understand its caveats). If @mem is %NULL it simply returns, so there is no need to check @mem against %NULL before calling this function. - + @@ -64879,16 +70020,16 @@ against %NULL before calling this function. nullable="1" allow-none="1"> the memory to free + filename="glib/gmem.c" + line="189">the memory to free Frees the memory pointed to by @mem, assuming it is has the given @size. + filename="glib/gmem.c" + line="212">Frees the memory pointed to by @mem, assuming it is has the given @size. If @mem is %NULL this is a no-op (and @size is ignored). @@ -64899,7 +70040,7 @@ allocator. If you don’t know the allocation size, use g_free() instead. In case a GCC compatible compiler is used, this function may be used automatically via g_free() if the allocated size is known at compile time, since GLib 2.78. - + @@ -64909,44 +70050,112 @@ since GLib 2.78. nullable="1" allow-none="1"> the memory to free + filename="glib/gmem.c" + line="214">the memory to free size of @mem, in bytes + filename="glib/gmem.c" + line="215">size of @mem, in bytes + + A wrapper for the POSIX freopen() function. The freopen() function +opens a file and associates it with an existing stream. + +See your C library manual for more details about freopen(). + + + A FILE* if the file was successfully opened, or %NULL if + an error occurred. + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a string describing the mode in which the file should be opened + + + + an existing stream which will be reused, or %NULL + + + + + + A wrapper for the POSIX `fsync()` function. On Windows, `_commit()` will be +used. On macOS, `fcntl(F_FULLFSYNC)` will be used. +The `fsync()` function is used to synchronize a file's in-core +state with that of the disk. + +This wrapper will handle retrying on `EINTR`. + +See the C library manual for more details about fsync(). + + + 0 on success, or -1 if an error occurred. +The return value can be used exactly like the return value from fsync(). + + + + + a file descriptor + + + + Gets a human-readable name for the application, as set by + filename="glib/gutils.c" + line="1192">Gets a human-readable name for the application, as set by g_set_application_name(). This name should be localized if possible, and is intended for display to the user. Contrast with g_get_prgname(), which gets a non-localized name. If g_set_application_name() has not been called, returns the result of g_get_prgname() (which may be %NULL if g_set_prgname() has also not been called). - + human-readable application + filename="glib/gutils.c" + line="1203">human-readable application name. May return %NULL Obtains the character set for the [current locale][setlocale]; you -might use this character set as an argument to g_convert(), to convert + filename="glib/gcharset.c" + line="173">Obtains the character set for the [current locale](running.html#locale); +you might use this character set as an argument to g_convert(), to convert from the current locale's encoding to some other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) @@ -64966,11 +70175,11 @@ case you can perhaps avoid calling g_convert(). The string returned in @charset is not allocated, and should not be freed. - + %TRUE if the returned charset is UTF-8 + filename="glib/gcharset.c" + line="200">%TRUE if the returned charset is UTF-8 @@ -64981,8 +70190,8 @@ freed. optional="1" allow-none="1"> return location for character set + filename="glib/gcharset.c" + line="175">return location for character set name, or %NULL. @@ -64990,13 +70199,13 @@ freed. Gets the character set for the current locale. - + filename="glib/gcharset.c" + line="314">Gets the character set for the current locale. + a newly allocated string containing the name + filename="glib/gcharset.c" + line="319">a newly allocated string containing the name of the character set. This string must be freed with g_free(). @@ -65005,8 +70214,8 @@ freed. c:identifier="g_get_console_charset" version="2.62"> Obtains the character set used by the console attached to the process, + filename="glib/gcharset.c" + line="332">Obtains the character set used by the console attached to the process, which is suitable for printing output to the terminal. Usually this matches the result returned by g_get_charset(), but in @@ -65023,11 +70232,11 @@ case you can perhaps avoid calling g_convert(). The string returned in @charset is not allocated, and should not be freed. - + %TRUE if the returned charset is UTF-8 + filename="glib/gcharset.c" + line="355">%TRUE if the returned charset is UTF-8 @@ -65038,8 +70247,8 @@ freed. optional="1" allow-none="1"> return location for character set + filename="glib/gcharset.c" + line="334">return location for character set name, or %NULL. @@ -65047,8 +70256,8 @@ freed. Gets the current directory. + filename="glib/gfileutils.c" + line="2918">Gets the current directory. The returned string should be freed when no longer needed. The encoding of the returned string is system defined. @@ -65058,11 +70267,11 @@ Since GLib 2.40, this function will return the value of the "PWD" environment variable if it is set and it happens to be the same as the current directory. This can make a difference in the case that the current directory is the target of a symbolic link. - + the current directory + filename="glib/gfileutils.c" + line="2932">the current directory @@ -65071,29 +70280,29 @@ the current directory is the target of a symbolic link. deprecated="1" deprecated-version="2.62"> Equivalent to the UNIX gettimeofday() function, but portable. + filename="glib/gmain.c" + line="2835">Equivalent to the UNIX gettimeofday() function, but portable. -You may find g_get_real_time() to be more convenient. - #GTimeVal is not year-2038-safe. Use g_get_real_time() - instead. - +You may find [func@GLib.get_real_time] to be more convenient. + #GTimeVal is not year-2038-safe. Use + [func@GLib.get_real_time] instead. + #GTimeVal structure in which to store current time. + filename="glib/gmain.c" + line="2837">#GTimeVal structure in which to store current time. Gets the list of environment variables for the current process. + filename="glib/genviron.c" + line="425">Gets the list of environment variables for the current process. The list is %NULL terminated and each item in the list is of the form 'NAME=VALUE'. @@ -65103,11 +70312,11 @@ except portable. The return value is freshly allocated and it should be freed with g_strfreev() when it is no longer needed. - + + filename="glib/genviron.c" + line="439"> the list of environment variables @@ -65118,8 +70327,8 @@ g_strfreev() when it is no longer needed. c:identifier="g_get_filename_charsets" version="2.6"> Determines the preferred character sets used for filenames. + filename="glib/gconvert.c" + line="1044">Determines the preferred character sets used for filenames. The first character set from the @charsets is the filename encoding, the subsequent character sets are used when trying to generate a displayable representation of a filename, see g_filename_display_name(). @@ -65130,8 +70339,8 @@ On Windows, the character set used in the GLib API is always UTF-8 and said environment variables have no effect. `G_FILENAME_ENCODING` may be set to a comma-separated list of -character set names. The special token "\@locale" is taken -to mean the character set for the [current locale][setlocale]. +character set names. The special token `@locale` is taken to mean the +character set for the [current locale](running.html#locale). If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, the character set of the current locale is taken as the filename encoding. If neither environment variable is set, UTF-8 is taken @@ -65143,11 +70352,11 @@ The returned @charsets belong to GLib and must not be freed. Note that on Unix, regardless of the locale character set or `G_FILENAME_ENCODING` value, the actual file names present on a system might be in any random encoding or just gibberish. - + %TRUE if the filename encoding is UTF-8. + filename="glib/gconvert.c" + line="1074">%TRUE if the filename encoding is UTF-8. @@ -65156,8 +70365,8 @@ on a system might be in any random encoding or just gibberish. caller-allocates="0" transfer-ownership="none"> + filename="glib/gconvert.c" + line="1046"> return location for the %NULL-terminated list of encoding names @@ -65167,8 +70376,8 @@ on a system might be in any random encoding or just gibberish. Gets the current user's home directory. + filename="glib/gutils.c" + line="902">Gets the current user's home directory. As with most UNIX tools, this function will return the value of the `HOME` environment variable if it is set to an existing absolute path @@ -65188,11 +70397,11 @@ old behaviour (and if you don't wish to increase your GLib dependency to ensure that the new behaviour is in effect) then you should either directly check the `HOME` environment variable yourself or unset it before calling any functions in GLib. - + the current user's home directory + filename="glib/gutils.c" + line="926">the current user's home directory @@ -65200,8 +70409,8 @@ or unset it before calling any functions in GLib. c:identifier="g_get_host_name" version="2.8"> Return a name for the machine. + filename="glib/gutils.c" + line="1033">Return a name for the machine. The returned name is not necessarily a fully-qualified domain name, or even present in DNS or some other name service at all. It need @@ -65215,11 +70424,11 @@ name can be determined, a default fixed string "localhost" is returned. The encoding of the returned string is UTF-8. - + the host name of the machine. + filename="glib/gutils.c" + line="1051">the host name of the machine. @@ -65227,8 +70436,8 @@ The encoding of the returned string is UTF-8. c:identifier="g_get_language_names" version="2.6"> Computes a list of applicable locale names, which can be used to + filename="glib/gcharset.c" + line="748">Computes a list of applicable locale names, which can be used to e.g. construct locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable and always contains the default locale "C". @@ -65239,11 +70448,11 @@ For example, if LANGUAGE=de:en_US, then the returned list is This function consults the environment variables `LANGUAGE`, `LC_ALL`, `LC_MESSAGES` and `LANG` to find the list of locales specified by the user. - + a %NULL-terminated array of strings owned by GLib + filename="glib/gcharset.c" + line="763">a %NULL-terminated array of strings owned by GLib that must not be modified or freed. @@ -65254,8 +70463,8 @@ user. c:identifier="g_get_language_names_with_category" version="2.58"> Computes a list of applicable locale names with a locale category name, + filename="glib/gcharset.c" + line="774">Computes a list of applicable locale names with a locale category name, which can be used to construct the fallback locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable and always contains the default locale "C". @@ -65265,11 +70474,11 @@ This function consults the environment variables `LANGUAGE`, `LC_ALL`, user. g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES"). - + a %NULL-terminated array of strings owned by + filename="glib/gcharset.c" + line="789">a %NULL-terminated array of strings owned by the thread g_get_language_names_with_category was called from. It must not be modified or freed. It must be copied if planned to be used in another thread. @@ -65279,8 +70488,8 @@ g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES") a locale category name + filename="glib/gcharset.c" + line="776">a locale category name @@ -65289,8 +70498,8 @@ g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES") c:identifier="g_get_locale_variants" version="2.28"> Returns a list of derived variants of @locale, which can be used to + filename="glib/gcharset.c" + line="641">Returns a list of derived variants of @locale, which can be used to e.g. construct locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable. This function handles territory, charset and extra locale modifiers. See @@ -65305,11 +70514,11 @@ is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`, If you need the list of variants for the current locale, use g_get_language_names(). - + a newly + filename="glib/gcharset.c" + line="661">a newly allocated array of newly allocated strings with the locale variants. Free with g_strfreev(). @@ -65319,8 +70528,8 @@ use g_get_language_names(). a locale identifier + filename="glib/gcharset.c" + line="643">a locale identifier @@ -65329,8 +70538,8 @@ use g_get_language_names(). c:identifier="g_get_monotonic_time" version="2.28"> Queries the system monotonic time. + filename="glib/gmain.c" + line="2906">Queries the system monotonic time. The monotonic clock will always increase and doesn't suffer discontinuities when the user (or NTP) changes the system time. It @@ -65340,11 +70549,11 @@ suspended. We try to use the clock that corresponds as closely as possible to the passage of time as measured by system calls such as poll() but it may not always be possible to do this. - + the monotonic time, in microseconds + filename="glib/gmain.c" + line="2920">the monotonic time, in microseconds @@ -65352,23 +70561,23 @@ may not always be possible to do this. c:identifier="g_get_num_processors" version="2.36"> Determine the approximate number of threads that the system will + filename="glib/gthread.c" + line="1127">Determine the approximate number of threads that the system will schedule simultaneously for this process. This is intended to be used as a parameter to g_thread_pool_new() for CPU bound tasks and similar cases. - + Number of schedulable threads, always greater than 0 + filename="glib/gthread.c" + line="1135">Number of schedulable threads, always greater than 0 Get information about the operating system. + filename="glib/gutils.c" + line="1656">Get information about the operating system. On Linux this comes from the `/etc/os-release` file. On other systems, it may come from a variety of sources. You can either use the standard key names @@ -65376,27 +70585,27 @@ like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example, `/etc/os-release` provides a number of other less commonly used values that may be useful. No key is guaranteed to be provided, so the caller should always check if the result is %NULL. - + The associated value for the requested key or %NULL if + filename="glib/gutils.c" + line="1669">The associated value for the requested key or %NULL if this information is not provided. a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME. + filename="glib/gutils.c" + line="1658">a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME. Gets the name of the program. This name should not be localized, + filename="glib/gutils.c" + line="1125">Gets the name of the program. This name should not be localized, in contrast to g_get_application_name(). If you are using #GApplication the program name is set in @@ -65404,11 +70613,11 @@ g_application_run(). In case of GDK or GTK it is set in gdk_init(), which is called by gtk_init() and the #GtkApplication::startup handler. The program name is found by taking the last component of @argv[0]. - + the name of the program, + filename="glib/gutils.c" + line="1137">the name of the program, or %NULL if it has not been set yet. The returned string belongs to GLib and must not be modified or freed. @@ -65416,17 +70625,17 @@ taking the last component of @argv[0]. Gets the real name of the user. This usually comes from the user's + filename="glib/gutils.c" + line="808">Gets the real name of the user. This usually comes from the user's entry in the `passwd` file. The encoding of the returned string is system-defined. (On Windows, it is, however, always UTF-8.) If the real user name cannot be determined, the string "Unknown" is returned. - + the user's real name. + filename="glib/gutils.c" + line="817">the user's real name. @@ -65434,21 +70643,21 @@ returned. c:identifier="g_get_real_time" version="2.28"> Queries the system wall-clock time. + filename="glib/gmain.c" + line="2861">Queries the system wall-clock time. -This call is functionally equivalent to g_get_current_time() except +This call is functionally equivalent to [func@GLib.get_current_time] except that the return value is often more convenient than dealing with a #GTimeVal. You should only use this call if you are actually interested in the real -wall-clock time. g_get_monotonic_time() is probably more useful for +wall-clock time. [func@GLib.get_monotonic_time] is probably more useful for measuring intervals. - + the number of microseconds since January 1, 1970 UTC. + filename="glib/gmain.c" + line="2874">the number of microseconds since January 1, 1970 UTC. @@ -65456,8 +70665,8 @@ measuring intervals. c:identifier="g_get_system_config_dirs" version="2.6"> Returns an ordered list of base directories in which to access + filename="glib/gutils.c" + line="2806">Returns an ordered list of base directories in which to access system-wide configuration information. On UNIX platforms this is determined using the mechanisms described @@ -65477,11 +70686,11 @@ to anyone using the computer. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + + filename="glib/gutils.c" + line="2830"> a %NULL-terminated array of strings owned by GLib that must not be modified or freed. @@ -65493,8 +70702,8 @@ it’s not thread-safe to modify environment variables at runtime. c:identifier="g_get_system_data_dirs" version="2.6"> Returns an ordered list of base directories in which to access + filename="glib/gutils.c" + line="2714">Returns an ordered list of base directories in which to access system-wide application data. On UNIX platforms this is determined using the mechanisms described @@ -65528,11 +70737,11 @@ this function is called. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + + filename="glib/gutils.c" + line="2752"> a %NULL-terminated array of strings owned by GLib that must not be modified or freed. @@ -65542,8 +70751,8 @@ it’s not thread-safe to modify environment variables at runtime. Gets the directory to use for temporary files. + filename="glib/gutils.c" + line="955">Gets the directory to use for temporary files. On UNIX, this is taken from the `TMPDIR` environment variable. If the variable is not set, `P_tmpdir` is @@ -65557,11 +70766,11 @@ as a default. The encoding of the returned string is system-defined. On Windows, it is always UTF-8. The return value is never %NULL or the empty string. - + the directory to use for temporary files. + filename="glib/gutils.c" + line="973">the directory to use for temporary files. @@ -65569,8 +70778,8 @@ string. c:identifier="g_get_user_cache_dir" version="2.6"> Returns a base directory in which to store non-essential, cached + filename="glib/gutils.c" + line="2015">Returns a base directory in which to store non-essential, cached data specific to particular user. On UNIX platforms this is determined using the mechanisms described @@ -65586,11 +70795,11 @@ See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/ The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + a string owned by GLib that + filename="glib/gutils.c" + line="2035">a string owned by GLib that must not be modified or freed. @@ -65599,8 +70808,8 @@ it’s not thread-safe to modify environment variables at runtime. c:identifier="g_get_user_config_dir" version="2.6"> Returns a base directory in which to store user-specific application + filename="glib/gutils.c" + line="1951">Returns a base directory in which to store user-specific application configuration information such as user preferences and settings. On UNIX platforms this is determined using the mechanisms described @@ -65617,11 +70826,11 @@ as what g_get_user_data_dir() returns. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + a string owned by GLib that + filename="glib/gutils.c" + line="1972">a string owned by GLib that must not be modified or freed. @@ -65630,8 +70839,8 @@ it’s not thread-safe to modify environment variables at runtime. c:identifier="g_get_user_data_dir" version="2.6"> Returns a base directory in which to access application data such + filename="glib/gutils.c" + line="1886">Returns a base directory in which to access application data such as icons that is customized for a particular user. On UNIX platforms this is determined using the mechanisms described @@ -65648,27 +70857,27 @@ as what g_get_user_config_dir() returns. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + a string owned by GLib that must + filename="glib/gutils.c" + line="1907">a string owned by GLib that must not be modified or freed. Gets the user name of the current user. The encoding of the returned + filename="glib/gutils.c" + line="788">Gets the user name of the current user. The encoding of the returned string is system-defined. On UNIX, it might be the preferred file name encoding, or something else, and there is no guarantee that it is even consistent on a machine. On Windows, it is always UTF-8. - + the user name of the current user. + filename="glib/gutils.c" + line="796">the user name of the current user. @@ -65676,8 +70885,8 @@ consistent on a machine. On Windows, it is always UTF-8. c:identifier="g_get_user_runtime_dir" version="2.28"> Returns a directory that is unique to the current user on the local + filename="glib/gutils.c" + line="2157">Returns a directory that is unique to the current user on the local system. This is determined using the mechanisms described @@ -65690,11 +70899,11 @@ g_get_user_cache_dir(), after verifying that it exists. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + a string owned by GLib that must not be + filename="glib/gutils.c" + line="2174">a string owned by GLib that must not be modified or freed. @@ -65703,8 +70912,8 @@ it’s not thread-safe to modify environment variables at runtime. c:identifier="g_get_user_special_dir" version="2.14"> Returns the full path of a special directory using its logical id. + filename="glib/gutils.c" + line="2447">Returns the full path of a special directory using its logical id. On UNIX this is done using the XDG special user directories. For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP @@ -65714,11 +70923,11 @@ not been set up. Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded. - + the path to the specified special + filename="glib/gutils.c" + line="2462">the path to the specified special directory, or %NULL if the logical id was not found. The returned string is owned by GLib and should not be modified or freed. @@ -65726,8 +70935,8 @@ will not reflect any change once the special directories are loaded. the logical id of special directory + filename="glib/gutils.c" + line="2449">the logical id of special directory @@ -65736,8 +70945,8 @@ will not reflect any change once the special directories are loaded. c:identifier="g_get_user_state_dir" version="2.72"> Returns a base directory in which to store state files specific to + filename="glib/gutils.c" + line="2078">Returns a base directory in which to store state files specific to particular user. On UNIX platforms this is determined using the mechanisms described @@ -65754,30 +70963,30 @@ as what g_get_user_data_dir() returns. The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. - + a string owned by GLib that + filename="glib/gutils.c" + line="2099">a string owned by GLib that must not be modified or freed. Returns the value of an environment variable. + filename="glib/genviron.c" + line="235">Returns the value of an environment variable. On UNIX, the name and value are byte strings which might or might not be in some consistent character set and encoding. On Windows, they are in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded. - + the value of the environment variable, or %NULL if + filename="glib/genviron.c" + line="247">the value of the environment variable, or %NULL if the environment variable is not found. The returned string may be overwritten by the next call to g_getenv(), g_setenv() or g_unsetenv(). @@ -65786,46 +70995,19 @@ references to other environment variables, they are expanded. the environment variable to get + filename="glib/genviron.c" + line="237">the environment variable to get - - Functions for manipulating internet hostnames; in particular, for -converting between Unicode and ASCII-encoded forms of -Internationalized Domain Names (IDNs). - -The -[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) -standards allow for the use -of Unicode domain names in applications, while providing -backward-compatibility with the old ASCII-only DNS, by defining an -ASCII-Compatible Encoding of any given Unicode name, which can be -used with non-IDN-aware applications and protocols. (For example, -"Παν語.org" maps to "xn--4wa8awb4637h.org".) - - - Most of GLib is intended to be portable; in contrast, this set of -functions is designed for programs which explicitly target UNIX, -or are using it to build higher level abstractions which would be -conditionally compiled if the platform matches %G_OS_UNIX. - -To use these functions, you must explicitly include the -"glib-unix.h" header. - This is a convenience function for using a #GHashTable as a set. It + filename="glib/ghash.c" + line="1637">This is a convenience function for using a #GHashTable as a set. It is equivalent to calling g_hash_table_replace() with @key as both the key and the value. @@ -65840,18 +71022,18 @@ the discussion in the section description. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. - + %TRUE if the key did not exist yet + filename="glib/ghash.c" + line="1658">%TRUE if the key did not exist yet a #GHashTable + filename="glib/ghash.c" + line="1639">a #GHashTable @@ -65862,8 +71044,8 @@ or not. nullable="1" allow-none="1"> a key to insert + filename="glib/ghash.c" + line="1640">a key to insert @@ -65873,20 +71055,20 @@ or not. moved-to="HashTable.contains" version="2.32"> Checks if @key is in @hash_table. - + filename="glib/ghash.c" + line="1669">Checks if @key is in @hash_table. + %TRUE if @key is in @hash_table, %FALSE otherwise. + filename="glib/ghash.c" + line="1676">%TRUE if @key is in @hash_table, %FALSE otherwise. a #GHashTable + filename="glib/ghash.c" + line="1671">a #GHashTable @@ -65897,8 +71079,8 @@ or not. nullable="1" allow-none="1"> a key to check + filename="glib/ghash.c" + line="1672">a key to check @@ -65907,42 +71089,250 @@ or not. c:identifier="g_hash_table_destroy" moved-to="HashTable.destroy"> Destroys all keys and values in the #GHashTable and decrements its + filename="glib/ghash.c" + line="1447">Destroys all keys and values in the #GHashTable and decrements its reference count by 1. If keys and/or values are dynamically allocated, you should either free them first or create the #GHashTable with destroy notifiers using g_hash_table_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values during the destruction phase. - + + + + + + + a #GHashTable + + + + + + + + + Calls the given function for key/value pairs in the #GHashTable +until @predicate returns %TRUE. The function is passed the key +and value of each pair, and the given @user_data parameter. The +hash table may not be modified while iterating over it (you can't +add/remove items). + +Note, that hash tables are really only optimized for forward +lookups, i.e. g_hash_table_lookup(). So code that frequently issues +g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of +once per every entry in a hash table) should probably be reworked +to use additional or different data structures for reverse lookups +(keep in mind that an O(n) find/foreach operation issued for all n +values in a hash table ends up needing O(n*n) operations). + + + The value of the first key/value pair is returned, + for which @predicate evaluates to %TRUE. If no pair with the + requested property is found, %NULL is returned. + + + + + a #GHashTable + + + + + + + function to test the key/value pairs for a certain property + + + + user data to pass to the function + + + + + + Calls the given function for each of the key/value pairs in the +#GHashTable. The function is passed the key and value of each +pair, and the given @user_data parameter. The hash table may not +be modified while iterating over it (you can't add/remove +items). To remove all items matching a predicate, use +g_hash_table_foreach_remove(). + +The order in which g_hash_table_foreach() iterates over the keys/values in +the hash table is not defined. + +See g_hash_table_find() for performance caveats for linear +order searches in contrast to g_hash_table_lookup(). + a #GHashTable + filename="glib/ghash.c" + line="2087">a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Calls the given function for each key/value pair in the +#GHashTable. If the function returns %TRUE, then the key/value +pair is removed from the #GHashTable. If you supplied key or +value destroy functions when creating the #GHashTable, they are +used to free the memory allocated for the removed keys and values. + +See #GHashTableIter for an alternative way to loop over the +key/value pairs in the hash table. + + + the number of key/value pairs removed + + + + + a #GHashTable + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Calls the given function for each key/value pair in the +#GHashTable. If the function returns %TRUE, then the key/value +pair is removed from the #GHashTable, but no key or value +destroy functions are called. + +See #GHashTableIter for an alternative way to loop over the +key/value pairs in the hash table. + + + the number of key/value pairs removed. + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + This function is deprecated and will be removed in the next major + filename="glib/ghash.c" + line="168">This function is deprecated and will be removed in the next major release of GLib. It does nothing. - + a #GHashTable + filename="glib/ghash.c" + line="170">a #GHashTable @@ -65952,8 +71342,8 @@ release of GLib. It does nothing. version="2.76" introspectable="0"> Retrieves every key inside @hash_table, as a #GPtrArray. + filename="glib/ghash.c" + line="2304">Retrieves every key inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those keys. This iterates over every entry in the hash table to build its return value. @@ -65961,11 +71351,11 @@ To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). - + a #GPtrArray containing each key from + filename="glib/ghash.c" + line="2317">a #GPtrArray containing each key from the table. Unref with with g_ptr_array_unref() when done. @@ -65974,8 +71364,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="2306">a #GHashTable @@ -65989,8 +71379,8 @@ the table. Unref with with g_ptr_array_unref() when done. version="2.76" introspectable="0"> Retrieves every value inside @hash_table, as a #GPtrArray. + filename="glib/ghash.c" + line="2379">Retrieves every value inside @hash_table, as a #GPtrArray. The returned data is valid until changes to the hash release those values. This iterates over every entry in the hash table to build its return value. @@ -65998,11 +71388,11 @@ To iterate over the entries in a #GHashTable more efficiently, use a #GHashTableIter. You should always unref the returned array with g_ptr_array_unref(). - + a #GPtrArray containing each value from + filename="glib/ghash.c" + line="2392">a #GPtrArray containing each value from the table. Unref with with g_ptr_array_unref() when done. @@ -66011,8 +71401,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="2381">a #GHashTable @@ -66024,8 +71414,8 @@ the table. Unref with with g_ptr_array_unref() when done. c:identifier="g_hash_table_insert" moved-to="HashTable.insert"> Inserts a new key and value into a #GHashTable. + filename="glib/ghash.c" + line="1580">Inserts a new key and value into a #GHashTable. If the key already exists in the #GHashTable its current value is replaced with the new value. If you supplied a @@ -66037,18 +71427,18 @@ key is freed using that function. Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. - + %TRUE if the key did not exist yet + filename="glib/ghash.c" + line="1599">%TRUE if the key did not exist yet a #GHashTable + filename="glib/ghash.c" + line="1582">a #GHashTable @@ -66059,8 +71449,8 @@ or not. nullable="1" allow-none="1"> a key to insert + filename="glib/ghash.c" + line="1583">a key to insert nullable="1" allow-none="1"> the value to associate with the key + filename="glib/ghash.c" + line="1584">the value to associate with the key @@ -66078,23 +71468,23 @@ or not. c:identifier="g_hash_table_lookup" moved-to="HashTable.lookup"> Looks up a key in a #GHashTable. Note that this function cannot + filename="glib/ghash.c" + line="1467">Looks up a key in a #GHashTable. Note that this function cannot distinguish between a key that is not present and one which is present and has the value %NULL. If you need this distinction, use g_hash_table_lookup_extended(). - + the associated value, or %NULL if the key is not found + filename="glib/ghash.c" + line="1477">the associated value, or %NULL if the key is not found a #GHashTable + filename="glib/ghash.c" + line="1469">a #GHashTable @@ -66105,8 +71495,8 @@ g_hash_table_lookup_extended(). nullable="1" allow-none="1"> the key to look up + filename="glib/ghash.c" + line="1470">the key to look up @@ -66115,8 +71505,8 @@ g_hash_table_lookup_extended(). c:identifier="g_hash_table_lookup_extended" moved-to="HashTable.lookup_extended"> Looks up a key in the #GHashTable, returning the original key and the + filename="glib/ghash.c" + line="1495">Looks up a key in the #GHashTable, returning the original key and the associated value and a #gboolean which is %TRUE if the key was found. This is useful if you need to free the memory allocated for the original key, for example before calling g_hash_table_remove(). @@ -66124,18 +71514,18 @@ for example before calling g_hash_table_remove(). You can actually pass %NULL for @lookup_key to test whether the %NULL key exists, provided the hash and equal functions of @hash_table are %NULL-safe. - + %TRUE if the key was found in the #GHashTable + filename="glib/ghash.c" + line="1512">%TRUE if the key was found in the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1497">a #GHashTable @@ -66146,8 +71536,8 @@ of @hash_table are %NULL-safe. nullable="1" allow-none="1"> the key to look up + filename="glib/ghash.c" + line="1498">the key to look up optional="1" allow-none="1"> return location for the original key + filename="glib/ghash.c" + line="1499">return location for the original key optional="1" allow-none="1"> return location for the value associated + filename="glib/ghash.c" + line="1500">return location for the value associated with the key @@ -66182,8 +71572,8 @@ with the key moved-to="HashTable.new_similar" version="2.72"> Creates a new #GHashTable like g_hash_table_new_full() with a reference + filename="glib/ghash.c" + line="1038">Creates a new #GHashTable like g_hash_table_new_full() with a reference count of 1. It inherits the hash function, the key equal function, the key destroy function, @@ -66191,11 +71581,11 @@ as well as the value destroy function, from @other_hash_table. The returned hash table will be empty; it will not contain the keys or values from @other_hash_table. - + a new #GHashTable + filename="glib/ghash.c" + line="1051">a new #GHashTable @@ -66204,8 +71594,38 @@ or values from @other_hash_table. Another #GHashTable + filename="glib/ghash.c" + line="1040">Another #GHashTable + + + + + + + + + Atomically increments the reference count of @hash_table by one. +This function is MT-safe and may be called from any thread. + + + the passed in #GHashTable + + + + + + + + a valid #GHashTable @@ -66217,25 +71637,25 @@ or values from @other_hash_table. c:identifier="g_hash_table_remove" moved-to="HashTable.remove"> Removes a key and its associated value from a #GHashTable. + filename="glib/ghash.c" + line="1732">Removes a key and its associated value from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. - + %TRUE if the key was found and removed from the #GHashTable + filename="glib/ghash.c" + line="1744">%TRUE if the key was found and removed from the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1734">a #GHashTable @@ -66246,8 +71666,8 @@ yourself. nullable="1" allow-none="1"> the key to remove + filename="glib/ghash.c" + line="1735">the key to remove @@ -66257,22 +71677,22 @@ yourself. moved-to="HashTable.remove_all" version="2.12"> Removes all keys and their associated values from a #GHashTable. + filename="glib/ghash.c" + line="1849">Removes all keys and their associated values from a #GHashTable. If the #GHashTable was created using g_hash_table_new_full(), the keys and values are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. - + a #GHashTable + filename="glib/ghash.c" + line="1851">a #GHashTable @@ -66284,8 +71704,8 @@ values are freed yourself. c:identifier="g_hash_table_replace" moved-to="HashTable.replace"> Inserts a new key and value into a #GHashTable similar to + filename="glib/ghash.c" + line="1609">Inserts a new key and value into a #GHashTable similar to g_hash_table_insert(). The difference is that if the key already exists in the #GHashTable, it gets replaced by the new key. If you supplied a @value_destroy_func when creating @@ -66296,18 +71716,18 @@ If you supplied a @key_destroy_func when creating the Starting from GLib 2.40, this function returns a boolean value to indicate whether the newly added value was already in the hash table or not. - + %TRUE if the key did not exist yet + filename="glib/ghash.c" + line="1627">%TRUE if the key did not exist yet a #GHashTable + filename="glib/ghash.c" + line="1611">a #GHashTable @@ -66318,8 +71738,8 @@ or not. nullable="1" allow-none="1"> a key to insert + filename="glib/ghash.c" + line="1612">a key to insert nullable="1" allow-none="1"> the value to associate with the key + filename="glib/ghash.c" + line="1613">the value to associate with the key @@ -66337,20 +71757,20 @@ or not. c:identifier="g_hash_table_size" moved-to="HashTable.size"> Returns the number of elements contained in the #GHashTable. - + filename="glib/ghash.c" + line="2202">Returns the number of elements contained in the #GHashTable. + the number of key/value pairs in the #GHashTable. + filename="glib/ghash.c" + line="2208">the number of key/value pairs in the #GHashTable. a #GHashTable + filename="glib/ghash.c" + line="2204">a #GHashTable @@ -66362,21 +71782,21 @@ or not. c:identifier="g_hash_table_steal" moved-to="HashTable.steal"> Removes a key and its associated value from a #GHashTable without + filename="glib/ghash.c" + line="1753">Removes a key and its associated value from a #GHashTable without calling the key and value destroy functions. - + %TRUE if the key was found and removed from the #GHashTable + filename="glib/ghash.c" + line="1761">%TRUE if the key was found and removed from the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1755">a #GHashTable @@ -66387,8 +71807,8 @@ calling the key and value destroy functions. nullable="1" allow-none="1"> the key to remove + filename="glib/ghash.c" + line="1756">the key to remove @@ -66398,18 +71818,18 @@ calling the key and value destroy functions. moved-to="HashTable.steal_all" version="2.12"> Removes all keys and their associated values from a #GHashTable + filename="glib/ghash.c" + line="1876">Removes all keys and their associated values from a #GHashTable without calling the key and value destroy functions. - + a #GHashTable + filename="glib/ghash.c" + line="1878">a #GHashTable @@ -66423,16 +71843,16 @@ without calling the key and value destroy functions. version="2.76" introspectable="0"> Removes all keys and their associated values from a #GHashTable + filename="glib/ghash.c" + line="1899">Removes all keys and their associated values from a #GHashTable without calling the key destroy functions, returning the keys as a #GPtrArray with the free func set to the @hash_table key destroy function. - + a #GPtrArray containing each key of + filename="glib/ghash.c" + line="1908">a #GPtrArray containing each key of the table. Unref with with g_ptr_array_unref() when done. @@ -66441,8 +71861,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="1901">a #GHashTable @@ -66456,16 +71876,16 @@ the table. Unref with with g_ptr_array_unref() when done. version="2.76" introspectable="0"> Removes all keys and their associated values from a #GHashTable + filename="glib/ghash.c" + line="1936">Removes all keys and their associated values from a #GHashTable without calling the value destroy functions, returning the values as a #GPtrArray with the free func set to the @hash_table value destroy function. - + a #GPtrArray containing each value of + filename="glib/ghash.c" + line="1945">a #GPtrArray containing each value of the table. Unref with with g_ptr_array_unref() when done. @@ -66474,8 +71894,8 @@ the table. Unref with with g_ptr_array_unref() when done. a #GHashTable + filename="glib/ghash.c" + line="1938">a #GHashTable @@ -66488,8 +71908,8 @@ the table. Unref with with g_ptr_array_unref() when done. moved-to="HashTable.steal_extended" version="2.58"> Looks up a key in the #GHashTable, stealing the original key and the + filename="glib/ghash.c" + line="1770">Looks up a key in the #GHashTable, stealing the original key and the associated value and returning %TRUE if the key was found. If the key was not found, %FALSE is returned. @@ -66503,20 +71923,21 @@ You can pass %NULL for @lookup_key, provided the hash and equal functions of @hash_table are %NULL-safe. The dictionary implementation optimizes for having all values identical to -their keys, for example by using g_hash_table_add(). When stealing both the -key and the value from such a dictionary, the value will be %NULL. - +their keys, for example by using g_hash_table_add(). Before 2.82, when +stealing both the key and the value from such a dictionary, the value was +%NULL. Since 2.82, the returned value and key will be the same. + %TRUE if the key was found in the #GHashTable + filename="glib/ghash.c" + line="1797">%TRUE if the key was found in the #GHashTable a #GHashTable + filename="glib/ghash.c" + line="1772">a #GHashTable @@ -66527,8 +71948,8 @@ key and the value from such a dictionary, the value will be %NULL. nullable="1" allow-none="1"> the key to look up + filename="glib/ghash.c" + line="1773">the key to look up optional="1" allow-none="1"> return location for the + filename="glib/ghash.c" + line="1774">return location for the original key @@ -66552,8 +71973,8 @@ key and the value from such a dictionary, the value will be %NULL. optional="1" allow-none="1"> return location + filename="glib/ghash.c" + line="1776">return location for the value associated with the key @@ -66563,15 +71984,15 @@ key and the value from such a dictionary, the value will be %NULL. c:identifier="g_hash_table_thaw" introspectable="0"> This function is deprecated and will be removed in the next major + filename="glib/ghash.c" + line="176">This function is deprecated and will be removed in the next major release of GLib. It does nothing. - + a #GHashTable + filename="glib/ghash.c" + line="178">a #GHashTable @@ -66580,20 +72001,20 @@ release of GLib. It does nothing. moved-to="HashTable.unref" version="2.10"> Atomically decrements the reference count of @hash_table by one. + filename="glib/ghash.c" + line="1420">Atomically decrements the reference count of @hash_table by one. If the reference count drops to 0, all keys and values will be destroyed, and all memory allocated by the hash table is released. This function is MT-safe and may be called from any thread. - + - + a valid #GHashTable + filename="glib/ghash.c" + line="1422">a valid #GHashTable @@ -66601,94 +72022,23 @@ This function is MT-safe and may be called from any thread. - - A #GHashTable provides associations between keys and values which is -optimized so that given a key, the associated value can be found, -inserted or removed in amortized O(1). All operations going through -each element take O(n) time (list all keys/values, table resize, etc.). - -Note that neither keys nor values are copied when inserted into the -#GHashTable, so they must exist for the lifetime of the #GHashTable. -This means that the use of static strings is OK, but temporary -strings (i.e. those created in buffers and those returned by GTK -widgets) should be copied with g_strdup() before being inserted. - -If keys or values are dynamically allocated, you must be careful to -ensure that they are freed when they are removed from the -#GHashTable, and also when they are overwritten by new insertions -into the #GHashTable. It is also not advisable to mix static strings -and dynamically-allocated strings in a #GHashTable, because it then -becomes difficult to determine whether the string should be freed. - -To create a #GHashTable, use g_hash_table_new(). - -To insert a key and value into a #GHashTable, use -g_hash_table_insert(). - -To look up a value corresponding to a given key, use -g_hash_table_lookup() and g_hash_table_lookup_extended(). - -g_hash_table_lookup_extended() can also be used to simply -check if a key is present in the hash table. - -To remove a key and value, use g_hash_table_remove(). - -To call a function for each key and value pair use -g_hash_table_foreach() or use an iterator to iterate over the -key/value pairs in the hash table, see #GHashTableIter. The iteration order -of a hash table is not defined, and you must not rely on iterating over -keys/values in the same order as they were inserted. - -To destroy a #GHashTable use g_hash_table_destroy(). - -A common use-case for hash tables is to store information about a -set of keys, without associating any particular value with each -key. GHashTable optimizes one way of doing so: If you store only -key-value pairs where key == value, then GHashTable does not -allocate memory to store the values, which can be a considerable -space saving, if your set is large. The functions -g_hash_table_add() and g_hash_table_contains() are designed to be -used when using #GHashTable this way. - -#GHashTable is not designed to be statically initialised with keys and -values known at compile time. To build a static hash table, use a tool such -as [gperf](https://www.gnu.org/software/gperf/). - - - HMACs should be used when producing a cookie or hash based on data -and a key. Simple mechanisms for using SHA1 and other algorithms to -digest a key and data together are vulnerable to various security -issues. -[HMAC](http://en.wikipedia.org/wiki/HMAC) -uses algorithms like SHA1 in a secure way to produce a digest of a -key and data. - -Both the key and data are arbitrary byte arrays of bytes or characters. - -Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 -in GLib 2.42. Support for SHA-384 was added in GLib 2.52. - Appends a #GHook onto the end of a #GHookList. - + filename="glib/ghook.c" + line="421">Appends a #GHook onto the end of a #GHookList. + a #GHookList + filename="glib/ghook.c" + line="423">a #GHookList the #GHook to add to the end of @hook_list + filename="glib/ghook.c" + line="424">the #GHook to add to the end of @hook_list @@ -66696,26 +72046,26 @@ in GLib 2.42. Support for SHA-384 was added in GLib 2.52. c:identifier="g_hook_destroy" moved-to="Hook.destroy"> Destroys a #GHook, given its ID. - + filename="glib/ghook.c" + line="321">Destroys a #GHook, given its ID. + %TRUE if the #GHook was found in the #GHookList and destroyed + filename="glib/ghook.c" + line="328">%TRUE if the #GHook was found in the #GHookList and destroyed a #GHookList + filename="glib/ghook.c" + line="323">a #GHookList a hook ID + filename="glib/ghook.c" + line="324">a hook ID @@ -66724,48 +72074,48 @@ in GLib 2.42. Support for SHA-384 was added in GLib 2.52. c:identifier="g_hook_destroy_link" moved-to="Hook.destroy_link"> Removes one #GHook from a #GHookList, marking it + filename="glib/ghook.c" + line="298">Removes one #GHook from a #GHookList, marking it inactive and calling g_hook_unref() on it. - + a #GHookList + filename="glib/ghook.c" + line="300">a #GHookList the #GHook to remove + filename="glib/ghook.c" + line="301">the #GHook to remove Calls the #GHookList @finalize_hook function if it exists, + filename="glib/ghook.c" + line="275">Calls the #GHookList @finalize_hook function if it exists, and frees the memory allocated for the #GHook. - + a #GHookList + filename="glib/ghook.c" + line="277">a #GHookList the #GHook to free + filename="glib/ghook.c" + line="278">the #GHook to free @@ -66774,17 +72124,17 @@ and frees the memory allocated for the #GHook. c:identifier="g_hook_insert_before" moved-to="Hook.insert_before"> Inserts a #GHook into a #GHookList, before a given #GHook. - + filename="glib/ghook.c" + line="445">Inserts a #GHook into a #GHookList, before a given #GHook. + a #GHookList + filename="glib/ghook.c" + line="447">a #GHookList nullable="1" allow-none="1"> the #GHook to insert the new #GHook before + filename="glib/ghook.c" + line="448">the #GHook to insert the new #GHook before the #GHook to insert + filename="glib/ghook.c" + line="449">the #GHook to insert + + Inserts a #GHook into a #GHookList, sorted by the given function. + + + + + + + a #GHookList + + + + the #GHook to insert + + + + the comparison function used to sort the #GHook elements + + + + Prepends a #GHook on the start of a #GHookList. - + filename="glib/ghook.c" + line="429">Prepends a #GHook on the start of a #GHookList. + a #GHookList + filename="glib/ghook.c" + line="431">a #GHookList the #GHook to add to the start of @hook_list + filename="glib/ghook.c" + line="432">the #GHook to add to the start of @hook_list @@ -66833,42 +72214,35 @@ and frees the memory allocated for the #GHook. c:identifier="g_hook_unref" moved-to="Hook.unref"> Decrements the reference count of a #GHook. + filename="glib/ghook.c" + line="349">Decrements the reference count of a #GHook. If the reference count falls to 0, the #GHook is removed from the #GHookList and g_hook_free() is called to free it. - + a #GHookList + filename="glib/ghook.c" + line="351">a #GHookList the #GHook to unref + filename="glib/ghook.c" + line="352">the #GHook to unref - - The #GHookList, #GHook and their related functions provide support for -lists of hook functions. Functions can be added and removed from the lists, -and the list of hook functions can be invoked. - Tests if @hostname contains segments with an ASCII-compatible + filename="glib/ghostutils.c" + line="718">Tests if @hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns %TRUE, you should decode the hostname with g_hostname_to_unicode() before displaying it to the user. @@ -66876,19 +72250,19 @@ before displaying it to the user. Note that a hostname might contain a mix of encoded and unencoded segments, and so it is possible for g_hostname_is_non_ascii() and g_hostname_is_ascii_encoded() to both return %TRUE for a name. - + %TRUE if @hostname contains any ASCII-encoded + filename="glib/ghostutils.c" + line="731">%TRUE if @hostname contains any ASCII-encoded segments. a hostname + filename="glib/ghostutils.c" + line="720">a hostname @@ -66897,23 +72271,23 @@ segments. c:identifier="g_hostname_is_ip_address" version="2.22"> Tests if @hostname is the string form of an IPv4 or IPv6 address. + filename="glib/ghostutils.c" + line="751">Tests if @hostname is the string form of an IPv4 or IPv6 address. (Eg, "192.168.0.1".) Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874). - + %TRUE if @hostname is an IP address + filename="glib/ghostutils.c" + line="760">%TRUE if @hostname is an IP address a hostname (or IP address in string form) + filename="glib/ghostutils.c" + line="753">a hostname (or IP address in string form) @@ -66922,26 +72296,26 @@ Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874). c:identifier="g_hostname_is_non_ascii" version="2.22"> Tests if @hostname contains Unicode characters. If this returns + filename="glib/ghostutils.c" + line="540">Tests if @hostname contains Unicode characters. If this returns %TRUE, you need to encode the hostname with g_hostname_to_ascii() before using it in non-IDN-aware contexts. Note that a hostname might contain a mix of encoded and unencoded segments, and so it is possible for g_hostname_is_non_ascii() and g_hostname_is_ascii_encoded() to both return %TRUE for a name. - + %TRUE if @hostname contains any non-ASCII characters + filename="glib/ghostutils.c" + line="552">%TRUE if @hostname contains any non-ASCII characters a hostname + filename="glib/ghostutils.c" + line="542">a hostname @@ -66950,23 +72324,23 @@ g_hostname_is_ascii_encoded() to both return %TRUE for a name. c:identifier="g_hostname_to_ascii" version="2.22"> Converts @hostname to its canonical ASCII form; an ASCII-only + filename="glib/ghostutils.c" + line="444">Converts @hostname to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot. - + an ASCII hostname, which must be freed, + filename="glib/ghostutils.c" + line="452">an ASCII hostname, which must be freed, or %NULL if @hostname is in some way invalid. a valid UTF-8 or ASCII hostname + filename="glib/ghostutils.c" + line="446">a valid UTF-8 or ASCII hostname @@ -66975,107 +72349,61 @@ trailing dot. c:identifier="g_hostname_to_unicode" version="2.22"> Converts @hostname to its canonical presentation form; a UTF-8 + filename="glib/ghostutils.c" + line="647">Converts @hostname to its canonical presentation form; a UTF-8 string in Unicode normalization form C, containing no uppercase letters, no forbidden characters, and no ASCII-encoded segments, and not ending with a trailing dot. Of course if @hostname is not an internationalized hostname, then the canonical presentation form will be entirely ASCII. - + a UTF-8 hostname, which must be freed, + filename="glib/ghostutils.c" + line="659">a UTF-8 hostname, which must be freed, or %NULL if @hostname is in some way invalid. a valid UTF-8 or ASCII hostname + filename="glib/ghostutils.c" + line="649">a valid UTF-8 or ASCII hostname Converts a 32-bit integer value from host to network byte order. - + filename="glib/docs.c" + line="130">Converts a 32-bit integer value from host to network byte order. + a 32-bit integer value in host byte order + filename="glib/docs.c" + line="132">a 32-bit integer value in host byte order Converts a 16-bit integer value from host to network byte order. - + filename="glib/docs.c" + line="139">Converts a 16-bit integer value from host to network byte order. + a 16-bit integer value in host byte order + filename="glib/docs.c" + line="141">a 16-bit integer value in host byte order - - GLib doesn't force any particular localization method upon its users. -But since GLib itself is localized using the gettext() mechanism, it seems -natural to offer the de-facto standard gettext() support macros in an -easy-to-use form. - -In order to use these macros in an application, you must include -`<glib/gi18n.h>`. For use in a library, you must include -`<glib/gi18n-lib.h>` -after defining the %GETTEXT_PACKAGE macro suitably for your library: -|[<!-- language="C" --> -#define GETTEXT_PACKAGE "gtk20" -#include <glib/gi18n-lib.h> -]| -For an application, note that you also have to call bindtextdomain(), -bind_textdomain_codeset(), textdomain() and setlocale() early on in your -main() to make gettext() work. For example: -|[<!-- language="C" --> -#include <glib/gi18n.h> -#include <locale.h> - -int -main (int argc, char **argv) -{ - setlocale (LC_ALL, ""); - bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale"); - bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8"); - textdomain (GETTEXT_PACKAGE); - - // Rest of your application. -} -]| -where `DATADIR` is as typically provided by automake or Meson. - -For a library, you only have to call bindtextdomain() and -bind_textdomain_codeset() in your initialization function. If your library -doesn't have an initialization function, you can call the functions before -the first translated message. - -The -[gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers) -covers details of how to integrate gettext into a project’s build system and -workflow. - Same as the standard UNIX routine iconv(), but + filename="glib/gconvert.c" + line="153">Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. @@ -67087,25 +72415,28 @@ input character set, but which have no representation in the output character set, is implementation defined. This function may return success (with a positive number of non-reversible conversions as replacement characters were used), or it may return -1 and set an error such as %EILSEQ, in such a -situation. - +situation. + +See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an +error occurs. + count of non-reversible conversions, or -1 on error + filename="glib/gconvert.c" + line="178">count of non-reversible conversions, or -1 on error conversion descriptor from g_iconv_open() + filename="glib/gconvert.c" + line="155">conversion descriptor from g_iconv_open() bytes to convert + filename="glib/gconvert.c" + line="156">bytes to convert caller-allocates="0" transfer-ownership="full"> inout parameter, bytes remaining to convert in @inbuf + filename="glib/gconvert.c" + line="157">inout parameter, bytes remaining to convert in @inbuf converted output bytes + filename="glib/gconvert.c" + line="158">converted output bytes caller-allocates="0" transfer-ownership="full"> inout parameter, bytes available to fill in @outbuf + filename="glib/gconvert.c" + line="159">inout parameter, bytes available to fill in @outbuf @@ -67139,32 +72470,32 @@ situation. moved-to="IConv.open" introspectable="0"> Same as the standard UNIX routine iconv_open(), but + filename="glib/gconvert.c" + line="104">Same as the standard UNIX routine iconv_open(), but may be implemented via libiconv on UNIX flavors that lack a native implementation. GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers. - + a "conversion descriptor", or (GIConv)-1 if + filename="glib/gconvert.c" + line="116">a "conversion descriptor", or (GIConv)-1 if opening the converter failed. destination codeset + filename="glib/gconvert.c" + line="106">destination codeset source codeset + filename="glib/gconvert.c" + line="107">source codeset @@ -67174,33 +72505,33 @@ more convenient than the raw iconv wrappers. shadowed-by="idle_add_full" introspectable="0"> Adds a function to be called whenever there are no higher priority + filename="glib/gmain.c" + line="6393">Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the -default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function +default idle priority, [const@GLib.PRIORITY_DEFAULT_IDLE]. If the function returns %FALSE it is automatically removed from the list of event sources and will not be called again. -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -This internally creates a main loop source using g_idle_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. - +This internally creates a main loop source using [func@GLib.idle_source_new] +and attaches it to the global [struct@GLib.MainContext] using +[method@GLib.Source.attach], so the callback will be invoked in whichever +thread is running that main context. You can do these steps manually if you +need greater control or to use a custom main context. + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="6413">the ID (greater than 0) of the event source. function to call + filename="glib/gmain.c" + line="6395">function to call nullable="1" allow-none="1"> data to pass to @function. + filename="glib/gmain.c" + line="6396">data to pass to @function. @@ -67218,34 +72549,35 @@ use a custom main context. c:identifier="g_idle_add_full" shadows="idle_add"> Adds a function to be called whenever there are no higher priority + filename="glib/gmain.c" + line="6358">Adds a function to be called whenever there are no higher priority events pending. -If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically +If the function returns [const@GLib.SOURCE_REMOVE] or %FALSE it is automatically removed from the list of event sources and will not be called again. -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -This internally creates a main loop source using g_idle_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. - +This internally creates a main loop source using [func@GLib.idle_source_new] +and attaches it to the global [struct@GLib.MainContext] using +[method@GLib.Source.attach], so the callback will be invoked in whichever +thread is running that main context. You can do these steps manually if you +need greater control or to use a custom main context. + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="6382">the ID (greater than 0) of the event source. the priority of the idle source. Typically this will be in the - range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. + filename="glib/gmain.c" + line="6360">the priority of the idle source. Typically this will be in the + range between [const@GLib.PRIORITY_DEFAULT_IDLE] and + [const@GLib.PRIORITY_HIGH_IDLE]. closure="2" destroy="3"> function to call + filename="glib/gmain.c" + line="6363">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="6364">data to pass to @function allow-none="1" scope="async"> function to call when the idle is removed, or %NULL + filename="glib/gmain.c" + line="6365">function to call when the idle is removed, or %NULL @@ -67284,27 +72616,27 @@ use a custom main context. version="2.74" introspectable="0"> Adds a function to be called whenever there are no higher priority + filename="glib/gmain.c" + line="6422">Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the -default idle priority, %G_PRIORITY_DEFAULT_IDLE. +default idle priority, [const@GLib.PRIORITY_DEFAULT_IDLE]. The function will only be called once and then the source will be automatically removed from the main context. -This function otherwise behaves like g_idle_add(). - +This function otherwise behaves like [func@GLib.idle_add]. + the ID (greater than 0) of the event source + filename="glib/gmain.c" + line="6436">the ID (greater than 0) of the event source function to call + filename="glib/gmain.c" + line="6424">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="6425">data to pass to @function Removes the idle function with the given data. - + filename="glib/gmain.c" + line="6447">Removes the idle function with the given data. + %TRUE if an idle source was found and removed. + filename="glib/gmain.c" + line="6453">%TRUE if an idle source was found and removed. @@ -67335,27 +72667,28 @@ This function otherwise behaves like g_idle_add(). nullable="1" allow-none="1"> the data for the idle source's callback. + filename="glib/gmain.c" + line="6449">the data for the idle source's callback. Creates a new idle source. + filename="glib/gmain.c" + line="6311">Creates a new idle source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. Note that the default priority for idle sources is -%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which -have a default priority of %G_PRIORITY_DEFAULT. - +The source will not initially be associated with any +[struct@GLib.MainContext] and must be added to one with +[method@GLib.Source.attach] before it will be executed. Note that the +default priority for idle sources is [const@GLib.PRIORITY_DEFAULT_IDLE], as +compared to other sources which have a default priority of +[const@GLib.PRIORITY_DEFAULT]. + the newly-created idle source + filename="glib/gmain.c" + line="6323">the newly-created idle source @@ -67364,88 +72697,92 @@ have a default priority of %G_PRIORITY_DEFAULT. version="2.40" introspectable="0"> A convenience function/macro to log an informational message. Seldom used. + filename="glib/gmessages.c" + line="308">A convenience function/macro to log an informational message. -If g_log_default_handler() is used as the log handler function, a new-line +Seldom used. + +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -Such messages are suppressed by the g_log_default_handler() and -g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is -set appropriately. +Such messages are suppressed by the [func@GLib.log_default_handler] and +[func@GLib.log_writer_default] unless the `G_MESSAGES_DEBUG` or +`DEBUG_INVOCATION` environment variables are set appropriately. If you need +to set the allowed domains at runtime, use +[func@GLib.log_writer_default_set_debug_domains]. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. - +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). + format string, followed by parameters to insert - into the format string (as with printf()) + filename="glib/gmessages.c" + line="310">format string, followed by parameters to insert into the format string + (as with `printf()`) Compares the two #gint64 values being pointed to and returns + filename="glib/ghash.c" + line="2610">Compares the two #gint64 values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL pointers to 64-bit integers as keys in a #GHashTable. - + %TRUE if the two keys match. + filename="glib/ghash.c" + line="2621">%TRUE if the two keys match. a pointer to a #gint64 key + filename="glib/ghash.c" + line="2612">a pointer to a #gint64 key a pointer to a #gint64 key to compare with @v1 + filename="glib/ghash.c" + line="2613">a pointer to a #gint64 key to compare with @v1 Converts a pointer to a #gint64 to a hash value. + filename="glib/ghash.c" + line="2632">Converts a pointer to a #gint64 to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL pointers to 64-bit integer values as keys in a #GHashTable. - + a hash value corresponding to the key. + filename="glib/ghash.c" + line="2642">a hash value corresponding to the key. a pointer to a #gint64 key + filename="glib/ghash.c" + line="2634">a pointer to a #gint64 key Compares the two #gint values being pointed to and returns + filename="glib/ghash.c" + line="2522">Compares the two #gint values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL pointers to integers as keys in a @@ -67454,50 +72791,50 @@ parameter, when using non-%NULL pointers to integers as keys in a Note that this function acts on pointers to #gint, not on #gint directly: if your hash table's keys are of the form `GINT_TO_POINTER (n)`, use g_direct_equal() instead. - + %TRUE if the two keys match. + filename="glib/ghash.c" + line="2537">%TRUE if the two keys match. a pointer to a #gint key + filename="glib/ghash.c" + line="2524">a pointer to a #gint key a pointer to a #gint key to compare with @v1 + filename="glib/ghash.c" + line="2525">a pointer to a #gint key to compare with @v1 Converts a pointer to a #gint to a hash value. + filename="glib/ghash.c" + line="2546">Converts a pointer to a #gint to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when using non-%NULL pointers to integer values as keys in a #GHashTable. Note that this function acts on pointers to #gint, not on #gint directly: if your hash table's keys are of the form `GINT_TO_POINTER (n)`, use g_direct_hash() instead. - + a hash value corresponding to the key. + filename="glib/ghash.c" + line="2558">a hash value corresponding to the key. a pointer to a #gint key + filename="glib/ghash.c" + line="2548">a pointer to a #gint key @@ -67506,8 +72843,8 @@ directly: if your hash table's keys are of the form c:identifier="g_intern_static_string" version="2.10"> Returns a canonical representation for @string. Interned strings + filename="glib/gquark.c" + line="351">Returns a canonical representation for @string. Interned strings can be compared for equality by comparing the pointers, instead of using strcmp(). g_intern_static_string() does not copy the string, therefore @string must not be freed or modified. @@ -67515,11 +72852,11 @@ therefore @string must not be freed or modified. This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. - + a canonical representation for the string + filename="glib/gquark.c" + line="364">a canonical representation for the string @@ -67528,8 +72865,8 @@ variables in C++. nullable="1" allow-none="1"> a static string + filename="glib/gquark.c" + line="353">a static string @@ -67538,19 +72875,19 @@ variables in C++. c:identifier="g_intern_string" version="2.10"> Returns a canonical representation for @string. Interned strings + filename="glib/gquark.c" + line="329">Returns a canonical representation for @string. Interned strings can be compared for equality by comparing the pointers, instead of using strcmp(). This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. - + a canonical representation for the string + filename="glib/gquark.c" + line="341">a canonical representation for the string @@ -67559,8 +72896,8 @@ variables in C++. nullable="1" allow-none="1"> a string + filename="glib/gquark.c" + line="331">a string @@ -67570,33 +72907,33 @@ variables in C++. shadowed-by="io_add_watch_full" introspectable="0"> Adds the #GIOChannel into the default main loop context + filename="glib/giochannel.c" + line="655">Adds the #GIOChannel into the default main loop context with the default priority. - + the event source id + filename="glib/giochannel.c" + line="665">the event source id a #GIOChannel + filename="glib/giochannel.c" + line="657">a #GIOChannel the condition to watch for + filename="glib/giochannel.c" + line="658">the condition to watch for the function to call when the condition is satisfied + filename="glib/giochannel.c" + line="659">the function to call when the condition is satisfied nullable="1" allow-none="1"> user data to pass to @func + filename="glib/giochannel.c" + line="660">user data to pass to @func @@ -67614,37 +72951,37 @@ with the default priority. c:identifier="g_io_add_watch_full" shadows="io_add_watch"> Adds the #GIOChannel into the default main loop context + filename="glib/giochannel.c" + line="612">Adds the #GIOChannel into the default main loop context with the given priority. This internally creates a main loop source using g_io_create_watch() and attaches it to the main loop context with g_source_attach(). You can do these steps manually if you need greater control. - + the event source id + filename="glib/giochannel.c" + line="628">the event source id a #GIOChannel + filename="glib/giochannel.c" + line="614">a #GIOChannel the priority of the #GIOChannel source + filename="glib/giochannel.c" + line="615">the priority of the #GIOChannel source the condition to watch for + filename="glib/giochannel.c" + line="616">the condition to watch for closure="4" destroy="5"> the function to call when the condition is satisfied + filename="glib/giochannel.c" + line="617">the function to call when the condition is satisfied nullable="1" allow-none="1"> user data to pass to @func + filename="glib/giochannel.c" + line="618">user data to pass to @func the function to call when the source is removed + filename="glib/giochannel.c" + line="619">the function to call when the source is removed @@ -67678,21 +73015,21 @@ You can do these steps manually if you need greater control. c:identifier="g_io_channel_error_from_errno" moved-to="IOChannel.error_from_errno"> Converts an `errno` error number to a #GIOChannelError. - + filename="glib/giochannel.c" + line="734">Converts an `errno` error number to a #GIOChannelError. + a #GIOChannelError error number, e.g. + filename="glib/giochannel.c" + line="740">a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. an `errno` error number, e.g. `EINVAL` + filename="glib/giochannel.c" + line="736">an `errno` error number, e.g. `EINVAL` @@ -67706,8 +73043,8 @@ You can do these steps manually if you need greater control. Creates a #GSource that's dispatched when @condition is met for the + filename="glib/giochannel.c" + line="581">Creates a #GSource that's dispatched when @condition is met for the given @channel. For example, if condition is %G_IO_IN, the source will be dispatched when there's data available for reading. @@ -67721,67 +73058,28 @@ at the default priority. On Windows, polling a #GSource created to watch a channel for a socket puts the socket in non-blocking mode. This is a side-effect of the implementation and unavoidable. - + a new #GSource + filename="glib/giochannel.c" + line="601">a new #GSource a #GIOChannel to watch + filename="glib/giochannel.c" + line="583">a #GIOChannel to watch conditions to watch for + filename="glib/giochannel.c" + line="584">conditions to watch for - - The #GIOChannel data type aims to provide a portable method for -using file descriptors, pipes, and sockets, and integrating them -into the [main event loop][glib-The-Main-Event-Loop]. Currently, -full support is available on UNIX platforms, support for Windows -is only partially complete. - -To create a new #GIOChannel on UNIX systems use -g_io_channel_unix_new(). This works for plain file descriptors, -pipes and sockets. Alternatively, a channel can be created for a -file in a system independent manner using g_io_channel_new_file(). - -Once a #GIOChannel has been created, it can be used in a generic -manner with the functions g_io_channel_read_chars(), -g_io_channel_write_chars(), g_io_channel_seek_position(), and -g_io_channel_shutdown(). - -To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], -use g_io_add_watch() or g_io_add_watch_full(). Here you specify which -events you are interested in on the #GIOChannel, and provide a -function to be called whenever these events occur. - -#GIOChannel instances are created with an initial reference count of 1. -g_io_channel_ref() and g_io_channel_unref() can be used to -increment or decrement the reference count respectively. When the -reference count falls to 0, the #GIOChannel is freed. (Though it -isn't closed automatically, unless it was created using -g_io_channel_new_file().) Using g_io_add_watch() or -g_io_add_watch_full() increments a channel's reference count. - -The new functions g_io_channel_read_chars(), -g_io_channel_read_line(), g_io_channel_read_line_string(), -g_io_channel_read_to_end(), g_io_channel_write_chars(), -g_io_channel_seek_position(), and g_io_channel_flush() should not be -mixed with the deprecated functions g_io_channel_read(), -g_io_channel_write(), and g_io_channel_seek() on the same channel. - @@ -67789,173 +73087,65 @@ g_io_channel_write(), and g_io_channel_seek() on the same channel. - - The #GList structure and its associated functions provide a standard -doubly-linked list data structure. The benefit of this data-structure -is to provide insertion/deletion operations in O(1) complexity where -access/search operations are in O(n). The benefit of #GList over -#GSList (singly linked list) is that the worst case on access/search -operations is divided by two which comes at a cost in space as we need -to retain two pointers in place of one. - -Each element in the list contains a piece of data, together with -pointers which link to the previous and next elements in the list. -Using these pointers it is possible to move through the list in both -directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], -which only allows movement through the list in the forward direction). - -The double linked list does not keep track of the number of items -and does not keep track of both the start and end of the list. If -you want fast access to both the start and the end of the list, -and/or the number of items in the list, use a -[GQueue][glib-Double-ended-Queues] instead. - -The data contained in each element can be either integer values, by -using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], -or simply pointers to any type of data. - -List elements are allocated from the [slice allocator][glib-Memory-Slices], -which is more efficient than allocating elements individually. - -Note that most of the #GList functions expect to be passed a pointer -to the first element in the list. The functions which insert -elements return the new start of the list, which may have changed. - -There is no function to create a #GList. %NULL is considered to be -a valid, empty list so you simply set a #GList* to %NULL to initialize -it. - -To add elements, use g_list_append(), g_list_prepend(), -g_list_insert() and g_list_insert_sorted(). - -To visit all elements in the list, use a loop over the list: -|[<!-- language="C" --> -GList *l; -for (l = list; l != NULL; l = l->next) - { - // do something with l->data - } -]| - -To call a function for each element in the list, use g_list_foreach(). - -To loop over the list and modify it (e.g. remove a certain element) -a while loop is more appropriate, for example: -|[<!-- language="C" --> -GList *l = list; -while (l != NULL) - { - GList *next = l->next; - if (should_be_removed (l)) - { - // possibly free l->data - list = g_list_delete_link (list, l); - } - l = next; - } -]| - -To remove elements, use g_list_remove(). - -To navigate in a list, use g_list_first(), g_list_last(), -g_list_next(), g_list_previous(). - -To find elements in the list use g_list_nth(), g_list_nth_data(), -g_list_find() and g_list_find_custom(). - -To find the index of an element use g_list_position() and -g_list_index(). - -To free the entire list, use g_list_free() or g_list_free_full(). - - - The #GSList structure and its associated functions provide a -standard singly-linked list data structure. The benefit of this -data-structure is to provide insertion/deletion operations in O(1) -complexity where access/search operations are in O(n). The benefit -of #GSList over #GList (doubly linked list) is that they are lighter -in space as they only need to retain one pointer but it double the -cost of the worst case access/search operations. - -Each element in the list contains a piece of data, together with a -pointer which links to the next element in the list. Using this -pointer it is possible to move through the list in one direction -only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], -which allow movement in both directions). - -The data contained in each element can be either integer values, by -using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], -or simply pointers to any type of data. - -List elements are allocated from the [slice allocator][glib-Memory-Slices], -which is more efficient than allocating elements individually. - -Note that most of the #GSList functions expect to be passed a -pointer to the first element in the list. The functions which insert -elements return the new start of the list, which may have changed. - -There is no function to create a #GSList. %NULL is considered to be -the empty list so you simply set a #GSList* to %NULL. - -To add elements, use g_slist_append(), g_slist_prepend(), -g_slist_insert() and g_slist_insert_sorted(). - -To remove elements, use g_slist_remove(). - -To find elements in the list use g_slist_last(), g_slist_next(), -g_slist_nth(), g_slist_nth_data(), g_slist_find() and -g_slist_find_custom(). - -To find the index of an element use g_slist_position() and -g_slist_index(). - -To call a function for each element in the list use -g_slist_foreach(). - -To free the entire list, use g_slist_free(). - A convenience macro to get the next element in a #GList. + filename="glib/glist.c" + line="62">A convenience macro to get the next element in a #GList. Note that it is considered perfectly acceptable to access @list->next directly. - + an element in a #GList + filename="glib/glist.c" + line="64">an element in a #GList + + + + + + A convenience macro to get the previous element in a #GList. + filename="glib/glist.c" + line="50">A convenience macro to get the previous element in a #GList. Note that it is considered perfectly acceptable to access @list->prev directly. - + an element in a #GList + filename="glib/glist.c" + line="52">an element in a #GList + + + + + + + + + + + Gets the names of all variables set in the environment. + filename="glib/genviron.c" + line="385">Gets the names of all variables set in the environment. Programs that want to be portable to Windows should typically use this function and g_getenv() instead of using the environ array @@ -67963,11 +73153,11 @@ from the C library directly. On Windows, the strings in the environ array are in system codepage encoding, while in most of the typical use cases for environment variables in GLib-using programs you want the UTF-8 encoding that this function and g_getenv() provide. - + + filename="glib/genviron.c" + line="397"> a %NULL-terminated list of strings which must be freed with g_strfreev(). @@ -67979,21 +73169,21 @@ the UTF-8 encoding that this function and g_getenv() provide. c:identifier="g_locale_from_utf8" throws="1"> Converts a string from UTF-8 to the encoding used for strings by + filename="glib/gconvert.c" + line="976">Converts a string from UTF-8 to the encoding used for strings by the C runtime (usually the same as that used by the operating -system) in the [current locale][setlocale]. On Windows this means -the system codepage. +system) in the [current locale](running.html#locale). +On Windows this means the system codepage. The input string shall not contain nul characters even if the @len argument is positive. A nul character found inside the string will result in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert input that may contain embedded nul characters. - + + filename="glib/gconvert.c" + line="1004"> A newly-allocated buffer containing the converted string, or %NULL on an error, and error will be set. @@ -68003,14 +73193,14 @@ input that may contain embedded nul characters. a UTF-8 encoded string + filename="glib/gconvert.c" + line="978">a UTF-8 encoded string the length of the string, or -1 if the string is + filename="glib/gconvert.c" + line="979">the length of the string, or -1 if the string is nul-terminated. @@ -68021,8 +73211,8 @@ input that may contain embedded nul characters. optional="1" allow-none="1"> location to store the number of bytes in the + filename="glib/gconvert.c" + line="981">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -68039,8 +73229,8 @@ input that may contain embedded nul characters. optional="1" allow-none="1"> the number of bytes stored in the output + filename="glib/gconvert.c" + line="989">the number of bytes stored in the output buffer (not including the terminating nul). @@ -68048,10 +73238,10 @@ input that may contain embedded nul characters. Converts a string which is in the encoding used for strings by + filename="glib/gconvert.c" + line="877">Converts a string which is in the encoding used for strings by the C runtime (usually the same as that used by the operating -system) in the [current locale][setlocale] into a UTF-8 string. +system) in the [current locale](running.html#locale) into a UTF-8 string. If the source encoding is not UTF-8 and the conversion output contains a nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the @@ -68060,18 +73250,18 @@ If the source encoding is UTF-8, an embedded nul character is treated with the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with earlier versions of this library. Use g_convert() to produce output that may contain embedded nul characters. - + The converted string, or %NULL on an error. + filename="glib/gconvert.c" + line="911">The converted string, or %NULL on an error. a string in the + filename="glib/gconvert.c" + line="879">a string in the encoding of the current locale. On Windows this means the system codepage. @@ -68080,8 +73270,8 @@ may contain embedded nul characters. the length of the string, or -1 if the string is + filename="glib/gconvert.c" + line="882">the length of the string, or -1 if the string is nul-terminated (Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe) @@ -68094,8 +73284,8 @@ may contain embedded nul characters. optional="1" allow-none="1"> location to store the number of bytes in the + filename="glib/gconvert.c" + line="886">location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters @@ -68112,8 +73302,8 @@ may contain embedded nul characters. optional="1" allow-none="1"> the number of bytes stored in the output + filename="glib/gconvert.c" + line="894">the number of bytes stored in the output buffer (not including the terminating nul). @@ -68121,20 +73311,20 @@ may contain embedded nul characters. Logs an error or debugging message. + filename="glib/gmessages.c" + line="1298">Logs an error or debugging message. -If the log level has been set as fatal, G_BREAKPOINT() is called -to terminate the program. See the documentation for G_BREAKPOINT() for +If the log level has been set as fatal, [func@GLib.BREAKPOINT] is called +to terminate the program. See the documentation for [func@GLib.BREAKPOINT] for details of the debugging options this provides. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If [structured logging is enabled][using-structured-logging] this will -output via the structured log writer function (see g_log_set_writer_func()). - +If [structured logging is enabled](logging.html#using-structured-logging) this will +output via the structured log writer function (see [func@GLib.log_set_writer_func]). + @@ -68144,62 +73334,67 @@ output via the structured log writer function (see g_log_set_writer_func()). the log domain, usually %G_LOG_DOMAIN, or %NULL + filename="glib/gmessages.c" + line="1300">the log domain, usually `G_LOG_DOMAIN`, or `NULL` for the default the log level, either from #GLogLevelFlags + filename="glib/gmessages.c" + line="1302">the log level, either from [type@GLib.LogLevelFlags] or a user-defined level the message format. See the `printf()` documentation + filename="glib/gmessages.c" + line="1304">the message format. See the `printf()` documentation the parameters to insert into the format string + filename="glib/gmessages.c" + line="1305">the parameters to insert into the format string The default log handler set up by GLib; g_log_set_default_handler() + filename="glib/gmessages.c" + line="3350">The default log handler set up by GLib; [func@GLib.log_set_default_handler] allows to install an alternate default log handler. + This is used if no log handler has been set for the particular log -domain and log level combination. It outputs the message to stderr -or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically +domain and log level combination. It outputs the message to `stderr` +or `stdout` and if the log level is fatal it calls [func@GLib.BREAKPOINT]. It automatically prints a new-line character after the message, so one does not need to be manually included in @message. The behavior of this log handler can be influenced by a number of environment variables: -- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which - messages should be prefixed by the program name and PID of the - application. - -- `G_MESSAGES_DEBUG`: A space-separated list of log domains for - which debug and informational messages are printed. By default - these messages are not printed. - -stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, -%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for -the rest, unless stderr was requested by -g_log_writer_default_set_use_stderr(). + - `G_MESSAGES_PREFIXED`: A `:`-separated list of log levels for which + messages should be prefixed by the program name and PID of the + application. + - `G_MESSAGES_DEBUG`: A space-separated list of log domains for + which debug and informational messages are printed. By default + these messages are not printed. If you need to set the allowed + domains at runtime, use [func@GLib.log_writer_default_set_debug_domains]. + - `DEBUG_INVOCATION`: If set to `1`, this is equivalent to + `G_MESSAGES_DEBUG=all`. `DEBUG_INVOCATION` is a standard environment + variable set by systemd to prompt debug output. (Since: 2.84) + +`stderr` is used for levels [flags@GLib.LogLevelFlags.LEVEL_ERROR], +[flags@GLib.LogLevelFlags.LEVEL_CRITICAL], [flags@GLib.LogLevelFlags.LEVEL_WARNING] and +[flags@GLib.LogLevelFlags.LEVEL_MESSAGE]. `stdout` is used for +the rest, unless `stderr` was requested by +[func@GLib.log_writer_default_set_use_stderr]. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - +[Using Structured Logging](logging.html#using-structured-logging). + @@ -68209,15 +73404,15 @@ This has no effect if structured logging is enabled; see nullable="1" allow-none="1"> the log domain of the message, or %NULL for the -default "" application domain + filename="glib/gmessages.c" + line="3352">the log domain of the message, or `NULL` for the + default `""` application domain the level of the message + filename="glib/gmessages.c" + line="3354">the level of the message nullable="1" allow-none="1"> the message + filename="glib/gmessages.c" + line="3355">the message nullable="1" allow-none="1"> data passed from g_log() which is unused + filename="glib/gmessages.c" + line="3356">data passed from [func@GLib.log] which is unused @@ -68244,46 +73439,47 @@ default "" application domain c:identifier="g_log_get_debug_enabled" version="2.72"> Return whether debug output from the GLib logging system is enabled. + filename="glib/gmessages.c" + line="3016">Return whether debug output from the GLib logging system is enabled. -Note that this should not be used to conditionalise calls to g_debug() or -other logging functions; it should only be used from %GLogWriterFunc +Note that this should not be used to conditionalise calls to [func@GLib.debug] or +other logging functions; it should only be used from [type@GLib.LogWriterFunc] implementations. -Note also that the value of this does not depend on `G_MESSAGES_DEBUG`; see -the docs for g_log_set_debug_enabled(). - +Note also that the value of this does not depend on `G_MESSAGES_DEBUG`, nor +`DEBUG_INVOCATION`, nor [func@GLib.log_writer_default_set_debug_domains]; see +the docs for [func@GLib.log_set_debug_enabled]. + %TRUE if debug output is enabled, %FALSE otherwise + filename="glib/gmessages.c" + line="3029">`TRUE` if debug output is enabled, `FALSE` otherwise Removes the log handler. + filename="glib/gmessages.c" + line="853">Removes the log handler. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - +[Using Structured Logging](logging.html#using-structured-logging). + the log domain + filename="glib/gmessages.c" + line="855">the log domain the id of the handler, which was returned - in g_log_set_handler() + filename="glib/gmessages.c" + line="856">the ID of the handler, which was returned + in [func@GLib.log_set_handler] @@ -68291,11 +73487,12 @@ This has no effect if structured logging is enabled; see Sets the message levels which are always fatal, in any log domain. + filename="glib/gmessages.c" + line="560">Sets the message levels which are always fatal, in any log domain. + When a message with any of these levels is logged the program terminates. You can only set the levels defined by GLib to be fatal. -%G_LOG_LEVEL_ERROR is always fatal. +[flags@GLib.LogLevelFlags.LEVEL_ERROR] is always fatal. You can also make some message levels fatal at runtime by setting the `G_DEBUG` environment variable (see @@ -68304,23 +73501,23 @@ the `G_DEBUG` environment variable (see Libraries should not call this function, as it affects all messages logged by a process, including those from other libraries. -Structured log messages (using g_log_structured() and -g_log_structured_array()) are fatal only if the default log writer is used; +Structured log messages (using [func@GLib.log_structured] and +[func@GLib.log_structured_array]) are fatal only if the default log writer is used; otherwise it is up to the writer function to determine which log messages -are fatal. See [Using Structured Logging][using-structured-logging]. - +are fatal. See [Using Structured Logging](logging.html#using-structured-logging). + the old fatal mask + filename="glib/gmessages.c" + line="583">the old fatal mask the mask containing bits set for each level - of error which is to be fatal + filename="glib/gmessages.c" + line="562">the mask containing bits set for each level of error which is + to be fatal @@ -68329,22 +73526,24 @@ are fatal. See [Using Structured Logging][using-structured-logging]. c:identifier="g_log_set_debug_enabled" version="2.72"> Enable or disable debug output from the GLib logging system for all domains. -This value interacts disjunctively with `G_MESSAGES_DEBUG` — if either of -them would allow a debug message to be outputted, it will be. + filename="glib/gmessages.c" + line="3039">Enable or disable debug output from the GLib logging system for all domains. + +This value interacts disjunctively with `G_MESSAGES_DEBUG`, `DEBUG_INVOCATION` and +[func@GLib.log_writer_default_set_debug_domains] — if any of them would allow +a debug message to be outputted, it will be. Note that this should not be used from within library code to enable debug output — it is intended for external use. - + %TRUE to enable debug output, %FALSE otherwise + filename="glib/gmessages.c" + line="3041">`TRUE` to enable debug output, `FALSE` otherwise @@ -68354,26 +73553,27 @@ output — it is intended for external use. version="2.6" introspectable="0"> Installs a default log handler which is used if no + filename="glib/gmessages.c" + line="781">Installs a default log handler which is used if no log handler has been set for the particular log domain -and log level combination. By default, GLib uses -g_log_default_handler() as default log handler. +and log level combination. + +By default, GLib uses [func@GLib.log_default_handler] as default log handler. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - +[Using Structured Logging](logging.html#using-structured-logging). + the previous default log handler + filename="glib/gmessages.c" + line="795">the previous default log handler the log handler function + filename="glib/gmessages.c" + line="783">the log handler function data passed to the log handler + filename="glib/gmessages.c" + line="784">data passed to the log handler Sets the log levels which are fatal in the given domain. -%G_LOG_LEVEL_ERROR is always fatal. + filename="glib/gmessages.c" + line="607">Sets the log levels which are fatal in the given domain. -This has no effect on structured log messages (using g_log_structured() or -g_log_structured_array()). To change the fatal behaviour for specific log +[flags@GLib.LogLevelFlags.LEVEL_ERROR] is always fatal. + +This has no effect on structured log messages (using [func@GLib.log_structured] or +[func@GLib.log_structured_array]). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using -g_log_set_writer_func(). See -[Using Structured Logging][using-structured-logging]. +[func@GLib.log_set_writer_func]. See +[Using Structured Logging](logging.html#using-structured-logging). This function is mostly intended to be used with -%G_LOG_LEVEL_CRITICAL. You should typically not set -%G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or -%G_LOG_LEVEL_DEBUG as fatal except inside of test programs. - +[flags@GLib.LogLevelFlags.LEVEL_CRITICAL]. You should typically not set +[flags@GLib.LogLevelFlags.LEVEL_WARNING], [flags@GLib.LogLevelFlags.LEVEL_MESSAGE], [flags@GLib.LogLevelFlags.LEVEL_INFO] or +[flags@GLib.LogLevelFlags.LEVEL_DEBUG] as fatal except inside of test programs. + the old fatal mask for the log domain + filename="glib/gmessages.c" + line="627">the old fatal mask for the log domain the log domain + filename="glib/gmessages.c" + line="609">the log domain the new fatal mask + filename="glib/gmessages.c" + line="610">the new fatal mask @@ -68430,46 +73631,49 @@ This function is mostly intended to be used with shadowed-by="log_set_handler_full" introspectable="0"> Sets the log handler for a domain and a set of log levels. + filename="glib/gmessages.c" + line="659">Sets the log handler for a domain and a set of log levels. To handle fatal and recursive messages the @log_levels parameter -must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION +must be combined with the [flags@GLib.LogLevelFlags.FLAG_FATAL] and [flags@GLib.LogLevelFlags.FLAG_RECURSION] bit flags. -Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if +Note that since the [flags@GLib.LogLevelFlags.LEVEL_ERROR] log level is always fatal, if you want to set a handler for this log level you must combine it with -%G_LOG_FLAG_FATAL. +[flags@GLib.LogLevelFlags.FLAG_FATAL]. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). + +The `log_domain` parameter can be set to `NULL` or an empty string to use the default +application domain. Here is an example for adding a log handler for all warning messages in the default domain: -|[<!-- language="C" --> +```c g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| +``` This example adds a log handler for all critical messages from GTK: -|[<!-- language="C" --> +```c g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| +``` This example adds a log handler for all messages from GLib: -|[<!-- language="C" --> +```c g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| - +``` + the id of the new handler + filename="glib/gmessages.c" + line="708">the id of the new handler @@ -68478,24 +73682,24 @@ g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL nullable="1" allow-none="1"> the log domain, or %NULL for the default "" + filename="glib/gmessages.c" + line="661">the log domain application domain the log levels to apply the log handler for. + filename="glib/gmessages.c" + line="663">the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine - the log levels with the %G_LOG_FLAG_FATAL and - %G_LOG_FLAG_RECURSION bit flags. + the log levels with the [flags@GLib.LogLevelFlags.FLAG_FATAL] and + [flags@GLib.LogLevelFlags.FLAG_RECURSION] bit flags. the log handler function + filename="glib/gmessages.c" + line="667">the log handler function data passed to the log handler + filename="glib/gmessages.c" + line="668">data passed to the log handler @@ -68514,16 +73718,19 @@ g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL shadows="log_set_handler" version="2.46"> Like g_log_set_handler(), but takes a destroy notify for the @user_data. + filename="glib/gmessages.c" + line="719">Like [func@GLib.log_set_handler], but takes a destroy notify for the @user_data. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - +[Using Structured Logging](logging.html#using-structured-logging). + +The `log_domain` parameter can be set to `NULL` or an empty string to use the default +application domain. + the id of the new handler + filename="glib/gmessages.c" + line="739">the ID of the new handler @@ -68532,18 +73739,18 @@ This has no effect if structured logging is enabled; see nullable="1" allow-none="1"> the log domain, or %NULL for the default "" + filename="glib/gmessages.c" + line="721">the log domain application domain the log levels to apply the log handler for. + filename="glib/gmessages.c" + line="723">the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine - the log levels with the %G_LOG_FLAG_FATAL and - %G_LOG_FLAG_RECURSION bit flags. + the log levels with the [flags@GLib.LogLevelFlags.FLAG_FATAL] and + [flags@GLib.LogLevelFlags.FLAG_RECURSION] bit flags. the log handler function + filename="glib/gmessages.c" + line="727">the log handler function data passed to the log handler + filename="glib/gmessages.c" + line="728">data passed to the log handler destroy notify for @user_data, or %NULL + filename="glib/gmessages.c" + line="729">destroy notify for @user_data, or `NULL` @@ -68577,41 +73784,40 @@ This has no effect if structured logging is enabled; see c:identifier="g_log_set_writer_func" version="2.50"> Set a writer function which will be called to format and write out each log -message. Each program should set a writer function, or the default writer -(g_log_writer_default()) will be used. + filename="glib/gmessages.c" + line="1936">Set a writer function which will be called to format and write out each log +message. + +Each program should set a writer function, or the default writer +([func@GLib.log_writer_default]) will be used. Libraries **must not** call this function — only programs are allowed to install a writer function, as there must be a single, central point where log messages are formatted and outputted. There can only be one writer function. It is an error to set more than one. - + log writer function, which must not be %NULL + filename="glib/gmessages.c" + line="1938">log writer function, which must not be `NULL` + allow-none="1"> user data to pass to @func + filename="glib/gmessages.c" + line="1939">user data to pass to @func function to free @user_data once it’s - finished with, if non-%NULL + filename="glib/gmessages.c" + line="1940">function to free @user_data once it’s + finished with, if non-`NULL` @@ -68631,21 +73837,21 @@ There can only be one writer function. It is an error to set more than one. Log a message with structured data. + filename="glib/gmessages.c" + line="1502">Log a message with structured data. The message will be passed through to the log writer set by the application -using g_log_set_writer_func(). If the message is fatal (i.e. its log level -is %G_LOG_LEVEL_ERROR), the program will be aborted by calling -G_BREAKPOINT() at the end of this function. If the log writer returns -%G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. -See the documentation for #GLogWriterFunc for information on chaining +using [func@GLib.log_set_writer_func]. If the message is fatal (i.e. its log level +is [flags@GLib.LogLevelFlags.LEVEL_ERROR]), the program will be aborted by calling +[func@GLib.BREAKPOINT] at the end of this function. If the log writer returns +[enum@GLib.LogWriterOutput.UNHANDLED] (failure), no other fallback writers will be tried. +See the documentation for [type@GLib.LogWriterFunc] for information on chaining writers. The structured data is provided as key–value pairs, where keys are UTF-8 strings, and values are arbitrary pointers — typically pointing to UTF-8 strings, but that is not a requirement. To pass binary (non-nul-terminated) -structured data, use g_log_structured_array(). The keys for structured data +structured data, use [func@GLib.log_structured_array]. The keys for structured data should follow the [systemd journal fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) specification. It is suggested that custom keys are namespaced according to @@ -68653,10 +73859,11 @@ the code which sets them. For example, custom keys from GLib all have a `GLIB_` prefix. Note that keys that expect UTF-8 strings (specifically `"MESSAGE"` and -`"GLIB_DOMAIN"`) must be passed as NUL-terminated UTF-8 strings until GLib +`"GLIB_DOMAIN"`) must be passed as nul-terminated UTF-8 strings until GLib version 2.74.1 because the default log handler did not consider the length of the `GLogField`. Starting with GLib 2.74.1 this is fixed and -non-NUL-terminated UTF-8 strings can be passed with their correct length. +non-nul-terminated UTF-8 strings can be passed with their correct length, +with the exception of `"GLIB_DOMAIN"` which was only fixed with GLib 2.82.3. The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will be converted into a @@ -68675,19 +73882,19 @@ Other fields you may commonly want to pass into this function: * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by -the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), -g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including +the logging macros, [func@GLib.DEBUG_HERE], [func@GLib.message], [func@GLib.warning], [func@GLib.critical], +[func@GLib.error], etc, if the symbol `G_LOG_USE_STRUCTURED` is defined before including `glib.h`. For example: -|[<!-- language="C" --> +```c g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", "MY_APPLICATION_CUSTOM_FIELD", "some debug string", "MESSAGE", "This is a debug message about pointer %p and integer %u.", some_pointer, some_integer); -]| +``` Note that each `MESSAGE_ID` must be [uniquely and randomly generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). @@ -68696,13 +73903,13 @@ catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with your software. To pass a user data pointer to the log writer function which is specific to -this logging call, you must use g_log_structured_array() and pass the pointer -as a field with #GLogField.length set to zero, otherwise it will be +this logging call, you must use [func@GLib.log_structured_array] and pass the pointer +as a field with `GLogField.length` set to zero, otherwise it will be interpreted as a string. For example: -|[<!-- language="C" --> +```c const GLogField fields[] = { { "MESSAGE", "This is a debug message.", -1 }, { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, @@ -68710,39 +73917,39 @@ const GLogField fields[] = { { "MY_APPLICATION_STATE", state_object, 0 }, }; g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); -]| +``` Note also that, even if no other structured fields are specified, there must always be a `MESSAGE` key before the format string. The `MESSAGE`-format pair has to be the last of the key-value pairs, and `MESSAGE` is the only -field for which printf()-style formatting is supported. +field for which `printf()`-style formatting is supported. The default writer function for `stdout` and `stderr` will automatically append a new-line character after the message, so you should not add one manually to the format string. - + log domain, usually %G_LOG_DOMAIN + filename="glib/gmessages.c" + line="1504">log domain, usually `G_LOG_DOMAIN` log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="1505">log level, either from [type@GLib.LogLevelFlags], or a user-defined level key-value pairs of structured data to add to the log entry, followed - by the key "MESSAGE", followed by a printf()-style message format, + filename="glib/gmessages.c" + line="1507">key-value pairs of structured data to add to the log entry, followed + by the key `MESSAGE`, followed by a `printf()`-style message format, followed by parameters to insert in the format string @@ -68752,32 +73959,34 @@ manually to the format string. c:identifier="g_log_structured_array" version="2.50"> Log a message with structured data. The message will be passed through to the -log writer set by the application using g_log_set_writer_func(). If the -message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will + filename="glib/gmessages.c" + line="1824">Log a message with structured data. + +The message will be passed through to the log writer set by the application +using [func@GLib.log_set_writer_func]. If the +message is fatal (i.e. its log level is [flags@GLib.LogLevelFlags.LEVEL_ERROR]), the program will be aborted at the end of this function. -See g_log_structured() for more documentation. +See [func@GLib.log_structured] for more documentation. This assumes that @log_level is already present in @fields (typically as the `PRIORITY` field). - + log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="1826">log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data to add + filename="glib/gmessages.c" + line="1828">key–value pairs of structured data to add to the log message @@ -68785,8 +73994,8 @@ This assumes that @log_level is already present in @fields (typically as the number of elements in the @fields array + filename="glib/gmessages.c" + line="1830">number of elements in the @fields array @@ -68794,7 +74003,7 @@ This assumes that @log_level is already present in @fields (typically as the - + @@ -68824,22 +74033,23 @@ This assumes that @log_level is already present in @fields (typically as the Log a message with structured data, accepting the data within a #GVariant. This -version is especially useful for use in other languages, via introspection. + filename="glib/gmessages.c" + line="1707">Log a message with structured data, accepting the data within a [type@GLib.Variant]. -The only mandatory item in the @fields dictionary is the "MESSAGE" which must +This version is especially useful for use in other languages, via introspection. + +The only mandatory item in the @fields dictionary is the `"MESSAGE"` which must contain the text shown to the user. -The values in the @fields dictionary are likely to be of type String -(%G_VARIANT_TYPE_STRING). Array of bytes (%G_VARIANT_TYPE_BYTESTRING) is also +The values in the @fields dictionary are likely to be of type `G_VARIANT_TYPE_STRING`. +Array of bytes (`G_VARIANT_TYPE_BYTESTRING`) is also supported. In this case the message is handled as binary and will be forwarded to the log writer as such. The size of the array should not be higher than -%G_MAXSSIZE. Otherwise it will be truncated to this size. For other types -g_variant_print() will be used to convert the value into a string. +`G_MAXSSIZE`. Otherwise it will be truncated to this size. For other types +[method@GLib.Variant.print] will be used to convert the value into a string. -For more details on its usage and about the parameters, see g_log_structured(). - +For more details on its usage and about the parameters, see [func@GLib.log_structured]. + @@ -68849,21 +74059,21 @@ For more details on its usage and about the parameters, see g_log_structured().< nullable="1" allow-none="1"> log domain, usually %G_LOG_DOMAIN + filename="glib/gmessages.c" + line="1709">log domain, usually `G_LOG_DOMAIN` log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="1710">log level, either from [type@GLib.LogLevelFlags], or a user-defined level a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT) + filename="glib/gmessages.c" + line="1712">a dictionary ([type@GLib.Variant] of the type `G_VARIANT_TYPE_VARDICT`) containing the key-value pairs of message data. @@ -68873,9 +74083,11 @@ containing the key-value pairs of message data. c:identifier="g_log_writer_default" version="2.50"> Format a structured log message and output it to the default log destination -for the platform. On Linux, this is typically the systemd journal, falling + filename="glib/gmessages.c" + line="2857">Format a structured log message and output it to the default log destination +for the platform. + +On Linux, this is typically the systemd journal, falling back to `stdout` or `stderr` if running from the terminal or if output is being redirected to a file. @@ -68883,35 +74095,37 @@ Support for other platform-specific logging mechanisms may be added in future. Distributors of GLib may modify this function to impose their own (documented) platform-specific log writing policies. -This is suitable for use as a #GLogWriterFunc, and is the default writer used -if no other is set using g_log_set_writer_func(). +This is suitable for use as a [type@GLib.LogWriterFunc], and is the default writer used +if no other is set using [func@GLib.log_set_writer_func]. -As with g_log_default_handler(), this function drops debug and informational +As with [func@GLib.log_default_handler], this function drops debug and informational messages unless their log domain (or `all`) is listed in the space-separated -`G_MESSAGES_DEBUG` environment variable. +`G_MESSAGES_DEBUG` environment variable, or `DEBUG_INVOCATION=1` is set in +the environment, or set at runtime by [func@GLib.log_writer_default_set_debug_domains]. -g_log_writer_default() uses the mask set by g_log_set_always_fatal() to -determine which messages are fatal. When using a custom writer func instead it is +[func@GLib.log_writer_default] uses the mask set by [func@GLib.log_set_always_fatal] to +determine which messages are fatal. When using a custom writer function instead it is up to the writer function to determine which log messages are fatal. - + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + filename="glib/gmessages.c" + line="2889">[enum@GLib.LogWriterOutput.HANDLED] on success, + [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="2859">log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming + filename="glib/gmessages.c" + line="2861">key–value pairs of structured data forming the log message @@ -68919,8 +74133,8 @@ up to the writer function to determine which log messages are fatal. number of elements in the @fields array + filename="glib/gmessages.c" + line="2863">number of elements in the @fields array nullable="1" allow-none="1"> user data passed to g_log_set_writer_func() + filename="glib/gmessages.c" + line="2864">user data passed to [func@GLib.log_set_writer_func] + + Reset the list of domains to be logged, that might be initially set by the +`G_MESSAGES_DEBUG` or `DEBUG_INVOCATION` environment variables. + +This function is thread-safe. + + + + + + + `NULL`-terminated array with domains to be printed. + `NULL` or an array with no values means none. Array with a single value `"all"` means all. + + + + Configure whether the built-in log functions -(g_log_default_handler() for the old-style API, and both -g_log_writer_default() and g_log_writer_standard_streams() for the -structured API) will output all log messages to `stderr`. + filename="glib/gmessages.c" + line="1043">Configure whether the built-in log functions will output all log messages to +`stderr`. + +The built-in log functions are [func@GLib.log_default_handler] for the +old-style API, and both [func@GLib.log_writer_default] and +[func@GLib.log_writer_standard_streams] for the structured API. -By default, log messages of levels %G_LOG_LEVEL_INFO and -%G_LOG_LEVEL_DEBUG are sent to `stdout`, and other log messages are +By default, log messages of levels [flags@GLib.LogLevelFlags.LEVEL_INFO] and +[flags@GLib.LogLevelFlags.LEVEL_DEBUG] are sent to `stdout`, and other log messages are sent to `stderr`. This is problematic for applications that intend to reserve `stdout` for structured output such as JSON or XML. This function sets global state. It is not thread-aware, and should be called at the very start of a program, before creating any other threads or creating objects that could create worker threads of their own. - + If %TRUE, use `stderr` for log messages that would + filename="glib/gmessages.c" + line="1045">If `TRUE`, use `stderr` for log messages that would normally have appeared on `stdout` @@ -68970,47 +74212,47 @@ or creating objects that could create worker threads of their own. c:identifier="g_log_writer_default_would_drop" version="2.68"> Check whether g_log_writer_default() and g_log_default_handler() would + filename="glib/gmessages.c" + line="2812">Check whether [func@GLib.log_writer_default] and [func@GLib.log_default_handler] would ignore a message with the given domain and level. -As with g_log_default_handler(), this function drops debug and informational +As with [func@GLib.log_default_handler], this function drops debug and informational messages unless their log domain (or `all`) is listed in the space-separated -`G_MESSAGES_DEBUG` environment variable. +`G_MESSAGES_DEBUG` environment variable, or `DEBUG_INVOCATION=1` is set in +the environment, or by [func@GLib.log_writer_default_set_debug_domains]. This can be used when implementing log writers with the same filtering behaviour as the default, but a different destination or output format: -|[<!-- language="C" --> - if (g_log_writer_default_would_drop (log_level, log_domain)) - return G_LOG_WRITER_HANDLED; +```c +if (g_log_writer_default_would_drop (log_level, log_domain)) + return G_LOG_WRITER_HANDLED; ]| or to skip an expensive computation if it is only needed for a debugging -message, and `G_MESSAGES_DEBUG` is not set: +message, and `G_MESSAGES_DEBUG` and `DEBUG_INVOCATION` are not set: -|[<!-- language="C" --> - if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) - { - gchar *result = expensive_computation (my_object); +```c +if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) + { + g_autofree gchar *result = expensive_computation (my_object); - g_debug ("my_object result: %s", result); - g_free (result); - } -]| - + g_debug ("my_object result: %s", result); + } +``` + %TRUE if the log message would be dropped by GLib's - default log handlers + filename="glib/gmessages.c" + line="2846">`TRUE` if the log message would be dropped by GLib’s + default log handlers log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="2815">log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -69019,8 +74261,8 @@ message, and `G_MESSAGES_DEBUG` is not set: nullable="1" allow-none="1"> log domain + filename="glib/gmessages.c" + line="2814">log domain @@ -69029,36 +74271,38 @@ message, and `G_MESSAGES_DEBUG` is not set: c:identifier="g_log_writer_format_fields" version="2.50"> Format a structured log message as a string suitable for outputting to the -terminal (or elsewhere). This will include the values of all fields it knows + filename="glib/gmessages.c" + line="2125">Format a structured log message as a string suitable for outputting to the +terminal (or elsewhere). + +This will include the values of all fields it knows how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the -documentation for g_log_structured()). It does not include values from +documentation for [func@GLib.log_structured]). It does not include values from unknown fields. The returned string does **not** have a trailing new-line character. It is encoded in the character set of the current locale, which is not necessarily UTF-8. - + string containing the formatted log message, in + filename="glib/gmessages.c" + line="2148">string containing the formatted log message, in the character set of the current locale log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="2127">log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming + filename="glib/gmessages.c" + line="2129">key–value pairs of structured data forming the log message @@ -69066,15 +74310,16 @@ UTF-8. number of elements in the @fields array + filename="glib/gmessages.c" + line="2131">number of elements in the @fields array %TRUE to use ANSI color escape sequences when formatting the - message, %FALSE to not + filename="glib/gmessages.c" + line="2132">`TRUE` to use + [ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) + when formatting the message, `FALSE` to not @@ -69083,28 +74328,28 @@ UTF-8. c:identifier="g_log_writer_is_journald" version="2.50"> Check whether the given @output_fd file descriptor is a connection to the + filename="glib/gmessages.c" + line="2096">Check whether the given @output_fd file descriptor is a connection to the systemd journal, or something else (like a log file or `stdout` or `stderr`). -Invalid file descriptors are accepted and return %FALSE, which allows for +Invalid file descriptors are accepted and return `FALSE`, which allows for the following construct without needing any additional error handling: -|[<!-- language="C" --> - is_journald = g_log_writer_is_journald (fileno (stderr)); -]| - +```c +is_journald = g_log_writer_is_journald (fileno (stderr)); +``` + %TRUE if @output_fd points to the journal, %FALSE otherwise + filename="glib/gmessages.c" + line="2110">`TRUE` if @output_fd points to the journal, `FALSE` otherwise output file descriptor to check + filename="glib/gmessages.c" + line="2098">output file descriptor to check @@ -69113,35 +74358,37 @@ the following construct without needing any additional error handling: c:identifier="g_log_writer_journald" version="2.50"> Format a structured log message and send it to the systemd journal as a set -of key–value pairs. All fields are sent to the journal, but if a field has + filename="glib/gmessages.c" + line="2458">Format a structured log message and send it to the systemd journal as a set +of key–value pairs. + +All fields are sent to the journal, but if a field has length zero (indicating program-specific data) then only its key will be sent. -This is suitable for use as a #GLogWriterFunc. +This is suitable for use as a [type@GLib.LogWriterFunc]. If GLib has been compiled without systemd support, this function is still -defined, but will always return %G_LOG_WRITER_UNHANDLED. - +defined, but will always return [enum@GLib.LogWriterOutput.UNHANDLED]. + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + filename="glib/gmessages.c" + line="2479">[enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="2460">log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming + filename="glib/gmessages.c" + line="2462">key–value pairs of structured data forming the log message @@ -69149,8 +74396,8 @@ defined, but will always return %G_LOG_WRITER_UNHANDLED. number of elements in the @fields array + filename="glib/gmessages.c" + line="2464">number of elements in the @fields array nullable="1" allow-none="1"> user data passed to g_log_set_writer_func() + filename="glib/gmessages.c" + line="2465">user data passed to [func@GLib.log_set_writer_func] @@ -69168,40 +74415,44 @@ defined, but will always return %G_LOG_WRITER_UNHANDLED. c:identifier="g_log_writer_standard_streams" version="2.50"> Format a structured log message and print it to either `stdout` or `stderr`, -depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages + filename="glib/gmessages.c" + line="2571">Format a structured log message and print it to either `stdout` or `stderr`, +depending on its log level. + +[flags@GLib.LogLevelFlags.LEVEL_INFO] and [flags@GLib.LogLevelFlags.LEVEL_DEBUG] messages are sent to `stdout`, or to `stderr` if requested by -g_log_writer_default_set_use_stderr(); +[func@GLib.log_writer_default_set_use_stderr]; all other log levels are sent to `stderr`. Only fields which are understood by this function are included in the formatted string which is printed. -If the output stream supports ANSI color escape sequences, they will be used -in the output. +If the output stream supports +[ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code), +they will be used in the output. A trailing new-line character is added to the log message when it is printed. -This is suitable for use as a #GLogWriterFunc. - +This is suitable for use as a [type@GLib.LogWriterFunc]. + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + filename="glib/gmessages.c" + line="2598">[enum@GLib.LogWriterOutput.HANDLED] on success, + [enum@GLib.LogWriterOutput.UNHANDLED] otherwise log level, either from #GLogLevelFlags, or a user-defined + filename="glib/gmessages.c" + line="2573">log level, either from [type@GLib.LogLevelFlags], or a user-defined level key–value pairs of structured data forming + filename="glib/gmessages.c" + line="2575">key–value pairs of structured data forming the log message @@ -69209,8 +74460,8 @@ This is suitable for use as a #GLogWriterFunc. number of elements in the @fields array + filename="glib/gmessages.c" + line="2577">number of elements in the @fields array nullable="1" allow-none="1"> user data passed to g_log_set_writer_func() + filename="glib/gmessages.c" + line="2578">user data passed to [func@GLib.log_set_writer_func] @@ -69228,42 +74479,104 @@ This is suitable for use as a #GLogWriterFunc. c:identifier="g_log_writer_supports_color" version="2.50"> Check whether the given @output_fd file descriptor supports ANSI color -escape sequences. If so, they can safely be used when formatting log -messages. - + filename="glib/gmessages.c" + line="1980">Check whether the given @output_fd file descriptor supports +[ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code). + +If so, they can safely be used when formatting log messages. + %TRUE if ANSI color escapes are supported, %FALSE otherwise + filename="glib/gmessages.c" + line="1989">`TRUE` if ANSI color escapes are supported, `FALSE` otherwise output file descriptor to check + filename="glib/gmessages.c" + line="1982">output file descriptor to check + + Format a structured log message and send it to the syslog daemon. Only fields +which are understood by this function are included in the formatted string +which is printed. + +Log facility will be defined via the SYSLOG_FACILITY field and accepts the following +values: "auth", "daemon", and "user". If SYSLOG_FACILITY is not specified, LOG_USER +facility will be used. + +This is suitable for use as a [type@GLib.LogWriterFunc]. + +If syslog is not supported, this function is still defined, but will always +return [enum@GLib.LogWriterOutput.UNHANDLED]. + + + [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise + + + + + log level, either from [type@GLib.LogLevelFlags], or a user-defined + level + + + + key–value pairs of structured data forming + the log message + + + + + + number of elements in the @fields array + + + + user data passed to [func@GLib.log_set_writer_func] + + + + Logs an error or debugging message. + filename="glib/gmessages.c" + line="1135">Logs an error or debugging message. -If the log level has been set as fatal, G_BREAKPOINT() is called -to terminate the program. See the documentation for G_BREAKPOINT() for +If the log level has been set as fatal, [func@GLib.BREAKPOINT] is called +to terminate the program. See the documentation for [func@GLib.BREAKPOINT] for details of the debugging options this provides. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If [structured logging is enabled][using-structured-logging] this will -output via the structured log writer function (see g_log_set_writer_func()). - +If [structured logging is enabled](logging.html#using-structured-logging) this will +output via the structured log writer function (see [func@GLib.log_set_writer_func]). + +The `log_domain` parameter can be set to `NULL` or an empty string to use the default +application domain. + @@ -69273,35 +74586,70 @@ output via the structured log writer function (see g_log_set_writer_func()). the log domain, or %NULL for the default "" -application domain + filename="glib/gmessages.c" + line="1137">the log domain + application domain the log level + filename="glib/gmessages.c" + line="1139">the log level the message format. See the printf() documentation + filename="glib/gmessages.c" + line="1140">the message format. See the `printf()` documentation the parameters to insert into the format string + filename="glib/gmessages.c" + line="1141">the parameters to insert into the format string + + A wrapper for the POSIX lstat() function. The lstat() function is +like stat() except that in the case of symbolic links, it returns +information about the symbolic link itself and not the file that it +refers to. If the system does not support symbolic links g_lstat() +is identical to g_stat(). + +See your C library manual for more details about lstat(). + + + 0 if the information was successfully retrieved, + -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pointer to a stat struct, which will be filled with the file + information + + + + - + @@ -69310,13 +74658,25 @@ application domain - + + + + + + + + + - + @@ -69325,7 +74685,7 @@ application domain - + @@ -69334,162 +74694,26 @@ application domain - + - - These macros provide a few commonly-used features. - - - These macros provide more specialized features which are not -needed so often by application programmers. - - - The main event loop manages all the available sources of events for -GLib and GTK applications. These events can come from any number of -different types of sources such as file descriptors (plain files, -pipes or sockets) and timeouts. New types of event sources can also -be added using g_source_attach(). - -To allow multiple independent sets of sources to be handled in -different threads, each source is associated with a #GMainContext. -A #GMainContext can only be running in a single thread, but -sources can be added to it and removed from it from other threads. All -functions which operate on a #GMainContext or a built-in #GSource are -thread-safe. - -Each event source is assigned a priority. The default priority, -%G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. -Values greater than 0 denote lower priorities. Events from high priority -sources are always processed before events from lower priority sources: if -several sources are ready to dispatch, the ones with equal-highest priority -will be dispatched on the current #GMainContext iteration, and the rest wait -until a subsequent #GMainContext iteration when they have the highest -priority of the sources which are ready for dispatch. - -Idle functions can also be added, and assigned a priority. These will -be run whenever no events with a higher priority are ready to be dispatched. - -The #GMainLoop data type represents a main event loop. A GMainLoop is -created with g_main_loop_new(). After adding the initial event sources, -g_main_loop_run() is called. This continuously checks for new events from -each of the event sources and dispatches them. Finally, the processing of -an event from one of the sources leads to a call to g_main_loop_quit() to -exit the main loop, and g_main_loop_run() returns. - -It is possible to create new instances of #GMainLoop recursively. -This is often used in GTK applications when showing modal dialog -boxes. Note that event sources are associated with a particular -#GMainContext, and will be checked and dispatched for all main -loops associated with that GMainContext. - -GTK contains wrappers of some of these functions, e.g. gtk_main(), -gtk_main_quit() and gtk_events_pending(). - -## Creating new source types - -One of the unusual features of the #GMainLoop functionality -is that new types of event source can be created and used in -addition to the builtin type of event source. A new event source -type is used for handling GDK events. A new source type is created -by "deriving" from the #GSource structure. The derived type of -source is represented by a structure that has the #GSource structure -as a first element, and other elements specific to the new source -type. To create an instance of the new source type, call -g_source_new() passing in the size of the derived structure and -a table of functions. These #GSourceFuncs determine the behavior of -the new source type. - -New source types basically interact with the main context -in two ways. Their prepare function in #GSourceFuncs can set a timeout -to determine the maximum amount of time that the main loop will sleep -before checking the source again. In addition, or as well, the source -can add file descriptors to the set that the main context checks using -g_source_add_poll(). - -## Customizing the main loop iteration - -Single iterations of a #GMainContext can be run with -g_main_context_iteration(). In some cases, more detailed control -of exactly how the details of the main loop work is desired, for -instance, when integrating the #GMainLoop with an external main loop. -In such cases, you can call the component functions of -g_main_context_iteration() directly. These functions are -g_main_context_prepare(), g_main_context_query(), -g_main_context_check() and g_main_context_dispatch(). - -If the event loop thread releases #GMainContext ownership until the results -required by g_main_context_check() are ready you must create a context with -the flag %G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING or else you'll lose -g_source_attach() notifications. This happens for instance when you integrate -the GLib event loop into implementations that follow the proactor pattern -(i.e. in these contexts the `poll()` implementation will reclaim the thread for -other tasks until the results are ready). One example of the proactor pattern -is the Boost.Asio library. - -## State of a Main Context # {#mainloop-states} - -The operation of these functions can best be seen in terms -of a state diagram, as shown in this image. - -![](mainloop-states.gif) - -On UNIX, the GLib mainloop is incompatible with fork(). Any program -using the mainloop must either exec() or exit() from the child -without returning to the mainloop. - -## Memory management of sources # {#mainloop-memory-management} - -There are two options for memory management of the user data passed to a -#GSource to be passed to its callback on invocation. This data is provided -in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and -more generally, using g_source_set_callback(). This data is typically an -object which ‘owns’ the timeout or idle callback, such as a widget or a -network protocol implementation. In many cases, it is an error for the -callback to be invoked after this owning object has been destroyed, as that -results in use of freed memory. - -The first, and preferred, option is to store the source ID returned by -functions such as g_timeout_add() or g_source_attach(), and explicitly -remove that source from the main context using g_source_remove() when the -owning object is finalized. This ensures that the callback can only be -invoked while the object is still alive. - -The second option is to hold a strong reference to the object in the -callback, and to release it in the callback’s #GDestroyNotify. This ensures -that the object is kept alive until after the source is finalized, which is -guaranteed to be after it is invoked for the final time. The #GDestroyNotify -is another callback passed to the ‘full’ variants of #GSource functions (for -example, g_timeout_add_full()). It is called when the source is finalized, -and is designed for releasing references like this. - -One important caveat of this second approach is that it will keep the object -alive indefinitely if the main loop is stopped before the #GSource is -invoked, which may be undesirable. - Returns the global-default main context. This is the main context + filename="glib/gmain.c" + line="687">Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the "main" main loop. See also -g_main_context_get_thread_default(). - +[func@GLib.MainContext.get_thread_default]. + the global-default main context. + filename="glib/gmain.c" + line="695">the global-default main context. @@ -69498,23 +74722,23 @@ g_main_context_get_thread_default(). moved-to="MainContext.get_thread_default" version="2.22"> Gets the thread-default #GMainContext for this thread. Asynchronous + filename="glib/gmain.c" + line="846">Gets the thread-default #GMainContext for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or -g_main_context_ref_thread_default() to get a #GMainContext to add -their #GSources to. (Note that even in single-threaded -programs applications may sometimes want to temporarily push a -non-default context, so it is not safe to assume that this will -always return %NULL if you are running in the default thread.) +[func@GLib.MainContext.ref_thread_default] to get a +[struct@GLib.MainContext] to add their [struct@GLib.Source]s to. (Note that +even in single-threaded programs applications may sometimes want to +temporarily push a non-default context, so it is not safe to assume that +this will always return %NULL if you are running in the default thread.) If you need to hold a reference on the context, use -g_main_context_ref_thread_default() instead. - +[func@GLib.MainContext.ref_thread_default] instead. + the thread-default #GMainContext, or + filename="glib/gmain.c" + line="861">the thread-default #GMainContext, or %NULL if the thread-default context is the global-default main context. @@ -69524,19 +74748,20 @@ g_main_context_ref_thread_default() instead. moved-to="MainContext.ref_thread_default" version="2.32"> Gets the thread-default #GMainContext for this thread, as with -g_main_context_get_thread_default(), but also adds a reference to -it with g_main_context_ref(). In addition, unlike -g_main_context_get_thread_default(), if the thread-default context -is the global-default context, this will return that #GMainContext -(with a ref added to it) rather than returning %NULL. - + filename="glib/gmain.c" + line="878">Gets the thread-default [struct@GLib.MainContext] for this thread, as with +[func@GLib.MainContext.get_thread_default], but also adds a reference to +it with [method@GLib.MainContext.ref]. In addition, unlike +[func@GLib.MainContext.get_thread_default], if the thread-default context +is the global-default context, this will return that +[struct@GLib.MainContext] (with a ref added to it) rather than returning +%NULL. + the thread-default #GMainContext. Unref - with g_main_context_unref() when you are done with it. + filename="glib/gmain.c" + line="889">the thread-default #GMainContext. Unref + with [method@GLib.MainContext.unref] when you are done with it. @@ -69544,25 +74769,25 @@ is the global-default context, this will return that #GMainContext c:identifier="g_main_current_source" version="2.12"> Returns the currently firing source for this thread. - + filename="glib/gmain.c" + line="3156">Returns the currently firing source for this thread. + The currently firing source or %NULL. + filename="glib/gmain.c" + line="3161">The currently firing source or %NULL. Returns the depth of the stack of calls to -g_main_context_dispatch() on any #GMainContext in the current thread. + filename="glib/gmain.c" + line="3042">Returns the depth of the stack of calls to +[method@GLib.MainContext.dispatch] on any #GMainContext in the current thread. That is, when called from the toplevel, it gives 0. When -called from within a callback from g_main_context_iteration() -(or g_main_loop_run(), etc.) it returns 1. When called from within -a callback to a recursive call to g_main_context_iteration(), +called from within a callback from [method@GLib.MainContext.iteration] +(or [method@GLib.MainLoop.run], etc.) it returns 1. When called from within +a callback to a recursive call to [method@GLib.MainContext.iteration], it returns 2. And so forth. This function is useful in a situation like the following: @@ -69603,7 +74828,7 @@ thing from a library, it gets more difficult, since you no longer control the main loop. You might think you can simply use an idle function to make the call to free_allocated_memory(), but that doesn't work, since the idle function could be called from a -recursive callback. This can be fixed by using g_main_depth() +recursive callback. This can be fixed by using [func@GLib.main_depth] |[<!-- language="C" --> gpointer @@ -69638,12 +74863,12 @@ free_allocated_memory (void) } ]| -There is a temptation to use g_main_depth() to solve +There is a temptation to use [func@GLib.main_depth] to solve problems with reentrancy. For instance, while waiting for data to be received from the network in response to a menu item, the menu item might be selected again. It might seem that one could make the menu item's callback return immediately -and do nothing if g_main_depth() returns a value greater than 1. +and do nothing if [func@GLib.main_depth] returns a value greater than 1. However, this should be avoided since the user then sees selecting the menu item do nothing. Furthermore, you'll find yourself adding these checks all over your code, since there are doubtless many, @@ -69658,179 +74883,274 @@ following techniques: arbitrary callbacks. Instead, structure your code so that you simply return to the main loop and then get called again when there is more work to do. - + The main loop recursion level in the current thread + filename="glib/gmain.c" + line="3147">The main loop recursion level in the current thread + + Frees the memory allocated for the #GMainLoop. + Use g_main_loop_unref() instead + + + + a #GMainLoop + + + + + Checks if the main loop is running. + Use g_main_loop_is_running() instead + + + + a #GMainLoop + + + + + Runs a single iteration for the default #GMainContext. + Use g_main_context_iteration() instead. + + + + set to %TRUE if it should block (i.e. wait) until an event + source becomes ready. It will return after an event source has been + processed. If set to %FALSE it will return immediately if no event + source is ready to be processed. + + + + + Creates a new #GMainLoop for th default main context. + Use g_main_loop_new() instead + + + + set to %TRUE to indicate that the loop is running. This + is not very important since calling g_main_run() will set this + to %TRUE anyway. + + + + + Checks if any events are pending for the default #GMainContext +(i.e. ready to be processed). + Use g_main_context_pending() instead. + + + + Stops the #GMainLoop. +If g_main_run() was called to run the #GMainLoop, it will now return. + Use g_main_loop_quit() instead + + + + a #GMainLoop + + + + + Runs a main loop until it stops running. + Use g_main_loop_run() instead + + + + a #GMainLoop + + + + + Sets the function to use for the handle polling of file descriptors +for the default main context. + Use g_main_context_set_poll_func() again + + + + the function to call to poll all file descriptors + + + Allocates @n_bytes bytes of memory. + filename="glib/gmem.c" + line="81">Allocates @n_bytes bytes of memory. If @n_bytes is 0 it returns %NULL. If the allocation fails (because the system is out of memory), the program is terminated. - + a pointer to the allocated memory + filename="glib/gmem.c" + line="91">a pointer to the allocated memory the number of bytes to allocate + filename="glib/gmem.c" + line="83">the number of bytes to allocate Allocates @n_bytes bytes of memory, initialized to 0's. + filename="glib/gmem.c" + line="114">Allocates @n_bytes bytes of memory, initialized to 0's. If @n_bytes is 0 it returns %NULL. If the allocation fails (because the system is out of memory), the program is terminated. - + a pointer to the allocated memory + filename="glib/gmem.c" + line="124">a pointer to the allocated memory the number of bytes to allocate + filename="glib/gmem.c" + line="116">the number of bytes to allocate This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, + filename="glib/gmem.c" + line="413">This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. - + a pointer to the allocated memory + filename="glib/gmem.c" + line="425">a pointer to the allocated memory the number of blocks to allocate + filename="glib/gmem.c" + line="415">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="416">the size of each block in bytes This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, + filename="glib/gmem.c" + line="386">This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. - + a pointer to the allocated memory + filename="glib/gmem.c" + line="398">a pointer to the allocated memory the number of blocks to allocate + filename="glib/gmem.c" + line="388">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="389">the size of each block in bytes - - The "GMarkup" parser is intended to parse a simple markup format -that's a subset of XML. This is a small, efficient, easy-to-use -parser. It should not be used if you expect to interoperate with -other applications generating full-scale XML, and must not be used if you -expect to parse untrusted input. However, it's very -useful for application data files, config files, etc. where you -know your application will be the only one writing the file. -Full-scale XML parsers should be able to parse the subset used by -GMarkup, so you can easily migrate to full-scale XML at a later -time if the need arises. - -GMarkup is not guaranteed to signal an error on all invalid XML; -the parser may accept documents that an XML parser would not. -However, XML documents which are not well-formed (which is a -weaker condition than being valid. See the -[XML specification](http://www.w3.org/TR/REC-xml/) -for definitions of these terms.) are not considered valid GMarkup -documents. - -Simplifications to XML include: - -- Only UTF-8 encoding is allowed - -- No user-defined entities - -- Processing instructions, comments and the doctype declaration - are "passed through" but are not interpreted in any way - -- No DTD or validation - -The markup format does support: - -- Elements - -- Attributes - -- 5 standard entities: &amp; &lt; &gt; &quot; &apos; - -- Character references - -- Sections marked as CDATA - -## An example parser # {#example} - -Here is an example for a markup parser: -[markup-example.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/markup-example.c) - Collects the attributes of the element from the data passed to the + filename="glib/gmarkup.c" + line="2651">Collects the attributes of the element from the data passed to the #GMarkupParser start_element function, dealing with common error conditions and supporting boolean values. @@ -69862,54 +75182,54 @@ attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well as parse errors for boolean-valued attributes (again of type %G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE will be returned and @error will be set as appropriate. - + %TRUE if successful + filename="glib/gmarkup.c" + line="2696">%TRUE if successful the current tag name + filename="glib/gmarkup.c" + line="2653">the current tag name the attribute names + filename="glib/gmarkup.c" + line="2654">the attribute names the attribute values + filename="glib/gmarkup.c" + line="2655">the attribute values a pointer to a #GError or %NULL + filename="glib/gmarkup.c" + line="2656">a pointer to a #GError or %NULL the #GMarkupCollectType of the first attribute + filename="glib/gmarkup.c" + line="2657">the #GMarkupCollectType of the first attribute the name of the first attribute + filename="glib/gmarkup.c" + line="2658">the name of the first attribute a pointer to the storage location of the first attribute + filename="glib/gmarkup.c" + line="2659">a pointer to the storage location of the first attribute (or %NULL), followed by more types names and pointers, ending with %G_MARKUP_COLLECT_INVALID @@ -69923,8 +75243,8 @@ will be returned and @error will be set as appropriate. Escapes text so that the markup parser will parse it verbatim. + filename="glib/gmarkup.c" + line="2233">Escapes text so that the markup parser will parse it verbatim. Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This function would typically be used when writing out a file to be parsed with the markup parser. @@ -69938,24 +75258,24 @@ the range of &#x1; ... &#x1f; for all control sequences except for tabstop, newline and carriage return. The character references in this range are not valid XML 1.0, but they are valid XML 1.1 and will be accepted by the GMarkup parser. - + a newly allocated string with the escaped text + filename="glib/gmarkup.c" + line="2253">a newly allocated string with the escaped text some valid UTF-8 text + filename="glib/gmarkup.c" + line="2235">some valid UTF-8 text length of @text in bytes, or -1 if the text is nul-terminated + filename="glib/gmarkup.c" + line="2236">length of @text in bytes, or -1 if the text is nul-terminated @@ -69965,8 +75285,8 @@ valid XML 1.1 and will be accepted by the GMarkup parser. version="2.4" introspectable="0"> Formats arguments according to @format, escaping + filename="glib/gmarkup.c" + line="2544">Formats arguments according to @format, escaping all string and character arguments in the fashion of g_markup_escape_text(). This is useful when you want to insert literal strings into XML-style markup @@ -69984,25 +75304,25 @@ output = g_markup_printf_escaped ("<purchase>" "</purchase>", store, item); ]| - + newly allocated result from formatting + filename="glib/gmarkup.c" + line="2568">newly allocated result from formatting operation. Free with g_free(). printf() style format string + filename="glib/gmarkup.c" + line="2546">printf() style format string the arguments to insert in the format string + filename="glib/gmarkup.c" + line="2547">the arguments to insert in the format string @@ -70012,51 +75332,72 @@ output = g_markup_printf_escaped ("<purchase>" version="2.4" introspectable="0"> Formats the data in @args according to @format, escaping + filename="glib/gmarkup.c" + line="2399">Formats the data in @args according to @format, escaping all string and character arguments in the fashion of g_markup_escape_text(). See g_markup_printf_escaped(). - + newly allocated result from formatting + filename="glib/gmarkup.c" + line="2408">newly allocated result from formatting operation. Free with g_free(). printf() style format string + filename="glib/gmarkup.c" + line="2401">printf() style format string variable argument list, similar to vprintf() + filename="glib/gmarkup.c" + line="2402">variable argument list, similar to vprintf() + + + + + + + + + + + + + + + + + Checks whether the allocator used by g_malloc() is the system's + filename="glib/gmem.c" + line="534">Checks whether the allocator used by g_malloc() is the system's malloc implementation. If it returns %TRUE memory allocated with malloc() can be used interchangeably with memory allocated using g_malloc(). This function is useful for avoiding an extra copy of allocated memory returned by a non-GLib-based API. GLib always uses the system malloc, so this function always returns %TRUE. - + if %TRUE, malloc() and g_malloc() can be mixed. + filename="glib/gmem.c" + line="543">if %TRUE, malloc() and g_malloc() can be mixed. @@ -70065,12 +75406,12 @@ returns %TRUE. deprecated="1" deprecated-version="2.46"> GLib used to support some tools for memory profiling, but this + filename="glib/gmem.c" + line="583">GLib used to support some tools for memory profiling, but this no longer works. There are many other useful tools for memory profiling these days which can be used instead. Use other memory profiling tools instead - + @@ -70080,22 +75421,22 @@ profiling these days which can be used instead. deprecated="1" deprecated-version="2.46"> This function used to let you override the memory allocation function. + filename="glib/gmem.c" + line="554">This function used to let you override the memory allocation function. However, its use was incompatible with the use of global constructors in GLib and GIO, because those use the GLib allocators before main is reached. Therefore this function is now deprecated and is just a stub. This function now does nothing. Use other memory profiling tools instead - + table of memory allocation routines. + filename="glib/gmem.c" + line="556">table of memory allocation routines. @@ -70105,18 +75446,17 @@ profiling tools instead deprecated="1" deprecated-version="2.68"> Allocates @byte_size bytes of memory, and copies @byte_size bytes into it -from @mem. If @mem is %NULL it returns %NULL. - Use g_memdup2() instead, as it accepts a #gsize argument - for @byte_size, avoiding the possibility of overflow in a #gsize → #guint - conversion - - + filename="glib/gstrfuncs.c" + line="332">Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is `NULL` it returns `NULL`. + Use [func@GLib.memdup2] instead, as it accepts a gsize argument + for @byte_size, avoiding the possibility of overflow in a `gsize` → `guint` + conversion + + a pointer to the newly-allocated copy of the memory, or %NULL if @mem - is %NULL. + filename="glib/gstrfuncs.c" + line="340">a pointer to the newly-allocated copy of the memory @@ -70125,32 +75465,31 @@ from @mem. If @mem is %NULL it returns %NULL. nullable="1" allow-none="1"> the memory to copy. + filename="glib/gstrfuncs.c" + line="334">the memory to copy the number of bytes to copy. + filename="glib/gstrfuncs.c" + line="335">the number of bytes to copy Allocates @byte_size bytes of memory, and copies @byte_size bytes into it -from @mem. If @mem is %NULL it returns %NULL. + filename="glib/gstrfuncs.c" + line="363">Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is `NULL` it returns `NULL`. -This replaces g_memdup(), which was prone to integer overflows when -converting the argument from a #gsize to a #guint. - - +This replaces [func@GLib.memdup], which was prone to integer overflows when +converting the argument from a `gsize` to a `guint`. + + a pointer to the newly-allocated copy of the memory, - or %NULL if @mem is %NULL. + filename="glib/gstrfuncs.c" + line="374">a pointer to the newly-allocated copy of the memory @@ -70159,14 +75498,14 @@ converting the argument from a #gsize to a #guint. nullable="1" allow-none="1"> the memory to copy. + filename="glib/gstrfuncs.c" + line="365">the memory to copy the number of bytes to copy. + filename="glib/gstrfuncs.c" + line="366">the number of bytes to copy @@ -70177,302 +75516,109 @@ converting the argument from a #gsize to a #guint. deprecated="1" deprecated-version="2.40"> Copies a block of memory @len bytes long, from @src to @dest. + filename="glib/gutils.c" + line="101">Copies a block of memory @len bytes long, from @src to @dest. The source and destination areas may overlap. Just use memmove(). - + the destination address to copy the bytes to. + filename="glib/gutils.c" + line="103">the destination address to copy the bytes to. the source address to copy the bytes from. + filename="glib/gutils.c" + line="104">the source address to copy the bytes from. the number of bytes to copy. + filename="glib/gutils.c" + line="105">the number of bytes to copy. - - These functions provide support for allocating and freeing memory. - -If any call to allocate memory using functions g_new(), g_new0(), g_renew(), -g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() -fails, the application is terminated. This also means that there is no -need to check if the call succeeded. On the other hand, the `g_try_...()` family -of functions returns %NULL on failure that can be used as a check -for unsuccessful memory allocation. The application is not terminated -in this case. - -As all GLib functions and data structures use `g_malloc()` internally, unless -otherwise specified, any allocation failure will result in the application -being terminated. - -It's important to match g_malloc() (and wrappers such as g_new()) with -g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with -g_slice_free(), plain malloc() with free(), and (if you're using C++) -new with delete and new[] with delete[]. Otherwise bad things can happen, -since these allocators may use different memory pools (and new/delete call -constructors and destructors). - -Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc -implementation. - - - GSlice was a space-efficient and multi-processing scalable way to allocate -equal sized pieces of memory. Since GLib 2.76, its implementation has been -removed and it calls g_malloc() and g_free_sized(), because the performance -of the system-default allocators has improved on all platforms since GSlice -was written. - -The GSlice APIs have not been deprecated, as they are widely in use and doing -so would be very disruptive for little benefit. - -New code should be written using g_new()/g_malloc() and g_free_sized() or -g_free(). There is no particular benefit in porting existing code away from -g_slice_new()/g_slice_free() unless it’s being rewritten anyway. - -Here is an example for using the slice allocator: -|[<!-- language="C" --> -gchar *mem[10000]; -gint i; - -// Allocate 10000 blocks. -for (i = 0; i < 10000; i++) - { - mem[i] = g_slice_alloc (50); - - // Fill in the memory with some junk. - for (j = 0; j < 50; j++) - mem[i][j] = i * j; - } - -// Now free all of the blocks. -for (i = 0; i < 10000; i++) - g_slice_free1 (50, mem[i]); -]| - -And here is an example for using the using the slice allocator -with data structures: -|[<!-- language="C" --> -GRealArray *array; - -// Allocate one block, using the g_slice_new() macro. -array = g_slice_new (GRealArray); - -// We can now use array just like a normal pointer to a structure. -array->data = NULL; -array->len = 0; -array->alloc = 0; -array->zero_terminated = (zero_terminated ? 1 : 0); -array->clear = (clear ? 1 : 0); -array->elt_size = elt_size; - -// We can free the block, so it can be reused. -g_slice_free (GRealArray, array); -]| - A convenience function/macro to log a normal message. + filename="glib/gmessages.c" + line="181">A convenience function/macro to log a normal message. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. - +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). + format string, followed by parameters to insert - into the format string (as with printf()) + filename="glib/gmessages.c" + line="183">format string, followed by parameters to insert into the format string + (as with `printf()`) - - These functions provide support for outputting messages. - -The g_return family of macros (g_return_if_fail(), -g_return_val_if_fail(), g_return_if_reached(), -g_return_val_if_reached()) should only be used for programming -errors, a typical use case is checking for invalid parameters at -the beginning of a public function. They should not be used if -you just mean "if (error) return", they should only be used if -you mean "if (bug in program) return". The program behavior is -generally considered undefined after one of these checks fails. -They are not intended for normal control flow, only to give a -perhaps-helpful warning before giving up. - -Structured logging output is supported using g_log_structured(). This differs -from the traditional g_log() API in that log messages are handled as a -collection of key–value pairs representing individual pieces of information, -rather than as a single string containing all the information in an arbitrary -format. - -The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() -will use the traditional g_log() API unless you define the symbol -%G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages -logged through the traditional g_log() API are ultimatively passed to -g_log_structured(), so that all log messages end up in same destination. -If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become -ineffective for the wrapper macros g_warning() and friends (see -[Testing for Messages][testing-for-messages]). - -The support for structured logging was motivated by the following needs (some -of which were supported previously; others weren’t): - * Support for multiple logging levels. - * Structured log support with the ability to add `MESSAGE_ID`s (see - g_log_structured()). - * Moving the responsibility for filtering log messages from the program to - the log viewer — instead of libraries and programs installing log handlers - (with g_log_set_handler()) which filter messages before output, all log - messages are outputted, and the log viewer program (such as `journalctl`) - must filter them. This is based on the idea that bugs are sometimes hard - to reproduce, so it is better to log everything possible and then use - tools to analyse the logs than it is to not be able to reproduce a bug to - get additional log data. Code which uses logging in performance-critical - sections should compile out the g_log_structured() calls in - release builds, and compile them in in debugging builds. - * A single writer function which handles all log messages in a process, from - all libraries and program code; rather than multiple log handlers with - poorly defined interactions between them. This allows a program to easily - change its logging policy by changing the writer function, for example to - log to an additional location or to change what logging output fallbacks - are used. The log writer functions provided by GLib are exposed publicly - so they can be used from programs’ log writers. This allows log writer - policy and implementation to be kept separate. - * If a library wants to add standard information to all of its log messages - (such as library state) or to redact private data (such as passwords or - network credentials), it should use a wrapper function around its - g_log_structured() calls or implement that in the single log writer - function. - * If a program wants to pass context data from a g_log_structured() call to - its log writer function so that, for example, it can use the correct - server connection to submit logs to, that user data can be passed as a - zero-length #GLogField to g_log_structured_array(). - * Color output needed to be supported on the terminal, to make reading - through logs easier. - -## Using Structured Logging ## {#using-structured-logging} - -To use structured logging (rather than the old-style logging), either use -the g_log_structured() and g_log_structured_array() functions; or define -`G_LOG_USE_STRUCTURED` before including any GLib header, and use the -g_message(), g_debug(), g_error() (etc.) macros. - -You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), -but it is a good idea to avoid confusion. - -## Log Domains ## {#log-domains} - -Log domains may be used to broadly split up the origins of log messages. -Typically, there are one or a few log domains per application or library. -%G_LOG_DOMAIN should be used to define the default log domain for the current -compilation unit — it is typically defined at the top of a source file, or in -the preprocessor flags for a group of source files. - -Log domains must be unique, and it is recommended that they are the -application or library name, optionally followed by a hyphen and a sub-domain -name. For example, `bloatpad` or `bloatpad-io`. + + A wrapper for the POSIX mkdir() function. The mkdir() function +attempts to create a directory with the given name and permissions. +The mode argument is ignored on Windows. -## Debug Message Output ## {#debug-message-output} - -The default log functions (g_log_default_handler() for the old-style API and -g_log_writer_default() for the structured API) both drop debug and -informational messages by default, unless the log domains of those messages -are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to -`all`). - -It is recommended that custom log writer functions re-use the -`G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, -so that developers can re-use the same debugging techniques and tools across -projects. Since GLib 2.68, this can be implemented by dropping messages -for which g_log_writer_default_would_drop() returns %TRUE. - -## Testing for Messages ## {#testing-for-messages} - -With the old g_log() API, g_test_expect_message() and -g_test_assert_expected_messages() could be used in simple cases to check -whether some code under test had emitted a given log message. These -functions have been deprecated with the structured logging API, for several -reasons: - * They relied on an internal queue which was too inflexible for many use - cases, where messages might be emitted in several orders, some - messages might not be emitted deterministically, or messages might be - emitted by unrelated log domains. - * They do not support structured log fields. - * Examining the log output of code is a bad approach to testing it, and - while it might be necessary for legacy code which uses g_log(), it should - be avoided for new code using g_log_structured(). - -They will continue to work as before if g_log() is in use (and -%G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the -structured logging API. - -Examining the log output of code is discouraged: libraries should not emit to -`stderr` during defined behaviour, and hence this should not be tested. If -the log emissions of a library during undefined behaviour need to be tested, -they should be limited to asserting that the library aborts and prints a -suitable error message before aborting. This should be done with -g_test_trap_assert_stderr(). - -If it is really necessary to test the structured log messages emitted by a -particular piece of code – and the code cannot be restructured to be more -suitable to more conventional unit testing – you should write a custom log -writer function (see g_log_set_writer_func()) which appends all log messages -to a queue. When you want to check the log messages, examine and clear the -queue, ignoring irrelevant log messages (for example, from log domains other -than the one under test). - - - These are portable utility functions. - +See your C library manual for more details about mkdir(). + + + 0 if the directory was successfully created, -1 if an error + occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + permissions to use for the newly created directory + + + + Create a directory if it doesn't already exist. Create intermediate + filename="glib/gfileutils.c" + line="168">Create a directory if it doesn't already exist. Create intermediate parent directories as needed, too. - + 0 if the directory already exists, or was successfully + filename="glib/gfileutils.c" + line="176">0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set. a pathname in the GLib file name encoding + filename="glib/gfileutils.c" + line="170">a pathname in the GLib file name encoding permissions to use for newly created directories + filename="glib/gfileutils.c" + line="171">permissions to use for newly created directories @@ -70482,8 +75628,8 @@ created. Returns -1 if an error occurred, with errno set. version="2.30" introspectable="0"> Creates a temporary directory. See the mkdtemp() documentation + filename="glib/gfileutils.c" + line="1632">Creates a temporary directory. See the mkdtemp() documentation on most UNIX-like systems. The parameter is a string that should follow the rules for @@ -70498,11 +75644,11 @@ on Windows it should be in UTF-8. If you are going to be creating a temporary directory inside the directory returned by g_get_tmp_dir(), you might want to use g_dir_make_tmp() instead. - + A pointer to @tmpl, which has been + filename="glib/gfileutils.c" + line="1652">A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned and %errno will be set. @@ -70510,8 +75656,8 @@ g_dir_make_tmp() instead. template directory name + filename="glib/gfileutils.c" + line="1634">template directory name @@ -70521,8 +75667,8 @@ g_dir_make_tmp() instead. version="2.30" introspectable="0"> Creates a temporary directory. See the mkdtemp() documentation + filename="glib/gfileutils.c" + line="1595">Creates a temporary directory. See the mkdtemp() documentation on most UNIX-like systems. The parameter is a string that should follow the rules for @@ -70537,11 +75683,11 @@ should be in UTF-8. If you are going to be creating a temporary directory inside the directory returned by g_get_tmp_dir(), you might want to use g_dir_make_tmp() instead. - + A pointer to @tmpl, which has been + filename="glib/gfileutils.c" + line="1616">A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned, and %errno will be set. @@ -70549,22 +75695,22 @@ g_dir_make_tmp() instead. template directory name + filename="glib/gfileutils.c" + line="1597">template directory name permissions to create the temporary directory with + filename="glib/gfileutils.c" + line="1598">permissions to create the temporary directory with Opens a temporary file. See the mkstemp() documentation + filename="glib/gfileutils.c" + line="1700">Opens a temporary file. See the mkstemp() documentation on most UNIX-like systems. The parameter is a string that should follow the rules for @@ -70574,11 +75720,11 @@ sequence does not have to occur at the very end of the template. The X string will be modified to form the name of a file that didn't exist. The string should be in the GLib file name encoding. Most importantly, on Windows it should be in UTF-8. - + A file handle (as from open()) to the file + filename="glib/gfileutils.c" + line="1715">A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is @@ -70588,8 +75734,8 @@ Most importantly, on Windows it should be in UTF-8. template filename + filename="glib/gfileutils.c" + line="1702">template filename @@ -70599,8 +75745,8 @@ Most importantly, on Windows it should be in UTF-8. version="2.22" introspectable="0"> Opens a temporary file. See the mkstemp() documentation + filename="glib/gfileutils.c" + line="1664">Opens a temporary file. See the mkstemp() documentation on most UNIX-like systems. The parameter is a string that should follow the rules for @@ -70611,11 +75757,11 @@ template and you can pass a @mode and additional @flags. The X string will be modified to form the name of a file that didn't exist. The string should be in the GLib file name encoding. Most importantly, on Windows it should be in UTF-8. - + A file handle (as from open()) to the file + filename="glib/gfileutils.c" + line="1683">A file handle (as from open()) to the file opened for reading and writing. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set. @@ -70624,29 +75770,48 @@ on Windows it should be in UTF-8. template filename + filename="glib/gfileutils.c" + line="1666">template filename flags to pass to an open() call in addition to O_EXCL + filename="glib/gfileutils.c" + line="1667">flags to pass to an open() call in addition to O_EXCL and O_CREAT, which are passed automatically permissions to create the temporary file with + filename="glib/gfileutils.c" + line="1669">permissions to create the temporary file with + + Allocates and initializes a new #GMutex. + GMutex can now be statically allocated, or embedded +in structures and initialised with g_mutex_init(). + + + a newly allocated #GMutex. Use g_mutex_free() to free + + + Allocates @n_structs elements of type @struct_type. + filename="glib/gmem.h" + line="302">Allocates @n_structs elements of type @struct_type. The returned pointer is cast to a pointer to the given type. If @n_structs is 0 it returns %NULL. Care is taken to avoid overflow when calculating the size of the allocated block. @@ -70654,24 +75819,24 @@ Care is taken to avoid overflow when calculating the size of the allocated block Since the returned pointer is already casted to the right type, it is normally unnecessary to cast it explicitly, and doing so might hide memory allocation errors. - + the type of the elements to allocate + filename="glib/gmem.h" + line="304">the type of the elements to allocate the number of elements to allocate + filename="glib/gmem.h" + line="305">the number of elements to allocate Allocates @n_structs elements of type @struct_type, initialized to 0's. + filename="glib/gmem.h" + line="319">Allocates @n_structs elements of type @struct_type, initialized to 0's. The returned pointer is cast to a pointer to the given type. If @n_structs is 0 it returns %NULL. Care is taken to avoid overflow when calculating the size of the allocated block. @@ -70679,23 +75844,23 @@ Care is taken to avoid overflow when calculating the size of the allocated block Since the returned pointer is already casted to the right type, it is normally unnecessary to cast it explicitly, and doing so might hide memory allocation errors. - + the type of the elements to allocate. + filename="glib/gmem.h" + line="321">the type of the elements to allocate. the number of elements to allocate. + filename="glib/gmem.h" + line="322">the number of elements to allocate. Wraps g_alloca() in a more typesafe manner. As mentioned in the documentation for g_alloca(), @n_structs must always be @@ -70703,16 +75868,16 @@ entirely under the control of the program, or you may introduce a denial of service vulnerability. In addition, the multiplication of @struct_type by @n_structs is not checked, so an overflow may lead to a remote code execution vulnerability. - + Type of memory chunks to be allocated Number of chunks to be allocated @@ -70722,18 +75887,18 @@ vulnerability. version="2.72" introspectable="0"> Wraps g_alloca0() in a more typesafe manner. - + the type of the elements to allocate. the number of elements to allocate. @@ -70742,18 +75907,18 @@ vulnerability. c:identifier="g_node_append" introspectable="0"> Inserts a #GNode as the last child of the given parent. - + the #GNode to place the new #GNode under the #GNode to insert @@ -70762,18 +75927,18 @@ vulnerability. c:identifier="g_node_append_data" introspectable="0"> Inserts a new #GNode as the last child of the given parent. - + the #GNode to place the new #GNode under the data for the new #GNode @@ -70782,13 +75947,13 @@ vulnerability. c:identifier="g_node_first_child" introspectable="0"> Gets the first child of a #GNode. - + a #GNode @@ -70797,24 +75962,24 @@ vulnerability. c:identifier="g_node_insert_data" introspectable="0"> Inserts a new #GNode at the given position. - + the #GNode to place the new #GNode under the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent the data for the new #GNode @@ -70823,23 +75988,23 @@ vulnerability. c:identifier="g_node_insert_data_after" introspectable="0"> Inserts a new #GNode after the given sibling. - + the #GNode to place the new #GNode under the sibling #GNode to place the new #GNode after the data for the new #GNode @@ -70848,23 +76013,23 @@ vulnerability. c:identifier="g_node_insert_data_before" introspectable="0"> Inserts a new #GNode before the given sibling. - + the #GNode to place the new #GNode under the sibling #GNode to place the new #GNode before the data for the new #GNode @@ -70873,33 +76038,41 @@ vulnerability. c:identifier="g_node_next_sibling" introspectable="0"> Gets the next sibling of a #GNode. - + a #GNode + + + + + + Inserts a new #GNode as the first child of the given parent. - + the #GNode to place the new #GNode under the data for the new #GNode @@ -70908,56 +76081,69 @@ vulnerability. c:identifier="g_node_prev_sibling" introspectable="0"> Gets the previous sibling of a #GNode. - + a #GNode + + + + + + + + + + + Converts a 32-bit integer value from network to host byte order. - + filename="glib/docs.c" + line="148">Converts a 32-bit integer value from network to host byte order. + a 32-bit integer value in network byte order + filename="glib/docs.c" + line="150">a 32-bit integer value in network byte order Converts a 16-bit integer value from network to host byte order. - + filename="glib/docs.c" + line="157">Converts a 16-bit integer value from network to host byte order. + a 16-bit integer value in network byte order + filename="glib/docs.c" + line="159">a 16-bit integer value in network byte order Set the pointer at the specified location to %NULL. - + filename="glib/gutils.c" + line="2852">Set the pointer at the specified location to %NULL. + the memory address of the pointer. + filename="glib/gutils.c" + line="2854">the memory address of the pointer. @@ -70968,24 +76154,10 @@ vulnerability. - - GLib offers mathematical constants such as %G_PI for the value of pi; -many platforms have these in the C library, but some don't, the GLib -versions always exist. - -The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the -sign, mantissa and exponent of IEEE floats and doubles. These unions are -defined as appropriate for a given platform. IEEE floats and doubles are -supported (used for storage) by at least Intel, PPC and Sparc. See -[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) -for more information about IEEE number formats. - Prompts the user with + filename="glib/gbacktrace.c" + line="92">Prompts the user with `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. This function is intended to be used for debugging use only. The following example shows how it can be used together with @@ -71031,15 +76203,15 @@ This function may cause different actions on non-UNIX platforms. On Windows consider using the `G_DEBUGGER` environment variable (see [Running GLib Applications](glib-running.html)) and calling g_on_error_stack_trace() instead. - + the program name, needed by gdb for the "[S]tack trace" + filename="glib/gbacktrace.c" + line="94">the program name, needed by gdb for the "[S]tack trace" option. If @prg_name is %NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called) @@ -71050,8 +76222,8 @@ calling g_on_error_stack_trace() instead. Invokes gdb, which attaches to the current process and shows a + filename="glib/gbacktrace.c" + line="229">Invokes gdb, which attaches to the current process and shows a stack trace. Called by g_on_error_query() when the "[S]tack trace" option is selected. You can get the current process's program name with g_get_prgname(), assuming that you have called gtk_init() or @@ -71064,16 +76236,19 @@ g_on_error_query(). If called directly, it will raise an exception, which will crash the program. If the `G_DEBUGGER` environment variable is set, a debugger will be invoked to attach and handle that exception (see [Running GLib Applications](glib-running.html)). - + - + the program name, needed by gdb for the "[S]tack trace" - option + filename="glib/gbacktrace.c" + line="231">the program name, needed by gdb for the + "[S]tack trace" option, or `NULL` to use a default string @@ -71083,8 +76258,8 @@ handle that exception (see [Running GLib Applications](glib-running.html)). The first call to this routine by a process with a given #GOnce + filename="glib/gthread.c" + line="567">The first call to this routine by a process with a given #GOnce struct calls @func with the given argument. Thereafter, subsequent calls to g_once() with the same #GOnce struct do not call @func again, but return the stored result of the first call. On return @@ -71108,24 +76283,24 @@ Calling g_once() recursively on the same #GOnce struct in return my_once.retval; } ]| - + a #GOnce structure + filename="glib/gthread.c" + line="569">a #GOnce structure the #GThreadFunc function associated to @once. This function + filename="glib/gthread.c" + line="570">the #GThreadFunc function associated to @once. This function is called only once, regardless of the number of times it and its associated #GOnce struct are passed to g_once(). data to be passed to @func + filename="glib/gthread.c" + line="573">data to be passed to @func @@ -71134,8 +76309,8 @@ Calling g_once() recursively on the same #GOnce struct in moved-to="Once.init_enter" version="2.14"> Function to be called when starting a critical initialization + filename="glib/gthread.c" + line="641">Function to be called when starting a critical initialization section. The argument @location must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with @@ -71160,31 +76335,86 @@ like this: While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + %TRUE if the initialization section should be entered, + filename="glib/gthread.c" + line="672">%TRUE if the initialization section should be entered, %FALSE and blocks otherwise - + location of a static initializable variable + filename="glib/gthread.c" + line="643">location of a static initializable variable containing 0 + + + + + + + + + + + + + This functions behaves in the same way as g_once_init_enter(), but can +can be used to initialize pointers (or #guintptr) instead of #gsize. + +|[<!-- language="C" --> + static MyStruct *interesting_struct = NULL; + + if (g_once_init_enter_pointer (&interesting_struct)) + { + MyStruct *setup_value = allocate_my_struct (); // initialization code here + + g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value)); + } + + // use interesting_struct here +]| + + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing `NULL` + + + + Counterpart to g_once_init_enter(). Expects a location of a static + filename="glib/gthread.c" + line="747">Counterpart to g_once_init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter() on this @@ -71192,26 +76422,118 @@ initialization variable. While @location has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`. - + - + location of a static initializable variable + filename="glib/gthread.c" + line="749">location of a static initializable variable containing 0 new non-0 value for *@value_location + filename="glib/gthread.c" + line="751">new non-0 value for `*value_location` + + Counterpart to g_once_init_enter_pointer(). Expects a location of a static +`NULL`-initialized initialization variable, and an initialization value +other than `NULL`. Sets the variable to the initialization value, and +releases concurrent threads blocking in g_once_init_enter_pointer() on this +initialization variable. + +This functions behaves in the same way as g_once_init_leave(), but +can be used to initialize pointers (or #guintptr) instead of #gsize. + + + + + + + location of a static initializable variable + containing `NULL` + + + + new non-`NULL` value for `*location` + + + + + + A wrapper for the POSIX open() function. The open() function is +used to convert a pathname into a file descriptor. + +On POSIX systems file descriptors are implemented by the operating +system. On Windows, it's the C library that implements open() and +file descriptors. The actual Win32 API for opening files is quite +different, see MSDN documentation for CreateFile(). The Win32 API +uses file handles, which are more randomish integers, not small +integers like file descriptors. + +Because file descriptors are specific to the C library on Windows, +the file descriptor returned by this function makes sense only to +functions in the same C library. Thus if the GLib-using code uses a +different C library than GLib does, the file descriptor returned by +this function cannot be passed to C library functions like write() +or read(). + +See your C library manual for more details about open(). + + + a new file descriptor, or -1 if an error occurred. + The return value can be used exactly like the return value + from open(). + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in open() + + + + as in open() + + + + @@ -71219,8 +76541,8 @@ the pointer passed to it should not be `volatile`. Parses a string containing debugging options + filename="glib/glib-init.c" + line="259">Parses a string containing debugging options into a %guint containing bit flags. This is used within GDK and GTK to parse the debug options passed on the command line or through environment variables. @@ -71232,11 +76554,11 @@ corresponding to "foo" and "bar". If @string is equal to "help", all the available keys in @keys are printed out to standard error. - + the combined set of bit flags. + filename="glib/glib-init.c" + line="280">the combined set of bit flags. @@ -71245,15 +76567,15 @@ are printed out to standard error. nullable="1" allow-none="1"> a list of debug options separated by colons, spaces, or + filename="glib/glib-init.c" + line="261">a list of debug options separated by colons, spaces, or commas, or %NULL. pointer to an array of #GDebugKey which associate + filename="glib/glib-init.c" + line="263">pointer to an array of #GDebugKey which associate strings with bit flags. @@ -71261,8 +76583,8 @@ commas, or %NULL. the number of #GDebugKeys in the array. + filename="glib/glib-init.c" + line="265">the number of #GDebugKeys in the array. @@ -71272,8 +76594,8 @@ commas, or %NULL. moved-to="PathBuf.equal" version="2.76"> Compares two path buffers for equality and returns `TRUE` + filename="glib/gpathbuf.c" + line="555">Compares two path buffers for equality and returns `TRUE` if they are equal. The path inside the paths buffers are not going to be normalized, @@ -71282,84 +76604,84 @@ equal. This function can be passed to g_hash_table_new() as the `key_equal_func` parameter. - + `TRUE` if the two path buffers are equal, + filename="glib/gpathbuf.c" + line="570">`TRUE` if the two path buffers are equal, and `FALSE` otherwise a path buffer to compare + filename="glib/gpathbuf.c" + line="557">a path buffer to compare a path buffer to compare + filename="glib/gpathbuf.c" + line="558">a path buffer to compare Gets the last component of the filename. + filename="glib/gfileutils.c" + line="2580">Gets the last component of the filename. If @file_name ends with a directory separator it gets the component before the last slash. If @file_name consists only of directory separators (and on Windows, possibly a drive letter), a single separator is returned. If @file_name is empty, it gets ".". - + a newly allocated string + filename="glib/gfileutils.c" + line="2591">a newly allocated string containing the last component of the filename the name of the file + filename="glib/gfileutils.c" + line="2582">the name of the file Gets the directory components of a file name. For example, the directory + filename="glib/gfileutils.c" + line="2657">Gets the directory components of a file name. For example, the directory component of `/usr/bin/test` is `/usr/bin`. The directory component of `/` is `/`. If the file name has no directory components "." is returned. The returned string should be freed when no longer needed. - + the directory components of the file + filename="glib/gfileutils.c" + line="2668">the directory components of the file the name of the file + filename="glib/gfileutils.c" + line="2659">the name of the file Returns %TRUE if the given @file_name is an absolute file name. + filename="glib/gfileutils.c" + line="2415">Returns %TRUE if the given @file_name is an absolute file name. Note that this is a somewhat vague concept on Windows. On POSIX systems, an absolute file name is well-defined. It always @@ -71383,41 +76705,41 @@ function, but they obviously are not relative to the normal current directory as returned by getcwd() or g_get_current_dir() either. Such paths should be avoided, or need to be handled using Windows-specific code. - + %TRUE if @file_name is absolute + filename="glib/gfileutils.c" + line="2444">%TRUE if @file_name is absolute a file name + filename="glib/gfileutils.c" + line="2417">a file name Returns a pointer into @file_name after the root component, + filename="glib/gfileutils.c" + line="2464">Returns a pointer into @file_name after the root component, i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name is not an absolute path it returns %NULL. - + a pointer into @file_name after the + filename="glib/gfileutils.c" + line="2472">a pointer into @file_name after the root component a file name + filename="glib/gfileutils.c" + line="2466">a file name @@ -71428,50 +76750,52 @@ is not an absolute path it returns %NULL. deprecated="1" deprecated-version="2.70"> Matches a string against a compiled pattern. Passing the correct + filename="glib/gpattern.c" + line="239">Matches a string against a compiled pattern. + +Passing the correct length of the string given is mandatory. The reversed string can be -omitted by passing %NULL, this is more efficient if the reversed +omitted by passing `NULL`, this is more efficient if the reversed version of the string to be matched is not at hand, as -g_pattern_match() will only construct it if the compiled pattern +`g_pattern_match()` will only construct it if the compiled pattern requires reverse matches. Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that -some patterns will require a reversed string. In this case, it's +some patterns will require a reversed string. In this case, it’s more efficient to provide the reversed string to avoid multiple -constructions thereof in the various calls to g_pattern_match(). +constructions thereof in the various calls to `g_pattern_match()`. Note also that the reverse of a UTF-8 encoded string can in general -not be obtained by g_strreverse(). This works only if the string +not be obtained by [func@GLib.strreverse]. This works only if the string does not contain any multibyte characters. GLib offers the -g_utf8_strreverse() function to reverse UTF-8 encoded strings. - Use g_pattern_spec_match() instead - +[func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings. + Use [method@GLib.PatternSpec.match] instead + %TRUE if @string matches @pspec + filename="glib/gpattern.c" + line="267">%TRUE if @string matches @pspec a #GPatternSpec + filename="glib/gpattern.c" + line="241">a #GPatternSpec the length of @string (in bytes, i.e. strlen(), - not g_utf8_strlen()) + filename="glib/gpattern.c" + line="242">the length of @string (in bytes, i.e. `strlen()`, + not [func@GLib.utf8_strlen]) the UTF-8 encoded string to match + filename="glib/gpattern.c" + line="244">the UTF-8 encoded string to match nullable="1" allow-none="1"> the reverse of @string or %NULL + filename="glib/gpattern.c" + line="245">the reverse of @string @@ -71488,29 +76812,31 @@ g_utf8_strreverse() function to reverse UTF-8 encoded strings. Matches a string against a pattern given as a string. If this -function is to be called in a loop, it's more efficient to compile -the pattern once with g_pattern_spec_new() and call -g_pattern_match_string() repeatedly. - + filename="glib/gpattern.c" + line="502">Matches a string against a pattern given as a string. + +If this +function is to be called in a loop, it’s more efficient to compile +the pattern once with [ctor@GLib.PatternSpec.new] and call +[method@GLib.PatternSpec.match_string] repeatedly. + %TRUE if @string matches @pspec + filename="glib/gpattern.c" + line="514">%TRUE if @string matches @pspec the UTF-8 encoded pattern + filename="glib/gpattern.c" + line="504">the UTF-8 encoded pattern the UTF-8 encoded string to match + filename="glib/gpattern.c" + line="505">the UTF-8 encoded string to match @@ -71521,57 +76847,41 @@ g_pattern_match_string() repeatedly. deprecated="1" deprecated-version="2.70"> Matches a string against a compiled pattern. If the string is to be + filename="glib/gpattern.c" + line="481">Matches a string against a compiled pattern. + +If the string is to be matched against more than one pattern, consider using -g_pattern_match() instead while supplying the reversed string. - Use g_pattern_spec_match_string() instead - +[method@GLib.PatternSpec.match] instead while supplying the reversed string. + Use [method@GLib.PatternSpec.match_string] instead + %TRUE if @string matches @pspec + filename="glib/gpattern.c" + line="492">%TRUE if @string matches @pspec a #GPatternSpec + filename="glib/gpattern.c" + line="483">a #GPatternSpec the UTF-8 encoded string to match + filename="glib/gpattern.c" + line="484">the UTF-8 encoded string to match - - The g_pattern_match* functions match a string -against a pattern containing '*' and '?' wildcards with similar -semantics as the standard glob() function: '*' matches an arbitrary, -possibly empty, string, '?' matches an arbitrary character. - -Note that in contrast to glob(), the '/' character can be matched by -the wildcards, there are no '[...]' character ranges and '*' and '?' -can not be escaped to include them literally in a pattern. - -When multiple strings must be matched against the same pattern, it -is better to compile the pattern to a #GPatternSpec using -g_pattern_spec_new() and use g_pattern_match_string() instead of -g_pattern_match_simple(). This avoids the overhead of repeated -pattern compilation. - This is equivalent to g_bit_lock, but working on pointers (or other + filename="glib/gbitlock.c" + line="495">This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of @@ -71579,31 +76889,134 @@ the pointer. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + a pointer to a #gpointer-sized value + filename="glib/gbitlock.c" + line="497">a pointer to a #gpointer-sized value a bit value between 0 and 31 + filename="glib/gbitlock.c" + line="498">a bit value between 0 and 31 + + This is equivalent to g_bit_lock, but working on pointers (or other +pointer-sized values). + +For portability reasons, you may only lock on the bottom 32 bits of +the pointer. + + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + returns the set pointer atomically. + This is the value after setting the lock, it thus always has the + lock bit set, while previously @address had the lockbit unset. + You may also use g_pointer_bit_lock_mask_ptr() to clear the lock bit. + + + + + + This mangles @ptr as g_pointer_bit_lock() and g_pointer_bit_unlock() +do. + + + the mangled pointer. + + + + + the pointer to mask + + + + the bit to set/clear. If set to `G_MAXUINT`, the + lockbit is taken from @preserve_ptr or @ptr (depending on @preserve_mask). + + + + whether to set (lock) the bit or unset (unlock). This + has no effect, if @lock_bit is set to `G_MAXUINT`. + + + + if non-zero, a bit-mask for @preserve_ptr. The + @preserve_mask bits from @preserve_ptr are set in the result. + Note that the @lock_bit bit will be always set according to @set, + regardless of @preserve_mask and @preserve_ptr (unless @lock_bit is + `G_MAXUINT`). + + + + if @preserve_mask is non-zero, the bits + from this pointer are set in the result. + + + + This is equivalent to g_bit_trylock(), but working on pointers (or + filename="glib/gbitlock.c" + line="518">This is equivalent to g_bit_trylock(), but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of @@ -71611,24 +77024,24 @@ the pointer. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + %TRUE if the lock was acquired + filename="glib/gbitlock.c" + line="532">%TRUE if the lock was acquired a pointer to a #gpointer-sized value + filename="glib/gbitlock.c" + line="520">a pointer to a #gpointer-sized value a bit value between 0 and 31 + filename="glib/gbitlock.c" + line="521">a bit value between 0 and 31 @@ -71637,8 +77050,8 @@ artifact and the argument passed to it should not be `volatile`. c:identifier="g_pointer_bit_unlock" version="2.30"> This is equivalent to g_bit_unlock, but working on pointers (or other + filename="glib/gbitlock.c" + line="569">This is equivalent to g_bit_unlock, but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of @@ -71646,29 +77059,78 @@ the pointer. While @address has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + a pointer to a #gpointer-sized value + filename="glib/gbitlock.c" + line="571">a pointer to a #gpointer-sized value a bit value between 0 and 31 + filename="glib/gbitlock.c" + line="572">a bit value between 0 and 31 + + This is equivalent to g_pointer_bit_unlock() and atomically setting +the pointer value. + +Note that the lock bit will be cleared from the pointer. If the unlocked +pointer that was set is not identical to @ptr, an assertion fails. In other +words, @ptr must have @lock_bit unset. This also means, you usually can +only use this on the lowest bits. + + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + the new pointer value to set + + + + if non-zero, those bits of the current pointer in @address + are preserved. + Note that the @lock_bit bit will be always set according to @set, + regardless of @preserve_mask and the currently set value in @address. + + + + Polls @fds, as with the poll() system call, but portably. (On + filename="glib/gpoll.c" + line="91">Polls @fds, as with the poll() system call, but portably. (On systems that don't have poll(), it is emulated using select().) This is used internally by #GMainContext, but it can be called directly if you need to block until a file descriptor is ready, but @@ -71685,11 +77147,11 @@ file descriptor, but the situation is much more complicated on Windows. If you need to use g_poll() in code that has to run on Windows, the easiest solution is to construct all of your #GPollFDs with g_io_channel_win32_make_pollfd(). - + the number of entries in @fds whose @revents fields + filename="glib/gpoll.c" + line="115">the number of entries in @fds whose @revents fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted. @@ -71697,20 +77159,20 @@ if the call was interrupted. file descriptors to poll + filename="glib/gpoll.c" + line="93">file descriptors to poll the number of file descriptors in @fds + filename="glib/gpoll.c" + line="94">the number of file descriptors in @fds amount of time to wait, in milliseconds, or -1 to wait forever + filename="glib/gpoll.c" + line="95">amount of time to wait, in milliseconds, or -1 to wait forever @@ -71720,14 +77182,14 @@ if the call was interrupted. version="2.16" introspectable="0"> Formats a string according to @format and prefix it to an existing + filename="glib/gerror.c" + line="602">Formats a string according to @format and prefix it to an existing error message. If @err is %NULL (ie: no error variable) then do nothing. -If *@err is %NULL (ie: an error variable is present but there is no +If `*err` is %NULL (ie: an error variable is present but there is no error condition) then also do nothing. - + @@ -71740,20 +77202,20 @@ error condition) then also do nothing. allow-none="1" optional="1"> a return location for a #GError + filename="glib/gerror.c" + line="604">a return location for a #GError printf()-style format string + filename="glib/gerror.c" + line="605">printf()-style format string arguments to @format + filename="glib/gerror.c" + line="606">arguments to @format @@ -71762,89 +77224,94 @@ error condition) then also do nothing. c:identifier="g_prefix_error_literal" version="2.70"> Prefixes @prefix to an existing error message. If @err or *@err is + filename="glib/gerror.c" + line="632">Prefixes @prefix to an existing error message. If @err or `*err` is %NULL (i.e.: no error variable) then do nothing. - + + allow-none="1" + optional="1"> a return location for a #GError, or %NULL + filename="glib/gerror.c" + line="634">a return location for a #GError, or %NULL string to prefix @err with + filename="glib/gerror.c" + line="635">string to prefix @err with Outputs a formatted message via the print handler. -The default print handler outputs the encoded message to stdout, without + filename="glib/gmessages.c" + line="3530">Outputs a formatted message via the print handler. + +The default print handler outputs the encoded message to `stdout`, without appending a trailing new-line character. Typically, @format should end with its own new-line character. -g_print() should not be used from within libraries for debugging +This function should not be used from within libraries for debugging messages, since it may be redirected by applications to special purpose message windows or even files. Instead, libraries should -use g_log(), g_log_structured(), or the convenience macros g_message(), -g_warning() and g_error(). - +use [func@GLib.log], [func@GLib.log_structured], or the convenience macros +[func@GLib.message], [func@GLib.warning] and [func@GLib.error]. + the message format. See the printf() documentation + filename="glib/gmessages.c" + line="3532">the message format. See the `printf()` documentation the parameters to insert into the format string + filename="glib/gmessages.c" + line="3533">the parameters to insert into the format string Outputs a formatted message via the error message handler. -The default handler outputs the encoded message to stderr, without appending + filename="glib/gmessages.c" + line="3597">Outputs a formatted message via the error message handler. + +The default handler outputs the encoded message to `stderr`, without appending a trailing new-line character. Typically, @format should end with its own new-line character. -g_printerr() should not be used from within libraries. -Instead g_log() or g_log_structured() should be used, or the convenience -macros g_message(), g_warning() and g_error(). - +This function should not be used from within libraries. +Instead [func@GLib.log] or [func@GLib.log_structured] should be used, or the convenience +macros [func@GLib.message], [func@GLib.warning] and [func@GLib.error]. + the message format. See the printf() documentation + filename="glib/gmessages.c" + line="3599">the message format. See the `printf()` documentation the parameters to insert into the format string + filename="glib/gmessages.c" + line="3600">the parameters to insert into the format string @@ -71854,34 +77321,34 @@ macros g_message(), g_warning() and g_error(). version="2.2" introspectable="0"> An implementation of the standard printf() function which supports + filename="glib/gprintf.c" + line="31">An implementation of the standard `printf()` function which supports positional parameters, as specified in the Single Unix Specification. -As with the standard printf(), this does not automatically append a trailing +As with the standard `printf()`, this does not automatically append a trailing new-line character to the message, so typically @format should end with its own new-line character. `glib/gprintf.h` must be explicitly included in order to use this function. - + the number of bytes printed. + filename="glib/gprintf.c" + line="46">the number of bytes printed a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="33">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output. + filename="glib/gprintf.c" + line="35">the arguments to insert in the output @@ -71890,35 +77357,70 @@ own new-line character. c:identifier="g_printf_string_upper_bound" introspectable="0"> Calculates the maximum space needed to store the output -of the sprintf() function. - + filename="glib/gmessages.c" + line="3632">Calculates the maximum space needed to store the output +of the `sprintf()` function. + +If @format or @args are invalid, `0` is returned. This could happen if, for +example, @format contains an `%lc` or `%ls` placeholder and @args contains a +wide character which cannot be represented in multibyte encoding. `0` +can also be returned legitimately if, for example, @format is `%s` and @args +is an empty string. The caller is responsible for differentiating these two +return cases if necessary. It is recommended to not use `%lc` or `%ls` +placeholders in any case, as their behaviour is locale-dependent. + the maximum space needed to store the formatted string + filename="glib/gmessages.c" + line="3648">the maximum space needed to store the formatted string, or `0` on error the format string. See the printf() documentation + filename="glib/gmessages.c" + line="3634">the format string. See the `printf()` documentation the parameters to be inserted into the format string + filename="glib/gmessages.c" + line="3635">the parameters to be inserted into the format string + + Creates a new #GPrivate. + dynamic allocation of #GPrivate is a bad idea. Use + static storage and G_PRIVATE_INIT() instead. + + + a newly allocated #GPrivate (which can never be destroyed) + + + + + a #GDestroyNotify + + + + If @dest is %NULL, free @src; otherwise, moves @src into *@dest. + filename="glib/gerror.c" + line="532">If @dest is %NULL, free @src; otherwise, moves @src into `*dest`. The error variable @dest points to must be %NULL. @src must be non-%NULL. @@ -71926,7 +77428,7 @@ The error variable @dest points to must be %NULL. Note that @src is no longer valid after this call. If you want to keep using the same GError*, you need to set it to %NULL after calling this function on it. - + @@ -71939,14 +77441,14 @@ after calling this function on it. optional="1" allow-none="1"> error return location + filename="glib/gerror.c" + line="534">error return location error to move into the return location + filename="glib/gerror.c" + line="535">error to move into the return location @@ -71956,37 +77458,37 @@ after calling this function on it. version="2.16" introspectable="0"> If @dest is %NULL, free @src; otherwise, moves @src into *@dest. -*@dest must be %NULL. After the move, add a prefix as with + filename="glib/gerror.c" + line="656">If @dest is %NULL, free @src; otherwise, moves @src into `*dest`. +`*dest` must be %NULL. After the move, add a prefix as with g_prefix_error(). - + error return location + filename="glib/gerror.c" + line="658">error return location error to move into the return location + filename="glib/gerror.c" + line="659">error to move into the return location printf()-style format string + filename="glib/gerror.c" + line="660">printf()-style format string arguments to @format + filename="glib/gerror.c" + line="661">arguments to @format @@ -71997,26 +77499,26 @@ g_prefix_error(). version="2.54" introspectable="0"> Checks whether @needle exists in @haystack. If the element is found, %TRUE is + filename="glib/garray.c" + line="2601">Checks whether @needle exists in @haystack. If the element is found, %TRUE is returned and the element’s index is returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of the first instance is returned. This does pointer comparisons only. If you want to use more complex equality checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). - + %TRUE if @needle is one of the elements of @haystack + filename="glib/garray.c" + line="2616">%TRUE if @needle is one of the elements of @haystack pointer array to be searched + filename="glib/garray.c" + line="2603">pointer array to be searched @@ -72026,8 +77528,8 @@ checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). pointer to look for + filename="glib/garray.c" + line="2604">pointer to look for return location for the index of + filename="glib/garray.c" + line="2605">return location for the index of the element, if found @@ -72050,8 +77552,8 @@ checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). Checks whether @needle exists in @haystack, using the given @equal_func. + filename="glib/garray.c" + line="2627">Checks whether @needle exists in @haystack, using the given @equal_func. If the element is found, %TRUE is returned and the element’s index is returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists multiple times in @haystack, the index of @@ -72060,18 +77562,18 @@ the first instance is returned. @equal_func is called with the element from the array as its first parameter, and @needle as its second parameter. If @equal_func is %NULL, pointer equality is used. - + %TRUE if @needle is one of the elements of @haystack + filename="glib/garray.c" + line="2647">%TRUE if @needle is one of the elements of @haystack pointer array to be searched + filename="glib/garray.c" + line="2629">pointer array to be searched @@ -72081,8 +77583,8 @@ equality is used. nullable="1" allow-none="1"> pointer to look for + filename="glib/garray.c" + line="2630">pointer to look for nullable="1" allow-none="1"> the function to call for each element, which should + filename="glib/garray.c" + line="2631">the function to call for each element, which should return %TRUE when the desired element is found; or %NULL to use pointer equality @@ -72103,8 +77605,8 @@ equality is used. optional="1" allow-none="1"> return location for the index of + filename="glib/garray.c" + line="2634">return location for the index of the element, if found @@ -72114,22 +77616,22 @@ equality is used. c:identifier="g_ptr_array_index" introspectable="0"> Returns the pointer at the given index of the pointer array. + filename="glib/garray.c" + line="1104">Returns the pointer at the given index of the pointer array. This does not perform bounds checking on the given @index_, so you are responsible for checking it against the array length. - + a #GPtrArray + filename="glib/garray.c" + line="1106">a #GPtrArray the index of the pointer to return + filename="glib/garray.c" + line="1107">the index of the pointer to return @@ -72139,8 +77641,8 @@ so you are responsible for checking it against the array length. version="2.76" introspectable="0"> Creates a new #GPtrArray, copying @len pointers from @data, and setting + filename="glib/garray.c" + line="1313">Creates a new #GPtrArray, copying @len pointers from @data, and setting the array’s reference count to 1. This avoids having to manually add each element one by one. @@ -72156,11 +77658,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if @len is greater than %G_MAXUINT. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1341">A new #GPtrArray @@ -72171,8 +77673,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array of pointers, + filename="glib/garray.c" + line="1315">an array of pointers, or %NULL for an empty array @@ -72180,8 +77682,8 @@ or %NULL for an empty array the number of pointers in @data + filename="glib/garray.c" + line="1317">the number of pointers in @data closure="3" destroy="4"> a copy function used to copy every element in the + filename="glib/garray.c" + line="1318">a copy function used to copy every element in the array or %NULL. @@ -72202,8 +77704,8 @@ or %NULL for an empty array nullable="1" allow-none="1"> user data passed to @copy_func, or %NULL + filename="glib/garray.c" + line="1320">user data passed to @copy_func, or %NULL allow-none="1" scope="async"> a function to free elements on @array + filename="glib/garray.c" + line="1321">a function to free elements on @array destruction or %NULL @@ -72225,8 +77727,8 @@ or %NULL for an empty array version="2.76" introspectable="0"> Creates a new #GPtrArray copying the pointers from @data after having + filename="glib/garray.c" + line="1359">Creates a new #GPtrArray copying the pointers from @data after having computed the length of it and with a reference count of 1. This avoids having to manually add each element one by one. If @copy_func is provided, then it is used to copy the data in the new @@ -72238,11 +77740,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if the @data has more than %G_MAXUINT elements. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1382">A new #GPtrArray @@ -72253,8 +77755,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array of + filename="glib/garray.c" + line="1361">an array of pointers, %NULL terminated; or %NULL for an empty array @@ -72268,8 +77770,8 @@ stores the length of its data in #guint, which may be shorter than closure="2" destroy="3"> a copy function used to copy every element in the + filename="glib/garray.c" + line="1363">a copy function used to copy every element in the array or %NULL. @@ -72278,8 +77780,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> user data passed to @copy_func, or %NULL + filename="glib/garray.c" + line="1365">user data passed to @copy_func, or %NULL a function to free elements on @array + filename="glib/garray.c" + line="1366">a function to free elements on @array destruction or %NULL @@ -72301,8 +77803,8 @@ stores the length of its data in #guint, which may be shorter than version="2.76" introspectable="0"> Creates a new #GPtrArray with @data as pointers, @len as length and a + filename="glib/garray.c" + line="1178">Creates a new #GPtrArray with @data as pointers, @len as length and a reference count of 1. This avoids having to copy such data manually. @@ -72317,11 +77819,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if @len is greater than %G_MAXUINT. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1202">A new #GPtrArray @@ -72332,8 +77834,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array of pointers, + filename="glib/garray.c" + line="1180">an array of pointers, or %NULL for an empty array @@ -72341,8 +77843,8 @@ stores the length of its data in #guint, which may be shorter than the number of pointers in @data + filename="glib/garray.c" + line="1182">the number of pointers in @data A function to free elements on @array + filename="glib/garray.c" + line="1183">A function to free elements on @array destruction or %NULL @@ -72364,8 +77866,8 @@ stores the length of its data in #guint, which may be shorter than version="2.76" introspectable="0"> Creates a new #GPtrArray with @data as pointers, computing the length of it + filename="glib/garray.c" + line="1227">Creates a new #GPtrArray with @data as pointers, computing the length of it and setting the reference count to 1. This avoids having to copy such data manually. @@ -72383,11 +77885,11 @@ with @free_segment set to %TRUE or when removing elements. Do not use it if the @data length is greater than %G_MAXUINT. #GPtrArray stores the length of its data in #guint, which may be shorter than #gsize. - + A new #GPtrArray + filename="glib/garray.c" + line="1253">A new #GPtrArray @@ -72398,8 +77900,8 @@ stores the length of its data in #guint, which may be shorter than nullable="1" allow-none="1"> an array + filename="glib/garray.c" + line="1229">an array of pointers, %NULL terminated, or %NULL for an empty array @@ -72411,8 +77913,8 @@ stores the length of its data in #guint, which may be shorter than allow-none="1" scope="async"> a function to free elements on @array + filename="glib/garray.c" + line="1231">a function to free elements on @array destruction or %NULL @@ -72420,40 +77922,47 @@ stores the length of its data in #guint, which may be shorter than + deprecated="1" + deprecated-version="2.82"> This is just like the standard C qsort() function, but -the comparison routine accepts a user data argument. + filename="glib/gqsort.c" + line="284">This is just like the standard C [`qsort()`](man:qsort(3)) function, but +the comparison routine accepts a user data argument +(like [`qsort_r()`](man:qsort_r(3))). -This is guaranteed to be a stable sort since version 2.32. - +Unlike `qsort()`, this is guaranteed to be a stable sort (since GLib 2.32). + `total_elems` is too small to represent larger arrays; use + [func@GLib.sort_array] instead + start of array to sort + filename="glib/gqsort.c" + line="286">start of array to sort elements in the array + filename="glib/gqsort.c" + line="287">elements in the array size of each element + filename="glib/gqsort.c" + line="288">size of each element - + function to compare elements + filename="glib/gqsort.c" + line="289">function to compare elements nullable="1" allow-none="1"> data to pass to @compare_func + filename="glib/gqsort.c" + line="290">data to pass to @compare_func @@ -72470,8 +77979,8 @@ This is guaranteed to be a stable sort since version 2.32. Gets the #GQuark identifying the given (static) string. If the + filename="glib/gquark.c" + line="229">Gets the #GQuark identifying the given (static) string. If the string does not currently have an associated #GQuark, a new #GQuark is created, linked to the given string. @@ -72487,11 +77996,11 @@ function in GTK theme engines). This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. - + the #GQuark identifying the string, or 0 if @string is %NULL + filename="glib/gquark.c" + line="250">the #GQuark identifying the string, or 0 if @string is %NULL @@ -72500,27 +78009,27 @@ variables in C++. nullable="1" allow-none="1"> a string + filename="glib/gquark.c" + line="231">a string Gets the #GQuark identifying the given string. If the string does + filename="glib/gquark.c" + line="209">Gets the #GQuark identifying the given string. If the string does not currently have an associated #GQuark, a new #GQuark is created, using a copy of the string. This function must not be used before library constructors have finished running. In particular, this means it cannot be used to initialize global variables in C++. - + the #GQuark identifying the string, or 0 if @string is %NULL + filename="glib/gquark.c" + line="221">the #GQuark identifying the string, or 0 if @string is %NULL @@ -72529,36 +78038,36 @@ variables in C++. nullable="1" allow-none="1"> a string + filename="glib/gquark.c" + line="211">a string Gets the string associated with the given #GQuark. - + filename="glib/gquark.c" + line="258">Gets the string associated with the given #GQuark. + the string associated with the #GQuark + filename="glib/gquark.c" + line="264">the string associated with the #GQuark a #GQuark. + filename="glib/gquark.c" + line="260">a #GQuark. Gets the #GQuark associated with the given string, or 0 if string is + filename="glib/gquark.c" + line="116">Gets the #GQuark associated with the given string, or 0 if string is %NULL or it has no associated #GQuark. If you want the GQuark to be created if it doesn't already exist, @@ -72566,11 +78075,11 @@ use g_quark_from_string() or g_quark_from_static_string(). This function must not be used before library constructors have finished running. - + the #GQuark associated with the string, or 0 if @string is + filename="glib/gquark.c" + line="129">the #GQuark associated with the string, or 0 if @string is %NULL or there is no #GQuark associated with it @@ -72580,78 +78089,25 @@ running. nullable="1" allow-none="1"> a string + filename="glib/gquark.c" + line="118">a string - - Quarks are associations between strings and integer identifiers. -Given either the string or the #GQuark identifier it is possible to -retrieve the other. - -Quarks are used for both [datasets][glib-Datasets] and -[keyed data lists][glib-Keyed-Data-Lists]. - -To create a new quark from a string, use g_quark_from_string() or -g_quark_from_static_string(). - -To find the string corresponding to a given #GQuark, use -g_quark_to_string(). - -To find the #GQuark corresponding to a given string, use -g_quark_try_string(). - -Another use for the string pool maintained for the quark functions -is string interning, using g_intern_string() or -g_intern_static_string(). An interned string is a canonical -representation for a string. One important advantage of interned -strings is that they can be compared for equality by a simple -pointer comparison, rather than using strcmp(). - - - The #GQueue structure and its associated functions provide a standard -queue data structure. Internally, GQueue uses the same data structure -as #GList to store elements with the same complexity over -insertion/deletion (O(1)) and access/search (O(n)) operations. - -The data contained in each element can be either integer values, by -using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], -or simply pointers to any type of data. - -As with all other GLib data structures, #GQueue is not thread-safe. -For a thread-safe queue, use #GAsyncQueue. - -To create a new GQueue, use g_queue_new(). - -To initialize a statically-allocated GQueue, use %G_QUEUE_INIT or -g_queue_init(). - -To add elements, use g_queue_push_head(), g_queue_push_head_link(), -g_queue_push_tail() and g_queue_push_tail_link(). - -To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). - -To free the entire queue, use g_queue_free(). - Returns a random #gboolean from @rand_. + filename="glib/grand.c" + line="383">Returns a random #gboolean from @rand_. This corresponds to an unbiased coin toss. - + a #GRand + filename="glib/grand.c" + line="385">a #GRand @@ -72659,152 +78115,104 @@ This corresponds to an unbiased coin toss. c:identifier="g_random_boolean" introspectable="0"> Returns a random #gboolean. + filename="glib/grand.c" + line="583">Returns a random #gboolean. This corresponds to an unbiased coin toss. - + Returns a random #gdouble equally distributed over the range [0..1). - + filename="glib/grand.c" + line="630">Returns a random #gdouble equally distributed over the range [0..1). + a random number + filename="glib/grand.c" + line="635">a random number Returns a random #gdouble equally distributed over the range + filename="glib/grand.c" + line="647">Returns a random #gdouble equally distributed over the range [@begin..@end). - + a random number + filename="glib/grand.c" + line="655">a random number lower closed bound of the interval + filename="glib/grand.c" + line="649">lower closed bound of the interval upper open bound of the interval + filename="glib/grand.c" + line="650">upper open bound of the interval Return a random #guint32 equally distributed over the range + filename="glib/grand.c" + line="591">Return a random #guint32 equally distributed over the range [0..2^32-1]. - + a random number + filename="glib/grand.c" + line="597">a random number Returns a random #gint32 equally distributed over the range + filename="glib/grand.c" + line="609">Returns a random #gint32 equally distributed over the range [@begin..@end-1]. - + a random number + filename="glib/grand.c" + line="617">a random number lower closed bound of the interval + filename="glib/grand.c" + line="611">lower closed bound of the interval upper open bound of the interval + filename="glib/grand.c" + line="612">upper open bound of the interval - - The following functions allow you to use a portable, fast and good -pseudo-random number generator (PRNG). - -Do not use this API for cryptographic purposes such as key -generation, nonces, salts or one-time pads. - -This PRNG is suitable for non-cryptographic use such as in games -(shuffling a card deck, generating levels), generating data for -a test suite, etc. If you need random data for cryptographic -purposes, it is recommended to use platform-specific APIs such -as `/dev/random` on UNIX, or CryptGenRandom() on Windows. - -GRand uses the Mersenne Twister PRNG, which was originally -developed by Makoto Matsumoto and Takuji Nishimura. Further -information can be found at -[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). - -If you just need a random number, you simply call the g_random_* -functions, which will create a globally used #GRand and use the -according g_rand_* functions internally. Whenever you need a -stream of reproducible random numbers, you better create a -#GRand yourself and use the g_rand_* functions directly, which -will also be slightly faster. Initializing a #GRand with a -certain seed will produce exactly the same series of random -numbers on all platforms. This can thus be used as a seed for -e.g. games. - -The g_rand*_range functions will return high quality equally -distributed random numbers, whereas for example the -`(g_random_int()%max)` approach often -doesn't yield equally distributed numbers. - -GLib changed the seeding algorithm for the pseudo-random number -generator Mersenne Twister, as used by #GRand. This was necessary, -because some seeds would yield very bad pseudo-random streams. -Also the pseudo-random integers generated by g_rand*_int_range() -will have a slightly better equal distribution with the new -version of GLib. - -The original seeding and generation algorithms, as found in -GLib 2.0.x, can be used instead of the new ones by setting the -environment variable `G_RANDOM_VERSION` to the value of '2.0'. -Use the GLib-2.0 algorithms only if you have sequences of numbers -generated with Glib-2.0 that you need to reproduce exactly. - Sets the seed for the global random number generator, which is used + filename="glib/grand.c" + line="668">Sets the seed for the global random number generator, which is used by the g_random_* functions, to @seed. - + a value to reinitialize the global random number generator + filename="glib/grand.c" + line="670">a value to reinitialize the global random number generator @@ -72813,29 +78221,29 @@ by the g_random_* functions, to @seed. c:identifier="g_rc_box_acquire" version="2.58"> Acquires a reference on the data pointed by @mem_block. - + filename="glib/grcbox.c" + line="270">Acquires a reference on the data pointed by @mem_block. + a pointer to the data, + filename="glib/grcbox.c" + line="276">a pointer to the data, with its reference count increased a pointer to reference counted data + filename="glib/grcbox.c" + line="272">a pointer to reference counted data Allocates @block_size bytes of memory, and adds reference + filename="glib/grcbox.c" + line="155">Allocates @block_size bytes of memory, and adds reference counting semantics to it. The data will be freed when its reference count drops to @@ -72843,18 +78251,18 @@ zero. The allocated data is guaranteed to be suitably aligned for any built-in type. - + a pointer to the allocated memory + filename="glib/grcbox.c" + line="168">a pointer to the allocated memory the size of the allocation, must be greater than 0 + filename="glib/grcbox.c" + line="157">the size of the allocation, must be greater than 0 @@ -72863,8 +78271,8 @@ built-in type. c:identifier="g_rc_box_alloc0" version="2.58"> Allocates @block_size bytes of memory, and adds reference + filename="glib/grcbox.c" + line="180">Allocates @block_size bytes of memory, and adds reference counting semantics to it. The contents of the returned data is set to zero. @@ -72874,47 +78282,47 @@ zero. The allocated data is guaranteed to be suitably aligned for any built-in type. - + a pointer to the allocated memory + filename="glib/grcbox.c" + line="195">a pointer to the allocated memory the size of the allocation, must be greater than 0 + filename="glib/grcbox.c" + line="182">the size of the allocation, must be greater than 0 Allocates a new block of data with reference counting + filename="glib/grcbox.c" + line="241">Allocates a new block of data with reference counting semantics, and copies @block_size bytes of @mem_block into it. - + a pointer to the allocated + filename="glib/grcbox.c" + line="250">a pointer to the allocated memory the number of bytes to copy, must be greater than 0 + filename="glib/grcbox.c" + line="243">the number of bytes to copy, must be greater than 0 the memory to copy + filename="glib/grcbox.c" + line="244">the memory to copy @@ -72923,20 +78331,20 @@ into it. c:identifier="g_rc_box_get_size" version="2.58"> Retrieves the size of the reference counted data pointed by @mem_block. - + filename="glib/grcbox.c" + line="353">Retrieves the size of the reference counted data pointed by @mem_block. + the size of the data, in bytes + filename="glib/grcbox.c" + line="359">the size of the data, in bytes a pointer to reference counted data + filename="glib/grcbox.c" + line="355">a pointer to reference counted data @@ -72946,19 +78354,19 @@ into it. version="2.58" introspectable="0"> A convenience macro to allocate reference counted data with + filename="glib/grcbox.c" + line="207">A convenience macro to allocate reference counted data with the size of the given @type. This macro calls g_rc_box_alloc() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. - + the type to allocate, typically a structure name + filename="glib/grcbox.c" + line="209">the type to allocate, typically a structure name @@ -72967,19 +78375,19 @@ avoiding a type cast in the source code. version="2.58" introspectable="0"> A convenience macro to allocate reference counted data with + filename="glib/grcbox.c" + line="224">A convenience macro to allocate reference counted data with the size of the given @type, and set its contents to zero. This macro calls g_rc_box_alloc0() with `sizeof (@type)` and casts the returned pointer to a pointer of the given @type, avoiding a type cast in the source code. - + the type to allocate, typically a structure name + filename="glib/grcbox.c" + line="226">the type to allocate, typically a structure name @@ -72987,20 +78395,20 @@ avoiding a type cast in the source code. c:identifier="g_rc_box_release" version="2.58"> Releases a reference on the data pointed by @mem_block. + filename="glib/grcbox.c" + line="298">Releases a reference on the data pointed by @mem_block. If the reference was the last one, it will free the resources allocated for @mem_block. - + a pointer to reference counted data + filename="glib/grcbox.c" + line="300">a pointer to reference counted data @@ -73009,160 +78417,35 @@ resources allocated for @mem_block. c:identifier="g_rc_box_release_full" version="2.58"> Releases a reference on the data pointed by @mem_block. + filename="glib/grcbox.c" + line="315">Releases a reference on the data pointed by @mem_block. If the reference was the last one, it will call @clear_func to clear the contents of @mem_block, and then will free the resources allocated for @mem_block. - + a pointer to reference counted data + filename="glib/grcbox.c" + line="317">a pointer to reference counted data a function to call when clearing the data + filename="glib/grcbox.c" + line="318">a function to call when clearing the data - - A "reference counted box", or "RcBox", is an opaque wrapper data type -that is guaranteed to be as big as the size of a given data type, and -which augments the given data type with reference counting semantics -for its memory management. - -RcBox is useful if you have a plain old data type, like a structure -typically placed on the stack, and you wish to provide additional API -to use it on the heap; or if you want to implement a new type to be -passed around by reference without necessarily implementing copy/free -semantics or your own reference counting. - -The typical use is: - -|[<!-- language="C" --> -typedef struct { - char *name; - char *address; - char *city; - char *state; - int age; -} Person; - -Person * -person_new (void) -{ - return g_rc_box_new0 (Person); -} -]| - -Every time you wish to acquire a reference on the memory, you should -call g_rc_box_acquire(); similarly, when you wish to release a reference -you should call g_rc_box_release(): - -|[<!-- language="C" --> -// Add a Person to the Database; the Database acquires ownership -// of the Person instance -void -add_person_to_database (Database *db, Person *p) -{ - db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p)); -} - -// Removes a Person from the Database; the reference acquired by -// add_person_to_database() is released here -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_rc_box_release (p); -} -]| - -If you have additional memory allocated inside the structure, you can -use g_rc_box_release_full(), which takes a function pointer, which -will be called if the reference released was the last: - -|[<!-- language="C" --> -void -person_clear (Person *p) -{ - g_free (p->name); - g_free (p->address); - g_free (p->city); - g_free (p->state); -} - -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_rc_box_release_full (p, (GDestroyNotify) person_clear); -} -]| - -If you wish to transfer the ownership of a reference counted data -type without increasing the reference count, you can use g_steal_pointer(): - -|[<!-- language="C" --> - Person *p = g_rc_box_new (Person); - - // fill_person_details() is defined elsewhere - fill_person_details (p); - - // add_person_to_database_no_ref() is defined elsewhere; it adds - // a Person to the Database without taking a reference - add_person_to_database_no_ref (db, g_steal_pointer (&p)); -]| - -## Thread safety - -The reference counting operations on data allocated using g_rc_box_alloc(), -g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's -responsibility to ensure that references are acquired are released on the -same thread. - -If you need thread safe reference counting, see the [atomic reference counted -data][arcbox] API. - -## Automatic pointer clean up - -If you want to add g_autoptr() support to your plain old data type through -reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and -g_rc_box_release(): - -|[<!-- language="C" --> -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release) -]| - -If you need to clear the contents of the data, you will need to use an -ancillary function that calls g_rc_box_release_full(): - -|[<!-- language="C" --> -static void -my_data_struct_release (MyDataStruct *data) -{ - // my_data_struct_clear() is defined elsewhere - g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); -} - -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) -]| - Reallocates the memory pointed to by @mem, so that it now has space for + filename="glib/gmem.c" + line="147">Reallocates the memory pointed to by @mem, so that it now has space for @n_bytes bytes of memory. It returns the new address of the memory, which may have been moved. @mem may be %NULL, in which case it's considered to have zero-length. @n_bytes may be 0, in which case %NULL will be returned @@ -73170,11 +78453,11 @@ and @mem will be freed unless it is %NULL. If the allocation fails (because the system is out of memory), the program is terminated. - + the new address of the allocated memory + filename="glib/gmem.c" + line="161">the new address of the allocated memory @@ -73183,31 +78466,31 @@ the program is terminated. nullable="1" allow-none="1"> the memory to reallocate + filename="glib/gmem.c" + line="149">the memory to reallocate new size of the memory in bytes + filename="glib/gmem.c" + line="150">new size of the memory in bytes This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, + filename="glib/gmem.c" + line="440">This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. If the allocation fails (because the system is out of memory), the program is terminated. - + the new address of the allocated memory + filename="glib/gmem.c" + line="453">the new address of the allocated memory @@ -73216,20 +78499,20 @@ the program is terminated. nullable="1" allow-none="1"> the memory to reallocate + filename="glib/gmem.c" + line="442">the memory to reallocate the number of blocks to allocate + filename="glib/gmem.c" + line="443">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="444">the size of each block in bytes @@ -73238,27 +78521,27 @@ the program is terminated. c:identifier="g_ref_count_compare" version="2.58"> Compares the current value of @rc with @val. - + filename="glib/grefcount.c" + line="152">Compares the current value of @rc with @val. + %TRUE if the reference count is the same + filename="glib/grefcount.c" + line="159">%TRUE if the reference count is the same as the given value the address of a reference count variable + filename="glib/grefcount.c" + line="154">the address of a reference count variable the value to compare + filename="glib/grefcount.c" + line="155">the value to compare @@ -73267,24 +78550,24 @@ the program is terminated. c:identifier="g_ref_count_dec" version="2.58"> Decreases the reference count. + filename="glib/grefcount.c" + line="118">Decreases the reference count. If %TRUE is returned, the reference count reached 0. After this point, @rc is an undefined state and must be reinitialized with g_ref_count_init() to be used again. - + %TRUE if the reference count reached 0, and %FALSE otherwise + filename="glib/grefcount.c" + line="128">%TRUE if the reference count reached 0, and %FALSE otherwise the address of a reference count variable + filename="glib/grefcount.c" + line="120">the address of a reference count variable @@ -73293,17 +78576,17 @@ g_ref_count_init() to be used again. c:identifier="g_ref_count_inc" version="2.58"> Increases the reference count. - + filename="glib/grefcount.c" + line="87">Increases the reference count. + the address of a reference count variable + filename="glib/grefcount.c" + line="89">the address of a reference count variable @@ -73312,17 +78595,17 @@ g_ref_count_init() to be used again. c:identifier="g_ref_count_init" version="2.58"> Initializes a reference count variable to 1. - + filename="glib/grefcount.c" + line="62">Initializes a reference count variable to 1. + the address of a reference count variable + filename="glib/grefcount.c" + line="64">the address of a reference count variable @@ -73331,42 +78614,75 @@ g_ref_count_init() to be used again. c:identifier="g_ref_string_acquire" version="2.58"> Acquires a reference on a string. - + filename="glib/grefstring.c" + line="214">Acquires a reference on a string. + the given string, with its reference count increased + filename="glib/grefstring.c" + line="220">the given string, with its reference count increased a reference counted string + filename="glib/grefstring.c" + line="216">a reference counted string + + Compares two ref-counted strings for byte-by-byte equality. + +It can be passed to [func@GLib.HashTable.new] as the key equality function, +and behaves exactly the same as [func@GLib.str_equal] (or `strcmp()`), but +can return slightly faster as it can check the string lengths before checking +all the bytes. + + + `TRUE` if the strings are equal, otherwise `FALSE` + + + + + a reference counted string + + + + a reference counted string + + + + Retrieves the length of @str. - + filename="glib/grefstring.c" + line="295">Retrieves the length of @str. + the length of the given string, in bytes + filename="glib/grefstring.c" + line="301">the length of the given string, in bytes a reference counted string + filename="glib/grefstring.c" + line="297">a reference counted string @@ -73375,21 +78691,21 @@ g_ref_count_init() to be used again. c:identifier="g_ref_string_new" version="2.58"> Creates a new reference counted string and copies the contents of @str + filename="glib/grefstring.c" + line="77">Creates a new reference counted string and copies the contents of @str into it. - + the newly created reference counted string + filename="glib/grefstring.c" + line="84">the newly created reference counted string a NUL-terminated string + filename="glib/grefstring.c" + line="79">a NUL-terminated string @@ -73398,26 +78714,26 @@ into it. c:identifier="g_ref_string_new_intern" version="2.58"> Creates a new reference counted string and copies the content of @str + filename="glib/grefstring.c" + line="169">Creates a new reference counted string and copies the content of @str into it. If you call this function multiple times with the same @str, or with the same contents of @str, it will return a new reference, instead of creating a new string. - + the newly created reference + filename="glib/grefstring.c" + line="180">the newly created reference counted string, or a new reference to an existing string a NUL-terminated string + filename="glib/grefstring.c" + line="171">a NUL-terminated string @@ -73426,30 +78742,30 @@ creating a new string. c:identifier="g_ref_string_new_len" version="2.58"> Creates a new reference counted string and copies the contents of @str + filename="glib/grefstring.c" + line="110">Creates a new reference counted string and copies the contents of @str into it, up to @len bytes. Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that @str has at least @len addressable bytes. - + the newly created reference counted string + filename="glib/grefstring.c" + line="121">the newly created reference counted string a string + filename="glib/grefstring.c" + line="112">a string length of @str to use, or -1 if @str is nul-terminated + filename="glib/grefstring.c" + line="113">length of @str to use, or -1 if @str is nul-terminated @@ -73458,111 +78774,30 @@ responsibility to ensure that @str has at least @len addressable bytes. c:identifier="g_ref_string_release" version="2.58"> Releases a reference on a string; if it was the last reference, the + filename="glib/grefstring.c" + line="234">Releases a reference on a string; if it was the last reference, the resources allocated by the string are freed as well. - + a reference counted string + filename="glib/grefstring.c" + line="236">a reference counted string - - Reference counting is a garbage collection mechanism that is based on -assigning a counter to a data type, or any memory area; the counter is -increased whenever a new reference to that data type is acquired, and -decreased whenever the reference is released. Once the last reference -is released, the resources associated to that data type are freed. - -GLib uses reference counting in many of its data types, and provides -the #grefcount and #gatomicrefcount types to implement safe and atomic -reference counting semantics in new data types. - -It is important to note that #grefcount and #gatomicrefcount should be -considered completely opaque types; you should always use the provided -API to increase and decrease the counters, and you should never check -their content directly, or compare their content with other values. - - - Reference counted strings are normal C strings that have been augmented -with a reference counter to manage their resources. You allocate a new -reference counted string and acquire and release references as needed, -instead of copying the string among callers; when the last reference on -the string is released, the resources allocated for it are freed. - -Typically, reference counted strings can be used when parsing data from -files and storing them into data structures that are passed to various -callers: - -|[<!-- language="C" --> -PersonDetails * -person_details_from_data (const char *data) -{ - // Use g_autoptr() to simplify error cases - g_autoptr(GRefString) full_name = NULL; - g_autoptr(GRefString) address = NULL; - g_autoptr(GRefString) city = NULL; - g_autoptr(GRefString) state = NULL; - g_autoptr(GRefString) zip_code = NULL; - - // parse_person_details() is defined elsewhere; returns refcounted strings - if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code)) - return NULL; - - if (!validate_zip_code (zip_code)) - return NULL; - - // add_address_to_cache() and add_full_name_to_cache() are defined - // elsewhere; they add strings to various caches, using refcounted - // strings to avoid copying data over and over again - add_address_to_cache (address, city, state, zip_code); - add_full_name_to_cache (full_name); - - // person_details_new() is defined elsewhere; it takes a reference - // on each string - PersonDetails *res = person_details_new (full_name, - address, - city, - state, - zip_code); - - return res; -} -]| - -In the example above, we have multiple functions taking the same strings -for different uses; with typical C strings, we'd have to copy the strings -every time the life time rules of the data differ from the life time of -the string parsed from the original buffer. With reference counted strings, -each caller can take a reference on the data, and keep it as long as it -needs to own the string. - -Reference counted strings can also be "interned" inside a global table -owned by GLib; while an interned string has at least a reference, creating -a new interned reference counted string with the same contents will return -a reference to the existing string instead of creating a new reference -counted string instance. Once the string loses its last reference, it will -be automatically removed from the global interned strings table. - Checks whether @replacement is a valid replacement string + filename="glib/gregex.c" + line="3503">Checks whether @replacement is a valid replacement string (see g_regex_replace()), i.e. that all escape sequences in it are valid. @@ -73571,18 +78806,18 @@ for pattern references. For instance, replacement text 'foo\n' does not contain references and may be evaluated without information about actual match, but '\0\1' (whole match followed by first subpattern) requires valid #GMatchInfo object. - + whether @replacement is a valid replacement string + filename="glib/gregex.c" + line="3520">whether @replacement is a valid replacement string the replacement string + filename="glib/gregex.c" + line="3505">the replacement string optional="1" allow-none="1"> location to store information about + filename="glib/gregex.c" + line="3506">location to store information about references in @replacement or %NULL @@ -73611,30 +78846,30 @@ subpattern) requires valid #GMatchInfo object. moved-to="Regex.escape_nul" version="2.30"> Escapes the nul characters in @string to "\x00". It can be used + filename="glib/gregex.c" + line="3548">Escapes the nul characters in @string to "\x00". It can be used to compile a regex with embedded nul characters. For completeness, @length can be -1 for a nul-terminated string. In this case the output string will be of course equal to @string. - + a newly-allocated escaped string + filename="glib/gregex.c" + line="3559">a newly-allocated escaped string the string to escape + filename="glib/gregex.c" + line="3550">the string to escape the length of @string + filename="glib/gregex.c" + line="3551">the length of @string @@ -73644,32 +78879,32 @@ In this case the output string will be of course equal to @string. moved-to="Regex.escape_string" version="2.14"> Escapes the special characters used for regular expressions + filename="glib/gregex.c" + line="3616">Escapes the special characters used for regular expressions in @string, for instance "a.b*c" becomes "a\.b\*c". This function is useful to dynamically generate regular expressions. @string can contain nul characters that are replaced with "\0", in this case remember to specify the correct length of @string in @length. - + a newly-allocated escaped string + filename="glib/gregex.c" + line="3629">a newly-allocated escaped string the string to escape + filename="glib/gregex.c" + line="3618">the string to escape the length of @string, in bytes, or -1 if @string is nul-terminated + filename="glib/gregex.c" + line="3619">the length of @string, in bytes, or -1 if @string is nul-terminated @@ -73679,8 +78914,8 @@ in @length. moved-to="Regex.match_simple" version="2.14"> Scans for a match in @string for @pattern. + filename="glib/gregex.c" + line="2105">Scans for a match in @string for @pattern. This function is equivalent to g_regex_match() but it does not require to compile the pattern with g_regex_new(), avoiding some @@ -73690,36 +78925,36 @@ substrings, capture counts, and so on. If this function is to be called on the same @pattern more than once, it's more efficient to compile the pattern once with g_regex_new() and then use g_regex_match(). - + %TRUE if the string matched, %FALSE otherwise + filename="glib/gregex.c" + line="2123">%TRUE if the string matched, %FALSE otherwise the regular expression + filename="glib/gregex.c" + line="2107">the regular expression the string to scan for matches + filename="glib/gregex.c" + line="2108">the string to scan for matches compile options for the regular expression, or 0 + filename="glib/gregex.c" + line="2109">compile options for the regular expression, or 0 match options, or 0 + filename="glib/gregex.c" + line="2110">match options, or 0 @@ -73729,8 +78964,8 @@ g_regex_new() and then use g_regex_match(). moved-to="Regex.split_simple" version="2.14"> Breaks the string on the pattern, and returns an array of + filename="glib/gregex.c" + line="2531">Breaks the string on the pattern, and returns an array of the tokens. If the pattern contains capturing parentheses, then the text for each of the substrings will also be returned. If the pattern does not match anywhere in the string, then the @@ -73757,11 +78992,11 @@ A pattern that can match empty strings splits @string into separate characters wherever it matches the empty string between characters. For example splitting "ab c" using as a separator "\s*", you will get "a", "b" and "c". - + a %NULL-terminated array of strings. Free + filename="glib/gregex.c" + line="2566">a %NULL-terminated array of strings. Free it using g_strfreev() @@ -73770,26 +79005,26 @@ it using g_strfreev() the regular expression + filename="glib/gregex.c" + line="2533">the regular expression the string to scan for matches + filename="glib/gregex.c" + line="2534">the string to scan for matches compile options for the regular expression, or 0 + filename="glib/gregex.c" + line="2535">compile options for the regular expression, or 0 match options, or 0 + filename="glib/gregex.c" + line="2536">match options, or 0 @@ -73798,8 +79033,8 @@ it using g_strfreev() c:identifier="g_reload_user_special_dirs_cache" version="2.22"> Resets the cache used for g_get_user_special_dir(), so + filename="glib/gutils.c" + line="2391">Resets the cache used for g_get_user_special_dir(), so that the latest on-disk version is used. Call this only if you just changed the data on disk yourself. @@ -73807,41 +79042,110 @@ Due to thread safety issues this may cause leaking of strings that were previously returned from g_get_user_special_dir() that can't be freed. We ensure to only leak the data for the directories that actually changed value though. - + + + A wrapper for the POSIX remove() function. The remove() function +deletes a name from the filesystem. + +See your C library manual for more details about how remove() works +on your system. On Unix, remove() removes also directories, as it +calls unlink() for files and rmdir() for directories. On Windows, +although remove() in the C library only works for files, this +function tries first remove() and then if that fails rmdir(), and +thus works for both files and directories. Note however, that on +Windows, it is in general not possible to remove a file that is +open to some process, or mapped into memory. + +If this function fails on Windows you can't infer too much from the +errno value. rmdir() is tried regardless of what caused remove() to +fail. Any errno value set by remove() will be overwritten by that +set by rmdir(). + + + 0 if the file was successfully removed, -1 if an error + occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + + + A wrapper for the POSIX rename() function. The rename() function +renames a file, moving it between directories if required. + +See your C library manual for more details about how rename() works +on your system. It is not possible in general on Windows to rename +a file that is open to some process. + + + 0 if the renaming succeeded, -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pathname in the GLib file name encoding + + + + Reallocates the memory pointed to by @mem, so that it now has space for + filename="glib/gmem.h" + line="336">Reallocates the memory pointed to by @mem, so that it now has space for @n_structs elements of type @struct_type. It returns the new address of the memory, which may have been moved. Care is taken to avoid overflow when calculating the size of the allocated block. - + the type of the elements to allocate + filename="glib/gmem.h" + line="338">the type of the elements to allocate the currently allocated memory + filename="glib/gmem.h" + line="339">the currently allocated memory the number of elements to allocate + filename="glib/gmem.h" + line="340">the number of elements to allocate - + @@ -73851,10 +79155,10 @@ Care is taken to avoid overflow when calculating the size of the allocated block c:identifier="g_return_if_fail_warning" introspectable="0"> Internal function used to print messages from the public g_return_if_fail() -and g_return_val_if_fail() macros. - + filename="glib/gmessages.c" + line="3060">Internal function used to print messages from the public [func@GLib.return_if_fail] +and [func@GLib.return_val_if_fail] macros. + @@ -73864,14 +79168,14 @@ and g_return_val_if_fail() macros. nullable="1" allow-none="1"> log domain + filename="glib/gmessages.c" + line="3062">log domain function containing the assertion + filename="glib/gmessages.c" + line="3063">function containing the assertion nullable="1" allow-none="1"> expression which failed + filename="glib/gmessages.c" + line="3064">expression which failed @@ -73888,12 +79192,12 @@ and g_return_val_if_fail() macros. - + - + @@ -73904,7 +79208,7 @@ and g_return_val_if_fail() macros. - + @@ -73912,61 +79216,55 @@ and g_return_val_if_fail() macros. A wrapper for the POSIX rmdir() function. The rmdir() function + filename="glib/gstdio.c" + line="1500">A wrapper for the POSIX rmdir() function. The rmdir() function deletes a directory from the filesystem. See your C library manual for more details about how rmdir() works on your system. - + 0 if the directory was successfully removed, -1 if an error + filename="glib/gstdio.c" + line="1511">0 if the directory was successfully removed, -1 if an error occurred a pathname in the GLib file name encoding + filename="glib/gstdio.c" + line="1502">a pathname in the GLib file name encoding (UTF-8 on Windows) - - The #GScanner and its associated functions provide a -general purpose lexical scanner. - Adds a symbol to the default scope. + filename="glib/gscanner.c" + line="659">Adds a symbol to the default scope. Use g_scanner_scope_add_symbol() instead. - + a #GScanner + filename="glib/gscanner.c" + line="661">a #GScanner the symbol to add + filename="glib/gscanner.c" + line="662">the symbol to add the value of the symbol + filename="glib/gscanner.c" + line="663">the value of the symbol @@ -73976,25 +79274,25 @@ general purpose lexical scanner. deprecated="1" deprecated-version="2.2"> Calls a function for each symbol in the default scope. + filename="glib/gscanner.c" + line="883">Calls a function for each symbol in the default scope. Use g_scanner_scope_foreach_symbol() instead. - + a #GScanner + filename="glib/gscanner.c" + line="885">a #GScanner the function to call with each symbol + filename="glib/gscanner.c" + line="886">the function to call with each symbol data to pass to the function + filename="glib/gscanner.c" + line="887">data to pass to the function @@ -74004,15 +79302,15 @@ general purpose lexical scanner. deprecated="1" deprecated-version="2.2"> There is no reason to use this macro, since it does nothing. + filename="glib/gscanner.c" + line="753">There is no reason to use this macro, since it does nothing. This macro does nothing. - + a #GScanner + filename="glib/gscanner.c" + line="755">a #GScanner @@ -74022,20 +79320,20 @@ general purpose lexical scanner. deprecated="1" deprecated-version="2.2"> Removes a symbol from the default scope. + filename="glib/gscanner.c" + line="715">Removes a symbol from the default scope. Use g_scanner_scope_remove_symbol() instead. - + a #GScanner + filename="glib/gscanner.c" + line="717">a #GScanner the symbol to remove + filename="glib/gscanner.c" + line="718">the symbol to remove @@ -74045,83 +79343,83 @@ general purpose lexical scanner. deprecated="1" deprecated-version="2.2"> There is no reason to use this macro, since it does nothing. + filename="glib/gscanner.c" + line="762">There is no reason to use this macro, since it does nothing. This macro does nothing. - + a #GScanner + filename="glib/gscanner.c" + line="764">a #GScanner - - The #GSequence data structure has the API of a list, but is -implemented internally with a balanced binary tree. This means that -most of the operations (access, search, insertion, deletion, ...) on -#GSequence are O(log(n)) in average and O(n) in worst case for time -complexity. But, note that maintaining a balanced sorted list of n -elements is done in time O(n log(n)). -The data contained in each element can be either integer values, by using -of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply -pointers to any type of data. - -A #GSequence is accessed through "iterators", represented by a -#GSequenceIter. An iterator represents a position between two -elements of the sequence. For example, the "begin" iterator -represents the gap immediately before the first element of the -sequence, and the "end" iterator represents the gap immediately -after the last element. In an empty sequence, the begin and end -iterators are the same. - -Some methods on #GSequence operate on ranges of items. For example -g_sequence_foreach_range() will call a user-specified function on -each element with the given range. The range is delimited by the -gaps represented by the passed-in iterators, so if you pass in the -begin and end iterators, the range in question is the entire -sequence. - -The function g_sequence_get() is used with an iterator to access the -element immediately following the gap that the iterator represents. -The iterator is said to "point" to that element. - -Iterators are stable across most operations on a #GSequence. For -example an iterator pointing to some element of a sequence will -continue to point to that element even after the sequence is sorted. -Even moving an element to another sequence using for example -g_sequence_move_range() will not invalidate the iterators pointing -to it. The only operation that will invalidate an iterator is when -the element it points to is removed from any sequence. - -To sort the data, either use g_sequence_insert_sorted() or -g_sequence_insert_sorted_iter() to add data to the #GSequence or, if -you want to add a large amount of data, it is more efficient to call -g_sequence_sort() or g_sequence_sort_iter() after doing unsorted -insertions. - + + Calls @func for each item in the range (@begin, @end) passing +@user_data to the function. @func must not modify the sequence +itself. + + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + a #GFunc + + + + user data passed to @func + + + + Returns the data that @iter points to. - + filename="glib/gsequence.c" + line="1153">Returns the data that @iter points to. + the data that @iter points to + filename="glib/gsequence.c" + line="1159">the data that @iter points to a #GSequenceIter + filename="glib/gsequence.c" + line="1155">a #GSequenceIter @@ -74131,20 +79429,20 @@ insertions. moved-to="Sequence.insert_before" version="2.14"> Inserts a new item just before the item pointed to by @iter. - + filename="glib/gsequence.c" + line="459">Inserts a new item just before the item pointed to by @iter. + an iterator pointing to the new item + filename="glib/gsequence.c" + line="466">an iterator pointing to the new item a #GSequenceIter + filename="glib/gsequence.c" + line="461">a #GSequenceIter nullable="1" allow-none="1"> the data for the new item + filename="glib/gsequence.c" + line="462">the data for the new item @@ -74163,26 +79461,26 @@ insertions. moved-to="Sequence.move" version="2.14"> Moves the item pointed to by @src to the position indicated by @dest. + filename="glib/gsequence.c" + line="1318">Moves the item pointed to by @src to the position indicated by @dest. After calling this function @dest will point to the position immediately after @src. It is allowed for @src and @dest to point into different sequences. - + a #GSequenceIter pointing to the item to move + filename="glib/gsequence.c" + line="1320">a #GSequenceIter pointing to the item to move a #GSequenceIter pointing to the position to which + filename="glib/gsequence.c" + line="1321">a #GSequenceIter pointing to the position to which the item is moved @@ -74193,8 +79491,8 @@ sequences. moved-to="Sequence.move_range" version="2.14"> Inserts the (@begin, @end) range at the destination pointed to by @dest. + filename="glib/gsequence.c" + line="543">Inserts the (@begin, @end) range at the destination pointed to by @dest. The @begin and @end iters must point into the same sequence. It is allowed for @dest to point to a different sequence than the one pointed into by @begin and @end. @@ -74202,27 +79500,27 @@ into by @begin and @end. If @dest is %NULL, the range indicated by @begin and @end is removed from the sequence. If @dest points to a place within the (@begin, @end) range, the range does not move. - + a #GSequenceIter + filename="glib/gsequence.c" + line="545">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="546">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="547">a #GSequenceIter @@ -74232,32 +79530,32 @@ the (@begin, @end) range, the range does not move. moved-to="Sequence.range_get_midpoint" version="2.14"> Finds an iterator somewhere in the range (@begin, @end). This + filename="glib/gsequence.c" + line="323">Finds an iterator somewhere in the range (@begin, @end). This iterator will be close to the middle of the range, but is not guaranteed to be exactly in the middle. The @begin and @end iterators must both point to the same sequence and @begin must come before or be equal to @end in the sequence. - + a #GSequenceIter pointing somewhere in the + filename="glib/gsequence.c" + line="335">a #GSequenceIter pointing somewhere in the (@begin, @end) range a #GSequenceIter + filename="glib/gsequence.c" + line="325">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="326">a #GSequenceIter @@ -74267,21 +79565,21 @@ and @begin must come before or be equal to @end in the sequence. moved-to="Sequence.remove" version="2.14"> Removes the item pointed to by @iter. It is an error to pass the + filename="glib/gsequence.c" + line="489">Removes the item pointed to by @iter. It is an error to pass the end iterator to this function. If the sequence has a data destroy function associated with it, this function is called on the data for the removed item. - + a #GSequenceIter + filename="glib/gsequence.c" + line="491">a #GSequenceIter @@ -74291,26 +79589,26 @@ function is called on the data for the removed item. moved-to="Sequence.remove_range" version="2.14"> Removes all items in the (@begin, @end) range. + filename="glib/gsequence.c" + line="517">Removes all items in the (@begin, @end) range. If the sequence has a data destroy function associated with it, this function is called on the data for the removed items. - + a #GSequenceIter + filename="glib/gsequence.c" + line="519">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="520">a #GSequenceIter @@ -74320,19 +79618,19 @@ function is called on the data for the removed items. moved-to="Sequence.set" version="2.14"> Changes the data for the item pointed to by @iter to be @data. If + filename="glib/gsequence.c" + line="1172">Changes the data for the item pointed to by @iter to be @data. If the sequence has a data destroy function associated with it, that function is called on the existing data that @iter pointed to. - + a #GSequenceIter + filename="glib/gsequence.c" + line="1174">a #GSequenceIter nullable="1" allow-none="1"> new data for the item + filename="glib/gsequence.c" + line="1175">new data for the item + + + + + + Moves the data pointed to by @iter to a new position as indicated by +@cmp_func. This +function should be called for items in a sequence already sorted according +to @cmp_func whenever some aspect of an item changes so that @cmp_func +may return different values for that item. + +@cmp_func is called with two items of the @seq, and @cmp_data. +It should return 0 if the items are equal, a negative value if +the first item comes before the second, and a positive value if +the second item comes before the first. + + + + + + + A #GSequenceIter + + + + the function used to compare items in the sequence + + + + user data passed to @cmp_func. + + + + + + Like g_sequence_sort_changed(), but uses +a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as +the compare function. + +@iter_cmp is called with two iterators pointing into the #GSequence that +@iter points into. It should +return 0 if the iterators are equal, a negative value if the first +iterator comes before the second, and a positive value if the second +iterator comes before the first. + + + + + + + a #GSequenceIter + + + + the function used to compare iterators in the sequence + + + + user data passed to @cmp_func @@ -74351,24 +79743,24 @@ function is called on the existing data that @iter pointed to. moved-to="Sequence.swap" version="2.14"> Swaps the items pointed to by @a and @b. It is allowed for @a and @b + filename="glib/gsequence.c" + line="1477">Swaps the items pointed to by @a and @b. It is allowed for @a and @b to point into difference sequences. - + a #GSequenceIter + filename="glib/gsequence.c" + line="1479">a #GSequenceIter a #GSequenceIter + filename="glib/gsequence.c" + line="1480">a #GSequenceIter @@ -74377,8 +79769,8 @@ to point into difference sequences. c:identifier="g_set_application_name" version="2.2"> Sets a human-readable name for the application. This name should be + filename="glib/gutils.c" + line="1221">Sets a human-readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with g_set_prgname(), which sets a non-localized name. g_set_prgname() will be called automatically by gtk_init(), @@ -74389,25 +79781,25 @@ be called once. The application name will be used in contexts such as error messages, or when displaying an application's name in the task list. - + localized name of the application + filename="glib/gutils.c" + line="1223">localized name of the application Does nothing if @err is %NULL; if @err is non-%NULL, then *@err -must be %NULL. A new #GError is created and assigned to *@err. - + filename="glib/gerror.c" + line="464">Does nothing if @err is %NULL; if @err is non-%NULL, then `*err` +must be %NULL. A new #GError is created and assigned to `*err`. + @@ -74419,32 +79811,32 @@ must be %NULL. A new #GError is created and assigned to *@err. optional="1" allow-none="1"> a return location for a #GError + filename="glib/gerror.c" + line="466">a return location for a #GError error domain + filename="glib/gerror.c" + line="467">error domain error code + filename="glib/gerror.c" + line="468">error code printf()-style format + filename="glib/gerror.c" + line="469">printf()-style format args for @format + filename="glib/gerror.c" + line="470">args for @format @@ -74453,13 +79845,13 @@ must be %NULL. A new #GError is created and assigned to *@err. c:identifier="g_set_error_literal" version="2.18"> Does nothing if @err is %NULL; if @err is non-%NULL, then *@err -must be %NULL. A new #GError is created and assigned to *@err. + filename="glib/gerror.c" + line="502">Does nothing if @err is %NULL; if @err is non-%NULL, then `*err` +must be %NULL. A new #GError is created and assigned to `*err`. Unlike g_set_error(), @message is not a printf()-style format string. Use this function if @message contains text you don't have control over, that could include printf() escape sequences. - + @@ -74471,34 +79863,34 @@ that could include printf() escape sequences. optional="1" allow-none="1"> a return location for a #GError + filename="glib/gerror.c" + line="504">a return location for a #GError error domain + filename="glib/gerror.c" + line="505">error domain error code + filename="glib/gerror.c" + line="506">error code error message + filename="glib/gerror.c" + line="507">error message Sets the name of the program. This name should not be localized, + filename="glib/gutils.c" + line="1147">Sets the name of the program. This name should not be localized, in contrast to g_set_application_name(). If you are using #GApplication the program name is set in @@ -74510,15 +79902,15 @@ taking the last component of @argv[0]. Since GLib 2.72, this function can be called multiple times and is fully thread safe. Prior to GLib 2.72, this function could only be called once per process. - + the name of the program. + filename="glib/gutils.c" + line="1149">the name of the program. @@ -74527,27 +79919,27 @@ could only be called once per process. c:identifier="g_set_print_handler" introspectable="0"> Sets the print handler to @func, or resets it to the -default GLib handler if %NULL. + filename="glib/gmessages.c" + line="3437">Sets the print handler to @func, or resets it to the +default GLib handler if `NULL`. -Any messages passed to g_print() will be output via +Any messages passed to [func@GLib.print] will be output via the new handler. The default handler outputs -the encoded message to stdout. By providing your own handler +the encoded message to `stdout`. By providing your own handler you can redirect the output, to a GTK widget or a log file for example. Since 2.76 this functions always returns a valid -#GPrintFunc, and never returns %NULL. If no custom +[type@GLib.PrintFunc], and never returns `NULL`. If no custom print handler was set, it will return the GLib default print handler and that can be re-used to -decorate its output and/or to write to stderr -in all platforms. Before GLib 2.76, this was %NULL. - +decorate its output and/or to write to `stderr` +in all platforms. Before GLib 2.76, this was `NULL`. + the old print handler + filename="glib/gmessages.c" + line="3458">the old print handler @@ -74556,8 +79948,8 @@ in all platforms. Before GLib 2.76, this was %NULL. nullable="1" allow-none="1"> the new print handler or %NULL to + filename="glib/gmessages.c" + line="3439">the new print handler or `NULL` to reset to the default @@ -74567,27 +79959,27 @@ in all platforms. Before GLib 2.76, this was %NULL. c:identifier="g_set_printerr_handler" introspectable="0"> Sets the handler for printing error messages to @func, -or resets it to the default GLib handler if %NULL. + filename="glib/gmessages.c" + line="3567">Sets the handler for printing error messages to @func, +or resets it to the default GLib handler if `NULL`. -Any messages passed to g_printerr() will be output via +Any messages passed to [func@GLib.printerr] will be output via the new handler. The default handler outputs the encoded -message to stderr. By providing your own handler you can +message to `stderr`. By providing your own handler you can redirect the output, to a GTK widget or a log file for example. Since 2.76 this functions always returns a valid -#GPrintFunc, and never returns %NULL. If no custom error +[type@GLib.PrintFunc], and never returns `NULL`. If no custom error print handler was set, it will return the GLib default error print handler and that can be re-used to decorate -its output and/or to write to stderr in all platforms. -Before GLib 2.76, this was %NULL. - +its output and/or to write to `stderr` in all platforms. +Before GLib 2.76, this was `NULL`. + the old error message handler + filename="glib/gmessages.c" + line="3588">the old error message handler @@ -74596,17 +79988,74 @@ Before GLib 2.76, this was %NULL. nullable="1" allow-none="1"> he new error message handler or %NULL - to reset to the default + filename="glib/gmessages.c" + line="3569">he new error message handler or `NULL` + to reset to the default + + Updates a pointer to a string to a copy of @new_str and returns whether the +string was changed. + +If @new_str matches the previous string, this function is a no-op. If +@new_str is different, a copy of it will be assigned to @str_pointer and +the previous string pointed to by @str_pointer will be freed with +[func@GLib.free]. + +@str_pointer must not be `NULL`, but can point to a `NULL` value. + +One convenient usage of this function is in implementing property settings: +```C +void +foo_set_bar (Foo *foo, + const char *new_bar) +{ + g_return_if_fail (IS_FOO (foo)); + + if (g_set_str (&foo->bar, new_bar)) + g_object_notify (foo, "bar"); +} +``` + + + true if the value of @str_pointer changed, false otherwise + + + + + a pointer to either + a string or `NULL` + + + + a string to assign to @str_pointer + + + + Sets an environment variable. On UNIX, both the variable's name and + filename="glib/genviron.c" + line="260">Sets an environment variable. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8. @@ -74625,46 +80074,35 @@ If you need to set up the environment for a child process, you can use g_get_environ() to get an environment array, modify that with g_environ_setenv() and g_environ_unsetenv(), and then pass that array directly to execvpe(), g_spawn_async(), or the like. - + %FALSE if the environment variable couldn't be set. + filename="glib/genviron.c" + line="287">%FALSE if the environment variable couldn't be set. the environment variable to set, must not + filename="glib/genviron.c" + line="262">the environment variable to set, must not contain '='. the value for to set the variable to. + filename="glib/genviron.c" + line="264">the value for to set the variable to. whether to change the variable if it already exists. + filename="glib/genviron.c" + line="265">whether to change the variable if it already exists. - - GLib provides the functions g_shell_quote() and g_shell_unquote() -to handle shell-like quoting in strings. The function g_shell_parse_argv() -parses a string similar to the way a POSIX shell (/bin/sh) would. - -Note that string handling in shells has many obscure and historical -corner-cases which these functions do not necessarily reproduce. They -are good enough in practice, though. - @@ -74674,8 +80112,8 @@ are good enough in practice, though. c:identifier="g_shell_parse_argv" throws="1"> Parses a command line into an argument vector, in much the same way + filename="glib/gshell.c" + line="617">Parses a command line into an argument vector, in much the same way the shell would, but without many of the expansions the shell would perform (variable expansion, globs, operators, filename expansion, etc. are not supported). @@ -74693,18 +80131,18 @@ guaranteed that @argvp will be a non-empty array if this function returns successfully. Free the returned vector with g_strfreev(). - + %TRUE on success, %FALSE if error set + filename="glib/gshell.c" + line="644">%TRUE on success, %FALSE if error set command line to parse + filename="glib/gshell.c" + line="619">command line to parse optional="1" allow-none="1"> return location for number of args + filename="glib/gshell.c" + line="620">return location for number of args optional="1" allow-none="1"> + filename="glib/gshell.c" + line="621"> return location for array of args @@ -74736,8 +80174,8 @@ Free the returned vector with g_strfreev(). Quotes a string so that the shell (/bin/sh) will interpret the + filename="glib/gshell.c" + line="179">Quotes a string so that the shell (/bin/sh) will interpret the quoted string to mean @unquoted_string. If you pass a filename to the shell, for example, you should first @@ -74747,26 +80185,26 @@ The return value must be freed with g_free(). The quoting style used is undefined (single or double quotes may be used). - + quoted string + filename="glib/gshell.c" + line="194">quoted string a literal string + filename="glib/gshell.c" + line="181">a literal string Unquotes a string as the shell (/bin/sh) would. + filename="glib/gshell.c" + line="233">Unquotes a string as the shell (/bin/sh) would. This function only handles quotes; if a string contains file globs, arithmetic operators, variables, backticks, redirections, or other @@ -74793,18 +80231,18 @@ literal string exactly. escape sequences are not allowed; not even like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and newline to be escaped with backslash. Otherwise double quotes preserve things literally. - + an unquoted string + filename="glib/gshell.c" + line="266">an unquoted string shell-quoted string + filename="glib/gshell.c" + line="235">shell-quoted string @@ -74814,29 +80252,29 @@ preserve things literally. version="2.48" introspectable="0"> Performs a checked addition of @a and @b, storing the result in + filename="glib/docs.c" + line="738">Performs a checked addition of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. - + a pointer to the #gsize destination + filename="glib/docs.c" + line="740">a pointer to the #gsize destination the #gsize left operand + filename="glib/docs.c" + line="741">the #gsize left operand the #gsize right operand + filename="glib/docs.c" + line="742">the #gsize right operand @@ -74845,107 +80283,107 @@ returned. version="2.48" introspectable="0"> Performs a checked multiplication of @a and @b, storing the result in + filename="glib/docs.c" + line="755">Performs a checked multiplication of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. - + a pointer to the #gsize destination + filename="glib/docs.c" + line="757">a pointer to the #gsize destination the #gsize left operand + filename="glib/docs.c" + line="758">the #gsize left operand the #gsize right operand + filename="glib/docs.c" + line="759">the #gsize right operand Allocates a block of memory from the libc allocator. + filename="glib/gslice.c" + line="171">Allocates a block of memory from the libc allocator. The block address handed out can be expected to be aligned to at least `1 * sizeof (void*)`. Since GLib 2.76 this always uses the system malloc() implementation internally. - + a pointer to the allocated memory block, which will + filename="glib/gslice.c" + line="183">a pointer to the allocated memory block, which will be %NULL if and only if @mem_size is 0 the number of bytes to allocate + filename="glib/gslice.c" + line="173">the number of bytes to allocate Allocates a block of memory via g_slice_alloc() and initializes + filename="glib/gslice.c" + line="199">Allocates a block of memory via g_slice_alloc() and initializes the returned memory to 0. Since GLib 2.76 this always uses the system malloc() implementation internally. - + a pointer to the allocated block, which will be %NULL + filename="glib/gslice.c" + line="209">a pointer to the allocated block, which will be %NULL if and only if @mem_size is 0 the number of bytes to allocate + filename="glib/gslice.c" + line="201">the number of bytes to allocate Allocates a block of memory from the slice allocator + filename="glib/gslice.c" + line="223">Allocates a block of memory from the slice allocator and copies @block_size bytes into it from @mem_block. @mem_block must be non-%NULL if @block_size is non-zero. Since GLib 2.76 this always uses the system malloc() implementation internally. - + a pointer to the allocated memory block, + filename="glib/gslice.c" + line="236">a pointer to the allocated memory block, which will be %NULL if and only if @mem_size is 0 the number of bytes to allocate + filename="glib/gslice.c" + line="225">the number of bytes to allocate nullable="1" allow-none="1"> the memory to copy + filename="glib/gslice.c" + line="226">the memory to copy @@ -74964,8 +80402,8 @@ internally. version="2.14" introspectable="0"> A convenience macro to duplicate a block of memory using + filename="glib/gslice.c" + line="106">A convenience macro to duplicate a block of memory using the slice allocator. It calls g_slice_copy() with `sizeof (@type)` @@ -74976,17 +80414,17 @@ This can never return %NULL. Since GLib 2.76 this always uses the system malloc() implementation internally. - + the type to duplicate, typically a structure name + filename="glib/gslice.c" + line="108">the type to duplicate, typically a structure name the memory to copy into the allocated block + filename="glib/gslice.c" + line="109">the memory to copy into the allocated block @@ -74995,56 +80433,56 @@ internally. version="2.10" introspectable="0"> A convenience macro to free a block of memory that has + filename="glib/gslice.c" + line="129">A convenience macro to free a block of memory that has been allocated from the slice allocator. It calls g_slice_free1() using `sizeof (type)` as the block size. Note that the exact release behaviour can be changed with the -[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable. +[`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem is %NULL, this macro does nothing. Since GLib 2.76 this always uses the system free() implementation internally. - + the type of the block to free, typically a structure name + filename="glib/gslice.c" + line="131">the type of the block to free, typically a structure name a pointer to the block to free + filename="glib/gslice.c" + line="132">a pointer to the block to free Frees a block of memory. + filename="glib/gslice.c" + line="251">Frees a block of memory. The memory must have been allocated via g_slice_alloc() or g_slice_alloc0() and the @block_size has to match the size specified upon allocation. Note that the exact release behaviour -can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment +can be changed with the [`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem_block is %NULL, this function does nothing. Since GLib 2.76 this always uses the system free_sized() implementation internally. - + the size of the block + filename="glib/gslice.c" + line="253">the size of the block nullable="1" allow-none="1"> a pointer to the block to free + filename="glib/gslice.c" + line="254">a pointer to the block to free @@ -75063,35 +80501,35 @@ internally. version="2.10" introspectable="0"> Frees a linked list of memory blocks of structure type @type. + filename="glib/gslice.c" + line="149">Frees a linked list of memory blocks of structure type @type. The memory blocks must be equal-sized, allocated via g_slice_alloc() or g_slice_alloc0() and linked together by a @next pointer (similar to #GSList). The name of the @next field in @type is passed as third argument. Note that the exact release behaviour can be changed with the -[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable. +[`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem_chain is %NULL, this function does nothing. Since GLib 2.76 this always uses the system free() implementation internally. - + the type of the @mem_chain blocks + filename="glib/gslice.c" + line="151">the type of the @mem_chain blocks a pointer to the first block of the chain + filename="glib/gslice.c" + line="152">a pointer to the first block of the chain the field name of the next pointer in @type + filename="glib/gslice.c" + line="153">the field name of the next pointer in @type @@ -75099,29 +80537,29 @@ Since GLib 2.76 this always uses the system free() implementation internally. Frees a linked list of memory blocks of structure type @type. + filename="glib/gslice.c" + line="281">Frees a linked list of memory blocks of structure type @type. The memory blocks must be equal-sized, allocated via g_slice_alloc() or g_slice_alloc0() and linked together by a @next pointer (similar to #GSList). The offset of the @next field in each block is passed as third argument. Note that the exact release behaviour can be changed with the -[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable. +[`G_DEBUG=gc-friendly`](running.html#environment-variables) environment variable. If @mem_chain is %NULL, this function does nothing. Since GLib 2.76 this always uses the system free_sized() implementation internally. - + the size of the blocks + filename="glib/gslice.c" + line="283">the size of the blocks nullable="1" allow-none="1"> a pointer to the first block of the chain + filename="glib/gslice.c" + line="284">a pointer to the first block of the chain the offset of the @next field in the blocks + filename="glib/gslice.c" + line="285">the offset of the @next field in the blocks - + @@ -75154,7 +80592,7 @@ internally. - + @@ -75175,8 +80613,8 @@ internally. version="2.10" introspectable="0"> A convenience macro to allocate a block of memory from the + filename="glib/gslice.c" + line="60">A convenience macro to allocate a block of memory from the slice allocator. It calls g_slice_alloc() with `sizeof (@type)` and casts the @@ -75188,12 +80626,12 @@ This can never return %NULL as the minimum allocation size from Since GLib 2.76 this always uses the system malloc() implementation internally. - + the type to allocate, typically a structure name + filename="glib/gslice.c" + line="62">the type to allocate, typically a structure name @@ -75202,8 +80640,8 @@ internally. version="2.10" introspectable="0"> A convenience macro to allocate a block of memory from the + filename="glib/gslice.c" + line="83">A convenience macro to allocate a block of memory from the slice allocator and set the memory to 0. It calls g_slice_alloc0() with `sizeof (@type)` @@ -75215,17 +80653,17 @@ This can never return %NULL as the minimum allocation size from Since GLib 2.76 this always uses the system malloc() implementation internally. - + the type to allocate, typically a structure name + filename="glib/gslice.c" + line="85">the type to allocate, typically a structure name - + @@ -75242,27 +80680,48 @@ internally. c:identifier="g_slist_next" introspectable="0"> A convenience macro to get the next element in a #GSList. + filename="glib/gslist.c" + line="49">A convenience macro to get the next element in a #GSList. Note that it is considered perfectly acceptable to access @slist->next directly. - + an element in a #GSList. + filename="glib/gslist.c" + line="51">an element in a #GSList. + + + + + + + + + + + + + + + + + A safer form of the standard sprintf() function. The output is guaranteed + filename="glib/gprintf.c" + line="133">A safer form of the standard sprintf() function. The output is guaranteed to not exceed @n characters (including the terminating nul character), so it is easy to ensure that a buffer overflow cannot occur. -See also g_strdup_printf(). +See also [func@GLib.strdup_printf]. In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. @@ -75271,83 +80730,140 @@ string. The return value of g_snprintf() conforms to the snprintf() function as standardized in ISO C99. Note that this is different from -traditional snprintf(), which returns the length of the output string. +traditional `snprintf()`, which returns the length of the output string. The format string may contain positional parameters, as specified in the Single Unix Specification. - + the number of bytes which would be produced if the buffer - was large enough. + filename="glib/gprintf.c" + line="160">the number of bytes which would be produced if the buffer + was large enough the buffer to hold the output. + filename="glib/gprintf.c" + line="135">the buffer to hold the output the maximum number of bytes to produce (including the - terminating nul character). + filename="glib/gprintf.c" + line="136">the maximum number of bytes to produce (including the + terminating nul character) a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="138">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output. + filename="glib/gprintf.c" + line="140">the arguments to insert in the output + + This is just like the standard C [`qsort()`](man:qsort(3)) function, but +the comparison routine accepts a user data argument +(like [`qsort_r()`](man:qsort_r(3))). + +Unlike `qsort()`, this is guaranteed to be a stable sort. + + + + + + + start of array to sort + + + + + + number of elements in the array + + + + size of each element + + + + function to compare elements + + + + data to pass to @compare_func + + + + Removes the source with the given ID from the default main context. You must -use g_source_destroy() for sources added to a non-default main context. + filename="glib/gmain.c" + line="2521">Removes the source with the given ID from the default main context. You must +use [method@GLib.Source.destroy] for sources added to a non-default main context. -The ID of a #GSource is given by g_source_get_id(), or will be -returned by the functions g_source_attach(), g_idle_add(), -g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), -g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and -g_io_add_watch_full(). +The ID of a #GSource is given by [method@GLib.Source.get_id], or will be +returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add], +[func@GLib.idle_add_full], [func@GLib.timeout_add], +[func@GLib.timeout_add_full], [func@GLib.child_watch_add], +[func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and +[func@GLib.io_add_watch_full]. It is a programmer error to attempt to remove a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. - + %TRUE if the source was found and removed. + filename="glib/gmain.c" + line="2546">%TRUE if the source was found and removed. the ID of the source to remove. + filename="glib/gmain.c" + line="2523">the ID of the source to remove. @@ -75356,22 +80872,22 @@ wrong source. c:identifier="g_source_remove_by_funcs_user_data" moved-to="Source.remove_by_funcs_user_data"> Removes a source from the default main loop context given the + filename="glib/gmain.c" + line="2589">Removes a source from the default main loop context given the source functions and user data. If multiple sources exist with the same source functions and user data, only one will be destroyed. - + %TRUE if a source was found and removed. + filename="glib/gmain.c" + line="2598">%TRUE if a source was found and removed. The @source_funcs passed to g_source_new() + filename="glib/gmain.c" + line="2591">The @source_funcs passed to [ctor@GLib.Source.new] nullable="1" allow-none="1"> the user data for the callback + filename="glib/gmain.c" + line="2592">the user data for the callback @@ -75389,15 +80905,15 @@ same source functions and user data, only one will be destroyed. c:identifier="g_source_remove_by_user_data" moved-to="Source.remove_by_user_data"> Removes a source from the default main loop context given the user + filename="glib/gmain.c" + line="2564">Removes a source from the default main loop context given the user data for the callback. If multiple sources exist with the same user data, only one will be destroyed. - + %TRUE if a source was found and removed. + filename="glib/gmain.c" + line="2572">%TRUE if a source was found and removed. @@ -75406,8 +80922,8 @@ data, only one will be destroyed. nullable="1" allow-none="1"> the user_data for the callback. + filename="glib/gmain.c" + line="2566">the user_data for the callback. @@ -75417,11 +80933,11 @@ data, only one will be destroyed. moved-to="Source.set_name_by_id" version="2.26"> Sets the name of a source using its ID. + filename="glib/gmain.c" + line="2150">Sets the name of a source using its ID. This is a convenience utility to set source names from the return -value of g_idle_add(), g_timeout_add(), etc. +value of [func@GLib.idle_add], [func@GLib.timeout_add], etc. It is a programmer error to attempt to set the name of a non-existent source. @@ -75429,26 +80945,26 @@ source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source. - + a #GSource ID + filename="glib/gmain.c" + line="2152">a #GSource ID debug name for the source + filename="glib/gmain.c" + line="2153">debug name for the source @@ -75456,91 +80972,34 @@ wrong source. Gets the smallest prime number from a built-in array of primes which + filename="glib/gprimes.c" + line="74">Gets the smallest prime number from a built-in array of primes which is larger than @num. This is used within GLib to calculate the optimum size of a #GHashTable. The built-in array of primes ranges from 11 to 13845163 such that each prime is approximately 1.5-2 times the previous prime. - + the smallest prime number from a built-in array of primes + filename="glib/gprimes.c" + line="85">the smallest prime number from a built-in array of primes which is larger than @num a #guint + filename="glib/gprimes.c" + line="76">a #guint - - GLib supports spawning of processes with an API that is more -convenient than the bare UNIX fork() and exec(). - -The g_spawn family of functions has synchronous (g_spawn_sync()) -and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), -as well as convenience variants that take a complete shell-like -commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). - -See #GSubprocess in GIO for a higher-level API that provides -stream interfaces for communication with child processes. - -An example of using g_spawn_async_with_pipes(): -|[<!-- language="C" --> -const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; -gint child_stdout, child_stderr; -GPid child_pid; -g_autoptr(GError) error = NULL; - -// Spawn child process. -g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, - NULL, &child_pid, NULL, &child_stdout, - &child_stderr, &error); -if (error != NULL) - { - g_error ("Spawning child failed: %s", error->message); - return; - } - -// Add a child watch function which will be called when the child process -// exits. -g_child_watch_add (child_pid, child_watch_cb, NULL); - -// You could watch for output on @child_stdout and @child_stderr using -// #GUnixInputStream or #GIOChannel here. - -static void -child_watch_cb (GPid pid, - gint status, - gpointer user_data) -{ - g_message ("Child %" G_PID_FORMAT " exited %s", pid, - g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally"); - - // Free any resources associated with the child here, such as I/O channels - // on its stdout and stderr FDs. If you have no code to put in the - // child_watch_cb() callback, you can remove it and the g_child_watch_add() - // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, - // otherwise the child process will stay around as a zombie until this - // process exits. - - g_spawn_close_pid (pid); -} -]| - Executes a child program asynchronously. + filename="glib/gspawn.c" + line="35">Executes a child program asynchronously. See g_spawn_async_with_pipes() for a full description; this function simply calls the g_spawn_async_with_pipes() without any pipes. @@ -75556,11 +81015,11 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, Note that the returned @child_pid on Windows is a handle to the child process and not its identifier. Process handles and process identifiers are different concepts on Windows. - + %TRUE on success, %FALSE if error is set + filename="glib/gspawn.c" + line="67">%TRUE on success, %FALSE if error is set @@ -75569,15 +81028,15 @@ are different concepts on Windows. nullable="1" allow-none="1"> child's current working + filename="glib/gspawn.c" + line="37">child's current working directory, or %NULL to inherit parent's + filename="glib/gspawn.c" + line="39"> child's argument vector @@ -75588,8 +81047,8 @@ are different concepts on Windows. nullable="1" allow-none="1"> + filename="glib/gspawn.c" + line="41"> child's environment, or %NULL to inherit parent's @@ -75597,8 +81056,8 @@ are different concepts on Windows. flags from #GSpawnFlags + filename="glib/gspawn.c" + line="43">flags from #GSpawnFlags scope="async" closure="5"> function to run + filename="glib/gspawn.c" + line="44">function to run in the child just before `exec()` @@ -75618,8 +81077,8 @@ are different concepts on Windows. nullable="1" allow-none="1"> user data for @child_setup + filename="glib/gspawn.c" + line="46">user data for @child_setup optional="1" allow-none="1"> return location for child process reference, or %NULL + filename="glib/gspawn.c" + line="47">return location for child process reference, or %NULL @@ -75640,16 +81099,16 @@ are different concepts on Windows. version="2.58" throws="1"> Executes a child program asynchronously. + filename="glib/gspawn.c" + line="474">Executes a child program asynchronously. Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, so no FD assignments are used. - + %TRUE on success, %FALSE if an error was set + filename="glib/gspawn.c" + line="495">%TRUE on success, %FALSE if an error was set @@ -75658,14 +81117,14 @@ so no FD assignments are used. nullable="1" allow-none="1"> child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding + filename="glib/gspawn.c" + line="476">child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding child's argument vector, in the GLib file name encoding; + filename="glib/gspawn.c" + line="477">child's argument vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated @@ -75676,16 +81135,16 @@ so no FD assignments are used. nullable="1" allow-none="1"> child's environment, or %NULL to inherit parent's, in the GLib file name encoding + filename="glib/gspawn.c" + line="479">child's environment, or %NULL to inherit parent's, in the GLib file name encoding flags from #GSpawnFlags + filename="glib/gspawn.c" + line="480">flags from #GSpawnFlags scope="async" closure="5"> function to run + filename="glib/gspawn.c" + line="481">function to run in the child just before `exec()` @@ -75705,8 +81164,8 @@ so no FD assignments are used. nullable="1" allow-none="1"> user data for @child_setup + filename="glib/gspawn.c" + line="483">user data for @child_setup optional="1" allow-none="1"> return location for child process ID, or %NULL + filename="glib/gspawn.c" + line="484">return location for child process ID, or %NULL file descriptor to use for child's stdin, or `-1` + filename="glib/gspawn.c" + line="485">file descriptor to use for child's stdin, or `-1` file descriptor to use for child's stdout, or `-1` + filename="glib/gspawn.c" + line="486">file descriptor to use for child's stdout, or `-1` file descriptor to use for child's stderr, or `-1` + filename="glib/gspawn.c" + line="487">file descriptor to use for child's stderr, or `-1` @@ -75744,14 +81203,14 @@ so no FD assignments are used. c:identifier="g_spawn_async_with_pipes" throws="1"> Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, + filename="glib/gspawn.c" + line="157">Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, so no FD assignments are used. - + %TRUE on success, %FALSE if an error was set + filename="glib/gspawn.c" + line="179">%TRUE on success, %FALSE if an error was set @@ -75760,15 +81219,15 @@ so no FD assignments are used. nullable="1" allow-none="1"> child's current working + filename="glib/gspawn.c" + line="159">child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding child's argument + filename="glib/gspawn.c" + line="161">child's argument vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated @@ -75779,8 +81238,8 @@ so no FD assignments are used. nullable="1" allow-none="1"> + filename="glib/gspawn.c" + line="163"> child's environment, or %NULL to inherit parent's, in the GLib file name encoding @@ -75789,8 +81248,8 @@ so no FD assignments are used. flags from #GSpawnFlags + filename="glib/gspawn.c" + line="166">flags from #GSpawnFlags scope="async" closure="5"> function to run + filename="glib/gspawn.c" + line="167">function to run in the child just before `exec()` @@ -75810,8 +81269,8 @@ so no FD assignments are used. nullable="1" allow-none="1"> user data for @child_setup + filename="glib/gspawn.c" + line="169">user data for @child_setup optional="1" allow-none="1"> return location for child process ID, or %NULL + filename="glib/gspawn.c" + line="170">return location for child process ID, or %NULL optional="1" allow-none="1"> return location for file descriptor to write to child's stdin, or %NULL + filename="glib/gspawn.c" + line="171">return location for file descriptor to write to child's stdin, or %NULL optional="1" allow-none="1"> return location for file descriptor to read child's stdout, or %NULL + filename="glib/gspawn.c" + line="172">return location for file descriptor to read child's stdout, or %NULL optional="1" allow-none="1"> return location for file descriptor to read child's stderr, or %NULL + filename="glib/gspawn.c" + line="173">return location for file descriptor to read child's stderr, or %NULL @@ -75865,8 +81324,8 @@ so no FD assignments are used. version="2.68" throws="1"> Executes a child program asynchronously (your program will not + filename="glib/gspawn.c" + line="208">Executes a child program asynchronously (your program will not block waiting for the child to exit). The child program is specified by the only argument that must be @@ -76060,11 +81519,11 @@ If you are writing a GTK application, and the program you are spawning is a graphical application too, then to ensure that the spawned program opens its windows on the right screen, you may want to use #GdkAppLaunchContext, #GAppLaunchContext, or set the `DISPLAY` environment variable. - + %TRUE on success, %FALSE if an error was set + filename="glib/gspawn.c" + line="430">%TRUE on success, %FALSE if an error was set @@ -76073,15 +81532,15 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, nullable="1" allow-none="1"> child's current working + filename="glib/gspawn.c" + line="210">child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding child's argument + filename="glib/gspawn.c" + line="212">child's argument vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated @@ -76092,8 +81551,8 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, nullable="1" allow-none="1"> + filename="glib/gspawn.c" + line="214"> child's environment, or %NULL to inherit parent's, in the GLib file name encoding @@ -76102,8 +81561,8 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, flags from #GSpawnFlags + filename="glib/gspawn.c" + line="217">flags from #GSpawnFlags function to run + filename="glib/gspawn.c" + line="218">function to run in the child just before `exec()` @@ -76123,26 +81582,26 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, nullable="1" allow-none="1"> user data for @child_setup + filename="glib/gspawn.c" + line="220">user data for @child_setup file descriptor to use for child's stdin, or `-1` + filename="glib/gspawn.c" + line="221">file descriptor to use for child's stdin, or `-1` file descriptor to use for child's stdout, or `-1` + filename="glib/gspawn.c" + line="222">file descriptor to use for child's stdout, or `-1` file descriptor to use for child's stderr, or `-1` + filename="glib/gspawn.c" + line="223">file descriptor to use for child's stderr, or `-1` array of FDs from the parent + filename="glib/gspawn.c" + line="224">array of FDs from the parent process to make available in the child process @@ -76162,8 +81621,8 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, nullable="1" allow-none="1"> array of FDs to remap + filename="glib/gspawn.c" + line="226">array of FDs to remap @source_fds to in the child process @@ -76171,8 +81630,8 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, number of FDs in @source_fds and @target_fds + filename="glib/gspawn.c" + line="228">number of FDs in @source_fds and @target_fds return location for child process ID, or %NULL + filename="glib/gspawn.c" + line="229">return location for child process ID, or %NULL return location for file descriptor to write to child's stdin, or %NULL + filename="glib/gspawn.c" + line="230">return location for file descriptor to write to child's stdin, or %NULL return location for file descriptor to read child's stdout, or %NULL + filename="glib/gspawn.c" + line="231">return location for file descriptor to read child's stdout, or %NULL return location for file descriptor to read child's stderr, or %NULL + filename="glib/gspawn.c" + line="232">return location for file descriptor to read child's stderr, or %NULL @@ -76228,8 +81687,8 @@ windows on the right screen, you may want to use #GdkAppLaunchContext, deprecated-version="2.70" throws="1"> An old name for g_spawn_check_wait_status(), deprecated because its + filename="glib/gspawn.c" + line="707">An old name for g_spawn_check_wait_status(), deprecated because its name is misleading. Despite the name of the function, @wait_status must be the wait status @@ -76238,19 +81697,19 @@ etc. On Unix platforms, it is incorrect for it to be the exit status as passed to `exit()` or returned by g_subprocess_get_exit_status() or `WEXITSTATUS()`. Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses. - + %TRUE if child exited successfully, %FALSE otherwise (and + filename="glib/gspawn.c" + line="721">%TRUE if child exited successfully, %FALSE otherwise (and @error will be set) A status as returned from g_spawn_sync() + filename="glib/gspawn.c" + line="709">A status as returned from g_spawn_sync() @@ -76260,8 +81719,8 @@ as passed to `exit()` or returned by g_subprocess_get_exit_status() or version="2.70" throws="1"> Set @error if @wait_status indicates the child exited abnormally + filename="glib/gspawn.c" + line="650">Set @error if @wait_status indicates the child exited abnormally (e.g. with a nonzero exit code, or via a fatal signal). The g_spawn_sync() and g_child_watch_add() family of APIs return the @@ -76300,39 +81759,39 @@ change in future versions of GLib. Prior to version 2.70, g_spawn_check_exit_status() provides the same functionality, although under a misleading name. - + %TRUE if child exited successfully, %FALSE otherwise (and + filename="glib/gspawn.c" + line="695">%TRUE if child exited successfully, %FALSE otherwise (and @error will be set) A platform-specific wait status as returned from g_spawn_sync() + filename="glib/gspawn.c" + line="652">A platform-specific wait status as returned from g_spawn_sync() On some platforms, notably Windows, the #GPid type represents a resource + filename="glib/gspawn.c" + line="735">On some platforms, notably Windows, the #GPid type represents a resource which must be closed to prevent resource leaking. g_spawn_close_pid() is provided for this purpose. It should be used on all platforms, even though it doesn't do anything under UNIX. - + The process reference to close + filename="glib/gspawn.c" + line="737">The process reference to close @@ -76341,8 +81800,8 @@ though it doesn't do anything under UNIX. c:identifier="g_spawn_command_line_async" throws="1"> A simple version of g_spawn_async() that parses a command line with + filename="glib/gspawn.c" + line="604">A simple version of g_spawn_async() that parses a command line with g_shell_parse_argv() and passes it to g_spawn_async(). Runs a command line in the background. Unlike g_spawn_async(), the @@ -76352,18 +81811,18 @@ consider using g_spawn_async() directly if appropriate. Possible errors are those from g_shell_parse_argv() and g_spawn_async(). The same concerns on Windows apply as for g_spawn_command_line_sync(). - + %TRUE on success, %FALSE if error is set + filename="glib/gspawn.c" + line="620">%TRUE on success, %FALSE if error is set a command line + filename="glib/gspawn.c" + line="606">a command line @@ -76372,8 +81831,8 @@ The same concerns on Windows apply as for g_spawn_command_line_sync(). c:identifier="g_spawn_command_line_sync" throws="1"> A simple version of g_spawn_sync() with little-used parameters + filename="glib/gspawn.c" + line="531">A simple version of g_spawn_sync() with little-used parameters removed, taking a command line instead of an argument vector. See g_spawn_sync() for full details. @@ -76402,18 +81861,18 @@ canonical Windows paths, like "c:\\program files\\app\\app.exe", as the backslashes will be eaten, and the space will act as a separator. You need to enclose such paths with single quotes, like "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". - + %TRUE on success, %FALSE if an error was set + filename="glib/gspawn.c" + line="569">%TRUE on success, %FALSE if an error was set a command line + filename="glib/gspawn.c" + line="533">a command line return location for child output + filename="glib/gspawn.c" + line="534">return location for child output @@ -76436,8 +81895,8 @@ separator. You need to enclose such paths with single quotes, like optional="1" allow-none="1"> return location for child errors + filename="glib/gspawn.c" + line="535">return location for child errors @@ -76449,8 +81908,8 @@ separator. You need to enclose such paths with single quotes, like optional="1" allow-none="1"> return location for child wait status, as returned by waitpid() + filename="glib/gspawn.c" + line="536">return location for child wait status, as returned by waitpid() @@ -76468,8 +81927,8 @@ separator. You need to enclose such paths with single quotes, like Executes a child synchronously (waits for the child to exit before returning). + filename="glib/gspawn.c" + line="89">Executes a child synchronously (waits for the child to exit before returning). All output from the child is stored in @standard_output and @standard_error, if those parameters are non-%NULL. Note that you must set the @@ -76492,11 +81951,11 @@ If an error occurs, no data is returned in @standard_output, This function calls g_spawn_async_with_pipes() internally; see that function for full details on the other parameters and details on how these functions work on Windows. - + %TRUE on success, %FALSE if an error was set + filename="glib/gspawn.c" + line="130">%TRUE on success, %FALSE if an error was set @@ -76505,15 +81964,15 @@ how these functions work on Windows. nullable="1" allow-none="1"> child's current working + filename="glib/gspawn.c" + line="91">child's current working directory, or %NULL to inherit parent's + filename="glib/gspawn.c" + line="93"> child's argument vector, which must be non-empty and %NULL-terminated @@ -76524,8 +81983,8 @@ how these functions work on Windows. nullable="1" allow-none="1"> + filename="glib/gspawn.c" + line="95"> child's environment, or %NULL to inherit parent's @@ -76533,8 +81992,8 @@ how these functions work on Windows. flags from #GSpawnFlags + filename="glib/gspawn.c" + line="97">flags from #GSpawnFlags scope="call" closure="5"> function to run + filename="glib/gspawn.c" + line="98">function to run in the child just before `exec()` @@ -76554,8 +82013,8 @@ how these functions work on Windows. nullable="1" allow-none="1"> user data for @child_setup + filename="glib/gspawn.c" + line="100">user data for @child_setup optional="1" allow-none="1"> return location for child output, or %NULL + filename="glib/gspawn.c" + line="101">return location for child output, or %NULL @@ -76578,8 +82037,8 @@ how these functions work on Windows. optional="1" allow-none="1"> return location for child error messages, or %NULL + filename="glib/gspawn.c" + line="102">return location for child error messages, or %NULL @@ -76591,8 +82050,8 @@ how these functions work on Windows. optional="1" allow-none="1"> return location for child wait status, as returned by waitpid(), or %NULL + filename="glib/gspawn.c" + line="103">return location for child wait status, as returned by waitpid(), or %NULL @@ -76602,53 +82061,241 @@ how these functions work on Windows. version="2.2" introspectable="0"> An implementation of the standard sprintf() function which supports + filename="glib/gprintf.c" + line="95">An implementation of the standard `sprintf()` function which supports positional parameters, as specified in the Single Unix Specification. -Note that it is usually better to use g_snprintf(), to avoid the +Note that it is usually better to use [func@GLib.snprintf], to avoid the risk of buffer overflow. `glib/gprintf.h` must be explicitly included in order to use this function. -See also g_strdup_printf(). - +See also [func@GLib.strdup_printf]. + the number of bytes printed. + filename="glib/gprintf.c" + line="114">the number of bytes printed A pointer to a memory buffer to contain the resulting string. It - is up to the caller to ensure that the allocated buffer is large - enough to hold the formatted result + filename="glib/gprintf.c" + line="97">A pointer to a memory buffer to contain the resulting string. It + is up to the caller to ensure that the allocated buffer is large + enough to hold the formatted result. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="100">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the arguments to insert in the output. + filename="glib/gprintf.c" + line="102">the arguments to insert in the output - + + A wrapper for the POSIX stat() function. The stat() function +returns information about a file. On Windows the stat() function in +the C library checks only the FAT-style READONLY attribute and does +not look at the ACL at all. Thus on Windows the protection bits in +the @st_mode field are a fabrication of little use. + +On Windows the Microsoft C libraries have several variants of the +stat struct and stat() function with names like _stat(), _stat32(), +_stat32i64() and _stat64i32(). The one used here is for 32-bit code +the one with 32-bit size and time fields, specifically called _stat32(). + +In Microsoft's compiler, by default struct stat means one with +64-bit time fields while in MinGW struct stat is the legacy one +with 32-bit fields. To hopefully clear up this messs, the gstdio.h +header defines a type #GStatBuf which is the appropriate struct type +depending on the platform and/or compiler being used. On POSIX it +is just struct stat, but note that even on POSIX platforms, stat() +might be a macro. + +See your C library manual for more details about stat(). + + + 0 if the information was successfully retrieved, + -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pointer to a stat struct, which will be filled with the file + information + + + + + + Works like g_mutex_lock(), but for a #GStaticMutex. + Use g_mutex_lock() + + + + a #GStaticMutex. + + + + + Works like g_mutex_trylock(), but for a #GStaticMutex. + Use g_mutex_trylock() + + + + a #GStaticMutex. + + + + + Works like g_mutex_unlock(), but for a #GStaticMutex. + Use g_mutex_unlock() + + + + a #GStaticMutex. + + + + + Sets @fd_ptr to `-1`, returning the value that was there before. + +Conceptually, this transfers the ownership of the file descriptor +from the referenced variable to the caller of the function (i.e. +‘steals’ the reference). This is very similar to [func@GLib.steal_pointer], +but for file descriptors. + +On POSIX platforms, this function is async-signal safe +(see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + + the value that @fd_ptr previously had + + + + + A pointer to a file descriptor + + + + + + Sets @handle_pointer to `0`, returning the value that was there before. + +Conceptually, this transfers the ownership of the handle ID from the +referenced variable to the ‘caller’ of the macro (ie: ‘steals’ the +handle ID). + +This can be very useful to make ownership transfer explicit, or to prevent +a handle from being released multiple times. For example: + +```c +void +maybe_unsubscribe_signal (ContextStruct *data) +{ + if (some_complex_logic (data)) + { + g_dbus_connection_signal_unsubscribe (data->connection, + g_steal_handle_id (&data->subscription_id)); + // now data->subscription_id isn’t a dangling handle + } +} +``` + +While [func@GLib.clear_handle_id] can be used in many of the same situations +as `g_steal_handle_id()`, this is one situation where it cannot be used, as +there is no way to pass the `GDBusConnection` to a +[type@GLib.ClearHandleFunc]. + + + + + + + a pointer to a handle ID + + + + + Sets @pp to %NULL, returning the value that was there before. Conceptually, this transfers the ownership of the pointer from the @@ -76697,48 +82344,52 @@ get_object (GObject **obj_out) In the above example, the object will be automatically freed in the early error case and also in the case that %NULL was given for @obj_out. - + + + + - + a pointer to a pointer + - + Copies a nul-terminated string into the destination buffer, including + filename="glib/gstrfuncs.c" + line="451">Copies a nul-terminated string into the destination buffer, including the trailing nul byte, and returns a pointer to the trailing nul byte in `dest`. The return value is useful for concatenating multiple strings without having to repeatedly scan for the end. - + a pointer to the trailing nul byte in `dest`. + filename="glib/gstrfuncs.c" + line="461">a pointer to the trailing nul byte in `dest` destination buffer. + filename="glib/gstrfuncs.c" + line="453">destination buffer source string. + filename="glib/gstrfuncs.c" + line="454">source string Compares two strings for byte-by-byte equality and returns %TRUE + filename="glib/ghash.c" + line="2421">Compares two strings for byte-by-byte equality and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using non-%NULL strings as keys in a #GHashTable. @@ -76746,24 +82397,24 @@ if they are equal. It can be passed to g_hash_table_new() as the This function is typically used for hash table comparisons, but can be used for general purpose comparisons of non-%NULL strings. For a %NULL-safe string comparison function, see g_strcmp0(). - + %TRUE if the two keys match + filename="glib/ghash.c" + line="2435">%TRUE if the two keys match a key + filename="glib/ghash.c" + line="2423">a key a key to compare with @v1 + filename="glib/ghash.c" + line="2424">a key to compare with @v1 @@ -76772,26 +82423,26 @@ comparison function, see g_strcmp0(). c:identifier="g_str_has_prefix" version="2.2"> Looks whether the string @str begins with @prefix. - + filename="glib/gstrfuncs.c" + line="2930">Looks whether the string @str begins with @prefix. + %TRUE if @str begins with @prefix, %FALSE otherwise. + filename="glib/gstrfuncs.c" + line="2937">true if @str begins with @prefix, false otherwise a nul-terminated string + filename="glib/gstrfuncs.c" + line="2932">a string to look in the nul-terminated prefix to look for + filename="glib/gstrfuncs.c" + line="2933">the prefix to look for @@ -76800,34 +82451,34 @@ comparison function, see g_strcmp0(). c:identifier="g_str_has_suffix" version="2.2"> Looks whether the string @str ends with @suffix. - + filename="glib/gstrfuncs.c" + line="2901">Looks whether a string ends with @suffix. + %TRUE if @str end with @suffix, %FALSE otherwise. + filename="glib/gstrfuncs.c" + line="2908">true if @str ends with @suffix, false otherwise a nul-terminated string + filename="glib/gstrfuncs.c" + line="2903">a string to look in the nul-terminated suffix to look for + filename="glib/gstrfuncs.c" + line="2904">the suffix to look for Converts a string to a hash value. + filename="glib/ghash.c" + line="2447">Converts a string to a hash value. This function implements the widely used "djb" hash apparently posted by Daniel Bernstein to comp.lang.c some time ago. The 32 @@ -76841,39 +82492,39 @@ when using non-%NULL strings as keys in a #GHashTable. Note that this function may not be a perfect fit for all use cases. For example, it produces some hash collisions with strings as short as 2. - + a hash value corresponding to the key + filename="glib/ghash.c" + line="2466">a hash value corresponding to the key a string key + filename="glib/ghash.c" + line="2449">a string key Determines if a string is pure ASCII. A string is pure ASCII if it + filename="glib/gutf8.c" + line="1892">Determines if a string is pure ASCII. A string is pure ASCII if it contains no bytes with the high bit set. - + %TRUE if @str is ASCII + filename="glib/gutf8.c" + line="1899">true if @str is ASCII a string + filename="glib/gutf8.c" + line="1894">a string @@ -76882,12 +82533,12 @@ contains no bytes with the high bit set. c:identifier="g_str_match_string" version="2.40"> Checks if a search conducted for @search_term should match + filename="glib/gstrfuncs.c" + line="3144">Checks if a search conducted for @search_term should match @potential_hit. -This function calls g_str_tokenize_and_fold() on both -@search_term and @potential_hit. ASCII alternates are never taken +This function calls [func@GLib.str_tokenize_and_fold] on both +@search_term and @potential_hit. ASCII alternates are never taken for @search_term but will be taken for @potential_hit according to the value of @accept_alternates. @@ -76895,9 +82546,9 @@ A hit occurs when each folded token in @search_term is a prefix of a folded token from @potential_hit. Depending on how you're performing the search, it will typically be -faster to call g_str_tokenize_and_fold() on each string in +faster to call `g_str_tokenize_and_fold()` on each string in your corpus and build an index on the returned folded tokens, then -call g_str_tokenize_and_fold() on the search term and +call `g_str_tokenize_and_fold()` on the search term and perform lookups into that index. As some examples, searching for ‘fred’ would match the potential hit @@ -76905,38 +82556,38 @@ As some examples, searching for ‘fred’ would match the potential hit ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). - + %TRUE if @potential_hit is a hit + filename="glib/gstrfuncs.c" + line="3173">true if @potential_hit is a hit the search term from the user + filename="glib/gstrfuncs.c" + line="3146">the search term from the user the text that may be a hit + filename="glib/gstrfuncs.c" + line="3147">the text that may be a hit %TRUE to accept ASCII alternates + filename="glib/gstrfuncs.c" + line="3148">if true, ASCII alternates are accepted Transliterate @str to plain ASCII. + filename="glib/gtranslit.c" + line="303">Transliterate @str to plain ASCII. For best results, @str should be in composed normalised form. @@ -76954,18 +82605,18 @@ If @from_locale is %NULL then the current locale is used. If you want to do translation for no specific locale, and you want it to be done independently of the currently locale, specify `"C"` for @from_locale. - + a string in plain ASCII + filename="glib/gtranslit.c" + line="327">a string in plain ASCII a string, in UTF-8 + filename="glib/gtranslit.c" + line="305">a string, in UTF-8 the source locale, if known + filename="glib/gtranslit.c" + line="306">the source locale, if known @@ -76983,27 +82634,27 @@ to be done independently of the currently locale, specify `"C"` for c:identifier="g_str_tokenize_and_fold" version="2.40"> Tokenises @string and performs folding on each token. + filename="glib/gstrfuncs.c" + line="3058">Tokenizes @string and performs folding on each token. A token is a non-empty sequence of alphanumeric characters in the source string, separated by non-alphanumeric characters. An "alphanumeric" character for this purpose is one that matches -g_unichar_isalnum() or g_unichar_ismark(). +[func@GLib.unichar_isalnum] or [func@GLib.unichar_ismark]. Each token is then (Unicode) normalised and case-folded. If -@ascii_alternates is non-%NULL and some of the returned tokens +@ascii_alternates is non-`NULL` and some of the returned tokens contain non-ASCII characters, ASCII alternatives will be generated. The number of ASCII alternatives that are generated and the method for doing so is unspecified, but @translit_locale (if specified) may improve the transliteration if the language of the source string is known. - + the folded tokens + filename="glib/gstrfuncs.c" + line="3082">the folded tokens @@ -77011,8 +82662,8 @@ known. a string + filename="glib/gstrfuncs.c" + line="3060">a string to tokenize nullable="1" allow-none="1"> the language code (like 'de' or + filename="glib/gstrfuncs.c" + line="3061">the language code (like 'de' or 'en_GB') from which @string originates + transfer-ownership="full" + optional="1" + allow-none="1"> a - return location for ASCII alternates + filename="glib/gstrfuncs.c" + line="3063"> + a return location for ASCII alternates @@ -77041,48 +82694,46 @@ known. For each character in @string, if the character is not in @valid_chars, + filename="glib/gstrfuncs.c" + line="2050">For each character in @string, if the character is not in @valid_chars, replaces the character with @substitutor. Modifies @string in place, and return @string itself, not a copy. The return value is to allow nesting such as: +```C +g_ascii_strup (g_strcanon (str, "abc", '?')) +``` -|[<!-- language="C" --> - g_ascii_strup (g_strcanon (str, "abc", '?')) -]| - -In order to modify a copy, you may use g_strdup(): - -|[<!-- language="C" --> - reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); - ... - g_free (reformatted); -]| - +In order to modify a copy, you may use [func@GLib.strdup]: +```C +reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); +… +g_free (reformatted); +``` + the modified @string + filename="glib/gstrfuncs.c" + line="2072">the modified @string a nul-terminated array of bytes + filename="glib/gstrfuncs.c" + line="2052">a nul-terminated array of bytes bytes permitted in @string + filename="glib/gstrfuncs.c" + line="2053">bytes permitted in @string replacement character for disallowed bytes + filename="glib/gstrfuncs.c" + line="2054">replacement character for disallowed bytes @@ -77092,38 +82743,38 @@ In order to modify a copy, you may use g_strdup(): deprecated="1" deprecated-version="2.2"> A case-insensitive string comparison, corresponding to the standard -strcasecmp() function on platforms which support it. - See g_strncasecmp() for a discussion of why this - function is deprecated and how to replace it. - + filename="glib/gstrfuncs.c" + line="1895">A case-insensitive string comparison, corresponding to the standard +`strcasecmp()` function on platforms which support it. + See [func@GLib.strncasecmp] for a discussion of why this + function is deprecated and how to replace it. + 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. + filename="glib/gstrfuncs.c" + line="1903">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2 a string + filename="glib/gstrfuncs.c" + line="1897">string to compare with @s2 a string to compare with @s1 + filename="glib/gstrfuncs.c" + line="1898">string to compare with @s1 Removes trailing whitespace from a string. + filename="glib/gstrfuncs.c" + line="2327">Removes trailing whitespace from a string. This function doesn't allocate or reallocate any memory; it modifies @string in place. Therefore, it cannot be used @@ -77131,27 +82782,27 @@ on statically allocated strings. The pointer to @string is returned to allow the nesting of functions. -Also see g_strchug() and g_strstrip(). - +Also see [func@GLib.strchug] and [func@GLib.strstrip]. + @string + filename="glib/gstrfuncs.c" + line="2341">the modified @string a string to remove the trailing whitespace from + filename="glib/gstrfuncs.c" + line="2329">a string to remove the trailing whitespace from Removes leading whitespace from a string, by moving the rest + filename="glib/gstrfuncs.c" + line="2295">Removes leading whitespace from a string, by moving the rest of the characters forward. This function doesn't allocate or reallocate any memory; @@ -77160,34 +82811,36 @@ statically allocated strings. The pointer to @string is returned to allow the nesting of functions. -Also see g_strchomp() and g_strstrip(). - +Also see [func@GLib.strchomp] and [func@GLib.strstrip]. + @string + filename="glib/gstrfuncs.c" + line="2310">the modified @string a string to remove the leading whitespace from + filename="glib/gstrfuncs.c" + line="2297">a string to remove the leading whitespace from Compares @str1 and @str2 like strcmp(). Handles %NULL -gracefully by sorting it before non-%NULL strings. -Comparing two %NULL pointers returns 0. - + filename="glib/gtestutils.c" + line="3646">Compares @str1 and @str2 like `strcmp()`. + +Handles `NULL` gracefully by sorting it before non-`NULL` strings. +Comparing two `NULL` pointers returns 0. + an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. + filename="glib/gtestutils.c" + line="3656">an integer less than, equal to, or greater than zero, + if @str1 is <, == or > than @str2 @@ -77196,8 +82849,8 @@ Comparing two %NULL pointers returns 0. nullable="1" allow-none="1"> a C string or %NULL + filename="glib/gtestutils.c" + line="3648">a string nullable="1" allow-none="1"> another C string or %NULL + filename="glib/gtestutils.c" + line="3649">another string Replaces all escaped characters with their one byte equivalent. - -This function does the reverse conversion of g_strescape(). - + filename="glib/gstrfuncs.c" + line="2093">Makes a copy of a string replacing C string-style escape +sequences with their one byte equivalent: + +- `\b` → [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) +- `\f` → [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) +- `\n` → [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) +- `\r` → [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) +- `\t` → [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) +- `\v` → [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) +- `\` followed by one to three octal digits → the numeric value (mod 255) +- `\` followed by any other character → the character as is. + For example, `\\` will turn into a backslash (`\`) and `\"` into a double quote (`"`). + +[func@GLib.strescape] does the reverse conversion. + a newly-allocated copy of @source with all escaped - character compressed + filename="glib/gstrfuncs.c" + line="2112">a newly-allocated copy of @source with all escaped + character compressed a string to compress + filename="glib/gstrfuncs.c" + line="2095">a string to compress Concatenates all of the given strings into one long string. The -returned string should be freed with g_free() when no longer needed. + filename="glib/gstrfuncs.c" + line="547">Concatenates all of the given strings into one long string. -The variable argument list must end with %NULL. If you forget the %NULL, -g_strconcat() will start appending random memory junk to your string. +The variable argument list must end with `NULL`. If you forget the `NULL`, +`g_strconcat()` will start appending random memory junk to your string. Note that this function is usually not the right function to use to assemble a translated message from pieces, since proper translation often requires the pieces to be reordered. - + a newly-allocated string containing all the string arguments + filename="glib/gstrfuncs.c" + line="561">a newly-allocated string containing all the string arguments the first string to add, which must not be %NULL + filename="glib/gstrfuncs.c" + line="549">the first string to add, which must not be `NULL` a %NULL-terminated list of strings to append to the string + filename="glib/gstrfuncs.c" + line="550">a `NULL`-terminated list of strings to append to the string Converts any delimiter characters in @string to @new_delimiter. + filename="glib/gstrfuncs.c" + line="2002">Converts any delimiter characters in @string to @new_delimiter. Any characters in @string which are found in @delimiters are changed to the @new_delimiter character. Modifies @string in place, and returns @string itself, not a copy. The return value is to allow nesting such as: +```C +g_ascii_strup (g_strdelimit (str, "abc", '?')) +``` -|[<!-- language="C" --> - g_ascii_strup (g_strdelimit (str, "abc", '?')) -]| - -In order to modify a copy, you may use g_strdup(): - -|[<!-- language="C" --> - reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); - ... - g_free (reformatted); -]| - +In order to modify a copy, you may use [func@GLib.strdup]: +```C +reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); +… +g_free (reformatted); +``` + the modified @string + filename="glib/gstrfuncs.c" + line="2027">the modified @string the string to convert + filename="glib/gstrfuncs.c" + line="2004">the string to convert a string containing the current delimiters, - or %NULL to use the standard delimiters defined in %G_STR_DELIMITERS + filename="glib/gstrfuncs.c" + line="2005">a string containing the current delimiters, or + `NULL` to use the standard delimiters defined in [const@GLib.STR_DELIMITERS] the new delimiter character + filename="glib/gstrfuncs.c" + line="2007">the new delimiter character @@ -77327,38 +82988,36 @@ In order to modify a copy, you may use g_strdup(): deprecated="1" deprecated-version="2.2"> Converts a string to lower case. + filename="glib/gstrfuncs.c" + line="1607">Converts a string to lower case. This function is totally broken for the reasons discussed -in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() -instead. - + in the [func@GLib.strncasecmp] docs — use [func@GLib.ascii_strdown] or + [func@GLib.utf8_strdown] instead. + the string + filename="glib/gstrfuncs.c" + line="1613">the string the string to convert. + filename="glib/gstrfuncs.c" + line="1609">the string to convert Duplicates a string. If @str is %NULL it returns %NULL. -The returned string should be freed with g_free() -when no longer needed. - + filename="glib/gstrfuncs.c" + line="306">Duplicates a string. If @str is `NULL` it returns `NULL`. + a newly-allocated copy of @str + filename="glib/gstrfuncs.c" + line="312">a newly-allocated copy of @str @@ -77367,8 +83026,8 @@ when no longer needed. nullable="1" allow-none="1"> the string to duplicate + filename="glib/gstrfuncs.c" + line="308">the string to duplicate @@ -77377,34 +83036,34 @@ when no longer needed. c:identifier="g_strdup_printf" introspectable="0"> Similar to the standard C sprintf() function but safer, since it + filename="glib/gstrfuncs.c" + line="516">Similar to the standard C `sprintf()` function but safer, since it calculates the maximum space required and allocates memory to hold -the result. The returned string should be freed with g_free() when no -longer needed. +the result. The returned string is guaranteed to be non-NULL, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. - - + + a newly-allocated string holding the result + filename="glib/gstrfuncs.c" + line="530">a newly-allocated string holding the + result a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gstrfuncs.c" + line="518">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the parameters to insert into the format string + filename="glib/gstrfuncs.c" + line="520">the parameters to insert into the format string @@ -77413,53 +83072,54 @@ representation is available for the given character. c:identifier="g_strdup_vprintf" introspectable="0"> Similar to the standard C vsprintf() function but safer, since it + filename="glib/gstrfuncs.c" + line="485">Similar to the standard C `vsprintf()` function but safer, since it calculates the maximum space required and allocates memory to hold -the result. The returned string should be freed with g_free() when -no longer needed. +the result. The returned string is guaranteed to be non-NULL, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. -See also g_vasprintf(), which offers the same functionality, but +See also [func@GLib.vasprintf], which offers the same functionality, but additionally returns the length of the allocated string. - - + + a newly-allocated string holding the result + filename="glib/gstrfuncs.c" + line="502">a newly-allocated string holding the + result a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gstrfuncs.c" + line="487">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of parameters to insert into the format string + filename="glib/gstrfuncs.c" + line="489">the list of parameters to insert into the format string - + Copies %NULL-terminated array of strings. The copy is a deep copy; -the new array should be freed by first freeing each string, then -the array itself. g_strfreev() does this for you. If called -on a %NULL value, g_strdupv() simply returns %NULL. - - + filename="glib/gstrfuncs.c" + line="2565">Copies an array of strings. The copy is a deep copy; each string is also +copied. + +If called on a `NULL` value, `g_strdupv()` simply returns `NULL`. + + a new %NULL-terminated array of strings. + filename="glib/gstrfuncs.c" + line="2574">a + newly-allocated array of strings. Use [func@GLib.strfreev] to free it. @@ -77470,75 +83130,88 @@ on a %NULL value, g_strdupv() simply returns %NULL. nullable="1" allow-none="1"> a %NULL-terminated array of strings - + filename="glib/gstrfuncs.c" + line="2567">an array of strings to copy + + + Returns a string corresponding to the given error code, e.g. "no -such process". Unlike strerror(), this always returns a string in + filename="glib/gstrfuncs.c" + line="1259">Returns a string corresponding to the given error code, e.g. "no +such process". + +Unlike `strerror()`, this always returns a string in UTF-8 encoding, and the pointer is guaranteed to remain valid for -the lifetime of the process. +the lifetime of the process. If the error code is unknown, it returns a +string like “Unknown error <code\>”. Note that the string may be translated according to the current locale. -The value of %errno will not be changed by this function. However, it may +The value of `errno` will not be changed by this function. However, it may be changed by intermediate function calls, so you should save its value as soon as the call returns: -|[ - int saved_errno; +```C +int saved_errno; - ret = read (blah); - saved_errno = errno; +ret = read (blah); +saved_errno = errno; - g_strerror (saved_errno); -]| - +g_strerror (saved_errno); +``` + a UTF-8 string describing the error code. If the error code - is unknown, it returns a string like "Unknown error: <code>". + filename="glib/gstrfuncs.c" + line="1285">the string describing the error code the system error number. See the standard C %errno - documentation + filename="glib/gstrfuncs.c" + line="1261">the system error number. See the standard C `errno` documentation Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' -and '"' in the string @source by inserting a '\' before -them. Additionally all characters in the range 0x01-0x1F (everything + filename="glib/gstrfuncs.c" + line="2182">It replaces the following special characters in the string @source +with their corresponding C escape sequence: + +| Symbol | Escape | +|-----------------------------------------------------------------------------|--------| +| [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) | `\b` | +| [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) | `\f` | +| [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) | `\n` | +| [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) | `\r` | +| [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) | `\t` | +| [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) | `\v` | + +It also inserts a backslash (`\`) before any backslash or a double quote (`"`). +Additionally all characters in the range 0x01-0x1F (everything below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are -replaced with a '\' followed by their octal representation. +replaced with a backslash followed by their octal representation. Characters supplied in @exceptions are not escaped. -g_strcompress() does the reverse conversion. - +[func@GLib.strcompress] does the reverse conversion. + a newly-allocated copy of @source with certain - characters escaped. See above. + filename="glib/gstrfuncs.c" + line="2207">a newly-allocated copy of @source with special characters escaped a string to escape + filename="glib/gstrfuncs.c" + line="2184">a string to escape nullable="1" allow-none="1"> a string of characters not to escape in @source + filename="glib/gstrfuncs.c" + line="2185">a string of characters not to escape in @source Frees a %NULL-terminated array of strings, as well as each -string it contains. + filename="glib/gstrfuncs.c" + line="2542">Frees an array of strings, as well as each string it contains. -If @str_array is %NULL, this function simply returns. - +If @str_array is `NULL`, this function simply returns. + a %NULL-terminated array of strings to free - + filename="glib/gstrfuncs.c" + line="2544">an + array of strings to free + + + - - String chunks are used to store groups of strings. Memory is -allocated in blocks, and as strings are added to the #GStringChunk -they are copied into the next free position in a block. When a block -is full a new block is allocated. - -When storing a large number of strings, string chunks are more -efficient than using g_strdup() since fewer calls to malloc() are -needed, and less memory is wasted in memory allocation overheads. - -By adding strings with g_string_chunk_insert_const() it is also -possible to remove duplicates. - -To create a new #GStringChunk use g_string_chunk_new(). - -To add strings to a #GStringChunk use g_string_chunk_insert(). - -To add strings to a #GStringChunk, but without duplicating strings -which are already in the #GStringChunk, use -g_string_chunk_insert_const(). - -To free the entire #GStringChunk use g_string_chunk_free(). It is -not possible to free individual strings. - - - This section describes a number of utility functions for creating, -duplicating, and manipulating strings. - -Note that the functions g_printf(), g_fprintf(), g_sprintf(), -g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() -are declared in the header `gprintf.h` which is not included in `glib.h` -(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to -explicitly include `<glib/gprintf.h>` in order to use the GLib -printf() functions. - -## String precision pitfalls # {#string-precision} - -While you may use the printf() functions to format UTF-8 strings, -notice that the precision of a \%Ns parameter is interpreted -as the number of bytes, not characters to print. On top of that, -the GNU libc implementation of the printf() functions has the -"feature" that it checks that the string given for the \%Ns -parameter consists of a whole number of characters in the current -encoding. So, unless you are sure you are always going to be in an -UTF-8 locale or your know your text is restricted to ASCII, avoid -using \%Ns. If your intention is to format strings for a -certain number of columns, then \%Ns is not a correct solution -anyway, since it fails to take wide characters (see g_unichar_iswide()) -into account. - -Note also that there are various printf() parameters which are platform -dependent. GLib provides platform independent macros for these parameters -which should be used instead. A common example is %G_GUINT64_FORMAT, which -should be used instead of `%llu` or similar parameters for formatting -64-bit integers. These macros are all named `G_*_FORMAT`; see -[Basic Types][glib-Basic-Types]. - - - A #GString is an object that handles the memory management of a C -string for you. The emphasis of #GString is on text, typically -UTF-8. Crucially, the "str" member of a #GString is guaranteed to -have a trailing nul character, and it is therefore always safe to -call functions such as strchr() or g_strdup() on it. - -However, a #GString can also hold arbitrary binary data, because it -has a "len" member, which includes any possible embedded nul -characters in the data. Conceptually then, #GString is like a -#GByteArray with the addition of many convenience methods for text, -and a guaranteed nul terminator. - An auxiliary function for gettext() support (see Q_()). - + filename="glib/ggettext.c" + line="160">An auxiliary function for gettext() support (see Q_()). + @msgval, unless @msgval is identical to @msgid + filename="glib/ggettext.c" + line="167">@msgval, unless @msgval is identical to @msgid and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned. @@ -77669,30 +83268,29 @@ and a guaranteed nul terminator. a string + filename="glib/ggettext.c" + line="162">a string another string + filename="glib/ggettext.c" + line="163">another string Joins a number of strings together to form one long string, with the -optional @separator inserted between each of them. The returned string -should be freed with g_free(). - + filename="glib/gstrfuncs.c" + line="2660">Joins a number of strings together to form one long string, with the +optional @separator inserted between each of them. + a newly-allocated string containing all of the strings joined - together, with @separator between them + filename="glib/gstrfuncs.c" + line="2668">a newly-allocated string containing all of the strings joined + together, with @separator between them @@ -77701,35 +83299,33 @@ should be freed with g_free(). nullable="1" allow-none="1"> a string to insert between each of the - strings, or %NULL + filename="glib/gstrfuncs.c" + line="2662">a string to insert between each of the strings a %NULL-terminated list of strings to join + filename="glib/gstrfuncs.c" + line="2663">a `NULL`-terminated list of strings to join Joins a number of strings together to form one long string, with the -optional @separator inserted between each of them. The returned string -should be freed with g_free(). + filename="glib/gstrfuncs.c" + line="2605">Joins an array of strings together to form one long string, with the +optional @separator inserted between each of them. If @str_array has no items, the return value will be an empty string. If @str_array contains a single item, @separator will not appear in the resulting string. - + a newly-allocated string containing all of the strings joined - together, with @separator between them + filename="glib/gstrfuncs.c" + line="2617">a newly-allocated string containing all of the strings joined + together, with @separator between them @@ -77738,107 +83334,108 @@ appear in the resulting string. nullable="1" allow-none="1"> a string to insert between each of the - strings, or %NULL + filename="glib/gstrfuncs.c" + line="2607">a string to insert between each of the strings a %NULL-terminated array of strings to join - + filename="glib/gstrfuncs.c" + line="2608">an array of strings to join + + + Portability wrapper that calls strlcat() on systems which have it, + filename="glib/gstrfuncs.c" + line="1483">Portability wrapper that calls `strlcat()` on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing nul-termination for @dest. The total size of @dest won't exceed @dest_size. -At most @dest_size - 1 characters will be copied. Unlike strncat(), +At most @dest_size - 1 characters will be copied. Unlike `strncat()`, @dest_size is the full size of dest, not the space left over. This function does not allocate memory. It always nul-terminates (unless @dest_size == 0 or there were no nul characters in the @dest_size characters of dest to start with). -Caveat: this is supposedly a more secure alternative to strcat() or -strncat(), but for real security g_strconcat() is harder to mess up. - +Caveat: this is supposedly a more secure alternative to `strcat()` or +`strncat()`, but for real security [func@GLib.strconcat] is harder to mess up. + size of attempted result, which is MIN (dest_size, strlen - (original dest)) + strlen (src), so if retval >= dest_size, - truncation occurred. + filename="glib/gstrfuncs.c" + line="1504">size of attempted result, which is `MIN (dest_size, strlen + (original dest)) + strlen (src)`, so if @retval >= @dest_size, + truncation occurred destination buffer, already containing one nul-terminated string + filename="glib/gstrfuncs.c" + line="1485">destination buffer, already containing one nul-terminated string source buffer + filename="glib/gstrfuncs.c" + line="1486">source buffer length of @dest buffer in bytes (not length of existing string - inside @dest) + filename="glib/gstrfuncs.c" + line="1487">length of @dest buffer in bytes (not length of existing string + inside @dest) Portability wrapper that calls strlcpy() on systems which have it, -and emulates strlcpy() otherwise. Copies @src to @dest; @dest is + filename="glib/gstrfuncs.c" + line="1424">Portability wrapper that calls `strlcpy()` on systems which have it, +and emulates `strlcpy()` otherwise. Copies @src to @dest; @dest is guaranteed to be nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not the number of bytes to copy. At most @dest_size - 1 characters will be copied. Always nul-terminates (unless @dest_size is 0). This function does not allocate memory. Unlike -strncpy(), this function doesn't pad @dest (so it's often faster). It -returns the size of the attempted result, strlen (src), so if +`strncpy()`, this function doesn't pad @dest (so it's often faster). It +returns the size of the attempted result, `strlen (src)`, so if @retval >= @dest_size, truncation occurred. -Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), -but if you really want to avoid screwups, g_strdup() is an even better +Caveat: `strlcpy()` is supposedly more secure than `strcpy()` or `strncpy()`, +but if you really want to avoid screwups, [func@GLib.strdup] is an even better idea. - + length of @src + filename="glib/gstrfuncs.c" + line="1445">length of @src destination buffer + filename="glib/gstrfuncs.c" + line="1426">destination buffer source buffer + filename="glib/gstrfuncs.c" + line="1427">source buffer length of @dest in bytes + filename="glib/gstrfuncs.c" + line="1428">length of @dest in bytes @@ -77848,251 +83445,258 @@ idea. deprecated="1" deprecated-version="2.2"> A case-insensitive string comparison, corresponding to the standard -strncasecmp() function on platforms which support it. It is similar -to g_strcasecmp() except it only compares the first @n characters of + filename="glib/gstrfuncs.c" + line="1940">A case-insensitive string comparison, corresponding to the standard +`strncasecmp()` function on platforms which support it. It is similar +to [func@GLib.strcasecmp] except it only compares the first @n characters of the strings. - The problem with g_strncasecmp() is that it does - the comparison by calling toupper()/tolower(). These functions - are locale-specific and operate on single bytes. However, it is - impossible to handle things correctly from an internationalization - standpoint by operating on bytes, since characters may be multibyte. - Thus g_strncasecmp() is broken if your string is guaranteed to be - ASCII, since it is locale-sensitive, and it's broken if your string - is localized, since it doesn't work on many encodings at all, - including UTF-8, EUC-JP, etc. - - There are therefore two replacement techniques: g_ascii_strncasecmp(), - which only works on ASCII and is not locale-sensitive, and - g_utf8_casefold() followed by strcmp() on the resulting strings, - which is good for case-insensitive sorting of UTF-8. - - - 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. + The problem with `g_strncasecmp()` is that it does + the comparison by calling `toupper()`/`tolower()`. These functions + are locale-specific and operate on single bytes. However, it is + impossible to handle things correctly from an internationalization + standpoint by operating on bytes, since characters may be multibyte. + Thus `g_strncasecmp()` is broken if your string is guaranteed to be + ASCII, since it is locale-sensitive, and it's broken if your string + is localized, since it doesn't work on many encodings at all, + including UTF-8, EUC-JP, etc. + + There are therefore two replacement techniques: [func@GLib.ascii_strncasecmp], + which only works on ASCII and is not locale-sensitive, and + [func@GLib.utf8_casefold] followed by `strcmp()` on the resulting strings, + which is good for case-insensitive sorting of UTF-8. + + + 0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2 a string + filename="glib/gstrfuncs.c" + line="1942">string to compare with @s2 a string to compare with @s1 + filename="glib/gstrfuncs.c" + line="1943">string to compare with @s1 the maximum number of characters to compare + filename="glib/gstrfuncs.c" + line="1944">the maximum number of characters to compare Duplicates the first @n bytes of a string, returning a newly-allocated + filename="glib/gstrfuncs.c" + line="395">Duplicates the first @n bytes of a string, returning a newly-allocated buffer @n + 1 bytes long which will always be nul-terminated. If @str is less than @n bytes long the buffer is padded with nuls. If @str is -%NULL it returns %NULL. The returned value should be freed when no longer -needed. +`NULL` it returns `NULL`. To copy a number of characters from a UTF-8 encoded string, -use g_utf8_strncpy() instead. - - +use [func@GLib.utf8_strncpy] instead. + + a newly-allocated buffer containing the first @n bytes - of @str, nul-terminated + filename="glib/gstrfuncs.c" + line="408">a newly-allocated buffer containing the first + @n bytes of @str - + the string to duplicate + filename="glib/gstrfuncs.c" + line="397">the string to duplicate the maximum number of bytes to copy from @str + filename="glib/gstrfuncs.c" + line="398">the maximum number of bytes to copy from @str Creates a new string @length bytes long filled with @fill_char. -The returned string should be freed when no longer needed. - + filename="glib/gstrfuncs.c" + line="429">Creates a new string @length bytes long filled with @fill_char. + a newly-allocated string filled the @fill_char + filename="glib/gstrfuncs.c" + line="436">a newly-allocated string filled with @fill_char the length of the new string + filename="glib/gstrfuncs.c" + line="431">the length of the new string the byte to fill the string with + filename="glib/gstrfuncs.c" + line="432">the byte to fill the string with Reverses all of the bytes in a string. For example, + filename="glib/gstrfuncs.c" + line="1669">Reverses all of the bytes in a string. For example, `g_strreverse ("abcdef")` will result in "fedcba". -Note that g_strreverse() doesn't work on UTF-8 strings +Note that `g_strreverse()` doesn't work on UTF-8 strings containing multibyte characters. For that purpose, use -g_utf8_strreverse(). - +[func@GLib.utf8_strreverse]. + the same pointer passed in as @string + filename="glib/gstrfuncs.c" + line="1680">the @string, reversed in place the string to reverse + filename="glib/gstrfuncs.c" + line="1671">the string to reverse Searches the string @haystack for the last occurrence -of the string @needle. - - + filename="glib/gstrfuncs.c" + line="2790">Searches the string @haystack for the last occurrence +of the string @needle. + +The fact that this function returns `gchar *` rather than `const gchar *` is +a historical artifact. + + a pointer to the found occurrence, or - %NULL if not found. + filename="glib/gstrfuncs.c" + line="2801">a pointer to the found occurrence, or + `NULL` if not found a nul-terminated string + filename="glib/gstrfuncs.c" + line="2792">a string to search in the nul-terminated string to search for + filename="glib/gstrfuncs.c" + line="2793">the string to search for Searches the string @haystack for the last occurrence + filename="glib/gstrfuncs.c" + line="2842">Searches the string @haystack for the last occurrence of the string @needle, limiting the length of the search -to @haystack_len. - - +to @haystack_len. + +The fact that this function returns `gchar *` rather than `const gchar *` is +a historical artifact. + + a pointer to the found occurrence, or - %NULL if not found. + filename="glib/gstrfuncs.c" + line="2856">a pointer to the found occurrence, or + `NULL` if not found a nul-terminated string + filename="glib/gstrfuncs.c" + line="2844">a string to search in the maximum length of @haystack in bytes. A length of -1 - can be used to mean "search the entire string", like g_strrstr(). + filename="glib/gstrfuncs.c" + line="2845">the maximum length of @haystack in bytes. A length of `-1` + can be used to mean "search the entire string", like [func@GLib.strrstr] the nul-terminated string to search for + filename="glib/gstrfuncs.c" + line="2847">the string to search for Returns a string describing the given signal, e.g. "Segmentation fault". -You should use this function in preference to strsignal(), because it + filename="glib/gstrfuncs.c" + line="1357">Returns a string describing the given signal, e.g. "Segmentation fault". +If the signal is unknown, it returns “unknown signal (<signum\>)”. + +You should use this function in preference to `strsignal()`, because it returns a string in UTF-8 encoding, and since not all platforms support -the strsignal() function. - +the `strsignal()` function. + a UTF-8 string describing the signal. If the signal is unknown, - it returns "unknown signal (<signum>)". + filename="glib/gstrfuncs.c" + line="1368">the string describing the signal the signal number. See the `signal` documentation + filename="glib/gstrfuncs.c" + line="1359">the signal number. See the `signal` documentation Splits a string into a maximum of @max_tokens pieces, using the given + filename="glib/gstrfuncs.c" + line="2362">Splits a string into a maximum of @max_tokens pieces, using the given @delimiter. If @max_tokens is reached, the remainder of @string is appended to the last token. -As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a -%NULL-terminated vector containing the six strings "", "a", "bc", "", "d" -and "". +As an example, the result of `g_strsplit (":a:bc::d:", ":", -1)` is an array +containing the six strings "", "a", "bc", "", "d" and "". As a special case, the result of splitting the empty string "" is an empty -vector, not a vector containing a single string. The reason for this -special case is that being able to represent an empty vector is typically +array, not an array containing a single string. The reason for this +special case is that being able to represent an empty array is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string -before calling g_strsplit(). - +before calling `g_strsplit()`. + a newly-allocated %NULL-terminated array of - strings. Use g_strfreev() to free it. + filename="glib/gstrfuncs.c" + line="2385">a newly-allocated array of strings, freed with + [func@GLib.strfreev] @@ -78100,57 +83704,56 @@ before calling g_strsplit(). a string to split + filename="glib/gstrfuncs.c" + line="2364">a string to split a string which specifies the places at which to split - the string. The delimiter is not included in any of the resulting - strings, unless @max_tokens is reached. + filename="glib/gstrfuncs.c" + line="2365">a string which specifies the places at which to split + the string. The delimiter is not included in any of the resulting + strings, unless @max_tokens is reached. the maximum number of pieces to split @string into. - If this is less than 1, the string is split completely. + filename="glib/gstrfuncs.c" + line="2368">the maximum number of pieces to split @string into + If this is less than 1, the string is split completely Splits @string into a number of tokens not containing any of the characters -in @delimiter. A token is the (possibly empty) longest string that does not + filename="glib/gstrfuncs.c" + line="2435">Splits @string into a number of tokens not containing any of the characters +in @delimiters. A token is the (possibly empty) longest string that does not contain any of the characters in @delimiters. If @max_tokens is reached, the remainder is appended to the last token. -For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a -%NULL-terminated vector containing the three strings "abc", "def", -and "ghi". +For example, the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is an +array containing the three strings "abc", "def", and "ghi". -The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated -vector containing the four strings "", "def", "ghi", and "". +The result of g_strsplit_set (":def/ghi:", ":/", -1) is an array containing +the four strings "", "def", "ghi", and "". As a special case, the result of splitting the empty string "" is an empty -vector, not a vector containing a single string. The reason for this -special case is that being able to represent an empty vector is typically +array, not an array containing a single string. The reason for this +special case is that being able to represent an empty array is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string -before calling g_strsplit_set(). +before calling `g_strsplit_set()`. Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. - + a newly-allocated %NULL-terminated array of - strings. Use g_strfreev() to free it. + filename="glib/gstrfuncs.c" + line="2464">a newly-allocated array of strings. Use + [func@GLib.strfreev] to free it. @@ -78158,59 +83761,64 @@ to delimit UTF-8 strings for anything but ASCII characters. The string to be tokenized + filename="glib/gstrfuncs.c" + line="2437">a string to split A nul-terminated string containing bytes that are used - to split the string (it can accept an empty string, which will result - in no string splitting). + filename="glib/gstrfuncs.c" + line="2438">a string containing characters that are used to split the + string. Can be empty, which will result in no string splitting The maximum number of tokens to split @string into. - If this is less than 1, the string is split completely + filename="glib/gstrfuncs.c" + line="2440">the maximum number of tokens to split @string into. + If this is less than 1, the string is split completely Searches the string @haystack for the first occurrence + filename="glib/gstrfuncs.c" + line="2728">Searches the string @haystack for the first occurrence of the string @needle, limiting the length of the search -to @haystack_len or a nul terminator byte (whichever is reached first). - - +to @haystack_len or a nul terminator byte (whichever is reached first). + +A length of `-1` can be used to mean “search the entire string”, like +`strstr()`. + +The fact that this function returns `gchar *` rather than `const gchar *` is +a historical artifact. + + a pointer to the found occurrence, or - %NULL if not found. + filename="glib/gstrfuncs.c" + line="2745">a pointer to the found occurrence, or + `NULL` if not found a nul-terminated string + filename="glib/gstrfuncs.c" + line="2730">a string to search in the maximum length of @haystack in bytes. A length of -1 - can be used to mean "search the entire string", like `strstr()`. + filename="glib/gstrfuncs.c" + line="2731">the maximum length of @haystack in bytes, or `-1` to + search it entirely the string to search for + filename="glib/gstrfuncs.c" + line="2733">the string to search for @@ -78219,44 +83827,46 @@ to @haystack_len or a nul terminator byte (whichever is reached first). c:identifier="g_strstrip" introspectable="0"> Removes leading and trailing whitespace from a string. -See g_strchomp() and g_strchug(). - + filename="glib/gstrfuncs.c" + line="245">Removes leading and trailing whitespace from a string. + +See [func@GLib.strchomp] and [func@GLib.strchug]. + a string to remove the leading and trailing whitespace from + filename="glib/gstrfuncs.c" + line="247">a string to remove the leading and trailing whitespace from Converts a string to a #gdouble value. -It calls the standard strtod() function to handle the conversion, but + filename="glib/gstrfuncs.c" + line="601">Converts a string to a floating point value. + +It calls the standard `strtod()` function to handle the conversion, but if the string is not completely converted it attempts the conversion -again with g_ascii_strtod(), and returns the best match. +again with [func@GLib.ascii_strtod], and returns the best match. This function should seldom be used. The normal situation when reading -numbers not for human consumption is to use g_ascii_strtod(). Only when +numbers not for human consumption is to use [func@GLib.ascii_strtod]. Only when you know that you must expect both locale formatted and C formatted numbers should you use this. Make sure that you don't pass strings such as comma separated lists of values, since the commas may be interpreted as a decimal point in some locales, causing unexpected results. - + the #gdouble value. + filename="glib/gstrfuncs.c" + line="620">the converted value the string to convert to a numeric value. + filename="glib/gstrfuncs.c" + line="603">the string to convert to a numeric value optional="1" allow-none="1"> if non-%NULL, it returns the - character after the last character used in the conversion. + filename="glib/gstrfuncs.c" + line="604">if non-`NULL`, it returns the + character after the last character used in the conversion @@ -78278,23 +83888,23 @@ point in some locales, causing unexpected results. deprecated="1" deprecated-version="2.2"> Converts a string to upper case. - This function is totally broken for the reasons - discussed in the g_strncasecmp() docs - use g_ascii_strup() - or g_utf8_strup() instead. - + filename="glib/gstrfuncs.c" + line="1638">Converts a string to upper case. + This function is totally broken for the reasons discussed + in the [func@GLib.strncasecmp] docs — use [func@GLib.ascii_strup] or + [func@GLib.utf8_strup] instead. + the string + filename="glib/gstrfuncs.c" + line="1644">the string the string to convert + filename="glib/gstrfuncs.c" + line="1640">the string to convert @@ -78303,85 +83913,96 @@ point in some locales, causing unexpected results. c:identifier="g_strv_contains" version="2.44"> Checks if @strv contains @str. @strv must not be %NULL. - + filename="glib/gstrfuncs.c" + line="3221">Checks if an array of strings contains the string @str according to +[func@GLib.str_equal]. @strv must not be `NULL`. + %TRUE if @str is an element of @strv, according to g_str_equal(). + filename="glib/gstrfuncs.c" + line="3229">true if @str is an element of @strv a %NULL-terminated array of strings - + filename="glib/gstrfuncs.c" + line="3223">an array of strings to search in + + + a string + filename="glib/gstrfuncs.c" + line="3224">the string to search for Checks if @strv1 and @strv2 contain exactly the same elements in exactly the -same order. Elements are compared using g_str_equal(). To match independently -of order, sort the arrays first (using g_qsort_with_data() or similar). + filename="glib/gstrfuncs.c" + line="3249">Checks if two arrays of strings contain exactly the same elements in +exactly the same order. -Two empty arrays are considered equal. Neither @strv1 not @strv2 may be -%NULL. - +Elements are compared using [func@GLib.str_equal]. To match independently +of order, sort the arrays first (using [func@GLib.qsort_with_data] +or similar). + +Two empty arrays are considered equal. Neither @strv1 nor @strv2 may be +`NULL`. + %TRUE if @strv1 and @strv2 are equal + filename="glib/gstrfuncs.c" + line="3264">true if @strv1 and @strv2 are equal a %NULL-terminated array of strings - + filename="glib/gstrfuncs.c" + line="3251">an array of strings to compare to @strv2 + + + another %NULL-terminated array of strings - + filename="glib/gstrfuncs.c" + line="3252">an array of strings to compare to @strv1 + + + - + Returns the length of the given %NULL-terminated -string array @str_array. @str_array must not be %NULL. - + filename="glib/gstrfuncs.c" + line="2950">Returns the length of an array of strings. @str_array must not be `NULL`. + length of @str_array. + filename="glib/gstrfuncs.c" + line="2956">length of @str_array a %NULL-terminated array of strings - + filename="glib/gstrfuncs.c" + line="2952">an array of strings + + + @@ -78390,45 +84011,49 @@ string array @str_array. @str_array must not be %NULL. version="2.16" introspectable="0"> Hook up a new test case at @testpath, similar to g_test_add_func(). -A fixture data structure with setup and teardown functions may be provided, -similar to g_test_create_case(). + filename="glib/gtestutils.h" + line="440">Hooks up a new test case at @testpath. + +This function is similar to [func@GLib.test_add_func]. + +A fixture data structure with setup and teardown functions +may be provided, similar to [func@GLib.test_create_case]. -g_test_add() is implemented as a macro, so that the fsetup(), ftest() and -fteardown() callbacks can expect a @Fixture pointer as their first argument -in a type safe manner. They otherwise have type #GTestFixtureFunc. - +`g_test_add()` is implemented as a macro, so that the @fsetup, +@ftest and @fteardown callbacks can expect a @Fixture pointer +as their first argument in a type safe manner. They otherwise +have type `GTestFixtureFunc`. + The test path for a new test case. + filename="glib/gtestutils.h" + line="442">the test path for a new test case The type of a fixture data structure. + filename="glib/gtestutils.h" + line="443">the type of a fixture data structure Data argument for the test functions. + filename="glib/gtestutils.h" + line="444">data argument for the test functions The function to set up the fixture data. + filename="glib/gtestutils.h" + line="445">the function to set up the fixture data The actual test function. + filename="glib/gtestutils.h" + line="446">the actual test function The function to tear down the fixture data. + filename="glib/gtestutils.h" + line="447">the function to tear down the fixture data @@ -78436,29 +84061,31 @@ in a type safe manner. They otherwise have type #GTestFixtureFunc. c:identifier="g_test_add_data_func" version="2.16"> Create a new test case, similar to g_test_create_case(). However -the test is assumed to use no fixture, and test suites are automatically -created on the fly and added to the root fixture, based on the -slash-separated portions of @testpath. The @test_data argument -will be passed as first argument to @test_func. + filename="glib/gtestutils.c" + line="2832">Creates a new test case. + +This function is similar to [func@GLib.test_create_case]. +However the test is assumed to use no fixture, and test suites are +automatically created on the fly and added to the root fixture, +based on the /-separated portions of @testpath. The @test_data +argument will be passed as first argument to @test_func. If @testpath includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly -required via the `-p` command-line option or g_test_trap_subprocess(). +required via the `-p` command-line option or [func@GLib.test_trap_subprocess]. No component of @testpath may start with a dot (`.`) if the -%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to -do so even if it isn’t. - +[const@GLib.TEST_OPTION_ISOLATE_DIRS] option is being used; +and it is recommended to do so even if it isn’t. + /-separated test case path name for the test. + filename="glib/gtestutils.c" + line="2834">a /-separated name for the test nullable="1" allow-none="1"> Test data argument for the test function. + filename="glib/gtestutils.c" + line="2835">data for the @test_func The test function to invoke for this test. + filename="glib/gtestutils.c" + line="2836">the test function to invoke for this test @@ -78482,18 +84109,20 @@ do so even if it isn’t. c:identifier="g_test_add_data_func_full" version="2.34"> Create a new test case, as with g_test_add_data_func(), but freeing -@test_data after the test run is complete. - + filename="glib/gtestutils.c" + line="2868">Creates a new test case. + +In constract to [func@GLib.test_add_data_func], this function +is freeing @test_data after the test run is complete. + /-separated test case path name for the test. + filename="glib/gtestutils.c" + line="2870">a /-separated name for the test nullable="1" allow-none="1"> Test data argument for the test function. + filename="glib/gtestutils.c" + line="2871">data for @test_func scope="notified" destroy="3"> The test function to invoke for this test. + filename="glib/gtestutils.c" + line="2872">the test function to invoke for this test #GDestroyNotify for @test_data. + filename="glib/gtestutils.c" + line="2873">#GDestroyNotify for @test_data @@ -78528,34 +84157,36 @@ do so even if it isn’t. c:identifier="g_test_add_func" version="2.16"> Create a new test case, similar to g_test_create_case(). However -the test is assumed to use no fixture, and test suites are automatically -created on the fly and added to the root fixture, based on the -slash-separated portions of @testpath. + filename="glib/gtestutils.c" + line="2790">Creates a new test case. + +This function is similar to [func@GLib.test_create_case]. +However the test is assumed to use no fixture, and test suites are +automatically created on the fly and added to the root fixture, +based on the /-separated portions of @testpath. If @testpath includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly -required via the `-p` command-line option or g_test_trap_subprocess(). +required via the `-p` command-line option or [func@GLib.test_trap_subprocess]. No component of @testpath may start with a dot (`.`) if the -%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to -do so even if it isn’t. - +[const@GLib.TEST_OPTION_ISOLATE_DIRS] option is being used; and +it is recommended to do so even if it isn’t. + /-separated test case path name for the test. + filename="glib/gtestutils.c" + line="2792">a /-separated name for the test The test function to invoke for this test. + filename="glib/gtestutils.c" + line="2793">the test function to invoke for this test @@ -78563,7 +84194,7 @@ do so even if it isn’t. - + @@ -78596,21 +84227,21 @@ do so even if it isn’t. version="2.34" introspectable="0"> Asserts that all messages previously indicated via -g_test_expect_message() have been seen and suppressed. + filename="glib/gmessages.c" + line="3225">Asserts that all messages previously indicated via +[func@GLib.test_expect_message] have been seen and suppressed. -This API may only be used with the old logging API (g_log() without -%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging -API. See [Testing for Messages][testing-for-messages]. +This API may only be used with the old logging API ([func@GLib.log] without +`G_LOG_USE_STRUCTURED` defined). It will not work with the structured logging +API. See [Testing for Messages](logging.html#testing-for-messages). -If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly -expected via g_test_expect_message() then they will be ignored. - +If messages at [flags@GLib.LogLevelFlags.LEVEL_DEBUG] are emitted, but not explicitly +expected via [func@GLib.test_expect_message] then they will be ignored. + - + @@ -78631,28 +84262,27 @@ expected via g_test_expect_message() then they will be ignored. This function adds a message to test reports that -associates a bug URI with a test case. + filename="glib/gtestutils.c" + line="2214">Adds a message to test reports that associates a bug URI with a test case. -Bug URIs are constructed from a base URI set with g_test_bug_base() -and @bug_uri_snippet. If g_test_bug_base() has not been called, it is +Bug URIs are constructed from a base URI set with [func@GLib.test_bug_base] +and @bug_uri_snippet. If [func@GLib.test_bug_base] has not been called, it is assumed to be the empty string, so a full URI can be provided to -g_test_bug() instead. +[func@GLib.test_bug] instead. -Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it -is already a valid URI. - -See also: g_test_summary() - +See also [func@GLib.test_summary]. + +Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet +if it is already a valid URI. + Bug specific bug tracker URI or URI portion. + filename="glib/gtestutils.c" + line="2216">Bug specific bug tracker URI or URI portion. @@ -78661,11 +84291,11 @@ See also: g_test_summary() c:identifier="g_test_bug_base" version="2.16"> Specify the base URI for bug reports. + filename="glib/gtestutils.c" + line="2186">Specifies the base URI for bug reports. The base URI is used to construct bug report messages for -g_test_message() when g_test_bug() is called. +[func@GLib.test_message] when [func@GLib.test_bug] is called. Calling this function outside of a test case sets the default base URI for all test cases. Calling it from within a test case changes the base URI for the scope of the test @@ -78674,17 +84304,17 @@ Bug URIs are constructed by appending a bug specific URI portion to @uri_pattern, or by replacing the special string `%s` within @uri_pattern if that is present. -If g_test_bug_base() is not called, bug URIs are formed solely -from the value provided by g_test_bug(). - +If [func@GLib.test_bug_base] is not called, bug URIs are formed +solely from the value provided by [func@GLib.test_bug]. + the base pattern for bug URIs + filename="glib/gtestutils.c" + line="2188">the base pattern for bug URIs @@ -78694,53 +84324,53 @@ from the value provided by g_test_bug(). version="2.38" introspectable="0"> Creates the pathname to a data file that is required for a test. + filename="glib/gtestutils.c" + line="4628">Creates the pathname to a data file that is required for a test. -This function is conceptually similar to g_build_filename() except -that the first argument has been replaced with a #GTestFileType -argument. +This function is conceptually similar to [func@GLib.build_filename] +except that the first argument has been replaced with a +[enum@GLib.TestFileType] argument. The data file should either have been distributed with the module -containing the test (%G_TEST_DIST) or built as part of the build -system of that module (%G_TEST_BUILT). +containing the test ([enum@GLib.TestFileType.dist] or built as part of the +buildcsystem of that module ([enum@GLib.TestFileType.built]). In order for this function to work in srcdir != builddir situations, -the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to -have been defined. As of 2.38, this is done by the glib.mk -included in GLib. Please ensure that your copy is up to date before +the `G_TEST_SRCDIR` and `G_TEST_BUILDDIR` environment variables need +to have been defined. As of 2.38, this is done by the glib.mk that is +included in GLib. Please ensure that your copy is up to date before using this function. In case neither variable is set, this function will fall back to -using the dirname portion of argv[0], possibly removing ".libs". +using the dirname portion of `argv[0]`, possibly removing ".libs". This allows for casual running of tests directly from the commandline in the srcdir == builddir case and should also support running of installed tests, assuming the data files have been installed in the same relative path as the test binary. - + the path of the file, to be freed using g_free() + filename="glib/gtestutils.c" + line="4657">the path of the file, to be freed using [func@GLib.free] the type of file (built vs. distributed) + filename="glib/gtestutils.c" + line="4630">the type of file (built vs. distributed) the first segment of the pathname + filename="glib/gtestutils.c" + line="4631">the first segment of the pathname %NULL-terminated additional path segments + filename="glib/gtestutils.c" + line="4632">`NULL`-terminated additional path segments @@ -78750,42 +84380,42 @@ same relative path as the test binary. version="2.16" introspectable="0"> Create a new #GTestCase, named @test_name. + filename="glib/gtestutils.c" + line="2417">Creates a new [struct@GLib.TestCase]. -This API is fairly low level, and calling g_test_add() or g_test_add_func() -is preferable. +This API is fairly low level, and calling [func@GLib.test_add] or +[func@GLib.test_add_func] is preferable. When this test is executed, a fixture structure of size @data_size -will be automatically allocated and filled with zeros. Then @data_setup is -called to initialize the fixture. After fixture setup, the actual test +will be automatically allocated and filled with zeros. Then @data_setup +is called to initialize the fixture. After fixture setup, the actual test function @data_test is called. Once the test run completes, the -fixture structure is torn down by calling @data_teardown and -after that the memory is automatically released by the test framework. +fixture structure is torn down by calling @data_teardown and after +that the memory is automatically released by the test framework. Splitting up a test run into fixture setup, test function and fixture teardown is most useful if the same fixture type is used for -multiple tests. In this cases, g_test_create_case() will be -called with the same type of fixture (the @data_size argument), but varying -@test_name and @data_test arguments. - +multiple tests. In this cases, [func@GLib.test_create_case] will be +called with the same type of fixture (the @data_size argument), but +varying @test_name and @data_test arguments. + a newly allocated #GTestCase. + filename="glib/gtestutils.c" + line="2444">a newly allocated test case the name for the test case + filename="glib/gtestutils.c" + line="2419">the name for the test case the size of the fixture data structure + filename="glib/gtestutils.c" + line="2420">the size of the fixture data structure test data argument for the test functions + filename="glib/gtestutils.c" + line="2421">test data argument for the test functions the function to set up the fixture data + filename="glib/gtestutils.c" + line="2422">the function to set up the fixture data the actual test function + filename="glib/gtestutils.c" + line="2423">the actual test function the function to teardown the fixture data + filename="glib/gtestutils.c" + line="2424">the function to teardown the fixture data @@ -78824,20 +84454,20 @@ called with the same type of fixture (the @data_size argument), but varying version="2.16" introspectable="0"> Create a new test suite with the name @suite_name. - + filename="glib/gtestutils.c" + line="2932">Creates a new test suite with the name @suite_name. + A newly allocated #GTestSuite instance. + filename="glib/gtestutils.c" + line="2938">a newly allocated test suite a name for the suite + filename="glib/gtestutils.c" + line="2934">a name for the suite @@ -78846,13 +84476,13 @@ called with the same type of fixture (the @data_size argument), but varying c:identifier="g_test_disable_crash_reporting" version="2.78"> Attempt to disable system crash reporting infrastructure. + filename="glib/gtestutils.c" + line="1153">Attempts to disable system crash reporting infrastructure. This function should be called before exercising code paths that are expected or intended to crash, to avoid wasting resources in system-wide crash collection infrastructure such as systemd-coredump or abrt. - + @@ -78861,42 +84491,43 @@ crash collection infrastructure such as systemd-coredump or abrt. c:identifier="g_test_expect_message" version="2.34"> Indicates that a message with the given @log_domain and @log_level, -with text matching @pattern, is expected to be logged. When this -message is logged, it will not be printed, and the test case will + filename="glib/gmessages.c" + line="3139">Indicates that a message with the given @log_domain and @log_level, +with text matching @pattern, is expected to be logged. + +When this message is logged, it will not be printed, and the test case will not abort. -This API may only be used with the old logging API (g_log() without -%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging -API. See [Testing for Messages][testing-for-messages]. +This API may only be used with the old logging API ([func@GLib.log] without +`G_LOG_USE_STRUCTURED` defined). It will not work with the structured logging +API. See [Testing for Messages](logging.html#testing-for-messages). -Use g_test_assert_expected_messages() to assert that all +Use [func@GLib.test_assert_expected_messages] to assert that all previously-expected messages have been seen and suppressed. You can call this multiple times in a row, if multiple messages are expected as a result of a single call. (The messages must appear in -the same order as the calls to g_test_expect_message().) +the same order as the calls to [func@GLib.test_expect_message].) For example: -|[<!-- language="C" --> - // g_main_context_push_thread_default() should fail if the - // context is already owned by another thread. - g_test_expect_message (G_LOG_DOMAIN, - G_LOG_LEVEL_CRITICAL, - "assertion*acquired_context*failed"); - g_main_context_push_thread_default (bad_context); - g_test_assert_expected_messages (); -]| - -Note that you cannot use this to test g_error() messages, since -g_error() intentionally never returns even if the program doesn't -abort; use g_test_trap_subprocess() in this case. - -If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly -expected via g_test_expect_message() then they will be ignored. - +```c +// g_main_context_push_thread_default() should fail if the +// context is already owned by another thread. +g_test_expect_message (G_LOG_DOMAIN, + G_LOG_LEVEL_CRITICAL, + "assertion*acquired_context*failed"); +g_main_context_push_thread_default (bad_context); +g_test_assert_expected_messages (); +``` + +Note that you cannot use this to test [func@GLib.error] messages, since +[func@GLib.error] intentionally never returns even if the program doesn’t +abort; use [func@GLib.test_trap_subprocess] in this case. + +If messages at [flags@GLib.LogLevelFlags.LEVEL_DEBUG] are emitted, but not explicitly +expected via [func@GLib.test_expect_message] then they will be ignored. + @@ -78906,30 +84537,31 @@ expected via g_test_expect_message() then they will be ignored. nullable="1" allow-none="1"> the log domain of the message + filename="glib/gmessages.c" + line="3141">the log domain of the message the log level of the message + filename="glib/gmessages.c" + line="3142">the log level of the message a glob-style [pattern][glib-Glob-style-pattern-matching] + filename="glib/gmessages.c" + line="3143">a glob-style pattern (see [type@GLib.PatternSpec]) Indicates that a test failed. This function can be called -multiple times from the same test. You can use this function -if your test failed in a recoverable way. + filename="glib/gtestutils.c" + line="2568">Indicates that a test failed. + +This function can be called multiple times from the same test. +You can use this function if your test failed in a recoverable way. Do not use this function if the failure of a test could cause other tests to malfunction. @@ -78941,12 +84573,12 @@ the test. If not called from inside a test, this function does nothing. -Note that unlike g_test_skip() and g_test_incomplete(), this -function does not log a message alongside the test failure. +Note that unlike [func@GLib.test_skip] and [func@GLib.test_incomplete], +this function does not log a message alongside the test failure. If details of the test failure are available, either log them with -g_test_message() before g_test_fail(), or use g_test_fail_printf() -instead. - +[func@GLib.test_message] before [func@GLib.test_fail], or use +[func@GLib.test_fail_printf] instead. + @@ -78956,69 +84588,73 @@ instead. version="2.70" introspectable="0"> Equivalent to g_test_fail(), but also record a message like -g_test_skip_printf(). - + filename="glib/gtestutils.c" + line="2601">Indicates that a test failed and records a message. + +Also see [func@GLib.test_fail]. + +The message is formatted as if by [func@GLib.strdup_printf]. + the format string + filename="glib/gtestutils.c" + line="2603">the format string printf-like arguments to @format + filename="glib/gtestutils.c" + line="2604">printf-like arguments to @format Returns whether a test has already failed. This will -be the case when g_test_fail(), g_test_incomplete() -or g_test_skip() have been called, but also if an -assertion has failed. + filename="glib/gtestutils.c" + line="2727">Returns whether a test has already failed. + +This will be the case when [func@GLib.test_fail], +[func@GLib.test_incomplete] or [func@GLib.test_skip] have +been called, but also if an assertion has failed. This can be useful to return early from a test if continuing after a failed assertion might be harmful. The return value of this function is only meaningful if it is called from inside a test function. - + %TRUE if the test has failed + filename="glib/gtestutils.c" + line="2742">true if the test has failed Gets the pathname of the directory containing test files of the type + filename="glib/gtestutils.c" + line="4703">Gets the pathname of the directory containing test files of the type specified by @file_type. -This is approximately the same as calling g_test_build_filename("."), +This is approximately the same as calling `g_test_build_filename(".")`, but you don't need to free the return value. - + the path of the directory, owned by GLib + filename="glib/gtestutils.c" + line="4713">the path of the directory, owned by GLib the type of file (built vs. distributed) + filename="glib/gtestutils.c" + line="4705">the type of file (built vs. distributed) @@ -79028,12 +84664,12 @@ but you don't need to free the return value. version="2.38" introspectable="0"> Gets the pathname to a data file that is required for a test. + filename="glib/gtestutils.c" + line="4730">Gets the pathname to a data file that is required for a test. -This is the same as g_test_build_filename() with two differences. +This is the same as [func@GLib.test_build_filename] with two differences. The first difference is that you must only use this function from within -a testcase function. The second difference is that you need not free +a testcase function. The second difference is that you need not free the return value — it will be automatically freed when the testcase finishes running. @@ -79041,30 +84677,30 @@ It is safe to use this function from a thread inside of a testcase but you must ensure that all such uses occur before the main testcase function returns (ie: it is best to ensure that all threads have been joined). - + the path, automatically freed at the end of the testcase + filename="glib/gtestutils.c" + line="4749">the path, automatically freed at the end of the testcase the type of file (built vs. distributed) + filename="glib/gtestutils.c" + line="4732">the type of file (built vs. distributed) the first segment of the pathname + filename="glib/gtestutils.c" + line="4733">the first segment of the pathname %NULL-terminated additional path segments + filename="glib/gtestutils.c" + line="4734">`NULL`-terminated additional path segments @@ -79073,20 +84709,20 @@ joined). c:identifier="g_test_get_path" version="2.68"> Gets the test path for the test currently being run. + filename="glib/gtestutils.c" + line="4778">Gets the test path for the test currently being run. -In essence, it will be the same string passed as the first argument to -e.g. g_test_add() when the test was added. +In essence, it will be the same string passed as the first argument +to e.g. [func@GLib.test_add] when the test was added. This function returns a valid string only within a test function. Note that this is a test path, not a file system path. - + the test path for the test currently being run + filename="glib/gtestutils.c" + line="4790">the test path for the test currently being run @@ -79095,13 +84731,13 @@ Note that this is a test path, not a file system path. version="2.16" introspectable="0"> Get the toplevel test suite for the test path API. - + filename="glib/gtestutils.c" + line="2300">Gets the toplevel test suite for the test path API. + the toplevel #GTestSuite + filename="glib/gtestutils.c" + line="2305">the toplevel test suite @@ -79109,10 +84745,11 @@ Note that this is a test path, not a file system path. c:identifier="g_test_incomplete" version="2.38"> Indicates that a test failed because of some incomplete -functionality. This function can be called multiple times -from the same test. + filename="glib/gtestutils.c" + line="2627">Indicates that a test failed because of some incomplete +functionality. + +This function can be called multiple times from the same test. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can @@ -79120,7 +84757,7 @@ produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. - + @@ -79130,8 +84767,8 @@ If not called from inside a test, this function does nothing. nullable="1" allow-none="1"> explanation + filename="glib/gtestutils.c" + line="2629">explanation @@ -79141,24 +84778,27 @@ If not called from inside a test, this function does nothing. version="2.70" introspectable="0"> Equivalent to g_test_incomplete(), but the explanation is formatted -as if by g_strdup_printf(). - + filename="glib/gtestutils.c" + line="2653">Indicates that a test failed because of some incomplete +functionality. + +Equivalent to [func@GLib.test_incomplete], but the explanation +is formatted as if by [func@GLib.strdup_printf]. + the format string + filename="glib/gtestutils.c" + line="2655">the format string printf-like arguments to @format + filename="glib/gtestutils.c" + line="2656">printf-like arguments to @format @@ -79168,14 +84808,15 @@ as if by g_strdup_printf(). version="2.16" introspectable="0"> Initialize the GLib testing framework, e.g. by seeding the -test random number generator, the name for g_get_prgname() -and parsing test related command line args. + filename="glib/gtestutils.c" + line="1627">Initializes the GLib testing framework. + +This includes seeding the test random number generator, +setting the program name, and parsing test-related commandline args. This should be called before calling any other `g_test_*()` functions. -So far, the following arguments are understood: +The following arguments are understood: - `-l`: List test cases available in a test executable. - `--seed=SEED`: Provide a random seed to reproduce test @@ -79186,59 +84827,62 @@ So far, the following arguments are understood: - `-s PATH`: Skip all tests matching the given path. This can also be used to force a test to run that would otherwise be skipped (ie, a test whose name contains "/subprocess"). -- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: +- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according + to these test modes: `perf`: Performance tests, may take long and report results (off by default). - `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage - (off by default). + `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize + coverage (off by default). `quick`: Quick tests, should run really quickly and give good coverage (the default). `undefined`: Tests for undefined behaviour, may provoke programming errors - under g_test_trap_subprocess() or g_test_expect_message() to check - that appropriate assertions or warnings are given (the default). + under [func@GLib.test_trap_subprocess] or [func@GLib.test_expect_message] + to check that appropriate assertions or warnings are given (the default). - `no-undefined`: Avoid tests for undefined behaviour + `no-undefined`: Avoid tests for undefined behaviour. - `--debug-log`: Debug test logging output. -Options which can be passed to @... are: +Any parsed arguments are removed from @argv, and @argc is adjust accordingly. + +The following options are supported: - - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname(). - - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each - unit test and uses g_set_user_dirs() to set XDG directories to point into - that temporary directory for the duration of the unit test. See the - documentation for %G_TEST_OPTION_ISOLATE_DIRS. +- `G_TEST_OPTION_NO_PRGNAME`: Causes g_test_init() to not call + [func@GLib.set_prgname]. Since. 2.84 +- `G_TEST_OPTION_ISOLATE_DIRS`: Creates a unique temporary directory for each + unit test and sets XDG directories to point there for the duration of the unit + test. See [const@GLib.TEST_OPTION_ISOLATE_DIRS]. +- `G_TEST_OPTION_NONFATAL_ASSERTIONS`: This has the same effect as + [func@GLib.test_set_nonfatal_assertions]. Since 2.84 -Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, -g_test_init() will print an error and exit. This is to prevent no-op tests -from being executed, as g_assert() is commonly (erroneously) used in unit -tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your -tests are compiled without `G_DISABLE_ASSERT` defined. - +Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, `g_test_init()` +will print an error and exit. This is to prevent no-op tests from being executed, +as [func@GLib.assert] is commonly (erroneously) used in unit tests, and is a no-op +when compiled with `G_DISABLE_ASSERT`. Ensure your tests are compiled without +`G_DISABLE_ASSERT` defined. + Address of the @argc parameter of the main() function. - Changed if any arguments were handled. + filename="glib/gtestutils.c" + line="1629">address of the @argc parameter of `main()` Address of the @argv parameter of main(). - Any parameters understood by g_test_init() stripped before return. + filename="glib/gtestutils.c" + line="1630">address of the @argv parameter of `main()` %NULL-terminated list of special options, documented below. + filename="glib/gtestutils.c" + line="1631">`NULL`-terminated list of special options @@ -79248,17 +84892,17 @@ tests are compiled without `G_DISABLE_ASSERT` defined. version="2.36" introspectable="0"> Returns %TRUE if g_test_init() has been called. - + filename="glib/gtestutils.c" + line="71">Returns true if [func@GLib.test_init] has been called. + Installs a non-error fatal log handler which can be + filename="glib/gmessages.c" + line="814">Installs a non-error fatal log handler which can be used to decide whether log messages which are counted as fatal abort the program. @@ -79275,19 +84919,19 @@ function which needs the special behavior. This handler has no effect on g_error messages. This handler also has no effect on structured log messages (using -g_log_structured() or g_log_structured_array()). To change the fatal +[func@GLib.log_structured] or [func@GLib.log_structured_array]). To change the fatal behaviour for specific log messages, programs must install a custom log -writer function using g_log_set_writer_func().See -[Using Structured Logging][using-structured-logging]. - +writer function using [func@GLib.log_set_writer_func].See +[Using Structured Logging](logging.html#using-structured-logging). + the log handler function. + filename="glib/gmessages.c" + line="816">the log handler function. data passed to the log handler. + filename="glib/gmessages.c" + line="817">data passed to the log handler. - + @@ -79317,33 +84961,34 @@ writer function using g_log_set_writer_func().See version="2.16" introspectable="0"> Report the result of a performance or measurement test. + filename="glib/gtestutils.c" + line="2130">Reports the result of a performance or measurement test. + The test should generally strive to maximize the reported quantities (larger values are better than smaller ones), this and @maximized_quantity can determine sorting order for test result reports. - + the reported value + filename="glib/gtestutils.c" + line="2132">the reported value the format string of the report message + filename="glib/gtestutils.c" + line="2133">the format string of the report message arguments to pass to the printf() function + filename="glib/gtestutils.c" + line="2134">printf-like arguments to @format @@ -79353,23 +84998,23 @@ order for test result reports. version="2.16" introspectable="0"> Add a message to the test report. - + filename="glib/gtestutils.c" + line="2162">Adds a message to the test report. + the format string + filename="glib/gtestutils.c" + line="2164">the format string printf-like arguments to @format + filename="glib/gtestutils.c" + line="2165">printf-like arguments to @format @@ -79379,33 +85024,34 @@ order for test result reports. version="2.16" introspectable="0"> Report the result of a performance or measurement test. + filename="glib/gtestutils.c" + line="2098">Reports the result of a performance or measurement test. + The test should generally strive to minimize the reported quantities (smaller values are better than larger ones), this and @minimized_quantity can determine sorting order for test result reports. - + the reported value + filename="glib/gtestutils.c" + line="2100">the reported value the format string of the report message + filename="glib/gtestutils.c" + line="2101">the format string of the report message arguments to pass to the printf() function + filename="glib/gtestutils.c" + line="2102">printf-like arguments to @format @@ -79414,34 +85060,35 @@ order for test result reports. c:identifier="g_test_perf" introspectable="0"> Returns %TRUE if tests are run in performance mode. + filename="glib/gtestutils.c" + line="123">Returns true if tests are run in performance mode. By default, tests are run in quick mode. In tests that use -g_test_init(), the option `-m perf` enables performance tests, while +[func@GLib.test_init], the option `-m perf` enables performance tests, while `-m quick` disables them. - + This function enqueus a callback @destroy_func to be executed -during the next test case teardown phase. This is most useful -to auto destruct allocated test resources at the end of a test run. -Resources are released in reverse queue order, that means enqueueing -callback A before callback B will cause B() to be called before -A() during teardown. - + filename="glib/gtestutils.c" + line="3011">Enqueues a callback @destroy_func to be executed during the next test case +teardown phase. + +This is most useful to auto destroy allocated test resources at the end +of a test run. Resources are released in reverse queue order, that means +enqueueing callback `A` before callback `B` will cause `B()` to be called +before `A()` during teardown. + Destroy callback for teardown phase. + filename="glib/gtestutils.c" + line="3013">destroy callback for teardown phase nullable="1" allow-none="1"> Destroy callback data. + filename="glib/gtestutils.c" + line="3014">destroy callback data @@ -79459,11 +85106,13 @@ A() during teardown. c:identifier="g_test_queue_free" version="2.16"> Enqueue a pointer to be released with g_free() during the next -teardown phase. This is equivalent to calling g_test_queue_destroy() -with a destroy callback of g_free(). - + filename="glib/gtestutils.c" + line="2992">Enqueues a pointer to be released with [func@GLib.free] +during the next teardown phase. + +This is equivalent to calling [func@GLib.test_queue_destroy] +with a destroy callback of [func@GLib.free]. + @@ -79473,8 +85122,8 @@ with a destroy callback of g_free(). nullable="1" allow-none="1"> the pointer to be stored. + filename="glib/gtestutils.c" + line="2994">the pointer to be stored @@ -79484,16 +85133,18 @@ with a destroy callback of g_free(). version="2.16" introspectable="0"> Enqueue an object to be released with g_object_unref() during -the next teardown phase. This is equivalent to calling -g_test_queue_destroy() with a destroy callback of g_object_unref(). - + filename="glib/gtestutils.c" + line="181">Enqueue an object to be released with g_object_unref() during +the next teardown phase. + +This is equivalent to calling [func@GLib.test_queue_destroy] +with a destroy callback of g_object_unref(). + the object to unref + filename="glib/gtestutils.c" + line="183">the object to unref @@ -79501,49 +85152,53 @@ g_test_queue_destroy() with a destroy callback of g_object_unref(). c:identifier="g_test_quick" introspectable="0"> Returns %TRUE if tests are run in quick mode. -Exactly one of g_test_quick() and g_test_slow() is active in any run; -there is no "medium speed". + filename="glib/gtestutils.c" + line="81">Returns true if tests are run in quick mode. + +Tests are always run in slow mode or in fast mode; there is no "medium speed". By default, tests are run in quick mode. In tests that use -g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` +[func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. - + Returns %TRUE if tests are run in quiet mode. -In tests that use g_test_init(), the option `-q` or `--quiet` enables + filename="glib/gtestutils.c" + line="168">Returns true if tests are run in quiet mode. + +In tests that use [func@GLib.test_init], the option `-q` or `--quiet` enables this, while `--verbose` disables it. -The default is neither g_test_verbose() nor g_test_quiet(). - + +The default is neither verbose nor quiet. + Get a reproducible random bit (0 or 1), see g_test_rand_int() -for details on test case random numbers. - + filename="glib/gtestutils.c" + line="297">Get a reproducible random bit (0 or 1). + +See [func@GLib.test_rand_int] for details on test case random numbers. + Get a reproducible random floating point number, -see g_test_rand_int() for details on test case random numbers. - + filename="glib/gtestutils.c" + line="1998">Gets a reproducible random floating point number. + +See [func@GLib.test_rand_int] for details on test case random numbers. + a random number from the seeded random number generator. + filename="glib/gtestutils.c" + line="2005">a random number from the seeded random number generator @@ -79551,27 +85206,28 @@ see g_test_rand_int() for details on test case random numbers. c:identifier="g_test_rand_double_range" version="2.16"> Get a reproducible random floating pointer number out of a specified range, -see g_test_rand_int() for details on test case random numbers. - + filename="glib/gtestutils.c" + line="2021">Gets a reproducible random floating point number out of a specified range. + +See [func@GLib.test_rand_int] for details on test case random numbers. + a number with @range_start <= number < @range_end. + filename="glib/gtestutils.c" + line="2030">a number with @range_start <= number < @range_end the minimum value returned by this function + filename="glib/gtestutils.c" + line="2023">the minimum value returned by this function the minimum value not returned by this function + filename="glib/gtestutils.c" + line="2024">the minimum value not returned by this function @@ -79580,8 +85236,8 @@ see g_test_rand_int() for details on test case random numbers. c:identifier="g_test_rand_int" version="2.16"> Get a reproducible random integer number. + filename="glib/gtestutils.c" + line="1943">Gets a reproducible random integer number. The random numbers generated by the g_test_rand_*() family of functions change with every new test program start, unless the --seed option is @@ -79590,11 +85246,11 @@ given when starting test programs. For individual test cases however, the random number generator is reseeded, to avoid dependencies between tests and to make --seed effective for all test cases. - + a random number from the seeded random number generator. + filename="glib/gtestutils.c" + line="1956">a random number from the seeded random number generator @@ -79602,40 +85258,43 @@ effective for all test cases. c:identifier="g_test_rand_int_range" version="2.16"> Get a reproducible random integer number out of a specified range, -see g_test_rand_int() for details on test case random numbers. - + filename="glib/gtestutils.c" + line="1972">Gets a reproducible random integer number out of a specified range. + +See [func@GLib.test_rand_int] for details on test case random numbers. + a number with @begin <= number < @end. + filename="glib/gtestutils.c" + line="1981">a number with @begin <= number < @end the minimum value returned by this function + filename="glib/gtestutils.c" + line="1974">the minimum value returned by this function the smallest value not to be returned by this function + filename="glib/gtestutils.c" + line="1975">the smallest value not to be returned by this function Runs all tests under the toplevel suite which can be retrieved -with g_test_get_root(). Similar to g_test_run_suite(), the test -cases to be run are filtered according to test path arguments -(`-p testpath` and `-s testpath`) as parsed by g_test_init(). -g_test_run_suite() or g_test_run() may only be called once in a -program. + filename="glib/gtestutils.c" + line="2322">Runs all tests under the toplevel suite. + +The toplevel suite can be retrieved with [func@GLib.test_get_root]. + +Similar to [func@GLib.test_run_suite], the test cases to be run are +filtered according to test path arguments (`-p testpath` and `-s testpath`) +as parsed by [func@GLib.test_init]. [func@GLib.test_run_suite] or +[func@GLib.test_run] may only be called once in a program. In general, the tests and sub-suites within each suite are run in the order in which they are defined. However, note that prior to @@ -79643,7 +85302,7 @@ GLib 2.36, there was a bug in the `g_test_add_*` functions which caused them to create multiple suites with the same name, meaning that if you created tests "/foo/simple", "/bar/simple", and "/foo/using-bar" in that order, they would get -run in that order (since g_test_run() would run the first "/foo" +run in that order (since [func@GLib.test_run] would run the first "/foo" suite, then the "/bar" suite, then the second "/foo" suite). As of 2.36, this bug is fixed, and adding the tests in that order would result in a running order of "/foo/simple", "/foo/using-bar", @@ -79657,18 +85316,17 @@ desired running order. Eg, "/simple/foo", "/simple/bar", However, you should never make the actual result of a test depend on the order that tests are run in. If you need to ensure that some particular code runs before or after a given test case, use -g_test_add(), which lets you specify setup and teardown functions. +[func@GLib.test_add], which lets you specify setup and teardown functions. If all tests are skipped or marked as incomplete (expected failures), this function will return 0 if producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. - + 0 on success, 1 on failure (assuming it returns at all), - 0 or 77 if all tests were skipped with g_test_skip() and/or - g_test_incomplete() + filename="glib/gtestutils.c" + line="2360">0 on success, 1 on failure (assuming it returns at all), + 0 or 77 if all tests were skipped or marked as incomplete @@ -79676,27 +85334,28 @@ as "skip test" by Automake) otherwise. c:identifier="g_test_run_suite" version="2.16"> Execute the tests within @suite and all nested #GTestSuites. + filename="glib/gtestutils.c" + line="3271">Executes the tests within @suite and all nested test suites. + The test suites to be executed are filtered according to test path arguments (`-p testpath` and `-s testpath`) as parsed by -g_test_init(). See the g_test_run() documentation for more -information on the order that tests are run in. +[func@GLib.test_init]. See the [func@GLib.test_run] documentation +for more information on the order that tests are run in. -g_test_run_suite() or g_test_run() may only be called once -in a program. - +[func@GLib.test_run_suite] or [func@GLib.test_run] may only be +called once in a program. + 0 on success + filename="glib/gtestutils.c" + line="3285">0 on success a #GTestSuite + filename="glib/gtestutils.c" + line="3273">a test suite @@ -79705,27 +85364,31 @@ in a program. c:identifier="g_test_set_nonfatal_assertions" version="2.38"> Changes the behaviour of the various `g_assert_*()` macros, -g_test_assert_expected_messages() and the various -`g_test_trap_assert_*()` macros to not abort to program, but instead -call g_test_fail() and continue. (This also changes the behavior of -g_test_fail() so that it will not cause the test program to abort -after completing the failed test.) + filename="glib/gtestutils.c" + line="2752">Changes the behaviour of the various assertion macros. + +The `g_assert_*()` macros, `g_test_assert_expected_messages()` +and the various `g_test_trap_assert_*()` macros are changed +to not abort to program. -Note that the g_assert_not_reached() and g_assert() macros are not -affected by this. +Instead, they will call [func@GLib.test_fail] and continue. +(This also changes the behavior of [func@GLib.test_fail] so that +it will not cause the test program to abort after completing +the failed test.) -This function can only be called after g_test_init(). - +Note that the [func@GLib.assert_not_reached] and [func@GLib.assert] +macros are not affected by this. + +This function can only be called after [func@GLib.test_init]. + Indicates that a test was skipped. + filename="glib/gtestutils.c" + line="2679">Indicates that a test was skipped. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can @@ -79733,7 +85396,7 @@ produce additional diagnostic messages or even continue running the test. If not called from inside a test, this function does nothing. - + @@ -79743,8 +85406,8 @@ If not called from inside a test, this function does nothing. nullable="1" allow-none="1"> explanation + filename="glib/gtestutils.c" + line="2681">explanation @@ -79754,24 +85417,26 @@ If not called from inside a test, this function does nothing. version="2.70" introspectable="0"> Equivalent to g_test_skip(), but the explanation is formatted -as if by g_strdup_printf(). - + filename="glib/gtestutils.c" + line="2702">Indicates that a test was skipped. + +Equivalent to [func@GLib.test_skip], but the explanation +is formatted as if by [func@GLib.strdup_printf]. + the format string + filename="glib/gtestutils.c" + line="2704">the format string printf-like arguments to @format + filename="glib/gtestutils.c" + line="2705">printf-like arguments to @format @@ -79780,65 +85445,64 @@ as if by g_strdup_printf(). c:identifier="g_test_slow" introspectable="0"> Returns %TRUE if tests are run in slow mode. -Exactly one of g_test_quick() and g_test_slow() is active in any run; -there is no "medium speed". + filename="glib/gtestutils.c" + line="95">Returns true if tests are run in slow mode. + +Tests are always run in slow mode or in fast mode; there is no "medium speed". By default, tests are run in quick mode. In tests that use -g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` +[func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. - + Returns %TRUE (after g_test_init() has been called) if the test -program is running under g_test_trap_subprocess(). - + filename="glib/gtestutils.c" + line="4201">Returns true if the test program is running under [func@GLib.test_trap_subprocess]. + %TRUE if the test program is running under -g_test_trap_subprocess(). + filename="glib/gtestutils.c" + line="4206">true if the test program is running under [func@GLib.test_trap_subprocess] Set the summary for a test, which describes what the test checks, and how it -goes about checking it. This may be included in test report output, and is -useful documentation for anyone reading the source code or modifying a test -in future. It must be a single line. + filename="glib/gtestutils.c" + line="2261">Sets the summary for a test. + +This may be included in test report output, and is useful documentation for +anyone reading the source code or modifying a test in future. It must be a +single line, and it should summarise what the test checks, and how. This should be called at the top of a test function. For example: -|[<!-- language="C" --> + +```c static void test_array_sort (void) { g_test_summary ("Test my_array_sort() sorts the array correctly and stably, " "including testing zero length and one-element arrays."); - … + // ... } -]| - -See also: g_test_bug() - +``` + +See also [func@GLib.test_bug]. + One or two sentences summarising what the test checks, and how it - checks it. + filename="glib/gtestutils.c" + line="2263">summary of the test purpose @@ -79847,27 +85511,28 @@ See also: g_test_bug() c:identifier="g_test_thorough" introspectable="0"> Returns %TRUE if tests are run in thorough mode, equivalent to -g_test_slow(). + filename="glib/gtestutils.c" + line="109">Returns true if tests are run in thorough mode. + +Thorough mode is equivalent to slow mode. By default, tests are run in quick mode. In tests that use -g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` +[func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. - + Get the number of seconds since the last start of the timer with -g_test_timer_start(). - + filename="glib/gtestutils.c" + line="2066">Gets the number of seconds since the last start of the timer with +[func@GLib.test_timer_start]. + the time since the last start of the timer in seconds, as a double + filename="glib/gtestutils.c" + line="2072">the time since the last start of the timer in seconds @@ -79875,13 +85540,13 @@ g_test_timer_start(). c:identifier="g_test_timer_last" version="2.16"> Report the last result of g_test_timer_elapsed(). - + filename="glib/gtestutils.c" + line="2083">Reports the last result of [func@GLib.test_timer_elapsed]. + the last result of g_test_timer_elapsed(), as a double + filename="glib/gtestutils.c" + line="2088">the last result of [func@GLib.test_timer_elapsed] @@ -79889,10 +85554,12 @@ g_test_timer_start(). c:identifier="g_test_timer_start" version="2.16"> Start a timing test. Call g_test_timer_elapsed() when the task is supposed + filename="glib/gtestutils.c" + line="2047">Starts a timing test. + +Call [func@GLib.test_timer_elapsed] when the task is supposed to be done. Call this function again to restart the timer. - + @@ -79902,48 +85569,52 @@ to be done. Call this function again to restart the timer. version="2.16" introspectable="0"> Assert that the last test subprocess failed. -See g_test_trap_subprocess(). + filename="glib/gtestutils.c" + line="226">Assert that the last test subprocess failed. + +See [func@GLib.test_trap_subprocess]. This is sometimes used to test situations that are formally considered to -be undefined behaviour, like inputs that fail a g_return_if_fail() +be undefined behaviour, like inputs that fail a [func@GLib.return_if_fail] check. In these situations you should skip the entire test, including the -call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE -to indicate that undefined behaviour may be tested. - +call to [func@GLib.test_trap_subprocess], unless [func@GLib.test_undefined] +returns true to indicate that undefined behaviour may be tested. + Assert that the last test subprocess passed. -See g_test_trap_subprocess(). - + filename="glib/gtestutils.c" + line="216">Assert that the last test subprocess passed. + +See [func@GLib.test_trap_subprocess]. + Assert that the stderr output of the last test subprocess -matches @serrpattern. See g_test_trap_subprocess(). + filename="glib/gtestutils.c" + line="266">Assert that the stderr output of the last test subprocess +matches @serrpattern. -This is sometimes used to test situations that are formally -considered to be undefined behaviour, like code that hits a -g_assert() or g_error(). In these situations you should skip the -entire test, including the call to g_test_trap_subprocess(), unless -g_test_undefined() returns %TRUE to indicate that undefined +See [func@GLib.test_trap_subprocess]. + +This is sometimes used to test situations that are formally considered +to be undefined behaviour, like code that hits a [func@GLib.assert] or +[func@GLib.error]. In these situations you should skip the entire test, +including the call to [func@GLib.test_trap_subprocess], unless +[func@GLib.test_undefined] returns true to indicate that undefined behaviour may be tested. - + a glob-style [pattern][glib-Glob-style-pattern-matching] + filename="glib/gtestutils.c" + line="268">a string that follows glob-style [pattern][struct@PatternSpec] rules @@ -79952,15 +85623,17 @@ behaviour may be tested. version="2.16" introspectable="0"> Assert that the stderr output of the last test subprocess -does not match @serrpattern. See g_test_trap_subprocess(). - + filename="glib/gtestutils.c" + line="285">Assert that the stderr output of the last test subprocess +does not match @serrpattern. + +See [func@GLib.test_trap_subprocess]. + a glob-style [pattern][glib-Glob-style-pattern-matching] + filename="glib/gtestutils.c" + line="287">a string that follows glob-style [pattern][struct@PatternSpec] rules @@ -79969,15 +85642,17 @@ does not match @serrpattern. See g_test_trap_subprocess(). version="2.16" introspectable="0"> Assert that the stdout output of the last test subprocess matches -@soutpattern. See g_test_trap_subprocess(). - + filename="glib/gtestutils.c" + line="242">Assert that the stdout output of the last test subprocess matches +@soutpattern. + +See [func@GLib.test_trap_subprocess]. + a glob-style [pattern][glib-Glob-style-pattern-matching] + filename="glib/gtestutils.c" + line="244">a string that follows glob-style [pattern][struct@PatternSpec] rules @@ -79986,21 +85661,23 @@ does not match @serrpattern. See g_test_trap_subprocess(). version="2.16" introspectable="0"> Assert that the stdout output of the last test subprocess -does not match @soutpattern. See g_test_trap_subprocess(). - + filename="glib/gtestutils.c" + line="254">Assert that the stdout output of the last test subprocess +does not match @soutpattern. + +See [func@GLib.test_trap_subprocess]. + a glob-style [pattern][glib-Glob-style-pattern-matching] + filename="glib/gtestutils.c" + line="256">a string that follows glob-style [pattern][struct@PatternSpec] rules - + @@ -80030,57 +85707,60 @@ does not match @soutpattern. See g_test_trap_subprocess(). version="2.16" deprecated="1"> Fork the current test program to execute a test case that might + filename="glib/gtestutils.c" + line="3882">Forks the current test program to execute a test case that might not return or that might abort. If @usec_timeout is non-0, the forked test case is aborted and considered failing if its run time exceeds it. -The forking behavior can be configured with the #GTestTrapFlags flags. +The forking behavior can be configured with [flags@GLib.TestTrapFlags] +flags. In the following example, the test code forks, the forked child process produces some sample output and exits successfully. The forking parent process then asserts successful child program termination and validates child program outputs. -|[<!-- language="C" --> +```c static void test_fork_patterns (void) { if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) { - g_print ("some stdout text: somagic17\n"); - g_printerr ("some stderr text: semagic43\n"); + g_print ("some stdout text: somagic17 +"); + g_printerr ("some stderr text: semagic43 +"); exit (0); // successful test run } g_test_trap_assert_passed (); g_test_trap_assert_stdout ("*somagic17*"); g_test_trap_assert_stderr ("*semagic43*"); } -]| +``` This function is implemented only on Unix platforms, is not always reliable due to problems inherent in fork-without-exec and doesn't set close-on-exec flag on its file descriptors. -Use g_test_trap_subprocess() instead. - +Use func@GLib.test_trap_subprocess] instead. + %TRUE for the forked child and %FALSE for the executing parent process. + filename="glib/gtestutils.c" + line="3919">true for the forked child and false for the executing parent process. Timeout for the forked test in micro seconds. + filename="glib/gtestutils.c" + line="3884">timeout for the forked test in microseconds Flags to modify forking behaviour. + filename="glib/gtestutils.c" + line="3885">flags to modify forking behaviour @@ -80089,13 +85769,13 @@ Use g_test_trap_subprocess() instead. c:identifier="g_test_trap_has_passed" version="2.16"> Check the result of the last g_test_trap_subprocess() call. - + filename="glib/gtestutils.c" + line="4216">Checks the result of the last [func@GLib.test_trap_subprocess] call. + %TRUE if the last test subprocess terminated successfully. + filename="glib/gtestutils.c" + line="4221">true if the last test subprocess terminated successfully @@ -80103,13 +85783,13 @@ Use g_test_trap_subprocess() instead. c:identifier="g_test_trap_reached_timeout" version="2.16"> Check the result of the last g_test_trap_subprocess() call. - + filename="glib/gtestutils.c" + line="4236">Checks the result of the last [func@GLib.test_trap_subprocess] call. + %TRUE if the last test subprocess got killed due to a timeout. + filename="glib/gtestutils.c" + line="4241">true if the last test subprocess got killed due to a timeout @@ -80117,14 +85797,54 @@ Use g_test_trap_subprocess() instead. c:identifier="g_test_trap_subprocess" version="2.38"> Respawns the test program to run only @test_path in a subprocess. + filename="glib/gtestutils.c" + line="4000">Respawns the test program to run only @test_path in a subprocess. + +This is equivalent to calling [func@GLib.test_trap_subprocess_with_envp] +with `envp` set to `NULL`. See the documentation for that function +for full details. + + + + + + + test to run in a subprocess + + + + timeout for the subprocess test in microseconds. + + + + flags to modify subprocess behaviour + + + + + + Respawns the test program to run only @test_path in a subprocess with +a given environment. + This can be used for a test case that might not return, or that might abort. -If @test_path is %NULL then the same test is re-run in a subprocess. -You can use g_test_subprocess() to determine whether the test is in -a subprocess or not. +If @test_path is `NULL` then the same test is re-run in a subprocess. +You can use [func@GLib.test_subprocess] to determine whether the test +is in a subprocess or not. @test_path can also be the name of the parent test, followed by "`/subprocess/`" and then a name for the specific subtest (or just @@ -80132,33 +85852,34 @@ ending with "`/subprocess`" if the test only has one child test); tests with names of this form will automatically be skipped in the parent process. +If @envp is `NULL`, the parent process’ environment will be inherited. + If @usec_timeout is non-0, the test subprocess is aborted and considered failing if its run time exceeds it. -The subprocess behavior can be configured with the -#GTestSubprocessFlags flags. +The subprocess behavior can be configured with [flags@GLib.TestSubprocessFlags] +flags. -You can use methods such as g_test_trap_assert_passed(), -g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to +You can use methods such as [func@GLib.test_trap_assert_passed], +[func@GLib.test_trap_assert_failed], and [func@GLib.test_trap_assert_stderr] to check the results of the subprocess. (But note that -g_test_trap_assert_stdout() and g_test_trap_assert_stderr() +[func@GLib.test_trap_assert_stdout] and [func@GLib.test_trap_assert_stderr] cannot be used if @test_flags specifies that the child should inherit the parent stdout/stderr.) -If your `main ()` needs to behave differently in -the subprocess, you can call g_test_subprocess() (after calling -g_test_init()) to see whether you are in a subprocess. +If your `main ()` needs to behave differently in the subprocess, you can +call [func@GLib.test_subprocess] (after calling [func@GLib.test_init]) +to see whether you are in a subprocess. Internally, this function tracks the child process using -g_child_watch_source_new(), so your process must not ignore `SIGCHLD`, and -must not attempt to watch or wait for the child process via another -mechanism. +[func@GLib.child_watch_source_new], so your process must not ignore +`SIGCHLD`, and must not attempt to watch or wait for the child process +via another mechanism. -The following example tests that calling -`my_object_new(1000000)` will abort with an error -message. +The following example tests that calling `my_object_new(1000000)` will +abort with an error message. -|[<!-- language="C" --> +```c static void test_create_large_object (void) { @@ -80174,17 +85895,37 @@ message. g_test_trap_assert_stderr ("*ERROR*too large*"); } + static void + test_different_username (void) + { + if (g_test_subprocess ()) + { + // Code under test goes here + g_message ("Username is now simulated as %s", g_getenv ("USER")); + return; + } + + // Reruns this same test in a subprocess + g_autoptr(GStrv) envp = g_get_environ (); + envp = g_environ_setenv (g_steal_pointer (&envp), "USER", "charlie", TRUE); + g_test_trap_subprocess_with_envp (NULL, envp, 0, G_TEST_SUBPROCESS_DEFAULT); + g_test_trap_assert_passed (); + g_test_trap_assert_stdout ("Username is now simulated as charlie"); + } + int main (int argc, char **argv) { g_test_init (&argc, &argv, NULL); - g_test_add_func ("/myobject/create_large_object", + g_test_add_func ("/myobject/create-large-object", test_create_large_object); + g_test_add_func ("/myobject/different-username", + test_different_username); return g_test_run (); } -]| - +``` + @@ -80194,20 +85935,32 @@ message. nullable="1" allow-none="1"> Test to run in a subprocess + filename="glib/gtestutils.c" + line="4024">test to run in a subprocess + + environment + to run the test in + + + + Timeout for the subprocess test in micro seconds. + filename="glib/gtestutils.c" + line="4027">timeout for the subprocess test in microseconds Flags to modify subprocess behaviour. + filename="glib/gtestutils.c" + line="4028">flags to modify subprocess behaviour @@ -80216,214 +85969,149 @@ message. c:identifier="g_test_undefined" introspectable="0"> Returns %TRUE if tests may provoke assertions and other formally-undefined -behaviour, to verify that appropriate warnings are given. It might, in some -cases, be useful to turn this off with if running tests under valgrind; -in tests that use g_test_init(), the option `-m no-undefined` disables + filename="glib/gtestutils.c" + line="135">Returns true if tests may provoke assertions and other formally-undefined +behaviour, to verify that appropriate warnings are given. + +This might, in some cases, be useful to turn this off (e.g. if running tests +under valgrind). + +In tests that use [func@GLib.test_init], the option `-m no-undefined` disables those tests, while `-m undefined` explicitly enables them (normally the default behaviour). Since GLib 2.68, if GLib was compiled with gcc or clang and [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) is enabled, the default changes to not exercising undefined behaviour. - + Returns %TRUE if tests are run in verbose mode. -In tests that use g_test_init(), the option `--verbose` enables this, + filename="glib/gtestutils.c" + line="155">Returns true if tests are run in verbose mode. + +In tests that use [func@GLib.test_init], the option `--verbose` enables this, while `-q` or `--quiet` disables it. -The default is neither g_test_verbose() nor g_test_quiet(). - + +The default is neither verbose nor quiet. + - + GLib provides a framework for writing and maintaining unit tests -in parallel to the code they are testing. The API is designed according -to established concepts found in the other test frameworks (JUnit, NUnit, -RUnit), which in turn is based on smalltalk unit testing concepts. - -- Test case: Tests (test methods) are grouped together with their - fixture into test cases. - -- Fixture: A test fixture consists of fixture data and setup and - teardown methods to establish the environment for the test - functions. We use fresh fixtures, i.e. fixtures are newly set - up and torn down around each test invocation to avoid dependencies - between tests. - -- Test suite: Test cases can be grouped into test suites, to allow - subsets of the available tests to be run. Test suites can be - grouped into other test suites as well. - -The API is designed to handle creation and registration of test suites -and test cases implicitly. A simple call like -|[<!-- language="C" --> - g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); - - g_test_add_func ("/misc/assertions", test_assertions); -]| -creates a test suite called "misc" with a single test case named -"assertions", which consists of running the test_assertions function. - -g_test_init() should be called before calling any other test functions. - -In addition to the traditional g_assert_true(), the test framework provides -an extended set of assertions for comparisons: g_assert_cmpfloat(), -g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(), -g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and -g_assert_cmpvariant(). The -advantage of these variants over plain g_assert_true() is that the assertion -messages can be more elaborate, and include the values of the compared -entities. - -Note that g_assert() should not be used in unit tests, since it is a no-op -when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code, -and g_assert_true() in unit tests. - -A full example of creating a test suite with two tests using fixtures: -|[<!-- language="C" --> -#include <glib.h> -#include <locale.h> - -typedef struct { - MyObject *obj; - OtherObject *helper; -} MyObjectFixture; - -static void -my_object_fixture_set_up (MyObjectFixture *fixture, - gconstpointer user_data) -{ - fixture->obj = my_object_new (); - my_object_set_prop1 (fixture->obj, "some-value"); - my_object_do_some_complex_setup (fixture->obj, user_data); - - fixture->helper = other_object_new (); -} - -static void -my_object_fixture_tear_down (MyObjectFixture *fixture, - gconstpointer user_data) -{ - g_clear_object (&fixture->helper); - g_clear_object (&fixture->obj); -} - -static void -test_my_object_test1 (MyObjectFixture *fixture, - gconstpointer user_data) -{ - g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value"); -} - -static void -test_my_object_test2 (MyObjectFixture *fixture, - gconstpointer user_data) -{ - my_object_do_some_work_using_helper (fixture->obj, fixture->helper); - g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value"); -} - -int -main (int argc, char *argv[]) -{ - setlocale (LC_ALL, ""); - - g_test_init (&argc, &argv, NULL); - - // Define the tests. - g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data", - my_object_fixture_set_up, test_my_object_test1, - my_object_fixture_tear_down); - g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data", - my_object_fixture_set_up, test_my_object_test2, - my_object_fixture_tear_down); - - return g_test_run (); -} -]| - -## Integrating GTest in your project - -If you are using the [Meson](http://mesonbuild.com) build system, you will -typically use the provided `test()` primitive to call the test binaries, -e.g.: - -|[<!-- language="plain" --> - test( - 'foo', - executable('foo', 'foo.c', dependencies: deps), - env: [ - 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), - 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), - ], - ) - - test( - 'bar', - executable('bar', 'bar.c', dependencies: deps), - env: [ - 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), - 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), - ], - ) -]| - -If you are using Autotools, you're strongly encouraged to use the Automake -[TAP](https://testanything.org/) harness; GLib provides template files for -easily integrating with it: - - - [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk) - - [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test) - - [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh) - -You can copy these files in your own project's root directory, and then -set up your `Makefile.am` file to reference them, for instance: - -|[<!-- language="plain" --> -include $(top_srcdir)/glib-tap.mk + filename="glib/deprecated/gthread-deprecated.c" + line="312">This function creates a new thread. -# test binaries -test_programs = \ - foo \ - bar +The new thread executes the function @func with the argument @data. +If the thread was created successfully, it is returned. -# data distributed in the tarball -dist_test_data = \ - foo.data.txt \ - bar.data.txt - -# data not distributed in the tarball -test_data = \ - blah.data.txt -]| - -Make sure to distribute the TAP files, using something like the following -in your top-level `Makefile.am`: - -|[<!-- language="plain" --> -EXTRA_DIST += \ - tap-driver.sh \ - tap-test -]| - -`glib-tap.mk` will be distributed implicitly due to being included in a -`Makefile.am`. All three files should be added to version control. - -If you don't have access to the Autotools TAP harness, you can use the -[gtester][gtester] and [gtester-report][gtester-report] tools, and use -the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk) -Automake template provided by GLib. Note, however, that since GLib 2.62, -[gtester][gtester] and [gtester-report][gtester-report] have been deprecated -in favour of using TAP. The `--tap` argument to tests is enabled by default -as of GLib 2.62. - +@error can be %NULL to ignore errors, or non-%NULL to report errors. +The error is set, if and only if the function returns %NULL. + +This function returns a reference to the created thread only if +@joinable is %TRUE. In that case, you must free this reference by +calling g_thread_unref() or g_thread_join(). If @joinable is %FALSE +then you should probably not touch the return value. + Use g_thread_new() instead + + + the new #GThread on success + + + + + a function to execute in the new thread + + + + an argument to supply to the new thread + + + + should this thread be joinable? + + + + + + This function creates a new thread. + The @bound and @priority arguments are now ignored. +Use g_thread_new(). + + + the new #GThread on success. + + + + + a function to execute in the new thread. + + + + an argument to supply to the new thread. + + + + a stack size for the new thread. + + + + should this thread be joinable? + + + + ignored + + + + ignored + + + + @@ -80435,8 +86123,8 @@ as of GLib 2.62. c:identifier="g_thread_exit" moved-to="Thread.exit"> Terminates the current thread. + filename="glib/gthread.c" + line="997">Terminates the current thread. If another thread is waiting for us using g_thread_join() then the waiting thread will be woken up and get @retval as the return value @@ -80449,7 +86137,7 @@ You must only call g_thread_exit() from a thread that you created yourself with g_thread_new() or related APIs. You must not call this function from a thread created with another threading library or or from within a #GThreadPool. - + @@ -80459,8 +86147,138 @@ or or from within a #GThreadPool. nullable="1" allow-none="1"> the return value of this thread + filename="glib/gthread.c" + line="999">the return value of this thread + + + + + + Call @thread_func on all #GThreads that have been +created with g_thread_create(). + +Note that threads may decide to exit while @thread_func is +running, so without intimate knowledge about the lifetime of +foreign threads, @thread_func shouldn't access the GThread* +pointer passed in as first argument. However, @thread_func will +not be called for threads which are known to have exited already. + +Due to thread lifetime checks, this function has an execution complexity +which is quadratic in the number of existing threads. + There aren't many things you can do with a #GThread, + except comparing it with one that was returned from g_thread_create(). + There are better ways to find out if your thread is still alive. + + + + + + + function to call for all #GThread structures + + + + second argument to @thread_func + + + + + + Indicates if g_thread_init() has been called. + + + %TRUE if threads have been initialized. + + + + + If you use GLib from more than one thread, you must initialize the +thread system by calling g_thread_init(). + +Since version 2.24, calling g_thread_init() multiple times is allowed, +but nothing happens except for the first call. + +Since version 2.32, GLib does not support custom thread implementations +anymore and the @vtable parameter is ignored and you should pass %NULL. + +::: note + g_thread_init() must not be called directly or indirectly in a + callback from GLib. Also no mutexes may be currently locked + while calling g_thread_init(). + +::: note + To use g_thread_init() in your program, you have to link with + the libraries that the command `pkg-config --libs gthread-2.0` + outputs. This is not the case for all the other thread-related + functions of GLib. Those can be used without having to link + with the thread libraries. + This function is no longer necessary. The GLib + threading system is automatically initialized at the start + of your program. + + + + + + + a function table of type #GThreadFunctions, that provides + the entry points to the thread system to be used. Since 2.32, + this parameter is ignored and should always be %NULL + + + + + + + + + + + @@ -80470,18 +86288,18 @@ or or from within a #GThreadPool. moved-to="ThreadPool.get_max_idle_time" version="2.10"> This function will return the maximum @interval that a + filename="glib/gthreadpool.c" + line="1181">This function will return the maximum @interval that a thread will wait in the thread pool for new tasks before being stopped. If this function returns 0, threads waiting in the thread pool for new work are not stopped. - + the maximum @interval (milliseconds) to wait + filename="glib/gthreadpool.c" + line="1191">the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread @@ -80491,13 +86309,13 @@ pool for new work are not stopped. c:identifier="g_thread_pool_get_max_unused_threads" moved-to="ThreadPool.get_max_unused_threads"> Returns the maximal allowed number of unused threads. - + filename="glib/gthreadpool.c" + line="1018">Returns the maximal allowed number of unused threads. + the maximal number of unused threads + filename="glib/gthreadpool.c" + line="1023">the maximal number of unused threads @@ -80505,13 +86323,13 @@ pool for new work are not stopped. c:identifier="g_thread_pool_get_num_unused_threads" moved-to="ThreadPool.get_num_unused_threads"> Returns the number of currently unused threads. - + filename="glib/gthreadpool.c" + line="1031">Returns the number of currently unused threads. + the number of currently unused threads + filename="glib/gthreadpool.c" + line="1036">the number of currently unused threads @@ -80520,8 +86338,8 @@ pool for new work are not stopped. moved-to="ThreadPool.set_max_idle_time" version="2.10"> This function will set the maximum @interval that a thread + filename="glib/gthreadpool.c" + line="1140">This function will set the maximum @interval that a thread waiting in the pool for new tasks can be idle for before being stopped. This function is similar to calling g_thread_pool_stop_unused_threads() on a regular timeout, @@ -80530,15 +86348,15 @@ except this is done on a per thread basis. By setting @interval to 0, idle threads will not be stopped. The default value is 15000 (15 seconds). - + the maximum @interval (in milliseconds) + filename="glib/gthreadpool.c" + line="1142">the maximum @interval (in milliseconds) a thread can be idle @@ -80548,21 +86366,21 @@ The default value is 15000 (15 seconds). c:identifier="g_thread_pool_set_max_unused_threads" moved-to="ThreadPool.set_max_unused_threads"> Sets the maximal number of unused threads to @max_threads. + filename="glib/gthreadpool.c" + line="979">Sets the maximal number of unused threads to @max_threads. If @max_threads is -1, no limit is imposed on the number of unused threads. -The default value is 2. - +The default value is 8 since GLib 2.84. Previously the default value was 2. + maximal number of unused threads + filename="glib/gthreadpool.c" + line="981">maximal number of unused threads @@ -80571,54 +86389,21 @@ The default value is 2. c:identifier="g_thread_pool_stop_unused_threads" moved-to="ThreadPool.stop_unused_threads"> Stops all currently unused threads. This does not change the + filename="glib/gthreadpool.c" + line="1044">Stops all currently unused threads. This does not change the maximal number of unused threads. This function can be used to regularly stop all unused threads e.g. from g_timeout_add(). - + - - Sometimes you wish to asynchronously fork out the execution of work -and continue working in your own thread. If that will happen often, -the overhead of starting and destroying a thread each time might be -too high. In such cases reusing already started threads seems like a -good idea. And it indeed is, but implementing this can be tedious -and error-prone. - -Therefore GLib provides thread pools for your convenience. An added -advantage is, that the threads can be shared between the different -subsystems of your program, when they are using GLib. - -To create a new thread pool, you use g_thread_pool_new(). -It is destroyed by g_thread_pool_free(). - -If you want to execute a certain task within a thread pool, -you call g_thread_pool_push(). - -To get the current number of running threads you call -g_thread_pool_get_num_threads(). To get the number of still -unprocessed tasks you call g_thread_pool_unprocessed(). To control -the maximal number of threads for a thread pool, you use -g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). - -Finally you can control the number of unused threads, that are kept -alive by GLib for future use. The current number can be fetched with -g_thread_pool_get_num_unused_threads(). The maximal number can be -controlled by g_thread_pool_get_max_unused_threads() and -g_thread_pool_set_max_unused_threads(). All currently unused threads -can be stopped by calling g_thread_pool_stop_unused_threads(). - This function returns the #GThread corresponding to the + filename="glib/gthread.c" + line="1072">This function returns the #GThread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct. @@ -80627,121 +86412,40 @@ were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as g_thread_join()) on these threads. - + the #GThread representing the current thread + filename="glib/gthread.c" + line="1085">the #GThread representing the current thread + + This macro returns %TRUE if the thread system is initialized, +and %FALSE if it is not. + +For language bindings, g_thread_get_initialized() provides +the same functionality as a function. + + Causes the calling thread to voluntarily relinquish the CPU, so + filename="glib/gthread.c" + line="1919">Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run. This function is often used as a method to make busy wait less evil. - + - - Threads act almost like processes, but unlike processes all threads -of one process share the same memory. This is good, as it provides -easy communication between the involved threads via this shared -memory, and it is bad, because strange things (so called -"Heisenbugs") might happen if the program is not carefully designed. -In particular, due to the concurrent nature of threads, no -assumptions on the order of execution of code running in different -threads can be made, unless order is explicitly forced by the -programmer through synchronization primitives. - -The aim of the thread-related functions in GLib is to provide a -portable means for writing multi-threaded software. There are -primitives for mutexes to protect the access to portions of memory -(#GMutex, #GRecMutex and #GRWLock). There is a facility to use -individual bits for locks (g_bit_lock()). There are primitives -for condition variables to allow synchronization of threads (#GCond). -There are primitives for thread-private data - data that every -thread has a private instance of (#GPrivate). There are facilities -for one-time initialization (#GOnce, g_once_init_enter()). Finally, -there are primitives to create and manage threads (#GThread). - -The GLib threading system used to be initialized with g_thread_init(). -This is no longer necessary. Since version 2.32, the GLib threading -system is automatically initialized at the start of your program, -and all thread-creation functions and synchronization primitives -are available right away. - -Note that it is not safe to assume that your program has no threads -even if you don't call g_thread_new() yourself. GLib and GIO can -and will create threads for their own purposes in some cases, such -as when using g_unix_signal_source_new() or when using GDBus. - -Originally, UNIX did not have threads, and therefore some traditional -UNIX APIs are problematic in threaded programs. Some notable examples -are - -- C library functions that return data in statically allocated - buffers, such as strtok() or strerror(). For many of these, - there are thread-safe variants with a _r suffix, or you can - look at corresponding GLib APIs (like g_strsplit() or g_strerror()). - -- The functions setenv() and unsetenv() manipulate the process - environment in a not thread-safe way, and may interfere with getenv() - calls in other threads. Note that getenv() calls may be hidden behind - other APIs. For example, GNU gettext() calls getenv() under the - covers. In general, it is best to treat the environment as readonly. - If you absolutely have to modify the environment, do it early in - main(), when no other threads are around yet. - -- The setlocale() function changes the locale for the entire process, - affecting all threads. Temporary changes to the locale are often made - to change the behavior of string scanning or formatting functions - like scanf() or printf(). GLib offers a number of string APIs - (like g_ascii_formatd() or g_ascii_strtod()) that can often be - used as an alternative. Or you can use the uselocale() function - to change the locale only for the current thread. - -- The fork() function only takes the calling thread into the child's - copy of the process image. If other threads were executing in critical - sections they could have left mutexes locked which could easily - cause deadlocks in the new child. For this reason, you should - call exit() or exec() as soon as possible in the child and only - make signal-safe library calls before that. - -- The daemon() function uses fork() in a way contrary to what is - described above. It should not be used with GLib programs. - -GLib itself is internally completely thread-safe (all global data is -automatically locked), but individual data structure instances are -not automatically locked for performance reasons. For example, -you must coordinate accesses to the same #GHashTable from multiple -threads. The two notable exceptions from this rule are #GMainLoop -and #GAsyncQueue, which are thread-safe and need no further -application-level locking to be accessed from multiple threads. -Most refcounting functions such as g_object_ref() are also thread-safe. - -A common use for #GThreads is to move a long-running blocking operation out -of the main thread and into a worker thread. For GLib functions, such as -single GIO operations, this is not necessary, and complicates the code. -Instead, the `…_async()` version of the function should be used from the main -thread, eliminating the need for locking and synchronisation between multiple -threads. If an operation does need to be moved to a worker thread, consider -using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a -better choice than #GThread, as it handles thread reuse and task queueing; -#GTask uses this internally. - -However, if multiple blocking operations need to be performed in sequence, -and it is not possible to use #GTask for them, moving them to a worker thread -can clarify the code. - deprecated="1" deprecated-version="2.62"> Converts a string containing an ISO 8601 encoded date and time + filename="glib/gtimer.c" + line="357">Converts a string containing an ISO 8601 encoded date and time to a #GTimeVal and puts it into @time_. @iso_date must include year, month, day, hours, minutes, and @@ -80769,18 +86473,18 @@ g_date_time_unref (dt); ]| #GTimeVal is not year-2038-safe. Use g_date_time_new_from_iso8601() instead. - + %TRUE if the conversion was successful. + filename="glib/gtimer.c" + line="380">%TRUE if the conversion was successful. an ISO 8601 encoded date string + filename="glib/gtimer.c" + line="359">an ISO 8601 encoded date string a #GTimeVal + filename="glib/gtimer.c" + line="360">a #GTimeVal @@ -80799,14 +86503,14 @@ g_date_time_unref (dt); shadowed-by="timeout_add_full" introspectable="0"> Sets a function to be called at regular intervals, with the default -priority, %G_PRIORITY_DEFAULT. + filename="glib/gmain.c" + line="5264">Sets a function to be called at regular intervals, with the default +priority, [const@GLib.PRIORITY_DEFAULT]. -The given @function is called repeatedly until it returns %G_SOURCE_REMOVE -or %FALSE, at which point the timeout is automatically destroyed and the -function will not be called again. The first call to the function will be -at the end of the first @interval. +The given @function is called repeatedly until it returns +[const@GLib.SOURCE_REMOVE] or %FALSE, at which point the timeout is +automatically destroyed and the function will not be called again. The first +call to the function will be at the end of the first @interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. @@ -80814,43 +86518,44 @@ After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays). -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. If you want to have a timer in the "seconds" range and do not care about the exact time of the first call of the timer, use the -g_timeout_add_seconds() function; this function allows for more +[func@GLib.timeout_add_seconds] function; this function allows for more optimizations and more efficient system power usage. -This internally creates a main loop source using g_timeout_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. +This internally creates a main loop source using +[func@GLib.timeout_source_new] and attaches it to the global +[struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback +will be invoked in whichever thread is running that main context. You can do +these steps manually if you need greater control or to use a custom main +context. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - +time. See [func@GLib.get_monotonic_time]. + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="5305">the ID (greater than 0) of the event source. the time between calls to the function, in milliseconds + filename="glib/gmain.c" + line="5266">the time between calls to the function, in milliseconds (1/1000ths of a second) function to call + filename="glib/gmain.c" + line="5268">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="5269">data to pass to @function @@ -80868,8 +86573,8 @@ time. See g_get_monotonic_time(). c:identifier="g_timeout_add_full" shadows="timeout_add"> Sets a function to be called at regular intervals, with the given + filename="glib/gmain.c" + line="5215">Sets a function to be called at regular intervals, with the given priority. The function is called repeatedly until it returns %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. The @notify function is @@ -80882,36 +86587,38 @@ After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays). -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -This internally creates a main loop source using g_timeout_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. +This internally creates a main loop source using +[func@GLib.timeout_source_new] and attaches it to the global +[struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback +will be invoked in whichever thread is running that main context. You can do +these steps manually if you need greater control or to use a custom main +context. The interval given is in terms of monotonic time, not wall clock time. -See g_get_monotonic_time(). - +See [func@GLib.get_monotonic_time]. + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="5252">the ID (greater than 0) of the event source. the priority of the timeout source. Typically this will be in - the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. + filename="glib/gmain.c" + line="5217">the priority of the timeout source. Typically this will be in + the range between [const@GLib.PRIORITY_DEFAULT] and + [const@GLib.PRIORITY_HIGH]. the time between calls to the function, in milliseconds + filename="glib/gmain.c" + line="5220">the time between calls to the function, in milliseconds (1/1000ths of a second) @@ -80921,8 +86628,8 @@ See g_get_monotonic_time(). closure="3" destroy="4"> function to call + filename="glib/gmain.c" + line="5222">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="5223">data to pass to @function allow-none="1" scope="async"> function to call when the timeout is removed, or %NULL + filename="glib/gmain.c" + line="5224">function to call when the timeout is removed, or %NULL @@ -80951,33 +86658,33 @@ See g_get_monotonic_time(). version="2.74" introspectable="0"> Sets a function to be called after @interval milliseconds have elapsed, -with the default priority, %G_PRIORITY_DEFAULT. + filename="glib/gmain.c" + line="5316">Sets a function to be called after @interval milliseconds have elapsed, +with the default priority, [const@GLib.PRIORITY_DEFAULT]. The given @function is called once and then the source will be automatically removed from the main context. -This function otherwise behaves like g_timeout_add(). - +This function otherwise behaves like [func@GLib.timeout_add]. + the ID (greater than 0) of the event source + filename="glib/gmain.c" + line="5331">the ID (greater than 0) of the event source the time after which the function will be called, in + filename="glib/gmain.c" + line="5318">the time after which the function will be called, in milliseconds (1/1000ths of a second) function to call + filename="glib/gmain.c" + line="5320">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="5321">data to pass to @function @@ -80997,48 +86704,48 @@ This function otherwise behaves like g_timeout_add(). version="2.14" introspectable="0"> Sets a function to be called at regular intervals with the default -priority, %G_PRIORITY_DEFAULT. + filename="glib/gmain.c" + line="5408">Sets a function to be called at regular intervals with the default +priority, [const@GLib.PRIORITY_DEFAULT]. -The function is called repeatedly until it returns %G_SOURCE_REMOVE +The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE] or %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. This internally creates a main loop source using -g_timeout_source_new_seconds() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you need -greater control. Also see g_timeout_add_seconds_full(). +[func@GLib.timeout_source_new_seconds] and attaches it to the main loop context +using [method@GLib.Source.attach]. You can do these steps manually if you need +greater control. Also see [func@GLib.timeout_add_seconds_full]. It is safe to call this function from any thread. Note that the first call of the timer may not be precise for timeouts of one second. If you need finer precision and have such a timeout, -you may want to use g_timeout_add() instead. +you may want to use [func@GLib.timeout_add] instead. -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - +time. See [func@GLib.get_monotonic_time]. + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="5438">the ID (greater than 0) of the event source. the time between calls to the function, in seconds + filename="glib/gmain.c" + line="5410">the time between calls to the function, in seconds function to call + filename="glib/gmain.c" + line="5411">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="5412">data to pass to @function @@ -81057,65 +86764,67 @@ time. See g_get_monotonic_time(). shadows="timeout_add_seconds" version="2.14"> Sets a function to be called at regular intervals, with @priority. + filename="glib/gmain.c" + line="5343">Sets a function to be called at regular intervals, with @priority. -The function is called repeatedly until it returns %G_SOURCE_REMOVE +The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE] or %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. -Unlike g_timeout_add(), this function operates at whole second granularity. -The initial starting point of the timer is determined by the implementation -and the implementation is expected to group multiple timers together so that -they fire all at the same time. To allow this grouping, the @interval to the -first timer is rounded and can deviate up to one second from the specified -interval. Subsequent timer iterations will generally run at the specified -interval. +Unlike [func@GLib.timeout_add], this function operates at whole second +granularity. The initial starting point of the timer is determined by the +implementation and the implementation is expected to group multiple timers +together so that they fire all at the same time. To allow this grouping, the +@interval to the first timer is rounded and can deviate up to one second +from the specified interval. Subsequent timer iterations will generally run +at the specified interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given @interval -See [memory management of sources][mainloop-memory-management] for details +See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -If you want timing more precise than whole seconds, use g_timeout_add() -instead. +If you want timing more precise than whole seconds, use +[func@GLib.timeout_add] instead. The grouping of timers to fire at the same time results in a more power and CPU efficient behavior so if your timer is in multiples of seconds and you don't require the first timer exactly one second from now, the -use of g_timeout_add_seconds() is preferred over g_timeout_add(). +use of [func@GLib.timeout_add_seconds] is preferred over +[func@GLib.timeout_add]. This internally creates a main loop source using -g_timeout_source_new_seconds() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you need -greater control. +[func@GLib.timeout_source_new_seconds] and attaches it to the main loop +context using [method@GLib.Source.attach]. You can do these steps manually +if you need greater control. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - +time. See [func@GLib.get_monotonic_time]. + the ID (greater than 0) of the event source. + filename="glib/gmain.c" + line="5394">the ID (greater than 0) of the event source. the priority of the timeout source. Typically this will be in - the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. + filename="glib/gmain.c" + line="5345">the priority of the timeout source. Typically this will be in + the range between [const@GLib.PRIORITY_DEFAULT] and + [const@GLib.PRIORITY_HIGH]. the time between calls to the function, in seconds + filename="glib/gmain.c" + line="5348">the time between calls to the function, in seconds closure="3" destroy="4"> function to call + filename="glib/gmain.c" + line="5349">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="5350">data to pass to @function allow-none="1" scope="async"> function to call when the timeout is removed, or %NULL + filename="glib/gmain.c" + line="5351">function to call when the timeout is removed, or %NULL @@ -81154,26 +86863,27 @@ time. See g_get_monotonic_time(). version="2.78" introspectable="0"> This function behaves like g_timeout_add_once() but with a range in seconds. - + filename="glib/gmain.c" + line="5452">This function behaves like [func@GLib.timeout_add_once] but with a range in +seconds. + the ID (greater than 0) of the event source + filename="glib/gmain.c" + line="5461">the ID (greater than 0) of the event source the time after which the function will be called, in seconds + filename="glib/gmain.c" + line="5454">the time after which the function will be called, in seconds function to call + filename="glib/gmain.c" + line="5455">function to call nullable="1" allow-none="1"> data to pass to @function + filename="glib/gmain.c" + line="5456">data to pass to @function Creates a new timeout source. + filename="glib/gmain.c" + line="5139">Creates a new timeout source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be +The source will not initially be associated with any [struct@GLib.MainContext] +and must be added to one with [method@GLib.Source.attach] before it will be executed. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - +time. See [func@GLib.get_monotonic_time]. + the newly-created timeout source + filename="glib/gmain.c" + line="5152">the newly-created timeout source the timeout interval in milliseconds. + filename="glib/gmain.c" + line="5141">the timeout interval in milliseconds. @@ -81218,111 +86928,58 @@ time. See g_get_monotonic_time(). c:identifier="g_timeout_source_new_seconds" version="2.14"> Creates a new timeout source. + filename="glib/gmain.c" + line="5160">Creates a new timeout source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. +The source will not initially be associated with any +[struct@GLib.MainContext] and must be added to one with +[method@GLib.Source.attach] before it will be executed. The scheduling granularity/accuracy of this timeout source will be in seconds. The interval given is in terms of monotonic time, not wall clock time. -See g_get_monotonic_time(). - +See [func@GLib.get_monotonic_time]. + the newly-created timeout source + filename="glib/gmain.c" + line="5176">the newly-created timeout source the timeout interval in seconds + filename="glib/gmain.c" + line="5162">the timeout interval in seconds - - #GTimer records a start time, and counts microseconds elapsed since -that time. This is done somewhat differently on different platforms, -and can be tricky to get exactly right, so #GTimer provides a -portable/convenient interface. - - - #GTimeZone is a structure that represents a time zone, at no -particular point in time. It is refcounted and immutable. - -Each time zone has an identifier (for example, ‘Europe/London’) which is -platform dependent. See g_time_zone_new() for information on the identifier -formats. The identifier of a time zone can be retrieved using -g_time_zone_get_identifier(). - -A time zone contains a number of intervals. Each interval has -an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a -flag indicating if the daylight savings time is in effect during that -interval. A time zone always has at least one interval — interval 0. Note -that interval abbreviations are not the same as time zone identifiers -(apart from ‘UTC’), and cannot be passed to g_time_zone_new(). - -Every UTC time is contained within exactly one interval, but a given -local time may be contained within zero, one or two intervals (due to -incontinuities associated with daylight savings time). - -An interval may refer to a specific period of time (eg: the duration -of daylight savings time during 2010) or it may refer to many periods -of time that share the same properties (eg: all periods of daylight -savings time). It is also possible (usually for political reasons) -that some properties (like the abbreviation) change between intervals -without other properties changing. - -#GTimeZone is available since GLib 2.26. - - - A #GTrashStack is an efficient way to keep a stack of unused allocated -memory chunks. Each memory chunk is required to be large enough to hold -a #gpointer. This allows the stack to be maintained without any space -overhead, since the stack pointers can be stored inside the memory chunks. - -There is no function to create a #GTrashStack. A %NULL #GTrashStack* -is a perfectly valid empty stack. - -There is no longer any good reason to use #GTrashStack. If you have -extra pieces of memory, free() them and allocate them again later. - Returns the height of a #GTrashStack. + filename="glib/gtrashstack.c" + line="124">Returns the height of a #GTrashStack. Note that execution of this function is of O(N) complexity where N denotes the number of items on the stack. #GTrashStack is deprecated without replacement - + the height of the stack + filename="glib/gtrashstack.c" + line="133">the height of the stack a #GTrashStack + filename="glib/gtrashstack.c" + line="126">a #GTrashStack @@ -81333,22 +86990,22 @@ where N denotes the number of items on the stack. deprecated="1" deprecated-version="2.48"> Returns the element at the top of a #GTrashStack + filename="glib/gtrashstack.c" + line="104">Returns the element at the top of a #GTrashStack which may be %NULL. #GTrashStack is deprecated without replacement - + the element at the top of the stack + filename="glib/gtrashstack.c" + line="111">the element at the top of the stack a #GTrashStack + filename="glib/gtrashstack.c" + line="106">a #GTrashStack @@ -81359,21 +87016,21 @@ which may be %NULL. deprecated="1" deprecated-version="2.48"> Pops a piece of memory off a #GTrashStack. + filename="glib/gtrashstack.c" + line="77">Pops a piece of memory off a #GTrashStack. #GTrashStack is deprecated without replacement - + the element at the top of the stack + filename="glib/gtrashstack.c" + line="83">the element at the top of the stack a #GTrashStack + filename="glib/gtrashstack.c" + line="79">a #GTrashStack @@ -81384,128 +87041,66 @@ which may be %NULL. deprecated="1" deprecated-version="2.48"> Pushes a piece of memory onto a #GTrashStack. + filename="glib/gtrashstack.c" + line="59">Pushes a piece of memory onto a #GTrashStack. #GTrashStack is deprecated without replacement - + a #GTrashStack + filename="glib/gtrashstack.c" + line="61">a #GTrashStack the piece of memory to push on the stack + filename="glib/gtrashstack.c" + line="62">the piece of memory to push on the stack - - The #GTree structure and its associated functions provide a sorted -collection of key/value pairs optimized for searching and traversing -in order. This means that most of the operations (access, search, -insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n) -in worst case for time complexity. But, note that maintaining a -balanced sorted #GTree of n elements is done in time O(n log(n)). - -To create a new #GTree use g_tree_new(). - -To insert a key/value pair into a #GTree use g_tree_insert() -(O(n log(n))). - -To remove a key/value pair use g_tree_remove() (O(n log(n))). - -To look up the value corresponding to a given key, use -g_tree_lookup() and g_tree_lookup_extended(). - -To find out the number of nodes in a #GTree, use g_tree_nnodes(). To -get the height of a #GTree, use g_tree_height(). - -To traverse a #GTree, calling a function for each node visited in -the traversal, use g_tree_foreach(). - -To destroy a #GTree, use g_tree_destroy(). - - - The #GNode struct and its associated functions provide a N-ary tree -data structure, where nodes in the tree can contain arbitrary data. - -To create a new tree use g_node_new(). - -To insert a node into a tree use g_node_insert(), -g_node_insert_before(), g_node_append() and g_node_prepend(). - -To create a new node and insert it into a tree use -g_node_insert_data(), g_node_insert_data_after(), -g_node_insert_data_before(), g_node_append_data() -and g_node_prepend_data(). - -To reverse the children of a node use g_node_reverse_children(). - -To find a node use g_node_get_root(), g_node_find(), -g_node_find_child(), g_node_child_index(), g_node_child_position(), -g_node_first_child(), g_node_last_child(), g_node_nth_child(), -g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() -or g_node_last_sibling(). - -To get information about a node or tree use G_NODE_IS_LEAF(), -G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), -g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). - -To traverse a tree, calling a function for each node visited in the -traversal, use g_node_traverse() or g_node_children_foreach(). - -To remove a node or subtree from a tree use g_node_unlink() or -g_node_destroy(). - Attempts to allocate @n_bytes, and returns %NULL on failure. + filename="glib/gmem.c" + line="304">Attempts to allocate @n_bytes, and returns %NULL on failure. Contrast with g_malloc(), which aborts the program on failure. - + the allocated memory, or %NULL. + filename="glib/gmem.c" + line="311">the allocated memory, or %NULL. number of bytes to allocate. + filename="glib/gmem.c" + line="306">number of bytes to allocate. Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on + filename="glib/gmem.c" + line="328">Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on failure. Contrast with g_malloc0(), which aborts the program on failure. - + the allocated memory, or %NULL + filename="glib/gmem.c" + line="336">the allocated memory, or %NULL number of bytes to allocate + filename="glib/gmem.c" + line="330">number of bytes to allocate @@ -81514,54 +87109,54 @@ failure. Contrast with g_malloc0(), which aborts the program on failure. c:identifier="g_try_malloc0_n" version="2.24"> This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, + filename="glib/gmem.c" + line="490">This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. - + the allocated memory, or %NULL + filename="glib/gmem.c" + line="499">the allocated memory, or %NULL the number of blocks to allocate + filename="glib/gmem.c" + line="492">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="493">the size of each block in bytes This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, + filename="glib/gmem.c" + line="469">This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. - + the allocated memory, or %NULL. + filename="glib/gmem.c" + line="478">the allocated memory, or %NULL. the number of blocks to allocate + filename="glib/gmem.c" + line="471">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="472">the size of each block in bytes @@ -81571,22 +87166,22 @@ but care is taken to detect possible overflow during multiplication. version="2.8" introspectable="0"> Attempts to allocate @n_structs elements of type @struct_type, and returns + filename="glib/gmem.h" + line="350">Attempts to allocate @n_structs elements of type @struct_type, and returns %NULL on failure. Contrast with g_new(), which aborts the program on failure. The returned pointer is cast to a pointer to the given type. The function returns %NULL when @n_structs is 0 of if an overflow occurs. - + the type of the elements to allocate + filename="glib/gmem.h" + line="352">the type of the elements to allocate the number of elements to allocate + filename="glib/gmem.h" + line="353">the number of elements to allocate @@ -81595,39 +87190,39 @@ The function returns %NULL when @n_structs is 0 of if an overflow occurs. version="2.8" introspectable="0"> Attempts to allocate @n_structs elements of type @struct_type, initialized + filename="glib/gmem.h" + line="364">Attempts to allocate @n_structs elements of type @struct_type, initialized to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts the program on failure. The returned pointer is cast to a pointer to the given type. The function returns %NULL when @n_structs is 0 or if an overflow occurs. - + the type of the elements to allocate + filename="glib/gmem.h" + line="366">the type of the elements to allocate the number of elements to allocate + filename="glib/gmem.h" + line="367">the number of elements to allocate Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL + filename="glib/gmem.c" + line="351">Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL on failure. Contrast with g_realloc(), which aborts the program on failure. If @mem is %NULL, behaves the same as g_try_malloc(). - + the allocated memory, or %NULL. + filename="glib/gmem.c" + line="362">the allocated memory, or %NULL. @@ -81636,14 +87231,14 @@ If @mem is %NULL, behaves the same as g_try_malloc(). nullable="1" allow-none="1"> previously-allocated memory, or %NULL. + filename="glib/gmem.c" + line="353">previously-allocated memory, or %NULL. number of bytes to allocate. + filename="glib/gmem.c" + line="354">number of bytes to allocate. @@ -81652,14 +87247,14 @@ If @mem is %NULL, behaves the same as g_try_malloc(). c:identifier="g_try_realloc_n" version="2.24"> This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, + filename="glib/gmem.c" + line="511">This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, but care is taken to detect possible overflow during multiplication. - + the allocated memory, or %NULL. + filename="glib/gmem.c" + line="521">the allocated memory, or %NULL. @@ -81668,20 +87263,20 @@ but care is taken to detect possible overflow during multiplication. nullable="1" allow-none="1"> previously-allocated memory, or %NULL. + filename="glib/gmem.c" + line="513">previously-allocated memory, or %NULL. the number of blocks to allocate + filename="glib/gmem.c" + line="514">the number of blocks to allocate the size of each block in bytes + filename="glib/gmem.c" + line="515">the size of each block in bytes @@ -81691,136 +87286,68 @@ but care is taken to detect possible overflow during multiplication. version="2.8" introspectable="0"> Attempts to reallocate the memory pointed to by @mem, so that it now has + filename="glib/gmem.h" + line="379">Attempts to reallocate the memory pointed to by @mem, so that it now has space for @n_structs elements of type @struct_type, and returns %NULL on failure. Contrast with g_renew(), which aborts the program on failure. It returns the new address of the memory, which may have been moved. The function returns %NULL if an overflow occurs. - + the type of the elements to allocate + filename="glib/gmem.h" + line="381">the type of the elements to allocate the currently allocated memory + filename="glib/gmem.h" + line="382">the currently allocated memory the number of elements to allocate + filename="glib/gmem.h" + line="383">the number of elements to allocate - - Many times GLib, GTK, and other libraries allow you to pass "user -data" to a callback, in the form of a void pointer. From time to time -you want to pass an integer instead of a pointer. You could allocate -an integer, with something like: -|[<!-- language="C" --> - int *ip = g_new (int, 1); - *ip = 42; -]| -But this is inconvenient, and it's annoying to have to free the -memory at some later time. - -Pointers are always at least 32 bits in size (on all platforms GLib -intends to support). Thus you can store at least 32-bit integer values -in a pointer value. Naively, you might try this, but it's incorrect: -|[<!-- language="C" --> - gpointer p; - int i; - p = (void*) 42; - i = (int) p; -]| -Again, that example was not correct, don't copy it. -The problem is that on some systems you need to do this: -|[<!-- language="C" --> - gpointer p; - int i; - p = (void*) (long) 42; - i = (int) (long) p; -]| -The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care -to do the right thing on every platform. - -Warning: You may not store pointers in integers. This is not -portable in any way, shape or form. These macros only allow storing -integers in pointers, and only preserve 32 bits of the integer; values -outside the range of a 32-bit integer will be mangled. - - + - - GLib defines a number of commonly used types, which can be divided -into several groups: -- New types which are not part of standard C (but are defined in - various C standard library header files) — #gboolean, #gssize. -- Integer types which are guaranteed to be the same size across - all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, - #guint32, #gint64, #guint64. -- Types which are easier to use than their standard C counterparts - - #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. -- Types which correspond exactly to standard C types, but are - included for completeness — #gchar, #gint, #gshort, #glong, - #gfloat, #gdouble. -- Types which correspond exactly to standard C99 types, but are available - to use even if your compiler does not support C99 — #gsize, #goffset, - #gintptr, #guintptr. - -GLib also defines macros for the limits of some of the standard -integer and floating point types, as well as macros for suitable -printf() formats for these types. - -Note that depending on the platform and build configuration, the format -macros might not be compatible with the system provided printf() function, -because GLib might use a different printf() implementation internally. -The format macros will always work with GLib API (like g_print()), and with -any C99 compatible printf() implementation. - Convert a string from UCS-4 to UTF-16. A 0 character will be -added to the result after the converted text. - + filename="glib/gutf8.c" + line="1484">Convert a string from UCS-4 to UTF-16. + +A nul character (U+0000) will be added to the result after the converted text. + a pointer to a newly allocated UTF-16 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + filename="glib/gutf8.c" + line="1503">a pointer to a newly allocated UTF-16 string. + This value must be freed with [func@GLib.free]. a UCS-4 encoded string + filename="glib/gutf8.c" + line="1486">a UCS-4 encoded string the maximum length (number of characters) of @str to use. - If @len < 0, then the string is nul-terminated. + filename="glib/gutf8.c" + line="1487">the maximum length (number of characters) of @str to use. + If @len is negative, then the string is nul-terminated. optional="1" allow-none="1"> location to store number of - bytes read, or %NULL. If an error occurs then the index of the invalid - input is stored here. + filename="glib/gutf8.c" + line="1489">location to store number of + bytes read, or `NULL`. If an error occurs then the index of the invalid + input is stored here. optional="1" allow-none="1"> location to store number - of #gunichar2 written, or %NULL. The value stored here does not include - the trailing 0. + filename="glib/gutf8.c" + line="1492">location to store number + of `gunichar2` written, or `NULL`. The value stored here does not include + the trailing nul. Convert a string from a 32-bit fixed width representation as UCS-4. -to UTF-8. The result will be terminated with a 0 byte. - + filename="glib/gutf8.c" + line="997">Convert a string from a 32-bit fixed width representation as UCS-4. +to UTF-8. + +The result will be terminated with a nul byte. + a pointer to a newly allocated UTF-8 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. In that case, @items_read - will be set to the position of the first invalid input character. + filename="glib/gutf8.c" + line="1016">a pointer to a newly allocated UTF-8 string. + This value must be freed with [func@GLib.free]. If an error occurs, + @items_read will be set to the position of the first invalid input + character. a UCS-4 encoded string + filename="glib/gutf8.c" + line="999">a UCS-4 encoded string the maximum length (number of characters) of @str to use. - If @len < 0, then the string is nul-terminated. + filename="glib/gutf8.c" + line="1000">the maximum length (number of characters) of @str to use. + If @len is negative, then the string is nul-terminated. optional="1" allow-none="1"> location to store number of - characters read, or %NULL. + filename="glib/gutf8.c" + line="1002">location to store number of + characters read, or `NULL`. optional="1" allow-none="1"> location to store number - of bytes written or %NULL. The value here stored does not include the - trailing 0 byte. + filename="glib/gutf8.c" + line="1004">location to store number + of bytes written or `NULL`. The value here stored does not include the + trailing nul byte. @@ -81914,29 +87443,29 @@ to UTF-8. The result will be terminated with a 0 byte. version="2.48" introspectable="0"> Performs a checked addition of @a and @b, storing the result in + filename="glib/docs.c" + line="704">Performs a checked addition of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. - + a pointer to the #guint64 destination + filename="glib/docs.c" + line="706">a pointer to the #guint64 destination the #guint64 left operand + filename="glib/docs.c" + line="707">the #guint64 left operand the #guint64 right operand + filename="glib/docs.c" + line="708">the #guint64 right operand @@ -81945,29 +87474,29 @@ returned. version="2.48" introspectable="0"> Performs a checked multiplication of @a and @b, storing the result in + filename="glib/docs.c" + line="721">Performs a checked multiplication of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. - + a pointer to the #guint64 destination + filename="glib/docs.c" + line="723">a pointer to the #guint64 destination the #guint64 left operand + filename="glib/docs.c" + line="724">the #guint64 left operand the #guint64 right operand + filename="glib/docs.c" + line="725">the #guint64 right operand @@ -81976,29 +87505,29 @@ returned. version="2.48" introspectable="0"> Performs a checked addition of @a and @b, storing the result in + filename="glib/docs.c" + line="670">Performs a checked addition of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. - + a pointer to the #guint destination + filename="glib/docs.c" + line="672">a pointer to the #guint destination the #guint left operand + filename="glib/docs.c" + line="673">the #guint left operand the #guint right operand + filename="glib/docs.c" + line="674">the #guint right operand @@ -82007,53 +87536,53 @@ returned. version="2.48" introspectable="0"> Performs a checked multiplication of @a and @b, storing the result in + filename="glib/docs.c" + line="687">Performs a checked multiplication of @a and @b, storing the result in @dest. If the operation is successful, %TRUE is returned. If the operation overflows then the state of @dest is undefined and %FALSE is returned. - + a pointer to the #guint destination + filename="glib/docs.c" + line="689">a pointer to the #guint destination the #guint left operand + filename="glib/docs.c" + line="690">the #guint left operand the #guint right operand + filename="glib/docs.c" + line="691">the #guint right operand Determines the break type of @c. @c should be a Unicode character + filename="glib/gunibreak.c" + line="44">Determines the break type of @c. @c should be a Unicode character (to derive a character from UTF-8 encoded text, use g_utf8_get_char()). The break type is used to find word and line breaks ("text boundaries"), Pango implements the Unicode boundary resolution algorithms and normally you would use a function such as pango_break() instead of caring about break types yourself. - + the break type of @c + filename="glib/gunibreak.c" + line="55">the break type of @c a Unicode character + filename="glib/gunibreak.c" + line="46">a Unicode character @@ -82062,20 +87591,20 @@ as pango_break() instead of caring about break types yourself. c:identifier="g_unichar_combining_class" version="2.14"> Determines the canonical combining class of a Unicode character. - + filename="glib/gunidecomp.c" + line="51">Determines the canonical combining class of a Unicode character. + the combining class of the character + filename="glib/gunidecomp.c" + line="57">the combining class of the character a Unicode character + filename="glib/gunidecomp.c" + line="53">a Unicode character @@ -82084,8 +87613,8 @@ as pango_break() instead of caring about break types yourself. c:identifier="g_unichar_compose" version="2.30"> Performs a single composition step of the + filename="glib/gunidecomp.c" + line="669">Performs a single composition step of the Unicode canonical composition algorithm. This function includes algorithmic Hangul Jamo composition, @@ -82101,24 +87630,24 @@ If @a and @b do not compose a new character, @ch is set to zero. See [UAX#15](http://unicode.org/reports/tr15/) for details. - + %TRUE if the characters could be composed + filename="glib/gunidecomp.c" + line="692">%TRUE if the characters could be composed a Unicode character + filename="glib/gunidecomp.c" + line="671">a Unicode character a Unicode character + filename="glib/gunidecomp.c" + line="672">a Unicode character caller-allocates="0" transfer-ownership="full"> return location for the composed character + filename="glib/gunidecomp.c" + line="673">return location for the composed character @@ -82136,18 +87665,18 @@ for details. c:identifier="g_unichar_decompose" version="2.30"> Performs a single decomposition step of the + filename="glib/gunidecomp.c" + line="595">Performs a single decomposition step of the Unicode canonical decomposition algorithm. This function does not include compatibility decompositions. It does, however, include algorithmic Hangul Jamo decomposition, as well as 'singleton' decompositions which replace a character by a single -other character. In the case of singletons *@b will +other character. In the case of singletons `*b` will be set to zero. -If @ch is not decomposable, *@a is set to @ch and *@b +If @ch is not decomposable, `*a` is set to @ch and `*b` is set to zero. Note that the way Unicode decomposition pairs are @@ -82160,18 +87689,18 @@ g_unichar_fully_decompose(). See [UAX#15](http://unicode.org/reports/tr15/) for details. - + %TRUE if the character could be decomposed + filename="glib/gunidecomp.c" + line="625">%TRUE if the character could be decomposed a Unicode character + filename="glib/gunidecomp.c" + line="597">a Unicode character caller-allocates="0" transfer-ownership="full"> return location for the first component of @ch + filename="glib/gunidecomp.c" + line="598">return location for the first component of @ch caller-allocates="0" transfer-ownership="full"> return location for the second component of @ch + filename="glib/gunidecomp.c" + line="599">return location for the second component of @ch Determines the numeric value of a character as a decimal + filename="glib/guniprop.c" + line="671">Determines the numeric value of a character as a decimal digit. - + If @c is a decimal digit (according to + filename="glib/guniprop.c" + line="678">If @c is a decimal digit (according to g_unichar_isdigit()), its numeric value. Otherwise, -1. a Unicode character + filename="glib/guniprop.c" + line="673">a Unicode character @@ -82220,8 +87749,8 @@ g_unichar_isdigit()), its numeric value. Otherwise, -1. c:identifier="g_unichar_fully_decompose" version="2.30"> Computes the canonical or compatibility decomposition of a + filename="glib/gunidecomp.c" + line="708">Computes the canonical or compatibility decomposition of a Unicode character. For compatibility decomposition, pass %TRUE for @compat; for canonical decomposition pass %FALSE for @compat. @@ -82240,24 +87769,24 @@ as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. See [UAX#15](http://unicode.org/reports/tr15/) for details. - + the length of the full decomposition. + filename="glib/gunidecomp.c" + line="735">the length of the full decomposition. a Unicode character. + filename="glib/gunidecomp.c" + line="710">a Unicode character. whether perform canonical or compatibility decomposition + filename="glib/gunidecomp.c" + line="711">whether perform canonical or compatibility decomposition optional="1" allow-none="1"> location to store decomposed result, or %NULL + filename="glib/gunidecomp.c" + line="712">location to store decomposed result, or %NULL length of @result + filename="glib/gunidecomp.c" + line="713">length of @result @@ -82283,8 +87812,8 @@ for details. c:identifier="g_unichar_get_mirror_char" version="2.4"> In Unicode, some characters are "mirrored". This means that their + filename="glib/guniprop.c" + line="1236">In Unicode, some characters are "mirrored". This means that their images are mirrored horizontally in text that is laid out from right to left. For instance, "(" would become its mirror image, ")", in right-to-left text. @@ -82293,18 +87822,18 @@ If @ch has the Unicode mirrored property and there is another unicode character that typically has a glyph that is the mirror image of @ch's glyph and @mirrored_ch is set, it puts that character in the address pointed to by @mirrored_ch. Otherwise the original character is put. - + %TRUE if @ch has a mirrored character, %FALSE otherwise + filename="glib/guniprop.c" + line="1251">%TRUE if @ch has a mirrored character, %FALSE otherwise a Unicode character + filename="glib/guniprop.c" + line="1238">a Unicode character caller-allocates="0" transfer-ownership="full"> location to store the mirrored character + filename="glib/guniprop.c" + line="1239">location to store the mirrored character @@ -82322,181 +87851,181 @@ pointed to by @mirrored_ch. Otherwise the original character is put. c:identifier="g_unichar_get_script" version="2.14"> Looks up the #GUnicodeScript for a particular character (as defined + filename="glib/guniprop.c" + line="1299">Looks up the #GUnicodeScript for a particular character (as defined by Unicode Standard Annex \#24). No check is made for @ch being a valid Unicode character; if you pass in invalid character, the result is undefined. This function is equivalent to pango_script_for_unichar() and the two are interchangeable. - + the #GUnicodeScript for the character. + filename="glib/guniprop.c" + line="1311">the #GUnicodeScript for the character. a Unicode character + filename="glib/guniprop.c" + line="1301">a Unicode character Determines whether a character is alphanumeric. + filename="glib/guniprop.c" + line="106">Determines whether a character is alphanumeric. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is an alphanumeric character + filename="glib/guniprop.c" + line="114">%TRUE if @c is an alphanumeric character a Unicode character + filename="glib/guniprop.c" + line="108">a Unicode character Determines whether a character is alphabetic (i.e. a letter). + filename="glib/guniprop.c" + line="122">Determines whether a character is alphabetic (i.e. a letter). Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is an alphabetic character + filename="glib/guniprop.c" + line="130">%TRUE if @c is an alphabetic character a Unicode character + filename="glib/guniprop.c" + line="124">a Unicode character Determines whether a character is a control character. + filename="glib/guniprop.c" + line="139">Determines whether a character is a control character. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is a control character + filename="glib/guniprop.c" + line="147">%TRUE if @c is a control character a Unicode character + filename="glib/guniprop.c" + line="141">a Unicode character Determines if a given character is assigned in the Unicode + filename="glib/guniprop.c" + line="381">Determines if a given character is assigned in the Unicode standard. - + %TRUE if the character has an assigned value + filename="glib/guniprop.c" + line="388">%TRUE if the character has an assigned value a Unicode character + filename="glib/guniprop.c" + line="383">a Unicode character Determines whether a character is numeric (i.e. a digit). This + filename="glib/guniprop.c" + line="155">Determines whether a character is numeric (i.e. a digit). This covers ASCII 0-9 and also digits in other languages/scripts. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is a digit + filename="glib/guniprop.c" + line="163">%TRUE if @c is a digit a Unicode character + filename="glib/guniprop.c" + line="157">a Unicode character Determines whether a character is printable and not a space + filename="glib/guniprop.c" + line="172">Determines whether a character is printable and not a space (returns %FALSE for control characters, format characters, and spaces). g_unichar_isprint() is similar, but returns %TRUE for spaces. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is printable unless it's a space + filename="glib/guniprop.c" + line="182">%TRUE if @c is printable unless it's a space a Unicode character + filename="glib/guniprop.c" + line="174">a Unicode character Determines whether a character is a lowercase letter. + filename="glib/guniprop.c" + line="196">Determines whether a character is a lowercase letter. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is a lowercase letter + filename="glib/guniprop.c" + line="204">%TRUE if @c is a lowercase letter a Unicode character + filename="glib/guniprop.c" + line="198">a Unicode character @@ -82505,8 +88034,8 @@ g_utf8_get_char(). c:identifier="g_unichar_ismark" version="2.14"> Determines whether a character is a mark (non-spacing mark, + filename="glib/guniprop.c" + line="302">Determines whether a character is a mark (non-spacing mark, combining mark, or enclosing mark in Unicode speak). Given some UTF-8 text, obtain a character value with g_utf8_get_char(). @@ -82515,155 +88044,155 @@ Note: in most cases where isalpha characters are allowed, ismark characters should be allowed to as they are essential for writing most European languages as well as many non-Latin scripts. - + %TRUE if @c is a mark character + filename="glib/guniprop.c" + line="316">%TRUE if @c is a mark character a Unicode character + filename="glib/guniprop.c" + line="304">a Unicode character Determines whether a character is printable. + filename="glib/guniprop.c" + line="213">Determines whether a character is printable. Unlike g_unichar_isgraph(), returns %TRUE for spaces. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is printable + filename="glib/guniprop.c" + line="222">%TRUE if @c is printable a Unicode character + filename="glib/guniprop.c" + line="215">a Unicode character Determines whether a character is punctuation or a symbol. + filename="glib/guniprop.c" + line="235">Determines whether a character is punctuation or a symbol. Given some UTF-8 text, obtain a character value with g_utf8_get_char(). - + %TRUE if @c is a punctuation or symbol character + filename="glib/guniprop.c" + line="243">%TRUE if @c is a punctuation or symbol character a Unicode character + filename="glib/guniprop.c" + line="237">a Unicode character Determines whether a character is a space, tab, or line separator + filename="glib/guniprop.c" + line="263">Determines whether a character is a space, tab, or line separator (newline, carriage return, etc.). Given some UTF-8 text, obtain a character value with g_utf8_get_char(). (Note: don't use this to do word breaking; you have to use Pango or equivalent to get word breaking right, the algorithm is fairly complex.) - + %TRUE if @c is a space character + filename="glib/guniprop.c" + line="275">%TRUE if @c is a space character a Unicode character + filename="glib/guniprop.c" + line="265">a Unicode character Determines if a character is titlecase. Some characters in + filename="glib/guniprop.c" + line="340">Determines if a character is titlecase. Some characters in Unicode which are composites, such as the DZ digraph have three case variants instead of just two. The titlecase form is used at the beginning of a word where only the first letter is capitalized. The titlecase form of the DZ digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. - + %TRUE if the character is titlecase + filename="glib/guniprop.c" + line="351">%TRUE if the character is titlecase a Unicode character + filename="glib/guniprop.c" + line="342">a Unicode character Determines if a character is uppercase. - + filename="glib/guniprop.c" + line="326">Determines if a character is uppercase. + %TRUE if @c is an uppercase character + filename="glib/guniprop.c" + line="332">%TRUE if @c is an uppercase character a Unicode character + filename="glib/guniprop.c" + line="328">a Unicode character Determines if a character is typically rendered in a double-width + filename="glib/guniprop.c" + line="488">Determines if a character is typically rendered in a double-width cell. - + %TRUE if the character is wide + filename="glib/guniprop.c" + line="495">%TRUE if the character is wide a Unicode character + filename="glib/guniprop.c" + line="490">a Unicode character @@ -82672,8 +88201,8 @@ cell. c:identifier="g_unichar_iswide_cjk" version="2.12"> Determines if a character is typically rendered in a double-width + filename="glib/guniprop.c" + line="516">Determines if a character is typically rendered in a double-width cell under legacy East Asian locales. If a character is wide according to g_unichar_iswide(), then it is also reported wide with this function, but the converse is not necessarily true. See the @@ -82683,38 +88212,38 @@ for details. If a character passes the g_unichar_iswide() test then it will also pass this test, but not the other way around. Note that some characters may pass both this test and g_unichar_iszerowidth(). - + %TRUE if the character is wide in legacy East Asian locales + filename="glib/guniprop.c" + line="531">%TRUE if the character is wide in legacy East Asian locales a Unicode character + filename="glib/guniprop.c" + line="518">a Unicode character Determines if a character is a hexadecimal digit. - + filename="glib/guniprop.c" + line="363">Determines if a character is a hexadecimal digit. + %TRUE if the character is a hexadecimal digit + filename="glib/guniprop.c" + line="369">%TRUE if the character is a hexadecimal digit a Unicode character. + filename="glib/guniprop.c" + line="365">a Unicode character. @@ -82723,8 +88252,8 @@ pass both this test and g_unichar_iszerowidth(). c:identifier="g_unichar_iszerowidth" version="2.14"> Determines if a given character typically takes zero width when rendered. + filename="glib/guniprop.c" + line="399">Determines if a given character typically takes zero width when rendered. The return value is %TRUE for all non-spacing and enclosing marks (e.g., combining accents), format characters, zero-width space, but not U+00AD SOFT HYPHEN. @@ -82733,38 +88262,38 @@ A typical use of this function is with one of g_unichar_iswide() or g_unichar_iswide_cjk() to determine the number of cells a string occupies when displayed on a grid display (terminals). However, note that not all terminals support zero-width rendering of zero-width marks. - + %TRUE if the character has zero width + filename="glib/guniprop.c" + line="413">%TRUE if the character has zero width a Unicode character + filename="glib/guniprop.c" + line="401">a Unicode character Converts a single character to UTF-8. - + filename="glib/gutf8.c" + line="534">Converts a single character to UTF-8. + number of bytes written + filename="glib/gutf8.c" + line="543">number of bytes written a Unicode character code + filename="glib/gutf8.c" + line="536">a Unicode character code optional="1" allow-none="1"> output buffer, must have at - least 6 bytes of space. If %NULL, the length will be computed and - returned and nothing will be written to @outbuf. + filename="glib/gutf8.c" + line="537">output buffer, must have at + least 6 bytes of space. If `NULL`, the length will be computed and + returned and nothing will be written to @outbuf. Converts a character to lower case. - + filename="glib/guniprop.c" + line="597">Converts a character to lower case. + the result of converting @c to lower case. + filename="glib/guniprop.c" + line="603">the result of converting @c to lower case. If @c is not an upperlower or titlecase character, or has no lowercase equivalent @c is returned unchanged. @@ -82798,21 +88327,21 @@ terminals support zero-width rendering of zero-width marks. a Unicode character. + filename="glib/guniprop.c" + line="599">a Unicode character. Converts a character to the titlecase. - + filename="glib/guniprop.c" + line="638">Converts a character to the titlecase. + the result of converting @c to titlecase. + filename="glib/guniprop.c" + line="644">the result of converting @c to titlecase. If @c is not an uppercase or lowercase character, @c is returned unchanged. @@ -82820,21 +88349,21 @@ terminals support zero-width rendering of zero-width marks. a Unicode character + filename="glib/guniprop.c" + line="640">a Unicode character Converts a character to uppercase. - + filename="glib/guniprop.c" + line="557">Converts a character to uppercase. + the result of converting @c to uppercase. + filename="glib/guniprop.c" + line="563">the result of converting @c to uppercase. If @c is not a lowercase or titlecase character, or has no upper case equivalent @c is returned unchanged. @@ -82842,50 +88371,51 @@ terminals support zero-width rendering of zero-width marks. a Unicode character + filename="glib/guniprop.c" + line="559">a Unicode character Classifies a Unicode character by type. - + filename="glib/guniprop.c" + line="715">Classifies a Unicode character by type. + the type of the character. + filename="glib/guniprop.c" + line="721">the type of the character. a Unicode character + filename="glib/guniprop.c" + line="717">a Unicode character Checks whether @ch is a valid Unicode character. Some possible -integer values of @ch will not be valid. 0 is considered a valid -character, though it's normally a string terminator. - + filename="glib/gutf8.c" + line="1911">Checks whether @ch is a valid Unicode character. + +Some possible integer values of @ch will not be valid. U+0000 is considered a +valid character, though it’s normally a string terminator. + %TRUE if @ch is a valid Unicode character + filename="glib/gutf8.c" + line="1920">`TRUE` if @ch is a valid Unicode character a Unicode character + filename="glib/gutf8.c" + line="1913">a Unicode character @@ -82893,86 +88423,54 @@ character, though it's normally a string terminator. Determines the numeric value of a character as a hexadecimal + filename="glib/guniprop.c" + line="689">Determines the numeric value of a character as a hexadecimal digit. - + If @c is a hex digit (according to + filename="glib/guniprop.c" + line="696">If @c is a hex digit (according to g_unichar_isxdigit()), its numeric value. Otherwise, -1. a Unicode character + filename="glib/guniprop.c" + line="691">a Unicode character - - This section describes a number of functions for dealing with -Unicode characters and strings. There are analogues of the -traditional `ctype.h` character classification and case conversion -functions, UTF-8 analogues of some string utility functions, -functions to perform normalization, case conversion and collation -on UTF-8 strings and finally functions to convert between the UTF-8, -UTF-16 and UCS-4 encodings of Unicode. - -The implementations of the Unicode functions in GLib are based -on the Unicode Character Data tables, which are available from -[www.unicode.org](http://www.unicode.org/). - - * Unicode 4.0 was added in GLib 2.8 - * Unicode 4.1 was added in GLib 2.10 - * Unicode 5.0 was added in GLib 2.12 - * Unicode 5.1 was added in GLib 2.16.3 - * Unicode 6.0 was added in GLib 2.30 - * Unicode 6.1 was added in GLib 2.32 - * Unicode 6.2 was added in GLib 2.36 - * Unicode 6.3 was added in GLib 2.40 - * Unicode 7.0 was added in GLib 2.42 - * Unicode 8.0 was added in GLib 2.48 - * Unicode 9.0 was added in GLib 2.50.1 - * Unicode 10.0 was added in GLib 2.54 - * Unicode 11.10 was added in GLib 2.58 - * Unicode 12.0 was added in GLib 2.62 - * Unicode 12.1 was added in GLib 2.62 - * Unicode 13.0 was added in GLib 2.66 - Computes the canonical decomposition of a Unicode character. + filename="glib/gunidecomp.c" + line="199">Computes the canonical decomposition of a Unicode character. Use the more flexible g_unichar_fully_decompose() instead. - + a newly allocated string of Unicode characters. + filename="glib/gunidecomp.c" + line="206">a newly allocated string of Unicode characters. @result_len is set to the resulting length of the string. a Unicode character. + filename="glib/gunidecomp.c" + line="201">a Unicode character. location to store the length of the return value. + filename="glib/gunidecomp.c" + line="202">location to store the length of the return value. @@ -82980,38 +88478,39 @@ on the Unicode Character Data tables, which are available from Computes the canonical ordering of a string in-place. + filename="glib/gunidecomp.c" + line="78">Computes the canonical ordering of a string in-place. This rearranges decomposed characters in the string according to their combining classes. See the Unicode manual for more information. - + a UCS-4 encoded string. + filename="glib/gunidecomp.c" + line="80">a UCS-4 encoded string. the maximum length of @string to use. + filename="glib/gunidecomp.c" + line="81">the maximum length of @string to use. Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter + filename="glib/guniprop.c" + line="1574">Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. This function accepts four letter codes encoded as a @guint32 in a big-endian fashion. That is, the code expected for Arabic is @@ -83020,11 +88519,11 @@ big-endian fashion. That is, the code expected for Arabic is See [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) for details. - + the Unicode script for @iso15924, or + filename="glib/guniprop.c" + line="1588">the Unicode script for @iso15924, or of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. @@ -83032,18 +88531,19 @@ for details. a Unicode script + filename="glib/guniprop.c" + line="1576">a Unicode script Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter + filename="glib/guniprop.c" + line="1542">Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. The four letter codes are encoded as a @guint32 by this function in a big-endian fashion. That is, the code returned for Arabic is @@ -83052,11 +88552,11 @@ big-endian fashion. That is, the code returned for Arabic is See [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) for details. - + the ISO 15924 code for @script, encoded as an integer, + filename="glib/guniprop.c" + line="1556">the ISO 15924 code for @script, encoded as an integer, of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. @@ -83064,8 +88564,8 @@ for details. a Unicode script + filename="glib/guniprop.c" + line="1544">a Unicode script @@ -83080,8 +88580,8 @@ for details. version="2.36" introspectable="0"> Sets a function to be called when the IO condition, as specified by + filename="glib/glib-unix.c" + line="397">Sets a function to be called when the IO condition, as specified by @condition becomes true for @fd. @function will be called when the specified IO condition becomes @@ -83094,30 +88594,30 @@ The return value of this function can be passed to g_source_remove() to cancel the watch at any time that it exists. The source will never close the fd -- you must do it yourself. - + the ID (greater than 0) of the event source + filename="glib/glib-unix.c" + line="418">the ID (greater than 0) of the event source a file descriptor + filename="glib/glib-unix.c" + line="399">a file descriptor IO conditions to watch for on @fd + filename="glib/glib-unix.c" + line="400">IO conditions to watch for on @fd a #GUnixFDSourceFunc + filename="glib/glib-unix.c" + line="401">a #GUnixFDSourceFunc nullable="1" allow-none="1"> data to pass to @function + filename="glib/glib-unix.c" + line="402">data to pass to @function @@ -83135,37 +88635,37 @@ The source will never close the fd -- you must do it yourself. c:identifier="g_unix_fd_add_full" version="2.36"> Sets a function to be called when the IO condition, as specified by + filename="glib/glib-unix.c" + line="352">Sets a function to be called when the IO condition, as specified by @condition becomes true for @fd. This is the same as g_unix_fd_add(), except that it allows you to specify a non-default priority and a provide a #GDestroyNotify for @user_data. - + the ID (greater than 0) of the event source + filename="glib/glib-unix.c" + line="368">the ID (greater than 0) of the event source the priority of the source + filename="glib/glib-unix.c" + line="354">the priority of the source a file descriptor + filename="glib/glib-unix.c" + line="355">a file descriptor IO conditions to watch for on @fd + filename="glib/glib-unix.c" + line="356">IO conditions to watch for on @fd a #GUnixFDSourceFunc + filename="glib/glib-unix.c" + line="357">a #GUnixFDSourceFunc data to pass to @function + filename="glib/glib-unix.c" + line="358">data to pass to @function function to call when the idle is removed, or %NULL + filename="glib/glib-unix.c" + line="359">function to call when the idle is removed, or %NULL @@ -83199,32 +88699,32 @@ specify a non-default priority and a provide a #GDestroyNotify for c:identifier="g_unix_fd_source_new" version="2.36"> Creates a #GSource to watch for a particular I/O condition on a file + filename="glib/glib-unix.c" + line="319">Creates a #GSource to watch for a particular I/O condition on a file descriptor. The source will never close the @fd — you must do it yourself. Any callback attached to the returned #GSource must have type #GUnixFDSourceFunc. - + the newly created #GSource + filename="glib/glib-unix.c" + line="332">the newly created #GSource a file descriptor + filename="glib/glib-unix.c" + line="321">a file descriptor I/O conditions to watch for on @fd + filename="glib/glib-unix.c" + line="322">I/O conditions to watch for on @fd @@ -83234,8 +88734,8 @@ Any callback attached to the returned #GSource must have type version="2.64" throws="1"> Get the `passwd` file entry for the given @user_name using `getpwnam_r()`. + filename="glib/glib-unix.c" + line="431">Get the `passwd` file entry for the given @user_name using `getpwnam_r()`. This can fail if the given @user_name doesn’t exist. The returned `struct passwd` has been allocated using g_malloc() and should @@ -83246,19 +88746,19 @@ freed. This function is safe to call from multiple threads concurrently. You will need to include `pwd.h` to get the definition of `struct passwd`. - + passwd entry, or %NULL on error; free the returned + filename="glib/glib-unix.c" + line="448">passwd entry, or %NULL on error; free the returned value with g_free() the username to get the passwd file entry for + filename="glib/glib-unix.c" + line="433">the username to get the passwd file entry for @@ -83268,8 +88768,8 @@ You will need to include `pwd.h` to get the definition of `struct passwd`. version="2.30" throws="1"> Similar to the UNIX pipe() call, but on modern systems like Linux + filename="glib/glib-unix.c" + line="96">Similar to the UNIX pipe() call, but on modern systems like Linux uses the pipe2() system call, which atomically creates a pipe with the configured flags. @@ -83278,6 +88778,9 @@ and `O_NONBLOCK`. Prior to GLib 2.78, only `FD_CLOEXEC` was supported — if you wanted to configure `O_NONBLOCK` then that had to be done separately with `fcntl()`. +Since GLib 2.80, the constants %G_UNIX_PIPE_END_READ and +%G_UNIX_PIPE_END_WRITE can be used as mnemonic indexes in @fds. + It is a programmer error to call this function with unsupported flags, and a critical warning will be raised. @@ -83285,26 +88788,26 @@ As of GLib 2.78, it is preferred to pass `O_CLOEXEC` in, rather than `FD_CLOEXEC`, as that matches the underlying `pipe()` API more closely. Prior to 2.78, only `FD_CLOEXEC` was supported. Support for `FD_CLOEXEC` may be deprecated and removed in future. - + %TRUE on success, %FALSE if not (and errno will be set). + filename="glib/glib-unix.c" + line="122">%TRUE on success, %FALSE if not (and errno will be set). Array of two integers + filename="glib/glib-unix.c" + line="98">Array of two integers Bitfield of file descriptor flags, as for fcntl() + filename="glib/glib-unix.c" + line="99">Bitfield of file descriptor flags, as for fcntl() @@ -83314,28 +88817,28 @@ deprecated and removed in future. version="2.30" throws="1"> Control the non-blocking state of the given file descriptor, + filename="glib/glib-unix.c" + line="147">Control the non-blocking state of the given file descriptor, according to @nonblock. On most systems this uses %O_NONBLOCK, but on some older ones may use %O_NDELAY. - + %TRUE if successful + filename="glib/glib-unix.c" + line="157">%TRUE if successful A file descriptor + filename="glib/glib-unix.c" + line="149">A file descriptor If %TRUE, set the descriptor to be non-blocking + filename="glib/glib-unix.c" + line="150">If %TRUE, set the descriptor to be non-blocking @@ -83346,28 +88849,28 @@ on some older ones may use %O_NDELAY. version="2.30" introspectable="0"> A convenience function for g_unix_signal_source_new(), which + filename="glib/glib-unix.c" + line="267">A convenience function for g_unix_signal_source_new(), which attaches to the default #GMainContext. You can remove the watch using g_source_remove(). - + An ID (greater than 0) for the event source + filename="glib/glib-unix.c" + line="277">An ID (greater than 0) for the event source Signal number + filename="glib/glib-unix.c" + line="269">Signal number Callback + filename="glib/glib-unix.c" + line="270">Callback nullable="1" allow-none="1"> Data for @handler + filename="glib/glib-unix.c" + line="271">Data for @handler @@ -83386,29 +88889,29 @@ using g_source_remove(). shadows="unix_signal_add" version="2.30"> A convenience function for g_unix_signal_source_new(), which + filename="glib/glib-unix.c" + line="228">A convenience function for g_unix_signal_source_new(), which attaches to the default #GMainContext. You can remove the watch using g_source_remove(). - + An ID (greater than 0) for the event source + filename="glib/glib-unix.c" + line="241">An ID (greater than 0) for the event source the priority of the signal source. Typically this will be in + filename="glib/glib-unix.c" + line="230">the priority of the signal source. Typically this will be in the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. Signal number + filename="glib/glib-unix.c" + line="232">Signal number closure="3" destroy="4"> Callback + filename="glib/glib-unix.c" + line="233">Callback nullable="1" allow-none="1"> Data for @handler + filename="glib/glib-unix.c" + line="234">Data for @handler #GDestroyNotify for @handler + filename="glib/glib-unix.c" + line="235">#GDestroyNotify for @handler @@ -83442,8 +88945,8 @@ using g_source_remove(). c:identifier="g_unix_signal_source_new" version="2.30"> Create a #GSource that will be dispatched upon delivery of the UNIX + filename="glib/glib-unix.c" + line="186">Create a #GSource that will be dispatched upon delivery of the UNIX signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` were added. In GLib 2.54, `SIGWINCH` was added. @@ -83466,26 +88969,26 @@ functions like sigprocmask() is not defined. The source will not initially be associated with any #GMainContext and must be added to one with g_source_attach() before it will be executed. - + A newly created #GSource + filename="glib/glib-unix.c" + line="214">A newly created #GSource A signal number + filename="glib/glib-unix.c" + line="188">A signal number A wrapper for the POSIX unlink() function. The unlink() function + filename="glib/gstdio.c" + line="1400">A wrapper for the POSIX unlink() function. The unlink() function deletes a name from the filesystem. If this was the last link to the file and no processes have it opened, the diskspace occupied by the file is freed. @@ -83493,19 +88996,19 @@ file is freed. See your C library manual for more details about unlink(). Note that on Windows, it is in general not possible to delete files that are open to some process, or mapped into memory. - + 0 if the name was successfully deleted, -1 if an error + filename="glib/gstdio.c" + line="1414">0 if the name was successfully deleted, -1 if an error occurred a pathname in the GLib file name encoding + filename="glib/gstdio.c" + line="1402">a pathname in the GLib file name encoding (UTF-8 on Windows) @@ -83513,8 +89016,8 @@ are open to some process, or mapped into memory. Removes an environment variable from the environment. + filename="glib/genviron.c" + line="337">Removes an environment variable from the environment. Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. @@ -83531,15 +89034,15 @@ If you need to set up the environment for a child process, you can use g_get_environ() to get an environment array, modify that with g_environ_setenv() and g_environ_unsetenv(), and then pass that array directly to execvpe(), g_spawn_async(), or the like. - + the environment variable to remove, must + filename="glib/genviron.c" + line="339">the environment variable to remove, must not contain '=' @@ -83550,29 +89053,29 @@ array directly to execvpe(), g_spawn_async(), or the like. moved-to="Uri.build" version="2.66"> Creates a new #GUri from the given components according to @flags. + filename="glib/guri.c" + line="1860">Creates a new #GUri from the given components according to @flags. See also g_uri_build_with_user(), which allows specifying the components of the "userinfo" separately. - + a new #GUri + filename="glib/guri.c" + line="1876">a new #GUri flags describing how to build the #GUri + filename="glib/guri.c" + line="1862">flags describing how to build the #GUri the URI scheme + filename="glib/guri.c" + line="1863">the URI scheme nullable="1" allow-none="1"> the userinfo component, or %NULL + filename="glib/guri.c" + line="1864">the userinfo component, or %NULL nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1865">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1866">the port, or `-1` the path component + filename="glib/guri.c" + line="1867">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1868">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1869">the fragment, or %NULL @@ -83630,8 +89133,8 @@ components of the "userinfo" separately. moved-to="Uri.build_with_user" version="2.66"> Creates a new #GUri from the given components according to @flags + filename="glib/guri.c" + line="1909">Creates a new #GUri from the given components according to @flags (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be coherent with the passed values, in particular use `%`-encoded values with %G_URI_FLAGS_ENCODED. @@ -83639,24 +89142,24 @@ coherent with the passed values, in particular use `%`-encoded values with In contrast to g_uri_build(), this allows specifying the components of the ‘userinfo’ field separately. Note that @user must be non-%NULL if either @password or @auth_params is non-%NULL. - + a new #GUri + filename="glib/guri.c" + line="1931">a new #GUri flags describing how to build the #GUri + filename="glib/guri.c" + line="1911">flags describing how to build the #GUri the URI scheme + filename="glib/guri.c" + line="1912">the URI scheme nullable="1" allow-none="1"> the user component of the userinfo, or %NULL + filename="glib/guri.c" + line="1913">the user component of the userinfo, or %NULL nullable="1" allow-none="1"> the password component of the userinfo, or %NULL + filename="glib/guri.c" + line="1914">the password component of the userinfo, or %NULL nullable="1" allow-none="1"> the auth params of the userinfo, or %NULL + filename="glib/guri.c" + line="1915">the auth params of the userinfo, or %NULL nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1916">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1917">the port, or `-1` the path component + filename="glib/guri.c" + line="1918">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1919">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1920">the fragment, or %NULL @@ -83739,8 +89242,8 @@ if either @password or @auth_params is non-%NULL. moved-to="Uri.escape_bytes" version="2.66"> Escapes arbitrary data for use in a URI. + filename="glib/guri.c" + line="2779">Escapes arbitrary data for use in a URI. Normally all characters that are not ‘unreserved’ (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are @@ -83751,27 +89254,27 @@ portions of a URI. Though technically incorrect, this will also allow escaping nul bytes as `%``00`. - + an escaped version of @unescaped. + filename="glib/guri.c" + line="2798">an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input data. + filename="glib/guri.c" + line="2781">the unescaped input data. the length of @unescaped + filename="glib/guri.c" + line="2782">the length of @unescaped nullable="1" allow-none="1"> a string of reserved + filename="glib/guri.c" + line="2783">a string of reserved characters that are allowed to be used, or %NULL. @@ -83791,8 +89294,8 @@ bytes as `%``00`. moved-to="Uri.escape_string" version="2.16"> Escapes a string for use in a URI. + filename="glib/guri.c" + line="2688">Escapes a string for use in a URI. Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are @@ -83800,19 +89303,19 @@ escaped. But if you specify characters in @reserved_chars_allowed they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI. - + an escaped version of @unescaped. The + filename="glib/guri.c" + line="2704">an escaped version of @unescaped. The returned string should be freed when no longer needed. the unescaped input string. + filename="glib/guri.c" + line="2690">the unescaped input string. nullable="1" allow-none="1"> a string of reserved + filename="glib/guri.c" + line="2691">a string of reserved characters that are allowed to be used, or %NULL. %TRUE if the result can include UTF-8 characters. + filename="glib/guri.c" + line="2693">%TRUE if the result can include UTF-8 characters. @@ -83839,33 +89342,33 @@ returned string should be freed when no longer needed. version="2.66" throws="1"> Parses @uri_string according to @flags, to determine whether it is a valid -[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved + filename="glib/guri.c" + line="1247">Parses @uri_string according to @flags, to determine whether it is a valid +[absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved relative to another URI using g_uri_parse_relative(). If it’s not a valid URI, an error is returned explaining how it’s invalid. See g_uri_split(), and the definition of #GUriFlags, for more information on the effect of @flags. - + %TRUE if @uri_string is a valid absolute URI, %FALSE on error. + filename="glib/guri.c" + line="1262">%TRUE if @uri_string is a valid absolute URI, %FALSE on error. a string containing an absolute URI + filename="glib/guri.c" + line="1249">a string containing an absolute URI flags for parsing @uri_string + filename="glib/guri.c" + line="1250">flags for parsing @uri_string @@ -83875,8 +89378,8 @@ information on the effect of @flags. moved-to="Uri.join" version="2.66"> Joins the given components together according to @flags to create + filename="glib/guri.c" + line="1753">Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). @@ -83890,18 +89393,18 @@ components of the ‘userinfo’ separately. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. - + an absolute URI string + filename="glib/guri.c" + line="1779">an absolute URI string flags describing how to build the URI string + filename="glib/guri.c" + line="1755">flags describing how to build the URI string nullable="1" allow-none="1"> the URI scheme, or %NULL + filename="glib/guri.c" + line="1756">the URI scheme, or %NULL nullable="1" allow-none="1"> the userinfo component, or %NULL + filename="glib/guri.c" + line="1757">the userinfo component, or %NULL nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1758">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1759">the port, or `-1` the path component + filename="glib/guri.c" + line="1760">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1761">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1762">the fragment, or %NULL @@ -83968,8 +89471,8 @@ in @flags. moved-to="Uri.join_with_user" version="2.66"> Joins the given components together according to @flags to create + filename="glib/guri.c" + line="1806">Joins the given components together according to @flags to create an absolute URI string. @path may not be %NULL (though it may be the empty string). @@ -83978,18 +89481,18 @@ of the ‘userinfo’ separately. It otherwise behaves the same. %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set in @flags. - + an absolute URI string + filename="glib/guri.c" + line="1831">an absolute URI string flags describing how to build the URI string + filename="glib/guri.c" + line="1808">flags describing how to build the URI string nullable="1" allow-none="1"> the URI scheme, or %NULL + filename="glib/guri.c" + line="1809">the URI scheme, or %NULL nullable="1" allow-none="1"> the user component of the userinfo, or %NULL + filename="glib/guri.c" + line="1810">the user component of the userinfo, or %NULL nullable="1" allow-none="1"> the password component of the userinfo, or + filename="glib/guri.c" + line="1811">the password component of the userinfo, or %NULL @@ -84025,8 +89528,8 @@ in @flags. nullable="1" allow-none="1"> the auth params of the userinfo, or + filename="glib/guri.c" + line="1813">the auth params of the userinfo, or %NULL @@ -84035,20 +89538,20 @@ in @flags. nullable="1" allow-none="1"> the host component, or %NULL + filename="glib/guri.c" + line="1815">the host component, or %NULL the port, or `-1` + filename="glib/guri.c" + line="1816">the port, or `-1` the path component + filename="glib/guri.c" + line="1817">the path component nullable="1" allow-none="1"> the query component, or %NULL + filename="glib/guri.c" + line="1818">the query component, or %NULL nullable="1" allow-none="1"> the fragment, or %NULL + filename="glib/guri.c" + line="1819">the fragment, or %NULL @@ -84076,15 +89579,15 @@ in @flags. moved-to="Uri.list_extract_uris" version="2.6"> Splits an URI list conforming to the text/uri-list + filename="glib/gconvert.c" + line="1765">Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated. - + a newly allocated %NULL-terminated list + filename="glib/gconvert.c" + line="1773">a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev(). @@ -84094,8 +89597,8 @@ discarding any comments. The URIs are not validated. an URI list + filename="glib/gconvert.c" + line="1767">an URI list @@ -84106,28 +89609,28 @@ discarding any comments. The URIs are not validated. version="2.66" throws="1"> Parses @uri_string according to @flags. If the result is not a -valid [absolute URI][relative-absolute-uris], it will be discarded, and an + filename="glib/guri.c" + line="1385">Parses @uri_string according to @flags. If the result is not a +valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an error returned. - + a new #GUri, or NULL on error. + filename="glib/guri.c" + line="1395">a new #GUri, or NULL on error. a string representing an absolute URI + filename="glib/guri.c" + line="1387">a string representing an absolute URI flags describing how to parse @uri_string + filename="glib/guri.c" + line="1388">flags describing how to parse @uri_string @@ -84138,8 +89641,8 @@ error returned. version="2.66" throws="1"> Many URI schemes include one or more attribute/value pairs as part of the URI + filename="glib/guri.c" + line="2284">Many URI schemes include one or more attribute/value pairs as part of the URI value. This method can be used to parse them into a hash table. When an attribute has multiple occurrences, the last value is the final returned value. If you need to handle repeated attributes differently, use @@ -84163,11 +89666,11 @@ the returned attributes. If @params cannot be parsed (for example, it contains two @separators characters in a row), then @error is set and %NULL is returned. - + + filename="glib/guri.c" + line="2322"> A hash table of attribute/value pairs, with both names and values fully-decoded; or %NULL on error. @@ -84178,21 +89681,21 @@ characters in a row), then @error is set and %NULL is returned. a `%`-encoded string containing `attribute=value` + filename="glib/guri.c" + line="2286">a `%`-encoded string containing `attribute=value` parameters the length of @params, or `-1` if it is nul-terminated + filename="glib/guri.c" + line="2288">the length of @params, or `-1` if it is nul-terminated the separator byte character set between parameters. (usually + filename="glib/guri.c" + line="2289">the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case @@ -84201,8 +89704,8 @@ characters in a row), then @error is set and %NULL is returned. flags to modify the way the parameters are handled. + filename="glib/guri.c" + line="2294">flags to modify the way the parameters are handled. @@ -84212,27 +89715,27 @@ characters in a row), then @error is set and %NULL is returned. moved-to="Uri.parse_scheme" version="2.16"> Gets the scheme portion of a URI string. + filename="glib/guri.c" + line="2838">Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include `file`, `https`, `svn+ssh`, etc. - + The ‘scheme’ component of the URI, or + filename="glib/guri.c" + line="2850">The ‘scheme’ component of the URI, or %NULL on error. The returned string should be freed when no longer needed. a valid URI. + filename="glib/guri.c" + line="2840">a valid URI. @@ -84242,8 +89745,8 @@ Common schemes include `file`, `https`, `svn+ssh`, etc. moved-to="Uri.peek_scheme" version="2.66"> Gets the scheme portion of a URI string. + filename="glib/guri.c" + line="2866">Gets the scheme portion of a URI string. [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme as: |[ @@ -84253,11 +89756,11 @@ Common schemes include `file`, `https`, `svn+ssh`, etc. Unlike g_uri_parse_scheme(), the returned scheme is normalized to all-lowercase and does not need to be freed. - + The ‘scheme’ component of the URI, or + filename="glib/guri.c" + line="2881">The ‘scheme’ component of the URI, or %NULL on error. The returned string is normalized to all-lowercase, and interned via g_intern_string(), so it does not need to be freed. @@ -84265,8 +89768,8 @@ all-lowercase and does not need to be freed. a valid URI. + filename="glib/guri.c" + line="2868">a valid URI. @@ -84277,19 +89780,19 @@ all-lowercase and does not need to be freed. version="2.66" throws="1"> Parses @uri_ref according to @flags and, if it is a -[relative URI][relative-absolute-uris], resolves it relative to + filename="glib/guri.c" + line="1553">Parses @uri_ref according to @flags and, if it is a +[relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned. (If @base_uri_string is %NULL, this just returns @uri_ref, or %NULL if @uri_ref is invalid or not absolute.) - + the resolved URI string, + filename="glib/guri.c" + line="1568">the resolved URI string, or NULL on error. @@ -84299,20 +89802,20 @@ or NULL on error. nullable="1" allow-none="1"> a string representing a base URI + filename="glib/guri.c" + line="1555">a string representing a base URI a string representing a relative or absolute URI + filename="glib/guri.c" + line="1556">a string representing a relative or absolute URI flags describing how to parse @uri_ref + filename="glib/guri.c" + line="1557">flags describing how to parse @uri_ref @@ -84323,9 +89826,9 @@ or NULL on error. version="2.66" throws="1"> Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and + filename="glib/guri.c" + line="1045">Parses @uri_ref (which can be an +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -84340,25 +89843,25 @@ Note that the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), since it always returns only the full userinfo; use g_uri_split_with_user() if you want it split up. - + %TRUE if @uri_ref parsed successfully, %FALSE + filename="glib/guri.c" + line="1082">%TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI + filename="glib/guri.c" + line="1047">a string containing a relative or absolute URI flags for parsing @uri_ref + filename="glib/guri.c" + line="1048">flags for parsing @uri_ref optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1049">on return, contains the scheme (converted to lowercase), or %NULL @@ -84382,8 +89885,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1051">on return, contains the userinfo, or %NULL @@ -84395,8 +89898,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1053">on return, contains the host, or %NULL @@ -84407,8 +89910,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1055">on return, contains the port, or `-1` @@ -84419,8 +89922,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1057">on return, contains the path @@ -84432,8 +89935,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1059">on return, contains the query, or %NULL @@ -84445,8 +89948,8 @@ g_uri_split_with_user() if you want it split up. optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1061">on return, contains the fragment, or %NULL @@ -84458,32 +89961,32 @@ g_uri_split_with_user() if you want it split up. version="2.66" throws="1"> Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) + filename="glib/guri.c" + line="1173">Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces relevant to connecting to a host. See the documentation for g_uri_split() for more details; this is mostly a wrapper around that function with simpler arguments. However, it will return an error if @uri_string is a relative URI, or does not contain a hostname component. - + %TRUE if @uri_string parsed successfully, + filename="glib/guri.c" + line="1192">%TRUE if @uri_string parsed successfully, %FALSE on error. a string containing an absolute URI + filename="glib/guri.c" + line="1175">a string containing an absolute URI flags for parsing @uri_string + filename="glib/guri.c" + line="1176">flags for parsing @uri_string optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1177">on return, contains the scheme (converted to lowercase), or %NULL @@ -84507,8 +90010,8 @@ or does not contain a hostname component. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1179">on return, contains the host, or %NULL @@ -84519,8 +90022,8 @@ or does not contain a hostname component. optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1181">on return, contains the port, or `-1` @@ -84532,9 +90035,9 @@ or does not contain a hostname component. version="2.66" throws="1"> Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and + filename="glib/guri.c" + line="1108">Parses @uri_ref (which can be an +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -84544,25 +90047,25 @@ information on the effect of @flags. Note that @password will only be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and @auth_params will only be parsed out if @flags contains %G_URI_FLAGS_HAS_AUTH_PARAMS. - + %TRUE if @uri_ref parsed successfully, %FALSE + filename="glib/guri.c" + line="1144">%TRUE if @uri_ref parsed successfully, %FALSE on error. a string containing a relative or absolute URI + filename="glib/guri.c" + line="1110">a string containing a relative or absolute URI flags for parsing @uri_ref + filename="glib/guri.c" + line="1111">flags for parsing @uri_ref on return, contains + filename="glib/guri.c" + line="1112">on return, contains the scheme (converted to lowercase), or %NULL @@ -84586,8 +90089,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1114">on return, contains the user, or %NULL @@ -84599,8 +90102,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1116">on return, contains the password, or %NULL @@ -84612,8 +90115,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1118">on return, contains the auth_params, or %NULL @@ -84625,8 +90128,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1120">on return, contains the host, or %NULL @@ -84637,8 +90140,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1122">on return, contains the port, or `-1` @@ -84649,8 +90152,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1124">on return, contains the path @@ -84662,8 +90165,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains the + filename="glib/guri.c" + line="1126">on return, contains the query, or %NULL @@ -84675,8 +90178,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and optional="1" allow-none="1"> on return, contains + filename="glib/guri.c" + line="1128">on return, contains the fragment, or %NULL @@ -84688,8 +90191,8 @@ be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and version="2.66" throws="1"> Unescapes a segment of an escaped string as binary data. + filename="glib/guri.c" + line="2725">Unescapes a segment of an escaped string as binary data. Note that in contrast to g_uri_unescape_string(), this does allow nul bytes to appear in the output. @@ -84699,11 +90202,11 @@ character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - + an unescaped version of @escaped_string + filename="glib/guri.c" + line="2745">an unescaped version of @escaped_string or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error code). The returned #GBytes should be unreffed when no longer needed. @@ -84711,14 +90214,14 @@ handling. A URI-escaped string + filename="glib/guri.c" + line="2727">A URI-escaped string the length (in bytes) of @escaped_string to escape, or `-1` if it + filename="glib/guri.c" + line="2728">the length (in bytes) of @escaped_string to escape, or `-1` if it is nul-terminated. @@ -84727,8 +90230,8 @@ handling. nullable="1" allow-none="1"> a string of illegal characters + filename="glib/guri.c" + line="2730">a string of illegal characters not to be allowed, or %NULL. @@ -84739,8 +90242,8 @@ handling. moved-to="Uri.unescape_segment" version="2.16"> Unescapes a segment of an escaped string. + filename="glib/guri.c" + line="2601">Unescapes a segment of an escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then @@ -84750,11 +90253,11 @@ escaped path element, which might confuse pathname handling. Note: `NUL` byte is not accepted in the output, in contrast to g_uri_unescape_bytes(). - + an unescaped version of @escaped_string, + filename="glib/guri.c" + line="2620">an unescaped version of @escaped_string, or %NULL on error. The returned string should be freed when no longer needed. As a special case if %NULL is given for @escaped_string, this function will return %NULL. @@ -84766,8 +90269,8 @@ function will return %NULL. nullable="1" allow-none="1"> A string, may be %NULL + filename="glib/guri.c" + line="2603">A string, may be %NULL nullable="1" allow-none="1"> Pointer to end of @escaped_string, + filename="glib/guri.c" + line="2604">Pointer to end of @escaped_string, may be %NULL @@ -84785,8 +90288,8 @@ function will return %NULL. nullable="1" allow-none="1"> An optional string of illegal + filename="glib/guri.c" + line="2606">An optional string of illegal characters not to be allowed, may be %NULL @@ -84797,27 +90300,27 @@ function will return %NULL. moved-to="Uri.unescape_string" version="2.16"> Unescapes a whole escaped string. + filename="glib/guri.c" + line="2662">Unescapes a whole escaped string. If any of the characters in @illegal_characters or the NUL character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - + an unescaped version of @escaped_string. + filename="glib/guri.c" + line="2676">an unescaped version of @escaped_string. The returned string should be freed when no longer needed. an escaped string to be unescaped. + filename="glib/guri.c" + line="2664">an escaped string to be unescaped. nullable="1" allow-none="1"> a string of illegal characters + filename="glib/guri.c" + line="2665">a string of illegal characters not to be allowed, or %NULL. @@ -84834,54 +90337,54 @@ The returned string should be freed when no longer needed. Pauses the current thread for the given number of microseconds. + filename="glib/gtimer.c" + line="251">Pauses the current thread for the given number of microseconds. There are 1 million microseconds per second (represented by the %G_USEC_PER_SEC macro). g_usleep() may have limited precision, depending on hardware and operating system; don't rely on the exact length of the sleep. - + number of microseconds to pause + filename="glib/gtimer.c" + line="253">number of microseconds to pause Convert a string from UTF-16 to UCS-4. The result will be -nul-terminated. - + filename="glib/gutf8.c" + line="1229">Convert a string from UTF-16 to UCS-4. + +The result will be nul-terminated. + a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + filename="glib/gutf8.c" + line="1249">a pointer to a newly allocated UCS-4 string. + This value must be freed with [func@GLib.free]. a UTF-16 encoded string + filename="glib/gutf8.c" + line="1231">a UTF-16 encoded string the maximum length (number of #gunichar2) of @str to use. - If @len < 0, then the string is nul-terminated. + filename="glib/gutf8.c" + line="1232">the maximum length (number of #gunichar2) of @str to use. + If @len is negative, then the string is nul-terminated. optional="1" allow-none="1"> location to store number of - words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. + filename="glib/gutf8.c" + line="1234">location to store number of words read, or + `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be + returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. optional="1" allow-none="1"> location to store number - of characters written, or %NULL. The value stored here does not include - the trailing 0 character. + filename="glib/gutf8.c" + line="1238">location to store number + of characters written, or `NULL`. The value stored here does not include + the trailing nul character. Convert a string from UTF-16 to UTF-8. The result will be -terminated with a 0 byte. + filename="glib/gutf8.c" + line="1073">Convert a string from UTF-16 to UTF-8. + +The result will be terminated with a nul byte. Note that the input is expected to be already in native endianness, an initial byte-order-mark character is not handled specially. -g_convert() can be used to convert a byte buffer of UTF-16 data of +[func@GLib.convert] can be used to convert a byte buffer of UTF-16 data of ambiguous endianness. Further note that this function does not validate the result -string; it may e.g. include embedded NUL characters. The only +string; it may (for example) include embedded nul characters. The only validation done by this function is to ensure that the input can -be correctly interpreted as UTF-16, i.e. it doesn't contain +be correctly interpreted as UTF-16, i.e. it doesn’t contain unpaired surrogates or partial character sequences. - + a pointer to a newly allocated UTF-8 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + filename="glib/gutf8.c" + line="1105">a pointer to a newly allocated UTF-8 string. + This value must be freed with [func@GLib.free]. a UTF-16 encoded string + filename="glib/gutf8.c" + line="1075">a UTF-16 encoded string the maximum length (number of #gunichar2) of @str to use. - If @len < 0, then the string is nul-terminated. + filename="glib/gutf8.c" + line="1076">the maximum length (number of #gunichar2) of @str to use. + If @len is negative, then the string is nul-terminated. optional="1" allow-none="1"> location to store number of - words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. - It’s guaranteed to be non-negative. + filename="glib/gutf8.c" + line="1078">location to store number of words read, or + `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. + It’s guaranteed to be non-negative. optional="1" allow-none="1"> location to store number - of bytes written, or %NULL. The value stored here does not include the - trailing 0 byte. It’s guaranteed to be non-negative. + filename="glib/gutf8.c" + line="1083">location to store number + of bytes written, or `NULL`. The value stored here does not include the + trailing nul byte. It’s guaranteed to be non-negative. Converts a string into a form that is independent of case. The + filename="glib/guniprop.c" + line="1169">Converts a string into a form that is independent of case. The result will not correspond to any particular case, but can be compared for equality or ordered with the results of calling g_utf8_casefold() on other strings. @@ -84998,34 +90501,34 @@ ordering, though it is a fairly good one. Getting this exactly right would require a more sophisticated collation function that takes case sensitivity into account. GLib does not currently provide such a function. - + a newly allocated string, that is a + filename="glib/guniprop.c" + line="1186">a newly allocated string, that is a case independent form of @str. a UTF-8 encoded string + filename="glib/guniprop.c" + line="1171">a UTF-8 encoded string length of @str, in bytes, or -1 if @str is nul-terminated. + filename="glib/guniprop.c" + line="1172">length of @str, in bytes, or -1 if @str is nul-terminated. Compares two strings for ordering using the linguistically -correct rules for the [current locale][setlocale]. + filename="glib/gunicollate.c" + line="64">Compares two strings for ordering using the linguistically +correct rules for the [current locale](running.html#locale). When sorting a large number of strings, it will be significantly faster to obtain collation keys with g_utf8_collate_key() and compare the keys with strcmp() when sorting instead of sorting @@ -85034,33 +90537,33 @@ the original strings. If the two strings are not comparable due to being in different collation sequences, the result is undefined. This can happen if the strings are in different language scripts, for example. - + < 0 if @str1 compares before @str2, + filename="glib/gunicollate.c" + line="80">< 0 if @str1 compares before @str2, 0 if they compare equal, > 0 if @str1 compares after @str2. a UTF-8 encoded string + filename="glib/gunicollate.c" + line="66">a UTF-8 encoded string a UTF-8 encoded string + filename="glib/gunicollate.c" + line="67">a UTF-8 encoded string Converts a string into a collation key that can be compared + filename="glib/gunicollate.c" + line="363">Converts a string into a collation key that can be compared with other collation keys produced by the same function using strcmp(). @@ -85068,26 +90571,31 @@ The results of comparing the collation keys of two strings with strcmp() will always be the same as comparing the two original keys with g_utf8_collate(). -Note that this function depends on the [current locale][setlocale]. - +Note that this function depends on the [current locale](running.html#locale). + +Note that the returned string is not guaranteed to be in any +encoding, especially UTF-8. The returned value is meant to be +used only for comparisons. + a newly allocated string. This string should - be freed with g_free() when you are done with it. - + filename="glib/gunicollate.c" + line="382">a newly allocated string. + The contents of the string are only meant to be used when sorting. + This string should be freed with g_free() when you are done with it. + a UTF-8 encoded string. + filename="glib/gunicollate.c" + line="365">a UTF-8 encoded string. length of @str, in bytes, or -1 if @str is nul-terminated. + filename="glib/gunicollate.c" + line="366">length of @str, in bytes, or -1 if @str is nul-terminated. @@ -85096,8 +90604,8 @@ Note that this function depends on the [current locale][setlocale]. c:identifier="g_utf8_collate_key_for_filename" version="2.8"> Converts a string into a collation key that can be compared + filename="glib/gunicollate.c" + line="495">Converts a string into a collation key that can be compared with other collation keys produced by the same function using strcmp(). In order to sort filenames correctly, this function treats the dot '.' @@ -85107,56 +90615,61 @@ insignificant, thus producing the ordering "event.c" "eventgenerator.c" would like to treat numbers intelligently so that "file1" "file10" "file5" is sorted as "file1" "file5" "file10". -Note that this function depends on the [current locale][setlocale]. - +Note that this function depends on the [current locale](running.html#locale). + +Note that the returned string is not guaranteed to be in any +encoding, especially UTF-8. The returned value is meant to be +used only for comparisons. + a newly allocated string. This string should - be freed with g_free() when you are done with it. - + filename="glib/gunicollate.c" + line="516">a newly allocated string. + The contents of the string are only meant to be used when sorting. + This string should be freed with g_free() when you are done with it. + a UTF-8 encoded string. + filename="glib/gunicollate.c" + line="497">a UTF-8 encoded string. length of @str, in bytes, or -1 if @str is nul-terminated. + filename="glib/gunicollate.c" + line="498">length of @str, in bytes, or -1 if @str is nul-terminated. Finds the start of the next UTF-8 character in the string after @p. + filename="glib/gutf8.c" + line="156">Finds the start of the next UTF-8 character in the string after @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. -If @end is %NULL, the return value will never be %NULL: if the end of the +If @end is `NULL`, the return value will never be `NULL`: if the end of the string is reached, a pointer to the terminating nul byte is returned. If -@end is non-%NULL, the return value will be %NULL if the end of the string +@end is non-`NULL`, the return value will be `NULL` if the end of the string is reached. - + a pointer to the found character or %NULL if @end is + filename="glib/gutf8.c" + line="173">a pointer to the found character or `NULL` if @end is set and is reached a pointer to a position within a UTF-8 encoded string + filename="glib/gutf8.c" + line="158">a pointer to a position within a UTF-8 encoded string nullable="1" allow-none="1"> a pointer to the byte following the end of the string, - or %NULL to indicate that the string is nul-terminated + filename="glib/gutf8.c" + line="159">a pointer to the byte following the end of the string, + or `NULL` to indicate that the string is nul-terminated Given a position @p with a UTF-8 encoded string @str, find the start -of the previous UTF-8 character starting before @p. Returns %NULL if no + filename="glib/gutf8.c" + line="128">Given a position @p with a UTF-8 encoded string @str, find the start +of the previous UTF-8 character starting before @p. Returns `NULL` if no UTF-8 characters are present in @str before @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. - + a pointer to the found character or %NULL. + filename="glib/gutf8.c" + line="141">a pointer to the found character pointer to the beginning of a UTF-8 encoded string + filename="glib/gutf8.c" + line="130">pointer to the beginning of a UTF-8 encoded string pointer to some position within @str + filename="glib/gutf8.c" + line="131">pointer to some position within @str Converts a sequence of bytes encoded as UTF-8 to a Unicode character. + filename="glib/gutf8.c" + line="319">Converts a sequence of bytes encoded as UTF-8 to a Unicode character. If @p does not point to a valid UTF-8 encoded character, results are undefined. If you are not sure that the bytes are complete -valid Unicode characters, you should use g_utf8_get_char_validated() +valid Unicode characters, you should use [func@GLib.utf8_get_char_validated] instead. - + the resulting character + filename="glib/gutf8.c" + line="330">the resulting character a pointer to Unicode character encoded as UTF-8 + filename="glib/gutf8.c" + line="321">a pointer to Unicode character encoded as UTF-8 @@ -85231,37 +90744,38 @@ instead. Convert a sequence of bytes encoded as UTF-8 to a Unicode character. + filename="glib/gutf8.c" + line="746">Convert a sequence of bytes encoded as UTF-8 to a Unicode character. + This function checks for incomplete characters, for invalid characters such as characters that are out of the range of Unicode, and for overlong encodings of valid characters. -Note that g_utf8_get_char_validated() returns (gunichar)-2 if +Note that [func@GLib.utf8_get_char_validated] returns `(gunichar)-2` if @max_len is positive and any of the bytes in the first UTF-8 character sequence are nul. - + the resulting character. If @p points to a partial - sequence at the end of a string that could begin a valid - character (or if @max_len is zero), returns (gunichar)-2; - otherwise, if @p does not point to a valid UTF-8 encoded - Unicode character, returns (gunichar)-1. + filename="glib/gutf8.c" + line="761">the resulting character. If @p points to a partial + sequence at the end of a string that could begin a valid + character (or if @max_len is zero), returns `(gunichar)-2`; + otherwise, if @p does not point to a valid UTF-8 encoded + Unicode character, returns `(gunichar)-1`. a pointer to Unicode character encoded as UTF-8 + filename="glib/gutf8.c" + line="748">a pointer to Unicode character encoded as UTF-8 the maximum number of bytes to read, or -1 if @p is nul-terminated + filename="glib/gutf8.c" + line="749">the maximum number of bytes to read, or `-1` if @p is nul-terminated @@ -85270,8 +90784,8 @@ sequence are nul. c:identifier="g_utf8_make_valid" version="2.52"> If the provided string is valid UTF-8, return a copy of it. If not, + filename="glib/gutf8.c" + line="1979">If the provided string is valid UTF-8, return a copy of it. If not, return a copy in which bytes that could not be interpreted as valid Unicode are replaced with the Unicode replacement character (U+FFFD). @@ -85280,25 +90794,25 @@ a string that was incorrectly declared to be UTF-8, and you need a valid UTF-8 version of it that can be logged or displayed to the user, with the assumption that it is close enough to ASCII or UTF-8 to be mostly readable as-is. - + a valid UTF-8 string whose content resembles @str + filename="glib/gutf8.c" + line="1995">a valid UTF-8 string whose content resembles @str string to coerce into UTF-8 + filename="glib/gutf8.c" + line="1981">string to coerce into UTF-8 the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + filename="glib/gutf8.c" + line="1982">the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. @@ -85307,8 +90821,8 @@ readable as-is. c:identifier="g_utf8_next_char" introspectable="0"> Skips to the next character in a UTF-8 string. + filename="glib/gunicode.h" + line="809">Skips to the next character in a UTF-8 string. The string must be valid; this macro is as fast as possible, and has no error-checking. @@ -85319,19 +90833,19 @@ The macro returns the start of the next UTF-8 character. Before using this macro, use g_utf8_validate() to validate strings that may contain invalid UTF-8. - + Pointer to the start of a valid UTF-8 character + filename="glib/gunicode.h" + line="811">Pointer to the start of a valid UTF-8 character Converts a string into canonical form, standardizing + filename="glib/gunidecomp.c" + line="513">Converts a string into canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. The @@ -85356,11 +90870,11 @@ than a maximally decomposed form. This is often useful if you intend to convert the string to a legacy encoding or pass it to a system with less capable Unicode handling. - + a newly allocated string, that + filename="glib/gunidecomp.c" + line="545">a newly allocated string, that is the normalized form of @str, or %NULL if @str is not valid UTF-8. @@ -85368,20 +90882,20 @@ less capable Unicode handling. a UTF-8 encoded string. + filename="glib/gunidecomp.c" + line="515">a UTF-8 encoded string. length of @str, in bytes, or -1 if @str is nul-terminated. + filename="glib/gunidecomp.c" + line="516">length of @str, in bytes, or -1 if @str is nul-terminated. the type of normalization to perform. + filename="glib/gunidecomp.c" + line="517">the type of normalization to perform. @@ -85389,8 +90903,8 @@ less capable Unicode handling. Converts from an integer character offset to a pointer to a position + filename="glib/gutf8.c" + line="347">Converts from an integer character offset to a pointer to a position within the string. Since 2.10, this function allows to pass a negative @offset to @@ -85398,29 +90912,29 @@ step backwards. It is usually worth stepping backwards from the end instead of forwards if @offset is in the last fourth of the string, since moving forward is about 3 times faster than moving backward. -Note that this function doesn't abort when reaching the end of @str. +Note that this function doesn’t abort when reaching the end of @str. Therefore you should be sure that @offset is within string boundaries -before calling that function. Call g_utf8_strlen() when unsure. +before calling that function. Call [func@GLib.utf8_strlen] when unsure. This limitation exists as this function is called frequently during text rendering and therefore has to be as fast as possible. - + the resulting pointer + filename="glib/gutf8.c" + line="366">the resulting pointer a UTF-8 encoded string + filename="glib/gutf8.c" + line="349">a UTF-8 encoded string a character offset within @str + filename="glib/gutf8.c" + line="350">a character offset within @str @@ -85428,227 +90942,232 @@ text rendering and therefore has to be as fast as possible. Converts from a pointer to position within a string to an integer + filename="glib/gutf8.c" + line="399">Converts from a pointer to position within a string to an integer character offset. Since 2.10, this function allows @pos to be before @str, and returns a negative offset in this case. - + the resulting character offset + filename="glib/gutf8.c" + line="410">the resulting character offset a UTF-8 encoded string + filename="glib/gutf8.c" + line="401">a UTF-8 encoded string a pointer to a position within @str + filename="glib/gutf8.c" + line="402">a pointer to a position within @str Finds the previous UTF-8 character in the string before @p. + filename="glib/gutf8.c" + line="194">Finds the previous UTF-8 character in the string before @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. If @p might be the first -character of the string, you must use g_utf8_find_prev_char() instead. - +character of the string, you must use [func@GLib.utf8_find_prev_char] +instead. + a pointer to the found character + filename="glib/gutf8.c" + line="206">a pointer to the found character a pointer to a position within a UTF-8 encoded string + filename="glib/gutf8.c" + line="196">a pointer to a position within a UTF-8 encoded string Finds the leftmost occurrence of the given Unicode character + filename="glib/gutf8.c" + line="598">Finds the leftmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to @len bytes. -If @len is -1, allow unbounded search. - + +If @len is `-1`, allow unbounded search. + %NULL if the string does not contain the character, - otherwise, a pointer to the start of the leftmost occurrence - of the character in the string. + filename="glib/gutf8.c" + line="609">`NULL` if the string does not contain + the character, otherwise, a pointer to the start of the leftmost occurrence + of the character in the string. a nul-terminated UTF-8 encoded string + filename="glib/gutf8.c" + line="600">a nul-terminated UTF-8 encoded string the maximum length of @p + filename="glib/gutf8.c" + line="601">the maximum length of @p a Unicode character + filename="glib/gutf8.c" + line="602">a Unicode character Converts all Unicode characters in the string that have a case + filename="glib/guniprop.c" + line="1133">Converts all Unicode characters in the string that have a case to lowercase. The exact manner that this is done depends on the current locale, and may result in the number of characters in the string changing. - + a newly allocated string, with all characters + filename="glib/guniprop.c" + line="1143">a newly allocated string, with all characters converted to lowercase. a UTF-8 encoded string + filename="glib/guniprop.c" + line="1135">a UTF-8 encoded string length of @str, in bytes, or -1 if @str is nul-terminated. + filename="glib/guniprop.c" + line="1136">length of @str, in bytes, or -1 if @str is nul-terminated. Computes the length of the string in characters, not including -the terminating nul character. If the @max'th byte falls in the + filename="glib/gutf8.c" + line="219">Computes the length of the string in characters, not including +the terminating nul character. If the @max’th byte falls in the middle of a character, the last (partial) character is not counted. - + the length of the string in characters + filename="glib/gutf8.c" + line="232">the length of the string in characters pointer to the start of a UTF-8 encoded string + filename="glib/gutf8.c" + line="221">pointer to the start of a UTF-8 encoded string the maximum number of bytes to examine. If @max - is less than 0, then the string is assumed to be - nul-terminated. If @max is 0, @p will not be examined and - may be %NULL. If @max is greater than 0, up to @max - bytes are examined + filename="glib/gutf8.c" + line="222">the maximum number of bytes to examine. If @max + is less than 0, then the string is assumed to be + nul-terminated. If @max is 0, @p will not be examined and + may be `NULL`. If @max is greater than 0, up to @max + bytes are examined Like the standard C strncpy() function, but copies a given number -of characters instead of a given number of bytes. The @src string -must be valid UTF-8 encoded text. (Use g_utf8_validate() on all -text before trying to use UTF-8 utility functions with it.) + filename="glib/gutf8.c" + line="432">Like the standard C [`strncpy()`](man:strncpy) function, but copies a given +number of characters instead of a given number of bytes. + +The @src string must be valid UTF-8 encoded text. (Use +[func@GLib.utf8_validate] on all text before trying to use UTF-8 utility +functions with it.) Note you must ensure @dest is at least 4 * @n + 1 to fit the largest possible UTF-8 characters - + @dest + filename="glib/gutf8.c" + line="448">@dest buffer to fill with characters from @src + filename="glib/gutf8.c" + line="434">buffer to fill with characters from @src UTF-8 encoded string + filename="glib/gutf8.c" + line="435">UTF-8 encoded string character count + filename="glib/gutf8.c" + line="436">character count Find the rightmost occurrence of the given Unicode character + filename="glib/gutf8.c" + line="627">Find the rightmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to @len bytes. -If @len is -1, allow unbounded search. - + +If @len is `-1`, allow unbounded search. + %NULL if the string does not contain the character, - otherwise, a pointer to the start of the rightmost occurrence - of the character in the string. + filename="glib/gutf8.c" + line="638">`NULL` if the string does not contain + the character, otherwise, a pointer to the start of the rightmost + occurrence of the character in the string. a nul-terminated UTF-8 encoded string + filename="glib/gutf8.c" + line="629">a nul-terminated UTF-8 encoded string the maximum length of @p + filename="glib/gutf8.c" + line="630">the maximum length of @p a Unicode character + filename="glib/gutf8.c" + line="631">a Unicode character @@ -85657,10 +91176,11 @@ If @len is -1, allow unbounded search. c:identifier="g_utf8_strreverse" version="2.2"> Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. -(Use g_utf8_validate() on all text before trying to use UTF-8 -utility functions with it.) + filename="glib/gutf8.c" + line="1928">Reverses a UTF-8 string. + +@str must be valid UTF-8 encoded text. (Use [func@GLib.utf8_validate] on all +text before trying to use UTF-8 utility functions with it.) This function is intended for programmatic uses of reversed strings. It pays no attention to decomposed characters, combining marks, byte @@ -85668,59 +91188,59 @@ order marks, directional indicators (LRM, LRO, etc) and similar characters which might need special handling when reversing a string for display purposes. -Note that unlike g_strreverse(), this function returns -newly-allocated memory, which should be freed with g_free() when +Note that unlike [func@GLib.strreverse], this function returns +newly-allocated memory, which should be freed with [func@GLib.free] when no longer needed. - + a newly-allocated string which is the reverse of @str + filename="glib/gutf8.c" + line="1949">a newly-allocated string which is the reverse of @str a UTF-8 encoded string + filename="glib/gutf8.c" + line="1930">a UTF-8 encoded string the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + filename="glib/gutf8.c" + line="1931">the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. Converts all Unicode characters in the string that have a case + filename="glib/guniprop.c" + line="938">Converts all Unicode characters in the string that have a case to uppercase. The exact manner that this is done depends on the current locale, and may result in the number of characters in the string increasing. (For instance, the German ess-zet will be changed to SS.) - + a newly allocated string, with all characters + filename="glib/guniprop.c" + line="949">a newly allocated string, with all characters converted to uppercase. a UTF-8 encoded string + filename="glib/guniprop.c" + line="940">a UTF-8 encoded string length of @str, in bytes, or -1 if @str is nul-terminated. + filename="glib/guniprop.c" + line="941">length of @str, in bytes, or -1 if @str is nul-terminated. @@ -85729,37 +91249,37 @@ German ess-zet will be changed to SS.) c:identifier="g_utf8_substring" version="2.30"> Copies a substring out of a UTF-8 encoded string. + filename="glib/gutf8.c" + line="273">Copies a substring out of a UTF-8 encoded string. The substring will contain @end_pos - @start_pos characters. Since GLib 2.72, `-1` can be passed to @end_pos to indicate the end of the string. - + a newly allocated copy of the requested - substring. Free with g_free() when no longer needed. + filename="glib/gutf8.c" + line="286">a newly allocated copy of the requested + substring. Free with [func@GLib.free] when no longer needed. a UTF-8 encoded string + filename="glib/gutf8.c" + line="275">a UTF-8 encoded string a character offset within @str + filename="glib/gutf8.c" + line="276">a character offset within @str another character offset within @str, + filename="glib/gutf8.c" + line="277">another character offset within @str, or `-1` to indicate the end of the string @@ -85767,31 +91287,31 @@ end of the string. Convert a string from UTF-8 to a 32-bit fixed width -representation as UCS-4. A trailing 0 character will be added to the -string after the converted text. - + filename="glib/gutf8.c" + line="911">Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4. + +A trailing nul character (U+0000) will be added to the string after the +converted text. + a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + filename="glib/gutf8.c" + line="934">a pointer to a newly allocated UCS-4 string. + This value must be freed with [func@GLib.free]. a UTF-8 encoded string + filename="glib/gutf8.c" + line="913">a UTF-8 encoded string the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + filename="glib/gutf8.c" + line="914">the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. optional="1" allow-none="1"> location to store number of - bytes read, or %NULL. - If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - returned in case @str contains a trailing partial - character. If an error occurs then the index of the - invalid input is stored here. + filename="glib/gutf8.c" + line="916">location to store number of + bytes read, or `NULL`. + If `NULL`, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + returned in case @str contains a trailing partial + character. If an error occurs then the index of the + invalid input is stored here. optional="1" allow-none="1"> location to store number - of characters written or %NULL. The value here stored does not include - the trailing 0 character. + filename="glib/gutf8.c" + line="922">location to store number + of characters written or `NULL`. The value here stored does not include + the trailing nul character. Convert a string from UTF-8 to a 32-bit fixed width + filename="glib/gutf8.c" + line="793">Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4, assuming valid UTF-8 input. -This function is roughly twice as fast as g_utf8_to_ucs4() -but does no error checking on the input. A trailing 0 character + +This function is roughly twice as fast as [func@GLib.utf8_to_ucs4] +but does no error checking on the input. A trailing nul character (U+0000) will be added to the string after the converted text. - + a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). + filename="glib/gutf8.c" + line="808">a pointer to a newly allocated UCS-4 string. + This value must be freed with [func@GLib.free]. a UTF-8 encoded string + filename="glib/gutf8.c" + line="795">a UTF-8 encoded string the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + filename="glib/gutf8.c" + line="796">the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. optional="1" allow-none="1"> location to store the - number of characters in the result, or %NULL. + filename="glib/gutf8.c" + line="798">location to store the + number of characters in the result, or `NULL`. Convert a string from UTF-8 to UTF-16. A 0 character will be -added to the result after the converted text. - + filename="glib/gutf8.c" + line="1367">Convert a string from UTF-8 to UTF-16. + +A nul character (U+0000) will be added to the result after the converted text. + a pointer to a newly allocated UTF-16 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + filename="glib/gutf8.c" + line="1387">a pointer to a newly allocated UTF-16 string. + This value must be freed with [func@GLib.free]. a UTF-8 encoded string + filename="glib/gutf8.c" + line="1369">a UTF-8 encoded string the maximum length (number of bytes) of @str to use. - If @len < 0, then the string is nul-terminated. + filename="glib/gutf8.c" + line="1370">the maximum length (number of bytes) of @str to use. + If @len is negative, then the string is nul-terminated. optional="1" allow-none="1"> location to store number of - bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. + filename="glib/gutf8.c" + line="1372">location to store number of bytes read, or + `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. optional="1" allow-none="1"> location to store number - of #gunichar2 written, or %NULL. The value stored here does not include - the trailing 0. + filename="glib/gutf8.c" + line="1376">location to store number + of `gunichar2` written, or `NULL`. The value stored here does not include + the trailing nul. @@ -85930,72 +91451,74 @@ added to the result after the converted text. c:identifier="g_utf8_truncate_middle" version="2.78"> Cuts off the middle of the string, preserving half of @truncate_length + filename="glib/gutf8.c" + line="466">Cuts off the middle of the string, preserving half of @truncate_length characters at the beginning and half at the end. If @string is already short enough, this returns a copy of @string. If @truncate_length is `0`, an empty string is returned. - + a newly-allocated copy of @string ellipsized in the middle + filename="glib/gutf8.c" + line="477">a newly-allocated copy of @string ellipsized in the middle a nul-terminated UTF-8 encoded string + filename="glib/gutf8.c" + line="468">a nul-terminated UTF-8 encoded string the new size of @string, in characters, including the ellipsis character + filename="glib/gutf8.c" + line="469">the new size of @string, in characters, including the ellipsis character Validates UTF-8 encoded text. @str is the text to validate; -if @str is nul-terminated, then @max_len can be -1, otherwise -@max_len should be the number of bytes to validate. -If @end is non-%NULL, then the end of the valid range -will be stored there (i.e. the start of the first invalid -character if some bytes were invalid, or the end of the text -being validated otherwise). + filename="glib/gutf8.c" + line="1828">Validates UTF-8 encoded text. + +@str is the text to validate; if @str is nul-terminated, then @max_len can be +`-1`, otherwise @max_len should be the number of bytes to validate. -Note that g_utf8_validate() returns %FALSE if @max_len is -positive and any of the @max_len bytes are nul. +If @end is non-`NULL`, then the end of the valid range will be stored there. +This is the first byte of the first invalid character if some bytes were +invalid, or the end of the text being validated otherwise — either the +trailing nul byte, or the first byte beyond @max_len (if it’s positive). -Returns %TRUE if all of @str was valid. Many GLib and GTK +Note that `g_utf8_validate()` returns `FALSE` if @max_len is positive and +any of the @max_len bytes are nul. + +Returns `TRUE` if all of @str was valid. Many GLib and GTK routines require valid UTF-8 as input; so data read from a file -or the network should be checked with g_utf8_validate() before +or the network should be checked with `g_utf8_validate()` before doing anything else with it. - + %TRUE if the text was valid UTF-8 + filename="glib/gutf8.c" + line="1852">`TRUE` if the text was valid UTF-8 a pointer to character data + filename="glib/gutf8.c" + line="1830">a pointer to character data max bytes to validate, or -1 to go until NUL + filename="glib/gutf8.c" + line="1831">max bytes to validate, or `-1` to go until nul optional="1" allow-none="1"> return location for end of valid data + filename="glib/gutf8.c" + line="1832">return location for end of valid data @@ -86015,31 +91538,31 @@ doing anything else with it. c:identifier="g_utf8_validate_len" version="2.60"> Validates UTF-8 encoded text. + filename="glib/gutf8.c" + line="1864">Validates UTF-8 encoded text. -As with g_utf8_validate(), but @max_len must be set, and hence this function -will always return %FALSE if any of the bytes of @str are nul. - +As with [func@GLib.utf8_validate], but @max_len must be set, and hence this +function will always return `FALSE` if any of the bytes of @str are nul. + %TRUE if the text was valid UTF-8 + filename="glib/gutf8.c" + line="1875">`TRUE` if the text was valid UTF-8 a pointer to character data + filename="glib/gutf8.c" + line="1866">a pointer to character data max bytes to validate + filename="glib/gutf8.c" + line="1867">max bytes to validate optional="1" allow-none="1"> return location for end of valid data + filename="glib/gutf8.c" + line="1868">return location for end of valid data - + A UUID, or Universally unique identifier, is intended to uniquely -identify information in a distributed environment. For the -definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). - -The creation of UUIDs does not require a centralized authority. - -UUIDs are of relatively small size (128 bits, or 16 bytes). The -common string representation (ex: -1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. + filename="glib/gstdio.c" + line="1704">A wrapper for the POSIX utime() function. The utime() function +sets the access and modification timestamps of a file. -The UUID specification defines 5 versions, and calling -g_uuid_string_random() will generate a unique (or rather random) -UUID of the most common version, version 4. - +See your C library manual for more details about how utime() works +on your system. + + + 0 if the operation was successful, -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pointer to a struct utimbuf. + + + + Parses the string @str and verify if it is a UUID. + filename="glib/guuid.c" + line="103">Parses the string @str and verify if it is a UUID. The function accepts the following syntax: @@ -86085,18 +91625,18 @@ The function accepts the following syntax: Note that hyphens are required within the UUID string itself, as per the aforementioned RFC. - + %TRUE if @str is a valid UUID, %FALSE otherwise. + filename="glib/guuid.c" + line="116">%TRUE if @str is a valid UUID, %FALSE otherwise. a string representing a UUID + filename="glib/guuid.c" + line="105">a string representing a UUID @@ -86105,20 +91645,20 @@ as per the aforementioned RFC. c:identifier="g_uuid_string_random" version="2.52"> Generates a random UUID (RFC 4122 version 4) as a string. It has the same + filename="glib/guuid.c" + line="171">Generates a random UUID (RFC 4122 version 4) as a string. It has the same randomness guarantees as #GRand, so must not be used for cryptographic purposes such as key generation, nonces, salts or one-time pads. - + A string that should be freed with g_free(). + filename="glib/guuid.c" + line="178">A string that should be freed with g_free(). - + @@ -86128,8 +91668,8 @@ purposes such as key generation, nonces, salts or one-time pads. moved-to="Variant.is_object_path" version="2.24"> Determines if a given string is a valid D-Bus object path. You + filename="glib/gvariant.c" + line="1377">Determines if a given string is a valid D-Bus object path. You should ensure that a string is a valid D-Bus object path before passing it to g_variant_new_object_path(). @@ -86137,18 +91677,18 @@ A valid object path starts with `/` followed by zero or more sequences of characters separated by `/` characters. Each sequence must contain only the characters `[A-Z][a-z][0-9]_`. No sequence (including the one following the final `/` character) may be empty. - + %TRUE if @string is a D-Bus object path + filename="glib/gvariant.c" + line="1390">%TRUE if @string is a D-Bus object path a normal C nul-terminated string + filename="glib/gvariant.c" + line="1379">a normal C nul-terminated string @@ -86158,25 +91698,25 @@ must contain only the characters `[A-Z][a-z][0-9]_`. No sequence moved-to="Variant.is_signature" version="2.24"> Determines if a given string is a valid D-Bus type signature. You + filename="glib/gvariant.c" + line="1423">Determines if a given string is a valid D-Bus type signature. You should ensure that a string is a valid D-Bus type signature before passing it to g_variant_new_signature(). D-Bus type signatures consist of zero or more definite #GVariantType strings in sequence. - + %TRUE if @string is a D-Bus type signature + filename="glib/gvariant.c" + line="1434">%TRUE if @string is a D-Bus type signature a normal C nul-terminated string + filename="glib/gvariant.c" + line="1425">a normal C nul-terminated string @@ -86186,12 +91726,12 @@ strings in sequence. moved-to="Variant.parse" throws="1"> Parses a #GVariant from a text representation. + filename="glib/gvariant-parser.c" + line="2489">Parses a #GVariant from a text representation. A single #GVariant is parsed from the content of @text. -The format is described [here][gvariant-text]. +The format is described [here](gvariant-text-format.html). The memory at @limit will never be accessed and the parser behaves as if the character at @limit is the nul terminator. This has the @@ -86211,22 +91751,23 @@ with empty arrays). In the event that the parsing is successful, the resulting #GVariant is returned. It is never floating, and must be freed with -g_variant_unref(). +[method@GLib.Variant.unref]. In case of any error, %NULL will be returned. If @error is non-%NULL then it will be set to reflect the error that occurred. -Officially, the language understood by the parser is "any string -produced by g_variant_print()". +Officially, the language understood by the parser is “any string +produced by [method@GLib.Variant.print]”. This explicitly includes +`g_variant_print()`’s annotated types like `int64 -1000`. There may be implementation specific restrictions on deeply nested values, which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is guaranteed to handle nesting up to at least 64 levels. - + a non-floating reference to a #GVariant, or %NULL + filename="glib/gvariant-parser.c" + line="2534">a non-floating reference to a #GVariant, or %NULL @@ -86235,14 +91776,14 @@ guaranteed to handle nesting up to at least 64 levels. nullable="1" allow-none="1"> a #GVariantType, or %NULL + filename="glib/gvariant-parser.c" + line="2491">a #GVariantType, or %NULL a string containing a GVariant in text form + filename="glib/gvariant-parser.c" + line="2492">a string containing a GVariant in text form nullable="1" allow-none="1"> a pointer to the end of @text, or %NULL + filename="glib/gvariant-parser.c" + line="2493">a pointer to the end of @text, or %NULL nullable="1" allow-none="1"> a location to store the end pointer, or %NULL + filename="glib/gvariant-parser.c" + line="2494">a location to store the end pointer, or %NULL @@ -86270,8 +91811,8 @@ guaranteed to handle nesting up to at least 64 levels. moved-to="Variant.parse_error_print_context" version="2.40"> Pretty-prints a message showing the context of a #GVariant parse + filename="glib/gvariant-parser.c" + line="2858">Pretty-prints a message showing the context of a #GVariant parse error within the string for which parsing was attempted. The resulting string is suitable for output to the console or other @@ -86300,24 +91841,24 @@ The format of the message may change in a future version. If @source_str was not nul-terminated when you passed it to g_variant_parse() then you must add nul termination before using this function. - + the printed message + filename="glib/gvariant-parser.c" + line="2893">the printed message a #GError from the #GVariantParseError domain + filename="glib/gvariant-parser.c" + line="2860">a #GError from the #GVariantParseError domain the string that was given to the parser + filename="glib/gvariant-parser.c" + line="2861">the string that was given to the parser @@ -86334,8 +91875,8 @@ function. moved-to="Variant.parser_get_error_quark" deprecated="1"> Same as g_variant_error_quark(). + filename="glib/gvariant-parser.c" + line="79">Same as g_variant_error_quark(). Use g_variant_parse_error_quark() instead. @@ -86344,12 +91885,12 @@ function. - + - + @@ -86357,7 +91898,7 @@ function. - + @@ -86371,24 +91912,25 @@ function. c:identifier="g_variant_type_string_is_valid" moved-to="VariantType.string_is_valid"> Checks if @type_string is a valid GVariant type string. This call is -equivalent to calling g_variant_type_string_scan() and confirming -that the following character is a nul terminator. - + filename="glib/gvarianttype.c" + line="338">Checks if @type_string is a valid +[GVariant type string](./struct.VariantType.html#gvariant-type-strings). + +This call is equivalent to calling [func@GLib.VariantType.string_scan] and +confirming that the following character is a nul terminator. + %TRUE if @type_string is exactly one valid type string - + filename="glib/gvarianttype.c" + line="348">true if @type_string is exactly one valid type string Since 2.24 a pointer to any string + filename="glib/gvarianttype.c" + line="340">a pointer to any string @@ -86398,8 +91940,9 @@ Since 2.24 moved-to="VariantType.string_scan" version="2.24"> Scan for a single complete and valid GVariant type string in @string. + filename="glib/gvarianttype.c" + line="276">Scan for a single complete and valid GVariant type string in @string. + The memory pointed to by @limit (or bytes beyond it) is never accessed. @@ -86411,19 +91954,19 @@ If there is no valid type string starting at @string, or if the type string does not end before @limit then %FALSE is returned. For the simple case of checking if a string is a valid type string, -see g_variant_type_string_is_valid(). - +see [func@GLib.VariantType.string_is_valid]. + %TRUE if a valid type string was found + filename="glib/gvarianttype.c" + line="297">true if a valid type string was found a pointer to any string + filename="glib/gvarianttype.c" + line="278">a pointer to any string nullable="1" allow-none="1"> the end of @string, or %NULL + filename="glib/gvarianttype.c" + line="279">the end of @string optional="1" allow-none="1"> location to store the end pointer, or %NULL + filename="glib/gvarianttype.c" + line="280">location to store the end pointer @@ -86453,102 +91996,87 @@ see g_variant_type_string_is_valid(). version="2.4" introspectable="0"> An implementation of the GNU vasprintf() function which supports + filename="glib/gprintf.c" + line="298">An implementation of the GNU `vasprintf()` function which supports positional parameters, as specified in the Single Unix Specification. -This function is similar to g_vsprintf(), except that it allocates a +This function is similar to [func@GLib.vsprintf], except that it allocates a string to hold the output, instead of putting the output in a buffer you allocate in advance. -The returned value in @string is guaranteed to be non-NULL, unless +The returned value in @string is guaranteed to be non-`NULL`, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. `glib/gprintf.h` must be explicitly included in order to use this function. - + the number of bytes printed, or `-1` on failure + filename="glib/gprintf.c" + line="319">the number of bytes printed, or -1 on failure - + the return location for the newly-allocated string, - which will be %NULL if (and only if) this function fails + filename="glib/gprintf.c" + line="300">the return location for the + newly-allocated string, which will be `NULL` if (and only if) + this function fails a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="303">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output. + filename="glib/gprintf.c" + line="305">the list of arguments to insert in the output - - GLib provides version information, primarily useful in configure -checks for builds that have a configure script. Applications will -not typically use the features described here. - -The GLib headers annotate deprecated APIs in a way that produces -compiler warnings if these deprecated APIs are used. The warnings -can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS -before including the glib.h header. - -GLib also provides support for building applications against -defined subsets of deprecated or new GLib APIs. Define the macro -%GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib -you want to receive warnings about deprecated APIs. Define the -macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of -GLib whose API you want to use. - An implementation of the standard fprintf() function which supports + filename="glib/gprintf.c" + line="203">An implementation of the standard `fprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. - + the number of bytes printed. + filename="glib/gprintf.c" + line="215">the number of bytes printed the stream to write to. + filename="glib/gprintf.c" + line="205">the stream to write to a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="206">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output. + filename="glib/gprintf.c" + line="208">the list of arguments to insert in the output @@ -86558,87 +92086,87 @@ positional parameters, as specified in the Single Unix Specification. version="2.2" introspectable="0"> An implementation of the standard vprintf() function which supports + filename="glib/gprintf.c" + line="179">An implementation of the standard `vprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. - + the number of bytes printed. + filename="glib/gprintf.c" + line="190">the number of bytes printed a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="181">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output. + filename="glib/gprintf.c" + line="183">the list of arguments to insert in the output A safer form of the standard vsprintf() function. The output is guaranteed + filename="glib/gprintf.c" + line="256">A safer form of the standard `vsprintf()` function. The output is guaranteed to not exceed @n characters (including the terminating nul character), so it is easy to ensure that a buffer overflow cannot occur. -See also g_strdup_vprintf(). +See also [func@GLib.strdup_vprintf]. In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string. -The return value of g_vsnprintf() conforms to the vsnprintf() function +The return value of `g_vsnprintf()` conforms to the `vsnprintf()` function as standardized in ISO C99. Note that this is different from traditional -vsnprintf(), which returns the length of the output string. +`vsnprintf()`, which returns the length of the output string. The format string may contain positional parameters, as specified in the Single Unix Specification. - + the number of bytes which would be produced if the buffer - was large enough. + filename="glib/gprintf.c" + line="283">the number of bytes which would be produced if the buffer + was large enough the buffer to hold the output. + filename="glib/gprintf.c" + line="258">the buffer to hold the output the maximum number of bytes to produce (including the - terminating nul character). + filename="glib/gprintf.c" + line="259">the maximum number of bytes to produce (including the + terminating nul character) a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="261">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output. + filename="glib/gprintf.c" + line="263">the list of arguments to insert in the output @@ -86648,36 +92176,36 @@ the Single Unix Specification. version="2.2" introspectable="0"> An implementation of the standard vsprintf() function which supports + filename="glib/gprintf.c" + line="229">An implementation of the standard `vsprintf()` function which supports positional parameters, as specified in the Single Unix Specification. `glib/gprintf.h` must be explicitly included in order to use this function. - + the number of bytes printed. + filename="glib/gprintf.c" + line="241">the number of bytes printed the buffer to hold the output. + filename="glib/gprintf.c" + line="231">the buffer to hold the output a standard printf() format string, but notice - [string precision pitfalls][string-precision] + filename="glib/gprintf.c" + line="232">a standard `printf()` format string, but notice + [string precision pitfalls](string-utils.html#string-precision-pitfalls) the list of arguments to insert in the output. + filename="glib/gprintf.c" + line="234">the list of arguments to insert in the output @@ -86687,14 +92215,17 @@ positional parameters, as specified in the Single Unix Specification. version="2.16" introspectable="0"> Logs a warning if the expression is not true. - + filename="glib/gmessages.h" + line="549">Logs a warning if the expression is not true. + +Unlike g_return_if_fail(), the expression is always evaluated, even if +checks and assertions are disabled. + the expression to check + filename="glib/gmessages.h" + line="551">the expression to check @@ -86703,18 +92234,18 @@ positional parameters, as specified in the Single Unix Specification. version="2.16" introspectable="0"> Logs a warning. - + filename="glib/gmessages.h" + line="537">Logs a warning. + Internal function used to print messages from the public g_warn_if_reached() -and g_warn_if_fail() macros. - + filename="glib/gmessages.c" + line="3081">Internal function used to print messages from the public [func@GLib.warn_if_reached] +and [func@GLib.warn_if_fail] macros. + @@ -86724,26 +92255,26 @@ and g_warn_if_fail() macros. nullable="1" allow-none="1"> log domain + filename="glib/gmessages.c" + line="3083">log domain file containing the warning + filename="glib/gmessages.c" + line="3084">file containing the warning line number of the warning + filename="glib/gmessages.c" + line="3085">line number of the warning function containing the warning + filename="glib/gmessages.c" + line="3086">function containing the warning nullable="1" allow-none="1"> expression which failed + filename="glib/gmessages.c" + line="3087">expression which failed A convenience function/macro to log a warning message. The message should -typically *not* be translated to the user's language. + filename="glib/gmessages.c" + line="197">A convenience function/macro to log a warning message. + +The message should typically *not* be translated to the user’s language. -This is not intended for end user error reporting. Use of #GError is +This is not intended for end user error reporting. Use of [type@GLib.Error] is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error. @@ -86773,35 +92305,35 @@ other trusted programs violating protocol, invalid contents in trusted files, etc.) If attempting to deal with programmer errors (for example, incorrect function -parameters) then you should use %G_LOG_LEVEL_CRITICAL instead. +parameters) then you should use [flags@GLib.LogLevelFlags.LEVEL_CRITICAL] instead. -g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING. +[func@GLib.warn_if_reached] and func@GLib.warn_if_fail] log at [flags@GLib.LogLevelFlags.LEVEL_WARNING]. You can make warnings fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](glib-running.html)): -|[ - G_DEBUG=fatal-warnings gdb ./my-program -]| +``` +G_DEBUG=fatal-warnings gdb ./my-program +``` Any unrelated failures can be skipped over in [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. -If g_log_default_handler() is used as the log handler function, +If [func@GLib.log_default_handler] is used as the log handler function, a newline character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. - +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). + format string, followed by parameters to insert - into the format string (as with printf()) + filename="glib/gmessages.c" + line="199">format string, followed by parameters to insert into the format string + (as with `printf()`) @@ -86810,80 +92342,23 @@ otherwise it will use g_log(). See version="2.64" introspectable="0"> Logs a warning only once. + filename="glib/gmessages.h" + line="481">Logs a warning only once. g_warning_once() calls g_warning() with the passed message the first time the statement is executed; subsequent times it is a no-op. Note! On platforms where the compiler doesn't support variadic macros, the warning is printed each time instead of only once. - + format string, followed by parameters to insert + filename="glib/gmessages.h" + line="483">format string, followed by parameters to insert into the format string (as with printf()) - - GLib defines several warning functions and assertions which can be used to -warn of programmer errors when calling functions, and print error messages -from command line programs. - -The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and -g_return_val_if_reached() macros are intended as pre-condition assertions, to -be used at the top of a public function to check that the function’s -arguments are acceptable. Any failure of such a pre-condition assertion is -considered a programming error on the part of the caller of the public API, -and the program is considered to be in an undefined state afterwards. They -are similar to the libc assert() function, but provide more context on -failures. - -For example: -|[<!-- language="C" --> -gboolean -g_dtls_connection_shutdown (GDtlsConnection *conn, - gboolean shutdown_read, - gboolean shutdown_write, - GCancellable *cancellable, - GError **error) -{ - // local variable declarations - - g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE); - g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); - g_return_val_if_fail (error == NULL || *error == NULL, FALSE); - - // function body - - return return_val; -} -]| - -g_print() and g_printerr() are intended to be used for -output from command line applications, since they output to standard output -and standard error by default — whereas functions like g_message() and -g_log() may be redirected to special purpose message windows, files, or the -system journal. - -If the console encoding is not UTF-8 (as specified by g_get_console_charset()) -then these functions convert the message first. Any Unicode -characters not defined by that charset are replaced by `'?'`. On Linux, -setlocale() must be called early in main() to load the encoding. This behaviour -can be changed by providing custom handlers to g_set_print_handler(), -g_set_printerr_handler() and g_log_set_handler(). - - - These functions provide some level of UNIX emulation on the -Windows platform. If your application really needs the POSIX -APIs, we suggest you try the Cygwin project. - diff --git a/generator/src/main/resources/gir/GObject-2.0.gir b/generator/src/main/resources/gir/GObject-2.0.gir index 9069000..0255b10 100644 --- a/generator/src/main/resources/gir/GObject-2.0.gir +++ b/generator/src/main/resources/gir/GObject-2.0.gir @@ -5,18 +5,20 @@ and/or use gtk-doc annotations. --> + + c:symbol-prefixes="gobject,g"> This is the signature of marshaller functions, required to marshall arrays of parameter values to signal emissions into C language callback invocations. @@ -24,24 +26,24 @@ invocations. It is merely an alias to #GClosureMarshal since the #GClosure mechanism takes over responsibility of actual function invocation for the signal system. - + This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues. - + A numerical value which represents the unique identifier of a registered type. - + version="2.38" introspectable="0"> A convenience macro to ease adding private data to instances of a new type + filename="gobject/gtype.h" + line="2122">A convenience macro to ease adding private data to instances of a new type in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). @@ -115,12 +117,12 @@ name of the form `TypeNamePrivate`. It is safe to call the `_get_instance_private` function on %NULL or invalid objects since it's only adding an offset to the instance pointer. In that case the returned pointer must not be dereferenced. - + the name of the type in CamelCase + filename="gobject/gtype.h" + line="2124">the name of the type in CamelCase @@ -129,8 +131,8 @@ case the returned pointer must not be dereferenced. version="2.38" introspectable="0"> A convenience macro to ease adding private data to instances of a new dynamic + filename="gobject/gtypemodule.h" + line="245">A convenience macro to ease adding private data to instances of a new dynamic type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_ADD_PRIVATE() for details, it is similar but for static types. @@ -138,17 +140,22 @@ See G_ADD_PRIVATE() for details, it is similar but for static types. Note that this macro can only be used together with the G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable names from that macro. - + the name of the type in CamelCase + filename="gobject/gtypemodule.h" + line="247">the name of the type in CamelCase + + - + @@ -157,7 +164,7 @@ names from that macro. - + @@ -165,8 +172,8 @@ names from that macro. A callback function used by the type system to finalize those portions + filename="gobject/gtype.h" + line="830">A callback function used by the type system to finalize those portions of a derived types class structure that were setup from the corresponding GBaseInitFunc() function. @@ -174,23 +181,23 @@ Class finalization basically works the inverse way in which class initialization is performed. See GClassInitFunc() for a discussion of the class initialization process. - + The #GTypeClass structure to finalize + filename="gobject/gtype.h" + line="832">The #GTypeClass structure to finalize A callback function used by the type system to do base initialization + filename="gobject/gtype.h" + line="813">A callback function used by the type system to do base initialization of the class structures of derived types. This function is called as part of the initialization process of all derived @@ -201,15 +208,15 @@ For example, class members (such as strings) that are not sufficiently handled by a plain memory copy of the parent class into the derived class have to be altered. See GClassInitFunc() for a discussion of the class initialization process. - + The #GTypeClass structure to initialize + filename="gobject/gtype.h" + line="815">The #GTypeClass structure to initialize @@ -222,33 +229,32 @@ initialization process. glib:type-name="GBinding" glib:get-type="g_binding_get_type"> #GBinding is the representation of a binding between a property on a -#GObject instance (or source) and another property on another #GObject + filename="gobject/gbinding.c" + line="23">`GObject` instance (or source) and another property on another `GObject` instance (or target). Whenever the source property changes, the same value is applied to the target property; for instance, the following binding: -|[<!-- language="C" --> +```c g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_DEFAULT); -]| +``` will cause the property named "property-b" of @object2 to be updated -every time g_object_set() or the specific accessor changes the value of +every time [method@GObject.set] or the specific accessor changes the value of the property "property-a" of @object1. It is possible to create a bidirectional binding between two properties -of two #GObject instances, so that if either property changes, the +of two `GObject` instances, so that if either property changes, the other is updated as well, for instance: -|[<!-- language="C" --> +```c g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_BIDIRECTIONAL); -]| +``` will keep the two properties in sync. @@ -257,14 +263,14 @@ directions, in case of a bidirectional binding) to apply a custom transformation from the source value to the target value before applying it; for instance, the following binding: -|[<!-- language="C" --> +```c g_object_bind_property_full (adjustment1, "value", adjustment2, "value", G_BINDING_BIDIRECTIONAL, celsius_to_fahrenheit, fahrenheit_to_celsius, NULL, NULL); -]| +``` will keep the "value" property of the two adjustments in sync; the @celsius_to_fahrenheit function will be called whenever the "value" @@ -278,52 +284,50 @@ of @adjustment1. Note that #GBinding does not resolve cycles by itself; a cycle like -|[ +``` object1:propertyA -> object2:propertyB object2:propertyB -> object3:propertyC object3:propertyC -> object1:propertyA -]| +``` might lead to an infinite loop. The loop, in this particular case, -can be avoided if the objects emit the #GObject::notify signal only +can be avoided if the objects emit the `GObject::notify` signal only if the value has effectively been changed. A binding is implemented -using the #GObject::notify signal, so it is susceptible to all the -various ways of blocking a signal emission, like g_signal_stop_emission() -or g_signal_handler_block(). +using the `GObject::notify` signal, so it is susceptible to all the +various ways of blocking a signal emission, like [func@GObject.signal_stop_emission] +or [func@GObject.signal_handler_block]. A binding will be severed, and the resources it allocates freed, whenever -either one of the #GObject instances it refers to are finalized, or when +either one of the `GObject` instances it refers to are finalized, or when the #GBinding instance loses its last reference. Bindings for languages with garbage collection can use -g_binding_unbind() to explicitly release a binding between the source +[method@GObject.Binding.unbind] to explicitly release a binding between the source and target properties, instead of relying on the last reference on the -binding, source, and target instances to drop. - -#GBinding is available since GObject 2.26 +binding, source, and target instances to drop. Retrieves the #GObject instance used as the source of the binding. + filename="gobject/gbinding.c" + line="1024">Retrieves the #GObject instance used as the source of the binding. A #GBinding can outlive the source #GObject as the binding does not hold a strong reference to the source. If the source is destroyed before the binding then this function will return %NULL. - + the source #GObject, or %NULL if the + filename="gobject/gbinding.c" + line="1034">the source #GObject, or %NULL if the source does not exist any more. a #GBinding + filename="gobject/gbinding.c" + line="1026">a #GBinding @@ -332,25 +336,25 @@ binding then this function will return %NULL. c:identifier="g_binding_dup_target" version="2.68"> Retrieves the #GObject instance used as the target of the binding. + filename="gobject/gbinding.c" + line="1085">Retrieves the #GObject instance used as the target of the binding. A #GBinding can outlive the target #GObject as the binding does not hold a strong reference to the target. If the target is destroyed before the binding then this function will return %NULL. - + the target #GObject, or %NULL if the + filename="gobject/gbinding.c" + line="1095">the target #GObject, or %NULL if the target does not exist any more. a #GBinding + filename="gobject/gbinding.c" + line="1087">a #GBinding @@ -360,20 +364,20 @@ binding then this function will return %NULL. glib:get-property="flags" version="2.26"> Retrieves the flags passed when constructing the #GBinding. - + filename="gobject/gbinding.c" + line="968">Retrieves the flags passed when constructing the #GBinding. + the #GBindingFlags used by the #GBinding + filename="gobject/gbinding.c" + line="974">the #GBindingFlags used by the #GBinding a #GBinding + filename="gobject/gbinding.c" + line="970">a #GBinding @@ -385,8 +389,8 @@ binding then this function will return %NULL. deprecated="1" deprecated-version="2.68"> Retrieves the #GObject instance used as the source of the binding. + filename="gobject/gbinding.c" + line="986">Retrieves the #GObject instance used as the source of the binding. A #GBinding can outlive the source #GObject as the binding does not hold a strong reference to the source. If the source is destroyed before the @@ -397,19 +401,19 @@ threads as otherwise the pointer returned from this function might become invalid if the source is finalized from another thread in the meantime. Use g_binding_dup_source() for a safer version of this function. - + the source #GObject, or %NULL if the + filename="gobject/gbinding.c" + line="1000">the source #GObject, or %NULL if the source does not exist any more. a #GBinding + filename="gobject/gbinding.c" + line="988">a #GBinding @@ -419,21 +423,21 @@ function. glib:get-property="source-property" version="2.26"> Retrieves the name of the property of #GBinding:source used as the source + filename="gobject/gbinding.c" + line="1108">Retrieves the name of the property of #GBinding:source used as the source of the binding. - + the name of the source property + filename="gobject/gbinding.c" + line="1115">the name of the source property a #GBinding + filename="gobject/gbinding.c" + line="1110">a #GBinding @@ -445,8 +449,8 @@ of the binding. deprecated="1" deprecated-version="2.68"> Retrieves the #GObject instance used as the target of the binding. + filename="gobject/gbinding.c" + line="1047">Retrieves the #GObject instance used as the target of the binding. A #GBinding can outlive the target #GObject as the binding does not hold a strong reference to the target. If the target is destroyed before the @@ -457,19 +461,19 @@ threads as otherwise the pointer returned from this function might become invalid if the target is finalized from another thread in the meantime. Use g_binding_dup_target() for a safer version of this function. - + the target #GObject, or %NULL if the + filename="gobject/gbinding.c" + line="1061">the target #GObject, or %NULL if the target does not exist any more. a #GBinding + filename="gobject/gbinding.c" + line="1049">a #GBinding @@ -479,29 +483,29 @@ function. glib:get-property="target-property" version="2.26"> Retrieves the name of the property of #GBinding:target used as the target + filename="gobject/gbinding.c" + line="1127">Retrieves the name of the property of #GBinding:target used as the target of the binding. - + the name of the target property + filename="gobject/gbinding.c" + line="1134">the name of the target property a #GBinding + filename="gobject/gbinding.c" + line="1129">a #GBinding Explicitly releases the binding between the source and the target + filename="gobject/gbinding.c" + line="1146">Explicitly releases the binding between the source and the target property expressed by @binding. This function will release the reference that is being held on @@ -512,15 +516,15 @@ to hold a reference to it. Note however that this function does not take ownership of @binding, it only unrefs the reference that was initially created by g_object_bind_property() and is owned by the binding. - + a #GBinding + filename="gobject/gbinding.c" + line="1148">a #GBinding @@ -533,8 +537,8 @@ g_object_bind_property() and is owned by the binding. getter="get_flags" default-value="G_BINDING_DEFAULT"> Flags to be used to control the #GBinding + filename="gobject/gbinding.c" + line="941">Flags to be used to control the #GBinding transfer-ownership="none" getter="get_source"> The #GObject that should be used as the source of the binding + filename="gobject/gbinding.c" + line="881">The #GObject that should be used as the source of the binding getter="get_source_property" default-value="NULL"> The name of the property of #GBinding:source that should be used + filename="gobject/gbinding.c" + line="907">The name of the property of #GBinding:source that should be used as the source of the binding. This should be in [canonical form][canonical-parameter-names] to get the @@ -571,8 +575,8 @@ best performance. transfer-ownership="none" getter="get_target"> The #GObject that should be used as the target of the binding + filename="gobject/gbinding.c" + line="894">The #GObject that should be used as the target of the binding getter="get_target_property" default-value="NULL"> The name of the property of #GBinding:target that should be used + filename="gobject/gbinding.c" + line="924">The name of the property of #GBinding:target that should be used as the target of the binding. This should be in [canonical form][canonical-parameter-names] to get the @@ -598,8 +602,8 @@ best performance. glib:get-type="g_binding_flags_get_type" c:type="GBindingFlags"> Flags to be passed to g_object_bind_property() or + filename="gobject/gbinding.h" + line="68">Flags to be passed to g_object_bind_property() or g_object_bind_property_full(). This enumeration can be extended at later date. @@ -609,8 +613,8 @@ This enumeration can be extended at later date. glib:nick="default" glib:name="G_BINDING_DEFAULT"> The default binding; if the source property + filename="gobject/gbinding.h" + line="70">The default binding; if the source property changes, the target property is updated with its value. glib:nick="bidirectional" glib:name="G_BINDING_BIDIRECTIONAL"> Bidirectional binding; if either the + filename="gobject/gbinding.h" + line="72">Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. @@ -630,8 +634,8 @@ This enumeration can be extended at later date. glib:nick="sync-create" glib:name="G_BINDING_SYNC_CREATE"> Synchronize the values of the source and + filename="gobject/gbinding.h" + line="75">Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. @@ -641,8 +645,8 @@ This enumeration can be extended at later date. glib:nick="invert-boolean" glib:name="G_BINDING_INVERT_BOOLEAN"> If the two properties being bound are + filename="gobject/gbinding.h" + line="78">If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom @@ -657,70 +661,70 @@ This enumeration can be extended at later date. glib:type-name="GBindingGroup" glib:get-type="g_binding_group_get_type"> The #GBindingGroup can be used to bind multiple properties + filename="gobject/gbindinggroup.c" + line="29">`GBindingGroup` can be used to bind multiple properties from an object collectively. Use the various methods to bind properties from a single source object to multiple destination objects. Properties can be bound bidirectionally and are connected when the source object is set -with g_binding_group_set_source(). +with [method@GObject.BindingGroup.set_source]. Creates a new #GBindingGroup. - + filename="gobject/gbindinggroup.c" + line="362">Creates a new #GBindingGroup. + a new #GBindingGroup + filename="gobject/gbindinggroup.c" + line="367">a new #GBindingGroup Creates a binding between @source_property on the source object + filename="gobject/gbindinggroup.c" + line="557">Creates a binding between @source_property on the source object and @target_property on @target. Whenever the @source_property is changed the @target_property is updated using the same value. The binding flag %G_BINDING_SYNC_CREATE is automatically specified. See g_object_bind_property() for more information. - + the #GBindingGroup + filename="gobject/gbindinggroup.c" + line="559">the #GBindingGroup the property on the source to bind + filename="gobject/gbindinggroup.c" + line="560">the property on the source to bind the target #GObject + filename="gobject/gbindinggroup.c" + line="561">the target #GObject the property on @target to bind + filename="gobject/gbindinggroup.c" + line="562">the property on @target to bind the flags used to create the #GBinding + filename="gobject/gbindinggroup.c" + line="563">the flags used to create the #GBinding @@ -730,46 +734,46 @@ See g_object_bind_property() for more information. shadowed-by="bind_with_closures" version="2.72"> Creates a binding between @source_property on the source object and + filename="gobject/gbindinggroup.c" + line="588">Creates a binding between @source_property on the source object and @target_property on @target, allowing you to set the transformation functions to be used by the binding. The binding flag %G_BINDING_SYNC_CREATE is automatically specified. See g_object_bind_property_full() for more information. - + the #GBindingGroup + filename="gobject/gbindinggroup.c" + line="590">the #GBindingGroup the property on the source to bind + filename="gobject/gbindinggroup.c" + line="591">the property on the source to bind the target #GObject + filename="gobject/gbindinggroup.c" + line="592">the target #GObject the property on @target to bind + filename="gobject/gbindinggroup.c" + line="593">the property on @target to bind the flags used to create the #GBinding + filename="gobject/gbindinggroup.c" + line="594">the flags used to create the #GBinding allow-none="1" scope="notified"> the transformation function + filename="gobject/gbindinggroup.c" + line="595">the transformation function from the source object to the @target, or %NULL to use the default @@ -791,8 +795,8 @@ See g_object_bind_property_full() for more information. closure="6" destroy="7"> the transformation function + filename="gobject/gbindinggroup.c" + line="597">the transformation function from the @target to the source object, or %NULL to use the default @@ -801,8 +805,8 @@ See g_object_bind_property_full() for more information. nullable="1" allow-none="1"> custom data to be passed to the transformation + filename="gobject/gbindinggroup.c" + line="599">custom data to be passed to the transformation functions, or %NULL @@ -810,8 +814,8 @@ See g_object_bind_property_full() for more information. transfer-ownership="none" scope="async"> function to be called when disposing the binding, + filename="gobject/gbindinggroup.c" + line="601">function to be called when disposing the binding, to free the resources used by the transformation functions @@ -822,8 +826,8 @@ See g_object_bind_property_full() for more information. shadows="bind_full" version="2.72"> Creates a binding between @source_property on the source object and + filename="gobject/gbindinggroup.c" + line="632">Creates a binding between @source_property on the source object and @target_property on @target, allowing you to set the transformation functions to be used by the binding. The binding flag %G_BINDING_SYNC_CREATE is automatically specified. @@ -833,39 +837,39 @@ g_binding_group_bind_property_full(), using #GClosures instead of function pointers. See g_object_bind_property_with_closures() for more information. - + the #GBindingGroup + filename="gobject/gbindinggroup.c" + line="634">the #GBindingGroup the property on the source to bind + filename="gobject/gbindinggroup.c" + line="635">the property on the source to bind the target #GObject + filename="gobject/gbindinggroup.c" + line="636">the target #GObject the property on @target to bind + filename="gobject/gbindinggroup.c" + line="637">the property on @target to bind the flags used to create the #GBinding + filename="gobject/gbindinggroup.c" + line="638">the flags used to create the #GBinding nullable="1" allow-none="1"> a #GClosure wrapping the + filename="gobject/gbindinggroup.c" + line="639">a #GClosure wrapping the transformation function from the source object to the @target, or %NULL to use the default @@ -884,8 +888,8 @@ See g_object_bind_property_with_closures() for more information. nullable="1" allow-none="1"> a #GClosure wrapping the + filename="gobject/gbindinggroup.c" + line="642">a #GClosure wrapping the transformation function from the @target to the source object, or %NULL to use the default @@ -896,20 +900,20 @@ See g_object_bind_property_with_closures() for more information. c:identifier="g_binding_group_dup_source" version="2.72"> Gets the source object used for binding properties. - + filename="gobject/gbindinggroup.c" + line="377">Gets the source object used for binding properties. + a #GObject or %NULL. + filename="gobject/gbindinggroup.c" + line="383">a #GObject or %NULL. the #GBindingGroup + filename="gobject/gbindinggroup.c" + line="379">the #GBindingGroup @@ -919,21 +923,21 @@ See g_object_bind_property_with_closures() for more information. glib:set-property="source" version="2.72"> Sets @source as the source object used for creating property + filename="gobject/gbindinggroup.c" + line="422">Sets @source as the source object used for creating property bindings. If there is already a source object all bindings from it will be removed. Note that all properties that have been bound must exist on @source. - + the #GBindingGroup + filename="gobject/gbindinggroup.c" + line="424">the #GBindingGroup nullable="1" allow-none="1"> the source #GObject, + filename="gobject/gbindinggroup.c" + line="425">the source #GObject, or %NULL to clear it @@ -954,8 +958,8 @@ Note that all properties that have been bound must exist on @source. transfer-ownership="none" setter="set_source"> The source object used for binding properties. + filename="gobject/gbindinggroup.c" + line="340">The source object used for binding properties. @@ -963,39 +967,39 @@ Note that all properties that have been bound must exist on @source. c:type="GBindingTransformFunc" version="2.26"> A function to be called to transform @from_value to @to_value. + filename="gobject/gbinding.h" + line="43">A function to be called to transform @from_value to @to_value. If this is the @transform_to function of a binding, then @from_value is the @source_property on the @source object, and @to_value is the @target_property on the @target object. If this is the @transform_from function of a %G_BINDING_BIDIRECTIONAL binding, then those roles are reversed. - + %TRUE if the transformation was successful, and %FALSE + filename="gobject/gbinding.h" + line="58">%TRUE if the transformation was successful, and %FALSE otherwise a #GBinding + filename="gobject/gbinding.h" + line="45">a #GBinding the #GValue containing the value to transform + filename="gobject/gbinding.h" + line="46">the #GValue containing the value to transform the #GValue in which to store the transformed value + filename="gobject/gbinding.h" + line="47">the #GValue in which to store the transformed value allow-none="1" closure="3"> data passed to the transform function + filename="gobject/gbinding.h" + line="48">data passed to the transform function + + This function is provided by the user and should produce a copy of the passed in boxed structure. - + The newly created copy of the boxed structure. The boxed structure to be copied. @@ -1033,33 +1042,43 @@ of the passed in boxed structure. This function is provided by the user and should free the boxed structure passed. - + The boxed structure to be freed. + + + + Cast a function pointer to a #GCallback. - + a function pointer. @@ -1068,71 +1087,71 @@ structure passed. c:identifier="G_CCLOSURE_SWAP_DATA" introspectable="0"> Checks whether the user data of the #GCClosure should be passed as the first parameter to the callback. See g_cclosure_new_swap(). - + a #GCClosure A #GCClosure is a specialization of #GClosure for C function callbacks. - + the #GClosure the callback function A #GClosureMarshal function for use with signals with handlers that + filename="gobject/gmarshal.c" + line="2390">A #GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). - + A #GClosure. + filename="gobject/gmarshal.c" + line="2392">A #GClosure. A #GValue to store the return value. May be %NULL + filename="gobject/gmarshal.c" + line="2393">A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. + filename="gobject/gmarshal.c" + line="2395">The length of the @param_values array. An array of #GValues holding the arguments + filename="gobject/gmarshal.c" + line="2396">An array of #GValues holding the arguments on which to invoke the callback of closure. @@ -1141,8 +1160,8 @@ accumulator, such as g_signal_accumulator_true_handled(). nullable="1" allow-none="1"> The invocation hint given as the last argument to + filename="gobject/gmarshal.c" + line="2398">The invocation hint given as the last argument to g_closure_invoke(). @@ -1151,8 +1170,8 @@ accumulator, such as g_signal_accumulator_true_handled(). nullable="1" allow-none="1"> Additional data specified when registering the + filename="gobject/gmarshal.c" + line="2400">Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() @@ -1163,17 +1182,17 @@ accumulator, such as g_signal_accumulator_true_handled(). c:identifier="g_cclosure_marshal_BOOLEAN__BOXED_BOXEDv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). - + filename="gobject/gmarshal.c" + line="2450">The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2452">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="2453">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="2456">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="2457">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="2458">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="2461">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="2462">the #GType of each argument from @args. @@ -1230,37 +1249,40 @@ accumulator, such as g_signal_accumulator_true_handled(). A marshaller for a #GCClosure with a callback of type -`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter -denotes a flags type. - + filename="gobject/gmarshal.c" + line="2143">A #GClosureMarshal function for use with signals with handlers that +take a flags type as an argument and return a boolean. If you have +such a signal, you will probably also need to use an accumulator, +such as g_signal_accumulator_true_handled(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2145">A #GClosure. a #GValue which can store the returned #gboolean + filename="gobject/gmarshal.c" + line="2146">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="2148">The length of the @param_values array. a #GValue array holding instance and arg1 + filename="gobject/gmarshal.c" + line="2149">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="2151">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="2153">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1288,17 +1312,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_BOOLEAN__FLAGSv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). - + filename="gobject/gmarshal.c" + line="2201">The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2203">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="2204">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="2207">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="2208">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="2209">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="2212">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="2213">the #GType of each argument from @args. @@ -1355,36 +1379,39 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="2262">A #GClosureMarshal function for use with signals with handlers that +take a #GObject and a pointer and produce a string. It is highly +unlikely that your signal handler fits this description. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2264">A #GClosure. a #GValue, which can store the returned string + filename="gobject/gmarshal.c" + line="2265">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 3 + filename="gobject/gmarshal.c" + line="2267">The length of the @param_values array. a #GValue array holding instance, arg1 and arg2 + filename="gobject/gmarshal.c" + line="2268">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="2270">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="2272">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1412,17 +1441,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_STRING__OBJECT_POINTERv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). - + filename="gobject/gmarshal.c" + line="2321">The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2323">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="2324">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="2327">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="2328">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="2329">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="2332">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="2333">the #GType of each argument from @args. @@ -1479,36 +1508,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="169">A #GClosureMarshal function for use with signals with a single +boolean argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="171">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="172">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="174">The length of the @param_values array. a #GValue array holding the instance and the #gboolean parameter + filename="gobject/gmarshal.c" + line="175">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="177">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="179">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1536,17 +1569,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__BOOLEANv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). - + filename="gobject/gmarshal.c" + line="221">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="223">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="224">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="227">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="228">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="229">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="232">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="233">the #GType of each argument from @args. @@ -1603,36 +1636,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1581">A #GClosureMarshal function for use with signals with a single +argument which is any boxed pointer type. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1583">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1584">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1586">The length of the @param_values array. a #GValue array holding the instance and the #GBoxed* parameter + filename="gobject/gmarshal.c" + line="1587">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1589">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1591">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1660,17 +1697,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__BOXEDv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). - + filename="gobject/gmarshal.c" + line="1633">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1635">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1636">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1639">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1640">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1641">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1644">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1645">the #GType of each argument from @args. @@ -1727,36 +1764,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="277">A #GClosureMarshal function for use with signals with a single +character argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="279">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="280">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="282">The length of the @param_values array. a #GValue array holding the instance and the #gchar parameter + filename="gobject/gmarshal.c" + line="283">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="285">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="287">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1784,17 +1825,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__CHARv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). - + filename="gobject/gmarshal.c" + line="329">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="331">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="332">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="335">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="336">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="337">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="340">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="341">the #GType of each argument from @args. @@ -1851,36 +1892,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1249">A #GClosureMarshal function for use with signals with one +double-precision floating point argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1251">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1252">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1254">The length of the @param_values array. a #GValue array holding the instance and the #gdouble parameter + filename="gobject/gmarshal.c" + line="1255">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1257">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1259">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1908,17 +1953,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__DOUBLEv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). - + filename="gobject/gmarshal.c" + line="1301">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1303">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1304">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1307">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1308">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1309">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1312">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1313">the #GType of each argument from @args. @@ -1975,36 +2020,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. - + filename="gobject/gmarshal.c" + line="925">A #GClosureMarshal function for use with signals with a single +argument with an enumerated type. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="927">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="928">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="930">The length of the @param_values array. a #GValue array holding the instance and the enumeration parameter + filename="gobject/gmarshal.c" + line="931">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="933">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="935">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2032,17 +2081,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__ENUMv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). - + filename="gobject/gmarshal.c" + line="977">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="979">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="980">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="983">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="984">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="985">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="988">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="989">the #GType of each argument from @args. @@ -2099,36 +2148,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. - + filename="gobject/gmarshal.c" + line="1033">A #GClosureMarshal function for use with signals with a single +argument with a flags types. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1035">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1036">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1038">The length of the @param_values array. a #GValue array holding the instance and the flags parameter + filename="gobject/gmarshal.c" + line="1039">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1041">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1043">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2156,17 +2209,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__FLAGSv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). - + filename="gobject/gmarshal.c" + line="1085">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1087">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1088">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1091">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1092">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1093">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1096">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1097">the #GType of each argument from @args. @@ -2223,36 +2276,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1141">A #GClosureMarshal function for use with signals with one +single-precision floating point argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1143">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1144">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1146">The length of the @param_values array. a #GValue array holding the instance and the #gfloat parameter + filename="gobject/gmarshal.c" + line="1147">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1149">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1151">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2280,17 +2337,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__FLOATv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). - + filename="gobject/gmarshal.c" + line="1193">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1195">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1196">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1199">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1200">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1201">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1204">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1205">the #GType of each argument from @args. @@ -2347,36 +2404,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="493">A #GClosureMarshal function for use with signals with a single +integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="495">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="496">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="498">The length of the @param_values array. a #GValue array holding the instance and the #gint parameter + filename="gobject/gmarshal.c" + line="499">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="501">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="503">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2404,17 +2465,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__INTv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). - + filename="gobject/gmarshal.c" + line="545">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="547">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="548">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="551">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="552">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="553">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="556">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="557">the #GType of each argument from @args. @@ -2471,36 +2532,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="709">A #GClosureMarshal function for use with signals with with a single +long integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="711">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="712">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="714">The length of the @param_values array. a #GValue array holding the instance and the #glong parameter + filename="gobject/gmarshal.c" + line="715">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="717">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="719">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2528,17 +2593,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__LONGv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). - + filename="gobject/gmarshal.c" + line="761">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="763">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="764">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="767">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="768">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="769">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="772">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="773">the #GType of each argument from @args. @@ -2595,36 +2660,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1805">A #GClosureMarshal function for use with signals with a single +#GObject argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1807">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1808">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1810">The length of the @param_values array. a #GValue array holding the instance and the #GObject* parameter + filename="gobject/gmarshal.c" + line="1811">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1813">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1815">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2652,17 +2721,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__OBJECTv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). - + filename="gobject/gmarshal.c" + line="1857">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1859">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1860">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1863">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1864">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1865">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1868">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1869">the #GType of each argument from @args. @@ -2719,36 +2788,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1469">A #GClosureMarshal function for use with signals with a single +argument of type #GParamSpec. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1471">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1472">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1474">The length of the @param_values array. a #GValue array holding the instance and the #GParamSpec* parameter + filename="gobject/gmarshal.c" + line="1475">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1477">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1479">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2776,17 +2849,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__PARAMv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). - + filename="gobject/gmarshal.c" + line="1521">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1523">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1524">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1527">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1528">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1529">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1532">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1533">the #GType of each argument from @args. @@ -2843,36 +2916,42 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1693">A #GClosureMarshal function for use with signals with a single raw +pointer argument type. + +If it is possible, it is better to use one of the more specific +functions such as g_cclosure_marshal_VOID__OBJECT() or +g_cclosure_marshal_VOID__OBJECT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1695">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1696">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1698">The length of the @param_values array. a #GValue array holding the instance and the #gpointer parameter + filename="gobject/gmarshal.c" + line="1699">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1701">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1703">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2900,17 +2981,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__POINTERv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). - + filename="gobject/gmarshal.c" + line="1749">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1751">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1752">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1755">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1756">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1757">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1760">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1761">the #GType of each argument from @args. @@ -2967,36 +3048,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1357">A #GClosureMarshal function for use with signals with a single string +argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1359">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1360">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1362">The length of the @param_values array. a #GValue array holding the instance and the #gchar* parameter + filename="gobject/gmarshal.c" + line="1363">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1365">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1367">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3024,17 +3109,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__STRINGv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). - + filename="gobject/gmarshal.c" + line="1409">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1411">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1412">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1415">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1416">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1417">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1420">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1421">the #GType of each argument from @args. @@ -3091,36 +3176,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="385">A #GClosureMarshal function for use with signals with a single +unsigned character argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="387">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="388">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="390">The length of the @param_values array. a #GValue array holding the instance and the #guchar parameter + filename="gobject/gmarshal.c" + line="391">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="393">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="395">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3148,17 +3237,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__UCHARv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). - + filename="gobject/gmarshal.c" + line="437">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="439">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="440">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="443">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="444">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="445">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="448">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="449">the #GType of each argument from @args. @@ -3215,36 +3304,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="601">A #GClosureMarshal function for use with signals with with a single +unsigned integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="603">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="604">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="606">The length of the @param_values array. a #GValue array holding the instance and the #guint parameter + filename="gobject/gmarshal.c" + line="607">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="609">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="611">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3271,36 +3364,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="2029">A #GClosureMarshal function for use with signals with an unsigned int +and a pointer as arguments. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2031">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="2032">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 3 + filename="gobject/gmarshal.c" + line="2034">The length of the @param_values array. a #GValue array holding instance, arg1 and arg2 + filename="gobject/gmarshal.c" + line="2035">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="2037">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="2039">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3328,17 +3425,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__UINT_POINTERv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). - + filename="gobject/gmarshal.c" + line="2083">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2085">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="2086">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="2089">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="2090">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="2091">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="2094">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="2095">the #GType of each argument from @args. @@ -3396,17 +3493,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__UINTv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). - + filename="gobject/gmarshal.c" + line="653">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="655">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="656">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="659">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="660">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="661">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="664">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="665">the #GType of each argument from @args. @@ -3463,36 +3560,38 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="817">A #GClosureMarshal function for use with signals with a single +unsigned long integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="819">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="820">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="822">The length of the @param_values array. a #GValue array holding the instance and the #gulong parameter + filename="gobject/gmarshal.c" + line="823">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="825">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="827">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3520,17 +3621,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__ULONGv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). - + filename="gobject/gmarshal.c" + line="869">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="871">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="872">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="875">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="876">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="877">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="880">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="881">the #GType of each argument from @args. @@ -3585,39 +3686,40 @@ denotes a flags type. + c:identifier="g_cclosure_marshal_VOID__VARIANT"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1917">A #GClosureMarshal function for use with signals with a single +#GVariant argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1919">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1920">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1922">The length of the @param_values array. a #GValue array holding the instance and the #GVariant* parameter + filename="gobject/gmarshal.c" + line="1923">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1925">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1927">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3645,17 +3749,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__VARIANTv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). - + filename="gobject/gmarshal.c" + line="1969">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1971">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="1972">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="1975">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="1976">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="1977">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="1980">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="1981">the #GType of each argument from @args. @@ -3712,36 +3816,37 @@ denotes a flags type. A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="72">A #GClosureMarshal function for use with signals with no arguments. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="74">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="75">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 1 + filename="gobject/gmarshal.c" + line="77">The length of the @param_values array. a #GValue array holding only the instance + filename="gobject/gmarshal.c" + line="78">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="80">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="82">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -3769,17 +3876,17 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__VOIDv" introspectable="0"> The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). - + filename="gobject/gmarshal.c" + line="121">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="123">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gmarshal.c" + line="124">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. + filename="gobject/gmarshal.c" + line="127">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gmarshal.c" + line="128">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gmarshal.c" + line="129">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gmarshal.c" + line="132">the length of the @param_types array the #GType of each argument from + filename="gobject/gmarshal.c" + line="133">the #GType of each argument from @args. @@ -3837,40 +3944,40 @@ denotes a flags type. c:identifier="g_cclosure_marshal_generic" version="2.30"> A generic marshaller function implemented via + filename="gobject/gclosure.c" + line="1444">A generic marshaller function implemented via [libffi](http://sourceware.org/libffi/). Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a %NULL marshaller. - + A #GClosure. + filename="gobject/gclosure.c" + line="1446">A #GClosure. A #GValue to store the return value. May be %NULL + filename="gobject/gclosure.c" + line="1447">A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. + filename="gobject/gclosure.c" + line="1449">The length of the @param_values array. An array of #GValues holding the arguments + filename="gobject/gclosure.c" + line="1450">An array of #GValues holding the arguments on which to invoke the callback of closure. @@ -3879,8 +3986,8 @@ but used automatically by GLib when specifying a %NULL marshaller. nullable="1" allow-none="1"> The invocation hint given as the last argument to + filename="gobject/gclosure.c" + line="1452">The invocation hint given as the last argument to g_closure_invoke(). @@ -3889,8 +3996,8 @@ but used automatically by GLib when specifying a %NULL marshaller. nullable="1" allow-none="1"> Additional data specified when registering the + filename="gobject/gclosure.c" + line="1454">Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() @@ -3902,18 +4009,18 @@ but used automatically by GLib when specifying a %NULL marshaller. version="2.30" introspectable="0"> A generic #GVaClosureMarshal function implemented via + filename="gobject/gclosure.c" + line="1543">A generic #GVaClosureMarshal function implemented via [libffi](http://sourceware.org/libffi/). - + the #GClosure to which the marshaller belongs + filename="gobject/gclosure.c" + line="1545">the #GClosure to which the marshaller belongs nullable="1" allow-none="1"> a #GValue to store the return + filename="gobject/gclosure.c" + line="1546">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is + filename="gobject/gclosure.c" + line="1549">the instance on which the closure is invoked. va_list of arguments to be passed to the closure. + filename="gobject/gclosure.c" + line="1551">va_list of arguments to be passed to the closure. nullable="1" allow-none="1"> additional data specified when + filename="gobject/gclosure.c" + line="1552">additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array + filename="gobject/gclosure.c" + line="1555">the length of the @param_types array the #GType of each argument from + filename="gobject/gclosure.c" + line="1556">the #GType of each argument from @args_list. @@ -3970,43 +4077,40 @@ but used automatically by GLib when specifying a %NULL marshaller. Creates a new closure which invokes @callback_func with @user_data as + filename="gobject/gclosure.c" + line="957">Creates a new closure which invokes @callback_func with @user_data as the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - - + + a floating reference to a new #GCClosure + filename="gobject/gclosure.c" + line="968">a floating reference to a new #GCClosure the function to invoke + filename="gobject/gclosure.c" + line="959">the function to invoke + allow-none="1"> user data to pass to @callback_func + filename="gobject/gclosure.c" + line="960">user data to pass to @callback_func destroy notify to be called when @user_data is no longer used + filename="gobject/gclosure.c" + line="961">destroy notify to be called when @user_data is no longer used @@ -4015,30 +4119,30 @@ the last parameter. c:identifier="g_cclosure_new_object" introspectable="0"> A variant of g_cclosure_new() which uses @object as @user_data and + filename="gobject/gobject.c" + line="5330">A variant of g_cclosure_new() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - - + + a new #GCClosure + filename="gobject/gobject.c" + line="5341">a new #GCClosure the function to invoke + filename="gobject/gobject.c" + line="5332">the function to invoke a #GObject pointer to pass to @callback_func + filename="gobject/gobject.c" + line="5333">a #GObject pointer to pass to @callback_func @@ -4047,30 +4151,30 @@ after the object is is freed. c:identifier="g_cclosure_new_object_swap" introspectable="0"> A variant of g_cclosure_new_swap() which uses @object as @user_data + filename="gobject/gobject.c" + line="5359">A variant of g_cclosure_new_swap() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - - + + a new #GCClosure + filename="gobject/gobject.c" + line="5370">a new #GCClosure the function to invoke + filename="gobject/gobject.c" + line="5361">the function to invoke a #GObject pointer to pass to @callback_func + filename="gobject/gobject.c" + line="5362">a #GObject pointer to pass to @callback_func @@ -4079,43 +4183,40 @@ after the object is is freed. c:identifier="g_cclosure_new_swap" introspectable="0"> Creates a new closure which invokes @callback_func with @user_data as + filename="gobject/gclosure.c" + line="987">Creates a new closure which invokes @callback_func with @user_data as the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - - + + a floating reference to a new #GCClosure + filename="gobject/gclosure.c" + line="998">a floating reference to a new #GCClosure the function to invoke + filename="gobject/gclosure.c" + line="989">the function to invoke + allow-none="1"> user data to pass to @callback_func + filename="gobject/gclosure.c" + line="990">user data to pass to @callback_func destroy notify to be called when @user_data is no longer used + filename="gobject/gclosure.c" + line="991">destroy notify to be called when @user_data is no longer used @@ -4125,13 +4226,13 @@ the first parameter. c:identifier="G_CLOSURE_NEEDS_MARSHAL" introspectable="0"> Check if the closure still needs a marshaller. See g_closure_set_marshal(). - + a #GClosure @@ -4140,25 +4241,25 @@ the first parameter. c:identifier="G_CLOSURE_N_NOTIFIERS" introspectable="0"> Get the total number of notifiers connected with the closure @cl. The count includes the meta marshaller, the finalize and invalidate notifiers and the marshal guards. Note that each guard counts as two notifiers. See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). - + a #GClosure The type used for callback functions in structure definitions and function signatures. @@ -4167,15 +4268,20 @@ return void. The required signature of a callback function is determined by the context in which is used (e.g. the signal to which it is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. - + + + A callback function used by the type system to finalize a class. + filename="gobject/gtype.h" + line="949">A callback function used by the type system to finalize a class. This function is rarely needed, as dynamically allocated class resources should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). @@ -4184,15 +4290,15 @@ Also, specification of a GClassFinalizeFunc() in the #GTypeInfo structure of a static type is invalid, because classes of static types will never be finalized (they are artificially kept alive when their reference count drops to zero). - + The #GTypeClass structure to finalize + filename="gobject/gtype.h" + line="951">The #GTypeClass structure to finalize nullable="1" allow-none="1"> The @class_data member supplied via the #GTypeInfo structure + filename="gobject/gtype.h" + line="952">The @class_data member supplied via the #GTypeInfo structure A callback function used by the type system to initialize the class + filename="gobject/gtype.h" + line="844">A callback function used by the type system to initialize the class of a specific type. This function should initialize all static class members. @@ -4306,15 +4412,15 @@ is called to complete the initialization process with the static members Corresponding finalization counter parts to the GBaseInitFunc() functions have to be provided to release allocated resources at class finalization time. - + The #GTypeClass structure to initialize. + filename="gobject/gtype.h" + line="846">The #GTypeClass structure to initialize. nullable="1" allow-none="1"> The @class_data member supplied via the #GTypeInfo structure. + filename="gobject/gtype.h" + line="847">The @class_data member supplied via the #GTypeInfo structure. @@ -4334,8 +4440,8 @@ time. glib:get-type="g_closure_get_type" c:symbol-prefix="closure"> A #GClosure represents a callback supplied by the programmer. + filename="gobject/gclosure.c" + line="41">A `GClosure` represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to @@ -4379,7 +4485,7 @@ callback function/data pointer combination: - g_closure_invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away. - + @@ -4406,21 +4512,21 @@ callback function/data pointer combination: Indicates whether the closure is currently being invoked with - g_closure_invoke() + filename="gobject/gclosure.c" + line="43">Indicates whether the closure is currently being invoked with + g_closure_invoke() Indicates whether the closure has been invalidated by - g_closure_invalidate() + filename="gobject/gclosure.c" + line="45">Indicates whether the closure has been invalidated by + g_closure_invalidate() - + @@ -4454,30 +4560,30 @@ callback function/data pointer combination: A variant of g_closure_new_simple() which stores @object in the + filename="gobject/gobject.c" + line="5301">A variant of g_closure_new_simple() which stores @object in the @data field of the closure and calls g_object_watch_closure() on @object and the created closure. This function is mainly useful when implementing new types of closures. - - + + a newly allocated #GClosure + filename="gobject/gobject.c" + line="5313">a newly allocated #GClosure the size of the structure to allocate, must be at least + filename="gobject/gobject.c" + line="5303">the size of the structure to allocate, must be at least `sizeof (GClosure)` a #GObject pointer to store in the @data field of the newly + filename="gobject/gobject.c" + line="5305">a #GObject pointer to store in the @data field of the newly allocated #GClosure @@ -4485,8 +4591,8 @@ when implementing new types of closures. Allocates a struct of the given size and initializes the initial + filename="gobject/gclosure.c" + line="142">Allocates a struct of the given size and initializes the initial part as a #GClosure. This function is mainly useful when implementing new types of closures: @@ -4523,18 +4629,18 @@ MyClosure *my_closure_new (gpointer data) return my_closure; } ]| - - + + a floating reference to a new #GClosure + filename="gobject/gclosure.c" + line="186">a floating reference to a new #GClosure the size of the structure to allocate, must be at least + filename="gobject/gclosure.c" + line="144">the size of the structure to allocate, must be at least `sizeof (GClosure)` @@ -4543,8 +4649,8 @@ MyClosure *my_closure_new (gpointer data) nullable="1" allow-none="1"> data to store in the @data field of the newly allocated #GClosure + filename="gobject/gclosure.c" + line="146">data to store in the @data field of the newly allocated #GClosure @@ -4553,42 +4659,38 @@ MyClosure *my_closure_new (gpointer data) c:identifier="g_closure_add_finalize_notifier" introspectable="0"> Registers a finalization notifier which will be called when the + filename="gobject/gclosure.c" + line="426">Registers a finalization notifier which will be called when the reference count of @closure goes down to 0. Multiple finalization notifiers on a single closure are invoked in unspecified order. If a single call to g_closure_unref() results in the closure being both invalidated and finalized, then the invalidate notifiers will be run before the finalize notifiers. - + a #GClosure + filename="gobject/gclosure.c" + line="428">a #GClosure + allow-none="1"> data to pass to @notify_func + filename="gobject/gclosure.c" + line="429">data to pass to @notify_func - + the callback function to register + filename="gobject/gclosure.c" + line="430">the callback function to register @@ -4597,40 +4699,36 @@ notifiers will be run before the finalize notifiers. c:identifier="g_closure_add_invalidate_notifier" introspectable="0"> Registers an invalidation notifier which will be called when the + filename="gobject/gclosure.c" + line="463">Registers an invalidation notifier which will be called when the @closure is invalidated with g_closure_invalidate(). Invalidation notifiers are invoked before finalization notifiers, in an unspecified order. - + a #GClosure + filename="gobject/gclosure.c" + line="465">a #GClosure + allow-none="1"> data to pass to @notify_func + filename="gobject/gclosure.c" + line="466">data to pass to @notify_func - + the callback function to register + filename="gobject/gclosure.c" + line="467">the callback function to register @@ -4639,71 +4737,64 @@ in an unspecified order. c:identifier="g_closure_add_marshal_guards" introspectable="0"> Adds a pair of notifiers which get invoked before and after the + filename="gobject/gclosure.c" + line="365">Adds a pair of notifiers which get invoked before and after the closure callback, respectively. This is typically used to protect the extra arguments for the duration of the callback. See g_object_watch_closure() for an example of marshal guards. - + a #GClosure + filename="gobject/gclosure.c" + line="367">a #GClosure + allow-none="1"> data to pass + filename="gobject/gclosure.c" + line="368">data to pass to @pre_marshal_notify a function to call before the closure callback + filename="gobject/gclosure.c" + line="370">a function to call before the closure callback + allow-none="1"> data to pass + filename="gobject/gclosure.c" + line="371">data to pass to @post_marshal_notify - + a function to call after the closure callback + filename="gobject/gclosure.c" + line="373">a function to call after the closure callback Sets a flag on the closure to indicate that its calling + filename="gobject/gclosure.c" + line="572">Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of g_closure_invoke() on this @closure to be ignored. @@ -4718,32 +4809,32 @@ that you've previously called g_closure_ref(). Note that g_closure_invalidate() will also be called when the reference count of a closure drops to zero (unless it has already been invalidated before). - + #GClosure to invalidate + filename="gobject/gclosure.c" + line="574">#GClosure to invalidate Invokes the closure, i.e. executes the callback represented by the @closure. - + filename="gobject/gclosure.c" + line="784">Invokes the closure, i.e. executes the callback represented by the @closure. + a #GClosure + filename="gobject/gclosure.c" + line="786">a #GClosure optional="1" allow-none="1"> a #GValue to store the return + filename="gobject/gclosure.c" + line="787">a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the length of the @param_values array + filename="gobject/gclosure.c" + line="790">the length of the @param_values array an array of + filename="gobject/gclosure.c" + line="791">an array of #GValues holding the arguments on which to invoke the callback of @closure @@ -4780,29 +4871,29 @@ been invalidated before). nullable="1" allow-none="1"> a context-dependent invocation hint + filename="gobject/gclosure.c" + line="794">a context-dependent invocation hint Increments the reference count on a closure to force it staying + filename="gobject/gclosure.c" + line="538">Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it. - + The @closure passed in, for convenience + filename="gobject/gclosure.c" + line="545">The @closure passed in, for convenience #GClosure to increment the reference count on + filename="gobject/gclosure.c" + line="540">#GClosure to increment the reference count on @@ -4811,19 +4902,19 @@ alive while the caller holds a pointer to it. c:identifier="g_closure_remove_finalize_notifier" introspectable="0"> Removes a finalization notifier. + filename="gobject/gclosure.c" + line="756">Removes a finalization notifier. Notice that notifiers are automatically removed after they are run. - + a #GClosure + filename="gobject/gclosure.c" + line="758">a #GClosure nullable="1" allow-none="1"> data which was passed to g_closure_add_finalize_notifier() + filename="gobject/gclosure.c" + line="759">data which was passed to g_closure_add_finalize_notifier() when registering @notify_func the callback function to remove + filename="gobject/gclosure.c" + line="761">the callback function to remove @@ -4848,19 +4939,19 @@ Notice that notifiers are automatically removed after they are run. c:identifier="g_closure_remove_invalidate_notifier" introspectable="0"> Removes an invalidation notifier. + filename="gobject/gclosure.c" + line="728">Removes an invalidation notifier. Notice that notifiers are automatically removed after they are run. - + a #GClosure + filename="gobject/gclosure.c" + line="730">a #GClosure nullable="1" allow-none="1"> data which was passed to g_closure_add_invalidate_notifier() + filename="gobject/gclosure.c" + line="731">data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func the callback function to remove + filename="gobject/gclosure.c" + line="733">the callback function to remove @@ -4885,8 +4976,8 @@ Notice that notifiers are automatically removed after they are run. c:identifier="g_closure_set_marshal" introspectable="0"> Sets the marshaller of @closure. + filename="gobject/gclosure.c" + line="909">Sets the marshaller of @closure. The `marshal_data` of @marshal provides a way for a meta marshaller to provide additional information to the marshaller. @@ -4896,21 +4987,21 @@ functions), what it provides is a callback function to use instead of @closure->callback. See also: g_closure_set_meta_marshal() - + a #GClosure + filename="gobject/gclosure.c" + line="911">a #GClosure a #GClosureMarshal function + filename="gobject/gclosure.c" + line="912">a #GClosureMarshal function @@ -4919,8 +5010,8 @@ See also: g_closure_set_meta_marshal() c:identifier="g_closure_set_meta_marshal" introspectable="0"> Sets the meta marshaller of @closure. + filename="gobject/gclosure.c" + line="320">Sets the meta marshaller of @closure. A meta marshaller wraps the @closure's marshal and modifies the way it is called in some fashion. The most common use of this facility @@ -4937,43 +5028,39 @@ g_signal_type_cclosure_new()) retrieve the callback function from a fixed offset in the class structure. The meta marshaller retrieves the right callback and passes it to the marshaller as the @marshal_data argument. - + a #GClosure + filename="gobject/gclosure.c" + line="322">a #GClosure + allow-none="1"> context-dependent data to pass + filename="gobject/gclosure.c" + line="323">context-dependent data to pass to @meta_marshal - + a #GClosureMarshal function + filename="gobject/gclosure.c" + line="325">a #GClosureMarshal function Takes over the initial ownership of a closure. + filename="gobject/gclosure.c" + line="654">Takes over the initial ownership of a closure. Each closure is initially created in a "floating" state, which means that the initial reference count is not owned by any caller. @@ -5020,15 +5107,15 @@ foo_notify_set_closure (GClosure *closure) Because g_closure_sink() may decrement the reference count of a closure (if it hasn't been called on @closure yet) just like g_closure_unref(), g_closure_ref() should be called prior to this function. - + #GClosure to decrement the initial reference count on, if it's + filename="gobject/gclosure.c" + line="656">#GClosure to decrement the initial reference count on, if it's still being held @@ -5036,21 +5123,21 @@ g_closure_ref() should be called prior to this function. Decrements the reference count of a closure after it was previously + filename="gobject/gclosure.c" + line="605">Decrements the reference count of a closure after it was previously incremented by the same caller. If no other callers are using the closure, then the closure will be destroyed and freed. - + #GClosure to decrement the reference count on + filename="gobject/gclosure.c" + line="607">#GClosure to decrement the reference count on @@ -5058,16 +5145,16 @@ destroyed and freed. The type used for marshaller functions. - + the #GClosure to which the marshaller belongs @@ -5076,7 +5163,7 @@ destroyed and freed. nullable="1" allow-none="1"> a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. @@ -5084,13 +5171,13 @@ destroyed and freed. the length of the @param_values array an array of #GValues holding the arguments on which to invoke the callback of @closure @@ -5103,7 +5190,7 @@ destroyed and freed. nullable="1" allow-none="1"> the invocation hint given as the last argument to g_closure_invoke() @@ -5113,7 +5200,7 @@ destroyed and freed. nullable="1" allow-none="1"> additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() @@ -5123,10 +5210,10 @@ destroyed and freed. The type used for the various notification callbacks which can be registered on closures. - + @@ -5136,20 +5223,20 @@ on closures. nullable="1" allow-none="1"> data specified when registering the notification callback the #GClosure on which the notification is emitted - + @@ -5159,25 +5246,25 @@ on closures. The connection flags are used to specify the behaviour of a signal's connection. - + Default behaviour (no special flags). Since: 2.74 If set, the handler should be called after the default handler of the signal. Normally, the handler is called before the default handler. If set, the instance and data should be swapped when calling the handler; see g_signal_connect_swapped() for an example. @@ -5187,8 +5274,8 @@ connection. version="2.44" introspectable="0"> A convenience macro for emitting the usual declarations in the + filename="gobject/gtype.h" + line="1623">A convenience macro for emitting the usual declarations in the header file for a type which is intended to be subclassed. You might use it in a header as follows: @@ -5264,33 +5351,33 @@ structures, use G_DECLARE_FINAL_TYPE(). If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your class structure to leave space for the addition of future virtual functions. - + The name of the new type, in camel case (like `GtkWidget`) + filename="gobject/gtype.h" + line="1625">The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words + filename="gobject/gtype.h" + line="1626">The name of the new type in lowercase, with words separated by `_` (like `gtk_widget`) The name of the module, in all caps (like `GTK`) + filename="gobject/gtype.h" + line="1628">The name of the module, in all caps (like `GTK`) The bare name of the type, in all caps (like `WIDGET`) + filename="gobject/gtype.h" + line="1629">The bare name of the type, in all caps (like `WIDGET`) the name of the parent type, in camel case (like `GtkWidget`) + filename="gobject/gtype.h" + line="1630">the name of the parent type, in camel case (like `GtkWidget`) @@ -5299,8 +5386,8 @@ class structure to leave space for the addition of future virtual functions. A convenience macro for emitting the usual declarations in the header file + filename="gobject/gtype.h" + line="1531">A convenience macro for emitting the usual declarations in the header file for a type which is not (at the present time) intended to be subclassed. You might use it in a header as follows: @@ -5365,33 +5452,33 @@ G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be subclassed. Once a class structure has been exposed it is not possible to change its size or remove or reorder items without breaking the API and/or ABI. - + The name of the new type, in camel case (like `GtkWidget`) + filename="gobject/gtype.h" + line="1533">The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words + filename="gobject/gtype.h" + line="1534">The name of the new type in lowercase, with words separated by `_` (like `gtk_widget`) The name of the module, in all caps (like `GTK`) + filename="gobject/gtype.h" + line="1536">The name of the module, in all caps (like `GTK`) The bare name of the type, in all caps (like `WIDGET`) + filename="gobject/gtype.h" + line="1537">The bare name of the type, in all caps (like `WIDGET`) the name of the parent type, in camel case (like `GtkWidget`) + filename="gobject/gtype.h" + line="1538">the name of the parent type, in camel case (like `GtkWidget`) @@ -5400,8 +5487,8 @@ reorder items without breaking the API and/or ABI. version="2.44" introspectable="0"> A convenience macro for emitting the usual declarations in the header file for a #GInterface type. + filename="gobject/gtype.h" + line="1733">A convenience macro for emitting the usual declarations in the header file for a #GInterface type. You might use it in a header as follows: @@ -5459,33 +5546,33 @@ manually define this as a macro for yourself. The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. - + The name of the new type, in camel case (like `GtkWidget`) + filename="gobject/gtype.h" + line="1735">The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words + filename="gobject/gtype.h" + line="1736">The name of the new type in lowercase, with words separated by `_` (like `gtk_widget`) The name of the module, in all caps (like `GTK`) + filename="gobject/gtype.h" + line="1738">The name of the module, in all caps (like `GTK`) The bare name of the type, in all caps (like `WIDGET`) + filename="gobject/gtype.h" + line="1739">The bare name of the type, in all caps (like `WIDGET`) the name of the prerequisite type, in camel case (like `GtkWidget`) + filename="gobject/gtype.h" + line="1740">the name of the prerequisite type, in camel case (like `GtkWidget`) @@ -5494,28 +5581,28 @@ to be used in the usual way with export control and API versioning macros. version="2.4" introspectable="0"> A convenience macro for type implementations. + filename="gobject/gtype.h" + line="1877">A convenience macro for type implementations. Similar to G_DEFINE_TYPE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. - + The name of the new type, in Camel case. + filename="gobject/gtype.h" + line="1879">The name of the new type, in Camel case. The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="1880">The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. + filename="gobject/gtype.h" + line="1882">The #GType of the parent type. @@ -5524,36 +5611,36 @@ See G_DEFINE_TYPE_EXTENDED() for an example. version="2.4" introspectable="0"> A convenience macro for type implementations. + filename="gobject/gtype.h" + line="1892">A convenience macro for type implementations. Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to insert custom code into the `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. - + The name of the new type, in Camel case. + filename="gobject/gtype.h" + line="1894">The name of the new type, in Camel case. The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="1895">The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. + filename="gobject/gtype.h" + line="1897">The #GType of the parent type. Custom code that gets inserted in the `type_name_get_type()` function. + filename="gobject/gtype.h" + line="1898">Custom code that gets inserted in the `type_name_get_type()` function. @@ -5562,27 +5649,27 @@ See G_DEFINE_TYPE_EXTENDED() for an example. version="2.38" introspectable="0"> Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. + filename="gobject/gtype.h" + line="1911">Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. - + The name of the new type, in Camel case. + filename="gobject/gtype.h" + line="1913">The name of the new type, in Camel case. The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="1914">The name of the new type, in lowercase, with words separated by `_`. The #GType of the parent type. + filename="gobject/gtype.h" + line="1916">The #GType of the parent type. @@ -5591,8 +5678,8 @@ See G_DEFINE_TYPE_EXTENDED() for an example. version="2.26" introspectable="0"> A convenience macro for defining a new custom boxed type. + filename="gobject/gtype.h" + line="2377">A convenience macro for defining a new custom boxed type. Using this macro is the recommended way of defining new custom boxed types, over calling g_boxed_type_register_static() directly. It defines @@ -5644,28 +5731,28 @@ foo () my_struct_free (ms); } ]| - + The name of the new type, in Camel case + filename="gobject/gtype.h" + line="2379">The name of the new type, in Camel case The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="2380">The name of the new type, in lowercase, with words separated by `_` the #GBoxedCopyFunc for the new type + filename="gobject/gtype.h" + line="2382">the #GBoxedCopyFunc for the new type the #GBoxedFreeFunc for the new type + filename="gobject/gtype.h" + line="2383">the #GBoxedFreeFunc for the new type @@ -5674,8 +5761,8 @@ foo () version="2.26" introspectable="0"> A convenience macro for boxed type implementations. + filename="gobject/gtype.h" + line="2441">A convenience macro for boxed type implementations. Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the `type_name_get_type()` function, e.g. to register value transformations with @@ -5690,33 +5777,33 @@ G_DEFINE_BOXED_TYPE_WITH_CODE (GdkRectangle, gdk_rectangle, Similarly to the `G_DEFINE_TYPE_*` family of macros, the #GType of the newly defined boxed type is exposed in the `g_define_type_id` variable. - + The name of the new type, in Camel case + filename="gobject/gtype.h" + line="2443">The name of the new type, in Camel case The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="2444">The name of the new type, in lowercase, with words separated by `_` the #GBoxedCopyFunc for the new type + filename="gobject/gtype.h" + line="2446">the #GBoxedCopyFunc for the new type the #GBoxedFreeFunc for the new type + filename="gobject/gtype.h" + line="2447">the #GBoxedFreeFunc for the new type Custom code that gets inserted in the `*_get_type()` function + filename="gobject/gtype.h" + line="2448">Custom code that gets inserted in the `*_get_type()` function @@ -5725,8 +5812,8 @@ defined boxed type is exposed in the `g_define_type_id` variable. version="2.14" introspectable="0"> A convenience macro for dynamic type implementations, which declares a + filename="gobject/gtypemodule.h" + line="81">A convenience macro for dynamic type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named `t_n`_parent_class pointing to the parent class. @@ -5735,23 +5822,23 @@ Furthermore, it defines a `*_get_type()` and a static `*_register_type()` functions for use in your `module_init()`. See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. - + The name of the new type, in Camel case. + filename="gobject/gtypemodule.h" + line="83">The name of the new type, in Camel case. The name of the new type, in lowercase, with words + filename="gobject/gtypemodule.h" + line="84">The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. + filename="gobject/gtypemodule.h" + line="86">The #GType of the parent type. @@ -5760,8 +5847,8 @@ See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. version="2.14" introspectable="0"> A more general version of G_DEFINE_DYNAMIC_TYPE() which + filename="gobject/gtypemodule.h" + line="101">A more general version of G_DEFINE_DYNAMIC_TYPE() which allows to specify #GTypeFlags and custom code. |[<!-- language="C" --> @@ -5823,33 +5910,33 @@ gtk_gadget_register_type (GTypeModule *type_module) } } ]| - + The name of the new type, in Camel case. + filename="gobject/gtypemodule.h" + line="103">The name of the new type, in Camel case. The name of the new type, in lowercase, with words + filename="gobject/gtypemodule.h" + line="104">The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. + filename="gobject/gtypemodule.h" + line="106">The #GType of the parent type. #GTypeFlags to pass to g_type_module_register_type() + filename="gobject/gtypemodule.h" + line="107">#GTypeFlags to pass to g_type_module_register_type() Custom code that gets inserted in the *_get_type() function. + filename="gobject/gtypemodule.h" + line="108">Custom code that gets inserted in the *_get_type() function. @@ -5858,7 +5945,7 @@ gtk_gadget_register_type (GTypeModule *type_module) version="2.74" introspectable="0"> A convenience macro for defining enumeration types. This macro will generate a `*_get_type()` function for the @@ -5873,21 +5960,21 @@ G_DEFINE_ENUM_TYPE (GtkOrientation, gtk_orientation, For projects that have multiple enumeration types, or enumeration types with many values, you should consider using glib-mkenums to generate the type function. - + the enumeration type, in `CamelCase` the enumeration type prefixed, in `snake_case` a list of enumeration values, defined using G_DEFINE_ENUM_VALUE() @@ -5897,21 +5984,21 @@ generate the type function. version="2.74" introspectable="0"> Defines an enumeration value, and maps it to a "nickname". This macro can only be used with G_DEFINE_ENUM_TYPE() and G_DEFINE_FLAGS_TYPE(). - + an enumeration value a short string representing the enumeration value @@ -5921,29 +6008,29 @@ G_DEFINE_FLAGS_TYPE(). version="2.70" introspectable="0"> A convenience macro for type implementations. + filename="gobject/gtype.h" + line="1925">A convenience macro for type implementations. Similar to G_DEFINE_TYPE(), but defines a final type. See G_DEFINE_TYPE_EXTENDED() for an example. - + the name of the new type, in Camel case + filename="gobject/gtype.h" + line="1927">the name of the new type, in Camel case the name of the new type, in lower case, with words + filename="gobject/gtype.h" + line="1928">the name of the new type, in lower case, with words separated by `_` (snake case) the #GType of the parent type + filename="gobject/gtype.h" + line="1930">the #GType of the parent type @@ -5952,36 +6039,36 @@ See G_DEFINE_TYPE_EXTENDED() for an example. version="2.70" introspectable="0"> A convenience macro for type implementations. + filename="gobject/gtype.h" + line="1941">A convenience macro for type implementations. Similar to G_DEFINE_TYPE_WITH_CODE(), but defines a final type and allows you to insert custom code into the `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. - + the name of the new type, in Camel case + filename="gobject/gtype.h" + line="1943">the name of the new type, in Camel case the name of the new type, in lower case, with words + filename="gobject/gtype.h" + line="1944">the name of the new type, in lower case, with words separated by `_` (snake case) the #GType of the parent type + filename="gobject/gtype.h" + line="1946">the #GType of the parent type Custom code that gets inserted in the `type_name_get_type()` function. + filename="gobject/gtype.h" + line="1947">Custom code that gets inserted in the `type_name_get_type()` function. @@ -5990,29 +6077,29 @@ See G_DEFINE_TYPE_EXTENDED() for an example. version="2.70" introspectable="0"> A convenience macro for type implementations. + filename="gobject/gtype.h" + line="1960">A convenience macro for type implementations. Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines a final type. See G_DEFINE_TYPE_EXTENDED() for an example. - + the name of the new type, in Camel case + filename="gobject/gtype.h" + line="1962">the name of the new type, in Camel case the name of the new type, in lower case, with words + filename="gobject/gtype.h" + line="1963">the name of the new type, in lower case, with words separated by `_` (snake case) the #GType of the parent type + filename="gobject/gtype.h" + line="1965">the #GType of the parent type @@ -6021,7 +6108,7 @@ See G_DEFINE_TYPE_EXTENDED() for an example. version="2.74" introspectable="0"> A convenience macro for defining flag types. This macro will generate a `*_get_type()` function for the @@ -6040,21 +6127,21 @@ G_DEFINE_FLAGS_TYPE (GSettingsBindFlags, g_settings_bind_flags, For projects that have multiple enumeration types, or enumeration types with many values, you should consider using glib-mkenums to generate the type function. - + the enumeration type, in `CamelCase` the enumeration type prefixed, in `snake_case` a list of enumeration values, defined using G_DEFINE_ENUM_VALUE() @@ -6064,8 +6151,8 @@ generate the type function. version="2.24" introspectable="0"> A convenience macro for #GTypeInterface definitions, which declares + filename="gobject/gtype.h" + line="2055">A convenience macro for #GTypeInterface definitions, which declares a default vtable initialization function and defines a `*_get_type()` function. @@ -6078,22 +6165,22 @@ The initialization function has signature the full #GInterfaceInitFunc signature, for brevity and convenience. If you need to use an initialization function with an `iface_data` argument, you must write the #GTypeInterface definitions manually. - + The name of the new type, in Camel case. + filename="gobject/gtype.h" + line="2057">The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. + filename="gobject/gtype.h" + line="2058">The name of the new type, in lowercase, with words separated by `_`. The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID + filename="gobject/gtype.h" + line="2059">The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID for no prerequisite type. @@ -6103,8 +6190,8 @@ for no prerequisite type. version="2.24" introspectable="0"> A convenience macro for #GTypeInterface definitions. + filename="gobject/gtype.h" + line="2080">A convenience macro for #GTypeInterface definitions. Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code into the `*_get_type()` function, e.g. additional interface implementations @@ -6112,28 +6199,28 @@ via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See G_DEFINE_TYPE_EXTENDED() for a similar example using G_DEFINE_TYPE_WITH_CODE(). - + The name of the new type, in Camel case. + filename="gobject/gtype.h" + line="2082">The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by `_`. + filename="gobject/gtype.h" + line="2083">The name of the new type, in lowercase, with words separated by `_`. The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID + filename="gobject/gtype.h" + line="2084">The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID for no prerequisite type. Custom code that gets inserted in the `*_get_type()` function. + filename="gobject/gtype.h" + line="2086">Custom code that gets inserted in the `*_get_type()` function. @@ -6142,20 +6229,20 @@ for no prerequisite type. version="2.26" introspectable="0"> A convenience macro for pointer type implementations, which defines a + filename="gobject/gtype.h" + line="2538">A convenience macro for pointer type implementations, which defines a `type_name_get_type()` function registering the pointer type. - + The name of the new type, in Camel case + filename="gobject/gtype.h" + line="2540">The name of the new type, in Camel case The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="2541">The name of the new type, in lowercase, with words separated by `_` @@ -6165,249 +6252,1353 @@ for no prerequisite type. version="2.26" introspectable="0"> A convenience macro for pointer type implementations. + filename="gobject/gtype.h" + line="2550">A convenience macro for pointer type implementations. Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the `type_name_get_type()` function. - + The name of the new type, in Camel case + filename="gobject/gtype.h" + line="2552">The name of the new type, in Camel case The name of the new type, in lowercase, with words + filename="gobject/gtype.h" + line="2553">The name of the new type, in lowercase, with words separated by `_` Custom code that gets inserted in the `*_get_type()` function + filename="gobject/gtype.h" + line="2555">Custom code that gets inserted in the `*_get_type()` function + + + + + A convenience macro for type implementations, which declares a class +initialization function, an instance initialization function (see #GTypeInfo +for information about these) and a static variable named `t_n_parent_class` +pointing to the parent class. Furthermore, it defines a `*_get_type()` function. +See G_DEFINE_TYPE_EXTENDED() for an example. + + + + The name of the new type, in Camel case. + + + The name of the new type, in lowercase, with words + separated by `_`. + + + The #GType of the parent type. + + + + + The most general convenience macro for type implementations, on which +G_DEFINE_TYPE(), etc are based. + +|[<!-- language="C" --> +G_DEFINE_TYPE_EXTENDED (GtkGadget, + gtk_gadget, + GTK_TYPE_WIDGET, + 0, + G_ADD_PRIVATE (GtkGadget) + G_IMPLEMENT_INTERFACE (TYPE_GIZMO, + gtk_gadget_gizmo_init)); +]| + +expands to + +|[<!-- language="C" --> +static void gtk_gadget_init (GtkGadget *self); +static void gtk_gadget_class_init (GtkGadgetClass *klass); +static gpointer gtk_gadget_parent_class = NULL; +static gint GtkGadget_private_offset; +static void gtk_gadget_class_intern_init (gpointer klass) +{ + gtk_gadget_parent_class = g_type_class_peek_parent (klass); + if (GtkGadget_private_offset != 0) + g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset); + gtk_gadget_class_init ((GtkGadgetClass*) klass); +} +static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) +{ + return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset)); +} + +GType +gtk_gadget_get_type (void) +{ + static GType static_g_define_type_id = 0; + if (g_once_init_enter_pointer (&static_g_define_type_id)) + { + GType g_define_type_id = + g_type_register_static_simple (GTK_TYPE_WIDGET, + g_intern_static_string ("GtkGadget"), + sizeof (GtkGadgetClass), + (GClassInitFunc) gtk_gadget_class_intern_init, + sizeof (GtkGadget), + (GInstanceInitFunc) gtk_gadget_init, + 0); + { + GtkGadget_private_offset = + g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate)); + } + { + const GInterfaceInfo g_implement_interface_info = { + (GInterfaceInitFunc) gtk_gadget_gizmo_init + }; + g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + } + g_once_init_leave_pointer (&static_g_define_type_id, g_define_type_id); + } + return static_g_define_type_id; +} +]| + +The only pieces which have to be manually provided are the definitions of +the instance and class structure and the definitions of the instance and +class init functions. + + + + The name of the new type, in Camel case. + + + The name of the new type, in lowercase, with words + separated by `_`. + + + The #GType of the parent type. + + + #GTypeFlags to pass to g_type_register_static() + + + Custom code that gets inserted in the `*_get_type()` function. + + + + + A convenience macro for type implementations. + +Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the +`*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). +See G_DEFINE_TYPE_EXTENDED() for an example. + + + + The name of the new type, in Camel case. + + + The name of the new type in lowercase, with words separated by `_`. + + + The #GType of the parent type. + + + Custom code that gets inserted in the `*_get_type()` function. + + + + + A convenience macro for type implementations, which declares a class +initialization function, an instance initialization function (see #GTypeInfo +for information about these), a static variable named `t_n_parent_class` +pointing to the parent class, and adds private instance data to the type. + +Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() +for an example. + +Note that private structs added with this macros must have a struct +name of the form `TN ## Private`. + +The private instance data can be retrieved using the automatically generated +getter function `t_n_get_instance_private()`. + +See also: G_ADD_PRIVATE() + + + + The name of the new type, in Camel case. + + + The name of the new type, in lowercase, with words + separated by `_`. + + + The #GType of the parent type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - A convenience macro for type implementations, which declares a class -initialization function, an instance initialization function (see #GTypeInfo -for information about these) and a static variable named `t_n_parent_class` -pointing to the parent class. Furthermore, it defines a `*_get_type()` function. -See G_DEFINE_TYPE_EXTENDED() for an example. - + - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by `_`. - - - The #GType of the parent type. + - - The most general convenience macro for type implementations, on which -G_DEFINE_TYPE(), etc are based. - -|[<!-- language="C" --> -G_DEFINE_TYPE_EXTENDED (GtkGadget, - gtk_gadget, - GTK_TYPE_WIDGET, - 0, - G_ADD_PRIVATE (GtkGadget) - G_IMPLEMENT_INTERFACE (TYPE_GIZMO, - gtk_gadget_gizmo_init)); -]| - -expands to - -|[<!-- language="C" --> -static void gtk_gadget_init (GtkGadget *self); -static void gtk_gadget_class_init (GtkGadgetClass *klass); -static gpointer gtk_gadget_parent_class = NULL; -static gint GtkGadget_private_offset; -static void gtk_gadget_class_intern_init (gpointer klass) -{ - gtk_gadget_parent_class = g_type_class_peek_parent (klass); - if (GtkGadget_private_offset != 0) - g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset); - gtk_gadget_class_init ((GtkGadgetClass*) klass); -} -static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) -{ - return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset)); -} - -GType -gtk_gadget_get_type (void) -{ - static gsize static_g_define_type_id = 0; - if (g_once_init_enter (&static_g_define_type_id)) - { - GType g_define_type_id = - g_type_register_static_simple (GTK_TYPE_WIDGET, - g_intern_static_string ("GtkGadget"), - sizeof (GtkGadgetClass), - (GClassInitFunc) gtk_gadget_class_intern_init, - sizeof (GtkGadget), - (GInstanceInitFunc) gtk_gadget_init, - 0); - { - GtkGadget_private_offset = - g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate)); - } - { - const GInterfaceInfo g_implement_interface_info = { - (GInterfaceInitFunc) gtk_gadget_gizmo_init - }; - g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - } - g_once_init_leave (&static_g_define_type_id, g_define_type_id); - } - return static_g_define_type_id; -} -]| - -The only pieces which have to be manually provided are the definitions of -the instance and class structure and the definitions of the instance and -class init functions. - + - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by `_`. - - - The #GType of the parent type. - - - #GTypeFlags to pass to g_type_register_static() - - - Custom code that gets inserted in the `*_get_type()` function. + - - A convenience macro for type implementations. - -Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the -`*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). -See G_DEFINE_TYPE_EXTENDED() for an example. - + - - The name of the new type, in Camel case. - - - The name of the new type in lowercase, with words separated by `_`. - - - The #GType of the parent type. - - - Custom code that gets inserted in the `*_get_type()` function. + - - A convenience macro for type implementations, which declares a class -initialization function, an instance initialization function (see #GTypeInfo -for information about these), a static variable named `t_n_parent_class` -pointing to the parent class, and adds private instance data to the type. - -Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() -for an example. - -Note that private structs added with this macros must have a struct -name of the form `TN ## Private`. - -The private instance data can be retrieved using the automatically generated -getter function `t_n_get_instance_private()`. - -See also: G_ADD_PRIVATE() - + - - The name of the new type, in Camel case. + - - The name of the new type, in lowercase, with words - separated by `_`. + + + + + + - - The #GType of the parent type. + + + + + + + + + + + + Casts a derived #GEnumClass structure into a #GEnumClass structure. - + a valid #GEnumClass @@ -6416,13 +7607,13 @@ See also: G_ADD_PRIVATE() c:identifier="G_ENUM_CLASS_TYPE" introspectable="0"> Get the type identifier from a given #GEnumClass structure. - + a #GEnumClass @@ -6431,50 +7622,50 @@ See also: G_ADD_PRIVATE() c:identifier="G_ENUM_CLASS_TYPE_NAME" introspectable="0"> Get the static type name from a given #GEnumClass structure. - + a #GEnumClass The class of an enumeration type holds information about its possible values. - + the parent class the smallest possible value. the largest possible value. the number of possible values. an array of #GEnumValue structs describing the individual values. @@ -6482,40 +7673,45 @@ possible values. A structure which contains a single enum value, its name, and its nickname. - + the enum value the name of the value the nickname of the value + + Casts a derived #GFlagsClass structure into a #GFlagsClass structure. - + a valid #GFlagsClass @@ -6524,13 +7720,13 @@ nickname. c:identifier="G_FLAGS_CLASS_TYPE" introspectable="0"> Get the type identifier from a given #GFlagsClass structure. - + a #GFlagsClass @@ -6539,44 +7735,44 @@ nickname. c:identifier="G_FLAGS_CLASS_TYPE_NAME" introspectable="0"> Get the static type name from a given #GFlagsClass structure. - + a #GFlagsClass The class of a flags type holds information about its possible values. - + the parent class a mask covering all possible values. the number of possible values. an array of #GFlagsValue structs describing the individual values. @@ -6584,52 +7780,62 @@ possible values. A structure which contains a single flags value, its name, and its nickname. - + the flags value the name of the value the nickname of the value + + + + A convenience macro to ease interface addition in the `_C_` section + filename="gobject/gtype.h" + line="2101">A convenience macro to ease interface addition in the `_C_` section of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). See G_DEFINE_TYPE_EXTENDED() for an example. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` macros, since it depends on variable names from those macros. - + The #GType of the interface to add + filename="gobject/gtype.h" + line="2103">The #GType of the interface to add The interface init function, of type #GInterfaceInitFunc + filename="gobject/gtype.h" + line="2104">The interface init function, of type #GInterfaceInitFunc @@ -6638,8 +7844,8 @@ macros, since it depends on variable names from those macros. version="2.24" introspectable="0"> A convenience macro to ease interface addition in the @_C_ section + filename="gobject/gtypemodule.h" + line="222">A convenience macro to ease interface addition in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. @@ -6647,17 +7853,17 @@ See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. Note that this macro can only be used together with the G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable names from that macro. - + The #GType of the interface to add + filename="gobject/gtypemodule.h" + line="224">The #GType of the interface to add The interface init function + filename="gobject/gtypemodule.h" + line="225">The interface init function @@ -6665,17 +7871,17 @@ names from that macro. c:identifier="G_INITIALLY_UNOWNED" introspectable="0"> Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) pointer. Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts. - + Object which is subject to casting. @@ -6684,14 +7890,14 @@ certain runtime checks to identify invalid casts. c:identifier="G_INITIALLY_UNOWNED_CLASS" introspectable="0"> Casts a derived #GInitiallyUnownedClass structure into a #GInitiallyUnownedClass structure. - + a valid #GInitiallyUnownedClass @@ -6700,21 +7906,67 @@ certain runtime checks to identify invalid casts. c:identifier="G_INITIALLY_UNOWNED_GET_CLASS" introspectable="0"> Get the class structure associated to a #GInitiallyUnowned instance. - + a #GInitiallyUnowned instance. + + + + + + + + + + + + + + + + - + @@ -6723,7 +7975,7 @@ certain runtime checks to identify invalid casts. - + @@ -6733,14 +7985,14 @@ certain runtime checks to identify invalid casts. c:identifier="G_IS_ENUM_CLASS" introspectable="0"> Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM or derived. - + a #GEnumClass @@ -6749,14 +8001,14 @@ or derived. c:identifier="G_IS_FLAGS_CLASS" introspectable="0"> Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS or derived. - + a #GFlagsClass @@ -6765,13 +8017,13 @@ or derived. c:identifier="G_IS_INITIALLY_UNOWNED" introspectable="0"> Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. - + Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. @@ -6780,14 +8032,14 @@ or derived. c:identifier="G_IS_INITIALLY_UNOWNED_CLASS" introspectable="0"> Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type %G_TYPE_INITIALLY_UNOWNED or derived. - + a #GInitiallyUnownedClass @@ -6796,13 +8048,13 @@ or derived. c:identifier="G_IS_OBJECT" introspectable="0"> Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. - + Instance to check for being a %G_TYPE_OBJECT. @@ -6811,14 +8063,14 @@ or derived. c:identifier="G_IS_OBJECT_CLASS" introspectable="0"> Checks whether @class "is a" valid #GObjectClass structure of type %G_TYPE_OBJECT or derived. - + a #GObjectClass @@ -6827,14 +8079,14 @@ or derived. c:identifier="G_IS_PARAM_SPEC" introspectable="0"> Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM or derived. - + a #GParamSpec @@ -6843,13 +8095,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_BOOLEAN" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. - + a valid #GParamSpec instance @@ -6858,13 +8110,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_BOXED" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. - + a valid #GParamSpec instance @@ -6873,13 +8125,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_CHAR" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. - + a valid #GParamSpec instance @@ -6888,14 +8140,14 @@ or derived. c:identifier="G_IS_PARAM_SPEC_CLASS" introspectable="0"> Checks whether @pclass "is a" valid #GParamSpecClass structure of type %G_TYPE_PARAM or derived. - + a #GParamSpecClass @@ -6904,13 +8156,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_DOUBLE" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. - + a valid #GParamSpec instance @@ -6919,13 +8171,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_ENUM" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. - + a valid #GParamSpec instance @@ -6934,13 +8186,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_FLAGS" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. - + a valid #GParamSpec instance @@ -6949,13 +8201,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_FLOAT" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. - + a valid #GParamSpec instance @@ -6965,13 +8217,13 @@ or derived. version="2.10" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. - + a #GParamSpec @@ -6980,13 +8232,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_INT" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. - + a valid #GParamSpec instance @@ -6995,13 +8247,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_INT64" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. - + a valid #GParamSpec instance @@ -7010,13 +8262,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_LONG" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. - + a valid #GParamSpec instance @@ -7025,13 +8277,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_OBJECT" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. - + a valid #GParamSpec instance @@ -7041,13 +8293,13 @@ or derived. version="2.4" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. - + a #GParamSpec @@ -7056,13 +8308,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_PARAM" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. - + a valid #GParamSpec instance @@ -7071,13 +8323,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_POINTER" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. - + a valid #GParamSpec instance @@ -7086,13 +8338,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_STRING" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. - + a valid #GParamSpec instance @@ -7101,13 +8353,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_UCHAR" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. - + a valid #GParamSpec instance @@ -7116,13 +8368,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_UINT" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. - + a valid #GParamSpec instance @@ -7131,13 +8383,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_UINT64" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. - + a valid #GParamSpec instance @@ -7146,13 +8398,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_ULONG" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. - + a valid #GParamSpec instance @@ -7161,13 +8413,13 @@ or derived. c:identifier="G_IS_PARAM_SPEC_UNICHAR" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. - + a valid #GParamSpec instance @@ -7178,14 +8430,14 @@ or derived. deprecated="1" deprecated-version="2.32"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. Use #GArray instead of #GValueArray - + a valid #GParamSpec instance @@ -7195,13 +8447,13 @@ or derived. version="2.26" introspectable="0"> Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. - + a #GParamSpec @@ -7209,7 +8461,7 @@ or derived. - + @@ -7218,7 +8470,7 @@ or derived. - + @@ -7227,7 +8479,7 @@ or derived. - + @@ -7236,7 +8488,7 @@ or derived. - + @@ -7245,7 +8497,7 @@ or derived. - + @@ -7255,13 +8507,13 @@ or derived. c:identifier="G_IS_VALUE" introspectable="0"> Checks if @value is a valid and initialized #GValue structure. - + A #GValue structure. @@ -7274,12 +8526,12 @@ or derived. glib:get-type="g_initially_unowned_get_type" glib:type-struct="InitiallyUnownedClass"> A type for objects that have an initially floating reference. + filename="gobject/gobject.h" + line="382">A type for objects that have an initially floating reference. All the fields in the `GInitiallyUnowned` structure are private to the implementation and should never be accessed directly. - + @@ -7294,13 +8546,13 @@ implementation and should never be accessed directly. c:type="GInitiallyUnownedClass" glib:is-gtype-struct-for="InitiallyUnowned"> The class structure for the GInitiallyUnowned type. - + filename="gobject/gobject.h" + line="390">The class structure for the GInitiallyUnowned type. + the parent class + filename="gobject/gobject.h" + line="262">the parent class @@ -7309,8 +8561,15 @@ implementation and should never be accessed directly. + the @constructor function is called by g_object_new () to + complete the object initialization after all the construction properties are + set. The first thing a @constructor implementation must do is chain up to the + @constructor of the parent class. Overriding @constructor should be rarely + needed, e.g. to handle construct properties, or to implement singletons. - + @@ -7329,8 +8588,15 @@ implementation and should never be accessed directly. + the generic setter for all properties of this type. Should be + overridden for every type with properties. If implementations of + @set_property don't emit property change notification explicitly, this will + be done implicitly by the type system. However, if the notify signal is + emitted explicitly, the type system will not emit it a second time. - + @@ -7351,8 +8617,12 @@ implementation and should never be accessed directly. + the generic getter for all properties of this type. Should be + overridden for every type with properties. - + @@ -7373,8 +8643,15 @@ implementation and should never be accessed directly. + the @dispose function is supposed to drop all references to other + objects, but keep the instance otherwise intact, so that client method + invocations still work. It may be run multiple times (due to reference + loops). Before returning, @dispose should chain up to the @dispose method + of the parent class. - + @@ -7386,8 +8663,13 @@ implementation and should never be accessed directly. + instance finalization function, should finish the finalization of + the instance begun in @dispose and chain up to the @finalize method of the + parent class. - + @@ -7399,8 +8681,13 @@ implementation and should never be accessed directly. + emits property change notification for a bunch + of properties. Overriding @dispatch_properties_changed should be rarely + needed. - + @@ -7418,16 +8705,19 @@ implementation and should never be accessed directly. + the class closure for the notify signal - + a #GObject + filename="gobject/gobject.c" + line="1944">a #GObject @@ -7437,8 +8727,17 @@ implementation and should never be accessed directly. + the @constructed function is called by g_object_new() as the + final step of the object creation process. At the point of the call, all + construction properties have been set on the object. The purpose of this + call is to allow for object initialisation steps that can only be performed + after construction properties have been set. @constructed implementors + should chain up to the @constructed call of their parent class to allow it + to complete its initialisation. - + @@ -7469,8 +8768,8 @@ implementation and should never be accessed directly. A callback function used by the type system to initialize a new + filename="gobject/gtype.h" + line="966">A callback function used by the type system to initialize a new instance of a type. This function initializes all instance members and allocates any resources @@ -7483,21 +8782,21 @@ belongs to the type the current initializer was introduced for. The extended members of @instance are guaranteed to have been filled with zeros before this function is called. - + The instance to initialize + filename="gobject/gtype.h" + line="968">The instance to initialize The class of the type the instance is + filename="gobject/gtype.h" + line="969">The class of the type the instance is created for @@ -7505,20 +8804,20 @@ zeros before this function is called. A callback function used by the type system to finalize an interface. + filename="gobject/gtype.h" + line="1004">A callback function used by the type system to finalize an interface. This function should destroy any internal data and release any resources allocated by the corresponding GInterfaceInitFunc() function. - + The interface structure to finalize + filename="gobject/gtype.h" + line="1006">The interface structure to finalize nullable="1" allow-none="1"> The @interface_data supplied via the #GInterfaceInfo structure + filename="gobject/gtype.h" + line="1007">The @interface_data supplied via the #GInterfaceInfo structure A structure that provides information to the type system which is + filename="gobject/gtype.h" + line="1158">A structure that provides information to the type system which is used specifically for managing interface types. - + location of the interface initialization function + filename="gobject/gtype.h" + line="1160">location of the interface initialization function location of the interface finalization function + filename="gobject/gtype.h" + line="1161">location of the interface finalization function user-supplied data passed to the interface init/finalize functions + filename="gobject/gtype.h" + line="1162">user-supplied data passed to the interface init/finalize functions A callback function used by the type system to initialize a new + filename="gobject/gtype.h" + line="988">A callback function used by the type system to initialize a new interface. This function should initialize all internal data and* allocate any @@ -7568,15 +8867,15 @@ resources required by the interface. The members of @iface_data are guaranteed to have been filled with zeros before this function is called. - + The interface structure to initialize + filename="gobject/gtype.h" + line="990">The interface structure to initialize nullable="1" allow-none="1"> The @interface_data supplied via the #GInterfaceInfo structure + filename="gobject/gtype.h" + line="991">The @interface_data supplied via the #GInterfaceInfo structure + + + + + + + + + + + + Casts a #GObject or derived pointer into a (GObject*) pointer. Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts. - + Object which is subject to casting. @@ -7610,13 +8939,13 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_CLASS" introspectable="0"> Casts a derived #GObjectClass structure into a #GObjectClass structure. - + a valid #GObjectClass @@ -7625,13 +8954,13 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_CLASS_NAME" introspectable="0"> Return the name of a class structure's type. - + a valid #GObjectClass @@ -7640,13 +8969,13 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_CLASS_TYPE" introspectable="0"> Get the type id of a class structure. - + a valid #GObjectClass @@ -7655,13 +8984,13 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_GET_CLASS" introspectable="0"> Get the class structure associated to a #GObject instance. - + a #GObject instance. @@ -7670,13 +8999,13 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_TYPE" introspectable="0"> Get the type id of an object. - + Object to return the type id for. @@ -7685,13 +9014,13 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_TYPE_NAME" introspectable="0"> Get the name of an object's type. - + Object to return the type name for. @@ -7700,32 +9029,32 @@ certain runtime checks to identify invalid casts. c:identifier="G_OBJECT_WARN_INVALID_PROPERTY_ID" introspectable="0"> This macro should be used to emit a standard warning about unexpected + filename="gobject/gobject.h" + line="681">This macro should be used to emit a standard warning about unexpected properties in set_property() and get_property() implementations. - + the #GObject on which set_property() or get_property() was called + filename="gobject/gobject.h" + line="683">the #GObject on which set_property() or get_property() was called the numeric id of the property + filename="gobject/gobject.h" + line="684">the numeric id of the property the #GParamSpec of the property + filename="gobject/gobject.h" + line="685">the #GParamSpec of the property - + @@ -7744,24 +9073,34 @@ properties in set_property() and get_property() implementations. glib:get-type="g_object_get_type" glib:type-struct="ObjectClass"> The base object type. + filename="gobject/gobject.c" + line="40">The base object type. -All the fields in the `GObject` structure are private to the implementation -and should never be accessed directly. +`GObject` is the fundamental type providing the common attributes and +methods for all object types in GTK, Pango and other libraries +based on GObject. The `GObject` class provides methods for object +construction and destruction, property access methods, and signal +support. Signals are described in detail [here][gobject-Signals]. -Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the -alignment of the largest basic GLib type (typically this is #guint64 or -#gdouble). If you need larger alignment for an element in a #GObject, you -should allocate it on the heap (aligned), or arrange for your #GObject to be -appropriately padded. This guarantee applies to the #GObject (or derived) -struct, the #GObjectClass (or derived) struct, and any private data allocated -by G_ADD_PRIVATE(). - +For a tutorial on implementing a new `GObject` class, see [How to define and +implement a new GObject](tutorial.html#how-to-define-and-implement-a-new-gobject). +For a list of naming conventions for GObjects and their methods, see the +[GType conventions](concepts.html#conventions). For the high-level concepts +behind GObject, read +[Instantiatable classed types: Objects](concepts.html#instantiatable-classed-types-objects). + +Since GLib 2.72, all `GObject`s are guaranteed to be aligned to at least the +alignment of the largest basic GLib type (typically this is `guint64` or +`gdouble`). If you need larger alignment for an element in a `GObject`, you +should allocate it on the heap (aligned), or arrange for your `GObject` to be +appropriately padded. This guarantee applies to the `GObject` (or derived) +struct, the `GObjectClass` (or derived) struct, and any private data allocated +by `G_ADD_PRIVATE()`. + Creates a new instance of a #GObject subtype and sets its properties. + filename="gobject/gobject.c" + line="2376">Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. Any @@ -7787,31 +9126,31 @@ alignment of the largest basic GLib type (typically this is `guint64` or `gdouble`). If you need larger alignment for an element in a #GObject, you should allocate it on the heap (aligned), or arrange for your #GObject to be appropriately padded. - + a new instance of + filename="gobject/gobject.c" + line="2410">a new instance of @object_type the type id of the #GObject subtype to instantiate + filename="gobject/gobject.c" + line="2378">the type id of the #GObject subtype to instantiate the name of the first property + filename="gobject/gobject.c" + line="2379">the name of the first property the value of the first property, followed optionally by more + filename="gobject/gobject.c" + line="2380">the value of the first property, followed optionally by more name/value pairs, followed by %NULL @@ -7821,35 +9160,35 @@ appropriately padded. c:identifier="g_object_new_valist" introspectable="0"> Creates a new instance of a #GObject subtype and sets its properties. + filename="gobject/gobject.c" + line="2855">Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. - + a new instance of @object_type + filename="gobject/gobject.c" + line="2867">a new instance of @object_type the type id of the #GObject subtype to instantiate + filename="gobject/gobject.c" + line="2857">the type id of the #GObject subtype to instantiate the name of the first property + filename="gobject/gobject.c" + line="2858">the name of the first property the value of the first property, followed optionally by more + filename="gobject/gobject.c" + line="2859">the value of the first property, followed optionally by more name/value pairs, followed by %NULL @@ -7860,46 +9199,46 @@ which are not explicitly specified are set to their default values. version="2.54" introspectable="0"> Creates a new instance of a #GObject subtype and sets its properties using + filename="gobject/gobject.c" + line="2720">Creates a new instance of a #GObject subtype and sets its properties using the provided arrays. Both arrays must have exactly @n_properties elements, and the names and values correspond by index. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. - + a new instance of + filename="gobject/gobject.c" + line="2734">a new instance of @object_type the object type to instantiate + filename="gobject/gobject.c" + line="2722">the object type to instantiate the number of properties + filename="gobject/gobject.c" + line="2723">the number of properties the names of each property to be set + filename="gobject/gobject.c" + line="2724">the names of each property to be set the values of each property to be set + filename="gobject/gobject.c" + line="2725">the values of each property to be set @@ -7911,38 +9250,38 @@ which are not explicitly specified are set to their default values. deprecated="1" deprecated-version="2.54"> Creates a new instance of a #GObject subtype and sets its properties. + filename="gobject/gobject.c" + line="2785">Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. Use g_object_new_with_properties() instead. deprecated. See #GParameter for more information. - + a new instance of + filename="gobject/gobject.c" + line="2796">a new instance of @object_type the type id of the #GObject subtype to instantiate + filename="gobject/gobject.c" + line="2787">the type id of the #GObject subtype to instantiate the length of the @parameters array + filename="gobject/gobject.c" + line="2788">the length of the @parameters array an array of #GParameter + filename="gobject/gobject.c" + line="2789">an array of #GParameter @@ -7950,7 +9289,7 @@ deprecated. See #GParameter for more information. - + @@ -7970,17 +9309,17 @@ deprecated. See #GParameter for more information. c:identifier="g_object_interface_find_property" version="2.4"> Find the #GParamSpec with the given name for an + filename="gobject/gobject.c" + line="1463">Find the #GParamSpec with the given name for an interface. Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). - + the #GParamSpec for the property of the + filename="gobject/gobject.c" + line="1477">the #GParamSpec for the property of the interface with the name @property_name, or %NULL if no such property exists. @@ -7988,15 +9327,15 @@ g_type_default_interface_peek(). any interface vtable for the + filename="gobject/gobject.c" + line="1465">any interface vtable for the interface, or the default vtable for the interface name of a property to look up. + filename="gobject/gobject.c" + line="1467">name of a property to look up. @@ -8005,8 +9344,8 @@ g_type_default_interface_peek(). c:identifier="g_object_interface_install_property" version="2.4"> Add a property to an interface; this is only useful for interfaces + filename="gobject/gobject.c" + line="1383">Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly @@ -8022,23 +9361,23 @@ vtable initialization function (the @class_init member of been called for any object types implementing this interface. If @pspec is a floating reference, it will be consumed. - + any interface vtable for the + filename="gobject/gobject.c" + line="1385">any interface vtable for the interface, or the default vtable for the interface. the #GParamSpec for the new property + filename="gobject/gobject.c" + line="1388">the #GParamSpec for the new property @@ -8047,20 +9386,20 @@ If @pspec is a floating reference, it will be consumed. c:identifier="g_object_interface_list_properties" version="2.4"> Lists the properties of an interface.Generally, the interface + filename="gobject/gobject.c" + line="1603">Lists the properties of an interface.Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). - + a - pointer to an array of pointers to #GParamSpec - structures. The paramspecs are owned by GLib, but the - array should be freed with g_free() when you are done with - it. + filename="gobject/gobject.c" + line="1616">a + pointer to an array of pointers to #GParamSpec + structures. The paramspecs are owned by GLib, but the + array should be freed with g_free() when you are done with + it. @@ -8068,8 +9407,8 @@ already been loaded, g_type_default_interface_peek(). any interface vtable for the + filename="gobject/gobject.c" + line="1605">any interface vtable for the interface, or the default vtable for the interface @@ -8078,14 +9417,23 @@ already been loaded, g_type_default_interface_peek(). caller-allocates="0" transfer-ownership="full"> location to store number of properties returned. + filename="gobject/gobject.c" + line="1607">location to store number of properties returned. - + the @constructed function is called by g_object_new() as the + final step of the object creation process. At the point of the call, all + construction properties have been set on the object. The purpose of this + call is to allow for object initialisation steps that can only be performed + after construction properties have been set. @constructed implementors + should chain up to the @constructed call of their parent class to allow it + to complete its initialisation. + @@ -8096,7 +9444,12 @@ already been loaded, g_type_default_interface_peek(). - + emits property change notification for a bunch + of properties. Overriding @dispatch_properties_changed should be rarely + needed. + @@ -8113,7 +9466,14 @@ already been loaded, g_type_default_interface_peek(). - + the @dispose function is supposed to drop all references to other + objects, but keep the instance otherwise intact, so that client method + invocations still work. It may be run multiple times (due to reference + loops). Before returning, @dispose should chain up to the @dispose method + of the parent class. + @@ -8124,7 +9484,12 @@ already been loaded, g_type_default_interface_peek(). - + instance finalization function, should finish the finalization of + the instance begun in @dispose and chain up to the @finalize method of the + parent class. + @@ -8135,7 +9500,11 @@ already been loaded, g_type_default_interface_peek(). - + the generic getter for all properties of this type. Should be + overridden for every type with properties. + @@ -8156,8 +9525,8 @@ already been loaded, g_type_default_interface_peek(). Emits a "notify" signal for the property @property_name on @object. + filename="gobject/gobject.c" + line="1942">Emits a "notify" signal for the property @property_name on @object. When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() @@ -8167,15 +9536,15 @@ Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called. - + a #GObject + filename="gobject/gobject.c" + line="1944">a #GObject @@ -8184,7 +9553,14 @@ called. - + the generic setter for all properties of this type. Should be + overridden for every type with properties. If implementations of + @set_property don't emit property change notification explicitly, this will + be done implicitly by the type system. However, if the notify signal is + emitted explicitly, the type system will not emit it a second time. + @@ -8208,8 +9584,8 @@ called. version="2.8" introspectable="0"> Increases the reference count of the object by one and sets a + filename="gobject/gobject.c" + line="4029">Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established. @@ -8236,22 +9612,29 @@ Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there -is important state in the proxy object. - +is important state in the proxy object. + +Note that if you unref the object on another thread, then @notify might +still be invoked after g_object_remove_toggle_ref(), and the object argument +might be a dangling pointer. If the object is destroyed on other threads, +you must take care of that yourself. + +A g_object_add_toggle_ref() must be released with g_object_remove_toggle_ref(). + a #GObject + filename="gobject/gobject.c" + line="4031">a #GObject a function to call when this reference is the + filename="gobject/gobject.c" + line="4032">a function to call when this reference is the last reference to the object, or is no longer the last reference. @@ -8261,8 +9644,8 @@ is important state in the proxy object. nullable="1" allow-none="1"> data to pass to @notify + filename="gobject/gobject.c" + line="4035">data to pass to @notify @@ -8271,8 +9654,8 @@ is important state in the proxy object. c:identifier="g_object_add_weak_pointer" introspectable="0"> Adds a weak reference from weak_pointer to @object to indicate that + filename="gobject/gobject.c" + line="3751">Adds a weak reference from weak_pointer to @object to indicate that the pointer located at @weak_pointer_location is only valid during the lifetime of @object. When the @object is finalized, @weak_pointer will be set to %NULL. @@ -8281,15 +9664,15 @@ Note that as with g_object_weak_ref(), the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use #GWeakRef if thread-safety is required. - + The object that should be weak referenced. + filename="gobject/gobject.c" + line="3753">The object that should be weak referenced. caller-allocates="0" transfer-ownership="full"> The memory address + filename="gobject/gobject.c" + line="3754">The memory address of a pointer. @@ -8308,8 +9691,8 @@ thread. Use #GWeakRef if thread-safety is required. c:identifier="g_object_bind_property" version="2.26"> Creates a binding between @source_property on @source and @target_property + filename="gobject/gbinding.c" + line="1369">Creates a binding between @source_property on @source and @target_property on @target. Whenever the @source_property is changed the @target_property is @@ -8340,11 +9723,11 @@ finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side. A #GObject can have multiple bindings. - + the #GBinding instance representing the + filename="gobject/gbinding.c" + line="1409">the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. @@ -8352,32 +9735,32 @@ A #GObject can have multiple bindings. the source #GObject + filename="gobject/gbinding.c" + line="1371">the source #GObject the property on @source to bind + filename="gobject/gbinding.c" + line="1372">the property on @source to bind the target #GObject + filename="gobject/gbinding.c" + line="1373">the target #GObject the property on @target to bind + filename="gobject/gbinding.c" + line="1374">the property on @target to bind flags to pass to #GBinding + filename="gobject/gbinding.c" + line="1375">flags to pass to #GBinding @@ -8387,8 +9770,8 @@ A #GObject can have multiple bindings. shadowed-by="bind_property_with_closures" version="2.26"> Complete version of g_object_bind_property(). + filename="gobject/gbinding.c" + line="1172">Complete version of g_object_bind_property(). Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by @@ -8413,11 +9796,11 @@ and @transform_from transformation functions; the @notify function will be called once, when the binding is removed. If you need different data for each transformation function, please use g_object_bind_property_with_closures() instead. - + the #GBinding instance representing the + filename="gobject/gbinding.c" + line="1214">the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. @@ -8425,32 +9808,32 @@ g_object_bind_property_with_closures() instead. the source #GObject + filename="gobject/gbinding.c" + line="1174">the source #GObject the property on @source to bind + filename="gobject/gbinding.c" + line="1175">the property on @source to bind the target #GObject + filename="gobject/gbinding.c" + line="1176">the target #GObject the property on @target to bind + filename="gobject/gbinding.c" + line="1177">the property on @target to bind flags to pass to #GBinding + filename="gobject/gbinding.c" + line="1178">flags to pass to #GBinding allow-none="1" scope="notified"> the transformation function + filename="gobject/gbinding.c" + line="1179">the transformation function from the @source to the @target, or %NULL to use the default @@ -8472,8 +9855,8 @@ g_object_bind_property_with_closures() instead. closure="6" destroy="7"> the transformation function + filename="gobject/gbinding.c" + line="1181">the transformation function from the @target to the @source, or %NULL to use the default @@ -8482,8 +9865,8 @@ g_object_bind_property_with_closures() instead. nullable="1" allow-none="1"> custom data to be passed to the transformation functions, + filename="gobject/gbinding.c" + line="1183">custom data to be passed to the transformation functions, or %NULL @@ -8493,8 +9876,8 @@ g_object_bind_property_with_closures() instead. allow-none="1" scope="async"> a function to call when disposing the binding, to free + filename="gobject/gbinding.c" + line="1185">a function to call when disposing the binding, to free resources used by the transformation functions, or %NULL if not required @@ -8505,19 +9888,19 @@ g_object_bind_property_with_closures() instead. shadows="bind_property_full" version="2.26"> Creates a binding between @source_property on @source and @target_property + filename="gobject/gbinding.c" + line="1538">Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding. This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers. - + the #GBinding instance representing the + filename="gobject/gbinding.c" + line="1558">the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. @@ -8525,45 +9908,45 @@ function pointers. the source #GObject + filename="gobject/gbinding.c" + line="1540">the source #GObject the property on @source to bind + filename="gobject/gbinding.c" + line="1541">the property on @source to bind the target #GObject + filename="gobject/gbinding.c" + line="1542">the target #GObject the property on @target to bind + filename="gobject/gbinding.c" + line="1543">the property on @target to bind flags to pass to #GBinding + filename="gobject/gbinding.c" + line="1544">flags to pass to #GBinding a #GClosure wrapping the transformation function + filename="gobject/gbinding.c" + line="1545">a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default a #GClosure wrapping the transformation function + filename="gobject/gbinding.c" + line="1547">a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default @@ -8573,56 +9956,58 @@ function pointers. c:identifier="g_object_connect" introspectable="0"> A convenience function to connect multiple signals at once. + filename="gobject/gobject.c" + line="3473">A convenience function to connect multiple signals at once. The signal specs expected by this function have the form -"modifier::signal_name", where modifier can be one of the following: -- signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT) -- object-signal, object_signal: equivalent to g_signal_connect_object (..., G_CONNECT_DEFAULT) -- swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) -- swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) -- signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) -- object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) -- swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) -- swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) - -|[<!-- language="C" --> - menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, - "type", GTK_WINDOW_POPUP, - "child", menu, - NULL), - "signal::event", gtk_menu_window_event, menu, - "signal::size_request", gtk_menu_window_size_request, menu, - "signal::destroy", gtk_widget_destroyed, &menu->toplevel, - NULL); -]| - +`modifier::signal_name`, where `modifier` can be one of the +following: + +- `signal`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT)` +- `object-signal`, `object_signal`: equivalent to `g_signal_connect_object (..., G_CONNECT_DEFAULT)` +- `swapped-signal`, `swapped_signal`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)` +- `swapped_object_signal`, `swapped-object-signal`: equivalent to `g_signal_connect_object (..., G_CONNECT_SWAPPED)` +- `signal_after`, `signal-after`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_AFTER)` +- `object_signal_after`, `object-signal-after`: equivalent to `g_signal_connect_object (..., G_CONNECT_AFTER)` +- `swapped_signal_after`, `swapped-signal-after`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)` +- `swapped_object_signal_after`, `swapped-object-signal-after`: equivalent to `g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)` + +```c +menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, + "type", GTK_WINDOW_POPUP, + "child", menu, + NULL), + "signal::event", gtk_menu_window_event, menu, + "signal::size_request", gtk_menu_window_size_request, menu, + "signal::destroy", gtk_widget_destroyed, &menu->toplevel, + NULL); +``` + @object + filename="gobject/gobject.c" + line="3507">the object a #GObject + filename="gobject/gobject.c" + line="3475">a #GObject the spec for the first signal + filename="gobject/gobject.c" + line="3476">the spec for the first signal #GCallback for the first signal, followed by data for the - first signal, followed optionally by more signal - spec/callback/data triples, followed by %NULL + filename="gobject/gobject.c" + line="3477">[type@GObject.Callback] for the first signal, followed by data for the + first signal, followed optionally by more signal + spec/callback/data triples, followed by `NULL` @@ -8631,34 +10016,34 @@ The signal specs expected by this function have the form c:identifier="g_object_disconnect" introspectable="0"> A convenience function to disconnect multiple signals at once. + filename="gobject/gobject.c" + line="3577">A convenience function to disconnect multiple signals at once. The signal specs expected by this function have the form "any_signal", which means to disconnect any signal with matching callback and data, or "any_signal::signal_name", which only disconnects the signal named "signal_name". - + a #GObject + filename="gobject/gobject.c" + line="3579">a #GObject the spec for the first signal + filename="gobject/gobject.c" + line="3580">the spec for the first signal #GCallback for the first signal, followed by data for the first signal, + filename="gobject/gobject.c" + line="3581">#GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL @@ -8670,8 +10055,8 @@ disconnects the signal named "signal_name". version="2.34" introspectable="0"> This is a variant of g_object_get_data() which returns + filename="gobject/gobject.c" + line="4795">This is a variant of g_object_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. @@ -8685,11 +10070,11 @@ is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. - + the result of calling @dup_func on the value + filename="gobject/gobject.c" + line="4817">the result of calling @dup_func on the value associated with @key on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. @@ -8698,14 +10083,14 @@ object. the #GObject to store user data on + filename="gobject/gobject.c" + line="4797">the #GObject to store user data on a string, naming the user data pointer + filename="gobject/gobject.c" + line="4798">a string, naming the user data pointer allow-none="1" closure="2"> function to dup the value + filename="gobject/gobject.c" + line="4799">function to dup the value nullable="1" allow-none="1"> passed as user_data to @dup_func + filename="gobject/gobject.c" + line="4800">passed as user_data to @dup_func @@ -8734,8 +10119,8 @@ object. version="2.34" introspectable="0"> This is a variant of g_object_get_qdata() which returns + filename="gobject/gobject.c" + line="4582">This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. @@ -8749,11 +10134,11 @@ is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. - + the result of calling @dup_func on the value + filename="gobject/gobject.c" + line="4604">the result of calling @dup_func on the value associated with @quark on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. @@ -8762,14 +10147,14 @@ object. the #GObject to store user data on + filename="gobject/gobject.c" + line="4584">the #GObject to store user data on a #GQuark, naming the user data pointer + filename="gobject/gobject.c" + line="4585">a #GQuark, naming the user data pointer allow-none="1" closure="2"> function to dup the value + filename="gobject/gobject.c" + line="4586">function to dup the value nullable="1" allow-none="1"> passed as user_data to @dup_func + filename="gobject/gobject.c" + line="4587">passed as user_data to @dup_func @@ -8797,28 +10182,28 @@ object. c:identifier="g_object_force_floating" version="2.10"> This function is intended for #GObject implementations to re-enforce + filename="gobject/gobject.c" + line="3937">This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink(). - + a #GObject + filename="gobject/gobject.c" + line="3939">a #GObject Increases the freeze count on @object. If the freeze count is + filename="gobject/gobject.c" + line="1864">Increases the freeze count on @object. If the freeze count is non-zero, the emission of "notify" signals on @object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one @@ -8827,23 +10212,23 @@ object is frozen. This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified. - + a #GObject + filename="gobject/gobject.c" + line="1866">a #GObject Gets properties of an object. + filename="gobject/gobject.c" + line="3329">Gets properties of an object. In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for @@ -8869,27 +10254,27 @@ of three properties: an integer, a string and an object: g_free (strval); g_object_unref (objval); ]| - + a #GObject + filename="gobject/gobject.c" + line="3331">a #GObject name of the first property to get + filename="gobject/gobject.c" + line="3332">name of the first property to get return location for the first property, followed optionally by more + filename="gobject/gobject.c" + line="3333">return location for the first property, followed optionally by more name/return location pairs, followed by %NULL @@ -8897,35 +10282,35 @@ of three properties: an integer, a string and an object: Gets a named field from the objects table of associations (see g_object_set_data()). - + filename="gobject/gobject.c" + line="4747">Gets a named field from the objects table of associations (see g_object_set_data()). + the data if found, + filename="gobject/gobject.c" + line="4754">the data if found, or %NULL if no such data exists. #GObject containing the associations + filename="gobject/gobject.c" + line="4749">#GObject containing the associations name of the key for that association + filename="gobject/gobject.c" + line="4750">name of the key for that association Gets a property of an object. + filename="gobject/gobject.c" + line="3394">Gets a property of an object. The @value can be: @@ -8941,54 +10326,54 @@ responsible for freeing the memory by calling g_value_unset(). Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming. - + a #GObject + filename="gobject/gobject.c" + line="3396">a #GObject the name of the property to get + filename="gobject/gobject.c" + line="3397">the name of the property to get return location for the property value + filename="gobject/gobject.c" + line="3398">return location for the property value This function gets back user data pointers stored via + filename="gobject/gobject.c" + line="4537">This function gets back user data pointers stored via g_object_set_qdata(). - + The user data pointer set, or %NULL + filename="gobject/gobject.c" + line="4545">The user data pointer set, or %NULL The GObject to get a stored user data pointer from + filename="gobject/gobject.c" + line="4539">The GObject to get a stored user data pointer from A #GQuark, naming the user data pointer + filename="gobject/gobject.c" + line="4540">A #GQuark, naming the user data pointer @@ -8997,35 +10382,35 @@ g_object_set_qdata(). c:identifier="g_object_get_valist" introspectable="0"> Gets properties of an object. + filename="gobject/gobject.c" + line="3233">Gets properties of an object. In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling g_free() or g_object_unref(). See g_object_get(). - + a #GObject + filename="gobject/gobject.c" + line="3235">a #GObject name of the first property to get + filename="gobject/gobject.c" + line="3236">name of the first property to get return location for the first property, followed optionally by more + filename="gobject/gobject.c" + line="3237">return location for the first property, followed optionally by more name/return location pairs, followed by %NULL @@ -9033,40 +10418,40 @@ See g_object_get(). Gets @n_properties properties for an @object. + filename="gobject/gobject.c" + line="3186">Gets @n_properties properties for an @object. Obtained properties will be set to @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in. - + a #GObject + filename="gobject/gobject.c" + line="3188">a #GObject the number of properties + filename="gobject/gobject.c" + line="3189">the number of properties the names of each property to get + filename="gobject/gobject.c" + line="3190">the names of each property to get the values of each property to get + filename="gobject/gobject.c" + line="3191">the values of each property to get @@ -9077,28 +10462,28 @@ properties are passed in. c:identifier="g_object_is_floating" version="2.10"> Checks whether @object has a [floating][floating-ref] reference. - + filename="gobject/gobject.c" + line="3829">Checks whether @object has a [floating][floating-ref] reference. + %TRUE if @object has a floating reference + filename="gobject/gobject.c" + line="3837">%TRUE if @object has a floating reference a #GObject + filename="gobject/gobject.c" + line="3831">a #GObject Emits a "notify" signal for the property @property_name on @object. + filename="gobject/gobject.c" + line="1942">Emits a "notify" signal for the property @property_name on @object. When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() @@ -9108,21 +10493,21 @@ Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called. - + a #GObject + filename="gobject/gobject.c" + line="1944">a #GObject the name of a property installed on the class of @object. + filename="gobject/gobject.c" + line="1945">the name of a property installed on the class of @object. @@ -9131,8 +10516,8 @@ called. c:identifier="g_object_notify_by_pspec" version="2.26"> Emits a "notify" signal for the property specified by @pspec on @object. + filename="gobject/gobject.c" + line="1985">Emits a "notify" signal for the property specified by @pspec on @object. This function omits the property name lookup, hence it is faster than g_object_notify(). @@ -9154,7 +10539,7 @@ g_object_class_install_property() inside a static array, e.g.: static void my_object_class_init (MyObjectClass *klass) { - properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", + properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL, 0, 100, 50, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -9169,54 +10554,54 @@ and then notify a change on the "foo" property with: |[<!-- language="C" --> g_object_notify_by_pspec (self, properties[PROP_FOO]); ]| - + a #GObject + filename="gobject/gobject.c" + line="1987">a #GObject the #GParamSpec of a property installed on the class of @object. + filename="gobject/gobject.c" + line="1988">the #GParamSpec of a property installed on the class of @object. Increases the reference count of @object. + filename="gobject/gobject.c" + line="4228">Increases the reference count of @object. Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type of @object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit. - + the same @object + filename="gobject/gobject.c" + line="4239">the same @object a #GObject + filename="gobject/gobject.c" + line="4230">a #GObject Increase the reference count of @object, and possibly remove the + filename="gobject/gobject.c" + line="3847">Increase the reference count of @object, and possibly remove the [floating][floating-ref] reference, if @object has a floating reference. In other words, if the object is floating, then this call "assumes @@ -9227,18 +10612,18 @@ adds a new normal reference increasing the reference count by one. Since GLib 2.56, the type of @object will be propagated to the return type under the same conditions as for g_object_ref(). - + @object + filename="gobject/gobject.c" + line="3865">@object a #GObject + filename="gobject/gobject.c" + line="3849">a #GObject @@ -9248,24 +10633,29 @@ under the same conditions as for g_object_ref(). version="2.8" introspectable="0"> Removes a reference added with g_object_add_toggle_ref(). The -reference count of the object is decreased by one. - + filename="gobject/gobject.c" + line="4116">Removes a reference added with g_object_add_toggle_ref(). The +reference count of the object is decreased by one. + +Note that if you unref the object on another thread, then @notify might +still be invoked after g_object_remove_toggle_ref(), and the object argument +might be a dangling pointer. If the object is destroyed on other threads, +you must take care of that yourself. + a #GObject + filename="gobject/gobject.c" + line="4118">a #GObject a function to call when this reference is the + filename="gobject/gobject.c" + line="4119">a function to call when this reference is the last reference to the object, or is no longer the last reference. @@ -9275,8 +10665,8 @@ reference count of the object is decreased by one. nullable="1" allow-none="1"> data to pass to @notify, or %NULL to + filename="gobject/gobject.c" + line="4122">data to pass to @notify, or %NULL to match any toggle refs with the @notify argument. @@ -9286,19 +10676,19 @@ reference count of the object is decreased by one. c:identifier="g_object_remove_weak_pointer" introspectable="0"> Removes a weak reference from @object that was previously added + filename="gobject/gobject.c" + line="3779">Removes a weak reference from @object that was previously added using g_object_add_weak_pointer(). The @weak_pointer_location has to match the one used with g_object_add_weak_pointer(). - + The object that is weak referenced. + filename="gobject/gobject.c" + line="3781">The object that is weak referenced. caller-allocates="0" transfer-ownership="full"> The memory address + filename="gobject/gobject.c" + line="3782">The memory address of a pointer. @@ -9318,8 +10708,8 @@ to match the one used with g_object_add_weak_pointer(). version="2.34" introspectable="0"> Compares the user data for the key @key on @object with + filename="gobject/gobject.c" + line="4838">Compares the user data for the key @key on @object with @oldval, and if they are the same, replaces @oldval with @newval. @@ -9335,25 +10725,25 @@ should not destroy the object in the normal way. See g_object_set_data() for guidance on using a small, bounded set of values for @key. - + %TRUE if the existing value for @key was replaced + filename="gobject/gobject.c" + line="4864">%TRUE if the existing value for @key was replaced by @newval, %FALSE otherwise. the #GObject to store user data on + filename="gobject/gobject.c" + line="4840">the #GObject to store user data on a string, naming the user data pointer + filename="gobject/gobject.c" + line="4841">a string, naming the user data pointer nullable="1" allow-none="1"> the old value to compare against + filename="gobject/gobject.c" + line="4842">the old value to compare against nullable="1" allow-none="1"> the new value + filename="gobject/gobject.c" + line="4843">the new value allow-none="1" scope="async"> a destroy notify for the new value + filename="gobject/gobject.c" + line="4844">a destroy notify for the new value allow-none="1" scope="async"> destroy notify for the existing value + filename="gobject/gobject.c" + line="4845">destroy notify for the existing value @@ -9403,8 +10793,8 @@ for @key. version="2.34" introspectable="0"> Compares the user data for the key @quark on @object with + filename="gobject/gobject.c" + line="4623">Compares the user data for the key @quark on @object with @oldval, and if they are the same, replaces @oldval with @newval. @@ -9417,25 +10807,25 @@ the registered destroy notify for it (passed out in @old_destroy). It’s up to the caller to free this as needed, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. - + %TRUE if the existing value for @quark was replaced + filename="gobject/gobject.c" + line="4646">%TRUE if the existing value for @quark was replaced by @newval, %FALSE otherwise. the #GObject to store user data on + filename="gobject/gobject.c" + line="4625">the #GObject to store user data on a #GQuark, naming the user data pointer + filename="gobject/gobject.c" + line="4626">a #GQuark, naming the user data pointer nullable="1" allow-none="1"> the old value to compare against + filename="gobject/gobject.c" + line="4627">the old value to compare against nullable="1" allow-none="1"> the new value + filename="gobject/gobject.c" + line="4628">the new value allow-none="1" scope="async"> a destroy notify for the new value + filename="gobject/gobject.c" + line="4629">a destroy notify for the new value allow-none="1" scope="async"> destroy notify for the existing value + filename="gobject/gobject.c" + line="4630">destroy notify for the existing value Releases all references to other objects. This can be used to break + filename="gobject/gobject.c" + line="1830">Releases all references to other objects. This can be used to break reference cycles. This function should only be called from object system implementations. - + a #GObject + filename="gobject/gobject.c" + line="1832">a #GObject Sets properties on an object. + filename="gobject/gobject.c" + line="3296">Sets properties on an object. The same caveats about passing integer literals as varargs apply as with g_object_new(). In particular, any integer literals set as the values for @@ -9513,27 +10903,27 @@ properties of type #gint64 or #guint64 must be 64 bits wide, using the Note that the "notify" signals are queued and only emitted (in reverse order) after all properties have been set. See g_object_freeze_notify(). - + a #GObject + filename="gobject/gobject.c" + line="3298">a #GObject name of the first property to set + filename="gobject/gobject.c" + line="3299">name of the first property to set value for the first property, followed optionally by more + filename="gobject/gobject.c" + line="3300">value for the first property, followed optionally by more name/value pairs, followed by %NULL @@ -9541,8 +10931,8 @@ g_object_freeze_notify(). Each object carries around a table of associations from + filename="gobject/gobject.c" + line="4767">Each object carries around a table of associations from strings to pointers. This function lets you set an association. If the object already had an association with that name, @@ -9552,21 +10942,21 @@ Internally, the @key is converted to a #GQuark using g_quark_from_string(). This means a copy of @key is kept permanently (even after @object has been finalized) — so it is recommended to only use a small, bounded set of values for @key in your program, to avoid the #GQuark storage growing unbounded. - + #GObject containing the associations. + filename="gobject/gobject.c" + line="4769">#GObject containing the associations. name of the key + filename="gobject/gobject.c" + line="4770">name of the key nullable="1" allow-none="1"> data to associate with that key + filename="gobject/gobject.c" + line="4771">data to associate with that key @@ -9584,27 +10974,27 @@ for @key in your program, to avoid the #GQuark storage growing unbounded. c:identifier="g_object_set_data_full" introspectable="0"> Like g_object_set_data() except it adds notification + filename="gobject/gobject.c" + line="4886">Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed. Note that the @destroy callback is not called if @data is %NULL. - + #GObject containing the associations + filename="gobject/gobject.c" + line="4888">#GObject containing the associations name of the key + filename="gobject/gobject.c" + line="4889">name of the key nullable="1" allow-none="1"> data to associate with that key + filename="gobject/gobject.c" + line="4890">data to associate with that key allow-none="1" scope="async"> function to call when the association is destroyed + filename="gobject/gobject.c" + line="4891">function to call when the association is destroyed Sets a property on an object. - + filename="gobject/gobject.c" + line="3378">Sets a property on an object. + a #GObject + filename="gobject/gobject.c" + line="3380">a #GObject the name of the property to set + filename="gobject/gobject.c" + line="3381">the name of the property to set the value + filename="gobject/gobject.c" + line="3382">the value @@ -9661,8 +11051,8 @@ Note that the @destroy callback is not called if @data is %NULL. c:identifier="g_object_set_qdata" introspectable="0"> This sets an opaque, named pointer on an object. + filename="gobject/gobject.c" + line="4556">This sets an opaque, named pointer on an object. The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @object with g_object_get_qdata() @@ -9670,21 +11060,21 @@ until the @object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using #NULL as pointer essentially removes the data stored. - + The GObject to set store a user data pointer + filename="gobject/gobject.c" + line="4558">The GObject to set store a user data pointer A #GQuark, naming the user data pointer + filename="gobject/gobject.c" + line="4559">A #GQuark, naming the user data pointer nullable="1" allow-none="1"> An opaque user data pointer + filename="gobject/gobject.c" + line="4560">An opaque user data pointer @@ -9702,27 +11092,27 @@ removes the data stored. c:identifier="g_object_set_qdata_full" introspectable="0"> This function works like g_object_set_qdata(), but in addition, + filename="gobject/gobject.c" + line="4667">This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with @data as argument when the @object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same @quark. - + The GObject to set store a user data pointer + filename="gobject/gobject.c" + line="4669">The GObject to set store a user data pointer A #GQuark, naming the user data pointer + filename="gobject/gobject.c" + line="4670">A #GQuark, naming the user data pointer nullable="1" allow-none="1"> An opaque user data pointer + filename="gobject/gobject.c" + line="4671">An opaque user data pointer allow-none="1" scope="async"> Function to invoke with @data as argument, when @data + filename="gobject/gobject.c" + line="4672">Function to invoke with @data as argument, when @data needs to be freed @@ -9751,29 +11141,29 @@ with the same @quark. c:identifier="g_object_set_valist" introspectable="0"> Sets properties on an object. - + filename="gobject/gobject.c" + line="3100">Sets properties on an object. + a #GObject + filename="gobject/gobject.c" + line="3102">a #GObject name of the first property to set + filename="gobject/gobject.c" + line="3103">name of the first property to set value for the first property, followed optionally by more + filename="gobject/gobject.c" + line="3104">value for the first property, followed optionally by more name/value pairs, followed by %NULL @@ -9784,40 +11174,40 @@ with the same @quark. version="2.54" introspectable="0"> Sets @n_properties properties for an @object. + filename="gobject/gobject.c" + line="3047">Sets @n_properties properties for an @object. Properties to be set will be taken from @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in. - + a #GObject + filename="gobject/gobject.c" + line="3049">a #GObject the number of properties + filename="gobject/gobject.c" + line="3050">the number of properties the names of each property to be set + filename="gobject/gobject.c" + line="3051">the names of each property to be set the values of each property to be set + filename="gobject/gobject.c" + line="3052">the values of each property to be set @@ -9826,36 +11216,36 @@ properties are passed in. Remove a specified datum from the object's data associations, + filename="gobject/gobject.c" + line="4912">Remove a specified datum from the object's data associations, without invoking the association's destroy handler. - + the data if found, or %NULL + filename="gobject/gobject.c" + line="4920">the data if found, or %NULL if no such data exists. #GObject containing the associations + filename="gobject/gobject.c" + line="4914">#GObject containing the associations name of the key + filename="gobject/gobject.c" + line="4915">name of the key This function gets back user data pointers stored via + filename="gobject/gobject.c" + line="4694">This function gets back user data pointers stored via g_object_set_qdata() and removes the @data from object without invoking its destroy() function (if any was set). @@ -9890,24 +11280,24 @@ Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full(). - + The user data pointer set, or %NULL + filename="gobject/gobject.c" + line="4735">The user data pointer set, or %NULL The GObject to get a stored user data pointer from + filename="gobject/gobject.c" + line="4696">The GObject to get a stored user data pointer from A #GQuark, naming the user data pointer + filename="gobject/gobject.c" + line="4697">A #GQuark, naming the user data pointer @@ -9917,8 +11307,8 @@ g_object_set_qdata_full(). version="2.70" introspectable="0"> If @object is floating, sink it. Otherwise, do nothing. + filename="gobject/gobject.c" + line="3881">If @object is floating, sink it. Otherwise, do nothing. In other words, this function will convert a floating reference (if present) into a full reference. @@ -9941,7 +11331,7 @@ return a floating reference. Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller will -alway receives exactly one full reference to the value: either the +always receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference. @@ -9953,26 +11343,26 @@ reference. If g_object_take_ref() runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation. - + @object + filename="gobject/gobject.c" + line="3923">@object a #GObject + filename="gobject/gobject.c" + line="3883">a #GObject Reverts the effect of a previous call to + filename="gobject/gobject.c" + line="2041">Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on @object and when it reaches zero, queued "notify" signals are emitted. @@ -9981,46 +11371,46 @@ Duplicate notifications for each property are squashed so that at most one in which they have been queued. It is an error to call this function when the freeze count is zero. - + a #GObject + filename="gobject/gobject.c" + line="2043">a #GObject Decreases the reference count of @object. When its reference count + filename="gobject/gobject.c" + line="4313">Decreases the reference count of @object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed). If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this. - + a #GObject + filename="gobject/gobject.c" + line="4315">a #GObject This function essentially limits the life time of the @closure to + filename="gobject/gobject.c" + line="5250">This function essentially limits the life time of the @closure to the life time of the object. That is, when the object is finalized, the @closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized @@ -10029,21 +11419,21 @@ added as marshal guards to the @closure, to ensure that an extra reference count is held on @object during invocation of the @closure. Usually, this function will be called on closures that use this @object as closure data. - + #GObject restricting lifetime of @closure + filename="gobject/gobject.c" + line="5252">#GObject restricting lifetime of @closure #GClosure to watch + filename="gobject/gobject.c" + line="5253">#GClosure to watch @@ -10052,8 +11442,8 @@ use this @object as closure data. c:identifier="g_object_weak_ref" introspectable="0"> Adds a weak reference callback to an object. Weak references are + filename="gobject/gobject.c" + line="3660">Adds a weak reference callback to an object. Weak references are used for notification when an object is disposed. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a @@ -10063,21 +11453,21 @@ Note that the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use #GWeakRef if thread-safety is required. - + #GObject to reference weakly + filename="gobject/gobject.c" + line="3662">#GObject to reference weakly callback to invoke before the object is freed + filename="gobject/gobject.c" + line="3663">callback to invoke before the object is freed nullable="1" allow-none="1"> extra data to pass to notify + filename="gobject/gobject.c" + line="3664">extra data to pass to notify @@ -10095,23 +11485,23 @@ Use #GWeakRef if thread-safety is required. c:identifier="g_object_weak_unref" introspectable="0"> Removes a weak reference callback to an object. - + filename="gobject/gobject.c" + line="3709">Removes a weak reference callback to an object. + #GObject to remove a weak reference from + filename="gobject/gobject.c" + line="3711">#GObject to remove a weak reference from callback to search for + filename="gobject/gobject.c" + line="3712">callback to search for nullable="1" allow-none="1"> data to search for + filename="gobject/gobject.c" + line="3713">data to search for @@ -10141,8 +11531,8 @@ Use #GWeakRef if thread-safety is required. action="1" no-hooks="1"> The notify signal is emitted on an object when one of its properties has + filename="gobject/gobject.c" + line="1003">The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al. Note that getting this signal doesn’t itself guarantee that the value of @@ -10165,7 +11555,7 @@ g_signal_connect (text_view->buffer, "notify::paste-target-list", ]| It is important to note that you must use -[canonical parameter names][canonical-parameter-names] as +[canonical parameter names][class@GObject.ParamSpec#parameter-names] as detail strings for the notify signal. @@ -10173,8 +11563,8 @@ detail strings for the notify signal. the #GParamSpec of the property which changed. + filename="gobject/gobject.c" + line="1006">the #GParamSpec of the property which changed. @@ -10184,8 +11574,8 @@ detail strings for the notify signal. c:type="GObjectClass" glib:is-gtype-struct-for="Object"> The class structure for the GObject type. + filename="gobject/gobject.h" + line="260">The class structure for the GObject type. |[<!-- language="C" --> // Example of implementing a singleton using a constructor. @@ -10211,11 +11601,11 @@ my_singleton_constructor (GType type, return object; } ]| - + the parent class + filename="gobject/gobject.h" + line="262">the parent class @@ -10224,8 +11614,15 @@ my_singleton_constructor (GType type, + the @constructor function is called by g_object_new () to + complete the object initialization after all the construction properties are + set. The first thing a @constructor implementation must do is chain up to the + @constructor of the parent class. Overriding @constructor should be rarely + needed, e.g. to handle construct properties, or to implement singletons. - + @@ -10244,8 +11641,15 @@ my_singleton_constructor (GType type, + the generic setter for all properties of this type. Should be + overridden for every type with properties. If implementations of + @set_property don't emit property change notification explicitly, this will + be done implicitly by the type system. However, if the notify signal is + emitted explicitly, the type system will not emit it a second time. - + @@ -10266,8 +11670,12 @@ my_singleton_constructor (GType type, + the generic getter for all properties of this type. Should be + overridden for every type with properties. - + @@ -10288,8 +11696,15 @@ my_singleton_constructor (GType type, + the @dispose function is supposed to drop all references to other + objects, but keep the instance otherwise intact, so that client method + invocations still work. It may be run multiple times (due to reference + loops). Before returning, @dispose should chain up to the @dispose method + of the parent class. - + @@ -10301,8 +11716,13 @@ my_singleton_constructor (GType type, + instance finalization function, should finish the finalization of + the instance begun in @dispose and chain up to the @finalize method of the + parent class. - + @@ -10314,8 +11734,13 @@ my_singleton_constructor (GType type, + emits property change notification for a bunch + of properties. Overriding @dispatch_properties_changed should be rarely + needed. - + @@ -10333,16 +11758,19 @@ my_singleton_constructor (GType type, + the class closure for the notify signal - + a #GObject + filename="gobject/gobject.c" + line="1944">a #GObject @@ -10352,8 +11780,17 @@ my_singleton_constructor (GType type, + the @constructed function is called by g_object_new() as the + final step of the object creation process. At the point of the call, all + construction properties have been set on the object. The purpose of this + call is to allow for object initialisation steps that can only be performed + after construction properties have been set. @constructed implementors + should chain up to the @constructed call of their parent class to allow it + to complete its initialisation. - + @@ -10383,27 +11820,27 @@ my_singleton_constructor (GType type, Looks up the #GParamSpec for a property of a class. - + filename="gobject/gobject.c" + line="1436">Looks up the #GParamSpec for a property of a class. + the #GParamSpec for the property, or + filename="gobject/gobject.c" + line="1443">the #GParamSpec for the property, or %NULL if the class doesn't have a property of that name a #GObjectClass + filename="gobject/gobject.c" + line="1438">a #GObjectClass the name of the property to look up + filename="gobject/gobject.c" + line="1439">the name of the property to look up @@ -10412,8 +11849,8 @@ my_singleton_constructor (GType type, c:identifier="g_object_class_install_properties" version="2.26"> Installs new properties from an array of #GParamSpecs. + filename="gobject/gobject.c" + line="1249">Installs new properties from an array of #GParamSpecs. All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not @@ -10445,13 +11882,13 @@ my_object_class_init (MyObjectClass *klass) GObjectClass *gobject_class = G_OBJECT_CLASS (klass); obj_properties[PROP_FOO] = - g_param_spec_int ("foo", "Foo", "Foo", + g_param_spec_int ("foo", NULL, NULL, -1, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); obj_properties[PROP_BAR] = - g_param_spec_string ("bar", "Bar", "Bar", + g_param_spec_string ("bar", NULL, NULL, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -10476,27 +11913,27 @@ my_object_set_foo (MyObject *self, gint foo) } } ]| - + a #GObjectClass + filename="gobject/gobject.c" + line="1251">a #GObjectClass the length of the #GParamSpecs array + filename="gobject/gobject.c" + line="1252">the length of the #GParamSpecs array the #GParamSpecs array + filename="gobject/gobject.c" + line="1253">the #GParamSpecs array defining the new properties @@ -10507,8 +11944,8 @@ my_object_set_foo (MyObject *self, gint foo) Installs a new property. + filename="gobject/gobject.c" + line="1140">Installs a new property. All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not @@ -10518,27 +11955,27 @@ use of properties on the same type on other threads. Note that it is possible to redefine a property in a derived class, by installing a property with the same name. This can be useful at times, e.g. to change the range of allowed values or the default value. - + a #GObjectClass + filename="gobject/gobject.c" + line="1142">a #GObjectClass the id for the new property + filename="gobject/gobject.c" + line="1143">the id for the new property the #GParamSpec for the new property + filename="gobject/gobject.c" + line="1144">the #GParamSpec for the new property @@ -10546,13 +11983,13 @@ e.g. to change the range of allowed values or the default value. Get an array of #GParamSpec* for all properties of a class. - + filename="gobject/gobject.c" + line="1575">Get an array of #GParamSpec* for all properties of a class. + an array of + filename="gobject/gobject.c" + line="1582">an array of #GParamSpec* which should be freed after use @@ -10561,8 +11998,8 @@ e.g. to change the range of allowed values or the default value. a #GObjectClass + filename="gobject/gobject.c" + line="1577">a #GObjectClass caller-allocates="0" transfer-ownership="full"> return location for the length of the returned array + filename="gobject/gobject.c" + line="1578">return location for the length of the returned array @@ -10580,8 +12017,8 @@ e.g. to change the range of allowed values or the default value. c:identifier="g_object_class_override_property" version="2.4"> Registers @property_id as referring to a property with the name + filename="gobject/gobject.c" + line="1498">Registers @property_id as referring to a property with the name @name in a parent class or in an interface implemented by @oclass. This allows this class to "override" a property implementation in a parent class or to provide the implementation of a property from @@ -10597,27 +12034,27 @@ instead, so that the @param_id field of the #GParamSpec will be correct. For virtually all uses, this makes no difference. If you need to get the overridden property, you can call g_param_spec_get_redirect_target(). - + a #GObjectClass + filename="gobject/gobject.c" + line="1500">a #GObjectClass the new property ID + filename="gobject/gobject.c" + line="1501">the new property ID the name of a property registered in a parent class or + filename="gobject/gobject.c" + line="1502">the name of a property registered in a parent class or in an interface of this class. @@ -10626,35 +12063,35 @@ g_param_spec_get_redirect_target(). The GObjectConstructParam struct is an auxiliary structure used to hand + filename="gobject/gobject.h" + line="368">The GObjectConstructParam struct is an auxiliary structure used to hand #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass. - + the #GParamSpec of the construct parameter + filename="gobject/gobject.h" + line="370">the #GParamSpec of the construct parameter the value to set the parameter to + filename="gobject/gobject.h" + line="371">the value to set the parameter to The type of the @finalize function of #GObjectClass. - + the #GObject being finalized @@ -10662,35 +12099,35 @@ g_param_spec_get_redirect_target(). The type of the @get_property function of #GObjectClass. - + a #GObject the numeric id under which the property was registered with g_object_class_install_property(). a #GValue to return the property value in the #GParamSpec describing the property @@ -10698,59 +12135,64 @@ g_param_spec_get_redirect_target(). The type of the @set_property function of #GObjectClass. - + a #GObject the numeric id under which the property was registered with g_object_class_install_property(). the new value for the property the #GParamSpec describing the property + + Mask containing the bits of #GParamSpec.flags which are reserved for GLib. - + filename="gobject/gparam.h" + line="189">Mask containing the bits of #GParamSpec.flags which are reserved for GLib. + Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into a #GParamSpec object. - + a valid #GParamSpec @@ -10759,13 +12201,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_BOOLEAN" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecBoolean. - + a valid #GParamSpec instance @@ -10774,13 +12216,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_BOXED" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecBoxed. - + a valid #GParamSpec instance @@ -10789,13 +12231,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_CHAR" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecChar. - + a valid #GParamSpec instance @@ -10804,13 +12246,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_CLASS" introspectable="0"> Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. - + a valid #GParamSpecClass @@ -10819,13 +12261,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_DOUBLE" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecDouble. - + a valid #GParamSpec instance @@ -10834,13 +12276,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_ENUM" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecEnum. - + a valid #GParamSpec instance @@ -10849,13 +12291,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_FLAGS" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecFlags. - + a valid #GParamSpec instance @@ -10864,13 +12306,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_FLOAT" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecFloat. - + a valid #GParamSpec instance @@ -10879,13 +12321,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_GET_CLASS" introspectable="0"> Retrieves the #GParamSpecClass of a #GParamSpec. - + a valid #GParamSpec @@ -10895,13 +12337,13 @@ a #GParamSpec object. version="2.10" introspectable="0"> Casts a #GParamSpec into a #GParamSpecGType. - + a #GParamSpec @@ -10910,13 +12352,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_INT" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecInt. - + a valid #GParamSpec instance @@ -10925,13 +12367,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_INT64" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecInt64. - + a valid #GParamSpec instance @@ -10940,13 +12382,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_LONG" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecLong. - + a valid #GParamSpec instance @@ -10955,13 +12397,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_OBJECT" introspectable="0"> Casts a #GParamSpec instance into a #GParamSpecObject. - + a valid #GParamSpec instance @@ -10971,13 +12413,13 @@ a #GParamSpec object. version="2.4" introspectable="0"> Casts a #GParamSpec into a #GParamSpecOverride. - + a #GParamSpec @@ -10986,13 +12428,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_PARAM" introspectable="0"> Casts a #GParamSpec instance into a #GParamSpecParam. - + a valid #GParamSpec instance @@ -11001,13 +12443,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_POINTER" introspectable="0"> Casts a #GParamSpec instance into a #GParamSpecPointer. - + a valid #GParamSpec instance @@ -11016,13 +12458,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_STRING" introspectable="0"> Casts a #GParamSpec instance into a #GParamSpecString. - + a valid #GParamSpec instance @@ -11031,13 +12473,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_TYPE" introspectable="0"> Retrieves the #GType of this @pspec. - + a valid #GParamSpec @@ -11046,13 +12488,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_TYPE_NAME" introspectable="0"> Retrieves the #GType name of this @pspec. - + a valid #GParamSpec @@ -11061,13 +12503,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_UCHAR" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecUChar. - + a valid #GParamSpec instance @@ -11076,13 +12518,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_UINT" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecUInt. - + a valid #GParamSpec instance @@ -11091,13 +12533,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_UINT64" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecUInt64. - + a valid #GParamSpec instance @@ -11106,13 +12548,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_ULONG" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecULong. - + a valid #GParamSpec instance @@ -11121,13 +12563,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_UNICHAR" introspectable="0"> Cast a #GParamSpec instance into a #GParamSpecUnichar. - + a valid #GParamSpec instance @@ -11138,14 +12580,14 @@ a #GParamSpec object. deprecated="1" deprecated-version="2.32"> Cast a #GParamSpec instance into a #GParamSpecValueArray. Use #GArray instead of #GValueArray - + a valid #GParamSpec instance @@ -11154,13 +12596,13 @@ a #GParamSpec object. c:identifier="G_PARAM_SPEC_VALUE_TYPE" introspectable="0"> Retrieves the #GType to initialize a #GValue for this parameter. - + a valid #GParamSpec @@ -11170,13 +12612,13 @@ a #GParamSpec object. version="2.26" introspectable="0"> Casts a #GParamSpec into a #GParamSpecVariant. - + a #GParamSpec @@ -11185,8 +12627,8 @@ a #GParamSpec object. value="224" c:type="G_PARAM_STATIC_STRINGS"> #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + filename="gobject/gparam.h" + line="174">#GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. It is recommended to use this for all properties by default, as it allows for internal performance improvements in GObject. @@ -11195,15 +12637,15 @@ It is very rare that a property would have a dynamically constructed name, nickname or blurb. Since 2.13.0 - + Minimum shift count to be used for user defined flags, to be stored in + filename="gobject/gparam.h" + line="195">Minimum shift count to be used for user defined flags, to be stored in #GParamSpec.flags. The maximum allowed is 10. - + version="2.38" introspectable="0"> Evaluates to the @field_name inside the @inst private data + filename="gobject/gtype.h" + line="2234">Evaluates to the @field_name inside the @inst private data structure for @TypeName. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. - + the name of the type in CamelCase + filename="gobject/gtype.h" + line="2236">the name of the type in CamelCase the instance of @TypeName you wish to access + filename="gobject/gtype.h" + line="2237">the instance of @TypeName you wish to access the type of the field in the private data structure + filename="gobject/gtype.h" + line="2238">the type of the field in the private data structure the name of the field in the private data structure + filename="gobject/gtype.h" + line="2239">the name of the field in the private data structure @@ -11247,29 +12689,29 @@ those macros. version="2.38" introspectable="0"> Evaluates to a pointer to the @field_name inside the @inst private data + filename="gobject/gtype.h" + line="2216">Evaluates to a pointer to the @field_name inside the @inst private data structure for @TypeName. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. - + the name of the type in CamelCase + filename="gobject/gtype.h" + line="2218">the name of the type in CamelCase the instance of @TypeName you wish to access + filename="gobject/gtype.h" + line="2219">the instance of @TypeName you wish to access the name of the field in the private data structure + filename="gobject/gtype.h" + line="2220">the name of the field in the private data structure @@ -11278,85 +12720,89 @@ those macros. version="2.38" introspectable="0"> Evaluates to the offset of the @field inside the instance private data + filename="gobject/gtype.h" + line="2199">Evaluates to the offset of the @field inside the instance private data structure for @TypeName. Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. - + the name of the type in CamelCase + filename="gobject/gtype.h" + line="2201">the name of the type in CamelCase the name of the field in the private data structure + filename="gobject/gtype.h" + line="2202">the name of the field in the private data structure Through the #GParamFlags flag values, certain aspects of parameters can be configured. See also: %G_PARAM_STATIC_STRINGS - + the parameter is readable the parameter is writable alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE the parameter will be set upon object construction + filename="gobject/gparam.h" + line="123">the parameter will be set upon object construction. + See [vfunc@Object.constructed] for more details the parameter can only be set upon object construction + filename="gobject/gparam.h" + line="125">the parameter can only be set upon object construction. + See [vfunc@Object.constructed] for more details upon parameter conversion (see g_param_value_convert()) + filename="gobject/gparam.h" + line="127">upon parameter conversion (see g_param_value_convert()) strict validation is not required the string used as name when constructing the + filename="gobject/gparam.h" + line="129">the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - internal + internal the string used as nick when constructing the + filename="gobject/gparam.h" + line="133">the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 @@ -11365,8 +12811,8 @@ See also: %G_PARAM_STATIC_STRINGS value="128" c:identifier="G_PARAM_STATIC_BLURB"> the string used as blurb when constructing the + filename="gobject/gparam.h" + line="137">the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 @@ -11375,8 +12821,8 @@ See also: %G_PARAM_STATIC_STRINGS value="1073741824" c:identifier="G_PARAM_EXPLICIT_NOTIFY"> calls to g_object_set_property() for this + filename="gobject/gparam.h" + line="141">calls to g_object_set_property() for this property will not automatically result in a "notify" signal being emitted: the implementation must call g_object_notify() themselves in case the property actually changes. Since: 2.42. @@ -11385,8 +12831,8 @@ See also: %G_PARAM_STATIC_STRINGS value="2147483648" c:identifier="G_PARAM_DEPRECATED"> the parameter is deprecated and will be removed + filename="gobject/gparam.h" + line="146">the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26 @@ -11405,31 +12851,30 @@ See also: %G_PARAM_STATIC_STRINGS glib:set-value-func="g_value_set_param" glib:get-value-func="g_value_get_param"> #GParamSpec is an object structure that encapsulates the metadata -required to specify parameters, such as e.g. #GObject properties. + filename="gobject/gparam.c" + line="33">`GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties. -## Parameter names # {#canonical-parameter-names} +## Parameter names A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first character of a property name must be a letter. These are the same rules as -for signal naming (see g_signal_new()). +for signal naming (see [func@GObject.signal_new]). -When creating and looking up a #GParamSpec, either separator can be +When creating and looking up a `GParamSpec`, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient, and is the ‘canonical form’. Using `_` is discouraged. - + Creates a new #GParamSpec instance. + filename="gobject/gparam.c" + line="422">Creates a new #GParamSpec instance. -See [canonical parameter names][canonical-parameter-names] for details of -the rules for @name. Names which violate these rules lead to undefined -behaviour. +See [canonical parameter names][class@GObject.ParamSpec#parameter-names] +for details of the rules for @name. Names which violate these rules lead +to undefined behaviour. Beyond the name, #GParamSpecs have two more descriptive strings, the @nick and @blurb, which may be used as a localized label and description. @@ -11437,25 +12882,25 @@ For GTK and related libraries these are considered deprecated and may be omitted, while for other libraries such as GStreamer and its plugins they are essential. When in doubt, follow the conventions used in the surrounding code and supporting libraries. - + (transfer floating): a newly allocated + filename="gobject/gparam.c" + line="443">(transfer floating): a newly allocated #GParamSpec instance, which is initially floating the #GType for the property; must be derived from %G_TYPE_PARAM + filename="gobject/gparam.c" + line="424">the #GType for the property; must be derived from %G_TYPE_PARAM the canonical name of the property + filename="gobject/gparam.c" + line="425">the canonical name of the property nullable="1" allow-none="1"> the nickname of the property + filename="gobject/gparam.c" + line="426">the nickname of the property nullable="1" allow-none="1"> a short description of the property + filename="gobject/gparam.c" + line="427">a short description of the property a combination of #GParamFlags + filename="gobject/gparam.c" + line="428">a combination of #GParamFlags @@ -11488,31 +12933,35 @@ surrounding code and supporting libraries. c:identifier="g_param_spec_is_valid_name" version="2.66"> Validate a property name for a #GParamSpec. This can be useful for + filename="gobject/gparam.c" + line="384">Validate a property name for a #GParamSpec. This can be useful for dynamically-generated properties which need to be validated at run-time before actually trying to create them. -See [canonical parameter names][canonical-parameter-names] for details of -the rules for valid names. - +See [canonical parameter names][class@GObject.ParamSpec#parameter-names] +for details of the rules for valid names. + %TRUE if @name is a valid property name, %FALSE otherwise. + filename="gobject/gparam.c" + line="395">%TRUE if @name is a valid property name, %FALSE otherwise. the canonical name of the property + filename="gobject/gparam.c" + line="386">the canonical name of the property - + The instance finalization function (optional), should chain + up to the finalize method of the parent class. + @@ -11523,7 +12972,12 @@ the rules for valid names. - + Checks if contents of @value comply with the specifications + set out by this type, without modifying the value. This vfunc is optional. + If it isn't set, GObject will use @value_validate. Since 2.74 + @@ -11537,7 +12991,12 @@ the rules for valid names. - + Resets a @value to the default value for this type + (recommended, the default is g_value_reset()), see + g_param_value_set_default(). + @@ -11551,7 +13010,12 @@ the rules for valid names. - + Ensures that the contents of @value comply with the + specifications set out by this type (optional), see + g_param_value_validate(). + @@ -11565,7 +13029,11 @@ the rules for valid names. - + Compares @value1 with @value2 according to this type + (recommended, the default is memcmp()), see g_param_values_cmp(). + @@ -11583,20 +13051,20 @@ the rules for valid names. Get the short description of a #GParamSpec. - + filename="gobject/gparam.c" + line="334">Get the short description of a #GParamSpec. + the short description of @pspec. + filename="gobject/gparam.c" + line="340">the short description of @pspec. a valid #GParamSpec + filename="gobject/gparam.c" + line="336">a valid #GParamSpec @@ -11605,45 +13073,45 @@ the rules for valid names. c:identifier="g_param_spec_get_default_value" version="2.38"> Gets the default value of @pspec as a pointer to a #GValue. + filename="gobject/gparam.c" + line="1621">Gets the default value of @pspec as a pointer to a #GValue. The #GValue will remain valid for the life of @pspec. - + a pointer to a #GValue which must not be modified + filename="gobject/gparam.c" + line="1629">a pointer to a #GValue which must not be modified a #GParamSpec + filename="gobject/gparam.c" + line="1623">a #GParamSpec Get the name of a #GParamSpec. + filename="gobject/gparam.c" + line="288">Get the name of a #GParamSpec. The name is always an "interned" string (as per g_intern_string()). This allows for pointer-value comparisons. - + the name of @pspec. + filename="gobject/gparam.c" + line="297">the name of @pspec. a valid #GParamSpec + filename="gobject/gparam.c" + line="290">a valid #GParamSpec @@ -11652,66 +13120,66 @@ This allows for pointer-value comparisons. c:identifier="g_param_spec_get_name_quark" version="2.46"> Gets the GQuark for the name. - + filename="gobject/gparam.c" + line="1667">Gets the GQuark for the name. + the GQuark for @pspec->name. + filename="gobject/gparam.c" + line="1673">the GQuark for @pspec->name. a #GParamSpec + filename="gobject/gparam.c" + line="1669">a #GParamSpec Get the nickname of a #GParamSpec. - + filename="gobject/gparam.c" + line="307">Get the nickname of a #GParamSpec. + the nickname of @pspec. + filename="gobject/gparam.c" + line="313">the nickname of @pspec. a valid #GParamSpec + filename="gobject/gparam.c" + line="309">a valid #GParamSpec Gets back user data pointers stored via g_param_spec_set_qdata(). - + filename="gobject/gparam.c" + line="501">Gets back user data pointers stored via g_param_spec_set_qdata(). + the user data pointer set, or %NULL + filename="gobject/gparam.c" + line="508">the user data pointer set, or %NULL a valid #GParamSpec + filename="gobject/gparam.c" + line="503">a valid #GParamSpec a #GQuark, naming the user data pointer + filename="gobject/gparam.c" + line="504">a #GQuark, naming the user data pointer @@ -11720,47 +13188,47 @@ This allows for pointer-value comparisons. c:identifier="g_param_spec_get_redirect_target" version="2.4"> If the paramspec redirects operations to another paramspec, + filename="gobject/gparam.c" + line="591">If the paramspec redirects operations to another paramspec, returns that paramspec. Redirect is used typically for providing a new implementation of a property in a derived type while preserving all the properties from the parent type. Redirection is established by creating a property of type #GParamSpecOverride. See g_object_class_override_property() for an example of the use of this capability. - + paramspec to which requests on this + filename="gobject/gparam.c" + line="605">paramspec to which requests on this paramspec should be redirected, or %NULL if none. a #GParamSpec + filename="gobject/gparam.c" + line="593">a #GParamSpec Increments the reference count of @pspec. - + filename="gobject/gparam.c" + line="204">Increments the reference count of @pspec. + the #GParamSpec that was passed into this function + filename="gobject/gparam.c" + line="210">the #GParamSpec that was passed into this function a valid #GParamSpec + filename="gobject/gparam.c" + line="206">a valid #GParamSpec @@ -11770,48 +13238,48 @@ for an example of the use of this capability. version="2.10" introspectable="0"> Convenience function to ref and sink a #GParamSpec. - + filename="gobject/gparam.c" + line="266">Convenience function to ref and sink a #GParamSpec. + the #GParamSpec that was passed into this function + filename="gobject/gparam.c" + line="273">the #GParamSpec that was passed into this function a valid #GParamSpec + filename="gobject/gparam.c" + line="268">a valid #GParamSpec Sets an opaque, named pointer on a #GParamSpec. The name is + filename="gobject/gparam.c" + line="519">Sets an opaque, named pointer on a #GParamSpec. The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @pspec with g_param_spec_get_qdata(). Setting a previously set user data pointer, overrides (frees) the old pointer set, using %NULL as pointer essentially removes the data stored. - + the #GParamSpec to set store a user data pointer + filename="gobject/gparam.c" + line="521">the #GParamSpec to set store a user data pointer a #GQuark, naming the user data pointer + filename="gobject/gparam.c" + line="522">a #GQuark, naming the user data pointer nullable="1" allow-none="1"> an opaque user data pointer + filename="gobject/gparam.c" + line="523">an opaque user data pointer @@ -11829,27 +13297,27 @@ set, using %NULL as pointer essentially removes the data stored. c:identifier="g_param_spec_set_qdata_full" introspectable="0"> This function works like g_param_spec_set_qdata(), but in addition, + filename="gobject/gparam.c" + line="543">This function works like g_param_spec_set_qdata(), but in addition, a `void (*destroy) (gpointer)` function may be specified which is called with @data as argument when the @pspec is finalized, or the data is being overwritten by a call to g_param_spec_set_qdata() with the same @quark. - + the #GParamSpec to set store a user data pointer + filename="gobject/gparam.c" + line="545">the #GParamSpec to set store a user data pointer a #GQuark, naming the user data pointer + filename="gobject/gparam.c" + line="546">a #GQuark, naming the user data pointer nullable="1" allow-none="1"> an opaque user data pointer + filename="gobject/gparam.c" + line="547">an opaque user data pointer allow-none="1" scope="async"> function to invoke with @data as argument, when @data needs to + filename="gobject/gparam.c" + line="548">function to invoke with @data as argument, when @data needs to be freed @@ -11876,52 +13344,52 @@ g_param_spec_set_qdata() with the same @quark. The initial reference count of a newly created #GParamSpec is 1, + filename="gobject/gparam.c" + line="243">The initial reference count of a newly created #GParamSpec is 1, even though no one has explicitly called g_param_spec_ref() on it yet. So the initial reference count is flagged as "floating", until someone calls `g_param_spec_ref (pspec); g_param_spec_sink (pspec);` in sequence on it, taking over the initial reference count (thus ending up with a @pspec that has a reference count of 1 still, but is not flagged "floating" anymore). - + a valid #GParamSpec + filename="gobject/gparam.c" + line="245">a valid #GParamSpec Gets back user data pointers stored via g_param_spec_set_qdata() + filename="gobject/gparam.c" + line="569">Gets back user data pointers stored via g_param_spec_set_qdata() and removes the @data from @pspec without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier. - + the user data pointer set, or %NULL + filename="gobject/gparam.c" + line="579">the user data pointer set, or %NULL the #GParamSpec to get a stored user data pointer from + filename="gobject/gparam.c" + line="571">the #GParamSpec to get a stored user data pointer from a #GQuark, naming the user data pointer + filename="gobject/gparam.c" + line="572">a #GQuark, naming the user data pointer @@ -11930,49 +13398,49 @@ required to update user data pointers with a destroy notifier. c:identifier="g_param_spec_unref" introspectable="0"> Decrements the reference count of a @pspec. - + filename="gobject/gparam.c" + line="222">Decrements the reference count of a @pspec. + a valid #GParamSpec + filename="gobject/gparam.c" + line="224">a valid #GParamSpec private #GTypeInstance portion + filename="gobject/gparam.c" + line="35">private `GTypeInstance` portion name of this parameter: always an interned string + filename="gobject/gparam.c" + line="36">name of this parameter: always an interned string #GParamFlags flags for this parameter + filename="gobject/gparam.c" + line="37">`GParamFlags` flags for this parameter the #GValue type for this parameter + filename="gobject/gparam.c" + line="38">the `GValue` type for this parameter #GType type that uses (introduces) this parameter + filename="gobject/gparam.c" + line="39">`GType` type that uses (introduces) this parameter @@ -11999,17 +13467,17 @@ required to update user data pointers with a destroy notifier. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for boolean properties. private #GParamSpec portion default value for the property specified @@ -12022,11 +13490,11 @@ required to update user data pointers with a destroy notifier. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for boxed properties. private #GParamSpec portion @@ -12039,29 +13507,29 @@ required to update user data pointers with a destroy notifier. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for character properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -12070,26 +13538,30 @@ required to update user data pointers with a destroy notifier. c:type="GParamSpecClass" glib:is-gtype-struct-for="ParamSpec"> The class structure for the GParamSpec type. + filename="gobject/gparam.h" + line="225">The class structure for the GParamSpec type. Normally, GParamSpec classes are filled by g_param_type_register_static(). - + the parent class + filename="gobject/gparam.h" + line="227">the parent class the #GValue type for this parameter + filename="gobject/gparam.h" + line="228">the #GValue type for this parameter + The instance finalization function (optional), should chain + up to the finalize method of the parent class. - + @@ -12101,8 +13573,13 @@ g_param_type_register_static(). + Resets a @value to the default value for this type + (recommended, the default is g_value_reset()), see + g_param_value_set_default(). - + @@ -12117,8 +13594,13 @@ g_param_type_register_static(). + Ensures that the contents of @value comply with the + specifications set out by this type (optional), see + g_param_value_validate(). - + @@ -12133,8 +13615,12 @@ g_param_type_register_static(). + Compares @value1 with @value2 according to this type + (recommended, the default is memcmp()), see g_param_values_cmp(). - + @@ -12152,8 +13638,13 @@ g_param_type_register_static(). + Checks if contents of @value comply with the specifications + set out by this type, without modifying the value. This vfunc is optional. + If it isn't set, GObject will use @value_validate. Since 2.74 - + @@ -12181,35 +13672,35 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for double properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. @@ -12223,24 +13714,24 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for enum properties. private #GParamSpec portion the #GEnumClass for the enum default value for the property specified @@ -12253,24 +13744,24 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for flags properties. private #GParamSpec portion the #GFlagsClass for the flags default value for the property specified @@ -12283,35 +13774,35 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for float properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. @@ -12326,17 +13817,17 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for #GType properties. private #GParamSpec portion a #GType whose subtypes can occur as values @@ -12349,29 +13840,29 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -12384,29 +13875,29 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for 64bit integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -12419,29 +13910,29 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for long integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -12454,11 +13945,11 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for object properties. private #GParamSpec portion @@ -12472,7 +13963,7 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that redirects operations to other types of #GParamSpec. @@ -12499,12 +13990,12 @@ unless you are implementing a new base type similar to GObject. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM properties. private #GParamSpec portion @@ -12517,11 +14008,11 @@ properties. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for pointer properties. private #GParamSpec portion @@ -12531,52 +14022,69 @@ properties. disguised="1" opaque="1"> A #GParamSpecPool maintains a collection of #GParamSpecs which can be + filename="gobject/gparam.c" + line="935">A #GParamSpecPool maintains a collection of #GParamSpecs which can be quickly accessed by owner and name. The implementation of the #GObject property system uses such a pool to store the #GParamSpecs of the properties all object types. - + + + Frees the resources allocated by a #GParamSpecPool. + + + + + + + a #GParamSpecPool + + + + Inserts a #GParamSpec in the pool. - + filename="gobject/gparam.c" + line="1023">Inserts a #GParamSpec in the pool. + a #GParamSpecPool. + filename="gobject/gparam.c" + line="1025">a #GParamSpecPool. the #GParamSpec to insert + filename="gobject/gparam.c" + line="1026">the #GParamSpec to insert a #GType identifying the owner of @pspec + filename="gobject/gparam.c" + line="1027">a #GType identifying the owner of @pspec Gets an array of all #GParamSpecs owned by @owner_type in + filename="gobject/gparam.c" + line="1363">Gets an array of all #GParamSpecs owned by @owner_type in the pool. - + a newly + filename="gobject/gparam.c" + line="1372">a newly allocated array containing pointers to all #GParamSpecs owned by @owner_type in the pool @@ -12586,14 +14094,14 @@ the pool. a #GParamSpecPool + filename="gobject/gparam.c" + line="1365">a #GParamSpecPool the owner to look for + filename="gobject/gparam.c" + line="1366">the owner to look for caller-allocates="0" transfer-ownership="full"> return location for the length of the returned array + filename="gobject/gparam.c" + line="1367">return location for the length of the returned array Gets an #GList of all #GParamSpecs owned by @owner_type in + filename="gobject/gparam.c" + line="1233">Gets an #GList of all #GParamSpecs owned by @owner_type in the pool. - + a + filename="gobject/gparam.c" + line="1241">a #GList of all #GParamSpecs owned by @owner_type in the pool#GParamSpecs. @@ -12626,53 +14134,53 @@ the pool. a #GParamSpecPool + filename="gobject/gparam.c" + line="1235">a #GParamSpecPool the owner to look for + filename="gobject/gparam.c" + line="1236">the owner to look for Looks up a #GParamSpec in the pool. - + filename="gobject/gparam.c" + line="1142">Looks up a #GParamSpec in the pool. + The found #GParamSpec, or %NULL if no + filename="gobject/gparam.c" + line="1152">The found #GParamSpec, or %NULL if no matching #GParamSpec was found. a #GParamSpecPool + filename="gobject/gparam.c" + line="1144">a #GParamSpecPool the name to look for + filename="gobject/gparam.c" + line="1145">the name to look for the owner to look for + filename="gobject/gparam.c" + line="1146">the owner to look for If %TRUE, also try to find a #GParamSpec with @param_name + filename="gobject/gparam.c" + line="1147">If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. @@ -12680,23 +14188,23 @@ matching #GParamSpec was found. Removes a #GParamSpec from the pool. - + filename="gobject/gparam.c" + line="1063">Removes a #GParamSpec from the pool. + a #GParamSpecPool + filename="gobject/gparam.c" + line="1065">a #GParamSpecPool the #GParamSpec to remove + filename="gobject/gparam.c" + line="1066">the #GParamSpec to remove @@ -12705,25 +14213,25 @@ matching #GParamSpec was found. c:identifier="g_param_spec_pool_new" introspectable="0"> Creates a new #GParamSpecPool. + filename="gobject/gparam.c" + line="976">Creates a new #GParamSpecPool. If @type_prefixing is %TRUE, lookups in the newly created pool will allow to specify the owner as a colon-separated prefix of the property name, like "GtkContainer:border-width". This feature is deprecated, so you should always set @type_prefixing to %FALSE. - + a newly allocated #GParamSpecPool. + filename="gobject/gparam.c" + line="987">a newly allocated #GParamSpecPool. Whether the pool will support type-prefixed property names. + filename="gobject/gparam.c" + line="978">Whether the pool will support type-prefixed property names. @@ -12737,56 +14245,56 @@ deprecated, so you should always set @type_prefixing to %FALSE. glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for string properties. private #GParamSpec portion default value for the property specified a string containing the allowed values for the first byte a string containing the allowed values for the subsequent bytes the replacement byte for bytes which don't match @cset_first or @cset_nth. replace empty string by %NULL replace %NULL strings by an empty string This structure is used to provide the type system with the information + filename="gobject/gparam.h" + line="364">This structure is used to provide the type system with the information required to initialize and destruct (finalize) a parameter's class and instances thereof. @@ -12794,22 +14302,25 @@ The initialized structure is passed to the g_param_type_register_static() The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of g_param_type_register_static(). - + Size of the instance (object) structure. + filename="gobject/gparam.h" + line="366">Size of the instance (object) structure. Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. + filename="gobject/gparam.h" + line="367">Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. + Location of the instance initialization function (optional). - + @@ -12822,13 +14333,16 @@ g_param_type_register_static(). The #GType of values conforming to this #GParamSpec + filename="gobject/gparam.h" + line="369">The #GType of values conforming to this #GParamSpec + The instance finalization function (optional). - + @@ -12840,8 +14354,13 @@ g_param_type_register_static(). + Resets a @value to the default value for @pspec + (recommended, the default is g_value_reset()), see + g_param_value_set_default(). - + @@ -12856,8 +14375,13 @@ g_param_type_register_static(). + Ensures that the contents of @value comply with the + specifications set out by @pspec (optional), see + g_param_value_validate(). - + @@ -12872,8 +14396,12 @@ g_param_type_register_static(). + Compares @value1 with @value2 according to @pspec + (recommended, the default is memcmp()), see g_param_values_cmp(). - + @@ -12899,29 +14427,29 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for unsigned character properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -12934,29 +14462,29 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for unsigned integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -12969,29 +14497,29 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -13004,29 +14532,29 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified @@ -13039,17 +14567,17 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. private #GParamSpec portion default value for the property specified @@ -13062,23 +14590,23 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for #GValueArray properties. private #GParamSpec portion a #GParamSpec describing the elements contained in arrays of this property, may be %NULL if greater than 0, arrays of this property will always have this many elements @@ -13092,7 +14620,7 @@ g_param_type_register_static(). glib:get-type="intern" glib:fundamental="1"> A #GParamSpec derived structure that contains the meta data for #GVariant properties. When comparing values with g_param_values_cmp(), scalar values with the same @@ -13102,19 +14630,19 @@ otherwise undefined. %NULL is ordered before non-%NULL variants. Two %NULL values compare equal. private #GParamSpec portion a #GVariantType, or %NULL a #GVariant, or %NULL @@ -13129,37 +14657,62 @@ values compare equal. deprecated="1" deprecated-version="2.54"> The GParameter struct is an auxiliary structure used + filename="gobject/gparam.h" + line="270">The GParameter struct is an auxiliary structure used to hand parameter name/value pairs to g_object_newv(). This type is not introspectable. - + the parameter name + filename="gobject/gparam.h" + line="272">the parameter name the parameter value + filename="gobject/gparam.h" + line="273">the parameter value + + + + + + + + + + A mask for all #GSignalFlags bits. - + - + @@ -13167,14 +14720,14 @@ to hand parameter name/value pairs to g_object_newv(). A mask for all #GSignalMatchType bits. - + The signal accumulator is a special callback function that can be used to collect return values of the various callbacks that are called during a signal emission. @@ -13183,10 +14736,10 @@ The signal accumulator is specified at signal creation time, if it is left %NULL, no accumulation of callback return values is performed. The return value of signal emissions is then the value returned by the last callback. - + The accumulator function returns whether the signal emission should be aborted. Returning %TRUE will continue with the signal emission. Returning %FALSE will abort the current emission. @@ -13198,20 +14751,20 @@ last callback. Signal invocation hint, see #GSignalInvocationHint. Accumulator to collect callback return values in, this is the return value of the current signal emission. A #GValue holding the return value of the signal handler. @@ -13220,7 +14773,7 @@ last callback. nullable="1" allow-none="1"> Callback data that was specified when creating the signal. @@ -13228,17 +14781,17 @@ last callback. A simple function pointer to get invoked when the signal is emitted. Emission hooks allow you to tie a hook to the signal type, so that it will trap all emissions of that signal, from any object. You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. - + whether it wants to stay connected. If it returns %FALSE, the signal hook is disconnected (and destroyed). @@ -13246,20 +14799,20 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. Signal invocation hint, see #GSignalInvocationHint. the number of parameters to the function, including the instance on which the signal was emitted. the instance on which the signal was emitted, followed by the parameters of the emission. @@ -13271,7 +14824,7 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. user data associated with the hook. @@ -13279,40 +14832,40 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. The signal flags are used to specify a signal's behaviour. - + Invoke the object method handler in the first emission stage. Invoke the object method handler in the third emission stage. Invoke the object method handler in the last emission stage. Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. This signal supports "::detail" appendices to the signal name upon handler connections and emissions. Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or @@ -13322,20 +14875,20 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. No emissions hooks are supported for this signal. Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30. The signal is deprecated and will be removed in a future version. A warning will be generated if it is connected while running with G_ENABLE_DIAGNOSTIC=1. Since 2.32. @@ -13344,7 +14897,7 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. Only used in #GSignalAccumulator accumulator functions for the #GSignalInvocationHint::run_type field to mark the first call to the accumulator function for a signal emission. Since 2.68. @@ -13358,10 +14911,11 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. #GSignalGroup manages to simplify the process of connecting -many signals to a #GObject as a group. As such there is no API -to disconnect a signal from the group. + filename="gobject/gsignalgroup.c" + line="30">`GSignalGroup` manages a collection of signals on a `GObject`. + +`GSignalGroup` simplifies the process of connecting many signals to a `GObject` +as a group. As such there is no API to disconnect a signal from the group. In particular, this allows you to: @@ -13370,50 +14924,50 @@ In particular, this allows you to: - Block and unblock signals as a group - Ensuring that blocked state transfers across target instances. -One place you might want to use such a structure is with #GtkTextView and -#GtkTextBuffer. Often times, you'll need to connect to many signals on -#GtkTextBuffer from a #GtkTextView subclass. This allows you to create a +One place you might want to use such a structure is with `GtkTextView` and +`GtkTextBuffer`. Often times, you'll need to connect to many signals on +`GtkTextBuffer` from a `GtkTextView` subclass. This allows you to create a signal group during instance construction, simply bind the -#GtkTextView:buffer property to #GSignalGroup:target and connect -all the signals you need. When the #GtkTextView:buffer property changes +`GtkTextView:buffer` property to `GSignalGroup:target` and connect +all the signals you need. When the `GtkTextView:buffer` property changes all of the signals will be transitioned correctly. Creates a new #GSignalGroup for target instances of @target_type. - + filename="gobject/gsignalgroup.c" + line="683">Creates a new #GSignalGroup for target instances of @target_type. + a new #GSignalGroup + filename="gobject/gsignalgroup.c" + line="689">a new #GSignalGroup the #GType of the target instance. + filename="gobject/gsignalgroup.c" + line="685">the #GType of the target instance. Blocks all signal handlers managed by @self so they will not + filename="gobject/gsignalgroup.c" + line="320">Blocks all signal handlers managed by @self so they will not be called during any signal emissions. Must be unblocked exactly the same number of times it has been blocked to become active again. This blocked state will be kept across changes of the target instance. - + the #GSignalGroup + filename="gobject/gsignalgroup.c" + line="322">the #GSignalGroup @@ -13423,26 +14977,26 @@ This blocked state will be kept across changes of the target instance. version="2.72" introspectable="0"> Connects @c_handler to the signal @detailed_signal + filename="gobject/gsignalgroup.c" + line="877">Connects @c_handler to the signal @detailed_signal on the target instance of @self. You cannot connect a signal handler after #GSignalGroup:target has been set. - + a #GSignalGroup + filename="gobject/gsignalgroup.c" + line="879">a #GSignalGroup a string of the form "signal-name::detail" + filename="gobject/gsignalgroup.c" + line="880">a string of the form "signal-name::detail" the #GCallback to connect + filename="gobject/gsignalgroup.c" + line="881">the #GCallback to connect the data to pass to @c_handler calls + filename="gobject/gsignalgroup.c" + line="882">the data to pass to @c_handler calls @@ -13470,28 +15024,28 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Connects @c_handler to the signal @detailed_signal + filename="gobject/gsignalgroup.c" + line="901">Connects @c_handler to the signal @detailed_signal on the target instance of @self. The @c_handler will be called after the default handler of the signal. You cannot connect a signal handler after #GSignalGroup:target has been set. - + a #GSignalGroup + filename="gobject/gsignalgroup.c" + line="903">a #GSignalGroup a string of the form "signal-name::detail" + filename="gobject/gsignalgroup.c" + line="904">a string of the form "signal-name::detail" the #GCallback to connect + filename="gobject/gsignalgroup.c" + line="905">the #GCallback to connect the data to pass to @c_handler calls + filename="gobject/gsignalgroup.c" + line="906">the data to pass to @c_handler calls @@ -13518,37 +15072,37 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Connects @closure to the signal @detailed_signal on #GSignalGroup:target. + filename="gobject/gsignalgroup.c" + line="760">Connects @closure to the signal @detailed_signal on #GSignalGroup:target. You cannot connect a signal handler after #GSignalGroup:target has been set. - + a #GSignalGroup + filename="gobject/gsignalgroup.c" + line="762">a #GSignalGroup a string of the form `signal-name` with optional `::signal-detail` + filename="gobject/gsignalgroup.c" + line="763">a string of the form `signal-name` with optional `::signal-detail` the closure to connect. + filename="gobject/gsignalgroup.c" + line="764">the closure to connect. whether the handler should be called before or after the + filename="gobject/gsignalgroup.c" + line="765">whether the handler should be called before or after the default handler of the signal. @@ -13558,26 +15112,26 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Connects @c_handler to the signal @detailed_signal + filename="gobject/gsignalgroup.c" + line="849">Connects @c_handler to the signal @detailed_signal on the target instance of @self. You cannot connect a signal handler after #GSignalGroup:target has been set. - + a #GSignalGroup + filename="gobject/gsignalgroup.c" + line="851">a #GSignalGroup a string of the form "signal-name::detail" + filename="gobject/gsignalgroup.c" + line="852">a string of the form "signal-name::detail" the #GCallback to connect + filename="gobject/gsignalgroup.c" + line="853">the #GCallback to connect the data to pass to @c_handler calls + filename="gobject/gsignalgroup.c" + line="854">the data to pass to @c_handler calls function to be called when disposing of @self + filename="gobject/gsignalgroup.c" + line="855">function to be called when disposing of @self the flags used to create the signal connection + filename="gobject/gsignalgroup.c" + line="856">the flags used to create the signal connection @@ -13618,49 +15172,49 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Connects @c_handler to the signal @detailed_signal on #GSignalGroup:target. + filename="gobject/gsignalgroup.c" + line="818">Connects @c_handler to the signal @detailed_signal on #GSignalGroup:target. Ensures that the @object stays alive during the call to @c_handler by temporarily adding a reference count. When the @object is destroyed the signal handler will automatically be removed. You cannot connect a signal handler after #GSignalGroup:target has been set. - + a #GSignalGroup + filename="gobject/gsignalgroup.c" + line="820">a #GSignalGroup a string of the form `signal-name` with optional `::signal-detail` + filename="gobject/gsignalgroup.c" + line="821">a string of the form `signal-name` with optional `::signal-detail` the #GCallback to connect + filename="gobject/gsignalgroup.c" + line="822">the #GCallback to connect the #GObject to pass as data to @c_handler calls + filename="gobject/gsignalgroup.c" + line="823">the #GObject to pass as data to @c_handler calls #GConnectFlags for the signal connection + filename="gobject/gsignalgroup.c" + line="824">#GConnectFlags for the signal connection @@ -13669,29 +15223,29 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Connects @c_handler to the signal @detailed_signal + filename="gobject/gsignalgroup.c" + line="927">Connects @c_handler to the signal @detailed_signal on the target instance of @self. The instance on which the signal is emitted and @data will be swapped when calling @c_handler. You cannot connect a signal handler after #GSignalGroup:target has been set. - + a #GSignalGroup + filename="gobject/gsignalgroup.c" + line="929">a #GSignalGroup a string of the form "signal-name::detail" + filename="gobject/gsignalgroup.c" + line="930">a string of the form "signal-name::detail" the #GCallback to connect + filename="gobject/gsignalgroup.c" + line="931">the #GCallback to connect the data to pass to @c_handler calls + filename="gobject/gsignalgroup.c" + line="932">the data to pass to @c_handler calls @@ -13718,20 +15272,20 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Gets the target instance used when connecting signals. - + filename="gobject/gsignalgroup.c" + line="414">Gets the target instance used when connecting signals. + The target instance + filename="gobject/gsignalgroup.c" + line="420">The target instance the #GSignalGroup + filename="gobject/gsignalgroup.c" + line="416">the #GSignalGroup @@ -13741,22 +15295,22 @@ You cannot connect a signal handler after #GSignalGroup:target has been set. Sets the target instance used when connecting signals. Any signal + filename="gobject/gsignalgroup.c" + line="438">Sets the target instance used when connecting signals. Any signal that has been registered with g_signal_group_connect_object() or similar functions will be connected to this object. If the target instance was previously set, signals will be disconnected from that object prior to connecting to @target. - + the #GSignalGroup. + filename="gobject/gsignalgroup.c" + line="440">the #GSignalGroup. nullable="1" allow-none="1"> The target instance used + filename="gobject/gsignalgroup.c" + line="441">The target instance used when connecting signals. @@ -13775,20 +15329,20 @@ disconnected from that object prior to connecting to @target. c:identifier="g_signal_group_unblock" version="2.72"> Unblocks all signal handlers managed by @self so they will be + filename="gobject/gsignalgroup.c" + line="368">Unblocks all signal handlers managed by @self so they will be called again during any signal emissions unless it is blocked again. Must be unblocked exactly the same number of times it has been blocked to become active again. - + the #GSignalGroup + filename="gobject/gsignalgroup.c" + line="370">the #GSignalGroup @@ -13799,8 +15353,8 @@ has been blocked to become active again. transfer-ownership="none" setter="set_target"> The target instance used when connecting signals. + filename="gobject/gsignalgroup.c" + line="605">The target instance used when connecting signals. construct-only="1" transfer-ownership="none"> The #GType of the target property. + filename="gobject/gsignalgroup.c" + line="617">The #GType of the target property. This signal is emitted when #GSignalGroup:target is set to a new value + filename="gobject/gsignalgroup.c" + line="631">This signal is emitted when #GSignalGroup:target is set to a new value other than %NULL. It is similar to #GObject::notify on `target` except it will not emit when #GSignalGroup:target is %NULL and also allows for receiving the #GObject without a data-race. @@ -13826,16 +15380,16 @@ receiving the #GObject without a data-race. a #GObject containing the new value for #GSignalGroup:target + filename="gobject/gsignalgroup.c" + line="634">a #GObject containing the new value for #GSignalGroup:target This signal is emitted when the target instance of @self is set to a + filename="gobject/gsignalgroup.c" + line="653">This signal is emitted when the target instance of @self is set to a new #GObject. This signal will only be emitted if the previous target of @self is @@ -13847,25 +15401,25 @@ non-%NULL. The #GSignalInvocationHint structure is used to pass on additional information to callbacks during a signal emission. - + The signal id of the signal invoking the callback The detail passed on for this emission The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP and %G_SIGNAL_ACCUMULATOR_FIRST_RUN. @@ -13876,91 +15430,91 @@ to callbacks during a signal emission. The match types specify what g_signal_handlers_block_matched(), g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() match signals by. - + The signal id must be equal. The signal detail must be equal. The closure must be the same. The C closure callback must be the same. The closure data must be the same. Only unblocked signals may be matched. A structure holding in-depth information for a specific signal. See also: g_signal_query() - + The signal id of the signal being queried, or 0 if the signal to be queried was unknown. The signal name. The interface/instance type that this signal can be emitted for. The signal flags as passed in to g_signal_new(). The return type for user callbacks. The number of parameters that user callbacks take. The individual parameter types for user callbacks, note that the effective callback signature is: |[<!-- language="C" --> @@ -13973,32 +15527,106 @@ See also: g_signal_query() + + + Set the callback for a source as a #GClosure. + +If the source is not one of the standard GLib types, the @closure_callback +and @closure_marshal fields of the #GSourceFuncs structure must have been +filled in with pointers to appropriate functions. + + + + + + + the source + + + + a #GClosure + + + + + + Sets a dummy callback for @source. The callback will do nothing, and +if the source expects a #gboolean return value, it will return %TRUE. +(If the source expects any other type of return value, it will return +a 0/%NULL value; whatever g_value_init() initializes a #GValue to for +that type.) + +If the source is not one of the standard GLib types, the +@closure_callback and @closure_marshal fields of the #GSourceFuncs +structure must have been filled in with pointers to appropriate +functions. + + + + + + + the source + + + + + + + + + + + Checks that @g_class is a class structure of the type identified by @g_type + filename="gobject/gtype.h" + line="585">Checks that @g_class is a class structure of the type identified by @g_type and issues a warning if this is not the case. Returns @g_class casted to a pointer to @c_type. %NULL is not a valid class structure. This macro should only be used in type implementations. - + Location of a #GTypeClass structure + filename="gobject/gtype.h" + line="587">Location of a #GTypeClass structure The type to be returned + filename="gobject/gtype.h" + line="588">The type to be returned The corresponding C type of class structure of @g_type + filename="gobject/gtype.h" + line="589">The corresponding C type of class structure of @g_type @@ -14006,22 +15634,22 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_CLASS_TYPE" introspectable="0"> Checks if @g_class is a class structure of the type identified by + filename="gobject/gtype.h" + line="598">Checks if @g_class is a class structure of the type identified by @g_type. If @g_class is %NULL, %FALSE will be returned. This macro should only be used in type implementations. - + Location of a #GTypeClass structure + filename="gobject/gtype.h" + line="600">Location of a #GTypeClass structure The type to be checked + filename="gobject/gtype.h" + line="601">The type to be checked @@ -14029,18 +15657,18 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_INSTANCE" introspectable="0"> Checks if @instance is a valid #GTypeInstance structure, + filename="gobject/gtype.h" + line="501">Checks if @instance is a valid #GTypeInstance structure, otherwise issues a warning and returns %FALSE. %NULL is not a valid #GTypeInstance. This macro should only be used in type implementations. - + Location of a #GTypeInstance structure + filename="gobject/gtype.h" + line="503">Location of a #GTypeInstance structure @@ -14048,30 +15676,30 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_INSTANCE_CAST" introspectable="0"> Checks that @instance is an instance of the type identified by @g_type + filename="gobject/gtype.h" + line="514">Checks that @instance is an instance of the type identified by @g_type and issues a warning if this is not the case. Returns @instance casted to a pointer to @c_type. No warning will be issued if @instance is %NULL, and %NULL will be returned. This macro should only be used in type implementations. - + Location of a #GTypeInstance structure + filename="gobject/gtype.h" + line="516">Location of a #GTypeInstance structure The type to be returned + filename="gobject/gtype.h" + line="517">The type to be returned The corresponding C type of @g_type + filename="gobject/gtype.h" + line="518">The corresponding C type of @g_type @@ -14079,22 +15707,22 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE" introspectable="0"> Checks if @instance is an instance of the fundamental type identified by @g_type. + filename="gobject/gtype.h" + line="542">Checks if @instance is an instance of the fundamental type identified by @g_type. If @instance is %NULL, %FALSE will be returned. This macro should only be used in type implementations. - + Location of a #GTypeInstance structure. + filename="gobject/gtype.h" + line="544">Location of a #GTypeInstance structure. The fundamental type to be checked + filename="gobject/gtype.h" + line="545">The fundamental type to be checked @@ -14102,22 +15730,22 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_INSTANCE_TYPE" introspectable="0"> Checks if @instance is an instance of the type identified by @g_type. If + filename="gobject/gtype.h" + line="529">Checks if @instance is an instance of the type identified by @g_type. If @instance is %NULL, %FALSE will be returned. This macro should only be used in type implementations. - + Location of a #GTypeInstance structure. + filename="gobject/gtype.h" + line="531">Location of a #GTypeInstance structure. The type to be checked + filename="gobject/gtype.h" + line="532">The type to be checked @@ -14125,17 +15753,17 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_VALUE" introspectable="0"> Checks if @value has been initialized to hold values + filename="gobject/gtype.h" + line="611">Checks if @value has been initialized to hold values of a value type. This macro should only be used in type implementations. - + a #GValue + filename="gobject/gtype.h" + line="613">a #GValue @@ -14143,22 +15771,22 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_CHECK_VALUE_TYPE" introspectable="0"> Checks if @value has been initialized to hold values + filename="gobject/gtype.h" + line="623">Checks if @value has been initialized to hold values of type @g_type. This macro should only be used in type implementations. - + a #GValue + filename="gobject/gtype.h" + line="625">a #GValue The type to be checked + filename="gobject/gtype.h" + line="626">The type to be checked @@ -14167,29 +15795,29 @@ This macro should only be used in type implementations. version="2.24" introspectable="0"> Gets the private class structure for a particular type. + filename="gobject/gtype.h" + line="690">Gets the private class structure for a particular type. The private structure must have been registered in the get_type() function with g_type_add_class_private(). This macro should only be used in type implementations. - + the class of a type deriving from @private_type + filename="gobject/gtype.h" + line="692">the class of a type deriving from @private_type the type identifying which private data to retrieve + filename="gobject/gtype.h" + line="693">the type identifying which private data to retrieve The C type for the private structure + filename="gobject/gtype.h" + line="694">The C type for the private structure @@ -14197,25 +15825,25 @@ This macro should only be used in type implementations. value="1" c:type="G_TYPE_FLAG_RESERVED_ID_BIT"> A bit in the type number that's supposed to be left untouched. - - + filename="gobject/gtype.h" + line="2712">A bit in the type number that's supposed to be left untouched. + + Get the type identifier from a given @class structure. + filename="gobject/gtype.h" + line="647">Get the type identifier from a given @class structure. This macro should only be used in type implementations. - + Location of a valid #GTypeClass structure + filename="gobject/gtype.h" + line="649">Location of a valid #GTypeClass structure @@ -14223,16 +15851,16 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_FROM_INSTANCE" introspectable="0"> Get the type identifier from a given @instance structure. + filename="gobject/gtype.h" + line="636">Get the type identifier from a given @instance structure. This macro should only be used in type implementations. - + Location of a valid #GTypeInstance structure + filename="gobject/gtype.h" + line="638">Location of a valid #GTypeInstance structure @@ -14240,16 +15868,16 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_FROM_INTERFACE" introspectable="0"> Get the type identifier from a given @interface structure. + filename="gobject/gtype.h" + line="658">Get the type identifier from a given @interface structure. This macro should only be used in type implementations. - + Location of a valid #GTypeInterface structure + filename="gobject/gtype.h" + line="660">Location of a valid #GTypeInterface structure @@ -14257,16 +15885,16 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_FUNDAMENTAL" introspectable="0"> The fundamental type which is the ancestor of @type. Fundamental types are types that serve as ultimate bases for the derived types, thus they are the roots of distinct inheritance hierarchies. - + A #GType value. @@ -14275,32 +15903,32 @@ thus they are the roots of distinct inheritance hierarchies. value="1020" c:type="G_TYPE_FUNDAMENTAL_MAX"> An integer constant that represents the number of identifiers reserved for types that are assigned at compile-time. - + Shift value used in converting numbers to type IDs. - + Checks if @type has a #GTypeValueTable. - + A #GType value @@ -14309,30 +15937,30 @@ for types that are assigned at compile-time. c:identifier="G_TYPE_INSTANCE_GET_CLASS" introspectable="0"> Get the class structure of a given @instance, casted + filename="gobject/gtype.h" + line="555">Get the class structure of a given @instance, casted to a specified ancestor type @g_type of the instance. Note that while calling a GInstanceInitFunc(), the class pointer gets modified, so it might not always return the expected pointer. This macro should only be used in type implementations. - + Location of the #GTypeInstance structure + filename="gobject/gtype.h" + line="557">Location of the #GTypeInstance structure The #GType of the class to be returned + filename="gobject/gtype.h" + line="558">The #GType of the class to be returned The C type of the class structure + filename="gobject/gtype.h" + line="559">The C type of the class structure @@ -14340,26 +15968,26 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_INSTANCE_GET_INTERFACE" introspectable="0"> Get the interface structure for interface @g_type of a given @instance. + filename="gobject/gtype.h" + line="572">Get the interface structure for interface @g_type of a given @instance. This macro should only be used in type implementations. - + Location of the #GTypeInstance structure + filename="gobject/gtype.h" + line="574">Location of the #GTypeInstance structure The #GType of the interface to be returned + filename="gobject/gtype.h" + line="575">The #GType of the interface to be returned The C type of the interface structure + filename="gobject/gtype.h" + line="576">The C type of the interface structure @@ -14370,8 +15998,8 @@ This macro should only be used in type implementations. deprecated="1" deprecated-version="2.58"> Gets the private structure for a particular type. + filename="gobject/gtype.h" + line="670">Gets the private structure for a particular type. The private structure must have been registered in the class_init function with g_type_class_add_private(). @@ -14379,22 +16007,22 @@ class_init function with g_type_class_add_private(). This macro should only be used in type implementations. Use G_ADD_PRIVATE() and the generated `your_type_get_instance_private()` function instead - + the instance of a type deriving from @private_type + filename="gobject/gtype.h" + line="672">the instance of a type deriving from @private_type the type identifying which private data to retrieve + filename="gobject/gtype.h" + line="673">the type identifying which private data to retrieve The C type for the private structure + filename="gobject/gtype.h" + line="674">The C type for the private structure @@ -14402,15 +16030,15 @@ This macro should only be used in type implementations. c:identifier="G_TYPE_IS_ABSTRACT" introspectable="0"> Checks if @type is an abstract type. An abstract type cannot be instantiated and is normally used as an abstract base class for derived classes. - + A #GType value @@ -14418,7 +16046,7 @@ derived classes. - + @@ -14428,7 +16056,7 @@ derived classes. c:identifier="G_TYPE_IS_CLASSED" introspectable="0"> Checks if @type is a classed type. A classed type has an associated #GTypeClass which can be derived to store @@ -14439,11 +16067,11 @@ fundamental types built into GLib are classed. Interfaces are not classed: while their #GTypeInterface struct could be considered similar to #GTypeClass, and classes can derive interfaces, #GTypeInterface doesn’t allow for subclassing. - + A #GType value @@ -14452,14 +16080,14 @@ considered similar to #GTypeClass, and classes can derive interfaces, c:identifier="G_TYPE_IS_DEEP_DERIVABLE" introspectable="0"> Checks if @type is a deep derivable type. A deep derivable type can be used as the base class of a deep (multi-level) class hierarchy. - + A #GType value @@ -14469,14 +16097,14 @@ can be used as the base class of a deep (multi-level) class hierarchy. version="2.76" introspectable="0"> Checks if @type is deprecated. Instantiating a deprecated type will trigger a warning if running with `G_ENABLE_DIAGNOSTIC=1`. - + a #GType value @@ -14485,14 +16113,14 @@ trigger a warning if running with `G_ENABLE_DIAGNOSTIC=1`. c:identifier="G_TYPE_IS_DERIVABLE" introspectable="0"> Checks if @type is a derivable type. A derivable type can be used as the base class of a flat (single-level) class hierarchy. - + A #GType value @@ -14501,15 +16129,15 @@ be used as the base class of a flat (single-level) class hierarchy. c:identifier="G_TYPE_IS_DERIVED" introspectable="0"> Checks if @type is derived (or in object-oriented terminology: inherited) from another type (this holds true for all non-fundamental types). - + A #GType value @@ -14518,13 +16146,13 @@ types). c:identifier="G_TYPE_IS_ENUM" introspectable="0"> Checks whether @type "is a" %G_TYPE_ENUM. - + a #GType ID. @@ -14534,14 +16162,14 @@ types). version="2.70" introspectable="0"> Checks if @type is a final type. A final type cannot be derived any further. - + a #GType value @@ -14550,13 +16178,13 @@ further. c:identifier="G_TYPE_IS_FLAGS" introspectable="0"> Checks whether @type "is a" %G_TYPE_FLAGS. - + a #GType ID. @@ -14565,13 +16193,13 @@ further. c:identifier="G_TYPE_IS_FUNDAMENTAL" introspectable="0"> Checks if @type is a fundamental type. - + A #GType value @@ -14580,14 +16208,14 @@ further. c:identifier="G_TYPE_IS_INSTANTIATABLE" introspectable="0"> Checks if @type can be instantiated. Instantiation is the process of creating an instance (object) of this type. - + A #GType value @@ -14596,7 +16224,7 @@ process of creating an instance (object) of this type. c:identifier="G_TYPE_IS_INTERFACE" introspectable="0"> Checks if @type is an interface type. An interface type provides a pure API, the implementation @@ -14605,11 +16233,11 @@ to the interface). GLib interfaces are somewhat analogous to Java interfaces and C++ classes containing only pure virtual functions, with the difference that GType interfaces are not derivable (but see g_type_interface_add_prerequisite() for an alternative). - + A #GType value @@ -14618,13 +16246,13 @@ g_type_interface_add_prerequisite() for an alternative). c:identifier="G_TYPE_IS_OBJECT" introspectable="0"> Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. - + Type id to check @@ -14633,13 +16261,13 @@ g_type_interface_add_prerequisite() for an alternative). c:identifier="G_TYPE_IS_PARAM" introspectable="0"> Checks whether @type "is a" %G_TYPE_PARAM. - + a #GType ID @@ -14648,16 +16276,16 @@ g_type_interface_add_prerequisite() for an alternative). c:identifier="G_TYPE_IS_VALUE" introspectable="0"> Checks whether the passed in type ID can be used for g_value_init(). That is, this macro checks whether this type provides an implementation of the #GTypeValueTable functions required for a type to create a #GValue of. - + A #GType value. @@ -14666,15 +16294,15 @@ of the #GTypeValueTable functions required for a type to create a #GValue of. Checks if @type is an abstract value type. An abstract value type introduces a value table, but can't be used for g_value_init() and is normally used as an abstract base type for derived value types. - + A #GType value @@ -14683,13 +16311,13 @@ an abstract base type for derived value types. c:identifier="G_TYPE_IS_VALUE_TYPE" introspectable="0"> Checks if @type is a value type and can be used with g_value_init(). - + A #GType value @@ -14698,16 +16326,16 @@ an abstract base type for derived value types. c:identifier="G_TYPE_MAKE_FUNDAMENTAL" introspectable="0"> Get the type ID for the fundamental type number @x. Use g_type_fundamental_next() instead of this macro to create new fundamental types. - + the fundamental type number. @@ -14715,7 +16343,7 @@ types. - + @@ -14724,7 +16352,7 @@ types. - + @@ -14733,7 +16361,7 @@ types. - + @@ -14742,7 +16370,7 @@ types. - + @@ -14751,7 +16379,7 @@ types. - + @@ -14760,7 +16388,7 @@ types. - + @@ -14770,58 +16398,68 @@ types. value="32" c:type="G_TYPE_RESERVED_BSE_FIRST"> First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. - + Last fundamental type number reserved for BSE. - + First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. - + Last fundamental type number reserved for GLib. - + First available fundamental type number to create new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL(). - + + + + + A callback function used for notification when the state + filename="gobject/gobject.h" + line="537">A callback function used for notification when the state of a toggle reference changes. See also: g_object_add_toggle_ref() - + @@ -14831,20 +16469,20 @@ See also: g_object_add_toggle_ref() nullable="1" allow-none="1"> Callback data passed to g_object_add_toggle_ref() + filename="gobject/gobject.h" + line="539">Callback data passed to g_object_add_toggle_ref() The object on which g_object_add_toggle_ref() was called. + filename="gobject/gobject.h" + line="540">The object on which g_object_add_toggle_ref() was called. %TRUE if the toggle reference is now the + filename="gobject/gobject.h" + line="541">%TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. @@ -14852,14 +16490,52 @@ See also: g_object_add_toggle_ref() + + - + A union holding one collected value. + + + the field for holding integer values + + + + the field for holding long integer values + + + + the field for holding 64 bit integer values + + + + the field for holding floating point values + + + + the field for holding pointers + + An opaque structure used as the base of all classes. - + filename="gobject/gtype.h" + line="446">An opaque structure used as the base of all classes. + @@ -14869,8 +16545,8 @@ See also: g_object_add_toggle_ref() deprecated="1" deprecated-version="2.58"> Registers a private structure for an instantiatable type. + filename="gobject/gtype.c" + line="4441">Registers a private structure for an instantiatable type. When an object is allocated, the private structures for the type and all of its parent types are allocated @@ -14934,22 +16610,22 @@ my_object_get_some_field (MyObject *my_object) ]| Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*` family of macros to add instance private data to a type - + class structure for an instantiatable + filename="gobject/gtype.c" + line="4443">class structure for an instantiatable type size of private structure + filename="gobject/gtype.c" + line="4445">size of private structure @@ -14959,8 +16635,8 @@ my_object_get_some_field (MyObject *my_object) version="2.38" introspectable="0"> Gets the offset of the private data for instances of @g_class. + filename="gobject/gtype.c" + line="4676">Gets the offset of the private data for instances of @g_class. This is how many bytes you should add to the instance pointer of a class in order to get the private data for the type represented by @@ -14968,24 +16644,24 @@ class in order to get the private data for the type represented by You can only call this function after you have registered a private data area for @g_class using g_type_class_add_private(). - + the offset, in bytes + filename="gobject/gtype.c" + line="4689">the offset, in bytes a #GTypeClass + filename="gobject/gtype.c" + line="4678">a #GTypeClass - + @@ -15000,78 +16676,92 @@ data area for @g_class using g_type_class_add_private(). This is a convenience function often needed in class initializers. -It returns the class structure of the immediate parent type of the -class passed in. Since derived classes hold a reference count on -their parent classes as long as they are instantiated, the returned -class will always exist. + filename="gobject/gtype.c" + line="2897">Retrieves the class structure of the immediate parent type of the +class passed in. + +This is a convenience function often needed in class initializers. + +Since derived classes hold a reference on their parent classes as +long as they are instantiated, the returned class will always exist. This function is essentially equivalent to: g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) - + the parent class - of @g_class + filename="gobject/gtype.c" + line="2913">the parent class + of @g_class the #GTypeClass structure to - retrieve the parent class for + filename="gobject/gtype.c" + line="2899">the #GTypeClass structure to + retrieve the parent class for - + Decrements the reference count of the class structure being passed in. + filename="gobject/gtype.c" + line="2790">Decrements the reference count of the class structure being passed in. + Once the last reference count of a class has been released, classes may be finalized by the type system, so further dereferencing of a class pointer after g_type_class_unref() are invalid. - + Type class reference counting has been removed and type + classes now cannot be finalized. This function no longer does anything. + a #GTypeClass structure to unref + filename="gobject/gtype.c" + line="2792">a #GTypeClass structure to unref + introspectable="0" + deprecated="1" + deprecated-version="2.84"> A variant of g_type_class_unref() for use in #GTypeClassCacheFunc -implementations. It unreferences a class without consulting the chain + filename="gobject/gtype.c" + line="2808">A variant of g_type_class_unref() for use in #GTypeClassCacheFunc +implementations. + +It unreferences a class without consulting the chain of #GTypeClassCacheFuncs, avoiding the recursion which would occur otherwise. - + Type class reference counting has been removed and type + classes now cannot be finalized. This function no longer does anything. + a #GTypeClass structure to unref + filename="gobject/gtype.c" + line="2810">a #GTypeClass structure to unref - + @@ -15087,28 +16777,57 @@ otherwise. + + Retrieves the type class of the given @type. + +This function will create the class on demand if it does not exist +already. + +If you don't want to create the class, use g_type_class_peek() instead. + + + the class structure + for the type + + + + + type ID of a classed type + + + + This function is essentially the same as g_type_class_ref(), -except that the classes reference count isn't incremented. + filename="gobject/gtype.c" + line="2827">Retrieves the class for a give type. + +This function is essentially the same as g_type_class_get(), +except that the class may have not been instantiated yet. + As a consequence, this function may return %NULL if the class of the type passed in does not currently exist (hasn't been referenced before). - - + + the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist + filename="gobject/gtype.c" + line="2840">the + #GTypeClass structure for the given type ID or %NULL if the class + does not currently exist type ID of a classed type + filename="gobject/gtype.c" + line="2829">type ID of a classed type @@ -15117,46 +16836,51 @@ referenced before). c:identifier="g_type_class_peek_static" version="2.4"> A more efficient version of g_type_class_peek() which works only for + filename="gobject/gtype.c" + line="2862">A more efficient version of g_type_class_peek() which works only for static types. - - + + the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist or is dynamically loaded + filename="gobject/gtype.c" + line="2869">the + #GTypeClass structure for the given type ID or %NULL if the class + does not currently exist or is dynamically loaded type ID of a classed type + filename="gobject/gtype.c" + line="2864">type ID of a classed type - - Increments the reference count of the class structure belonging to -@type. This function will demand-create the class if it doesn't -exist already. - + + Increments the reference count of the class structure belonging to +@type. + +This function will demand-create the class if it doesn't exist already. + Use g_type_class_get() instead + the #GTypeClass - structure for the given type ID + filename="gobject/gtype.c" + line="2779">the #GTypeClass + structure for the given type ID type ID of a classed type + filename="gobject/gtype.c" + line="2772">type ID of a classed type @@ -15164,8 +16888,8 @@ exist already. A callback function which is called when the reference count of a class + filename="gobject/gtype.h" + line="1016">A callback function which is called when the reference count of a class drops to zero. It may use g_type_class_ref() to prevent the class from being freed. You @@ -15175,11 +16899,11 @@ to prevent infinite recursion, use g_type_class_unref_uncached() instead. The functions have to check the class id passed in to figure whether they actually want to cache the class of this type, since all classes are routed through the same #GTypeClassCacheFunc chain. - + %TRUE to stop further #GTypeClassCacheFuncs from being + filename="gobject/gtype.h" + line="1033">%TRUE to stop further #GTypeClassCacheFuncs from being called, %FALSE to continue @@ -15189,14 +16913,14 @@ classes are routed through the same #GTypeClassCacheFunc chain. nullable="1" allow-none="1"> data that was given to the g_type_add_class_cache_func() call + filename="gobject/gtype.h" + line="1018">data that was given to the g_type_add_class_cache_func() call The #GTypeClass structure which is + filename="gobject/gtype.h" + line="1019">The #GTypeClass structure which is unreferenced @@ -15207,131 +16931,131 @@ classes are routed through the same #GTypeClassCacheFunc chain. deprecated-version="2.36" c:type="GTypeDebugFlags"> These flags used to be passed to g_type_init_with_debug_flags() which + filename="gobject/gtype.h" + line="708">These flags used to be passed to g_type_init_with_debug_flags() which is now deprecated. If you need to enable debugging features, use the `GOBJECT_DEBUG` environment variable. g_type_init() is now done automatically - + Print no messages + filename="gobject/gtype.h" + line="710">Print no messages Print messages about object bookkeeping + filename="gobject/gtype.h" + line="711">Print messages about object bookkeeping Print messages about signal emissions + filename="gobject/gtype.h" + line="712">Print messages about signal emissions Keep a count of instances of each type + filename="gobject/gtype.h" + line="714">Keep a count of instances of each type Mask covering all debug flags + filename="gobject/gtype.h" + line="713">Mask covering all debug flags Bit masks used to check or determine characteristics of a type. - + filename="gobject/gtype.h" + line="1071">Bit masks used to check or determine characteristics of a type. + No special flags. Since: 2.74 + filename="gobject/gtype.h" + line="1073">No special flags. Since: 2.74 Indicates an abstract type. No instances can be + filename="gobject/gtype.h" + line="1074">Indicates an abstract type. No instances can be created for an abstract type Indicates an abstract value type, i.e. a type + filename="gobject/gtype.h" + line="1076">Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init() Indicates a final type. A final type is a non-derivable + filename="gobject/gtype.h" + line="1079">Indicates a final type. A final type is a non-derivable leaf node in a deep derivable type hierarchy tree. Since: 2.70 The type is deprecated and may be removed in a + filename="gobject/gtype.h" + line="1081">The type is deprecated and may be removed in a future version. A warning will be emitted if it is instantiated while running with `G_ENABLE_DIAGNOSTIC=1`. Since 2.76 Bit masks used to check or determine specific characteristics of a + filename="gobject/gtype.h" + line="1052">Bit masks used to check or determine specific characteristics of a fundamental type. - + Indicates a classed type + filename="gobject/gtype.h" + line="1054">Indicates a classed type Indicates an instantiatable type (implies classed) + filename="gobject/gtype.h" + line="1055">Indicates an instantiatable type (implies classed) Indicates a flat derivable type + filename="gobject/gtype.h" + line="1056">Indicates a flat derivable type Indicates a deep derivable type (implies derivable) + filename="gobject/gtype.h" + line="1057">Indicates a deep derivable type (implies derivable) A structure that provides information to the type system which is + filename="gobject/gtype.h" + line="1147">A structure that provides information to the type system which is used specifically for managing fundamental types. - + #GTypeFundamentalFlags describing the characteristics of the fundamental type + filename="gobject/gtype.h" + line="1149">#GTypeFundamentalFlags describing the characteristics of the fundamental type This structure is used to provide the type system with the information + filename="gobject/gtype.h" + line="1095">This structure is used to provide the type system with the information required to initialize and destruct (finalize) a type's class and its instances. @@ -15340,31 +17064,31 @@ The initialized structure is passed to the g_type_register_static() function g_type_plugin_complete_type_info()). The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of g_type_register_static(). - + Size of the class structure (required for interface, classed and instantiatable types) + filename="gobject/gtype.h" + line="1097">Size of the class structure (required for interface, classed and instantiatable types) Location of the base initialization function (optional) + filename="gobject/gtype.h" + line="1098">Location of the base initialization function (optional) Location of the base finalization function (optional) + filename="gobject/gtype.h" + line="1099">Location of the base finalization function (optional) Location of the class initialization function for + filename="gobject/gtype.h" + line="1100">Location of the class initialization function for classed and instantiatable types. Location of the default vtable - inititalization function for interface types. (optional) This function + initialization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties. @@ -15372,54 +17096,54 @@ across invocation of g_type_register_static(). Location of the class finalization function for + filename="gobject/gtype.h" + line="1106">Location of the class finalization function for classed and instantiatable types. Location of the default vtable finalization function for interface types. (optional) User-supplied data passed to the class init/finalize functions + filename="gobject/gtype.h" + line="1109">User-supplied data passed to the class init/finalize functions Size of the instance (object) structure (required for instantiatable types only) + filename="gobject/gtype.h" + line="1110">Size of the instance (object) structure (required for instantiatable types only) Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10 this field is ignored. + filename="gobject/gtype.h" + line="1111">Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10 this field is ignored. Location of the instance initialization function (optional, for instantiatable types only) + filename="gobject/gtype.h" + line="1112">Location of the instance initialization function (optional, for instantiatable types only) A #GTypeValueTable function table for generic handling of GValues + filename="gobject/gtype.h" + line="1113">A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types) An opaque structure used as the base of all type instances. - + filename="gobject/gtype.h" + line="456">An opaque structure used as the base of all type instances. + - + @@ -15435,9 +17159,9 @@ across invocation of g_type_register_static(). An opaque structure used as the base of all interface types. - + filename="gobject/gtype.h" + line="466">An opaque structure used as the base of all interface types. + @@ -15446,26 +17170,27 @@ across invocation of g_type_register_static(). Returns the corresponding #GTypeInterface structure of the parent type -of the instance type to which @g_iface belongs. This is useful when -deriving the implementation of an interface from the parent type and -then possibly overriding some methods. - - + filename="gobject/gtype.c" + line="2976">Returns the corresponding #GTypeInterface structure of the parent type +of the instance type to which @g_iface belongs. + +This is useful when deriving the implementation of an interface from the +parent type and then possibly overriding some methods. + + the - corresponding #GTypeInterface structure of the parent type of the - instance type to which @g_iface belongs, or %NULL if the parent - type doesn't conform to the interface + filename="gobject/gtype.c" + line="2986">the + corresponding #GTypeInterface structure of the parent type of the + instance type to which @g_iface belongs, or %NULL if the parent + type doesn't conform to the interface a #GTypeInterface structure + filename="gobject/gtype.c" + line="2978">a #GTypeInterface structure @@ -15473,57 +17198,57 @@ then possibly overriding some methods. Adds @prerequisite_type to the list of prerequisites of @interface_type. + filename="gobject/gtype.c" + line="1509">Adds @prerequisite_type to the list of prerequisites of @interface_type. This means that any type implementing @interface_type must also implement @prerequisite_type. Prerequisites can be thought of as an alternative to interface derivation (which GType doesn't support). An interface can have at most one instantiatable prerequisite type. - + #GType value of an interface type + filename="gobject/gtype.c" + line="1511">#GType value of an interface type #GType value of an interface or instantiatable type + filename="gobject/gtype.c" + line="1512">#GType value of an interface or instantiatable type Returns the #GTypePlugin structure for the dynamic interface + filename="gobject/gtype.c" + line="3802">Returns the #GTypePlugin structure for the dynamic interface @interface_type which has been added to @instance_type, or %NULL if @interface_type has not been added to @instance_type or does not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - + the #GTypePlugin for the dynamic + filename="gobject/gtype.c" + line="3812">the #GTypePlugin for the dynamic interface @interface_type of @instance_type #GType of an instantiatable type + filename="gobject/gtype.c" + line="3804">#GType of an instantiatable type #GType of an interface type + filename="gobject/gtype.c" + line="3805">#GType of an interface type @@ -15532,54 +17257,54 @@ not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). c:identifier="g_type_interface_instantiatable_prerequisite" version="2.68"> Returns the most specific instantiatable prerequisite of an + filename="gobject/gtype.c" + line="1656">Returns the most specific instantiatable prerequisite of an interface type. If the interface type has no instantiatable prerequisite, %G_TYPE_INVALID is returned. See g_type_interface_add_prerequisite() for more information about prerequisites. - + the instantiatable prerequisite type or %G_TYPE_INVALID if none + filename="gobject/gtype.c" + line="1667">the instantiatable prerequisite type or %G_TYPE_INVALID if none an interface type + filename="gobject/gtype.c" + line="1658">an interface type Returns the #GTypeInterface structure of an interface to which the + filename="gobject/gtype.c" + line="2943">Returns the #GTypeInterface structure of an interface to which the passed in class conforms. - - + + the #GTypeInterface - structure of @iface_type if implemented by @instance_class, %NULL - otherwise + filename="gobject/gtype.c" + line="2951">the #GTypeInterface + structure of @iface_type if implemented by @instance_class, %NULL + otherwise a #GTypeClass structure + filename="gobject/gtype.c" + line="2945">a #GTypeClass structure an interface ID which this class conforms to + filename="gobject/gtype.c" + line="2946">an interface ID which this class conforms to @@ -15588,13 +17313,13 @@ passed in class conforms. c:identifier="g_type_interface_prerequisites" version="2.2"> Returns the prerequisites of an interfaces type. - + filename="gobject/gtype.c" + line="1595">Returns the prerequisites of an interfaces type. + a + filename="gobject/gtype.c" + line="1605">a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type @@ -15604,8 +17329,8 @@ passed in class conforms. an interface type + filename="gobject/gtype.c" + line="1597">an interface type optional="1" allow-none="1"> location to return the number + filename="gobject/gtype.c" + line="1598">location to return the number of prerequisites, or %NULL @@ -15627,11 +17352,11 @@ passed in class conforms. c:type="GTypeInterfaceCheckFunc" version="2.4"> A callback called after an interface vtable is initialized. + filename="gobject/gtype.h" + line="1038">A callback called after an interface vtable is initialized. See g_type_add_interface_check(). - + @@ -15641,14 +17366,14 @@ See g_type_add_interface_check(). nullable="1" allow-none="1"> data passed to g_type_add_interface_check() + filename="gobject/gtype.h" + line="1040">data passed to g_type_add_interface_check() the interface that has been + filename="gobject/gtype.h" + line="1041">the interface that has been initialized @@ -15663,41 +17388,46 @@ See g_type_add_interface_check(). glib:get-type="g_type_module_get_type" glib:type-struct="TypeModuleClass"> #GTypeModule provides a simple implementation of the #GTypePlugin + filename="gobject/gtypemodule.c" + line="28">`GTypeModule` provides a simple implementation of the `GTypePlugin` interface. -The model of #GTypeModule is a dynamically loaded module which +The model of `GTypeModule` is a dynamically loaded module which implements some number of types and interface implementations. When the module is loaded, it registers its types and interfaces -using g_type_module_register_type() and g_type_module_add_interface(). +using [method@GObject.TypeModule.register_type] and +[method@GObject.TypeModule.add_interface]. As long as any instances of these types and interface implementations are in use, the module is kept loaded. When the types and interfaces are gone, the module may be unloaded. If the types and interfaces become used again, the module will be reloaded. Note that the last reference cannot be released from within the module code, since that -would lead to the caller's code being unloaded before g_object_unref() +would lead to the caller's code being unloaded before `g_object_unref()` returns to it. Keeping track of whether the module should be loaded or not is done by using a use count - it starts at zero, and whenever it is greater than zero, the module is loaded. The use count is maintained internally by the type system, but also can be explicitly controlled by -g_type_module_use() and g_type_module_unuse(). Typically, when loading -a module for the first type, g_type_module_use() will be used to load -it so that it can initialize its types. At some later point, when the -module no longer needs to be loaded except for the type -implementations it contains, g_type_module_unuse() is called. +[method@GObject.TypeModule.use] and [method@GObject.TypeModule.unuse]. +Typically, when loading a module for the first type, `g_type_module_use()` +will be used to load it so that it can initialize its types. At some later +point, when the module no longer needs to be loaded except for the type +implementations it contains, `g_type_module_unuse()` is called. -#GTypeModule does not actually provide any implementation of module +`GTypeModule` does not actually provide any implementation of module loading and unloading. To create a particular module type you must -derive from #GTypeModule and implement the load and unload functions -in #GTypeModuleClass. - +derive from `GTypeModule` and implement the load and unload functions +in `GTypeModuleClass`. + - + loads the module and registers one or more types using + g_type_module_register_type(). + @@ -15708,7 +17438,10 @@ in #GTypeModuleClass. - + unloads the module + @@ -15720,8 +17453,8 @@ in #GTypeModuleClass. Registers an additional interface for a type, whose interface lives + filename="gobject/gtypemodule.c" + line="453">Registers an additional interface for a type, whose interface lives in the given type plugin. If the interface was already registered for the type in this plugin, nothing will be done. @@ -15730,7 +17463,7 @@ not be unloaded. Since 2.56 if @module is %NULL this will call g_type_add_interface_static() instead. This can be used when making a static build of the module. - + @@ -15740,26 +17473,26 @@ instead. This can be used when making a static build of the module. nullable="1" allow-none="1"> a #GTypeModule + filename="gobject/gtypemodule.c" + line="455">a #GTypeModule type to which to add the interface. + filename="gobject/gtypemodule.c" + line="456">type to which to add the interface. interface type to add + filename="gobject/gtypemodule.c" + line="457">interface type to add type information structure + filename="gobject/gtypemodule.c" + line="458">type information structure @@ -15768,8 +17501,8 @@ instead. This can be used when making a static build of the module. c:identifier="g_type_module_register_enum" version="2.6"> Looks up or registers an enumeration that is implemented with a particular + filename="gobject/gtypemodule.c" + line="524">Looks up or registers an enumeration that is implemented with a particular type plugin. If a type with name @type_name was previously registered, the #GType identifier for the type is returned, otherwise the type is newly registered, and the resulting #GType identifier returned. @@ -15779,11 +17512,11 @@ not be unloaded. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. - + the new or existing type ID + filename="gobject/gtypemodule.c" + line="546">the new or existing type ID @@ -15792,20 +17525,20 @@ instead. This can be used when making a static build of the module. nullable="1" allow-none="1"> a #GTypeModule + filename="gobject/gtypemodule.c" + line="526">a #GTypeModule name for the type + filename="gobject/gtypemodule.c" + line="527">name for the type an array of #GEnumValue structs for the + filename="gobject/gtypemodule.c" + line="528">an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. @@ -15817,8 +17550,8 @@ instead. This can be used when making a static build of the module. c:identifier="g_type_module_register_flags" version="2.6"> Looks up or registers a flags type that is implemented with a particular + filename="gobject/gtypemodule.c" + line="566">Looks up or registers a flags type that is implemented with a particular type plugin. If a type with name @type_name was previously registered, the #GType identifier for the type is returned, otherwise the type is newly registered, and the resulting #GType identifier returned. @@ -15828,11 +17561,11 @@ not be unloaded. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. - + the new or existing type ID + filename="gobject/gtypemodule.c" + line="588">the new or existing type ID @@ -15841,20 +17574,20 @@ instead. This can be used when making a static build of the module. nullable="1" allow-none="1"> a #GTypeModule + filename="gobject/gtypemodule.c" + line="568">a #GTypeModule name for the type + filename="gobject/gtypemodule.c" + line="569">name for the type an array of #GFlagsValue structs for the + filename="gobject/gtypemodule.c" + line="570">an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. @@ -15864,8 +17597,8 @@ instead. This can be used when making a static build of the module. Looks up or registers a type that is implemented with a particular + filename="gobject/gtypemodule.c" + line="353">Looks up or registers a type that is implemented with a particular type plugin. If a type with name @type_name was previously registered, the #GType identifier for the type is returned, otherwise the type is newly registered, and the resulting #GType identifier returned. @@ -15879,11 +17612,11 @@ not be unloaded. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. - + the new or existing type ID + filename="gobject/gtypemodule.c" + line="376">the new or existing type ID @@ -15892,100 +17625,100 @@ instead. This can be used when making a static build of the module. nullable="1" allow-none="1"> a #GTypeModule + filename="gobject/gtypemodule.c" + line="355">a #GTypeModule the type for the parent class + filename="gobject/gtypemodule.c" + line="356">the type for the parent class name for the type + filename="gobject/gtypemodule.c" + line="357">name for the type type information structure + filename="gobject/gtypemodule.c" + line="358">type information structure flags field providing details about the type + filename="gobject/gtypemodule.c" + line="359">flags field providing details about the type Sets the name for a #GTypeModule - + filename="gobject/gtypemodule.c" + line="178">Sets the name for a #GTypeModule + a #GTypeModule. + filename="gobject/gtypemodule.c" + line="180">a #GTypeModule. a human-readable name to use in error messages. + filename="gobject/gtypemodule.c" + line="181">a human-readable name to use in error messages. Decreases the use count of a #GTypeModule by one. If the + filename="gobject/gtypemodule.c" + line="279">Decreases the use count of a #GTypeModule by one. If the result is zero, the module will be unloaded. (However, the #GTypeModule will not be freed, and types associated with the #GTypeModule are not unregistered. Once a #GTypeModule is initialized, it must exist forever.) - + a #GTypeModule + filename="gobject/gtypemodule.c" + line="281">a #GTypeModule Increases the use count of a #GTypeModule by one. If the + filename="gobject/gtypemodule.c" + line="231">Increases the use count of a #GTypeModule by one. If the use count was zero before, the plugin will be loaded. If loading the plugin fails, the use count is reset to its prior value. - + %FALSE if the plugin needed to be loaded and + filename="gobject/gtypemodule.c" + line="240">%FALSE if the plugin needed to be loaded and loading the plugin failed. a #GTypeModule + filename="gobject/gtypemodule.c" + line="233">a #GTypeModule @@ -16008,8 +17741,8 @@ its prior value. the name of the module + filename="gobject/gtypemodule.c" + line="30">the name of the module @@ -16017,19 +17750,23 @@ its prior value. c:type="GTypeModuleClass" glib:is-gtype-struct-for="TypeModule"> In order to implement dynamic loading of types based on #GTypeModule, + filename="gobject/gtypemodule.h" + line="55">In order to implement dynamic loading of types based on #GTypeModule, the @load and @unload functions in #GTypeModuleClass must be implemented. - + the parent class + filename="gobject/gtypemodule.h" + line="57">the parent class + loads the module and registers one or more types using + g_type_module_register_type(). - + @@ -16041,8 +17778,11 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. + unloads the module - + @@ -16055,7 +17795,7 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. - + @@ -16063,7 +17803,7 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. - + @@ -16071,7 +17811,7 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. - + @@ -16079,7 +17819,7 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. - + @@ -16092,8 +17832,8 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. glib:type-name="GTypePlugin" glib:get-type="g_type_plugin_get_type"> An interface that handles the lifecycle of dynamically loaded types. + filename="gobject/gtypeplugin.c" + line="25">An interface that handles the lifecycle of dynamically loaded types. The GObject type system supports dynamic loading of types. It goes as follows: @@ -16101,81 +17841,81 @@ It goes as follows: 1. The type is initially introduced (usually upon loading the module the first time, or by your main application that knows what modules introduces what types), like this: - |[<!-- language="C" --> + ```c new_type_id = g_type_register_dynamic (parent_type_id, "TypeName", new_type_plugin, type_flags); - ]| - where @new_type_plugin is an implementation of the - #GTypePlugin interface. + ``` + where `new_type_plugin` is an implementation of the + `GTypePlugin` interface. 2. The type's implementation is referenced, e.g. through - g_type_class_ref() or through g_type_create_instance() (this is - being called by g_object_new()) or through one of the above done on - a type derived from @new_type_id. + [func@GObject.TypeClass.ref] or through [func@GObject.type_create_instance] + (this is being called by [ctor@GObject.Object.new]) or through one of the above + done on a type derived from `new_type_id`. -3. This causes the type system to load the type's implementation by - calling g_type_plugin_use() and g_type_plugin_complete_type_info() - on @new_type_plugin. +3. This causes the type system to load the type's implementation by calling + [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info] + on `new_type_plugin`. -4. At some point the type's implementation isn't required anymore, - e.g. after g_type_class_unref() or g_type_free_instance() (called - when the reference count of an instance drops to zero). +4. At some point the type's implementation isn't required anymore, e.g. after + [method@GObject.TypeClass.unref] or [func@GObject.type_free_instance] + (called when the reference count of an instance drops to zero). 5. This causes the type system to throw away the information retrieved - from g_type_plugin_complete_type_info() and then it calls - g_type_plugin_unuse() on @new_type_plugin. + from [method@GObject.TypePlugin.complete_type_info] and then it calls + [method@GObject.TypePlugin.unuse] on `new_type_plugin`. 6. Things may repeat from the second step. -So basically, you need to implement a #GTypePlugin type that +So basically, you need to implement a `GTypePlugin` type that carries a use_count, once use_count goes from zero to one, you need to load the implementation to successfully handle the upcoming -g_type_plugin_complete_type_info() call. Later, maybe after +[method@GObject.TypePlugin.complete_type_info] call. Later, maybe after succeeding use/unuse calls, once use_count drops to zero, you can unload the implementation again. The type system makes sure to call -g_type_plugin_use() and g_type_plugin_complete_type_info() again -when the type is needed again. +[method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info] +again when the type is needed again. -#GTypeModule is an implementation of #GTypePlugin that already -implements most of this except for the actual module loading and +[class@GObject.TypeModule] is an implementation of `GTypePlugin` that +already implements most of this except for the actual module loading and unloading. It even handles multiple registered types per module. Calls the @complete_interface_info function from the + filename="gobject/gtypeplugin.c" + line="174">Calls the @complete_interface_info function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. - + the #GTypePlugin + filename="gobject/gtypeplugin.c" + line="176">the #GTypePlugin the #GType of an instantiatable type to which the interface + filename="gobject/gtypeplugin.c" + line="177">the #GType of an instantiatable type to which the interface is added the #GType of the interface whose info is completed + filename="gobject/gtypeplugin.c" + line="179">the #GType of the interface whose info is completed the #GInterfaceInfo to fill in + filename="gobject/gtypeplugin.c" + line="180">the #GInterfaceInfo to fill in @@ -16183,75 +17923,75 @@ function outside of the GObject type system itself. Calls the @complete_type_info function from the #GTypePluginClass of @plugin. + filename="gobject/gtypeplugin.c" + line="144">Calls the @complete_type_info function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. - + a #GTypePlugin + filename="gobject/gtypeplugin.c" + line="146">a #GTypePlugin the #GType whose info is completed + filename="gobject/gtypeplugin.c" + line="147">the #GType whose info is completed the #GTypeInfo struct to fill in + filename="gobject/gtypeplugin.c" + line="148">the #GTypeInfo struct to fill in the #GTypeValueTable to fill in + filename="gobject/gtypeplugin.c" + line="149">the #GTypeValueTable to fill in Calls the @unuse_plugin function from the #GTypePluginClass of + filename="gobject/gtypeplugin.c" + line="125">Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. - + a #GTypePlugin + filename="gobject/gtypeplugin.c" + line="127">a #GTypePlugin Calls the @use_plugin function from the #GTypePluginClass of + filename="gobject/gtypeplugin.c" + line="106">Calls the @use_plugin function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. - + a #GTypePlugin + filename="gobject/gtypeplugin.c" + line="108">a #GTypePlugin @@ -16259,29 +17999,29 @@ the GObject type system itself. The #GTypePlugin interface is used by the type system in order to handle + filename="gobject/gtypeplugin.h" + line="83">The #GTypePlugin interface is used by the type system in order to handle the lifecycle of dynamically loaded types. - + Increases the use count of the plugin. + filename="gobject/gtypeplugin.h" + line="85">Increases the use count of the plugin. Decreases the use count of the plugin. + filename="gobject/gtypeplugin.h" + line="86">Decreases the use count of the plugin. Fills in the #GTypeInfo and + filename="gobject/gtypeplugin.h" + line="87">Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with `memset(s, 0, sizeof (s))` before calling this function. Fills in missing parts of the #GInterfaceInfo + filename="gobject/gtypeplugin.h" + line="90">Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with `memset(s, 0, sizeof (s))` before calling this function. The type of the @complete_interface_info function of #GTypePluginClass. - + the #GTypePlugin the #GType of an instantiatable type to which the interface is added the #GType of the interface whose info is completed the #GInterfaceInfo to fill in @@ -16337,34 +18077,34 @@ the lifecycle of dynamically loaded types. The type of the @complete_type_info function of #GTypePluginClass. - + the #GTypePlugin the #GType whose info is completed the #GTypeInfo struct to fill in the #GTypeValueTable to fill in @@ -16372,16 +18112,16 @@ the lifecycle of dynamically loaded types. The type of the @unuse_plugin function of #GTypePluginClass. - + the #GTypePlugin whose use count should be decreased @@ -16389,17 +18129,17 @@ the lifecycle of dynamically loaded types. The type of the @use_plugin function of #GTypePluginClass, which gets called to increase the use count of @plugin. - + the #GTypePlugin whose use count should be increased @@ -16407,33 +18147,33 @@ to increase the use count of @plugin. A structure holding information for a specific type. + filename="gobject/gtype.h" + line="477">A structure holding information for a specific type. See also: g_type_query() - + the #GType value of the type + filename="gobject/gtype.h" + line="479">the #GType value of the type the name of the type + filename="gobject/gtype.h" + line="480">the name of the type the size of the class structure + filename="gobject/gtype.h" + line="481">the size of the class structure the size of the instance structure + filename="gobject/gtype.h" + line="482">the size of the instance structure @@ -16441,8 +18181,8 @@ See also: g_type_query() c:type="GTypeValueCollectFunc" version="2.78"> This function is responsible for converting the values collected from + filename="gobject/gtype.h" + line="1260">This function is responsible for converting the values collected from a variadic argument list into contents suitable for storage in a #GValue. This function should setup @value similar to #GTypeValueInitFunc; e.g. @@ -16513,39 +18253,39 @@ prior to returning an error; however, `collect_values()` is not obliged to return a correctly setup @value for error returns, simply because any non-`NULL` return is considered a fatal programming error, and further program behaviour is undefined. - + `NULL` on success, otherwise a + filename="gobject/gtype.h" + line="1339">`NULL` on success, otherwise a newly allocated error string on failure the value to initialize + filename="gobject/gtype.h" + line="1262">the value to initialize the number of collected values + filename="gobject/gtype.h" + line="1263">the number of collected values the collected values + filename="gobject/gtype.h" + line="1264">the collected values optional flags + filename="gobject/gtype.h" + line="1265">optional flags @@ -16554,8 +18294,8 @@ further program behaviour is undefined. c:type="GTypeValueCopyFunc" version="2.78"> Copies the content of a #GValue into another. + filename="gobject/gtype.h" + line="1216">Copies the content of a #GValue into another. The @dest_value is a #GValue with zero-filled data section and @src_value is a properly initialized #GValue of same type, or derived type. @@ -16567,15 +18307,15 @@ contents of @dest_value remain valid. String type example: |[<!-- language="C" --> dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| - + the value to copy + filename="gobject/gtype.h" + line="1218">the value to copy the location of the copy + filename="gobject/gtype.h" + line="1219">the location of the copy @@ -16593,8 +18333,8 @@ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); c:type="GTypeValueFreeFunc" version="2.78"> Frees any old contents that might be left in the `value->data` array of + filename="gobject/gtype.h" + line="1195">Frees any old contents that might be left in the `value->data` array of the given value. No resources may remain allocated through the #GValue contents after this @@ -16605,15 +18345,15 @@ function returns. E.g. for our above string type: if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| - + the value to free + filename="gobject/gtype.h" + line="1197">the value to free @@ -16622,8 +18362,8 @@ if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) c:type="GTypeValueInitFunc" version="2.78"> Initializes the value contents by setting the fields of the `value->data` + filename="gobject/gtype.h" + line="1174">Initializes the value contents by setting the fields of the `value->data` array. The data array of the #GValue passed into this function was zero-filled @@ -16634,15 +18374,15 @@ implementation might look like: |[<!-- language="C" --> value->data[0].v_pointer = g_strdup (""); ]| - + the value to initialize + filename="gobject/gtype.h" + line="1176">the value to initialize @@ -16651,8 +18391,8 @@ value->data[0].v_pointer = g_strdup (""); c:type="GTypeValueLCopyFunc" version="2.78"> This function is responsible for storing the `value` + filename="gobject/gtype.h" + line="1350">This function is responsible for storing the `value` contents into arguments passed through a variadic argument list which got collected into `collect_values` according to `lcopy_format`. @@ -16694,31 +18434,31 @@ else return NULL; ]| - + `NULL` on success, otherwise + filename="gobject/gtype.h" + line="1401">`NULL` on success, otherwise a newly allocated error string on failure the value to lcopy + filename="gobject/gtype.h" + line="1352">the value to lcopy the number of collected values + filename="gobject/gtype.h" + line="1353">the number of collected values the collected + filename="gobject/gtype.h" + line="1354">the collected locations for storage @@ -16726,8 +18466,8 @@ return NULL; optional flags + filename="gobject/gtype.h" + line="1356">optional flags @@ -16736,8 +18476,8 @@ return NULL; c:type="GTypeValuePeekPointerFunc" version="2.78"> If the value contents fit into a pointer, such as objects or strings, + filename="gobject/gtype.h" + line="1240">If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: @@ -16745,90 +18485,91 @@ To extend on our above string example: |[<!-- language="C" --> return value->data[0].v_pointer; ]| - + a pointer to the value contents + filename="gobject/gtype.h" + line="1253">a pointer to the value contents the value to peek + filename="gobject/gtype.h" + line="1242">the value to peek The #GTypeValueTable provides the functions required by the #GValue + filename="gobject/gtype.h" + line="1412">- `'i'`: Integers, passed as `collect_values[].v_int` + - `'l'`: Longs, passed as `collect_values[].v_long` + - `'d'`: Doubles, passed as `collect_values[].v_double` + - `'p'`: Pointers, passed as `collect_values[].v_pointer` + + It should be noted that for variable argument list construction, + ANSI C promotes every type smaller than an integer to an int, and + floats to doubles. So for collection of short int or char, `'i'` + needs to be used, and for collection of floats `'d'`. +The #GTypeValueTable provides the functions required by the #GValue implementation, to serve as a container for values of a type. - + Function to initialize a GValue + filename="gobject/gtype.h" + line="1414">Function to initialize a GValue Function to free a GValue + filename="gobject/gtype.h" + line="1415">Function to free a GValue Function to copy a GValue + filename="gobject/gtype.h" + line="1416">Function to copy a GValue Function to peek the contents of a GValue if they fit + filename="gobject/gtype.h" + line="1417">Function to peek the contents of a GValue if they fit into a pointer A string format describing how to collect the contents of + filename="gobject/gtype.h" + line="1419">A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate - the type of the argument. Currently supported arguments are: - - `'i'`: Integers, passed as `collect_values[].v_int` - - `'l'`: Longs, passed as `collect_values[].v_long` - - `'d'`: Doubles, passed as `collect_values[].v_double` - - `'p'`: Pointers, passed as `collect_values[].v_pointer` - It should be noted that for variable argument list construction, - ANSI C promotes every type smaller than an integer to an int, and - floats to doubles. So for collection of short int or char, `'i'` - needs to be used, and for collection of floats `'d'`. + the type of the argument. Currently supported arguments are: Function to initialize a GValue from the values + filename="gobject/gtype.h" + line="1433">Function to initialize a GValue from the values collected from variadic arguments Format description of the arguments to collect for @lcopy_value, + filename="gobject/gtype.h" + line="1435">Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of `'p'`s to provide lcopy_value() with pointers to storage locations. Function to store the contents of a value into the + filename="gobject/gtype.h" + line="1438">Function to store the contents of a value into the locations collected from variadic arguments @@ -16836,48 +18577,232 @@ implementation, to serve as a container for values of a type. c:identifier="g_type_value_table_peek" introspectable="0"> Returns the location of the #GTypeValueTable associated with @type. + filename="gobject/gtype.c" + line="4101">Returns the location of the #GTypeValueTable associated with @type. Note that this function should only be used from source code that implements or has internal knowledge of the implementation of @type. - - + + location of the #GTypeValueTable associated with @type or - %NULL if there is no #GTypeValueTable associated with @type + filename="gobject/gtype.c" + line="4111">location of the #GTypeValueTable + associated with @type or %NULL if there is no #GTypeValueTable + associated with @type a #GType + filename="gobject/gtype.c" + line="4103">a #GType + + + + + + + + + + + + + + + + + + + + + + Collects a variable argument value from a `va_list`. + +We have to implement the varargs collection as a macro, because on some systems +`va_list` variables cannot be passed by reference. + +Note: If you are creating the @value argument just before calling this macro, +you should use the G_VALUE_COLLECT_INIT() variant and pass the uninitialized +#GValue. That variant is faster than G_VALUE_COLLECT(). + + + + a #GValue return location. @value is supposed to be initialized + according to the value type to be collected + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the collect_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error messages if something fails + + + + + The maximal number of #GTypeCValues which can be collected for a +single #GValue. + + + + + Collects a variable argument value from a `va_list`. + +We have to implement the varargs collection as a macro, because on some +systems `va_list` variables cannot be passed by reference. + + + + a #GValue return location. @value must contain only 0 bytes. + + + the #GType to use for @value. + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the collect_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error messages if something fails + + + + + A variant of G_VALUE_COLLECT_INIT() that provides the #GTypeValueTable +to the caller. + + + + a #GValue return location. @value must contain only 0 bytes. + + + a #GTypeValueTable pointer that will be set to the value table + for @_value_type + + + the #GType to use for @value. + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the collect_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error messages if something fails + + + + + Skip an argument of type @_value_type from @var_args. + + + + the #GType of the value to skip + + + the va_list variable; it may be evaluated multiple times + + + Checks if @value holds (or contains) a value of @type. This macro will also check for @value != %NULL and issue a warning if the check fails. - + A #GValue structure. A #GType value. @@ -16886,13 +18811,13 @@ warning if the check fails. c:identifier="G_VALUE_HOLDS_BOOLEAN" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. - + a valid #GValue structure @@ -16901,14 +18826,14 @@ warning if the check fails. c:identifier="G_VALUE_HOLDS_BOXED" introspectable="0"> Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. - + a valid #GValue structure @@ -16917,13 +18842,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_CHAR" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. - + a valid #GValue structure @@ -16932,13 +18857,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_DOUBLE" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. - + a valid #GValue structure @@ -16947,13 +18872,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_ENUM" introspectable="0"> Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. - + a valid #GValue structure @@ -16962,13 +18887,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_FLAGS" introspectable="0"> Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. - + a valid #GValue structure @@ -16977,13 +18902,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_FLOAT" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. - + a valid #GValue structure @@ -16993,13 +18918,13 @@ from type %G_TYPE_BOXED. version="2.12" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. - + a valid #GValue structure @@ -17008,13 +18933,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_INT" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_INT. - + a valid #GValue structure @@ -17023,13 +18948,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_INT64" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_INT64. - + a valid #GValue structure @@ -17038,13 +18963,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_LONG" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_LONG. - + a valid #GValue structure @@ -17053,13 +18978,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_OBJECT" introspectable="0"> Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. - + a valid #GValue structure @@ -17068,13 +18993,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_PARAM" introspectable="0"> Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. - + a valid #GValue structure @@ -17083,13 +19008,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_POINTER" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. - + a valid #GValue structure @@ -17098,13 +19023,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_STRING" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_STRING. - + a valid #GValue structure @@ -17113,13 +19038,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_UCHAR" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. - + a valid #GValue structure @@ -17128,13 +19053,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_UINT" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_UINT. - + a valid #GValue structure @@ -17143,13 +19068,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_UINT64" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. - + a valid #GValue structure @@ -17158,13 +19083,13 @@ from type %G_TYPE_BOXED. c:identifier="G_VALUE_HOLDS_ULONG" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. - + a valid #GValue structure @@ -17174,13 +19099,13 @@ from type %G_TYPE_BOXED. version="2.26" introspectable="0"> Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. - + a valid #GValue structure @@ -17190,10 +19115,10 @@ from type %G_TYPE_BOXED. c:type="G_VALUE_INTERNED_STRING" version="2.66"> For string values, indicates that the string contained is canonical and will exist for the duration of the process. See g_value_set_interned_string(). - + version="2.66" introspectable="0"> Checks whether @value contains a string which is canonical. - + a valid #GValue structure + + Stores a value’s value into one or more argument locations from a `va_list`. + +This is the inverse of G_VALUE_COLLECT(). + + + + a #GValue to store into the @var_args; this must be initialized + and set + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the lcopy_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error message if something fails + + + If passed to G_VALUE_COLLECT(), allocated data won't be copied but used verbatim. This does not affect ref-counted types like objects. This does not affect usage of g_value_copy(), the data will be copied if it is not ref-counted. - + Get the type identifier of @value. - + A #GValue structure. @@ -17243,13 +19203,13 @@ be copied if it is not ref-counted. c:identifier="G_VALUE_TYPE_NAME" introspectable="0"> Gets the type name of @value. - + A #GValue structure. @@ -17258,18 +19218,18 @@ be copied if it is not ref-counted. c:type="GVaClosureMarshal" introspectable="0"> This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues. - + the #GClosure to which the marshaller belongs @@ -17278,7 +19238,7 @@ marshalling the signal argument into GValues. nullable="1" allow-none="1"> a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. @@ -17286,14 +19246,14 @@ marshalling the signal argument into GValues. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. @@ -17302,7 +19262,7 @@ marshalling the signal argument into GValues. nullable="1" allow-none="1"> additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() @@ -17310,13 +19270,13 @@ marshalling the signal argument into GValues. the length of the @param_types array the #GType of each argument from @args. @@ -17331,7 +19291,7 @@ marshalling the signal argument into GValues. glib:get-type="g_value_get_type" c:symbol-prefix="value"> An opaque structure used to hold different types of values. The data within the structure has protected scope: it is accessible only @@ -17342,7 +19302,7 @@ types. #GValue users cannot make any assumptions about how data is stored within the 2 element @data union, and the @g_type member should only be accessed through the G_VALUE_TYPE() macro. - + @@ -17353,23 +19313,23 @@ only be accessed through the G_VALUE_TYPE() macro. Copies the value of @src_value into @dest_value. - + filename="gobject/gvalue.c" + line="110">Copies the value of @src_value into @dest_value. + An initialized #GValue structure. + filename="gobject/gvalue.c" + line="112">An initialized #GValue structure. An initialized #GValue structure of the same type as @src_value. + filename="gobject/gvalue.c" + line="113">An initialized #GValue structure of the same type as @src_value. @@ -17378,46 +19338,46 @@ only be accessed through the G_VALUE_TYPE() macro. c:identifier="g_value_dup_boxed" introspectable="0"> Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, + filename="gobject/gboxed.c" + line="429">Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, the boxed value is duplicated and needs to be later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value); - + boxed contents of @value + filename="gobject/gboxed.c" + line="438">boxed contents of @value a valid #GValue of %G_TYPE_BOXED derived type + filename="gobject/gboxed.c" + line="431">a valid #GValue of %G_TYPE_BOXED derived type Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing + filename="gobject/gobject.c" + line="5129">Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count. If the contents of the #GValue are %NULL, then %NULL will be returned. - + object content of @value, + filename="gobject/gobject.c" + line="5137">object content of @value, should be unreferenced when no longer needed. a valid #GValue whose type is derived from %G_TYPE_OBJECT + filename="gobject/gobject.c" + line="5131">a valid #GValue whose type is derived from %G_TYPE_OBJECT @@ -17426,42 +19386,42 @@ its reference count. If the contents of the #GValue are %NULL, then c:identifier="g_value_dup_param" introspectable="0"> Get the contents of a %G_TYPE_PARAM #GValue, increasing its + filename="gobject/gparam.c" + line="1603">Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. - + #GParamSpec content of @value, should be + filename="gobject/gparam.c" + line="1610">#GParamSpec content of @value, should be unreferenced when no longer needed. a valid #GValue whose type is derived from %G_TYPE_PARAM + filename="gobject/gparam.c" + line="1605">a valid #GValue whose type is derived from %G_TYPE_PARAM Get a copy the contents of a %G_TYPE_STRING #GValue. - + filename="gobject/gvaluetypes.c" + line="1147">Get a copy the contents of a %G_TYPE_STRING #GValue. + a newly allocated copy of the string content of @value + filename="gobject/gvaluetypes.c" + line="1153">a newly allocated copy of the string content of @value a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1149">a valid #GValue of type %G_TYPE_STRING @@ -17470,83 +19430,83 @@ reference count. c:identifier="g_value_dup_variant" version="2.26"> Get the contents of a variant #GValue, increasing its refcount. The returned + filename="gobject/gvaluetypes.c" + line="1355">Get the contents of a variant #GValue, increasing its refcount. The returned #GVariant is never floating. - + variant contents of @value (may be %NULL); + filename="gobject/gvaluetypes.c" + line="1362">variant contents of @value (may be %NULL); should be unreffed using g_variant_unref() when no longer needed a valid #GValue of type %G_TYPE_VARIANT + filename="gobject/gvaluetypes.c" + line="1357">a valid #GValue of type %G_TYPE_VARIANT Determines if @value will fit inside the size of a pointer value. + filename="gobject/gvalue.c" + line="201">Determines if @value will fit inside the size of a pointer value. This is an internal function introduced mainly for C marshallers. - + %TRUE if @value will fit inside a pointer value. + filename="gobject/gvalue.c" + line="208">%TRUE if @value will fit inside a pointer value. An initialized #GValue structure. + filename="gobject/gvalue.c" + line="203">An initialized #GValue structure. Get the contents of a %G_TYPE_BOOLEAN #GValue. - + filename="gobject/gvaluetypes.c" + line="749">Get the contents of a %G_TYPE_BOOLEAN #GValue. + boolean contents of @value + filename="gobject/gvaluetypes.c" + line="755">boolean contents of @value a valid #GValue of type %G_TYPE_BOOLEAN + filename="gobject/gvaluetypes.c" + line="751">a valid #GValue of type %G_TYPE_BOOLEAN Get the contents of a %G_TYPE_BOXED derived #GValue. - + filename="gobject/gboxed.c" + line="412">Get the contents of a %G_TYPE_BOXED derived #GValue. + boxed contents of @value + filename="gobject/gboxed.c" + line="418">boxed contents of @value a valid #GValue of %G_TYPE_BOXED derived type + filename="gobject/gboxed.c" + line="414">a valid #GValue of %G_TYPE_BOXED derived type @@ -17556,364 +19516,364 @@ This is an internal function introduced mainly for C marshallers. deprecated="1" deprecated-version="2.32"> Do not use this function; it is broken on platforms where the %char + filename="gobject/gvaluetypes.c" + line="646">Do not use this function; it is broken on platforms where the %char type is unsigned, such as ARM and PowerPC. See g_value_get_schar(). Get the contents of a %G_TYPE_CHAR #GValue. This function's return type is broken, see g_value_get_schar() - + character contents of @value + filename="gobject/gvaluetypes.c" + line="655">character contents of @value a valid #GValue of type %G_TYPE_CHAR + filename="gobject/gvaluetypes.c" + line="648">a valid #GValue of type %G_TYPE_CHAR Get the contents of a %G_TYPE_DOUBLE #GValue. - + filename="gobject/gvaluetypes.c" + line="1005">Get the contents of a %G_TYPE_DOUBLE #GValue. + double contents of @value + filename="gobject/gvaluetypes.c" + line="1011">double contents of @value a valid #GValue of type %G_TYPE_DOUBLE + filename="gobject/gvaluetypes.c" + line="1007">a valid #GValue of type %G_TYPE_DOUBLE Get the contents of a %G_TYPE_ENUM #GValue. - + filename="gobject/genums.c" + line="680">Get the contents of a %G_TYPE_ENUM #GValue. + enum contents of @value + filename="gobject/genums.c" + line="686">enum contents of @value a valid #GValue whose type is derived from %G_TYPE_ENUM + filename="gobject/genums.c" + line="682">a valid #GValue whose type is derived from %G_TYPE_ENUM Get the contents of a %G_TYPE_FLAGS #GValue. - + filename="gobject/genums.c" + line="712">Get the contents of a %G_TYPE_FLAGS #GValue. + flags contents of @value + filename="gobject/genums.c" + line="718">flags contents of @value a valid #GValue whose type is derived from %G_TYPE_FLAGS + filename="gobject/genums.c" + line="714">a valid #GValue whose type is derived from %G_TYPE_FLAGS Get the contents of a %G_TYPE_FLOAT #GValue. - + filename="gobject/gvaluetypes.c" + line="973">Get the contents of a %G_TYPE_FLOAT #GValue. + float contents of @value + filename="gobject/gvaluetypes.c" + line="979">float contents of @value a valid #GValue of type %G_TYPE_FLOAT + filename="gobject/gvaluetypes.c" + line="975">a valid #GValue of type %G_TYPE_FLOAT Get the contents of a %G_TYPE_GTYPE #GValue. - + filename="gobject/gvaluetypes.c" + line="1251">Get the contents of a %G_TYPE_GTYPE #GValue. + the #GType stored in @value + filename="gobject/gvaluetypes.c" + line="1259">the #GType stored in @value a valid #GValue of type %G_TYPE_GTYPE + filename="gobject/gvaluetypes.c" + line="1253">a valid #GValue of type %G_TYPE_GTYPE Get the contents of a %G_TYPE_INT #GValue. - + filename="gobject/gvaluetypes.c" + line="781">Get the contents of a %G_TYPE_INT #GValue. + integer contents of @value + filename="gobject/gvaluetypes.c" + line="787">integer contents of @value a valid #GValue of type %G_TYPE_INT + filename="gobject/gvaluetypes.c" + line="783">a valid #GValue of type %G_TYPE_INT Get the contents of a %G_TYPE_INT64 #GValue. - + filename="gobject/gvaluetypes.c" + line="893">Get the contents of a %G_TYPE_INT64 #GValue. + 64bit integer contents of @value + filename="gobject/gvaluetypes.c" + line="899">64bit integer contents of @value a valid #GValue of type %G_TYPE_INT64 + filename="gobject/gvaluetypes.c" + line="895">a valid #GValue of type %G_TYPE_INT64 Get the contents of a %G_TYPE_LONG #GValue. - + filename="gobject/gvaluetypes.c" + line="845">Get the contents of a %G_TYPE_LONG #GValue. + long integer contents of @value + filename="gobject/gvaluetypes.c" + line="851">long integer contents of @value a valid #GValue of type %G_TYPE_LONG + filename="gobject/gvaluetypes.c" + line="847">a valid #GValue of type %G_TYPE_LONG Get the contents of a %G_TYPE_OBJECT derived #GValue. - + filename="gobject/gobject.c" + line="5113">Get the contents of a %G_TYPE_OBJECT derived #GValue. + object contents of @value + filename="gobject/gobject.c" + line="5119">object contents of @value a valid #GValue of %G_TYPE_OBJECT derived type + filename="gobject/gobject.c" + line="5115">a valid #GValue of %G_TYPE_OBJECT derived type Get the contents of a %G_TYPE_PARAM #GValue. - + filename="gobject/gparam.c" + line="1587">Get the contents of a %G_TYPE_PARAM #GValue. + #GParamSpec content of @value + filename="gobject/gparam.c" + line="1593">#GParamSpec content of @value a valid #GValue whose type is derived from %G_TYPE_PARAM + filename="gobject/gparam.c" + line="1589">a valid #GValue whose type is derived from %G_TYPE_PARAM Get the contents of a pointer #GValue. - + filename="gobject/gvaluetypes.c" + line="1214">Get the contents of a pointer #GValue. + pointer contents of @value + filename="gobject/gvaluetypes.c" + line="1220">pointer contents of @value a valid #GValue of %G_TYPE_POINTER + filename="gobject/gvaluetypes.c" + line="1216">a valid #GValue of %G_TYPE_POINTER Get the contents of a %G_TYPE_CHAR #GValue. - + filename="gobject/gvaluetypes.c" + line="684">Get the contents of a %G_TYPE_CHAR #GValue. + signed 8 bit integer contents of @value + filename="gobject/gvaluetypes.c" + line="690">signed 8 bit integer contents of @value a valid #GValue of type %G_TYPE_CHAR + filename="gobject/gvaluetypes.c" + line="686">a valid #GValue of type %G_TYPE_CHAR Get the contents of a %G_TYPE_STRING #GValue. - + filename="gobject/gvaluetypes.c" + line="1131">Get the contents of a %G_TYPE_STRING #GValue. + string content of @value + filename="gobject/gvaluetypes.c" + line="1137">string content of @value a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1133">a valid #GValue of type %G_TYPE_STRING Get the contents of a %G_TYPE_UCHAR #GValue. - + filename="gobject/gvaluetypes.c" + line="717">Get the contents of a %G_TYPE_UCHAR #GValue. + unsigned character contents of @value + filename="gobject/gvaluetypes.c" + line="723">unsigned character contents of @value a valid #GValue of type %G_TYPE_UCHAR + filename="gobject/gvaluetypes.c" + line="719">a valid #GValue of type %G_TYPE_UCHAR Get the contents of a %G_TYPE_UINT #GValue. - + filename="gobject/gvaluetypes.c" + line="813">Get the contents of a %G_TYPE_UINT #GValue. + unsigned integer contents of @value + filename="gobject/gvaluetypes.c" + line="819">unsigned integer contents of @value a valid #GValue of type %G_TYPE_UINT + filename="gobject/gvaluetypes.c" + line="815">a valid #GValue of type %G_TYPE_UINT Get the contents of a %G_TYPE_UINT64 #GValue. - + filename="gobject/gvaluetypes.c" + line="941">Get the contents of a %G_TYPE_UINT64 #GValue. + unsigned 64bit integer contents of @value + filename="gobject/gvaluetypes.c" + line="947">unsigned 64bit integer contents of @value a valid #GValue of type %G_TYPE_UINT64 + filename="gobject/gvaluetypes.c" + line="943">a valid #GValue of type %G_TYPE_UINT64 Get the contents of a %G_TYPE_ULONG #GValue. - + filename="gobject/gvaluetypes.c" + line="877">Get the contents of a %G_TYPE_ULONG #GValue. + unsigned long integer contents of @value + filename="gobject/gvaluetypes.c" + line="883">unsigned long integer contents of @value a valid #GValue of type %G_TYPE_ULONG + filename="gobject/gvaluetypes.c" + line="879">a valid #GValue of type %G_TYPE_ULONG @@ -17922,46 +19882,46 @@ Get the contents of a %G_TYPE_CHAR #GValue. c:identifier="g_value_get_variant" version="2.26"> Get the contents of a variant #GValue. - + filename="gobject/gvaluetypes.c" + line="1337">Get the contents of a variant #GValue. + variant contents of @value (may be %NULL) + filename="gobject/gvaluetypes.c" + line="1343">variant contents of @value (may be %NULL) a valid #GValue of type %G_TYPE_VARIANT + filename="gobject/gvaluetypes.c" + line="1339">a valid #GValue of type %G_TYPE_VARIANT Initializes @value with the default value of @type. - + filename="gobject/gvalue.c" + line="71">Initializes @value with the default value of @type. + the #GValue structure that has been passed in + filename="gobject/gvalue.c" + line="78">the #GValue structure that has been passed in A zero-filled (uninitialized) #GValue structure. + filename="gobject/gvalue.c" + line="73">A zero-filled (uninitialized) #GValue structure. Type the #GValue should hold values of. + filename="gobject/gvalue.c" + line="74">Type the #GValue should hold values of. @@ -17970,112 +19930,112 @@ Get the contents of a %G_TYPE_CHAR #GValue. c:identifier="g_value_init_from_instance" version="2.42"> Initializes and sets @value from an instantiatable type via the + filename="gobject/gvalue.c" + line="305">Initializes and sets @value from an instantiatable type via the value_table's collect_value() function. Note: The @value will be initialised with the exact type of @instance. If you wish to set the @value's type to a different GType (such as a parent class GType), you need to manually call g_value_init() and g_value_set_instance(). - + An uninitialized #GValue structure. + filename="gobject/gvalue.c" + line="307">An uninitialized #GValue structure. the instance + filename="gobject/gvalue.c" + line="308">the instance Returns the value contents as pointer. This function asserts that + filename="gobject/gvalue.c" + line="223">Returns the value contents as pointer. This function asserts that g_value_fits_pointer() returned %TRUE for the passed in value. This is an internal function introduced mainly for C marshallers. - + the value contents as pointer + filename="gobject/gvalue.c" + line="231">the value contents as pointer An initialized #GValue structure + filename="gobject/gvalue.c" + line="225">An initialized #GValue structure Clears the current value in @value and resets it to the default value + filename="gobject/gvalue.c" + line="142">Clears the current value in @value and resets it to the default value (as if the value had just been initialized). - + the #GValue structure that has been passed in + filename="gobject/gvalue.c" + line="149">the #GValue structure that has been passed in An initialized #GValue structure. + filename="gobject/gvalue.c" + line="144">An initialized #GValue structure. Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. - + filename="gobject/gvaluetypes.c" + line="733">Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + a valid #GValue of type %G_TYPE_BOOLEAN + filename="gobject/gvaluetypes.c" + line="735">a valid #GValue of type %G_TYPE_BOOLEAN boolean value to be set + filename="gobject/gvaluetypes.c" + line="736">boolean value to be set Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. - + filename="gobject/gboxed.c" + line="472">Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + a valid #GValue of %G_TYPE_BOXED derived type + filename="gobject/gboxed.c" + line="474">a valid #GValue of %G_TYPE_BOXED derived type nullable="1" allow-none="1"> boxed value to be set + filename="gobject/gboxed.c" + line="475">boxed value to be set @@ -18094,18 +20054,18 @@ This is an internal function introduced mainly for C marshallers. deprecated="1" deprecated-version="2.4"> This is an internal function introduced mainly for C marshallers. + filename="gobject/gboxed.c" + line="509">This is an internal function introduced mainly for C marshallers. Use g_value_take_boxed() instead. - + a valid #GValue of %G_TYPE_BOXED derived type + filename="gobject/gboxed.c" + line="511">a valid #GValue of %G_TYPE_BOXED derived type nullable="1" allow-none="1"> duplicated unowned boxed value to be set + filename="gobject/gboxed.c" + line="512">duplicated unowned boxed value to be set @@ -18124,157 +20084,157 @@ This is an internal function introduced mainly for C marshallers. deprecated="1" deprecated-version="2.32"> Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + filename="gobject/gvaluetypes.c" + line="629">Set the contents of a %G_TYPE_CHAR #GValue to @v_char. This function's input type is broken, see g_value_set_schar() - + a valid #GValue of type %G_TYPE_CHAR + filename="gobject/gvaluetypes.c" + line="631">a valid #GValue of type %G_TYPE_CHAR character value to be set + filename="gobject/gvaluetypes.c" + line="632">character value to be set Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. - + filename="gobject/gvaluetypes.c" + line="989">Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. + a valid #GValue of type %G_TYPE_DOUBLE + filename="gobject/gvaluetypes.c" + line="991">a valid #GValue of type %G_TYPE_DOUBLE double value to be set + filename="gobject/gvaluetypes.c" + line="992">double value to be set Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. - + filename="gobject/genums.c" + line="664">Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. + a valid #GValue whose type is derived from %G_TYPE_ENUM + filename="gobject/genums.c" + line="666">a valid #GValue whose type is derived from %G_TYPE_ENUM enum value to be set + filename="gobject/genums.c" + line="667">enum value to be set Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. - + filename="gobject/genums.c" + line="696">Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. + a valid #GValue whose type is derived from %G_TYPE_FLAGS + filename="gobject/genums.c" + line="698">a valid #GValue whose type is derived from %G_TYPE_FLAGS flags value to be set + filename="gobject/genums.c" + line="699">flags value to be set Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. - + filename="gobject/gvaluetypes.c" + line="957">Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. + a valid #GValue of type %G_TYPE_FLOAT + filename="gobject/gvaluetypes.c" + line="959">a valid #GValue of type %G_TYPE_FLOAT float value to be set + filename="gobject/gvaluetypes.c" + line="960">float value to be set Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. - + filename="gobject/gvaluetypes.c" + line="1232">Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + a valid #GValue of type %G_TYPE_GTYPE + filename="gobject/gvaluetypes.c" + line="1234">a valid #GValue of type %G_TYPE_GTYPE #GType to be set + filename="gobject/gvaluetypes.c" + line="1235">#GType to be set Sets @value from an instantiatable type via the + filename="gobject/gvalue.c" + line="252">Sets @value from an instantiatable type via the value_table's collect_value() function. - + An initialized #GValue structure. + filename="gobject/gvalue.c" + line="254">An initialized #GValue structure. nullable="1" allow-none="1"> the instance + filename="gobject/gvalue.c" + line="255">the instance Set the contents of a %G_TYPE_INT #GValue to @v_int. - + filename="gobject/gvaluetypes.c" + line="765">Set the contents of a %G_TYPE_INT #GValue to @v_int. + a valid #GValue of type %G_TYPE_INT + filename="gobject/gvaluetypes.c" + line="767">a valid #GValue of type %G_TYPE_INT integer value to be set + filename="gobject/gvaluetypes.c" + line="768">integer value to be set Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. - + filename="gobject/gvaluetypes.c" + line="910">Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. + a valid #GValue of type %G_TYPE_INT64 + filename="gobject/gvaluetypes.c" + line="912">a valid #GValue of type %G_TYPE_INT64 64bit integer value to be set + filename="gobject/gvaluetypes.c" + line="913">64bit integer value to be set @@ -18338,19 +20298,19 @@ value_table's collect_value() function. c:identifier="g_value_set_interned_string" version="2.66"> Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is + filename="gobject/gvaluetypes.c" + line="1070">Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is assumed to be static and interned (canonical, for example from g_intern_string()), and is thus not duplicated when setting the #GValue. - + a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1072">a valid #GValue of type %G_TYPE_STRING nullable="1" allow-none="1"> static string to be set + filename="gobject/gvaluetypes.c" + line="1073">static string to be set Set the contents of a %G_TYPE_LONG #GValue to @v_long. - + filename="gobject/gvaluetypes.c" + line="829">Set the contents of a %G_TYPE_LONG #GValue to @v_long. + a valid #GValue of type %G_TYPE_LONG + filename="gobject/gvaluetypes.c" + line="831">a valid #GValue of type %G_TYPE_LONG long integer value to be set + filename="gobject/gvaluetypes.c" + line="832">long integer value to be set Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. + filename="gobject/gobject.c" + line="5024">Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. g_value_set_object() increases the reference count of @v_object (the #GValue holds a reference to @v_object). If you do not wish @@ -18401,15 +20361,15 @@ need it), use g_value_take_object() instead. It is important that your #GValue holds a reference to @v_object (either its own, or one it has taken) to ensure that the object won't be destroyed while the #GValue still exists). - + a valid #GValue of %G_TYPE_OBJECT derived type + filename="gobject/gobject.c" + line="5026">a valid #GValue of %G_TYPE_OBJECT derived type nullable="1" allow-none="1"> object value to be set + filename="gobject/gobject.c" + line="5027">object value to be set @@ -18429,18 +20389,18 @@ the #GValue still exists). deprecated="1" deprecated-version="2.4"> This is an internal function introduced mainly for C marshallers. + filename="gobject/gobject.c" + line="5065">This is an internal function introduced mainly for C marshallers. Use g_value_take_object() instead. - + a valid #GValue of %G_TYPE_OBJECT derived type + filename="gobject/gobject.c" + line="5067">a valid #GValue of %G_TYPE_OBJECT derived type nullable="1" allow-none="1"> object value to be set + filename="gobject/gobject.c" + line="5068">object value to be set Set the contents of a %G_TYPE_PARAM #GValue to @param. - + filename="gobject/gparam.c" + line="1525">Set the contents of a %G_TYPE_PARAM #GValue to @param. + a valid #GValue of type %G_TYPE_PARAM + filename="gobject/gparam.c" + line="1527">a valid #GValue of type %G_TYPE_PARAM nullable="1" allow-none="1"> the #GParamSpec to be set + filename="gobject/gparam.c" + line="1528">the #GParamSpec to be set @@ -18486,18 +20446,18 @@ the #GValue still exists). deprecated="1" deprecated-version="2.4"> This is an internal function introduced mainly for C marshallers. + filename="gobject/gparam.c" + line="1547">This is an internal function introduced mainly for C marshallers. Use g_value_take_param() instead. - + a valid #GValue of type %G_TYPE_PARAM + filename="gobject/gparam.c" + line="1549">a valid #GValue of type %G_TYPE_PARAM nullable="1" allow-none="1"> the #GParamSpec to be set + filename="gobject/gparam.c" + line="1550">the #GParamSpec to be set Set the contents of a pointer #GValue to @v_pointer. - + filename="gobject/gvaluetypes.c" + line="1198">Set the contents of a pointer #GValue to @v_pointer. + a valid #GValue of %G_TYPE_POINTER + filename="gobject/gvaluetypes.c" + line="1200">a valid #GValue of %G_TYPE_POINTER nullable="1" allow-none="1"> pointer value to be set + filename="gobject/gvaluetypes.c" + line="1201">pointer value to be set Set the contents of a %G_TYPE_CHAR #GValue to @v_char. - + filename="gobject/gvaluetypes.c" + line="666">Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + a valid #GValue of type %G_TYPE_CHAR + filename="gobject/gvaluetypes.c" + line="668">a valid #GValue of type %G_TYPE_CHAR signed 8 bit integer to be set + filename="gobject/gvaluetypes.c" + line="669">signed 8 bit integer to be set Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + filename="gobject/gboxed.c" + line="489">Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. The boxed value is assumed to be static, and is thus not duplicated when setting the #GValue. - + a valid #GValue of %G_TYPE_BOXED derived type + filename="gobject/gboxed.c" + line="491">a valid #GValue of %G_TYPE_BOXED derived type nullable="1" allow-none="1"> static boxed value to be set + filename="gobject/gboxed.c" + line="492">static boxed value to be set @@ -18592,22 +20552,22 @@ when setting the #GValue. Set the contents of a %G_TYPE_STRING #GValue to @v_string. + filename="gobject/gvaluetypes.c" + line="1046">Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is assumed to be static, and is thus not duplicated when setting the #GValue. If the the string is a canonical string, using g_value_set_interned_string() is more appropriate. - + a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1048">a valid #GValue of type %G_TYPE_STRING nullable="1" allow-none="1"> static string to be set + filename="gobject/gvaluetypes.c" + line="1049">static string to be set Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string. - + filename="gobject/gvaluetypes.c" + line="1021">Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string. + a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1023">a valid #GValue of type %G_TYPE_STRING nullable="1" allow-none="1"> caller-owned string to be duplicated for the #GValue + filename="gobject/gvaluetypes.c" + line="1024">caller-owned string to be duplicated for the #GValue @@ -18652,18 +20612,18 @@ is more appropriate. deprecated="1" deprecated-version="2.4"> This is an internal function introduced mainly for C marshallers. + filename="gobject/gvaluetypes.c" + line="1093">This is an internal function introduced mainly for C marshallers. Use g_value_take_string() instead. - + a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1095">a valid #GValue of type %G_TYPE_STRING nullable="1" allow-none="1"> duplicated unowned string to be set + filename="gobject/gvaluetypes.c" + line="1096">duplicated unowned string to be set Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. - + filename="gobject/gvaluetypes.c" + line="701">Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. + a valid #GValue of type %G_TYPE_UCHAR + filename="gobject/gvaluetypes.c" + line="703">a valid #GValue of type %G_TYPE_UCHAR unsigned character value to be set + filename="gobject/gvaluetypes.c" + line="704">unsigned character value to be set Set the contents of a %G_TYPE_UINT #GValue to @v_uint. - + filename="gobject/gvaluetypes.c" + line="797">Set the contents of a %G_TYPE_UINT #GValue to @v_uint. + a valid #GValue of type %G_TYPE_UINT + filename="gobject/gvaluetypes.c" + line="799">a valid #GValue of type %G_TYPE_UINT unsigned integer value to be set + filename="gobject/gvaluetypes.c" + line="800">unsigned integer value to be set Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. - + filename="gobject/gvaluetypes.c" + line="925">Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. + a valid #GValue of type %G_TYPE_UINT64 + filename="gobject/gvaluetypes.c" + line="927">a valid #GValue of type %G_TYPE_UINT64 unsigned 64bit integer value to be set + filename="gobject/gvaluetypes.c" + line="928">unsigned 64bit integer value to be set Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. - + filename="gobject/gvaluetypes.c" + line="861">Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. + a valid #GValue of type %G_TYPE_ULONG + filename="gobject/gvaluetypes.c" + line="863">a valid #GValue of type %G_TYPE_ULONG unsigned long integer value to be set + filename="gobject/gvaluetypes.c" + line="864">unsigned long integer value to be set @@ -18773,18 +20733,18 @@ is more appropriate. c:identifier="g_value_set_variant" version="2.26"> Set the contents of a variant #GValue to @variant. + filename="gobject/gvaluetypes.c" + line="1269">Set the contents of a variant #GValue to @variant. If the variant is floating, it is consumed. - + a valid #GValue of type %G_TYPE_VARIANT + filename="gobject/gvaluetypes.c" + line="1271">a valid #GValue of type %G_TYPE_VARIANT nullable="1" allow-none="1"> a #GVariant, or %NULL + filename="gobject/gvaluetypes.c" + line="1272">a #GVariant, or %NULL + + Steal ownership on contents of a %G_TYPE_STRING #GValue. +As a result of this operation the value's contents will be reset to %NULL. + +The purpose of this call is to provide a way to avoid an extra copy +when some object have been serialized into string through #GValue API. + +NOTE: for safety and compatibility purposes, if #GValue contains +static string, or an interned one, this function will return a copy +of the string. Otherwise the transfer notation would be ambiguous. + + + string content of @value; + Should be freed with g_free() when no longer needed. + + + + + a valid #GValue of type %G_TYPE_STRING + + + + Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed + filename="gobject/gboxed.c" + line="525">Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and takes over the ownership of the caller’s reference to @v_boxed; the caller doesn’t have to unref it any more. - + a valid #GValue of %G_TYPE_BOXED derived type + filename="gobject/gboxed.c" + line="527">a valid #GValue of %G_TYPE_BOXED derived type nullable="1" allow-none="1"> duplicated unowned boxed value to be set + filename="gobject/gboxed.c" + line="528">duplicated unowned boxed value to be set @@ -18833,23 +20824,23 @@ the caller doesn’t have to unref it any more. version="2.4" introspectable="0"> Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object + filename="gobject/gobject.c" + line="5081">Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object and takes over the ownership of the caller’s reference to @v_object; the caller doesn’t have to unref it any more (i.e. the reference count of the object is not increased). If you want the #GValue to hold its own reference to @v_object, use g_value_set_object() instead. - + a valid #GValue of %G_TYPE_OBJECT derived type + filename="gobject/gobject.c" + line="5083">a valid #GValue of %G_TYPE_OBJECT derived type nullable="1" allow-none="1"> object value to be set + filename="gobject/gobject.c" + line="5084">object value to be set @@ -18868,19 +20859,19 @@ g_value_set_object() instead. version="2.4" introspectable="0"> Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes + filename="gobject/gparam.c" + line="1563">Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes over the ownership of the caller’s reference to @param; the caller doesn’t have to unref it any more. - + a valid #GValue of type %G_TYPE_PARAM + filename="gobject/gparam.c" + line="1565">a valid #GValue of type %G_TYPE_PARAM nullable="1" allow-none="1"> the #GParamSpec to be set + filename="gobject/gparam.c" + line="1566">the #GParamSpec to be set @@ -18898,17 +20889,17 @@ doesn’t have to unref it any more. c:identifier="g_value_take_string" version="2.4"> Sets the contents of a %G_TYPE_STRING #GValue to @v_string. - + filename="gobject/gvaluetypes.c" + line="1109">Sets the contents of a %G_TYPE_STRING #GValue to @v_string. + a valid #GValue of type %G_TYPE_STRING + filename="gobject/gvaluetypes.c" + line="1111">a valid #GValue of type %G_TYPE_STRING nullable="1" allow-none="1"> string to take ownership of + filename="gobject/gvaluetypes.c" + line="1112">string to take ownership of @@ -18926,8 +20917,8 @@ doesn’t have to unref it any more. c:identifier="g_value_take_variant" version="2.26"> Set the contents of a variant #GValue to @variant, and takes over + filename="gobject/gvaluetypes.c" + line="1298">Set the contents of a variant #GValue to @variant, and takes over the ownership of the caller's reference to @variant; the caller doesn't have to unref it any more (i.e. the reference count of the variant is not increased). @@ -18939,15 +20930,15 @@ If you want the #GValue to hold its own reference to @variant, use g_value_set_variant() instead. This is an internal function introduced mainly for C marshallers. - + a valid #GValue of type %G_TYPE_VARIANT + filename="gobject/gvaluetypes.c" + line="1300">a valid #GValue of type %G_TYPE_VARIANT nullable="1" allow-none="1"> a #GVariant, or %NULL + filename="gobject/gvaluetypes.c" + line="1301">a #GVariant, or %NULL Tries to cast the contents of @src_value into a type appropriate + filename="gobject/gvalue.c" + line="513">Tries to cast the contents of @src_value into a type appropriate to store in @dest_value, e.g. to transform a %G_TYPE_INT value into a %G_TYPE_FLOAT value. Performing transformations between value types might incur precision lossage. Especially transformations into strings might reveal seemingly arbitrary results and shouldn't be relied upon for production code (such as rcfile value or object property serialization). - + Whether a transformation rule was found and could be applied. + filename="gobject/gvalue.c" + line="526">Whether a transformation rule was found and could be applied. Upon failing transformations, @dest_value is left untouched. Source value. + filename="gobject/gvalue.c" + line="515">Source value. Target value. + filename="gobject/gvalue.c" + line="516">Target value. Clears the current value in @value (if any) and "unsets" the type, + filename="gobject/gvalue.c" + line="174">Clears the current value in @value (if any) and "unsets" the type, this releases all resources associated with this GValue. An unset value is the same as an uninitialized (zero-filled) #GValue structure. - + An initialized #GValue structure. + filename="gobject/gvalue.c" + line="176">An initialized #GValue structure. @@ -19018,31 +21009,31 @@ structure. c:identifier="g_value_register_transform_func" introspectable="0"> Registers a value transformation function for use in g_value_transform(). + filename="gobject/gvalue.c" + line="426">Registers a value transformation function for use in g_value_transform(). A previously registered transformation function for @src_type and @dest_type will be replaced. - + Source type. + filename="gobject/gvalue.c" + line="428">Source type. Target type. + filename="gobject/gvalue.c" + line="429">Target type. a function which transforms values of type @src_type + filename="gobject/gvalue.c" + line="430">a function which transforms values of type @src_type into value of type @dest_type @@ -19050,27 +21041,27 @@ will be replaced. Returns whether a #GValue of type @src_type can be copied into + filename="gobject/gvalue.c" + line="488">Returns whether a #GValue of type @src_type can be copied into a #GValue of type @dest_type. - + %TRUE if g_value_copy() is possible with @src_type and @dest_type. + filename="gobject/gvalue.c" + line="496">%TRUE if g_value_copy() is possible with @src_type and @dest_type. source type to be copied. + filename="gobject/gvalue.c" + line="490">source type to be copied. destination type for copying. + filename="gobject/gvalue.c" + line="491">destination type for copying. @@ -19078,29 +21069,29 @@ a #GValue of type @dest_type. Check whether g_value_transform() is able to transform values + filename="gobject/gvalue.c" + line="465">Check whether g_value_transform() is able to transform values of type @src_type into values of type @dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered. - + %TRUE if the transformation is possible, %FALSE otherwise. + filename="gobject/gvalue.c" + line="475">%TRUE if the transformation is possible, %FALSE otherwise. Source type. + filename="gobject/gvalue.c" + line="467">Source type. Target type. + filename="gobject/gvalue.c" + line="468">Target type. @@ -19108,23 +21099,49 @@ transformation function must be registered. A #GValueArray contains an array of #GValue elements. - + filename="gobject/gvaluearray.c" + line="32">A `GValueArray` is a container structure to hold an array of generic values. + +The prime purpose of a `GValueArray` is for it to be used as an +object property that holds an array of values. A `GValueArray` wraps +an array of `GValue` elements in order for it to be used as a boxed +type through `G_TYPE_VALUE_ARRAY`. + +`GValueArray` is deprecated in favour of `GArray` since GLib 2.32. +It is possible to create a `GArray` that behaves like a `GValueArray` +by using the size of `GValue` as the element size, and by setting +[method@GObject.Value.unset] as the clear function using +[func@GLib.Array.set_clear_func], for instance, the following code: + +```c + GValueArray *array = g_value_array_new (10); +``` + +can be replaced by: + +```c + GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); + g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); +``` + Use `GArray` instead, if possible for the given use case, + as described above. + number of values contained in the array + filename="gobject/gvaluearray.c" + line="34">number of values contained in the array array of values + filename="gobject/gvaluearray.c" + line="35">array of values @@ -19135,23 +21152,23 @@ transformation function must be registered. deprecated="1" deprecated-version="2.32"> Allocate and initialize a new #GValueArray, optionally preserve space + filename="gobject/gvaluearray.c" + line="111">Allocate and initialize a new #GValueArray, optionally preserve space for @n_prealloced elements. New arrays always contain 0 elements, regardless of the value of @n_prealloced. Use #GArray and g_array_sized_new() instead. - + a newly allocated #GValueArray with 0 values + filename="gobject/gvaluearray.c" + line="119">a newly allocated #GValueArray with 0 values number of values to preallocate space for + filename="gobject/gvaluearray.c" + line="113">number of values to preallocate space for @@ -19161,22 +21178,22 @@ regardless of the value of @n_prealloced. deprecated="1" deprecated-version="2.32"> Insert a copy of @value as last element of @value_array. If @value is + filename="gobject/gvaluearray.c" + line="222">Insert a copy of @value as last element of @value_array. If @value is %NULL, an uninitialized value is appended. Use #GArray and g_array_append_val() instead. - + the #GValueArray passed in as @value_array + filename="gobject/gvaluearray.c" + line="230">the #GValueArray passed in as @value_array #GValueArray to add an element to + filename="gobject/gvaluearray.c" + line="224">#GValueArray to add an element to nullable="1" allow-none="1"> #GValue to copy into #GValueArray, or %NULL + filename="gobject/gvaluearray.c" + line="225">#GValue to copy into #GValueArray, or %NULL @@ -19195,22 +21212,22 @@ regardless of the value of @n_prealloced. deprecated="1" deprecated-version="2.32"> Construct an exact copy of a #GValueArray by duplicating all its + filename="gobject/gvaluearray.c" + line="163">Construct an exact copy of a #GValueArray by duplicating all its contents. Use #GArray and g_array_ref() instead. - + Newly allocated copy of #GValueArray + filename="gobject/gvaluearray.c" + line="170">Newly allocated copy of #GValueArray #GValueArray to copy + filename="gobject/gvaluearray.c" + line="165">#GValueArray to copy @@ -19221,18 +21238,18 @@ contents. deprecated="1" deprecated-version="2.32"> Free a #GValueArray including its contents. + filename="gobject/gvaluearray.c" + line="137">Free a #GValueArray including its contents. Use #GArray and g_array_unref() instead. - + #GValueArray to free + filename="gobject/gvaluearray.c" + line="139">#GValueArray to free @@ -19242,27 +21259,27 @@ contents. deprecated="1" deprecated-version="2.32"> Return a pointer to the value at @index_ containd in @value_array. + filename="gobject/gvaluearray.c" + line="69">Return a pointer to the value at @index_ contained in @value_array. Use g_array_index() instead. - + pointer to a value at @index_ in @value_array + filename="gobject/gvaluearray.c" + line="76">pointer to a value at @index_ in @value_array #GValueArray to get a value from + filename="gobject/gvaluearray.c" + line="71">#GValueArray to get a value from index of the value of interest + filename="gobject/gvaluearray.c" + line="72">index of the value of interest @@ -19272,28 +21289,28 @@ contents. deprecated="1" deprecated-version="2.32"> Insert a copy of @value at specified position into @value_array. If @value + filename="gobject/gvaluearray.c" + line="245">Insert a copy of @value at specified position into @value_array. If @value is %NULL, an uninitialized value is inserted. Use #GArray and g_array_insert_val() instead. - + the #GValueArray passed in as @value_array + filename="gobject/gvaluearray.c" + line="254">the #GValueArray passed in as @value_array #GValueArray to add an element to + filename="gobject/gvaluearray.c" + line="247">#GValueArray to add an element to insertion position, must be <= value_array->;n_values + filename="gobject/gvaluearray.c" + line="248">insertion position, must be <= value_array->;n_values nullable="1" allow-none="1"> #GValue to copy into #GValueArray, or %NULL + filename="gobject/gvaluearray.c" + line="249">#GValue to copy into #GValueArray, or %NULL @@ -19312,22 +21329,22 @@ is %NULL, an uninitialized value is inserted. deprecated="1" deprecated-version="2.32"> Insert a copy of @value as first element of @value_array. If @value is + filename="gobject/gvaluearray.c" + line="198">Insert a copy of @value as first element of @value_array. If @value is %NULL, an uninitialized value is prepended. Use #GArray and g_array_prepend_val() instead. - + the #GValueArray passed in as @value_array + filename="gobject/gvaluearray.c" + line="207">the #GValueArray passed in as @value_array #GValueArray to add an element to + filename="gobject/gvaluearray.c" + line="200">#GValueArray to add an element to nullable="1" allow-none="1"> #GValue to copy into #GValueArray, or %NULL + filename="gobject/gvaluearray.c" + line="201">#GValue to copy into #GValueArray, or %NULL @@ -19346,27 +21363,27 @@ is %NULL, an uninitialized value is inserted. deprecated="1" deprecated-version="2.32"> Remove the value at position @index_ from @value_array. + filename="gobject/gvaluearray.c" + line="282">Remove the value at position @index_ from @value_array. Use #GArray and g_array_remove_index() instead. - + the #GValueArray passed in as @value_array + filename="gobject/gvaluearray.c" + line="290">the #GValueArray passed in as @value_array #GValueArray to remove an element from + filename="gobject/gvaluearray.c" + line="284">#GValueArray to remove an element from position of value to remove, which must be less than + filename="gobject/gvaluearray.c" + line="285">position of value to remove, which must be less than @value_array->n_values @@ -19378,33 +21395,33 @@ is %NULL, an uninitialized value is inserted. deprecated="1" deprecated-version="2.32"> Sort @value_array using @compare_func to compare the elements according to + filename="gobject/gvaluearray.c" + line="313">Sort @value_array using @compare_func to compare the elements according to the semantics of #GCompareFunc. The current implementation uses the same sorting algorithm as standard C qsort() function. Use #GArray and g_array_sort(). - + the #GValueArray passed in as @value_array + filename="gobject/gvaluearray.c" + line="324">the #GValueArray passed in as @value_array #GValueArray to sort + filename="gobject/gvaluearray.c" + line="315">#GValueArray to sort function to compare elements + filename="gobject/gvaluearray.c" + line="316">function to compare elements @@ -19415,25 +21432,25 @@ C qsort() function. deprecated="1" deprecated-version="2.32"> Sort @value_array using @compare_func to compare the elements according + filename="gobject/gvaluearray.c" + line="342">Sort @value_array using @compare_func to compare the elements according to the semantics of #GCompareDataFunc. The current implementation uses the same sorting algorithm as standard C qsort() function. Use #GArray and g_array_sort_with_data(). - + the #GValueArray passed in as @value_array + filename="gobject/gvaluearray.c" + line="354">the #GValueArray passed in as @value_array #GValueArray to sort + filename="gobject/gvaluearray.c" + line="344">#GValueArray to sort scope="call" closure="1"> function to compare elements + filename="gobject/gvaluearray.c" + line="345">function to compare elements nullable="1" allow-none="1"> extra data argument provided for @compare_func + filename="gobject/gvaluearray.c" + line="346">extra data argument provided for @compare_func @@ -19459,33 +21476,48 @@ C qsort() function. The type of value transformation functions which can be registered with g_value_register_transform_func(). @dest_value will be initialized to the correct destination type. - + Source value. Target value. + + + + + + A #GWeakNotify function can be added to an object as a callback that gets triggered when the object is finalized. @@ -19497,7 +21529,7 @@ In particular, this means it’s invalid to call g_object_ref(), g_weak_ref_init(), g_weak_ref_set(), g_object_add_toggle_ref(), g_object_weak_ref(), g_object_add_weak_pointer() or any function which calls them on the object from this callback. - + @@ -19507,13 +21539,13 @@ them on the object from this callback. nullable="1" allow-none="1"> data that was provided when the weak reference was established the object being disposed @@ -19521,8 +21553,8 @@ them on the object from this callback. A structure containing a weak reference to a #GObject. + filename="gobject/gobject.c" + line="5422">A structure containing a weak reference to a #GObject. A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an object for as long as at least one "strong" reference to that object @@ -19546,9 +21578,9 @@ goes back to zero, at which point they too will be invalidated. It is invalid to take a #GWeakRef on an object during #GObjectClass.dispose without first having or creating a strong reference to the object. - + - + @@ -19558,24 +21590,21 @@ without first having or creating a strong reference to the object. version="2.32" introspectable="0"> Frees resources associated with a non-statically-allocated #GWeakRef. + filename="gobject/gobject.c" + line="5683">Frees resources associated with a non-statically-allocated #GWeakRef. After this call, the #GWeakRef is left in an undefined state. You should only call this on a #GWeakRef that previously had g_weak_ref_init() called on it. - + - + location of a weak reference, which + filename="gobject/gobject.c" + line="5685">location of a weak reference, which may be empty @@ -19586,8 +21615,8 @@ g_weak_ref_init() called on it. version="2.32" introspectable="0"> If @weak_ref is not empty, atomically acquire a strong + filename="gobject/gobject.c" + line="5705">If @weak_ref is not empty, atomically acquire a strong reference to the object it points to, and return that reference. This function is needed because of the potential race between taking @@ -19596,22 +21625,19 @@ its last reference at the same time in a different thread. The caller should release the resulting reference in the usual way, by using g_object_unref(). - + the object pointed to + filename="gobject/gobject.c" + line="5719">the object pointed to by @weak_ref, or %NULL if it was empty - + location of a weak reference to a #GObject + filename="gobject/gobject.c" + line="5707">location of a weak reference to a #GObject @@ -19621,8 +21647,8 @@ by using g_object_unref(). version="2.32" introspectable="0"> Initialise a non-statically-allocated #GWeakRef. + filename="gobject/gobject.c" + line="5649">Initialise a non-statically-allocated #GWeakRef. This function also calls g_weak_ref_set() with @object on the freshly-initialised weak reference. @@ -19631,19 +21657,15 @@ This function should always be matched with a call to g_weak_ref_clear(). It is not necessary to use this function for a #GWeakRef in static storage because it will already be properly initialised. Just use g_weak_ref_set() directly. - + - + uninitialized or empty location for a weak - reference + filename="gobject/gobject.c" + line="5651">uninitialized or empty location for a weak reference nullable="1" allow-none="1"> a #GObject or %NULL + filename="gobject/gobject.c" + line="5652">a #GObject or %NULL @@ -19662,21 +21684,21 @@ properly initialised. Just use g_weak_ref_set() directly. version="2.32" introspectable="0"> Change the object to which @weak_ref points, or set it to + filename="gobject/gobject.c" + line="5814">Change the object to which @weak_ref points, or set it to %NULL. You must own a strong reference on @object while calling this function. - + location for a weak reference + filename="gobject/gobject.c" + line="5816">location for a weak reference nullable="1" allow-none="1"> a #GObject or %NULL + filename="gobject/gobject.c" + line="5817">a #GObject or %NULL @@ -19725,8 +21747,8 @@ function. version="2.62" introspectable="0"> Assert that @object is non-%NULL, then release one reference to it with + filename="gobject/gobject.h" + line="784">Assert that @object is non-%NULL, then release one reference to it with g_object_unref() and assert that it has been finalized (i.e. that there are no more references). @@ -19734,71 +21756,70 @@ If assertions are disabled via `G_DISABLE_ASSERT`, this macro just calls g_object_unref() without any further checks. This macro should only be used in regression tests. - + an object + filename="gobject/gobject.h" + line="786">an object Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. - + filename="gobject/gboxed.c" + line="317">Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. + The newly created copy of the boxed + filename="gobject/gboxed.c" + line="324">The newly created copy of the boxed structure. The type of @src_boxed. + filename="gobject/gboxed.c" + line="319">The type of @src_boxed. The boxed structure to be copied. + filename="gobject/gboxed.c" + line="320">The boxed structure to be copied. Free the boxed structure @boxed which is of type @boxed_type. - + filename="gobject/gboxed.c" + line="378">Free the boxed structure @boxed which is of type @boxed_type. + The type of @boxed. + filename="gobject/gboxed.c" + line="380">The type of @boxed. The boxed structure to be freed. + filename="gobject/gboxed.c" + line="381">The boxed structure to be freed. + c:identifier="g_boxed_type_register_static"> This function creates a new %G_TYPE_BOXED derived type id for a new + filename="gobject/gboxed.c" + line="256">This function creates a new %G_TYPE_BOXED derived type id for a new boxed type with name @name. Boxed type handling functions have to be provided to copy and free @@ -19807,30 +21828,30 @@ opaque boxed structures of this type. For the general case, it is recommended to use G_DEFINE_BOXED_TYPE() instead of calling g_boxed_type_register_static() directly. The macro will create the appropriate `*_get_type()` function for the boxed type. - + New %G_TYPE_BOXED derived type id for @name. + filename="gobject/gboxed.c" + line="272">New %G_TYPE_BOXED derived type id for @name. Name of the new boxed type. + filename="gobject/gboxed.c" + line="258">Name of the new boxed type. - + Boxed structure copy function. + filename="gobject/gboxed.c" + line="259">Boxed structure copy function. - + Boxed structure free function. + filename="gobject/gboxed.c" + line="260">Boxed structure free function. @@ -19839,39 +21860,39 @@ will create the appropriate `*_get_type()` function for the boxed type. c:identifier="g_cclosure_marshal_BOOLEAN__BOXED_BOXED" moved-to="CClosure.marshal_BOOLEAN__BOXED_BOXED"> A #GClosureMarshal function for use with signals with handlers that + filename="gobject/gmarshal.c" + line="2390">A #GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). - + A #GClosure. + filename="gobject/gmarshal.c" + line="2392">A #GClosure. A #GValue to store the return value. May be %NULL + filename="gobject/gmarshal.c" + line="2393">A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. + filename="gobject/gmarshal.c" + line="2395">The length of the @param_values array. An array of #GValues holding the arguments + filename="gobject/gmarshal.c" + line="2396">An array of #GValues holding the arguments on which to invoke the callback of closure. @@ -19880,8 +21901,8 @@ accumulator, such as g_signal_accumulator_true_handled(). nullable="1" allow-none="1"> The invocation hint given as the last argument to + filename="gobject/gmarshal.c" + line="2398">The invocation hint given as the last argument to g_closure_invoke(). @@ -19890,8 +21911,8 @@ accumulator, such as g_signal_accumulator_true_handled(). nullable="1" allow-none="1"> Additional data specified when registering the + filename="gobject/gmarshal.c" + line="2400">Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() @@ -19902,37 +21923,40 @@ accumulator, such as g_signal_accumulator_true_handled(). c:identifier="g_cclosure_marshal_BOOLEAN__FLAGS" moved-to="CClosure.marshal_BOOLEAN__FLAGS"> A marshaller for a #GCClosure with a callback of type -`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter -denotes a flags type. - + filename="gobject/gmarshal.c" + line="2143">A #GClosureMarshal function for use with signals with handlers that +take a flags type as an argument and return a boolean. If you have +such a signal, you will probably also need to use an accumulator, +such as g_signal_accumulator_true_handled(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2145">A #GClosure. a #GValue which can store the returned #gboolean + filename="gobject/gmarshal.c" + line="2146">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="2148">The length of the @param_values array. a #GValue array holding instance and arg1 + filename="gobject/gmarshal.c" + line="2149">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="2151">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="2153">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -19960,36 +21986,39 @@ denotes a flags type. c:identifier="g_cclosure_marshal_STRING__OBJECT_POINTER" moved-to="CClosure.marshal_STRING__OBJECT_POINTER"> A marshaller for a #GCClosure with a callback of type -`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="2262">A #GClosureMarshal function for use with signals with handlers that +take a #GObject and a pointer and produce a string. It is highly +unlikely that your signal handler fits this description. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2264">A #GClosure. a #GValue, which can store the returned string + filename="gobject/gmarshal.c" + line="2265">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 3 + filename="gobject/gmarshal.c" + line="2267">The length of the @param_values array. a #GValue array holding instance, arg1 and arg2 + filename="gobject/gmarshal.c" + line="2268">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="2270">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="2272">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20017,36 +22048,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__BOOLEAN" moved-to="CClosure.marshal_VOID__BOOLEAN"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="169">A #GClosureMarshal function for use with signals with a single +boolean argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="171">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="172">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="174">The length of the @param_values array. a #GValue array holding the instance and the #gboolean parameter + filename="gobject/gmarshal.c" + line="175">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="177">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="179">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20074,36 +22109,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__BOXED" moved-to="CClosure.marshal_VOID__BOXED"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1581">A #GClosureMarshal function for use with signals with a single +argument which is any boxed pointer type. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1583">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1584">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1586">The length of the @param_values array. a #GValue array holding the instance and the #GBoxed* parameter + filename="gobject/gmarshal.c" + line="1587">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1589">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1591">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20131,36 +22170,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__CHAR" moved-to="CClosure.marshal_VOID__CHAR"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="277">A #GClosureMarshal function for use with signals with a single +character argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="279">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="280">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="282">The length of the @param_values array. a #GValue array holding the instance and the #gchar parameter + filename="gobject/gmarshal.c" + line="283">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="285">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="287">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20188,36 +22231,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__DOUBLE" moved-to="CClosure.marshal_VOID__DOUBLE"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1249">A #GClosureMarshal function for use with signals with one +double-precision floating point argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1251">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1252">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1254">The length of the @param_values array. a #GValue array holding the instance and the #gdouble parameter + filename="gobject/gmarshal.c" + line="1255">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1257">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1259">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20245,36 +22292,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__ENUM" moved-to="CClosure.marshal_VOID__ENUM"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. - + filename="gobject/gmarshal.c" + line="925">A #GClosureMarshal function for use with signals with a single +argument with an enumerated type. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="927">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="928">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="930">The length of the @param_values array. a #GValue array holding the instance and the enumeration parameter + filename="gobject/gmarshal.c" + line="931">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="933">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="935">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20302,36 +22353,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__FLAGS" moved-to="CClosure.marshal_VOID__FLAGS"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. - + filename="gobject/gmarshal.c" + line="1033">A #GClosureMarshal function for use with signals with a single +argument with a flags types. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1035">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1036">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1038">The length of the @param_values array. a #GValue array holding the instance and the flags parameter + filename="gobject/gmarshal.c" + line="1039">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1041">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1043">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20359,36 +22414,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__FLOAT" moved-to="CClosure.marshal_VOID__FLOAT"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1141">A #GClosureMarshal function for use with signals with one +single-precision floating point argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1143">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1144">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1146">The length of the @param_values array. a #GValue array holding the instance and the #gfloat parameter + filename="gobject/gmarshal.c" + line="1147">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1149">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1151">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20416,36 +22475,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__INT" moved-to="CClosure.marshal_VOID__INT"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="493">A #GClosureMarshal function for use with signals with a single +integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="495">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="496">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="498">The length of the @param_values array. a #GValue array holding the instance and the #gint parameter + filename="gobject/gmarshal.c" + line="499">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="501">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="503">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20473,36 +22536,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__LONG" moved-to="CClosure.marshal_VOID__LONG"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="709">A #GClosureMarshal function for use with signals with with a single +long integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="711">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="712">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="714">The length of the @param_values array. a #GValue array holding the instance and the #glong parameter + filename="gobject/gmarshal.c" + line="715">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="717">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="719">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20530,36 +22597,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__OBJECT" moved-to="CClosure.marshal_VOID__OBJECT"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1805">A #GClosureMarshal function for use with signals with a single +#GObject argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1807">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1808">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1810">The length of the @param_values array. a #GValue array holding the instance and the #GObject* parameter + filename="gobject/gmarshal.c" + line="1811">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1813">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1815">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20587,36 +22658,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__PARAM" moved-to="CClosure.marshal_VOID__PARAM"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1469">A #GClosureMarshal function for use with signals with a single +argument of type #GParamSpec. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1471">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1472">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1474">The length of the @param_values array. a #GValue array holding the instance and the #GParamSpec* parameter + filename="gobject/gmarshal.c" + line="1475">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1477">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1479">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20644,36 +22719,42 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__POINTER" moved-to="CClosure.marshal_VOID__POINTER"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1693">A #GClosureMarshal function for use with signals with a single raw +pointer argument type. + +If it is possible, it is better to use one of the more specific +functions such as g_cclosure_marshal_VOID__OBJECT() or +g_cclosure_marshal_VOID__OBJECT(). + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1695">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1696">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1698">The length of the @param_values array. a #GValue array holding the instance and the #gpointer parameter + filename="gobject/gmarshal.c" + line="1699">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1701">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1703">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20701,36 +22784,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__STRING" moved-to="CClosure.marshal_VOID__STRING"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1357">A #GClosureMarshal function for use with signals with a single string +argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1359">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1360">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1362">The length of the @param_values array. a #GValue array holding the instance and the #gchar* parameter + filename="gobject/gmarshal.c" + line="1363">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1365">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1367">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20758,36 +22845,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__UCHAR" moved-to="CClosure.marshal_VOID__UCHAR"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="385">A #GClosureMarshal function for use with signals with a single +unsigned character argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="387">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="388">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="390">The length of the @param_values array. a #GValue array holding the instance and the #guchar parameter + filename="gobject/gmarshal.c" + line="391">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="393">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="395">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20815,36 +22906,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__UINT" moved-to="CClosure.marshal_VOID__UINT"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="601">A #GClosureMarshal function for use with signals with with a single +unsigned integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="603">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="604">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="606">The length of the @param_values array. a #GValue array holding the instance and the #guint parameter + filename="gobject/gmarshal.c" + line="607">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="609">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="611">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20872,36 +22967,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__UINT_POINTER" moved-to="CClosure.marshal_VOID__UINT_POINTER"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="2029">A #GClosureMarshal function for use with signals with an unsigned int +and a pointer as arguments. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="2031">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="2032">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 3 + filename="gobject/gmarshal.c" + line="2034">The length of the @param_values array. a #GValue array holding instance, arg1 and arg2 + filename="gobject/gmarshal.c" + line="2035">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="2037">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="2039">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -20929,36 +23028,38 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__ULONG" moved-to="CClosure.marshal_VOID__ULONG"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="817">A #GClosureMarshal function for use with signals with a single +unsigned long integer argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="819">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="820">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="822">The length of the @param_values array. a #GValue array holding the instance and the #gulong parameter + filename="gobject/gmarshal.c" + line="823">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="825">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="827">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + moved-to="CClosure.marshal_VOID__VARIANT"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="1917">A #GClosureMarshal function for use with signals with a single +#GVariant argument. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="1919">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="1920">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 2 + filename="gobject/gmarshal.c" + line="1922">The length of the @param_values array. a #GValue array holding the instance and the #GVariant* parameter + filename="gobject/gmarshal.c" + line="1923">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="1925">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="1927">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -21044,36 +23150,37 @@ denotes a flags type. c:identifier="g_cclosure_marshal_VOID__VOID" moved-to="CClosure.marshal_VOID__VOID"> A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer user_data)`. - + filename="gobject/gmarshal.c" + line="72">A #GClosureMarshal function for use with signals with no arguments. + the #GClosure to which the marshaller belongs + filename="gobject/gmarshal.c" + line="74">A #GClosure. ignored + filename="gobject/gmarshal.c" + line="75">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. 1 + filename="gobject/gmarshal.c" + line="77">The length of the @param_values array. a #GValue array holding only the instance + filename="gobject/gmarshal.c" + line="78">An array of #GValues holding the arguments + on which to invoke the callback of closure. nullable="1" allow-none="1"> the invocation hint given as the last argument - to g_closure_invoke() + filename="gobject/gmarshal.c" + line="80">The invocation hint given as the last argument to + g_closure_invoke(). nullable="1" allow-none="1"> additional data specified when registering the marshaller + filename="gobject/gmarshal.c" + line="82">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -21102,40 +23211,40 @@ denotes a flags type. moved-to="CClosure.marshal_generic" version="2.30"> A generic marshaller function implemented via + filename="gobject/gclosure.c" + line="1444">A generic marshaller function implemented via [libffi](http://sourceware.org/libffi/). Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a %NULL marshaller. - + A #GClosure. + filename="gobject/gclosure.c" + line="1446">A #GClosure. A #GValue to store the return value. May be %NULL + filename="gobject/gclosure.c" + line="1447">A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. + filename="gobject/gclosure.c" + line="1449">The length of the @param_values array. An array of #GValues holding the arguments + filename="gobject/gclosure.c" + line="1450">An array of #GValues holding the arguments on which to invoke the callback of closure. @@ -21144,8 +23253,8 @@ but used automatically by GLib when specifying a %NULL marshaller. nullable="1" allow-none="1"> The invocation hint given as the last argument to + filename="gobject/gclosure.c" + line="1452">The invocation hint given as the last argument to g_closure_invoke(). @@ -21154,8 +23263,8 @@ but used automatically by GLib when specifying a %NULL marshaller. nullable="1" allow-none="1"> Additional data specified when registering the + filename="gobject/gclosure.c" + line="1454">Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() @@ -21167,43 +23276,38 @@ but used automatically by GLib when specifying a %NULL marshaller. moved-to="CClosure.new" introspectable="0"> Creates a new closure which invokes @callback_func with @user_data as + filename="gobject/gclosure.c" + line="957">Creates a new closure which invokes @callback_func with @user_data as the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - - + + a floating reference to a new #GCClosure + filename="gobject/gclosure.c" + line="968">a floating reference to a new #GCClosure - + the function to invoke + filename="gobject/gclosure.c" + line="959">the function to invoke + allow-none="1"> user data to pass to @callback_func + filename="gobject/gclosure.c" + line="960">user data to pass to @callback_func destroy notify to be called when @user_data is no longer used + filename="gobject/gclosure.c" + line="961">destroy notify to be called when @user_data is no longer used @@ -21213,30 +23317,30 @@ the last parameter. moved-to="CClosure.new_object" introspectable="0"> A variant of g_cclosure_new() which uses @object as @user_data and + filename="gobject/gobject.c" + line="5330">A variant of g_cclosure_new() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - - + + a new #GCClosure + filename="gobject/gobject.c" + line="5341">a new #GCClosure the function to invoke + filename="gobject/gobject.c" + line="5332">the function to invoke a #GObject pointer to pass to @callback_func + filename="gobject/gobject.c" + line="5333">a #GObject pointer to pass to @callback_func @@ -21246,30 +23350,30 @@ after the object is is freed. moved-to="CClosure.new_object_swap" introspectable="0"> A variant of g_cclosure_new_swap() which uses @object as @user_data + filename="gobject/gobject.c" + line="5359">A variant of g_cclosure_new_swap() which uses @object as @user_data and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - - + + a new #GCClosure + filename="gobject/gobject.c" + line="5370">a new #GCClosure the function to invoke + filename="gobject/gobject.c" + line="5361">the function to invoke a #GObject pointer to pass to @callback_func + filename="gobject/gobject.c" + line="5362">a #GObject pointer to pass to @callback_func @@ -21279,43 +23383,38 @@ after the object is is freed. moved-to="CClosure.new_swap" introspectable="0"> Creates a new closure which invokes @callback_func with @user_data as + filename="gobject/gclosure.c" + line="987">Creates a new closure which invokes @callback_func with @user_data as the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - - + + a floating reference to a new #GCClosure + filename="gobject/gclosure.c" + line="998">a floating reference to a new #GCClosure - + the function to invoke + filename="gobject/gclosure.c" + line="989">the function to invoke + allow-none="1"> user data to pass to @callback_func + filename="gobject/gclosure.c" + line="990">user data to pass to @callback_func destroy notify to be called when @user_data is no longer used + filename="gobject/gclosure.c" + line="991">destroy notify to be called when @user_data is no longer used @@ -21325,8 +23424,8 @@ the first parameter. version="2.28" introspectable="0"> Clears a reference to a #GObject. + filename="gobject/gobject.c" + line="4513">Clears a reference to a #GObject. @object_ptr must not be %NULL. @@ -21336,15 +23435,15 @@ pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. - + a pointer to a #GObject reference + filename="gobject/gobject.c" + line="4515">a pointer to a #GObject reference @@ -21353,8 +23452,8 @@ pointer casts. c:identifier="g_clear_signal_handler" version="2.62"> Disconnects a handler from @instance so it will not be called during + filename="gobject/gsignal.c" + line="4173">Disconnects a handler from @instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The @handler_id_ptr is then set to zero, which is never a valid handler ID value (see g_signal_connect()). @@ -21362,21 +23461,21 @@ If the handler ID is 0 then this function does nothing. There is also a macro version of this function so that the code will be inlined. - + A pointer to a handler ID (of type #gulong) of the handler to be disconnected. + filename="gobject/gsignal.c" + line="4175">A pointer to a handler ID (of type #gulong) of the handler to be disconnected. The instance to remove the signal handler from. + filename="gobject/gsignal.c" + line="4176">The instance to remove the signal handler from. This pointer may be %NULL or invalid, if the handler ID is zero. @@ -21387,8 +23486,8 @@ will be inlined. version="2.56" introspectable="0"> Clears a weak reference to a #GObject. + filename="gobject/gobject.h" + line="816">Clears a weak reference to a #GObject. @weak_pointer_location must not be %NULL. @@ -21399,20 +23498,20 @@ and the pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. - + The memory address of a pointer + filename="gobject/gobject.h" + line="818">The memory address of a pointer This function is meant to be called from the `complete_type_info` + filename="gobject/genums.c" + line="231">This function is meant to be called from the `complete_type_info` function of a #GTypePlugin implementation, as in the following example: @@ -21432,15 +23531,15 @@ my_enum_complete_type_info (GTypePlugin *plugin, g_enum_complete_type_info (type, info, values); } ]| - + the type identifier of the type being completed + filename="gobject/genums.c" + line="233">the type identifier of the type being completed the #GTypeInfo struct to be filled in + filename="gobject/genums.c" + line="234">the #GTypeInfo struct to be filled in An array of #GEnumValue structs for the possible + filename="gobject/genums.c" + line="235">An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. @@ -21464,27 +23563,27 @@ my_enum_complete_type_info (GTypePlugin *plugin, Returns the #GEnumValue for a value. - + filename="gobject/genums.c" + line="472">Returns the #GEnumValue for a value. + the #GEnumValue for @value, or %NULL + filename="gobject/genums.c" + line="479">the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration a #GEnumClass + filename="gobject/genums.c" + line="474">a #GEnumClass the value to look up + filename="gobject/genums.c" + line="475">the value to look up @@ -21492,13 +23591,13 @@ my_enum_complete_type_info (GTypePlugin *plugin, Looks up a #GEnumValue by name. - + filename="gobject/genums.c" + line="354">Looks up a #GEnumValue by name. + the #GEnumValue with name @name, + filename="gobject/genums.c" + line="361">the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name @@ -21506,14 +23605,14 @@ my_enum_complete_type_info (GTypePlugin *plugin, a #GEnumClass + filename="gobject/genums.c" + line="356">a #GEnumClass the name to look up + filename="gobject/genums.c" + line="357">the name to look up @@ -21521,13 +23620,13 @@ my_enum_complete_type_info (GTypePlugin *plugin, Looks up a #GEnumValue by nickname. - + filename="gobject/genums.c" + line="413">Looks up a #GEnumValue by nickname. + the #GEnumValue with nickname @nick, + filename="gobject/genums.c" + line="420">the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname @@ -21535,14 +23634,14 @@ my_enum_complete_type_info (GTypePlugin *plugin, a #GEnumClass + filename="gobject/genums.c" + line="415">a #GEnumClass the nickname to look up + filename="gobject/genums.c" + line="416">the nickname to look up @@ -21550,34 +23649,36 @@ my_enum_complete_type_info (GTypePlugin *plugin, Registers a new static enumeration type with the name @name. + filename="gobject/genums.c" + line="143">Registers a new static enumeration type with the name @name. It is normally more convenient to let [glib-mkenums][glib-mkenums], generate a my_enum_get_type() function from a usual C enumeration definition than to write one yourself using g_enum_register_static(). - + The new type identifier. + filename="gobject/genums.c" + line="157">The new type identifier. A nul-terminated string used as the name of the new type. + filename="gobject/genums.c" + line="145">A nul-terminated string used as the name of the new type. An array of #GEnumValue structs for the possible - enumeration values. The array is terminated by a struct with all - members being 0. GObject keeps a reference to the data, so it cannot - be stack-allocated. - + filename="gobject/genums.c" + line="146">An array of + #GEnumValue structs for the possible enumeration values. The array is + terminated by a struct with all members being 0. GObject keeps a + reference to the data, so it cannot be stack-allocated. + + + @@ -21585,80 +23686,49 @@ definition than to write one yourself using g_enum_register_static(). c:identifier="g_enum_to_string" version="2.54"> Pretty-prints @value in the form of the enum’s name. + filename="gobject/genums.c" + line="537">Pretty-prints @value in the form of the enum’s name. This is intended to be used for debugging purposes. The format of the output may change in the future. - + a newly-allocated text string + filename="gobject/genums.c" + line="547">a newly-allocated text string the type identifier of a #GEnumClass type + filename="gobject/genums.c" + line="539">the type identifier of a #GEnumClass type the value + filename="gobject/genums.c" + line="540">the value - - The GLib type system provides fundamental types for enumeration and -flags types. (Flags types are like enumerations, but allow their -values to be combined by bitwise or). A registered enumeration or -flags type associates a name and a nickname with each allowed -value, and the methods g_enum_get_value_by_name(), -g_enum_get_value_by_nick(), g_flags_get_value_by_name() and -g_flags_get_value_by_nick() can look up values by their name or -nickname. When an enumeration or flags type is registered with the -GLib type system, it can be used as value type for object -properties, using g_param_spec_enum() or g_param_spec_flags(). - -GObject ships with a utility called [glib-mkenums][glib-mkenums], -that can construct suitable type registration functions from C enumeration -definitions. - -Example of how to get a string representation of an enum value: -|[<!-- language="C" --> -GEnumClass *enum_class; -GEnumValue *enum_value; - -enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); -enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); - -g_print ("Name: %s\n", enum_value->value_name); - -g_type_class_unref (enum_class); -]| - This function is meant to be called from the complete_type_info() + filename="gobject/genums.c" + line="277">This function is meant to be called from the complete_type_info() function of a #GTypePlugin implementation, see the example for g_enum_complete_type_info() above. - + the type identifier of the type being completed + filename="gobject/genums.c" + line="279">the type identifier of the type being completed caller-allocates="0" transfer-ownership="full"> the #GTypeInfo struct to be filled in + filename="gobject/genums.c" + line="280">the #GTypeInfo struct to be filled in An array of #GFlagsValue structs for the possible + filename="gobject/genums.c" + line="281">An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. @@ -21683,27 +23753,27 @@ g_enum_complete_type_info() above. Returns the first #GFlagsValue which is set in @value. - + filename="gobject/genums.c" + line="500">Returns the first #GFlagsValue which is set in @value. + the first #GFlagsValue which is set in + filename="gobject/genums.c" + line="507">the first #GFlagsValue which is set in @value, or %NULL if none is set a #GFlagsClass + filename="gobject/genums.c" + line="502">a #GFlagsClass the value + filename="gobject/genums.c" + line="503">the value @@ -21711,27 +23781,27 @@ g_enum_complete_type_info() above. Looks up a #GFlagsValue by name. - + filename="gobject/genums.c" + line="384">Looks up a #GFlagsValue by name. + the #GFlagsValue with name @name, + filename="gobject/genums.c" + line="391">the #GFlagsValue with name @name, or %NULL if there is no flag with that name a #GFlagsClass + filename="gobject/genums.c" + line="386">a #GFlagsClass the name to look up + filename="gobject/genums.c" + line="387">the name to look up @@ -21739,27 +23809,27 @@ g_enum_complete_type_info() above. Looks up a #GFlagsValue by nickname. - + filename="gobject/genums.c" + line="443">Looks up a #GFlagsValue by nickname. + the #GFlagsValue with nickname @nick, + filename="gobject/genums.c" + line="450">the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname a #GFlagsClass + filename="gobject/genums.c" + line="445">a #GFlagsClass the nickname to look up + filename="gobject/genums.c" + line="446">the nickname to look up @@ -21767,33 +23837,36 @@ g_enum_complete_type_info() above. Registers a new static flags type with the name @name. + filename="gobject/genums.c" + line="187">Registers a new static flags type with the name @name. It is normally more convenient to let [glib-mkenums][glib-mkenums] generate a my_flags_get_type() function from a usual C enumeration definition than to write one yourself using g_flags_register_static(). - + The new type identifier. + filename="gobject/genums.c" + line="201">The new type identifier. A nul-terminated string used as the name of the new type. + filename="gobject/genums.c" + line="189">A nul-terminated string used as the name of the new type. An array of #GFlagsValue structs for the possible - flags values. The array is terminated by a struct with all members being 0. - GObject keeps a reference to the data, so it cannot be stack-allocated. - + filename="gobject/genums.c" + line="190">An array of + #GFlagsValue structs for the possible flags values. The array is + terminated by a struct with all members being 0. GObject keeps a + reference to the data, so it cannot be stack-allocated. + + + @@ -21801,341 +23874,62 @@ definition than to write one yourself using g_flags_register_static(). c:identifier="g_flags_to_string" version="2.54"> Pretty-prints @value in the form of the flag names separated by ` | ` and + filename="gobject/genums.c" + line="627">Pretty-prints @value in the form of the flag names separated by ` | ` and sorted. Any extra bits will be shown at the end as a hexadecimal number. This is intended to be used for debugging purposes. The format of the output may change in the future. - + a newly-allocated text string + filename="gobject/genums.c" + line="638">a newly-allocated text string the type identifier of a #GFlagsClass type + filename="gobject/genums.c" + line="629">the type identifier of a #GFlagsClass type the value + filename="gobject/genums.c" + line="630">the value - - #GBoxed is a generic wrapper mechanism for arbitrary C structures. - -The only thing the type system needs to know about the structures is how to -copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc); -beyond that, they are treated as opaque chunks of memory. - -Boxed types are useful for simple value-holder structures like rectangles or -points. They can also be used for wrapping structures defined in non-#GObject -based libraries. They allow arbitrary structures to be handled in a uniform -way, allowing uniform copying (or referencing) and freeing (or unreferencing) -of them, and uniform representation of the type of the contained structure. -In turn, this allows any type which can be boxed to be set as the data in a -#GValue, which allows for polymorphic handling of a much wider range of data -types, and hence usage of such types as #GObject property values. - -#GBoxed is designed so that reference counted types can be boxed. Use the -type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the -#GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is -g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref(). - - - The #GValue structure is basically a variable container that consists -of a type identifier and a specific value of that type. - -The type identifier within a #GValue structure always determines the -type of the associated value. - -To create an undefined #GValue structure, simply create a zero-filled -#GValue structure. To initialize the #GValue, use the g_value_init() -function. A #GValue cannot be used until it is initialized. Before -destruction you must always use g_value_unset() to make sure allocated -memory is freed. - -The basic type operations (such as freeing and copying) are determined -by the #GTypeValueTable associated with the type ID stored in the #GValue. -Other #GValue operations (such as converting values between types) are -provided by this interface. - -The code in the example program below demonstrates #GValue's -features. - -|[<!-- language="C" --> -#include <glib-object.h> - -static void -int2string (const GValue *src_value, - GValue *dest_value) -{ - if (g_value_get_int (src_value) == 42) - g_value_set_static_string (dest_value, "An important number"); - else - g_value_set_static_string (dest_value, "What's that?"); -} - -int -main (int argc, - char *argv[]) -{ - // GValues must be initialized - GValue a = G_VALUE_INIT; - GValue b = G_VALUE_INIT; - const gchar *message; - - // The GValue starts empty - g_assert (!G_VALUE_HOLDS_STRING (&a)); - - // Put a string in it - g_value_init (&a, G_TYPE_STRING); - g_assert (G_VALUE_HOLDS_STRING (&a)); - g_value_set_static_string (&a, "Hello, world!"); - g_printf ("%s\n", g_value_get_string (&a)); - - // Reset it to its pristine state - g_value_unset (&a); - - // It can then be reused for another type - g_value_init (&a, G_TYPE_INT); - g_value_set_int (&a, 42); - - // Attempt to transform it into a GValue of type STRING - g_value_init (&b, G_TYPE_STRING); - - // An INT is transformable to a STRING - g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); - - g_value_transform (&a, &b); - g_printf ("%s\n", g_value_get_string (&b)); - - // Attempt to transform it again using a custom transform function - g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - g_value_transform (&a, &b); - g_printf ("%s\n", g_value_get_string (&b)); - return 0; -} -]| - -See also [gobject-Standard-Parameter-and-Value-Types] for more information on -validation of #GValue. - -For letting a #GValue own (and memory manage) arbitrary types or pointers, -they need to become a [boxed type][gboxed]. The example below shows how -the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed]. - -|[<!-- language="C" --> -typedef struct { ... } MyStruct; -G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) - -// These two lines normally go in a public header. By GObject convention, -// the naming scheme is NAMESPACE_TYPE_NAME: -#define MY_TYPE_STRUCT (my_struct_get_type ()) -GType my_struct_get_type (void); - -void -foo () -{ - GValue *value = g_new0 (GValue, 1); - g_value_init (value, MY_TYPE_STRUCT); - g_value_set_boxed (value, mystruct); - // [... your code ....] - g_value_unset (value); - g_free (value); -} -]| - - - The GType API is the foundation of the GObject system. It provides the -facilities for registering and managing all fundamental data types, -user-defined object and interface types. - -For type creation and registration purposes, all types fall into one of -two categories: static or dynamic. Static types are never loaded or -unloaded at run-time as dynamic types may be. Static types are created -with g_type_register_static() that gets type specific information passed -in via a #GTypeInfo structure. - -Dynamic types are created with g_type_register_dynamic() which takes a -#GTypePlugin structure instead. The remaining type information (the -#GTypeInfo structure) is retrieved during runtime through #GTypePlugin -and the g_type_plugin_*() API. - -These registration functions are usually called only once from a -function whose only purpose is to return the type identifier for a -specific class. Once the type (or class or interface) is registered, -it may be instantiated, inherited, or implemented depending on exactly -what sort of type it is. - -There is also a third registration function for registering fundamental -types called g_type_register_fundamental() which requires both a #GTypeInfo -structure and a #GTypeFundamentalInfo structure but it is seldom used -since most fundamental types are predefined rather than user-defined. - -Type instance and class structs are limited to a total of 64 KiB, -including all parent types. Similarly, type instances' private data -(as created by G_ADD_PRIVATE()) are limited to a total of -64 KiB. If a type instance needs a large static buffer, allocate it -separately (typically by using #GArray or #GPtrArray) and put a pointer -to the buffer in the structure. - -As mentioned in the [GType conventions][gtype-conventions], type names must -be at least three characters long. There is no upper length limit. The first -character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent -characters can be letters, numbers or any of ‘-_+’. - -# Runtime Debugging - -When `G_ENABLE_DEBUG` is defined during compilation, the GObject library -supports an environment variable `GOBJECT_DEBUG` that can be set to a -combination of flags to trigger debugging messages about -object bookkeeping and signal emissions during runtime. - -The currently supported flags are: - - `objects`: Tracks all #GObject instances in a global hash table called - `debug_objects_ht`, and prints the still-alive objects on exit. - - `instance-count`: Tracks the number of instances of every #GType and makes - it available via the g_type_get_instance_count() function. - - `signals`: Currently unused. - - + - - GObject is the fundamental type providing the common attributes and -methods for all object types in GTK, Pango and other libraries -based on GObject. The GObject class provides methods for object -construction and destruction, property access methods, and signal -support. Signals are described in detail [here][gobject-Signals]. - -For a tutorial on implementing a new GObject class, see [How to define and -implement a new GObject][howto-gobject]. For a list of naming conventions for -GObjects and their methods, see the [GType conventions][gtype-conventions]. -For the high-level concepts behind GObject, read [Instantiatable classed types: -Objects][gtype-instantiatable-classed]. - -## Floating references # {#floating-ref} - -**Note**: Floating references are a C convenience API and should not be -used in modern GObject code. Language bindings in particular find the -concept highly problematic, as floating references are not identifiable -through annotations, and neither are deviations from the floating reference -behavior, like types that inherit from #GInitiallyUnowned and still return -a full reference from g_object_new(). - -GInitiallyUnowned is derived from GObject. The only difference between -the two is that the initial reference of a GInitiallyUnowned is flagged -as a "floating" reference. This means that it is not specifically -claimed to be "owned" by any code portion. The main motivation for -providing floating references is C convenience. In particular, it -allows code to be written as: - -|[<!-- language="C" --> -container = create_container (); -container_add_child (container, create_child()); -]| - -If container_add_child() calls g_object_ref_sink() on the passed-in child, -no reference of the newly created child is leaked. Without floating -references, container_add_child() can only g_object_ref() the new child, -so to implement this code without reference leaks, it would have to be -written as: - -|[<!-- language="C" --> -Child *child; -container = create_container (); -child = create_child (); -container_add_child (container, child); -g_object_unref (child); -]| - -The floating reference can be converted into an ordinary reference by -calling g_object_ref_sink(). For already sunken objects (objects that -don't have a floating reference anymore), g_object_ref_sink() is equivalent -to g_object_ref() and returns a new reference. - -Since floating references are useful almost exclusively for C convenience, -language bindings that provide automated reference and memory ownership -maintenance (such as smart pointers or garbage collection) should not -expose floating references in their API. The best practice for handling -types that have initially floating references is to immediately sink those -references after g_object_new() returns, by checking if the #GType -inherits from #GInitiallyUnowned. For instance: - -|[<!-- language="C" --> -GObject *res = g_object_new_with_properties (gtype, - n_props, - prop_names, - prop_values); - -// or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) -if (G_IS_INITIALLY_UNOWNED (res)) - g_object_ref_sink (res); - -return res; -]| - -Some object implementations may need to save an objects floating state -across certain code portions (an example is #GtkMenu), to achieve this, -the following sequence can be used: - -|[<!-- language="C" --> -// save floating state -gboolean was_floating = g_object_is_floating (object); -g_object_ref_sink (object); -// protected code portion - -... - -// restore floating state -if (was_floating) - g_object_force_floating (object); -else - g_object_unref (object); // release previously acquired reference -]| - Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN + filename="gobject/gparamspecs.c" + line="1912">Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN property. In many cases, it may be more appropriate to use an enum with g_param_spec_enum(), both to improve code clarity by using explicitly named values, and to allow for more values to be added in future without breaking API. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="1928">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="1914">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="1915">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="1916">description of the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="1917">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="1918">flags for the property specified Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED + filename="gobject/gparamspecs.c" + line="2489">Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED derived property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2502">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2491">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2492">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2493">description of the property specified %G_TYPE_BOXED derived type of this property + filename="gobject/gparamspecs.c" + line="2494">%G_TYPE_BOXED derived type of this property flags for the property specified + filename="gobject/gparamspecs.c" + line="2495">flags for the property specified Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. - + filename="gobject/gparamspecs.c" + line="1832">Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="1844">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="1834">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="1835">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="1836">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="1837">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="1838">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="1839">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="1840">flags for the property specified Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE + filename="gobject/gparamspecs.c" + line="2376">Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2391">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2378">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2379">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2380">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="2381">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2382">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2383">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2384">flags for the property specified Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM + filename="gobject/gparamspecs.c" + line="2242">Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2256">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2244">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2245">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2246">description of the property specified a #GType derived from %G_TYPE_ENUM + filename="gobject/gparamspecs.c" + line="2247">a #GType derived from %G_TYPE_ENUM default value for the property specified + filename="gobject/gparamspecs.c" + line="2248">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2249">flags for the property specified Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS + filename="gobject/gparamspecs.c" + line="2288">Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2302">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2290">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2291">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2292">description of the property specified a #GType derived from %G_TYPE_FLAGS + filename="gobject/gparamspecs.c" + line="2293">a #GType derived from %G_TYPE_FLAGS default value for the property specified + filename="gobject/gparamspecs.c" + line="2294">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2295">flags for the property specified Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + filename="gobject/gparamspecs.c" + line="2334">Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2348">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2336">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2337">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2338">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="2339">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2340">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2341">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2342">flags for the property specified @@ -22536,23 +24330,23 @@ See g_param_spec_internal() for details on property names. c:identifier="g_param_spec_gtype" version="2.10"> Creates a new #GParamSpecGType instance specifying a + filename="gobject/gparamspecs.c" + line="2559">Creates a new #GParamSpecGType instance specifying a %G_TYPE_GTYPE property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2575">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2561">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2562">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2563">description of the property specified a #GType whose subtypes are allowed as values + filename="gobject/gparamspecs.c" + line="2564">a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) flags for the property specified + filename="gobject/gparamspecs.c" + line="2566">flags for the property specified Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + filename="gobject/gparamspecs.c" + line="1952">Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="1966">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="1954">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="1955">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="1956">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="1957">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="1958">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="1959">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="1960">flags for the property specified Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + filename="gobject/gparamspecs.c" + line="2121">Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2135">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2123">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2124">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2125">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="2126">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2127">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2128">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2129">flags for the property specified Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + filename="gobject/gparamspecs.c" + line="2036">Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2050">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2038">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2039">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2040">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="2041">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2042">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2043">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2044">flags for the property specified Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT + filename="gobject/gparamspecs.c" + line="2641">Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT derived property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2654">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2643">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2644">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2645">description of the property specified %G_TYPE_OBJECT derived type of this property + filename="gobject/gparamspecs.c" + line="2646">%G_TYPE_OBJECT derived type of this property flags for the property specified + filename="gobject/gparamspecs.c" + line="2647">flags for the property specified @@ -22838,51 +24632,51 @@ See g_param_spec_internal() for details on property names. version="2.4" introspectable="0"> Creates a new property of type #GParamSpecOverride. This is used + filename="gobject/gparamspecs.c" + line="2678">Creates a new property of type #GParamSpecOverride. This is used to direct operations to another paramspec, and will not be directly useful unless you are implementing a new base type similar to GObject. - + the newly created #GParamSpec + filename="gobject/gparamspecs.c" + line="2689">the newly created #GParamSpec the name of the property. + filename="gobject/gparamspecs.c" + line="2680">the name of the property. The property that is being overridden + filename="gobject/gparamspecs.c" + line="2681">The property that is being overridden Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM + filename="gobject/gparamspecs.c" + line="2452">Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2465">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2454">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2455">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2456">description of the property specified a #GType derived from %G_TYPE_PARAM + filename="gobject/gparamspecs.c" + line="2457">a #GType derived from %G_TYPE_PARAM flags for the property specified + filename="gobject/gparamspecs.c" + line="2458">flags for the property specified Creates a new #GParamSpecPointer instance specifying a pointer property. + filename="gobject/gparamspecs.c" + line="2527">Creates a new #GParamSpecPointer instance specifying a pointer property. Where possible, it is better to use g_param_spec_object() or g_param_spec_boxed() to expose memory management information. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2540">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2529">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2530">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2531">description of the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2532">flags for the property specified Creates a new #GParamSpecString instance. + filename="gobject/gparamspecs.c" + line="2419">Creates a new #GParamSpecString instance. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2431">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2421">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2422">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2423">description of the property specified nullable="1" allow-none="1"> default value for the property specified + filename="gobject/gparamspecs.c" + line="2424">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2425">flags for the property specified Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. - + filename="gobject/gparamspecs.c" + line="1872">Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="1884">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="1874">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="1875">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="1876">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="1877">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="1878">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="1879">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="1880">flags for the property specified Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + filename="gobject/gparamspecs.c" + line="1994">Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2008">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="1996">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="1997">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="1998">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="1999">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2000">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2001">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2002">flags for the property specified Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 + filename="gobject/gparamspecs.c" + line="2163">Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2178">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2165">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2166">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2167">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="2168">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2169">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2170">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2171">flags for the property specified Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG + filename="gobject/gparamspecs.c" + line="2078">Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2093">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2080">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2081">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2082">description of the property specified minimum value for the property specified + filename="gobject/gparamspecs.c" + line="2083">minimum value for the property specified maximum value for the property specified + filename="gobject/gparamspecs.c" + line="2084">maximum value for the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2085">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2086">flags for the property specified Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT + filename="gobject/gparamspecs.c" + line="2206">Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT property. #GValue structures for this property can be accessed with g_value_set_uint() and g_value_get_uint(). See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2220">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2208">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2209">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2210">description of the property specified default value for the property specified + filename="gobject/gparamspecs.c" + line="2211">default value for the property specified flags for the property specified + filename="gobject/gparamspecs.c" + line="2212">flags for the property specified @@ -23334,25 +25128,25 @@ See g_param_spec_internal() for details on property names. c:identifier="g_param_spec_value_array" introspectable="0"> Creates a new #GParamSpecValueArray instance specifying a + filename="gobject/gparamspecs.c" + line="2597">Creates a new #GParamSpecValueArray instance specifying a %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED type, as such, #GValue structures for this property can be accessed with g_value_set_boxed() and g_value_get_boxed(). See g_param_spec_internal() for details on property names. - + a newly created parameter specification + filename="gobject/gparamspecs.c" + line="2613">a newly created parameter specification canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2599">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2600">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2601">description of the property specified a #GParamSpec describing the elements contained in + filename="gobject/gparamspecs.c" + line="2602">a #GParamSpec describing the elements contained in arrays of this property, may be %NULL flags for the property specified + filename="gobject/gparamspecs.c" + line="2604">flags for the property specified @@ -23392,25 +25186,25 @@ See g_param_spec_internal() for details on property names. c:identifier="g_param_spec_variant" version="2.26"> Creates a new #GParamSpecVariant instance specifying a #GVariant + filename="gobject/gparamspecs.c" + line="2721">Creates a new #GParamSpecVariant instance specifying a #GVariant property. If @default_value is floating, it is consumed. See g_param_spec_internal() for details on property names. - + the newly created #GParamSpec + filename="gobject/gparamspecs.c" + line="2738">the newly created #GParamSpec canonical name of the property specified + filename="gobject/gparamspecs.c" + line="2723">canonical name of the property specified nullable="1" allow-none="1"> nick name for the property specified + filename="gobject/gparamspecs.c" + line="2724">nick name for the property specified nullable="1" allow-none="1"> description of the property specified + filename="gobject/gparamspecs.c" + line="2725">description of the property specified a #GVariantType + filename="gobject/gparamspecs.c" + line="2726">a #GVariantType nullable="1" allow-none="1"> a #GVariant of type @type to + filename="gobject/gparamspecs.c" + line="2727">a #GVariant of type @type to use as the default value, or %NULL flags for the property specified + filename="gobject/gparamspecs.c" + line="2729">flags for the property specified @@ -23458,76 +25252,76 @@ See g_param_spec_internal() for details on property names. Registers @name as the name of a new static type derived + filename="gobject/gparam.c" + line="1470">Registers @name as the name of a new static type derived from %G_TYPE_PARAM. The type system uses the information contained in the #GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec type and its instances. - + The new type identifier. + filename="gobject/gparam.c" + line="1482">The new type identifier. 0-terminated string used as the name of the new #GParamSpec type. + filename="gobject/gparam.c" + line="1472">0-terminated string used as the name of the new #GParamSpec type. The #GParamSpecTypeInfo for this #GParamSpec type. + filename="gobject/gparam.c" + line="1473">The #GParamSpecTypeInfo for this #GParamSpec type. Transforms @src_value into @dest_value if possible, and then + filename="gobject/gparam.c" + line="754">Transforms @src_value into @dest_value if possible, and then validates @dest_value, in order for it to conform to @pspec. If @strict_validation is %TRUE this function will only succeed if the transformed @dest_value complied to @pspec without modifications. See also g_value_type_transformable(), g_value_transform() and g_param_value_validate(). - + %TRUE if transformation and validation were successful, + filename="gobject/gparam.c" + line="770">%TRUE if transformation and validation were successful, %FALSE otherwise and @dest_value is left untouched. a valid #GParamSpec + filename="gobject/gparam.c" + line="756">a valid #GParamSpec source #GValue + filename="gobject/gparam.c" + line="757">source #GValue destination #GValue of correct type for @pspec + filename="gobject/gparam.c" + line="758">destination #GValue of correct type for @pspec %TRUE requires @dest_value to conform to @pspec + filename="gobject/gparam.c" + line="759">%TRUE requires @dest_value to conform to @pspec without modifications @@ -23536,26 +25330,26 @@ without modifications Checks whether @value contains the default value as specified in @pspec. - + filename="gobject/gparam.c" + line="647">Checks whether @value contains the default value as specified in @pspec. + whether @value contains the canonical default for this @pspec + filename="gobject/gparam.c" + line="654">whether @value contains the canonical default for this @pspec a valid #GParamSpec + filename="gobject/gparam.c" + line="649">a valid #GParamSpec a #GValue of correct type for @pspec + filename="gobject/gparam.c" + line="650">a #GValue of correct type for @pspec @@ -23564,28 +25358,28 @@ without modifications c:identifier="g_param_value_is_valid" version="2.74"> Return whether the contents of @value comply with the specifications + filename="gobject/gparam.c" + line="709">Return whether the contents of @value comply with the specifications set out by @pspec. - + whether the contents of @value comply with the specifications + filename="gobject/gparam.c" + line="717">whether the contents of @value comply with the specifications set out by @pspec. a valid #GParamSpec + filename="gobject/gparam.c" + line="711">a valid #GParamSpec a #GValue of correct type for @pspec + filename="gobject/gparam.c" + line="712">a #GValue of correct type for @pspec @@ -23593,107 +25387,90 @@ set out by @pspec. Sets @value to its default value as specified in @pspec. - + filename="gobject/gparam.c" + line="619">Sets @value to its default value as specified in @pspec. + a valid #GParamSpec + filename="gobject/gparam.c" + line="621">a valid #GParamSpec a #GValue of correct type for @pspec; since 2.64, you + filename="gobject/gparam.c" + line="622">a #GValue of correct type for @pspec; since 2.64, you can also pass an empty #GValue, initialized with %G_VALUE_INIT - - #GValue provides an abstract container structure which can be -copied, transformed and compared while holding a value of any -(derived) type, which is registered as a #GType with a -#GTypeValueTable in its #GTypeInfo structure. Parameter -specifications for most value types can be created as #GParamSpec -derived instances, to implement e.g. #GObject properties which -operate on #GValue containers. - -Parameter names need to start with a letter (a-z or A-Z). Subsequent -characters can be letters, numbers or a '-'. -All other characters are replaced by a '-' during construction. - -See also #GValue for more information. - Ensures that the contents of @value comply with the specifications + filename="gobject/gparam.c" + line="675">Ensures that the contents of @value comply with the specifications set out by @pspec. For example, a #GParamSpecInt might require that integers stored in @value may not be smaller than -42 and not be greater than +42. If @value contains an integer outside of this range, it is modified accordingly, so the resulting value will fit into the range -42 .. +42. - + whether modifying @value was necessary to ensure validity + filename="gobject/gparam.c" + line="687">whether modifying @value was necessary to ensure validity a valid #GParamSpec + filename="gobject/gparam.c" + line="677">a valid #GParamSpec a #GValue of correct type for @pspec + filename="gobject/gparam.c" + line="678">a #GValue of correct type for @pspec Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, + filename="gobject/gparam.c" + line="807">Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, if @value1 is found to be less than, equal to or greater than @value2, respectively. - + -1, 0 or +1, for a less than, equal to or greater than result + filename="gobject/gparam.c" + line="817">-1, 0 or +1, for a less than, equal to or greater than result a valid #GParamSpec + filename="gobject/gparam.c" + line="809">a valid #GParamSpec a #GValue of correct type for @pspec + filename="gobject/gparam.c" + line="810">a #GValue of correct type for @pspec a #GValue of correct type for @pspec + filename="gobject/gparam.c" + line="811">a #GValue of correct type for @pspec @@ -23701,21 +25478,21 @@ respectively. Creates a new %G_TYPE_POINTER derived type id for a new + filename="gobject/gvaluetypes.c" + line="1473">Creates a new %G_TYPE_POINTER derived type id for a new pointer type with name @name. - + a new %G_TYPE_POINTER derived type id for @name. + filename="gobject/gvaluetypes.c" + line="1480">a new %G_TYPE_POINTER derived type id for @name. the name of the new pointer type. + filename="gobject/gvaluetypes.c" + line="1475">the name of the new pointer type. @@ -23725,8 +25502,8 @@ pointer type with name @name. version="2.44" introspectable="0"> Updates a #GObject pointer to refer to @new_object. + filename="gobject/gobject.h" + line="697">Updates a #GObject pointer to refer to @new_object. It increments the reference count of @new_object (if non-%NULL), decrements the reference count of the current value of @object_ptr (if non-%NULL), and @@ -23751,17 +25528,17 @@ One convenient usage of this function is in implementing property setters: g_object_notify (foo, "bar"); } ]| - + a pointer to a #GObject reference + filename="gobject/gobject.h" + line="699">a pointer to a #GObject reference a pointer to the new #GObject to + filename="gobject/gobject.h" + line="700">a pointer to the new #GObject to assign to @object_ptr, or %NULL to clear the pointer @@ -23771,8 +25548,8 @@ One convenient usage of this function is in implementing property setters: version="2.56" introspectable="0"> Updates a pointer to weakly refer to @new_object. + filename="gobject/gobject.h" + line="851">Updates a pointer to weakly refer to @new_object. It assigns @new_object to @weak_pointer_location and ensures that @weak_pointer_location will automatically be set to %NULL @@ -23799,17 +25576,17 @@ One convenient usage of this function is in implementing property setters: g_object_notify (foo, "bar"); } ]| - + the memory address of a pointer + filename="gobject/gobject.h" + line="853">the memory address of a pointer a pointer to the new #GObject to + filename="gobject/gobject.h" + line="854">a pointer to the new #GObject to assign to it, or %NULL to clear the pointer @@ -23818,8 +25595,8 @@ One convenient usage of this function is in implementing property setters: c:identifier="g_signal_accumulator_first_wins" version="2.28"> A predefined #GSignalAccumulator for signals intended to be used as a + filename="gobject/gsignal.c" + line="4141">A predefined #GSignalAccumulator for signals intended to be used as a hook for application code to provide a particular value. Usually only one such value is desired and multiple handlers for the same signal don't make much sense (except for the case of the default @@ -23829,30 +25606,30 @@ usually want the signal connection to override the class handler). This accumulator will use the return value from the first signal handler that is run as the return value for the signal and not run any further handlers (ie: the first handler "wins"). - + standard #GSignalAccumulator result + filename="gobject/gsignal.c" + line="4159">standard #GSignalAccumulator result standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4143">standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4144">standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4145">standard #GSignalAccumulator parameter nullable="1" allow-none="1"> standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4146">standard #GSignalAccumulator parameter @@ -23870,38 +25647,38 @@ any further handlers (ie: the first handler "wins"). c:identifier="g_signal_accumulator_true_handled" version="2.4"> A predefined #GSignalAccumulator for signals that return a + filename="gobject/gsignal.c" + line="4106">A predefined #GSignalAccumulator for signals that return a boolean values. The behavior that this accumulator gives is that a return of %TRUE stops the signal emission: no further callbacks will be invoked, while a return of %FALSE allows the emission to continue. The idea here is that a %TRUE return indicates that the callback handled the signal, and no further handling is needed. - + standard #GSignalAccumulator result + filename="gobject/gsignal.c" + line="4123">standard #GSignalAccumulator result standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4108">standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4109">standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4110">standard #GSignalAccumulator parameter nullable="1" allow-none="1"> standard #GSignalAccumulator parameter + filename="gobject/gsignal.c" + line="4111">standard #GSignalAccumulator parameter @@ -23918,28 +25695,28 @@ handling is needed. Adds an emission hook for a signal, which will get called for any emission + filename="gobject/gsignal.c" + line="934">Adds an emission hook for a signal, which will get called for any emission of that signal, independent of the instance. This is possible only for signals which don't have %G_SIGNAL_NO_HOOKS flag set. - + the hook id, for later use with g_signal_remove_emission_hook(). + filename="gobject/gsignal.c" + line="946">the hook id, for later use with g_signal_remove_emission_hook(). the signal identifier, as returned by g_signal_lookup(). + filename="gobject/gsignal.c" + line="936">the signal identifier, as returned by g_signal_lookup(). the detail on which to call the hook. + filename="gobject/gsignal.c" + line="937">the detail on which to call the hook. closure="3" destroy="4"> a #GSignalEmissionHook function. + filename="gobject/gsignal.c" + line="938">a #GSignalEmissionHook function. + scope="notified"> user data for @hook_func. + filename="gobject/gsignal.c" + line="939">user data for @hook_func. scope="async" destroy="3"> a #GDestroyNotify for @hook_data. + filename="gobject/gsignal.c" + line="940">a #GDestroyNotify for @hook_data. @@ -23979,20 +25755,20 @@ for signals which don't have %G_SIGNAL_NO_HOOKS flag set. Calls the original class closure of a signal. This function should only + filename="gobject/gsignal.c" + line="2033">Calls the original class closure of a signal. This function should only be called from an overridden class closure; see g_signal_override_class_closure() and g_signal_override_class_handler(). - + the argument list of the signal emission. + filename="gobject/gsignal.c" + line="2035">the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. @@ -24001,8 +25777,8 @@ g_signal_override_class_handler(). Location for the return value. + filename="gobject/gsignal.c" + line="2038">Location for the return value. @@ -24012,27 +25788,27 @@ g_signal_override_class_handler(). version="2.18" introspectable="0"> Calls the original class closure of a signal. This function should + filename="gobject/gsignal.c" + line="2105">Calls the original class closure of a signal. This function should only be called from an overridden class closure; see g_signal_override_class_closure() and g_signal_override_class_handler(). - + the instance the signal is being + filename="gobject/gsignal.c" + line="2107">the instance the signal is being emitted on. parameters to be passed to the parent class closure, followed by a + filename="gobject/gsignal.c" + line="2109">parameters to be passed to the parent class closure, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. @@ -24043,33 +25819,42 @@ g_signal_override_class_handler(). c:identifier="g_signal_connect" introspectable="0"> Connects a #GCallback function to a signal for a particular object. + filename="gobject/gsignal.h" + line="496">Connects a [type@GObject.Callback] function to a signal for a particular object. + +The handler will be called synchronously, before the default handler of the signal. +[func@GObject.signal_emit] will not return control until all handlers are called. -The handler will be called synchronously, before the default handler of the signal. g_signal_emit() will not return control until all handlers are called. +See [memory management of signal handlers](signals.html#memory-management-of-signal-handlers) for +details on how to handle the return value and memory management of @data. -See [memory management of signal handlers][signal-memory-management] for -details on how to handle the return value and memory management of @data. - +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +‘detail’ string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. @@ -24078,72 +25863,88 @@ details on how to handle the return value and memory management of @data. c:identifier="g_signal_connect_after" introspectable="0"> Connects a #GCallback function to a signal for a particular object. + filename="gobject/gsignal.h" + line="525">Connects a #GCallback function to a signal for a particular object. + +The handler will be called synchronously, after the default handler of the signal. -The handler will be called synchronously, after the default handler of the signal. - +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +‘detail’ string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the instance to connect to. + filename="gobject/gsignal.h" + line="527">the instance to connect to. a string of the form "signal-name::detail". + filename="gobject/gsignal.h" + line="528">a string of the form "signal-name::detail". the #GCallback to connect. + filename="gobject/gsignal.h" + line="529">the #GCallback to connect. data to pass to @c_handler calls. + filename="gobject/gsignal.h" + line="530">data to pass to @c_handler calls. Connects a closure to a signal for a particular object. + filename="gobject/gsignal.c" + line="2363">Connects a closure to a signal for a particular object. If @closure is a floating reference (see g_closure_sink()), this function -takes ownership of @closure. - +takes ownership of @closure. + +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +‘detail’ string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the handler ID (always greater than 0 for successful connections) + filename="gobject/gsignal.c" + line="2384">the handler ID (always greater than 0) the instance to connect to. + filename="gobject/gsignal.c" + line="2365">the instance to connect to. a string of the form "signal-name::detail". + filename="gobject/gsignal.c" + line="2366">a string of the form "signal-name::detail". the closure to connect. + filename="gobject/gsignal.c" + line="2367">the closure to connect. whether the handler should be called before or after the + filename="gobject/gsignal.c" + line="2368">whether the handler should be called before or after the default handler of the signal. @@ -24152,47 +25953,55 @@ takes ownership of @closure. Connects a closure to a signal for a particular object. + filename="gobject/gsignal.c" + line="2289">Connects a closure to a signal for a particular object. If @closure is a floating reference (see g_closure_sink()), this function -takes ownership of @closure. - +takes ownership of @closure. + +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +‘detail’ string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the handler ID (always greater than 0 for successful connections) + filename="gobject/gsignal.c" + line="2311">the handler ID (always greater than 0) the instance to connect to. + filename="gobject/gsignal.c" + line="2291">the instance to connect to. the id of the signal. + filename="gobject/gsignal.c" + line="2292">the id of the signal. the detail. + filename="gobject/gsignal.c" + line="2293">the detail. the closure to connect. + filename="gobject/gsignal.c" + line="2294">the closure to connect. whether the handler should be called before or after the + filename="gobject/gsignal.c" + line="2295">whether the handler should be called before or after the default handler of the signal. @@ -24202,47 +26011,54 @@ takes ownership of @closure. c:identifier="g_signal_connect_data" introspectable="0"> Connects a #GCallback function to a signal for a particular object. Similar + filename="gobject/gsignal.c" + line="2465">Connects a #GCallback function to a signal for a particular object. Similar to g_signal_connect(), but allows to provide a #GClosureNotify for the data which will be called when the signal handler is disconnected and no longer used. Specify @connect_flags if you need `..._after()` or -`..._swapped()` variants of this function. - +`..._swapped()` variants of this function. + +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +‘detail’ string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the handler ID (always greater than 0 for successful connections) + filename="gobject/gsignal.c" + line="2488">the handler ID (always greater than 0) the instance to connect to. + filename="gobject/gsignal.c" + line="2467">the instance to connect to. a string of the form "signal-name::detail". + filename="gobject/gsignal.c" + line="2468">a string of the form "signal-name::detail". the #GCallback to connect. + filename="gobject/gsignal.c" + line="2469">the #GCallback to connect. + scope="notified"> data to pass to @c_handler calls. + filename="gobject/gsignal.c" + line="2470">data to pass to @c_handler calls. a #GClosureNotify for @data. + filename="gobject/gsignal.c" + line="2471">a #GClosureNotify for @data. a combination of #GConnectFlags. + filename="gobject/gsignal.c" + line="2472">a combination of #GConnectFlags. @@ -24268,39 +26084,47 @@ used. Specify @connect_flags if you need `..._after()` or c:identifier="g_signal_connect_object" introspectable="0"> This is similar to g_signal_connect_data(), but uses a closure which + filename="gobject/gobject.c" + line="5148">This is similar to g_signal_connect_data(), but uses a closure which ensures that the @gobject stays alive during the call to @c_handler by temporarily adding a reference count to @gobject. When the @gobject is destroyed the signal handler will be automatically disconnected. Note that this is not currently threadsafe (ie: emitting a signal while @gobject is being destroyed in another thread -is not safe). - +is not safe). + +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +"detail" string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the handler id. + filename="gobject/gobject.c" + line="5174">the handler id. the instance to connect to. + filename="gobject/gobject.c" + line="5150">the instance to connect to. a string of the form "signal-name::detail". + filename="gobject/gobject.c" + line="5151">a string of the form "signal-name::detail". the #GCallback to connect. + filename="gobject/gobject.c" + line="5152">the #GCallback to connect. nullable="1" allow-none="1"> the object to pass as data + filename="gobject/gobject.c" + line="5153">the object to pass as data to @c_handler. a combination of #GConnectFlags. + filename="gobject/gobject.c" + line="5155">a combination of #GConnectFlags. @@ -24325,8 +26149,8 @@ is not safe). c:identifier="g_signal_connect_swapped" introspectable="0"> Connects a #GCallback function to a signal for a particular object. + filename="gobject/gsignal.h" + line="548">Connects a #GCallback function to a signal for a particular object. The instance on which the signal is emitted and @data will be swapped when calling the handler. This is useful when calling pre-existing functions to @@ -24351,28 +26175,36 @@ button_clicked_cb (GtkButton *button, GtkWidget *other_widget) g_signal_connect (button, "clicked", (GCallback) button_clicked_cb, other_widget); -]| - +]| + +This function cannot fail. If the given signal name doesn’t exist, +a critical warning is emitted. No validation is performed on the +‘detail’ string when specified in @detailed_signal, other than a +non-empty check. + +Refer to the [signals documentation](signals.html) for more +details. + the instance to connect to. + filename="gobject/gsignal.h" + line="550">the instance to connect to. a string of the form "signal-name::detail". + filename="gobject/gsignal.h" + line="551">a string of the form "signal-name::detail". the #GCallback to connect. + filename="gobject/gsignal.h" + line="552">the #GCallback to connect. data to pass to @c_handler calls. + filename="gobject/gsignal.h" + line="553">data to pass to @c_handler calls. @@ -24380,39 +26212,39 @@ g_signal_connect (button, "clicked", c:identifier="g_signal_emit" introspectable="0"> Emits a signal. Signal emission is done synchronously. + filename="gobject/gsignal.c" + line="3573">Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emit() resets the return value to the default if no handlers are connected, in contrast to g_signal_emitv(). - + the instance the signal is being emitted on. + filename="gobject/gsignal.c" + line="3575">the instance the signal is being emitted on. the signal id + filename="gobject/gsignal.c" + line="3576">the signal id the detail + filename="gobject/gsignal.c" + line="3577">the detail parameters to be passed to the signal, followed by a + filename="gobject/gsignal.c" + line="3578">parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. @@ -24423,33 +26255,33 @@ if no handlers are connected, in contrast to g_signal_emitv(). c:identifier="g_signal_emit_by_name" introspectable="0"> Emits a signal. Signal emission is done synchronously. + filename="gobject/gsignal.c" + line="3601">Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emit_by_name() resets the return value to the default if no handlers are connected, in contrast to g_signal_emitv(). - + the instance the signal is being emitted on. + filename="gobject/gsignal.c" + line="3603">the instance the signal is being emitted on. a string of the form "signal-name::detail". + filename="gobject/gsignal.c" + line="3604">a string of the form "signal-name::detail". parameters to be passed to the signal, followed by a + filename="gobject/gsignal.c" + line="3605">parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. The number of parameters to pass to this function is defined when creating the signal. @@ -24461,40 +26293,40 @@ if no handlers are connected, in contrast to g_signal_emitv(). c:identifier="g_signal_emit_valist" introspectable="0"> Emits a signal. Signal emission is done synchronously. + filename="gobject/gsignal.c" + line="3254">Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emit_valist() resets the return value to the default if no handlers are connected, in contrast to g_signal_emitv(). - + the instance the signal is being + filename="gobject/gsignal.c" + line="3256">the instance the signal is being emitted on. the signal id + filename="gobject/gsignal.c" + line="3258">the signal id the detail + filename="gobject/gsignal.c" + line="3259">the detail a list of parameters to be passed to the signal, followed by a + filename="gobject/gsignal.c" + line="3260">a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is %G_TYPE_NONE, the return value location can be omitted. @@ -24503,21 +26335,21 @@ if no handlers are connected, in contrast to g_signal_emitv(). Emits a signal. Signal emission is done synchronously. + filename="gobject/gsignal.c" + line="3102">Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped. Note that g_signal_emitv() doesn't change @return_value if no handlers are connected, in contrast to g_signal_emit() and g_signal_emit_valist(). - + argument list for the signal emission. + filename="gobject/gsignal.c" + line="3104">argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. @@ -24526,14 +26358,14 @@ connected, in contrast to g_signal_emit() and g_signal_emit_valist(). the signal id + filename="gobject/gsignal.c" + line="3107">the signal id the detail + filename="gobject/gsignal.c" + line="3108">the detail transfer-ownership="full" optional="1"> Location to + filename="gobject/gsignal.c" + line="3109">Location to store the return value of the signal emission. This must be provided if the specified signal returns a value, but may be ignored otherwise. @@ -24553,21 +26385,21 @@ specified signal returns a value, but may be ignored otherwise. Returns the invocation hint of the innermost signal emission of instance. - + filename="gobject/gsignal.c" + line="2266">Returns the invocation hint of the innermost signal emission of instance. + the invocation hint of the innermost + filename="gobject/gsignal.c" + line="2272">the invocation hint of the innermost signal emission, or %NULL if not found. the instance to query + filename="gobject/gsignal.c" + line="2268">the instance to query @@ -24575,8 +26407,8 @@ specified signal returns a value, but may be ignored otherwise. Blocks a handler of an instance so it will not be called during any + filename="gobject/gsignal.c" + line="2557">Blocks a handler of an instance so it will not be called during any signal emissions unless it is unblocked again. Thus "blocking" a signal handler means to temporarily deactivate it, a signal handler has to be unblocked exactly the same amount of times it has been @@ -24584,21 +26416,21 @@ blocked before to become active again. The @handler_id has to be a valid signal handler id, connected to a signal of @instance. - + The instance to block the signal handler of. + filename="gobject/gsignal.c" + line="2559">The instance to block the signal handler of. Handler id of the handler to be blocked. + filename="gobject/gsignal.c" + line="2560">Handler id of the handler to be blocked. @@ -24606,71 +26438,71 @@ signal of @instance. Disconnects a handler from an instance so it will not be called during + filename="gobject/gsignal.c" + line="2659">Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The @handler_id becomes invalid and may be reused. The @handler_id has to be a valid signal handler id, connected to a signal of @instance. - + The instance to remove the signal handler from. + filename="gobject/gsignal.c" + line="2661">The instance to remove the signal handler from. Handler id of the handler to be disconnected. + filename="gobject/gsignal.c" + line="2662">Handler id of the handler to be disconnected. Finds the first signal handler that matches certain selection criteria. + filename="gobject/gsignal.c" + line="2780">Finds the first signal handler that matches certain selection criteria. The criteria mask is passed as an OR-ed combination of #GSignalMatchType flags, and the criteria values are passed as arguments. The match @mask has to be non-0 for successful matches. If no handler was found, 0 is returned. - + A valid non-0 signal handler id for a successful match. + filename="gobject/gsignal.c" + line="2797">A valid non-0 signal handler id for a successful match. The instance owning the signal handler to be found. + filename="gobject/gsignal.c" + line="2782">The instance owning the signal handler to be found. Mask indicating which of @signal_id, @detail, @closure, @func + filename="gobject/gsignal.c" + line="2783">Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. Signal the handler has to be connected to. + filename="gobject/gsignal.c" + line="2785">Signal the handler has to be connected to. Signal detail the handler has to be connected to. + filename="gobject/gsignal.c" + line="2786">Signal detail the handler has to be connected to. nullable="1" allow-none="1"> The closure the handler will invoke. + filename="gobject/gsignal.c" + line="2787">The closure the handler will invoke. nullable="1" allow-none="1"> The C closure callback of the handler (useless for non-C closures). + filename="gobject/gsignal.c" + line="2788">The C closure callback of the handler (useless for non-C closures). + allow-none="1"> The closure data of the handler's closure. + filename="gobject/gsignal.c" + line="2789">The closure data of the handler's closure. @@ -24706,26 +26537,26 @@ If no handler was found, 0 is returned. Returns whether @handler_id is the ID of a handler connected to @instance. - + filename="gobject/gsignal.c" + line="2702">Returns whether @handler_id is the ID of a handler connected to @instance. + whether @handler_id identifies a handler connected to @instance. + filename="gobject/gsignal.c" + line="2709">whether @handler_id identifies a handler connected to @instance. The instance where a signal handler is sought. + filename="gobject/gsignal.c" + line="2704">The instance where a signal handler is sought. the handler ID. + filename="gobject/gsignal.c" + line="2705">the handler ID. @@ -24733,8 +26564,8 @@ If no handler was found, 0 is returned. Undoes the effect of a previous g_signal_handler_block() call. A + filename="gobject/gsignal.c" + line="2606">Undoes the effect of a previous g_signal_handler_block() call. A blocked handler is skipped during signal emissions and will not be invoked, unblocking it (for exactly the amount of times it has been blocked before) reverts its "blocked" state, so the handler will be @@ -24747,21 +26578,21 @@ proceeded yet). The @handler_id has to be a valid id of a signal handler that is connected to a signal of @instance and is currently blocked. - + The instance to unblock the signal handler of. + filename="gobject/gsignal.c" + line="2608">The instance to unblock the signal handler of. Handler id of the handler to be unblocked. + filename="gobject/gsignal.c" + line="2609">Handler id of the handler to be unblocked. @@ -24770,32 +26601,32 @@ connected to a signal of @instance and is currently blocked. c:identifier="g_signal_handlers_block_by_func" introspectable="0"> Blocks all handlers on an instance that match @func and @data. - + filename="gobject/gsignal.h" + line="623">Blocks all handlers on an instance that match @func and @data. + The instance to block handlers from. + filename="gobject/gsignal.h" + line="625">The instance to block handlers from. The C closure callback of the handlers (useless for non-C closures). + filename="gobject/gsignal.h" + line="626">The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. + filename="gobject/gsignal.h" + line="627">The closure data of the handlers' closures. Blocks all handlers on an instance that match a certain selection criteria. + filename="gobject/gsignal.c" + line="2858">Blocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as a combination of #GSignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all @@ -24808,37 +26639,37 @@ If no handlers were found, 0 is returned, the number of blocked handlers otherwise. Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. - + The number of handlers that matched. + filename="gobject/gsignal.c" + line="2883">The number of handlers that matched. The instance to block handlers from. + filename="gobject/gsignal.c" + line="2860">The instance to block handlers from. Mask indicating which of @signal_id, @detail, @closure, @func + filename="gobject/gsignal.c" + line="2861">Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. + filename="gobject/gsignal.c" + line="2863">Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. + filename="gobject/gsignal.c" + line="2864">Signal detail the handlers have to be connected to. nullable="1" allow-none="1"> The closure the handlers will invoke. + filename="gobject/gsignal.c" + line="2865">The closure the handlers will invoke. nullable="1" allow-none="1"> The C closure callback of the handlers (useless for non-C closures). + filename="gobject/gsignal.c" + line="2866">The C closure callback of the handlers (useless for non-C closures). + allow-none="1"> The closure data of the handlers' closures. + filename="gobject/gsignal.c" + line="2867">The closure data of the handlers' closures. @@ -24874,19 +26704,19 @@ Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. Destroy all signal handlers of a type instance. This function is + filename="gobject/gsignal.c" + line="2728">Destroy all signal handlers of a type instance. This function is an implementation detail of the #GObject dispose implementation, and should not be used outside of the type system. - + The instance whose signal handlers are destroyed + filename="gobject/gsignal.c" + line="2730">The instance whose signal handlers are destroyed @@ -24896,19 +26726,19 @@ and should not be used outside of the type system. version="2.32" introspectable="0"> Disconnects all handlers on an instance that match @data. - + filename="gobject/gsignal.h" + line="609">Disconnects all handlers on an instance that match @data. + The instance to remove handlers from + filename="gobject/gsignal.h" + line="611">The instance to remove handlers from the closure data of the handlers' closures + filename="gobject/gsignal.h" + line="612">the closure data of the handlers' closures @@ -24916,32 +26746,32 @@ and should not be used outside of the type system. c:identifier="g_signal_handlers_disconnect_by_func" introspectable="0"> Disconnects all handlers on an instance that match @func and @data. - + filename="gobject/gsignal.h" + line="594">Disconnects all handlers on an instance that match @func and @data. + The instance to remove handlers from. + filename="gobject/gsignal.h" + line="596">The instance to remove handlers from. The C closure callback of the handlers (useless for non-C closures). + filename="gobject/gsignal.h" + line="597">The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. + filename="gobject/gsignal.h" + line="598">The closure data of the handlers' closures. Disconnects all handlers on an instance that match a certain + filename="gobject/gsignal.c" + line="2968">Disconnects all handlers on an instance that match a certain selection criteria. The criteria mask is passed as a combination of #GSignalMatchType flags, and @@ -24955,37 +26785,37 @@ matches. If no handlers were found, 0 is returned, the number of disconnected handlers otherwise. Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. - + The number of handlers that matched. + filename="gobject/gsignal.c" + line="2994">The number of handlers that matched. The instance to remove handlers from. + filename="gobject/gsignal.c" + line="2970">The instance to remove handlers from. Mask indicating which of @signal_id, @detail, @closure, @func + filename="gobject/gsignal.c" + line="2971">Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. + filename="gobject/gsignal.c" + line="2973">Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. + filename="gobject/gsignal.c" + line="2974">Signal detail the handlers have to be connected to. nullable="1" allow-none="1"> The closure the handlers will invoke. + filename="gobject/gsignal.c" + line="2975">The closure the handlers will invoke. nullable="1" allow-none="1"> The C closure callback of the handlers (useless for non-C closures). + filename="gobject/gsignal.c" + line="2976">The C closure callback of the handlers (useless for non-C closures). + allow-none="1"> The closure data of the handlers' closures. + filename="gobject/gsignal.c" + line="2977">The closure data of the handlers' closures. @@ -25022,32 +26851,32 @@ Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. c:identifier="g_signal_handlers_unblock_by_func" introspectable="0"> Unblocks all handlers on an instance that match @func and @data. - + filename="gobject/gsignal.h" + line="637">Unblocks all handlers on an instance that match @func and @data. + The instance to unblock handlers from. + filename="gobject/gsignal.h" + line="639">The instance to unblock handlers from. The C closure callback of the handlers (useless for non-C closures). + filename="gobject/gsignal.h" + line="640">The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. + filename="gobject/gsignal.h" + line="641">The closure data of the handlers' closures. Unblocks all handlers on an instance that match a certain selection + filename="gobject/gsignal.c" + line="2912">Unblocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as a combination of #GSignalMatchType flags, and @@ -25062,37 +26891,37 @@ otherwise. The match criteria should not apply to any handlers that are not currently blocked. Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. - + The number of handlers that matched. + filename="gobject/gsignal.c" + line="2939">The number of handlers that matched. The instance to unblock handlers from. + filename="gobject/gsignal.c" + line="2914">The instance to unblock handlers from. Mask indicating which of @signal_id, @detail, @closure, @func + filename="gobject/gsignal.c" + line="2915">Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. + filename="gobject/gsignal.c" + line="2917">Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. + filename="gobject/gsignal.c" + line="2918">Signal detail the handlers have to be connected to. nullable="1" allow-none="1"> The closure the handlers will invoke. + filename="gobject/gsignal.c" + line="2919">The closure the handlers will invoke. nullable="1" allow-none="1"> The C closure callback of the handlers (useless for non-C closures). + filename="gobject/gsignal.c" + line="2920">The C closure callback of the handlers (useless for non-C closures). + allow-none="1"> The closure data of the handlers' closures. + filename="gobject/gsignal.c" + line="2921">The closure data of the handlers' closures. @@ -25128,8 +26956,8 @@ Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78. Returns whether there are any handlers connected to @instance for the + filename="gobject/gsignal.c" + line="3023">Returns whether there are any handlers connected to @instance for the given signal id and detail. If @detail is 0 then it will only match handlers that were connected @@ -25145,37 +26973,37 @@ One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments. - + %TRUE if a handler is connected to the signal, %FALSE + filename="gobject/gsignal.c" + line="3047">%TRUE if a handler is connected to the signal, %FALSE otherwise. the object whose signal handlers are sought. + filename="gobject/gsignal.c" + line="3025">the object whose signal handlers are sought. the signal id. + filename="gobject/gsignal.c" + line="3026">the signal id. the detail. + filename="gobject/gsignal.c" + line="3027">the detail. whether blocked handlers should count as match. + filename="gobject/gsignal.c" + line="3028">whether blocked handlers should count as match. @@ -25184,40 +27012,39 @@ of building the arguments. c:identifier="g_signal_is_valid_name" version="2.66"> Validate a signal name. This can be useful for dynamically-generated signals + filename="gobject/gsignal.c" + line="279">Validate a signal name. This can be useful for dynamically-generated signals which need to be validated at run-time before actually trying to create them. -See [canonical parameter names][canonical-parameter-names] for details of -the rules for valid names. The rules for signal names are the same as those -for property names. - +See [func@GObject.signal_new] for details of the rules for valid names. +The rules for signal names are the same as those for property names. + %TRUE if @name is a valid signal name, %FALSE otherwise. + filename="gobject/gsignal.c" + line="289">%TRUE if @name is a valid signal name, %FALSE otherwise. the canonical name of the signal + filename="gobject/gsignal.c" + line="281">the canonical name of the signal Lists the signals by id that a certain instance or interface type + filename="gobject/gsignal.c" + line="1237">Lists the signals by id that a certain instance or interface type created. Further information about the signals can be acquired through g_signal_query(). - + Newly allocated array of signal IDs. + filename="gobject/gsignal.c" + line="1246">Newly allocated array of signal IDs. @@ -25225,8 +27052,8 @@ g_signal_query(). Instance or interface type. + filename="gobject/gsignal.c" + line="1239">Instance or interface type. caller-allocates="0" transfer-ownership="full"> Location to store the number of signal ids for @itype. + filename="gobject/gsignal.c" + line="1240">Location to store the number of signal ids for @itype. Given the name of the signal and the type of object it connects to, gets + filename="gobject/gsignal.c" + line="1193">Given the name of the signal and the type of object it connects to, gets the signal's identifying integer. Emitting the signal by number is somewhat faster than using the name each time. @@ -25254,54 +27081,54 @@ example, using g_type_class_ref()) for this function to work, as signals are always installed during class initialization. See g_signal_new() for details on allowed signal names. - + the signal's identifying number, or 0 if no signal was found. + filename="gobject/gsignal.c" + line="1210">the signal's identifying number, or 0 if no signal was found. the signal's name. + filename="gobject/gsignal.c" + line="1195">the signal's name. the type that the signal operates on. + filename="gobject/gsignal.c" + line="1196">the type that the signal operates on. Given the signal's identifier, finds its name. + filename="gobject/gsignal.c" + line="1289">Given the signal's identifier, finds its name. Two different signals may have the same name, if they have differing types. - + the signal name, or %NULL if the signal number was invalid. + filename="gobject/gsignal.c" + line="1297">the signal name, or %NULL if the signal number was invalid. the signal's identifying number. + filename="gobject/gsignal.c" + line="1291">the signal's identifying number. Creates a new signal. (This is usually done in the class initializer.) + filename="gobject/gsignal.c" + line="1351">Creates a new signal. (This is usually done in the class initializer.) A signal name consists of segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first @@ -25325,39 +27152,39 @@ instead of g_cclosure_marshal_generic(). If @c_marshaller is non-%NULL, you need to also specify a va_marshaller using g_signal_set_va_marshaller() or the generic va_marshaller will be used. - + the signal id + filename="gobject/gsignal.c" + line="1396">the signal id the name for the signal + filename="gobject/gsignal.c" + line="1353">the name for the signal the type this signal pertains to. It will also pertain to + filename="gobject/gsignal.c" + line="1354">the type this signal pertains to. It will also pertain to types which are derived from this type. a combination of #GSignalFlags specifying detail of when + filename="gobject/gsignal.c" + line="1356">a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. The offset of the function pointer in the class structure + filename="gobject/gsignal.c" + line="1359">The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. @@ -25366,20 +27193,20 @@ be used. transfer-ownership="none" nullable="1" allow-none="1" + scope="forever" closure="5"> the accumulator for this signal; may be %NULL. + filename="gobject/gsignal.c" + line="1362">the accumulator for this signal; may be %NULL. + allow-none="1"> user data for the @accumulator. + filename="gobject/gsignal.c" + line="1363">user data for the @accumulator. nullable="1" allow-none="1"> the function to translate arrays of parameter + filename="gobject/gsignal.c" + line="1364">the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or %G_TYPE_NONE for a signal + filename="gobject/gsignal.c" + line="1366">the type of return value, or %G_TYPE_NONE for a signal without a return value. the number of parameter types to follow. + filename="gobject/gsignal.c" + line="1368">the number of parameter types to follow. a list of types, one for each parameter. + filename="gobject/gsignal.c" + line="1369">a list of types, one for each parameter. @@ -25418,8 +27245,8 @@ be used. version="2.18" introspectable="0"> Creates a new signal. (This is usually done in the class initializer.) + filename="gobject/gsignal.c" + line="1427">Creates a new signal. (This is usually done in the class initializer.) This is a variant of g_signal_new() that takes a C callback instead of a class offset for the signal's class handler. This function @@ -25435,31 +27262,31 @@ See g_signal_new() for information about signal names. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. - + the signal id + filename="gobject/gsignal.c" + line="1464">the signal id the name for the signal + filename="gobject/gsignal.c" + line="1429">the name for the signal the type this signal pertains to. It will also pertain to + filename="gobject/gsignal.c" + line="1430">the type this signal pertains to. It will also pertain to types which are derived from this type. a combination of #GSignalFlags specifying detail of when + filename="gobject/gsignal.c" + line="1432">a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. @@ -25467,10 +27294,11 @@ the marshaller for this signal. + allow-none="1" + scope="forever"> a #GCallback which acts as class implementation of + filename="gobject/gsignal.c" + line="1435">a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. @@ -25479,20 +27307,20 @@ the marshaller for this signal. transfer-ownership="none" nullable="1" allow-none="1" + scope="forever" closure="5"> the accumulator for this signal; may be %NULL. + filename="gobject/gsignal.c" + line="1438">the accumulator for this signal; may be %NULL. + allow-none="1"> user data for the @accumulator. + filename="gobject/gsignal.c" + line="1439">user data for the @accumulator. nullable="1" allow-none="1"> the function to translate arrays of parameter + filename="gobject/gsignal.c" + line="1440">the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or %G_TYPE_NONE for a signal + filename="gobject/gsignal.c" + line="1442">the type of return value, or %G_TYPE_NONE for a signal without a return value. the number of parameter types to follow. + filename="gobject/gsignal.c" + line="1444">the number of parameter types to follow. a list of types, one for each parameter. + filename="gobject/gsignal.c" + line="1445">a list of types, one for each parameter. @@ -25530,38 +27358,38 @@ the marshaller for this signal. c:identifier="g_signal_new_valist" introspectable="0"> Creates a new signal. (This is usually done in the class initializer.) + filename="gobject/gsignal.c" + line="1827">Creates a new signal. (This is usually done in the class initializer.) See g_signal_new() for details on allowed signal names. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. - + the signal id + filename="gobject/gsignal.c" + line="1852">the signal id the name for the signal + filename="gobject/gsignal.c" + line="1829">the name for the signal the type this signal pertains to. It will also pertain to + filename="gobject/gsignal.c" + line="1830">the type this signal pertains to. It will also pertain to types which are derived from this type. a combination of #GSignalFlags specifying detail of when + filename="gobject/gsignal.c" + line="1832">a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. @@ -25571,28 +27399,28 @@ the marshaller for this signal. nullable="1" allow-none="1"> The closure to invoke on signal emission; may be %NULL. + filename="gobject/gsignal.c" + line="1835">The closure to invoke on signal emission; may be %NULL. the accumulator for this signal; may be %NULL. + filename="gobject/gsignal.c" + line="1836">the accumulator for this signal; may be %NULL. + allow-none="1"> user data for the @accumulator. + filename="gobject/gsignal.c" + line="1837">user data for the @accumulator. nullable="1" allow-none="1"> the function to translate arrays of parameter + filename="gobject/gsignal.c" + line="1838">the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or %G_TYPE_NONE for a signal + filename="gobject/gsignal.c" + line="1840">the type of return value, or %G_TYPE_NONE for a signal without a return value. the number of parameter types in @args. + filename="gobject/gsignal.c" + line="1842">the number of parameter types in @args. va_list of #GType, one for each parameter. + filename="gobject/gsignal.c" + line="1843">va_list of #GType, one for each parameter. @@ -25630,38 +27458,38 @@ the marshaller for this signal. c:identifier="g_signal_newv" introspectable="0"> Creates a new signal. (This is usually done in the class initializer.) + filename="gobject/gsignal.c" + line="1565">Creates a new signal. (This is usually done in the class initializer.) See g_signal_new() for details on allowed signal names. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. - + the signal id + filename="gobject/gsignal.c" + line="1593">the signal id the name for the signal + filename="gobject/gsignal.c" + line="1567">the name for the signal the type this signal pertains to. It will also pertain to + filename="gobject/gsignal.c" + line="1568">the type this signal pertains to. It will also pertain to types which are derived from this type a combination of #GSignalFlags specifying detail of when + filename="gobject/gsignal.c" + line="1570">a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST @@ -25671,8 +27499,8 @@ the marshaller for this signal. nullable="1" allow-none="1"> The closure to invoke on signal emission; + filename="gobject/gsignal.c" + line="1573">The closure to invoke on signal emission; may be %NULL @@ -25680,20 +27508,20 @@ the marshaller for this signal. transfer-ownership="none" nullable="1" allow-none="1" + scope="forever" closure="5"> the accumulator for this signal; may be %NULL + filename="gobject/gsignal.c" + line="1575">the accumulator for this signal; may be %NULL + allow-none="1"> user data for the @accumulator + filename="gobject/gsignal.c" + line="1576">user data for the @accumulator nullable="1" allow-none="1"> the function to translate arrays of + filename="gobject/gsignal.c" + line="1577">the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL the type of return value, or %G_TYPE_NONE for a signal + filename="gobject/gsignal.c" + line="1580">the type of return value, or %G_TYPE_NONE for a signal without a return value the length of @param_types + filename="gobject/gsignal.c" + line="1582">the length of @param_types nullable="1" allow-none="1"> an array of types, one for + filename="gobject/gsignal.c" + line="1583">an array of types, one for each parameter (may be %NULL if @n_params is zero) @@ -25737,47 +27565,46 @@ the marshaller for this signal. Overrides the class closure (i.e. the default handler) for the given signal + filename="gobject/gsignal.c" + line="1951">Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of @instance_type. @instance_type must be derived from the type to which the signal belongs. See g_signal_chain_from_overridden() and g_signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one. - + the signal id + filename="gobject/gsignal.c" + line="1953">the signal id the instance type on which to override the class closure + filename="gobject/gsignal.c" + line="1954">the instance type on which to override the class closure for the signal. the closure. + filename="gobject/gsignal.c" + line="1956">the closure. + version="2.18"> Overrides the class closure (i.e. the default handler) for the + filename="gobject/gsignal.c" + line="1993">Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of @instance_type with callback @class_handler. @instance_type must be derived from the type to which the signal belongs. @@ -25785,55 +27612,57 @@ type to which the signal belongs. See g_signal_chain_from_overridden() and g_signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one. - + the name for the signal + filename="gobject/gsignal.c" + line="1995">the name for the signal the instance type on which to override the class handler + filename="gobject/gsignal.c" + line="1996">the instance type on which to override the class handler for the signal. - + the handler. + filename="gobject/gsignal.c" + line="1998">the handler. Internal function to parse a signal name into its @signal_id + filename="gobject/gsignal.c" + line="1088">Internal function to parse a signal name into its @signal_id and @detail quark. - + Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + filename="gobject/gsignal.c" + line="1099">Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. a string of the form "signal-name::detail". + filename="gobject/gsignal.c" + line="1090">a string of the form "signal-name::detail". The interface/instance type that introduced "signal-name". + filename="gobject/gsignal.c" + line="1091">The interface/instance type that introduced "signal-name". caller-allocates="0" transfer-ownership="full"> Location to store the signal id. + filename="gobject/gsignal.c" + line="1092">Location to store the signal id. caller-allocates="0" transfer-ownership="full"> Location to store the detail quark. + filename="gobject/gsignal.c" + line="1093">Location to store the detail quark. %TRUE forces creation of a #GQuark for the detail. + filename="gobject/gsignal.c" + line="1094">%TRUE forces creation of a #GQuark for the detail. Queries the signal system for in-depth information about a + filename="gobject/gsignal.c" + line="1313">Queries the signal system for in-depth information about a specific signal. This function will fill in a user-provided structure to hold signal-specific information. If an invalid signal id is passed in, the @signal_id member of the #GSignalQuery is 0. All members filled into the #GSignalQuery structure should be considered constant and have to be left untouched. - + The signal id of the signal to query information for. + filename="gobject/gsignal.c" + line="1315">The signal id of the signal to query information for. caller-allocates="1" transfer-ownership="none"> A user provided structure that is + filename="gobject/gsignal.c" + line="1316">A user provided structure that is filled in with constant values upon success. @@ -25897,23 +27726,23 @@ be considered constant and have to be left untouched. Deletes an emission hook. - + filename="gobject/gsignal.c" + line="1008">Deletes an emission hook. + the id of the signal + filename="gobject/gsignal.c" + line="1010">the id of the signal the id of the emission hook, as returned by + filename="gobject/gsignal.c" + line="1011">the id of the emission hook, as returned by g_signal_add_emission_hook() @@ -25921,34 +27750,35 @@ be considered constant and have to be left untouched. + version="2.32" + introspectable="0"> Change the #GSignalCVaMarshaller used for a given signal. This is a + filename="gobject/gsignal.c" + line="1785">Change the #GSignalCVaMarshaller used for a given signal. This is a specialised form of the marshaller that can often be used for the common case of a single connected signal handler and avoids the overhead of #GValue. Its use is optional. - + the signal id + filename="gobject/gsignal.c" + line="1787">the signal id the instance type on which to set the marshaller. + filename="gobject/gsignal.c" + line="1788">the instance type on which to set the marshaller. the marshaller to set. + filename="gobject/gsignal.c" + line="1789">the marshaller to set. @@ -25956,35 +27786,35 @@ overhead of #GValue. Its use is optional. Stops a signal's current emission. + filename="gobject/gsignal.c" + line="866">Stops a signal's current emission. This will prevent the default method from running, if the signal was %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" flag). Prints a warning if used on a signal which isn't being emitted. - + the object whose signal handlers you wish to stop. + filename="gobject/gsignal.c" + line="868">the object whose signal handlers you wish to stop. the signal identifier, as returned by g_signal_lookup(). + filename="gobject/gsignal.c" + line="869">the signal identifier, as returned by g_signal_lookup(). the detail which the signal was emitted with. + filename="gobject/gsignal.c" + line="870">the detail which the signal was emitted with. @@ -25992,26 +27822,26 @@ Prints a warning if used on a signal which isn't being emitted. Stops a signal's current emission. + filename="gobject/gsignal.c" + line="1137">Stops a signal's current emission. This is just like g_signal_stop_emission() except it will look up the signal id for you. - + the object whose signal handlers you wish to stop. + filename="gobject/gsignal.c" + line="1139">the object whose signal handlers you wish to stop. a string of the form "signal-name::detail". + filename="gobject/gsignal.c" + line="1140">a string of the form "signal-name::detail". @@ -26019,153 +27849,68 @@ signal id for you. Creates a new closure which invokes the function found at the offset + filename="gobject/gclosure.c" + line="1156">Creates a new closure which invokes the function found at the offset @struct_offset in the class structure of the interface or classed type identified by @itype. - - + + a floating reference to a new #GCClosure + filename="gobject/gclosure.c" + line="1166">a floating reference to a new #GCClosure the #GType identifier of an interface or classed type + filename="gobject/gclosure.c" + line="1158">the #GType identifier of an interface or classed type the offset of the member function of @itype's class + filename="gobject/gclosure.c" + line="1159">the offset of the member function of @itype's class structure which is to be invoked by the new closure - - The basic concept of the signal system is that of the emission -of a signal. Signals are introduced per-type and are identified -through strings. Signals introduced for a parent type are available -in derived types as well, so basically they are a per-type facility -that is inherited. - -A signal emission mainly involves invocation of a certain set of -callbacks in precisely defined manner. There are two main categories -of such callbacks, per-object ones and user provided ones. -(Although signals can deal with any kind of instantiatable type, I'm -referring to those types as "object types" in the following, simply -because that is the context most users will encounter signals in.) -The per-object callbacks are most often referred to as "object method -handler" or "default (signal) handler", while user provided callbacks are -usually just called "signal handler". - -The object method handler is provided at signal creation time (this most -frequently happens at the end of an object class' creation), while user -provided handlers are frequently connected and disconnected to/from a -certain signal on certain object instances. - -A signal emission consists of five stages, unless prematurely stopped: - -1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - -2. Invocation of normal user-provided signal handlers (where the @after - flag is not set) - -3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - -4. Invocation of user provided signal handlers (where the @after flag is set) - -5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - -The user-provided signal handlers are called in the order they were -connected in. - -All handlers may prematurely stop a signal emission, and any number of -handlers may be connected, disconnected, blocked or unblocked during -a signal emission. - -There are certain criteria for skipping user handlers in stages 2 and 4 -of a signal emission. - -First, user handlers may be blocked. Blocked handlers are omitted during -callback invocation, to return from the blocked state, a handler has to -get unblocked exactly the same amount of times it has been blocked before. - -Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional -@detail argument passed in to g_signal_emit() has to match the detail -argument of the signal handler currently subject to invocation. -Specification of no detail argument for signal handlers (omission of the -detail part of the signal specification upon connection) serves as a -wildcard and matches any detail argument passed in to emission. - -While the @detail argument is typically used to pass an object property name -(as with #GObject::notify), no specific format is mandated for the detail -string, other than that it must be non-empty. - -## Memory management of signal handlers # {#signal-memory-management} - -If you are connecting handlers to signals and using a #GObject instance as -your signal handler user data, you should remember to pair calls to -g_signal_connect() with calls to g_signal_handler_disconnect() or -g_signal_handlers_disconnect_by_func(). While signal handlers are -automatically disconnected when the object emitting the signal is finalised, -they are not automatically disconnected when the signal handler user data is -destroyed. If this user data is a #GObject instance, using it from a -signal handler after it has been finalised is an error. - -There are two strategies for managing such user data. The first is to -disconnect the signal handler (using g_signal_handler_disconnect() or -g_signal_handlers_disconnect_by_func()) when the user data (object) is -finalised; this has to be implemented manually. For non-threaded programs, -g_signal_connect_object() can be used to implement this automatically. -Currently, however, it is unsafe to use in threaded programs. - -The second is to hold a strong reference on the user data until after the -signal is disconnected for other reasons. This can be implemented -automatically using g_signal_connect_data(). - -The first approach is recommended, as the second approach can result in -effective memory leaks of the user data if the signal handler is never -disconnected for some reason. - - - Set the callback for a source as a #GClosure. + + Set the callback for a source as a #GClosure. If the source is not one of the standard GLib types, the @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. - + the source + filename="gobject/gsourceclosure.c" + line="237">the source a #GClosure + filename="gobject/gsourceclosure.c" + line="238">a #GClosure + c:identifier="g_source_set_dummy_callback" + moved-to="Source.set_dummy_callback"> Sets a dummy callback for @source. The callback will do nothing, and + filename="gobject/gsourceclosure.c" + line="301">Sets a dummy callback for @source. The callback will do nothing, and if the source expects a #gboolean return value, it will return %TRUE. (If the source expects any other type of return value, it will return a 0/%NULL value; whatever g_value_init() initializes a #GValue to for @@ -26175,15 +27920,15 @@ If the source is not one of the standard GLib types, the @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. - + the source + filename="gobject/gsourceclosure.c" + line="303">the source @@ -26191,23 +27936,23 @@ functions. Return a newly allocated string, which describes the contents of a + filename="gobject/gvaluetypes.c" + line="1381">Return a newly allocated string, which describes the contents of a #GValue. The main purpose of this function is to describe #GValue contents for debugging output, the way in which the contents are described may change between different GLib versions. - + Newly allocated string. + filename="gobject/gvaluetypes.c" + line="1390">Newly allocated string. #GValue which contents are to be described. + filename="gobject/gvaluetypes.c" + line="1383">#GValue which contents are to be described. @@ -26216,15 +27961,15 @@ described may change between different GLib versions. c:identifier="g_type_add_class_cache_func" introspectable="0"> Adds a #GTypeClassCacheFunc to be called before the reference count of a + filename="gobject/gtype.c" + line="2270">Adds a #GTypeClassCacheFunc to be called before the reference count of a class goes from one to zero. This can be used to prevent premature class destruction. All installed #GTypeClassCacheFunc functions will be chained until one of them returns %TRUE. The functions have to check the class id passed in to figure whether they actually want to cache the class of this type, since all classes are routed through the same #GTypeClassCacheFunc chain. - + @@ -26234,14 +27979,14 @@ chain. nullable="1" allow-none="1"> data to be passed to @cache_func + filename="gobject/gtype.c" + line="2272">data to be passed to @cache_func a #GTypeClassCacheFunc + filename="gobject/gtype.c" + line="2273">a #GTypeClassCacheFunc @@ -26250,8 +27995,8 @@ chain. c:identifier="g_type_add_class_private" version="2.24"> Registers a private class structure for a classed type; + filename="gobject/gtype.c" + line="4724">Registers a private class structure for a classed type; when the class is allocated, the private structures for the class and all of its parent types are allocated sequentially in the same memory block as the public @@ -26261,28 +28006,28 @@ This function should be called in the type's get_type() function after the type is registered. The private structure can be retrieved using the G_TYPE_CLASS_GET_PRIVATE() macro. - + GType of a classed type + filename="gobject/gtype.c" + line="4726">GType of a classed type size of private structure + filename="gobject/gtype.c" + line="4727">size of private structure - + @@ -26300,8 +28045,8 @@ G_TYPE_CLASS_GET_PRIVATE() macro. version="2.4" introspectable="0"> Adds a function to be called after an interface vtable is + filename="gobject/gtype.c" + line="2338">Adds a function to be called after an interface vtable is initialized for any class (i.e. after the @interface_init member of #GInterfaceInfo has been called). @@ -26310,7 +28055,7 @@ that depends on the interfaces of a class. For instance, the implementation of #GObject uses this facility to check that an object implements all of the properties that are defined on its interfaces. - + @@ -26320,14 +28065,14 @@ interfaces. nullable="1" allow-none="1"> data to pass to @check_func + filename="gobject/gtype.c" + line="2340">data to pass to @check_func function to be called after each interface + filename="gobject/gtype.c" + line="2341">function to be called after each interface is initialized @@ -26337,31 +28082,31 @@ interfaces. Adds @interface_type to the dynamic @instance_type. The information + filename="gobject/gtype.c" + line="2668">Adds @interface_type to the dynamic @instance_type. The information contained in the #GTypePlugin structure pointed to by @plugin is used to manage the relationship. - + #GType value of an instantiatable type + filename="gobject/gtype.c" + line="2670">#GType value of an instantiatable type #GType value of an interface type + filename="gobject/gtype.c" + line="2671">#GType value of an interface type #GTypePlugin structure to retrieve the #GInterfaceInfo from + filename="gobject/gtype.c" + line="2672">#GTypePlugin structure to retrieve the #GInterfaceInfo from @@ -26369,31 +28114,31 @@ is used to manage the relationship. Adds @interface_type to the static @instance_type. + filename="gobject/gtype.c" + line="2631">Adds @interface_type to the static @instance_type. The information contained in the #GInterfaceInfo structure pointed to by @info is used to manage the relationship. - + #GType value of an instantiatable type + filename="gobject/gtype.c" + line="2633">#GType value of an instantiatable type #GType value of an interface type + filename="gobject/gtype.c" + line="2634">#GType value of an interface type #GInterfaceInfo structure for this + filename="gobject/gtype.c" + line="2635">#GInterfaceInfo structure for this (@instance_type, @interface_type) combination @@ -26402,7 +28147,7 @@ pointed to by @info is used to manage the relationship. - + @@ -26417,7 +28162,7 @@ pointed to by @info is used to manage the relationship. - + @@ -26432,21 +28177,21 @@ pointed to by @info is used to manage the relationship. Private helper function to aid implementation of the + filename="gobject/gtype.c" + line="4005">Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() macro. - + %TRUE if @instance is valid, %FALSE otherwise + filename="gobject/gtype.c" + line="4012">%TRUE if @instance is valid, %FALSE otherwise a valid #GTypeInstance structure + filename="gobject/gtype.c" + line="4007">a valid #GTypeInstance structure @@ -26454,7 +28199,7 @@ G_TYPE_CHECK_INSTANCE() macro. - + @@ -26469,7 +28214,7 @@ G_TYPE_CHECK_INSTANCE() macro. - + @@ -26484,7 +28229,7 @@ G_TYPE_CHECK_INSTANCE() macro. - + @@ -26499,7 +28244,7 @@ G_TYPE_CHECK_INSTANCE() macro. - + @@ -26510,7 +28255,7 @@ G_TYPE_CHECK_INSTANCE() macro. - + @@ -26522,7 +28267,7 @@ G_TYPE_CHECK_INSTANCE() macro. - + @@ -26537,14 +28282,14 @@ G_TYPE_CHECK_INSTANCE() macro. Return a newly allocated and 0-terminated array of type IDs, listing + filename="gobject/gtype.c" + line="3383">Return a newly allocated and 0-terminated array of type IDs, listing the child types of @type. - + Newly allocated + filename="gobject/gtype.c" + line="3392">Newly allocated and 0-terminated array of child types, free with g_free() @@ -26553,8 +28298,8 @@ the child types of @type. the parent type + filename="gobject/gtype.c" + line="3385">the parent type optional="1" allow-none="1"> location to store the length of + filename="gobject/gtype.c" + line="3386">location to store the length of the returned array, or %NULL @@ -26574,7 +28319,7 @@ the child types of @type. - + @@ -26590,30 +28335,62 @@ the child types of @type. + + Retrieves the type class of the given @type. + +This function will create the class on demand if it does not exist +already. + +If you don't want to create the class, use g_type_class_peek() instead. + + + the class structure + for the type + + + + + type ID of a classed type + + + + This function is essentially the same as g_type_class_ref(), -except that the classes reference count isn't incremented. + filename="gobject/gtype.c" + line="2827">Retrieves the class for a give type. + +This function is essentially the same as g_type_class_get(), +except that the class may have not been instantiated yet. + As a consequence, this function may return %NULL if the class of the type passed in does not currently exist (hasn't been referenced before). - - + + the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist + filename="gobject/gtype.c" + line="2840">the + #GTypeClass structure for the given type ID or %NULL if the class + does not currently exist type ID of a classed type + filename="gobject/gtype.c" + line="2829">type ID of a classed type @@ -26623,48 +28400,52 @@ referenced before). moved-to="TypeClass.peek_static" version="2.4"> A more efficient version of g_type_class_peek() which works only for + filename="gobject/gtype.c" + line="2862">A more efficient version of g_type_class_peek() which works only for static types. - - + + the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist or is dynamically loaded + filename="gobject/gtype.c" + line="2869">the + #GTypeClass structure for the given type ID or %NULL if the class + does not currently exist or is dynamically loaded type ID of a classed type + filename="gobject/gtype.c" + line="2864">type ID of a classed type + moved-to="TypeClass.ref" + deprecated="1" + deprecated-version="2.84"> Increments the reference count of the class structure belonging to -@type. This function will demand-create the class if it doesn't -exist already. - + filename="gobject/gtype.c" + line="2770">Increments the reference count of the class structure belonging to +@type. + +This function will demand-create the class if it doesn't exist already. + Use g_type_class_get() instead + the #GTypeClass - structure for the given type ID + filename="gobject/gtype.c" + line="2779">the #GTypeClass + structure for the given type ID type ID of a classed type + filename="gobject/gtype.c" + line="2772">type ID of a classed type @@ -26673,8 +28454,8 @@ exist already. c:identifier="g_type_create_instance" introspectable="0"> Creates and initializes an instance of @type if @type is valid and + filename="gobject/gtype.c" + line="1793">Creates and initializes an instance of @type if @type is valid and can be instantiated. The type system only performs basic allocation and structure setups for instances: actual instance creation should happen through functions supplied by the type's fundamental type @@ -26690,19 +28471,54 @@ with zeros. Note: Do not use this function, unless you're implementing a fundamental type. Also language bindings should not use this function, but g_object_new() instead. - + an allocated and initialized instance, subject to further + filename="gobject/gtype.c" + line="1814">an allocated and initialized instance, subject to further treatment by the fundamental type implementation an instantiatable type to create an instance for + filename="gobject/gtype.c" + line="1795">an instantiatable type to create an instance for + + + + + + Returns the default interface vtable for the given @g_type. + +If the type is not currently in use, then the default vtable +for the type will be created and initialized by calling +the base interface init and default vtable init functions for +the type (the @base_init and @class_init members of #GTypeInfo). + +If you don't want to create the interface vtable, you should use +g_type_default_interface_peek() instead. + +Calling g_type_default_interface_get() is useful when you +want to make sure that signals and properties for an interface +have been installed. + + + the default + vtable for the interface. + + + + + an interface type @@ -26711,33 +28527,35 @@ function, but g_object_new() instead. c:identifier="g_type_default_interface_peek" version="2.4"> If the interface type @g_type is currently in use, returns its + filename="gobject/gtype.c" + line="3099">If the interface type @g_type is currently in use, returns its default interface vtable. - + the default - vtable for the interface, or %NULL if the type is not currently - in use + filename="gobject/gtype.c" + line="3108">the default + vtable for the interface, or %NULL if the type is not currently + in use an interface type + filename="gobject/gtype.c" + line="3101">an interface type + version="2.4" + deprecated="1" + deprecated-version="2.84"> Increments the reference count for the interface type @g_type, + filename="gobject/gtype.c" + line="3013">Increments the reference count for the interface type @g_type, and returns the default interface vtable for the type. If the type is not currently in use, then the default vtable @@ -26747,43 +28565,50 @@ the type (the @base_init and @class_init members of #GTypeInfo). Calling g_type_default_interface_ref() is useful when you want to make sure that signals and properties for an interface have been installed. - + Use g_type_default_interface_get() instead + the default - vtable for the interface; call g_type_default_interface_unref() - when you are done using the interface. + filename="gobject/gtype.c" + line="3032">the default + vtable for the interface; call g_type_default_interface_unref() + when you are done using the interface. an interface type + filename="gobject/gtype.c" + line="3015">an interface type - Decrements the reference count for the type corresponding to the -interface default vtable @g_iface. If the type is dynamic, then -when no one is using the interface and all references have -been released, the finalize function for the interface's default -vtable (the @class_finalize member of #GTypeInfo) will be called. - + version="2.4" + deprecated="1" + deprecated-version="2.84"> + Decrements the reference count for the type corresponding to the +interface default vtable @g_iface. + +If the type is dynamic, then when no one is using the interface and all +references have been released, the finalize function for the interface's +default vtable (the @class_finalize member of #GTypeInfo) will be called. + Interface reference counting has been removed and + interface types now cannot be finalized. This function no longer does + anything. + the default vtable + filename="gobject/gtype.c" + line="3129">the default vtable structure for an interface, as returned by g_type_default_interface_ref() @@ -26791,29 +28616,29 @@ vtable (the @class_finalize member of #GTypeInfo) will be called. Returns the length of the ancestry of the passed in type. This + filename="gobject/gtype.c" + line="3237">Returns the length of the ancestry of the passed in type. This includes the type itself, so that e.g. a fundamental type has depth 1. - + the depth of @type + filename="gobject/gtype.c" + line="3244">the depth of @type a #GType + filename="gobject/gtype.c" + line="3239">a #GType Ensures that the indicated @type has been registered with the + filename="gobject/gtype.c" + line="4822">Ensures that the indicated @type has been registered with the type system, and its _class_init() method has been run. In theory, simply calling the type's _get_type() method (or using @@ -26825,80 +28650,80 @@ which _get_type() methods do on the first call). As a result, if you write a bare call to a _get_type() macro, it may get optimized out by the compiler. Using g_type_ensure() guarantees that the type's _get_type() method is called. - + a #GType + filename="gobject/gtype.c" + line="4824">a #GType Frees an instance of a type, returning it to the instance pool for + filename="gobject/gtype.c" + line="1915">Frees an instance of a type, returning it to the instance pool for the type, if there is one. Like g_type_create_instance(), this function is reserved for implementors of fundamental types. - + an instance of a type + filename="gobject/gtype.c" + line="1917">an instance of a type Look up the type ID from a given type name, returning 0 if no type + filename="gobject/gtype.c" + line="3193">Look up the type ID from a given type name, returning 0 if no type has been registered under this name (this is the preferred method to find out by name whether a specific type has been registered yet). - + corresponding type ID or 0 + filename="gobject/gtype.c" + line="3202">corresponding type ID or 0 type name to look up + filename="gobject/gtype.c" + line="3195">type name to look up Internal function, used to extract the fundamental type ID portion. + filename="gobject/gtype.c" + line="3874">Internal function, used to extract the fundamental type ID portion. Use G_TYPE_FUNDAMENTAL() instead. - + fundamental type ID + filename="gobject/gtype.c" + line="3881">fundamental type ID valid type ID + filename="gobject/gtype.c" + line="3876">valid type ID @@ -26906,16 +28731,16 @@ Use G_TYPE_FUNDAMENTAL() instead. Returns the next free fundamental type id which can be used to + filename="gobject/gtype.c" + line="3851">Returns the next free fundamental type id which can be used to register a new fundamental type with g_type_register_fundamental(). The returned type ID represents the highest currently registered fundamental type identifier. - + the next available fundamental type ID to be registered, + filename="gobject/gtype.c" + line="3859">the next available fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs @@ -26924,76 +28749,76 @@ fundamental type identifier. c:identifier="g_type_get_instance_count" version="2.44"> Returns the number of instances allocated of the particular type; + filename="gobject/gtype.c" + line="3689">Returns the number of instances allocated of the particular type; this is only available if GLib is built with debugging support and the `instance-count` debug flag is set (by setting the `GOBJECT_DEBUG` variable to include `instance-count`). - + the number of instances allocated of the given type; + filename="gobject/gtype.c" + line="3698">the number of instances allocated of the given type; if instance counts are not available, returns 0. a #GType + filename="gobject/gtype.c" + line="3691">a #GType Returns the #GTypePlugin structure for @type. - + filename="gobject/gtype.c" + line="3783">Returns the #GTypePlugin structure for @type. + the corresponding plugin + filename="gobject/gtype.c" + line="3789">the corresponding plugin if @type is a dynamic type, %NULL otherwise #GType to retrieve the plugin for + filename="gobject/gtype.c" + line="3785">#GType to retrieve the plugin for Obtains data which has previously been attached to @type + filename="gobject/gtype.c" + line="3527">Obtains data which has previously been attached to @type with g_type_set_qdata(). Note that this does not take subtyping into account; data attached to one type with g_type_set_qdata() cannot be retrieved from a subtype using g_type_get_qdata(). - + the data, or %NULL if no data was found + filename="gobject/gtype.c" + line="3539">the data, or %NULL if no data was found a #GType + filename="gobject/gtype.c" + line="3529">a #GType a #GQuark id to identify the data + filename="gobject/gtype.c" + line="3530">a #GQuark id to identify the data @@ -27002,17 +28827,17 @@ be retrieved from a subtype using g_type_get_qdata(). c:identifier="g_type_get_type_registration_serial" version="2.36"> Returns an opaque serial number that represents the state of the set + filename="gobject/gtype.c" + line="370">Returns an opaque serial number that represents the state of the set of registered types. Any time a type is registered this serial changes, which means you can cache information based on type lookups (such as g_type_from_name()) and know if the cache is still valid at a later time by comparing the current serial with the one at the type lookup. - + An unsigned int, representing the state of type registrations + filename="gobject/gtype.c" + line="381">An unsigned int, representing the state of type registrations @@ -27021,12 +28846,12 @@ time by comparing the current serial with the one at the type lookup. deprecated="1" deprecated-version="2.36"> This function used to initialise the type system. Since GLib 2.36, + filename="gobject/gtype.c" + line="4240">This function used to initialise the type system. Since GLib 2.36, the type system is initialised automatically and this function does nothing. the type system is now initialised automatically - + @@ -27036,23 +28861,23 @@ nothing. deprecated="1" deprecated-version="2.36"> This function used to initialise the type system with debugging + filename="gobject/gtype.c" + line="4215">This function used to initialise the type system with debugging flags. Since GLib 2.36, the type system is initialised automatically and this function does nothing. If you need to enable debugging features, use the `GOBJECT_DEBUG` environment variable. the type system is now initialised automatically - + bitwise combination of #GTypeDebugFlags values for + filename="gobject/gtype.c" + line="4217">bitwise combination of #GTypeDebugFlags values for debugging purposes @@ -27062,27 +28887,27 @@ environment variable. c:identifier="g_type_interface_add_prerequisite" moved-to="TypeInterface.add_prerequisite"> Adds @prerequisite_type to the list of prerequisites of @interface_type. + filename="gobject/gtype.c" + line="1509">Adds @prerequisite_type to the list of prerequisites of @interface_type. This means that any type implementing @interface_type must also implement @prerequisite_type. Prerequisites can be thought of as an alternative to interface derivation (which GType doesn't support). An interface can have at most one instantiatable prerequisite type. - + #GType value of an interface type + filename="gobject/gtype.c" + line="1511">#GType value of an interface type #GType value of an interface or instantiatable type + filename="gobject/gtype.c" + line="1512">#GType value of an interface or instantiatable type @@ -27091,30 +28916,30 @@ at most one instantiatable prerequisite type. c:identifier="g_type_interface_get_plugin" moved-to="TypeInterface.get_plugin"> Returns the #GTypePlugin structure for the dynamic interface + filename="gobject/gtype.c" + line="3802">Returns the #GTypePlugin structure for the dynamic interface @interface_type which has been added to @instance_type, or %NULL if @interface_type has not been added to @instance_type or does not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - + the #GTypePlugin for the dynamic + filename="gobject/gtype.c" + line="3812">the #GTypePlugin for the dynamic interface @interface_type of @instance_type #GType of an instantiatable type + filename="gobject/gtype.c" + line="3804">#GType of an instantiatable type #GType of an interface type + filename="gobject/gtype.c" + line="3805">#GType of an interface type @@ -27124,25 +28949,25 @@ not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). moved-to="TypeInterface.instantiatable_prerequisite" version="2.68"> Returns the most specific instantiatable prerequisite of an + filename="gobject/gtype.c" + line="1656">Returns the most specific instantiatable prerequisite of an interface type. If the interface type has no instantiatable prerequisite, %G_TYPE_INVALID is returned. See g_type_interface_add_prerequisite() for more information about prerequisites. - + the instantiatable prerequisite type or %G_TYPE_INVALID if none + filename="gobject/gtype.c" + line="1667">the instantiatable prerequisite type or %G_TYPE_INVALID if none an interface type + filename="gobject/gtype.c" + line="1658">an interface type @@ -27151,29 +28976,29 @@ about prerequisites. c:identifier="g_type_interface_peek" moved-to="TypeInterface.peek"> Returns the #GTypeInterface structure of an interface to which the + filename="gobject/gtype.c" + line="2943">Returns the #GTypeInterface structure of an interface to which the passed in class conforms. - - + + the #GTypeInterface - structure of @iface_type if implemented by @instance_class, %NULL - otherwise + filename="gobject/gtype.c" + line="2951">the #GTypeInterface + structure of @iface_type if implemented by @instance_class, %NULL + otherwise a #GTypeClass structure + filename="gobject/gtype.c" + line="2945">a #GTypeClass structure an interface ID which this class conforms to + filename="gobject/gtype.c" + line="2946">an interface ID which this class conforms to @@ -27183,13 +29008,13 @@ passed in class conforms. moved-to="TypeInterface.prerequisites" version="2.2"> Returns the prerequisites of an interfaces type. - + filename="gobject/gtype.c" + line="1595">Returns the prerequisites of an interfaces type. + a + filename="gobject/gtype.c" + line="1605">a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type @@ -27199,8 +29024,8 @@ passed in class conforms. an interface type + filename="gobject/gtype.c" + line="1597">an interface type optional="1" allow-none="1"> location to return the number + filename="gobject/gtype.c" + line="1598">location to return the number of prerequisites, or %NULL @@ -27219,14 +29044,14 @@ passed in class conforms. Return a newly allocated and 0-terminated array of type IDs, listing + filename="gobject/gtype.c" + line="3427">Return a newly allocated and 0-terminated array of type IDs, listing the interface types that @type conforms to. - + Newly allocated + filename="gobject/gtype.c" + line="3436">Newly allocated and 0-terminated array of interface types, free with g_free() @@ -27235,8 +29060,8 @@ the interface types that @type conforms to. the type to list interface types for + filename="gobject/gtype.c" + line="3429">the type to list interface types for optional="1" allow-none="1"> location to store the length of + filename="gobject/gtype.c" + line="3430">location to store the length of the returned array, or %NULL @@ -27255,28 +29080,28 @@ the interface types that @type conforms to. If @is_a_type is a derivable type, check whether @type is a + filename="gobject/gtype.c" + line="3354">If @is_a_type is a derivable type, check whether @type is a descendant of @is_a_type. If @is_a_type is an interface, check whether @type conforms to it. - + %TRUE if @type is a @is_a_type + filename="gobject/gtype.c" + line="3364">%TRUE if @type is a @is_a_type type to check ancestry for + filename="gobject/gtype.c" + line="3356">type to check ancestry for possible ancestor of @type or interface that @type + filename="gobject/gtype.c" + line="3357">possible ancestor of @type or interface that @type could conform to @@ -27284,31 +29109,32 @@ whether @type conforms to it. Get the unique name that is assigned to a type ID. Note that this -function (like all other GType API) cannot cope with invalid type -IDs. %G_TYPE_INVALID may be passed to this function, as may be any -other validly registered type ID, but randomized type IDs should -not be passed in and will most likely lead to a crash. - + filename="gobject/gtype.c" + line="3150">Get the unique name that is assigned to a type ID. + +Note that this function (like all other GType API) cannot cope with +invalid type IDs. %G_TYPE_INVALID may be passed to this function, as +may be any other validly registered type ID, but randomized type IDs +should not be passed in and will most likely lead to a crash. + static type name or %NULL + filename="gobject/gtype.c" + line="3161">static type name or %NULL type to return name for + filename="gobject/gtype.c" + line="3152">type to return name for - + @@ -27320,7 +29146,7 @@ not be passed in and will most likely lead to a crash. - + @@ -27332,81 +29158,81 @@ not be passed in and will most likely lead to a crash. Given a @leaf_type and a @root_type which is contained in its + filename="gobject/gtype.c" + line="3256">Given a @leaf_type and a @root_type which is contained in its ancestry, return the type that @root_type is the immediate parent of. In other words, this function determines the type that is derived directly from @root_type which is also a base class of @leaf_type. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type. - + immediate child of @root_type and ancestor of @leaf_type + filename="gobject/gtype.c" + line="3269">immediate child of @root_type and ancestor of @leaf_type descendant of @root_type and the type to be returned + filename="gobject/gtype.c" + line="3258">descendant of @root_type and the type to be returned immediate parent of the returned type + filename="gobject/gtype.c" + line="3259">immediate parent of the returned type Return the direct parent type of the passed in type. If the passed + filename="gobject/gtype.c" + line="3218">Return the direct parent type of the passed in type. If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. - + the parent type + filename="gobject/gtype.c" + line="3225">the parent type the derived type + filename="gobject/gtype.c" + line="3220">the derived type Get the corresponding quark of the type IDs name. - + filename="gobject/gtype.c" + line="3175">Get the corresponding quark of the type IDs name. + the type names quark or 0 + filename="gobject/gtype.c" + line="3181">the type names quark or 0 type to return quark of type name for + filename="gobject/gtype.c" + line="3177">type to return quark of type name for Queries the type system for information about a specific type. + filename="gobject/gtype.c" + line="3646">Queries the type system for information about a specific type. This function will fill in a user-provided structure to hold type-specific information. If an invalid #GType is passed in, the @@ -27416,15 +29242,15 @@ left untouched. Since GLib 2.78, this function allows queries on dynamic types. Previously it only supported static types. - + #GType of a static, classed type + filename="gobject/gtype.c" + line="3648">#GType of a static, classed type caller-allocates="1" transfer-ownership="none"> a user provided structure that is + filename="gobject/gtype.c" + line="3649">a user provided structure that is filled in with constant values upon success @@ -27442,42 +29268,42 @@ it only supported static types. Registers @type_name as the name of a new dynamic type derived from + filename="gobject/gtype.c" + line="2587">Registers @type_name as the name of a new dynamic type derived from @parent_type. The type system uses the information contained in the #GTypePlugin structure pointed to by @plugin to manage the type and its instances (if not abstract). The value of @flags determines the nature (e.g. abstract or not) of the type. - + the new type identifier or %G_TYPE_INVALID if registration failed + filename="gobject/gtype.c" + line="2600">the new type identifier or %G_TYPE_INVALID if registration failed type from which this type will be derived + filename="gobject/gtype.c" + line="2589">type from which this type will be derived 0-terminated string used as the name of the new type + filename="gobject/gtype.c" + line="2590">0-terminated string used as the name of the new type #GTypePlugin structure to retrieve the #GTypeInfo from + filename="gobject/gtype.c" + line="2591">#GTypePlugin structure to retrieve the #GTypeInfo from bitwise combination of #GTypeFlags values + filename="gobject/gtype.c" + line="2592">bitwise combination of #GTypeFlags values @@ -27485,51 +29311,51 @@ instances (if not abstract). The value of @flags determines the nature Registers @type_id as the predefined identifier and @type_name as the + filename="gobject/gtype.c" + line="2412">Registers @type_id as the predefined identifier and @type_name as the name of a fundamental type. If @type_id is already registered, or a type named @type_name is already registered, the behaviour is undefined. The type system uses the information contained in the #GTypeInfo structure pointed to by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to manage the type and its instances. The value of @flags determines additional characteristics of the fundamental type. - + the predefined type identifier + filename="gobject/gtype.c" + line="2428">the predefined type identifier a predefined type identifier + filename="gobject/gtype.c" + line="2414">a predefined type identifier 0-terminated string used as the name of the new type + filename="gobject/gtype.c" + line="2415">0-terminated string used as the name of the new type #GTypeInfo structure for this type + filename="gobject/gtype.c" + line="2416">#GTypeInfo structure for this type #GTypeFundamentalInfo structure for this type + filename="gobject/gtype.c" + line="2417">#GTypeFundamentalInfo structure for this type bitwise combination of #GTypeFlags values + filename="gobject/gtype.c" + line="2418">bitwise combination of #GTypeFlags values @@ -27537,42 +29363,42 @@ additional characteristics of the fundamental type. Registers @type_name as the name of a new static type derived from + filename="gobject/gtype.c" + line="2532">Registers @type_name as the name of a new static type derived from @parent_type. The type system uses the information contained in the #GTypeInfo structure pointed to by @info to manage the type and its instances (if not abstract). The value of @flags determines the nature (e.g. abstract or not) of the type. - + the new type identifier + filename="gobject/gtype.c" + line="2545">the new type identifier type from which this type will be derived + filename="gobject/gtype.c" + line="2534">type from which this type will be derived 0-terminated string used as the name of the new type + filename="gobject/gtype.c" + line="2535">0-terminated string used as the name of the new type #GTypeInfo structure for this type + filename="gobject/gtype.c" + line="2536">#GTypeInfo structure for this type bitwise combination of #GTypeFlags values + filename="gobject/gtype.c" + line="2537">bitwise combination of #GTypeFlags values @@ -27582,59 +29408,59 @@ instances (if not abstract). The value of @flags determines the nature version="2.12" introspectable="0"> Registers @type_name as the name of a new static type derived from + filename="gobject/gtype.c" + line="2482">Registers @type_name as the name of a new static type derived from @parent_type. The value of @flags determines the nature (e.g. abstract or not) of the type. It works by filling a #GTypeInfo struct and calling g_type_register_static(). - + the new type identifier + filename="gobject/gtype.c" + line="2499">the new type identifier type from which this type will be derived + filename="gobject/gtype.c" + line="2484">type from which this type will be derived 0-terminated string used as the name of the new type + filename="gobject/gtype.c" + line="2485">0-terminated string used as the name of the new type size of the class structure (see #GTypeInfo) + filename="gobject/gtype.c" + line="2486">size of the class structure (see #GTypeInfo) location of the class initialization function (see #GTypeInfo) + filename="gobject/gtype.c" + line="2487">location of the class initialization function (see #GTypeInfo) size of the instance structure (see #GTypeInfo) + filename="gobject/gtype.c" + line="2488">size of the instance structure (see #GTypeInfo) location of the instance initialization function (see #GTypeInfo) + filename="gobject/gtype.c" + line="2489">location of the instance initialization function (see #GTypeInfo) bitwise combination of #GTypeFlags values + filename="gobject/gtype.c" + line="2490">bitwise combination of #GTypeFlags values @@ -27643,11 +29469,11 @@ struct and calling g_type_register_static(). c:identifier="g_type_remove_class_cache_func" introspectable="0"> Removes a previously installed #GTypeClassCacheFunc. The cache + filename="gobject/gtype.c" + line="2299">Removes a previously installed #GTypeClassCacheFunc. The cache maintained by @cache_func has to be empty when calling g_type_remove_class_cache_func() to avoid leaks. - + @@ -27657,14 +29483,14 @@ g_type_remove_class_cache_func() to avoid leaks. nullable="1" allow-none="1"> data that was given when adding @cache_func + filename="gobject/gtype.c" + line="2301">data that was given when adding @cache_func a #GTypeClassCacheFunc + filename="gobject/gtype.c" + line="2302">a #GTypeClassCacheFunc @@ -27674,10 +29500,10 @@ g_type_remove_class_cache_func() to avoid leaks. version="2.4" introspectable="0"> Removes an interface check function added with + filename="gobject/gtype.c" + line="2372">Removes an interface check function added with g_type_add_interface_check(). - + @@ -27687,14 +29513,14 @@ g_type_add_interface_check(). nullable="1" allow-none="1"> callback data passed to g_type_add_interface_check() + filename="gobject/gtype.c" + line="2374">callback data passed to g_type_add_interface_check() callback function passed to g_type_add_interface_check() + filename="gobject/gtype.c" + line="2375">callback function passed to g_type_add_interface_check() @@ -27702,23 +29528,23 @@ g_type_add_interface_check(). Attaches arbitrary data to a type. - + filename="gobject/gtype.c" + line="3598">Attaches arbitrary data to a type. + a #GType + filename="gobject/gtype.c" + line="3600">a #GType a #GQuark id to identify the data + filename="gobject/gtype.c" + line="3601">a #GQuark id to identify the data nullable="1" allow-none="1"> the data + filename="gobject/gtype.c" + line="3602">the data - + @@ -27751,84 +29577,60 @@ g_type_add_interface_check(). moved-to="TypeValueTable.peek" introspectable="0"> Returns the location of the #GTypeValueTable associated with @type. + filename="gobject/gtype.c" + line="4101">Returns the location of the #GTypeValueTable associated with @type. Note that this function should only be used from source code that implements or has internal knowledge of the implementation of @type. - - + + location of the #GTypeValueTable associated with @type or - %NULL if there is no #GTypeValueTable associated with @type + filename="gobject/gtype.c" + line="4111">location of the #GTypeValueTable + associated with @type or %NULL if there is no #GTypeValueTable + associated with @type a #GType + filename="gobject/gtype.c" + line="4103">a #GType - - The prime purpose of a #GValueArray is for it to be used as an -object property that holds an array of values. A #GValueArray wraps -an array of #GValue elements in order for it to be used as a boxed -type through %G_TYPE_VALUE_ARRAY. - -#GValueArray is deprecated in favour of #GArray since GLib 2.32. It -is possible to create a #GArray that behaves like a #GValueArray by -using the size of #GValue as the element size, and by setting -g_value_unset() as the clear function using g_array_set_clear_func(), -for instance, the following code: - -|[<!-- language="C" --> - GValueArray *array = g_value_array_new (10); -]| - -can be replaced by: - -|[<!-- language="C" --> - GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); - g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); -]| - Registers a value transformation function for use in g_value_transform(). + filename="gobject/gvalue.c" + line="426">Registers a value transformation function for use in g_value_transform(). A previously registered transformation function for @src_type and @dest_type will be replaced. - + Source type. + filename="gobject/gvalue.c" + line="428">Source type. Target type. + filename="gobject/gvalue.c" + line="429">Target type. a function which transforms values of type @src_type + filename="gobject/gvalue.c" + line="430">a function which transforms values of type @src_type into value of type @dest_type @@ -27838,27 +29640,27 @@ will be replaced. c:identifier="g_value_type_compatible" moved-to="Value.type_compatible"> Returns whether a #GValue of type @src_type can be copied into + filename="gobject/gvalue.c" + line="488">Returns whether a #GValue of type @src_type can be copied into a #GValue of type @dest_type. - + %TRUE if g_value_copy() is possible with @src_type and @dest_type. + filename="gobject/gvalue.c" + line="496">%TRUE if g_value_copy() is possible with @src_type and @dest_type. source type to be copied. + filename="gobject/gvalue.c" + line="490">source type to be copied. destination type for copying. + filename="gobject/gvalue.c" + line="491">destination type for copying. @@ -27867,32 +29669,38 @@ a #GValue of type @dest_type. c:identifier="g_value_type_transformable" moved-to="Value.type_transformable"> Check whether g_value_transform() is able to transform values + filename="gobject/gvalue.c" + line="465">Check whether g_value_transform() is able to transform values of type @src_type into values of type @dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered. - + %TRUE if the transformation is possible, %FALSE otherwise. + filename="gobject/gvalue.c" + line="475">%TRUE if the transformation is possible, %FALSE otherwise. Source type. + filename="gobject/gvalue.c" + line="467">Source type. Target type. + filename="gobject/gvalue.c" + line="468">Target type. + + + + + + diff --git a/generator/src/main/resources/gir/Gdk-4.0.gir b/generator/src/main/resources/gir/Gdk-4.0.gir index f488ba7..13d3a22 100644 --- a/generator/src/main/resources/gir/Gdk-4.0.gir +++ b/generator/src/main/resources/gir/Gdk-4.0.gir @@ -21,11 +21,11 @@ and/or use gtk-doc annotations. --> Defines all possible DND actions. + line="294">Defines all possible DND actions. This can be used in [method@Gdk.Drop.status] messages when any drop can be accepted or a more specific drop method is not yet known. - + glib:get-type="gdk_app_launch_context_get_type"> `GdkAppLaunchContext` handles launching an application in a graphical context. + line="28">Handles launching an application in a graphical context. It is an implementation of `GAppLaunchContext` that provides startup notification and allows to launch applications on a specific workspace. @@ -170,7 +170,6 @@ g_object_unref (context); - Gets the `GdkDisplay` that @context is for. @@ -330,8 +329,6 @@ prevention'. construct-only="1" transfer-ownership="none" getter="get_display"> - The display that the `GdkAppLaunchContext` is on. @@ -344,7 +341,7 @@ prevention'. c:type="GdkAxisFlags"> Flags describing the current capabilities of a device/tool. + line="242">Flags describing the current capabilities of a device/tool. glib:name="GDK_AXIS_FLAG_X"> X axis is present + line="244">X axis is present glib:name="GDK_AXIS_FLAG_Y"> Y axis is present + line="245">Y axis is present glib:name="GDK_AXIS_FLAG_DELTA_X"> Scroll X delta axis is present + line="246">Scroll X delta axis is present glib:name="GDK_AXIS_FLAG_DELTA_Y"> Scroll Y delta axis is present + line="247">Scroll Y delta axis is present glib:name="GDK_AXIS_FLAG_PRESSURE"> Pressure axis is present + line="248">Pressure axis is present glib:name="GDK_AXIS_FLAG_XTILT"> X tilt axis is present + line="249">X tilt axis is present glib:name="GDK_AXIS_FLAG_YTILT"> Y tilt axis is present + line="250">Y tilt axis is present glib:name="GDK_AXIS_FLAG_WHEEL"> Wheel axis is present + line="251">Wheel axis is present glib:name="GDK_AXIS_FLAG_DISTANCE"> Distance axis is present + line="252">Distance axis is present glib:name="GDK_AXIS_FLAG_ROTATION"> Z-axis rotation is present + line="253">Z-axis rotation is present glib:name="GDK_AXIS_FLAG_SLIDER"> Slider axis is present + line="254">Slider axis is present c:type="GdkAxisUse"> Defines how device axes are interpreted by GTK. + line="203">Defines how device axes are interpreted by GTK. Note that the X and Y axes are not really needed; pointer devices report their location via the x/y members of events regardless. Whether @@ -463,7 +460,7 @@ X and Y are present as axes depends on the GDK backend. glib:name="GDK_AXIS_IGNORE"> the axis is ignored. + line="205">the axis is ignored. glib:name="GDK_AXIS_X"> the axis is used as the x axis. + line="206">the axis is used as the x axis. glib:name="GDK_AXIS_Y"> the axis is used as the y axis. + line="207">the axis is used as the y axis. glib:name="GDK_AXIS_DELTA_X"> the axis is used as the scroll x delta + line="208">the axis is used as the scroll x delta glib:name="GDK_AXIS_DELTA_Y"> the axis is used as the scroll y delta + line="209">the axis is used as the scroll y delta glib:name="GDK_AXIS_PRESSURE"> the axis is used for pressure information. + line="210">the axis is used for pressure information. glib:name="GDK_AXIS_XTILT"> the axis is used for x tilt information. + line="211">the axis is used for x tilt information. glib:name="GDK_AXIS_YTILT"> the axis is used for y tilt information. + line="212">the axis is used for y tilt information. glib:name="GDK_AXIS_WHEEL"> the axis is used for wheel information. + line="213">the axis is used for wheel information. glib:name="GDK_AXIS_DISTANCE"> the axis is used for pen/tablet distance information + line="214">the axis is used for pen/tablet distance information glib:name="GDK_AXIS_ROTATION"> the axis is used for pen rotation information + line="215">the axis is used for pen rotation information glib:name="GDK_AXIS_SLIDER"> the axis is used for pen slider information + line="216">the axis is used for pen slider information glib:name="GDK_AXIS_LAST"> a constant equal to the numerically highest axis value. + line="217">a constant equal to the numerically highest axis value. @@ -606,23 +603,23 @@ left button in a left-handed setup. glib:fundamental="1"> An event related to a button on a pointer device. + line="1400">An event related to a button on a pointer device. Extract the button number from a button event. - + line="1506">Extract the button number from a button event. + the button of @event + line="1512">the button of @event a button event + line="1508">a button event @@ -714,8 +711,7 @@ left button in a left-handed setup. glib:get-type="gdk_cairo_context_get_type"> `GdkCairoContext` is an object representing the platform-specific -draw context. + line="29">Represents the platform-specific draw context. `GdkCairoContext`s are created for a surface using [method@Gdk.Surface.create_cairo_context], and the context @@ -724,7 +720,7 @@ can then be used to draw on that surface. c:identifier="gdk_cairo_context_cairo_create"> Retrieves a Cairo context to be used to draw on the `GdkSurface` + line="58">Retrieves a Cairo context to be used to draw on the `GdkSurface` of @context. A call to [method@Gdk.DrawContext.begin_frame] with this @@ -736,7 +732,7 @@ The returned context is guaranteed to be valid until a Cairo context + line="71">a Cairo context to draw on `GdkSurface @@ -744,12 +740,396 @@ The returned context is guaranteed to be valid until a `GdkCairoContext` that is currently drawing + line="60">a `GdkCairoContext` that is currently drawing + + Contains the parameters that define a colorstate with cicp parameters. + +Cicp parameters are specified in the ITU-T H.273 +[specification](https://www.itu.int/rec/T-REC-H.273/en). + +See the documentation of individual properties for supported values. + +The 'unspecified' value (2) is not treated in any special way, and +must be replaced by a different value before creating a color state. + +`GdkCicpParams` can be used as a builder object to construct a color +state from Cicp data with [method@Gdk.CicpParams.build_color_state]. +The function will return an error if the given parameters are not +supported. + +You can obtain a `GdkCicpParams` object from a color state with +[method@Gdk.ColorState.create_cicp_params]. This can be used to +create a variant of a color state, by changing just one of the cicp +parameters, or just to obtain information about the color state. + + + Creates a new `GdkCicpParams` object. + +The initial values of the properties are the values for "undefined" +and need to be set before a color state object can be built. + + + a new `GdkCicpParams` + + + + + Creates a new `GdkColorState` object for the cicp parameters in @self. + +Note that this may fail if the cicp parameters in @self are not +supported by GTK. In that case, `NULL` is returned, and @error is set +with an error message that can be presented to the user. + + + A newly allocated `GdkColorState` + + + + + a `GdkCicpParams` + + + + + + Returns the value of the color-primaries property +of @self. + + + the color-primaries value + + + + + a `GdkCicpParams` + + + + + + Gets the matrix-coefficients property of @self. + + + the matrix-coefficients value + + + + + a `GdkCicpParams` + + + + + + Gets the range property of @self. + + + the range value + + + + + a `GdkCicpParams` + + + + + + Gets the transfer-function property of @self. + + + the transfer-function value + + + + + a `GdkCicpParams` + + + + + + Sets the color-primaries property of @self. + + + + + + + a `GdkCicpParams` + + + + the new color primaries value + + + + + + @self a `GdkCicpParams` +Sets the matrix-coefficients property of @self. + + + + + + + + + + the new matrix-coefficients value + + + + + + Sets the range property of @self + + + + + + + a `GdkCipParams` + + + + the range value + + + + + + Sets the transfer-function property of @self. + + + + + + + a `GdkCicpParams` + + + + the new transfer-function value + + + + + + The color primaries to use. + +Supported values: + +- 1: BT.709 / sRGB +- 2: unspecified +- 5: PAL +- 6,7: BT.601 / NTSC +- 9: BT.2020 +- 12: Display P3 + + + + The matrix coefficients (for YUV to RGB conversion). + +Supported values: + +- 0: RGB +- 2: unspecified + + + + Whether the data is using the full range of values. + +The range of the data. + + + + The transfer function to use. + +Supported values: + +- 1,6,14,15: BT.709, BT.601, BT.2020 +- 2: unspecified +- 4: gamma 2.2 +- 5: gamma 2.8 +- 8: linear +- 13: sRGB +- 16: BT.2100 PQ +- 18: BT.2100 HLG + + + + + + + + The values of this enumeration describe whether image data uses +the full range of 8-bit values. + +In digital broadcasting, it is common to reserve the lowest and +highest values. Typically the allowed values for the narrow range +are 16-235 for Y and 16-240 for u,v (when dealing with YUV data). + + The values use the range of 16-235 (for Y) and 16-240 for u and v. + + + The values use the full range. + + The `GdkClipboard` object represents data shared between applications or -inside an application. + line="36">Represents data shared between applications or inside an application. To get a `GdkClipboard` object, use [method@Gdk.Display.get_clipboard] or [method@Gdk.Display.get_primary_clipboard]. You can find out about the data @@ -778,10 +1157,9 @@ To read textual or image data from a clipboard, use - Returns the `GdkContentProvider` currently set on @clipboard. + line="490">Returns the `GdkContentProvider` currently set on @clipboard. If the @clipboard is empty or its contents are not owned by the current process, %NULL will be returned. @@ -789,7 +1167,7 @@ current process, %NULL will be returned. The content of a clipboard + line="499">The content of a clipboard if the clipboard does not maintain any content @@ -797,7 +1175,7 @@ current process, %NULL will be returned. a `GdkClipboard` + line="492">a `GdkClipboard` @@ -805,22 +1183,21 @@ current process, %NULL will be returned. - Gets the `GdkDisplay` that the clipboard was created for. + line="430">Gets the `GdkDisplay` that the clipboard was created for. a `GdkDisplay` + line="436">a `GdkDisplay` a `GdkClipboard` + line="432">a `GdkClipboard` @@ -828,31 +1205,31 @@ current process, %NULL will be returned. - Gets the formats that the clipboard can provide its current contents in. + line="448">Gets the formats that the clipboard can provide its current contents in. The formats of the clipboard + line="454">The formats of the clipboard a `GdkClipboard` + line="450">a `GdkClipboard` - - + Returns if the clipboard is local. + line="466">Returns if the clipboard is local. A clipboard is considered local if it was last claimed by the running application. @@ -863,27 +1240,26 @@ even on a local clipboard. In this case the clipboard is empty. %TRUE if the clipboard is local + line="478">%TRUE if the clipboard is local a `GdkClipboard` + line="468">a `GdkClipboard` - + Asynchronously requests an input stream to read the @clipboard's + line="626">Asynchronously requests an input stream to read the @clipboard's contents from. -When the operation is finished @callback will be called. You must then -call [method@Gdk.Clipboard.read_finish] to get the result of the operation. - The clipboard will choose the most suitable mime type from the given list to fulfill the request, preferring the ones listed first. @@ -894,13 +1270,13 @@ to fulfill the request, preferring the ones listed first. a `GdkClipboard` + line="628">a `GdkClipboard` a %NULL-terminated array of mime types to choose from + line="629">a %NULL-terminated array of mime types to choose from @@ -908,7 +1284,7 @@ to fulfill the request, preferring the ones listed first. the I/O priority of the request + line="630">the I/O priority of the request allow-none="1"> optional `GCancellable` object + line="631">optional `GCancellable` object closure="4"> callback to call when the request is satisfied + line="632">callback to call when the request is satisfied allow-none="1"> the data to pass to callback function + line="633">the data to pass to callback function @@ -947,27 +1323,27 @@ to fulfill the request, preferring the ones listed first. throws="1"> Finishes an asynchronous clipboard read. + line="663">Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_async]. a `GInputStream` + line="675">a `GInputStream` a `GdkClipboard` + line="665">a `GdkClipboard` a `GAsyncResult` + line="666">a `GAsyncResult` allow-none="1"> location to store + line="667">location to store the chosen mime type + c:identifier="gdk_clipboard_read_text_async" + glib:finish-func="read_text_finish"> Asynchronously request the @clipboard contents converted to a string. - -When the operation is finished @callback will be called. You must then -call [method@Gdk.Clipboard.read_text_finish] to get the result. + line="942">Asynchronously request the @clipboard contents converted to a string. This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. Use that function or [method@Gdk.Clipboard.read_async] directly if you @@ -1004,7 +1378,7 @@ need more control over the operation. a `GdkClipboard` + line="944">a `GdkClipboard` allow-none="1"> optional `GCancellable` object + line="945">optional `GCancellable` object closure="2"> callback to call when the request is satisfied + line="946">callback to call when the request is satisfied allow-none="1"> the data to pass to callback function + line="947">the data to pass to callback function @@ -1043,39 +1417,37 @@ need more control over the operation. throws="1"> Finishes an asynchronous clipboard read. + line="974">Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_text_async]. a new string + line="984">a new string a `GdkClipboard` + line="976">a `GdkClipboard` a `GAsyncResult` + line="977">a `GAsyncResult` + c:identifier="gdk_clipboard_read_texture_async" + glib:finish-func="read_texture_finish"> Asynchronously request the @clipboard contents converted to a `GdkPixbuf`. - -When the operation is finished @callback will be called. You must then -call [method@Gdk.Clipboard.read_texture_finish] to get the result. + line="880">Asynchronously request the @clipboard contents converted to a `GdkPixbuf`. This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. Use that function or [method@Gdk.Clipboard.read_async] directly if you @@ -1088,7 +1460,7 @@ need more control over the operation. a `GdkClipboard` + line="882">a `GdkClipboard` allow-none="1"> optional `GCancellable` object, %NULL to ignore. + line="883">optional `GCancellable` object, %NULL to ignore. closure="2"> callback to call when the request is satisfied + line="884">callback to call when the request is satisfied allow-none="1"> the data to pass to callback function + line="885">the data to pass to callback function @@ -1127,41 +1499,39 @@ need more control over the operation. throws="1"> Finishes an asynchronous clipboard read. + line="912">Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_texture_async]. a new `GdkTexture` + line="922">a new `GdkTexture` a `GdkClipboard` + line="914">a `GdkClipboard` a `GAsyncResult` + line="915">a `GAsyncResult` + c:identifier="gdk_clipboard_read_value_async" + glib:finish-func="read_value_finish"> Asynchronously request the @clipboard contents converted to the given + line="819">Asynchronously request the @clipboard contents converted to the given @type. -When the operation is finished @callback will be called. You must then call -[method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`. - For local clipboard contents that are available in the given `GType`, the value will be copied directly. Otherwise, GDK will try to use [func@content_deserialize_async] to convert the clipboard's data. @@ -1173,19 +1543,19 @@ the value will be copied directly. Otherwise, GDK will try to use a `GdkClipboard` + line="821">a `GdkClipboard` a `GType` to read + line="822">a `GType` to read the I/O priority of the request + line="823">the I/O priority of the request optional `GCancellable` object + line="824">optional `GCancellable` object callback to call when the request is satisfied + line="825">callback to call when the request is satisfied the data to pass to callback function + line="826">the data to pass to callback function @@ -1224,27 +1594,27 @@ the value will be copied directly. Otherwise, GDK will try to use throws="1"> Finishes an asynchronous clipboard read. + line="856">Finishes an asynchronous clipboard read. See [method@Gdk.Clipboard.read_value_async]. a `GValue` containing the result. + line="866">a `GValue` containing the result. a `GdkClipboard` + line="858">a `GdkClipboard` a `GAsyncResult` + line="859">a `GAsyncResult` @@ -1255,11 +1625,11 @@ See [method@Gdk.Clipboard.read_value_async]. introspectable="0"> Sets the clipboard to contain the value collected from the given varargs. + line="1228">Sets the clipboard to contain the value collected from the given varargs. Values should be passed the same way they are passed to other value -collecting APIs, such as [`method@GObject.Object.set`] or -[`func@GObject.signal_emit`]. +collecting APIs, such as [method@GObject.Object.set] or +[func@GObject.signal_emit]. ```c gdk_clipboard_set (clipboard, GTK_TYPE_STRING, "Hello World"); @@ -1274,19 +1644,19 @@ gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, some_texture); a `GdkClipboard` + line="1230">a `GdkClipboard` type of value to set + line="1231">type of value to set value contents conforming to @type + line="1232">value contents conforming to @type @@ -1294,7 +1664,7 @@ gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, some_texture); Sets a new content provider on @clipboard. + line="1173">Sets a new content provider on @clipboard. The clipboard will claim the `GdkDisplay`'s resources and advertise these new contents to other applications. @@ -1310,14 +1680,14 @@ transfer the contents and then request that format from @provider. %TRUE if setting the clipboard succeeded + line="1192">%TRUE if setting the clipboard succeeded a `GdkClipboard` + line="1175">a `GdkClipboard` allow-none="1"> the new contents of @clipboard + line="1176">the new contents of @clipboard or %NULL to clear the clipboard @@ -1337,7 +1707,7 @@ transfer the contents and then request that format from @provider. introspectable="0"> Puts the given @text into the clipboard. + line="1317">Puts the given @text into the clipboard. @@ -1346,13 +1716,13 @@ transfer the contents and then request that format from @provider. a `GdkClipboard` + line="1319">a `GdkClipboard` Text to put into the clipboard + line="1320">Text to put into the clipboard @@ -1362,7 +1732,7 @@ transfer the contents and then request that format from @provider. introspectable="0"> Puts the given @texture into the clipboard. + line="1333">Puts the given @texture into the clipboard. @@ -1371,13 +1741,13 @@ transfer the contents and then request that format from @provider. a `GdkClipboard` + line="1335">a `GdkClipboard` a `GdkTexture` to put into the clipboard + line="1336">a `GdkTexture` to put into the clipboard @@ -1387,7 +1757,7 @@ transfer the contents and then request that format from @provider. introspectable="0"> Sets the clipboard to contain the value collected from the given @args. + line="1260">Sets the clipboard to contain the value collected from the given @args. @@ -1396,19 +1766,19 @@ transfer the contents and then request that format from @provider. a `GdkClipboard` + line="1262">a `GdkClipboard` type of value to set + line="1263">type of value to set varargs containing the value of @type + line="1264">varargs containing the value of @type @@ -1418,7 +1788,7 @@ transfer the contents and then request that format from @provider. shadows="set"> Sets the @clipboard to contain the given @value. + line="1295">Sets the @clipboard to contain the given @value. @@ -1427,26 +1797,26 @@ transfer the contents and then request that format from @provider. a `GdkClipboard` + line="1297">a `GdkClipboard` a `GValue` to set + line="1298">a `GValue` to set - + Asynchronously instructs the @clipboard to store its contents remotely. + line="512">Asynchronously instructs the @clipboard to store its contents remotely. If the clipboard is not local, this function does nothing but report success. -The @callback must call [method@Gdk.Clipboard.store_finish]. - The purpose of this call is to preserve clipboard contents beyond the lifetime of an application, so this function is typically called on exit. Depending on the platform, the functionality may not be available @@ -1463,13 +1833,13 @@ is shut down, so you likely don't need to call it. a `GdkClipboard` + line="514">a `GdkClipboard` the I/O priority of the request + line="515">the I/O priority of the request allow-none="1"> optional `GCancellable` object + line="516">optional `GCancellable` object closure="3"> callback to call when the request is satisfied + line="517">callback to call when the request is satisfied allow-none="1"> the data to pass to callback function + line="518">the data to pass to callback function @@ -1508,37 +1878,35 @@ is shut down, so you likely don't need to call it. throws="1"> Finishes an asynchronous clipboard store. + line="564">Finishes an asynchronous clipboard store. See [method@Gdk.Clipboard.store_async]. %TRUE if storing was successful. + line="574">%TRUE if storing was successful. a `GdkClipboard` + line="566">a `GdkClipboard` a `GAsyncResult` + line="567">a `GAsyncResult` - The `GdkContentProvider` or %NULL if the clipboard is empty or contents are + line="391">The `GdkContentProvider` or %NULL if the clipboard is empty or contents are provided otherwise. @@ -1547,185 +1915,418 @@ provided otherwise. construct-only="1" transfer-ownership="none" getter="get_display"> - The `GdkDisplay` that the clipboard belongs to. + line="354">The `GdkDisplay` that the clipboard belongs to. - The possible formats that the clipboard can provide its data in. + line="367">The possible formats that the clipboard can provide its data in. - - + %TRUE if the contents of the clipboard are owned by this process. + line="379">%TRUE if the contents of the clipboard are owned by this process. Emitted when the clipboard changes ownership. + line="404">Emitted when the clipboard changes ownership. - - The type of a function that can be registered with gdk_content_register_deserializer(). - -When the function gets called to operate on content, it can call functions on the -@deserializer object to obtain the mime type, input stream, user data, etc. for its -operation. - - - - - - - a `GdkContentDeserializer` - - - - - + A `GdkContentDeserializer` is used to deserialize content received via -inter-application data transfers. + filename="gdk/gdkcolorstate.c" + line="29">Provides information to interpret colors and pixels in a variety of ways. -The `GdkContentDeserializer` transforms serialized content that is -identified by a mime type into an object identified by a GType. +They are also known as +[*color spaces*](https://en.wikipedia.org/wiki/Color_space). -GTK provides serializers and deserializers for common data types -such as text, colors, images or file lists. To register your own -deserialization functions, use [func@content_register_deserializer]. +Crucially, GTK knows how to convert colors from one color +state to another. -Also see [class@Gdk.ContentSerializer]. - - +`GdkColorState` objects are immutable and therefore threadsafe. + + Gets the cancellable for the current operation. + filename="gdk/gdkcolorstate.c" + line="231">Create a [class@Gdk.CicpParams] representing the colorstate. -This is the `GCancellable` that was passed to [func@Gdk.content_deserialize_async]. - - +It is not guaranteed that every `GdkColorState` can be +represented with Cicp parameters. If that is the case, +this function returns `NULL`. + + the cancellable for the current operation - + filename="gdk/gdkcolorstate.c" + line="241">A new [class@Gdk.CicpParams] + - + a `GdkContentDeserializer` - + filename="gdk/gdkcolorstate.c" + line="233">a `GdkColorState` + - + Gets the `GType` to create an instance of. - + filename="gdk/gdkcolorstate.c" + line="209">Compares two `GdkColorStates` for equality. + +Note that this function is not guaranteed to be perfect and two objects +describing the same color state may compare not equal. However, different +color states will never compare equal. + the `GType` for the current operation - + filename="gdk/gdkcolorstate.c" + line="220">%TRUE if the two color states compare equal + - + a `GdkContentDeserializer` - + filename="gdk/gdkcolorstate.c" + line="211">a `GdkColorState` + + + another `GdkColorStatee` + + - + Gets the input stream for the current operation. - -This is the stream that was passed to [func@Gdk.content_deserialize_async]. - - + filename="gdk/gdkcolorstate.c" + line="50">Increase the reference count of @self. + + the input stream for the current operation - + filename="gdk/gdkcolorstate.c" + line="56">the object that was passed in + - + a `GdkContentDeserializer` - + filename="gdk/gdkcolorstate.c" + line="52">a `GdkColorState` + - + Gets the mime type to deserialize from. - + filename="gdk/gdkcolorstate.c" + line="66">Decrease the reference count of @self. + +Unless @self is static, it will be freed +when the reference count reaches zero. + - the mime type for the current operation - + - + a `GdkContentDeserializer` - + filename="gdk/gdkcolorstate.c" + line="68">a `GdkColorState` + - + Gets the I/O priority for the current operation. + filename="gdk/gdkcolorstate.c" + line="174">Returns the color state object representing the oklab color space. + +This is a perceptually uniform color state. + + + the color state object for oklab + + + + + Returns the color state object representing the oklch color space. + +This is the polar variant of oklab, in which the hue is encoded as +a polar coordinate. + + + the color state object for oklch + + + + + Returns the color state object representing the linear rec2100 color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear +transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear) +for details about this colorstate. + + + the color state object for linearized rec2100 + + + + + Returns the color state object representing the rec2100-pq color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer +function defined by SMPTE ST 2084 and BT.2100-2. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq) +for details about this colorstate. + + + the color state object for rec2100-pq + + + + + Returns the color state object representing the sRGB color space. + +This color state uses the primaries defined by BT.709-6 and the transfer function +defined by IEC 61966-2-1. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB) +for details about this colorstate. + + + the color state object for sRGB + + + + + Returns the color state object representing the linearized sRGB color space. + +This color state uses the primaries defined by BT.709-6 and a linear transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear) +for details about this colorstate. + + + the color state object for linearized sRGB + + + + + + The type of a function that can be registered with gdk_content_register_deserializer(). + +When the function gets called to operate on content, it can call functions on the +@deserializer object to obtain the mime type, input stream, user data, etc. for its +operation. + + + + + + + a `GdkContentDeserializer` + + + + + + Deserializes content received via inter-application data transfers. + +The `GdkContentDeserializer` transforms serialized content that is +identified by a mime type into an object identified by a GType. + +GTK provides serializers and deserializers for common data types +such as text, colors, images or file lists. To register your own +deserialization functions, use [func@content_register_deserializer]. + +Also see [class@Gdk.ContentSerializer]. + + + Gets the cancellable for the current operation. + +This is the `GCancellable` that was passed to [func@Gdk.content_deserialize_async]. + + + the cancellable for the current operation + + + + + a `GdkContentDeserializer` + + + + + + Gets the `GType` to create an instance of. + + + the `GType` for the current operation + + + + + a `GdkContentDeserializer` + + + + + + Gets the input stream for the current operation. + +This is the stream that was passed to [func@Gdk.content_deserialize_async]. + + + the input stream for the current operation + + + + + a `GdkContentDeserializer` + + + + + + Gets the mime type to deserialize from. + + + the mime type for the current operation + + + + + a `GdkContentDeserializer` + + + + + + Gets the I/O priority for the current operation. This is the priority that was passed to [func@Gdk.content_deserialize_async]. the I/O priority for the current operation + line="249">the I/O priority for the current operation a `GdkContentDeserializer` + line="243">a `GdkContentDeserializer` @@ -1734,21 +2335,21 @@ This is the priority that was passed to [func@Gdk.content_deserialize_async]. Gets the data that was associated with the current operation. + line="315">Gets the data that was associated with the current operation. See [method@Gdk.ContentDeserializer.set_task_data]. the task data for @deserializer + line="323">the task data for @deserializer a `GdkContentDeserializer` + line="317">a `GdkContentDeserializer` @@ -1757,19 +2358,19 @@ See [method@Gdk.ContentDeserializer.set_task_data]. c:identifier="gdk_content_deserializer_get_user_data"> Gets the user data that was passed when the deserializer was registered. + line="277">Gets the user data that was passed when the deserializer was registered. the user data for this deserializer + line="283">the user data for this deserializer a `GdkContentDeserializer` + line="279">a `GdkContentDeserializer` @@ -1778,19 +2379,19 @@ See [method@Gdk.ContentDeserializer.set_task_data]. c:identifier="gdk_content_deserializer_get_value"> Gets the `GValue` to store the deserialized object in. + line="207">Gets the `GValue` to store the deserialized object in. the `GValue` for the current operation + line="213">the `GValue` for the current operation a `GdkContentDeserializer` + line="209">a `GdkContentDeserializer` @@ -1799,7 +2400,7 @@ See [method@Gdk.ContentDeserializer.set_task_data]. c:identifier="gdk_content_deserializer_return_error"> Indicate that the deserialization has ended with an error. + line="368">Indicate that the deserialization has ended with an error. This function consumes @error. @@ -1810,13 +2411,13 @@ This function consumes @error. a `GdkContentDeserializer` + line="370">a `GdkContentDeserializer` a `GError` + line="371">a `GError` @@ -1825,7 +2426,7 @@ This function consumes @error. c:identifier="gdk_content_deserializer_return_success"> Indicate that the deserialization has been successfully completed. + line="346">Indicate that the deserialization has been successfully completed. @@ -1834,7 +2435,7 @@ This function consumes @error. a `GdkContentDeserializer` + line="348">a `GdkContentDeserializer` @@ -1843,7 +2444,7 @@ This function consumes @error. c:identifier="gdk_content_deserializer_set_task_data"> Associate data with the current deserialization operation. + line="293">Associate data with the current deserialization operation. @@ -1852,7 +2453,7 @@ This function consumes @error. a `GdkContentDeserializer` + line="295">a `GdkContentDeserializer` allow-none="1"> data to associate with this operation + line="296">data to associate with this operation destroy notify for @data + line="297">destroy notify for @data @@ -1881,8 +2482,7 @@ This function consumes @error. c:symbol-prefix="content_formats"> The `GdkContentFormats` structure is used to advertise and negotiate the -format of content. + line="18">Used to advertise and negotiate the format of content. You will encounter `GdkContentFormats` when interacting with objects controlling operations that pass data between different widgets, window @@ -1913,11 +2513,11 @@ to least important. the types it represents. Instead, new `GdkContentFormats` have to be created. The [struct@Gdk.ContentFormatsBuilder] structure is meant to help in this endeavor. - + Creates a new `GdkContentFormats` from an array of mime types. + line="131">Creates a new `GdkContentFormats` from an array of mime types. The mime types must be valid and different from each other or the behavior of the return value is undefined. If you cannot guarantee @@ -1926,7 +2526,7 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. the new `GdkContentFormats`. + line="143">the new `GdkContentFormats`. @@ -1936,7 +2536,7 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. allow-none="1"> Pointer to an + line="133">Pointer to an array of mime types @@ -1945,7 +2545,7 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. number of entries in @mime_types. + line="135">number of entries in @mime_types. @@ -1954,19 +2554,19 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. c:identifier="gdk_content_formats_new_for_gtype"> Creates a new `GdkContentFormats` for a given `GType`. + line="165">Creates a new `GdkContentFormats` for a given `GType`. a new `GdkContentFormats` + line="171">a new `GdkContentFormats` a `GType` + line="167">a `GType` @@ -1975,25 +2575,25 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. c:identifier="gdk_content_formats_contain_gtype"> Checks if a given `GType` is part of the given @formats. + line="480">Checks if a given `GType` is part of the given @formats. %TRUE if the `GType` was found + line="487">%TRUE if the `GType` was found a `GdkContentFormats` + line="482">a `GdkContentFormats` the `GType` to search for + line="483">the `GType` to search for @@ -2002,25 +2602,25 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. c:identifier="gdk_content_formats_contain_mime_type"> Checks if a given mime type is part of the given @formats. + line="506">Checks if a given mime type is part of the given @formats. %TRUE if the mime_type was found + line="513">%TRUE if the mime_type was found a `GdkContentFormats` + line="508">a `GdkContentFormats` the mime type to search for + line="509">the mime type to search for @@ -2028,7 +2628,7 @@ this, use [struct@Gdk.ContentFormatsBuilder] instead. Gets the `GType`s included in @formats. + line="526">Gets the `GType`s included in @formats. Note that @formats may not contain any `GType`s, in particular when they are empty. In that case %NULL will be returned. @@ -2036,7 +2636,7 @@ they are empty. In that case %NULL will be returned. + line="537"> %G_TYPE_INVALID-terminated array of types included in @formats @@ -2046,7 +2646,7 @@ they are empty. In that case %NULL will be returned. a `GdkContentFormats` + line="528">a `GdkContentFormats` allow-none="1"> optional pointer to take the + line="529">optional pointer to take the number of `GType`s contained in the return value @@ -2067,7 +2667,7 @@ they are empty. In that case %NULL will be returned. c:identifier="gdk_content_formats_get_mime_types"> Gets the mime types included in @formats. + line="552">Gets the mime types included in @formats. Note that @formats may not contain any mime types, in particular when they are empty. In that case %NULL will be returned. @@ -2075,7 +2675,7 @@ when they are empty. In that case %NULL will be returned. + line="563"> %NULL-terminated array of interned strings of mime types included in @formats @@ -2086,7 +2686,7 @@ when they are empty. In that case %NULL will be returned. a `GdkContentFormats` + line="554">a `GdkContentFormats` allow-none="1"> optional pointer to take the + line="555">optional pointer to take the number of mime types contained in the return value + + Returns whether the content formats contain any formats. + + + true if @formats contains no mime types and no GTypes + + + + + content formats + + + + Checks if @first and @second have any matching formats. + line="400">Checks if @first and @second have any matching formats. %TRUE if a matching format was found. + line="407">%TRUE if a matching format was found. the primary `GdkContentFormats` to intersect + line="402">the primary `GdkContentFormats` to intersect the `GdkContentFormats` to intersect with + line="403">the `GdkContentFormats` to intersect with @@ -2133,7 +2755,7 @@ when they are empty. In that case %NULL will be returned. c:identifier="gdk_content_formats_match_gtype"> Finds the first `GType` from @first that is also contained + line="420">Finds the first `GType` from @first that is also contained in @second. If no matching `GType` is found, %G_TYPE_INVALID is returned. @@ -2141,20 +2763,20 @@ If no matching `GType` is found, %G_TYPE_INVALID is returned. The first common `GType` or %G_TYPE_INVALID if none. + line="430">The first common `GType` or %G_TYPE_INVALID if none. the primary `GdkContentFormats` to intersect + line="422">the primary `GdkContentFormats` to intersect the `GdkContentFormats` to intersect with + line="423">the `GdkContentFormats` to intersect with @@ -2163,7 +2785,7 @@ If no matching `GType` is found, %G_TYPE_INVALID is returned. c:identifier="gdk_content_formats_match_mime_type"> Finds the first mime type from @first that is also contained + line="450">Finds the first mime type from @first that is also contained in @second. If no matching mime type is found, %NULL is returned. @@ -2171,20 +2793,20 @@ If no matching mime type is found, %NULL is returned. The first common mime type or %NULL if none + line="460">The first common mime type or %NULL if none the primary `GdkContentFormats` to intersect + line="452">the primary `GdkContentFormats` to intersect the `GdkContentFormats` to intersect with + line="453">the `GdkContentFormats` to intersect with @@ -2192,7 +2814,7 @@ If no matching mime type is found, %NULL is returned. Prints the given @formats into a string for human consumption. + line="298">Prints the given @formats into a string for human consumption. The result of this function can later be parsed with [func@Gdk.ContentFormats.parse]. @@ -2204,13 +2826,13 @@ The result of this function can later be parsed with a `GdkContentFormats` + line="300">a `GdkContentFormats` a `GString` to print into + line="301">a `GString` to print into @@ -2218,19 +2840,19 @@ The result of this function can later be parsed with Increases the reference count of a `GdkContentFormats` by one. + line="257">Increases the reference count of a `GdkContentFormats` by one. the passed in `GdkContentFormats`. + line="263">the passed in `GdkContentFormats`. a `GdkContentFormats` + line="259">a `GdkContentFormats` @@ -2238,7 +2860,7 @@ The result of this function can later be parsed with Prints the given @formats into a human-readable string. + line="331">Prints the given @formats into a human-readable string. The resulting string can be parsed with [func@Gdk.ContentFormats.parse]. @@ -2248,14 +2870,14 @@ to help when debugging. a new string + line="342">a new string a `GdkContentFormats` + line="333">a `GdkContentFormats` @@ -2263,26 +2885,26 @@ to help when debugging. Append all missing types from @second to @first, in the order + line="357">Append all missing types from @second to @first, in the order they had in @second. a new `GdkContentFormats` + line="365">a new `GdkContentFormats` the `GdkContentFormats` to merge into + line="359">the `GdkContentFormats` to merge into the `GdkContentFormats` to merge from + line="360">the `GdkContentFormats` to merge from @@ -2291,20 +2913,20 @@ they had in @second. c:identifier="gdk_content_formats_union_deserialize_gtypes"> Add GTypes for mime types in @formats for which deserializers are + line="447">Add GTypes for mime types in @formats for which deserializers are registered. a new `GdkContentFormats` + line="454">a new `GdkContentFormats` a `GdkContentFormats` + line="449">a `GdkContentFormats` @@ -2313,20 +2935,20 @@ registered. c:identifier="gdk_content_formats_union_deserialize_mime_types"> Add mime types for GTypes in @formats for which deserializers are + line="485">Add mime types for GTypes in @formats for which deserializers are registered. a new `GdkContentFormats` + line="492">a new `GdkContentFormats` a `GdkContentFormats` + line="487">a `GdkContentFormats` @@ -2335,20 +2957,20 @@ registered. c:identifier="gdk_content_formats_union_serialize_gtypes"> Add GTypes for the mime types in @formats for which serializers are + line="453">Add GTypes for the mime types in @formats for which serializers are registered. a new `GdkContentFormats` + line="460">a new `GdkContentFormats` a `GdkContentFormats` + line="455">a `GdkContentFormats` @@ -2357,20 +2979,20 @@ registered. c:identifier="gdk_content_formats_union_serialize_mime_types"> Add mime types for GTypes in @formats for which serializers are + line="488">Add mime types for GTypes in @formats for which serializers are registered. a new `GdkContentFormats` + line="495">a new `GdkContentFormats` a `GdkContentFormats` + line="490">a `GdkContentFormats` @@ -2378,7 +3000,7 @@ registered. Decreases the reference count of a `GdkContentFormats` by one. + line="275">Decreases the reference count of a `GdkContentFormats` by one. If the resulting reference count is zero, frees the formats. @@ -2389,7 +3011,7 @@ If the resulting reference count is zero, frees the formats. a `GdkContentFormats` + line="277">a `GdkContentFormats` @@ -2399,7 +3021,7 @@ If the resulting reference count is zero, frees the formats. version="4.4"> Parses the given @string into `GdkContentFormats` and + line="187">Parses the given @string into `GdkContentFormats` and returns the formats. Strings printed via [method@Gdk.ContentFormats.to_string] @@ -2411,14 +3033,14 @@ is returned. the content formats if @string is valid + line="200">the content formats if @string is valid the string to parse + line="189">the string to parse @@ -2432,21 +3054,20 @@ is returned. c:symbol-prefix="content_formats_builder"> A `GdkContentFormatsBuilder` is an auxiliary struct used to create -new `GdkContentFormats`, and should not be kept around. - + line="54">Creates `GdkContentFormats` objects. + Create a new `GdkContentFormatsBuilder` object. + line="622">Create a new `GdkContentFormatsBuilder` object. The resulting builder would create an empty `GdkContentFormats`. Use addition functions to add types to it. - + a new `GdkContentFormatsBuilder` + line="630">a new `GdkContentFormatsBuilder` @@ -2455,9 +3076,9 @@ Use addition functions to add types to it. c:identifier="gdk_content_formats_builder_add_formats"> Appends all formats from @formats to @builder, skipping those that + line="783">Appends all formats from @formats to @builder, skipping those that already exist. - + @@ -2465,14 +3086,14 @@ already exist. a `GdkContentFormatsBuilder` + line="785">a `GdkContentFormatsBuilder` the formats to add + line="786">the formats to add @@ -2481,8 +3102,8 @@ already exist. c:identifier="gdk_content_formats_builder_add_gtype"> Appends @type to @builder if it has not already been added. - + line="807">Appends @type to @builder if it has not already been added. + @@ -2490,14 +3111,14 @@ already exist. a `GdkContentFormats`Builder + line="809">a `GdkContentFormats`Builder a `GType` + line="810">a `GType` @@ -2506,8 +3127,8 @@ already exist. c:identifier="gdk_content_formats_builder_add_mime_type"> Appends @mime_type to @builder if it has not already been added. - + line="828">Appends @mime_type to @builder if it has not already been added. + @@ -2515,14 +3136,14 @@ already exist. a `GdkContentFormatsBuilder` + line="830">a `GdkContentFormatsBuilder` a mime type + line="831">a mime type @@ -2532,13 +3153,13 @@ already exist. introspectable="0"> Creates a new `GdkContentFormats` from the current state of the + line="697">Creates a new `GdkContentFormats` from the current state of the given @builder, and frees the @builder instance. - + the newly created `GdkContentFormats` + line="704">the newly created `GdkContentFormats` with all the formats added to @builder @@ -2546,7 +3167,7 @@ given @builder, and frees the @builder instance. a `GdkContentFormatsBuilder` + line="699">a `GdkContentFormatsBuilder` @@ -2555,15 +3176,15 @@ given @builder, and frees the @builder instance. Acquires a reference on the given @builder. + line="643">Acquires a reference on the given @builder. This function is intended primarily for bindings. `GdkContentFormatsBuilder` objects should not be kept around. - + the given `GdkContentFormatsBuilder` + line="652">the given `GdkContentFormatsBuilder` with its reference count increased @@ -2572,7 +3193,7 @@ This function is intended primarily for bindings. a `GdkContentFormatsBuilder` + line="645">a `GdkContentFormatsBuilder` @@ -2582,18 +3203,18 @@ This function is intended primarily for bindings. c:identifier="gdk_content_formats_builder_to_formats"> Creates a new `GdkContentFormats` from the given @builder. + line="721">Creates a new `GdkContentFormats` from the given @builder. The given `GdkContentFormatsBuilder` is reset once this function returns; you cannot call this function multiple times on the same @builder instance. This function is intended primarily for bindings. C code should use [method@Gdk.ContentFormatsBuilder.free_to_formats]. - + the newly created `GdkContentFormats` + line="733">the newly created `GdkContentFormats` with all the formats added to @builder @@ -2601,7 +3222,7 @@ This function is intended primarily for bindings. C code should use a `GdkContentFormats`Builder + line="723">a `GdkContentFormats`Builder @@ -2610,8 +3231,8 @@ This function is intended primarily for bindings. C code should use Releases a reference on the given @builder. - + line="676">Releases a reference on the given @builder. + @@ -2619,7 +3240,7 @@ This function is intended primarily for bindings. C code should use a `GdkContentFormatsBuilder` + line="678">a `GdkContentFormatsBuilder` @@ -2635,8 +3256,8 @@ This function is intended primarily for bindings. C code should use glib:type-struct="ContentProviderClass"> A `GdkContentProvider` is used to provide content for the clipboard or -for drag-and-drop operations in a number of formats. + line="28">Provides content for the clipboard or for drag-and-drop operations +in a number of formats. To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value] or [ctor@Gdk.ContentProvider.new_for_bytes]. @@ -2742,7 +3363,7 @@ contents with a call such as ```c gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), - gdk_content_provider_new_typed (G_TYPE_TEXTURE, texture) + gdk_content_provider_new_typed (GDK_TYPE_TEXTURE, texture) }, 2); ``` @@ -2823,7 +3444,7 @@ gdk_content_provider_new_union ((GdkContentProvider *[2]) { Gets the contents of @provider stored in @value. + line="335">Gets the contents of @provider stored in @value. The @value will have been initialized to the `GType` the value should be provided in. This given `GType` does not need to be listed in the formats @@ -2834,7 +3455,7 @@ given `GType` is not supported, this operation can fail and %TRUE if the value was set successfully. Otherwise + line="349">%TRUE if the value was set successfully. Otherwise @error will be set to describe the failure. @@ -2842,7 +3463,7 @@ given `GType` is not supported, this operation can fail and a `GdkContentProvider` + line="337">a `GdkContentProvider` the `GValue` to fill + line="338">the `GValue` to fill - Gets the formats that the provider can provide its current contents in. @@ -2879,8 +3499,6 @@ given `GType` is not supported, this operation can fail and - Gets the formats that the provider suggests other applications to store @@ -2906,16 +3524,13 @@ This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].< + invoker="write_mime_type_async" + glib:finish-func="write_mime_type_finish"> Asynchronously writes the contents of @provider to @stream in the given @mime_type. -When the operation is finished @callback will be called. You must then call -[method@Gdk.ContentProvider.write_mime_type_finish] to get the result -of the operation. - The given mime type does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported. @@ -2987,14 +3602,14 @@ The given @stream will not be closed. throws="1"> Finishes an asynchronous write operation. + line="311">Finishes an asynchronous write operation. See [method@Gdk.ContentProvider.write_mime_type_async]. %TRUE if the operation was completed successfully. Otherwise + line="321">%TRUE if the operation was completed successfully. Otherwise @error will be set to describe the failure. @@ -3002,13 +3617,13 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. a `GdkContentProvider` + line="313">a `GdkContentProvider` a `GAsyncResult` + line="314">a `GAsyncResult` @@ -3036,7 +3651,7 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. throws="1"> Gets the contents of @provider stored in @value. + line="335">Gets the contents of @provider stored in @value. The @value will have been initialized to the `GType` the value should be provided in. This given `GType` does not need to be listed in the formats @@ -3047,7 +3662,7 @@ given `GType` is not supported, this operation can fail and %TRUE if the value was set successfully. Otherwise + line="349">%TRUE if the value was set successfully. Otherwise @error will be set to describe the failure. @@ -3055,7 +3670,7 @@ given `GType` is not supported, this operation can fail and a `GdkContentProvider` + line="337">a `GdkContentProvider` the `GValue` to fill + line="338">the `GValue` to fill - + c:identifier="gdk_content_provider_ref_formats" + glib:get-property="formats"> Gets the formats that the provider can provide its current contents in. @@ -3092,9 +3707,8 @@ given `GType` is not supported, this operation can fail and - + c:identifier="gdk_content_provider_ref_storable_formats" + glib:get-property="storable-formats"> Gets the formats that the provider suggests other applications to store @@ -3120,16 +3734,13 @@ This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].< + c:identifier="gdk_content_provider_write_mime_type_async" + glib:finish-func="write_mime_type_finish"> Asynchronously writes the contents of @provider to @stream in the given @mime_type. -When the operation is finished @callback will be called. You must then call -[method@Gdk.ContentProvider.write_mime_type_finish] to get the result -of the operation. - The given mime type does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported. @@ -3200,14 +3811,14 @@ The given @stream will not be closed. throws="1"> Finishes an asynchronous write operation. + line="311">Finishes an asynchronous write operation. See [method@Gdk.ContentProvider.write_mime_type_async]. %TRUE if the operation was completed successfully. Otherwise + line="321">%TRUE if the operation was completed successfully. Otherwise @error will be set to describe the failure. @@ -3215,28 +3826,26 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. a `GdkContentProvider` + line="313">a `GdkContentProvider` a `GAsyncResult` + line="314">a `GAsyncResult` - - + The possible formats that the provider can provide its data in. - - + The subset of formats that clipboard managers should store this provider's data in. @@ -3265,6 +3874,9 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. + Signal class closure for `GdkContentProvider::content-changed` @@ -3421,7 +4033,7 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. %TRUE if the operation was completed successfully. Otherwise + line="321">%TRUE if the operation was completed successfully. Otherwise @error will be set to describe the failure. @@ -3429,13 +4041,13 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. a `GdkContentProvider` + line="313">a `GdkContentProvider` a `GAsyncResult` + line="314">a `GAsyncResult` @@ -3447,7 +4059,7 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. %TRUE if the value was set successfully. Otherwise + line="349">%TRUE if the value was set successfully. Otherwise @error will be set to describe the failure. @@ -3455,7 +4067,7 @@ See [method@Gdk.ContentProvider.write_mime_type_async]. a `GdkContentProvider` + line="337">a `GdkContentProvider` transfer-ownership="none"> the `GValue` to fill + line="338">the `GValue` to fill @@ -3505,8 +4117,7 @@ operation. glib:get-type="gdk_content_serializer_get_type"> A `GdkContentSerializer` is used to serialize content for -inter-application data transfers. + line="39">Serializes content for inter-application data transfers. The `GdkContentSerializer` transforms an object that is identified by a GType into a serialized form (i.e. a byte stream) that is @@ -3522,21 +4133,21 @@ Also see [class@Gdk.ContentDeserializer]. c:identifier="gdk_content_serializer_get_cancellable"> Gets the cancellable for the current operation. + line="265">Gets the cancellable for the current operation. This is the `GCancellable` that was passed to [func@content_serialize_async]. the cancellable for the current operation + line="273">the cancellable for the current operation a `GdkContentSerializer` + line="267">a `GdkContentSerializer` @@ -3544,19 +4155,19 @@ This is the `GCancellable` that was passed to [func@content_serialize_async]. Gets the `GType` to of the object to serialize. + line="197">Gets the `GType` to of the object to serialize. the `GType` for the current operation + line="203">the `GType` for the current operation a `GdkContentSerializer` + line="199">a `GdkContentSerializer` @@ -3565,19 +4176,19 @@ This is the `GCancellable` that was passed to [func@content_serialize_async]. Gets the mime type to serialize to. + line="181">Gets the mime type to serialize to. the mime type for the current operation + line="187">the mime type for the current operation a `GdkContentSerializer` + line="183">a `GdkContentSerializer` @@ -3586,21 +4197,21 @@ This is the `GCancellable` that was passed to [func@content_serialize_async]. Gets the output stream for the current operation. + line="229">Gets the output stream for the current operation. This is the stream that was passed to [func@content_serialize_async]. the output stream for the current operation + line="237">the output stream for the current operation a `GdkContentSerializer` + line="231">a `GdkContentSerializer` @@ -3609,21 +4220,21 @@ This is the stream that was passed to [func@content_serialize_async]. c:identifier="gdk_content_serializer_get_priority"> Gets the I/O priority for the current operation. + line="247">Gets the I/O priority for the current operation. This is the priority that was passed to [func@content_serialize_async]. the I/O priority for the current operation + line="255">the I/O priority for the current operation a `GdkContentSerializer` + line="249">a `GdkContentSerializer` @@ -3632,21 +4243,21 @@ This is the priority that was passed to [func@content_serialize_async]. c:identifier="gdk_content_serializer_get_task_data"> Gets the data that was associated with the current operation. + line="321">Gets the data that was associated with the current operation. See [method@Gdk.ContentSerializer.set_task_data]. the task data for @serializer + line="329">the task data for @serializer a `GdkContentSerializer` + line="323">a `GdkContentSerializer` @@ -3655,19 +4266,19 @@ See [method@Gdk.ContentSerializer.set_task_data]. c:identifier="gdk_content_serializer_get_user_data"> Gets the user data that was passed when the serializer was registered. + line="283">Gets the user data that was passed when the serializer was registered. the user data for this serializer + line="289">the user data for this serializer a `GdkContentSerializer` + line="285">a `GdkContentSerializer` @@ -3675,19 +4286,19 @@ See [method@Gdk.ContentSerializer.set_task_data]. Gets the `GValue` to read the object to serialize from. + line="213">Gets the `GValue` to read the object to serialize from. the `GValue` for the current operation + line="219">the `GValue` for the current operation a `GdkContentSerializer` + line="215">a `GdkContentSerializer` @@ -3696,7 +4307,7 @@ See [method@Gdk.ContentSerializer.set_task_data]. c:identifier="gdk_content_serializer_return_error"> Indicate that the serialization has ended with an error. + line="374">Indicate that the serialization has ended with an error. This function consumes @error. @@ -3707,13 +4318,13 @@ This function consumes @error. a `GdkContentSerializer` + line="376">a `GdkContentSerializer` a `GError` + line="377">a `GError` @@ -3722,7 +4333,7 @@ This function consumes @error. c:identifier="gdk_content_serializer_return_success"> Indicate that the serialization has been successfully completed. + line="352">Indicate that the serialization has been successfully completed. @@ -3731,7 +4342,7 @@ This function consumes @error. a `GdkContentSerializer` + line="354">a `GdkContentSerializer` @@ -3740,7 +4351,7 @@ This function consumes @error. c:identifier="gdk_content_serializer_set_task_data"> Associate data with the current serialization operation. + line="299">Associate data with the current serialization operation. @@ -3749,7 +4360,7 @@ This function consumes @error. a `GdkContentSerializer` + line="301">a `GdkContentSerializer` allow-none="1"> data to associate with this operation + line="302">data to associate with this operation destroy notify for @data + line="303">destroy notify for @data @@ -3779,23 +4390,23 @@ This function consumes @error. glib:fundamental="1"> An event caused by a pointing device moving between surfaces. + line="2125">An event caused by a pointing device moving between surfaces. Extracts the notify detail from a crossing event. - + line="2245">Extracts the notify detail from a crossing event. + the notify detail of @event + line="2251">the notify detail of @event a crossing event + line="2247">a crossing event @@ -3803,19 +4414,19 @@ This function consumes @error. Checks if the @event surface is the focus surface. - + line="2225">Checks if the @event surface is the focus surface. + %TRUE if the surface is the focus surface + line="2231">%TRUE if the surface is the focus surface a crossing event + line="2227">a crossing event @@ -3823,19 +4434,19 @@ This function consumes @error. Extracts the crossing mode from a crossing event. - + line="2205">Extracts the crossing mode from a crossing event. + the mode of @event + line="2211">the mode of @event a crossing event + line="2207">a crossing event @@ -3847,7 +4458,7 @@ This function consumes @error. c:type="GdkCrossingMode"> Specifies the crossing mode for enter and leave events. + line="332">Specifies the crossing mode for enter and leave events. glib:name="GDK_CROSSING_NORMAL"> crossing because of pointer motion. + line="334">crossing because of pointer motion. glib:name="GDK_CROSSING_GRAB"> crossing because a grab is activated. + line="335">crossing because a grab is activated. glib:name="GDK_CROSSING_UNGRAB"> crossing because a grab is deactivated. + line="336">crossing because a grab is deactivated. glib:name="GDK_CROSSING_GTK_GRAB"> crossing because a GTK grab is activated. + line="337">crossing because a GTK grab is activated. glib:name="GDK_CROSSING_GTK_UNGRAB"> crossing because a GTK grab is deactivated. + line="338">crossing because a GTK grab is deactivated. glib:name="GDK_CROSSING_STATE_CHANGED"> crossing because a GTK widget changed + line="339">crossing because a GTK widget changed state (e.g. sensitivity). glib:name="GDK_CROSSING_TOUCH_BEGIN"> crossing because a touch sequence has begun, + line="341">crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the surface. glib:name="GDK_CROSSING_TOUCH_END"> crossing because a touch sequence has ended, + line="343">crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the surface. glib:name="GDK_CROSSING_DEVICE_SWITCH"> crossing because of a device switch (i.e. + line="345">crossing because of a device switch (i.e. a mouse taking control of the pointer after a touch device), this event is synthetic as the pointer didn’t leave the surface. @@ -3943,7 +4554,7 @@ This function consumes @error. glib:get-type="gdk_cursor_get_type"> `GdkCursor` is used to create and destroy cursors. + line="38">Used to create and destroy cursors. Cursors are immutable objects, so once you created them, there is no way to modify them later. You should create a new cursor when you want to change @@ -3977,11 +4588,66 @@ above, it will try the fallback cursor. Fallback cursors can themselves have fallback cursors again, so it is possible to provide a chain of progressively easier to support cursors. If none of the provided cursors can be supported, the default cursor will be the ultimate fallback. + + Creates a new callback-based cursor object. + +Cursors of this kind produce textures for the cursor +image on demand, when the @callback is called. + + + a new `GdkCursor` + + + + + the `GdkCursorGetTextureCallback` + + + + data to pass to @callback + + + + destroy notify for @data + + + + the `GdkCursor` to fall back to when + this one cannot be supported + + + + Creates a new cursor by looking up @name in the current cursor + line="299">Creates a new cursor by looking up @name in the current cursor theme. A recommended set of cursor names that will work across different @@ -4002,7 +4668,7 @@ platforms can be found in the CSS specification: a new `GdkCursor`, or %NULL if there is no + line="323">a new `GdkCursor`, or %NULL if there is no cursor with the given name @@ -4010,7 +4676,7 @@ platforms can be found in the CSS specification: the name of the cursor + line="301">the name of the cursor %NULL or the `GdkCursor` to fall back to when + line="302">%NULL or the `GdkCursor` to fall back to when this one cannot be supported @@ -4029,31 +4695,31 @@ platforms can be found in the CSS specification: c:identifier="gdk_cursor_new_from_texture"> Creates a new cursor from a `GdkTexture`. + line="339">Creates a new cursor from a `GdkTexture`. a new `GdkCursor` + line="349">a new `GdkCursor` the texture providing the pixel data + line="341">the texture providing the pixel data the horizontal offset of the “hotspot” of the cursor + line="342">the horizontal offset of the “hotspot” of the cursor the vertical offset of the “hotspot” of the cursor + line="343">the vertical offset of the “hotspot” of the cursor the `GdkCursor` to fall back to when + line="344">the `GdkCursor` to fall back to when this one cannot be supported @@ -4071,21 +4737,20 @@ platforms can be found in the CSS specification: - Returns the fallback for this @cursor. + line="409">Returns the fallback for this @cursor. The fallback will be used if this cursor is not available on a given `GdkDisplay`. For named cursors, this can happen when using nonstandard names or when using an incomplete cursor theme. For textured cursors, this can happen when the texture is too large or when the `GdkDisplay` it is used on does not support textured cursors. - + the fallback of the cursor or %NULL + line="421">the fallback of the cursor or %NULL to use the default cursor as fallback @@ -4093,7 +4758,7 @@ it is used on does not support textured cursors. a `GdkCursor` + line="411">a `GdkCursor` @@ -4101,28 +4766,27 @@ it is used on does not support textured cursors. - Returns the horizontal offset of the hotspot. + line="470">Returns the horizontal offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor. Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with [ctor@Gdk.Cursor.new_from_texture]. - + the horizontal offset of the hotspot or 0 for named cursors + line="482">the horizontal offset of the hotspot or 0 for named cursors a `GdkCursor` + line="472">a `GdkCursor` @@ -4130,28 +4794,27 @@ will only return the hotspot position for cursors created with - Returns the vertical offset of the hotspot. + line="492">Returns the vertical offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor. Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with [ctor@Gdk.Cursor.new_from_texture]. - + the vertical offset of the hotspot or 0 for named cursors + line="504">the vertical offset of the hotspot or 0 for named cursors a `GdkCursor` + line="494">a `GdkCursor` @@ -4159,17 +4822,16 @@ will only return the hotspot position for cursors created with - Returns the name of the cursor. + line="432">Returns the name of the cursor. If the cursor is not a named cursor, %NULL will be returned. - + the name of the cursor or %NULL + line="440">the name of the cursor or %NULL if it is not a named cursor @@ -4177,7 +4839,7 @@ If the cursor is not a named cursor, %NULL will be returned. a `GdkCursor` + line="434">a `GdkCursor` @@ -4187,14 +4849,14 @@ If the cursor is not a named cursor, %NULL will be returned. glib:get-property="texture"> Returns the texture for the cursor. + line="451">Returns the texture for the cursor. If the cursor is a named cursor, %NULL will be returned. - + the texture for cursor or %NULL + line="459">the texture for cursor or %NULL if it is a named cursor @@ -4202,7 +4864,7 @@ If the cursor is a named cursor, %NULL will be returned. a `GdkCursor` + line="453">a `GdkCursor` @@ -4212,11 +4874,9 @@ If the cursor is a named cursor, %NULL will be returned. construct-only="1" transfer-ownership="none" getter="get_fallback"> - Cursor to fall back to if this cursor cannot be displayed. + line="174">Cursor to fall back to if this cursor cannot be displayed. transfer-ownership="none" getter="get_hotspot_x" default-value="0"> - X position of the cursor hotspot in the cursor image. + line="186">X position of the cursor hotspot in the cursor image. transfer-ownership="none" getter="get_hotspot_y" default-value="0"> - Y position of the cursor hotspot in the cursor image. + line="198">Y position of the cursor hotspot in the cursor image. transfer-ownership="none" getter="get_name" default-value="NULL"> - Name of this this cursor. + line="210">Name of this this cursor. The name will be %NULL if the cursor was created from a texture. @@ -4266,31 +4921,125 @@ The name will be %NULL if the cursor was created from a texture. getter="get_texture"> The texture displayed by this cursor. + line="224">The texture displayed by this cursor. The texture will be %NULL if the cursor was created from a name. - - + + The type of callback used by a dynamic `GdkCursor` to generate +a texture for the cursor image at the given @cursor_size +and @scale. + +The actual cursor size in application pixels may be different +from @cursor_size x @cursor_size, and will be returned in +@width, @height. The returned texture should have a size that +corresponds to the actual cursor size, in device pixels (i.e. +application pixels, multiplied by @scale). + +This function may fail and return `NULL`, in which case +the fallback cursor will be used. + + + the cursor image, or + `NULL` if none could be produced. + + - + + the `GdkCursor` + - + + the nominal cursor size, in application pixels + - + + the device scale + - + + return location for the actual cursor width, + in application pixels + - + + return location for the actual cursor height, + in application pixels + - - - - + + return location for the hotspot X position, + in application pixels + + + + return location for the hotspot Y position, + in application pixels + + + + User data for the callback + + + + + + + + + + + + + + + + + + + + + @@ -4332,6 +5081,15 @@ The texture will be %NULL if the cursor was created from a name. + + + + + + + glib:fundamental="1"> An event related to drag and drop operations. + line="3266">An event related to drag and drop operations. Gets the `GdkDrop` object from a DND event. - + line="3346">Gets the `GdkDrop` object from a DND event. + the drop + line="3352">the drop a DND event + line="3348">a DND event @@ -4395,7 +5153,7 @@ The texture will be %NULL if the cursor was created from a name. glib:fundamental="1"> An event related to closing a top-level surface. + line="2268">An event related to closing a top-level surface. glib:get-type="gdk_device_get_type"> The `GdkDevice` object represents an input device, such -as a keyboard, a mouse, or a touchpad. + line="28">Represents an input device, such as a keyboard, mouse or touchpad. See the [class@Gdk.Seat] documentation for more information about the various kinds of devices, and their relationships. + + Retrieves the index of the active layout of the keyboard. + +If there is no valid active layout for the `GdkDevice`, this function will +return -1; + +This is only relevant for keyboard devices. + + + The layout index of the active layout or -1. + + + + + a `GdkDevice` + + + + - Retrieves whether the Caps Lock modifier of the keyboard is locked. + line="1259">Retrieves whether the Caps Lock modifier of the keyboard is locked. This is only relevant for keyboard devices. %TRUE if Caps Lock is on for @device + line="1267">%TRUE if Caps Lock is on for @device a `GdkDevice` + line="1261">a `GdkDevice` - - + Retrieves the current tool for @device. + line="1243">Retrieves the current tool for @device. the `GdkDeviceTool` + line="1249">the `GdkDeviceTool` a `GdkDevice` + line="1245">a `GdkDevice` @@ -4460,10 +5245,9 @@ This is only relevant for keyboard devices. - Returns the direction of effective layout of the keyboard. + line="1393">Returns the direction of effective layout of the keyboard. This is only relevant for keyboard devices. @@ -4473,7 +5257,7 @@ of its symbols. See [func@Pango.unichar_direction]. %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL + line="1404">%PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL if it can determine the direction. %PANGO_DIRECTION_NEUTRAL otherwise @@ -4482,7 +5266,7 @@ of its symbols. See [func@Pango.unichar_direction]. a `GdkDevice` + line="1395">a `GdkDevice` @@ -4490,22 +5274,21 @@ of its symbols. See [func@Pango.unichar_direction]. - Returns the `GdkDisplay` to which @device pertains. + line="640">Returns the `GdkDisplay` to which @device pertains. a `GdkDisplay` + line="646">a `GdkDisplay` a `GdkDevice` + line="642">a `GdkDevice` @@ -4513,10 +5296,9 @@ of its symbols. See [func@Pango.unichar_direction]. - Determines whether the pointer follows device motion. + line="581">Determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which don't have a pointer. @@ -4524,14 +5306,42 @@ don't have a pointer. %TRUE if the pointer follows device motion + line="590">%TRUE if the pointer follows device motion a `GdkDevice` + line="583">a `GdkDevice` + + + + + + Retrieves the names of the layouts of the keyboard. + +This is only relevant for keyboard devices. + + + + %NULL-terminated array of strings of layouts, + + + + + + + a `GdkDevice` @@ -4539,24 +5349,23 @@ don't have a pointer. - Retrieves the current modifier state of the keyboard. + line="1322">Retrieves the current modifier state of the keyboard. This is only relevant for keyboard devices. the current modifier state + line="1330">the current modifier state a `GdkDevice` + line="1324">a `GdkDevice` @@ -4566,19 +5375,19 @@ This is only relevant for keyboard devices. glib:get-property="name"> The name of the device, suitable for showing in a user interface. + line="565">The name of the device, suitable for showing in a user interface. a name + line="571">a name a GdkDevice` + line="567">a GdkDevice` @@ -4586,24 +5395,23 @@ This is only relevant for keyboard devices. - Retrieves whether the Num Lock modifier of the keyboard is locked. + line="1280">Retrieves whether the Num Lock modifier of the keyboard is locked. This is only relevant for keyboard devices. %TRUE if Num Lock is on for @device + line="1288">%TRUE if Num Lock is on for @device a ``GdkDevice` + line="1282">a ``GdkDevice` @@ -4613,19 +5421,19 @@ This is only relevant for keyboard devices. glib:get-property="num-touches"> Retrieves the number of touch points associated to @device. + line="1227">Retrieves the number of touch points associated to @device. the number of touch points + line="1233">the number of touch points a `GdkDevice` + line="1229">a `GdkDevice` @@ -4633,10 +5441,9 @@ This is only relevant for keyboard devices. - Returns the product ID of this device. + line="1165">Returns the product ID of this device. This ID is retrieved from the device, and does not change. See [method@Gdk.Device.get_vendor_id] for more information. @@ -4644,14 +5451,14 @@ See [method@Gdk.Device.get_vendor_id] for more information. the product ID + line="1174">the product ID a physical `GdkDevice` + line="1167">a physical `GdkDevice` @@ -4659,25 +5466,23 @@ See [method@Gdk.Device.get_vendor_id] for more information. - Retrieves whether the Scroll Lock modifier of the keyboard is locked. + line="1301">Retrieves whether the Scroll Lock modifier of the keyboard is locked. This is only relevant for keyboard devices. %TRUE if Scroll Lock is on for @device + line="1309">%TRUE if Scroll Lock is on for @device a `GdkDevice` + line="1303">a `GdkDevice` @@ -4685,22 +5490,21 @@ This is only relevant for keyboard devices. - Returns the `GdkSeat` the device belongs to. + line="1198">Returns the `GdkSeat` the device belongs to. a `GdkSeat` + line="1204">a `GdkSeat` A `GdkDevice` + line="1200">A `GdkDevice` @@ -4708,22 +5512,21 @@ This is only relevant for keyboard devices. - Determines the type of the device. + line="600">Determines the type of the device. a `GdkInputSource` + line="606">a `GdkInputSource` a `GdkDevice` + line="602">a `GdkDevice` @@ -4732,7 +5535,7 @@ This is only relevant for keyboard devices. c:identifier="gdk_device_get_surface_at_position"> Obtains the surface underneath @device, returning the location of the + line="527">Obtains the surface underneath @device, returning the location of the device in @win_x and @win_y. Returns %NULL if the surface tree under @device is not known to GDK @@ -4741,7 +5544,7 @@ Returns %NULL if the surface tree under @device is not known to GDK the `GdkSurface` under the + line="541">the `GdkSurface` under the device position @@ -4749,7 +5552,7 @@ Returns %NULL if the surface tree under @device is not known to GDK pointer `GdkDevice` to query info to + line="529">pointer `GdkDevice` to query info to return location for the X coordinate + line="530">return location for the X coordinate of the device location relative to the surface origin @@ -4772,7 +5575,7 @@ Returns %NULL if the surface tree under @device is not known to GDK allow-none="1"> return location for the Y coordinate + line="532">return location for the Y coordinate of the device location relative to the surface origin @@ -4783,7 +5586,7 @@ Returns %NULL if the surface tree under @device is not known to GDK version="4.2"> Returns the timestamp of the last activity for this device. + line="1448">Returns the timestamp of the last activity for this device. In practice, this means the timestamp of the last event that was received from the OS for this device. (GTK may occasionally produce @@ -4793,14 +5596,14 @@ update the timestamp). the timestamp of the last activity for this device + line="1459">the timestamp of the last activity for this device a `GdkDevice` + line="1450">a `GdkDevice` @@ -4808,10 +5611,9 @@ update the timestamp). - Returns the vendor ID of this device. + line="1123">Returns the vendor ID of this device. This ID is retrieved from the device, and does not change. @@ -4842,14 +5644,14 @@ for this device. the vendor ID + line="1155">the vendor ID a physical `GdkDevice` + line="1125">a physical `GdkDevice` @@ -4857,11 +5659,9 @@ for this device. - Determines if layouts for both right-to-left and + line="1419">Determines if layouts for both right-to-left and left-to-right languages are in use on the keyboard. This is only relevant for keyboard devices. @@ -4869,27 +5669,39 @@ This is only relevant for keyboard devices. %TRUE if there are layouts with both directions, %FALSE otherwise + line="1428">%TRUE if there are layouts with both directions, %FALSE otherwise a `GdkDevice` + line="1421">a `GdkDevice` + + The index of the keyboard active layout of a `GdkDevice`. + +Will be -1 if there is no valid active layout. + +This is only relevant for keyboard devices. + + - Whether Caps Lock is on. + line="249">Whether Caps Lock is on. This is only relevant for keyboard devices. @@ -4898,11 +5710,9 @@ This is only relevant for keyboard devices. transfer-ownership="none" getter="get_direction" default-value="PANGO_DIRECTION_NEUTRAL"> - The direction of the current layout. + line="225">The direction of the current layout. This is only relevant for keyboard devices. @@ -4912,21 +5722,18 @@ This is only relevant for keyboard devices. construct-only="1" transfer-ownership="none" getter="get_display"> - The `GdkDisplay` the `GdkDevice` pertains to. + line="108">The `GdkDisplay` the `GdkDevice` pertains to. - Whether the device has both right-to-left and left-to-right layouts. + line="237">Whether the device has both right-to-left and left-to-right layouts. This is only relevant for keyboard devices. @@ -4937,22 +5744,31 @@ This is only relevant for keyboard devices. transfer-ownership="none" getter="get_has_cursor" default-value="FALSE"> - Whether the device is represented by a cursor on the screen. + line="141">Whether the device is represented by a cursor on the screen. + + The names of the keyboard layouts of a `GdkDevice`. + +This is only relevant for keyboard devices. + + + + - + default-value="GDK_NO_MODIFIER_MASK"> The current modifier state of the device. + line="285">The current modifier state of the device. This is only relevant for keyboard devices. @@ -4960,7 +5776,7 @@ This is only relevant for keyboard devices. Number of axes in the device. + line="152">Number of axes in the device. transfer-ownership="none" getter="get_name" default-value="NULL"> - The device name. + line="118">The device name. - Whether Num Lock is on. + line="261">Whether Num Lock is on. This is only relevant for keyboard devices. @@ -4994,11 +5807,9 @@ This is only relevant for keyboard devices. transfer-ownership="none" getter="get_num_touches" default-value="0"> - The maximal number of concurrent touches on a touch device. + line="200">The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown. @@ -5010,11 +5821,9 @@ of touches is unknown. transfer-ownership="none" getter="get_product_id" default-value="NULL"> - Product ID of this device. + line="176">Product ID of this device. See [method@Gdk.Device.get_product_id]. @@ -5023,11 +5832,9 @@ See [method@Gdk.Device.get_product_id]. transfer-ownership="none" getter="get_scroll_lock_state" default-value="FALSE"> - Whether Scroll Lock is on. + line="273">Whether Scroll Lock is on. This is only relevant for keyboard devices. @@ -5036,10 +5843,9 @@ This is only relevant for keyboard devices. writable="1" transfer-ownership="none" getter="get_seat"> - `GdkSeat` of this device. + line="189">`GdkSeat` of this device. transfer-ownership="none" getter="get_source" default-value="GDK_SOURCE_MOUSE"> - Source type for the device. + line="129">Source type for the device. - - + The `GdkDeviceTool` that is currently used with this device. + line="215">The `GdkDeviceTool` that is currently used with this device. transfer-ownership="none" getter="get_vendor_id" default-value="NULL"> - Vendor ID of this device. + line="163">Vendor ID of this device. See [method@Gdk.Device.get_vendor_id]. @@ -5080,7 +5881,7 @@ See [method@Gdk.Device.get_vendor_id]. Emitted either when the number of either axes or keys changes. + line="330">Emitted either when the number of either axes or keys changes. On X11 this will normally happen when the physical device routing events through the logical device changes (for @@ -5094,7 +5895,7 @@ and keys on the new physical device. Emitted on pen/eraser devices whenever tools enter or leave proximity. + line="350">Emitted on pen/eraser devices whenever tools enter or leave proximity. @@ -5102,7 +5903,7 @@ and keys on the new physical device. The new current tool + line="353">The new current tool @@ -5116,8 +5917,7 @@ and keys on the new physical device. glib:type-struct="DevicePadInterface"> `GdkDevicePad` is an interface implemented by devices of type -%GDK_SOURCE_TABLET_PAD + line="20">An interface for tablet pad devices. It allows querying the features provided by the pad device. @@ -5139,33 +5939,33 @@ for a given group will be notified through events of type `GDK_PAD_GROUP_MODE`.< c:identifier="gdk_device_pad_get_feature_group"> Returns the group the given @feature and @idx belong to. + line="117">Returns the group the given @feature and @idx belong to. f the feature or index do not exist in @pad, -1 is returned. The group number of the queried pad feature. + line="127">The group number of the queried pad feature. a `GdkDevicePad` + line="119">a `GdkDevicePad` the feature type to get the group from + line="120">the feature type to get the group from the index of the feature to get the group from + line="121">the index of the feature to get the group from @@ -5174,25 +5974,25 @@ f the feature or index do not exist in @pad, -1 is returned. c:identifier="gdk_device_pad_get_group_n_modes"> Returns the number of modes that @group may have. + line="76">Returns the number of modes that @group may have. The number of modes available in @group. + line="83">The number of modes available in @group. a `GdkDevicePad` + line="78">a `GdkDevicePad` group to get the number of available modes from + line="79">group to get the number of available modes from @@ -5201,25 +6001,25 @@ f the feature or index do not exist in @pad, -1 is returned. c:identifier="gdk_device_pad_get_n_features"> Returns the number of features a tablet pad has. + line="97">Returns the number of features a tablet pad has. The amount of elements of type @feature that this pad has. + line="104">The amount of elements of type @feature that this pad has. a `GdkDevicePad` + line="99">a `GdkDevicePad` a pad feature + line="100">a pad feature @@ -5227,7 +6027,7 @@ f the feature or index do not exist in @pad, -1 is returned. Returns the number of groups this pad device has. + line="54">Returns the number of groups this pad device has. Pads have at least one group. A pad group is a subcollection of buttons/strip/rings that is affected collectively by a same @@ -5236,14 +6036,14 @@ current mode. The number of button/ring/strip groups in the pad. + line="64">The number of button/ring/strip groups in the pad. a `GdkDevicePad` + line="56">a `GdkDevicePad` @@ -5303,7 +6103,6 @@ current mode. - Gets the axes of the tool. @@ -5326,7 +6125,6 @@ current mode. - Gets the hardware ID of this tool, or 0 if it's not known. @@ -5359,7 +6157,6 @@ as a tablet may support multiple devices with the same - Gets the serial number of this tool. @@ -5385,7 +6182,6 @@ This value can be used to identify a physical tool - Gets the `GdkDeviceToolType` of the tool. @@ -5413,8 +6209,6 @@ This value can be used to identify a physical tool transfer-ownership="none" getter="get_axes" default-value="0"> - The axes of the tool. @@ -5426,8 +6220,6 @@ This value can be used to identify a physical tool transfer-ownership="none" getter="get_hardware_id" default-value="0"> - The hardware ID of the tool. @@ -5439,8 +6231,6 @@ This value can be used to identify a physical tool transfer-ownership="none" getter="get_serial" default-value="0"> - The serial number of the tool. @@ -5452,8 +6242,6 @@ This value can be used to identify a physical tool transfer-ownership="none" getter="get_tool_type" default-value="GDK_DEVICE_TOOL_TYPE_UNKNOWN"> - The type of the tool. @@ -5549,7 +6337,7 @@ airbrush, pencil, etc. glib:get-type="gdk_display_get_type"> `GdkDisplay` objects are the GDK representation of a workstation. + line="56">A representation of a workstation. Their purpose are two-fold: @@ -5566,16 +6354,16 @@ be accessed with [method@Gdk.Display.get_monitor_at_surface] and similar APIs. Gets the default `GdkDisplay`. + line="332">Gets the default `GdkDisplay`. This is a convenience function for: gdk_display_manager_get_default_display (gdk_display_manager_get ()) - + a `GdkDisplay`, or %NULL if + line="341">a `GdkDisplay`, or %NULL if there is no default display @@ -5583,14 +6371,14 @@ This is a convenience function for: Opens a display. + line="1187">Opens a display. If opening the display fails, `NULL` is returned. a `GdkDisplay` + line="1195">a `GdkDisplay` @@ -5600,7 +6388,7 @@ If opening the display fails, `NULL` is returned. allow-none="1"> the name of the display to open + line="1189">the name of the display to open @@ -5608,7 +6396,7 @@ If opening the display fails, `NULL` is returned. Emits a short beep on @display + line="1018">Emits a short beep on @display @@ -5617,7 +6405,7 @@ If opening the display fails, `NULL` is returned. a `GdkDisplay` + line="1020">a `GdkDisplay` @@ -5625,7 +6413,7 @@ If opening the display fails, `NULL` is returned. Closes the connection to the windowing system for the given display. + line="478">Closes the connection to the windowing system for the given display. This cleans up associated resources. @@ -5636,7 +6424,7 @@ This cleans up associated resources. a `GdkDisplay` + line="480">a `GdkDisplay` @@ -5647,7 +6435,7 @@ This cleans up associated resources. throws="1"> Creates a new `GdkGLContext` for the `GdkDisplay`. + line="1500">Creates a new `GdkGLContext` for the `GdkDisplay`. The context is disconnected from any particular surface or surface and cannot be used to draw to any surface. It can only be used to @@ -5656,18 +6444,18 @@ draw to non-surface framebuffers like textures. If the creation of the `GdkGLContext` failed, @error will be set. Before using the returned `GdkGLContext`, you will need to call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. - + the newly created `GdkGLContext` + line="1515">the newly created `GdkGLContext` a `GdkDisplay` + line="1502">a `GdkDisplay` @@ -5676,25 +6464,25 @@ call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. Returns %TRUE if there is an ongoing grab on @device for @display. + line="975">Returns %TRUE if there is an ongoing grab on @device for @display. %TRUE if there is a grab in effect for @device. + line="982">%TRUE if there is a grab in effect for @device. a `GdkDisplay` + line="977">a `GdkDisplay` a `GdkDevice` + line="978">a `GdkDevice` @@ -5702,7 +6490,7 @@ call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. Flushes any requests queued for the windowing system. + line="1055">Flushes any requests queued for the windowing system. This happens automatically when the main loop blocks waiting for new events, but if your application is drawing without returning control to the main loop, @@ -5720,7 +6508,7 @@ handled synchronously, this function will do nothing. a `GdkDisplay` + line="1057">a `GdkDisplay` @@ -5729,20 +6517,20 @@ handled synchronously, this function will do nothing. c:identifier="gdk_display_get_app_launch_context"> Returns a `GdkAppLaunchContext` suitable for launching + line="1170">Returns a `GdkAppLaunchContext` suitable for launching applications on the given display. - + a new `GdkAppLaunchContext` for @display + line="1177">a new `GdkAppLaunchContext` for @display a `GdkDisplay` + line="1172">a `GdkDisplay` @@ -5750,19 +6538,19 @@ applications on the given display. Gets the clipboard used for copy/paste operations. - + line="1078">Gets the clipboard used for copy/paste operations. + the display's clipboard + line="1084">the display's clipboard a `GdkDisplay` + line="1080">a `GdkDisplay` @@ -5771,22 +6559,53 @@ applications on the given display. c:identifier="gdk_display_get_default_seat"> Returns the default `GdkSeat` for this display. + line="2278">Returns the default `GdkSeat` for this display. Note that a display may not have a seat. In this case, this function will return %NULL. - + the default seat. + line="2287">the default seat. a `GdkDisplay` + line="2280">a `GdkDisplay` + + + + + + Returns the dma-buf formats that are supported on this display. + +GTK may use OpenGL or Vulkan to support some formats. +Calling this function will then initialize them if they aren't yet. + +The formats returned by this function can be used for negotiating +buffer formats with producers such as v4l, pipewire or GStreamer. + +To learn more about dma-bufs, see [class@Gdk.DmabufTextureBuilder]. + + + a `GdkDmabufFormats` object + + + + + a `GdkDisplay` @@ -5795,13 +6614,13 @@ this function will return %NULL. c:identifier="gdk_display_get_monitor_at_surface"> Gets the monitor in which the largest area of @surface + line="2340">Gets the monitor in which the largest area of @surface resides. - + the monitor with the largest + line="2348">the monitor with the largest overlap with @surface @@ -5809,13 +6628,13 @@ resides. a `GdkDisplay` + line="2342">a `GdkDisplay` a `GdkSurface` + line="2343">a `GdkSurface` @@ -5823,25 +6642,25 @@ resides. Gets the list of monitors associated with this display. + line="2318">Gets the list of monitors associated with this display. Subsequent calls to this function will always return the same list for the same display. You can listen to the GListModel::items-changed signal on this list to monitor changes to the monitor of this display. - + a `GListModel` of `GdkMonitor` + line="2330">a `GListModel` of `GdkMonitor` a `GdkDisplay` + line="2320">a `GdkDisplay` @@ -5849,12 +6668,12 @@ this list to monitor changes to the monitor of this display. Gets the name of the display. + line="1001">Gets the name of the display. a string representing the display name. This string is owned + line="1007">a string representing the display name. This string is owned by GDK and should not be modified or freed. @@ -5862,7 +6681,7 @@ this list to monitor changes to the monitor of this display. a `GdkDisplay` + line="1003">a `GdkDisplay` @@ -5871,22 +6690,22 @@ this list to monitor changes to the monitor of this display. c:identifier="gdk_display_get_primary_clipboard"> Gets the clipboard used for the primary selection. + line="1097">Gets the clipboard used for the primary selection. On backends where the primary clipboard is not supported natively, GDK emulates this clipboard locally. - + the primary clipboard + line="1106">the primary clipboard a `GdkDisplay` + line="1099">a `GdkDisplay` @@ -5894,13 +6713,13 @@ GDK emulates this clipboard locally. Retrieves a desktop-wide setting such as double-click time + line="2405">Retrieves a desktop-wide setting such as double-click time for the @display. - + %TRUE if the setting existed and a value was stored + line="2414">%TRUE if the setting existed and a value was stored in @value, %FALSE otherwise @@ -5908,19 +6727,19 @@ for the @display. a `GdkDisplay` + line="2407">a `GdkDisplay` the name of the setting + line="2408">the name of the setting location to store the value of the setting + line="2409">location to store the value of the setting @@ -5931,20 +6750,20 @@ for the @display. deprecated-version="4.10"> Gets the startup notification ID for a Wayland display, or %NULL + line="1236">Gets the startup notification ID for a Wayland display, or %NULL if no ID has been defined. - + the startup notification ID for @display + line="1243">the startup notification ID for @display a `GdkDisplay` + line="1238">a `GdkDisplay` @@ -5952,28 +6771,29 @@ if no ID has been defined. Finds out if the display has been closed. + line="502">Finds out if the display has been closed. %TRUE if the display is closed. + line="508">%TRUE if the display is closed. a `GdkDisplay` + line="504">a `GdkDisplay` - - + Returns whether surfaces can reasonably be expected to have + line="2102">Returns whether surfaces can reasonably be expected to have their alpha channel drawn correctly on the screen. Check [method@Gdk.Display.is_rgba] for whether the display @@ -5987,7 +6807,7 @@ On modern displays, this value is always %TRUE. Whether surfaces with RGBA visuals can reasonably + line="2117">Whether surfaces with RGBA visuals can reasonably be expected to have their alpha channels drawn correctly on the screen. @@ -5996,16 +6816,17 @@ On modern displays, this value is always %TRUE. a `GdkDisplay` + line="2104">a `GdkDisplay` - - + Returns whether surfaces on this @display are created with an + line="2147">Returns whether surfaces on this @display are created with an alpha channel. Even if a %TRUE is returned, it is possible that the @@ -6020,7 +6841,7 @@ On modern displays, this value is always %TRUE. %TRUE if surfaces are created with an alpha channel or + line="2163">%TRUE if surfaces are created with an alpha channel or %FALSE if the display does not support this functionality. @@ -6028,7 +6849,7 @@ On modern displays, this value is always %TRUE. a `GdkDisplay` + line="2149">a `GdkDisplay` @@ -6036,12 +6857,12 @@ On modern displays, this value is always %TRUE. Returns the list of seats known to @display. - + line="2301">Returns the list of seats known to @display. + the + line="2307">the list of seats known to the `GdkDisplay` @@ -6051,7 +6872,7 @@ On modern displays, this value is always %TRUE. a `GdkDisplay` + line="2303">a `GdkDisplay` @@ -6059,7 +6880,7 @@ On modern displays, this value is always %TRUE. Returns the keyvals bound to @keycode. + line="2497">Returns the keyvals bound to @keycode. The Nth `GdkKeymapKey` in @keys is bound to the Nth keyval in @keyvals. @@ -6068,24 +6889,24 @@ this list of entries is selected by considering the effective keyboard group and level. Free the returned arrays with g_free(). - + %TRUE if there were any entries + line="2517">%TRUE if there were any entries a `GdkDisplay` + line="2499">a `GdkDisplay` a keycode + line="2500">a keycode allow-none="1"> return + line="2501">return location for array of `GdkKeymapKey` @@ -6110,7 +6931,7 @@ Free the returned arrays with g_free(). allow-none="1"> return + line="2503">return location for array of keyvals @@ -6122,7 +6943,7 @@ Free the returned arrays with g_free(). transfer-ownership="full"> length of @keys and @keyvals + line="2505">length of @keys and @keyvals @@ -6130,7 +6951,7 @@ Free the returned arrays with g_free(). Obtains a list of keycode/group/level combinations that will + line="2459">Obtains a list of keycode/group/level combinations that will generate @keyval. Groups and levels are two kinds of keyboard mode; in general, the level @@ -6145,24 +6966,24 @@ Hebrew to English modes, for example. keyboard group. The level is computed from the modifier mask. The returned array should be freed with g_free(). - + %TRUE if keys were found and returned + line="2483">%TRUE if keys were found and returned a `GdkDisplay` + line="2461">a `GdkDisplay` a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc. + line="2462">a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc. transfer-ownership="full"> return location + line="2463">return location for an array of `GdkKeymapKey` @@ -6183,7 +7004,7 @@ The returned array should be freed with g_free(). transfer-ownership="full"> return location for number of elements in returned array + line="2465">return location for number of elements in returned array @@ -6194,7 +7015,7 @@ The returned array should be freed with g_free(). deprecated-version="4.10"> Indicates to the GUI environment that the application has + line="1211">Indicates to the GUI environment that the application has finished loading, using a given identifier. GTK will call this function automatically for [GtkWindow](../gtk4/class.Window.html) @@ -6202,7 +7023,7 @@ with custom startup-notification identifier unless [gtk_window_set_auto_startup_notification()](../gtk4/method.Window.set_auto_startup_notification.html) is called to disable that feature. Using [method@Gdk.Toplevel.set_startup_id] is sufficient - + @@ -6210,13 +7031,13 @@ is called to disable that feature. a `GdkDisplay` + line="1213">a `GdkDisplay` a startup-notification identifier, for which + line="1214">a startup-notification identifier, for which notification process should be completed @@ -6228,7 +7049,7 @@ is called to disable that feature. throws="1"> Checks that OpenGL is available for @self and ensures that it is + line="1447">Checks that OpenGL is available for @self and ensures that it is properly initialized. When this fails, an @error will be set describing the error and this function returns %FALSE. @@ -6242,18 +7063,18 @@ return the same value or error. You never need to call this function, GDK will call it automatically as needed. But you can use it as a check when setting up code that might make use of OpenGL. - + %TRUE if the display supports OpenGL + line="1467">%TRUE if the display supports OpenGL a `GdkDisplay` + line="1449">a `GdkDisplay` @@ -6264,10 +7085,10 @@ might make use of OpenGL. deprecated-version="4.10"> Adds the given event to the event queue for @display. + line="539">Adds the given event to the event queue for @display. This function is only useful in very special situations and should not be used by applications. - + @@ -6275,40 +7096,67 @@ special situations and should not be used by applications. a `GdkDisplay` + line="541">a `GdkDisplay` a `GdkEvent` + line="542">a `GdkEvent` - + c:identifier="gdk_display_supports_input_shapes" + glib:get-property="input-shapes"> Returns %TRUE if the display supports input shapes. + line="1119">Returns %TRUE if the display supports input shapes. This means that [method@Gdk.Surface.set_input_region] can be used to modify the input shape of surfaces on @display. On modern displays, this value is always %TRUE. + + + %TRUE if surfaces with modified input shape are supported + + + + + a `GdkDisplay` + + + + + + Returns whether it's possible for a surface to draw outside of the window area. + +If %TRUE is returned the application decides if it wants to draw shadows. +If %FALSE is returned, the compositor decides if it wants to draw shadows. %TRUE if surfaces with modified input shape are supported + line="2201">%TRUE if surfaces can draw shadows or + %FALSE if the display does not support this functionality. a `GdkDisplay` + line="2194">a `GdkDisplay` @@ -6316,7 +7164,7 @@ On modern displays, this value is always %TRUE. Flushes any requests queued for the windowing system and waits until all + line="1032">Flushes any requests queued for the windowing system and waits until all requests have been handled. This is often used for making sure that the display is synchronized @@ -6334,7 +7182,7 @@ handled synchronously, this function will do nothing. a `GdkDisplay` + line="1034">a `GdkDisplay` @@ -6342,7 +7190,7 @@ handled synchronously, this function will do nothing. Translates the contents of a `GdkEventKey` into a keyval, effective group, + line="2533">Translates the contents of a `GdkEventKey` into a keyval, effective group, and level. Modifiers that affected the translation and are thus unavailable for @@ -6361,36 +7209,36 @@ should be masked out. This function should rarely be needed, since `GdkEventKey` already contains the translated keyval. It is exported for the benefit of virtualized test environments. - + %TRUE if there was a keyval bound to keycode/state/group. + line="2565">%TRUE if there was a keyval bound to keycode/state/group. a `GdkDisplay` + line="2535">a `GdkDisplay` a keycode + line="2536">a keycode a modifier state + line="2537">a modifier state active keyboard group + line="2538">active keyboard group allow-none="1"> return location for keyval + line="2539">return location for keyval allow-none="1"> return location for effective group + line="2540">return location for effective group allow-none="1"> return location for level + line="2541">return location for level allow-none="1"> return location for modifiers that were used + line="2542">return location for modifiers that were used to determine the group or level @@ -6442,35 +7290,54 @@ virtualized test environments. - %TRUE if the display properly composites the alpha channel. + line="232">%TRUE if the display properly composites the alpha channel. + + The dma-buf formats that are supported on this display + + + %TRUE if the display supports input shapes. + + + - %TRUE if the display supports input shapes. + line="242">%TRUE if the display supports an alpha channel. - - + %TRUE if the display supports an alpha channel. + line="252">%TRUE if the display supports extensible frames. Emitted when the connection to the windowing system for @display is closed. + line="303">Emitted when the connection to the windowing system for @display is closed. @@ -6478,7 +7345,7 @@ virtualized test environments. %TRUE if the display was closed due to an error + line="306">%TRUE if the display was closed due to an error @@ -6486,7 +7353,7 @@ virtualized test environments. Emitted when the connection to the windowing system for @display is opened. + line="288">Emitted when the connection to the windowing system for @display is opened. @@ -6494,7 +7361,7 @@ virtualized test environments. Emitted whenever a new seat is made known to the windowing system. + line="321">Emitted whenever a new seat is made known to the windowing system. @@ -6502,7 +7369,7 @@ virtualized test environments. the seat that was just added + line="324">the seat that was just added @@ -6510,7 +7377,7 @@ virtualized test environments. Emitted whenever a seat is removed by the windowing system. + line="336">Emitted whenever a seat is removed by the windowing system. @@ -6518,7 +7385,7 @@ virtualized test environments. the seat that was just removed + line="339">the seat that was just removed @@ -6526,7 +7393,7 @@ virtualized test environments. Emitted whenever a setting changes its value. + line="351">Emitted whenever a setting changes its value. @@ -6534,7 +7401,7 @@ virtualized test environments. the name of the setting that changed + line="354">the name of the setting that changed @@ -6548,8 +7415,9 @@ virtualized test environments. glib:get-type="gdk_display_manager_get_type"> A singleton object that offers notification when displays appear or -disappear. + line="60">Offers notification when displays appear or disappear. + +`GdkDisplayManager` is a singleton object. You can use [func@Gdk.DisplayManager.get] to obtain the `GdkDisplayManager` singleton, but that should be rarely necessary. Typically, initializing @@ -6593,7 +7461,7 @@ macros like GDK_IS_X11_DISPLAY() to find out which backend is in use: Gets the singleton `GdkDisplayManager` object. + line="290">Gets the singleton `GdkDisplayManager` object. When called for the first time, this function consults the `GDK_BACKEND` environment variable to find out which of the @@ -6606,29 +7474,28 @@ backends will be used. The global `GdkDisplayManager` singleton + line="303">The global `GdkDisplayManager` singleton - Gets the default `GdkDisplay`. + line="318">Gets the default `GdkDisplay`. a `GdkDisplay` + line="324">a `GdkDisplay` a `GdkDisplayManager` + line="320">a `GdkDisplayManager` @@ -6637,12 +7504,12 @@ backends will be used. c:identifier="gdk_display_manager_list_displays"> List all currently open displays. + line="372">List all currently open displays. a newly + line="378">a newly allocated `GSList` of `GdkDisplay` objects @@ -6652,7 +7519,7 @@ backends will be used. a `GdkDisplayManager` + line="374">a `GdkDisplayManager` @@ -6661,12 +7528,12 @@ backends will be used. c:identifier="gdk_display_manager_open_display"> Opens a display. + line="387">Opens a display. a `GdkDisplay`, or %NULL + line="394">a `GdkDisplay`, or %NULL if the display could not be opened @@ -6674,7 +7541,7 @@ backends will be used. a `GdkDisplayManager` + line="389">a `GdkDisplayManager` allow-none="1"> the name of the display to open + line="390">the name of the display to open @@ -6693,7 +7560,7 @@ backends will be used. glib:set-property="default-display"> Sets @display as the default display. + line="353">Sets @display as the default display. @@ -6702,13 +7569,13 @@ backends will be used. a `GdkDisplayManager` + line="355">a `GdkDisplayManager` a `GdkDisplay` + line="356">a `GdkDisplay` @@ -6718,17 +7585,15 @@ backends will be used. transfer-ownership="none" setter="set_default_display" getter="get_default_display"> - The default display. + line="157">The default display. Emitted when a display is opened. + line="139">Emitted when a display is opened. @@ -6736,2033 +7601,3331 @@ backends will be used. the opened display + line="142">the opened display - + The `GdkDrag` object represents the source of an ongoing DND operation. + filename="gdk/gdkenums.h" + line="154">Error enumeration for `GdkDmabufTexture`. + + Dmabuf support is not available, because the OS + is not Linux, or it was explicitly disabled at compile- or runtime + + + The requested format is not supported + + + GTK failed to create the resource for other + reasons + + + Registers an error quark for [class@Gdk.DmabufTexture] errors. + + the error quark + + + + + + Provides information about supported DMA buffer formats. -A `GdkDrag` is created when a drag is started, and stays alive for duration of -the DND operation. After a drag has been started with [func@Gdk.Drag.begin], -the caller gets informed about the status of the ongoing drag operation -with signals on the `GdkDrag` object. +You can query whether a given format is supported with +[method@Gdk.DmabufFormats.contains] and you can iterate +over the list of all supported formats with +[method@Gdk.DmabufFormats.get_n_formats] and +[method@Gdk.DmabufFormats.get_format]. -GTK provides a higher level abstraction based on top of these functions, -and so they are not normally needed in GTK applications. See the -"Drag and Drop" section of the GTK documentation for more information. - - Starts a drag and creates a new drag context for it. +The list of supported formats is sorted by preference, +with the best formats coming first. -This function is called by the drag source. After this call, you -probably want to set up the drag icon using the surface returned -by [method@Gdk.Drag.get_drag_surface]. +The list may contains (format, modifier) pairs where the modifier +is `DMA_FORMAT_MOD_INVALID`, indicating that **_implicit modifiers_** +may be used with this format. -This function returns a reference to the [class@Gdk.Drag] object, -but GTK keeps its own reference as well, as long as the DND operation -is going on. +See [class@Gdk.DmabufTextureBuilder] for more information +about DMA buffers. -Note: if @actions include %GDK_ACTION_MOVE, you need to listen for -the [signal@Gdk.Drag::dnd-finished] signal and delete the data at -the source if [method@Gdk.Drag.get_selected_action] returns -%GDK_ACTION_MOVE. - - +Note that DMA buffers only exist on Linux. + + + Returns whether a given format is contained in @formats. + + a newly created `GdkDrag` - + filename="gdk/gdkdmabufformats.c" + line="161">`TRUE` if the format specified by the arguments + is part of @formats + - - the source surface for this drag - - - + the device that controls this drag - - - + filename="gdk/gdkdmabufformats.c" + line="155">a `GdkDmabufFormats` + + + the offered content - + filename="gdk/gdkdmabufformats.c" + line="156">a format code + - + the actions supported by this drag - + filename="gdk/gdkdmabufformats.c" + line="157">a format modifier + - + + + + Returns whether @formats1 and @formats2 contain the +same dmabuf formats, in the same order. + + + `TRUE` if @formats1 and @formats2 are equal + + + + the x offset to @device's position where the drag nominally started - - - + filename="gdk/gdkdmabufformats.c" + line="223">a `GdkDmabufFormats` + + + the y offset to @device's position where the drag nominally started - + filename="gdk/gdkdmabufformats.c" + line="224">another `GdkDmabufFormats` + - - + + Informs GDK that the drop ended. - -Passing %FALSE for @success may trigger a drag cancellation -animation. - -This function is called by the drag source, and should be the -last call before dropping the reference to the @drag. - -The `GdkDrag` will only take the first [method@Gdk.Drag.drop_done] -call as effective, if this function is called multiple times, -all subsequent calls will be ignored. - + filename="gdk/gdkdmabufformats.c" + line="123">Gets the fourcc code and modifier for a format +that is contained in @formats. + - + a `GdkDrag` - + filename="gdk/gdkdmabufformats.c" + line="125">a `GdkDmabufFormats` + - + whether the drag was ultimatively successful - + filename="gdk/gdkdmabufformats.c" + line="126">the index of the format to return + + + + return location for the format code + + + + return location for the format modifier + - - + Determines the bitmask of possible actions proposed by the source. - + filename="gdk/gdkdmabufformats.c" + line="102">Returns the number of formats that the @formats object +contains. + +Note that DMA buffers are a Linux concept, so on other +platforms, [method@Gdk.DmabufFormats.get_n_formats] will +always return zero. + the `GdkDragAction` flags - + filename="gdk/gdkdmabufformats.c" + line="113">the number of formats + - + a `GdkDrag` - + filename="gdk/gdkdmabufformats.c" + line="104">a `GdkDmabufFormats` + - - + Returns the `GdkContentProvider` associated to the `GdkDrag` object. - - + filename="gdk/gdkdmabufformats.c" + line="61">Increases the reference count of @formats. + + The `GdkContentProvider` associated to @drag. - + filename="gdk/gdkdmabufformats.c" + line="67">the passed-in object + - + a `GdkDrag` - + filename="gdk/gdkdmabufformats.c" + line="63">a `GdkDmabufFormats` + - - + Returns the `GdkDevice` associated to the `GdkDrag` object. - + filename="gdk/gdkdmabufformats.c" + line="79">Decreases the reference count of @formats. + +When the reference count reaches zero, +the object is freed. + + + + + + a `GdkDmabufFormats` + + + + + + + A `GdkTexture` representing a DMA buffer. + +To create a `GdkDmabufTexture`, use the auxiliary +[class@Gdk.DmabufTextureBuilder] object. + +Dma-buf textures can only be created on Linux. + + + + + + + Constructs [class@Gdk.Texture] objects from DMA buffers. + +DMA buffers are commonly called **_dma-bufs_**. + +DMA buffers are a feature of the Linux kernel to enable efficient buffer and +memory sharing between hardware such as codecs, GPUs, displays, cameras and the +kernel drivers controlling them. For example, a decoder may want its output to +be directly shared with the display server for rendering without a copy. + +Any device driver which participates in DMA buffer sharing, can do so as either +the exporter or importer of buffers (or both). + +The memory that is shared via DMA buffers is usually stored in non-system memory +(maybe in device's local memory or something else not directly accessible by the +CPU), and accessing this memory from the CPU may have higher-than-usual overhead. + +In particular for graphics data, it is not uncommon that data consists of multiple +separate blocks of memory, for example one block for each of the red, green and +blue channels. These blocks are called **_planes_**. DMA buffers can have up to +four planes. Even if the memory is a single block, the data can be organized in +multiple planes, by specifying offsets from the beginning of the data. + +DMA buffers are exposed to user-space as file descriptors allowing to pass them +between processes. If a DMA buffer has multiple planes, there is one file +descriptor per plane. + +The format of the data (for graphics data, essentially its colorspace) is described +by a 32-bit integer. These format identifiers are defined in the header file `drm_fourcc.h` +and commonly referred to as **_fourcc_** values, since they are identified by 4 ASCII +characters. Additionally, each DMA buffer has a **_modifier_**, which is a 64-bit integer +that describes driver-specific details of the memory layout, such as tiling or compression. + +For historical reasons, some producers of dma-bufs don't provide an explicit modifier, but +instead return `DMA_FORMAT_MOD_INVALID` to indicate that their modifier is **_implicit_**. +GTK tries to accommodate this situation by accepting `DMA_FORMAT_MOD_INVALID` as modifier. + +The operation of `GdkDmabufTextureBuilder` is quite simple: Create a texture builder, +set all the necessary properties, and then call [method@Gdk.DmabufTextureBuilder.build] +to create the new texture. + +The required properties for a dma-buf texture are + + * The width and height in pixels + + * The `fourcc` code and `modifier` which identify the format and memory layout of the dma-buf + + * The file descriptor, offset and stride for each of the planes + +`GdkDmabufTextureBuilder` can be used for quick one-shot construction of +textures as well as kept around and reused to construct multiple textures. + +For further information, see + +* The Linux kernel [documentation](https://docs.kernel.org/driver-api/dma-buf.html) + +* The header file [drm_fourcc.h](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/include/drm/drm_fourcc.h) + + + Creates a new texture builder. + + The `GdkDevice` associated to @drag. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="419">the new `GdkTextureBuilder` + + + + + Builds a new `GdkTexture` with the values set up in the builder. + +It is a programming error to call this function if any mandatory property has not been set. + +Not all formats defined in the `drm_fourcc.h` header are supported. You can use +[method@Gdk.Display.get_dmabuf_formats] to get a list of supported formats. If the +format is not supported by GTK, %NULL will be returned and @error will be set. + +The `destroy` function gets called when the returned texture gets released. + +It is the responsibility of the caller to keep the file descriptors for the planes +open until the created texture is no longer used, and close them afterwards (possibly +using the @destroy notify). + +It is possible to call this function multiple times to create multiple textures, +possibly with changing properties in between. + + + a newly built `GdkTexture` or `NULL` + if the format is not supported + - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="1019">a `GdkDmabufTextureBuilder` + + + + destroy function to be called when the texture is + released + + + + user data to pass to the destroy function + + + + + + Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state(). + + + the color state + + + + + a `GdkDmabufTextureBuilder` + - + c:identifier="gdk_dmabuf_texture_builder_get_display" + glib:get-property="display" + version="4.14"> Gets the `GdkDisplay` that the drag object was created for. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="429">Returns the display that this texture builder is +associated with. + a `GdkDisplay` + filename="gdk/gdkdmabuftexturebuilder.c" + line="436">the display - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="431">a `GdkDmabufTextureBuilder + - + Returns the surface on which the drag icon should be rendered -during the drag operation. + filename="gdk/gdkdmabuftexturebuilder.c" + line="735">Gets the file descriptor for a plane. + + + the file descriptor + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to get the fd for + + + + + + Gets the format previously set via gdk_dmabuf_texture_builder_set_fourcc() +or 0 if the format wasn't set. -Note that the surface may not be available until the drag operation -has begun. GDK will move the surface in accordance with the ongoing -drag operation. The surface is owned by @drag and will be destroyed -when the drag operation is over. - - +The format is specified as a fourcc code. + + the drag surface - + filename="gdk/gdkdmabuftexturebuilder.c" + line="569">The format + - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="562">a `GdkDmabufTextureBuilder` + - - + Retrieves the formats supported by this `GdkDrag` object. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="516">Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or +0 if the height wasn't set. + a `GdkContentFormats` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="523">The height + - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="518">a `GdkDmabufTextureBuilder` + - - + Determines the action chosen by the drag destination. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="608">Gets the modifier value. + a `GdkDragAction` value - + filename="gdk/gdkdmabuftexturebuilder.c" + line="614">the modifier + - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="610">a `GdkDmabufTextureBuilder` + - - + Returns the `GdkSurface` where the drag originates. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="649">Gets the number of planes. + The `GdkSurface` where the drag originates - + filename="gdk/gdkdmabuftexturebuilder.c" + line="655">The number of planes + - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="651">a `GdkDmabufTextureBuilder` + - + Sets the position of the drag surface that will be kept -under the cursor hotspot. - -Initially, the hotspot is at the top left corner of the drag surface. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="827">Gets the offset value for a plane. + - + the offset + - + a `GdkDrag` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="829">a `GdkDmabufTextureBuilder` + - + x coordinate of the drag surface hotspot - + filename="gdk/gdkdmabuftexturebuilder.c" + line="830">the plane to get the offset for + - + + + + Whether the data is premultiplied. + + + whether the data is premultiplied + + + + y coordinate of the drag surface hotspot - - + filename="gdk/gdkdmabuftexturebuilder.c" + line="669">a `GdkDmabufTextureBuilder` + + - - + The possible actions of this drag. - - - - - The `GdkContentProvider`. - - - - - The `GdkDevice` that is performing the drag. - - - - - The `GdkDisplay` that the drag belongs to. - - - - - The possible formats that the drag can provide its data in. - - - - - The currently selected action of the drag. - - - - - The surface where the drag originates. - - - - Emitted when the drag operation is cancelled. + filename="gdk/gdkdmabuftexturebuilder.c" + line="780">Gets the stride value for a plane. + - + the stride + - + The reason the drag was cancelled - + filename="gdk/gdkdmabuftexturebuilder.c" + line="782">a `GdkDmabufTextureBuilder` + + + + the plane to get the stride for + - - + + Emitted when the destination side has finished reading all data. - -The drag object can now free all miscellaneous data. + filename="gdk/gdkdmabuftexturebuilder.c" + line="963">Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or +%NULL if none was set. + + + The region + + + + + a `GdkDmabufTextureBuilder` + + + + + + Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or +%NULL if none was set. + + + The texture + + + + + a `GdkDmabufTextureBuilder` + + + + + + Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or +0 if the width wasn't set. + - + The width + - - + + + a `GdkDmabufTextureBuilder` + + + + + Emitted when the drop operation is performed on an accepting client. + filename="gdk/gdkdmabuftexturebuilder.c" + line="890">Sets the color state for the texture. + +By default, the colorstate is `NULL`. In that case, GTK will choose the +correct colorstate based on the format. +If you don't know what colorstates are, this is probably the right thing. + - - - - Used in `GdkDrop` and `GdkDrag` to indicate the actions that the -destination can and should do with the dropped data. - - Copy the data. - - - Move the data, i.e. first copy it, then delete - it from the source using the DELETE target of the X selection protocol. - - - Add a link to the data. Note that this is only - useful if source and destination agree on what it means, and is not - supported on all platforms. - - - Ask the user what to do with the data. - - + + + a `GdkDmabufTextureBuilder` + + + + a `GdkColorState` or `NULL` to unset the colorstate. + + + + + Checks if @action represents a single action or includes -multiple actions. + filename="gdk/gdkdmabuftexturebuilder.c" + line="448">Sets the display that this texture builder is +associated with. -When @action is 0 - ie no action was given, %TRUE -is returned. - +The display is used to determine the supported +dma-buf formats. + - %TRUE if exactly one action was given - + - + a `GdkDragAction` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="450">a `GdkDmabufTextureBuilder + + + + the display + - - - - Used in `GdkDrag` to the reason of a cancelled DND operation. - - There is no suitable drop target. - - - Drag cancelled by the user - - - Unspecified error. - - - - A `GdkDragSurface` is an interface for surfaces used during DND. - - - + + Present @drag_surface. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="756">Sets the file descriptor for a plane. + - %FALSE if it failed to be presented, otherwise %TRUE. - + - + the `GdkDragSurface` to show - + filename="gdk/gdkdmabuftexturebuilder.c" + line="758">a `GdkDmabufTextureBuilder` + - + the unconstrained drag_surface width to layout - + filename="gdk/gdkdmabuftexturebuilder.c" + line="759">the plane to set the fd for + - + the unconstrained drag_surface height to layout + filename="gdk/gdkdmabuftexturebuilder.c" + line="760">the file descriptor - + Emitted when the size for the surface needs to be computed, when it is -present. + filename="gdk/gdkdmabuftexturebuilder.c" + line="581">Sets the format of the texture. -This signal will normally be emitted during the native surface layout -cycle when the surface size needs to be recomputed. +The format is specified as a fourcc code. -It is the responsibility of the drag surface user to handle this signal -and compute the desired size of the surface, storing the computed size -in the [struct@Gdk.DragSurfaceSize] object that is passed to the signal -handler, using [method@Gdk.DragSurfaceSize.set_size]. +The format must be set before calling [method@Gdk.DmabufTextureBuilder.build]. + + + + + + + a `GdkDmabufTextureBuilder` + + + + the texture's format or 0 to unset + + + + + + Sets the height of the texture. -Failing to set a size so will result in an arbitrary size being used as -a result. +The height must be set before calling [method@Gdk.DmabufTextureBuilder.build]. + - + the size of the drag surface - + filename="gdk/gdkdmabuftexturebuilder.c" + line="537">a `GdkDmabufTextureBuilder` + + + + the texture's height or 0 to unset + - - - - The `GdkDragSurfaceInterface` implementation is private to GDK. - - - - The `GdkDragSurfaceSize` struct contains information that is useful -to compute the size of a drag surface. - - + + Sets the size the drag surface prefers to be resized to. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="626">Sets the modifier. + - + a `GdkDragSurfaceSize` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="628">a `GdkDmabufTextureBuilder` + - + the width - + filename="gdk/gdkdmabuftexturebuilder.c" + line="629">the modifier value + - + + + + Sets the number of planes of the texture. + + + + + + the height - + filename="gdk/gdkdmabuftexturebuilder.c" + line="713">a `GdkDmabufTextureBuilder` + + + + the number of planes + - - - Base class for objects implementing different rendering methods. - -`GdkDrawContext` is the base object used by contexts implementing different -rendering methods, such as [class@Gdk.CairoContext] or [class@Gdk.GLContext]. -It provides shared functionality between those contexts. - -You will always interact with one of those subclasses. - -A `GdkDrawContext` is always associated with a single toplevel surface. - + Indicates that you are beginning the process of redrawing @region -on the @context's surface. - -Calling this function begins a drawing operation using @context on the -surface that @context was created from. The actual requirements and -guarantees for the drawing operation vary for different implementations -of drawing, so a [class@Gdk.CairoContext] and a [class@Gdk.GLContext] -need to be treated differently. - -A call to this function is a requirement for drawing and must be -followed by a call to [method@Gdk.DrawContext.end_frame], which will -complete the drawing operation and ensure the contents become visible -on screen. - -Note that the @region passed to this function is the minimum region that -needs to be drawn and depending on implementation, windowing system and -hardware in use, it might be necessary to draw a larger region. Drawing -implementation must use [method@Gdk.DrawContext.get_frame_region] to -query the region that must be drawn. - -When using GTK, the widget system automatically places calls to -gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the -use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code -does not need to call these functions explicitly. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="848">Sets the offset for a plane. + - + the `GdkDrawContext` used to draw the frame. The context must - have a surface. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="850">a `GdkDmabufTextureBuilder` + - + minimum region that should be drawn - + filename="gdk/gdkdmabuftexturebuilder.c" + line="851">the plane to set the offset for + + + + the offset value + - + Ends a drawing operation started with gdk_draw_context_begin_frame(). - -This makes the drawing available on screen. -See [method@Gdk.DrawContext.begin_frame] for more details about drawing. + filename="gdk/gdkdmabuftexturebuilder.c" + line="685">Sets whether the data is premultiplied. -When using a [class@Gdk.GLContext], this function may call `glFlush()` -implicitly before returning; it is not recommended to call `glFlush()` -explicitly before calling this function. - +Unless otherwise specified, all formats including alpha channels are assumed +to be premultiplied. + - + a `GdkDrawContext` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="687">a `GdkDmabufTextureBuilder` + + + whether the data is premultiplied + + - - + Retrieves the `GdkDisplay` the @context is created for - - - the `GdkDisplay` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="801">Sets the stride for a plane. + +The stride must be set for all planes before calling [method@Gdk.DmabufTextureBuilder.build]. + + + - + a `GdkDrawContext` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="803">a `GdkDmabufTextureBuilder` + + + the plane to set the stride for + + + + the stride value + + - + Retrieves the region that is currently being repainted. + filename="gdk/gdkdmabuftexturebuilder.c" + line="982">Sets the region to be updated by this texture. Together with +[property@Gdk.DmabufTextureBuilder:update-texture] this describes an +update of a previous texture. -After a call to [method@Gdk.DrawContext.begin_frame] this function will -return a union of the region passed to that function and the area of the -surface that the @context determined needs to be repainted. +When rendering animations of large textures, it is possible that +consecutive textures are only updating contents in parts of the texture. +It is then possible to describe this update via these two properties, +so that GTK can avoid rerendering parts that did not change. -If @context is not in between calls to [method@Gdk.DrawContext.begin_frame] -and [method@Gdk.DrawContext.end_frame], %NULL will be returned. - - - a Cairo region - +An example would be a screen recording where only the mouse pointer moves. + + + - + a `GdkDrawContext` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="984">a `GdkDmabufTextureBuilder` + + + the region to update + + - - + Retrieves the surface that @context is bound to. - - - a `GdkSurface` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="940">Sets the texture to be updated by this texture. See +[method@Gdk.DmabufTextureBuilder.set_update_region] for an explanation. + + + - + a `GdkDrawContext` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="942">a `GdkDmabufTextureBuilder` + + + the texture to update + + - + Returns %TRUE if @context is in the process of drawing to its surface. + filename="gdk/gdkdmabuftexturebuilder.c" + line="491">Sets the width of the texture. -This is the case between calls to [method@Gdk.DrawContext.begin_frame] -and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands -may be effecting the contents of the @context's surface. - +The width must be set before calling [method@Gdk.DmabufTextureBuilder.build]. + - %TRUE if the context is between [method@Gdk.DrawContext.begin_frame] - and [method@Gdk.DrawContext.end_frame] calls. - + - + a `GdkDrawContext` - + filename="gdk/gdkdmabuftexturebuilder.c" + line="493">a `GdkDmabufTextureBuilder` + + + The texture's width or 0 to unset + + + + The color state of the texture. + + - The `GdkDisplay` used to create the `GdkDrawContext`. + filename="gdk/gdkdmabuftexturebuilder.c" + line="273">The display that this texture will be used on. - - + setter="set_fourcc" + getter="get_fourcc" + default-value="0"> The `GdkSurface` the context is bound to. - + filename="gdk/gdkdmabuftexturebuilder.c" + line="309">The format of the texture, as a fourcc value. + - - + The height of the texture. + + + + The modifier. + + + + The number of planes of the texture. + +Note that you can set properties for other planes, +but they will be ignored when constructing the texture. + + + + Whether the alpha channel is premultiplied into the others. + +Only relevant if the format has alpha. + + + + The update region for [property@Gdk.DmabufTextureBuilder:update-texture]. + + + + The texture [property@Gdk.DmabufTextureBuilder:update-region] is an update for. + + + + The width of the texture. + + + + + + + + + + + glib:type-name="GdkDrag" + glib:get-type="gdk_drag_get_type"> The `GdkDrop` object represents the target of an ongoing DND operation. - -Possible drop sites get informed about the status of the ongoing drag -operation with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, -%GDK_DRAG_MOTION and %GDK_DROP_START. The `GdkDrop` object can be obtained -from these [class@Gdk.Event] types using [method@Gdk.DNDEvent.get_drop]. + filename="gdk/gdkdrag.c" + line="25">Represents the source of an ongoing DND operation. -The actual data transfer is initiated from the target side via an async -read, using one of the `GdkDrop` methods for this purpose: -[method@Gdk.Drop.read_async] or [method@Gdk.Drop.read_value_async]. +A `GdkDrag` is created when a drag is started, and stays alive for duration of +the DND operation. After a drag has been started with [func@Gdk.Drag.begin], +the caller gets informed about the status of the ongoing drag operation +with signals on the `GdkDrag` object. GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the "Drag and Drop" section of the GTK documentation for more information. - + Ends the drag operation after a drop. + filename="gdk/gdksurface.c" + line="2417">Starts a drag and creates a new drag context for it. -The @action must be a single action selected from the actions -available via [method@Gdk.Drop.get_actions]. - +This function is called by the drag source. After this call, you +probably want to set up the drag icon using the surface returned +by [method@Gdk.Drag.get_drag_surface]. + +This function returns a reference to the [class@Gdk.Drag] object, +but GTK keeps its own reference as well, as long as the DND operation +is going on. + +Note: if @actions include %GDK_ACTION_MOVE, you need to listen for +the [signal@Gdk.Drag::dnd-finished] signal and delete the data at +the source if [method@Gdk.Drag.get_selected_action] returns +%GDK_ACTION_MOVE. + + + a newly created `GdkDrag` + + + + + the source surface for this drag + + + + the device that controls this drag + + + + the offered content + + + + the actions supported by this drag + + + + the x offset to @device's position where the drag nominally started + + + + the y offset to @device's position where the drag nominally started + + + + + + Informs GDK that the drop ended. + +Passing %FALSE for @success may trigger a drag cancellation +animation. + +This function is called by the drag source, and should be the +last call before dropping the reference to the @drag. + +The `GdkDrag` will only take the first [method@Gdk.Drag.drop_done] +call as effective, if this function is called multiple times, +all subsequent calls will be ignored. + - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="706">a `GdkDrag` + - + the action performed by the destination or 0 if the drop failed - + filename="gdk/gdkdrag.c" + line="707">whether the drag was ultimatively successful + - Returns the possible actions for this `GdkDrop`. - -If this value contains multiple actions - i.e. -[func@Gdk.DragAction.is_unique] returns %FALSE for the result - -[method@Gdk.Drop.finish] must choose the action to use when -accepting the drop. This will only happen if you passed -%GDK_ACTION_ASK as one of the possible actions in -[method@Gdk.Drop.status]. %GDK_ACTION_ASK itself will not -be included in the actions returned by this function. - -This value may change over the lifetime of the [class@Gdk.Drop] -both as a response to source side actions as well as to calls to -[method@Gdk.Drop.status] or [method@Gdk.Drop.finish]. The source -side will not change this value anymore once a drop has started. - + filename="gdk/gdkdrag.c" + line="130">Determines the bitmask of possible actions proposed by the source. + The possible `GdkDragActions` + filename="gdk/gdkdrag.c" + line="136">the `GdkDragAction` flags - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="132">a `GdkDrag` + + + + + + Returns the `GdkContentProvider` associated to the `GdkDrag` object. + + + The `GdkContentProvider` associated to @drag. + + + + + a `GdkDrag` + - Returns the `GdkDevice` performing the drop. - + filename="gdk/gdkdrag.c" + line="166">Returns the `GdkDevice` associated to the `GdkDrag` object. + The `GdkDevice` performing the drop. + filename="gdk/gdkdrag.c" + line="172">The `GdkDevice` associated to @drag. - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="168">a `GdkDrag` + - Gets the `GdkDisplay` that @self was created for. - + filename="gdk/gdkdrag.c" + line="94">Gets the `GdkDisplay` that the drag object was created for. + a `GdkDisplay` + filename="gdk/gdkdrag.c" + line="100">a `GdkDisplay` - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="96">a `GdkDrag` + - - + If this is an in-app drag-and-drop operation, returns the `GdkDrag` -that corresponds to this drop. + filename="gdk/gdkdrag.c" + line="657">Returns the surface on which the drag icon should be rendered +during the drag operation. -If it is not, %NULL is returned. - +Note that the surface may not be available until the drag operation +has begun. GDK will move the surface in accordance with the ongoing +drag operation. The surface is owned by @drag and will be destroyed +when the drag operation is over. + the corresponding `GdkDrag` - + filename="gdk/gdkdrag.c" + line="669">the drag surface + - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="659">a `GdkDrag` + - Returns the `GdkContentFormats` that the drop offers the data -to be read in. - + filename="gdk/gdkdrag.c" + line="112">Retrieves the formats supported by this `GdkDrag` object. + The possible `GdkContentFormats` + filename="gdk/gdkdrag.c" + line="118">a `GdkContentFormats` - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="114">a `GdkDrag` + - - + Returns the `GdkSurface` performing the drop. - + filename="gdk/gdkdrag.c" + line="148">Determines the action chosen by the drag destination. + The `GdkSurface` performing the drop. - + filename="gdk/gdkdrag.c" + line="154">a `GdkDragAction` value + - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="150">a `GdkDrag` + - + Asynchronously read the dropped data from a `GdkDrop` -in a format that complies with one of the mime types. - + filename="gdk/gdkdrag.c" + line="202">Returns the `GdkSurface` where the drag originates. + - + The `GdkSurface` where the drag originates + - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="204">a `GdkDrag` + - - - pointer to an array of mime types - - - - - - the I/O priority for the read operation - - - - optional `GCancellable` object - - - - a `GAsyncReadyCallback` to call when - the request is satisfied - - - - the data to pass to @callback - - - + Finishes an async drop read operation. - -Note that you must not use blocking read calls on the returned stream -in the GTK thread, since some platforms might require communication with -GTK to complete the data transfer. You can use async APIs such as -g_input_stream_read_bytes_async(). + filename="gdk/gdkdrag.c" + line="682">Sets the position of the drag surface that will be kept +under the cursor hotspot. -See [method@Gdk.Drop.read_async]. - - - the `GInputStream` - +Initially, the hotspot is at the top left corner of the drag surface. + + + - + a `GdkDrop` - + filename="gdk/gdkdrag.c" + line="684">a `GdkDrag` + - + a `GAsyncResult` - + filename="gdk/gdkdrag.c" + line="685">x coordinate of the drag surface hotspot + - + return location for the used mime type - + filename="gdk/gdkdrag.c" + line="686">y coordinate of the drag surface hotspot + - + Asynchronously request the drag operation's contents converted -to the given @type. - -When the operation is finished @callback will be called. You must -then call [method@Gdk.Drop.read_value_finish] to get the resulting -`GValue`. - -For local drag-and-drop operations that are available in the given -`GType`, the value will be copied directly. Otherwise, GDK will -try to use [func@Gdk.content_deserialize_async] to convert the data. - + filename="gdk/gdkdrag.c" + line="428">The possible actions of this drag. + + + + The `GdkContentProvider`. + + + + The `GdkDevice` that is performing the drag. + + + + The `GdkDisplay` that the drag belongs to. + + + + The possible formats that the drag can provide its data in. + + + + The currently selected action of the drag. + + + + The surface where the drag originates. + + + + Emitted when the drag operation is cancelled. - + a `GdkDrop` - - - - a `GType` to read - - - - the I/O priority of the request. - - - - optional `GCancellable` object, %NULL to ignore. - - - - callback to call when the request is satisfied - + filename="gdk/gdkdrag.c" + line="457">The reason the drag was cancelled + - + + + + Emitted when the destination side has finished reading all data. + +The drag object can now free all miscellaneous data. + + + + + + Emitted when the drop operation is performed on an accepting client. + + + + + + + Used in `GdkDrop` and `GdkDrag` to indicate the actions that the +destination can and should do with the dropped data. + + Copy the data. + + + Move the data, i.e. first copy it, then delete + it from the source using the DELETE target of the X selection protocol. + + + Add a link to the data. Note that this is only + useful if source and destination agree on what it means, and is not + supported on all platforms. + + + Ask the user what to do with the data. + + + Checks if @action represents a single action or includes +multiple actions. + +When @action is 0 - ie no action was given, %TRUE +is returned. + + + %TRUE if exactly one action was given + + + + the data to pass to callback function - + filename="gdk/gdkdrag.c" + line="809">a `GdkDragAction` + - - + + + + Used in `GdkDrag` to the reason of a cancelled DND operation. + Finishes an async drop read. - -See [method@Gdk.Drop.read_value_async]. - + filename="gdk/gdkdrag.h" + line="43">There is no suitable drop target. + + + Drag cancelled by the user + + + Unspecified error. + + + + A surface that is used during DND. + + + + Present @drag_surface. + a `GValue` containing the result. - + filename="gdk/gdkdragsurface.c" + line="109">%FALSE if it failed to be presented, otherwise %TRUE. + - + a `GdkDrop` - + filename="gdk/gdkdragsurface.c" + line="103">the `GdkDragSurface` to show + - + a `GAsyncResult` - + filename="gdk/gdkdragsurface.c" + line="104">the unconstrained drag_surface width to layout + + + + the unconstrained drag_surface height to layout + - + Selects all actions that are potentially supported by the destination. + filename="gdk/gdkdragsurface.c" + line="69">Emitted when the size for the surface needs to be computed, when it is +present. -When calling this function, do not restrict the passed in actions to -the ones provided by [method@Gdk.Drop.get_actions]. Those actions may -change in the future, even depending on the actions you provide here. +This signal will normally be emitted during the native surface layout +cycle when the surface size needs to be recomputed. -The @preferred action is a hint to the drag-and-drop mechanism about which -action to use when multiple actions are possible. +It is the responsibility of the drag surface user to handle this signal +and compute the desired size of the surface, storing the computed size +in the [struct@Gdk.DragSurfaceSize] object that is passed to the signal +handler, using [method@Gdk.DragSurfaceSize.set_size]. -This function should be called by drag destinations in response to -%GDK_DRAG_ENTER or %GDK_DRAG_MOTION events. If the destination does -not yet know the exact actions it supports, it should set any possible -actions first and then later call this function again. - +Failing to set a size so will result in an arbitrary size being used as +a result. - - a `GdkDrop` - - - - Supported actions of the destination, or 0 to indicate - that a drop will not be accepted - - - + A unique action that's a member of @actions indicating the - preferred action - + filename="gdk/gdkdragsurface.c" + line="72">the size of the drag surface + - - - - The possible actions for this drop - - - - - The `GdkDevice` performing the drop - - - - - The `GdkDisplay` that the drop belongs to. - - - - - The `GdkDrag` that initiated this drop - - - - - The possible formats that the drop can provide its data in. - - - - - The `GdkSurface` the drop happens on - - - - - - - - - - - - Use this macro as the return value for continuing the propagation of -an event handler. - - - - + + + Use this macro as the return value for stopping the propagation of -an event handler. - - - - + filename="gdk/gdkdragsurface.c" + line="32">The `GdkDragSurfaceInterface` implementation is private to GDK. + + + `GdkEvent`s are immutable data structures, created by GDK to -represent windowing system events. - -In GTK applications the events are handled automatically by toplevel -widgets and passed on to the event controllers of appropriate widgets, -so using `GdkEvent` and its related API is rarely needed. - + filename="gdk/gdkdragsurfacesize.c" + line="23">Contains information that is useful to compute the size of a drag surface. + + Returns the relative angle from @event1 to @event2. - -The relative angle is the angle between the X axis and the line -through both events' positions. The rotation direction for positive -angles is from the positive X axis towards the positive Y axis. - -This assumes that both events have X/Y information. -If not, this function returns %FALSE. - + filename="gdk/gdkdragsurfacesize.c" + line="39">Sets the size the drag surface prefers to be resized to. + - %TRUE if the angle could be calculated. - + - + first `GdkEvent` - + filename="gdk/gdkdragsurfacesize.c" + line="41">a `GdkDragSurfaceSize` + - + second `GdkEvent` - + filename="gdk/gdkdragsurfacesize.c" + line="42">the width + - + return location for the relative angle between both events - + filename="gdk/gdkdragsurfacesize.c" + line="43">the height + - + + + Base class for objects implementing different rendering methods. + +`GdkDrawContext` is the base object used by contexts implementing different +rendering methods, such as [class@Gdk.CairoContext] or [class@Gdk.GLContext]. +It provides shared functionality between those contexts. + +You will always interact with one of those subclasses. + +A `GdkDrawContext` is always associated with a single toplevel surface. + Returns the point halfway between the events' positions. + filename="gdk/gdkdrawcontext.c" + line="289">Indicates that you are beginning the process of redrawing @region +on the @context's surface. -This assumes that both events have X/Y information. -If not, this function returns %FALSE. - +Calling this function begins a drawing operation using @context on the +surface that @context was created from. The actual requirements and +guarantees for the drawing operation vary for different implementations +of drawing, so a [class@Gdk.CairoContext] and a [class@Gdk.GLContext] +need to be treated differently. + +A call to this function is a requirement for drawing and must be +followed by a call to [method@Gdk.DrawContext.end_frame], which will +complete the drawing operation and ensure the contents become visible +on screen. + +Note that the @region passed to this function is the minimum region that +needs to be drawn and depending on implementation, windowing system and +hardware in use, it might be necessary to draw a larger region. Drawing +implementation must use [method@Gdk.DrawContext.get_frame_region] to +query the region that must be drawn. + +When using GTK, the widget system automatically places calls to +gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the +use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code +does not need to call these functions explicitly. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. + - %TRUE if the center could be calculated. - + - + first `GdkEvent` - + filename="gdk/gdkdrawcontext.c" + line="291">the `GdkDrawContext` used to draw the frame. The context must + have a surface. + - - second `GdkEvent` - - - - return location for the X coordinate of the center - - - + return location for the Y coordinate of the center - + filename="gdk/gdkdrawcontext.c" + line="293">minimum region that should be drawn + - + Returns the distance between the event locations. + filename="gdk/gdkdrawcontext.c" + line="450">Ends a drawing operation started with gdk_draw_context_begin_frame(). -This assumes that both events have X/Y information. -If not, this function returns %FALSE. - +This makes the drawing available on screen. +See [method@Gdk.DrawContext.begin_frame] for more details about drawing. + +When using a [class@Gdk.GLContext], this function may call `glFlush()` +implicitly before returning; it is not recommended to call `glFlush()` +explicitly before calling this function. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. + - %TRUE if the distance could be calculated. - + - + first `GdkEvent` - + filename="gdk/gdkdrawcontext.c" + line="452">a `GdkDrawContext` + - - second `GdkEvent` - - - - return location for the distance - - - + Extracts all axis values from an event. - -To find out which axes are used, use [method@Gdk.DeviceTool.get_axes] -on the device tool returned by [method@Gdk.Event.get_device_tool]. - - + filename="gdk/gdkdrawcontext.c" + line="253">Retrieves the `GdkDisplay` the @context is created for + + %TRUE on success, otherwise %FALSE - + filename="gdk/gdkdrawcontext.c" + line="259">the `GdkDisplay` + - + a `GdkEvent` - + filename="gdk/gdkdrawcontext.c" + line="255">a `GdkDrawContext` + - - the array of values for all axes - - - - - - the length of array - - - + Extract the axis value for a particular axis use from -an event structure. + filename="gdk/gdkdrawcontext.c" + line="495">Retrieves the region that is currently being repainted. -To find out which axes are used, use [method@Gdk.DeviceTool.get_axes] -on the device tool returned by [method@Gdk.Event.get_device_tool]. - - +After a call to [method@Gdk.DrawContext.begin_frame] this function will +return a union of the region passed to that function and the area of the +surface that the @context determined needs to be repainted. + +If @context is not in between calls to [method@Gdk.DrawContext.begin_frame] +and [method@Gdk.DrawContext.end_frame], %NULL will be returned. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. + + %TRUE if the specified axis was found, otherwise %FALSE - + filename="gdk/gdkdrawcontext.c" + line="508">a Cairo region + - + a `GdkEvent` - + filename="gdk/gdkdrawcontext.c" + line="497">a `GdkDrawContext` + - - the axis use to look for - - - - location to store the value found - - - + Returns the device of an event. - + filename="gdk/gdkdrawcontext.c" + line="271">Retrieves the surface that @context is bound to. + a `GdkDevice` - + filename="gdk/gdkdrawcontext.c" + line="277">a `GdkSurface` + - + a `GdkEvent`. - + filename="gdk/gdkdrawcontext.c" + line="273">a `GdkDrawContext` + - + Returns a `GdkDeviceTool` representing the tool that -caused the event. - -If the was not generated by a device that supports -different tools (such as a tablet), this function will -return %NULL. + filename="gdk/gdkdrawcontext.c" + line="214">Returns %TRUE if @context is in the process of drawing to its surface. -Note: the `GdkDeviceTool` will be constant during -the application lifetime, if settings must be stored -persistently across runs, see [method@Gdk.DeviceTool.get_serial]. - - +This is the case between calls to [method@Gdk.DrawContext.begin_frame] +and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands +may be effecting the contents of the @context's surface. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. + + The current device tool - + filename="gdk/gdkdrawcontext.c" + line="224">%TRUE if the context is between [method@Gdk.DrawContext.begin_frame] + and [method@Gdk.DrawContext.end_frame] calls. + - + a `GdkEvent` - + filename="gdk/gdkdrawcontext.c" + line="216">a `GdkDrawContext` + - + Retrieves the display associated to the @event. - - - a `GdkDisplay` - + filename="gdk/gdkdrawcontext.c" + line="174">The `GdkDisplay` used to create the `GdkDrawContext`. + + + + The `GdkSurface` the context is bound to. + + + + + Represents the target of an ongoing DND operation. + +Possible drop sites get informed about the status of the ongoing drag +operation with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, +%GDK_DRAG_MOTION and %GDK_DROP_START. The `GdkDrop` object can be obtained +from these [class@Gdk.Event] types using [method@Gdk.DNDEvent.get_drop]. + +The actual data transfer is initiated from the target side via an async +read, using one of the `GdkDrop` methods for this purpose: +[method@Gdk.Drop.read_async] or [method@Gdk.Drop.read_value_async]. + +GTK provides a higher level abstraction based on top of these functions, +and so they are not normally needed in GTK applications. See the +"Drag and Drop" section of the GTK documentation for more information. + + Ends the drag operation after a drop. + +The @action must be a single action selected from the actions +available via [method@Gdk.Drop.get_actions]. + + + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="592">a `GdkDrop` + + + the action performed by the destination or 0 if the drop failed + + - + Returns the event sequence to which the event belongs. + filename="gdk/gdkdrop.c" + line="481">Returns the possible actions for this `GdkDrop`. -Related touch events are connected in a sequence. Other -events typically don't have event sequence information. - +If this value contains multiple actions - i.e. +[func@Gdk.DragAction.is_unique] returns %FALSE for the result - +[method@Gdk.Drop.finish] must choose the action to use when +accepting the drop. This will only happen if you passed +%GDK_ACTION_ASK as one of the possible actions in +[method@Gdk.Drop.status]. %GDK_ACTION_ASK itself will not +be included in the actions returned by this function. + +This value may change over the lifetime of the [class@Gdk.Drop] +both as a response to source side actions as well as to calls to +[method@Gdk.Drop.status] or [method@Gdk.Drop.finish]. The source +side will not change this value anymore once a drop has started. + the event sequence that the event belongs to - + filename="gdk/gdkdrop.c" + line="500">The possible `GdkDragActions` + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="483">a `GdkDrop` + - + Retrieves the type of the event. - + filename="gdk/gdkdrop.c" + line="426">Returns the `GdkDevice` performing the drop. + a `GdkEvent`Type - + filename="gdk/gdkdrop.c" + line="432">The `GdkDevice` performing the drop. + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="428">a `GdkDrop` + - + Retrieves the history of the device that @event is for, as a list of -time and coordinates. - -The history includes positions that are not delivered as separate events -to the application because they occurred in the same frame as @event. - -Note that only motion and scroll events record history, and motion -events do it only if one of the mouse buttons is down, or the device -has a tool. - - + filename="gdk/gdkdrop.c" + line="408">Gets the `GdkDisplay` that @self was created for. + + an - array of time and coordinates - - - + filename="gdk/gdkdrop.c" + line="414">a `GdkDisplay` + - + a motion or scroll event - + filename="gdk/gdkdrop.c" + line="410">a `GdkDrop` + - + + + + If this is an in-app drag-and-drop operation, returns the `GdkDrag` +that corresponds to this drop. + +If it is not, %NULL is returned. + + + the corresponding `GdkDrag` + + + + Return location for the length of the returned array - - + filename="gdk/gdkdrop.c" + line="532">a `GdkDrop` + + - + Returns the modifier state field of an event. - + filename="gdk/gdkdrop.c" + line="444">Returns the `GdkContentFormats` that the drop offers the data +to be read in. + the modifier state of @event - + filename="gdk/gdkdrop.c" + line="451">The possible `GdkContentFormats` + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="446">a `GdkDrop` + - + Returns whether this event is an 'emulated' pointer event. - -Emulated pointer events typically originate from a touch events. - + filename="gdk/gdkdrop.c" + line="463">Returns the `GdkSurface` performing the drop. + %TRUE if this event is emulated - + filename="gdk/gdkdrop.c" + line="469">The `GdkSurface` performing the drop. + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="465">a `GdkDrop` + - + Extract the event surface relative x/y coordinates from an event. - -This position is in [surface coordinates](coordinates.html). - + filename="gdk/gdkdrop.c" + line="647">Asynchronously read the dropped data from a `GdkDrop` +in a format that complies with one of the mime types. + - + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="649">a `GdkDrop` + - + location to put event surface x coordinate - + filename="gdk/gdkdrop.c" + line="650"> + pointer to an array of mime types + + + - + location to put event surface y coordinate - + filename="gdk/gdkdrop.c" + line="652">the I/O priority for the read operation + + + + optional `GCancellable` object + + + + a `GAsyncReadyCallback` to call when + the request is satisfied + + + + the data to pass to @callback + - + Returns the seat that originated the event. - - + filename="gdk/gdkdrop.c" + line="683">Finishes an async drop read operation. + +Note that you must not use blocking read calls on the returned stream +in the GTK thread, since some platforms might require communication with +GTK to complete the data transfer. You can use async APIs such as +g_input_stream_read_bytes_async(). + +See [method@Gdk.Drop.read_async]. + + a `GdkSeat`. - + filename="gdk/gdkdrop.c" + line="699">the `GInputStream` + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="685">a `GdkDrop` + + + a `GAsyncResult` + + + + return location for the used mime type + + - + Extracts the surface associated with an event. - - - The `GdkSurface` associated with the event - + filename="gdk/gdkdrop.c" + line="840">Asynchronously request the drag operation's contents converted +to the given @type. + +For local drag-and-drop operations that are available in the given +`GType`, the value will be copied directly. Otherwise, GDK will +try to use [func@Gdk.content_deserialize_async] to convert the data. + + + - + a `GdkEvent` - - + filename="gdk/gdkdrop.c" + line="842">a `GdkDrop` + + + + a `GType` to read + + + + the I/O priority of the request. + + + + optional `GCancellable` object, %NULL to ignore. + + + + callback to call when the request is satisfied + + + + the data to pass to callback function + + - + Returns the timestamp of @event. + filename="gdk/gdkdrop.c" + line="877">Finishes an async drop read. -Not all events have timestamps. In that case, this function -returns %GDK_CURRENT_TIME. - +See [method@Gdk.Drop.read_value_async]. + timestamp field from @event - + filename="gdk/gdkdrop.c" + line="887">a `GValue` containing the result. + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="879">a `GdkDrop` + + + a `GAsyncResult` + + - + Increase the ref count of @event. - - - @event - + filename="gdk/gdkdrop.c" + line="551">Selects all actions that are potentially supported by the destination. + +When calling this function, do not restrict the passed in actions to +the ones provided by [method@Gdk.Drop.get_actions]. Those actions may +change in the future, even depending on the actions you provide here. + +The @preferred action is a hint to the drag-and-drop mechanism about which +action to use when multiple actions are possible. + +This function should be called by drag destinations in response to +%GDK_DRAG_ENTER or %GDK_DRAG_MOTION events. If the destination does +not yet know the exact actions it supports, it should set any possible +actions first and then later call this function again. + + + - + a `GdkEvent` - + filename="gdk/gdkdrop.c" + line="553">a `GdkDrop` + + + Supported actions of the destination, or 0 to indicate + that a drop will not be accepted + + + + A unique action that's a member of @actions indicating the + preferred action + + - + + The possible actions for this drop + + + + The `GdkDevice` performing the drop + + + + The `GdkDisplay` that the drop belongs to. + + + + The `GdkDrag` that initiated this drop + + + + The possible formats that the drop can provide its data in. + + + + The `GdkSurface` the drop happens on + + + + + + + + + + + + Use this macro as the return value for continuing the propagation of +an event handler. + + + + + Use this macro as the return value for stopping the propagation of +an event handler. + + + + + Represents windowing system events. + +In GTK applications the events are handled automatically by toplevel +widgets and passed on to the event controllers of appropriate widgets, +so using `GdkEvent` and its related API is rarely needed. + +`GdkEvent` structs are immutable. + Returns whether a `GdkEvent` should trigger a context menu, -according to platform conventions. + line="1069">Returns the relative angle from @event1 to @event2. -The right mouse button typically triggers context menus. +The relative angle is the angle between the X axis and the line +through both events' positions. The rotation direction for positive +angles is from the positive X axis towards the positive Y axis. -This function should always be used instead of simply checking for -event->button == %GDK_BUTTON_SECONDARY. - +This assumes that both events have X/Y information. +If not, this function returns %FALSE. + %TRUE if the event should trigger a context menu. + line="1084">%TRUE if the angle could be calculated. - + a `GdkEvent`, currently only button events are meaningful values + line="1071">first `GdkEvent` + + second `GdkEvent` + + + + return location for the relative angle between both events + + - + Decrease the ref count of @event. + line="1115">Returns the point halfway between the events' positions. -If the last reference is dropped, the structure is freed. - +This assumes that both events have X/Y information. +If not, this function returns %FALSE. + - + %TRUE if the center could be calculated. + - + a `GdkEvent` + line="1117">first `GdkEvent` - + + second `GdkEvent` + + + + return location for the X coordinate of the center + + + + return location for the Y coordinate of the center + + + + + + Returns the distance between the event locations. + +This assumes that both events have X/Y information. +If not, this function returns %FALSE. + + + %TRUE if the distance could be calculated. + + + + + first `GdkEvent` + + + + second `GdkEvent` + + + + return location for the distance + + + + + + Extracts all axis values from an event. + +To find out which axes are used, use [method@Gdk.DeviceTool.get_axes] +on the device tool returned by [method@Gdk.Event.get_device_tool]. + + + %TRUE on success, otherwise %FALSE + + + + + a `GdkEvent` + + + + the array of values for all axes + + + + + + the length of array + + + + + + Extract the axis value for a particular axis use from +an event structure. + +To find out which axes are used, use [method@Gdk.DeviceTool.get_axes] +on the device tool returned by [method@Gdk.Event.get_device_tool]. + + + %TRUE if the specified axis was found, otherwise %FALSE + + + + + a `GdkEvent` + + + + the axis use to look for + + + + location to store the value found + + + + + + Returns the device of an event. + + + a `GdkDevice` + + + + + a `GdkEvent`. + + + + + + Returns a `GdkDeviceTool` representing the tool that +caused the event. + +If the was not generated by a device that supports +different tools (such as a tablet), this function will +return %NULL. + +Note: the `GdkDeviceTool` will be constant during +the application lifetime, if settings must be stored +persistently across runs, see [method@Gdk.DeviceTool.get_serial]. + + + The current device tool + + + + + a `GdkEvent` + + + + + + Retrieves the display associated to the @event. + + + a `GdkDisplay` + + + + + a `GdkEvent` + + + + + + Returns the event sequence to which the event belongs. + +Related touch events are connected in a sequence. Other +events typically don't have event sequence information. + + + the event sequence that the event belongs to + + + + + a `GdkEvent` + + + + + + Retrieves the type of the event. + + + a `GdkEvent`Type + + + + + a `GdkEvent` + + + + + + Retrieves the history of the device that @event is for, as a list of +time and coordinates. + +The history includes positions that are not delivered as separate events +to the application because they occurred in the same frame as @event. + +Note that only motion and scroll events record history, and motion +events do it only if one of the mouse buttons is down, or the device +has a tool. + + + an + array of time and coordinates + + + + + + + a motion or scroll event + + + + Return location for the length of the returned array + + + + + + Returns the modifier state field of an event. + + + the modifier state of @event + + + + + a `GdkEvent` + + + + + + Returns whether this event is an 'emulated' pointer event. + +Emulated pointer events typically originate from a touch events. + + + %TRUE if this event is emulated + + + + + a `GdkEvent` + + + + + + Extract the event surface relative x/y coordinates from an event. + +This position is in [surface coordinates](coordinates.html). + + + whether the positions were set + + + + + a `GdkEvent` + + + + location to put event surface x coordinate + + + + location to put event surface y coordinate + + + + + + Returns the seat that originated the event. + + + a `GdkSeat`. + + + + + a `GdkEvent` + + + + + + Extracts the surface associated with an event. + + + The `GdkSurface` associated with the event + + + + + a `GdkEvent` + + + + + + Returns the timestamp of @event. + +Not all events have timestamps. In that case, this function +returns %GDK_CURRENT_TIME. + + + timestamp field from @event + + + + + a `GdkEvent` + + + + + + Increase the ref count of @event. + + + @event + + + + + a `GdkEvent` + + + + + + Returns whether a `GdkEvent` should trigger a context menu, +according to platform conventions. + +The right mouse button typically triggers context menus. +On macOS, Control+left mouse button also triggers. + +This function should always be used instead of simply checking for + +```c +event->button == GDK_BUTTON_SECONDARY +``` + + + %TRUE if the event should trigger a context menu. + + + + + a `GdkEvent`, currently only button events are meaningful values + + + + + + Decrease the ref count of @event. + +If the last reference is dropped, the structure is freed. + + + + + + + a `GdkEvent` + + + c:symbol-prefix="event_sequence"> `GdkEventSequence` is an opaque type representing a sequence -of related touch events. + line="53">An opaque type representing a sequence of related events. A touchpad hold gesture event, the current state - is determined by its phase field. Since: 4.6 + line="172">A touchpad hold gesture event, the current state is determined by its phase +field. glib:name="GDK_EVENT_LAST"> marks the end of the GdkEventType enumeration. + line="168">marks the end of the GdkEventType enumeration. c:symbol-prefix="file_list"> An opaque type representing a list of files. - + line="117">An opaque type representing a list of files. + Creates a new `GdkFileList` for the given array of files. + line="911">Creates a new `GdkFileList` for the given array of files. This function is meant to be used by language bindings. - + the newly create files list + line="920">the newly create files list the files to add to the list + line="913">the files to add to the list @@ -9128,7 +11291,7 @@ This function is meant to be used by language bindings. the number of files in the array + line="914">the number of files in the array @@ -9138,22 +11301,22 @@ This function is meant to be used by language bindings. version="4.8"> Creates a new files list container from a singly linked list of + line="892">Creates a new files list container from a singly linked list of `GFile` instances. This function is meant to be used by language bindings - + the newly created files list + line="901">the newly created files list a list of files + line="894">a list of files @@ -9165,14 +11328,14 @@ This function is meant to be used by language bindings version="4.6"> Retrieves the list of files inside a `GdkFileList`. + line="874">Retrieves the list of files inside a `GdkFileList`. This function is meant for language bindings. - + the files inside the list + line="882">the files inside the list @@ -9181,7 +11344,7 @@ This function is meant for language bindings. the file list + line="876">the file list @@ -9196,24 +11359,24 @@ This function is meant for language bindings. glib:fundamental="1"> An event related to a keyboard focus change. + line="2298">An event related to a keyboard focus change. Extracts whether this event is about focus entering or + line="2331">Extracts whether this event is about focus entering or leaving the surface. - + %TRUE of the focus is entering + line="2338">%TRUE of the focus is entering a focus change event + line="2333">a focus change event @@ -9229,8 +11392,7 @@ leaving the surface. glib:type-struct="FrameClockClass"> A `GdkFrameClock` tells the application when to update and repaint -a surface. + line="29">Tells the application when to update and repaint a surface. This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based @@ -9267,7 +11429,7 @@ they will stay exactly synchronized. c:identifier="gdk_frame_clock_begin_updating"> Starts updates for an animation. + line="321">Starts updates for an animation. Until a matching call to [method@Gdk.FrameClock.end_updating] is made, the frame clock will continually request a new frame with the @@ -9282,7 +11444,7 @@ is called the same number of times. a `GdkFrameClock` + line="323">a `GdkFrameClock` @@ -9290,7 +11452,7 @@ is called the same number of times. Stops updates for an animation. + line="341">Stops updates for an animation. See the documentation for [method@Gdk.FrameClock.begin_updating]. @@ -9301,7 +11463,7 @@ See the documentation for [method@Gdk.FrameClock.begin_updating]. a `GdkFrameClock` + line="343">a `GdkFrameClock` @@ -9310,12 +11472,12 @@ See the documentation for [method@Gdk.FrameClock.begin_updating]. c:identifier="gdk_frame_clock_get_current_timings"> Gets the frame timings for the current frame. + line="541">Gets the frame timings for the current frame. the `GdkFrameTimings` for the + line="547">the `GdkFrameTimings` for the frame currently being processed, or even no frame is being processed, for the previous frame. Before any frames have been processed, returns %NULL. @@ -9325,7 +11487,7 @@ See the documentation for [method@Gdk.FrameClock.begin_updating]. a `GdkFrameClock` + line="543">a `GdkFrameClock` @@ -9333,20 +11495,20 @@ See the documentation for [method@Gdk.FrameClock.begin_updating]. Calculates the current frames-per-second, based on the + line="786">Calculates the current frames-per-second, based on the frame timings of @frame_clock. the current fps, as a `double` + line="793">the current fps, as a `double` a `GdkFrameClock` + line="788">a `GdkFrameClock` @@ -9355,13 +11517,13 @@ frame timings of @frame_clock. c:identifier="gdk_frame_clock_get_frame_counter"> `GdkFrameClock` maintains a 64-bit counter that increments for + line="403">`GdkFrameClock` maintains a 64-bit counter that increments for each frame drawn. inside frame processing, the value of the frame counter + line="410">inside frame processing, the value of the frame counter for the current frame. Outside of frame processing, the frame counter for the last frame. @@ -9370,7 +11532,7 @@ each frame drawn. a `GdkFrameClock` + line="405">a `GdkFrameClock` @@ -9379,7 +11541,7 @@ each frame drawn. c:identifier="gdk_frame_clock_get_frame_time"> Gets the time that should currently be used for animations. + line="272">Gets the time that should currently be used for animations. Inside the processing of a frame, it’s the time used to compute the animation position of everything in a frame. Outside of a frame, it's @@ -9390,7 +11552,7 @@ time. a timestamp in microseconds, in the timescale of + line="284">a timestamp in microseconds, in the timescale of of g_get_monotonic_time(). @@ -9398,7 +11560,7 @@ time. a `GdkFrameClock` + line="274">a `GdkFrameClock` @@ -9407,7 +11569,7 @@ time. c:identifier="gdk_frame_clock_get_history_start"> Returns the frame counter for the oldest frame available in history. + line="428">Returns the frame counter for the oldest frame available in history. `GdkFrameClock` internally keeps a history of `GdkFrameTimings` objects for recent frames that can be retrieved with @@ -9419,7 +11581,7 @@ is the set from the counter values given by the frame counter value for the oldest frame + line="441">the frame counter value for the oldest frame that is available in the internal frame history of the `GdkFrameClock` @@ -9428,7 +11590,7 @@ is the set from the counter values given by a `GdkFrameClock` + line="430">a `GdkFrameClock` @@ -9437,7 +11599,7 @@ is the set from the counter values given by c:identifier="gdk_frame_clock_get_refresh_info"> Predicts a presentation time, based on history. + line="614">Predicts a presentation time, based on history. Using the frame history stored in the frame clock, finds the last known presentation time and refresh interval, and assuming that @@ -9452,13 +11614,13 @@ interval after the last presentation time, and later than @base_time. a `GdkFrameClock` + line="616">a `GdkFrameClock` base time for determining a presentaton time + line="617">base time for determining a presentaton time allow-none="1"> a location to store the + line="618">a location to store the determined refresh interval, or %NULL. A default refresh interval of 1/60th of a second will be stored if no history is present. @@ -9480,7 +11642,7 @@ interval after the last presentation time, and later than @base_time. transfer-ownership="full"> a location to store the next + line="621">a location to store the next candidate presentation time after the given base time. 0 will be will be stored if no history is present. @@ -9490,7 +11652,7 @@ interval after the last presentation time, and later than @base_time. Retrieves a `GdkFrameTimings` object holding timing information + line="516">Retrieves a `GdkFrameTimings` object holding timing information for the current frame or a recent frame. The `GdkFrameTimings` object may not yet be complete: see @@ -9500,7 +11662,7 @@ The `GdkFrameTimings` object may not yet be complete: see the `GdkFrameTimings` object + line="529">the `GdkFrameTimings` object for the specified frame, or %NULL if it is not available @@ -9508,13 +11670,13 @@ The `GdkFrameTimings` object may not yet be complete: see a `GdkFrameClock` + line="518">a `GdkFrameClock` the frame counter value identifying the frame to + line="519">the frame counter value identifying the frame to be received @@ -9524,7 +11686,7 @@ The `GdkFrameTimings` object may not yet be complete: see c:identifier="gdk_frame_clock_request_phase"> Asks the frame clock to run a particular phase. + line="295">Asks the frame clock to run a particular phase. The signal corresponding the requested phase will be emitted the next time the frame clock processes. Multiple calls to @@ -9543,13 +11705,13 @@ smooth animations. a `GdkFrameClock` + line="297">a `GdkFrameClock` the phase that is requested + line="298">the phase that is requested @@ -9557,7 +11719,7 @@ smooth animations. This signal ends processing of the frame. + line="223">This signal ends processing of the frame. Applications should generally not handle this signal. @@ -9567,7 +11729,7 @@ Applications should generally not handle this signal. Begins processing of the frame. + line="149">Begins processing of the frame. Applications should generally not handle this signal. @@ -9577,7 +11739,7 @@ Applications should generally not handle this signal. Used to flush pending motion events that are being batched up and + line="132">Used to flush pending motion events that are being batched up and compressed together. Applications should not handle this signal. @@ -9588,7 +11750,7 @@ Applications should not handle this signal. Emitted as the second step of toolkit and application processing + line="185">Emitted as the second step of toolkit and application processing of the frame. Any work to update sizes and positions of application elements @@ -9600,7 +11762,7 @@ should be performed. GTK normally handles this internally. Emitted as the third step of toolkit and application processing + line="203">Emitted as the third step of toolkit and application processing of the frame. The frame is repainted. GDK normally handles this internally and @@ -9614,7 +11776,7 @@ by GTK. Emitted after processing of the frame is finished. + line="239">Emitted after processing of the frame is finished. This signal is handled internally by GTK to resume normal event processing. Applications should not handle this signal. @@ -9625,7 +11787,7 @@ event processing. Applications should not handle this signal. Emitted as the first step of toolkit and application processing + line="165">Emitted as the first step of toolkit and application processing of the frame. Animations should be updated using [method@Gdk.FrameClock.get_frame_time]. @@ -9740,8 +11902,7 @@ The elements of the enumeration correspond to the signals of `GdkFrameClock`. A `GdkFrameTimings` object holds timing information for a single frame -of the application’s displays. + line="24">Holds timing information for a single frame of the application’s displays. To retrieve `GdkFrameTimings` objects, use [method@Gdk.FrameClock.get_timings] or [method@Gdk.FrameClock.get_current_timings]. The information in @@ -9753,7 +11914,7 @@ application’s display, such as latency and jitter. c:identifier="gdk_frame_timings_get_complete"> Returns whether @timings are complete. + line="119">Returns whether @timings are complete. The timing information in a `GdkFrameTimings` is filled in incrementally as the frame as drawn and passed off to the @@ -9770,7 +11931,7 @@ stored in the `GdkFrameTimings`. %TRUE if all information that will be available + line="137">%TRUE if all information that will be available for the frame has been filled in. @@ -9778,7 +11939,7 @@ stored in the `GdkFrameTimings`. a `GdkFrameTimings` + line="121">a `GdkFrameTimings` @@ -9787,20 +11948,20 @@ stored in the `GdkFrameTimings`. c:identifier="gdk_frame_timings_get_frame_counter"> Gets the frame counter value of the `GdkFrameClock` when + line="104">Gets the frame counter value of the `GdkFrameClock` when this frame was drawn. the frame counter value for this frame + line="111">the frame counter value for this frame a `GdkFrameTimings` + line="106">a `GdkFrameTimings` @@ -9809,7 +11970,7 @@ this frame was drawn. c:identifier="gdk_frame_timings_get_frame_time"> Returns the frame time for the frame. + line="148">Returns the frame time for the frame. This is the time value that is typically used to time animations for the frame. See [method@Gdk.FrameClock.get_frame_time]. @@ -9817,7 +11978,7 @@ animations for the frame. See [method@Gdk.FrameClock.get_frame_time]. the frame time for the frame, in the timescale + line="157">the frame time for the frame, in the timescale of g_get_monotonic_time() @@ -9825,7 +11986,7 @@ animations for the frame. See [method@Gdk.FrameClock.get_frame_time]. A `GdkFrameTimings` + line="150">A `GdkFrameTimings` @@ -9834,7 +11995,7 @@ animations for the frame. See [method@Gdk.FrameClock.get_frame_time]. c:identifier="gdk_frame_timings_get_predicted_presentation_time"> Gets the predicted time at which this frame will be displayed. + line="188">Gets the predicted time at which this frame will be displayed. Although no predicted time may be available, if one is available, it will be available while the frame is being generated, in contrast @@ -9850,7 +12011,7 @@ for Audio/Video synchronization. The predicted time at which the frame will be presented, + line="205">The predicted time at which the frame will be presented, in the timescale of g_get_monotonic_time(), or 0 if no predicted presentation time is available. @@ -9859,7 +12020,7 @@ for Audio/Video synchronization. a `GdkFrameTimings` + line="190">a `GdkFrameTimings` @@ -9868,14 +12029,14 @@ for Audio/Video synchronization. c:identifier="gdk_frame_timings_get_presentation_time"> Reurns the presentation time. + line="168">Reurns the presentation time. This is the time at which the frame became visible to the user. the time the frame was displayed to the user, in the + line="176">the time the frame was displayed to the user, in the timescale of g_get_monotonic_time(), or 0 if no presentation time is available. See [method@Gdk.FrameTimings.get_complete] @@ -9884,7 +12045,7 @@ This is the time at which the frame became visible to the user. a `GdkFrameTimings` + line="170">a `GdkFrameTimings` @@ -9893,7 +12054,7 @@ This is the time at which the frame became visible to the user. c:identifier="gdk_frame_timings_get_refresh_interval"> Gets the natural interval between presentation times for + line="217">Gets the natural interval between presentation times for the display that this frame was displayed on. Frame presentation usually happens during the “vertical @@ -9902,7 +12063,7 @@ blanking interval”. the refresh interval of the display, in microseconds, + line="227">the refresh interval of the display, in microseconds, or 0 if the refresh interval is not available. See [method@Gdk.FrameTimings.get_complete]. @@ -9911,7 +12072,7 @@ blanking interval”. a `GdkFrameTimings` + line="219">a `GdkFrameTimings` @@ -9919,19 +12080,19 @@ blanking interval”. Increases the reference count of @timings. + line="67">Increases the reference count of @timings. @timings + line="73">@timings a `GdkFrameTimings` + line="69">a `GdkFrameTimings` @@ -9939,7 +12100,7 @@ blanking interval”. Decreases the reference count of @timings. + line="85">Decreases the reference count of @timings. If @timings is no longer referenced, it will be freed. @@ -9950,7 +12111,7 @@ If @timings is no longer referenced, it will be freed. a `GdkFrameTimings` + line="87">a `GdkFrameTimings` @@ -10018,8 +12179,7 @@ If @timings is no longer referenced, it will be freed. glib:get-type="gdk_gl_context_get_type"> `GdkGLContext` is an object representing a platform-specific -OpenGL draw context. + line="21">Represents a platform-specific OpenGL draw context. `GdkGLContext`s are created for a surface using [method@Gdk.Surface.create_gl_context], and the context will match @@ -10071,7 +12231,7 @@ that is currently set by calling [func@Gdk.GLContext.clear_current]. c:identifier="gdk_gl_context_clear_current"> Clears the current `GdkGLContext`. + line="1946">Clears the current `GdkGLContext`. Any OpenGL call after this function returns will be ignored until [method@Gdk.GLContext.make_current] is called. @@ -10083,12 +12243,12 @@ until [method@Gdk.GLContext.make_current] is called. Retrieves the current `GdkGLContext`. + line="2006">Retrieves the current `GdkGLContext`. the current `GdkGLContext` + line="2011">the current `GdkGLContext` @@ -10096,22 +12256,21 @@ until [method@Gdk.GLContext.make_current] is called. c:identifier="gdk_gl_context_get_allowed_apis" glib:get-property="allowed-apis" version="4.6"> - Gets the allowed APIs set via gdk_gl_context_set_allowed_apis(). + line="1253">Gets the allowed APIs set via gdk_gl_context_set_allowed_apis(). the allowed APIs + line="1259">the allowed APIs a GL context + line="1255">a GL context @@ -10120,24 +12279,23 @@ until [method@Gdk.GLContext.make_current] is called. c:identifier="gdk_gl_context_get_api" glib:get-property="api" version="4.6"> - Gets the API currently in use. + line="1273">Gets the API currently in use. If the renderer has not been realized yet, 0 is returned. the currently used API + line="1281">the currently used API a GL context + line="1275">a GL context @@ -10146,21 +12304,21 @@ If the renderer has not been realized yet, 0 is returned. c:identifier="gdk_gl_context_get_debug_enabled"> Retrieves whether the context is doing extra validations and runtime checking. + line="959">Retrieves whether the context is doing extra validations and runtime checking. See [method@Gdk.GLContext.set_debug_enabled]. %TRUE if debugging is enabled + line="967">%TRUE if debugging is enabled a `GdkGLContext` + line="961">a `GdkGLContext` @@ -10168,19 +12326,19 @@ See [method@Gdk.GLContext.set_debug_enabled]. Retrieves the display the @context is created for + line="1818">Retrieves the display the @context is created for a `GdkDisplay` + line="1824">a `GdkDisplay` a `GdkGLContext` + line="1820">a `GdkGLContext` @@ -10189,21 +12347,21 @@ See [method@Gdk.GLContext.set_debug_enabled]. c:identifier="gdk_gl_context_get_forward_compatible"> Retrieves whether the context is forward-compatible. + line="1008">Retrieves whether the context is forward-compatible. See [method@Gdk.GLContext.set_forward_compatible]. %TRUE if the context should be forward-compatible + line="1016">%TRUE if the context should be forward-compatible a `GdkGLContext` + line="1010">a `GdkGLContext` @@ -10212,7 +12370,7 @@ See [method@Gdk.GLContext.set_forward_compatible]. c:identifier="gdk_gl_context_get_required_version"> Retrieves required OpenGL version set as a requirement for the @context + line="1106">Retrieves required OpenGL version set as a requirement for the @context realization. It will not change even if a greater OpenGL version is supported and used after the @context is realized. See [method@Gdk.GLContext.get_version] for the real version in use. @@ -10226,7 +12384,7 @@ See [method@Gdk.GLContext.set_required_version]. a `GdkGLContext` + line="1108">a `GdkGLContext` nullable="1"> return location for the major version to request + line="1109">return location for the major version to request nullable="1"> return location for the minor version to request + line="1110">return location for the minor version to request @@ -10256,10 +12414,9 @@ See [method@Gdk.GLContext.set_required_version]. glib:get-property="shared-context" deprecated="1" deprecated-version="4.4"> - Used to retrieves the `GdkGLContext` that this @context share data with. + line="1850">Used to retrieves the `GdkGLContext` that this @context share data with. As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns %NULL. @@ -10269,14 +12426,14 @@ anymore, this function has been deprecated and now always returns %NULL. %NULL + line="1859">%NULL a `GdkGLContext` + line="1852">a `GdkGLContext` @@ -10284,19 +12441,19 @@ anymore, this function has been deprecated and now always returns %NULL. Retrieves the surface used by the @context. + line="1834">Retrieves the surface used by the @context. a `GdkSurface` + line="1840">a `GdkSurface` a `GdkGLContext` + line="1836">a `GdkGLContext` @@ -10304,12 +12461,12 @@ anymore, this function has been deprecated and now always returns %NULL. Checks whether the @context is using an OpenGL or OpenGL ES profile. + line="1383">Checks whether the @context is using an OpenGL or OpenGL ES profile. %TRUE if the `GdkGLContext` is using an OpenGL ES profile; + line="1389">%TRUE if the `GdkGLContext` is using an OpenGL ES profile; %FALSE if other profile is in use of if the @context has not yet been realized. @@ -10318,7 +12475,7 @@ been realized. a `GdkGLContext` + line="1385">a `GdkGLContext` @@ -10326,7 +12483,7 @@ been realized. Retrieves the OpenGL version of the @context. + line="1872">Retrieves the OpenGL version of the @context. The @context must be realized prior to calling this function. @@ -10337,7 +12494,7 @@ The @context must be realized prior to calling this function. a `GdkGLContext` + line="1874">a `GdkGLContext` transfer-ownership="full"> return location for the major version + line="1875">return location for the major version transfer-ownership="full"> return location for the minor version + line="1876">return location for the minor version @@ -10363,7 +12520,7 @@ The @context must be realized prior to calling this function. Whether the `GdkGLContext` is in legacy mode or not. + line="1134">Whether the `GdkGLContext` is in legacy mode or not. The `GdkGLContext` must be realized before calling this function. @@ -10383,14 +12540,14 @@ kind of shader programs to load. %TRUE if the GL context is in legacy mode + line="1155">%TRUE if the GL context is in legacy mode a `GdkGLContext` + line="1136">a `GdkGLContext` @@ -10400,7 +12557,7 @@ kind of shader programs to load. version="4.4"> Checks if the two GL contexts can share resources. + line="1186">Checks if the two GL contexts can share resources. When they can, the texture IDs from @other can be used in @self. This is particularly useful when passing `GdkGLTexture` objects between @@ -10416,20 +12573,20 @@ is not, this function will return %FALSE. %TRUE if the two GL contexts are compatible. + line="1204">%TRUE if the two GL contexts are compatible. a `GdkGLContext` + line="1188">a `GdkGLContext` the `GdkGLContext` that should be compatible with @self + line="1189">the `GdkGLContext` that should be compatible with @self @@ -10437,7 +12594,7 @@ is not, this function will return %FALSE. Makes the @context the current one. + line="1762">Makes the @context the current one. @@ -10446,7 +12603,7 @@ is not, this function will return %FALSE. a `GdkGLContext` + line="1764">a `GdkGLContext` @@ -10454,21 +12611,21 @@ is not, this function will return %FALSE. Realizes the given `GdkGLContext`. + line="1504">Realizes the given `GdkGLContext`. It is safe to call this function on a realized `GdkGLContext`. %TRUE if the context is realized + line="1513">%TRUE if the context is realized a `GdkGLContext` + line="1506">a `GdkGLContext` @@ -10477,10 +12634,9 @@ It is safe to call this function on a realized `GdkGLContext`. c:identifier="gdk_gl_context_set_allowed_apis" glib:set-property="allowed-apis" version="4.6"> - Sets the allowed APIs. When gdk_gl_context_realize() is called, only the + line="1222">Sets the allowed APIs. When gdk_gl_context_realize() is called, only the allowed APIs will be tried. If you set this to 0, realizing will always fail. If you set it on a realized context, the property will not have any effect. @@ -10495,13 +12651,13 @@ By default, all APIs are allowed. a GL context + line="1224">a GL context the allowed APIs + line="1225">the allowed APIs @@ -10510,7 +12666,7 @@ By default, all APIs are allowed. c:identifier="gdk_gl_context_set_debug_enabled"> Sets whether the `GdkGLContext` should perform extra validations and + line="932">Sets whether the `GdkGLContext` should perform extra validations and runtime checking. This is useful during development, but has additional overhead. @@ -10525,13 +12681,13 @@ calling this function. a `GdkGLContext` + line="934">a `GdkGLContext` whether to enable debugging in the context + line="935">whether to enable debugging in the context @@ -10540,7 +12696,7 @@ calling this function. c:identifier="gdk_gl_context_set_forward_compatible"> Sets whether the `GdkGLContext` should be forward-compatible. + line="979">Sets whether the `GdkGLContext` should be forward-compatible. Forward-compatible contexts must not support OpenGL functionality that has been marked as deprecated in the requested version; non-forward @@ -10557,13 +12713,13 @@ this function. a `GdkGLContext` + line="981">a `GdkGLContext` whether the context should be forward-compatible + line="982">whether the context should be forward-compatible @@ -10572,7 +12728,7 @@ this function. c:identifier="gdk_gl_context_set_required_version"> Sets the major and minor version of OpenGL to request. + line="1051">Sets the major and minor version of OpenGL to request. Setting @major and @minor to zero will use the default values. @@ -10589,19 +12745,19 @@ this function. a `GdkGLContext` + line="1053">a `GdkGLContext` the major version to request + line="1054">the major version to request the minor version to request + line="1055">the minor version to request @@ -10609,7 +12765,7 @@ this function. Requests that GDK create an OpenGL ES context instead of an OpenGL one. + line="1339">Requests that GDK create an OpenGL ES context instead of an OpenGL one. Not all platforms support OpenGL ES. @@ -10630,13 +12786,13 @@ the OpenGL or OpenGL ES API, extensions, or shaders. a `GdkGLContext` + line="1341">a `GdkGLContext` whether the context should use OpenGL ES instead of OpenGL, + line="1342">whether the context should use OpenGL ES instead of OpenGL, or -1 to allow auto-detection @@ -10649,11 +12805,9 @@ the OpenGL or OpenGL ES API, extensions, or shaders. setter="set_allowed_apis" getter="get_allowed_apis" default-value="GDK_GL_API_GL | GDK_GL_API_GLES"> - The allowed APIs. + line="762">The allowed APIs. transfer-ownership="none" getter="get_api" default-value="0"> - The API currently in use. + line="777">The API currently in use. construct-only="1" transfer-ownership="none" getter="get_shared_context"> - Always %NULL + line="743">Always %NULL As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns %NULL. @@ -10694,7 +12845,7 @@ anymore, this function has been deprecated and now always returns %NULL. glib:error-domain="gdk-gl-error-quark"> Error enumeration for `GdkGLContext`. + line="172">Error enumeration for `GdkGLContext`. glib:name="GDK_GL_ERROR_NOT_AVAILABLE"> OpenGL support is not available + line="174">OpenGL support is not available glib:name="GDK_GL_ERROR_UNSUPPORTED_FORMAT"> The requested visual format is not supported + line="175">The requested visual format is not supported glib:name="GDK_GL_ERROR_UNSUPPORTED_PROFILE"> The requested profile is not supported + line="176">The requested profile is not supported glib:name="GDK_GL_ERROR_COMPILATION_FAILED"> The shader compilation failed + line="177">The shader compilation failed glib:name="GDK_GL_ERROR_LINK_FAILED"> The shader linking failed + line="178">The shader linking failed + Registers an error quark for [class@Gdk.GLContext] errors. + the error quark @@ -10755,7 +12912,7 @@ anymore, this function has been deprecated and now always returns %NULL. glib:type-struct="GLTextureClass"> A GdkTexture representing a GL texture object. + line="31">A `GdkTexture` representing a GL texture object. @@ -10766,18 +12923,18 @@ anymore, this function has been deprecated and now always returns %NULL. deprecated-version="4.12"> Creates a new texture for an existing GL texture. + line="427">Creates a new texture for an existing GL texture. Note that the GL texture must not be modified until @destroy is called, which will happen when the GdkTexture object is finalized, or due to an explicit call of [method@Gdk.GLTexture.release]. - [class@Gdk.GLTextureBuilder] supercedes this function + [class@Gdk.GLTextureBuilder] supersedes this function and provides extended functionality for creating GL textures. A newly-created + line="443">A newly-created `GdkTexture` @@ -10785,31 +12942,31 @@ an explicit call of [method@Gdk.GLTexture.release]. a `GdkGLContext` + line="429">a `GdkGLContext` the ID of a texture that was created with @context + line="430">the ID of a texture that was created with @context the nominal width of the texture + line="431">the nominal width of the texture the nominal height of the texture + line="432">the nominal height of the texture a destroy notify that will be called when the GL resources + line="433">a destroy notify that will be called when the GL resources are released @@ -10819,7 +12976,7 @@ an explicit call of [method@Gdk.GLTexture.release]. allow-none="1"> data that gets passed to @destroy + line="435">data that gets passed to @destroy @@ -10827,7 +12984,7 @@ an explicit call of [method@Gdk.GLTexture.release]. Releases the GL resources held by a `GdkGLTexture`. + line="238">Releases the GL resources held by a `GdkGLTexture`. The texture contents are still available via the [method@Gdk.Texture.download] function, after this @@ -10840,7 +12997,7 @@ function has been called. a `GdkTexture` wrapping a GL texture + line="240">a `GdkTexture` wrapping a GL texture @@ -10856,8 +13013,7 @@ function has been called. glib:type-struct="GLTextureBuilderClass"> `GdkGLTextureBuilder` is a buider used to construct [class@Gdk.Texture] objects from -GL textures. + line="53">Constructs [class@Gdk.Texture] objects from GL textures. The operation is quite simple: Create a texture builder, set all the necessary properties - keep in mind that the properties [property@Gdk.GLTextureBuilder:context], @@ -10873,12 +13029,12 @@ textures as well as kept around and reused to construct multiple textures. version="4.12"> Creates a new texture builder. + line="358">Creates a new texture builder. the new `GdkTextureBuilder` + line="363">the new `GdkTextureBuilder` @@ -10887,7 +13043,7 @@ textures as well as kept around and reused to construct multiple textures. version="4.12"> Builds a new `GdkTexture` with the values set up in the builder. + line="840">Builds a new `GdkTexture` with the values set up in the builder. The `destroy` function gets called when the returned texture gets released; either when the texture is finalized or by an explicit call to @@ -10900,18 +13056,18 @@ property has not been set. It is possible to call this function multiple times to create multiple textures, possibly with changing properties in between. - + a newly built `GdkTexture` + line="861">a newly built `GdkTexture` a `GdkGLTextureBuilder` + line="842">a `GdkGLTextureBuilder` scope="async"> destroy function to be called when the texture is + line="843">destroy function to be called when the texture is released @@ -10931,32 +13087,54 @@ possibly with changing properties in between. allow-none="1"> user data to pass to the destroy function + line="845">user data to pass to the destroy function + + Gets the color state previously set via gdk_gl_texture_builder_set_color_state(). + + + the color state + + + + + a `GdkGLTextureBuilder` + + + + - Gets the context previously set via gdk_gl_texture_builder_set_context() or + line="373">Gets the context previously set via gdk_gl_texture_builder_set_context() or %NULL if none was set. The context + line="380">The context a `GdkGLTextureBuilder` + line="375">a `GdkGLTextureBuilder` @@ -10965,22 +13143,21 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_format" glib:get-property="format" version="4.12"> - Gets the format previously set via gdk_gl_texture_builder_set_format(). + line="688">Gets the format previously set via gdk_gl_texture_builder_set_format(). The format + line="694">The format a `GdkGLTextureBuilder` + line="690">a `GdkGLTextureBuilder` @@ -10989,22 +13166,21 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_has_mipmap" glib:get-property="has-mipmap" version="4.12"> - Gets whether the texture has a mipmap. + line="551">Gets whether the texture has a mipmap. Whether the texture has a mipmap + line="557">Whether the texture has a mipmap a `GdkGLTextureBuilder` + line="553">a `GdkGLTextureBuilder` @@ -11013,23 +13189,22 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_height" glib:get-property="height" version="4.12"> - Gets the height previously set via gdk_gl_texture_builder_set_height() or + line="417">Gets the height previously set via gdk_gl_texture_builder_set_height() or 0 if the height wasn't set. The height + line="424">The height a `GdkGLTextureBuilder` + line="419">a `GdkGLTextureBuilder` @@ -11038,23 +13213,22 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_id" glib:get-property="id" version="4.12"> - Gets the texture id previously set via gdk_gl_texture_builder_set_id() or + line="461">Gets the texture id previously set via gdk_gl_texture_builder_set_id() or 0 if the id wasn't set. The id + line="468">The id a `GdkGLTextureBuilder` + line="463">a `GdkGLTextureBuilder` @@ -11063,22 +13237,21 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_sync" glib:get-property="sync" version="4.12"> - Gets the `GLsync` previously set via gdk_gl_texture_builder_set_sync(). + line="595">Gets the `GLsync` previously set via gdk_gl_texture_builder_set_sync(). the `GLSync` + line="601">the `GLSync` a `GdkGLTextureBuilder` + line="597">a `GdkGLTextureBuilder` @@ -11087,23 +13260,22 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_update_region" glib:get-property="update-region" version="4.12"> - Gets the region previously set via gdk_gl_texture_builder_set_update_region() or + line="786">Gets the region previously set via gdk_gl_texture_builder_set_update_region() or %NULL if none was set. - + The region + line="793">The region a `GdkGLTextureBuilder` + line="788">a `GdkGLTextureBuilder` @@ -11112,23 +13284,22 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_update_texture" glib:get-property="update-texture" version="4.12"> - Gets the texture previously set via gdk_gl_texture_builder_set_update_texture() or + line="744">Gets the texture previously set via gdk_gl_texture_builder_set_update_texture() or %NULL if none was set. - + The texture + line="751">The texture a `GdkGLTextureBuilder` + line="746">a `GdkGLTextureBuilder` @@ -11137,35 +13308,62 @@ possibly with changing properties in between. c:identifier="gdk_gl_texture_builder_get_width" glib:get-property="width" version="4.12"> - Gets the width previously set via gdk_gl_texture_builder_set_width() or + line="507">Gets the width previously set via gdk_gl_texture_builder_set_width() or 0 if the width wasn't set. The width + line="514">The width a `GdkGLTextureBuilder` + line="509">a `GdkGLTextureBuilder` + + + + + + Sets the color state for the texture. + +By default, the sRGB colorstate is used. If you don't know what +colorstates are, this is probably the right thing. + + + + + + + a `GdkGLTextureBuilder` + + a `GdkColorState` + + - Sets the context to be used for the texture. This is the context that owns + line="392">Sets the context to be used for the texture. This is the context that owns the texture. The context must be set before calling [method@Gdk.GLTextureBuilder.build]. @@ -11177,7 +13375,7 @@ The context must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` + line="394">a `GdkGLTextureBuilder` The context the texture beongs to or %NULL to unset + line="395">The context the texture belongs to or %NULL to unset @@ -11195,10 +13393,9 @@ The context must be set before calling [method@Gdk.GLTextureBuilder.build]. - Sets the format of the texture. The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. + line="706">Sets the format of the texture. The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. The format is the preferred format the texture data should be downloaded to. The format must be supported by the GL version of [property@Gdk.GLTextureBuilder:context]. @@ -11222,13 +13419,13 @@ in GSK's shaders. a `GdkGLTextureBuilder` + line="708">a `GdkGLTextureBuilder` The texture's format + line="709">The texture's format @@ -11237,10 +13434,9 @@ in GSK's shaders. c:identifier="gdk_gl_texture_builder_set_has_mipmap" glib:set-property="has-mipmap" version="4.12"> - Sets whether the texture has a mipmap. This allows the renderer and other users of the + line="569">Sets whether the texture has a mipmap. This allows the renderer and other users of the generated texture to use a higher quality downscaling. Typically, the `glGenerateMipmap` function is used to generate a mimap. @@ -11252,13 +13448,13 @@ Typically, the `glGenerateMipmap` function is used to generate a mimap. a `GdkGLTextureBuilder` + line="571">a `GdkGLTextureBuilder` Whether the texture has a mipmap + line="572">Whether the texture has a mipmap @@ -11267,10 +13463,9 @@ Typically, the `glGenerateMipmap` function is used to generate a mimap. c:identifier="gdk_gl_texture_builder_set_height" glib:set-property="height" version="4.12"> - Sets the height of the texture. + line="436">Sets the height of the texture. The height must be set before calling [method@Gdk.GLTextureBuilder.build]. @@ -11281,13 +13476,13 @@ The height must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` + line="438">a `GdkGLTextureBuilder` The texture's height or 0 to unset + line="439">The texture's height or 0 to unset @@ -11296,10 +13491,9 @@ The height must be set before calling [method@Gdk.GLTextureBuilder.build]. c:identifier="gdk_gl_texture_builder_set_id" glib:set-property="id" version="4.12"> - Sets the texture id of the texture. The texture id must remain unmodified + line="480">Sets the texture id of the texture. The texture id must remain unmodified until the texture was finalized. See [method@Gdk.GLTextureBuilder.build] for a longer discussion. @@ -11312,13 +13506,13 @@ The id must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` + line="482">a `GdkGLTextureBuilder` The texture id to be used for creating the texture + line="483">The texture id to be used for creating the texture @@ -11327,10 +13521,9 @@ The id must be set before calling [method@Gdk.GLTextureBuilder.build]. c:identifier="gdk_gl_texture_builder_set_sync" glib:set-property="sync" version="4.12"> - Sets the GLSync object to use for the texture. + line="613">Sets the GLSync object to use for the texture. GTK will wait on this object before using the created `GdkTexture`. @@ -11346,7 +13539,7 @@ responsibility to make sure it doesn't leak. a `GdkGLTextureBuilder` + line="615">a `GdkGLTextureBuilder` allow-none="1"> the GLSync object + line="616">the GLSync object @@ -11364,10 +13557,9 @@ responsibility to make sure it doesn't leak. c:identifier="gdk_gl_texture_builder_set_update_region" glib:set-property="update-region" version="4.12"> - Sets the region to be updated by this texture. Together with + line="805">Sets the region to be updated by this texture. Together with [property@Gdk.GLTextureBuilder:update-texture] this describes an update of a previous texture. @@ -11377,7 +13569,7 @@ It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change. An example would be a screen recording where only the mouse pointer moves. - + @@ -11385,7 +13577,7 @@ An example would be a screen recording where only the mouse pointer moves. a `GdkGLTextureBuilder` + line="807">a `GdkGLTextureBuilder` allow-none="1"> the region to update + line="808">the region to update @@ -11403,12 +13595,11 @@ An example would be a screen recording where only the mouse pointer moves. c:identifier="gdk_gl_texture_builder_set_update_texture" glib:set-property="update-texture" version="4.12"> - Sets the texture to be updated by this texture. See + line="763">Sets the texture to be updated by this texture. See [method@Gdk.GLTextureBuilder.set_update_region] for an explanation. - + @@ -11416,7 +13607,7 @@ An example would be a screen recording where only the mouse pointer moves. a `GdkGLTextureBuilder` + line="765">a `GdkGLTextureBuilder` allow-none="1"> the texture to update + line="766">the texture to update @@ -11434,10 +13625,9 @@ An example would be a screen recording where only the mouse pointer moves. c:identifier="gdk_gl_texture_builder_set_width" glib:set-property="width" version="4.12"> - Sets the width of the texture. + line="526">Sets the width of the texture. The width must be set before calling [method@Gdk.GLTextureBuilder.build]. @@ -11448,30 +13638,37 @@ The width must be set before calling [method@Gdk.GLTextureBuilder.build]. a `GdkGLTextureBuilder` + line="528">a `GdkGLTextureBuilder` The texture's width or 0 to unset + line="529">The texture's width or 0 to unset + + The color state of the texture. + + - - The context owning the texture. + line="226">The context owning the texture. setter="set_format" getter="get_format" default-value="GDK_MEMORY_R8G8B8A8_PREMULTIPLIED"> - - The format when downloading the texture. + line="238">The format when downloading the texture. setter="set_has_mipmap" getter="get_has_mipmap" default-value="FALSE"> - - If the texture has a mipmap. + line="251">If the texture has a mipmap. setter="set_height" getter="get_height" default-value="0"> - - The height of the texture. + line="263">The height of the texture. setter="set_id" getter="get_id" default-value="0"> - - The texture ID to use. + line="275">The texture ID to use. transfer-ownership="none" setter="set_sync" getter="get_sync"> - - An optional `GLSync` object. + line="287">An optional `GLSync` object. If this is set, GTK will wait on it before using the texture. @@ -11561,13 +13738,9 @@ If this is set, GTK will wait on it before using the texture. transfer-ownership="none" setter="set_update_region" getter="get_update_region"> - - The update region for [property@Gdk.GLTextureBuilder:update-texture]. + line="312">The update region for [property@Gdk.GLTextureBuilder:update-texture]. transfer-ownership="none" setter="set_update_texture" getter="get_update_texture"> - - The texture [property@Gdk.GLTextureBuilder:update-region] is an update for. + line="324">The texture [property@Gdk.GLTextureBuilder:update-region] is an update for. setter="set_width" getter="get_width" default-value="0"> - - The width of the texture. + line="336">The width of the texture. @@ -11643,24 +13808,24 @@ If this is set, GTK will wait on it before using the texture. glib:fundamental="1"> An event related to a broken windowing system grab. + line="3371">An event related to a broken windowing system grab. Extracts the grab surface from a grab broken event. - + line="3407">Extracts the grab surface from a grab broken event. + the grab surface of @event + line="3413">the grab surface of @event a grab broken event + line="3409">a grab broken event @@ -11669,19 +13834,19 @@ If this is set, GTK will wait on it before using the texture. c:identifier="gdk_grab_broken_event_get_implicit"> Checks whether the grab broken event is for an implicit grab. - + line="3426">Checks whether the grab broken event is for an implicit grab. + %TRUE if the an implicit grab was broken + line="3432">%TRUE if the an implicit grab was broken a grab broken event + line="3428">a grab broken event @@ -11903,6 +14068,15 @@ If this is set, GTK will wait on it before using the texture. + + + + + + + @@ -12052,7 +14226,7 @@ If this is set, GTK will wait on it before using the texture. - + @@ -12134,11295 +14308,12189 @@ If this is set, GTK will wait on it before using the texture. - + - + + + + + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + - + + + + + + + + + + + + + - + + + + + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - + - + - + - + + + + + + + + + - + - + + + + + - + - + - + - + + + + + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + + + + + + + + + - + - + + + + + - + + + + + + + + + + + + + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + + + + + + + + + + + + + + + + + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - + + + + + - + - + + + + + + + + + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + - + - + - + - + - + - + + + + + + + + + - + - + + + + + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + + + + + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + + + + + - + - + - + - + - + + + + + + + + + - + - + - + - + + + + + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + - + + + + + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + + + + + - + - + + + + + - + + + + + + + + + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + glib:fundamental="1"> An event related to a key-based device. + line="1529">An event related to a key-based device. Extracts the consumed modifiers from a key event. - + line="1743">Extracts the consumed modifiers from a key event. + the consumed modifiers or @event + line="1749">the consumed modifiers or @event a key event + line="1745">a key event @@ -23459,19 +26527,19 @@ If this is set, GTK will wait on it before using the texture. Extracts the keycode from a key event. - + line="1683">Extracts the keycode from a key event. + the keycode of @event + line="1689">the keycode of @event a key event + line="1685">a key event @@ -23479,19 +26547,19 @@ If this is set, GTK will wait on it before using the texture. Extracts the keyval from a key event. - + line="1663">Extracts the keyval from a key event. + the keyval of @event + line="1669">the keyval of @event a key event + line="1665">a key event @@ -23499,19 +26567,19 @@ If this is set, GTK will wait on it before using the texture. Extracts the layout from a key event. - + line="1723">Extracts the layout from a key event. + the layout of @event + line="1729">the layout of @event a key event + line="1725">a key event @@ -23519,19 +26587,19 @@ If this is set, GTK will wait on it before using the texture. Extracts the shift level from a key event. - + line="1703">Extracts the shift level from a key event. + the shift level of @event + line="1709">the shift level of @event a key event + line="1705">a key event @@ -23539,22 +26607,22 @@ If this is set, GTK will wait on it before using the texture. Gets a keyval and modifier combination that will match + line="1921">Gets a keyval and modifier combination that will match the event. See [method@Gdk.KeyEvent.matches]. - + %TRUE on success + line="1932">%TRUE on success a key `GdkEvent` + line="1923">a key `GdkEvent` transfer-ownership="full"> return location for a keyval + line="1924">return location for a keyval transfer-ownership="full"> return location for modifiers + line="1925">return location for modifiers @@ -23580,19 +26648,19 @@ See [method@Gdk.KeyEvent.matches]. Extracts whether the key event is for a modifier key. - + line="1763">Extracts whether the key event is for a modifier key. + %TRUE if the @event is for a modifier key + line="1769">%TRUE if the @event is for a modifier key a key event + line="1765">a key event @@ -23600,7 +26668,7 @@ See [method@Gdk.KeyEvent.matches]. Matches a key event against a keyval and modifiers. + line="1801">Matches a key event against a keyval and modifiers. This is typically used to trigger keyboard shortcuts such as Ctrl-C. @@ -23608,30 +26676,30 @@ Partial matches are possible where the combination matches if the currently active group is ignored. Note that we ignore Caps Lock for matching. - + a `GdkKeyMatch` value describing whether @event matches + line="1816">a `GdkKeyMatch` value describing whether @event matches a key `GdkEvent` + line="1803">a key `GdkEvent` the keyval to match + line="1804">the keyval to match the modifiers to match + line="1805">the modifiers to match @@ -23643,7 +26711,7 @@ Note that we ignore Caps Lock for matching. c:type="GdkKeyMatch"> Describes how well an event matches a given keyval and modifiers. + line="529">Describes how well an event matches a given keyval and modifiers. `GdkKeyMatch` values are returned by [method@Gdk.KeyEvent.matches]. glib:name="GDK_KEY_MATCH_NONE"> The key event does not match + line="531">The key event does not match glib:name="GDK_KEY_MATCH_PARTIAL"> The key event matches if keyboard state + line="532">The key event matches if keyboard state (specifically, the currently active group) is ignored glib:name="GDK_KEY_MATCH_EXACT"> The key event matches + line="534">The key event matches A `GdkKeymapKey` is a hardware key that can be mapped to a keyval. - + line="145">Represents a hardware key that can be mapped to a keyval. + the hardware keycode. This is an identifying number for a + line="147">the hardware keycode. This is an identifying number for a physical key. indicates movement in a horizontal direction. Usually groups are used + line="149">indicates movement in a horizontal direction. Usually groups are used for two different languages. In group 0, a key might have two English characters, and in group 1 it might have two Hebrew characters. The Hebrew characters will be printed on the key next to the English characters. @@ -23699,7 +26767,7 @@ Note that we ignore Caps Lock for matching. indicates which symbol on the key will be used, in a vertical direction. + line="153">indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number “1” on it also has the exclamation point ("!") character on it. The level indicates whether to use the “1” or the “!” symbol. The letter keys are considered to have a lowercase @@ -23722,8 +26790,8 @@ Note that we ignore Caps Lock for matching. c:type="GDK_MODIFIER_MASK"> A mask covering all entries in `GdkModifierType`. - + line="143">A mask covering all entries in `GdkModifierType`. + c:type="GdkMemoryFormat"> `GdkMemoryFormat` describes formats that image data can have in memory. + line="304">Describes formats that image data can have in memory. It describes formats by listing the contents of the memory passed to it. -So GDK_MEMORY_A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a +So `GDK_MEMORY_A8R8G8B8` will be 1 byte (8 bits) of alpha, followed by a byte each of red, green and blue. It is not endian-dependent, so -CAIRO_FORMAT_ARGB32 is represented by different `GdkMemoryFormats` +`CAIRO_FORMAT_ARGB32` is represented by different `GdkMemoryFormats` on architectures with different endiannesses. Its naming is modelled after @@ -23759,7 +26827,7 @@ for details). glib:name="GDK_MEMORY_B8G8R8A8_PREMULTIPLIED"> 4 bytes; for blue, green, red, alpha. + line="306">4 bytes; for blue, green, red, alpha. The color values are premultiplied with the alpha value. glib:name="GDK_MEMORY_A8R8G8B8_PREMULTIPLIED"> 4 bytes; for alpha, red, green, blue. + line="308">4 bytes; for alpha, red, green, blue. The color values are premultiplied with the alpha value. glib:name="GDK_MEMORY_R8G8B8A8_PREMULTIPLIED"> 4 bytes; for red, green, blue, alpha + line="310">4 bytes; for red, green, blue, alpha The color values are premultiplied with the alpha value. glib:name="GDK_MEMORY_B8G8R8A8"> 4 bytes; for blue, green, red, alpha. + line="312">4 bytes; for blue, green, red, alpha. glib:name="GDK_MEMORY_A8R8G8B8"> 4 bytes; for alpha, red, green, blue. + line="313">4 bytes; for alpha, red, green, blue. glib:name="GDK_MEMORY_R8G8B8A8"> 4 bytes; for red, green, blue, alpha. + line="314">4 bytes; for red, green, blue, alpha. glib:name="GDK_MEMORY_A8B8G8R8"> 4 bytes; for alpha, blue, green, red. + line="315">4 bytes; for alpha, blue, green, red. glib:name="GDK_MEMORY_R8G8B8"> 3 bytes; for red, green, blue. The data is opaque. + line="316">3 bytes; for red, green, blue. The data is opaque. glib:name="GDK_MEMORY_B8G8R8"> 3 bytes; for blue, green, red. The data is opaque. + line="317">3 bytes; for blue, green, red. The data is opaque. 3 guint16 values; for red, green, blue. Since: 4.6 + line="370">3 guint16 values; for red, green, blue. 4 guint16 values; for red, green, - blue, alpha. The color values are premultiplied with the alpha value. - Since: 4.6 + line="377">4 guint16 values; for red, green, blue, alpha. The color values are +premultiplied with the alpha value. 4 guint16 values; for red, green, blue, alpha. - Since: 4.6 + line="385">4 guint16 values; for red, green, blue, alpha. 3 half-float values; for red, green, blue. - The data is opaque. Since: 4.6 + line="392">3 half-float values; for red, green, blue. The data is opaque. 4 half-float values; for - red, green, blue and alpha. The color values are premultiplied with - the alpha value. Since: 4.6 + line="399">4 half-float values; for red, green, blue and alpha. The color values are +premultiplied with the alpha value. 4 half-float values; for red, green, - blue and alpha. Since: 4.6 + line="407">4 half-float values; for red, green, blue and alpha. + 3 float values; for red, green, blue. 4 float values; for - red, green, blue and alpha. The color values are premultiplied with - the alpha value. Since: 4.6 + line="421">4 float values; for red, green, blue and alpha. The color values are +premultiplied with the alpha value. 4 float values; for red, green, blue and - alpha. Since: 4.6 + line="429">4 float values; for red, green, blue and alpha. 2 bytes; for grayscale, alpha. The color - values are premultiplied with the alpha value. Since: 4.12 + line="436">2 bytes; for grayscale, alpha. The color values are premultiplied with the +alpha value. 2 bytes; for grayscale, alpha. Since: 4.12 + line="444">2 bytes; for grayscale, alpha. One byte; for grayscale. The data is opaque. - Since: 4.12 + line="451">One byte; for grayscale. The data is opaque. 2 guint16 values; for grayscale, alpha. - The color values are premultiplied with the alpha value. Since: 4.12 + line="458">2 guint16 values; for grayscale, alpha. The color values are premultiplied +with the alpha value. 2 guint16 values; for grayscale, alpha. Since: 4.12 + line="466">2 guint16 values; for grayscale, alpha. One guint16 value; for grayscale. The data is opaque. - Since: 4.12 + line="473">One guint16 value; for grayscale. The data is opaque. One byte; for alpha. - Since: 4.12 + line="480">One byte; for alpha. One guint16 value; for alpha. - Since: 4.12 - - - - - - + filename="gdk/gdkenums.h" + line="487">One guint16 value; for alpha. + + + One half-float value; for alpha. + + + One float value; for alpha. + + + 4 bytes; for alpha, blue, green, red, The color values are premultiplied with +the alpha value. + + + 4 bytes; for blue, green, red, unused. + + + 4 bytes; for unused, red, green, blue. + + + 4 bytes; for red, green, blue, unused. + + + 4 bytes; for unused, blue, green, red. + + + The number of formats. This value will change as + more formats get added, so do not rely on its concrete integer. + + + + A `GdkTexture` representing image data in memory. + + + + + + Creates a new texture for a blob of image data. + +The `GBytes` must contain @stride × @height pixels +in the given format. + + + A newly-created `GdkTexture` + + + + + the width of the texture + + + + the height of the texture + + + + the format of the data + + + + the `GBytes` containing the pixel data + + + + rowstride for the data + + + + + + + Constructs [class@Gdk.Texture] objects from system memory provided +via [struct@GLib.Bytes]. + +The operation is quite simple: Create a texture builder, set all the necessary +properties - keep in mind that the properties [property@Gdk.MemoryTextureBuilder:bytes], +[property@Gdk.MemoryTextureBuilder:stride], [property@Gdk.MemoryTextureBuilder:width], +and [property@Gdk.MemoryTextureBuilder:height] are mandatory - and then call +[method@Gdk.MemoryTextureBuilder.build] to create the new texture. + +`GdkMemoryTextureBuilder` can be used for quick one-shot construction of +textures as well as kept around and reused to construct multiple textures. + + + Creates a new texture builder. + + + the new `GdkTextureBuilder` + + + + + Builds a new `GdkTexture` with the values set up in the builder. + +Note that it is a programming error to call this function if any mandatory +property has not been set. + +It is possible to call this function multiple times to create multiple textures, +possibly with changing properties in between. + + + a newly built `GdkTexture` + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the bytes previously set via gdk_memory_texture_builder_set_bytes() +or %NULL if none was set. + + + The bytes + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the colorstate previously set via gdk_memory_texture_builder_set_color_state(). + + + The colorstate + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the format previously set via gdk_memory_texture_builder_set_format(). + + + The format + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the height previously set via gdk_memory_texture_builder_set_height() +or 0 if the height wasn't set. + + + The height + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the stride previously set via gdk_memory_texture_builder_set_stride(). + + + the stride + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the region previously set via gdk_memory_texture_builder_set_update_region() +or %NULL if none was set. + + + The update region + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the texture previously set via gdk_memory_texture_builder_set_update_texture() +or %NULL if none was set. + + + The update texture + + + + + a `GdkMemoryTextureBuilder` + + + + + The number of formats. This value will change as - more formats get added, so do not rely on its concrete integer. - - - - A `GdkTexture` representing image data in memory. - - - - - + filename="gdk/gdkmemorytexturebuilder.c" + line="471">Gets the width previously set via gdk_memory_texture_builder_set_width() +or 0 if the width wasn't set. + + + The width + + + + + a `GdkMemoryTextureBuilder` + + + + + Creates a new texture for a blob of image data. + filename="gdk/gdkmemorytexturebuilder.c" + line="350">Sets the data to be shown but the texture. -The `GBytes` must contain @stride × @height pixels -in the given format. - - - A newly-created `GdkTexture` - +The bytes must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + - + the width of the texture - + filename="gdk/gdkmemorytexturebuilder.c" + line="352">a `GdkMemoryTextureBuilder` + + + + The bytes the texture shows or %NULL to unset + - + + + + Sets the colorstate describing the data. + +By default, the sRGB colorstate is used. If you don't know +what colorstates are, this is probably the right thing. + + + + + + the height of the texture - + filename="gdk/gdkmemorytexturebuilder.c" + line="399">a `GdkMemoryTextureBuilder` + + + + The colorstate describing the data + + + + + Sets the format of the bytes. + +The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. + + + + + + + a `GdkMemoryTextureBuilder` + + the format of the data + filename="gdk/gdkmemorytexturebuilder.c" + line="579">The texture's format - + + + + Sets the height of the texture. + +The height must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + the `GBytes` containing the pixel data - + filename="gdk/gdkmemorytexturebuilder.c" + line="448">a `GdkMemoryTextureBuilder` + + + + The texture's height or 0 to unset + + + + + Sets the rowstride of the bytes used. + +The rowstride must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + + a `GdkMemoryTextureBuilder` + + rowstride for the data + filename="gdk/gdkmemorytexturebuilder.c" + line="536">the stride or 0 to unset - + + + Sets the region to be updated by this texture. + +Together with [property@Gdk.MemoryTextureBuilder:update-texture], +this describes an update of a previous texture. + +When rendering animations of large textures, it is possible that +consecutive textures are only updating contents in parts of the texture. +It is then possible to describe this update via these two properties, +so that GTK can avoid rerendering parts that did not change. + +An example would be a screen recording where only the mouse pointer moves. + + + + + + + a `GdkMemoryTextureBuilder` + + + + the region to update + + + + + + Sets the texture to be updated by this texture. + +See [method@Gdk.MemoryTextureBuilder.set_update_region] for an explanation. + + + + + + + a `GdkMemoryTextureBuilder` + + + + the texture to update + + + + + + Sets the width of the texture. + +The width must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + + a `GdkMemoryTextureBuilder` + + + + The texture's width or 0 to unset + + + + + + The bytes holding the data. + + + + The colorstate describing the data. + + + + The format of the data. + + + + The height of the texture. + + + + The rowstride of the texture. + +The rowstride is the number of bytes between the first pixel +in a row of image data, and the first pixel in the next row. + + + + The update region for [property@Gdk.MemoryTextureBuilder:update-texture]. + + + + The texture [property@Gdk.MemoryTextureBuilder:update-region] is an update for. + + + + The width of the texture. + + + + + + + No modifier. + a Lock key (depending on the modifier mapping of the - X server this may either be CapsLock or ShiftLock). + line="90">a Lock key (depending on the Windowing System configuration, + this may either be <kbd>CapsLock</kbd> or <kbd>ShiftLock</kbd>). the fourth modifier key (it depends on the modifier - mapping of the X server which key is interpreted as this modifier, but - normally it is the Alt key). + line="93">the fourth modifier key (it depends on the Windowing System + configuration which key is interpreted as this modifier, but normally it + is the <kbd>Alt</kbd> key). the Super modifier + line="101">the Super modifier. the Hyper modifier + line="102">the Hyper modifier. the Meta modifier + line="103">the Meta modifier. Maps to Command on macOS. `GdkMonitor` objects represent the individual outputs that are -associated with a `GdkDisplay`. + line="31">Represents the individual outputs that are associated with a `GdkDisplay`. `GdkDisplay` keeps a `GListModel` to enumerate and monitor monitors with [method@Gdk.Display.get_monitors]. You can use @@ -24241,10 +28003,9 @@ monitor. - Gets the name of the monitor's connector, if available. + line="416">Gets the name of the monitor's connector, if available. These are strings such as "eDP-1", or "HDMI-2". They depend on software and hardware configuration, and should not be @@ -24253,14 +28014,14 @@ relied on as stable identifiers of a specific monitor. the name of the connector + line="426">the name of the connector a `GdkMonitor` + line="418">a `GdkMonitor` @@ -24269,24 +28030,23 @@ relied on as stable identifiers of a specific monitor. c:identifier="gdk_monitor_get_description" glib:get-property="description" version="4.10"> - Gets a string describing the monitor, if available. + line="717">Gets a string describing the monitor, if available. This can be used to identify a monitor in the UI. - + the monitor description + line="725">the monitor description a `GdkMonitor` + line="719">a `GdkMonitor` @@ -24294,22 +28054,21 @@ This can be used to identify a monitor in the UI. - Gets the display that this monitor belongs to. + line="347">Gets the display that this monitor belongs to. the display + line="353">the display a `GdkMonitor` + line="349">a `GdkMonitor` @@ -24317,14 +28076,13 @@ This can be used to identify a monitor in the UI. - Retrieves the size and position of the monitor within the + line="363">Retrieves the size and position of the monitor within the display coordinate space. The returned geometry is in ”application pixels”, not in -”device pixels” (see [method@Gdk.Monitor.get_scale_factor]). +”device pixels” (see [method@Gdk.Monitor.get_scale]). @@ -24333,7 +28091,7 @@ The returned geometry is in ”application pixels”, not in a `GdkMonitor` + line="365">a `GdkMonitor` a `GdkRectangle` to be filled with the monitor geometry + line="366">a `GdkRectangle` to be filled with the monitor geometry @@ -24350,22 +28108,21 @@ The returned geometry is in ”application pixels”, not in - Gets the height in millimeters of the monitor. + line="400">Gets the height in millimeters of the monitor. the physical height of the monitor + line="406">the physical height of the monitor a `GdkMonitor` + line="402">a `GdkMonitor` @@ -24373,10 +28130,9 @@ The returned geometry is in ”application pixels”, not in - Gets the name or PNP ID of the monitor's manufacturer. + line="436">Gets the name or PNP ID of the monitor's manufacturer. Note that this value might also vary depending on actual display backend. @@ -24387,14 +28143,14 @@ The PNP ID registry is located at the name of the manufacturer + line="448">the name of the manufacturer a `GdkMonitor` + line="438">a `GdkMonitor` @@ -24402,22 +28158,21 @@ The PNP ID registry is located at - Gets the string identifying the monitor model, if available. + line="458">Gets the string identifying the monitor model, if available. the monitor model + line="464">the monitor model a `GdkMonitor` + line="460">a `GdkMonitor` @@ -24425,25 +28180,52 @@ The PNP ID registry is located at - Gets the refresh rate of the monitor, if available. + line="521">Gets the refresh rate of the monitor, if available. The value is in milli-Hertz, so a refresh rate of 60Hz is returned as 60000. - + the refresh rate in milli-Hertz, or 0 + line="530">the refresh rate in milli-Hertz, or 0 a `GdkMonitor` + line="523">a `GdkMonitor` + + + + + + Gets the internal scale factor that maps from monitor coordinates +to device pixels. + +This can be used if you want to create pixel based data for a +particular monitor, but most of the time you’re drawing to a surface +where it is better to use [method@Gdk.Surface.get_scale] instead. + + + the scale + + + + + a `GdkMonitor` @@ -24451,10 +28233,9 @@ is returned as 60000. - Gets the internal scale factor that maps from monitor coordinates + line="474">Gets the internal scale factor that maps from monitor coordinates to device pixels. On traditional systems this is 1, but on very high density outputs @@ -24467,14 +28248,14 @@ where it is better to use [method@Gdk.Surface.get_scale_factor] instead. the scale factor + line="488">the scale factor a `GdkMonitor` + line="476">a `GdkMonitor` @@ -24482,23 +28263,22 @@ where it is better to use [method@Gdk.Surface.get_scale_factor] instead. - Gets information about the layout of red, green and blue + line="540">Gets information about the layout of red, green and blue primaries for pixels. - + the subpixel layout + line="547">the subpixel layout a `GdkMonitor` + line="542">a `GdkMonitor` @@ -24506,47 +28286,47 @@ primaries for pixels. - Gets the width in millimeters of the monitor. + line="384">Gets the width in millimeters of the monitor. the physical width of the monitor + line="390">the physical width of the monitor a `GdkMonitor` + line="386">a `GdkMonitor` - - + Returns %TRUE if the @monitor object corresponds to a + line="697">Returns %TRUE if the @monitor object corresponds to a physical monitor. The @monitor becomes invalid when the physical monitor is unplugged or removed. - + %TRUE if the object corresponds to a physical monitor + line="707">%TRUE if the object corresponds to a physical monitor a `GdkMonitor` + line="699">a `GdkMonitor` @@ -24555,11 +28335,9 @@ is unplugged or removed. transfer-ownership="none" getter="get_connector" default-value="NULL"> - The connector name. + line="230">The connector name. transfer-ownership="none" getter="get_description" default-value="NULL"> - A short description of the monitor, meant for display to the user. + line="188">A short description of the monitor, meant for display to the user. construct-only="1" transfer-ownership="none" getter="get_display"> - The `GdkDisplay` of the monitor. + line="200">The `GdkDisplay` of the monitor. - The geometry of the monitor. + line="266">The geometry of the monitor. - The height of the monitor, in millimeters. + line="287">The height of the monitor, in millimeters. - The manufacturer name. + line="210">The manufacturer name. - The model name. + line="220">The model name. - The refresh rate, in milli-Hertz. + line="298">The refresh rate, in milli-Hertz. + + The scale of the monitor. + + - The scale factor. + line="240">The scale factor. + +The scale factor is the next larger integer, +compared to [property@Gdk.Surface:scale]. - The subpixel layout. + line="309">The subpixel layout. - - + Whether the object is still valid. + line="320">Whether the object is still valid. - The width of the monitor, in millimeters. + line="276">The width of the monitor, in millimeters. Emitted when the output represented by @monitor gets disconnected. + line="332">Emitted when the output represented by @monitor gets disconnected. @@ -24704,7 +28478,7 @@ is unplugged or removed. glib:fundamental="1"> An event related to a pointer or touch device motion. + line="3043">An event related to a pointer or touch device motion. c:type="GdkNotifyType"> Specifies the kind of crossing for enter and leave events. + line="301">Specifies the kind of crossing for enter and leave events. See the X11 protocol specification of LeaveNotify for full details of crossing event generation. @@ -24723,7 +28497,7 @@ full details of crossing event generation. glib:name="GDK_NOTIFY_ANCESTOR"> the surface is entered from an ancestor or + line="303">the surface is entered from an ancestor or left towards an ancestor. glib:name="GDK_NOTIFY_VIRTUAL"> the pointer moves between an ancestor and an + line="305">the pointer moves between an ancestor and an inferior of the surface. glib:name="GDK_NOTIFY_INFERIOR"> the surface is entered from an inferior or + line="307">the surface is entered from an inferior or left towards an inferior. glib:name="GDK_NOTIFY_NONLINEAR"> the surface is entered from or left towards + line="309">the surface is entered from or left towards a surface which is neither an ancestor nor an inferior. glib:name="GDK_NOTIFY_NONLINEAR_VIRTUAL"> the pointer moves between two surfaces + line="311">the pointer moves between two surfaces which are not ancestors of each other and the surface is part of the ancestor chain between one of these surfaces and their least common ancestor. @@ -24775,7 +28549,7 @@ full details of crossing event generation. glib:name="GDK_NOTIFY_UNKNOWN"> an unknown type of enter/leave event occurred. + line="315">an unknown type of enter/leave event occurred. @@ -24795,13 +28569,13 @@ is given in the main loop. glib:fundamental="1"> An event related to a pad-based device. + line="2870">An event related to a pad-based device. Extracts the information from a pad strip or ring event. - + line="2991">Extracts the information from a pad strip or ring event. + @@ -24809,7 +28583,7 @@ is given in the main loop. a pad strip or ring event + line="2993">a pad strip or ring event transfer-ownership="full"> Return location for the axis index + line="2994">Return location for the axis index transfer-ownership="full"> Return location for the axis value + line="2995">Return location for the axis value @@ -24835,20 +28609,20 @@ is given in the main loop. Extracts information about the pressed button from + line="2970">Extracts information about the pressed button from a pad event. - + the button of @event + line="2977">the button of @event a pad button event + line="2972">a pad button event @@ -24857,8 +28631,8 @@ a pad event. c:identifier="gdk_pad_event_get_group_mode"> Extracts group and mode information from a pad event. - + line="3014">Extracts group and mode information from a pad event. + @@ -24866,7 +28640,7 @@ a pad event. a pad event + line="3016">a pad event transfer-ownership="full"> return location for the group + line="3017">return location for the group transfer-ownership="full"> return location for the mode + line="3018">return location for the mode @@ -24898,8 +28672,7 @@ a pad event. glib:type-struct="PaintableInterface"> `GdkPaintable` is a simple interface used by GTK to represent content that -can be painted. + line="38">An interface for content that can be painted. The content of a `GdkPaintable` can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by @@ -24947,7 +28720,7 @@ useful for implementing subclasses and should not be used by applications: Returns a paintable that has the given intrinsic size and draws nothing. + line="673">Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the [vfunc@Gdk.Paintable.get_current_image] virtual function @@ -24958,20 +28731,20 @@ the first frame). a `GdkPaintable` + line="686">a `GdkPaintable` The intrinsic width to report. Can be 0 for no width. + line="675">The intrinsic width to report. Can be 0 for no width. The intrinsic height to report. Can be 0 for no height. + line="676">The intrinsic height to report. Can be 0 for no height. @@ -24979,7 +28752,7 @@ the first frame). Gets an immutable paintable for the current contents displayed by @paintable. + line="265">Gets an immutable paintable for the current contents displayed by @paintable. This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation. @@ -24989,7 +28762,7 @@ If the @paintable is already immutable, it will return itself. An immutable paintable for the current + line="276">An immutable paintable for the current contents of @paintable @@ -24997,7 +28770,7 @@ If the @paintable is already immutable, it will return itself. a `GdkPaintable` + line="267">a `GdkPaintable` @@ -25005,7 +28778,7 @@ If the @paintable is already immutable, it will return itself. Get flags for the paintable. + line="293">Get flags for the paintable. This is oftentimes useful for optimizations. @@ -25014,14 +28787,14 @@ See [flags@Gdk.PaintableFlags] for the flags and what they mean. The `GdkPaintableFlags` for this paintable + line="303">The `GdkPaintableFlags` for this paintable a `GdkPaintable` + line="295">a `GdkPaintable` @@ -25030,7 +28803,7 @@ See [flags@Gdk.PaintableFlags] for the flags and what they mean. invoker="get_intrinsic_aspect_ratio"> Gets the preferred aspect ratio the @paintable would like to be displayed at. + line="372">Gets the preferred aspect ratio the @paintable would like to be displayed at. The aspect ratio is the width divided by the height, so a value of 0.5 means that the @paintable prefers to be displayed twice as high as it @@ -25051,14 +28824,14 @@ it returns 0. Negative values are never returned. the intrinsic aspect ratio of @paintable or 0 if none. + line="394">the intrinsic aspect ratio of @paintable or 0 if none. a `GdkPaintable` + line="374">a `GdkPaintable` @@ -25067,7 +28840,7 @@ it returns 0. Negative values are never returned. invoker="get_intrinsic_height"> Gets the preferred height the @paintable would like to be displayed at. + line="344">Gets the preferred height the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. @@ -25081,14 +28854,14 @@ Negative values are never returned. the intrinsic height of @paintable or 0 if none. + line="359">the intrinsic height of @paintable or 0 if none. a `GdkPaintable` + line="346">a `GdkPaintable` @@ -25096,7 +28869,7 @@ Negative values are never returned. Gets the preferred width the @paintable would like to be displayed at. + line="316">Gets the preferred width the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. @@ -25110,14 +28883,14 @@ Negative values are never returned. the intrinsic width of @paintable or 0 if none. + line="331">the intrinsic width of @paintable or 0 if none. a `GdkPaintable` + line="318">a `GdkPaintable` @@ -25125,7 +28898,7 @@ Negative values are never returned. Snapshots the given paintable with the given @width and @height. + line="223">Snapshots the given paintable with the given @width and @height. The paintable is drawn at the current (0,0) offset of the @snapshot. If @width and @height are not larger than zero, this function will @@ -25138,25 +28911,25 @@ do nothing. a `GdkPaintable` + line="225">a `GdkPaintable` a `GdkSnapshot` to snapshot to + line="226">a `GdkSnapshot` to snapshot to width to snapshot in + line="227">width to snapshot in height to snapshot in + line="228">height to snapshot in @@ -25165,7 +28938,7 @@ do nothing. c:identifier="gdk_paintable_compute_concrete_size"> Compute a concrete size for the `GdkPaintable`. + line="455">Compute a concrete size for the `GdkPaintable`. Applies the sizing algorithm outlined in the [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing) @@ -25183,34 +28956,34 @@ other dimension when only one dimension is given. a `GdkPaintable` + line="457">a `GdkPaintable` the width @paintable could be drawn into or + line="458">the width @paintable could be drawn into or 0.0 if unknown the height @paintable could be drawn into or + line="460">the height @paintable could be drawn into or 0.0 if unknown the width @paintable would be drawn into if + line="462">the width @paintable would be drawn into if no other constraints were given the height @paintable would be drawn into if + line="464">the height @paintable would be drawn into if no other constraints were given @@ -25220,7 +28993,7 @@ other dimension when only one dimension is given. transfer-ownership="full"> will be set to the concrete width computed + line="466">will be set to the concrete width computed transfer-ownership="full"> will be set to the concrete height computed + line="467">will be set to the concrete height computed @@ -25238,7 +29011,7 @@ other dimension when only one dimension is given. c:identifier="gdk_paintable_get_current_image"> Gets an immutable paintable for the current contents displayed by @paintable. + line="265">Gets an immutable paintable for the current contents displayed by @paintable. This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation. @@ -25248,7 +29021,7 @@ If the @paintable is already immutable, it will return itself. An immutable paintable for the current + line="276">An immutable paintable for the current contents of @paintable @@ -25256,7 +29029,7 @@ If the @paintable is already immutable, it will return itself. a `GdkPaintable` + line="267">a `GdkPaintable` @@ -25264,7 +29037,7 @@ If the @paintable is already immutable, it will return itself. Get flags for the paintable. + line="293">Get flags for the paintable. This is oftentimes useful for optimizations. @@ -25273,14 +29046,14 @@ See [flags@Gdk.PaintableFlags] for the flags and what they mean. The `GdkPaintableFlags` for this paintable + line="303">The `GdkPaintableFlags` for this paintable a `GdkPaintable` + line="295">a `GdkPaintable` @@ -25289,7 +29062,7 @@ See [flags@Gdk.PaintableFlags] for the flags and what they mean. c:identifier="gdk_paintable_get_intrinsic_aspect_ratio"> Gets the preferred aspect ratio the @paintable would like to be displayed at. + line="372">Gets the preferred aspect ratio the @paintable would like to be displayed at. The aspect ratio is the width divided by the height, so a value of 0.5 means that the @paintable prefers to be displayed twice as high as it @@ -25310,14 +29083,14 @@ it returns 0. Negative values are never returned. the intrinsic aspect ratio of @paintable or 0 if none. + line="394">the intrinsic aspect ratio of @paintable or 0 if none. a `GdkPaintable` + line="374">a `GdkPaintable` @@ -25326,7 +29099,7 @@ it returns 0. Negative values are never returned. c:identifier="gdk_paintable_get_intrinsic_height"> Gets the preferred height the @paintable would like to be displayed at. + line="344">Gets the preferred height the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. @@ -25340,14 +29113,14 @@ Negative values are never returned. the intrinsic height of @paintable or 0 if none. + line="359">the intrinsic height of @paintable or 0 if none. a `GdkPaintable` + line="346">a `GdkPaintable` @@ -25356,7 +29129,7 @@ Negative values are never returned. c:identifier="gdk_paintable_get_intrinsic_width"> Gets the preferred width the @paintable would like to be displayed at. + line="316">Gets the preferred width the @paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable. @@ -25370,14 +29143,14 @@ Negative values are never returned. the intrinsic width of @paintable or 0 if none. + line="331">the intrinsic width of @paintable or 0 if none. a `GdkPaintable` + line="318">a `GdkPaintable` @@ -25386,7 +29159,7 @@ Negative values are never returned. c:identifier="gdk_paintable_invalidate_contents"> Called by implementations of `GdkPaintable` to invalidate their contents. + line="407">Called by implementations of `GdkPaintable` to invalidate their contents. Unless the contents are invalidated, implementations must guarantee that multiple calls of [method@Gdk.Paintable.snapshot] produce the same output. @@ -25404,7 +29177,7 @@ it must not call this function. a `GdkPaintable` + line="409">a `GdkPaintable` @@ -25413,7 +29186,7 @@ it must not call this function. c:identifier="gdk_paintable_invalidate_size"> Called by implementations of `GdkPaintable` to invalidate their size. + line="431">Called by implementations of `GdkPaintable` to invalidate their size. As long as the size is not invalidated, @paintable must return the same values for its intrinsic width, height and aspect ratio. @@ -25431,7 +29204,7 @@ it must not call this function. a `GdkPaintable` + line="433">a `GdkPaintable` @@ -25439,7 +29212,7 @@ it must not call this function. Snapshots the given paintable with the given @width and @height. + line="223">Snapshots the given paintable with the given @width and @height. The paintable is drawn at the current (0,0) offset of the @snapshot. If @width and @height are not larger than zero, this function will @@ -25452,25 +29225,25 @@ do nothing. a `GdkPaintable` + line="225">a `GdkPaintable` a `GdkSnapshot` to snapshot to + line="226">a `GdkSnapshot` to snapshot to width to snapshot in + line="227">width to snapshot in height to snapshot in + line="228">height to snapshot in @@ -25478,7 +29251,7 @@ do nothing. Emitted when the contents of the @paintable change. + line="180">Emitted when the contents of the @paintable change. Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing. @@ -25489,7 +29262,7 @@ the icon theme for an icon changing. Emitted when the intrinsic size of the @paintable changes. + line="198">Emitted when the intrinsic size of the @paintable changes. This means the values reported by at least one of [method@Gdk.Paintable.get_intrinsic_width], @@ -25555,6 +29328,12 @@ that will make the implementation likely quite slow. + Snapshot the paintable. The given @width and @height are + guaranteed to be larger than 0.0. The resulting snapshot must modify + only the area in the rectangle from (0,0) to (width, height). + This is the only function that must be implemented for this interface. @@ -25564,37 +29343,42 @@ that will make the implementation likely quite slow. a `GdkPaintable` + line="225">a `GdkPaintable` a `GdkSnapshot` to snapshot to + line="226">a `GdkSnapshot` to snapshot to width to snapshot in + line="227">width to snapshot in height to snapshot in + line="228">height to snapshot in + return a `GdkPaintable` that does not change over + time. This means the `GDK_PAINTABLE_STATIC_SIZE` and + `GDK_PAINTABLE_STATIC_CONTENTS` flag are set. An immutable paintable for the current + line="276">An immutable paintable for the current contents of @paintable @@ -25602,83 +29386,103 @@ that will make the implementation likely quite slow. a `GdkPaintable` + line="267">a `GdkPaintable` + Get the flags for this instance. See [flags@Gdk.PaintableFlags] + for details. The `GdkPaintableFlags` for this paintable + line="303">The `GdkPaintableFlags` for this paintable a `GdkPaintable` + line="295">a `GdkPaintable` + The preferred width for this object to be + snapshot at or 0 if none. This is purely a hint. The object must still + be able to render at any size. the intrinsic width of @paintable or 0 if none. + line="331">the intrinsic width of @paintable or 0 if none. a `GdkPaintable` + line="318">a `GdkPaintable` + The preferred height for this object to be + snapshot at or 0 if none. This is purely a hint. The object must still + be able to render at any size. the intrinsic height of @paintable or 0 if none. + line="359">the intrinsic height of @paintable or 0 if none. a `GdkPaintable` + line="346">a `GdkPaintable` + The preferred aspect ratio for this object + or 0 if none. If both [vfunc@Gdk.Paintable.get_intrinsic_width] + and [vfunc@Gdk.Paintable.get_intrinsic_height] return non-zero + values, this function should return the aspect ratio computed from those. the intrinsic aspect ratio of @paintable or 0 if none. + line="394">the intrinsic aspect ratio of @paintable or 0 if none. a `GdkPaintable` + line="374">a `GdkPaintable` @@ -25693,7 +29497,7 @@ that will make the implementation likely quite slow. glib:type-struct="PopupInterface"> A `GdkPopup` is a surface that is attached to another surface. + line="26">A surface that is attached to another surface. The `GdkPopup` is positioned relative to its parent surface. @@ -25705,7 +29509,6 @@ property. - Returns whether this popup is set to hide on outside clicks. @@ -25728,7 +29531,6 @@ property. - Returns the parent surface of a popup. @@ -25840,7 +29642,7 @@ or after the [signal@Gdk.Surface::layout] signal is emitted. filename="gdk/gdkpopup.c" line="103">Present @popup after having processed the `GdkPopupLayout` rules. -If the popup was previously now showing, it will be showed, +If the popup was previously not showing, it will be shown, otherwise it will change position according to @layout. After calling this function, the result should be handled in response @@ -25893,7 +29695,6 @@ the [signal@Gdk.Surface::layout] signal will not me emitted. transfer-ownership="none" getter="get_autohide" default-value="FALSE"> - Whether to hide on outside clicks. @@ -25904,7 +29705,6 @@ the [signal@Gdk.Surface::layout] signal will not me emitted. construct-only="1" transfer-ownership="none" getter="get_parent"> - The parent surface. @@ -25926,8 +29726,8 @@ the [signal@Gdk.Surface::layout] signal will not me emitted. c:symbol-prefix="popup_layout"> The `GdkPopupLayout` struct contains information that is -necessary position a [iface@Gdk.Popup] relative to its parent. + line="26">Contains information that is necessary position a [iface@Gdk.Popup] +relative to its parent. The positioning requires a negotiation with the windowing system, since it depends on external constraints, such as the position of @@ -26449,7 +30249,7 @@ surrounding the window, would there be any. glib:fundamental="1"> An event related to the proximity of a tool to a device. + line="3204">An event related to the proximity of a tool to a device. c:symbol-prefix="rgba"> A `GdkRGBA` is used to represent a color, in a way that is compatible -with cairo’s notion of color. + line="38">Represents a color, in a way that is compatible with cairo’s notion of color. `GdkRGBA` is a convenient way to pass colors around. It’s based on cairo’s way to deal with colors and mirrors its behavior. All values @@ -26496,21 +30295,21 @@ be clamped to this range when drawing. Makes a copy of a `GdkRGBA`. + line="56">Makes a copy of a `GdkRGBA`. The result must be freed through [method@Gdk.RGBA.free]. A newly allocated `GdkRGBA`, with the same contents as @rgba + line="64">A newly allocated `GdkRGBA`, with the same contents as @rgba a `GdkRGBA` + line="58">a `GdkRGBA` @@ -26518,25 +30317,25 @@ The result must be freed through [method@Gdk.RGBA.free]. Compares two `GdkRGBA` colors. + line="360">Compares two `GdkRGBA` colors. %TRUE if the two colors compare equal + line="367">%TRUE if the two colors compare equal a `GdkRGBA` + line="362">a `GdkRGBA` another `GdkRGBA` + line="363">another `GdkRGBA` @@ -26544,7 +30343,7 @@ The result must be freed through [method@Gdk.RGBA.free]. Frees a `GdkRGBA`. + line="77">Frees a `GdkRGBA`. @@ -26553,7 +30352,7 @@ The result must be freed through [method@Gdk.RGBA.free]. a `GdkRGBA` + line="79">a `GdkRGBA` @@ -26561,20 +30360,20 @@ The result must be freed through [method@Gdk.RGBA.free]. A hash function suitable for using for a hash + line="340">A hash function suitable for using for a hash table that stores `GdkRGBA`s. The hash value for @p + line="347">The hash value for @p a `GdkRGBA` + line="342">a `GdkRGBA` @@ -26582,21 +30381,21 @@ table that stores `GdkRGBA`s. Checks if an @rgba value is transparent. + line="89">Checks if an @rgba value is transparent. That is, drawing with the value would not produce any change. %TRUE if the @rgba is clear + line="97">%TRUE if the @rgba is clear a `GdkRGBA` + line="91">a `GdkRGBA` @@ -26604,7 +30403,7 @@ That is, drawing with the value would not produce any change. Checks if an @rgba value is opaque. + line="105">Checks if an @rgba value is opaque. That is, drawing with the value will not retain any results from previous contents. @@ -26612,14 +30411,14 @@ from previous contents. %TRUE if the @rgba is opaque + line="114">%TRUE if the @rgba is opaque a `GdkRGBA` + line="107">a `GdkRGBA` @@ -26627,7 +30426,7 @@ from previous contents. Parses a textual representation of a color. + line="163">Parses a textual representation of a color. The string can be either one of: @@ -26651,20 +30450,20 @@ in the range 0 to 1. %TRUE if the parsing succeeded + line="189">%TRUE if the parsing succeeded the `GdkRGBA` to fill in + line="165">the `GdkRGBA` to fill in the string specifying the color + line="166">the string specifying the color @@ -26672,7 +30471,7 @@ in the range 0 to 1. Returns a textual specification of @rgba in the form + line="376">Returns a textual specification of @rgba in the form `rgb(r,g,b)` or `rgba(r,g,b,a)`, where “r”, “g”, “b” and “a” represent the red, green, blue and alpha values respectively. “r”, “g”, and “b” are represented as integers @@ -26689,14 +30488,14 @@ this is a concern, you should use a different representation. A newly allocated text string + line="394">A newly allocated text string a `GdkRGBA` + line="378">a `GdkRGBA` @@ -26709,7 +30508,7 @@ this is a concern, you should use a different representation. c:symbol-prefix="rectangle"> A `GdkRectangle` data type for representing rectangles. + line="31">Represents a rectangle. `GdkRectangle` is identical to `cairo_rectangle_t`. Together with Cairo’s `cairo_region_t` data type, these are the central types for representing @@ -26941,7 +30740,7 @@ zero width or height). c:type="GdkScrollDirection"> Specifies the direction for scroll events. + line="250">Specifies the direction for scroll events. glib:name="GDK_SCROLL_UP"> the surface is scrolled up. + line="252">the surface is scrolled up. glib:name="GDK_SCROLL_DOWN"> the surface is scrolled down. + line="253">the surface is scrolled down. glib:name="GDK_SCROLL_LEFT"> the surface is scrolled to the left. + line="254">the surface is scrolled to the left. glib:name="GDK_SCROLL_RIGHT"> the surface is scrolled to the right. + line="255">the surface is scrolled to the right. glib:name="GDK_SCROLL_SMOOTH"> the scrolling is determined by the delta values + line="256">the scrolling is determined by the delta values in scroll events. See gdk_scroll_event_get_deltas() @@ -26998,18 +30797,18 @@ zero width or height). glib:fundamental="1"> An event related to a scrolling motion. + line="2354">An event related to a scrolling motion. Extracts the scroll deltas of a scroll event. + line="2529">Extracts the scroll deltas of a scroll event. The deltas will be zero unless the scroll direction is %GDK_SCROLL_SMOOTH. For the representation unit of these deltas, see [method@Gdk.ScrollEvent.get_unit]. - + @@ -27017,7 +30816,7 @@ For the representation unit of these deltas, see a scroll event + line="2531">a scroll event return location for x scroll delta + line="2532">return location for x scroll delta return location for y scroll delta + line="2533">return location for y scroll delta @@ -27044,19 +30843,19 @@ For the representation unit of these deltas, see c:identifier="gdk_scroll_event_get_direction"> Extracts the direction of a scroll event. - + line="2510">Extracts the direction of a scroll event. + the scroll direction of @event + line="2516">the scroll direction of @event a scroll event + line="2512">a scroll event @@ -27066,22 +30865,22 @@ For the representation unit of these deltas, see version="4.8"> Extracts the scroll delta unit of a scroll event. + line="2584">Extracts the scroll delta unit of a scroll event. The unit will always be %GDK_SCROLL_UNIT_WHEEL if the scroll direction is not %GDK_SCROLL_SMOOTH. - + the scroll unit. + line="2593">the scroll unit. a scroll event. + line="2586">a scroll event. @@ -27089,7 +30888,7 @@ The unit will always be %GDK_SCROLL_UNIT_WHEEL if the scroll direction is not Check whether a scroll event is a stop scroll event. + line="2557">Check whether a scroll event is a stop scroll event. Scroll sequences with smooth scroll information may provide a stop scroll event once the interaction with the device finishes, @@ -27098,18 +30897,18 @@ that a widget may trigger kinetic scrolling based on the current velocity. Stop scroll events always have a delta of 0/0. - + %TRUE if the event is a scroll stop event + line="2571">%TRUE if the event is a scroll stop event a scroll event + line="2559">a scroll event @@ -27122,7 +30921,7 @@ Stop scroll events always have a delta of 0/0. c:type="GdkScrollUnit"> Specifies the unit of scroll deltas. + line="270">Specifies the unit of scroll deltas. When you get %GDK_SCROLL_UNIT_WHEEL, a delta of 1.0 means 1 wheel detent click in the south direction, 2.0 means 2 wheel detent clicks in the south @@ -27145,7 +30944,7 @@ scale factor and eventually a custom scale factor in your app). glib:name="GDK_SCROLL_UNIT_WHEEL"> The delta is in number of wheel clicks. + line="272">The delta is in number of wheel clicks. glib:name="GDK_SCROLL_UNIT_SURFACE"> The delta is in surface pixels to scroll directly + line="273">The delta is in surface pixels to scroll directly on screen. @@ -27167,24 +30966,23 @@ scale factor and eventually a custom scale factor in your app). glib:get-type="gdk_seat_get_type"> The `GdkSeat` object represents a collection of input devices -that belong to a user. + line="30">Represents a collection of input devices that belong to a user. Returns the capabilities this `GdkSeat` currently has. + line="200">Returns the capabilities this `GdkSeat` currently has. the seat capabilities + line="206">the seat capabilities a `GdkSeat` + line="202">a `GdkSeat` @@ -27192,12 +30990,12 @@ that belong to a user. Returns the devices that match the given capabilities. + line="312">Returns the devices that match the given capabilities. A list + line="319">A list of `GdkDevices`. The list must be freed with g_list_free(), the elements are owned by GTK and must not be freed. @@ -27208,13 +31006,13 @@ that belong to a user. a `GdkSeat` + line="314">a `GdkSeat` capabilities to get devices for + line="315">capabilities to get devices for @@ -27222,15 +31020,14 @@ that belong to a user. - Returns the `GdkDisplay` this seat belongs to. + line="391">Returns the `GdkDisplay` this seat belongs to. a `GdkDisplay`. This object + line="397">a `GdkDisplay`. This object is owned by GTK and must not be freed. @@ -27238,7 +31035,7 @@ that belong to a user. a `GdkSeat` + line="393">a `GdkSeat` @@ -27246,12 +31043,12 @@ that belong to a user. Returns the device that routes keyboard events. + line="355">Returns the device that routes keyboard events. a `GdkDevice` with keyboard + line="361">a `GdkDevice` with keyboard capabilities. This object is owned by GTK and must not be freed. @@ -27259,7 +31056,7 @@ that belong to a user. a `GdkSeat` + line="357">a `GdkSeat` @@ -27267,12 +31064,12 @@ that belong to a user. Returns the device that routes pointer events. + line="335">Returns the device that routes pointer events. a `GdkDevice` with pointer + line="341">a `GdkDevice` with pointer capabilities. This object is owned by GTK and must not be freed. @@ -27280,7 +31077,7 @@ that belong to a user. a `GdkSeat` + line="337">a `GdkSeat` @@ -27288,12 +31085,12 @@ that belong to a user. Returns all `GdkDeviceTools` that are known to the application. + line="451">Returns all `GdkDeviceTools` that are known to the application. + line="457"> A list of tools. Free with g_list_free(). @@ -27303,7 +31100,7 @@ that belong to a user. a `GdkSeat` + line="453">a `GdkSeat` @@ -27313,10 +31110,9 @@ that belong to a user. construct-only="1" transfer-ownership="none" getter="get_display"> - `GdkDisplay` of this seat. + line="180">`GdkDisplay` of this seat. @@ -27325,7 +31121,7 @@ that belong to a user. Emitted when a new input device is related to this seat. + line="108">Emitted when a new input device is related to this seat. @@ -27333,7 +31129,7 @@ that belong to a user. the newly added `GdkDevice`. + line="111">the newly added `GdkDevice`. @@ -27341,7 +31137,7 @@ that belong to a user. Emitted when an input device is removed (e.g. unplugged). + line="125">Emitted when an input device is removed (e.g. unplugged). @@ -27349,7 +31145,7 @@ that belong to a user. the just removed `GdkDevice`. + line="128">the just removed `GdkDevice`. @@ -27357,7 +31153,7 @@ that belong to a user. Emitted whenever a new tool is made known to the seat. + line="142">Emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device (i.e. on proximity with a tablet). The device will emit the @@ -27371,7 +31167,7 @@ A same tool may be used by several devices. the new `GdkDeviceTool` known to the seat + line="145">the new `GdkDeviceTool` known to the seat @@ -27379,7 +31175,7 @@ A same tool may be used by several devices. Emitted whenever a tool is no longer known to this @seat. + line="164">Emitted whenever a tool is no longer known to this @seat. @@ -27387,7 +31183,7 @@ A same tool may be used by several devices. the just removed `GdkDeviceTool` + line="167">the just removed `GdkDeviceTool` @@ -27568,7 +31364,7 @@ of physical pixels on an output device are laid out. glib:type-struct="SurfaceClass"> A `GdkSurface` is a rectangular region on the screen. + line="56">Represents a rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as [GtkWindow](../gtk4/class.Window.html). @@ -27581,7 +31377,7 @@ types exist, but you will rarely interact with them directly. Create a new popup surface. + line="911">Create a new popup surface. The surface will be attached to @parent and can be positioned relative to it using [method@Gdk.Popup.present]. @@ -27589,20 +31385,20 @@ relative to it using [method@Gdk.Popup.present]. a new `GdkSurface` + line="921">a new `GdkSurface` the parent surface to attach the surface to + line="913">the parent surface to attach the surface to whether to hide the surface on outside clicks + line="914">whether to hide the surface on outside clicks @@ -27610,19 +31406,19 @@ relative to it using [method@Gdk.Popup.present]. Creates a new toplevel surface. + line="893">Creates a new toplevel surface. the new `GdkSurface` + line="899">the new `GdkSurface` the display to create the surface on + line="895">the display to create the surface on @@ -27630,7 +31426,7 @@ relative to it using [method@Gdk.Popup.present]. Emits a short beep associated to @surface. + line="2202">Emits a short beep associated to @surface. If the display of @surface does not support per-surface beeps, emits a short beep on the display just as [method@Gdk.Display.beep]. @@ -27642,7 +31438,7 @@ emits a short beep on the display just as [method@Gdk.Display.beep]. a toplevel `GdkSurface` + line="2204">a toplevel `GdkSurface` @@ -27651,19 +31447,19 @@ emits a short beep on the display just as [method@Gdk.Display.beep]. c:identifier="gdk_surface_create_cairo_context"> Creates a new `GdkCairoContext` for rendering on @surface. + line="1294">Creates a new `GdkCairoContext` for rendering on @surface. the newly created `GdkCairoContext` + line="1300">the newly created `GdkCairoContext` a `GdkSurface` + line="1296">a `GdkSurface` @@ -27673,7 +31469,7 @@ emits a short beep on the display just as [method@Gdk.Display.beep]. throws="1"> Creates a new `GdkGLContext` for the `GdkSurface`. + line="1267">Creates a new `GdkGLContext` for the `GdkSurface`. The context is disconnected from any particular surface or surface. If the creation of the `GdkGLContext` failed, @error will be set. @@ -27683,14 +31479,14 @@ call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. the newly created `GdkGLContext` + line="1279">the newly created `GdkGLContext` a `GdkSurface` + line="1269">a `GdkSurface` @@ -27701,7 +31497,7 @@ call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. Create a new Cairo surface that is as compatible as possible with the + line="2359">Create a new Cairo surface that is as compatible as possible with the given @surface. For example the new surface will have the same fallback resolution @@ -27721,7 +31517,7 @@ or any other error occurs. a pointer to the newly allocated surface. The caller + line="2382">a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. @@ -27730,50 +31526,51 @@ or any other error occurs. surface to make new surface similar to + line="2361">surface to make new surface similar to the content for the new surface + line="2362">the content for the new surface width of the new surface + line="2363">width of the new surface height of the new surface + line="2364">height of the new surface Creates a new `GdkVulkanContext` for rendering on @surface. - -If the creation of the `GdkVulkanContext` failed, @error will be set. + line="1316">Sets an error and returns %NULL. + GTK does not expose any Vulkan internals. This + function is a leftover that was accidentally exposed. the newly created `GdkVulkanContext`, or - %NULL on error + line="1323">%NULL a `GdkSurface` + line="1318">a `GdkSurface` @@ -27781,7 +31578,7 @@ If the creation of the `GdkVulkanContext` failed, @error will be set. Destroys the window system resources associated with @surface and + line="1047">Destroys the window system resources associated with @surface and decrements @surface's reference count. The window system resources for all children of @surface are also @@ -27798,7 +31595,7 @@ before that happens. a `GdkSurface` + line="1049">a `GdkSurface` @@ -27806,10 +31603,9 @@ before that happens. - Retrieves a `GdkCursor` pointer for the cursor currently set on the + line="1847">Retrieves a `GdkCursor` pointer for the cursor currently set on the `GdkSurface`. If the return value is %NULL then there is no custom cursor set on @@ -27820,14 +31616,14 @@ Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface. a `GdkCursor` + line="1859">a `GdkCursor` a `GdkSurface` + line="1849">a `GdkSurface` @@ -27836,7 +31632,7 @@ Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface. c:identifier="gdk_surface_get_device_cursor"> Retrieves a `GdkCursor` pointer for the @device currently set on the + line="1926">Retrieves a `GdkCursor` pointer for the @device currently set on the specified `GdkSurface`. If the return value is %NULL then there is no custom cursor set on the @@ -27847,20 +31643,20 @@ Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface. a `GdkCursor` + line="1939">a `GdkCursor` a `GdkSurface` + line="1928">a `GdkSurface` a pointer `GdkDevice` + line="1929">a pointer `GdkDevice` @@ -27869,7 +31665,7 @@ Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface. c:identifier="gdk_surface_get_device_position"> Obtains the current device position and modifier state. + line="1710">Obtains the current device position and modifier state. The position is given in coordinates relative to the upper left corner of @surface. @@ -27877,20 +31673,20 @@ left corner of @surface. %TRUE if the device is over the surface + line="1723">%TRUE if the device is over the surface a `GdkSurface` + line="1712">a `GdkSurface` pointer `GdkDevice` to query to + line="1713">pointer `GdkDevice` to query to allow-none="1"> return location for the X coordinate of @device + line="1714">return location for the X coordinate of @device allow-none="1"> return location for the Y coordinate of @device + line="1715">return location for the Y coordinate of @device allow-none="1"> return location for the modifier mask + line="1716">return location for the modifier mask @@ -27931,22 +31727,21 @@ left corner of @surface. - Gets the `GdkDisplay` associated with a `GdkSurface`. + line="1085">Gets the `GdkDisplay` associated with a `GdkSurface`. the `GdkDisplay` associated with @surface + line="1091">the `GdkDisplay` associated with @surface a `GdkSurface` + line="1087">a `GdkSurface` @@ -27954,10 +31749,9 @@ left corner of @surface. - Gets the frame clock for the surface. + line="2592">Gets the frame clock for the surface. The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface. @@ -27965,14 +31759,14 @@ reparented to a new toplevel surface. the frame clock + line="2601">the frame clock surface to get frame clock for + line="2594">surface to get frame clock for @@ -27980,10 +31774,9 @@ reparented to a new toplevel surface. - Returns the height of the given @surface. + line="2048">Returns the height of the given @surface. Surface size is reported in ”application pixels”, not ”device pixels” (see [method@Gdk.Surface.get_scale_factor]). @@ -27991,14 +31784,14 @@ Surface size is reported in ”application pixels”, not The height of @surface + line="2057">The height of @surface a `GdkSurface` + line="2050">a `GdkSurface` @@ -28006,10 +31799,9 @@ Surface size is reported in ”application pixels”, not - Checks whether the surface has been mapped. + line="1114">Checks whether the surface has been mapped. A surface is mapped with [method@Gdk.Toplevel.present] or [method@Gdk.Popup.present]. @@ -28017,14 +31809,14 @@ or [method@Gdk.Popup.present]. %TRUE if the surface is mapped + line="1123">%TRUE if the surface is mapped a `GdkSurface` + line="1116">a `GdkSurface` @@ -28033,10 +31825,9 @@ or [method@Gdk.Popup.present]. c:identifier="gdk_surface_get_scale" glib:get-property="scale" version="4.12"> - Returns the internal scale that maps from surface coordinates + line="2637">Returns the internal scale that maps from surface coordinates to the actual device pixels. When the scale is bigger than 1, the windowing system prefers to get @@ -28051,14 +31842,14 @@ The scale may change during the lifetime of the surface. the scale + line="2653">the scale surface to get scale for + line="2639">surface to get scale for @@ -28066,10 +31857,9 @@ The scale may change during the lifetime of the surface. - Returns the internal scale factor that maps from surface coordinates + line="2611">Returns the internal scale factor that maps from surface coordinates to the actual device pixels. On traditional systems this is 1, but on very high density outputs @@ -28084,14 +31874,14 @@ The scale factor may change during the lifetime of the surface. the scale factor + line="2627">the scale factor surface to get scale factor for + line="2613">surface to get scale factor for @@ -28099,10 +31889,9 @@ The scale factor may change during the lifetime of the surface. - Returns the width of the given @surface. + line="2029">Returns the width of the given @surface. Surface size is reported in ”application pixels”, not ”device pixels” (see [method@Gdk.Surface.get_scale_factor]). @@ -28110,14 +31899,14 @@ Surface size is reported in ”application pixels”, not The width of @surface + line="2038">The width of @surface a `GdkSurface` + line="2031">a `GdkSurface` @@ -28125,7 +31914,7 @@ Surface size is reported in ”application pixels”, not Hide the surface. + line="1759">Hide the surface. For toplevel surfaces, withdraws them, so they will no longer be known to the window manager; for all surfaces, unmaps them, so @@ -28139,7 +31928,7 @@ part of [gtk_widget_hide()](../gtk4/method.Widget.hide.html). a `GdkSurface` + line="1761">a `GdkSurface` @@ -28147,19 +31936,19 @@ part of [gtk_widget_hide()](../gtk4/method.Widget.hide.html). Check to see if a surface is destroyed. + line="1100">Check to see if a surface is destroyed. %TRUE if the surface is destroyed + line="1106">%TRUE if the surface is destroyed a `GdkSurface` + line="1102">a `GdkSurface` @@ -28167,7 +31956,7 @@ part of [gtk_widget_hide()](../gtk4/method.Widget.hide.html). Forces a [signal@Gdk.Surface::render] signal emission for @surface + line="1500">Forces a [signal@Gdk.Surface::render] signal emission for @surface to be scheduled. This function is useful for implementations that track invalid @@ -28180,7 +31969,7 @@ regions on their own. a `GdkSurface` + line="1502">a `GdkSurface` @@ -28188,7 +31977,7 @@ regions on their own. Request a layout phase from the surface's frame clock. + line="1392">Request a layout phase from the surface's frame clock. See [method@Gdk.FrameClock.request_phase]. @@ -28199,7 +31988,7 @@ See [method@Gdk.FrameClock.request_phase]. a `GdkSurface` + line="1394">a `GdkSurface` @@ -28207,10 +31996,9 @@ See [method@Gdk.FrameClock.request_phase]. - Sets the default mouse pointer for a `GdkSurface`. + line="1869">Sets the default mouse pointer for a `GdkSurface`. Passing %NULL for the @cursor argument means that @surface will use the cursor of its parent surface. Most surfaces should use this default. @@ -28226,7 +32014,7 @@ to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. a `GdkSurface` + line="1871">a `GdkSurface` allow-none="1"> a `GdkCursor` + line="1872">a `GdkCursor` @@ -28244,7 +32032,7 @@ to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. c:identifier="gdk_surface_set_device_cursor"> Sets a specific `GdkCursor` for a given device when it gets inside @surface. + line="1952">Sets a specific `GdkCursor` for a given device when it gets inside @surface. Passing %NULL for the @cursor argument means that @surface will use the cursor of its parent surface. Most surfaces should use this default. @@ -28259,19 +32047,19 @@ to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. a `GdkSurface` + line="1954">a `GdkSurface` a pointer `GdkDevice` + line="1955">a pointer `GdkDevice` a `GdkCursor` + line="1956">a `GdkCursor` @@ -28280,7 +32068,7 @@ to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. c:identifier="gdk_surface_set_input_region"> Apply the region to the surface for the purpose of event + line="2121">Apply the region to the surface for the purpose of event handling. Mouse events which happen while the pointer position corresponds @@ -28302,22 +32090,24 @@ a particular backend supports input regions. a `GdkSurface` + line="2123">a `GdkSurface` region of surface to be reactive + line="2124">region of surface to be reactive + c:identifier="gdk_surface_set_opaque_region" + deprecated="1" + deprecated-version="4.16"> Marks a region of the `GdkSurface` as opaque. + line="2697">Marks a region of the `GdkSurface` as opaque. For optimisation purposes, compositing window managers may like to not draw obscured regions of surfaces, or turn off blending @@ -28332,6 +32122,8 @@ GTK will update this property automatically if the @surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your [GtkWidgetClass.css_changed](../gtk4/vfunc.Widget.css_changed.html) handler. + GDK can figure out the opaque parts of a window itself + by inspecting the contents that are drawn. @@ -28340,7 +32132,7 @@ background is not opaque, please update this property in your a top-level `GdkSurface` + line="2699">a top-level `GdkSurface` a region, or %NULL to make the entire + line="2700">a region, or %NULL to make the entire surface opaque @@ -28359,7 +32151,7 @@ background is not opaque, please update this property in your c:identifier="gdk_surface_translate_coordinates"> Translates coordinates between two surfaces. + line="3109">Translates coordinates between two surfaces. Note that this only works if @to and @from are popups or transient-for to the same toplevel (directly or indirectly). @@ -28367,20 +32159,20 @@ transient-for to the same toplevel (directly or indirectly). %TRUE if the coordinates were successfully translated + line="3121">%TRUE if the coordinates were successfully translated the origin surface + line="3111">the origin surface the target surface + line="3112">the target surface transfer-ownership="full"> coordinates to translate + line="3113">coordinates to translate transfer-ownership="full"> coordinates to translate + line="3114">coordinates to translate @@ -28408,11 +32200,9 @@ transient-for to the same toplevel (directly or indirectly). transfer-ownership="none" setter="set_cursor" getter="get_cursor"> - - The mouse pointer for the `GdkSurface`. + line="549">The mouse pointer for the `GdkSurface`. construct-only="1" transfer-ownership="none" getter="get_display"> - The `GdkDisplay` connection of the surface. + line="559">The `GdkDisplay` connection of the surface. construct-only="1" transfer-ownership="none" getter="get_frame_clock"> - The `GdkFrameClock` of the surface. + line="569">The `GdkFrameClock` of the surface. - The height of the surface, in pixels. + line="599">The height of the surface, in pixels. - Whether the surface is mapped. + line="579">Whether the surface is mapped. transfer-ownership="none" getter="get_scale" default-value="1.000000"> - The scale of the surface. + line="622">The scale of the surface. - The scale factor of the surface. + line="609">The scale factor of the surface. The scale factor is the next larger integer, compared to [property@Gdk.Surface:scale]. @@ -28488,16 +32269,15 @@ compared to [property@Gdk.Surface:scale]. transfer-ownership="none" getter="get_width" default-value="0"> - The width of the surface in pixels. + line="589">The width of the surface in pixels. Emitted when @surface starts being present on the monitor. + line="712">Emitted when @surface starts being present on the monitor. @@ -28505,7 +32285,7 @@ compared to [property@Gdk.Surface:scale]. the monitor + line="715">the monitor @@ -28513,18 +32293,18 @@ compared to [property@Gdk.Surface:scale]. Emitted when GDK receives an input event for @surface. + line="688">Emitted when GDK receives an input event for @surface. %TRUE to indicate that the event has been handled + line="695">%TRUE to indicate that the event has been handled an input event + line="691">an input event @@ -28532,7 +32312,7 @@ compared to [property@Gdk.Surface:scale]. Emitted when the size of @surface is changed, or when relayout should + line="636">Emitted when the size of @surface is changed, or when relayout should be performed. Surface size is reported in ”application pixels”, not @@ -28544,13 +32324,13 @@ Surface size is reported in ”application pixels”, not the current width + line="639">the current width the current height + line="640">the current height @@ -28558,7 +32338,7 @@ Surface size is reported in ”application pixels”, not Emitted when @surface stops being present on the monitor. + line="731">Emitted when @surface stops being present on the monitor. @@ -28566,7 +32346,7 @@ Surface size is reported in ”application pixels”, not the monitor + line="734">the monitor @@ -28574,18 +32354,18 @@ Surface size is reported in ”application pixels”, not Emitted when part of the surface needs to be redrawn. + line="664">Emitted when part of the surface needs to be redrawn. %TRUE to indicate that the signal has been handled + line="671">%TRUE to indicate that the signal has been handled the region that needs to be redrawn + line="667">the region that needs to be redrawn @@ -28697,7 +32477,7 @@ Surface size is reported in ”application pixels”, not glib:type-struct="TextureClass"> `GdkTexture` is the basic element used to refer to pixel data. + line="19">Refers to pixel data in various forms. It is primarily meant for pixel data that will not change over multiple frames, and will be used for a long time. @@ -28711,7 +32491,18 @@ instance; you can only make a copy of it, via [method@Gdk.Texture.download]. `GdkTexture` is an immutable object: That means you cannot change anything about it other than increasing the reference count via -[method@GObject.Object.ref], and consequently, it is a thread-safe object. +[method@GObject.Object.ref], and consequently, it is a threadsafe object. + +GDK provides a number of threadsafe texture loading functions: +[ctor@Gdk.Texture.new_from_resource], +[ctor@Gdk.Texture.new_from_bytes], +[ctor@Gdk.Texture.new_from_file], +[ctor@Gdk.Texture.new_from_filename], +[ctor@Gdk.Texture.new_for_pixbuf]. Note that these are meant for loading +icons and resources that are shipped with the toolkit or application. It +is recommended that you use a dedicated image loading framework such as +[glycin](https://lib.rs/crates/glycin), if you need to load untrusted image +data. @@ -28720,7 +32511,7 @@ anything about it other than increasing the reference count via c:identifier="gdk_texture_new_for_pixbuf"> Creates a new texture object representing the `GdkPixbuf`. + line="523">Creates a new texture object representing the `GdkPixbuf`. This function is threadsafe, so that you can e.g. use GTask and [method@Gio.Task.run_in_thread] to avoid blocking the main thread @@ -28729,14 +32520,14 @@ while loading a big image. a new `GdkTexture` + line="533">a new `GdkTexture` a `GdkPixbuf` + line="525">a `GdkPixbuf` @@ -28747,7 +32538,7 @@ while loading a big image. throws="1"> Creates a new texture by loading an image from memory, + line="698">Creates a new texture by loading an image from memory, The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. @@ -28761,14 +32552,14 @@ while loading a big image. A newly-created `GdkTexture` + line="714">A newly-created `GdkTexture` a `GBytes` containing the data to load + line="700">a `GBytes` containing the data to load @@ -28778,7 +32569,7 @@ while loading a big image. throws="1"> Creates a new texture by loading an image from a file. + line="605">Creates a new texture by loading an image from a file. The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. @@ -28792,14 +32583,14 @@ while loading a big image. A newly-created `GdkTexture` + line="621">A newly-created `GdkTexture` `GFile` to load + line="607">`GFile` to load @@ -28810,7 +32601,7 @@ while loading a big image. throws="1"> Creates a new texture by loading an image from a file. + line="744">Creates a new texture by loading an image from a file. The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available. @@ -28824,14 +32615,14 @@ while loading a big image. A newly-created `GdkTexture` + line="760">A newly-created `GdkTexture` the filename to load + line="746">the filename to load @@ -28840,7 +32631,7 @@ while loading a big image. c:identifier="gdk_texture_new_from_resource"> Creates a new texture by loading an image from a resource. + line="561">Creates a new texture by loading an image from a resource. The file format is detected automatically. The supported formats are PNG and JPEG, though more formats might be available. @@ -28857,14 +32648,14 @@ while loading a big image. A newly-created `GdkTexture` + line="579">A newly-created `GdkTexture` the path of the resource file + line="563">the path of the resource file @@ -28872,7 +32663,7 @@ while loading a big image. Downloads the @texture into local memory. + line="981">Downloads the @texture into local memory. This may be an expensive operation, as the actual texture data may reside on a GPU or on a remote display server. @@ -28892,9 +32683,9 @@ gdk_texture_download (texture, cairo_surface_mark_dirty (surface); ``` -For more flexible download capabilites, see +For more flexible download capabilities, see [struct@Gdk.TextureDownloader]. - + @@ -28902,13 +32693,13 @@ For more flexible download capabilites, see a `GdkTexture` + line="983">a `GdkTexture` pointer to enough memory to be filled with the + line="984">pointer to enough memory to be filled with the downloaded data of @texture @@ -28917,17 +32708,40 @@ For more flexible download capabilites, see rowstride in bytes + line="986">rowstride in bytes + + Returns the color state associated with the texture. + + + the color state of the `GdkTexture` + + + + + a `GdkTexture` + + + + Gets the memory format most closely associated with the data of + line="1027">Gets the memory format most closely associated with the data of the texture. Note that it may not be an exact match for texture data @@ -28940,14 +32754,14 @@ downloading the texture. the preferred format for the texture's data + line="1041">the preferred format for the texture's data a GdkTexture + line="1029">a GdkTexture @@ -28955,22 +32769,21 @@ downloading the texture. - Returns the height of the @texture, in pixels. + line="799">Returns the height of the @texture, in pixels. the height of the `GdkTexture` + line="805">the height of the `GdkTexture` a `GdkTexture` + line="801">a `GdkTexture` @@ -28978,22 +32791,21 @@ downloading the texture. - Returns the width of @texture, in pixels. + line="783">Returns the width of @texture, in pixels. the width of the `GdkTexture` + line="789">the width of the `GdkTexture` a `GdkTexture` + line="785">a `GdkTexture` @@ -29001,31 +32813,31 @@ downloading the texture. Store the given @texture to the @filename as a PNG file. + line="1107">Store the given @texture to the @filename as a PNG file. This is a utility function intended for debugging and testing. If you want more control over formats, proper error handling or want to store to a [iface@Gio.File] or other location, you might want to use [method@Gdk.Texture.save_to_png_bytes] or look into the gdk-pixbuf library. - + %TRUE if saving succeeded, %FALSE on failure. + line="1120">%TRUE if saving succeeded, %FALSE on failure. a `GdkTexture` + line="1109">a `GdkTexture` the filename to store to + line="1110">the filename to store to @@ -29035,7 +32847,7 @@ gdk-pixbuf library. version="4.6"> Store the given @texture in memory as a PNG file. + line="1142">Store the given @texture in memory as a PNG file. Use [ctor@Gdk.Texture.new_from_bytes] to read it back. @@ -29049,18 +32861,18 @@ library such as the gdk-pixbuf library. If you are dealing with high dynamic range float data, you might also want to consider [method@Gdk.Texture.save_to_tiff_bytes] instead. - + a newly allocated `GBytes` containing PNG data + line="1161">a newly allocated `GBytes` containing PNG data a `GdkTexture` + line="1144">a `GdkTexture` @@ -29070,27 +32882,27 @@ instead. version="4.6"> Store the given @texture to the @filename as a TIFF file. + line="1173">Store the given @texture to the @filename as a TIFF file. GTK will attempt to store data without loss. - + %TRUE if saving succeeded, %FALSE on failure. + line="1181">%TRUE if saving succeeded, %FALSE on failure. a `GdkTexture` + line="1175">a `GdkTexture` the filename to store to + line="1176">the filename to store to @@ -29100,7 +32912,7 @@ GTK will attempt to store data without loss. version="4.6"> Store the given @texture in memory as a TIFF file. + line="1205">Store the given @texture in memory as a TIFF file. Use [ctor@Gdk.Texture.new_from_bytes] to read it back. @@ -29112,32 +32924,42 @@ images and floating-point texture data. If that is not your concern and you are interested in a smaller size and a more portable format, you might want to use [method@Gdk.Texture.save_to_png_bytes]. - + a newly allocated `GBytes` containing TIFF data + line="1222">a newly allocated `GBytes` containing TIFF data a `GdkTexture` + line="1207">a `GdkTexture` + + The color state of the texture. + + - The height of the texture, in pixels. + line="412">The height of the texture, in pixels. transfer-ownership="none" getter="get_width" default-value="1"> - The width of the texture, in pixels. + line="397">The width of the texture, in pixels. @@ -29169,35 +32990,37 @@ use [method@Gdk.Texture.save_to_png_bytes]. c:symbol-prefix="texture_downloader"> The `GdkTextureDownloader` is used to download the contents of a -[class@Gdk.Texture]. + line="18">Used to download the contents of a [class@Gdk.Texture]. It is intended to be created as a short-term object for a single download, -but can be used for multipe downloads of different textures or with different +but can be used for multiple downloads of different textures or with different settings. `GdkTextureDownloader` can be used to convert data between different formats. Create a `GdkTexture` for the existing format and then download it in a different format. - + Creates a new texture downloader for @texture. + line="64">Creates a new texture downloader for @texture. + +By default, the downloader will convert the data to +the default memory format, and to the sRGB color state. A new texture downloader + line="73">A new texture downloader texture to download + line="66">texture to download @@ -29207,21 +33030,21 @@ different format. version="4.10"> Creates a copy of the downloader. + line="90">Creates a copy of the downloader. This function is meant for language bindings. A copy of the downloader + line="98">A copy of the downloader the downloader to copy + line="92">the downloader to copy @@ -29232,25 +33055,25 @@ This function is meant for language bindings. version="4.10"> Downloads the given texture pixels into a `GBytes`. The rowstride will + line="269">Downloads the given texture pixels into a `GBytes`. The rowstride will be stored in the stride value. This function will abort if it tries to download a large texture and fails to allocate memory. If you think that may happen, you should handle memory allocation yourself and use [method@Gdk.TextureDownloader.download_into] once allocation succeeded. - + The downloaded pixels + line="282">The downloaded pixels the downloader + line="271">the downloader @@ -29260,7 +33083,7 @@ once allocation succeeded. transfer-ownership="full"> The stride of the resulting data in bytes + line="272">The stride of the resulting data in bytes @@ -29270,8 +33093,8 @@ once allocation succeeded. version="4.10"> Downloads the @texture into local memory. - + line="246">Downloads the @texture into local memory. + @@ -29279,14 +33102,14 @@ once allocation succeeded. a texture downloader + line="248">a texture downloader pointer to enough memory to be filled with the + line="249">pointer to enough memory to be filled with the downloaded data of the texture @@ -29295,7 +33118,7 @@ once allocation succeeded. rowstride in bytes + line="251">rowstride in bytes @@ -29305,7 +33128,7 @@ once allocation succeeded. version="4.10"> Frees the given downloader and all its associated resources. + line="115">Frees the given downloader and all its associated resources. @@ -29314,29 +33137,52 @@ once allocation succeeded. texture downloader to free + line="117">texture downloader to free + + Gets the color state that the data will be downloaded in. + + + The color state of the download + + + + + a texture downloader + + + + Gets the format that the data will be downloaded in. + line="189">Gets the format that the data will be downloaded in. The format of the download + line="195">The format of the download a texture downloader + line="191">a texture downloader @@ -29347,30 +33193,58 @@ once allocation succeeded. version="4.10"> Gets the texture that the downloader will download. + line="151">Gets the texture that the downloader will download. The texture to download + line="157">The texture to download a texture downloader + line="153">a texture downloader + + Sets the color state the downloader will convert the data to. + +By default, the sRGB colorstate returned by [func@ColorState.get_srgb] +is used. + + + + + + + a texture downloader + + + + the color state to use + + + + Sets the format the downloader will download. + line="169">Sets the format the downloader will download. By default, GDK_MEMORY_DEFAULT is set. @@ -29381,13 +33255,13 @@ By default, GDK_MEMORY_DEFAULT is set. a texture downloader + line="171">a texture downloader the format to use + line="172">the format to use @@ -29397,7 +33271,7 @@ By default, GDK_MEMORY_DEFAULT is set. version="4.10"> Changes the texture the downloader will download. + line="132">Changes the texture the downloader will download. @@ -29406,13 +33280,13 @@ By default, GDK_MEMORY_DEFAULT is set. a texture downloader + line="134">a texture downloader the new texture to download + line="135">the new texture to download @@ -29465,7 +33339,13 @@ By default, GDK_MEMORY_DEFAULT is set. line="48">The image format is not supported + Registers an error quark for [class@Gdk.Texture] errors. + the error quark @@ -29473,7 +33353,7 @@ By default, GDK_MEMORY_DEFAULT is set. A `GdkTimeCoord` stores a single event in a motion history. + line="63">Stores a single event in a motion history. To check whether an axis is present, check whether the corresponding flag from the [flags@Gdk.AxisFlags] enumeration is set in the @flags @@ -29506,23 +33386,36 @@ the [enum@Gdk.AxisUse] enumerations as indices. glib:type-name="GdkTitlebarGesture" glib:get-type="gdk_titlebar_gesture_get_type" c:type="GdkTitlebarGesture"> + The kind of title bar gesture to emit with +[method@Gdk.Toplevel.titlebar_gesture]. + double click gesture + right click gesture + middle click gesture glib:type-struct="ToplevelInterface"> A `GdkToplevel` is a freestanding toplevel surface. + line="32">A freestanding toplevel surface. The `GdkToplevel` interface provides useful APIs for interacting with the windowing system, such as controlling maximization and size of the surface, setting icons and transient parents for dialogs. - + line="703">Begins an interactive move operation. You might use this function to implement draggable titlebars. - + @@ -29596,7 +33489,7 @@ You might use this function to implement draggable titlebars. line="660">Begins an interactive resize operation. You might use this function to implement a “window resize grip.” - + @@ -29657,7 +33550,7 @@ You might use this function to implement a “window resize grip.” In most cases, [gtk_window_present_with_time()](../gtk4/method.Window.present_with_time.html) should be used on a [GtkWindow](../gtk4/class.Window.html), rather than calling this function. - + @@ -29679,12 +33572,11 @@ calling this function. - Gets the bitwise or of the currently active surface state flags, from the `GdkToplevelState` enumeration. - + - + @@ -29754,7 +33646,7 @@ by listening to the [property@Gdk.Toplevel:shortcuts-inhibited] property. line="355">Asks to lower the @toplevel below other windows. The windowing system may choose to ignore the request. - + line="337">Asks to minimize the @toplevel. The windowing system may choose to ignore the request. - + - + @@ -29833,7 +33725,7 @@ guaranteed to be respected. inhibited. This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts]. - + @@ -29849,7 +33741,6 @@ This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts]. - Sets the toplevel to be decorated. @@ -29857,7 +33748,7 @@ This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts]. Setting @decorated to %FALSE hints the desktop environment that the surface has its own, client-side decorations and does not need to have window decorations added. - + @@ -29879,14 +33770,13 @@ does not need to have window decorations added. - Sets the toplevel to be deletable. Setting @deletable to %TRUE hints the desktop environment that it should offer the user a way to close the surface. - + @@ -29908,7 +33798,6 @@ that it should offer the user a way to close the surface. - Sets a list of icons for the surface. @@ -29920,7 +33809,7 @@ can scale the icon but setting several size icons can give better image quality. Note that some platforms don't support surface icons. - + @@ -29945,7 +33834,6 @@ Note that some platforms don't support surface icons. - Sets the toplevel to be modal. @@ -29957,7 +33845,7 @@ to handle modal surfaces in a special way. You should only use this on surfaces for which you have previously called [method@Gdk.Toplevel.set_transient_for]. - + @@ -29979,7 +33867,6 @@ previously called [method@Gdk.Toplevel.set_transient_for]. - Sets the startup notification ID. @@ -29987,7 +33874,7 @@ previously called [method@Gdk.Toplevel.set_transient_for]. When using GTK, typically you should use [gtk_window_set_startup_id()](../gtk4/method.Window.set_startup_id.html) instead of this low-level function. - + @@ -30009,14 +33896,13 @@ instead of this low-level function. - Sets the title of a toplevel surface. The title maybe be displayed in the titlebar, in lists of windows, etc. - + @@ -30038,7 +33924,6 @@ in lists of windows, etc. - Sets a transient-for parent. @@ -30050,7 +33935,7 @@ on @parent and keep @surface above @parent. See [gtk_window_set_transient_for()](../gtk4/method.Window.set_transient_for.html) if you’re using [GtkWindow](../gtk4/class.Window.html). - + @@ -30079,7 +33964,7 @@ The window menu is the menu shown when right-clicking the titlebar on traditional windows managed by the window manager. This is useful for windows using client-side decorations, activating it with a right-click on the window decorations. - + filename="gdk/gdktoplevel.c" line="588">Returns whether the desktop environment supports tiled window states. - + - + Performs a title bar gesture. + + whether the gesture was performed @@ -30150,8 +34041,6 @@ tiled window states. transfer-ownership="none" setter="set_decorated" default-value="FALSE"> - Whether the window manager should add decorations. @@ -30162,8 +34051,6 @@ tiled window states. transfer-ownership="none" setter="set_deletable" default-value="FALSE"> - Whether the window manager should allow to close the surface. @@ -30182,8 +34069,6 @@ tiled window states. writable="1" transfer-ownership="none" setter="set_icon_list"> - A list of textures to use as icon. @@ -30194,7 +34079,6 @@ tiled window states. transfer-ownership="none" setter="set_modal" default-value="FALSE"> - Whether the surface is modal. @@ -30213,8 +34097,6 @@ tiled window states. transfer-ownership="none" setter="set_startup_id" default-value="NULL"> - The startup ID of the surface. @@ -30227,7 +34109,6 @@ startup feedback. transfer-ownership="none" getter="get_state" default-value="0"> - The state of the toplevel. @@ -30238,7 +34119,6 @@ startup feedback. transfer-ownership="none" setter="set_title" default-value="NULL"> - The title of the surface. @@ -30248,8 +34128,6 @@ startup feedback. writable="1" transfer-ownership="none" setter="set_transient_for"> - The transient parent of the surface. @@ -30289,7 +34167,7 @@ will result in an arbitrary size being used as a result. disguised="1" opaque="1" glib:is-gtype-struct-for="Toplevel"> - + c:symbol-prefix="toplevel_layout"> The `GdkToplevelLayout` struct contains information that -is necessary to present a sovereign window on screen. + line="25">Contains information that is necessary to present a sovereign +window on screen. The `GdkToplevelLayout` struct is necessary for using [method@Gdk.Toplevel.present]. @@ -30607,16 +34485,18 @@ to resize the surface after it has been presented. + opaque="1" + glib:type-name="GdkToplevelSize" + glib:get-type="gdk_toplevel_size_get_type" + c:symbol-prefix="toplevel_size"> The `GdkToplevelSize` struct contains information that is useful -to compute the size of a toplevel. + line="23">Contains information that is useful to compute the size of a toplevel. Retrieves the bounds the toplevel is placed within. + line="51">Retrieves the bounds the toplevel is placed within. The bounds represent the largest size a toplevel may have while still being able to fit within some type of boundary. Depending on the backend, this may @@ -30631,7 +34511,7 @@ toplevel can be presented. a `GdkToplevelSize` + line="53">a `GdkToplevelSize` transfer-ownership="full"> return location for width + line="54">return location for width transfer-ownership="full"> return location for height + line="55">return location for height @@ -30658,7 +34538,7 @@ toplevel can be presented. c:identifier="gdk_toplevel_size_set_min_size"> Sets the minimum size of the toplevel. + line="106">Sets the minimum size of the toplevel. The minimum size corresponds to the limitations the toplevel can be shrunk to, without resulting in incorrect painting. A user of a `GdkToplevel` should @@ -30675,19 +34555,19 @@ The minimum size should be within the bounds (see a `GdkToplevelSize` + line="108">a `GdkToplevelSize` the minimum width + line="109">the minimum width the minimum height + line="110">the minimum height @@ -30696,11 +34576,14 @@ The minimum size should be within the bounds (see c:identifier="gdk_toplevel_size_set_shadow_width"> Sets the shadows size of the toplevel. + line="131">Sets the shadows size of the toplevel. The shadow width corresponds to the part of the computed surface size that would consist of the shadow margin surrounding the window, would -there be any. +there be any. + +Shadow width should only be set if +[method@Gtk.Display.supports_shadow_width] is %TRUE. @@ -30709,31 +34592,31 @@ there be any. a `GdkToplevelSize` + line="133">a `GdkToplevelSize` width of the left part of the shadow + line="134">width of the left part of the shadow width of the right part of the shadow + line="135">width of the right part of the shadow height of the top part of the shadow + line="136">height of the top part of the shadow height of the bottom part of the shadow + line="137">height of the bottom part of the shadow @@ -30741,7 +34624,7 @@ there be any. Sets the size the toplevel prefers to be resized to. + line="84">Sets the size the toplevel prefers to be resized to. The size should be within the bounds (see [method@Gdk.ToplevelSize.get_bounds]). The set size should @@ -30755,19 +34638,19 @@ respected by the windowing system, or backend. a `GdkToplevelSize` + line="86">a `GdkToplevelSize` the width + line="87">the width the height + line="88">the height @@ -30933,11 +34816,12 @@ being set. the surface is not visible to the user + line="98">The surface is not visible to the user. glib:fundamental="1"> An event related to a touch-based device. + line="1989">An event related to a touch-based device. Extracts whether a touch event is emulating a pointer event. - + line="2100">Extracts whether a touch event is emulating a pointer event. + %TRUE if @event is emulating + line="2106">%TRUE if @event is emulating a touch event + line="2102">a touch event @@ -30981,7 +34865,7 @@ being set. glib:fundamental="1"> An event related to a gesture on a touchpad device. + line="2612">An event related to a gesture on a touchpad device. Unlike touchscreens, where the windowing system sends basic sequences of begin, update, end events, and leaves gesture @@ -30990,8 +34874,8 @@ processed by the system, resulting in these events. Extracts delta information from a touchpad event. - + line="2806">Extracts delta information from a touchpad event. + @@ -30999,7 +34883,7 @@ processed by the system, resulting in these events. a touchpad event + line="2808">a touchpad event transfer-ownership="full"> return location for x + line="2809">return location for x transfer-ownership="full"> return location for y + line="2810">return location for y @@ -31026,19 +34910,19 @@ processed by the system, resulting in these events. c:identifier="gdk_touchpad_event_get_gesture_phase"> Extracts the touchpad gesture phase from a touchpad event. - + line="2764">Extracts the touchpad gesture phase from a touchpad event. + the gesture phase of @event + line="2770">the gesture phase of @event a touchpad event + line="2766">a touchpad event @@ -31047,19 +34931,19 @@ processed by the system, resulting in these events. c:identifier="gdk_touchpad_event_get_n_fingers"> Extracts the number of fingers from a touchpad event. - + line="2785">Extracts the number of fingers from a touchpad event. + the number of fingers for @event + line="2791">the number of fingers for @event a touchpad event + line="2787">a touchpad event @@ -31068,19 +34952,19 @@ processed by the system, resulting in these events. c:identifier="gdk_touchpad_event_get_pinch_angle_delta"> Extracts the angle delta from a touchpad pinch event. - + line="2829">Extracts the angle delta from a touchpad pinch event. + the angle delta of @event + line="2835">the angle delta of @event a touchpad pinch event + line="2831">a touchpad pinch event @@ -31089,19 +34973,19 @@ processed by the system, resulting in these events. c:identifier="gdk_touchpad_event_get_pinch_scale"> Extracts the scale from a touchpad pinch event. - + line="2848">Extracts the scale from a touchpad pinch event. + the scale of @event + line="2854">the scale of @event a touchpad pinch event + line="2850">a touchpad pinch event @@ -31113,7 +34997,7 @@ processed by the system, resulting in these events. c:type="GdkTouchpadGesturePhase"> Specifies the current state of a touchpad gesture. + line="214">Specifies the current state of a touchpad gesture. All gestures are guaranteed to begin with an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN, followed by 0 or several events @@ -31138,7 +35022,7 @@ progress of the gesture. glib:name="GDK_TOUCHPAD_GESTURE_PHASE_BEGIN"> The gesture has begun. + line="216">The gesture has begun. glib:name="GDK_TOUCHPAD_GESTURE_PHASE_UPDATE"> The gesture has been updated. + line="217">The gesture has been updated. glib:name="GDK_TOUCHPAD_GESTURE_PHASE_END"> The gesture was finished, changes + line="218">The gesture was finished, changes should be permanently applied. glib:name="GDK_TOUCHPAD_GESTURE_PHASE_CANCEL"> The gesture was cancelled, all + line="220">The gesture was cancelled, all changes should be undone. - + @@ -31182,14 +35066,15 @@ progress of the gesture. `GdkVulkanContext` is an object representing the platform-specific -Vulkan draw context. + line="48">Represents the platform-specific Vulkan draw context. `GdkVulkanContext`s are created for a surface using [method@Gdk.Surface.create_vulkan_context], and the context will match @@ -31197,11 +35082,13 @@ the characteristics of the surface. Support for `GdkVulkanContext` is platform-specific and context creation can fail, returning %NULL context. + GTK does not expose any Vulkan internals. This + struct is a leftover that was accidentally exposed. Emitted when the images managed by this context have changed. + line="894">Emitted when the images managed by this context have changed. Usually this means that the swapchain had to be recreated, for example in response to a change of the surface size. @@ -31217,7 +35104,7 @@ for example in response to a change of the surface size. glib:error-domain="gdk-vulkan-error-quark"> Error enumeration for `GdkVulkanContext`. + line="190">Error enumeration for `GdkVulkanContext`. glib:name="GDK_VULKAN_ERROR_UNSUPPORTED"> Vulkan is not supported on this backend or has not been + line="192">Vulkan is not supported on this backend or has not been compiled in. glib:name="GDK_VULKAN_ERROR_NOT_AVAILABLE"> Vulkan support is not available on this Surface + line="194">Vulkan support is not available on this Surface + Registers an error quark for [class@Gdk.VulkanContext] errors. + the error quark @@ -31249,7 +35142,7 @@ for example in response to a change of the surface size. deprecated-version="4.6"> The main way to not draw GL content in GTK. + line="33">Draws GL content onto a cairo context. It takes a render buffer ID (@source_type == GL_RENDERBUFFER) or a texture id (@source_type == GL_TEXTURE) and draws it onto @cr with an OVER operation, @@ -31467,17 +35360,140 @@ so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y. + + Returns the color state object representing the oklab color space. + +This is a perceptually uniform color state. + + + the color state object for oklab + + + + + Returns the color state object representing the oklch color space. + +This is the polar variant of oklab, in which the hue is encoded as +a polar coordinate. + + + the color state object for oklch + + + + + Returns the color state object representing the linear rec2100 color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear +transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear) +for details about this colorstate. + + + the color state object for linearized rec2100 + + + + + Returns the color state object representing the rec2100-pq color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer +function defined by SMPTE ST 2084 and BT.2100-2. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq) +for details about this colorstate. + + + the color state object for rec2100-pq + + + + + Returns the color state object representing the sRGB color space. + +This color state uses the primaries defined by BT.709-6 and the transfer function +defined by IEC 61966-2-1. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB) +for details about this colorstate. + + + the color state object for sRGB + + + + + Returns the color state object representing the linearized sRGB color space. + +This color state uses the primaries defined by BT.709-6 and a linear transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear) +for details about this colorstate. + + + the color state object for linearized sRGB + + + Read content from the given input stream and deserialize it, asynchronously. - -The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers -indicate a higher priority. + line="534">Reads content from the given input stream and deserialize it, asynchronously. -When the operation is finished, @callback will be called. You must then -call [func@Gdk.content_deserialize_finish] to get the result of the operation. +The default I/O priority is `G_PRIORITY_DEFAULT` (i.e. 0), and lower numbers +indicate a higher priority. @@ -31486,25 +35502,25 @@ call [func@Gdk.content_deserialize_finish] to get the result of the operation. a `GInputStream` to read the serialized content from + line="536">a `GInputStream` to read the serialized content from the mime type to deserialize from + line="537">the mime type to deserialize from the GType to deserialize from + line="538">the GType to deserialize from the I/O priority of the operation + line="539">the I/O priority of the operation optional `GCancellable` object + line="540">optional `GCancellable` object callback to call when the operation is done + line="541">callback to call when the operation is done data to pass to the callback function + line="542">data to pass to the callback function @@ -31543,12 +35559,12 @@ call [func@Gdk.content_deserialize_finish] to get the result of the operation. Finishes a content deserialization operation. + line="579">Finishes a content deserialization operation. %TRUE if the operation was successful. In this case, + line="587">%TRUE if the operation was successful. In this case, @value is set. %FALSE if an error occurred. In this case, @error is set @@ -31557,7 +35573,7 @@ call [func@Gdk.content_deserialize_finish] to get the result of the operation. the `GAsyncResult` + line="581">the `GAsyncResult` return location for the result of the operation + line="582">return location for the result of the operation @@ -31577,7 +35593,7 @@ call [func@Gdk.content_deserialize_finish] to get the result of the operation. Parses the given @string into `GdkContentFormats` and + line="187">Parses the given @string into `GdkContentFormats` and returns the formats. Strings printed via [method@Gdk.ContentFormats.to_string] @@ -31589,14 +35605,14 @@ is returned. the content formats if @string is valid + line="200">the content formats if @string is valid the string to parse + line="189">the string to parse @@ -31605,7 +35621,7 @@ is returned. c:identifier="gdk_content_register_deserializer"> Registers a function to deserialize object of a given type. + line="390">Registers a function to deserialize object of a given type. @@ -31614,13 +35630,13 @@ is returned. the mime type which the function can deserialize from + line="392">the mime type which the function can deserialize from the type of objects that the function creates + line="393">the type of objects that the function creates destroy="4"> the callback + line="394">the callback @@ -31640,13 +35656,13 @@ is returned. allow-none="1"> data that @deserialize can access + line="395">data that @deserialize can access destroy notify for @data + line="396">destroy notify for @data @@ -31655,7 +35671,7 @@ is returned. c:identifier="gdk_content_register_serializer"> Registers a function to serialize objects of a given type. + line="396">Registers a function to serialize objects of a given type. @@ -31664,13 +35680,13 @@ is returned. the type of objects that the function can serialize + line="398">the type of objects that the function can serialize the mime type to serialize to + line="399">the mime type to serialize to destroy="4"> the callback + line="400">the callback allow-none="1"> data that @serialize can access + line="401">data that @serialize can access destroy notify for @data + line="402">destroy notify for @data @@ -31704,13 +35720,10 @@ is returned. c:identifier="gdk_content_serialize_async"> Serialize content and write it to the given output stream, asynchronously. + line="534">Serialize content and write it to the given output stream, asynchronously. The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers -indicate a higher priority. - -When the operation is finished, @callback will be called. You must then -call [func@Gdk.content_serialize_finish] to get the result of the operation. +indicate a higher priority. @@ -31719,25 +35732,25 @@ call [func@Gdk.content_serialize_finish] to get the result of the operation. a `GOutputStream` to write the serialized content to + line="536">a `GOutputStream` to write the serialized content to the mime type to serialize to + line="537">the mime type to serialize to the content to serialize + line="538">the content to serialize the I/O priority of the operation + line="539">the I/O priority of the operation optional `GCancellable` object + line="540">optional `GCancellable` object callback to call when the operation is done + line="541">callback to call when the operation is done data to pass to the callback function + line="542">data to pass to the callback function @@ -31776,12 +35789,12 @@ call [func@Gdk.content_serialize_finish] to get the result of the operation. Finishes a content serialization operation. + line="577">Finishes a content serialization operation. %TRUE if the operation was successful, %FALSE if an + line="584">%TRUE if the operation was successful, %FALSE if an error occurred. In this case, @error is set @@ -31789,17 +35802,30 @@ call [func@Gdk.content_serialize_finish] to get the result of the operation. the `GAsyncResult` + line="579">the `GAsyncResult` + + Registers an error quark for [class@Gdk.DmabufTexture] errors. + + the error quark + + + Checks if @action represents a single action or includes + line="807">Checks if @action represents a single action or includes multiple actions. When @action is 0 - ie no action was given, %TRUE @@ -31808,29 +35834,22 @@ is returned. %TRUE if exactly one action was given + line="817">%TRUE if exactly one action was given a `GdkDragAction` + line="809">a `GdkDragAction` - - - - - - Returns the relative angle from @event1 to @event2. + line="1069">Returns the relative angle from @event1 to @event2. The relative angle is the angle between the X axis and the line through both events' positions. The rotation direction for positive @@ -31838,24 +35857,24 @@ angles is from the positive X axis towards the positive Y axis. This assumes that both events have X/Y information. If not, this function returns %FALSE. - + %TRUE if the angle could be calculated. + line="1084">%TRUE if the angle could be calculated. first `GdkEvent` + line="1071">first `GdkEvent` second `GdkEvent` + line="1072">second `GdkEvent` transfer-ownership="full"> return location for the relative angle between both events + line="1073">return location for the relative angle between both events @@ -31872,28 +35891,28 @@ If not, this function returns %FALSE. Returns the point halfway between the events' positions. + line="1115">Returns the point halfway between the events' positions. This assumes that both events have X/Y information. If not, this function returns %FALSE. - + %TRUE if the center could be calculated. + line="1127">%TRUE if the center could be calculated. first `GdkEvent` + line="1117">first `GdkEvent` second `GdkEvent` + line="1118">second `GdkEvent` transfer-ownership="full"> return location for the X coordinate of the center + line="1119">return location for the X coordinate of the center transfer-ownership="full"> return location for the Y coordinate of the center + line="1120">return location for the Y coordinate of the center @@ -31920,28 +35939,28 @@ If not, this function returns %FALSE. c:identifier="gdk_events_get_distance"> Returns the distance between the event locations. + line="1046">Returns the distance between the event locations. This assumes that both events have X/Y information. If not, this function returns %FALSE. - + %TRUE if the distance could be calculated. + line="1057">%TRUE if the distance could be calculated. first `GdkEvent` + line="1048">first `GdkEvent` second `GdkEvent` + line="1049">second `GdkEvent` transfer-ownership="full"> return location for the distance + line="1050">return location for the distance @@ -31958,14 +35977,20 @@ If not, this function returns %FALSE. + Registers an error quark for [class@Gdk.GLContext] errors. + the error quark Canonicalizes the given mime type and interns the result. + line="83">Canonicalizes the given mime type and interns the result. If @string is not a valid mime type, %NULL is returned instead. See RFC 2048 for the syntax if mime types. @@ -31973,7 +35998,7 @@ See RFC 2048 for the syntax if mime types. An interned string for the canonicalized + line="92">An interned string for the canonicalized mime type or %NULL if the string wasn't a valid mime type @@ -31981,7 +36006,7 @@ See RFC 2048 for the syntax if mime types. string of a potential mime type + line="85">string of a potential mime type @@ -31990,7 +36015,7 @@ See RFC 2048 for the syntax if mime types. c:identifier="gdk_keyval_convert_case"> Obtains the upper- and lower-case versions of the keyval @symbol. + line="775">Obtains the upper- and lower-case versions of the keyval @symbol. Examples of keyvals are `GDK_KEY_a`, `GDK_KEY_Enter`, `GDK_KEY_F1`, etc. @@ -32001,7 +36026,7 @@ Examples of keyvals are `GDK_KEY_a`, `GDK_KEY_Enter`, `GDK_KEY_F1`, etc. a keyval + line="777">a keyval transfer-ownership="full"> return location for lowercase version of @symbol + line="778">return location for lowercase version of @symbol transfer-ownership="full"> return location for uppercase version of @symbol + line="779">return location for uppercase version of @symbol @@ -32027,7 +36052,7 @@ Examples of keyvals are `GDK_KEY_a`, `GDK_KEY_Enter`, `GDK_KEY_F1`, etc. Converts a key name to a key value. + line="756">Converts a key name to a key value. The names are the same as those in the `gdk/gdkkeysyms.h` header file @@ -32036,7 +36061,7 @@ but without the leading “GDK_KEY_”. the corresponding key value, or %GDK_KEY_VoidSymbol + line="766">the corresponding key value, or `GDK_KEY_VoidSymbol` if the key name is not a valid key @@ -32044,7 +36069,7 @@ but without the leading “GDK_KEY_”. a key name + line="758">a key name @@ -32052,12 +36077,12 @@ but without the leading “GDK_KEY_”. Returns %TRUE if the given key value is in lower case. + line="270">Returns true if the given key value is in lower case. %TRUE if @keyval is in lower case, or if @keyval is not + line="276">true if @keyval is in lower case, or if @keyval is not subject to case conversion. @@ -32073,12 +36098,12 @@ but without the leading “GDK_KEY_”. Returns %TRUE if the given key value is in upper case. + line="248">Returns true if the given key value is in upper case. %TRUE if @keyval is in upper case, or if @keyval is not subject to + line="254">true if @keyval is in upper case, or if @keyval is not subject to case conversion. @@ -32094,7 +36119,7 @@ but without the leading “GDK_KEY_”. Converts a key value into a symbolic name. + line="737">Converts a key value into a symbolic name. The names are the same as those in the `gdk/gdkkeysyms.h` header file @@ -32103,7 +36128,7 @@ but without the leading “GDK_KEY_”. a string containing the name + line="747">a string containing the name of the key @@ -32111,7 +36136,7 @@ but without the leading “GDK_KEY_”. a key value + line="739">a key value @@ -32140,12 +36165,12 @@ but without the leading “GDK_KEY_”. Convert from a GDK key symbol to the corresponding Unicode + line="874">Converts from a GDK key symbol to the corresponding Unicode character. Note that the conversion does not take the current locale into consideration, which might be expected for particular -keyvals, such as %GDK_KEY_KP_Decimal. +keyvals, such as `GDK_KEY_KP_Decimal`. moved-to="Paintable.new_empty"> Returns a paintable that has the given intrinsic size and draws nothing. + line="673">Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the [vfunc@Gdk.Paintable.get_current_image] virtual function @@ -32200,20 +36225,20 @@ the first frame). a `GdkPaintable` + line="686">a `GdkPaintable` The intrinsic width to report. Can be 0 for no width. + line="675">The intrinsic width to report. Can be 0 for no width. The intrinsic height to report. Can be 0 for no height. + line="676">The intrinsic height to report. Can be 0 for no height. @@ -32425,7 +36450,7 @@ to draw it on screen. c:identifier="gdk_set_allowed_backends"> Sets a list of backends that GDK should try to use. + line="212">Sets a list of backends that GDK should try to use. This can be useful if your application does not work with certain GDK backends. @@ -32466,7 +36491,7 @@ in order to take effect. a comma-separated list of backends + line="214">a comma-separated list of backends @@ -32474,27 +36499,26 @@ in order to take effect. + Registers an error quark for [class@Gdk.Texture] errors. + the error quark - - - - - - Convert from a Unicode character to a key symbol. + line="1698">Converts from a Unicode character to a key symbol. the corresponding GDK key symbol, if one exists. - or, if there is no corresponding symbol, wc | 0x01000000 + line="1704">the corresponding GDK key symbol, if one exists, + or, if there is no corresponding symbol, `wc | 0x01000000` @@ -32509,7 +36533,13 @@ in order to take effect. + Registers an error quark for [class@Gdk.VulkanContext] errors. + the error quark diff --git a/generator/src/main/resources/gir/GdkPixbuf-2.0.gir b/generator/src/main/resources/gir/GdkPixbuf-2.0.gir index 202e79c..4341ecd 100644 --- a/generator/src/main/resources/gir/GdkPixbuf-2.0.gir +++ b/generator/src/main/resources/gir/GdkPixbuf-2.0.gir @@ -504,7 +504,7 @@ interpolation is just as fast and results in higher quality. - + Micro version of gdk-pixbuf library, that is the "2" in @@ -551,7 +551,7 @@ interpolation is just as fast and results in higher quality. This data is commonly the result of including an XPM file into a program's C source. - + A newly-created pixbuf @@ -1427,7 +1427,8 @@ image values without needing to create a `GdkPixbuf`. + version="2.4" + glib:async-func="get_file_info_async"> Parses an image file far enough to determine its format and size. @@ -1472,7 +1473,9 @@ image values without needing to create a `GdkPixbuf`. + version="2.32" + glib:finish-func="get_file_info_finish" + glib:sync-func="get_file_info"> Asynchronously parses an image file far enough to determine its @@ -1621,7 +1624,8 @@ provided modules. + version="2.24" + glib:finish-func="new_from_stream_finish"> Creates a new pixbuf by asynchronously loading an image from an input stream. @@ -1787,7 +1791,7 @@ pixels will become fully transparent. If `substitute_color` is `FALSE`, then the (`r`, `g`, `b`) arguments will be ignored. - + A newly-created pixbuf @@ -4176,7 +4180,8 @@ The stream is not closed. + version="2.28" + glib:finish-func="new_from_stream_finish"> Creates a new animation by asynchronously loading an image from an input stream. @@ -4294,6 +4299,9 @@ A delay time of -1 is possible, indicating "infinite". + fills @width and @height with the frame size of the animation. @@ -4602,6 +4610,9 @@ virtual functions. + returns whether the given animation is just a static image. @@ -4622,6 +4633,9 @@ virtual functions. + returns a static image representing the given animation. @@ -4642,6 +4656,9 @@ virtual functions. + fills @width and @height with the frame size of the animation. @@ -4662,6 +4679,9 @@ virtual functions. + returns an iterator for the given animation. @@ -5009,6 +5029,10 @@ virtual functions. + returns the time in milliseconds that the current frame + should be shown. @@ -5030,6 +5054,9 @@ virtual functions. + returns the current frame. @@ -5051,6 +5078,10 @@ virtual functions. + returns whether the current frame of @iter is + being loaded. @@ -5072,6 +5103,10 @@ virtual functions. + advances the iterator to @current_time, possibly changing the + current frame. @@ -5298,7 +5333,7 @@ use the `gdk_pixbuf_format_*` family of functions. filename="gdk-pixbuf/gdk-pixbuf-io.c" line="3452">Creates a copy of `format`. - + the newly allocated copy of a `GdkPixbufFormat`. Use @@ -5339,7 +5374,7 @@ using gdk_pixbuf_format_copy() filename="gdk-pixbuf/gdk-pixbuf-io.c" line="3249">Returns a description of the format. - + a description of the format. @@ -5362,7 +5397,7 @@ using gdk_pixbuf_format_copy() line="3293">Returns the filename extensions typically used for files in the given format. - + an array of @@ -5390,7 +5425,7 @@ given format. The returned string should be a shorthand for a well known license, e.g. "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. - + a string describing the license of the pixbuf format @@ -5412,7 +5447,7 @@ The returned string should be a shorthand for a well known license, e.g. filename="gdk-pixbuf/gdk-pixbuf-io.c" line="3275">Returns the mime types supported by the format. - + an array of mime types @@ -5436,7 +5471,7 @@ The returned string should be a shorthand for a well known license, e.g. filename="gdk-pixbuf/gdk-pixbuf-io.c" line="3231">Returns the name of the format. - + the name of the format. diff --git a/generator/src/main/resources/gir/Geoclue-2.0.gir b/generator/src/main/resources/gir/Geoclue-2.0.gir index d11319e..b7f0123 100644 --- a/generator/src/main/resources/gir/Geoclue-2.0.gir +++ b/generator/src/main/resources/gir/Geoclue-2.0.gir @@ -328,6 +328,9 @@ Since this D-Bus property is both readable and writable, it is meaningful to use + Handler for the #GClueClient::handle-start signal. @@ -343,6 +346,9 @@ Since this D-Bus property is both readable and writable, it is meaningful to use + Handler for the #GClueClient::handle-stop signal. @@ -358,6 +364,9 @@ Since this D-Bus property is both readable and writable, it is meaningful to use + Handler for the #GClueClient::location-updated signal. @@ -374,7 +383,10 @@ Since this D-Bus property is both readable and writable, it is meaningful to use - + Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Client.Start">Start()</link> D-Bus method on @proxy. @@ -454,7 +466,8 @@ See gclue_client_call_start_sync() for the synchronous, blocking version of this + throws="1" + glib:async-func="call_start"> Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Client.Start">Start()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. @@ -485,7 +498,10 @@ See gclue_client_call_start() for the asynchronous version of this method. - + Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Client.Stop">Stop()</link> D-Bus method on @proxy. @@ -565,7 +581,8 @@ See gclue_client_call_stop_sync() for the synchronous, blocking version of this + throws="1" + glib:async-func="call_stop"> Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Client.Stop">Stop()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. @@ -1207,6 +1224,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Handler for the #GClueClient::handle-start signal. @@ -1224,6 +1244,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Handler for the #GClueClient::handle-stop signal. @@ -1241,6 +1264,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Getter for the #GClueClient:active property. @@ -1260,6 +1286,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Getter for the #GClueClient:desktop-id property. @@ -1279,6 +1308,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Getter for the #GClueClient:distance-threshold property. @@ -1298,6 +1330,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Getter for the #GClueClient:location property. @@ -1317,6 +1352,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Getter for the #GClueClient:requested-accuracy-level property. @@ -1336,6 +1374,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Getter for the #GClueClient:time-threshold property. @@ -1355,6 +1396,9 @@ On the service-side, this signal can be used with e.g. g_signal_emit_by_name() t + Handler for the #GClueClient::location-updated signal. @@ -1542,7 +1586,10 @@ See gclue_client_proxy_new() for the asynchronous version of this constructor. - + A utility function to create a #GClueClientProxy without having to deal with @@ -1627,7 +1674,9 @@ object or %NULL if @error is set. + c:identifier="gclue_client_proxy_create_full" + glib:finish-func="create_full_finish" + glib:sync-func="create_full_sync"> A utility function to create a #GClueClientProxy without having to deal with @@ -1721,7 +1770,8 @@ object or %NULL if @error is set. + throws="1" + glib:async-func="create_full"> The synchronous and blocking version of #gclue_client_proxy_create_full(). @@ -1771,7 +1821,8 @@ object or %NULL if @error is set. + throws="1" + glib:async-func="create"> The synchronous and blocking version of #gclue_client_proxy_create(). @@ -1812,7 +1863,9 @@ object or %NULL if @error is set. - + Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-GeoClue2-Client.top_of_page">org.freedesktop.GeoClue2.Client</link>. See g_dbus_proxy_new() for more details. @@ -1885,7 +1938,8 @@ See gclue_client_proxy_new_sync() for the synchronous, blocking version of this + c:identifier="gclue_client_proxy_new_for_bus" + glib:finish-func="new_for_bus_finish"> Like gclue_client_proxy_new() but takes a #GBusType instead of a #GDBusConnection. @@ -3132,6 +3186,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:accuracy property. @@ -3151,6 +3208,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:altitude property. @@ -3170,6 +3230,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:description property. @@ -3189,6 +3252,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:heading property. @@ -3208,6 +3274,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:latitude property. @@ -3227,6 +3296,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:longitude property. @@ -3246,6 +3318,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:speed property. @@ -3265,6 +3340,9 @@ Since the D-Bus property for this #GObject property is readable but not writable + Getter for the #GClueLocation:timestamp property. @@ -3452,7 +3530,9 @@ See gclue_location_proxy_new() for the asynchronous version of this constructor. - + Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-GeoClue2-Location.top_of_page">org.freedesktop.GeoClue2.Location</link>. See g_dbus_proxy_new() for more details. @@ -3525,7 +3605,8 @@ See gclue_location_proxy_new_sync() for the synchronous, blocking version of thi + c:identifier="gclue_location_proxy_new_for_bus" + glib:finish-func="new_for_bus_finish"> Like gclue_location_proxy_new() but takes a #GBusType instead of a #GDBusConnection. @@ -3848,6 +3929,9 @@ Since this D-Bus property is readable, it is meaningful to use this function on + Handler for the #GClueManager::handle-add-agent signal. @@ -3866,6 +3950,9 @@ Since this D-Bus property is readable, it is meaningful to use this function on + Handler for the #GClueManager::handle-create-client signal. @@ -3881,6 +3968,9 @@ Since this D-Bus property is readable, it is meaningful to use this function on + Handler for the #GClueManager::handle-delete-client signal. @@ -3899,6 +3989,9 @@ Since this D-Bus property is readable, it is meaningful to use this function on + Handler for the #GClueManager::handle-get-client signal. @@ -3914,7 +4007,9 @@ Since this D-Bus property is readable, it is meaningful to use this function on + c:identifier="gclue_manager_call_add_agent" + glib:finish-func="call_add_agent_finish" + glib:sync-func="call_add_agent_sync"> Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.AddAgent">AddAgent()</link> D-Bus method on @proxy. @@ -4000,7 +4095,8 @@ See gclue_manager_call_add_agent_sync() for the synchronous, blocking version of + throws="1" + glib:async-func="call_add_agent"> Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.AddAgent">AddAgent()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. @@ -4038,7 +4134,9 @@ See gclue_manager_call_add_agent() for the asynchronous version of this method.< + c:identifier="gclue_manager_call_create_client" + glib:finish-func="call_create_client_finish" + glib:sync-func="call_create_client_sync"> Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.CreateClient">CreateClient()</link> D-Bus method on @proxy. @@ -4129,7 +4227,8 @@ See gclue_manager_call_create_client_sync() for the synchronous, blocking versio + throws="1" + glib:async-func="call_create_client"> Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.CreateClient">CreateClient()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. @@ -4172,7 +4271,9 @@ See gclue_manager_call_create_client() for the asynchronous version of this meth + c:identifier="gclue_manager_call_delete_client" + glib:finish-func="call_delete_client_finish" + glib:sync-func="call_delete_client_sync"> Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.DeleteClient">DeleteClient()</link> D-Bus method on @proxy. @@ -4258,7 +4359,8 @@ See gclue_manager_call_delete_client_sync() for the synchronous, blocking versio + throws="1" + glib:async-func="call_delete_client"> Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.DeleteClient">DeleteClient()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. @@ -4296,7 +4398,9 @@ See gclue_manager_call_delete_client() for the asynchronous version of this meth + c:identifier="gclue_manager_call_get_client" + glib:finish-func="call_get_client_finish" + glib:sync-func="call_get_client_sync"> Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.GetClient">GetClient()</link> D-Bus method on @proxy. @@ -4387,7 +4491,8 @@ See gclue_manager_call_get_client_sync() for the synchronous, blocking version o + throws="1" + glib:async-func="call_get_client"> Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-GeoClue2-Manager.GetClient">GetClient()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. @@ -4792,6 +4897,9 @@ If a signal handler returns %TRUE, it means the signal handler will handle the i + Handler for the #GClueManager::handle-add-agent signal. @@ -4812,6 +4920,9 @@ If a signal handler returns %TRUE, it means the signal handler will handle the i + Handler for the #GClueManager::handle-create-client signal. @@ -4829,6 +4940,9 @@ If a signal handler returns %TRUE, it means the signal handler will handle the i + Handler for the #GClueManager::handle-delete-client signal. @@ -4849,6 +4963,9 @@ If a signal handler returns %TRUE, it means the signal handler will handle the i + Handler for the #GClueManager::handle-get-client signal. @@ -4866,6 +4983,9 @@ If a signal handler returns %TRUE, it means the signal handler will handle the i + Getter for the #GClueManager:available-accuracy-level property. @@ -4885,6 +5005,9 @@ If a signal handler returns %TRUE, it means the signal handler will handle the i + Getter for the #GClueManager:in-use property. @@ -5072,7 +5195,9 @@ See gclue_manager_proxy_new() for the asynchronous version of this constructor.< - + Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-GeoClue2-Manager.top_of_page">org.freedesktop.GeoClue2.Manager</link>. See g_dbus_proxy_new() for more details. @@ -5145,7 +5270,8 @@ See gclue_manager_proxy_new_sync() for the synchronous, blocking version of this + c:identifier="gclue_manager_proxy_new_for_bus" + glib:finish-func="new_for_bus_finish"> Like gclue_manager_proxy_new() but takes a #GBusType instead of a #GDBusConnection. @@ -5337,12 +5463,12 @@ See gclue_manager_proxy_new_for_bus_sync() for the synchronous, blocking version throws="1"> Finishes an operation started with #gclue_simple_new(). + line="777">Finishes an operation started with #gclue_simple_new(). The constructed proxy + line="785">The constructed proxy object or %NULL if @error is set. @@ -5350,7 +5476,7 @@ object or %NULL if @error is set. The #GAsyncResult obtained from the #GAsyncReadyCallback passed to + line="779">The #GAsyncResult obtained from the #GAsyncReadyCallback passed to #gclue_simple_new(). @@ -5361,12 +5487,12 @@ object or %NULL if @error is set. throws="1"> The synchronous and blocking version of #gclue_simple_new(). + line="848">The synchronous and blocking version of #gclue_simple_new(). The new #GClueSimple object or + line="857">The new #GClueSimple object or %NULL if @error is set. @@ -5374,13 +5500,13 @@ object or %NULL if @error is set. The desktop file id (the basename of the desktop file). + line="850">The desktop file id (the basename of the desktop file). The requested accuracy level as #GClueAccuracyLevel. + line="851">The requested accuracy level as #GClueAccuracyLevel. allow-none="1"> A #GCancellable or %NULL. + line="852">A #GCancellable or %NULL. @@ -5399,12 +5525,12 @@ object or %NULL if @error is set. throws="1"> Finishes an operation started with #gclue_simple_new_with_thresholds(). + line="806">Finishes an operation started with #gclue_simple_new_with_thresholds(). The constructed proxy + line="814">The constructed proxy object or %NULL if @error is set. @@ -5412,7 +5538,7 @@ object or %NULL if @error is set. The #GAsyncResult obtained from the #GAsyncReadyCallback passed to + line="808">The #GAsyncResult obtained from the #GAsyncReadyCallback passed to #gclue_simple_new_with_thresholds(). @@ -5423,12 +5549,12 @@ object or %NULL if @error is set. throws="1"> The synchronous and blocking version of #gclue_simple_new_with_thresholds(). + line="926">The synchronous and blocking version of #gclue_simple_new_with_thresholds(). The new #GClueSimple object or + line="937">The new #GClueSimple object or %NULL if @error is set. @@ -5436,25 +5562,25 @@ object or %NULL if @error is set. The desktop file id (the basename of the desktop file). + line="928">The desktop file id (the basename of the desktop file). The requested accuracy level as #GClueAccuracyLevel. + line="929">The requested accuracy level as #GClueAccuracyLevel. Time threshold in seconds, 0 for no limit. + line="930">Time threshold in seconds, 0 for no limit. Distance threshold in meters, 0 for no limit. + line="931">Distance threshold in meters, 0 for no limit. allow-none="1"> A #GCancellable or %NULL. + line="932">A #GCancellable or %NULL. - + Asynchronously creates a #GClueSimple instance. Use + line="746">Asynchronously creates a #GClueSimple instance. Use #gclue_simple_new_finish() to get the created #GClueSimple instance. See #gclue_simple_new_sync() for the synchronous, blocking version @@ -5484,13 +5612,13 @@ of this function. The desktop file id (the basename of the desktop file). + line="748">The desktop file id (the basename of the desktop file). The requested accuracy level as #GClueAccuracyLevel. + line="749">The requested accuracy level as #GClueAccuracyLevel. allow-none="1"> A #GCancellable or %NULL. + line="750">A #GCancellable or %NULL. closure="4"> A #GAsyncReadyCallback to call when the results are ready. + line="751">A #GAsyncReadyCallback to call when the results are ready. allow-none="1"> User data to pass to @callback. + line="752">User data to pass to @callback. + c:identifier="gclue_simple_new_with_thresholds" + glib:finish-func="new_with_thresholds_finish"> Asynchronously creates a #GClueSimple instance. Use + line="889">Asynchronously creates a #GClueSimple instance. Use #gclue_simple_new_with_thresholds_finish() to get the created #GClueSimple instance. See #gclue_simple_new_with_thresholds_sync() for the synchronous, @@ -5541,25 +5670,25 @@ blocking version of this function. The desktop file id (the basename of the desktop file). + line="891">The desktop file id (the basename of the desktop file). The requested accuracy level as #GClueAccuracyLevel. + line="892">The requested accuracy level as #GClueAccuracyLevel. Time threshold in seconds, 0 for no limit. + line="893">Time threshold in seconds, 0 for no limit. Distance threshold in meters, 0 for no limit. + line="894">Distance threshold in meters, 0 for no limit. allow-none="1"> A #GCancellable or %NULL. + line="895">A #GCancellable or %NULL. closure="6"> A #GAsyncReadyCallback to call when the results are ready. + line="896">A #GAsyncReadyCallback to call when the results are ready. allow-none="1"> User data to pass to @callback. + line="897">User data to pass to @callback. @@ -5598,20 +5727,20 @@ blocking version of this function. glib:get-property="client"> Gets the client proxy, or %NULL if @simple is not using a client proxy (i-e + line="974">Gets the client proxy, or %NULL if @simple is not using a client proxy (i-e when inside the Flatpak sandbox). The client object. + line="981">The client object. A #GClueSimple object. + line="976">A #GClueSimple object. @@ -5621,12 +5750,12 @@ when inside the Flatpak sandbox). glib:get-property="location"> Gets the current location. + line="991">Gets the current location. The last known location + line="997">The last known location as #GClueLocation. @@ -5634,7 +5763,7 @@ as #GClueLocation. A #GClueSimple object. + line="993">A #GClueSimple object. @@ -5647,13 +5776,13 @@ as #GClueLocation. default-value="GCLUE_ACCURACY_LEVEL_NONE"> The requested maximum accuracy level. + line="201">The requested maximum accuracy level. The client proxy. This is %NULL if @simple is not using a client proxy + line="217">The client proxy. This is %NULL if @simple is not using a client proxy (i-e when inside the Flatpak sandbox). @@ -5665,7 +5794,7 @@ as #GClueLocation. default-value="NULL"> The Desktop ID of the application. + line="186">The Desktop ID of the application. default-value="0"> The current distance threshold in meters. This value is used by the + line="246">The current distance threshold in meters. This value is used by the service when it gets new location info. If the distance moved is below the threshold, it won't emit the LocationUpdated signal. @@ -5687,7 +5816,7 @@ When set to 0 (default), it always emits the signal. getter="get_location"> The current location. + line="232">The current location. default-value="0"> The current time threshold in seconds. This value is used by the + line="265">The current time threshold in seconds. This value is used by the service when it gets new location info. If the time passed is below the threshold, it won't emit the LocationUpdated signal. diff --git a/generator/src/main/resources/gir/Gio-2.0.gir b/generator/src/main/resources/gir/Gio-2.0.gir index 87fd218..43f2945 100644 --- a/generator/src/main/resources/gir/Gio-2.0.gir +++ b/generator/src/main/resources/gir/Gio-2.0.gir @@ -5,7 +5,10 @@ and/or use gtk-doc annotations. --> + + @@ -16,13 +19,14 @@ and/or use gtk-doc annotations. --> + + c:symbol-prefixes="gio,g"> - + @@ -31,7 +35,7 @@ and/or use gtk-doc annotations. --> - + @@ -40,7 +44,7 @@ and/or use gtk-doc annotations. --> - + @@ -49,7 +53,7 @@ and/or use gtk-doc annotations. --> - + @@ -58,7 +62,7 @@ and/or use gtk-doc annotations. --> - + @@ -67,7 +71,7 @@ and/or use gtk-doc annotations. --> - + @@ -76,7 +80,7 @@ and/or use gtk-doc annotations. --> - + @@ -85,7 +89,7 @@ and/or use gtk-doc annotations. --> - + @@ -94,7 +98,7 @@ and/or use gtk-doc annotations. --> - + @@ -103,7 +107,7 @@ and/or use gtk-doc annotations. --> - + @@ -112,7 +116,7 @@ and/or use gtk-doc annotations. --> - + @@ -121,7 +125,7 @@ and/or use gtk-doc annotations. --> - + @@ -130,7 +134,7 @@ and/or use gtk-doc annotations. --> - + @@ -139,7 +143,7 @@ and/or use gtk-doc annotations. --> - + @@ -148,7 +152,7 @@ and/or use gtk-doc annotations. --> - + @@ -157,7 +161,7 @@ and/or use gtk-doc annotations. --> - + @@ -166,7 +170,7 @@ and/or use gtk-doc annotations. --> - + @@ -175,7 +179,7 @@ and/or use gtk-doc annotations. --> - + @@ -184,7 +188,7 @@ and/or use gtk-doc annotations. --> - + @@ -193,7 +197,7 @@ and/or use gtk-doc annotations. --> - + @@ -202,7 +206,7 @@ and/or use gtk-doc annotations. --> - + @@ -211,7 +215,7 @@ and/or use gtk-doc annotations. --> - + @@ -224,61 +228,61 @@ and/or use gtk-doc annotations. --> glib:get-type="g_action_get_type" glib:type-struct="ActionInterface"> #GAction represents a single named action. + filename="gio/gaction.c" + line="30">`GAction` represents a single named action. The main interface to an action is that it can be activated with -g_action_activate(). This results in the 'activate' signal being -emitted. An activation has a #GVariant parameter (which may be -%NULL). The correct type for the parameter is determined by a static +[method@Gio.Action.activate]. This results in the 'activate' signal being +emitted. An activation has a `GVariant` parameter (which may be +`NULL`). The correct type for the parameter is determined by a static parameter type (which is given at construction time). An action may optionally have a state, in which case the state may be -set with g_action_change_state(). This call takes a #GVariant. The +set with [method@Gio.Action.change_state]. This call takes a [type@GLib.Variant]. The correct type for the state is determined by a static state type (which is given at construction time). The state may have a hint associated with it, specifying its valid range. -#GAction is merely the interface to the concept of an action, as +`GAction` is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including -#GSimpleAction. +[class@Gio.SimpleAction]. In all cases, the implementing class is responsible for storing the -name of the action, the parameter type, the enabled state, the -optional state type and the state and emitting the appropriate -signals when these change. The implementor is responsible for filtering -calls to g_action_activate() and g_action_change_state() for type -safety and for the state being enabled. - -Probably the only useful thing to do with a #GAction is to put it -inside of a #GSimpleActionGroup. - +name of the action, the parameter type, the enabled state, the optional +state type and the state and emitting the appropriate signals when these +change. The implementor is responsible for filtering calls to +[method@Gio.Action.activate] and [method@Gio.Action.change_state] +for type safety and for the state being enabled. + +Probably the only useful thing to do with a `GAction` is to put it +inside of a [class@Gio.SimpleActionGroup]. + Checks if @action_name is valid. + filename="gio/gaction.c" + line="387">Checks if @action_name is valid. @action_name is valid if it consists only of alphanumeric characters, -plus '-' and '.'. The empty string is not a valid action name. +plus `-` and `.`. The empty string is not a valid action name. -It is an error to call this function with a non-utf8 @action_name. -@action_name must not be %NULL. - +It is an error to call this function with a non-UTF-8 @action_name. +@action_name must not be `NULL`. + %TRUE if @action_name is valid + filename="gio/gaction.c" + line="399">`TRUE` if @action_name is valid a potential action name + filename="gio/gaction.c" + line="389">a potential action name @@ -288,8 +292,8 @@ It is an error to call this function with a non-utf8 @action_name. version="2.38" throws="1"> Parses a detailed action name into its separate name and target + filename="gio/gaction.c" + line="418">Parses a detailed action name into its separate name and target components. Detailed action names can have three formats. @@ -307,30 +311,30 @@ separated by a double colon (`::`). For example: The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: `app.action(42)`. The -target value is parsed using g_variant_parse(). If a tuple-typed +target value is parsed using [func@GLib.Variant.parse]. If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: `app.action((1,2,3))`. A string target can be specified this way as well: `app.action('target')`. For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, `-` and `.`. -If this function returns %TRUE, a non-%NULL value is guaranteed to be returned -in @action_name (if a pointer is passed in). A %NULL value may still be +If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned +in @action_name (if a pointer is passed in). A `NULL` value may still be returned in @target_value, as the @detailed_name may not contain a target. -If returned, the #GVariant in @target_value is guaranteed to not be floating. - +If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating. + %TRUE if successful, else %FALSE with @error set + filename="gio/gaction.c" + line="457">`TRUE` if successful, else `FALSE` with @error set a detailed action name + filename="gio/gaction.c" + line="420">a detailed action name the action name + filename="gio/gaction.c" + line="421">the action name the target value, - or %NULL for no target + filename="gio/gaction.c" + line="422">the target value, + or `NULL` for no target @@ -363,29 +367,29 @@ If returned, the #GVariant in @target_value is guaranteed to not be floating. Formats a detailed action name from @action_name and @target_value. + filename="gio/gaction.c" + line="532">Formats a detailed action name from @action_name and @target_value. It is an error to call this function with an invalid action name. -This function is the opposite of g_action_parse_detailed_name(). +This function is the opposite of [func@Gio.Action.parse_detailed_name]. It will produce a string that can be parsed back to the @action_name and @target_value by that function. See that function for the types of strings that will be printed by this function. - + a detailed format string + filename="gio/gaction.c" + line="548">a detailed format string a valid action name + filename="gio/gaction.c" + line="534">a valid action name nullable="1" allow-none="1"> a #GVariant target value, or %NULL + filename="gio/gaction.c" + line="535">a [type@GLib.Variant] target value, or `NULL` Activates the action. + filename="gio/gaction.c" + line="356">Activates the action. @parameter must be the correct type of parameter for the action (ie: the parameter type given at construction time). If the parameter -type was %NULL then @parameter must also be %NULL. +type was `NULL` then @parameter must also be `NULL`. -If the @parameter GVariant is floating, it is consumed. - +If the @parameter [type@GLib.Variant] is floating, it is consumed. + a #GAction + filename="gio/gaction.c" + line="358">a [type@Gio.Action] nullable="1" allow-none="1"> the parameter to the activation + filename="gio/gaction.c" + line="359">the parameter to the activation @@ -435,75 +439,75 @@ If the @parameter GVariant is floating, it is consumed. invoker="change_state" version="2.30"> Request for the state of @action to be changed to @value. + filename="gio/gaction.c" + line="158">Request for the state of @action to be changed to @value. The action must be stateful and @value must be of the correct type. -See g_action_get_state_type(). +See [method@Gio.Action.get_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. -See g_action_get_state_hint(). +See [method@Gio.Action.get_state_hint]. -If the @value GVariant is floating, it is consumed. - +If the @value [type@GLib.Variant] is floating, it is consumed. + a #GAction + filename="gio/gaction.c" + line="160">a [type@Gio.Action] the new state + filename="gio/gaction.c" + line="161">the new state Checks if @action is currently enabled. + filename="gio/gaction.c" + line="334">Checks if @action is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. - + whether the action is enabled + filename="gio/gaction.c" + line="343">whether the action is enabled a #GAction + filename="gio/gaction.c" + line="336">a [type@Gio.Action] Queries the name of @action. - + filename="gio/gaction.c" + line="222">Queries the name of @action. + the name of the action + filename="gio/gaction.c" + line="228">the name of the action a #GAction + filename="gio/gaction.c" + line="224">a [type@Gio.Action] @@ -512,54 +516,55 @@ have its state changed from outside callers. invoker="get_parameter_type" version="2.28"> Queries the type of the parameter that must be given when activating + filename="gio/gaction.c" + line="241">Queries the type of the parameter that must be given when activating @action. -When activating the action using g_action_activate(), the #GVariant -given to that function must be of the type returned by this function. +When activating the action using [method@Gio.Action.activate], the +[type@GLib.Variant] given to that function must be of the type returned by +this function. -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. - +In the case that this function returns `NULL`, you must not give any +[type@GLib.Variant], but `NULL` instead. + the parameter type + filename="gio/gaction.c" + line="255">the parameter type a #GAction + filename="gio/gaction.c" + line="243">a [type@Gio.Action] Queries the current state of @action. + filename="gio/gaction.c" + line="196">Queries the current state of @action. -If the action is not stateful then %NULL will be returned. If the +If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type -given by g_action_get_state_type(). +given by [method@Gio.Action.get_state_type]. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the current state of the action + filename="gio/gaction.c" + line="209">the current state of the action a #GAction + filename="gio/gaction.c" + line="198">a [type@Gio.Action] @@ -568,16 +573,16 @@ g_variant_unref() when it is no longer required. invoker="get_state_hint" version="2.28"> Requests a hint about the valid range of values for the state of + filename="gio/gaction.c" + line="298">Requests a hint about the valid range of values for the state of @action. -If %NULL is returned it either means that the action is not stateful +If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is +If a [type@GLib.Variant] array is returned then each item in the array is a +possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. @@ -585,20 +590,20 @@ In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the state range hint + filename="gio/gaction.c" + line="321">the state range hint a #GAction + filename="gio/gaction.c" + line="300">a [type@Gio.Action] @@ -607,54 +612,54 @@ g_variant_unref() when it is no longer required. invoker="get_state_type" version="2.28"> Queries the type of the state of @action. + filename="gio/gaction.c" + line="268">Queries the type of the state of @action. If the action is stateful (e.g. created with -g_simple_action_new_stateful()) then this function returns the -#GVariantType of the state. This is the type of the initial value -given as the state. All calls to g_action_change_state() must give a -#GVariant of this type and g_action_get_state() will return a -#GVariant of the same type. - -If the action is not stateful (e.g. created with g_simple_action_new()) -then this function will return %NULL. In that case, g_action_get_state() -will return %NULL and you must not call g_action_change_state(). - +[ctor@Gio.SimpleAction.new_stateful]) then this function returns the +[type@GLib.VariantType] of the state. This is the type of the initial value +given as the state. All calls to [method@Gio.Action.change_state] must give a +[type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a +[type@GLib.Variant] of the same type. + +If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new]) +then this function will return `NULL`. In that case, [method@Gio.Action.get_state] +will return `NULL` and you must not call [method@Gio.Action.change_state]. + the state type, if the action is stateful + filename="gio/gaction.c" + line="285">the state type, if the action is stateful a #GAction + filename="gio/gaction.c" + line="270">a [type@Gio.Action] Activates the action. + filename="gio/gaction.c" + line="356">Activates the action. @parameter must be the correct type of parameter for the action (ie: the parameter type given at construction time). If the parameter -type was %NULL then @parameter must also be %NULL. +type was `NULL` then @parameter must also be `NULL`. -If the @parameter GVariant is floating, it is consumed. - +If the @parameter [type@GLib.Variant] is floating, it is consumed. + a #GAction + filename="gio/gaction.c" + line="358">a [type@Gio.Action] nullable="1" allow-none="1"> the parameter to the activation + filename="gio/gaction.c" + line="359">the parameter to the activation @@ -672,32 +677,32 @@ If the @parameter GVariant is floating, it is consumed. c:identifier="g_action_change_state" version="2.30"> Request for the state of @action to be changed to @value. + filename="gio/gaction.c" + line="158">Request for the state of @action to be changed to @value. The action must be stateful and @value must be of the correct type. -See g_action_get_state_type(). +See [method@Gio.Action.get_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. -See g_action_get_state_hint(). +See [method@Gio.Action.get_state_hint]. -If the @value GVariant is floating, it is consumed. - +If the @value [type@GLib.Variant] is floating, it is consumed. + a #GAction + filename="gio/gaction.c" + line="160">a [type@Gio.Action] the new state + filename="gio/gaction.c" + line="161">the new state @@ -707,23 +712,23 @@ If the @value GVariant is floating, it is consumed. glib:get-property="enabled" version="2.28"> Checks if @action is currently enabled. + filename="gio/gaction.c" + line="334">Checks if @action is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. - + whether the action is enabled + filename="gio/gaction.c" + line="343">whether the action is enabled a #GAction + filename="gio/gaction.c" + line="336">a [type@Gio.Action] @@ -733,20 +738,20 @@ have its state changed from outside callers. glib:get-property="name" version="2.28"> Queries the name of @action. - + filename="gio/gaction.c" + line="222">Queries the name of @action. + the name of the action + filename="gio/gaction.c" + line="228">the name of the action a #GAction + filename="gio/gaction.c" + line="224">a [type@Gio.Action] @@ -756,27 +761,28 @@ have its state changed from outside callers. glib:get-property="parameter-type" version="2.28"> Queries the type of the parameter that must be given when activating + filename="gio/gaction.c" + line="241">Queries the type of the parameter that must be given when activating @action. -When activating the action using g_action_activate(), the #GVariant -given to that function must be of the type returned by this function. +When activating the action using [method@Gio.Action.activate], the +[type@GLib.Variant] given to that function must be of the type returned by +this function. -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. - +In the case that this function returns `NULL`, you must not give any +[type@GLib.Variant], but `NULL` instead. + the parameter type + filename="gio/gaction.c" + line="255">the parameter type a #GAction + filename="gio/gaction.c" + line="243">a [type@Gio.Action] @@ -786,27 +792,27 @@ In the case that this function returns %NULL, you must not give any glib:get-property="state" version="2.28"> Queries the current state of @action. + filename="gio/gaction.c" + line="196">Queries the current state of @action. -If the action is not stateful then %NULL will be returned. If the +If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type -given by g_action_get_state_type(). +given by [method@Gio.Action.get_state_type]. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the current state of the action + filename="gio/gaction.c" + line="209">the current state of the action a #GAction + filename="gio/gaction.c" + line="198">a [type@Gio.Action] @@ -815,16 +821,16 @@ g_variant_unref() when it is no longer required. c:identifier="g_action_get_state_hint" version="2.28"> Requests a hint about the valid range of values for the state of + filename="gio/gaction.c" + line="298">Requests a hint about the valid range of values for the state of @action. -If %NULL is returned it either means that the action is not stateful +If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is +If a [type@GLib.Variant] array is returned then each item in the array is a +possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. @@ -832,20 +838,20 @@ In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the state range hint + filename="gio/gaction.c" + line="321">the state range hint a #GAction + filename="gio/gaction.c" + line="300">a [type@Gio.Action] @@ -855,31 +861,31 @@ g_variant_unref() when it is no longer required. glib:get-property="state-type" version="2.28"> Queries the type of the state of @action. + filename="gio/gaction.c" + line="268">Queries the type of the state of @action. If the action is stateful (e.g. created with -g_simple_action_new_stateful()) then this function returns the -#GVariantType of the state. This is the type of the initial value -given as the state. All calls to g_action_change_state() must give a -#GVariant of this type and g_action_get_state() will return a -#GVariant of the same type. - -If the action is not stateful (e.g. created with g_simple_action_new()) -then this function will return %NULL. In that case, g_action_get_state() -will return %NULL and you must not call g_action_change_state(). - +[ctor@Gio.SimpleAction.new_stateful]) then this function returns the +[type@GLib.VariantType] of the state. This is the type of the initial value +given as the state. All calls to [method@Gio.Action.change_state] must give a +[type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a +[type@GLib.Variant] of the same type. + +If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new]) +then this function will return `NULL`. In that case, [method@Gio.Action.get_state] +will return `NULL` and you must not call [method@Gio.Action.change_state]. + the state type, if the action is stateful + filename="gio/gaction.c" + line="285">the state type, if the action is stateful a #GAction + filename="gio/gaction.c" + line="270">a [type@Gio.Action] @@ -890,11 +896,11 @@ will return %NULL and you must not call g_action_change_state(). getter="get_enabled" default-value="TRUE"> If @action is currently enabled. + filename="gio/gaction.c" + line="113">If @action is currently enabled. -If the action is disabled then calls to g_action_activate() and -g_action_change_state() have no effect. +If the action is disabled then calls to [method@Gio.Action.activate] and +[method@Gio.Action.change_state] have no effect. getter="get_name" default-value="NULL"> The name of the action. This is mostly meaningful for identifying -the action once it has been added to a #GActionGroup. It is immutable. + filename="gio/gaction.c" + line="84">The name of the action. This is mostly meaningful for identifying +the action once it has been added to a [type@Gio.ActionGroup]. It is immutable. transfer-ownership="none" getter="get_parameter_type"> The type of the parameter that must be given when activating the -action. This is immutable, and may be %NULL if no parameter is needed when + filename="gio/gaction.c" + line="98">The type of the parameter that must be given when activating the +action. This is immutable, and may be `NULL` if no parameter is needed when activating the action. @@ -924,8 +930,8 @@ activating the action. transfer-ownership="none" getter="get_state"> The state of the action, or %NULL if the action is stateless. + filename="gio/gaction.c" + line="143">The state of the action, or `NULL` if the action is stateless. transfer-ownership="none" getter="get_state_type"> The #GVariantType of the state that the action has, or %NULL if the + filename="gio/gaction.c" + line="129">The [type@GLib.VariantType] of the state that the action has, or `NULL` if the action is stateless. This is immutable. This struct defines a single action. It is for use with -g_action_map_add_action_entries(). + filename="gio/gactionmap.c" + line="127">This struct defines a single action. It is for use with +[method@Gio.ActionMap.add_action_entries]. The order of the items in the structure are intended to reflect frequency of use. It is permissible to use an incomplete initialiser -in order to leave some of the later values as %NULL. All values +in order to leave some of the later values as `NULL`. All values after @name are optional. Additional optional fields may be added in the future. -See g_action_map_add_action_entries() for an example. - +See [method@Gio.ActionMap.add_action_entries] for an example. + the name of the action + filename="gio/gactionmap.c" + line="129">the name of the action + the callback to connect to the "activate" signal of the action. + Since GLib 2.40, this can be `NULL` for stateful actions, in which case + the default handler is used. For boolean-stated actions with no + parameter, this is a toggle. For other state types (and parameter type + equal to the state type) this will be a function that just calls + @change_state (which you should provide). - + @@ -984,25 +998,29 @@ See g_action_map_add_action_entries() for an example. the type of the parameter that must be passed to the - activate function for this action, given as a single - GVariant type string (or %NULL for no parameter) + filename="gio/gactionmap.c" + line="136">the type of the parameter that must be passed to the + activate function for this action, given as a single GVariant type string + (or `NULL` for no parameter) the initial state for this action, given in - [GVariant text format][gvariant-text]. The state is parsed - with no extra type information, so type tags must be added to - the string if they are necessary. Stateless actions should - give %NULL here. + filename="gio/gactionmap.c" + line="139">the initial state for this action, given in + [GVariant text format](gvariant-text-format.html). The state is parsed + with no extra type information, so type tags must be added to the string + if they are necessary. Stateless actions should give `NULL` here. + the callback to connect to the "change-state" signal of the + action. All stateful actions should provide a handler here; stateless + actions should not. - + @@ -1036,76 +1054,75 @@ See g_action_map_add_action_entries() for an example. glib:get-type="g_action_group_get_type" glib:type-struct="ActionGroupInterface"> #GActionGroup represents a group of actions. Actions can be used to -expose functionality in a structured way, either from one part of a -program to another, or to the outside world. Action groups are often -used together with a #GMenuModel that provides additional -representation data for displaying the actions to the user, e.g. in -a menu. - -The main way to interact with the actions in a GActionGroup is to -activate them with g_action_group_activate_action(). Activating an -action may require a #GVariant parameter. The required type of the -parameter can be inquired with g_action_group_get_action_parameter_type(). -Actions may be disabled, see g_action_group_get_action_enabled(). + filename="gio/gactiongroup.c" + line="28">`GActionGroup` represents a group of actions. + +Actions can be used to expose functionality in a structured way, either +from one part of a program to another, or to the outside world. Action +groups are often used together with a [type@Gio.MenuModel] that provides additional +representation data for displaying the actions to the user, e.g. in a menu. + +The main way to interact with the actions in a `GActionGroup` is to +activate them with [method@Gio.ActionGroup.activate_action]. Activating an +action may require a [type@GLib.Variant] parameter. The required type of the +parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type]. +Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled]. Activating a disabled action has no effect. -Actions may optionally have a state in the form of a #GVariant. The -current state of an action can be inquired with -g_action_group_get_action_state(). Activating a stateful action may -change its state, but it is also possible to set the state by calling -g_action_group_change_action_state(). +Actions may optionally have a state in the form of a [type@GLib.Variant]. The current +state of an action can be inquired with [method@Gio.ActionGroup.get_action_state]. +Activating a stateful action may change its state, but it is also possible to +set the state by calling [method@Gio.ActionGroup.change_action_state]. As typical example, consider a text editing application which has an -option to change the current font to 'bold'. A good way to represent +option to change the current font to ‘bold’. A good way to represent this would be a stateful action, with a boolean state. Activating the action would toggle the state. Each action in the group has a unique name (which is a string). All -method calls, except g_action_group_list_actions() take the name of +method calls, except [method@Gio.ActionGroup.list_actions] take the name of an action as an argument. -The #GActionGroup API is meant to be the 'public' API to the action -group. The calls here are exactly the interaction that 'external -forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have -with actions. 'Internal' APIs (ie: ones meant only to be accessed by -the action group implementation) are found on subclasses. This is -why you will find - for example - g_action_group_get_action_enabled() -but not an equivalent set() call. +The `GActionGroup` API is meant to be the ‘public’ API to the action +group. The calls here are exactly the interaction that ‘external +forces’ (eg: UI, incoming D-Bus messages, etc.) are supposed to have +with actions. ‘Internal’ APIs (ie: ones meant only to be accessed by +the action group implementation) are found on subclasses. This is +why you will find – for example – [method@Gio.ActionGroup.get_action_enabled] +but not an equivalent `set_action_enabled()` method. Signals are emitted on the action group in response to state changes on individual actions. -Implementations of #GActionGroup should provide implementations for -the virtual functions g_action_group_list_actions() and -g_action_group_query_action(). The other virtual functions should -not be implemented - their "wrappers" are actually implemented with -calls to g_action_group_query_action(). - +Implementations of `GActionGroup` should provide implementations for +the virtual functions [method@Gio.ActionGroup.list_actions] and +[method@Gio.ActionGroup.query_action]. The other virtual functions should +not be implemented — their ‘wrappers’ are actually implemented with +calls to [method@Gio.ActionGroup.query_action]. + Emits the #GActionGroup::action-added signal on @action_group. + filename="gio/gactiongroup.c" + line="628">Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="630">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="631">the name of an action in the group @@ -1114,31 +1131,31 @@ This function should only be called by #GActionGroup implementations. invoker="action_enabled_changed" version="2.28"> Emits the #GActionGroup::action-enabled-changed signal on @action_group. + filename="gio/gactiongroup.c" + line="676">Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="678">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="679">the name of an action in the group whether or not the action is now enabled + filename="gio/gactiongroup.c" + line="680">whether the action is now enabled @@ -1147,25 +1164,25 @@ This function should only be called by #GActionGroup implementations. invoker="action_removed" version="2.28"> Emits the #GActionGroup::action-removed signal on @action_group. + filename="gio/gactiongroup.c" + line="652">Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="654">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="655">the name of an action in the group @@ -1174,31 +1191,31 @@ This function should only be called by #GActionGroup implementations. invoker="action_state_changed" version="2.28"> Emits the #GActionGroup::action-state-changed signal on @action_group. + filename="gio/gactiongroup.c" + line="705">Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="707">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="708">the name of an action in the group the new state of the named action + filename="gio/gactiongroup.c" + line="709">the new state of the named action @@ -1207,55 +1224,55 @@ This function should only be called by #GActionGroup implementations. invoker="activate_action" version="2.28"> Activate the named action within @action_group. + filename="gio/gactiongroup.c" + line="574">Activate the named action within @action_group. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no -parameters then @parameter must be %NULL. See -g_action_group_get_action_parameter_type(). +parameters then @parameter must be `NULL`. See +[method@Gio.ActionGroup.get_action_parameter_type]. -If the #GActionGroup implementation supports asynchronous remote +If the [type@Gio.ActionGroup] implementation supports asynchronous remote activation over D-Bus, this call may return before the relevant D-Bus traffic has been sent, or any replies have been received. In order to block on such asynchronous activation calls, -g_dbus_connection_flush() should be called prior to the code, which +[method@Gio.DBusConnection.flush] should be called prior to the code, which depends on the result of the action activation. Without flushing the D-Bus connection, there is no guarantee that the action would have been activated. The following code which runs in a remote app instance, shows an -example of a "quit" action being activated on the primary app -instance over D-Bus. Here g_dbus_connection_flush() is called -before `exit()`. Without g_dbus_connection_flush(), the "quit" action +example of a ‘quit’ action being activated on the primary app +instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called +before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action may fail to be activated on the primary instance. -|[<!-- language="C" --> -// call "quit" action on primary instance +```c +// call ‘quit’ action on primary instance g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); // make sure the action is activated now -g_dbus_connection_flush (...); +g_dbus_connection_flush (…); -g_debug ("application has been terminated. exiting."); +g_debug ("Application has been terminated. Exiting."); exit (0); -]| - +``` + a #GActionGroup + filename="gio/gactiongroup.c" + line="576">a [type@Gio.ActionGroup] the name of the action to activate + filename="gio/gactiongroup.c" + line="577">the name of the action to activate parameters to the activation + filename="gio/gactiongroup.c" + line="578">parameters to the activation @@ -1273,39 +1290,39 @@ exit (0); invoker="change_action_state" version="2.28"> Request for the state of the named action within @action_group to be + filename="gio/gactiongroup.c" + line="541">Request for the state of the named action within @action_group to be changed to @value. The action must be stateful and @value must be of the correct type. -See g_action_group_get_action_state_type(). +See [method@Gio.ActionGroup.get_action_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. -See g_action_group_get_action_state_hint(). +See [method@Gio.ActionGroup.get_action_state_hint]. If the @value GVariant is floating, it is consumed. - + a #GActionGroup + filename="gio/gactiongroup.c" + line="543">a [type@Gio.ActionGroup] the name of the action to request the change on + filename="gio/gactiongroup.c" + line="544">the name of the action to request the change on the new state + filename="gio/gactiongroup.c" + line="545">the new state @@ -1314,29 +1331,29 @@ If the @value GVariant is floating, it is consumed. invoker="get_action_enabled" version="2.28"> Checks if the named action within @action_group is currently enabled. + filename="gio/gactiongroup.c" + line="489">Checks if the named action within @action_group is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. - + whether or not the action is currently enabled + filename="gio/gactiongroup.c" + line="499">whether the action is currently enabled a #GActionGroup + filename="gio/gactiongroup.c" + line="491">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="492">the name of the action to query @@ -1345,38 +1362,38 @@ have its state changed from outside callers. invoker="get_action_parameter_type" version="2.28"> Queries the type of the parameter that must be given when activating + filename="gio/gactiongroup.c" + line="382">Queries the type of the parameter that must be given when activating the named action within @action_group. -When activating the action using g_action_group_activate_action(), -the #GVariant given to that function must be of the type returned +When activating the action using [method@Gio.ActionGroup.activate_action], +the [type@GLib.Variant] given to that function must be of the type returned by this function. -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. +In the case that this function returns `NULL`, you must not give any +[type@GLib.Variant], but `NULL` instead. The parameter type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different parameter type. - + the parameter type + filename="gio/gactiongroup.c" + line="401">the parameter type a #GActionGroup + filename="gio/gactiongroup.c" + line="384">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="385">the name of the action to query @@ -1385,33 +1402,33 @@ with the same name but a different parameter type. invoker="get_action_state" version="2.28"> Queries the current state of the named action within @action_group. + filename="gio/gactiongroup.c" + line="513">Queries the current state of the named action within @action_group. -If the action is not stateful then %NULL will be returned. If the +If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type -given by g_action_group_get_action_state_type(). +given by [method@Gio.ActionGroup.get_action_state_type]. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the current state of the action + filename="gio/gactiongroup.c" + line="527">the current state of the action a #GActionGroup + filename="gio/gactiongroup.c" + line="515">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="516">the name of the action to query @@ -1420,16 +1437,16 @@ g_variant_unref() when it is no longer required. invoker="get_action_state_hint" version="2.28"> Requests a hint about the valid range of values for the state of the + filename="gio/gactiongroup.c" + line="451">Requests a hint about the valid range of values for the state of the named action within @action_group. -If %NULL is returned it either means that the action is not stateful +If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is +If a [type@GLib.Variant] array is returned then each item in the array is a +possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. @@ -1437,26 +1454,26 @@ In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the state range hint + filename="gio/gactiongroup.c" + line="475">the state range hint a #GActionGroup + filename="gio/gactiongroup.c" + line="453">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="454">the name of the action to query @@ -1465,67 +1482,67 @@ g_variant_unref() when it is no longer required. invoker="get_action_state_type" version="2.28"> Queries the type of the state of the named action within + filename="gio/gactiongroup.c" + line="415">Queries the type of the state of the named action within @action_group. If the action is stateful then this function returns the -#GVariantType of the state. All calls to -g_action_group_change_action_state() must give a #GVariant of this -type and g_action_group_get_action_state() will return a #GVariant +[type@GLib.VariantType] of the state. All calls to +[method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this +type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant] of the same type. -If the action is not stateful then this function will return %NULL. -In that case, g_action_group_get_action_state() will return %NULL -and you must not call g_action_group_change_action_state(). +If the action is not stateful then this function will return `NULL`. +In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL` +and you must not call [method@Gio.ActionGroup.change_action_state]. The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type. - + the state type, if the action is stateful + filename="gio/gactiongroup.c" + line="437">the state type, if the action is stateful a #GActionGroup + filename="gio/gactiongroup.c" + line="417">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="418">the name of the action to query Checks if the named action exists within @action_group. - + filename="gio/gactiongroup.c" + line="361">Checks if the named action exists within @action_group. + whether the named action exists + filename="gio/gactiongroup.c" + line="368">whether the named action exists a #GActionGroup + filename="gio/gactiongroup.c" + line="363">a [type@Gio.ActionGroup] the name of the action to check for + filename="gio/gactiongroup.c" + line="364">the name of the action to check for @@ -1534,17 +1551,17 @@ with the same name but a different state type. invoker="list_actions" version="2.28"> Lists the actions contained within @action_group. + filename="gio/gactiongroup.c" + line="338">Lists the actions contained within @action_group. -The caller is responsible for freeing the list with g_strfreev() when +The caller is responsible for freeing the list with [func@GLib.strfreev] when it is no longer required. - + a %NULL-terminated array of the names of the -actions in the group + filename="gio/gactiongroup.c" + line="347">a `NULL`-terminated array + of the names of the actions in the group @@ -1552,8 +1569,8 @@ actions in the group a #GActionGroup + filename="gio/gactiongroup.c" + line="340">a [type@Gio.ActionGroup] @@ -1562,22 +1579,22 @@ actions in the group invoker="query_action" version="2.32"> Queries all aspects of the named action within an @action_group. + filename="gio/gactiongroup.c" + line="732">Queries all aspects of the named action within an @action_group. This function acquires the information available from -g_action_group_has_action(), g_action_group_get_action_enabled(), -g_action_group_get_action_parameter_type(), -g_action_group_get_action_state_type(), -g_action_group_get_action_state_hint() and -g_action_group_get_action_state() with a single function call. +[method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled], +[method@Gio.ActionGroup.get_action_parameter_type], +[method@Gio.ActionGroup.get_action_state_type], +[method@Gio.ActionGroup.get_action_state_hint] and +[method@Gio.ActionGroup.get_action_state] with a single function call. This provides two main benefits. The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing -#GActionGroup can now be done by only overriding this one virtual +[type@Gio.ActionGroup] can now be done by only overriding this one virtual function. The interface provides a default implementation of this function that @@ -1586,28 +1603,28 @@ information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others. -If the action exists, %TRUE is returned and any of the requested -fields (as indicated by having a non-%NULL reference passed in) are -filled. If the action doesn't exist, %FALSE is returned and the +If the action exists, `TRUE` is returned and any of the requested +fields (as indicated by having a non-`NULL` reference passed in) are +filled. If the action doesn’t exist, `FALSE` is returned and the fields may or may not have been modified. - + %TRUE if the action exists, else %FALSE + filename="gio/gactiongroup.c" + line="770">`TRUE` if the action exists, else `FALSE` a #GActionGroup + filename="gio/gactiongroup.c" + line="734">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="735">the name of an action in the group caller-allocates="0" transfer-ownership="full"> if the action is presently enabled + filename="gio/gactiongroup.c" + line="736">if the action is presently enabled optional="1" allow-none="1"> the parameter type, or %NULL if none needed + filename="gio/gactiongroup.c" + line="737">the parameter type, or `NULL` if none needed optional="1" allow-none="1"> the state type, or %NULL if stateless + filename="gio/gactiongroup.c" + line="738">the state type, or `NULL` if stateless optional="1" allow-none="1"> the state hint, or %NULL if none + filename="gio/gactiongroup.c" + line="739">the state hint, or `NULL` if none optional="1" allow-none="1"> the current state, or %NULL if stateless + filename="gio/gactiongroup.c" + line="740">the current state, or `NULL` if stateless @@ -1669,25 +1686,25 @@ fields may or may not have been modified. c:identifier="g_action_group_action_added" version="2.28"> Emits the #GActionGroup::action-added signal on @action_group. + filename="gio/gactiongroup.c" + line="628">Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="630">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="631">the name of an action in the group @@ -1696,31 +1713,31 @@ This function should only be called by #GActionGroup implementations. c:identifier="g_action_group_action_enabled_changed" version="2.28"> Emits the #GActionGroup::action-enabled-changed signal on @action_group. + filename="gio/gactiongroup.c" + line="676">Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="678">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="679">the name of an action in the group whether or not the action is now enabled + filename="gio/gactiongroup.c" + line="680">whether the action is now enabled @@ -1729,25 +1746,25 @@ This function should only be called by #GActionGroup implementations. c:identifier="g_action_group_action_removed" version="2.28"> Emits the #GActionGroup::action-removed signal on @action_group. + filename="gio/gactiongroup.c" + line="652">Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="654">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="655">the name of an action in the group @@ -1756,31 +1773,31 @@ This function should only be called by #GActionGroup implementations. c:identifier="g_action_group_action_state_changed" version="2.28"> Emits the #GActionGroup::action-state-changed signal on @action_group. + filename="gio/gactiongroup.c" + line="705">Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group. -This function should only be called by #GActionGroup implementations. - +This function should only be called by [type@Gio.ActionGroup] implementations. + a #GActionGroup + filename="gio/gactiongroup.c" + line="707">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="708">the name of an action in the group the new state of the named action + filename="gio/gactiongroup.c" + line="709">the new state of the named action @@ -1789,55 +1806,55 @@ This function should only be called by #GActionGroup implementations. c:identifier="g_action_group_activate_action" version="2.28"> Activate the named action within @action_group. + filename="gio/gactiongroup.c" + line="574">Activate the named action within @action_group. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no -parameters then @parameter must be %NULL. See -g_action_group_get_action_parameter_type(). +parameters then @parameter must be `NULL`. See +[method@Gio.ActionGroup.get_action_parameter_type]. -If the #GActionGroup implementation supports asynchronous remote +If the [type@Gio.ActionGroup] implementation supports asynchronous remote activation over D-Bus, this call may return before the relevant D-Bus traffic has been sent, or any replies have been received. In order to block on such asynchronous activation calls, -g_dbus_connection_flush() should be called prior to the code, which +[method@Gio.DBusConnection.flush] should be called prior to the code, which depends on the result of the action activation. Without flushing the D-Bus connection, there is no guarantee that the action would have been activated. The following code which runs in a remote app instance, shows an -example of a "quit" action being activated on the primary app -instance over D-Bus. Here g_dbus_connection_flush() is called -before `exit()`. Without g_dbus_connection_flush(), the "quit" action +example of a ‘quit’ action being activated on the primary app +instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called +before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action may fail to be activated on the primary instance. -|[<!-- language="C" --> -// call "quit" action on primary instance +```c +// call ‘quit’ action on primary instance g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); // make sure the action is activated now -g_dbus_connection_flush (...); +g_dbus_connection_flush (…); -g_debug ("application has been terminated. exiting."); +g_debug ("Application has been terminated. Exiting."); exit (0); -]| - +``` + a #GActionGroup + filename="gio/gactiongroup.c" + line="576">a [type@Gio.ActionGroup] the name of the action to activate + filename="gio/gactiongroup.c" + line="577">the name of the action to activate parameters to the activation + filename="gio/gactiongroup.c" + line="578">parameters to the activation @@ -1855,39 +1872,39 @@ exit (0); c:identifier="g_action_group_change_action_state" version="2.28"> Request for the state of the named action within @action_group to be + filename="gio/gactiongroup.c" + line="541">Request for the state of the named action within @action_group to be changed to @value. The action must be stateful and @value must be of the correct type. -See g_action_group_get_action_state_type(). +See [method@Gio.ActionGroup.get_action_state_type]. This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. -See g_action_group_get_action_state_hint(). +See [method@Gio.ActionGroup.get_action_state_hint]. If the @value GVariant is floating, it is consumed. - + a #GActionGroup + filename="gio/gactiongroup.c" + line="543">a [type@Gio.ActionGroup] the name of the action to request the change on + filename="gio/gactiongroup.c" + line="544">the name of the action to request the change on the new state + filename="gio/gactiongroup.c" + line="545">the new state @@ -1896,29 +1913,29 @@ If the @value GVariant is floating, it is consumed. c:identifier="g_action_group_get_action_enabled" version="2.28"> Checks if the named action within @action_group is currently enabled. + filename="gio/gactiongroup.c" + line="489">Checks if the named action within @action_group is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. - + whether or not the action is currently enabled + filename="gio/gactiongroup.c" + line="499">whether the action is currently enabled a #GActionGroup + filename="gio/gactiongroup.c" + line="491">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="492">the name of the action to query @@ -1927,38 +1944,38 @@ have its state changed from outside callers. c:identifier="g_action_group_get_action_parameter_type" version="2.28"> Queries the type of the parameter that must be given when activating + filename="gio/gactiongroup.c" + line="382">Queries the type of the parameter that must be given when activating the named action within @action_group. -When activating the action using g_action_group_activate_action(), -the #GVariant given to that function must be of the type returned +When activating the action using [method@Gio.ActionGroup.activate_action], +the [type@GLib.Variant] given to that function must be of the type returned by this function. -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. +In the case that this function returns `NULL`, you must not give any +[type@GLib.Variant], but `NULL` instead. The parameter type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different parameter type. - + the parameter type + filename="gio/gactiongroup.c" + line="401">the parameter type a #GActionGroup + filename="gio/gactiongroup.c" + line="384">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="385">the name of the action to query @@ -1967,33 +1984,33 @@ with the same name but a different parameter type. c:identifier="g_action_group_get_action_state" version="2.28"> Queries the current state of the named action within @action_group. + filename="gio/gactiongroup.c" + line="513">Queries the current state of the named action within @action_group. -If the action is not stateful then %NULL will be returned. If the +If the action is not stateful then `NULL` will be returned. If the action is stateful then the type of the return value is the type -given by g_action_group_get_action_state_type(). +given by [method@Gio.ActionGroup.get_action_state_type]. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the current state of the action + filename="gio/gactiongroup.c" + line="527">the current state of the action a #GActionGroup + filename="gio/gactiongroup.c" + line="515">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="516">the name of the action to query @@ -2002,16 +2019,16 @@ g_variant_unref() when it is no longer required. c:identifier="g_action_group_get_action_state_hint" version="2.28"> Requests a hint about the valid range of values for the state of the + filename="gio/gactiongroup.c" + line="451">Requests a hint about the valid range of values for the state of the named action within @action_group. -If %NULL is returned it either means that the action is not stateful +If `NULL` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is +If a [type@GLib.Variant] array is returned then each item in the array is a +possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. @@ -2019,26 +2036,26 @@ In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - +The return value (if non-`NULL`) should be freed with +[method@GLib.Variant.unref] when it is no longer required. + the state range hint + filename="gio/gactiongroup.c" + line="475">the state range hint a #GActionGroup + filename="gio/gactiongroup.c" + line="453">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="454">the name of the action to query @@ -2047,41 +2064,41 @@ g_variant_unref() when it is no longer required. c:identifier="g_action_group_get_action_state_type" version="2.28"> Queries the type of the state of the named action within + filename="gio/gactiongroup.c" + line="415">Queries the type of the state of the named action within @action_group. If the action is stateful then this function returns the -#GVariantType of the state. All calls to -g_action_group_change_action_state() must give a #GVariant of this -type and g_action_group_get_action_state() will return a #GVariant +[type@GLib.VariantType] of the state. All calls to +[method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this +type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant] of the same type. -If the action is not stateful then this function will return %NULL. -In that case, g_action_group_get_action_state() will return %NULL -and you must not call g_action_group_change_action_state(). +If the action is not stateful then this function will return `NULL`. +In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL` +and you must not call [method@Gio.ActionGroup.change_action_state]. The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type. - + the state type, if the action is stateful + filename="gio/gactiongroup.c" + line="437">the state type, if the action is stateful a #GActionGroup + filename="gio/gactiongroup.c" + line="417">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="418">the name of the action to query @@ -2090,26 +2107,26 @@ with the same name but a different state type. c:identifier="g_action_group_has_action" version="2.28"> Checks if the named action exists within @action_group. - + filename="gio/gactiongroup.c" + line="361">Checks if the named action exists within @action_group. + whether the named action exists + filename="gio/gactiongroup.c" + line="368">whether the named action exists a #GActionGroup + filename="gio/gactiongroup.c" + line="363">a [type@Gio.ActionGroup] the name of the action to check for + filename="gio/gactiongroup.c" + line="364">the name of the action to check for @@ -2118,17 +2135,17 @@ with the same name but a different state type. c:identifier="g_action_group_list_actions" version="2.28"> Lists the actions contained within @action_group. + filename="gio/gactiongroup.c" + line="338">Lists the actions contained within @action_group. -The caller is responsible for freeing the list with g_strfreev() when +The caller is responsible for freeing the list with [func@GLib.strfreev] when it is no longer required. - + a %NULL-terminated array of the names of the -actions in the group + filename="gio/gactiongroup.c" + line="347">a `NULL`-terminated array + of the names of the actions in the group @@ -2136,8 +2153,8 @@ actions in the group a #GActionGroup + filename="gio/gactiongroup.c" + line="340">a [type@Gio.ActionGroup] @@ -2146,22 +2163,22 @@ actions in the group c:identifier="g_action_group_query_action" version="2.32"> Queries all aspects of the named action within an @action_group. + filename="gio/gactiongroup.c" + line="732">Queries all aspects of the named action within an @action_group. This function acquires the information available from -g_action_group_has_action(), g_action_group_get_action_enabled(), -g_action_group_get_action_parameter_type(), -g_action_group_get_action_state_type(), -g_action_group_get_action_state_hint() and -g_action_group_get_action_state() with a single function call. +[method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled], +[method@Gio.ActionGroup.get_action_parameter_type], +[method@Gio.ActionGroup.get_action_state_type], +[method@Gio.ActionGroup.get_action_state_hint] and +[method@Gio.ActionGroup.get_action_state] with a single function call. This provides two main benefits. The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing -#GActionGroup can now be done by only overriding this one virtual +[type@Gio.ActionGroup] can now be done by only overriding this one virtual function. The interface provides a default implementation of this function that @@ -2170,28 +2187,28 @@ information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others. -If the action exists, %TRUE is returned and any of the requested -fields (as indicated by having a non-%NULL reference passed in) are -filled. If the action doesn't exist, %FALSE is returned and the +If the action exists, `TRUE` is returned and any of the requested +fields (as indicated by having a non-`NULL` reference passed in) are +filled. If the action doesn’t exist, `FALSE` is returned and the fields may or may not have been modified. - + %TRUE if the action exists, else %FALSE + filename="gio/gactiongroup.c" + line="770">`TRUE` if the action exists, else `FALSE` a #GActionGroup + filename="gio/gactiongroup.c" + line="734">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="735">the name of an action in the group caller-allocates="0" transfer-ownership="full"> if the action is presently enabled + filename="gio/gactiongroup.c" + line="736">if the action is presently enabled optional="1" allow-none="1"> the parameter type, or %NULL if none needed + filename="gio/gactiongroup.c" + line="737">the parameter type, or `NULL` if none needed optional="1" allow-none="1"> the state type, or %NULL if stateless + filename="gio/gactiongroup.c" + line="738">the state type, or `NULL` if stateless optional="1" allow-none="1"> the state hint, or %NULL if none + filename="gio/gactiongroup.c" + line="739">the state hint, or `NULL` if none optional="1" allow-none="1"> the current state, or %NULL if stateless + filename="gio/gactiongroup.c" + line="740">the current state, or `NULL` if stateless Signals that a new action was just added to the group. + filename="gio/gactiongroup.c" + line="241">Signals that a new action was just added to the group. + This signal is emitted after the action has been added and is now visible. @@ -2261,8 +2279,8 @@ and is now visible. the name of the action in @action_group + filename="gio/gactiongroup.c" + line="244">the name of the action in @action_group @@ -2272,22 +2290,22 @@ and is now visible. detailed="1" version="2.28"> Signals that the enabled status of the named action has changed. + filename="gio/gactiongroup.c" + line="285">Signals that the enabled status of the named action has changed. the name of the action in @action_group + filename="gio/gactiongroup.c" + line="288">the name of the action in @action_group whether the action is enabled or not + filename="gio/gactiongroup.c" + line="289">whether the action is enabled @@ -2297,8 +2315,9 @@ and is now visible. detailed="1" version="2.28"> Signals that an action is just about to be removed from the group. + filename="gio/gactiongroup.c" + line="263">Signals that an action is just about to be removed from the group. + This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler. @@ -2307,8 +2326,8 @@ is still visible and can be queried from the signal handler. the name of the action in @action_group + filename="gio/gactiongroup.c" + line="266">the name of the action in @action_group @@ -2318,22 +2337,22 @@ is still visible and can be queried from the signal handler. detailed="1" version="2.28"> Signals that the state of the named action has changed. + filename="gio/gactiongroup.c" + line="310">Signals that the state of the named action has changed. the name of the action in @action_group + filename="gio/gactiongroup.c" + line="313">the name of the action in @action_group the new value of the state + filename="gio/gactiongroup.c" + line="314">the new value of the state @@ -2344,45 +2363,51 @@ is still visible and can be queried from the signal handler. glib:is-gtype-struct-for="ActionGroup" version="2.28"> The virtual function table for #GActionGroup. - + filename="gio/gactiongroup.c" + line="77">The virtual function table for [type@Gio.ActionGroup]. + + the virtual function pointer for [method@Gio.ActionGroup.has_action] - + whether the named action exists + filename="gio/gactiongroup.c" + line="368">whether the named action exists a #GActionGroup + filename="gio/gactiongroup.c" + line="363">a [type@Gio.ActionGroup] the name of the action to check for + filename="gio/gactiongroup.c" + line="364">the name of the action to check for + the virtual function pointer for [method@Gio.ActionGroup.list_actions] - + a %NULL-terminated array of the names of the -actions in the group + filename="gio/gactiongroup.c" + line="347">a `NULL`-terminated array + of the names of the actions in the group @@ -2390,183 +2415,204 @@ actions in the group a #GActionGroup + filename="gio/gactiongroup.c" + line="340">a [type@Gio.ActionGroup] + the virtual function pointer for [method@Gio.ActionGroup.get_action_enabled] - + whether or not the action is currently enabled + filename="gio/gactiongroup.c" + line="499">whether the action is currently enabled a #GActionGroup + filename="gio/gactiongroup.c" + line="491">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="492">the name of the action to query + the virtual function pointer for [method@Gio.ActionGroup.get_action_parameter_type] - + the parameter type + filename="gio/gactiongroup.c" + line="401">the parameter type a #GActionGroup + filename="gio/gactiongroup.c" + line="384">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="385">the name of the action to query + the virtual function pointer for [method@Gio.ActionGroup.get_action_state_type] - + the state type, if the action is stateful + filename="gio/gactiongroup.c" + line="437">the state type, if the action is stateful a #GActionGroup + filename="gio/gactiongroup.c" + line="417">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="418">the name of the action to query + the virtual function pointer for [method@Gio.ActionGroup.get_action_state_hint] - + the state range hint + filename="gio/gactiongroup.c" + line="475">the state range hint a #GActionGroup + filename="gio/gactiongroup.c" + line="453">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="454">the name of the action to query + the virtual function pointer for [method@Gio.ActionGroup.get_action_state] - + the current state of the action + filename="gio/gactiongroup.c" + line="527">the current state of the action a #GActionGroup + filename="gio/gactiongroup.c" + line="515">a [type@Gio.ActionGroup] the name of the action to query + filename="gio/gactiongroup.c" + line="516">the name of the action to query + the virtual function pointer for [method@Gio.ActionGroup.change_action_state] - + a #GActionGroup + filename="gio/gactiongroup.c" + line="543">a [type@Gio.ActionGroup] the name of the action to request the change on + filename="gio/gactiongroup.c" + line="544">the name of the action to request the change on the new state + filename="gio/gactiongroup.c" + line="545">the new state + the virtual function pointer for [method@Gio.ActionGroup.activate_action] - + a #GActionGroup + filename="gio/gactiongroup.c" + line="576">a [type@Gio.ActionGroup] the name of the action to activate + filename="gio/gactiongroup.c" + line="577">the name of the action to activate nullable="1" allow-none="1"> parameters to the activation + filename="gio/gactiongroup.c" + line="578">parameters to the activation + the class closure for the [signal@Gio.ActionGroup::action-added] signal - + a #GActionGroup + filename="gio/gactiongroup.c" + line="630">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="631">the name of an action in the group + the class closure for the [signal@Gio.ActionGroup::action-removed] signal - + a #GActionGroup + filename="gio/gactiongroup.c" + line="654">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="655">the name of an action in the group + the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal - + a #GActionGroup + filename="gio/gactiongroup.c" + line="678">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="679">the name of an action in the group whether or not the action is now enabled + filename="gio/gactiongroup.c" + line="680">whether the action is now enabled + the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal - + a #GActionGroup + filename="gio/gactiongroup.c" + line="707">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="708">the name of an action in the group the new state of the named action + filename="gio/gactiongroup.c" + line="709">the new state of the named action + the virtual function pointer for [method@Gio.ActionGroup.query_action] - + %TRUE if the action exists, else %FALSE + filename="gio/gactiongroup.c" + line="770">`TRUE` if the action exists, else `FALSE` a #GActionGroup + filename="gio/gactiongroup.c" + line="734">a [type@Gio.ActionGroup] the name of an action in the group + filename="gio/gactiongroup.c" + line="735">the name of an action in the group caller-allocates="0" transfer-ownership="full"> if the action is presently enabled + filename="gio/gactiongroup.c" + line="736">if the action is presently enabled optional="1" allow-none="1"> the parameter type, or %NULL if none needed + filename="gio/gactiongroup.c" + line="737">the parameter type, or `NULL` if none needed optional="1" allow-none="1"> the state type, or %NULL if stateless + filename="gio/gactiongroup.c" + line="738">the state type, or `NULL` if stateless optional="1" allow-none="1"> the state hint, or %NULL if none + filename="gio/gactiongroup.c" + line="739">the state hint, or `NULL` if none optional="1" allow-none="1"> the current state, or %NULL if stateless + filename="gio/gactiongroup.c" + line="740">the current state, or `NULL` if stateless @@ -2765,159 +2826,184 @@ actions in the group glib:is-gtype-struct-for="Action" version="2.28"> The virtual function table for #GAction. - + filename="gio/gaction.c" + line="64">The virtual function table for [type@Gio.Action]. + + the virtual function pointer for [method@Gio.Action.get_name] - + the name of the action + filename="gio/gaction.c" + line="228">the name of the action a #GAction + filename="gio/gaction.c" + line="224">a [type@Gio.Action] + the virtual function pointer for [method@Gio.Action.get_parameter_type] - + the parameter type + filename="gio/gaction.c" + line="255">the parameter type a #GAction + filename="gio/gaction.c" + line="243">a [type@Gio.Action] + the virtual function pointer for [method@Gio.Action.get_state_type] - + the state type, if the action is stateful + filename="gio/gaction.c" + line="285">the state type, if the action is stateful a #GAction + filename="gio/gaction.c" + line="270">a [type@Gio.Action] + the virtual function pointer for [method@Gio.Action.get_state_hint] - + the state range hint + filename="gio/gaction.c" + line="321">the state range hint a #GAction + filename="gio/gaction.c" + line="300">a [type@Gio.Action] + the virtual function pointer for [method@Gio.Action.get_enabled] - + whether the action is enabled + filename="gio/gaction.c" + line="343">whether the action is enabled a #GAction + filename="gio/gaction.c" + line="336">a [type@Gio.Action] + the virtual function pointer for [method@Gio.Action.get_state] - + the current state of the action + filename="gio/gaction.c" + line="209">the current state of the action a #GAction + filename="gio/gaction.c" + line="198">a [type@Gio.Action] + the virtual function pointer for [method@Gio.Action.change_state] - + a #GAction + filename="gio/gaction.c" + line="160">a [type@Gio.Action] the new state + filename="gio/gaction.c" + line="161">the new state + the virtual function pointer for [method@Gio.Action.activate]. Note that [type@Gio.Action] does not have an + 'activate' signal but that implementations of it may have one. - + a #GAction + filename="gio/gaction.c" + line="358">a [type@Gio.Action] nullable="1" allow-none="1"> the parameter to the activation + filename="gio/gaction.c" + line="359">the parameter to the activation @@ -2941,41 +3027,43 @@ actions in the group glib:get-type="g_action_map_get_type" glib:type-struct="ActionMapInterface"> The GActionMap interface is implemented by #GActionGroup -implementations that operate by containing a number of -named #GAction instances, such as #GSimpleActionGroup. + filename="gio/gactionmap.c" + line="28">`GActionMap` is an interface for action containers. + +The `GActionMap` interface is implemented by [iface@Gio.ActionGroup] +implementations that operate by containing a number of named +[iface@Gio.Action] instances, such as [class@Gio.SimpleActionGroup]. One useful application of this interface is to map the names of actions from various action groups to unique, prefixed names (e.g. by prepending "app." or "win."). -This is the motivation for the 'Map' part of the interface +This is the motivation for the ‘Map’ part of the interface name. - + Adds an action to the @action_map. + filename="gio/gactionmap.c" + line="88">Adds an action to the @action_map. If the action map already contains an action with the same name as @action then the old action is dropped from the action map. The action map takes its own reference on @action. - + a #GActionMap + filename="gio/gactionmap.c" + line="90">an action map a #GAction + filename="gio/gactionmap.c" + line="91">a [iface@Gio.Action] @@ -2984,28 +3072,28 @@ The action map takes its own reference on @action. invoker="lookup_action" version="2.32"> Looks up the action with the name @action_name in @action_map. + filename="gio/gactionmap.c" + line="67">Looks up the action with the name @action_name in @action_map. -If no such action exists, returns %NULL. - +If no such action exists, returns `NULL`. + a #GAction, or %NULL + filename="gio/gactionmap.c" + line="76">a [iface@Gio.Action] a #GActionMap + filename="gio/gactionmap.c" + line="69">an action map the name of an action + filename="gio/gactionmap.c" + line="70">the name of an action @@ -3014,25 +3102,25 @@ If no such action exists, returns %NULL. invoker="remove_action" version="2.32"> Removes the named action from the action map. + filename="gio/gactionmap.c" + line="109">Removes the named action from the action map. If no action of this name is in the map then nothing happens. - + a #GActionMap + filename="gio/gactionmap.c" + line="111">an action map the name of the action + filename="gio/gactionmap.c" + line="112">the name of the action @@ -3041,28 +3129,28 @@ If no action of this name is in the map then nothing happens. c:identifier="g_action_map_add_action" version="2.32"> Adds an action to the @action_map. + filename="gio/gactionmap.c" + line="88">Adds an action to the @action_map. If the action map already contains an action with the same name as @action then the old action is dropped from the action map. The action map takes its own reference on @action. - + a #GActionMap + filename="gio/gactionmap.c" + line="90">an action map a #GAction + filename="gio/gactionmap.c" + line="91">a [iface@Gio.Action] @@ -3071,13 +3159,13 @@ The action map takes its own reference on @action. c:identifier="g_action_map_add_action_entries" version="2.32"> A convenience function for creating multiple #GSimpleAction instances -and adding them to a #GActionMap. + filename="gio/gactionmap.c" + line="159">A convenience function for creating multiple [class@Gio.SimpleAction] +instances and adding them to a [iface@Gio.ActionMap]. -Each action is constructed as per one #GActionEntry. +Each action is constructed as per one [struct@Gio.ActionEntry]. -|[<!-- language="C" --> +```c static void activate_quit (GSimpleAction *simple, GVariant *parameter, @@ -3108,31 +3196,31 @@ create_action_group (void) return G_ACTION_GROUP (group); } -]| - +``` + a #GActionMap + filename="gio/gactionmap.c" + line="161">an action map a pointer to - the first item in an array of #GActionEntry structs + filename="gio/gactionmap.c" + line="162">a pointer to + the first item in an array of [struct@Gio.ActionEntry] structs the length of @entries, or -1 if @entries is %NULL-terminated + filename="gio/gactionmap.c" + line="164">the length of @entries, or -1 if @entries is `NULL`-terminated the user data for signal connections + filename="gio/gactionmap.c" + line="165">the user data for signal connections @@ -3150,28 +3238,28 @@ create_action_group (void) c:identifier="g_action_map_lookup_action" version="2.32"> Looks up the action with the name @action_name in @action_map. + filename="gio/gactionmap.c" + line="67">Looks up the action with the name @action_name in @action_map. -If no such action exists, returns %NULL. - +If no such action exists, returns `NULL`. + a #GAction, or %NULL + filename="gio/gactionmap.c" + line="76">a [iface@Gio.Action] a #GActionMap + filename="gio/gactionmap.c" + line="69">an action map the name of an action + filename="gio/gactionmap.c" + line="70">the name of an action @@ -3180,25 +3268,25 @@ If no such action exists, returns %NULL. c:identifier="g_action_map_remove_action" version="2.32"> Removes the named action from the action map. + filename="gio/gactionmap.c" + line="109">Removes the named action from the action map. If no action of this name is in the map then nothing happens. - + a #GActionMap + filename="gio/gactionmap.c" + line="111">an action map the name of the action + filename="gio/gactionmap.c" + line="112">the name of the action @@ -3207,12 +3295,12 @@ If no action of this name is in the map then nothing happens. c:identifier="g_action_map_remove_action_entries" version="2.78"> Remove actions from a #GActionMap. This is meant as the reverse of -g_action_map_add_action_entries(). + filename="gio/gactionmap.c" + line="280">Remove actions from a [iface@Gio.ActionMap]. This is meant as the reverse of +[method@Gio.ActionMap.add_action_entries]. -|[<!-- language="C" --> +```c static const GActionEntry entries[] = { { "quit", activate_quit }, { "print-string", activate_print_string, "s" } @@ -3229,31 +3317,31 @@ remove_actions (GActionMap *map) { g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries)); } -]| - +``` + The #GActionMap + filename="gio/gactionmap.c" + line="282">The [iface@Gio.ActionMap] a pointer to - the first item in an array of #GActionEntry structs + filename="gio/gactionmap.c" + line="283">a pointer to + the first item in an array of [struct@Gio.ActionEntry] structs the length of @entries, or -1 if @entries is %NULL-terminated + filename="gio/gactionmap.c" + line="285">the length of @entries, or -1 if @entries is `NULL`-terminated @@ -3264,76 +3352,88 @@ remove_actions (GActionMap *map) glib:is-gtype-struct-for="ActionMap" version="2.32"> The virtual function table for #GActionMap. - + filename="gio/gactionmap.c" + line="46">The virtual function table for [iface@Gio.ActionMap]. + + the virtual function pointer for + [method@Gio.ActionMap.lookup_action] - + a #GAction, or %NULL + filename="gio/gactionmap.c" + line="76">a [iface@Gio.Action] a #GActionMap + filename="gio/gactionmap.c" + line="69">an action map the name of an action + filename="gio/gactionmap.c" + line="70">the name of an action + the virtual function pointer for + [method@Gio.ActionMap.add_action] - + a #GActionMap + filename="gio/gactionmap.c" + line="90">an action map a #GAction + filename="gio/gactionmap.c" + line="91">a [iface@Gio.Action] + the virtual function pointer for + [method@Gio.ActionMap.remove_action] - + a #GActionMap + filename="gio/gactionmap.c" + line="111">an action map the name of the action + filename="gio/gactionmap.c" + line="112">the name of the action @@ -3347,33 +3447,40 @@ remove_actions (GActionMap *map) glib:get-type="g_app_info_get_type" glib:type-struct="AppInfoIface"> #GAppInfo and #GAppLaunchContext are used for describing and launching + filename="gio/gappinfo.c" + line="48">Information about an installed application and methods to launch +it (with file arguments). + +`GAppInfo` and `GAppLaunchContext` are used for describing and launching applications installed on the system. As of GLib 2.20, URIs will always be converted to POSIX paths -(using g_file_get_path()) when using g_app_info_launch() even if -the application requested an URI and not a POSIX path. For example -for a desktop-file based application with Exec key `totem -%U` and a single URI, `sftp://foo/file.avi`, then -`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will -only work if a set of suitable GIO extensions (such as gvfs 2.26 -compiled with FUSE support), is available and operational; if this -is not the case, the URI will be passed unmodified to the application. -Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX -path (in gvfs there's no FUSE mount for it); such URIs will be -passed unmodified to the application. - -Specifically for gvfs 2.26 and later, the POSIX URI will be mapped -back to the GIO URI in the #GFile constructors (since gvfs -implements the #GVfs extension point). As such, if the application -needs to examine the URI, it needs to use g_file_get_uri() or -similar on #GFile. In other words, an application cannot assume -that the URI passed to e.g. g_file_new_for_commandline_arg() is -equal to the result of g_file_get_uri(). The following snippet +(using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch] +even if the application requested an URI and not a POSIX path. For example +for a desktop-file based application with the following Exec key: + +``` +Exec=totem %U +``` + +and a single URI, `sftp://foo/file.avi`, then +`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will only work +if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE +support), is available and operational; if this is not the case, the URI +will be passed unmodified to the application. Some URIs, such as `mailto:`, +of course cannot be mapped to a POSIX path (in GVfs there’s no FUSE mount +for it); such URIs will be passed unmodified to the application. + +Specifically for GVfs 2.26 and later, the POSIX URI will be mapped +back to the GIO URI in the [iface@Gio.File] constructors (since GVfs +implements the GVfs extension point). As such, if the application +needs to examine the URI, it needs to use [method@Gio.File.get_uri] +or similar on [iface@Gio.File]. In other words, an application cannot +assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg] +is equal to the result of [method@Gio.File.get_uri]. The following snippet illustrates this: -|[ +```c GFile *f; char *uri; @@ -3388,39 +3495,41 @@ if (g_file_has_uri_scheme (file, "cdda")) // do something special with uri } g_object_unref (file); -]| +``` This code will work when both `cdda://sr0/Track 1.wav` and `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the -application. It should be noted that it's generally not safe +application. It should be noted that it’s generally not safe for applications to rely on the format of a particular URIs. Different launcher applications (e.g. file managers) may have different ideas of what a given URI means. - + Creates a new #GAppInfo from the given information. + filename="gio/gappinfo.c" + line="120">Creates a new [iface@Gio.AppInfo] from the given information. -Note that for @commandline, the quoting rules of the Exec key of the +Note that for @commandline, the quoting rules of the `Exec` key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the @commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from -being swallowed by Exec key unquoting. See the specification for exact quoting rules. - +being swallowed by `Exec` key unquoting. See +[the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) +for exact quoting rules. + new #GAppInfo for given command. + filename="gio/gappinfo.c" + line="138">new [iface@Gio.AppInfo] for given command. the commandline to use + filename="gio/gappinfo.c" + line="122">the command line to use the application name, or %NULL to use @commandline + filename="gio/gappinfo.c" + line="123">the application name, or `NULL` to use @commandline flags that can specify details of the created #GAppInfo + filename="gio/gappinfo.c" + line="124">flags that can specify details of the created [iface@Gio.AppInfo] Gets a list of all of the applications currently registered + filename="gio/gappinfo.c" + line="410">Gets a list of all of the applications currently registered on this system. For desktop files, this includes applications that have -`NoDisplay=true` set or are excluded from display by means -of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). -The returned list does not include applications which have -the `Hidden` key set. - +[`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) +set or are excluded from display by means of +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). +See [method@Gio.AppInfo.should_show]. + +The returned list does not include applications which have the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +set. + a newly allocated #GList of references to #GAppInfos. + filename="gio/gappinfo.c" + line="427">a newly allocated + list of references to [iface@Gio.AppInfo]s. @@ -3464,17 +3579,17 @@ the `Hidden` key set. Gets a list of all #GAppInfos for a given content type, -including the recommended and fallback #GAppInfos. See -g_app_info_get_recommended_for_type() and -g_app_info_get_fallback_for_type(). - + filename="gio/gappinfo.c" + line="482">Gets a list of all [iface@Gio.AppInfo]s for a given content type, +including the recommended and fallback [iface@Gio.AppInfo]s. See +[func@Gio.AppInfo.get_recommended_for_type] and +[func@Gio.AppInfo.get_fallback_for_type]. + #GList of #GAppInfos - for given @content_type or %NULL on error. + filename="gio/gappinfo.c" + line="491">list of + [iface@Gio.AppInfo]s for given @content_type. @@ -3482,63 +3597,67 @@ g_app_info_get_fallback_for_type(). the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="484">the content type to find a [iface@Gio.AppInfo] for + c:identifier="g_app_info_get_default_for_type" + glib:async-func="get_default_for_type_async"> Gets the default #GAppInfo for a given content type. - + filename="gio/gappinfo.c" + line="520">Gets the default [iface@Gio.AppInfo] for a given content type. + #GAppInfo for given @content_type or - %NULL on error. + filename="gio/gappinfo.c" + line="528">[iface@Gio.AppInfo] for given + @content_type or `NULL` on error. the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="522">the content type to find a [iface@Gio.AppInfo] for if %TRUE, the #GAppInfo is expected to - support URIs + filename="gio/gappinfo.c" + line="523">if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs + version="2.74" + glib:finish-func="get_default_for_type_finish" + glib:sync-func="get_default_for_type"> Asynchronously gets the default #GAppInfo for a given content type. - + filename="gio/gappinfo.c" + line="1002">Asynchronously gets the default [iface@Gio.AppInfo] for a given content +type. + the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="1004">the content type to find a [iface@Gio.AppInfo] for if %TRUE, the #GAppInfo is expected to - support URIs + filename="gio/gappinfo.c" + line="1005">if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gappinfo.c" + line="1007">a [class@Gio.Cancellable] scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="1008">a [type@Gio.AsyncReadyCallback] to call + when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gappinfo.c" + line="1010">data to pass to @callback @@ -3577,71 +3697,75 @@ g_app_info_get_fallback_for_type(). version="2.74" throws="1"> Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_type_async(). + filename="gio/gappinfo.c" + line="1125">Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_type_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. - +If no #[iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. + #GAppInfo for given @content_type or - %NULL on error. + filename="gio/gappinfo.c" + line="1135">[iface@Gio.AppInfo] for given @content_type or + `NULL` on error. a #GAsyncResult + filename="gio/gappinfo.c" + line="1127">the async result + c:identifier="g_app_info_get_default_for_uri_scheme" + glib:async-func="get_default_for_uri_scheme_async"> Gets the default application for handling URIs with -the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". - + filename="gio/gappinfo.c" + line="540">Gets the default application for handling URIs with the given URI scheme. + +A URI scheme is the initial part of the URI, up to but not including the `:`. +For example, `http`, `ftp` or `sip`. + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gappinfo.c" + line="549">[iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. a string containing a URI scheme. + filename="gio/gappinfo.c" + line="542">a string containing a URI scheme. + version="2.74" + glib:finish-func="get_default_for_uri_scheme_finish" + glib:sync-func="get_default_for_uri_scheme"> Asynchronously gets the default application for handling URIs with + filename="gio/gappinfo.c" + line="1064">Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". - +of the URI, up to but not including the `:`, e.g. `http`, +`ftp` or `sip`. + a string containing a URI scheme. + filename="gio/gappinfo.c" + line="1066">a string containing a URI scheme. optional #GCancellable object, %NULL to ignore + filename="gio/gappinfo.c" + line="1067">a [class@Gio.Cancellable] a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="1068">a [type@Gio.AsyncReadyCallback] to call + when the request is done data to pass to @callback + filename="gio/gappinfo.c" + line="1070">data to pass to @callback @@ -3680,24 +3805,25 @@ of the URI, up to but not including the ':', e.g. "http", version="2.74" throws="1"> Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_uri_scheme_async(). + filename="gio/gappinfo.c" + line="1098">Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_uri_scheme_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. - +If no [iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gappinfo.c" + line="1108">[iface@Gio.AppInfo] for given @uri_scheme or + `NULL` on error. a #GAsyncResult + filename="gio/gappinfo.c" + line="1100">the async result @@ -3706,16 +3832,16 @@ If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. Gets a list of fallback #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type -by MIME type subclassing and not directly. - + filename="gio/gappinfo.c" + line="461">Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. +those applications which claim to support the given content type by MIME +type subclassing and not directly. + #GList of #GAppInfos - for given @content_type or %NULL on error. + filename="gio/gappinfo.c" + line="469">list of [iface@Gio.AppInfo]s + for given @content_type or `NULL` on error. @@ -3723,8 +3849,8 @@ by MIME type subclassing and not directly. the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="463">the content type to find a [iface@Gio.AppInfo] for @@ -3733,19 +3859,20 @@ by MIME type subclassing and not directly. c:identifier="g_app_info_get_recommended_for_type" version="2.28"> Gets a list of recommended #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type exactly, -and not by MIME type subclassing. + filename="gio/gappinfo.c" + line="436">Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, +i.e. those applications which claim to support the given content type +exactly, and not by MIME type subclassing. + Note that the first application of the list is the last used one, i.e. -the last one for which g_app_info_set_as_last_used_for_type() has been -called. - +the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has +been called. + #GList of #GAppInfos - for given @content_type or %NULL on error. + filename="gio/gappinfo.c" + line="448">list of + [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. @@ -3753,37 +3880,37 @@ called. the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="438">the content type to find a [iface@Gio.AppInfo] for + throws="1" + glib:async-func="launch_default_for_uri_async"> Utility function that launches the default application -registered to handle the specified uri. Synchronous I/O -is done on the uri to detect the type of the file if -required. + filename="gio/gappinfo.c" + line="1152">Utility function that launches the default application registered to handle +the specified uri. Synchronous I/O is done on the uri to detect the type of +the file if required. -The D-Bus–activated applications don't have to be started if your application +The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use -g_app_info_launch_default_for_uri_async() instead. - +[func@Gio.AppInfo.launch_default_for_uri_async] instead. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="1165">`TRUE` on success, `FALSE` on error. the uri to show + filename="gio/gappinfo.c" + line="1154">the uri to show nullable="1" allow-none="1"> an optional #GAppLaunchContext + filename="gio/gappinfo.c" + line="1155">optional launch context + version="2.50" + glib:finish-func="launch_default_for_uri_finish" + glib:sync-func="launch_default_for_uri"> Async version of g_app_info_launch_default_for_uri(). + filename="gio/gappinfo.c" + line="1417">Async version of [func@Gio.AppInfo.launch_default_for_uri]. -This version is useful if you are interested in receiving -error information in the case where the application is -sandboxed and the portal may present an application chooser -dialog to the user. +This version is useful if you are interested in receiving error information +in the case where the application is sandboxed and the portal may present an +application chooser dialog to the user. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation. - + the uri to show + filename="gio/gappinfo.c" + line="1419">the uri to show nullable="1" allow-none="1"> an optional #GAppLaunchContext + filename="gio/gappinfo.c" + line="1420">optional launch context nullable="1" allow-none="1"> a #GCancellable + filename="gio/gappinfo.c" + line="1421">a [class@Gio.Cancellable] scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="1422">a [type@Gio.AsyncReadyCallback] to call + when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gappinfo.c" + line="1424">data to pass to @callback @@ -3868,20 +3997,20 @@ in receiving error information from their activation. version="2.50" throws="1"> Finishes an asynchronous launch-default-for-uri operation. - + filename="gio/gappinfo.c" + line="1479">Finishes an asynchronous launch-default-for-uri operation. + %TRUE if the launch was successful, %FALSE if @error is set + filename="gio/gappinfo.c" + line="1485">`TRUE` if the launch was successful, `FALSE` if @error is set a #GAsyncResult + filename="gio/gappinfo.c" + line="1481">the async result @@ -3890,21 +4019,21 @@ in receiving error information from their activation. c:identifier="g_app_info_reset_type_associations" version="2.20"> Removes all changes to the type associations done by -g_app_info_set_as_default_for_type(), -g_app_info_set_as_default_for_extension(), -g_app_info_add_supports_type() or -g_app_info_remove_supports_type(). - + filename="gio/gappinfo.c" + line="502">Removes all changes to the type associations done by +[method@Gio.AppInfo.set_as_default_for_type], +[method@Gio.AppInfo.set_as_default_for_extension], +[method@Gio.AppInfo.add_supports_type] or +[method@Gio.AppInfo.remove_supports_type]. + a content type + filename="gio/gappinfo.c" + line="504">a content type @@ -3913,48 +4042,48 @@ g_app_info_remove_supports_type(). invoker="add_supports_type" throws="1"> Adds a content type to the application information to indicate the + filename="gio/gappinfo.c" + line="591">Adds a content type to the application information to indicate the application is capable of opening files with the given content type. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="599">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="593">the app info a string. + filename="gio/gappinfo.c" + line="594">a string. Obtains the information whether the #GAppInfo can be deleted. -See g_app_info_delete(). - + filename="gio/gappinfo.c" + line="1498">Obtains the information whether the [iface@Gio.AppInfo] can be deleted. +See [method@Gio.AppInfo.delete]. + %TRUE if @appinfo can be deleted + filename="gio/gappinfo.c" + line="1505">`TRUE` if @appinfo can be deleted a #GAppInfo + filename="gio/gappinfo.c" + line="1500">the app info @@ -3962,95 +4091,95 @@ See g_app_info_delete(). Checks if a supported content type can be removed from an application. - + filename="gio/gappinfo.c" + line="624">Checks if a supported content type can be removed from an application. + %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. + filename="gio/gappinfo.c" + line="630">`TRUE` if it is possible to remove supported content types from a + given @appinfo, `FALSE` if not. a #GAppInfo. + filename="gio/gappinfo.c" + line="626">the app info Tries to delete a #GAppInfo. + filename="gio/gappinfo.c" + line="1525">Tries to delete a [iface@Gio.AppInfo]. On some platforms, there may be a difference between user-defined -#GAppInfos which can be deleted, and system-wide ones which cannot. -See g_app_info_can_delete(). - +[iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot. +See [method@Gio.AppInfo.can_delete]. + %TRUE if @appinfo has been deleted + filename="gio/gappinfo.c" + line="1535">`TRUE` if @appinfo has been deleted a #GAppInfo + filename="gio/gappinfo.c" + line="1527">the app info Creates a duplicate of a #GAppInfo. - + filename="gio/gappinfo.c" + line="153">Creates a duplicate of a [iface@Gio.AppInfo]. + a duplicate of @appinfo. + filename="gio/gappinfo.c" + line="159">a duplicate of @appinfo. a #GAppInfo. + filename="gio/gappinfo.c" + line="155">the app info Checks if two #GAppInfos are equal. + filename="gio/gappinfo.c" + line="173">Checks if two [iface@Gio.AppInfo]s are equal. -Note that the check *may not* compare each individual -field, and only does an identity check. In case detecting changes in the -contents is needed, program code must additionally compare relevant fields. - +Note that the check *may not* compare each individual field, and only does +an identity check. In case detecting changes in the contents is needed, +program code must additionally compare relevant fields. + %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + filename="gio/gappinfo.c" + line="184">`TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. the first #GAppInfo. + filename="gio/gappinfo.c" + line="175">the first [iface@Gio.AppInfo]. the second #GAppInfo. + filename="gio/gappinfo.c" + line="176">the second [iface@Gio.AppInfo]. @@ -4059,43 +4188,43 @@ contents is needed, program code must additionally compare relevant fields. Gets the commandline with which the application will be + filename="gio/gappinfo.c" + line="322">Gets the commandline with which the application will be started. - + a string containing the @appinfo's commandline, - or %NULL if this information is not available + filename="gio/gappinfo.c" + line="329">a string containing the @appinfo’s + commandline, or `NULL` if this information is not available a #GAppInfo + filename="gio/gappinfo.c" + line="324">the app info Gets a human-readable description of an installed application. - + filename="gio/gappinfo.c" + line="275">Gets a human-readable description of an installed application. + a string containing a description of the -application @appinfo, or %NULL if none. + filename="gio/gappinfo.c" + line="281">a string containing a description of the +application @appinfo, or `NULL` if none. a #GAppInfo. + filename="gio/gappinfo.c" + line="277">the app info @@ -4104,114 +4233,113 @@ application @appinfo, or %NULL if none. invoker="get_display_name" version="2.24"> Gets the display name of the application. The display name is often more + filename="gio/gappinfo.c" + line="248">Gets the display name of the application. The display name is often more descriptive to the user than the name itself. - + the display name of the application for @appinfo, or the name if + filename="gio/gappinfo.c" + line="255">the display name of the application for @appinfo, or the name if no display name is available. a #GAppInfo. + filename="gio/gappinfo.c" + line="250">the app info Gets the executable's name for the installed application. + filename="gio/gappinfo.c" + line="296">Gets the executable’s name for the installed application. This is intended to be used for debugging or labelling what program is going -to be run. To launch the executable, use g_app_info_launch() and related +to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related functions, rather than spawning the return value from this function. - + a string containing the @appinfo's application + filename="gio/gappinfo.c" + line="306">a string containing the @appinfo’s application binaries name a #GAppInfo + filename="gio/gappinfo.c" + line="298">the app info Gets the icon for the application. - + filename="gio/gappinfo.c" + line="713">Gets the icon for the application. + the default #GIcon for @appinfo or %NULL -if there is no default icon. + filename="gio/gappinfo.c" + line="719">the default [iface@Gio.Icon] for + @appinfo or `NULL` if there is no default icon. a #GAppInfo. + filename="gio/gappinfo.c" + line="715">the app info Gets the ID of an application. An id is a string that -identifies the application. The exact format of the id is -platform dependent. For instance, on Unix this is the -desktop file id from the xdg menu specification. + filename="gio/gappinfo.c" + line="203">Gets the ID of an application. An id is a string that identifies the +application. The exact format of the id is platform dependent. For instance, +on Unix this is the desktop file id from the xdg menu specification. -Note that the returned ID may be %NULL, depending on how -the @appinfo has been constructed. - +Note that the returned ID may be `NULL`, depending on how the @appinfo has +been constructed. + a string containing the application's ID. + filename="gio/gappinfo.c" + line="214">a string containing the application’s ID. a #GAppInfo. + filename="gio/gappinfo.c" + line="205">the app info Gets the installed name of the application. - + filename="gio/gappinfo.c" + line="228">Gets the installed name of the application. + the name of the application for @appinfo. + filename="gio/gappinfo.c" + line="234">the name of the application for @appinfo. a #GAppInfo. + filename="gio/gappinfo.c" + line="230">the app info @@ -4220,19 +4348,20 @@ the @appinfo has been constructed. invoker="get_supported_types" version="2.34"> Retrieves the list of content types that @app_info claims to support. + filename="gio/gappinfo.c" + line="680">Retrieves the list of content types that @app_info claims to support. If this information is not provided by the environment, this function -will return %NULL. +will return `NULL`. + This function does not take in consideration associations added with -g_app_info_add_supports_type(), but only those exported directly by +[method@Gio.AppInfo.add_supports_type], but only those exported directly by the application. - + - a list of content types. + filename="gio/gappinfo.c" + line="692"> + a list of content types. @@ -4240,21 +4369,21 @@ the application. a #GAppInfo that can handle files + filename="gio/gappinfo.c" + line="682">an app info that can handle files Launches the application. Passes @files to the launched application + filename="gio/gappinfo.c" + line="735">Launches the application. Passes @files to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. -To launch the application without arguments pass a %NULL @files list. +To launch the application without arguments pass a `NULL` @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is @@ -4263,11 +4392,11 @@ no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using -g_app_info_launch_uris() instead. +[method@Gio.AppInfo.launch_uris] instead. The launched application inherits the environment of the launching -process, but it can be modified with g_app_launch_context_setenv() -and g_app_launch_context_unsetenv(). +process, but it can be modified with [method@Gio.AppLaunchContext.setenv] +and [method@Gio.AppLaunchContext.unsetenv]. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and @@ -4276,18 +4405,18 @@ process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="769">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="737">the app info nullable="1" allow-none="1"> a #GList of #GFile objects + filename="gio/gappinfo.c" + line="738">a list of [iface@Gio.File] objects @@ -4306,39 +4435,42 @@ variables are also set, based on information provided in @context. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="739">the launch context - + Launches the application. This passes the @uris to the launched application + filename="gio/gappinfo.c" + line="829">Launches the application. This passes the @uris to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. -To launch the application without arguments pass a %NULL @uris list. +To launch the application without arguments pass a `NULL` @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="848">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="831">the app info nullable="1" allow-none="1"> a #GList containing URIs to launch. + filename="gio/gappinfo.c" + line="832">a list of URIs to launch. @@ -4357,32 +4489,34 @@ no way to detect this. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="833">the launch context + version="2.60" + glib:finish-func="launch_uris_finish" + glib:sync-func="launch_uris"> Async version of g_app_info_launch_uris(). + filename="gio/gappinfo.c" + line="865">Async version of [method@Gio.AppInfo.launch_uris]. The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for -g_app_info_launch_default_for_uri_async(). - +[func@Gio.AppInfo.launch_default_for_uri_async]. + a #GAppInfo + filename="gio/gappinfo.c" + line="867">the app info nullable="1" allow-none="1"> a #GList containing URIs to launch. + filename="gio/gappinfo.c" + line="868">a list of URIs to launch. @@ -4401,8 +4535,8 @@ g_app_info_launch_default_for_uri_async(). nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="869">the launch context nullable="1" allow-none="1"> a #GCancellable + filename="gio/gappinfo.c" + line="870">a [class@Gio.Cancellable] scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="871">a [type@Gio.AsyncReadyCallback] to call + when the request is done allow-none="1" closure="4"> data to pass to @callback + filename="gio/gappinfo.c" + line="873">data to pass to @callback @@ -4442,26 +4577,26 @@ g_app_info_launch_default_for_uri_async(). version="2.60" throws="1"> Finishes a g_app_info_launch_uris_async() operation. - + filename="gio/gappinfo.c" + line="915">Finishes a [method@Gio.AppInfo.launch_uris_async] operation. + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="922">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="917">the app info a #GAsyncResult + filename="gio/gappinfo.c" + line="918">the async result @@ -4470,26 +4605,26 @@ g_app_info_launch_default_for_uri_async(). invoker="remove_supports_type" throws="1"> Removes a supported type from an application, if possible. - + filename="gio/gappinfo.c" + line="649">Removes a supported type from an application, if possible. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="656">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="651">the app info a string. + filename="gio/gappinfo.c" + line="652">a string. @@ -4498,27 +4633,27 @@ g_app_info_launch_default_for_uri_async(). invoker="set_as_default_for_extension" throws="1"> Sets the application as the default handler for the given file extension. - + filename="gio/gappinfo.c" + line="560">Sets the application as the default handler for the given file extension. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="568">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="562">the app info a string containing the file extension - (without the dot). + filename="gio/gappinfo.c" + line="563">a string containing the file extension (without + the dot). @@ -4527,26 +4662,26 @@ g_app_info_launch_default_for_uri_async(). invoker="set_as_default_for_type" throws="1"> Sets the application as the default handler for a given type. - + filename="gio/gappinfo.c" + line="349">Sets the application as the default handler for a given type. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="356">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="351">the app info the content type. + filename="gio/gappinfo.c" + line="352">the content type. @@ -4555,90 +4690,90 @@ g_app_info_launch_default_for_uri_async(). invoker="set_as_last_used_for_type" throws="1"> Sets the application as the last used application for a given type. -This will make the application appear as first in the list returned -by g_app_info_get_recommended_for_type(), regardless of the default + filename="gio/gappinfo.c" + line="378">Sets the application as the last used application for a given type. This +will make the application appear as first in the list returned by +[func@Gio.AppInfo.get_recommended_for_type], regardless of the default application for that content type. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="388">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="380">the app info the content type. + filename="gio/gappinfo.c" + line="381">the content type. Checks if the application info should be shown in menus that + filename="gio/gappinfo.c" + line="946">Checks if the application info should be shown in menus that list available applications. - + %TRUE if the @appinfo should be shown, %FALSE otherwise. + filename="gio/gappinfo.c" + line="953">`TRUE` if the @appinfo should be shown, `FALSE` otherwise. a #GAppInfo. + filename="gio/gappinfo.c" + line="948">the app info Checks if the application accepts files as arguments. - + filename="gio/gappinfo.c" + line="808">Checks if the application accepts files as arguments. + %TRUE if the @appinfo supports files. + filename="gio/gappinfo.c" + line="814">`TRUE` if the @appinfo supports files. a #GAppInfo. + filename="gio/gappinfo.c" + line="810">the app info Checks if the application supports reading files and directories from URIs. - + filename="gio/gappinfo.c" + line="787">Checks if the application supports reading files and directories from URIs. + %TRUE if the @appinfo supports URIs. + filename="gio/gappinfo.c" + line="793">`TRUE` if the @appinfo supports URIs. a #GAppInfo. + filename="gio/gappinfo.c" + line="789">the app info @@ -4647,27 +4782,27 @@ list available applications. c:identifier="g_app_info_add_supports_type" throws="1"> Adds a content type to the application information to indicate the + filename="gio/gappinfo.c" + line="591">Adds a content type to the application information to indicate the application is capable of opening files with the given content type. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="599">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="593">the app info a string. + filename="gio/gappinfo.c" + line="594">a string. @@ -4676,21 +4811,21 @@ application is capable of opening files with the given content type. c:identifier="g_app_info_can_delete" version="2.20"> Obtains the information whether the #GAppInfo can be deleted. -See g_app_info_delete(). - + filename="gio/gappinfo.c" + line="1498">Obtains the information whether the [iface@Gio.AppInfo] can be deleted. +See [method@Gio.AppInfo.delete]. + %TRUE if @appinfo can be deleted + filename="gio/gappinfo.c" + line="1505">`TRUE` if @appinfo can be deleted a #GAppInfo + filename="gio/gappinfo.c" + line="1500">the app info @@ -4698,95 +4833,95 @@ See g_app_info_delete(). Checks if a supported content type can be removed from an application. - + filename="gio/gappinfo.c" + line="624">Checks if a supported content type can be removed from an application. + %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. + filename="gio/gappinfo.c" + line="630">`TRUE` if it is possible to remove supported content types from a + given @appinfo, `FALSE` if not. a #GAppInfo. + filename="gio/gappinfo.c" + line="626">the app info Tries to delete a #GAppInfo. + filename="gio/gappinfo.c" + line="1525">Tries to delete a [iface@Gio.AppInfo]. On some platforms, there may be a difference between user-defined -#GAppInfos which can be deleted, and system-wide ones which cannot. -See g_app_info_can_delete(). - +[iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot. +See [method@Gio.AppInfo.can_delete]. + %TRUE if @appinfo has been deleted + filename="gio/gappinfo.c" + line="1535">`TRUE` if @appinfo has been deleted a #GAppInfo + filename="gio/gappinfo.c" + line="1527">the app info Creates a duplicate of a #GAppInfo. - + filename="gio/gappinfo.c" + line="153">Creates a duplicate of a [iface@Gio.AppInfo]. + a duplicate of @appinfo. + filename="gio/gappinfo.c" + line="159">a duplicate of @appinfo. a #GAppInfo. + filename="gio/gappinfo.c" + line="155">the app info Checks if two #GAppInfos are equal. + filename="gio/gappinfo.c" + line="173">Checks if two [iface@Gio.AppInfo]s are equal. -Note that the check *may not* compare each individual -field, and only does an identity check. In case detecting changes in the -contents is needed, program code must additionally compare relevant fields. - +Note that the check *may not* compare each individual field, and only does +an identity check. In case detecting changes in the contents is needed, +program code must additionally compare relevant fields. + %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + filename="gio/gappinfo.c" + line="184">`TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. the first #GAppInfo. + filename="gio/gappinfo.c" + line="175">the first [iface@Gio.AppInfo]. the second #GAppInfo. + filename="gio/gappinfo.c" + line="176">the second [iface@Gio.AppInfo]. @@ -4795,43 +4930,43 @@ contents is needed, program code must additionally compare relevant fields. Gets the commandline with which the application will be + filename="gio/gappinfo.c" + line="322">Gets the commandline with which the application will be started. - + a string containing the @appinfo's commandline, - or %NULL if this information is not available + filename="gio/gappinfo.c" + line="329">a string containing the @appinfo’s + commandline, or `NULL` if this information is not available a #GAppInfo + filename="gio/gappinfo.c" + line="324">the app info Gets a human-readable description of an installed application. - + filename="gio/gappinfo.c" + line="275">Gets a human-readable description of an installed application. + a string containing a description of the -application @appinfo, or %NULL if none. + filename="gio/gappinfo.c" + line="281">a string containing a description of the +application @appinfo, or `NULL` if none. a #GAppInfo. + filename="gio/gappinfo.c" + line="277">the app info @@ -4840,114 +4975,113 @@ application @appinfo, or %NULL if none. c:identifier="g_app_info_get_display_name" version="2.24"> Gets the display name of the application. The display name is often more + filename="gio/gappinfo.c" + line="248">Gets the display name of the application. The display name is often more descriptive to the user than the name itself. - + the display name of the application for @appinfo, or the name if + filename="gio/gappinfo.c" + line="255">the display name of the application for @appinfo, or the name if no display name is available. a #GAppInfo. + filename="gio/gappinfo.c" + line="250">the app info Gets the executable's name for the installed application. + filename="gio/gappinfo.c" + line="296">Gets the executable’s name for the installed application. This is intended to be used for debugging or labelling what program is going -to be run. To launch the executable, use g_app_info_launch() and related +to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related functions, rather than spawning the return value from this function. - + a string containing the @appinfo's application + filename="gio/gappinfo.c" + line="306">a string containing the @appinfo’s application binaries name a #GAppInfo + filename="gio/gappinfo.c" + line="298">the app info Gets the icon for the application. - + filename="gio/gappinfo.c" + line="713">Gets the icon for the application. + the default #GIcon for @appinfo or %NULL -if there is no default icon. + filename="gio/gappinfo.c" + line="719">the default [iface@Gio.Icon] for + @appinfo or `NULL` if there is no default icon. a #GAppInfo. + filename="gio/gappinfo.c" + line="715">the app info Gets the ID of an application. An id is a string that -identifies the application. The exact format of the id is -platform dependent. For instance, on Unix this is the -desktop file id from the xdg menu specification. + filename="gio/gappinfo.c" + line="203">Gets the ID of an application. An id is a string that identifies the +application. The exact format of the id is platform dependent. For instance, +on Unix this is the desktop file id from the xdg menu specification. -Note that the returned ID may be %NULL, depending on how -the @appinfo has been constructed. - +Note that the returned ID may be `NULL`, depending on how the @appinfo has +been constructed. + a string containing the application's ID. + filename="gio/gappinfo.c" + line="214">a string containing the application’s ID. a #GAppInfo. + filename="gio/gappinfo.c" + line="205">the app info Gets the installed name of the application. - + filename="gio/gappinfo.c" + line="228">Gets the installed name of the application. + the name of the application for @appinfo. + filename="gio/gappinfo.c" + line="234">the name of the application for @appinfo. a #GAppInfo. + filename="gio/gappinfo.c" + line="230">the app info @@ -4956,19 +5090,20 @@ the @appinfo has been constructed. c:identifier="g_app_info_get_supported_types" version="2.34"> Retrieves the list of content types that @app_info claims to support. + filename="gio/gappinfo.c" + line="680">Retrieves the list of content types that @app_info claims to support. If this information is not provided by the environment, this function -will return %NULL. +will return `NULL`. + This function does not take in consideration associations added with -g_app_info_add_supports_type(), but only those exported directly by +[method@Gio.AppInfo.add_supports_type], but only those exported directly by the application. - + - a list of content types. + filename="gio/gappinfo.c" + line="692"> + a list of content types. @@ -4976,21 +5111,21 @@ the application. a #GAppInfo that can handle files + filename="gio/gappinfo.c" + line="682">an app info that can handle files Launches the application. Passes @files to the launched application + filename="gio/gappinfo.c" + line="735">Launches the application. Passes @files to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. -To launch the application without arguments pass a %NULL @files list. +To launch the application without arguments pass a `NULL` @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is @@ -4999,11 +5134,11 @@ no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using -g_app_info_launch_uris() instead. +[method@Gio.AppInfo.launch_uris] instead. The launched application inherits the environment of the launching -process, but it can be modified with g_app_launch_context_setenv() -and g_app_launch_context_unsetenv(). +process, but it can be modified with [method@Gio.AppLaunchContext.setenv] +and [method@Gio.AppLaunchContext.unsetenv]. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and @@ -5012,18 +5147,18 @@ process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="769">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="737">the app info nullable="1" allow-none="1"> a #GList of #GFile objects + filename="gio/gappinfo.c" + line="738">a list of [iface@Gio.File] objects @@ -5042,41 +5177,42 @@ variables are also set, based on information provided in @context. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="739">the launch context + throws="1" + glib:async-func="launch_uris_async"> Launches the application. This passes the @uris to the launched application + filename="gio/gappinfo.c" + line="829">Launches the application. This passes the @uris to the launched application as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. -To launch the application without arguments pass a %NULL @uris list. +To launch the application without arguments pass a `NULL` @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="848">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="831">the app info nullable="1" allow-none="1"> a #GList containing URIs to launch. + filename="gio/gappinfo.c" + line="832">a list of URIs to launch. @@ -5095,32 +5231,34 @@ no way to detect this. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="833">the launch context + version="2.60" + glib:finish-func="launch_uris_finish" + glib:sync-func="launch_uris"> Async version of g_app_info_launch_uris(). + filename="gio/gappinfo.c" + line="865">Async version of [method@Gio.AppInfo.launch_uris]. The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for -g_app_info_launch_default_for_uri_async(). - +[func@Gio.AppInfo.launch_default_for_uri_async]. + a #GAppInfo + filename="gio/gappinfo.c" + line="867">the app info nullable="1" allow-none="1"> a #GList containing URIs to launch. + filename="gio/gappinfo.c" + line="868">a list of URIs to launch. @@ -5139,8 +5277,8 @@ g_app_info_launch_default_for_uri_async(). nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="869">the launch context nullable="1" allow-none="1"> a #GCancellable + filename="gio/gappinfo.c" + line="870">a [class@Gio.Cancellable] scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="871">a [type@Gio.AsyncReadyCallback] to call + when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gappinfo.c" + line="873">data to pass to @callback @@ -5179,26 +5318,26 @@ g_app_info_launch_default_for_uri_async(). version="2.60" throws="1"> Finishes a g_app_info_launch_uris_async() operation. - + filename="gio/gappinfo.c" + line="915">Finishes a [method@Gio.AppInfo.launch_uris_async] operation. + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="922">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="917">the app info a #GAsyncResult + filename="gio/gappinfo.c" + line="918">the async result @@ -5207,26 +5346,26 @@ g_app_info_launch_default_for_uri_async(). c:identifier="g_app_info_remove_supports_type" throws="1"> Removes a supported type from an application, if possible. - + filename="gio/gappinfo.c" + line="649">Removes a supported type from an application, if possible. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="656">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="651">the app info a string. + filename="gio/gappinfo.c" + line="652">a string. @@ -5235,27 +5374,27 @@ g_app_info_launch_default_for_uri_async(). c:identifier="g_app_info_set_as_default_for_extension" throws="1"> Sets the application as the default handler for the given file extension. - + filename="gio/gappinfo.c" + line="560">Sets the application as the default handler for the given file extension. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="568">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="562">the app info a string containing the file extension - (without the dot). + filename="gio/gappinfo.c" + line="563">a string containing the file extension (without + the dot). @@ -5264,26 +5403,26 @@ g_app_info_launch_default_for_uri_async(). c:identifier="g_app_info_set_as_default_for_type" throws="1"> Sets the application as the default handler for a given type. - + filename="gio/gappinfo.c" + line="349">Sets the application as the default handler for a given type. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="356">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="351">the app info the content type. + filename="gio/gappinfo.c" + line="352">the content type. @@ -5292,90 +5431,90 @@ g_app_info_launch_default_for_uri_async(). c:identifier="g_app_info_set_as_last_used_for_type" throws="1"> Sets the application as the last used application for a given type. -This will make the application appear as first in the list returned -by g_app_info_get_recommended_for_type(), regardless of the default + filename="gio/gappinfo.c" + line="378">Sets the application as the last used application for a given type. This +will make the application appear as first in the list returned by +[func@Gio.AppInfo.get_recommended_for_type], regardless of the default application for that content type. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="388">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="380">the app info the content type. + filename="gio/gappinfo.c" + line="381">the content type. Checks if the application info should be shown in menus that + filename="gio/gappinfo.c" + line="946">Checks if the application info should be shown in menus that list available applications. - + %TRUE if the @appinfo should be shown, %FALSE otherwise. + filename="gio/gappinfo.c" + line="953">`TRUE` if the @appinfo should be shown, `FALSE` otherwise. a #GAppInfo. + filename="gio/gappinfo.c" + line="948">the app info Checks if the application accepts files as arguments. - + filename="gio/gappinfo.c" + line="808">Checks if the application accepts files as arguments. + %TRUE if the @appinfo supports files. + filename="gio/gappinfo.c" + line="814">`TRUE` if the @appinfo supports files. a #GAppInfo. + filename="gio/gappinfo.c" + line="810">the app info Checks if the application supports reading files and directories from URIs. - + filename="gio/gappinfo.c" + line="787">Checks if the application supports reading files and directories from URIs. + %TRUE if the @appinfo supports URIs. + filename="gio/gappinfo.c" + line="793">`TRUE` if the @appinfo supports URIs. a #GAppInfo. + filename="gio/gappinfo.c" + line="789">the app info @@ -5386,7 +5525,7 @@ list available applications. glib:get-type="g_app_info_create_flags_get_type" c:type="GAppInfoCreateFlags"> Flags used when creating a #GAppInfo. glib:nick="none" glib:name="G_APP_INFO_CREATE_NONE"> No flags. glib:nick="needs-terminal" glib:name="G_APP_INFO_CREATE_NEEDS_TERMINAL"> Application opens in a terminal window. glib:nick="supports-uris" glib:name="G_APP_INFO_CREATE_SUPPORTS_URIS"> Application supports URI arguments. glib:nick="supports-startup-notification" glib:name="G_APP_INFO_CREATE_SUPPORTS_STARTUP_NOTIFICATION"> Application supports startup notification. Since 2.26 @@ -5429,171 +5568,196 @@ list available applications. c:type="GAppInfoIface" glib:is-gtype-struct-for="AppInfo"> Application Information interface, for operating system portability. - + filename="gio/gappinfo.h" + line="49">Application Information interface, for operating system portability. + The parent interface. + filename="gio/gappinfo.h" + line="51">The parent interface. + Copies a [iface@Gio.AppInfo]. - + a duplicate of @appinfo. + filename="gio/gappinfo.c" + line="159">a duplicate of @appinfo. a #GAppInfo. + filename="gio/gappinfo.c" + line="155">the app info + Checks two [iface@Gio.AppInfo]s for equality. - + %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + filename="gio/gappinfo.c" + line="184">`TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. the first #GAppInfo. + filename="gio/gappinfo.c" + line="175">the first [iface@Gio.AppInfo]. the second #GAppInfo. + filename="gio/gappinfo.c" + line="176">the second [iface@Gio.AppInfo]. + Gets a string identifier for a [iface@Gio.AppInfo]. - + a string containing the application's ID. + filename="gio/gappinfo.c" + line="214">a string containing the application’s ID. a #GAppInfo. + filename="gio/gappinfo.c" + line="205">the app info + Gets the name of the application for a [iface@Gio.AppInfo]. - + the name of the application for @appinfo. + filename="gio/gappinfo.c" + line="234">the name of the application for @appinfo. a #GAppInfo. + filename="gio/gappinfo.c" + line="230">the app info + Gets a short description for the application described by + the [iface@Gio.AppInfo]. - + a string containing a description of the -application @appinfo, or %NULL if none. + filename="gio/gappinfo.c" + line="281">a string containing a description of the +application @appinfo, or `NULL` if none. a #GAppInfo. + filename="gio/gappinfo.c" + line="277">the app info + Gets the executable name for the [iface@Gio.AppInfo]. - + a string containing the @appinfo's application + filename="gio/gappinfo.c" + line="306">a string containing the @appinfo’s application binaries name a #GAppInfo + filename="gio/gappinfo.c" + line="298">the app info + Gets the [iface@Gio.Icon] for the [iface@Gio.AppInfo]. - + the default #GIcon for @appinfo or %NULL -if there is no default icon. + filename="gio/gappinfo.c" + line="719">the default [iface@Gio.Icon] for + @appinfo or `NULL` if there is no default icon. a #GAppInfo. + filename="gio/gappinfo.c" + line="715">the app info + Launches an application specified by the [iface@Gio.AppInfo]. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="769">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="737">the app info nullable="1" allow-none="1"> a #GList of #GFile objects + filename="gio/gappinfo.c" + line="738">a list of [iface@Gio.File] objects @@ -5612,65 +5776,76 @@ if there is no default icon. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="739">the launch context + Indicates whether the application specified supports + launching URIs. - + %TRUE if the @appinfo supports URIs. + filename="gio/gappinfo.c" + line="793">`TRUE` if the @appinfo supports URIs. a #GAppInfo. + filename="gio/gappinfo.c" + line="789">the app info + Indicates whether the application specified accepts + filename arguments. - + %TRUE if the @appinfo supports files. + filename="gio/gappinfo.c" + line="814">`TRUE` if the @appinfo supports files. a #GAppInfo. + filename="gio/gappinfo.c" + line="810">the app info + Launches an application with a list of URIs. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="848">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="831">the app info nullable="1" allow-none="1"> a #GList containing URIs to launch. + filename="gio/gappinfo.c" + line="832">a list of URIs to launch. @@ -5689,264 +5864,311 @@ if there is no default icon. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="833">the launch context + Returns whether an application should be shown (e.g. when + getting a list of installed applications). + [FreeDesktop.Org Startup Notification Specification](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - + %TRUE if the @appinfo should be shown, %FALSE otherwise. + filename="gio/gappinfo.c" + line="953">`TRUE` if the @appinfo should be shown, `FALSE` otherwise. a #GAppInfo. + filename="gio/gappinfo.c" + line="948">the app info + Sets an application as default for a given content + type. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="356">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="351">the app info the content type. + filename="gio/gappinfo.c" + line="352">the content type. + Sets an application as default for a given + file extension. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="568">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="562">the app info a string containing the file extension - (without the dot). + filename="gio/gappinfo.c" + line="563">a string containing the file extension (without + the dot). + Adds to the [iface@Gio.AppInfo] information about + supported file types. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="599">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="593">the app info a string. + filename="gio/gappinfo.c" + line="594">a string. + Checks for support for removing supported file + types from a [iface@Gio.AppInfo]. - + %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. + filename="gio/gappinfo.c" + line="630">`TRUE` if it is possible to remove supported content types from a + given @appinfo, `FALSE` if not. a #GAppInfo. + filename="gio/gappinfo.c" + line="626">the app info + Removes a supported application type from a + [iface@Gio.AppInfo]. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="656">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="651">the app info a string. + filename="gio/gappinfo.c" + line="652">a string. + Checks if a [iface@Gio.AppInfo] can be deleted. (Since 2.20) - + %TRUE if @appinfo can be deleted + filename="gio/gappinfo.c" + line="1505">`TRUE` if @appinfo can be deleted a #GAppInfo + filename="gio/gappinfo.c" + line="1500">the app info + Deletes a [iface@Gio.AppInfo]. (Since 2.20) - + %TRUE if @appinfo has been deleted + filename="gio/gappinfo.c" + line="1535">`TRUE` if @appinfo has been deleted a #GAppInfo + filename="gio/gappinfo.c" + line="1527">the app info + Gets the commandline for the [iface@Gio.AppInfo]. + (Since 2.20) - + a string containing the @appinfo's commandline, - or %NULL if this information is not available + filename="gio/gappinfo.c" + line="329">a string containing the @appinfo’s + commandline, or `NULL` if this information is not available a #GAppInfo + filename="gio/gappinfo.c" + line="324">the app info + Gets the display name for the [iface@Gio.AppInfo]. + (Since 2.24) - + the display name of the application for @appinfo, or the name if + filename="gio/gappinfo.c" + line="255">the display name of the application for @appinfo, or the name if no display name is available. a #GAppInfo. + filename="gio/gappinfo.c" + line="250">the app info + Sets the application as the last used. See + [method@Gio.AppInfo.set_as_last_used_for_type]. - + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="388">`TRUE` on success, `FALSE` on error. a #GAppInfo. + filename="gio/gappinfo.c" + line="380">the app info the content type. + filename="gio/gappinfo.c" + line="381">the content type. + Retrieves the list of content types that @app_info + claims to support. - + - a list of content types. + filename="gio/gappinfo.c" + line="692"> + a list of content types. @@ -5954,24 +6176,28 @@ no display name is available. a #GAppInfo that can handle files + filename="gio/gappinfo.c" + line="682">an app info that can handle files + Asynchronously launches an application with a list of + URIs. (Since: 2.60) - + a #GAppInfo + filename="gio/gappinfo.c" + line="867">the app info nullable="1" allow-none="1"> a #GList containing URIs to launch. + filename="gio/gappinfo.c" + line="868">a list of URIs to launch. @@ -5990,8 +6216,8 @@ no display name is available. nullable="1" allow-none="1"> a #GAppLaunchContext or %NULL + filename="gio/gappinfo.c" + line="869">the launch context nullable="1" allow-none="1"> a #GCancellable + filename="gio/gappinfo.c" + line="870">a [class@Gio.Cancellable] scope="async" closure="5"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="871">a [type@Gio.AsyncReadyCallback] to call + when the request is done allow-none="1" closure="5"> data to pass to @callback + filename="gio/gappinfo.c" + line="873">data to pass to @callback + Finishes an operation started with @launch_uris_async. + (Since: 2.60) - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gappinfo.c" + line="922">`TRUE` on successful launch, `FALSE` otherwise. a #GAppInfo + filename="gio/gappinfo.c" + line="917">the app info a #GAsyncResult + filename="gio/gappinfo.c" + line="918">the async result @@ -6061,48 +6292,55 @@ no display name is available. glib:type-name="GAppInfoMonitor" glib:get-type="g_app_info_monitor_get_type"> #GAppInfoMonitor is a very simple object used for monitoring the app + filename="gio/gappinfo.c" + line="1881">`GAppInfoMonitor` monitors application information for changes. + +`GAppInfoMonitor` is a very simple object used for monitoring the app info database for changes (newly installed or removed applications). -Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect -to the #GAppInfoMonitor::changed signal. The signal will be emitted once when +Call [func@Gio.AppInfoMonitor.get] to get a `GAppInfoMonitor` and connect +to the [signal@Gio.AppInfoMonitor::changed] signal. The signal will be emitted once when the app info database changes, and will not be emitted again until after the -next call to g_app_info_get_all() or another `g_app_info_*()` function. This -is because monitoring the app info database for changes is expensive. - -The following functions will re-arm the #GAppInfoMonitor::changed signal so -it can be emitted again: - - g_app_info_get_all() - - g_app_info_get_all_for_type() - - g_app_info_get_default_for_type() - - g_app_info_get_fallback_for_type() - - g_app_info_get_recommended_for_type() - - g_desktop_app_info_get_implementations() - - g_desktop_app_info_new() - - g_desktop_app_info_new_from_filename() - - g_desktop_app_info_new_from_keyfile() - - g_desktop_app_info_search() +next call to [func@Gio.AppInfo.get_all] or another `g_app_info_*()` function. +This is because monitoring the app info database for changes is expensive. + +The following functions will re-arm the [signal@Gio.AppInfoMonitor::changed] +signal so it can be emitted again: + + - [func@Gio.AppInfo.get_all] + - [func@Gio.AppInfo.get_all_for_type] + - [func@Gio.AppInfo.get_default_for_type] + - [func@Gio.AppInfo.get_fallback_for_type] + - [func@Gio.AppInfo.get_recommended_for_type] + - [`g_desktop_app_info_get_implementations()`](../gio-unix/type_func.DesktopAppInfo.get_implementation.html) + - [`g_desktop_app_info_new()`](../gio-unix/ctor.DesktopAppInfo.new.html) + - [`g_desktop_app_info_new_from_filename()`](../gio-unix/ctor.DesktopAppInfo.new_from_filename.html) + - [`g_desktop_app_info_new_from_keyfile()`](../gio-unix/ctor.DesktopAppInfo.new_from_keyfile.html) + - [`g_desktop_app_info_search()`](../gio-unix/type_func.DesktopAppInfo.search.html) + +The latter functions are available if using +[`GDesktopAppInfo`](../gio-unix/class.DesktopAppInfo.html) from +`gio-unix-2.0.pc` (GIR namespace `GioUnix-2.0`). In the usual case, applications should try to make note of the change -(doing things like invalidating caches) but not act on it. In -particular, applications should avoid making calls to #GAppInfo APIs +(doing things like invalidating caches) but not act on it. In +particular, applications should avoid making calls to `GAppInfo` APIs in response to the change signal, deferring these until the time that -the updated data is actually required. The exception to this case is when +the updated data is actually required. The exception to this case is when application information is actually being displayed on the screen (for example, during a search or when the list of all applications is shown). -The reason for this is that changes to the list of installed -applications often come in groups (like during system updates) and -rescanning the list on every change is pointless and expensive. +The reason for this is that changes to the list of installed applications +often come in groups (like during system updates) and rescanning the list +on every change is pointless and expensive. Gets the #GAppInfoMonitor for the current thread-default main + filename="gio/gappinfo.c" + line="1979">Gets the #GAppInfoMonitor for the current thread-default main context. -The #GAppInfoMonitor will emit a "changed" signal in the +The #GAppInfoMonitor will emit a “changed” signal in the thread-default main context whenever the list of installed applications (as reported by g_app_info_get_all()) may have changed. @@ -6112,18 +6350,18 @@ so will re-arm the signal ready to notify about the next change. You must only call g_object_unref() on the return value from under the same main context as you created it. - + a reference to a #GAppInfoMonitor + filename="gio/gappinfo.c" + line="1996">a reference to a #GAppInfoMonitor Signal emitted when the app info database changes, when applications are + filename="gio/gappinfo.c" + line="1965">Signal emitted when the app info database changes, when applications are installed or removed. @@ -6138,54 +6376,55 @@ installed or removed. glib:get-type="g_app_launch_context_get_type" glib:type-struct="AppLaunchContextClass"> Integrating the launch with the launching application. This is used to + filename="gio/gappinfo.h" + line="294">Integrating the launch with the launching application. This is used to handle for instance startup notification and launching the new application on the same screen as the launching window. - + Creates a new application launch context. This is not normally used, -instead you instantiate a subclass of this, such as #GdkAppLaunchContext. - + filename="gio/gappinfo.c" + line="1566">Creates a new application launch context. This is not normally used, +instead you instantiate a subclass of this, such as +[`GdkAppLaunchContext`](https://docs.gtk.org/gdk4/class.AppLaunchContext.html). + a #GAppLaunchContext. + filename="gio/gappinfo.c" + line="1573">a launch context. Gets the display string for the @context. This is used to ensure new + filename="gio/gappinfo.c" + line="1785">Gets the display string for the @context. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. - + a display string for the display. + filename="gio/gappinfo.c" + line="1795">a display string for the display. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1787">the launch context a #GAppInfo + filename="gio/gappinfo.c" + line="1788">the app info a #GList of #GFile objects + filename="gio/gappinfo.c" + line="1789">a list of [iface@Gio.File] objects @@ -6195,8 +6434,8 @@ application, by setting the `DISPLAY` environment variable. Initiates startup notification for the application and returns the + filename="gio/gappinfo.c" + line="1815">Initiates startup notification for the application and returns the `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation, if supported. @@ -6208,32 +6447,40 @@ Activation tokens are defined in the [XDG Activation Protocol](https://wayland.a and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). -Support for the XDG Activation Protocol was added in GLib 2.76. - +Support for the XDG Activation Protocol was added in GLib 2.76. +Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend, +the returned token will be `NULL`. + a startup notification ID for the application, or %NULL if - not supported. + filename="gio/gappinfo.c" + line="1837">a startup notification ID for the application, or `NULL` if + not supported. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1817">the launch context - + a #GAppInfo + filename="gio/gappinfo.c" + line="1818">the app info - + a #GList of #GFile objects + filename="gio/gappinfo.c" + line="1819">a list of [iface@Gio.File] objects @@ -6242,30 +6489,32 @@ Support for the XDG Activation Protocol was added in GLib 2.76. Called when an application has failed to launch, so that it can cancel -the application startup notification started in g_app_launch_context_get_startup_notify_id(). - + filename="gio/gappinfo.c" + line="1859">Called when an application has failed to launch, so that it can cancel +the application startup notification started in +[method@Gio.AppLaunchContext.get_startup_notify_id]. + a #GAppLaunchContext. + filename="gio/gappinfo.c" + line="1861">the launch context the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + filename="gio/gappinfo.c" + line="1862">the startup notification id that was returned by + [method@Gio.AppLaunchContext.get_startup_notify_id]. - + @@ -6282,7 +6531,7 @@ the application startup notification started in g_app_launch_context_get_startup - + @@ -6301,34 +6550,34 @@ the application startup notification started in g_app_launch_context_get_startup Gets the display string for the @context. This is used to ensure new + filename="gio/gappinfo.c" + line="1785">Gets the display string for the @context. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. - + a display string for the display. + filename="gio/gappinfo.c" + line="1795">a display string for the display. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1787">the launch context a #GAppInfo + filename="gio/gappinfo.c" + line="1788">the app info a #GList of #GFile objects + filename="gio/gappinfo.c" + line="1789">a list of [iface@Gio.File] objects @@ -6339,17 +6588,17 @@ application, by setting the `DISPLAY` environment variable. c:identifier="g_app_launch_context_get_environment" version="2.32"> Gets the complete environment variable list to be passed to + filename="gio/gappinfo.c" + line="1760">Gets the complete environment variable list to be passed to the child process when @context is used to launch an application. -This is a %NULL-terminated array of strings, where each string has +This is a `NULL`-terminated array of strings, where each string has the form `KEY=VALUE`. - + - the child's environment + filename="gio/gappinfo.c" + line="1769"> + the child’s environment @@ -6357,8 +6606,8 @@ the form `KEY=VALUE`. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1762">the launch context @@ -6366,8 +6615,8 @@ the form `KEY=VALUE`. Initiates startup notification for the application and returns the + filename="gio/gappinfo.c" + line="1815">Initiates startup notification for the application and returns the `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation, if supported. @@ -6379,32 +6628,40 @@ Activation tokens are defined in the [XDG Activation Protocol](https://wayland.a and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). -Support for the XDG Activation Protocol was added in GLib 2.76. - +Support for the XDG Activation Protocol was added in GLib 2.76. +Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend, +the returned token will be `NULL`. + a startup notification ID for the application, or %NULL if - not supported. + filename="gio/gappinfo.c" + line="1837">a startup notification ID for the application, or `NULL` if + not supported. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1817">the launch context - + a #GAppInfo + filename="gio/gappinfo.c" + line="1818">the app info - + a #GList of #GFile objects + filename="gio/gappinfo.c" + line="1819">a list of [iface@Gio.File] objects @@ -6414,24 +6671,26 @@ Support for the XDG Activation Protocol was added in GLib 2.76. Called when an application has failed to launch, so that it can cancel -the application startup notification started in g_app_launch_context_get_startup_notify_id(). - + filename="gio/gappinfo.c" + line="1859">Called when an application has failed to launch, so that it can cancel +the application startup notification started in +[method@Gio.AppLaunchContext.get_startup_notify_id]. + a #GAppLaunchContext. + filename="gio/gappinfo.c" + line="1861">the launch context the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + filename="gio/gappinfo.c" + line="1862">the startup notification id that was returned by + [method@Gio.AppLaunchContext.get_startup_notify_id]. @@ -6440,30 +6699,30 @@ the application startup notification started in g_app_launch_context_get_startup c:identifier="g_app_launch_context_setenv" version="2.32"> Arranges for @variable to be set to @value in the child's -environment when @context is used to launch an application. - + filename="gio/gappinfo.c" + line="1709">Arranges for @variable to be set to @value in the child’s environment when +@context is used to launch an application. + a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1711">the launch context the environment variable to set + filename="gio/gappinfo.c" + line="1712">the environment variable to set the value for to set the variable to. + filename="gio/gappinfo.c" + line="1713">the value for to set the variable to. @@ -6472,24 +6731,24 @@ environment when @context is used to launch an application. c:identifier="g_app_launch_context_unsetenv" version="2.32"> Arranges for @variable to be unset in the child's environment -when @context is used to launch an application. - + filename="gio/gappinfo.c" + line="1736">Arranges for @variable to be unset in the child’s environment when @context +is used to launch an application. + a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1738">the launch context the environment variable to remove + filename="gio/gappinfo.c" + line="1739">the environment variable to remove @@ -6503,10 +6762,10 @@ when @context is used to launch an application. The #GAppLaunchContext::launch-failed signal is emitted when a #GAppInfo launch -fails. The startup notification id is provided, so that the launcher -can cancel the startup notification. + filename="gio/gappinfo.c" + line="1598">The [signal@Gio.AppLaunchContext::launch-failed] signal is emitted when a +[iface@Gio.AppInfo] launch fails. The startup notification id is provided, +so that the launcher can cancel the startup notification. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple @@ -6517,20 +6776,20 @@ times, one for each spawned instance. the startup notification id for the failed launch + filename="gio/gappinfo.c" + line="1601">the startup notification id for the failed launch The #GAppLaunchContext::launch-started signal is emitted when a #GAppInfo is -about to be launched. If non-null the @platform_data is an -GVariant dictionary mapping strings to variants (ie `a{sv}`), which -contains additional, platform-specific data about this launch. On -UNIX, at least the `startup-notification-id` keys will be + filename="gio/gappinfo.c" + line="1620">The [signal@Gio.AppLaunchContext::launch-started] signal is emitted when a +[iface@Gio.AppInfo] is about to be launched. If non-null the +@platform_data is an GVariant dictionary mapping strings to variants +(ie `a{sv}`), which contains additional, platform-specific data about this +launch. On UNIX, at least the `startup-notification-id` keys will be present. The value of the `startup-notification-id` key (type `s`) is a startup @@ -6538,8 +6797,9 @@ notification ID corresponding to the format from the [startup-notification specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt). It allows tracking the progress of the launchee through startup. -It is guaranteed that this signal is followed by either a #GAppLaunchContext::launched or -#GAppLaunchContext::launch-failed signal. +It is guaranteed that this signal is followed by either a +[signal@Gio.AppLaunchContext::launched] or +[signal@Gio.AppLaunchContext::launch-failed] signal. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple @@ -6550,8 +6810,8 @@ times, one for each spawned instance. the #GAppInfo that is about to be launched + filename="gio/gappinfo.c" + line="1623">the [iface@Gio.AppInfo] that is about to be launched nullable="1" allow-none="1"> additional platform-specific data for this launch + filename="gio/gappinfo.c" + line="1624">additional platform-specific data for this launch The #GAppLaunchContext::launched signal is emitted when a #GAppInfo is successfully -launched. + filename="gio/gappinfo.c" + line="1660">The [signal@Gio.AppLaunchContext::launched] signal is emitted when a +[iface@Gio.AppInfo] is successfully launched. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple @@ -6580,28 +6840,29 @@ strings to variants (ie `a{sv}`), which contains additional, platform-specific data about this launch. On UNIX, at least the `pid` and `startup-notification-id` keys will be present. -Since 2.72 the `pid` may be 0 if the process id wasn't known (for +Since 2.72 the `pid` may be 0 if the process id wasn’t known (for example if the process was launched via D-Bus). The `pid` may not be set at all in subsequent releases. On Windows, `pid` is guaranteed to be valid only for the duration of the -#GAppLaunchContext::launched signal emission; after the signal is emitted, -GLib will call g_spawn_close_pid(). If you need to keep the #GPid after the -signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. +[signal@Gio.AppLaunchContext::launched] signal emission; after the signal +is emitted, GLib will call [func@GLib.spawn_close_pid]. If you need to +keep the [alias@GLib.Pid] after the signal has been emitted, then you can +duplicate `pid` using `DuplicateHandle()`. the #GAppInfo that was just launched + filename="gio/gappinfo.c" + line="1663">the [iface@Gio.AppInfo] that was just launched additional platform-specific data for this launch + filename="gio/gappinfo.c" + line="1664">additional platform-specific data for this launch @@ -6610,36 +6871,36 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + - + a display string for the display. + filename="gio/gappinfo.c" + line="1795">a display string for the display. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1787">the launch context a #GAppInfo + filename="gio/gappinfo.c" + line="1788">the app info a #GList of #GFile objects + filename="gio/gappinfo.c" + line="1789">a list of [iface@Gio.File] objects @@ -6649,31 +6910,37 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + a startup notification ID for the application, or %NULL if - not supported. + filename="gio/gappinfo.c" + line="1837">a startup notification ID for the application, or `NULL` if + not supported. a #GAppLaunchContext + filename="gio/gappinfo.c" + line="1817">the launch context - + a #GAppInfo + filename="gio/gappinfo.c" + line="1818">the app info - + a #GList of #GFile objects + filename="gio/gappinfo.c" + line="1819">a list of [iface@Gio.File] objects @@ -6683,21 +6950,22 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + a #GAppLaunchContext. + filename="gio/gappinfo.c" + line="1861">the launch context the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + filename="gio/gappinfo.c" + line="1862">the startup notification id that was returned by + [method@Gio.AppLaunchContext.get_startup_notify_id]. @@ -6705,7 +6973,7 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + @@ -6724,7 +6992,7 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + @@ -6743,7 +7011,7 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + @@ -6751,7 +7019,7 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + @@ -6759,7 +7027,7 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - + @@ -6770,7 +7038,7 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. c:type="GAppLaunchContextPrivate" disguised="1" opaque="1"> - + A #GApplication is the foundation of an application. It wraps some + filename="gio/gapplication.c" + line="48">`GApplication` is the core class for application support. + +A `GApplication` is the foundation of an application. It wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as -#GtkApplication or #MxApplication. In general, you should not use +`GtkApplication` or `MxApplication`. In general, you should not use this class outside of a higher level framework. -GApplication provides convenient life cycle management by maintaining +`GApplication` provides convenient life-cycle management by maintaining a "use count" for the primary application instance. The use count can -be changed using g_application_hold() and g_application_release(). If -it drops to zero, the application exits. Higher-level classes such as -#GtkApplication employ the use count to ensure that the application -stays alive as long as it has any opened windows. +be changed using [method@Gio.Application.hold] and +[method@Gio.Application.release]. If it drops to zero, the application +exits. Higher-level classes such as `GtkApplication` employ the use count +to ensure that the application stays alive as long as it has any opened +windows. -Another feature that GApplication (optionally) provides is process +Another feature that `GApplication` (optionally) provides is process uniqueness. Applications can make use of this functionality by providing a unique application ID. If given, only one application with this ID can be running at a time per session. The session @@ -6807,17 +7078,17 @@ called the "primary instance"; for non-unique applications this is always the current instance. On Linux, the D-Bus session bus is used for communication. -The use of #GApplication differs from some other commonly-used +The use of `GApplication` differs from some other commonly-used uniqueness libraries (such as libunique) in important ways. The application is not expected to manually register itself and check if it is the primary instance. Instead, the main() function of a -#GApplication should do very little more than instantiating the +`GApplication` should do very little more than instantiating the application instance, possibly connecting signal handlers, then -calling g_application_run(). All checks for uniqueness are done +calling [method@Gio.Application.run]. All checks for uniqueness are done internally. If the application is the primary instance then the startup signal is emitted and the mainloop runs. If the application is not the primary instance then a signal is sent to the primary -instance and g_application_run() promptly returns. See the code +instance and [method@Gio.Application.run] promptly returns. See the code examples below. If used, the expected form of an application identifier is the @@ -6825,35 +7096,36 @@ same as that of a [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, `org._7_zip.Archiver`. -For details on valid application identifiers, see g_application_id_is_valid(). +For details on valid application identifiers, see [func@Gio.Application.id_is_valid]. On Linux, the application identifier is claimed as a well-known bus name -on the user's session bus. This means that the uniqueness of your -application is scoped to the current session. It also means that your +on the user's session bus. This means that the uniqueness of your +application is scoped to the current session. It also means that your application may provide additional services (through registration of other -object paths) at that bus name. The registration of these object paths -should be done with the shared GDBus session bus. Note that due to the +object paths) at that bus name. The registration of these object paths +should be done with the shared GDBus session bus. Note that due to the internal architecture of GDBus, method calls can be dispatched at any time -(even if a main loop is not running). For this reason, you must ensure that +(even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before #GApplication attempts to acquire the bus name of your application (which happens in -g_application_register()). Unfortunately, this means that you cannot use -g_application_get_is_remote() to decide if you want to register object paths. +[method@Gio.Application.register]). Unfortunately, this means that you cannot +use [property@Gio.Application:is-remote] to decide if you want to register +object paths. -GApplication also implements the #GActionGroup and #GActionMap +`GApplication` also implements the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] interfaces and lets you easily export actions by adding them with -g_action_map_add_action(). When invoking an action by calling -g_action_group_activate_action() on the application, it is always +[method@Gio.ActionMap.add_action]. When invoking an action by calling +[method@Gio.ActionGroup.activate_action] on the application, it is always invoked in the primary instance. The actions are also exported on -the session bus, and GIO provides the #GDBusActionGroup wrapper to -conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper -for remote access to exported #GMenuModels. +the session bus, and GIO provides the [class@Gio.DBusActionGroup] wrapper to +conveniently access them remotely. GIO provides a [class@Gio.DBusMenuModel] wrapper +for remote access to exported [class@Gio.MenuModel]s. Note: Due to the fact that actions are exported on the session bus, using `maybe` parameters is not supported, since D-Bus does not support `maybe` types. -There is a number of different entry points into a GApplication: +There is a number of different entry points into a `GApplication`: - via 'Activate' (i.e. just starting the application) @@ -6863,61 +7135,62 @@ There is a number of different entry points into a GApplication: - via activating an action -The #GApplication::startup signal lets you handle the application +The [signal@Gio.Application::startup] signal lets you handle the application initialization for all of these in a single place. Regardless of which of these entry points is used to start the -application, GApplication passes some ‘platform data’ from the +application, `GApplication` passes some ‘platform data’ from the launching instance to the primary instance, in the form of a -#GVariant dictionary mapping strings to variants. To use platform -data, override the @before_emit or @after_emit virtual functions -in your #GApplication subclass. When dealing with -#GApplicationCommandLine objects, the platform data is -directly available via g_application_command_line_get_cwd(), -g_application_command_line_get_environ() and -g_application_command_line_get_platform_data(). +[struct@GLib.Variant] dictionary mapping strings to variants. To use platform +data, override the [vfunc@Gio.Application.before_emit] or +[vfunc@Gio.Application.after_emit] virtual functions +in your `GApplication` subclass. When dealing with +[class@Gio.ApplicationCommandLine] objects, the platform data is +directly available via [method@Gio.ApplicationCommandLine.get_cwd], +[method@Gio.ApplicationCommandLine.get_environ] and +[method@Gio.ApplicationCommandLine.get_platform_data]. As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory (key -"cwd"), and optionally the environment (ie the set of environment -variables and their values) of the calling process (key "environ"). +`cwd`), and optionally the environment (ie the set of environment +variables and their values) of the calling process (key `environ`). The environment is only added to the platform data if the -%G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses -can add their own platform data by overriding the @add_platform_data -virtual function. For instance, #GtkApplication adds startup notification -data in this way. +`G_APPLICATION_SEND_ENVIRONMENT` flag is set. `GApplication` subclasses +can add their own platform data by overriding the +[vfunc@Gio.Application.add_platform_data] virtual function. For instance, +`GtkApplication` adds startup notification data in this way. To parse commandline arguments you may handle the -#GApplication::command-line signal or override the local_command_line() -vfunc, to parse them in either the primary instance or the local instance, -respectively. +[signal@Gio.Application::command-line] signal or override the +[vfunc@Gio.Application.local_command_line] virtual function, to parse them in +either the primary instance or the local instance, respectively. -For an example of opening files with a GApplication, see +For an example of opening files with a `GApplication`, see [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c). -For an example of using actions with GApplication, see +For an example of using actions with `GApplication`, see [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c). -For an example of using extra D-Bus hooks with GApplication, see +For an example of using extra D-Bus hooks with `GApplication`, see [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). - + Creates a new #GApplication instance. + filename="gio/gapplication.c" + line="1869">Creates a new #GApplication instance. If non-%NULL, the application id must be valid. See g_application_id_is_valid(). If no application ID is given then some features of #GApplication (most notably application uniqueness) will be disabled. - + a new #GApplication instance + filename="gio/gapplication.c" + line="1882">a new #GApplication instance @@ -6926,14 +7199,14 @@ If no application ID is given then some features of #GApplication nullable="1" allow-none="1"> the application id + filename="gio/gapplication.c" + line="1871">the application id the application flags + filename="gio/gapplication.c" + line="1872">the application flags @@ -6942,26 +7215,26 @@ If no application ID is given then some features of #GApplication c:identifier="g_application_get_default" version="2.32"> Returns the default #GApplication instance for this process. + filename="gio/gapplication.c" + line="2898">Returns the default #GApplication instance for this process. Normally there is only one #GApplication per process and it becomes the default when it is created. You can exercise more control over this by using g_application_set_default(). If there is no default application then %NULL is returned. - + the default application for this process, or %NULL + filename="gio/gapplication.c" + line="2909">the default application for this process, or %NULL Checks if @application_id is a valid application identifier. + filename="gio/gapplication.c" + line="1809">Checks if @application_id is a valid application identifier. A valid ID is required for calls to g_application_new() and g_application_set_application_id(). @@ -7006,46 +7279,50 @@ hyphen/minus characters they should be replaced by underscores, and if it contains leading digits they should be escaped by prepending an underscore. For example, if the owner of 7-zip.org used an application identifier for an archiving application, it might be named `org._7_zip.Archiver`. - + %TRUE if @application_id is valid + filename="gio/gapplication.c" + line="1859">%TRUE if @application_id is valid a potential application identifier + filename="gio/gapplication.c" + line="1811">a potential application identifier Activates the application. + filename="gio/gapplication.c" + line="2430">Activates the application. In essence, this results in the #GApplication::activate signal being emitted in the primary instance. The application must be registered before calling this function. - + a #GApplication + filename="gio/gapplication.c" + line="2432">a #GApplication - + invoked (locally) to add 'platform data' to be sent to + the primary instance when activating, opening or invoking actions + @@ -7059,7 +7336,12 @@ The application must be registered before calling this function. - + invoked on the primary instance after 'activate', 'open', + 'command-line' or any action invocation, gets the 'platform data' from + the calling instance + @@ -7073,7 +7355,12 @@ The application must be registered before calling this function. - + invoked on the primary instance before 'activate', 'open', + 'command-line' or any action invocation, gets the 'platform data' from + the calling instance + @@ -7087,7 +7374,11 @@ The application must be registered before calling this function. - + invoked on the primary instance when a command-line is + not handled locally + @@ -7102,7 +7393,16 @@ The application must be registered before calling this function. - + invoked locally during registration, if the application is + using its D-Bus backend. You can use this to export extra objects on the + bus, that need to exist before the application tries to own the bus name. + The function is passed the #GDBusConnection to to session bus, and the + object path that #GApplication will use to export its D-Bus API. + If this function returns %TRUE, registration will proceed; otherwise + registration will abort. Since: 2.34 + @@ -7119,7 +7419,12 @@ The application must be registered before calling this function. - + invoked locally during unregistration, if the application + is using its D-Bus backend. Use this to undo anything done by + the @dbus_register vfunc. Since: 2.34 + @@ -7136,7 +7441,11 @@ The application must be registered before calling this function. - + invoked locally after the parsing of the commandline + options has occurred. Since: 2.40 + @@ -7151,7 +7460,7 @@ The application must be registered before calling this function. This virtual function is always invoked in the local instance. It gets passed a pointer to a %NULL-terminated copy of @argv and is expected to remove arguments that it handled (shifting up remaining @@ -7162,17 +7471,17 @@ variable which can used to set the exit status that is returned from g_application_run(). See g_application_run() for more details on #GApplication startup. - + %TRUE if the commandline has been completely handled a #GApplication @@ -7181,7 +7490,7 @@ See g_application_run() for more details on #GApplication startup. caller-allocates="0" transfer-ownership="full"> array of command line arguments @@ -7192,14 +7501,17 @@ See g_application_run() for more details on #GApplication startup. caller-allocates="0" transfer-ownership="full"> exit status to fill after processing the command line. - + invoked when another instance is taking over the name. Since: 2.60 + @@ -7211,8 +7523,8 @@ See g_application_run() for more details on #GApplication startup. Opens the given files. + filename="gio/gapplication.c" + line="2457">Opens the given files. In essence, this results in the #GApplication::open signal being emitted in the primary instance. @@ -7226,41 +7538,46 @@ for this functionality, you should use "". The application must be registered before calling this function and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - + a #GApplication + filename="gio/gapplication.c" + line="2459">a #GApplication an array of #GFiles to open + filename="gio/gapplication.c" + line="2460">an array of #GFiles to open the length of the @files array + filename="gio/gapplication.c" + line="2461">the length of the @files array a hint (or ""), but never %NULL + filename="gio/gapplication.c" + line="2462">a hint (or ""), but never %NULL - + Used to be invoked on the primary instance when the use + count of the application drops to zero (and after any inactivity + timeout, if requested). Not used anymore since 2.32 + @@ -7271,7 +7588,13 @@ and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - + Used to be invoked on the primary instance from + g_application_run() if the use-count is non-zero. Since 2.32, + GApplication is iterating the main context directly and is not + using @run_mainloop anymore + @@ -7282,7 +7605,11 @@ and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - + invoked only on the registered primary instance immediately + after the main loop terminates + @@ -7293,7 +7620,10 @@ and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - + invoked on the primary instance immediately after registration + @@ -7307,22 +7637,22 @@ and it must have the %G_APPLICATION_HANDLES_OPEN flag set. c:identifier="g_application_activate" version="2.28"> Activates the application. + filename="gio/gapplication.c" + line="2430">Activates the application. In essence, this results in the #GApplication::activate signal being emitted in the primary instance. The application must be registered before calling this function. - + a #GApplication + filename="gio/gapplication.c" + line="2432">a #GApplication @@ -7331,8 +7661,8 @@ The application must be registered before calling this function. c:identifier="g_application_add_main_option" version="2.42"> Add an option to be handled by @application. + filename="gio/gapplication.c" + line="768">Add an option to be handled by @application. Calling this function is the equivalent of calling g_application_add_main_option_entries() with a single #GOptionEntry @@ -7345,45 +7675,45 @@ be sent to the primary instance. See g_application_add_main_option_entries() for more details. See #GOptionEntry for more documentation of the arguments. - + the #GApplication + filename="gio/gapplication.c" + line="770">the #GApplication the long name of an option used to specify it in a commandline + filename="gio/gapplication.c" + line="771">the long name of an option used to specify it in a commandline the short name of an option + filename="gio/gapplication.c" + line="772">the short name of an option flags from #GOptionFlags + filename="gio/gapplication.c" + line="773">flags from #GOptionFlags the type of the option, as a #GOptionArg + filename="gio/gapplication.c" + line="774">the type of the option, as a #GOptionArg the description for the option in `--help` output + filename="gio/gapplication.c" + line="775">the description for the option in `--help` output nullable="1" allow-none="1"> the placeholder to use for the extra argument + filename="gio/gapplication.c" + line="776">the placeholder to use for the extra argument parsed by the option in `--help` output @@ -7402,8 +7732,8 @@ See #GOptionEntry for more documentation of the arguments. c:identifier="g_application_add_main_option_entries" version="2.40"> Adds main option entries to be handled by @application. + filename="gio/gapplication.c" + line="672">Adds main option entries to be handled by @application. This function is comparable to g_option_context_add_main_entries(). @@ -7437,8 +7767,8 @@ This function is new in GLib 2.40. Before then, the only real choice was to send all of the commandline arguments (options and all) to the primary instance for handling. #GApplication ignored them completely on the local side. Calling this function "opts in" to the new -behaviour, and in particular, means that unrecognised options will be -treated as errors. Unrecognised options have never been ignored when +behaviour, and in particular, means that unrecognized options will be +treated as errors. Unrecognized options have never been ignored when %G_APPLICATION_HANDLES_COMMAND_LINE is unset. If #GApplication::handle-local-options needs to see the list of @@ -7459,22 +7789,22 @@ the options with g_variant_dict_lookup(): - for %G_OPTION_ARG_FILENAME, use `^&ay` - for %G_OPTION_ARG_STRING_ARRAY, use `^a&s` - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay` - + a #GApplication + filename="gio/gapplication.c" + line="674">a #GApplication a - %NULL-terminated list of #GOptionEntrys + filename="gio/gapplication.c" + line="675">the + main options for the application @@ -7485,8 +7815,8 @@ the options with g_variant_dict_lookup(): c:identifier="g_application_add_option_group" version="2.40"> Adds a #GOptionGroup to the commandline handling of @application. + filename="gio/gapplication.c" + line="826">Adds a #GOptionGroup to the commandline handling of @application. This function is comparable to g_option_context_add_group(). @@ -7509,23 +7839,23 @@ on future runs will have no effect on the existing primary instance. Calling this function will cause the options in the supplied option group to be parsed, but it does not cause you to be "opted in" to the -new functionality whereby unrecognised options are rejected even if +new functionality whereby unrecognized options are rejected even if %G_APPLICATION_HANDLES_COMMAND_LINE was given. - + the #GApplication + filename="gio/gapplication.c" + line="828">the #GApplication a #GOptionGroup + filename="gio/gapplication.c" + line="829">a #GOptionGroup @@ -7534,34 +7864,34 @@ new functionality whereby unrecognised options are rejected even if c:identifier="g_application_bind_busy_property" version="2.44"> Marks @application as busy (see g_application_mark_busy()) while + filename="gio/gapplication.c" + line="3191">Marks @application as busy (see g_application_mark_busy()) while @property on @object is %TRUE. The binding holds a reference to @application while it is active, but not to @object. Instead, the binding is destroyed when @object is finalized. - + a #GApplication + filename="gio/gapplication.c" + line="3193">a #GApplication a #GObject + filename="gio/gapplication.c" + line="3194">a #GObject the name of a boolean property of @object + filename="gio/gapplication.c" + line="3195">the name of a boolean property of @object @@ -7571,20 +7901,20 @@ finalized. glib:get-property="application-id" version="2.28"> Gets the unique identifier for @application. - + filename="gio/gapplication.c" + line="1897">Gets the unique identifier for @application. + the identifier for @application, owned by @application + filename="gio/gapplication.c" + line="1903">the identifier for @application, owned by @application a #GApplication + filename="gio/gapplication.c" + line="1899">a #GApplication @@ -7593,8 +7923,8 @@ finalized. c:identifier="g_application_get_dbus_connection" version="2.34"> Gets the #GDBusConnection being used by the application, or %NULL. + filename="gio/gapplication.c" + line="2220">Gets the #GDBusConnection being used by the application, or %NULL. If #GApplication is using its D-Bus backend then this function will return the #GDBusConnection being used for uniqueness and @@ -7607,18 +7937,18 @@ normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See g_application_get_is_registered(). - + a #GDBusConnection, or %NULL + filename="gio/gapplication.c" + line="2238">a #GDBusConnection, or %NULL a #GApplication + filename="gio/gapplication.c" + line="2222">a #GApplication @@ -7627,8 +7957,8 @@ registered. See g_application_get_is_registered(). c:identifier="g_application_get_dbus_object_path" version="2.34"> Gets the D-Bus object path being used by the application, or %NULL. + filename="gio/gapplication.c" + line="2251">Gets the D-Bus object path being used by the application, or %NULL. If #GApplication is using its D-Bus backend then this function will return the D-Bus object path that #GApplication is using. If the @@ -7642,18 +7972,18 @@ normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See g_application_get_is_registered(). - + the object path, or %NULL + filename="gio/gapplication.c" + line="2270">the object path, or %NULL a #GApplication + filename="gio/gapplication.c" + line="2253">a #GApplication @@ -7663,22 +7993,22 @@ registered. See g_application_get_is_registered(). glib:get-property="flags" version="2.28"> Gets the flags for @application. + filename="gio/gapplication.c" + line="1992">Gets the flags for @application. See #GApplicationFlags. - + the flags for @application + filename="gio/gapplication.c" + line="2000">the flags for @application a #GApplication + filename="gio/gapplication.c" + line="1994">a #GApplication @@ -7688,23 +8018,23 @@ See #GApplicationFlags. glib:get-property="inactivity-timeout" version="2.28"> Gets the current inactivity timeout for the application. + filename="gio/gapplication.c" + line="2120">Gets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running. - + the timeout, in milliseconds + filename="gio/gapplication.c" + line="2129">the timeout, in milliseconds a #GApplication + filename="gio/gapplication.c" + line="2122">a #GApplication @@ -7714,21 +8044,21 @@ g_application_release() before the application stops running. glib:get-property="is-busy" version="2.44"> Gets the application's current busy state, as set through + filename="gio/gapplication.c" + line="3032">Gets the application's current busy state, as set through g_application_mark_busy() or g_application_bind_busy_property(). - + %TRUE if @application is currently marked as busy + filename="gio/gapplication.c" + line="3039">%TRUE if @application is currently marked as busy a #GApplication + filename="gio/gapplication.c" + line="3034">a #GApplication @@ -7738,23 +8068,23 @@ g_application_mark_busy() or g_application_bind_busy_property(). glib:get-property="is-registered" version="2.28"> Checks if @application is registered. + filename="gio/gapplication.c" + line="2171">Checks if @application is registered. An application is registered if g_application_register() has been successfully called. - + %TRUE if @application is registered + filename="gio/gapplication.c" + line="2180">%TRUE if @application is registered a #GApplication + filename="gio/gapplication.c" + line="2173">a #GApplication @@ -7764,8 +8094,8 @@ successfully called. glib:get-property="is-remote" version="2.28"> Checks if @application is remote. + filename="gio/gapplication.c" + line="2192">Checks if @application is remote. If @application is remote then it means that another instance of application already exists (the 'primary' instance). Calls to @@ -7775,18 +8105,18 @@ performed by the primary instance. The value of this property cannot be accessed before g_application_register() has been called. See g_application_get_is_registered(). - + %TRUE if @application is remote + filename="gio/gapplication.c" + line="2207">%TRUE if @application is remote a #GApplication + filename="gio/gapplication.c" + line="2194">a #GApplication @@ -7796,45 +8126,68 @@ g_application_get_is_registered(). glib:get-property="resource-base-path" version="2.42"> Gets the resource base path of @application. + filename="gio/gapplication.c" + line="2042">Gets the resource base path of @application. See g_application_set_resource_base_path() for more information. - + the base resource path, if one is set + filename="gio/gapplication.c" + line="2050">the base resource path, if one is set a #GApplication + filename="gio/gapplication.c" + line="2044">a #GApplication + + + + + + Gets the version of @application. + + + the version of @application + + + + + a #GApplication Increases the use count of @application. + filename="gio/gapplication.c" + line="2368">Increases the use count of @application. Use this function to indicate that the application has a reason to continue to run. For example, g_application_hold() is called by GTK when a toplevel window is on the screen. To cancel the hold, call g_application_release(). - + a #GApplication + filename="gio/gapplication.c" + line="2370">a #GApplication @@ -7843,8 +8196,8 @@ To cancel the hold, call g_application_release(). c:identifier="g_application_mark_busy" version="2.38"> Increases the busy count of @application. + filename="gio/gapplication.c" + line="2966">Increases the busy count of @application. Use this function to indicate that the application is busy, for instance while a long running operation is pending. @@ -7856,23 +8209,23 @@ spinner). To cancel the busy indication, use g_application_unmark_busy(). The application must be registered before calling this function. - + a #GApplication + filename="gio/gapplication.c" + line="2968">a #GApplication Opens the given files. + filename="gio/gapplication.c" + line="2457">Opens the given files. In essence, this results in the #GApplication::open signal being emitted in the primary instance. @@ -7886,43 +8239,43 @@ for this functionality, you should use "". The application must be registered before calling this function and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - + a #GApplication + filename="gio/gapplication.c" + line="2459">a #GApplication an array of #GFiles to open + filename="gio/gapplication.c" + line="2460">an array of #GFiles to open the length of the @files array + filename="gio/gapplication.c" + line="2461">the length of the @files array a hint (or ""), but never %NULL + filename="gio/gapplication.c" + line="2462">a hint (or ""), but never %NULL Immediately quits the application. + filename="gio/gapplication.c" + line="2938">Immediately quits the application. Upon return to the mainloop, g_application_run() will return, calling only the 'shutdown' function before doing so. @@ -7935,15 +8288,15 @@ through gtk_application_add_window().) The result of calling g_application_run() again after it returns is unspecified. - + a #GApplication + filename="gio/gapplication.c" + line="2940">a #GApplication @@ -7953,8 +8306,8 @@ unspecified. version="2.28" throws="1"> Attempts registration of the application. + filename="gio/gapplication.c" + line="2285">Attempts registration of the application. This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing @@ -7984,18 +8337,18 @@ is set appropriately. Note: the return value of this function is not an indicator that this instance is or is not the primary instance of the application. See g_application_get_is_remote() for that. - + %TRUE if registration succeeded + filename="gio/gapplication.c" + line="2322">%TRUE if registration succeeded a #GApplication + filename="gio/gapplication.c" + line="2287">a #GApplication nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gapplication.c" + line="2288">a #GCancellable, or %NULL Decrease the use count of @application. + filename="gio/gapplication.c" + line="2405">Decrease the use count of @application. When the use count reaches zero, the application will stop running. Never call this function except to cancel the effect of a previous call to g_application_hold(). - + a #GApplication + filename="gio/gapplication.c" + line="2407">a #GApplication Runs the application. + filename="gio/gapplication.c" + line="2503">Runs the application. This function is intended to be run from main() and its return value is intended to be returned by main(). Although you are expected to pass @@ -8109,24 +8462,24 @@ approach is suitable for use by most graphical applications but should not be used from applications like editors that need precise control over when processes invoked via the commandline will exit and what their exit status will be. - + the exit status + filename="gio/gapplication.c" + line="2586">the exit status a #GApplication + filename="gio/gapplication.c" + line="2505">a #GApplication the argc from main() (or 0 if @argv is %NULL) + filename="gio/gapplication.c" + line="2506">the argc from main() (or 0 if @argv is %NULL) nullable="1" allow-none="1"> + filename="gio/gapplication.c" + line="2507"> the argv from main(), or %NULL @@ -8147,8 +8500,8 @@ what their exit status will be. c:identifier="g_application_send_notification" version="2.40"> Sends a notification on behalf of @application to the desktop shell. + filename="gio/gapplication.c" + line="3053">Sends a notification on behalf of @application to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all. @@ -8169,20 +8522,23 @@ replaced with @notification and shown again as if it was a new notification. This works even for notifications sent from a previous execution of the application, as long as @id is the same string. -@id may be %NULL, but it is impossible to replace or withdraw +@id may be `NULL`, but it is impossible to replace or withdraw notifications without an id. If @notification is no longer relevant, it can be withdrawn with -g_application_withdraw_notification(). - +[method@Gio.Application.withdraw_notification]. + +It is an error to call this function if @application has no +application ID. + a #GApplication + filename="gio/gapplication.c" + line="3055">a #GApplication nullable="1" allow-none="1"> id of the notification, or %NULL + filename="gio/gapplication.c" + line="3056">id of the notification, or %NULL the #GNotification to send + filename="gio/gapplication.c" + line="3057">the #GNotification to send @@ -8209,23 +8565,23 @@ g_application_withdraw_notification(). deprecated="1" deprecated-version="2.32"> This used to be how actions were associated with a #GApplication. + filename="gio/gapplication.c" + line="1299">This used to be how actions were associated with a #GApplication. Now there is #GActionMap for that. Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead. - + a #GApplication + filename="gio/gapplication.c" + line="1301">a #GApplication nullable="1" allow-none="1"> a #GActionGroup, or %NULL + filename="gio/gapplication.c" + line="1302">a #GActionGroup, or %NULL @@ -8244,23 +8600,23 @@ action group), so you should really use #GActionMap instead. glib:set-property="application-id" version="2.28"> Sets the unique identifier for @application. + filename="gio/gapplication.c" + line="1915">Sets the unique identifier for @application. The application id can only be modified if @application has not yet been registered. If non-%NULL, the application id must be valid. See g_application_id_is_valid(). - + a #GApplication + filename="gio/gapplication.c" + line="1917">a #GApplication nullable="1" allow-none="1"> the identifier for @application + filename="gio/gapplication.c" + line="1918">the identifier for @application @@ -8278,14 +8634,14 @@ g_application_id_is_valid(). c:identifier="g_application_set_default" version="2.32"> Sets or unsets the default application for the process, as returned + filename="gio/gapplication.c" + line="2919">Sets or unsets the default application for the process, as returned by g_application_get_default(). This function does not take its own reference on @application. If @application is destroyed then the default application will revert back to %NULL. - + @@ -8295,8 +8651,8 @@ back to %NULL. nullable="1" allow-none="1"> the application to set as default, or %NULL + filename="gio/gapplication.c" + line="2921">the application to set as default, or %NULL @@ -8306,28 +8662,28 @@ back to %NULL. glib:set-property="flags" version="2.28"> Sets the flags for @application. + filename="gio/gapplication.c" + line="2012">Sets the flags for @application. The flags can only be modified if @application has not yet been registered. See #GApplicationFlags. - + a #GApplication + filename="gio/gapplication.c" + line="2014">a #GApplication the flags for @application + filename="gio/gapplication.c" + line="2015">the flags for @application @@ -8337,8 +8693,8 @@ See #GApplicationFlags. glib:set-property="inactivity-timeout" version="2.28"> Sets the current inactivity timeout for the application. + filename="gio/gapplication.c" + line="2141">Sets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running. @@ -8346,21 +8702,21 @@ g_application_release() before the application stops running. This call has no side effects of its own. The value set here is only used for next time g_application_release() drops the use count to zero. Any timeouts currently in progress are not impacted. - + a #GApplication + filename="gio/gapplication.c" + line="2143">a #GApplication the timeout, in milliseconds + filename="gio/gapplication.c" + line="2144">the timeout, in milliseconds @@ -8369,19 +8725,19 @@ zero. Any timeouts currently in progress are not impacted. c:identifier="g_application_set_option_context_description" version="2.56"> Adds a description to the @application option context. + filename="gio/gapplication.c" + line="916">Adds a description to the @application option context. See g_option_context_set_description() for more information. - + the #GApplication + filename="gio/gapplication.c" + line="918">the #GApplication nullable="1" allow-none="1"> a string to be shown in `--help` output + filename="gio/gapplication.c" + line="919">a string to be shown in `--help` output after the list of options, or %NULL @@ -8400,22 +8756,22 @@ See g_option_context_set_description() for more information. c:identifier="g_application_set_option_context_parameter_string" version="2.56"> Sets the parameter string to be used by the commandline handling of @application. + filename="gio/gapplication.c" + line="869">Sets the parameter string to be used by the commandline handling of @application. This function registers the argument to be passed to g_option_context_new() when the internal #GOptionContext of @application is created. See g_option_context_new() for more information about @parameter_string. - + the #GApplication + filename="gio/gapplication.c" + line="871">the #GApplication nullable="1" allow-none="1"> a string which is displayed + filename="gio/gapplication.c" + line="872">a string which is displayed in the first line of `--help` output, after the usage summary `programname [OPTION...]`. @@ -8434,19 +8790,19 @@ See g_option_context_new() for more information about @parameter_string. c:identifier="g_application_set_option_context_summary" version="2.56"> Adds a summary to the @application option context. + filename="gio/gapplication.c" + line="894">Adds a summary to the @application option context. See g_option_context_set_summary() for more information. - + the #GApplication + filename="gio/gapplication.c" + line="896">the #GApplication nullable="1" allow-none="1"> a string to be shown in `--help` output + filename="gio/gapplication.c" + line="897">a string to be shown in `--help` output before the list of options, or %NULL @@ -8466,13 +8822,13 @@ See g_option_context_set_summary() for more information. glib:set-property="resource-base-path" version="2.42"> Sets (or unsets) the base resource path of @application. + filename="gio/gapplication.c" + line="2062">Sets (or unsets) the base resource path of @application. -The path is used to automatically load various [application -resources][gresource] such as menu layouts and action descriptions. -The various types of resources will be found at fixed names relative -to the given base path. +The path is used to automatically load various +[application resources][struct@Gio.Resource] such as menu layouts and +action descriptions. The various types of resources will be found at +fixed names relative to the given base path. By default, the resource base path is determined from the application ID by prefixing '/' and replacing each '.' with '/'. This is done at @@ -8500,15 +8856,15 @@ a sub-class of #GApplication you should either set the this function during the instance initialization. Alternatively, you can call this function in the #GApplicationClass.startup virtual function, before chaining up to the parent implementation. - + a #GApplication + filename="gio/gapplication.c" + line="2064">a #GApplication nullable="1" allow-none="1"> the resource path to use + filename="gio/gapplication.c" + line="2065">the resource path to use + + + + + + Sets the version number of @application. This will be used to implement +a `--version` command line argument + +The application version can only be modified if @application has not yet +been registered. + + + + + + + a #GApplication + + + + the version of @application @@ -8526,31 +8912,31 @@ before chaining up to the parent implementation. c:identifier="g_application_unbind_busy_property" version="2.44"> Destroys a binding between @property and the busy state of + filename="gio/gapplication.c" + line="3246">Destroys a binding between @property and the busy state of @application that was previously created with g_application_bind_busy_property(). - + a #GApplication + filename="gio/gapplication.c" + line="3248">a #GApplication a #GObject + filename="gio/gapplication.c" + line="3249">a #GObject the name of a boolean property of @object + filename="gio/gapplication.c" + line="3250">the name of a boolean property of @object @@ -8559,23 +8945,23 @@ g_application_bind_busy_property(). c:identifier="g_application_unmark_busy" version="2.38"> Decreases the busy count of @application. + filename="gio/gapplication.c" + line="3003">Decreases the busy count of @application. When the busy count reaches zero, the new state will be propagated to other processes. This function must only be called to cancel the effect of a previous call to g_application_mark_busy(). - + a #GApplication + filename="gio/gapplication.c" + line="3005">a #GApplication @@ -8584,8 +8970,8 @@ call to g_application_mark_busy(). c:identifier="g_application_withdraw_notification" version="2.40"> Withdraws a notification that was sent with + filename="gio/gapplication.c" + line="3118">Withdraws a notification that was sent with g_application_send_notification(). This call does nothing if a notification with @id doesn't exist or @@ -8598,55 +8984,76 @@ the sent notification. Note that notifications are dismissed when the user clicks on one of the buttons in a notification or triggers its default action, so there is no need to explicitly withdraw the notification in that case. - + a #GApplication + filename="gio/gapplication.c" + line="3120">a #GApplication id of a previously sent notification + filename="gio/gapplication.c" + line="3121">id of a previously sent notification + The group of actions that the application exports. + Use the [iface@Gio.ActionMap] interface instead. + Never ever mix use of this API with use of `GActionMap` on the + same @application or things will go very badly wrong. + The unique identifier for the application. + Flags specifying the behaviour of the application. + Time (in milliseconds) to stay alive after becoming idle. getter="get_is_busy" default-value="FALSE"> Whether the application is currently marked as busy through + filename="gio/gapplication.c" + line="1626">Whether the application is currently marked as busy through g_application_mark_busy() or g_application_bind_busy_property(). + Whether [method@Gio.Application.register] has been called. + Whether this application instance is remote. + The base resource path for the application. + + + + The human-readable version number of the application. @@ -8688,8 +9119,8 @@ g_application_mark_busy() or g_application_bind_busy_property(). The ::activate signal is emitted on the primary instance when an + filename="gio/gapplication.c" + line="1662">The ::activate signal is emitted on the primary instance when an activation occurs. See g_application_activate(). @@ -8697,22 +9128,22 @@ activation occurs. See g_application_activate(). The ::command-line signal is emitted on the primary instance when + filename="gio/gapplication.c" + line="1695">The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See g_application_run() and the #GApplicationCommandLine documentation for more information. An integer that is set as the exit status for the calling + filename="gio/gapplication.c" + line="1705">An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status(). a #GApplicationCommandLine representing the + filename="gio/gapplication.c" + line="1698">a #GApplicationCommandLine representing the passed commandline @@ -8720,8 +9151,8 @@ the #GApplicationCommandLine documentation for more information. The ::handle-local-options signal is emitted on the local instance + filename="gio/gapplication.c" + line="1718">The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred. You can add options to be recognised during commandline option @@ -8764,8 +9195,8 @@ capabilities than what is provided here, but this should not normally be required. an exit code. If you have handled your options and want + filename="gio/gapplication.c" + line="1765">an exit code. If you have handled your options and want to exit the process, return a non-negative option, 0 for success, and a positive value for failure. To continue, return -1 to let the default option processing continue. @@ -8774,31 +9205,31 @@ the default option processing continue. the options dictionary + filename="gio/gapplication.c" + line="1721">the options dictionary The ::name-lost signal is emitted only on the registered primary instance + filename="gio/gapplication.c" + line="1782">The ::name-lost signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the %G_APPLICATION_ALLOW_REPLACEMENT flag. The default handler for this signal calls g_application_quit(). %TRUE if the signal has been handled + filename="gio/gapplication.c" + line="1792">%TRUE if the signal has been handled The ::open signal is emitted on the primary instance when there are + filename="gio/gapplication.c" + line="1675">The ::open signal is emitted on the primary instance when there are files to open. See g_application_open() for more information. @@ -8806,30 +9237,30 @@ files to open. See g_application_open() for more information. an array of #GFiles + filename="gio/gapplication.c" + line="1678">an array of #GFiles the length of @files + filename="gio/gapplication.c" + line="1679">the length of @files a hint provided by the calling instance + filename="gio/gapplication.c" + line="1680">a hint provided by the calling instance The ::shutdown signal is emitted only on the registered primary instance + filename="gio/gapplication.c" + line="1650">The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates. @@ -8837,8 +9268,8 @@ immediately after the main loop terminates. The ::startup signal is emitted on the primary instance immediately + filename="gio/gapplication.c" + line="1638">The ::startup signal is emitted on the primary instance immediately after registration. See g_application_register(). @@ -8850,15 +9281,18 @@ after registration. See g_application_register(). glib:is-gtype-struct-for="Application" version="2.28"> Virtual function table for #GApplication. - + filename="gio/gapplication.c" + line="178">Virtual function table for #GApplication. + + invoked on the primary instance immediately after registration - + @@ -8870,60 +9304,70 @@ after registration. See g_application_register(). + invoked on the primary instance when an activation occurs - + a #GApplication + filename="gio/gapplication.c" + line="2432">a #GApplication + invoked on the primary instance when there are files to open - + a #GApplication + filename="gio/gapplication.c" + line="2459">a #GApplication an array of #GFiles to open + filename="gio/gapplication.c" + line="2460">an array of #GFiles to open the length of the @files array + filename="gio/gapplication.c" + line="2461">the length of the @files array a hint (or ""), but never %NULL + filename="gio/gapplication.c" + line="2462">a hint (or ""), but never %NULL + invoked on the primary instance when a command-line is + not handled locally - + @@ -8939,18 +9383,25 @@ after registration. See g_application_register(). + invoked (locally). The virtual function has the chance + to inspect (and possibly replace) command line arguments. See + g_application_run() for more information. Also see the + #GApplication::handle-local-options signal, which is a simpler + alternative to handling some commandline options locally - + %TRUE if the commandline has been completely handled a #GApplication @@ -8959,7 +9410,7 @@ after registration. See g_application_register(). caller-allocates="0" transfer-ownership="full"> array of command line arguments @@ -8970,7 +9421,7 @@ after registration. See g_application_register(). caller-allocates="0" transfer-ownership="full"> exit status to fill after processing the command line. @@ -8978,8 +9429,13 @@ after registration. See g_application_register(). + invoked on the primary instance before 'activate', 'open', + 'command-line' or any action invocation, gets the 'platform data' from + the calling instance - + @@ -8994,8 +9450,13 @@ after registration. See g_application_register(). + invoked on the primary instance after 'activate', 'open', + 'command-line' or any action invocation, gets the 'platform data' from + the calling instance - + @@ -9010,8 +9471,12 @@ after registration. See g_application_register(). + invoked (locally) to add 'platform data' to be sent to + the primary instance when activating, opening or invoking actions - + @@ -9026,8 +9491,13 @@ after registration. See g_application_register(). + Used to be invoked on the primary instance when the use + count of the application drops to zero (and after any inactivity + timeout, if requested). Not used anymore since 2.32 - + @@ -9039,8 +9509,14 @@ after registration. See g_application_register(). + Used to be invoked on the primary instance from + g_application_run() if the use-count is non-zero. Since 2.32, + GApplication is iterating the main context directly and is not + using @run_mainloop anymore - + @@ -9052,8 +9528,12 @@ after registration. See g_application_register(). + invoked only on the registered primary instance immediately + after the main loop terminates - + @@ -9065,8 +9545,17 @@ after registration. See g_application_register(). + invoked locally during registration, if the application is + using its D-Bus backend. You can use this to export extra objects on the + bus, that need to exist before the application tries to own the bus name. + The function is passed the #GDBusConnection to to session bus, and the + object path that #GApplication will use to export its D-Bus API. + If this function returns %TRUE, registration will proceed; otherwise + registration will abort. Since: 2.34 - + @@ -9084,8 +9573,13 @@ after registration. See g_application_register(). + invoked locally during unregistration, if the application + is using its D-Bus backend. Use this to undo anything done by + the @dbus_register vfunc. Since: 2.34 - + @@ -9103,8 +9597,12 @@ after registration. See g_application_register(). + invoked locally after the parsing of the commandline + options has occurred. Since: 2.40 - + @@ -9119,8 +9617,11 @@ after registration. See g_application_register(). + invoked when another instance is taking over the name. Since: 2.60 - + @@ -9145,31 +9646,34 @@ after registration. See g_application_register(). glib:get-type="g_application_command_line_get_type" glib:type-struct="ApplicationCommandLineClass"> #GApplicationCommandLine represents a command-line invocation of -an application. It is created by #GApplication and emitted -in the #GApplication::command-line signal and virtual function. + filename="gio/gapplicationcommandline.c" + line="42">`GApplicationCommandLine` represents a command-line invocation of +an application. + +It is created by [class@Gio.Application] and emitted +in the [signal@Gio.Application::command-line] signal and virtual function. The class contains the list of arguments that the program was invoked -with. It is also possible to query if the commandline invocation was +with. It is also possible to query if the commandline invocation was local (ie: the current process is running in direct response to the invocation) or remote (ie: some other process forwarded the commandline to this process). -The GApplicationCommandLine object can provide the @argc and @argv -parameters for use with the #GOptionContext command-line parsing API, -with the g_application_command_line_get_arguments() function. See -[gapplication-example-cmdline3.c][gapplication-example-cmdline3] +The `GApplicationCommandLine` object can provide the @argc and @argv +parameters for use with the [struct@GLib.OptionContext] command-line parsing API, +with the [method@Gio.ApplicationCommandLine.get_arguments] function. See +[gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) for an example. The exit status of the originally-invoked process may be set and -messages can be printed to stdout or stderr of that process. The -lifecycle of the originally-invoked process is tied to the lifecycle -of this object (ie: the process exits when the last reference is -dropped). +messages can be printed to stdout or stderr of that process. + +For remote invocation, the originally-invoked process exits when +[method@Gio.ApplicationCommandLine.done] method is called. This method is +also automatically called when the object is disposed. -The main use for #GApplicationCommandLine (and the -#GApplication::command-line signal) is 'Emacs server' like use cases: +The main use for `GApplicationCommandLine` (and the +[signal@Gio.Application::command-line] signal) is 'Emacs server' like use cases: You can set the `EDITOR` environment variable to have e.g. git use your favourite editor to edit commit messages, and if you already have an instance of the editor running, the editing will happen @@ -9178,11 +9682,12 @@ aspect of this use case is that the process that gets started by git does not return until the editing is done. Normally, the commandline is completely handled in the -#GApplication::command-line handler. The launching instance exits +[signal@Gio.Application::command-line] handler. The launching instance exits once the signal handler in the primary instance has returned, and the return value of the signal handler becomes the exit status of the launching instance. -|[<!-- language="C" --> + +```c static int command_line (GApplication *application, GApplicationCommandLine *cmdline) @@ -9204,13 +9709,15 @@ command_line (GApplication *application, return 0; } -]| +``` + The complete example can be found here: [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c) In more complicated cases, the handling of the commandline can be split between the launcher and the primary instance. -|[<!-- language="C" --> + +```c static gboolean test_local_cmdline (GApplication *application, gchar ***arguments, @@ -9256,18 +9763,19 @@ test_application_class_init (TestApplicationClass *class) ... } -]| +``` + In this example of split commandline handling, options that start with `--local-` are handled locally, all other options are passed -to the #GApplication::command-line handler which runs in the primary +to the [signal@Gio.Application::command-line] handler which runs in the primary instance. The complete example can be found here: [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) -If handling the commandline requires a lot of work, it may -be better to defer it. -|[<!-- language="C" --> +If handling the commandline requires a lot of work, it may be better to defer it. + +```c static gboolean my_cmdline_handler (gpointer data) { @@ -9297,20 +9805,53 @@ command_line (GApplication *application, return 0; } -]| +``` + In this example the commandline is not completely handled before -the #GApplication::command-line handler returns. Instead, we keep -a reference to the #GApplicationCommandLine object and handle it +the [signal@Gio.Application::command-line] handler returns. Instead, we keep +a reference to the `GApplicationCommandLine` object and handle it later (in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline. The complete example can be found here: [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) - + + + Signals that command line processing is completed. + +For remote invocation, it causes the invoking process to terminate. + +For local invocation, it does nothing. + +This method should be called in the [signal@Gio.Application::command-line] +handler, after the exit status is set and all messages are printed. + +After this call, g_application_command_line_set_exit_status() has no effect. +Subsequent calls to this method are no-ops. + +This method is automatically called when the #GApplicationCommandLine +object is disposed — so you can omit the call in non-garbage collected +languages. + + + + + + + a #GApplicationCommandLine + + + + Gets the stdin of the invoking process. + filename="gio/gapplicationcommandline.c" + line="565">Gets the stdin of the invoking process. The #GInputStream can be used to read data passed to the standard input of the invoking process. @@ -9320,49 +9861,79 @@ If stdin is not available then %NULL will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. - + a #GInputStream for stdin + filename="gio/gapplicationcommandline.c" + line="580">a #GInputStream for stdin a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="567">a #GApplicationCommandLine - - + + Prints a message using the stdout print handler in the invoking process. + +Unlike g_application_command_line_print(), @message is not a `printf()`-style +format string. Use this function if @message contains text you don't have +control over, that could include `printf()` escape sequences. + + a #GApplicationCommandLine + the message - - + + Prints a message using the stderr print handler in the invoking process. + +Unlike g_application_command_line_printerr(), @message is not +a `printf()`-style format string. Use this function if @message contains text +you don't have control over, that could include `printf()` escape sequences. + + a #GApplicationCommandLine + the message @@ -9371,42 +9942,76 @@ You must only call this function once per commandline invocation. c:identifier="g_application_command_line_create_file_for_arg" version="2.36"> Creates a #GFile corresponding to a filename that was given as part + filename="gio/gapplicationcommandline.c" + line="910">Creates a #GFile corresponding to a filename that was given as part of the invocation of @cmdline. This differs from g_file_new_for_commandline_arg() in that it resolves relative pathnames using the current working directory of the invoking process rather than the local process. - + a new #GFile + filename="gio/gapplicationcommandline.c" + line="922">a new #GFile a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="912">a #GApplicationCommandLine an argument from @cmdline + filename="gio/gapplicationcommandline.c" + line="913">an argument from @cmdline + + Signals that command line processing is completed. + +For remote invocation, it causes the invoking process to terminate. + +For local invocation, it does nothing. + +This method should be called in the [signal@Gio.Application::command-line] +handler, after the exit status is set and all messages are printed. + +After this call, g_application_command_line_set_exit_status() has no effect. +Subsequent calls to this method are no-ops. + +This method is automatically called when the #GApplicationCommandLine +object is disposed — so you can omit the call in non-garbage collected +languages. + + + + + + + a #GApplicationCommandLine + + + + Gets the list of arguments that was passed on the command line. + filename="gio/gapplicationcommandline.c" + line="494">Gets the list of arguments that was passed on the command line. The strings in the array may contain non-UTF-8 data on UNIX (such as filenames or arguments given in the system locale) but are always in @@ -9417,11 +10022,11 @@ use g_option_context_parse_strv(). The return value is %NULL-terminated and should be freed using g_strfreev(). - + + filename="gio/gapplicationcommandline.c" + line="511"> the string array containing the arguments (the argv) @@ -9430,8 +10035,8 @@ g_strfreev(). a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="496">a #GApplicationCommandLine @@ -9442,8 +10047,8 @@ g_strfreev(). optional="1" allow-none="1"> the length of the arguments array, or %NULL + filename="gio/gapplicationcommandline.c" + line="497">the length of the arguments array, or %NULL @@ -9452,8 +10057,8 @@ g_strfreev(). c:identifier="g_application_command_line_get_cwd" version="2.28"> Gets the working directory of the command line invocation. + filename="gio/gapplicationcommandline.c" + line="590">Gets the working directory of the command line invocation. The string may contain non-utf8 data. It is possible that the remote application did not send a working @@ -9461,18 +10066,18 @@ directory, so this may be %NULL. The return value should not be modified or freed and is valid for as long as @cmdline exists. - + the current directory, or %NULL + filename="gio/gapplicationcommandline.c" + line="603">the current directory, or %NULL a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="592">a #GApplicationCommandLine @@ -9482,8 +10087,8 @@ long as @cmdline exists. c:identifier="g_application_command_line_get_environ" version="2.28"> Gets the contents of the 'environ' variable of the command line + filename="gio/gapplicationcommandline.c" + line="613">Gets the contents of the 'environ' variable of the command line invocation, as would be returned by g_get_environ(), ie as a %NULL-terminated list of strings in the form 'NAME=VALUE'. The strings may contain non-utf8 data. @@ -9498,11 +10103,11 @@ long as @cmdline exists. See g_application_command_line_getenv() if you are only interested in the value of a single environment variable. - + + filename="gio/gapplicationcommandline.c" + line="633"> the environment strings, or %NULL if they were not sent @@ -9511,8 +10116,8 @@ in the value of a single environment variable. a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="615">a #GApplicationCommandLine @@ -9522,21 +10127,21 @@ in the value of a single environment variable. c:identifier="g_application_command_line_get_exit_status" version="2.28"> Gets the exit status of @cmdline. See + filename="gio/gapplicationcommandline.c" + line="860">Gets the exit status of @cmdline. See g_application_command_line_set_exit_status() for more information. - + the exit status + filename="gio/gapplicationcommandline.c" + line="867">the exit status a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="862">a #GApplicationCommandLine @@ -9547,20 +10152,20 @@ g_application_command_line_set_exit_status() for more information. glib:get-property="is-remote" version="2.28"> Determines if @cmdline represents a remote invocation. - + filename="gio/gapplicationcommandline.c" + line="682">Determines if @cmdline represents a remote invocation. + %TRUE if the invocation was remote + filename="gio/gapplicationcommandline.c" + line="688">%TRUE if the invocation was remote a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="684">a #GApplicationCommandLine @@ -9570,8 +10175,8 @@ g_application_command_line_set_exit_status() for more information. c:identifier="g_application_command_line_get_options_dict" version="2.40"> Gets the options that were passed to g_application_command_line(). + filename="gio/gapplicationcommandline.c" + line="533">Gets the options that were passed to g_application_command_line(). If you did not override local_command_line() then these are the same options that were parsed according to the #GOptionEntrys added to the @@ -9583,18 +10188,18 @@ you don't need to check for %NULL. The data has been passed via an untrusted external process, so the types of all values must be checked before being used. - + a #GVariantDict with the options + filename="gio/gapplicationcommandline.c" + line="550">a #GVariantDict with the options a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="535">a #GApplicationCommandLine @@ -9604,8 +10209,8 @@ all values must be checked before being used. c:identifier="g_application_command_line_get_platform_data" version="2.28"> Gets the platform data associated with the invocation of @cmdline. + filename="gio/gapplicationcommandline.c" + line="879">Gets the platform data associated with the invocation of @cmdline. This is a #GVariant dictionary containing information about the context in which the invocation occurred. It typically contains @@ -9616,18 +10221,18 @@ It comes from an untrusted external process and hence the types of all values must be validated before being used. For local invocation, it will be %NULL. - + the platform data, or %NULL + filename="gio/gapplicationcommandline.c" + line="895">the platform data, or %NULL #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="881">#GApplicationCommandLine @@ -9637,8 +10242,8 @@ For local invocation, it will be %NULL. c:identifier="g_application_command_line_get_stdin" version="2.34"> Gets the stdin of the invoking process. + filename="gio/gapplicationcommandline.c" + line="565">Gets the stdin of the invoking process. The #GInputStream can be used to read data passed to the standard input of the invoking process. @@ -9648,18 +10253,18 @@ If stdin is not available then %NULL will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. - + a #GInputStream for stdin + filename="gio/gapplicationcommandline.c" + line="580">a #GInputStream for stdin a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="567">a #GApplicationCommandLine @@ -9669,8 +10274,8 @@ You must only call this function once per commandline invocation. c:identifier="g_application_command_line_getenv" version="2.28"> Gets the value of a particular environment variable of the command + filename="gio/gapplicationcommandline.c" + line="644">Gets the value of a particular environment variable of the command line invocation, as would be returned by g_getenv(). The strings may contain non-utf8 data. @@ -9681,25 +10286,25 @@ to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. - + the value of the variable, or %NULL if unset or unsent + filename="gio/gapplicationcommandline.c" + line="661">the value of the variable, or %NULL if unset or unsent a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="646">a #GApplicationCommandLine the environment variable to get + filename="gio/gapplicationcommandline.c" + line="647">the environment variable to get @@ -9709,83 +10314,143 @@ long as @cmdline exists. version="2.28" introspectable="0"> Formats a message and prints it using the stdout print handler in the + filename="gio/gapplicationcommandline.c" + line="746">Formats a message and prints it using the stdout print handler in the invoking process. If @cmdline is a local invocation then this is exactly equivalent to g_print(). If @cmdline is remote then this is equivalent to calling g_print() in the invoking process. - + a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="748">a #GApplicationCommandLine a printf-style format string + filename="gio/gapplicationcommandline.c" + line="749">a printf-style format string arguments, as per @format + filename="gio/gapplicationcommandline.c" + line="750">arguments, as per @format + + Prints a message using the stdout print handler in the invoking process. + +Unlike g_application_command_line_print(), @message is not a `printf()`-style +format string. Use this function if @message contains text you don't have +control over, that could include `printf()` escape sequences. + + + + + + + a #GApplicationCommandLine + + + + the message + + + + Formats a message and prints it using the stderr print handler in the + filename="gio/gapplicationcommandline.c" + line="781">Formats a message and prints it using the stderr print handler in the invoking process. If @cmdline is a local invocation then this is exactly equivalent to g_printerr(). If @cmdline is remote then this is equivalent to calling g_printerr() in the invoking process. - + a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="783">a #GApplicationCommandLine a printf-style format string + filename="gio/gapplicationcommandline.c" + line="784">a printf-style format string arguments, as per @format + filename="gio/gapplicationcommandline.c" + line="785">arguments, as per @format + + Prints a message using the stderr print handler in the invoking process. + +Unlike g_application_command_line_printerr(), @message is not +a `printf()`-style format string. Use this function if @message contains text +you don't have control over, that could include `printf()` escape sequences. + + + + + + + a #GApplicationCommandLine + + + + the message + + + + Sets the exit status that will be used when the invoking process + filename="gio/gapplicationcommandline.c" + line="816">Sets the exit status that will be used when the invoking process exits. The return value of the #GApplication::command-line signal is @@ -9805,52 +10470,72 @@ in the mainloop running (ie: because the use-count of the application increased to a non-zero value) then the application is considered to have been 'successful' in a certain sense, and the exit status is always zero. If the application use count is zero, though, the exit -status of the local #GApplicationCommandLine is used. - +status of the local #GApplicationCommandLine is used. + +This method is a no-op if g_application_command_line_done() has +been called. + a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="818">a #GApplicationCommandLine the exit status + filename="gio/gapplicationcommandline.c" + line="819">the exit status + The commandline that caused this [signal@Gio.Application::command-line] +signal emission. + Whether this is a remote commandline. + The options sent along with the commandline. + Platform-specific data for the commandline. @@ -9866,25 +10551,31 @@ status of the local #GApplicationCommandLine is used. glib:is-gtype-struct-for="ApplicationCommandLine" version="2.28"> The #GApplicationCommandLineClass-struct + filename="gio/gapplicationcommandline.c" + line="215">The #GApplicationCommandLineClass-struct contains private data only. - + - + + a #GApplicationCommandLine + the message @@ -9892,16 +10583,22 @@ contains private data only. - + + a #GApplicationCommandLine + the message @@ -9909,18 +10606,35 @@ contains private data only. - + a #GInputStream for stdin + filename="gio/gapplicationcommandline.c" + line="580">a #GInputStream for stdin a #GApplicationCommandLine + filename="gio/gapplicationcommandline.c" + line="567">a #GApplicationCommandLine + + + + + + + + + + + + + + a #GApplicationCommandLine @@ -9928,7 +10642,7 @@ contains private data only. - + @@ -9937,7 +10651,7 @@ contains private data only. c:type="GApplicationCommandLinePrivate" disguised="1" opaque="1"> - + glib:get-type="g_application_flags_get_type" c:type="GApplicationFlags"> Flags used to define the behaviour of a #GApplication. + filename="gio/gioenums.h" + line="1497">Flags used to define the behaviour of a #GApplication. Default. Deprecated in 2.74, use - %G_APPLICATION_DEFAULT_FLAGS instead + filename="gio/gioenums.h" + line="1540">Default flags. + Use [flags@Gio.ApplicationFlags.DEFAULT_FLAGS]. Default flags. Since: 2.74 + filename="gio/gioenums.h" + line="1547">Default flags. glib:nick="is-service" glib:name="G_APPLICATION_IS_SERVICE"> Run as a service. In this mode, registration + filename="gio/gioenums.h" + line="1499">Run as a service. In this mode, registration fails if the service is already running, and the application will initially wait up to 10 seconds for an initial activation message to arrive. @@ -9984,8 +10701,8 @@ contains private data only. glib:nick="is-launcher" glib:name="G_APPLICATION_IS_LAUNCHER"> Don't try to become the primary instance. + filename="gio/gioenums.h" + line="1503">Don't try to become the primary instance. glib:nick="handles-open" glib:name="G_APPLICATION_HANDLES_OPEN"> This application handles opening files (in + filename="gio/gioenums.h" + line="1504">This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. @@ -10006,8 +10723,8 @@ contains private data only. glib:nick="handles-command-line" glib:name="G_APPLICATION_HANDLES_COMMAND_LINE"> This application handles command line + filename="gio/gioenums.h" + line="1509">This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details. @@ -10018,8 +10735,8 @@ contains private data only. glib:nick="send-environment" glib:name="G_APPLICATION_SEND_ENVIRONMENT"> Send the environment of the + filename="gio/gioenums.h" + line="1513">Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected @@ -10034,8 +10751,8 @@ contains private data only. glib:nick="non-unique" glib:name="G_APPLICATION_NON_UNIQUE"> Make no attempts to do any of the typical + filename="gio/gioenums.h" + line="1521">Make no attempts to do any of the typical single-instance application negotiation, even if the application ID is given. The application neither attempts to become the owner of the application ID nor does it check if an existing @@ -10048,8 +10765,8 @@ contains private data only. glib:nick="can-override-app-id" glib:name="G_APPLICATION_CAN_OVERRIDE_APP_ID"> Allow users to override the + filename="gio/gioenums.h" + line="1527">Allow users to override the application ID from the command line with `--gapplication-app-id`. Since: 2.48 @@ -10059,8 +10776,8 @@ contains private data only. glib:nick="allow-replacement" glib:name="G_APPLICATION_ALLOW_REPLACEMENT"> Allow another instance to take over + filename="gio/gioenums.h" + line="1530">Allow another instance to take over the bus name. Since: 2.60 glib:nick="replace" glib:name="G_APPLICATION_REPLACE"> Take over from another instance. This flag is + filename="gio/gioenums.h" + line="1532">Take over from another instance. This flag is usually set by passing `--gapplication-replace` on the commandline. Since: 2.60 @@ -10079,15 +10796,15 @@ contains private data only. c:type="GApplicationPrivate" disguised="1" opaque="1"> - + #GAskPasswordFlags are used to request specific information from the + filename="gio/gioenums.h" + line="595">#GAskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation. glib:nick="need-password" glib:name="G_ASK_PASSWORD_NEED_PASSWORD"> operation requires a password. + filename="gio/gioenums.h" + line="597">operation requires a password. glib:nick="need-username" glib:name="G_ASK_PASSWORD_NEED_USERNAME"> operation requires a username. + filename="gio/gioenums.h" + line="598">operation requires a username. glib:nick="need-domain" glib:name="G_ASK_PASSWORD_NEED_DOMAIN"> operation requires a domain. + filename="gio/gioenums.h" + line="599">operation requires a domain. glib:nick="saving-supported" glib:name="G_ASK_PASSWORD_SAVING_SUPPORTED"> operation supports saving settings. + filename="gio/gioenums.h" + line="600">operation supports saving settings. glib:nick="anonymous-supported" glib:name="G_ASK_PASSWORD_ANONYMOUS_SUPPORTED"> operation supports anonymous users. + filename="gio/gioenums.h" + line="601">operation supports anonymous users. glib:nick="tcrypt" glib:name="G_ASK_PASSWORD_TCRYPT"> operation takes TCRYPT parameters (Since: 2.58) + filename="gio/gioenums.h" + line="602">operation takes TCRYPT parameters (Since: 2.58) glib:get-type="g_async_initable_get_type" glib:type-struct="AsyncInitableIface"> This is the asynchronous version of #GInitable; it behaves the same + filename="gio/gasyncinitable.c" + line="31">`GAsyncInitable` is an interface for asynchronously initializable objects. + +This is the asynchronous version of [iface@Gio.Initable]; it behaves the same in all ways except that initialization is asynchronous. For more details -see the descriptions on #GInitable. +see the descriptions on `GInitable`. -A class may implement both the #GInitable and #GAsyncInitable interfaces. +A class may implement both the `GInitable` and `GAsyncInitable` interfaces. Users of objects implementing this are not intended to use the interface method directly; instead it will be used automatically in various ways. -For C applications you generally just call g_async_initable_new_async() +For C applications you generally just call [func@Gio.AsyncInitable.new_async] directly, or indirectly via a foo_thing_new_async() wrapper. This will call -g_async_initable_init_async() under the cover, calling back with %NULL and -a set %GError on failure. +[method@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL` +and a set `GError` on failure. A typical implementation might look something like this: -|[<!-- language="C" --> +```c enum { NOT_INITIALIZED, INITIALIZING, @@ -10252,35 +10971,35 @@ foo_async_initable_iface_init (gpointer g_iface, iface->init_async = foo_init_async; iface->init_finish = foo_init_finish; } -]| - +``` + Helper function for constructing #GAsyncInitable object. This is + filename="gio/gasyncinitable.c" + line="313">Helper function for constructing #GAsyncInitable object. This is similar to g_object_new() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. - + a #GType supporting #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="315">a #GType supporting #GAsyncInitable. the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="316">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="317">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback to call when the initialization is + filename="gio/gasyncinitable.c" + line="318">a #GAsyncReadyCallback to call when the initialization is finished @@ -10309,8 +11028,8 @@ for any errors. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gasyncinitable.c" + line="320">the data to pass to callback function nullable="1" allow-none="1"> the name of the first property, or %NULL if no + filename="gio/gasyncinitable.c" + line="321">the name of the first property, or %NULL if no properties the value of the first property, followed by other property + filename="gio/gasyncinitable.c" + line="323">the value of the first property, followed by other property value pairs, and ended by %NULL. @@ -10337,42 +11056,42 @@ for any errors. version="2.22" introspectable="0"> Helper function for constructing #GAsyncInitable object. This is + filename="gio/gasyncinitable.c" + line="399">Helper function for constructing #GAsyncInitable object. This is similar to g_object_new_valist() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. - + a #GType supporting #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="401">a #GType supporting #GAsyncInitable. the name of the first property, followed by + filename="gio/gasyncinitable.c" + line="402">the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. The var args list generated from @first_property_name. + filename="gio/gasyncinitable.c" + line="404">The var args list generated from @first_property_name. the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="405">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="406">optional #GCancellable object, %NULL to ignore. scope="async" closure="6"> a #GAsyncReadyCallback to call when the initialization is + filename="gio/gasyncinitable.c" + line="407">a #GAsyncReadyCallback to call when the initialization is finished @@ -10401,8 +11120,8 @@ the value, and other property value pairs, and ended by %NULL. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gasyncinitable.c" + line="409">the data to pass to callback function @@ -10413,8 +11132,8 @@ the value, and other property value pairs, and ended by %NULL. deprecated="1" deprecated-version="2.54"> Helper function for constructing #GAsyncInitable object. This is + filename="gio/gasyncinitable.c" + line="354">Helper function for constructing #GAsyncInitable object. This is similar to g_object_newv() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can @@ -10422,33 +11141,33 @@ then call g_async_initable_new_finish() to get the new object and check for any errors. Use g_object_new_with_properties() and g_async_initable_init_async() instead. See #GParameter for more information. - + a #GType supporting #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="356">a #GType supporting #GAsyncInitable. the number of parameters in @parameters + filename="gio/gasyncinitable.c" + line="357">the number of parameters in @parameters the parameters to use to construct the object + filename="gio/gasyncinitable.c" + line="358">the parameters to use to construct the object the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="359">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="360">optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is + filename="gio/gasyncinitable.c" + line="361">a #GAsyncReadyCallback to call when the initialization is finished @@ -10477,16 +11196,19 @@ g_async_initable_init_async() instead. See #GParameter for more information. the data to pass to callback function + filename="gio/gasyncinitable.c" + line="363">the data to pass to callback function - + Starts asynchronous initialization of the object implementing the + filename="gio/gasyncinitable.c" + line="160">Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead. @@ -10522,21 +11244,21 @@ implementation of this method will run the g_initable_init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the #GAsyncInitable interface without overriding any interface methods. - + a #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="162">a #GAsyncInitable. the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="163">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="164">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gasyncinitable.c" + line="165">a #GAsyncReadyCallback to call when the request is satisfied allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gasyncinitable.c" + line="166">the data to pass to callback function @@ -10576,38 +11298,39 @@ any interface methods. version="2.22" throws="1"> Finishes asynchronous initialization and returns the result. + filename="gio/gasyncinitable.c" + line="223">Finishes asynchronous initialization and returns the result. See g_async_initable_init_async(). - + %TRUE if successful. If an error has occurred, this function + filename="gio/gasyncinitable.c" + line="233">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="225">a #GAsyncInitable. a #GAsyncResult. + filename="gio/gasyncinitable.c" + line="226">a #GAsyncResult. + version="2.22" + glib:finish-func="init_finish"> Starts asynchronous initialization of the object implementing the + filename="gio/gasyncinitable.c" + line="160">Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead. @@ -10643,21 +11366,21 @@ implementation of this method will run the g_initable_init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the #GAsyncInitable interface without overriding any interface methods. - + a #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="162">a #GAsyncInitable. the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="163">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="164">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gasyncinitable.c" + line="165">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gasyncinitable.c" + line="166">the data to pass to callback function @@ -10696,28 +11419,28 @@ any interface methods. version="2.22" throws="1"> Finishes asynchronous initialization and returns the result. + filename="gio/gasyncinitable.c" + line="223">Finishes asynchronous initialization and returns the result. See g_async_initable_init_async(). - + %TRUE if successful. If an error has occurred, this function + filename="gio/gasyncinitable.c" + line="233">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="225">a #GAsyncInitable. a #GAsyncResult. + filename="gio/gasyncinitable.c" + line="226">a #GAsyncResult. @@ -10727,28 +11450,28 @@ will return %FALSE and set @error appropriately if present. version="2.22" throws="1"> Finishes the async construction for the various g_async_initable_new + filename="gio/gasyncinitable.c" + line="444">Finishes the async construction for the various g_async_initable_new calls, returning the created object or %NULL on error. - + a newly created #GObject, + filename="gio/gasyncinitable.c" + line="453">a newly created #GObject, or %NULL on error. Free with g_object_unref(). the #GAsyncInitable from the callback + filename="gio/gasyncinitable.c" + line="446">the #GAsyncInitable from the callback the #GAsyncResult from the callback + filename="gio/gasyncinitable.c" + line="447">the #GAsyncResult from the callback @@ -10759,33 +11482,36 @@ calls, returning the created object or %NULL on error. glib:is-gtype-struct-for="AsyncInitable" version="2.22"> Provides an interface for asynchronous initializing object such that + filename="gio/gasyncinitable.h" + line="43">Provides an interface for asynchronous initializing object such that initialization may fail. - + The parent interface. + filename="gio/gasyncinitable.h" + line="45">The parent interface. + Starts initialization of the object. - + a #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="162">a #GAsyncInitable. the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="163">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="164">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gasyncinitable.c" + line="165">a #GAsyncReadyCallback to call when the request is satisfied allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gasyncinitable.c" + line="166">the data to pass to callback function + Finishes initialization of the object. - + %TRUE if successful. If an error has occurred, this function + filename="gio/gasyncinitable.c" + line="233">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="225">a #GAsyncInitable. a #GAsyncResult. + filename="gio/gasyncinitable.c" + line="226">a #GAsyncResult. @@ -10850,12 +11579,12 @@ will return %FALSE and set @error appropriately if present. Type definition for a function that will be called back when an asynchronous + filename="gio/giotypes.h" + line="171">Type definition for a function that will be called back when an asynchronous operation within GIO has been completed. #GAsyncReadyCallback callbacks from #GTask are guaranteed to be invoked in a later -iteration of the -[thread-default main context][g-main-context-push-thread-default] +iteration of the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) where the #GTask was created. All other users of #GAsyncReadyCallback must likewise call it asynchronously in a later iteration of the main context. @@ -10863,7 +11592,7 @@ later iteration of the main context. The asynchronous operation is guaranteed to have held a reference to @source_object from the time when the `*_async()` function was called, until after this callback returns. - + @@ -10873,14 +11602,14 @@ after this callback returns. nullable="1" allow-none="1"> the object the asynchronous operation was started with. + filename="gio/giotypes.h" + line="173">the object the asynchronous operation was started with. a #GAsyncResult. + filename="gio/giotypes.h" + line="174">a #GAsyncResult. nullable="1" allow-none="1"> user data passed to the callback. + filename="gio/giotypes.h" + line="175">user data passed to the callback. @@ -10901,38 +11630,39 @@ after this callback returns. glib:get-type="g_async_result_get_type" glib:type-struct="AsyncResultIface"> Provides a base class for implementing asynchronous function results. + filename="gio/gasyncresult.c" + line="29">`GAsyncResult` provides a base class for implementing asynchronous function results. Asynchronous operations are broken up into two separate operations -which are chained together by a #GAsyncReadyCallback. To begin -an asynchronous operation, provide a #GAsyncReadyCallback to the +which are chained together by a `GAsyncReadyCallback`. To begin +an asynchronous operation, provide a `GAsyncReadyCallback` to the asynchronous function. This callback will be triggered when the operation has completed, and must be run in a later iteration of -the [thread-default main context][g-main-context-push-thread-default] -from where the operation was initiated. It will be passed a -#GAsyncResult instance filled with the details of the operation's -success or failure, the object the asynchronous function was -started for and any error codes returned. The asynchronous callback -function is then expected to call the corresponding "_finish()" +the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) from where the operation was +initiated. It will be passed a `GAsyncResult` instance filled with the +details of the operation's success or failure, the object the asynchronous +function was started for and any error codes returned. The asynchronous +callback function is then expected to call the corresponding `_finish()` function, passing the object the function was called for, the -#GAsyncResult instance, and (optionally) an @error to grab any +`GAsyncResult` instance, and (optionally) an @error to grab any error conditions that may have occurred. -The "_finish()" function for an operation takes the generic result -(of type #GAsyncResult) and returns the specific result that the -operation in question yields (e.g. a #GFileEnumerator for a +The `_finish()` function for an operation takes the generic result +(of type `GAsyncResult`) and returns the specific result that the +operation in question yields (e.g. a [class@Gio.FileEnumerator] for a "enumerate children" operation). If the result or error status of the -operation is not needed, there is no need to call the "_finish()" +operation is not needed, there is no need to call the `_finish()` function; GIO will take care of cleaning up the result and error -information after the #GAsyncReadyCallback returns. You can pass -%NULL for the #GAsyncReadyCallback if you don't need to take any +information after the `GAsyncReadyCallback` returns. You can pass +`NULL` for the `GAsyncReadyCallback` if you don't need to take any action at all after the operation completes. Applications may also -take a reference to the #GAsyncResult and call "_finish()" later; -however, the "_finish()" function may be called at most once. +take a reference to the `GAsyncResult` and call `_finish()` later; +however, the `_finish()` function may be called at most once. Example of a typical asynchronous operation flow: -|[<!-- language="C" --> + +```c void _theoretical_frobnitz_async (Theoretical *t, GCancellable *c, GAsyncReadyCallback cb, @@ -10971,81 +11701,81 @@ int main (int argc, void *argv[]) ... } -]| +``` The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation. On cancellation -the result is a %G_IO_ERROR_CANCELLED error. +the result is a `G_IO_ERROR_CANCELLED` error. -## I/O Priority # {#io-priority} +## I/O Priority Many I/O-related asynchronous operations have a priority parameter, which is used in certain cases to determine the order in which operations are executed. They are not used to determine system-wide I/O scheduling. Priorities are integers, with lower numbers indicating higher priority. It is recommended to choose priorities between -%G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT +`G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT` as a default. - + Gets the source object from a #GAsyncResult. - + filename="gio/gasyncresult.c" + line="147">Gets the source object from a [iface@Gio.AsyncResult]. + a new reference to the source - object for the @res, or %NULL if there is none. + filename="gio/gasyncresult.c" + line="153">a new reference to the source + object for the @res, or `NULL` if there is none. a #GAsyncResult + filename="gio/gasyncresult.c" + line="149">a [iface@Gio.AsyncResult] Gets the user data from a #GAsyncResult. - + filename="gio/gasyncresult.c" + line="127">Gets the user data from a [iface@Gio.AsyncResult]. + the user data for @res. + filename="gio/gasyncresult.c" + line="133">the user data for @res. a #GAsyncResult. + filename="gio/gasyncresult.c" + line="129">a [iface@Gio.AsyncResult]. Checks if @res has the given @source_tag (generally a function + filename="gio/gasyncresult.c" + line="210">Checks if @res has the given @source_tag (generally a function pointer indicating the function @res was created by). - + %TRUE if @res has the indicated @source_tag, %FALSE if + filename="gio/gasyncresult.c" + line="218">`TRUE` if @res has the indicated @source_tag, `FALSE` if not. a #GAsyncResult + filename="gio/gasyncresult.c" + line="212">a [iface@Gio.AsyncResult] nullable="1" allow-none="1"> an application-defined tag + filename="gio/gasyncresult.c" + line="213">an application-defined tag @@ -11062,41 +11792,41 @@ pointer indicating the function @res was created by). Gets the source object from a #GAsyncResult. - + filename="gio/gasyncresult.c" + line="147">Gets the source object from a [iface@Gio.AsyncResult]. + a new reference to the source - object for the @res, or %NULL if there is none. + filename="gio/gasyncresult.c" + line="153">a new reference to the source + object for the @res, or `NULL` if there is none. a #GAsyncResult + filename="gio/gasyncresult.c" + line="149">a [iface@Gio.AsyncResult] Gets the user data from a #GAsyncResult. - + filename="gio/gasyncresult.c" + line="127">Gets the user data from a [iface@Gio.AsyncResult]. + the user data for @res. + filename="gio/gasyncresult.c" + line="133">the user data for @res. a #GAsyncResult. + filename="gio/gasyncresult.c" + line="129">a [iface@Gio.AsyncResult]. @@ -11105,22 +11835,22 @@ pointer indicating the function @res was created by). c:identifier="g_async_result_is_tagged" version="2.34"> Checks if @res has the given @source_tag (generally a function + filename="gio/gasyncresult.c" + line="210">Checks if @res has the given @source_tag (generally a function pointer indicating the function @res was created by). - + %TRUE if @res has the indicated @source_tag, %FALSE if + filename="gio/gasyncresult.c" + line="218">`TRUE` if @res has the indicated @source_tag, `FALSE` if not. a #GAsyncResult + filename="gio/gasyncresult.c" + line="212">a [iface@Gio.AsyncResult] nullable="1" allow-none="1"> an application-defined tag + filename="gio/gasyncresult.c" + line="213">an application-defined tag @@ -11139,30 +11869,30 @@ pointer indicating the function @res was created by). version="2.34" throws="1"> If @res is a #GSimpleAsyncResult, this is equivalent to -g_simple_async_result_propagate_error(). Otherwise it returns -%FALSE. + filename="gio/gasyncresult.c" + line="168">If @res is a [class@Gio.SimpleAsyncResult], this is equivalent to +[method@Gio.SimpleAsyncResult.propagate_error]. Otherwise it returns +`FALSE`. -This can be used for legacy error handling in async *_finish() -wrapper functions that traditionally handled #GSimpleAsyncResult +This can be used for legacy error handling in async `*_finish()` +wrapper functions that traditionally handled [class@Gio.SimpleAsyncResult] error returns themselves rather than calling into the virtual method. -This should not be used in new code; #GAsyncResult errors that are +This should not be used in new code; [iface@Gio.AsyncResult] errors that are set by virtual methods should also be extracted by virtual methods, to enable subclasses to chain up correctly. - + %TRUE if @error is has been filled in with an error from - @res, %FALSE if not. + filename="gio/gasyncresult.c" + line="184">`TRUE` if @error is has been filled in with an error from + @res, `FALSE` if not. a #GAsyncResult + filename="gio/gasyncresult.c" + line="170">a [iface@Gio.AsyncResult] @@ -11172,69 +11902,78 @@ to enable subclasses to chain up correctly. c:type="GAsyncResultIface" glib:is-gtype-struct-for="AsyncResult"> Interface definition for #GAsyncResult. - + filename="gio/gasyncresult.h" + line="42">Interface definition for [iface@Gio.AsyncResult]. + The parent interface. + filename="gio/gasyncresult.h" + line="44">The parent interface. + Gets the user data passed to the callback. - + the user data for @res. + filename="gio/gasyncresult.c" + line="133">the user data for @res. a #GAsyncResult. + filename="gio/gasyncresult.c" + line="129">a [iface@Gio.AsyncResult]. + Gets the source object that issued the asynchronous operation. - + a new reference to the source - object for the @res, or %NULL if there is none. + filename="gio/gasyncresult.c" + line="153">a new reference to the source + object for the @res, or `NULL` if there is none. a #GAsyncResult + filename="gio/gasyncresult.c" + line="149">a [iface@Gio.AsyncResult] + Checks if a result is tagged with a particular source. - + %TRUE if @res has the indicated @source_tag, %FALSE if + filename="gio/gasyncresult.c" + line="218">`TRUE` if @res has the indicated @source_tag, `FALSE` if not. a #GAsyncResult + filename="gio/gasyncresult.c" + line="212">a [iface@Gio.AsyncResult] nullable="1" allow-none="1"> an application-defined tag + filename="gio/gasyncresult.c" + line="213">an application-defined tag @@ -11253,7 +11992,7 @@ to enable subclasses to chain up correctly. - + @@ -11262,7 +12001,7 @@ to enable subclasses to chain up correctly. - + @@ -11271,7 +12010,7 @@ to enable subclasses to chain up correctly. - + @@ -11280,7 +12019,7 @@ to enable subclasses to chain up correctly. - + @@ -11289,7 +12028,7 @@ to enable subclasses to chain up correctly. - + @@ -11298,7 +12037,7 @@ to enable subclasses to chain up correctly. - + @@ -11307,7 +12046,7 @@ to enable subclasses to chain up correctly. - + @@ -11321,40 +12060,39 @@ to enable subclasses to chain up correctly. glib:get-type="g_buffered_input_stream_get_type" glib:type-struct="BufferedInputStreamClass"> Buffered input stream implements #GFilterInputStream and provides + filename="gio/gbufferedinputstream.c" + line="36">Buffered input stream implements [class@Gio.FilterInputStream] and provides for buffered reads. -By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. +By default, `GBufferedInputStream`'s buffer size is set at 4 kilobytes. -To create a buffered input stream, use g_buffered_input_stream_new(), -or g_buffered_input_stream_new_sized() to specify the buffer's size at +To create a buffered input stream, use [ctor@Gio.BufferedInputStream.new], +or [ctor@Gio.BufferedInputStream.new_sized] to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use -g_buffered_input_stream_get_buffer_size(). To change the size of a -buffered input stream's buffer, use -g_buffered_input_stream_set_buffer_size(). Note that the buffer's size -cannot be reduced below the size of the data within the buffer. - +[method@Gio.BufferedInputStream.get_buffer_size]. To change the size of a +buffered input stream's buffer, use [method@Gio.BufferedInputStream.set_buffer_size]. +Note that the buffer's size cannot be reduced below the size of the data within the buffer. + Creates a new #GInputStream from the given @base_stream, with + filename="gio/gbufferedinputstream.c" + line="320">Creates a new [class@Gio.InputStream] from the given @base_stream, with a buffer set to the default size (4 kilobytes). - + a #GInputStream for the given @base_stream. + filename="gio/gbufferedinputstream.c" + line="327">a [class@Gio.InputStream] for the given @base_stream. a #GInputStream + filename="gio/gbufferedinputstream.c" + line="322">a [class@Gio.InputStream] @@ -11362,39 +12100,43 @@ a buffer set to the default size (4 kilobytes). Creates a new #GBufferedInputStream from the given @base_stream, + filename="gio/gbufferedinputstream.c" + line="343">Creates a new [class@Gio.BufferedInputStream] from the given @base_stream, with a buffer set to @size. - + a #GInputStream. + filename="gio/gbufferedinputstream.c" + line="351">a [class@Gio.InputStream]. a #GInputStream + filename="gio/gbufferedinputstream.c" + line="345">a [class@Gio.InputStream] a #gsize + filename="gio/gbufferedinputstream.c" + line="346">a #gsize - + Tries to read @count bytes from the stream into the buffer. + filename="gio/gbufferedinputstream.c" + line="369">Tries to read @count bytes from the stream into the buffer. Will block during this read. If @count is zero, returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. +larger than `G_MAXSSIZE` will cause a +[error@Gio.IOErrorEnum.INVALID_ARGUMENT] error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it @@ -11404,35 +12146,35 @@ can happen e.g. near the end of a file. Zero is returned on end of file If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. -If @cancellable is not %NULL, then the operation can be cancelled by +If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the +was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. +If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. -On error -1 is returned and @error is set accordingly. +On error `-1` is returned and @error is set accordingly. For the asynchronous, non-blocking, version of this function, see -g_buffered_input_stream_fill_async(). - +[method@Gio.BufferedInputStream.fill_async]. + the number of bytes read into @stream's buffer, up to @count, - or -1 on error. + filename="gio/gbufferedinputstream.c" + line="402">the number of bytes read into @stream's buffer, up to @count, + or `-1` on error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="371">a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream + filename="gio/gbufferedinputstream.c" + line="372">the number of bytes that will be read from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gbufferedinputstream.c" + line="373">optional [class@Gio.Cancellable] object, `NULL` to ignore - + Reads data into @stream's buffer asynchronously, up to @count size. + filename="gio/gbufferedinputstream.c" + line="455">Reads data into @stream's buffer asynchronously, up to @count size. @io_priority can be used to prioritize reads. For the synchronous -version of this function, see g_buffered_input_stream_fill(). +version of this function, see [method@Gio.BufferedInputStream.fill]. -If @count is -1 then the attempted read size is equal to the number +If @count is `-1` then the attempted read size is equal to the number of bytes that are required to fill the buffer. - + a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="457">a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream + filename="gio/gbufferedinputstream.c" + line="458">the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request + filename="gio/gbufferedinputstream.c" + line="459">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object + filename="gio/gbufferedinputstream.c" + line="460">optional [class@Gio.Cancellable] object scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gbufferedinputstream.c" + line="461">a [callback@Gio.AsyncReadyCallback] allow-none="1" closure="4"> a #gpointer + filename="gio/gbufferedinputstream.c" + line="462">a #gpointer Finishes an asynchronous read. - + filename="gio/gbufferedinputstream.c" + line="521">Finishes an asynchronous read. + a #gssize of the read stream, or `-1` on an error. + filename="gio/gbufferedinputstream.c" + line="529">a #gssize of the read stream, or `-1` on an error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="523">a [class@Gio.BufferedInputStream] a #GAsyncResult + filename="gio/gbufferedinputstream.c" + line="524">a [iface@Gio.AsyncResult] + throws="1" + glib:async-func="fill_async"> Tries to read @count bytes from the stream into the buffer. + filename="gio/gbufferedinputstream.c" + line="369">Tries to read @count bytes from the stream into the buffer. Will block during this read. If @count is zero, returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. +larger than `G_MAXSSIZE` will cause a +[error@Gio.IOErrorEnum.INVALID_ARGUMENT] error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it @@ -11555,35 +12302,35 @@ can happen e.g. near the end of a file. Zero is returned on end of file If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. -If @cancellable is not %NULL, then the operation can be cancelled by +If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the +was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. +If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. -On error -1 is returned and @error is set accordingly. +On error `-1` is returned and @error is set accordingly. For the asynchronous, non-blocking, version of this function, see -g_buffered_input_stream_fill_async(). - +[method@Gio.BufferedInputStream.fill_async]. + the number of bytes read into @stream's buffer, up to @count, - or -1 on error. + filename="gio/gbufferedinputstream.c" + line="402">the number of bytes read into @stream's buffer, up to @count, + or `-1` on error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="371">a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream + filename="gio/gbufferedinputstream.c" + line="372">the number of bytes that will be read from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gbufferedinputstream.c" + line="373">optional [class@Gio.Cancellable] object, `NULL` to ignore + c:identifier="g_buffered_input_stream_fill_async" + glib:finish-func="fill_finish" + glib:sync-func="fill"> Reads data into @stream's buffer asynchronously, up to @count size. + filename="gio/gbufferedinputstream.c" + line="455">Reads data into @stream's buffer asynchronously, up to @count size. @io_priority can be used to prioritize reads. For the synchronous -version of this function, see g_buffered_input_stream_fill(). +version of this function, see [method@Gio.BufferedInputStream.fill]. -If @count is -1 then the attempted read size is equal to the number +If @count is `-1` then the attempted read size is equal to the number of bytes that are required to fill the buffer. - + a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="457">a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream + filename="gio/gbufferedinputstream.c" + line="458">the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request + filename="gio/gbufferedinputstream.c" + line="459">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object + filename="gio/gbufferedinputstream.c" + line="460">optional [class@Gio.Cancellable] object scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gbufferedinputstream.c" + line="461">a [callback@Gio.AsyncReadyCallback] nullable="1" allow-none="1"> a #gpointer + filename="gio/gbufferedinputstream.c" + line="462">a #gpointer @@ -11665,26 +12414,26 @@ of bytes that are required to fill the buffer. c:identifier="g_buffered_input_stream_fill_finish" throws="1"> Finishes an asynchronous read. - + filename="gio/gbufferedinputstream.c" + line="521">Finishes an asynchronous read. + a #gssize of the read stream, or `-1` on an error. + filename="gio/gbufferedinputstream.c" + line="529">a #gssize of the read stream, or `-1` on an error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="523">a [class@Gio.BufferedInputStream] a #GAsyncResult + filename="gio/gbufferedinputstream.c" + line="524">a [iface@Gio.AsyncResult] @@ -11692,20 +12441,20 @@ of bytes that are required to fill the buffer. Gets the size of the available data within the stream. - + filename="gio/gbufferedinputstream.c" + line="550">Gets the size of the available data within the stream. + size of the available stream. + filename="gio/gbufferedinputstream.c" + line="556">size of the available stream. #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="552">[class@Gio.BufferedInputStream] @@ -11714,47 +12463,47 @@ of bytes that are required to fill the buffer. c:identifier="g_buffered_input_stream_get_buffer_size" glib:get-property="buffer-size"> Gets the size of the input buffer. - + filename="gio/gbufferedinputstream.c" + line="177">Gets the size of the input buffer. + the current buffer size. + filename="gio/gbufferedinputstream.c" + line="183">the current buffer size. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="179">a [class@Gio.BufferedInputStream] Peeks in the buffer, copying data of size @count into @buffer, + filename="gio/gbufferedinputstream.c" + line="566">Peeks in the buffer, copying data of size @count into @buffer, offset @offset bytes. - + a #gsize of the number of bytes peeked, or -1 on error. + filename="gio/gbufferedinputstream.c" + line="577">a #gsize of the number of bytes peeked, or `-1` on error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="568">a [class@Gio.BufferedInputStream] a pointer to + filename="gio/gbufferedinputstream.c" + line="569">a pointer to an allocated chunk of memory @@ -11762,14 +12511,14 @@ offset @offset bytes. a #gsize + filename="gio/gbufferedinputstream.c" + line="571">a #gsize a #gsize + filename="gio/gbufferedinputstream.c" + line="572">a #gsize @@ -11777,15 +12526,15 @@ offset @offset bytes. Returns the buffer with the currently available bytes. The returned + filename="gio/gbufferedinputstream.c" + line="603">Returns the buffer with the currently available bytes. The returned buffer must not be modified and will become invalid when reading from the stream or filling the buffer. - + + filename="gio/gbufferedinputstream.c" + line="612"> read-only buffer @@ -11794,8 +12543,8 @@ the stream or filling the buffer. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="605">a [class@Gio.BufferedInputStream] caller-allocates="0" transfer-ownership="full"> a #gsize to get the number of bytes available in the buffer + filename="gio/gbufferedinputstream.c" + line="606">a #gsize to get the number of bytes available in the buffer @@ -11813,32 +12562,32 @@ the stream or filling the buffer. c:identifier="g_buffered_input_stream_read_byte" throws="1"> Tries to read a single byte from the stream or the buffer. Will block + filename="gio/gbufferedinputstream.c" + line="944">Tries to read a single byte from the stream or the buffer. Will block during this read. On success, the byte read from the stream is returned. On end of stream --1 is returned but it's not an exceptional error and @error is not set. +`-1` is returned but it's not an exceptional error and @error is not set. -If @cancellable is not %NULL, then the operation can be cancelled by +If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the +was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. +If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. -On error -1 is returned and @error is set accordingly. - +On error `-1` is returned and @error is set accordingly. + the byte read from the @stream, or -1 on end of stream or error. + filename="gio/gbufferedinputstream.c" + line="964">the byte read from the @stream, or `-1` on end of stream or error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="946">a [class@Gio.BufferedInputStream] nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gbufferedinputstream.c" + line="947">optional [class@Gio.Cancellable] object, `NULL` to ignore @@ -11856,25 +12605,25 @@ On error -1 is returned and @error is set accordingly. c:identifier="g_buffered_input_stream_set_buffer_size" glib:set-property="buffer-size"> Sets the size of the internal buffer of @stream to @size, or to the + filename="gio/gbufferedinputstream.c" + line="193">Sets the size of the internal buffer of @stream to @size, or to the size of the contents of the buffer. The buffer can never be resized smaller than its current contents. - + a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="195">a [class@Gio.BufferedInputStream] a #gsize + filename="gio/gbufferedinputstream.c" + line="196">a #gsize @@ -11886,6 +12635,9 @@ smaller than its current contents. setter="set_buffer_size" getter="get_buffer_size" default-value="4096"> + The size of the backend buffer, in bytes. @@ -11899,31 +12651,31 @@ smaller than its current contents. - + - + the number of bytes read into @stream's buffer, up to @count, - or -1 on error. + filename="gio/gbufferedinputstream.c" + line="402">the number of bytes read into @stream's buffer, up to @count, + or `-1` on error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="371">a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream + filename="gio/gbufferedinputstream.c" + line="372">the number of bytes that will be read from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gbufferedinputstream.c" + line="373">optional [class@Gio.Cancellable] object, `NULL` to ignore @@ -11940,27 +12692,27 @@ smaller than its current contents. - + a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="457">a [class@Gio.BufferedInputStream] the number of bytes that will be read from the stream + filename="gio/gbufferedinputstream.c" + line="458">the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request + filename="gio/gbufferedinputstream.c" + line="459">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object + filename="gio/gbufferedinputstream.c" + line="460">optional [class@Gio.Cancellable] object scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gbufferedinputstream.c" + line="461">a [callback@Gio.AsyncReadyCallback] allow-none="1" closure="5"> a #gpointer + filename="gio/gbufferedinputstream.c" + line="462">a #gpointer @@ -11998,24 +12750,24 @@ smaller than its current contents. - + a #gssize of the read stream, or `-1` on an error. + filename="gio/gbufferedinputstream.c" + line="529">a #gssize of the read stream, or `-1` on an error. a #GBufferedInputStream + filename="gio/gbufferedinputstream.c" + line="523">a [class@Gio.BufferedInputStream] a #GAsyncResult + filename="gio/gbufferedinputstream.c" + line="524">a [iface@Gio.AsyncResult] @@ -12023,7 +12775,7 @@ smaller than its current contents. - + @@ -12031,7 +12783,7 @@ smaller than its current contents. - + @@ -12039,7 +12791,7 @@ smaller than its current contents. - + @@ -12047,7 +12799,7 @@ smaller than its current contents. - + @@ -12055,7 +12807,7 @@ smaller than its current contents. - + @@ -12066,7 +12818,7 @@ smaller than its current contents. c:type="GBufferedInputStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_buffered_output_stream_get_type" glib:type-struct="BufferedOutputStreamClass"> Buffered output stream implements #GFilterOutputStream and provides + filename="gio/gbufferedoutputstream.c" + line="32">Buffered output stream implements [class@Gio.FilterOutputStream] and provides for buffered writes. -By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. +By default, `GBufferedOutputStream`'s buffer size is set at 4 kilobytes. -To create a buffered output stream, use g_buffered_output_stream_new(), -or g_buffered_output_stream_new_sized() to specify the buffer's size +To create a buffered output stream, use [ctor@Gio.BufferedOutputStream.new], +or [ctor@Gio.BufferedOutputStream.new_sized] to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use -g_buffered_output_stream_get_buffer_size(). To change the size of a -buffered output stream's buffer, use -g_buffered_output_stream_set_buffer_size(). Note that the buffer's -size cannot be reduced below the size of the data within the buffer. - +[method@Gio.BufferedOutputStream.get_buffer_size]. To change the size of a +buffered output stream's buffer, use [method@Gio.BufferedOutputStream.set_buffer_size]. +Note that the buffer's size cannot be reduced below the size of the data within the buffer. + Creates a new buffered output stream for a base stream. - + filename="gio/gbufferedoutputstream.c" + line="362">Creates a new buffered output stream for a base stream. + a #GOutputStream for the given @base_stream. + filename="gio/gbufferedoutputstream.c" + line="368">a [class@Gio.OutputStream] for the given @base_stream. a #GOutputStream. + filename="gio/gbufferedoutputstream.c" + line="364">a [class@Gio.OutputStream]. @@ -12116,26 +12867,26 @@ size cannot be reduced below the size of the data within the buffer. Creates a new buffered output stream with a given buffer size. - + filename="gio/gbufferedoutputstream.c" + line="384">Creates a new buffered output stream with a given buffer size. + a #GOutputStream with an internal buffer set to @size. + filename="gio/gbufferedoutputstream.c" + line="391">a [class@Gio.OutputStream] with an internal buffer set to @size. a #GOutputStream. + filename="gio/gbufferedoutputstream.c" + line="386">a [class@Gio.OutputStream]. a #gsize. + filename="gio/gbufferedoutputstream.c" + line="387">a #gsize. @@ -12144,21 +12895,21 @@ size cannot be reduced below the size of the data within the buffer. c:identifier="g_buffered_output_stream_get_auto_grow" glib:get-property="auto-grow"> Checks if the buffer automatically grows as data is added. - + filename="gio/gbufferedoutputstream.c" + line="234">Checks if the buffer automatically grows as data is added. + %TRUE if the @stream's buffer automatically grows, -%FALSE otherwise. + filename="gio/gbufferedoutputstream.c" + line="240">`TRUE` if the @stream's buffer automatically grows, +`FALSE` otherwise. a #GBufferedOutputStream. + filename="gio/gbufferedoutputstream.c" + line="236">a [class@Gio.BufferedOutputStream]. @@ -12167,20 +12918,20 @@ size cannot be reduced below the size of the data within the buffer. c:identifier="g_buffered_output_stream_get_buffer_size" glib:get-property="buffer-size"> Gets the size of the buffer in the @stream. - + filename="gio/gbufferedoutputstream.c" + line="176">Gets the size of the buffer in the @stream. + the current size of the buffer. + filename="gio/gbufferedoutputstream.c" + line="182">the current size of the buffer. a #GBufferedOutputStream. + filename="gio/gbufferedoutputstream.c" + line="178">a [class@Gio.BufferedOutputStream]. @@ -12189,26 +12940,26 @@ size cannot be reduced below the size of the data within the buffer. c:identifier="g_buffered_output_stream_set_auto_grow" glib:set-property="auto-grow"> Sets whether or not the @stream's buffer should automatically grow. + filename="gio/gbufferedoutputstream.c" + line="251">Sets whether or not the @stream's buffer should automatically grow. If @auto_grow is true, then each write will just make the buffer larger, and you must manually flush the buffer to actually write out the data to the underlying stream. - + a #GBufferedOutputStream. + filename="gio/gbufferedoutputstream.c" + line="253">a [class@Gio.BufferedOutputStream]. a #gboolean. + filename="gio/gbufferedoutputstream.c" + line="254">a #gboolean. @@ -12217,23 +12968,23 @@ the data to the underlying stream. c:identifier="g_buffered_output_stream_set_buffer_size" glib:set-property="buffer-size"> Sets the size of the internal buffer to @size. - + filename="gio/gbufferedoutputstream.c" + line="192">Sets the size of the internal buffer to @size. + a #GBufferedOutputStream. + filename="gio/gbufferedoutputstream.c" + line="194">a [class@Gio.BufferedOutputStream]. a #gsize. + filename="gio/gbufferedoutputstream.c" + line="195">a #gsize. @@ -12244,6 +12995,9 @@ the data to the underlying stream. setter="set_auto_grow" getter="get_auto_grow" default-value="FALSE"> + Whether the buffer should automatically grow. setter="set_buffer_size" getter="get_buffer_size" default-value="4096"> + The size of the backend buffer, in bytes. @@ -12266,14 +13023,14 @@ the data to the underlying stream. - + - + @@ -12281,7 +13038,7 @@ the data to the underlying stream. - + @@ -12292,28 +13049,28 @@ the data to the underlying stream. c:type="GBufferedOutputStreamPrivate" disguised="1" opaque="1"> - + Invoked when a connection to a message bus has been obtained. - + The #GDBusConnection to a message bus. The name that is requested to be owned. @@ -12323,7 +13080,7 @@ the data to the underlying stream. allow-none="1" closure="2"> User data passed to g_bus_own_name(). @@ -12333,22 +13090,22 @@ the data to the underlying stream. c:type="GBusNameAcquiredCallback" version="2.26"> Invoked when the name is acquired. - + The #GDBusConnection on which to acquired the name. The name being owned. @@ -12358,7 +13115,7 @@ the data to the underlying stream. allow-none="1" closure="2"> User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). @@ -12368,28 +13125,28 @@ the data to the underlying stream. c:type="GBusNameAppearedCallback" version="2.26"> Invoked when the name being watched is known to have to have an owner. - + The #GDBusConnection the name is being watched on. The name being watched. Unique name of the owner of the name being watched. @@ -12399,7 +13156,7 @@ the data to the underlying stream. allow-none="1" closure="3"> User data passed to g_bus_watch_name(). @@ -12409,23 +13166,23 @@ the data to the underlying stream. c:type="GBusNameLostCallback" version="2.26"> Invoked when the name is lost or @connection has been closed. - + The #GDBusConnection on which to acquire the name or %NULL if the connection was disconnected. The name being owned. @@ -12435,7 +13192,7 @@ the connection was disconnected. allow-none="1" closure="2"> User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). @@ -12447,16 +13204,16 @@ the connection was disconnected. glib:get-type="g_bus_name_owner_flags_get_type" c:type="GBusNameOwnerFlags"> Flags used in g_bus_own_name(). + filename="gio/gioenums.h" + line="984">Flags used in g_bus_own_name(). No flags set. + filename="gio/gioenums.h" + line="986">No flags set. glib:nick="allow-replacement" glib:name="G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT"> Allow another message bus connection to claim the name. + filename="gio/gioenums.h" + line="987">Allow another message bus connection to claim the name. glib:nick="replace" glib:name="G_BUS_NAME_OWNER_FLAGS_REPLACE"> If another message bus connection owns the name and have + filename="gio/gioenums.h" + line="988">If another message bus connection owns the name and have specified %G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. If another message bus connection owns the name, immediately + filename="gio/gioenums.h" + line="990">If another message bus connection owns the name, immediately return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54) @@ -12492,27 +13249,27 @@ return an error from g_bus_own_name() rather than entering the waiting queue for c:type="GBusNameVanishedCallback" version="2.26"> Invoked when the name being watched is known not to have to have an owner. This is also invoked when the #GDBusConnection on which the watch was established has been closed. In that case, @connection will be %NULL. - + The #GDBusConnection the name is being watched on, or %NULL. The name being watched. @@ -12522,7 +13279,7 @@ established has been closed. In that case, @connection will be allow-none="1" closure="2"> User data passed to g_bus_watch_name(). @@ -12534,16 +13291,16 @@ established has been closed. In that case, @connection will be glib:get-type="g_bus_name_watcher_flags_get_type" c:type="GBusNameWatcherFlags"> Flags used in g_bus_watch_name(). + filename="gio/gioenums.h" + line="1007">Flags used in g_bus_watch_name(). No flags set. + filename="gio/gioenums.h" + line="1009">No flags set. If no-one owns the name when + filename="gio/gioenums.h" + line="1010">If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name. @@ -12563,16 +13320,16 @@ name. glib:get-type="g_bus_type_get_type" c:type="GBusType"> An enumeration for well-known message buses. + filename="gio/gioenums.h" + line="965">An enumeration for well-known message buses. An alias for the message bus that activated the process, if any. + filename="gio/gioenums.h" + line="967">An alias for the message bus that activated the process, if any. glib:nick="none" glib:name="G_BUS_TYPE_NONE"> Not a message bus. + filename="gio/gioenums.h" + line="968">Not a message bus. glib:nick="system" glib:name="G_BUS_TYPE_SYSTEM"> The system-wide message bus. + filename="gio/gioenums.h" + line="969">The system-wide message bus. glib:nick="session" glib:name="G_BUS_TYPE_SESSION"> The login session message bus. + filename="gio/gioenums.h" + line="970">The login session message bus. glib:type-name="GBytesIcon" glib:get-type="g_bytes_icon_get_type"> #GBytesIcon specifies an image held in memory in a common format (usually -png) to be used as icon. + filename="gio/gbytesicon.c" + line="35">`GBytesIcon` specifies an image held in memory in a common format (usually +PNG) to be used as icon. Creates a new icon for a bytes. + filename="gio/gbytesicon.c" + line="140">Creates a new icon for a bytes. This cannot fail, but loading and interpreting the bytes may fail later on (for example, if g_loadable_icon_load() is called) if the image is invalid. - + a #GIcon for the given + filename="gio/gbytesicon.c" + line="149">a #GIcon for the given @bytes. a #GBytes. + filename="gio/gbytesicon.c" + line="142">a #GBytes. @@ -12644,20 +13401,20 @@ This cannot fail, but loading and interpreting the bytes may fail later on glib:get-property="bytes" version="2.38"> Gets the #GBytes associated with the given @icon. - + filename="gio/gbytesicon.c" + line="162">Gets the #GBytes associated with the given @icon. + a #GBytes. + filename="gio/gbytesicon.c" + line="168">a #GBytes. a #GIcon. + filename="gio/gbytesicon.c" + line="164">a #GIcon. @@ -12668,15 +13425,15 @@ This cannot fail, but loading and interpreting the bytes may fail later on transfer-ownership="none" getter="get_bytes"> The bytes containing the icon. + filename="gio/gbytesicon.c" + line="124">The bytes containing the icon. - + @@ -12685,7 +13442,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12694,7 +13451,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12703,7 +13460,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12712,7 +13469,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12721,7 +13478,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12730,7 +13487,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12739,7 +13496,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12748,7 +13505,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12757,7 +13514,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12766,7 +13523,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12775,7 +13532,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12784,7 +13541,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12793,7 +13550,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12802,7 +13559,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12811,7 +13568,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12820,7 +13577,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + @@ -12834,15 +13591,17 @@ This cannot fail, but loading and interpreting the bytes may fail later on glib:get-type="g_cancellable_get_type" glib:type-struct="CancellableClass"> GCancellable is a thread-safe operation cancellation stack used + filename="gio/gcancellable.c" + line="33">`GCancellable` allows operations to be cancelled. + +`GCancellable` is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations. - + Creates a new #GCancellable object. + filename="gio/gcancellable.c" + line="166">Creates a new #GCancellable object. Applications that want to start one or more operations that should be cancellable should create a #GCancellable @@ -12850,29 +13609,29 @@ and pass it to the operations. One #GCancellable can be used in multiple consecutive operations or in multiple concurrent operations. - + a #GCancellable. + filename="gio/gcancellable.c" + line="178">a #GCancellable. Gets the top cancellable from the stack. - + filename="gio/gcancellable.c" + line="232">Gets the top cancellable from the stack. + a #GCancellable from the top + filename="gio/gcancellable.c" + line="237">a #GCancellable from the top of the stack, or %NULL if the stack is empty. - + @@ -12887,8 +13646,8 @@ of the stack, or %NULL if the stack is empty. Will set @cancellable to cancelled, and will emit the + filename="gio/gcancellable.c" + line="467">Will set @cancellable to cancelled, and will emit the #GCancellable::cancelled signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.) @@ -12904,7 +13663,7 @@ operation causes it to complete asynchronously. That is, if you cancel the operation from the same thread in which it is running, then the operation's #GAsyncReadyCallback will not be invoked until the application returns to the main loop. - + @@ -12914,8 +13673,8 @@ the application returns to the main loop. nullable="1" allow-none="1"> a #GCancellable object. + filename="gio/gcancellable.c" + line="469">a #GCancellable object. @@ -12924,14 +13683,16 @@ the application returns to the main loop. c:identifier="g_cancellable_connect" version="2.22"> Convenience function to connect to the #GCancellable::cancelled + filename="gio/gcancellable.c" + line="526">Convenience function to connect to the #GCancellable::cancelled signal. Also handles the race condition that may happen if the cancellable is cancelled right before connecting. -@callback is called at most once, either directly at the -time of the connect if @cancellable is already cancelled, -or when @cancellable is cancelled in some thread. +@callback is called exactly once each time @cancellable is cancelled, +either directly at the time of the connect if @cancellable is already +cancelled, or when @cancellable is cancelled in some thread. +In case the cancellable is reset via [method@Gio.Cancellable.reset] +then the callback can be called again if the @cancellable is cancelled. @data_destroy_func will be called when the handler is disconnected, or immediately if the cancellable is already @@ -12943,11 +13704,11 @@ Since GLib 2.40, the lock protecting @cancellable is not held when @callback is invoked. This lifts a restriction in place for earlier GLib versions which now makes it easier to write cleanup code that unconditionally invokes e.g. g_cancellable_cancel(). - + The id of the signal handler or 0 if @cancellable has already + filename="gio/gcancellable.c" + line="554">The id of the signal handler or 0 if @cancellable has already been cancelled. @@ -12957,8 +13718,8 @@ code that unconditionally invokes e.g. g_cancellable_cancel(). nullable="1" allow-none="1"> A #GCancellable. + filename="gio/gcancellable.c" + line="528">A #GCancellable. closure="1" destroy="2"> The #GCallback to connect. + filename="gio/gcancellable.c" + line="529">The #GCallback to connect. nullable="1" allow-none="1"> Data to pass to @callback. + filename="gio/gcancellable.c" + line="530">Data to pass to @callback. allow-none="1" scope="async"> Free function for @data or %NULL. + filename="gio/gcancellable.c" + line="531">Free function for @data or %NULL. @@ -12996,8 +13757,8 @@ code that unconditionally invokes e.g. g_cancellable_cancel(). c:identifier="g_cancellable_disconnect" version="2.22"> Disconnects a handler from a cancellable instance similar to + filename="gio/gcancellable.c" + line="597">Disconnects a handler from a cancellable instance similar to g_signal_handler_disconnect(). Additionally, in the event that a signal handler is currently running, this call will block until the handler has finished. Calling this function from a @@ -13011,7 +13772,7 @@ details on how to use this. If @cancellable is %NULL or @handler_id is `0` this function does nothing. - + @@ -13021,22 +13782,22 @@ nothing. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gcancellable.c" + line="599">A #GCancellable or %NULL. Handler id of the handler to be disconnected, or `0`. + filename="gio/gcancellable.c" + line="600">Handler id of the handler to be disconnected, or `0`. Gets the file descriptor for a cancellable job. This can be used to + filename="gio/gcancellable.c" + line="329">Gets the file descriptor for a cancellable job. This can be used to implement cancellable operations on Unix systems. The returned fd will turn readable when @cancellable is cancelled. @@ -13049,11 +13810,11 @@ g_cancellable_release_fd() to free up resources allocated for the returned file descriptor. See also g_cancellable_make_pollfd(). - + A valid file descriptor. `-1` if the file descriptor + filename="gio/gcancellable.c" + line="347">A valid file descriptor. `-1` if the file descriptor is not supported, or on errors. @@ -13063,21 +13824,21 @@ is not supported, or on errors. nullable="1" allow-none="1"> a #GCancellable. + filename="gio/gcancellable.c" + line="331">a #GCancellable. Checks if a cancellable job has been cancelled. - + filename="gio/gcancellable.c" + line="288">Checks if a cancellable job has been cancelled. + %TRUE if @cancellable is cancelled, + filename="gio/gcancellable.c" + line="294">%TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled. @@ -13087,8 +13848,8 @@ FALSE if called with %NULL or if item is not cancelled. nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gcancellable.c" + line="290">a #GCancellable or %NULL @@ -13097,8 +13858,8 @@ FALSE if called with %NULL or if item is not cancelled. c:identifier="g_cancellable_make_pollfd" version="2.22"> Creates a #GPollFD corresponding to @cancellable; this can be passed + filename="gio/gcancellable.c" + line="371">Creates a #GPollFD corresponding to @cancellable; this can be passed to g_poll() and used to poll for cancellation. This is useful both for unix systems without a native poll and for portability to windows. @@ -13116,11 +13877,11 @@ these cases is to ignore the @cancellable. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with g_cancellable_reset(). - + %TRUE if @pollfd was successfully initialized, %FALSE on + filename="gio/gcancellable.c" + line="395">%TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable. @@ -13130,24 +13891,24 @@ with g_cancellable_reset(). nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gcancellable.c" + line="373">a #GCancellable or %NULL a pointer to a #GPollFD + filename="gio/gcancellable.c" + line="374">a pointer to a #GPollFD Pops @cancellable off the cancellable stack (verifying that @cancellable + filename="gio/gcancellable.c" + line="211">Pops @cancellable off the cancellable stack (verifying that @cancellable is on the top of the stack). - + @@ -13157,16 +13918,16 @@ is on the top of the stack). nullable="1" allow-none="1"> a #GCancellable object + filename="gio/gcancellable.c" + line="213">a #GCancellable object Pushes @cancellable onto the cancellable stack. The current + filename="gio/gcancellable.c" + line="186">Pushes @cancellable onto the cancellable stack. The current cancellable can then be received using g_cancellable_get_current(). This is useful when implementing cancellable operations in @@ -13174,7 +13935,7 @@ code that does not allow you to pass down the cancellable object. This is typically called automatically by e.g. #GFile operations, so you rarely have to call this yourself. - + @@ -13184,8 +13945,8 @@ so you rarely have to call this yourself. nullable="1" allow-none="1"> a #GCancellable object + filename="gio/gcancellable.c" + line="188">a #GCancellable object @@ -13194,8 +13955,8 @@ so you rarely have to call this yourself. c:identifier="g_cancellable_release_fd" version="2.22"> Releases a resources previously allocated by g_cancellable_get_fd() + filename="gio/gcancellable.c" + line="430">Releases a resources previously allocated by g_cancellable_get_fd() or g_cancellable_make_pollfd(). For compatibility reasons with older releases, calling this function @@ -13204,7 +13965,7 @@ when the @cancellable is finalized. However, the @cancellable will block scarce file descriptors until it is finalized if this function is not called. This can cause the application to run out of file descriptors when many #GCancellables are used at the same time. - + @@ -13214,16 +13975,16 @@ descriptors when many #GCancellables are used at the same time. nullable="1" allow-none="1"> a #GCancellable + filename="gio/gcancellable.c" + line="432">a #GCancellable Resets @cancellable to its uncancelled state. + filename="gio/gcancellable.c" + line="252">Resets @cancellable to its uncancelled state. If cancellable is currently in use by any cancellable operation then the behavior of this function is undefined. @@ -13234,7 +13995,7 @@ as this function might tempt you to do. The recommended practice is to drop the reference to a cancellable after cancelling it, and let it die with the outstanding async operations. You should create a fresh cancellable for further async operations. - + @@ -13244,8 +14005,8 @@ create a fresh cancellable for further async operations. nullable="1" allow-none="1"> a #GCancellable object. + filename="gio/gcancellable.c" + line="254">a #GCancellable object. @@ -13254,14 +14015,14 @@ create a fresh cancellable for further async operations. c:identifier="g_cancellable_set_error_if_cancelled" throws="1"> If the @cancellable is cancelled, sets the error to notify + filename="gio/gcancellable.c" + line="303">If the @cancellable is cancelled, sets the error to notify that the operation was cancelled. - + %TRUE if @cancellable was cancelled, %FALSE if it was not + filename="gio/gcancellable.c" + line="311">%TRUE if @cancellable was cancelled, %FALSE if it was not @@ -13270,8 +14031,8 @@ that the operation was cancelled. nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gcancellable.c" + line="305">a #GCancellable or %NULL @@ -13280,8 +14041,8 @@ that the operation was cancelled. c:identifier="g_cancellable_source_new" version="2.28"> Creates a source that triggers if @cancellable is cancelled and + filename="gio/gcancellable.c" + line="792">Creates a source that triggers if @cancellable is cancelled and calls its callback of type #GCancellableSourceFunc. This is primarily useful for attaching to another (non-cancellable) source with g_source_add_child_source() to add cancellability to it. @@ -13290,11 +14051,11 @@ For convenience, you can call this with a %NULL #GCancellable, in which case the source will never trigger. The new #GSource will hold a reference to the #GCancellable. - + the new #GSource. + filename="gio/gcancellable.c" + line="806">the new #GSource. @@ -13303,8 +14064,8 @@ The new #GSource will hold a reference to the #GCancellable. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gcancellable.c" + line="794">a #GCancellable, or %NULL @@ -13317,8 +14078,8 @@ The new #GSource will hold a reference to the #GCancellable. Emitted when the operation has been cancelled. + filename="gio/gcancellable.c" + line="91">Emitted when the operation has been cancelled. Can be used by implementations of cancellable operations. If the operation is cancelled from another thread, the signal will be @@ -13377,13 +14138,13 @@ cancellable signal should not do something that can block. - + - + @@ -13399,7 +14160,7 @@ cancellable signal should not do something that can block. - + @@ -13407,7 +14168,7 @@ cancellable signal should not do something that can block. - + @@ -13415,7 +14176,7 @@ cancellable signal should not do something that can block. - + @@ -13423,7 +14184,7 @@ cancellable signal should not do something that can block. - + @@ -13431,7 +14192,7 @@ cancellable signal should not do something that can block. - + @@ -13442,20 +14203,20 @@ cancellable signal should not do something that can block. c:type="GCancellablePrivate" disguised="1" opaque="1"> - + This is the function type of the callback used for the #GSource + filename="gio/giotypes.h" + line="484">This is the function type of the callback used for the #GSource returned by g_cancellable_source_new(). - + it should return %FALSE if the source should be removed. + filename="gio/giotypes.h" + line="492">it should return %FALSE if the source should be removed. @@ -13464,8 +14225,8 @@ returned by g_cancellable_source_new(). nullable="1" allow-none="1"> the #GCancellable + filename="gio/giotypes.h" + line="486">the #GCancellable nullable="1" allow-none="1"> data passed in by the user. + filename="gio/giotypes.h" + line="487">data passed in by the user. @@ -13487,10 +14248,10 @@ returned by g_cancellable_source_new(). glib:get-type="g_charset_converter_get_type" glib:type-struct="CharsetConverterClass"> #GCharsetConverter is an implementation of #GConverter based on -GIConv. - + filename="gio/gcharsetconverter.c" + line="41">`GCharsetConverter` is an implementation of [iface@Gio.Converter] based on +[struct@GLib.IConv]. + version="2.24" throws="1"> Creates a new #GCharsetConverter. - + filename="gio/gcharsetconverter.c" + line="205">Creates a new #GCharsetConverter. + a new #GCharsetConverter or %NULL on error. + filename="gio/gcharsetconverter.c" + line="213">a new #GCharsetConverter or %NULL on error. destination charset + filename="gio/gcharsetconverter.c" + line="207">destination charset source charset + filename="gio/gcharsetconverter.c" + line="208">source charset @@ -13526,20 +14287,20 @@ GIConv. c:identifier="g_charset_converter_get_num_fallbacks" version="2.24"> Gets the number of fallbacks that @converter has applied so far. - + filename="gio/gcharsetconverter.c" + line="419">Gets the number of fallbacks that @converter has applied so far. + the number of fallbacks that @converter has applied + filename="gio/gcharsetconverter.c" + line="425">the number of fallbacks that @converter has applied a #GCharsetConverter + filename="gio/gcharsetconverter.c" + line="421">a #GCharsetConverter @@ -13549,20 +14310,20 @@ GIConv. glib:get-property="use-fallback" version="2.24"> Gets the #GCharsetConverter:use-fallback property. - + filename="gio/gcharsetconverter.c" + line="403">Gets the #GCharsetConverter:use-fallback property. + %TRUE if fallbacks are used by @converter + filename="gio/gcharsetconverter.c" + line="409">%TRUE if fallbacks are used by @converter a #GCharsetConverter + filename="gio/gcharsetconverter.c" + line="405">a #GCharsetConverter @@ -13572,55 +14333,67 @@ GIConv. glib:set-property="use-fallback" version="2.24"> Sets the #GCharsetConverter:use-fallback property. - + filename="gio/gcharsetconverter.c" + line="381">Sets the #GCharsetConverter:use-fallback property. + a #GCharsetConverter + filename="gio/gcharsetconverter.c" + line="383">a #GCharsetConverter %TRUE to use fallbacks + filename="gio/gcharsetconverter.c" + line="384">%TRUE to use fallbacks + The character encoding to convert from. + The character encoding to convert to. + Use fallback (of form `\<hexval>`) for invalid bytes. - + @@ -13633,22 +14406,24 @@ GIConv. glib:get-type="g_converter_get_type" glib:type-struct="ConverterIface"> #GConverter is implemented by objects that convert + filename="gio/gconverter.c" + line="31">`GConverter` is an interface for streaming conversions. + +`GConverter` is implemented by objects that convert binary data in various ways. The conversion can be stateful and may fail at any place. Some example conversions are: character set conversion, compression, decompression and regular expression replace. - + This is the main operation used when converting data. It is to be called + filename="gio/gconverter.c" + line="56">This is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in @outbuf) or consuming some input (from @inbuf) or both. If its not possible to do any work an error is returned. @@ -13730,18 +14505,18 @@ Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically %G_IO_ERROR_PARTIAL_INPUT). - + a #GConverterResult, %G_CONVERTER_ERROR on error. + filename="gio/gconverter.c" + line="155">a #GConverterResult, %G_CONVERTER_ERROR on error. a #GConverter. + filename="gio/gconverter.c" + line="58">a #GConverter. the buffer + filename="gio/gconverter.c" + line="59">the buffer containing the data to convert. @@ -13758,14 +14533,14 @@ to produce as much output as possible and then return an error the number of bytes in @inbuf + filename="gio/gconverter.c" + line="61">the number of bytes in @inbuf a + filename="gio/gconverter.c" + line="62">a buffer to write converted data in. @@ -13773,14 +14548,14 @@ to produce as much output as possible and then return an error the number of bytes in @outbuf, must be at least one + filename="gio/gconverter.c" + line="64">the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details + filename="gio/gconverter.c" + line="65">a #GConverterFlags controlling the conversion details will be set to the number of bytes read + filename="gio/gconverter.c" + line="66">will be set to the number of bytes read from @inbuf on success @@ -13798,8 +14573,8 @@ to produce as much output as possible and then return an error caller-allocates="0" transfer-ownership="full"> will be set to the number of bytes + filename="gio/gconverter.c" + line="68">will be set to the number of bytes written to @outbuf on success @@ -13807,19 +14582,19 @@ to produce as much output as possible and then return an error Resets all internal state in the converter, making it behave + filename="gio/gconverter.c" + line="192">Resets all internal state in the converter, making it behave as if it was just created. If the converter has any internal state that would produce output then that output is lost. - + a #GConverter. + filename="gio/gconverter.c" + line="194">a #GConverter. @@ -13829,8 +14604,8 @@ state that would produce output then that output is lost. version="2.24" throws="1"> This is the main operation used when converting data. It is to be called + filename="gio/gconverter.c" + line="56">This is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in @outbuf) or consuming some input (from @inbuf) or both. If its not possible to do any work an error is returned. @@ -13912,24 +14687,24 @@ Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically %G_IO_ERROR_PARTIAL_INPUT). - + a #GConverterResult, %G_CONVERTER_ERROR on error. + filename="gio/gconverter.c" + line="155">a #GConverterResult, %G_CONVERTER_ERROR on error. a #GConverter. + filename="gio/gconverter.c" + line="58">a #GConverter. the buffer + filename="gio/gconverter.c" + line="59">the buffer containing the data to convert. @@ -13937,14 +14712,14 @@ to produce as much output as possible and then return an error the number of bytes in @inbuf + filename="gio/gconverter.c" + line="61">the number of bytes in @inbuf a + filename="gio/gconverter.c" + line="62">a buffer to write converted data in. @@ -13952,14 +14727,14 @@ to produce as much output as possible and then return an error the number of bytes in @outbuf, must be at least one + filename="gio/gconverter.c" + line="64">the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details + filename="gio/gconverter.c" + line="65">a #GConverterFlags controlling the conversion details will be set to the number of bytes read + filename="gio/gconverter.c" + line="66">will be set to the number of bytes read from @inbuf on success @@ -13977,28 +14752,59 @@ to produce as much output as possible and then return an error caller-allocates="0" transfer-ownership="full"> will be set to the number of bytes + filename="gio/gconverter.c" + line="68">will be set to the number of bytes written to @outbuf on success + + Applies @converter to the data in @bytes. + + + A newly-allocated + `GBytes` with the converted data, or `NULL` if an error + occurred + + + + + the `GConverter` to use + + + + the data to convert + + + + Resets all internal state in the converter, making it behave + filename="gio/gconverter.c" + line="192">Resets all internal state in the converter, making it behave as if it was just created. If the converter has any internal state that would produce output then that output is lost. - + a #GConverter. + filename="gio/gconverter.c" + line="194">a #GConverter. @@ -14010,7 +14816,7 @@ state that would produce output then that output is lost. glib:get-type="g_converter_flags_get_type" c:type="GConverterFlags"> Flags used when calling a g_converter_convert(). glib:nick="none" glib:name="G_CONVERTER_NO_FLAGS"> No flags. glib:nick="input-at-end" glib:name="G_CONVERTER_INPUT_AT_END"> At end of input data glib:nick="flush" glib:name="G_CONVERTER_FLUSH"> Flush data @@ -14045,31 +14851,34 @@ state that would produce output then that output is lost. glib:is-gtype-struct-for="Converter" version="2.24"> Provides an interface for converting data from one type + filename="gio/gconverter.h" + line="41">Provides an interface for converting data from one type to another type. The conversion can be stateful and may fail at any place. - + The parent interface. + filename="gio/gconverter.h" + line="43">The parent interface. + Converts data. - + a #GConverterResult, %G_CONVERTER_ERROR on error. + filename="gio/gconverter.c" + line="155">a #GConverterResult, %G_CONVERTER_ERROR on error. a #GConverter. + filename="gio/gconverter.c" + line="58">a #GConverter. nullable="1" allow-none="1"> the buffer + filename="gio/gconverter.c" + line="59">the buffer containing the data to convert. @@ -14086,14 +14895,14 @@ and may fail at any place. the number of bytes in @inbuf + filename="gio/gconverter.c" + line="61">the number of bytes in @inbuf a + filename="gio/gconverter.c" + line="62">a buffer to write converted data in. @@ -14101,14 +14910,14 @@ and may fail at any place. the number of bytes in @outbuf, must be at least one + filename="gio/gconverter.c" + line="64">the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details + filename="gio/gconverter.c" + line="65">a #GConverterFlags controlling the conversion details caller-allocates="0" transfer-ownership="full"> will be set to the number of bytes read + filename="gio/gconverter.c" + line="66">will be set to the number of bytes read from @inbuf on success @@ -14126,8 +14935,8 @@ and may fail at any place. caller-allocates="0" transfer-ownership="full"> will be set to the number of bytes + filename="gio/gconverter.c" + line="68">will be set to the number of bytes written to @outbuf on success @@ -14135,16 +14944,19 @@ and may fail at any place. + Reverts the internal state of the converter to its initial state. - + a #GConverter. + filename="gio/gconverter.c" + line="194">a #GConverter. @@ -14159,36 +14971,36 @@ and may fail at any place. glib:get-type="g_converter_input_stream_get_type" glib:type-struct="ConverterInputStreamClass"> Converter input stream implements #GInputStream and allows + filename="gio/gconverterinputstream.c" + line="35">Converter input stream implements [class@Gio.InputStream] and allows conversion of data of various types during reading. -As of GLib 2.34, #GConverterInputStream implements -#GPollableInputStream. - +As of GLib 2.34, `GConverterInputStream` implements +[iface@Gio.PollableInputStream]. + Creates a new converter input stream for the @base_stream. - + filename="gio/gconverterinputstream.c" + line="210">Creates a new converter input stream for the @base_stream. + a new #GInputStream. + filename="gio/gconverterinputstream.c" + line="217">a new #GInputStream. a #GInputStream + filename="gio/gconverterinputstream.c" + line="212">a #GInputStream a #GConverter + filename="gio/gconverterinputstream.c" + line="213">a #GConverter @@ -14198,21 +15010,21 @@ As of GLib 2.34, #GConverterInputStream implements glib:get-property="converter" version="2.24"> Gets the #GConverter that is used by @converter_stream. - + filename="gio/gconverterinputstream.c" + line="639">Gets the #GConverter that is used by @converter_stream. + the converter of the converter input stream + filename="gio/gconverterinputstream.c" + line="645">the converter of the converter input stream a #GConverterInputStream + filename="gio/gconverterinputstream.c" + line="641">a #GConverterInputStream @@ -14222,6 +15034,9 @@ As of GLib 2.34, #GConverterInputStream implements construct-only="1" transfer-ownership="none" getter="get_converter"> + The converter object. @@ -14235,13 +15050,13 @@ As of GLib 2.34, #GConverterInputStream implements - + - + @@ -14249,7 +15064,7 @@ As of GLib 2.34, #GConverterInputStream implements - + @@ -14257,7 +15072,7 @@ As of GLib 2.34, #GConverterInputStream implements - + @@ -14265,7 +15080,7 @@ As of GLib 2.34, #GConverterInputStream implements - + @@ -14273,7 +15088,7 @@ As of GLib 2.34, #GConverterInputStream implements - + @@ -14284,7 +15099,7 @@ As of GLib 2.34, #GConverterInputStream implements c:type="GConverterInputStreamPrivate" disguised="1" opaque="1"> - + Converter output stream implements #GOutputStream and allows + filename="gio/gconverteroutputstream.c" + line="35">Converter output stream implements [class@Gio.OutputStream] and allows conversion of data of various types during reading. -As of GLib 2.34, #GConverterOutputStream implements -#GPollableOutputStream. - +As of GLib 2.34, `GConverterOutputStream` implements +[iface@Gio.PollableOutputStream]. + Creates a new converter output stream for the @base_stream. - + filename="gio/gconverteroutputstream.c" + line="226">Creates a new converter output stream for the @base_stream. + a new #GOutputStream. + filename="gio/gconverteroutputstream.c" + line="233">a new #GOutputStream. a #GOutputStream + filename="gio/gconverteroutputstream.c" + line="228">a #GOutputStream a #GConverter + filename="gio/gconverteroutputstream.c" + line="229">a #GConverter @@ -14333,21 +15148,21 @@ As of GLib 2.34, #GConverterOutputStream implements glib:get-property="converter" version="2.24"> Gets the #GConverter that is used by @converter_stream. - + filename="gio/gconverteroutputstream.c" + line="681">Gets the #GConverter that is used by @converter_stream. + the converter of the converter output stream + filename="gio/gconverteroutputstream.c" + line="687">the converter of the converter output stream a #GConverterOutputStream + filename="gio/gconverteroutputstream.c" + line="683">a #GConverterOutputStream @@ -14358,6 +15173,9 @@ As of GLib 2.34, #GConverterOutputStream implements construct-only="1" transfer-ownership="none" getter="get_converter"> + The converter object. @@ -14371,14 +15189,14 @@ As of GLib 2.34, #GConverterOutputStream implements - + - + @@ -14386,7 +15204,7 @@ As of GLib 2.34, #GConverterOutputStream implements - + @@ -14394,7 +15212,7 @@ As of GLib 2.34, #GConverterOutputStream implements - + @@ -14402,7 +15220,7 @@ As of GLib 2.34, #GConverterOutputStream implements - + @@ -14410,7 +15228,7 @@ As of GLib 2.34, #GConverterOutputStream implements - + @@ -14421,7 +15239,7 @@ As of GLib 2.34, #GConverterOutputStream implements c:type="GConverterOutputStreamPrivate" disguised="1" opaque="1"> - + Results returned from g_converter_convert(). There was an error during conversion. Some data was consumed or produced The conversion is finished Flushing is finished @@ -14477,55 +15295,53 @@ As of GLib 2.34, #GConverterOutputStream implements glib:get-type="g_credentials_get_type" glib:type-struct="CredentialsClass"> The #GCredentials type is a reference-counted wrapper for native -credentials. This information is typically used for identifying, + filename="gio/gcredentials.c" + line="38">The `GCredentials` type is a reference-counted wrapper for native +credentials. + +The information in `GCredentials` is typically used for identifying, authenticating and authorizing other processes. -Some operating systems supports looking up the credentials of the -remote peer of a communication endpoint - see e.g. -g_socket_get_credentials(). +Some operating systems supports looking up the credentials of the remote +peer of a communication endpoint - see e.g. [method@Gio.Socket.get_credentials]. Some operating systems supports securely sending and receiving -credentials over a Unix Domain Socket, see -#GUnixCredentialsMessage, g_unix_connection_send_credentials() and -g_unix_connection_receive_credentials() for details. +credentials over a Unix Domain Socket, see [class@Gio.UnixCredentialsMessage], +[method@Gio.UnixConnection.send_credentials] and +[method@Gio.UnixConnection.receive_credentials] for details. On Linux, the native credential type is a `struct ucred` - see the -unix(7) man page for details. This corresponds to -%G_CREDENTIALS_TYPE_LINUX_UCRED. +[`unix(7)` man page](man:unix(7)) for details. This corresponds to +`G_CREDENTIALS_TYPE_LINUX_UCRED`. -On Apple operating systems (including iOS, tvOS, and macOS), -the native credential type is a `struct xucred`. -This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED. +On Apple operating systems (including iOS, tvOS, and macOS), the native credential +type is a `struct xucred`. This corresponds to `G_CREDENTIALS_TYPE_APPLE_XUCRED`. -On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native -credential type is a `struct cmsgcred`. This corresponds -to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. +On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a +`struct cmsgcred`. This corresponds to `G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED`. On NetBSD, the native credential type is a `struct unpcbid`. -This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID. +This corresponds to `G_CREDENTIALS_TYPE_NETBSD_UNPCBID`. On OpenBSD, the native credential type is a `struct sockpeercred`. -This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. +This corresponds to `G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED`. -On Solaris (including OpenSolaris and its derivatives), the native -credential type is a `ucred_t`. This corresponds to -%G_CREDENTIALS_TYPE_SOLARIS_UCRED. +On Solaris (including OpenSolaris and its derivatives), the native credential type +is a `ucred_t`. This corresponds to `G_CREDENTIALS_TYPE_SOLARIS_UCRED`. Since GLib 2.72, on Windows, the native credentials may contain the PID of a -process. This corresponds to %G_CREDENTIALS_TYPE_WIN32_PID. - +process. This corresponds to `G_CREDENTIALS_TYPE_WIN32_PID`. + Creates a new #GCredentials object with credentials matching the + filename="gio/gcredentials.c" + line="195">Creates a new #GCredentials object with credentials matching the the current process. - + A #GCredentials. Free with g_object_unref(). + filename="gio/gcredentials.c" + line="201">A #GCredentials. Free with g_object_unref(). @@ -14534,18 +15350,18 @@ the current process. version="2.26" introspectable="0"> Gets a pointer to native credentials of type @native_type from + filename="gio/gcredentials.c" + line="430">Gets a pointer to native credentials of type @native_type from @credentials. It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. - + The pointer to native credentials or + filename="gio/gcredentials.c" + line="442">The pointer to native credentials or %NULL if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Do not free the returned data, it is owned by @credentials. @@ -14554,14 +15370,14 @@ the OS or if @native_type isn't supported by the OS. A #GCredentials. + filename="gio/gcredentials.c" + line="432">A #GCredentials. The type of native credentials to get. + filename="gio/gcredentials.c" + line="433">The type of native credentials to get. @@ -14571,25 +15387,25 @@ the OS or if @native_type isn't supported by the OS. version="2.36" throws="1"> Tries to get the UNIX process identifier from @credentials. This + filename="gio/gcredentials.c" + line="566">Tries to get the UNIX process identifier from @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX process ID. - + The UNIX process ID, or `-1` if @error is set. - + filename="gio/gcredentials.c" + line="578">The UNIX process ID, or `-1` if @error is set. + A #GCredentials + filename="gio/gcredentials.c" + line="568">A #GCredentials @@ -14599,25 +15415,25 @@ about the UNIX process ID. version="2.26" throws="1"> Tries to get the UNIX user identifier from @credentials. This + filename="gio/gcredentials.c" + line="502">Tries to get the UNIX user identifier from @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. - + The UNIX user identifier or `-1` if @error is set. - + filename="gio/gcredentials.c" + line="514">The UNIX user identifier or `-1` if @error is set. + A #GCredentials + filename="gio/gcredentials.c" + line="504">A #GCredentials @@ -14627,30 +15443,30 @@ about the UNIX user. version="2.26" throws="1"> Checks if @credentials and @other_credentials is the same user. + filename="gio/gcredentials.c" + line="335">Checks if @credentials and @other_credentials is the same user. This operation can fail if #GCredentials is not supported on the the OS. - + %TRUE if @credentials and @other_credentials has the same + filename="gio/gcredentials.c" + line="346">%TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set. A #GCredentials. + filename="gio/gcredentials.c" + line="337">A #GCredentials. A #GCredentials. + filename="gio/gcredentials.c" + line="338">A #GCredentials. @@ -14659,34 +15475,34 @@ user, %FALSE otherwise or if @error is set. c:identifier="g_credentials_set_native" version="2.26"> Copies the native credentials of type @native_type from @native + filename="gio/gcredentials.c" + line="467">Copies the native credentials of type @native_type from @native into @credentials. It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. - + A #GCredentials. + filename="gio/gcredentials.c" + line="469">A #GCredentials. The type of native credentials to set. + filename="gio/gcredentials.c" + line="470">The type of native credentials to set. A pointer to native credentials. + filename="gio/gcredentials.c" + line="471">A pointer to native credentials. @@ -14696,33 +15512,33 @@ the OS or if @native_type isn't supported by the OS. version="2.26" throws="1"> Tries to set the UNIX user identifier on @credentials. This method + filename="gio/gcredentials.c" + line="624">Tries to set the UNIX user identifier on @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. It can also fail if the OS does not allow the use of "spoofed" credentials. - + %TRUE if @uid was set, %FALSE if error is set. + filename="gio/gcredentials.c" + line="638">%TRUE if @uid was set, %FALSE if error is set. A #GCredentials. + filename="gio/gcredentials.c" + line="626">A #GCredentials. The UNIX user identifier to set. - + filename="gio/gcredentials.c" + line="627">The UNIX user identifier to set. + @@ -14730,22 +15546,22 @@ use of "spoofed" credentials. c:identifier="g_credentials_to_string" version="2.26"> Creates a human-readable textual representation of @credentials + filename="gio/gcredentials.c" + line="213">Creates a human-readable textual representation of @credentials that can be used in logging and debug messages. The format of the returned string may change in future GLib release. - + A string that should be freed with g_free(). + filename="gio/gcredentials.c" + line="221">A string that should be freed with g_free(). A #GCredentials object. + filename="gio/gcredentials.c" + line="215">A #GCredentials object. @@ -14758,9 +15574,9 @@ returned string may change in future GLib release. glib:is-gtype-struct-for="Credentials" version="2.26"> Class structure for #GCredentials. - + filename="gio/gcredentials.c" + line="110">Class structure for #GCredentials. + glib:get-type="g_credentials_type_get_type" c:type="GCredentialsType"> Enumeration describing different kinds of native credential types. + filename="gio/gioenums.h" + line="1455">Enumeration describing different kinds of native credential types. Indicates an invalid native credential type. + filename="gio/gioenums.h" + line="1457">Indicates an invalid native credential type. glib:nick="linux-ucred" glib:name="G_CREDENTIALS_TYPE_LINUX_UCRED"> The native credentials type is a `struct ucred`. + filename="gio/gioenums.h" + line="1458">The native credentials type is a `struct ucred`. glib:nick="freebsd-cmsgcred" glib:name="G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED"> The native credentials type is a `struct cmsgcred`. + filename="gio/gioenums.h" + line="1459">The native credentials type is a `struct cmsgcred`. glib:nick="openbsd-sockpeercred" glib:name="G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED"> The native credentials type is a `struct sockpeercred`. Added in 2.30. + filename="gio/gioenums.h" + line="1460">The native credentials type is a `struct sockpeercred`. Added in 2.30. glib:nick="solaris-ucred" glib:name="G_CREDENTIALS_TYPE_SOLARIS_UCRED"> The native credentials type is a `ucred_t`. Added in 2.40. + filename="gio/gioenums.h" + line="1461">The native credentials type is a `ucred_t`. Added in 2.40. glib:nick="netbsd-unpcbid" glib:name="G_CREDENTIALS_TYPE_NETBSD_UNPCBID"> The native credentials type is a `struct unpcbid`. Added in 2.42. + filename="gio/gioenums.h" + line="1462">The native credentials type is a `struct unpcbid`. Added in 2.42. glib:nick="apple-xucred" glib:name="G_CREDENTIALS_TYPE_APPLE_XUCRED"> The native credentials type is a `struct xucred`. Added in 2.66. + filename="gio/gioenums.h" + line="1463">The native credentials type is a `struct xucred`. Added in 2.66. glib:nick="win32-pid" glib:name="G_CREDENTIALS_TYPE_WIN32_PID"> The native credentials type is a PID `DWORD`. Added in 2.72. + filename="gio/gioenums.h" + line="1464">The native credentials type is a PID `DWORD`. Added in 2.72. - + @@ -14855,7 +15671,7 @@ returned string may change in future GLib release. - + @@ -14864,7 +15680,7 @@ returned string may change in future GLib release. - + @@ -14873,7 +15689,7 @@ returned string may change in future GLib release. - + @@ -14882,7 +15698,7 @@ returned string may change in future GLib release. - + @@ -14891,7 +15707,7 @@ returned string may change in future GLib release. - + @@ -14900,7 +15716,7 @@ returned string may change in future GLib release. - + @@ -14909,7 +15725,7 @@ returned string may change in future GLib release. - + @@ -14918,7 +15734,7 @@ returned string may change in future GLib release. - + @@ -14927,7 +15743,7 @@ returned string may change in future GLib release. - + @@ -14936,7 +15752,7 @@ returned string may change in future GLib release. - + @@ -14945,7 +15761,7 @@ returned string may change in future GLib release. - + @@ -14954,7 +15770,7 @@ returned string may change in future GLib release. - + @@ -14963,7 +15779,7 @@ returned string may change in future GLib release. - + @@ -14972,7 +15788,7 @@ returned string may change in future GLib release. - + @@ -14981,7 +15797,7 @@ returned string may change in future GLib release. - + @@ -14990,7 +15806,7 @@ returned string may change in future GLib release. - + @@ -14999,7 +15815,7 @@ returned string may change in future GLib release. - + @@ -15008,7 +15824,7 @@ returned string may change in future GLib release. - + @@ -15017,7 +15833,7 @@ returned string may change in future GLib release. - + @@ -15026,7 +15842,7 @@ returned string may change in future GLib release. - + @@ -15037,7 +15853,7 @@ returned string may change in future GLib release. c:type="G_DBUS_METHOD_INVOCATION_HANDLED" version="2.68"> The value returned by handlers of the signals generated by the `gdbus-codegen` tool to indicate that a method call has been handled by an implementation. It is equal to %TRUE, but using @@ -15050,7 +15866,7 @@ use %TRUE instead, often written like this: g_dbus_method_invocation_return_error (invocation, ...); return TRUE; // handled ]| - + The value returned by handlers of the signals generated by the `gdbus-codegen` tool to indicate that a method call has not been handled by an implementation. It is equal to %FALSE, but using @@ -15066,13 +15882,13 @@ this macro is sometimes more readable. In code that needs to be backwards-compatible with older GLib, use %FALSE instead. - + - + @@ -15081,7 +15897,7 @@ use %FALSE instead. - + @@ -15090,7 +15906,7 @@ use %FALSE instead. - + @@ -15099,7 +15915,7 @@ use %FALSE instead. - + @@ -15108,7 +15924,7 @@ use %FALSE instead. - + @@ -15117,7 +15933,7 @@ use %FALSE instead. - + @@ -15126,7 +15942,7 @@ use %FALSE instead. - + @@ -15135,7 +15951,7 @@ use %FALSE instead. - + @@ -15144,7 +15960,7 @@ use %FALSE instead. - + @@ -15153,7 +15969,7 @@ use %FALSE instead. - + @@ -15162,7 +15978,7 @@ use %FALSE instead. - + @@ -15171,7 +15987,7 @@ use %FALSE instead. - + @@ -15180,7 +15996,7 @@ use %FALSE instead. - + @@ -15189,7 +16005,7 @@ use %FALSE instead. - + @@ -15198,7 +16014,7 @@ use %FALSE instead. - + @@ -15207,7 +16023,7 @@ use %FALSE instead. - + @@ -15216,7 +16032,7 @@ use %FALSE instead. - + @@ -15225,7 +16041,7 @@ use %FALSE instead. - + @@ -15234,7 +16050,7 @@ use %FALSE instead. - + @@ -15243,7 +16059,7 @@ use %FALSE instead. - + @@ -15256,18 +16072,20 @@ use %FALSE instead. glib:type-name="GDBusActionGroup" glib:get-type="g_dbus_action_group_get_type"> #GDBusActionGroup is an implementation of the #GActionGroup -interface that can be used as a proxy for an action group -that is exported over D-Bus with g_dbus_connection_export_action_group(). + filename="gio/gdbusactiongroup.c" + line="31">`GDBusActionGroup` is an implementation of the [iface@Gio.ActionGroup] +interface. + +`GDBusActionGroup` can be used as a proxy for an action group +that is exported over D-Bus with [method@Gio.DBusConnection.export_action_group]. Obtains a #GDBusActionGroup for the action group which is exported at + filename="gio/gdbusactiongroup.c" + line="468">Obtains a #GDBusActionGroup for the action group which is exported at the given @bus_name and @object_path. The thread default main context is taken at the time of this call. @@ -15280,18 +16098,18 @@ This call is non-blocking. The returned action group may or may not already be filled in. The correct thing to do is connect the signals for the action group to monitor for changes and then to call g_action_group_list_actions() to get the initial list. - + a #GDBusActionGroup + filename="gio/gdbusactiongroup.c" + line="489">a #GDBusActionGroup A #GDBusConnection + filename="gio/gdbusactiongroup.c" + line="470">A #GDBusConnection nullable="1" allow-none="1"> the bus name which exports the action + filename="gio/gdbusactiongroup.c" + line="471">the bus name which exports the action group or %NULL if @connection is not a message bus connection the object path at which the action group is exported + filename="gio/gdbusactiongroup.c" + line="473">the object path at which the action group is exported @@ -15320,30 +16138,30 @@ g_action_group_list_actions() to get the initial list. glib:get-type="g_dbus_annotation_info_get_type" c:symbol-prefix="dbus_annotation_info"> Information about an annotation. - + The reference count or -1 if statically allocated. The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated". The value of the annotation. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -15353,21 +16171,21 @@ g_action_group_list_actions() to get the initial list. c:identifier="g_dbus_annotation_info_ref" version="2.26"> If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="202">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="209">The same @info. A #GDBusNodeInfo + filename="gio/gdbusintrospection.c" + line="204">A #GDBusNodeInfo @@ -15376,19 +16194,19 @@ the reference count. c:identifier="g_dbus_annotation_info_unref" version="2.26"> If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="236">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusAnnotationInfo. + filename="gio/gdbusintrospection.c" + line="238">A #GDBusAnnotationInfo. @@ -15397,15 +16215,15 @@ the memory used is freed. c:identifier="g_dbus_annotation_info_lookup" version="2.26"> Looks up the value of an annotation. + filename="gio/gdbusintrospection.c" + line="1829">Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. - + The value or %NULL if not found. Do not free, it is owned by @annotations. + filename="gio/gdbusintrospection.c" + line="1838">The value or %NULL if not found. Do not free, it is owned by @annotations. @@ -15414,16 +16232,16 @@ The cost of this function is O(n) in number of annotations. nullable="1" allow-none="1"> A %NULL-terminated array of annotations or %NULL. + filename="gio/gdbusintrospection.c" + line="1831">A %NULL-terminated array of annotations or %NULL. The name of the annotation to look up. + filename="gio/gdbusintrospection.c" + line="1832">The name of the annotation to look up. @@ -15436,30 +16254,30 @@ The cost of this function is O(n) in number of annotations. glib:get-type="g_dbus_arg_info_get_type" c:symbol-prefix="dbus_arg_info"> Information about an argument for a method or a signal. - + The reference count or -1 if statically allocated. Name of the argument, e.g. @unix_user_id. D-Bus signature of the argument (a single complete type). A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -15467,40 +16285,40 @@ The cost of this function is O(n) in number of annotations. If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="182">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="189">The same @info. A #GDBusArgInfo + filename="gio/gdbusintrospection.c" + line="184">A #GDBusArgInfo If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="260">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusArgInfo. + filename="gio/gdbusintrospection.c" + line="262">A #GDBusArgInfo. @@ -15514,23 +16332,24 @@ the memory used is freed. glib:type-name="GDBusAuthObserver" glib:get-type="g_dbus_auth_observer_get_type"> The #GDBusAuthObserver type provides a mechanism for participating -in how a #GDBusServer (or a #GDBusConnection) authenticates remote -peers. Simply instantiate a #GDBusAuthObserver and connect to the + filename="gio/gdbusauthobserver.c" + line="34">`GDBusAuthObserver` provides a mechanism for participating +in how a [class@Gio.DBusServer] (or a [class@Gio.DBusConnection]) +authenticates remote peers. + +Simply instantiate a `GDBusAuthObserver` and connect to the signals you are interested in. Note that new signals may be added -in the future +in the future. ## Controlling Authentication Mechanisms -By default, a #GDBusServer or server-side #GDBusConnection will allow -any authentication mechanism to be used. If you only -want to allow D-Bus connections with the `EXTERNAL` mechanism, -which makes use of credentials passing and is the recommended -mechanism for modern Unix platforms such as Linux and the BSD family, -you would use a signal handler like this: +By default, a `GDBusServer` or server-side `GDBusConnection` will allow +any authentication mechanism to be used. If you only want to allow D-Bus +connections with the `EXTERNAL` mechanism, which makes use of credentials +passing and is the recommended mechanism for modern Unix platforms such +as Linux and the BSD family, you would use a signal handler like this: -|[<!-- language="C" --> +```c static gboolean on_allow_mechanism (GDBusAuthObserver *observer, const gchar *mechanism, @@ -15543,19 +16362,19 @@ on_allow_mechanism (GDBusAuthObserver *observer, return FALSE; } -]| +``` -## Controlling Authorization # {#auth-observer} +## Controlling Authorization -By default, a #GDBusServer or server-side #GDBusConnection will accept +By default, a `GDBusServer` or server-side `GDBusConnection` will accept connections from any successfully authenticated user (but not from anonymous connections using the `ANONYMOUS` mechanism). If you only want to allow D-Bus connections from processes owned by the same uid as the server, since GLib 2.68, you should use the -%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent +`G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag. It’s equivalent to the following signal handler: -|[<!-- language="C" --> +```c static gboolean on_authorize_authenticated_peer (GDBusAuthObserver *observer, GIOStream *stream, @@ -15576,18 +16395,18 @@ on_authorize_authenticated_peer (GDBusAuthObserver *observer, return authorized; } -]| +``` Creates a new #GDBusAuthObserver object. - + filename="gio/gdbusauthobserver.c" + line="240">Creates a new #GDBusAuthObserver object. + A #GDBusAuthObserver. Free with g_object_unref(). + filename="gio/gdbusauthobserver.c" + line="245">A #GDBusAuthObserver. Free with g_object_unref(). @@ -15595,26 +16414,26 @@ on_authorize_authenticated_peer (GDBusAuthObserver *observer, c:identifier="g_dbus_auth_observer_allow_mechanism" version="2.34"> Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. - + filename="gio/gdbusauthobserver.c" + line="286">Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. + %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. + filename="gio/gdbusauthobserver.c" + line="293">%TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. A #GDBusAuthObserver. + filename="gio/gdbusauthobserver.c" + line="288">A #GDBusAuthObserver. The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. + filename="gio/gdbusauthobserver.c" + line="289">The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. @@ -15623,26 +16442,26 @@ on_authorize_authenticated_peer (GDBusAuthObserver *observer, c:identifier="g_dbus_auth_observer_authorize_authenticated_peer" version="2.26"> Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. - + filename="gio/gdbusauthobserver.c" + line="257">Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. + %TRUE if the peer is authorized, %FALSE if not. + filename="gio/gdbusauthobserver.c" + line="265">%TRUE if the peer is authorized, %FALSE if not. A #GDBusAuthObserver. + filename="gio/gdbusauthobserver.c" + line="259">A #GDBusAuthObserver. A #GIOStream for the #GDBusConnection. + filename="gio/gdbusauthobserver.c" + line="260">A #GIOStream for the #GDBusConnection. Credentials received from the peer or %NULL. + filename="gio/gdbusauthobserver.c" + line="261">Credentials received from the peer or %NULL. Emitted to check if @mechanism is allowed to be used. + filename="gio/gdbusauthobserver.c" + line="208">Emitted to check if @mechanism is allowed to be used. %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. + filename="gio/gdbusauthobserver.c" + line="215">%TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. + filename="gio/gdbusauthobserver.c" + line="211">The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. @@ -15679,20 +16498,20 @@ on_authorize_authenticated_peer (GDBusAuthObserver *observer, when="last" version="2.26"> Emitted to check if a peer that is successfully authenticated + filename="gio/gdbusauthobserver.c" + line="179">Emitted to check if a peer that is successfully authenticated is authorized. %TRUE if the peer is authorized, %FALSE if not. + filename="gio/gdbusauthobserver.c" + line="188">%TRUE if the peer is authorized, %FALSE if not. A #GIOStream for the #GDBusConnection. + filename="gio/gdbusauthobserver.c" + line="182">A #GIOStream for the #GDBusConnection. nullable="1" allow-none="1"> Credentials received from the peer or %NULL. + filename="gio/gdbusauthobserver.c" + line="183">Credentials received from the peer or %NULL. @@ -15713,16 +16532,16 @@ is authorized. glib:get-type="g_dbus_call_flags_get_type" c:type="GDBusCallFlags"> Flags used in g_dbus_connection_call() and similar APIs. + filename="gio/gioenums.h" + line="1265">Flags used in g_dbus_connection_call() and similar APIs. No flags set. + filename="gio/gioenums.h" + line="1267">No flags set. glib:nick="no-auto-start" glib:name="G_DBUS_CALL_FLAGS_NO_AUTO_START"> The bus must not launch + filename="gio/gioenums.h" + line="1268">The bus must not launch an owner for the destination name in response to this method invocation. @@ -15741,8 +16560,8 @@ invocation. glib:nick="allow-interactive-authorization" glib:name="G_DBUS_CALL_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION"> the caller is prepared to + filename="gio/gioenums.h" + line="1271">the caller is prepared to wait for interactive authorization. Since 2.46. @@ -15752,16 +16571,16 @@ wait for interactive authorization. Since 2.46. glib:get-type="g_dbus_capability_flags_get_type" c:type="GDBusCapabilityFlags"> Capabilities negotiated with the remote peer. + filename="gio/gioenums.h" + line="1250">Capabilities negotiated with the remote peer. No flags set. + filename="gio/gioenums.h" + line="1252">No flags set. glib:nick="unix-fd-passing" glib:name="G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING"> The connection + filename="gio/gioenums.h" + line="1253">The connection supports exchanging UNIX file descriptors with the remote peer. @@ -15782,53 +16601,56 @@ supports exchanging UNIX file descriptors with the remote peer. glib:type-name="GDBusConnection" glib:get-type="g_dbus_connection_get_type"> The #GDBusConnection type is used for D-Bus connections to remote -peers such as a message buses. It is a low-level API that offers a -lot of flexibility. For instance, it lets you establish a connection -over any transport that can by represented as a #GIOStream. + filename="gio/gdbusconnection.c" + line="134">The `GDBusConnection` type is used for D-Bus connections to remote +peers such as a message buses. + +It is a low-level API that offers a lot of flexibility. For instance, +it lets you establish a connection over any transport that can by represented +as a [class@Gio.IOStream]. This class is rarely used directly in D-Bus clients. If you are writing -a D-Bus client, it is often easier to use the g_bus_own_name(), -g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. +a D-Bus client, it is often easier to use the [func@Gio.bus_own_name], +[func@Gio.bus_watch_name] or [func@Gio.DBusProxy.new_for_bus] APIs. As an exception to the usual GLib rule that a particular object must not -be used by two threads at the same time, #GDBusConnection's methods may be -called from any thread. This is so that g_bus_get() and g_bus_get_sync() -can safely return the same #GDBusConnection when called from any thread. - -Most of the ways to obtain a #GDBusConnection automatically initialize it -(i.e. connect to D-Bus): for instance, g_dbus_connection_new() and -g_bus_get(), and the synchronous versions of those methods, give you an -initialized connection. Language bindings for GIO should use -g_initable_new() or g_async_initable_new_async(), which also initialize the -connection. - -If you construct an uninitialized #GDBusConnection, such as via -g_object_new(), you must initialize it via g_initable_init() or -g_async_initable_init_async() before using its methods or properties. -Calling methods or accessing properties on a #GDBusConnection that has not +be used by two threads at the same time, `GDBusConnection`s methods may be +called from any thread. This is so that [func@Gio.bus_get] and +[func@Gio.bus_get_sync] can safely return the same `GDBusConnection` when +called from any thread. + +Most of the ways to obtain a `GDBusConnection` automatically initialize it +(i.e. connect to D-Bus): for instance, [func@Gio.DBusConnection.new] and +[func@Gio.bus_get], and the synchronous versions of those methods, give you +an initialized connection. Language bindings for GIO should use +[func@Gio.Initable.new] or [func@Gio.AsyncInitable.new_async], which also +initialize the connection. + +If you construct an uninitialized `GDBusConnection`, such as via +[ctor@GObject.Object.new], you must initialize it via [method@Gio.Initable.init] or +[method@Gio.AsyncInitable.init_async] before using its methods or properties. +Calling methods or accessing properties on a `GDBusConnection` that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a -#GError, the only valid thing you can do with that #GDBusConnection is to -free it with g_object_unref(). +`GError`, the only valid thing you can do with that `GDBusConnection` is to +free it with [method@GObject.Object.unref]. -## An example D-Bus server # {#gdbus-server} +## An example D-Bus server Here is an example for a D-Bus server: [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c) -## An example for exporting a subtree # {#gdbus-subtree-server} +## An example for exporting a subtree Here is an example for exporting a subtree: [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) -## An example for file descriptor passing # {#gdbus-unix-fd-client} +## An example for file descriptor passing Here is an example for passing UNIX file descriptors: [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) -## An example for exporting a GObject # {#gdbus-export} +## An example for exporting a GObject Here is an example for exporting a #GObject: [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) @@ -15839,21 +16661,21 @@ Here is an example for exporting a #GObject: version="2.26" throws="1"> Finishes an operation started with g_dbus_connection_new(). - + filename="gio/gdbusconnection.c" + line="3119">Finishes an operation started with g_dbus_connection_new(). + a #GDBusConnection or %NULL if @error is set. Free + filename="gio/gdbusconnection.c" + line="3127">a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GAsyncResult obtained from the #GAsyncReadyCallback + filename="gio/gdbusconnection.c" + line="3121">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). @@ -15864,21 +16686,21 @@ Here is an example for exporting a #GObject: version="2.26" throws="1"> Finishes an operation started with g_dbus_connection_new_for_address(). - + filename="gio/gdbusconnection.c" + line="3266">Finishes an operation started with g_dbus_connection_new_for_address(). + a #GDBusConnection or %NULL if @error is set. + filename="gio/gdbusconnection.c" + line="3274">a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GAsyncResult obtained from the #GAsyncReadyCallback passed + filename="gio/gdbusconnection.c" + line="3268">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new() @@ -15889,8 +16711,8 @@ Here is an example for exporting a #GObject: version="2.26" throws="1"> Synchronously connects and sets up a D-Bus client connection for + filename="gio/gdbusconnection.c" + line="3301">Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by @address which must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). @@ -15907,25 +16729,25 @@ g_dbus_connection_new_for_address() for the asynchronous version. If @observer is not %NULL it may be used to control the authentication process. - + a #GDBusConnection or %NULL if @error is set. + filename="gio/gdbusconnection.c" + line="3327">a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a D-Bus address + filename="gio/gdbusconnection.c" + line="3303">a D-Bus address flags describing how to make the connection + filename="gio/gdbusconnection.c" + line="3304">flags describing how to make the connection nullable="1" allow-none="1"> a #GDBusAuthObserver or %NULL + filename="gio/gdbusconnection.c" + line="3305">a #GDBusAuthObserver or %NULL nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="3306">a #GCancellable or %NULL @@ -15953,8 +16775,8 @@ authentication process. version="2.26" throws="1"> Synchronously sets up a D-Bus connection for exchanging D-Bus messages + filename="gio/gdbusconnection.c" + line="3154">Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by @stream. If @stream is a #GSocketConnection, then the corresponding #GSocket @@ -15969,19 +16791,19 @@ authentication process. This is a synchronous failable constructor. See g_dbus_connection_new() for the asynchronous version. - + a #GDBusConnection or %NULL if @error is set. + filename="gio/gdbusconnection.c" + line="3179">a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GIOStream + filename="gio/gdbusconnection.c" + line="3156">a #GIOStream nullable="1" allow-none="1"> the GUID to use if authenticating as a server or %NULL + filename="gio/gdbusconnection.c" + line="3157">the GUID to use if authenticating as a server or %NULL flags describing how to make the connection + filename="gio/gdbusconnection.c" + line="3158">flags describing how to make the connection nullable="1" allow-none="1"> a #GDBusAuthObserver or %NULL + filename="gio/gdbusconnection.c" + line="3159">a #GDBusAuthObserver or %NULL nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="3160">a #GCancellable or %NULL - + Asynchronously sets up a D-Bus connection for exchanging D-Bus messages + filename="gio/gdbusconnection.c" + line="3060">Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by @stream. If @stream is a #GSocketConnection, then the corresponding #GSocket @@ -16042,15 +16867,15 @@ operation. This is an asynchronous failable constructor. See g_dbus_connection_new_sync() for the synchronous version. - + a #GIOStream + filename="gio/gdbusconnection.c" + line="3062">a #GIOStream nullable="1" allow-none="1"> the GUID to use if authenticating as a server or %NULL + filename="gio/gdbusconnection.c" + line="3063">the GUID to use if authenticating as a server or %NULL flags describing how to make the connection + filename="gio/gdbusconnection.c" + line="3064">flags describing how to make the connection nullable="1" allow-none="1"> a #GDBusAuthObserver or %NULL + filename="gio/gdbusconnection.c" + line="3065">a #GDBusAuthObserver or %NULL nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="3066">a #GCancellable or %NULL scope="async" closure="6"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gdbusconnection.c" + line="3067">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to @callback + filename="gio/gdbusconnection.c" + line="3068">the data to pass to @callback + version="2.26" + glib:finish-func="new_for_address_finish"> Asynchronously connects and sets up a D-Bus client connection for + filename="gio/gdbusconnection.c" + line="3208">Asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by @address which must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). @@ -16135,21 +16961,21 @@ authentication process. This is an asynchronous failable constructor. See g_dbus_connection_new_for_address_sync() for the synchronous version. - + a D-Bus address + filename="gio/gdbusconnection.c" + line="3210">a D-Bus address flags describing how to make the connection + filename="gio/gdbusconnection.c" + line="3211">flags describing how to make the connection nullable="1" allow-none="1"> a #GDBusAuthObserver or %NULL + filename="gio/gdbusconnection.c" + line="3212">a #GDBusAuthObserver or %NULL nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="3213">a #GCancellable or %NULL scope="async" closure="5"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gdbusconnection.c" + line="3214">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to @callback + filename="gio/gdbusconnection.c" + line="3215">the data to pass to @callback @@ -16196,8 +17022,8 @@ version. c:identifier="g_dbus_connection_add_filter" version="2.26"> Adds a message filter. Filters are handlers that are run on all + filename="gio/gdbusconnection.c" + line="3491">Adds a message filter. Filters are handlers that are run on all incoming and outgoing messages, prior to standard dispatch. Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more @@ -16224,19 +17050,19 @@ method from) at some point after @user_data is no longer needed. (It is not guaranteed to be called synchronously when the filter is removed, and may be called after @connection has been destroyed.) - + a filter identifier that can be used with + filename="gio/gdbusconnection.c" + line="3527">a filter identifier that can be used with g_dbus_connection_remove_filter() a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3493">a #GDBusConnection closure="1" destroy="2"> a filter function + filename="gio/gdbusconnection.c" + line="3494">a filter function @@ -16255,25 +17081,29 @@ destroyed.) nullable="1" allow-none="1"> user data to pass to @filter_function + filename="gio/gdbusconnection.c" + line="3495">user data to pass to @filter_function function to free @user_data with when filter + filename="gio/gdbusconnection.c" + line="3496">function to free @user_data with when filter is removed or %NULL - + Asynchronously invokes the @method_name method on the + filename="gio/gdbusconnection.c" + line="6766">Asynchronously invokes the @method_name method on the @interface_name D-Bus interface on the remote object at @object_path owned by @bus_name. @@ -16309,8 +17139,8 @@ convenient 'inline' use of g_variant_new(), e.g.: ]| This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +@callback will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_call_finish() to get the result of the operation. See g_dbus_connection_call_sync() for the synchronous version of this @@ -16318,15 +17148,15 @@ function. If @callback is %NULL then the D-Bus method call message will be sent with the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="6768">a #GDBusConnection nullable="1" allow-none="1"> a unique or well-known bus name or %NULL if + filename="gio/gdbusconnection.c" + line="6769">a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object + filename="gio/gdbusconnection.c" + line="6771">path of remote object D-Bus interface to invoke method on + filename="gio/gdbusconnection.c" + line="6772">D-Bus interface to invoke method on the name of the method to invoke + filename="gio/gdbusconnection.c" + line="6773">the name of the method to invoke nullable="1" allow-none="1"> a #GVariant tuple with parameters for the method + filename="gio/gdbusconnection.c" + line="6774">a #GVariant tuple with parameters for the method or %NULL if not passing parameters @@ -16372,21 +17202,21 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. nullable="1" allow-none="1"> the expected type of the reply (which will be a + filename="gio/gdbusconnection.c" + line="6776">the expected type of the reply (which will be a tuple), or %NULL flags from the #GDBusCallFlags enumeration + filename="gio/gdbusconnection.c" + line="6778">flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default + filename="gio/gdbusconnection.c" + line="6779">the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout @@ -16395,8 +17225,8 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="6781">a #GCancellable or %NULL scope="async" closure="10"> a #GAsyncReadyCallback to call when the request + filename="gio/gdbusconnection.c" + line="6782">a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation @@ -16417,8 +17247,8 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. nullable="1" allow-none="1"> the data to pass to @callback + filename="gio/gdbusconnection.c" + line="6785">the data to pass to @callback @@ -16428,27 +17258,27 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. version="2.26" throws="1"> Finishes an operation started with g_dbus_connection_call(). - + filename="gio/gdbusconnection.c" + line="6852">Finishes an operation started with g_dbus_connection_call(). + %NULL if @error is set. Otherwise a non-floating + filename="gio/gdbusconnection.c" + line="6860">%NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection + filename="gio/gdbusconnection.c" + line="6854">a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() + filename="gio/gdbusconnection.c" + line="6855">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() @@ -16456,10 +17286,11 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. + throws="1" + glib:async-func="call"> Synchronously invokes the @method_name method on the + filename="gio/gdbusconnection.c" + line="6873">Synchronously invokes the @method_name method on the @interface_name D-Bus interface on the remote object at @object_path owned by @bus_name. @@ -16495,19 +17326,19 @@ This allows convenient 'inline' use of g_variant_new(), e.g.: The calling thread is blocked until a reply is received. See g_dbus_connection_call() for the asynchronous version of this method. - + %NULL if @error is set. Otherwise a non-floating + filename="gio/gdbusconnection.c" + line="6927">%NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection + filename="gio/gdbusconnection.c" + line="6875">a #GDBusConnection nullable="1" allow-none="1"> a unique or well-known bus name or %NULL if + filename="gio/gdbusconnection.c" + line="6876">a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object + filename="gio/gdbusconnection.c" + line="6878">path of remote object D-Bus interface to invoke method on + filename="gio/gdbusconnection.c" + line="6879">D-Bus interface to invoke method on the name of the method to invoke + filename="gio/gdbusconnection.c" + line="6880">the name of the method to invoke nullable="1" allow-none="1"> a #GVariant tuple with parameters for the method + filename="gio/gdbusconnection.c" + line="6881">a #GVariant tuple with parameters for the method or %NULL if not passing parameters @@ -16553,20 +17384,20 @@ this method. nullable="1" allow-none="1"> the expected type of the reply, or %NULL + filename="gio/gdbusconnection.c" + line="6883">the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration + filename="gio/gdbusconnection.c" + line="6884">flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default + filename="gio/gdbusconnection.c" + line="6885">the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout @@ -16575,18 +17406,20 @@ this method. nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="6887">a #GCancellable or %NULL + version="2.30" + glib:finish-func="call_with_unix_fd_list_finish" + glib:sync-func="call_with_unix_fd_list_sync"> Like g_dbus_connection_call() but also takes a #GUnixFDList object. + filename="gio/gdbusconnection.c" + line="6952">Like g_dbus_connection_call() but also takes a #GUnixFDList object. The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if a message contains @@ -16601,15 +17434,15 @@ access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. This method is only available on UNIX. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="6954">a #GDBusConnection nullable="1" allow-none="1"> a unique or well-known bus name or %NULL if + filename="gio/gdbusconnection.c" + line="6955">a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object + filename="gio/gdbusconnection.c" + line="6957">path of remote object D-Bus interface to invoke method on + filename="gio/gdbusconnection.c" + line="6958">D-Bus interface to invoke method on the name of the method to invoke + filename="gio/gdbusconnection.c" + line="6959">the name of the method to invoke nullable="1" allow-none="1"> a #GVariant tuple with parameters for the method + filename="gio/gdbusconnection.c" + line="6960">a #GVariant tuple with parameters for the method or %NULL if not passing parameters @@ -16655,20 +17488,20 @@ This method is only available on UNIX. nullable="1" allow-none="1"> the expected type of the reply, or %NULL + filename="gio/gdbusconnection.c" + line="6962">the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration + filename="gio/gdbusconnection.c" + line="6963">flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default + filename="gio/gdbusconnection.c" + line="6964">the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout @@ -16677,8 +17510,8 @@ This method is only available on UNIX. nullable="1" allow-none="1"> a #GUnixFDList or %NULL + filename="gio/gdbusconnection.c" + line="6966">a #GUnixFDList or %NULL nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="6967">a #GCancellable or %NULL scope="async" closure="11"> a #GAsyncReadyCallback to call when the request is + filename="gio/gdbusconnection.c" + line="6968">a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation @@ -16708,8 +17541,8 @@ This method is only available on UNIX. nullable="1" allow-none="1"> The data to pass to @callback. + filename="gio/gdbusconnection.c" + line="6971">The data to pass to @callback. @@ -16719,8 +17552,8 @@ This method is only available on UNIX. version="2.30" throws="1"> Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). + filename="gio/gdbusconnection.c" + line="7009">Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, @@ -16732,36 +17565,37 @@ When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. - + %NULL if @error is set. Otherwise a non-floating + filename="gio/gdbusconnection.c" + line="7030">%NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection + filename="gio/gdbusconnection.c" + line="7011">a #GDBusConnection return location for a #GUnixFDList or %NULL + filename="gio/gdbusconnection.c" + line="7012">return location for a #GUnixFDList or %NULL a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + filename="gio/gdbusconnection.c" + line="7013">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list() @@ -16770,27 +17604,28 @@ value of type %G_VARIANT_TYPE_HANDLE in the body of the message. + throws="1" + glib:async-func="call_with_unix_fd_list"> Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. + filename="gio/gdbusconnection.c" + line="7044">Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. See g_dbus_connection_call_with_unix_fd_list() and g_dbus_connection_call_with_unix_fd_list_finish() for more details. This method is only available on UNIX. - + %NULL if @error is set. Otherwise a non-floating + filename="gio/gdbusconnection.c" + line="7069">%NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). a #GDBusConnection + filename="gio/gdbusconnection.c" + line="7046">a #GDBusConnection nullable="1" allow-none="1"> a unique or well-known bus name or %NULL + filename="gio/gdbusconnection.c" + line="7047">a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object + filename="gio/gdbusconnection.c" + line="7049">path of remote object D-Bus interface to invoke method on + filename="gio/gdbusconnection.c" + line="7050">D-Bus interface to invoke method on the name of the method to invoke + filename="gio/gdbusconnection.c" + line="7051">the name of the method to invoke nullable="1" allow-none="1"> a #GVariant tuple with parameters for + filename="gio/gdbusconnection.c" + line="7052">a #GVariant tuple with parameters for the method or %NULL if not passing parameters @@ -16836,20 +17671,20 @@ This method is only available on UNIX. nullable="1" allow-none="1"> the expected type of the reply, or %NULL + filename="gio/gdbusconnection.c" + line="7054">the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration + filename="gio/gdbusconnection.c" + line="7055">flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default + filename="gio/gdbusconnection.c" + line="7056">the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout @@ -16858,19 +17693,20 @@ This method is only available on UNIX. nullable="1" allow-none="1"> a #GUnixFDList or %NULL + filename="gio/gdbusconnection.c" + line="7058">a #GUnixFDList or %NULL return location for a #GUnixFDList or %NULL + filename="gio/gdbusconnection.c" + line="7059">return location for a #GUnixFDList or %NULL nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="7060">a #GCancellable or %NULL + version="2.26" + glib:finish-func="close_finish" + glib:sync-func="close_sync"> Closes @connection. Note that this never causes the process to + filename="gio/gdbusconnection.c" + line="1543">Closes @connection. Note that this never causes the process to exit (this might only happen if the other end of a shared message bus connection disconnects, see #GDBusConnection:exit-on-close). @@ -16902,26 +17740,26 @@ If @connection is already closed, this method fails with %G_IO_ERROR_CLOSED. When @connection has been closed, the #GDBusConnection::closed -signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] +signal is emitted in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread that @connection was constructed in. This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +@callback will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_close_finish() to get the result of the operation. See g_dbus_connection_close_sync() for the synchronous version. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1545">a #GDBusConnection nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="1546">a #GCancellable or %NULL scope="async" closure="2"> a #GAsyncReadyCallback to call when the request is + filename="gio/gdbusconnection.c" + line="1547">a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result @@ -16950,8 +17788,8 @@ version. nullable="1" allow-none="1"> The data to pass to @callback + filename="gio/gdbusconnection.c" + line="1549">The data to pass to @callback @@ -16961,26 +17799,26 @@ version. version="2.26" throws="1"> Finishes an operation started with g_dbus_connection_close(). - + filename="gio/gdbusconnection.c" + line="1600">Finishes an operation started with g_dbus_connection_close(). + %TRUE if the operation succeeded, %FALSE if @error is set + filename="gio/gdbusconnection.c" + line="1609">%TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1602">a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed + filename="gio/gdbusconnection.c" + line="1603">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close() @@ -16989,25 +17827,26 @@ version. + throws="1" + glib:async-func="close"> Synchronously closes @connection. The calling thread is blocked + filename="gio/gdbusconnection.c" + line="1642">Synchronously closes @connection. The calling thread is blocked until this is done. See g_dbus_connection_close() for the asynchronous version of this method and more details about what it does. - + %TRUE if the operation succeeded, %FALSE if @error is set + filename="gio/gdbusconnection.c" + line="1653">%TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1644">a #GDBusConnection nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="1645">a #GCancellable or %NULL @@ -17026,26 +17865,26 @@ does. version="2.26" throws="1"> Emits a signal. + filename="gio/gdbusconnection.c" + line="6266">Emits a signal. If the parameters GVariant is floating, it is consumed. This can only fail if @parameters is not compatible with the D-Bus protocol (%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed (%G_IO_ERROR_CLOSED). - + %TRUE unless @error is set + filename="gio/gdbusconnection.c" + line="6286">%TRUE unless @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="6268">a #GDBusConnection the unique bus name for the destination + filename="gio/gdbusconnection.c" + line="6269">the unique bus name for the destination for the signal or %NULL to emit to all listeners path of remote object + filename="gio/gdbusconnection.c" + line="6271">path of remote object D-Bus interface to emit a signal on + filename="gio/gdbusconnection.c" + line="6272">D-Bus interface to emit a signal on the name of the signal to emit + filename="gio/gdbusconnection.c" + line="6273">the name of the signal to emit a #GVariant tuple with parameters for the signal + filename="gio/gdbusconnection.c" + line="6274">a #GVariant tuple with parameters for the signal or %NULL if not passing parameters @@ -17093,8 +17932,8 @@ This can only fail if @parameters is not compatible with the D-Bus protocol version="2.32" throws="1"> Exports @action_group on @connection at @object_path. + filename="gio/gactiongroupexporter.c" + line="557">Exports @action_group on @connection at @object_path. The implemented D-Bus API should be considered private. It is subject to change in the future. @@ -17104,7 +17943,7 @@ If this constraint is violated, the export will fail and 0 will be returned (with @error set accordingly). You can unexport the action group using -g_dbus_connection_unexport_action_group() with the return value of +[method@Gio.DBusConnection.unexport_action_group] with the return value of this function. The thread default main context is taken at the time of this call. @@ -17115,30 +17954,30 @@ Since incoming action activations and state change requests are rather likely to cause changes on the action group, this effectively limits a given action group to being exported from only one main context. - + the ID of the export (never zero), or 0 in case of failure + filename="gio/gactiongroupexporter.c" + line="585">the ID of the export (never zero), or 0 in case of failure a #GDBusConnection + filename="gio/gactiongroupexporter.c" + line="559">the D-Bus connection a D-Bus object path + filename="gio/gactiongroupexporter.c" + line="560">a D-Bus object path a #GActionGroup + filename="gio/gactiongroupexporter.c" + line="561">an action group @@ -17148,8 +17987,8 @@ context. version="2.32" throws="1"> Exports @menu on @connection at @object_path. + filename="gio/gmenuexporter.c" + line="754">Exports @menu on @connection at @object_path. The implemented D-Bus API should be considered private. It is subject to change in the future. @@ -17165,62 +18004,64 @@ undefined behavior. You can unexport the menu model using g_dbus_connection_unexport_menu_model() with the return value of this function. - + the ID of the export (never zero), or 0 in case of failure + filename="gio/gmenuexporter.c" + line="778">the ID of the export (never zero), or 0 in case of failure a #GDBusConnection + filename="gio/gmenuexporter.c" + line="756">a #GDBusConnection a D-Bus object path + filename="gio/gmenuexporter.c" + line="757">a D-Bus object path a #GMenuModel + filename="gio/gmenuexporter.c" + line="758">a #GMenuModel + version="2.26" + glib:finish-func="flush_finish" + glib:sync-func="flush_sync"> Asynchronously flushes @connection, that is, writes all queued -outgoing message to the transport and then flushes the transport + filename="gio/gdbusconnection.c" + line="1362">Asynchronously flushes @connection, that is, writes all queued +outgoing messages to the transport and then flushes the transport (using g_output_stream_flush_async()). This is useful in programs -that wants to emit a D-Bus signal and then exit immediately. Without -flushing the connection, there is no guaranteed that the message has +that want to emit a D-Bus signal and then exit immediately. Without +flushing the connection, there is no guarantee that the message has been sent to the networking buffers in the OS kernel. This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +@callback will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_flush_finish() to get the result of the operation. See g_dbus_connection_flush_sync() for the synchronous version. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1364">a #GDBusConnection nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="1365">a #GCancellable or %NULL scope="async" closure="2"> a #GAsyncReadyCallback to call when the + filename="gio/gdbusconnection.c" + line="1366">a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result @@ -17249,8 +18090,8 @@ version. nullable="1" allow-none="1"> The data to pass to @callback + filename="gio/gdbusconnection.c" + line="1368">The data to pass to @callback @@ -17260,26 +18101,26 @@ version. version="2.26" throws="1"> Finishes an operation started with g_dbus_connection_flush(). - + filename="gio/gdbusconnection.c" + line="1403">Finishes an operation started with g_dbus_connection_flush(). + %TRUE if the operation succeeded, %FALSE if @error is set + filename="gio/gdbusconnection.c" + line="1412">%TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1405">a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed + filename="gio/gdbusconnection.c" + line="1406">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush() @@ -17288,25 +18129,26 @@ version. + throws="1" + glib:async-func="flush"> Synchronously flushes @connection. The calling thread is blocked + filename="gio/gdbusconnection.c" + line="1428">Synchronously flushes @connection. The calling thread is blocked until this is done. See g_dbus_connection_flush() for the asynchronous version of this method and more details about what it does. - + %TRUE if the operation succeeded, %FALSE if @error is set + filename="gio/gdbusconnection.c" + line="1439">%TRUE if the operation succeeded, %FALSE if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1430">a #GDBusConnection nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="1431">a #GCancellable or %NULL @@ -17325,20 +18167,20 @@ does. glib:get-property="capabilities" version="2.26"> Gets the capabilities negotiated with the remote peer - + filename="gio/gdbusconnection.c" + line="1299">Gets the capabilities negotiated with the remote peer + zero or more flags from the #GDBusCapabilityFlags enumeration + filename="gio/gdbusconnection.c" + line="1305">zero or more flags from the #GDBusCapabilityFlags enumeration a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1301">a #GDBusConnection @@ -17348,23 +18190,23 @@ does. glib:get-property="exit-on-close" version="2.26"> Gets whether the process is terminated when @connection is + filename="gio/gdbusconnection.c" + line="3387">Gets whether the process is terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. - + whether the process is terminated when @connection is + filename="gio/gdbusconnection.c" + line="3395">whether the process is terminated when @connection is closed by the remote peer a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3389">a #GDBusConnection @@ -17374,20 +18216,20 @@ closed by the remote peer. See glib:get-property="flags" version="2.60"> Gets the flags used to construct this connection - + filename="gio/gdbusconnection.c" + line="1321">Gets the flags used to construct this connection + zero or more flags from the #GDBusConnectionFlags enumeration + filename="gio/gdbusconnection.c" + line="1327">zero or more flags from the #GDBusConnectionFlags enumeration a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1323">a #GDBusConnection @@ -17397,22 +18239,22 @@ closed by the remote peer. See glib:get-property="guid" version="2.26"> The GUID of the peer performing the role of server when + filename="gio/gdbusconnection.c" + line="3411">The GUID of the peer performing the role of server when authenticating. See #GDBusConnection:guid for more details. - + The GUID. Do not free this string, it is owned by + filename="gio/gdbusconnection.c" + line="3418">The GUID. Do not free this string, it is owned by @connection. a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3413">a #GDBusConnection @@ -17421,25 +18263,25 @@ authenticating. See #GDBusConnection:guid for more details. c:identifier="g_dbus_connection_get_last_serial" version="2.34"> Retrieves the last serial number assigned to a #GDBusMessage on + filename="gio/gdbusconnection.c" + line="1694">Retrieves the last serial number assigned to a #GDBusMessage on the current thread. This includes messages sent via both low-level API such as g_dbus_connection_send_message() as well as high-level API such as g_dbus_connection_emit_signal(), g_dbus_connection_call() or g_dbus_proxy_call(). - + the last used serial or zero when no message has been sent + filename="gio/gdbusconnection.c" + line="1704">the last used serial or zero when no message has been sent within the current thread a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1696">a #GDBusConnection @@ -17448,8 +18290,8 @@ g_dbus_connection_call() or g_dbus_proxy_call(). c:identifier="g_dbus_connection_get_peer_credentials" version="2.26"> Gets the credentials of the authenticated peer. This will always + filename="gio/gdbusconnection.c" + line="3456">Gets the credentials of the authenticated peer. This will always return %NULL unless @connection acted as a server (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the @@ -17458,19 +18300,19 @@ authentication process. In a message bus setup, the message bus is always the server and each application is a client. So this method will always return %NULL for message bus clients. - + a #GCredentials or %NULL if not + filename="gio/gdbusconnection.c" + line="3470">a #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection. a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3458">a #GDBusConnection @@ -17480,24 +18322,24 @@ each application is a client. So this method will always return glib:get-property="stream" version="2.26"> Gets the underlying stream used for IO. + filename="gio/gdbusconnection.c" + line="1227">Gets the underlying stream used for IO. While the #GDBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly. - + the stream used for IO + filename="gio/gdbusconnection.c" + line="1237">the stream used for IO a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1229">a #GDBusConnection @@ -17507,15 +18349,15 @@ the stream directly. glib:get-property="unique-name" version="2.26"> Gets the unique name of @connection as assigned by the message + filename="gio/gdbusconnection.c" + line="3430">Gets the unique name of @connection as assigned by the message bus. This can also be used to figure out if @connection is a message bus connection. - + the unique name or %NULL if @connection is not a message + filename="gio/gdbusconnection.c" + line="3438">the unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection. @@ -17523,30 +18365,31 @@ message bus connection. a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3432">a #GDBusConnection Gets whether @connection is closed. - + filename="gio/gdbusconnection.c" + line="1277">Gets whether @connection is closed. + %TRUE if the connection is closed, %FALSE otherwise + filename="gio/gdbusconnection.c" + line="1283">%TRUE if the connection is closed, %FALSE otherwise a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1279">a #GDBusConnection @@ -17557,13 +18400,13 @@ message bus connection. version="2.26" throws="1"> Registers callbacks for exported objects at @object_path with the + filename="gio/gdbusconnection.c" + line="5703">Registers callbacks for exported objects at @object_path with the D-Bus interface that is described in @interface_info. Calls to functions in @vtable (and @user_data_free_func) will happen -in the -[thread-default main context][g-main-context-push-thread-default] +in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. Note that all #GVariant values passed to functions in @vtable will match @@ -17595,32 +18438,33 @@ incremented by 1 (unless allocated statically, e.g. if the reference count is -1, see g_dbus_interface_info_ref()) for as long as the object is exported. Also note that @vtable will be copied. -See this [server][gdbus-server] for an example of how to use this method. - +See this [server][class@Gio.DBusConnection#an-example-d-bus-server] +for an example of how to use this method. + 0 if @error is set, otherwise a registration id (never 0) + filename="gio/gdbusconnection.c" + line="5753">0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() a #GDBusConnection + filename="gio/gdbusconnection.c" + line="5705">a #GDBusConnection the object path to register at + filename="gio/gdbusconnection.c" + line="5706">the object path to register at introspection data for the interface + filename="gio/gdbusconnection.c" + line="5707">introspection data for the interface nullable="1" allow-none="1"> a #GDBusInterfaceVTable to call into or %NULL + filename="gio/gdbusconnection.c" + line="5708">a #GDBusInterfaceVTable to call into or %NULL @@ -17638,16 +18482,16 @@ See this [server][gdbus-server] for an example of how to use this method. nullable="1" allow-none="1"> data to pass to functions in @vtable + filename="gio/gdbusconnection.c" + line="5709">data to pass to functions in @vtable function to call when the object path is unregistered + filename="gio/gdbusconnection.c" + line="5710">function to call when the object path is unregistered @@ -17656,36 +18500,46 @@ See this [server][gdbus-server] for an example of how to use this method. c:identifier="g_dbus_connection_register_object_with_closures" shadows="register_object" version="2.46" + deprecated="1" + deprecated-version="2.84" throws="1"> Version of g_dbus_connection_register_object() using closures instead of a -#GDBusInterfaceVTable for easier binding in other languages. - + filename="gio/gdbusconnection.c" + line="6098">Version of g_dbus_connection_register_object() using closures instead of a +#GDBusInterfaceVTable for easier binding in other languages. + +Note that the reference counting semantics of the function wrapped by +@method_call_closure are the same as those of +[callback@Gio.DBusInterfaceMethodCallFunc]: ownership of a reference to the +[class@Gio.DBusMethodInvocation] is transferred to the function. + Deprecated in favour of + [method@Gio.DBusConnection.register_object_with_closures2], which has more + binding-friendly reference counting semantics. + 0 if @error is set, otherwise a registration ID (never 0) + filename="gio/gdbusconnection.c" + line="6116">0 if @error is set, otherwise a registration ID (never 0) that can be used with g_dbus_connection_unregister_object() . A #GDBusConnection. + filename="gio/gdbusconnection.c" + line="6100">A #GDBusConnection. The object path to register at. + filename="gio/gdbusconnection.c" + line="6101">The object path to register at. Introspection data for the interface. + filename="gio/gdbusconnection.c" + line="6102">Introspection data for the interface. nullable="1" allow-none="1"> #GClosure for handling incoming method calls. + filename="gio/gdbusconnection.c" + line="6103">#GClosure for handling incoming method calls. nullable="1" allow-none="1"> #GClosure for getting a property. + filename="gio/gdbusconnection.c" + line="6104">#GClosure for getting a property. nullable="1" allow-none="1"> #GClosure for setting a property. + filename="gio/gdbusconnection.c" + line="6105">#GClosure for setting a property. + + + + + + Version of [method@Gio.DBusConnection.register_object] using closures instead +of a [type@Gio.DBusInterfaceVTable] for easier binding in other languages. + +In contrast to [method@Gio.DBusConnection.register_object] and +[method@Gio.DBusConnection.register_object_with_closures], the reference +counting semantics of the function wrapped by @method_call_closure are *not* +the same as those of [callback@Gio.DBusInterfaceMethodCallFunc]. Ownership of +a reference to the [class@Gio.DBusMethodInvocation] is *not* transferred to +the function. Bindings must ensure that they add a reference to the +[class@Gio.DBusMethodInvocation] before calling any +`g_dbus_method_invocation_return_*()` methods on it. This should be automatic +as a result of the introspection annotations on those methods. + + + `0` if @error is set, otherwise a registration ID (never `0`) +that can be used with [method@Gio.DBusConnection.unregister_object]. + + + + + A [class@Gio.DBusConnection]. + + + + The object path to register at. + + + + Introspection data for the interface. + + + + [type@GObject.Closure] for handling incoming method calls. + + + + [type@GObject.Closure] for getting a property. + + + + [type@GObject.Closure] for setting a property. @@ -17722,8 +18650,8 @@ that can be used with g_dbus_connection_unregister_object() . version="2.26" throws="1"> Registers a whole subtree of dynamic objects. + filename="gio/gdbusconnection.c" + line="7508">Registers a whole subtree of dynamic objects. The @enumerate and @introspection functions in @vtable are used to convey, to remote callers, what nodes exist in the subtree rooted @@ -17738,8 +18666,8 @@ where to dispatch the call. The collected #GDBusInterfaceVTable and #gpointer will be used to call into the interface vtable for processing the request. -All calls into user-provided code will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +All calls into user-provided code will be invoked in the thread-default +main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. If an existing subtree is already registered at @object_path or @@ -17755,40 +18683,40 @@ registered via g_dbus_connection_register_object() or other bindings. Note that @vtable will be copied so you cannot change it after registration. -See this [server][gdbus-subtree-server] for an example of how to use -this method. - +See this [server][class@Gio.DBusConnection#an-example-for-exporting-a-subtree] +for an example of how to use this method. + 0 if @error is set, otherwise a subtree registration ID (never 0) + filename="gio/gdbusconnection.c" + line="7554">0 if @error is set, otherwise a subtree registration ID (never 0) that can be used with g_dbus_connection_unregister_subtree() a #GDBusConnection + filename="gio/gdbusconnection.c" + line="7510">a #GDBusConnection the object path to register the subtree at + filename="gio/gdbusconnection.c" + line="7511">the object path to register the subtree at a #GDBusSubtreeVTable to enumerate, introspect and + filename="gio/gdbusconnection.c" + line="7512">a #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree flags used to fine tune the behavior of the subtree + filename="gio/gdbusconnection.c" + line="7514">flags used to fine tune the behavior of the subtree nullable="1" allow-none="1"> data to pass to functions in @vtable + filename="gio/gdbusconnection.c" + line="7515">data to pass to functions in @vtable function to call when the subtree is unregistered + filename="gio/gdbusconnection.c" + line="7516">function to call when the subtree is unregistered @@ -17814,8 +18742,8 @@ that can be used with g_dbus_connection_unregister_subtree() c:identifier="g_dbus_connection_remove_filter" version="2.26"> Removes a filter. + filename="gio/gdbusconnection.c" + line="3568">Removes a filter. Note that since filters run in a different thread, there is a race condition where it is possible that the filter will be running even @@ -17823,21 +18751,21 @@ after calling g_dbus_connection_remove_filter(), so you cannot just free data that the filter might be using. Instead, you should pass a #GDestroyNotify to g_dbus_connection_add_filter(), which will be called when it is guaranteed that the data is no longer needed. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3570">a #GDBusConnection an identifier obtained from g_dbus_connection_add_filter() + filename="gio/gdbusconnection.c" + line="3571">an identifier obtained from g_dbus_connection_add_filter() @@ -17847,8 +18775,8 @@ called when it is guaranteed that the data is no longer needed. version="2.26" throws="1"> Asynchronously sends @message to the peer represented by @connection. + filename="gio/gdbusconnection.c" + line="1831">Asynchronously sends @message to the peer represented by @connection. Unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number @@ -17863,37 +18791,38 @@ If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @message is not well-formed, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] +See this [server][class@Gio.DBusConnection#an-example-d-bus-server] +and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - + %TRUE if the message was well-formed and queued for + filename="gio/gdbusconnection.c" + line="1863">%TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1833">a #GDBusConnection a #GDBusMessage + filename="gio/gdbusconnection.c" + line="1834">a #GDBusMessage flags affecting how the message is sent + filename="gio/gdbusconnection.c" + line="1835">flags affecting how the message is sent return location for serial number assigned + filename="gio/gdbusconnection.c" + line="1836">return location for serial number assigned to @message when sending it or %NULL @@ -17912,10 +18841,11 @@ Note that @message must be unlocked, unless @flags contain the + version="2.26" + glib:finish-func="send_message_with_reply_finish"> Asynchronously sends @message to the peer represented by @connection. + filename="gio/gdbusconnection.c" + line="2111">Asynchronously sends @message to the peer represented by @connection. Unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number @@ -17932,8 +18862,8 @@ fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. This is an asynchronous method. When the operation is finished, @callback -will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. @@ -17941,36 +18871,37 @@ See g_dbus_connection_send_message_with_reply_sync() for the synchronous version Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] +See this [server][class@Gio.DBusConnection#an-example-d-bus-server] +and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="2113">a #GDBusConnection a #GDBusMessage + filename="gio/gdbusconnection.c" + line="2114">a #GDBusMessage flags affecting how the message is sent + filename="gio/gdbusconnection.c" + line="2115">flags affecting how the message is sent the timeout in milliseconds, -1 to use the default + filename="gio/gdbusconnection.c" + line="2116">the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout @@ -17981,8 +18912,8 @@ UNIX file descriptors. optional="1" allow-none="1"> return location for serial number assigned + filename="gio/gdbusconnection.c" + line="2118">return location for serial number assigned to @message when sending it or %NULL @@ -17991,8 +18922,8 @@ UNIX file descriptors. nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="2120">a #GCancellable or %NULL scope="async" closure="6"> a #GAsyncReadyCallback to call when the request + filename="gio/gdbusconnection.c" + line="2121">a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result @@ -18012,8 +18943,8 @@ UNIX file descriptors. nullable="1" allow-none="1"> The data to pass to @callback + filename="gio/gdbusconnection.c" + line="2123">The data to pass to @callback @@ -18023,35 +18954,36 @@ UNIX file descriptors. version="2.26" throws="1"> Finishes an operation started with g_dbus_connection_send_message_with_reply(). + filename="gio/gdbusconnection.c" + line="2185">Finishes an operation started with g_dbus_connection_send_message_with_reply(). Note that @error is only set if a local in-process error occurred. That is to say that the returned #GDBusMessage object may be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError. -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] +See this [server][class@Gio.DBusConnection#an-example-d-bus-server] +and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. - + a locked #GDBusMessage or %NULL if @error is set + filename="gio/gdbusconnection.c" + line="2204">a locked #GDBusMessage or %NULL if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="2187">a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + filename="gio/gdbusconnection.c" + line="2188">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply() @@ -18062,8 +18994,8 @@ UNIX file descriptors. version="2.26" throws="1"> Synchronously sends @message to the peer represented by @connection + filename="gio/gdbusconnection.c" + line="2240">Synchronously sends @message to the peer represented by @connection and blocks the calling thread until a reply is received or the timeout is reached. See g_dbus_connection_send_message_with_reply() for the asynchronous version of this method. @@ -18087,43 +19019,44 @@ occurred. That is to say that the returned #GDBusMessage object may be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError. -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] +See this [server][class@Gio.DBusConnection#an-example-d-bus-server] +and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - + a locked #GDBusMessage that is the reply + filename="gio/gdbusconnection.c" + line="2284">a locked #GDBusMessage that is the reply to @message or %NULL if @error is set a #GDBusConnection + filename="gio/gdbusconnection.c" + line="2242">a #GDBusConnection a #GDBusMessage + filename="gio/gdbusconnection.c" + line="2243">a #GDBusMessage flags affecting how the message is sent. + filename="gio/gdbusconnection.c" + line="2244">flags affecting how the message is sent. the timeout in milliseconds, -1 to use the default + filename="gio/gdbusconnection.c" + line="2245">the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout @@ -18134,8 +19067,8 @@ Note that @message must be unlocked, unless @flags contain the optional="1" allow-none="1"> return location for serial number + filename="gio/gdbusconnection.c" + line="2247">return location for serial number assigned to @message when sending it or %NULL @@ -18144,8 +19077,8 @@ Note that @message must be unlocked, unless @flags contain the nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="2249">a #GCancellable or %NULL @@ -18155,8 +19088,8 @@ Note that @message must be unlocked, unless @flags contain the glib:set-property="exit-on-close" version="2.26"> Sets whether the process should be terminated when @connection is + filename="gio/gdbusconnection.c" + line="3355">Sets whether the process should be terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. @@ -18166,21 +19099,21 @@ all of a user's applications to quit when their bus connection goes away. If you are setting @exit_on_close to %FALSE for the shared session bus connection, you should make sure that your application exits when the user session ends. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3357">a #GDBusConnection whether the process should be terminated + filename="gio/gdbusconnection.c" + line="3358">whether the process should be terminated when @connection is closed by the remote peer @@ -18190,10 +19123,10 @@ when the user session ends. c:identifier="g_dbus_connection_signal_subscribe" version="2.26"> Subscribes to signals on @connection and invokes @callback whenever + filename="gio/gdbusconnection.c" + line="3781">Subscribes to signals on @connection and invokes @callback whenever the signal is received. Note that @callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. If @connection is not a message bus connection, @sender must be @@ -18240,18 +19173,18 @@ The returned subscription identifier is an opaque value which is guaranteed to never be zero. This function can never fail. - + a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() + filename="gio/gdbusconnection.c" + line="3851">a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() a #GDBusConnection + filename="gio/gdbusconnection.c" + line="3783">a #GDBusConnection nullable="1" allow-none="1"> sender name to match on (unique or well-known name) + filename="gio/gdbusconnection.c" + line="3784">sender name to match on (unique or well-known name) or %NULL to listen from all senders @@ -18269,8 +19202,8 @@ This function can never fail. nullable="1" allow-none="1"> D-Bus interface name to match on or %NULL to + filename="gio/gdbusconnection.c" + line="3786">D-Bus interface name to match on or %NULL to match on all interfaces @@ -18279,8 +19212,8 @@ This function can never fail. nullable="1" allow-none="1"> D-Bus signal name to match on or %NULL to match on + filename="gio/gdbusconnection.c" + line="3788">D-Bus signal name to match on or %NULL to match on all signals @@ -18289,8 +19222,8 @@ This function can never fail. nullable="1" allow-none="1"> object path to match on or %NULL to match on + filename="gio/gdbusconnection.c" + line="3790">object path to match on or %NULL to match on all object paths @@ -18299,15 +19232,15 @@ This function can never fail. nullable="1" allow-none="1"> contents of first string argument to match on or %NULL + filename="gio/gdbusconnection.c" + line="3792">contents of first string argument to match on or %NULL to match on all kinds of arguments #GDBusSignalFlags describing how arg0 is used in subscribing to the + filename="gio/gdbusconnection.c" + line="3794">#GDBusSignalFlags describing how arg0 is used in subscribing to the signal @@ -18317,8 +19250,8 @@ This function can never fail. closure="7" destroy="8"> callback to invoke when there is a signal matching the requested data + filename="gio/gdbusconnection.c" + line="3796">callback to invoke when there is a signal matching the requested data nullable="1" allow-none="1"> user data to pass to @callback + filename="gio/gdbusconnection.c" + line="3797">user data to pass to @callback allow-none="1" scope="async"> function to free @user_data with when + filename="gio/gdbusconnection.c" + line="3798">function to free @user_data with when subscription is removed or %NULL @@ -18347,8 +19280,8 @@ This function can never fail. c:identifier="g_dbus_connection_signal_unsubscribe" version="2.26"> Unsubscribes from signals. + filename="gio/gdbusconnection.c" + line="4116">Unsubscribes from signals. Note that there may still be D-Bus traffic to process (relating to this signal subscription) in the current thread-default #GMainContext after this @@ -18360,21 +19293,21 @@ iterated. Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT that was scheduled after unsubscription, also indicates that all resources of this subscription are released. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="4118">a #GDBusConnection a subscription id obtained from + filename="gio/gdbusconnection.c" + line="4119">a subscription id obtained from g_dbus_connection_signal_subscribe() @@ -18384,20 +19317,20 @@ of this subscription are released. c:identifier="g_dbus_connection_start_message_processing" version="2.26"> If @connection was created with + filename="gio/gdbusconnection.c" + line="1253">If @connection was created with %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method starts processing messages. Does nothing on if @connection wasn't created with this flag or if the method has already been called. - + a #GDBusConnection + filename="gio/gdbusconnection.c" + line="1255">a #GDBusConnection @@ -18406,28 +19339,28 @@ created with this flag or if the method has already been called. c:identifier="g_dbus_connection_unexport_action_group" version="2.32"> Reverses the effect of a previous call to -g_dbus_connection_export_action_group(). + filename="gio/gactiongroupexporter.c" + line="641">Reverses the effect of a previous call to +[method@Gio.DBusConnection.export_action_group]. -It is an error to call this function with an ID that wasn't returned -from g_dbus_connection_export_action_group() or to call it with the -same ID more than once. - +It is an error to call this function with an ID that wasn’t returned from +[method@Gio.DBusConnection.export_action_group] or to call it with the same +ID more than once. + a #GDBusConnection + filename="gio/gactiongroupexporter.c" + line="643">the D-Bus connection the ID from g_dbus_connection_export_action_group() + filename="gio/gactiongroupexporter.c" + line="644">the ID from [method@Gio.DBusConnection.export_action_group] @@ -18436,28 +19369,28 @@ same ID more than once. c:identifier="g_dbus_connection_unexport_menu_model" version="2.32"> Reverses the effect of a previous call to + filename="gio/gmenuexporter.c" + line="809">Reverses the effect of a previous call to g_dbus_connection_export_menu_model(). It is an error to call this function with an ID that wasn't returned from g_dbus_connection_export_menu_model() or to call it with the same ID more than once. - + a #GDBusConnection + filename="gio/gmenuexporter.c" + line="811">a #GDBusConnection the ID from g_dbus_connection_export_menu_model() + filename="gio/gmenuexporter.c" + line="812">the ID from g_dbus_connection_export_menu_model() @@ -18466,26 +19399,26 @@ same ID more than once. c:identifier="g_dbus_connection_unregister_object" version="2.26"> Unregisters an object. - + filename="gio/gdbusconnection.c" + line="5837">Unregisters an object. + %TRUE if the object was unregistered, %FALSE otherwise + filename="gio/gdbusconnection.c" + line="5845">%TRUE if the object was unregistered, %FALSE otherwise a #GDBusConnection + filename="gio/gdbusconnection.c" + line="5839">a #GDBusConnection a registration id obtained from + filename="gio/gdbusconnection.c" + line="5840">a registration id obtained from g_dbus_connection_register_object() @@ -18495,26 +19428,26 @@ same ID more than once. c:identifier="g_dbus_connection_unregister_subtree" version="2.26"> Unregisters a subtree. - + filename="gio/gdbusconnection.c" + line="7622">Unregisters a subtree. + %TRUE if the subtree was unregistered, %FALSE otherwise + filename="gio/gdbusconnection.c" + line="7630">%TRUE if the subtree was unregistered, %FALSE otherwise a #GDBusConnection + filename="gio/gdbusconnection.c" + line="7624">a #GDBusConnection a subtree registration id obtained from + filename="gio/gdbusconnection.c" + line="7625">a subtree registration id obtained from g_dbus_connection_register_subtree() @@ -18528,8 +19461,8 @@ same ID more than once. transfer-ownership="none" default-value="NULL"> A D-Bus address specifying potential endpoints that can be used + filename="gio/gdbusconnection.c" + line="977">A D-Bus address specifying potential endpoints that can be used when establishing the connection. @@ -18540,8 +19473,8 @@ when establishing the connection. construct-only="1" transfer-ownership="none"> A #GDBusAuthObserver object to assist in the authentication process or %NULL. + filename="gio/gdbusconnection.c" + line="1126">A #GDBusAuthObserver object to assist in the authentication process or %NULL. getter="get_capabilities" default-value="G_DBUS_CAPABILITY_FLAGS_NONE"> Flags from the #GDBusCapabilityFlags enumeration + filename="gio/gdbusconnection.c" + line="1108">Flags from the #GDBusCapabilityFlags enumeration representing connection features negotiated with the other peer. A boolean specifying whether the connection has been closed. + filename="gio/gdbusconnection.c" + line="1070">A boolean specifying whether the connection has been closed. getter="get_exit_on_close" default-value="FALSE"> A boolean specifying whether the process will be terminated (by + filename="gio/gdbusconnection.c" + line="1086">A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer. @@ -18589,8 +19523,8 @@ and g_bus_get_sync() will (usually) have this property set to %TRUE. getter="get_flags" default-value="G_DBUS_CONNECTION_FLAGS_NONE"> Flags from the #GDBusConnectionFlags enumeration. + filename="gio/gdbusconnection.c" + line="995">Flags from the #GDBusConnectionFlags enumeration. getter="get_guid" default-value="NULL"> The GUID of the peer performing the role of server when + filename="gio/gdbusconnection.c" + line="1014">The GUID of the peer performing the role of server when authenticating. If you are constructing a #GDBusConnection and pass @@ -18633,8 +19567,8 @@ GUID format. transfer-ownership="none" getter="get_stream"> The underlying #GIOStream used for I/O. + filename="gio/gdbusconnection.c" + line="952">The underlying #GIOStream used for I/O. If this is passed on construction and is a #GSocketConnection, then the corresponding #GSocket will be put into non-blocking mode. @@ -18650,15 +19584,15 @@ the stream directly. getter="get_unique_name" default-value="NULL"> The unique name as assigned by the message bus or %NULL if the + filename="gio/gdbusconnection.c" + line="1053">The unique name as assigned by the message bus or %NULL if the connection is not open or not a message bus connection. Emitted when the connection is closed. + filename="gio/gdbusconnection.c" + line="1143">Emitted when the connection is closed. The cause of this event can be @@ -18680,8 +19614,8 @@ once. %TRUE if @connection is closed because the + filename="gio/gdbusconnection.c" + line="1146">%TRUE if @connection is closed because the remote peer closed its end of the connection @@ -18690,8 +19624,8 @@ once. nullable="1" allow-none="1"> a #GError with more details about the event or %NULL + filename="gio/gdbusconnection.c" + line="1148">a #GError with more details about the event or %NULL @@ -18703,16 +19637,16 @@ once. glib:get-type="g_dbus_connection_flags_get_type" c:type="GDBusConnectionFlags"> Flags used when creating a new #GDBusConnection. + filename="gio/gioenums.h" + line="1214">Flags used when creating a new #GDBusConnection. No flags set. + filename="gio/gioenums.h" + line="1216">No flags set. glib:nick="authentication-client" glib:name="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT"> Perform authentication against server. + filename="gio/gioenums.h" + line="1217">Perform authentication against server. glib:nick="authentication-server" glib:name="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER"> Perform authentication against client. + filename="gio/gioenums.h" + line="1218">Perform authentication against client. glib:nick="authentication-allow-anonymous" glib:name="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS"> When + filename="gio/gioenums.h" + line="1219">When authenticating as a server, allow the anonymous authentication method. @@ -18749,8 +19683,8 @@ method. glib:nick="message-bus-connection" glib:name="G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION"> Pass this flag if connecting to a peer that is a + filename="gio/gioenums.h" + line="1222">Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup. If set, processing of D-Bus messages is + filename="gio/gioenums.h" + line="1224">If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called. glib:nick="authentication-require-same-user" glib:name="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER"> When authenticating + filename="gio/gioenums.h" + line="1226">When authenticating as a server, require the UID of the peer to be the same as the UID of the server. (Since: 2.68) When authenticating, try to use + filename="gio/gioenums.h" + line="1228">When authenticating, try to use protocols that work across a Linux user namespace boundary, even if this reduces interoperability with older D-Bus implementations. This currently affects client-side `EXTERNAL` authentication, for which this flag makes @@ -18795,16 +19729,16 @@ as a server, require the UID of the peer to be the same as the UID of the server c:type="GDBusError" glib:error-domain="g-dbus-error-quark"> Error codes for the %G_DBUS_ERROR error domain. + filename="gio/gioenums.h" + line="1056">Error codes for the %G_DBUS_ERROR error domain. A generic error; "something went wrong" - see the error message for + filename="gio/gioenums.h" + line="1058">A generic error; "something went wrong" - see the error message for more. glib:nick="no-memory" glib:name="G_DBUS_ERROR_NO_MEMORY"> There was not enough memory to complete an operation. + filename="gio/gioenums.h" + line="1061">There was not enough memory to complete an operation. glib:nick="service-unknown" glib:name="G_DBUS_ERROR_SERVICE_UNKNOWN"> The bus doesn't know how to launch a service to supply the bus name + filename="gio/gioenums.h" + line="1063">The bus doesn't know how to launch a service to supply the bus name you wanted. glib:nick="name-has-no-owner" glib:name="G_DBUS_ERROR_NAME_HAS_NO_OWNER"> The bus name you referenced doesn't exist (i.e. no application owns + filename="gio/gioenums.h" + line="1066">The bus name you referenced doesn't exist (i.e. no application owns it). glib:nick="no-reply" glib:name="G_DBUS_ERROR_NO_REPLY"> No reply to a message expecting one, usually means a timeout occurred. + filename="gio/gioenums.h" + line="1069">No reply to a message expecting one, usually means a timeout occurred. glib:nick="io-error" glib:name="G_DBUS_ERROR_IO_ERROR"> Something went wrong reading or writing to a socket, for example. + filename="gio/gioenums.h" + line="1071">Something went wrong reading or writing to a socket, for example. glib:nick="bad-address" glib:name="G_DBUS_ERROR_BAD_ADDRESS"> A D-Bus bus address was malformed. + filename="gio/gioenums.h" + line="1073">A D-Bus bus address was malformed. glib:nick="not-supported" glib:name="G_DBUS_ERROR_NOT_SUPPORTED"> Requested operation isn't supported (like ENOSYS on UNIX). + filename="gio/gioenums.h" + line="1075">Requested operation isn't supported (like ENOSYS on UNIX). glib:nick="limits-exceeded" glib:name="G_DBUS_ERROR_LIMITS_EXCEEDED"> Some limited resource is exhausted. + filename="gio/gioenums.h" + line="1077">Some limited resource is exhausted. glib:nick="access-denied" glib:name="G_DBUS_ERROR_ACCESS_DENIED"> Security restrictions don't allow doing what you're trying to do. + filename="gio/gioenums.h" + line="1079">Security restrictions don't allow doing what you're trying to do. glib:nick="auth-failed" glib:name="G_DBUS_ERROR_AUTH_FAILED"> Authentication didn't work. + filename="gio/gioenums.h" + line="1081">Authentication didn't work. glib:nick="no-server" glib:name="G_DBUS_ERROR_NO_SERVER"> Unable to connect to server (probably caused by ECONNREFUSED on a + filename="gio/gioenums.h" + line="1083">Unable to connect to server (probably caused by ECONNREFUSED on a socket). glib:nick="timeout" glib:name="G_DBUS_ERROR_TIMEOUT"> Certain timeout errors, possibly ETIMEDOUT on a socket. Note that + filename="gio/gioenums.h" + line="1086">Certain timeout errors, possibly ETIMEDOUT on a socket. Note that %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also exists. We can't fix it for compatibility reasons so just be @@ -18928,8 +19862,8 @@ careful. glib:nick="no-network" glib:name="G_DBUS_ERROR_NO_NETWORK"> No network access (probably ENETUNREACH on a socket). + filename="gio/gioenums.h" + line="1092">No network access (probably ENETUNREACH on a socket). glib:nick="address-in-use" glib:name="G_DBUS_ERROR_ADDRESS_IN_USE"> Can't bind a socket since its address is in use (i.e. EADDRINUSE). + filename="gio/gioenums.h" + line="1094">Can't bind a socket since its address is in use (i.e. EADDRINUSE). glib:nick="disconnected" glib:name="G_DBUS_ERROR_DISCONNECTED"> The connection is disconnected and you're trying to use it. + filename="gio/gioenums.h" + line="1096">The connection is disconnected and you're trying to use it. glib:nick="invalid-args" glib:name="G_DBUS_ERROR_INVALID_ARGS"> Invalid arguments passed to a method call. + filename="gio/gioenums.h" + line="1098">Invalid arguments passed to a method call. glib:nick="file-not-found" glib:name="G_DBUS_ERROR_FILE_NOT_FOUND"> Missing file. + filename="gio/gioenums.h" + line="1100">Missing file. glib:nick="file-exists" glib:name="G_DBUS_ERROR_FILE_EXISTS"> Existing file and the operation you're using does not silently overwrite. + filename="gio/gioenums.h" + line="1102">Existing file and the operation you're using does not silently overwrite. glib:nick="unknown-method" glib:name="G_DBUS_ERROR_UNKNOWN_METHOD"> Method name you invoked isn't known by the object you invoked it on. + filename="gio/gioenums.h" + line="1104">Method name you invoked isn't known by the object you invoked it on. glib:nick="timed-out" glib:name="G_DBUS_ERROR_TIMED_OUT"> Certain timeout errors, e.g. while starting a service. Warning: this is + filename="gio/gioenums.h" + line="1114">Certain timeout errors, e.g. while starting a service. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We can't fix it for compatibility reasons so just be careful. @@ -19002,8 +19936,8 @@ can't fix it for compatibility reasons so just be careful. glib:nick="match-rule-not-found" glib:name="G_DBUS_ERROR_MATCH_RULE_NOT_FOUND"> Tried to remove or modify a match rule that didn't exist. + filename="gio/gioenums.h" + line="1118">Tried to remove or modify a match rule that didn't exist. glib:nick="match-rule-invalid" glib:name="G_DBUS_ERROR_MATCH_RULE_INVALID"> The match rule isn't syntactically valid. + filename="gio/gioenums.h" + line="1120">The match rule isn't syntactically valid. glib:nick="spawn-exec-failed" glib:name="G_DBUS_ERROR_SPAWN_EXEC_FAILED"> While starting a new process, the exec() call failed. + filename="gio/gioenums.h" + line="1122">While starting a new process, the exec() call failed. glib:nick="spawn-fork-failed" glib:name="G_DBUS_ERROR_SPAWN_FORK_FAILED"> While starting a new process, the fork() call failed. + filename="gio/gioenums.h" + line="1124">While starting a new process, the fork() call failed. glib:nick="spawn-child-exited" glib:name="G_DBUS_ERROR_SPAWN_CHILD_EXITED"> While starting a new process, the child exited with a status code. + filename="gio/gioenums.h" + line="1126">While starting a new process, the child exited with a status code. glib:nick="spawn-child-signaled" glib:name="G_DBUS_ERROR_SPAWN_CHILD_SIGNALED"> While starting a new process, the child exited on a signal. + filename="gio/gioenums.h" + line="1128">While starting a new process, the child exited on a signal. glib:nick="spawn-failed" glib:name="G_DBUS_ERROR_SPAWN_FAILED"> While starting a new process, something went wrong. + filename="gio/gioenums.h" + line="1130">While starting a new process, something went wrong. glib:nick="spawn-setup-failed" glib:name="G_DBUS_ERROR_SPAWN_SETUP_FAILED"> We failed to setup the environment correctly. + filename="gio/gioenums.h" + line="1132">We failed to setup the environment correctly. glib:nick="spawn-config-invalid" glib:name="G_DBUS_ERROR_SPAWN_CONFIG_INVALID"> We failed to setup the config parser correctly. + filename="gio/gioenums.h" + line="1134">We failed to setup the config parser correctly. glib:nick="spawn-service-invalid" glib:name="G_DBUS_ERROR_SPAWN_SERVICE_INVALID"> Bus name was not valid. + filename="gio/gioenums.h" + line="1136">Bus name was not valid. glib:nick="spawn-service-not-found" glib:name="G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND"> Service file not found in system-services directory. + filename="gio/gioenums.h" + line="1138">Service file not found in system-services directory. glib:nick="spawn-permissions-invalid" glib:name="G_DBUS_ERROR_SPAWN_PERMISSIONS_INVALID"> Permissions are incorrect on the setuid helper. + filename="gio/gioenums.h" + line="1140">Permissions are incorrect on the setuid helper. glib:nick="spawn-file-invalid" glib:name="G_DBUS_ERROR_SPAWN_FILE_INVALID"> Service file invalid (Name, User or Exec missing). + filename="gio/gioenums.h" + line="1142">Service file invalid (Name, User or Exec missing). glib:nick="spawn-no-memory" glib:name="G_DBUS_ERROR_SPAWN_NO_MEMORY"> Tried to get a UNIX process ID and it wasn't available. + filename="gio/gioenums.h" + line="1144">Tried to get a UNIX process ID and it wasn't available. glib:nick="unix-process-id-unknown" glib:name="G_DBUS_ERROR_UNIX_PROCESS_ID_UNKNOWN"> Tried to get a UNIX process ID and it wasn't available. + filename="gio/gioenums.h" + line="1146">Tried to get a UNIX process ID and it wasn't available. glib:nick="invalid-signature" glib:name="G_DBUS_ERROR_INVALID_SIGNATURE"> A type signature is not valid. + filename="gio/gioenums.h" + line="1148">A type signature is not valid. glib:nick="invalid-file-content" glib:name="G_DBUS_ERROR_INVALID_FILE_CONTENT"> A file contains invalid syntax or is otherwise broken. + filename="gio/gioenums.h" + line="1150">A file contains invalid syntax or is otherwise broken. glib:nick="selinux-security-context-unknown" glib:name="G_DBUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN"> Asked for SELinux security context and it wasn't available. + filename="gio/gioenums.h" + line="1152">Asked for SELinux security context and it wasn't available. glib:nick="adt-audit-data-unknown" glib:name="G_DBUS_ERROR_ADT_AUDIT_DATA_UNKNOWN"> Asked for ADT audit data and it wasn't available. + filename="gio/gioenums.h" + line="1154">Asked for ADT audit data and it wasn't available. glib:nick="object-path-in-use" glib:name="G_DBUS_ERROR_OBJECT_PATH_IN_USE"> There's already an object with the requested object path. + filename="gio/gioenums.h" + line="1156">There's already an object with the requested object path. glib:nick="unknown-object" glib:name="G_DBUS_ERROR_UNKNOWN_OBJECT"> Object you invoked a method on isn't known. Since 2.42 + filename="gio/gioenums.h" + line="1106">Object you invoked a method on isn't known. Since 2.42 glib:nick="unknown-interface" glib:name="G_DBUS_ERROR_UNKNOWN_INTERFACE"> Interface you invoked a method on isn't known by the object. Since 2.42 + filename="gio/gioenums.h" + line="1108">Interface you invoked a method on isn't known by the object. Since 2.42 glib:nick="unknown-property" glib:name="G_DBUS_ERROR_UNKNOWN_PROPERTY"> Property you tried to access isn't known by the object. Since 2.42 + filename="gio/gioenums.h" + line="1110">Property you tried to access isn't known by the object. Since 2.42 glib:nick="property-read-only" glib:name="G_DBUS_ERROR_PROPERTY_READ_ONLY"> Property you tried to set is read-only. Since 2.42 + filename="gio/gioenums.h" + line="1112">Property you tried to set is read-only. Since 2.42 Creates a D-Bus error name to use for @error. If @error matches + filename="gio/gdbuserror.c" + line="723">Creates a D-Bus error name to use for @error. If @error matches a registered error (cf. g_dbus_error_register_error()), the corresponding D-Bus error name will be returned. @@ -19228,19 +20162,19 @@ on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). This function is typically only used in object mappings to put a #GError on the wire. Regular applications should not use it. - + A D-Bus error name (never %NULL). + filename="gio/gdbuserror.c" + line="739">A D-Bus error name (never %NULL). Free with g_free(). A #GError. + filename="gio/gdbuserror.c" + line="725">A #GError. @@ -19249,26 +20183,26 @@ This function is typically only used in object mappings to put a c:identifier="g_dbus_error_get_remote_error" version="2.26"> Gets the D-Bus error name used for @error, if any. + filename="gio/gdbuserror.c" + line="430">Gets the D-Bus error name used for @error, if any. This function is guaranteed to return a D-Bus error name for all #GErrors returned from functions handling remote method calls (e.g. g_dbus_connection_call_finish()) unless g_dbus_error_strip_remote_error() has been used on @error. - + an allocated string or %NULL if the + filename="gio/gdbuserror.c" + line="441">an allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). a #GError + filename="gio/gdbuserror.c" + line="432">a #GError @@ -19277,22 +20211,22 @@ g_dbus_error_strip_remote_error() has been used on @error. c:identifier="g_dbus_error_is_remote_error" version="2.26"> Checks if @error represents an error received via D-Bus from a remote peer. If so, + filename="gio/gdbuserror.c" + line="410">Checks if @error represents an error received via D-Bus from a remote peer. If so, use g_dbus_error_get_remote_error() to get the name of the error. - + %TRUE if @error represents an error from a remote peer, + filename="gio/gdbuserror.c" + line="417">%TRUE if @error represents an error from a remote peer, %FALSE otherwise. A #GError. + filename="gio/gdbuserror.c" + line="412">A #GError. @@ -19301,8 +20235,8 @@ use g_dbus_error_get_remote_error() to get the name of the error. c:identifier="g_dbus_error_new_for_dbus_error" version="2.26"> Creates a #GError based on the contents of @dbus_error_name and + filename="gio/gdbuserror.c" + line="497">Creates a #GError based on the contents of @dbus_error_name and @dbus_error_message. Errors registered with g_dbus_error_register_error() will be looked @@ -19328,24 +20262,24 @@ returned #GError using the g_dbus_error_get_remote_error() function This function is typically only used in object mappings to prepare #GError instances for applications. Regular applications should not use it. - + An allocated #GError. Free with g_error_free(). + filename="gio/gdbuserror.c" + line="529">An allocated #GError. Free with g_error_free(). D-Bus error name. + filename="gio/gdbuserror.c" + line="499">D-Bus error name. D-Bus error message. + filename="gio/gdbuserror.c" + line="500">D-Bus error message. @@ -19359,37 +20293,37 @@ it. c:identifier="g_dbus_error_register_error" version="2.26"> Creates an association to map between @dbus_error_name and + filename="gio/gdbuserror.c" + line="271">Creates an association to map between @dbus_error_name and #GErrors specified by @error_domain and @error_code. This is typically done in the routine that returns the #GQuark for an error domain. - + %TRUE if the association was created, %FALSE if it already + filename="gio/gdbuserror.c" + line="283">%TRUE if the association was created, %FALSE if it already exists. A #GQuark for an error domain. + filename="gio/gdbuserror.c" + line="273">A #GQuark for an error domain. An error code. + filename="gio/gdbuserror.c" + line="274">An error code. A D-Bus error name. + filename="gio/gdbuserror.c" + line="275">A D-Bus error name. @@ -19398,32 +20332,32 @@ exists. c:identifier="g_dbus_error_register_error_domain" version="2.26"> Helper function for associating a #GError error domain with D-Bus error names. + filename="gio/gdbuserror.c" + line="97">Helper function for associating a #GError error domain with D-Bus error names. While @quark_volatile has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + The error domain name. + filename="gio/gdbuserror.c" + line="99">The error domain name. A pointer where to store the #GQuark. + filename="gio/gdbuserror.c" + line="100">A pointer where to store the #GQuark. A pointer to @num_entries #GDBusErrorEntry struct items. + filename="gio/gdbuserror.c" + line="101">A pointer to @num_entries #GDBusErrorEntry struct items. @@ -19432,8 +20366,8 @@ artifact and the argument passed to it should not be `volatile`. Number of items to register. + filename="gio/gdbuserror.c" + line="102">Number of items to register. @@ -19443,31 +20377,31 @@ artifact and the argument passed to it should not be `volatile`. version="2.26" introspectable="0"> Does nothing if @error is %NULL. Otherwise sets *@error to + filename="gio/gdbuserror.c" + line="592">Does nothing if @error is %NULL. Otherwise sets `*error` to a new #GError created with g_dbus_error_new_for_dbus_error() with @dbus_error_message prepend with @format (unless %NULL). - + A pointer to a #GError or %NULL. + filename="gio/gdbuserror.c" + line="594">A pointer to a #GError or %NULL. D-Bus error name. + filename="gio/gdbuserror.c" + line="595">D-Bus error name. D-Bus error message. + filename="gio/gdbuserror.c" + line="596">D-Bus error message. nullable="1" allow-none="1"> printf()-style format to prepend to @dbus_error_message or %NULL. + filename="gio/gdbuserror.c" + line="597">printf()-style format to prepend to @dbus_error_message or %NULL. Arguments for @format. + filename="gio/gdbuserror.c" + line="598">Arguments for @format. @@ -19492,29 +20426,29 @@ with @dbus_error_message prepend with @format (unless %NULL). version="2.26" introspectable="0"> Like g_dbus_error_set_dbus_error() but intended for language bindings. - + filename="gio/gdbuserror.c" + line="637">Like g_dbus_error_set_dbus_error() but intended for language bindings. + A pointer to a #GError or %NULL. + filename="gio/gdbuserror.c" + line="639">A pointer to a #GError or %NULL. D-Bus error name. + filename="gio/gdbuserror.c" + line="640">D-Bus error name. D-Bus error message. + filename="gio/gdbuserror.c" + line="641">D-Bus error message. nullable="1" allow-none="1"> printf()-style format to prepend to @dbus_error_message or %NULL. + filename="gio/gdbuserror.c" + line="642">printf()-style format to prepend to @dbus_error_message or %NULL. Arguments for @format. + filename="gio/gdbuserror.c" + line="643">Arguments for @format. @@ -19538,25 +20472,25 @@ with @dbus_error_message prepend with @format (unless %NULL). c:identifier="g_dbus_error_strip_remote_error" version="2.26"> Looks for extra information in the error message used to recover + filename="gio/gdbuserror.c" + line="679">Looks for extra information in the error message used to recover the D-Bus error name and strips it if found. If stripped, the message field in @error will correspond exactly to what was received on the wire. This is typically used when presenting errors to the end user. - + %TRUE if information was stripped, %FALSE otherwise. + filename="gio/gdbuserror.c" + line="690">%TRUE if information was stripped, %FALSE otherwise. A #GError. + filename="gio/gdbuserror.c" + line="681">A #GError. @@ -19565,32 +20499,32 @@ This is typically used when presenting errors to the end user. c:identifier="g_dbus_error_unregister_error" version="2.26"> Destroys an association previously set up with g_dbus_error_register_error(). - + filename="gio/gdbuserror.c" + line="337">Destroys an association previously set up with g_dbus_error_register_error(). + %TRUE if the association was destroyed, %FALSE if it wasn't found. + filename="gio/gdbuserror.c" + line="345">%TRUE if the association was destroyed, %FALSE if it wasn't found. A #GQuark for an error domain. + filename="gio/gdbuserror.c" + line="339">A #GQuark for an error domain. An error code. + filename="gio/gdbuserror.c" + line="340">An error code. A D-Bus error name. + filename="gio/gdbuserror.c" + line="341">A D-Bus error name. @@ -19598,18 +20532,18 @@ This is typically used when presenting errors to the end user. Struct used in g_dbus_error_register_error_domain(). - + An error code. The D-Bus error name to associate with @error_code. @@ -19622,49 +20556,51 @@ This is typically used when presenting errors to the end user. glib:get-type="g_dbus_interface_get_type" glib:type-struct="DBusInterfaceIface"> The #GDBusInterface type is the base type for D-Bus interfaces both -on the service side (see #GDBusInterfaceSkeleton) and client side -(see #GDBusProxy). - + filename="gio/gdbusinterface.c" + line="30">Base type for D-Bus interfaces. + +The `GDBusInterface` type is the base type for D-Bus interfaces both +on the service side (see [class@Gio.DBusInterfaceSkeleton]) and client side +(see [class@Gio.DBusProxy]). + Gets the #GDBusObject that @interface_ belongs to, if any. - + filename="gio/gdbusinterface.c" + line="92">Gets the #GDBusObject that @interface_ belongs to, if any. + A #GDBusObject or %NULL. The returned + filename="gio/gdbusinterface.c" + line="98">A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="94">An exported D-Bus interface. Gets D-Bus introspection information for the D-Bus interface + filename="gio/gdbusinterface.c" + line="52">Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. - + A #GDBusInterfaceInfo. Do not free. + filename="gio/gdbusinterface.c" + line="59">A #GDBusInterfaceInfo. Do not free. An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="54">An exported D-Bus interface. @@ -19674,44 +20610,44 @@ implemented by @interface_. version="2.30" introspectable="0"> Gets the #GDBusObject that @interface_ belongs to, if any. + filename="gio/gdbusinterface.c" + line="70">Gets the #GDBusObject that @interface_ belongs to, if any. It is not safe to use the returned object if @interface_ or the returned object is being used from other threads. See g_dbus_interface_dup_object() for a thread-safe alternative. - + A #GDBusObject or %NULL. The returned + filename="gio/gdbusinterface.c" + line="80">A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. An exported D-Bus interface + filename="gio/gdbusinterface.c" + line="72">An exported D-Bus interface Sets the #GDBusObject for @interface_ to @object. + filename="gio/gdbusinterface.c" + line="123">Sets the #GDBusObject for @interface_ to @object. Note that @interface_ will hold a weak reference to @object. - + An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="125">An exported D-Bus interface. nullable="1" allow-none="1"> A #GDBusObject or %NULL. + filename="gio/gdbusinterface.c" + line="126">A #GDBusObject or %NULL. @@ -19730,21 +20666,21 @@ Note that @interface_ will hold a weak reference to @object. shadows="get_object" version="2.32"> Gets the #GDBusObject that @interface_ belongs to, if any. - + filename="gio/gdbusinterface.c" + line="92">Gets the #GDBusObject that @interface_ belongs to, if any. + A #GDBusObject or %NULL. The returned + filename="gio/gdbusinterface.c" + line="98">A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="94">An exported D-Bus interface. @@ -19753,21 +20689,21 @@ reference should be freed with g_object_unref(). c:identifier="g_dbus_interface_get_info" version="2.30"> Gets D-Bus introspection information for the D-Bus interface + filename="gio/gdbusinterface.c" + line="52">Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. - + A #GDBusInterfaceInfo. Do not free. + filename="gio/gdbusinterface.c" + line="59">A #GDBusInterfaceInfo. Do not free. An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="54">An exported D-Bus interface. @@ -19778,25 +20714,25 @@ implemented by @interface_. version="2.30" introspectable="0"> Gets the #GDBusObject that @interface_ belongs to, if any. + filename="gio/gdbusinterface.c" + line="70">Gets the #GDBusObject that @interface_ belongs to, if any. It is not safe to use the returned object if @interface_ or the returned object is being used from other threads. See g_dbus_interface_dup_object() for a thread-safe alternative. - + A #GDBusObject or %NULL. The returned + filename="gio/gdbusinterface.c" + line="80">A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. An exported D-Bus interface + filename="gio/gdbusinterface.c" + line="72">An exported D-Bus interface @@ -19805,19 +20741,19 @@ g_dbus_interface_dup_object() for a thread-safe alternative. c:identifier="g_dbus_interface_set_object" version="2.30"> Sets the #GDBusObject for @interface_ to @object. + filename="gio/gdbusinterface.c" + line="123">Sets the #GDBusObject for @interface_ to @object. Note that @interface_ will hold a weak reference to @object. - + An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="125">An exported D-Bus interface. nullable="1" allow-none="1"> A #GDBusObject or %NULL. + filename="gio/gdbusinterface.c" + line="126">A #GDBusObject or %NULL. @@ -19836,13 +20772,13 @@ Note that @interface_ will hold a weak reference to @object. c:type="GDBusInterfaceGetPropertyFunc" version="2.26"> The type of the @get_property function in #GDBusInterfaceVTable. - + filename="gio/gdbusconnection.h" + line="298">The type of the @get_property function in #GDBusInterfaceVTable. + A #GVariant with the value for @property_name or %NULL if + filename="gio/gdbusconnection.h" + line="311">A #GVariant with the value for @property_name or %NULL if @error is set. If the returned #GVariant is floating, it is consumed - otherwise its reference count is decreased by one. @@ -19850,38 +20786,42 @@ Note that @interface_ will hold a weak reference to @object. A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="300">A #GDBusConnection. - + The unique bus name of the remote caller. + filename="gio/gdbusconnection.h" + line="301">The unique bus name of the remote caller or %NULL if + not specified by the caller, e.g. on peer-to-peer connections. The object path that the method was invoked on. + filename="gio/gdbusconnection.h" + line="303">The object path that the method was invoked on. The D-Bus interface name for the property. + filename="gio/gdbusconnection.h" + line="304">The D-Bus interface name for the property. The name of the property to get the value of. + filename="gio/gdbusconnection.h" + line="305">The name of the property to get the value of. Return location for error. + filename="gio/gdbusconnection.h" + line="306">Return location for error. allow-none="1" closure="6"> The @user_data #gpointer passed to g_dbus_connection_register_object(). + filename="gio/gdbusconnection.h" + line="307">The @user_data #gpointer passed to g_dbus_connection_register_object(). @@ -19901,65 +20841,74 @@ Note that @interface_ will hold a weak reference to @object. glib:is-gtype-struct-for="DBusInterface" version="2.30"> Base type for D-Bus interfaces. - + filename="gio/gdbusinterface.h" + line="37">Base type for D-Bus interfaces. + The parent interface. + filename="gio/gdbusinterface.h" + line="39">The parent interface. + Returns a #GDBusInterfaceInfo. See g_dbus_interface_get_info(). - + A #GDBusInterfaceInfo. Do not free. + filename="gio/gdbusinterface.c" + line="59">A #GDBusInterfaceInfo. Do not free. An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="54">An exported D-Bus interface. + Gets the enclosing #GDBusObject. See g_dbus_interface_get_object(). - + A #GDBusObject or %NULL. The returned + filename="gio/gdbusinterface.c" + line="80">A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. An exported D-Bus interface + filename="gio/gdbusinterface.c" + line="72">An exported D-Bus interface + Sets the enclosing #GDBusObject. See g_dbus_interface_set_object(). - + An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="125">An exported D-Bus interface. nullable="1" allow-none="1"> A #GDBusObject or %NULL. + filename="gio/gdbusinterface.c" + line="126">A #GDBusObject or %NULL. + Gets a reference to the enclosing #GDBusObject. See g_dbus_interface_dup_object(). Added in 2.32. - + A #GDBusObject or %NULL. The returned + filename="gio/gdbusinterface.c" + line="98">A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). An exported D-Bus interface. + filename="gio/gdbusinterface.c" + line="94">An exported D-Bus interface. @@ -20002,24 +20954,24 @@ reference should be freed with g_object_unref(). glib:get-type="g_dbus_interface_info_get_type" c:symbol-prefix="dbus_interface_info"> Information about a D-Bus interface. - + The reference count or -1 if statically allocated. The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties". A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods. @@ -20027,7 +20979,7 @@ reference should be freed with g_object_unref(). A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals. @@ -20035,7 +20987,7 @@ reference should be freed with g_object_unref(). A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties. @@ -20043,7 +20995,7 @@ reference should be freed with g_object_unref(). A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -20053,8 +21005,8 @@ reference should be freed with g_object_unref(). c:identifier="g_dbus_interface_info_cache_build" version="2.30"> Builds a lookup-cache to speed up + filename="gio/gdbusintrospection.c" + line="2058">Builds a lookup-cache to speed up g_dbus_interface_info_lookup_method(), g_dbus_interface_info_lookup_signal() and g_dbus_interface_info_lookup_property(). @@ -20064,15 +21016,15 @@ used and its use count is increased. Note that @info cannot be modified until g_dbus_interface_info_cache_release() is called. - + A #GDBusInterfaceInfo. + filename="gio/gdbusintrospection.c" + line="2060">A #GDBusInterfaceInfo. @@ -20081,19 +21033,19 @@ g_dbus_interface_info_cache_release() is called. c:identifier="g_dbus_interface_info_cache_release" version="2.30"> Decrements the usage count for the cache for @info built by + filename="gio/gdbusintrospection.c" + line="2106">Decrements the usage count for the cache for @info built by g_dbus_interface_info_cache_build() (if any) and frees the resources used by the cache if the usage count drops to zero. - + A GDBusInterfaceInfo + filename="gio/gdbusintrospection.c" + line="2108">A GDBusInterfaceInfo @@ -20102,34 +21054,34 @@ resources used by the cache if the usage count drops to zero. c:identifier="g_dbus_interface_info_generate_xml" version="2.26"> Appends an XML representation of @info (and its children) to @string_builder. + filename="gio/gdbusintrospection.c" + line="763">Appends an XML representation of @info (and its children) to @string_builder. This function is typically used for generating introspection XML documents at run-time for handling the `org.freedesktop.DBus.Introspectable.Introspect` method. - + A #GDBusNodeInfo + filename="gio/gdbusintrospection.c" + line="765">A #GDBusNodeInfo Indentation level. + filename="gio/gdbusintrospection.c" + line="766">Indentation level. A #GString to to append XML data to. + filename="gio/gdbusintrospection.c" + line="767">A #GString to to append XML data to. @@ -20138,29 +21090,29 @@ method. c:identifier="g_dbus_interface_info_lookup_method" version="2.26"> Looks up information about a method. + filename="gio/gdbusintrospection.c" + line="1896">Looks up information about a method. The cost of this function is O(n) in number of methods unless g_dbus_interface_info_cache_build() has been used on @info. - + A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. + filename="gio/gdbusintrospection.c" + line="1906">A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusInterfaceInfo. + filename="gio/gdbusintrospection.c" + line="1898">A #GDBusInterfaceInfo. A D-Bus method name (typically in CamelCase) + filename="gio/gdbusintrospection.c" + line="1899">A D-Bus method name (typically in CamelCase) @@ -20169,29 +21121,29 @@ g_dbus_interface_info_cache_build() has been used on @info. c:identifier="g_dbus_interface_info_lookup_property" version="2.26"> Looks up information about a property. + filename="gio/gdbusintrospection.c" + line="2004">Looks up information about a property. The cost of this function is O(n) in number of properties unless g_dbus_interface_info_cache_build() has been used on @info. - + A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. + filename="gio/gdbusintrospection.c" + line="2014">A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusInterfaceInfo. + filename="gio/gdbusintrospection.c" + line="2006">A #GDBusInterfaceInfo. A D-Bus property name (typically in CamelCase). + filename="gio/gdbusintrospection.c" + line="2007">A D-Bus property name (typically in CamelCase). @@ -20200,29 +21152,29 @@ g_dbus_interface_info_cache_build() has been used on @info. c:identifier="g_dbus_interface_info_lookup_signal" version="2.26"> Looks up information about a signal. + filename="gio/gdbusintrospection.c" + line="1950">Looks up information about a signal. The cost of this function is O(n) in number of signals unless g_dbus_interface_info_cache_build() has been used on @info. - + A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. + filename="gio/gdbusintrospection.c" + line="1960">A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusInterfaceInfo. + filename="gio/gdbusintrospection.c" + line="1952">A #GDBusInterfaceInfo. A D-Bus signal name (typically in CamelCase) + filename="gio/gdbusintrospection.c" + line="1953">A D-Bus signal name (typically in CamelCase) @@ -20231,21 +21183,21 @@ g_dbus_interface_info_cache_build() has been used on @info. c:identifier="g_dbus_interface_info_ref" version="2.26"> If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="102">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="109">The same @info. A #GDBusInterfaceInfo + filename="gio/gdbusintrospection.c" + line="104">A #GDBusInterfaceInfo @@ -20254,19 +21206,19 @@ the reference count. c:identifier="g_dbus_interface_info_unref" version="2.26"> If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="357">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusInterfaceInfo. + filename="gio/gdbusintrospection.c" + line="359">A #GDBusInterfaceInfo. @@ -20276,53 +21228,68 @@ the memory used is freed. c:type="GDBusInterfaceMethodCallFunc" version="2.26"> The type of the @method_call function in #GDBusInterfaceVTable. - + filename="gio/gdbusconnection.h" + line="265">The type of the @method_call function in #GDBusInterfaceVTable. + +@interface_name may be `NULL` if not specified by the sender, although it’s +encouraged for the sender to set it. If unset, and the object has only one +method (across all interfaces) matching @method_name, that method is invoked. +Otherwise, behaviour is implementation defined. See the +[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method). +It is recommended to return [error@Gio.DBusError.UNKNOWN_METHOD]. + A #GDBusConnection. - + The unique bus name of the remote caller. + filename="gio/gdbusconnection.h" + line="268">The unique bus name of the remote caller, or `NULL` if + not specified by the caller, e.g. on peer-to-peer connections. The object path that the method was invoked on. + filename="gio/gdbusconnection.h" + line="270">The object path that the method was invoked on. - + The D-Bus interface name the method was invoked on. + filename="gio/gdbusconnection.h" + line="271">The D-Bus interface name the method was invoked on, + or `NULL` if not specified by the sender. The name of the method that was invoked. + filename="gio/gdbusconnection.h" + line="273">The name of the method that was invoked. A #GVariant tuple with parameters. + filename="gio/gdbusconnection.h" + line="274">A #GVariant tuple with parameters. A #GDBusMethodInvocation object that must be used to return a value or error. + filename="gio/gdbusconnection.h" + line="275">A #GDBusMethodInvocation object that must be used to return a value or error. allow-none="1" closure="7"> The @user_data #gpointer passed to g_dbus_connection_register_object(). + filename="gio/gdbusconnection.h" + line="276">The @user_data #gpointer passed to g_dbus_connection_register_object(). @@ -20341,56 +21308,60 @@ the memory used is freed. c:type="GDBusInterfaceSetPropertyFunc" version="2.26"> The type of the @set_property function in #GDBusInterfaceVTable. - + filename="gio/gdbusconnection.h" + line="325">The type of the @set_property function in #GDBusInterfaceVTable. + %TRUE if the property was set to @value, %FALSE if @error is set. + filename="gio/gdbusconnection.h" + line="339">%TRUE if the property was set to @value, %FALSE if @error is set. A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="327">A #GDBusConnection. - + The unique bus name of the remote caller. + filename="gio/gdbusconnection.h" + line="328">The unique bus name of the remote caller or %NULL if + not specified by the caller, e.g. on peer-to-peer connections. The object path that the method was invoked on. + filename="gio/gdbusconnection.h" + line="330">The object path that the method was invoked on. The D-Bus interface name for the property. + filename="gio/gdbusconnection.h" + line="331">The D-Bus interface name for the property. The name of the property to get the value of. + filename="gio/gdbusconnection.h" + line="332">The name of the property to get the value of. The value to set the property to. + filename="gio/gdbusconnection.h" + line="333">The value to set the property to. Return location for error. + filename="gio/gdbusconnection.h" + line="334">Return location for error. allow-none="1" closure="7"> The @user_data #gpointer passed to g_dbus_connection_register_object(). + filename="gio/gdbusconnection.h" + line="335">The @user_data #gpointer passed to g_dbus_connection_register_object(). @@ -20415,14 +21386,14 @@ the memory used is freed. glib:get-type="g_dbus_interface_skeleton_get_type" glib:type-struct="DBusInterfaceSkeletonClass"> Abstract base class for D-Bus interfaces on the service side. - + filename="gio/gdbusinterfaceskeleton.c" + line="38">Abstract base class for D-Bus interfaces on the service side. + If @interface_ has outstanding changes, request for these changes to be + filename="gio/gdbusinterfaceskeleton.c" + line="379">If @interface_ has outstanding changes, request for these changes to be emitted immediately. For example, an exported D-Bus interface may queue up property @@ -20430,22 +21401,25 @@ changes and emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal later (e.g. in an idle handler). This technique is useful for collapsing multiple property changes into one. - + A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="381">A #GDBusInterfaceSkeleton. - + Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal. + @@ -20461,21 +21435,21 @@ for collapsing multiple property changes into one. Gets D-Bus introspection information for the D-Bus interface + filename="gio/gdbusinterfaceskeleton.c" + line="315">Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. - + A #GDBusInterfaceInfo (never %NULL). Do not free. + filename="gio/gdbusinterfaceskeleton.c" + line="322">A #GDBusInterfaceInfo (never %NULL). Do not free. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="317">A #GDBusInterfaceSkeleton. @@ -20485,22 +21459,22 @@ implemented by @interface_. invoker="get_properties" version="2.30"> Gets all D-Bus properties for @interface_. - + filename="gio/gdbusinterfaceskeleton.c" + line="358">Gets all D-Bus properties for @interface_. + A #GVariant of type -['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + filename="gio/gdbusinterfaceskeleton.c" + line="364">A #GVariant of type +['a{sv}'](../glib/gvariant-text-format.html#dictionaries-and-dictionary-entries). Free with g_variant_unref(). A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="360">A #GDBusInterfaceSkeleton. @@ -20508,22 +21482,22 @@ Free with g_variant_unref(). Gets the interface vtable for the D-Bus interface implemented by + filename="gio/gdbusinterfaceskeleton.c" + line="336">Gets the interface vtable for the D-Bus interface implemented by @interface_. The returned function pointers should expect @interface_ itself to be passed as @user_data. - + the vtable of the D-Bus interface implemented by the skeleton + filename="gio/gdbusinterfaceskeleton.c" + line="344">the vtable of the D-Bus interface implemented by the skeleton A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="338">A #GDBusInterfaceSkeleton. @@ -20534,40 +21508,40 @@ itself to be passed as @user_data. version="2.30" throws="1"> Exports @interface_ at @object_path on @connection. + filename="gio/gdbusinterfaceskeleton.c" + line="899">Exports @interface_ at @object_path on @connection. This can be called multiple times to export the same @interface_ onto multiple connections however the @object_path provided must be the same for all connections. Use g_dbus_interface_skeleton_unexport() to unexport the object. - + %TRUE if the interface was exported on @connection, otherwise %FALSE with + filename="gio/gdbusinterfaceskeleton.c" + line="914">%TRUE if the interface was exported on @connection, otherwise %FALSE with @error set. The D-Bus interface to export. + filename="gio/gdbusinterfaceskeleton.c" + line="901">The D-Bus interface to export. A #GDBusConnection to export @interface_ on. + filename="gio/gdbusinterfaceskeleton.c" + line="902">A #GDBusConnection to export @interface_ on. The path to export the interface at. + filename="gio/gdbusinterfaceskeleton.c" + line="903">The path to export the interface at. @@ -20576,8 +21550,8 @@ Use g_dbus_interface_skeleton_unexport() to unexport the object. c:identifier="g_dbus_interface_skeleton_flush" version="2.30"> If @interface_ has outstanding changes, request for these changes to be + filename="gio/gdbusinterfaceskeleton.c" + line="379">If @interface_ has outstanding changes, request for these changes to be emitted immediately. For example, an exported D-Bus interface may queue up property @@ -20585,15 +21559,15 @@ changes and emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal later (e.g. in an idle handler). This technique is useful for collapsing multiple property changes into one. - + A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="381">A #GDBusInterfaceSkeleton. @@ -20603,21 +21577,21 @@ for collapsing multiple property changes into one. c:identifier="g_dbus_interface_skeleton_get_connection" version="2.30"> Gets the first connection that @interface_ is exported on, if any. - + filename="gio/gdbusinterfaceskeleton.c" + line="768">Gets the first connection that @interface_ is exported on, if any. + A #GDBusConnection or %NULL if @interface_ is + filename="gio/gdbusinterfaceskeleton.c" + line="774">A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="770">A #GDBusInterfaceSkeleton. @@ -20627,13 +21601,13 @@ not exported anywhere. Do not free, the object belongs to @interface_. c:identifier="g_dbus_interface_skeleton_get_connections" version="2.32"> Gets a list of the connections that @interface_ is exported on. - + filename="gio/gdbusinterfaceskeleton.c" + line="801">Gets a list of the connections that @interface_ is exported on. + A list of + filename="gio/gdbusinterfaceskeleton.c" + line="807">A list of all the connections that @interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). @@ -20644,8 +21618,8 @@ not exported anywhere. Do not free, the object belongs to @interface_. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="803">A #GDBusInterfaceSkeleton. @@ -20655,22 +21629,22 @@ not exported anywhere. Do not free, the object belongs to @interface_. c:identifier="g_dbus_interface_skeleton_get_flags" version="2.30"> Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior + filename="gio/gdbusinterfaceskeleton.c" + line="270">Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior of @interface_ - + One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. + filename="gio/gdbusinterfaceskeleton.c" + line="277">One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="272">A #GDBusInterfaceSkeleton. @@ -20680,21 +21654,21 @@ of @interface_ c:identifier="g_dbus_interface_skeleton_get_info" version="2.30"> Gets D-Bus introspection information for the D-Bus interface + filename="gio/gdbusinterfaceskeleton.c" + line="315">Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. - + A #GDBusInterfaceInfo (never %NULL). Do not free. + filename="gio/gdbusinterfaceskeleton.c" + line="322">A #GDBusInterfaceInfo (never %NULL). Do not free. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="317">A #GDBusInterfaceSkeleton. @@ -20704,21 +21678,21 @@ implemented by @interface_. c:identifier="g_dbus_interface_skeleton_get_object_path" version="2.30"> Gets the object path that @interface_ is exported on, if any. - + filename="gio/gdbusinterfaceskeleton.c" + line="877">Gets the object path that @interface_ is exported on, if any. + A string owned by @interface_ or %NULL if @interface_ is not exported + filename="gio/gdbusinterfaceskeleton.c" + line="883">A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="879">A #GDBusInterfaceSkeleton. @@ -20728,22 +21702,22 @@ anywhere. Do not free, the string belongs to @interface_. c:identifier="g_dbus_interface_skeleton_get_properties" version="2.30"> Gets all D-Bus properties for @interface_. - + filename="gio/gdbusinterfaceskeleton.c" + line="358">Gets all D-Bus properties for @interface_. + A #GVariant of type -['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + filename="gio/gdbusinterfaceskeleton.c" + line="364">A #GVariant of type +['a{sv}'](../glib/gvariant-text-format.html#dictionaries-and-dictionary-entries). Free with g_variant_unref(). A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="360">A #GDBusInterfaceSkeleton. @@ -20753,22 +21727,22 @@ Free with g_variant_unref(). c:identifier="g_dbus_interface_skeleton_get_vtable" version="2.30"> Gets the interface vtable for the D-Bus interface implemented by + filename="gio/gdbusinterfaceskeleton.c" + line="336">Gets the interface vtable for the D-Bus interface implemented by @interface_. The returned function pointers should expect @interface_ itself to be passed as @user_data. - + the vtable of the D-Bus interface implemented by the skeleton + filename="gio/gdbusinterfaceskeleton.c" + line="344">the vtable of the D-Bus interface implemented by the skeleton A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="338">A #GDBusInterfaceSkeleton. @@ -20778,27 +21752,27 @@ itself to be passed as @user_data. c:identifier="g_dbus_interface_skeleton_has_connection" version="2.32"> Checks if @interface_ is exported on @connection. - + filename="gio/gdbusinterfaceskeleton.c" + line="839">Checks if @interface_ is exported on @connection. + %TRUE if @interface_ is exported on @connection, %FALSE otherwise. + filename="gio/gdbusinterfaceskeleton.c" + line="846">%TRUE if @interface_ is exported on @connection, %FALSE otherwise. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="841">A #GDBusInterfaceSkeleton. A #GDBusConnection. + filename="gio/gdbusinterfaceskeleton.c" + line="842">A #GDBusConnection. @@ -20807,24 +21781,24 @@ itself to be passed as @user_data. c:identifier="g_dbus_interface_skeleton_set_flags" version="2.30"> Sets flags describing what the behavior of @skeleton should be. - + filename="gio/gdbusinterfaceskeleton.c" + line="288">Sets flags describing what the behavior of @skeleton should be. + A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="290">A #GDBusInterfaceSkeleton. Flags from the #GDBusInterfaceSkeletonFlags enumeration. + filename="gio/gdbusinterfaceskeleton.c" + line="291">Flags from the #GDBusInterfaceSkeletonFlags enumeration. @@ -20834,20 +21808,20 @@ itself to be passed as @user_data. c:identifier="g_dbus_interface_skeleton_unexport" version="2.30"> Stops exporting @interface_ on all connections it is exported on. + filename="gio/gdbusinterfaceskeleton.c" + line="948">Stops exporting @interface_ on all connections it is exported on. To unexport @interface_ from only a single connection, use g_dbus_interface_skeleton_unexport_from_connection() - + A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="950">A #GDBusInterfaceSkeleton. @@ -20857,27 +21831,27 @@ g_dbus_interface_skeleton_unexport_from_connection() c:identifier="g_dbus_interface_skeleton_unexport_from_connection" version="2.32"> Stops exporting @interface_ on @connection. + filename="gio/gdbusinterfaceskeleton.c" + line="984">Stops exporting @interface_ on @connection. To stop exporting on all connections the interface is exported on, use g_dbus_interface_skeleton_unexport(). - + A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="986">A #GDBusInterfaceSkeleton. A #GDBusConnection. + filename="gio/gdbusinterfaceskeleton.c" + line="987">A #GDBusConnection. @@ -20888,8 +21862,8 @@ use g_dbus_interface_skeleton_unexport(). transfer-ownership="none" default-value="G_DBUS_INTERFACE_SKELETON_FLAGS_NONE"> Flags from the #GDBusInterfaceSkeletonFlags enumeration. + filename="gio/gdbusinterfaceskeleton.c" + line="186">Flags from the #GDBusInterfaceSkeletonFlags enumeration. @@ -20901,8 +21875,8 @@ use g_dbus_interface_skeleton_unexport(). Emitted when a method is invoked by a remote caller and used to + filename="gio/gdbusinterfaceskeleton.c" + line="202">Emitted when a method is invoked by a remote caller and used to determine if the method call is authorized. Note that this signal is emitted in a thread dedicated to @@ -20937,15 +21911,15 @@ handled in the same thread as the object that @interface belongs to was exported in. %TRUE if the call is authorized, %FALSE otherwise. + filename="gio/gdbusinterfaceskeleton.c" + line="241">%TRUE if the call is authorized, %FALSE otherwise. A #GDBusMethodInvocation. + filename="gio/gdbusinterfaceskeleton.c" + line="205">A #GDBusMethodInvocation. @@ -20956,29 +21930,32 @@ to was exported in. glib:is-gtype-struct-for="DBusInterfaceSkeleton" version="2.30"> Class structure for #GDBusInterfaceSkeleton. - + filename="gio/gdbusinterfaceskeleton.h" + line="47">Class structure for #GDBusInterfaceSkeleton. + The parent class. + filename="gio/gdbusinterfaceskeleton.h" + line="49">The parent class. + Returns a #GDBusInterfaceInfo. See g_dbus_interface_skeleton_get_info() for details. - + A #GDBusInterfaceInfo (never %NULL). Do not free. + filename="gio/gdbusinterfaceskeleton.c" + line="322">A #GDBusInterfaceInfo (never %NULL). Do not free. A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="317">A #GDBusInterfaceSkeleton. @@ -20986,19 +21963,22 @@ to was exported in. + Returns a #GDBusInterfaceVTable. See g_dbus_interface_skeleton_get_vtable() for details. - + the vtable of the D-Bus interface implemented by the skeleton + filename="gio/gdbusinterfaceskeleton.c" + line="344">the vtable of the D-Bus interface implemented by the skeleton A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="338">A #GDBusInterfaceSkeleton. @@ -21006,21 +21986,24 @@ to was exported in. + Returns a #GVariant with all properties. See g_dbus_interface_skeleton_get_properties(). - + A #GVariant of type -['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + filename="gio/gdbusinterfaceskeleton.c" + line="364">A #GVariant of type +['a{sv}'](../glib/gvariant-text-format.html#dictionaries-and-dictionary-entries). Free with g_variant_unref(). A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="360">A #GDBusInterfaceSkeleton. @@ -21028,16 +22011,19 @@ Free with g_variant_unref(). + Emits outstanding changes, if any. See g_dbus_interface_skeleton_flush(). - + A #GDBusInterfaceSkeleton. + filename="gio/gdbusinterfaceskeleton.c" + line="381">A #GDBusInterfaceSkeleton. @@ -21050,8 +22036,11 @@ Free with g_variant_unref(). + Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal. - + @@ -21079,16 +22068,16 @@ Free with g_variant_unref(). glib:get-type="g_dbus_interface_skeleton_flags_get_type" c:type="GDBusInterfaceSkeletonFlags"> Flags describing the behavior of a #GDBusInterfaceSkeleton instance. + filename="gio/gioenums.h" + line="1804">Flags describing the behavior of a #GDBusInterfaceSkeleton instance. No flags set. + filename="gio/gioenums.h" + line="1806">No flags set. glib:nick="handle-method-invocations-in-thread" glib:name="G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD"> Each method invocation is handled in + filename="gio/gioenums.h" + line="1807">Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must use locking to access data structures used by other threads. @@ -21107,14 +22096,14 @@ Free with g_variant_unref(). c:type="GDBusInterfaceSkeletonPrivate" disguised="1" opaque="1"> - + Virtual table for handling properties and method calls for a D-Bus + filename="gio/gdbusconnection.h" + line="352">Virtual table for handling properties and method calls for a D-Bus interface. Since 2.38, if you want to handle getting/setting D-Bus properties @@ -21155,25 +22144,25 @@ If you have writable properties specified in your interface info, you must ensure that you either provide a non-%NULL @set_property() function or provide an implementation of the `Set` call. If implementing the call, you must return the value of type %G_VARIANT_TYPE_UNIT. - + Function for handling incoming method calls. + filename="gio/gdbusconnection.h" + line="354">Function for handling incoming method calls. Function for getting a property. + filename="gio/gdbusconnection.h" + line="355">Function for getting a property. Function for setting a property. + filename="gio/gdbusconnection.h" + line="356">Function for setting a property. @@ -21190,14 +22179,14 @@ the call, you must return the value of type %G_VARIANT_TYPE_UNIT. glib:type-name="GDBusMenuModel" glib:get-type="g_dbus_menu_model_get_type"> #GDBusMenuModel is an implementation of #GMenuModel that can be used -as a proxy for a menu model that is exported over D-Bus with -g_dbus_connection_export_menu_model(). + filename="gio/gdbusmenumodel.c" + line="31">`GDBusMenuModel` is an implementation of [class@Gio.MenuModel] that can be +used as a proxy for a menu model that is exported over D-Bus with +[method@Gio.DBusConnection.export_menu_model]. Obtains a #GDBusMenuModel for the menu model which is exported + filename="gio/gdbusmenumodel.c" + line="873">Obtains a #GDBusMenuModel for the menu model which is exported at the given @bus_name and @object_path. The thread default main context is taken at the time of this call. @@ -21205,19 +22194,19 @@ All signals on the menu model (and any linked models) are reported with respect to this context. All calls on the returned menu model (and linked models) must also originate from this same context, with the thread default main context unchanged. - + a #GDBusMenuModel object. Free with + filename="gio/gdbusmenumodel.c" + line="889">a #GDBusMenuModel object. Free with g_object_unref(). a #GDBusConnection + filename="gio/gdbusmenumodel.c" + line="875">a #GDBusConnection nullable="1" allow-none="1"> the bus name which exports the menu model + filename="gio/gdbusmenumodel.c" + line="876">the bus name which exports the menu model or %NULL if @connection is not a message bus connection the object path at which the menu model is exported + filename="gio/gdbusmenumodel.c" + line="878">the object path at which the menu model is exported @@ -21247,18 +22236,18 @@ the thread default main context unchanged. glib:type-name="GDBusMessage" glib:get-type="g_dbus_message_get_type"> A type for representing D-Bus messages that can be sent or received -on a #GDBusConnection. + filename="gio/gdbusmessage.c" + line="480">A type for representing D-Bus messages that can be sent or received +on a [class@Gio.DBusConnection]. Creates a new empty #GDBusMessage. - + filename="gio/gdbusmessage.c" + line="601">Creates a new empty #GDBusMessage. + A #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="606">A #GDBusMessage. Free with g_object_unref(). @@ -21267,40 +22256,40 @@ on a #GDBusConnection. version="2.26" throws="1"> Creates a new #GDBusMessage from the data stored at @blob. The byte + filename="gio/gdbusmessage.c" + line="2324">Creates a new #GDBusMessage from the data stored at @blob. The byte order that the message was in can be retrieved using g_dbus_message_get_byte_order(). If the @blob cannot be parsed, contains invalid fields, or contains invalid headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. - + A new #GDBusMessage or %NULL if @error is set. Free with + filename="gio/gdbusmessage.c" + line="2338">A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). A blob representing a binary D-Bus message. + filename="gio/gdbusmessage.c" + line="2326">A blob representing a binary D-Bus message. The length of @blob. + filename="gio/gdbusmessage.c" + line="2327">The length of @blob. A #GDBusCapabilityFlags describing what protocol features are supported. + filename="gio/gdbusmessage.c" + line="2328">A #GDBusCapabilityFlags describing what protocol features are supported. @@ -21309,13 +22298,13 @@ g_object_unref(). c:identifier="g_dbus_message_new_method_call" version="2.26"> Creates a new #GDBusMessage for a method call. - + filename="gio/gdbusmessage.c" + line="616">Creates a new #GDBusMessage for a method call. + A #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="625">A #GDBusMessage. Free with g_object_unref(). @@ -21324,14 +22313,14 @@ g_object_unref(). nullable="1" allow-none="1"> A valid D-Bus name or %NULL. + filename="gio/gdbusmessage.c" + line="618">A valid D-Bus name or %NULL. A valid object path. + filename="gio/gdbusmessage.c" + line="619">A valid object path. nullable="1" allow-none="1"> A valid D-Bus interface name or %NULL. + filename="gio/gdbusmessage.c" + line="620">A valid D-Bus interface name or %NULL. A valid method name. + filename="gio/gdbusmessage.c" + line="621">A valid method name. @@ -21355,32 +22344,32 @@ g_object_unref(). c:identifier="g_dbus_message_new_signal" version="2.26"> Creates a new #GDBusMessage for a signal emission. - + filename="gio/gdbusmessage.c" + line="655">Creates a new #GDBusMessage for a signal emission. + A #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="663">A #GDBusMessage. Free with g_object_unref(). A valid object path. + filename="gio/gdbusmessage.c" + line="657">A valid object path. A valid D-Bus interface name. + filename="gio/gdbusmessage.c" + line="658">A valid D-Bus interface name. A valid signal name. + filename="gio/gdbusmessage.c" + line="659">A valid signal name. @@ -21390,14 +22379,14 @@ g_object_unref(). version="2.26" throws="1"> Utility function to calculate how many bytes are needed to + filename="gio/gdbusmessage.c" + line="2256">Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at @blob. - + Number of bytes needed or -1 if @error is set (e.g. if + filename="gio/gdbusmessage.c" + line="2265">Number of bytes needed or -1 if @error is set (e.g. if @blob contains invalid data or not enough data is available to determine the size). @@ -21405,16 +22394,16 @@ determine the size). A blob representing a binary D-Bus message. + filename="gio/gdbusmessage.c" + line="2258">A blob representing a binary D-Bus message. The length of @blob (must be at least 16). + filename="gio/gdbusmessage.c" + line="2259">The length of @blob (must be at least 16). @@ -21424,26 +22413,26 @@ determine the size). version="2.26" throws="1"> Copies @message. The copy is a deep copy and the returned + filename="gio/gdbusmessage.c" + line="3972">Copies @message. The copy is a deep copy and the returned #GDBusMessage is completely identical except that it is guaranteed to not be locked. This operation can fail if e.g. @message contains file descriptors and the per-process or system-wide open files limit is reached. - + A new #GDBusMessage or %NULL if @error is set. + filename="gio/gdbusmessage.c" + line="3984">A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3974">A #GDBusMessage. @@ -21452,21 +22441,49 @@ and the per-process or system-wide open files limit is reached. c:identifier="g_dbus_message_get_arg0" version="2.26"> Convenience to get the first item in the body of @message. - + filename="gio/gdbusmessage.c" + line="3544">Convenience to get the first item in the body of @message. + +See [method@Gio.DBusMessage.get_arg0_path] for returning object-path-typed +arg0 values. + The string item or %NULL if the first item in the body of + filename="gio/gdbusmessage.c" + line="3553">The string item or %NULL if the first item in the body of @message is not a string. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3546">A #GDBusMessage. + + + + + + Convenience to get the first item in the body of @message. + +See [method@Gio.DBusMessage.get_arg0] for returning string-typed arg0 values. + + + The object path item or `NULL` if the first item in the + body of @message is not an object path. + + + + + A `GDBusMessage`. @@ -21475,21 +22492,21 @@ and the per-process or system-wide open files limit is reached. c:identifier="g_dbus_message_get_body" version="2.26"> Gets the body of a message. - + filename="gio/gdbusmessage.c" + line="1119">Gets the body of a message. + A #GVariant or %NULL if the body is + filename="gio/gdbusmessage.c" + line="1125">A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1121">A #GDBusMessage. @@ -21497,20 +22514,20 @@ empty. Do not free, it is owned by @message. Gets the byte order of @message. - + filename="gio/gdbusmessage.c" + line="835">Gets the byte order of @message. + The byte order. + filename="gio/gdbusmessage.c" + line="841">The byte order. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="837">A #GDBusMessage. @@ -21519,20 +22536,20 @@ empty. Do not free, it is owned by @message. c:identifier="g_dbus_message_get_destination" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - + filename="gio/gdbusmessage.c" + line="3427">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. + The value. + filename="gio/gdbusmessage.c" + line="3433">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3429">A #GDBusMessage. @@ -21541,20 +22558,20 @@ empty. Do not free, it is owned by @message. c:identifier="g_dbus_message_get_error_name" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - + filename="gio/gdbusmessage.c" + line="3464">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. + The value. + filename="gio/gdbusmessage.c" + line="3470">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3466">A #GDBusMessage. @@ -21563,20 +22580,20 @@ empty. Do not free, it is owned by @message. c:identifier="g_dbus_message_get_flags" version="2.26"> Gets the flags for @message. - + filename="gio/gdbusmessage.c" + line="922">Gets the flags for @message. + Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). + filename="gio/gdbusmessage.c" + line="928">Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="924">A #GDBusMessage. @@ -21585,30 +22602,30 @@ empty. Do not free, it is owned by @message. c:identifier="g_dbus_message_get_header" version="2.26"> Gets a header field on @message. + filename="gio/gdbusmessage.c" + line="1019">Gets a header field on @message. The caller is responsible for checking the type of the returned #GVariant matches what is expected. - + A #GVariant with the value if the header was found, %NULL + filename="gio/gdbusmessage.c" + line="1029">A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1021">A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) + filename="gio/gdbusmessage.c" + line="1022">A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) @@ -21618,13 +22635,13 @@ otherwise. Do not free, it is owned by @message. c:identifier="g_dbus_message_get_header_fields" version="2.26"> Gets an array of all header fields on @message that are set. - + filename="gio/gdbusmessage.c" + line="1079">Gets an array of all header fields on @message that are set. + An array of header fields + filename="gio/gdbusmessage.c" + line="1085">An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free(). @@ -21634,8 +22651,8 @@ is a #guchar. Free with g_free(). A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1081">A #GDBusMessage. @@ -21644,20 +22661,20 @@ is a #guchar. Free with g_free(). c:identifier="g_dbus_message_get_interface" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - + filename="gio/gdbusmessage.c" + line="3279">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. + The value. + filename="gio/gdbusmessage.c" + line="3285">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3281">A #GDBusMessage. @@ -21667,22 +22684,22 @@ is a #guchar. Free with g_free(). glib:get-property="locked" version="2.26"> Checks whether @message is locked. To monitor changes to this + filename="gio/gdbusmessage.c" + line="3930">Checks whether @message is locked. To monitor changes to this value, conncet to the #GObject::notify signal to listen for changes on the #GDBusMessage:locked property. - + %TRUE if @message is locked, %FALSE otherwise. + filename="gio/gdbusmessage.c" + line="3938">%TRUE if @message is locked, %FALSE otherwise. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3932">A #GDBusMessage. @@ -21691,20 +22708,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_member" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - + filename="gio/gdbusmessage.c" + line="3316">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. + The value. + filename="gio/gdbusmessage.c" + line="3322">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3318">A #GDBusMessage. @@ -21713,20 +22730,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_message_type" version="2.26"> Gets the type of @message. - + filename="gio/gdbusmessage.c" + line="876">Gets the type of @message. + A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). + filename="gio/gdbusmessage.c" + line="882">A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="878">A #GDBusMessage. @@ -21735,20 +22752,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_num_unix_fds" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. - + filename="gio/gdbusmessage.c" + line="3597">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. + The value. + filename="gio/gdbusmessage.c" + line="3603">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3599">A #GDBusMessage. @@ -21757,20 +22774,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_path" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - + filename="gio/gdbusmessage.c" + line="3353">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. + The value. + filename="gio/gdbusmessage.c" + line="3359">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3355">A #GDBusMessage. @@ -21779,20 +22796,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_reply_serial" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. - + filename="gio/gdbusmessage.c" + line="3243">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. + The value. + filename="gio/gdbusmessage.c" + line="3249">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3245">A #GDBusMessage. @@ -21801,20 +22818,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_sender" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - + filename="gio/gdbusmessage.c" + line="3390">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. + The value. + filename="gio/gdbusmessage.c" + line="3396">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3392">A #GDBusMessage. @@ -21823,20 +22840,20 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_serial" version="2.26"> Gets the serial for @message. - + filename="gio/gdbusmessage.c" + line="967">Gets the serial for @message. + A #guint32. + filename="gio/gdbusmessage.c" + line="973">A #guint32. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="969">A #GDBusMessage. @@ -21845,22 +22862,22 @@ on the #GDBusMessage:locked property. c:identifier="g_dbus_message_get_signature" version="2.26"> Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + filename="gio/gdbusmessage.c" + line="3501">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. This will always be non-%NULL, but may be an empty string. - + The value. + filename="gio/gdbusmessage.c" + line="3509">The value. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3503">A #GDBusMessage. @@ -21869,8 +22886,8 @@ This will always be non-%NULL, but may be an empty string. c:identifier="g_dbus_message_get_unix_fd_list" version="2.26"> Gets the UNIX file descriptors associated with @message, if any. + filename="gio/gdbusmessage.c" + line="1197">Gets the UNIX file descriptors associated with @message, if any. This method is only available on UNIX. @@ -21879,36 +22896,36 @@ values in the body of the message. For example, if g_variant_get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by `g_unix_fd_list_get (list, 5, ...)`. - + A #GUnixFDList or %NULL if no file descriptors are + filename="gio/gdbusmessage.c" + line="1211">A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1199">A #GDBusMessage. If @message is locked, does nothing. Otherwise locks the message. - + filename="gio/gdbusmessage.c" + line="3949">If @message is locked, does nothing. Otherwise locks the message. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3951">A #GDBusMessage. @@ -21918,40 +22935,40 @@ associated. Do not free, this object is owned by @message. version="2.26" introspectable="0"> Creates a new #GDBusMessage that is an error reply to @method_call_message. - + filename="gio/gdbusmessage.c" + line="725">Creates a new #GDBusMessage that is an error reply to @method_call_message. + A #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="735">A #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + filename="gio/gdbusmessage.c" + line="727">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. + filename="gio/gdbusmessage.c" + line="729">A valid D-Bus error name. The D-Bus error message in a printf() format. + filename="gio/gdbusmessage.c" + line="730">The D-Bus error message in a printf() format. Arguments for @error_message_format. + filename="gio/gdbusmessage.c" + line="731">Arguments for @error_message_format. @@ -21960,34 +22977,34 @@ create a reply message to. c:identifier="g_dbus_message_new_method_error_literal" version="2.26"> Creates a new #GDBusMessage that is an error reply to @method_call_message. - + filename="gio/gdbusmessage.c" + line="758">Creates a new #GDBusMessage that is an error reply to @method_call_message. + A #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="767">A #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + filename="gio/gdbusmessage.c" + line="760">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. + filename="gio/gdbusmessage.c" + line="762">A valid D-Bus error name. The D-Bus error message. + filename="gio/gdbusmessage.c" + line="763">The D-Bus error message. @@ -21997,40 +23014,40 @@ create a reply message to. version="2.26" introspectable="0"> Like g_dbus_message_new_method_error() but intended for language bindings. - + filename="gio/gdbusmessage.c" + line="802">Like g_dbus_message_new_method_error() but intended for language bindings. + A #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="812">A #GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + filename="gio/gdbusmessage.c" + line="804">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. + filename="gio/gdbusmessage.c" + line="806">A valid D-Bus error name. The D-Bus error message in a printf() format. + filename="gio/gdbusmessage.c" + line="807">The D-Bus error message in a printf() format. Arguments for @error_message_format. + filename="gio/gdbusmessage.c" + line="808">Arguments for @error_message_format. @@ -22039,21 +23056,21 @@ create a reply message to. c:identifier="g_dbus_message_new_method_reply" version="2.26"> Creates a new #GDBusMessage that is a reply to @method_call_message. - + filename="gio/gdbusmessage.c" + line="690">Creates a new #GDBusMessage that is a reply to @method_call_message. + #GDBusMessage. Free with g_object_unref(). + filename="gio/gdbusmessage.c" + line="697">#GDBusMessage. Free with g_object_unref(). A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + filename="gio/gdbusmessage.c" + line="692">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. @@ -22061,13 +23078,13 @@ create a reply message to. Produces a human-readable multi-line description of @message. + filename="gio/gdbusmessage.c" + line="3760">Produces a human-readable multi-line description of @message. The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this: -|[ +``` Flags: none Version: 0 Serial: 4 @@ -22079,9 +23096,9 @@ Headers: Body: () UNIX File Descriptors: (none) -]| +``` or -|[ +``` Flags: no-reply-expected Version: 0 Serial: 477 @@ -22093,25 +23110,25 @@ Headers: Body: () UNIX File Descriptors: fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 -]| - +``` + A string that should be freed with g_free(). + filename="gio/gdbusmessage.c" + line="3800">A string that should be freed with [func@GLib.free]. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3762">A #GDBusMessage. Indentation level. + filename="gio/gdbusmessage.c" + line="3763">Indentation level. @@ -22120,27 +23137,27 @@ UNIX File Descriptors: c:identifier="g_dbus_message_set_body" version="2.26"> Sets the body @message. As a side-effect the + filename="gio/gdbusmessage.c" + line="1137">Sets the body @message. As a side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the type string of @body (or cleared if @body is %NULL). If @body is floating, @message assumes ownership of @body. - + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1139">A #GDBusMessage. Either %NULL or a #GVariant that is a tuple. + filename="gio/gdbusmessage.c" + line="1140">Either %NULL or a #GVariant that is a tuple. @@ -22148,23 +23165,23 @@ If @body is floating, @message assumes ownership of @body. Sets the byte order of @message. - + filename="gio/gdbusmessage.c" + line="850">Sets the byte order of @message. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="852">A #GDBusMessage. The byte order. + filename="gio/gdbusmessage.c" + line="853">The byte order. @@ -22173,17 +23190,17 @@ If @body is floating, @message assumes ownership of @body. c:identifier="g_dbus_message_set_destination" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - + filename="gio/gdbusmessage.c" + line="3444">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3446">A #GDBusMessage. nullable="1" allow-none="1"> The value to set. + filename="gio/gdbusmessage.c" + line="3447">The value to set. @@ -22201,9 +23218,9 @@ If @body is floating, @message assumes ownership of @body. c:identifier="g_dbus_message_set_error_name" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - + filename="gio/gdbusmessage.c" + line="3481">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. + @@ -22213,14 +23230,14 @@ If @body is floating, @message assumes ownership of @body. nullable="1" allow-none="1"> A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3483">A #GDBusMessage. The value to set. + filename="gio/gdbusmessage.c" + line="3484">The value to set. @@ -22229,23 +23246,23 @@ If @body is floating, @message assumes ownership of @body. c:identifier="g_dbus_message_set_flags" version="2.26"> Sets the flags to set on @message. - + filename="gio/gdbusmessage.c" + line="939">Sets the flags to set on @message. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="941">A #GDBusMessage. Flags for @message that are set (typically values from the #GDBusMessageFlags + filename="gio/gdbusmessage.c" + line="942">Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). @@ -22255,25 +23272,25 @@ enumeration bitwise ORed together). c:identifier="g_dbus_message_set_header" version="2.26"> Sets a header field on @message. + filename="gio/gdbusmessage.c" + line="1043">Sets a header field on @message. If @value is floating, @message assumes ownership of @value. - + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1045">A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) + filename="gio/gdbusmessage.c" + line="1046">A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) @@ -22282,8 +23299,8 @@ If @value is floating, @message assumes ownership of @value. nullable="1" allow-none="1"> A #GVariant to set the header field or %NULL to clear the header field. + filename="gio/gdbusmessage.c" + line="1047">A #GVariant to set the header field or %NULL to clear the header field. @@ -22292,17 +23309,17 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_interface" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - + filename="gio/gdbusmessage.c" + line="3296">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3298">A #GDBusMessage. nullable="1" allow-none="1"> The value to set. + filename="gio/gdbusmessage.c" + line="3299">The value to set. @@ -22320,17 +23337,17 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_member" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - + filename="gio/gdbusmessage.c" + line="3333">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3335">A #GDBusMessage. nullable="1" allow-none="1"> The value to set. + filename="gio/gdbusmessage.c" + line="3336">The value to set. @@ -22348,23 +23365,23 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_message_type" version="2.26"> Sets @message to be of @type. - + filename="gio/gdbusmessage.c" + line="893">Sets @message to be of @type. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="895">A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). + filename="gio/gdbusmessage.c" + line="896">A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). @@ -22373,23 +23390,23 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_num_unix_fds" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. - + filename="gio/gdbusmessage.c" + line="3614">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3616">A #GDBusMessage. The value to set. + filename="gio/gdbusmessage.c" + line="3617">The value to set. @@ -22398,17 +23415,17 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_path" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - + filename="gio/gdbusmessage.c" + line="3370">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3372">A #GDBusMessage. nullable="1" allow-none="1"> The value to set. + filename="gio/gdbusmessage.c" + line="3373">The value to set. @@ -22426,23 +23443,23 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_reply_serial" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. - + filename="gio/gdbusmessage.c" + line="3260">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3262">A #GDBusMessage. The value to set. + filename="gio/gdbusmessage.c" + line="3263">The value to set. @@ -22451,17 +23468,17 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_sender" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - + filename="gio/gdbusmessage.c" + line="3407">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3409">A #GDBusMessage. nullable="1" allow-none="1"> The value to set. + filename="gio/gdbusmessage.c" + line="3410">The value to set. @@ -22479,23 +23496,26 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_serial" version="2.26"> Sets the serial for @message. - + filename="gio/gdbusmessage.c" + line="984">Sets the serial for @message. + +The [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-messages) +does not allow the @serial to be zero. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="986">A #GDBusMessage. A #guint32. + filename="gio/gdbusmessage.c" + line="987">A #guint32, which must not be zero. @@ -22504,17 +23524,17 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_signature" version="2.26"> Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. - + filename="gio/gdbusmessage.c" + line="3524">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3526">A #GDBusMessage. nullable="1" allow-none="1"> The value to set. + filename="gio/gdbusmessage.c" + line="3527">The value to set. @@ -22532,8 +23552,8 @@ If @value is floating, @message assumes ownership of @value. c:identifier="g_dbus_message_set_unix_fd_list" version="2.26"> Sets the UNIX file descriptors associated with @message. As a + filename="gio/gdbusmessage.c" + line="1223">Sets the UNIX file descriptors associated with @message. As a side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field is set to the number of fds in @fd_list (or cleared if @fd_list is %NULL). @@ -22544,15 +23564,15 @@ When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. - + A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="1225">A #GDBusMessage. A #GUnixFDList or %NULL. + filename="gio/gdbusmessage.c" + line="1226">A #GUnixFDList or %NULL. @@ -22571,14 +23591,14 @@ access file descriptors if they are referenced by a value of type version="2.26" throws="1"> Serializes @message to a blob. The byte order returned by + filename="gio/gdbusmessage.c" + line="2944">Serializes @message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used. - + A pointer to a + filename="gio/gdbusmessage.c" + line="2954">A pointer to a valid binary D-Bus message of @out_size bytes generated by @message or %NULL if @error is set. Free with g_free(). @@ -22588,8 +23608,8 @@ or %NULL if @error is set. Free with g_free(). A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="2946">A #GDBusMessage. caller-allocates="0" transfer-ownership="full"> Return location for size of generated blob. + filename="gio/gdbusmessage.c" + line="2947">Return location for size of generated blob. A #GDBusCapabilityFlags describing what protocol features are supported. + filename="gio/gdbusmessage.c" + line="2948">A #GDBusCapabilityFlags describing what protocol features are supported. @@ -22614,26 +23634,26 @@ or %NULL if @error is set. Free with g_free(). version="2.26" throws="1"> If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does + filename="gio/gdbusmessage.c" + line="3633">If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does nothing and returns %FALSE. Otherwise this method encodes the error in @message as a #GError using g_dbus_error_set_dbus_error() using the information in the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as well as the first string item in @message's body. - + %TRUE if @error was set, %FALSE otherwise. + filename="gio/gdbusmessage.c" + line="3646">%TRUE if @error was set, %FALSE otherwise. A #GDBusMessage. + filename="gio/gdbusmessage.c" + line="3635">A #GDBusMessage. @@ -22651,16 +23671,16 @@ well as the first string item in @message's body. glib:get-type="g_dbus_message_byte_order_get_type" c:type="GDBusMessageByteOrder"> Enumeration used to describe the byte order of a D-Bus message. + filename="gio/gioenums.h" + line="1482">Enumeration used to describe the byte order of a D-Bus message. The byte order is big endian. + filename="gio/gioenums.h" + line="1484">The byte order is big endian. glib:nick="little-endian" glib:name="G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN"> The byte order is little endian. + filename="gio/gioenums.h" + line="1485">The byte order is little endian. Signature for function used in g_dbus_connection_add_filter(). + filename="gio/gdbusconnection.h" + line="657">Signature for function used in g_dbus_connection_add_filter(). A filter function is passed a #GDBusMessage and expected to return a #GDBusMessage too. Passive filter functions that don't modify the @@ -22736,11 +23756,11 @@ descriptors, not compatible with @connection), then a warning is logged to standard error. Applications can check this ahead of time using g_dbus_message_to_blob() passing a #GDBusCapabilityFlags value obtained from @connection. - + A #GDBusMessage that will be freed with + filename="gio/gdbusconnection.h" + line="725">A #GDBusMessage that will be freed with g_object_unref() or %NULL to drop the message. Passive filter functions can simply return the passed @message object. @@ -22748,20 +23768,20 @@ functions can simply return the passed @message object. A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="659">A #GDBusConnection. A locked #GDBusMessage that the filter function takes ownership of. + filename="gio/gdbusconnection.h" + line="660">A locked #GDBusMessage that the filter function takes ownership of. %TRUE if it is a message received from the other peer, %FALSE if it is + filename="gio/gdbusconnection.h" + line="661">%TRUE if it is a message received from the other peer, %FALSE if it is a message to be sent to the other peer. @@ -22771,8 +23791,8 @@ a message to be sent to the other peer. allow-none="1" closure="3"> User data passed when adding the filter. + filename="gio/gdbusconnection.h" + line="663">User data passed when adding the filter. @@ -22783,16 +23803,16 @@ a message to be sent to the other peer. glib:get-type="g_dbus_message_flags_get_type" c:type="GDBusMessageFlags"> Message flags used in #GDBusMessage. + filename="gio/gioenums.h" + line="1305">Message flags used in #GDBusMessage. No flags set. + filename="gio/gioenums.h" + line="1307">No flags set. glib:nick="no-reply-expected" glib:name="G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED"> A reply is not expected. + filename="gio/gioenums.h" + line="1308">A reply is not expected. glib:nick="no-auto-start" glib:name="G_DBUS_MESSAGE_FLAGS_NO_AUTO_START"> The bus must not launch an + filename="gio/gioenums.h" + line="1309">The bus must not launch an owner for the destination name in response to this message. glib:nick="allow-interactive-authorization" glib:name="G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION"> If set on a method + filename="gio/gioenums.h" + line="1311">If set on a method call, this flag means that the caller is prepared to wait for interactive authorization. Since 2.46. @@ -22831,16 +23851,16 @@ authorization. Since 2.46. glib:get-type="g_dbus_message_header_field_get_type" c:type="GDBusMessageHeaderField"> Header fields used in #GDBusMessage. + filename="gio/gioenums.h" + line="1326">Header fields used in #GDBusMessage. Not a valid header field. + filename="gio/gioenums.h" + line="1328">Not a valid header field. glib:nick="path" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_PATH"> The object path. + filename="gio/gioenums.h" + line="1329">The object path. glib:nick="interface" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE"> The interface name. + filename="gio/gioenums.h" + line="1330">The interface name. glib:nick="member" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_MEMBER"> The method or signal name. + filename="gio/gioenums.h" + line="1331">The method or signal name. glib:nick="error-name" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME"> The name of the error that occurred. + filename="gio/gioenums.h" + line="1332">The name of the error that occurred. glib:nick="reply-serial" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL"> The serial number the message is a reply to. + filename="gio/gioenums.h" + line="1333">The serial number the message is a reply to. glib:nick="destination" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION"> The name the message is intended for. + filename="gio/gioenums.h" + line="1334">The name the message is intended for. glib:nick="sender" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_SENDER"> Unique name of the sender of the message (filled in by the bus). + filename="gio/gioenums.h" + line="1335">Unique name of the sender of the message (filled in by the bus). glib:nick="signature" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE"> The signature of the message body. + filename="gio/gioenums.h" + line="1336">The signature of the message body. glib:nick="num-unix-fds" glib:name="G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS"> The number of UNIX file descriptors that accompany the message. + filename="gio/gioenums.h" + line="1337">The number of UNIX file descriptors that accompany the message. glib:get-type="g_dbus_message_type_get_type" c:type="GDBusMessageType"> Message types used in #GDBusMessage. + filename="gio/gioenums.h" + line="1285">Message types used in #GDBusMessage. Message is of invalid type. + filename="gio/gioenums.h" + line="1287">Message is of invalid type. glib:nick="method-call" glib:name="G_DBUS_MESSAGE_TYPE_METHOD_CALL"> Method call. + filename="gio/gioenums.h" + line="1288">Method call. glib:nick="method-return" glib:name="G_DBUS_MESSAGE_TYPE_METHOD_RETURN"> Method reply. + filename="gio/gioenums.h" + line="1289">Method reply. glib:nick="error" glib:name="G_DBUS_MESSAGE_TYPE_ERROR"> Error reply. + filename="gio/gioenums.h" + line="1290">Error reply. glib:nick="signal" glib:name="G_DBUS_MESSAGE_TYPE_SIGNAL"> Signal emission. + filename="gio/gioenums.h" + line="1291">Signal emission. glib:get-type="g_dbus_method_info_get_type" c:symbol-prefix="dbus_method_info"> Information about a method on an D-Bus interface. - + filename="gio/gdbusintrospection.h" + line="74">Information about a method on a D-Bus interface. + The reference count or -1 if statically allocated. The name of the D-Bus method, e.g. @RequestName. A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments. @@ -23010,7 +24030,7 @@ authorization. Since 2.46. A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments. @@ -23018,7 +24038,7 @@ authorization. Since 2.46. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -23026,21 +24046,21 @@ authorization. Since 2.46. If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="122">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="129">The same @info. A #GDBusMethodInfo + filename="gio/gdbusintrospection.c" + line="124">A #GDBusMethodInfo @@ -23049,19 +24069,19 @@ the reference count. c:identifier="g_dbus_method_info_unref" version="2.26"> If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="284">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusMethodInfo. + filename="gio/gdbusintrospection.c" + line="286">A #GDBusMethodInfo. @@ -23075,32 +24095,33 @@ the memory used is freed. glib:type-name="GDBusMethodInvocation" glib:get-type="g_dbus_method_invocation_get_type"> Instances of the #GDBusMethodInvocation class are used when + filename="gio/gdbusmethodinvocation.c" + line="42">Instances of the `GDBusMethodInvocation` class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors. -The normal way to obtain a #GDBusMethodInvocation object is to receive -it as an argument to the handle_method_call() function in a -#GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). +The normal way to obtain a `GDBusMethodInvocation` object is to receive +it as an argument to the `handle_method_call()` function in a +[type@Gio.DBusInterfaceVTable] that was passed to +[method@Gio.DBusConnection.register_object]. Gets the #GDBusConnection the method was invoked on. - + filename="gio/gdbusmethodinvocation.c" + line="255">Gets the #GDBusConnection the method was invoked on. + A #GDBusConnection. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="261">A #GDBusConnection. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="257">A #GDBusMethodInvocation. @@ -23109,25 +24130,30 @@ it as an argument to the handle_method_call() function in a c:identifier="g_dbus_method_invocation_get_interface_name" version="2.26"> Gets the name of the D-Bus interface the method was invoked on. + filename="gio/gdbusmethodinvocation.c" + line="162">Gets the name of the D-Bus interface the method was invoked on. + +This can be `NULL` if it was not specified by the sender. See +[callback@Gio.DBusInterfaceMethodCallFunc] or the +[D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method) +for details on when this can happen and how it should be handled. If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then "org.freedesktop.DBus.Properties" will be returned. See #GDBusInterfaceVTable for more information. - - + + A string. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="178">A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="164">A #GDBusMethodInvocation. @@ -23136,27 +24162,28 @@ been redirected to the method call handler then c:identifier="g_dbus_method_invocation_get_message" version="2.26"> Gets the #GDBusMessage for the method invocation. This is useful if + filename="gio/gdbusmethodinvocation.c" + line="272">Gets the #GDBusMessage for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the #GVariant API. -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] +See this [server][class@Gio.DBusConnection#an-example-d-bus-server] +and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors. - + #GDBusMessage. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="286">#GDBusMessage. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="274">A #GDBusMethodInvocation. @@ -23165,25 +24192,25 @@ UNIX file descriptors. c:identifier="g_dbus_method_invocation_get_method_info" version="2.26"> Gets information about the method call, if any. + filename="gio/gdbusmethodinvocation.c" + line="189">Gets information about the method call, if any. If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then %NULL will be returned. See g_dbus_method_invocation_get_property_info() and #GDBusInterfaceVTable for more information. - + A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="200">A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="191">A #GDBusMethodInvocation. @@ -23192,20 +24219,20 @@ returned. See g_dbus_method_invocation_get_property_info() and c:identifier="g_dbus_method_invocation_get_method_name" version="2.26"> Gets the name of the method that was invoked. - + filename="gio/gdbusmethodinvocation.c" + line="238">Gets the name of the method that was invoked. + A string. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="244">A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="240">A #GDBusMethodInvocation. @@ -23214,20 +24241,20 @@ returned. See g_dbus_method_invocation_get_property_info() and c:identifier="g_dbus_method_invocation_get_object_path" version="2.26"> Gets the object path the method was invoked on. - + filename="gio/gdbusmethodinvocation.c" + line="145">Gets the object path the method was invoked on. + A string. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="151">A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="147">A #GDBusMethodInvocation. @@ -23236,21 +24263,21 @@ returned. See g_dbus_method_invocation_get_property_info() and c:identifier="g_dbus_method_invocation_get_parameters" version="2.26"> Gets the parameters of the method invocation. If there are no input + filename="gio/gdbusmethodinvocation.c" + line="297">Gets the parameters of the method invocation. If there are no input parameters then this will return a GVariant with 0 children rather than NULL. - + A #GVariant tuple. Do not unref this because it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="304">A #GVariant tuple. Do not unref this because it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="299">A #GDBusMethodInvocation. @@ -23259,8 +24286,8 @@ parameters then this will return a GVariant with 0 children rather than NULL. Gets information about the property that this method call is for, if + filename="gio/gdbusmethodinvocation.c" + line="211">Gets information about the property that this method call is for, if any. This will only be set in the case of an invocation in response to a @@ -23271,18 +24298,18 @@ property_set() vtable pointers being unset. See #GDBusInterfaceVTable for more information. If the call was GetAll, %NULL will be returned. - + a #GDBusPropertyInfo or %NULL + filename="gio/gdbusmethodinvocation.c" + line="227">a #GDBusPropertyInfo or %NULL A #GDBusMethodInvocation + filename="gio/gdbusmethodinvocation.c" + line="213">A #GDBusMethodInvocation @@ -23291,20 +24318,23 @@ If the call was GetAll, %NULL will be returned. c:identifier="g_dbus_method_invocation_get_sender" version="2.26"> Gets the bus name that invoked the method. - - + filename="gio/gdbusmethodinvocation.c" + line="125">Gets the bus name that invoked the method. + +This can return %NULL if not specified by the caller, e.g. on peer-to-peer +connections. + + A string. Do not free, it is owned by @invocation. + filename="gio/gdbusmethodinvocation.c" + line="134">A string. Do not free, it is owned by @invocation. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="127">A #GDBusMethodInvocation. @@ -23314,20 +24344,20 @@ If the call was GetAll, %NULL will be returned. version="2.26" introspectable="0"> Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). - + filename="gio/gdbusmethodinvocation.c" + line="315">Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). + A #gpointer. + filename="gio/gdbusmethodinvocation.c" + line="321">A #gpointer. A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="317">A #GDBusMethodInvocation. @@ -23336,33 +24366,33 @@ If the call was GetAll, %NULL will be returned. c:identifier="g_dbus_method_invocation_return_dbus_error" version="2.26"> Finishes handling a D-Bus method call by returning an error. + filename="gio/gdbusmethodinvocation.c" + line="786">Finishes handling a D-Bus method call by returning an error. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="788">A #GDBusMethodInvocation. A valid D-Bus error name. + filename="gio/gdbusmethodinvocation.c" + line="789">A valid D-Bus error name. A valid D-Bus error message. + filename="gio/gdbusmethodinvocation.c" + line="790">A valid D-Bus error message. @@ -23372,8 +24402,8 @@ This method will take ownership of @invocation. See version="2.26" introspectable="0"> Finishes handling a D-Bus method call by returning an error. + filename="gio/gdbusmethodinvocation.c" + line="611">Finishes handling a D-Bus method call by returning an error. See g_dbus_error_encode_gerror() for details about what error name will be returned on the wire. In a nutshell, if the given error is @@ -23393,39 +24423,39 @@ This method will take ownership of @invocation. See Since 2.48, if the method call requested for a reply not to be sent then this call will free @invocation but otherwise do nothing (as per the recommendations of the D-Bus specification). - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="613">A #GDBusMethodInvocation. A #GQuark for the #GError error domain. + filename="gio/gdbusmethodinvocation.c" + line="614">A #GQuark for the #GError error domain. The error code. + filename="gio/gdbusmethodinvocation.c" + line="615">The error code. printf()-style format. + filename="gio/gdbusmethodinvocation.c" + line="616">printf()-style format. Parameters for @format. + filename="gio/gdbusmethodinvocation.c" + line="617">Parameters for @format. @@ -23434,39 +24464,39 @@ the recommendations of the D-Bus specification). c:identifier="g_dbus_method_invocation_return_error_literal" version="2.26"> Like g_dbus_method_invocation_return_error() but without printf()-style formatting. + filename="gio/gdbusmethodinvocation.c" + line="700">Like g_dbus_method_invocation_return_error() but without printf()-style formatting. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="702">A #GDBusMethodInvocation. A #GQuark for the #GError error domain. + filename="gio/gdbusmethodinvocation.c" + line="703">A #GQuark for the #GError error domain. The error code. + filename="gio/gdbusmethodinvocation.c" + line="704">The error code. The error message. + filename="gio/gdbusmethodinvocation.c" + line="705">The error message. @@ -23476,46 +24506,46 @@ This method will take ownership of @invocation. See version="2.26" introspectable="0"> Like g_dbus_method_invocation_return_error() but intended for + filename="gio/gdbusmethodinvocation.c" + line="663">Like g_dbus_method_invocation_return_error() but intended for language bindings. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="665">A #GDBusMethodInvocation. A #GQuark for the #GError error domain. + filename="gio/gdbusmethodinvocation.c" + line="666">A #GQuark for the #GError error domain. The error code. + filename="gio/gdbusmethodinvocation.c" + line="667">The error code. printf()-style format. + filename="gio/gdbusmethodinvocation.c" + line="668">printf()-style format. #va_list of parameters for @format. + filename="gio/gdbusmethodinvocation.c" + line="669">#va_list of parameters for @format. @@ -23524,28 +24554,28 @@ This method will take ownership of @invocation. See c:identifier="g_dbus_method_invocation_return_gerror" version="2.26"> Like g_dbus_method_invocation_return_error() but takes a #GError + filename="gio/gdbusmethodinvocation.c" + line="731">Like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="733">A #GDBusMethodInvocation. A #GError. + filename="gio/gdbusmethodinvocation.c" + line="734">A #GError. @@ -23554,8 +24584,8 @@ This method will take ownership of @invocation. See c:identifier="g_dbus_method_invocation_return_value" version="2.26"> Finishes handling a D-Bus method call by returning @parameters. + filename="gio/gdbusmethodinvocation.c" + line="536">Finishes handling a D-Bus method call by returning @parameters. If the @parameters GVariant is floating, it is consumed. It is an error if @parameters is not of the right format: it must be a tuple @@ -23587,15 +24617,15 @@ Since 2.48, if the method call requested for a reply not to be sent then this call will sink @parameters and free @invocation, but otherwise do nothing (as per the recommendations of the D-Bus specification). - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="538">A #GDBusMethodInvocation. nullable="1" allow-none="1"> A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. + filename="gio/gdbusmethodinvocation.c" + line="539">A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. @@ -23613,23 +24643,23 @@ specification). c:identifier="g_dbus_method_invocation_return_value_with_unix_fd_list" version="2.30"> Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. + filename="gio/gdbusmethodinvocation.c" + line="584">Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. This method is only available on UNIX. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="586">A #GDBusMethodInvocation. A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. + filename="gio/gdbusmethodinvocation.c" + line="587">A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. A #GUnixFDList or %NULL. + filename="gio/gdbusmethodinvocation.c" + line="588">A #GUnixFDList or %NULL. @@ -23657,28 +24687,28 @@ This method will take ownership of @invocation. See version="2.30" introspectable="0"> Like g_dbus_method_invocation_return_gerror() but takes ownership + filename="gio/gdbusmethodinvocation.c" + line="762">Like g_dbus_method_invocation_return_gerror() but takes ownership of @error so the caller does not need to free it. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. - + A #GDBusMethodInvocation. + filename="gio/gdbusmethodinvocation.c" + line="764">A #GDBusMethodInvocation. A #GError. + filename="gio/gdbusmethodinvocation.c" + line="765">A #GError. @@ -23691,24 +24721,24 @@ This method will take ownership of @invocation. See glib:get-type="g_dbus_node_info_get_type" c:symbol-prefix="dbus_node_info"> Information about nodes in a remote object hierarchy. - + The reference count or -1 if statically allocated. The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details. A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces. @@ -23716,7 +24746,7 @@ This method will take ownership of @invocation. See A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes. @@ -23724,7 +24754,7 @@ This method will take ownership of @invocation. See A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -23735,28 +24765,28 @@ This method will take ownership of @invocation. See version="2.26" throws="1"> Parses @xml_data and returns a #GDBusNodeInfo representing the data. + filename="gio/gdbusintrospection.c" + line="1742">Parses @xml_data and returns a #GDBusNodeInfo representing the data. The introspection XML must contain exactly one top-level -<node> element. +`<node>` element. Note that this routine is using a -[GMarkup][glib-Simple-XML-Subset-Parser.description]-based +[GMarkup](../glib/markup.html)-based parser that only accepts a subset of valid XML documents. - + A #GDBusNodeInfo structure or %NULL if @error is set. Free + filename="gio/gdbusintrospection.c" + line="1756">A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref(). Valid D-Bus introspection XML. + filename="gio/gdbusintrospection.c" + line="1744">Valid D-Bus introspection XML. @@ -23765,32 +24795,32 @@ with g_dbus_node_info_unref(). c:identifier="g_dbus_node_info_generate_xml" version="2.26"> Appends an XML representation of @info (and its children) to @string_builder. + filename="gio/gdbusintrospection.c" + line="812">Appends an XML representation of @info (and its children) to @string_builder. This function is typically used for generating introspection XML documents at run-time for handling the `org.freedesktop.DBus.Introspectable.Introspect` method. - + A #GDBusNodeInfo. + filename="gio/gdbusintrospection.c" + line="814">A #GDBusNodeInfo. Indentation level. + filename="gio/gdbusintrospection.c" + line="815">Indentation level. A #GString to to append XML data to. + filename="gio/gdbusintrospection.c" + line="816">A #GString to to append XML data to. @@ -23799,49 +24829,49 @@ handling the `org.freedesktop.DBus.Introspectable.Introspect` method. c:identifier="g_dbus_node_info_lookup_interface" version="2.26"> Looks up information about an interface. + filename="gio/gdbusintrospection.c" + line="2147">Looks up information about an interface. The cost of this function is O(n) in number of interfaces. - + A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. + filename="gio/gdbusintrospection.c" + line="2156">A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. A #GDBusNodeInfo. + filename="gio/gdbusintrospection.c" + line="2149">A #GDBusNodeInfo. A D-Bus interface name. + filename="gio/gdbusintrospection.c" + line="2150">A D-Bus interface name. If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="82">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="89">The same @info. A #GDBusNodeInfo + filename="gio/gdbusintrospection.c" + line="84">A #GDBusNodeInfo @@ -23850,19 +24880,19 @@ the reference count. c:identifier="g_dbus_node_info_unref" version="2.26"> If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="383">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusNodeInfo. + filename="gio/gdbusintrospection.c" + line="385">A #GDBusNodeInfo. @@ -23875,38 +24905,38 @@ the memory used is freed. glib:get-type="g_dbus_object_get_type" glib:type-struct="DBusObjectIface"> The #GDBusObject type is the base type for D-Bus objects on both -the service side (see #GDBusObjectSkeleton) and the client side -(see #GDBusObjectProxy). It is essentially just a container of + filename="gio/gdbusobject.c" + line="31">The `GDBusObject` type is the base type for D-Bus objects on both +the service side (see [class@Gio.DBusObjectSkeleton]) and the client side +(see [class@Gio.DBusObjectProxy]). It is essentially just a container of interfaces. - + Gets the D-Bus interface with name @interface_name associated with + filename="gio/gdbusobject.c" + line="125">Gets the D-Bus interface with name @interface_name associated with @object, if any. - + %NULL if not found, otherwise a + filename="gio/gdbusobject.c" + line="133">%NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). A #GDBusObject. + filename="gio/gdbusobject.c" + line="127">A #GDBusObject. A D-Bus interface name. + filename="gio/gdbusobject.c" + line="128">A D-Bus interface name. @@ -23915,13 +24945,13 @@ interfaces. invoker="get_interfaces" version="2.30"> Gets the D-Bus interfaces associated with @object. - + filename="gio/gdbusobject.c" + line="106">Gets the D-Bus interfaces associated with @object. + A list of #GDBusInterface instances. + filename="gio/gdbusobject.c" + line="112">A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). @@ -23931,8 +24961,8 @@ interfaces. A #GDBusObject. + filename="gio/gdbusobject.c" + line="108">A #GDBusObject. @@ -23941,26 +24971,29 @@ interfaces. invoker="get_object_path" version="2.30"> Gets the object path for @object. - + filename="gio/gdbusobject.c" + line="89">Gets the object path for @object. + A string owned by @object. Do not free. + filename="gio/gdbusobject.c" + line="95">A string owned by @object. Do not free. A #GDBusObject. + filename="gio/gdbusobject.c" + line="91">A #GDBusObject. - + Signal handler for the #GDBusObject::interface-added signal. + @@ -23974,7 +25007,10 @@ interfaces. - + Signal handler for the #GDBusObject::interface-removed signal. + @@ -23991,28 +25027,28 @@ interfaces. c:identifier="g_dbus_object_get_interface" version="2.30"> Gets the D-Bus interface with name @interface_name associated with + filename="gio/gdbusobject.c" + line="125">Gets the D-Bus interface with name @interface_name associated with @object, if any. - + %NULL if not found, otherwise a + filename="gio/gdbusobject.c" + line="133">%NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). A #GDBusObject. + filename="gio/gdbusobject.c" + line="127">A #GDBusObject. A D-Bus interface name. + filename="gio/gdbusobject.c" + line="128">A D-Bus interface name. @@ -24021,13 +25057,13 @@ interfaces. c:identifier="g_dbus_object_get_interfaces" version="2.30"> Gets the D-Bus interfaces associated with @object. - + filename="gio/gdbusobject.c" + line="106">Gets the D-Bus interfaces associated with @object. + A list of #GDBusInterface instances. + filename="gio/gdbusobject.c" + line="112">A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). @@ -24037,8 +25073,8 @@ interfaces. A #GDBusObject. + filename="gio/gdbusobject.c" + line="108">A #GDBusObject. @@ -24047,52 +25083,52 @@ interfaces. c:identifier="g_dbus_object_get_object_path" version="2.30"> Gets the object path for @object. - + filename="gio/gdbusobject.c" + line="89">Gets the object path for @object. + A string owned by @object. Do not free. + filename="gio/gdbusobject.c" + line="95">A string owned by @object. Do not free. A #GDBusObject. + filename="gio/gdbusobject.c" + line="91">A #GDBusObject. Emitted when @interface is added to @object. + filename="gio/gdbusobject.c" + line="46">Emitted when @interface is added to @object. The #GDBusInterface that was added. + filename="gio/gdbusobject.c" + line="49">The #GDBusInterface that was added. Emitted when @interface is removed from @object. + filename="gio/gdbusobject.c" + line="66">Emitted when @interface is removed from @object. The #GDBusInterface that was removed. + filename="gio/gdbusobject.c" + line="69">The #GDBusInterface that was removed. @@ -24103,41 +25139,47 @@ interfaces. glib:is-gtype-struct-for="DBusObject" version="2.30"> Base object type for D-Bus objects. - + The parent interface. + Returns the object path. See g_dbus_object_get_object_path(). - + A string owned by @object. Do not free. + filename="gio/gdbusobject.c" + line="95">A string owned by @object. Do not free. A #GDBusObject. + filename="gio/gdbusobject.c" + line="91">A #GDBusObject. + Returns all interfaces. See g_dbus_object_get_interfaces(). - + A list of #GDBusInterface instances. + filename="gio/gdbusobject.c" + line="112">A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). @@ -24147,42 +25189,48 @@ interfaces. A #GDBusObject. + filename="gio/gdbusobject.c" + line="108">A #GDBusObject. + Returns an interface by name. See g_dbus_object_get_interface(). - + %NULL if not found, otherwise a + filename="gio/gdbusobject.c" + line="133">%NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). A #GDBusObject. + filename="gio/gdbusobject.c" + line="127">A #GDBusObject. A D-Bus interface name. + filename="gio/gdbusobject.c" + line="128">A D-Bus interface name. + Signal handler for the #GDBusObject::interface-added signal. - + @@ -24197,8 +25245,11 @@ interfaces. + Signal handler for the #GDBusObject::interface-removed signal. - + @@ -24220,74 +25271,74 @@ interfaces. glib:get-type="g_dbus_object_manager_get_type" glib:type-struct="DBusObjectManagerIface"> The #GDBusObjectManager type is the base type for service- and + filename="gio/gdbusobjectmanager.c" + line="33">The `GDBusObjectManager` type is the base type for service- and client-side implementations of the standardized -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) +[`org.freedesktop.DBus.ObjectManager`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. -See #GDBusObjectManagerClient for the client-side implementation -and #GDBusObjectManagerServer for the service-side implementation. - +See [class@Gio.DBusObjectManagerClient] for the client-side implementation +and [class@Gio.DBusObjectManagerServer] for the service-side implementation. + Gets the interface proxy for @interface_name at @object_path, if + filename="gio/gdbusobjectmanager.c" + line="223">Gets the interface proxy for @interface_name at @object_path, if any. - + A #GDBusInterface instance or %NULL. Free + filename="gio/gdbusobjectmanager.c" + line="232">A #GDBusInterface instance or %NULL. Free with g_object_unref(). A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="225">A #GDBusObjectManager. Object path to look up. + filename="gio/gdbusobjectmanager.c" + line="226">Object path to look up. D-Bus interface name to look up. + filename="gio/gdbusobjectmanager.c" + line="227">D-Bus interface name to look up. Gets the #GDBusObject at @object_path, if any. - + filename="gio/gdbusobjectmanager.c" + line="202">Gets the #GDBusObject at @object_path, if any. + A #GDBusObject or %NULL. Free with + filename="gio/gdbusobjectmanager.c" + line="209">A #GDBusObject or %NULL. Free with g_object_unref(). A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="204">A #GDBusObjectManager. Object path to look up. + filename="gio/gdbusobjectmanager.c" + line="205">Object path to look up. @@ -24296,33 +25347,33 @@ any. invoker="get_object_path" version="2.30"> Gets the object path that @manager is for. - + filename="gio/gdbusobjectmanager.c" + line="165">Gets the object path that @manager is for. + A string owned by @manager. Do not free. + filename="gio/gdbusobjectmanager.c" + line="171">A string owned by @manager. Do not free. A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="167">A #GDBusObjectManager. Gets all #GDBusObject objects known to @manager. - + filename="gio/gdbusobjectmanager.c" + line="182">Gets all #GDBusObject objects known to @manager. + A list of + filename="gio/gdbusobjectmanager.c" + line="188">A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). @@ -24333,14 +25384,17 @@ any. A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="184">A #GDBusObjectManager. - + Signal handler for the #GDBusObjectManager::interface-added signal. + @@ -24357,7 +25411,10 @@ any. - + Signal handler for the #GDBusObjectManager::interface-removed signal. + @@ -24374,7 +25431,10 @@ any. - + Signal handler for the #GDBusObjectManager::object-added signal. + @@ -24388,7 +25448,10 @@ any. - + Signal handler for the #GDBusObjectManager::object-removed signal. + @@ -24405,34 +25468,34 @@ any. c:identifier="g_dbus_object_manager_get_interface" version="2.30"> Gets the interface proxy for @interface_name at @object_path, if + filename="gio/gdbusobjectmanager.c" + line="223">Gets the interface proxy for @interface_name at @object_path, if any. - + A #GDBusInterface instance or %NULL. Free + filename="gio/gdbusobjectmanager.c" + line="232">A #GDBusInterface instance or %NULL. Free with g_object_unref(). A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="225">A #GDBusObjectManager. Object path to look up. + filename="gio/gdbusobjectmanager.c" + line="226">Object path to look up. D-Bus interface name to look up. + filename="gio/gdbusobjectmanager.c" + line="227">D-Bus interface name to look up. @@ -24441,27 +25504,27 @@ any. c:identifier="g_dbus_object_manager_get_object" version="2.30"> Gets the #GDBusObject at @object_path, if any. - + filename="gio/gdbusobjectmanager.c" + line="202">Gets the #GDBusObject at @object_path, if any. + A #GDBusObject or %NULL. Free with + filename="gio/gdbusobjectmanager.c" + line="209">A #GDBusObject or %NULL. Free with g_object_unref(). A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="204">A #GDBusObjectManager. Object path to look up. + filename="gio/gdbusobjectmanager.c" + line="205">Object path to look up. @@ -24470,20 +25533,20 @@ any. c:identifier="g_dbus_object_manager_get_object_path" version="2.30"> Gets the object path that @manager is for. - + filename="gio/gdbusobjectmanager.c" + line="165">Gets the object path that @manager is for. + A string owned by @manager. Do not free. + filename="gio/gdbusobjectmanager.c" + line="171">A string owned by @manager. Do not free. A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="167">A #GDBusObjectManager. @@ -24492,13 +25555,13 @@ any. c:identifier="g_dbus_object_manager_get_objects" version="2.30"> Gets all #GDBusObject objects known to @manager. - + filename="gio/gdbusobjectmanager.c" + line="182">Gets all #GDBusObject objects known to @manager. + A list of + filename="gio/gdbusobjectmanager.c" + line="188">A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). @@ -24509,16 +25572,16 @@ any. A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="184">A #GDBusObjectManager. Emitted when @interface is added to @object. + filename="gio/gdbusobjectmanager.c" + line="103">Emitted when @interface is added to @object. This signal exists purely as a convenience to avoid having to connect signals to all objects managed by @manager. @@ -24528,22 +25591,22 @@ connect signals to all objects managed by @manager. The #GDBusObject on which an interface was added. + filename="gio/gdbusobjectmanager.c" + line="106">The #GDBusObject on which an interface was added. The #GDBusInterface that was added. + filename="gio/gdbusobjectmanager.c" + line="107">The #GDBusInterface that was added. Emitted when @interface has been removed from @object. + filename="gio/gdbusobjectmanager.c" + line="132">Emitted when @interface has been removed from @object. This signal exists purely as a convenience to avoid having to connect signals to all objects managed by @manager. @@ -24553,46 +25616,46 @@ connect signals to all objects managed by @manager. The #GDBusObject on which an interface was removed. + filename="gio/gdbusobjectmanager.c" + line="135">The #GDBusObject on which an interface was removed. The #GDBusInterface that was removed. + filename="gio/gdbusobjectmanager.c" + line="136">The #GDBusInterface that was removed. Emitted when @object is added to @manager. + filename="gio/gdbusobjectmanager.c" + line="61">Emitted when @object is added to @manager. The #GDBusObject that was added. + filename="gio/gdbusobjectmanager.c" + line="64">The #GDBusObject that was added. Emitted when @object is removed from @manager. + filename="gio/gdbusobjectmanager.c" + line="82">Emitted when @object is removed from @manager. The #GDBusObject that was removed. + filename="gio/gdbusobjectmanager.c" + line="85">The #GDBusObject that was removed. @@ -24607,83 +25670,86 @@ connect signals to all objects managed by @manager. glib:get-type="g_dbus_object_manager_client_get_type" glib:type-struct="DBusObjectManagerClientClass"> #GDBusObjectManagerClient is used to create, monitor and delete object -proxies for remote objects exported by a #GDBusObjectManagerServer (or any -code implementing the + filename="gio/gdbusobjectmanagerclient.c" + line="45">`GDBusObjectManagerClient` is used to create, monitor and delete object +proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer] +(or any code implementing the [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface). Once an instance of this type has been created, you can connect to -the #GDBusObjectManager::object-added and -#GDBusObjectManager::object-removed signals and inspect the -#GDBusObjectProxy objects returned by -g_dbus_object_manager_get_objects(). +the [signal@Gio.DBusObjectManager::object-added] and +[signal@Gio.DBusObjectManager::object-removed signals] and inspect the +[class@Gio.DBusObjectProxy] objects returned by +[method@Gio.DBusObjectManager.get_objects]. -If the name for a #GDBusObjectManagerClient is not owned by anyone at +If the name for a `GDBusObjectManagerClient` is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be -disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START -flag. It's also worth noting that this only works if the name of +disabled using the `G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START` +flag. It’s also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this -case, #GDBusObjectManagerClient object construction still succeeds but +case, `GDBusObjectManagerClient` object construction still succeeds but there will be no object proxies -(e.g. g_dbus_object_manager_get_objects() returns the empty list) and -the #GDBusObjectManagerClient:name-owner property is %NULL. +(e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and +the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`. The owner of the requested name can come and go (for example -consider a system service being restarted) – #GDBusObjectManagerClient -handles this case too; simply connect to the #GObject::notify -signal to watch for changes on the #GDBusObjectManagerClient:name-owner -property. When the name owner vanishes, the behavior is that -#GDBusObjectManagerClient:name-owner is set to %NULL (this includes -emission of the #GObject::notify signal) and then -#GDBusObjectManager::object-removed signals are synthesized +consider a system service being restarted) – `GDBusObjectManagerClient` +handles this case too; simply connect to the [signal@GObject.Object::notify] +signal to watch for changes on the +[property@Gio.DBusObjectManagerClient:name-owner] property. When the name +owner vanishes, the behavior is that +[property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this +includes emission of the [signal@GObject.Object::notify] signal) and then +[signal@Gio.DBusObjectManager::object-removed] signals are synthesized for all currently existing object proxies. Since -#GDBusObjectManagerClient:name-owner is %NULL when this happens, you can -use this information to disambiguate a synthesized signal from a -genuine signal caused by object removal on the remote -#GDBusObjectManager. Similarly, when a new name owner appears, -#GDBusObjectManager::object-added signals are synthesized -while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all -object proxies have been added, the #GDBusObjectManagerClient:name-owner -is set to the new name owner (this includes emission of the -#GObject::notify signal). Furthermore, you are guaranteed that -#GDBusObjectManagerClient:name-owner will alternate between a name owner -(e.g. `:1.42`) and %NULL even in the case where +[property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this +happens, you can use this information to disambiguate a synthesized signal +from a genuine signal caused by object removal on the remote +[iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears, +[signal@Gio.DBusObjectManager::object-added] signals are synthesized +while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only +when all object proxies have been added, the +[property@Gio.DBusObjectManagerClient:name-owner] is set to the new name +owner (this includes emission of the [signal@GObject.Object::notify] signal). +Furthermore, you are guaranteed that +[property@Gio.DBusObjectManagerClient:name-owner] will alternate between a +name owner (e.g. `:1.42`) and `NULL` even in the case where the name of interest is atomically replaced -Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy -instances. All signals (including the -org.freedesktop.DBus.Properties::PropertiesChanged signal) -delivered to #GDBusProxy instances are guaranteed to originate +Ultimately, `GDBusObjectManagerClient` is used to obtain +[class@Gio.DBusProxy] instances. All signals (including the +`org.freedesktop.DBus.Properties::PropertiesChanged` signal) +delivered to [class@Gio.DBusProxy] instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the -"half the proxy is from the old owner and the other half is from -the new owner" problem cannot happen. +“half the proxy is from the old owner and the other half is from +the new owner” problem cannot happen. To avoid having the application connect to signals on the returned -#GDBusObjectProxy and #GDBusProxy objects, the -#GDBusObject::interface-added, -#GDBusObject::interface-removed, -#GDBusProxy::g-properties-changed and -#GDBusProxy::g-signal signals -are also emitted on the #GDBusObjectManagerClient instance managing these +[class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the +[signal@Gio.DBusObject::interface-added], +[signal@Gio.DBusObject::interface-removed], +[signal@Gio.DBusProxy::g-properties-changed] and +[signal@Gio.DBusProxy::g-signal] signals +are also emitted on the `GDBusObjectManagerClient` instance managing these objects. The signals emitted are -#GDBusObjectManager::interface-added, -#GDBusObjectManager::interface-removed, -#GDBusObjectManagerClient::interface-proxy-properties-changed and -#GDBusObjectManagerClient::interface-proxy-signal. +[signal@Gio.DBusObjectManager::interface-added], +[signal@Gio.DBusObjectManager::interface-removed], +[signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and +[signal@Gio.DBusObjectManagerClient::interface-proxy-signal]. Note that all callbacks and signals are emitted in the -[thread-default main context][g-main-context-push-thread-default] -that the #GDBusObjectManagerClient object was constructed -in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects -originating from the #GDBusObjectManagerClient object will be created in +thread-default main context (see +[method@GLib.MainContext.push_thread_default]) that the +`GDBusObjectManagerClient` object was constructed in. Additionally, the +[class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects +originating from the `GDBusObjectManagerClient` object will be created in the same context and, consequently, will deliver signals in the same main loop. - + @@ -24692,13 +25758,13 @@ same main loop. version="2.30" throws="1"> Finishes an operation started with g_dbus_object_manager_client_new(). - + filename="gio/gdbusobjectmanagerclient.c" + line="718">Finishes an operation started with g_dbus_object_manager_client_new(). + A + filename="gio/gdbusobjectmanagerclient.c" + line="725">A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). @@ -24706,8 +25772,8 @@ same main loop. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new(). + filename="gio/gdbusobjectmanagerclient.c" + line="720">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new(). @@ -24717,13 +25783,13 @@ same main loop. version="2.30" throws="1"> Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). - + filename="gio/gdbusobjectmanagerclient.c" + line="870">Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). + A + filename="gio/gdbusobjectmanagerclient.c" + line="877">A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). @@ -24731,8 +25797,8 @@ same main loop. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus(). + filename="gio/gdbusobjectmanagerclient.c" + line="872">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus(). @@ -24742,18 +25808,18 @@ same main loop. version="2.30" throws="1"> Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead + filename="gio/gdbusobjectmanagerclient.c" + line="754">Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead of a #GDBusConnection. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() for the asynchronous version. - + A + filename="gio/gdbusobjectmanagerclient.c" + line="773">A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). @@ -24761,27 +25827,27 @@ for the asynchronous version. A #GBusType. + filename="gio/gdbusobjectmanagerclient.c" + line="756">A #GBusType. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. + filename="gio/gdbusobjectmanagerclient.c" + line="757">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). + filename="gio/gdbusobjectmanagerclient.c" + line="758">The owner of the control object (unique or well-known name). The object path of the control object. + filename="gio/gdbusobjectmanagerclient.c" + line="759">The object path of the control object. closure="5" destroy="6"> A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. + filename="gio/gdbusobjectmanagerclient.c" + line="760">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. nullable="1" allow-none="1"> User data to pass to @get_proxy_type_func. + filename="gio/gdbusobjectmanagerclient.c" + line="761">User data to pass to @get_proxy_type_func. allow-none="1" scope="async"> Free function for @get_proxy_type_user_data or %NULL. + filename="gio/gdbusobjectmanagerclient.c" + line="762">Free function for @get_proxy_type_user_data or %NULL. nullable="1" allow-none="1"> A #GCancellable or %NULL + filename="gio/gdbusobjectmanagerclient.c" + line="763">A #GCancellable or %NULL @@ -24831,17 +25897,17 @@ for the asynchronous version. version="2.30" throws="1"> Creates a new #GDBusObjectManagerClient object. + filename="gio/gdbusobjectmanagerclient.c" + line="602">Creates a new #GDBusObjectManagerClient object. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new() for the asynchronous version. - + A + filename="gio/gdbusobjectmanagerclient.c" + line="620">A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). @@ -24849,14 +25915,14 @@ for the asynchronous version. A #GDBusConnection. + filename="gio/gdbusobjectmanagerclient.c" + line="604">A #GDBusConnection. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. + filename="gio/gdbusobjectmanagerclient.c" + line="605">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. @@ -24865,14 +25931,14 @@ for the asynchronous version. nullable="1" allow-none="1"> The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. + filename="gio/gdbusobjectmanagerclient.c" + line="606">The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. The object path of the control object. + filename="gio/gdbusobjectmanagerclient.c" + line="607">The object path of the control object. closure="5" destroy="6"> A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. + filename="gio/gdbusobjectmanagerclient.c" + line="608">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. nullable="1" allow-none="1"> User data to pass to @get_proxy_type_func. + filename="gio/gdbusobjectmanagerclient.c" + line="609">User data to pass to @get_proxy_type_func. allow-none="1" scope="async"> Free function for @get_proxy_type_user_data or %NULL. + filename="gio/gdbusobjectmanagerclient.c" + line="610">Free function for @get_proxy_type_user_data or %NULL. nullable="1" allow-none="1"> A #GCancellable or %NULL + filename="gio/gdbusobjectmanagerclient.c" + line="611">A #GCancellable or %NULL + version="2.30" + glib:finish-func="new_finish"> Asynchronously creates a new #GDBusObjectManagerClient object. + filename="gio/gdbusobjectmanagerclient.c" + line="662">Asynchronously creates a new #GDBusObjectManagerClient object. This is an asynchronous failable constructor. When the result is -ready, @callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. You can -then call g_dbus_object_manager_client_new_finish() to get the result. See +ready, @callback will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) +of the thread you are calling this method from. You can then call +g_dbus_object_manager_client_new_finish() to get the result. See g_dbus_object_manager_client_new_sync() for the synchronous version. - + A #GDBusConnection. + filename="gio/gdbusobjectmanagerclient.c" + line="664">A #GDBusConnection. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. + filename="gio/gdbusobjectmanagerclient.c" + line="665">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). + filename="gio/gdbusobjectmanagerclient.c" + line="666">The owner of the control object (unique or well-known name). The object path of the control object. + filename="gio/gdbusobjectmanagerclient.c" + line="667">The object path of the control object. closure="5" destroy="6"> A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. + filename="gio/gdbusobjectmanagerclient.c" + line="668">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. nullable="1" allow-none="1"> User data to pass to @get_proxy_type_func. + filename="gio/gdbusobjectmanagerclient.c" + line="669">User data to pass to @get_proxy_type_func. allow-none="1" scope="async"> Free function for @get_proxy_type_user_data or %NULL. + filename="gio/gdbusobjectmanagerclient.c" + line="670">Free function for @get_proxy_type_user_data or %NULL. nullable="1" allow-none="1"> A #GCancellable or %NULL + filename="gio/gdbusobjectmanagerclient.c" + line="671">A #GCancellable or %NULL scope="async" closure="9"> A #GAsyncReadyCallback to call when the request is satisfied. + filename="gio/gdbusobjectmanagerclient.c" + line="672">A #GAsyncReadyCallback to call when the request is satisfied. nullable="1" allow-none="1"> The data to pass to @callback. + filename="gio/gdbusobjectmanagerclient.c" + line="673">The data to pass to @callback. + version="2.30" + glib:finish-func="new_for_bus_finish"> Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a + filename="gio/gdbusobjectmanagerclient.c" + line="814">Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a #GDBusConnection. This is an asynchronous failable constructor. When the result is -ready, @callback will be invoked in the -[thread-default main loop][g-main-context-push-thread-default] +ready, @callback will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. - + A #GBusType. + filename="gio/gdbusobjectmanagerclient.c" + line="816">A #GBusType. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. + filename="gio/gdbusobjectmanagerclient.c" + line="817">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). + filename="gio/gdbusobjectmanagerclient.c" + line="818">The owner of the control object (unique or well-known name). The object path of the control object. + filename="gio/gdbusobjectmanagerclient.c" + line="819">The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. + filename="gio/gdbusobjectmanagerclient.c" + line="820">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. + filename="gio/gdbusobjectmanagerclient.c" + line="821">User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. + filename="gio/gdbusobjectmanagerclient.c" + line="822">Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL + filename="gio/gdbusobjectmanagerclient.c" + line="823">A #GCancellable or %NULL A #GAsyncReadyCallback to call when the request is satisfied. + filename="gio/gdbusobjectmanagerclient.c" + line="824">A #GAsyncReadyCallback to call when the request is satisfied. The data to pass to @callback. + filename="gio/gdbusobjectmanagerclient.c" + line="825">The data to pass to @callback. - + Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal. + @@ -25153,7 +26224,10 @@ g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. - + Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal. + @@ -25184,21 +26258,21 @@ g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. Gets the #GDBusConnection used by @manager. - + filename="gio/gdbusobjectmanagerclient.c" + line="906">Gets the #GDBusConnection used by @manager. + A #GDBusConnection object. Do not free, + filename="gio/gdbusobjectmanagerclient.c" + line="912">A #GDBusConnection object. Do not free, the object belongs to @manager. A #GDBusObjectManagerClient + filename="gio/gdbusobjectmanagerclient.c" + line="908">A #GDBusObjectManagerClient @@ -25209,13 +26283,13 @@ g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. Gets the flags that @manager was constructed with. - + filename="gio/gdbusobjectmanagerclient.c" + line="951">Gets the flags that @manager was constructed with. + Zero of more flags from the #GDBusObjectManagerClientFlags + filename="gio/gdbusobjectmanagerclient.c" + line="957">Zero of more flags from the #GDBusObjectManagerClientFlags enumeration. @@ -25223,8 +26297,8 @@ enumeration. A #GDBusObjectManagerClient + filename="gio/gdbusobjectmanagerclient.c" + line="953">A #GDBusObjectManagerClient @@ -25235,22 +26309,22 @@ enumeration. glib:get-property="name" version="2.30"> Gets the name that @manager is for, or %NULL if not a message bus + filename="gio/gdbusobjectmanagerclient.c" + line="928">Gets the name that @manager is for, or %NULL if not a message bus connection. - + A unique or well-known name. Do not free, the string + filename="gio/gdbusobjectmanagerclient.c" + line="935">A unique or well-known name. Do not free, the string belongs to @manager. A #GDBusObjectManagerClient + filename="gio/gdbusobjectmanagerclient.c" + line="930">A #GDBusObjectManagerClient @@ -25261,24 +26335,24 @@ belongs to @manager. glib:get-property="name-owner" version="2.30"> The unique name that owns the name that @manager is for or %NULL if + filename="gio/gdbusobjectmanagerclient.c" + line="973">The unique name that owns the name that @manager is for or %NULL if no-one currently owns that name. You can connect to the #GObject::notify signal to track changes to the #GDBusObjectManagerClient:name-owner property. - + The name owner or %NULL if no name owner + filename="gio/gdbusobjectmanagerclient.c" + line="982">The name owner or %NULL if no name owner exists. Free with g_free(). A #GDBusObjectManagerClient. + filename="gio/gdbusobjectmanagerclient.c" + line="975">A #GDBusObjectManagerClient. @@ -25292,8 +26366,8 @@ exists. Free with g_free(). transfer-ownership="none" default-value="G_BUS_TYPE_NONE"> If this property is not %G_BUS_TYPE_NONE, then + filename="gio/gdbusobjectmanagerclient.c" + line="373">If this property is not %G_BUS_TYPE_NONE, then #GDBusObjectManagerClient:connection must be %NULL and will be set to the #GDBusConnection obtained by calling g_bus_get() with the value of this property. @@ -25306,8 +26380,8 @@ of this property. transfer-ownership="none" getter="get_connection"> The #GDBusConnection to use. + filename="gio/gdbusobjectmanagerclient.c" + line="357">The #GDBusConnection to use. getter="get_flags" default-value="G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE"> Flags from the #GDBusObjectManagerClientFlags enumeration. + filename="gio/gdbusobjectmanagerclient.c" + line="394">Flags from the #GDBusObjectManagerClientFlags enumeration. construct-only="1" transfer-ownership="none"> A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data. + filename="gio/gdbusobjectmanagerclient.c" + line="492">A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data. construct-only="1" transfer-ownership="none"> The #GDBusProxyTypeFunc to use when determining what #GType to + filename="gio/gdbusobjectmanagerclient.c" + line="461">The #GDBusProxyTypeFunc to use when determining what #GType to use for interface proxies or %NULL. @@ -25349,8 +26423,8 @@ use for interface proxies or %NULL. construct-only="1" transfer-ownership="none"> The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. + filename="gio/gdbusobjectmanagerclient.c" + line="477">The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. getter="get_name" default-value="NULL"> The well-known name or unique name that the manager is for. + filename="gio/gdbusobjectmanagerclient.c" + line="429">The well-known name or unique name that the manager is for. getter="get_name_owner" default-value="NULL"> The unique name that owns #GDBusObjectManagerClient:name or %NULL if + filename="gio/gdbusobjectmanagerclient.c" + line="445">The unique name that owns #GDBusObjectManagerClient:name or %NULL if no-one is currently owning the name. Connect to the #GObject::notify signal to track changes to this property. @@ -25384,8 +26458,8 @@ no-one is currently owning the name. Connect to the transfer-ownership="none" default-value="NULL"> The object path the manager is for. + filename="gio/gdbusobjectmanagerclient.c" + line="413">The object path the manager is for. @@ -25399,8 +26473,8 @@ no-one is currently owning the name. Connect to the when="last" version="2.30"> Emitted when one or more D-Bus properties on proxy changes. The + filename="gio/gdbusobjectmanagerclient.c" + line="546">Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both @changed_properties and @invalidated_properties are guaranteed to never be %NULL (either may be empty though). @@ -25408,8 +26482,8 @@ guaranteed to never be %NULL (either may be empty though). This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by @manager. -This signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] +This signal is emitted in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) that @manager was constructed in. @@ -25417,26 +26491,26 @@ that @manager was constructed in. The #GDBusObjectProxy on which an interface has properties that are changing. + filename="gio/gdbusobjectmanagerclient.c" + line="549">The #GDBusObjectProxy on which an interface has properties that are changing. The #GDBusProxy that has properties that are changing. + filename="gio/gdbusobjectmanagerclient.c" + line="550">The #GDBusProxy that has properties that are changing. A #GVariant containing the properties that changed (type: `a{sv}`). + filename="gio/gdbusobjectmanagerclient.c" + line="551">A #GVariant containing the properties that changed (type: `a{sv}`). A %NULL terminated + filename="gio/gdbusobjectmanagerclient.c" + line="552">A %NULL terminated array of properties that were invalidated. @@ -25446,14 +26520,14 @@ that @manager was constructed in. Emitted when a D-Bus signal is received on @interface_proxy. + filename="gio/gdbusobjectmanagerclient.c" + line="507">Emitted when a D-Bus signal is received on @interface_proxy. This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by @manager. -This signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] +This signal is emitted in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) that @manager was constructed in. @@ -25461,32 +26535,32 @@ that @manager was constructed in. The #GDBusObjectProxy on which an interface is emitting a D-Bus signal. + filename="gio/gdbusobjectmanagerclient.c" + line="510">The #GDBusObjectProxy on which an interface is emitting a D-Bus signal. The #GDBusProxy that is emitting a D-Bus signal. + filename="gio/gdbusobjectmanagerclient.c" + line="511">The #GDBusProxy that is emitting a D-Bus signal. The sender of the signal or NULL if the connection is not a bus connection. + filename="gio/gdbusobjectmanagerclient.c" + line="512">The sender of the signal or NULL if the connection is not a bus connection. The signal name. + filename="gio/gdbusobjectmanagerclient.c" + line="513">The signal name. A #GVariant tuple with parameters for the signal. + filename="gio/gdbusobjectmanagerclient.c" + line="514">A #GVariant tuple with parameters for the signal. @@ -25497,18 +26571,22 @@ that @manager was constructed in. glib:is-gtype-struct-for="DBusObjectManagerClient" version="2.30"> Class structure for #GDBusObjectManagerClient. - + filename="gio/gdbusobjectmanagerclient.h" + line="47">Class structure for #GDBusObjectManagerClient. + The parent class. + filename="gio/gdbusobjectmanagerclient.h" + line="49">The parent class. + Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal. - + @@ -25536,8 +26614,12 @@ that @manager was constructed in. + Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal. - + @@ -25573,16 +26655,16 @@ that @manager was constructed in. glib:get-type="g_dbus_object_manager_client_flags_get_type" c:type="GDBusObjectManagerClientFlags"> Flags used when constructing a #GDBusObjectManagerClient. + filename="gio/gioenums.h" + line="1822">Flags used when constructing a #GDBusObjectManagerClient. No flags set. + filename="gio/gioenums.h" + line="1824">No flags set. glib:nick="do-not-auto-start" glib:name="G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START"> If not set and the + filename="gio/gioenums.h" + line="1825">If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in managers for well-known names. @@ -25601,48 +26683,54 @@ that @manager was constructed in. c:type="GDBusObjectManagerClientPrivate" disguised="1" opaque="1"> - + Base type for D-Bus object managers. - + The parent interface. + Virtual function for g_dbus_object_manager_get_object_path(). - + A string owned by @manager. Do not free. + filename="gio/gdbusobjectmanager.c" + line="171">A string owned by @manager. Do not free. A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="167">A #GDBusObjectManager. + Virtual function for g_dbus_object_manager_get_objects(). - + A list of + filename="gio/gdbusobjectmanager.c" + line="188">A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). @@ -25653,74 +26741,83 @@ that @manager was constructed in. A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="184">A #GDBusObjectManager. + Virtual function for g_dbus_object_manager_get_object(). - + A #GDBusObject or %NULL. Free with + filename="gio/gdbusobjectmanager.c" + line="209">A #GDBusObject or %NULL. Free with g_object_unref(). A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="204">A #GDBusObjectManager. Object path to look up. + filename="gio/gdbusobjectmanager.c" + line="205">Object path to look up. + Virtual function for g_dbus_object_manager_get_interface(). - + A #GDBusInterface instance or %NULL. Free + filename="gio/gdbusobjectmanager.c" + line="232">A #GDBusInterface instance or %NULL. Free with g_object_unref(). A #GDBusObjectManager. + filename="gio/gdbusobjectmanager.c" + line="225">A #GDBusObjectManager. Object path to look up. + filename="gio/gdbusobjectmanager.c" + line="226">Object path to look up. D-Bus interface name to look up. + filename="gio/gdbusobjectmanager.c" + line="227">D-Bus interface name to look up. + Signal handler for the #GDBusObjectManager::object-added signal. - + @@ -25735,8 +26832,11 @@ that @manager was constructed in. + Signal handler for the #GDBusObjectManager::object-removed signal. - + @@ -25751,8 +26851,11 @@ that @manager was constructed in. + Signal handler for the #GDBusObjectManager::interface-added signal. - + @@ -25770,8 +26873,11 @@ that @manager was constructed in. + Signal handler for the #GDBusObjectManager::interface-removed signal. - + @@ -25798,10 +26904,10 @@ that @manager was constructed in. glib:get-type="g_dbus_object_manager_server_get_type" glib:type-struct="DBusObjectManagerServerClass"> #GDBusObjectManagerServer is used to export #GDBusObject instances using -the standardized -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) + filename="gio/gdbusobjectmanagerserver.c" + line="41">`GDBusObjectManagerServer` is used to export [iface@Gio.DBusObject] instances +using the standardized +[`org.freedesktop.DBus.ObjectManager`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. For example, remote D-Bus clients can get all objects and properties in a single call. Additionally, any change in the object hierarchy is broadcast using signals. This means that D-Bus @@ -25817,37 +26923,36 @@ below (to allow for multiple object managers in a service). It is supported, but not recommended, to export an object manager at the root path, `/`. -See #GDBusObjectManagerClient for the client-side code that is -intended to be used with #GDBusObjectManagerServer or any D-Bus -object implementing the org.freedesktop.DBus.ObjectManager -interface. - +See [class@Gio.DBusObjectManagerClient] for the client-side code that is +intended to be used with `GDBusObjectManagerServer` or any D-Bus +object implementing the `org.freedesktop.DBus.ObjectManager` interface. + Creates a new #GDBusObjectManagerServer object. + filename="gio/gdbusobjectmanagerserver.c" + line="248">Creates a new #GDBusObjectManagerServer object. The returned server isn't yet exported on any connection. To do so, use g_dbus_object_manager_server_set_connection(). Normally you want to export all of your objects before doing so to avoid [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) signals being emitted. - + A #GDBusObjectManagerServer object. Free with g_object_unref(). + filename="gio/gdbusobjectmanagerserver.c" + line="260">A #GDBusObjectManagerServer object. Free with g_object_unref(). The object path to export the manager object at. + filename="gio/gdbusobjectmanagerserver.c" + line="250">The object path to export the manager object at. @@ -25856,8 +26961,8 @@ signals being emitted. c:identifier="g_dbus_object_manager_server_export" version="2.30"> Exports @object on @manager. + filename="gio/gdbusobjectmanagerserver.c" + line="550">Exports @object on @manager. If there is already a #GDBusObject exported at the object path, then the old object is removed. @@ -25867,22 +26972,22 @@ object path for @manager. Note that @manager will take a reference on @object for as long as it is exported. - + A #GDBusObjectManagerServer. + filename="gio/gdbusobjectmanagerserver.c" + line="552">A #GDBusObjectManagerServer. A #GDBusObjectSkeleton. + filename="gio/gdbusobjectmanagerserver.c" + line="553">A #GDBusObjectSkeleton. @@ -25891,27 +26996,27 @@ it is exported. c:identifier="g_dbus_object_manager_server_export_uniquely" version="2.30"> Like g_dbus_object_manager_server_export() but appends a string of + filename="gio/gdbusobjectmanagerserver.c" + line="579">Like g_dbus_object_manager_server_export() but appends a string of the form _N (with N being a natural number) to @object's object path if an object with the given path already exists. As such, the #GDBusObjectProxy:g-object-path property of @object may be modified. - + A #GDBusObjectManagerServer. + filename="gio/gdbusobjectmanagerserver.c" + line="581">A #GDBusObjectManagerServer. An object. + filename="gio/gdbusobjectmanagerserver.c" + line="582">An object. @@ -25921,13 +27026,13 @@ if an object with the given path already exists. As such, the glib:get-property="connection" version="2.30"> Gets the #GDBusConnection used by @manager. - + filename="gio/gdbusobjectmanagerserver.c" + line="314">Gets the #GDBusConnection used by @manager. + A #GDBusConnection object or %NULL if + filename="gio/gdbusobjectmanagerserver.c" + line="320">A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref(). @@ -25935,8 +27040,8 @@ if an object with the given path already exists. As such, the A #GDBusObjectManagerServer + filename="gio/gdbusobjectmanagerserver.c" + line="316">A #GDBusObjectManagerServer @@ -25946,27 +27051,27 @@ if an object with the given path already exists. As such, the c:identifier="g_dbus_object_manager_server_is_exported" version="2.34"> Returns whether @object is currently exported on @manager. - + filename="gio/gdbusobjectmanagerserver.c" + line="635">Returns whether @object is currently exported on @manager. + %TRUE if @object is exported + filename="gio/gdbusobjectmanagerserver.c" + line="642">%TRUE if @object is exported A #GDBusObjectManagerServer. + filename="gio/gdbusobjectmanagerserver.c" + line="637">A #GDBusObjectManagerServer. An object. + filename="gio/gdbusobjectmanagerserver.c" + line="638">An object. @@ -25975,18 +27080,18 @@ if an object with the given path already exists. As such, the c:identifier="g_dbus_object_manager_server_set_connection" glib:set-property="connection"> Exports all objects managed by @manager on @connection. If + filename="gio/gdbusobjectmanagerserver.c" + line="273">Exports all objects managed by @manager on @connection. If @connection is %NULL, stops exporting objects. - + A #GDBusObjectManagerServer. + filename="gio/gdbusobjectmanagerserver.c" + line="275">A #GDBusObjectManagerServer. @@ -25995,8 +27100,8 @@ if an object with the given path already exists. As such, the nullable="1" allow-none="1"> A #GDBusConnection or %NULL. + filename="gio/gdbusobjectmanagerserver.c" + line="276">A #GDBusConnection or %NULL. @@ -26005,31 +27110,31 @@ if an object with the given path already exists. As such, the c:identifier="g_dbus_object_manager_server_unexport" version="2.30"> If @manager has an object at @path, removes the object. Otherwise + filename="gio/gdbusobjectmanagerserver.c" + line="707">If @manager has an object at @path, removes the object. Otherwise does nothing. Note that @object_path must be in the hierarchy rooted by the object path for @manager. - + %TRUE if object at @object_path was removed, %FALSE otherwise. + filename="gio/gdbusobjectmanagerserver.c" + line="718">%TRUE if object at @object_path was removed, %FALSE otherwise. A #GDBusObjectManagerServer. + filename="gio/gdbusobjectmanagerserver.c" + line="709">A #GDBusObjectManagerServer. An object path. + filename="gio/gdbusobjectmanagerserver.c" + line="710">An object path. @@ -26041,8 +27146,8 @@ object path for @manager. setter="set_connection" getter="get_connection"> The #GDBusConnection to export objects on. + filename="gio/gdbusobjectmanagerserver.c" + line="205">The #GDBusConnection to export objects on. transfer-ownership="none" default-value="NULL"> The object path to register the manager object at. + filename="gio/gdbusobjectmanagerserver.c" + line="220">The object path to register the manager object at. @@ -26069,13 +27174,13 @@ object path for @manager. glib:is-gtype-struct-for="DBusObjectManagerServer" version="2.30"> Class structure for #GDBusObjectManagerServer. - + filename="gio/gdbusobjectmanagerserver.h" + line="47">Class structure for #GDBusObjectManagerServer. + The parent class. + filename="gio/gdbusobjectmanagerserver.h" + line="49">The parent class. @@ -26088,7 +27193,7 @@ object path for @manager. c:type="GDBusObjectManagerServerPrivate" disguised="1" opaque="1"> - + glib:get-type="g_dbus_object_proxy_get_type" glib:type-struct="DBusObjectProxyClass"> A #GDBusObjectProxy is an object used to represent a remote object -with one or more D-Bus interfaces. Normally, you don't instantiate -a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient + filename="gio/gdbusobjectproxy.c" + line="34">A `GDBusObjectProxy` is an object used to represent a remote object +with one or more D-Bus interfaces. Normally, you don’t instantiate +a `GDBusObjectProxy` yourself — typically [class@Gio.DBusObjectManagerClient] is used to obtain it. - + Creates a new #GDBusObjectProxy for the given connection and + filename="gio/gdbusobjectproxy.c" + line="260">Creates a new #GDBusObjectProxy for the given connection and object path. - + a new #GDBusObjectProxy + filename="gio/gdbusobjectproxy.c" + line="268">a new #GDBusObjectProxy a #GDBusConnection + filename="gio/gdbusobjectproxy.c" + line="262">a #GDBusConnection the object path + filename="gio/gdbusobjectproxy.c" + line="263">the object path @@ -26139,21 +27244,21 @@ object path. c:identifier="g_dbus_object_proxy_get_connection" version="2.30"> Gets the connection that @proxy is for. - + filename="gio/gdbusobjectproxy.c" + line="199">Gets the connection that @proxy is for. + A #GDBusConnection. Do not free, the + filename="gio/gdbusobjectproxy.c" + line="205">A #GDBusConnection. Do not free, the object is owned by @proxy. a #GDBusObjectProxy + filename="gio/gdbusobjectproxy.c" + line="201">a #GDBusObjectProxy @@ -26164,8 +27269,8 @@ object path. construct-only="1" transfer-ownership="none"> The connection of the proxy. + filename="gio/gdbusobjectproxy.c" + line="161">The connection of the proxy. transfer-ownership="none" default-value="NULL"> The object path of the proxy. + filename="gio/gdbusobjectproxy.c" + line="146">The object path of the proxy. @@ -26191,13 +27296,13 @@ object path. glib:is-gtype-struct-for="DBusObjectProxy" version="2.30"> Class structure for #GDBusObjectProxy. - + filename="gio/gdbusobjectproxy.h" + line="47">Class structure for #GDBusObjectProxy. + The parent class. + filename="gio/gdbusobjectproxy.h" + line="49">The parent class. @@ -26210,7 +27315,7 @@ object path. c:type="GDBusObjectProxyPrivate" disguised="1" opaque="1"> - + glib:get-type="g_dbus_object_skeleton_get_type" glib:type-struct="DBusObjectSkeletonClass"> A #GDBusObjectSkeleton instance is essentially a group of D-Bus + filename="gio/gdbusobjectskeleton.c" + line="36">A `GDBusObjectSkeleton` instance is essentially a group of D-Bus interfaces. The set of exported interfaces on the object may be dynamic and change at runtime. -This type is intended to be used with #GDBusObjectManager. - +This type is intended to be used with [iface@Gio.DBusObjectManager]. + Creates a new #GDBusObjectSkeleton. - + filename="gio/gdbusobjectskeleton.c" + line="211">Creates a new #GDBusObjectSkeleton. + A #GDBusObjectSkeleton. Free with g_object_unref(). + filename="gio/gdbusobjectskeleton.c" + line="217">A #GDBusObjectSkeleton. Free with g_object_unref(). An object path. + filename="gio/gdbusobjectskeleton.c" + line="213">An object path. - + Signal class handler for the #GDBusObjectSkeleton::authorize-method signal. + @@ -26273,29 +27381,29 @@ This type is intended to be used with #GDBusObjectManager. c:identifier="g_dbus_object_skeleton_add_interface" version="2.30"> Adds @interface_ to @object. + filename="gio/gdbusobjectskeleton.c" + line="271">Adds @interface_ to @object. If @object already contains a #GDBusInterfaceSkeleton with the same interface name, it is removed before @interface_ is added. Note that @object takes its own reference on @interface_ and holds it until removed. - + A #GDBusObjectSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="273">A #GDBusObjectSkeleton. A #GDBusInterfaceSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="274">A #GDBusInterfaceSkeleton. @@ -26305,19 +27413,19 @@ it until removed. c:identifier="g_dbus_object_skeleton_flush" version="2.30"> This method simply calls g_dbus_interface_skeleton_flush() on all + filename="gio/gdbusobjectskeleton.c" + line="461">This method simply calls g_dbus_interface_skeleton_flush() on all interfaces belonging to @object. See that method for when flushing is useful. - + A #GDBusObjectSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="463">A #GDBusObjectSkeleton. @@ -26326,23 +27434,23 @@ is useful. c:identifier="g_dbus_object_skeleton_remove_interface" version="2.30"> Removes @interface_ from @object. - + filename="gio/gdbusobjectskeleton.c" + line="329">Removes @interface_ from @object. + A #GDBusObjectSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="331">A #GDBusObjectSkeleton. A #GDBusInterfaceSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="332">A #GDBusInterfaceSkeleton. @@ -26352,26 +27460,26 @@ is useful. c:identifier="g_dbus_object_skeleton_remove_interface_by_name" version="2.30"> Removes the #GDBusInterface with @interface_name from @object. + filename="gio/gdbusobjectskeleton.c" + line="385">Removes the #GDBusInterface with @interface_name from @object. If no D-Bus interface of the given interface exists, this function does nothing. - + A #GDBusObjectSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="387">A #GDBusObjectSkeleton. A D-Bus interface name. + filename="gio/gdbusobjectskeleton.c" + line="388">A D-Bus interface name. @@ -26380,23 +27488,23 @@ does nothing. c:identifier="g_dbus_object_skeleton_set_object_path" version="2.30"> Sets the object path for @object. - + filename="gio/gdbusobjectskeleton.c" + line="230">Sets the object path for @object. + A #GDBusObjectSkeleton. + filename="gio/gdbusobjectskeleton.c" + line="232">A #GDBusObjectSkeleton. A valid D-Bus object path. + filename="gio/gdbusobjectskeleton.c" + line="233">A valid D-Bus object path. @@ -26408,8 +27516,8 @@ does nothing. transfer-ownership="none" default-value="NULL"> The object path where the object is exported. + filename="gio/gdbusobjectskeleton.c" + line="151">The object path where the object is exported. @@ -26421,8 +27529,8 @@ does nothing. Emitted when a method is invoked by a remote caller and used to + filename="gio/gdbusobjectskeleton.c" + line="167">Emitted when a method is invoked by a remote caller and used to determine if the method call is authorized. This signal is like #GDBusInterfaceSkeleton's @@ -26432,21 +27540,21 @@ except that it is for the enclosing object. The default class handler just returns %TRUE. %TRUE if the call is authorized, %FALSE otherwise. + filename="gio/gdbusobjectskeleton.c" + line="182">%TRUE if the call is authorized, %FALSE otherwise. The #GDBusInterfaceSkeleton that @invocation is for. + filename="gio/gdbusobjectskeleton.c" + line="170">The #GDBusInterfaceSkeleton that @invocation is for. A #GDBusMethodInvocation. + filename="gio/gdbusobjectskeleton.c" + line="171">A #GDBusMethodInvocation. @@ -26457,18 +27565,21 @@ The default class handler just returns %TRUE. glib:is-gtype-struct-for="DBusObjectSkeleton" version="2.30"> Class structure for #GDBusObjectSkeleton. - + filename="gio/gdbusobjectskeleton.h" + line="47">Class structure for #GDBusObjectSkeleton. + The parent class. + filename="gio/gdbusobjectskeleton.h" + line="49">The parent class. + Signal class handler for the #GDBusObjectSkeleton::authorize-method signal. - + @@ -26497,7 +27608,7 @@ The default class handler just returns %TRUE. c:type="GDBusObjectSkeletonPrivate" disguised="1" opaque="1"> - + glib:get-type="g_dbus_property_info_get_type" c:symbol-prefix="dbus_property_info"> Information about a D-Bus property on a D-Bus interface. - + The reference count or -1 if statically allocated. The name of the D-Bus property, e.g. "SupportedFilesystems". The D-Bus signature of the property (a single complete type). Access control flags for the property. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -26545,21 +27656,21 @@ The default class handler just returns %TRUE. c:identifier="g_dbus_property_info_ref" version="2.26"> If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="162">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="169">The same @info. A #GDBusPropertyInfo + filename="gio/gdbusintrospection.c" + line="164">A #GDBusPropertyInfo @@ -26568,19 +27679,19 @@ the reference count. c:identifier="g_dbus_property_info_unref" version="2.26"> If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="333">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusPropertyInfo. + filename="gio/gdbusintrospection.c" + line="335">A #GDBusPropertyInfo. @@ -26592,16 +27703,16 @@ the memory used is freed. glib:get-type="g_dbus_property_info_flags_get_type" c:type="GDBusPropertyInfoFlags"> Flags describing the access control of a D-Bus property. + filename="gio/gioenums.h" + line="1356">Flags describing the access control of a D-Bus property. No flags set. + filename="gio/gioenums.h" + line="1358">No flags set. glib:nick="readable" glib:name="G_DBUS_PROPERTY_INFO_FLAGS_READABLE"> Property is readable. + filename="gio/gioenums.h" + line="1359">Property is readable. glib:nick="writable" glib:name="G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE"> Property is writable. + filename="gio/gioenums.h" + line="1360">Property is writable. glib:get-type="g_dbus_proxy_get_type" glib:type-struct="DBusProxyClass"> #GDBusProxy is a base class used for proxies to access a D-Bus -interface on a remote object. A #GDBusProxy can be constructed for + filename="gio/gdbusproxy.c" + line="49">`GDBusProxy` is a base class used for proxies to access a D-Bus +interface on a remote object. A `GDBusProxy` can be constructed for both well-known and unique names. -By default, #GDBusProxy will cache all properties (and listen to +By default, `GDBusProxy` will cache all properties (and listen to changes) of the remote object, and proxy all signals that get emitted. This behaviour can be changed by passing suitable -#GDBusProxyFlags when the proxy is created. If the proxy is for a +[flags@Gio.DBusProxyFlags] when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears. -The unique name owner of the proxy's name is tracked and can be read from -#GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to -get notified of changes. Additionally, only signals and property -changes emitted from the current name owner are considered and -calls are always sent to the current name owner. This avoids a -number of race conditions when the name is lost by one owner and -claimed by another. However, if no name owner currently exists, +The unique name owner of the proxy’s name is tracked and can be read from +[property@Gio.DBusProxy:g-name-owner]. Connect to the +[signal@GObject.Object::notify] signal to get notified of changes. +Additionally, only signals and property changes emitted from the current name +owner are considered and calls are always sent to the current name owner. +This avoids a number of race conditions when the name is lost by one owner +and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless -%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). +`G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set). If the proxy is for a stateless D-Bus service, where the name owner may -be started and stopped between calls, the #GDBusProxy:g-name-owner tracking -of #GDBusProxy will cause the proxy to drop signal and property changes from -the service after it has restarted for the first time. When interacting -with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus -method calls and signal connections. - -The generic #GDBusProxy::g-properties-changed and -#GDBusProxy::g-signal signals are not very convenient to work with. -Therefore, the recommended way of working with proxies is to subclass -#GDBusProxy, and have more natural properties and signals in your derived -class. This [example][gdbus-example-gdbus-codegen] shows how this can -easily be done using the [gdbus-codegen][gdbus-codegen] tool. - -A #GDBusProxy instance can be used from multiple threads but note -that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed -and #GObject::notify) are emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread where the instance was constructed. - +be started and stopped between calls, the +[property@Gio.DBusProxy:g-name-owner] tracking of `GDBusProxy` will cause the +proxy to drop signal and property changes from the service after it has +restarted for the first time. When interacting with a stateless D-Bus +service, do not use `GDBusProxy` — use direct D-Bus method calls and signal +connections. + +The generic [signal@Gio.DBusProxy::g-properties-changed] and +[signal@Gio.DBusProxy::g-signal] signals are not very convenient to work +with. Therefore, the recommended way of working with proxies is to subclass +`GDBusProxy`, and have more natural properties and signals in your derived +class. This [example](migrating-gdbus.html#using-gdbus-codegen) shows how +this can easily be done using the [`gdbus-codegen`](gdbus-codegen.html) tool. + +A `GDBusProxy` instance can be used from multiple threads but note +that all signals (e.g. [signal@Gio.DBusProxy::g-signal], +[signal@Gio.DBusProxy::g-properties-changed] and +[signal@GObject.Object::notify]) are emitted in the thread-default main +context (see [method@GLib.MainContext.push_thread_default]) of the thread +where the instance was constructed. + + +## A watch proxy example An example using a proxy for a well-known name can be found in -[gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c) - +[`gdbus-example-watch-proxy.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c). + @@ -26685,21 +27800,21 @@ An example using a proxy for a well-known name can be found in version="2.26" throws="1"> Finishes creating a #GDBusProxy. - + filename="gio/gdbusproxy.c" + line="1999">Finishes creating a #GDBusProxy. + A #GDBusProxy or %NULL if @error is set. + filename="gio/gdbusproxy.c" + line="2006">A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). + filename="gio/gdbusproxy.c" + line="2001">A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). @@ -26709,21 +27824,21 @@ An example using a proxy for a well-known name can be found in version="2.26" throws="1"> Finishes creating a #GDBusProxy. - + filename="gio/gdbusproxy.c" + line="2156">Finishes creating a #GDBusProxy. + A #GDBusProxy or %NULL if @error is set. + filename="gio/gdbusproxy.c" + line="2163">A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). + filename="gio/gdbusproxy.c" + line="2158">A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). @@ -26733,29 +27848,29 @@ An example using a proxy for a well-known name can be found in version="2.26" throws="1"> Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. + filename="gio/gdbusproxy.c" + line="2175">Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - +#GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. + A #GDBusProxy or %NULL if error is set. + filename="gio/gdbusproxy.c" + line="2191">A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). A #GBusType. + filename="gio/gdbusproxy.c" + line="2177">A #GBusType. Flags used when constructing the proxy. + filename="gio/gdbusproxy.c" + line="2178">Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface + filename="gio/gdbusproxy.c" + line="2179">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique). + filename="gio/gdbusproxy.c" + line="2181">A bus name (well-known or unique). An object path. + filename="gio/gdbusproxy.c" + line="2182">An object path. A D-Bus interface name. + filename="gio/gdbusproxy.c" + line="2183">A D-Bus interface name. A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="2184">A #GCancellable or %NULL. @@ -26802,8 +27917,8 @@ An example using a proxy for a well-known name can be found in version="2.26" throws="1"> Creates a proxy for accessing @interface_name on the remote object + filename="gio/gdbusproxy.c" + line="2032">Creates a proxy for accessing @interface_name on the remote object at @object_path owned by @name at @connection and synchronously loads D-Bus properties unless the %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. @@ -26824,26 +27939,26 @@ will be requested to launch a name owner for the name. This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version. -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - +#GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. + A #GDBusProxy or %NULL if error is set. + filename="gio/gdbusproxy.c" + line="2066">A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). A #GDBusConnection. + filename="gio/gdbusproxy.c" + line="2034">A #GDBusConnection. Flags used when constructing the proxy. + filename="gio/gdbusproxy.c" + line="2035">Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + filename="gio/gdbusproxy.c" + line="2036">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + filename="gio/gdbusproxy.c" + line="2037">A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. An object path. + filename="gio/gdbusproxy.c" + line="2038">An object path. A D-Bus interface name. + filename="gio/gdbusproxy.c" + line="2039">A D-Bus interface name. A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="2040">A #GCancellable or %NULL. - + Creates a proxy for accessing @interface_name on the remote object + filename="gio/gdbusproxy.c" + line="1925">Creates a proxy for accessing @interface_name on the remote object at @object_path owned by @name at @connection and asynchronously loads D-Bus properties unless the %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to @@ -26916,22 +28034,22 @@ g_dbus_proxy_new_finish() to get the result. See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - +#GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. + A #GDBusConnection. + filename="gio/gdbusproxy.c" + line="1927">A #GDBusConnection. Flags used when constructing the proxy. + filename="gio/gdbusproxy.c" + line="1928">Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + filename="gio/gdbusproxy.c" + line="1929">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + filename="gio/gdbusproxy.c" + line="1930">A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. An object path. + filename="gio/gdbusproxy.c" + line="1931">An object path. A D-Bus interface name. + filename="gio/gdbusproxy.c" + line="1932">A D-Bus interface name. A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="1933">A #GCancellable or %NULL. Callback function to invoke when the proxy is ready. + filename="gio/gdbusproxy.c" + line="1934">Callback function to invoke when the proxy is ready. User data to pass to @callback. + filename="gio/gdbusproxy.c" + line="1935">User data to pass to @callback. + version="2.26" + glib:finish-func="new_for_bus_finish"> Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. + filename="gio/gdbusproxy.c" + line="2107">Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - +#GDBusProxy is used in this [example][class@Gio.DBusProxy#a-watch-proxy-example]. + A #GBusType. + filename="gio/gdbusproxy.c" + line="2109">A #GBusType. Flags used when constructing the proxy. + filename="gio/gdbusproxy.c" + line="2110">Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + filename="gio/gdbusproxy.c" + line="2111">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique). + filename="gio/gdbusproxy.c" + line="2112">A bus name (well-known or unique). An object path. + filename="gio/gdbusproxy.c" + line="2113">An object path. A D-Bus interface name. + filename="gio/gdbusproxy.c" + line="2114">A D-Bus interface name. A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="2115">A #GCancellable or %NULL. Callback function to invoke when the proxy is ready. + filename="gio/gdbusproxy.c" + line="2116">Callback function to invoke when the proxy is ready. User data to pass to @callback. + filename="gio/gdbusproxy.c" + line="2117">User data to pass to @callback. - + Signal class handler for the #GDBusProxy::g-properties-changed signal. + @@ -27096,7 +28218,10 @@ See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. - + Signal class handler for the #GDBusProxy::g-signal signal. + @@ -27115,10 +28240,14 @@ See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. - + Asynchronously invokes the @method_name method on @proxy. + filename="gio/gdbusproxy.c" + line="2873">Asynchronously invokes the @method_name method on @proxy. If @method_name contains any dots, then @name is split into interface and method name parts. This allows using @proxy for invoking methods on @@ -27151,8 +28280,8 @@ If @proxy has an expected interface (see then the return value is checked against the return type. This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +@callback will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous @@ -27160,21 +28289,21 @@ version of this method. If @callback is %NULL then the D-Bus method call message will be sent with the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. - + A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2875">A #GDBusProxy. Name of method to invoke. + filename="gio/gdbusproxy.c" + line="2876">Name of method to invoke. nullable="1" allow-none="1"> A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + filename="gio/gdbusproxy.c" + line="2877">A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. + filename="gio/gdbusproxy.c" + line="2878">Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning + filename="gio/gdbusproxy.c" + line="2879">The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. @@ -27204,8 +28333,8 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="2881">A #GCancellable or %NULL. scope="async" closure="6"> A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + filename="gio/gdbusproxy.c" + line="2882">A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. @@ -27225,8 +28354,8 @@ care about the result of the method invocation. nullable="1" allow-none="1"> The data to pass to @callback. + filename="gio/gdbusproxy.c" + line="2884">The data to pass to @callback. @@ -27236,27 +28365,27 @@ care about the result of the method invocation. version="2.26" throws="1"> Finishes an operation started with g_dbus_proxy_call(). - + filename="gio/gdbusproxy.c" + line="2944">Finishes an operation started with g_dbus_proxy_call(). + %NULL if @error is set. Otherwise a #GVariant tuple with + filename="gio/gdbusproxy.c" + line="2952">%NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2946">A #GDBusProxy. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). + filename="gio/gdbusproxy.c" + line="2947">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). @@ -27264,10 +28393,11 @@ return values. Free with g_variant_unref(). + throws="1" + glib:async-func="call"> Synchronously invokes the @method_name method on @proxy. + filename="gio/gdbusproxy.c" + line="2965">Synchronously invokes the @method_name method on @proxy. If @method_name contains any dots, then @name is split into interface and method name parts. This allows using @proxy for invoking methods on @@ -27301,25 +28431,25 @@ method. If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @method_name is referenced by it, then the return value is checked against the return type. - + %NULL if @error is set. Otherwise a #GVariant tuple with + filename="gio/gdbusproxy.c" + line="3012">%NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2967">A #GDBusProxy. Name of method to invoke. + filename="gio/gdbusproxy.c" + line="2968">Name of method to invoke. nullable="1" allow-none="1"> A #GVariant tuple with parameters for the signal + filename="gio/gdbusproxy.c" + line="2969">A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. + filename="gio/gdbusproxy.c" + line="2971">Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning + filename="gio/gdbusproxy.c" + line="2972">The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. @@ -27350,35 +28480,37 @@ return values. Free with g_variant_unref(). nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="2974">A #GCancellable or %NULL. + version="2.30" + glib:finish-func="call_with_unix_fd_list_finish" + glib:sync-func="call_with_unix_fd_list_sync"> Like g_dbus_proxy_call() but also takes a #GUnixFDList object. + filename="gio/gdbusproxy.c" + line="3033">Like g_dbus_proxy_call() but also takes a #GUnixFDList object. This method is only available on UNIX. - + A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="3035">A #GDBusProxy. Name of method to invoke. + filename="gio/gdbusproxy.c" + line="3036">Name of method to invoke. nullable="1" allow-none="1"> A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + filename="gio/gdbusproxy.c" + line="3037">A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. + filename="gio/gdbusproxy.c" + line="3038">Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning + filename="gio/gdbusproxy.c" + line="3039">The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. @@ -27408,8 +28540,8 @@ This method is only available on UNIX. nullable="1" allow-none="1"> A #GUnixFDList or %NULL. + filename="gio/gdbusproxy.c" + line="3041">A #GUnixFDList or %NULL. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="3042">A #GCancellable or %NULL. scope="async" closure="7"> A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + filename="gio/gdbusproxy.c" + line="3043">A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. @@ -27438,8 +28570,8 @@ care about the result of the method invocation. nullable="1" allow-none="1"> The data to pass to @callback. + filename="gio/gdbusproxy.c" + line="3045">The data to pass to @callback. @@ -27449,38 +28581,39 @@ care about the result of the method invocation. version="2.30" throws="1"> Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). - + filename="gio/gdbusproxy.c" + line="3067">Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). + %NULL if @error is set. Otherwise a #GVariant tuple with + filename="gio/gdbusproxy.c" + line="3076">%NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="3069">A #GDBusProxy. Return location for a #GUnixFDList or %NULL. + filename="gio/gdbusproxy.c" + line="3070">Return location for a #GUnixFDList or %NULL. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list(). + filename="gio/gdbusproxy.c" + line="3071">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list(). @@ -27488,31 +28621,32 @@ return values. Free with g_variant_unref(). + throws="1" + glib:async-func="call_with_unix_fd_list"> Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. + filename="gio/gdbusproxy.c" + line="3090">Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. This method is only available on UNIX. - + %NULL if @error is set. Otherwise a #GVariant tuple with + filename="gio/gdbusproxy.c" + line="3108">%NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="3092">A #GDBusProxy. Name of method to invoke. + filename="gio/gdbusproxy.c" + line="3093">Name of method to invoke. nullable="1" allow-none="1"> A #GVariant tuple with parameters for the signal + filename="gio/gdbusproxy.c" + line="3094">A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. + filename="gio/gdbusproxy.c" + line="3096">Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning + filename="gio/gdbusproxy.c" + line="3097">The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. @@ -27543,19 +28677,20 @@ return values. Free with g_variant_unref(). nullable="1" allow-none="1"> A #GUnixFDList or %NULL. + filename="gio/gdbusproxy.c" + line="3099">A #GUnixFDList or %NULL. Return location for a #GUnixFDList or %NULL. + filename="gio/gdbusproxy.c" + line="3100">Return location for a #GUnixFDList or %NULL. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusproxy.c" + line="3101">A #GCancellable or %NULL. @@ -27573,18 +28708,18 @@ return values. Free with g_variant_unref(). c:identifier="g_dbus_proxy_get_cached_property" version="2.26"> Looks up the value for a property from the cache. This call does no + filename="gio/gdbusproxy.c" + line="682">Looks up the value for a property from the cache. This call does no blocking IO. If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @property_name is referenced by it, then @value is checked against the type of the property. - + A reference to the #GVariant instance + filename="gio/gdbusproxy.c" + line="694">A reference to the #GVariant instance that holds the value for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref(). @@ -27592,14 +28727,14 @@ it, then @value is checked against the type of the property. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="684">A #GDBusProxy. Property name. + filename="gio/gdbusproxy.c" + line="685">Property name. @@ -27608,13 +28743,13 @@ it, then @value is checked against the type of the property. c:identifier="g_dbus_proxy_get_cached_property_names" version="2.26"> Gets the names of all cached properties on @proxy. - + filename="gio/gdbusproxy.c" + line="620">Gets the names of all cached properties on @proxy. + A + filename="gio/gdbusproxy.c" + line="626">A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev(). @@ -27625,8 +28760,8 @@ it, then @value is checked against the type of the property. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="622">A #GDBusProxy. @@ -27635,20 +28770,20 @@ it, then @value is checked against the type of the property. c:identifier="g_dbus_proxy_get_connection" version="2.26"> Gets the connection @proxy is for. - + filename="gio/gdbusproxy.c" + line="2232">Gets the connection @proxy is for. + A #GDBusConnection owned by @proxy. Do not free. + filename="gio/gdbusproxy.c" + line="2238">A #GDBusConnection owned by @proxy. Do not free. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2234">A #GDBusProxy. @@ -27657,24 +28792,24 @@ it, then @value is checked against the type of the property. c:identifier="g_dbus_proxy_get_default_timeout" version="2.26"> Gets the timeout to use if -1 (specifying default timeout) is + filename="gio/gdbusproxy.c" + line="2348">Gets the timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. See the #GDBusProxy:g-default-timeout property for more details. - + Timeout to use for @proxy. + filename="gio/gdbusproxy.c" + line="2358">Timeout to use for @proxy. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2350">A #GDBusProxy. @@ -27683,20 +28818,20 @@ See the #GDBusProxy:g-default-timeout property for more details. c:identifier="g_dbus_proxy_get_flags" version="2.26"> Gets the flags that @proxy was constructed with. - + filename="gio/gdbusproxy.c" + line="2249">Gets the flags that @proxy was constructed with. + Flags from the #GDBusProxyFlags enumeration. + filename="gio/gdbusproxy.c" + line="2255">Flags from the #GDBusProxyFlags enumeration. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2251">A #GDBusProxy. @@ -27705,23 +28840,23 @@ See the #GDBusProxy:g-default-timeout property for more details. c:identifier="g_dbus_proxy_get_interface_info" version="2.26"> Returns the #GDBusInterfaceInfo, if any, specifying the interface + filename="gio/gdbusproxy.c" + line="2410">Returns the #GDBusInterfaceInfo, if any, specifying the interface that @proxy conforms to. See the #GDBusProxy:g-interface-info property for more details. - + A #GDBusInterfaceInfo or %NULL. + filename="gio/gdbusproxy.c" + line="2418">A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy. A #GDBusProxy + filename="gio/gdbusproxy.c" + line="2412">A #GDBusProxy @@ -27730,20 +28865,20 @@ property for more details. c:identifier="g_dbus_proxy_get_interface_name" version="2.26"> Gets the D-Bus interface name @proxy is for. - + filename="gio/gdbusproxy.c" + line="2331">Gets the D-Bus interface name @proxy is for. + A string owned by @proxy. Do not free. + filename="gio/gdbusproxy.c" + line="2337">A string owned by @proxy. Do not free. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2333">A #GDBusProxy. @@ -27752,24 +28887,24 @@ property for more details. c:identifier="g_dbus_proxy_get_name" version="2.26"> Gets the name that @proxy was constructed for. + filename="gio/gdbusproxy.c" + line="2266">Gets the name that @proxy was constructed for. When connected to a message bus, this will usually be non-%NULL. However, it may be %NULL for a proxy that communicates using a peer-to-peer pattern. - + A string owned by @proxy. Do not free. + filename="gio/gdbusproxy.c" + line="2276">A string owned by @proxy. Do not free. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2268">A #GDBusProxy. @@ -27778,24 +28913,24 @@ pattern. c:identifier="g_dbus_proxy_get_name_owner" version="2.26"> The unique name that owns the name that @proxy is for or %NULL if + filename="gio/gdbusproxy.c" + line="2287">The unique name that owns the name that @proxy is for or %NULL if no-one currently owns that name. You may connect to the #GObject::notify signal to track changes to the #GDBusProxy:g-name-owner property. - + The name owner or %NULL if no name + filename="gio/gdbusproxy.c" + line="2296">The name owner or %NULL if no name owner exists. Free with g_free(). A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2289">A #GDBusProxy. @@ -27804,20 +28939,20 @@ no-one currently owns that name. You may connect to the c:identifier="g_dbus_proxy_get_object_path" version="2.26"> Gets the object path @proxy is for. - + filename="gio/gdbusproxy.c" + line="2314">Gets the object path @proxy is for. + A string owned by @proxy. Do not free. + filename="gio/gdbusproxy.c" + line="2320">A string owned by @proxy. Do not free. A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2316">A #GDBusProxy. @@ -27826,8 +28961,8 @@ no-one currently owns that name. You may connect to the c:identifier="g_dbus_proxy_set_cached_property" version="2.26"> If @value is not %NULL, sets the cached value for the property with + filename="gio/gdbusproxy.c" + line="739">If @value is not %NULL, sets the cached value for the property with name @property_name to the value in @value. If @value is %NULL, then the cached value is removed from the @@ -27860,21 +28995,21 @@ transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals `ChatroomParticipantJoined(String name)` and `ChatroomParticipantParted(String name)`. - + A #GDBusProxy + filename="gio/gdbusproxy.c" + line="741">A #GDBusProxy Property name. + filename="gio/gdbusproxy.c" + line="742">Property name. Value for the property or %NULL to remove it from the cache. + filename="gio/gdbusproxy.c" + line="743">Value for the property or %NULL to remove it from the cache. @@ -27892,27 +29027,27 @@ it is more efficient to only transmit the delta using e.g. signals c:identifier="g_dbus_proxy_set_default_timeout" version="2.26"> Sets the timeout to use if -1 (specifying default timeout) is + filename="gio/gdbusproxy.c" + line="2375">Sets the timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. See the #GDBusProxy:g-default-timeout property for more details. - + A #GDBusProxy. + filename="gio/gdbusproxy.c" + line="2377">A #GDBusProxy. Timeout in milliseconds. + filename="gio/gdbusproxy.c" + line="2378">Timeout in milliseconds. @@ -27921,19 +29056,19 @@ See the #GDBusProxy:g-default-timeout property for more details. c:identifier="g_dbus_proxy_set_interface_info" version="2.26"> Ensure that interactions with @proxy conform to the given + filename="gio/gdbusproxy.c" + line="2439">Ensure that interactions with @proxy conform to the given interface. See the #GDBusProxy:g-interface-info property for more details. - + A #GDBusProxy + filename="gio/gdbusproxy.c" + line="2441">A #GDBusProxy nullable="1" allow-none="1"> Minimum interface this proxy conforms to + filename="gio/gdbusproxy.c" + line="2442">Minimum interface this proxy conforms to or %NULL to unset. @@ -27956,8 +29091,8 @@ details. transfer-ownership="none" default-value="G_BUS_TYPE_NONE"> If this property is not %G_BUS_TYPE_NONE, then + filename="gio/gdbusproxy.c" + line="400">If this property is not %G_BUS_TYPE_NONE, then #GDBusProxy:g-connection must be %NULL and will be set to the #GDBusConnection obtained by calling g_bus_get() with the value of this property. @@ -27969,8 +29104,8 @@ of this property. construct-only="1" transfer-ownership="none"> The #GDBusConnection the proxy is for. + filename="gio/gdbusproxy.c" + line="382">The #GDBusConnection the proxy is for. transfer-ownership="none" default-value="-1"> The timeout to use if -1 (specifying default timeout) is passed + filename="gio/gdbusproxy.c" + line="512">The timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. @@ -27998,8 +29133,8 @@ the default timeout (typically 25 seconds) is used. If set to transfer-ownership="none" default-value="G_DBUS_PROXY_FLAGS_NONE"> Flags from the #GDBusProxyFlags enumeration. + filename="gio/gdbusproxy.c" + line="421">Flags from the #GDBusProxyFlags enumeration. Ensure that interactions with this proxy conform to the given + filename="gio/gdbusproxy.c" + line="342">Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given #GDBusInterfaceInfo is said to be the "expected interface". @@ -28041,8 +29176,8 @@ service-side is not considered an ABI break. transfer-ownership="none" default-value="NULL"> The D-Bus interface name the proxy is for. + filename="gio/gdbusproxy.c" + line="494">The D-Bus interface name the proxy is for. transfer-ownership="none" default-value="NULL"> The well-known or unique name that the proxy is for. + filename="gio/gdbusproxy.c" + line="440">The well-known or unique name that the proxy is for. transfer-ownership="none" default-value="NULL"> The unique name that owns #GDBusProxy:g-name or %NULL if no-one + filename="gio/gdbusproxy.c" + line="458">The unique name that owns #GDBusProxy:g-name or %NULL if no-one currently owns that name. You may connect to #GObject::notify signal to track changes to this property. @@ -28074,8 +29209,8 @@ track changes to this property. transfer-ownership="none" default-value="NULL"> The object path the proxy is for. + filename="gio/gdbusproxy.c" + line="476">The object path the proxy is for. @@ -28086,8 +29221,8 @@ track changes to this property. Emitted when one or more D-Bus properties on @proxy changes. The + filename="gio/gdbusproxy.c" + line="539">Emitted when one or more D-Bus properties on @proxy changes. The local cache has already been updated when this signal fires. Note that both @changed_properties and @invalidated_properties are guaranteed to never be %NULL (either may be empty though). @@ -28105,14 +29240,14 @@ This signal corresponds to the A #GVariant containing the properties that changed (type: `a{sv}`) + filename="gio/gdbusproxy.c" + line="542">A #GVariant containing the properties that changed (type: `a{sv}`) A %NULL terminated array of properties that was invalidated + filename="gio/gdbusproxy.c" + line="543">A %NULL terminated array of properties that was invalidated @@ -28121,8 +29256,8 @@ This signal corresponds to the Emitted when a signal from the remote object and interface that @proxy is for, has been received. + filename="gio/gdbusproxy.c" + line="575">Emitted when a signal from the remote object and interface that @proxy is for, has been received. Since 2.72 this signal supports detailed connections. You can connect to the detailed signal `g-signal::x` in order to receive callbacks only when @@ -28136,20 +29271,20 @@ signal `x` is received from the remote object. nullable="1" allow-none="1"> The sender of the signal or %NULL if the connection is not a bus connection. + filename="gio/gdbusproxy.c" + line="578">The sender of the signal or %NULL if the connection is not a bus connection. The name of the signal. + filename="gio/gdbusproxy.c" + line="579">The name of the signal. A #GVariant tuple with parameters for the signal. + filename="gio/gdbusproxy.c" + line="580">A #GVariant tuple with parameters for the signal. @@ -28160,15 +29295,18 @@ signal `x` is received from the remote object. glib:is-gtype-struct-for="DBusProxy" version="2.26"> Class structure for #GDBusProxy. - + filename="gio/gdbusproxy.h" + line="52">Class structure for #GDBusProxy. + + Signal class handler for the #GDBusProxy::g-properties-changed signal. - + @@ -28186,8 +29324,11 @@ signal `x` is received from the remote object. + Signal class handler for the #GDBusProxy::g-signal signal. - + @@ -28219,16 +29360,16 @@ signal `x` is received from the remote object. glib:get-type="g_dbus_proxy_flags_get_type" c:type="GDBusProxyFlags"> Flags used when constructing an instance of a #GDBusProxy derived class. + filename="gio/gioenums.h" + line="1024">Flags used when constructing an instance of a #GDBusProxy derived class. No flags set. + filename="gio/gioenums.h" + line="1026">No flags set. glib:nick="do-not-load-properties" glib:name="G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES"> Don't load properties. + filename="gio/gioenums.h" + line="1027">Don't load properties. glib:nick="do-not-connect-signals" glib:name="G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS"> Don't connect to signals on the remote object. + filename="gio/gioenums.h" + line="1028">Don't connect to signals on the remote object. glib:nick="do-not-auto-start" glib:name="G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START"> If the proxy is for a well-known name, + filename="gio/gioenums.h" + line="1029">If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization or a method call. This flag is only meaningful in proxies for well-known names. @@ -28265,8 +29406,8 @@ This flag is only meaningful in proxies for well-known names. glib:nick="get-invalidated-properties" glib:name="G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES"> If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32. + filename="gio/gioenums.h" + line="1032">If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32. glib:nick="do-not-auto-start-at-construction" glib:name="G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION"> If the proxy is for a well-known name, + filename="gio/gioenums.h" + line="1033">If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization, but allow it to be autostarted by a method call. This flag is only meaningful in proxies for well-known names, and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified. @@ -28286,8 +29427,8 @@ and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified. glib:nick="no-match-rule" glib:name="G_DBUS_PROXY_FLAGS_NO_MATCH_RULE"> Don't actually send the AddMatch D-Bus + filename="gio/gioenums.h" + line="1037">Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). (Since: 2.72) @@ -28296,25 +29437,25 @@ and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified. c:type="GDBusProxyPrivate" disguised="1" opaque="1"> - + Function signature for a function used to determine the #GType to + filename="gio/giotypes.h" + line="524">Function signature for a function used to determine the #GType to use for an interface proxy (if @interface_name is not %NULL) or object proxy (if @interface_name is %NULL). -This function is called in the -[thread-default main loop][g-main-context-push-thread-default] +This function is called in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) that @manager was constructed in. - + A #GType to use for the remote object. The returned type + filename="gio/giotypes.h" + line="539">A #GType to use for the remote object. The returned type must be a #GDBusProxy or #GDBusObjectProxy -derived type. @@ -28322,15 +29463,15 @@ that @manager was constructed in. A #GDBusObjectManagerClient. + filename="gio/giotypes.h" + line="526">A #GDBusObjectManagerClient. The object path of the remote object. + filename="gio/giotypes.h" + line="527">The object path of the remote object. nullable="1" allow-none="1"> The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested. + filename="gio/giotypes.h" + line="528">The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested. nullable="1" allow-none="1"> data passed in by the user. + filename="gio/giotypes.h" + line="529">data passed in by the user. @@ -28359,16 +29500,16 @@ that @manager was constructed in. glib:get-type="g_dbus_send_message_flags_get_type" c:type="GDBusSendMessageFlags"> Flags used when sending #GDBusMessages on a #GDBusConnection. + filename="gio/gioenums.h" + line="1437">Flags used when sending #GDBusMessages on a #GDBusConnection. No flags set. + filename="gio/gioenums.h" + line="1439">No flags set. glib:nick="preserve-serial" glib:name="G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL"> Do not automatically + filename="gio/gioenums.h" + line="1440">Do not automatically assign a serial number from the #GDBusConnection object when sending a message. @@ -28390,33 +29531,35 @@ sending a message. glib:type-name="GDBusServer" glib:get-type="g_dbus_server_get_type"> #GDBusServer is a helper for listening to and accepting D-Bus + filename="gio/gdbusserver.c" + line="65">`GDBusServer` is a helper for listening to and accepting D-Bus connections. This can be used to create a new D-Bus server, allowing two peers to use the D-Bus protocol for their own specialized communication. A server instance provided in this way will not perform message routing or -implement the org.freedesktop.DBus interface. +implement the +[`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages). To just export an object on a well-known name on a message bus, such as the -session or system bus, you should instead use g_bus_own_name(). +session or system bus, you should instead use [func@Gio.bus_own_name]. An example of peer-to-peer communication with GDBus can be found in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). -Note that a minimal #GDBusServer will accept connections from any -peer. In many use-cases it will be necessary to add a #GDBusAuthObserver -that only accepts connections that have successfully authenticated -as the same user that is running the #GDBusServer. Since GLib 2.68 this can -be achieved more simply by passing the -%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server. +Note that a minimal `GDBusServer` will accept connections from any +peer. In many use-cases it will be necessary to add a +[class@Gio.DBusAuthObserver] that only accepts connections that have +successfully authenticated as the same user that is running the +`GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing +the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the +server. Creates a new D-Bus server that listens on the first address in + filename="gio/gdbusserver.c" + line="458">Creates a new D-Bus server that listens on the first address in @address that works. Once constructed, you can use g_dbus_server_get_client_address() to @@ -28432,35 +29575,35 @@ incoming connections. The returned #GDBusServer isn't active - you have to start it with g_dbus_server_start(). -#GDBusServer is used in this [example][gdbus-peer-to-peer]. +#GDBusServer is used in this [example](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). This is a synchronous failable constructor. There is currently no asynchronous version. - + A #GDBusServer or %NULL if @error is set. Free with + filename="gio/gdbusserver.c" + line="488">A #GDBusServer or %NULL if @error is set. Free with g_object_unref(). A D-Bus address. + filename="gio/gdbusserver.c" + line="460">A D-Bus address. Flags from the #GDBusServerFlags enumeration. + filename="gio/gdbusserver.c" + line="461">Flags from the #GDBusServerFlags enumeration. A D-Bus GUID. + filename="gio/gdbusserver.c" + line="462">A D-Bus GUID. nullable="1" allow-none="1"> A #GDBusAuthObserver or %NULL. + filename="gio/gdbusserver.c" + line="463">A #GDBusAuthObserver or %NULL. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusserver.c" + line="464">A #GCancellable or %NULL. @@ -28488,25 +29631,25 @@ g_object_unref(). glib:get-property="client-address" version="2.26"> Gets a + filename="gio/gdbusserver.c" + line="520">Gets a [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) string that can be used by clients to connect to @server. This is valid and non-empty if initializing the #GDBusServer succeeded. - + A D-Bus address string. Do not free, the string is owned + filename="gio/gdbusserver.c" + line="530">A D-Bus address string. Do not free, the string is owned by @server. A #GDBusServer. + filename="gio/gdbusserver.c" + line="522">A #GDBusServer. @@ -28516,20 +29659,20 @@ by @server. glib:get-property="flags" version="2.26"> Gets the flags for @server. - + filename="gio/gdbusserver.c" + line="559">Gets the flags for @server. + A set of flags from the #GDBusServerFlags enumeration. + filename="gio/gdbusserver.c" + line="565">A set of flags from the #GDBusServerFlags enumeration. A #GDBusServer. + filename="gio/gdbusserver.c" + line="561">A #GDBusServer. @@ -28539,76 +29682,77 @@ by @server. glib:get-property="guid" version="2.26"> Gets the GUID for @server, as provided to g_dbus_server_new_sync(). - + filename="gio/gdbusserver.c" + line="542">Gets the GUID for @server, as provided to g_dbus_server_new_sync(). + A D-Bus GUID. Do not free this string, it is owned by @server. + filename="gio/gdbusserver.c" + line="548">A D-Bus GUID. Do not free this string, it is owned by @server. A #GDBusServer. + filename="gio/gdbusserver.c" + line="544">A #GDBusServer. Gets whether @server is active. - + filename="gio/gdbusserver.c" + line="576">Gets whether @server is active. + %TRUE if server is active, %FALSE otherwise. + filename="gio/gdbusserver.c" + line="582">%TRUE if server is active, %FALSE otherwise. A #GDBusServer. + filename="gio/gdbusserver.c" + line="578">A #GDBusServer. Starts @server. - + filename="gio/gdbusserver.c" + line="593">Starts @server. + A #GDBusServer. + filename="gio/gdbusserver.c" + line="595">A #GDBusServer. Stops @server. - + filename="gio/gdbusserver.c" + line="620">Stops @server. + A #GDBusServer. + filename="gio/gdbusserver.c" + line="622">A #GDBusServer. @@ -28616,10 +29760,11 @@ by @server. Whether the server is currently active. + filename="gio/gdbusserver.c" + line="365">Whether the server is currently active. transfer-ownership="none" default-value="NULL"> The D-Bus address to listen on. + filename="gio/gdbusserver.c" + line="331">The D-Bus address to listen on. construct-only="1" transfer-ownership="none"> A #GDBusAuthObserver object to assist in the authentication process or %NULL. + filename="gio/gdbusserver.c" + line="381">A #GDBusAuthObserver object to assist in the authentication process or %NULL. getter="get_client_address" default-value="NULL"> The D-Bus address that clients can use. + filename="gio/gdbusserver.c" + line="349">The D-Bus address that clients can use. getter="get_flags" default-value="G_DBUS_SERVER_FLAGS_NONE"> Flags from the #GDBusServerFlags enumeration. + filename="gio/gdbusserver.c" + line="292">Flags from the #GDBusServerFlags enumeration. getter="get_guid" default-value="NULL"> The GUID of the server. + filename="gio/gdbusserver.c" + line="311">The GUID of the server. See #GDBusConnection:guid for more details. Emitted when a new authenticated connection has been made. Use + filename="gio/gdbusserver.c" + line="399">Emitted when a new authenticated connection has been made. Use g_dbus_connection_get_peer_credentials() to figure out what identity (if any), was authenticated. @@ -28695,8 +29840,8 @@ the #GDBusConnection::closed signal. If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD then the signal is emitted in a new thread dedicated to the -connection. Otherwise the signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] +connection. Otherwise the signal is emitted in the thread-default +main context (see [method@GLib.MainContext.push_thread_default]) of the thread that @server was constructed in. You are guaranteed that signal handlers for this signal runs @@ -28705,16 +29850,16 @@ that it's suitable to call g_dbus_connection_register_object() or similar from the signal handler. %TRUE to claim @connection, %FALSE to let other handlers + filename="gio/gdbusserver.c" + line="426">%TRUE to claim @connection, %FALSE to let other handlers run. A #GDBusConnection for the new connection. + filename="gio/gdbusserver.c" + line="402">A #GDBusConnection for the new connection. @@ -28726,16 +29871,16 @@ run. glib:get-type="g_dbus_server_flags_get_type" c:type="GDBusServerFlags"> Flags used when creating a #GDBusServer. + filename="gio/gioenums.h" + line="1390">Flags used when creating a #GDBusServer. No flags set. + filename="gio/gioenums.h" + line="1392">No flags set. glib:nick="run-in-thread" glib:name="G_DBUS_SERVER_FLAGS_RUN_IN_THREAD"> All #GDBusServer::new-connection + filename="gio/gioenums.h" + line="1393">All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details). @@ -28754,8 +29899,8 @@ details). glib:nick="authentication-allow-anonymous" glib:name="G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS"> Allow the anonymous + filename="gio/gioenums.h" + line="1396">Allow the anonymous authentication method. glib:nick="authentication-require-same-user" glib:name="G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER"> Require the UID of the + filename="gio/gioenums.h" + line="1398">Require the UID of the peer to be the same as the UID of the server when authenticating. (Since: 2.68) @@ -28773,17 +29918,17 @@ peer to be the same as the UID of the server when authenticating. (Since: 2.68)< c:type="GDBusSignalCallback" version="2.26"> Signature for callback function used in g_dbus_connection_signal_subscribe(). - + filename="gio/gdbusconnection.h" + line="576">Signature for callback function used in g_dbus_connection_signal_subscribe(). + A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="578">A #GDBusConnection. The unique bus name of the sender of the signal, + filename="gio/gdbusconnection.h" + line="579">The unique bus name of the sender of the signal, or %NULL on a peer-to-peer D-Bus connection. The object path that the signal was emitted on. + filename="gio/gdbusconnection.h" + line="581">The object path that the signal was emitted on. The name of the interface. + filename="gio/gdbusconnection.h" + line="582">The name of the interface. The name of the signal. + filename="gio/gdbusconnection.h" + line="583">The name of the signal. A #GVariant tuple with parameters for the signal. + filename="gio/gdbusconnection.h" + line="584">A #GVariant tuple with parameters for the signal. User data passed when subscribing to the signal. + filename="gio/gdbusconnection.h" + line="585">User data passed when subscribing to the signal. @@ -28838,16 +29983,16 @@ peer to be the same as the UID of the server when authenticating. (Since: 2.68)< glib:get-type="g_dbus_signal_flags_get_type" c:type="GDBusSignalFlags"> Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). + filename="gio/gioenums.h" + line="1413">Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). No flags set. + filename="gio/gioenums.h" + line="1415">No flags set. Don't actually send the AddMatch + filename="gio/gioenums.h" + line="1416">Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). @@ -28866,8 +30011,8 @@ over which match rules you add (but you must add them manually). glib:nick="match-arg0-namespace" glib:name="G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE"> Match first arguments that + filename="gio/gioenums.h" + line="1419">Match first arguments that contain a bus or interface name with the given namespace. glib:nick="match-arg0-path" glib:name="G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH"> Match first arguments that + filename="gio/gioenums.h" + line="1421">Match first arguments that contain an object path that is either equivalent to the given path, or one of the paths is a subpath of the other. @@ -28889,24 +30034,24 @@ or one of the paths is a subpath of the other. glib:get-type="g_dbus_signal_info_get_type" c:symbol-prefix="dbus_signal_info"> Information about a signal on a D-Bus interface. - + The reference count or -1 if statically allocated. The name of the D-Bus signal, e.g. "NameOwnerChanged". A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments. @@ -28914,7 +30059,7 @@ or one of the paths is a subpath of the other. A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. @@ -28922,21 +30067,21 @@ or one of the paths is a subpath of the other. If @info is statically allocated does nothing. Otherwise increases + filename="gio/gdbusintrospection.c" + line="142">If @info is statically allocated does nothing. Otherwise increases the reference count. - + The same @info. + filename="gio/gdbusintrospection.c" + line="149">The same @info. A #GDBusSignalInfo + filename="gio/gdbusintrospection.c" + line="144">A #GDBusSignalInfo @@ -28945,19 +30090,19 @@ the reference count. c:identifier="g_dbus_signal_info_unref" version="2.26"> If @info is statically allocated, does nothing. Otherwise decreases + filename="gio/gdbusintrospection.c" + line="309">If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed. - + A #GDBusSignalInfo. + filename="gio/gdbusintrospection.c" + line="311">A #GDBusSignalInfo. @@ -28967,53 +30112,53 @@ the memory used is freed. c:type="GDBusSubtreeDispatchFunc" version="2.26"> The type of the @dispatch function in #GDBusSubtreeVTable. + filename="gio/gdbusconnection.h" + line="511">The type of the @dispatch function in #GDBusSubtreeVTable. Subtrees are flat. @node, if non-%NULL, is always exactly one segment of the object path (ie: it never contains a slash). - + A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. + filename="gio/gdbusconnection.h" + line="526">A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="513">A #GDBusConnection. The unique bus name of the remote caller. + filename="gio/gdbusconnection.h" + line="514">The unique bus name of the remote caller. The object path that was registered with g_dbus_connection_register_subtree(). + filename="gio/gdbusconnection.h" + line="515">The object path that was registered with g_dbus_connection_register_subtree(). The D-Bus interface name that the method call or property access is for. + filename="gio/gdbusconnection.h" + line="516">The D-Bus interface name that the method call or property access is for. A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. + filename="gio/gdbusconnection.h" + line="517">A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. Return location for user data to pass to functions in the returned #GDBusInterfaceVTable. + filename="gio/gdbusconnection.h" + line="518">Return location for user data to pass to functions in the returned #GDBusInterfaceVTable. allow-none="1" closure="6"> The @user_data #gpointer passed to g_dbus_connection_register_subtree(). + filename="gio/gdbusconnection.h" + line="519">The @user_data #gpointer passed to g_dbus_connection_register_subtree(). @@ -29032,8 +30177,8 @@ segment of the object path (ie: it never contains a slash). c:type="GDBusSubtreeEnumerateFunc" version="2.26"> The type of the @enumerate function in #GDBusSubtreeVTable. + filename="gio/gdbusconnection.h" + line="446">The type of the @enumerate function in #GDBusSubtreeVTable. This function is called when generating introspection data and also when preparing to dispatch incoming messages in the event that the @@ -29044,11 +30189,11 @@ Hierarchies are not supported; the items that you return should not contain the `/` character. The return value will be freed with g_strfreev(). - + A newly allocated array of strings for node names that are children of @object_path. + filename="gio/gdbusconnection.h" + line="465">A newly allocated array of strings for node names that are children of @object_path. @@ -29056,20 +30201,20 @@ The return value will be freed with g_strfreev(). A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="448">A #GDBusConnection. The unique bus name of the remote caller. + filename="gio/gdbusconnection.h" + line="449">The unique bus name of the remote caller. The object path that was registered with g_dbus_connection_register_subtree(). + filename="gio/gdbusconnection.h" + line="450">The object path that was registered with g_dbus_connection_register_subtree(). allow-none="1" closure="3"> The @user_data #gpointer passed to g_dbus_connection_register_subtree(). + filename="gio/gdbusconnection.h" + line="451">The @user_data #gpointer passed to g_dbus_connection_register_subtree(). @@ -29090,16 +30235,16 @@ The return value will be freed with g_strfreev(). glib:get-type="g_dbus_subtree_flags_get_type" c:type="GDBusSubtreeFlags"> Flags passed to g_dbus_connection_register_subtree(). + filename="gio/gioenums.h" + line="1373">Flags passed to g_dbus_connection_register_subtree(). No flags set. + filename="gio/gioenums.h" + line="1375">No flags set. glib:nick="dispatch-to-unenumerated-nodes" glib:name="G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES"> Method calls to objects not in the enumerated range + filename="gio/gioenums.h" + line="1376">Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. @@ -29117,8 +30262,8 @@ The return value will be freed with g_strfreev(). c:type="GDBusSubtreeIntrospectFunc" version="2.26"> The type of the @introspect function in #GDBusSubtreeVTable. + filename="gio/gdbusconnection.h" + line="474">The type of the @introspect function in #GDBusSubtreeVTable. Subtrees are flat. @node, if non-%NULL, is always exactly one segment of the object path (ie: it never contains a slash). @@ -29136,11 +30281,11 @@ The difference between returning %NULL and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the %NULL case. - + A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. + filename="gio/gdbusconnection.h" + line="501">A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. @@ -29148,26 +30293,26 @@ case. A #GDBusConnection. + filename="gio/gdbusconnection.h" + line="476">A #GDBusConnection. The unique bus name of the remote caller. + filename="gio/gdbusconnection.h" + line="477">The unique bus name of the remote caller. The object path that was registered with g_dbus_connection_register_subtree(). + filename="gio/gdbusconnection.h" + line="478">The object path that was registered with g_dbus_connection_register_subtree(). A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. + filename="gio/gdbusconnection.h" + line="479">A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. allow-none="1" closure="4"> The @user_data #gpointer passed to g_dbus_connection_register_subtree(). + filename="gio/gdbusconnection.h" + line="480">The @user_data #gpointer passed to g_dbus_connection_register_subtree(). @@ -29186,27 +30331,27 @@ case. c:type="GDBusSubtreeVTable" version="2.26"> Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). - + filename="gio/gdbusconnection.h" + line="538">Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). + Function for enumerating child nodes. + filename="gio/gdbusconnection.h" + line="540">Function for enumerating child nodes. Function for introspecting a child node. + filename="gio/gdbusconnection.h" + line="541">Function for introspecting a child node. Function for dispatching a remote call on a child node. + filename="gio/gdbusconnection.h" + line="542">Function for dispatching a remote call on a child node. @@ -29219,7 +30364,7 @@ case. - + @@ -29230,25 +30375,1114 @@ case. c:type="G_DEBUG_CONTROLLER_EXTENSION_POINT_NAME" version="2.72"> Extension point for debug control functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + @@ -29257,7 +31491,7 @@ See [Extending GIO][extending-gio]. - + @@ -29266,7 +31500,7 @@ See [Extending GIO][extending-gio]. - + @@ -29275,7 +31509,7 @@ See [Extending GIO][extending-gio]. - + @@ -29287,25 +31521,25 @@ See [Extending GIO][extending-gio]. deprecated="1" deprecated-version="2.28"> Extension point for default handler to URI association. See -[Extending GIO][extending-gio]. +[Extending GIO](overview.html#extending-gio). The #GDesktopAppInfoLookup interface is deprecated and unused by GIO. - + - + - + @@ -29314,7 +31548,7 @@ See [Extending GIO][extending-gio]. - + @@ -29325,15 +31559,15 @@ See [Extending GIO][extending-gio]. c:type="G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE" version="2.58"> The string used to obtain a Unix device path with g_drive_get_identifier(). - + - + @@ -29342,7 +31576,7 @@ See [Extending GIO][extending-gio]. - + @@ -29351,7 +31585,7 @@ See [Extending GIO][extending-gio]. - + @@ -29360,7 +31594,7 @@ See [Extending GIO][extending-gio]. - + @@ -29369,7 +31603,7 @@ See [Extending GIO][extending-gio]. - + @@ -29378,7 +31612,7 @@ See [Extending GIO][extending-gio]. - + @@ -29392,27 +31626,27 @@ See [Extending GIO][extending-gio]. glib:get-type="g_data_input_stream_get_type" glib:type-struct="DataInputStreamClass"> Data input stream implements #GInputStream and includes functions for -reading structured data directly from a binary input stream. - + filename="gio/gdatainputstream.c" + line="35">Data input stream implements [class@Gio.InputStream] and includes functions +for reading structured data directly from a binary input stream. + Creates a new data input stream for the @base_stream. - + filename="gio/gdatainputstream.c" + line="167">Creates a new data input stream for the @base_stream. + a new #GDataInputStream. + filename="gio/gdatainputstream.c" + line="173">a new #GDataInputStream. a #GInputStream. + filename="gio/gdatainputstream.c" + line="169">a #GInputStream. @@ -29421,20 +31655,20 @@ reading structured data directly from a binary input stream. c:identifier="g_data_input_stream_get_byte_order" glib:get-property="byte-order"> Gets the byte order for the data input stream. - + filename="gio/gdatainputstream.c" + line="216">Gets the byte order for the data input stream. + the @stream's current #GDataStreamByteOrder. + filename="gio/gdatainputstream.c" + line="222">the @stream's current #GDataStreamByteOrder. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="218">a given #GDataInputStream. @@ -29443,20 +31677,20 @@ reading structured data directly from a binary input stream. c:identifier="g_data_input_stream_get_newline_type" glib:get-property="newline-type"> Gets the current newline type for the @stream. - + filename="gio/gdatainputstream.c" + line="262">Gets the current newline type for the @stream. + #GDataStreamNewlineType for the given @stream. + filename="gio/gdatainputstream.c" + line="268">#GDataStreamNewlineType for the given @stream. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="264">a given #GDataInputStream. @@ -29465,21 +31699,21 @@ reading structured data directly from a binary input stream. c:identifier="g_data_input_stream_read_byte" throws="1"> Reads an unsigned 8-bit/1-byte value from @stream. - + filename="gio/gdatainputstream.c" + line="312">Reads an unsigned 8-bit/1-byte value from @stream. + an unsigned 8-bit/1-byte value read from the @stream or `0` + filename="gio/gdatainputstream.c" + line="320">an unsigned 8-bit/1-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="314">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="315">optional #GCancellable object, %NULL to ignore. @@ -29497,24 +31731,24 @@ if an error occurred. c:identifier="g_data_input_stream_read_int16" throws="1"> Reads a 16-bit/2-byte value from @stream. + filename="gio/gdatainputstream.c" + line="339">Reads a 16-bit/2-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - + a signed 16-bit/2-byte value read from @stream or `0` if + filename="gio/gdatainputstream.c" + line="350">a signed 16-bit/2-byte value read from @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="341">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="342">optional #GCancellable object, %NULL to ignore. @@ -29532,8 +31766,8 @@ an error occurred. c:identifier="g_data_input_stream_read_int32" throws="1"> Reads a signed 32-bit/4-byte value from @stream. + filename="gio/gdatainputstream.c" + line="427">Reads a signed 32-bit/4-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). @@ -29541,19 +31775,19 @@ see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order( If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a signed 32-bit/4-byte value read from the @stream or `0` if + filename="gio/gdatainputstream.c" + line="442">a signed 32-bit/4-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="429">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="430">optional #GCancellable object, %NULL to ignore. @@ -29571,8 +31805,8 @@ an error occurred. c:identifier="g_data_input_stream_read_int64" throws="1"> Reads a 64-bit/8-byte value from @stream. + filename="gio/gdatainputstream.c" + line="523">Reads a 64-bit/8-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). @@ -29580,19 +31814,19 @@ see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order( If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a signed 64-bit/8-byte value read from @stream or `0` if + filename="gio/gdatainputstream.c" + line="538">a signed 64-bit/8-byte value read from @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="525">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="526">optional #GCancellable object, %NULL to ignore. + throws="1" + glib:async-func="read_line_async"> Reads a line from the data input stream. Note that no encoding + filename="gio/gdatainputstream.c" + line="717">Reads a line from the data input stream. Note that no encoding checks or conversion is performed; the input is not guaranteed to be UTF-8, and may in fact have embedded NUL characters. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + + filename="gio/gdatainputstream.c" + line="732"> a NUL terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error @@ -29635,8 +31870,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="719">a given #GDataInputStream. optional="1" allow-none="1"> a #gsize to get the length of the data read in. + filename="gio/gdatainputstream.c" + line="720">a #gsize to get the length of the data read in. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="721">optional #GCancellable object, %NULL to ignore. + version="2.20" + glib:finish-func="read_line_finish" + glib:sync-func="read_line"> The asynchronous version of g_data_input_stream_read_line(). It is + filename="gio/gdatainputstream.c" + line="1133">The asynchronous version of g_data_input_stream_read_line(). It is an error to have two outstanding calls to this function. When the operation is finished, @callback will be called. You can then call g_data_input_stream_read_line_finish() to get the result of the operation. - + a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="1135">a given #GDataInputStream. the [I/O priority][io-priority] of the request + filename="gio/gdatainputstream.c" + line="1136">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="1137">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> callback to call when the request is satisfied. + filename="gio/gdatainputstream.c" + line="1138">callback to call when the request is satisfied. nullable="1" allow-none="1"> the data to pass to callback function. + filename="gio/gdatainputstream.c" + line="1139">the data to pass to callback function. @@ -29725,16 +31962,16 @@ the result of the operation. version="2.20" throws="1"> Finish an asynchronous call started by + filename="gio/gdatainputstream.c" + line="1209">Finish an asynchronous call started by g_data_input_stream_read_line_async(). Note the warning about string encoding in g_data_input_stream_read_line() applies here as well. - + + filename="gio/gdatainputstream.c" + line="1221"> a NUL-terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error @@ -29747,14 +31984,14 @@ well. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="1211">a given #GDataInputStream. the #GAsyncResult that was provided to the callback. + filename="gio/gdatainputstream.c" + line="1212">the #GAsyncResult that was provided to the callback. optional="1" allow-none="1"> a #gsize to get the length of the data read in. + filename="gio/gdatainputstream.c" + line="1213">a #gsize to get the length of the data read in. @@ -29775,14 +32012,14 @@ well. version="2.30" throws="1"> Finish an asynchronous call started by + filename="gio/gdatainputstream.c" + line="1241">Finish an asynchronous call started by g_data_input_stream_read_line_async(). - + a string with the line that + filename="gio/gdatainputstream.c" + line="1251">a string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set @@ -29793,14 +32030,14 @@ g_data_input_stream_read_line_async(). a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="1243">a given #GDataInputStream. the #GAsyncResult that was provided to the callback. + filename="gio/gdatainputstream.c" + line="1244">the #GAsyncResult that was provided to the callback. optional="1" allow-none="1"> a #gsize to get the length of the data read in. + filename="gio/gdatainputstream.c" + line="1245">a #gsize to get the length of the data read in. @@ -29821,17 +32058,17 @@ g_data_input_stream_read_line_async(). version="2.30" throws="1"> Reads a UTF-8 encoded line from the data input stream. + filename="gio/gdatainputstream.c" + line="803">Reads a UTF-8 encoded line from the data input stream. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a NUL terminated UTF-8 string + filename="gio/gdatainputstream.c" + line="816">a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 @@ -29843,8 +32080,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="805">a given #GDataInputStream. optional="1" allow-none="1"> a #gsize to get the length of the data read in. + filename="gio/gdatainputstream.c" + line="806">a #gsize to get the length of the data read in. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="807">optional #GCancellable object, %NULL to ignore. @@ -29873,24 +32110,24 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_data_input_stream_read_uint16" throws="1"> Reads an unsigned 16-bit/2-byte value from @stream. + filename="gio/gdatainputstream.c" + line="383">Reads an unsigned 16-bit/2-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - + an unsigned 16-bit/2-byte value read from the @stream or `0` if + filename="gio/gdatainputstream.c" + line="394">an unsigned 16-bit/2-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="385">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="386">optional #GCancellable object, %NULL to ignore. @@ -29908,8 +32145,8 @@ an error occurred. c:identifier="g_data_input_stream_read_uint32" throws="1"> Reads an unsigned 32-bit/4-byte value from @stream. + filename="gio/gdatainputstream.c" + line="475">Reads an unsigned 32-bit/4-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). @@ -29917,19 +32154,19 @@ see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order( If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + an unsigned 32-bit/4-byte value read from the @stream or `0` if + filename="gio/gdatainputstream.c" + line="490">an unsigned 32-bit/4-byte value read from the @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="477">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="478">optional #GCancellable object, %NULL to ignore. @@ -29947,8 +32184,8 @@ an error occurred. c:identifier="g_data_input_stream_read_uint64" throws="1"> Reads an unsigned 64-bit/8-byte value from @stream. + filename="gio/gdatainputstream.c" + line="571">Reads an unsigned 64-bit/8-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order(). @@ -29956,19 +32193,19 @@ see g_data_input_stream_get_byte_order(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + an unsigned 64-bit/8-byte read from @stream or `0` if + filename="gio/gdatainputstream.c" + line="586">an unsigned 64-bit/8-byte read from @stream or `0` if an error occurred. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="573">a given #GDataInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="574">optional #GCancellable object, %NULL to ignore. @@ -29986,10 +32223,11 @@ an error occurred. c:identifier="g_data_input_stream_read_until" deprecated="1" deprecated-version="2.56" - throws="1"> + throws="1" + glib:async-func="read_until_async"> Reads a string from the data input stream, up to the first + filename="gio/gdatainputstream.c" + line="904">Reads a string from the data input stream, up to the first occurrence of any of the stop characters. Note that, in contrast to g_data_input_stream_read_until_async(), @@ -30002,11 +32240,11 @@ g_data_input_stream_read_upto() instead, but note that that function does not consume the stop character. Use g_data_input_stream_read_upto() instead, which has more consistent behaviour regarding the stop character. - + a string with the data that was read + filename="gio/gdatainputstream.c" + line="924">a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. @@ -30015,14 +32253,14 @@ does not consume the stop character. a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="906">a given #GDataInputStream. characters to terminate the read. + filename="gio/gdatainputstream.c" + line="907">characters to terminate the read. optional="1" allow-none="1"> a #gsize to get the length of the data read in. + filename="gio/gdatainputstream.c" + line="908">a #gsize to get the length of the data read in. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="909">optional #GCancellable object, %NULL to ignore. @@ -30051,10 +32289,12 @@ does not consume the stop character. c:identifier="g_data_input_stream_read_until_async" version="2.20" deprecated="1" - deprecated-version="2.56"> + deprecated-version="2.56" + glib:finish-func="read_until_finish" + glib:sync-func="read_until"> The asynchronous version of g_data_input_stream_read_until(). + filename="gio/gdatainputstream.c" + line="1164">The asynchronous version of g_data_input_stream_read_until(). It is an error to have two outstanding calls to this function. Note that, in contrast to g_data_input_stream_read_until(), @@ -30071,27 +32311,27 @@ will be marked as deprecated in a future release. Use g_data_input_stream_read_upto_async() instead. Use g_data_input_stream_read_upto_async() instead, which has more consistent behaviour regarding the stop character. - + a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="1166">a given #GDataInputStream. characters to terminate the read. + filename="gio/gdatainputstream.c" + line="1167">characters to terminate the read. the [I/O priority][io-priority] of the request + filename="gio/gdatainputstream.c" + line="1168">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdatainputstream.c" + line="1169">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> callback to call when the request is satisfied. + filename="gio/gdatainputstream.c" + line="1170">callback to call when the request is satisfied. nullable="1" allow-none="1"> the data to pass to callback function. + filename="gio/gdatainputstream.c" + line="1171">the data to pass to callback function. @@ -30132,16 +32372,16 @@ g_data_input_stream_read_upto_async() instead. deprecated-version="2.56" throws="1"> Finish an asynchronous call started by + filename="gio/gdatainputstream.c" + line="1283">Finish an asynchronous call started by g_data_input_stream_read_until_async(). Use g_data_input_stream_read_upto_finish() instead, which has more consistent behaviour regarding the stop character. - + a string with the data that was read + filename="gio/gdatainputstream.c" + line="1295">a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. @@ -30150,14 +32390,14 @@ g_data_input_stream_read_until_async(). a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="1285">a given #GDataInputStream. the #GAsyncResult that was provided to the callback. + filename="gio/gdatainputstream.c" + line="1286">the #GAsyncResult that was provided to the callback. optional="1" allow-none="1"> a #gsize to get the length of the data read in. + filename="gio/gdatainputstream.c" + line="1287">a #gsize to get the length of the data read in. @@ -30176,10 +32416,11 @@ g_data_input_stream_read_until_async(). + throws="1" + glib:async-func="read_upto_async"> Reads a string from the data input stream, up to the first + filename="gio/gdatainputstream.c" + line="1313">Reads a string from the data input stream, up to the first occurrence of any of the stop characters. In contrast to g_data_input_stream_read_until(), this function @@ -30191,11 +32432,11 @@ Note that @stop_chars may contain '\0' if @stop_chars_len is specified. The returned string will always be nul-terminated on success. - + a string with the data that was read + filename="gio/gdatainputstream.c" + line="1336">a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error @@ -30204,20 +32445,20 @@ The returned string will always be nul-terminated on success. a #GDataInputStream + filename="gio/gdatainputstream.c" + line="1315">a #GDataInputStream characters to terminate the read + filename="gio/gdatainputstream.c" + line="1316">characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is + filename="gio/gdatainputstream.c" + line="1317">length of @stop_chars. May be -1 if @stop_chars is nul-terminated @@ -30228,8 +32469,8 @@ The returned string will always be nul-terminated on success. optional="1" allow-none="1"> a #gsize to get the length of the data read in + filename="gio/gdatainputstream.c" + line="1319">a #gsize to get the length of the data read in nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gdatainputstream.c" + line="1320">optional #GCancellable object, %NULL to ignore + version="2.26" + glib:finish-func="read_upto_finish" + glib:sync-func="read_upto"> The asynchronous version of g_data_input_stream_read_upto(). + filename="gio/gdatainputstream.c" + line="1410">The asynchronous version of g_data_input_stream_read_upto(). It is an error to have two outstanding calls to this function. In contrast to g_data_input_stream_read_until(), this function @@ -30262,34 +32505,34 @@ specified. When the operation is finished, @callback will be called. You can then call g_data_input_stream_read_upto_finish() to get the result of the operation. - + a #GDataInputStream + filename="gio/gdatainputstream.c" + line="1412">a #GDataInputStream characters to terminate the read + filename="gio/gdatainputstream.c" + line="1413">characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is + filename="gio/gdatainputstream.c" + line="1414">length of @stop_chars. May be -1 if @stop_chars is nul-terminated the [I/O priority][io-priority] of the request + filename="gio/gdatainputstream.c" + line="1416">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gdatainputstream.c" + line="1417">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> callback to call when the request is satisfied + filename="gio/gdatainputstream.c" + line="1418">callback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gdatainputstream.c" + line="1419">the data to pass to callback function @@ -30328,8 +32571,8 @@ the result of the operation. version="2.24" throws="1"> Finish an asynchronous call started by + filename="gio/gdatainputstream.c" + line="1455">Finish an asynchronous call started by g_data_input_stream_read_upto_async(). Note that this function does not consume the stop character. You @@ -30337,11 +32580,11 @@ have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto_async() again. The returned string will always be nul-terminated on success. - + a string with the data that was read + filename="gio/gdatainputstream.c" + line="1471">a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. @@ -30350,14 +32593,14 @@ The returned string will always be nul-terminated on success. a #GDataInputStream + filename="gio/gdatainputstream.c" + line="1457">a #GDataInputStream the #GAsyncResult that was provided to the callback + filename="gio/gdatainputstream.c" + line="1458">the #GAsyncResult that was provided to the callback optional="1" allow-none="1"> a #gsize to get the length of the data read in + filename="gio/gdatainputstream.c" + line="1459">a #gsize to get the length of the data read in @@ -30377,24 +32620,24 @@ The returned string will always be nul-terminated on success. c:identifier="g_data_input_stream_set_byte_order" glib:set-property="byte-order"> This function sets the byte order for the given @stream. All subsequent + filename="gio/gdatainputstream.c" + line="189">This function sets the byte order for the given @stream. All subsequent reads from the @stream will be read in the given @order. - + a given #GDataInputStream. + filename="gio/gdatainputstream.c" + line="191">a given #GDataInputStream. a #GDataStreamByteOrder to set. + filename="gio/gdatainputstream.c" + line="192">a #GDataStreamByteOrder to set. @@ -30403,27 +32646,27 @@ reads from the @stream will be read in the given @order. c:identifier="g_data_input_stream_set_newline_type" glib:set-property="newline-type"> Sets the newline type for the @stream. + filename="gio/gdatainputstream.c" + line="232">Sets the newline type for the @stream. Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read chunk ends in "CR" we must read an additional byte to know if this is "CR" or "CR LF", and this might block if there is no more data available. - + a #GDataInputStream. + filename="gio/gdatainputstream.c" + line="234">a #GDataInputStream. the type of new line return as #GDataStreamNewlineType. + filename="gio/gdatainputstream.c" + line="235">the type of new line return as #GDataStreamNewlineType. @@ -30436,8 +32679,8 @@ chunk ends in "CR" we must read an additional byte to know if this is "CR" or getter="get_byte_order" default-value="G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN"> The :byte-order property determines the byte ordering that + filename="gio/gdatainputstream.c" + line="76">The :byte-order property determines the byte ordering that is used when reading multi-byte entities (such as integers) from the stream. @@ -30449,8 +32692,8 @@ from the stream. getter="get_newline_type" default-value="G_DATA_STREAM_NEWLINE_TYPE_LF"> The :newline-type property determines what is considered + filename="gio/gdatainputstream.c" + line="90">The :newline-type property determines what is considered as a line ending when reading complete lines from the stream. @@ -30464,14 +32707,14 @@ as a line ending when reading complete lines from the stream. - + - + @@ -30479,7 +32722,7 @@ as a line ending when reading complete lines from the stream. - + @@ -30487,7 +32730,7 @@ as a line ending when reading complete lines from the stream. - + @@ -30495,7 +32738,7 @@ as a line ending when reading complete lines from the stream. - + @@ -30503,7 +32746,7 @@ as a line ending when reading complete lines from the stream. - + @@ -30514,7 +32757,7 @@ as a line ending when reading complete lines from the stream. c:type="GDataInputStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_data_output_stream_get_type" glib:type-struct="DataOutputStreamClass"> Data output stream implements #GOutputStream and includes functions for -writing data directly to an output stream. - + filename="gio/gdataoutputstream.c" + line="32">Data output stream implements [class@Gio.OutputStream] and includes functions +for writing data directly to an output stream. + Creates a new data output stream for @base_stream. - + filename="gio/gdataoutputstream.c" + line="167">Creates a new data output stream for @base_stream. + #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="173">#GDataOutputStream. a #GOutputStream. + filename="gio/gdataoutputstream.c" + line="169">a #GOutputStream. @@ -30553,20 +32796,20 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_get_byte_order" glib:get-property="byte-order"> Gets the byte order for the stream. - + filename="gio/gdataoutputstream.c" + line="210">Gets the byte order for the stream. + the #GDataStreamByteOrder for the @stream. + filename="gio/gdataoutputstream.c" + line="216">the #GDataStreamByteOrder for the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="212">a #GDataOutputStream. @@ -30575,26 +32818,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_byte" throws="1"> Puts a byte into the output stream. - + filename="gio/gdataoutputstream.c" + line="226">Puts a byte into the output stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="235">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="228">a #GDataOutputStream. a #guchar. + filename="gio/gdataoutputstream.c" + line="229">a #guchar. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="230">optional #GCancellable object, %NULL to ignore. @@ -30612,26 +32855,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_int16" throws="1"> Puts a signed 16-bit integer into the output stream. - + filename="gio/gdataoutputstream.c" + line="253">Puts a signed 16-bit integer into the output stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="262">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="255">a #GDataOutputStream. a #gint16. + filename="gio/gdataoutputstream.c" + line="256">a #gint16. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="257">optional #GCancellable object, %NULL to ignore. @@ -30649,26 +32892,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_int32" throws="1"> Puts a signed 32-bit integer into the output stream. - + filename="gio/gdataoutputstream.c" + line="333">Puts a signed 32-bit integer into the output stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="342">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="335">a #GDataOutputStream. a #gint32. + filename="gio/gdataoutputstream.c" + line="336">a #gint32. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="337">optional #GCancellable object, %NULL to ignore. @@ -30686,26 +32929,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_int64" throws="1"> Puts a signed 64-bit integer into the stream. - + filename="gio/gdataoutputstream.c" + line="413">Puts a signed 64-bit integer into the stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="422">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="415">a #GDataOutputStream. a #gint64. + filename="gio/gdataoutputstream.c" + line="416">a #gint64. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="417">optional #GCancellable object, %NULL to ignore. @@ -30723,26 +32966,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_string" throws="1"> Puts a string into the output stream. - + filename="gio/gdataoutputstream.c" + line="493">Puts a string into the output stream. + %TRUE if @string was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="502">%TRUE if @string was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="495">a #GDataOutputStream. a string. + filename="gio/gdataoutputstream.c" + line="496">a string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="497">optional #GCancellable object, %NULL to ignore. @@ -30760,26 +33003,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_uint16" throws="1"> Puts an unsigned 16-bit integer into the output stream. - + filename="gio/gdataoutputstream.c" + line="293">Puts an unsigned 16-bit integer into the output stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="302">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="295">a #GDataOutputStream. a #guint16. + filename="gio/gdataoutputstream.c" + line="296">a #guint16. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="297">optional #GCancellable object, %NULL to ignore. @@ -30797,26 +33040,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_uint32" throws="1"> Puts an unsigned 32-bit integer into the stream. - + filename="gio/gdataoutputstream.c" + line="373">Puts an unsigned 32-bit integer into the stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="382">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="375">a #GDataOutputStream. a #guint32. + filename="gio/gdataoutputstream.c" + line="376">a #guint32. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="377">optional #GCancellable object, %NULL to ignore. @@ -30834,26 +33077,26 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_put_uint64" throws="1"> Puts an unsigned 64-bit integer into the stream. - + filename="gio/gdataoutputstream.c" + line="453">Puts an unsigned 64-bit integer into the stream. + %TRUE if @data was successfully added to the @stream. + filename="gio/gdataoutputstream.c" + line="462">%TRUE if @data was successfully added to the @stream. a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="455">a #GDataOutputStream. a #guint64. + filename="gio/gdataoutputstream.c" + line="456">a #guint64. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdataoutputstream.c" + line="457">optional #GCancellable object, %NULL to ignore. @@ -30871,23 +33114,23 @@ writing data directly to an output stream. c:identifier="g_data_output_stream_set_byte_order" glib:set-property="byte-order"> Sets the byte order of the data output stream to @order. - + filename="gio/gdataoutputstream.c" + line="189">Sets the byte order of the data output stream to @order. + a #GDataOutputStream. + filename="gio/gdataoutputstream.c" + line="191">a #GDataOutputStream. a %GDataStreamByteOrder. + filename="gio/gdataoutputstream.c" + line="192">a %GDataStreamByteOrder. @@ -30899,8 +33142,8 @@ writing data directly to an output stream. getter="get_byte_order" default-value="G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN"> Determines the byte ordering that is used when writing + filename="gio/gdataoutputstream.c" + line="89">Determines the byte ordering that is used when writing multi-byte entities (such as integers) to the stream. @@ -30915,14 +33158,14 @@ multi-byte entities (such as integers) to the stream. - + - + @@ -30930,7 +33173,7 @@ multi-byte entities (such as integers) to the stream. - + @@ -30938,7 +33181,7 @@ multi-byte entities (such as integers) to the stream. - + @@ -30946,7 +33189,7 @@ multi-byte entities (such as integers) to the stream. - + @@ -30954,7 +33197,7 @@ multi-byte entities (such as integers) to the stream. - + @@ -30965,14 +33208,14 @@ multi-byte entities (such as integers) to the stream. c:type="GDataOutputStreamPrivate" disguised="1" opaque="1"> - + #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures. glib:nick="big-endian" glib:name="G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN"> Selects Big Endian byte order. glib:nick="little-endian" glib:name="G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN"> Selects Little Endian byte order. glib:nick="host-endian" glib:name="G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN"> Selects endianness based on host machine's architecture. @@ -31008,7 +33251,7 @@ across various machine architectures. glib:get-type="g_data_stream_newline_type_get_type" c:type="GDataStreamNewlineType"> #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. glib:nick="lf" glib:name="G_DATA_STREAM_NEWLINE_TYPE_LF"> Selects "LF" line endings, common on most modern UNIX platforms. glib:nick="cr" glib:name="G_DATA_STREAM_NEWLINE_TYPE_CR"> Selects "CR" line endings. glib:nick="cr-lf" glib:name="G_DATA_STREAM_NEWLINE_TYPE_CR_LF"> Selects "CR, LF" line ending, common on Microsoft Windows. glib:nick="any" glib:name="G_DATA_STREAM_NEWLINE_TYPE_ANY"> Automatically try to handle any line ending type. @@ -31055,61 +33298,63 @@ across various machine architectures. glib:get-type="g_datagram_based_get_type" glib:type-struct="DatagramBasedInterface"> A #GDatagramBased is a networking interface for representing datagram-based + filename="gio/gdatagrambased.c" + line="34">Interface for socket-like objects with datagram semantics. + +A `GDatagramBased` is a networking interface for representing datagram-based communications. It is a more or less direct mapping of the core parts of the BSD socket API in a portable GObject interface. It is implemented by -#GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows. +[class@Gio.Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows. -#GDatagramBased is entirely platform independent, and is intended to be used -alongside higher-level networking APIs such as #GIOStream. +`GDatagramBased` is entirely platform independent, and is intended to be used +alongside higher-level networking APIs such as [class@Gio.IOStream]. It uses vectored scatter/gather I/O by default, allowing for many messages to be sent or received in a single call. Where possible, implementations of the interface should take advantage of vectored I/O to minimise processing -or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where -possible. Callers should take advantage of scatter/gather I/O (the use of +or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()` +where possible. Callers should take advantage of scatter/gather I/O (the use of multiple buffers per message) to avoid unnecessary copying of data to assemble or disassemble a message. -Each #GDatagramBased operation has a timeout parameter which may be negative +Each `GDatagramBased` operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a -%G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation +`G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or -%G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would -successfully run you can call g_datagram_based_condition_check() or -g_datagram_based_condition_wait(). You can also use -g_datagram_based_create_source() and attach it to a #GMainContext to get -callbacks when I/O is possible. +`G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would +successfully run you can call [method@Gio.DatagramBased.condition_check] or +[method@Gio.DatagramBased.condition_wait]. You can also use +[method@Gio.DatagramBased.create_source] and attach it to a [struct@GLib.MainContext] +to get callbacks when I/O is possible. When running a non-blocking operation applications should always be able to -handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function +handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write -returns %G_IO_ERROR_WOULD_BLOCK. +returns `G_IO_ERROR_WOULD_BLOCK`. -As with #GSocket, #GDatagramBaseds can be either connection oriented (for -example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be +As with `GSocket`, `GDatagramBased`s can be either connection oriented (for +example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection -before sending and receiving data through the #GDatagramBased API. For +before sending and receiving data through the `GDatagramBased` API. For connectionless socket types the target/source address is specified or received in each I/O operation. -Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. -To use a #GDatagramBased concurrently from multiple threads, you must +Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe. +To use a `GDatagramBased` concurrently from multiple threads, you must implement your own locking. - + Checks on the readiness of @datagram_based to perform operations. The + filename="gio/gdatagrambased.c" + line="353">Checks on the readiness of @datagram_based to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @datagram_based. The result is returned. @@ -31145,24 +33390,24 @@ conditions will always be set in the output if they are true. Apart from these flags, the output is guaranteed to be masked by @condition. This call never blocks. - + the #GIOCondition mask of the current state + filename="gio/gdatagrambased.c" + line="395">the #GIOCondition mask of the current state a #GDatagramBased + filename="gio/gdatagrambased.c" + line="355">a #GDatagramBased a #GIOCondition mask to check + filename="gio/gdatagrambased.c" + line="356">a #GIOCondition mask to check @@ -31172,37 +33417,37 @@ This call never blocks. version="2.48" throws="1"> Waits for up to @timeout microseconds for condition to become true on + filename="gio/gdatagrambased.c" + line="426">Waits for up to @timeout microseconds for condition to become true on @datagram_based. If the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if @timeout is reached before the condition is met, then %FALSE is returned and @error is set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). - + %TRUE if the condition was met, %FALSE otherwise + filename="gio/gdatagrambased.c" + line="442">%TRUE if the condition was met, %FALSE otherwise a #GDatagramBased + filename="gio/gdatagrambased.c" + line="428">a #GDatagramBased a #GIOCondition mask to wait for + filename="gio/gdatagrambased.c" + line="429">a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="430">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31211,8 +33456,8 @@ set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). nullable="1" allow-none="1"> a #GCancellable + filename="gio/gdatagrambased.c" + line="432">a #GCancellable @@ -31221,8 +33466,8 @@ set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). invoker="create_source" version="2.48"> Creates a #GSource that can be attached to a #GMainContext to monitor for + filename="gio/gdatagrambased.c" + line="311">Creates a #GSource that can be attached to a #GMainContext to monitor for the availability of the specified @condition on the #GDatagramBased. The #GSource keeps a reference to the @datagram_based. @@ -31236,24 +33481,24 @@ cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled(). - + a newly allocated #GSource + filename="gio/gdatagrambased.c" + line="332">a newly allocated #GSource a #GDatagramBased + filename="gio/gdatagrambased.c" + line="313">a #GDatagramBased a #GIOCondition mask to monitor + filename="gio/gdatagrambased.c" + line="314">a #GIOCondition mask to monitor nullable="1" allow-none="1"> a #GCancellable + filename="gio/gdatagrambased.c" + line="315">a #GCancellable @@ -31272,8 +33517,8 @@ g_cancellable_is_cancelled(). version="2.48" throws="1"> Receive one or more data messages from @datagram_based in one go. + filename="gio/gdatagrambased.c" + line="98">Receive one or more data messages from @datagram_based in one go. @messages must point to an array of #GInputMessage structs and @num_messages must be the length of this array. Each #GInputMessage @@ -31323,11 +33568,11 @@ be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - + number of messages received, or -1 on error. Note that the number + filename="gio/gdatagrambased.c" + line="160">number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if @timeout is zero or positive, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try @@ -31337,34 +33582,34 @@ other error. a #GDatagramBased + filename="gio/gdatagrambased.c" + line="100">a #GDatagramBased an array of #GInputMessage structs + filename="gio/gdatagrambased.c" + line="101">an array of #GInputMessage structs the number of elements in @messages + filename="gio/gdatagrambased.c" + line="102">the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation + filename="gio/gdatagrambased.c" + line="103">an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="104">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31373,8 +33618,8 @@ other error. nullable="1" allow-none="1"> a %GCancellable + filename="gio/gdatagrambased.c" + line="106">a %GCancellable @@ -31384,8 +33629,8 @@ other error. version="2.48" throws="1"> Send one or more data messages from @datagram_based in one go. + filename="gio/gdatagrambased.c" + line="209">Send one or more data messages from @datagram_based in one go. @messages must point to an array of #GOutputMessage structs and @num_messages must be the length of this array. Each #GOutputMessage @@ -31426,11 +33671,11 @@ On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - + number of messages sent, or -1 on error. Note that the number of + filename="gio/gdatagrambased.c" + line="262">number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if @timeout is zero or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. @@ -31439,34 +33684,34 @@ cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. a #GDatagramBased + filename="gio/gdatagrambased.c" + line="211">a #GDatagramBased an array of #GOutputMessage structs + filename="gio/gdatagrambased.c" + line="212">an array of #GOutputMessage structs the number of elements in @messages + filename="gio/gdatagrambased.c" + line="213">the number of elements in @messages an int containing #GSocketMsgFlags flags + filename="gio/gdatagrambased.c" + line="214">an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="215">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31475,8 +33720,8 @@ cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. nullable="1" allow-none="1"> a %GCancellable + filename="gio/gdatagrambased.c" + line="217">a %GCancellable @@ -31485,8 +33730,8 @@ cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. c:identifier="g_datagram_based_condition_check" version="2.48"> Checks on the readiness of @datagram_based to perform operations. The + filename="gio/gdatagrambased.c" + line="353">Checks on the readiness of @datagram_based to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @datagram_based. The result is returned. @@ -31522,24 +33767,24 @@ conditions will always be set in the output if they are true. Apart from these flags, the output is guaranteed to be masked by @condition. This call never blocks. - + the #GIOCondition mask of the current state + filename="gio/gdatagrambased.c" + line="395">the #GIOCondition mask of the current state a #GDatagramBased + filename="gio/gdatagrambased.c" + line="355">a #GDatagramBased a #GIOCondition mask to check + filename="gio/gdatagrambased.c" + line="356">a #GIOCondition mask to check @@ -31549,37 +33794,37 @@ This call never blocks. version="2.48" throws="1"> Waits for up to @timeout microseconds for condition to become true on + filename="gio/gdatagrambased.c" + line="426">Waits for up to @timeout microseconds for condition to become true on @datagram_based. If the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if @timeout is reached before the condition is met, then %FALSE is returned and @error is set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). - + %TRUE if the condition was met, %FALSE otherwise + filename="gio/gdatagrambased.c" + line="442">%TRUE if the condition was met, %FALSE otherwise a #GDatagramBased + filename="gio/gdatagrambased.c" + line="428">a #GDatagramBased a #GIOCondition mask to wait for + filename="gio/gdatagrambased.c" + line="429">a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="430">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31588,8 +33833,8 @@ set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). nullable="1" allow-none="1"> a #GCancellable + filename="gio/gdatagrambased.c" + line="432">a #GCancellable @@ -31598,8 +33843,8 @@ set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). c:identifier="g_datagram_based_create_source" version="2.48"> Creates a #GSource that can be attached to a #GMainContext to monitor for + filename="gio/gdatagrambased.c" + line="311">Creates a #GSource that can be attached to a #GMainContext to monitor for the availability of the specified @condition on the #GDatagramBased. The #GSource keeps a reference to the @datagram_based. @@ -31613,24 +33858,24 @@ cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled(). - + a newly allocated #GSource + filename="gio/gdatagrambased.c" + line="332">a newly allocated #GSource a #GDatagramBased + filename="gio/gdatagrambased.c" + line="313">a #GDatagramBased a #GIOCondition mask to monitor + filename="gio/gdatagrambased.c" + line="314">a #GIOCondition mask to monitor nullable="1" allow-none="1"> a #GCancellable + filename="gio/gdatagrambased.c" + line="315">a #GCancellable @@ -31649,8 +33894,8 @@ g_cancellable_is_cancelled(). version="2.48" throws="1"> Receive one or more data messages from @datagram_based in one go. + filename="gio/gdatagrambased.c" + line="98">Receive one or more data messages from @datagram_based in one go. @messages must point to an array of #GInputMessage structs and @num_messages must be the length of this array. Each #GInputMessage @@ -31700,11 +33945,11 @@ be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - + number of messages received, or -1 on error. Note that the number + filename="gio/gdatagrambased.c" + line="160">number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if @timeout is zero or positive, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try @@ -31714,34 +33959,34 @@ other error. a #GDatagramBased + filename="gio/gdatagrambased.c" + line="100">a #GDatagramBased an array of #GInputMessage structs + filename="gio/gdatagrambased.c" + line="101">an array of #GInputMessage structs the number of elements in @messages + filename="gio/gdatagrambased.c" + line="102">the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation + filename="gio/gdatagrambased.c" + line="103">an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="104">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31750,8 +33995,8 @@ other error. nullable="1" allow-none="1"> a %GCancellable + filename="gio/gdatagrambased.c" + line="106">a %GCancellable @@ -31761,8 +34006,8 @@ other error. version="2.48" throws="1"> Send one or more data messages from @datagram_based in one go. + filename="gio/gdatagrambased.c" + line="209">Send one or more data messages from @datagram_based in one go. @messages must point to an array of #GOutputMessage structs and @num_messages must be the length of this array. Each #GOutputMessage @@ -31803,11 +34048,11 @@ On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. If @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - + number of messages sent, or -1 on error. Note that the number of + filename="gio/gdatagrambased.c" + line="262">number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if @timeout is zero or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. @@ -31816,34 +34061,34 @@ cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. a #GDatagramBased + filename="gio/gdatagrambased.c" + line="211">a #GDatagramBased an array of #GOutputMessage structs + filename="gio/gdatagrambased.c" + line="212">an array of #GOutputMessage structs the number of elements in @messages + filename="gio/gdatagrambased.c" + line="213">the number of elements in @messages an int containing #GSocketMsgFlags flags + filename="gio/gdatagrambased.c" + line="214">an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="215">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31852,8 +34097,8 @@ cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. nullable="1" allow-none="1"> a %GCancellable + filename="gio/gdatagrambased.c" + line="217">a %GCancellable @@ -31864,26 +34109,29 @@ cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. glib:is-gtype-struct-for="DatagramBased" version="2.48"> Provides an interface for socket-like objects which have datagram semantics, + filename="gio/gdatagrambased.h" + line="46">Provides an interface for socket-like objects which have datagram semantics, following the Berkeley sockets API. The interface methods are thin wrappers around the corresponding virtual methods, and no pre-processing of inputs is implemented — so implementations of this API must handle all functionality documented in the interface methods. - + The parent interface. + filename="gio/gdatagrambased.h" + line="48">The parent interface. + Virtual method for g_datagram_based_receive_messages(). - + number of messages received, or -1 on error. Note that the number + filename="gio/gdatagrambased.c" + line="160">number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if @timeout is zero or positive, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try @@ -31893,34 +34141,34 @@ documented in the interface methods. a #GDatagramBased + filename="gio/gdatagrambased.c" + line="100">a #GDatagramBased an array of #GInputMessage structs + filename="gio/gdatagrambased.c" + line="101">an array of #GInputMessage structs the number of elements in @messages + filename="gio/gdatagrambased.c" + line="102">the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation + filename="gio/gdatagrambased.c" + line="103">an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="104">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31929,20 +34177,23 @@ documented in the interface methods. nullable="1" allow-none="1"> a %GCancellable + filename="gio/gdatagrambased.c" + line="106">a %GCancellable + Virtual method for g_datagram_based_send_messages(). - + number of messages sent, or -1 on error. Note that the number of + filename="gio/gdatagrambased.c" + line="262">number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if @timeout is zero or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. @@ -31951,34 +34202,34 @@ documented in the interface methods. a #GDatagramBased + filename="gio/gdatagrambased.c" + line="211">a #GDatagramBased an array of #GOutputMessage structs + filename="gio/gdatagrambased.c" + line="212">an array of #GOutputMessage structs the number of elements in @messages + filename="gio/gdatagrambased.c" + line="213">the number of elements in @messages an int containing #GSocketMsgFlags flags + filename="gio/gdatagrambased.c" + line="214">an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="215">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -31987,33 +34238,36 @@ documented in the interface methods. nullable="1" allow-none="1"> a %GCancellable + filename="gio/gdatagrambased.c" + line="217">a %GCancellable + Virtual method for g_datagram_based_create_source(). - + a newly allocated #GSource + filename="gio/gdatagrambased.c" + line="332">a newly allocated #GSource a #GDatagramBased + filename="gio/gdatagrambased.c" + line="313">a #GDatagramBased a #GIOCondition mask to monitor + filename="gio/gdatagrambased.c" + line="314">a #GIOCondition mask to monitor nullable="1" allow-none="1"> a #GCancellable + filename="gio/gdatagrambased.c" + line="315">a #GCancellable + Virtual method for g_datagram_based_condition_check(). - + the #GIOCondition mask of the current state + filename="gio/gdatagrambased.c" + line="395">the #GIOCondition mask of the current state a #GDatagramBased + filename="gio/gdatagrambased.c" + line="355">a #GDatagramBased a #GIOCondition mask to check + filename="gio/gdatagrambased.c" + line="356">a #GIOCondition mask to check + Virtual method for + g_datagram_based_condition_wait(). - + %TRUE if the condition was met, %FALSE otherwise + filename="gio/gdatagrambased.c" + line="442">%TRUE if the condition was met, %FALSE otherwise a #GDatagramBased + filename="gio/gdatagrambased.c" + line="428">a #GDatagramBased a #GIOCondition mask to wait for + filename="gio/gdatagrambased.c" + line="429">a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 + filename="gio/gdatagrambased.c" + line="430">the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely @@ -32087,8 +34348,8 @@ documented in the interface methods. nullable="1" allow-none="1"> a #GCancellable + filename="gio/gdatagrambased.c" + line="432">a #GCancellable @@ -32099,28 +34360,28 @@ documented in the interface methods. c:type="GDatagramBasedSourceFunc" version="2.48"> This is the function type of the callback used for the #GSource + filename="gio/giotypes.h" + line="319">This is the function type of the callback used for the #GSource returned by g_datagram_based_create_source(). - + %G_SOURCE_REMOVE if the source should be removed, + filename="gio/giotypes.h" + line="328">%G_SOURCE_REMOVE if the source should be removed, %G_SOURCE_CONTINUE otherwise the #GDatagramBased + filename="gio/giotypes.h" + line="321">the #GDatagramBased the current condition at the source fired + filename="gio/giotypes.h" + line="322">the current condition at the source fired nullable="1" allow-none="1"> data passed in by the user + filename="gio/giotypes.h" + line="323">data passed in by the user @@ -32142,43 +34403,44 @@ returned by g_datagram_based_create_source(). glib:get-type="g_debug_controller_get_type" glib:type-struct="DebugControllerInterface"> #GDebugController is an interface to expose control of debugging features and + filename="gio/gdebugcontroller.c" + line="31">`GDebugController` is an interface to expose control of debugging features and debug output. -It is implemented on Linux using #GDebugControllerDBus, which exposes a D-Bus -interface to allow authenticated peers to control debug features in this -process. +It is implemented on Linux using [class@Gio.DebugControllerDBus], which +exposes a D-Bus interface to allow authenticated peers to control debug +features in this process. Whether debug output is enabled is exposed as -#GDebugController:debug-enabled. This controls g_log_set_debug_enabled() by -default. Application code may connect to the #GObject::notify signal for it +[property@Gio.DebugController:debug-enabled]. This controls +[func@GLib.log_set_debug_enabled] by default. Application code may +connect to the [signal@GObject.Object::notify] signal for it to control other parts of its debug infrastructure as necessary. If your application or service is using the default GLib log writer function, -creating one of the built-in implementations of #GDebugController should be +creating one of the built-in implementations of `GDebugController` should be all that’s needed to dynamically enable or disable debug output. - + Get the value of #GDebugController:debug-enabled. - + filename="gio/gdebugcontroller.c" + line="76">Get the value of #GDebugController:debug-enabled. + %TRUE if debug output should be exposed, %FALSE otherwise + filename="gio/gdebugcontroller.c" + line="82">%TRUE if debug output should be exposed, %FALSE otherwise a #GDebugController + filename="gio/gdebugcontroller.c" + line="78">a #GDebugController @@ -32188,23 +34450,23 @@ all that’s needed to dynamically enable or disable debug output. glib:set-property="debug-enabled" version="2.72"> Set the value of #GDebugController:debug-enabled. - + filename="gio/gdebugcontroller.c" + line="99">Set the value of #GDebugController:debug-enabled. + a #GDebugController + filename="gio/gdebugcontroller.c" + line="101">a #GDebugController %TRUE if debug output should be exposed, %FALSE otherwise + filename="gio/gdebugcontroller.c" + line="102">%TRUE if debug output should be exposed, %FALSE otherwise @@ -32217,8 +34479,8 @@ all that’s needed to dynamically enable or disable debug output. getter="get_debug_enabled" default-value="FALSE"> %TRUE if debug output should be exposed (for example by forwarding it to + filename="gio/gdebugcontroller.c" + line="60">%TRUE if debug output should be exposed (for example by forwarding it to the journal), %FALSE otherwise. @@ -32232,31 +34494,33 @@ the journal), %FALSE otherwise. glib:get-type="g_debug_controller_dbus_get_type" glib:type-struct="DebugControllerDBusClass"> #GDebugControllerDBus is an implementation of #GDebugController which exposes -debug settings as a D-Bus object. + filename="gio/gdebugcontrollerdbus.c" + line="33">`GDebugControllerDBus` is an implementation of [iface@Gio.DebugController] +which exposes debug settings as a D-Bus object. -It is a #GInitable object, and will register an object at +It is a [iface@Gio.Initable] object, and will register an object at `/org/gtk/Debugging` on the bus given as -#GDebugControllerDBus:connection once it’s initialized. The object will be -unregistered when the last reference to the #GDebugControllerDBus is dropped. +[property@Gio.DebugControllerDBus:connection] once it’s initialized. The +object will be unregistered when the last reference to the +`GDebugControllerDBus` is dropped. This D-Bus object can be used by remote processes to enable or disable debug output in this process. Remote processes calling `org.gtk.Debugging.SetDebugEnabled()` will affect the value of -#GDebugController:debug-enabled and, by default, g_log_get_debug_enabled(). -default. +[property@Gio.DebugController:debug-enabled] and, by default, +[func@GLib.log_get_debug_enabled]. By default, no processes are allowed to call `SetDebugEnabled()` unless a -#GDebugControllerDBus::authorize signal handler is installed. This is because -the process may be privileged, or might expose sensitive information in its -debug output. You may want to restrict the ability to enable debug output to -privileged users or processes. +[signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This +is because the process may be privileged, or might expose sensitive +information in its debug output. You may want to restrict the ability to +enable debug output to privileged users or processes. One option is to install a D-Bus security policy which restricts access to `SetDebugEnabled()`, installing something like the following in `$datadir/dbus-1/system.d/`: -|[<!-- language="XML" --> + +```xml <?xml version="1.0"?> <!--*-nxml-*--> <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> @@ -32268,7 +34532,7 @@ One option is to install a D-Bus security policy which restricts access to <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/> </policy> </busconfig> -]| +``` This will prevent the `SetDebugEnabled()` method from being called by all except root. It will not prevent the `DebugEnabled` property from being read, @@ -32276,9 +34540,10 @@ as it’s accessed through the `org.freedesktop.DBus.Properties` interface. Another option is to use polkit to allow or deny requests on a case-by-case basis, allowing for the possibility of dynamic authorisation. To do this, -connect to the #GDebugControllerDBus::authorize signal and query polkit in -it: -|[<!-- language="C" --> +connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query +polkit in it: + +```c g_autoptr(GError) child_error = NULL; g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL); gulong debug_controller_authorize_id = 0; @@ -32287,7 +34552,7 @@ it: debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error)); if (debug_controller == NULL) { - g_error ("Could not register debug controller on bus: %s"), + g_error ("Could not register debug controller on bus: %s", child_error->message); } @@ -32339,8 +34604,8 @@ it: return polkit_authorization_result_get_is_authorized (auth_result); } -]| - +``` + Create a new #GDebugControllerDBus and synchronously initialize it. + filename="gio/gdebugcontrollerdbus.c" + line="628">Create a new #GDebugControllerDBus and synchronously initialize it. Initializing the object will export the debug object on @connection. The object will remain registered until the last reference to the #GDebugControllerDBus is dropped. Initialization may fail if registering the object on @connection fails. - + a new #GDebugControllerDBus, or %NULL + filename="gio/gdebugcontrollerdbus.c" + line="642">a new #GDebugControllerDBus, or %NULL on failure a #GDBusConnection to register the debug object on + filename="gio/gdebugcontrollerdbus.c" + line="630">a #GDBusConnection to register the debug object on nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdebugcontrollerdbus.c" + line="631">a #GCancellable, or %NULL - + Default handler for the #GDebugControllerDBus::authorize signal. + @@ -32400,8 +34668,8 @@ Initialization may fail if registering the object on @connection fails. c:identifier="g_debug_controller_dbus_stop" version="2.72"> Stop the debug controller, unregistering its object from the bus. + filename="gio/gdebugcontrollerdbus.c" + line="662">Stop the debug controller, unregistering its object from the bus. Any pending method calls to the object will complete successfully, but new ones will return an error. This method will block until all pending @@ -32417,15 +34685,15 @@ reference count cycles. Calling this method from within a #GDebugControllerDBus::authorize signal handler will cause a deadlock and must not be done. - + a #GDebugControllerDBus + filename="gio/gdebugcontrollerdbus.c" + line="664">a #GDebugControllerDBus @@ -32436,8 +34704,8 @@ handler will cause a deadlock and must not be done. construct-only="1" transfer-ownership="none"> The D-Bus connection to expose the debugging interface on. + filename="gio/gdebugcontrollerdbus.c" + line="552">The D-Bus connection to expose the debugging interface on. Typically this will be the same connection (to the system or session bus) which the rest of the application or service’s D-Bus objects are registered @@ -32449,8 +34717,8 @@ on. Emitted when a D-Bus peer is trying to change the debug settings and used + filename="gio/gdebugcontrollerdbus.c" + line="574">Emitted when a D-Bus peer is trying to change the debug settings and used to determine if that is authorized. This signal is emitted in a dedicated worker thread, so handlers are @@ -32469,15 +34737,15 @@ Signal handlers must not modify @invocation, or cause it to return a value. The default class handler just returns %TRUE. %TRUE if the call is authorized, %FALSE otherwise. + filename="gio/gdebugcontrollerdbus.c" + line="597">%TRUE if the call is authorized, %FALSE otherwise. A #GDBusMethodInvocation. + filename="gio/gdebugcontrollerdbus.c" + line="577">A #GDBusMethodInvocation. @@ -32488,18 +34756,21 @@ The default class handler just returns %TRUE. glib:is-gtype-struct-for="DebugControllerDBus" version="2.72"> The virtual function table for #GDebugControllerDBus. - + filename="gio/gdebugcontrollerdbus.h" + line="35">The virtual function table for #GDebugControllerDBus. + The parent class. + filename="gio/gdebugcontrollerdbus.h" + line="37">The parent class. + Default handler for the #GDebugControllerDBus::authorize signal. - + @@ -32525,13 +34796,13 @@ The default class handler just returns %TRUE. glib:is-gtype-struct-for="DebugController" version="2.72"> The virtual function table for #GDebugController. - + filename="gio/gdebugcontroller.h" + line="52">The virtual function table for #GDebugController. + The parent interface. + filename="gio/gdebugcontroller.h" + line="54">The parent interface. @@ -32543,42 +34814,42 @@ The default class handler just returns %TRUE. glib:get-type="g_desktop_app_info_get_type" glib:type-struct="DesktopAppInfoClass"> #GDesktopAppInfo is an implementation of #GAppInfo based on + filename="gio/gdesktopappinfo.c" + line="65">`GDesktopAppInfo` is an implementation of [iface@Gio.AppInfo] based on desktop files. Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - +file or the `GioUnix-2.0` GIR namespace when using it. + Creates a new #GDesktopAppInfo based on a desktop file id. + filename="gio/gdesktopappinfo.c" + line="2116">Creates a new [class@Gio.DesktopAppInfo] based on a desktop file ID. -A desktop file id is the basename of the desktop file, including the -.desktop extension. GIO is looking for a desktop file with this name +A desktop file ID is the basename of the desktop file, including the +`.desktop` extension. GIO is looking for a desktop file with this name in the `applications` subdirectories of the XDG data directories (i.e. the directories specified in the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) -(i.e. a desktop id of kde-foo.desktop will match +(i.e. a desktop ID of `kde-foo.desktop` will match `/usr/share/applications/kde/foo.desktop`). - + a new #GDesktopAppInfo, or %NULL if no desktop - file with that id exists. + filename="gio/gdesktopappinfo.c" + line="2132">a new [class@Gio.DesktopAppInfo], or `NULL` if no + desktop file with that ID exists. the desktop file id + filename="gio/gdesktopappinfo.c" + line="2118">the desktop file ID @@ -32586,20 +34857,20 @@ prefix-to-subdirectory mapping that is described in the Creates a new #GDesktopAppInfo. - + filename="gio/gdesktopappinfo.c" + line="2093">Creates a new [class@Gio.DesktopAppInfo]. + a new #GDesktopAppInfo or %NULL on error. + filename="gio/gdesktopappinfo.c" + line="2100">a new [class@Gio.DesktopAppInfo] or `NULL` on error. the path of a desktop file, in the GLib + filename="gio/gdesktopappinfo.c" + line="2095">the path of a desktop file, in the GLib filename encoding @@ -32609,20 +34880,20 @@ prefix-to-subdirectory mapping that is described in the c:identifier="g_desktop_app_info_new_from_keyfile" version="2.18"> Creates a new #GDesktopAppInfo. - + filename="gio/gdesktopappinfo.c" + line="2065">Creates a new [class@Gio.DesktopAppInfo]. + a new #GDesktopAppInfo or %NULL on error. + filename="gio/gdesktopappinfo.c" + line="2071">a new [class@Gio.DesktopAppInfo] or `NULL` on error. an opened #GKeyFile + filename="gio/gdesktopappinfo.c" + line="2067">an opened [type@GLib.KeyFile] @@ -32631,17 +34902,17 @@ prefix-to-subdirectory mapping that is described in the c:identifier="g_desktop_app_info_get_implementations" version="2.42"> Gets all applications that implement @interface. + filename="gio/gdesktopappinfo.c" + line="4665">Gets all applications that implement @interface. An application implements an interface if that interface is listed in -the Implements= line of the desktop file of the application. - +the `Implements` line of the desktop file of the application. + a list of #GDesktopAppInfo -objects. + filename="gio/gdesktopappinfo.c" + line="4674">a list of + [class@Gio.DesktopAppInfo] objects. @@ -32649,16 +34920,16 @@ objects. the name of the interface + filename="gio/gdesktopappinfo.c" + line="4667">the name of the interface Searches desktop files for ones that match @search_string. + filename="gio/gdesktopappinfo.c" + line="4714">Searches desktop files for ones that match @search_string. The return value is an array of strvs. Each strv contains a list of applications that matched @search_string with an equal score. The @@ -32668,18 +34939,18 @@ The algorithm for determining matches is undefined and may change at any time. None of the search results are subjected to the normal validation -checks performed by g_desktop_app_info_new() (for example, checking that +checks performed by [ctor@Gio.DesktopAppInfo.new] (for example, checking that the executable referenced by a result exists), and so it is possible for -g_desktop_app_info_new() to return %NULL when passed an app ID returned by -this function. It is expected that calling code will do this when -subsequently creating a #GDesktopAppInfo for each result. - +[ctor@Gio.DesktopAppInfo.new] to return `NULL` when passed an app ID returned +by this function. It is expected that calling code will do this when +subsequently creating a [class@Gio.DesktopAppInfo] for each result. + a - list of strvs. Free each item with g_strfreev() and free the outer - list with g_free(). + filename="gio/gdesktopappinfo.c" + line="4734">a + list of strvs. Free each item with [func@GLib.strfreev] and free the outer + list with [func@GLib.free]. @@ -32689,8 +34960,8 @@ subsequently creating a #GDesktopAppInfo for each result. the search string to use + filename="gio/gdesktopappinfo.c" + line="4716">the search string to use @@ -32700,25 +34971,27 @@ subsequently creating a #GDesktopAppInfo for each result. deprecated="1" deprecated-version="2.42"> Sets the name of the desktop that the application is running in. -This is used by g_app_info_should_show() and -g_desktop_app_info_get_show_in() to evaluate the -`OnlyShowIn` and `NotShowIn` -desktop entry fields. + filename="gio/gdesktopappinfo.c" + line="3665">Sets the name of the desktop that the application is running in. + +This is used by [method@Gio.AppInfo.should_show] and +[method@Gio.DesktopAppInfo.get_show_in] to evaluate the +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) +keys. Should be called only once; subsequent calls are ignored. do not use this API. Since 2.42 the value of the -`XDG_CURRENT_DESKTOP` environment variable will be used. - + `XDG_CURRENT_DESKTOP` environment variable will be used. + a string specifying what desktop this is + filename="gio/gdesktopappinfo.c" + line="3667">a string specifying what desktop this is @@ -32727,31 +35000,32 @@ Should be called only once; subsequent calls are ignored. c:identifier="g_desktop_app_info_get_action_name" version="2.38"> Gets the user-visible display name of the "additional application -action" specified by @action_name. + filename="gio/gdesktopappinfo.c" + line="5090">Gets the user-visible display name of the +[‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) +specified by @action_name. -This corresponds to the "Name" key within the keyfile group for the +This corresponds to the `Name` key within the keyfile group for the action. - + the locale-specific action name + filename="gio/gdesktopappinfo.c" + line="5103">the locale-specific action name a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="5092">a [class@Gio.DesktopAppInfo] the name of the action as from - g_desktop_app_info_list_actions() + filename="gio/gdesktopappinfo.c" + line="5093">the name of the action as from + [method@Gio.DesktopAppInfo.list_actions] @@ -32760,29 +35034,28 @@ action. c:identifier="g_desktop_app_info_get_boolean" version="2.36"> Looks up a boolean value in the keyfile backing @info. + filename="gio/gdesktopappinfo.c" + line="4978">Looks up a boolean value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. - +The @key is looked up in the `Desktop Entry` group. + the boolean value, or %FALSE if the key - is not found + filename="gio/gdesktopappinfo.c" + line="4987">the boolean value, or `FALSE` if the key is not found a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="4980">a [class@Gio.DesktopAppInfo] the key to look up + filename="gio/gdesktopappinfo.c" + line="4981">the key to look up @@ -32790,21 +35063,23 @@ The @key is looked up in the "Desktop Entry" group. Gets the categories from the desktop file. - + filename="gio/gdesktopappinfo.c" + line="2315">Gets the categories from the desktop file. + The unparsed Categories key from the desktop file; - i.e. no attempt is made to split it by ';' or validate it. + filename="gio/gdesktopappinfo.c" + line="2321">The unparsed + [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories) + from the desktop file; + i.e. no attempt is made to split it by `;` or validate it. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="2317">a [class@Gio.DesktopAppInfo] @@ -32814,23 +35089,23 @@ The @key is looked up in the "Desktop Entry" group. glib:get-property="filename" version="2.24"> When @info was created from a known filename, return it. In some -situations such as the #GDesktopAppInfo returned from -g_desktop_app_info_new_from_keyfile(), this function will return %NULL. - + filename="gio/gdesktopappinfo.c" + line="2265">When @info was created from a known filename, return it. In some +situations such as a [class@Gio.DesktopAppInfo] returned from +[ctor@Gio.DesktopAppInfo.new_from_keyfile], this function will return `NULL`. + The full path to the file for @info, - or %NULL if not known. + filename="gio/gdesktopappinfo.c" + line="2273">The full path to the file for @info, + or `NULL` if not known. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="2267">a [class@Gio.DesktopAppInfo] @@ -32838,20 +35113,21 @@ g_desktop_app_info_new_from_keyfile(), this function will return %NULL. Gets the generic name from the desktop file. - + filename="gio/gdesktopappinfo.c" + line="2349">Gets the generic name from the desktop file. + The value of the GenericName key + filename="gio/gdesktopappinfo.c" + line="2355">The value of the + [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname) a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="2351">a [class@Gio.DesktopAppInfo] @@ -32859,21 +35135,22 @@ g_desktop_app_info_new_from_keyfile(), this function will return %NULL. A desktop file is hidden if the Hidden key in it is -set to True. - + filename="gio/gdesktopappinfo.c" + line="2249">A desktop file is hidden if the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +in it is set to `True`. + %TRUE if hidden, %FALSE otherwise. + filename="gio/gdesktopappinfo.c" + line="2257">`TRUE` if hidden, `FALSE` otherwise. a #GDesktopAppInfo. + filename="gio/gdesktopappinfo.c" + line="2251">a [class@Gio.DesktopAppInfo]. @@ -32882,13 +35159,14 @@ set to True. c:identifier="g_desktop_app_info_get_keywords" version="2.32"> Gets the keywords from the desktop file. - + filename="gio/gdesktopappinfo.c" + line="2332">Gets the keywords from the desktop file. + The value of the Keywords key + filename="gio/gdesktopappinfo.c" + line="2338">The value of the + [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords) @@ -32896,8 +35174,8 @@ set to True. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="2334">a [class@Gio.DesktopAppInfo] @@ -32906,30 +35184,30 @@ set to True. c:identifier="g_desktop_app_info_get_locale_string" version="2.56"> Looks up a localized string value in the keyfile backing @info + filename="gio/gdesktopappinfo.c" + line="4951">Looks up a localized string value in the keyfile backing @info translated to the current locale. -The @key is looked up in the "Desktop Entry" group. - +The @key is looked up in the `Desktop Entry` group. + a newly allocated string, or %NULL if the key - is not found + filename="gio/gdesktopappinfo.c" + line="4961">a newly allocated string, or `NULL` if the key is not + found a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="4953">a [class@Gio.DesktopAppInfo] the key to look up + filename="gio/gdesktopappinfo.c" + line="4954">the key to look up @@ -32938,22 +35216,23 @@ The @key is looked up in the "Desktop Entry" group. c:identifier="g_desktop_app_info_get_nodisplay" version="2.30"> Gets the value of the NoDisplay key, which helps determine if the -application info should be shown in menus. See -%G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). - + filename="gio/gdesktopappinfo.c" + line="2364">Gets the value of the +[`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) + which helps determine if the application info should be shown in menus. See +`G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [method@Gio.AppInfo.should_show]. + The value of the NoDisplay key + filename="gio/gdesktopappinfo.c" + line="2373">The value of the `NoDisplay` key a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="2366">a [class@Gio.DesktopAppInfo] @@ -32962,32 +35241,33 @@ application info should be shown in menus. See c:identifier="g_desktop_app_info_get_show_in" version="2.30"> Checks if the application info should be shown in menus that list available + filename="gio/gdesktopappinfo.c" + line="2383">Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the -`OnlyShowIn` and `NotShowIn` keys. +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) +keys. -@desktop_env should typically be given as %NULL, in which case the +@desktop_env should typically be given as `NULL`, in which case the `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want to override the default mechanism then you may specify @desktop_env, but this is not recommended. -Note that g_app_info_should_show() for @info will include this check (with -%NULL for @desktop_env) as well as additional checks. - +Note that [method@Gio.AppInfo.should_show] for @info will include this check +(with `NULL` for @desktop_env) as well as additional checks. + %TRUE if the @info should be shown in @desktop_env according to the -`OnlyShowIn` and `NotShowIn` keys, %FALSE -otherwise. + filename="gio/gdesktopappinfo.c" + line="2402">`TRUE` if the @info should be shown in @desktop_env according to the +`OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="2385">a [class@Gio.DesktopAppInfo] nullable="1" allow-none="1"> a string specifying a desktop name + filename="gio/gdesktopappinfo.c" + line="2386">a string specifying a desktop name @@ -33005,23 +35285,23 @@ otherwise. c:identifier="g_desktop_app_info_get_startup_wm_class" version="2.34"> Retrieves the StartupWMClass field from @info. This represents the -WM_CLASS property of the main window of the application, if launched + filename="gio/gdesktopappinfo.c" + line="4906">Retrieves the `StartupWMClass` field from @info. This represents the +`WM_CLASS` property of the main window of the application, if launched through @info. - + the startup WM class, or %NULL if none is set -in the desktop file. + filename="gio/gdesktopappinfo.c" + line="4914">the startup WM class, or `NULL` if none + is set in the desktop file. a #GDesktopAppInfo that supports startup notify + filename="gio/gdesktopappinfo.c" + line="4908">a [class@Gio.DesktopAppInfo] that supports startup notify @@ -33030,29 +35310,29 @@ in the desktop file. c:identifier="g_desktop_app_info_get_string" version="2.36"> Looks up a string value in the keyfile backing @info. + filename="gio/gdesktopappinfo.c" + line="4927">Looks up a string value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. - +The @key is looked up in the `Desktop Entry` group. + a newly allocated string, or %NULL if the key - is not found + filename="gio/gdesktopappinfo.c" + line="4936">a newly allocated string, or `NULL` if the key is not + found a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="4929">a [class@Gio.DesktopAppInfo] the key to look up + filename="gio/gdesktopappinfo.c" + line="4930">the key to look up @@ -33061,17 +35341,17 @@ The @key is looked up in the "Desktop Entry" group. c:identifier="g_desktop_app_info_get_string_list" version="2.60"> Looks up a string list value in the keyfile backing @info. + filename="gio/gdesktopappinfo.c" + line="5001">Looks up a string list value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. - +The @key is looked up in the `Desktop Entry` group. + - a %NULL-terminated string array or %NULL if the specified - key cannot be found. The array should be freed with g_strfreev(). + filename="gio/gdesktopappinfo.c" + line="5012"> + a `NULL`-terminated string array or `NULL` if the specified + key cannot be found. The array should be freed with [func@GLib.strfreev]. @@ -33079,14 +35359,14 @@ The @key is looked up in the "Desktop Entry" group. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="5003">a [class@Gio.DesktopAppInfo] the key to look up + filename="gio/gdesktopappinfo.c" + line="5004">the key to look up optional="1" allow-none="1"> return location for the number of returned strings, or %NULL + filename="gio/gdesktopappinfo.c" + line="5005">return location for the number of returned + strings, or `NULL` @@ -33106,27 +35387,27 @@ The @key is looked up in the "Desktop Entry" group. c:identifier="g_desktop_app_info_has_key" version="2.36"> Returns whether @key exists in the "Desktop Entry" group + filename="gio/gdesktopappinfo.c" + line="5029">Returns whether @key exists in the `Desktop Entry` group of the keyfile backing @info. - + %TRUE if the @key exists + filename="gio/gdesktopappinfo.c" + line="5037">`TRUE` if the @key exists a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="5031">a [class@Gio.DesktopAppInfo] the key to look up + filename="gio/gdesktopappinfo.c" + line="5032">the key to look up @@ -33135,38 +35416,39 @@ of the keyfile backing @info. c:identifier="g_desktop_app_info_launch_action" version="2.38"> Activates the named application action. + filename="gio/gdesktopappinfo.c" + line="5133">Activates the named application action. You may only call this function on action names that were -returned from g_desktop_app_info_list_actions(). +returned from [method@Gio.DesktopAppInfo.list_actions]. Note that if the main entry of the desktop file indicates that the application supports startup notification, and @launch_context is -non-%NULL, then startup notification will be used when activating the +non-`NULL`, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional -actions, as per the desktop file specification. +actions, as per the +[desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html). -As with g_app_info_launch() there is no way to detect failures that +As with [method@Gio.AppInfo.launch] there is no way to detect failures that occur while using this function. - + a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="5135">a [class@Gio.DesktopAppInfo] the name of the action as from - g_desktop_app_info_list_actions() + filename="gio/gdesktopappinfo.c" + line="5136">the name of the action as from + [method@Gio.DesktopAppInfo.list_actions] nullable="1" allow-none="1"> a #GAppLaunchContext + filename="gio/gdesktopappinfo.c" + line="5138">a [class@Gio.AppLaunchContext] @@ -33184,40 +35466,41 @@ occur while using this function. c:identifier="g_desktop_app_info_launch_uris_as_manager" throws="1"> This function performs the equivalent of g_app_info_launch_uris(), + filename="gio/gdesktopappinfo.c" + line="3608">This function performs the equivalent of [method@Gio.AppInfo.launch_uris], but is intended primarily for operating system components that launch applications. Ordinary applications should use -g_app_info_launch_uris(). +[method@Gio.AppInfo.launch_uris]. If the application is launched via GSpawn, then @spawn_flags, @user_setup -and @user_setup_data are used for the call to g_spawn_async(). +and @user_setup_data are used for the call to [func@GLib.spawn_async]. Additionally, @pid_callback (with @pid_callback_data) will be called to -inform about the PID of the created process. See g_spawn_async_with_pipes() -for information on certain parameter conditions that can enable an -optimized posix_spawn() codepath to be used. +inform about the PID of the created process. See +[func@GLib.spawn_async_with_pipes] for information on certain parameter +conditions that can enable an optimized [`posix_spawn()`](man:posix_spawn(3)) +code path to be used. -If application launching occurs via some other mechanism (eg: D-Bus +If application launching occurs via some other mechanism (for example, D-Bus activation) then @spawn_flags, @user_setup, @user_setup_data, @pid_callback and @pid_callback_data are ignored. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gdesktopappinfo.c" + line="3638">`TRUE` on successful launch, `FALSE` otherwise. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="3610">a [class@Gio.DesktopAppInfo] List of URIs + filename="gio/gdesktopappinfo.c" + line="3611">List of URIs @@ -33227,14 +35510,14 @@ activation) then @spawn_flags, @user_setup, @user_setup_data, nullable="1" allow-none="1"> a #GAppLaunchContext + filename="gio/gdesktopappinfo.c" + line="3612">a [class@Gio.AppLaunchContext] #GSpawnFlags, used for each process + filename="gio/gdesktopappinfo.c" + line="3613">[flags@GLib.SpawnFlags], used for each process a #GSpawnChildSetupFunc, used once - for each process. + filename="gio/gdesktopappinfo.c" + line="3614">a [callback@GLib.SpawnChildSetupFunc], + used once for each process. + allow-none="1"> User data for @user_setup + filename="gio/gdesktopappinfo.c" + line="3616">User data for @user_setup Callback for child processes + filename="gio/gdesktopappinfo.c" + line="3617">Callback for child processes + allow-none="1"> User data for @callback + filename="gio/gdesktopappinfo.c" + line="3618">User data for @callback @@ -33289,31 +35570,31 @@ activation) then @spawn_flags, @user_setup, @user_setup_data, version="2.58" throws="1"> Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows + filename="gio/gdesktopappinfo.c" + line="3553">Equivalent to [method@Gio.DesktopAppInfo.launch_uris_as_manager] but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process. If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - + %TRUE on successful launch, %FALSE otherwise. + filename="gio/gdesktopappinfo.c" + line="3576">`TRUE` on successful launch, `FALSE` otherwise. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="3555">a [class@Gio.DesktopAppInfo] List of URIs + filename="gio/gdesktopappinfo.c" + line="3556">List of URIs @@ -33323,14 +35604,14 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. nullable="1" allow-none="1"> a #GAppLaunchContext + filename="gio/gdesktopappinfo.c" + line="3557">a [class@Gio.AppLaunchContext] #GSpawnFlags, used for each process + filename="gio/gdesktopappinfo.c" + line="3558">[flags@GLib.SpawnFlags], used for each process scope="async" closure="4"> a #GSpawnChildSetupFunc, used once - for each process. + filename="gio/gdesktopappinfo.c" + line="3559">a + [callback@GLib.SpawnChildSetupFunc], used once for each process. @@ -33351,8 +35632,8 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. nullable="1" allow-none="1"> User data for @user_setup + filename="gio/gdesktopappinfo.c" + line="3561">User data for @user_setup scope="call" closure="6"> Callback for child processes + filename="gio/gdesktopappinfo.c" + line="3562">Callback for child processes @@ -33372,26 +35653,26 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. nullable="1" allow-none="1"> User data for @callback + filename="gio/gdesktopappinfo.c" + line="3563">User data for @callback file descriptor to use for child's stdin, or -1 + filename="gio/gdesktopappinfo.c" + line="3564">file descriptor to use for child’s stdin, or `-1` file descriptor to use for child's stdout, or -1 + filename="gio/gdesktopappinfo.c" + line="3565">file descriptor to use for child’s stdout, or `-1` file descriptor to use for child's stderr, or -1 + filename="gio/gdesktopappinfo.c" + line="3566">file descriptor to use for child’s stderr, or `-1` @@ -33400,17 +35681,19 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. c:identifier="g_desktop_app_info_list_actions" version="2.38"> Returns the list of "additional application actions" supported on the -desktop file, as per the desktop file specification. + filename="gio/gdesktopappinfo.c" + line="5053">Returns the list of +[‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) +supported on the desktop file, as per the desktop file specification. As per the specification, this is the list of actions that are -explicitly listed in the "Actions" key of the [Desktop Entry] group. - +explicitly listed in the `Actions` key of the `Desktop Entry` group. + a list of strings, always non-%NULL + filename="gio/gdesktopappinfo.c" + line="5064">a + list of strings, always non-`NULL` @@ -33418,8 +35701,8 @@ explicitly listed in the "Actions" key of the [Desktop Entry] group. a #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="5055">a [class@Gio.DesktopAppInfo] @@ -33431,15 +35714,15 @@ explicitly listed in the "Actions" key of the [Desktop Entry] group. getter="get_filename" default-value="NULL"> The origin filename of this #GDesktopAppInfo + filename="gio/gdesktopappinfo.c" + line="1777">The origin filename of this [class@Gio.DesktopAppInfo] - + @@ -33453,47 +35736,48 @@ explicitly listed in the "Actions" key of the [Desktop Entry] group. glib:get-type="g_desktop_app_info_lookup_get_type" glib:type-struct="DesktopAppInfoLookupIface"> #GDesktopAppInfoLookup is an opaque data structure and can only be accessed + filename="gio/gdesktopappinfo.c" + line="4846">#GDesktopAppInfoLookup is an opaque data structure and can only be accessed using the following functions. - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. + Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup + filename="gio/gdesktopappinfo.c" + line="4868">Gets the default application for launching applications +using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] implementation. -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends +The [iface@Gio.DesktopAppInfoLookup] interface and this function is used +to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - +directly. Applications should use +[func@Gio.AppInfo.get_default_for_uri_scheme]. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gdesktopappinfo.c" + line="4883">[iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. a #GDesktopAppInfoLookup + filename="gio/gdesktopappinfo.c" + line="4870">a [iface@Gio.DesktopAppInfoLookup] a string containing a URI scheme. + filename="gio/gdesktopappinfo.c" + line="4871">a string containing a URI scheme. @@ -33503,36 +35787,37 @@ directly. Applications should use g_app_info_get_default_for_uri_scheme(). deprecated="1" deprecated-version="2.28"> Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup + filename="gio/gdesktopappinfo.c" + line="4868">Gets the default application for launching applications +using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] implementation. -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends +The [iface@Gio.DesktopAppInfoLookup] interface and this function is used +to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - +directly. Applications should use +[func@Gio.AppInfo.get_default_for_uri_scheme]. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gdesktopappinfo.c" + line="4883">[iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. a #GDesktopAppInfoLookup + filename="gio/gdesktopappinfo.c" + line="4870">a [iface@Gio.DesktopAppInfoLookup] a string containing a URI scheme. + filename="gio/gdesktopappinfo.c" + line="4871">a string containing a URI scheme. @@ -33542,35 +35827,39 @@ directly. Applications should use g_app_info_get_default_for_uri_scheme(). c:type="GDesktopAppInfoLookupIface" glib:is-gtype-struct-for="DesktopAppInfoLookup"> Interface that is used by backends to associate default handlers with URI schemes. - + + Virtual method for + g_desktop_app_info_lookup_get_default_for_uri_scheme(). - + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gdesktopappinfo.c" + line="4883">[iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. a #GDesktopAppInfoLookup + filename="gio/gdesktopappinfo.c" + line="4870">a [iface@Gio.DesktopAppInfoLookup] a string containing a URI scheme. + filename="gio/gdesktopappinfo.c" + line="4871">a string containing a URI scheme. @@ -33580,24 +35869,24 @@ handlers with URI schemes. During invocation, g_desktop_app_info_launch_uris_as_manager() may create one or more child processes. This callback is invoked once for each, providing the process ID. - + a #GDesktopAppInfo Process identifier @@ -33607,7 +35896,7 @@ for each, providing the process ID. allow-none="1" closure="2"> User data @@ -33620,91 +35909,91 @@ for each, providing the process ID. glib:get-type="g_drive_get_type" glib:type-struct="DriveIface"> #GDrive - this represent a piece of hardware connected to the machine. -It's generally only created for removable hardware or hardware with -removable media. + filename="gio/gdrive.c" + line="33">`GDrive` represents a piece of hardware connected to the machine. +It’s generally only created for removable hardware or hardware with +removable media. For example, an optical disc drive, or a USB flash drive. -#GDrive is a container class for #GVolume objects that stem from -the same piece of media. As such, #GDrive abstracts a drive with +`GDrive` is a container class for [iface@Gio.Volume] objects that stem from +the same piece of media. As such, `GDrive` abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media. -If the #GDrive reports that media isn't automatically detected, one +If the `GDrive` reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise. -#GDrive supports starting and stopping drives with authentication +`GDrive` supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual -semantics and side-effects of starting/stopping a #GDrive may vary +semantics and side-effects of starting/stopping a `GDrive` may vary according to implementation. To choose the correct verbs in e.g. a -file manager, use g_drive_get_start_stop_type(). +file manager, use [method@Gio.Drive.get_start_stop_type]. -For porting from GnomeVFS note that there is no equivalent of -#GDrive in that API. - +For [porting from GnomeVFS](migrating-gnome-vfs.html) note that there is no +equivalent of `GDrive` in that API. + Checks if a drive can be ejected. - + filename="gio/gdrive.c" + line="336">Checks if a drive can be ejected. + %TRUE if the @drive can be ejected, %FALSE otherwise. + filename="gio/gdrive.c" + line="342">%TRUE if the @drive can be ejected, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="338">a #GDrive. Checks if a drive can be polled for media changes. - + filename="gio/gdrive.c" + line="359">Checks if a drive can be polled for media changes. + %TRUE if the @drive can be polled for media changes, + filename="gio/gdrive.c" + line="365">%TRUE if the @drive can be polled for media changes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="361">a #GDrive. Checks if a drive can be started. - + filename="gio/gdrive.c" + line="691">Checks if a drive can be started. + %TRUE if the @drive can be started, %FALSE otherwise. + filename="gio/gdrive.c" + line="697">%TRUE if the @drive can be started, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="693">a #GDrive. @@ -33713,46 +36002,49 @@ For porting from GnomeVFS note that there is no equivalent of invoker="can_start_degraded" version="2.22"> Checks if a drive can be started degraded. - + filename="gio/gdrive.c" + line="716">Checks if a drive can be started degraded. + %TRUE if the @drive can be started degraded, %FALSE otherwise. + filename="gio/gdrive.c" + line="722">%TRUE if the @drive can be started degraded, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="718">a #GDrive. Checks if a drive can be stopped. - + filename="gio/gdrive.c" + line="818">Checks if a drive can be stopped. + %TRUE if the @drive can be stopped, %FALSE otherwise. + filename="gio/gdrive.c" + line="824">%TRUE if the @drive can be stopped, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="820">a #GDrive. - + Signal emitted when the drive is changed. + @@ -33763,7 +36055,10 @@ For porting from GnomeVFS note that there is no equivalent of - + The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. + @@ -33776,30 +36071,31 @@ For porting from GnomeVFS note that there is no equivalent of + deprecated-version="2.22" + glib:finish-func="eject_finish"> Asynchronously ejects a drive. + filename="gio/gdrive.c" + line="383">Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation. Use g_drive_eject_with_operation() instead. - + a #GDrive. + filename="gio/gdrive.c" + line="385">a #GDrive. flags affecting the unmount if required for eject + filename="gio/gdrive.c" + line="386">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="387">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="388">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="3"> user data to pass to @callback + filename="gio/gdrive.c" + line="389">user data to pass to @callback - + Signal emitted when the physical eject button (if any) of a drive have been pressed. + @@ -33851,55 +36150,56 @@ result of the operation. deprecated-version="2.22" throws="1"> Finishes ejecting a drive. + filename="gio/gdrive.c" + line="424">Finishes ejecting a drive. Use g_drive_eject_with_operation_finish() instead. - + %TRUE if the drive has been ejected successfully, + filename="gio/gdrive.c" + line="432">%TRUE if the drive has been ejected successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="426">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="427">a #GAsyncResult. + version="2.22" + glib:finish-func="eject_with_operation_finish"> Ejects a drive. This is an asynchronous operation, and is + filename="gio/gdrive.c" + line="457">Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the @drive and #GAsyncResult data returned in the @callback. - + a #GDrive. + filename="gio/gdrive.c" + line="459">a #GDrive. flags affecting the unmount if required for eject + filename="gio/gdrive.c" + line="460">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="461">a #GMountOperation or %NULL to avoid user interaction. @@ -33917,8 +36217,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="463">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="464">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data passed to @callback. + filename="gio/gdrive.c" + line="465">user data passed to @callback. @@ -33949,27 +36249,27 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes ejecting a drive. If any errors occurred during the operation, + filename="gio/gdrive.c" + line="505">Finishes ejecting a drive. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the drive was successfully ejected. %FALSE otherwise. + filename="gio/gdrive.c" + line="515">%TRUE if the drive was successfully ejected. %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="507">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="508">a #GAsyncResult. @@ -33977,15 +36277,15 @@ and #GAsyncResult data returned in the @callback. Gets the kinds of identifiers that @drive has. + filename="gio/gdrive.c" + line="639">Gets the kinds of identifiers that @drive has. Use g_drive_get_identifier() to obtain the identifiers themselves. - + a %NULL-terminated + filename="gio/gdrive.c" + line="647">a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -33995,44 +36295,44 @@ themselves. a #GDrive + filename="gio/gdrive.c" + line="641">a #GDrive Gets the icon for @drive. - + filename="gio/gdrive.c" + line="155">Gets the icon for @drive. + #GIcon for the @drive. + filename="gio/gdrive.c" + line="161">#GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="157">a #GDrive. Gets the identifier of the given kind for @drive. The only + filename="gio/gdrive.c" + line="609">Gets the identifier of the given kind for @drive. The only identifier currently available is %G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. - + a newly allocated string containing the + filename="gio/gdrive.c" + line="618">a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. @@ -34040,35 +36340,35 @@ identifier currently available is a #GDrive + filename="gio/gdrive.c" + line="611">a #GDrive the kind of identifier to return + filename="gio/gdrive.c" + line="612">the kind of identifier to return Gets the name of @drive. - + filename="gio/gdrive.c" + line="134">Gets the name of @drive. + a string containing @drive's name. The returned + filename="gio/gdrive.c" + line="140">a string containing @drive's name. The returned string should be freed when no longer needed. a #GDrive. + filename="gio/gdrive.c" + line="136">a #GDrive. @@ -34077,20 +36377,20 @@ identifier currently available is invoker="get_sort_key" version="2.32"> Gets the sort key for @drive, if any. - + filename="gio/gdrive.c" + line="920">Gets the sort key for @drive, if any. + Sorting key for @drive or %NULL if no such key is available. + filename="gio/gdrive.c" + line="926">Sorting key for @drive or %NULL if no such key is available. A #GDrive. + filename="gio/gdrive.c" + line="922">A #GDrive. @@ -34099,20 +36399,20 @@ identifier currently available is invoker="get_start_stop_type" version="2.22"> Gets a hint about how a drive can be started/stopped. - + filename="gio/gdrive.c" + line="665">Gets a hint about how a drive can be started/stopped. + A value from the #GDriveStartStopType enumeration. + filename="gio/gdrive.c" + line="671">A value from the #GDriveStartStopType enumeration. a #GDrive. + filename="gio/gdrive.c" + line="667">a #GDrive. @@ -34121,37 +36421,37 @@ identifier currently available is invoker="get_symbolic_icon" version="2.34"> Gets the icon for @drive. - + filename="gio/gdrive.c" + line="176">Gets the icon for @drive. + symbolic #GIcon for the @drive. + filename="gio/gdrive.c" + line="182">symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="178">a #GDrive. Get a list of mountable volumes for @drive. + filename="gio/gdrive.c" + line="225">Get a list of mountable volumes for @drive. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + #GList containing any #GVolume objects on the given @drive. + filename="gio/gdrive.c" + line="234">#GList containing any #GVolume objects on the given @drive. @@ -34159,50 +36459,50 @@ its elements have been unreffed with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="227">a #GDrive. Checks if the @drive has media. Note that the OS may not be polling + filename="gio/gdrive.c" + line="314">Checks if the @drive has media. Note that the OS may not be polling the drive for media changes; see g_drive_is_media_check_automatic() for more details. - + %TRUE if @drive has media, %FALSE otherwise. + filename="gio/gdrive.c" + line="322">%TRUE if @drive has media, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="316">a #GDrive. Check if @drive has any mountable volumes. - + filename="gio/gdrive.c" + line="205">Check if @drive has any mountable volumes. + %TRUE if the @drive contains volumes, %FALSE otherwise. + filename="gio/gdrive.c" + line="211">%TRUE if the @drive contains volumes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="207">a #GDrive. @@ -34210,41 +36510,41 @@ for more details. Checks if @drive is capable of automatically detecting media changes. - + filename="gio/gdrive.c" + line="248">Checks if @drive is capable of automatically detecting media changes. + %TRUE if the @drive is capable of automatically detecting + filename="gio/gdrive.c" + line="254">%TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="250">a #GDrive. Checks if the @drive supports removable media. - + filename="gio/gdrive.c" + line="294">Checks if the @drive supports removable media. + %TRUE if @drive supports removable media, %FALSE otherwise. + filename="gio/gdrive.c" + line="300">%TRUE if @drive supports removable media, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="296">a #GDrive. @@ -34253,42 +36553,44 @@ for more details. invoker="is_removable" version="2.50"> Checks if the #GDrive and/or its media is considered removable by the user. + filename="gio/gdrive.c" + line="269">Checks if the #GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable(). - + %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. + filename="gio/gdrive.c" + line="276">%TRUE if @drive and/or its media is considered removable, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="271">a #GDrive. - + Asynchronously polls @drive to see if media has been inserted or removed. + filename="gio/gdrive.c" + line="541">Asynchronously polls @drive to see if media has been inserted or removed. When the operation is finished, @callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation. - + a #GDrive. + filename="gio/gdrive.c" + line="543">a #GDrive. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="544">optional #GCancellable object, %NULL to ignore. scope="async" closure="2"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="545">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="2"> user data to pass to @callback + filename="gio/gdrive.c" + line="546">user data to pass to @callback @@ -34327,54 +36629,57 @@ result of the operation. invoker="poll_for_media_finish" throws="1"> Finishes an operation started with g_drive_poll_for_media() on a drive. - + filename="gio/gdrive.c" + line="578">Finishes an operation started with g_drive_poll_for_media() on a drive. + %TRUE if the drive has been poll_for_mediaed successfully, + filename="gio/gdrive.c" + line="586">%TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="580">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="581">a #GAsyncResult. - + Asynchronously starts a drive. + filename="gio/gdrive.c" + line="741">Asynchronously starts a drive. When the operation is finished, @callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation. - + a #GDrive. + filename="gio/gdrive.c" + line="743">a #GDrive. flags affecting the start operation. + filename="gio/gdrive.c" + line="744">flags affecting the start operation. nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="745">a #GMountOperation or %NULL to avoid user interaction. @@ -34392,8 +36697,8 @@ result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="747">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="748">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data to pass to @callback + filename="gio/gdrive.c" + line="749">user data to pass to @callback @@ -34424,54 +36729,57 @@ result of the operation. version="2.22" throws="1"> Finishes starting a drive. - + filename="gio/gdrive.c" + line="785">Finishes starting a drive. + %TRUE if the drive has been started successfully, + filename="gio/gdrive.c" + line="793">%TRUE if the drive has been started successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="787">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="788">a #GAsyncResult. - + Asynchronously stops a drive. + filename="gio/gdrive.c" + line="843">Asynchronously stops a drive. When the operation is finished, @callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation. - + a #GDrive. + filename="gio/gdrive.c" + line="845">a #GDrive. flags affecting the unmount if required for stopping. + filename="gio/gdrive.c" + line="846">flags affecting the unmount if required for stopping. nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="847">a #GMountOperation or %NULL to avoid user interaction. @@ -34489,8 +36797,8 @@ result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="849">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="850">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data to pass to @callback + filename="gio/gdrive.c" + line="851">user data to pass to @callback - + Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. + @@ -34532,47 +36843,47 @@ result of the operation. version="2.22" throws="1"> Finishes stopping a drive. - + filename="gio/gdrive.c" + line="887">Finishes stopping a drive. + %TRUE if the drive has been stopped successfully, + filename="gio/gdrive.c" + line="895">%TRUE if the drive has been stopped successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="889">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="890">a #GAsyncResult. Checks if a drive can be ejected. - + filename="gio/gdrive.c" + line="336">Checks if a drive can be ejected. + %TRUE if the @drive can be ejected, %FALSE otherwise. + filename="gio/gdrive.c" + line="342">%TRUE if the @drive can be ejected, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="338">a #GDrive. @@ -34580,41 +36891,41 @@ result of the operation. Checks if a drive can be polled for media changes. - + filename="gio/gdrive.c" + line="359">Checks if a drive can be polled for media changes. + %TRUE if the @drive can be polled for media changes, + filename="gio/gdrive.c" + line="365">%TRUE if the @drive can be polled for media changes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="361">a #GDrive. Checks if a drive can be started. - + filename="gio/gdrive.c" + line="691">Checks if a drive can be started. + %TRUE if the @drive can be started, %FALSE otherwise. + filename="gio/gdrive.c" + line="697">%TRUE if the @drive can be started, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="693">a #GDrive. @@ -34623,40 +36934,40 @@ result of the operation. c:identifier="g_drive_can_start_degraded" version="2.22"> Checks if a drive can be started degraded. - + filename="gio/gdrive.c" + line="716">Checks if a drive can be started degraded. + %TRUE if the @drive can be started degraded, %FALSE otherwise. + filename="gio/gdrive.c" + line="722">%TRUE if the @drive can be started degraded, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="718">a #GDrive. Checks if a drive can be stopped. - + filename="gio/gdrive.c" + line="818">Checks if a drive can be stopped. + %TRUE if the @drive can be stopped, %FALSE otherwise. + filename="gio/gdrive.c" + line="824">%TRUE if the @drive can be stopped, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="820">a #GDrive. @@ -34664,30 +36975,31 @@ result of the operation. + deprecated-version="2.22" + glib:finish-func="eject_finish"> Asynchronously ejects a drive. + filename="gio/gdrive.c" + line="383">Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation. Use g_drive_eject_with_operation() instead. - + a #GDrive. + filename="gio/gdrive.c" + line="385">a #GDrive. flags affecting the unmount if required for eject + filename="gio/gdrive.c" + line="386">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="387">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="388">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data to pass to @callback + filename="gio/gdrive.c" + line="389">user data to pass to @callback @@ -34727,55 +37039,56 @@ result of the operation. deprecated-version="2.22" throws="1"> Finishes ejecting a drive. + filename="gio/gdrive.c" + line="424">Finishes ejecting a drive. Use g_drive_eject_with_operation_finish() instead. - + %TRUE if the drive has been ejected successfully, + filename="gio/gdrive.c" + line="432">%TRUE if the drive has been ejected successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="426">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="427">a #GAsyncResult. + version="2.22" + glib:finish-func="eject_with_operation_finish"> Ejects a drive. This is an asynchronous operation, and is + filename="gio/gdrive.c" + line="457">Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the @drive and #GAsyncResult data returned in the @callback. - + a #GDrive. + filename="gio/gdrive.c" + line="459">a #GDrive. flags affecting the unmount if required for eject + filename="gio/gdrive.c" + line="460">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="461">a #GMountOperation or %NULL to avoid user interaction. @@ -34793,8 +37106,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="463">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="464">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gdrive.c" + line="465">user data passed to @callback. @@ -34824,27 +37137,27 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes ejecting a drive. If any errors occurred during the operation, + filename="gio/gdrive.c" + line="505">Finishes ejecting a drive. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the drive was successfully ejected. %FALSE otherwise. + filename="gio/gdrive.c" + line="515">%TRUE if the drive was successfully ejected. %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="507">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="508">a #GAsyncResult. @@ -34852,15 +37165,15 @@ and #GAsyncResult data returned in the @callback. Gets the kinds of identifiers that @drive has. + filename="gio/gdrive.c" + line="639">Gets the kinds of identifiers that @drive has. Use g_drive_get_identifier() to obtain the identifiers themselves. - + a %NULL-terminated + filename="gio/gdrive.c" + line="647">a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -34870,44 +37183,44 @@ themselves. a #GDrive + filename="gio/gdrive.c" + line="641">a #GDrive Gets the icon for @drive. - + filename="gio/gdrive.c" + line="155">Gets the icon for @drive. + #GIcon for the @drive. + filename="gio/gdrive.c" + line="161">#GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="157">a #GDrive. Gets the identifier of the given kind for @drive. The only + filename="gio/gdrive.c" + line="609">Gets the identifier of the given kind for @drive. The only identifier currently available is %G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. - + a newly allocated string containing the + filename="gio/gdrive.c" + line="618">a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. @@ -34915,35 +37228,35 @@ identifier currently available is a #GDrive + filename="gio/gdrive.c" + line="611">a #GDrive the kind of identifier to return + filename="gio/gdrive.c" + line="612">the kind of identifier to return Gets the name of @drive. - + filename="gio/gdrive.c" + line="134">Gets the name of @drive. + a string containing @drive's name. The returned + filename="gio/gdrive.c" + line="140">a string containing @drive's name. The returned string should be freed when no longer needed. a #GDrive. + filename="gio/gdrive.c" + line="136">a #GDrive. @@ -34952,20 +37265,20 @@ identifier currently available is c:identifier="g_drive_get_sort_key" version="2.32"> Gets the sort key for @drive, if any. - + filename="gio/gdrive.c" + line="920">Gets the sort key for @drive, if any. + Sorting key for @drive or %NULL if no such key is available. + filename="gio/gdrive.c" + line="926">Sorting key for @drive or %NULL if no such key is available. A #GDrive. + filename="gio/gdrive.c" + line="922">A #GDrive. @@ -34974,20 +37287,20 @@ identifier currently available is c:identifier="g_drive_get_start_stop_type" version="2.22"> Gets a hint about how a drive can be started/stopped. - + filename="gio/gdrive.c" + line="665">Gets a hint about how a drive can be started/stopped. + A value from the #GDriveStartStopType enumeration. + filename="gio/gdrive.c" + line="671">A value from the #GDriveStartStopType enumeration. a #GDrive. + filename="gio/gdrive.c" + line="667">a #GDrive. @@ -34996,37 +37309,37 @@ identifier currently available is c:identifier="g_drive_get_symbolic_icon" version="2.34"> Gets the icon for @drive. - + filename="gio/gdrive.c" + line="176">Gets the icon for @drive. + symbolic #GIcon for the @drive. + filename="gio/gdrive.c" + line="182">symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="178">a #GDrive. Get a list of mountable volumes for @drive. + filename="gio/gdrive.c" + line="225">Get a list of mountable volumes for @drive. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + #GList containing any #GVolume objects on the given @drive. + filename="gio/gdrive.c" + line="234">#GList containing any #GVolume objects on the given @drive. @@ -35034,50 +37347,50 @@ its elements have been unreffed with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="227">a #GDrive. Checks if the @drive has media. Note that the OS may not be polling + filename="gio/gdrive.c" + line="314">Checks if the @drive has media. Note that the OS may not be polling the drive for media changes; see g_drive_is_media_check_automatic() for more details. - + %TRUE if @drive has media, %FALSE otherwise. + filename="gio/gdrive.c" + line="322">%TRUE if @drive has media, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="316">a #GDrive. Check if @drive has any mountable volumes. - + filename="gio/gdrive.c" + line="205">Check if @drive has any mountable volumes. + %TRUE if the @drive contains volumes, %FALSE otherwise. + filename="gio/gdrive.c" + line="211">%TRUE if the @drive contains volumes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="207">a #GDrive. @@ -35085,21 +37398,21 @@ for more details. Checks if @drive is capable of automatically detecting media changes. - + filename="gio/gdrive.c" + line="248">Checks if @drive is capable of automatically detecting media changes. + %TRUE if the @drive is capable of automatically detecting + filename="gio/gdrive.c" + line="254">%TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="250">a #GDrive. @@ -35107,20 +37420,20 @@ for more details. Checks if the @drive supports removable media. - + filename="gio/gdrive.c" + line="294">Checks if the @drive supports removable media. + %TRUE if @drive supports removable media, %FALSE otherwise. + filename="gio/gdrive.c" + line="300">%TRUE if @drive supports removable media, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="296">a #GDrive. @@ -35129,42 +37442,44 @@ for more details. c:identifier="g_drive_is_removable" version="2.50"> Checks if the #GDrive and/or its media is considered removable by the user. + filename="gio/gdrive.c" + line="269">Checks if the #GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable(). - + %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. + filename="gio/gdrive.c" + line="276">%TRUE if @drive and/or its media is considered removable, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="271">a #GDrive. - + Asynchronously polls @drive to see if media has been inserted or removed. + filename="gio/gdrive.c" + line="541">Asynchronously polls @drive to see if media has been inserted or removed. When the operation is finished, @callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation. - + a #GDrive. + filename="gio/gdrive.c" + line="543">a #GDrive. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="544">optional #GCancellable object, %NULL to ignore. scope="async" closure="2"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="545">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data to pass to @callback + filename="gio/gdrive.c" + line="546">user data to pass to @callback @@ -35202,54 +37517,57 @@ result of the operation. c:identifier="g_drive_poll_for_media_finish" throws="1"> Finishes an operation started with g_drive_poll_for_media() on a drive. - + filename="gio/gdrive.c" + line="578">Finishes an operation started with g_drive_poll_for_media() on a drive. + %TRUE if the drive has been poll_for_mediaed successfully, + filename="gio/gdrive.c" + line="586">%TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="580">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="581">a #GAsyncResult. - + Asynchronously starts a drive. + filename="gio/gdrive.c" + line="741">Asynchronously starts a drive. When the operation is finished, @callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation. - + a #GDrive. + filename="gio/gdrive.c" + line="743">a #GDrive. flags affecting the start operation. + filename="gio/gdrive.c" + line="744">flags affecting the start operation. nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="745">a #GMountOperation or %NULL to avoid user interaction. @@ -35267,8 +37585,8 @@ result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="747">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="748">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data to pass to @callback + filename="gio/gdrive.c" + line="749">user data to pass to @callback @@ -35298,54 +37616,57 @@ result of the operation. version="2.22" throws="1"> Finishes starting a drive. - + filename="gio/gdrive.c" + line="785">Finishes starting a drive. + %TRUE if the drive has been started successfully, + filename="gio/gdrive.c" + line="793">%TRUE if the drive has been started successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="787">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="788">a #GAsyncResult. - + Asynchronously stops a drive. + filename="gio/gdrive.c" + line="843">Asynchronously stops a drive. When the operation is finished, @callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation. - + a #GDrive. + filename="gio/gdrive.c" + line="845">a #GDrive. flags affecting the unmount if required for stopping. + filename="gio/gdrive.c" + line="846">flags affecting the unmount if required for stopping. nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="847">a #GMountOperation or %NULL to avoid user interaction. @@ -35363,8 +37684,8 @@ result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="849">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="850">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data to pass to @callback + filename="gio/gdrive.c" + line="851">user data to pass to @callback @@ -35394,43 +37715,43 @@ result of the operation. version="2.22" throws="1"> Finishes stopping a drive. - + filename="gio/gdrive.c" + line="887">Finishes stopping a drive. + %TRUE if the drive has been stopped successfully, + filename="gio/gdrive.c" + line="895">%TRUE if the drive has been stopped successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="889">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="890">a #GAsyncResult. Emitted when the drive's state has changed. + filename="gio/gdrive.c" + line="70">Emitted when the drive's state has changed. This signal is emitted when the #GDrive have been + filename="gio/gdrive.c" + line="84">This signal is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. @@ -35440,8 +37761,8 @@ finalized. Emitted when the physical eject button (if any) of a drive has + filename="gio/gdrive.c" + line="101">Emitted when the physical eject button (if any) of a drive has been pressed. @@ -35449,8 +37770,8 @@ been pressed. Emitted when the physical stop button (if any) of a drive has + filename="gio/gdrive.c" + line="116">Emitted when the physical stop button (if any) of a drive has been pressed. @@ -35461,18 +37782,21 @@ been pressed. c:type="GDriveIface" glib:is-gtype-struct-for="Drive"> Interface for creating #GDrive implementations. - + The parent interface. + Signal emitted when the drive is changed. - + @@ -35484,8 +37808,11 @@ been pressed. + The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. - + @@ -35497,8 +37824,11 @@ been pressed. + Signal emitted when the physical eject button (if any) of a drive have been pressed. - + @@ -35510,71 +37840,83 @@ been pressed. + Returns the name for the given #GDrive. - + a string containing @drive's name. The returned + filename="gio/gdrive.c" + line="140">a string containing @drive's name. The returned string should be freed when no longer needed. a #GDrive. + filename="gio/gdrive.c" + line="136">a #GDrive. + Returns a #GIcon for the given #GDrive. - + #GIcon for the @drive. + filename="gio/gdrive.c" + line="161">#GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="157">a #GDrive. + Returns %TRUE if the #GDrive has mountable volumes. - + %TRUE if the @drive contains volumes, %FALSE otherwise. + filename="gio/gdrive.c" + line="211">%TRUE if the @drive contains volumes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="207">a #GDrive. + Returns a list #GList of #GVolume for the #GDrive. - + #GList containing any #GVolume objects on the given @drive. + filename="gio/gdrive.c" + line="234">#GList containing any #GVolume objects on the given @drive. @@ -35582,127 +37924,145 @@ been pressed. a #GDrive. + filename="gio/gdrive.c" + line="227">a #GDrive. + Returns %TRUE if the #GDrive supports removal and insertion of media. - + %TRUE if @drive supports removable media, %FALSE otherwise. + filename="gio/gdrive.c" + line="300">%TRUE if @drive supports removable media, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="296">a #GDrive. + Returns %TRUE if the #GDrive has media inserted. - + %TRUE if @drive has media, %FALSE otherwise. + filename="gio/gdrive.c" + line="322">%TRUE if @drive has media, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="316">a #GDrive. + Returns %TRUE if the #GDrive is capable of automatically detecting media changes. - + %TRUE if the @drive is capable of automatically detecting + filename="gio/gdrive.c" + line="254">%TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="250">a #GDrive. + Returns %TRUE if the #GDrive can eject media. - + %TRUE if the @drive can be ejected, %FALSE otherwise. + filename="gio/gdrive.c" + line="342">%TRUE if the @drive can be ejected, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="338">a #GDrive. + Returns %TRUE if the #GDrive is capable of manually polling for media change. - + %TRUE if the @drive can be polled for media changes, + filename="gio/gdrive.c" + line="365">%TRUE if the @drive can be polled for media changes, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="361">a #GDrive. + Ejects a #GDrive. - + a #GDrive. + filename="gio/gdrive.c" + line="385">a #GDrive. flags affecting the unmount if required for eject + filename="gio/gdrive.c" + line="386">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="387">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="388">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data to pass to @callback + filename="gio/gdrive.c" + line="389">user data to pass to @callback + Finishes an eject operation. - + %TRUE if the drive has been ejected successfully, + filename="gio/gdrive.c" + line="432">%TRUE if the drive has been ejected successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="426">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="427">a #GAsyncResult. + Poll for media insertion/removal on a #GDrive. - + a #GDrive. + filename="gio/gdrive.c" + line="543">a #GDrive. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="544">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="545">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="3"> user data to pass to @callback + filename="gio/gdrive.c" + line="546">user data to pass to @callback + Finishes a media poll operation. - + %TRUE if the drive has been poll_for_mediaed successfully, + filename="gio/gdrive.c" + line="586">%TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="580">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="581">a #GAsyncResult. + Returns the identifier of the given kind, or %NULL if + the #GDrive doesn't have one. - + a newly allocated string containing the + filename="gio/gdrive.c" + line="618">a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. @@ -35850,26 +38223,30 @@ been pressed. a #GDrive + filename="gio/gdrive.c" + line="611">a #GDrive the kind of identifier to return + filename="gio/gdrive.c" + line="612">the kind of identifier to return + Returns an array strings listing the kinds + of identifiers which the #GDrive has. - + a %NULL-terminated + filename="gio/gdrive.c" + line="647">a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -35879,87 +38256,99 @@ been pressed. a #GDrive + filename="gio/gdrive.c" + line="641">a #GDrive + Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22. - + A value from the #GDriveStartStopType enumeration. + filename="gio/gdrive.c" + line="671">A value from the #GDriveStartStopType enumeration. a #GDrive. + filename="gio/gdrive.c" + line="667">a #GDrive. + Returns %TRUE if a #GDrive can be started. Since 2.22. - + %TRUE if the @drive can be started, %FALSE otherwise. + filename="gio/gdrive.c" + line="697">%TRUE if the @drive can be started, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="693">a #GDrive. + Returns %TRUE if a #GDrive can be started degraded. Since 2.22. - + %TRUE if the @drive can be started degraded, %FALSE otherwise. + filename="gio/gdrive.c" + line="722">%TRUE if the @drive can be started degraded, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="718">a #GDrive. + Starts a #GDrive. Since 2.22. - + a #GDrive. + filename="gio/gdrive.c" + line="743">a #GDrive. flags affecting the start operation. + filename="gio/gdrive.c" + line="744">flags affecting the start operation. nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="745">a #GMountOperation or %NULL to avoid user interaction. @@ -35977,8 +38366,8 @@ been pressed. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="747">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="748">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="5"> user data to pass to @callback + filename="gio/gdrive.c" + line="749">user data to pass to @callback + Finishes a start operation. Since 2.22. - + %TRUE if the drive has been started successfully, + filename="gio/gdrive.c" + line="793">%TRUE if the drive has been started successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="787">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="788">a #GAsyncResult. + Returns %TRUE if a #GDrive can be stopped. Since 2.22. - + %TRUE if the @drive can be stopped, %FALSE otherwise. + filename="gio/gdrive.c" + line="824">%TRUE if the @drive can be stopped, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="820">a #GDrive. + Stops a #GDrive. Since 2.22. - + a #GDrive. + filename="gio/gdrive.c" + line="845">a #GDrive. flags affecting the unmount if required for stopping. + filename="gio/gdrive.c" + line="846">flags affecting the unmount if required for stopping. nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="847">a #GMountOperation or %NULL to avoid user interaction. @@ -36084,8 +38482,8 @@ been pressed. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="849">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="850">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="5"> user data to pass to @callback + filename="gio/gdrive.c" + line="851">user data to pass to @callback + Finishes a stop operation. Since 2.22. - + %TRUE if the drive has been stopped successfully, + filename="gio/gdrive.c" + line="895">%TRUE if the drive has been stopped successfully, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="889">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="890">a #GAsyncResult. + Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. - + @@ -36152,22 +38556,25 @@ been pressed. + Starts ejecting a #GDrive using a #GMountOperation. Since 2.22. - + a #GDrive. + filename="gio/gdrive.c" + line="459">a #GDrive. flags affecting the unmount if required for eject + filename="gio/gdrive.c" + line="460">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gdrive.c" + line="461">a #GMountOperation or %NULL to avoid user interaction. @@ -36185,8 +38592,8 @@ been pressed. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gdrive.c" + line="463">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gdrive.c" + line="464">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="5"> user data passed to @callback. + filename="gio/gdrive.c" + line="465">user data passed to @callback. + Finishes an eject operation using a #GMountOperation. Since 2.22. - + %TRUE if the drive was successfully ejected. %FALSE otherwise. + filename="gio/gdrive.c" + line="515">%TRUE if the drive was successfully ejected. %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="507">a #GDrive. a #GAsyncResult. + filename="gio/gdrive.c" + line="508">a #GAsyncResult. + Gets a key used for sorting #GDrive instances or %NULL if no such key exists. Since 2.32. - + Sorting key for @drive or %NULL if no such key is available. + filename="gio/gdrive.c" + line="926">Sorting key for @drive or %NULL if no such key is available. A #GDrive. + filename="gio/gdrive.c" + line="922">A #GDrive. + Returns a symbolic #GIcon for the given #GDrive. Since 2.34. - + symbolic #GIcon for the @drive. + filename="gio/gdrive.c" + line="182">symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). a #GDrive. + filename="gio/gdrive.c" + line="178">a #GDrive. + Returns %TRUE if the #GDrive and/or its media is considered removable by the user. Since 2.50. - + %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. + filename="gio/gdrive.c" + line="276">%TRUE if @drive and/or its media is considered removable, %FALSE otherwise. a #GDrive. + filename="gio/gdrive.c" + line="271">a #GDrive. @@ -36303,7 +38722,7 @@ been pressed. glib:get-type="g_drive_start_flags_get_type" c:type="GDriveStartFlags"> Flags used when starting a drive. glib:nick="none" glib:name="G_DRIVE_START_NONE"> No flags set. @@ -36321,7 +38740,7 @@ been pressed. glib:get-type="g_drive_start_stop_type_get_type" c:type="GDriveStartStopType"> Enumeration describing how a drive can be started/stopped. glib:nick="unknown" glib:name="G_DRIVE_START_STOP_TYPE_UNKNOWN"> Unknown or drive doesn't support start/stop. @@ -36339,7 +38758,7 @@ been pressed. glib:nick="shutdown" glib:name="G_DRIVE_START_STOP_TYPE_SHUTDOWN"> The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. @@ -36350,7 +38769,7 @@ been pressed. glib:nick="network" glib:name="G_DRIVE_START_STOP_TYPE_NETWORK"> The start/stop methods are used for connecting/disconnect to the drive over the network. @@ -36360,7 +38779,7 @@ been pressed. glib:nick="multidisk" glib:name="G_DRIVE_START_STOP_TYPE_MULTIDISK"> The start/stop methods will assemble/disassemble a virtual drive from several physical drives. @@ -36371,10 +38790,10 @@ been pressed. glib:nick="password" glib:name="G_DRIVE_START_STOP_TYPE_PASSWORD"> The start/stop methods will - unlock/lock the disk (for example using the ATA <quote>SECURITY - UNLOCK DEVICE</quote> command) + unlock/lock the disk (for example using the ATA `SECURITY UNLOCK + DEVICE` command) glib:get-type="g_dtls_client_connection_get_type" glib:type-struct="DtlsClientConnectionInterface"> #GDtlsClientConnection is the client-side subclass of -#GDtlsConnection, representing a client-side DTLS connection. - + filename="gio/gdtlsclientconnection.c" + line="34">`GDtlsClientConnection` is the client-side subclass of +[iface@Gio.DtlsConnection], representing a client-side DTLS connection. + version="2.48" throws="1"> Creates a new #GDtlsClientConnection wrapping @base_socket which is + filename="gio/gdtlsclientconnection.c" + line="126">Creates a new #GDtlsClientConnection wrapping @base_socket which is assumed to communicate with the server identified by @server_identity. - + the new + filename="gio/gdtlsclientconnection.c" + line="135">the new #GDtlsClientConnection, or %NULL on error the #GDatagramBased to wrap + filename="gio/gdtlsclientconnection.c" + line="128">the #GDatagramBased to wrap nullable="1" allow-none="1"> the expected identity of the server + filename="gio/gdtlsclientconnection.c" + line="129">the expected identity of the server @@ -36430,19 +38849,19 @@ assumed to communicate with the server identified by @server_identity. glib:get-property="accepted-cas" version="2.48"> Gets the list of distinguished names of the Certificate Authorities + filename="gio/gdtlsclientconnection.c" + line="256">Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be %NULL. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. - + the list of + filename="gio/gdtlsclientconnection.c" + line="268">the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free(). @@ -36454,8 +38873,8 @@ the free the list with g_list_free(). the #GDtlsClientConnection + filename="gio/gdtlsclientconnection.c" + line="258">the #GDtlsClientConnection @@ -36465,13 +38884,13 @@ the free the list with g_list_free(). glib:get-property="server-identity" version="2.48"> Gets @conn's expected server identity - + filename="gio/gdtlsclientconnection.c" + line="210">Gets @conn's expected server identity + a #GSocketConnectable describing the + filename="gio/gdtlsclientconnection.c" + line="216">a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. @@ -36479,8 +38898,8 @@ known. the #GDtlsClientConnection + filename="gio/gdtlsclientconnection.c" + line="212">the #GDtlsClientConnection @@ -36492,25 +38911,25 @@ known. deprecated="1" deprecated-version="2.74"> Gets @conn's validation flags + filename="gio/gdtlsclientconnection.c" + line="157">Gets @conn's validation flags This function does not work as originally designed and is impossible to use correctly. See #GDtlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. - + the validation flags + filename="gio/gdtlsclientconnection.c" + line="167">the validation flags the #GDtlsClientConnection + filename="gio/gdtlsclientconnection.c" + line="159">the #GDtlsClientConnection @@ -36520,26 +38939,26 @@ information. glib:set-property="server-identity" version="2.48"> Sets @conn's expected server identity, which is used both to tell + filename="gio/gdtlsclientconnection.c" + line="235">Sets @conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let @conn know what name to look for in the certificate when performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - + the #GDtlsClientConnection + filename="gio/gdtlsclientconnection.c" + line="237">the #GDtlsClientConnection a #GSocketConnectable describing the expected server identity + filename="gio/gdtlsclientconnection.c" + line="238">a #GSocketConnectable describing the expected server identity @@ -36551,8 +38970,8 @@ performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. deprecated="1" deprecated-version="2.74"> Sets @conn's validation flags, to override the default set of + filename="gio/gdtlsclientconnection.c" + line="184">Sets @conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, %G_TLS_CERTIFICATE_VALIDATE_ALL is used. @@ -36560,21 +38979,21 @@ This function does not work as originally designed and is impossible to use correctly. See #GDtlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. - + the #GDtlsClientConnection + filename="gio/gdtlsclientconnection.c" + line="186">the #GDtlsClientConnection the #GTlsCertificateFlags to use + filename="gio/gdtlsclientconnection.c" + line="187">the #GTlsCertificateFlags to use @@ -36584,8 +39003,8 @@ information. transfer-ownership="none" getter="get_accepted_cas"> A list of the distinguished names of the Certificate Authorities + filename="gio/gdtlsclientconnection.c" + line="107">A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. @@ -36604,8 +39023,8 @@ subject DN of the certificate authority. setter="set_server_identity" getter="get_server_identity"> A #GSocketConnectable describing the identity of the server that + filename="gio/gdtlsclientconnection.c" + line="80">A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in @@ -36632,8 +39051,8 @@ virtual hosts. getter="get_validation_flags" default-value="G_TLS_CERTIFICATE_UNKNOWN_CA | G_TLS_CERTIFICATE_BAD_IDENTITY | G_TLS_CERTIFICATE_NOT_ACTIVATED | G_TLS_CERTIFICATE_EXPIRED | G_TLS_CERTIFICATE_REVOKED | G_TLS_CERTIFICATE_INSECURE | G_TLS_CERTIFICATE_GENERIC_ERROR"> What steps to perform when validating a certificate received from + filename="gio/gdtlsclientconnection.c" + line="48">What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GDtlsConnection::accept-certificate. @@ -36658,12 +39077,12 @@ connect to #GDtlsConnection::accept-certificate. glib:is-gtype-struct-for="DtlsClientConnection" version="2.48"> vtable for a #GDtlsClientConnection implementation. - + The parent interface. @@ -36676,30 +39095,35 @@ connect to #GDtlsConnection::accept-certificate. glib:get-type="g_dtls_connection_get_type" glib:type-struct="DtlsConnectionInterface"> #GDtlsConnection is the base DTLS connection class type, which wraps -a #GDatagramBased and provides DTLS encryption on top of it. Its -subclasses, #GDtlsClientConnection and #GDtlsServerConnection, -implement client-side and server-side DTLS, respectively. + filename="gio/gdtlsconnection.c" + line="38">`GDtlsConnection` is the base DTLS connection class type, which wraps +a [iface@Gio.DatagramBased] and provides DTLS encryption on top of it. Its +subclasses, [iface@Gio.DtlsClientConnection] and +[iface@Gio.DtlsServerConnection], implement client-side and server-side DTLS, +respectively. -For TLS support, see #GTlsConnection. +For TLS support, see [class@Gio.TlsConnection]. -As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased, -presenting a datagram-socket-like API for the encrypted connection. This -operates over a base datagram connection, which is also a #GDatagramBased -(#GDtlsConnection:base-socket). +As DTLS is datagram based, `GDtlsConnection` implements +[iface@Gio.DatagramBased], presenting a datagram-socket-like API for the +encrypted connection. This operates over a base datagram connection, which is +also a `GDatagramBased` ([property@Gio.DtlsConnection:base-socket]). -To close a DTLS connection, use g_dtls_connection_close(). +To close a DTLS connection, use [method@Gio.DtlsConnection.close]. -Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address -on their base #GDatagramBased if it is a #GSocket — it is up to the caller to -do that if they wish. If they do not, and g_socket_close() is called on the -base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED -error on further I/O. - +Neither [iface@Gio.DtlsServerConnection] or [iface@Gio.DtlsClientConnection] +set the peer address on their base [iface@Gio.DatagramBased] if it is a +[class@Gio.Socket] — it is up to the caller to do that if they wish. If they +do not, and [method@Gio.Socket.close] is called on the base socket, the +`GDtlsConnection` will not raise a `G_IO_ERROR_NOT_CONNECTED` error on +further I/O. + - + Check whether to accept a certificate. + @@ -36716,7 +39140,10 @@ error on further I/O. - + Retrieve TLS channel binding data (Since: 2.66) + @@ -36739,26 +39166,26 @@ error on further I/O. invoker="get_negotiated_protocol" version="2.60"> Gets the name of the application-layer protocol negotiated during + filename="gio/gdtlsconnection.c" + line="1084">Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_dtls_connection_set_advertised_protocols(). - + the negotiated protocol, or %NULL + filename="gio/gdtlsconnection.c" + line="1096">the negotiated protocol, or %NULL a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1086">a #GDtlsConnection @@ -36766,10 +39193,11 @@ g_dtls_connection_set_advertised_protocols(). + throws="1" + glib:async-func="handshake_async"> Attempts a TLS handshake on @conn. + filename="gio/gdtlsconnection.c" + line="707">Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after @@ -36795,18 +39223,18 @@ the initial handshake will no longer do anything. #GDtlsConnection::accept_certificate may be emitted during the handshake. - + success or failure + filename="gio/gdtlsconnection.c" + line="740">success or failure a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="709">a #GDtlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="710">a #GCancellable, or %NULL + version="2.48" + glib:finish-func="handshake_finish" + glib:sync-func="handshake"> Asynchronously performs a TLS handshake on @conn. See + filename="gio/gdtlsconnection.c" + line="755">Asynchronously performs a TLS handshake on @conn. See g_dtls_connection_handshake() for more information. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="757">a #GDtlsConnection the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="758">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="759">a #GCancellable, or %NULL scope="async" closure="3"> callback to call when the handshake is complete + filename="gio/gdtlsconnection.c" + line="760">callback to call when the handshake is complete allow-none="1" closure="3"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="761">the data to pass to the callback function @@ -36881,28 +39311,28 @@ g_dtls_connection_handshake() for more information. version="2.48" throws="1"> Finish an asynchronous TLS handshake operation. See + filename="gio/gdtlsconnection.c" + line="782">Finish an asynchronous TLS handshake operation. See g_dtls_connection_handshake() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="791">%TRUE on success, %FALSE on failure, in which case @error will be set. a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="784">a #GDtlsConnection a #GAsyncResult. + filename="gio/gdtlsconnection.c" + line="785">a #GAsyncResult. @@ -36911,8 +39341,8 @@ case @error will be set. invoker="set_advertised_protocols" version="2.60"> Sets the list of application-layer protocols to advertise that the + filename="gio/gdtlsconnection.c" + line="1052">Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use @@ -36922,15 +39352,15 @@ of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1054">a #GDtlsConnection nullable="1" allow-none="1"> a %NULL-terminated + filename="gio/gdtlsconnection.c" + line="1055">a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL @@ -36950,10 +39380,11 @@ for a list of registered protocol IDs. + throws="1" + glib:async-func="shutdown_async"> Shut down part or all of a DTLS connection. + filename="gio/gdtlsconnection.c" + line="808">Shut down part or all of a DTLS connection. If @shutdown_read is %TRUE then the receiving side of the connection is shut down, and further reading is disallowed. Subsequent calls to @@ -36969,30 +39400,30 @@ is equivalent to calling g_dtls_connection_close(). If @cancellable is cancelled, the #GDtlsConnection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. - + %TRUE on success, %FALSE otherwise + filename="gio/gdtlsconnection.c" + line="833">%TRUE on success, %FALSE otherwise a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="810">a #GDtlsConnection %TRUE to stop reception of incoming datagrams + filename="gio/gdtlsconnection.c" + line="811">%TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams + filename="gio/gdtlsconnection.c" + line="812">%TRUE to stop sending outgoing datagrams a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="813">a #GCancellable, or %NULL + version="2.48" + glib:finish-func="shutdown_finish" + glib:sync-func="shutdown"> Asynchronously shut down part or all of the DTLS connection. See + filename="gio/gdtlsconnection.c" + line="861">Asynchronously shut down part or all of the DTLS connection. See g_dtls_connection_shutdown() for more information. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="863">a #GDtlsConnection %TRUE to stop reception of incoming datagrams + filename="gio/gdtlsconnection.c" + line="864">%TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams + filename="gio/gdtlsconnection.c" + line="865">%TRUE to stop sending outgoing datagrams the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="866">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="867">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the shutdown operation is complete + filename="gio/gdtlsconnection.c" + line="868">callback to call when the shutdown operation is complete allow-none="1" closure="5"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="869">the data to pass to the callback function @@ -37079,28 +39512,28 @@ g_dtls_connection_shutdown() for more information. version="2.48" throws="1"> Finish an asynchronous TLS shutdown operation. See + filename="gio/gdtlsconnection.c" + line="897">Finish an asynchronous TLS shutdown operation. See g_dtls_connection_shutdown() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="906">%TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="899">a #GDtlsConnection a #GAsyncResult + filename="gio/gdtlsconnection.c" + line="900">a #GAsyncResult @@ -37108,10 +39541,11 @@ case @error will be set + throws="1" + glib:async-func="close_async"> Close the DTLS connection. This is equivalent to calling + filename="gio/gdtlsconnection.c" + line="927">Close the DTLS connection. This is equivalent to calling g_dtls_connection_shutdown() to shut down both sides of the connection. Closing a #GDtlsConnection waits for all buffered but untransmitted data to @@ -37130,18 +39564,18 @@ released as early as possible. If @cancellable is cancelled, the #GDtlsConnection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_close() again to complete closing the #GDtlsConnection. - + %TRUE on success, %FALSE otherwise + filename="gio/gdtlsconnection.c" + line="953">%TRUE on success, %FALSE otherwise a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="929">a #GDtlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="930">a #GCancellable, or %NULL + version="2.48" + glib:finish-func="close_finish" + glib:sync-func="close"> Asynchronously close the DTLS connection. See g_dtls_connection_close() for + filename="gio/gdtlsconnection.c" + line="971">Asynchronously close the DTLS connection. See g_dtls_connection_close() for more information. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="973">a #GDtlsConnection the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="974">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="975">a #GCancellable, or %NULL scope="async" closure="3"> callback to call when the close operation is complete + filename="gio/gdtlsconnection.c" + line="976">callback to call when the close operation is complete nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="977">the data to pass to the callback function @@ -37215,28 +39651,28 @@ more information. version="2.48" throws="1"> Finish an asynchronous TLS close operation. See g_dtls_connection_close() + filename="gio/gdtlsconnection.c" + line="1000">Finish an asynchronous TLS close operation. See g_dtls_connection_close() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="1009">%TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1002">a #GDtlsConnection a #GAsyncResult + filename="gio/gdtlsconnection.c" + line="1003">a #GAsyncResult @@ -37245,34 +39681,34 @@ case @error will be set c:identifier="g_dtls_connection_emit_accept_certificate" version="2.48"> Used by #GDtlsConnection implementations to emit the + filename="gio/gdtlsconnection.c" + line="1026">Used by #GDtlsConnection implementations to emit the #GDtlsConnection::accept-certificate signal. - + %TRUE if one of the signal handlers has returned + filename="gio/gdtlsconnection.c" + line="1035">%TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1028">a #GDtlsConnection the peer's #GTlsCertificate + filename="gio/gdtlsconnection.c" + line="1029">the peer's #GTlsCertificate the problems with @peer_cert + filename="gio/gdtlsconnection.c" + line="1030">the problems with @peer_cert @@ -37282,21 +39718,21 @@ case @error will be set glib:get-property="certificate" version="2.48"> Gets @conn's certificate, as set by + filename="gio/gdtlsconnection.c" + line="452">Gets @conn's certificate, as set by g_dtls_connection_set_certificate(). - + @conn's certificate, or %NULL + filename="gio/gdtlsconnection.c" + line="459">@conn's certificate, or %NULL a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="454">a #GDtlsConnection @@ -37306,8 +39742,8 @@ g_dtls_connection_set_certificate(). version="2.66" throws="1"> Query the TLS backend for TLS channel binding data of @type for @conn. + filename="gio/gdtlsconnection.c" + line="1112">Query the TLS backend for TLS channel binding data of @type for @conn. This call retrieves TLS channel binding data as specified in RFC [5056](https://tools.ietf.org/html/rfc5056), RFC @@ -37320,24 +39756,24 @@ is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support @type or the binding data is not available yet due to additional negotiation or input required. - + %TRUE on success, %FALSE otherwise + filename="gio/gdtlsconnection.c" + line="1134">%TRUE on success, %FALSE otherwise a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1114">a #GDtlsConnection #GTlsChannelBindingType type of data to fetch + filename="gio/gdtlsconnection.c" + line="1115">#GTlsChannelBindingType type of data to fetch @@ -37348,8 +39784,8 @@ negotiation or input required. optional="1" allow-none="1"> #GByteArray is + filename="gio/gdtlsconnection.c" + line="1116">#GByteArray is filled with the binding data, or %NULL @@ -37362,8 +39798,8 @@ negotiation or input required. glib:get-property="ciphersuite-name" version="2.70"> Returns the name of the current DTLS ciphersuite, or %NULL if the + filename="gio/gdtlsconnection.c" + line="1193">Returns the name of the current DTLS ciphersuite, or %NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that @@ -37371,18 +39807,18 @@ are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended. - + The name of the current DTLS ciphersuite, or %NULL + filename="gio/gdtlsconnection.c" + line="1206">The name of the current DTLS ciphersuite, or %NULL a #GDTlsConnection + filename="gio/gdtlsconnection.c" + line="1195">a #GDTlsConnection @@ -37392,21 +39828,21 @@ is not recommended. glib:get-property="database" version="2.48"> Gets the certificate database that @conn uses to verify + filename="gio/gdtlsconnection.c" + line="390">Gets the certificate database that @conn uses to verify peer certificates. See g_dtls_connection_set_database(). - + the certificate database that @conn uses or %NULL + filename="gio/gdtlsconnection.c" + line="397">the certificate database that @conn uses or %NULL a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="392">a #GDtlsConnection @@ -37416,22 +39852,22 @@ peer certificates. See g_dtls_connection_set_database(). glib:get-property="interaction" version="2.48"> Get the object that will be used to interact with the user. It will be used + filename="gio/gdtlsconnection.c" + line="501">Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. - + The interaction object. + filename="gio/gdtlsconnection.c" + line="509">The interaction object. a connection + filename="gio/gdtlsconnection.c" + line="503">a connection @@ -37441,26 +39877,26 @@ no user interaction will occur for this connection. glib:get-property="negotiated-protocol" version="2.60"> Gets the name of the application-layer protocol negotiated during + filename="gio/gdtlsconnection.c" + line="1084">Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_dtls_connection_set_advertised_protocols(). - + the negotiated protocol, or %NULL + filename="gio/gdtlsconnection.c" + line="1096">the negotiated protocol, or %NULL a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1086">a #GDtlsConnection @@ -37470,22 +39906,22 @@ g_dtls_connection_set_advertised_protocols(). glib:get-property="peer-certificate" version="2.48"> Gets @conn's peer's certificate after the handshake has completed + filename="gio/gdtlsconnection.c" + line="527">Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) - + @conn's peer's certificate, or %NULL + filename="gio/gdtlsconnection.c" + line="535">@conn's peer's certificate, or %NULL a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="529">a #GDtlsConnection @@ -37495,22 +39931,22 @@ or failed. (It is not set during the emission of glib:get-property="peer-certificate-errors" version="2.48"> Gets the errors associated with validating @conn's peer's + filename="gio/gdtlsconnection.c" + line="553">Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) - + @conn's peer's certificate errors + filename="gio/gdtlsconnection.c" + line="561">@conn's peer's certificate errors a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="555">a #GDtlsConnection @@ -37520,23 +39956,23 @@ not set during the emission of #GDtlsConnection::accept-certificate.) glib:get-property="protocol-version" version="2.70"> Returns the current DTLS protocol version, which may be + filename="gio/gdtlsconnection.c" + line="1161">Returns the current DTLS protocol version, which may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized #GTlsProtocolVersion. - + The current DTLS protocol version + filename="gio/gdtlsconnection.c" + line="1170">The current DTLS protocol version a #GDTlsConnection + filename="gio/gdtlsconnection.c" + line="1163">a #GDTlsConnection @@ -37548,24 +39984,24 @@ that is not a recognized #GTlsProtocolVersion. deprecated="1" deprecated-version="2.64."> Gets @conn rehandshaking mode. See + filename="gio/gdtlsconnection.c" + line="674">Gets @conn rehandshaking mode. See g_dtls_connection_set_rehandshake_mode() for details. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. - + %G_TLS_REHANDSHAKE_SAFELY + filename="gio/gdtlsconnection.c" + line="681">%G_TLS_REHANDSHAKE_SAFELY a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="676">a #GDtlsConnection @@ -37575,22 +40011,22 @@ g_dtls_connection_set_rehandshake_mode() for details. glib:get-property="require-close-notify" version="2.48"> Tests whether or not @conn expects a proper TLS close notification + filename="gio/gdtlsconnection.c" + line="620">Tests whether or not @conn expects a proper TLS close notification when the connection is closed. See g_dtls_connection_set_require_close_notify() for details. - + %TRUE if @conn requires a proper TLS close notification. + filename="gio/gdtlsconnection.c" + line="628">%TRUE if @conn requires a proper TLS close notification. a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="622">a #GDtlsConnection @@ -37598,10 +40034,11 @@ g_dtls_connection_set_require_close_notify() for details. + throws="1" + glib:async-func="handshake_async"> Attempts a TLS handshake on @conn. + filename="gio/gdtlsconnection.c" + line="707">Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after @@ -37627,18 +40064,18 @@ the initial handshake will no longer do anything. #GDtlsConnection::accept_certificate may be emitted during the handshake. - + success or failure + filename="gio/gdtlsconnection.c" + line="740">success or failure a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="709">a #GDtlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="710">a #GCancellable, or %NULL + version="2.48" + glib:finish-func="handshake_finish" + glib:sync-func="handshake"> Asynchronously performs a TLS handshake on @conn. See + filename="gio/gdtlsconnection.c" + line="755">Asynchronously performs a TLS handshake on @conn. See g_dtls_connection_handshake() for more information. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="757">a #GDtlsConnection the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="758">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="759">a #GCancellable, or %NULL scope="async" closure="3"> callback to call when the handshake is complete + filename="gio/gdtlsconnection.c" + line="760">callback to call when the handshake is complete nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="761">the data to pass to the callback function @@ -37712,28 +40151,28 @@ g_dtls_connection_handshake() for more information. version="2.48" throws="1"> Finish an asynchronous TLS handshake operation. See + filename="gio/gdtlsconnection.c" + line="782">Finish an asynchronous TLS handshake operation. See g_dtls_connection_handshake() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="791">%TRUE on success, %FALSE on failure, in which case @error will be set. a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="784">a #GDtlsConnection a #GAsyncResult. + filename="gio/gdtlsconnection.c" + line="785">a #GAsyncResult. @@ -37743,8 +40182,8 @@ case @error will be set. glib:set-property="advertised-protocols" version="2.60"> Sets the list of application-layer protocols to advertise that the + filename="gio/gdtlsconnection.c" + line="1052">Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use @@ -37754,15 +40193,15 @@ of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1054">a #GDtlsConnection nullable="1" allow-none="1"> a %NULL-terminated + filename="gio/gdtlsconnection.c" + line="1055">a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL @@ -37784,8 +40223,8 @@ for a list of registered protocol IDs. glib:set-property="certificate" version="2.48"> This sets the certificate that @conn will present to its peer + filename="gio/gdtlsconnection.c" + line="416">This sets the certificate that @conn will present to its peer during the TLS handshake. For a #GDtlsServerConnection, it is mandatory to set this, and that will normally be done at construct time. @@ -37803,21 +40242,21 @@ or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that g_dtls_client_connection_get_accepted_cas() will return non-%NULL.) - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="418">a #GDtlsConnection the certificate to use for @conn + filename="gio/gdtlsconnection.c" + line="419">the certificate to use for @conn @@ -37827,8 +40266,8 @@ non-%NULL.) glib:set-property="database" version="2.48"> Sets the certificate database that is used to verify peer certificates. + filename="gio/gdtlsconnection.c" + line="359">Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to %NULL, then peer certificate validation will always set the @@ -37839,15 +40278,15 @@ client-side connections, unless that bit is not set in There are nonintuitive security implications when using a non-default database. See #GDtlsConnection:database for details. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="361">a #GDtlsConnection nullable="1" allow-none="1"> a #GTlsDatabase + filename="gio/gdtlsconnection.c" + line="362">a #GTlsDatabase @@ -37866,22 +40305,22 @@ database. See #GDtlsConnection:database for details. glib:set-property="interaction" version="2.48"> Set the object that will be used to interact with the user. It will be used + filename="gio/gdtlsconnection.c" + line="477">Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. The @interaction argument will normally be a derived subclass of #GTlsInteraction. %NULL can also be provided if no user interaction should occur for this connection. - + a connection + filename="gio/gdtlsconnection.c" + line="479">a connection nullable="1" allow-none="1"> an interaction object, or %NULL + filename="gio/gdtlsconnection.c" + line="480">an interaction object, or %NULL @@ -37902,29 +40341,29 @@ should occur for this connection. deprecated="1" deprecated-version="2.60."> Since GLib 2.64, changing the rehandshake mode is no longer supported + filename="gio/gdtlsconnection.c" + line="645">Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="647">a #GDtlsConnection the rehandshaking mode + filename="gio/gdtlsconnection.c" + line="648">the rehandshaking mode @@ -37934,8 +40373,8 @@ rekey operations. glib:set-property="require-close-notify" version="2.48"> Sets whether or not @conn expects a proper TLS close notification + filename="gio/gdtlsconnection.c" + line="576">Sets whether or not @conn expects a proper TLS close notification before the connection is closed. If this is %TRUE (the default), then @conn will expect to receive a TLS close notification from its peer before the connection is closed, and will return a @@ -37960,21 +40399,21 @@ connection; when the application calls g_dtls_connection_close_async() on setting of this property. If you explicitly want to do an unclean close, you can close @conn's #GDtlsConnection:base-socket rather than closing @conn itself. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="578">a #GDtlsConnection whether or not to require close notification + filename="gio/gdtlsconnection.c" + line="579">whether or not to require close notification @@ -37982,10 +40421,11 @@ than closing @conn itself. + throws="1" + glib:async-func="shutdown_async"> Shut down part or all of a DTLS connection. + filename="gio/gdtlsconnection.c" + line="808">Shut down part or all of a DTLS connection. If @shutdown_read is %TRUE then the receiving side of the connection is shut down, and further reading is disallowed. Subsequent calls to @@ -38001,30 +40441,30 @@ is equivalent to calling g_dtls_connection_close(). If @cancellable is cancelled, the #GDtlsConnection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. - + %TRUE on success, %FALSE otherwise + filename="gio/gdtlsconnection.c" + line="833">%TRUE on success, %FALSE otherwise a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="810">a #GDtlsConnection %TRUE to stop reception of incoming datagrams + filename="gio/gdtlsconnection.c" + line="811">%TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams + filename="gio/gdtlsconnection.c" + line="812">%TRUE to stop sending outgoing datagrams a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="813">a #GCancellable, or %NULL + version="2.48" + glib:finish-func="shutdown_finish" + glib:sync-func="shutdown"> Asynchronously shut down part or all of the DTLS connection. See + filename="gio/gdtlsconnection.c" + line="861">Asynchronously shut down part or all of the DTLS connection. See g_dtls_connection_shutdown() for more information. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="863">a #GDtlsConnection %TRUE to stop reception of incoming datagrams + filename="gio/gdtlsconnection.c" + line="864">%TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams + filename="gio/gdtlsconnection.c" + line="865">%TRUE to stop sending outgoing datagrams the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="866">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="867">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the shutdown operation is complete + filename="gio/gdtlsconnection.c" + line="868">callback to call when the shutdown operation is complete nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="869">the data to pass to the callback function @@ -38110,28 +40552,28 @@ g_dtls_connection_shutdown() for more information. version="2.48" throws="1"> Finish an asynchronous TLS shutdown operation. See + filename="gio/gdtlsconnection.c" + line="897">Finish an asynchronous TLS shutdown operation. See g_dtls_connection_shutdown() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="906">%TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="899">a #GDtlsConnection a #GAsyncResult + filename="gio/gdtlsconnection.c" + line="900">a #GAsyncResult @@ -38142,8 +40584,8 @@ case @error will be set transfer-ownership="none" setter="set_advertised_protocols"> The list of application-layer protocols that the connection + filename="gio/gdtlsconnection.c" + line="233">The list of application-layer protocols that the connection advertises that it is willing to speak. See g_dtls_connection_set_advertised_protocols(). @@ -38156,8 +40598,8 @@ g_dtls_connection_set_advertised_protocols(). construct-only="1" transfer-ownership="none"> The #GDatagramBased that the connection wraps. Note that this may be any + filename="gio/gdtlsconnection.c" + line="90">The #GDatagramBased that the connection wraps. Note that this may be any implementation of #GDatagramBased, not just a #GSocket. @@ -38168,8 +40610,8 @@ implementation of #GDatagramBased, not just a #GSocket. setter="set_certificate" getter="get_certificate"> The connection's certificate; see + filename="gio/gdtlsconnection.c" + line="177">The connection's certificate; see g_dtls_connection_set_certificate(). @@ -38179,8 +40621,8 @@ g_dtls_connection_set_certificate(). getter="get_ciphersuite_name" default-value="NULL"> The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). + filename="gio/gdtlsconnection.c" + line="275">The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). setter="set_database" getter="get_database"> The certificate database to use when verifying this TLS connection. + filename="gio/gdtlsconnection.c" + line="104">The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). @@ -38216,8 +40658,8 @@ unusual security requirements. setter="set_interaction" getter="get_interaction"> A #GTlsInteraction object to be used when the connection or certificate + filename="gio/gdtlsconnection.c" + line="131">A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. @@ -38228,8 +40670,8 @@ user for passwords where necessary. getter="get_negotiated_protocol" default-value="NULL"> The application-layer protocol negotiated during the TLS + filename="gio/gdtlsconnection.c" + line="247">The application-layer protocol negotiated during the TLS handshake. See g_dtls_connection_get_negotiated_protocol(). @@ -38238,8 +40680,8 @@ handshake. See g_dtls_connection_get_negotiated_protocol(). transfer-ownership="none" getter="get_peer_certificate"> The connection's peer's certificate, after the TLS handshake has + filename="gio/gdtlsconnection.c" + line="190">The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GDtlsConnection::accept-certificate. @@ -38253,8 +40695,8 @@ detect when a handshake has occurred.) getter="get_peer_certificate_errors" default-value="G_TLS_CERTIFICATE_NO_FLAGS"> The errors noticed while verifying + filename="gio/gdtlsconnection.c" + line="207">The errors noticed while verifying #GDtlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GDtlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -38276,8 +40718,8 @@ error flag set even if other problems exist with the certificate. getter="get_protocol_version" default-value="G_TLS_PROTOCOL_VERSION_UNKNOWN"> The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). + filename="gio/gdtlsconnection.c" + line="261">The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). getter="get_rehandshake_mode" default-value="G_TLS_REHANDSHAKE_NEVER"> The rehandshaking mode. See + filename="gio/gdtlsconnection.c" + line="159">The rehandshaking mode. See g_dtls_connection_set_rehandshake_mode(). The rehandshake mode is ignored. @@ -38306,15 +40748,15 @@ g_dtls_connection_set_rehandshake_mode(). getter="get_require_close_notify" default-value="TRUE"> Whether or not proper TLS close notification is required. + filename="gio/gdtlsconnection.c" + line="145">Whether or not proper TLS close notification is required. See g_dtls_connection_set_require_close_notify(). Emitted during the TLS handshake after the peer certificate has + filename="gio/gdtlsconnection.c" + line="288">Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert's certification path by calling g_tls_certificate_get_issuer() on it. @@ -38358,8 +40800,8 @@ need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. %TRUE to accept @peer_cert (which will also + filename="gio/gdtlsconnection.c" + line="337">%TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. @@ -38368,14 +40810,14 @@ no one else overrides it. the peer's #GTlsCertificate + filename="gio/gdtlsconnection.c" + line="291">the peer's #GTlsCertificate the problems with @peer_cert. + filename="gio/gdtlsconnection.c" + line="292">the problems with @peer_cert. @@ -38386,18 +40828,21 @@ no one else overrides it. glib:is-gtype-struct-for="DtlsConnection" version="2.48"> Virtual method table for a #GDtlsConnection implementation. - + The parent interface. + Check whether to accept a certificate. - + @@ -38415,19 +40860,22 @@ no one else overrides it. + Perform a handshake operation. - + success or failure + filename="gio/gdtlsconnection.c" + line="740">success or failure a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="709">a #GDtlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="710">a #GCancellable, or %NULL + Start an asynchronous handshake operation. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="757">a #GDtlsConnection the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="758">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="759">a #GCancellable, or %NULL scope="async" closure="4"> callback to call when the handshake is complete + filename="gio/gdtlsconnection.c" + line="760">callback to call when the handshake is complete allow-none="1" closure="4"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="761">the data to pass to the callback function + Finish an asynchronous handshake operation. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="791">%TRUE on success, %FALSE on failure, in which case @error will be set. a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="784">a #GDtlsConnection a #GAsyncResult. + filename="gio/gdtlsconnection.c" + line="785">a #GAsyncResult. + Shut down one or both directions of the connection. - + %TRUE on success, %FALSE otherwise + filename="gio/gdtlsconnection.c" + line="833">%TRUE on success, %FALSE otherwise a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="810">a #GDtlsConnection %TRUE to stop reception of incoming datagrams + filename="gio/gdtlsconnection.c" + line="811">%TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams + filename="gio/gdtlsconnection.c" + line="812">%TRUE to stop sending outgoing datagrams nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="813">a #GCancellable, or %NULL + Start an asynchronous shutdown operation. - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="863">a #GDtlsConnection %TRUE to stop reception of incoming datagrams + filename="gio/gdtlsconnection.c" + line="864">%TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams + filename="gio/gdtlsconnection.c" + line="865">%TRUE to stop sending outgoing datagrams the [I/O priority][io-priority] of the request + filename="gio/gdtlsconnection.c" + line="866">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gdtlsconnection.c" + line="867">a #GCancellable, or %NULL scope="async" closure="6"> callback to call when the shutdown operation is complete + filename="gio/gdtlsconnection.c" + line="868">callback to call when the shutdown operation is complete allow-none="1" closure="6"> the data to pass to the callback function + filename="gio/gdtlsconnection.c" + line="869">the data to pass to the callback function + Finish an asynchronous shutdown operation. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gdtlsconnection.c" + line="906">%TRUE on success, %FALSE on failure, in which case @error will be set a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="899">a #GDtlsConnection a #GAsyncResult + filename="gio/gdtlsconnection.c" + line="900">a #GAsyncResult + Set APLN protocol list (Since: 2.60) - + a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1054">a #GDtlsConnection nullable="1" allow-none="1"> a %NULL-terminated + filename="gio/gdtlsconnection.c" + line="1055">a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL @@ -38679,27 +41145,33 @@ case @error will be set + Get ALPN-negotiated protocol (Since: 2.60) - + the negotiated protocol, or %NULL + filename="gio/gdtlsconnection.c" + line="1096">the negotiated protocol, or %NULL a #GDtlsConnection + filename="gio/gdtlsconnection.c" + line="1086">a #GDtlsConnection + Retrieve TLS channel binding data (Since: 2.66) - + @@ -38728,10 +41200,10 @@ case @error will be set glib:get-type="g_dtls_server_connection_get_type" glib:type-struct="DtlsServerConnectionInterface"> #GDtlsServerConnection is the server-side subclass of #GDtlsConnection, -representing a server-side DTLS connection. - + filename="gio/gdtlsserverconnection.c" + line="33">`GDtlsServerConnection` is the server-side subclass of +[iface@Gio.DtlsConnection], representing a server-side DTLS connection. + version="2.48" throws="1"> Creates a new #GDtlsServerConnection wrapping @base_socket. - + filename="gio/gdtlsserverconnection.c" + line="64">Creates a new #GDtlsServerConnection wrapping @base_socket. + the new + filename="gio/gdtlsserverconnection.c" + line="72">the new #GDtlsServerConnection, or %NULL on error the #GDatagramBased to wrap + filename="gio/gdtlsserverconnection.c" + line="66">the #GDatagramBased to wrap nullable="1" allow-none="1"> the default server certificate, or %NULL + filename="gio/gdtlsserverconnection.c" + line="67">the default server certificate, or %NULL @@ -38773,8 +41245,8 @@ representing a server-side DTLS connection. transfer-ownership="none" default-value="G_TLS_AUTHENTICATION_NONE"> The #GTlsAuthenticationMode for the server. This can be changed + filename="gio/gdtlsserverconnection.c" + line="47">The #GTlsAuthenticationMode for the server. This can be changed before calling g_dtls_connection_handshake() if you want to rehandshake with a different mode from the initial handshake. @@ -38785,18 +41257,18 @@ rehandshake with a different mode from the initial handshake. glib:is-gtype-struct-for="DtlsServerConnection" version="2.48"> vtable for a #GDtlsServerConnection implementation. - + filename="gio/gdtlsserverconnection.h" + line="40">vtable for a #GDtlsServerConnection implementation. + The parent interface. + filename="gio/gdtlsserverconnection.h" + line="42">The parent interface. - + @@ -38805,7 +41277,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -38814,7 +41286,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -38823,7 +41295,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -38832,7 +41304,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -38841,7 +41313,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -38855,31 +41327,31 @@ rehandshake with a different mode from the initial handshake. glib:get-type="g_emblem_get_type" glib:type-struct="EmblemClass"> #GEmblem is an implementation of #GIcon that supports + filename="gio/gemblem.c" + line="33">`GEmblem` is an implementation of [iface@Gio.Icon] that supports having an emblem, which is an icon with additional properties. -It can than be added to a #GEmblemedIcon. +It can than be added to a [class@Gio.EmblemedIcon]. Currently, only metainformation about the emblem's origin is supported. More may be added in the future. - + Creates a new emblem for @icon. - + filename="gio/gemblem.c" + line="171">Creates a new emblem for @icon. + a new #GEmblem. + filename="gio/gemblem.c" + line="177">a new #GEmblem. a GIcon containing the icon. + filename="gio/gemblem.c" + line="173">a GIcon containing the icon. @@ -38888,26 +41360,26 @@ supported. More may be added in the future. c:identifier="g_emblem_new_with_origin" version="2.18"> Creates a new emblem for @icon. - + filename="gio/gemblem.c" + line="197">Creates a new emblem for @icon. + a new #GEmblem. + filename="gio/gemblem.c" + line="204">a new #GEmblem. a GIcon containing the icon. + filename="gio/gemblem.c" + line="199">a GIcon containing the icon. a GEmblemOrigin enum defining the emblem's origin + filename="gio/gemblem.c" + line="200">a GEmblemOrigin enum defining the emblem's origin @@ -38917,21 +41389,21 @@ supported. More may be added in the future. glib:get-property="icon" version="2.18"> Gives back the icon from @emblem. - + filename="gio/gemblem.c" + line="225">Gives back the icon from @emblem. + a #GIcon. The returned object belongs to + filename="gio/gemblem.c" + line="231">a #GIcon. The returned object belongs to the emblem and should not be modified or freed. a #GEmblem from which the icon should be extracted. + filename="gio/gemblem.c" + line="227">a #GEmblem from which the icon should be extracted. @@ -38941,37 +41413,45 @@ supported. More may be added in the future. glib:get-property="origin" version="2.18"> Gets the origin of the emblem. - + filename="gio/gemblem.c" + line="245">Gets the origin of the emblem. + the origin of the emblem + filename="gio/gemblem.c" + line="251">the origin of the emblem a #GEmblem + filename="gio/gemblem.c" + line="247">a #GEmblem + The actual icon of the emblem. + The origin the emblem is derived from. @@ -38980,7 +41460,7 @@ supported. More may be added in the future. disguised="1" opaque="1" glib:is-gtype-struct-for="Emblem"> - + glib:get-type="g_emblem_origin_get_type" c:type="GEmblemOrigin"> GEmblemOrigin is used to add information about the origin of the emblem + filename="gio/gioenums.h" + line="693">GEmblemOrigin is used to add information about the origin of the emblem to #GEmblem. glib:nick="unknown" glib:name="G_EMBLEM_ORIGIN_UNKNOWN"> Emblem of unknown origin + filename="gio/gioenums.h" + line="695">Emblem of unknown origin glib:nick="device" glib:name="G_EMBLEM_ORIGIN_DEVICE"> Emblem adds device-specific information + filename="gio/gioenums.h" + line="696">Emblem adds device-specific information glib:nick="livemetadata" glib:name="G_EMBLEM_ORIGIN_LIVEMETADATA"> Emblem depicts live metadata, such as "readonly" + filename="gio/gioenums.h" + line="697">Emblem depicts live metadata, such as "readonly" glib:nick="tag" glib:name="G_EMBLEM_ORIGIN_TAG"> Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) + filename="gio/gioenums.h" + line="698">Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) glib:get-type="g_emblemed_icon_get_type" glib:type-struct="EmblemedIconClass"> #GEmblemedIcon is an implementation of #GIcon that supports + filename="gio/gemblemedicon.c" + line="35">`GEmblemedIcon` is an implementation of [iface@Gio.Icon] that supports adding an emblem to an icon. Adding multiple emblems to an -icon is ensured via g_emblemed_icon_add_emblem(). +icon is ensured via [method@Gio.EmblemedIcon.add_emblem]. -Note that #GEmblemedIcon allows no control over the position -of the emblems. See also #GEmblem for more information. - +Note that `GEmblemedIcon` allows no control over the position +of the emblems. See also [class@Gio.Emblem] for more information. + Creates a new emblemed icon for @icon with the emblem @emblem. - + filename="gio/gemblemedicon.c" + line="147">Creates a new emblemed icon for @icon with the emblem @emblem. + a new #GIcon + filename="gio/gemblemedicon.c" + line="154">a new #GIcon a #GIcon + filename="gio/gemblemedicon.c" + line="149">a #GIcon nullable="1" allow-none="1"> a #GEmblem, or %NULL + filename="gio/gemblemedicon.c" + line="150">a #GEmblem, or %NULL @@ -39080,23 +41560,23 @@ of the emblems. See also #GEmblem for more information. c:identifier="g_emblemed_icon_add_emblem" version="2.18"> Adds @emblem to the #GList of #GEmblems. - + filename="gio/gemblemedicon.c" + line="252">Adds @emblem to the #GList of #GEmblems. + a #GEmblemedIcon + filename="gio/gemblemedicon.c" + line="254">a #GEmblemedIcon a #GEmblem + filename="gio/gemblemedicon.c" + line="255">a #GEmblem @@ -39105,17 +41585,17 @@ of the emblems. See also #GEmblem for more information. c:identifier="g_emblemed_icon_clear_emblems" version="2.28"> Removes all the emblems from @icon. - + filename="gio/gemblemedicon.c" + line="216">Removes all the emblems from @icon. + a #GEmblemedIcon + filename="gio/gemblemedicon.c" + line="218">a #GEmblemedIcon @@ -39124,13 +41604,13 @@ of the emblems. See also #GEmblem for more information. c:identifier="g_emblemed_icon_get_emblems" version="2.18"> Gets the list of emblems for the @icon. - + filename="gio/gemblemedicon.c" + line="196">Gets the list of emblems for the @icon. + a #GList of + filename="gio/gemblemedicon.c" + line="202">a #GList of #GEmblems that is owned by @emblemed @@ -39139,8 +41619,8 @@ of the emblems. See also #GEmblem for more information. a #GEmblemedIcon + filename="gio/gemblemedicon.c" + line="198">a #GEmblemedIcon @@ -39149,28 +41629,32 @@ of the emblems. See also #GEmblem for more information. c:identifier="g_emblemed_icon_get_icon" version="2.18"> Gets the main icon for @emblemed. - + filename="gio/gemblemedicon.c" + line="178">Gets the main icon for @emblemed. + a #GIcon that is owned by @emblemed + filename="gio/gemblemedicon.c" + line="184">a #GIcon that is owned by @emblemed a #GEmblemedIcon + filename="gio/gemblemedicon.c" + line="180">a #GEmblemedIcon + The [iface@Gio.Icon] to attach emblems to. @@ -39183,7 +41667,7 @@ of the emblems. See also #GEmblem for more information. - + @@ -39192,10 +41676,10 @@ of the emblems. See also #GEmblem for more information. c:type="GEmblemedIconPrivate" disguised="1" opaque="1"> - + - + @@ -39204,7 +41688,7 @@ of the emblems. See also #GEmblem for more information. - + @@ -39213,7 +41697,7 @@ of the emblems. See also #GEmblem for more information. - + @@ -39222,7 +41706,7 @@ of the emblems. See also #GEmblem for more information. - + @@ -39232,87 +41716,87 @@ of the emblems. See also #GEmblem for more information. value="access::can-delete" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE"> A key in the "access" namespace for checking deletion privileges. + filename="gio/gfileinfo.h" + line="365">A key in the "access" namespace for checking deletion privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to delete the file. - + A key in the "access" namespace for getting execution privileges. + filename="gio/gfileinfo.h" + line="354">A key in the "access" namespace for getting execution privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to execute the file. - + A key in the "access" namespace for getting read privileges. + filename="gio/gfileinfo.h" + line="332">A key in the "access" namespace for getting read privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to read the file. - + A key in the "access" namespace for checking renaming privileges. + filename="gio/gfileinfo.h" + line="388">A key in the "access" namespace for checking renaming privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to rename the file. - + A key in the "access" namespace for checking trashing privileges. + filename="gio/gfileinfo.h" + line="376">A key in the "access" namespace for checking trashing privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to move the file to the trash. - + A key in the "access" namespace for getting write privileges. + filename="gio/gfileinfo.h" + line="343">A key in the "access" namespace for getting write privileges. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be %TRUE if the user is able to write to the file. - + A key in the "dos" namespace for checking if the file's archive flag + filename="gio/gfileinfo.h" + line="817">A key in the "dos" namespace for checking if the file's archive flag is set. This attribute is %TRUE if the archive flag is set. @@ -39320,7 +41804,7 @@ This attribute is %TRUE if the archive flag is set. This attribute is only available for DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_DOS_IS_MOUNTPOINT" version="2.60"> A key in the "dos" namespace for checking if the file is a NTFS mount point + filename="gio/gfileinfo.h" + line="845">A key in the "dos" namespace for checking if the file is a NTFS mount point (a volume mount or a junction point). This attribute is %TRUE if file is a reparse point of type @@ -39338,15 +41822,15 @@ This attribute is %TRUE if file is a reparse point of type This attribute is only available for DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "dos" namespace for checking if the file's backup flag + filename="gio/gfileinfo.h" + line="831">A key in the "dos" namespace for checking if the file's backup flag is set. This attribute is %TRUE if the backup flag is set. @@ -39354,7 +41838,7 @@ This attribute is %TRUE if the backup flag is set. This attribute is only available for DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG" version="2.60"> A key in the "dos" namespace for getting the file NTFS reparse tag. + filename="gio/gfileinfo.h" + line="862">A key in the "dos" namespace for getting the file NTFS reparse tag. This value is 0 for files that are not reparse points. @@ -39371,82 +41855,82 @@ See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx) page for possible reparse tag values. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "etag" namespace for getting the value of the file's + filename="gio/gfileinfo.h" + line="291">A key in the "etag" namespace for getting the value of the file's entity tag. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "filesystem" namespace for getting the number of bytes + filename="gio/gfileinfo.h" + line="1153">A key in the "filesystem" namespace for getting the number of bytes of free space left on the file system. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "filesystem" namespace for checking if the file system + filename="gio/gfileinfo.h" + line="1184">A key in the "filesystem" namespace for checking if the file system is read only. Is set to %TRUE if the file system is read only. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "filesystem" namespace for checking if the file system + filename="gio/gfileinfo.h" + line="1207">A key in the "filesystem" namespace for checking if the file system is remote. Is set to %TRUE if the file system is remote. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "filesystem" namespace for getting the total size (in + filename="gio/gfileinfo.h" + line="1143">A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "filesystem" namespace for getting the file system's type. + filename="gio/gfileinfo.h" + line="1175">A key in the "filesystem" namespace for getting the file system's type. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + c:type="G_FILE_ATTRIBUTE_FILESYSTEM_USED" version="2.32"> A key in the "filesystem" namespace for getting the number of bytes + filename="gio/gfileinfo.h" + line="1163">A key in the "filesystem" namespace for getting the number of bytes used by data on the file system. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "filesystem" namespace for hinting a file manager + filename="gio/gfileinfo.h" + line="1196">A key in the "filesystem" namespace for hinting a file manager application whether it should preview (e.g. thumbnail) files on the file system. The value for this key contain a #GFilesystemPreviewType. - + A key in the "gvfs" namespace that gets the name of the current + filename="gio/gfileinfo.h" + line="1219">A key in the "gvfs" namespace that gets the name of the current GVFS backend in use. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "id" namespace for getting a file identifier. + filename="gio/gfileinfo.h" + line="305">A key in the "id" namespace for getting a file identifier. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. An example use would be during listing files, to avoid recursive directory scanning. - + A key in the "id" namespace for getting the file system identifier. + filename="gio/gfileinfo.h" + line="317">A key in the "id" namespace for getting the file system identifier. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. An example use would be during drag and drop to see if the source and target are on the same filesystem (default to move) or not (default to copy). - + A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="423">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="403">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL" version="2.22"> A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="510">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START" version="2.22"> A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="463">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED" version="2.22"> A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="475">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started degraded. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP" version="2.22"> A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="487">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="413">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "mountable" namespace for getting the HAL UDI for the mountable + filename="gio/gfileinfo.h" + line="453">A key in the "mountable" namespace for getting the HAL UDI for the mountable file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC" version="2.22"> A key in the "mountable" namespace for checking if a file (of + filename="gio/gfileinfo.h" + line="522">A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is automatically polled for media. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE" version="2.22"> A key in the "mountable" namespace for getting the #GDriveStartStopType. + filename="gio/gfileinfo.h" + line="499">A key in the "mountable" namespace for getting the #GDriveStartStopType. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "mountable" namespace for getting the unix device. + filename="gio/gfileinfo.h" + line="433">A key in the "mountable" namespace for getting the unix device. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + c:type="G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE" version="2.22"> A key in the "mountable" namespace for getting the unix device file. + filename="gio/gfileinfo.h" + line="442">A key in the "mountable" namespace for getting the unix device file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "owner" namespace for getting the file owner's group. + filename="gio/gfileinfo.h" + line="900">A key in the "owner" namespace for getting the file owner's group. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "owner" namespace for getting the user name of the + filename="gio/gfileinfo.h" + line="880">A key in the "owner" namespace for getting the user name of the file's owner. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "owner" namespace for getting the real name of the + filename="gio/gfileinfo.h" + line="890">A key in the "owner" namespace for getting the real name of the user that owns the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + c:type="G_FILE_ATTRIBUTE_PREVIEW_ICON" version="2.20"> A key in the "preview" namespace for getting a #GIcon that can be + filename="gio/gfileinfo.h" + line="1125">A key in the "preview" namespace for getting a #GIcon that can be used to get preview of the file. For example, it may be a low resolution thumbnail without metadata. @@ -39713,7 +42197,7 @@ For example, it may be a low resolution thumbnail without metadata. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a #GIcon. - + c:type="G_FILE_ATTRIBUTE_RECENT_MODIFIED" version="2.52"> A key in the "recent" namespace for getting time, when the metadata for the + filename="gio/gfileinfo.h" + line="1278">A key in the "recent" namespace for getting time, when the metadata for the file in `recent:///` was last changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT64. - + A key in the "selinux" namespace for getting the file's SELinux + filename="gio/gfileinfo.h" + line="1229">A key in the "selinux" namespace for getting the file's SELinux context. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only available if GLib has been built with SELinux support. - + c:type="G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE" version="2.20"> A key in the "standard" namespace for getting the amount of disk space + filename="gio/gfileinfo.h" + line="240">A key in the "standard" namespace for getting the amount of disk space that is consumed by the file (in bytes). This will generally be larger than the file size (due to block size overhead) but can occasionally be smaller (for example, for sparse files). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "standard" namespace for getting the content type of the file. + filename="gio/gfileinfo.h" + line="206">A key in the "standard" namespace for getting the content type of the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. The value for this key should contain a valid content type. - + A key in the "standard" namespace for getting the copy name of the file. + filename="gio/gfileinfo.h" + line="152">A key in the "standard" namespace for getting the copy name of the file. The copy name is an optional version of the name. If available it's always in UTF8, and corresponds directly to the original filename (only transcoded to @@ -39787,15 +42271,15 @@ might have a different encoding. If the filename is not a valid string in the encoding selected for the filesystem it is in then the copy name will not be set. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "standard" namespace for getting the description of the file. + filename="gio/gfileinfo.h" + line="167">A key in the "standard" namespace for getting the description of the file. The description is a utf8 string that describes the file, generally containing the filename, but can also contain further information. Example descriptions @@ -39804,29 +42288,29 @@ for a file in the trash. This is useful for instance as the window title when displaying a directory or for a bookmarks menu. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "standard" namespace for getting the display name of the file. + filename="gio/gfileinfo.h" + line="126">A key in the "standard" namespace for getting the display name of the file. A display name is guaranteed to be in UTF-8 and can thus be displayed in the UI. It is guaranteed to be set on every file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "standard" namespace for edit name of the file. + filename="gio/gfileinfo.h" + line="138">A key in the "standard" namespace for edit name of the file. An edit name is similar to the display name, but it is meant to be used when you want to rename the file in the UI. The display name @@ -39834,83 +42318,83 @@ might contain information you don't want in the new filename (such as "(invalid unicode)" if the filename was in an invalid encoding). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "standard" namespace for getting the fast content type. + filename="gio/gfileinfo.h" + line="217">A key in the "standard" namespace for getting the fast content type. The fast content type isn't as reliable as the regular one, as it only uses the filename to guess it, but it is faster to calculate than the regular content type. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "standard" namespace for getting the icon for the file. + filename="gio/gfileinfo.h" + line="182">A key in the "standard" namespace for getting the icon for the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a #GIcon. - + A key in the "standard" namespace for checking if a file is a backup file. + filename="gio/gfileinfo.h" + line="65">A key in the "standard" namespace for checking if a file is a backup file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "standard" namespace for checking if a file is hidden. + filename="gio/gfileinfo.h" + line="56">A key in the "standard" namespace for checking if a file is hidden. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "standard" namespace for checking if the file is a symlink. + filename="gio/gfileinfo.h" + line="74">A key in the "standard" namespace for checking if the file is a symlink. Typically the actual type is something else, if we followed the symlink to get the type. On Windows NTFS mountpoints are considered to be symlinks as well. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "standard" namespace for checking if a file is virtual. + filename="gio/gfileinfo.h" + line="87">A key in the "standard" namespace for checking if a file is virtual. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_STANDARD_IS_VOLATILE" version="2.46"> A key in the "standard" namespace for checking if a file is + filename="gio/gfileinfo.h" + line="96">A key in the "standard" namespace for checking if a file is volatile. This is meant for opaque, non-POSIX-like backends to indicate that the URI is not persistent. Applications should look at %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "standard" namespace for getting the name of the file. + filename="gio/gfileinfo.h" + line="110">A key in the "standard" namespace for getting the name of the file. The name is the on-disk filename which may not be in any known encoding, and can thus not be generally displayed as is. It is guaranteed to be set on @@ -39943,26 +42427,26 @@ Use %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user interface. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + A key in the "standard" namespace for getting the file's size (in bytes). + filename="gio/gfileinfo.h" + line="231">A key in the "standard" namespace for getting the file's size (in bytes). Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "standard" namespace for setting the sort order of a file. + filename="gio/gfileinfo.h" + line="275">A key in the "standard" namespace for setting the sort order of a file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. @@ -39970,7 +42454,7 @@ An example use would be in file managers, which would use this key to set the order files are displayed. Files with smaller sort order should be sorted first, and files without sort order as if sort order was zero. - + c:type="G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON" version="2.34"> A key in the "standard" namespace for getting the symbolic icon for the file. + filename="gio/gfileinfo.h" + line="193">A key in the "standard" namespace for getting the symbolic icon for the file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a #GIcon. - + A key in the "standard" namespace for getting the symlink target, if the file + filename="gio/gfileinfo.h" + line="255">A key in the "standard" namespace for getting the symlink target, if the file is a symlink. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + A key in the "standard" namespace for getting the target URI for the file, in + filename="gio/gfileinfo.h" + line="265">A key in the "standard" namespace for getting the target URI for the file, in the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "standard" namespace for storing file types. + filename="gio/gfileinfo.h" + line="45">A key in the "standard" namespace for storing file types. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. The value for this key should contain a #GFileType. - + A key in the "thumbnail" namespace for checking if thumbnailing failed. + filename="gio/gfileinfo.h" + line="920">A key in the "thumbnail" namespace for checking if thumbnailing failed. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_LARGE" version="2.76"> A key in the "thumbnail" namespace for checking if thumbnailing failed + filename="gio/gfileinfo.h" + line="1002">A key in the "thumbnail" namespace for checking if thumbnailing failed for the large image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_NORMAL" version="2.76"> A key in the "thumbnail" namespace for checking if thumbnailing failed + filename="gio/gfileinfo.h" + line="958">A key in the "thumbnail" namespace for checking if thumbnailing failed for the normal image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XLARGE" version="2.76"> A key in the "thumbnail" namespace for checking if thumbnailing failed + filename="gio/gfileinfo.h" + line="1046">A key in the "thumbnail" namespace for checking if thumbnailing failed for the x-large image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XXLARGE" version="2.76"> A key in the "thumbnail" namespace for checking if thumbnailing failed + filename="gio/gfileinfo.h" + line="1090">A key in the "thumbnail" namespace for checking if thumbnailing failed for the xx-large image. This attribute is %TRUE if thumbnailing failed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID" version="2.40"> A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. + filename="gio/gfileinfo.h" + line="930">A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. This attribute is %TRUE if the thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. @@ -40112,7 +42596,7 @@ If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED is %TRUE and this attribute is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_LARGE" version="2.76"> A key in the "thumbnail" namespace for checking whether the large + filename="gio/gfileinfo.h" + line="1015">A key in the "thumbnail" namespace for checking whether the large thumbnail is outdated. This attribute is %TRUE if the large thumbnail is up-to-date with the file @@ -40133,7 +42617,7 @@ is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_NORMAL" version="2.76"> A key in the "thumbnail" namespace for checking whether the normal + filename="gio/gfileinfo.h" + line="971">A key in the "thumbnail" namespace for checking whether the normal thumbnail is outdated. This attribute is %TRUE if the normal thumbnail is up-to-date with the file @@ -40154,7 +42638,7 @@ is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_XLARGE" version="2.76"> A key in the "thumbnail" namespace for checking whether the x-large + filename="gio/gfileinfo.h" + line="1059">A key in the "thumbnail" namespace for checking whether the x-large thumbnail is outdated. This attribute is %TRUE if the x-large thumbnail is up-to-date with the file @@ -40175,7 +42659,7 @@ is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_XXLARGE" version="2.76"> A key in the "thumbnail" namespace for checking whether the xx-large + filename="gio/gfileinfo.h" + line="1103">A key in the "thumbnail" namespace for checking whether the xx-large thumbnail is outdated. This attribute is %TRUE if the x-large thumbnail is up-to-date with the file @@ -40196,19 +42680,19 @@ is %FALSE, it indicates that thumbnailing may be attempted again and may succeed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "thumbnail" namespace for getting the path to the thumbnail + filename="gio/gfileinfo.h" + line="911">A key in the "thumbnail" namespace for getting the path to the thumbnail image with the biggest size available. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_PATH_LARGE" version="2.76"> A key in the "thumbnail" namespace for getting the path to the large + filename="gio/gfileinfo.h" + line="991">A key in the "thumbnail" namespace for getting the path to the large thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_PATH_NORMAL" version="2.76"> A key in the "thumbnail" namespace for getting the path to the normal + filename="gio/gfileinfo.h" + line="947">A key in the "thumbnail" namespace for getting the path to the normal thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_PATH_XLARGE" version="2.76"> A key in the "thumbnail" namespace for getting the path to the x-large + filename="gio/gfileinfo.h" + line="1035">A key in the "thumbnail" namespace for getting the path to the x-large thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + c:type="G_FILE_ATTRIBUTE_THUMBNAIL_PATH_XXLARGE" version="2.76"> A key in the "thumbnail" namespace for getting the path to the xx-large + filename="gio/gfileinfo.h" + line="1079">A key in the "thumbnail" namespace for getting the path to the xx-large thumbnail image. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + A key in the "time" namespace for getting the time the file was last + filename="gio/gfileinfo.h" + line="572">A key in the "time" namespace for getting the time the file was last accessed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was last accessed, in seconds since the UNIX epoch. - + c:type="G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC" version="2.74"> A key in the "time" namespace for getting the nanoseconds of the time + filename="gio/gfileinfo.h" + line="596">A key in the "time" namespace for getting the nanoseconds of the time the file was last accessed. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the microseconds of the time + filename="gio/gfileinfo.h" + line="584">A key in the "time" namespace for getting the microseconds of the time the file was last accessed. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the time the file was last + filename="gio/gfileinfo.h" + line="608">A key in the "time" namespace for getting the time the file was last changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, @@ -40317,7 +42801,7 @@ and contains the time since the file was last changed, in seconds since the UNIX epoch. This corresponds to the traditional UNIX ctime. - + c:type="G_FILE_ATTRIBUTE_TIME_CHANGED_NSEC" version="2.74"> A key in the "time" namespace for getting the nanoseconds of the time + filename="gio/gfileinfo.h" + line="634">A key in the "time" namespace for getting the nanoseconds of the time the file was last changed. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the microseconds of the time + filename="gio/gfileinfo.h" + line="622">A key in the "time" namespace for getting the microseconds of the time the file was last changed. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the time the file was created. + filename="gio/gfileinfo.h" + line="646">A key in the "time" namespace for getting the time the file was created. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was created, in seconds since the UNIX @@ -40360,7 +42844,7 @@ epoch. This may correspond to Linux `stx_btime`, FreeBSD `st_birthtim`, NetBSD `st_birthtime` or NTFS `ctime`. - + A key in the "time" namespace for getting the nanoseconds of the time + filename="gio/gfileinfo.h" + line="672">A key in the "time" namespace for getting the nanoseconds of the time the file was created. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the microseconds of the time + filename="gio/gfileinfo.h" + line="660">A key in the "time" namespace for getting the microseconds of the time the file was created. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the time the file was last + filename="gio/gfileinfo.h" + line="536">A key in the "time" namespace for getting the time the file was last modified. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was modified, in seconds since the UNIX epoch. - + c:type="G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC" version="2.74"> A key in the "time" namespace for getting the nanoseconds of the time + filename="gio/gfileinfo.h" + line="560">A key in the "time" namespace for getting the nanoseconds of the time the file was last modified. This should be used in conjunction with #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "time" namespace for getting the microseconds of the time + filename="gio/gfileinfo.h" + line="548">A key in the "time" namespace for getting the microseconds of the time the file was last modified. This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + c:type="G_FILE_ATTRIBUTE_TRASH_DELETION_DATE" version="2.24"> A key in the "trash" namespace for getting the deletion date and time + filename="gio/gfileinfo.h" + line="1264">A key in the "trash" namespace for getting the deletion date and time of a file inside the `trash:///` folder. The format of the returned string is `YYYY-MM-DDThh:mm:ss`. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - + A key in the "trash" namespace for getting the number of (toplevel) items + filename="gio/gfileinfo.h" + line="1242">A key in the "trash" namespace for getting the number of (toplevel) items that are present in the `trash:///` folder. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + c:type="G_FILE_ATTRIBUTE_TRASH_ORIG_PATH" version="2.24"> A key in the "trash" namespace for getting the original path of a file + filename="gio/gfileinfo.h" + line="1252">A key in the "trash" namespace for getting the original path of a file inside the `trash:///` folder before it was trashed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - + A key in the "unix" namespace for getting the number of blocks allocated + filename="gio/gfileinfo.h" + line="787">A key in the "unix" namespace for getting the number of blocks allocated for the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "unix" namespace for getting the block size for the file + filename="gio/gfileinfo.h" + line="775">A key in the "unix" namespace for getting the block size for the file system. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "unix" namespace for getting the device id of the device the + filename="gio/gfileinfo.h" + line="686">A key in the "unix" namespace for getting the device id of the device the file is located on (see stat() documentation). This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "unix" namespace for getting the group ID for the file. + filename="gio/gfileinfo.h" + line="750">A key in the "unix" namespace for getting the group ID for the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "unix" namespace for getting the inode of the file. + filename="gio/gfileinfo.h" + line="698">A key in the "unix" namespace for getting the inode of the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - + A key in the "unix" namespace for checking if the file represents a + filename="gio/gfileinfo.h" + line="799">A key in the "unix" namespace for checking if the file represents a UNIX mount point. This attribute is %TRUE if the file is a UNIX mount point. @@ -40554,15 +43038,15 @@ Since 2.58, `/` is considered to be a mount point. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - + A key in the "unix" namespace for getting the mode of the file + filename="gio/gfileinfo.h" + line="709">A key in the "unix" namespace for getting the mode of the file (e.g. whether the file is a regular file, symlink, etc). See the documentation for `lstat()`: this attribute is equivalent to @@ -40572,15 +43056,15 @@ and permissions. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "unix" namespace for getting the number of hard links + filename="gio/gfileinfo.h" + line="725">A key in the "unix" namespace for getting the number of hard links for a file. See the documentation for `lstat()`. @@ -40588,15 +43072,15 @@ See the documentation for `lstat()`. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "unix" namespace for getting the device ID for the file + filename="gio/gfileinfo.h" + line="761">A key in the "unix" namespace for getting the device ID for the file (if it is a special file). See the documentation for `lstat()`. @@ -40604,26 +43088,26 @@ See the documentation for `lstat()`. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + A key in the "unix" namespace for getting the user ID for the file. + filename="gio/gfileinfo.h" + line="739">A key in the "unix" namespace for getting the user ID for the file. This attribute is only available for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + - + @@ -40632,7 +43116,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40641,7 +43125,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40650,7 +43134,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40659,7 +43143,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40668,7 +43152,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40677,7 +43161,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40686,7 +43170,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40695,7 +43179,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40704,7 +43188,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40713,7 +43197,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40722,7 +43206,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40731,7 +43215,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40740,7 +43224,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40749,7 +43233,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40758,7 +43242,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40767,7 +43251,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40776,7 +43260,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40785,7 +43269,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40794,7 +43278,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40803,7 +43287,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40812,7 +43296,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40821,7 +43305,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40830,7 +43314,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40839,7 +43323,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40848,7 +43332,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40857,7 +43341,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40866,7 +43350,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40875,7 +43359,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40884,7 +43368,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - + @@ -40897,120 +43381,128 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. glib:get-type="g_file_get_type" glib:type-struct="FileIface"> #GFile is a high level abstraction for manipulating files on a -virtual file system. #GFiles are lightweight, immutable objects + filename="gio/gfile.c" + line="88">`GFile` is a high level abstraction for manipulating files on a +virtual file system. `GFile`s are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that -#GFile objects do not represent files, merely an identifier for a +`GFile` objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations -(see #GInputStream and #GOutputStream). - -To construct a #GFile, you can use: -- g_file_new_for_path() if you have a path. -- g_file_new_for_uri() if you have a URI. -- g_file_new_for_commandline_arg() for a command line argument. -- g_file_new_tmp() to create a temporary file from a template. -- g_file_new_tmp_async() to asynchronously create a temporary file. -- g_file_new_tmp_dir_async() to asynchronously create a temporary directory. -- g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). -- g_file_new_build_filename() or g_file_new_build_filenamev() to create a file from path elements. - -One way to think of a #GFile is as an abstraction of a pathname. For +(see [class@Gio.InputStream] and [class@Gio.OutputStream]). + +To construct a `GFile`, you can use: + +- [func@Gio.File.new_for_path] if you have a path. +- [func@Gio.File.new_for_uri] if you have a URI. +- [func@Gio.File.new_for_commandline_arg] or + [func@Gio.File.new_for_commandline_arg_and_cwd] for a command line + argument. +- [func@Gio.File.new_tmp] to create a temporary file from a template. +- [func@Gio.File.new_tmp_async] to asynchronously create a temporary file. +- [func@Gio.File.new_tmp_dir_async] to asynchronously create a temporary + directory. +- [func@Gio.File.parse_name] from a UTF-8 string gotten from + [method@Gio.File.get_parse_name]. +- [func@Gio.File.new_build_filename] or [func@Gio.File.new_build_filenamev] + to create a file from path elements. + +One way to think of a `GFile` is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as -#GFiles are extensible it could also be something else that corresponds +`GFile`s are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. -#GFiles make up hierarchies of directories and files that correspond to +`GFile`s make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with -#GFile using g_file_get_parent() to get an identifier for the parent -directory, g_file_get_child() to get a child within a directory, -g_file_resolve_relative_path() to resolve a relative path between two -#GFiles. There can be multiple hierarchies, so you may not end up at -the same root if you repeatedly call g_file_get_parent() on two different -files. - -All #GFiles have a basename (get with g_file_get_basename()). These names -are byte strings that are used to identify the file on the filesystem +`GFile` using [method@Gio.File.get_parent] to get an identifier for the +parent directory, [method@Gio.File.get_child] to get a child within a +directory, and [method@Gio.File.resolve_relative_path] to resolve a relative +path between two `GFile`s. There can be multiple hierarchies, so you may not +end up at the same root if you repeatedly call [method@Gio.File.get_parent] +on two different files. + +All `GFile`s have a basename (get with [method@Gio.File.get_basename]). These +names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the -%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). -This is guaranteed to be in UTF-8 and can be used in a user interface. -But always store the real basename or the #GFile to use to actually -access the file, because there is no way to go from a display name to -the actual name. +`G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with +[method@Gio.File.query_info]. This is guaranteed to be in UTF-8 and can be +used in a user interface. But always store the real basename or the `GFile` +to use to actually access the file, because there is no way to go from a +display name to the actual name. -Using #GFile as an identifier has the same weaknesses as using a path +Using `GFile` as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, -hard or soft links may cause two different #GFiles to refer to the same +hard or soft links may cause two different `GFile`s to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to -check if two #GFiles point to the same file you can query for the -%G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial +check if two `GFile`s point to the same file you can query for the +`G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `GFile` does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of -path, "." or ".." path segments, etc) does not create different #GFiles. +path, `.` or `..` path segments, etc) does not create different `GFile`s. -Many #GFile operations have both synchronous and asynchronous versions +Many `GFile` operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions -simply have _async() appended to their function names. The asynchronous -I/O functions call a #GAsyncReadyCallback which is then used to finalize -the operation, producing a GAsyncResult which is then passed to the -function's matching _finish() operation. +simply have `_async()` appended to their function names. The asynchronous +I/O functions call a [callback@Gio.AsyncReadyCallback] which is then used to +finalize the operation, producing a [iface@Gio.AsyncResult] which is then +passed to the function’s matching `_finish()` operation. It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the -[introduction to asynchronous programming section][async-programming] for -more. +[introduction to asynchronous programming section](overview.html#asynchronous-programming) +for more. -Some #GFile operations almost always take a noticeable amount of time, and +Some `GFile` operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include: -- g_file_mount_mountable() to mount a mountable file. -- g_file_unmount_mountable_with_operation() to unmount a mountable file. -- g_file_eject_mountable_with_operation() to eject a mountable file. -## Entity Tags # {#gfile-etag} +- [method@Gio.File.mount_mountable] to mount a mountable file. +- [method@Gio.File.unmount_mountable_with_operation] to unmount a mountable + file. +- [method@Gio.File.eject_mountable_with_operation] to eject a mountable file. + +## Entity Tags -One notable feature of #GFiles are entity tags, or "etags" for +One notable feature of `GFile`s are entity tags, or ‘etags’ for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the HTTP 1.1 [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) -for HTTP Etag headers, which are a very similar concept. - +for HTTP `ETag` headers, which are a very similar concept. + Constructs a #GFile from a series of elements using the correct + filename="gio/gfile.c" + line="7545">Constructs a #GFile from a series of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filename(), followed by g_file_new_for_path() on the result. - + a new #GFile + filename="gio/gfile.c" + line="7556">a new #GFile the first element in the path + filename="gio/gfile.c" + line="7547">the first element in the path remaining elements in path, terminated by %NULL + filename="gio/gfile.c" + line="7548">remaining elements in path, terminated by %NULL @@ -41019,24 +43511,24 @@ followed by g_file_new_for_path() on the result. c:identifier="g_file_new_build_filenamev" version="2.78"> Constructs a #GFile from a vector of elements using the correct + filename="gio/gfile.c" + line="7581">Constructs a #GFile from a vector of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filenamev(), followed by g_file_new_for_path() on the result. - + a new #GFile + filename="gio/gfile.c" + line="7592">a new #GFile %NULL-terminated + filename="gio/gfile.c" + line="7583">%NULL-terminated array of strings containing the path elements. @@ -41047,8 +43539,8 @@ followed by g_file_new_for_path() on the result. Creates a #GFile with the given argument from the command line. + filename="gio/gfile.c" + line="7665">Creates a #GFile with the given argument from the command line. The value of @arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not @@ -41062,19 +43554,19 @@ the commandline. #GApplication also uses UTF-8 but g_application_command_line_create_file_for_arg() may be more useful for you there. It is also always possible to use this function with #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. - + a new #GFile. + filename="gio/gfile.c" + line="7684">a new #GFile. Free the returned object with g_object_unref(). a command line string + filename="gio/gfile.c" + line="7667">a command line string @@ -41083,8 +43575,8 @@ for you there. It is also always possible to use this function with c:identifier="g_file_new_for_commandline_arg_and_cwd" version="2.36"> Creates a #GFile with the given argument from the command line. + filename="gio/gfile.c" + line="7695">Creates a #GFile with the given argument from the command line. This function is similar to g_file_new_for_commandline_arg() except that it allows for passing the current working directory as an @@ -41095,47 +43587,47 @@ This is useful if the commandline argument was given in a context other than the invocation of the current process. See also g_application_command_line_create_file_for_arg(). - + a new #GFile + filename="gio/gfile.c" + line="7712">a new #GFile a command line string + filename="gio/gfile.c" + line="7697">a command line string the current working directory of the commandline + filename="gio/gfile.c" + line="7698">the current working directory of the commandline Constructs a #GFile for a given path. This operation never + filename="gio/gfile.c" + line="7190">Constructs a #GFile for a given path. This operation never fails, but the returned object might not support any I/O operation if @path is malformed. - + a new #GFile for the given @path. + filename="gio/gfile.c" + line="7199">a new #GFile for the given @path. Free the returned object with g_object_unref(). a string containing a relative or absolute path. + filename="gio/gfile.c" + line="7192">a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. @@ -41143,24 +43635,24 @@ operation if @path is malformed. Constructs a #GFile for a given URI. This operation never + filename="gio/gfile.c" + line="7210">Constructs a #GFile for a given URI. This operation never fails, but the returned object might not support any I/O operation if @uri is malformed or if the uri type is not supported. - + a new #GFile for the given @uri. + filename="gio/gfile.c" + line="7219">a new #GFile for the given @uri. Free the returned object with g_object_unref(). a UTF-8 string containing a URI + filename="gio/gfile.c" + line="7212">a UTF-8 string containing a URI @@ -41168,10 +43660,11 @@ not supported. + throws="1" + glib:async-func="new_tmp_async"> Opens a file in the preferred directory for temporary files (as + filename="gio/gfile.c" + line="7230">Opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) and returns a #GFile and #GFileIOStream pointing to it. @@ -41181,11 +43674,11 @@ directory components. If it is %NULL, a default template is used. Unlike the other #GFile constructors, this will return %NULL if a temporary file could not be created. - + a new #GFile. + filename="gio/gfile.c" + line="7248">a new #GFile. Free the returned object with g_object_unref(). @@ -41195,8 +43688,8 @@ a temporary file could not be created. nullable="1" allow-none="1"> Template for the file + filename="gio/gfile.c" + line="7232">Template for the file name, as in g_file_open_tmp(), or %NULL for a default template @@ -41205,24 +43698,26 @@ a temporary file could not be created. caller-allocates="0" transfer-ownership="full"> on return, a #GFileIOStream for the created file + filename="gio/gfile.c" + line="7234">on return, a #GFileIOStream for the created file + version="2.74" + glib:finish-func="new_tmp_finish" + glib:sync-func="new_tmp"> Asynchronously opens a file in the preferred directory for temporary files + filename="gio/gfile.c" + line="7340">Asynchronously opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_file_new_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. - + @@ -41232,15 +43727,15 @@ directory components. If it is %NULL, a default template is used. nullable="1" allow-none="1"> Template for the file + filename="gio/gfile.c" + line="7342">Template for the file name, as in g_file_open_tmp(), or %NULL for a default template the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="7344">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="7345">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gfile.c" + line="7346">a #GAsyncReadyCallback to call when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gfile.c" + line="7347">data to pass to @callback + version="2.74" + glib:finish-func="new_tmp_dir_finish"> Asynchronously creates a directory in the preferred directory for + filename="gio/gfile.c" + line="7463">Asynchronously creates a directory in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. - + @@ -41295,15 +43791,15 @@ directory components. If it is %NULL, a default template is used. nullable="1" allow-none="1"> Template for the file + filename="gio/gfile.c" + line="7465">Template for the file name, as in g_dir_make_tmp(), or %NULL for a default template the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="7467">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="7468">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gfile.c" + line="7469">a #GAsyncReadyCallback to call when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gfile.c" + line="7470">data to pass to @callback @@ -41342,22 +43838,22 @@ directory components. If it is %NULL, a default template is used. version="2.74" throws="1"> Finishes a temporary directory creation started by + filename="gio/gfile.c" + line="7501">Finishes a temporary directory creation started by g_file_new_tmp_dir_async(). - + a new #GFile. + filename="gio/gfile.c" + line="7509">a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult + filename="gio/gfile.c" + line="7503">a #GAsyncResult @@ -41367,21 +43863,21 @@ g_file_new_tmp_dir_async(). version="2.74" throws="1"> Finishes a temporary file creation started by g_file_new_tmp_async(). - + filename="gio/gfile.c" + line="7378">Finishes a temporary file creation started by g_file_new_tmp_async(). + a new #GFile. + filename="gio/gfile.c" + line="7386">a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult + filename="gio/gfile.c" + line="7380">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> on return, a #GFileIOStream for the created file + filename="gio/gfile.c" + line="7381">on return, a #GFileIOStream for the created file Constructs a #GFile with the given @parse_name (i.e. something + filename="gio/gfile.c" + line="7526">Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()). This operation never fails, but the returned object might not support any I/O operation if the @parse_name cannot be parsed. - + a new #GFile. + filename="gio/gfile.c" + line="7535">a new #GFile. a file name or path to be parsed + filename="gio/gfile.c" + line="7528">a file name or path to be parsed - + Gets an output stream for appending data to the file. + filename="gio/gfile.c" + line="1734">Gets an output stream for appending data to the file. If the file doesn't already exist it is created. By default files created are generally readable by everyone, @@ -41438,25 +43937,25 @@ Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileOutputStream, or %NULL on error. + filename="gio/gfile.c" + line="1760">a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1736">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1737">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1738">optional #GCancellable object, %NULL to ignore - + Asynchronously opens @file for appending. + filename="gio/gfile.c" + line="2174">Asynchronously opens @file for appending. For more details, see g_file_append_to() which is the synchronous version of this call. @@ -41482,27 +43984,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_append_to_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2176">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2177">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2178">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2179">optional #GCancellable object, %NULL to ignore @@ -41522,8 +44024,8 @@ of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2181">a #GAsyncReadyCallback to call when the request is satisfied @@ -41533,8 +44035,8 @@ of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="2183">the data to pass to callback function @@ -41543,14 +44045,14 @@ of the operation. invoker="append_to_finish" throws="1"> Finishes an asynchronous file append operation started with + filename="gio/gfile.c" + line="2215">Finishes an asynchronous file append operation started with g_file_append_to_async(). - + a valid #GFileOutputStream + filename="gio/gfile.c" + line="2224">a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). @@ -41558,22 +44060,25 @@ g_file_append_to_async(). input #GFile + filename="gio/gfile.c" + line="2217">input #GFile #GAsyncResult + filename="gio/gfile.c" + line="2218">#GAsyncResult - + Copies the file @source to the location specified by @destination. + filename="gio/gfile.c" + line="3647">Copies the file @source to the location specified by @destination. Can not handle recursive copies of directories. If the flag %G_FILE_COPY_OVERWRITE is specified an already @@ -41613,30 +44118,30 @@ If the source is a directory and the target does not exist, or If you are interested in copying the #GFile object itself (not the on-disk file), see g_file_dup(). - + %TRUE on success, %FALSE otherwise. + filename="gio/gfile.c" + line="3700">%TRUE on success, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="3649">input #GFile destination #GFile + filename="gio/gfile.c" + line="3650">destination #GFile set of #GFileCopyFlags + filename="gio/gfile.c" + line="3651">set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3652">optional #GCancellable object, %NULL to ignore @@ -41656,8 +44161,8 @@ file), see g_file_dup(). scope="call" closure="4"> function to callback with + filename="gio/gfile.c" + line="3654">function to callback with progress information, or %NULL if progress information is not needed @@ -41666,16 +44171,19 @@ file), see g_file_dup(). nullable="1" allow-none="1"> user data to pass to @progress_callback + filename="gio/gfile.c" + line="3656">user data to pass to @progress_callback - + Copies the file @source to the location specified by @destination + filename="gio/gfile.c" + line="3775">Copies the file @source to the location specified by @destination asynchronously. For details of the behaviour, see g_file_copy(). If @progress_callback is not %NULL, then that function that will be called @@ -41685,33 +44193,33 @@ run in. When the operation is finished, @callback will be called. You can then call g_file_copy_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="3777">input #GFile destination #GFile + filename="gio/gfile.c" + line="3778">destination #GFile set of #GFileCopyFlags + filename="gio/gfile.c" + line="3779">set of #GFileCopyFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="3780">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3781">optional #GCancellable object, %NULL to ignore @@ -41731,8 +44239,8 @@ g_file_copy_finish() to get the result of the operation. scope="notified" closure="5"> + filename="gio/gfile.c" + line="3783"> function to callback with progress information, or %NULL if progress information is not needed @@ -41742,8 +44250,8 @@ g_file_copy_finish() to get the result of the operation. nullable="1" allow-none="1"> user data to pass to @progress_callback + filename="gio/gfile.c" + line="3786">user data to pass to @progress_callback scope="async" closure="7"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="3787">a #GAsyncReadyCallback to call when the request is satisfied @@ -41764,42 +44272,45 @@ g_file_copy_finish() to get the result of the operation. allow-none="1" closure="7"> the data to pass to callback + filename="gio/gfile.c" + line="3789">the data to pass to callback Finishes copying the file started with g_file_copy_async(). - + filename="gio/gfile.c" + line="3947">Finishes copying the file started with g_file_copy_async(). + a %TRUE on success, %FALSE on error. + filename="gio/gfile.c" + line="3955">a %TRUE on success, %FALSE on error. input #GFile + filename="gio/gfile.c" + line="3949">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="3950">a #GAsyncResult - + Creates a new file and returns an output stream for writing to it. + filename="gio/gfile.c" + line="1789">Creates a new file and returns an output stream for writing to it. The file must not already exist. By default files created are generally readable by everyone, @@ -41818,11 +44329,11 @@ allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileOutputStream for the newly created + filename="gio/gfile.c" + line="1817">a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). @@ -41830,14 +44341,14 @@ of filesystem the file is on. input #GFile + filename="gio/gfile.c" + line="1791">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1792">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1793">optional #GCancellable object, %NULL to ignore - + Asynchronously creates a new file and returns an output stream + filename="gio/gfile.c" + line="2245">Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see g_file_create() which is @@ -41864,27 +44378,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2247">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2248">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2249">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2250">optional #GCancellable object, %NULL to ignore @@ -41904,8 +44418,8 @@ of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2252">a #GAsyncReadyCallback to call when the request is satisfied @@ -41915,36 +44429,36 @@ of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="2254">the data to pass to callback function Finishes an asynchronous file create operation started with + filename="gio/gfile.c" + line="2287">Finishes an asynchronous file create operation started with g_file_create_async(). - + a #GFileOutputStream or %NULL on error. + filename="gio/gfile.c" + line="2296">a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2289">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2290">a #GAsyncResult @@ -41952,10 +44466,11 @@ g_file_create_async(). + throws="1" + glib:async-func="create_readwrite_async"> Creates a new file and returns a stream for reading and + filename="gio/gfile.c" + line="1988">Creates a new file and returns a stream for reading and writing to it. The file must not already exist. By default files created are generally readable by everyone, @@ -41978,11 +44493,11 @@ kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. - + a #GFileIOStream for the newly created + filename="gio/gfile.c" + line="2020">a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). @@ -41990,14 +44505,14 @@ streaming, rather than just opening for reading or writing. a #GFile + filename="gio/gfile.c" + line="1990">a #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1991">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1992">optional #GCancellable object, %NULL to ignore @@ -42014,10 +44529,12 @@ streaming, rather than just opening for reading or writing. + version="2.22" + glib:finish-func="create_readwrite_finish" + glib:sync-func="create_readwrite"> Asynchronously creates a new file and returns a stream + filename="gio/gfile.c" + line="2465">Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist. For more details, see g_file_create_readwrite() which is @@ -42026,27 +44543,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_readwrite_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2467">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2468">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2469">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2470">optional #GCancellable object, %NULL to ignore @@ -42066,8 +44583,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2472">a #GAsyncReadyCallback to call when the request is satisfied @@ -42077,8 +44594,8 @@ the result of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="2474">the data to pass to callback function @@ -42088,36 +44605,39 @@ the result of the operation. version="2.22" throws="1"> Finishes an asynchronous file create operation started with + filename="gio/gfile.c" + line="2509">Finishes an asynchronous file create operation started with g_file_create_readwrite_async(). - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2518">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2511">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2512">a #GAsyncResult - + Deletes a file. If the @file is a directory, it will only be + filename="gio/gfile.c" + line="4628">Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows @@ -42138,18 +44658,18 @@ if (!g_file_delete (my_file, my_cancellable, &local_error) && If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the file was deleted. %FALSE otherwise. + filename="gio/gfile.c" + line="4657">%TRUE if the file was deleted. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4630">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4631">optional #GCancellable object, %NULL to ignore @@ -42166,27 +44686,29 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.34" + glib:finish-func="delete_file_finish" + glib:sync-func="delete_file"> Asynchronously delete a file. If the @file is a directory, it will + filename="gio/gfile.c" + line="4684">Asynchronously delete a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). - + input #GFile + filename="gio/gfile.c" + line="4686">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4687">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4688">optional #GCancellable object, %NULL to ignore @@ -42206,8 +44728,8 @@ g_unlink(). scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4690">a #GAsyncReadyCallback to call when the request is satisfied @@ -42217,8 +44739,8 @@ g_unlink(). allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="4692">the data to pass to callback function @@ -42228,34 +44750,34 @@ g_unlink(). version="2.34" throws="1"> Finishes deleting a file started with g_file_delete_async(). - + filename="gio/gfile.c" + line="4719">Finishes deleting a file started with g_file_delete_async(). + %TRUE if the file was deleted. %FALSE otherwise. + filename="gio/gfile.c" + line="4727">%TRUE if the file was deleted. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4721">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4722">a #GAsyncResult Duplicates a #GFile handle. This operation does not duplicate + filename="gio/gfile.c" + line="724">Duplicates a #GFile handle. This operation does not duplicate the actual file or directory represented by the #GFile; see g_file_copy() if attempting to copy a file. @@ -42265,19 +44787,19 @@ within the same thread, use g_object_ref() to increment the existing object’s reference count. This call does no blocking I/O. - + a new #GFile that is a duplicate + filename="gio/gfile.c" + line="739">a new #GFile that is a duplicate of the given #GFile. input #GFile + filename="gio/gfile.c" + line="726">input #GFile @@ -42285,10 +44807,11 @@ This call does no blocking I/O. + deprecated-version="2.22" + glib:finish-func="eject_mountable_finish"> Starts an asynchronous eject on a mountable. + filename="gio/gfile.c" + line="5790">Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_finish(). @@ -42297,21 +44820,21 @@ If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Use g_file_eject_mountable_with_operation() instead. - + input #GFile + filename="gio/gfile.c" + line="5792">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5793">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5794">optional #GCancellable object, %NULL to ignore @@ -42331,8 +44854,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5796">a #GAsyncReadyCallback to call when the request is satisfied @@ -42342,8 +44865,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="5798">the data to pass to callback function @@ -42354,40 +44877,41 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. deprecated-version="2.22" throws="1"> Finishes an asynchronous eject operation started by + filename="gio/gfile.c" + line="5840">Finishes an asynchronous eject operation started by g_file_eject_mountable(). Use g_file_eject_mountable_with_operation_finish() instead. - + %TRUE if the @file was ejected successfully. + filename="gio/gfile.c" + line="5849">%TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5842">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5843">a #GAsyncResult + version="2.22" + glib:finish-func="eject_mountable_with_operation_finish"> Starts an asynchronous eject on a mountable. + filename="gio/gfile.c" + line="5874">Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_with_operation_finish(). @@ -42395,21 +44919,21 @@ g_file_eject_mountable_with_operation_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + input #GFile + filename="gio/gfile.c" + line="5876">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5877">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5878">a #GMountOperation, or %NULL to avoid user interaction @@ -42427,8 +44951,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5880">optional #GCancellable object, %NULL to ignore @@ -42439,8 +44963,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5882">a #GAsyncReadyCallback to call when the request is satisfied @@ -42450,8 +44974,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="5884">the data to pass to callback function @@ -42461,38 +44985,39 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.22" throws="1"> Finishes an asynchronous eject operation started by + filename="gio/gfile.c" + line="5935">Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation(). - + %TRUE if the @file was ejected successfully. + filename="gio/gfile.c" + line="5944">%TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5937">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5938">a #GAsyncResult + throws="1" + glib:async-func="enumerate_children_async"> Gets the requested information about the files in a directory. + filename="gio/gfile.c" + line="1047">Gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. @@ -42517,31 +45042,31 @@ returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY error will be returned. Other errors are possible too. - + A #GFileEnumerator if successful, + filename="gio/gfile.c" + line="1082">A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1049">input #GFile an attribute query string + filename="gio/gfile.c" + line="1050">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1051">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1052">optional #GCancellable object, %NULL to ignore + invoker="enumerate_children_async" + glib:finish-func="enumerate_children_finish" + glib:sync-func="enumerate_children"> Asynchronously gets the requested information about the files + filename="gio/gfile.c" + line="1113">Asynchronously gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. @@ -42570,33 +45097,33 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_enumerate_children_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="1115">input #GFile an attribute query string + filename="gio/gfile.c" + line="1116">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1117">a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1118">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1119">optional #GCancellable object, %NULL to ignore @@ -42616,8 +45143,8 @@ the operation. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1121">a #GAsyncReadyCallback to call when the request is satisfied @@ -42627,8 +45154,8 @@ the operation. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="1123">the data to pass to callback function @@ -42637,14 +45164,14 @@ the operation. invoker="enumerate_children_finish" throws="1"> Finishes an async enumerate children operation. + filename="gio/gfile.c" + line="1159">Finishes an async enumerate children operation. See g_file_enumerate_children_async(). - + a #GFileEnumerator or %NULL + filename="gio/gfile.c" + line="1168">a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). @@ -42652,56 +45179,57 @@ See g_file_enumerate_children_async(). input #GFile + filename="gio/gfile.c" + line="1161">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1162">a #GAsyncResult Checks if the two given #GFiles refer to the same file. + filename="gio/gfile.c" + line="779">Checks if the two given #GFiles refer to the same file. Note that two #GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. This call does no blocking I/O. - + %TRUE if @file1 and @file2 are equal. + filename="gio/gfile.c" + line="792">%TRUE if @file1 and @file2 are equal. the first #GFile + filename="gio/gfile.c" + line="781">the first #GFile the second #GFile + filename="gio/gfile.c" + line="782">the second #GFile + throws="1" + glib:async-func="find_enclosing_mount_async"> Gets a #GMount for the #GFile. + filename="gio/gfile.c" + line="1571">Gets a #GMount for the #GFile. #GMount is returned only for user interesting locations, see #GVolumeMonitor. If the #GFileIface for @file does not have a #mount, @@ -42710,11 +45238,11 @@ This call does no blocking I/O. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GMount where the @file is located + filename="gio/gfile.c" + line="1588">a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). @@ -42722,8 +45250,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="1573">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1574">optional #GCancellable object, %NULL to ignore + invoker="find_enclosing_mount_async" + glib:finish-func="find_enclosing_mount_finish" + glib:sync-func="find_enclosing_mount"> Asynchronously gets the mount for the file. + filename="gio/gfile.c" + line="1620">Asynchronously gets the mount for the file. For more details, see g_file_find_enclosing_mount() which is the synchronous version of this call. @@ -42750,21 +45280,21 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_find_enclosing_mount_finish() to get the result of the operation. - + a #GFile + filename="gio/gfile.c" + line="1622">a #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1623">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1624">optional #GCancellable object, %NULL to ignore @@ -42784,8 +45314,8 @@ get the result of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1626">a #GAsyncReadyCallback to call when the request is satisfied @@ -42795,8 +45325,8 @@ get the result of the operation. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="1628">the data to pass to callback function @@ -42805,36 +45335,36 @@ get the result of the operation. invoker="find_enclosing_mount_finish" throws="1"> Finishes an asynchronous find mount request. + filename="gio/gfile.c" + line="1658">Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async(). - + #GMount for given @file or %NULL on error. + filename="gio/gfile.c" + line="1667">#GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). a #GFile + filename="gio/gfile.c" + line="1660">a #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1661">a #GAsyncResult Gets the base name (the last component of the path) for a given #GFile. + filename="gio/gfile.c" + line="536">Gets the base name (the last component of the path) for a given #GFile. If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator @@ -42847,11 +45377,11 @@ can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). This call does no blocking I/O. - + string containing the #GFile's + filename="gio/gfile.c" + line="554">string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. @@ -42859,8 +45389,8 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="538">input #GFile @@ -42869,8 +45399,8 @@ This call does no blocking I/O. invoker="get_child_for_display_name" throws="1"> Gets the child of @file for a given @display_name (i.e. a UTF-8 + filename="gio/gfile.c" + line="911">Gets the child of @file for a given @display_name (i.e. a UTF-8 version of the name). If this function fails, it returns %NULL and @error will be set. This is very useful when constructing a #GFile for a new file and the user entered the filename in the @@ -42878,11 +45408,11 @@ user interface, for instance when you select a directory and type a filename in the file selector. This call does no blocking I/O. - + a #GFile to the specified child, or + filename="gio/gfile.c" + line="926">a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). @@ -42890,31 +45420,31 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="913">input #GFile string to a possible child + filename="gio/gfile.c" + line="914">string to a possible child Gets the parent directory for the @file. + filename="gio/gfile.c" + line="815">Gets the parent directory for the @file. If the @file represents the root directory of the file system, then %NULL will be returned. This call does no blocking I/O. - + a #GFile structure to the + filename="gio/gfile.c" + line="825">a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). @@ -42922,16 +45452,16 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="817">input #GFile Gets the parse name of the @file. + filename="gio/gfile.c" + line="689">Gets the parse name of the @file. A parse name is a UTF-8 string that describes the file such that one can get the #GFile back using g_file_parse_name(). @@ -42945,11 +45475,11 @@ to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped). This call does no blocking I/O. - + a string containing the #GFile's parse name. + filename="gio/gfile.c" + line="708">a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. @@ -42957,24 +45487,24 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="691">input #GFile Gets the local pathname for #GFile, if one exists. If non-%NULL, this is + filename="gio/gfile.c" + line="570">Gets the local pathname for #GFile, if one exists. If non-%NULL, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O. - + string containing the #GFile's path, + filename="gio/gfile.c" + line="579">string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. @@ -42982,23 +45512,23 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="572">input #GFile Gets the path for @descendant relative to @parent. + filename="gio/gfile.c" + line="988">Gets the path for @descendant relative to @parent. This call does no blocking I/O. - + string with the relative path from + filename="gio/gfile.c" + line="997">string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. @@ -43007,29 +45537,29 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="990">input #GFile input #GFile + filename="gio/gfile.c" + line="991">input #GFile Gets the URI for the @file. + filename="gio/gfile.c" + line="664">Gets the URI for the @file. This call does no blocking I/O. - + a string containing the #GFile's URI. If the #GFile was constructed + filename="gio/gfile.c" + line="672">a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. @@ -43038,16 +45568,16 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="666">input #GFile Gets the URI scheme for a #GFile. + filename="gio/gfile.c" + line="503">Gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] @@ -43058,11 +45588,11 @@ The scheme can be different from the one used to construct the #GFile, in that it might be replaced with one that is logically equivalent to the #GFile. This call does no blocking I/O. - + a string containing the URI scheme for the given + filename="gio/gfile.c" + line="519">a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. @@ -43070,23 +45600,23 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="505">input #GFile Checks to see if a #GFile has a given URI scheme. + filename="gio/gfile.c" + line="475">Checks to see if a #GFile has a given URI scheme. This call does no blocking I/O. - + %TRUE if #GFile's backend supports the + filename="gio/gfile.c" + line="484">%TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. @@ -43094,29 +45624,29 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="477">input #GFile a string containing a URI scheme + filename="gio/gfile.c" + line="478">a string containing a URI scheme Creates a hash value for a #GFile. + filename="gio/gfile.c" + line="754">Creates a hash value for a #GFile. This call does no blocking I/O. - + 0 if @file is not a valid #GFile, otherwise an + filename="gio/gfile.c" + line="762">0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. @@ -43125,16 +45655,16 @@ This call does no blocking I/O. #gconstpointer to a #GFile + filename="gio/gfile.c" + line="756">#gconstpointer to a #GFile Checks to see if a file is native to the platform. + filename="gio/gfile.c" + line="444">Checks to see if a file is native to the platform. A native file is one expressed in the platform-native filename format, e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, @@ -43145,28 +45675,29 @@ filesystem via a userspace filesystem (FUSE), in these cases this call will return %FALSE, but g_file_get_path() will still return a native path. This call does no blocking I/O. - + %TRUE if @file is native + filename="gio/gfile.c" + line="460">%TRUE if @file is native input #GFile + filename="gio/gfile.c" + line="446">input #GFile + throws="1" + glib:async-func="make_directory_async"> Creates a directory. Note that this will only create a child directory + filename="gio/gfile.c" + line="4228">Creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the #GFile. To recursively create directories, see g_file_make_directory_with_parents(). This function will fail if the parent directory does not exist, setting @@ -43180,18 +45711,18 @@ For a local #GFile the newly created directory will have the default If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on successful creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4250">%TRUE on successful creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4230">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4231">optional #GCancellable object, %NULL to ignore @@ -43208,25 +45739,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.38" + glib:finish-func="make_directory_finish" + glib:sync-func="make_directory"> Asynchronously creates a directory. - + filename="gio/gfile.c" + line="4277">Asynchronously creates a directory. + input #GFile + filename="gio/gfile.c" + line="4279">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4280">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4281">optional #GCancellable object, %NULL to ignore @@ -43246,8 +45779,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4283">a #GAsyncReadyCallback to call when the request is satisfied @@ -43257,8 +45790,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="4285">the data to pass to callback function @@ -43268,60 +45801,61 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.38" throws="1"> Finishes an asynchronous directory creation, started with + filename="gio/gfile.c" + line="4310">Finishes an asynchronous directory creation, started with g_file_make_directory_async(). - + %TRUE on successful directory creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4319">%TRUE on successful directory creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4312">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4313">a #GAsyncResult + throws="1" + glib:async-func="make_symbolic_link_async"> Creates a symbolic link named @file which contains the string + filename="gio/gfile.c" + line="4458">Creates a symbolic link named @file which contains the string @symlink_value. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on the creation of a new symlink, %FALSE otherwise. + filename="gio/gfile.c" + line="4474">%TRUE on the creation of a new symlink, %FALSE otherwise. a #GFile with the name of the symlink to create + filename="gio/gfile.c" + line="4460">a #GFile with the name of the symlink to create a string with the path for the target + filename="gio/gfile.c" + line="4461">a string with the path for the target of the new symlink @@ -43330,8 +45864,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4463">optional #GCancellable object, %NULL to ignore @@ -43339,33 +45873,35 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.74" + glib:finish-func="make_symbolic_link_finish" + glib:sync-func="make_symbolic_link"> Asynchronously creates a symbolic link named @file which contains the + filename="gio/gfile.c" + line="4549">Asynchronously creates a symbolic link named @file which contains the string @symlink_value. - + a #GFile with the name of the symlink to create + filename="gio/gfile.c" + line="4551">a #GFile with the name of the symlink to create a string with the path for the target + filename="gio/gfile.c" + line="4552">a string with the path for the target of the new symlink the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4554">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4555">optional #GCancellable object, %NULL to ignore @@ -43385,8 +45921,8 @@ string @symlink_value. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4557">a #GAsyncReadyCallback to call when the request is satisfied @@ -43396,8 +45932,8 @@ string @symlink_value. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="4559">the data to pass to callback function @@ -43407,27 +45943,27 @@ string @symlink_value. version="2.74" throws="1"> Finishes an asynchronous symbolic link creation, started with + filename="gio/gfile.c" + line="4599">Finishes an asynchronous symbolic link creation, started with g_file_make_symbolic_link_async(). - + %TRUE on successful directory creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4608">%TRUE on successful directory creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4601">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4602">a #GAsyncResult @@ -43435,11 +45971,11 @@ g_file_make_symbolic_link_async(). + throws="1" + glib:async-func="measure_disk_usage_async"> Recursively measures the disk usage of @file. + filename="gio/gfile.c" + line="9025">Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered @@ -43457,25 +45993,25 @@ in a user interface. periodic progress updates while scanning. See the documentation for #GFileMeasureProgressCallback for information about when and how the callback will be invoked. - + %TRUE if successful, with the out parameters set. + filename="gio/gfile.c" + line="9056">%TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile + filename="gio/gfile.c" + line="9027">a #GFile #GFileMeasureFlags + filename="gio/gfile.c" + line="9028">#GFileMeasureFlags nullable="1" allow-none="1"> optional #GCancellable + filename="gio/gfile.c" + line="9029">optional #GCancellable a #GFileMeasureProgressCallback + filename="gio/gfile.c" + line="9030">a #GFileMeasureProgressCallback @@ -43503,8 +46040,8 @@ callback will be invoked. nullable="1" allow-none="1"> user_data for @progress_callback + filename="gio/gfile.c" + line="9031">user_data for @progress_callback optional="1" allow-none="1"> the number of bytes of disk space used + filename="gio/gfile.c" + line="9032">the number of bytes of disk space used optional="1" allow-none="1"> the number of directories encountered + filename="gio/gfile.c" + line="9033">the number of directories encountered optional="1" allow-none="1"> the number of non-directories encountered + filename="gio/gfile.c" + line="9034">the number of non-directories encountered @@ -43545,34 +46082,36 @@ callback will be invoked. + introspectable="0" + glib:finish-func="measure_disk_usage_finish" + glib:sync-func="measure_disk_usage"> Recursively measures the disk usage of @file. + filename="gio/gfile.c" + line="9082">Recursively measures the disk usage of @file. This is the asynchronous version of g_file_measure_disk_usage(). See there for more information. - + a #GFile + filename="gio/gfile.c" + line="9084">a #GFile #GFileMeasureFlags + filename="gio/gfile.c" + line="9085">#GFileMeasureFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="9086">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable + filename="gio/gfile.c" + line="9087">optional #GCancellable allow-none="1" closure="4"> a #GFileMeasureProgressCallback + filename="gio/gfile.c" + line="9088">a #GFileMeasureProgressCallback @@ -43600,8 +46139,8 @@ there for more information. nullable="1" allow-none="1"> user_data for @progress_callback + filename="gio/gfile.c" + line="9089">user_data for @progress_callback scope="async" closure="6"> a #GAsyncReadyCallback to call when complete + filename="gio/gfile.c" + line="9090">a #GAsyncReadyCallback to call when complete allow-none="1" closure="6"> the data to pass to callback function + filename="gio/gfile.c" + line="9091">the data to pass to callback function @@ -43632,29 +46171,29 @@ there for more information. version="2.38" throws="1"> Collects the results from an earlier call to + filename="gio/gfile.c" + line="9118">Collects the results from an earlier call to g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for more information. - + %TRUE if successful, with the out parameters set. + filename="gio/gfile.c" + line="9131">%TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile + filename="gio/gfile.c" + line="9120">a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback + filename="gio/gfile.c" + line="9121">the #GAsyncResult passed to your #GAsyncReadyCallback optional="1" allow-none="1"> the number of bytes of disk space used + filename="gio/gfile.c" + line="9122">the number of bytes of disk space used optional="1" allow-none="1"> the number of directories encountered + filename="gio/gfile.c" + line="9123">the number of directories encountered optional="1" allow-none="1"> the number of non-directories encountered + filename="gio/gfile.c" + line="9124">the number of non-directories encountered @@ -43696,8 +46235,8 @@ more information. invoker="monitor_directory" throws="1"> Obtains a directory monitor for the given file. + filename="gio/gfile.c" + line="5971">Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported. If @cancellable is not %NULL, then the operation can be cancelled by @@ -43709,26 +46248,25 @@ It does not make sense for @flags to contain directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor(). - + a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). + filename="gio/gfile.c" + line="5992">a #GFileMonitor for the given @file, + or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="5973">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="5974">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5975">optional #GCancellable object, %NULL to ignore @@ -43745,8 +46283,8 @@ you must register individual watches with g_file_monitor(). Obtains a file monitor for the given file. If no file notification + filename="gio/gfile.c" + line="6022">Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used. If @cancellable is not %NULL, then the operation can be cancelled by @@ -43760,11 +46298,11 @@ changes made through the filename contained in @file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the #GFileMonitor backend and/or filesystem type. - + a #GFileMonitor for the given @file, + filename="gio/gfile.c" + line="6045">a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). @@ -43772,14 +46310,14 @@ backend and/or filesystem type. input #GFile + filename="gio/gfile.c" + line="6024">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="6025">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="6026">optional #GCancellable object, %NULL to ignore + invoker="mount_enclosing_volume" + glib:finish-func="mount_enclosing_volume_finish"> Starts a @mount_operation, mounting the volume that contains + filename="gio/gfile.c" + line="7726">Starts a @mount_operation, mounting the volume that contains the file @location. When this operation has completed, @callback will be called with @@ -43808,21 +46347,21 @@ g_file_mount_enclosing_volume_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + input #GFile + filename="gio/gfile.c" + line="7728">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="7729">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation + filename="gio/gfile.c" + line="7730">a #GMountOperation or %NULL to avoid user interaction @@ -43840,8 +46379,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="7732">optional #GCancellable object, %NULL to ignore @@ -43852,8 +46391,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="7734">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -43863,8 +46402,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="7736">the data to pass to callback function @@ -43873,13 +46412,13 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. invoker="mount_enclosing_volume_finish" throws="1"> Finishes a mount operation started by g_file_mount_enclosing_volume(). - + filename="gio/gfile.c" + line="7776">Finishes a mount operation started by g_file_mount_enclosing_volume(). + %TRUE if successful. If an error has occurred, + filename="gio/gfile.c" + line="7784">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -43887,22 +46426,24 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="7778">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="7779">a #GAsyncResult - + Mounts a file of type G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="5514">Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using @mount_operation, you can request callbacks when, for instance, passwords are needed during authentication. @@ -43913,21 +46454,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="5516">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5517">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5518">a #GMountOperation, or %NULL to avoid user interaction @@ -43945,8 +46486,8 @@ the result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5520">optional #GCancellable object, %NULL to ignore @@ -43957,8 +46498,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5522">a #GAsyncReadyCallback to call when the request is satisfied @@ -43968,8 +46509,8 @@ the result of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="5524">the data to pass to callback function @@ -43978,38 +46519,41 @@ the result of the operation. invoker="mount_mountable_finish" throws="1"> Finishes a mount operation. See g_file_mount_mountable() for details. + filename="gio/gfile.c" + line="5569">Finishes a mount operation. See g_file_mount_mountable() for details. Finish an asynchronous mount operation that was started with g_file_mount_mountable(). - + a #GFile or %NULL on error. + filename="gio/gfile.c" + line="5580">a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="5571">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5572">a #GAsyncResult - + Tries to move the file or directory @source to the location specified + filename="gio/gfile.c" + line="3974">Tries to move the file or directory @source to the location specified by @destination. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves @@ -44042,30 +46586,30 @@ If the source is a directory and the target does not exist, or %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native move operation isn't available). - + %TRUE on successful move, %FALSE otherwise. + filename="gio/gfile.c" + line="4021">%TRUE on successful move, %FALSE otherwise. #GFile pointing to the source location + filename="gio/gfile.c" + line="3976">#GFile pointing to the source location #GFile pointing to the destination location + filename="gio/gfile.c" + line="3977">#GFile pointing to the destination location set of #GFileCopyFlags + filename="gio/gfile.c" + line="3978">set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3979">optional #GCancellable object, %NULL to ignore @@ -44085,8 +46629,8 @@ move operation isn't available). scope="call" closure="4"> #GFileProgressCallback + filename="gio/gfile.c" + line="3981">#GFileProgressCallback function for updates @@ -44095,17 +46639,21 @@ move operation isn't available). nullable="1" allow-none="1"> gpointer to user data for + filename="gio/gfile.c" + line="3983">gpointer to user data for the callback function - + Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). + filename="gio/gfile.c" + line="4108">Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_move(). The callback will run in the default main context @@ -44114,33 +46662,33 @@ run in. When the operation is finished, @callback will be called. You can then call g_file_move_finish() to get the result of the operation. - + #GFile pointing to the source location + filename="gio/gfile.c" + line="4110">#GFile pointing to the source location #GFile pointing to the destination location + filename="gio/gfile.c" + line="4111">#GFile pointing to the destination location set of #GFileCopyFlags + filename="gio/gfile.c" + line="4112">set of #GFileCopyFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4113">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4114">optional #GCancellable object, %NULL to ignore @@ -44160,8 +46708,8 @@ g_file_move_finish() to get the result of the operation. scope="call" closure="5"> + filename="gio/gfile.c" + line="4116"> #GFileProgressCallback function for updates @@ -44170,8 +46718,8 @@ g_file_move_finish() to get the result of the operation. nullable="1" allow-none="1"> gpointer to user data for the callback function + filename="gio/gfile.c" + line="4118">gpointer to user data for the callback function scope="async" closure="7"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="4119">a #GAsyncReadyCallback to call when the request is satisfied @@ -44192,8 +46740,8 @@ g_file_move_finish() to get the result of the operation. allow-none="1" closure="7"> the data to pass to callback function + filename="gio/gfile.c" + line="4121">the data to pass to callback function @@ -44203,27 +46751,27 @@ g_file_move_finish() to get the result of the operation. version="2.72" throws="1"> Finishes an asynchronous file movement, started with + filename="gio/gfile.c" + line="4200">Finishes an asynchronous file movement, started with g_file_move_async(). - + %TRUE on successful file move, %FALSE otherwise. + filename="gio/gfile.c" + line="4209">%TRUE on successful file move, %FALSE otherwise. input source #GFile + filename="gio/gfile.c" + line="4202">input source #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4203">a #GAsyncResult @@ -44231,10 +46779,11 @@ g_file_move_async(). + throws="1" + glib:async-func="open_readwrite_async"> Opens an existing file for reading and writing. The result is + filename="gio/gfile.c" + line="1935">Opens an existing file for reading and writing. The result is a #GFileIOStream that can be used to read and write the contents of the file. @@ -44250,19 +46799,19 @@ what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. - + #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="1958">#GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to open + filename="gio/gfile.c" + line="1937">#GFile to open nullable="1" allow-none="1"> a #GCancellable + filename="gio/gfile.c" + line="1938">a #GCancellable + version="2.22" + glib:finish-func="open_readwrite_finish" + glib:sync-func="open_readwrite"> Asynchronously opens @file for reading and writing. + filename="gio/gfile.c" + line="2394">Asynchronously opens @file for reading and writing. For more details, see g_file_open_readwrite() which is the synchronous version of this call. @@ -44289,21 +46840,21 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_open_readwrite_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2396">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2397">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2398">optional #GCancellable object, %NULL to ignore @@ -44323,8 +46874,8 @@ the result of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2400">a #GAsyncReadyCallback to call when the request is satisfied @@ -44334,8 +46885,8 @@ the result of the operation. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="2402">the data to pass to callback function @@ -44345,38 +46896,39 @@ the result of the operation. version="2.22" throws="1"> Finishes an asynchronous file read operation started with + filename="gio/gfile.c" + line="2434">Finishes an asynchronous file read operation started with g_file_open_readwrite_async(). - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2443">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2436">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2437">a #GAsyncResult + version="2.22" + glib:finish-func="poll_mountable_finish"> Polls a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="9329">Polls a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -44385,15 +46937,15 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="9331">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="9332">optional #GCancellable object, %NULL to ignore scope="async" closure="2"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="9333">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -44423,8 +46975,8 @@ the result of the operation. allow-none="1" closure="2"> the data to pass to callback function + filename="gio/gfile.c" + line="9335">the data to pass to callback function @@ -44434,38 +46986,38 @@ the result of the operation. version="2.22" throws="1"> Finishes a poll operation. See g_file_poll_mountable() for details. + filename="gio/gfile.c" + line="9376">Finishes a poll operation. See g_file_poll_mountable() for details. Finish an asynchronous poll operation that was polled with g_file_poll_mountable(). - + %TRUE if the operation finished successfully. %FALSE + filename="gio/gfile.c" + line="9387">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9378">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9379">a #GAsyncResult Checks whether @file has the prefix specified by @prefix. + filename="gio/gfile.c" + line="945">Checks whether @file has the prefix specified by @prefix. In other words, if the names of initial elements of @file's pathname match @prefix. Only full pathname elements are matched, @@ -44479,35 +47031,91 @@ This call does no I/O, as it works purely on names. As such it can sometimes return %FALSE even if @file is inside a @prefix (from a filesystem point of view), because the prefix of @file is an alias of @prefix. - + %TRUE if the @file's parent, grandparent, etc is @prefix, + filename="gio/gfile.c" + line="965">%TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="948">input #GFile input #GFile + filename="gio/gfile.c" + line="947">input #GFile + + Utility function to check if a particular file exists. + +The fallback implementation of this API is using [method@Gio.File.query_info] +and therefore may do blocking I/O. To asynchronously query the existence +of a file, use [method@Gio.File.query_info_async]. + +Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) +and then execute something based on the outcome of that, because the +file might have been created or removed in between the operations. The +general approach to handling that is to not check, but just do the +operation and handle the errors as they come. + +As an example of race-free checking, take the case of reading a file, +and if it doesn't exist, creating it. There are two racy versions: read +it, and on error create it; and: check if it exists, if not create it. +These can both result in two processes creating the file (with perhaps +a partially written file as the result). The correct approach is to +always try to create the file with g_file_create() which will either +atomically create the file or fail with a %G_IO_ERROR_EXISTS error. + +However, in many cases an existence check is useful in a user interface, +for instance to make a menu item sensitive/insensitive, so that you don't +have to fool users that something is possible and then just show an error +dialog. If you do this, you should make sure to also handle the errors +that can happen due to races when you execute the operation. + + + %TRUE if the file exists (and can be detected without error), + %FALSE otherwise (or if cancelled). + + + + + input #GFile + + + + optional #GCancellable object, + %NULL to ignore + + + + + throws="1" + glib:async-func="query_filesystem_info_async"> Similar to g_file_query_info(), but obtains information + filename="gio/gfile.c" + line="1434">Similar to g_file_query_info(), but obtains information about the filesystem the @file is on, rather than the file itself. For instance the amount of space available and the type of the filesystem. @@ -44532,25 +47140,25 @@ returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileInfo or %NULL if there was an error. + filename="gio/gfile.c" + line="1468">a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1436">input #GFile an attribute query string + filename="gio/gfile.c" + line="1437">an attribute query string nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1438">optional #GCancellable object, %NULL to ignore + invoker="query_filesystem_info_async" + glib:finish-func="query_filesystem_info_finish" + glib:sync-func="query_filesystem_info"> Asynchronously gets the requested information about the filesystem + filename="gio/gfile.c" + line="1497">Asynchronously gets the requested information about the filesystem that the specified @file is on. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). @@ -44580,27 +47190,27 @@ synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="1499">input #GFile an attribute query string + filename="gio/gfile.c" + line="1500">an attribute query string the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1501">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1502">optional #GCancellable object, %NULL to ignore @@ -44620,8 +47230,8 @@ operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1504">a #GAsyncReadyCallback to call when the request is satisfied @@ -44631,8 +47241,8 @@ operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="1506">the data to pass to callback function @@ -44641,14 +47251,14 @@ operation. invoker="query_filesystem_info_finish" throws="1"> Finishes an asynchronous filesystem info query. + filename="gio/gfile.c" + line="1541">Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async(). - + #GFileInfo for given @file + filename="gio/gfile.c" + line="1550">#GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). @@ -44656,22 +47266,25 @@ See g_file_query_filesystem_info_async(). input #GFile + filename="gio/gfile.c" + line="1543">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1544">a #GAsyncResult - + Gets the requested information about specified @file. + filename="gio/gfile.c" + line="1289">Gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as the type or size of the file). @@ -44701,31 +47314,31 @@ about the symlink itself will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileInfo for the given @file, or %NULL + filename="gio/gfile.c" + line="1329">a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1291">input #GFile an attribute query string + filename="gio/gfile.c" + line="1292">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1293">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1294">optional #GCancellable object, %NULL to ignore - + Asynchronously gets the requested information about specified @file. + filename="gio/gfile.c" + line="1359">Asynchronously gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). @@ -44752,33 +47368,33 @@ version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="1361">input #GFile an attribute query string + filename="gio/gfile.c" + line="1362">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1363">a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1364">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1365">optional #GCancellable object, %NULL to ignore @@ -44798,8 +47414,8 @@ then call g_file_query_info_finish() to get the result of the operation. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1367">a #GAsyncReadyCallback to call when the request is satisfied @@ -44809,8 +47425,8 @@ then call g_file_query_info_finish() to get the result of the operation. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="1369">the data to pass to callback function @@ -44819,14 +47435,14 @@ then call g_file_query_info_finish() to get the result of the operation. invoker="query_info_finish" throws="1"> Finishes an asynchronous file info query. + filename="gio/gfile.c" + line="1404">Finishes an asynchronous file info query. See g_file_query_info_async(). - + #GFileInfo for given @file + filename="gio/gfile.c" + line="1413">#GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). @@ -44834,14 +47450,14 @@ See g_file_query_info_async(). input #GFile + filename="gio/gfile.c" + line="1406">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1407">a #GAsyncResult @@ -44850,8 +47466,8 @@ See g_file_query_info_async(). invoker="query_settable_attributes" throws="1"> Obtain the list of settable attributes for the file. + filename="gio/gfile.c" + line="4981">Obtain the list of settable attributes for the file. Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will @@ -44861,11 +47477,11 @@ specific file may not support a specific attribute. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFileAttributeInfoList describing the settable attributes. + filename="gio/gfile.c" + line="4999">a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() @@ -44873,8 +47489,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="4983">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4984">optional #GCancellable object, %NULL to ignore @@ -44893,19 +47509,19 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. invoker="query_writable_namespaces" throws="1"> Obtain the list of attribute namespaces where new attributes + filename="gio/gfile.c" + line="5039">Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFileAttributeInfoList describing the writable namespaces. + filename="gio/gfile.c" + line="5054">a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() @@ -44913,8 +47529,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="5041">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5042">optional #GCancellable object, %NULL to ignore - + Asynchronously opens @file for reading. + filename="gio/gfile.c" + line="2107">Asynchronously opens @file for reading. For more details, see g_file_read() which is the synchronous version of this call. @@ -44940,21 +47558,21 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_read_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2109">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2110">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2111">optional #GCancellable object, %NULL to ignore @@ -44974,8 +47592,8 @@ of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2113">a #GAsyncReadyCallback to call when the request is satisfied @@ -44985,44 +47603,44 @@ of the operation. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="2115">the data to pass to callback function Finishes an asynchronous file read operation started with + filename="gio/gfile.c" + line="2145">Finishes an asynchronous file read operation started with g_file_read_async(). - + a #GFileInputStream or %NULL on error. + filename="gio/gfile.c" + line="2154">a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2147">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2148">a #GAsyncResult Opens a file for reading. The result is a #GFileInputStream that + filename="gio/gfile.c" + line="1688">Opens a file for reading. The result is a #GFileInputStream that can be used to read the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by @@ -45033,19 +47651,19 @@ If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + #GFileInputStream or %NULL on error. + filename="gio/gfile.c" + line="1706">#GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to read + filename="gio/gfile.c" + line="1690">#GFile to read nullable="1" allow-none="1"> a #GCancellable + filename="gio/gfile.c" + line="1691">a #GCancellable - + Returns an output stream for overwriting the file, possibly + filename="gio/gfile.c" + line="1847">Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. @@ -45103,19 +47724,19 @@ file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileOutputStream or %NULL on error. + filename="gio/gfile.c" + line="1900">a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1849">input #GFile nullable="1" allow-none="1"> an optional [entity tag][gfile-etag] + filename="gio/gfile.c" + line="1850">an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="1852">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1853">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1854">optional #GCancellable object, %NULL to ignore - + Asynchronously overwrites the file, replacing the contents, + filename="gio/gfile.c" + line="2316">Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace() which is @@ -45164,15 +47788,15 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2318">input #GFile nullable="1" allow-none="1"> an [entity tag][gfile-etag] for the current #GFile, + filename="gio/gfile.c" + line="2319">an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2321">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2322">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2323">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2324">optional #GCancellable object, %NULL to ignore @@ -45220,8 +47844,8 @@ of the operation. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2326">a #GAsyncReadyCallback to call when the request is satisfied @@ -45231,8 +47855,8 @@ of the operation. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/gfile.c" + line="2328">the data to pass to callback function @@ -45241,28 +47865,28 @@ of the operation. invoker="replace_finish" throws="1"> Finishes an asynchronous file replace operation started with + filename="gio/gfile.c" + line="2365">Finishes an asynchronous file replace operation started with g_file_replace_async(). - + a #GFileOutputStream, or %NULL on error. + filename="gio/gfile.c" + line="2374">a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2367">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2368">a #GAsyncResult @@ -45270,10 +47894,11 @@ g_file_replace_async(). + throws="1" + glib:async-func="replace_readwrite_async"> Returns an output stream for overwriting the file in readwrite mode, + filename="gio/gfile.c" + line="2052">Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. @@ -45283,19 +47908,19 @@ same thing but returns an output stream only. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2074">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). a #GFile + filename="gio/gfile.c" + line="2054">a #GFile nullable="1" allow-none="1"> an optional [entity tag][gfile-etag] + filename="gio/gfile.c" + line="2055">an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2057">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2058">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2059">optional #GCancellable object, %NULL to ignore @@ -45334,10 +47959,12 @@ rather than just opening for reading or writing. + version="2.22" + glib:finish-func="replace_readwrite_finish" + glib:sync-func="replace_readwrite"> Asynchronously overwrites the file in read-write mode, + filename="gio/gfile.c" + line="2540">Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. @@ -45347,15 +47974,15 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_readwrite_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2542">input #GFile nullable="1" allow-none="1"> an [entity tag][gfile-etag] for the current #GFile, + filename="gio/gfile.c" + line="2543">an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2545">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2546">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2547">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2548">optional #GCancellable object, %NULL to ignore @@ -45403,8 +48030,8 @@ the result of the operation. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2550">a #GAsyncReadyCallback to call when the request is satisfied @@ -45414,8 +48041,8 @@ the result of the operation. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/gfile.c" + line="2552">the data to pass to callback function @@ -45425,28 +48052,28 @@ the result of the operation. version="2.22" throws="1"> Finishes an asynchronous file replace operation started with + filename="gio/gfile.c" + line="2592">Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async(). - + a #GFileIOStream, or %NULL on error. + filename="gio/gfile.c" + line="2601">a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2594">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2595">a #GAsyncResult @@ -45454,39 +48081,39 @@ g_file_replace_readwrite_async(). Resolves a relative path for @file to an absolute path. + filename="gio/gfile.c" + line="1019">Resolves a relative path for @file to an absolute path. This call does no blocking I/O. If the @relative_path is an absolute path name, the resolution is done absolutely (without taking @file path as base). - + a #GFile for the resolved path. + filename="gio/gfile.c" + line="1031">a #GFile for the resolved path. input #GFile + filename="gio/gfile.c" + line="1021">input #GFile a given relative path string + filename="gio/gfile.c" + line="1022">a given relative path string Sets an attribute in the file with attribute name @attribute to @value_p. + filename="gio/gfile.c" + line="5099">Sets an attribute in the file with attribute name @attribute to @value_p. Some attributes can be unset by setting @type to %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. @@ -45494,30 +48121,30 @@ Some attributes can be unset by setting @type to If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the attribute was set, %FALSE otherwise. + filename="gio/gfile.c" + line="5120">%TRUE if the attribute was set, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5101">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5102">a string containing the attribute's name The type of the attribute + filename="gio/gfile.c" + line="5103">The type of the attribute nullable="1" allow-none="1"> a pointer to the value (or the pointer + filename="gio/gfile.c" + line="5104">a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5106">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5107">optional #GCancellable object, %NULL to ignore + invoker="set_attributes_async" + glib:finish-func="set_attributes_finish"> Asynchronously sets the attributes of @file with @info. + filename="gio/gfile.c" + line="5243">Asynchronously sets the attributes of @file with @info. For more details, see g_file_set_attributes_from_info(), which is the synchronous version of this call. @@ -45560,33 +48188,33 @@ which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_attributes_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="5245">input #GFile a #GFileInfo + filename="gio/gfile.c" + line="5246">a #GFileInfo a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5247">a #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="5248">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5249">optional #GCancellable object, %NULL to ignore @@ -45606,8 +48234,8 @@ the result of the operation. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5251">a #GAsyncReadyCallback to call when the request is satisfied @@ -45617,8 +48245,8 @@ the result of the operation. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="5253">the data to pass to callback function @@ -45627,26 +48255,26 @@ the result of the operation. invoker="set_attributes_finish" throws="1"> Finishes setting an attribute started in g_file_set_attributes_async(). - + filename="gio/gfile.c" + line="5288">Finishes setting an attribute started in g_file_set_attributes_async(). + %TRUE if the attributes were set correctly, %FALSE otherwise. + filename="gio/gfile.c" + line="5297">%TRUE if the attributes were set correctly, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5290">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5291">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> a #GFileInfo + filename="gio/gfile.c" + line="5292">a #GFileInfo @@ -45664,8 +48292,8 @@ the result of the operation. invoker="set_attributes_from_info" throws="1"> Tries to set all attributes in the #GFileInfo on the target + filename="gio/gfile.c" + line="5152">Tries to set all attributes in the #GFileInfo on the target values, not stopping on the first error. If there is any error during this operation then @error will @@ -45677,30 +48305,30 @@ also detect further errors. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %FALSE if there was any error, %TRUE otherwise. + filename="gio/gfile.c" + line="5174">%FALSE if there was any error, %TRUE otherwise. input #GFile + filename="gio/gfile.c" + line="5154">input #GFile a #GFileInfo + filename="gio/gfile.c" + line="5155">a #GFileInfo #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5156">#GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5157">optional #GCancellable object, %NULL to ignore @@ -45717,10 +48345,11 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + throws="1" + glib:async-func="set_display_name_async"> Renames @file to the specified display name. + filename="gio/gfile.c" + line="4854">Renames @file to the specified display name. The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the @file is renamed to this. @@ -45735,11 +48364,11 @@ On success the resulting converted filename is returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFile specifying what @file was renamed to, + filename="gio/gfile.c" + line="4878">a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). @@ -45747,14 +48376,14 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="4856">input #GFile a string + filename="gio/gfile.c" + line="4857">a string nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4858">optional #GCancellable object, %NULL to ignore + invoker="set_display_name_async" + glib:finish-func="set_display_name_finish" + glib:sync-func="set_display_name"> Asynchronously sets the display name for a given #GFile. + filename="gio/gfile.c" + line="4910">Asynchronously sets the display name for a given #GFile. For more details, see g_file_set_display_name() which is the synchronous version of this call. @@ -45781,27 +48412,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_display_name_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="4912">input #GFile a string + filename="gio/gfile.c" + line="4913">a string the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4914">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4915">optional #GCancellable object, %NULL to ignore @@ -45821,8 +48452,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="4917">a #GAsyncReadyCallback to call when the request is satisfied @@ -45832,8 +48463,8 @@ the result of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="4919">the data to pass to callback function @@ -45842,38 +48473,39 @@ the result of the operation. invoker="set_display_name_finish" throws="1"> Finishes setting a display name started with + filename="gio/gfile.c" + line="4952">Finishes setting a display name started with g_file_set_display_name_async(). - + a #GFile or %NULL on error. + filename="gio/gfile.c" + line="4961">a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="4954">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4955">a #GAsyncResult + version="2.22" + glib:finish-func="start_mountable_finish"> Starts a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="9150">Starts a file of type %G_FILE_TYPE_MOUNTABLE. Using @start_operation, you can request callbacks when, for instance, passwords are needed during authentication. @@ -45884,21 +48516,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="9152">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="9153">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, or %NULL to avoid user interaction + filename="gio/gfile.c" + line="9154">a #GMountOperation, or %NULL to avoid user interaction nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="9155">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + filename="gio/gfile.c" + line="9156">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="9157">the data to pass to callback function @@ -45947,40 +48579,41 @@ the result of the operation. version="2.22" throws="1"> Finishes a start operation. See g_file_start_mountable() for details. + filename="gio/gfile.c" + line="9204">Finishes a start operation. See g_file_start_mountable() for details. Finish an asynchronous start operation that was started with g_file_start_mountable(). - + %TRUE if the operation finished successfully. %FALSE + filename="gio/gfile.c" + line="9215">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9206">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9207">a #GAsyncResult + version="2.22" + glib:finish-func="stop_mountable_finish"> Stops a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="9239">Stops a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -45989,21 +48622,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_stop_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="9241">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="9242">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="9243">a #GMountOperation, or %NULL to avoid user interaction. @@ -46021,8 +48654,8 @@ the result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="9245">optional #GCancellable object, %NULL to ignore @@ -46033,8 +48666,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="9247">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -46044,8 +48677,8 @@ the result of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="9249">the data to pass to callback function @@ -46055,59 +48688,65 @@ the result of the operation. version="2.22" throws="1"> Finishes a stop operation, see g_file_stop_mountable() for details. + filename="gio/gfile.c" + line="9294">Finishes a stop operation, see g_file_stop_mountable() for details. Finish an asynchronous stop operation that was started with g_file_stop_mountable(). - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="9305">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9296">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9297">a #GAsyncResult - + Sends @file to the "Trashcan", if possible. This is similar to + filename="gio/gfile.c" + line="4747">Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. -Not all file systems support trashing, so this call can return the +Trashing is disabled for system mounts by default (see +g_unix_mount_entry_is_system_internal()), so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix -mount option can be used to disable g_file_trash() support for certain +mount option can be used to disable g_file_trash() support for particular mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. +Since 2.82, the `x-gvfs-trash` unix mount option can be used to enable +g_file_trash() support for particular system mounts. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on successful trash, %FALSE otherwise. + filename="gio/gfile.c" + line="4768">%TRUE on successful trash, %FALSE otherwise. #GFile to send to trash + filename="gio/gfile.c" + line="4749">#GFile to send to trash nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4750">optional #GCancellable object, %NULL to ignore - + Asynchronously sends @file to the Trash location, if possible. - + filename="gio/gfile.c" + line="4795">Asynchronously sends @file to the Trash location, if possible. + input #GFile + filename="gio/gfile.c" + line="4797">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4798">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4799">optional #GCancellable object, %NULL to ignore @@ -46160,8 +48803,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4801">a #GAsyncReadyCallback to call when the request is satisfied @@ -46171,8 +48814,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="4803">the data to pass to callback function @@ -46182,27 +48825,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.38" throws="1"> Finishes an asynchronous file trashing operation, started with + filename="gio/gfile.c" + line="4828">Finishes an asynchronous file trashing operation, started with g_file_trash_async(). - + %TRUE on successful trash, %FALSE otherwise. + filename="gio/gfile.c" + line="4837">%TRUE on successful trash, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4830">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4831">a #GAsyncResult @@ -46210,10 +48853,11 @@ g_file_trash_async(). + deprecated-version="2.22" + glib:finish-func="unmount_mountable_finish"> Unmounts a file of type G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="5602">Unmounts a file of type G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -46223,21 +48867,21 @@ When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. Use g_file_unmount_mountable_with_operation() instead. - + input #GFile + filename="gio/gfile.c" + line="5604">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5605">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5606">optional #GCancellable object, %NULL to ignore @@ -46257,8 +48901,8 @@ the result of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5608">a #GAsyncReadyCallback to call when the request is satisfied @@ -46268,8 +48912,8 @@ the result of the operation. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="5610">the data to pass to callback function @@ -46280,42 +48924,43 @@ the result of the operation. deprecated-version="2.22" throws="1"> Finishes an unmount operation, see g_file_unmount_mountable() for details. + filename="gio/gfile.c" + line="5653">Finishes an unmount operation, see g_file_unmount_mountable() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable(). Use g_file_unmount_mountable_with_operation_finish() instead. - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="5664">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5655">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5656">a #GAsyncResult + version="2.22" + glib:finish-func="unmount_mountable_with_operation_finish"> Unmounts a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="5689">Unmounts a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -46324,21 +48969,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="5691">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5692">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5693">a #GMountOperation, or %NULL to avoid user interaction @@ -46356,8 +49001,8 @@ the result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5695">optional #GCancellable object, %NULL to ignore @@ -46368,8 +49013,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5697">a #GAsyncReadyCallback to call when the request is satisfied @@ -46379,8 +49024,8 @@ the result of the operation. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="5699">the data to pass to callback function @@ -46390,39 +49035,42 @@ the result of the operation. version="2.22" throws="1"> Finishes an unmount operation, + filename="gio/gfile.c" + line="5751">Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable_with_operation(). - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="5763">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5753">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5754">a #GAsyncResult - + Gets an output stream for appending data to the file. + filename="gio/gfile.c" + line="1734">Gets an output stream for appending data to the file. If the file doesn't already exist it is created. By default files created are generally readable by everyone, @@ -46439,25 +49087,25 @@ Some file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileOutputStream, or %NULL on error. + filename="gio/gfile.c" + line="1760">a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1736">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1737">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1738">optional #GCancellable object, %NULL to ignore - + Asynchronously opens @file for appending. + filename="gio/gfile.c" + line="2174">Asynchronously opens @file for appending. For more details, see g_file_append_to() which is the synchronous version of this call. @@ -46483,27 +49134,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_append_to_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2176">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2177">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2178">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2179">optional #GCancellable object, %NULL to ignore @@ -46523,8 +49174,8 @@ of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2181">a #GAsyncReadyCallback to call when the request is satisfied @@ -46533,8 +49184,8 @@ of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2183">the data to pass to callback function @@ -46543,14 +49194,14 @@ of the operation. c:identifier="g_file_append_to_finish" throws="1"> Finishes an asynchronous file append operation started with + filename="gio/gfile.c" + line="2215">Finishes an asynchronous file append operation started with g_file_append_to_async(). - + a valid #GFileOutputStream + filename="gio/gfile.c" + line="2224">a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). @@ -46558,14 +49209,14 @@ g_file_append_to_async(). input #GFile + filename="gio/gfile.c" + line="2217">input #GFile #GAsyncResult + filename="gio/gfile.c" + line="2218">#GAsyncResult @@ -46575,8 +49226,8 @@ g_file_append_to_async(). version="2.68" throws="1"> Prepares the file attribute query string for copying to @file. + filename="gio/gfile.c" + line="2769">Prepares the file attribute query string for copying to @file. This function prepares an attribute query string to be passed to g_file_query_info() to get a list of attributes @@ -46585,25 +49236,25 @@ for the detailed description). This function is used by the implementation of g_file_copy_attributes() and is useful when one needs to query and set the attributes in two stages (e.g., for recursive move of a directory). - + an attribute query string for g_file_query_info(), + filename="gio/gfile.c" + line="2787">an attribute query string for g_file_query_info(), or %NULL if an error occurs. a #GFile to copy attributes to + filename="gio/gfile.c" + line="2771">a #GFile to copy attributes to a set of #GFileCopyFlags + filename="gio/gfile.c" + line="2772">a set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2773">optional #GCancellable object, %NULL to ignore - + Copies the file @source to the location specified by @destination. + filename="gio/gfile.c" + line="3647">Copies the file @source to the location specified by @destination. Can not handle recursive copies of directories. If the flag %G_FILE_COPY_OVERWRITE is specified an already @@ -46661,30 +49315,30 @@ If the source is a directory and the target does not exist, or If you are interested in copying the #GFile object itself (not the on-disk file), see g_file_dup(). - + %TRUE on success, %FALSE otherwise. + filename="gio/gfile.c" + line="3700">%TRUE on success, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="3649">input #GFile destination #GFile + filename="gio/gfile.c" + line="3650">destination #GFile set of #GFileCopyFlags + filename="gio/gfile.c" + line="3651">set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3652">optional #GCancellable object, %NULL to ignore @@ -46704,8 +49358,8 @@ file), see g_file_dup(). scope="call" closure="4"> function to callback with + filename="gio/gfile.c" + line="3654">function to callback with progress information, or %NULL if progress information is not needed @@ -46714,16 +49368,20 @@ file), see g_file_dup(). nullable="1" allow-none="1"> user data to pass to @progress_callback + filename="gio/gfile.c" + line="3656">user data to pass to @progress_callback - + Copies the file @source to the location specified by @destination + filename="gio/gfile.c" + line="3775">Copies the file @source to the location specified by @destination asynchronously. For details of the behaviour, see g_file_copy(). If @progress_callback is not %NULL, then that function that will be called @@ -46733,33 +49391,33 @@ run in. When the operation is finished, @callback will be called. You can then call g_file_copy_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="3777">input #GFile destination #GFile + filename="gio/gfile.c" + line="3778">destination #GFile set of #GFileCopyFlags + filename="gio/gfile.c" + line="3779">set of #GFileCopyFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="3780">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3781">optional #GCancellable object, %NULL to ignore @@ -46779,8 +49437,8 @@ g_file_copy_finish() to get the result of the operation. scope="notified" closure="5"> + filename="gio/gfile.c" + line="3783"> function to callback with progress information, or %NULL if progress information is not needed @@ -46790,8 +49448,8 @@ g_file_copy_finish() to get the result of the operation. nullable="1" allow-none="1"> user data to pass to @progress_callback + filename="gio/gfile.c" + line="3786">user data to pass to @progress_callback scope="async" closure="7"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="3787">a #GAsyncReadyCallback to call when the request is satisfied @@ -46811,18 +49469,84 @@ g_file_copy_finish() to get the result of the operation. nullable="1" allow-none="1"> the data to pass to callback + filename="gio/gfile.c" + line="3789">the data to pass to callback + + Version of [method@Gio.File.copy_async] using closures instead of callbacks for +easier binding in other languages. + + + + + + + input [type@Gio.File] + + + + destination [type@Gio.File] + + + + set of [flags@Gio.FileCopyFlags] + + + + the [I/O priority](iface.AsyncResult.html#io-priority) of the request + + + + optional [class@Gio.Cancellable] object, + `NULL` to ignore + + + + [type@GObject.Closure] to invoke with progress + information, or `NULL` if progress information is not needed + + + + [type@GObject.Closure] to invoke when the request is satisfied + + + + Copies the file attributes from @source to @destination. + filename="gio/gfile.c" + line="2883">Copies the file attributes from @source to @destination. Normally only a subset of the file attributes are copied, those that are copies in a normal file copy operation @@ -46830,31 +49554,31 @@ those that are copies in a normal file copy operation if %G_FILE_COPY_ALL_METADATA is specified in @flags, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source. - + %TRUE if the attributes were copied successfully, + filename="gio/gfile.c" + line="2901">%TRUE if the attributes were copied successfully, %FALSE otherwise. a #GFile with attributes + filename="gio/gfile.c" + line="2885">a #GFile with attributes a #GFile to copy attributes to + filename="gio/gfile.c" + line="2886">a #GFile to copy attributes to a set of #GFileCopyFlags + filename="gio/gfile.c" + line="2887">a set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2888">optional #GCancellable object, %NULL to ignore @@ -46871,34 +49595,37 @@ is useful when implementing move by copy + delete source. Finishes copying the file started with g_file_copy_async(). - + filename="gio/gfile.c" + line="3947">Finishes copying the file started with g_file_copy_async(). + a %TRUE on success, %FALSE on error. + filename="gio/gfile.c" + line="3955">a %TRUE on success, %FALSE on error. input #GFile + filename="gio/gfile.c" + line="3949">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="3950">a #GAsyncResult - + Creates a new file and returns an output stream for writing to it. + filename="gio/gfile.c" + line="1789">Creates a new file and returns an output stream for writing to it. The file must not already exist. By default files created are generally readable by everyone, @@ -46917,11 +49644,11 @@ allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileOutputStream for the newly created + filename="gio/gfile.c" + line="1817">a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). @@ -46929,14 +49656,14 @@ of filesystem the file is on. input #GFile + filename="gio/gfile.c" + line="1791">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1792">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1793">optional #GCancellable object, %NULL to ignore - + Asynchronously creates a new file and returns an output stream + filename="gio/gfile.c" + line="2245">Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see g_file_create() which is @@ -46963,27 +49693,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2247">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2248">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2249">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2250">optional #GCancellable object, %NULL to ignore @@ -47003,8 +49733,8 @@ of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2252">a #GAsyncReadyCallback to call when the request is satisfied @@ -47013,8 +49743,8 @@ of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2254">the data to pass to callback function @@ -47023,28 +49753,28 @@ of the operation. c:identifier="g_file_create_finish" throws="1"> Finishes an asynchronous file create operation started with + filename="gio/gfile.c" + line="2287">Finishes an asynchronous file create operation started with g_file_create_async(). - + a #GFileOutputStream or %NULL on error. + filename="gio/gfile.c" + line="2296">a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2289">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2290">a #GAsyncResult @@ -47052,10 +49782,11 @@ g_file_create_async(). + throws="1" + glib:async-func="create_readwrite_async"> Creates a new file and returns a stream for reading and + filename="gio/gfile.c" + line="1988">Creates a new file and returns a stream for reading and writing to it. The file must not already exist. By default files created are generally readable by everyone, @@ -47078,11 +49809,11 @@ kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. - + a #GFileIOStream for the newly created + filename="gio/gfile.c" + line="2020">a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). @@ -47090,14 +49821,14 @@ streaming, rather than just opening for reading or writing. a #GFile + filename="gio/gfile.c" + line="1990">a #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1991">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1992">optional #GCancellable object, %NULL to ignore @@ -47114,10 +49845,12 @@ streaming, rather than just opening for reading or writing. + version="2.22" + glib:finish-func="create_readwrite_finish" + glib:sync-func="create_readwrite"> Asynchronously creates a new file and returns a stream + filename="gio/gfile.c" + line="2465">Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist. For more details, see g_file_create_readwrite() which is @@ -47126,27 +49859,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_readwrite_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2467">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2468">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2469">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2470">optional #GCancellable object, %NULL to ignore @@ -47166,8 +49899,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2472">a #GAsyncReadyCallback to call when the request is satisfied @@ -47176,8 +49909,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2474">the data to pass to callback function @@ -47187,36 +49920,39 @@ the result of the operation. version="2.22" throws="1"> Finishes an asynchronous file create operation started with + filename="gio/gfile.c" + line="2509">Finishes an asynchronous file create operation started with g_file_create_readwrite_async(). - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2518">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2511">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2512">a #GAsyncResult - + Deletes a file. If the @file is a directory, it will only be + filename="gio/gfile.c" + line="4628">Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows @@ -47237,18 +49973,18 @@ if (!g_file_delete (my_file, my_cancellable, &local_error) && If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the file was deleted. %FALSE otherwise. + filename="gio/gfile.c" + line="4657">%TRUE if the file was deleted. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4630">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4631">optional #GCancellable object, %NULL to ignore @@ -47265,27 +50001,29 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.34" + glib:finish-func="delete_finish" + glib:sync-func="delete"> Asynchronously delete a file. If the @file is a directory, it will + filename="gio/gfile.c" + line="4684">Asynchronously delete a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). - + input #GFile + filename="gio/gfile.c" + line="4686">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4687">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4688">optional #GCancellable object, %NULL to ignore @@ -47305,8 +50043,8 @@ g_unlink(). scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4690">a #GAsyncReadyCallback to call when the request is satisfied @@ -47315,8 +50053,8 @@ g_unlink(). nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="4692">the data to pass to callback function @@ -47326,34 +50064,34 @@ g_unlink(). version="2.34" throws="1"> Finishes deleting a file started with g_file_delete_async(). - + filename="gio/gfile.c" + line="4719">Finishes deleting a file started with g_file_delete_async(). + %TRUE if the file was deleted. %FALSE otherwise. + filename="gio/gfile.c" + line="4727">%TRUE if the file was deleted. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4721">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4722">a #GAsyncResult Duplicates a #GFile handle. This operation does not duplicate + filename="gio/gfile.c" + line="724">Duplicates a #GFile handle. This operation does not duplicate the actual file or directory represented by the #GFile; see g_file_copy() if attempting to copy a file. @@ -47363,19 +50101,19 @@ within the same thread, use g_object_ref() to increment the existing object’s reference count. This call does no blocking I/O. - + a new #GFile that is a duplicate + filename="gio/gfile.c" + line="739">a new #GFile that is a duplicate of the given #GFile. input #GFile + filename="gio/gfile.c" + line="726">input #GFile @@ -47383,10 +50121,11 @@ This call does no blocking I/O. + deprecated-version="2.22" + glib:finish-func="eject_mountable_finish"> Starts an asynchronous eject on a mountable. + filename="gio/gfile.c" + line="5790">Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_finish(). @@ -47395,21 +50134,21 @@ If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Use g_file_eject_mountable_with_operation() instead. - + input #GFile + filename="gio/gfile.c" + line="5792">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5793">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5794">optional #GCancellable object, %NULL to ignore @@ -47429,8 +50168,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5796">a #GAsyncReadyCallback to call when the request is satisfied @@ -47439,8 +50178,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="5798">the data to pass to callback function @@ -47451,40 +50190,41 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. deprecated-version="2.22" throws="1"> Finishes an asynchronous eject operation started by + filename="gio/gfile.c" + line="5840">Finishes an asynchronous eject operation started by g_file_eject_mountable(). Use g_file_eject_mountable_with_operation_finish() instead. - + %TRUE if the @file was ejected successfully. + filename="gio/gfile.c" + line="5849">%TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5842">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5843">a #GAsyncResult + version="2.22" + glib:finish-func="eject_mountable_with_operation_finish"> Starts an asynchronous eject on a mountable. + filename="gio/gfile.c" + line="5874">Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_eject_mountable_with_operation_finish(). @@ -47492,21 +50232,21 @@ g_file_eject_mountable_with_operation_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + input #GFile + filename="gio/gfile.c" + line="5876">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5877">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5878">a #GMountOperation, or %NULL to avoid user interaction @@ -47524,8 +50264,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5880">optional #GCancellable object, %NULL to ignore @@ -47536,8 +50276,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5882">a #GAsyncReadyCallback to call when the request is satisfied @@ -47546,8 +50286,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="5884">the data to pass to callback function @@ -47557,38 +50297,39 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.22" throws="1"> Finishes an asynchronous eject operation started by + filename="gio/gfile.c" + line="5935">Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation(). - + %TRUE if the @file was ejected successfully. + filename="gio/gfile.c" + line="5944">%TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5937">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5938">a #GAsyncResult + throws="1" + glib:async-func="enumerate_children_async"> Gets the requested information about the files in a directory. + filename="gio/gfile.c" + line="1047">Gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. @@ -47613,31 +50354,31 @@ returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY error will be returned. Other errors are possible too. - + A #GFileEnumerator if successful, + filename="gio/gfile.c" + line="1082">A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1049">input #GFile an attribute query string + filename="gio/gfile.c" + line="1050">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1051">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1052">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_enumerate_children_async" + glib:finish-func="enumerate_children_finish" + glib:sync-func="enumerate_children"> Asynchronously gets the requested information about the files + filename="gio/gfile.c" + line="1113">Asynchronously gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. @@ -47666,33 +50409,33 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_enumerate_children_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="1115">input #GFile an attribute query string + filename="gio/gfile.c" + line="1116">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1117">a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1118">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1119">optional #GCancellable object, %NULL to ignore @@ -47712,8 +50455,8 @@ the operation. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1121">a #GAsyncReadyCallback to call when the request is satisfied @@ -47722,8 +50465,8 @@ the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="1123">the data to pass to callback function @@ -47732,14 +50475,14 @@ the operation. c:identifier="g_file_enumerate_children_finish" throws="1"> Finishes an async enumerate children operation. + filename="gio/gfile.c" + line="1159">Finishes an async enumerate children operation. See g_file_enumerate_children_async(). - + a #GFileEnumerator or %NULL + filename="gio/gfile.c" + line="1168">a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). @@ -47747,56 +50490,57 @@ See g_file_enumerate_children_async(). input #GFile + filename="gio/gfile.c" + line="1161">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1162">a #GAsyncResult Checks if the two given #GFiles refer to the same file. + filename="gio/gfile.c" + line="779">Checks if the two given #GFiles refer to the same file. Note that two #GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. This call does no blocking I/O. - + %TRUE if @file1 and @file2 are equal. + filename="gio/gfile.c" + line="792">%TRUE if @file1 and @file2 are equal. the first #GFile + filename="gio/gfile.c" + line="781">the first #GFile the second #GFile + filename="gio/gfile.c" + line="782">the second #GFile + throws="1" + glib:async-func="find_enclosing_mount_async"> Gets a #GMount for the #GFile. + filename="gio/gfile.c" + line="1571">Gets a #GMount for the #GFile. #GMount is returned only for user interesting locations, see #GVolumeMonitor. If the #GFileIface for @file does not have a #mount, @@ -47805,11 +50549,11 @@ This call does no blocking I/O. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GMount where the @file is located + filename="gio/gfile.c" + line="1588">a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). @@ -47817,8 +50561,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="1573">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1574">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_find_enclosing_mount_async" + glib:finish-func="find_enclosing_mount_finish" + glib:sync-func="find_enclosing_mount"> Asynchronously gets the mount for the file. + filename="gio/gfile.c" + line="1620">Asynchronously gets the mount for the file. For more details, see g_file_find_enclosing_mount() which is the synchronous version of this call. @@ -47845,21 +50591,21 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_find_enclosing_mount_finish() to get the result of the operation. - + a #GFile + filename="gio/gfile.c" + line="1622">a #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1623">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1624">optional #GCancellable object, %NULL to ignore @@ -47879,8 +50625,8 @@ get the result of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1626">a #GAsyncReadyCallback to call when the request is satisfied @@ -47889,8 +50635,8 @@ get the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="1628">the data to pass to callback function @@ -47899,36 +50645,36 @@ get the result of the operation. c:identifier="g_file_find_enclosing_mount_finish" throws="1"> Finishes an asynchronous find mount request. + filename="gio/gfile.c" + line="1658">Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async(). - + #GMount for given @file or %NULL on error. + filename="gio/gfile.c" + line="1667">#GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). a #GFile + filename="gio/gfile.c" + line="1660">a #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1661">a #GAsyncResult Gets the base name (the last component of the path) for a given #GFile. + filename="gio/gfile.c" + line="536">Gets the base name (the last component of the path) for a given #GFile. If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator @@ -47941,11 +50687,11 @@ can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). This call does no blocking I/O. - + string containing the #GFile's + filename="gio/gfile.c" + line="554">string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. @@ -47953,41 +50699,41 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="538">input #GFile Gets a child of @file with basename equal to @name. + filename="gio/gfile.c" + line="884">Gets a child of @file with basename equal to @name. Note that the file with that specific name might not exist, but you can still have a #GFile that points to it. You can use this for instance to create that file. This call does no blocking I/O. - + a #GFile to a child specified by @name. + filename="gio/gfile.c" + line="897">a #GFile to a child specified by @name. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="886">input #GFile string containing the child's basename + filename="gio/gfile.c" + line="887">string containing the child's basename @@ -47996,8 +50742,8 @@ This call does no blocking I/O. c:identifier="g_file_get_child_for_display_name" throws="1"> Gets the child of @file for a given @display_name (i.e. a UTF-8 + filename="gio/gfile.c" + line="911">Gets the child of @file for a given @display_name (i.e. a UTF-8 version of the name). If this function fails, it returns %NULL and @error will be set. This is very useful when constructing a #GFile for a new file and the user entered the filename in the @@ -48005,11 +50751,11 @@ user interface, for instance when you select a directory and type a filename in the file selector. This call does no blocking I/O. - + a #GFile to the specified child, or + filename="gio/gfile.c" + line="926">a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). @@ -48017,31 +50763,31 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="913">input #GFile string to a possible child + filename="gio/gfile.c" + line="914">string to a possible child Gets the parent directory for the @file. + filename="gio/gfile.c" + line="815">Gets the parent directory for the @file. If the @file represents the root directory of the file system, then %NULL will be returned. This call does no blocking I/O. - + a #GFile structure to the + filename="gio/gfile.c" + line="825">a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). @@ -48049,16 +50795,16 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="817">input #GFile Gets the parse name of the @file. + filename="gio/gfile.c" + line="689">Gets the parse name of the @file. A parse name is a UTF-8 string that describes the file such that one can get the #GFile back using g_file_parse_name(). @@ -48072,11 +50818,11 @@ to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped). This call does no blocking I/O. - + a string containing the #GFile's parse name. + filename="gio/gfile.c" + line="708">a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. @@ -48084,24 +50830,24 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="691">input #GFile Gets the local pathname for #GFile, if one exists. If non-%NULL, this is + filename="gio/gfile.c" + line="570">Gets the local pathname for #GFile, if one exists. If non-%NULL, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O. - + string containing the #GFile's path, + filename="gio/gfile.c" + line="579">string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. @@ -48109,23 +50855,23 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="572">input #GFile Gets the path for @descendant relative to @parent. + filename="gio/gfile.c" + line="988">Gets the path for @descendant relative to @parent. This call does no blocking I/O. - + string with the relative path from + filename="gio/gfile.c" + line="997">string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. @@ -48134,29 +50880,29 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="990">input #GFile input #GFile + filename="gio/gfile.c" + line="991">input #GFile Gets the URI for the @file. + filename="gio/gfile.c" + line="664">Gets the URI for the @file. This call does no blocking I/O. - + a string containing the #GFile's URI. If the #GFile was constructed + filename="gio/gfile.c" + line="672">a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. @@ -48165,16 +50911,16 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="666">input #GFile Gets the URI scheme for a #GFile. + filename="gio/gfile.c" + line="503">Gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] @@ -48185,11 +50931,11 @@ The scheme can be different from the one used to construct the #GFile, in that it might be replaced with one that is logically equivalent to the #GFile. This call does no blocking I/O. - + a string containing the URI scheme for the given + filename="gio/gfile.c" + line="519">a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. @@ -48197,8 +50943,8 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="505">input #GFile @@ -48207,25 +50953,25 @@ This call does no blocking I/O. c:identifier="g_file_has_parent" version="2.24"> Checks if @file has a parent, and optionally, if it is @parent. + filename="gio/gfile.c" + line="841">Checks if @file has a parent, and optionally, if it is @parent. If @parent is %NULL then this function returns %TRUE if @file has any parent at all. If @parent is non-%NULL then %TRUE is only returned if @file is an immediate child of @parent. - + %TRUE if @file is an immediate child of @parent (or any parent in + filename="gio/gfile.c" + line="852">%TRUE if @file is an immediate child of @parent (or any parent in the case that @parent is %NULL). input #GFile + filename="gio/gfile.c" + line="843">input #GFile nullable="1" allow-none="1"> the parent to check for, or %NULL + filename="gio/gfile.c" + line="844">the parent to check for, or %NULL Checks whether @file has the prefix specified by @prefix. + filename="gio/gfile.c" + line="945">Checks whether @file has the prefix specified by @prefix. In other words, if the names of initial elements of @file's pathname match @prefix. Only full pathname elements are matched, @@ -48256,40 +51002,40 @@ This call does no I/O, as it works purely on names. As such it can sometimes return %FALSE even if @file is inside a @prefix (from a filesystem point of view), because the prefix of @file is an alias of @prefix. - + %TRUE if the @file's parent, grandparent, etc is @prefix, + filename="gio/gfile.c" + line="965">%TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="947">input #GFile input #GFile + filename="gio/gfile.c" + line="948">input #GFile Checks to see if a #GFile has a given URI scheme. + filename="gio/gfile.c" + line="475">Checks to see if a #GFile has a given URI scheme. This call does no blocking I/O. - + %TRUE if #GFile's backend supports the + filename="gio/gfile.c" + line="484">%TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. @@ -48297,29 +51043,29 @@ This call does no blocking I/O. input #GFile + filename="gio/gfile.c" + line="477">input #GFile a string containing a URI scheme + filename="gio/gfile.c" + line="478">a string containing a URI scheme Creates a hash value for a #GFile. + filename="gio/gfile.c" + line="754">Creates a hash value for a #GFile. This call does no blocking I/O. - + 0 if @file is not a valid #GFile, otherwise an + filename="gio/gfile.c" + line="762">0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. @@ -48328,16 +51074,16 @@ This call does no blocking I/O. #gconstpointer to a #GFile + filename="gio/gfile.c" + line="756">#gconstpointer to a #GFile Checks to see if a file is native to the platform. + filename="gio/gfile.c" + line="444">Checks to see if a file is native to the platform. A native file is one expressed in the platform-native filename format, e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, @@ -48348,18 +51094,18 @@ filesystem via a userspace filesystem (FUSE), in these cases this call will return %FALSE, but g_file_get_path() will still return a native path. This call does no blocking I/O. - + %TRUE if @file is native + filename="gio/gfile.c" + line="460">%TRUE if @file is native input #GFile + filename="gio/gfile.c" + line="446">input #GFile @@ -48367,10 +51113,11 @@ This call does no blocking I/O. + throws="1" + glib:async-func="load_bytes_async"> Loads the contents of @file and returns it as #GBytes. + filename="gio/gfile.c" + line="9435">Loads the contents of @file and returns it as #GBytes. If @file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling @@ -48381,18 +51128,18 @@ For resources, @etag_out will be set to %NULL. The data contained in the resulting #GBytes is always zero-terminated, but this is not included in the #GBytes length. The resulting #GBytes should be freed with g_bytes_unref() when no longer in use. - + a #GBytes or %NULL and @error is set + filename="gio/gfile.c" + line="9455">a #GBytes or %NULL and @error is set a #GFile + filename="gio/gfile.c" + line="9437">a #GFile nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gfile.c" + line="9438">a #GCancellable or %NULL optional="1" allow-none="1"> a location to place the current + filename="gio/gfile.c" + line="9439">a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -48421,10 +51168,12 @@ freed with g_bytes_unref() when no longer in use. + version="2.56" + glib:finish-func="load_bytes_finish" + glib:sync-func="load_bytes"> Asynchronously loads the contents of @file as #GBytes. + filename="gio/gfile.c" + line="9522">Asynchronously loads the contents of @file as #GBytes. If @file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling @@ -48434,15 +51183,15 @@ g_file_load_contents_async() and g_bytes_new_take(). asynchronous operation. See g_file_load_bytes() for more information. - + a #GFile + filename="gio/gfile.c" + line="9524">a #GFile nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gfile.c" + line="9525">a #GCancellable or %NULL scope="async" closure="2"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="9526">a #GAsyncReadyCallback to call when the request is satisfied @@ -48471,8 +51220,8 @@ See g_file_load_bytes() for more information. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="9528">the data to pass to callback function @@ -48482,8 +51231,8 @@ See g_file_load_bytes() for more information. version="2.56" throws="1"> Completes an asynchronous request to g_file_load_bytes_async(). + filename="gio/gfile.c" + line="9580">Completes an asynchronous request to g_file_load_bytes_async(). For resources, @etag_out will be set to %NULL. @@ -48492,24 +51241,24 @@ this is not included in the #GBytes length. The resulting #GBytes should be freed with g_bytes_unref() when no longer in use. See g_file_load_bytes() for more information. - + a #GBytes or %NULL and @error is set + filename="gio/gfile.c" + line="9598">a #GBytes or %NULL and @error is set a #GFile + filename="gio/gfile.c" + line="9582">a #GFile a #GAsyncResult provided to the callback + filename="gio/gfile.c" + line="9583">a #GAsyncResult provided to the callback optional="1" allow-none="1"> a location to place the current + filename="gio/gfile.c" + line="9584">a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -48529,10 +51278,11 @@ See g_file_load_bytes() for more information. + throws="1" + glib:async-func="load_contents_async"> Loads the content of the file into memory. The data is always + filename="gio/gfile.c" + line="8069">Loads the content of the file into memory. The data is always zero-terminated, but this is not included in the resultant @length. The returned @contents should be freed with g_free() when no longer needed. @@ -48540,19 +51290,19 @@ needed. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @file's contents were successfully loaded. + filename="gio/gfile.c" + line="8089">%TRUE if the @file's contents were successfully loaded. %FALSE if there were errors. input #GFile + filename="gio/gfile.c" + line="8071">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="8072">optional #GCancellable object, %NULL to ignore caller-allocates="0" transfer-ownership="full"> a location to place the contents of the file + filename="gio/gfile.c" + line="8073">a location to place the contents of the file @@ -48582,8 +51332,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. optional="1" allow-none="1"> a location to place the length of the contents of the file, + filename="gio/gfile.c" + line="8074">a location to place the length of the contents of the file, or %NULL if the length is not needed @@ -48595,18 +51345,20 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. optional="1" allow-none="1"> a location to place the current entity tag for the file, + filename="gio/gfile.c" + line="8076">a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + c:identifier="g_file_load_contents_async" + glib:finish-func="load_contents_finish" + glib:sync-func="load_contents"> Starts an asynchronous load of the @file's contents. + filename="gio/gfile.c" + line="8445">Starts an asynchronous load of the @file's contents. For more details, see g_file_load_contents() which is the synchronous version of this call. @@ -48619,15 +51371,15 @@ the @callback. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + input #GFile + filename="gio/gfile.c" + line="8447">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="8448">optional #GCancellable object, %NULL to ignore scope="async" closure="2"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gfile.c" + line="8449">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="8450">the data to pass to callback function @@ -48665,31 +51417,31 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_load_contents_finish" throws="1"> Finishes an asynchronous load of the @file's contents. + filename="gio/gfile.c" + line="8478">Finishes an asynchronous load of the @file's contents. The contents are placed in @contents, and @length is set to the size of the @contents string. The @contents should be freed with g_free() when no longer needed. If @etag_out is present, it will be set to the new entity tag for the @file. - + %TRUE if the load was successful. If %FALSE and @error is + filename="gio/gfile.c" + line="8495">%TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. input #GFile + filename="gio/gfile.c" + line="8480">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="8481">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> a location to place the contents of the file + filename="gio/gfile.c" + line="8482">a location to place the contents of the file @@ -48710,8 +51462,8 @@ set to the new entity tag for the @file. optional="1" allow-none="1"> a location to place the length of the contents of the file, + filename="gio/gfile.c" + line="8483">a location to place the length of the contents of the file, or %NULL if the length is not needed @@ -48723,8 +51475,8 @@ set to the new entity tag for the @file. optional="1" allow-none="1"> a location to place the current entity tag for the file, + filename="gio/gfile.c" + line="8485">a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -48732,10 +51484,11 @@ set to the new entity tag for the @file. + introspectable="0" + glib:finish-func="load_partial_contents_finish"> Reads the partial contents of a file. A #GFileReadMoreCallback should + filename="gio/gfile.c" + line="8333">Reads the partial contents of a file. A #GFileReadMoreCallback should be used to stop reading from the file when appropriate, else this function will behave exactly as g_file_load_contents_async(). This operation can be finished by g_file_load_partial_contents_finish(). @@ -48746,15 +51499,15 @@ both the @read_more_callback and the @callback. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + input #GFile + filename="gio/gfile.c" + line="8335">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="8336">optional #GCancellable object, %NULL to ignore scope="call" closure="3"> a + filename="gio/gfile.c" + line="8337">a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read @@ -48784,8 +51537,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="8340">a #GAsyncReadyCallback to call when the request is satisfied @@ -48794,8 +51547,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> the data to pass to the callback functions + filename="gio/gfile.c" + line="8342">the data to pass to the callback functions @@ -48804,31 +51557,31 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_load_partial_contents_finish" throws="1"> Finishes an asynchronous partial load operation that was started + filename="gio/gfile.c" + line="8381">Finishes an asynchronous partial load operation that was started with g_file_load_partial_contents_async(). The data is always zero-terminated, but this is not included in the resultant @length. The returned @contents should be freed with g_free() when no longer needed. - + %TRUE if the load was successful. If %FALSE and @error is + filename="gio/gfile.c" + line="8398">%TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. input #GFile + filename="gio/gfile.c" + line="8383">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="8384">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> a location to place the contents of the file + filename="gio/gfile.c" + line="8385">a location to place the contents of the file @@ -48849,8 +51602,8 @@ needed. optional="1" allow-none="1"> a location to place the length of the contents of the file, + filename="gio/gfile.c" + line="8386">a location to place the length of the contents of the file, or %NULL if the length is not needed @@ -48862,8 +51615,8 @@ needed. optional="1" allow-none="1"> a location to place the current entity tag for the file, + filename="gio/gfile.c" + line="8388">a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -48871,10 +51624,11 @@ needed. + throws="1" + glib:async-func="make_directory_async"> Creates a directory. Note that this will only create a child directory + filename="gio/gfile.c" + line="4228">Creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the #GFile. To recursively create directories, see g_file_make_directory_with_parents(). This function will fail if the parent directory does not exist, setting @@ -48888,18 +51642,18 @@ For a local #GFile the newly created directory will have the default If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on successful creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4250">%TRUE on successful creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4230">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4231">optional #GCancellable object, %NULL to ignore @@ -48916,25 +51670,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.38" + glib:finish-func="make_directory_finish" + glib:sync-func="make_directory"> Asynchronously creates a directory. - + filename="gio/gfile.c" + line="4277">Asynchronously creates a directory. + input #GFile + filename="gio/gfile.c" + line="4279">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4280">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4281">optional #GCancellable object, %NULL to ignore @@ -48954,8 +51710,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4283">a #GAsyncReadyCallback to call when the request is satisfied @@ -48964,8 +51720,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="4285">the data to pass to callback function @@ -48975,27 +51731,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.38" throws="1"> Finishes an asynchronous directory creation, started with + filename="gio/gfile.c" + line="4310">Finishes an asynchronous directory creation, started with g_file_make_directory_async(). - + %TRUE on successful directory creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4319">%TRUE on successful directory creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4312">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4313">a #GAsyncResult @@ -49005,8 +51761,8 @@ g_file_make_directory_async(). version="2.18" throws="1"> Creates a directory and any parent directories that may not + filename="gio/gfile.c" + line="4336">Creates a directory and any parent directories that may not exist similar to 'mkdir -p'. If the file system does not support creating directories, this function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, @@ -49019,19 +51775,19 @@ For a local #GFile the newly created directories will have the default If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if all directories have been successfully created, %FALSE + filename="gio/gfile.c" + line="4357">%TRUE if all directories have been successfully created, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4338">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4339">optional #GCancellable object, %NULL to ignore @@ -49048,33 +51804,34 @@ otherwise. + throws="1" + glib:async-func="make_symbolic_link_async"> Creates a symbolic link named @file which contains the string + filename="gio/gfile.c" + line="4458">Creates a symbolic link named @file which contains the string @symlink_value. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on the creation of a new symlink, %FALSE otherwise. + filename="gio/gfile.c" + line="4474">%TRUE on the creation of a new symlink, %FALSE otherwise. a #GFile with the name of the symlink to create + filename="gio/gfile.c" + line="4460">a #GFile with the name of the symlink to create a string with the path for the target + filename="gio/gfile.c" + line="4461">a string with the path for the target of the new symlink @@ -49083,8 +51840,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4463">optional #GCancellable object, %NULL to ignore @@ -49092,33 +51849,35 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.74" + glib:finish-func="make_symbolic_link_finish" + glib:sync-func="make_symbolic_link"> Asynchronously creates a symbolic link named @file which contains the + filename="gio/gfile.c" + line="4549">Asynchronously creates a symbolic link named @file which contains the string @symlink_value. - + a #GFile with the name of the symlink to create + filename="gio/gfile.c" + line="4551">a #GFile with the name of the symlink to create a string with the path for the target + filename="gio/gfile.c" + line="4552">a string with the path for the target of the new symlink the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4554">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4555">optional #GCancellable object, %NULL to ignore @@ -49138,8 +51897,8 @@ string @symlink_value. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4557">a #GAsyncReadyCallback to call when the request is satisfied @@ -49148,8 +51907,8 @@ string @symlink_value. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="4559">the data to pass to callback function @@ -49159,27 +51918,27 @@ string @symlink_value. version="2.74" throws="1"> Finishes an asynchronous symbolic link creation, started with + filename="gio/gfile.c" + line="4599">Finishes an asynchronous symbolic link creation, started with g_file_make_symbolic_link_async(). - + %TRUE on successful directory creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4608">%TRUE on successful directory creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4601">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4602">a #GAsyncResult @@ -49187,11 +51946,11 @@ g_file_make_symbolic_link_async(). + throws="1" + glib:async-func="measure_disk_usage_async"> Recursively measures the disk usage of @file. + filename="gio/gfile.c" + line="9025">Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered @@ -49209,25 +51968,25 @@ in a user interface. periodic progress updates while scanning. See the documentation for #GFileMeasureProgressCallback for information about when and how the callback will be invoked. - + %TRUE if successful, with the out parameters set. + filename="gio/gfile.c" + line="9056">%TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile + filename="gio/gfile.c" + line="9027">a #GFile #GFileMeasureFlags + filename="gio/gfile.c" + line="9028">#GFileMeasureFlags nullable="1" allow-none="1"> optional #GCancellable + filename="gio/gfile.c" + line="9029">optional #GCancellable a #GFileMeasureProgressCallback + filename="gio/gfile.c" + line="9030">a #GFileMeasureProgressCallback @@ -49255,8 +52015,8 @@ callback will be invoked. nullable="1" allow-none="1"> user_data for @progress_callback + filename="gio/gfile.c" + line="9031">user_data for @progress_callback optional="1" allow-none="1"> the number of bytes of disk space used + filename="gio/gfile.c" + line="9032">the number of bytes of disk space used optional="1" allow-none="1"> the number of directories encountered + filename="gio/gfile.c" + line="9033">the number of directories encountered optional="1" allow-none="1"> the number of non-directories encountered + filename="gio/gfile.c" + line="9034">the number of non-directories encountered @@ -49297,34 +52057,36 @@ callback will be invoked. + introspectable="0" + glib:finish-func="measure_disk_usage_finish" + glib:sync-func="measure_disk_usage"> Recursively measures the disk usage of @file. + filename="gio/gfile.c" + line="9082">Recursively measures the disk usage of @file. This is the asynchronous version of g_file_measure_disk_usage(). See there for more information. - + a #GFile + filename="gio/gfile.c" + line="9084">a #GFile #GFileMeasureFlags + filename="gio/gfile.c" + line="9085">#GFileMeasureFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="9086">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable + filename="gio/gfile.c" + line="9087">optional #GCancellable allow-none="1" closure="4"> a #GFileMeasureProgressCallback + filename="gio/gfile.c" + line="9088">a #GFileMeasureProgressCallback @@ -49352,8 +52114,8 @@ there for more information. nullable="1" allow-none="1"> user_data for @progress_callback + filename="gio/gfile.c" + line="9089">user_data for @progress_callback scope="async" closure="6"> a #GAsyncReadyCallback to call when complete + filename="gio/gfile.c" + line="9090">a #GAsyncReadyCallback to call when complete nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="9091">the data to pass to callback function @@ -49383,29 +52145,29 @@ there for more information. version="2.38" throws="1"> Collects the results from an earlier call to + filename="gio/gfile.c" + line="9118">Collects the results from an earlier call to g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for more information. - + %TRUE if successful, with the out parameters set. + filename="gio/gfile.c" + line="9131">%TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile + filename="gio/gfile.c" + line="9120">a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback + filename="gio/gfile.c" + line="9121">the #GAsyncResult passed to your #GAsyncReadyCallback optional="1" allow-none="1"> the number of bytes of disk space used + filename="gio/gfile.c" + line="9122">the number of bytes of disk space used optional="1" allow-none="1"> the number of directories encountered + filename="gio/gfile.c" + line="9123">the number of directories encountered optional="1" allow-none="1"> the number of non-directories encountered + filename="gio/gfile.c" + line="9124">the number of non-directories encountered @@ -49448,18 +52210,18 @@ more information. version="2.18" throws="1"> Obtains a file or directory monitor for the given file, + filename="gio/gfile.c" + line="6077">Obtains a file or directory monitor for the given file, depending on the type of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFileMonitor for the given @file, + filename="gio/gfile.c" + line="6092">a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). @@ -49467,14 +52229,14 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="6079">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="6080">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="6081">optional #GCancellable object, %NULL to ignore @@ -49493,8 +52255,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_monitor_directory" throws="1"> Obtains a directory monitor for the given file. + filename="gio/gfile.c" + line="5971">Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported. If @cancellable is not %NULL, then the operation can be cancelled by @@ -49506,26 +52268,25 @@ It does not make sense for @flags to contain directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor(). - + a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). + filename="gio/gfile.c" + line="5992">a #GFileMonitor for the given @file, + or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="5973">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="5974">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5975">optional #GCancellable object, %NULL to ignore @@ -49544,8 +52305,8 @@ you must register individual watches with g_file_monitor(). c:identifier="g_file_monitor_file" throws="1"> Obtains a file monitor for the given file. If no file notification + filename="gio/gfile.c" + line="6022">Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used. If @cancellable is not %NULL, then the operation can be cancelled by @@ -49559,11 +52320,11 @@ changes made through the filename contained in @file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the #GFileMonitor backend and/or filesystem type. - + a #GFileMonitor for the given @file, + filename="gio/gfile.c" + line="6045">a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). @@ -49571,14 +52332,14 @@ backend and/or filesystem type. input #GFile + filename="gio/gfile.c" + line="6024">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="6025">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="6026">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_mount_enclosing_volume" + glib:finish-func="mount_enclosing_volume_finish"> Starts a @mount_operation, mounting the volume that contains + filename="gio/gfile.c" + line="7726">Starts a @mount_operation, mounting the volume that contains the file @location. When this operation has completed, @callback will be called with @@ -49607,21 +52369,21 @@ g_file_mount_enclosing_volume_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + input #GFile + filename="gio/gfile.c" + line="7728">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="7729">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation + filename="gio/gfile.c" + line="7730">a #GMountOperation or %NULL to avoid user interaction @@ -49639,8 +52401,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="7732">optional #GCancellable object, %NULL to ignore @@ -49651,8 +52413,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="7734">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -49661,8 +52423,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="7736">the data to pass to callback function @@ -49671,13 +52433,13 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_mount_enclosing_volume_finish" throws="1"> Finishes a mount operation started by g_file_mount_enclosing_volume(). - + filename="gio/gfile.c" + line="7776">Finishes a mount operation started by g_file_mount_enclosing_volume(). + %TRUE if successful. If an error has occurred, + filename="gio/gfile.c" + line="7784">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -49685,22 +52447,24 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="7778">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="7779">a #GAsyncResult - + Mounts a file of type G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="5514">Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using @mount_operation, you can request callbacks when, for instance, passwords are needed during authentication. @@ -49711,21 +52475,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="5516">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5517">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5518">a #GMountOperation, or %NULL to avoid user interaction @@ -49743,8 +52507,8 @@ the result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5520">optional #GCancellable object, %NULL to ignore @@ -49755,8 +52519,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5522">a #GAsyncReadyCallback to call when the request is satisfied @@ -49765,8 +52529,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="5524">the data to pass to callback function @@ -49775,38 +52539,41 @@ the result of the operation. c:identifier="g_file_mount_mountable_finish" throws="1"> Finishes a mount operation. See g_file_mount_mountable() for details. + filename="gio/gfile.c" + line="5569">Finishes a mount operation. See g_file_mount_mountable() for details. Finish an asynchronous mount operation that was started with g_file_mount_mountable(). - + a #GFile or %NULL on error. + filename="gio/gfile.c" + line="5580">a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="5571">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5572">a #GAsyncResult - + Tries to move the file or directory @source to the location specified + filename="gio/gfile.c" + line="3974">Tries to move the file or directory @source to the location specified by @destination. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves @@ -49839,30 +52606,30 @@ If the source is a directory and the target does not exist, or %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native move operation isn't available). - + %TRUE on successful move, %FALSE otherwise. + filename="gio/gfile.c" + line="4021">%TRUE on successful move, %FALSE otherwise. #GFile pointing to the source location + filename="gio/gfile.c" + line="3976">#GFile pointing to the source location #GFile pointing to the destination location + filename="gio/gfile.c" + line="3977">#GFile pointing to the destination location set of #GFileCopyFlags + filename="gio/gfile.c" + line="3978">set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3979">optional #GCancellable object, %NULL to ignore @@ -49882,8 +52649,8 @@ move operation isn't available). scope="call" closure="4"> #GFileProgressCallback + filename="gio/gfile.c" + line="3981">#GFileProgressCallback function for updates @@ -49892,8 +52659,8 @@ move operation isn't available). nullable="1" allow-none="1"> gpointer to user data for + filename="gio/gfile.c" + line="3983">gpointer to user data for the callback function @@ -49901,10 +52668,13 @@ move operation isn't available). + shadowed-by="move_async_with_closures" + version="2.72" + glib:finish-func="move_finish" + glib:sync-func="move"> Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). + filename="gio/gfile.c" + line="4108">Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_move(). The callback will run in the default main context @@ -49913,33 +52683,33 @@ run in. When the operation is finished, @callback will be called. You can then call g_file_move_finish() to get the result of the operation. - + #GFile pointing to the source location + filename="gio/gfile.c" + line="4110">#GFile pointing to the source location #GFile pointing to the destination location + filename="gio/gfile.c" + line="4111">#GFile pointing to the destination location set of #GFileCopyFlags + filename="gio/gfile.c" + line="4112">set of #GFileCopyFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4113">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4114">optional #GCancellable object, %NULL to ignore @@ -49959,8 +52729,8 @@ g_file_move_finish() to get the result of the operation. scope="call" closure="5"> + filename="gio/gfile.c" + line="4116"> #GFileProgressCallback function for updates @@ -49969,8 +52739,8 @@ g_file_move_finish() to get the result of the operation. nullable="1" allow-none="1"> gpointer to user data for the callback function + filename="gio/gfile.c" + line="4118">gpointer to user data for the callback function scope="async" closure="7"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="4119">a #GAsyncReadyCallback to call when the request is satisfied @@ -49990,38 +52760,104 @@ g_file_move_finish() to get the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="4121">the data to pass to callback function + + Version of [method@Gio.File.move_async] using closures instead of callbacks for +easier binding in other languages. + + + + + + + input [type@Gio.File] + + + + destination [type@Gio.File] + + + + set of [flags@Gio.FileCopyFlags] + + + + the [I/O priority](iface.AsyncResult.html#io-priority) of the request + + + + optional [class@Gio.Cancellable] object, + `NULL` to ignore + + + + [type@GObject.Closure] to invoke with progress + information, or `NULL` if progress information is not needed + + + + [type@GObject.Closure] to invoke when the request is satisfied + + + + Finishes an asynchronous file movement, started with + filename="gio/gfile.c" + line="4200">Finishes an asynchronous file movement, started with g_file_move_async(). - + %TRUE on successful file move, %FALSE otherwise. + filename="gio/gfile.c" + line="4209">%TRUE on successful file move, %FALSE otherwise. input source #GFile + filename="gio/gfile.c" + line="4202">input source #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4203">a #GAsyncResult @@ -50029,10 +52865,11 @@ g_file_move_async(). + throws="1" + glib:async-func="open_readwrite_async"> Opens an existing file for reading and writing. The result is + filename="gio/gfile.c" + line="1935">Opens an existing file for reading and writing. The result is a #GFileIOStream that can be used to read and write the contents of the file. @@ -50048,19 +52885,19 @@ what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. - + #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="1958">#GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to open + filename="gio/gfile.c" + line="1937">#GFile to open nullable="1" allow-none="1"> a #GCancellable + filename="gio/gfile.c" + line="1938">a #GCancellable + version="2.22" + glib:finish-func="open_readwrite_finish" + glib:sync-func="open_readwrite"> Asynchronously opens @file for reading and writing. + filename="gio/gfile.c" + line="2394">Asynchronously opens @file for reading and writing. For more details, see g_file_open_readwrite() which is the synchronous version of this call. @@ -50087,21 +52926,21 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_open_readwrite_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2396">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2397">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2398">optional #GCancellable object, %NULL to ignore @@ -50121,8 +52960,8 @@ the result of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2400">a #GAsyncReadyCallback to call when the request is satisfied @@ -50131,8 +52970,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2402">the data to pass to callback function @@ -50142,65 +52981,66 @@ the result of the operation. version="2.22" throws="1"> Finishes an asynchronous file read operation started with + filename="gio/gfile.c" + line="2434">Finishes an asynchronous file read operation started with g_file_open_readwrite_async(). - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2443">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2436">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2437">a #GAsyncResult Exactly like g_file_get_path(), but caches the result via + filename="gio/gfile.c" + line="640">Exactly like g_file_get_path(), but caches the result via g_object_set_qdata_full(). This is useful for example in C applications which mix `g_file_*` APIs with native ones. It also avoids an extra duplicated string when possible, so will be generally more efficient. This call does no blocking I/O. - + string containing the #GFile's path, + filename="gio/gfile.c" + line="652">string containing the #GFile's path, or %NULL if no such path exists. The returned string is owned by @file. input #GFile + filename="gio/gfile.c" + line="642">input #GFile + version="2.22" + glib:finish-func="poll_mountable_finish"> Polls a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="9329">Polls a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -50209,15 +53049,15 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="9331">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="9332">optional #GCancellable object, %NULL to ignore scope="async" closure="2"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="9333">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -50246,8 +53086,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="9335">the data to pass to callback function @@ -50257,50 +53097,51 @@ the result of the operation. version="2.22" throws="1"> Finishes a poll operation. See g_file_poll_mountable() for details. + filename="gio/gfile.c" + line="9376">Finishes a poll operation. See g_file_poll_mountable() for details. Finish an asynchronous poll operation that was polled with g_file_poll_mountable(). - + %TRUE if the operation finished successfully. %FALSE + filename="gio/gfile.c" + line="9387">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9378">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9379">a #GAsyncResult + throws="1" + glib:async-func="query_default_handler_async"> Returns the #GAppInfo that is registered as the default + filename="gio/gfile.c" + line="7812">Returns the #GAppInfo that is registered as the default application to handle the file specified by @file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GAppInfo if the handle was found, + filename="gio/gfile.c" + line="7825">a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() @@ -50308,8 +53149,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFile to open + filename="gio/gfile.c" + line="7814">a #GFile to open nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="7815">optional #GCancellable object, %NULL to ignore + version="2.60" + glib:finish-func="query_default_handler_finish" + glib:sync-func="query_default_handler"> Async version of g_file_query_default_handler(). - + filename="gio/gfile.c" + line="7994">Async version of g_file_query_default_handler(). + a #GFile to open + filename="gio/gfile.c" + line="7996">a #GFile to open the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="7997">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="7998">optional #GCancellable object, %NULL to ignore scope="async" closure="3"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gfile.c" + line="7999">a #GAsyncReadyCallback to call when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gfile.c" + line="8000">data to pass to @callback @@ -50382,13 +53225,13 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.60" throws="1"> Finishes a g_file_query_default_handler_async() operation. - + filename="gio/gfile.c" + line="8042">Finishes a g_file_query_default_handler_async() operation. + a #GAppInfo if the handle was found, + filename="gio/gfile.c" + line="8050">a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() @@ -50396,23 +53239,26 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GFile to open + filename="gio/gfile.c" + line="8044">a #GFile to open a #GAsyncResult + filename="gio/gfile.c" + line="8045">a #GAsyncResult Utility function to check if a particular file exists. This is -implemented using g_file_query_info() and as such does blocking I/O. + filename="gio/gfile.c" + line="1189">Utility function to check if a particular file exists. + +The fallback implementation of this API is using [method@Gio.File.query_info] +and therefore may do blocking I/O. To asynchronously query the existence +of a file, use [method@Gio.File.query_info_async]. Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) and then execute something based on the outcome of that, because the @@ -50433,19 +53279,19 @@ for instance to make a menu item sensitive/insensitive, so that you don't have to fool users that something is possible and then just show an error dialog. If you do this, you should make sure to also handle the errors that can happen due to races when you execute the operation. - + %TRUE if the file exists (and can be detected without error), + filename="gio/gfile.c" + line="1221">%TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). input #GFile + filename="gio/gfile.c" + line="1191">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1192">optional #GCancellable object, %NULL to ignore @@ -50464,31 +53310,31 @@ that can happen due to races when you execute the operation. c:identifier="g_file_query_file_type" version="2.18"> Utility function to inspect the #GFileType of a file. This is + filename="gio/gfile.c" + line="1249">Utility function to inspect the #GFileType of a file. This is implemented using g_file_query_info() and as such does blocking I/O. The primary use case of this method is to check if a file is a regular file, directory, or symlink. - + The #GFileType of the file and %G_FILE_TYPE_UNKNOWN + filename="gio/gfile.c" + line="1262">The #GFileType of the file and %G_FILE_TYPE_UNKNOWN if the file does not exist input #GFile + filename="gio/gfile.c" + line="1251">input #GFile a set of #GFileQueryInfoFlags passed to g_file_query_info() + filename="gio/gfile.c" + line="1252">a set of #GFileQueryInfoFlags passed to g_file_query_info() nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1253">optional #GCancellable object, %NULL to ignore @@ -50505,10 +53351,11 @@ a regular file, directory, or symlink. + throws="1" + glib:async-func="query_filesystem_info_async"> Similar to g_file_query_info(), but obtains information + filename="gio/gfile.c" + line="1434">Similar to g_file_query_info(), but obtains information about the filesystem the @file is on, rather than the file itself. For instance the amount of space available and the type of the filesystem. @@ -50533,25 +53380,25 @@ returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileInfo or %NULL if there was an error. + filename="gio/gfile.c" + line="1468">a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1436">input #GFile an attribute query string + filename="gio/gfile.c" + line="1437">an attribute query string nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1438">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_query_filesystem_info_async" + glib:finish-func="query_filesystem_info_finish" + glib:sync-func="query_filesystem_info"> Asynchronously gets the requested information about the filesystem + filename="gio/gfile.c" + line="1497">Asynchronously gets the requested information about the filesystem that the specified @file is on. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). @@ -50581,27 +53430,27 @@ synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="1499">input #GFile an attribute query string + filename="gio/gfile.c" + line="1500">an attribute query string the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1501">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1502">optional #GCancellable object, %NULL to ignore @@ -50621,8 +53470,8 @@ operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1504">a #GAsyncReadyCallback to call when the request is satisfied @@ -50631,8 +53480,8 @@ operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="1506">the data to pass to callback function @@ -50641,14 +53490,14 @@ operation. c:identifier="g_file_query_filesystem_info_finish" throws="1"> Finishes an asynchronous filesystem info query. + filename="gio/gfile.c" + line="1541">Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async(). - + #GFileInfo for given @file + filename="gio/gfile.c" + line="1550">#GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). @@ -50656,22 +53505,25 @@ See g_file_query_filesystem_info_async(). input #GFile + filename="gio/gfile.c" + line="1543">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1544">a #GAsyncResult - + Gets the requested information about specified @file. + filename="gio/gfile.c" + line="1289">Gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as the type or size of the file). @@ -50701,31 +53553,31 @@ about the symlink itself will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileInfo for the given @file, or %NULL + filename="gio/gfile.c" + line="1329">a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1291">input #GFile an attribute query string + filename="gio/gfile.c" + line="1292">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1293">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1294">optional #GCancellable object, %NULL to ignore - + Asynchronously gets the requested information about specified @file. + filename="gio/gfile.c" + line="1359">Asynchronously gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as type or size for the file). @@ -50752,33 +53607,33 @@ version of this call. When the operation is finished, @callback will be called. You can then call g_file_query_info_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="1361">input #GFile an attribute query string + filename="gio/gfile.c" + line="1362">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1363">a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1364">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1365">optional #GCancellable object, %NULL to ignore @@ -50798,8 +53653,8 @@ then call g_file_query_info_finish() to get the result of the operation. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1367">a #GAsyncReadyCallback to call when the request is satisfied @@ -50808,8 +53663,8 @@ then call g_file_query_info_finish() to get the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="1369">the data to pass to callback function @@ -50818,14 +53673,14 @@ then call g_file_query_info_finish() to get the result of the operation. c:identifier="g_file_query_info_finish" throws="1"> Finishes an asynchronous file info query. + filename="gio/gfile.c" + line="1404">Finishes an asynchronous file info query. See g_file_query_info_async(). - + #GFileInfo for given @file + filename="gio/gfile.c" + line="1413">#GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). @@ -50833,14 +53688,14 @@ See g_file_query_info_async(). input #GFile + filename="gio/gfile.c" + line="1406">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1407">a #GAsyncResult @@ -50849,8 +53704,8 @@ See g_file_query_info_async(). c:identifier="g_file_query_settable_attributes" throws="1"> Obtain the list of settable attributes for the file. + filename="gio/gfile.c" + line="4981">Obtain the list of settable attributes for the file. Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will @@ -50860,11 +53715,11 @@ specific file may not support a specific attribute. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFileAttributeInfoList describing the settable attributes. + filename="gio/gfile.c" + line="4999">a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() @@ -50872,8 +53727,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="4983">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4984">optional #GCancellable object, %NULL to ignore @@ -50892,19 +53747,19 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_query_writable_namespaces" throws="1"> Obtain the list of attribute namespaces where new attributes + filename="gio/gfile.c" + line="5039">Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFileAttributeInfoList describing the writable namespaces. + filename="gio/gfile.c" + line="5054">a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() @@ -50912,8 +53767,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="5041">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5042">optional #GCancellable object, %NULL to ignore - + Opens a file for reading. The result is a #GFileInputStream that + filename="gio/gfile.c" + line="1688">Opens a file for reading. The result is a #GFileInputStream that can be used to read the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by @@ -50942,19 +53800,19 @@ If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + #GFileInputStream or %NULL on error. + filename="gio/gfile.c" + line="1706">#GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to read + filename="gio/gfile.c" + line="1690">#GFile to read nullable="1" allow-none="1"> a #GCancellable + filename="gio/gfile.c" + line="1691">a #GCancellable - + Asynchronously opens @file for reading. + filename="gio/gfile.c" + line="2107">Asynchronously opens @file for reading. For more details, see g_file_read() which is the synchronous version of this call. @@ -50979,21 +53840,21 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_read_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2109">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2110">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2111">optional #GCancellable object, %NULL to ignore @@ -51013,8 +53874,8 @@ of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2113">a #GAsyncReadyCallback to call when the request is satisfied @@ -51023,44 +53884,47 @@ of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2115">the data to pass to callback function Finishes an asynchronous file read operation started with + filename="gio/gfile.c" + line="2145">Finishes an asynchronous file read operation started with g_file_read_async(). - + a #GFileInputStream or %NULL on error. + filename="gio/gfile.c" + line="2154">a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2147">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2148">a #GAsyncResult - + Returns an output stream for overwriting the file, possibly + filename="gio/gfile.c" + line="1847">Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. @@ -51101,19 +53965,19 @@ file systems don't allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. - + a #GFileOutputStream or %NULL on error. + filename="gio/gfile.c" + line="1900">a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1849">input #GFile nullable="1" allow-none="1"> an optional [entity tag][gfile-etag] + filename="gio/gfile.c" + line="1850">an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="1852">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1853">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1854">optional #GCancellable object, %NULL to ignore - + Asynchronously overwrites the file, replacing the contents, + filename="gio/gfile.c" + line="2316">Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace() which is @@ -51162,15 +54029,15 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2318">input #GFile nullable="1" allow-none="1"> an [entity tag][gfile-etag] for the current #GFile, + filename="gio/gfile.c" + line="2319">an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2321">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2322">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2323">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2324">optional #GCancellable object, %NULL to ignore @@ -51218,8 +54085,8 @@ of the operation. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2326">a #GAsyncReadyCallback to call when the request is satisfied @@ -51228,18 +54095,19 @@ of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2328">the data to pass to callback function + throws="1" + glib:async-func="replace_contents_async"> Replaces the contents of @file with @contents of @length bytes. + filename="gio/gfile.c" + line="8514">Replaces the contents of @file with @contents of @length bytes. If @etag is specified (not %NULL), any existing file must have that etag, or the error %G_IO_ERROR_WRONG_ETAG will be returned. @@ -51255,33 +54123,33 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. The returned @new_etag can be used to verify that the file hasn't changed the next time it is saved over. - + %TRUE if successful. If an error has occurred, this function + filename="gio/gfile.c" + line="8546">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. input #GFile + filename="gio/gfile.c" + line="8516">input #GFile a string containing the new contents for @file + filename="gio/gfile.c" + line="8517">a string containing the new contents for @file the length of @contents in bytes + filename="gio/gfile.c" + line="8518">the length of @contents in bytes nullable="1" allow-none="1"> the old [entity-tag][gfile-etag] for the document, + filename="gio/gfile.c" + line="8519">the old [entity-tag](#entity-tags) for the document, or %NULL %TRUE if a backup should be created + filename="gio/gfile.c" + line="8521">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="8522">a set of #GFileCreateFlags optional="1" allow-none="1"> a location to a new [entity tag][gfile-etag] + filename="gio/gfile.c" + line="8523">a location to a new [entity tag](#entity-tags) for the document. This should be freed with g_free() when no longer needed, or %NULL @@ -51325,17 +54193,19 @@ changed the next time it is saved over. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="8526">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_replace_contents_async" + glib:finish-func="replace_contents_finish" + glib:sync-func="replace_contents"> Starts an asynchronous replacement of @file with the given + filename="gio/gfile.c" + line="8721">Starts an asynchronous replacement of @file with the given @contents of @length bytes. @etag will replace the document's current entity tag. @@ -51354,29 +54224,29 @@ Note that no copy of @contents will be made, so it must stay valid until @callback is called. See g_file_replace_contents_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call. - + input #GFile + filename="gio/gfile.c" + line="8723">input #GFile string of contents to replace the file with + filename="gio/gfile.c" + line="8724">string of contents to replace the file with the length of @contents in bytes + filename="gio/gfile.c" + line="8725">the length of @contents in bytes nullable="1" allow-none="1"> a new [entity tag][gfile-etag] for the @file, or %NULL + filename="gio/gfile.c" + line="8726">a new [entity tag](#entity-tags) for the @file, or %NULL %TRUE if a backup should be created + filename="gio/gfile.c" + line="8727">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="8728">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="8729">optional #GCancellable object, %NULL to ignore scope="async" closure="7"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gfile.c" + line="8730">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="8731">the data to pass to callback function @@ -51435,8 +54305,8 @@ contents (without copying) for the duration of the call. c:identifier="g_file_replace_contents_bytes_async" version="2.40"> Same as g_file_replace_contents_async() but takes a #GBytes input instead. + filename="gio/gfile.c" + line="8772">Same as g_file_replace_contents_async() but takes a #GBytes input instead. This function will keep a ref on @contents until the operation is done. Unlike g_file_replace_contents_async() this allows forgetting about the content without waiting for the callback. @@ -51444,21 +54314,21 @@ content without waiting for the callback. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_replace_contents_finish(). - + input #GFile + filename="gio/gfile.c" + line="8774">input #GFile a #GBytes + filename="gio/gfile.c" + line="8775">a #GBytes nullable="1" allow-none="1"> a new [entity tag][gfile-etag] for the @file, or %NULL + filename="gio/gfile.c" + line="8776">a new [entity tag](#entity-tags) for the @file, or %NULL %TRUE if a backup should be created + filename="gio/gfile.c" + line="8777">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="8778">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="8779">optional #GCancellable object, %NULL to ignore scope="async" closure="6"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gfile.c" + line="8780">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="8781">the data to pass to callback function @@ -51517,28 +54387,28 @@ g_file_replace_contents_finish(). c:identifier="g_file_replace_contents_finish" throws="1"> Finishes an asynchronous replace of the given @file. See + filename="gio/gfile.c" + line="8827">Finishes an asynchronous replace of the given @file. See g_file_replace_contents_async(). Sets @new_etag to the new entity tag for the document, if present. - + %TRUE on success, %FALSE on failure. + filename="gio/gfile.c" + line="8840">%TRUE on success, %FALSE on failure. input #GFile + filename="gio/gfile.c" + line="8829">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="8830">a #GAsyncResult optional="1" allow-none="1"> a location of a new [entity tag][gfile-etag] + filename="gio/gfile.c" + line="8831">a location of a new [entity tag](#entity-tags) for the document. This should be freed with g_free() when it is no longer needed, or %NULL @@ -51561,28 +54431,28 @@ tag for the document, if present. c:identifier="g_file_replace_finish" throws="1"> Finishes an asynchronous file replace operation started with + filename="gio/gfile.c" + line="2365">Finishes an asynchronous file replace operation started with g_file_replace_async(). - + a #GFileOutputStream, or %NULL on error. + filename="gio/gfile.c" + line="2374">a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2367">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2368">a #GAsyncResult @@ -51590,10 +54460,11 @@ g_file_replace_async(). + throws="1" + glib:async-func="replace_readwrite_async"> Returns an output stream for overwriting the file in readwrite mode, + filename="gio/gfile.c" + line="2052">Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. @@ -51603,19 +54474,19 @@ same thing but returns an output stream only. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2074">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). a #GFile + filename="gio/gfile.c" + line="2054">a #GFile nullable="1" allow-none="1"> an optional [entity tag][gfile-etag] + filename="gio/gfile.c" + line="2055">an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2057">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2058">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2059">optional #GCancellable object, %NULL to ignore @@ -51654,10 +54525,12 @@ rather than just opening for reading or writing. + version="2.22" + glib:finish-func="replace_readwrite_finish" + glib:sync-func="replace_readwrite"> Asynchronously overwrites the file in read-write mode, + filename="gio/gfile.c" + line="2540">Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. @@ -51667,15 +54540,15 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_readwrite_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="2542">input #GFile nullable="1" allow-none="1"> an [entity tag][gfile-etag] for the current #GFile, + filename="gio/gfile.c" + line="2543">an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2545">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2546">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2547">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2548">optional #GCancellable object, %NULL to ignore @@ -51723,8 +54596,8 @@ the result of the operation. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2550">a #GAsyncReadyCallback to call when the request is satisfied @@ -51733,8 +54606,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="2552">the data to pass to callback function @@ -51744,28 +54617,28 @@ the result of the operation. version="2.22" throws="1"> Finishes an asynchronous file replace operation started with + filename="gio/gfile.c" + line="2592">Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async(). - + a #GFileIOStream, or %NULL on error. + filename="gio/gfile.c" + line="2601">a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2594">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2595">a #GAsyncResult @@ -51773,31 +54646,31 @@ g_file_replace_readwrite_async(). Resolves a relative path for @file to an absolute path. + filename="gio/gfile.c" + line="1019">Resolves a relative path for @file to an absolute path. This call does no blocking I/O. If the @relative_path is an absolute path name, the resolution is done absolutely (without taking @file path as base). - + a #GFile for the resolved path. + filename="gio/gfile.c" + line="1031">a #GFile for the resolved path. input #GFile + filename="gio/gfile.c" + line="1021">input #GFile a given relative path string + filename="gio/gfile.c" + line="1022">a given relative path string @@ -51806,8 +54679,8 @@ is done absolutely (without taking @file path as base). c:identifier="g_file_set_attribute" throws="1"> Sets an attribute in the file with attribute name @attribute to @value_p. + filename="gio/gfile.c" + line="5099">Sets an attribute in the file with attribute name @attribute to @value_p. Some attributes can be unset by setting @type to %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. @@ -51815,30 +54688,30 @@ Some attributes can be unset by setting @type to If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the attribute was set, %FALSE otherwise. + filename="gio/gfile.c" + line="5120">%TRUE if the attribute was set, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5101">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5102">a string containing the attribute's name The type of the attribute + filename="gio/gfile.c" + line="5103">The type of the attribute nullable="1" allow-none="1"> a pointer to the value (or the pointer + filename="gio/gfile.c" + line="5104">a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5106">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5107">optional #GCancellable object, %NULL to ignore @@ -51873,45 +54746,45 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_set_attribute_byte_string" throws="1"> Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. + filename="gio/gfile.c" + line="5349">Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. If @attribute is of a different type, this operation will fail, returning %FALSE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @attribute was successfully set to @value + filename="gio/gfile.c" + line="5367">%TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5351">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5352">a string containing the attribute's name a string containing the attribute's new value + filename="gio/gfile.c" + line="5353">a string containing the attribute's new value a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5354">a #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5355">optional #GCancellable object, %NULL to ignore @@ -51930,44 +54803,44 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_set_attribute_int32" throws="1"> Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. + filename="gio/gfile.c" + line="5416">Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @attribute was successfully set to @value + filename="gio/gfile.c" + line="5433">%TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5418">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5419">a string containing the attribute's name a #gint32 containing the attribute's new value + filename="gio/gfile.c" + line="5420">a #gint32 containing the attribute's new value a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5421">a #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5422">optional #GCancellable object, %NULL to ignore @@ -51986,43 +54859,43 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_set_attribute_int64" throws="1"> Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. + filename="gio/gfile.c" + line="5482">Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @attribute was successfully set, %FALSE otherwise. + filename="gio/gfile.c" + line="5499">%TRUE if the @attribute was successfully set, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5484">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5485">a string containing the attribute's name a #guint64 containing the attribute's new value + filename="gio/gfile.c" + line="5486">a #guint64 containing the attribute's new value a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5487">a #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5488">optional #GCancellable object, %NULL to ignore @@ -52041,43 +54914,43 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_set_attribute_string" throws="1"> Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. + filename="gio/gfile.c" + line="5317">Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @attribute was successfully set, %FALSE otherwise. + filename="gio/gfile.c" + line="5334">%TRUE if the @attribute was successfully set, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5319">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5320">a string containing the attribute's name a string containing the attribute's value + filename="gio/gfile.c" + line="5321">a string containing the attribute's value #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5322">#GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5323">optional #GCancellable object, %NULL to ignore @@ -52096,44 +54969,44 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_set_attribute_uint32" throws="1"> Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. + filename="gio/gfile.c" + line="5383">Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @attribute was successfully set to @value + filename="gio/gfile.c" + line="5400">%TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5385">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5386">a string containing the attribute's name a #guint32 containing the attribute's new value + filename="gio/gfile.c" + line="5387">a #guint32 containing the attribute's new value a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5388">a #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5389">optional #GCancellable object, %NULL to ignore @@ -52152,44 +55025,44 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. c:identifier="g_file_set_attribute_uint64" throws="1"> Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. + filename="gio/gfile.c" + line="5449">Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. If @attribute is of a different type, this operation will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if the @attribute was successfully set to @value + filename="gio/gfile.c" + line="5466">%TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5451">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5452">a string containing the attribute's name a #guint64 containing the attribute's new value + filename="gio/gfile.c" + line="5453">a #guint64 containing the attribute's new value a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5454">a #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5455">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_set_attributes_async" + glib:finish-func="set_attributes_finish"> Asynchronously sets the attributes of @file with @info. + filename="gio/gfile.c" + line="5243">Asynchronously sets the attributes of @file with @info. For more details, see g_file_set_attributes_from_info(), which is the synchronous version of this call. @@ -52216,33 +55090,33 @@ which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_attributes_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="5245">input #GFile a #GFileInfo + filename="gio/gfile.c" + line="5246">a #GFileInfo a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5247">a #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="5248">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5249">optional #GCancellable object, %NULL to ignore @@ -52262,8 +55136,8 @@ the result of the operation. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5251">a #GAsyncReadyCallback to call when the request is satisfied @@ -52272,8 +55146,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="5253">the data to pass to callback function @@ -52282,26 +55156,26 @@ the result of the operation. c:identifier="g_file_set_attributes_finish" throws="1"> Finishes setting an attribute started in g_file_set_attributes_async(). - + filename="gio/gfile.c" + line="5288">Finishes setting an attribute started in g_file_set_attributes_async(). + %TRUE if the attributes were set correctly, %FALSE otherwise. + filename="gio/gfile.c" + line="5297">%TRUE if the attributes were set correctly, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5290">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5291">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> a #GFileInfo + filename="gio/gfile.c" + line="5292">a #GFileInfo @@ -52319,8 +55193,8 @@ the result of the operation. c:identifier="g_file_set_attributes_from_info" throws="1"> Tries to set all attributes in the #GFileInfo on the target + filename="gio/gfile.c" + line="5152">Tries to set all attributes in the #GFileInfo on the target values, not stopping on the first error. If there is any error during this operation then @error will @@ -52332,30 +55206,30 @@ also detect further errors. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %FALSE if there was any error, %TRUE otherwise. + filename="gio/gfile.c" + line="5174">%FALSE if there was any error, %TRUE otherwise. input #GFile + filename="gio/gfile.c" + line="5154">input #GFile a #GFileInfo + filename="gio/gfile.c" + line="5155">a #GFileInfo #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5156">#GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5157">optional #GCancellable object, %NULL to ignore @@ -52372,10 +55246,11 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + throws="1" + glib:async-func="set_display_name_async"> Renames @file to the specified display name. + filename="gio/gfile.c" + line="4854">Renames @file to the specified display name. The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the @file is renamed to this. @@ -52390,11 +55265,11 @@ On success the resulting converted filename is returned. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GFile specifying what @file was renamed to, + filename="gio/gfile.c" + line="4878">a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). @@ -52402,14 +55277,14 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile + filename="gio/gfile.c" + line="4856">input #GFile a string + filename="gio/gfile.c" + line="4857">a string nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4858">optional #GCancellable object, %NULL to ignore + c:identifier="g_file_set_display_name_async" + glib:finish-func="set_display_name_finish" + glib:sync-func="set_display_name"> Asynchronously sets the display name for a given #GFile. + filename="gio/gfile.c" + line="4910">Asynchronously sets the display name for a given #GFile. For more details, see g_file_set_display_name() which is the synchronous version of this call. @@ -52436,27 +55313,27 @@ the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_display_name_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="4912">input #GFile a string + filename="gio/gfile.c" + line="4913">a string the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4914">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4915">optional #GCancellable object, %NULL to ignore @@ -52476,8 +55353,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="4917">a #GAsyncReadyCallback to call when the request is satisfied @@ -52486,8 +55363,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="4919">the data to pass to callback function @@ -52496,38 +55373,39 @@ the result of the operation. c:identifier="g_file_set_display_name_finish" throws="1"> Finishes setting a display name started with + filename="gio/gfile.c" + line="4952">Finishes setting a display name started with g_file_set_display_name_async(). - + a #GFile or %NULL on error. + filename="gio/gfile.c" + line="4961">a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="4954">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4955">a #GAsyncResult + version="2.22" + glib:finish-func="start_mountable_finish"> Starts a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="9150">Starts a file of type %G_FILE_TYPE_MOUNTABLE. Using @start_operation, you can request callbacks when, for instance, passwords are needed during authentication. @@ -52538,21 +55416,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="9152">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="9153">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, or %NULL to avoid user interaction + filename="gio/gfile.c" + line="9154">a #GMountOperation, or %NULL to avoid user interaction nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="9155">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + filename="gio/gfile.c" + line="9156">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="9157">the data to pass to callback function @@ -52600,40 +55478,41 @@ the result of the operation. version="2.22" throws="1"> Finishes a start operation. See g_file_start_mountable() for details. + filename="gio/gfile.c" + line="9204">Finishes a start operation. See g_file_start_mountable() for details. Finish an asynchronous start operation that was started with g_file_start_mountable(). - + %TRUE if the operation finished successfully. %FALSE + filename="gio/gfile.c" + line="9215">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9206">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9207">a #GAsyncResult + version="2.22" + glib:finish-func="stop_mountable_finish"> Stops a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="9239">Stops a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -52642,21 +55521,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_stop_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="9241">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="9242">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="9243">a #GMountOperation, or %NULL to avoid user interaction. @@ -52674,8 +55553,8 @@ the result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="9245">optional #GCancellable object, %NULL to ignore @@ -52686,8 +55565,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="9247">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -52696,8 +55575,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="9249">the data to pass to callback function @@ -52707,30 +55586,30 @@ the result of the operation. version="2.22" throws="1"> Finishes a stop operation, see g_file_stop_mountable() for details. + filename="gio/gfile.c" + line="9294">Finishes a stop operation, see g_file_stop_mountable() for details. Finish an asynchronous stop operation that was started with g_file_stop_mountable(). - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="9305">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9296">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9297">a #GAsyncResult @@ -52739,52 +55618,58 @@ with g_file_stop_mountable(). c:identifier="g_file_supports_thread_contexts" version="2.22"> Checks if @file supports -[thread-default contexts][g-main-context-push-thread-default-context]. + filename="gio/gfile.c" + line="9411">Checks if @file supports thread-default main contexts +(see [method@GLib.MainContext.push_thread_default]) If this returns %FALSE, you cannot perform asynchronous operations on @file in a thread that has a thread-default context. - + Whether or not @file supports thread-default contexts. + filename="gio/gfile.c" + line="9420">Whether or not @file supports thread-default contexts. a #GFile + filename="gio/gfile.c" + line="9413">a #GFile - + Sends @file to the "Trashcan", if possible. This is similar to + filename="gio/gfile.c" + line="4747">Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. -Not all file systems support trashing, so this call can return the +Trashing is disabled for system mounts by default (see +g_unix_mount_entry_is_system_internal()), so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix -mount option can be used to disable g_file_trash() support for certain +mount option can be used to disable g_file_trash() support for particular mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. +Since 2.82, the `x-gvfs-trash` unix mount option can be used to enable +g_file_trash() support for particular system mounts. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on successful trash, %FALSE otherwise. + filename="gio/gfile.c" + line="4768">%TRUE on successful trash, %FALSE otherwise. #GFile to send to trash + filename="gio/gfile.c" + line="4749">#GFile to send to trash nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4750">optional #GCancellable object, %NULL to ignore @@ -52801,25 +55686,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + version="2.38" + glib:finish-func="trash_finish" + glib:sync-func="trash"> Asynchronously sends @file to the Trash location, if possible. - + filename="gio/gfile.c" + line="4795">Asynchronously sends @file to the Trash location, if possible. + input #GFile + filename="gio/gfile.c" + line="4797">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4798">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4799">optional #GCancellable object, %NULL to ignore @@ -52839,8 +55726,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4801">a #GAsyncReadyCallback to call when the request is satisfied @@ -52849,8 +55736,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="4803">the data to pass to callback function @@ -52860,27 +55747,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. version="2.38" throws="1"> Finishes an asynchronous file trashing operation, started with + filename="gio/gfile.c" + line="4828">Finishes an asynchronous file trashing operation, started with g_file_trash_async(). - + %TRUE on successful trash, %FALSE otherwise. + filename="gio/gfile.c" + line="4837">%TRUE on successful trash, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4830">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4831">a #GAsyncResult @@ -52888,10 +55775,11 @@ g_file_trash_async(). + deprecated-version="2.22" + glib:finish-func="unmount_mountable_finish"> Unmounts a file of type G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="5602">Unmounts a file of type G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -52901,21 +55789,21 @@ When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. Use g_file_unmount_mountable_with_operation() instead. - + input #GFile + filename="gio/gfile.c" + line="5604">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5605">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5606">optional #GCancellable object, %NULL to ignore @@ -52935,8 +55823,8 @@ the result of the operation. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5608">a #GAsyncReadyCallback to call when the request is satisfied @@ -52945,8 +55833,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="5610">the data to pass to callback function @@ -52957,42 +55845,43 @@ the result of the operation. deprecated-version="2.22" throws="1"> Finishes an unmount operation, see g_file_unmount_mountable() for details. + filename="gio/gfile.c" + line="5653">Finishes an unmount operation, see g_file_unmount_mountable() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable(). Use g_file_unmount_mountable_with_operation_finish() instead. - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="5664">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5655">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5656">a #GAsyncResult + version="2.22" + glib:finish-func="unmount_mountable_with_operation_finish"> Unmounts a file of type %G_FILE_TYPE_MOUNTABLE. + filename="gio/gfile.c" + line="5689">Unmounts a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -53001,21 +55890,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation. - + input #GFile + filename="gio/gfile.c" + line="5691">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5692">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5693">a #GMountOperation, or %NULL to avoid user interaction @@ -53033,8 +55922,8 @@ the result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5695">optional #GCancellable object, %NULL to ignore @@ -53045,8 +55934,8 @@ the result of the operation. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5697">a #GAsyncReadyCallback to call when the request is satisfied @@ -53055,8 +55944,8 @@ the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfile.c" + line="5699">the data to pass to callback function @@ -53066,31 +55955,31 @@ the result of the operation. version="2.22" throws="1"> Finishes an unmount operation, + filename="gio/gfile.c" + line="5751">Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable_with_operation(). - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="5763">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5753">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5754">a #GAsyncResult @@ -53098,24 +55987,24 @@ with g_file_unmount_mountable_with_operation(). Information about a specific attribute. - + the name of the attribute. the #GFileAttributeType type of the attribute. a set of #GFileAttributeInfoFlags. @@ -53125,7 +56014,7 @@ with g_file_unmount_mountable_with_operation(). glib:get-type="g_file_attribute_info_flags_get_type" c:type="GFileAttributeInfoFlags"> Flags specifying the behaviour of an attribute. glib:nick="none" glib:name="G_FILE_ATTRIBUTE_INFO_NONE"> no flags set. glib:nick="copy-with-file" glib:name="G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE"> copy the attribute values when the file is copied. glib:nick="copy-when-moved" glib:name="G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED"> copy the attribute values when the file is moved. @@ -53161,67 +56050,67 @@ with g_file_unmount_mountable_with_operation(). glib:get-type="g_file_attribute_info_list_get_type" c:symbol-prefix="file_attribute_info_list"> Acts as a lightweight registry for possible valid file attributes. The registry stores Key-Value pair formats as #GFileAttributeInfos. - + an array of #GFileAttributeInfos. the number of values in the array. Creates a new file attribute info list. - + filename="gio/gfileattribute.c" + line="689">Creates a new file attribute info list. + a #GFileAttributeInfoList. + filename="gio/gfileattribute.c" + line="694">a #GFileAttributeInfoList. Adds a new attribute with @name to the @list, setting + filename="gio/gfileattribute.c" + line="840">Adds a new attribute with @name to the @list, setting its @type and @flags. - + a #GFileAttributeInfoList. + filename="gio/gfileattribute.c" + line="842">a #GFileAttributeInfoList. the name of the attribute to add. + filename="gio/gfileattribute.c" + line="843">the name of the attribute to add. the #GFileAttributeType for the attribute. + filename="gio/gfileattribute.c" + line="844">the #GFileAttributeType for the attribute. #GFileAttributeInfoFlags for the attribute. + filename="gio/gfileattribute.c" + line="845">#GFileAttributeInfoFlags for the attribute. @@ -53229,20 +56118,20 @@ its @type and @flags. Makes a duplicate of a file attribute info list. - + filename="gio/gfileattribute.c" + line="711">Makes a duplicate of a file attribute info list. + a copy of the given @list. + filename="gio/gfileattribute.c" + line="717">a copy of the given @list. a #GFileAttributeInfoList to duplicate. + filename="gio/gfileattribute.c" + line="713">a #GFileAttributeInfoList to duplicate. @@ -53250,48 +56139,48 @@ its @type and @flags. Gets the file attribute with the name @name from @list. - + filename="gio/gfileattribute.c" + line="813">Gets the file attribute with the name @name from @list. + a #GFileAttributeInfo for the @name, or %NULL if an + filename="gio/gfileattribute.c" + line="820">a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found. a #GFileAttributeInfoList. + filename="gio/gfileattribute.c" + line="815">a #GFileAttributeInfoList. the name of the attribute to look up. + filename="gio/gfileattribute.c" + line="816">the name of the attribute to look up. References a file attribute info list. - + filename="gio/gfileattribute.c" + line="743">References a file attribute info list. + #GFileAttributeInfoList or %NULL on error. + filename="gio/gfileattribute.c" + line="749">#GFileAttributeInfoList or %NULL on error. a #GFileAttributeInfoList to reference. + filename="gio/gfileattribute.c" + line="745">a #GFileAttributeInfoList to reference. @@ -53299,18 +56188,18 @@ attribute isn't found. Removes a reference from the given @list. If the reference count + filename="gio/gfileattribute.c" + line="765">Removes a reference from the given @list. If the reference count falls to zero, the @list is deleted. - + The #GFileAttributeInfoList to unreference. + filename="gio/gfileattribute.c" + line="767">The #GFileAttributeInfoList to unreference. @@ -53324,13 +56213,13 @@ falls to zero, the @list is deleted. glib:get-type="g_file_attribute_matcher_get_type" c:symbol-prefix="file_attribute_matcher"> Determines if a string matches a file attribute. - + filename="gio/giotypes.h" + line="77">Determines if a string matches a file attribute. + Creates a new file attribute matcher, which matches attributes + filename="gio/gfileinfo.c" + line="2687">Creates a new file attribute matcher, which matches attributes against a given string. #GFileAttributeMatchers are reference counted structures, and are created with a reference count of 1. If the number of references falls to 0, the #GFileAttributeMatcher is @@ -53349,18 +56238,18 @@ The wildcard "*" may be used to match all keys and namespaces, or standard namespace. - `"standard::type,unix::*"`: matches the type key in the standard namespace and all keys in the unix namespace. - + a #GFileAttributeMatcher + filename="gio/gfileinfo.c" + line="2711">a #GFileAttributeMatcher an attribute string to match. + filename="gio/gfileinfo.c" + line="2689">an attribute string to match. @@ -53368,32 +56257,32 @@ The wildcard "*" may be used to match all keys and namespaces, or Checks if the matcher will match all of the keys in a given namespace. + filename="gio/gfileinfo.c" + line="2978">Checks if the matcher will match all of the keys in a given namespace. This will always return %TRUE if a wildcard character is in use (e.g. if matcher was created with "standard::*" and @ns is "standard", or if matcher was created using "*" and namespace is anything.) TODO: this is awkwardly worded. - + %TRUE if the matcher matches all of the entries + filename="gio/gfileinfo.c" + line="2990">%TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise. a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="2980">a #GFileAttributeMatcher. a string containing a file attribute namespace. + filename="gio/gfileinfo.c" + line="2981">a string containing a file attribute namespace. @@ -53401,49 +56290,49 @@ in the given @ns, %FALSE otherwise. Gets the next matched attribute from a #GFileAttributeMatcher. - + filename="gio/gfileinfo.c" + line="3028">Gets the next matched attribute from a #GFileAttributeMatcher. + a string containing the next attribute or, %NULL if + filename="gio/gfileinfo.c" + line="3034">a string containing the next attribute or, %NULL if no more attribute exist. a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="3030">a #GFileAttributeMatcher. Checks if an attribute will be matched by an attribute matcher. If + filename="gio/gfileinfo.c" + line="2950">Checks if an attribute will be matched by an attribute matcher. If the matcher was created with the "*" matching string, this function will always return %TRUE. - + %TRUE if @attribute matches @matcher. %FALSE otherwise. + filename="gio/gfileinfo.c" + line="2959">%TRUE if @attribute matches @matcher. %FALSE otherwise. a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="2952">a #GFileAttributeMatcher. a file attribute key. + filename="gio/gfileinfo.c" + line="2953">a file attribute key. @@ -53451,55 +56340,55 @@ will always return %TRUE. Checks if an attribute matcher only matches a given attribute. Always + filename="gio/gfileinfo.c" + line="2882">Checks if an attribute matcher only matches a given attribute. Always returns %FALSE if "*" was used when creating the matcher. - + %TRUE if the matcher only matches @attribute. %FALSE otherwise. + filename="gio/gfileinfo.c" + line="2890">%TRUE if the matcher only matches @attribute. %FALSE otherwise. a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="2884">a #GFileAttributeMatcher. a file attribute key. + filename="gio/gfileinfo.c" + line="2885">a file attribute key. References a file attribute matcher. - + filename="gio/gfileinfo.c" + line="2838">References a file attribute matcher. + a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="2844">a #GFileAttributeMatcher. a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="2840">a #GFileAttributeMatcher. Subtracts all attributes of @subtract from @matcher and returns + filename="gio/gfileinfo.c" + line="2767">Subtracts all attributes of @subtract from @matcher and returns a matcher that supports those attributes. Note that currently it is not possible to remove a single @@ -53507,11 +56396,11 @@ attribute when the @matcher matches the whole namespace - or remove a namespace or attribute when the matcher matches everything. This is a limitation of the current implementation, but may be fixed in the future. - + A file attribute matcher matching all attributes of + filename="gio/gfileinfo.c" + line="2781">A file attribute matcher matching all attributes of @matcher that are not matched by @subtract @@ -53521,8 +56410,8 @@ in the future. nullable="1" allow-none="1"> Matcher to subtract from + filename="gio/gfileinfo.c" + line="2769">Matcher to subtract from nullable="1" allow-none="1"> The matcher to subtract + filename="gio/gfileinfo.c" + line="2770">The matcher to subtract @@ -53540,16 +56429,16 @@ in the future. c:identifier="g_file_attribute_matcher_to_string" version="2.32"> Prints what the matcher is matching against. The format will be + filename="gio/gfileinfo.c" + line="3065">Prints what the matcher is matching against. The format will be equal to the format passed to g_file_attribute_matcher_new(). The output however, might not be identical, as the matcher may decide to use a different order or omit needless parts. - + a string describing the attributes the matcher matches + filename="gio/gfileinfo.c" + line="3074">a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL. @@ -53559,26 +56448,26 @@ decide to use a different order or omit needless parts. nullable="1" allow-none="1"> a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="3067">a #GFileAttributeMatcher. Unreferences @matcher. If the reference count falls below 1, + filename="gio/gfileinfo.c" + line="2857">Unreferences @matcher. If the reference count falls below 1, the @matcher is automatically freed. - + a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="2859">a #GFileAttributeMatcher. @@ -53589,7 +56478,7 @@ the @matcher is automatically freed. glib:get-type="g_file_attribute_status_get_type" c:type="GFileAttributeStatus"> Used by g_file_set_attributes_from_info() when setting file attributes. glib:nick="unset" glib:name="G_FILE_ATTRIBUTE_STATUS_UNSET"> Attribute value is unset (empty). glib:nick="set" glib:name="G_FILE_ATTRIBUTE_STATUS_SET"> Attribute value is set. glib:nick="error-setting" glib:name="G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING"> Indicates an error in setting the value. @@ -53624,7 +56513,7 @@ the @matcher is automatically freed. glib:get-type="g_file_attribute_type_get_type" c:type="GFileAttributeType"> The data types for file attributes. glib:nick="invalid" glib:name="G_FILE_ATTRIBUTE_TYPE_INVALID"> indicates an invalid or uninitialized type. glib:nick="string" glib:name="G_FILE_ATTRIBUTE_TYPE_STRING"> a null terminated UTF8 string. glib:nick="byte-string" glib:name="G_FILE_ATTRIBUTE_TYPE_BYTE_STRING"> a zero terminated string of non-zero bytes. glib:nick="boolean" glib:name="G_FILE_ATTRIBUTE_TYPE_BOOLEAN"> a boolean value. glib:nick="uint32" glib:name="G_FILE_ATTRIBUTE_TYPE_UINT32"> an unsigned 4-byte/32-bit integer. glib:nick="int32" glib:name="G_FILE_ATTRIBUTE_TYPE_INT32"> a signed 4-byte/32-bit integer. glib:nick="uint64" glib:name="G_FILE_ATTRIBUTE_TYPE_UINT64"> an unsigned 8-byte/64-bit integer. glib:nick="int64" glib:name="G_FILE_ATTRIBUTE_TYPE_INT64"> a signed 8-byte/64-bit integer. glib:nick="object" glib:name="G_FILE_ATTRIBUTE_TYPE_OBJECT"> a #GObject. glib:nick="stringv" glib:name="G_FILE_ATTRIBUTE_TYPE_STRINGV"> a %NULL terminated char **. Since 2.22 @@ -53722,7 +56611,7 @@ the @matcher is automatically freed. glib:get-type="g_file_copy_flags_get_type" c:type="GFileCopyFlags"> Flags used when copying or moving files. glib:nick="none" glib:name="G_FILE_COPY_NONE"> No flags set. glib:nick="overwrite" glib:name="G_FILE_COPY_OVERWRITE"> Overwrite any existing files glib:nick="backup" glib:name="G_FILE_COPY_BACKUP"> Make a backup of any existing files. glib:nick="nofollow-symlinks" glib:name="G_FILE_COPY_NOFOLLOW_SYMLINKS"> Don't follow symlinks. glib:nick="all-metadata" glib:name="G_FILE_COPY_ALL_METADATA"> Copy all file metadata instead of just default set used for copy (see #GFileInfo). glib:nick="no-fallback-for-move" glib:name="G_FILE_COPY_NO_FALLBACK_FOR_MOVE"> Don't use copy and delete fallback if native move not supported. glib:nick="target-default-perms" glib:name="G_FILE_COPY_TARGET_DEFAULT_PERMS"> Leaves target file with default perms, instead of setting the source file perms. + + Use default modification + timestamps instead of copying them from the source file. Since 2.80 + Flags used when an operation may create a file. glib:nick="none" glib:name="G_FILE_CREATE_NONE"> No flags set. glib:nick="private" glib:name="G_FILE_CREATE_PRIVATE"> Create a file that can only be accessed by the current user. @@ -53820,7 +56719,7 @@ the @matcher is automatically freed. glib:nick="replace-destination" glib:name="G_FILE_CREATE_REPLACE_DESTINATION"> Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This @@ -53841,30 +56740,32 @@ the @matcher is automatically freed. glib:get-type="g_file_descriptor_based_get_type" glib:type-struct="FileDescriptorBasedIface"> #GFileDescriptorBased is implemented by streams (implementations of -#GInputStream or #GOutputStream) that are based on file descriptors. + filename="gio/gfiledescriptorbased.c" + line="28">`GFileDescriptorBased` is an interface for file descriptor based IO. + +It is implemented by streams (implementations of [class@Gio.InputStream] or +[class@Gio.OutputStream]) that are based on file descriptors. Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - +file or the `GioUnix-2.0` GIR namespace when using it. + Gets the underlying file descriptor. - + filename="gio/gfiledescriptorbased.c" + line="51">Gets the underlying file descriptor. + The file descriptor + filename="gio/gfiledescriptorbased.c" + line="57">The file descriptor a #GFileDescriptorBased. + filename="gio/gfiledescriptorbased.c" + line="53">a #GFileDescriptorBased. @@ -53873,20 +56774,20 @@ file when using it. c:identifier="g_file_descriptor_based_get_fd" version="2.24"> Gets the underlying file descriptor. - + filename="gio/gfiledescriptorbased.c" + line="51">Gets the underlying file descriptor. + The file descriptor + filename="gio/gfiledescriptorbased.c" + line="57">The file descriptor a #GFileDescriptorBased. + filename="gio/gfiledescriptorbased.c" + line="53">a #GFileDescriptorBased. @@ -53896,29 +56797,32 @@ file when using it. c:type="GFileDescriptorBasedIface" glib:is-gtype-struct-for="FileDescriptorBased"> An interface for file descriptor based io objects. - + filename="gio/gfiledescriptorbased.h" + line="39">An interface for file descriptor based io objects. + The parent interface. + filename="gio/gfiledescriptorbased.h" + line="41">The parent interface. + Gets the underlying file descriptor. - + The file descriptor + filename="gio/gfiledescriptorbased.c" + line="57">The file descriptor a #GFileDescriptorBased. + filename="gio/gfiledescriptorbased.c" + line="53">a #GFileDescriptorBased. @@ -53933,20 +56837,20 @@ file when using it. glib:get-type="g_file_enumerator_get_type" glib:type-struct="FileEnumeratorClass"> #GFileEnumerator allows you to operate on a set of #GFiles, -returning a #GFileInfo structure for each file enumerated (e.g. -g_file_enumerate_children() will return a #GFileEnumerator for each + filename="gio/gfileenumerator.c" + line="41">`GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects, +returning a [class@Gio.FileInfo] structure for each file enumerated (e.g. +[method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each of the children within a directory). -To get the next file's information from a #GFileEnumerator, use -g_file_enumerator_next_file() or its asynchronous version, -g_file_enumerator_next_files_async(). Note that the asynchronous -version will return a list of #GFileInfos, whereas the +To get the next file's information from a `GFileEnumerator`, use +[method@Gio.FileEnumerator.next_file] or its asynchronous version, +[method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous +version will return a list of [class@Gio.FileInfo] objects, whereas the synchronous will only return the next file in the enumerator. The ordering of returned files is unspecified for non-Unix -platforms; for more information, see g_dir_read_name(). On Unix, +platforms; for more information, see [method@GLib.Dir.read_name]. On Unix, when operating on local files, returned files will be sorted by inode number. Effectively you can assume that the ordering of returned files will be stable between successive calls (and @@ -53956,35 +56860,37 @@ If your application needs a specific ordering, such as by name or modification time, you will have to implement that in your application code. -To close a #GFileEnumerator, use g_file_enumerator_close(), or -its asynchronous version, g_file_enumerator_close_async(). Once -a #GFileEnumerator is closed, no further actions may be performed -on it, and it should be freed with g_object_unref(). - - +To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or +its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once +a `GFileEnumerator` is closed, no further actions may be performed +on it, and it should be freed with [method@GObject.Object.unref]. + + Asynchronously closes the file enumerator. + filename="gio/gfileenumerator.c" + line="486">Asynchronously closes the file enumerator. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in g_file_enumerator_close_finish(). - + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="488">a #GFileEnumerator. the [I/O priority][io-priority] of the request + filename="gio/gfileenumerator.c" + line="489">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="490">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfileenumerator.c" + line="491">a #GAsyncReadyCallback to call when the request is satisfied @@ -54014,16 +56920,16 @@ g_file_enumerator_close_finish(). allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfileenumerator.c" + line="493">the data to pass to callback function Finishes closing a file enumerator, started from g_file_enumerator_close_async(). + filename="gio/gfileenumerator.c" + line="540">Finishes closing a file enumerator, started from g_file_enumerator_close_async(). If the file enumerator was already closed when g_file_enumerator_close_async() was called, then this function will report %G_IO_ERROR_CLOSED in @error, and @@ -54033,30 +56939,30 @@ return %FALSE. If @cancellable was not %NULL, then the operation may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be returned. - + %TRUE if the close operation has finished successfully. + filename="gio/gfileenumerator.c" + line="558">%TRUE if the close operation has finished successfully. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="542">a #GFileEnumerator. a #GAsyncResult. + filename="gio/gfileenumerator.c" + line="543">a #GAsyncResult. - + @@ -54074,8 +56980,8 @@ returned. Returns information for the next file in the enumerated object. + filename="gio/gfileenumerator.c" + line="180">Returns information for the next file in the enumerated object. Will block until the information is available. The #GFileInfo returned from this function will contain attributes that match the attribute string that was passed when the #GFileEnumerator was created. @@ -54086,11 +56992,11 @@ order of returned files. On error, returns %NULL and sets @error to the error. If the enumerator is at the end, %NULL will be returned and @error will be unset. - + A #GFileInfo or %NULL on error + filename="gio/gfileenumerator.c" + line="198">A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. @@ -54098,8 +57004,8 @@ be unset. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="182">a #GFileEnumerator. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="183">optional #GCancellable object, %NULL to ignore. - + Request information for a number of files from the enumerator asynchronously. + filename="gio/gfileenumerator.c" + line="313">Request information for a number of files from the enumerator asynchronously. When all I/O for the operation is finished the @callback will be called with the requested information. @@ -54180,27 +57088,27 @@ result in %G_IO_ERROR_PENDING errors. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. - + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="315">a #GFileEnumerator. the number of file info objects to request + filename="gio/gfileenumerator.c" + line="316">the number of file info objects to request the [I/O priority][io-priority] of the request + filename="gio/gfileenumerator.c" + line="317">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="318">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileenumerator.c" + line="319">a #GAsyncReadyCallback to call when the request is satisfied @@ -54230,8 +57138,8 @@ priority is %G_PRIORITY_DEFAULT. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfileenumerator.c" + line="321">the data to pass to callback function @@ -54240,13 +57148,13 @@ priority is %G_PRIORITY_DEFAULT. invoker="next_files_finish" throws="1"> Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). - + filename="gio/gfileenumerator.c" + line="440">Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). + a #GList of #GFileInfos. You must free the list with + filename="gio/gfileenumerator.c" + line="449">a #GList of #GFileInfos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. @@ -54256,39 +57164,42 @@ priority is %G_PRIORITY_DEFAULT. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="442">a #GFileEnumerator. a #GAsyncResult. + filename="gio/gfileenumerator.c" + line="443">a #GAsyncResult. - + Releases all resources used by this enumerator, making the + filename="gio/gfileenumerator.c" + line="249">Releases all resources used by this enumerator, making the enumerator return %G_IO_ERROR_CLOSED on all calls. This will be automatically called when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. - + #TRUE on success or #FALSE on error. + filename="gio/gfileenumerator.c" + line="262">#TRUE on success or #FALSE on error. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="251">a #GFileEnumerator. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="252">optional #GCancellable object, %NULL to ignore. - + Asynchronously closes the file enumerator. + filename="gio/gfileenumerator.c" + line="486">Asynchronously closes the file enumerator. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in g_file_enumerator_close_finish(). - + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="488">a #GFileEnumerator. the [I/O priority][io-priority] of the request + filename="gio/gfileenumerator.c" + line="489">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="490">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gfileenumerator.c" + line="491">a #GAsyncReadyCallback to call when the request is satisfied @@ -54354,8 +57268,8 @@ g_file_enumerator_close_finish(). nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfileenumerator.c" + line="493">the data to pass to callback function @@ -54364,8 +57278,8 @@ g_file_enumerator_close_finish(). c:identifier="g_file_enumerator_close_finish" throws="1"> Finishes closing a file enumerator, started from g_file_enumerator_close_async(). + filename="gio/gfileenumerator.c" + line="540">Finishes closing a file enumerator, started from g_file_enumerator_close_async(). If the file enumerator was already closed when g_file_enumerator_close_async() was called, then this function will report %G_IO_ERROR_CLOSED in @error, and @@ -54375,24 +57289,24 @@ return %FALSE. If @cancellable was not %NULL, then the operation may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be returned. - + %TRUE if the close operation has finished successfully. + filename="gio/gfileenumerator.c" + line="558">%TRUE if the close operation has finished successfully. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="542">a #GFileEnumerator. a #GAsyncResult. + filename="gio/gfileenumerator.c" + line="543">a #GAsyncResult. @@ -54401,8 +57315,8 @@ returned. c:identifier="g_file_enumerator_get_child" version="2.36"> Return a new #GFile which refers to the file named by @info in the source + filename="gio/gfileenumerator.c" + line="765">Return a new #GFile which refers to the file named by @info in the source directory of @enumerator. This function is primarily intended to be used inside loops with g_file_enumerator_next_file(). @@ -54415,24 +57329,24 @@ This is a convenience method that's equivalent to: GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), name); ]| - + a #GFile for the #GFileInfo passed it. + filename="gio/gfileenumerator.c" + line="785">a #GFile for the #GFileInfo passed it. a #GFileEnumerator + filename="gio/gfileenumerator.c" + line="767">a #GFileEnumerator a #GFileInfo gotten from g_file_enumerator_next_file() + filename="gio/gfileenumerator.c" + line="768">a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents. @@ -54442,60 +57356,60 @@ This is a convenience method that's equivalent to: c:identifier="g_file_enumerator_get_container" version="2.18"> Get the #GFile container which is being enumerated. - + filename="gio/gfileenumerator.c" + line="747">Get the #GFile container which is being enumerated. + the #GFile which is being enumerated. + filename="gio/gfileenumerator.c" + line="753">the #GFile which is being enumerated. a #GFileEnumerator + filename="gio/gfileenumerator.c" + line="749">a #GFileEnumerator Checks if the file enumerator has pending operations. - + filename="gio/gfileenumerator.c" + line="595">Checks if the file enumerator has pending operations. + %TRUE if the @enumerator has pending operations. + filename="gio/gfileenumerator.c" + line="601">%TRUE if the @enumerator has pending operations. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="597">a #GFileEnumerator. Checks if the file enumerator has been closed. - + filename="gio/gfileenumerator.c" + line="579">Checks if the file enumerator has been closed. + %TRUE if the @enumerator is closed. + filename="gio/gfileenumerator.c" + line="585">%TRUE if the @enumerator is closed. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="581">a #GFileEnumerator. @@ -54505,8 +57419,8 @@ This is a convenience method that's equivalent to: version="2.44" throws="1"> This is a version of g_file_enumerator_next_file() that's easier to + filename="gio/gfileenumerator.c" + line="627">This is a version of g_file_enumerator_next_file() that's easier to use correctly from C programs. With g_file_enumerator_next_file(), the gboolean return value signifies "end of iteration or error", which requires allocation of a temporary #GError. @@ -54544,15 +57458,15 @@ while (TRUE) out: g_object_unref (direnum); // Note: frees the last @info ]| - + an open #GFileEnumerator + filename="gio/gfileenumerator.c" + line="629">an open #GFileEnumerator Output location for the next #GFileInfo, or %NULL + filename="gio/gfileenumerator.c" + line="630">Output location for the next #GFileInfo, or %NULL Output location for the next #GFile, or %NULL + filename="gio/gfileenumerator.c" + line="631">Output location for the next #GFile, or %NULL a #GCancellable + filename="gio/gfileenumerator.c" + line="632">a #GCancellable @@ -54592,8 +57506,8 @@ out: c:identifier="g_file_enumerator_next_file" throws="1"> Returns information for the next file in the enumerated object. + filename="gio/gfileenumerator.c" + line="180">Returns information for the next file in the enumerated object. Will block until the information is available. The #GFileInfo returned from this function will contain attributes that match the attribute string that was passed when the #GFileEnumerator was created. @@ -54604,11 +57518,11 @@ order of returned files. On error, returns %NULL and sets @error to the error. If the enumerator is at the end, %NULL will be returned and @error will be unset. - + A #GFileInfo or %NULL on error + filename="gio/gfileenumerator.c" + line="198">A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. @@ -54616,8 +57530,8 @@ be unset. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="182">a #GFileEnumerator. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="183">optional #GCancellable object, %NULL to ignore. + c:identifier="g_file_enumerator_next_files_async" + glib:finish-func="next_files_finish"> Request information for a number of files from the enumerator asynchronously. + filename="gio/gfileenumerator.c" + line="313">Request information for a number of files from the enumerator asynchronously. When all I/O for the operation is finished the @callback will be called with the requested information. @@ -54699,27 +57614,27 @@ result in %G_IO_ERROR_PENDING errors. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. - + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="315">a #GFileEnumerator. the number of file info objects to request + filename="gio/gfileenumerator.c" + line="316">the number of file info objects to request the [I/O priority][io-priority] of the request + filename="gio/gfileenumerator.c" + line="317">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="318">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileenumerator.c" + line="319">a #GAsyncReadyCallback to call when the request is satisfied @@ -54748,8 +57663,8 @@ priority is %G_PRIORITY_DEFAULT. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfileenumerator.c" + line="321">the data to pass to callback function @@ -54758,13 +57673,13 @@ priority is %G_PRIORITY_DEFAULT. c:identifier="g_file_enumerator_next_files_finish" throws="1"> Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). - + filename="gio/gfileenumerator.c" + line="440">Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). + a #GList of #GFileInfos. You must free the list with + filename="gio/gfileenumerator.c" + line="449">a #GList of #GFileInfos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. @@ -54774,37 +57689,37 @@ priority is %G_PRIORITY_DEFAULT. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="442">a #GFileEnumerator. a #GAsyncResult. + filename="gio/gfileenumerator.c" + line="443">a #GAsyncResult. Sets the file enumerator as having pending operations. - + filename="gio/gfileenumerator.c" + line="611">Sets the file enumerator as having pending operations. + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="613">a #GFileEnumerator. a boolean value. + filename="gio/gfileenumerator.c" + line="614">a boolean value. @@ -54814,6 +57729,9 @@ priority is %G_PRIORITY_DEFAULT. writable="1" construct-only="1" transfer-ownership="none"> + The container that is being enumerated. @@ -54826,17 +57744,17 @@ priority is %G_PRIORITY_DEFAULT. - + - + A #GFileInfo or %NULL on error + filename="gio/gfileenumerator.c" + line="198">A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. @@ -54844,8 +57762,8 @@ priority is %G_PRIORITY_DEFAULT. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="182">a #GFileEnumerator. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="183">optional #GCancellable object, %NULL to ignore. @@ -54862,7 +57780,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -54881,27 +57799,27 @@ priority is %G_PRIORITY_DEFAULT. - + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="315">a #GFileEnumerator. the number of file info objects to request + filename="gio/gfileenumerator.c" + line="316">the number of file info objects to request the [I/O priority][io-priority] of the request + filename="gio/gfileenumerator.c" + line="317">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="318">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfileenumerator.c" + line="319">a #GAsyncReadyCallback to call when the request is satisfied @@ -54931,8 +57849,8 @@ priority is %G_PRIORITY_DEFAULT. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfileenumerator.c" + line="321">the data to pass to callback function @@ -54940,11 +57858,11 @@ priority is %G_PRIORITY_DEFAULT. - + a #GList of #GFileInfos. You must free the list with + filename="gio/gfileenumerator.c" + line="449">a #GList of #GFileInfos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. @@ -54954,14 +57872,14 @@ priority is %G_PRIORITY_DEFAULT. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="442">a #GFileEnumerator. a #GAsyncResult. + filename="gio/gfileenumerator.c" + line="443">a #GAsyncResult. @@ -54969,21 +57887,21 @@ priority is %G_PRIORITY_DEFAULT. - + a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="488">a #GFileEnumerator. the [I/O priority][io-priority] of the request + filename="gio/gfileenumerator.c" + line="489">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileenumerator.c" + line="490">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileenumerator.c" + line="491">a #GAsyncReadyCallback to call when the request is satisfied @@ -55013,8 +57931,8 @@ priority is %G_PRIORITY_DEFAULT. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfileenumerator.c" + line="493">the data to pass to callback function @@ -55022,24 +57940,24 @@ priority is %G_PRIORITY_DEFAULT. - + %TRUE if the close operation has finished successfully. + filename="gio/gfileenumerator.c" + line="558">%TRUE if the close operation has finished successfully. a #GFileEnumerator. + filename="gio/gfileenumerator.c" + line="542">a #GFileEnumerator. a #GAsyncResult. + filename="gio/gfileenumerator.c" + line="543">a #GAsyncResult. @@ -55047,7 +57965,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55055,7 +57973,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55063,7 +57981,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55071,7 +57989,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55079,7 +57997,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55087,7 +58005,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55095,7 +58013,7 @@ priority is %G_PRIORITY_DEFAULT. - + @@ -55106,7 +58024,7 @@ priority is %G_PRIORITY_DEFAULT. c:type="GFileEnumeratorPrivate" disguised="1" opaque="1"> - + glib:get-type="g_file_io_stream_get_type" glib:type-struct="FileIOStreamClass"> GFileIOStream provides io streams that both read and write to the same + filename="gio/gfileiostream.c" + line="36">`GFileIOStream` provides I/O streams that both read and write to the same file handle. -GFileIOStream implements #GSeekable, which allows the io +`GFileIOStream` implements [iface@Gio.Seekable], which allows the I/O stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. -To find the position of a file io stream, use -g_seekable_tell(). +To find the position of a file I/O stream, use [method@Gio.Seekable.tell]. -To find out if a file io stream supports seeking, use g_seekable_can_seek(). -To position a file io stream, use g_seekable_seek(). -To find out if a file io stream supports truncating, use -g_seekable_can_truncate(). To truncate a file io -stream, use g_seekable_truncate(). +To find out if a file I/O stream supports seeking, use +[method@Gio.Seekable.can_seek]. To position a file I/O stream, use +[method@Gio.Seekable.seek]. To find out if a file I/O stream supports +truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file I/O +stream, use [method@Gio.Seekable.truncate]. -The default implementation of all the #GFileIOStream operations -and the implementation of #GSeekable just call into the same operations -on the output stream. - +The default implementation of all the `GFileIOStream` operations +and the implementation of [iface@Gio.Seekable] just call into the same +operations on the output stream. + - + @@ -55152,7 +58069,7 @@ on the output stream. - + @@ -55164,22 +58081,22 @@ on the output stream. Gets the entity tag for the file when it has been written. + filename="gio/gfileiostream.c" + line="273">Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. + filename="gio/gfileiostream.c" + line="281">the entity tag for the stream. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="275">a #GFileIOStream. @@ -55187,10 +58104,11 @@ and closed, as the etag can change while writing. + throws="1" + glib:async-func="query_info_async"> Queries a file io stream for the given @attributes. + filename="gio/gfileiostream.c" + line="110">Queries a file io stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_io_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag @@ -55207,24 +58125,24 @@ If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. - + a #GFileInfo for the @stream, or %NULL on error. + filename="gio/gfileiostream.c" + line="135">a #GFileInfo for the @stream, or %NULL on error. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="112">a #GFileIOStream. a file attribute query string. + filename="gio/gfileiostream.c" + line="113">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileiostream.c" + line="114">optional #GCancellable object, %NULL to ignore. + version="2.22" + glib:finish-func="query_info_finish" + glib:sync-func="query_info"> Asynchronously queries the @stream for a #GFileInfo. When completed, + filename="gio/gfileiostream.c" + line="189">Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_io_stream_query_info_finish(). For the synchronous version of this function, see g_file_io_stream_query_info(). - + a #GFileIOStream. + filename="gio/gfileiostream.c" + line="191">a #GFileIOStream. a file attribute query string. + filename="gio/gfileiostream.c" + line="192">a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request + filename="gio/gfileiostream.c" + line="193">the [I/O priority](iface.AsyncResult.html#io-priority) of the + request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileiostream.c" + line="195">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileiostream.c" + line="196">a #GAsyncReadyCallback to call when the request is satisfied @@ -55299,8 +58220,8 @@ g_file_io_stream_query_info(). allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfileiostream.c" + line="198">the data to pass to callback function @@ -55310,33 +58231,33 @@ g_file_io_stream_query_info(). version="2.22" throws="1"> Finalizes the asynchronous query started + filename="gio/gfileiostream.c" + line="241">Finalizes the asynchronous query started by g_file_io_stream_query_info_async(). - + A #GFileInfo for the finished query. + filename="gio/gfileiostream.c" + line="250">A #GFileInfo for the finished query. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="243">a #GFileIOStream. a #GAsyncResult. + filename="gio/gfileiostream.c" + line="244">a #GAsyncResult. - + @@ -55359,7 +58280,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55370,7 +58291,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55393,22 +58314,22 @@ by g_file_io_stream_query_info_async(). c:identifier="g_file_io_stream_get_etag" version="2.22"> Gets the entity tag for the file when it has been written. + filename="gio/gfileiostream.c" + line="273">Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. + filename="gio/gfileiostream.c" + line="281">the entity tag for the stream. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="275">a #GFileIOStream. @@ -55416,10 +58337,11 @@ and closed, as the etag can change while writing. + throws="1" + glib:async-func="query_info_async"> Queries a file io stream for the given @attributes. + filename="gio/gfileiostream.c" + line="110">Queries a file io stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_io_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag @@ -55436,24 +58358,24 @@ If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. - + a #GFileInfo for the @stream, or %NULL on error. + filename="gio/gfileiostream.c" + line="135">a #GFileInfo for the @stream, or %NULL on error. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="112">a #GFileIOStream. a file attribute query string. + filename="gio/gfileiostream.c" + line="113">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileiostream.c" + line="114">optional #GCancellable object, %NULL to ignore. + version="2.22" + glib:finish-func="query_info_finish" + glib:sync-func="query_info"> Asynchronously queries the @stream for a #GFileInfo. When completed, + filename="gio/gfileiostream.c" + line="189">Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_io_stream_query_info_finish(). For the synchronous version of this function, see g_file_io_stream_query_info(). - + a #GFileIOStream. + filename="gio/gfileiostream.c" + line="191">a #GFileIOStream. a file attribute query string. + filename="gio/gfileiostream.c" + line="192">a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request + filename="gio/gfileiostream.c" + line="193">the [I/O priority](iface.AsyncResult.html#io-priority) of the + request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileiostream.c" + line="195">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileiostream.c" + line="196">a #GAsyncReadyCallback to call when the request is satisfied @@ -55527,8 +58452,8 @@ g_file_io_stream_query_info(). nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfileiostream.c" + line="198">the data to pass to callback function @@ -55538,27 +58463,27 @@ g_file_io_stream_query_info(). version="2.22" throws="1"> Finalizes the asynchronous query started + filename="gio/gfileiostream.c" + line="241">Finalizes the asynchronous query started by g_file_io_stream_query_info_async(). - + A #GFileInfo for the finished query. + filename="gio/gfileiostream.c" + line="250">A #GFileInfo for the finished query. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="243">a #GFileIOStream. a #GAsyncResult. + filename="gio/gfileiostream.c" + line="244">a #GAsyncResult. @@ -55573,13 +58498,13 @@ by g_file_io_stream_query_info_async(). - + - + @@ -55592,7 +58517,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55605,7 +58530,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55630,7 +58555,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55643,7 +58568,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55665,24 +58590,24 @@ by g_file_io_stream_query_info_async(). - + a #GFileInfo for the @stream, or %NULL on error. + filename="gio/gfileiostream.c" + line="135">a #GFileInfo for the @stream, or %NULL on error. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="112">a #GFileIOStream. a file attribute query string. + filename="gio/gfileiostream.c" + line="113">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileiostream.c" + line="114">optional #GCancellable object, %NULL to ignore. @@ -55699,27 +58624,28 @@ by g_file_io_stream_query_info_async(). - + a #GFileIOStream. + filename="gio/gfileiostream.c" + line="191">a #GFileIOStream. a file attribute query string. + filename="gio/gfileiostream.c" + line="192">a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request + filename="gio/gfileiostream.c" + line="193">the [I/O priority](iface.AsyncResult.html#io-priority) of the + request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileiostream.c" + line="195">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfileiostream.c" + line="196">a #GAsyncReadyCallback to call when the request is satisfied @@ -55749,8 +58675,8 @@ by g_file_io_stream_query_info_async(). allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfileiostream.c" + line="198">the data to pass to callback function @@ -55758,24 +58684,24 @@ by g_file_io_stream_query_info_async(). - + A #GFileInfo for the finished query. + filename="gio/gfileiostream.c" + line="250">A #GFileInfo for the finished query. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="243">a #GFileIOStream. a #GAsyncResult. + filename="gio/gfileiostream.c" + line="244">a #GAsyncResult. @@ -55783,18 +58709,18 @@ by g_file_io_stream_query_info_async(). - + the entity tag for the stream. + filename="gio/gfileiostream.c" + line="281">the entity tag for the stream. a #GFileIOStream. + filename="gio/gfileiostream.c" + line="275">a #GFileIOStream. @@ -55802,7 +58728,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55810,7 +58736,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55818,7 +58744,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55826,7 +58752,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55834,7 +58760,7 @@ by g_file_io_stream_query_info_async(). - + @@ -55845,7 +58771,7 @@ by g_file_io_stream_query_info_async(). c:type="GFileIOStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_file_icon_get_type" glib:type-struct="FileIconClass"> #GFileIcon specifies an icon by pointing to an image file -to be used as icon. - + filename="gio/gfileicon.c" + line="35">`GFileIcon` specifies an icon by pointing to an image file +to be used as icon. + +It implements [iface@Gio.LoadableIcon]. + Creates a new icon for a file. - + filename="gio/gfileicon.c" + line="166">Creates a new icon for a file. + a #GIcon for the given + filename="gio/gfileicon.c" + line="172">a #GIcon for the given @file, or %NULL on error. a #GFile. + filename="gio/gfileicon.c" + line="168">a #GFile. @@ -55886,20 +58814,20 @@ to be used as icon. c:identifier="g_file_icon_get_file" glib:get-property="file"> Gets the #GFile associated with the given @icon. - + filename="gio/gfileicon.c" + line="183">Gets the #GFile associated with the given @icon. + a #GFile. + filename="gio/gfileicon.c" + line="189">a #GFile. a #GIcon. + filename="gio/gfileicon.c" + line="185">a #GIcon. @@ -55910,8 +58838,8 @@ to be used as icon. transfer-ownership="none" getter="get_file"> The file containing the icon. + filename="gio/gfileicon.c" + line="150">The file containing the icon. @@ -55920,48 +58848,54 @@ to be used as icon. disguised="1" opaque="1" glib:is-gtype-struct-for="FileIcon"> - + An interface for writing VFS file handles. - + filename="gio/gfile.h" + line="42">An interface for writing VFS file handles. + The parent interface. + filename="gio/gfile.h" + line="44">The parent interface. + Duplicates a #GFile. - + a new #GFile that is a duplicate + filename="gio/gfile.c" + line="739">a new #GFile that is a duplicate of the given #GFile. input #GFile + filename="gio/gfile.c" + line="726">input #GFile + Creates a hash of a #GFile. - + 0 if @file is not a valid #GFile, otherwise an + filename="gio/gfile.c" + line="762">0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. @@ -55970,64 +58904,73 @@ to be used as icon. #gconstpointer to a #GFile + filename="gio/gfile.c" + line="756">#gconstpointer to a #GFile + Checks equality of two given #GFiles. - + %TRUE if @file1 and @file2 are equal. + filename="gio/gfile.c" + line="792">%TRUE if @file1 and @file2 are equal. the first #GFile + filename="gio/gfile.c" + line="781">the first #GFile the second #GFile + filename="gio/gfile.c" + line="782">the second #GFile + Checks to see if a file is native to the system. - + %TRUE if @file is native + filename="gio/gfile.c" + line="460">%TRUE if @file is native input #GFile + filename="gio/gfile.c" + line="446">input #GFile + Checks to see if a #GFile has a given URI scheme. - + %TRUE if #GFile's backend supports the + filename="gio/gfile.c" + line="484">%TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. @@ -56035,26 +58978,29 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="477">input #GFile a string containing a URI scheme + filename="gio/gfile.c" + line="478">a string containing a URI scheme + Gets the URI scheme for a #GFile. - + a string containing the URI scheme for the given + filename="gio/gfile.c" + line="519">a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. @@ -56062,20 +59008,23 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="505">input #GFile + Gets the basename for a given #GFile. - + string containing the #GFile's + filename="gio/gfile.c" + line="554">string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. @@ -56083,20 +59032,23 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="538">input #GFile + Gets the current path within a #GFile. - + string containing the #GFile's path, + filename="gio/gfile.c" + line="579">string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. @@ -56104,20 +59056,23 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="572">input #GFile + Gets a URI for the path within a #GFile. - + a string containing the #GFile's URI. If the #GFile was constructed + filename="gio/gfile.c" + line="672">a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. @@ -56126,20 +59081,23 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="666">input #GFile + Gets the parsed name for the #GFile. - + a string containing the #GFile's parse name. + filename="gio/gfile.c" + line="708">a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. @@ -56147,20 +59105,23 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="691">input #GFile + Gets the parent directory for the #GFile. - + a #GFile structure to the + filename="gio/gfile.c" + line="825">a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). @@ -56168,46 +59129,52 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="817">input #GFile + Checks whether a #GFile contains a specified file. - + %TRUE if the @file's parent, grandparent, etc is @prefix, + filename="gio/gfile.c" + line="965">%TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="948">input #GFile input #GFile + filename="gio/gfile.c" + line="947">input #GFile + Gets the path for a #GFile relative to a given path. - + string with the relative path from + filename="gio/gfile.c" + line="997">string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. @@ -56216,51 +59183,57 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="990">input #GFile input #GFile + filename="gio/gfile.c" + line="991">input #GFile + Resolves a relative path for a #GFile to an absolute path. - + a #GFile for the resolved path. + filename="gio/gfile.c" + line="1031">a #GFile for the resolved path. input #GFile + filename="gio/gfile.c" + line="1021">input #GFile a given relative path string + filename="gio/gfile.c" + line="1022">a given relative path string + Gets the child #GFile for a given display name. - + a #GFile to the specified child, or + filename="gio/gfile.c" + line="926">a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). @@ -56268,46 +59241,49 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="913">input #GFile string to a possible child + filename="gio/gfile.c" + line="914">string to a possible child + Gets a #GFileEnumerator with the children of a #GFile. - + A #GFileEnumerator if successful, + filename="gio/gfile.c" + line="1082">A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1049">input #GFile an attribute query string + filename="gio/gfile.c" + line="1050">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1051">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1052">optional #GCancellable object, %NULL to ignore @@ -56324,34 +59300,37 @@ to be used as icon. + Asynchronously gets a #GFileEnumerator with the children of a #GFile. - + input #GFile + filename="gio/gfile.c" + line="1115">input #GFile an attribute query string + filename="gio/gfile.c" + line="1116">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1117">a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1118">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1119">optional #GCancellable object, %NULL to ignore @@ -56371,8 +59350,8 @@ to be used as icon. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1121">a #GAsyncReadyCallback to call when the request is satisfied @@ -56382,20 +59361,23 @@ to be used as icon. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/gfile.c" + line="1123">the data to pass to callback function + Finishes asynchronously enumerating the children. - + a #GFileEnumerator or %NULL + filename="gio/gfile.c" + line="1168">a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). @@ -56403,46 +59385,49 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="1161">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1162">a #GAsyncResult + Gets the #GFileInfo for a #GFile. - + a #GFileInfo for the given @file, or %NULL + filename="gio/gfile.c" + line="1329">a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1291">input #GFile an attribute query string + filename="gio/gfile.c" + line="1292">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1293">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1294">optional #GCancellable object, %NULL to ignore @@ -56459,34 +59444,37 @@ to be used as icon. + Asynchronously gets the #GFileInfo for a #GFile. - + input #GFile + filename="gio/gfile.c" + line="1361">input #GFile an attribute query string + filename="gio/gfile.c" + line="1362">an attribute query string a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="1363">a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1364">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1365">optional #GCancellable object, %NULL to ignore @@ -56506,8 +59494,8 @@ to be used as icon. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1367">a #GAsyncReadyCallback to call when the request is satisfied @@ -56517,20 +59505,23 @@ to be used as icon. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/gfile.c" + line="1369">the data to pass to callback function + Finishes an asynchronous query info operation. - + #GFileInfo for given @file + filename="gio/gfile.c" + line="1413">#GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). @@ -56538,40 +59529,43 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="1406">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1407">a #GAsyncResult + Gets a #GFileInfo for the file system #GFile is on. - + a #GFileInfo or %NULL if there was an error. + filename="gio/gfile.c" + line="1468">a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1436">input #GFile an attribute query string + filename="gio/gfile.c" + line="1437">an attribute query string nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1438">optional #GCancellable object, %NULL to ignore @@ -56588,28 +59582,31 @@ to be used as icon. + Asynchronously gets a #GFileInfo for the file system #GFile is on. - + input #GFile + filename="gio/gfile.c" + line="1499">input #GFile an attribute query string + filename="gio/gfile.c" + line="1500">an attribute query string the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1501">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1502">optional #GCancellable object, %NULL to ignore @@ -56629,8 +59626,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1504">a #GAsyncReadyCallback to call when the request is satisfied @@ -56640,20 +59637,23 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="1506">the data to pass to callback function + Finishes asynchronously getting the file system info. - + #GFileInfo for given @file + filename="gio/gfile.c" + line="1550">#GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). @@ -56661,26 +59661,29 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="1543">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1544">a #GAsyncResult + Gets a #GMount for the #GFile. - + a #GMount where the @file is located + filename="gio/gfile.c" + line="1588">a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). @@ -56688,8 +59691,8 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="1573">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1574">optional #GCancellable object, %NULL to ignore @@ -56706,22 +59709,25 @@ to be used as icon. + Asynchronously gets the #GMount for a #GFile. - + a #GFile + filename="gio/gfile.c" + line="1622">a #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="1623">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1624">optional #GCancellable object, %NULL to ignore @@ -56741,8 +59747,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="1626">a #GAsyncReadyCallback to call when the request is satisfied @@ -56752,46 +59758,52 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="1628">the data to pass to callback function + Finishes asynchronously getting the volume. - + #GMount for given @file or %NULL on error. + filename="gio/gfile.c" + line="1667">#GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). a #GFile + filename="gio/gfile.c" + line="1660">a #GFile a #GAsyncResult + filename="gio/gfile.c" + line="1661">a #GAsyncResult + Sets the display name for a #GFile. - + a #GFile specifying what @file was renamed to, + filename="gio/gfile.c" + line="4878">a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). @@ -56799,14 +59811,14 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="4856">input #GFile a string + filename="gio/gfile.c" + line="4857">a string nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4858">optional #GCancellable object, %NULL to ignore @@ -56823,28 +59835,31 @@ to be used as icon. + Asynchronously sets a #GFile's display name. - + input #GFile + filename="gio/gfile.c" + line="4912">input #GFile a string + filename="gio/gfile.c" + line="4913">a string the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4914">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4915">optional #GCancellable object, %NULL to ignore @@ -56864,8 +59879,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="4917">a #GAsyncReadyCallback to call when the request is satisfied @@ -56875,46 +59890,52 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="4919">the data to pass to callback function + Finishes asynchronously setting a #GFile's display name. - + a #GFile or %NULL on error. + filename="gio/gfile.c" + line="4961">a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="4954">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4955">a #GAsyncResult + Returns a list of #GFileAttributeInfos that can be set. - + a #GFileAttributeInfoList describing the settable attributes. + filename="gio/gfile.c" + line="4999">a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile + filename="gio/gfile.c" + line="4983">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4984">optional #GCancellable object, %NULL to ignore @@ -56941,28 +59962,37 @@ to be used as icon. + Asynchronously gets a list of #GFileAttributeInfos that can be set. - + + Finishes asynchronously querying settable attributes. - + + Returns a list of #GFileAttributeInfo namespaces that are writable. - + a #GFileAttributeInfoList describing the writable namespaces. + filename="gio/gfile.c" + line="5054">a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() input #GFile + filename="gio/gfile.c" + line="5041">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5042">optional #GCancellable object, %NULL to ignore @@ -56989,47 +60019,56 @@ to be used as icon. + Asynchronously gets a list of #GFileAttributeInfo namespaces that are writable. - + + Finishes asynchronously querying the writable namespaces. - + + Sets a #GFileAttributeInfo. - + %TRUE if the attribute was set, %FALSE otherwise. + filename="gio/gfile.c" + line="5120">%TRUE if the attribute was set, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5101">input #GFile a string containing the attribute's name + filename="gio/gfile.c" + line="5102">a string containing the attribute's name The type of the attribute + filename="gio/gfile.c" + line="5103">The type of the attribute nullable="1" allow-none="1"> a pointer to the value (or the pointer + filename="gio/gfile.c" + line="5104">a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5106">a set of #GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5107">optional #GCancellable object, %NULL to ignore @@ -57062,31 +60101,34 @@ to be used as icon. + Sets a #GFileAttributeInfo with information from a #GFileInfo. - + %FALSE if there was any error, %TRUE otherwise. + filename="gio/gfile.c" + line="5174">%FALSE if there was any error, %TRUE otherwise. input #GFile + filename="gio/gfile.c" + line="5154">input #GFile a #GFileInfo + filename="gio/gfile.c" + line="5155">a #GFileInfo #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5156">#GFileQueryInfoFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5157">optional #GCancellable object, %NULL to ignore @@ -57103,34 +60145,37 @@ to be used as icon. + Asynchronously sets a file's attributes. - + input #GFile + filename="gio/gfile.c" + line="5245">input #GFile a #GFileInfo + filename="gio/gfile.c" + line="5246">a #GFileInfo a #GFileQueryInfoFlags + filename="gio/gfile.c" + line="5247">a #GFileQueryInfoFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="5248">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5249">optional #GCancellable object, %NULL to ignore @@ -57150,8 +60195,8 @@ to be used as icon. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5251">a #GAsyncReadyCallback to call when the request is satisfied @@ -57161,33 +60206,36 @@ to be used as icon. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/gfile.c" + line="5253">the data to pass to callback function + Finishes setting a file's attributes asynchronously. - + %TRUE if the attributes were set correctly, %FALSE otherwise. + filename="gio/gfile.c" + line="5297">%TRUE if the attributes were set correctly, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5290">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5291">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> a #GFileInfo + filename="gio/gfile.c" + line="5292">a #GFileInfo + Reads a file asynchronously. - + #GFileInputStream or %NULL on error. + filename="gio/gfile.c" + line="1706">#GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to read + filename="gio/gfile.c" + line="1690">#GFile to read nullable="1" allow-none="1"> a #GCancellable + filename="gio/gfile.c" + line="1691">a #GCancellable + Asynchronously reads a file. - + input #GFile + filename="gio/gfile.c" + line="2109">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2110">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2111">optional #GCancellable object, %NULL to ignore @@ -57267,8 +60321,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2113">a #GAsyncReadyCallback to call when the request is satisfied @@ -57278,60 +60332,66 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="2115">the data to pass to callback function + Finishes asynchronously reading a file. - + a #GFileInputStream or %NULL on error. + filename="gio/gfile.c" + line="2154">a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2147">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2148">a #GAsyncResult + Writes to the end of a file. - + a #GFileOutputStream, or %NULL on error. + filename="gio/gfile.c" + line="1760">a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1736">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1737">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1738">optional #GCancellable object, %NULL to ignore @@ -57348,28 +60408,31 @@ to be used as icon. + Asynchronously writes to the end of a file. - + input #GFile + filename="gio/gfile.c" + line="2176">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2177">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2178">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2179">optional #GCancellable object, %NULL to ignore @@ -57389,8 +60452,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2181">a #GAsyncReadyCallback to call when the request is satisfied @@ -57400,20 +60463,23 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="2183">the data to pass to callback function + Finishes an asynchronous file append operation. - + a valid #GFileOutputStream + filename="gio/gfile.c" + line="2224">a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). @@ -57421,26 +60487,29 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="2217">input #GFile #GAsyncResult + filename="gio/gfile.c" + line="2218">#GAsyncResult + Creates a new file. - + a #GFileOutputStream for the newly created + filename="gio/gfile.c" + line="1817">a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). @@ -57448,14 +60517,14 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="1791">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1792">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1793">optional #GCancellable object, %NULL to ignore @@ -57472,28 +60541,31 @@ to be used as icon. + Asynchronously creates a file. - + input #GFile + filename="gio/gfile.c" + line="2247">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2248">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2249">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2250">optional #GCancellable object, %NULL to ignore @@ -57513,8 +60585,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2252">a #GAsyncReadyCallback to call when the request is satisfied @@ -57524,54 +60596,60 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="2254">the data to pass to callback function + Finishes asynchronously creating a file. - + a #GFileOutputStream or %NULL on error. + filename="gio/gfile.c" + line="2296">a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2289">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2290">a #GAsyncResult + Replaces the contents of a file. - + a #GFileOutputStream or %NULL on error. + filename="gio/gfile.c" + line="1900">a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="1849">input #GFile nullable="1" allow-none="1"> an optional [entity tag][gfile-etag] + filename="gio/gfile.c" + line="1850">an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="1852">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1853">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1854">optional #GCancellable object, %NULL to ignore @@ -57610,16 +60688,19 @@ to be used as icon. + Asynchronously replaces the contents of a file. - + input #GFile + filename="gio/gfile.c" + line="2318">input #GFile nullable="1" allow-none="1"> an [entity tag][gfile-etag] for the current #GFile, + filename="gio/gfile.c" + line="2319">an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2321">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2322">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2323">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2324">optional #GCancellable object, %NULL to ignore @@ -57667,8 +60748,8 @@ to be used as icon. scope="async" closure="7"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2326">a #GAsyncReadyCallback to call when the request is satisfied @@ -57678,53 +60759,59 @@ to be used as icon. allow-none="1" closure="7"> the data to pass to callback function + filename="gio/gfile.c" + line="2328">the data to pass to callback function + Finishes asynchronously replacing a file. - + a #GFileOutputStream, or %NULL on error. + filename="gio/gfile.c" + line="2374">a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2367">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2368">a #GAsyncResult + Deletes a file. - + %TRUE if the file was deleted. %FALSE otherwise. + filename="gio/gfile.c" + line="4657">%TRUE if the file was deleted. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4630">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4631">optional #GCancellable object, %NULL to ignore @@ -57741,22 +60828,25 @@ to be used as icon. + Asynchronously deletes a file. - + input #GFile + filename="gio/gfile.c" + line="4686">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4687">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4688">optional #GCancellable object, %NULL to ignore @@ -57776,8 +60866,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4690">a #GAsyncReadyCallback to call when the request is satisfied @@ -57787,52 +60877,58 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="4692">the data to pass to callback function + Finishes an asynchronous delete. - + %TRUE if the file was deleted. %FALSE otherwise. + filename="gio/gfile.c" + line="4727">%TRUE if the file was deleted. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4721">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4722">a #GAsyncResult + Sends a #GFile to the Trash location. - + %TRUE on successful trash, %FALSE otherwise. + filename="gio/gfile.c" + line="4768">%TRUE on successful trash, %FALSE otherwise. #GFile to send to trash + filename="gio/gfile.c" + line="4749">#GFile to send to trash nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4750">optional #GCancellable object, %NULL to ignore @@ -57849,22 +60945,25 @@ to be used as icon. + Asynchronously sends a #GFile to the Trash location. - + input #GFile + filename="gio/gfile.c" + line="4797">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4798">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4799">optional #GCancellable object, %NULL to ignore @@ -57884,8 +60983,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4801">a #GAsyncReadyCallback to call when the request is satisfied @@ -57895,52 +60994,58 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="4803">the data to pass to callback function + Finishes an asynchronous file trashing operation. - + %TRUE on successful trash, %FALSE otherwise. + filename="gio/gfile.c" + line="4837">%TRUE on successful trash, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4830">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4831">a #GAsyncResult + Makes a directory. - + %TRUE on successful creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4250">%TRUE on successful creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4230">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4231">optional #GCancellable object, %NULL to ignore @@ -57957,22 +61062,25 @@ to be used as icon. + Asynchronously makes a directory. - + input #GFile + filename="gio/gfile.c" + line="4279">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4280">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4281">optional #GCancellable object, %NULL to ignore @@ -57992,8 +61100,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4283">a #GAsyncReadyCallback to call when the request is satisfied @@ -58003,58 +61111,65 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="4285">the data to pass to callback function + Finishes making a directory asynchronously. - + %TRUE on successful directory creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4319">%TRUE on successful directory creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4312">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4313">a #GAsyncResult + Makes a symbolic link. %NULL if symbolic + links are unsupported. - + %TRUE on the creation of a new symlink, %FALSE otherwise. + filename="gio/gfile.c" + line="4474">%TRUE on the creation of a new symlink, %FALSE otherwise. a #GFile with the name of the symlink to create + filename="gio/gfile.c" + line="4460">a #GFile with the name of the symlink to create a string with the path for the target + filename="gio/gfile.c" + line="4461">a string with the path for the target of the new symlink @@ -58063,8 +61178,8 @@ to be used as icon. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4463">optional #GCancellable object, %NULL to ignore @@ -58072,29 +61187,32 @@ to be used as icon. + Asynchronously makes a symbolic link - + a #GFile with the name of the symlink to create + filename="gio/gfile.c" + line="4551">a #GFile with the name of the symlink to create a string with the path for the target + filename="gio/gfile.c" + line="4552">a string with the path for the target of the new symlink the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4554">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4555">optional #GCancellable object, %NULL to ignore @@ -58114,8 +61232,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="4557">a #GAsyncReadyCallback to call when the request is satisfied @@ -58125,64 +61243,72 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="4559">the data to pass to callback function + Finishes making a symbolic link asynchronously. - + %TRUE on successful directory creation, %FALSE otherwise. + filename="gio/gfile.c" + line="4608">%TRUE on successful directory creation, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="4601">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4602">a #GAsyncResult + Copies a file. %NULL if copying is unsupported, which will + cause `GFile` to use a fallback copy method where it reads from the + source and writes to the destination. - + %TRUE on success, %FALSE otherwise. + filename="gio/gfile.c" + line="3700">%TRUE on success, %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="3649">input #GFile destination #GFile + filename="gio/gfile.c" + line="3650">destination #GFile set of #GFileCopyFlags + filename="gio/gfile.c" + line="3651">set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3652">optional #GCancellable object, %NULL to ignore @@ -58202,8 +61328,8 @@ to be used as icon. scope="call" closure="5"> function to callback with + filename="gio/gfile.c" + line="3654">function to callback with progress information, or %NULL if progress information is not needed @@ -58213,42 +61339,45 @@ to be used as icon. nullable="1" allow-none="1"> user data to pass to @progress_callback + filename="gio/gfile.c" + line="3656">user data to pass to @progress_callback + Asynchronously copies a file. - + input #GFile + filename="gio/gfile.c" + line="3777">input #GFile destination #GFile + filename="gio/gfile.c" + line="3778">destination #GFile set of #GFileCopyFlags + filename="gio/gfile.c" + line="3779">set of #GFileCopyFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="3780">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3781">optional #GCancellable object, %NULL to ignore @@ -58268,8 +61397,8 @@ to be used as icon. scope="notified" closure="6"> + filename="gio/gfile.c" + line="3783"> function to callback with progress information, or %NULL if progress information is not needed nullable="1" allow-none="1"> user data to pass to @progress_callback + filename="gio/gfile.c" + line="3786">user data to pass to @progress_callback scope="async" closure="8"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="3787">a #GAsyncReadyCallback to call when the request is satisfied @@ -58302,64 +61431,70 @@ to be used as icon. allow-none="1" closure="8"> the data to pass to callback + filename="gio/gfile.c" + line="3789">the data to pass to callback + Finishes an asynchronous copy operation. - + a %TRUE on success, %FALSE on error. + filename="gio/gfile.c" + line="3955">a %TRUE on success, %FALSE on error. input #GFile + filename="gio/gfile.c" + line="3949">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="3950">a #GAsyncResult + Moves a file. - + %TRUE on successful move, %FALSE otherwise. + filename="gio/gfile.c" + line="4021">%TRUE on successful move, %FALSE otherwise. #GFile pointing to the source location + filename="gio/gfile.c" + line="3976">#GFile pointing to the source location #GFile pointing to the destination location + filename="gio/gfile.c" + line="3977">#GFile pointing to the destination location set of #GFileCopyFlags + filename="gio/gfile.c" + line="3978">set of #GFileCopyFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="3979">optional #GCancellable object, %NULL to ignore @@ -58379,8 +61514,8 @@ to be used as icon. scope="call" closure="5"> #GFileProgressCallback + filename="gio/gfile.c" + line="3981">#GFileProgressCallback function for updates @@ -58390,8 +61525,8 @@ to be used as icon. nullable="1" allow-none="1"> gpointer to user data for + filename="gio/gfile.c" + line="3983">gpointer to user data for the callback function @@ -58399,34 +61534,37 @@ to be used as icon. + Asynchronously moves a file. Since: 2.72 - + #GFile pointing to the source location + filename="gio/gfile.c" + line="4110">#GFile pointing to the source location #GFile pointing to the destination location + filename="gio/gfile.c" + line="4111">#GFile pointing to the destination location set of #GFileCopyFlags + filename="gio/gfile.c" + line="4112">set of #GFileCopyFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="4113">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="4114">optional #GCancellable object, %NULL to ignore @@ -58446,8 +61584,8 @@ to be used as icon. scope="call" closure="6"> + filename="gio/gfile.c" + line="4116"> #GFileProgressCallback function for updates @@ -58457,8 +61595,8 @@ to be used as icon. nullable="1" allow-none="1"> gpointer to user data for the callback function + filename="gio/gfile.c" + line="4118">gpointer to user data for the callback function scope="async" closure="8"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="4119">a #GAsyncReadyCallback to call when the request is satisfied @@ -58479,55 +61617,61 @@ to be used as icon. allow-none="1" closure="8"> the data to pass to callback function + filename="gio/gfile.c" + line="4121">the data to pass to callback function + Finishes an asynchronous move operation. Since: 2.72 - + %TRUE on successful file move, %FALSE otherwise. + filename="gio/gfile.c" + line="4209">%TRUE on successful file move, %FALSE otherwise. input source #GFile + filename="gio/gfile.c" + line="4202">input source #GFile a #GAsyncResult + filename="gio/gfile.c" + line="4203">a #GAsyncResult + Mounts a mountable object. - + input #GFile + filename="gio/gfile.c" + line="5516">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5517">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5518">a #GMountOperation, or %NULL to avoid user interaction @@ -58545,8 +61689,8 @@ to be used as icon. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5520">optional #GCancellable object, %NULL to ignore @@ -58557,8 +61701,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5522">a #GAsyncReadyCallback to call when the request is satisfied @@ -58568,56 +61712,62 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="5524">the data to pass to callback function + Finishes a mounting operation. - + a #GFile or %NULL on error. + filename="gio/gfile.c" + line="5580">a #GFile or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="5571">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5572">a #GAsyncResult + Unmounts a mountable object. - + input #GFile + filename="gio/gfile.c" + line="5604">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5605">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5606">optional #GCancellable object, %NULL to ignore @@ -58637,8 +61787,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5608">a #GAsyncReadyCallback to call when the request is satisfied @@ -58648,56 +61798,62 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="5610">the data to pass to callback function + Finishes an unmount operation. - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="5664">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5655">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5656">a #GAsyncResult + Ejects a mountable. - + input #GFile + filename="gio/gfile.c" + line="5792">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5793">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5794">optional #GCancellable object, %NULL to ignore @@ -58717,8 +61873,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5796">a #GAsyncReadyCallback to call when the request is satisfied @@ -58728,56 +61884,62 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="5798">the data to pass to callback function + Finishes an eject operation. - + %TRUE if the @file was ejected successfully. + filename="gio/gfile.c" + line="5849">%TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5842">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5843">a #GAsyncResult + Mounts a specified location. - + input #GFile + filename="gio/gfile.c" + line="7728">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="7729">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation + filename="gio/gfile.c" + line="7730">a #GMountOperation or %NULL to avoid user interaction @@ -58795,8 +61957,8 @@ to be used as icon. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="7732">optional #GCancellable object, %NULL to ignore @@ -58807,8 +61969,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="7734">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -58818,20 +61980,23 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="7736">the data to pass to callback function + Finishes mounting a specified location. - + %TRUE if successful. If an error has occurred, + filename="gio/gfile.c" + line="7784">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -58839,41 +62004,43 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="7778">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="7779">a #GAsyncResult + Creates a #GFileMonitor for the location. - + a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). + filename="gio/gfile.c" + line="5992">a #GFileMonitor for the given @file, + or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="5973">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="5974">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5975">optional #GCancellable object, %NULL to ignore @@ -58890,12 +62057,15 @@ to be used as icon. + Creates a #GFileMonitor for the location. - + a #GFileMonitor for the given @file, + filename="gio/gfile.c" + line="6045">a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). @@ -58903,14 +62073,14 @@ to be used as icon. input #GFile + filename="gio/gfile.c" + line="6024">input #GFile a set of #GFileMonitorFlags + filename="gio/gfile.c" + line="6025">a set of #GFileMonitorFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="6026">optional #GCancellable object, %NULL to ignore @@ -58927,20 +62097,23 @@ to be used as icon. + Open file read/write. Since 2.22. - + #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="1958">#GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). #GFile to open + filename="gio/gfile.c" + line="1937">#GFile to open nullable="1" allow-none="1"> a #GCancellable + filename="gio/gfile.c" + line="1938">a #GCancellable + Asynchronously opens file read/write. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="2396">input #GFile the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2397">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2398">optional #GCancellable object, %NULL to ignore @@ -58991,8 +62167,8 @@ to be used as icon. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2400">a #GAsyncReadyCallback to call when the request is satisfied @@ -59002,46 +62178,52 @@ to be used as icon. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfile.c" + line="2402">the data to pass to callback function + Finishes an asynchronous open read/write. Since 2.22. - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2443">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2436">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2437">a #GAsyncResult + Creates file read/write. Since 2.22. - + a #GFileIOStream for the newly created + filename="gio/gfile.c" + line="2020">a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). @@ -59049,14 +62231,14 @@ to be used as icon. a #GFile + filename="gio/gfile.c" + line="1990">a #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="1991">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="1992">optional #GCancellable object, %NULL to ignore @@ -59073,28 +62255,31 @@ to be used as icon. + Asynchronously creates file read/write. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="2467">input #GFile a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2468">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2469">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2470">optional #GCancellable object, %NULL to ignore @@ -59114,8 +62299,8 @@ to be used as icon. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2472">a #GAsyncReadyCallback to call when the request is satisfied @@ -59125,54 +62310,60 @@ to be used as icon. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="2474">the data to pass to callback function + Finishes an asynchronous creates read/write. Since 2.22. - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2518">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2511">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2512">a #GAsyncResult + Replaces file read/write. Since 2.22. - + a #GFileIOStream or %NULL on error. + filename="gio/gfile.c" + line="2074">a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). a #GFile + filename="gio/gfile.c" + line="2054">a #GFile nullable="1" allow-none="1"> an optional [entity tag][gfile-etag] + filename="gio/gfile.c" + line="2055">an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2057">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2058">a set of #GFileCreateFlags nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2059">optional #GCancellable object, %NULL to ignore @@ -59211,16 +62402,19 @@ to be used as icon. + Asynchronously replaces file read/write. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="2542">input #GFile nullable="1" allow-none="1"> an [entity tag][gfile-etag] for the current #GFile, + filename="gio/gfile.c" + line="2543">an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore %TRUE if a backup should be created + filename="gio/gfile.c" + line="2545">%TRUE if a backup should be created a set of #GFileCreateFlags + filename="gio/gfile.c" + line="2546">a set of #GFileCreateFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="2547">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="2548">optional #GCancellable object, %NULL to ignore @@ -59268,8 +62462,8 @@ to be used as icon. scope="async" closure="7"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="2550">a #GAsyncReadyCallback to call when the request is satisfied @@ -59279,56 +62473,62 @@ to be used as icon. allow-none="1" closure="7"> the data to pass to callback function + filename="gio/gfile.c" + line="2552">the data to pass to callback function + Finishes an asynchronous replace read/write. Since 2.22. - + a #GFileIOStream, or %NULL on error. + filename="gio/gfile.c" + line="2601">a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). input #GFile + filename="gio/gfile.c" + line="2594">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="2595">a #GAsyncResult + Starts a mountable object. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="9152">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="9153">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, or %NULL to avoid user interaction + filename="gio/gfile.c" + line="9154">a #GMountOperation, or %NULL to avoid user interaction nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="9155">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + filename="gio/gfile.c" + line="9156">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="9157">the data to pass to callback function + Finishes a start operation. Since 2.22. - + %TRUE if the operation finished successfully. %FALSE + filename="gio/gfile.c" + line="9215">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9206">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9207">a #GAsyncResult + Stops a mountable. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="9241">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="9242">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="9243">a #GMountOperation, or %NULL to avoid user interaction. @@ -59433,8 +62639,8 @@ otherwise. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="9245">optional #GCancellable object, %NULL to ignore @@ -59445,8 +62651,8 @@ otherwise. scope="async" closure="5"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="9247">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -59456,34 +62662,37 @@ otherwise. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="9249">the data to pass to callback function + Finishes a stop operation. Since 2.22. - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="9305">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9296">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9297">a #GAsyncResult @@ -59491,27 +62700,30 @@ otherwise. a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22. + filename="gio/gfile.h" + line="141">a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22. + Unmounts a mountable object using a #GMountOperation. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="5691">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5692">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5693">a #GMountOperation, or %NULL to avoid user interaction @@ -59529,8 +62741,8 @@ otherwise. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5695">optional #GCancellable object, %NULL to ignore @@ -59541,8 +62753,8 @@ otherwise. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5697">a #GAsyncReadyCallback to call when the request is satisfied @@ -59552,56 +62764,62 @@ otherwise. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="5699">the data to pass to callback function + Finishes an unmount operation using a #GMountOperation. Since 2.22. - + %TRUE if the operation finished successfully. + filename="gio/gfile.c" + line="5763">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5753">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5754">a #GAsyncResult + Ejects a mountable object using a #GMountOperation. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="5876">input #GFile flags affecting the operation + filename="gio/gfile.c" + line="5877">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation, + filename="gio/gfile.c" + line="5878">a #GMountOperation, or %NULL to avoid user interaction @@ -59619,8 +62837,8 @@ otherwise. nullable="1" allow-none="1"> optional #GCancellable object, + filename="gio/gfile.c" + line="5880">optional #GCancellable object, %NULL to ignore @@ -59631,8 +62849,8 @@ otherwise. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfile.c" + line="5882">a #GAsyncReadyCallback to call when the request is satisfied @@ -59642,50 +62860,56 @@ otherwise. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfile.c" + line="5884">the data to pass to callback function + Finishes an eject operation using a #GMountOperation. Since 2.22. - + %TRUE if the @file was ejected successfully. + filename="gio/gfile.c" + line="5944">%TRUE if the @file was ejected successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="5937">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="5938">a #GAsyncResult + Polls a mountable object for media changes. Since 2.22. - + input #GFile + filename="gio/gfile.c" + line="9331">input #GFile nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="9332">optional #GCancellable object, %NULL to ignore scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gfile.c" + line="9333">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL @@ -59715,60 +62939,66 @@ otherwise. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gfile.c" + line="9335">the data to pass to callback function + Finishes a poll operation for media changes. Since 2.22. - + %TRUE if the operation finished successfully. %FALSE + filename="gio/gfile.c" + line="9387">%TRUE if the operation finished successfully. %FALSE otherwise. input #GFile + filename="gio/gfile.c" + line="9378">input #GFile a #GAsyncResult + filename="gio/gfile.c" + line="9379">a #GAsyncResult - - - + + Recursively measures the disk usage of @file. Since 2.38 + + %TRUE if successful, with the out parameters set. + filename="gio/gfile.c" + line="9056">%TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile + filename="gio/gfile.c" + line="9027">a #GFile #GFileMeasureFlags + filename="gio/gfile.c" + line="9028">#GFileMeasureFlags nullable="1" allow-none="1"> optional #GCancellable + filename="gio/gfile.c" + line="9029">optional #GCancellable a #GFileMeasureProgressCallback + filename="gio/gfile.c" + line="9030">a #GFileMeasureProgressCallback @@ -59796,8 +63027,8 @@ otherwise. nullable="1" allow-none="1"> user_data for @progress_callback + filename="gio/gfile.c" + line="9031">user_data for @progress_callback optional="1" allow-none="1"> the number of bytes of disk space used + filename="gio/gfile.c" + line="9032">the number of bytes of disk space used optional="1" allow-none="1"> the number of directories encountered + filename="gio/gfile.c" + line="9033">the number of directories encountered optional="1" allow-none="1"> the number of non-directories encountered + filename="gio/gfile.c" + line="9034">the number of non-directories encountered + Asynchronously recursively measures the disk usage of @file. Since 2.38 - + a #GFile + filename="gio/gfile.c" + line="9084">a #GFile #GFileMeasureFlags + filename="gio/gfile.c" + line="9085">#GFileMeasureFlags the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="9086">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable + filename="gio/gfile.c" + line="9087">optional #GCancellable allow-none="1" closure="5"> a #GFileMeasureProgressCallback + filename="gio/gfile.c" + line="9088">a #GFileMeasureProgressCallback @@ -59886,8 +63120,8 @@ otherwise. nullable="1" allow-none="1"> user_data for @progress_callback + filename="gio/gfile.c" + line="9089">user_data for @progress_callback scope="async" closure="7"> a #GAsyncReadyCallback to call when complete + filename="gio/gfile.c" + line="9090">a #GAsyncReadyCallback to call when complete allow-none="1" closure="7"> the data to pass to callback function + filename="gio/gfile.c" + line="9091">the data to pass to callback function + Finishes an asynchronous recursive measurement of the disk usage of @file. Since 2.38 - + %TRUE if successful, with the out parameters set. + filename="gio/gfile.c" + line="9131">%TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. a #GFile + filename="gio/gfile.c" + line="9120">a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback + filename="gio/gfile.c" + line="9121">the #GAsyncResult passed to your #GAsyncReadyCallback optional="1" allow-none="1"> the number of bytes of disk space used + filename="gio/gfile.c" + line="9122">the number of bytes of disk space used optional="1" allow-none="1"> the number of directories encountered + filename="gio/gfile.c" + line="9123">the number of directories encountered optional="1" allow-none="1"> the number of non-directories encountered + filename="gio/gfile.c" + line="9124">the number of non-directories encountered + + Queries whether a file exists. Since 2.84 + + + + %TRUE if the file exists (and can be detected without error), + %FALSE otherwise (or if cancelled). + + + + + input #GFile + + + + optional #GCancellable object, + %NULL to ignore + + + + + glib:get-type="g_file_info_get_type" glib:type-struct="FileInfoClass"> Functionality for manipulating basic metadata for files. #GFileInfo + filename="gio/gfileinfo.c" + line="23">Stores information about a file system object referenced by a [iface@Gio.File]. + +Functionality for manipulating basic metadata for files. `GFileInfo` implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. -See [GFileAttribute][gio-GFileAttribute] for more information on how -GIO handles file attributes. +See the [file attributes](file-attributes.html) document for more +information on how GIO handles file attributes. -To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its -async variant). To obtain a #GFileInfo for a file input or output -stream, use g_file_input_stream_query_info() or -g_file_output_stream_query_info() (or their async variants). +To obtain a `GFileInfo` for a [iface@Gio.File], use +[method@Gio.File.query_info] (or its async variant). To obtain a `GFileInfo` +for a file input or output stream, use [method@Gio.FileInputStream.query_info] +or [method@Gio.FileOutputStream.query_info] (or their async variants). To change the actual attributes of a file, you should then set the -attribute in the #GFileInfo and call g_file_set_attributes_from_info() -or g_file_set_attributes_async() on a GFile. +attribute in the `GFileInfo` and call [method@Gio.File.set_attributes_from_info] +or [method@Gio.File.set_attributes_async] on a `GFile`. However, not all attributes can be changed in the file. For instance, -the actual size of a file cannot be changed via g_file_info_set_size(). -You may call g_file_query_settable_attributes() and -g_file_query_writable_namespaces() to discover the settable attributes +the actual size of a file cannot be changed via [method@Gio.FileInfo.set_size]. +You may call [method@Gio.File.query_settable_attributes] and +[method@Gio.File.query_writable_namespaces] to discover the settable attributes of a particular file at runtime. -The direct accessors, such as g_file_info_get_name(), are slightly more +The direct accessors, such as [method@Gio.FileInfo.get_name], are slightly more optimized than the generic attribute accessors, such as -g_file_info_get_attribute_byte_string().This optimization will matter +[method@Gio.FileInfo.get_attribute_byte_string].This optimization will matter only if calling the API in a tight loop. It is an error to call these accessors without specifying their required file -attributes when creating the #GFileInfo. Use g_file_info_has_attribute() or -g_file_info_list_attributes() to check what attributes are specified for a -#GFileInfo. +attributes when creating the `GFileInfo`. Use +[method@Gio.FileInfo.has_attribute] or [method@Gio.FileInfo.list_attributes] +to check what attributes are specified for a `GFileInfo`. -#GFileAttributeMatcher allows for searching through a #GFileInfo for -attributes. - +[struct@Gio.FileAttributeMatcher] allows for searching through a `GFileInfo` +for attributes. + Creates a new file info structure. - + filename="gio/gfileinfo.c" + line="380">Creates a new file info structure. + a #GFileInfo. + filename="gio/gfileinfo.c" + line="385">a #GFileInfo. Clears the status information from @info. - + filename="gio/gfileinfo.c" + line="511">Clears the status information from @info. + a #GFileInfo. + filename="gio/gfileinfo.c" + line="513">a #GFileInfo. First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info, -and then copies all of the file attributes from @src_info to @dest_info. - + filename="gio/gfileinfo.c" + line="393">First clears all of the [GFileAttribute](file-attributes.html#file-attributes) of +@dest_info, and then copies all of the file attributes from @src_info to @dest_info. + source to copy attributes from. + filename="gio/gfileinfo.c" + line="395">source to copy attributes from. destination to copy attributes to. + filename="gio/gfileinfo.c" + line="396">destination to copy attributes to. Duplicates a file info structure. - + filename="gio/gfileinfo.c" + line="437">Duplicates a file info structure. + a duplicate #GFileInfo of @other. + filename="gio/gfileinfo.c" + line="443">a duplicate #GFileInfo of @other. a #GFileInfo. + filename="gio/gfileinfo.c" + line="439">a #GFileInfo. @@ -60095,8 +63367,8 @@ and then copies all of the file attributes from @src_info to @dest_info. c:identifier="g_file_info_get_access_date_time" version="2.70"> Gets the access time of the current @info and returns it as a + filename="gio/gfileinfo.c" + line="1945">Gets the access time of the current @info and returns it as a #GDateTime. It is an error to call this if the #GFileInfo does not contain @@ -60106,18 +63378,18 @@ precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must be queried separately using g_file_info_get_attribute_uint32(). - + access time, or %NULL if unknown + filename="gio/gfileinfo.c" + line="1960">access time, or %NULL if unknown a #GFileInfo. + filename="gio/gfileinfo.c" + line="1947">a #GFileInfo. @@ -60125,15 +63397,15 @@ be queried separately using g_file_info_get_attribute_uint32(). Gets the value of an attribute, formatted as a string. + filename="gio/gfileinfo.c" + line="871">Gets the value of an attribute, formatted as a string. This escapes things as needed to make the string valid UTF-8. - + a UTF-8 string associated with the given @attribute, or + filename="gio/gfileinfo.c" + line="880">a UTF-8 string associated with the given @attribute, or %NULL if the attribute wasn’t set. When you're done with the string it must be freed with g_free(). @@ -60141,14 +63413,14 @@ UTF-8. a #GFileInfo. + filename="gio/gfileinfo.c" + line="873">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="874">a file attribute key. @@ -60156,27 +63428,27 @@ UTF-8. Gets the value of a boolean attribute. If the attribute does not + filename="gio/gfileinfo.c" + line="1018">Gets the value of a boolean attribute. If the attribute does not contain a boolean value, %FALSE will be returned. - + the boolean value contained within the attribute. + filename="gio/gfileinfo.c" + line="1026">the boolean value contained within the attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1020">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1021">a file attribute key. @@ -60184,28 +63456,28 @@ contain a boolean value, %FALSE will be returned. Gets the value of a byte string attribute. If the attribute does + filename="gio/gfileinfo.c" + line="944">Gets the value of a byte string attribute. If the attribute does not contain a byte string, %NULL will be returned. - + the contents of the @attribute value as a byte string, or + filename="gio/gfileinfo.c" + line="952">the contents of the @attribute value as a byte string, or %NULL otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="946">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="947">a file attribute key. @@ -60213,27 +63485,27 @@ not contain a byte string, %NULL will be returned. Gets the attribute type, value and status for an attribute key. - + filename="gio/gfileinfo.c" + line="754">Gets the attribute type, value and status for an attribute key. + %TRUE if @info has an attribute named @attribute, + filename="gio/gfileinfo.c" + line="765">%TRUE if @info has an attribute named @attribute, %FALSE otherwise. a #GFileInfo + filename="gio/gfileinfo.c" + line="756">a #GFileInfo a file attribute key + filename="gio/gfileinfo.c" + line="757">a file attribute key optional="1" allow-none="1"> return location for the attribute type, or %NULL + filename="gio/gfileinfo.c" + line="758">return location for the attribute type, or %NULL optional="1" allow-none="1"> return location for the + filename="gio/gfileinfo.c" + line="759">return location for the attribute value, or %NULL; the attribute value will not be %NULL @@ -60266,8 +63538,8 @@ not contain a byte string, %NULL will be returned. optional="1" allow-none="1"> return location for the attribute status, or %NULL + filename="gio/gfileinfo.c" + line="761">return location for the attribute status, or %NULL @@ -60276,32 +63548,32 @@ not contain a byte string, %NULL will be returned. c:identifier="g_file_info_get_attribute_file_path" version="2.78"> Gets the value of a byte string attribute as a file path. + filename="gio/gfileinfo.c" + line="968">Gets the value of a byte string attribute as a file path. If the attribute does not contain a byte string, `NULL` will be returned. This function is meant to be used by language bindings that have specific handling for Unix paths. - + the contents of the @attribute value as + filename="gio/gfileinfo.c" + line="980">the contents of the @attribute value as a file path, or %NULL otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="970">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="971">a file attribute key. @@ -60309,28 +63581,28 @@ a file path, or %NULL otherwise. Gets a signed 32-bit integer contained within the attribute. If the + filename="gio/gfileinfo.c" + line="1065">Gets a signed 32-bit integer contained within the attribute. If the attribute does not contain a signed 32-bit integer, or is invalid, 0 will be returned. - + a signed 32-bit integer from the attribute. + filename="gio/gfileinfo.c" + line="1074">a signed 32-bit integer from the attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1067">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1068">a file attribute key. @@ -60338,28 +63610,28 @@ attribute does not contain a signed 32-bit integer, or is invalid, Gets a signed 64-bit integer contained within the attribute. If the + filename="gio/gfileinfo.c" + line="1113">Gets a signed 64-bit integer contained within the attribute. If the attribute does not contain a signed 64-bit integer, or is invalid, 0 will be returned. - + a signed 64-bit integer from the attribute. + filename="gio/gfileinfo.c" + line="1122">a signed 64-bit integer from the attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1115">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1116">a file attribute key. @@ -60367,28 +63639,28 @@ attribute does not contain a signed 64-bit integer, or is invalid, Gets the value of a #GObject attribute. If the attribute does + filename="gio/gfileinfo.c" + line="896">Gets the value of a #GObject attribute. If the attribute does not contain a #GObject, %NULL will be returned. - + a #GObject associated with the given @attribute, + filename="gio/gfileinfo.c" + line="904">a #GObject associated with the given @attribute, or %NULL otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="898">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="899">a file attribute key. @@ -60396,27 +63668,27 @@ or %NULL otherwise. Gets the attribute status for an attribute key. - + filename="gio/gfileinfo.c" + line="796">Gets the attribute status for an attribute key. + a #GFileAttributeStatus for the given @attribute, or + filename="gio/gfileinfo.c" + line="803">a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. a #GFileInfo + filename="gio/gfileinfo.c" + line="798">a #GFileInfo a file attribute key + filename="gio/gfileinfo.c" + line="799">a file attribute key @@ -60424,28 +63696,28 @@ or %NULL otherwise. Gets the value of a string attribute. If the attribute does + filename="gio/gfileinfo.c" + line="920">Gets the value of a string attribute. If the attribute does not contain a string, %NULL will be returned. - + the contents of the @attribute value as a UTF-8 string, + filename="gio/gfileinfo.c" + line="928">the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="922">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="923">a file attribute key. @@ -60454,14 +63726,14 @@ or %NULL otherwise. c:identifier="g_file_info_get_attribute_stringv" version="2.22"> Gets the value of a stringv attribute. If the attribute does + filename="gio/gfileinfo.c" + line="992">Gets the value of a stringv attribute. If the attribute does not contain a stringv, %NULL will be returned. - + the contents of the @attribute value as a stringv, + filename="gio/gfileinfo.c" + line="1000">the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8. @@ -60470,14 +63742,14 @@ or %NULL otherwise. Do not free. These returned strings are UTF-8. a #GFileInfo. + filename="gio/gfileinfo.c" + line="994">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="995">a file attribute key. @@ -60485,27 +63757,27 @@ or %NULL otherwise. Do not free. These returned strings are UTF-8. Gets the attribute type for an attribute key. - + filename="gio/gfileinfo.c" + line="685">Gets the attribute type for an attribute key. + a #GFileAttributeType for the given @attribute, or + filename="gio/gfileinfo.c" + line="692">a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. a #GFileInfo. + filename="gio/gfileinfo.c" + line="687">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="688">a file attribute key. @@ -60513,28 +63785,28 @@ or %NULL otherwise. Do not free. These returned strings are UTF-8. Gets an unsigned 32-bit integer contained within the attribute. If the + filename="gio/gfileinfo.c" + line="1041">Gets an unsigned 32-bit integer contained within the attribute. If the attribute does not contain an unsigned 32-bit integer, or is invalid, 0 will be returned. - + an unsigned 32-bit integer from the attribute. + filename="gio/gfileinfo.c" + line="1050">an unsigned 32-bit integer from the attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1043">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1044">a file attribute key. @@ -60542,28 +63814,28 @@ attribute does not contain an unsigned 32-bit integer, or is invalid, Gets a unsigned 64-bit integer contained within the attribute. If the + filename="gio/gfileinfo.c" + line="1089">Gets a unsigned 64-bit integer contained within the attribute. If the attribute does not contain an unsigned 64-bit integer, or is invalid, 0 will be returned. - + a unsigned 64-bit integer from the attribute. + filename="gio/gfileinfo.c" + line="1098">a unsigned 64-bit integer from the attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1091">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1092">a file attribute key. @@ -60571,24 +63843,24 @@ attribute does not contain an unsigned 64-bit integer, or is invalid, Gets the file's content type. + filename="gio/gfileinfo.c" + line="1802">Gets the file's content type. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. - + a string containing the file's content type, + filename="gio/gfileinfo.c" + line="1811">a string containing the file's content type, or %NULL if unknown. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1804">a #GFileInfo. @@ -60597,8 +63869,8 @@ or %NULL if unknown. c:identifier="g_file_info_get_creation_date_time" version="2.70"> Gets the creation time of the current @info and returns it as a + filename="gio/gfileinfo.c" + line="1994">Gets the creation time of the current @info and returns it as a #GDateTime. It is an error to call this if the #GFileInfo does not contain @@ -60608,18 +63880,18 @@ precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must be queried separately using g_file_info_get_attribute_uint32(). - + creation time, or %NULL if unknown + filename="gio/gfileinfo.c" + line="2009">creation time, or %NULL if unknown a #GFileInfo. + filename="gio/gfileinfo.c" + line="1996">a #GFileInfo. @@ -60628,22 +63900,22 @@ be queried separately using g_file_info_get_attribute_uint32(). c:identifier="g_file_info_get_deletion_date" version="2.36"> Returns the #GDateTime representing the deletion date of the file, as + filename="gio/gfileinfo.c" + line="1553">Returns the #GDateTime representing the deletion date of the file, as available in %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. - + a #GDateTime, or %NULL. + filename="gio/gfileinfo.c" + line="1561">a #GDateTime, or %NULL. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1555">a #GFileInfo. @@ -60651,186 +63923,186 @@ available in %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the Gets a display name for a file. This is guaranteed to always be set. + filename="gio/gfileinfo.c" + line="1702">Gets a display name for a file. This is guaranteed to always be set. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. - + a string containing the display name. + filename="gio/gfileinfo.c" + line="1711">a string containing the display name. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1704">a #GFileInfo. Gets the edit name for a file. + filename="gio/gfileinfo.c" + line="1724">Gets the edit name for a file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. - + a string containing the edit name. + filename="gio/gfileinfo.c" + line="1733">a string containing the edit name. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1726">a #GFileInfo. Gets the [entity tag][gfile-etag] for a given + filename="gio/gfileinfo.c" + line="2065">Gets the [entity tag][iface@Gio.File#entity-tags] for a given #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_ETAG_VALUE. - + a string containing the value of the "etag:value" attribute. + filename="gio/gfileinfo.c" + line="2075">a string containing the value of the "etag:value" attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="2067">a #GFileInfo. Gets a file's type (whether it is a regular file, symlink, etc). + filename="gio/gfileinfo.c" + line="1591">Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see g_file_info_get_content_type(). It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_TYPE. - + a #GFileType for the given file. + filename="gio/gfileinfo.c" + line="1601">a #GFileType for the given file. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1593">a #GFileInfo. Gets the icon for a file. + filename="gio/gfileinfo.c" + line="1746">Gets the icon for a file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_ICON. - + #GIcon for the given @info. + filename="gio/gfileinfo.c" + line="1755">#GIcon for the given @info. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1748">a #GFileInfo. Checks if a file is a backup file. + filename="gio/gfileinfo.c" + line="1636">Checks if a file is a backup file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP. - + %TRUE if file is a backup file, %FALSE otherwise. + filename="gio/gfileinfo.c" + line="1645">%TRUE if file is a backup file, %FALSE otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1638">a #GFileInfo. Checks if a file is hidden. + filename="gio/gfileinfo.c" + line="1614">Checks if a file is hidden. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. - + %TRUE if the file is a hidden file, %FALSE otherwise. + filename="gio/gfileinfo.c" + line="1623">%TRUE if the file is a hidden file, %FALSE otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1616">a #GFileInfo. Checks if a file is a symlink. + filename="gio/gfileinfo.c" + line="1658">Checks if a file is a symlink. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. - + %TRUE if the given @info is a symlink. + filename="gio/gfileinfo.c" + line="1667">%TRUE if the given @info is a symlink. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1660">a #GFileInfo. @@ -60839,8 +64111,8 @@ It is an error to call this if the #GFileInfo does not contain c:identifier="g_file_info_get_modification_date_time" version="2.62"> Gets the modification time of the current @info and returns it as a + filename="gio/gfileinfo.c" + line="1896">Gets the modification time of the current @info and returns it as a #GDateTime. It is an error to call this if the #GFileInfo does not contain @@ -60850,18 +64122,18 @@ precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must be queried separately using g_file_info_get_attribute_uint32(). - + modification time, or %NULL if unknown + filename="gio/gfileinfo.c" + line="1911">modification time, or %NULL if unknown a #GFileInfo. + filename="gio/gfileinfo.c" + line="1898">a #GFileInfo. @@ -60871,8 +64143,8 @@ be queried separately using g_file_info_get_attribute_uint32(). deprecated="1" deprecated-version="2.62"> Gets the modification time of the current @info and sets it + filename="gio/gfileinfo.c" + line="1849">Gets the modification time of the current @info and sets it in @result. It is an error to call this if the #GFileInfo does not contain @@ -60880,15 +64152,15 @@ It is an error to call this if the #GFileInfo does not contain provided it will be used too. Use g_file_info_get_modification_date_time() instead, as #GTimeVal is deprecated due to the year 2038 problem. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1851">a #GFileInfo. caller-allocates="1" transfer-ownership="none"> a #GTimeVal. + filename="gio/gfileinfo.c" + line="1852">a #GTimeVal. Gets the name for a file. This is guaranteed to always be set. + filename="gio/gfileinfo.c" + line="1680">Gets the name for a file. This is guaranteed to always be set. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_NAME. - + a string containing the file name. + filename="gio/gfileinfo.c" + line="1689">a string containing the file name. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1682">a #GFileInfo. Gets the file's size (in bytes). The size is retrieved through the value of + filename="gio/gfileinfo.c" + line="1825">Gets the file's size (in bytes). The size is retrieved through the value of the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted from #guint64 to #goffset before returning the result. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SIZE. - + a #goffset containing the file's size (in bytes). + filename="gio/gfileinfo.c" + line="1836">a #goffset containing the file's size (in bytes). a #GFileInfo. + filename="gio/gfileinfo.c" + line="1827">a #GFileInfo. Gets the value of the sort_order attribute from the #GFileInfo. + filename="gio/gfileinfo.c" + line="2088">Gets the value of the sort_order attribute from the #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - + a #gint32 containing the value of the "standard::sort_order" attribute. + filename="gio/gfileinfo.c" + line="2098">a #gint32 containing the value of the "standard::sort_order" attribute. a #GFileInfo. + filename="gio/gfileinfo.c" + line="2090">a #GFileInfo. @@ -60978,23 +64250,23 @@ It is an error to call this if the #GFileInfo does not contain c:identifier="g_file_info_get_symbolic_icon" version="2.34"> Gets the symbolic icon for a file. + filename="gio/gfileinfo.c" + line="1773">Gets the symbolic icon for a file. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. - + #GIcon for the given @info. + filename="gio/gfileinfo.c" + line="1782">#GIcon for the given @info. a #GFileInfo. + filename="gio/gfileinfo.c" + line="1775">a #GFileInfo. @@ -61002,50 +64274,50 @@ It is an error to call this if the #GFileInfo does not contain Gets the symlink target for a given #GFileInfo. + filename="gio/gfileinfo.c" + line="2043">Gets the symlink target for a given #GFileInfo. It is an error to call this if the #GFileInfo does not contain %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET. - + a string containing the symlink target. + filename="gio/gfileinfo.c" + line="2052">a string containing the symlink target. a #GFileInfo. + filename="gio/gfileinfo.c" + line="2045">a #GFileInfo. Checks if a file info structure has an attribute named @attribute. - + filename="gio/gfileinfo.c" + line="587">Checks if a file info structure has an attribute named @attribute. + %TRUE if @info has an attribute named @attribute, + filename="gio/gfileinfo.c" + line="594">%TRUE if @info has an attribute named @attribute, %FALSE otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="589">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="590">a file attribute key. @@ -61054,28 +64326,28 @@ It is an error to call this if the #GFileInfo does not contain c:identifier="g_file_info_has_namespace" version="2.22"> Checks if a file info structure has an attribute in the + filename="gio/gfileinfo.c" + line="610">Checks if a file info structure has an attribute in the specified @name_space. - + %TRUE if @info has an attribute in @name_space, + filename="gio/gfileinfo.c" + line="618">%TRUE if @info has an attribute in @name_space, %FALSE otherwise. a #GFileInfo. + filename="gio/gfileinfo.c" + line="612">a #GFileInfo. a file attribute namespace. + filename="gio/gfileinfo.c" + line="613">a file attribute namespace. @@ -61083,13 +64355,13 @@ specified @name_space. Lists the file info structure's attributes. - + filename="gio/gfileinfo.c" + line="646">Lists the file info structure's attributes. + a + filename="gio/gfileinfo.c" + line="654">a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error. @@ -61099,8 +64371,8 @@ types for the given @name_space, or %NULL on error. a #GFileInfo. + filename="gio/gfileinfo.c" + line="648">a #GFileInfo. nullable="1" allow-none="1"> a file attribute key's namespace, or %NULL to list + filename="gio/gfileinfo.c" + line="649">a file attribute key's namespace, or %NULL to list all attributes. @@ -61118,23 +64390,23 @@ types for the given @name_space, or %NULL on error. Removes all cases of @attribute from @info if it exists. - + filename="gio/gfileinfo.c" + line="733">Removes all cases of @attribute from @info if it exists. + a #GFileInfo. + filename="gio/gfileinfo.c" + line="735">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="736">a file attribute key. @@ -61143,63 +64415,63 @@ types for the given @name_space, or %NULL on error. c:identifier="g_file_info_set_access_date_time" version="2.70"> Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and + filename="gio/gfileinfo.c" + line="2455">Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2457">a #GFileInfo. a #GDateTime. + filename="gio/gfileinfo.c" + line="2458">a #GDateTime. Sets the @attribute to contain the given value, if possible. To unset the + filename="gio/gfileinfo.c" + line="1179">Sets the @attribute to contain the given value, if possible. To unset the attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1181">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1182">a file attribute key. a #GFileAttributeType + filename="gio/gfileinfo.c" + line="1183">a #GFileAttributeType pointer to the value + filename="gio/gfileinfo.c" + line="1184">pointer to the value @@ -61207,30 +64479,30 @@ attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1378">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1380">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1381">a file attribute key. a boolean value. + filename="gio/gfileinfo.c" + line="1382">a boolean value. @@ -61238,30 +64510,30 @@ if possible. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1321">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1323">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1324">a file attribute key. a byte string. + filename="gio/gfileinfo.c" + line="1325">a byte string. @@ -61270,33 +64542,33 @@ if possible. c:identifier="g_file_info_set_attribute_file_path" version="2.78"> Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1344">Sets the @attribute to contain the given @attr_value, if possible. This function is meant to be used by language bindings that have specific handling for Unix paths. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1346">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1347">a file attribute key. a file path. + filename="gio/gfileinfo.c" + line="1348">a file path. @@ -61304,30 +64576,30 @@ handling for Unix paths. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1446">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1448">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1449">a file attribute key. a signed 32-bit integer + filename="gio/gfileinfo.c" + line="1450">a signed 32-bit integer @@ -61335,30 +64607,30 @@ if possible. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1514">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1516">a #GFileInfo. attribute name to set. + filename="gio/gfileinfo.c" + line="1517">attribute name to set. int64 value to set attribute to. + filename="gio/gfileinfo.c" + line="1518">int64 value to set attribute to. @@ -61366,23 +64638,23 @@ if possible. Sets @mask on @info to match specific attribute types. - + filename="gio/gfileinfo.c" + line="457">Sets @mask on @info to match specific attribute types. + a #GFileInfo. + filename="gio/gfileinfo.c" + line="459">a #GFileInfo. a #GFileAttributeMatcher. + filename="gio/gfileinfo.c" + line="460">a #GFileAttributeMatcher. @@ -61390,30 +64662,30 @@ if possible. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1213">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1215">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1216">a file attribute key. a #GObject. + filename="gio/gfileinfo.c" + line="1217">a #GObject. @@ -61422,37 +64694,37 @@ if possible. c:identifier="g_file_info_set_attribute_status" version="2.22"> Sets the attribute status for an attribute key. This is only + filename="gio/gfileinfo.c" + line="823">Sets the attribute status for an attribute key. This is only needed by external code that implement g_file_set_attributes_from_info() or similar functions. The attribute must exist in @info for this to work. Otherwise %FALSE is returned and @info is unchanged. - + %TRUE if the status was changed, %FALSE if the key was not set. + filename="gio/gfileinfo.c" + line="836">%TRUE if the status was changed, %FALSE if the key was not set. a #GFileInfo + filename="gio/gfileinfo.c" + line="825">a #GFileInfo a file attribute key + filename="gio/gfileinfo.c" + line="826">a file attribute key a #GFileAttributeStatus + filename="gio/gfileinfo.c" + line="827">a #GFileAttributeStatus @@ -61460,30 +64732,30 @@ is returned and @info is unchanged. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1286">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1288">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1289">a file attribute key. a UTF-8 string. + filename="gio/gfileinfo.c" + line="1290">a UTF-8 string. @@ -61491,32 +64763,32 @@ if possible. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1248">Sets the @attribute to contain the given @attr_value, if possible. Sinze: 2.22 - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1250">a #GFileInfo. a file attribute key + filename="gio/gfileinfo.c" + line="1251">a file attribute key a %NULL + filename="gio/gfileinfo.c" + line="1252">a %NULL terminated array of UTF-8 strings. @@ -61527,30 +64799,30 @@ Sinze: 2.22 Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1412">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1414">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1415">a file attribute key. an unsigned 32-bit integer. + filename="gio/gfileinfo.c" + line="1416">an unsigned 32-bit integer. @@ -61558,30 +64830,30 @@ if possible. Sets the @attribute to contain the given @attr_value, + filename="gio/gfileinfo.c" + line="1480">Sets the @attribute to contain the given @attr_value, if possible. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="1482">a #GFileInfo. a file attribute key. + filename="gio/gfileinfo.c" + line="1483">a file attribute key. an unsigned 64-bit integer. + filename="gio/gfileinfo.c" + line="1484">an unsigned 64-bit integer. @@ -61589,24 +64861,24 @@ if possible. Sets the content type attribute for a given #GFileInfo. + filename="gio/gfileinfo.c" + line="2319">Sets the content type attribute for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2321">a #GFileInfo. a content type. See [GContentType][gio-GContentType] + filename="gio/gfileinfo.c" + line="2322">a [content type](content-types.html#content-types). @@ -61615,27 +64887,27 @@ See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. c:identifier="g_file_info_set_creation_date_time" version="2.70"> Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and + filename="gio/gfileinfo.c" + line="2496">Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2498">a #GFileInfo. a #GDateTime. + filename="gio/gfileinfo.c" + line="2499">a #GDateTime. @@ -61643,144 +64915,144 @@ given date/time value. Sets the display name for the current #GFileInfo. + filename="gio/gfileinfo.c" + line="2213">Sets the display name for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2215">a #GFileInfo. a string containing a display name. + filename="gio/gfileinfo.c" + line="2216">a string containing a display name. Sets the edit name for the current file. + filename="gio/gfileinfo.c" + line="2239">Sets the edit name for the current file. See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2241">a #GFileInfo. a string containing an edit name. + filename="gio/gfileinfo.c" + line="2242">a string containing an edit name. Sets the file type in a #GFileInfo to @type. + filename="gio/gfileinfo.c" + line="2112">Sets the file type in a #GFileInfo to @type. See %G_FILE_ATTRIBUTE_STANDARD_TYPE. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2114">a #GFileInfo. a #GFileType. + filename="gio/gfileinfo.c" + line="2115">a #GFileType. Sets the icon for a given #GFileInfo. + filename="gio/gfileinfo.c" + line="2265">Sets the icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_ICON. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2267">a #GFileInfo. a #GIcon. + filename="gio/gfileinfo.c" + line="2268">a #GIcon. Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. + filename="gio/gfileinfo.c" + line="2137">Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2139">a #GFileInfo. a #gboolean. + filename="gio/gfileinfo.c" + line="2140">a #gboolean. Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. + filename="gio/gfileinfo.c" + line="2162">Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2164">a #GFileInfo. a #gboolean. + filename="gio/gfileinfo.c" + line="2165">a #gboolean. @@ -61789,27 +65061,27 @@ See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. c:identifier="g_file_info_set_modification_date_time" version="2.62"> Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and + filename="gio/gfileinfo.c" + line="2414">Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2416">a #GFileInfo. a #GDateTime. + filename="gio/gfileinfo.c" + line="2417">a #GDateTime. @@ -61819,101 +65091,101 @@ given date/time value. deprecated="1" deprecated-version="2.62"> Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and + filename="gio/gfileinfo.c" + line="2370">Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given time value. %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. Use g_file_info_set_modification_date_time() instead, as #GTimeVal is deprecated due to the year 2038 problem. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2372">a #GFileInfo. a #GTimeVal. + filename="gio/gfileinfo.c" + line="2373">a #GTimeVal. Sets the name attribute for the current #GFileInfo. + filename="gio/gfileinfo.c" + line="2187">Sets the name attribute for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_NAME. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2189">a #GFileInfo. a string containing a name. + filename="gio/gfileinfo.c" + line="2190">a string containing a name. Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info + filename="gio/gfileinfo.c" + line="2345">Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info to the given size. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2347">a #GFileInfo. a #goffset containing the file's size. + filename="gio/gfileinfo.c" + line="2348">a #goffset containing the file's size. Sets the sort order attribute in the file info structure. See + filename="gio/gfileinfo.c" + line="2563">Sets the sort order attribute in the file info structure. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2565">a #GFileInfo. a sort order integer. + filename="gio/gfileinfo.c" + line="2566">a sort order integer. @@ -61922,24 +65194,24 @@ to the given size. c:identifier="g_file_info_set_symbolic_icon" version="2.34"> Sets the symbolic icon for a given #GFileInfo. + filename="gio/gfileinfo.c" + line="2291">Sets the symbolic icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2293">a #GFileInfo. a #GIcon. + filename="gio/gfileinfo.c" + line="2294">a #GIcon. @@ -61947,24 +65219,24 @@ See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info + filename="gio/gfileinfo.c" + line="2537">Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info to the given symlink target. - + a #GFileInfo. + filename="gio/gfileinfo.c" + line="2539">a #GFileInfo. a static string containing a path to a symlink target. + filename="gio/gfileinfo.c" + line="2540">a static string containing a path to a symlink target. @@ -61972,18 +65244,18 @@ to the given symlink target. Unsets a mask set by g_file_info_set_attribute_mask(), if one + filename="gio/gfileinfo.c" + line="494">Unsets a mask set by g_file_info_set_attribute_mask(), if one is set. - + #GFileInfo. + filename="gio/gfileinfo.c" + line="496">#GFileInfo. @@ -61994,7 +65266,7 @@ is set. disguised="1" opaque="1" glib:is-gtype-struct-for="FileInfo"> - + glib:get-type="g_file_input_stream_get_type" glib:type-struct="FileInputStreamClass"> GFileInputStream provides input streams that take their + filename="gio/gfileinputstream.c" + line="35">`GFileInputStream` provides input streams that take their content from a file. -GFileInputStream implements #GSeekable, which allows the input +`GFileInputStream` implements [iface@Gio.Seekable], which allows the input stream to jump to arbitrary positions in the file, provided the filesystem of the file allows it. To find the position of a file -input stream, use g_seekable_tell(). To find out if a file input -stream supports seeking, use g_seekable_can_seek(). -To position a file input stream, use g_seekable_seek(). - +input stream, use [method@Gio.Seekable.tell]. To find out if a file input +stream supports seeking, use [vfunc@Gio.Seekable.can_seek]. +To position a file input stream, use [vfunc@Gio.Seekable.seek]. + - + @@ -62027,32 +65299,35 @@ To position a file input stream, use g_seekable_seek(). - + Queries a file input stream the given @attributes. This function blocks + filename="gio/gfileinputstream.c" + line="105">Queries a file input stream the given @attributes. This function blocks while querying the stream. For the asynchronous (non-blocking) version of this function, see g_file_input_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. - + a #GFileInfo, or %NULL on error. + filename="gio/gfileinputstream.c" + line="119">a #GFileInfo, or %NULL on error. a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="107">a #GFileInputStream. a file attribute query string. + filename="gio/gfileinputstream.c" + line="108">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileinputstream.c" + line="109">optional #GCancellable object, %NULL to ignore. - + Queries the stream information asynchronously. + filename="gio/gfileinputstream.c" + line="171">Queries the stream information asynchronously. When the operation is finished @callback will be called. You can then call g_file_input_stream_query_info_finish() to get the result of the operation. @@ -62080,27 +65358,27 @@ see g_file_input_stream_query_info(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="173">a #GFileInputStream. a file attribute query string. + filename="gio/gfileinputstream.c" + line="174">a file attribute query string. the [I/O priority][io-priority] of the request + filename="gio/gfileinputstream.c" + line="175">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileinputstream.c" + line="176">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileinputstream.c" + line="177">a #GAsyncReadyCallback to call when the request is satisfied @@ -62130,8 +65408,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfileinputstream.c" + line="179">the data to pass to callback function @@ -62140,32 +65418,32 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set invoker="query_info_finish" throws="1"> Finishes an asynchronous info query operation. - + filename="gio/gfileinputstream.c" + line="226">Finishes an asynchronous info query operation. + #GFileInfo. + filename="gio/gfileinputstream.c" + line="235">#GFileInfo. a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="228">a #GFileInputStream. a #GAsyncResult. + filename="gio/gfileinputstream.c" + line="229">a #GAsyncResult. - + @@ -62188,7 +65466,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62200,32 +65478,33 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set + throws="1" + glib:async-func="query_info_async"> Queries a file input stream the given @attributes. This function blocks + filename="gio/gfileinputstream.c" + line="105">Queries a file input stream the given @attributes. This function blocks while querying the stream. For the asynchronous (non-blocking) version of this function, see g_file_input_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with %G_IO_ERROR_PENDING. - + a #GFileInfo, or %NULL on error. + filename="gio/gfileinputstream.c" + line="119">a #GFileInfo, or %NULL on error. a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="107">a #GFileInputStream. a file attribute query string. + filename="gio/gfileinputstream.c" + line="108">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileinputstream.c" + line="109">optional #GCancellable object, %NULL to ignore. + c:identifier="g_file_input_stream_query_info_async" + glib:finish-func="query_info_finish" + glib:sync-func="query_info"> Queries the stream information asynchronously. + filename="gio/gfileinputstream.c" + line="171">Queries the stream information asynchronously. When the operation is finished @callback will be called. You can then call g_file_input_stream_query_info_finish() to get the result of the operation. @@ -62254,27 +65535,27 @@ see g_file_input_stream_query_info(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="173">a #GFileInputStream. a file attribute query string. + filename="gio/gfileinputstream.c" + line="174">a file attribute query string. the [I/O priority][io-priority] of the request + filename="gio/gfileinputstream.c" + line="175">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileinputstream.c" + line="176">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gfileinputstream.c" + line="177">a #GAsyncReadyCallback to call when the request is satisfied @@ -62303,8 +65584,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfileinputstream.c" + line="179">the data to pass to callback function @@ -62313,26 +65594,26 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set c:identifier="g_file_input_stream_query_info_finish" throws="1"> Finishes an asynchronous info query operation. - + filename="gio/gfileinputstream.c" + line="226">Finishes an asynchronous info query operation. + #GFileInfo. + filename="gio/gfileinputstream.c" + line="235">#GFileInfo. a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="228">a #GFileInputStream. a #GAsyncResult. + filename="gio/gfileinputstream.c" + line="229">a #GAsyncResult. @@ -62347,13 +65628,13 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + - + @@ -62366,7 +65647,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62379,7 +65660,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62404,24 +65685,24 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + a #GFileInfo, or %NULL on error. + filename="gio/gfileinputstream.c" + line="119">a #GFileInfo, or %NULL on error. a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="107">a #GFileInputStream. a file attribute query string. + filename="gio/gfileinputstream.c" + line="108">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileinputstream.c" + line="109">optional #GCancellable object, %NULL to ignore. @@ -62438,27 +65719,27 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="173">a #GFileInputStream. a file attribute query string. + filename="gio/gfileinputstream.c" + line="174">a file attribute query string. the [I/O priority][io-priority] of the request + filename="gio/gfileinputstream.c" + line="175">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileinputstream.c" + line="176">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gfileinputstream.c" + line="177">a #GAsyncReadyCallback to call when the request is satisfied @@ -62488,8 +65769,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfileinputstream.c" + line="179">the data to pass to callback function @@ -62497,24 +65778,24 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + #GFileInfo. + filename="gio/gfileinputstream.c" + line="235">#GFileInfo. a #GFileInputStream. + filename="gio/gfileinputstream.c" + line="228">a #GFileInputStream. a #GAsyncResult. + filename="gio/gfileinputstream.c" + line="229">a #GAsyncResult. @@ -62522,7 +65803,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62530,7 +65811,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62538,7 +65819,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62546,7 +65827,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62554,7 +65835,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set - + @@ -62565,7 +65846,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set c:type="GFileInputStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_file_measure_flags_get_type" c:type="GFileMeasureFlags"> Flags that can be used with g_file_measure_disk_usage(). glib:nick="none" glib:name="G_FILE_MEASURE_NONE"> No flags set. glib:nick="report-any-error" glib:name="G_FILE_MEASURE_REPORT_ANY_ERROR"> Report any error encountered while traversing the directory tree. Normally errors are only reported for the toplevel file. @@ -62601,7 +65882,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set glib:nick="apparent-size" glib:name="G_FILE_MEASURE_APPARENT_SIZE"> Tally usage based on apparent file sizes. Normally, the block-size is used, if available, as this is a more accurate representation of disk space used. @@ -62616,7 +65897,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set glib:nick="no-xdev" glib:name="G_FILE_MEASURE_NO_XDEV"> Do not cross mount point boundaries. Compare with `du -x`. @@ -62625,8 +65906,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set c:type="GFileMeasureProgressCallback" version="2.38"> This callback type is used by g_file_measure_disk_usage() to make + filename="gio/giotypes.h" + line="225">This callback type is used by g_file_measure_disk_usage() to make periodic progress reports when measuring the amount of disk spaced used by a directory. @@ -62653,33 +65934,33 @@ ideally about once every 200ms. The last progress callback may or may not be equal to the final result. Always check the async result to get the final value. - + %TRUE if more reports will come + filename="gio/giotypes.h" + line="227">%TRUE if more reports will come the current cumulative size measurement + filename="gio/giotypes.h" + line="228">the current cumulative size measurement the number of directories visited so far + filename="gio/giotypes.h" + line="229">the number of directories visited so far the number of non-directory files encountered + filename="gio/giotypes.h" + line="230">the number of non-directory files encountered nullable="1" allow-none="1"> the data passed to the original request for this callback + filename="gio/giotypes.h" + line="231">the data passed to the original request for this callback @@ -62702,44 +65983,43 @@ result. Always check the async result to get the final value. glib:get-type="g_file_monitor_get_type" glib:type-struct="FileMonitorClass"> Monitors a file or directory for changes. + filename="gio/gfilemonitor.c" + line="34">Monitors a file or directory for changes. -To obtain a #GFileMonitor for a file or directory, use -g_file_monitor(), g_file_monitor_file(), or -g_file_monitor_directory(). +To obtain a `GFileMonitor` for a file or directory, use +[method@Gio.File.monitor], [method@Gio.File.monitor_file], or +[method@Gio.File.monitor_directory]. To get informed about changes to the file or directory you are -monitoring, connect to the #GFileMonitor::changed signal. The -signal will be emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread that the monitor was created in -(though if the global default main context is blocked, this may -cause notifications to be blocked even if the thread-default +monitoring, connect to the [signal@Gio.FileMonitor::changed] signal. The +signal will be emitted in the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) of the thread that the monitor +was created in (though if the global default main context is blocked, this +may cause notifications to be blocked even if the thread-default context is still running). - + Cancels a file monitor. - + filename="gio/gfilemonitor.c" + line="237">Cancels a file monitor. + always %TRUE + filename="gio/gfilemonitor.c" + line="243">always %TRUE a #GFileMonitor. + filename="gio/gfilemonitor.c" + line="239">a #GFileMonitor. - + @@ -62760,81 +66040,83 @@ context is still running). Cancels a file monitor. - + filename="gio/gfilemonitor.c" + line="237">Cancels a file monitor. + always %TRUE + filename="gio/gfilemonitor.c" + line="243">always %TRUE a #GFileMonitor. + filename="gio/gfilemonitor.c" + line="239">a #GFileMonitor. Emits the #GFileMonitor::changed signal if a change + filename="gio/gfilemonitor.c" + line="279">Emits the #GFileMonitor::changed signal if a change has taken place. Should be called from file monitor implementations only. Implementations are responsible to call this method from the -[thread-default main context][g-main-context-push-thread-default] of the -thread that the monitor was created in. - +thread-default main context (see [method@GLib.MainContext.push_thread_default]) +of the thread that the monitor was created in. + a #GFileMonitor. + filename="gio/gfilemonitor.c" + line="281">a #GFileMonitor. a #GFile. + filename="gio/gfilemonitor.c" + line="282">a #GFile. a #GFile. + filename="gio/gfilemonitor.c" + line="283">a #GFile. a set of #GFileMonitorEvent flags. + filename="gio/gfilemonitor.c" + line="284">a set of #GFileMonitorEvent flags. - + Returns whether the monitor is canceled. - + filename="gio/gfilemonitor.c" + line="221">Returns whether the monitor is canceled. + %TRUE if monitor is canceled. %FALSE otherwise. + filename="gio/gfilemonitor.c" + line="227">%TRUE if monitor is canceled. %FALSE otherwise. a #GFileMonitor + filename="gio/gfilemonitor.c" + line="223">a #GFileMonitor @@ -62843,24 +66125,24 @@ thread that the monitor was created in. c:identifier="g_file_monitor_set_rate_limit" glib:set-property="rate-limit"> Sets the rate limit to which the @monitor will report + filename="gio/gfilemonitor.c" + line="263">Sets the rate limit to which the @monitor will report consecutive change events to the same file. - + a #GFileMonitor. + filename="gio/gfilemonitor.c" + line="265">a #GFileMonitor. a non-negative integer with the limit in milliseconds + filename="gio/gfilemonitor.c" + line="266">a non-negative integer with the limit in milliseconds to poll for changes @@ -62868,7 +66150,11 @@ consecutive change events to the same file. + Whether the monitor has been cancelled. transfer-ownership="none" setter="set_rate_limit" default-value="800"> + The limit of the monitor to watch for changes, in milliseconds. @@ -62886,8 +66175,8 @@ consecutive change events to the same file. Emitted when @file has been changed. + filename="gio/gfilemonitor.c" + line="151">Emitted when @file has been changed. If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and the information is available (and if supported by the backend), @@ -62921,8 +66210,8 @@ In all the other cases, @other_file will be set to #NULL. a #GFile. + filename="gio/gfilemonitor.c" + line="154">a #GFile. nullable="1" allow-none="1"> a #GFile or #NULL. + filename="gio/gfilemonitor.c" + line="155">a #GFile or #NULL. a #GFileMonitorEvent. + filename="gio/gfilemonitor.c" + line="156">a #GFileMonitorEvent. @@ -62946,13 +66235,13 @@ In all the other cases, @other_file will be set to #NULL. - + - + @@ -62974,18 +66263,18 @@ In all the other cases, @other_file will be set to #NULL. - + always %TRUE + filename="gio/gfilemonitor.c" + line="243">always %TRUE a #GFileMonitor. + filename="gio/gfilemonitor.c" + line="239">a #GFileMonitor. @@ -62993,7 +66282,7 @@ In all the other cases, @other_file will be set to #NULL. - + @@ -63001,7 +66290,7 @@ In all the other cases, @other_file will be set to #NULL. - + @@ -63009,7 +66298,7 @@ In all the other cases, @other_file will be set to #NULL. - + @@ -63017,7 +66306,7 @@ In all the other cases, @other_file will be set to #NULL. - + @@ -63025,7 +66314,7 @@ In all the other cases, @other_file will be set to #NULL. - + @@ -63037,16 +66326,16 @@ In all the other cases, @other_file will be set to #NULL. glib:get-type="g_file_monitor_event_get_type" c:type="GFileMonitorEvent"> Specifies what type of event a monitor event is. + filename="gio/gioenums.h" + line="413">Specifies what type of event a monitor event is. a file changed. + filename="gio/gioenums.h" + line="415">a file changed. glib:nick="changes-done-hint" glib:name="G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT"> a hint that this was probably the last change in a set of changes. + filename="gio/gioenums.h" + line="416">a hint that this was probably the last change in a set of changes. glib:nick="deleted" glib:name="G_FILE_MONITOR_EVENT_DELETED"> a file was deleted. + filename="gio/gioenums.h" + line="417">a file was deleted. glib:nick="created" glib:name="G_FILE_MONITOR_EVENT_CREATED"> a file was created. + filename="gio/gioenums.h" + line="418">a file was created. glib:nick="attribute-changed" glib:name="G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED"> a file attribute was changed. + filename="gio/gioenums.h" + line="419">a file attribute was changed. glib:nick="pre-unmount" glib:name="G_FILE_MONITOR_EVENT_PRE_UNMOUNT"> the file location will soon be unmounted. + filename="gio/gioenums.h" + line="420">the file location will soon be unmounted. glib:nick="unmounted" glib:name="G_FILE_MONITOR_EVENT_UNMOUNTED"> the file location was unmounted. + filename="gio/gioenums.h" + line="421">the file location was unmounted. glib:nick="moved" glib:name="G_FILE_MONITOR_EVENT_MOVED"> the file was moved -- only sent if the + filename="gio/gioenums.h" + line="422">the file was moved -- only sent if the (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set glib:nick="renamed" glib:name="G_FILE_MONITOR_EVENT_RENAMED"> the file was renamed within the + filename="gio/gioenums.h" + line="424">the file was renamed within the current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. @@ -63129,8 +66418,8 @@ In all the other cases, @other_file will be set to #NULL. glib:nick="moved-in" glib:name="G_FILE_MONITOR_EVENT_MOVED_IN"> the file was moved into the + filename="gio/gioenums.h" + line="427">the file was moved into the monitored directory from another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. @@ -63140,8 +66429,8 @@ In all the other cases, @other_file will be set to #NULL. glib:nick="moved-out" glib:name="G_FILE_MONITOR_EVENT_MOVED_OUT"> the file was moved out of the + filename="gio/gioenums.h" + line="430">the file was moved out of the monitored directory to another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46 @@ -63151,16 +66440,16 @@ In all the other cases, @other_file will be set to #NULL. glib:get-type="g_file_monitor_flags_get_type" c:type="GFileMonitorFlags"> Flags used to set what a #GFileMonitor will watch for. + filename="gio/gioenums.h" + line="334">Flags used to set what a #GFileMonitor will watch for. No flags set. + filename="gio/gioenums.h" + line="336">No flags set. glib:nick="watch-mounts" glib:name="G_FILE_MONITOR_WATCH_MOUNTS"> Watch for mount events. + filename="gio/gioenums.h" + line="337">Watch for mount events. glib:nick="send-moved" glib:name="G_FILE_MONITOR_SEND_MOVED"> Pair DELETED and CREATED events caused + filename="gio/gioenums.h" + line="338">Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED @@ -63191,8 +66480,8 @@ In all the other cases, @other_file will be set to #NULL. glib:nick="watch-hard-links" glib:name="G_FILE_MONITOR_WATCH_HARD_LINKS"> Watch for changes to the file made + filename="gio/gioenums.h" + line="344">Watch for changes to the file made via another hard link. Since 2.36. glib:nick="watch-moves" glib:name="G_FILE_MONITOR_WATCH_MOVES"> Watch for rename operations on a + filename="gio/gioenums.h" + line="346">Watch for rename operations on a monitored directory. This causes %G_FILE_MONITOR_EVENT_RENAMED, %G_FILE_MONITOR_EVENT_MOVED_IN and %G_FILE_MONITOR_EVENT_MOVED_OUT events to be emitted when possible. Since: 2.46. @@ -63212,7 +66501,7 @@ In all the other cases, @other_file will be set to #NULL. c:type="GFileMonitorPrivate" disguised="1" opaque="1"> - + glib:get-type="g_file_output_stream_get_type" glib:type-struct="FileOutputStreamClass"> GFileOutputStream provides output streams that write their + filename="gio/gfileoutputstream.c" + line="35">`GFileOutputStream` provides output streams that write their content to a file. -GFileOutputStream implements #GSeekable, which allows the output +`GFileOutputStream` implements [iface@Gio.Seekable], which allows the output stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. -To find the position of a file output stream, use g_seekable_tell(). +To find the position of a file output stream, use [method@Gio.Seekable.tell]. To find out if a file output stream supports seeking, use -g_seekable_can_seek().To position a file output stream, use -g_seekable_seek(). To find out if a file output stream supports -truncating, use g_seekable_can_truncate(). To truncate a file output -stream, use g_seekable_truncate(). - +[method@Gio.Seekable.can_seek].To position a file output stream, use +[method@Gio.Seekable.seek]. To find out if a file output stream supports +truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file output +stream, use [method@Gio.Seekable.truncate]. + - + @@ -63251,7 +66540,7 @@ stream, use g_seekable_truncate(). - + @@ -63263,30 +66552,33 @@ stream, use g_seekable_truncate(). Gets the entity tag for the file when it has been written. + filename="gio/gfileoutputstream.c" + line="266">Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. + filename="gio/gfileoutputstream.c" + line="274">the entity tag for the stream. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="268">a #GFileOutputStream. - + Queries a file output stream for the given @attributes. + filename="gio/gfileoutputstream.c" + line="109">Queries a file output stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_output_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag @@ -63303,24 +66595,24 @@ If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. - + a #GFileInfo for the @stream, or %NULL on error. + filename="gio/gfileoutputstream.c" + line="134">a #GFileInfo for the @stream, or %NULL on error. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="111">a #GFileOutputStream. a file attribute query string. + filename="gio/gfileoutputstream.c" + line="112">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileoutputstream.c" + line="113">optional #GCancellable object, %NULL to ignore. - + Asynchronously queries the @stream for a #GFileInfo. When completed, + filename="gio/gfileoutputstream.c" + line="186">Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_output_stream_query_info_finish(). For the synchronous version of this function, see g_file_output_stream_query_info(). - + a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="188">a #GFileOutputStream. a file attribute query string. + filename="gio/gfileoutputstream.c" + line="189">a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request + filename="gio/gfileoutputstream.c" + line="190">the [I/O priority](iface.AsyncResult.html#io-priority) of the + request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileoutputstream.c" + line="192">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> callback to call when the request is satisfied + filename="gio/gfileoutputstream.c" + line="193">callback to call when the request is satisfied allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gfileoutputstream.c" + line="194">the data to pass to callback function @@ -63402,33 +66698,33 @@ g_file_output_stream_query_info(). invoker="query_info_finish" throws="1"> Finalizes the asynchronous query started + filename="gio/gfileoutputstream.c" + line="236">Finalizes the asynchronous query started by g_file_output_stream_query_info_async(). - + A #GFileInfo for the finished query. + filename="gio/gfileoutputstream.c" + line="245">A #GFileInfo for the finished query. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="238">a #GFileOutputStream. a #GAsyncResult. + filename="gio/gfileoutputstream.c" + line="239">a #GAsyncResult. - + @@ -63451,7 +66747,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63462,7 +66758,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63483,32 +66779,33 @@ by g_file_output_stream_query_info_async(). Gets the entity tag for the file when it has been written. + filename="gio/gfileoutputstream.c" + line="266">Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. + filename="gio/gfileoutputstream.c" + line="274">the entity tag for the stream. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="268">a #GFileOutputStream. + throws="1" + glib:async-func="query_info_async"> Queries a file output stream for the given @attributes. + filename="gio/gfileoutputstream.c" + line="109">Queries a file output stream for the given @attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_output_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag @@ -63525,24 +66822,24 @@ If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will be returned. - + a #GFileInfo for the @stream, or %NULL on error. + filename="gio/gfileoutputstream.c" + line="134">a #GFileInfo for the @stream, or %NULL on error. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="111">a #GFileOutputStream. a file attribute query string. + filename="gio/gfileoutputstream.c" + line="112">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileoutputstream.c" + line="113">optional #GCancellable object, %NULL to ignore. + c:identifier="g_file_output_stream_query_info_async" + glib:finish-func="query_info_finish" + glib:sync-func="query_info"> Asynchronously queries the @stream for a #GFileInfo. When completed, + filename="gio/gfileoutputstream.c" + line="186">Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_output_stream_query_info_finish(). For the synchronous version of this function, see g_file_output_stream_query_info(). - + a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="188">a #GFileOutputStream. a file attribute query string. + filename="gio/gfileoutputstream.c" + line="189">a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request + filename="gio/gfileoutputstream.c" + line="190">the [I/O priority](iface.AsyncResult.html#io-priority) of the + request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileoutputstream.c" + line="192">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> callback to call when the request is satisfied + filename="gio/gfileoutputstream.c" + line="193">callback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gfileoutputstream.c" + line="194">the data to pass to callback function @@ -63624,27 +66924,27 @@ g_file_output_stream_query_info(). c:identifier="g_file_output_stream_query_info_finish" throws="1"> Finalizes the asynchronous query started + filename="gio/gfileoutputstream.c" + line="236">Finalizes the asynchronous query started by g_file_output_stream_query_info_async(). - + A #GFileInfo for the finished query. + filename="gio/gfileoutputstream.c" + line="245">A #GFileInfo for the finished query. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="238">a #GFileOutputStream. a #GAsyncResult. + filename="gio/gfileoutputstream.c" + line="239">a #GAsyncResult. @@ -63660,13 +66960,13 @@ by g_file_output_stream_query_info_async(). - + - + @@ -63679,7 +66979,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63692,7 +66992,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63717,7 +67017,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63730,7 +67030,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63752,24 +67052,24 @@ by g_file_output_stream_query_info_async(). - + a #GFileInfo for the @stream, or %NULL on error. + filename="gio/gfileoutputstream.c" + line="134">a #GFileInfo for the @stream, or %NULL on error. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="111">a #GFileOutputStream. a file attribute query string. + filename="gio/gfileoutputstream.c" + line="112">a file attribute query string. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileoutputstream.c" + line="113">optional #GCancellable object, %NULL to ignore. @@ -63786,27 +67086,28 @@ by g_file_output_stream_query_info_async(). - + a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="188">a #GFileOutputStream. a file attribute query string. + filename="gio/gfileoutputstream.c" + line="189">a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request + filename="gio/gfileoutputstream.c" + line="190">the [I/O priority](iface.AsyncResult.html#io-priority) of the + request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gfileoutputstream.c" + line="192">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> callback to call when the request is satisfied + filename="gio/gfileoutputstream.c" + line="193">callback to call when the request is satisfied allow-none="1" closure="5"> the data to pass to callback function + filename="gio/gfileoutputstream.c" + line="194">the data to pass to callback function @@ -63844,24 +67145,24 @@ by g_file_output_stream_query_info_async(). - + A #GFileInfo for the finished query. + filename="gio/gfileoutputstream.c" + line="245">A #GFileInfo for the finished query. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="238">a #GFileOutputStream. a #GAsyncResult. + filename="gio/gfileoutputstream.c" + line="239">a #GAsyncResult. @@ -63869,18 +67170,18 @@ by g_file_output_stream_query_info_async(). - + the entity tag for the stream. + filename="gio/gfileoutputstream.c" + line="274">the entity tag for the stream. a #GFileOutputStream. + filename="gio/gfileoutputstream.c" + line="268">a #GFileOutputStream. @@ -63888,7 +67189,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63896,7 +67197,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63904,7 +67205,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63912,7 +67213,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63920,7 +67221,7 @@ by g_file_output_stream_query_info_async(). - + @@ -63931,29 +67232,29 @@ by g_file_output_stream_query_info_async(). c:type="GFileOutputStreamPrivate" disguised="1" opaque="1"> - + When doing file operations that may take a while, such as moving + filename="gio/giotypes.h" + line="194">When doing file operations that may take a while, such as moving a file or copying a file, a progress callback is used to pass how far along that operation is to the application. - + the current number of bytes in the operation. + filename="gio/giotypes.h" + line="196">the current number of bytes in the operation. the total number of bytes in the operation. + filename="gio/giotypes.h" + line="197">the total number of bytes in the operation. nullable="1" allow-none="1"> user data passed to the callback. + filename="gio/giotypes.h" + line="198">user data passed to the callback. @@ -63972,7 +67273,7 @@ far along that operation is to the application. glib:get-type="g_file_query_info_flags_get_type" c:type="GFileQueryInfoFlags"> Flags used when querying a #GFileInfo. glib:nick="none" glib:name="G_FILE_QUERY_INFO_NONE"> No flags set. glib:nick="nofollow-symlinks" glib:name="G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS"> Don't follow symlinks. When loading the partial contents of a file with g_file_load_partial_contents_async(), + filename="gio/giotypes.h" + line="208">When loading the partial contents of a file with g_file_load_partial_contents_async(), it may become necessary to determine if any more data from the file should be loaded. A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data should be read, or %FALSE otherwise. - + %TRUE if more data should be read back. %FALSE otherwise. + filename="gio/giotypes.h" + line="219">%TRUE if more data should be read back. %FALSE otherwise. the data as currently read. + filename="gio/giotypes.h" + line="210">the data as currently read. the size of the data currently read. + filename="gio/giotypes.h" + line="211">the size of the data currently read. nullable="1" allow-none="1"> data passed to the callback. + filename="gio/giotypes.h" + line="212">data passed to the callback. @@ -64036,8 +67337,8 @@ should be read, or %FALSE otherwise. glib:get-type="g_file_type_get_type" c:type="GFileType"> Indicates the file's on-disk type. + filename="gio/gioenums.h" + line="362">Indicates the file's on-disk type. On Windows systems a file will never have %G_FILE_TYPE_SYMBOLIC_LINK type; use #GFileInfo and %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK to determine @@ -64053,8 +67354,8 @@ which is why all Windows symlinks will continue to be reported as glib:nick="unknown" glib:name="G_FILE_TYPE_UNKNOWN"> File's type is unknown. + filename="gio/gioenums.h" + line="364">File's type is unknown. File handle represents a regular file. + filename="gio/gioenums.h" + line="365">File handle represents a regular file. File handle represents a directory. + filename="gio/gioenums.h" + line="366">File handle represents a directory. File handle represents a symbolic link + filename="gio/gioenums.h" + line="367">File handle represents a symbolic link (Unix systems). File is a "special" file, such as a socket, fifo, + filename="gio/gioenums.h" + line="369">File is a "special" file, such as a socket, fifo, block device, or character device. File is a shortcut (Windows systems). + filename="gio/gioenums.h" + line="371">File is a shortcut (Windows systems). File is a mountable location. + filename="gio/gioenums.h" + line="372">File is a mountable location. Completes partial file and directory names given a partial string by + filename="gio/gfilenamecompleter.c" + line="34">Completes partial file and directory names given a partial string by looking in the file system for clues. Can return a list of possible completion strings for widget implementations. - + Creates a new filename completer. - + filename="gio/gfilenamecompleter.c" + line="116">Creates a new filename completer. + a #GFilenameCompleter. + filename="gio/gfilenamecompleter.c" + line="121">a #GFilenameCompleter. - + @@ -64153,13 +67454,13 @@ completion strings for widget implementations. Obtains a completion for @initial_text from @completer. - + filename="gio/gfilenamecompleter.c" + line="399">Obtains a completion for @initial_text from @completer. + a completed string, or %NULL if no + filename="gio/gfilenamecompleter.c" + line="406">a completed string, or %NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished. @@ -64167,14 +67468,14 @@ completion strings for widget implementations. the filename completer. + filename="gio/gfilenamecompleter.c" + line="401">the filename completer. text to be completed. + filename="gio/gfilenamecompleter.c" + line="402">text to be completed. @@ -64182,13 +67483,13 @@ completion strings for widget implementations. Gets an array of completion strings for a given initial text. - + filename="gio/gfilenamecompleter.c" + line="453">Gets an array of completion strings for a given initial text. + array of strings with possible completions for @initial_text. + filename="gio/gfilenamecompleter.c" + line="460">array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished. @@ -64197,14 +67498,14 @@ This array must be freed by g_strfreev() when finished. the filename completer. + filename="gio/gfilenamecompleter.c" + line="455">the filename completer. text to be completed. + filename="gio/gfilenamecompleter.c" + line="456">text to be completed. @@ -64212,32 +67513,32 @@ This array must be freed by g_strfreev() when finished. If @dirs_only is %TRUE, @completer will only + filename="gio/gfilenamecompleter.c" + line="494">If @dirs_only is %TRUE, @completer will only complete directory names, and not file names. - + the filename completer. + filename="gio/gfilenamecompleter.c" + line="496">the filename completer. a #gboolean. + filename="gio/gfilenamecompleter.c" + line="497">a #gboolean. Emitted when the file name completion information comes available. + filename="gio/gfilenamecompleter.c" + line="97">Emitted when the file name completion information comes available. @@ -64246,13 +67547,13 @@ complete directory names, and not file names. - + - + @@ -64265,7 +67566,7 @@ complete directory names, and not file names. - + @@ -64273,7 +67574,7 @@ complete directory names, and not file names. - + @@ -64281,7 +67582,7 @@ complete directory names, and not file names. - + @@ -64293,8 +67594,8 @@ complete directory names, and not file names. glib:get-type="g_filesystem_preview_type_get_type" c:type="GFilesystemPreviewType"> Indicates a hint from the file system whether files should be + filename="gio/gioenums.h" + line="396">Indicates a hint from the file system whether files should be previewed in a file manager. Returned as the value of the key %G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. Only preview files if user has explicitly requested it. + filename="gio/gioenums.h" + line="398">Only preview files if user has explicitly requested it. Preview files if user has requested preview of "local" files. + filename="gio/gioenums.h" + line="399">Preview files if user has requested preview of "local" files. Never preview files. + filename="gio/gioenums.h" + line="400">Never preview files. Base class for input stream implementations that perform some + filename="gio/gfilterinputstream.c" + line="29">Base class for input stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. - + Gets the base stream for the filter stream. - + filename="gio/gfilterinputstream.c" + line="192">Gets the base stream for the filter stream. + a #GInputStream. + filename="gio/gfilterinputstream.c" + line="198">a #GInputStream. a #GFilterInputStream. + filename="gio/gfilterinputstream.c" + line="194">a #GFilterInputStream. @@ -64366,21 +67667,21 @@ and byte order flipping. c:identifier="g_filter_input_stream_get_close_base_stream" glib:get-property="close-base-stream"> Returns whether the base stream will be closed when @stream is + filename="gio/gfilterinputstream.c" + line="208">Returns whether the base stream will be closed when @stream is closed. - + %TRUE if the base stream will be closed. + filename="gio/gfilterinputstream.c" + line="215">%TRUE if the base stream will be closed. a #GFilterInputStream. + filename="gio/gfilterinputstream.c" + line="210">a #GFilterInputStream. @@ -64389,23 +67690,23 @@ closed. c:identifier="g_filter_input_stream_set_close_base_stream" glib:set-property="close-base-stream"> Sets whether the base stream will be closed when @stream is closed. - + filename="gio/gfilterinputstream.c" + line="229">Sets whether the base stream will be closed when @stream is closed. + a #GFilterInputStream. + filename="gio/gfilterinputstream.c" + line="231">a #GFilterInputStream. %TRUE to close the base stream. + filename="gio/gfilterinputstream.c" + line="232">%TRUE to close the base stream. @@ -64415,6 +67716,9 @@ closed. construct-only="1" transfer-ownership="none" getter="get_base_stream"> + The underlying base stream on which the I/O ops will be done. setter="set_close_base_stream" getter="get_close_base_stream" default-value="TRUE"> + Whether the base stream should be closed when the filter stream is closed. @@ -64436,13 +67743,13 @@ closed. - + - + @@ -64450,7 +67757,7 @@ closed. - + @@ -64458,7 +67765,7 @@ closed. - + @@ -64474,30 +67781,30 @@ closed. glib:get-type="g_filter_output_stream_get_type" glib:type-struct="FilterOutputStreamClass"> Base class for output stream implementations that perform some + filename="gio/gfilteroutputstream.c" + line="29">Base class for output stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. - + Gets the base stream for the filter stream. - + filename="gio/gfilteroutputstream.c" + line="196">Gets the base stream for the filter stream. + a #GOutputStream. + filename="gio/gfilteroutputstream.c" + line="202">a [class@Gio.OutputStream]. a #GFilterOutputStream. + filename="gio/gfilteroutputstream.c" + line="198">a [class@Gio.FilterOutputStream]. @@ -64506,21 +67813,21 @@ and byte order flipping. c:identifier="g_filter_output_stream_get_close_base_stream" glib:get-property="close-base-stream"> Returns whether the base stream will be closed when @stream is + filename="gio/gfilteroutputstream.c" + line="212">Returns whether the base stream will be closed when @stream is closed. - + %TRUE if the base stream will be closed. + filename="gio/gfilteroutputstream.c" + line="219">`TRUE` if the base stream will be closed. a #GFilterOutputStream. + filename="gio/gfilteroutputstream.c" + line="214">a [class@Gio.FilterOutputStream]. @@ -64528,23 +67835,23 @@ closed. Sets whether the base stream will be closed when @stream is closed. - + filename="gio/gfilteroutputstream.c" + line="233">Sets whether the base stream will be closed when @stream is closed. + a #GFilterOutputStream. + filename="gio/gfilteroutputstream.c" + line="235">a [class@Gio.FilterOutputStream]. %TRUE to close the base stream. + filename="gio/gfilteroutputstream.c" + line="236">`TRUE` to close the base stream. @@ -64554,6 +67861,9 @@ closed. construct-only="1" transfer-ownership="none" getter="get_base_stream"> + The underlying base stream on which the I/O ops will be done. transfer-ownership="none" getter="get_close_base_stream" default-value="TRUE"> + Whether the base stream should be closed when the filter stream is closed. @@ -64574,13 +67887,13 @@ closed. - + - + @@ -64588,7 +67901,7 @@ closed. - + @@ -64596,7 +67909,7 @@ closed. - + @@ -64604,7 +67917,7 @@ closed. - + @@ -64613,7 +67926,7 @@ closed. - + @@ -64622,7 +67935,7 @@ closed. - + @@ -64631,7 +67944,7 @@ closed. - + @@ -64640,7 +67953,7 @@ closed. - + @@ -64649,7 +67962,7 @@ closed. - + @@ -64658,7 +67971,7 @@ closed. - + @@ -64667,7 +67980,7 @@ closed. - + @@ -64676,7 +67989,7 @@ closed. - + @@ -64685,7 +67998,7 @@ closed. - + @@ -64694,7 +68007,7 @@ closed. - + @@ -64703,7 +68016,7 @@ closed. - + @@ -64712,7 +68025,7 @@ closed. - + @@ -64721,7 +68034,7 @@ closed. - + @@ -64730,7 +68043,7 @@ closed. - + @@ -64739,7 +68052,7 @@ closed. - + @@ -64751,8 +68064,8 @@ closed. c:type="GIOErrorEnum" glib:error-domain="g-io-error-quark"> Error codes returned by GIO functions. + filename="gio/gioenums.h" + line="456">Error codes returned by GIO functions. Note that this domain may be extended in future GLib releases. In general, new error codes either only apply to new APIs, or else @@ -64776,8 +68089,8 @@ See also #GPollableReturn for a cheaper way of returning glib:nick="failed" glib:name="G_IO_ERROR_FAILED"> Generic error condition for when an operation fails + filename="gio/gioenums.h" + line="458">Generic error condition for when an operation fails and no more specific #GIOErrorEnum value is defined. File not found. + filename="gio/gioenums.h" + line="460">File not found. File already exists. + filename="gio/gioenums.h" + line="461">File already exists. File is a directory. + filename="gio/gioenums.h" + line="462">File is a directory. File is not a directory. + filename="gio/gioenums.h" + line="463">File is not a directory. File is a directory that isn't empty. + filename="gio/gioenums.h" + line="464">File is a directory that isn't empty. File is not a regular file. + filename="gio/gioenums.h" + line="465">File is not a regular file. File is not a symbolic link. + filename="gio/gioenums.h" + line="466">File is not a symbolic link. File cannot be mounted. + filename="gio/gioenums.h" + line="467">File cannot be mounted. Filename is too many characters. + filename="gio/gioenums.h" + line="468">Filename is too many characters. Filename is invalid or contains invalid characters. + filename="gio/gioenums.h" + line="469">Filename is invalid or contains invalid characters. File contains too many symbolic links. + filename="gio/gioenums.h" + line="470">File contains too many symbolic links. No space left on drive. + filename="gio/gioenums.h" + line="471">No space left on drive. Invalid argument. + filename="gio/gioenums.h" + line="472">Invalid argument. Permission denied. + filename="gio/gioenums.h" + line="473">Permission denied. Operation (or one of its parameters) not supported + filename="gio/gioenums.h" + line="474">Operation (or one of its parameters) not supported File isn't mounted. + filename="gio/gioenums.h" + line="475">File isn't mounted. File is already mounted. + filename="gio/gioenums.h" + line="476">File is already mounted. File was closed. + filename="gio/gioenums.h" + line="477">File was closed. Operation was cancelled. See #GCancellable. + filename="gio/gioenums.h" + line="478">Operation was cancelled. See #GCancellable. Operations are still pending. + filename="gio/gioenums.h" + line="479">Operations are still pending. File is read only. + filename="gio/gioenums.h" + line="480">File is read only. Backup couldn't be created. + filename="gio/gioenums.h" + line="481">Backup couldn't be created. File's Entity Tag was incorrect. + filename="gio/gioenums.h" + line="482">File's Entity Tag was incorrect. Operation timed out. + filename="gio/gioenums.h" + line="483">Operation timed out. Operation would be recursive. + filename="gio/gioenums.h" + line="484">Operation would be recursive. File is busy. + filename="gio/gioenums.h" + line="485">File is busy. Operation would block. + filename="gio/gioenums.h" + line="486">Operation would block. Host couldn't be found (remote operations). + filename="gio/gioenums.h" + line="487">Host couldn't be found (remote operations). Operation would merge files. + filename="gio/gioenums.h" + line="488">Operation would merge files. Operation failed and a helper program has + filename="gio/gioenums.h" + line="489">Operation failed and a helper program has already interacted with the user. Do not display any error dialog. The current process has too many files + filename="gio/gioenums.h" + line="491">The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 @@ -65068,8 +68381,8 @@ See also #GPollableReturn for a cheaper way of returning glib:nick="not-initialized" glib:name="G_IO_ERROR_NOT_INITIALIZED"> The object has not been initialized. Since 2.22 + filename="gio/gioenums.h" + line="494">The object has not been initialized. Since 2.22 The requested address is already in use. Since 2.22 + filename="gio/gioenums.h" + line="495">The requested address is already in use. Since 2.22 Need more input to finish operation. Since 2.24 + filename="gio/gioenums.h" + line="496">Need more input to finish operation. Since 2.24 The input data was invalid. Since 2.24 + filename="gio/gioenums.h" + line="497">The input data was invalid. Since 2.24 A remote object generated an error that + filename="gio/gioenums.h" + line="498">A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the @@ -65117,8 +68430,8 @@ See also #GPollableReturn for a cheaper way of returning glib:nick="host-unreachable" glib:name="G_IO_ERROR_HOST_UNREACHABLE"> Host unreachable. Since 2.26 + filename="gio/gioenums.h" + line="503">Host unreachable. Since 2.26 Network unreachable. Since 2.26 + filename="gio/gioenums.h" + line="504">Network unreachable. Since 2.26 Connection refused. Since 2.26 + filename="gio/gioenums.h" + line="505">Connection refused. Since 2.26 Connection to proxy server failed. Since 2.26 + filename="gio/gioenums.h" + line="506">Connection to proxy server failed. Since 2.26 Proxy authentication failed. Since 2.26 + filename="gio/gioenums.h" + line="507">Proxy authentication failed. Since 2.26 Proxy server needs authentication. Since 2.26 + filename="gio/gioenums.h" + line="508">Proxy server needs authentication. Since 2.26 Proxy connection is not allowed by ruleset. + filename="gio/gioenums.h" + line="509">Proxy connection is not allowed by ruleset. Since 2.26 Broken pipe. Since 2.36 + filename="gio/gioenums.h" + line="511">Broken pipe. Since 2.36 Connection closed by peer. Note that this + filename="gio/gioenums.h" + line="512">Connection closed by peer. Note that this is the same code as %G_IO_ERROR_BROKEN_PIPE; before 2.44 some "connection closed" errors returned %G_IO_ERROR_BROKEN_PIPE, but others returned %G_IO_ERROR_FAILED. Now they should all return the same @@ -65203,8 +68516,8 @@ See also #GPollableReturn for a cheaper way of returning glib:nick="not-connected" glib:name="G_IO_ERROR_NOT_CONNECTED"> Transport endpoint is not connected. Since 2.44 + filename="gio/gioenums.h" + line="517">Transport endpoint is not connected. Since 2.44 Message too large. Since 2.48. + filename="gio/gioenums.h" + line="518">Message too large. Since 2.48. No such device found. Since 2.74 + filename="gio/gioenums.h" + line="519">No such device found. Since 2.74 + + + Destination address unset. Since 2.80 #GIOExtension is an opaque data structure and can only be accessed + filename="gio/giomodule.c" + line="252">#GIOExtension is an opaque data structure and can only be accessed using the following functions. - + Gets the name under which @extension was registered. + filename="gio/giomodule.c" + line="1675">Gets the name under which @extension was registered. Note that the same type may be registered as extension for multiple extension points, under different names. - + the name of @extension. + filename="gio/giomodule.c" + line="1684">the name of @extension. a #GIOExtension + filename="gio/giomodule.c" + line="1677">a #GIOExtension Gets the priority with which @extension was registered. - + filename="gio/giomodule.c" + line="1692">Gets the priority with which @extension was registered. + the priority of @extension + filename="gio/giomodule.c" + line="1698">the priority of @extension a #GIOExtension + filename="gio/giomodule.c" + line="1694">a #GIOExtension Gets the type associated with @extension. - + filename="gio/giomodule.c" + line="1661">Gets the type associated with @extension. + the type of @extension + filename="gio/giomodule.c" + line="1667">the type of @extension a #GIOExtension + filename="gio/giomodule.c" + line="1663">a #GIOExtension @@ -65298,21 +68620,21 @@ for multiple extension points, under different names. c:identifier="g_io_extension_ref_class" introspectable="0"> Gets a reference to the class for the type that is + filename="gio/giomodule.c" + line="1646">Gets a reference to the class for the type that is associated with @extension. - + the #GTypeClass for the type of @extension + filename="gio/giomodule.c" + line="1653">the #GTypeClass for the type of @extension a #GIOExtension + filename="gio/giomodule.c" + line="1648">a #GIOExtension @@ -65323,34 +68645,83 @@ associated with @extension. disguised="1" opaque="1"> #GIOExtensionPoint is an opaque data structure and can only be accessed -using the following functions. - + filename="gio/giomodule.c" + line="87">`GIOExtensionPoint` provides a mechanism for modules to extend the +functionality of the library or application that loaded it in an +organized fashion. + +An extension point is identified by a name, and it may optionally +require that any implementation must be of a certain type (or derived +thereof). Use [func@Gio.IOExtensionPoint.register] to register an +extension point, and [method@Gio.IOExtensionPoint.set_required_type] to +set a required type. + +A module can implement an extension point by specifying the +[type@GObject.Type] that implements the functionality. Additionally, each +implementation of an extension point has a name, and a priority. Use +[func@Gio.IOExtensionPoint.implement] to implement an extension point. + +```c +GIOExtensionPoint *ep; + +// Register an extension point +ep = g_io_extension_point_register ("my-extension-point"); +g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); +``` + +```c +// Implement an extension point +G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) +g_io_extension_point_implement ("my-extension-point", + my_example_impl_get_type (), + "my-example", + 10); +``` + + It is up to the code that registered the extension point how + it uses the implementations that have been associated with it. + Depending on the use case, it may use all implementations, or + only the one with the highest priority, or pick a specific + one by name. + + To avoid opening all modules just to find out what extension + points they implement, GIO makes use of a caching mechanism, + see [gio-querymodules](gio-querymodules.html). + You are expected to run this command after installing a + GIO module. + + The `GIO_EXTRA_MODULES` environment variable can be used to + specify additional directories to automatically load modules + from. This environment variable has the same syntax as the + `PATH`. If two modules have the same base name in different + directories, then the latter one will be ignored. If additional + directories are specified GIO will load modules from the built-in + directory last. + Finds a #GIOExtension for an extension point by name. - + filename="gio/giomodule.c" + line="1536">Finds a #GIOExtension for an extension point by name. + the #GIOExtension for @extension_point that has the + filename="gio/giomodule.c" + line="1543">the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name a #GIOExtensionPoint + filename="gio/giomodule.c" + line="1538">a #GIOExtensionPoint the name of the extension to get + filename="gio/giomodule.c" + line="1539">the name of the extension to get @@ -65358,14 +68729,14 @@ using the following functions. Gets a list of all extensions that implement this extension point. + filename="gio/giomodule.c" + line="1516">Gets a list of all extensions that implement this extension point. The list is sorted by priority, beginning with the highest priority. - + a #GList of + filename="gio/giomodule.c" + line="1523">a #GList of #GIOExtensions. The list is owned by GIO and should not be modified. @@ -65375,8 +68746,8 @@ The list is sorted by priority, beginning with the highest priority. a #GIOExtensionPoint + filename="gio/giomodule.c" + line="1518">a #GIOExtensionPoint @@ -65384,21 +68755,21 @@ The list is sorted by priority, beginning with the highest priority. Gets the required type for @extension_point. - + filename="gio/giomodule.c" + line="1480">Gets the required type for @extension_point. + the #GType that all implementations must have, + filename="gio/giomodule.c" + line="1486">the #GType that all implementations must have, or %G_TYPE_INVALID if the extension point has no required type a #GIOExtensionPoint + filename="gio/giomodule.c" + line="1482">a #GIOExtensionPoint @@ -65406,108 +68777,108 @@ The list is sorted by priority, beginning with the highest priority. Sets the required type for @extension_point to @type. + filename="gio/giomodule.c" + line="1465">Sets the required type for @extension_point to @type. All implementations must henceforth have this type. - + a #GIOExtensionPoint + filename="gio/giomodule.c" + line="1467">a #GIOExtensionPoint the #GType to require + filename="gio/giomodule.c" + line="1468">the #GType to require Registers @type as extension for the extension point with name + filename="gio/giomodule.c" + line="1582">Registers @type as extension for the extension point with name @extension_point_name. If @type has already been registered as an extension for this extension point, the existing #GIOExtension object is returned. - + a #GIOExtension object for #GType + filename="gio/giomodule.c" + line="1595">a #GIOExtension object for #GType the name of the extension point + filename="gio/giomodule.c" + line="1584">the name of the extension point the #GType to register as extension + filename="gio/giomodule.c" + line="1585">the #GType to register as extension the name for the extension + filename="gio/giomodule.c" + line="1586">the name for the extension the priority for the extension + filename="gio/giomodule.c" + line="1587">the priority for the extension Looks up an existing extension point. - + filename="gio/giomodule.c" + line="1440">Looks up an existing extension point. + the #GIOExtensionPoint, or %NULL if there + filename="gio/giomodule.c" + line="1446">the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. the name of the extension point + filename="gio/giomodule.c" + line="1442">the name of the extension point Registers an extension point. - + filename="gio/giomodule.c" + line="1402">Registers an extension point. + the new #GIOExtensionPoint. This object is + filename="gio/giomodule.c" + line="1408">the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. The name of the extension point + filename="gio/giomodule.c" + line="1404">The name of the extension point @@ -65521,38 +68892,38 @@ extension point, the existing #GIOExtension object is returned. glib:get-type="g_io_module_get_type" glib:type-struct="IOModuleClass"> Provides an interface and default functions for loading and unloading + filename="gio/giomodule.c" + line="79">Provides an interface and default functions for loading and unloading modules. This is used internally to make GIO extensible, but can also be used by others to implement module loading. - + Creates a new GIOModule that will load the specific + filename="gio/giomodule.c" + line="391">Creates a new GIOModule that will load the specific shared library when in use. - + a #GIOModule from given @filename, + filename="gio/giomodule.c" + line="398">a #GIOModule from given @filename, or %NULL on error. filename of the shared library module. + filename="gio/giomodule.c" + line="393">filename of the shared library module. Optional API for GIO modules to implement. + filename="gio/giomodule.h" + line="148">Optional API for GIO modules to implement. Should return a list of all the extension points that may be implemented in this module. @@ -65583,11 +68954,11 @@ throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. - + A %NULL-terminated array of strings, + filename="gio/giomodule.h" + line="183">A %NULL-terminated array of strings, listing the supported extension points of the module. The array must be suitable for freeing with g_strfreev(). @@ -65597,8 +68968,8 @@ for static builds. Required API for GIO modules to implement. + filename="gio/giomodule.h" + line="107">Required API for GIO modules to implement. This function is run after the module has been loaded into GIO, to initialize the module. Typically, this function will call @@ -65611,15 +68982,15 @@ throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. - + a #GIOModule. + filename="gio/giomodule.h" + line="109">a #GIOModule. @@ -65628,8 +68999,8 @@ for static builds. c:identifier="g_io_module_unload" introspectable="0"> Required API for GIO modules to implement. + filename="gio/giomodule.h" + line="128">Required API for GIO modules to implement. This function is run when the module is being unloaded from GIO, to finalize the module. @@ -65641,15 +69012,15 @@ throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. - + a #GIOModule. + filename="gio/giomodule.h" + line="130">a #GIOModule. @@ -65660,7 +69031,7 @@ for static builds. disguised="1" opaque="1" glib:is-gtype-struct-for="IOModule"> - + opaque="1" version="2.30"> Represents a scope for loading IO modules. A scope can be used for blocking + filename="gio/giomodule.c" + line="143">Represents a scope for loading IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load. The scope can be used with g_io_modules_load_all_in_directory_with_scope() or g_io_modules_scan_all_in_directory_with_scope(). - + Block modules with the given @basename from being loaded when + filename="gio/giomodule.c" + line="200">Block modules with the given @basename from being loaded when this scope is used with g_io_modules_scan_all_in_directory_with_scope() or g_io_modules_load_all_in_directory_with_scope(). - + a module loading scope + filename="gio/giomodule.c" + line="202">a module loading scope the basename to block + filename="gio/giomodule.c" + line="203">the basename to block Free a module scope. - + filename="gio/giomodule.c" + line="183">Free a module scope. + a module loading scope + filename="gio/giomodule.c" + line="185">a module loading scope @@ -65724,25 +69095,25 @@ or g_io_modules_load_all_in_directory_with_scope(). version="2.30" introspectable="0"> Create a new scope for loading of IO modules. A scope can be used for + filename="gio/giomodule.c" + line="159">Create a new scope for loading of IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load. Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules which have the same base name as a module that has already been seen in this scope. - + the new module scope + filename="gio/giomodule.c" + line="170">the new module scope flags for the new scope + filename="gio/giomodule.c" + line="161">flags for the new scope @@ -65754,16 +69125,16 @@ in this scope. glib:get-type="g_io_module_scope_flags_get_type" c:type="GIOModuleScopeFlags"> Flags for use with g_io_module_scope_new(). + filename="gio/gioenums.h" + line="1917">Flags for use with g_io_module_scope_new(). No module scan flags + filename="gio/gioenums.h" + line="1919">No module scan flags glib:nick="block-duplicates" glib:name="G_IO_MODULE_SCOPE_BLOCK_DUPLICATES"> When using this scope to load or + filename="gio/gioenums.h" + line="1920">When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module. @@ -65780,32 +69151,37 @@ in this scope. - Opaque class for defining and scheduling IO jobs. - + opaque="1" + deprecated="1" + deprecated-version="2.36"> + Opaque class for defining and scheduling IO jobs. + Use [struct@GLib.ThreadPool] or + [method@Gio.Task.run_in_thread] + + deprecated="1" + deprecated-version="2.36"> Used from an I/O job to send a callback to be run in the thread + filename="gio/gioscheduler.c" + line="214">Used from an I/O job to send a callback to be run in the thread that the job was started from, waiting for the result (and thus blocking the I/O job). Use g_main_context_invoke(). - + The return value of @func + filename="gio/gioscheduler.c" + line="225">The return value of @func a #GIOSchedulerJob + filename="gio/gioscheduler.c" + line="216">a #GIOSchedulerJob closure="1" destroy="2"> a #GSourceFunc callback that will be called in the original thread + filename="gio/gioscheduler.c" + line="217">a #GSourceFunc callback that will be called in the original thread nullable="1" allow-none="1"> data to pass to @func + filename="gio/gioscheduler.c" + line="218">data to pass to @func allow-none="1" scope="async"> a #GDestroyNotify for @user_data, or %NULL + filename="gio/gioscheduler.c" + line="219">a #GDestroyNotify for @user_data, or %NULL + deprecated="1" + deprecated-version="2.36"> Used from an I/O job to send a callback to be run asynchronously in + filename="gio/gioscheduler.c" + line="269">Used from an I/O job to send a callback to be run asynchronously in the thread that the job was started from. The callback will be run when the main loop is available, but at that time the I/O job might have finished. The return value from the callback is ignored. @@ -65854,15 +69231,15 @@ on to this function you have to ensure that it is not freed before @func is called, either by passing %NULL as @notify to g_io_scheduler_push_job() or by using refcounting for @user_data. Use g_main_context_invoke(). - + a #GIOSchedulerJob + filename="gio/gioscheduler.c" + line="271">a #GIOSchedulerJob closure="1" destroy="2"> a #GSourceFunc callback that will be called in the original thread + filename="gio/gioscheduler.c" + line="272">a #GSourceFunc callback that will be called in the original thread nullable="1" allow-none="1"> data to pass to @func + filename="gio/gioscheduler.c" + line="273">data to pass to @func allow-none="1" scope="async"> a #GDestroyNotify for @user_data, or %NULL + filename="gio/gioscheduler.c" + line="274">a #GDestroyNotify for @user_data, or %NULL - + I/O Job function. + filename="gio/giotypes.h" + line="269">I/O Job function. Long-running jobs should periodically check the @cancellable to see if they have been cancelled. - + Use [struct@GLib.ThreadPool] or + [method@Gio.Task.run_in_thread] + %TRUE if this function should be called again to + filename="gio/giotypes.h" + line="280">%TRUE if this function should be called again to complete the job, %FALSE if the job is complete (or cancelled) a #GIOSchedulerJob. + filename="gio/giotypes.h" + line="271">a #GIOSchedulerJob. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/giotypes.h" + line="272">optional #GCancellable object, %NULL to ignore. nullable="1" allow-none="1"> data passed to the callback function + filename="gio/giotypes.h" + line="273">data passed to the callback function @@ -65949,81 +69331,86 @@ to see if they have been cancelled. glib:get-type="g_io_stream_get_type" glib:type-struct="IOStreamClass"> GIOStream represents an object that has both read and write streams. + filename="gio/giostream.c" + line="34">`GIOStream` represents an object that has both read and write streams. Generally the two streams act as separate input and output streams, but they share some common resources and state. For instance, for seekable streams, both streams may use the same position. -Examples of #GIOStream objects are #GSocketConnection, which represents -a two-way network connection; and #GFileIOStream, which represents a +Examples of `GIOStream` objects are [class@Gio.SocketConnection], which represents +a two-way network connection; and [class@Gio.FileIOStream], which represents a file handle opened in read-write mode. To do the actual reading and writing you need to get the substreams -with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). +with [method@Gio.IOStream.get_input_stream] and +[method@Gio.IOStream.get_output_stream]. -The #GIOStream object owns the input and the output streams, not the other -way around, so keeping the substreams alive will not keep the #GIOStream -object alive. If the #GIOStream object is freed it will be closed, thus +The `GIOStream` object owns the input and the output streams, not the other +way around, so keeping the substreams alive will not keep the `GIOStream` +object alive. If the `GIOStream` object is freed it will be closed, thus closing the substreams, so even if the substreams stay alive they will -always return %G_IO_ERROR_CLOSED for all operations. +always return `G_IO_ERROR_CLOSED` for all operations. -To close a stream use g_io_stream_close() which will close the common +To close a stream use [method@Gio.IOStream.close] which will close the common stream object and also the individual substreams. You can also close the substreams themselves. In most cases this only marks the substream as closed, so further I/O on it fails but common state in the -#GIOStream may still be open. However, some streams may support -"half-closed" states where one direction of the stream is actually shut down. - -Operations on #GIOStreams cannot be started while another operation on the -#GIOStream or its substreams is in progress. Specifically, an application can -read from the #GInputStream and write to the #GOutputStream simultaneously -(either in separate threads, or as asynchronous operations in the same -thread), but an application cannot start any #GIOStream operation while there -is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and -an application can’t start any #GInputStream or #GOutputStream operation -while there is a #GIOStream operation in progress. +`GIOStream` may still be open. However, some streams may support +‘half-closed’ states where one direction of the stream is actually shut down. + +Operations on `GIOStream`s cannot be started while another operation on the +`GIOStream` or its substreams is in progress. Specifically, an application can +read from the [class@Gio.InputStream] and write to the +[class@Gio.OutputStream] simultaneously (either in separate threads, or as +asynchronous operations in the same thread), but an application cannot start +any `GIOStream` operation while there is a `GIOStream`, `GInputStream` or +`GOutputStream` operation in progress, and an application can’t start any +`GInputStream` or `GOutputStream` operation while there is a `GIOStream` +operation in progress. This is a product of individual stream operations being associated with a -given #GMainContext (the thread-default context at the time the operation was -started), rather than entire streams being associated with a single -#GMainContext. +given [type@GLib.MainContext] (the thread-default context at the time the +operation was started), rather than entire streams being associated with a +single `GMainContext`. -GIO may run operations on #GIOStreams from other (worker) threads, and this +GIO may run operations on `GIOStream`s from other (worker) threads, and this may be exposed to application code in the behaviour of wrapper streams, such -as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs, -application code may only run operations on the base (wrapped) stream when -the wrapper stream is idle. Note that the semantics of such operations may -not be well-defined due to the state the wrapper stream leaves the base -stream in (though they are guaranteed not to crash). - +as [class@Gio.BufferedInputStream] or [class@Gio.TlsConnection]. With such +wrapper APIs, application code may only run operations on the base (wrapped) +stream when the wrapper stream is idle. Note that the semantics of such +operations may not be well-defined due to the state the wrapper stream leaves +the base stream in (though they are guaranteed not to crash). + Finishes an asynchronous io stream splice operation. - + filename="gio/giostream.c" + line="920">Finishes an asynchronous io stream splice operation. + %TRUE on success, %FALSE otherwise. + filename="gio/giostream.c" + line="928">%TRUE on success, %FALSE otherwise. a #GAsyncResult. + filename="gio/giostream.c" + line="922">a #GAsyncResult. - + Requests an asynchronous close of the stream, releasing resources + filename="gio/giostream.c" + line="477">Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_io_stream_close_finish() to get the result of the operation. @@ -66033,21 +69420,21 @@ For behaviour details see g_io_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + a #GIOStream + filename="gio/giostream.c" + line="479">a #GIOStream the io priority of the request + filename="gio/giostream.c" + line="480">the io priority of the request nullable="1" allow-none="1"> optional cancellable object + filename="gio/giostream.c" + line="481">optional cancellable object scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/giostream.c" + line="482">a #GAsyncReadyCallback to call when the request is satisfied @@ -66077,8 +69464,8 @@ classes. However, if you override one you must override all. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/giostream.c" + line="484">the data to pass to callback function @@ -66088,32 +69475,32 @@ classes. However, if you override one you must override all. version="2.22" throws="1"> Closes a stream. - + filename="gio/giostream.c" + line="535">Closes a stream. + %TRUE if stream was successfully closed, %FALSE otherwise. + filename="gio/giostream.c" + line="544">%TRUE if stream was successfully closed, %FALSE otherwise. a #GIOStream + filename="gio/giostream.c" + line="537">a #GIOStream a #GAsyncResult + filename="gio/giostream.c" + line="538">a #GAsyncResult - + @@ -66133,22 +69520,22 @@ classes. However, if you override one you must override all. invoker="get_input_stream" version="2.22"> Gets the input stream for this object. This is used + filename="gio/giostream.c" + line="229">Gets the input stream for this object. This is used for reading. - + a #GInputStream, owned by the #GIOStream. + filename="gio/giostream.c" + line="236">a #GInputStream, owned by the #GIOStream. Do not free. a #GIOStream + filename="gio/giostream.c" + line="231">a #GIOStream @@ -66157,22 +69544,22 @@ Do not free. invoker="get_output_stream" version="2.22"> Gets the output stream for this object. This is used for + filename="gio/giostream.c" + line="253">Gets the output stream for this object. This is used for writing. - + a #GOutputStream, owned by the #GIOStream. + filename="gio/giostream.c" + line="260">a #GOutputStream, owned by the #GIOStream. Do not free. a #GIOStream + filename="gio/giostream.c" + line="255">a #GIOStream @@ -66181,17 +69568,17 @@ Do not free. c:identifier="g_io_stream_clear_pending" version="2.22"> Clears the pending flag on @stream. - + filename="gio/giostream.c" + line="335">Clears the pending flag on @stream. + a #GIOStream + filename="gio/giostream.c" + line="337">a #GIOStream @@ -66199,10 +69586,11 @@ Do not free. + throws="1" + glib:async-func="close_async"> Closes the stream, releasing resources related to it. This will also + filename="gio/giostream.c" + line="372">Closes the stream, releasing resources related to it. This will also close the individual input and output streams, if they are not already closed. @@ -66235,18 +69623,18 @@ can use a faster close that doesn't block to e.g. check errors. The default implementation of this method just calls close on the individual input/output streams. - + %TRUE on success, %FALSE on failure + filename="gio/giostream.c" + line="412">%TRUE on success, %FALSE on failure a #GIOStream + filename="gio/giostream.c" + line="374">a #GIOStream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/giostream.c" + line="375">optional #GCancellable object, %NULL to ignore + version="2.22" + glib:finish-func="close_finish" + glib:sync-func="close"> Requests an asynchronous close of the stream, releasing resources + filename="gio/giostream.c" + line="477">Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_io_stream_close_finish() to get the result of the operation. @@ -66275,21 +69665,21 @@ For behaviour details see g_io_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + a #GIOStream + filename="gio/giostream.c" + line="479">a #GIOStream the io priority of the request + filename="gio/giostream.c" + line="480">the io priority of the request nullable="1" allow-none="1"> optional cancellable object + filename="gio/giostream.c" + line="481">optional cancellable object scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/giostream.c" + line="482">a #GAsyncReadyCallback to call when the request is satisfied @@ -66318,8 +69708,8 @@ classes. However, if you override one you must override all. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/giostream.c" + line="484">the data to pass to callback function @@ -66329,26 +69719,26 @@ classes. However, if you override one you must override all. version="2.22" throws="1"> Closes a stream. - + filename="gio/giostream.c" + line="535">Closes a stream. + %TRUE if stream was successfully closed, %FALSE otherwise. + filename="gio/giostream.c" + line="544">%TRUE if stream was successfully closed, %FALSE otherwise. a #GIOStream + filename="gio/giostream.c" + line="537">a #GIOStream a #GAsyncResult + filename="gio/giostream.c" + line="538">a #GAsyncResult @@ -66358,22 +69748,22 @@ classes. However, if you override one you must override all. glib:get-property="input-stream" version="2.22"> Gets the input stream for this object. This is used + filename="gio/giostream.c" + line="229">Gets the input stream for this object. This is used for reading. - + a #GInputStream, owned by the #GIOStream. + filename="gio/giostream.c" + line="236">a #GInputStream, owned by the #GIOStream. Do not free. a #GIOStream + filename="gio/giostream.c" + line="231">a #GIOStream @@ -66383,22 +69773,22 @@ Do not free. glib:get-property="output-stream" version="2.22"> Gets the output stream for this object. This is used for + filename="gio/giostream.c" + line="253">Gets the output stream for this object. This is used for writing. - + a #GOutputStream, owned by the #GIOStream. + filename="gio/giostream.c" + line="260">a #GOutputStream, owned by the #GIOStream. Do not free. a #GIOStream + filename="gio/giostream.c" + line="255">a #GIOStream @@ -66407,42 +69797,43 @@ Do not free. c:identifier="g_io_stream_has_pending" version="2.22"> Checks if a stream has pending actions. - + filename="gio/giostream.c" + line="276">Checks if a stream has pending actions. + %TRUE if @stream has pending actions. + filename="gio/giostream.c" + line="282">%TRUE if @stream has pending actions. a #GIOStream + filename="gio/giostream.c" + line="278">a #GIOStream Checks if a stream is closed. - + filename="gio/giostream.c" + line="211">Checks if a stream is closed. + %TRUE if the stream is closed. + filename="gio/giostream.c" + line="217">%TRUE if the stream is closed. a #GIOStream + filename="gio/giostream.c" + line="213">a #GIOStream @@ -66452,22 +69843,22 @@ Do not free. version="2.22" throws="1"> Sets @stream to have actions pending. If the pending flag is + filename="gio/giostream.c" + line="294">Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. - + %TRUE if pending was previously unset and is now set. + filename="gio/giostream.c" + line="304">%TRUE if pending was previously unset and is now set. a #GIOStream + filename="gio/giostream.c" + line="296">a #GIOStream @@ -66476,41 +69867,41 @@ already set or @stream is closed, it will return %FALSE and set c:identifier="g_io_stream_splice_async" version="2.28"> Asynchronously splice the output stream of @stream1 to the input stream of + filename="gio/giostream.c" + line="841">Asynchronously splice the output stream of @stream1 to the input stream of @stream2, and splice the output stream of @stream2 to the input stream of @stream1. When the operation is finished @callback will be called. You can then call g_io_stream_splice_finish() to get the result of the operation. - + a #GIOStream. + filename="gio/giostream.c" + line="843">a #GIOStream. a #GIOStream. + filename="gio/giostream.c" + line="844">a #GIOStream. a set of #GIOStreamSpliceFlags. + filename="gio/giostream.c" + line="845">a set of #GIOStreamSpliceFlags. the io priority of the request. + filename="gio/giostream.c" + line="846">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/giostream.c" + line="847">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/giostream.c" + line="848">a #GAsyncReadyCallback to call when the request is satisfied @@ -66539,23 +69930,38 @@ result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/giostream.c" + line="850">the data to pass to callback function - + + Whether the stream is closed. + The [class@Gio.InputStream] to read from. + The [class@Gio.OutputStream] to write to. @@ -66569,30 +69975,30 @@ result of the operation. c:type="GIOStreamAdapter" disguised="1" opaque="1"> - + - + - + a #GInputStream, owned by the #GIOStream. + filename="gio/giostream.c" + line="236">a #GInputStream, owned by the #GIOStream. Do not free. a #GIOStream + filename="gio/giostream.c" + line="231">a #GIOStream @@ -66600,19 +70006,19 @@ Do not free. - + a #GOutputStream, owned by the #GIOStream. + filename="gio/giostream.c" + line="260">a #GOutputStream, owned by the #GIOStream. Do not free. a #GIOStream + filename="gio/giostream.c" + line="255">a #GIOStream @@ -66620,7 +70026,7 @@ Do not free. - + @@ -66639,21 +70045,21 @@ Do not free. - + a #GIOStream + filename="gio/giostream.c" + line="479">a #GIOStream the io priority of the request + filename="gio/giostream.c" + line="480">the io priority of the request nullable="1" allow-none="1"> optional cancellable object + filename="gio/giostream.c" + line="481">optional cancellable object scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/giostream.c" + line="482">a #GAsyncReadyCallback to call when the request is satisfied @@ -66683,8 +70089,8 @@ Do not free. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/giostream.c" + line="484">the data to pass to callback function @@ -66692,24 +70098,24 @@ Do not free. - + %TRUE if stream was successfully closed, %FALSE otherwise. + filename="gio/giostream.c" + line="544">%TRUE if stream was successfully closed, %FALSE otherwise. a #GIOStream + filename="gio/giostream.c" + line="537">a #GIOStream a #GAsyncResult + filename="gio/giostream.c" + line="538">a #GAsyncResult @@ -66717,7 +70123,7 @@ Do not free. - + @@ -66725,7 +70131,7 @@ Do not free. - + @@ -66733,7 +70139,7 @@ Do not free. - + @@ -66741,7 +70147,7 @@ Do not free. - + @@ -66749,7 +70155,7 @@ Do not free. - + @@ -66757,7 +70163,7 @@ Do not free. - + @@ -66765,7 +70171,7 @@ Do not free. - + @@ -66773,7 +70179,7 @@ Do not free. - + @@ -66781,7 +70187,7 @@ Do not free. - + @@ -66789,7 +70195,7 @@ Do not free. - + @@ -66800,7 +70206,7 @@ Do not free. c:type="GIOStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_io_stream_splice_flags_get_type" c:type="GIOStreamSpliceFlags"> GIOStreamSpliceFlags determine how streams should be spliced. + filename="gio/gioenums.h" + line="672">GIOStreamSpliceFlags determine how streams should be spliced. Do not close either stream. + filename="gio/gioenums.h" + line="674">Do not close either stream. glib:nick="close-stream1" glib:name="G_IO_STREAM_SPLICE_CLOSE_STREAM1"> Close the first stream after + filename="gio/gioenums.h" + line="675">Close the first stream after the splice. glib:nick="close-stream2" glib:name="G_IO_STREAM_SPLICE_CLOSE_STREAM2"> Close the second stream after + filename="gio/gioenums.h" + line="677">Close the second stream after the splice. glib:nick="wait-for-both" glib:name="G_IO_STREAM_SPLICE_WAIT_FOR_BOTH"> Wait for both splice operations to finish + filename="gio/gioenums.h" + line="679">Wait for both splice operations to finish before calling the callback. - + @@ -66862,7 +70268,7 @@ Do not free. - + @@ -66871,7 +70277,7 @@ Do not free. - + @@ -66880,7 +70286,7 @@ Do not free. - + @@ -66889,7 +70295,7 @@ Do not free. - + @@ -66898,7 +70304,7 @@ Do not free. - + @@ -66907,7 +70313,7 @@ Do not free. - + @@ -66916,7 +70322,7 @@ Do not free. - + @@ -66925,7 +70331,7 @@ Do not free. - + @@ -66934,7 +70340,7 @@ Do not free. - + @@ -66943,7 +70349,7 @@ Do not free. - + @@ -66952,7 +70358,7 @@ Do not free. - + @@ -66961,7 +70367,7 @@ Do not free. - + @@ -66970,7 +70376,7 @@ Do not free. - + @@ -66979,7 +70385,7 @@ Do not free. - + @@ -66988,7 +70394,7 @@ Do not free. - + @@ -66997,7 +70403,7 @@ Do not free. - + @@ -67006,7 +70412,7 @@ Do not free. - + @@ -67015,7 +70421,7 @@ Do not free. - + @@ -67024,7 +70430,7 @@ Do not free. - + @@ -67033,7 +70439,7 @@ Do not free. - + @@ -67042,7 +70448,7 @@ Do not free. - + @@ -67051,7 +70457,7 @@ Do not free. - + @@ -67060,7 +70466,7 @@ Do not free. - + @@ -67069,7 +70475,7 @@ Do not free. - + @@ -67078,7 +70484,7 @@ Do not free. - + @@ -67087,7 +70493,7 @@ Do not free. - + @@ -67096,7 +70502,7 @@ Do not free. - + @@ -67105,7 +70511,7 @@ Do not free. - + @@ -67114,7 +70520,7 @@ Do not free. - + @@ -67123,7 +70529,7 @@ Do not free. - + @@ -67132,7 +70538,7 @@ Do not free. - + @@ -67141,7 +70547,7 @@ Do not free. - + @@ -67150,7 +70556,7 @@ Do not free. - + @@ -67159,7 +70565,7 @@ Do not free. - + @@ -67168,7 +70574,7 @@ Do not free. - + @@ -67177,7 +70583,7 @@ Do not free. - + @@ -67186,7 +70592,7 @@ Do not free. - + @@ -67195,7 +70601,7 @@ Do not free. - + @@ -67204,7 +70610,7 @@ Do not free. - + @@ -67213,7 +70619,7 @@ Do not free. - + @@ -67222,7 +70628,7 @@ Do not free. - + @@ -67231,7 +70637,7 @@ Do not free. - + @@ -67240,7 +70646,7 @@ Do not free. - + @@ -67249,7 +70655,7 @@ Do not free. - + @@ -67258,7 +70664,7 @@ Do not free. - + @@ -67267,7 +70673,7 @@ Do not free. - + @@ -67276,7 +70682,7 @@ Do not free. - + @@ -67285,7 +70691,7 @@ Do not free. - + @@ -67294,7 +70700,7 @@ Do not free. - + @@ -67303,7 +70709,7 @@ Do not free. - + @@ -67312,7 +70718,7 @@ Do not free. - + @@ -67321,7 +70727,7 @@ Do not free. - + @@ -67330,7 +70736,7 @@ Do not free. - + @@ -67339,7 +70745,7 @@ Do not free. - + @@ -67348,7 +70754,7 @@ Do not free. - + @@ -67357,7 +70763,7 @@ Do not free. - + @@ -67366,7 +70772,7 @@ Do not free. - + @@ -67375,7 +70781,7 @@ Do not free. - + @@ -67384,7 +70790,7 @@ Do not free. - + @@ -67393,7 +70799,7 @@ Do not free. - + @@ -67402,7 +70808,7 @@ Do not free. - + @@ -67411,7 +70817,7 @@ Do not free. - + @@ -67420,7 +70826,7 @@ Do not free. - + @@ -67429,7 +70835,7 @@ Do not free. - + @@ -67438,7 +70844,7 @@ Do not free. - + @@ -67447,7 +70853,7 @@ Do not free. - + @@ -67456,7 +70862,7 @@ Do not free. - + @@ -67465,7 +70871,7 @@ Do not free. - + @@ -67474,7 +70880,7 @@ Do not free. - + @@ -67483,7 +70889,7 @@ Do not free. - + @@ -67492,7 +70898,7 @@ Do not free. - + @@ -67501,7 +70907,7 @@ Do not free. - + @@ -67510,7 +70916,7 @@ Do not free. - + @@ -67519,7 +70925,7 @@ Do not free. - + @@ -67528,7 +70934,7 @@ Do not free. - + @@ -67537,14 +70943,14 @@ Do not free. - + - + @@ -67553,7 +70959,7 @@ Do not free. - + @@ -67562,7 +70968,7 @@ Do not free. - + @@ -67571,7 +70977,7 @@ Do not free. - + @@ -67580,7 +70986,7 @@ Do not free. - + @@ -67589,7 +70995,7 @@ Do not free. - + @@ -67598,7 +71004,7 @@ Do not free. - + @@ -67607,7 +71013,7 @@ Do not free. - + @@ -67616,7 +71022,7 @@ Do not free. - + @@ -67625,7 +71031,7 @@ Do not free. - + @@ -67634,7 +71040,7 @@ Do not free. - + @@ -67643,7 +71049,7 @@ Do not free. - + @@ -67652,7 +71058,7 @@ Do not free. - + @@ -67661,7 +71067,7 @@ Do not free. - + @@ -67670,7 +71076,7 @@ Do not free. - + @@ -67679,7 +71085,7 @@ Do not free. - + @@ -67688,7 +71094,7 @@ Do not free. - + @@ -67697,7 +71103,7 @@ Do not free. - + @@ -67706,7 +71112,7 @@ Do not free. - + @@ -67715,7 +71121,7 @@ Do not free. - + @@ -67724,7 +71130,7 @@ Do not free. - + @@ -67733,14 +71139,14 @@ Do not free. - + - + @@ -67749,7 +71155,7 @@ Do not free. - + @@ -67758,7 +71164,7 @@ Do not free. - + @@ -67767,7 +71173,7 @@ Do not free. - + @@ -67776,7 +71182,7 @@ Do not free. - + @@ -67785,7 +71191,7 @@ Do not free. - + @@ -67794,7 +71200,7 @@ Do not free. - + @@ -67803,7 +71209,7 @@ Do not free. - + @@ -67812,7 +71218,7 @@ Do not free. - + @@ -67821,7 +71227,7 @@ Do not free. - + @@ -67830,7 +71236,7 @@ Do not free. - + @@ -67839,7 +71245,7 @@ Do not free. - + @@ -67848,7 +71254,7 @@ Do not free. - + @@ -67857,7 +71263,7 @@ Do not free. - + @@ -67866,7 +71272,7 @@ Do not free. - + @@ -67875,7 +71281,7 @@ Do not free. - + @@ -67884,7 +71290,7 @@ Do not free. - + @@ -67893,14 +71299,14 @@ Do not free. - + - + @@ -67909,7 +71315,7 @@ Do not free. - + @@ -67918,7 +71324,7 @@ Do not free. - + @@ -67927,7 +71333,7 @@ Do not free. - + @@ -67936,7 +71342,7 @@ Do not free. - + @@ -67945,7 +71351,7 @@ Do not free. - + @@ -67954,7 +71360,7 @@ Do not free. - + @@ -67963,7 +71369,7 @@ Do not free. - + @@ -67972,7 +71378,7 @@ Do not free. - + @@ -67981,7 +71387,7 @@ Do not free. - + @@ -67990,7 +71396,7 @@ Do not free. - + @@ -67999,7 +71405,7 @@ Do not free. - + @@ -68008,7 +71414,7 @@ Do not free. - + @@ -68017,7 +71423,7 @@ Do not free. - + @@ -68026,7 +71432,7 @@ Do not free. - + @@ -68035,7 +71441,7 @@ Do not free. - + @@ -68044,7 +71450,7 @@ Do not free. - + @@ -68053,7 +71459,7 @@ Do not free. - + @@ -68062,7 +71468,7 @@ Do not free. - + @@ -68071,7 +71477,7 @@ Do not free. - + @@ -68080,7 +71486,7 @@ Do not free. - + @@ -68089,7 +71495,7 @@ Do not free. - + @@ -68098,7 +71504,7 @@ Do not free. - + @@ -68107,7 +71513,7 @@ Do not free. - + @@ -68116,7 +71522,7 @@ Do not free. - + @@ -68125,7 +71531,7 @@ Do not free. - + @@ -68134,7 +71540,7 @@ Do not free. - + @@ -68143,7 +71549,7 @@ Do not free. - + @@ -68152,7 +71558,7 @@ Do not free. - + @@ -68161,7 +71567,7 @@ Do not free. - + @@ -68170,7 +71576,7 @@ Do not free. - + @@ -68179,7 +71585,7 @@ Do not free. - + @@ -68188,7 +71594,7 @@ Do not free. - + @@ -68197,7 +71603,7 @@ Do not free. - + @@ -68206,7 +71612,7 @@ Do not free. - + @@ -68215,7 +71621,7 @@ Do not free. - + @@ -68224,7 +71630,7 @@ Do not free. - + @@ -68233,7 +71639,7 @@ Do not free. - + @@ -68242,7 +71648,7 @@ Do not free. - + @@ -68251,7 +71657,7 @@ Do not free. - + @@ -68260,7 +71666,7 @@ Do not free. - + @@ -68269,7 +71675,7 @@ Do not free. - + @@ -68278,7 +71684,7 @@ Do not free. - + @@ -68287,7 +71693,7 @@ Do not free. - + @@ -68296,7 +71702,7 @@ Do not free. - + @@ -68305,7 +71711,7 @@ Do not free. - + @@ -68314,7 +71720,7 @@ Do not free. - + @@ -68323,7 +71729,7 @@ Do not free. - + @@ -68332,7 +71738,7 @@ Do not free. - + @@ -68341,7 +71747,7 @@ Do not free. - + @@ -68350,7 +71756,7 @@ Do not free. - + @@ -68359,7 +71765,7 @@ Do not free. - + @@ -68368,7 +71774,7 @@ Do not free. - + @@ -68377,7 +71783,7 @@ Do not free. - + @@ -68386,7 +71792,7 @@ Do not free. - + @@ -68395,7 +71801,7 @@ Do not free. - + @@ -68404,7 +71810,7 @@ Do not free. - + @@ -68413,7 +71819,7 @@ Do not free. - + @@ -68422,7 +71828,7 @@ Do not free. - + @@ -68431,7 +71837,7 @@ Do not free. - + @@ -68440,7 +71846,7 @@ Do not free. - + @@ -68449,7 +71855,7 @@ Do not free. - + @@ -68458,7 +71864,7 @@ Do not free. - + @@ -68467,7 +71873,7 @@ Do not free. - + @@ -68476,7 +71882,7 @@ Do not free. - + @@ -68485,7 +71891,7 @@ Do not free. - + @@ -68494,7 +71900,7 @@ Do not free. - + @@ -68503,7 +71909,7 @@ Do not free. - + @@ -68512,7 +71918,7 @@ Do not free. - + @@ -68521,7 +71927,7 @@ Do not free. - + @@ -68530,14 +71936,14 @@ Do not free. - + - + @@ -68546,7 +71952,7 @@ Do not free. - + @@ -68555,7 +71961,7 @@ Do not free. - + @@ -68564,7 +71970,7 @@ Do not free. - + @@ -68573,7 +71979,7 @@ Do not free. - + @@ -68582,7 +71988,7 @@ Do not free. - + @@ -68591,7 +71997,7 @@ Do not free. - + @@ -68600,7 +72006,7 @@ Do not free. - + @@ -68609,7 +72015,7 @@ Do not free. - + @@ -68618,7 +72024,7 @@ Do not free. - + @@ -68627,7 +72033,7 @@ Do not free. - + @@ -68636,7 +72042,7 @@ Do not free. - + @@ -68645,7 +72051,7 @@ Do not free. - + @@ -68654,7 +72060,7 @@ Do not free. - + @@ -68663,7 +72069,7 @@ Do not free. - + @@ -68672,7 +72078,7 @@ Do not free. - + @@ -68681,7 +72087,7 @@ Do not free. - + @@ -68690,7 +72096,7 @@ Do not free. - + @@ -68699,7 +72105,7 @@ Do not free. - + @@ -68708,7 +72114,7 @@ Do not free. - + @@ -68717,7 +72123,7 @@ Do not free. - + @@ -68726,7 +72132,7 @@ Do not free. - + @@ -68735,7 +72141,7 @@ Do not free. - + @@ -68744,7 +72150,7 @@ Do not free. - + @@ -68753,7 +72159,7 @@ Do not free. - + @@ -68762,7 +72168,7 @@ Do not free. - + @@ -68771,7 +72177,7 @@ Do not free. - + @@ -68780,7 +72186,7 @@ Do not free. - + @@ -68789,7 +72195,7 @@ Do not free. - + @@ -68798,7 +72204,7 @@ Do not free. - + @@ -68807,7 +72213,7 @@ Do not free. - + @@ -68816,7 +72222,7 @@ Do not free. - + @@ -68825,7 +72231,7 @@ Do not free. - + @@ -68834,7 +72240,7 @@ Do not free. - + @@ -68843,7 +72249,7 @@ Do not free. - + @@ -68852,7 +72258,7 @@ Do not free. - + @@ -68861,7 +72267,7 @@ Do not free. - + @@ -68870,7 +72276,7 @@ Do not free. - + @@ -68879,7 +72285,7 @@ Do not free. - + @@ -68888,7 +72294,7 @@ Do not free. - + @@ -68897,14 +72303,14 @@ Do not free. - + - + @@ -68913,7 +72319,7 @@ Do not free. - + @@ -68922,7 +72328,7 @@ Do not free. - + @@ -68931,7 +72337,7 @@ Do not free. - + @@ -68940,7 +72346,7 @@ Do not free. - + @@ -68949,7 +72355,7 @@ Do not free. - + @@ -68958,7 +72364,7 @@ Do not free. - + @@ -68967,7 +72373,7 @@ Do not free. - + @@ -68976,7 +72382,7 @@ Do not free. - + @@ -68989,54 +72395,56 @@ Do not free. glib:get-type="g_icon_get_type" glib:type-struct="IconIface"> #GIcon is a very minimal interface for icons. It provides functions + filename="gio/gicon.c" + line="43">`GIcon` is a very minimal interface for icons. It provides functions for checking the equality of two icons, hashing of icons and serializing an icon to and from strings. -#GIcon does not provide the actual pixmap for the icon as this is out -of GIO's scope, however implementations of #GIcon may contain the name -of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). +`GIcon` does not provide the actual pixmap for the icon as this is out +of GIO's scope, however implementations of `GIcon` may contain the name +of an icon (see [class@Gio.ThemedIcon]), or the path to an icon +(see [iface@Gio.LoadableIcon]). -To obtain a hash of a #GIcon, see g_icon_hash(). +To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash]. -To check if two #GIcons are equal, see g_icon_equal(). +To check if two `GIcon`s are equal, see [method@Gio.Icon.equal]. -For serializing a #GIcon, use g_icon_serialize() and -g_icon_deserialize(). +For serializing a `GIcon`, use [method@Gio.Icon.serialize] and +[func@Gio.Icon.deserialize]. -If you want to consume #GIcon (for example, in a toolkit) you must +If you want to consume `GIcon` (for example, in a toolkit) you must be prepared to handle at least the three following cases: -#GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make -sense to have fast-paths for other cases (like handling #GdkPixbuf -directly, for example) but all compliant #GIcon implementations -outside of GIO must implement #GLoadableIcon. +[iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon]. +It may also make sense to have fast-paths for other cases (like handling +[`GdkPixbuf`](https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html) directly, +for example) but all compliant `GIcon` implementations outside of GIO must +implement [iface@Gio.LoadableIcon]. -If your application or library provides one or more #GIcon +If your application or library provides one or more `GIcon` implementations you need to ensure that your new implementation also -implements #GLoadableIcon. Additionally, you must provide an -implementation of g_icon_serialize() that gives a result that is -understood by g_icon_deserialize(), yielding one of the built-in icon -types. - +implements [iface@Gio.LoadableIcon]. Additionally, you must provide an +implementation of [method@Gio.Icon.serialize] that gives a result that is +understood by [func@Gio.Icon.deserialize], yielding one of the built-in +icon types. + Deserializes a #GIcon previously serialized using g_icon_serialize(). - + filename="gio/gicon.c" + line="559">Deserializes a #GIcon previously serialized using g_icon_serialize(). + a #GIcon, or %NULL when deserialization fails. + filename="gio/gicon.c" + line="565">a #GIcon, or %NULL when deserialization fails. a #GVariant created with g_icon_serialize() + filename="gio/gicon.c" + line="561">a #GVariant created with g_icon_serialize() @@ -69046,39 +72454,39 @@ types. version="2.20" throws="1"> Generate a #GIcon instance from @str. This function can fail if + filename="gio/gicon.c" + line="425">Generate a #GIcon instance from @str. This function can fail if @str is not valid - see g_icon_to_string() for discussion. If your application or library provides one or more #GIcon implementations you need to ensure that each #GType is registered with the type system prior to calling g_icon_new_for_string(). - + An object implementing the #GIcon + filename="gio/gicon.c" + line="437">An object implementing the #GIcon interface or %NULL if @error is set. A string obtained via g_icon_to_string(). + filename="gio/gicon.c" + line="427">A string obtained via g_icon_to_string(). Checks if two icons are equal. - + filename="gio/gicon.c" + line="107">Checks if two icons are equal. + %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + filename="gio/gicon.c" + line="114">%TRUE if @icon1 is equal to @icon2. %FALSE otherwise. @@ -69087,8 +72495,8 @@ with the type system prior to calling g_icon_new_for_string(). nullable="1" allow-none="1"> pointer to the first #GIcon. + filename="gio/gicon.c" + line="109">pointer to the first #GIcon. nullable="1" allow-none="1"> pointer to the second #GIcon. + filename="gio/gicon.c" + line="110">pointer to the second #GIcon. Gets a hash for an icon. - + filename="gio/gicon.c" + line="86">Gets a hash for an icon. + a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. + filename="gio/gicon.c" + line="92">a #guint containing a hash for the @icon, suitable for + use in a #GHashTable or similar data structure. #gconstpointer to an icon object. + filename="gio/gicon.c" + line="88">#gconstpointer to an icon object. Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved + filename="gio/gicon.c" + line="646">Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace. - + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. + filename="gio/gicon.c" + line="656">a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. a #GIcon + filename="gio/gicon.c" + line="648">a #GIcon Serializes the @icon into string tokens. + filename="gio/gicon.h" + line="68">Serializes the @icon into string tokens. This is can be invoked when g_icon_new_for_string() is called. - + %TRUE if serialization took place, %FALSE otherwise + filename="gio/gicon.h" + line="78">%TRUE if serialization took place, %FALSE otherwise The #GIcon + filename="gio/gicon.h" + line="70">The #GIcon caller-allocates="1" transfer-ownership="none"> + filename="gio/gicon.h" + line="71"> The array to fill with tokens @@ -69183,21 +72591,21 @@ This is can be invoked when g_icon_new_for_string() is called. caller-allocates="0" transfer-ownership="full"> version of serialized tokens + filename="gio/gicon.h" + line="73">version of serialized tokens Checks if two icons are equal. - + filename="gio/gicon.c" + line="107">Checks if two icons are equal. + %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + filename="gio/gicon.c" + line="114">%TRUE if @icon1 is equal to @icon2. %FALSE otherwise. @@ -69206,8 +72614,8 @@ This is can be invoked when g_icon_new_for_string() is called. nullable="1" allow-none="1"> pointer to the first #GIcon. + filename="gio/gicon.c" + line="109">pointer to the first #GIcon. nullable="1" allow-none="1"> pointer to the second #GIcon. + filename="gio/gicon.c" + line="110">pointer to the second #GIcon. Gets a hash for an icon. - + filename="gio/gicon.c" + line="86">Gets a hash for an icon. + a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. + filename="gio/gicon.c" + line="92">a #guint containing a hash for the @icon, suitable for + use in a #GHashTable or similar data structure. #gconstpointer to an icon object. + filename="gio/gicon.c" + line="88">#gconstpointer to an icon object. Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved + filename="gio/gicon.c" + line="646">Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace. - + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. + filename="gio/gicon.c" + line="656">a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. a #GIcon + filename="gio/gicon.c" + line="648">a #GIcon Generates a textual representation of @icon that can be used for + filename="gio/gicon.c" + line="185">Generates a textual representation of @icon that can be used for serialization such as when passing @icon to a different process or saving it to persistent storage. Use g_icon_new_for_string() to get @icon back from the returned string. @@ -69285,19 +72693,19 @@ in the following two cases - If @icon is a #GThemedIcon with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`). - + An allocated NUL-terminated UTF8 string or + filename="gio/gicon.c" + line="206">An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free. a #GIcon. + filename="gio/gicon.c" + line="187">a #GIcon. @@ -69307,44 +72715,50 @@ in the following two cases c:type="GIconIface" glib:is-gtype-struct-for="Icon"> GIconIface is used to implement GIcon types for various + filename="gio/gicon.h" + line="41">GIconIface is used to implement GIcon types for various different systems. See #GThemedIcon and #GLoadableIcon for examples of how to implement this interface. - + The parent interface. + filename="gio/gicon.h" + line="43">The parent interface. + A hash for a given #GIcon. - + a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. + filename="gio/gicon.c" + line="92">a #guint containing a hash for the @icon, suitable for + use in a #GHashTable or similar data structure. #gconstpointer to an icon object. + filename="gio/gicon.c" + line="88">#gconstpointer to an icon object. + Checks if two #GIcons are equal. - + %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + filename="gio/gicon.c" + line="114">%TRUE if @icon1 is equal to @icon2. %FALSE otherwise. @@ -69353,8 +72767,8 @@ use in a #GHashTable or similar data structure. nullable="1" allow-none="1"> pointer to the first #GIcon. + filename="gio/gicon.c" + line="109">pointer to the first #GIcon. nullable="1" allow-none="1"> pointer to the second #GIcon. + filename="gio/gicon.c" + line="110">pointer to the second #GIcon. + Serializes a #GIcon into tokens. The tokens must not +contain any whitespace. Don't implement if the #GIcon can't be +serialized (Since 2.20). - + %TRUE if serialization took place, %FALSE otherwise + filename="gio/gicon.h" + line="78">%TRUE if serialization took place, %FALSE otherwise The #GIcon + filename="gio/gicon.h" + line="70">The #GIcon caller-allocates="1" transfer-ownership="none"> + filename="gio/gicon.h" + line="71"> The array to fill with tokens @@ -69402,16 +72821,21 @@ use in a #GHashTable or similar data structure. caller-allocates="0" transfer-ownership="full"> version of serialized tokens + filename="gio/gicon.h" + line="73">version of serialized tokens + Constructs a #GIcon from tokens. Set the #GError if +the tokens are malformed. Don't implement if the #GIcon can't be +serialized (Since 2.20). - + @@ -69429,19 +72853,22 @@ use in a #GHashTable or similar data structure. + Serializes a #GIcon into a #GVariant. Since: 2.38 - + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. + filename="gio/gicon.c" + line="656">a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. a #GIcon + filename="gio/gicon.c" + line="648">a #GIcon @@ -69456,30 +72883,30 @@ use in a #GHashTable or similar data structure. glib:get-type="g_inet_address_get_type" glib:type-struct="InetAddressClass"> #GInetAddress represents an IPv4 or IPv6 internet address. Use -g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to -look up the #GInetAddress for a hostname. Use -g_resolver_lookup_by_address() or -g_resolver_lookup_by_address_async() to look up the hostname for a -#GInetAddress. + filename="gio/ginetaddress.c" + line="47">`GInetAddress` represents an IPv4 or IPv6 internet address. Use +[method@Gio.Resolver.lookup_by_name] or +[method@Gio.Resolver.lookup_by_name_async] to look up the `GInetAddress` for +a hostname. Use [method@Gio.Resolver.lookup_by_address] or +[method@Gio.Resolver.lookup_by_address_async] to look up the hostname for a +`GInetAddress`. To actually connect to a remote host, you will need a -#GInetSocketAddress (which includes a #GInetAddress as well as a +[class@Gio.InetSocketAddress] (which includes a `GInetAddress` as well as a port number). - + Creates a #GInetAddress for the "any" address (unassigned/"don't + filename="gio/ginetaddress.c" + line="461">Creates a #GInetAddress for the "any" address (unassigned/"don't care") for @family. - + a new #GInetAddress corresponding to the "any" address + filename="gio/ginetaddress.c" + line="468">a new #GInetAddress corresponding to the "any" address for @family. Free the returned object with g_object_unref(). @@ -69487,8 +72914,8 @@ for @family. the address family + filename="gio/ginetaddress.c" + line="463">the address family @@ -69497,31 +72924,31 @@ for @family. c:identifier="g_inet_address_new_from_bytes" version="2.22"> Creates a new #GInetAddress from the given @family and @bytes. + filename="gio/ginetaddress.c" + line="404">Creates a new #GInetAddress from the given @family and @bytes. @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for %G_SOCKET_FAMILY_IPV6. - + a new #GInetAddress corresponding to @family and @bytes. + filename="gio/ginetaddress.c" + line="413">a new #GInetAddress corresponding to @family and @bytes. Free the returned object with g_object_unref(). raw address data + filename="gio/ginetaddress.c" + line="406">raw address data the address family of @bytes + filename="gio/ginetaddress.c" + line="407">the address family of @bytes @@ -69530,13 +72957,13 @@ for @family. c:identifier="g_inet_address_new_from_string" version="2.22"> Parses @string as an IP address and creates a new #GInetAddress. - + filename="gio/ginetaddress.c" + line="364">Parses @string as an IP address and creates a new #GInetAddress. + a new #GInetAddress corresponding + filename="gio/ginetaddress.c" + line="370">a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed. Free the returned object with g_object_unref(). @@ -69544,8 +72971,8 @@ to @string, or %NULL if @string could not be parsed. a string representation of an IP address + filename="gio/ginetaddress.c" + line="366">a string representation of an IP address @@ -69554,13 +72981,13 @@ to @string, or %NULL if @string could not be parsed. c:identifier="g_inet_address_new_loopback" version="2.22"> Creates a #GInetAddress for the loopback address for @family. - + filename="gio/ginetaddress.c" + line="430">Creates a #GInetAddress for the loopback address for @family. + a new #GInetAddress corresponding to the loopback address + filename="gio/ginetaddress.c" + line="436">a new #GInetAddress corresponding to the loopback address for @family. Free the returned object with g_object_unref(). @@ -69568,8 +72995,8 @@ for @family. the address family + filename="gio/ginetaddress.c" + line="432">the address family @@ -69579,13 +73006,13 @@ for @family. version="2.22" introspectable="0"> Gets the raw binary address data from @address. - + filename="gio/ginetaddress.c" + line="528">Gets the raw binary address data from @address. + a pointer to an internal array of the bytes in @address, + filename="gio/ginetaddress.c" + line="534">a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). @@ -69593,55 +73020,55 @@ array can be gotten with g_inet_address_get_native_size(). a #GInetAddress + filename="gio/ginetaddress.c" + line="530">a #GInetAddress Converts @address to string form. - + filename="gio/ginetaddress.c" + line="494">Converts @address to string form. + a representation of @address as a string, which should be + filename="gio/ginetaddress.c" + line="500">a representation of @address as a string, which should be freed after use. a #GInetAddress + filename="gio/ginetaddress.c" + line="496">a #GInetAddress Checks if two #GInetAddress instances are equal, e.g. the same address. - + filename="gio/ginetaddress.c" + line="869">Checks if two #GInetAddress instances are equal, e.g. the same address. + %TRUE if @address and @other_address are equal, %FALSE otherwise. + filename="gio/ginetaddress.c" + line="876">%TRUE if @address and @other_address are equal, %FALSE otherwise. A #GInetAddress. + filename="gio/ginetaddress.c" + line="871">A #GInetAddress. Another #GInetAddress. + filename="gio/ginetaddress.c" + line="872">Another #GInetAddress. @@ -69651,20 +73078,20 @@ freed after use. glib:get-property="family" version="2.22"> Gets @address's family - + filename="gio/ginetaddress.c" + line="571">Gets @address's family + @address's family + filename="gio/ginetaddress.c" + line="577">@address's family a #GInetAddress + filename="gio/ginetaddress.c" + line="573">a #GInetAddress @@ -69674,20 +73101,20 @@ freed after use. glib:get-property="is-any" version="2.22"> Tests whether @address is the "any" address for its family. - + filename="gio/ginetaddress.c" + line="589">Tests whether @address is the "any" address for its family. + %TRUE if @address is the "any" address for its family. + filename="gio/ginetaddress.c" + line="595">%TRUE if @address is the "any" address for its family. a #GInetAddress + filename="gio/ginetaddress.c" + line="591">a #GInetAddress @@ -69697,22 +73124,22 @@ freed after use. glib:get-property="is-link-local" version="2.22"> Tests whether @address is a link-local address (that is, if it + filename="gio/ginetaddress.c" + line="648">Tests whether @address is a link-local address (that is, if it identifies a host on a local network that is not connected to the Internet). - + %TRUE if @address is a link-local address. + filename="gio/ginetaddress.c" + line="656">%TRUE if @address is a link-local address. a #GInetAddress + filename="gio/ginetaddress.c" + line="650">a #GInetAddress @@ -69722,20 +73149,20 @@ Internet). glib:get-property="is-loopback" version="2.22"> Tests whether @address is the loopback address for its family. - + filename="gio/ginetaddress.c" + line="618">Tests whether @address is the loopback address for its family. + %TRUE if @address is the loopback address for its family. + filename="gio/ginetaddress.c" + line="624">%TRUE if @address is the loopback address for its family. a #GInetAddress + filename="gio/ginetaddress.c" + line="620">a #GInetAddress @@ -69745,20 +73172,20 @@ Internet). glib:get-property="is-mc-global" version="2.22"> Tests whether @address is a global multicast address. - + filename="gio/ginetaddress.c" + line="744">Tests whether @address is a global multicast address. + %TRUE if @address is a global multicast address. + filename="gio/ginetaddress.c" + line="750">%TRUE if @address is a global multicast address. a #GInetAddress + filename="gio/ginetaddress.c" + line="746">a #GInetAddress @@ -69768,20 +73195,20 @@ Internet). glib:get-property="is-mc-link-local" version="2.22"> Tests whether @address is a link-local multicast address. - + filename="gio/ginetaddress.c" + line="769">Tests whether @address is a link-local multicast address. + %TRUE if @address is a link-local multicast address. + filename="gio/ginetaddress.c" + line="775">%TRUE if @address is a link-local multicast address. a #GInetAddress + filename="gio/ginetaddress.c" + line="771">a #GInetAddress @@ -69791,20 +73218,20 @@ Internet). glib:get-property="is-mc-node-local" version="2.22"> Tests whether @address is a node-local multicast address. - + filename="gio/ginetaddress.c" + line="794">Tests whether @address is a node-local multicast address. + %TRUE if @address is a node-local multicast address. + filename="gio/ginetaddress.c" + line="800">%TRUE if @address is a node-local multicast address. a #GInetAddress + filename="gio/ginetaddress.c" + line="796">a #GInetAddress @@ -69814,20 +73241,20 @@ Internet). glib:get-property="is-mc-org-local" version="2.22"> Tests whether @address is an organization-local multicast address. - + filename="gio/ginetaddress.c" + line="819">Tests whether @address is an organization-local multicast address. + %TRUE if @address is an organization-local multicast address. + filename="gio/ginetaddress.c" + line="825">%TRUE if @address is an organization-local multicast address. a #GInetAddress + filename="gio/ginetaddress.c" + line="821">a #GInetAddress @@ -69837,20 +73264,20 @@ Internet). glib:get-property="is-mc-site-local" version="2.22"> Tests whether @address is a site-local multicast address. - + filename="gio/ginetaddress.c" + line="844">Tests whether @address is a site-local multicast address. + %TRUE if @address is a site-local multicast address. + filename="gio/ginetaddress.c" + line="850">%TRUE if @address is a site-local multicast address. a #GInetAddress + filename="gio/ginetaddress.c" + line="846">a #GInetAddress @@ -69860,20 +73287,20 @@ Internet). glib:get-property="is-multicast" version="2.22"> Tests whether @address is a multicast address. - + filename="gio/ginetaddress.c" + line="715">Tests whether @address is a multicast address. + %TRUE if @address is a multicast address. + filename="gio/ginetaddress.c" + line="721">%TRUE if @address is a multicast address. a #GInetAddress + filename="gio/ginetaddress.c" + line="717">a #GInetAddress @@ -69883,23 +73310,23 @@ Internet). glib:get-property="is-site-local" version="2.22"> Tests whether @address is a site-local address such as 10.0.0.1 + filename="gio/ginetaddress.c" + line="680">Tests whether @address is a site-local address such as 10.0.0.1 (that is, the address identifies a host on a local network that can not be reached directly from the Internet, but which may have outgoing Internet connectivity via a NAT or firewall). - + %TRUE if @address is a site-local address. + filename="gio/ginetaddress.c" + line="689">%TRUE if @address is a site-local address. a #GInetAddress + filename="gio/ginetaddress.c" + line="682">a #GInetAddress @@ -69908,21 +73335,21 @@ outgoing Internet connectivity via a NAT or firewall). c:identifier="g_inet_address_get_native_size" version="2.22"> Gets the size of the native raw binary address for @address. This + filename="gio/ginetaddress.c" + line="548">Gets the size of the native raw binary address for @address. This is the size of the data that you get from g_inet_address_to_bytes(). - + the number of bytes used for the native version of @address. + filename="gio/ginetaddress.c" + line="555">the number of bytes used for the native version of @address. a #GInetAddress + filename="gio/ginetaddress.c" + line="550">a #GInetAddress @@ -69932,13 +73359,13 @@ is the size of the data that you get from g_inet_address_to_bytes(). version="2.22" introspectable="0"> Gets the raw binary address data from @address. - + filename="gio/ginetaddress.c" + line="528">Gets the raw binary address data from @address. + a pointer to an internal array of the bytes in @address, + filename="gio/ginetaddress.c" + line="534">a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). @@ -69946,8 +73373,8 @@ array can be gotten with g_inet_address_get_native_size(). a #GInetAddress + filename="gio/ginetaddress.c" + line="530">a #GInetAddress @@ -69956,37 +73383,45 @@ array can be gotten with g_inet_address_get_native_size(). c:identifier="g_inet_address_to_string" version="2.22"> Converts @address to string form. - + filename="gio/ginetaddress.c" + line="494">Converts @address to string form. + a representation of @address as a string, which should be + filename="gio/ginetaddress.c" + line="500">a representation of @address as a string, which should be freed after use. a #GInetAddress + filename="gio/ginetaddress.c" + line="496">a #GInetAddress + The raw address data. + The address family (IPv4 or IPv6). getter="get_is_any" default-value="FALSE"> Whether this is the "any" address for its family. + filename="gio/ginetaddress.c" + line="216">Whether this is the "any" address for its family. See g_inet_address_get_is_any(). @@ -70006,8 +73441,8 @@ See g_inet_address_get_is_any(). getter="get_is_link_local" default-value="FALSE"> Whether this is a link-local address. + filename="gio/ginetaddress.c" + line="230">Whether this is a link-local address. See g_inet_address_get_is_link_local(). @@ -70017,8 +73452,8 @@ See g_inet_address_get_is_link_local(). getter="get_is_loopback" default-value="FALSE"> Whether this is the loopback address for its family. + filename="gio/ginetaddress.c" + line="244">Whether this is the loopback address for its family. See g_inet_address_get_is_loopback(). @@ -70028,8 +73463,8 @@ See g_inet_address_get_is_loopback(). getter="get_is_mc_global" default-value="FALSE"> Whether this is a global multicast address. + filename="gio/ginetaddress.c" + line="286">Whether this is a global multicast address. See g_inet_address_get_is_mc_global(). @@ -70039,8 +73474,8 @@ See g_inet_address_get_is_mc_global(). getter="get_is_mc_link_local" default-value="FALSE"> Whether this is a link-local multicast address. + filename="gio/ginetaddress.c" + line="301">Whether this is a link-local multicast address. See g_inet_address_get_is_mc_link_local(). @@ -70050,8 +73485,8 @@ See g_inet_address_get_is_mc_link_local(). getter="get_is_mc_node_local" default-value="FALSE"> Whether this is a node-local multicast address. + filename="gio/ginetaddress.c" + line="315">Whether this is a node-local multicast address. See g_inet_address_get_is_mc_node_local(). @@ -70061,8 +73496,8 @@ See g_inet_address_get_is_mc_node_local(). getter="get_is_mc_org_local" default-value="FALSE"> Whether this is an organization-local multicast address. + filename="gio/ginetaddress.c" + line="329">Whether this is an organization-local multicast address. See g_inet_address_get_is_mc_org_local(). @@ -70072,8 +73507,8 @@ See g_inet_address_get_is_mc_org_local(). getter="get_is_mc_site_local" default-value="FALSE"> Whether this is a site-local multicast address. + filename="gio/ginetaddress.c" + line="343">Whether this is a site-local multicast address. See g_inet_address_get_is_mc_site_local(). @@ -70083,8 +73518,8 @@ See g_inet_address_get_is_mc_site_local(). getter="get_is_multicast" default-value="FALSE"> Whether this is a multicast address. + filename="gio/ginetaddress.c" + line="272">Whether this is a multicast address. See g_inet_address_get_is_multicast(). @@ -70094,8 +73529,8 @@ See g_inet_address_get_is_multicast(). getter="get_is_site_local" default-value="FALSE"> Whether this is a site-local address. + filename="gio/ginetaddress.c" + line="258">Whether this is a site-local address. See g_inet_address_get_is_loopback(). @@ -70109,25 +73544,25 @@ See g_inet_address_get_is_loopback(). - + - + a representation of @address as a string, which should be + filename="gio/ginetaddress.c" + line="500">a representation of @address as a string, which should be freed after use. a #GInetAddress + filename="gio/ginetaddress.c" + line="496">a #GInetAddress @@ -70135,11 +73570,11 @@ freed after use. - + a pointer to an internal array of the bytes in @address, + filename="gio/ginetaddress.c" + line="534">a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). @@ -70147,8 +73582,8 @@ array can be gotten with g_inet_address_get_native_size(). a #GInetAddress + filename="gio/ginetaddress.c" + line="530">a #GInetAddress @@ -70164,39 +73599,39 @@ array can be gotten with g_inet_address_get_native_size(). glib:get-type="g_inet_address_mask_get_type" glib:type-struct="InetAddressMaskClass"> #GInetAddressMask represents a range of IPv4 or IPv6 addresses + filename="gio/ginetaddressmask.c" + line="33">`GInetAddressMask` represents a range of IPv4 or IPv6 addresses described by a base address and a length indicating how many bits of the base address are relevant for matching purposes. These are -often given in string form. Eg, "10.0.0.0/8", or "fe80::/10". - +often given in string form. For example, `10.0.0.0/8`, or `fe80::/10`. + Creates a new #GInetAddressMask representing all addresses whose + filename="gio/ginetaddressmask.c" + line="252">Creates a new #GInetAddressMask representing all addresses whose first @length bits match @addr. - + a new #GInetAddressMask, or %NULL on error + filename="gio/ginetaddressmask.c" + line="261">a new #GInetAddressMask, or %NULL on error a #GInetAddress + filename="gio/ginetaddressmask.c" + line="254">a #GInetAddress number of bits of @addr to use + filename="gio/ginetaddressmask.c" + line="255">number of bits of @addr to use @@ -70206,24 +73641,24 @@ first @length bits match @addr. version="2.32" throws="1"> Parses @mask_string as an IP address and (optional) length, and + filename="gio/ginetaddressmask.c" + line="276">Parses @mask_string as an IP address and (optional) length, and creates a new #GInetAddressMask. The length, if present, is delimited by a "/". If it is not present, then the length is assumed to be the full length of the address. - + a new #GInetAddressMask corresponding to @string, or %NULL + filename="gio/ginetaddressmask.c" + line="286">a new #GInetAddressMask corresponding to @string, or %NULL on error. an IP address or address/length string + filename="gio/ginetaddressmask.c" + line="278">an IP address or address/length string @@ -70232,26 +73667,26 @@ on error. c:identifier="g_inet_address_mask_equal" version="2.32"> Tests if @mask and @mask2 are the same mask. - + filename="gio/ginetaddressmask.c" + line="463">Tests if @mask and @mask2 are the same mask. + whether @mask and @mask2 are the same mask + filename="gio/ginetaddressmask.c" + line="470">whether @mask and @mask2 are the same mask a #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="465">a #GInetAddressMask another #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="466">another #GInetAddressMask @@ -70261,20 +73696,20 @@ on error. glib:get-property="address" version="2.32"> Gets @mask's base address - + filename="gio/ginetaddressmask.c" + line="383">Gets @mask's base address + @mask's base address + filename="gio/ginetaddressmask.c" + line="389">@mask's base address a #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="385">a #GInetAddressMask @@ -70284,20 +73719,20 @@ on error. glib:get-property="family" version="2.32"> Gets the #GSocketFamily of @mask's address - + filename="gio/ginetaddressmask.c" + line="365">Gets the #GSocketFamily of @mask's address + the #GSocketFamily of @mask's address + filename="gio/ginetaddressmask.c" + line="371">the #GSocketFamily of @mask's address a #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="367">a #GInetAddressMask @@ -70307,20 +73742,20 @@ on error. glib:get-property="length" version="2.32"> Gets @mask's length - + filename="gio/ginetaddressmask.c" + line="401">Gets @mask's length + @mask's length + filename="gio/ginetaddressmask.c" + line="407">@mask's length a #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="403">a #GInetAddressMask @@ -70329,27 +73764,27 @@ on error. c:identifier="g_inet_address_mask_matches" version="2.32"> Tests if @address falls within the range described by @mask. - + filename="gio/ginetaddressmask.c" + line="419">Tests if @address falls within the range described by @mask. + whether @address falls within the range described by + filename="gio/ginetaddressmask.c" + line="426">whether @address falls within the range described by @mask. a #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="421">a #GInetAddressMask a #GInetAddress + filename="gio/ginetaddressmask.c" + line="422">a #GInetAddress @@ -70358,41 +73793,53 @@ on error. c:identifier="g_inet_address_mask_to_string" version="2.32"> Converts @mask back to its corresponding string form. - + filename="gio/ginetaddressmask.c" + line="337">Converts @mask back to its corresponding string form. + a string corresponding to @mask. + filename="gio/ginetaddressmask.c" + line="343">a string corresponding to @mask. a #GInetAddressMask + filename="gio/ginetaddressmask.c" + line="339">a #GInetAddressMask + The base address. + The address family (IPv4 or IPv6). + The prefix length, in bytes. @@ -70405,7 +73852,7 @@ on error. - + @@ -70414,13 +73861,13 @@ on error. c:type="GInetAddressMaskPrivate" disguised="1" opaque="1"> - + - + glib:get-type="g_inet_socket_address_get_type" glib:type-struct="InetSocketAddressClass"> An IPv4 or IPv6 socket address; that is, the combination of a -#GInetAddress and a port number. - + filename="gio/ginetsocketaddress.c" + line="36">An IPv4 or IPv6 socket address. That is, the combination of a +[class@Gio.InetAddress] and a port number. + +In UNIX terms, `GInetSocketAddress` corresponds to a +[`struct sockaddr_in` or `struct sockaddr_in6`](man:sockaddr(3type)). + Creates a new #GInetSocketAddress for @address and @port. - + filename="gio/ginetsocketaddress.c" + line="372">Creates a new #GInetSocketAddress for @address and @port. + a new #GInetSocketAddress + filename="gio/ginetsocketaddress.c" + line="379">a new #GInetSocketAddress a #GInetAddress + filename="gio/ginetsocketaddress.c" + line="374">a #GInetAddress a port number + filename="gio/ginetsocketaddress.c" + line="375">a port number @@ -70467,30 +73917,30 @@ on error. c:identifier="g_inet_socket_address_new_from_string" version="2.40"> Creates a new #GInetSocketAddress for @address and @port. + filename="gio/ginetsocketaddress.c" + line="393">Creates a new #GInetSocketAddress for @address and @port. If @address is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). - + a new #GInetSocketAddress, + filename="gio/ginetsocketaddress.c" + line="403">a new #GInetSocketAddress, or %NULL if @address cannot be parsed. the string form of an IP address + filename="gio/ginetsocketaddress.c" + line="395">the string form of an IP address a port number + filename="gio/ginetsocketaddress.c" + line="396">a port number @@ -70500,21 +73950,21 @@ or %NULL if @address cannot be parsed. glib:get-property="address" version="2.22"> Gets @address's #GInetAddress. - + filename="gio/ginetsocketaddress.c" + line="469">Gets @address's #GInetAddress. + the #GInetAddress for @address, which must be + filename="gio/ginetsocketaddress.c" + line="475">the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored a #GInetSocketAddress + filename="gio/ginetsocketaddress.c" + line="471">a #GInetSocketAddress @@ -70524,21 +73974,21 @@ g_object_ref()'d if it will be stored glib:get-property="flowinfo" version="2.32"> Gets the `sin6_flowinfo` field from @address, + filename="gio/ginetsocketaddress.c" + line="507">Gets the `sin6_flowinfo` field from @address, which must be an IPv6 address. - + the flowinfo field + filename="gio/ginetsocketaddress.c" + line="514">the flowinfo field a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress + filename="gio/ginetsocketaddress.c" + line="509">a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress @@ -70548,20 +73998,20 @@ which must be an IPv6 address. glib:get-property="port" version="2.22"> Gets @address's port. - + filename="gio/ginetsocketaddress.c" + line="488">Gets @address's port. + the port for @address + filename="gio/ginetsocketaddress.c" + line="494">the port for @address a #GInetSocketAddress + filename="gio/ginetsocketaddress.c" + line="490">a #GInetSocketAddress @@ -70571,30 +74021,34 @@ which must be an IPv6 address. glib:get-property="scope-id" version="2.32"> Gets the `sin6_scope_id` field from @address, + filename="gio/ginetsocketaddress.c" + line="527">Gets the `sin6_scope_id` field from @address, which must be an IPv6 address. - + the scope id field + filename="gio/ginetsocketaddress.c" + line="534">the scope id field a %G_SOCKET_FAMILY_IPV6 #GInetAddress + filename="gio/ginetsocketaddress.c" + line="529">a %G_SOCKET_FAMILY_IPV6 #GInetAddress + The address. getter="get_flowinfo" default-value="0"> The `sin6_flowinfo` field, for IPv6 addresses. + filename="gio/ginetsocketaddress.c" + line="280">The `sin6_flowinfo` field, for IPv6 addresses. + The port. + The `sin6_scope_id` field, for IPv6 addresses. @@ -70636,7 +74098,7 @@ which must be an IPv6 address. - + @@ -70645,7 +74107,7 @@ which must be an IPv6 address. c:type="GInetSocketAddressPrivate" disguised="1" opaque="1"> - + glib:get-type="g_initable_get_type" glib:type-struct="InitableIface"> #GInitable is implemented by objects that can fail during + filename="gio/ginitable.c" + line="28">`GInitable` is implemented by objects that can fail during initialization. If an object implements this interface then it must be initialized as the first thing after construction, -either via g_initable_init() or g_async_initable_init_async() -(the latter is only available if it also implements #GAsyncInitable). +either via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async] +(the latter is only available if it also implements [iface@Gio.AsyncInitable]). If the object is not initialized, or initialization returns with an -error, then all operations on the object except g_object_ref() and -g_object_unref() are considered to be invalid, and have undefined -behaviour. They will often fail with g_critical() or g_warning(), but -this must not be relied on. +error, then all operations on the object except `g_object_ref()` and +`g_object_unref()` are considered to be invalid, and have undefined +behaviour. They will often fail with [func@GLib.critical] or +[func@GLib.warning], but this must not be relied on. Users of objects implementing this are not intended to use the interface method directly, instead it will be used automatically in various ways. For C applications you generally just call -g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. -This will call g_initable_init() under the cover, returning %NULL and -setting a #GError on failure (at which point the instance is +[func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper. +This will call [method@Gio.Initable.init] under the cover, returning `NULL` +and setting a `GError` on failure (at which point the instance is unreferenced). For bindings in languages where the native constructor supports -exceptions the binding could check for objects implementing %GInitable +exceptions the binding could check for objects implementing `GInitable` during normal construction and automatically initialize them, throwing an exception on failure. - + Helper function for constructing #GInitable object. This is + filename="gio/ginitable.c" + line="132">Helper function for constructing #GInitable object. This is similar to g_object_new() but also initializes the object and returns %NULL, setting an error on failure. - + a newly allocated + filename="gio/ginitable.c" + line="147">a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. + filename="gio/ginitable.c" + line="134">a #GType supporting #GInitable. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="135">optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to + filename="gio/ginitable.c" + line="136">a #GError location to store the error occurring, or %NULL to ignore. @@ -70726,15 +74188,15 @@ and returns %NULL, setting an error on failure. nullable="1" allow-none="1"> the name of the first property, or %NULL if no + filename="gio/ginitable.c" + line="138">the name of the first property, or %NULL if no properties the value if the first property, followed by and other property + filename="gio/ginitable.c" + line="140">the value if the first property, followed by and other property value pairs, and ended by %NULL. @@ -70746,36 +74208,36 @@ and returns %NULL, setting an error on failure. introspectable="0" throws="1"> Helper function for constructing #GInitable object. This is + filename="gio/ginitable.c" + line="215">Helper function for constructing #GInitable object. This is similar to g_object_new_valist() but also initializes the object and returns %NULL, setting an error on failure. - + a newly allocated + filename="gio/ginitable.c" + line="229">a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. + filename="gio/ginitable.c" + line="217">a #GType supporting #GInitable. the name of the first property, followed by + filename="gio/ginitable.c" + line="218">the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. The var args list generated from @first_property_name. + filename="gio/ginitable.c" + line="220">The var args list generated from @first_property_name. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="221">optional #GCancellable object, %NULL to ignore. @@ -70796,37 +74258,37 @@ the value, and other property value pairs, and ended by %NULL. deprecated-version="2.54" throws="1"> Helper function for constructing #GInitable object. This is + filename="gio/ginitable.c" + line="171">Helper function for constructing #GInitable object. This is similar to g_object_newv() but also initializes the object and returns %NULL, setting an error on failure. Use g_object_new_with_properties() and g_initable_init() instead. See #GParameter for more information. - + a newly allocated + filename="gio/ginitable.c" + line="184">a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. + filename="gio/ginitable.c" + line="173">a #GType supporting #GInitable. the number of parameters in @parameters + filename="gio/ginitable.c" + line="174">the number of parameters in @parameters the parameters to use to construct the object + filename="gio/ginitable.c" + line="175">the parameters to use to construct the object @@ -70836,16 +74298,16 @@ g_initable_init() instead. See #GParameter for more information. optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="176">optional #GCancellable object, %NULL to ignore. Initializes the object implementing the interface. + filename="gio/ginitable.c" + line="67">Initializes the object implementing the interface. This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead. @@ -70863,7 +74325,7 @@ the object doesn't support cancellable initialization the error If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined -behaviour. See the [introduction][ginitable] for more details. +behaviour. See the [description][iface@Gio.Initable#description] for more details. Callers should not assume that a class which implements #GInitable can be initialized multiple times, unless the class explicitly documents itself as @@ -70883,19 +74345,19 @@ it is designed to be used via the singleton pattern, with a In this pattern, a caller would expect to be able to call g_initable_init() on the result of g_object_new(), regardless of whether it is in fact a new instance. - + %TRUE if successful. If an error has occurred, this function will + filename="gio/ginitable.c" + line="113">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GInitable. + filename="gio/ginitable.c" + line="69">a #GInitable. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="70">optional #GCancellable object, %NULL to ignore. @@ -70914,8 +74376,8 @@ instance. version="2.22" throws="1"> Initializes the object implementing the interface. + filename="gio/ginitable.c" + line="67">Initializes the object implementing the interface. This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead. @@ -70933,7 +74395,7 @@ the object doesn't support cancellable initialization the error If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined -behaviour. See the [introduction][ginitable] for more details. +behaviour. See the [description][iface@Gio.Initable#description] for more details. Callers should not assume that a class which implements #GInitable can be initialized multiple times, unless the class explicitly documents itself as @@ -70953,19 +74415,19 @@ it is designed to be used via the singleton pattern, with a In this pattern, a caller would expect to be able to call g_initable_init() on the result of g_object_new(), regardless of whether it is in fact a new instance. - + %TRUE if successful. If an error has occurred, this function will + filename="gio/ginitable.c" + line="113">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GInitable. + filename="gio/ginitable.c" + line="69">a #GInitable. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="70">optional #GCancellable object, %NULL to ignore. @@ -70985,31 +74447,34 @@ instance. glib:is-gtype-struct-for="Initable" version="2.22"> Provides an interface for initializing object such that initialization + filename="gio/ginitable.h" + line="42">Provides an interface for initializing object such that initialization may fail. - + The parent interface. + filename="gio/ginitable.h" + line="44">The parent interface. + Initializes the object. - + %TRUE if successful. If an error has occurred, this function will + filename="gio/ginitable.c" + line="113">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. a #GInitable. + filename="gio/ginitable.c" + line="69">a #GInitable. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="70">optional #GCancellable object, %NULL to ignore. @@ -71027,8 +74492,8 @@ may fail. Structure used for scatter/gather data input when receiving multiple + filename="gio/giotypes.h" + line="356">Structure used for scatter/gather data input when receiving multiple messages or packets in one go. You generally pass in an array of empty #GInputVectors and the operation will use all the buffers as if they were one buffer, and will set @bytes_received to the total number of bytes @@ -71047,18 +74512,18 @@ this array, which may be zero. Flags relevant to this message will be returned in @flags. For example, `MSG_EOR` or `MSG_TRUNC`. - + return location + filename="gio/giotypes.h" + line="358">return location for a #GSocketAddress, or %NULL pointer to an + filename="gio/giotypes.h" + line="360">pointer to an array of input vectors @@ -71066,28 +74531,28 @@ Flags relevant to this message will be returned in @flags. For example, the number of input vectors pointed to by @vectors + filename="gio/giotypes.h" + line="362">the number of input vectors pointed to by @vectors will be set to the number of bytes that have been + filename="gio/giotypes.h" + line="363">will be set to the number of bytes that have been received collection of #GSocketMsgFlags for the received message, + filename="gio/giotypes.h" + line="365">collection of #GSocketMsgFlags for the received message, outputted by the call return location for a + filename="gio/giotypes.h" + line="367">return location for a caller-allocated array of #GSocketControlMessages, or %NULL return location for the number of + filename="gio/giotypes.h" + line="370">return location for the number of elements in @control_messages @@ -71112,23 +74577,27 @@ Flags relevant to this message will be returned in @flags. For example, glib:get-type="g_input_stream_get_type" glib:type-struct="InputStreamClass"> #GInputStream has functions to read from a stream (g_input_stream_read()), -to close a stream (g_input_stream_close()) and to skip some content -(g_input_stream_skip()). + filename="gio/ginputstream.c" + line="35">`GInputStream` is a base class for implementing streaming input. + +It has functions to read from a stream ([method@Gio.InputStream.read]), +to close a stream ([method@Gio.InputStream.close]) and to skip some content +([method@Gio.InputStream.skip]). To copy the content of an input stream to an output stream without -manually handling the reads and writes, use g_output_stream_splice(). +manually handling the reads and writes, use [method@Gio.OutputStream.splice]. -See the documentation for #GIOStream for details of thread safety of -streaming APIs. +See the documentation for [class@Gio.IOStream] for details of thread safety +of streaming APIs. All of these functions have async variants too. - - + + Requests an asynchronous closes of the stream, releasing resources related to it. + filename="gio/ginputstream.c" + line="1106">Requests an asynchronous closes of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_input_stream_close_finish() to get the result of the operation. @@ -71138,21 +74607,21 @@ For behaviour details see g_input_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="1108">A #GInputStream. the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="1109">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional cancellable object + filename="gio/ginputstream.c" + line="1110">optional cancellable object scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="1111">a #GAsyncReadyCallback to call when the request is satisfied @@ -71182,40 +74651,40 @@ override one you must override all. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/ginputstream.c" + line="1113">the data to pass to callback function Finishes closing a stream asynchronously, started from g_input_stream_close_async(). - + filename="gio/ginputstream.c" + line="1164">Finishes closing a stream asynchronously, started from g_input_stream_close_async(). + %TRUE if the stream was closed successfully. + filename="gio/ginputstream.c" + line="1173">%TRUE if the stream was closed successfully. a #GInputStream. + filename="gio/ginputstream.c" + line="1166">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="1167">a #GAsyncResult. - + @@ -71231,10 +74700,12 @@ override one you must override all. - + Request an asynchronous read of @count bytes from the stream into the buffer + filename="gio/ginputstream.c" + line="583">Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. When the operation is finished @callback will be called. You can then call g_input_stream_read_finish() to get the result of the operation. @@ -71257,15 +74728,15 @@ priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="585">A #GInputStream. transfer-ownership="none" nullable="1"> - a buffer to read data into (which should be at least count bytes long). + filename="gio/ginputstream.c" + line="586"> + a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="588">the number of bytes that will be read from the stream the [I/O priority][io-priority] + filename="gio/ginputstream.c" + line="589">the [I/O priority](iface.AsyncResult.html#io-priority) of the request. @@ -71299,8 +74770,8 @@ of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="591">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="592">a #GAsyncReadyCallback to call when the request is satisfied @@ -71321,40 +74792,40 @@ of the request. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/ginputstream.c" + line="594">the data to pass to callback function Finishes an asynchronous stream read operation. - + filename="gio/ginputstream.c" + line="671">Finishes an asynchronous stream read operation. + number of bytes read in, or -1 on error, or 0 on end of file. + filename="gio/ginputstream.c" + line="680">number of bytes read in, or -1 on error, or 0 on end of file. a #GInputStream. + filename="gio/ginputstream.c" + line="673">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="674">a #GAsyncResult. - + @@ -71379,10 +74850,13 @@ of the request. - + Tries to skip @count bytes from the stream. Will block during the operation. + filename="gio/ginputstream.c" + line="340">Tries to skip @count bytes from the stream. Will block during the operation. This is identical to g_input_stream_read(), from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some @@ -71396,24 +74870,24 @@ triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. - + Number of bytes skipped, or -1 on error + filename="gio/ginputstream.c" + line="362">Number of bytes skipped, or -1 on error a #GInputStream. + filename="gio/ginputstream.c" + line="342">a #GInputStream. the number of bytes that will be skipped from the stream + filename="gio/ginputstream.c" + line="343">the number of bytes that will be skipped from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="344">optional #GCancellable object, %NULL to ignore. - + Request an asynchronous skip of @count bytes from the stream. + filename="gio/ginputstream.c" + line="993">Request an asynchronous skip of @count bytes from the stream. When the operation is finished @callback will be called. You can then call g_input_stream_skip_finish() to get the result of the operation. @@ -71453,27 +74930,27 @@ Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one, you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="995">A #GInputStream. the number of bytes that will be skipped from the stream + filename="gio/ginputstream.c" + line="996">the number of bytes that will be skipped from the stream the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="997">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="998">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="999">a #GAsyncReadyCallback to call when the request is satisfied @@ -71503,59 +74980,62 @@ However, if you override one, you must override all. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/ginputstream.c" + line="1001">the data to pass to callback function Finishes a stream skip operation. - + filename="gio/ginputstream.c" + line="1076">Finishes a stream skip operation. + the size of the bytes skipped, or `-1` on error. + filename="gio/ginputstream.c" + line="1085">the size of the bytes skipped, or `-1` on error. a #GInputStream. + filename="gio/ginputstream.c" + line="1078">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="1079">a #GAsyncResult. Clears the pending flag on @stream. - + filename="gio/ginputstream.c" + line="1264">Clears the pending flag on @stream. + input stream + filename="gio/ginputstream.c" + line="1266">input stream - + Closes the stream, releasing resources related to it. + filename="gio/ginputstream.c" + line="488">Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. @@ -71578,18 +75058,18 @@ triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors. - + %TRUE on success, %FALSE on failure + filename="gio/ginputstream.c" + line="518">%TRUE on success, %FALSE on failure A #GInputStream. + filename="gio/ginputstream.c" + line="490">A #GInputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="491">optional #GCancellable object, %NULL to ignore. - + Requests an asynchronous closes of the stream, releasing resources related to it. + filename="gio/ginputstream.c" + line="1106">Requests an asynchronous closes of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_input_stream_close_finish() to get the result of the operation. @@ -71616,21 +75099,21 @@ For behaviour details see g_input_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="1108">A #GInputStream. the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="1109">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional cancellable object + filename="gio/ginputstream.c" + line="1110">optional cancellable object scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="1111">a #GAsyncReadyCallback to call when the request is satisfied @@ -71659,8 +75142,8 @@ override one you must override all. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/ginputstream.c" + line="1113">the data to pass to callback function @@ -71669,74 +75152,74 @@ override one you must override all. c:identifier="g_input_stream_close_finish" throws="1"> Finishes closing a stream asynchronously, started from g_input_stream_close_async(). - + filename="gio/ginputstream.c" + line="1164">Finishes closing a stream asynchronously, started from g_input_stream_close_async(). + %TRUE if the stream was closed successfully. + filename="gio/ginputstream.c" + line="1173">%TRUE if the stream was closed successfully. a #GInputStream. + filename="gio/ginputstream.c" + line="1166">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="1167">a #GAsyncResult. Checks if an input stream has pending actions. - + filename="gio/ginputstream.c" + line="1210">Checks if an input stream has pending actions. + %TRUE if @stream has pending actions. + filename="gio/ginputstream.c" + line="1216">%TRUE if @stream has pending actions. input stream. + filename="gio/ginputstream.c" + line="1212">input stream. Checks if an input stream is closed. - + filename="gio/ginputstream.c" + line="1194">Checks if an input stream is closed. + %TRUE if the stream is closed. + filename="gio/ginputstream.c" + line="1200">%TRUE if the stream is closed. input stream. + filename="gio/ginputstream.c" + line="1196">input stream. Tries to read @count bytes from the stream into the buffer starting at + filename="gio/ginputstream.c" + line="129">Tries to read @count bytes from the stream into the buffer starting at @buffer. Will block during this read. If count is zero returns zero and does nothing. A value of @count @@ -71757,18 +75240,18 @@ operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and @error is set accordingly. - + Number of bytes read, or -1 on error, or 0 on end of file. + filename="gio/ginputstream.c" + line="160">Number of bytes read, or -1 on error, or 0 on end of file. a #GInputStream. + filename="gio/ginputstream.c" + line="131">a #GInputStream. caller-allocates="1" transfer-ownership="none"> - a buffer to read data into (which should be at least count bytes long). + filename="gio/ginputstream.c" + line="132"> + a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="134">the number of bytes that will be read from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="135">optional #GCancellable object, %NULL to ignore. @@ -71804,8 +75287,8 @@ On error -1 is returned and @error is set accordingly. c:identifier="g_input_stream_read_all" throws="1"> Tries to read @count bytes from the stream into the buffer starting at + filename="gio/ginputstream.c" + line="210">Tries to read @count bytes from the stream into the buffer starting at @buffer. Will block during this read. This function is similar to g_input_stream_read(), except it tries to @@ -71824,18 +75307,18 @@ use #GError, if this function returns %FALSE (and sets @error) then read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read(). - + %TRUE on success, %FALSE if there was an error + filename="gio/ginputstream.c" + line="240">%TRUE on success, %FALSE if there was an error a #GInputStream. + filename="gio/ginputstream.c" + line="212">a #GInputStream. caller-allocates="1" transfer-ownership="none"> - a buffer to read data into (which should be at least count bytes long). + filename="gio/ginputstream.c" + line="213"> + a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="215">the number of bytes that will be read from the stream caller-allocates="0" transfer-ownership="full"> location to store the number of bytes that was read from the stream + filename="gio/ginputstream.c" + line="216">location to store the number of bytes that was read from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="217">optional #GCancellable object, %NULL to ignore. + version="2.44" + glib:finish-func="read_all_finish"> Request an asynchronous read of @count bytes from the stream into the + filename="gio/ginputstream.c" + line="776">Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. -This is the asynchronous equivalent of g_input_stream_read_all(). +This is the asynchronous equivalent of [method@InputStream.read_all]. -Call g_input_stream_read_all_finish() to collect the result. +Call [method@InputStream.read_all_finish] to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. - + A #GInputStream + filename="gio/ginputstream.c" + line="778">A #GInputStream caller-allocates="1" transfer-ownership="none"> - a buffer to read data into (which should be at least count bytes long) + filename="gio/ginputstream.c" + line="779"> + a buffer to read data into (which should be at least count bytes long) the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="781">the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="782">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/ginputstream.c" + line="783">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="784">a #GAsyncReadyCallback to call when the request is satisfied @@ -71952,8 +75436,8 @@ priority. Default priority is %G_PRIORITY_DEFAULT. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/ginputstream.c" + line="786">the data to pass to callback function @@ -71963,9 +75447,9 @@ priority. Default priority is %G_PRIORITY_DEFAULT. version="2.44" throws="1"> Finishes an asynchronous stream read operation started with -g_input_stream_read_all_async(). + filename="gio/ginputstream.c" + line="838">Finishes an asynchronous stream read operation started with +[method@InputStream.read_all_async]. As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @@ -71973,24 +75457,24 @@ use #GError, if this function returns %FALSE (and sets @error) then read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read_async(). - + %TRUE on success, %FALSE if there was an error + filename="gio/ginputstream.c" + line="855">%TRUE on success, %FALSE if there was an error a #GInputStream + filename="gio/ginputstream.c" + line="840">a #GInputStream a #GAsyncResult + filename="gio/ginputstream.c" + line="841">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> location to store the number of bytes that was read from the stream + filename="gio/ginputstream.c" + line="842">location to store the number of bytes that was read from the stream - + Request an asynchronous read of @count bytes from the stream into the buffer + filename="gio/ginputstream.c" + line="583">Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. When the operation is finished @callback will be called. You can then call g_input_stream_read_finish() to get the result of the operation. @@ -72030,15 +75516,15 @@ priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="585">A #GInputStream. caller-allocates="1" transfer-ownership="none"> - a buffer to read data into (which should be at least count bytes long). + filename="gio/ginputstream.c" + line="586"> + a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="588">the number of bytes that will be read from the stream the [I/O priority][io-priority] + filename="gio/ginputstream.c" + line="589">the [I/O priority](iface.AsyncResult.html#io-priority) of the request. @@ -72071,8 +75557,8 @@ of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="591">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="592">a #GAsyncReadyCallback to call when the request is satisfied @@ -72092,8 +75578,8 @@ of the request. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/ginputstream.c" + line="594">the data to pass to callback function @@ -72101,10 +75587,11 @@ of the request. + throws="1" + glib:async-func="read_bytes_async"> Like g_input_stream_read(), this tries to read @count bytes from + filename="gio/ginputstream.c" + line="279">Like g_input_stream_read(), this tries to read @count bytes from the stream in a blocking fashion. However, rather than reading into a user-supplied buffer, this will create a new #GBytes containing the data that was read. This may be easier to use from language @@ -72127,24 +75614,24 @@ operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error %NULL is returned and @error is set accordingly. - + a new #GBytes, or %NULL on error + filename="gio/ginputstream.c" + line="311">a new #GBytes, or %NULL on error a #GInputStream. + filename="gio/ginputstream.c" + line="281">a #GInputStream. maximum number of bytes that will be read from the stream. Common + filename="gio/ginputstream.c" + line="282">maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. @@ -72153,18 +75640,20 @@ values include 4096 and 8192. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="284">optional #GCancellable object, %NULL to ignore. + version="2.34" + glib:finish-func="read_bytes_finish" + glib:sync-func="read_bytes"> Request an asynchronous read of @count bytes from the stream into a + filename="gio/ginputstream.c" + line="914">Request an asynchronous read of @count bytes from the stream into a new #GBytes. When the operation is finished @callback will be called. You can then call g_input_stream_read_bytes_finish() to get the result of the operation. @@ -72184,27 +75673,27 @@ many bytes as requested. Zero is returned on end of file (or if Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. - + A #GInputStream. + filename="gio/ginputstream.c" + line="916">A #GInputStream. the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="917">the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="918">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="919">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="920">a #GAsyncReadyCallback to call when the request is satisfied @@ -72233,8 +75722,8 @@ priority. Default priority is %G_PRIORITY_DEFAULT. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/ginputstream.c" + line="922">the data to pass to callback function @@ -72244,26 +75733,26 @@ priority. Default priority is %G_PRIORITY_DEFAULT. version="2.34" throws="1"> Finishes an asynchronous stream read-into-#GBytes operation. - + filename="gio/ginputstream.c" + line="969">Finishes an asynchronous stream read-into-#GBytes operation. + the newly-allocated #GBytes, or %NULL on error + filename="gio/ginputstream.c" + line="978">the newly-allocated #GBytes, or %NULL on error a #GInputStream. + filename="gio/ginputstream.c" + line="971">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="972">a #GAsyncResult. @@ -72272,26 +75761,26 @@ priority. Default priority is %G_PRIORITY_DEFAULT. c:identifier="g_input_stream_read_finish" throws="1"> Finishes an asynchronous stream read operation. - + filename="gio/ginputstream.c" + line="671">Finishes an asynchronous stream read operation. + number of bytes read in, or -1 on error, or 0 on end of file. + filename="gio/ginputstream.c" + line="680">number of bytes read in, or -1 on error, or 0 on end of file. a #GInputStream. + filename="gio/ginputstream.c" + line="673">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="674">a #GAsyncResult. @@ -72300,30 +75789,33 @@ priority. Default priority is %G_PRIORITY_DEFAULT. c:identifier="g_input_stream_set_pending" throws="1"> Sets @stream to have actions pending. If the pending flag is + filename="gio/ginputstream.c" + line="1226">Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. - + %TRUE if pending was previously unset and is now set. + filename="gio/ginputstream.c" + line="1236">%TRUE if pending was previously unset and is now set. input stream + filename="gio/ginputstream.c" + line="1228">input stream - + Tries to skip @count bytes from the stream. Will block during the operation. + filename="gio/ginputstream.c" + line="340">Tries to skip @count bytes from the stream. Will block during the operation. This is identical to g_input_stream_read(), from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some @@ -72337,24 +75829,24 @@ triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. - + Number of bytes skipped, or -1 on error + filename="gio/ginputstream.c" + line="362">Number of bytes skipped, or -1 on error a #GInputStream. + filename="gio/ginputstream.c" + line="342">a #GInputStream. the number of bytes that will be skipped from the stream + filename="gio/ginputstream.c" + line="343">the number of bytes that will be skipped from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="344">optional #GCancellable object, %NULL to ignore. - + Request an asynchronous skip of @count bytes from the stream. + filename="gio/ginputstream.c" + line="993">Request an asynchronous skip of @count bytes from the stream. When the operation is finished @callback will be called. You can then call g_input_stream_skip_finish() to get the result of the operation. @@ -72394,27 +75889,27 @@ Default priority is %G_PRIORITY_DEFAULT. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one, you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="995">A #GInputStream. the number of bytes that will be skipped from the stream + filename="gio/ginputstream.c" + line="996">the number of bytes that will be skipped from the stream the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="997">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="998">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="999">a #GAsyncReadyCallback to call when the request is satisfied @@ -72443,8 +75938,8 @@ However, if you override one, you must override all. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/ginputstream.c" + line="1001">the data to pass to callback function @@ -72453,26 +75948,26 @@ However, if you override one, you must override all. c:identifier="g_input_stream_skip_finish" throws="1"> Finishes a stream skip operation. - + filename="gio/ginputstream.c" + line="1076">Finishes a stream skip operation. + the size of the bytes skipped, or `-1` on error. + filename="gio/ginputstream.c" + line="1085">the size of the bytes skipped, or `-1` on error. a #GInputStream. + filename="gio/ginputstream.c" + line="1078">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="1079">a #GAsyncResult. @@ -72487,13 +75982,13 @@ However, if you override one, you must override all. - + - + @@ -72521,24 +76016,24 @@ However, if you override one, you must override all. - + Number of bytes skipped, or -1 on error + filename="gio/ginputstream.c" + line="362">Number of bytes skipped, or -1 on error a #GInputStream. + filename="gio/ginputstream.c" + line="342">a #GInputStream. the number of bytes that will be skipped from the stream + filename="gio/ginputstream.c" + line="343">the number of bytes that will be skipped from the stream nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="344">optional #GCancellable object, %NULL to ignore. @@ -72555,7 +76050,7 @@ However, if you override one, you must override all. - + @@ -72574,15 +76069,15 @@ However, if you override one, you must override all. - + A #GInputStream. + filename="gio/ginputstream.c" + line="585">A #GInputStream. transfer-ownership="none" nullable="1"> - a buffer to read data into (which should be at least count bytes long). + filename="gio/ginputstream.c" + line="586"> + a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream + filename="gio/ginputstream.c" + line="588">the number of bytes that will be read from the stream the [I/O priority][io-priority] + filename="gio/ginputstream.c" + line="589">the [I/O priority](iface.AsyncResult.html#io-priority) of the request. @@ -72616,8 +76111,8 @@ of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="591">optional #GCancellable object, %NULL to ignore. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="592">a #GAsyncReadyCallback to call when the request is satisfied @@ -72638,8 +76133,8 @@ of the request. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/ginputstream.c" + line="594">the data to pass to callback function @@ -72647,24 +76142,24 @@ of the request. - + number of bytes read in, or -1 on error, or 0 on end of file. + filename="gio/ginputstream.c" + line="680">number of bytes read in, or -1 on error, or 0 on end of file. a #GInputStream. + filename="gio/ginputstream.c" + line="673">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="674">a #GAsyncResult. @@ -72672,27 +76167,27 @@ of the request. - + A #GInputStream. + filename="gio/ginputstream.c" + line="995">A #GInputStream. the number of bytes that will be skipped from the stream + filename="gio/ginputstream.c" + line="996">the number of bytes that will be skipped from the stream the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="997">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/ginputstream.c" + line="998">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="999">a #GAsyncReadyCallback to call when the request is satisfied @@ -72722,8 +76217,8 @@ of the request. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/ginputstream.c" + line="1001">the data to pass to callback function @@ -72731,24 +76226,24 @@ of the request. - + the size of the bytes skipped, or `-1` on error. + filename="gio/ginputstream.c" + line="1085">the size of the bytes skipped, or `-1` on error. a #GInputStream. + filename="gio/ginputstream.c" + line="1078">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="1079">a #GAsyncResult. @@ -72756,21 +76251,21 @@ of the request. - + A #GInputStream. + filename="gio/ginputstream.c" + line="1108">A #GInputStream. the [I/O priority][io-priority] of the request + filename="gio/ginputstream.c" + line="1109">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional cancellable object + filename="gio/ginputstream.c" + line="1110">optional cancellable object scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/ginputstream.c" + line="1111">a #GAsyncReadyCallback to call when the request is satisfied @@ -72800,8 +76295,8 @@ of the request. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/ginputstream.c" + line="1113">the data to pass to callback function @@ -72809,24 +76304,24 @@ of the request. - + %TRUE if the stream was closed successfully. + filename="gio/ginputstream.c" + line="1173">%TRUE if the stream was closed successfully. a #GInputStream. + filename="gio/ginputstream.c" + line="1166">a #GInputStream. a #GAsyncResult. + filename="gio/ginputstream.c" + line="1167">a #GAsyncResult. @@ -72834,7 +76329,7 @@ of the request. - + @@ -72842,7 +76337,7 @@ of the request. - + @@ -72850,7 +76345,7 @@ of the request. - + @@ -72858,7 +76353,7 @@ of the request. - + @@ -72866,7 +76361,7 @@ of the request. - + @@ -72877,33 +76372,33 @@ of the request. c:type="GInputStreamPrivate" disguised="1" opaque="1"> - + Structure used for scatter/gather data input. + filename="gio/giotypes.h" + line="337">Structure used for scatter/gather data input. You generally pass in an array of #GInputVectors and the operation will store the read data starting in the first buffer, switching to the next as needed. - + Pointer to a buffer where data will be written. + filename="gio/giotypes.h" + line="339">Pointer to a buffer where data will be written. the available size in @buffer. + filename="gio/giotypes.h" + line="340">the available size in @buffer. - + @@ -72912,7 +76407,7 @@ first buffer, switching to the next as needed. - + @@ -72925,98 +76420,100 @@ first buffer, switching to the next as needed. glib:get-type="g_list_model_get_type" glib:type-struct="ListModelInterface"> #GListModel is an interface that represents a mutable list of -#GObjects. Its main intention is as a model for various widgets in -user interfaces, such as list views, but it can also be used as a + filename="gio/glistmodel.c" + line="33">`GListModel` is an interface that represents a mutable list of +[class@GObject.Object]. Its main intention is as a model for various widgets +in user interfaces, such as list views, but it can also be used as a convenient method of returning lists of data, with support for updates. Each object in the list may also report changes in itself via some -mechanism (normally the #GObject::notify signal). Taken together -with the #GListModel::items-changed signal, this provides for a list -that can change its membership, and in which the members can change -their individual properties. +mechanism (normally the [signal@GObject.Object::notify] signal). Taken +together with the [signal@Gio.ListModel::items-changed] signal, this provides +for a list that can change its membership, and in which the members can +change their individual properties. A good example would be the list of visible wireless network access points, where each access point can report dynamic properties such as signal strength. -It is important to note that the #GListModel itself does not report +It is important to note that the `GListModel` itself does not report changes to the individual items. It only reports changes to the list membership. If you want to observe changes to the objects themselves then you need to connect signals to the objects that you are interested in. -All items in a #GListModel are of (or derived from) the same type. -g_list_model_get_item_type() returns that type. The type may be an +All items in a `GListModel` are of (or derived from) the same type. +[method@Gio.ListModel.get_item_type] returns that type. The type may be an interface, in which case all objects in the list must implement it. The semantics are close to that of an array: -g_list_model_get_n_items() returns the number of items in the list and -g_list_model_get_item() returns an item at a (0-based) position. In -order to allow implementations to calculate the list length lazily, +[method@Gio.ListModel.get_n_items] returns the number of items in the list +and [method@Gio.ListModel.get_item] returns an item at a (0-based) position. +In order to allow implementations to calculate the list length lazily, you can also iterate over items: starting from 0, repeatedly call -g_list_model_get_item() until it returns %NULL. +[method@Gio.ListModel.get_item] until it returns `NULL`. An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone. On the other side, a consumer is expected only to hold references on -objects that are currently "user visible", in order to facilitate the +objects that are currently ‘user visible’, in order to facilitate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time. This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns -the [thread-default main context][g-main-context-push-thread-default] -in effect at the time that the model was created. +the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) in effect at the time that the +model was created. -Over time, it has established itself as good practice for listmodel +Over time, it has established itself as good practice for list model implementations to provide properties `item-type` and `n-items` to ease working with them. While it is not required, it is recommended that implementations provide these two properties. They should return -the values of g_list_model_get_item_type() and g_list_model_get_n_items() -respectively and be defined as such: -|[<!-- language="C" --> +the values of [method@Gio.ListModel.get_item_type] and +[method@Gio.ListModel.get_n_items] respectively and be defined as such: + +```c properties[PROP_ITEM_TYPE] = - g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT, + g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT, G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); properties[PROP_N_ITEMS] = - g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0, + g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); -]| - +``` + Get the item at @position. If @position is greater than the number of + filename="gio/glistmodel.c" + line="114">Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. %NULL is never returned for an index that is smaller than the length of the list. See g_list_model_get_n_items(). The same #GObject instance may not appear more than once in a #GListModel. - + the object at @position. + filename="gio/glistmodel.c" + line="127">the object at @position. a #GListModel + filename="gio/glistmodel.c" + line="116">a #GListModel the position of the item to fetch + filename="gio/glistmodel.c" + line="117">the position of the item to fetch @@ -73025,8 +76522,8 @@ The same #GObject instance may not appear more than once in a #GListModel. invoker="get_item_type" version="2.44"> Gets the type of the items in @list. + filename="gio/glistmodel.c" + line="166">Gets the type of the items in @list. All items returned from g_list_model_get_item() are of the type returned by this function, or a subtype, or if the type is an @@ -73034,42 +76531,42 @@ interface, they are an implementation of that interface. The item type of a #GListModel can not change during the life of the model. - + the #GType of the items contained in @list. + filename="gio/glistmodel.c" + line="179">the #GType of the items contained in @list. a #GListModel + filename="gio/glistmodel.c" + line="168">a #GListModel Gets the number of items in @list. + filename="gio/glistmodel.c" + line="191">Gets the number of items in @list. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for @position until g_list_model_get_item() returns %NULL. - + the number of items in @list. + filename="gio/glistmodel.c" + line="201">the number of items in @list. a #GListModel + filename="gio/glistmodel.c" + line="193">a #GListModel @@ -73080,8 +76577,8 @@ less efficient than iterating the list with increasing values for version="2.44" introspectable="0"> Get the item at @position. + filename="gio/glistmodel.c" + line="213">Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. @@ -73090,24 +76587,24 @@ returned. of the list. See also: g_list_model_get_n_items() - + the item at @position. + filename="gio/glistmodel.c" + line="228">the item at @position. a #GListModel + filename="gio/glistmodel.c" + line="215">a #GListModel the position of the item to fetch + filename="gio/glistmodel.c" + line="216">the position of the item to fetch @@ -73116,8 +76613,8 @@ See also: g_list_model_get_n_items() c:identifier="g_list_model_get_item_type" version="2.44"> Gets the type of the items in @list. + filename="gio/glistmodel.c" + line="166">Gets the type of the items in @list. All items returned from g_list_model_get_item() are of the type returned by this function, or a subtype, or if the type is an @@ -73125,18 +76622,18 @@ interface, they are an implementation of that interface. The item type of a #GListModel can not change during the life of the model. - + the #GType of the items contained in @list. + filename="gio/glistmodel.c" + line="179">the #GType of the items contained in @list. a #GListModel + filename="gio/glistmodel.c" + line="168">a #GListModel @@ -73145,24 +76642,24 @@ model. c:identifier="g_list_model_get_n_items" version="2.44"> Gets the number of items in @list. + filename="gio/glistmodel.c" + line="191">Gets the number of items in @list. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for @position until g_list_model_get_item() returns %NULL. - + the number of items in @list. + filename="gio/glistmodel.c" + line="201">the number of items in @list. a #GListModel + filename="gio/glistmodel.c" + line="193">a #GListModel @@ -73172,8 +76669,8 @@ less efficient than iterating the list with increasing values for shadows="get_item" version="2.44"> Get the item at @position. + filename="gio/glistmodel.c" + line="241">Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. @@ -73185,24 +76682,24 @@ This function is meant to be used by language bindings in place of g_list_model_get_item(). See also: g_list_model_get_n_items() - + the object at @position. + filename="gio/glistmodel.c" + line="259">the object at @position. a #GListModel + filename="gio/glistmodel.c" + line="243">a #GListModel the position of the item to fetch + filename="gio/glistmodel.c" + line="244">the position of the item to fetch @@ -73211,8 +76708,8 @@ See also: g_list_model_get_n_items() c:identifier="g_list_model_items_changed" version="2.44"> Emits the #GListModel::items-changed signal on @list. + filename="gio/glistmodel.c" + line="276">Emits the #GListModel::items-changed signal on @list. This function should only be called by classes implementing #GListModel. It has to be called after the internal representation @@ -73232,41 +76729,41 @@ Stated another way: in general, it is assumed that code making a series of accesses to the model via the API, without returning to the mainloop, and without calling other code, will continue to view the same contents of the model. - + a #GListModel + filename="gio/glistmodel.c" + line="278">a #GListModel the position at which @list changed + filename="gio/glistmodel.c" + line="279">the position at which @list changed the number of items removed + filename="gio/glistmodel.c" + line="280">the number of items removed the number of items added + filename="gio/glistmodel.c" + line="281">the number of items added This signal is emitted whenever items were added to or removed + filename="gio/glistmodel.c" + line="137">This signal is emitted whenever items were added to or removed from @list. At @position, @removed items were removed and @added items were added in their place. @@ -73278,20 +76775,20 @@ in the model change. the position at which @list changed + filename="gio/glistmodel.c" + line="140">the position at which @list changed the number of items removed + filename="gio/glistmodel.c" + line="141">the number of items removed the number of items added + filename="gio/glistmodel.c" + line="142">the number of items added @@ -73302,73 +76799,82 @@ in the model change. glib:is-gtype-struct-for="ListModel" version="2.44"> The virtual function table for #GListModel. - + filename="gio/glistmodel.c" + line="102">The virtual function table for #GListModel. + parent #GTypeInterface + filename="gio/glistmodel.c" + line="104">parent #GTypeInterface + the virtual function pointer for g_list_model_get_item_type() - + the #GType of the items contained in @list. + filename="gio/glistmodel.c" + line="179">the #GType of the items contained in @list. a #GListModel + filename="gio/glistmodel.c" + line="168">a #GListModel + the virtual function pointer for g_list_model_get_n_items() - + the number of items in @list. + filename="gio/glistmodel.c" + line="201">the number of items in @list. a #GListModel + filename="gio/glistmodel.c" + line="193">a #GListModel + the virtual function pointer for g_list_model_get_item() - + the object at @position. + filename="gio/glistmodel.c" + line="127">the object at @position. a #GListModel + filename="gio/glistmodel.c" + line="116">a #GListModel the position of the item to fetch + filename="gio/glistmodel.c" + line="117">the position of the item to fetch @@ -73383,91 +76889,91 @@ in the model change. glib:get-type="g_list_store_get_type" glib:type-struct="ListStoreClass"> #GListStore is a simple implementation of #GListModel that stores all -items in memory. + filename="gio/gliststore.c" + line="30">`GListStore` is a simple implementation of [iface@Gio.ListModel] that stores +all items in memory. It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly. - + Creates a new #GListStore with items of type @item_type. @item_type + filename="gio/gliststore.c" + line="237">Creates a new #GListStore with items of type @item_type. @item_type must be a subclass of #GObject. - + a new #GListStore + filename="gio/gliststore.c" + line="244">a new #GListStore the #GType of items in the list + filename="gio/gliststore.c" + line="239">the #GType of items in the list Appends @item to @store. @item must be of type #GListStore:item-type. + filename="gio/gliststore.c" + line="361">Appends @item to @store. @item must be of type #GListStore:item-type. This function takes a ref on @item. Use g_list_store_splice() to append multiple items at the same time efficiently. - + a #GListStore + filename="gio/gliststore.c" + line="363">a #GListStore the new item + filename="gio/gliststore.c" + line="364">the new item Looks up the given @item in the list store by looping over the items until + filename="gio/gliststore.c" + line="611">Looks up the given @item in the list store by looping over the items until the first occurrence of @item. If @item was not found, then @position will not be set, and this method will return %FALSE. If you need to compare the two items with a custom comparison function, use g_list_store_find_with_equal_func() with a custom #GEqualFunc instead. - + Whether @store contains @item. If it was found, @position will be + filename="gio/gliststore.c" + line="624">Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. a #GListStore + filename="gio/gliststore.c" + line="613">a #GListStore an item + filename="gio/gliststore.c" + line="614">an item optional="1" allow-none="1"> the first position of @item, if it was found. + filename="gio/gliststore.c" + line="615">the first position of @item, if it was found. @@ -73487,8 +76993,8 @@ set to the position where @item occurred for the first time. c:identifier="g_list_store_find_with_equal_func" version="2.64"> Looks up the given @item in the list store by looping over the items and + filename="gio/gliststore.c" + line="520">Looks up the given @item in the list store by looping over the items and comparing them with @equal_func until the first occurrence of @item which matches. If @item was not found, then @position will not be set, and this method will return %FALSE. @@ -73496,19 +77002,19 @@ method will return %FALSE. @item is always passed as second parameter to @equal_func. Since GLib 2.76 it is possible to pass `NULL` for @item. - + Whether @store contains @item. If it was found, @position will be + filename="gio/gliststore.c" + line="536">Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. a #GListStore + filename="gio/gliststore.c" + line="522">a #GListStore nullable="1" allow-none="1"> an item + filename="gio/gliststore.c" + line="523">an item A custom equality check function + filename="gio/gliststore.c" + line="524">A custom equality check function optional="1" allow-none="1"> the first position of @item, if it was found. + filename="gio/gliststore.c" + line="525">the first position of @item, if it was found. @@ -73543,26 +77049,26 @@ set to the position where @item occurred for the first time. c:identifier="g_list_store_find_with_equal_func_full" version="2.74"> Like g_list_store_find_with_equal_func() but with an additional @user_data + filename="gio/gliststore.c" + line="553">Like g_list_store_find_with_equal_func() but with an additional @user_data that is passed to @equal_func. @item is always passed as second parameter to @equal_func. Since GLib 2.76 it is possible to pass `NULL` for @item. - + Whether @store contains @item. If it was found, @position will be + filename="gio/gliststore.c" + line="568">Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. a #GListStore + filename="gio/gliststore.c" + line="555">a #GListStore nullable="1" allow-none="1"> an item + filename="gio/gliststore.c" + line="556">an item scope="call" closure="2"> A custom equality check function + filename="gio/gliststore.c" + line="557">A custom equality check function nullable="1" allow-none="1"> user data for @equal_func + filename="gio/gliststore.c" + line="558">user data for @equal_func optional="1" allow-none="1"> the first position of @item, if it was found. + filename="gio/gliststore.c" + line="559">the first position of @item, if it was found. Inserts @item into @store at @position. @item must be of type + filename="gio/gliststore.c" + line="260">Inserts @item into @store at @position. @item must be of type #GListStore:item-type or derived from it. @position must be smaller than the length of the list, or equal to it to append. @@ -73616,27 +77122,27 @@ This function takes a ref on @item. Use g_list_store_splice() to insert multiple items at the same time efficiently. - + a #GListStore + filename="gio/gliststore.c" + line="262">a #GListStore the position at which to insert the new item + filename="gio/gliststore.c" + line="263">the position at which to insert the new item the new item + filename="gio/gliststore.c" + line="264">the new item @@ -73645,8 +77151,8 @@ efficiently. c:identifier="g_list_store_insert_sorted" version="2.44"> Inserts @item into @store at a position to be determined by the + filename="gio/gliststore.c" + line="294">Inserts @item into @store at a position to be determined by the @compare_func. The list must already be sorted before calling this function or the @@ -73654,24 +77160,24 @@ result is undefined. Usually you would approach this by only ever inserting items by way of this function. This function takes a ref on @item. - + the position at which @item was inserted + filename="gio/gliststore.c" + line="310">the position at which @item was inserted a #GListStore + filename="gio/gliststore.c" + line="296">a #GListStore the new item + filename="gio/gliststore.c" + line="297">the new item scope="call" closure="2"> pairwise comparison function for sorting + filename="gio/gliststore.c" + line="298">pairwise comparison function for sorting nullable="1" allow-none="1"> user data for @compare_func + filename="gio/gliststore.c" + line="299">user data for @compare_func Removes the item from @store that is at @position. @position must be + filename="gio/gliststore.c" + line="390">Removes the item from @store that is at @position. @position must be smaller than the current length of the list. Use g_list_store_splice() to remove multiple items at the same time efficiently. - + a #GListStore + filename="gio/gliststore.c" + line="392">a #GListStore the position of the item that is to be removed + filename="gio/gliststore.c" + line="393">the position of the item that is to be removed @@ -73725,34 +77231,34 @@ efficiently. c:identifier="g_list_store_remove_all" version="2.44"> Removes all items from @store. - + filename="gio/gliststore.c" + line="418">Removes all items from @store. + a #GListStore + filename="gio/gliststore.c" + line="420">a #GListStore Sort the items in @store according to @compare_func. - + filename="gio/gliststore.c" + line="335">Sort the items in @store according to @compare_func. + a #GListStore + filename="gio/gliststore.c" + line="337">a #GListStore scope="call" closure="1"> pairwise comparison function for sorting + filename="gio/gliststore.c" + line="338">pairwise comparison function for sorting nullable="1" allow-none="1"> user data for @compare_func + filename="gio/gliststore.c" + line="339">user data for @compare_func Changes @store by removing @n_removals items and adding @n_additions + filename="gio/gliststore.c" + line="440">Changes @store by removing @n_removals items and adding @n_additions items to it. @additions must contain @n_additions items of type #GListStore:item-type. %NULL is not permitted. @@ -73791,41 +77297,41 @@ This function takes a ref on each item in @additions. The parameters @position and @n_removals must be correct (ie: @position + @n_removals must be less than or equal to the length of the list at the time this function is called). - + a #GListStore + filename="gio/gliststore.c" + line="442">a #GListStore the position at which to make the change + filename="gio/gliststore.c" + line="443">the position at which to make the change the number of items to remove + filename="gio/gliststore.c" + line="444">the number of items to remove the items to add + filename="gio/gliststore.c" + line="445">the items to add the number of items to add + filename="gio/gliststore.c" + line="446">the number of items to add @@ -73836,8 +77342,8 @@ the list at the time this function is called). construct-only="1" transfer-ownership="none"> The type of items contained in this list store. Items must be + filename="gio/gliststore.c" + line="149">The type of items contained in this list store. Items must be subclasses of #GObject. @@ -73846,15 +77352,15 @@ subclasses of #GObject. transfer-ownership="none" default-value="0"> The number of items contained in this list store. + filename="gio/gliststore.c" + line="161">The number of items contained in this list store. - + @@ -73866,34 +77372,37 @@ subclasses of #GObject. glib:get-type="g_loadable_icon_get_type" glib:type-struct="LoadableIconIface"> Extends the #GIcon interface and adds the ability to -load icons from streams. - + filename="gio/gloadableicon.c" + line="31">`GLoadableIcon` extends the [iface@Gio.Icon] interface and adds the ability +to load icons from streams. + - + Loads a loadable icon. For the asynchronous version of this function, + filename="gio/gloadableicon.c" + line="58">Loads a loadable icon. For the asynchronous version of this function, see g_loadable_icon_load_async(). - + a #GInputStream to read the icon from. + filename="gio/gloadableicon.c" + line="72">a #GInputStream to read the icon from. a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="60">a #GLoadableIcon. an integer. + filename="gio/gloadableicon.c" + line="61">an integer. optional="1" allow-none="1"> a location to store the type of the loaded + filename="gio/gloadableicon.c" + line="62">a location to store the type of the loaded icon, %NULL to ignore. @@ -73913,34 +77422,37 @@ icon, %NULL to ignore. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to + filename="gio/gloadableicon.c" + line="64">optional #GCancellable object, %NULL to ignore. - + Loads an icon asynchronously. To finish this function, see + filename="gio/gloadableicon.c" + line="90">Loads an icon asynchronously. To finish this function, see g_loadable_icon_load_finish(). For the synchronous, blocking version of this function, see g_loadable_icon_load(). - + a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="92">a #GLoadableIcon. an integer. + filename="gio/gloadableicon.c" + line="93">an integer. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gloadableicon.c" + line="94">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gloadableicon.c" + line="95">a #GAsyncReadyCallback to call when the request is satisfied @@ -73970,34 +77482,34 @@ version of this function, see g_loadable_icon_load(). allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gloadableicon.c" + line="97">the data to pass to callback function Finishes an asynchronous icon load started in g_loadable_icon_load_async(). - + filename="gio/gloadableicon.c" + line="119">Finishes an asynchronous icon load started in g_loadable_icon_load_async(). + a #GInputStream to read the icon from. + filename="gio/gloadableicon.c" + line="130">a #GInputStream to read the icon from. a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="121">a #GLoadableIcon. a #GAsyncResult. + filename="gio/gloadableicon.c" + line="122">a #GAsyncResult. optional="1" allow-none="1"> a location to store the type of the loaded + filename="gio/gloadableicon.c" + line="123">a location to store the type of the loaded icon, %NULL to ignore. - + Loads a loadable icon. For the asynchronous version of this function, + filename="gio/gloadableicon.c" + line="58">Loads a loadable icon. For the asynchronous version of this function, see g_loadable_icon_load_async(). - + a #GInputStream to read the icon from. + filename="gio/gloadableicon.c" + line="72">a #GInputStream to read the icon from. a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="60">a #GLoadableIcon. an integer. + filename="gio/gloadableicon.c" + line="61">an integer. optional="1" allow-none="1"> a location to store the type of the loaded + filename="gio/gloadableicon.c" + line="62">a location to store the type of the loaded icon, %NULL to ignore. @@ -74056,34 +77571,37 @@ icon, %NULL to ignore. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to + filename="gio/gloadableicon.c" + line="64">optional #GCancellable object, %NULL to ignore. - + Loads an icon asynchronously. To finish this function, see + filename="gio/gloadableicon.c" + line="90">Loads an icon asynchronously. To finish this function, see g_loadable_icon_load_finish(). For the synchronous, blocking version of this function, see g_loadable_icon_load(). - + a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="92">a #GLoadableIcon. an integer. + filename="gio/gloadableicon.c" + line="93">an integer. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gloadableicon.c" + line="94">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gloadableicon.c" + line="95">a #GAsyncReadyCallback to call when the request is satisfied @@ -74112,8 +77630,8 @@ version of this function, see g_loadable_icon_load(). nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gloadableicon.c" + line="97">the data to pass to callback function @@ -74122,26 +77640,26 @@ version of this function, see g_loadable_icon_load(). c:identifier="g_loadable_icon_load_finish" throws="1"> Finishes an asynchronous icon load started in g_loadable_icon_load_async(). - + filename="gio/gloadableicon.c" + line="119">Finishes an asynchronous icon load started in g_loadable_icon_load_async(). + a #GInputStream to read the icon from. + filename="gio/gloadableicon.c" + line="130">a #GInputStream to read the icon from. a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="121">a #GLoadableIcon. a #GAsyncResult. + filename="gio/gloadableicon.c" + line="122">a #GAsyncResult. optional="1" allow-none="1"> a location to store the type of the loaded + filename="gio/gloadableicon.c" + line="123">a location to store the type of the loaded icon, %NULL to ignore. @@ -74163,35 +77681,38 @@ version of this function, see g_loadable_icon_load(). c:type="GLoadableIconIface" glib:is-gtype-struct-for="LoadableIcon"> Interface for icons that can be loaded as a stream. - + filename="gio/gloadableicon.h" + line="41">Interface for icons that can be loaded as a stream. + The parent interface. + filename="gio/gloadableicon.h" + line="43">The parent interface. + Loads an icon. - + a #GInputStream to read the icon from. + filename="gio/gloadableicon.c" + line="72">a #GInputStream to read the icon from. a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="60">a #GLoadableIcon. an integer. + filename="gio/gloadableicon.c" + line="61">an integer. optional="1" allow-none="1"> a location to store the type of the loaded + filename="gio/gloadableicon.c" + line="62">a location to store the type of the loaded icon, %NULL to ignore. @@ -74211,8 +77732,8 @@ icon, %NULL to ignore. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to + filename="gio/gloadableicon.c" + line="64">optional #GCancellable object, %NULL to ignore. @@ -74220,22 +77741,25 @@ ignore. + Loads an icon asynchronously. - + a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="92">a #GLoadableIcon. an integer. + filename="gio/gloadableicon.c" + line="93">an integer. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gloadableicon.c" + line="94">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gloadableicon.c" + line="95">a #GAsyncReadyCallback to call when the request is satisfied @@ -74265,33 +77789,36 @@ ignore. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gloadableicon.c" + line="97">the data to pass to callback function + Finishes an asynchronous icon load. - + a #GInputStream to read the icon from. + filename="gio/gloadableicon.c" + line="130">a #GInputStream to read the icon from. a #GLoadableIcon. + filename="gio/gloadableicon.c" + line="121">a #GLoadableIcon. a #GAsyncResult. + filename="gio/gloadableicon.c" + line="122">a #GAsyncResult. optional="1" allow-none="1"> a location to store the type of the loaded + filename="gio/gloadableicon.c" + line="123">a location to store the type of the loaded icon, %NULL to ignore. @@ -74313,7 +77840,7 @@ ignore. - + @@ -74322,7 +77849,7 @@ ignore. - + @@ -74331,7 +77858,7 @@ ignore. - + @@ -74340,7 +77867,7 @@ ignore. - + @@ -74351,16 +77878,16 @@ ignore. c:type="G_MEMORY_MONITOR_EXTENSION_POINT_NAME" version="2.64"> Extension point for memory usage monitoring functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -74369,7 +77896,7 @@ See [Extending GIO][extending-gio]. - + @@ -74378,7 +77905,7 @@ See [Extending GIO][extending-gio]. - + @@ -74387,14 +77914,14 @@ See [Extending GIO][extending-gio]. - + - + @@ -74405,14 +77932,14 @@ See [Extending GIO][extending-gio]. c:type="G_MENU_ATTRIBUTE_ACTION" version="2.32"> The menu item attribute which holds the action name of the item. Action names are namespaced with an identifier for the action group in which the action resides. For example, "win." for window-specific actions and "app." for application-wide actions. See also g_menu_model_get_item_attribute() and g_menu_item_set_attribute(). - + The menu item attribute that holds the namespace for all action names in menus that are linked from this item. - + c:type="G_MENU_ATTRIBUTE_ICON" version="2.38"> The menu item attribute which holds the icon of the item. The icon is stored in the format returned by g_icon_serialize(). @@ -74439,13 +77966,13 @@ The icon is stored in the format returned by g_icon_serialize(). This attribute is intended only to represent 'noun' icons such as favicons for a webpage, or application icons. It should not be used for 'verbs' (ie: stock icons). - + - + @@ -74454,7 +77981,7 @@ for 'verbs' (ie: stock icons). - + @@ -74463,7 +77990,7 @@ for 'verbs' (ie: stock icons). - + @@ -74474,9 +78001,9 @@ for 'verbs' (ie: stock icons). c:type="G_MENU_ATTRIBUTE_LABEL" version="2.32"> The menu item attribute which holds the label of the item. - + c:type="G_MENU_ATTRIBUTE_TARGET" version="2.32"> The menu item attribute which holds the target with which the item's action will be activated. See also g_menu_item_set_action_and_target() - + c:type="G_MENU_EXPORTER_MAX_SECTION_SIZE" version="2.76"> The maximum number of entries in a menu section supported by g_dbus_connection_export_menu_model(). The exact value of the limit may change in future GLib versions. - + - + @@ -74517,7 +78044,7 @@ The exact value of the limit may change in future GLib versions. - + @@ -74526,7 +78053,7 @@ The exact value of the limit may change in future GLib versions. - + @@ -74535,7 +78062,7 @@ The exact value of the limit may change in future GLib versions. - + @@ -74546,13 +78073,13 @@ The exact value of the limit may change in future GLib versions. c:type="G_MENU_LINK_SECTION" version="2.32"> The name of the link that associates a menu item with a section. The linked menu will usually be shown in place of the menu item, using the item's label as a header. See also g_menu_item_set_link(). - + c:type="G_MENU_LINK_SUBMENU" version="2.32"> The name of the link that associates a menu item with a submenu. See also g_menu_item_set_link(). - + - + @@ -74579,7 +78106,7 @@ See also g_menu_item_set_link(). - + @@ -74588,14 +78115,14 @@ See also g_menu_item_set_link(). - + - + @@ -74604,7 +78131,7 @@ See also g_menu_item_set_link(). - + @@ -74613,7 +78140,7 @@ See also g_menu_item_set_link(). - + @@ -74622,7 +78149,7 @@ See also g_menu_item_set_link(). - + @@ -74631,7 +78158,7 @@ See also g_menu_item_set_link(). - + @@ -74645,24 +78172,24 @@ See also g_menu_item_set_link(). glib:get-type="g_memory_input_stream_get_type" glib:type-struct="MemoryInputStreamClass"> #GMemoryInputStream is a class for using arbitrary + filename="gio/gmemoryinputstream.c" + line="34">`GMemoryInputStream` is a class for using arbitrary memory chunks as input for GIO streaming input operations. -As of GLib 2.34, #GMemoryInputStream implements -#GPollableInputStream. - +As of GLib 2.34, `GMemoryInputStream` implements +[iface@Gio.PollableInputStream]. + Creates a new empty #GMemoryInputStream. - + filename="gio/gmemoryinputstream.c" + line="167">Creates a new empty #GMemoryInputStream. + a new #GInputStream + filename="gio/gmemoryinputstream.c" + line="172">a new #GInputStream @@ -74670,20 +78197,20 @@ As of GLib 2.34, #GMemoryInputStream implements c:identifier="g_memory_input_stream_new_from_bytes" version="2.34"> Creates a new #GMemoryInputStream with data from the given @bytes. - + filename="gio/gmemoryinputstream.c" + line="209">Creates a new #GMemoryInputStream with data from the given @bytes. + new #GInputStream read from @bytes + filename="gio/gmemoryinputstream.c" + line="215">new #GInputStream read from @bytes a #GBytes + filename="gio/gmemoryinputstream.c" + line="211">a #GBytes @@ -74691,28 +78218,28 @@ As of GLib 2.34, #GMemoryInputStream implements Creates a new #GMemoryInputStream with data in memory of a given size. - + filename="gio/gmemoryinputstream.c" + line="184">Creates a new #GMemoryInputStream with data in memory of a given size. + new #GInputStream read from @data of @len bytes. + filename="gio/gmemoryinputstream.c" + line="192">new #GInputStream read from @data of @len bytes. input data + filename="gio/gmemoryinputstream.c" + line="186">input data length of the data, may be -1 if @data is a nul-terminated string + filename="gio/gmemoryinputstream.c" + line="187">length of the data, may be -1 if @data is a nul-terminated string function that is called to free @data, or %NULL + filename="gio/gmemoryinputstream.c" + line="188">function that is called to free @data, or %NULL @@ -74731,54 +78258,54 @@ As of GLib 2.34, #GMemoryInputStream implements c:identifier="g_memory_input_stream_add_bytes" version="2.34"> Appends @bytes to data that can be read from the input stream. - + filename="gio/gmemoryinputstream.c" + line="263">Appends @bytes to data that can be read from the input stream. + a #GMemoryInputStream + filename="gio/gmemoryinputstream.c" + line="265">a #GMemoryInputStream input data + filename="gio/gmemoryinputstream.c" + line="266">input data Appends @data to data that can be read from the input stream - + filename="gio/gmemoryinputstream.c" + line="233">Appends @data to data that can be read from the input stream + a #GMemoryInputStream + filename="gio/gmemoryinputstream.c" + line="235">a #GMemoryInputStream input data + filename="gio/gmemoryinputstream.c" + line="236">input data length of the data, may be -1 if @data is a nul-terminated string + filename="gio/gmemoryinputstream.c" + line="237">length of the data, may be -1 if @data is a nul-terminated string function that is called to free @data, or %NULL + filename="gio/gmemoryinputstream.c" + line="238">function that is called to free @data, or %NULL @@ -74804,13 +78331,13 @@ As of GLib 2.34, #GMemoryInputStream implements - + - + @@ -74818,7 +78345,7 @@ As of GLib 2.34, #GMemoryInputStream implements - + @@ -74826,7 +78353,7 @@ As of GLib 2.34, #GMemoryInputStream implements - + @@ -74834,7 +78361,7 @@ As of GLib 2.34, #GMemoryInputStream implements - + @@ -74842,7 +78369,7 @@ As of GLib 2.34, #GMemoryInputStream implements - + @@ -74853,7 +78380,7 @@ As of GLib 2.34, #GMemoryInputStream implements c:type="GMemoryInputStreamPrivate" disguised="1" opaque="1"> - + #GMemoryMonitor will monitor system memory and suggest to the application + filename="gio/gmemorymonitor.c" + line="33">`GMemoryMonitor` will monitor system memory and suggest to the application when to free memory so as to leave more room for other applications. -It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) +It is implemented on Linux using the +[Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) ([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)). There is also an implementation for use inside Flatpak sandboxes. @@ -74874,11 +78402,11 @@ There is also an implementation for use inside Flatpak sandboxes. Possible actions to take when the signal is received are: - Free caches - - Save files that haven't been looked at in a while to disk, ready to be reopened when needed + - Save files that haven’t been looked at in a while to disk, ready to be reopened when needed - Run a garbage collection cycle - Try and compress fragmented allocations - Exit on idle if the process has no reason to stay around - - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + - Call [`malloc_trim(3)`](man:malloc_trim(3)) to return cached heap pages to the kernel (if supported by your libc) Note that some actions may not always improve system performance, and so @@ -74886,9 +78414,10 @@ should be profiled for your application. `malloc_trim()`, for example, may make future heap allocations slower (due to releasing cached heap pages back to the kernel). -See #GMemoryMonitorWarningLevel for details on the various warning levels. +See [type@Gio.MemoryMonitorWarningLevel] for details on the various warning +levels. -|[<!-- language="C" --> +```c static void warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level) { @@ -74906,28 +78435,32 @@ monitor_low_memory (void) G_CALLBACK (warning_cb), NULL); return m; } -]| +``` -Don't forget to disconnect the #GMemoryMonitor::low-memory-warning -signal, and unref the #GMemoryMonitor itself when exiting. - +Don’t forget to disconnect the [signal@Gio.MemoryMonitor::low-memory-warning] +signal, and unref the `GMemoryMonitor` itself when exiting. + Gets a reference to the default #GMemoryMonitor for the system. - + filename="gio/gmemorymonitor.c" + line="109">Gets a reference to the default #GMemoryMonitor for the system. + a new reference to the default #GMemoryMonitor + filename="gio/gmemorymonitor.c" + line="114">a new reference to the default #GMemoryMonitor - + the virtual function pointer for the + #GMemoryMonitor::low-memory-warning signal. + @@ -74943,8 +78476,8 @@ signal, and unref the #GMemoryMonitor itself when exiting. Emitted when the system is running low on free memory. The signal + filename="gio/gmemorymonitor.c" + line="129">Emitted when the system is running low on free memory. The signal handler should then take the appropriate action depending on the warning level. See the #GMemoryMonitorWarningLevel documentation for details. @@ -74954,8 +78487,8 @@ details. the #GMemoryMonitorWarningLevel warning level + filename="gio/gmemorymonitor.c" + line="132">the #GMemoryMonitorWarningLevel warning level @@ -74966,18 +78499,22 @@ details. glib:is-gtype-struct-for="MemoryMonitor" version="2.64"> The virtual function table for #GMemoryMonitor. - + filename="gio/gmemorymonitor.c" + line="88">The virtual function table for #GMemoryMonitor. + The parent interface. + filename="gio/gmemorymonitor.c" + line="90">The parent interface. + the virtual function pointer for the + #GMemoryMonitor::low-memory-warning signal. - + @@ -74999,8 +78536,8 @@ details. glib:get-type="g_memory_monitor_warning_level_get_type" c:type="GMemoryMonitorWarningLevel"> Memory availability warning levels. + filename="gio/gioenums.h" + line="2134">Memory availability warning levels. Note that because new values might be added, it is recommended that applications check #GMemoryMonitorWarningLevel as ranges, for example: @@ -75014,8 +78551,8 @@ if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) glib:nick="low" glib:name="G_MEMORY_MONITOR_WARNING_LEVEL_LOW"> Memory on the device is low, processes + filename="gio/gioenums.h" + line="2136">Memory on the device is low, processes should free up unneeded resources (for example, in-memory caches) so they can be used elsewhere. @@ -75025,8 +78562,8 @@ if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) glib:nick="medium" glib:name="G_MEMORY_MONITOR_WARNING_LEVEL_MEDIUM"> Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW + filename="gio/gioenums.h" + line="2139">Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW but the device has even less free memory, so processes should try harder to free up unneeded resources. If your process does not need to stay running, it is a good time for it to quit. @@ -75037,8 +78574,8 @@ if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) glib:nick="critical" glib:name="G_MEMORY_MONITOR_WARNING_LEVEL_CRITICAL"> The system will soon start terminating + filename="gio/gioenums.h" + line="2143">The system will soon start terminating processes to reclaim memory, including background processes. @@ -75050,21 +78587,21 @@ if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) glib:get-type="g_memory_output_stream_get_type" glib:type-struct="MemoryOutputStreamClass"> #GMemoryOutputStream is a class for using arbitrary + filename="gio/gmemoryoutputstream.c" + line="37">`GMemoryOutputStream` is a class for using arbitrary memory chunks as output for GIO streaming output operations. -As of GLib 2.34, #GMemoryOutputStream trivially implements -#GPollableOutputStream: it always polls as ready. - +As of GLib 2.34, `GMemoryOutputStream` trivially implements +[iface@Gio.PollableOutputStream]: it always polls as ready. + Creates a new #GMemoryOutputStream. + filename="gio/gmemoryoutputstream.c" + line="321">Creates a new #GMemoryOutputStream. In most cases this is not the function you want. See g_memory_output_stream_new_resizable() instead. @@ -75105,11 +78642,11 @@ stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); data = malloc (200); stream3 = g_memory_output_stream_new (data, 200, NULL, free); ]| - + A newly created #GMemoryOutputStream object. + filename="gio/gmemoryoutputstream.c" + line="372">A newly created #GMemoryOutputStream object. @@ -75118,14 +78655,14 @@ stream3 = g_memory_output_stream_new (data, 200, NULL, free); nullable="1" allow-none="1"> pointer to a chunk of memory to use, or %NULL + filename="gio/gmemoryoutputstream.c" + line="323">pointer to a chunk of memory to use, or %NULL the size of @data + filename="gio/gmemoryoutputstream.c" + line="324">the size of @data a function with realloc() semantics (like g_realloc()) + filename="gio/gmemoryoutputstream.c" + line="325">a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL @@ -75146,8 +78683,8 @@ stream3 = g_memory_output_stream_new (data, 200, NULL, free); allow-none="1" scope="async"> a function to be called on @data when the stream is + filename="gio/gmemoryoutputstream.c" + line="327">a function to be called on @data when the stream is finalized, or %NULL @@ -75157,10 +78694,10 @@ stream3 = g_memory_output_stream_new (data, 200, NULL, free); c:identifier="g_memory_output_stream_new_resizable" version="2.36"> Creates a new #GMemoryOutputStream, using g_realloc() and g_free() + filename="gio/gmemoryoutputstream.c" + line="392">Creates a new #GMemoryOutputStream, using g_realloc() and g_free() for memory allocation. - + @@ -75169,24 +78706,24 @@ for memory allocation. c:identifier="g_memory_output_stream_get_data" glib:get-property="data"> Gets any loaded data from the @ostream. + filename="gio/gmemoryoutputstream.c" + line="406">Gets any loaded data from the @ostream. Note that the returned pointer may become invalid on the next write or truncate operation on the stream. - + pointer to the stream's data, or %NULL if the data + filename="gio/gmemoryoutputstream.c" + line="415">pointer to the stream's data, or %NULL if the data has been stolen a #GMemoryOutputStream + filename="gio/gmemoryoutputstream.c" + line="408">a #GMemoryOutputStream @@ -75196,21 +78733,21 @@ write or truncate operation on the stream. glib:get-property="data-size" version="2.18"> Returns the number of bytes from the start up to including the last + filename="gio/gmemoryoutputstream.c" + line="456">Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away. - + the number of bytes written to the stream + filename="gio/gmemoryoutputstream.c" + line="463">the number of bytes written to the stream a #GMemoryOutputStream + filename="gio/gmemoryoutputstream.c" + line="458">a #GMemoryOutputStream @@ -75219,8 +78756,8 @@ byte written in the stream that has not been truncated away. c:identifier="g_memory_output_stream_get_size" glib:get-property="size"> Gets the size of the currently allocated data area (available from + filename="gio/gmemoryoutputstream.c" + line="426">Gets the size of the currently allocated data area (available from g_memory_output_stream_get_data()). You probably don't want to use this function on resizable streams. @@ -75235,18 +78772,18 @@ stream and further writes will return %G_IO_ERROR_NO_SPACE. In any case, if you want the number of bytes currently written to the stream, use g_memory_output_stream_get_data_size(). - + the number of bytes allocated for the data buffer + filename="gio/gmemoryoutputstream.c" + line="446">the number of bytes allocated for the data buffer a #GMemoryOutputStream + filename="gio/gmemoryoutputstream.c" + line="428">a #GMemoryOutputStream @@ -75255,21 +78792,21 @@ stream, use g_memory_output_stream_get_data_size(). c:identifier="g_memory_output_stream_steal_as_bytes" version="2.34"> Returns data from the @ostream as a #GBytes. @ostream must be + filename="gio/gmemoryoutputstream.c" + line="505">Returns data from the @ostream as a #GBytes. @ostream must be closed before calling this function. - + the stream's data + filename="gio/gmemoryoutputstream.c" + line="512">the stream's data a #GMemoryOutputStream + filename="gio/gmemoryoutputstream.c" + line="507">a #GMemoryOutputStream @@ -75278,26 +78815,26 @@ closed before calling this function. c:identifier="g_memory_output_stream_steal_data" version="2.26"> Gets any loaded data from the @ostream. Ownership of the data + filename="gio/gmemoryoutputstream.c" + line="475">Gets any loaded data from the @ostream. Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in @ostream's #GMemoryOutputStream:destroy-function property. @ostream must be closed before calling this function. - + the stream's data, or %NULL if it has previously + filename="gio/gmemoryoutputstream.c" + line="486">the stream's data, or %NULL if it has previously been stolen a #GMemoryOutputStream + filename="gio/gmemoryoutputstream.c" + line="477">a #GMemoryOutputStream @@ -75309,8 +78846,8 @@ freed using the free function set in @ostream's transfer-ownership="none" getter="get_data"> Pointer to buffer where data will be written. + filename="gio/gmemoryoutputstream.c" + line="145">Pointer to buffer where data will be written. Size of data written to the buffer. + filename="gio/gmemoryoutputstream.c" + line="172">Size of data written to the buffer. Function called with the buffer as argument when the stream is destroyed. + filename="gio/gmemoryoutputstream.c" + line="199">Function called with the buffer as argument when the stream is destroyed. Function with realloc semantics called to enlarge the buffer. + filename="gio/gmemoryoutputstream.c" + line="186">Function with realloc semantics called to enlarge the buffer. Current size of the data buffer. + filename="gio/gmemoryoutputstream.c" + line="158">Current size of the data buffer. @@ -75368,13 +78905,13 @@ freed using the free function set in @ostream's - + - + @@ -75382,7 +78919,7 @@ freed using the free function set in @ostream's - + @@ -75390,7 +78927,7 @@ freed using the free function set in @ostream's - + @@ -75398,7 +78935,7 @@ freed using the free function set in @ostream's - + @@ -75406,7 +78943,7 @@ freed using the free function set in @ostream's - + @@ -75417,7 +78954,7 @@ freed using the free function set in @ostream's c:type="GMemoryOutputStreamPrivate" disguised="1" opaque="1"> - + #GMenu is a simple implementation of #GMenuModel. -You populate a #GMenu by adding #GMenuItem instances to it. + filename="gio/gmenu.c" + line="31">`GMenu` is a simple implementation of [class@Gio.MenuModel]. +You populate a `GMenu` by adding [class@Gio.MenuItem] instances to it. There are some convenience functions to allow you to directly -add items (avoiding #GMenuItem) for the common cases. To add -a regular item, use g_menu_insert(). To add a section, use -g_menu_insert_section(). To add a submenu, use -g_menu_insert_submenu(). +add items (avoiding [class@Gio.MenuItem]) for the common cases. To add +a regular item, use [method@Gio.Menu.insert]. To add a section, use +[method@Gio.Menu.insert_section]. To add a submenu, use +[method@Gio.Menu.insert_submenu]. Creates a new #GMenu. + filename="gio/gmenu.c" + line="227">Creates a new #GMenu. The new menu has no items. - + a new #GMenu + filename="gio/gmenu.c" + line="234">a new #GMenu Convenience function for appending a normal menu item to the end of + filename="gio/gmenu.c" + line="290">Convenience function for appending a normal menu item to the end of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="292">a #GMenu nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="293">the section label, or %NULL nullable="1" allow-none="1"> the detailed action string, or %NULL + filename="gio/gmenu.c" + line="294">the detailed action string, or %NULL @@ -75491,25 +79028,25 @@ flexible alternative. c:identifier="g_menu_append_item" version="2.32"> Appends @item to the end of @menu. + filename="gio/gmenu.c" + line="186">Appends @item to the end of @menu. See g_menu_insert_item() for more information. - + a #GMenu + filename="gio/gmenu.c" + line="188">a #GMenu a #GMenuItem to append + filename="gio/gmenu.c" + line="189">a #GMenuItem to append @@ -75518,19 +79055,19 @@ See g_menu_insert_item() for more information. c:identifier="g_menu_append_section" version="2.32"> Convenience function for appending a section menu item to the end of + filename="gio/gmenu.c" + line="357">Convenience function for appending a section menu item to the end of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="359">a #GMenu nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="360">the section label, or %NULL a #GMenuModel with the items of the section + filename="gio/gmenu.c" + line="361">a #GMenuModel with the items of the section @@ -75554,19 +79091,19 @@ more flexible alternative. c:identifier="g_menu_append_submenu" version="2.32"> Convenience function for appending a submenu menu item to the end of + filename="gio/gmenu.c" + line="423">Convenience function for appending a submenu menu item to the end of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="425">a #GMenu nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="426">the section label, or %NULL a #GMenuModel with the items of the submenu + filename="gio/gmenu.c" + line="427">a #GMenuModel with the items of the submenu Marks @menu as frozen. + filename="gio/gmenu.c" + line="204">Marks @menu as frozen. After the menu is frozen, it is an error to attempt to make any changes to it. In effect this means that the #GMenu API must no @@ -75597,40 +79134,40 @@ longer be used. This function causes g_menu_model_is_mutable() to begin returning %FALSE, which has some positive performance implications. - + a #GMenu + filename="gio/gmenu.c" + line="206">a #GMenu Convenience function for inserting a normal menu item into @menu. + filename="gio/gmenu.c" + line="244">Convenience function for inserting a normal menu item into @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="246">a #GMenu the position at which to insert the item + filename="gio/gmenu.c" + line="247">the position at which to insert the item nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="248">the section label, or %NULL nullable="1" allow-none="1"> the detailed action string, or %NULL + filename="gio/gmenu.c" + line="249">the detailed action string, or %NULL @@ -75657,8 +79194,8 @@ alternative. c:identifier="g_menu_insert_item" version="2.32"> Inserts @item into @menu. + filename="gio/gmenu.c" + line="121">Inserts @item into @menu. The "insertion" is actually done by copying all of the attribute and link values of @item and using them to form a new item within @menu. @@ -75675,27 +79212,27 @@ There are many convenience functions to take care of common cases. See g_menu_insert(), g_menu_insert_section() and g_menu_insert_submenu() as well as "prepend" and "append" variants of each of these functions. - + a #GMenu + filename="gio/gmenu.c" + line="123">a #GMenu the position at which to insert the item + filename="gio/gmenu.c" + line="124">the position at which to insert the item the #GMenuItem to insert + filename="gio/gmenu.c" + line="125">the #GMenuItem to insert @@ -75704,25 +79241,25 @@ each of these functions. c:identifier="g_menu_insert_section" version="2.32"> Convenience function for inserting a section menu item into @menu. + filename="gio/gmenu.c" + line="310">Convenience function for inserting a section menu item into @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="312">a #GMenu the position at which to insert the item + filename="gio/gmenu.c" + line="313">the position at which to insert the item nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="314">the section label, or %NULL a #GMenuModel with the items of the section + filename="gio/gmenu.c" + line="315">a #GMenuModel with the items of the section @@ -75746,25 +79283,25 @@ flexible alternative. c:identifier="g_menu_insert_submenu" version="2.32"> Convenience function for inserting a submenu menu item into @menu. + filename="gio/gmenu.c" + line="377">Convenience function for inserting a submenu menu item into @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="379">a #GMenu the position at which to insert the item + filename="gio/gmenu.c" + line="380">the position at which to insert the item nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="381">the section label, or %NULL a #GMenuModel with the items of the submenu + filename="gio/gmenu.c" + line="382">a #GMenuModel with the items of the submenu Convenience function for prepending a normal menu item to the start + filename="gio/gmenu.c" + line="270">Convenience function for prepending a normal menu item to the start of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="272">a #GMenu nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="273">the section label, or %NULL nullable="1" allow-none="1"> the detailed action string, or %NULL + filename="gio/gmenu.c" + line="274">the detailed action string, or %NULL @@ -75825,25 +79362,25 @@ flexible alternative. c:identifier="g_menu_prepend_item" version="2.32"> Prepends @item to the start of @menu. + filename="gio/gmenu.c" + line="168">Prepends @item to the start of @menu. See g_menu_insert_item() for more information. - + a #GMenu + filename="gio/gmenu.c" + line="170">a #GMenu a #GMenuItem to prepend + filename="gio/gmenu.c" + line="171">a #GMenuItem to prepend @@ -75852,19 +79389,19 @@ See g_menu_insert_item() for more information. c:identifier="g_menu_prepend_section" version="2.32"> Convenience function for prepending a section menu item to the start + filename="gio/gmenu.c" + line="337">Convenience function for prepending a section menu item to the start of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="339">a #GMenu nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="340">the section label, or %NULL a #GMenuModel with the items of the section + filename="gio/gmenu.c" + line="341">a #GMenuModel with the items of the section @@ -75888,19 +79425,19 @@ a more flexible alternative. c:identifier="g_menu_prepend_submenu" version="2.32"> Convenience function for prepending a submenu menu item to the start + filename="gio/gmenu.c" + line="403">Convenience function for prepending a submenu menu item to the start of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative. - + a #GMenu + filename="gio/gmenu.c" + line="405">a #GMenu nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="406">the section label, or %NULL a #GMenuModel with the items of the submenu + filename="gio/gmenu.c" + line="407">a #GMenuModel with the items of the submenu Removes an item from the menu. + filename="gio/gmenu.c" + line="452">Removes an item from the menu. @position gives the index of the item to remove. @@ -75933,21 +79470,21 @@ less than the number of items in the menu. It is not possible to remove items by identity since items are added to the menu simply by copying their links and attributes (ie: identity of the item itself is not preserved). - + a #GMenu + filename="gio/gmenu.c" + line="454">a #GMenu the position of the item to remove + filename="gio/gmenu.c" + line="455">the position of the item to remove @@ -75956,17 +79493,17 @@ identity of the item itself is not preserved). c:identifier="g_menu_remove_all" version="2.38"> Removes all items in the menu. - + filename="gio/gmenu.c" + line="482">Removes all items in the menu. + a #GMenu + filename="gio/gmenu.c" + line="484">a #GMenu @@ -75982,14 +79519,14 @@ identity of the item itself is not preserved). glib:get-type="g_menu_attribute_iter_get_type" glib:type-struct="MenuAttributeIterClass"> #GMenuAttributeIter is an opaque structure type. You must access it + filename="gio/gmenumodel.c" + line="155">#GMenuAttributeIter is an opaque structure type. You must access it using the functions below. - + This function combines g_menu_attribute_iter_next() with + filename="gio/gmenumodel.c" + line="704">This function combines g_menu_attribute_iter_next() with g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). First the iterator is advanced to the next (possibly first) attribute. @@ -76004,19 +79541,19 @@ return the same values again. The value returned in @name remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_variant_unref() when it is no longer in use. - + %TRUE on success, or %FALSE if there is no additional + filename="gio/gmenumodel.c" + line="726">%TRUE on success, or %FALSE if there is no additional attribute a #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="706">a #GMenuAttributeIter optional="1" allow-none="1"> the type of the attribute + filename="gio/gmenumodel.c" + line="707">the type of the attribute optional="1" allow-none="1"> the attribute value + filename="gio/gmenumodel.c" + line="708">the attribute value @@ -76047,23 +79584,23 @@ be unreffed using g_variant_unref() when it is no longer in use. c:identifier="g_menu_attribute_iter_get_name" version="2.32"> Gets the name of the attribute at the current iterator position, as + filename="gio/gmenumodel.c" + line="784">Gets the name of the attribute at the current iterator position, as a string. The iterator is not advanced. - + the name of the attribute + filename="gio/gmenumodel.c" + line="793">the name of the attribute a #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="786">a #GMenuAttributeIter @@ -76072,8 +79609,8 @@ The iterator is not advanced. c:identifier="g_menu_attribute_iter_get_next" version="2.32"> This function combines g_menu_attribute_iter_next() with + filename="gio/gmenumodel.c" + line="704">This function combines g_menu_attribute_iter_next() with g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). First the iterator is advanced to the next (possibly first) attribute. @@ -76088,19 +79625,19 @@ return the same values again. The value returned in @name remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_variant_unref() when it is no longer in use. - + %TRUE on success, or %FALSE if there is no additional + filename="gio/gmenumodel.c" + line="726">%TRUE on success, or %FALSE if there is no additional attribute a #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="706">a #GMenuAttributeIter optional="1" allow-none="1"> the type of the attribute + filename="gio/gmenumodel.c" + line="707">the type of the attribute optional="1" allow-none="1"> the attribute value + filename="gio/gmenumodel.c" + line="708">the attribute value @@ -76131,22 +79668,22 @@ be unreffed using g_variant_unref() when it is no longer in use. c:identifier="g_menu_attribute_iter_get_value" version="2.32"> Gets the value of the attribute at the current iterator position. + filename="gio/gmenumodel.c" + line="805">Gets the value of the attribute at the current iterator position. The iterator is not advanced. - + the value of the current attribute + filename="gio/gmenumodel.c" + line="813">the value of the current attribute a #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="807">a #GMenuAttributeIter @@ -76155,8 +79692,8 @@ The iterator is not advanced. c:identifier="g_menu_attribute_iter_next" version="2.32"> Attempts to advance the iterator to the next (possibly first) + filename="gio/gmenumodel.c" + line="760">Attempts to advance the iterator to the next (possibly first) attribute. %TRUE is returned on success, or %FALSE if there are no more @@ -76165,18 +79702,18 @@ attributes. You must call this function when you first acquire the iterator to advance it to the first attribute (and determine if the first attribute exists at all). - + %TRUE on success, or %FALSE when there are no more attributes + filename="gio/gmenumodel.c" + line="774">%TRUE on success, or %FALSE when there are no more attributes a #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="762">a #GMenuAttributeIter @@ -76192,25 +79729,25 @@ attribute exists at all). - + - + %TRUE on success, or %FALSE if there is no additional + filename="gio/gmenumodel.c" + line="726">%TRUE on success, or %FALSE if there is no additional attribute a #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="706">a #GMenuAttributeIter optional="1" allow-none="1"> the type of the attribute + filename="gio/gmenumodel.c" + line="707">the type of the attribute optional="1" allow-none="1"> the attribute value + filename="gio/gmenumodel.c" + line="708">the attribute value @@ -76243,7 +79780,7 @@ attribute exists at all). c:type="GMenuAttributeIterPrivate" disguised="1" opaque="1"> - + glib:type-name="GMenuItem" glib:get-type="g_menu_item_get_type"> #GMenuItem is an opaque structure type. You must access it using the + filename="gio/gmenu.c" + line="46">#GMenuItem is an opaque structure type. You must access it using the functions below. Creates a new #GMenuItem. + filename="gio/gmenu.c" + line="1105">Creates a new #GMenuItem. If @label is non-%NULL it is used to set the "label" attribute of the new item. @@ -76267,11 +79804,11 @@ new item. If @detailed_action is non-%NULL it is used to set the "action" and possibly the "target" attribute of the new item. See g_menu_item_set_detailed_action() for more information. - + a new #GMenuItem + filename="gio/gmenu.c" + line="1119">a new #GMenuItem @@ -76280,8 +79817,8 @@ g_menu_item_set_detailed_action() for more information. nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="1107">the section label, or %NULL nullable="1" allow-none="1"> the detailed action string, or %NULL + filename="gio/gmenu.c" + line="1108">the detailed action string, or %NULL @@ -76299,30 +79836,30 @@ g_menu_item_set_detailed_action() for more information. c:identifier="g_menu_item_new_from_model" version="2.34"> Creates a #GMenuItem as an exact copy of an existing menu item in a + filename="gio/gmenu.c" + line="1256">Creates a #GMenuItem as an exact copy of an existing menu item in a #GMenuModel. @item_index must be valid (ie: be sure to call g_menu_model_get_n_items() first). - + a new #GMenuItem. + filename="gio/gmenu.c" + line="1267">a new #GMenuItem. a #GMenuModel + filename="gio/gmenu.c" + line="1258">a #GMenuModel the index of an item in @model + filename="gio/gmenu.c" + line="1259">the index of an item in @model @@ -76331,8 +79868,8 @@ g_menu_model_get_n_items() first). c:identifier="g_menu_item_new_section" version="2.32"> Creates a new #GMenuItem representing a section. + filename="gio/gmenu.c" + line="1170">Creates a new #GMenuItem representing a section. This is a convenience API around g_menu_item_new() and g_menu_item_set_section(). @@ -76342,7 +79879,7 @@ exactly as it sounds: the items from @section become a direct part of the menu that @menu_item is added to. Visual separation is typically displayed between two non-empty -sections. If @label is non-%NULL then it will be encorporated into +sections. If @label is non-%NULL then it will be incorporated into this visual indication. This allows for labeled subsections of a menu. @@ -76392,11 +79929,11 @@ purpose of understanding what is really going on). </item> </menu> ]| - + a new #GMenuItem + filename="gio/gmenu.c" + line="1236">a new #GMenuItem @@ -76405,14 +79942,14 @@ purpose of understanding what is really going on). nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="1172">the section label, or %NULL a #GMenuModel with the items of the section + filename="gio/gmenu.c" + line="1173">a #GMenuModel with the items of the section @@ -76421,16 +79958,16 @@ purpose of understanding what is really going on). c:identifier="g_menu_item_new_submenu" version="2.32"> Creates a new #GMenuItem representing a submenu. + filename="gio/gmenu.c" + line="1140">Creates a new #GMenuItem representing a submenu. This is a convenience API around g_menu_item_new() and g_menu_item_set_submenu(). - + a new #GMenuItem + filename="gio/gmenu.c" + line="1150">a new #GMenuItem @@ -76439,14 +79976,14 @@ g_menu_item_set_submenu(). nullable="1" allow-none="1"> the section label, or %NULL + filename="gio/gmenu.c" + line="1142">the section label, or %NULL a #GMenuModel with the items of the submenu + filename="gio/gmenu.c" + line="1143">a #GMenuModel with the items of the submenu @@ -76456,8 +79993,8 @@ g_menu_item_set_submenu(). version="2.34" introspectable="0"> Queries the named @attribute on @menu_item. + filename="gio/gmenu.c" + line="803">Queries the named @attribute on @menu_item. If the attribute exists and matches the #GVariantType corresponding to @format_string then @format_string is used to deconstruct the @@ -76466,37 +80003,37 @@ value into the positional parameters and %TRUE is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and %FALSE is returned. - + %TRUE if the named attribute was found with the expected + filename="gio/gmenu.c" + line="820">%TRUE if the named attribute was found with the expected type a #GMenuItem + filename="gio/gmenu.c" + line="805">a #GMenuItem the attribute name to query + filename="gio/gmenu.c" + line="806">the attribute name to query a #GVariant format string + filename="gio/gmenu.c" + line="807">a #GVariant format string positional parameters, as per @format_string + filename="gio/gmenu.c" + line="808">positional parameters, as per @format_string @@ -76505,30 +80042,30 @@ returned. c:identifier="g_menu_item_get_attribute_value" version="2.34"> Queries the named @attribute on @menu_item. + filename="gio/gmenu.c" + line="764">Queries the named @attribute on @menu_item. If @expected_type is specified and the attribute does not have this type, %NULL is returned. %NULL is also returned if the attribute simply does not exist. - + the attribute value, or %NULL + filename="gio/gmenu.c" + line="776">the attribute value, or %NULL a #GMenuItem + filename="gio/gmenu.c" + line="766">a #GMenuItem the attribute name to query + filename="gio/gmenu.c" + line="767">the attribute name to query nullable="1" allow-none="1"> the expected type of the attribute + filename="gio/gmenu.c" + line="768">the expected type of the attribute @@ -76546,26 +80083,26 @@ simply does not exist. c:identifier="g_menu_item_get_link" version="2.34"> Queries the named @link on @menu_item. - + filename="gio/gmenu.c" + line="853">Queries the named @link on @menu_item. + the link, or %NULL + filename="gio/gmenu.c" + line="860">the link, or %NULL a #GMenuItem + filename="gio/gmenu.c" + line="855">a #GMenuItem the link name to query + filename="gio/gmenu.c" + line="856">the link name to query @@ -76575,8 +80112,8 @@ simply does not exist. version="2.32" introspectable="0"> Sets or unsets the "action" and "target" attributes of @menu_item. + filename="gio/gmenu.c" + line="1018">Sets or unsets the "action" and "target" attributes of @menu_item. If @action is %NULL then both the "action" and "target" attributes are unset (and @format_string is ignored along with the positional @@ -76595,15 +80132,15 @@ works with string-typed targets. See also g_menu_item_set_action_and_target_value() for a description of the semantics of the action and target attributes. - + a #GMenuItem + filename="gio/gmenu.c" + line="1020">a #GMenuItem nullable="1" allow-none="1"> the name of the action for this item + filename="gio/gmenu.c" + line="1021">the name of the action for this item nullable="1" allow-none="1"> a GVariant format string + filename="gio/gmenu.c" + line="1022">a GVariant format string positional parameters, as per @format_string + filename="gio/gmenu.c" + line="1023">positional parameters, as per @format_string @@ -76636,8 +80173,8 @@ description of the semantics of the action and target attributes. c:identifier="g_menu_item_set_action_and_target_value" version="2.32"> Sets or unsets the "action" and "target" attributes of @menu_item. + filename="gio/gmenu.c" + line="952">Sets or unsets the "action" and "target" attributes of @menu_item. If @action is %NULL then both the "action" and "target" attributes are unset (and @target_value is ignored). @@ -76673,15 +80210,15 @@ state is equal to the value of the @target property. See g_menu_item_set_action_and_target() or g_menu_item_set_detailed_action() for two equivalent calls that are probably more convenient for most uses. - + a #GMenuItem + filename="gio/gmenu.c" + line="954">a #GMenuItem nullable="1" allow-none="1"> the name of the action for this item + filename="gio/gmenu.c" + line="955">the name of the action for this item nullable="1" allow-none="1"> a #GVariant to use as the action target + filename="gio/gmenu.c" + line="956">a #GVariant to use as the action target @@ -76709,8 +80246,8 @@ probably more convenient for most uses. version="2.32" introspectable="0"> Sets or unsets an attribute on @menu_item. + filename="gio/gmenu.c" + line="679">Sets or unsets an attribute on @menu_item. The attribute to set or unset is specified by @attribute. This can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, @@ -76727,21 +80264,21 @@ and the named attribute is unset. See also g_menu_item_set_attribute_value() for an equivalent call that directly accepts a #GVariant. - + a #GMenuItem + filename="gio/gmenu.c" + line="681">a #GMenuItem the attribute to set + filename="gio/gmenu.c" + line="682">the attribute to set nullable="1" allow-none="1"> a #GVariant format string, or %NULL + filename="gio/gmenu.c" + line="683">a #GVariant format string, or %NULL positional parameters, as per @format_string + filename="gio/gmenu.c" + line="684">positional parameters, as per @format_string @@ -76765,8 +80302,8 @@ that directly accepts a #GVariant. c:identifier="g_menu_item_set_attribute_value" version="2.32"> Sets or unsets an attribute on @menu_item. + filename="gio/gmenu.c" + line="634">Sets or unsets an attribute on @menu_item. The attribute to set or unset is specified by @attribute. This can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, @@ -76785,21 +80322,21 @@ the @value #GVariant is floating, it is consumed. See also g_menu_item_set_attribute() for a more convenient way to do the same. - + a #GMenuItem + filename="gio/gmenu.c" + line="636">a #GMenuItem the attribute to set + filename="gio/gmenu.c" + line="637">the attribute to set nullable="1" allow-none="1"> a #GVariant to use as the value, or %NULL + filename="gio/gmenu.c" + line="638">a #GVariant to use as the value, or %NULL @@ -76817,8 +80354,8 @@ the same. c:identifier="g_menu_item_set_detailed_action" version="2.32"> Sets the "action" and possibly the "target" attribute of @menu_item. + filename="gio/gmenu.c" + line="1069">Sets the "action" and possibly the "target" attribute of @menu_item. The format of @detailed_action is the same format parsed by g_action_parse_detailed_name(). @@ -76829,21 +80366,21 @@ slightly less convenient) alternatives. See also g_menu_item_set_action_and_target_value() for a description of the semantics of the action and target attributes. - + a #GMenuItem + filename="gio/gmenu.c" + line="1071">a #GMenuItem the "detailed" action string + filename="gio/gmenu.c" + line="1072">the "detailed" action string @@ -76852,8 +80389,8 @@ the semantics of the action and target attributes. c:identifier="g_menu_item_set_icon" version="2.38"> Sets (or unsets) the icon on @menu_item. + filename="gio/gmenu.c" + line="1343">Sets (or unsets) the icon on @menu_item. This call is the same as calling g_icon_serialize() and using the result as the value to g_menu_item_set_attribute_value() for @@ -76865,21 +80402,21 @@ menu items corresponding to verbs (eg: stock icons for 'Save' or 'Quit'). If @icon is %NULL then the icon is unset. - + a #GMenuItem + filename="gio/gmenu.c" + line="1345">a #GMenuItem a #GIcon, or %NULL + filename="gio/gmenu.c" + line="1346">a #GIcon, or %NULL @@ -76888,20 +80425,20 @@ If @icon is %NULL then the icon is unset. c:identifier="g_menu_item_set_label" version="2.32"> Sets or unsets the "label" attribute of @menu_item. + filename="gio/gmenu.c" + line="882">Sets or unsets the "label" attribute of @menu_item. If @label is non-%NULL it is used as the label for the menu item. If it is %NULL then the label attribute is unset. - + a #GMenuItem + filename="gio/gmenu.c" + line="884">a #GMenuItem nullable="1" allow-none="1"> the label to set, or %NULL to unset + filename="gio/gmenu.c" + line="885">the label to set, or %NULL to unset @@ -76919,8 +80456,8 @@ it is %NULL then the label attribute is unset. c:identifier="g_menu_item_set_link" version="2.32"> Creates a link from @menu_item to @model if non-%NULL, or unsets it. + filename="gio/gmenu.c" + line="728">Creates a link from @menu_item to @model if non-%NULL, or unsets it. Links are used to establish a relationship between a particular menu item and another menu. For example, %G_MENU_LINK_SUBMENU is used to @@ -76930,21 +80467,21 @@ is no guarantee that clients will be able to make sense of them. Link types are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. - + a #GMenuItem + filename="gio/gmenu.c" + line="730">a #GMenuItem type of link to establish or unset + filename="gio/gmenu.c" + line="731">type of link to establish or unset nullable="1" allow-none="1"> the #GMenuModel to link to (or %NULL to unset) + filename="gio/gmenu.c" + line="732">the #GMenuModel to link to (or %NULL to unset) @@ -76962,23 +80499,23 @@ must not end with a '-', and must not contain consecutive dashes. c:identifier="g_menu_item_set_section" version="2.32"> Sets or unsets the "section" link of @menu_item to @section. + filename="gio/gmenu.c" + line="930">Sets or unsets the "section" link of @menu_item to @section. The effect of having one menu appear as a section of another is exactly as it sounds: the items from @section become a direct part of the menu that @menu_item is added to. See g_menu_item_new_section() for more information about what it means for a menu item to be a section. - + a #GMenuItem + filename="gio/gmenu.c" + line="932">a #GMenuItem nullable="1" allow-none="1"> a #GMenuModel, or %NULL + filename="gio/gmenu.c" + line="933">a #GMenuModel, or %NULL @@ -76996,23 +80533,23 @@ section. c:identifier="g_menu_item_set_submenu" version="2.32"> Sets or unsets the "submenu" link of @menu_item to @submenu. + filename="gio/gmenu.c" + line="908">Sets or unsets the "submenu" link of @menu_item to @submenu. If @submenu is non-%NULL, it is linked to. If it is %NULL then the link is unset. The effect of having one menu appear as a submenu of another is exactly as it sounds. - + a #GMenuItem + filename="gio/gmenu.c" + line="910">a #GMenuItem nullable="1" allow-none="1"> a #GMenuModel, or %NULL + filename="gio/gmenu.c" + line="911">a #GMenuModel, or %NULL @@ -77037,14 +80574,14 @@ exactly as it sounds. glib:get-type="g_menu_link_iter_get_type" glib:type-struct="MenuLinkIterClass"> #GMenuLinkIter is an opaque structure type. You must access it using + filename="gio/gmenumodel.c" + line="164">#GMenuLinkIter is an opaque structure type. You must access it using the functions below. - + This function combines g_menu_link_iter_next() with + filename="gio/gmenumodel.c" + line="860">This function combines g_menu_link_iter_next() with g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). First the iterator is advanced to the next (possibly first) link. @@ -77058,18 +80595,18 @@ same values again. The value returned in @out_link remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_object_unref() when it is no longer in use. - + %TRUE on success, or %FALSE if there is no additional link + filename="gio/gmenumodel.c" + line="881">%TRUE on success, or %FALSE if there is no additional link a #GMenuLinkIter + filename="gio/gmenumodel.c" + line="862">a #GMenuLinkIter optional="1" allow-none="1"> the name of the link + filename="gio/gmenumodel.c" + line="863">the name of the link optional="1" allow-none="1"> the linked #GMenuModel + filename="gio/gmenumodel.c" + line="864">the linked #GMenuModel @@ -77100,22 +80637,22 @@ be unreffed using g_object_unref() when it is no longer in use. c:identifier="g_menu_link_iter_get_name" version="2.32"> Gets the name of the link at the current iterator position. + filename="gio/gmenumodel.c" + line="939">Gets the name of the link at the current iterator position. The iterator is not advanced. - + the type of the link + filename="gio/gmenumodel.c" + line="947">the type of the link a #GMenuLinkIter + filename="gio/gmenumodel.c" + line="941">a #GMenuLinkIter @@ -77124,8 +80661,8 @@ The iterator is not advanced. c:identifier="g_menu_link_iter_get_next" version="2.32"> This function combines g_menu_link_iter_next() with + filename="gio/gmenumodel.c" + line="860">This function combines g_menu_link_iter_next() with g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). First the iterator is advanced to the next (possibly first) link. @@ -77139,18 +80676,18 @@ same values again. The value returned in @out_link remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_object_unref() when it is no longer in use. - + %TRUE on success, or %FALSE if there is no additional link + filename="gio/gmenumodel.c" + line="881">%TRUE on success, or %FALSE if there is no additional link a #GMenuLinkIter + filename="gio/gmenumodel.c" + line="862">a #GMenuLinkIter optional="1" allow-none="1"> the name of the link + filename="gio/gmenumodel.c" + line="863">the name of the link optional="1" allow-none="1"> the linked #GMenuModel + filename="gio/gmenumodel.c" + line="864">the linked #GMenuModel @@ -77181,30 +80718,30 @@ be unreffed using g_object_unref() when it is no longer in use. c:identifier="g_menu_link_iter_get_value" version="2.32"> Gets the linked #GMenuModel at the current iterator position. + filename="gio/gmenumodel.c" + line="959">Gets the linked #GMenuModel at the current iterator position. The iterator is not advanced. - + the #GMenuModel that is linked to + filename="gio/gmenumodel.c" + line="967">the #GMenuModel that is linked to a #GMenuLinkIter + filename="gio/gmenumodel.c" + line="961">a #GMenuLinkIter Attempts to advance the iterator to the next (possibly first) + filename="gio/gmenumodel.c" + line="916">Attempts to advance the iterator to the next (possibly first) link. %TRUE is returned on success, or %FALSE if there are no more links. @@ -77212,18 +80749,18 @@ link. You must call this function when you first acquire the iterator to advance it to the first link (and determine if the first link exists at all). - + %TRUE on success, or %FALSE when there are no more links + filename="gio/gmenumodel.c" + line="929">%TRUE on success, or %FALSE when there are no more links a #GMenuLinkIter + filename="gio/gmenumodel.c" + line="918">a #GMenuLinkIter @@ -77238,24 +80775,24 @@ at all). - + - + %TRUE on success, or %FALSE if there is no additional link + filename="gio/gmenumodel.c" + line="881">%TRUE on success, or %FALSE if there is no additional link a #GMenuLinkIter + filename="gio/gmenumodel.c" + line="862">a #GMenuLinkIter optional="1" allow-none="1"> the name of the link + filename="gio/gmenumodel.c" + line="863">the name of the link optional="1" allow-none="1"> the linked #GMenuModel + filename="gio/gmenumodel.c" + line="864">the linked #GMenuModel @@ -77288,7 +80825,7 @@ at all). c:type="GMenuLinkIterPrivate" disguised="1" opaque="1"> - + glib:get-type="g_menu_model_get_type" glib:type-struct="MenuModelClass"> #GMenuModel represents the contents of a menu -- an ordered list of + filename="gio/gmenumodel.c" + line="29">`GMenuModel` represents the contents of a menu — an ordered list of menu items. The items are associated with actions, which can be activated through them. Items can be grouped in sections, and may have submenus associated with them. Both items and sections usually @@ -77309,20 +80846,22 @@ have some representation data, such as labels or icons. The type of the associated action (ie whether it is stateful, and what kind of state it has) can influence the representation of the item. -The conceptual model of menus in #GMenuModel is hierarchical: -sections and submenus are again represented by #GMenuModels. +The conceptual model of menus in `GMenuModel` is hierarchical: +sections and submenus are again represented by `GMenuModel`s. Menus themselves do not define their own roles. Rather, the role -of a particular #GMenuModel is defined by the item that references -it (or, in the case of the 'root' menu, is defined by the context +of a particular `GMenuModel` is defined by the item that references +it (or, in the case of the ‘root’ menu, is defined by the context in which it is used). As an example, consider the visible portions of this menu: -## An example menu # {#menu-example} +## An example menu ![](menu-example.png) -There are 8 "menus" visible in the screenshot: one menubar, two +While this kind of deeply nested menu is no longer considered good UI +practice, it serves as a good example of the concepts in `GMenuModel`. +There are 8 ‘menus’ visible in the screenshot: one menubar, two submenus and 5 sections: - the toplevel menubar (containing 4 items) @@ -77334,17 +80873,20 @@ submenus and 5 sections: - the Sources section (containing 2 items) - the Markup section (containing 2 items) -The [example][menu-model] illustrates the conceptual connection between +The [example](#a-menu-example) illustrates the conceptual connection between these 8 menus. Each large block in the figure represents a menu and the smaller blocks within the large block represent items in that menu. Some items contain references to other menus. -## A menu example # {#menu-model} +## A menu example -![](menu-model.png) +<picture> + <source srcset="menu-model-dark.svg" media="(prefers-color-scheme: dark)"> + <img src="menu-model-light.svg" alt="menu model"> +</picture> -Notice that the separators visible in the [example][menu-example] -appear nowhere in the [menu model][menu-model]. This is because +Notice that the separators visible in the [example](#an-example-menu) +appear nowhere in the [menu model](#a-menu-example). This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, @@ -77353,32 +80895,33 @@ a display system may show a section header instead of a separator. The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, -dash boards, etc. To support such uses, it is necessary to 'export' +dash boards, etc. To support such uses, it is necessary to ‘export’ information about actions and their representation in menus, which -is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] -and the [GMenuModel exporter][gio-GMenuModel-exporter] do for -#GActionGroup and #GMenuModel. The client-side counterparts to -make use of the exported information are #GDBusActionGroup and -#GDBusMenuModel. - -The API of #GMenuModel is very generic, with iterators for the -attributes and links of an item, see g_menu_model_iterate_item_attributes() -and g_menu_model_iterate_item_links(). The 'standard' attributes and -link types have predefined names: %G_MENU_ATTRIBUTE_LABEL, -%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION -and %G_MENU_LINK_SUBMENU. - -Items in a #GMenuModel represent active controls if they refer to +is exactly what the action group exporter and the menu model exporter do for +[iface@Gio.ActionGroup] and [class@Gio.MenuModel]. The client-side +counterparts to make use of the exported information are +[class@Gio.DBusActionGroup] and [class@Gio.DBusMenuModel]. + +The API of `GMenuModel` is very generic, with iterators for the +attributes and links of an item, see +[method@Gio.MenuModel.iterate_item_attributes] and +[method@Gio.MenuModel.iterate_item_links]. The ‘standard’ attributes and +link types have predefined names: `G_MENU_ATTRIBUTE_LABEL`, +`G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, `G_MENU_LINK_SECTION` +and `G_MENU_LINK_SUBMENU`. + +Items in a `GMenuModel` represent active controls if they refer to an action that can get activated when the user interacts with the -menu item. The reference to the action is encoded by the string id -in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely +menu item. The reference to the action is encoded by the string ID +in the `G_MENU_ATTRIBUTE_ACTION` attribute. An action ID uniquely identifies an action in an action group. Which action group(s) provide actions depends on the context in which the menu model is used. E.g. when the model is exported as the application menu of a -#GtkApplication, actions can be application-wide or window-specific -(and thus come from two different action groups). By convention, the -application-wide actions have names that start with "app.", while the -names of window-specific actions start with "win.". +[`GtkApplication`](https://docs.gtk.org/gtk4/class.Application.html), +actions can be application-wide or window-specific (and thus come from +two different action groups). By convention, the application-wide actions +have names that start with `app.`, while the names of window-specific +actions start with `win.`. While a wide variety of stateful actions is possible, the following is the minimum that is expected to be supported by all users of exported @@ -77395,12 +80938,12 @@ Selecting such a menu item will activate the action (with no parameter). ## Boolean State -An action with a boolean state will most typically be used with a "toggle" -or "switch" menu item. The state can be set directly, but activating the +An action with a boolean state will most typically be used with a ‘toggle’ +or ‘switch’ menu item. The state can be set directly, but activating the action (with no parameter) results in the state being toggled. Selecting a toggle menu item will activate the action. The menu item should -be rendered as "checked" when the state is true. +be rendered as ‘checked’ when the state is true. ## String Parameter and State @@ -77412,15 +80955,15 @@ equivalent to setting that parameter as the state. Radio menu items, in addition to being associated with the action, will have a target value. Selecting that menu item will result in activation of the action with the target value as the parameter. The menu item should -be rendered as "selected" when the state of the action is equal to the +be rendered as ‘selected’ when the state of the action is equal to the target value of the menu item. - + Queries the item at position @item_index in @model for the attribute + filename="gio/gmenumodel.c" + line="521">Queries the item at position @item_index in @model for the attribute specified by @attribute. If @expected_type is non-%NULL then it specifies the expected type of @@ -77431,30 +80974,30 @@ expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then %NULL is returned. - + the value of the attribute + filename="gio/gmenumodel.c" + line="541">the value of the attribute a #GMenuModel + filename="gio/gmenumodel.c" + line="523">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="524">the index of the item the attribute to query + filename="gio/gmenumodel.c" + line="525">the attribute to query nullable="1" allow-none="1"> the expected type of the attribute, or + filename="gio/gmenumodel.c" + line="526">the expected type of the attribute, or %NULL @@ -77471,22 +81014,22 @@ then %NULL is returned. Gets all the attributes associated with the item in the menu model. - + the #GMenuModel to query The #GMenuItem to query @@ -77495,7 +81038,7 @@ then %NULL is returned. caller-allocates="0" transfer-ownership="full"> Attributes on the item @@ -77508,58 +81051,58 @@ then %NULL is returned. invoker="get_item_link" version="2.32"> Queries the item at position @item_index in @model for the link + filename="gio/gmenumodel.c" + line="636">Queries the item at position @item_index in @model for the link specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. - + the linked #GMenuModel, or %NULL + filename="gio/gmenumodel.c" + line="648">the linked #GMenuModel, or %NULL a #GMenuModel + filename="gio/gmenumodel.c" + line="638">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="639">the index of the item the link to query + filename="gio/gmenumodel.c" + line="640">the link to query Gets all the links associated with the item in the menu model. - + the #GMenuModel to query The #GMenuItem to query @@ -77568,7 +81111,7 @@ does not exist, %NULL is returned. caller-allocates="0" transfer-ownership="full"> Links from the item @@ -77579,44 +81122,44 @@ does not exist, %NULL is returned. Query the number of items in @model. - + filename="gio/gmenumodel.c" + line="482">Query the number of items in @model. + the number of items + filename="gio/gmenumodel.c" + line="488">the number of items a #GMenuModel + filename="gio/gmenumodel.c" + line="484">a #GMenuModel Queries if @model is mutable. + filename="gio/gmenumodel.c" + line="461">Queries if @model is mutable. An immutable #GMenuModel will never emit the #GMenuModel::items-changed signal. Consumers of the model may make optimisations accordingly. - + %TRUE if the model is mutable (ie: "items-changed" may be + filename="gio/gmenumodel.c" + line="470">%TRUE if the model is mutable (ie: "items-changed" may be emitted). a #GMenuModel + filename="gio/gmenumodel.c" + line="463">a #GMenuModel @@ -77625,29 +81168,29 @@ signal. Consumers of the model may make optimisations accordingly. invoker="iterate_item_attributes" version="2.32"> Creates a #GMenuAttributeIter to iterate over the attributes of + filename="gio/gmenumodel.c" + line="499">Creates a #GMenuAttributeIter to iterate over the attributes of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. - + a new #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="509">a new #GMenuAttributeIter a #GMenuModel + filename="gio/gmenumodel.c" + line="501">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="502">the index of the item @@ -77656,29 +81199,29 @@ You must free the iterator with g_object_unref() when you are done. invoker="iterate_item_links" version="2.32"> Creates a #GMenuLinkIter to iterate over the links of the item at + filename="gio/gmenumodel.c" + line="614">Creates a #GMenuLinkIter to iterate over the links of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. - + a new #GMenuLinkIter + filename="gio/gmenumodel.c" + line="624">a new #GMenuLinkIter a #GMenuModel + filename="gio/gmenumodel.c" + line="616">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="617">the index of the item @@ -77688,8 +81231,8 @@ You must free the iterator with g_object_unref() when you are done. version="2.32" introspectable="0"> Queries item at position @item_index in @model for the attribute + filename="gio/gmenumodel.c" + line="555">Queries item at position @item_index in @model for the attribute specified by @attribute. If the attribute exists and matches the #GVariantType corresponding @@ -77705,43 +81248,43 @@ g_variant_get(), followed by a g_variant_unref(). As such, @format_string must make a complete copy of the data (since the #GVariant may go away after the call to g_variant_unref()). In particular, no '&' characters are allowed in @format_string. - + %TRUE if the named attribute was found with the expected + filename="gio/gmenumodel.c" + line="580">%TRUE if the named attribute was found with the expected type a #GMenuModel + filename="gio/gmenumodel.c" + line="557">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="558">the index of the item the attribute to query + filename="gio/gmenumodel.c" + line="559">the attribute to query a #GVariant format string + filename="gio/gmenumodel.c" + line="560">a #GVariant format string positional parameters, as per @format_string + filename="gio/gmenumodel.c" + line="561">positional parameters, as per @format_string @@ -77750,8 +81293,8 @@ particular, no '&' characters are allowed in @format_string. c:identifier="g_menu_model_get_item_attribute_value" version="2.32"> Queries the item at position @item_index in @model for the attribute + filename="gio/gmenumodel.c" + line="521">Queries the item at position @item_index in @model for the attribute specified by @attribute. If @expected_type is non-%NULL then it specifies the expected type of @@ -77762,30 +81305,30 @@ expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then %NULL is returned. - + the value of the attribute + filename="gio/gmenumodel.c" + line="541">the value of the attribute a #GMenuModel + filename="gio/gmenumodel.c" + line="523">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="524">the index of the item the attribute to query + filename="gio/gmenumodel.c" + line="525">the attribute to query nullable="1" allow-none="1"> the expected type of the attribute, or + filename="gio/gmenumodel.c" + line="526">the expected type of the attribute, or %NULL @@ -77804,36 +81347,36 @@ then %NULL is returned. c:identifier="g_menu_model_get_item_link" version="2.32"> Queries the item at position @item_index in @model for the link + filename="gio/gmenumodel.c" + line="636">Queries the item at position @item_index in @model for the link specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. - + the linked #GMenuModel, or %NULL + filename="gio/gmenumodel.c" + line="648">the linked #GMenuModel, or %NULL a #GMenuModel + filename="gio/gmenumodel.c" + line="638">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="639">the index of the item the link to query + filename="gio/gmenumodel.c" + line="640">the link to query @@ -77842,20 +81385,20 @@ does not exist, %NULL is returned. c:identifier="g_menu_model_get_n_items" version="2.32"> Query the number of items in @model. - + filename="gio/gmenumodel.c" + line="482">Query the number of items in @model. + the number of items + filename="gio/gmenumodel.c" + line="488">the number of items a #GMenuModel + filename="gio/gmenumodel.c" + line="484">a #GMenuModel @@ -77864,24 +81407,24 @@ does not exist, %NULL is returned. c:identifier="g_menu_model_is_mutable" version="2.32"> Queries if @model is mutable. + filename="gio/gmenumodel.c" + line="461">Queries if @model is mutable. An immutable #GMenuModel will never emit the #GMenuModel::items-changed signal. Consumers of the model may make optimisations accordingly. - + %TRUE if the model is mutable (ie: "items-changed" may be + filename="gio/gmenumodel.c" + line="470">%TRUE if the model is mutable (ie: "items-changed" may be emitted). a #GMenuModel + filename="gio/gmenumodel.c" + line="463">a #GMenuModel @@ -77890,8 +81433,8 @@ signal. Consumers of the model may make optimisations accordingly. c:identifier="g_menu_model_items_changed" version="2.32"> Requests emission of the #GMenuModel::items-changed signal on @model. + filename="gio/gmenumodel.c" + line="661">Requests emission of the #GMenuModel::items-changed signal on @model. This function should never be called except by #GMenuModel subclasses. Any other calls to this function will very likely lead @@ -77906,33 +81449,33 @@ The implementation must dispatch this call directly from a mainloop entry and not in response to calls -- particularly those from the #GMenuModel API. Said another way: the menu must not change while user code is running without returning to the mainloop. - + a #GMenuModel + filename="gio/gmenumodel.c" + line="663">a #GMenuModel the position of the change + filename="gio/gmenumodel.c" + line="664">the position of the change the number of items removed + filename="gio/gmenumodel.c" + line="665">the number of items removed the number of items added + filename="gio/gmenumodel.c" + line="666">the number of items added @@ -77941,29 +81484,29 @@ user code is running without returning to the mainloop. c:identifier="g_menu_model_iterate_item_attributes" version="2.32"> Creates a #GMenuAttributeIter to iterate over the attributes of + filename="gio/gmenumodel.c" + line="499">Creates a #GMenuAttributeIter to iterate over the attributes of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. - + a new #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="509">a new #GMenuAttributeIter a #GMenuModel + filename="gio/gmenumodel.c" + line="501">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="502">the index of the item @@ -77972,29 +81515,29 @@ You must free the iterator with g_object_unref() when you are done. c:identifier="g_menu_model_iterate_item_links" version="2.32"> Creates a #GMenuLinkIter to iterate over the links of the item at + filename="gio/gmenumodel.c" + line="614">Creates a #GMenuLinkIter to iterate over the links of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. - + a new #GMenuLinkIter + filename="gio/gmenumodel.c" + line="624">a new #GMenuLinkIter a #GMenuModel + filename="gio/gmenumodel.c" + line="616">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="617">the index of the item @@ -78007,8 +81550,8 @@ You must free the iterator with g_object_unref() when you are done. Emitted when a change has occurred to the menu. + filename="gio/gmenumodel.c" + line="422">Emitted when a change has occurred to the menu. The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added @@ -78034,20 +81577,20 @@ reported. The signal is emitted after the modification. the position of the change + filename="gio/gmenumodel.c" + line="425">the position of the change the number of items removed + filename="gio/gmenumodel.c" + line="426">the number of items removed the number of items added + filename="gio/gmenumodel.c" + line="427">the number of items added @@ -78056,25 +81599,25 @@ reported. The signal is emitted after the modification. - + - + %TRUE if the model is mutable (ie: "items-changed" may be + filename="gio/gmenumodel.c" + line="470">%TRUE if the model is mutable (ie: "items-changed" may be emitted). a #GMenuModel + filename="gio/gmenumodel.c" + line="463">a #GMenuModel @@ -78082,18 +81625,18 @@ reported. The signal is emitted after the modification. - + the number of items + filename="gio/gmenumodel.c" + line="488">the number of items a #GMenuModel + filename="gio/gmenumodel.c" + line="484">a #GMenuModel @@ -78101,20 +81644,20 @@ reported. The signal is emitted after the modification. - + the #GMenuModel to query The #GMenuItem to query @@ -78123,7 +81666,7 @@ reported. The signal is emitted after the modification. caller-allocates="0" transfer-ownership="full"> Attributes on the item @@ -78135,24 +81678,24 @@ reported. The signal is emitted after the modification. - + a new #GMenuAttributeIter + filename="gio/gmenumodel.c" + line="509">a new #GMenuAttributeIter a #GMenuModel + filename="gio/gmenumodel.c" + line="501">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="502">the index of the item @@ -78160,30 +81703,30 @@ reported. The signal is emitted after the modification. - + the value of the attribute + filename="gio/gmenumodel.c" + line="541">the value of the attribute a #GMenuModel + filename="gio/gmenumodel.c" + line="523">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="524">the index of the item the attribute to query + filename="gio/gmenumodel.c" + line="525">the attribute to query nullable="1" allow-none="1"> the expected type of the attribute, or + filename="gio/gmenumodel.c" + line="526">the expected type of the attribute, or %NULL @@ -78201,20 +81744,20 @@ reported. The signal is emitted after the modification. - + the #GMenuModel to query The #GMenuItem to query @@ -78223,7 +81766,7 @@ reported. The signal is emitted after the modification. caller-allocates="0" transfer-ownership="full"> Links from the item @@ -78235,24 +81778,24 @@ reported. The signal is emitted after the modification. - + a new #GMenuLinkIter + filename="gio/gmenumodel.c" + line="624">a new #GMenuLinkIter a #GMenuModel + filename="gio/gmenumodel.c" + line="616">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="617">the index of the item @@ -78260,30 +81803,30 @@ reported. The signal is emitted after the modification. - + the linked #GMenuModel, or %NULL + filename="gio/gmenumodel.c" + line="648">the linked #GMenuModel, or %NULL a #GMenuModel + filename="gio/gmenumodel.c" + line="638">a #GMenuModel the index of the item + filename="gio/gmenumodel.c" + line="639">the index of the item the link to query + filename="gio/gmenumodel.c" + line="640">the link to query @@ -78294,7 +81837,7 @@ reported. The signal is emitted after the modification. c:type="GMenuModelPrivate" disguised="1" opaque="1"> - + glib:get-type="g_mount_get_type" glib:type-struct="MountIface"> The #GMount interface represents user-visible mounts. Note, when -porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. - -#GMount is a "mounted" filesystem that you can access. Mounted is in -quotes because it's not the same as a unix mount, it might be a gvfs -mount, but you can still access the files on it if you use GIO. Might or -might not be related to a volume object. - -Unmounting a #GMount instance is an asynchronous operation. For -more information about asynchronous operations, see #GAsyncResult -and #GTask. To unmount a #GMount instance, first call -g_mount_unmount_with_operation() with (at least) the #GMount instance and a -#GAsyncReadyCallback. The callback will be fired when the -operation has resolved (either with success or failure), and a -#GAsyncResult structure will be passed to the callback. That -callback should then call g_mount_unmount_with_operation_finish() with the #GMount -and the #GAsyncResult data to see if the operation was completed -successfully. If an @error is present when g_mount_unmount_with_operation_finish() -is called, then it will be filled with any error information. - + filename="gio/gmount.c" + line="39">The `GMount` interface represents a user-visible mount, such as a mounted +file system. + +`GMount` is a ‘mounted’ filesystem that you can access. Mounted is in +quotes because it’s not the same as a UNIX mount, it might be a GVFS +mount, but you can still access the files on it if you use GIO. + +A `GMount` might be associated with a [iface@Gio.Volume] (such as a USB flash +drive) which hosts it. + +Unmounting a `GMount` instance is an asynchronous operation. For +more information about asynchronous operations, see [iface@Gio.AsyncResult] +and [class@Gio.Task]. To unmount a `GMount` instance, first call +[method@Gio.Mount.unmount_with_operation] with (at least) the `GMount` +instance and a [type@Gio.AsyncReadyCallback]. The callback will be fired +when the operation has resolved (either with success or failure), and a +[iface@Gio.AsyncResult] structure will be passed to the callback. That +callback should then call [method@Gio.Mount.unmount_with_operation_finish] +with the `GMount` and the [iface@Gio.AsyncResult] data to see if the +operation was completed successfully. If an `error` is present when +[method@Gio.Mount.unmount_with_operation_finish] is called, then it will be +filled with any error information. + +Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), `GMount` is the +moral equivalent of `GnomeVFSVolume`. + Checks if @mount can be ejected. - + filename="gio/gmount.c" + line="349">Checks if @mount can be ejected. + %TRUE if the @mount can be ejected. + filename="gio/gmount.c" + line="355">%TRUE if the @mount can be ejected. a #GMount. + filename="gio/gmount.c" + line="351">a #GMount. Checks if @mount can be unmounted. - + filename="gio/gmount.c" + line="329">Checks if @mount can be unmounted. + %TRUE if the @mount can be unmounted. + filename="gio/gmount.c" + line="335">%TRUE if the @mount can be unmounted. a #GMount. + filename="gio/gmount.c" + line="331">a #GMount. - + Changed signal that is emitted when the mount's state has changed. + @@ -78378,28 +81930,29 @@ is called, then it will be filled with any error information. + deprecated-version="2.22" + glib:finish-func="eject_finish"> Ejects a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="445">Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_eject_with_operation() instead. - + a #GMount. + filename="gio/gmount.c" + line="447">a #GMount. flags affecting the unmount if required for eject + filename="gio/gmount.c" + line="448">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="449">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="450">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="3"> user data passed to @callback. + filename="gio/gmount.c" + line="451">user data passed to @callback. @@ -78440,55 +81993,56 @@ and #GAsyncResult data returned in the @callback. deprecated-version="2.22" throws="1"> Finishes ejecting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="487">Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_eject_with_operation_finish() instead. - + %TRUE if the mount was successfully ejected. %FALSE otherwise. + filename="gio/gmount.c" + line="497">%TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="489">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="490">a #GAsyncResult. + version="2.22" + glib:finish-func="eject_with_operation_finish"> Ejects a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="605">Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. - + a #GMount. + filename="gio/gmount.c" + line="607">a #GMount. flags affecting the unmount if required for eject + filename="gio/gmount.c" + line="608">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="609">a #GMountOperation or %NULL to avoid user interaction. @@ -78506,8 +82060,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="611">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="612">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data passed to @callback. + filename="gio/gmount.c" + line="613">user data passed to @callback. @@ -78538,27 +82092,27 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes ejecting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="653">Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the mount was successfully ejected. %FALSE otherwise. + filename="gio/gmount.c" + line="663">%TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="655">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="656">a #GAsyncResult. @@ -78566,15 +82120,15 @@ and #GAsyncResult data returned in the @callback. Gets the default location of @mount. The default location of the given + filename="gio/gmount.c" + line="148">Gets the default location of @mount. The default location of the given @mount is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume). - + a #GFile. + filename="gio/gmount.c" + line="156">a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -78582,24 +82136,24 @@ the home directory, or the root of the volume). a #GMount. + filename="gio/gmount.c" + line="150">a #GMount. Gets the drive for the @mount. + filename="gio/gmount.c" + line="303">Gets the drive for the @mount. This is a convenience method for getting the #GVolume and then using that object to get the #GDrive. - + a #GDrive or %NULL if @mount is not + filename="gio/gmount.c" + line="312">a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -78608,21 +82162,21 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="305">a #GMount. Gets the icon for @mount. - + filename="gio/gmount.c" + line="201">Gets the icon for @mount. + a #GIcon. + filename="gio/gmount.c" + line="207">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -78630,21 +82184,21 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="203">a #GMount. Gets the name of @mount. - + filename="gio/gmount.c" + line="179">Gets the name of @mount. + the name for the given @mount. + filename="gio/gmount.c" + line="185">the name for the given @mount. The returned string should be freed with g_free() when no longer needed. @@ -78652,21 +82206,21 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="181">a #GMount. Gets the root directory on @mount. - + filename="gio/gmount.c" + line="126">Gets the root directory on @mount. + a #GFile. + filename="gio/gmount.c" + line="132">a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -78674,8 +82228,8 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="128">a #GMount. @@ -78684,20 +82238,20 @@ using that object to get the #GDrive. invoker="get_sort_key" version="2.32"> Gets the sort key for @mount, if any. - + filename="gio/gmount.c" + line="1042">Gets the sort key for @mount, if any. + Sorting key for @mount or %NULL if no such key is available. + filename="gio/gmount.c" + line="1048">Sorting key for @mount or %NULL if no such key is available. A #GMount. + filename="gio/gmount.c" + line="1044">A #GMount. @@ -78706,13 +82260,13 @@ using that object to get the #GDrive. invoker="get_symbolic_icon" version="2.34"> Gets the symbolic icon for @mount. - + filename="gio/gmount.c" + line="224">Gets the symbolic icon for @mount. + a #GIcon. + filename="gio/gmount.c" + line="230">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -78720,24 +82274,24 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="226">a #GMount. Gets the UUID for the @mount. The reference is typically based on + filename="gio/gmount.c" + line="254">Gets the UUID for the @mount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - + the UUID for @mount or %NULL if no UUID + filename="gio/gmount.c" + line="263">the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. @@ -78746,21 +82300,21 @@ available. a #GMount. + filename="gio/gmount.c" + line="256">a #GMount. Gets the volume for the @mount. - + filename="gio/gmount.c" + line="280">Gets the volume for the @mount. + a #GVolume or %NULL if @mount is not + filename="gio/gmount.c" + line="286">a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -78769,18 +82323,20 @@ available. a #GMount. + filename="gio/gmount.c" + line="282">a #GMount. + version="2.18" + glib:finish-func="guess_content_type_finish" + glib:sync-func="guess_content_type_sync"> Tries to guess the type of content stored on @mount. Returns one or + filename="gio/gmount.c" + line="769">Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the @@ -78791,21 +82347,21 @@ This is an asynchronous operation (see g_mount_guess_content_type_sync() for the synchronous version), and is finished by calling g_mount_guess_content_type_finish() with the @mount and #GAsyncResult data returned in the @callback. - + a #GMount + filename="gio/gmount.c" + line="771">a #GMount Whether to force a rescan of the content. + filename="gio/gmount.c" + line="772">Whether to force a rescan of the content. Otherwise a cached result will be used if available @@ -78814,8 +82370,8 @@ is finished by calling g_mount_guess_content_type_finish() with the nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gmount.c" + line="774">optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback + filename="gio/gmount.c" + line="775">a #GAsyncReadyCallback user data passed to @callback + filename="gio/gmount.c" + line="776">user data passed to @callback @@ -78846,17 +82402,17 @@ is finished by calling g_mount_guess_content_type_finish() with the version="2.18" throws="1"> Finishes guessing content types of @mount. If any errors occurred + filename="gio/gmount.c" + line="820">Finishes guessing content types of @mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. In particular, you may get an %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content guessing. - + a %NULL-terminated array of content types or %NULL on error. + filename="gio/gmount.c" + line="833">a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. @@ -78865,14 +82421,14 @@ guessing. a #GMount + filename="gio/gmount.c" + line="822">a #GMount a #GAsyncResult + filename="gio/gmount.c" + line="823">a #GAsyncResult @@ -78880,10 +82436,11 @@ guessing. + throws="1" + glib:async-func="guess_content_type"> Tries to guess the type of content stored on @mount. Returns one or + filename="gio/gmount.c" + line="857">Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the @@ -78892,11 +82449,11 @@ specification for more on x-content types. This is a synchronous operation and as such may block doing IO; see g_mount_guess_content_type() for the asynchronous version. - + a %NULL-terminated array of content types or %NULL on error. + filename="gio/gmount.c" + line="876">a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. @@ -78905,14 +82462,14 @@ see g_mount_guess_content_type() for the asynchronous version. a #GMount + filename="gio/gmount.c" + line="859">a #GMount Whether to force a rescan of the content. + filename="gio/gmount.c" + line="860">Whether to force a rescan of the content. Otherwise a cached result will be used if available @@ -78921,14 +82478,17 @@ see g_mount_guess_content_type() for the asynchronous version. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gmount.c" + line="862">optional #GCancellable object, %NULL to ignore - + The ::pre-unmount signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. + @@ -78938,10 +82498,12 @@ see g_mount_guess_content_type() for the asynchronous version. - + Remounts a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="689">Remounts a mount. This is an asynchronous operation, and is finished by calling g_mount_remount_finish() with the @mount and #GAsyncResults data returned in the @callback. @@ -78950,21 +82512,21 @@ of the volume has been changed, as these may need a remount to take affect. While this is semantically equivalent with unmounting and then remounting not all backends might need to actually be unmounted. - + a #GMount. + filename="gio/gmount.c" + line="691">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="692">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="693">a #GMountOperation or %NULL to avoid user interaction. @@ -78982,8 +82544,8 @@ unmounted. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="695">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="696">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data passed to @callback. + filename="gio/gmount.c" + line="697">user data passed to @callback. @@ -79013,27 +82575,27 @@ unmounted. invoker="remount_finish" throws="1"> Finishes remounting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="738">Finishes remounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the mount was successfully remounted. %FALSE otherwise. + filename="gio/gmount.c" + line="748">%TRUE if the mount was successfully remounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="740">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="741">a #GAsyncResult. @@ -79041,28 +82603,29 @@ unmounted. + deprecated-version="2.22" + glib:finish-func="unmount_finish"> Unmounts a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="369">Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_unmount_with_operation() instead. - + a #GMount. + filename="gio/gmount.c" + line="371">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="372">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="373">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="374">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="3"> user data passed to @callback. + filename="gio/gmount.c" + line="375">user data passed to @callback. @@ -79103,55 +82666,56 @@ and #GAsyncResult data returned in the @callback. deprecated-version="2.22" throws="1"> Finishes unmounting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="411">Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_unmount_with_operation_finish() instead. - + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + filename="gio/gmount.c" + line="421">%TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="413">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="414">a #GAsyncResult. + version="2.22" + glib:finish-func="unmount_with_operation_finish"> Unmounts a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="520">Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. - + a #GMount. + filename="gio/gmount.c" + line="522">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="523">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="524">a #GMountOperation or %NULL to avoid user interaction. @@ -79169,8 +82733,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="526">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="527">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data passed to @callback. + filename="gio/gmount.c" + line="528">user data passed to @callback. @@ -79201,33 +82765,36 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes unmounting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="568">Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + filename="gio/gmount.c" + line="578">%TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="570">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="571">a #GAsyncResult. - + The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. + @@ -79239,40 +82806,40 @@ and #GAsyncResult data returned in the @callback. Checks if @mount can be ejected. - + filename="gio/gmount.c" + line="349">Checks if @mount can be ejected. + %TRUE if the @mount can be ejected. + filename="gio/gmount.c" + line="355">%TRUE if the @mount can be ejected. a #GMount. + filename="gio/gmount.c" + line="351">a #GMount. Checks if @mount can be unmounted. - + filename="gio/gmount.c" + line="329">Checks if @mount can be unmounted. + %TRUE if the @mount can be unmounted. + filename="gio/gmount.c" + line="335">%TRUE if the @mount can be unmounted. a #GMount. + filename="gio/gmount.c" + line="331">a #GMount. @@ -79280,28 +82847,29 @@ and #GAsyncResult data returned in the @callback. + deprecated-version="2.22" + glib:finish-func="eject_finish"> Ejects a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="445">Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_eject_with_operation() instead. - + a #GMount. + filename="gio/gmount.c" + line="447">a #GMount. flags affecting the unmount if required for eject + filename="gio/gmount.c" + line="448">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="449">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="450">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gmount.c" + line="451">user data passed to @callback. @@ -79341,55 +82909,56 @@ and #GAsyncResult data returned in the @callback. deprecated-version="2.22" throws="1"> Finishes ejecting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="487">Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_eject_with_operation_finish() instead. - + %TRUE if the mount was successfully ejected. %FALSE otherwise. + filename="gio/gmount.c" + line="497">%TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="489">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="490">a #GAsyncResult. + version="2.22" + glib:finish-func="eject_with_operation_finish"> Ejects a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="605">Ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. - + a #GMount. + filename="gio/gmount.c" + line="607">a #GMount. flags affecting the unmount if required for eject + filename="gio/gmount.c" + line="608">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="609">a #GMountOperation or %NULL to avoid user interaction. @@ -79407,8 +82976,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="611">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="612">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gmount.c" + line="613">user data passed to @callback. @@ -79438,27 +83007,27 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes ejecting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="653">Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the mount was successfully ejected. %FALSE otherwise. + filename="gio/gmount.c" + line="663">%TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="655">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="656">a #GAsyncResult. @@ -79466,15 +83035,15 @@ and #GAsyncResult data returned in the @callback. Gets the default location of @mount. The default location of the given + filename="gio/gmount.c" + line="148">Gets the default location of @mount. The default location of the given @mount is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume). - + a #GFile. + filename="gio/gmount.c" + line="156">a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -79482,24 +83051,24 @@ the home directory, or the root of the volume). a #GMount. + filename="gio/gmount.c" + line="150">a #GMount. Gets the drive for the @mount. + filename="gio/gmount.c" + line="303">Gets the drive for the @mount. This is a convenience method for getting the #GVolume and then using that object to get the #GDrive. - + a #GDrive or %NULL if @mount is not + filename="gio/gmount.c" + line="312">a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -79508,21 +83077,21 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="305">a #GMount. Gets the icon for @mount. - + filename="gio/gmount.c" + line="201">Gets the icon for @mount. + a #GIcon. + filename="gio/gmount.c" + line="207">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -79530,21 +83099,21 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="203">a #GMount. Gets the name of @mount. - + filename="gio/gmount.c" + line="179">Gets the name of @mount. + the name for the given @mount. + filename="gio/gmount.c" + line="185">the name for the given @mount. The returned string should be freed with g_free() when no longer needed. @@ -79552,21 +83121,21 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="181">a #GMount. Gets the root directory on @mount. - + filename="gio/gmount.c" + line="126">Gets the root directory on @mount. + a #GFile. + filename="gio/gmount.c" + line="132">a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -79574,8 +83143,8 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="128">a #GMount. @@ -79584,20 +83153,20 @@ using that object to get the #GDrive. c:identifier="g_mount_get_sort_key" version="2.32"> Gets the sort key for @mount, if any. - + filename="gio/gmount.c" + line="1042">Gets the sort key for @mount, if any. + Sorting key for @mount or %NULL if no such key is available. + filename="gio/gmount.c" + line="1048">Sorting key for @mount or %NULL if no such key is available. A #GMount. + filename="gio/gmount.c" + line="1044">A #GMount. @@ -79606,13 +83175,13 @@ using that object to get the #GDrive. c:identifier="g_mount_get_symbolic_icon" version="2.34"> Gets the symbolic icon for @mount. - + filename="gio/gmount.c" + line="224">Gets the symbolic icon for @mount. + a #GIcon. + filename="gio/gmount.c" + line="230">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -79620,24 +83189,24 @@ using that object to get the #GDrive. a #GMount. + filename="gio/gmount.c" + line="226">a #GMount. Gets the UUID for the @mount. The reference is typically based on + filename="gio/gmount.c" + line="254">Gets the UUID for the @mount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - + the UUID for @mount or %NULL if no UUID + filename="gio/gmount.c" + line="263">the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. @@ -79646,21 +83215,21 @@ available. a #GMount. + filename="gio/gmount.c" + line="256">a #GMount. Gets the volume for the @mount. - + filename="gio/gmount.c" + line="280">Gets the volume for the @mount. + a #GVolume or %NULL if @mount is not + filename="gio/gmount.c" + line="286">a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -79669,18 +83238,20 @@ available. a #GMount. + filename="gio/gmount.c" + line="282">a #GMount. + version="2.18" + glib:finish-func="guess_content_type_finish" + glib:sync-func="guess_content_type_sync"> Tries to guess the type of content stored on @mount. Returns one or + filename="gio/gmount.c" + line="769">Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the @@ -79691,21 +83262,21 @@ This is an asynchronous operation (see g_mount_guess_content_type_sync() for the synchronous version), and is finished by calling g_mount_guess_content_type_finish() with the @mount and #GAsyncResult data returned in the @callback. - + a #GMount + filename="gio/gmount.c" + line="771">a #GMount Whether to force a rescan of the content. + filename="gio/gmount.c" + line="772">Whether to force a rescan of the content. Otherwise a cached result will be used if available @@ -79714,8 +83285,8 @@ is finished by calling g_mount_guess_content_type_finish() with the nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gmount.c" + line="774">optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback + filename="gio/gmount.c" + line="775">a #GAsyncReadyCallback user data passed to @callback + filename="gio/gmount.c" + line="776">user data passed to @callback @@ -79745,17 +83316,17 @@ is finished by calling g_mount_guess_content_type_finish() with the version="2.18" throws="1"> Finishes guessing content types of @mount. If any errors occurred + filename="gio/gmount.c" + line="820">Finishes guessing content types of @mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. In particular, you may get an %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content guessing. - + a %NULL-terminated array of content types or %NULL on error. + filename="gio/gmount.c" + line="833">a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. @@ -79764,14 +83335,14 @@ guessing. a #GMount + filename="gio/gmount.c" + line="822">a #GMount a #GAsyncResult + filename="gio/gmount.c" + line="823">a #GAsyncResult @@ -79779,10 +83350,11 @@ guessing. + throws="1" + glib:async-func="guess_content_type"> Tries to guess the type of content stored on @mount. Returns one or + filename="gio/gmount.c" + line="857">Tries to guess the type of content stored on @mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the @@ -79791,11 +83363,11 @@ specification for more on x-content types. This is a synchronous operation and as such may block doing IO; see g_mount_guess_content_type() for the asynchronous version. - + a %NULL-terminated array of content types or %NULL on error. + filename="gio/gmount.c" + line="876">a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. @@ -79804,14 +83376,14 @@ see g_mount_guess_content_type() for the asynchronous version. a #GMount + filename="gio/gmount.c" + line="859">a #GMount Whether to force a rescan of the content. + filename="gio/gmount.c" + line="860">Whether to force a rescan of the content. Otherwise a cached result will be used if available @@ -79820,8 +83392,8 @@ see g_mount_guess_content_type() for the asynchronous version. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gmount.c" + line="862">optional #GCancellable object, %NULL to ignore @@ -79830,8 +83402,8 @@ see g_mount_guess_content_type() for the asynchronous version. c:identifier="g_mount_is_shadowed" version="2.20"> Determines if @mount is shadowed. Applications or libraries should + filename="gio/gmount.c" + line="944">Determines if @mount is shadowed. Applications or libraries should avoid displaying @mount in the user interface if it is shadowed. A mount is said to be shadowed if there exists one or more user @@ -79854,26 +83426,28 @@ root) that would shadow the original mount. The proxy monitor in GVfs 2.26 and later, automatically creates and manage shadow mounts (and shadows the underlying mount) if the activation root on a #GVolume is set. - + %TRUE if @mount is shadowed. + filename="gio/gmount.c" + line="972">%TRUE if @mount is shadowed. A #GMount. + filename="gio/gmount.c" + line="946">A #GMount. - + Remounts a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="689">Remounts a mount. This is an asynchronous operation, and is finished by calling g_mount_remount_finish() with the @mount and #GAsyncResults data returned in the @callback. @@ -79882,21 +83456,21 @@ of the volume has been changed, as these may need a remount to take affect. While this is semantically equivalent with unmounting and then remounting not all backends might need to actually be unmounted. - + a #GMount. + filename="gio/gmount.c" + line="691">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="692">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="693">a #GMountOperation or %NULL to avoid user interaction. @@ -79914,8 +83488,8 @@ unmounted. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="695">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="696">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gmount.c" + line="697">user data passed to @callback. @@ -79944,47 +83518,47 @@ unmounted. c:identifier="g_mount_remount_finish" throws="1"> Finishes remounting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="738">Finishes remounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the mount was successfully remounted. %FALSE otherwise. + filename="gio/gmount.c" + line="748">%TRUE if the mount was successfully remounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="740">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="741">a #GAsyncResult. Increments the shadow count on @mount. Usually used by + filename="gio/gmount.c" + line="992">Increments the shadow count on @mount. Usually used by #GVolumeMonitor implementations when creating a shadow mount for @mount, see g_mount_is_shadowed() for more information. The caller will need to emit the #GMount::changed signal on @mount manually. - + A #GMount. + filename="gio/gmount.c" + line="994">A #GMount. @@ -79992,28 +83566,29 @@ will need to emit the #GMount::changed signal on @mount manually. + deprecated-version="2.22" + glib:finish-func="unmount_finish"> Unmounts a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="369">Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_finish() with the @mount and #GAsyncResult data returned in the @callback. Use g_mount_unmount_with_operation() instead. - + a #GMount. + filename="gio/gmount.c" + line="371">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="372">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="373">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="374">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gmount.c" + line="375">user data passed to @callback. @@ -80053,55 +83628,56 @@ and #GAsyncResult data returned in the @callback. deprecated-version="2.22" throws="1"> Finishes unmounting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="411">Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_mount_unmount_with_operation_finish() instead. - + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + filename="gio/gmount.c" + line="421">%TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="413">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="414">a #GAsyncResult. + version="2.22" + glib:finish-func="unmount_with_operation_finish"> Unmounts a mount. This is an asynchronous operation, and is + filename="gio/gmount.c" + line="520">Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_with_operation_finish() with the @mount and #GAsyncResult data returned in the @callback. - + a #GMount. + filename="gio/gmount.c" + line="522">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="523">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="524">a #GMountOperation or %NULL to avoid user interaction. @@ -80119,8 +83695,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="526">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="527">a #GAsyncReadyCallback, or %NULL. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gmount.c" + line="528">user data passed to @callback. @@ -80150,63 +83726,63 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes unmounting a mount. If any errors occurred during the operation, + filename="gio/gmount.c" + line="568">Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + filename="gio/gmount.c" + line="578">%TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="570">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="571">a #GAsyncResult. Decrements the shadow count on @mount. Usually used by + filename="gio/gmount.c" + line="1016">Decrements the shadow count on @mount. Usually used by #GVolumeMonitor implementations when destroying a shadow mount for @mount, see g_mount_is_shadowed() for more information. The caller will need to emit the #GMount::changed signal on @mount manually. - + A #GMount. + filename="gio/gmount.c" + line="1018">A #GMount. Emitted when the mount has been changed. + filename="gio/gmount.c" + line="75">Emitted when the mount has been changed. This signal may be emitted when the #GMount is about to be + filename="gio/gmount.c" + line="105">This signal may be emitted when the #GMount is about to be unmounted. This signal depends on the backend and is only emitted if @@ -80217,8 +83793,8 @@ GIO was used to unmount. This signal is emitted when the #GMount have been + filename="gio/gmount.c" + line="89">This signal is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. @@ -80231,18 +83807,21 @@ finalized. c:type="GMountIface" glib:is-gtype-struct-for="Mount"> Interface for implementing operations for mounts. - + The parent interface. + Changed signal that is emitted when the mount's state has changed. - + @@ -80254,8 +83833,11 @@ finalized. + The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. - + @@ -80267,12 +83849,15 @@ finalized. + Gets a #GFile to the root directory of the #GMount. - + a #GFile. + filename="gio/gmount.c" + line="132">a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -80280,20 +83865,23 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="128">a #GMount. + Gets a string containing the name of the #GMount. - + the name for the given @mount. + filename="gio/gmount.c" + line="185">the name for the given @mount. The returned string should be freed with g_free() when no longer needed. @@ -80301,20 +83889,23 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="181">a #GMount. + Gets a #GIcon for the #GMount. - + a #GIcon. + filename="gio/gmount.c" + line="207">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -80322,20 +83913,23 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="203">a #GMount. + Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - + the UUID for @mount or %NULL if no UUID + filename="gio/gmount.c" + line="263">the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. @@ -80344,20 +83938,23 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="256">a #GMount. + Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume. - + a #GVolume or %NULL if @mount is not + filename="gio/gmount.c" + line="286">a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -80366,20 +83963,23 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="282">a #GMount. + Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive. - + a #GDrive or %NULL if @mount is not + filename="gio/gmount.c" + line="312">a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -80388,68 +83988,77 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="305">a #GMount. + Checks if a #GMount can be unmounted. - + %TRUE if the @mount can be unmounted. + filename="gio/gmount.c" + line="335">%TRUE if the @mount can be unmounted. a #GMount. + filename="gio/gmount.c" + line="331">a #GMount. + Checks if a #GMount can be ejected. - + %TRUE if the @mount can be ejected. + filename="gio/gmount.c" + line="355">%TRUE if the @mount can be ejected. a #GMount. + filename="gio/gmount.c" + line="351">a #GMount. + Starts unmounting a #GMount. - + a #GMount. + filename="gio/gmount.c" + line="371">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="372">flags affecting the operation nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="373">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="374">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data passed to @callback. + filename="gio/gmount.c" + line="375">user data passed to @callback. + Finishes an unmounting operation. - + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + filename="gio/gmount.c" + line="421">%TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="413">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="414">a #GAsyncResult. + Starts ejecting a #GMount. - + a #GMount. + filename="gio/gmount.c" + line="447">a #GMount. flags affecting the unmount if required for eject + filename="gio/gmount.c" + line="448">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="449">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="450">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="4"> user data passed to @callback. + filename="gio/gmount.c" + line="451">user data passed to @callback. + Finishes an eject operation. - + %TRUE if the mount was successfully ejected. %FALSE otherwise. + filename="gio/gmount.c" + line="497">%TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="489">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="490">a #GAsyncResult. + Starts remounting a #GMount. - + a #GMount. + filename="gio/gmount.c" + line="691">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="692">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="693">a #GMountOperation or %NULL to avoid user interaction. @@ -80621,8 +84242,8 @@ finalized. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="695">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="696">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="5"> user data passed to @callback. + filename="gio/gmount.c" + line="697">user data passed to @callback. + Finishes a remounting operation. - + %TRUE if the mount was successfully remounted. %FALSE otherwise. + filename="gio/gmount.c" + line="748">%TRUE if the mount was successfully remounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="740">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="741">a #GAsyncResult. + Starts guessing the type of the content of a #GMount. + See g_mount_guess_content_type() for more information on content + type guessing. This operation was added in 2.18. - + a #GMount + filename="gio/gmount.c" + line="771">a #GMount Whether to force a rescan of the content. + filename="gio/gmount.c" + line="772">Whether to force a rescan of the content. Otherwise a cached result will be used if available @@ -80699,8 +84328,8 @@ finalized. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gmount.c" + line="774">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gmount.c" + line="775">a #GAsyncReadyCallback allow-none="1" closure="4"> user data passed to @callback + filename="gio/gmount.c" + line="776">user data passed to @callback + Finishes a content type guessing operation. Added in 2.18. - + a %NULL-terminated array of content types or %NULL on error. + filename="gio/gmount.c" + line="833">a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. @@ -80742,26 +84374,29 @@ finalized. a #GMount + filename="gio/gmount.c" + line="822">a #GMount a #GAsyncResult + filename="gio/gmount.c" + line="823">a #GAsyncResult + Synchronous variant of @guess_content_type. Added in 2.18 - + a %NULL-terminated array of content types or %NULL on error. + filename="gio/gmount.c" + line="876">a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. @@ -80770,14 +84405,14 @@ finalized. a #GMount + filename="gio/gmount.c" + line="859">a #GMount Whether to force a rescan of the content. + filename="gio/gmount.c" + line="860">Whether to force a rescan of the content. Otherwise a cached result will be used if available @@ -80786,16 +84421,19 @@ finalized. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gmount.c" + line="862">optional #GCancellable object, %NULL to ignore + The ::pre-unmount signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. - + @@ -80807,22 +84445,25 @@ finalized. + Starts unmounting a #GMount using a #GMountOperation. Since 2.22. - + a #GMount. + filename="gio/gmount.c" + line="522">a #GMount. flags affecting the operation + filename="gio/gmount.c" + line="523">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="524">a #GMountOperation or %NULL to avoid user interaction. @@ -80840,8 +84481,8 @@ finalized. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="526">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="527">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="5"> user data passed to @callback. + filename="gio/gmount.c" + line="528">user data passed to @callback. + Finishes an unmounting operation using a #GMountOperation. Since 2.22. - + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + filename="gio/gmount.c" + line="578">%TRUE if the mount was successfully unmounted. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="570">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="571">a #GAsyncResult. + Starts ejecting a #GMount using a #GMountOperation. Since 2.22. - + a #GMount. + filename="gio/gmount.c" + line="607">a #GMount. flags affecting the unmount if required for eject + filename="gio/gmount.c" + line="608">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid + filename="gio/gmount.c" + line="609">a #GMountOperation or %NULL to avoid user interaction. @@ -80927,8 +84574,8 @@ finalized. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gmount.c" + line="611">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL. + filename="gio/gmount.c" + line="612">a #GAsyncReadyCallback, or %NULL. allow-none="1" closure="5"> user data passed to @callback. + filename="gio/gmount.c" + line="613">user data passed to @callback. + Finishes an eject operation using a #GMountOperation. Since 2.22. - + %TRUE if the mount was successfully ejected. %FALSE otherwise. + filename="gio/gmount.c" + line="663">%TRUE if the mount was successfully ejected. %FALSE otherwise. a #GMount. + filename="gio/gmount.c" + line="655">a #GMount. a #GAsyncResult. + filename="gio/gmount.c" + line="656">a #GAsyncResult. + Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24. - + a #GFile. + filename="gio/gmount.c" + line="156">a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -80994,39 +84647,45 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="150">a #GMount. + Gets a key used for sorting #GMount instance or %NULL if no such key exists. Since 2.32. - + Sorting key for @mount or %NULL if no such key is available. + filename="gio/gmount.c" + line="1048">Sorting key for @mount or %NULL if no such key is available. A #GMount. + filename="gio/gmount.c" + line="1044">A #GMount. + Gets a symbolic #GIcon for the #GMount. Since 2.34. - + a #GIcon. + filename="gio/gmount.c" + line="230">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -81034,8 +84693,8 @@ finalized. a #GMount. + filename="gio/gmount.c" + line="226">a #GMount. @@ -81047,7 +84706,7 @@ finalized. glib:get-type="g_mount_mount_flags_get_type" c:type="GMountMountFlags"> Flags used when mounting a mount. glib:nick="none" glib:name="G_MOUNT_MOUNT_NONE"> No flags set. @@ -81067,43 +84726,44 @@ finalized. glib:get-type="g_mount_operation_get_type" glib:type-struct="MountOperationClass"> #GMountOperation provides a mechanism for interacting with the user. + filename="gio/gmountoperation.c" + line="33">`GMountOperation` provides a mechanism for interacting with the user. It can be used for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations. It can also be used to ask the user questions or show a list of applications preventing unmount or eject operations from completing. -Note that #GMountOperation is used for more than just #GMount -objects – for example it is also used in g_drive_start() and -g_drive_stop(). +Note that `GMountOperation` is used for more than just [iface@Gio.Mount] +objects – for example it is also used in [method@Gio.Drive.start] and +[method@Gio.Drive.stop]. Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as -#GtkMountOperation. If no user interaction is desired (for example -when automounting filesystems at login time), usually %NULL can be -passed, see each method taking a #GMountOperation for details. +[`GtkMountOperation`](https://docs.gtk.org/gtk4/class.MountOperation.html). +If no user interaction is desired (for example when automounting +filesystems at login time), usually `NULL` can be passed, see each method +taking a `GMountOperation` for details. -The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. +Throughout the API, the term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various improvements and auditing fixes. - + Creates a new mount operation. - + filename="gio/gmountoperation.c" + line="605">Creates a new mount operation. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="610">a #GMountOperation. - + @@ -81114,7 +84774,7 @@ improvements and auditing fixes. - + @@ -81138,29 +84798,29 @@ improvements and auditing fixes. Virtual implementation of #GMountOperation::ask-question. - + filename="gio/gmountoperation.h" + line="63">Virtual implementation of #GMountOperation::ask-question. + a #GMountOperation + filename="gio/gmountoperation.h" + line="65">a #GMountOperation string containing a message to display to the user + filename="gio/gmountoperation.h" + line="66">string containing a message to display to the user an array of + filename="gio/gmountoperation.h" + line="67">an array of strings for each possible choice @@ -81170,52 +84830,52 @@ improvements and auditing fixes. Emits the #GMountOperation::reply signal. - + filename="gio/gmountoperation.c" + line="953">Emits the #GMountOperation::reply signal. + a #GMountOperation + filename="gio/gmountoperation.c" + line="955">a #GMountOperation a #GMountOperationResult + filename="gio/gmountoperation.c" + line="956">a #GMountOperationResult Virtual implementation of #GMountOperation::show-processes. - + filename="gio/gmountoperation.h" + line="81">Virtual implementation of #GMountOperation::show-processes. + a #GMountOperation + filename="gio/gmountoperation.h" + line="83">a #GMountOperation string containing a message to display to the user + filename="gio/gmountoperation.h" + line="84">string containing a message to display to the user an array of #GPid for processes blocking + filename="gio/gmountoperation.h" + line="85">an array of #GPid for processes blocking the operation @@ -81223,8 +84883,8 @@ improvements and auditing fixes. an array of + filename="gio/gmountoperation.h" + line="87">an array of strings for each possible choice @@ -81233,7 +84893,7 @@ improvements and auditing fixes. - + @@ -81256,21 +84916,21 @@ improvements and auditing fixes. c:identifier="g_mount_operation_get_anonymous" glib:get-property="anonymous"> Check to see whether the mount operation is being used + filename="gio/gmountoperation.c" + line="683">Check to see whether the mount operation is being used for an anonymous user. - + %TRUE if mount operation is anonymous. + filename="gio/gmountoperation.c" + line="690">%TRUE if mount operation is anonymous. a #GMountOperation. + filename="gio/gmountoperation.c" + line="685">a #GMountOperation. @@ -81279,21 +84939,21 @@ for an anonymous user. c:identifier="g_mount_operation_get_choice" glib:get-property="choice"> Gets a choice from the mount operation. - + filename="gio/gmountoperation.c" + line="792">Gets a choice from the mount operation. + an integer containing an index of the user's choice from + filename="gio/gmountoperation.c" + line="798">an integer containing an index of the user's choice from the choice's list, or `0`. a #GMountOperation. + filename="gio/gmountoperation.c" + line="794">a #GMountOperation. @@ -81302,20 +84962,20 @@ the choice's list, or `0`. c:identifier="g_mount_operation_get_domain" glib:get-property="domain"> Gets the domain of the mount operation. - + filename="gio/gmountoperation.c" + line="721">Gets the domain of the mount operation. + a string set to the domain. + filename="gio/gmountoperation.c" + line="727">a string set to the domain. a #GMountOperation. + filename="gio/gmountoperation.c" + line="723">a #GMountOperation. @@ -81325,21 +84985,21 @@ the choice's list, or `0`. glib:get-property="is-tcrypt-hidden-volume" version="2.58"> Check to see whether the mount operation is being used + filename="gio/gmountoperation.c" + line="829">Check to see whether the mount operation is being used for a TCRYPT hidden volume. - + %TRUE if mount operation is for hidden volume. + filename="gio/gmountoperation.c" + line="836">%TRUE if mount operation is for hidden volume. a #GMountOperation. + filename="gio/gmountoperation.c" + line="831">a #GMountOperation. @@ -81349,21 +85009,21 @@ for a TCRYPT hidden volume. glib:get-property="is-tcrypt-system-volume" version="2.58"> Check to see whether the mount operation is being used + filename="gio/gmountoperation.c" + line="871">Check to see whether the mount operation is being used for a TCRYPT system volume. - + %TRUE if mount operation is for system volume. + filename="gio/gmountoperation.c" + line="878">%TRUE if mount operation is for system volume. a #GMountOperation. + filename="gio/gmountoperation.c" + line="873">a #GMountOperation. @@ -81372,20 +85032,20 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_get_password" glib:get-property="password"> Gets a password from the mount operation. - + filename="gio/gmountoperation.c" + line="650">Gets a password from the mount operation. + a string containing the password within @op. + filename="gio/gmountoperation.c" + line="656">a string containing the password within @op. a #GMountOperation. + filename="gio/gmountoperation.c" + line="652">a #GMountOperation. @@ -81394,20 +85054,20 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_get_password_save" glib:get-property="password-save"> Gets the state of saving passwords for the mount operation. - + filename="gio/gmountoperation.c" + line="753">Gets the state of saving passwords for the mount operation. + a #GPasswordSave flag. + filename="gio/gmountoperation.c" + line="759">a #GPasswordSave flag. a #GMountOperation. + filename="gio/gmountoperation.c" + line="755">a #GMountOperation. @@ -81417,20 +85077,20 @@ for a TCRYPT system volume. glib:get-property="pim" version="2.58"> Gets a PIM from the mount operation. - + filename="gio/gmountoperation.c" + line="913">Gets a PIM from the mount operation. + The VeraCrypt PIM within @op. + filename="gio/gmountoperation.c" + line="919">The VeraCrypt PIM within @op. a #GMountOperation. + filename="gio/gmountoperation.c" + line="915">a #GMountOperation. @@ -81439,43 +85099,43 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_get_username" glib:get-property="username"> Get the user name from the mount operation. - + filename="gio/gmountoperation.c" + line="618">Get the user name from the mount operation. + a string containing the user name. + filename="gio/gmountoperation.c" + line="624">a string containing the user name. a #GMountOperation. + filename="gio/gmountoperation.c" + line="620">a #GMountOperation. Emits the #GMountOperation::reply signal. - + filename="gio/gmountoperation.c" + line="953">Emits the #GMountOperation::reply signal. + a #GMountOperation + filename="gio/gmountoperation.c" + line="955">a #GMountOperation a #GMountOperationResult + filename="gio/gmountoperation.c" + line="956">a #GMountOperationResult @@ -81484,23 +85144,23 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_set_anonymous" glib:set-property="anonymous"> Sets the mount operation to use an anonymous user if @anonymous is %TRUE. - + filename="gio/gmountoperation.c" + line="699">Sets the mount operation to use an anonymous user if @anonymous is %TRUE. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="701">a #GMountOperation. boolean value. + filename="gio/gmountoperation.c" + line="702">boolean value. @@ -81509,23 +85169,23 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_set_choice" glib:set-property="choice"> Sets a default choice for the mount operation. - + filename="gio/gmountoperation.c" + line="808">Sets a default choice for the mount operation. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="810">a #GMountOperation. an integer. + filename="gio/gmountoperation.c" + line="811">an integer. @@ -81534,17 +85194,17 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_set_domain" glib:set-property="domain"> Sets the mount operation's domain. - + filename="gio/gmountoperation.c" + line="736">Sets the mount operation's domain. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="738">a #GMountOperation. nullable="1" allow-none="1"> the domain to set. + filename="gio/gmountoperation.c" + line="739">the domain to set. @@ -81563,23 +85223,23 @@ for a TCRYPT system volume. glib:set-property="is-tcrypt-hidden-volume" version="2.58"> Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. - + filename="gio/gmountoperation.c" + line="847">Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="849">a #GMountOperation. boolean value. + filename="gio/gmountoperation.c" + line="850">boolean value. @@ -81589,23 +85249,23 @@ for a TCRYPT system volume. glib:set-property="is-tcrypt-system-volume" version="2.58"> Sets the mount operation to use a system volume if @system_volume is %TRUE. - + filename="gio/gmountoperation.c" + line="889">Sets the mount operation to use a system volume if @system_volume is %TRUE. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="891">a #GMountOperation. boolean value. + filename="gio/gmountoperation.c" + line="892">boolean value. @@ -81614,17 +85274,17 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_set_password" glib:set-property="password"> Sets the mount operation's password to @password. - + filename="gio/gmountoperation.c" + line="665">Sets the mount operation's password to @password. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="667">a #GMountOperation. nullable="1" allow-none="1"> password to set. + filename="gio/gmountoperation.c" + line="668">password to set. @@ -81642,23 +85302,23 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_set_password_save" glib:set-property="password-save"> Sets the state of saving passwords for the mount operation. - + filename="gio/gmountoperation.c" + line="769">Sets the state of saving passwords for the mount operation. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="771">a #GMountOperation. a set of #GPasswordSave flags. + filename="gio/gmountoperation.c" + line="772">a set of #GPasswordSave flags. @@ -81668,23 +85328,23 @@ for a TCRYPT system volume. glib:set-property="pim" version="2.58"> Sets the mount operation's PIM to @pim. - + filename="gio/gmountoperation.c" + line="930">Sets the mount operation's PIM to @pim. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="932">a #GMountOperation. an unsigned integer. + filename="gio/gmountoperation.c" + line="933">an unsigned integer. @@ -81693,17 +85353,17 @@ for a TCRYPT system volume. c:identifier="g_mount_operation_set_username" glib:set-property="username"> Sets the user name within @op to @username. - + filename="gio/gmountoperation.c" + line="633">Sets the user name within @op to @username. + a #GMountOperation. + filename="gio/gmountoperation.c" + line="635">a #GMountOperation. nullable="1" allow-none="1"> input username. + filename="gio/gmountoperation.c" + line="636">input username. @@ -81724,8 +85384,8 @@ for a TCRYPT system volume. getter="get_anonymous" default-value="FALSE"> Whether to use an anonymous user when authenticating. + filename="gio/gmountoperation.c" + line="500">Whether to use an anonymous user when authenticating. getter="get_choice" default-value="0"> The index of the user's choice when a question is asked during the + filename="gio/gmountoperation.c" + line="537">The index of the user's choice when a question is asked during the mount operation. See the #GMountOperation::ask-question signal. @@ -81747,8 +85407,8 @@ mount operation. See the #GMountOperation::ask-question signal. getter="get_domain" default-value="NULL"> The domain to use for the mount operation. + filename="gio/gmountoperation.c" + line="512">The domain to use for the mount operation. getter="get_is_tcrypt_hidden_volume" default-value="FALSE"> Whether the device to be unlocked is a TCRYPT hidden volume. + filename="gio/gmountoperation.c" + line="550">Whether the device to be unlocked is a TCRYPT hidden volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html). @@ -81772,8 +85432,8 @@ See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.ht getter="get_is_tcrypt_system_volume" default-value="FALSE"> Whether the device to be unlocked is a TCRYPT system volume. + filename="gio/gmountoperation.c" + line="565">Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see @@ -81787,8 +85447,8 @@ operating systems. For further documentation, see getter="get_password" default-value="NULL"> The password that is used for authentication when carrying out + filename="gio/gmountoperation.c" + line="487">The password that is used for authentication when carrying out the mount operation. @@ -81799,8 +85459,8 @@ the mount operation. getter="get_password_save" default-value="G_PASSWORD_SAVE_NEVER"> Determines if and how the password information should be saved. + filename="gio/gmountoperation.c" + line="524">Determines if and how the password information should be saved. getter="get_pim" default-value="0"> The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See + filename="gio/gmountoperation.c" + line="583">The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html). @@ -81823,8 +85483,8 @@ the mount operation. getter="get_username" default-value="NULL"> The user name that is used for authentication when carrying out + filename="gio/gmountoperation.c" + line="474">The user name that is used for authentication when carrying out the mount operation. @@ -81836,8 +85496,8 @@ the mount operation. Emitted by the backend when e.g. a device becomes unavailable + filename="gio/gmountoperation.c" + line="376">Emitted by the backend when e.g. a device becomes unavailable while a mount operation is in progress. Implementations of GMountOperation should handle this signal @@ -81848,8 +85508,8 @@ by dismissing open password dialogs. Emitted when a mount operation asks the user for a password. + filename="gio/gmountoperation.c" + line="306">Emitted when a mount operation asks the user for a password. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the @@ -81860,34 +85520,34 @@ primary text in a #GtkMessageDialog. string containing a message to display to the user. + filename="gio/gmountoperation.c" + line="309">string containing a message to display to the user. string containing the default user name. + filename="gio/gmountoperation.c" + line="310">string containing the default user name. string containing the default domain. + filename="gio/gmountoperation.c" + line="311">string containing the default domain. a set of #GAskPasswordFlags. + filename="gio/gmountoperation.c" + line="312">a set of #GAskPasswordFlags. Emitted when asking the user a question and gives a list of + filename="gio/gmountoperation.c" + line="333">Emitted when asking the user a question and gives a list of choices for the user to choose from. If the message contains a line break, the first line should be @@ -81899,14 +85559,14 @@ primary text in a #GtkMessageDialog. string containing a message to display to the user. + filename="gio/gmountoperation.c" + line="336">string containing a message to display to the user. an array of strings for each possible choice. + filename="gio/gmountoperation.c" + line="337">an array of strings for each possible choice. @@ -81915,24 +85575,24 @@ primary text in a #GtkMessageDialog. Emitted when the user has replied to the mount operation. + filename="gio/gmountoperation.c" + line="359">Emitted when the user has replied to the mount operation. a #GMountOperationResult indicating how the request was handled + filename="gio/gmountoperation.c" + line="362">a #GMountOperationResult indicating how the request was handled Emitted when one or more processes are blocking an operation + filename="gio/gmountoperation.c" + line="396">Emitted when one or more processes are blocking an operation e.g. unmounting/ejecting a #GMount or stopping a #GDrive. Note that this signal may be emitted several times to update the @@ -81950,14 +85610,14 @@ primary text in a #GtkMessageDialog. string containing a message to display to the user. + filename="gio/gmountoperation.c" + line="399">string containing a message to display to the user. an array of #GPid for processes + filename="gio/gmountoperation.c" + line="400">an array of #GPid for processes blocking the operation. @@ -81965,8 +85625,8 @@ primary text in a #GtkMessageDialog. an array of strings for each possible choice. + filename="gio/gmountoperation.c" + line="402">an array of strings for each possible choice. @@ -81975,8 +85635,8 @@ primary text in a #GtkMessageDialog. Emitted when an unmount operation has been busy for more than some time + filename="gio/gmountoperation.c" + line="432">Emitted when an unmount operation has been busy for more than some time (typically 1.5 seconds). When unmounting or ejecting a volume, the kernel might need to flush @@ -81998,21 +85658,21 @@ primary text in a #GtkMessageDialog. string containing a message to display to the user + filename="gio/gmountoperation.c" + line="435">string containing a message to display to the user the estimated time left before the operation completes, + filename="gio/gmountoperation.c" + line="436">the estimated time left before the operation completes, in microseconds, or -1 the amount of bytes to be written before the operation + filename="gio/gmountoperation.c" + line="438">the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed @@ -82023,13 +85683,13 @@ primary text in a #GtkMessageDialog. - + - + @@ -82054,27 +85714,27 @@ primary text in a #GtkMessageDialog. - + a #GMountOperation + filename="gio/gmountoperation.h" + line="65">a #GMountOperation string containing a message to display to the user + filename="gio/gmountoperation.h" + line="66">string containing a message to display to the user an array of + filename="gio/gmountoperation.h" + line="67">an array of strings for each possible choice @@ -82085,21 +85745,21 @@ primary text in a #GtkMessageDialog. - + a #GMountOperation + filename="gio/gmountoperation.c" + line="955">a #GMountOperation a #GMountOperationResult + filename="gio/gmountoperation.c" + line="956">a #GMountOperationResult @@ -82108,7 +85768,7 @@ primary text in a #GtkMessageDialog. - + @@ -82121,27 +85781,27 @@ primary text in a #GtkMessageDialog. - + a #GMountOperation + filename="gio/gmountoperation.h" + line="83">a #GMountOperation string containing a message to display to the user + filename="gio/gmountoperation.h" + line="84">string containing a message to display to the user an array of #GPid for processes blocking + filename="gio/gmountoperation.h" + line="85">an array of #GPid for processes blocking the operation @@ -82149,8 +85809,8 @@ primary text in a #GtkMessageDialog. an array of + filename="gio/gmountoperation.h" + line="87">an array of strings for each possible choice @@ -82161,7 +85821,7 @@ primary text in a #GtkMessageDialog. - + @@ -82183,7 +85843,7 @@ primary text in a #GtkMessageDialog. - + @@ -82191,7 +85851,7 @@ primary text in a #GtkMessageDialog. - + @@ -82199,7 +85859,7 @@ primary text in a #GtkMessageDialog. - + @@ -82207,7 +85867,7 @@ primary text in a #GtkMessageDialog. - + @@ -82215,7 +85875,7 @@ primary text in a #GtkMessageDialog. - + @@ -82223,7 +85883,7 @@ primary text in a #GtkMessageDialog. - + @@ -82231,7 +85891,7 @@ primary text in a #GtkMessageDialog. - + @@ -82239,7 +85899,7 @@ primary text in a #GtkMessageDialog. - + @@ -82247,7 +85907,7 @@ primary text in a #GtkMessageDialog. - + @@ -82258,15 +85918,15 @@ primary text in a #GtkMessageDialog. c:type="GMountOperationPrivate" disguised="1" opaque="1"> - + #GMountOperationResult is returned as a result when a request for + filename="gio/gioenums.h" + line="636">#GMountOperationResult is returned as a result when a request for information is send by the mounting operation. glib:nick="handled" glib:name="G_MOUNT_OPERATION_HANDLED"> The request was fulfilled and the + filename="gio/gioenums.h" + line="638">The request was fulfilled and the user specified data is now available glib:nick="aborted" glib:name="G_MOUNT_OPERATION_ABORTED"> The user requested the mount operation + filename="gio/gioenums.h" + line="640">The user requested the mount operation to be aborted glib:nick="unhandled" glib:name="G_MOUNT_OPERATION_UNHANDLED"> The request was unhandled (i.e. not + filename="gio/gioenums.h" + line="642">The request was unhandled (i.e. not implemented) @@ -82304,7 +85964,7 @@ information is send by the mounting operation. glib:get-type="g_mount_unmount_flags_get_type" c:type="GMountUnmountFlags"> Flags used when an unmounting a mount. glib:nick="none" glib:name="G_MOUNT_UNMOUNT_NONE"> No flags set. glib:nick="force" glib:name="G_MOUNT_UNMOUNT_FORCE"> Unmount even if there are outstanding file operations on the mount. @@ -82329,7 +85989,7 @@ information is send by the mounting operation. - + @@ -82338,7 +85998,7 @@ information is send by the mounting operation. - + @@ -82347,7 +86007,7 @@ information is send by the mounting operation. - + @@ -82356,7 +86016,7 @@ information is send by the mounting operation. - + @@ -82365,7 +86025,7 @@ information is send by the mounting operation. - + @@ -82374,13 +86034,13 @@ information is send by the mounting operation. - + - + @@ -82389,7 +86049,7 @@ information is send by the mounting operation. - + @@ -82398,7 +86058,7 @@ information is send by the mounting operation. - + @@ -82407,7 +86067,7 @@ information is send by the mounting operation. - + @@ -82418,16 +86078,16 @@ information is send by the mounting operation. c:type="G_NETWORK_MONITOR_EXTENSION_POINT_NAME" version="2.30"> Extension point for network status monitoring functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -82436,7 +86096,7 @@ See [Extending GIO][extending-gio]. - + @@ -82445,7 +86105,7 @@ See [Extending GIO][extending-gio]. - + @@ -82454,7 +86114,7 @@ See [Extending GIO][extending-gio]. - + @@ -82463,7 +86123,7 @@ See [Extending GIO][extending-gio]. - + @@ -82472,26 +86132,30 @@ See [Extending GIO][extending-gio]. A socket address of some unknown native type. - + filename="gio/gnativesocketaddress.c" + line="34">A socket address of some unknown native type. + +This corresponds to a general `struct sockaddr` of a type not otherwise +handled by GLib. + Creates a new #GNativeSocketAddress for @native and @len. - + filename="gio/gnativesocketaddress.c" + line="134">Creates a new #GNativeSocketAddress for @native and @len. + a new #GNativeSocketAddress + filename="gio/gnativesocketaddress.c" + line="141">a new #GNativeSocketAddress @@ -82500,14 +86164,14 @@ See [Extending GIO][extending-gio]. nullable="1" allow-none="1"> a native address object + filename="gio/gnativesocketaddress.c" + line="136">a native address object the length of @native, in bytes + filename="gio/gnativesocketaddress.c" + line="137">the length of @native, in bytes @@ -82523,7 +86187,7 @@ See [Extending GIO][extending-gio]. - + @@ -82532,7 +86196,7 @@ See [Extending GIO][extending-gio]. c:type="GNativeSocketAddressPrivate" disguised="1" opaque="1"> - + glib:type-name="GNativeVolumeMonitor" glib:get-type="g_native_volume_monitor_get_type" glib:type-struct="NativeVolumeMonitorClass"> - + @@ -82550,13 +86214,13 @@ See [Extending GIO][extending-gio]. - + - + @@ -82579,8 +86243,8 @@ See [Extending GIO][extending-gio]. glib:get-type="g_network_address_get_type" glib:type-struct="NetworkAddressClass"> #GNetworkAddress provides an easy way to resolve a hostname and + filename="gio/gnetworkaddress.c" + line="48">`GNetworkAddress` provides an easy way to resolve a hostname and then attempt to connect to that host, handling the possibility of multiple IP addresses and multiple address families. @@ -82588,16 +86252,16 @@ The enumeration results of resolved addresses *may* be cached as long as this object is kept alive which may have unexpected results if alive for too long. -See #GSocketConnectable for an example of using the connectable +See [iface@Gio.SocketConnectable] for an example of using the connectable interface. - + Creates a new #GSocketConnectable for connecting to the given + filename="gio/gnetworkaddress.c" + line="302">Creates a new #GSocketConnectable for connecting to the given @hostname and @port. Note that depending on the configuration of the machine, a @@ -82605,24 +86269,24 @@ Note that depending on the configuration of the machine, a only, or to both IPv4 and IPv6; use g_network_address_new_loopback() to create a #GNetworkAddress that is guaranteed to resolve to both addresses. - + the new #GNetworkAddress + filename="gio/gnetworkaddress.c" + line="316">the new #GNetworkAddress the hostname + filename="gio/gnetworkaddress.c" + line="304">the hostname the port + filename="gio/gnetworkaddress.c" + line="305">the port @@ -82631,8 +86295,8 @@ is guaranteed to resolve to both addresses. c:identifier="g_network_address_new_loopback" version="2.44"> Creates a new #GSocketConnectable for connecting to the local host + filename="gio/gnetworkaddress.c" + line="330">Creates a new #GSocketConnectable for connecting to the local host over a loopback connection to the given @port. This is intended for use in connecting to local services which may be running on IPv4 or IPv6. @@ -82644,18 +86308,18 @@ resolving `localhost`, and an IPv6 address for `localhost6`. g_network_address_get_hostname() will always return `localhost` for a #GNetworkAddress created with this constructor. - + the new #GNetworkAddress + filename="gio/gnetworkaddress.c" + line="347">the new #GNetworkAddress the port + filename="gio/gnetworkaddress.c" + line="332">the port @@ -82665,8 +86329,8 @@ a #GNetworkAddress created with this constructor. version="2.22" throws="1"> Creates a new #GSocketConnectable for connecting to the given + filename="gio/gnetworkaddress.c" + line="369">Creates a new #GSocketConnectable for connecting to the given @hostname and @port. May fail and return %NULL in case parsing @host_and_port fails. @@ -82687,25 +86351,25 @@ and @default_port is expected to be provided by the application. service name rather than as a numeric port, but this functionality is deprecated, because it depends on the contents of /etc/services, which is generally quite sparse on platforms other than Linux.) - + the new + filename="gio/gnetworkaddress.c" + line="397">the new #GNetworkAddress, or %NULL on error the hostname and optionally a port + filename="gio/gnetworkaddress.c" + line="371">the hostname and optionally a port the default port if not in @host_and_port + filename="gio/gnetworkaddress.c" + line="372">the default port if not in @host_and_port @@ -82715,32 +86379,32 @@ which is generally quite sparse on platforms other than Linux.) version="2.26" throws="1"> Creates a new #GSocketConnectable for connecting to the given + filename="gio/gnetworkaddress.c" + line="525">Creates a new #GSocketConnectable for connecting to the given @uri. May fail and return %NULL in case parsing @uri fails. Using this rather than g_network_address_new() or g_network_address_parse() allows #GSocketClient to determine when to use application-specific proxy protocols. - + the new + filename="gio/gnetworkaddress.c" + line="538">the new #GNetworkAddress, or %NULL on error the hostname and optionally a port + filename="gio/gnetworkaddress.c" + line="527">the hostname and optionally a port The default port if none is found in the URI + filename="gio/gnetworkaddress.c" + line="528">The default port if none is found in the URI @@ -82750,21 +86414,21 @@ when to use application-specific proxy protocols. glib:get-property="hostname" version="2.22"> Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, + filename="gio/gnetworkaddress.c" + line="575">Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, depending on what @addr was created with. - + @addr's hostname + filename="gio/gnetworkaddress.c" + line="582">@addr's hostname a #GNetworkAddress + filename="gio/gnetworkaddress.c" + line="577">a #GNetworkAddress @@ -82774,20 +86438,20 @@ depending on what @addr was created with. glib:get-property="port" version="2.22"> Gets @addr's port number - + filename="gio/gnetworkaddress.c" + line="594">Gets @addr's port number + @addr's port (which may be 0) + filename="gio/gnetworkaddress.c" + line="600">@addr's port (which may be 0) a #GNetworkAddress + filename="gio/gnetworkaddress.c" + line="596">a #GNetworkAddress @@ -82797,46 +86461,58 @@ depending on what @addr was created with. glib:get-property="scheme" version="2.26"> Gets @addr's scheme - + filename="gio/gnetworkaddress.c" + line="612">Gets @addr's scheme + @addr's scheme (%NULL if not built from URI) + filename="gio/gnetworkaddress.c" + line="618">@addr's scheme (%NULL if not built from URI) a #GNetworkAddress + filename="gio/gnetworkaddress.c" + line="614">a #GNetworkAddress + Hostname to resolve. + Network port. + URI scheme. @@ -82849,7 +86525,7 @@ depending on what @addr was created with. - + @@ -82858,7 +86534,7 @@ depending on what @addr was created with. c:type="GNetworkAddressPrivate" disguised="1" opaque="1"> - + glib:get-type="g_network_connectivity_get_type" c:type="GNetworkConnectivity"> The host's network connectivity state, as reported by #GNetworkMonitor. + filename="gio/gioenums.h" + line="2086">The host's network connectivity state, as reported by #GNetworkMonitor. The host is not configured with a + filename="gio/gioenums.h" + line="2088">The host is not configured with a route to the Internet; it may or may not be connected to a local network. @@ -82885,8 +86561,8 @@ depending on what @addr was created with. glib:nick="limited" glib:name="G_NETWORK_CONNECTIVITY_LIMITED"> The host is connected to a network, but + filename="gio/gioenums.h" + line="2091">The host is connected to a network, but does not appear to be able to reach the full Internet, perhaps due to upstream network problems. @@ -82896,8 +86572,8 @@ depending on what @addr was created with. glib:nick="portal" glib:name="G_NETWORK_CONNECTIVITY_PORTAL"> The host is behind a captive portal and + filename="gio/gioenums.h" + line="2094">The host is behind a captive portal and cannot reach the full Internet. glib:nick="full" glib:name="G_NETWORK_CONNECTIVITY_FULL"> The host is connected to a network, and + filename="gio/gioenums.h" + line="2096">The host is connected to a network, and appears to be able to reach the full Internet. @@ -82919,26 +86595,26 @@ depending on what @addr was created with. glib:get-type="g_network_monitor_get_type" glib:type-struct="NetworkMonitorInterface"> #GNetworkMonitor provides an easy-to-use cross-platform API + filename="gio/gnetworkmonitor.c" + line="33">`GNetworkMonitor` provides an easy-to-use cross-platform API for monitoring network connectivity. On Linux, the available implementations are based on the kernel's netlink interface and on NetworkManager. There is also an implementation for use inside Flatpak sandboxes. - + Gets the default #GNetworkMonitor for the system. - + filename="gio/gnetworkmonitor.c" + line="74">Gets the default #GNetworkMonitor for the system. + a #GNetworkMonitor, which will be + filename="gio/gnetworkmonitor.c" + line="79">a #GNetworkMonitor, which will be a dummy object if no network monitor is available @@ -82946,10 +86622,11 @@ There is also an implementation for use inside Flatpak sandboxes. + throws="1" + glib:async-func="can_reach_async"> Attempts to determine whether or not the host pointed to by + filename="gio/gnetworkmonitor.c" + line="181">Attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. @@ -82966,24 +86643,24 @@ Note that although this does not attempt to connect to @connectable, it may still block for a brief period of time (eg, trying to do multicast DNS on the local network), so if you do not want to block, you should use g_network_monitor_can_reach_async(). - + %TRUE if @connectable is reachable, %FALSE if not. + filename="gio/gnetworkmonitor.c" + line="206">%TRUE if @connectable is reachable, %FALSE if not. a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="183">a #GNetworkMonitor a #GSocketConnectable + filename="gio/gnetworkmonitor.c" + line="184">a #GSocketConnectable nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gnetworkmonitor.c" + line="185">a #GCancellable, or %NULL - + Asynchronously attempts to determine whether or not the host + filename="gio/gnetworkmonitor.c" + line="242">Asynchronously attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. @@ -83009,21 +86689,21 @@ For more details, see g_network_monitor_can_reach(). When the operation is finished, @callback will be called. You can then call g_network_monitor_can_reach_finish() to get the result of the operation. - + a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="244">a #GNetworkMonitor a #GSocketConnectable + filename="gio/gnetworkmonitor.c" + line="245">a #GSocketConnectable nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gnetworkmonitor.c" + line="246">a #GCancellable, or %NULL scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gnetworkmonitor.c" + line="247">a #GAsyncReadyCallback to call when the request is satisfied @@ -83053,8 +86733,8 @@ to get the result of the operation. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gnetworkmonitor.c" + line="249">the data to pass to callback function @@ -83063,33 +86743,37 @@ to get the result of the operation. invoker="can_reach_finish" throws="1"> Finishes an async network connectivity test. + filename="gio/gnetworkmonitor.c" + line="284">Finishes an async network connectivity test. See g_network_monitor_can_reach_async(). - + %TRUE if network is reachable, %FALSE if not. + filename="gio/gnetworkmonitor.c" + line="293">%TRUE if network is reachable, %FALSE if not. a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="286">a #GNetworkMonitor a #GAsyncResult + filename="gio/gnetworkmonitor.c" + line="287">a #GAsyncResult - + the virtual function pointer for the + GNetworkMonitor::network-changed signal. + @@ -83105,10 +86789,11 @@ See g_network_monitor_can_reach_async(). + throws="1" + glib:async-func="can_reach_async"> Attempts to determine whether or not the host pointed to by + filename="gio/gnetworkmonitor.c" + line="181">Attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. @@ -83125,24 +86810,24 @@ Note that although this does not attempt to connect to @connectable, it may still block for a brief period of time (eg, trying to do multicast DNS on the local network), so if you do not want to block, you should use g_network_monitor_can_reach_async(). - + %TRUE if @connectable is reachable, %FALSE if not. + filename="gio/gnetworkmonitor.c" + line="206">%TRUE if @connectable is reachable, %FALSE if not. a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="183">a #GNetworkMonitor a #GSocketConnectable + filename="gio/gnetworkmonitor.c" + line="184">a #GSocketConnectable nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gnetworkmonitor.c" + line="185">a #GCancellable, or %NULL + c:identifier="g_network_monitor_can_reach_async" + glib:finish-func="can_reach_finish" + glib:sync-func="can_reach"> Asynchronously attempts to determine whether or not the host + filename="gio/gnetworkmonitor.c" + line="242">Asynchronously attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. @@ -83169,21 +86856,21 @@ For more details, see g_network_monitor_can_reach(). When the operation is finished, @callback will be called. You can then call g_network_monitor_can_reach_finish() to get the result of the operation. - + a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="244">a #GNetworkMonitor a #GSocketConnectable + filename="gio/gnetworkmonitor.c" + line="245">a #GSocketConnectable nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gnetworkmonitor.c" + line="246">a #GCancellable, or %NULL scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gnetworkmonitor.c" + line="247">a #GAsyncReadyCallback to call when the request is satisfied @@ -83212,8 +86899,8 @@ to get the result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gnetworkmonitor.c" + line="249">the data to pass to callback function @@ -83222,27 +86909,27 @@ to get the result of the operation. c:identifier="g_network_monitor_can_reach_finish" throws="1"> Finishes an async network connectivity test. + filename="gio/gnetworkmonitor.c" + line="284">Finishes an async network connectivity test. See g_network_monitor_can_reach_async(). - + %TRUE if network is reachable, %FALSE if not. + filename="gio/gnetworkmonitor.c" + line="293">%TRUE if network is reachable, %FALSE if not. a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="286">a #GNetworkMonitor a #GAsyncResult + filename="gio/gnetworkmonitor.c" + line="287">a #GAsyncResult @@ -83252,8 +86939,8 @@ See g_network_monitor_can_reach_async(). glib:get-property="connectivity" version="2.44"> Gets a more detailed networking state than + filename="gio/gnetworkmonitor.c" + line="143">Gets a more detailed networking state than g_network_monitor_get_network_available(). If #GNetworkMonitor:network-available is %FALSE, then the @@ -83272,18 +86959,18 @@ Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and reachable but others are not. In this case, applications can attempt to connect to remote servers, but should gracefully fall back to their "offline" behavior if the connection attempt fails. - + the network connectivity state + filename="gio/gnetworkmonitor.c" + line="167">the network connectivity state the #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="145">the #GNetworkMonitor @@ -83293,23 +86980,23 @@ back to their "offline" behavior if the connection attempt fails. glib:get-property="network-available" version="2.32"> Checks if the network is available. "Available" here means that the + filename="gio/gnetworkmonitor.c" + line="101">Checks if the network is available. "Available" here means that the system has a default route available for at least one of IPv4 or IPv6. It does not necessarily imply that the public Internet is reachable. See #GNetworkMonitor:network-available for more details. - + whether the network is available + filename="gio/gnetworkmonitor.c" + line="110">whether the network is available the #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="103">the #GNetworkMonitor @@ -83319,21 +87006,21 @@ reachable. See #GNetworkMonitor:network-available for more details. glib:get-property="network-metered" version="2.46"> Checks if the network is metered. + filename="gio/gnetworkmonitor.c" + line="123">Checks if the network is metered. See #GNetworkMonitor:network-metered for more details. - + whether the connection is metered + filename="gio/gnetworkmonitor.c" + line="130">whether the connection is metered the #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="125">the #GNetworkMonitor @@ -83344,8 +87031,8 @@ See #GNetworkMonitor:network-metered for more details. getter="get_connectivity" default-value="G_NETWORK_CONNECTIVITY_FULL"> More detailed information about the host's network connectivity. + filename="gio/gnetworkmonitor.c" + line="393">More detailed information about the host's network connectivity. See g_network_monitor_get_connectivity() and #GNetworkConnectivity for more details. @@ -83356,8 +87043,8 @@ See g_network_monitor_get_connectivity() and getter="get_network_available" default-value="FALSE"> Whether the network is considered available. That is, whether the + filename="gio/gnetworkmonitor.c" + line="331">Whether the network is considered available. That is, whether the system has a default route for at least one of IPv4 or IPv6. Real-world networks are of course much more complicated than @@ -83382,8 +87069,8 @@ See also #GNetworkMonitor::network-changed. getter="get_network_metered" default-value="FALSE"> Whether the network is considered metered. + filename="gio/gnetworkmonitor.c" + line="360">Whether the network is considered metered. That is, whether the system has traffic flowing through the default connection that is @@ -83408,16 +87095,16 @@ See also #GNetworkMonitor:network-available. Emitted when the network configuration changes. + filename="gio/gnetworkmonitor.c" + line="312">Emitted when the network configuration changes. the current value of #GNetworkMonitor:network-available + filename="gio/gnetworkmonitor.c" + line="315">the current value of #GNetworkMonitor:network-available @@ -83428,18 +87115,22 @@ See also #GNetworkMonitor:network-available. glib:is-gtype-struct-for="NetworkMonitor" version="2.32"> The virtual function table for #GNetworkMonitor. - + filename="gio/gnetworkmonitor.c" + line="46">The virtual function table for #GNetworkMonitor. + The parent interface. + filename="gio/gnetworkmonitor.c" + line="48">The parent interface. + the virtual function pointer for the + GNetworkMonitor::network-changed signal. - + @@ -83454,25 +87145,28 @@ See also #GNetworkMonitor:network-available. + the virtual function pointer for g_network_monitor_can_reach() - + %TRUE if @connectable is reachable, %FALSE if not. + filename="gio/gnetworkmonitor.c" + line="206">%TRUE if @connectable is reachable, %FALSE if not. a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="183">a #GNetworkMonitor a #GSocketConnectable + filename="gio/gnetworkmonitor.c" + line="184">a #GSocketConnectable nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gnetworkmonitor.c" + line="185">a #GCancellable, or %NULL + the virtual function pointer for + g_network_monitor_can_reach_async() - + a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="244">a #GNetworkMonitor a #GSocketConnectable + filename="gio/gnetworkmonitor.c" + line="245">a #GSocketConnectable nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gnetworkmonitor.c" + line="246">a #GCancellable, or %NULL scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gnetworkmonitor.c" + line="247">a #GAsyncReadyCallback to call when the request is satisfied @@ -83533,33 +87231,37 @@ See also #GNetworkMonitor:network-available. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/gnetworkmonitor.c" + line="249">the data to pass to callback function + the virtual function pointer for + g_network_monitor_can_reach_finish() - + %TRUE if network is reachable, %FALSE if not. + filename="gio/gnetworkmonitor.c" + line="293">%TRUE if network is reachable, %FALSE if not. a #GNetworkMonitor + filename="gio/gnetworkmonitor.c" + line="286">a #GNetworkMonitor a #GAsyncResult + filename="gio/gnetworkmonitor.c" + line="287">a #GAsyncResult @@ -83574,50 +87276,50 @@ See also #GNetworkMonitor:network-available. glib:get-type="g_network_service_get_type" glib:type-struct="NetworkServiceClass"> Like #GNetworkAddress does with hostnames, #GNetworkService + filename="gio/gnetworkservice.c" + line="45">Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService` provides an easy way to resolve a SRV record, and then attempt to connect to one of the hosts that implements that service, handling service priority/weighting, multiple IP addresses, and multiple address families. -See #GSrvTarget for more information about SRV records, and see -#GSocketConnectable for an example of using the connectable +See [struct@Gio.SrvTarget] for more information about SRV records, and see +[iface@Gio.SocketConnectable] for an example of using the connectable interface. - + Creates a new #GNetworkService representing the given @service, + filename="gio/gnetworkservice.c" + line="252">Creates a new #GNetworkService representing the given @service, @protocol, and @domain. This will initially be unresolved; use the #GSocketConnectable interface to resolve it. - + a new #GNetworkService + filename="gio/gnetworkservice.c" + line="262">a new #GNetworkService the service type to look up (eg, "ldap") + filename="gio/gnetworkservice.c" + line="254">the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") + filename="gio/gnetworkservice.c" + line="255">the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in + filename="gio/gnetworkservice.c" + line="256">the DNS domain to look up the service in @@ -83627,21 +87329,21 @@ interface. glib:get-property="domain" version="2.22"> Gets the domain that @srv serves. This might be either UTF-8 or + filename="gio/gnetworkservice.c" + line="314">Gets the domain that @srv serves. This might be either UTF-8 or ASCII-encoded, depending on what @srv was created with. - + @srv's domain name + filename="gio/gnetworkservice.c" + line="321">@srv's domain name a #GNetworkService + filename="gio/gnetworkservice.c" + line="316">a #GNetworkService @@ -83651,20 +87353,20 @@ ASCII-encoded, depending on what @srv was created with. glib:get-property="protocol" version="2.22"> Gets @srv's protocol name (eg, "tcp"). - + filename="gio/gnetworkservice.c" + line="296">Gets @srv's protocol name (eg, "tcp"). + @srv's protocol name + filename="gio/gnetworkservice.c" + line="302">@srv's protocol name a #GNetworkService + filename="gio/gnetworkservice.c" + line="298">a #GNetworkService @@ -83674,21 +87376,21 @@ ASCII-encoded, depending on what @srv was created with. glib:get-property="scheme" version="2.26"> Gets the URI scheme used to resolve proxies. By default, the service name + filename="gio/gnetworkservice.c" + line="333">Gets the URI scheme used to resolve proxies. By default, the service name is used as scheme. - + @srv's scheme name + filename="gio/gnetworkservice.c" + line="340">@srv's scheme name a #GNetworkService + filename="gio/gnetworkservice.c" + line="335">a #GNetworkService @@ -83698,20 +87400,20 @@ is used as scheme. glib:get-property="service" version="2.22"> Gets @srv's service name (eg, "ldap"). - + filename="gio/gnetworkservice.c" + line="278">Gets @srv's service name (eg, "ldap"). + @srv's service name + filename="gio/gnetworkservice.c" + line="284">@srv's service name a #GNetworkService + filename="gio/gnetworkservice.c" + line="280">a #GNetworkService @@ -83721,58 +87423,74 @@ is used as scheme. glib:set-property="scheme" version="2.26"> Set's the URI scheme used to resolve proxies. By default, the service name + filename="gio/gnetworkservice.c" + line="355">Set's the URI scheme used to resolve proxies. By default, the service name is used as scheme. - + a #GNetworkService + filename="gio/gnetworkservice.c" + line="357">a #GNetworkService a URI scheme + filename="gio/gnetworkservice.c" + line="358">a URI scheme + Network domain, for example `example.com`. + Network protocol, for example `tcp`. + Network scheme (default is to use service). + Service name, for example `ldap`. @@ -83785,7 +87503,7 @@ is used as scheme. - + @@ -83794,7 +87512,7 @@ is used as scheme. c:type="GNetworkServicePrivate" disguised="1" opaque="1"> - + glib:type-name="GNotification" glib:get-type="g_notification_get_type"> #GNotification is a mechanism for creating a notification to be shown -to the user -- typically as a pop-up notification presented by the + filename="gio/gnotification.c" + line="30">`GNotification` is a mechanism for creating a notification to be shown +to the user — typically as a pop-up notification presented by the desktop environment shell. -The key difference between #GNotification and other similar APIs is +The key difference between `GNotification` and other similar APIs is that, if supported by the desktop environment, notifications sent -with #GNotification will persist after the application has exited, +with `GNotification` will persist after the application has exited, and even across system reboots. Since the user may click on a notification while the application is -not running, applications using #GNotification should be able to be -started as a D-Bus service, using #GApplication. +not running, applications using `GNotification` should be able to be +started as a D-Bus service, using [class@Gio.Application]. -In order for #GNotification to work, the application must have installed +In order for `GNotification` to work, the application must have installed a `.desktop` file. For example: -|[ - [Desktop Entry] - Name=Test Application - Comment=Description of what Test Application does - Exec=gnome-test-application - Icon=org.gnome.TestApplication - Terminal=false - Type=Application - Categories=GNOME;GTK;TestApplication Category; - StartupNotify=true - DBusActivatable=true - X-GNOME-UsesNotifications=true -]| +``` +[Desktop Entry] +Name=Test Application +Comment=Description of what Test Application does +Exec=gnome-test-application +Icon=org.gnome.TestApplication +Terminal=false +Type=Application +Categories=GNOME;GTK;TestApplication Category; +StartupNotify=true +DBusActivatable=true +X-GNOME-UsesNotifications=true +``` The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel. The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, -where `org.gnome.TestApplication` is the ID passed to g_application_new(). +where `org.gnome.TestApplication` is the ID passed to +[ctor@Gio.Application.new]. User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: -"app." actions). It is not possible to route user interaction +`app.` actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked. -A notification can be sent with g_application_send_notification(). +A notification can be sent with [method@Gio.Application.send_notification]. Creates a new #GNotification with @title as its title. + filename="gio/gnotification.c" + line="161">Creates a new #GNotification with @title as its title. After populating @notification with more details, it can be sent to the desktop shell with g_application_send_notification(). Changing any properties after this call will not have any effect until resending @notification. - + a new #GNotification instance + filename="gio/gnotification.c" + line="172">a new #GNotification instance the title of the notification + filename="gio/gnotification.c" + line="163">the title of the notification @@ -83878,8 +87597,8 @@ resending @notification. c:identifier="g_notification_add_button" version="2.40"> Adds a button to @notification that activates the action in + filename="gio/gnotification.c" + line="407">Adds a button to @notification that activates the action in @detailed_action when clicked. That action must be an application-wide action (starting with "app."). If @detailed_action contains a target, the action will be activated with that target as @@ -83887,27 +87606,27 @@ its parameter. See g_action_parse_detailed_name() for a description of the format for @detailed_action. - + a #GNotification + filename="gio/gnotification.c" + line="409">a #GNotification label of the button + filename="gio/gnotification.c" + line="410">label of the button a detailed action name + filename="gio/gnotification.c" + line="411">a detailed action name @@ -83918,35 +87637,35 @@ for @detailed_action. version="2.40" introspectable="0"> Adds a button to @notification that activates @action when clicked. + filename="gio/gnotification.c" + line="449">Adds a button to @notification that activates @action when clicked. @action must be an application-wide action (it must start with "app."). If @target_format is given, it is used to collect remaining positional parameters into a #GVariant instance, similar to g_variant_new(). @action will be activated with that #GVariant as its parameter. - + a #GNotification + filename="gio/gnotification.c" + line="451">a #GNotification label of the button + filename="gio/gnotification.c" + line="452">label of the button an action name + filename="gio/gnotification.c" + line="453">an action name nullable="1" allow-none="1"> a #GVariant format string, or %NULL + filename="gio/gnotification.c" + line="454">a #GVariant format string, or %NULL positional parameters, as determined by @target_format + filename="gio/gnotification.c" + line="455">positional parameters, as determined by @target_format @@ -83971,33 +87690,33 @@ parameter. shadows="add_button_with_target" version="2.40"> Adds a button to @notification that activates @action when clicked. + filename="gio/gnotification.c" + line="487">Adds a button to @notification that activates @action when clicked. @action must be an application-wide action (it must start with "app."). If @target is non-%NULL, @action will be activated with @target as its parameter. - + a #GNotification + filename="gio/gnotification.c" + line="489">a #GNotification label of the button + filename="gio/gnotification.c" + line="490">label of the button an action name + filename="gio/gnotification.c" + line="491">an action name nullable="1" allow-none="1"> a #GVariant to use as @action's parameter, or %NULL + filename="gio/gnotification.c" + line="492">a #GVariant to use as @action's parameter, or %NULL @@ -84015,17 +87734,17 @@ its parameter. c:identifier="g_notification_set_body" version="2.40"> Sets the body of @notification to @body. - + filename="gio/gnotification.c" + line="246">Sets the body of @notification to @body. + a #GNotification + filename="gio/gnotification.c" + line="248">a #GNotification nullable="1" allow-none="1"> the new body for @notification, or %NULL + filename="gio/gnotification.c" + line="249">the new body for @notification, or %NULL @@ -84043,22 +87762,22 @@ its parameter. c:identifier="g_notification_set_category" version="2.70"> Sets the type of @notification to @category. Categories have a main + filename="gio/gnotification.c" + line="364">Sets the type of @notification to @category. Categories have a main type like `email`, `im` or `device` and can have a detail separated by a `.`, e.g. `im.received` or `email.arrived`. Setting the category helps the notification server to select proper feedback to the user. Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html). - + a #GNotification + filename="gio/gnotification.c" + line="366">a #GNotification the category for @notification, or %NULL for no category + filename="gio/gnotification.c" + line="367">the category for @notification, or %NULL for no category @@ -84076,8 +87795,8 @@ Standard categories are [listed in the specification](https://specifications.fre c:identifier="g_notification_set_default_action" version="2.40"> Sets the default action of @notification to @detailed_action. This + filename="gio/gnotification.c" + line="643">Sets the default action of @notification to @detailed_action. This action is activated when the notification is clicked on. The action in @detailed_action must be an application-wide action (it @@ -84088,21 +87807,21 @@ for @detailed_action. When no default action is set, the application that the notification was sent on is activated. - + a #GNotification + filename="gio/gnotification.c" + line="645">a #GNotification a detailed action name + filename="gio/gnotification.c" + line="646">a detailed action name @@ -84113,8 +87832,8 @@ was sent on is activated. version="2.40" introspectable="0"> Sets the default action of @notification to @action. This action is + filename="gio/gnotification.c" + line="684">Sets the default action of @notification to @action. This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app."). @@ -84125,21 +87844,21 @@ parameter. When no default action is set, the application that the notification was sent on is activated. - + a #GNotification + filename="gio/gnotification.c" + line="686">a #GNotification an action name + filename="gio/gnotification.c" + line="687">an action name nullable="1" allow-none="1"> a #GVariant format string, or %NULL + filename="gio/gnotification.c" + line="688">a #GVariant format string, or %NULL positional parameters, as determined by @target_format + filename="gio/gnotification.c" + line="689">positional parameters, as determined by @target_format @@ -84164,8 +87883,8 @@ was sent on is activated. shadows="set_default_action_and_target" version="2.40"> Sets the default action of @notification to @action. This action is + filename="gio/gnotification.c" + line="724">Sets the default action of @notification to @action. This action is activated when the notification is clicked on. It must be an application-wide action (start with "app."). @@ -84174,21 +87893,21 @@ its parameter. If @target is floating, it will be consumed. When no default action is set, the application that the notification was sent on is activated. - + a #GNotification + filename="gio/gnotification.c" + line="726">a #GNotification an action name + filename="gio/gnotification.c" + line="727">an action name nullable="1" allow-none="1"> a #GVariant to use as @action's parameter, or %NULL + filename="gio/gnotification.c" + line="728">a #GVariant to use as @action's parameter, or %NULL @@ -84206,47 +87925,47 @@ was sent on is activated. c:identifier="g_notification_set_icon" version="2.40"> Sets the icon of @notification to @icon. - + filename="gio/gnotification.c" + line="285">Sets the icon of @notification to @icon. + a #GNotification + filename="gio/gnotification.c" + line="287">a #GNotification the icon to be shown in @notification, as a #GIcon + filename="gio/gnotification.c" + line="288">the icon to be shown in @notification, as a #GIcon Sets the priority of @notification to @priority. See + filename="gio/gnotification.c" + line="390">Sets the priority of @notification to @priority. See #GNotificationPriority for possible values. - + a #GNotification + filename="gio/gnotification.c" + line="392">a #GNotification a #GNotificationPriority + filename="gio/gnotification.c" + line="393">a #GNotificationPriority @@ -84255,23 +87974,23 @@ was sent on is activated. c:identifier="g_notification_set_title" version="2.40"> Sets the title of @notification to @title. - + filename="gio/gnotification.c" + line="207">Sets the title of @notification to @title. + a #GNotification + filename="gio/gnotification.c" + line="209">a #GNotification the new title for @notification + filename="gio/gnotification.c" + line="210">the new title for @notification @@ -84282,25 +88001,25 @@ was sent on is activated. deprecated="1" deprecated-version="2.42"> Deprecated in favor of g_notification_set_priority(). + filename="gio/gnotification.c" + line="322">Deprecated in favor of g_notification_set_priority(). Since 2.42, this has been deprecated in favour of g_notification_set_priority(). - + a #GNotification + filename="gio/gnotification.c" + line="324">a #GNotification %TRUE if @notification is urgent + filename="gio/gnotification.c" + line="325">%TRUE if @notification is urgent @@ -84312,16 +88031,16 @@ was sent on is activated. glib:get-type="g_notification_priority_get_type" c:type="GNotificationPriority"> Priority levels for #GNotifications. + filename="gio/gioenums.h" + line="2060">Priority levels for #GNotifications. the default priority, to be used for the + filename="gio/gioenums.h" + line="2065">the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) @@ -84331,8 +88050,8 @@ was sent on is activated. glib:nick="low" glib:name="G_NOTIFICATION_PRIORITY_LOW"> for notifications that do not require + filename="gio/gioenums.h" + line="2062">for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather @@ -84342,8 +88061,8 @@ was sent on is activated. glib:nick="high" glib:name="G_NOTIFICATION_PRIORITY_HIGH"> for events that require more attention, + filename="gio/gioenums.h" + line="2068">for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) @@ -84353,8 +88072,8 @@ was sent on is activated. glib:nick="urgent" glib:name="G_NOTIFICATION_PRIORITY_URGENT"> for urgent notifications, or notifications + filename="gio/gioenums.h" + line="2071">for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) @@ -84362,7 +88081,7 @@ was sent on is activated. - + @@ -84371,7 +88090,7 @@ was sent on is activated. - + @@ -84380,7 +88099,7 @@ was sent on is activated. - + @@ -84388,44 +88107,44 @@ was sent on is activated. Structure used for scatter/gather data output when sending multiple + filename="gio/giotypes.h" + line="429">Structure used for scatter/gather data output when sending multiple messages or packets in one go. You generally pass in an array of #GOutputVectors and the operation will use all the buffers as if they were one buffer. If @address is %NULL then the message is sent to the default receiver (as previously set by g_socket_connect()). - + a #GSocketAddress, or %NULL + filename="gio/giotypes.h" + line="431">a #GSocketAddress, or %NULL pointer to an array of output vectors + filename="gio/giotypes.h" + line="432">pointer to an array of output vectors the number of output vectors pointed to by @vectors. + filename="gio/giotypes.h" + line="433">the number of output vectors pointed to by @vectors. initialize to 0. Will be set to the number of bytes + filename="gio/giotypes.h" + line="434">initialize to 0. Will be set to the number of bytes that have been sent a pointer + filename="gio/giotypes.h" + line="436">a pointer to an array of #GSocketControlMessages, or %NULL. @@ -84433,8 +88152,8 @@ If @address is %NULL then the message is sent to the default receiver number of elements in @control_messages. + filename="gio/giotypes.h" + line="438">number of elements in @control_messages. @@ -84447,23 +88166,31 @@ If @address is %NULL then the message is sent to the default receiver glib:get-type="g_output_stream_get_type" glib:type-struct="OutputStreamClass"> #GOutputStream has functions to write to a stream (g_output_stream_write()), -to close a stream (g_output_stream_close()) and to flush pending writes -(g_output_stream_flush()). + filename="gio/goutputstream.c" + line="35">`GOutputStream` is a base class for implementing streaming output. + +It has functions to write to a stream ([method@Gio.OutputStream.write]), +to close a stream ([method@Gio.OutputStream.close]) and to flush pending +writes ([method@Gio.OutputStream.flush]). To copy the content of an input stream to an output stream without -manually handling the reads and writes, use g_output_stream_splice(). +manually handling the reads and writes, use [method@Gio.OutputStream.splice]. -See the documentation for #GIOStream for details of thread safety of -streaming APIs. +See the documentation for [class@Gio.IOStream] for details of thread safety +of streaming APIs. -All of these functions have async variants too. - - +All of these functions have async variants too. + +All classes derived from `GOutputStream` *should* implement synchronous +writing, splicing, flushing and closing streams, but *may* implement +asynchronous versions. + + Requests an asynchronous close of the stream, releasing resources + filename="gio/goutputstream.c" + line="2004">Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_output_stream_close_finish() to get the result of the operation. @@ -84473,21 +88200,21 @@ For behaviour details see g_output_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="2006">A #GOutputStream. the io priority of the request. + filename="gio/goutputstream.c" + line="2007">the io priority of the request. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="2008">optional cancellable object scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="2009">a #GAsyncReadyCallback to call when the request is satisfied @@ -84517,40 +88244,40 @@ classes. However, if you override one you must override all. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/goutputstream.c" + line="2011">the data to pass to callback function Closes an output stream. - + filename="gio/goutputstream.c" + line="2108">Closes an output stream. + %TRUE if stream was successfully closed, %FALSE otherwise. + filename="gio/goutputstream.c" + line="2117">%TRUE if stream was successfully closed, %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="2110">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="2111">a #GAsyncResult. - + @@ -84566,10 +88293,13 @@ classes. However, if you override one you must override all. - + Forces a write of all user-space buffered data for the given + filename="gio/goutputstream.c" + line="655">Forces a write of all user-space buffered data for the given @stream. Will block during the operation. Closing the stream will implicitly cause a flush. @@ -84578,18 +88308,18 @@ This function is optional for inherited classes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on success, %FALSE on error + filename="gio/goutputstream.c" + line="671">%TRUE on success, %FALSE on error a #GOutputStream. + filename="gio/goutputstream.c" + line="657">a #GOutputStream. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="658">optional cancellable object - + Forces an asynchronous write of all user-space buffered data for + filename="gio/goutputstream.c" + line="1844">Forces an asynchronous write of all user-space buffered data for the given @stream. For behaviour details see g_output_stream_flush(). When the operation is finished @callback will be called. You can then call g_output_stream_flush_finish() to get the result of the operation. - + a #GOutputStream. + filename="gio/goutputstream.c" + line="1846">a #GOutputStream. the io priority of the request. + filename="gio/goutputstream.c" + line="1847">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1848">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1849">a #GAsyncReadyCallback to call when the request is satisfied @@ -84657,47 +88390,50 @@ result of the operation. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1851">the data to pass to callback function Finishes flushing an output stream. - + filename="gio/goutputstream.c" + line="1899">Finishes flushing an output stream. + %TRUE if flush operation succeeded, %FALSE otherwise. + filename="gio/goutputstream.c" + line="1908">%TRUE if flush operation succeeded, %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="1901">a #GOutputStream. a GAsyncResult. + filename="gio/goutputstream.c" + line="1902">a GAsyncResult. - + Splices an input stream into an output stream. - + filename="gio/goutputstream.c" + line="705">Splices an input stream into an output stream. + a #gssize containing the size of the data spliced, or + filename="gio/goutputstream.c" + line="716">a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number @@ -84707,20 +88443,20 @@ result of the operation. a #GOutputStream. + filename="gio/goutputstream.c" + line="707">a #GOutputStream. a #GInputStream. + filename="gio/goutputstream.c" + line="708">a #GInputStream. a set of #GOutputStreamSpliceFlags. + filename="gio/goutputstream.c" + line="709">a set of #GOutputStreamSpliceFlags. @@ -84729,50 +88465,53 @@ result of the operation. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="710">optional #GCancellable object, %NULL to ignore. - + Splices a stream asynchronously. + filename="gio/goutputstream.c" + line="1725">Splices a stream asynchronously. When the operation is finished @callback will be called. You can then call g_output_stream_splice_finish() to get the result of the operation. For the synchronous, blocking version of this function, see g_output_stream_splice(). - + a #GOutputStream. + filename="gio/goutputstream.c" + line="1727">a #GOutputStream. a #GInputStream. + filename="gio/goutputstream.c" + line="1728">a #GInputStream. a set of #GOutputStreamSpliceFlags. + filename="gio/goutputstream.c" + line="1729">a set of #GOutputStreamSpliceFlags. the io priority of the request. + filename="gio/goutputstream.c" + line="1730">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1731">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1732">a #GAsyncReadyCallback to call when the request is satisfied @@ -84802,21 +88541,21 @@ g_output_stream_splice(). allow-none="1" closure="5"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1734">the data to pass to callback function Finishes an asynchronous stream splice operation. - + filename="gio/goutputstream.c" + line="1787">Finishes an asynchronous stream splice operation. + a #gssize of the number of bytes spliced. Note that if the + filename="gio/goutputstream.c" + line="1796">a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. @@ -84825,22 +88564,24 @@ g_output_stream_splice(). a #GOutputStream. + filename="gio/goutputstream.c" + line="1789">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1790">a #GAsyncResult. - + Request an asynchronous write of @count bytes from @buffer into + filename="gio/goutputstream.c" + line="975">Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_finish() to get the result of the operation. @@ -84875,15 +88616,15 @@ Note that no copy of @buffer will be made, so it must stay valid until @callback is called. See g_output_stream_write_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="977">A #GOutputStream. nullable="1" allow-none="1"> the buffer containing the data to write. + filename="gio/goutputstream.c" + line="978">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="979">the number of bytes to write the io priority of the request. + filename="gio/goutputstream.c" + line="980">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="981">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="982">a #GAsyncReadyCallback to call when the request is satisfied @@ -84936,42 +88677,42 @@ the contents (without copying) for the duration of the call. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/goutputstream.c" + line="984">the data to pass to callback function Finishes a stream write operation. - + filename="gio/goutputstream.c" + line="1071">Finishes a stream write operation. + a #gssize containing the number of bytes written to the stream. + filename="gio/goutputstream.c" + line="1080">a #gssize containing the number of bytes written to the stream. a #GOutputStream. + filename="gio/goutputstream.c" + line="1073">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1074">a #GAsyncResult. Tries to write @count bytes from @buffer into the stream. Will block + filename="gio/goutputstream.c" + line="177">Tries to write @count bytes from @buffer into the stream. Will block during the operation. If count is 0, returns 0 and does nothing. A value of @count @@ -84991,18 +88732,18 @@ operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and @error is set accordingly. - + Number of bytes written, or -1 on error + filename="gio/goutputstream.c" + line="206">Number of bytes written, or -1 on error a #GOutputStream. + filename="gio/goutputstream.c" + line="179">a #GOutputStream. nullable="1" allow-none="1"> the buffer containing the data to write. + filename="gio/goutputstream.c" + line="180">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="181">the number of bytes to write nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="182">optional cancellable object + version="2.60" + glib:finish-func="writev_finish"> Request an asynchronous write of the bytes contained in @n_vectors @vectors into + filename="gio/goutputstream.c" + line="1281">Request an asynchronous write of the bytes contained in @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_finish() to get the result of the operation. @@ -85068,21 +88810,21 @@ g_output_stream_writev(). Note that no copy of @vectors will be made, so it must stay valid until @callback is called. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="1283">A #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="1284">the buffer containing the #GOutputVectors to write. @@ -85091,14 +88833,14 @@ until @callback is called. the number of vectors to write + filename="gio/goutputstream.c" + line="1285">the number of vectors to write the I/O priority of the request. + filename="gio/goutputstream.c" + line="1286">the I/O priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1287">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1288">a #GAsyncReadyCallback to call when the request is satisfied @@ -85128,8 +88870,8 @@ until @callback is called. allow-none="1" closure="5"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1290">the data to pass to callback function @@ -85139,26 +88881,26 @@ until @callback is called. version="2.60" throws="1"> Finishes a stream writev operation. - + filename="gio/goutputstream.c" + line="1347">Finishes a stream writev operation. + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="1357">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="1349">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1350">a #GAsyncResult. optional="1" allow-none="1"> location to store the number of bytes that were written to the stream + filename="gio/goutputstream.c" + line="1351">location to store the number of bytes that were written to the stream @@ -85179,8 +88921,8 @@ until @callback is called. version="2.60" throws="1"> Tries to write the bytes contained in the @n_vectors @vectors into the + filename="gio/goutputstream.c" + line="324">Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and @@ -85203,24 +88945,24 @@ Some implementations of g_output_stream_writev() may have limitations on the aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these are exceeded. For example, when writing to a local file on UNIX platforms, the aggregate buffer size must not exceed %G_MAXSSIZE bytes. - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="358">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="326">a #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="327">the buffer containing the #GOutputVectors to write. @@ -85229,8 +88971,8 @@ the aggregate buffer size must not exceed %G_MAXSSIZE bytes. the number of vectors to write + filename="gio/goutputstream.c" + line="328">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/goutputstream.c" + line="329">location to store the number of bytes that were written to the stream @@ -85250,8 +88992,8 @@ the aggregate buffer size must not exceed %G_MAXSSIZE bytes. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="331">optional cancellable object @@ -85259,25 +89001,28 @@ the aggregate buffer size must not exceed %G_MAXSSIZE bytes. Clears the pending flag on @stream. - + filename="gio/goutputstream.c" + line="2226">Clears the pending flag on @stream. + output stream + filename="gio/goutputstream.c" + line="2228">output stream - + Closes the stream, releasing resources related to it. + filename="gio/goutputstream.c" + line="887">Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. @@ -85306,18 +89051,18 @@ Cancelling a close will still leave the stream closed, but there some streams can use a faster close that doesn't block to e.g. check errors. On cancellation (as with any error) there is no guarantee that all written data will reach the target. - + %TRUE on success, %FALSE on failure + filename="gio/goutputstream.c" + line="923">%TRUE on success, %FALSE on failure A #GOutputStream. + filename="gio/goutputstream.c" + line="889">A #GOutputStream. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="890">optional cancellable object - + Requests an asynchronous close of the stream, releasing resources + filename="gio/goutputstream.c" + line="2004">Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_output_stream_close_finish() to get the result of the operation. @@ -85344,21 +89092,21 @@ For behaviour details see g_output_stream_close(). The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="2006">A #GOutputStream. the io priority of the request. + filename="gio/goutputstream.c" + line="2007">the io priority of the request. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="2008">optional cancellable object scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="2009">a #GAsyncReadyCallback to call when the request is satisfied @@ -85387,8 +89135,8 @@ classes. However, if you override one you must override all. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="2011">the data to pass to callback function @@ -85397,34 +89145,37 @@ classes. However, if you override one you must override all. c:identifier="g_output_stream_close_finish" throws="1"> Closes an output stream. - + filename="gio/goutputstream.c" + line="2108">Closes an output stream. + %TRUE if stream was successfully closed, %FALSE otherwise. + filename="gio/goutputstream.c" + line="2117">%TRUE if stream was successfully closed, %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="2110">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="2111">a #GAsyncResult. - + Forces a write of all user-space buffered data for the given + filename="gio/goutputstream.c" + line="655">Forces a write of all user-space buffered data for the given @stream. Will block during the operation. Closing the stream will implicitly cause a flush. @@ -85433,18 +89184,18 @@ This function is optional for inherited classes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE on success, %FALSE on error + filename="gio/goutputstream.c" + line="671">%TRUE on success, %FALSE on error a #GOutputStream. + filename="gio/goutputstream.c" + line="657">a #GOutputStream. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="658">optional cancellable object - + Forces an asynchronous write of all user-space buffered data for + filename="gio/goutputstream.c" + line="1844">Forces an asynchronous write of all user-space buffered data for the given @stream. For behaviour details see g_output_stream_flush(). When the operation is finished @callback will be called. You can then call g_output_stream_flush_finish() to get the result of the operation. - + a #GOutputStream. + filename="gio/goutputstream.c" + line="1846">a #GOutputStream. the io priority of the request. + filename="gio/goutputstream.c" + line="1847">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1848">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1849">a #GAsyncReadyCallback to call when the request is satisfied @@ -85511,8 +89265,8 @@ result of the operation. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1851">the data to pass to callback function @@ -85521,66 +89275,66 @@ result of the operation. c:identifier="g_output_stream_flush_finish" throws="1"> Finishes flushing an output stream. - + filename="gio/goutputstream.c" + line="1899">Finishes flushing an output stream. + %TRUE if flush operation succeeded, %FALSE otherwise. + filename="gio/goutputstream.c" + line="1908">%TRUE if flush operation succeeded, %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="1901">a #GOutputStream. a GAsyncResult. + filename="gio/goutputstream.c" + line="1902">a GAsyncResult. Checks if an output stream has pending actions. - + filename="gio/goutputstream.c" + line="2171">Checks if an output stream has pending actions. + %TRUE if @stream has pending actions. + filename="gio/goutputstream.c" + line="2177">%TRUE if @stream has pending actions. a #GOutputStream. + filename="gio/goutputstream.c" + line="2173">a #GOutputStream. Checks if an output stream has already been closed. - + filename="gio/goutputstream.c" + line="2134">Checks if an output stream has already been closed. + %TRUE if @stream is closed. %FALSE otherwise. + filename="gio/goutputstream.c" + line="2140">%TRUE if @stream is closed. %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="2136">a #GOutputStream. @@ -85589,23 +89343,23 @@ result of the operation. c:identifier="g_output_stream_is_closing" version="2.24"> Checks if an output stream is being closed. This can be + filename="gio/goutputstream.c" + line="2150">Checks if an output stream is being closed. This can be used inside e.g. a flush implementation to see if the flush (or other i/o operation) is called from within the closing operation. - + %TRUE if @stream is being closed. %FALSE otherwise. + filename="gio/goutputstream.c" + line="2159">%TRUE if @stream is being closed. %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="2152">a #GOutputStream. @@ -85615,8 +89369,8 @@ the closing operation. version="2.40" introspectable="0"> This is a utility function around g_output_stream_write_all(). It + filename="gio/goutputstream.c" + line="519">This is a utility function around g_output_stream_write_all(). It uses g_strdup_vprintf() to turn @format and @... into a string that is then written to @stream. @@ -85628,18 +89382,18 @@ function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own printf()-like wrapper around g_output_stream_write() or g_output_stream_write_all(). - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="544">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="521">a #GOutputStream. optional="1" allow-none="1"> location to store the number of bytes that was + filename="gio/goutputstream.c" + line="522">location to store the number of bytes that was written to the stream @@ -85659,26 +89413,26 @@ or g_output_stream_write_all(). nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="524">optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore + filename="gio/goutputstream.c" + line="525">location to store the error occurring, or %NULL to ignore the format string. See the printf() documentation + filename="gio/goutputstream.c" + line="526">the format string. See the printf() documentation the parameters to insert into the format string + filename="gio/goutputstream.c" + line="527">the parameters to insert into the format string @@ -85687,35 +89441,38 @@ or g_output_stream_write_all(). c:identifier="g_output_stream_set_pending" throws="1"> Sets @stream to have actions pending. If the pending flag is + filename="gio/goutputstream.c" + line="2187">Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. - + %TRUE if pending was previously unset and is now set. + filename="gio/goutputstream.c" + line="2197">%TRUE if pending was previously unset and is now set. a #GOutputStream. + filename="gio/goutputstream.c" + line="2189">a #GOutputStream. - + Splices an input stream into an output stream. - + filename="gio/goutputstream.c" + line="705">Splices an input stream into an output stream. + a #gssize containing the size of the data spliced, or + filename="gio/goutputstream.c" + line="716">a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number @@ -85725,20 +89482,20 @@ already set or @stream is closed, it will return %FALSE and set a #GOutputStream. + filename="gio/goutputstream.c" + line="707">a #GOutputStream. a #GInputStream. + filename="gio/goutputstream.c" + line="708">a #GInputStream. a set of #GOutputStreamSpliceFlags. + filename="gio/goutputstream.c" + line="709">a set of #GOutputStreamSpliceFlags. @@ -85747,50 +89504,53 @@ already set or @stream is closed, it will return %FALSE and set nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="710">optional #GCancellable object, %NULL to ignore. - + Splices a stream asynchronously. + filename="gio/goutputstream.c" + line="1725">Splices a stream asynchronously. When the operation is finished @callback will be called. You can then call g_output_stream_splice_finish() to get the result of the operation. For the synchronous, blocking version of this function, see g_output_stream_splice(). - + a #GOutputStream. + filename="gio/goutputstream.c" + line="1727">a #GOutputStream. a #GInputStream. + filename="gio/goutputstream.c" + line="1728">a #GInputStream. a set of #GOutputStreamSpliceFlags. + filename="gio/goutputstream.c" + line="1729">a set of #GOutputStreamSpliceFlags. the io priority of the request. + filename="gio/goutputstream.c" + line="1730">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1731">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1732">a #GAsyncReadyCallback to call when the request is satisfied @@ -85819,8 +89579,8 @@ g_output_stream_splice(). nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1734">the data to pass to callback function @@ -85829,13 +89589,13 @@ g_output_stream_splice(). c:identifier="g_output_stream_splice_finish" throws="1"> Finishes an asynchronous stream splice operation. - + filename="gio/goutputstream.c" + line="1787">Finishes an asynchronous stream splice operation. + a #gssize of the number of bytes spliced. Note that if the + filename="gio/goutputstream.c" + line="1796">a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. @@ -85844,14 +89604,14 @@ g_output_stream_splice(). a #GOutputStream. + filename="gio/goutputstream.c" + line="1789">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1790">a #GAsyncResult. @@ -85861,8 +89621,8 @@ g_output_stream_splice(). version="2.40" introspectable="0"> This is a utility function around g_output_stream_write_all(). It + filename="gio/goutputstream.c" + line="565">This is a utility function around g_output_stream_write_all(). It uses g_strdup_vprintf() to turn @format and @args into a string that is then written to @stream. @@ -85874,18 +89634,18 @@ function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own printf()-like wrapper around g_output_stream_write() or g_output_stream_write_all(). - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="590">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="567">a #GOutputStream. optional="1" allow-none="1"> location to store the number of bytes that was + filename="gio/goutputstream.c" + line="568">location to store the number of bytes that was written to the stream @@ -85905,34 +89665,37 @@ or g_output_stream_write_all(). nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="570">optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore + filename="gio/goutputstream.c" + line="571">location to store the error occurring, or %NULL to ignore the format string. See the printf() documentation + filename="gio/goutputstream.c" + line="572">the format string. See the printf() documentation the parameters to insert into the format string + filename="gio/goutputstream.c" + line="573">the parameters to insert into the format string - + Tries to write @count bytes from @buffer into the stream. Will block + filename="gio/goutputstream.c" + line="177">Tries to write @count bytes from @buffer into the stream. Will block during the operation. If count is 0, returns 0 and does nothing. A value of @count @@ -85952,32 +89715,32 @@ operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and @error is set accordingly. - + Number of bytes written, or -1 on error + filename="gio/goutputstream.c" + line="206">Number of bytes written, or -1 on error a #GOutputStream. + filename="gio/goutputstream.c" + line="179">a #GOutputStream. the buffer containing the data to write. + filename="gio/goutputstream.c" + line="180">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="181">the number of bytes to write nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="182">optional cancellable object + throws="1" + glib:async-func="write_all_async"> Tries to write @count bytes from @buffer into the stream. Will block + filename="gio/goutputstream.c" + line="256">Tries to write @count bytes from @buffer into the stream. Will block during the operation. This function is similar to g_output_stream_write(), except it tries to @@ -86015,32 +89779,32 @@ successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write(). - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="286">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="258">a #GOutputStream. the buffer containing the data to write. + filename="gio/goutputstream.c" + line="259">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="260">the number of bytes to write optional="1" allow-none="1"> location to store the number of bytes that was + filename="gio/goutputstream.c" + line="261">location to store the number of bytes that was written to the stream @@ -86060,18 +89824,20 @@ g_output_stream_write(). nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="263">optional #GCancellable object, %NULL to ignore. + version="2.44" + glib:finish-func="write_all_finish" + glib:sync-func="write_all"> Request an asynchronous write of @count bytes from @buffer into + filename="gio/goutputstream.c" + line="1170">Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_all_finish() to get the result of the operation. @@ -86086,35 +89852,35 @@ priority. Default priority is %G_PRIORITY_DEFAULT. Note that no copy of @buffer will be made, so it must stay valid until @callback is called. - + A #GOutputStream + filename="gio/goutputstream.c" + line="1172">A #GOutputStream the buffer containing the data to write + filename="gio/goutputstream.c" + line="1173">the buffer containing the data to write the number of bytes to write + filename="gio/goutputstream.c" + line="1174">the number of bytes to write the io priority of the request + filename="gio/goutputstream.c" + line="1175">the io priority of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/goutputstream.c" + line="1176">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1177">a #GAsyncReadyCallback to call when the request is satisfied @@ -86143,8 +89909,8 @@ until @callback is called. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1179">the data to pass to callback function @@ -86154,8 +89920,8 @@ until @callback is called. version="2.44" throws="1"> Finishes an asynchronous stream write operation started with + filename="gio/goutputstream.c" + line="1236">Finishes an asynchronous stream write operation started with g_output_stream_write_all_async(). As a special exception to the normal conventions for functions that @@ -86165,24 +89931,24 @@ successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write_async(). - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="1254">%TRUE on success, %FALSE if there was an error a #GOutputStream + filename="gio/goutputstream.c" + line="1238">a #GOutputStream a #GAsyncResult + filename="gio/goutputstream.c" + line="1239">a #GAsyncResult optional="1" allow-none="1"> location to store the number of bytes that was written to the stream + filename="gio/goutputstream.c" + line="1240">location to store the number of bytes that was written to the stream - + Request an asynchronous write of @count bytes from @buffer into + filename="gio/goutputstream.c" + line="975">Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_finish() to get the result of the operation. @@ -86236,35 +90005,35 @@ Note that no copy of @buffer will be made, so it must stay valid until @callback is called. See g_output_stream_write_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="977">A #GOutputStream. the buffer containing the data to write. + filename="gio/goutputstream.c" + line="978">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="979">the number of bytes to write the io priority of the request. + filename="gio/goutputstream.c" + line="980">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="981">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="982">a #GAsyncReadyCallback to call when the request is satisfied @@ -86293,18 +90062,19 @@ the contents (without copying) for the duration of the call. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="984">the data to pass to callback function + throws="1" + glib:async-func="write_bytes_async"> A wrapper function for g_output_stream_write() which takes a + filename="gio/goutputstream.c" + line="617">A wrapper function for g_output_stream_write() which takes a #GBytes as input. This can be more convenient for use by language bindings or in other cases where the refcounted nature of #GBytes is helpful over a bare pointer interface. @@ -86315,24 +90085,24 @@ writing, you will need to create a new #GBytes containing just the remaining bytes, using g_bytes_new_from_bytes(). Passing the same #GBytes instance multiple times potentially can result in duplicated data in the output stream. - + Number of bytes written, or -1 on error + filename="gio/goutputstream.c" + line="636">Number of bytes written, or -1 on error a #GOutputStream. + filename="gio/goutputstream.c" + line="619">a #GOutputStream. the #GBytes to write + filename="gio/goutputstream.c" + line="620">the #GBytes to write nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="621">optional cancellable object + c:identifier="g_output_stream_write_bytes_async" + glib:finish-func="write_bytes_finish" + glib:sync-func="write_bytes"> This function is similar to g_output_stream_write_async(), but + filename="gio/goutputstream.c" + line="1624">This function is similar to g_output_stream_write_async(), but takes a #GBytes as input. Due to the refcounted nature of #GBytes, this allows the stream to avoid taking a copy of the data. @@ -86363,27 +90135,27 @@ data in the output stream. For the synchronous, blocking version of this function, see g_output_stream_write_bytes(). - + A #GOutputStream. + filename="gio/goutputstream.c" + line="1626">A #GOutputStream. The bytes to write + filename="gio/goutputstream.c" + line="1627">The bytes to write the io priority of the request. + filename="gio/goutputstream.c" + line="1628">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1629">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1630">a #GAsyncReadyCallback to call when the request is satisfied @@ -86412,8 +90184,8 @@ g_output_stream_write_bytes(). nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1632">the data to pass to callback function @@ -86422,26 +90194,26 @@ g_output_stream_write_bytes(). c:identifier="g_output_stream_write_bytes_finish" throws="1"> Finishes a stream write-from-#GBytes operation. - + filename="gio/goutputstream.c" + line="1675">Finishes a stream write-from-#GBytes operation. + a #gssize containing the number of bytes written to the stream. + filename="gio/goutputstream.c" + line="1684">a #gssize containing the number of bytes written to the stream. a #GOutputStream. + filename="gio/goutputstream.c" + line="1677">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1678">a #GAsyncResult. @@ -86450,26 +90222,26 @@ g_output_stream_write_bytes(). c:identifier="g_output_stream_write_finish" throws="1"> Finishes a stream write operation. - + filename="gio/goutputstream.c" + line="1071">Finishes a stream write operation. + a #gssize containing the number of bytes written to the stream. + filename="gio/goutputstream.c" + line="1080">a #gssize containing the number of bytes written to the stream. a #GOutputStream. + filename="gio/goutputstream.c" + line="1073">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1074">a #GAsyncResult. @@ -86477,10 +90249,11 @@ g_output_stream_write_bytes(). + throws="1" + glib:async-func="writev_async"> Tries to write the bytes contained in the @n_vectors @vectors into the + filename="gio/goutputstream.c" + line="324">Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and @@ -86503,24 +90276,24 @@ Some implementations of g_output_stream_writev() may have limitations on the aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these are exceeded. For example, when writing to a local file on UNIX platforms, the aggregate buffer size must not exceed %G_MAXSSIZE bytes. - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="358">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="326">a #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="327">the buffer containing the #GOutputVectors to write. @@ -86529,8 +90302,8 @@ the aggregate buffer size must not exceed %G_MAXSSIZE bytes. the number of vectors to write + filename="gio/goutputstream.c" + line="328">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/goutputstream.c" + line="329">location to store the number of bytes that were written to the stream @@ -86550,8 +90323,8 @@ the aggregate buffer size must not exceed %G_MAXSSIZE bytes. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="331">optional cancellable object @@ -86559,10 +90332,11 @@ the aggregate buffer size must not exceed %G_MAXSSIZE bytes. + throws="1" + glib:async-func="writev_all_async"> Tries to write the bytes contained in the @n_vectors @vectors into the + filename="gio/goutputstream.c" + line="411">Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. This function is similar to g_output_stream_writev(), except it tries to @@ -86584,32 +90358,32 @@ g_output_stream_write(). The content of the individual elements of @vectors might be changed by this function. - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="444">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="413">a #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="414">the buffer containing the #GOutputVectors to write. the number of vectors to write + filename="gio/goutputstream.c" + line="415">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/goutputstream.c" + line="416">location to store the number of bytes that were written to the stream @@ -86629,18 +90403,20 @@ function. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="418">optional #GCancellable object, %NULL to ignore. + version="2.60" + glib:finish-func="writev_all_finish" + glib:sync-func="writev_all"> Request an asynchronous write of the bytes contained in the @n_vectors @vectors into + filename="gio/goutputstream.c" + line="1476">Request an asynchronous write of the bytes contained in the @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_all_finish() to get the result of the operation. @@ -86656,35 +90432,35 @@ priority. Default priority is %G_PRIORITY_DEFAULT. Note that no copy of @vectors will be made, so it must stay valid until @callback is called. The content of the individual elements of @vectors might be changed by this function. - + A #GOutputStream + filename="gio/goutputstream.c" + line="1478">A #GOutputStream the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="1479">the buffer containing the #GOutputVectors to write. the number of vectors to write + filename="gio/goutputstream.c" + line="1480">the number of vectors to write the I/O priority of the request + filename="gio/goutputstream.c" + line="1481">the I/O priority of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/goutputstream.c" + line="1482">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1483">a #GAsyncReadyCallback to call when the request is satisfied @@ -86713,8 +90489,8 @@ of @vectors might be changed by this function. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1485">the data to pass to callback function @@ -86724,8 +90500,8 @@ of @vectors might be changed by this function. version="2.60" throws="1"> Finishes an asynchronous stream write operation started with + filename="gio/goutputstream.c" + line="1560">Finishes an asynchronous stream write operation started with g_output_stream_writev_all_async(). As a special exception to the normal conventions for functions that @@ -86735,24 +90511,24 @@ successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_writev_async(). - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="1578">%TRUE on success, %FALSE if there was an error a #GOutputStream + filename="gio/goutputstream.c" + line="1562">a #GOutputStream a #GAsyncResult + filename="gio/goutputstream.c" + line="1563">a #GAsyncResult optional="1" allow-none="1"> location to store the number of bytes that were written to the stream + filename="gio/goutputstream.c" + line="1564">location to store the number of bytes that were written to the stream + version="2.60" + glib:finish-func="writev_finish" + glib:sync-func="writev"> Request an asynchronous write of the bytes contained in @n_vectors @vectors into + filename="gio/goutputstream.c" + line="1281">Request an asynchronous write of the bytes contained in @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_finish() to get the result of the operation. @@ -86803,21 +90581,21 @@ g_output_stream_writev(). Note that no copy of @vectors will be made, so it must stay valid until @callback is called. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="1283">A #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="1284">the buffer containing the #GOutputVectors to write. @@ -86826,14 +90604,14 @@ until @callback is called. the number of vectors to write + filename="gio/goutputstream.c" + line="1285">the number of vectors to write the I/O priority of the request. + filename="gio/goutputstream.c" + line="1286">the I/O priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1287">optional #GCancellable object, %NULL to ignore. scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1288">a #GAsyncReadyCallback to call when the request is satisfied @@ -86862,8 +90640,8 @@ until @callback is called. nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1290">the data to pass to callback function @@ -86873,26 +90651,26 @@ until @callback is called. version="2.60" throws="1"> Finishes a stream writev operation. - + filename="gio/goutputstream.c" + line="1347">Finishes a stream writev operation. + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="1357">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="1349">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1350">a #GAsyncResult. optional="1" allow-none="1"> location to store the number of bytes that were written to the stream + filename="gio/goutputstream.c" + line="1351">location to store the number of bytes that were written to the stream @@ -86918,24 +90696,24 @@ until @callback is called. - + - + Number of bytes written, or -1 on error + filename="gio/goutputstream.c" + line="206">Number of bytes written, or -1 on error a #GOutputStream. + filename="gio/goutputstream.c" + line="179">a #GOutputStream. nullable="1" allow-none="1"> the buffer containing the data to write. + filename="gio/goutputstream.c" + line="180">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="181">the number of bytes to write nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="182">optional cancellable object @@ -86969,11 +90747,11 @@ until @callback is called. - + a #gssize containing the size of the data spliced, or + filename="gio/goutputstream.c" + line="716">a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number @@ -86983,20 +90761,20 @@ until @callback is called. a #GOutputStream. + filename="gio/goutputstream.c" + line="707">a #GOutputStream. a #GInputStream. + filename="gio/goutputstream.c" + line="708">a #GInputStream. a set of #GOutputStreamSpliceFlags. + filename="gio/goutputstream.c" + line="709">a set of #GOutputStreamSpliceFlags. @@ -87005,8 +90783,8 @@ until @callback is called. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="710">optional #GCancellable object, %NULL to ignore. @@ -87014,18 +90792,18 @@ until @callback is called. - + %TRUE on success, %FALSE on error + filename="gio/goutputstream.c" + line="671">%TRUE on success, %FALSE on error a #GOutputStream. + filename="gio/goutputstream.c" + line="657">a #GOutputStream. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="658">optional cancellable object @@ -87042,7 +90820,7 @@ until @callback is called. - + @@ -87061,15 +90839,15 @@ until @callback is called. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="977">A #GOutputStream. nullable="1" allow-none="1"> the buffer containing the data to write. + filename="gio/goutputstream.c" + line="978">the buffer containing the data to write. the number of bytes to write + filename="gio/goutputstream.c" + line="979">the number of bytes to write the io priority of the request. + filename="gio/goutputstream.c" + line="980">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="981">optional #GCancellable object, %NULL to ignore. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="982">a #GAsyncReadyCallback to call when the request is satisfied @@ -87122,8 +90900,8 @@ until @callback is called. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/goutputstream.c" + line="984">the data to pass to callback function @@ -87131,24 +90909,24 @@ until @callback is called. - + a #gssize containing the number of bytes written to the stream. + filename="gio/goutputstream.c" + line="1080">a #gssize containing the number of bytes written to the stream. a #GOutputStream. + filename="gio/goutputstream.c" + line="1073">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1074">a #GAsyncResult. @@ -87156,34 +90934,34 @@ until @callback is called. - + a #GOutputStream. + filename="gio/goutputstream.c" + line="1727">a #GOutputStream. a #GInputStream. + filename="gio/goutputstream.c" + line="1728">a #GInputStream. a set of #GOutputStreamSpliceFlags. + filename="gio/goutputstream.c" + line="1729">a set of #GOutputStreamSpliceFlags. the io priority of the request. + filename="gio/goutputstream.c" + line="1730">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1731">optional #GCancellable object, %NULL to ignore. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1732">a #GAsyncReadyCallback to call when the request is satisfied @@ -87213,8 +90991,8 @@ until @callback is called. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1734">the data to pass to callback function @@ -87222,11 +91000,11 @@ until @callback is called. - + a #gssize of the number of bytes spliced. Note that if the + filename="gio/goutputstream.c" + line="1796">a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. @@ -87235,14 +91013,14 @@ until @callback is called. a #GOutputStream. + filename="gio/goutputstream.c" + line="1789">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1790">a #GAsyncResult. @@ -87250,21 +91028,21 @@ until @callback is called. - + a #GOutputStream. + filename="gio/goutputstream.c" + line="1846">a #GOutputStream. the io priority of the request. + filename="gio/goutputstream.c" + line="1847">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1848">optional #GCancellable object, %NULL to ignore. scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1849">a #GAsyncReadyCallback to call when the request is satisfied @@ -87294,8 +91072,8 @@ until @callback is called. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1851">the data to pass to callback function @@ -87303,24 +91081,24 @@ until @callback is called. - + %TRUE if flush operation succeeded, %FALSE otherwise. + filename="gio/goutputstream.c" + line="1908">%TRUE if flush operation succeeded, %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="1901">a #GOutputStream. a GAsyncResult. + filename="gio/goutputstream.c" + line="1902">a GAsyncResult. @@ -87328,21 +91106,21 @@ until @callback is called. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="2006">A #GOutputStream. the io priority of the request. + filename="gio/goutputstream.c" + line="2007">the io priority of the request. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="2008">optional cancellable object scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="2009">a #GAsyncReadyCallback to call when the request is satisfied @@ -87372,8 +91150,8 @@ until @callback is called. allow-none="1" closure="4"> the data to pass to callback function + filename="gio/goutputstream.c" + line="2011">the data to pass to callback function @@ -87381,24 +91159,24 @@ until @callback is called. - + %TRUE if stream was successfully closed, %FALSE otherwise. + filename="gio/goutputstream.c" + line="2117">%TRUE if stream was successfully closed, %FALSE otherwise. a #GOutputStream. + filename="gio/goutputstream.c" + line="2110">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="2111">a #GAsyncResult. @@ -87406,24 +91184,24 @@ until @callback is called. - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="358">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="326">a #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="327">the buffer containing the #GOutputVectors to write. @@ -87432,8 +91210,8 @@ until @callback is called. the number of vectors to write + filename="gio/goutputstream.c" + line="328">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/goutputstream.c" + line="329">location to store the number of bytes that were written to the stream @@ -87453,8 +91231,8 @@ until @callback is called. nullable="1" allow-none="1"> optional cancellable object + filename="gio/goutputstream.c" + line="331">optional cancellable object @@ -87462,21 +91240,21 @@ until @callback is called. - + A #GOutputStream. + filename="gio/goutputstream.c" + line="1283">A #GOutputStream. the buffer containing the #GOutputVectors to write. + filename="gio/goutputstream.c" + line="1284">the buffer containing the #GOutputVectors to write. @@ -87485,14 +91263,14 @@ until @callback is called. the number of vectors to write + filename="gio/goutputstream.c" + line="1285">the number of vectors to write the I/O priority of the request. + filename="gio/goutputstream.c" + line="1286">the I/O priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/goutputstream.c" + line="1287">optional #GCancellable object, %NULL to ignore. scope="async" closure="6"> a #GAsyncReadyCallback + filename="gio/goutputstream.c" + line="1288">a #GAsyncReadyCallback to call when the request is satisfied @@ -87522,8 +91300,8 @@ until @callback is called. allow-none="1" closure="6"> the data to pass to callback function + filename="gio/goutputstream.c" + line="1290">the data to pass to callback function @@ -87531,24 +91309,24 @@ until @callback is called. - + %TRUE on success, %FALSE if there was an error + filename="gio/goutputstream.c" + line="1357">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/goutputstream.c" + line="1349">a #GOutputStream. a #GAsyncResult. + filename="gio/goutputstream.c" + line="1350">a #GAsyncResult. optional="1" allow-none="1"> location to store the number of bytes that were written to the stream + filename="gio/goutputstream.c" + line="1351">location to store the number of bytes that were written to the stream @@ -87567,7 +91345,7 @@ until @callback is called. - + @@ -87575,7 +91353,7 @@ until @callback is called. - + @@ -87583,7 +91361,7 @@ until @callback is called. - + @@ -87591,7 +91369,7 @@ until @callback is called. - + @@ -87599,7 +91377,7 @@ until @callback is called. - + @@ -87610,23 +91388,23 @@ until @callback is called. c:type="GOutputStreamPrivate" disguised="1" opaque="1"> - + GOutputStreamSpliceFlags determine how streams should be spliced. + filename="gio/gioenums.h" + line="655">GOutputStreamSpliceFlags determine how streams should be spliced. Do not close either stream. + filename="gio/gioenums.h" + line="657">Do not close either stream. glib:nick="close-source" glib:name="G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE"> Close the source stream after + filename="gio/gioenums.h" + line="658">Close the source stream after the splice. glib:nick="close-target" glib:name="G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET"> Close the target stream after + filename="gio/gioenums.h" + line="660">Close the target stream after the splice. Structure used for scatter/gather data output. + filename="gio/giotypes.h" + line="410">Structure used for scatter/gather data output. You generally pass in an array of #GOutputVectors and the operation will use all the buffers as if they were one buffer. - + Pointer to a buffer of data to read. + filename="gio/giotypes.h" + line="412">Pointer to a buffer of data to read. the size of @buffer. + filename="gio/giotypes.h" + line="413">the size of @buffer. - + @@ -87682,7 +91460,7 @@ one buffer. - + @@ -87691,7 +91469,7 @@ one buffer. - + @@ -87700,7 +91478,7 @@ one buffer. - + @@ -87709,7 +91487,7 @@ one buffer. - + @@ -87718,7 +91496,7 @@ one buffer. - + @@ -87727,7 +91505,7 @@ one buffer. - + @@ -87736,7 +91514,7 @@ one buffer. - + @@ -87747,16 +91525,16 @@ one buffer. c:type="G_POWER_PROFILE_MONITOR_EXTENSION_POINT_NAME" version="2.70"> Extension point for power profile usage monitoring functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -87765,14 +91543,14 @@ See [Extending GIO][extending-gio]. - + - + @@ -87781,7 +91559,7 @@ See [Extending GIO][extending-gio]. - + @@ -87790,7 +91568,7 @@ See [Extending GIO][extending-gio]. - + @@ -87799,7 +91577,7 @@ See [Extending GIO][extending-gio]. - + @@ -87808,7 +91586,7 @@ See [Extending GIO][extending-gio]. - + @@ -87817,7 +91595,7 @@ See [Extending GIO][extending-gio]. - + @@ -87826,7 +91604,7 @@ See [Extending GIO][extending-gio]. - + @@ -87837,16 +91615,16 @@ See [Extending GIO][extending-gio]. c:type="G_PROXY_EXTENSION_POINT_NAME" version="2.26"> Extension point for proxy functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -87855,7 +91633,7 @@ See [Extending GIO][extending-gio]. - + @@ -87865,16 +91643,16 @@ See [Extending GIO][extending-gio]. value="gio-proxy-resolver" c:type="G_PROXY_RESOLVER_EXTENSION_POINT_NAME"> Extension point for proxy resolving functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -87885,8 +91663,8 @@ See [Extending GIO][extending-gio]. glib:get-type="g_password_save_get_type" c:type="GPasswordSave"> #GPasswordSave is used to indicate the lifespan of a saved password. + filename="gio/gioenums.h" + line="618">#GPasswordSave is used to indicate the lifespan of a saved password. #Gvfs stores passwords in the Gnome keyring when this flag allows it to, and later retrieves it again from there. @@ -87896,8 +91674,8 @@ to, and later retrieves it again from there. glib:nick="never" glib:name="G_PASSWORD_SAVE_NEVER"> never save a password. + filename="gio/gioenums.h" + line="620">never save a password. glib:nick="for-session" glib:name="G_PASSWORD_SAVE_FOR_SESSION"> save a password for the session. + filename="gio/gioenums.h" + line="621">save a password for the session. glib:nick="permanently" glib:name="G_PASSWORD_SAVE_PERMANENTLY"> save a password permanently. + filename="gio/gioenums.h" + line="622">save a password permanently. glib:get-type="g_permission_get_type" glib:type-struct="PermissionClass"> A #GPermission represents the status of the caller's permission to + filename="gio/gpermission.c" + line="33">A `GPermission` represents the status of the caller’s permission to perform a certain action. You can query if the action is currently allowed and if it is @@ -87938,19 +91716,20 @@ in the future. There is also an API to actually acquire the permission and one to release it. -As an example, a #GPermission might represent the ability for the -user to write to a #GSettings object. This #GPermission object could -then be used to decide if it is appropriate to show a "Click here to -unlock" button in a dialog and to provide the mechanism to invoke +As an example, a `GPermission` might represent the ability for the +user to write to a [class@Gio.Settings] object. This `GPermission` object +could then be used to decide if it is appropriate to show a “Click here to +unlock” button in a dialog and to provide the mechanism to invoke when that button is clicked. - + + throws="1" + glib:async-func="acquire_async"> Attempts to acquire the permission represented by @permission. + filename="gio/gpermission.c" + line="69">Attempts to acquire the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is @@ -87965,18 +91744,18 @@ If the permission is acquired then %TRUE is returned. Otherwise, This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_acquire_async() for the non-blocking version. - + %TRUE if the permission was successfully acquired + filename="gio/gpermission.c" + line="91">%TRUE if the permission was successfully acquired a #GPermission instance + filename="gio/gpermission.c" + line="71">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="72">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="acquire_finish" + glib:sync-func="acquire"> Attempts to acquire the permission represented by @permission. + filename="gio/gpermission.c" + line="105">Attempts to acquire the permission represented by @permission. This is the first half of the asynchronous version of g_permission_acquire(). - + a #GPermission instance + filename="gio/gpermission.c" + line="107">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="108">a #GCancellable, or %NULL scope="async" closure="2"> the #GAsyncReadyCallback to call when done + filename="gio/gpermission.c" + line="109">the #GAsyncReadyCallback to call when done allow-none="1" closure="2"> the user data to pass to @callback + filename="gio/gpermission.c" + line="110">the user data to pass to @callback @@ -88047,30 +91828,30 @@ g_permission_acquire(). version="2.26" throws="1"> Collects the result of attempting to acquire the permission + filename="gio/gpermission.c" + line="130">Collects the result of attempting to acquire the permission represented by @permission. This is the second half of the asynchronous version of g_permission_acquire(). - + %TRUE if the permission was successfully acquired + filename="gio/gpermission.c" + line="142">%TRUE if the permission was successfully acquired a #GPermission instance + filename="gio/gpermission.c" + line="132">a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback + filename="gio/gpermission.c" + line="133">the #GAsyncResult given to the #GAsyncReadyCallback @@ -88078,10 +91859,11 @@ g_permission_acquire(). + throws="1" + glib:async-func="release_async"> Attempts to release the permission represented by @permission. + filename="gio/gpermission.c" + line="156">Attempts to release the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the @@ -88096,18 +91878,18 @@ If the permission is released then %TRUE is returned. Otherwise, This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_release_async() for the non-blocking version. - + %TRUE if the permission was successfully released + filename="gio/gpermission.c" + line="178">%TRUE if the permission was successfully released a #GPermission instance + filename="gio/gpermission.c" + line="158">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="159">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="release_finish" + glib:sync-func="release"> Attempts to release the permission represented by @permission. + filename="gio/gpermission.c" + line="192">Attempts to release the permission represented by @permission. This is the first half of the asynchronous version of g_permission_release(). - + a #GPermission instance + filename="gio/gpermission.c" + line="194">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="195">a #GCancellable, or %NULL scope="async" closure="2"> the #GAsyncReadyCallback to call when done + filename="gio/gpermission.c" + line="196">the #GAsyncReadyCallback to call when done allow-none="1" closure="2"> the user data to pass to @callback + filename="gio/gpermission.c" + line="197">the user data to pass to @callback @@ -88178,30 +91962,30 @@ g_permission_release(). version="2.26" throws="1"> Collects the result of attempting to release the permission + filename="gio/gpermission.c" + line="217">Collects the result of attempting to release the permission represented by @permission. This is the second half of the asynchronous version of g_permission_release(). - + %TRUE if the permission was successfully released + filename="gio/gpermission.c" + line="229">%TRUE if the permission was successfully released a #GPermission instance + filename="gio/gpermission.c" + line="219">a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback + filename="gio/gpermission.c" + line="220">the #GAsyncResult given to the #GAsyncReadyCallback @@ -88209,10 +91993,11 @@ g_permission_release(). + throws="1" + glib:async-func="acquire_async"> Attempts to acquire the permission represented by @permission. + filename="gio/gpermission.c" + line="69">Attempts to acquire the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is @@ -88227,18 +92012,18 @@ If the permission is acquired then %TRUE is returned. Otherwise, This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_acquire_async() for the non-blocking version. - + %TRUE if the permission was successfully acquired + filename="gio/gpermission.c" + line="91">%TRUE if the permission was successfully acquired a #GPermission instance + filename="gio/gpermission.c" + line="71">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="72">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="acquire_finish" + glib:sync-func="acquire"> Attempts to acquire the permission represented by @permission. + filename="gio/gpermission.c" + line="105">Attempts to acquire the permission represented by @permission. This is the first half of the asynchronous version of g_permission_acquire(). - + a #GPermission instance + filename="gio/gpermission.c" + line="107">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="108">a #GCancellable, or %NULL scope="async" closure="2"> the #GAsyncReadyCallback to call when done + filename="gio/gpermission.c" + line="109">the #GAsyncReadyCallback to call when done nullable="1" allow-none="1"> the user data to pass to @callback + filename="gio/gpermission.c" + line="110">the user data to pass to @callback @@ -88308,30 +92095,30 @@ g_permission_acquire(). version="2.26" throws="1"> Collects the result of attempting to acquire the permission + filename="gio/gpermission.c" + line="130">Collects the result of attempting to acquire the permission represented by @permission. This is the second half of the asynchronous version of g_permission_acquire(). - + %TRUE if the permission was successfully acquired + filename="gio/gpermission.c" + line="142">%TRUE if the permission was successfully acquired a #GPermission instance + filename="gio/gpermission.c" + line="132">a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback + filename="gio/gpermission.c" + line="133">the #GAsyncResult given to the #GAsyncReadyCallback @@ -88341,22 +92128,22 @@ g_permission_acquire(). glib:get-property="allowed" version="2.26"> Gets the value of the 'allowed' property. This property is %TRUE if + filename="gio/gpermission.c" + line="243">Gets the value of the 'allowed' property. This property is %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. - + the value of the 'allowed' property + filename="gio/gpermission.c" + line="251">the value of the 'allowed' property a #GPermission instance + filename="gio/gpermission.c" + line="245">a #GPermission instance @@ -88366,22 +92153,22 @@ the caller currently has permission to perform the action that glib:get-property="can-acquire" version="2.26"> Gets the value of the 'can-acquire' property. This property is %TRUE + filename="gio/gpermission.c" + line="262">Gets the value of the 'can-acquire' property. This property is %TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). - + the value of the 'can-acquire' property + filename="gio/gpermission.c" + line="270">the value of the 'can-acquire' property a #GPermission instance + filename="gio/gpermission.c" + line="264">a #GPermission instance @@ -88391,22 +92178,22 @@ g_permission_acquire(). glib:get-property="can-release" version="2.26"> Gets the value of the 'can-release' property. This property is %TRUE + filename="gio/gpermission.c" + line="281">Gets the value of the 'can-release' property. This property is %TRUE if it is generally possible to release the permission by calling g_permission_release(). - + the value of the 'can-release' property + filename="gio/gpermission.c" + line="289">the value of the 'can-release' property a #GPermission instance + filename="gio/gpermission.c" + line="283">a #GPermission instance @@ -88415,39 +92202,39 @@ g_permission_release(). c:identifier="g_permission_impl_update" version="2.26"> This function is called by the #GPermission implementation to update + filename="gio/gpermission.c" + line="300">This function is called by the #GPermission implementation to update the properties of the permission. You should never call this function except from a #GPermission implementation. GObject notify signals are generated, as appropriate. - + a #GPermission instance + filename="gio/gpermission.c" + line="302">a #GPermission instance the new value for the 'allowed' property + filename="gio/gpermission.c" + line="303">the new value for the 'allowed' property the new value for the 'can-acquire' property + filename="gio/gpermission.c" + line="304">the new value for the 'can-acquire' property the new value for the 'can-release' property + filename="gio/gpermission.c" + line="305">the new value for the 'can-release' property @@ -88455,10 +92242,11 @@ GObject notify signals are generated, as appropriate. + throws="1" + glib:async-func="release_async"> Attempts to release the permission represented by @permission. + filename="gio/gpermission.c" + line="156">Attempts to release the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the @@ -88473,18 +92261,18 @@ If the permission is released then %TRUE is returned. Otherwise, This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_release_async() for the non-blocking version. - + %TRUE if the permission was successfully released + filename="gio/gpermission.c" + line="178">%TRUE if the permission was successfully released a #GPermission instance + filename="gio/gpermission.c" + line="158">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="159">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="release_finish" + glib:sync-func="release"> Attempts to release the permission represented by @permission. + filename="gio/gpermission.c" + line="192">Attempts to release the permission represented by @permission. This is the first half of the asynchronous version of g_permission_release(). - + a #GPermission instance + filename="gio/gpermission.c" + line="194">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="195">a #GCancellable, or %NULL scope="async" closure="2"> the #GAsyncReadyCallback to call when done + filename="gio/gpermission.c" + line="196">the #GAsyncReadyCallback to call when done nullable="1" allow-none="1"> the user data to pass to @callback + filename="gio/gpermission.c" + line="197">the user data to pass to @callback @@ -88554,30 +92344,30 @@ g_permission_release(). version="2.26" throws="1"> Collects the result of attempting to release the permission + filename="gio/gpermission.c" + line="217">Collects the result of attempting to release the permission represented by @permission. This is the second half of the asynchronous version of g_permission_release(). - + %TRUE if the permission was successfully released + filename="gio/gpermission.c" + line="229">%TRUE if the permission was successfully released a #GPermission instance + filename="gio/gpermission.c" + line="219">a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback + filename="gio/gpermission.c" + line="220">the #GAsyncResult given to the #GAsyncReadyCallback @@ -88587,8 +92377,8 @@ g_permission_release(). getter="get_allowed" default-value="FALSE"> %TRUE if the caller currently has permission to perform the action that + filename="gio/gpermission.c" + line="429">%TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. @@ -88597,8 +92387,8 @@ g_permission_release(). getter="get_can_acquire" default-value="FALSE"> %TRUE if it is generally possible to acquire the permission by calling + filename="gio/gpermission.c" + line="440">%TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). @@ -88607,8 +92397,8 @@ g_permission_acquire(). getter="get_can_release" default-value="FALSE"> %TRUE if it is generally possible to release the permission by calling + filename="gio/gpermission.c" + line="451">%TRUE if it is generally possible to release the permission by calling g_permission_release(). @@ -88622,24 +92412,24 @@ g_permission_release(). - + - + %TRUE if the permission was successfully acquired + filename="gio/gpermission.c" + line="91">%TRUE if the permission was successfully acquired a #GPermission instance + filename="gio/gpermission.c" + line="71">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="72">a #GCancellable, or %NULL @@ -88656,15 +92446,15 @@ g_permission_release(). - + a #GPermission instance + filename="gio/gpermission.c" + line="107">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="108">a #GCancellable, or %NULL scope="async" closure="3"> the #GAsyncReadyCallback to call when done + filename="gio/gpermission.c" + line="109">the #GAsyncReadyCallback to call when done allow-none="1" closure="3"> the user data to pass to @callback + filename="gio/gpermission.c" + line="110">the user data to pass to @callback @@ -88702,24 +92492,24 @@ g_permission_release(). - + %TRUE if the permission was successfully acquired + filename="gio/gpermission.c" + line="142">%TRUE if the permission was successfully acquired a #GPermission instance + filename="gio/gpermission.c" + line="132">a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback + filename="gio/gpermission.c" + line="133">the #GAsyncResult given to the #GAsyncReadyCallback @@ -88727,18 +92517,18 @@ g_permission_release(). - + %TRUE if the permission was successfully released + filename="gio/gpermission.c" + line="178">%TRUE if the permission was successfully released a #GPermission instance + filename="gio/gpermission.c" + line="158">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="159">a #GCancellable, or %NULL @@ -88755,15 +92545,15 @@ g_permission_release(). - + a #GPermission instance + filename="gio/gpermission.c" + line="194">a #GPermission instance nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpermission.c" + line="195">a #GCancellable, or %NULL scope="async" closure="3"> the #GAsyncReadyCallback to call when done + filename="gio/gpermission.c" + line="196">the #GAsyncReadyCallback to call when done allow-none="1" closure="3"> the user data to pass to @callback + filename="gio/gpermission.c" + line="197">the user data to pass to @callback @@ -88801,24 +92591,24 @@ g_permission_release(). - + %TRUE if the permission was successfully released + filename="gio/gpermission.c" + line="229">%TRUE if the permission was successfully released a #GPermission instance + filename="gio/gpermission.c" + line="219">a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback + filename="gio/gpermission.c" + line="220">the #GAsyncResult given to the #GAsyncReadyCallback @@ -88834,7 +92624,7 @@ g_permission_release(). c:type="GPermissionPrivate" disguised="1" opaque="1"> - + glib:get-type="g_pollable_input_stream_get_type" glib:type-struct="PollableInputStreamInterface"> #GPollableInputStream is implemented by #GInputStreams that + filename="gio/gpollableinputstream.c" + line="29">`GPollableInputStream` is implemented by [class@Gio.InputStream]s that can be polled for readiness to read. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. -Some classes may implement #GPollableInputStream but have only certain -instances of that class be pollable. If g_pollable_input_stream_can_poll() -returns %FALSE, then the behavior of other #GPollableInputStream methods is +Some classes may implement `GPollableInputStream` but have only certain +instances of that class be pollable. If [method@Gio.PollableInputStream.can_poll] +returns false, then the behavior of other `GPollableInputStream` methods is undefined. - + Checks if @stream is actually pollable. Some classes may implement + filename="gio/gpollableinputstream.c" + line="66">Checks if @stream is actually pollable. Some classes may implement #GPollableInputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableInputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. - + %TRUE if @stream is pollable, %FALSE if not. + filename="gio/gpollableinputstream.c" + line="78">%TRUE if @stream is pollable, %FALSE if not. a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="68">a #GPollableInputStream. @@ -88886,8 +92676,8 @@ a stream cannot switch from pollable to non-pollable or vice versa. invoker="create_source" version="2.28"> Creates a #GSource that triggers when @stream can be read, or + filename="gio/gpollableinputstream.c" + line="121">Creates a #GSource that triggers when @stream can be read, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. @@ -88898,18 +92688,18 @@ rather than g_input_stream_read() from the callback. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. - + a new #GSource + filename="gio/gpollableinputstream.c" + line="138">a new #GSource a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="123">a #GPollableInputStream. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableinputstream.c" + line="124">a #GCancellable, or %NULL Checks if @stream can be read. + filename="gio/gpollableinputstream.c" + line="90">Checks if @stream can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_input_stream_read() @@ -88937,11 +92727,11 @@ g_pollable_input_stream_read_nonblocking(), which will return a The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. - + %TRUE if @stream is readable, %FALSE if not. If an error + filename="gio/gpollableinputstream.c" + line="106">%TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. @@ -88950,8 +92740,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="92">a #GPollableInputStream. @@ -88960,8 +92750,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. invoker="read_nonblocking" throws="1"> Attempts to read up to @count bytes from @stream into @buffer, as + filename="gio/gpollableinputstream.c" + line="169">Attempts to read up to @count bytes from @stream into @buffer, as with g_input_stream_read(). If @stream is not currently readable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_input_stream_create_source() to create a #GSource @@ -88975,19 +92765,19 @@ to having been cancelled. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. - + the number of bytes read, or -1 on error (including + filename="gio/gpollableinputstream.c" + line="193">the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableInputStream + filename="gio/gpollableinputstream.c" + line="171">a #GPollableInputStream transfer-ownership="none" nullable="1"> a + filename="gio/gpollableinputstream.c" + line="172">a buffer to read data into (which should be at least @count bytes long). @@ -89005,8 +92795,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. the number of bytes you want to read + filename="gio/gpollableinputstream.c" + line="174">the number of bytes you want to read @@ -89015,26 +92805,26 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. c:identifier="g_pollable_input_stream_can_poll" version="2.28"> Checks if @stream is actually pollable. Some classes may implement + filename="gio/gpollableinputstream.c" + line="66">Checks if @stream is actually pollable. Some classes may implement #GPollableInputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableInputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. - + %TRUE if @stream is pollable, %FALSE if not. + filename="gio/gpollableinputstream.c" + line="78">%TRUE if @stream is pollable, %FALSE if not. a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="68">a #GPollableInputStream. @@ -89043,8 +92833,8 @@ a stream cannot switch from pollable to non-pollable or vice versa. c:identifier="g_pollable_input_stream_create_source" version="2.28"> Creates a #GSource that triggers when @stream can be read, or + filename="gio/gpollableinputstream.c" + line="121">Creates a #GSource that triggers when @stream can be read, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. @@ -89055,18 +92845,18 @@ rather than g_input_stream_read() from the callback. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. - + a new #GSource + filename="gio/gpollableinputstream.c" + line="138">a new #GSource a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="123">a #GPollableInputStream. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableinputstream.c" + line="124">a #GCancellable, or %NULL @@ -89084,8 +92874,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. c:identifier="g_pollable_input_stream_is_readable" version="2.28"> Checks if @stream can be read. + filename="gio/gpollableinputstream.c" + line="90">Checks if @stream can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_input_stream_read() @@ -89096,11 +92886,11 @@ g_pollable_input_stream_read_nonblocking(), which will return a The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. - + %TRUE if @stream is readable, %FALSE if not. If an error + filename="gio/gpollableinputstream.c" + line="106">%TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. @@ -89109,8 +92899,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="92">a #GPollableInputStream. @@ -89119,8 +92909,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. c:identifier="g_pollable_input_stream_read_nonblocking" throws="1"> Attempts to read up to @count bytes from @stream into @buffer, as + filename="gio/gpollableinputstream.c" + line="169">Attempts to read up to @count bytes from @stream into @buffer, as with g_input_stream_read(). If @stream is not currently readable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_input_stream_create_source() to create a #GSource @@ -89134,19 +92924,19 @@ to having been cancelled. The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns %FALSE for @stream. - + the number of bytes read, or -1 on error (including + filename="gio/gpollableinputstream.c" + line="193">the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableInputStream + filename="gio/gpollableinputstream.c" + line="171">a #GPollableInputStream caller-allocates="1" transfer-ownership="none"> a + filename="gio/gpollableinputstream.c" + line="172">a buffer to read data into (which should be at least @count bytes long). @@ -89163,8 +92953,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. the number of bytes you want to read + filename="gio/gpollableinputstream.c" + line="174">the number of bytes you want to read nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableinputstream.c" + line="175">a #GCancellable, or %NULL @@ -89184,8 +92974,8 @@ g_pollable_input_stream_can_poll() returns %FALSE for @stream. glib:is-gtype-struct-for="PollableInputStream" version="2.28"> The interface for pollable input streams. + filename="gio/gpollableinputstream.h" + line="39">The interface for pollable input streams. The default implementation of @can_poll always returns %TRUE. @@ -89195,39 +92985,45 @@ g_input_stream_read() if it returns %TRUE. This means you only need to override it if it is possible that your @is_readable implementation may return %TRUE when the stream is not actually readable. - + The parent interface. + filename="gio/gpollableinputstream.h" + line="41">The parent interface. + Checks if the #GPollableInputStream instance is actually pollable - + %TRUE if @stream is pollable, %FALSE if not. + filename="gio/gpollableinputstream.c" + line="78">%TRUE if @stream is pollable, %FALSE if not. a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="68">a #GPollableInputStream. + Checks if the stream is readable - + %TRUE if @stream is readable, %FALSE if not. If an error + filename="gio/gpollableinputstream.c" + line="106">%TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. @@ -89236,27 +93032,30 @@ readable. a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="92">a #GPollableInputStream. + Creates a #GSource to poll the stream - + a new #GSource + filename="gio/gpollableinputstream.c" + line="138">a new #GSource a #GPollableInputStream. + filename="gio/gpollableinputstream.c" + line="123">a #GPollableInputStream. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableinputstream.c" + line="124">a #GCancellable, or %NULL + Does a non-blocking read or returns + %G_IO_ERROR_WOULD_BLOCK - + the number of bytes read, or -1 on error (including + filename="gio/gpollableinputstream.c" + line="193">the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableInputStream + filename="gio/gpollableinputstream.c" + line="171">a #GPollableInputStream transfer-ownership="none" nullable="1"> a + filename="gio/gpollableinputstream.c" + line="172">a buffer to read data into (which should be at least @count bytes long). @@ -89303,8 +93106,8 @@ readable. the number of bytes you want to read + filename="gio/gpollableinputstream.c" + line="174">the number of bytes you want to read @@ -89319,40 +93122,40 @@ readable. glib:get-type="g_pollable_output_stream_get_type" glib:type-struct="PollableOutputStreamInterface"> #GPollableOutputStream is implemented by #GOutputStreams that + filename="gio/gpollableoutputstream.c" + line="30">`GPollableOutputStream` is implemented by [class@Gio.OutputStream]s that can be polled for readiness to write. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. -Some classes may implement #GPollableOutputStream but have only certain -instances of that class be pollable. If g_pollable_output_stream_can_poll() -returns %FALSE, then the behavior of other #GPollableOutputStream methods is +Some classes may implement `GPollableOutputStream` but have only certain +instances of that class be pollable. If [method@Gio.PollableOutputStream.can_poll] +returns false, then the behavior of other `GPollableOutputStream` methods is undefined. - + Checks if @stream is actually pollable. Some classes may implement + filename="gio/gpollableoutputstream.c" + line="73">Checks if @stream is actually pollable. Some classes may implement #GPollableOutputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableOutputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. - + %TRUE if @stream is pollable, %FALSE if not. + filename="gio/gpollableoutputstream.c" + line="85">%TRUE if @stream is pollable, %FALSE if not. a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="75">a #GPollableOutputStream. @@ -89361,8 +93164,8 @@ a stream cannot switch from pollable to non-pollable or vice versa. invoker="create_source" version="2.28"> Creates a #GSource that triggers when @stream can be written, or + filename="gio/gpollableoutputstream.c" + line="128">Creates a #GSource that triggers when @stream can be written, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. @@ -89373,18 +93176,18 @@ rather than g_output_stream_write() from the callback. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + a new #GSource + filename="gio/gpollableoutputstream.c" + line="145">a new #GSource a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="130">a #GPollableOutputStream. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableoutputstream.c" + line="131">a #GCancellable, or %NULL Checks if @stream can be written. + filename="gio/gpollableoutputstream.c" + line="97">Checks if @stream can be written. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_output_stream_write() @@ -89412,11 +93215,11 @@ g_pollable_output_stream_write_nonblocking(), which will return a The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + %TRUE if @stream is writable, %FALSE if not. If an error + filename="gio/gpollableoutputstream.c" + line="113">%TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. @@ -89425,8 +93228,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="99">a #GPollableOutputStream. @@ -89435,8 +93238,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. invoker="write_nonblocking" throws="1"> Attempts to write up to @count bytes from @buffer to @stream, as + filename="gio/gpollableoutputstream.c" + line="237">Attempts to write up to @count bytes from @buffer to @stream, as with g_output_stream_write(). If @stream is not currently writable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource @@ -89454,19 +93257,19 @@ transports like D/TLS require that you re-send the same @buffer and The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + the number of bytes written, or -1 on error (including + filename="gio/gpollableoutputstream.c" + line="265">the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableOutputStream + filename="gio/gpollableoutputstream.c" + line="239">a #GPollableOutputStream nullable="1" allow-none="1"> a buffer to write + filename="gio/gpollableoutputstream.c" + line="240">a buffer to write data from @@ -89483,8 +93286,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. the number of bytes you want to write + filename="gio/gpollableoutputstream.c" + line="242">the number of bytes you want to write @@ -89494,8 +93297,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. version="2.60" throws="1"> Attempts to write the bytes contained in the @n_vectors @vectors to @stream, + filename="gio/gpollableoutputstream.c" + line="305">Attempts to write the bytes contained in the @n_vectors @vectors to @stream, as with g_output_stream_writev(). If @stream is not currently writable, this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource @@ -89514,11 +93317,11 @@ transports like D/TLS require that you re-send the same @vectors and The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK + filename="gio/gpollableoutputstream.c" + line="335">%@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. @@ -89527,14 +93330,14 @@ be set. a #GPollableOutputStream + filename="gio/gpollableoutputstream.c" + line="307">a #GPollableOutputStream the buffer containing the #GOutputVectors to write. + filename="gio/gpollableoutputstream.c" + line="308">the buffer containing the #GOutputVectors to write. @@ -89543,8 +93346,8 @@ be set. the number of vectors to write + filename="gio/gpollableoutputstream.c" + line="309">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/gpollableoutputstream.c" + line="310">location to store the number of bytes that were written to the stream @@ -89565,26 +93368,26 @@ be set. c:identifier="g_pollable_output_stream_can_poll" version="2.28"> Checks if @stream is actually pollable. Some classes may implement + filename="gio/gpollableoutputstream.c" + line="73">Checks if @stream is actually pollable. Some classes may implement #GPollableOutputStream but have only certain instances of that class be pollable. If this method returns %FALSE, then the behavior of other #GPollableOutputStream methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. - + %TRUE if @stream is pollable, %FALSE if not. + filename="gio/gpollableoutputstream.c" + line="85">%TRUE if @stream is pollable, %FALSE if not. a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="75">a #GPollableOutputStream. @@ -89593,8 +93396,8 @@ a stream cannot switch from pollable to non-pollable or vice versa. c:identifier="g_pollable_output_stream_create_source" version="2.28"> Creates a #GSource that triggers when @stream can be written, or + filename="gio/gpollableoutputstream.c" + line="128">Creates a #GSource that triggers when @stream can be written, or @cancellable is triggered or an error occurs. The callback on the source is of the #GPollableSourceFunc type. @@ -89605,18 +93408,18 @@ rather than g_output_stream_write() from the callback. The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + a new #GSource + filename="gio/gpollableoutputstream.c" + line="145">a new #GSource a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="130">a #GPollableOutputStream. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableoutputstream.c" + line="131">a #GCancellable, or %NULL @@ -89634,8 +93437,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. c:identifier="g_pollable_output_stream_is_writable" version="2.28"> Checks if @stream can be written. + filename="gio/gpollableoutputstream.c" + line="97">Checks if @stream can be written. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_output_stream_write() @@ -89646,11 +93449,11 @@ g_pollable_output_stream_write_nonblocking(), which will return a The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + %TRUE if @stream is writable, %FALSE if not. If an error + filename="gio/gpollableoutputstream.c" + line="113">%TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. @@ -89659,8 +93462,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="99">a #GPollableOutputStream. @@ -89669,8 +93472,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. c:identifier="g_pollable_output_stream_write_nonblocking" throws="1"> Attempts to write up to @count bytes from @buffer to @stream, as + filename="gio/gpollableoutputstream.c" + line="237">Attempts to write up to @count bytes from @buffer to @stream, as with g_output_stream_write(). If @stream is not currently writable, this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource @@ -89688,25 +93491,25 @@ transports like D/TLS require that you re-send the same @buffer and The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + the number of bytes written, or -1 on error (including + filename="gio/gpollableoutputstream.c" + line="265">the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableOutputStream + filename="gio/gpollableoutputstream.c" + line="239">a #GPollableOutputStream a buffer to write + filename="gio/gpollableoutputstream.c" + line="240">a buffer to write data from @@ -89714,8 +93517,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. the number of bytes you want to write + filename="gio/gpollableoutputstream.c" + line="242">the number of bytes you want to write nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableoutputstream.c" + line="243">a #GCancellable, or %NULL @@ -89734,8 +93537,8 @@ g_pollable_output_stream_can_poll() returns %FALSE for @stream. version="2.60" throws="1"> Attempts to write the bytes contained in the @n_vectors @vectors to @stream, + filename="gio/gpollableoutputstream.c" + line="305">Attempts to write the bytes contained in the @n_vectors @vectors to @stream, as with g_output_stream_writev(). If @stream is not currently writable, this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource @@ -89754,11 +93557,11 @@ transports like D/TLS require that you re-send the same @vectors and The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns %FALSE for @stream. - + %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK + filename="gio/gpollableoutputstream.c" + line="335">%@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. @@ -89767,14 +93570,14 @@ be set. a #GPollableOutputStream + filename="gio/gpollableoutputstream.c" + line="307">a #GPollableOutputStream the buffer containing the #GOutputVectors to write. + filename="gio/gpollableoutputstream.c" + line="308">the buffer containing the #GOutputVectors to write. @@ -89783,8 +93586,8 @@ be set. the number of vectors to write + filename="gio/gpollableoutputstream.c" + line="309">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/gpollableoutputstream.c" + line="310">location to store the number of bytes that were written to the stream @@ -89804,8 +93607,8 @@ be set. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableoutputstream.c" + line="312">a #GCancellable, or %NULL @@ -89816,8 +93619,8 @@ be set. glib:is-gtype-struct-for="PollableOutputStream" version="2.28"> The interface for pollable output streams. + filename="gio/gpollableoutputstream.h" + line="39">The interface for pollable output streams. The default implementation of @can_poll always returns %TRUE. @@ -89833,27 +93636,30 @@ g_pollable_output_stream_write_nonblocking() for each vector, and converts its return value and error (if set) to a #GPollableReturn. You should override this where possible to avoid having to allocate a #GError to return %G_IO_ERROR_WOULD_BLOCK. - + The parent interface. + filename="gio/gpollableoutputstream.h" + line="41">The parent interface. + Checks if the #GPollableOutputStream instance is actually pollable - + %TRUE if @stream is pollable, %FALSE if not. + filename="gio/gpollableoutputstream.c" + line="85">%TRUE if @stream is pollable, %FALSE if not. a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="75">a #GPollableOutputStream. @@ -89861,12 +93667,15 @@ override this where possible to avoid having to allocate a #GError to return + Checks if the stream is writable - + %TRUE if @stream is writable, %FALSE if not. If an error + filename="gio/gpollableoutputstream.c" + line="113">%TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. @@ -89875,8 +93684,8 @@ override this where possible to avoid having to allocate a #GError to return a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="99">a #GPollableOutputStream. @@ -89884,19 +93693,22 @@ override this where possible to avoid having to allocate a #GError to return + Creates a #GSource to poll the stream - + a new #GSource + filename="gio/gpollableoutputstream.c" + line="145">a new #GSource a #GPollableOutputStream. + filename="gio/gpollableoutputstream.c" + line="130">a #GPollableOutputStream. @@ -89905,28 +93717,32 @@ override this where possible to avoid having to allocate a #GError to return nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gpollableoutputstream.c" + line="131">a #GCancellable, or %NULL + Does a non-blocking write or returns + %G_IO_ERROR_WOULD_BLOCK - + the number of bytes written, or -1 on error (including + filename="gio/gpollableoutputstream.c" + line="265">the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). a #GPollableOutputStream + filename="gio/gpollableoutputstream.c" + line="239">a #GPollableOutputStream @@ -89935,8 +93751,8 @@ override this where possible to avoid having to allocate a #GError to return nullable="1" allow-none="1"> a buffer to write + filename="gio/gpollableoutputstream.c" + line="240">a buffer to write data from @@ -89944,20 +93760,24 @@ override this where possible to avoid having to allocate a #GError to return the number of bytes you want to write + filename="gio/gpollableoutputstream.c" + line="242">the number of bytes you want to write + Does a vectored non-blocking write, or returns + %G_POLLABLE_RETURN_WOULD_BLOCK - + %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK + filename="gio/gpollableoutputstream.c" + line="335">%@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. @@ -89966,15 +93786,15 @@ be set. a #GPollableOutputStream + filename="gio/gpollableoutputstream.c" + line="307">a #GPollableOutputStream the buffer containing the #GOutputVectors to write. + filename="gio/gpollableoutputstream.c" + line="308">the buffer containing the #GOutputVectors to write. @@ -89983,8 +93803,8 @@ be set. the number of vectors to write + filename="gio/gpollableoutputstream.c" + line="309">the number of vectors to write optional="1" allow-none="1"> location to store the number of bytes that were + filename="gio/gpollableoutputstream.c" + line="310">location to store the number of bytes that were written to the stream @@ -90009,8 +93829,8 @@ be set. glib:get-type="g_pollable_return_get_type" c:type="GPollableReturn"> Return value for various IO operations that signal errors via the + filename="gio/gioenums.h" + line="2110">Return value for various IO operations that signal errors via the return value and not necessarily via a #GError. This enum exists to be able to return errors to callers without having to @@ -90025,8 +93845,8 @@ operation to give details about the error that happened. glib:nick="failed" glib:name="G_POLLABLE_RETURN_FAILED"> Generic error condition for when an operation fails. + filename="gio/gioenums.h" + line="2112">Generic error condition for when an operation fails. glib:nick="ok" glib:name="G_POLLABLE_RETURN_OK"> The operation was successfully finished. + filename="gio/gioenums.h" + line="2113">The operation was successfully finished. glib:nick="would-block" glib:name="G_POLLABLE_RETURN_WOULD_BLOCK"> The operation would block. + filename="gio/gioenums.h" + line="2114">The operation would block. This is the function type of the callback used for the #GSource + filename="gio/giotypes.h" + line="499">This is the function type of the callback used for the #GSource returned by g_pollable_input_stream_create_source() and g_pollable_output_stream_create_source(). - + it should return %FALSE if the source should be removed. + filename="gio/giotypes.h" + line="508">it should return %FALSE if the source should be removed. the #GPollableInputStream or #GPollableOutputStream + filename="gio/giotypes.h" + line="501">the #GPollableInputStream or #GPollableOutputStream nullable="1" allow-none="1"> data passed in by the user. + filename="gio/giotypes.h" + line="502">data passed in by the user. @@ -90088,13 +93908,14 @@ g_pollable_output_stream_create_source(). glib:get-type="g_power_profile_monitor_get_type" glib:type-struct="PowerProfileMonitorInterface"> #GPowerProfileMonitor makes it possible for applications as well as OS components -to monitor system power profiles and act upon them. It currently only exports -whether the system is in “Power Saver” mode (known as “Low Power” mode on -some systems). + filename="gio/gpowerprofilemonitor.c" + line="34">`GPowerProfileMonitor` makes it possible for applications as well as OS +components to monitor system power profiles and act upon them. It currently +only exports whether the system is in “Power Saver” mode (known as +“Low Power” mode on some systems). When in “Low Power” mode, it is recommended that applications: + - disable automatic downloads; - reduce the rate of refresh from online sources such as calendar or email synchronisation; @@ -90109,21 +93930,22 @@ monitor the battery discharge rate, `powertop` to check on the background activi or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to profile GPU usage. -Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled -signal, and unref the #GPowerProfileMonitor itself when exiting. - +Don’t forget to disconnect the [signal@GObject.Object::notify] signal for +[property@Gio.PowerProfileMonitor:power-saver-enabled], and unref the +`GPowerProfileMonitor` itself when exiting. + Gets a reference to the default #GPowerProfileMonitor for the system. - + filename="gio/gpowerprofilemonitor.c" + line="78">Gets a reference to the default #GPowerProfileMonitor for the system. + a new reference to the default #GPowerProfileMonitor + filename="gio/gpowerprofilemonitor.c" + line="83">a new reference to the default #GPowerProfileMonitor @@ -90132,24 +93954,24 @@ signal, and unref the #GPowerProfileMonitor itself when exiting. glib:get-property="power-saver-enabled" version="2.70"> Gets whether the system is in “Power Saver” mode. + filename="gio/gpowerprofilemonitor.c" + line="95">Gets whether the system is in “Power Saver” mode. You are expected to listen to the #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has changed. - + Whether the system is in “Power Saver” mode. + filename="gio/gpowerprofilemonitor.c" + line="105">Whether the system is in “Power Saver” mode. a #GPowerProfileMonitor + filename="gio/gpowerprofilemonitor.c" + line="97">a #GPowerProfileMonitor @@ -90160,8 +93982,8 @@ changed. getter="get_power_saver_enabled" default-value="FALSE"> Whether “Power Saver” mode is enabled on the system. + filename="gio/gpowerprofilemonitor.c" + line="120">Whether “Power Saver” mode is enabled on the system. @@ -90170,13 +93992,13 @@ changed. glib:is-gtype-struct-for="PowerProfileMonitor" version="2.70"> The virtual function table for #GPowerProfileMonitor. - + filename="gio/gpowerprofilemonitor.c" + line="65">The virtual function table for #GPowerProfileMonitor. + The parent interface. + filename="gio/gpowerprofilemonitor.c" + line="67">The parent interface. @@ -90188,13 +94010,13 @@ changed. glib:type-name="GPropertyAction" glib:get-type="g_property_action_get_type"> A #GPropertyAction is a way to get a #GAction with a state value -reflecting and controlling the value of a #GObject property. + filename="gio/gpropertyaction.c" + line="30">A `GPropertyAction` is a way to get a [iface@Gio.Action] with a state value +reflecting and controlling the value of a [class@GObject.Object] property. The state of the action will correspond to the value of the property. Changing it will change the property (assuming the requested value -matches the requirements as specified in the #GParamSpec). +matches the requirements as specified in the [type@GObject.ParamSpec]). Only the most common types are presently supported. Booleans are mapped to booleans, strings to strings, signed/unsigned integers to @@ -90202,16 +94024,16 @@ int32/uint32 and floats and doubles to doubles. If the property is an enum then the state will be string-typed and conversion will automatically be performed between the enum value and -"nick" string as per the #GEnumValue table. +‘nick’ string as per the [type@GObject.EnumValue] table. Flags types are not currently supported. Properties of object types, boxed types and pointer types are not supported and probably never will be. -Properties of #GVariant types are not currently supported. +Properties of [type@GLib.Variant] types are not currently supported. -If the property is boolean-valued then the action will have a NULL +If the property is boolean-valued then the action will have a `NULL` parameter type, and activating the action (with no parameter) will toggle the value of the property. @@ -90220,33 +94042,34 @@ the property. The general idea here is to reduce the number of locations where a particular piece of state is kept (and therefore has to be synchronised -between). #GPropertyAction does not have a separate state that is kept -in sync with the property value -- its state is the property value. - -For example, it might be useful to create a #GAction corresponding to -the "visible-child-name" property of a #GtkStack so that the current -page can be switched from a menu. The active radio indication in the -menu is then directly determined from the active page of the -#GtkStack. - -An anti-example would be binding the "active-id" property on a -#GtkComboBox. This is because the state of the combobox itself is -probably uninteresting and is actually being used to control -something else. - -Another anti-example would be to bind to the "visible-child-name" -property of a #GtkStack if this value is actually stored in -#GSettings. In that case, the real source of the value is -#GSettings. If you want a #GAction to control a setting stored in -#GSettings, see g_settings_create_action() instead, and possibly -combine its use with g_settings_bind(). +between). `GPropertyAction` does not have a separate state that is kept +in sync with the property value — its state is the property value. + +For example, it might be useful to create a [iface@Gio.Action] corresponding +to the `visible-child-name` property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html) +so that the current page can be switched from a menu. The active radio +indication in the menu is then directly determined from the active page of +the `GtkStack`. + +An anti-example would be binding the `active-id` property on a +[`GtkComboBox`](https://docs.gtk.org/gtk4/class.ComboBox.html). This is +because the state of the combo box itself is probably uninteresting and is +actually being used to control something else. + +Another anti-example would be to bind to the `visible-child-name` +property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html) if +this value is actually stored in [class@Gio.Settings]. In that case, the +real source of the value is* [class@Gio.Settings]. If you want +a [iface@Gio.Action] to control a setting stored in [class@Gio.Settings], +see [method@Gio.Settings.create_action] instead, and possibly combine its +use with [method@Gio.Settings.bind]. Creates a #GAction corresponding to the value of property + filename="gio/gpropertyaction.c" + line="584">Creates a #GAction corresponding to the value of property @property_name on @object. The property must be existent and readable and writable (and not @@ -90254,31 +94077,31 @@ construct-only). This function takes a reference on @object and doesn't release it until the action is destroyed. - + a new #GPropertyAction + filename="gio/gpropertyaction.c" + line="600">a new #GPropertyAction the name of the action to create + filename="gio/gpropertyaction.c" + line="586">the name of the action to create the object that has the property + filename="gio/gpropertyaction.c" + line="587">the object that has the property to wrap the name of the property + filename="gio/gpropertyaction.c" + line="589">the name of the property @@ -90288,8 +94111,8 @@ until the action is destroyed. transfer-ownership="none" default-value="TRUE"> If @action is currently enabled. + filename="gio/gpropertyaction.c" + line="491">If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. @@ -90302,8 +94125,8 @@ g_action_change_state() have no effect. transfer-ownership="none" default-value="FALSE"> If %TRUE, the state of the action will be the negation of the + filename="gio/gpropertyaction.c" + line="568">If %TRUE, the state of the action will be the negation of the property value, provided the property is boolean. @@ -90314,8 +94137,8 @@ property value, provided the property is boolean. transfer-ownership="none" default-value="NULL"> The name of the action. This is mostly meaningful for identifying + filename="gio/gpropertyaction.c" + line="462">The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GActionMap. @@ -90326,16 +94149,16 @@ the action once it has been added to a #GActionMap. construct-only="1" transfer-ownership="none"> The object to wrap a property on. + filename="gio/gpropertyaction.c" + line="535">The object to wrap a property on. The object must be a non-%NULL #GObject with properties. The type of the parameter that must be given when activating the + filename="gio/gpropertyaction.c" + line="477">The type of the parameter that must be given when activating the action. @@ -90347,8 +94170,8 @@ action. transfer-ownership="none" default-value="NULL"> The name of the property to wrap on the object. + filename="gio/gpropertyaction.c" + line="551">The name of the property to wrap on the object. The property must exist on the passed-in object and it must be readable and writable (and not construct-only). @@ -90356,14 +94179,14 @@ readable and writable (and not construct-only). The state of the action, or %NULL if the action is stateless. + filename="gio/gpropertyaction.c" + line="521">The state of the action, or %NULL if the action is stateless. The #GVariantType of the state that the action has, or %NULL if the + filename="gio/gpropertyaction.c" + line="507">The #GVariantType of the state that the action has, or %NULL if the action is stateless. @@ -90376,34 +94199,34 @@ action is stateless. glib:get-type="g_proxy_get_type" glib:type-struct="ProxyInterface"> A #GProxy handles connecting to a remote host via a given type of -proxy server. It is implemented by the 'gio-proxy' extension point. + filename="gio/gproxy.c" + line="31">A `GProxy` handles connecting to a remote host via a given type of +proxy server. It is implemented by the `gio-proxy` extension point. The extensions are named after their proxy protocol name. As an example, a SOCKS5 proxy implementation can be retrieved with the -name 'socks5' using the function -g_io_extension_point_get_extension_by_name(). - +name `socks5` using the function +[method@Gio.IOExtensionPoint.get_extension_by_name]. + Find the `gio-proxy` extension point for a proxy implementation that supports + filename="gio/gproxy.c" + line="51">Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. - + return a #GProxy or NULL if protocol + filename="gio/gproxy.c" + line="58">return a #GProxy or NULL if protocol is not supported. the proxy protocol name (e.g. http, socks, etc) + filename="gio/gproxy.c" + line="53">the proxy protocol name (e.g. http, socks, etc) @@ -90411,18 +94234,19 @@ the specified protocol. + throws="1" + glib:async-func="connect_async"> Given @connection to communicate with a proxy (eg, a + filename="gio/gproxy.c" + line="82">Given @connection to communicate with a proxy (eg, a #GSocketConnection that is connected to the proxy server), this does the necessary handshake to connect to @proxy_address, and if required, wraps the #GIOStream to handle proxy payload. - + a #GIOStream that will replace @connection. This might + filename="gio/gproxy.c" + line="95">a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. @@ -90430,20 +94254,20 @@ required, wraps the #GIOStream to handle proxy payload. a #GProxy + filename="gio/gproxy.c" + line="84">a #GProxy a #GIOStream + filename="gio/gproxy.c" + line="85">a #GIOStream a #GProxyAddress + filename="gio/gproxy.c" + line="86">a #GProxyAddress nullable="1" allow-none="1"> a #GCancellable + filename="gio/gproxy.c" + line="87">a #GCancellable + version="2.26" + glib:finish-func="connect_finish" + glib:sync-func="connect"> Asynchronous version of g_proxy_connect(). - + filename="gio/gproxy.c" + line="121">Asynchronous version of g_proxy_connect(). + a #GProxy + filename="gio/gproxy.c" + line="123">a #GProxy a #GIOStream + filename="gio/gproxy.c" + line="124">a #GIOStream a #GProxyAddress + filename="gio/gproxy.c" + line="125">a #GProxyAddress nullable="1" allow-none="1"> a #GCancellable + filename="gio/gproxy.c" + line="126">a #GCancellable scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gproxy.c" + line="127">a #GAsyncReadyCallback allow-none="1" closure="4"> callback data + filename="gio/gproxy.c" + line="128">callback data @@ -90523,26 +94349,26 @@ required, wraps the #GIOStream to handle proxy payload. version="2.26" throws="1"> See g_proxy_connect(). - + filename="gio/gproxy.c" + line="156">See g_proxy_connect(). + a #GIOStream. + filename="gio/gproxy.c" + line="164">a #GIOStream. a #GProxy + filename="gio/gproxy.c" + line="158">a #GProxy a #GAsyncResult + filename="gio/gproxy.c" + line="159">a #GAsyncResult @@ -90551,26 +94377,26 @@ required, wraps the #GIOStream to handle proxy payload. invoker="supports_hostname" version="2.26"> Some proxy protocols expect to be passed a hostname, which they + filename="gio/gproxy.c" + line="182">Some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return %FALSE if @proxy is implementing such a protocol. When %FALSE is returned, the caller should resolve the destination hostname first, and then pass a #GProxyAddress containing the stringified IP address to g_proxy_connect() or g_proxy_connect_async(). - + %TRUE if hostname resolution is supported. + filename="gio/gproxy.c" + line="194">%TRUE if hostname resolution is supported. a #GProxy + filename="gio/gproxy.c" + line="184">a #GProxy @@ -90578,18 +94404,19 @@ g_proxy_connect() or g_proxy_connect_async(). + throws="1" + glib:async-func="connect_async"> Given @connection to communicate with a proxy (eg, a + filename="gio/gproxy.c" + line="82">Given @connection to communicate with a proxy (eg, a #GSocketConnection that is connected to the proxy server), this does the necessary handshake to connect to @proxy_address, and if required, wraps the #GIOStream to handle proxy payload. - + a #GIOStream that will replace @connection. This might + filename="gio/gproxy.c" + line="95">a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. @@ -90597,20 +94424,20 @@ required, wraps the #GIOStream to handle proxy payload. a #GProxy + filename="gio/gproxy.c" + line="84">a #GProxy a #GIOStream + filename="gio/gproxy.c" + line="85">a #GIOStream a #GProxyAddress + filename="gio/gproxy.c" + line="86">a #GProxyAddress nullable="1" allow-none="1"> a #GCancellable + filename="gio/gproxy.c" + line="87">a #GCancellable + version="2.26" + glib:finish-func="connect_finish" + glib:sync-func="connect"> Asynchronous version of g_proxy_connect(). - + filename="gio/gproxy.c" + line="121">Asynchronous version of g_proxy_connect(). + a #GProxy + filename="gio/gproxy.c" + line="123">a #GProxy a #GIOStream + filename="gio/gproxy.c" + line="124">a #GIOStream a #GProxyAddress + filename="gio/gproxy.c" + line="125">a #GProxyAddress nullable="1" allow-none="1"> a #GCancellable + filename="gio/gproxy.c" + line="126">a #GCancellable scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gproxy.c" + line="127">a #GAsyncReadyCallback nullable="1" allow-none="1"> callback data + filename="gio/gproxy.c" + line="128">callback data @@ -90689,26 +94518,26 @@ required, wraps the #GIOStream to handle proxy payload. version="2.26" throws="1"> See g_proxy_connect(). - + filename="gio/gproxy.c" + line="156">See g_proxy_connect(). + a #GIOStream. + filename="gio/gproxy.c" + line="164">a #GIOStream. a #GProxy + filename="gio/gproxy.c" + line="158">a #GProxy a #GAsyncResult + filename="gio/gproxy.c" + line="159">a #GAsyncResult @@ -90717,26 +94546,26 @@ required, wraps the #GIOStream to handle proxy payload. c:identifier="g_proxy_supports_hostname" version="2.26"> Some proxy protocols expect to be passed a hostname, which they + filename="gio/gproxy.c" + line="182">Some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return %FALSE if @proxy is implementing such a protocol. When %FALSE is returned, the caller should resolve the destination hostname first, and then pass a #GProxyAddress containing the stringified IP address to g_proxy_connect() or g_proxy_connect_async(). - + %TRUE if hostname resolution is supported. + filename="gio/gproxy.c" + line="194">%TRUE if hostname resolution is supported. a #GProxy + filename="gio/gproxy.c" + line="184">a #GProxy @@ -90751,57 +94580,57 @@ g_proxy_connect() or g_proxy_connect_async(). glib:get-type="g_proxy_address_get_type" glib:type-struct="ProxyAddressClass"> Support for proxied #GInetSocketAddress. - + filename="gio/gproxyaddress.c" + line="32">A [class@Gio.InetSocketAddress] representing a connection via a proxy server. + Creates a new #GProxyAddress for @inetaddr with @protocol that should + filename="gio/gproxyaddress.c" + line="308">Creates a new #GProxyAddress for @inetaddr with @protocol that should tunnel through @dest_hostname and @dest_port. (Note that this method doesn't set the #GProxyAddress:uri or #GProxyAddress:destination-protocol fields; use g_object_new() directly if you want to set those.) - + a new #GProxyAddress + filename="gio/gproxyaddress.c" + line="327">a new #GProxyAddress The proxy server #GInetAddress. + filename="gio/gproxyaddress.c" + line="310">The proxy server #GInetAddress. The proxy server port. + filename="gio/gproxyaddress.c" + line="311">The proxy server port. The proxy protocol to support, in lower case (e.g. socks, http). + filename="gio/gproxyaddress.c" + line="312">The proxy protocol to support, in lower case (e.g. socks, http). The destination hostname the proxy should tunnel to. + filename="gio/gproxyaddress.c" + line="313">The destination hostname the proxy should tunnel to. The destination port to tunnel to. + filename="gio/gproxyaddress.c" + line="314">The destination port to tunnel to. nullable="1" allow-none="1"> The username to authenticate to the proxy server + filename="gio/gproxyaddress.c" + line="315">The username to authenticate to the proxy server (or %NULL). @@ -90819,8 +94648,8 @@ directly if you want to set those.) nullable="1" allow-none="1"> The password to authenticate to the proxy server + filename="gio/gproxyaddress.c" + line="317">The password to authenticate to the proxy server (or %NULL). @@ -90831,22 +94660,22 @@ directly if you want to set those.) glib:get-property="destination-hostname" version="2.26"> Gets @proxy's destination hostname; that is, the name of the host + filename="gio/gproxyaddress.c" + line="385">Gets @proxy's destination hostname; that is, the name of the host that will be connected to via the proxy, not the name of the proxy itself. - + the @proxy's destination hostname + filename="gio/gproxyaddress.c" + line="393">the @proxy's destination hostname a #GProxyAddress + filename="gio/gproxyaddress.c" + line="387">a #GProxyAddress @@ -90856,22 +94685,22 @@ itself. glib:get-property="destination-port" version="2.26"> Gets @proxy's destination port; that is, the port on the + filename="gio/gproxyaddress.c" + line="403">Gets @proxy's destination port; that is, the port on the destination host that will be connected to via the proxy, not the port number of the proxy itself. - + the @proxy's destination port + filename="gio/gproxyaddress.c" + line="411">the @proxy's destination port a #GProxyAddress + filename="gio/gproxyaddress.c" + line="405">a #GProxyAddress @@ -90881,21 +94710,21 @@ port number of the proxy itself. glib:get-property="destination-protocol" version="2.34"> Gets the protocol that is being spoken to the destination + filename="gio/gproxyaddress.c" + line="368">Gets the protocol that is being spoken to the destination server; eg, "http" or "ftp". - + the @proxy's destination protocol + filename="gio/gproxyaddress.c" + line="375">the @proxy's destination protocol a #GProxyAddress + filename="gio/gproxyaddress.c" + line="370">a #GProxyAddress @@ -90905,20 +94734,20 @@ server; eg, "http" or "ftp". glib:get-property="password" version="2.26"> Gets @proxy's password. - + filename="gio/gproxyaddress.c" + line="437">Gets @proxy's password. + the @proxy's password + filename="gio/gproxyaddress.c" + line="443">the @proxy's password a #GProxyAddress + filename="gio/gproxyaddress.c" + line="439">a #GProxyAddress @@ -90928,20 +94757,20 @@ server; eg, "http" or "ftp". glib:get-property="protocol" version="2.26"> Gets @proxy's protocol. eg, "socks" or "http" - + filename="gio/gproxyaddress.c" + line="352">Gets @proxy's protocol. eg, "socks" or "http" + the @proxy's protocol + filename="gio/gproxyaddress.c" + line="358">the @proxy's protocol a #GProxyAddress + filename="gio/gproxyaddress.c" + line="354">a #GProxyAddress @@ -90951,20 +94780,20 @@ server; eg, "http" or "ftp". glib:get-property="uri" version="2.34"> Gets the proxy URI that @proxy was constructed from. - + filename="gio/gproxyaddress.c" + line="454">Gets the proxy URI that @proxy was constructed from. + the @proxy's URI, or %NULL if unknown + filename="gio/gproxyaddress.c" + line="460">the @proxy's URI, or %NULL if unknown a #GProxyAddress + filename="gio/gproxyaddress.c" + line="456">a #GProxyAddress @@ -90974,38 +94803,46 @@ server; eg, "http" or "ftp". glib:get-property="username" version="2.26"> Gets @proxy's username. - + filename="gio/gproxyaddress.c" + line="421">Gets @proxy's username. + the @proxy's username + filename="gio/gproxyaddress.c" + line="427">the @proxy's username a #GProxyAddress + filename="gio/gproxyaddress.c" + line="423">a #GProxyAddress + The proxy destination hostname. + The proxy destination port. getter="get_destination_protocol" default-value="NULL"> The protocol being spoke to the destination host, or %NULL if + filename="gio/gproxyaddress.c" + line="234">The protocol being spoke to the destination host, or %NULL if the #GProxyAddress doesn't know. + The proxy password. + The proxy protocol. getter="get_uri" default-value="NULL"> The URI string that the proxy was constructed from (or %NULL + filename="gio/gproxyaddress.c" + line="280">The URI string that the proxy was constructed from (or %NULL if the creator didn't specify this). + The proxy username. @@ -91070,9 +94919,9 @@ if the creator didn't specify this). glib:is-gtype-struct-for="ProxyAddress" version="2.26"> Class structure for #GProxyAddress. - + filename="gio/gproxyaddress.c" + line="40">Class structure for #GProxyAddress. + @@ -91085,21 +94934,25 @@ if the creator didn't specify this). glib:get-type="g_proxy_address_enumerator_get_type" glib:type-struct="ProxyAddressEnumeratorClass"> #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which -takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator -and wraps them in #GProxyAddress instances, using the given -#GProxyAddressEnumerator:proxy-resolver. + filename="gio/gproxyaddressenumerator.c" + line="44">`GProxyAddressEnumerator` is a wrapper around +[class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress] +instances returned by the [class@Gio.SocketAddressEnumerator] +and wraps them in [class@Gio.ProxyAddress] instances, using the given +[property@Gio.ProxyAddressEnumerator:proxy-resolver]. This enumerator will be returned (for example, by -g_socket_connectable_enumerate()) as appropriate when a proxy is configured; -there should be no need to manually wrap a #GSocketAddressEnumerator instance -with one. - +[method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is +configured; there should be no need to manually wrap a +[class@Gio.SocketAddressEnumerator] instance with one. + + The connectable being enumerated. transfer-ownership="none" default-value="0"> The default port to use if #GProxyAddressEnumerator:uri does not + filename="gio/gproxyaddressenumerator.c" + line="760">The default port to use if #GProxyAddressEnumerator:uri does not specify one. @@ -91120,8 +94973,8 @@ specify one. construct="1" transfer-ownership="none"> The proxy resolver to use. + filename="gio/gproxyaddressenumerator.c" + line="789">The proxy resolver to use. construct-only="1" transfer-ownership="none" default-value="NULL"> + The destination URI. Use `none://` for a generic socket. @@ -91144,16 +95000,16 @@ specify one. c:type="GProxyAddressEnumeratorClass" glib:is-gtype-struct-for="ProxyAddressEnumerator"> Class structure for #GProxyAddressEnumerator. - + filename="gio/gproxyaddressenumerator.h" + line="51">Class structure for #GProxyAddressEnumerator. + - + @@ -91161,7 +95017,7 @@ specify one. - + @@ -91169,7 +95025,7 @@ specify one. - + @@ -91177,7 +95033,7 @@ specify one. - + @@ -91185,7 +95041,7 @@ specify one. - + @@ -91193,7 +95049,7 @@ specify one. - + @@ -91201,7 +95057,7 @@ specify one. - + @@ -91212,35 +95068,39 @@ specify one. c:type="GProxyAddressEnumeratorPrivate" disguised="1" opaque="1"> - + - + Provides an interface for handling proxy connection and payload. - + filename="gio/gproxy.h" + line="53">Provides an interface for handling proxy connection and payload. + The parent interface. + filename="gio/gproxy.h" + line="55">The parent interface. + Connect to proxy server and wrap (if required) the #connection + to handle payload. - + a #GIOStream that will replace @connection. This might + filename="gio/gproxy.c" + line="95">a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. @@ -91248,20 +95108,20 @@ specify one. a #GProxy + filename="gio/gproxy.c" + line="84">a #GProxy a #GIOStream + filename="gio/gproxy.c" + line="85">a #GIOStream a #GProxyAddress + filename="gio/gproxy.c" + line="86">a #GProxyAddress nullable="1" allow-none="1"> a #GCancellable + filename="gio/gproxy.c" + line="87">a #GCancellable + Same as connect() but asynchronous. - + a #GProxy + filename="gio/gproxy.c" + line="123">a #GProxy a #GIOStream + filename="gio/gproxy.c" + line="124">a #GIOStream a #GProxyAddress + filename="gio/gproxy.c" + line="125">a #GProxyAddress nullable="1" allow-none="1"> a #GCancellable + filename="gio/gproxy.c" + line="126">a #GCancellable scope="async" closure="5"> a #GAsyncReadyCallback + filename="gio/gproxy.c" + line="127">a #GAsyncReadyCallback allow-none="1" closure="5"> callback data + filename="gio/gproxy.c" + line="128">callback data + Returns the result of connect_async() - + a #GIOStream. + filename="gio/gproxy.c" + line="164">a #GIOStream. a #GProxy + filename="gio/gproxy.c" + line="158">a #GProxy a #GAsyncResult + filename="gio/gproxy.c" + line="159">a #GAsyncResult + Returns whether the proxy supports hostname lookups. - + %TRUE if hostname resolution is supported. + filename="gio/gproxy.c" + line="194">%TRUE if hostname resolution is supported. a #GProxy + filename="gio/gproxy.c" + line="184">a #GProxy @@ -91387,26 +95256,27 @@ specify one. glib:get-type="g_proxy_resolver_get_type" glib:type-struct="ProxyResolverInterface"> #GProxyResolver provides synchronous and asynchronous network proxy -resolution. #GProxyResolver is used within #GSocketClient through -the method g_socket_connectable_proxy_enumerate(). + filename="gio/gproxyresolver.c" + line="38">`GProxyResolver` provides synchronous and asynchronous network proxy +resolution. `GProxyResolver` is used within [class@Gio.SocketClient] through +the method [method@Gio.SocketConnectable.proxy_enumerate]. -Implementations of #GProxyResolver based on libproxy and GNOME settings can -be found in glib-networking. GIO comes with an implementation for use inside -Flatpak portals. - +Implementations of `GProxyResolver` based on +[libproxy](https://github.com/libproxy/libproxy) and GNOME settings can be +found in [glib-networking](https://gitlab.gnome.org/GNOME/glib-networking). +GIO comes with an implementation for use inside Flatpak portals. + Gets the default #GProxyResolver for the system. - + filename="gio/gproxyresolver.c" + line="75">Gets the default #GProxyResolver for the system. + the default #GProxyResolver, which + filename="gio/gproxyresolver.c" + line="80">the default #GProxyResolver, which will be a dummy object if no proxy resolver is available @@ -91415,33 +95285,37 @@ Flatpak portals. invoker="is_supported" version="2.26"> Checks if @resolver can be used on this system. (This is used + filename="gio/gproxyresolver.c" + line="102">Checks if @resolver can be used on this system. (This is used internally; g_proxy_resolver_get_default() will only return a proxy resolver that returns %TRUE for this method.) - + %TRUE if @resolver is supported. + filename="gio/gproxyresolver.c" + line="110">%TRUE if @resolver is supported. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="104">a #GProxyResolver - + Looks into the system proxy configuration to determine what proxy, + filename="gio/gproxyresolver.c" + line="126">Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or -`direct://`, where <protocol> could be http, rtsp, socks +`direct://`, where `<protocol>` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the @@ -91453,11 +95327,11 @@ In this case, the resolver might still return a generic proxy type `direct://` is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies. - + A + filename="gio/gproxyresolver.c" + line="149">A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). @@ -91467,14 +95341,14 @@ returned array of proxies. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="128">a #GProxyResolver a URI representing the destination to connect to + filename="gio/gproxyresolver.c" + line="129">a URI representing the destination to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gproxyresolver.c" + line="130">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="lookup_finish" + glib:sync-func="lookup"> Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more + filename="gio/gproxyresolver.c" + line="182">Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more details. - + a #GProxyResolver + filename="gio/gproxyresolver.c" + line="184">a #GProxyResolver a URI representing the destination to connect to + filename="gio/gproxyresolver.c" + line="185">a URI representing the destination to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gproxyresolver.c" + line="186">a #GCancellable, or %NULL scope="async" closure="3"> callback to call after resolution completes + filename="gio/gproxyresolver.c" + line="187">callback to call after resolution completes allow-none="1" closure="3"> data for @callback + filename="gio/gproxyresolver.c" + line="188">data for @callback @@ -91549,15 +95425,15 @@ details. version="2.26" throws="1"> Call this function to obtain the array of proxy URIs when + filename="gio/gproxyresolver.c" + line="223">Call this function to obtain the array of proxy URIs when g_proxy_resolver_lookup_async() is complete. See g_proxy_resolver_lookup() for more details. - + A + filename="gio/gproxyresolver.c" + line="233">A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). @@ -91567,14 +95443,14 @@ g_proxy_resolver_lookup() for more details. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="225">a #GProxyResolver the result passed to your #GAsyncReadyCallback + filename="gio/gproxyresolver.c" + line="226">the result passed to your #GAsyncReadyCallback @@ -91583,22 +95459,22 @@ g_proxy_resolver_lookup() for more details. c:identifier="g_proxy_resolver_is_supported" version="2.26"> Checks if @resolver can be used on this system. (This is used + filename="gio/gproxyresolver.c" + line="102">Checks if @resolver can be used on this system. (This is used internally; g_proxy_resolver_get_default() will only return a proxy resolver that returns %TRUE for this method.) - + %TRUE if @resolver is supported. + filename="gio/gproxyresolver.c" + line="110">%TRUE if @resolver is supported. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="104">a #GProxyResolver @@ -91606,13 +95482,14 @@ resolver that returns %TRUE for this method.) + throws="1" + glib:async-func="lookup_async"> Looks into the system proxy configuration to determine what proxy, + filename="gio/gproxyresolver.c" + line="126">Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or -`direct://`, where <protocol> could be http, rtsp, socks +`direct://`, where `<protocol>` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the @@ -91624,11 +95501,11 @@ In this case, the resolver might still return a generic proxy type `direct://` is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies. - + A + filename="gio/gproxyresolver.c" + line="149">A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). @@ -91638,14 +95515,14 @@ returned array of proxies. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="128">a #GProxyResolver a URI representing the destination to connect to + filename="gio/gproxyresolver.c" + line="129">a URI representing the destination to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gproxyresolver.c" + line="130">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="lookup_finish" + glib:sync-func="lookup"> Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more + filename="gio/gproxyresolver.c" + line="182">Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more details. - + a #GProxyResolver + filename="gio/gproxyresolver.c" + line="184">a #GProxyResolver a URI representing the destination to connect to + filename="gio/gproxyresolver.c" + line="185">a URI representing the destination to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gproxyresolver.c" + line="186">a #GCancellable, or %NULL scope="async" closure="3"> callback to call after resolution completes + filename="gio/gproxyresolver.c" + line="187">callback to call after resolution completes nullable="1" allow-none="1"> data for @callback + filename="gio/gproxyresolver.c" + line="188">data for @callback @@ -91719,15 +95598,15 @@ details. version="2.26" throws="1"> Call this function to obtain the array of proxy URIs when + filename="gio/gproxyresolver.c" + line="223">Call this function to obtain the array of proxy URIs when g_proxy_resolver_lookup_async() is complete. See g_proxy_resolver_lookup() for more details. - + A + filename="gio/gproxyresolver.c" + line="233">A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). @@ -91737,14 +95616,14 @@ g_proxy_resolver_lookup() for more details. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="225">a #GProxyResolver the result passed to your #GAsyncReadyCallback + filename="gio/gproxyresolver.c" + line="226">the result passed to your #GAsyncReadyCallback @@ -91754,41 +95633,47 @@ g_proxy_resolver_lookup() for more details. c:type="GProxyResolverInterface" glib:is-gtype-struct-for="ProxyResolver"> The virtual function table for #GProxyResolver. - + filename="gio/gproxyresolver.c" + line="53">The virtual function table for #GProxyResolver. + The parent interface. + filename="gio/gproxyresolver.c" + line="55">The parent interface. + the virtual function pointer for g_proxy_resolver_is_supported() - + %TRUE if @resolver is supported. + filename="gio/gproxyresolver.c" + line="110">%TRUE if @resolver is supported. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="104">a #GProxyResolver + the virtual function pointer for g_proxy_resolver_lookup() - + A + filename="gio/gproxyresolver.c" + line="149">A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). @@ -91798,14 +95683,14 @@ g_proxy_resolver_lookup() for more details. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="128">a #GProxyResolver a URI representing the destination to connect to + filename="gio/gproxyresolver.c" + line="129">a URI representing the destination to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gproxyresolver.c" + line="130">a #GCancellable, or %NULL + the virtual function pointer for + g_proxy_resolver_lookup_async() - + a #GProxyResolver + filename="gio/gproxyresolver.c" + line="184">a #GProxyResolver a URI representing the destination to connect to + filename="gio/gproxyresolver.c" + line="185">a URI representing the destination to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gproxyresolver.c" + line="186">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gproxyresolver.c" + line="187">callback to call after resolution completes allow-none="1" closure="4"> data for @callback + filename="gio/gproxyresolver.c" + line="188">data for @callback + the virtual function pointer for + g_proxy_resolver_lookup_finish() - + A + filename="gio/gproxyresolver.c" + line="233">A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). @@ -91888,14 +95781,14 @@ g_proxy_resolver_lookup() for more details. a #GProxyResolver + filename="gio/gproxyresolver.c" + line="225">a #GProxyResolver the result passed to your #GAsyncReadyCallback + filename="gio/gproxyresolver.c" + line="226">the result passed to your #GAsyncReadyCallback @@ -91905,7 +95798,7 @@ g_proxy_resolver_lookup() for more details. - + @@ -91914,7 +95807,7 @@ g_proxy_resolver_lookup() for more details. - + @@ -91923,7 +95816,7 @@ g_proxy_resolver_lookup() for more details. - + @@ -91932,7 +95825,7 @@ g_proxy_resolver_lookup() for more details. - + @@ -91941,7 +95834,7 @@ g_proxy_resolver_lookup() for more details. - + @@ -91949,16 +95842,16 @@ g_proxy_resolver_lookup() for more details. Changes the size of the memory block pointed to by @data to + filename="gio/gmemoryoutputstream.h" + line="65">Changes the size of the memory block pointed to by @data to @size bytes. The function should have the same semantics as realloc(). - + a pointer to the reallocated memory + filename="gio/gmemoryoutputstream.h" + line="75">a pointer to the reallocated memory @@ -91967,14 +95860,14 @@ The function should have the same semantics as realloc(). nullable="1" allow-none="1"> memory block to reallocate + filename="gio/gmemoryoutputstream.h" + line="67">memory block to reallocate size to reallocate @data to + filename="gio/gmemoryoutputstream.h" + line="68">size to reallocate @data to @@ -91987,36 +95880,36 @@ The function should have the same semantics as realloc(). glib:get-type="g_remote_action_group_get_type" glib:type-struct="RemoteActionGroupInterface"> The GRemoteActionGroup interface is implemented by #GActionGroup + filename="gio/gremoteactiongroup.c" + line="29">The `GRemoteActionGroup` interface is implemented by [iface@Gio.ActionGroup] instances that either transmit action invocations to other processes or receive action invocations in the local process from other processes. The interface has `_full` variants of the two -methods on #GActionGroup used to activate actions: -g_action_group_activate_action() and -g_action_group_change_action_state(). These variants allow a -"platform data" #GVariant to be specified: a dictionary providing +methods on [iface@Gio.ActionGroup] used to activate actions: +[method@Gio.ActionGroup.activate_action] and +[method@Gio.ActionGroup.change_action_state]. These variants allow a +‘platform data’ [struct@GLib.Variant] to be specified: a dictionary providing context for the action invocation (for example: timestamps, startup notification IDs, etc). -#GDBusActionGroup implements #GRemoteActionGroup. This provides a +[class@Gio.DBusActionGroup] implements `GRemoteActionGroup`. This provides a mechanism to send platform data for action invocations over D-Bus. -Additionally, g_dbus_connection_export_action_group() will check if -the exported #GActionGroup implements #GRemoteActionGroup and use the -`_full` variants of the calls if available. This +Additionally, [method@Gio.DBusConnection.export_action_group] will check if +the exported [iface@Gio.ActionGroup] implements `GRemoteActionGroup` and use +the `_full` variants of the calls if available. This provides a mechanism by which to receive platform data for action invocations that arrive by way of D-Bus. - + Activates the remote action. + filename="gio/gremoteactiongroup.c" + line="78">Activates the remote action. This is the same as g_action_group_activate_action() except that it allows for provision of "platform data" to be sent along with the @@ -92025,21 +95918,21 @@ interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - + a #GDBusActionGroup + filename="gio/gremoteactiongroup.c" + line="80">a #GDBusActionGroup the name of the action to activate + filename="gio/gremoteactiongroup.c" + line="81">the name of the action to activate the optional parameter to the activation + filename="gio/gremoteactiongroup.c" + line="82">the optional parameter to the activation the platform data to send + filename="gio/gremoteactiongroup.c" + line="83">the platform data to send @@ -92063,8 +95956,8 @@ interaction timestamp or startup notification information. invoker="change_action_state_full" version="2.32"> Changes the state of a remote action. + filename="gio/gremoteactiongroup.c" + line="107">Changes the state of a remote action. This is the same as g_action_group_change_action_state() except that it allows for provision of "platform data" to be sent along with the @@ -92073,33 +95966,33 @@ user interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - + a #GRemoteActionGroup + filename="gio/gremoteactiongroup.c" + line="109">a #GRemoteActionGroup the name of the action to change the state of + filename="gio/gremoteactiongroup.c" + line="110">the name of the action to change the state of the new requested value for the state + filename="gio/gremoteactiongroup.c" + line="111">the new requested value for the state the platform data to send + filename="gio/gremoteactiongroup.c" + line="112">the platform data to send @@ -92108,8 +96001,8 @@ user interaction timestamp or startup notification information. c:identifier="g_remote_action_group_activate_action_full" version="2.32"> Activates the remote action. + filename="gio/gremoteactiongroup.c" + line="78">Activates the remote action. This is the same as g_action_group_activate_action() except that it allows for provision of "platform data" to be sent along with the @@ -92118,21 +96011,21 @@ interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - + a #GDBusActionGroup + filename="gio/gremoteactiongroup.c" + line="80">a #GDBusActionGroup the name of the action to activate + filename="gio/gremoteactiongroup.c" + line="81">the name of the action to activate the optional parameter to the activation + filename="gio/gremoteactiongroup.c" + line="82">the optional parameter to the activation the platform data to send + filename="gio/gremoteactiongroup.c" + line="83">the platform data to send @@ -92156,8 +96049,8 @@ interaction timestamp or startup notification information. c:identifier="g_remote_action_group_change_action_state_full" version="2.32"> Changes the state of a remote action. + filename="gio/gremoteactiongroup.c" + line="107">Changes the state of a remote action. This is the same as g_action_group_change_action_state() except that it allows for provision of "platform data" to be sent along with the @@ -92166,33 +96059,33 @@ user interaction timestamp or startup notification information. @platform_data must be non-%NULL and must have the type %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - + a #GRemoteActionGroup + filename="gio/gremoteactiongroup.c" + line="109">a #GRemoteActionGroup the name of the action to change the state of + filename="gio/gremoteactiongroup.c" + line="110">the name of the action to change the state of the new requested value for the state + filename="gio/gremoteactiongroup.c" + line="111">the new requested value for the state the platform data to send + filename="gio/gremoteactiongroup.c" + line="112">the platform data to send @@ -92203,29 +96096,32 @@ user interaction timestamp or startup notification information. glib:is-gtype-struct-for="RemoteActionGroup" version="2.32"> The virtual function table for #GRemoteActionGroup. - + filename="gio/gremoteactiongroup.c" + line="57">The virtual function table for #GRemoteActionGroup. + + the virtual function pointer for g_remote_action_group_activate_action_full() - + a #GDBusActionGroup + filename="gio/gremoteactiongroup.c" + line="80">a #GDBusActionGroup the name of the action to activate + filename="gio/gremoteactiongroup.c" + line="81">the name of the action to activate the optional parameter to the activation + filename="gio/gremoteactiongroup.c" + line="82">the optional parameter to the activation the platform data to send + filename="gio/gremoteactiongroup.c" + line="83">the platform data to send + the virtual function pointer for g_remote_action_group_change_action_state_full() - + a #GRemoteActionGroup + filename="gio/gremoteactiongroup.c" + line="109">a #GRemoteActionGroup the name of the action to change the state of + filename="gio/gremoteactiongroup.c" + line="110">the name of the action to change the state of the new requested value for the state + filename="gio/gremoteactiongroup.c" + line="111">the new requested value for the state the platform data to send + filename="gio/gremoteactiongroup.c" + line="112">the platform data to send @@ -92290,39 +96189,46 @@ user interaction timestamp or startup notification information. glib:get-type="g_resolver_get_type" glib:type-struct="ResolverClass"> #GResolver provides cancellable synchronous and asynchronous DNS -resolution, for hostnames (g_resolver_lookup_by_address(), -g_resolver_lookup_by_name() and their async variants) and SRV -(service) records (g_resolver_lookup_service()). + filename="gio/gresolver.c" + line="45">The object that handles DNS resolution. Use [func@Gio.Resolver.get_default] +to get the default resolver. + +`GResolver` provides cancellable synchronous and asynchronous DNS +resolution, for hostnames ([method@Gio.Resolver.lookup_by_address], +[method@Gio.Resolver.lookup_by_name] and their async variants) and SRV +(service) records ([method@Gio.Resolver.lookup_service]). + +[class@Gio.NetworkAddress] and [class@Gio.NetworkService] provide wrappers +around `GResolver` functionality that also implement +[iface@Gio.SocketConnectable], making it easy to connect to a remote +host/service. -#GNetworkAddress and #GNetworkService provide wrappers around -#GResolver functionality that also implement #GSocketConnectable, -making it easy to connect to a remote host/service. +The default resolver (see [func@Gio.Resolver.get_default]) has a timeout of +30s set on it since GLib 2.78. Earlier versions of GLib did not support +resolver timeouts. -The default resolver (see g_resolver_get_default()) has a timeout of 30s set -on it since GLib 2.78. Earlier versions of GLib did not support resolver -timeouts. - +This is an abstract type; subclasses of it implement different resolvers for +different platforms and situations. + Frees @addresses (which should be the return value from + filename="gio/gresolver.c" + line="876">Frees @addresses (which should be the return value from g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). (This is a convenience method; you can also simply free the results by hand.) - + a #GList of #GInetAddress + filename="gio/gresolver.c" + line="878">a #GList of #GInetAddress @@ -92334,20 +96240,20 @@ by hand.) version="2.22" introspectable="0"> Frees @targets (which should be the return value from + filename="gio/gresolver.c" + line="1166">Frees @targets (which should be the return value from g_resolver_lookup_service() or g_resolver_lookup_service_finish()). (This is a convenience method; you can also simply free the results by hand.) - + a #GList of #GSrvTarget + filename="gio/gresolver.c" + line="1168">a #GList of #GSrvTarget @@ -92358,25 +96264,26 @@ results by hand.) c:identifier="g_resolver_get_default" version="2.22"> Gets the default #GResolver. You should unref it when you are done + filename="gio/gresolver.c" + line="282">Gets the default #GResolver. You should unref it when you are done with it. #GResolver may use its reference count as a hint about how many threads it should allocate for concurrent DNS resolutions. - + the default #GResolver. + filename="gio/gresolver.c" + line="289">the default #GResolver. + throws="1" + glib:async-func="lookup_by_address_async"> Synchronously reverse-resolves @address to determine its + filename="gio/gresolver.c" + line="897">Synchronously reverse-resolves @address to determine its associated hostname. If the DNS resolution fails, @error (if non-%NULL) will be set to @@ -92385,25 +96292,25 @@ a value from #GResolverError. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. - + a hostname (either ASCII-only, or in ASCII-encoded + filename="gio/gresolver.c" + line="914">a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver + filename="gio/gresolver.c" + line="899">a #GResolver the address to reverse-resolve + filename="gio/gresolver.c" + line="900">the address to reverse-resolve a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="901">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="lookup_by_address_finish" + glib:sync-func="lookup_by_address"> Begins asynchronously reverse-resolving @address to determine its + filename="gio/gresolver.c" + line="933">Begins asynchronously reverse-resolving @address to determine its associated hostname, and eventually calls @callback, which must call g_resolver_lookup_by_address_finish() to get the final result. - + a #GResolver + filename="gio/gresolver.c" + line="935">a #GResolver the address to reverse-resolve + filename="gio/gresolver.c" + line="936">the address to reverse-resolve nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="937">a #GCancellable, or %NULL scope="async" closure="3"> callback to call after resolution completes + filename="gio/gresolver.c" + line="938">callback to call after resolution completes allow-none="1" closure="3"> data for @callback + filename="gio/gresolver.c" + line="939">data for @callback @@ -92479,32 +96388,32 @@ call g_resolver_lookup_by_address_finish() to get the final result. version="2.22" throws="1"> Retrieves the result of a previous call to + filename="gio/gresolver.c" + line="962">Retrieves the result of a previous call to g_resolver_lookup_by_address_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a hostname (either ASCII-only, or in ASCII-encoded + filename="gio/gresolver.c" + line="975">a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver + filename="gio/gresolver.c" + line="964">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="965">the result passed to your #GAsyncReadyCallback @@ -92512,10 +96421,11 @@ form), or %NULL on error. + throws="1" + glib:async-func="lookup_by_name_async"> Synchronously resolves @hostname to determine its associated IP + filename="gio/gresolver.c" + line="558">Synchronously resolves @hostname to determine its associated IP address(es). @hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around g_inet_address_new_from_string()). @@ -92538,11 +96448,11 @@ operation, in which case @error (if non-%NULL) will be set to If you are planning to connect to a socket on the resolved IP address, it may be easier to create a #GNetworkAddress and use its #GSocketConnectable interface. - + a non-empty #GList + filename="gio/gresolver.c" + line="589">a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) @@ -92553,14 +96463,14 @@ done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver + filename="gio/gresolver.c" + line="560">a #GResolver the hostname to look up + filename="gio/gresolver.c" + line="561">the hostname to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="562">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="lookup_by_name_finish" + glib:sync-func="lookup_by_name"> Begins asynchronously resolving @hostname to determine its + filename="gio/gresolver.c" + line="786">Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_finish() to get the result. See g_resolver_lookup_by_name() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="788">a #GResolver the hostname to look up the address of + filename="gio/gresolver.c" + line="789">the hostname to look up the address of nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="790">a #GCancellable, or %NULL scope="async" closure="3"> callback to call after resolution completes + filename="gio/gresolver.c" + line="791">callback to call after resolution completes allow-none="1" closure="3"> data for @callback + filename="gio/gresolver.c" + line="792">data for @callback @@ -92637,18 +96549,18 @@ See g_resolver_lookup_by_name() for more details. version="2.22" throws="1"> Retrieves the result of a call to + filename="gio/gresolver.c" + line="816">Retrieves the result of a call to g_resolver_lookup_by_name_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a #GList + filename="gio/gresolver.c" + line="829">a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. @@ -92658,14 +96570,14 @@ for more details. a #GResolver + filename="gio/gresolver.c" + line="818">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="819">the result passed to your #GAsyncReadyCallback @@ -92673,17 +96585,18 @@ for more details. + throws="1" + glib:async-func="lookup_by_name_with_flags_async"> This differs from g_resolver_lookup_by_name() in that you can modify + filename="gio/gresolver.c" + line="609">This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with @flags. For example this can be used to limit results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. - + a non-empty #GList + filename="gio/gresolver.c" + line="621">a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) @@ -92694,20 +96607,20 @@ done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver + filename="gio/gresolver.c" + line="611">a #GResolver the hostname to look up + filename="gio/gresolver.c" + line="612">the hostname to look up extra #GResolverNameLookupFlags for the lookup + filename="gio/gresolver.c" + line="613">extra #GResolverNameLookupFlags for the lookup @@ -92716,42 +96629,44 @@ done with it. (You can use g_resolver_free_addresses() to do this.) nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="614">a #GCancellable, or %NULL + version="2.60" + glib:finish-func="lookup_by_name_with_flags_finish" + glib:sync-func="lookup_by_name_with_flags"> Begins asynchronously resolving @hostname to determine its + filename="gio/gresolver.c" + line="754">Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_with_flags_finish() to get the result. See g_resolver_lookup_by_name() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="756">a #GResolver the hostname to look up the address of + filename="gio/gresolver.c" + line="757">the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup + filename="gio/gresolver.c" + line="758">extra #GResolverNameLookupFlags for the lookup @@ -92760,8 +96675,8 @@ See g_resolver_lookup_by_name() for more details. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="759">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gresolver.c" + line="760">callback to call after resolution completes allow-none="1" closure="4"> data for @callback + filename="gio/gresolver.c" + line="761">data for @callback @@ -92792,18 +96707,18 @@ See g_resolver_lookup_by_name() for more details. version="2.60" throws="1"> Retrieves the result of a call to + filename="gio/gresolver.c" + line="846">Retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a #GList + filename="gio/gresolver.c" + line="859">a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. @@ -92813,14 +96728,14 @@ for more details. a #GResolver + filename="gio/gresolver.c" + line="848">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="849">the result passed to your #GAsyncReadyCallback @@ -92828,10 +96743,11 @@ for more details. + throws="1" + glib:async-func="lookup_records_async"> Synchronously performs a DNS record lookup for the given @rrname and returns + filename="gio/gresolver.c" + line="1187">Synchronously performs a DNS record lookup for the given @rrname and returns a list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain for each @record_type. @@ -92841,11 +96757,11 @@ a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1206">a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) @@ -92856,20 +96772,20 @@ g_variant_unref() to do this.) a #GResolver + filename="gio/gresolver.c" + line="1189">a #GResolver the DNS name to look up the record for + filename="gio/gresolver.c" + line="1190">the DNS name to look up the record for the type of DNS record to look up + filename="gio/gresolver.c" + line="1191">the type of DNS record to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1192">a #GCancellable, or %NULL + version="2.34" + glib:finish-func="lookup_records_finish" + glib:sync-func="lookup_records"> Begins asynchronously performing a DNS lookup for the given + filename="gio/gresolver.c" + line="1232">Begins asynchronously performing a DNS lookup for the given @rrname, and eventually calls @callback, which must call g_resolver_lookup_records_finish() to get the final result. See g_resolver_lookup_records() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="1234">a #GResolver the DNS name to look up the record for + filename="gio/gresolver.c" + line="1235">the DNS name to look up the record for the type of DNS record to look up + filename="gio/gresolver.c" + line="1236">the type of DNS record to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1237">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gresolver.c" + line="1238">callback to call after resolution completes allow-none="1" closure="4"> data for @callback + filename="gio/gresolver.c" + line="1239">data for @callback @@ -92952,8 +96870,8 @@ g_resolver_lookup_records() for more details. version="2.34" throws="1"> Retrieves the result of a previous call to + filename="gio/gresolver.c" + line="1264">Retrieves the result of a previous call to g_resolver_lookup_records_async(). Returns a non-empty list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain. @@ -92961,11 +96879,11 @@ records contain. If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1279">a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) @@ -92976,20 +96894,23 @@ g_variant_unref() to do this.) a #GResolver + filename="gio/gresolver.c" + line="1266">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="1267">the result passed to your #GAsyncReadyCallback - - + + @@ -93010,8 +96931,10 @@ g_variant_unref() to do this.) - - + + @@ -93050,18 +96973,18 @@ g_variant_unref() to do this.) version="2.22" throws="1"> Retrieves the result of a previous call to + filename="gio/gresolver.c" + line="1133">Retrieves the result of a previous call to g_resolver_lookup_service_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1146">a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. @@ -93071,20 +96994,20 @@ details. a #GResolver + filename="gio/gresolver.c" + line="1135">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="1136">the result passed to your #GAsyncReadyCallback - + @@ -93099,20 +97022,20 @@ details. glib:get-property="timeout" version="2.78"> Get the timeout applied to all resolver lookups. See #GResolver:timeout. - + filename="gio/gresolver.c" + line="1316">Get the timeout applied to all resolver lookups. See #GResolver:timeout. + the resolver timeout, in milliseconds, or `0` for no timeout + filename="gio/gresolver.c" + line="1322">the resolver timeout, in milliseconds, or `0` for no timeout a #GResolver + filename="gio/gresolver.c" + line="1318">a #GResolver @@ -93120,10 +97043,11 @@ details. + throws="1" + glib:async-func="lookup_by_address_async"> Synchronously reverse-resolves @address to determine its + filename="gio/gresolver.c" + line="897">Synchronously reverse-resolves @address to determine its associated hostname. If the DNS resolution fails, @error (if non-%NULL) will be set to @@ -93132,25 +97056,25 @@ a value from #GResolverError. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. - + a hostname (either ASCII-only, or in ASCII-encoded + filename="gio/gresolver.c" + line="914">a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver + filename="gio/gresolver.c" + line="899">a #GResolver the address to reverse-resolve + filename="gio/gresolver.c" + line="900">the address to reverse-resolve a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="901">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="lookup_by_address_finish" + glib:sync-func="lookup_by_address"> Begins asynchronously reverse-resolving @address to determine its + filename="gio/gresolver.c" + line="933">Begins asynchronously reverse-resolving @address to determine its associated hostname, and eventually calls @callback, which must call g_resolver_lookup_by_address_finish() to get the final result. - + a #GResolver + filename="gio/gresolver.c" + line="935">a #GResolver the address to reverse-resolve + filename="gio/gresolver.c" + line="936">the address to reverse-resolve nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="937">a #GCancellable, or %NULL scope="async" closure="3"> callback to call after resolution completes + filename="gio/gresolver.c" + line="938">callback to call after resolution completes nullable="1" allow-none="1"> data for @callback + filename="gio/gresolver.c" + line="939">data for @callback @@ -93225,32 +97151,32 @@ call g_resolver_lookup_by_address_finish() to get the final result. version="2.22" throws="1"> Retrieves the result of a previous call to + filename="gio/gresolver.c" + line="962">Retrieves the result of a previous call to g_resolver_lookup_by_address_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a hostname (either ASCII-only, or in ASCII-encoded + filename="gio/gresolver.c" + line="975">a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver + filename="gio/gresolver.c" + line="964">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="965">the result passed to your #GAsyncReadyCallback @@ -93258,10 +97184,11 @@ form), or %NULL on error. + throws="1" + glib:async-func="lookup_by_name_async"> Synchronously resolves @hostname to determine its associated IP + filename="gio/gresolver.c" + line="558">Synchronously resolves @hostname to determine its associated IP address(es). @hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around g_inet_address_new_from_string()). @@ -93284,11 +97211,11 @@ operation, in which case @error (if non-%NULL) will be set to If you are planning to connect to a socket on the resolved IP address, it may be easier to create a #GNetworkAddress and use its #GSocketConnectable interface. - + a non-empty #GList + filename="gio/gresolver.c" + line="589">a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) @@ -93299,14 +97226,14 @@ done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver + filename="gio/gresolver.c" + line="560">a #GResolver the hostname to look up + filename="gio/gresolver.c" + line="561">the hostname to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="562">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="lookup_by_name_finish" + glib:sync-func="lookup_by_name"> Begins asynchronously resolving @hostname to determine its + filename="gio/gresolver.c" + line="786">Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_finish() to get the result. See g_resolver_lookup_by_name() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="788">a #GResolver the hostname to look up the address of + filename="gio/gresolver.c" + line="789">the hostname to look up the address of nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="790">a #GCancellable, or %NULL scope="async" closure="3"> callback to call after resolution completes + filename="gio/gresolver.c" + line="791">callback to call after resolution completes nullable="1" allow-none="1"> data for @callback + filename="gio/gresolver.c" + line="792">data for @callback @@ -93382,18 +97311,18 @@ See g_resolver_lookup_by_name() for more details. version="2.22" throws="1"> Retrieves the result of a call to + filename="gio/gresolver.c" + line="816">Retrieves the result of a call to g_resolver_lookup_by_name_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a #GList + filename="gio/gresolver.c" + line="829">a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. @@ -93403,14 +97332,14 @@ for more details. a #GResolver + filename="gio/gresolver.c" + line="818">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="819">the result passed to your #GAsyncReadyCallback @@ -93418,17 +97347,18 @@ for more details. + throws="1" + glib:async-func="lookup_by_name_with_flags_async"> This differs from g_resolver_lookup_by_name() in that you can modify + filename="gio/gresolver.c" + line="609">This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with @flags. For example this can be used to limit results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. - + a non-empty #GList + filename="gio/gresolver.c" + line="621">a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) @@ -93439,20 +97369,20 @@ done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver + filename="gio/gresolver.c" + line="611">a #GResolver the hostname to look up + filename="gio/gresolver.c" + line="612">the hostname to look up extra #GResolverNameLookupFlags for the lookup + filename="gio/gresolver.c" + line="613">extra #GResolverNameLookupFlags for the lookup @@ -93461,42 +97391,44 @@ done with it. (You can use g_resolver_free_addresses() to do this.) nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="614">a #GCancellable, or %NULL + version="2.60" + glib:finish-func="lookup_by_name_with_flags_finish" + glib:sync-func="lookup_by_name_with_flags"> Begins asynchronously resolving @hostname to determine its + filename="gio/gresolver.c" + line="754">Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_with_flags_finish() to get the result. See g_resolver_lookup_by_name() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="756">a #GResolver the hostname to look up the address of + filename="gio/gresolver.c" + line="757">the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup + filename="gio/gresolver.c" + line="758">extra #GResolverNameLookupFlags for the lookup @@ -93505,8 +97437,8 @@ See g_resolver_lookup_by_name() for more details. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="759">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gresolver.c" + line="760">callback to call after resolution completes nullable="1" allow-none="1"> data for @callback + filename="gio/gresolver.c" + line="761">data for @callback @@ -93536,18 +97468,18 @@ See g_resolver_lookup_by_name() for more details. version="2.60" throws="1"> Retrieves the result of a call to + filename="gio/gresolver.c" + line="846">Retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a #GList + filename="gio/gresolver.c" + line="859">a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. @@ -93557,14 +97489,14 @@ for more details. a #GResolver + filename="gio/gresolver.c" + line="848">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="849">the result passed to your #GAsyncReadyCallback @@ -93572,10 +97504,11 @@ for more details. + throws="1" + glib:async-func="lookup_records_async"> Synchronously performs a DNS record lookup for the given @rrname and returns + filename="gio/gresolver.c" + line="1187">Synchronously performs a DNS record lookup for the given @rrname and returns a list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain for each @record_type. @@ -93585,11 +97518,11 @@ a value from #GResolverError and %NULL will be returned. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1206">a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) @@ -93600,20 +97533,20 @@ g_variant_unref() to do this.) a #GResolver + filename="gio/gresolver.c" + line="1189">a #GResolver the DNS name to look up the record for + filename="gio/gresolver.c" + line="1190">the DNS name to look up the record for the type of DNS record to look up + filename="gio/gresolver.c" + line="1191">the type of DNS record to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1192">a #GCancellable, or %NULL + version="2.34" + glib:finish-func="lookup_records_finish" + glib:sync-func="lookup_records"> Begins asynchronously performing a DNS lookup for the given + filename="gio/gresolver.c" + line="1232">Begins asynchronously performing a DNS lookup for the given @rrname, and eventually calls @callback, which must call g_resolver_lookup_records_finish() to get the final result. See g_resolver_lookup_records() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="1234">a #GResolver the DNS name to look up the record for + filename="gio/gresolver.c" + line="1235">the DNS name to look up the record for the type of DNS record to look up + filename="gio/gresolver.c" + line="1236">the type of DNS record to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1237">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gresolver.c" + line="1238">callback to call after resolution completes nullable="1" allow-none="1"> data for @callback + filename="gio/gresolver.c" + line="1239">data for @callback @@ -93695,8 +97630,8 @@ g_resolver_lookup_records() for more details. version="2.34" throws="1"> Retrieves the result of a previous call to + filename="gio/gresolver.c" + line="1264">Retrieves the result of a previous call to g_resolver_lookup_records_async(). Returns a non-empty list of records as #GVariant tuples. See #GResolverRecordType for information on what the records contain. @@ -93704,11 +97639,11 @@ records contain. If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1279">a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) @@ -93719,14 +97654,14 @@ g_variant_unref() to do this.) a #GResolver + filename="gio/gresolver.c" + line="1266">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="1267">the result passed to your #GAsyncReadyCallback @@ -93734,10 +97669,11 @@ g_variant_unref() to do this.) + throws="1" + glib:async-func="lookup_service_async"> Synchronously performs a DNS SRV lookup for the given @service and + filename="gio/gresolver.c" + line="1012">Synchronously performs a DNS SRV lookup for the given @service and @protocol in the given @domain and returns an array of #GSrvTarget. @domain may be an ASCII-only or UTF-8 hostname. Note also that the @service and @protocol arguments do not include the leading underscore @@ -93758,11 +97694,11 @@ operation, in which case @error (if non-%NULL) will be set to If you are planning to connect to the service, it is usually easier to create a #GNetworkService and use its #GSocketConnectable interface. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1043">a non-empty #GList of #GSrvTarget, or %NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.) @@ -93773,26 +97709,26 @@ this.) a #GResolver + filename="gio/gresolver.c" + line="1014">a #GResolver the service type to look up (eg, "ldap") + filename="gio/gresolver.c" + line="1015">the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") + filename="gio/gresolver.c" + line="1016">the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in + filename="gio/gresolver.c" + line="1017">the DNS domain to look up the service in nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1018">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="lookup_service_finish" + glib:sync-func="lookup_service"> Begins asynchronously performing a DNS SRV lookup for the given + filename="gio/gresolver.c" + line="1082">Begins asynchronously performing a DNS SRV lookup for the given @service and @protocol in the given @domain, and eventually calls @callback, which must call g_resolver_lookup_service_finish() to get the final result. See g_resolver_lookup_service() for more details. - + a #GResolver + filename="gio/gresolver.c" + line="1084">a #GResolver the service type to look up (eg, "ldap") + filename="gio/gresolver.c" + line="1085">the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") + filename="gio/gresolver.c" + line="1086">the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in + filename="gio/gresolver.c" + line="1087">the DNS domain to look up the service in nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1088">a #GCancellable, or %NULL scope="async" closure="5"> callback to call after resolution completes + filename="gio/gresolver.c" + line="1089">callback to call after resolution completes nullable="1" allow-none="1"> data for @callback + filename="gio/gresolver.c" + line="1090">data for @callback @@ -93881,18 +97819,18 @@ details. version="2.22" throws="1"> Retrieves the result of a previous call to + filename="gio/gresolver.c" + line="1133">Retrieves the result of a previous call to g_resolver_lookup_service_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1146">a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. @@ -93902,14 +97840,14 @@ details. a #GResolver + filename="gio/gresolver.c" + line="1135">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="1136">the result passed to your #GAsyncReadyCallback @@ -93918,8 +97856,8 @@ details. c:identifier="g_resolver_set_default" version="2.22"> Sets @resolver to be the application's default resolver (reffing + filename="gio/gresolver.c" + line="309">Sets @resolver to be the application's default resolver (reffing @resolver, and unreffing the previous default resolver, if any). Future calls to g_resolver_get_default() will return this resolver. @@ -93928,15 +97866,15 @@ caching or "pinning"; it can implement its own #GResolver that calls the original default resolver for DNS operations, and implements its own cache policies on top of that, and then set itself as the default resolver for all later code to use. - + the new default #GResolver + filename="gio/gresolver.c" + line="311">the new default #GResolver @@ -93946,23 +97884,23 @@ itself as the default resolver for all later code to use. glib:set-property="timeout" version="2.78"> Set the timeout applied to all resolver lookups. See #GResolver:timeout. - + filename="gio/gresolver.c" + line="1336">Set the timeout applied to all resolver lookups. See #GResolver:timeout. + a #GResolver + filename="gio/gresolver.c" + line="1338">a #GResolver timeout in milliseconds, or `0` for no timeouts + filename="gio/gresolver.c" + line="1339">timeout in milliseconds, or `0` for no timeouts @@ -93975,8 +97913,8 @@ itself as the default resolver for all later code to use. getter="get_timeout" default-value="0"> The timeout applied to all resolver lookups, in milliseconds. + filename="gio/gresolver.c" + line="222">The timeout applied to all resolver lookups, in milliseconds. This may be changed through the lifetime of the #GResolver. The new value will apply to any lookups started after the change, but not to any @@ -93996,8 +97934,8 @@ GLib 2.78. Emitted when the resolver notices that the system resolver + filename="gio/gresolver.c" + line="245">Emitted when the resolver notices that the system resolver configuration has changed. @@ -94007,13 +97945,13 @@ configuration has changed. - + - + @@ -94026,11 +97964,11 @@ configuration has changed. - + a non-empty #GList + filename="gio/gresolver.c" + line="589">a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) @@ -94041,14 +97979,14 @@ done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver + filename="gio/gresolver.c" + line="560">a #GResolver the hostname to look up + filename="gio/gresolver.c" + line="561">the hostname to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="562">a #GCancellable, or %NULL @@ -94065,21 +98003,21 @@ done with it. (You can use g_resolver_free_addresses() to do this.) - + a #GResolver + filename="gio/gresolver.c" + line="788">a #GResolver the hostname to look up the address of + filename="gio/gresolver.c" + line="789">the hostname to look up the address of nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="790">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gresolver.c" + line="791">callback to call after resolution completes allow-none="1" closure="4"> data for @callback + filename="gio/gresolver.c" + line="792">data for @callback @@ -94117,11 +98055,11 @@ done with it. (You can use g_resolver_free_addresses() to do this.) - + a #GList + filename="gio/gresolver.c" + line="829">a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. @@ -94131,14 +98069,14 @@ for more details. a #GResolver + filename="gio/gresolver.c" + line="818">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="819">the result passed to your #GAsyncReadyCallback @@ -94146,25 +98084,25 @@ for more details. - + a hostname (either ASCII-only, or in ASCII-encoded + filename="gio/gresolver.c" + line="914">a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver + filename="gio/gresolver.c" + line="899">a #GResolver the address to reverse-resolve + filename="gio/gresolver.c" + line="900">the address to reverse-resolve nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="901">a #GCancellable, or %NULL @@ -94181,21 +98119,21 @@ for more details. - + a #GResolver + filename="gio/gresolver.c" + line="935">a #GResolver the address to reverse-resolve + filename="gio/gresolver.c" + line="936">the address to reverse-resolve nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="937">a #GCancellable, or %NULL scope="async" closure="4"> callback to call after resolution completes + filename="gio/gresolver.c" + line="938">callback to call after resolution completes allow-none="1" closure="4"> data for @callback + filename="gio/gresolver.c" + line="939">data for @callback @@ -94233,25 +98171,25 @@ for more details. - + a hostname (either ASCII-only, or in ASCII-encoded + filename="gio/gresolver.c" + line="975">a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. a #GResolver + filename="gio/gresolver.c" + line="964">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="965">the result passed to your #GAsyncReadyCallback @@ -94259,7 +98197,7 @@ form), or %NULL on error. - + @@ -94283,7 +98221,7 @@ form), or %NULL on error. - + @@ -94320,11 +98258,11 @@ form), or %NULL on error. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1146">a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. @@ -94334,14 +98272,14 @@ details. a #GResolver + filename="gio/gresolver.c" + line="1135">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="1136">the result passed to your #GAsyncReadyCallback @@ -94349,11 +98287,11 @@ details. - + a non-empty #GList of + filename="gio/gresolver.c" + line="1206">a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) @@ -94364,20 +98302,20 @@ g_variant_unref() to do this.) a #GResolver + filename="gio/gresolver.c" + line="1189">a #GResolver the DNS name to look up the record for + filename="gio/gresolver.c" + line="1190">the DNS name to look up the record for the type of DNS record to look up + filename="gio/gresolver.c" + line="1191">the type of DNS record to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1192">a #GCancellable, or %NULL @@ -94394,27 +98332,27 @@ g_variant_unref() to do this.) - + a #GResolver + filename="gio/gresolver.c" + line="1234">a #GResolver the DNS name to look up the record for + filename="gio/gresolver.c" + line="1235">the DNS name to look up the record for the type of DNS record to look up + filename="gio/gresolver.c" + line="1236">the type of DNS record to look up nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="1237">a #GCancellable, or %NULL scope="async" closure="5"> callback to call after resolution completes + filename="gio/gresolver.c" + line="1238">callback to call after resolution completes allow-none="1" closure="5"> data for @callback + filename="gio/gresolver.c" + line="1239">data for @callback @@ -94452,11 +98390,11 @@ g_variant_unref() to do this.) - + a non-empty #GList of + filename="gio/gresolver.c" + line="1279">a non-empty #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) @@ -94467,14 +98405,14 @@ g_variant_unref() to do this.) a #GResolver + filename="gio/gresolver.c" + line="1266">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="1267">the result passed to your #GAsyncReadyCallback @@ -94482,27 +98420,27 @@ g_variant_unref() to do this.) - + a #GResolver + filename="gio/gresolver.c" + line="756">a #GResolver the hostname to look up the address of + filename="gio/gresolver.c" + line="757">the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup + filename="gio/gresolver.c" + line="758">extra #GResolverNameLookupFlags for the lookup @@ -94511,8 +98449,8 @@ g_variant_unref() to do this.) nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="759">a #GCancellable, or %NULL scope="async" closure="5"> callback to call after resolution completes + filename="gio/gresolver.c" + line="760">callback to call after resolution completes allow-none="1" closure="5"> data for @callback + filename="gio/gresolver.c" + line="761">data for @callback @@ -94541,11 +98479,11 @@ g_variant_unref() to do this.) - + a #GList + filename="gio/gresolver.c" + line="859">a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. @@ -94555,14 +98493,14 @@ for more details. a #GResolver + filename="gio/gresolver.c" + line="848">a #GResolver the result passed to your #GAsyncReadyCallback + filename="gio/gresolver.c" + line="849">the result passed to your #GAsyncReadyCallback @@ -94570,11 +98508,11 @@ for more details. - + a non-empty #GList + filename="gio/gresolver.c" + line="621">a non-empty #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) @@ -94585,20 +98523,20 @@ done with it. (You can use g_resolver_free_addresses() to do this.) a #GResolver + filename="gio/gresolver.c" + line="611">a #GResolver the hostname to look up + filename="gio/gresolver.c" + line="612">the hostname to look up extra #GResolverNameLookupFlags for the lookup + filename="gio/gresolver.c" + line="613">extra #GResolverNameLookupFlags for the lookup @@ -94607,8 +98545,8 @@ done with it. (You can use g_resolver_free_addresses() to do this.) nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gresolver.c" + line="614">a #GCancellable, or %NULL @@ -94622,8 +98560,8 @@ done with it. (You can use g_resolver_free_addresses() to do this.) c:type="GResolverError" glib:error-domain="g-resolver-error-quark"> An error code used with %G_RESOLVER_ERROR in a #GError returned + filename="gio/gioenums.h" + line="712">An error code used with %G_RESOLVER_ERROR in a #GError returned from a #GResolver routine. glib:nick="not-found" glib:name="G_RESOLVER_ERROR_NOT_FOUND"> the requested name/address/service was not + filename="gio/gioenums.h" + line="714">the requested name/address/service was not found glib:nick="temporary-failure" glib:name="G_RESOLVER_ERROR_TEMPORARY_FAILURE"> the requested information could not + filename="gio/gioenums.h" + line="716">the requested information could not be looked up due to a network error or similar problem glib:nick="internal" glib:name="G_RESOLVER_ERROR_INTERNAL"> unknown error + filename="gio/gioenums.h" + line="718">unknown error Gets the #GResolver Error Quark. + filename="gio/gresolver.c" + line="1360">Gets the #GResolver Error Quark. a #GQuark. + filename="gio/gresolver.c" + line="1365">a #GQuark. @@ -94674,7 +98612,7 @@ from a #GResolver routine. glib:get-type="g_resolver_name_lookup_flags_get_type" c:type="GResolverNameLookupFlags"> Flags to modify lookup behavior. glib:nick="default" glib:name="G_RESOLVER_NAME_LOOKUP_FLAGS_DEFAULT"> default behavior (same as g_resolver_lookup_by_name()) glib:nick="ipv4-only" glib:name="G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY"> only resolve ipv4 addresses glib:nick="ipv6-only" glib:name="G_RESOLVER_NAME_LOOKUP_FLAGS_IPV6_ONLY"> only resolve ipv6 addresses @@ -94708,7 +98646,7 @@ from a #GResolver routine. c:type="GResolverPrivate" disguised="1" opaque="1"> - + glib:get-type="g_resolver_record_type_get_type" c:type="GResolverRecordType"> The type of record that g_resolver_lookup_records() or + filename="gio/gioenums.h" + line="731">The type of record that g_resolver_lookup_records() or g_resolver_lookup_records_async() should retrieve. The records are returned as lists of #GVariant tuples. Each record type has different values in the variant tuples returned. @@ -94753,8 +98691,8 @@ as a `guint32`, and the TTL as a `guint32`. glib:nick="srv" glib:name="G_RESOLVER_RECORD_SRV"> look up DNS SRV records for a domain + filename="gio/gioenums.h" + line="733">look up DNS SRV records for a domain look up DNS MX records for a domain + filename="gio/gioenums.h" + line="734">look up DNS MX records for a domain look up DNS TXT records for a name + filename="gio/gioenums.h" + line="735">look up DNS TXT records for a name look up DNS SOA records for a zone + filename="gio/gioenums.h" + line="736">look up DNS SOA records for a zone look up DNS NS records for a domain + filename="gio/gioenums.h" + line="737">look up DNS NS records for a domain Applications and libraries often contain binary or textual data that is + filename="gio/gresource.c" + line="50">Applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance -#GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, -icons, etc. These are often shipped as files in `$datadir/appname`, or -manually included as literal strings in the code. - -The #GResource API and the [glib-compile-resources][glib-compile-resources] program -provide a convenient and efficient alternative to this which has some nice properties. You -maintain the files as normal files, so its easy to edit them, but during the build the files -are combined into a binary bundle that is linked into the executable. This means that loading -the resource files are efficient (as they are already in memory, shared with other instances) and -simple (no need to check for things like I/O errors or locate the files in the filesystem). It +[`GtkBuilder`](https://docs.gtk.org/gtk4/class.Builder.html) `.ui` files, +splashscreen images, [class@Gio.Menu] markup XML, CSS files, icons, etc. +These are often shipped as files in `$datadir/appname`, or manually +included as literal strings in the code. + +The `GResource` API and the +[`glib-compile-resources`](glib-compile-resources.html) program provide a +convenient and efficient alternative to this which has some nice properties. +You maintain the files as normal files, so it’s easy to edit them, but during +the build the files are combined into a binary bundle that is linked into the +executable. This means that loading the resource files are efficient (as they +are already in memory, shared with other instances) and simple (no need to +check for things like I/O errors or locate the files in the filesystem). It also makes it easier to create relocatable applications. -Resource files can also be marked as compressed. Such files will be included in the resource bundle -in a compressed form, but will be automatically uncompressed when the resource is used. This -is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. +Resource files can also be marked as compressed. Such files will be included +in the resource bundle in a compressed form, but will be automatically +uncompressed when the resource is used. This is very useful e.g. for larger +text files that are parsed once (or rarely) and then thrown away. Resource files can also be marked to be preprocessed, by setting the value of the `preprocess` attribute to a comma-separated list of preprocessing options. The only options currently supported are: -`xml-stripblanks` which will use the xmllint command -to strip ignorable whitespace from the XML file. For this to work, -the `XMLLINT` environment variable must be set to the full path to -the xmllint executable, or xmllint must be in the `PATH`; otherwise -the preprocessing step is skipped. - -`to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the -`gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format, -which allows you to create pixbufs directly using the data inside the -resource file, rather than an (uncompressed) copy of it. For this, the -`gdk-pixbuf-pixdata` program must be in the `PATH`, or the -`GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the -`gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort. -`to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource -supports embedding modern image formats just as well. Instead of using it, -embed a PNG or SVG file in your #GResource. - -`json-stripblanks` which will use the `json-glib-format` command to strip -ignorable whitespace from the JSON file. For this to work, the -`JSON_GLIB_FORMAT` environment variable must be set to the full path to the -`json-glib-format` executable, or it must be in the `PATH`; -otherwise the preprocessing step is skipped. In addition, at least version -1.6 of `json-glib-format` is required. - -Resource files will be exported in the GResource namespace using the + - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command + to strip ignorable whitespace from the XML file. For this to work, + the `XMLLINT` environment variable must be set to the full path to + the xmllint executable, or xmllint must be in the `PATH`; otherwise + the preprocessing step is skipped. + + - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the + `gdk-pixbuf-pixdata` command to convert images to the [`GdkPixdata`](https://docs.gtk.org/gdk-pixbuf/class.Pixdata.html) + format, which allows you to create pixbufs directly using the data inside + the resource file, rather than an (uncompressed) copy of it. For this, the + `gdk-pixbuf-pixdata` program must be in the `PATH`, or the + `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to + the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will + abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as + `GResource` supports embedding modern image formats just as well. Instead + of using it, embed a PNG or SVG file in your `GResource`. + + - `json-stripblanks` which will use the + [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable + whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT` + environment variable must be set to the full path to the + `json-glib-format` executable, or it must be in the `PATH`; otherwise the + preprocessing step is skipped. In addition, at least version 1.6 of + `json-glib-format` is required. + +Resource files will be exported in the `GResource` namespace using the combination of the given `prefix` and the filename from the `file` element. The `alias` attribute can be used to alter the filename to expose them at a different location in the resource namespace. Typically, this is used to include files from a different source directory without exposing the source directory in the resource namespace, as in the example below. -Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program -which takes an XML file that describes the bundle, and a set of files that the XML references. These -are combined into a binary resource bundle. +Resource bundles are created by the +[`glib-compile-resources`](glib-compile-resources.html) program +which takes an XML file that describes the bundle, and a set of files that +the XML references. These are combined into a binary resource bundle. An example resource description: -|[ +```xml <?xml version="1.0" encoding="UTF-8"?> <gresources> <gresource prefix="/org/gtk/Example"> @@ -94870,105 +98814,125 @@ An example resource description: <file alias="example.css">data/example.css</file> </gresource> </gresources> -]| +``` This will create a resource bundle with the following files: -|[ +``` /org/gtk/Example/data/splashscreen.png /org/gtk/Example/dialog.ui /org/gtk/Example/menumarkup.xml /org/gtk/Example/example.css -]| +``` -Note that all resources in the process share the same namespace, so use Java-style -path prefixes (like in the above example) to avoid conflicts. +Note that all resources in the process share the same namespace, so use +Java-style path prefixes (like in the above example) to avoid conflicts. -You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a -binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and ---generate-header arguments to create a source file and header to link directly into your application. +You can then use [`glib-compile-resources`](glib-compile-resources.html) to +compile the XML to a binary bundle that you can load with +[func@Gio.Resource.load]. However, it’s more common to use the +`--generate-source` and `--generate-header` arguments to create a source file +and header to link directly into your application. This will generate `get_resource()`, `register_resource()` and `unregister_resource()` functions, prefixed by the `--c-name` argument passed -to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns -the generated #GResource object. The register and unregister functions -register the resource so its files can be accessed using -g_resources_lookup_data(). - -Once a #GResource has been created and registered all the data in it can be accessed globally in the process by -using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer -to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access -the resource data. - -Some higher-level APIs, such as #GtkApplication, will automatically load -resources from certain well-known paths in the resource namespace as a -convenience. See the documentation for those APIs for details. - -There are two forms of the generated source, the default version uses the compiler support for constructor -and destructor functions (where available) to automatically create and register the #GResource on startup -or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created -instead. This requires an explicit initialization call in your application/library, but it works on all platforms, -even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) - -Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries -during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away -when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses -are for your own resources, and resource data is often used once, during parsing, and then released. - -When debugging a program or testing a change to an installed version, it is often useful to be able to -replace resources in the program or library, without recompiling, for debugging or quick hacking and testing -purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay -resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform -during resource lookups. It is ignored when running in a setuid process. +to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()` +returns the generated `GResource` object. The register and unregister +functions register the resource so its files can be accessed using +[func@Gio.resources_lookup_data]. + +Once a `GResource` has been created and registered all the data in it can be +accessed globally in the process by using API calls like +[func@Gio.resources_open_stream] to stream the data or +[func@Gio.resources_lookup_data] to get a direct pointer to the data. You can +also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with +[iface@Gio.File] to access the resource data. + +Some higher-level APIs, such as [`GtkApplication`](https://docs.gtk.org/gtk4/class.Application.html), +will automatically load resources from certain well-known paths in the +resource namespace as a convenience. See the documentation for those APIs +for details. + +There are two forms of the generated source, the default version uses the +compiler support for constructor and destructor functions (where available) +to automatically create and register the `GResource` on startup or library +load time. If you pass `--manual-register`, two functions to +register/unregister the resource are created instead. This requires an +explicit initialization call in your application/library, but it works on all +platforms, even on the minor ones where constructors are not supported. +(Constructor support is available for at least Win32, Mac OS and Linux.) + +Note that resource data can point directly into the data segment of e.g. a +library, so if you are unloading libraries during runtime you need to be very +careful with keeping around pointers to data from a resource, as this goes +away when the library is unloaded. However, in practice this is not generally +a problem, since most resource accesses are for your own resources, and +resource data is often used once, during parsing, and then released. + +# Overlays + +When debugging a program or testing a change to an installed version, it is +often useful to be able to replace resources in the program or library, +without recompiling, for debugging or quick hacking and testing purposes. +Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment +variable to selectively overlay resources with replacements from the +filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions +to perform during resource lookups. It is ignored when running in a setuid +process. A substitution has the form -|[ - /org/gtk/libgtk=/home/desrt/gtk-overlay -]| +``` +/org/gtk/libgtk=/home/desrt/gtk-overlay +``` -The part before the `=` is the resource subpath for which the overlay applies. The part after is a -filesystem path which contains files and subdirectories as you would like to be loaded as resources with the +The part before the `=` is the resource subpath for which the overlay +applies. The part after is a filesystem path which contains files and +subdirectories as you would like to be loaded as resources with the equivalent names. -In the example above, if an application tried to load a resource with the resource path -`/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path -`/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an -overlay, not an outright replacement, which means that if a file is not found at that path, the built-in -version will be used instead. Whiteouts are not currently supported. - -Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after -the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the -location of a single resource with an individual file. - +In the example above, if an application tried to load a resource with the +resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check +the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was +found there, it would be used instead. This is an overlay, not an outright +replacement, which means that if a file is not found at that path, the +built-in version will be used instead. Whiteouts are not currently +supported. + +Substitutions must start with a slash, and must not contain a trailing slash +before the `=`. The path after the slash should ideally be absolute, but +this is not strictly required. It is possible to overlay the location of a +single resource with an individual file. + Creates a GResource from a reference to the binary resource bundle. + filename="gio/gresource.c" + line="592">Creates a [struct@Gio.Resource] from a reference to the binary resource bundle. + This will keep a reference to @data while the resource lives, so the data should not be modified or freed. If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). +to register it with [func@Gio.resources_register]. Note: @data must be backed by memory that is at least pointer aligned. Otherwise this function will internally create a copy of the memory since GLib 2.56, or in older versions fail and exit the process. If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. - + a new #GResource, or %NULL on error + filename="gio/gresource.c" + line="611">a new [struct@Gio.Resource], or `NULL` on error A #GBytes + filename="gio/gresource.c" + line="594">A [struct@GLib.Bytes] @@ -94978,19 +98942,21 @@ If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. moved-to="resources_register" version="2.32"> Registers the resource with the process-global set of resources. + filename="gio/gresource.c" + line="1128">Registers the resource with the process-global set of resources. + Once a resource is registered the files in it can be accessed -with the global resource lookup functions like g_resources_lookup_data(). - +with the global resource lookup functions like +[func@Gio.resources_lookup_data]. + A #GResource + filename="gio/gresource.c" + line="1130">A [struct@Gio.Resource] @@ -95000,17 +98966,17 @@ with the global resource lookup functions like g_resources_lookup_data(). moved-to="resources_unregister" version="2.32"> Unregisters the resource from the process-global set of resources. - + filename="gio/gresource.c" + line="1148">Unregisters the resource from the process-global set of resources. + A #GResource + filename="gio/gresource.c" + line="1150">A [struct@Gio.Resource] @@ -95020,20 +98986,21 @@ with the global resource lookup functions like g_resources_lookup_data(). version="2.32" throws="1"> Returns all the names of children at the specified @path in the resource. -The return result is a %NULL terminated list of strings which should -be released with g_strfreev(). + filename="gio/gresource.c" + line="1005">Returns all the names of children at the specified @path in the resource. -If @path is invalid or does not exist in the #GResource, +The return result is a `NULL` terminated list of strings which should +be released with [func@GLib.strfreev]. + +If @path is invalid or does not exist in the [struct@Gio.Resource], %G_RESOURCE_ERROR_NOT_FOUND will be returned. @lookup_flags controls the behaviour of the lookup. - + an array of constant strings + filename="gio/gresource.c" + line="1022">an array of constant strings @@ -95041,20 +99008,20 @@ If @path is invalid or does not exist in the #GResource, A #GResource + filename="gio/gresource.c" + line="1007">A [struct@Gio.Resource] A pathname inside the resource + filename="gio/gresource.c" + line="1008">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="1009">A [flags@Gio.ResourceLookupFlags] @@ -95064,35 +99031,38 @@ If @path is invalid or does not exist in the #GResource, version="2.32" throws="1"> Looks for a file at the specified @path in the resource and + filename="gio/gresource.c" + line="933">Looks for a file at the specified @path in the resource and if found returns information about it. -@lookup_flags controls the behaviour of the lookup. - +@lookup_flags controls the behaviour of the lookup. + +The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was +not found in @resource. + %TRUE if the file was found. %FALSE if there were errors + filename="gio/gresource.c" + line="952">`TRUE` if the file was found, `FALSE` if there were errors A #GResource + filename="gio/gresource.c" + line="935">A [struct@Gio.Resource] A pathname inside the resource + filename="gio/gresource.c" + line="936">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="937">A [flags@Gio.ResourceLookupFlags] a location to place the length of the contents of the file, - or %NULL if the length is not needed + filename="gio/gresource.c" + line="938">a location to place the length of the contents of the file, + or `NULL` if the length is not needed a location to place the flags about the file, - or %NULL if the length is not needed + filename="gio/gresource.c" + line="940">a location to place the flags about the file, + or `NULL` if the length is not needed + + Returns whether the specified @path in the resource +has children. + + + %TRUE if @path has children + + + + + A #GResource + + + + A pathname inside the resource + + + + Looks for a file at the specified @path in the resource and -returns a #GBytes that lets you directly access the data in + filename="gio/gresource.c" + line="819">Looks for a file at the specified @path in the resource and +returns a [struct@GLib.Bytes] that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte -is not included in the size of the GBytes. +is not included in the size of the [struct@GLib.Bytes]. For uncompressed resource files this is a pointer directly into -the resource bundle, which is typically in some readonly data section -in the program binary. For compressed files we allocate memory on -the heap and automatically uncompress the data. +the resource bundle, which is typically in some read-only data section +in the program binary. For compressed files, memory is allocated on +the heap and the data is automatically uncompressed. -@lookup_flags controls the behaviour of the lookup. - +@lookup_flags controls the behaviour of the lookup. + +This can return error %G_RESOURCE_ERROR_NOT_FOUND if @path was not found in +@resource, or %G_RESOURCE_ERROR_INTERNAL if decompression of a compressed +resource failed. + #GBytes or %NULL on error. - Free the returned object with g_bytes_unref() + filename="gio/gresource.c" + line="845">[struct@GLib.Bytes] or `NULL` on error A #GResource + filename="gio/gresource.c" + line="821">A [struct@Gio.Resource] A pathname inside the resource + filename="gio/gresource.c" + line="822">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="823">A [flags@Gio.ResourceLookupFlags] @@ -95175,77 +99177,81 @@ the heap and automatically uncompress the data. version="2.32" throws="1"> Looks for a file at the specified @path in the resource and -returns a #GInputStream that lets you read the data. + filename="gio/gresource.c" + line="759">Looks for a file at the specified @path in the resource and +returns a [class@Gio.InputStream] that lets you read the data. -@lookup_flags controls the behaviour of the lookup. - +@lookup_flags controls the behaviour of the lookup. + +The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was +not found in @resource. + #GInputStream or %NULL on error. - Free the returned object with g_object_unref() + filename="gio/gresource.c" + line="774">[class@Gio.InputStream] or `NULL` on error A #GResource + filename="gio/gresource.c" + line="761">A [struct@Gio.Resource] A pathname inside the resource + filename="gio/gresource.c" + line="762">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="763">A [flags@Gio.ResourceLookupFlags] Atomically increments the reference count of @resource by one. This -function is MT-safe and may be called from any thread. - + filename="gio/gresource.c" + line="520">Atomically increments the reference count of @resource by one. + +This function is threadsafe and may be called from any thread. + The passed in #GResource + filename="gio/gresource.c" + line="528">The passed in [struct@Gio.Resource] A #GResource + filename="gio/gresource.c" + line="522">A [struct@Gio.Resource] Atomically decrements the reference count of @resource by one. If the -reference count drops to 0, all memory allocated by the resource is -released. This function is MT-safe and may be called from any + filename="gio/gresource.c" + line="539">Atomically decrements the reference count of @resource by one. + +If the reference count drops to 0, all memory allocated by the resource is +released. This function is threadsafe and may be called from any thread. - + A #GResource + filename="gio/gresource.c" + line="541">A [struct@Gio.Resource] @@ -95255,29 +99261,29 @@ thread. version="2.32" throws="1"> Loads a binary resource bundle and creates a #GResource representation of it, allowing -you to query it for data. + filename="gio/gresource.c" + line="644">Loads a binary resource bundle and creates a [struct@Gio.Resource] +representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). +to register it with [func@Gio.resources_register]. If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or -there is an error in reading it, an error from g_mapped_file_new() will be -returned. - +there is an error in reading it, an error from [ctor@GLib.MappedFile.new] +will be returned. + a new #GResource, or %NULL on error + filename="gio/gresource.c" + line="660">a new [struct@Gio.Resource], or `NULL` on error the path of a filename to load, in the GLib filename encoding + filename="gio/gresource.c" + line="646">the path of a filename to load, in the GLib filename encoding @@ -95290,8 +99296,8 @@ returned. c:type="GResourceError" glib:error-domain="g-resource-error-quark"> An error code used with %G_RESOURCE_ERROR in a #GError returned + filename="gio/gioenums.h" + line="780">An error code used with %G_RESOURCE_ERROR in a #GError returned from a #GResource routine. glib:nick="not-found" glib:name="G_RESOURCE_ERROR_NOT_FOUND"> no file was found at the requested path + filename="gio/gioenums.h" + line="782">no file was found at the requested path glib:nick="internal" glib:name="G_RESOURCE_ERROR_INTERNAL"> unknown error + filename="gio/gioenums.h" + line="783">unknown error Gets the #GResource Error Quark. + filename="gio/gresource.c" + line="509">Gets the [struct@Gio.Resource] Error Quark. a #GQuark + filename="gio/gresource.c" + line="514">a [type@GLib.Quark] @@ -95331,8 +99337,8 @@ from a #GResource routine. glib:get-type="g_resource_flags_get_type" c:type="GResourceFlags"> GResourceFlags give information about a particular file inside a resource + filename="gio/gioenums.h" + line="795">GResourceFlags give information about a particular file inside a resource bundle. glib:nick="none" glib:name="G_RESOURCE_FLAGS_NONE"> No flags set. + filename="gio/gioenums.h" + line="797">No flags set. glib:nick="compressed" glib:name="G_RESOURCE_FLAGS_COMPRESSED"> The file is compressed. + filename="gio/gioenums.h" + line="798">The file is compressed. glib:get-type="g_resource_lookup_flags_get_type" c:type="GResourceLookupFlags"> GResourceLookupFlags determine how resource path lookups are handled. + filename="gio/gioenums.h" + line="810">GResourceLookupFlags determine how resource path lookups are handled. No flags set. + filename="gio/gioenums.h" + line="812">No flags set. - + @@ -95383,7 +99389,7 @@ bundle. - + @@ -95392,7 +99398,7 @@ bundle. - + @@ -95401,7 +99407,7 @@ bundle. - + @@ -95410,7 +99416,7 @@ bundle. - + @@ -95420,15 +99426,15 @@ bundle. value="gsettings-backend" c:type="G_SETTINGS_BACKEND_EXTENSION_POINT_NAME"> Extension point for #GSettingsBackend functionality. - + - + @@ -95437,7 +99443,7 @@ bundle. - + @@ -95446,7 +99452,7 @@ bundle. - + @@ -95455,7 +99461,7 @@ bundle. - + @@ -95464,7 +99470,7 @@ bundle. - + @@ -95473,7 +99479,7 @@ bundle. - + @@ -95482,7 +99488,7 @@ bundle. - + @@ -95491,7 +99497,7 @@ bundle. - + @@ -95500,7 +99506,7 @@ bundle. - + @@ -95509,7 +99515,7 @@ bundle. - + @@ -95518,7 +99524,7 @@ bundle. - + @@ -95527,7 +99533,7 @@ bundle. - + @@ -95536,7 +99542,7 @@ bundle. - + @@ -95545,7 +99551,7 @@ bundle. - + @@ -95554,14 +99560,14 @@ bundle. - + - + @@ -95570,7 +99576,7 @@ bundle. - + @@ -95579,7 +99585,7 @@ bundle. - + @@ -95588,7 +99594,7 @@ bundle. - + @@ -95597,7 +99603,7 @@ bundle. - + @@ -95606,7 +99612,7 @@ bundle. - + @@ -95615,7 +99621,7 @@ bundle. - + @@ -95624,7 +99630,7 @@ bundle. - + @@ -95633,7 +99639,7 @@ bundle. - + @@ -95642,7 +99648,7 @@ bundle. - + @@ -95651,7 +99657,7 @@ bundle. - + @@ -95660,7 +99666,7 @@ bundle. - + @@ -95669,7 +99675,7 @@ bundle. - + @@ -95678,7 +99684,7 @@ bundle. - + @@ -95687,7 +99693,7 @@ bundle. - + @@ -95696,7 +99702,7 @@ bundle. - + @@ -95705,7 +99711,7 @@ bundle. - + @@ -95714,7 +99720,7 @@ bundle. - + @@ -95723,7 +99729,7 @@ bundle. - + @@ -95732,7 +99738,7 @@ bundle. - + @@ -95741,7 +99747,7 @@ bundle. - + @@ -95750,7 +99756,7 @@ bundle. - + @@ -95759,7 +99765,7 @@ bundle. - + @@ -95768,7 +99774,7 @@ bundle. - + @@ -95777,7 +99783,7 @@ bundle. - + @@ -95786,7 +99792,7 @@ bundle. - + @@ -95795,7 +99801,7 @@ bundle. - + @@ -95804,7 +99810,7 @@ bundle. - + @@ -95817,67 +99823,67 @@ bundle. glib:get-type="g_seekable_get_type" glib:type-struct="SeekableIface"> #GSeekable is implemented by streams (implementations of -#GInputStream or #GOutputStream) that support seeking. + filename="gio/gseekable.c" + line="28">`GSeekable` is implemented by streams (implementations of +[class@Gio.InputStream] or [class@Gio.OutputStream]) that support seeking. Seekable streams largely fall into two categories: resizable and fixed-size. -#GSeekable on fixed-sized streams is approximately the same as POSIX -lseek() on a block device (for example: attempting to seek past the -end of the device is an error). Fixed streams typically cannot be +`GSeekable` on fixed-sized streams is approximately the same as POSIX +[`lseek()`](man:lseek(2)) on a block device (for example: attempting to seek +past the end of the device is an error). Fixed streams typically cannot be truncated. -#GSeekable on resizable streams is approximately the same as POSIX -lseek() on a normal file. Seeking past the end and writing data will -usually cause the stream to resize by introducing zero bytes. - +`GSeekable` on resizable streams is approximately the same as POSIX +[`lseek()`](man:lseek(2)) on a normal file. Seeking past the end and writing +data will usually cause the stream to resize by introducing zero bytes. + Tests if the stream supports the #GSeekableIface. - + filename="gio/gseekable.c" + line="76">Tests if the stream supports the #GSeekableIface. + %TRUE if @seekable can be seeked. %FALSE otherwise. + filename="gio/gseekable.c" + line="82">%TRUE if @seekable can be seeked. %FALSE otherwise. a #GSeekable. + filename="gio/gseekable.c" + line="78">a #GSeekable. Tests if the length of the stream can be adjusted with + filename="gio/gseekable.c" + line="140">Tests if the length of the stream can be adjusted with g_seekable_truncate(). - + %TRUE if the stream can be truncated, %FALSE otherwise. + filename="gio/gseekable.c" + line="147">%TRUE if the stream can be truncated, %FALSE otherwise. a #GSeekable. + filename="gio/gseekable.c" + line="142">a #GSeekable. Seeks in the stream by the given @offset, modified by @type. + filename="gio/gseekable.c" + line="96">Seeks in the stream by the given @offset, modified by @type. Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If @@ -95891,11 +99897,11 @@ Any operation that would result in a negative offset will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if successful. If an error + filename="gio/gseekable.c" + line="120">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -95903,20 +99909,20 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GSeekable. + filename="gio/gseekable.c" + line="98">a #GSeekable. a #goffset. + filename="gio/gseekable.c" + line="99">a #goffset. a #GSeekType. + filename="gio/gseekable.c" + line="100">a #GSeekType. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gseekable.c" + line="101">optional #GCancellable object, %NULL to ignore. Tells the current position within the stream. - + filename="gio/gseekable.c" + line="55">Tells the current position within the stream. + the (positive or zero) offset from the beginning of the + filename="gio/gseekable.c" + line="61">the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. a #GSeekable. + filename="gio/gseekable.c" + line="57">a #GSeekable. Sets the length of the stream to @offset. If the stream was previously + filename="gio/gseekable.c" + line="161">Sets the length of the stream to @offset. If the stream was previously larger than @offset, the extra data is discarded. If the stream was previously shorter than @offset, it is extended with NUL ('\0') bytes. @@ -95963,11 +99969,11 @@ triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. - + %TRUE if successful. If an error + filename="gio/gseekable.c" + line="179">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -95975,14 +99981,14 @@ partial result will be returned, without an error. a #GSeekable. + filename="gio/gseekable.c" + line="163">a #GSeekable. new length for @seekable, in bytes. + filename="gio/gseekable.c" + line="164">new length for @seekable, in bytes. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gseekable.c" + line="165">optional #GCancellable object, %NULL to ignore. Tests if the stream supports the #GSeekableIface. - + filename="gio/gseekable.c" + line="76">Tests if the stream supports the #GSeekableIface. + %TRUE if @seekable can be seeked. %FALSE otherwise. + filename="gio/gseekable.c" + line="82">%TRUE if @seekable can be seeked. %FALSE otherwise. a #GSeekable. + filename="gio/gseekable.c" + line="78">a #GSeekable. Tests if the length of the stream can be adjusted with + filename="gio/gseekable.c" + line="140">Tests if the length of the stream can be adjusted with g_seekable_truncate(). - + %TRUE if the stream can be truncated, %FALSE otherwise. + filename="gio/gseekable.c" + line="147">%TRUE if the stream can be truncated, %FALSE otherwise. a #GSeekable. + filename="gio/gseekable.c" + line="142">a #GSeekable. Seeks in the stream by the given @offset, modified by @type. + filename="gio/gseekable.c" + line="96">Seeks in the stream by the given @offset, modified by @type. Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If @@ -96054,11 +100060,11 @@ Any operation that would result in a negative offset will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + %TRUE if successful. If an error + filename="gio/gseekable.c" + line="120">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -96066,20 +100072,20 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GSeekable. + filename="gio/gseekable.c" + line="98">a #GSeekable. a #goffset. + filename="gio/gseekable.c" + line="99">a #goffset. a #GSeekType. + filename="gio/gseekable.c" + line="100">a #GSeekType. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gseekable.c" + line="101">optional #GCancellable object, %NULL to ignore. Tells the current position within the stream. - + filename="gio/gseekable.c" + line="55">Tells the current position within the stream. + the (positive or zero) offset from the beginning of the + filename="gio/gseekable.c" + line="61">the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. a #GSeekable. + filename="gio/gseekable.c" + line="57">a #GSeekable. Sets the length of the stream to @offset. If the stream was previously + filename="gio/gseekable.c" + line="161">Sets the length of the stream to @offset. If the stream was previously larger than @offset, the extra data is discarded. If the stream was previously shorter than @offset, it is extended with NUL ('\0') bytes. @@ -96126,11 +100132,11 @@ triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. - + %TRUE if successful. If an error + filename="gio/gseekable.c" + line="179">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -96138,14 +100144,14 @@ partial result will be returned, without an error. a #GSeekable. + filename="gio/gseekable.c" + line="163">a #GSeekable. new length for @seekable, in bytes. + filename="gio/gseekable.c" + line="164">new length for @seekable, in bytes. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gseekable.c" + line="165">optional #GCancellable object, %NULL to ignore. @@ -96164,61 +100170,70 @@ partial result will be returned, without an error. c:type="GSeekableIface" glib:is-gtype-struct-for="Seekable"> Provides an interface for implementing seekable functionality on I/O Streams. - + filename="gio/gseekable.h" + line="41">Provides an interface for implementing seekable functionality on I/O Streams. + The parent interface. + filename="gio/gseekable.h" + line="43">The parent interface. + Tells the current location within a stream. - + the (positive or zero) offset from the beginning of the + filename="gio/gseekable.c" + line="61">the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. a #GSeekable. + filename="gio/gseekable.c" + line="57">a #GSeekable. + Checks if seeking is supported by the stream. - + %TRUE if @seekable can be seeked. %FALSE otherwise. + filename="gio/gseekable.c" + line="82">%TRUE if @seekable can be seeked. %FALSE otherwise. a #GSeekable. + filename="gio/gseekable.c" + line="78">a #GSeekable. + Seeks to a location within a stream. - + %TRUE if successful. If an error + filename="gio/gseekable.c" + line="120">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -96226,20 +100241,20 @@ buffer, zero if the target is not seekable. a #GSeekable. + filename="gio/gseekable.c" + line="98">a #GSeekable. a #goffset. + filename="gio/gseekable.c" + line="99">a #goffset. a #GSeekType. + filename="gio/gseekable.c" + line="100">a #GSeekType. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gseekable.c" + line="101">optional #GCancellable object, %NULL to ignore. + Checks if truncation is supported by the stream. - + %TRUE if the stream can be truncated, %FALSE otherwise. + filename="gio/gseekable.c" + line="147">%TRUE if the stream can be truncated, %FALSE otherwise. a #GSeekable. + filename="gio/gseekable.c" + line="142">a #GSeekable. + Truncates a stream. - + %TRUE if successful. If an error + filename="gio/gseekable.c" + line="179">%TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. @@ -96287,14 +100308,14 @@ buffer, zero if the target is not seekable. a #GSeekable. + filename="gio/gseekable.c" + line="163">a #GSeekable. new length for @seekable, in bytes. + filename="gio/gseekable.c" + line="164">new length for @seekable, in bytes. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gseekable.c" + line="165">optional #GCancellable object, %NULL to ignore. @@ -96318,113 +100339,114 @@ buffer, zero if the target is not seekable. glib:get-type="g_settings_get_type" glib:type-struct="SettingsClass"> The #GSettings class provides a convenient API for storing and retrieving + filename="gio/gsettings.c" + line="39">The `GSettings` class provides a convenient API for storing and retrieving application settings. Reads and writes can be considered to be non-blocking. Reading -settings with #GSettings is typically extremely fast: on +settings with `GSettings` is typically extremely fast: on approximately the same order of magnitude (but slower than) a -#GHashTable lookup. Writing settings is also extremely fast in terms -of time to return to your application, but can be extremely expensive +[struct@GLib.HashTable] lookup. Writing settings is also extremely fast in +terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings -a lot of work can be avoided. For dconf, the D-Bus service doesn't +a lot of work can be avoided. For dconf, the D-Bus service doesn’t even need to be started in this case. For this reason, you should -only ever modify #GSettings keys in response to explicit user action. +only ever modify `GSettings` keys in response to explicit user action. Particular care should be paid to ensure that modifications are not -made during startup -- for example, when setting the initial value -of preferences widgets. The built-in g_settings_bind() functionality -is careful not to write settings in response to notify signals as a -result of modifications that it makes to widgets. +made during startup — for example, when setting the initial value +of preferences widgets. The built-in [method@Gio.Settings.bind] +functionality is careful not to write settings in response to notify signals +as a result of modifications that it makes to widgets. -When creating a GSettings instance, you have to specify a schema +When creating a `GSettings` instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information. Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas -can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with +can also be ‘[relocatable](#relocatable-schemas)’, i.e. not equipped with a fixed path. This is -useful e.g. when the schema describes an 'account', and you want to be +useful e.g. when the schema describes an ‘account’, and you want to be able to store a arbitrary number of accounts. -Paths must start with and end with a forward slash character ('/') +Paths must start with and end with a forward slash character (`/`) and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are -"/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". -Paths should not start with "/apps/", "/desktop/" or "/system/" as +`/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`. +Paths should not start with `/apps/`, `/desktop/` or `/system/` as they often did in GConf. Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores -values as #GVariant, and allows any #GVariantType for keys. Key names -are restricted to lowercase characters, numbers and '-'. Furthermore, -the names must begin with a lowercase character, must not end -with a '-', and must not contain consecutive dashes. +values as [struct@GLib.Variant], and allows any [type@GLib.VariantType] for +keys. Key names are restricted to lowercase characters, numbers and `-`. +Furthermore, the names must begin with a lowercase character, must not end +with a `-`, and must not contain consecutive dashes. Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the -`gettext-domain` attribute of the <schemalist> or <schema> +`gettext-domain` attribute of the `<schemalist>` or `<schema>` elements and the category that is specified in the `l10n` attribute of -the <default> element. The string which is translated includes all text in -the <default> element, including any surrounding quotation marks. +the `<default>` element. The string which is translated includes all text in +the `<default>` element, including any surrounding quotation marks. The `l10n` attribute must be set to `messages` or `time`, and sets the [locale category for translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). The `messages` category should be used by default; use `time` for translatable date or time formats. A translation comment can be added as an -XML comment immediately above the <default> element — it is recommended to +XML comment immediately above the `<default>` element — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation `context` -attribute can be set on the <default> element to disambiguate multiple +attribute can be set on the `<default>` element to disambiguate multiple defaults which use the same string. For example: -|[ +```xml <!-- Translators: A list of words which are not allowed to be typed, in GVariant serialization syntax. See: https://developer.gnome.org/glib/stable/gvariant-text.html --> <default l10n='messages' context='Banned words'>['bad', 'words']</default> -]| +``` Translations of default values must remain syntactically valid serialized -#GVariants (e.g. retaining any surrounding quotation marks) or runtime -errors will occur. +[struct@GLib.Variant]s (e.g. retaining any surrounding quotation marks) or +runtime errors will occur. GSettings uses schemas in a compact binary form that is created -by the [glib-compile-schemas][glib-compile-schemas] +by the [`glib-compile-schemas`](glib-compile-schemas.html) utility. The input is a schema description in an XML format. A DTD for the gschema XML format can be found here: [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) -The [glib-compile-schemas][glib-compile-schemas] tool expects schema +The [`glib-compile-schemas`](glib-compile-schemas.html) tool expects schema files to have the extension `.gschema.xml`. -At runtime, schemas are identified by their id (as specified in the -id attribute of the <schema> element). The convention for schema -ids is to use a dotted name, similar in style to a D-Bus bus name, -e.g. "org.gnome.SessionManager". In particular, if the settings are +At runtime, schemas are identified by their ID (as specified in the +`id` attribute of the `<schema>` element). The convention for schema +IDs is to use a dotted name, similar in style to a D-Bus bus name, +e.g. `org.gnome.SessionManager`. In particular, if the settings are for a specific service that owns a D-Bus bus name, the D-Bus bus name -and schema id should match. For schemas which deal with settings not -associated with one named application, the id should not use -StudlyCaps, e.g. "org.gnome.font-rendering". - -In addition to #GVariant types, keys can have types that have -enumerated types. These can be described by a <choice>, -<enum> or <flags> element, as seen in the -[example][schema-enumerated]. The underlying type of such a key -is string, but you can use g_settings_get_enum(), g_settings_set_enum(), -g_settings_get_flags(), g_settings_set_flags() access the numeric values -corresponding to the string value of enum and flags keys. +and schema ID should match. For schemas which deal with settings not +associated with one named application, the ID should not use +StudlyCaps, e.g. `org.gnome.font-rendering`. + +In addition to [struct@GLib.Variant] types, keys can have types that have +enumerated types. These can be described by a `<choice>`, +`<enum>` or `<flags>` element, as seen in the +second example below. The underlying type of such a key +is string, but you can use [method@Gio.Settings.get_enum], +[method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags], +[method@Gio.Settings.set_flags] access the numeric values corresponding to +the string value of enum and flags keys. An example for default value: -|[ +```xml <schemalist> <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> @@ -96447,10 +100469,10 @@ An example for default value: </schema> </schemalist> -]| +``` An example for ranges, choices and enumerated types: -|[ +```xml <schemalist> <enum id="org.gtk.Test.myenum"> @@ -96493,7 +100515,7 @@ An example for ranges, choices and enumerated types: </key> </schema> </schemalist> -]| +``` ## Vendor overrides @@ -96501,41 +100523,42 @@ Default values are defined in the schemas that get installed by an application. Sometimes, it is necessary for a vendor or distributor to adjust these defaults. Since patching the XML source for the schema is inconvenient and error-prone, -[glib-compile-schemas][glib-compile-schemas] reads so-called vendor -override' files. These are keyfiles in the same directory as the XML -schema sources which can override default values. The schema id serves +[`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor +override’ files. These are keyfiles in the same directory as the XML +schema sources which can override default values. The schema ID serves as the group name in the key file, and the values are expected in -serialized GVariant form, as in the following example: -|[ - [org.gtk.Example] - key1='string' - key2=1.5 -]| - -glib-compile-schemas expects schema files to have the extension +serialized [struct@GLib.Variant] form, as in the following example: +``` +[org.gtk.Example] +key1='string' +key2=1.5 +``` + +`glib-compile-schemas` expects schema files to have the extension `.gschema.override`. ## Binding -A very convenient feature of GSettings lets you bind #GObject properties -directly to settings, using g_settings_bind(). Once a GObject property -has been bound to a setting, changes on either side are automatically -propagated to the other side. GSettings handles details like mapping -between GObject and GVariant types, and preventing infinite cycles. +A very convenient feature of GSettings lets you bind [class@GObject.Object] +properties directly to settings, using [method@Gio.Settings.bind]. Once a +[class@GObject.Object] property has been bound to a setting, changes on +either side are automatically propagated to the other side. GSettings handles +details like mapping between [class@GObject.Object] and [struct@GLib.Variant] +types, and preventing infinite cycles. This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings -looks for a boolean property with the name "sensitivity" and +looks for a boolean property with the name `sensitivity` and automatically binds it to the writability of the bound setting. -If this 'magic' gets in the way, it can be suppressed with the -%G_SETTINGS_BIND_NO_SENSITIVITY flag. +If this ‘magic’ gets in the way, it can be suppressed with the +`G_SETTINGS_BIND_NO_SENSITIVITY` flag. -## Relocatable schemas # {#gsettings-relocatable} +## Relocatable schemas A relocatable schema is one with no `path` attribute specified on its -<schema> element. By using g_settings_new_with_path(), a #GSettings object -can be instantiated for a relocatable schema, assigning a path to the -instance. Paths passed to g_settings_new_with_path() will typically be +`<schema>` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings` +object can be instantiated for a relocatable schema, assigning a path to the +instance. Paths passed to [ctor@Gio.Settings.new_with_path] will typically be constructed dynamically from a constant prefix plus some form of instance identifier; but they must still be valid GSettings paths. Paths could also be constant and used with a globally installed schema originating from a @@ -96546,71 +100569,138 @@ for different windows in an application. If the schema ID was `org.foo.MyApp.Window`, it could be instantiated for paths `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known -they can be specified as <child> elements in the parent schema, e.g.: -|[ +they can be specified as `<child>` elements in the parent schema, e.g.: +```xml <schema id="org.foo.MyApp" path="/org/foo/MyApp/"> <child name="main" schema="org.foo.MyApp.Window"/> </schema> -]| +``` -## Build system integration # {#gsettings-build-system} +## Build system integration + +### Meson + +GSettings is natively supported by Meson's [GNOME module](https://mesonbuild.com/Gnome-module.html). + +You can install the schemas as any other data file: + +``` +install_data( + 'org.foo.MyApp.gschema.xml', + install_dir: get_option('datadir') / 'glib-2.0/schemas', +) +``` + +You can use `gnome.post_install()` function to compile the schemas on +installation: + +``` +gnome = import('gnome') +gnome.post_install( + glib_compile_schemas: true, +) +``` + +If an enumerated type defined in a C header file is to be used in a GSettings +schema, it can either be defined manually using an `<enum>` element in the +schema XML, or it can be extracted automatically from the C header. This +approach is preferred, as it ensures the two representations are always +synchronised. To do so, you will need to use the `gnome.mkenums()` function +with the following templates: + +``` +schemas_enums = gnome.mkenums('org.foo.MyApp.enums.xml', + comments: '<!-- @comment@ -->', + fhead: '<schemalist>', + vhead: ' <@type@ id="org.foo.MyApp.@EnumName@">', + vprod: ' <value nick="@valuenick@" value="@valuenum@"/>', + vtail: ' </@type@>', + ftail: '</schemalist>', + sources: enum_sources, + install_header: true, + install_dir: get_option('datadir') / 'glib-2.0/schemas', +) +``` + +It is recommended to validate your schemas as part of the test suite for +your application: + +``` +test('validate-schema', + find_program('glib-compile-schemas'), + args: ['--strict', '--dry-run', meson.current_source_dir()], +) +``` + +If your application allows running uninstalled, you should also use the +`gnome.compile_schemas()` function to compile the schemas in the current +build directory: + +``` +gnome.compile_schemas() +``` + +### Autotools GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your `configure.ac`: -|[ +``` GLIB_GSETTINGS -]| +``` In the appropriate `Makefile.am`, use the following snippet to compile and install the named schema: -|[ +``` gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@ -]| - -No changes are needed to the build system to mark a schema XML file for -translation. Assuming it sets the `gettext-domain` attribute, a schema may -be marked for translation by adding it to `POTFILES.in`, assuming gettext -0.19 is in use (the preferred method for translation): -|[ -data/org.foo.MyApp.gschema.xml -]| - -Alternatively, if intltool 0.50.1 is in use: -|[ -[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml -]| - -GSettings will use gettext to look up translations for the <summary> and -<description> elements, and also any <default> elements which have a `l10n` -attribute set. Translations must not be included in the `.gschema.xml` file -by the build system, for example by using intltool XML rules with a -`.gschema.xml.in` template. +``` If an enumerated type defined in a C header file is to be used in a GSettings -schema, it can either be defined manually using an <enum> element in the +schema, it can either be defined manually using an `<enum>` element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant `Makefile.am`: -|[ +``` gsettings_ENUM_NAMESPACE = org.foo.MyApp gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h -]| +``` `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, which are specified in `gsettings_ENUM_FILES`. This will generate a `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be automatically included in the schema compilation, install and uninstall rules. It should not be committed to version control or included in -`EXTRA_DIST`. - +`EXTRA_DIST`. + +## Localization + +No changes are needed to the build system to mark a schema XML file for +translation. Assuming it sets the `gettext-domain` attribute, a schema may +be marked for translation by adding it to `POTFILES.in`, assuming gettext +0.19 or newer is in use (the preferred method for translation): +``` +data/org.foo.MyApp.gschema.xml +``` + +Alternatively, if intltool 0.50.1 is in use: +``` +[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml +``` + +GSettings will use gettext to look up translations for the `<summary>` and +`<description>` elements, and also any `<default>` elements which have a +`l10n` attribute set. + +Translations **must not** be included in the `.gschema.xml` file by the build +system, for example by using a rule to generate the XML file from a template. + Creates a new #GSettings object with the schema specified by + filename="gio/gsettings.c" + line="1003">Creates a new #GSettings object with the schema specified by @schema_id. It is an error for the schema to not exist: schemas are an @@ -96623,18 +100713,18 @@ Signals on the newly created #GSettings object will be dispatched via the thread-default #GMainContext in effect at the time of the call to g_settings_new(). The new #GSettings will hold a reference on the context. See g_main_context_push_thread_default(). - + a new #GSettings object + filename="gio/gsettings.c" + line="1021">a new #GSettings object the id of the schema + filename="gio/gsettings.c" + line="1005">the id of the schema @@ -96643,8 +100733,8 @@ on the context. See g_main_context_push_thread_default(). c:identifier="g_settings_new_full" version="2.32"> Creates a new #GSettings object with a given schema, backend and + filename="gio/gsettings.c" + line="1149">Creates a new #GSettings object with a given schema, backend and path. It should be extremely rare that you ever want to use this function. @@ -96667,18 +100757,18 @@ If @path is %NULL then the path from the schema is used. It is an error if @path is %NULL and the schema has no path of its own or if @path is non-%NULL and not equal to the path that the schema does have. - + a new #GSettings object + filename="gio/gsettings.c" + line="1179">a new #GSettings object a #GSettingsSchema + filename="gio/gsettings.c" + line="1151">a #GSettingsSchema nullable="1" allow-none="1"> a #GSettingsBackend + filename="gio/gsettings.c" + line="1152">a #GSettingsBackend nullable="1" allow-none="1"> the path to use + filename="gio/gsettings.c" + line="1153">the path to use @@ -96705,8 +100795,8 @@ have. c:identifier="g_settings_new_with_backend" version="2.26"> Creates a new #GSettings object with the schema specified by + filename="gio/gsettings.c" + line="1086">Creates a new #GSettings object with the schema specified by @schema_id and a given #GSettingsBackend. Creating a #GSettings object with a different backend allows accessing @@ -96714,24 +100804,24 @@ settings from a database other than the usual one. For example, it may make sense to pass a backend corresponding to the "defaults" settings database on the system to get a settings object that modifies the system default settings instead of the settings for this user. - + a new #GSettings object + filename="gio/gsettings.c" + line="1100">a new #GSettings object the id of the schema + filename="gio/gsettings.c" + line="1088">the id of the schema the #GSettingsBackend to use + filename="gio/gsettings.c" + line="1089">the #GSettingsBackend to use @@ -96740,36 +100830,36 @@ settings instead of the settings for this user. c:identifier="g_settings_new_with_backend_and_path" version="2.26"> Creates a new #GSettings object with the schema specified by + filename="gio/gsettings.c" + line="1117">Creates a new #GSettings object with the schema specified by @schema_id and a given #GSettingsBackend and path. This is a mix of g_settings_new_with_backend() and g_settings_new_with_path(). - + a new #GSettings object + filename="gio/gsettings.c" + line="1129">a new #GSettings object the id of the schema + filename="gio/gsettings.c" + line="1119">the id of the schema the #GSettingsBackend to use + filename="gio/gsettings.c" + line="1120">the #GSettingsBackend to use the path to use + filename="gio/gsettings.c" + line="1121">the path to use @@ -96778,8 +100868,8 @@ g_settings_new_with_path(). c:identifier="g_settings_new_with_path" version="2.26"> Creates a new #GSettings object with the relocatable schema specified + filename="gio/gsettings.c" + line="1050">Creates a new #GSettings object with the relocatable schema specified by @schema_id and a given path. You only need to do this if you want to directly create a settings @@ -96792,24 +100882,24 @@ has an explicitly specified path. It is a programmer error if @path is not a valid path. A valid path begins and ends with '/' and does not contain two consecutive '/' characters. - + a new #GSettings object + filename="gio/gsettings.c" + line="1069">a new #GSettings object the id of the schema + filename="gio/gsettings.c" + line="1052">the id of the schema the path to use + filename="gio/gsettings.c" + line="1053">the path to use @@ -96820,14 +100910,14 @@ characters. deprecated="1" deprecated-version="2.40"> Deprecated. + filename="gio/gsettingsschema.c" + line="892">Deprecated. Use g_settings_schema_source_list_schemas() instead - + a list of + filename="gio/gsettingsschema.c" + line="897">a list of relocatable #GSettings schemas that are available, in no defined order. The list must not be modified or freed. @@ -96841,17 +100931,17 @@ characters. deprecated="1" deprecated-version="2.40"> Deprecated. + filename="gio/gsettingsschema.c" + line="868">Deprecated. Use g_settings_schema_source_list_schemas() instead. If you used g_settings_list_schemas() to check for the presence of a particular schema, use g_settings_schema_source_lookup() instead of your whole loop. - + a list of + filename="gio/gsettingsschema.c" + line="873">a list of #GSettings schemas that are available, in no defined order. The list must not be modified or freed. @@ -96861,8 +100951,8 @@ of your whole loop. Ensures that all pending operations are complete for the default backend. + filename="gio/gsettings.c" + line="2417">Ensures that all pending operations are complete for the default backend. Writes made to a #GSettings are handled asynchronously. For this reason, it is very unlikely that the changes have it to disk by the @@ -96872,40 +100962,40 @@ This call will block until all of the writes have made it to the backend. Since the mainloop is not running, no change notifications will be dispatched during this call (but some may be queued by the time the call is done). - + Removes an existing binding for @property on @object. + filename="gio/gsettings.c" + line="3318">Removes an existing binding for @property on @object. Note that bindings are automatically removed when the object is finalized, so it is rarely necessary to call this function. - + the object + filename="gio/gsettings.c" + line="3320">the object the property whose binding is removed + filename="gio/gsettings.c" + line="3321">the property whose binding is removed - + @@ -96922,7 +101012,7 @@ function. - + @@ -96936,7 +101026,7 @@ function. - + @@ -96950,7 +101040,7 @@ function. - + @@ -96965,28 +101055,28 @@ function. Applies any changes that have been made to the settings. This + filename="gio/gsettings.c" + line="2326">Applies any changes that have been made to the settings. This function does nothing unless @settings is in 'delay-apply' mode; see g_settings_delay(). In the normal case settings are always applied immediately. - + a #GSettings instance + filename="gio/gsettings.c" + line="2328">a #GSettings instance Create a binding between the @key in the @settings object + filename="gio/gsettings.c" + line="2827">Create a binding between the @key in the @settings object and the property @property of @object. The binding uses the default GIO mapping functions to map @@ -97006,50 +101096,51 @@ Note that the lifecycle of the binding is tied to @object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. - + a #GSettings object + filename="gio/gsettings.c" + line="2829">a #GSettings object the key to bind + filename="gio/gsettings.c" + line="2830">the key to bind a #GObject + filename="gio/gsettings.c" + line="2831">a #GObject the name of the property to bind + filename="gio/gsettings.c" + line="2832">the name of the property to bind flags for the binding + filename="gio/gsettings.c" + line="2833">flags for the binding Create a binding between the @key in the @settings object + filename="gio/gsettings.c" + line="2881">Create a binding between the @key in the @settings object and the property @property of @object. The binding uses the provided mapping functions to map between @@ -97059,45 +101150,45 @@ Note that the lifecycle of the binding is tied to @object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. - + a #GSettings object + filename="gio/gsettings.c" + line="2883">a #GSettings object the key to bind + filename="gio/gsettings.c" + line="2884">the key to bind a #GObject + filename="gio/gsettings.c" + line="2885">a #GObject the name of the property to bind + filename="gio/gsettings.c" + line="2886">the name of the property to bind flags for the binding + filename="gio/gsettings.c" + line="2887">flags for the binding a function that gets called to convert values + filename="gio/gsettings.c" + line="2888">a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping @@ -97108,8 +101199,8 @@ binding overrides the first one. closure="6" destroy="7"> a function that gets called to convert values + filename="gio/gsettings.c" + line="2890">a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping @@ -97119,24 +101210,89 @@ binding overrides the first one. nullable="1" allow-none="1"> data that gets passed to @get_mapping and @set_mapping + filename="gio/gsettings.c" + line="2892">data that gets passed to @get_mapping and @set_mapping #GDestroyNotify function for @user_data + filename="gio/gsettings.c" + line="2893">#GDestroyNotify function for @user_data + + Version of g_settings_bind_with_mapping() using closures instead of callbacks +for easier binding in other languages. + + + + + + + a #GSettings object + + + + the key to bind + + + + a #GObject + + + + the name of the property to bind + + + + flags for the binding + + + + a function that gets called to convert values + from @settings to @object, or %NULL to use the default GIO mapping + + + + a function that gets called to convert values + from @object to @settings, or %NULL to use the default GIO mapping + + + + Create a binding between the writability of @key in the + filename="gio/gsettings.c" + line="3243">Create a binding between the writability of @key in the @settings object and the property @property of @object. The property must be boolean; "sensitive" or "visible" properties of widgets are the most likely candidates. @@ -97153,39 +101309,39 @@ Note that the lifecycle of the binding is tied to @object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. - + a #GSettings object + filename="gio/gsettings.c" + line="3245">a #GSettings object the key to bind + filename="gio/gsettings.c" + line="3246">the key to bind a #GObject + filename="gio/gsettings.c" + line="3247">a #GObject the name of a boolean property to bind + filename="gio/gsettings.c" + line="3248">the name of a boolean property to bind whether to 'invert' the value + filename="gio/gsettings.c" + line="3249">whether to 'invert' the value @@ -97194,8 +101350,8 @@ binding overrides the first one. c:identifier="g_settings_create_action" version="2.32"> Creates a #GAction corresponding to a given #GSettings key. + filename="gio/gsettings.c" + line="3552">Creates a #GAction corresponding to a given #GSettings key. The action has the same name as the key. @@ -97209,43 +101365,43 @@ For boolean-valued keys, action activations take no parameter and result in the toggling of the value. For all other types, activations take the new value for the key (which must have the correct type). - + a new #GAction + filename="gio/gsettings.c" + line="3572">a new #GAction a #GSettings + filename="gio/gsettings.c" + line="3554">a #GSettings the name of a key in @settings + filename="gio/gsettings.c" + line="3555">the name of a key in @settings Changes the #GSettings object into 'delay-apply' mode. In this + filename="gio/gsettings.c" + line="2292">Changes the #GSettings object into 'delay-apply' mode. In this mode, changes to @settings are not immediately propagated to the backend, but kept locally until g_settings_apply() is called. - + a #GSettings object + filename="gio/gsettings.c" + line="2294">a #GSettings object @@ -97255,8 +101411,8 @@ backend, but kept locally until g_settings_apply() is called. version="2.26" introspectable="0"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="1660">Gets the value that is stored at @key in @settings. A convenience function that combines g_settings_get_value() with g_variant_get(). @@ -97264,33 +101420,33 @@ g_variant_get(). It is a programmer error to give a @key that isn't contained in the schema for @settings or for the #GVariantType of @format to mismatch the type given in the schema. - + a #GSettings object + filename="gio/gsettings.c" + line="1662">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1663">the key to get the value for a #GVariant format string + filename="gio/gsettings.c" + line="1664">a #GVariant format string arguments as per @format + filename="gio/gsettings.c" + line="1665">arguments as per @format @@ -97299,31 +101455,31 @@ the type given in the schema. c:identifier="g_settings_get_boolean" version="2.26"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="2171">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for booleans. It is a programmer error to give a @key that isn't specified as having a boolean type in the schema for @settings. - + a boolean + filename="gio/gsettings.c" + line="2183">a boolean a #GSettings object + filename="gio/gsettings.c" + line="2173">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="2174">the key to get the value for @@ -97332,8 +101488,8 @@ having a boolean type in the schema for @settings. c:identifier="g_settings_get_child" version="2.26"> Creates a child settings object which has a base path of + filename="gio/gsettings.c" + line="2464">Creates a child settings object which has a base path of `base-path/@name`, where `base-path` is the base path of @settings. @@ -97342,24 +101498,24 @@ in the schema of @settings using a `<child>` element. The created child settings object will inherit the #GSettings:delay-apply mode from @settings. - + a 'child' settings object + filename="gio/gsettings.c" + line="2479">a 'child' settings object a #GSettings object + filename="gio/gsettings.c" + line="2466">a #GSettings object the name of the child schema + filename="gio/gsettings.c" + line="2467">the name of the child schema @@ -97368,8 +101524,8 @@ mode from @settings. c:identifier="g_settings_get_default_value" version="2.40"> Gets the "default value" of a key. + filename="gio/gsettings.c" + line="1326">Gets the "default value" of a key. This is the value that would be read if g_settings_reset() were to be called on the key. @@ -97390,24 +101546,24 @@ the default value was before the user set it. It is a programmer error to give a @key that isn't contained in the schema for @settings. - + the default value + filename="gio/gsettings.c" + line="1353">the default value a #GSettings object + filename="gio/gsettings.c" + line="1328">a #GSettings object the key to get the default value for + filename="gio/gsettings.c" + line="1329">the key to get the default value for @@ -97416,31 +101572,31 @@ schema for @settings. c:identifier="g_settings_get_double" version="2.26"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="2115">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for doubles. It is a programmer error to give a @key that isn't specified as having a 'double' type in the schema for @settings. - + a double + filename="gio/gsettings.c" + line="2127">a double a #GSettings object + filename="gio/gsettings.c" + line="2117">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="2118">the key to get the value for @@ -97449,8 +101605,8 @@ having a 'double' type in the schema for @settings. c:identifier="g_settings_get_enum" version="2.26"> Gets the value that is stored in @settings for @key and converts it + filename="gio/gsettings.c" + line="1378">Gets the value that is stored in @settings for @key and converts it to the enum value that it represents. In order to use this function the type of the value must be a string @@ -97462,24 +101618,24 @@ schema for @settings or is not marked as an enumerated type. If the value stored in the configuration database is not a valid value for the enumerated type then this function will return the default value. - + the enum value + filename="gio/gsettings.c" + line="1396">the enum value a #GSettings object + filename="gio/gsettings.c" + line="1380">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1381">the key to get the value for @@ -97488,8 +101644,8 @@ default value. c:identifier="g_settings_get_flags" version="2.26"> Gets the value that is stored in @settings for @key and converts it + filename="gio/gsettings.c" + line="1488">Gets the value that is stored in @settings for @key and converts it to the flags value that it represents. In order to use this function the type of the value must be an array @@ -97501,24 +101657,24 @@ schema for @settings or is not marked as a flags type. If the value stored in the configuration database is not a valid value for the flags type then this function will return the default value. - + the flags value + filename="gio/gsettings.c" + line="1506">the flags value a #GSettings object + filename="gio/gsettings.c" + line="1490">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1491">the key to get the value for @@ -97528,52 +101684,52 @@ value. glib:get-property="has-unapplied" version="2.26"> Returns whether the #GSettings object has any unapplied + filename="gio/gsettings.c" + line="2370">Returns whether the #GSettings object has any unapplied changes. This can only be the case if it is in 'delayed-apply' mode. - + %TRUE if @settings has unapplied changes + filename="gio/gsettings.c" + line="2377">%TRUE if @settings has unapplied changes a #GSettings object + filename="gio/gsettings.c" + line="2372">a #GSettings object Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="1887">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for 32-bit integers. It is a programmer error to give a @key that isn't specified as having a int32 type in the schema for @settings. - + an integer + filename="gio/gsettings.c" + line="1899">an integer a #GSettings object + filename="gio/gsettings.c" + line="1889">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1890">the key to get the value for @@ -97582,39 +101738,39 @@ having a int32 type in the schema for @settings. c:identifier="g_settings_get_int64" version="2.50"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="1943">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for 64-bit integers. It is a programmer error to give a @key that isn't specified as having a int64 type in the schema for @settings. - + a 64-bit integer + filename="gio/gsettings.c" + line="1955">a 64-bit integer a #GSettings object + filename="gio/gsettings.c" + line="1945">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1946">the key to get the value for Gets the value that is stored at @key in @settings, subject to + filename="gio/gsettings.c" + line="1740">Gets the value that is stored at @key in @settings, subject to application-level validation/mapping. You should use this function when the application needs to perform @@ -97641,24 +101797,24 @@ The result parameter for the @mapping function is pointed to a to each invocation of @mapping. The final value of that #gpointer is what is returned by this function. %NULL is valid; it is returned just as any other value would be. - + the result, which may be %NULL + filename="gio/gsettings.c" + line="1776">the result, which may be %NULL a #GSettings object + filename="gio/gsettings.c" + line="1742">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1743">the key to get the value for scope="call" closure="2"> the function to map the value in the + filename="gio/gsettings.c" + line="1744">the function to map the value in the settings database to the value used by the application @@ -97676,8 +101832,8 @@ just as any other value would be. nullable="1" allow-none="1"> user data for @mapping + filename="gio/gsettings.c" + line="1746">user data for @mapping @@ -97688,24 +101844,24 @@ just as any other value would be. deprecated="1" deprecated-version="2.40"> Queries the range of a key. + filename="gio/gsettings.c" + line="2557">Queries the range of a key. Use g_settings_schema_key_get_range() instead. - + a #GSettings + filename="gio/gsettings.c" + line="2559">a #GSettings the key to query the range of + filename="gio/gsettings.c" + line="2560">the key to query the range of @@ -97714,31 +101870,31 @@ just as any other value would be. c:identifier="g_settings_get_string" version="2.26"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="1831">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for strings. It is a programmer error to give a @key that isn't specified as having a string type in the schema for @settings. - + a newly-allocated string + filename="gio/gsettings.c" + line="1843">a newly-allocated string a #GSettings object + filename="gio/gsettings.c" + line="1833">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1834">the key to get the value for @@ -97747,16 +101903,16 @@ having a string type in the schema for @settings. c:identifier="g_settings_get_strv" version="2.26"> A convenience variant of g_settings_get() for string arrays. + filename="gio/gsettings.c" + line="2227">A convenience variant of g_settings_get() for string arrays. It is a programmer error to give a @key that isn't specified as having an array of strings type in the schema for @settings. - + a + filename="gio/gsettings.c" + line="2237">a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. @@ -97766,14 +101922,14 @@ is stored at @key in @settings. a #GSettings object + filename="gio/gsettings.c" + line="2229">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="2230">the key to get the value for @@ -97782,32 +101938,32 @@ is stored at @key in @settings. c:identifier="g_settings_get_uint" version="2.30"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="1999">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for 32-bit unsigned integers. It is a programmer error to give a @key that isn't specified as having a uint32 type in the schema for @settings. - + an unsigned integer + filename="gio/gsettings.c" + line="2012">an unsigned integer a #GSettings object + filename="gio/gsettings.c" + line="2001">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="2002">the key to get the value for @@ -97816,32 +101972,32 @@ having a uint32 type in the schema for @settings. c:identifier="g_settings_get_uint64" version="2.50"> Gets the value that is stored at @key in @settings. + filename="gio/gsettings.c" + line="2057">Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for 64-bit unsigned integers. It is a programmer error to give a @key that isn't specified as having a uint64 type in the schema for @settings. - + a 64-bit unsigned integer + filename="gio/gsettings.c" + line="2070">a 64-bit unsigned integer a #GSettings object + filename="gio/gsettings.c" + line="2059">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="2060">the key to get the value for @@ -97850,8 +102006,8 @@ having a uint64 type in the schema for @settings. c:identifier="g_settings_get_user_value" version="2.40"> Checks the "user value" of a key, if there is one. + filename="gio/gsettings.c" + line="1281">Checks the "user value" of a key, if there is one. The user value of a key is the last value that was set by the user. @@ -97869,24 +102025,24 @@ for providing indication that a particular value has been changed. It is a programmer error to give a @key that isn't contained in the schema for @settings. - + the user's value, if set + filename="gio/gsettings.c" + line="1305">the user's value, if set a #GSettings object + filename="gio/gsettings.c" + line="1283">a #GSettings object the key to get the user value for + filename="gio/gsettings.c" + line="1284">the key to get the user value for @@ -97895,29 +102051,29 @@ schema for @settings. c:identifier="g_settings_get_value" version="2.26"> Gets the value that is stored in @settings for @key. + filename="gio/gsettings.c" + line="1246">Gets the value that is stored in @settings for @key. It is a programmer error to give a @key that isn't contained in the schema for @settings. - + a new #GVariant + filename="gio/gsettings.c" + line="1256">a new #GVariant a #GSettings object + filename="gio/gsettings.c" + line="1248">a #GSettings object the key to get the value for + filename="gio/gsettings.c" + line="1249">the key to get the value for @@ -97926,34 +102082,34 @@ schema for @settings. c:identifier="g_settings_is_writable" version="2.26"> Finds out if a key can be written or not - + filename="gio/gsettings.c" + line="2437">Finds out if a key can be written or not + %TRUE if the key @name is writable + filename="gio/gsettings.c" + line="2444">%TRUE if the key @name is writable a #GSettings object + filename="gio/gsettings.c" + line="2439">a #GSettings object the name of a key + filename="gio/gsettings.c" + line="2440">the name of a key Gets the list of children on @settings. + filename="gio/gsettings.c" + line="2532">Gets the list of children on @settings. The list is exactly the list of strings for which it is not an error to call g_settings_get_child(). @@ -97964,11 +102120,11 @@ may still be useful there for introspection reasons, however. You should free the return value with g_strfreev() when you are done with it. - + a list of the children + filename="gio/gsettings.c" + line="2548">a list of the children on @settings, in no defined order @@ -97977,8 +102133,8 @@ with it. a #GSettings object + filename="gio/gsettings.c" + line="2534">a #GSettings object @@ -97988,8 +102144,8 @@ with it. deprecated="1" deprecated-version="2.46"> Introspects the list of keys on @settings. + filename="gio/gsettings.c" + line="2509">Introspects the list of keys on @settings. You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This @@ -97998,11 +102154,11 @@ function is intended for introspection reasons. You should free the return value with g_strfreev() when you are done with it. Use g_settings_schema_list_keys() instead. - + a list + filename="gio/gsettings.c" + line="2522">a list of the keys on @settings, in no defined order @@ -98011,8 +102167,8 @@ with it. a #GSettings object + filename="gio/gsettings.c" + line="2511">a #GSettings object @@ -98023,83 +102179,83 @@ with it. deprecated="1" deprecated-version="2.40"> Checks if the given @value is of the correct type and within the + filename="gio/gsettings.c" + line="2582">Checks if the given @value is of the correct type and within the permitted range for @key. Use g_settings_schema_key_range_check() instead. - + %TRUE if @value is valid for @key + filename="gio/gsettings.c" + line="2591">%TRUE if @value is valid for @key a #GSettings + filename="gio/gsettings.c" + line="2584">a #GSettings the key to check + filename="gio/gsettings.c" + line="2585">the key to check the value to check + filename="gio/gsettings.c" + line="2586">the value to check Resets @key to its default value. + filename="gio/gsettings.c" + line="2392">Resets @key to its default value. This call resets the key, as much as possible, to its default value. That might be the value specified in the schema or the one set by the administrator. - + a #GSettings object + filename="gio/gsettings.c" + line="2394">a #GSettings object the name of a key + filename="gio/gsettings.c" + line="2395">the name of a key Reverts all non-applied changes to the settings. This function + filename="gio/gsettings.c" + line="2347">Reverts all non-applied changes to the settings. This function does nothing unless @settings is in 'delay-apply' mode; see g_settings_delay(). In the normal case settings are always applied immediately. Change notifications will be emitted for affected keys. - + a #GSettings instance + filename="gio/gsettings.c" + line="2349">a #GSettings instance @@ -98109,8 +102265,8 @@ Change notifications will be emitted for affected keys. version="2.26" introspectable="0"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="1703">Sets @key in @settings to @value. A convenience function that combines g_settings_set_value() with g_variant_new(). @@ -98118,37 +102274,37 @@ g_variant_new(). It is a programmer error to give a @key that isn't contained in the schema for @settings or for the #GVariantType of @format to mismatch the type given in the schema. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="1719">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="1705">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="1706">the name of the key to set a #GVariant format string + filename="gio/gsettings.c" + line="1707">a #GVariant format string arguments as per @format + filename="gio/gsettings.c" + line="1708">arguments as per @format @@ -98157,38 +102313,38 @@ the type given in the schema. c:identifier="g_settings_set_boolean" version="2.26"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="2201">Sets @key in @settings to @value. A convenience variant of g_settings_set() for booleans. It is a programmer error to give a @key that isn't specified as having a boolean type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="2214">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="2203">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="2204">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="2205">the value to set it to @@ -98197,46 +102353,46 @@ having a boolean type in the schema for @settings. c:identifier="g_settings_set_double" version="2.26"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="2145">Sets @key in @settings to @value. A convenience variant of g_settings_set() for doubles. It is a programmer error to give a @key that isn't specified as having a 'double' type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="2158">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="2147">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="2148">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="2149">the value to set it to Looks up the enumerated type nick for @value and writes it to @key, + filename="gio/gsettings.c" + line="1433">Looks up the enumerated type nick for @value and writes it to @key, within @settings. It is a programmer error to give a @key that isn't contained in the @@ -98246,38 +102402,38 @@ schema for @settings or is not marked as an enumerated type, or for After performing the write, accessing @key directly with g_settings_get_string() will return the 'nick' associated with @value. - + %TRUE, if the set succeeds + filename="gio/gsettings.c" + line="1450">%TRUE, if the set succeeds a #GSettings object + filename="gio/gsettings.c" + line="1435">a #GSettings object a key, within @settings + filename="gio/gsettings.c" + line="1436">a key, within @settings an enumerated value + filename="gio/gsettings.c" + line="1437">an enumerated value Looks up the flags type nicks for the bits specified by @value, puts + filename="gio/gsettings.c" + line="1543">Looks up the flags type nicks for the bits specified by @value, puts them in an array of strings and writes the array to @key, within @settings. @@ -98288,68 +102444,68 @@ to contain any bits that are not value for the named type. After performing the write, accessing @key directly with g_settings_get_strv() will return an array of 'nicks'; one for each bit in @value. - + %TRUE, if the set succeeds + filename="gio/gsettings.c" + line="1561">%TRUE, if the set succeeds a #GSettings object + filename="gio/gsettings.c" + line="1545">a #GSettings object a key, within @settings + filename="gio/gsettings.c" + line="1546">a key, within @settings a flags value + filename="gio/gsettings.c" + line="1547">a flags value Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="1917">Sets @key in @settings to @value. A convenience variant of g_settings_set() for 32-bit integers. It is a programmer error to give a @key that isn't specified as having a int32 type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="1930">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="1919">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="1920">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="1921">the value to set it to @@ -98358,38 +102514,38 @@ having a int32 type in the schema for @settings. c:identifier="g_settings_set_int64" version="2.50"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="1973">Sets @key in @settings to @value. A convenience variant of g_settings_set() for 64-bit integers. It is a programmer error to give a @key that isn't specified as having a int64 type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="1986">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="1975">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="1976">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="1977">the value to set it to @@ -98398,38 +102554,38 @@ having a int64 type in the schema for @settings. c:identifier="g_settings_set_string" version="2.26"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="1861">Sets @key in @settings to @value. A convenience variant of g_settings_set() for strings. It is a programmer error to give a @key that isn't specified as having a string type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="1874">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="1863">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="1864">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="1865">the value to set it to @@ -98438,33 +102594,33 @@ having a string type in the schema for @settings. c:identifier="g_settings_set_strv" version="2.26"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="2257">Sets @key in @settings to @value. A convenience variant of g_settings_set() for string arrays. If @value is %NULL, then @key is set to be the empty array. It is a programmer error to give a @key that isn't specified as having an array of strings type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="2271">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="2259">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="2260">the name of the key to set nullable="1" allow-none="1"> the value to set it to, or %NULL + filename="gio/gsettings.c" + line="2261">the value to set it to, or %NULL @@ -98484,39 +102640,39 @@ having an array of strings type in the schema for @settings. c:identifier="g_settings_set_uint" version="2.30"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="2030">Sets @key in @settings to @value. A convenience variant of g_settings_set() for 32-bit unsigned integers. It is a programmer error to give a @key that isn't specified as having a uint32 type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="2044">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="2032">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="2033">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="2034">the value to set it to @@ -98525,39 +102681,39 @@ having a uint32 type in the schema for @settings. c:identifier="g_settings_set_uint64" version="2.50"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="2088">Sets @key in @settings to @value. A convenience variant of g_settings_set() for 64-bit unsigned integers. It is a programmer error to give a @key that isn't specified as having a uint64 type in the schema for @settings. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="2102">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="2090">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="2091">the name of the key to set the value to set it to + filename="gio/gsettings.c" + line="2092">the value to set it to @@ -98566,39 +102722,39 @@ having a uint64 type in the schema for @settings. c:identifier="g_settings_set_value" version="2.26"> Sets @key in @settings to @value. + filename="gio/gsettings.c" + line="1599">Sets @key in @settings to @value. It is a programmer error to give a @key that isn't contained in the schema for @settings or for @value to have the incorrect type, per the schema. If @value is floating then this function consumes the reference. - + %TRUE if setting the key succeeded, + filename="gio/gsettings.c" + line="1613">%TRUE if setting the key succeeded, %FALSE if the key was not writable a #GSettings object + filename="gio/gsettings.c" + line="1601">a #GSettings object the name of the key to set + filename="gio/gsettings.c" + line="1602">the name of the key to set a #GVariant of the correct type + filename="gio/gsettings.c" + line="1603">a #GVariant of the correct type @@ -98608,8 +102764,8 @@ If @value is floating then this function consumes the reference. construct-only="1" transfer-ownership="none"> The name of the context that the settings are stored in. + filename="gio/gsettings.c" + line="905">The name of the context that the settings are stored in. transfer-ownership="none" default-value="FALSE"> Whether the #GSettings object is in 'delay-apply' mode. See + filename="gio/gsettings.c" + line="988">Whether the #GSettings object is in 'delay-apply' mode. See g_settings_delay() for details. @@ -98627,8 +102783,8 @@ g_settings_delay() for details. getter="get_has_unapplied" default-value="FALSE"> If this property is %TRUE, the #GSettings object has outstanding + filename="gio/gsettings.c" + line="977">If this property is %TRUE, the #GSettings object has outstanding changes that will be applied when g_settings_apply() is called. @@ -98638,8 +102794,8 @@ changes that will be applied when g_settings_apply() is called. transfer-ownership="none" default-value="NULL"> The path within the backend where the settings are stored. + filename="gio/gsettings.c" + line="966">The path within the backend where the settings are stored. transfer-ownership="none" default-value="NULL"> The name of the schema that describes the types of keys + filename="gio/gsettings.c" + line="932">The name of the schema that describes the types of keys for this #GSettings object. The type of this property is *not* #GSettingsSchema. @@ -98670,8 +102826,8 @@ version, this property may instead refer to a #GSettingsSchema. transfer-ownership="none" default-value="NULL"> The name of the schema that describes the types of keys + filename="gio/gsettings.c" + line="954">The name of the schema that describes the types of keys for this #GSettings object. @@ -98680,8 +102836,8 @@ for this #GSettings object. construct-only="1" transfer-ownership="none"> The #GSettingsSchema describing the types of keys for this + filename="gio/gsettings.c" + line="915">The #GSettingsSchema describing the types of keys for this #GSettings object. Ideally, this property would be called 'schema'. #GSettingsSchema @@ -98698,8 +102854,8 @@ than the schema itself. Take care. The "change-event" signal is emitted once per change event that + filename="gio/gsettings.c" + line="810">The "change-event" signal is emitted once per change event that affects this settings object. You should connect to this signal only if you are interested in viewing groups of changes before they are split out into multiple emissions of the "changed" signal. @@ -98716,8 +102872,8 @@ for each affected key. If any other connected handler returns %TRUE then this default functionality will be suppressed. %TRUE to stop other handlers from being invoked for the + filename="gio/gsettings.c" + line="833">%TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. @@ -98727,8 +102883,8 @@ for each affected key. If any other connected handler returns nullable="1" allow-none="1"> + filename="gio/gsettings.c" + line="813"> an array of #GQuarks for the changed keys, or %NULL @@ -98736,16 +102892,16 @@ for each affected key. If any other connected handler returns the length of the @keys array, or 0 + filename="gio/gsettings.c" + line="815">the length of the @keys array, or 0 The "changed" signal is emitted when a key has potentially changed. + filename="gio/gsettings.c" + line="787">The "changed" signal is emitted when a key has potentially changed. You should call one of the g_settings_get() calls to check the new value. @@ -98761,16 +102917,16 @@ least once while a signal handler was already connected for @key. the name of the key that changed + filename="gio/gsettings.c" + line="790">the name of the key that changed The "writable-change-event" signal is emitted once per writability + filename="gio/gsettings.c" + line="867">The "writable-change-event" signal is emitted once per writability change event that affects this settings object. You should connect to this signal if you are interested in viewing groups of changes before they are split out into multiple emissions of the @@ -98790,24 +102946,24 @@ connected handler returns %TRUE then this default functionality will be suppressed. %TRUE to stop other handlers from being invoked for the + filename="gio/gsettings.c" + line="891">%TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. the quark of the key, or 0 + filename="gio/gsettings.c" + line="870">the quark of the key, or 0 The "writable-changed" signal is emitted when the writability of a + filename="gio/gsettings.c" + line="847">The "writable-changed" signal is emitted when the writability of a key has potentially changed. You should call g_settings_is_writable() in order to determine the new status. @@ -98820,8 +102976,8 @@ callbacks when the writability of "x" changes. the key + filename="gio/gsettings.c" + line="850">the key @@ -98836,12 +102992,12 @@ callbacks when the writability of "x" changes. glib:get-type="g_settings_backend_get_type" glib:type-struct="SettingsBackendClass"> The #GSettingsBackend interface defines a generic interface for + filename="gio/gsettingsbackend.c" + line="54">The `GSettingsBackend` interface defines a generic interface for non-strictly-typed data that is stored in a hierarchy. To implement -an alternative storage backend for #GSettings, you need to implement -the #GSettingsBackend interface and then make it implement the -extension point %G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. +an alternative storage backend for [class@Gio.Settings], you need to +implement the `GSettingsBackend` interface and then make it implement the +extension point `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. The interface defines methods for reading and writing values, a method for determining if writing of certain values will fail @@ -98851,38 +103007,37 @@ The semantics of the interface are very precisely defined and implementations must carefully adhere to the expectations of callers that are documented on each of the interface methods. -Some of the #GSettingsBackend functions accept or return a #GTree. -These trees always have strings as keys and #GVariant as values. -g_settings_backend_create_tree() is a convenience function to create -suitable trees. +Some of the `GSettingsBackend` functions accept or return a +[struct@GLib.Tree]. These trees always have strings as keys and +[struct@GLib.Variant] as values. -The #GSettingsBackend API is exported to allow third-party +The `GSettingsBackend` API is exported to allow third-party implementations, but does not carry the same stability guarantees as the public GIO API. For this reason, you have to define the -C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including +C preprocessor symbol `G_SETTINGS_ENABLE_BACKEND` before including `gio/gsettingsbackend.h`. - + Calculate the longest common prefix of all keys in a tree and write + filename="gio/gsettingsbackend.c" + line="595">Calculate the longest common prefix of all keys in a tree and write out an array of the key names relative to that prefix and, optionally, the value to store at each of those keys. You must free the value returned in @path, @keys and @values using g_free(). You should not attempt to free or unref the contents of @keys or @values. - + a #GTree containing the changes + filename="gio/gsettingsbackend.c" + line="597">a #GTree containing the changes the location to save the path + filename="gio/gsettingsbackend.c" + line="598">the location to save the path the + filename="gio/gsettingsbackend.c" + line="599">the location to save the relative keys @@ -98913,8 +103068,8 @@ g_free(). You should not attempt to free or unref the contents of optional="1" allow-none="1"> + filename="gio/gsettingsbackend.c" + line="601"> the location to save the values, or %NULL @@ -98926,24 +103081,27 @@ g_free(). You should not attempt to free or unref the contents of c:identifier="g_settings_backend_get_default" version="2.28"> Returns the default #GSettingsBackend. It is possible to override + filename="gio/gsettingsbackend.c" + line="998">Returns the default #GSettingsBackend. It is possible to override the default by setting the `GSETTINGS_BACKEND` environment variable to the name of a settings backend. The user gets a reference to the backend. - + the default #GSettingsBackend, + filename="gio/gsettingsbackend.c" + line="1007">the default #GSettingsBackend, which will be a dummy (memory) settings backend if no other settings backend is available. - + virtual method to get permission of a key + @@ -98957,7 +103115,10 @@ The user gets a reference to the backend. - + virtual method to get if a key is writable + @@ -98971,7 +103132,10 @@ The user gets a reference to the backend. - + virtual method to read a key's value + @@ -98991,7 +103155,10 @@ The user gets a reference to the backend. - + virtual method to read user's key value + @@ -99008,7 +103175,10 @@ The user gets a reference to the backend. - + virtual method to reset state + @@ -99028,7 +103198,10 @@ The user gets a reference to the backend. - + virtual method to subscribe to key changes + @@ -99042,7 +103215,10 @@ The user gets a reference to the backend. - + virtual method to sync state + @@ -99053,7 +103229,10 @@ The user gets a reference to the backend. - + virtual method to unsubscribe to key changes + @@ -99067,7 +103246,10 @@ The user gets a reference to the backend. - + virtual method to change key's value + @@ -99090,7 +103272,10 @@ The user gets a reference to the backend. - + virtual method to change a tree of keys + @@ -99113,8 +103298,8 @@ The user gets a reference to the backend. c:identifier="g_settings_backend_changed" version="2.26"> Signals that a single key has possibly changed. Backend + filename="gio/gsettingsbackend.c" + line="344">Signals that a single key has possibly changed. Backend implementations should call this if a key has possibly changed its value. @@ -99136,21 +103321,21 @@ g_settings_backend_write()). In the case that this call is in response to a call to g_settings_backend_write() then @origin_tag must be set to the same value that was passed to that call. - + a #GSettingsBackend implementation + filename="gio/gsettingsbackend.c" + line="346">a #GSettingsBackend implementation the name of the key + filename="gio/gsettingsbackend.c" + line="347">the name of the key nullable="1" allow-none="1"> the origin tag + filename="gio/gsettingsbackend.c" + line="348">the origin tag @@ -99168,25 +103353,25 @@ value that was passed to that call. c:identifier="g_settings_backend_changed_tree" version="2.26"> This call is a convenience wrapper. It gets the list of changes from + filename="gio/gsettingsbackend.c" + line="642">This call is a convenience wrapper. It gets the list of changes from @tree, computes the longest common prefix and calls g_settings_backend_changed(). - + a #GSettingsBackend implementation + filename="gio/gsettingsbackend.c" + line="644">a #GSettingsBackend implementation a #GTree containing the changes + filename="gio/gsettingsbackend.c" + line="645">a #GTree containing the changes nullable="1" allow-none="1"> the origin tag + filename="gio/gsettingsbackend.c" + line="646">the origin tag @@ -99204,8 +103389,8 @@ g_settings_backend_changed(). c:identifier="g_settings_backend_keys_changed" version="2.26"> Signals that a list of keys have possibly changed. Backend + filename="gio/gsettingsbackend.c" + line="389">Signals that a list of keys have possibly changed. Backend implementations should call this if keys have possibly changed their values. @@ -99226,27 +103411,27 @@ case g_settings_backend_changed() is definitely preferred). For efficiency reasons, the implementation should strive for @path to be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. - + a #GSettingsBackend implementation + filename="gio/gsettingsbackend.c" + line="391">a #GSettingsBackend implementation the path containing the changes + filename="gio/gsettingsbackend.c" + line="392">the path containing the changes the %NULL-terminated list of changed keys + filename="gio/gsettingsbackend.c" + line="393">the %NULL-terminated list of changed keys @@ -99256,8 +103441,8 @@ keys that were changed) but this is not strictly required. nullable="1" allow-none="1"> the origin tag + filename="gio/gsettingsbackend.c" + line="394">the origin tag @@ -99266,8 +103451,8 @@ keys that were changed) but this is not strictly required. c:identifier="g_settings_backend_path_changed" version="2.26"> Signals that all keys below a given path may have possibly changed. + filename="gio/gsettingsbackend.c" + line="438">Signals that all keys below a given path may have possibly changed. Backend implementations should call this if an entire path of keys have possibly changed their values. @@ -99288,21 +103473,21 @@ be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. As an example, if this function is called with the path of "/" then every single key in the application will be notified of a possible change. - + a #GSettingsBackend implementation + filename="gio/gsettingsbackend.c" + line="440">a #GSettingsBackend implementation the path containing the changes + filename="gio/gsettingsbackend.c" + line="441">the path containing the changes nullable="1" allow-none="1"> the origin tag + filename="gio/gsettingsbackend.c" + line="442">the origin tag @@ -99320,27 +103505,27 @@ single key in the application will be notified of a possible change. c:identifier="g_settings_backend_path_writable_changed" version="2.26"> Signals that the writability of all keys below a given path may have + filename="gio/gsettingsbackend.c" + line="507">Signals that the writability of all keys below a given path may have changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. - + a #GSettingsBackend implementation + filename="gio/gsettingsbackend.c" + line="509">a #GSettingsBackend implementation the name of the path + filename="gio/gsettingsbackend.c" + line="510">the name of the path @@ -99349,26 +103534,26 @@ will always be made in response to external events. c:identifier="g_settings_backend_writable_changed" version="2.26"> Signals that the writability of a single key has possibly changed. + filename="gio/gsettingsbackend.c" + line="482">Signals that the writability of a single key has possibly changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. - + a #GSettingsBackend implementation + filename="gio/gsettingsbackend.c" + line="484">a #GSettingsBackend implementation the name of the key + filename="gio/gsettingsbackend.c" + line="485">the name of the key @@ -99384,15 +103569,18 @@ will always be made in response to external events. c:type="GSettingsBackendClass" glib:is-gtype-struct-for="SettingsBackend"> Class structure for #GSettingsBackend. - + filename="gio/gsettingsbackend.h" + line="59">Class structure for #GSettingsBackend. + + virtual method to read a key's value - + @@ -99413,8 +103601,11 @@ will always be made in response to external events. + virtual method to get if a key is writable - + @@ -99429,8 +103620,11 @@ will always be made in response to external events. + virtual method to change key's value - + @@ -99454,8 +103648,11 @@ will always be made in response to external events. + virtual method to change a tree of keys - + @@ -99476,8 +103673,11 @@ will always be made in response to external events. + virtual method to reset state - + @@ -99498,8 +103698,11 @@ will always be made in response to external events. + virtual method to subscribe to key changes - + @@ -99514,8 +103717,11 @@ will always be made in response to external events. + virtual method to unsubscribe to key changes - + @@ -99530,8 +103736,11 @@ will always be made in response to external events. + virtual method to sync state - + @@ -99543,8 +103752,11 @@ will always be made in response to external events. + virtual method to get permission of a key - + @@ -99559,8 +103771,11 @@ will always be made in response to external events. + virtual method to read user's key value - + @@ -99587,14 +103802,14 @@ will always be made in response to external events. c:type="GSettingsBackendPrivate" disguised="1" opaque="1"> - + Flags used when creating a binding. These flags determine in which direction the binding works. The default is to synchronize in both directions. @@ -99604,7 +103819,7 @@ directions. glib:nick="default" glib:name="G_SETTINGS_BIND_DEFAULT"> Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET` glib:nick="get" glib:name="G_SETTINGS_BIND_GET"> Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable. @@ -99623,7 +103838,7 @@ directions. glib:nick="set" glib:name="G_SETTINGS_BIND_SET"> Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable. @@ -99633,7 +103848,7 @@ directions. glib:nick="no-sensitivity" glib:name="G_SETTINGS_BIND_NO_SENSITIVITY"> Do not try to bind a "sensitivity" property to the writability of the setting glib:nick="get-no-changes" glib:name="G_SETTINGS_BIND_GET_NO_CHANGES"> When set in addition to %G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting @@ -99652,7 +103867,7 @@ directions. glib:nick="invert-boolean" glib:name="G_SETTINGS_BIND_INVERT_BOOLEAN"> When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to g_settings_bind_with_mapping(). @@ -99660,27 +103875,27 @@ directions. The type for the function that is used to convert from #GSettings to an object property. The @value is already initialized to hold values of the appropriate type. - + %TRUE if the conversion succeeded, %FALSE in case of an error return location for the property value the #GVariant @@ -99690,7 +103905,7 @@ of the appropriate type. allow-none="1" closure="2"> user data that was specified when the binding was created @@ -99698,13 +103913,13 @@ of the appropriate type. The type for the function that is used to convert an object property value to a #GVariant for storing it in #GSettings. - + a new #GVariant holding the data from @value, or %NULL in case of an error @@ -99712,13 +103927,13 @@ value to a #GVariant for storing it in #GSettings. a #GValue containing the property value to map the #GVariantType to create @@ -99728,7 +103943,7 @@ value to a #GVariant for storing it in #GSettings. allow-none="1" closure="2"> user data that was specified when the binding was created @@ -99737,13 +103952,13 @@ value to a #GVariant for storing it in #GSettings. - + - + @@ -99759,7 +103974,7 @@ value to a #GVariant for storing it in #GSettings. - + @@ -99775,7 +103990,7 @@ value to a #GVariant for storing it in #GSettings. - + @@ -99791,7 +104006,7 @@ value to a #GVariant for storing it in #GSettings. - + @@ -99816,7 +104031,7 @@ value to a #GVariant for storing it in #GSettings. The type of the function that is used to convert from a value stored in a #GSettings to a value that is useful to the application. @@ -99827,17 +104042,17 @@ is not in the right format) then %FALSE should be returned. If @value is %NULL then it means that the mapping function is being given a "last chance" to successfully return a valid value. %TRUE must be returned in this case. - + %TRUE if the conversion succeeded, %FALSE in case of an error the #GVariant to map, or %NULL @@ -99847,7 +104062,7 @@ must be returned in this case. transfer-ownership="full" nullable="1"> the result of the mapping @@ -99857,7 +104072,7 @@ must be returned in this case. allow-none="1" closure="2"> the user data that was passed to g_settings_get_mapped() @@ -99868,7 +104083,7 @@ g_settings_get_mapped() c:type="GSettingsPrivate" disguised="1" opaque="1"> - + glib:get-type="g_settings_schema_get_type" c:symbol-prefix="settings_schema"> The #GSettingsSchemaSource and #GSettingsSchema APIs provide a + filename="gio/gsettingsschema.c" + line="40">The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a mechanism for advanced control over the loading of schemas and a mechanism for introspecting their content. @@ -99889,20 +104104,20 @@ settings visible to GSettings. Typically, a plugin will want to ship the schema along with itself and it won't be installed into the standard system directories for schemas. -#GSettingsSchemaSource provides a mechanism for dealing with this by -allowing the creation of a new 'schema source' from which schemas can +[struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this +by allowing the creation of a new ‘schema source’ from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings. Consider the following example: -|[<!-- language="C" --> +```c typedef struct { - ... + … GSettingsSchemaSource *schema_source; - ... + … } Plugin; Plugin * @@ -99910,18 +104125,18 @@ initialise_plugin (const gchar *dir) { Plugin *plugin; - ... + … plugin->schema_source = g_settings_schema_source_new_from_directory (dir, g_settings_schema_source_get_default (), FALSE, NULL); - ... + … return plugin; } -... +… GSettings * plugin_get_settings (Plugin *plugin, @@ -99937,12 +104152,12 @@ plugin_get_settings (Plugin *plugin, if (schema == NULL) { - ... disable the plugin or abort, etc ... + … disable the plugin or abort, etc … } return g_settings_new_full (schema, NULL, NULL); } -]| +``` The code above shows how hooks should be added to the code that initialises (or enables) the plugin to create the schema source and @@ -99954,38 +104169,38 @@ From the standpoint of the plugin, it would need to ensure that it ships a gschemas.compiled file as part of itself, and then simply do the following: -|[<!-- language="C" --> +```c { GSettings *settings; gint some_value; settings = plugin_get_settings (self, NULL); some_value = g_settings_get_int (settings, "some-value"); - ... + … } -]| +``` It's also possible that the plugin system expects the schema source -files (ie: .gschema.xml files) instead of a gschemas.compiled file. +files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file. In that case, the plugin loading system must compile the schemas for itself before attempting to create the settings source. - + Get the ID of @schema. - + filename="gio/gsettingsschema.c" + line="1257">Get the ID of @schema. + the ID + filename="gio/gsettingsschema.c" + line="1263">the ID a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="1259">a #GSettingsSchema @@ -99994,29 +104209,29 @@ itself before attempting to create the settings source. c:identifier="g_settings_schema_get_key" version="2.40"> Gets the key named @name from @schema. + filename="gio/gsettingsschema.c" + line="1650">Gets the key named @name from @schema. It is a programmer error to request a key that does not exist. See g_settings_schema_list_keys(). - + the #GSettingsSchemaKey for @name + filename="gio/gsettingsschema.c" + line="1660">the #GSettingsSchemaKey for @name a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="1652">a #GSettingsSchema the name of a key + filename="gio/gsettingsschema.c" + line="1653">the name of a key @@ -100025,8 +104240,8 @@ g_settings_schema_list_keys(). c:identifier="g_settings_schema_get_path" version="2.32"> Gets the path associated with @schema, or %NULL. + filename="gio/gsettingsschema.c" + line="1013">Gets the path associated with @schema, or %NULL. Schemas may be single-instance or relocatable. Single-instance schemas correspond to exactly one set of keys in the backend @@ -100035,18 +104250,18 @@ database: those located at the path returned by this function. Relocatable schemas can be referenced by other schemas and can therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return %NULL. - + the path of the schema, or %NULL + filename="gio/gsettingsschema.c" + line="1027">the path of the schema, or %NULL a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="1015">a #GSettingsSchema @@ -100055,26 +104270,26 @@ relocatable schemas, this function will return %NULL. c:identifier="g_settings_schema_has_key" version="2.40"> Checks if @schema has a key named @name. - + filename="gio/gsettingsschema.c" + line="1043">Checks if @schema has a key named @name. + %TRUE if such a key exists + filename="gio/gsettingsschema.c" + line="1050">%TRUE if such a key exists a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="1045">a #GSettingsSchema the name of a key + filename="gio/gsettingsschema.c" + line="1046">the name of a key @@ -100083,16 +104298,16 @@ relocatable schemas, this function will return %NULL. c:identifier="g_settings_schema_list_children" version="2.44"> Gets the list of children in @schema. + filename="gio/gsettingsschema.c" + line="1070">Gets the list of children in @schema. You should free the return value with g_strfreev() when you are done with it. - + a list of + filename="gio/gsettingsschema.c" + line="1079">a list of the children on @settings, in no defined order @@ -100101,8 +104316,8 @@ with it. a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="1072">a #GSettingsSchema @@ -100111,17 +104326,17 @@ with it. c:identifier="g_settings_schema_list_keys" version="2.46"> Introspects the list of keys on @schema. + filename="gio/gsettingsschema.c" + line="1114">Introspects the list of keys on @schema. You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons. - + a list + filename="gio/gsettingsschema.c" + line="1124">a list of the keys on @schema, in no defined order @@ -100130,28 +104345,28 @@ function is intended for introspection reasons. a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="1116">a #GSettingsSchema Increase the reference count of @schema, returning a new reference. - + filename="gio/gsettingsschema.c" + line="913">Increase the reference count of @schema, returning a new reference. + a new reference to @schema + filename="gio/gsettingsschema.c" + line="919">a new reference to @schema a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="915">a #GSettingsSchema @@ -100160,17 +104375,17 @@ function is intended for introspection reasons. c:identifier="g_settings_schema_unref" version="2.32"> Decrease the reference count of @schema, possibly freeing it. - + filename="gio/gsettingsschema.c" + line="931">Decrease the reference count of @schema, possibly freeing it. + a #GSettingsSchema + filename="gio/gsettingsschema.c" + line="933">a #GSettingsSchema @@ -100183,31 +104398,31 @@ function is intended for introspection reasons. glib:get-type="g_settings_schema_key_get_type" c:symbol-prefix="settings_schema_key"> #GSettingsSchemaKey is an opaque data structure and can only be accessed + filename="gio/gsettingsschema.c" + line="137">#GSettingsSchemaKey is an opaque data structure and can only be accessed using the following functions. - + Gets the default value for @key. + filename="gio/gsettingsschema.c" + line="1785">Gets the default value for @key. Note that this is the default value according to the schema. System administrator defaults and lockdown are not visible via this API. - + the default value for the key + filename="gio/gsettingsschema.c" + line="1794">the default value for the key a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1787">a #GSettingsSchemaKey @@ -100216,8 +104431,8 @@ administrator defaults and lockdown are not visible via this API. c:identifier="g_settings_schema_key_get_description" version="2.34"> Gets the description for @key. + filename="gio/gsettingsschema.c" + line="1732">Gets the description for @key. If no description has been provided in the schema for @key, returns %NULL. @@ -100231,18 +104446,18 @@ This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. - + the description for @key, or %NULL + filename="gio/gsettingsschema.c" + line="1751">the description for @key, or %NULL a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1734">a #GSettingsSchemaKey @@ -100251,20 +104466,20 @@ directory. c:identifier="g_settings_schema_key_get_name" version="2.44"> Gets the name of @key. - + filename="gio/gsettingsschema.c" + line="1680">Gets the name of @key. + the name of @key. + filename="gio/gsettingsschema.c" + line="1686">the name of @key. a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1682">a #GSettingsSchemaKey @@ -100273,8 +104488,8 @@ directory. c:identifier="g_settings_schema_key_get_range" version="2.40"> Queries the range of a key. + filename="gio/gsettingsschema.c" + line="1816">Queries the range of a key. This function will return a #GVariant that fully describes the range of values that are valid for @key. @@ -100310,18 +104525,18 @@ forms may be added to the possibilities described above. You should free the returned value with g_variant_unref() when it is no longer needed. - + a #GVariant describing the range + filename="gio/gsettingsschema.c" + line="1857">a #GVariant describing the range a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1818">a #GSettingsSchemaKey @@ -100330,8 +104545,8 @@ no longer needed. c:identifier="g_settings_schema_key_get_summary" version="2.34"> Gets the summary for @key. + filename="gio/gsettingsschema.c" + line="1698">Gets the summary for @key. If no summary has been provided in the schema for @key, returns %NULL. @@ -100344,18 +104559,18 @@ This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. - + the summary for @key, or %NULL + filename="gio/gsettingsschema.c" + line="1716">the summary for @key, or %NULL a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1700">a #GSettingsSchemaKey @@ -100364,20 +104579,20 @@ directory. c:identifier="g_settings_schema_key_get_value_type" version="2.40"> Gets the #GVariantType of @key. - + filename="gio/gsettingsschema.c" + line="1767">Gets the #GVariantType of @key. + the type of @key + filename="gio/gsettingsschema.c" + line="1773">the type of @key a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1769">a #GSettingsSchemaKey @@ -100386,30 +104601,30 @@ directory. c:identifier="g_settings_schema_key_range_check" version="2.40"> Checks if the given @value is within the + filename="gio/gsettingsschema.c" + line="1886">Checks if the given @value is within the permitted range for @key. It is a programmer error if @value is not of the correct type — you must check for this first. - + %TRUE if @value is valid for @key + filename="gio/gsettingsschema.c" + line="1897">%TRUE if @value is valid for @key a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1888">a #GSettingsSchemaKey the value to check + filename="gio/gsettingsschema.c" + line="1889">the value to check @@ -100418,20 +104633,20 @@ must check for this first. c:identifier="g_settings_schema_key_ref" version="2.40"> Increase the reference count of @key, returning a new reference. - + filename="gio/gsettingsschema.c" + line="1609">Increase the reference count of @key, returning a new reference. + a new reference to @key + filename="gio/gsettingsschema.c" + line="1615">a new reference to @key a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1611">a #GSettingsSchemaKey @@ -100440,17 +104655,17 @@ must check for this first. c:identifier="g_settings_schema_key_unref" version="2.40"> Decrease the reference count of @key, possibly freeing it. - + filename="gio/gsettingsschema.c" + line="1629">Decrease the reference count of @key, possibly freeing it. + a #GSettingsSchemaKey + filename="gio/gsettingsschema.c" + line="1631">a #GSettingsSchemaKey @@ -100464,16 +104679,16 @@ must check for this first. glib:get-type="g_settings_schema_source_get_type" c:symbol-prefix="settings_schema_source"> This is an opaque structure type. You may not access it directly. - + filename="gio/gsettingsschema.c" + line="177">This is an opaque structure type. You may not access it directly. + Attempts to create a new schema source corresponding to the contents + filename="gio/gsettingsschema.c" + line="246">Attempts to create a new schema source corresponding to the contents of the given directory. This function is not required for normal uses of #GSettings but it @@ -100504,15 +104719,15 @@ from the @parent. For this second reason, except in very unusual situations, the @parent should probably be given as the default schema source, as returned by g_settings_schema_source_get_default(). - + the filename of a directory + filename="gio/gsettingsschema.c" + line="248">the filename of a directory nullable="1" allow-none="1"> a #GSettingsSchemaSource, or %NULL + filename="gio/gsettingsschema.c" + line="249">a #GSettingsSchemaSource, or %NULL %TRUE, if the directory is trusted + filename="gio/gsettingsschema.c" + line="250">%TRUE, if the directory is trusted @@ -100536,8 +104751,8 @@ returned by g_settings_schema_source_get_default(). c:identifier="g_settings_schema_source_list_schemas" version="2.40"> Lists the schemas in a given source. + filename="gio/gsettingsschema.c" + line="754">Lists the schemas in a given source. If @recursive is %TRUE then include parent sources. If %FALSE then only include the schemas from one source (ie: one directory). You @@ -100549,21 +104764,21 @@ use g_settings_new_with_path(). Do not call this function from normal programs. This is designed for use by database editors, commandline tools, etc. - + a #GSettingsSchemaSource + filename="gio/gsettingsschema.c" + line="756">a #GSettingsSchemaSource if we should recurse + filename="gio/gsettingsschema.c" + line="757">if we should recurse caller-allocates="0" transfer-ownership="full"> the + filename="gio/gsettingsschema.c" + line="758">the list of non-relocatable schemas, in no defined order @@ -100583,8 +104798,8 @@ use by database editors, commandline tools, etc. caller-allocates="0" transfer-ownership="full"> the list + filename="gio/gsettingsschema.c" + line="760">the list of relocatable schemas, in no defined order @@ -100596,8 +104811,8 @@ use by database editors, commandline tools, etc. c:identifier="g_settings_schema_source_lookup" version="2.32"> Looks up a schema with the identifier @schema_id in @source. + filename="gio/gsettingsschema.c" + line="405">Looks up a schema with the identifier @schema_id in @source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who @@ -100607,30 +104822,30 @@ If the schema isn't found directly in @source and @recursive is %TRUE then the parent sources will also be checked. If the schema isn't found, %NULL is returned. - + a new #GSettingsSchema + filename="gio/gsettingsschema.c" + line="422">a new #GSettingsSchema a #GSettingsSchemaSource + filename="gio/gsettingsschema.c" + line="407">a #GSettingsSchemaSource a schema ID + filename="gio/gsettingsschema.c" + line="408">a schema ID %TRUE if the lookup should be recursive + filename="gio/gsettingsschema.c" + line="409">%TRUE if the lookup should be recursive @@ -100639,20 +104854,20 @@ If the schema isn't found, %NULL is returned. c:identifier="g_settings_schema_source_ref" version="2.32"> Increase the reference count of @source, returning a new reference. - + filename="gio/gsettingsschema.c" + line="196">Increase the reference count of @source, returning a new reference. + a new reference to @source + filename="gio/gsettingsschema.c" + line="202">a new reference to @source a #GSettingsSchemaSource + filename="gio/gsettingsschema.c" + line="198">a #GSettingsSchemaSource @@ -100661,17 +104876,17 @@ If the schema isn't found, %NULL is returned. c:identifier="g_settings_schema_source_unref" version="2.32"> Decrease the reference count of @source, possibly freeing it. - + filename="gio/gsettingsschema.c" + line="214">Decrease the reference count of @source, possibly freeing it. + a #GSettingsSchemaSource + filename="gio/gsettingsschema.c" + line="216">a #GSettingsSchemaSource @@ -100680,8 +104895,8 @@ If the schema isn't found, %NULL is returned. c:identifier="g_settings_schema_source_get_default" version="2.32"> Gets the default system schema source. + filename="gio/gsettingsschema.c" + line="376">Gets the default system schema source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who @@ -100694,11 +104909,11 @@ from different directories, depending on which directories were given in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all lookups performed against the default source should probably be done recursively. - + the default schema source + filename="gio/gsettingsschema.c" + line="393">the default schema source @@ -100710,34 +104925,32 @@ recursively. glib:type-name="GSimpleAction" glib:get-type="g_simple_action_get_type"> A #GSimpleAction is the obvious simple implementation of the #GAction -interface. This is the easiest way to create an action for purposes of -adding it to a #GSimpleActionGroup. - -See also #GtkAction. + filename="gio/gsimpleaction.c" + line="29">A `GSimpleAction` is the obvious simple implementation of the +[iface@Gio.Action] interface. This is the easiest way to create an action for +purposes of adding it to a [class@Gio.SimpleActionGroup]. Creates a new action. + filename="gio/gsimpleaction.c" + line="575">Creates a new action. The created action is stateless. See g_simple_action_new_stateful() to create an action that has state. - + a new #GSimpleAction + filename="gio/gsimpleaction.c" + line="586">a new #GSimpleAction the name of the action + filename="gio/gsimpleaction.c" + line="577">the name of the action nullable="1" allow-none="1"> the type of parameter that will be passed to + filename="gio/gsimpleaction.c" + line="578">the type of parameter that will be passed to handlers for the #GSimpleAction::activate signal, or %NULL for no parameter @@ -100756,25 +104969,25 @@ an action that has state. c:identifier="g_simple_action_new_stateful" version="2.28"> Creates a new stateful action. + filename="gio/gsimpleaction.c" + line="602">Creates a new stateful action. All future state values must have the same #GVariantType as the initial @state. If the @state #GVariant is floating, it is consumed. - + a new #GSimpleAction + filename="gio/gsimpleaction.c" + line="616">a new #GSimpleAction the name of the action + filename="gio/gsimpleaction.c" + line="604">the name of the action nullable="1" allow-none="1"> the type of the parameter that will be passed to + filename="gio/gsimpleaction.c" + line="605">the type of the parameter that will be passed to handlers for the #GSimpleAction::activate signal, or %NULL for no parameter the initial state of the action + filename="gio/gsimpleaction.c" + line="607">the initial state of the action @@ -100800,29 +105013,29 @@ If the @state #GVariant is floating, it is consumed. glib:set-property="enabled" version="2.28"> Sets the action as enabled or not. + filename="gio/gsimpleaction.c" + line="517">Sets the action as enabled or not. An action must be enabled in order to be activated or in order to have its state changed from outside callers. This should only be called by the implementor of the action. Users of the action should not attempt to modify its enabled flag. - + a #GSimpleAction + filename="gio/gsimpleaction.c" + line="519">a #GSimpleAction whether the action is enabled + filename="gio/gsimpleaction.c" + line="520">whether the action is enabled @@ -100832,8 +105045,8 @@ of the action should not attempt to modify its enabled flag. glib:set-property="state" version="2.30"> Sets the state of the action. + filename="gio/gsimpleaction.c" + line="137">Sets the state of the action. This directly updates the 'state' property to the given value. @@ -100843,21 +105056,21 @@ property. Instead, they should call g_action_change_state() to request the change. If the @value GVariant is floating, it is consumed. - + a #GSimpleAction + filename="gio/gsimpleaction.c" + line="139">a #GSimpleAction the new #GVariant for the state + filename="gio/gsimpleaction.c" + line="140">the new #GVariant for the state @@ -100866,20 +105079,20 @@ If the @value GVariant is floating, it is consumed. c:identifier="g_simple_action_set_state_hint" version="2.44"> Sets the state hint for the action. + filename="gio/gsimpleaction.c" + line="547">Sets the state hint for the action. See g_action_get_state_hint() for more information about action state hints. - + a #GSimpleAction + filename="gio/gsimpleaction.c" + line="549">a #GSimpleAction nullable="1" allow-none="1"> a #GVariant representing the state hint + filename="gio/gsimpleaction.c" + line="550">a #GVariant representing the state hint @@ -100900,8 +105113,8 @@ action state hints. setter="set_enabled" default-value="TRUE"> If @action is currently enabled. + filename="gio/gsimpleaction.c" + line="472">If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. @@ -100914,8 +105127,8 @@ g_action_change_state() have no effect. transfer-ownership="none" default-value="NULL"> The name of the action. This is mostly meaningful for identifying + filename="gio/gsimpleaction.c" + line="442">The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GSimpleActionGroup. @@ -100925,8 +105138,8 @@ the action once it has been added to a #GSimpleActionGroup. construct-only="1" transfer-ownership="none"> The type of the parameter that must be given when activating the + filename="gio/gsimpleaction.c" + line="457">The type of the parameter that must be given when activating the action. @@ -100937,21 +105150,21 @@ action. transfer-ownership="none" setter="set_state"> The state of the action, or %NULL if the action is stateless. + filename="gio/gsimpleaction.c" + line="502">The state of the action, or %NULL if the action is stateless. The #GVariantType of the state that the action has, or %NULL if the + filename="gio/gsimpleaction.c" + line="488">The #GVariantType of the state that the action has, or %NULL if the action is stateless. Indicates that the action was just activated. + filename="gio/gsimpleaction.c" + line="361">Indicates that the action was just activated. @parameter will always be of the expected type, i.e. the parameter type specified when the action was created. If an incorrect type is given when @@ -100973,8 +105186,8 @@ of #GSimpleAction to connect only one handler or the other. nullable="1" allow-none="1"> the parameter to the activation, or %NULL if it has + filename="gio/gsimpleaction.c" + line="364">the parameter to the activation, or %NULL if it has no parameter @@ -100982,8 +105195,8 @@ of #GSimpleAction to connect only one handler or the other. Indicates that the action just received a request to change its + filename="gio/gsimpleaction.c" + line="392">Indicates that the action just received a request to change its state. @value will always be of the correct state type, i.e. the type of the @@ -101025,8 +105238,8 @@ It could set it to any value at all, or take some other action. nullable="1" allow-none="1"> the requested value for the state + filename="gio/gsimpleaction.c" + line="395">the requested value for the state @@ -101041,23 +105254,24 @@ It could set it to any value at all, or take some other action. glib:get-type="g_simple_action_group_get_type" glib:type-struct="SimpleActionGroupClass"> #GSimpleActionGroup is a hash table filled with #GAction objects, -implementing the #GActionGroup and #GActionMap interfaces. - + filename="gio/gsimpleactiongroup.c" + line="30">`GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects, +implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] +interfaces. + Creates a new, empty, #GSimpleActionGroup. - + filename="gio/gsimpleactiongroup.c" + line="293">Creates a new, empty, #GSimpleActionGroup. + a new #GSimpleActionGroup + filename="gio/gsimpleactiongroup.c" + line="298">a new #GSimpleActionGroup @@ -101067,25 +105281,25 @@ implementing the #GActionGroup and #GActionMap interfaces. deprecated="1" deprecated-version="2.38"> A convenience function for creating multiple #GSimpleAction instances + filename="gio/gsimpleactiongroup.c" + line="380">A convenience function for creating multiple #GSimpleAction instances and adding them to the action group. Use g_action_map_add_action_entries() - + a #GSimpleActionGroup + filename="gio/gsimpleactiongroup.c" + line="382">a #GSimpleActionGroup a pointer to the first item in + filename="gio/gsimpleactiongroup.c" + line="383">a pointer to the first item in an array of #GActionEntry structs @@ -101093,8 +105307,8 @@ and adding them to the action group. the length of @entries, or -1 + filename="gio/gsimpleactiongroup.c" + line="385">the length of @entries, or -1 nullable="1" allow-none="1"> the user data for signal connections + filename="gio/gsimpleactiongroup.c" + line="386">the user data for signal connections @@ -101114,29 +105328,29 @@ and adding them to the action group. deprecated="1" deprecated-version="2.38"> Adds an action to the action group. + filename="gio/gsimpleactiongroup.c" + line="332">Adds an action to the action group. If the action group already contains an action with the same name as @action then the old action is dropped from the group. The action group takes its own reference on @action. Use g_action_map_add_action() - + a #GSimpleActionGroup + filename="gio/gsimpleactiongroup.c" + line="334">a #GSimpleActionGroup a #GAction + filename="gio/gsimpleactiongroup.c" + line="335">a #GAction @@ -101147,29 +105361,29 @@ The action group takes its own reference on @action. deprecated="1" deprecated-version="2.38"> Looks up the action with the name @action_name in the group. + filename="gio/gsimpleactiongroup.c" + line="308">Looks up the action with the name @action_name in the group. If no such action exists, returns %NULL. Use g_action_map_lookup_action() - + a #GAction, or %NULL + filename="gio/gsimpleactiongroup.c" + line="317">a #GAction, or %NULL a #GSimpleActionGroup + filename="gio/gsimpleactiongroup.c" + line="310">a #GSimpleActionGroup the name of an action + filename="gio/gsimpleactiongroup.c" + line="311">the name of an action @@ -101180,26 +105394,26 @@ If no such action exists, returns %NULL. deprecated="1" deprecated-version="2.38"> Removes the named action from the action group. + filename="gio/gsimpleactiongroup.c" + line="357">Removes the named action from the action group. If no action of this name is in the group then nothing happens. Use g_action_map_remove_action() - + a #GSimpleActionGroup + filename="gio/gsimpleactiongroup.c" + line="359">a #GSimpleActionGroup the name of the action + filename="gio/gsimpleactiongroup.c" + line="360">the name of the action @@ -101215,7 +105429,7 @@ If no action of this name is in the group then nothing happens. - + @@ -101229,7 +105443,7 @@ If no action of this name is in the group then nothing happens. c:type="GSimpleActionGroupPrivate" disguised="1" opaque="1"> - + glib:get-type="g_simple_async_result_get_type" glib:type-struct="SimpleAsyncResultClass"> As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of -#GTask, which provides a simpler API. + filename="gio/gsimpleasyncresult.c" + line="35">As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of +[class@Gio.Task], which provides a simpler API. -#GSimpleAsyncResult implements #GAsyncResult. +`GSimpleAsyncResult` implements [iface@Gio.AsyncResult]. -GSimpleAsyncResult handles #GAsyncReadyCallbacks, error +`GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error reporting, operation cancellation and the final state of an operation, completely transparent to the application. Results can be returned as a pointer e.g. for functions that return data that is collected asynchronously, a boolean value for checking the success or failure -of an operation, or a #gssize for operations which return the number +of an operation, or a `gssize` for operations which return the number of bytes modified by the operation; all of the simple return cases are covered. Most of the time, an application will not need to know of the details of this API; it is handled transparently, and any necessary operations -are handled by #GAsyncResult's interface. However, if implementing a -new GIO module, for writing language bindings, or for complex +are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing +a new GIO module, for writing language bindings, or for complex applications that need better control of how asynchronous operations are completed, it is important to understand this functionality. -GSimpleAsyncResults are tagged with the calling function to ensure +`GSimpleAsyncResult`s are tagged with the calling function to ensure that asynchronous functions and their finishing functions are used together correctly. -To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). -If the result needs to be created for a #GError, use -g_simple_async_result_new_from_error() or -g_simple_async_result_new_take_error(). If a #GError is not available -(e.g. the asynchronous operation's doesn't take a #GError argument), +To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new]. +If the result needs to be created for a `GError`, use +[ctor@Gio.SimpleAsyncResult.new_from_error] or +[ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available +(e.g. the asynchronous operation doesn’t take a `GError` argument), but the result still needs to be created for an error condition, use -g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() -if your application or binding requires passing a variable argument list -directly), and the error can then be propagated through the use of -g_simple_async_result_propagate_error(). +[ctor@Gio.SimpleAsyncResult.new_error] (or +[method@Gio.SimpleAsyncResult.set_error_va] if your application or binding +requires passing a variable argument list directly), and the error can then +be propagated through the use of +[method@Gio.SimpleAsyncResult.propagate_error]. An asynchronous operation can be made to ignore a cancellation event by -calling g_simple_async_result_set_handle_cancellation() with a -#GSimpleAsyncResult for the operation and %FALSE. This is useful for +calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a +`GSimpleAsyncResult` for the operation and `FALSE`. This is useful for operations that are dangerous to cancel, such as close (which would cause a leak if cancelled before being run). -GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, -or it can use #GThreads. -g_simple_async_result_complete() will finish an I/O task directly -from the point where it is called. g_simple_async_result_complete_in_idle() -will finish it from an idle handler in the -[thread-default main context][g-main-context-push-thread-default] -where the #GSimpleAsyncResult was created. -g_simple_async_result_run_in_thread() will run the job in a -separate thread and then use -g_simple_async_result_complete_in_idle() to deliver the result. +`GSimpleAsyncResult` can integrate into GLib’s event loop, +[type@GLib.MainLoop], or it can use [type@GLib.Thread]s. +[method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly +from the point where it is called. +[method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle +handler in the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult` +was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in +a separate thread and then use +[method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result. To set the results of an asynchronous function, -g_simple_async_result_set_op_res_gpointer(), -g_simple_async_result_set_op_res_gboolean(), and -g_simple_async_result_set_op_res_gssize() -are provided, setting the operation's result to a gpointer, gboolean, or -gssize, respectively. +[method@Gio.SimpleAsyncResult.set_op_res_gpointer], +[method@Gio.SimpleAsyncResult.set_op_res_gboolean], and +[method@Gio.SimpleAsyncResult.set_op_res_gssize] +are provided, setting the operation's result to a `gpointer`, `gboolean`, or +`gssize`, respectively. Likewise, to get the result of an asynchronous function, -g_simple_async_result_get_op_res_gpointer(), -g_simple_async_result_get_op_res_gboolean(), and -g_simple_async_result_get_op_res_gssize() are -provided, getting the operation's result as a gpointer, gboolean, and -gssize, respectively. +[method@Gio.SimpleAsyncResult.get_op_res_gpointer], +[method@Gio.SimpleAsyncResult.get_op_res_gboolean], and +[method@Gio.SimpleAsyncResult.get_op_res_gssize] are +provided, getting the operation’s result as a `gpointer`, `gboolean`, and +`gssize`, respectively. For the details of the requirements implementations must respect, see -#GAsyncResult. A typical implementation of an asynchronous operation -using GSimpleAsyncResult looks something like this: +[iface@Gio.AsyncResult]. A typical implementation of an asynchronous +operation using `GSimpleAsyncResult` looks something like this: -|[<!-- language="C" --> +```c static void baked_cb (Cake *cake, gpointer user_data) @@ -101404,16 +105619,16 @@ baker_bake_cake_finish (Baker *self, cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); return g_object_ref (cake); } -]| - +``` + Creates a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="292">Creates a #GSimpleAsyncResult. The common convention is to create the #GSimpleAsyncResult in the function that starts the asynchronous operation and use that same @@ -101424,11 +105639,11 @@ probably should) then you should provide the user's cancellable to g_simple_async_result_set_check_cancellable() immediately after this function returns. Use g_task_new() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="310">a #GSimpleAsyncResult. @@ -101437,8 +105652,8 @@ this function returns. nullable="1" allow-none="1"> a #GObject, or %NULL. + filename="gio/gsimpleasyncresult.c" + line="294">a #GObject, or %NULL. scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="295">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="296">user data passed to @callback. nullable="1" allow-none="1"> the asynchronous function. + filename="gio/gsimpleasyncresult.c" + line="297">the asynchronous function. @@ -101478,14 +105693,14 @@ this function returns. deprecated="1" deprecated-version="2.46"> Creates a new #GSimpleAsyncResult with a set error. + filename="gio/gsimpleasyncresult.c" + line="401">Creates a new #GSimpleAsyncResult with a set error. Use g_task_new() and g_task_return_new_error() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="413">a #GSimpleAsyncResult. @@ -101494,8 +105709,8 @@ this function returns. nullable="1" allow-none="1"> a #GObject, or %NULL. + filename="gio/gsimpleasyncresult.c" + line="403">a #GObject, or %NULL. scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="404">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="405">user data passed to @callback. a #GQuark. + filename="gio/gsimpleasyncresult.c" + line="406">a #GQuark. an error code. + filename="gio/gsimpleasyncresult.c" + line="407">an error code. a string with format characters. + filename="gio/gsimpleasyncresult.c" + line="408">a string with format characters. a list of values to insert into @format. + filename="gio/gsimpleasyncresult.c" + line="409">a list of values to insert into @format. @@ -101549,14 +105764,14 @@ this function returns. deprecated="1" deprecated-version="2.46"> Creates a #GSimpleAsyncResult from an error condition. + filename="gio/gsimpleasyncresult.c" + line="336">Creates a #GSimpleAsyncResult from an error condition. Use g_task_new() and g_task_return_error() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="345">a #GSimpleAsyncResult. @@ -101565,8 +105780,8 @@ this function returns. nullable="1" allow-none="1"> a #GObject, or %NULL. + filename="gio/gsimpleasyncresult.c" + line="338">a #GObject, or %NULL. scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="339">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="340">user data passed to @callback. a #GError + filename="gio/gsimpleasyncresult.c" + line="341">a #GError @@ -101604,15 +105819,15 @@ this function returns. deprecated="1" deprecated-version="2.46"> Creates a #GSimpleAsyncResult from an error condition, and takes over the + filename="gio/gsimpleasyncresult.c" + line="367">Creates a #GSimpleAsyncResult from an error condition, and takes over the caller's ownership of @error, so the caller does not need to free it anymore. Use g_task_new() and g_task_return_error() instead. - + a #GSimpleAsyncResult + filename="gio/gsimpleasyncresult.c" + line="377">a #GSimpleAsyncResult @@ -101621,8 +105836,8 @@ caller's ownership of @error, so the caller does not need to free it anymore. a #GObject, or %NULL + filename="gio/gsimpleasyncresult.c" + line="369">a #GObject, or %NULL a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="370">a #GAsyncReadyCallback. user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="371">user data passed to @callback. a #GError + filename="gio/gsimpleasyncresult.c" + line="372">a #GError @@ -101659,8 +105874,8 @@ caller's ownership of @error, so the caller does not need to free it anymore. Ensures that the data passed to the _finish function of an async + filename="gio/gsimpleasyncresult.c" + line="952">Ensures that the data passed to the _finish function of an async operation is consistent. Three checks are performed. First, @result is checked to ensure that it is really a @@ -101673,18 +105888,18 @@ which this function is called). (Alternatively, if either @source_tag or @result's source tag is %NULL, then the source tag check is skipped.) Use #GTask and g_task_is_valid() instead. - + #TRUE if all checks passed or #FALSE if any failed. + filename="gio/gsimpleasyncresult.c" + line="971">#TRUE if all checks passed or #FALSE if any failed. the #GAsyncResult passed to the _finish function. + filename="gio/gsimpleasyncresult.c" + line="954">the #GAsyncResult passed to the _finish function. nullable="1" allow-none="1"> the #GObject passed to the _finish function. + filename="gio/gsimpleasyncresult.c" + line="955">the #GObject passed to the _finish function. nullable="1" allow-none="1"> the asynchronous function. + filename="gio/gsimpleasyncresult.c" + line="956">the asynchronous function. @@ -101712,8 +105927,8 @@ check is skipped.) deprecated="1" deprecated-version="2.46"> Completes an asynchronous I/O job immediately. Must be called in + filename="gio/gsimpleasyncresult.c" + line="765">Completes an asynchronous I/O job immediately. Must be called in the thread where the asynchronous result was to be delivered, as it invokes the callback directly. If you are in a different thread use g_simple_async_result_complete_in_idle(). @@ -101721,15 +105936,15 @@ g_simple_async_result_complete_in_idle(). Calling this function takes a reference to @simple for as long as is needed to complete the call. Use #GTask instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="767">a #GSimpleAsyncResult. @@ -101739,24 +105954,24 @@ is needed to complete the call. deprecated="1" deprecated-version="2.46"> Completes an asynchronous function in an idle handler in the -[thread-default main context][g-main-context-push-thread-default] + filename="gio/gsimpleasyncresult.c" + line="819">Completes an asynchronous function in an idle handler in the +thread-default main context (see [method@GLib.MainContext.push_thread_default]) of the thread that @simple was initially created in (and re-pushes that context around the invocation of the callback). Calling this function takes a reference to @simple for as long as is needed to complete the call. Use #GTask instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="821">a #GSimpleAsyncResult. @@ -101766,22 +105981,22 @@ is needed to complete the call. deprecated="1" deprecated-version="2.46"> Gets the operation result boolean from within the asynchronous result. + filename="gio/gsimpleasyncresult.c" + line="640">Gets the operation result boolean from within the asynchronous result. Use #GTask and g_task_propagate_boolean() instead. - + %TRUE if the operation's result was %TRUE, %FALSE + filename="gio/gsimpleasyncresult.c" + line="646">%TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE. a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="642">a #GSimpleAsyncResult. @@ -101792,21 +106007,21 @@ is needed to complete the call. deprecated="1" deprecated-version="2.46"> Gets a pointer result as returned by the asynchronous function. + filename="gio/gsimpleasyncresult.c" + line="569">Gets a pointer result as returned by the asynchronous function. Use #GTask and g_task_propagate_pointer() instead. - + a pointer from the result. + filename="gio/gsimpleasyncresult.c" + line="575">a pointer from the result. a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="571">a #GSimpleAsyncResult. @@ -101816,21 +106031,21 @@ is needed to complete the call. deprecated="1" deprecated-version="2.46"> Gets a gssize from the asynchronous result. + filename="gio/gsimpleasyncresult.c" + line="605">Gets a gssize from the asynchronous result. Use #GTask and g_task_propagate_int() instead. - + a gssize returned from the asynchronous function. + filename="gio/gsimpleasyncresult.c" + line="611">a gssize returned from the asynchronous function. a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="607">a #GSimpleAsyncResult. @@ -101841,21 +106056,21 @@ is needed to complete the call. deprecated="1" deprecated-version="2.46."> Gets the source tag for the #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="495">Gets the source tag for the #GSimpleAsyncResult. Use #GTask and g_task_get_source_tag() instead. - + a #gpointer to the source object for the #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="501">a #gpointer to the source object for the #GSimpleAsyncResult. a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="497">a #GSimpleAsyncResult. @@ -101866,26 +106081,26 @@ is needed to complete the call. deprecated-version="2.46" throws="1"> Propagates an error from within the simple asynchronous result to + filename="gio/gsimpleasyncresult.c" + line="512">Propagates an error from within the simple asynchronous result to a given destination. If the #GCancellable given to a prior call to g_simple_async_result_set_check_cancellable() is cancelled then this function will return %TRUE with @dest set appropriately. Use #GTask instead. - + %TRUE if the error was propagated to @dest. %FALSE otherwise. + filename="gio/gsimpleasyncresult.c" + line="524">%TRUE if the error was propagated to @dest. %FALSE otherwise. a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="514">a #GSimpleAsyncResult. @@ -101896,36 +106111,36 @@ function will return %TRUE with @dest set appropriately. deprecated="1" deprecated-version="2.46"> Runs the asynchronous job in a separate thread and then calls + filename="gio/gsimpleasyncresult.c" + line="914">Runs the asynchronous job in a separate thread and then calls g_simple_async_result_complete_in_idle() on @simple to return the result to the appropriate main loop. Calling this function takes a reference to @simple for as long as is needed to run the job and report its completion. Use #GTask and g_task_run_in_thread() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="916">a #GSimpleAsyncResult. a #GSimpleAsyncThreadFunc. + filename="gio/gsimpleasyncresult.c" + line="917">a #GSimpleAsyncThreadFunc. the io priority of the request. + filename="gio/gsimpleasyncresult.c" + line="918">the io priority of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsimpleasyncresult.c" + line="919">optional #GCancellable object, %NULL to ignore. @@ -101945,8 +106160,8 @@ is needed to run the job and report its completion. deprecated="1" deprecated-version="2.46"> Sets a #GCancellable to check before dispatching results. + filename="gio/gsimpleasyncresult.c" + line="1114">Sets a #GCancellable to check before dispatching results. This function has one very specific purpose: the provided cancellable is checked at the time of g_simple_async_result_propagate_error() If @@ -101962,15 +106177,15 @@ already been sent as an idle to the main context to be dispatched). The checking described above is done regardless of any call to the unrelated g_simple_async_result_set_handle_cancellation() function. Use #GTask instead. - + a #GSimpleAsyncResult + filename="gio/gsimpleasyncresult.c" + line="1116">a #GSimpleAsyncResult nullable="1" allow-none="1"> a #GCancellable to check, or %NULL to unset + filename="gio/gsimpleasyncresult.c" + line="1117">a #GCancellable to check, or %NULL to unset @@ -101990,42 +106205,42 @@ unrelated g_simple_async_result_set_handle_cancellation() function. deprecated="1" deprecated-version="2.46"> Sets an error within the asynchronous result without a #GError. + filename="gio/gsimpleasyncresult.c" + line="735">Sets an error within the asynchronous result without a #GError. Use #GTask and g_task_return_new_error() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="737">a #GSimpleAsyncResult. a #GQuark (usually %G_IO_ERROR). + filename="gio/gsimpleasyncresult.c" + line="738">a #GQuark (usually %G_IO_ERROR). an error code. + filename="gio/gsimpleasyncresult.c" + line="739">an error code. a formatted error reporting string. + filename="gio/gsimpleasyncresult.c" + line="740">a formatted error reporting string. a list of variables to fill in @format. + filename="gio/gsimpleasyncresult.c" + line="741">a list of variables to fill in @format. @@ -102036,43 +106251,43 @@ unrelated g_simple_async_result_set_handle_cancellation() function. deprecated="1" deprecated-version="2.46"> Sets an error within the asynchronous result without a #GError. + filename="gio/gsimpleasyncresult.c" + line="705">Sets an error within the asynchronous result without a #GError. Unless writing a binding, see g_simple_async_result_set_error(). Use #GTask and g_task_return_error() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="707">a #GSimpleAsyncResult. a #GQuark (usually %G_IO_ERROR). + filename="gio/gsimpleasyncresult.c" + line="708">a #GQuark (usually %G_IO_ERROR). an error code. + filename="gio/gsimpleasyncresult.c" + line="709">an error code. a formatted error reporting string. + filename="gio/gsimpleasyncresult.c" + line="710">a formatted error reporting string. va_list of arguments. + filename="gio/gsimpleasyncresult.c" + line="711">va_list of arguments. @@ -102082,24 +106297,24 @@ Unless writing a binding, see g_simple_async_result_set_error(). deprecated="1" deprecated-version="2.46"> Sets the result from a #GError. + filename="gio/gsimpleasyncresult.c" + line="658">Sets the result from a #GError. Use #GTask and g_task_return_error() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="660">a #GSimpleAsyncResult. #GError. + filename="gio/gsimpleasyncresult.c" + line="661">#GError. @@ -102109,27 +106324,27 @@ Unless writing a binding, see g_simple_async_result_set_error(). deprecated="1" deprecated-version="2.46"> Sets whether to handle cancellation within the asynchronous operation. + filename="gio/gsimpleasyncresult.c" + line="474">Sets whether to handle cancellation within the asynchronous operation. This function has nothing to do with g_simple_async_result_set_check_cancellable(). It only refers to the #GCancellable passed to g_simple_async_result_run_in_thread(). - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="476">a #GSimpleAsyncResult. a #gboolean. + filename="gio/gsimpleasyncresult.c" + line="477">a #gboolean. @@ -102139,24 +106354,24 @@ g_simple_async_result_set_check_cancellable(). It only refers to the deprecated="1" deprecated-version="2.46"> Sets the operation result to a boolean within the asynchronous result. + filename="gio/gsimpleasyncresult.c" + line="622">Sets the operation result to a boolean within the asynchronous result. Use #GTask and g_task_return_boolean() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="624">a #GSimpleAsyncResult. a #gboolean. + filename="gio/gsimpleasyncresult.c" + line="625">a #gboolean. @@ -102167,18 +106382,18 @@ g_simple_async_result_set_check_cancellable(). It only refers to the deprecated="1" deprecated-version="2.46"> Sets the operation result within the asynchronous result to a pointer. + filename="gio/gsimpleasyncresult.c" + line="547">Sets the operation result within the asynchronous result to a pointer. Use #GTask and g_task_return_pointer() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="549">a #GSimpleAsyncResult. a pointer result from an asynchronous function. + filename="gio/gsimpleasyncresult.c" + line="550">a pointer result from an asynchronous function. a #GDestroyNotify function. + filename="gio/gsimpleasyncresult.c" + line="551">a #GDestroyNotify function. @@ -102205,25 +106420,25 @@ g_simple_async_result_set_check_cancellable(). It only refers to the deprecated="1" deprecated-version="2.46"> Sets the operation result within the asynchronous result to + filename="gio/gsimpleasyncresult.c" + line="586">Sets the operation result within the asynchronous result to the given @op_res. Use #GTask and g_task_return_int() instead. - + a #GSimpleAsyncResult. + filename="gio/gsimpleasyncresult.c" + line="588">a #GSimpleAsyncResult. a #gssize. + filename="gio/gsimpleasyncresult.c" + line="589">a #gssize. @@ -102235,25 +106450,25 @@ the given @op_res. deprecated="1" deprecated-version="2.46"> Sets the result from @error, and takes over the caller's ownership + filename="gio/gsimpleasyncresult.c" + line="680">Sets the result from @error, and takes over the caller's ownership of @error, so the caller does not need to free it any more. Use #GTask and g_task_return_error() instead. - + a #GSimpleAsyncResult + filename="gio/gsimpleasyncresult.c" + line="682">a #GSimpleAsyncResult a #GError + filename="gio/gsimpleasyncresult.c" + line="683">a #GError @@ -102264,28 +106479,28 @@ of @error, so the caller does not need to free it any more. disguised="1" opaque="1" glib:is-gtype-struct-for="SimpleAsyncResult"> - + Simple thread function that runs an asynchronous operation and + filename="gio/giotypes.h" + line="289">Simple thread function that runs an asynchronous operation and checks for cancellation. - + a #GSimpleAsyncResult. + filename="gio/giotypes.h" + line="291">a #GSimpleAsyncResult. a #GObject. + filename="gio/giotypes.h" + line="292">a #GObject. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/giotypes.h" + line="293">optional #GCancellable object, %NULL to ignore. @@ -102307,40 +106522,42 @@ checks for cancellation. glib:type-name="GSimpleIOStream" glib:get-type="g_simple_io_stream_get_type"> GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and -#GOutputStream. This allows any pair of input and output streams to be used -with #GIOStream methods. - -This is useful when you obtained a #GInputStream and a #GOutputStream -by other means, for instance creating them with platform specific methods as -g_unix_input_stream_new() or g_win32_input_stream_new(), and you want -to take advantage of the methods provided by #GIOStream. + filename="gio/gsimpleiostream.c" + line="30">`GSimpleIOStream` creates a [class@Gio.IOStream] from an arbitrary +[class@Gio.InputStream] and [class@Gio.OutputStream]. This allows any pair of +input and output streams to be used with [class@Gio.IOStream] methods. + +This is useful when you obtained a [class@Gio.InputStream] and a +[class@Gio.OutputStream] by other means, for instance creating them with +platform specific methods as +[`g_unix_input_stream_new()`](../gio-unix/ctor.UnixInputStream.new.html) +(from `gio-unix-2.0.pc` / `GioUnix-2.0`), and you want to +take advantage of the methods provided by [class@Gio.IOStream]. Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. + filename="gio/gsimpleiostream.c" + line="195">Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. See also #GIOStream. - + a new #GSimpleIOStream instance. + filename="gio/gsimpleiostream.c" + line="203">a new #GSimpleIOStream instance. a #GInputStream. + filename="gio/gsimpleiostream.c" + line="197">a #GInputStream. a #GOutputStream. + filename="gio/gsimpleiostream.c" + line="198">a #GOutputStream. @@ -102350,6 +106567,9 @@ See also #GIOStream. writable="1" construct-only="1" transfer-ownership="none"> + The [class@Gio.InputStream] to read from. writable="1" construct-only="1" transfer-ownership="none"> + The [class@Gio.OutputStream] to write to. @@ -102367,31 +106590,32 @@ See also #GIOStream. glib:type-name="GSimplePermission" glib:get-type="g_simple_permission_get_type"> #GSimplePermission is a trivial implementation of #GPermission that -represents a permission that is either always or never allowed. The -value is given at construction and doesn't change. + filename="gio/gsimplepermission.c" + line="28">`GSimplePermission` is a trivial implementation of [class@Gio.Permission] +that represents a permission that is either always or never allowed. The +value is given at construction and doesn’t change. -Calling request or release will result in errors. +Calling [method@Gio.Permission.acquire] or [method@Gio.Permission.release] +on a `GSimplePermission` will result in errors. Creates a new #GPermission instance that represents an action that is + filename="gio/gsimplepermission.c" + line="58">Creates a new #GPermission instance that represents an action that is either always or never allowed. - + the #GSimplePermission, as a #GPermission + filename="gio/gsimplepermission.c" + line="65">the #GSimplePermission, as a #GPermission %TRUE if the action is allowed + filename="gio/gsimplepermission.c" + line="60">%TRUE if the action is allowed @@ -102406,31 +106630,31 @@ either always or never allowed. glib:get-type="g_simple_proxy_resolver_get_type" glib:type-struct="SimpleProxyResolverClass"> #GSimpleProxyResolver is a simple #GProxyResolver implementation + filename="gio/gsimpleproxyresolver.c" + line="36">`GSimpleProxyResolver` is a simple [iface@Gio.ProxyResolver] implementation that handles a single default proxy, multiple URI-scheme-specific proxies, and a list of hosts that proxies should not be used for. -#GSimpleProxyResolver is never the default proxy resolver, but it +`GSimpleProxyResolver` is never the default proxy resolver, but it can be used as the base class for another proxy resolver implementation, or it can be created and used manually, such as -with g_socket_client_set_proxy_resolver(). - +with [method@Gio.SocketClient.set_proxy_resolver]. + Creates a new #GSimpleProxyResolver. See + filename="gio/gsimpleproxyresolver.c" + line="493">Creates a new #GSimpleProxyResolver. See #GSimpleProxyResolver:default-proxy and #GSimpleProxyResolver:ignore-hosts for more details on how the arguments are interpreted. - + a new #GSimpleProxyResolver + filename="gio/gsimpleproxyresolver.c" + line="505">a new #GSimpleProxyResolver @@ -102439,8 +106663,8 @@ arguments are interpreted. nullable="1" allow-none="1"> the default proxy to use, eg + filename="gio/gsimpleproxyresolver.c" + line="495">the default proxy to use, eg "socks://192.168.1.1" @@ -102449,8 +106673,8 @@ arguments are interpreted. nullable="1" allow-none="1"> an optional list of hosts/IP addresses + filename="gio/gsimpleproxyresolver.c" + line="497">an optional list of hosts/IP addresses to not use a proxy for. @@ -102463,23 +106687,23 @@ arguments are interpreted. glib:set-property="default-proxy" version="2.36"> Sets the default proxy on @resolver, to be used for any URIs that + filename="gio/gsimpleproxyresolver.c" + line="519">Sets the default proxy on @resolver, to be used for any URIs that don't match #GSimpleProxyResolver:ignore-hosts or a proxy set via g_simple_proxy_resolver_set_uri_proxy(). If @default_proxy starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. - + a #GSimpleProxyResolver + filename="gio/gsimpleproxyresolver.c" + line="521">a #GSimpleProxyResolver nullable="1" allow-none="1"> the default proxy to use + filename="gio/gsimpleproxyresolver.c" + line="522">the default proxy to use @@ -102498,26 +106722,26 @@ the socks5, socks4a, and socks4 proxy types. glib:set-property="ignore-hosts" version="2.36"> Sets the list of ignored hosts. + filename="gio/gsimpleproxyresolver.c" + line="546">Sets the list of ignored hosts. See #GSimpleProxyResolver:ignore-hosts for more details on how the @ignore_hosts argument is interpreted. - + a #GSimpleProxyResolver + filename="gio/gsimpleproxyresolver.c" + line="548">a #GSimpleProxyResolver %NULL-terminated list of hosts/IP addresses + filename="gio/gsimpleproxyresolver.c" + line="549">%NULL-terminated list of hosts/IP addresses to not use a proxy for @@ -102529,8 +106753,8 @@ See #GSimpleProxyResolver:ignore-hosts for more details on how the c:identifier="g_simple_proxy_resolver_set_uri_proxy" version="2.36"> Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme + filename="gio/gsimpleproxyresolver.c" + line="571">Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme matches @uri_scheme (and which don't match #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy. @@ -102538,27 +106762,27 @@ As with #GSimpleProxyResolver:default-proxy, if @proxy starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. - + a #GSimpleProxyResolver + filename="gio/gsimpleproxyresolver.c" + line="573">a #GSimpleProxyResolver the URI scheme to add a proxy for + filename="gio/gsimpleproxyresolver.c" + line="574">the URI scheme to add a proxy for the proxy to use for @uri_scheme + filename="gio/gsimpleproxyresolver.c" + line="575">the proxy to use for @uri_scheme @@ -102569,8 +106793,8 @@ types. setter="set_default_proxy" default-value="NULL"> The default proxy URI that will be used for any URI that doesn't + filename="gio/gsimpleproxyresolver.c" + line="422">The default proxy URI that will be used for any URI that doesn't match #GSimpleProxyResolver:ignore-hosts, and doesn't match any of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). @@ -102584,8 +106808,8 @@ to all three of the socks5, socks4a, and socks4 proxy types. transfer-ownership="none" setter="set_ignore_hosts"> A list of hostnames and IP addresses that the resolver should + filename="gio/gsimpleproxyresolver.c" + line="439">A list of hostnames and IP addresses that the resolver should allow direct connections to. Entries can be in one of 4 formats: @@ -102634,13 +106858,13 @@ commonly used by other applications. - + - + @@ -102648,7 +106872,7 @@ commonly used by other applications. - + @@ -102656,7 +106880,7 @@ commonly used by other applications. - + @@ -102664,7 +106888,7 @@ commonly used by other applications. - + @@ -102672,7 +106896,7 @@ commonly used by other applications. - + @@ -102683,7 +106907,7 @@ commonly used by other applications. c:type="GSimpleProxyResolverPrivate" disguised="1" opaque="1"> - + glib:get-type="g_socket_get_type" glib:type-struct="SocketClass"> A #GSocket is a low-level networking primitive. It is a more or less + filename="gio/gsocket.c" + line="85">A `GSocket` is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows. -#GSocket is the platform independent base upon which the higher level +`GSocket` is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to -use it directly, but rather through classes like #GSocketClient, -#GSocketService and #GSocketConnection. However there may be cases where -direct use of #GSocket is useful. - -#GSocket implements the #GInitable interface, so if it is manually constructed -by e.g. g_object_new() you must call g_initable_init() and check the -results before using the object. This is done automatically in -g_socket_new() and g_socket_new_from_fd(), so these functions can return -%NULL. +use it directly, but rather through classes like [class@Gio.SocketClient], +[class@Gio.SocketService] and [class@Gio.SocketConnection]. However there may +be cases where direct use of `GSocket` is useful. + +`GSocket` implements the [iface@Gio.Initable] interface, so if it is manually +constructed by e.g. [ctor@GObject.Object.new] you must call +[method@Gio.Initable.init] and check the results before using the object. +This is done automatically in [ctor@Gio.Socket.new] and +[ctor@Gio.Socket.new_from_fd], so these functions can return `NULL`. Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that -would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. -To know when a call would successfully run you can call g_socket_condition_check(), -or g_socket_condition_wait(). You can also use g_socket_create_source() and -attach it to a #GMainContext to get callbacks when I/O is possible. +would block return immediately with a `G_IO_ERROR_WOULD_BLOCK` error. +To know when a call would successfully run you can call +[method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait]. +You can also use [method@Gio.Socket.create_source] and attach it to a +[type@GLib.MainContext] to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and -blocking mode is emulated in GSocket. +blocking mode is emulated in `GSocket`. When working in non-blocking mode applications should always be able to -handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other +handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable -until a write returns %G_IO_ERROR_WOULD_BLOCK. +until a write returns `G_IO_ERROR_WOULD_BLOCK`. -#GSockets can be either connection oriented or datagram based. +`GSocket`s can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is @@ -102737,16 +106962,34 @@ specified or received in each I/O operation. All socket file descriptors are set to be close-on-exec. -Note that creating a #GSocket causes the signal %SIGPIPE to be +Note that creating a `GSocket` causes the signal `SIGPIPE` to be ignored for the remainder of the program. If you are writing a -command-line utility that uses #GSocket, you may need to take into +command-line utility that uses `GSocket`, you may need to take into account the fact that your program will not automatically be killed -if it tries to write to %stdout after it has been closed. +if it tries to write to `stdout` after it has been closed. + +Like most other APIs in GLib, `GSocket` is not inherently thread safe. To use +a `GSocket` concurrently from multiple threads, you must implement your own +locking. -Like most other APIs in GLib, #GSocket is not inherently thread safe. To use -a #GSocket concurrently from multiple threads, you must implement your own -locking. - +## Nagle’s algorithm + +Since GLib 2.80, `GSocket` will automatically set the `TCP_NODELAY` option on +all `G_SOCKET_TYPE_STREAM` sockets. This disables +[Nagle’s algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) as it +typically does more harm than good on modern networks. + +If your application needs Nagle’s algorithm enabled, call +[method@Gio.Socket.set_option] after constructing a `GSocket` to enable it: +```c +socket = g_socket_new (…, G_SOCKET_TYPE_STREAM, …); +if (socket != NULL) + { + g_socket_set_option (socket, IPPROTO_TCP, TCP_NODELAY, FALSE, &local_error); + // handle error if needed + } +``` + version="2.22" throws="1"> Creates a new #GSocket with the defined family, type and protocol. + filename="gio/gsocket.c" + line="1337">Creates a new #GSocket with the defined family, type and protocol. If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type for the family and type is used. @@ -102768,31 +107011,31 @@ the family and type. The protocol id is passed directly to the operating system, so you can use protocols not listed in #GSocketProtocol if you know the protocol number used for it. - + a #GSocket or %NULL on error. + filename="gio/gsocket.c" + line="1358">a #GSocket or %NULL on error. Free the returned object with g_object_unref(). the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. + filename="gio/gsocket.c" + line="1339">the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. the socket type to use. + filename="gio/gsocket.c" + line="1340">the socket type to use. the id of the protocol to use, or 0 for default. + filename="gio/gsocket.c" + line="1341">the id of the protocol to use, or 0 for default. @@ -102802,8 +107045,8 @@ know the protocol number used for it. version="2.22" throws="1"> Creates a new #GSocket from a native file descriptor + filename="gio/gsocket.c" + line="1377">Creates a new #GSocket from a native file descriptor or winsock SOCKET handle. This reads all the settings from the file descriptor so that @@ -102816,19 +107059,19 @@ caller must close @fd themselves. Since GLib 2.46, it is no longer a fatal error to call this on a non-socket descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED - + a #GSocket or %NULL on error. + filename="gio/gsocket.c" + line="1396">a #GSocket or %NULL on error. Free the returned object with g_object_unref(). a native socket file descriptor. + filename="gio/gsocket.c" + line="1379">a native socket file descriptor. @@ -102838,8 +107081,8 @@ descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED version="2.22" throws="1"> Accept incoming connections on a connection-based socket. This removes + filename="gio/gsocket.c" + line="2936">Accept incoming connections on a connection-based socket. This removes the first outstanding connection request from the listening socket and creates a #GSocket object for it. @@ -102849,19 +107092,19 @@ must be listening for incoming connections (g_socket_listen()). If there are no outstanding connections then the operation will block or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the %G_IO_IN condition. - + a new #GSocket, or %NULL on error. + filename="gio/gsocket.c" + line="2953">a new #GSocket, or %NULL on error. Free the returned object with g_object_unref(). a #GSocket. + filename="gio/gsocket.c" + line="2938">a #GSocket. nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="2939">a %GCancellable or %NULL @@ -102880,8 +107123,8 @@ To be notified of an incoming connection, wait for the %G_IO_IN condition. version="2.22" throws="1"> When a socket is created it is attached to an address family, but it + filename="gio/gsocket.c" + line="2188">When a socket is created it is attached to an address family, but it doesn't have an address in this family. g_socket_bind() assigns the address (sometimes called name) of the socket. @@ -102904,30 +107147,30 @@ time. In particular, you can have several UDP sockets bound to the same address, and they will all receive all of the multicast and broadcast packets sent to that address. (The behavior of unicast UDP packets to an address with multiple listeners is not defined.) - + %TRUE on success, %FALSE on error. + filename="gio/gsocket.c" + line="2219">%TRUE on success, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="2190">a #GSocket. a #GSocketAddress specifying the local address. + filename="gio/gsocket.c" + line="2191">a #GSocketAddress specifying the local address. whether to allow reusing this address + filename="gio/gsocket.c" + line="2192">whether to allow reusing this address @@ -102937,22 +107180,22 @@ UDP packets to an address with multiple listeners is not defined.) version="2.22" throws="1"> Checks and resets the pending connect error for the socket. + filename="gio/gsocket.c" + line="3174">Checks and resets the pending connect error for the socket. This is used to check for errors when g_socket_connect() is used in non-blocking mode. - + %TRUE if no error, %FALSE otherwise, setting @error to the error + filename="gio/gsocket.c" + line="3183">%TRUE if no error, %FALSE otherwise, setting @error to the error a #GSocket + filename="gio/gsocket.c" + line="3176">a #GSocket @@ -102962,8 +107205,8 @@ used in non-blocking mode. version="2.22" throws="1"> Closes the socket, shutting down any active connection. + filename="gio/gsocket.c" + line="3930">Closes the socket, shutting down any active connection. Closing a socket does not wait for all outstanding I/O operations to finish, so the caller should not rely on them to be guaranteed @@ -102992,18 +107235,18 @@ connection, after which the server can safely call g_socket_close(). g_tcp_connection_set_graceful_disconnect(). But of course, this only works if the client will close its connection after the server does.) - + %TRUE on success, %FALSE on error + filename="gio/gsocket.c" + line="3965">%TRUE on success, %FALSE on error a #GSocket + filename="gio/gsocket.c" + line="3932">a #GSocket @@ -103012,8 +107255,8 @@ does.) c:identifier="g_socket_condition_check" version="2.22"> Checks on the readiness of @socket to perform operations. + filename="gio/gsocket.c" + line="4471">Checks on the readiness of @socket to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @socket. The result is returned. @@ -103030,24 +107273,24 @@ It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; these conditions will always be set in the output if they are true. This call never blocks. - + the @GIOCondition mask of the current state + filename="gio/gsocket.c" + line="4494">the @GIOCondition mask of the current state a #GSocket + filename="gio/gsocket.c" + line="4473">a #GSocket a #GIOCondition mask to check + filename="gio/gsocket.c" + line="4474">a #GIOCondition mask to check @@ -103057,8 +107300,8 @@ This call never blocks. version="2.32" throws="1"> Waits for up to @timeout_us microseconds for @condition to become true + filename="gio/gsocket.c" + line="4569">Waits for up to @timeout_us microseconds for @condition to become true on @socket. If the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if @@ -103074,30 +107317,30 @@ Note that although @timeout_us is in microseconds for consistency with other GLib APIs, this function actually only has millisecond resolution, and the behavior is undefined if @timeout_us is not an exact number of milliseconds. - + %TRUE if the condition was met, %FALSE otherwise + filename="gio/gsocket.c" + line="4594">%TRUE if the condition was met, %FALSE otherwise a #GSocket + filename="gio/gsocket.c" + line="4571">a #GSocket a #GIOCondition mask to wait for + filename="gio/gsocket.c" + line="4572">a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, or -1 + filename="gio/gsocket.c" + line="4573">the maximum time (in microseconds) to wait, or -1 nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocket.c" + line="4574">a #GCancellable, or %NULL @@ -103116,8 +107359,8 @@ exact number of milliseconds. version="2.22" throws="1"> Waits for @condition to become true on @socket. When the condition + filename="gio/gsocket.c" + line="4535">Waits for @condition to become true on @socket. When the condition is met, %TRUE is returned. If @cancellable is cancelled before the condition is met, or if the @@ -103127,24 +107370,24 @@ the appropriate value (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). See also g_socket_condition_timed_wait(). - + %TRUE if the condition was met, %FALSE otherwise + filename="gio/gsocket.c" + line="4553">%TRUE if the condition was met, %FALSE otherwise a #GSocket + filename="gio/gsocket.c" + line="4537">a #GSocket a #GIOCondition mask to wait for + filename="gio/gsocket.c" + line="4538">a #GIOCondition mask to wait for nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocket.c" + line="4539">a #GCancellable, or %NULL @@ -103163,8 +107406,8 @@ See also g_socket_condition_timed_wait(). version="2.22" throws="1"> Connect the socket to the specified remote address. + filename="gio/gsocket.c" + line="3072">Connect the socket to the specified remote address. For connection oriented socket this generally means we attempt to make a connection to the @address. For a connection-less socket it sets @@ -103180,24 +107423,24 @@ non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned and the user can be notified of the connection finishing by waiting for the G_IO_OUT condition. The result of the connection must then be checked with g_socket_check_connect_result(). - + %TRUE if connected, %FALSE on error. + filename="gio/gsocket.c" + line="3096">%TRUE if connected, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="3074">a #GSocket. a #GSocketAddress specifying the remote address. + filename="gio/gsocket.c" + line="3075">a #GSocketAddress specifying the remote address. nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3076">a %GCancellable or %NULL @@ -103215,21 +107458,21 @@ checked with g_socket_check_connect_result(). c:identifier="g_socket_connection_factory_create_connection" version="2.22"> Creates a #GSocketConnection subclass of the right type for + filename="gio/gsocketconnection.c" + line="675">Creates a #GSocketConnection subclass of the right type for @socket. - + a #GSocketConnection + filename="gio/gsocketconnection.c" + line="682">a #GSocketConnection a #GSocket + filename="gio/gsocketconnection.c" + line="677">a #GSocket @@ -103239,8 +107482,8 @@ checked with g_socket_check_connect_result(). version="2.22" introspectable="0"> Creates a #GSource that can be attached to a %GMainContext to monitor + filename="gio/gsocket.c" + line="4430">Creates a #GSource that can be attached to a %GMainContext to monitor for the availability of the specified @condition on the socket. The #GSource keeps a reference to the @socket. @@ -103260,24 +107503,24 @@ occurs, the source will then trigger anyway, reporting %G_IO_IN or %G_IO_OUT depending on @condition. However, @socket will have been marked as having had a timeout, and so the next #GSocket I/O method you call will then fail with a %G_IO_ERROR_TIMED_OUT. - + a newly allocated %GSource, free with g_source_unref(). + filename="gio/gsocket.c" + line="4457">a newly allocated %GSource, free with g_source_unref(). a #GSocket + filename="gio/gsocket.c" + line="4432">a #GSocket a #GIOCondition mask to monitor + filename="gio/gsocket.c" + line="4433">a #GIOCondition mask to monitor nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="4434">a %GCancellable or %NULL @@ -103295,8 +107538,8 @@ you call will then fail with a %G_IO_ERROR_TIMED_OUT. c:identifier="g_socket_get_available_bytes" version="2.32"> Get the amount of data pending in the OS input buffer, without blocking. + filename="gio/gsocket.c" + line="3225">Get the amount of data pending in the OS input buffer, without blocking. If @socket is a UDP or SCTP socket, this will return the size of just the next packet, even if additional packets are buffered after @@ -103308,19 +107551,19 @@ of the incoming packet, it is better to just do a g_socket_receive() with a buffer of that size, rather than calling g_socket_get_available_bytes() first and then doing a receive of exactly the right size. - + the number of bytes that can be read from the socket + filename="gio/gsocket.c" + line="3242">the number of bytes that can be read from the socket without blocking or truncating, or -1 on error. a #GSocket + filename="gio/gsocket.c" + line="3227">a #GSocket @@ -103330,21 +107573,21 @@ without blocking or truncating, or -1 on error. glib:get-property="blocking" version="2.22"> Gets the blocking mode of the socket. For details on blocking I/O, + filename="gio/gsocket.c" + line="1443">Gets the blocking mode of the socket. For details on blocking I/O, see g_socket_set_blocking(). - + %TRUE if blocking I/O is used, %FALSE otherwise. + filename="gio/gsocket.c" + line="1450">%TRUE if blocking I/O is used, %FALSE otherwise. a #GSocket. + filename="gio/gsocket.c" + line="1445">a #GSocket. @@ -103354,22 +107597,22 @@ see g_socket_set_blocking(). glib:get-property="broadcast" version="2.32"> Gets the broadcast setting on @socket; if %TRUE, + filename="gio/gsocket.c" + line="1721">Gets the broadcast setting on @socket; if %TRUE, it is possible to send packets to broadcast addresses. - + the broadcast setting on @socket + filename="gio/gsocket.c" + line="1729">the broadcast setting on @socket a #GSocket. + filename="gio/gsocket.c" + line="1723">a #GSocket. @@ -103379,8 +107622,8 @@ addresses. version="2.26" throws="1"> Returns the credentials of the foreign process connected to this + filename="gio/gsocket.c" + line="6259">Returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX sockets). @@ -103400,19 +107643,19 @@ Other ways to obtain credentials from a foreign peer includes the #GUnixCredentialsMessage type and g_unix_connection_send_credentials() / g_unix_connection_receive_credentials() functions. - + %NULL if @error is set, otherwise a #GCredentials object + filename="gio/gsocket.c" + line="6285">%NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref(). a #GSocket. + filename="gio/gsocket.c" + line="6261">a #GSocket. @@ -103422,20 +107665,20 @@ that must be freed with g_object_unref(). glib:get-property="family" version="2.22"> Gets the socket family of the socket. - + filename="gio/gsocket.c" + line="1960">Gets the socket family of the socket. + a #GSocketFamily + filename="gio/gsocket.c" + line="1966">a #GSocketFamily a #GSocket. + filename="gio/gsocket.c" + line="1962">a #GSocket. @@ -103445,24 +107688,24 @@ that must be freed with g_object_unref(). glib:get-property="fd" version="2.22"> Returns the underlying OS socket object. On unix this + filename="gio/gsocket.c" + line="2015">Returns the underlying OS socket object. On unix this is a socket file descriptor, and on Windows this is a Winsock2 SOCKET handle. This may be useful for doing platform specific or otherwise unusual operations on the socket. - + the file descriptor of the socket. + filename="gio/gsocket.c" + line="2025">the file descriptor of the socket. a #GSocket. + filename="gio/gsocket.c" + line="2017">a #GSocket. @@ -103472,21 +107715,21 @@ on the socket. glib:get-property="keepalive" version="2.22"> Gets the keepalive mode of the socket. For details on this, + filename="gio/gsocket.c" + line="1509">Gets the keepalive mode of the socket. For details on this, see g_socket_set_keepalive(). - + %TRUE if keepalive is active, %FALSE otherwise. + filename="gio/gsocket.c" + line="1516">%TRUE if keepalive is active, %FALSE otherwise. a #GSocket. + filename="gio/gsocket.c" + line="1511">a #GSocket. @@ -103496,21 +107739,21 @@ see g_socket_set_keepalive(). glib:get-property="listen-backlog" version="2.22"> Gets the listen backlog setting of the socket. For details on this, + filename="gio/gsocket.c" + line="1528">Gets the listen backlog setting of the socket. For details on this, see g_socket_set_listen_backlog(). - + the maximum number of pending connections. + filename="gio/gsocket.c" + line="1535">the maximum number of pending connections. a #GSocket. + filename="gio/gsocket.c" + line="1530">a #GSocket. @@ -103521,23 +107764,23 @@ see g_socket_set_listen_backlog(). version="2.22" throws="1"> Try to get the local address of a bound socket. This is only + filename="gio/gsocket.c" + line="2037">Try to get the local address of a bound socket. This is only useful if the socket has been bound to a local address, either explicitly or implicitly when connecting. - + a #GSocketAddress or %NULL on error. + filename="gio/gsocket.c" + line="2046">a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocket. + filename="gio/gsocket.c" + line="2039">a #GSocket. @@ -103547,22 +107790,22 @@ either explicitly or implicitly when connecting. glib:get-property="multicast-loopback" version="2.32"> Gets the multicast loopback setting on @socket; if %TRUE (the + filename="gio/gsocket.c" + line="1784">Gets the multicast loopback setting on @socket; if %TRUE (the default), outgoing multicast packets will be looped back to multicast listeners on the same host. - + the multicast loopback setting on @socket + filename="gio/gsocket.c" + line="1792">the multicast loopback setting on @socket a #GSocket. + filename="gio/gsocket.c" + line="1786">a #GSocket. @@ -103572,21 +107815,21 @@ multicast listeners on the same host. glib:get-property="multicast-ttl" version="2.32"> Gets the multicast time-to-live setting on @socket; see + filename="gio/gsocket.c" + line="1874">Gets the multicast time-to-live setting on @socket; see g_socket_set_multicast_ttl() for more details. - + the multicast time-to-live setting on @socket + filename="gio/gsocket.c" + line="1881">the multicast time-to-live setting on @socket a #GSocket. + filename="gio/gsocket.c" + line="1876">a #GSocket. @@ -103596,12 +107839,12 @@ g_socket_set_multicast_ttl() for more details. version="2.36" throws="1"> Gets the value of an integer-valued option on @socket, as with + filename="gio/gsocket.c" + line="6453">Gets the value of an integer-valued option on @socket, as with getsockopt(). (If you need to fetch a non-integer-valued option, you will need to call getsockopt() directly.) -The [<gio/gnetworking.h>][gio-gnetworking.h] +The [`<gio/gnetworking.h>`](networking.html) header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional @@ -103610,11 +107853,11 @@ headers. Note that even for socket options that are a single byte in size, @value is still a pointer to a #gint variable, not a #guchar; g_socket_get_option() will handle the conversion internally. - + success or failure. On failure, @error will be set, and + filename="gio/gsocket.c" + line="6475">success or failure. On failure, @error will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the getsockopt() call. @@ -103622,20 +107865,20 @@ g_socket_get_option() will handle the conversion internally. a #GSocket + filename="gio/gsocket.c" + line="6455">a #GSocket the "API level" of the option (eg, `SOL_SOCKET`) + filename="gio/gsocket.c" + line="6456">the "API level" of the option (eg, `SOL_SOCKET`) the "name" of the option (eg, `SO_BROADCAST`) + filename="gio/gsocket.c" + line="6457">the "name" of the option (eg, `SO_BROADCAST`) caller-allocates="0" transfer-ownership="full"> return location for the option value + filename="gio/gsocket.c" + line="6458">return location for the option value @@ -103654,21 +107897,21 @@ g_socket_get_option() will handle the conversion internally. glib:get-property="protocol" version="2.22"> Gets the socket protocol id the socket was created with. + filename="gio/gsocket.c" + line="1996">Gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned. - + a protocol id, or -1 if unknown + filename="gio/gsocket.c" + line="2003">a protocol id, or -1 if unknown a #GSocket. + filename="gio/gsocket.c" + line="1998">a #GSocket. @@ -103679,22 +107922,22 @@ In case the protocol is unknown, -1 is returned. version="2.22" throws="1"> Try to get the remote address of a connected socket. This is only + filename="gio/gsocket.c" + line="2074">Try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected. - + a #GSocketAddress or %NULL on error. + filename="gio/gsocket.c" + line="2082">a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocket. + filename="gio/gsocket.c" + line="2076">a #GSocket. @@ -103703,20 +107946,20 @@ useful for connection oriented sockets that have been connected. c:identifier="g_socket_get_socket_type" version="2.22"> Gets the socket type of the socket. - + filename="gio/gsocket.c" + line="1978">Gets the socket type of the socket. + a #GSocketType + filename="gio/gsocket.c" + line="1984">a #GSocketType a #GSocket. + filename="gio/gsocket.c" + line="1980">a #GSocket. @@ -103726,21 +107969,21 @@ useful for connection oriented sockets that have been connected. glib:get-property="timeout" version="2.26"> Gets the timeout setting of the socket. For details on this, see + filename="gio/gsocket.c" + line="1576">Gets the timeout setting of the socket. For details on this, see g_socket_set_timeout(). - + the timeout in seconds + filename="gio/gsocket.c" + line="1583">the timeout in seconds a #GSocket. + filename="gio/gsocket.c" + line="1578">a #GSocket. @@ -103750,21 +107993,21 @@ g_socket_set_timeout(). glib:get-property="ttl" version="2.32"> Gets the unicast time-to-live setting on @socket; see + filename="gio/gsocket.c" + line="1636">Gets the unicast time-to-live setting on @socket; see g_socket_set_ttl() for more details. - + the time-to-live setting on @socket + filename="gio/gsocket.c" + line="1643">the time-to-live setting on @socket a #GSocket. + filename="gio/gsocket.c" + line="1638">a #GSocket. @@ -103773,20 +108016,20 @@ g_socket_set_ttl() for more details. c:identifier="g_socket_is_closed" version="2.22"> Checks whether a socket is closed. - + filename="gio/gsocket.c" + line="4019">Checks whether a socket is closed. + %TRUE if socket is closed, %FALSE otherwise + filename="gio/gsocket.c" + line="4025">%TRUE if socket is closed, %FALSE otherwise a #GSocket + filename="gio/gsocket.c" + line="4021">a #GSocket @@ -103795,26 +108038,26 @@ g_socket_set_ttl() for more details. c:identifier="g_socket_is_connected" version="2.22"> Check whether the socket is connected. This is only useful for + filename="gio/gsocket.c" + line="2123">Check whether the socket is connected. This is only useful for connection-oriented sockets. If using g_socket_shutdown(), this function will return %TRUE until the socket has been shut down for reading and writing. If you do a non-blocking connect, this function will not return %TRUE until after you call g_socket_check_connect_result(). - + %TRUE if socket is connected, %FALSE otherwise. + filename="gio/gsocket.c" + line="2135">%TRUE if socket is connected, %FALSE otherwise. a #GSocket. + filename="gio/gsocket.c" + line="2125">a #GSocket. @@ -103824,8 +108067,8 @@ g_socket_check_connect_result(). version="2.32" throws="1"> Registers @socket to receive multicast messages sent to @group. + filename="gio/gsocket.c" + line="2561">Registers @socket to receive multicast messages sent to @group. @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have been bound to an appropriate interface and port with g_socket_bind(). @@ -103839,30 +108082,30 @@ with a %G_IO_ERROR_NOT_SUPPORTED error. To bind to a given source-specific multicast address, use g_socket_join_multicast_group_ssm() instead. - + %TRUE on success, %FALSE on error. + filename="gio/gsocket.c" + line="2584">%TRUE on success, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="2563">a #GSocket. a #GInetAddress specifying the group address to join. + filename="gio/gsocket.c" + line="2564">a #GInetAddress specifying the group address to join. %TRUE if source-specific multicast should be used + filename="gio/gsocket.c" + line="2566">%TRUE if source-specific multicast should be used nullable="1" allow-none="1"> Name of the interface to use, or %NULL + filename="gio/gsocket.c" + line="2565">Name of the interface to use, or %NULL @@ -103881,8 +108124,8 @@ g_socket_join_multicast_group_ssm() instead. version="2.56" throws="1"> Registers @socket to receive multicast messages sent to @group. + filename="gio/gsocket.c" + line="2818">Registers @socket to receive multicast messages sent to @group. @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have been bound to an appropriate interface and port with g_socket_bind(). @@ -103897,24 +108140,24 @@ with a %G_IO_ERROR_NOT_SUPPORTED error. Note that this function can be called multiple times for the same @group with different @source_specific in order to receive multicast packets from more than one source. - + %TRUE on success, %FALSE on error. + filename="gio/gsocket.c" + line="2843">%TRUE on success, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="2820">a #GSocket. a #GInetAddress specifying the group address to join. + filename="gio/gsocket.c" + line="2821">a #GInetAddress specifying the group address to join. nullable="1" allow-none="1"> a #GInetAddress specifying the + filename="gio/gsocket.c" + line="2822">a #GInetAddress specifying the source-specific multicast address or %NULL to ignore. @@ -103932,8 +108175,8 @@ source-specific multicast address or %NULL to ignore. nullable="1" allow-none="1"> Name of the interface to use, or %NULL + filename="gio/gsocket.c" + line="2824">Name of the interface to use, or %NULL @@ -103943,8 +108186,8 @@ source-specific multicast address or %NULL to ignore. version="2.32" throws="1"> Removes @socket from the multicast group defined by @group, @iface, + filename="gio/gsocket.c" + line="2598">Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group). @@ -103953,30 +108196,30 @@ unicast messages after calling this. To unbind to a given source-specific multicast address, use g_socket_leave_multicast_group_ssm() instead. - + %TRUE on success, %FALSE on error. + filename="gio/gsocket.c" + line="2616">%TRUE on success, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="2600">a #GSocket. a #GInetAddress specifying the group address to leave. + filename="gio/gsocket.c" + line="2601">a #GInetAddress specifying the group address to leave. %TRUE if source-specific multicast was used + filename="gio/gsocket.c" + line="2603">%TRUE if source-specific multicast was used nullable="1" allow-none="1"> Interface used + filename="gio/gsocket.c" + line="2602">Interface used @@ -103995,31 +108238,31 @@ g_socket_leave_multicast_group_ssm() instead. version="2.56" throws="1"> Removes @socket from the multicast group defined by @group, @iface, + filename="gio/gsocket.c" + line="2858">Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group). @socket remains bound to its address and port, and can still receive unicast messages after calling this. - + %TRUE on success, %FALSE on error. + filename="gio/gsocket.c" + line="2874">%TRUE on success, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="2860">a #GSocket. a #GInetAddress specifying the group address to leave. + filename="gio/gsocket.c" + line="2861">a #GInetAddress specifying the group address to leave. nullable="1" allow-none="1"> a #GInetAddress specifying the + filename="gio/gsocket.c" + line="2862">a #GInetAddress specifying the source-specific multicast address or %NULL to ignore. @@ -104037,8 +108280,8 @@ source-specific multicast address or %NULL to ignore. nullable="1" allow-none="1"> Name of the interface to use, or %NULL + filename="gio/gsocket.c" + line="2864">Name of the interface to use, or %NULL @@ -104048,8 +108291,8 @@ source-specific multicast address or %NULL to ignore. version="2.22" throws="1"> Marks the socket as a server socket, i.e. a socket that is used + filename="gio/gsocket.c" + line="2147">Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using g_socket_accept(). Before calling this the socket must be bound to a local address using @@ -104057,18 +108300,18 @@ g_socket_bind(). To set the maximum amount of outstanding clients, use g_socket_set_listen_backlog(). - + %TRUE on success, %FALSE on error. + filename="gio/gsocket.c" + line="2161">%TRUE on success, %FALSE on error. a #GSocket. + filename="gio/gsocket.c" + line="2149">a #GSocket. @@ -104078,8 +108321,8 @@ g_socket_set_listen_backlog(). version="2.22" throws="1"> Receive data (up to @size bytes) from a socket. This is mainly used by + filename="gio/gsocket.c" + line="3467">Receive data (up to @size bytes) from a socket. This is mainly used by connection-oriented sockets; it is identical to g_socket_receive_from() with @address set to %NULL. @@ -104102,19 +108345,19 @@ returned. To be notified when data is available, wait for the %G_IO_IN condition. On error -1 is returned and @error is set accordingly. - + Number of bytes read, or 0 if the connection was closed by + filename="gio/gsocket.c" + line="3500">Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket + filename="gio/gsocket.c" + line="3469">a #GSocket caller-allocates="1" transfer-ownership="none"> + filename="gio/gsocket.c" + line="3470"> a buffer to read data into (which should be at least @size bytes long). @@ -104131,17 +108374,141 @@ the peer, or -1 on error the number of bytes you want to read from the socket + filename="gio/gsocket.c" + line="3472">the number of bytes you want to read from the socket + + + + a %GCancellable or %NULL + + + + + + Receives data (up to @size bytes) from a socket. + +This function is a variant of [method@Gio.Socket.receive] which returns a +[struct@GLib.Bytes] rather than a plain buffer. + +Pass `-1` to @timeout_us to block indefinitely until data is received (or +the connection is closed, or there is an error). Pass `0` to use the default +timeout from [property@Gio.Socket:timeout], or pass a positive number to wait +for that many microseconds for data before returning `G_IO_ERROR_TIMED_OUT`. + + + a bytes buffer containing the + received bytes, or `NULL` on error + + + + + a #GSocket + + + + the number of bytes you want to read from the socket + + + + the timeout to wait for, in microseconds, or `-1` to block + indefinitely + + + + a %GCancellable, or `NULL` + + + + + + Receive data (up to @size bytes) from a socket. + +This function is a variant of [method@Gio.Socket.receive_from] which returns +a [struct@GLib.Bytes] rather than a plain buffer. + +If @address is non-%NULL then @address will be set equal to the +source address of the received packet. + +The @address is owned by the caller. + +Pass `-1` to @timeout_us to block indefinitely until data is received (or +the connection is closed, or there is an error). Pass `0` to use the default +timeout from [property@Gio.Socket:timeout], or pass a positive number to wait +for that many microseconds for data before returning `G_IO_ERROR_TIMED_OUT`. + + + a bytes buffer containing the + received bytes, or `NULL` on error + + + + + a #GSocket + + + + return location for a #GSocketAddress + + + + the number of bytes you want to read from the socket + + the timeout to wait for, in microseconds, or `-1` to block + indefinitely + + a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3555">a #GCancellable, or `NULL` @@ -104151,27 +108518,27 @@ the peer, or -1 on error version="2.22" throws="1"> Receive data (up to @size bytes) from a socket. + filename="gio/gsocket.c" + line="3627">Receive data (up to @size bytes) from a socket. If @address is non-%NULL then @address will be set equal to the source address of the received packet. @address is owned by the caller. See g_socket_receive() for additional information. - + Number of bytes read, or 0 if the connection was closed by + filename="gio/gsocket.c" + line="3646">Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket + filename="gio/gsocket.c" + line="3629">a #GSocket optional="1" allow-none="1"> a pointer to a #GSocketAddress + filename="gio/gsocket.c" + line="3630">a pointer to a #GSocketAddress pointer, or %NULL @@ -104191,8 +108558,8 @@ the peer, or -1 on error caller-allocates="1" transfer-ownership="none"> + filename="gio/gsocket.c" + line="3632"> a buffer to read data into (which should be at least @size bytes long). @@ -104200,8 +108567,8 @@ the peer, or -1 on error the number of bytes you want to read from the socket + filename="gio/gsocket.c" + line="3634">the number of bytes you want to read from the socket nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3635">a %GCancellable or %NULL @@ -104220,8 +108587,8 @@ the peer, or -1 on error version="2.22" throws="1"> Receive data from a socket. For receiving multiple messages, see + filename="gio/gsocket.c" + line="6159">Receive data from a socket. For receiving multiple messages, see g_socket_receive_messages(); for easier use, see g_socket_receive() and g_socket_receive_from(). @@ -104280,19 +108647,19 @@ returned. To be notified when data is available, wait for the %G_IO_IN condition. On error -1 is returned and @error is set accordingly. - + Number of bytes read, or 0 if the connection was closed by + filename="gio/gsocket.c" + line="6236">Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket + filename="gio/gsocket.c" + line="6161">a #GSocket optional="1" allow-none="1"> a pointer to a #GSocketAddress + filename="gio/gsocket.c" + line="6162">a pointer to a #GSocketAddress pointer, or %NULL an array of #GInputVector structs + filename="gio/gsocket.c" + line="6164">an array of #GInputVector structs the number of elements in @vectors, or -1 + filename="gio/gsocket.c" + line="6165">the number of elements in @vectors, or -1 optional="1" allow-none="1"> a pointer + filename="gio/gsocket.c" + line="6166">a pointer which may be filled with an array of #GSocketControlMessages, or %NULL caller-allocates="0" transfer-ownership="full"> a pointer which will be filled with the number of + filename="gio/gsocket.c" + line="6168">a pointer which will be filled with the number of elements in @messages, or %NULL @@ -104354,8 +108721,8 @@ the peer, or -1 on error caller-allocates="0" transfer-ownership="full"> a pointer to an int containing #GSocketMsgFlags flags, + filename="gio/gsocket.c" + line="6170">a pointer to an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) @@ -104365,8 +108732,8 @@ the peer, or -1 on error nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="6173">a %GCancellable or %NULL @@ -104376,8 +108743,8 @@ the peer, or -1 on error version="2.48" throws="1"> Receive multiple data messages from @socket in one go. This is the most + filename="gio/gsocket.c" + line="5880">Receive multiple data messages from @socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message(). @@ -104425,11 +108792,11 @@ g_socket_receive_messages() will return 0 (with no error set). On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. - + number of messages received, or -1 on error. Note that the number + filename="gio/gsocket.c" + line="5940">number of messages received, or -1 on error. Note that the number of messages received may be smaller than @num_messages if in non-blocking mode, if the peer closed the connection, or if @num_messages was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try @@ -104439,28 +108806,28 @@ messages successfully received before the error will be returned. a #GSocket + filename="gio/gsocket.c" + line="5882">a #GSocket an array of #GInputMessage structs + filename="gio/gsocket.c" + line="5883">an array of #GInputMessage structs the number of elements in @messages + filename="gio/gsocket.c" + line="5884">the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation, + filename="gio/gsocket.c" + line="5885">an int containing #GSocketMsgFlags flags for the overall operation, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) @@ -104470,8 +108837,8 @@ messages successfully received before the error will be returned. nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="5888">a %GCancellable or %NULL @@ -104481,23 +108848,23 @@ messages successfully received before the error will be returned. version="2.26" throws="1"> This behaves exactly the same as g_socket_receive(), except that + filename="gio/gsocket.c" + line="3517">This behaves exactly the same as g_socket_receive(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties. - + Number of bytes read, or 0 if the connection was closed by + filename="gio/gsocket.c" + line="3531">Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error a #GSocket + filename="gio/gsocket.c" + line="3519">a #GSocket caller-allocates="1" transfer-ownership="none"> + filename="gio/gsocket.c" + line="3520"> a buffer to read data into (which should be at least @size bytes long). @@ -104514,14 +108881,14 @@ the peer, or -1 on error the number of bytes you want to read from the socket + filename="gio/gsocket.c" + line="3522">the number of bytes you want to read from the socket whether to do blocking or non-blocking I/O + filename="gio/gsocket.c" + line="3523">whether to do blocking or non-blocking I/O nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3524">a %GCancellable or %NULL @@ -104540,8 +108907,8 @@ the peer, or -1 on error version="2.22" throws="1"> Tries to send @size bytes from @buffer on the socket. This is + filename="gio/gsocket.c" + line="3740">Tries to send @size bytes from @buffer on the socket. This is mainly used by connection-oriented sockets; it is identical to g_socket_send_to() with @address set to %NULL. @@ -104555,25 +108922,25 @@ notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and @error is set accordingly. - + Number of bytes written (which may be less than @size), or -1 + filename="gio/gsocket.c" + line="3764">Number of bytes written (which may be less than @size), or -1 on error a #GSocket + filename="gio/gsocket.c" + line="3742">a #GSocket the buffer + filename="gio/gsocket.c" + line="3743">the buffer containing the data to send. @@ -104581,8 +108948,8 @@ on error the number of bytes to send + filename="gio/gsocket.c" + line="3745">the number of bytes to send nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3746">a %GCancellable or %NULL @@ -104601,8 +108968,8 @@ on error version="2.22" throws="1"> Send data to @address on @socket. For sending multiple messages see + filename="gio/gsocket.c" + line="4997">Send data to @address on @socket. For sending multiple messages see g_socket_send_messages(); for easier use, see g_socket_send() and g_socket_send_to(). @@ -104644,19 +109011,19 @@ then it is mandatory to use the g_socket_send_message_with_timeout() function. On error -1 is returned and @error is set accordingly. - + Number of bytes written (which may be less than @size), or -1 + filename="gio/gsocket.c" + line="5054">Number of bytes written (which may be less than @size), or -1 on error a #GSocket + filename="gio/gsocket.c" + line="4999">a #GSocket nullable="1" allow-none="1"> a #GSocketAddress, or %NULL + filename="gio/gsocket.c" + line="5000">a #GSocketAddress, or %NULL an array of #GOutputVector structs + filename="gio/gsocket.c" + line="5001">an array of #GOutputVector structs the number of elements in @vectors, or -1 + filename="gio/gsocket.c" + line="5002">the number of elements in @vectors, or -1 nullable="1" allow-none="1"> a pointer to an + filename="gio/gsocket.c" + line="5003">a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @messages, or -1. + filename="gio/gsocket.c" + line="5005">number of elements in @messages, or -1. an int containing #GSocketMsgFlags flags, which may additionally + filename="gio/gsocket.c" + line="5006">an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) @@ -104715,8 +109082,8 @@ on error nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="5008">a %GCancellable or %NULL @@ -104726,19 +109093,19 @@ on error version="2.60" throws="1"> This behaves exactly the same as g_socket_send_message(), except that + filename="gio/gsocket.c" + line="5137">This behaves exactly the same as g_socket_send_message(), except that the choice of timeout behavior is determined by the @timeout_us argument rather than by @socket's properties. On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is returned. @bytes_written will contain 0 in both cases. - + %G_POLLABLE_RETURN_OK if all data was successfully written, + filename="gio/gsocket.c" + line="5161">%G_POLLABLE_RETURN_OK if all data was successfully written, %G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or %G_POLLABLE_RETURN_FAILED if an error happened and @error is set. @@ -104746,8 +109113,8 @@ returned. @bytes_written will contain 0 in both cases. a #GSocket + filename="gio/gsocket.c" + line="5139">a #GSocket nullable="1" allow-none="1"> a #GSocketAddress, or %NULL + filename="gio/gsocket.c" + line="5140">a #GSocketAddress, or %NULL an array of #GOutputVector structs + filename="gio/gsocket.c" + line="5141">an array of #GOutputVector structs @@ -104771,8 +109138,8 @@ returned. @bytes_written will contain 0 in both cases. the number of elements in @vectors, or -1 + filename="gio/gsocket.c" + line="5142">the number of elements in @vectors, or -1 nullable="1" allow-none="1"> a pointer to an + filename="gio/gsocket.c" + line="5143">a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @messages, or -1. + filename="gio/gsocket.c" + line="5145">number of elements in @messages, or -1. an int containing #GSocketMsgFlags flags, which may additionally + filename="gio/gsocket.c" + line="5146">an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) the maximum time (in microseconds) to wait, or -1 + filename="gio/gsocket.c" + line="5148">the maximum time (in microseconds) to wait, or -1 optional="1" allow-none="1"> location to store the number of bytes that were written to the socket + filename="gio/gsocket.c" + line="5149">location to store the number of bytes that were written to the socket nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="5150">a %GCancellable or %NULL @@ -104836,8 +109203,8 @@ returned. @bytes_written will contain 0 in both cases. version="2.44" throws="1"> Send multiple data messages from @socket in one go. This is the most + filename="gio/gsocket.c" + line="5375">Send multiple data messages from @socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_send(), g_socket_send_to(), and g_socket_send_message(). @@ -104871,11 +109238,11 @@ very common due to the way the underlying APIs work.) On error -1 is returned and @error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. - + number of messages sent, or -1 on error. Note that the number of + filename="gio/gsocket.c" + line="5420">number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than @num_messages if the socket is non-blocking or if @num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages. @@ -104884,28 +109251,28 @@ successfully sent before the error will be returned. a #GSocket + filename="gio/gsocket.c" + line="5377">a #GSocket an array of #GOutputMessage structs + filename="gio/gsocket.c" + line="5378">an array of #GOutputMessage structs the number of elements in @messages + filename="gio/gsocket.c" + line="5379">the number of elements in @messages an int containing #GSocketMsgFlags flags, which may additionally + filename="gio/gsocket.c" + line="5380">an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) @@ -104914,8 +109281,8 @@ successfully sent before the error will be returned. nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="5382">a %GCancellable or %NULL @@ -104925,25 +109292,25 @@ successfully sent before the error will be returned. version="2.22" throws="1"> Tries to send @size bytes from @buffer to @address. If @address is + filename="gio/gsocket.c" + line="3812">Tries to send @size bytes from @buffer to @address. If @address is %NULL then the message is sent to the default receiver (set by g_socket_connect()). See g_socket_send() for additional information. - + Number of bytes written (which may be less than @size), or -1 + filename="gio/gsocket.c" + line="3828">Number of bytes written (which may be less than @size), or -1 on error a #GSocket + filename="gio/gsocket.c" + line="3814">a #GSocket nullable="1" allow-none="1"> a #GSocketAddress, or %NULL + filename="gio/gsocket.c" + line="3815">a #GSocketAddress, or %NULL the buffer + filename="gio/gsocket.c" + line="3816">the buffer containing the data to send. @@ -104966,8 +109333,8 @@ on error the number of bytes to send + filename="gio/gsocket.c" + line="3818">the number of bytes to send nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3819">a %GCancellable or %NULL @@ -104986,29 +109353,29 @@ on error version="2.26" throws="1"> This behaves exactly the same as g_socket_send(), except that + filename="gio/gsocket.c" + line="3781">This behaves exactly the same as g_socket_send(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties. - + Number of bytes written (which may be less than @size), or -1 + filename="gio/gsocket.c" + line="3795">Number of bytes written (which may be less than @size), or -1 on error a #GSocket + filename="gio/gsocket.c" + line="3783">a #GSocket the buffer + filename="gio/gsocket.c" + line="3784">the buffer containing the data to send. @@ -105016,14 +109383,14 @@ on error the number of bytes to send + filename="gio/gsocket.c" + line="3786">the number of bytes to send whether to do blocking or non-blocking I/O + filename="gio/gsocket.c" + line="3787">whether to do blocking or non-blocking I/O nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocket.c" + line="3788">a %GCancellable or %NULL @@ -105042,8 +109409,8 @@ on error glib:set-property="blocking" version="2.22"> Sets the blocking mode of the socket. In blocking mode + filename="gio/gsocket.c" + line="1411">Sets the blocking mode of the socket. In blocking mode all operations (which don’t take an explicit blocking parameter) block until they succeed or there is an error. In non-blocking mode all functions return results immediately or @@ -105052,21 +109419,21 @@ with a %G_IO_ERROR_WOULD_BLOCK error. All sockets are created in blocking mode. However, note that the platform level socket is always non-blocking, and blocking mode is a GSocket level feature. - + a #GSocket. + filename="gio/gsocket.c" + line="1413">a #GSocket. Whether to use blocking I/O or not. + filename="gio/gsocket.c" + line="1414">Whether to use blocking I/O or not. @@ -105076,24 +109443,24 @@ is a GSocket level feature. glib:set-property="broadcast" version="2.32"> Sets whether @socket should allow sending to broadcast addresses. + filename="gio/gsocket.c" + line="1752">Sets whether @socket should allow sending to broadcast addresses. This is %FALSE by default. - + a #GSocket. + filename="gio/gsocket.c" + line="1754">a #GSocket. whether @socket should allow sending to broadcast + filename="gio/gsocket.c" + line="1755">whether @socket should allow sending to broadcast addresses @@ -105104,8 +109471,8 @@ This is %FALSE by default. glib:set-property="keepalive" version="2.22"> Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When + filename="gio/gsocket.c" + line="1462">Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When this flag is set on a socket, the system will attempt to verify that the remote socket endpoint is still present if a sufficiently long period of time passes with no data being exchanged. If the system is unable to @@ -105120,21 +109487,21 @@ normally be at least two hours. Most commonly, you would set this flag on a server socket if you want to allow clients to remain idle for long periods of time, but also want to ensure that connections are eventually garbage-collected if clients crash or become unreachable. - + a #GSocket. + filename="gio/gsocket.c" + line="1464">a #GSocket. Value for the keepalive flag + filename="gio/gsocket.c" + line="1465">Value for the keepalive flag @@ -105144,29 +109511,29 @@ garbage-collected if clients crash or become unreachable. glib:set-property="listen-backlog" version="2.22"> Sets the maximum number of outstanding connections allowed + filename="gio/gsocket.c" + line="1547">Sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them on time then the new connections will be refused. Note that this must be called before g_socket_listen() and has no effect if called after that. - + a #GSocket. + filename="gio/gsocket.c" + line="1549">a #GSocket. the maximum number of pending connections. + filename="gio/gsocket.c" + line="1550">the maximum number of pending connections. @@ -105176,25 +109543,25 @@ effect if called after that. glib:set-property="multicast-loopback" version="2.32"> Sets whether outgoing multicast packets will be received by sockets + filename="gio/gsocket.c" + line="1827">Sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host. This is %TRUE by default. - + a #GSocket. + filename="gio/gsocket.c" + line="1829">a #GSocket. whether @socket should receive messages sent to its + filename="gio/gsocket.c" + line="1830">whether @socket should receive messages sent to its multicast groups from the local host @@ -105205,25 +109572,25 @@ by default. glib:set-property="multicast-ttl" version="2.32"> Sets the time-to-live for outgoing multicast datagrams on @socket. + filename="gio/gsocket.c" + line="1916">Sets the time-to-live for outgoing multicast datagrams on @socket. By default, this is 1, meaning that multicast packets will not leave the local network. - + a #GSocket. + filename="gio/gsocket.c" + line="1918">a #GSocket. the time-to-live value for all multicast datagrams on @socket + filename="gio/gsocket.c" + line="1919">the time-to-live value for all multicast datagrams on @socket @@ -105233,21 +109600,21 @@ the local network. version="2.36" throws="1"> Sets the value of an integer-valued option on @socket, as with + filename="gio/gsocket.c" + line="6525">Sets the value of an integer-valued option on @socket, as with setsockopt(). (If you need to set a non-integer-valued option, you will need to call setsockopt() directly.) -The [<gio/gnetworking.h>][gio-gnetworking.h] +The [`<gio/gnetworking.h>`](networking.html) header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. - + success or failure. On failure, @error will be set, and + filename="gio/gsocket.c" + line="6543">success or failure. On failure, @error will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the setsockopt() call. @@ -105255,26 +109622,26 @@ headers. a #GSocket + filename="gio/gsocket.c" + line="6527">a #GSocket the "API level" of the option (eg, `SOL_SOCKET`) + filename="gio/gsocket.c" + line="6528">the "API level" of the option (eg, `SOL_SOCKET`) the "name" of the option (eg, `SO_BROADCAST`) + filename="gio/gsocket.c" + line="6529">the "name" of the option (eg, `SO_BROADCAST`) the value to set the option to + filename="gio/gsocket.c" + line="6530">the value to set the option to @@ -105284,8 +109651,8 @@ headers. glib:set-property="timeout" version="2.26"> Sets the time in seconds after which I/O operations on @socket will + filename="gio/gsocket.c" + line="1595">Sets the time in seconds after which I/O operations on @socket will time out if they have not yet completed. On a blocking socket, this means that any blocking #GSocket @@ -105305,21 +109672,21 @@ on their own. Note that if an I/O operation is interrupted by a signal, this may cause the timeout to be reset. - + a #GSocket. + filename="gio/gsocket.c" + line="1597">a #GSocket. the timeout for @socket, in seconds, or 0 for none + filename="gio/gsocket.c" + line="1598">the timeout for @socket, in seconds, or 0 for none @@ -105329,24 +109696,24 @@ cause the timeout to be reset. glib:set-property="ttl" version="2.32"> Sets the time-to-live for outgoing unicast packets on @socket. + filename="gio/gsocket.c" + line="1678">Sets the time-to-live for outgoing unicast packets on @socket. By default the platform-specific default value is used. - + a #GSocket. + filename="gio/gsocket.c" + line="1680">a #GSocket. the time-to-live value for all unicast packets on @socket + filename="gio/gsocket.c" + line="1681">the time-to-live value for all unicast packets on @socket @@ -105356,8 +109723,8 @@ By default the platform-specific default value is used. version="2.22" throws="1"> Shut down part or all of a full-duplex connection. + filename="gio/gsocket.c" + line="3855">Shut down part or all of a full-duplex connection. If @shutdown_read is %TRUE then the receiving side of the connection is shut down, and further reading is disallowed. @@ -105371,30 +109738,30 @@ One example where it is useful to shut down only one side of a connection is graceful disconnect for TCP connections where you close the sending side, then wait for the other side to close the connection, thus ensuring that the other side saw all sent data. - + %TRUE on success, %FALSE on error + filename="gio/gsocket.c" + line="3877">%TRUE on success, %FALSE on error a #GSocket + filename="gio/gsocket.c" + line="3857">a #GSocket whether to shut down the read side + filename="gio/gsocket.c" + line="3858">whether to shut down the read side whether to shut down the write side + filename="gio/gsocket.c" + line="3859">whether to shut down the write side @@ -105403,8 +109770,8 @@ other side saw all sent data. c:identifier="g_socket_speaks_ipv4" version="2.22"> Checks if a socket is capable of speaking IPv4. + filename="gio/gsocket.c" + line="2889">Checks if a socket is capable of speaking IPv4. IPv4 sockets are capable of speaking IPv4. On some operating systems and under some combinations of circumstances IPv6 sockets are also @@ -105413,28 +109780,32 @@ information. No other types of sockets are currently considered as being capable of speaking IPv4. - + %TRUE if this socket can be used with IPv4. + filename="gio/gsocket.c" + line="2903">%TRUE if this socket can be used with IPv4. a #GSocket + filename="gio/gsocket.c" + line="2891">a #GSocket + Whether I/O on this socket is blocking. getter="get_broadcast" default-value="FALSE"> Whether the socket should allow sending to broadcast addresses. + filename="gio/gsocket.c" + line="1118">Whether the socket should allow sending to broadcast addresses. + The socket’s address family. + The socket’s file descriptor. + Whether to keep the connection alive by sending periodic pings. + The number of outstanding connections in the listen queue. + The local address the socket is bound to. getter="get_multicast_loopback" default-value="TRUE"> Whether outgoing multicast packets loop back to the local host. + filename="gio/gsocket.c" + line="1144">Whether outgoing multicast packets loop back to the local host. getter="get_multicast_ttl" default-value="1"> Time-to-live out outgoing multicast packets + filename="gio/gsocket.c" + line="1157">Time-to-live out outgoing multicast packets + The ID of the protocol to use, or `-1` for unknown. + The remote address the socket is connected to. getter="get_timeout" default-value="0"> The timeout in seconds on socket I/O + filename="gio/gsocket.c" + line="1103">The timeout in seconds on socket I/O getter="get_ttl" default-value="0"> Time-to-live for outgoing unicast packets + filename="gio/gsocket.c" + line="1131">Time-to-live for outgoing unicast packets + The socket’s type. @@ -105570,58 +109973,59 @@ of speaking IPv4. glib:get-type="g_socket_address_get_type" glib:type-struct="SocketAddressClass"> #GSocketAddress is the equivalent of struct sockaddr in the BSD -sockets API. This is an abstract class; use #GInetSocketAddress -for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. - + filename="gio/gsocketaddress.c" + line="47">`GSocketAddress` is the equivalent of +[`struct sockaddr`](man:sockaddr(3type)) and its subtypes in the BSD sockets +API. This is an abstract class; use [class@Gio.InetSocketAddress] for +internet sockets, or [class@Gio.UnixSocketAddress] for UNIX domain sockets. + Creates a #GSocketAddress subclass corresponding to the native + filename="gio/gsocketaddress.c" + line="193">Creates a #GSocketAddress subclass corresponding to the native struct sockaddr @native. - + a new #GSocketAddress if @native could successfully + filename="gio/gsocketaddress.c" + line="201">a new #GSocketAddress if @native could successfully be converted, otherwise %NULL a pointer to a struct sockaddr + filename="gio/gsocketaddress.c" + line="195">a pointer to a struct sockaddr the size of the memory location pointed to by @native + filename="gio/gsocketaddress.c" + line="196">the size of the memory location pointed to by @native Gets the socket family type of @address. - + filename="gio/gsocketaddress.c" + line="70">Gets the socket family type of @address. + the socket family type of @address + filename="gio/gsocketaddress.c" + line="76">the socket family type of @address a #GSocketAddress + filename="gio/gsocketaddress.c" + line="72">a #GSocketAddress @@ -105630,23 +110034,23 @@ struct sockaddr @native. invoker="get_native_size" version="2.22"> Gets the size of @address's native struct sockaddr. + filename="gio/gsocketaddress.c" + line="141">Gets the size of @address's native struct sockaddr. You can use this to allocate memory to pass to g_socket_address_to_native(). - + the size of the native struct sockaddr that + filename="gio/gsocketaddress.c" + line="149">the size of the native struct sockaddr that @address represents a #GSocketAddress + filename="gio/gsocketaddress.c" + line="143">a #GSocketAddress @@ -105656,25 +110060,25 @@ g_socket_address_to_native(). version="2.22" throws="1"> Converts a #GSocketAddress to a native struct sockaddr, which can + filename="gio/gsocketaddress.c" + line="162">Converts a #GSocketAddress to a native struct sockaddr, which can be passed to low-level functions like connect() or bind(). If not enough space is available, a %G_IO_ERROR_NO_SPACE error is returned. If the address type is not known on the system then a %G_IO_ERROR_NOT_SUPPORTED error is returned. - + %TRUE if @dest was filled in, %FALSE on error + filename="gio/gsocketaddress.c" + line="178">%TRUE if @dest was filled in, %FALSE on error a #GSocketAddress + filename="gio/gsocketaddress.c" + line="164">a #GSocketAddress nullable="1" allow-none="1"> a pointer to a memory location that will contain the native + filename="gio/gsocketaddress.c" + line="165">a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as + filename="gio/gsocketaddress.c" + line="167">the size of @dest. Must be at least as large as g_socket_address_get_native_size() @@ -105701,20 +110105,20 @@ struct sockaddr glib:get-property="family" version="2.22"> Gets the socket family type of @address. - + filename="gio/gsocketaddress.c" + line="70">Gets the socket family type of @address. + the socket family type of @address + filename="gio/gsocketaddress.c" + line="76">the socket family type of @address a #GSocketAddress + filename="gio/gsocketaddress.c" + line="72">a #GSocketAddress @@ -105723,23 +110127,23 @@ struct sockaddr c:identifier="g_socket_address_get_native_size" version="2.22"> Gets the size of @address's native struct sockaddr. + filename="gio/gsocketaddress.c" + line="141">Gets the size of @address's native struct sockaddr. You can use this to allocate memory to pass to g_socket_address_to_native(). - + the size of the native struct sockaddr that + filename="gio/gsocketaddress.c" + line="149">the size of the native struct sockaddr that @address represents a #GSocketAddress + filename="gio/gsocketaddress.c" + line="143">a #GSocketAddress @@ -105749,25 +110153,25 @@ g_socket_address_to_native(). version="2.22" throws="1"> Converts a #GSocketAddress to a native struct sockaddr, which can + filename="gio/gsocketaddress.c" + line="162">Converts a #GSocketAddress to a native struct sockaddr, which can be passed to low-level functions like connect() or bind(). If not enough space is available, a %G_IO_ERROR_NO_SPACE error is returned. If the address type is not known on the system then a %G_IO_ERROR_NOT_SUPPORTED error is returned. - + %TRUE if @dest was filled in, %FALSE on error + filename="gio/gsocketaddress.c" + line="178">%TRUE if @dest was filled in, %FALSE on error a #GSocketAddress + filename="gio/gsocketaddress.c" + line="164">a #GSocketAddress nullable="1" allow-none="1"> a pointer to a memory location that will contain the native + filename="gio/gsocketaddress.c" + line="165">a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as + filename="gio/gsocketaddress.c" + line="167">the size of @dest. Must be at least as large as g_socket_address_get_native_size() + The family of the socket address. @@ -105802,24 +110210,24 @@ struct sockaddr - + - + the socket family type of @address + filename="gio/gsocketaddress.c" + line="76">the socket family type of @address a #GSocketAddress + filename="gio/gsocketaddress.c" + line="72">a #GSocketAddress @@ -105827,19 +110235,19 @@ struct sockaddr - + the size of the native struct sockaddr that + filename="gio/gsocketaddress.c" + line="149">the size of the native struct sockaddr that @address represents a #GSocketAddress + filename="gio/gsocketaddress.c" + line="143">a #GSocketAddress @@ -105847,18 +110255,18 @@ struct sockaddr - + %TRUE if @dest was filled in, %FALSE on error + filename="gio/gsocketaddress.c" + line="178">%TRUE if @dest was filled in, %FALSE on error a #GSocketAddress + filename="gio/gsocketaddress.c" + line="164">a #GSocketAddress nullable="1" allow-none="1"> a pointer to a memory location that will contain the native + filename="gio/gsocketaddress.c" + line="165">a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as + filename="gio/gsocketaddress.c" + line="167">the size of @dest. Must be at least as large as g_socket_address_get_native_size() @@ -105891,26 +110299,30 @@ struct sockaddr glib:get-type="g_socket_address_enumerator_get_type" glib:type-struct="SocketAddressEnumeratorClass"> #GSocketAddressEnumerator is an enumerator type for #GSocketAddress -instances. It is returned by enumeration functions such as -g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator -to list each #GSocketAddress which could be used to connect to that -#GSocketConnectable. + filename="gio/gsocketaddressenumerator.c" + line="27">`GSocketAddressEnumerator` is an enumerator type for +[class@Gio.SocketAddress] instances. It is returned by enumeration functions +such as [method@Gio.SocketConnectable.enumerate], which returns a +`GSocketAddressEnumerator` to list each [class@Gio.SocketAddress] which could +be used to connect to that [iface@Gio.SocketConnectable]. Enumeration is typically a blocking operation, so the asynchronous methods -g_socket_address_enumerator_next_async() and -g_socket_address_enumerator_next_finish() should be used where possible. +[method@Gio.SocketAddressEnumerator.next_async] and +[method@Gio.SocketAddressEnumerator.next_finish] should be used where +possible. -Each #GSocketAddressEnumerator can only be enumerated once. Once -g_socket_address_enumerator_next() has returned %NULL, further -enumeration with that #GSocketAddressEnumerator is not possible, and it can +Each `GSocketAddressEnumerator` can only be enumerated once. Once +[method@Gio.SocketAddressEnumerator.next] has returned `NULL`, further +enumeration with that `GSocketAddressEnumerator` is not possible, and it can be unreffed. - - - Retrieves the next #GSocketAddress from @enumerator. Note that this + + + Retrieves the next #GSocketAddress from @enumerator. Note that this may block for some amount of time. (Eg, a #GNetworkAddress may need to do a DNS lookup before it can return an address.) Use g_socket_address_enumerator_next_async() if you need to avoid @@ -105919,24 +110331,24 @@ blocking. If @enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to g_socket_address_enumerator_next() will return an appropriate error -in *@error. However, if the first call to +in `*error`. However, if the first call to g_socket_address_enumerator_next() succeeds, then any further internal errors (other than @cancellable being triggered) will be ignored. - + a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no + filename="gio/gsocketaddressenumerator.c" + line="89">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="71">a #GSocketAddressEnumerator @@ -105945,29 +110357,32 @@ ignored. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketaddressenumerator.c" + line="72">optional #GCancellable object, %NULL to ignore. - + Asynchronously retrieves the next #GSocketAddress from @enumerator + filename="gio/gsocketaddressenumerator.c" + line="133">Asynchronously retrieves the next #GSocketAddress from @enumerator and then calls @callback, which must call g_socket_address_enumerator_next_finish() to get the result. It is an error to call this multiple times before the previous callback has finished. - + a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="135">a #GSocketAddressEnumerator @@ -105976,8 +110391,8 @@ It is an error to call this multiple times before the previous callback has fini nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketaddressenumerator.c" + line="136">optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call + filename="gio/gsocketaddressenumerator.c" + line="137">a #GAsyncReadyCallback to call when the request is satisfied @@ -105998,50 +110413,51 @@ It is an error to call this multiple times before the previous callback has fini allow-none="1" closure="2"> the data to pass to callback function + filename="gio/gsocketaddressenumerator.c" + line="139">the data to pass to callback function Retrieves the result of a completed call to + filename="gio/gsocketaddressenumerator.c" + line="172">Retrieves the result of a completed call to g_socket_address_enumerator_next_async(). See g_socket_address_enumerator_next() for more information about error handling. - + a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no + filename="gio/gsocketaddressenumerator.c" + line="183">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="174">a #GSocketAddressEnumerator a #GAsyncResult + filename="gio/gsocketaddressenumerator.c" + line="175">a #GAsyncResult + throws="1" + glib:async-func="next_async"> Retrieves the next #GSocketAddress from @enumerator. Note that this + filename="gio/gsocketaddressenumerator.c" + line="69">Retrieves the next #GSocketAddress from @enumerator. Note that this may block for some amount of time. (Eg, a #GNetworkAddress may need to do a DNS lookup before it can return an address.) Use g_socket_address_enumerator_next_async() if you need to avoid @@ -106050,24 +110466,24 @@ blocking. If @enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to g_socket_address_enumerator_next() will return an appropriate error -in *@error. However, if the first call to +in `*error`. However, if the first call to g_socket_address_enumerator_next() succeeds, then any further internal errors (other than @cancellable being triggered) will be ignored. - + a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no + filename="gio/gsocketaddressenumerator.c" + line="89">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="71">a #GSocketAddressEnumerator @@ -106076,30 +110492,32 @@ ignored. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketaddressenumerator.c" + line="72">optional #GCancellable object, %NULL to ignore. + c:identifier="g_socket_address_enumerator_next_async" + glib:finish-func="next_finish" + glib:sync-func="next"> Asynchronously retrieves the next #GSocketAddress from @enumerator + filename="gio/gsocketaddressenumerator.c" + line="133">Asynchronously retrieves the next #GSocketAddress from @enumerator and then calls @callback, which must call g_socket_address_enumerator_next_finish() to get the result. It is an error to call this multiple times before the previous callback has finished. - + a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="135">a #GSocketAddressEnumerator @@ -106108,8 +110526,8 @@ It is an error to call this multiple times before the previous callback has fini nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketaddressenumerator.c" + line="136">optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call + filename="gio/gsocketaddressenumerator.c" + line="137">a #GAsyncReadyCallback to call when the request is satisfied @@ -106129,8 +110547,8 @@ It is an error to call this multiple times before the previous callback has fini nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gsocketaddressenumerator.c" + line="139">the data to pass to callback function @@ -106139,32 +110557,32 @@ It is an error to call this multiple times before the previous callback has fini c:identifier="g_socket_address_enumerator_next_finish" throws="1"> Retrieves the result of a completed call to + filename="gio/gsocketaddressenumerator.c" + line="172">Retrieves the result of a completed call to g_socket_address_enumerator_next_async(). See g_socket_address_enumerator_next() for more information about error handling. - + a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no + filename="gio/gsocketaddressenumerator.c" + line="183">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="174">a #GSocketAddressEnumerator a #GAsyncResult + filename="gio/gsocketaddressenumerator.c" + line="175">a #GAsyncResult @@ -106177,28 +110595,32 @@ error handling. c:type="GSocketAddressEnumeratorClass" glib:is-gtype-struct-for="SocketAddressEnumerator"> Class structure for #GSocketAddressEnumerator. - + filename="gio/gsocketaddressenumerator.h" + line="47">Class structure for #GSocketAddressEnumerator. + + Virtual method for g_socket_address_enumerator_next(). - + a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no + filename="gio/gsocketaddressenumerator.c" + line="89">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="71">a #GSocketAddressEnumerator @@ -106207,24 +110629,28 @@ error handling. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketaddressenumerator.c" + line="72">optional #GCancellable object, %NULL to ignore. + Virtual method for g_socket_address_enumerator_next_async(). - + a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="135">a #GSocketAddressEnumerator @@ -106233,8 +110659,8 @@ error handling. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketaddressenumerator.c" + line="136">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback to call + filename="gio/gsocketaddressenumerator.c" + line="137">a #GAsyncReadyCallback to call when the request is satisfied @@ -106255,36 +110681,40 @@ error handling. allow-none="1" closure="3"> the data to pass to callback function + filename="gio/gsocketaddressenumerator.c" + line="139">the data to pass to callback function + Virtual method for g_socket_address_enumerator_next_finish(). - + a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no + filename="gio/gsocketaddressenumerator.c" + line="183">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case `*error` will be set) or if there are no more addresses. a #GSocketAddressEnumerator + filename="gio/gsocketaddressenumerator.c" + line="174">a #GSocketAddressEnumerator a #GAsyncResult + filename="gio/gsocketaddressenumerator.c" + line="175">a #GAsyncResult @@ -106294,13 +110724,13 @@ error handling. - + - + @@ -106308,7 +110738,7 @@ error handling. - + @@ -106316,7 +110746,7 @@ error handling. - + @@ -106324,7 +110754,7 @@ error handling. - + @@ -106332,7 +110762,7 @@ error handling. - + @@ -106340,7 +110770,7 @@ error handling. - + @@ -106348,7 +110778,7 @@ error handling. - + @@ -106356,7 +110786,7 @@ error handling. - + @@ -106364,7 +110794,7 @@ error handling. - + @@ -106372,7 +110802,7 @@ error handling. - + @@ -106388,38 +110818,38 @@ error handling. glib:get-type="g_socket_client_get_type" glib:type-struct="SocketClientClass"> #GSocketClient is a lightweight high-level utility class for connecting to + filename="gio/gsocketclient.c" + line="68">`GSocketClient` is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type. -You create a #GSocketClient object, set any options you want, and then -call a sync or async connect operation, which returns a #GSocketConnection -subclass on success. +You create a `GSocketClient` object, set any options you want, and then +call a sync or async connect operation, which returns a +[class@Gio.SocketConnection] subclass on success. -The type of the #GSocketConnection object returned depends on the type of -the underlying socket that is in use. For instance, for a TCP/IP connection -it will be a #GTcpConnection. +The type of the [class@Gio.SocketConnection] object returned depends on the +type of the underlying socket that is in use. For instance, for a TCP/IP +connection it will be a [class@Gio.TcpConnection]. -As #GSocketClient is a lightweight object, you don't need to cache it. You +As `GSocketClient` is a lightweight object, you don't need to cache it. You can just create a new one any time you need one. - + Creates a new #GSocketClient with the default options. - + filename="gio/gsocketclient.c" + line="225">Creates a new #GSocketClient with the default options. + a #GSocketClient. + filename="gio/gsocketclient.c" + line="230">a #GSocketClient. Free the returned object with g_object_unref(). - + @@ -106441,8 +110871,8 @@ can just create a new one any time you need one. Enable proxy protocols to be handled by the application. When the + filename="gio/gsocketclient.c" + line="2435">Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the #GProxyResolver, #GSocketClient will consider this protocol as supported but will not try to find a #GProxy instance to handle handshaking. The @@ -106461,21 +110891,21 @@ be use as generic socket proxy through the HTTP CONNECT method. When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake. - + a #GSocketClient + filename="gio/gsocketclient.c" + line="2437">a #GSocketClient The proxy protocol + filename="gio/gsocketclient.c" + line="2438">The proxy protocol @@ -106483,10 +110913,11 @@ specific handshake. + throws="1" + glib:async-func="connect_async"> Tries to resolve the @connectable and make a network connection to it. + filename="gio/gsocketclient.c" + line="1094">Tries to resolve the @connectable and make a network connection to it. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their @@ -106504,24 +110935,24 @@ g_socket_client_set_socket_type(). If a local address is specified with g_socket_client_set_local_address() the socket will be bound to this address before connecting. - + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="1120">a #GSocketConnection on success, %NULL on error. a #GSocketClient. + filename="gio/gsocketclient.c" + line="1096">a #GSocketClient. a #GSocketConnectable specifying the remote address. + filename="gio/gsocketclient.c" + line="1097">a #GSocketConnectable specifying the remote address. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketclient.c" + line="1098">optional #GCancellable object, %NULL to ignore. + version="2.22" + glib:finish-func="connect_finish" + glib:sync-func="connect"> This is the asynchronous version of g_socket_client_connect(). + filename="gio/gsocketclient.c" + line="2117">This is the asynchronous version of g_socket_client_connect(). You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements @@ -106554,21 +110987,21 @@ the future.) When the operation is finished @callback will be called. You can then call g_socket_client_connect_finish() to get the result of the operation. - + a #GSocketClient + filename="gio/gsocketclient.c" + line="2119">a #GSocketClient a #GSocketConnectable specifying the remote address. + filename="gio/gsocketclient.c" + line="2120">a #GSocketConnectable specifying the remote address. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="2121">a #GCancellable, or %NULL scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gsocketclient.c" + line="2122">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketclient.c" + line="2123">user data for the callback @@ -106607,26 +111040,26 @@ the result of the operation. version="2.22" throws="1"> Finishes an async connect operation. See g_socket_client_connect_async() - + filename="gio/gsocketclient.c" + line="2349">Finishes an async connect operation. See g_socket_client_connect_async() + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="2358">a #GSocketConnection on success, %NULL on error. a #GSocketClient. + filename="gio/gsocketclient.c" + line="2351">a #GSocketClient. a #GAsyncResult. + filename="gio/gsocketclient.c" + line="2352">a #GAsyncResult. @@ -106634,10 +111067,11 @@ the result of the operation. + throws="1" + glib:async-func="connect_to_host_async"> This is a helper function for g_socket_client_connect(). + filename="gio/gsocketclient.c" + line="1329">This is a helper function for g_socket_client_connect(). Attempts to create a TCP connection to the named host. @@ -106667,30 +111101,30 @@ reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. - + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="1368">a #GSocketConnection on success, %NULL on error. a #GSocketClient + filename="gio/gsocketclient.c" + line="1331">a #GSocketClient the name and optionally port of the host to connect to + filename="gio/gsocketclient.c" + line="1332">the name and optionally port of the host to connect to the default port to connect to + filename="gio/gsocketclient.c" + line="1333">the default port to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="1334">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="connect_to_host_finish" + glib:sync-func="connect_to_host"> This is the asynchronous version of g_socket_client_connect_to_host(). + filename="gio/gsocketclient.c" + line="2225">This is the asynchronous version of g_socket_client_connect_to_host(). When the operation is finished @callback will be called. You can then call g_socket_client_connect_to_host_finish() to get the result of the operation. - + a #GSocketClient + filename="gio/gsocketclient.c" + line="2227">a #GSocketClient the name and optionally the port of the host to connect to + filename="gio/gsocketclient.c" + line="2228">the name and optionally the port of the host to connect to the default port to connect to + filename="gio/gsocketclient.c" + line="2229">the default port to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="2230">a #GCancellable, or %NULL scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gsocketclient.c" + line="2231">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketclient.c" + line="2232">user data for the callback @@ -106773,36 +111209,37 @@ the result of the operation. version="2.22" throws="1"> Finishes an async connect operation. See g_socket_client_connect_to_host_async() - + filename="gio/gsocketclient.c" + line="2372">Finishes an async connect operation. See g_socket_client_connect_to_host_async() + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="2381">a #GSocketConnection on success, %NULL on error. a #GSocketClient. + filename="gio/gsocketclient.c" + line="2374">a #GSocketClient. a #GAsyncResult. + filename="gio/gsocketclient.c" + line="2375">a #GAsyncResult. + throws="1" + glib:async-func="connect_to_service_async"> Attempts to create a TCP connection to a service. + filename="gio/gsocketclient.c" + line="1393">Attempts to create a TCP connection to a service. This call looks up the SRV record for @service at @domain for the "tcp" protocol. It then attempts to connect, in turn, to each of @@ -106816,30 +111253,30 @@ reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. - + a #GSocketConnection if successful, or %NULL on error + filename="gio/gsocketclient.c" + line="1416">a #GSocketConnection if successful, or %NULL on error a #GSocketConnection + filename="gio/gsocketclient.c" + line="1395">a #GSocketConnection a domain name + filename="gio/gsocketclient.c" + line="1396">a domain name the name of the service to connect to + filename="gio/gsocketclient.c" + line="1397">the name of the service to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="1398">a #GCancellable, or %NULL + version="2.22" + glib:finish-func="connect_to_service_finish" + glib:sync-func="connect_to_service"> This is the asynchronous version of + filename="gio/gsocketclient.c" + line="2271">This is the asynchronous version of g_socket_client_connect_to_service(). - + a #GSocketClient + filename="gio/gsocketclient.c" + line="2273">a #GSocketClient a domain name + filename="gio/gsocketclient.c" + line="2274">a domain name the name of the service to connect to + filename="gio/gsocketclient.c" + line="2275">the name of the service to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="2276">a #GCancellable, or %NULL scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gsocketclient.c" + line="2277">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketclient.c" + line="2278">user data for the callback @@ -106919,26 +111358,26 @@ g_socket_client_connect_to_service(). version="2.22" throws="1"> Finishes an async connect operation. See g_socket_client_connect_to_service_async() - + filename="gio/gsocketclient.c" + line="2393">Finishes an async connect operation. See g_socket_client_connect_to_service_async() + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="2402">a #GSocketConnection on success, %NULL on error. a #GSocketClient. + filename="gio/gsocketclient.c" + line="2395">a #GSocketClient. a #GAsyncResult. + filename="gio/gsocketclient.c" + line="2396">a #GAsyncResult. @@ -106946,10 +111385,11 @@ g_socket_client_connect_to_service(). + throws="1" + glib:async-func="connect_to_uri_async"> This is a helper function for g_socket_client_connect(). + filename="gio/gsocketclient.c" + line="1436">This is a helper function for g_socket_client_connect(). Attempts to create a TCP connection with a network URI. @@ -106970,30 +111410,30 @@ reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. - + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="1466">a #GSocketConnection on success, %NULL on error. a #GSocketClient + filename="gio/gsocketclient.c" + line="1438">a #GSocketClient A network URI + filename="gio/gsocketclient.c" + line="1439">A network URI the default port to connect to + filename="gio/gsocketclient.c" + line="1440">the default port to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="1441">a #GCancellable, or %NULL + version="2.26" + glib:finish-func="connect_to_uri_finish" + glib:sync-func="connect_to_uri"> This is the asynchronous version of g_socket_client_connect_to_uri(). + filename="gio/gsocketclient.c" + line="2302">This is the asynchronous version of g_socket_client_connect_to_uri(). When the operation is finished @callback will be called. You can then call g_socket_client_connect_to_uri_finish() to get the result of the operation. - + a #GSocketClient + filename="gio/gsocketclient.c" + line="2304">a #GSocketClient a network uri + filename="gio/gsocketclient.c" + line="2305">a network uri the default port to connect to + filename="gio/gsocketclient.c" + line="2306">the default port to connect to nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketclient.c" + line="2307">a #GCancellable, or %NULL scope="async" closure="4"> a #GAsyncReadyCallback + filename="gio/gsocketclient.c" + line="2308">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketclient.c" + line="2309">user data for the callback @@ -107076,26 +111518,26 @@ the result of the operation. version="2.26" throws="1"> Finishes an async connect operation. See g_socket_client_connect_to_uri_async() - + filename="gio/gsocketclient.c" + line="2414">Finishes an async connect operation. See g_socket_client_connect_to_uri_async() + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketclient.c" + line="2423">a #GSocketConnection on success, %NULL on error. a #GSocketClient. + filename="gio/gsocketclient.c" + line="2416">a #GSocketClient. a #GAsyncResult. + filename="gio/gsocketclient.c" + line="2417">a #GAsyncResult. @@ -107105,20 +111547,20 @@ the result of the operation. glib:get-property="enable-proxy" version="2.26"> Gets the proxy enable state; see g_socket_client_set_enable_proxy() - + filename="gio/gsocketclient.c" + line="583">Gets the proxy enable state; see g_socket_client_set_enable_proxy() + whether proxying is enabled + filename="gio/gsocketclient.c" + line="589">whether proxying is enabled a #GSocketClient. + filename="gio/gsocketclient.c" + line="585">a #GSocketClient. @@ -107128,22 +111570,22 @@ the result of the operation. glib:get-property="family" version="2.22"> Gets the socket family of the socket client. + filename="gio/gsocketclient.c" + line="360">Gets the socket family of the socket client. See g_socket_client_set_family() for details. - + a #GSocketFamily + filename="gio/gsocketclient.c" + line="368">a #GSocketFamily a #GSocketClient. + filename="gio/gsocketclient.c" + line="362">a #GSocketClient. @@ -107153,22 +111595,22 @@ See g_socket_client_set_family() for details. glib:get-property="local-address" version="2.22"> Gets the local address of the socket client. + filename="gio/gsocketclient.c" + line="491">Gets the local address of the socket client. See g_socket_client_set_local_address() for details. - + a #GSocketAddress or %NULL. Do not free. + filename="gio/gsocketclient.c" + line="499">a #GSocketAddress or %NULL. Do not free. a #GSocketClient. + filename="gio/gsocketclient.c" + line="493">a #GSocketClient. @@ -107178,22 +111620,22 @@ See g_socket_client_set_local_address() for details. glib:get-property="protocol" version="2.22"> Gets the protocol name type of the socket client. + filename="gio/gsocketclient.c" + line="448">Gets the protocol name type of the socket client. See g_socket_client_set_protocol() for details. - + a #GSocketProtocol + filename="gio/gsocketclient.c" + line="456">a #GSocketProtocol a #GSocketClient + filename="gio/gsocketclient.c" + line="450">a #GSocketClient @@ -107203,23 +111645,23 @@ See g_socket_client_set_protocol() for details. glib:get-property="proxy-resolver" version="2.36"> Gets the #GProxyResolver being used by @client. Normally, this will + filename="gio/gsocketclient.c" + line="730">Gets the #GProxyResolver being used by @client. Normally, this will be the resolver returned by g_proxy_resolver_get_default(), but you can override it with g_socket_client_set_proxy_resolver(). - + The #GProxyResolver being used by + filename="gio/gsocketclient.c" + line="738">The #GProxyResolver being used by @client. a #GSocketClient. + filename="gio/gsocketclient.c" + line="732">a #GSocketClient. @@ -107228,22 +111670,22 @@ can override it with g_socket_client_set_proxy_resolver(). c:identifier="g_socket_client_get_socket_type" version="2.22"> Gets the socket type of the socket client. + filename="gio/gsocketclient.c" + line="405">Gets the socket type of the socket client. See g_socket_client_set_socket_type() for details. - + a #GSocketFamily + filename="gio/gsocketclient.c" + line="413">a #GSocketFamily a #GSocketClient. + filename="gio/gsocketclient.c" + line="407">a #GSocketClient. @@ -107253,22 +111695,22 @@ See g_socket_client_set_socket_type() for details. glib:get-property="timeout" version="2.26"> Gets the I/O timeout time for sockets created by @client. + filename="gio/gsocketclient.c" + line="539">Gets the I/O timeout time for sockets created by @client. See g_socket_client_set_timeout() for details. - + the timeout in seconds + filename="gio/gsocketclient.c" + line="547">the timeout in seconds a #GSocketClient + filename="gio/gsocketclient.c" + line="541">a #GSocketClient @@ -107278,21 +111720,21 @@ See g_socket_client_set_timeout() for details. glib:get-property="tls" version="2.28"> Gets whether @client creates TLS connections. See + filename="gio/gsocketclient.c" + line="625">Gets whether @client creates TLS connections. See g_socket_client_set_tls() for details. - + whether @client uses TLS + filename="gio/gsocketclient.c" + line="632">whether @client uses TLS a #GSocketClient. + filename="gio/gsocketclient.c" + line="627">a #GSocketClient. @@ -107304,26 +111746,26 @@ g_socket_client_set_tls() for details. deprecated="1" deprecated-version="2.72"> Gets the TLS validation flags used creating TLS connections via + filename="gio/gsocketclient.c" + line="680">Gets the TLS validation flags used creating TLS connections via @client. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information. Do not attempt to ignore validation errors. - + the TLS validation flags + filename="gio/gsocketclient.c" + line="691">the TLS validation flags a #GSocketClient. + filename="gio/gsocketclient.c" + line="682">a #GSocketClient. @@ -107333,28 +111775,28 @@ information. glib:set-property="enable-proxy" version="2.26"> Sets whether or not @client attempts to make connections via a + filename="gio/gsocketclient.c" + line="599">Sets whether or not @client attempts to make connections via a proxy server. When enabled (the default), #GSocketClient will use a #GProxyResolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation. See also g_socket_client_set_proxy_resolver(). - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="601">a #GSocketClient. whether to enable proxies + filename="gio/gsocketclient.c" + line="602">whether to enable proxies @@ -107364,8 +111806,8 @@ See also g_socket_client_set_proxy_resolver(). glib:set-property="family" version="2.22"> Sets the socket family of the socket client. + filename="gio/gsocketclient.c" + line="378">Sets the socket family of the socket client. If this is set to something other than %G_SOCKET_FAMILY_INVALID then the sockets created by this object will be of the specified family. @@ -107373,21 +111815,21 @@ family. This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="380">a #GSocketClient. a #GSocketFamily + filename="gio/gsocketclient.c" + line="381">a #GSocketFamily @@ -107397,23 +111839,23 @@ be an ipv6 mapped to ipv4 address. glib:set-property="local-address" version="2.22"> Sets the local address of the socket client. + filename="gio/gsocketclient.c" + line="509">Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not %NULL) before connecting. This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="511">a #GSocketClient. nullable="1" allow-none="1"> a #GSocketAddress, or %NULL + filename="gio/gsocketclient.c" + line="512">a #GSocketAddress, or %NULL @@ -107432,28 +111874,28 @@ a specific interface. glib:set-property="protocol" version="2.22"> Sets the protocol of the socket client. + filename="gio/gsocketclient.c" + line="466">Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default protocol for the socket family and type. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="468">a #GSocketClient. a #GSocketProtocol + filename="gio/gsocketclient.c" + line="469">a #GSocketProtocol @@ -107463,23 +111905,23 @@ protocol for the socket family and type. glib:set-property="proxy-resolver" version="2.36"> Overrides the #GProxyResolver used by @client. You can call this if + filename="gio/gsocketclient.c" + line="752">Overrides the #GProxyResolver used by @client. You can call this if you want to use specific proxies, rather than using the system default proxy settings. Note that whether or not the proxy resolver is actually used depends on the setting of #GSocketClient:enable-proxy, which is not changed by this function (but which is %TRUE by default) - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="754">a #GSocketClient. nullable="1" allow-none="1"> a #GProxyResolver, or %NULL for the + filename="gio/gsocketclient.c" + line="755">a #GProxyResolver, or %NULL for the default. @@ -107498,28 +111940,28 @@ changed by this function (but which is %TRUE by default) c:identifier="g_socket_client_set_socket_type" version="2.22"> Sets the socket type of the socket client. + filename="gio/gsocketclient.c" + line="423">Sets the socket type of the socket client. The sockets created by this object will be of the specified type. It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, as GSocketClient is used for connection oriented services. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="425">a #GSocketClient. a #GSocketType + filename="gio/gsocketclient.c" + line="426">a #GSocketType @@ -107529,28 +111971,28 @@ as GSocketClient is used for connection oriented services. glib:set-property="timeout" version="2.26"> Sets the I/O timeout for sockets created by @client. @timeout is a + filename="gio/gsocketclient.c" + line="558">Sets the I/O timeout for sockets created by @client. @timeout is a time in seconds, or 0 for no timeout (the default). The timeout value affects the initial connection attempt as well, so setting this may cause calls to g_socket_client_connect(), etc, to fail with %G_IO_ERROR_TIMED_OUT. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="560">a #GSocketClient. the timeout + filename="gio/gsocketclient.c" + line="561">the timeout @@ -107560,8 +112002,8 @@ to fail with %G_IO_ERROR_TIMED_OUT. glib:set-property="tls" version="2.28"> Sets whether @client creates TLS (aka SSL) connections. If @tls is + filename="gio/gsocketclient.c" + line="642">Sets whether @client creates TLS (aka SSL) connections. If @tls is %TRUE, @client will wrap its connections in a #GTlsClientConnection and perform a TLS handshake when connecting. @@ -107579,21 +112021,21 @@ setting a client-side certificate to use, or connecting to the emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you a chance to see the #GTlsClientConnection before the handshake starts. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="644">a #GSocketClient. whether to use TLS + filename="gio/gsocketclient.c" + line="645">whether to use TLS @@ -107605,66 +112047,82 @@ starts. deprecated="1" deprecated-version="2.72"> Sets the TLS validation flags used when creating TLS connections + filename="gio/gsocketclient.c" + line="703">Sets the TLS validation flags used when creating TLS connections via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information. Do not attempt to ignore validation errors. - + a #GSocketClient. + filename="gio/gsocketclient.c" + line="705">a #GSocketClient. the validation flags + filename="gio/gsocketclient.c" + line="706">the validation flags + Enable proxy support. + The address family to use for socket construction. + The local address constructed sockets will be bound to. + The protocol to use for socket construction, or `0` for default. setter="set_proxy_resolver" getter="get_proxy_resolver"> The proxy resolver to use + filename="gio/gsocketclient.c" + line="1003">The proxy resolver to use + The I/O timeout for sockets, in seconds, or `0` for none. + Whether to create TLS connections. getter="get_tls_validation_flags" default-value="G_TLS_CERTIFICATE_UNKNOWN_CA | G_TLS_CERTIFICATE_BAD_IDENTITY | G_TLS_CERTIFICATE_NOT_ACTIVATED | G_TLS_CERTIFICATE_EXPIRED | G_TLS_CERTIFICATE_REVOKED | G_TLS_CERTIFICATE_INSECURE | G_TLS_CERTIFICATE_GENERIC_ERROR"> The TLS validation flags used when creating TLS connections. The + filename="gio/gsocketclient.c" + line="972">The TLS validation flags used when creating TLS connections. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. GLib guarantees that if certificate verification fails, at least one @@ -107728,10 +112194,14 @@ connect to #GTlsConnection::accept-certificate. + The type to use for socket construction. @@ -107742,8 +112212,8 @@ connect to #GTlsConnection::accept-certificate. Emitted when @client's activity on @connectable changes state. + filename="gio/gsocketclient.c" + line="797">Emitted when @client's activity on @connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different @event values are as follows: @@ -107798,14 +112268,14 @@ the future; unrecognized @event values should be ignored. the event that is occurring + filename="gio/gsocketclient.c" + line="800">the event that is occurring the #GSocketConnectable that @event is occurring on + filename="gio/gsocketclient.c" + line="801">the #GSocketConnectable that @event is occurring on nullable="1" allow-none="1"> the current representation of the connection + filename="gio/gsocketclient.c" + line="802">the current representation of the connection @@ -107823,13 +112293,13 @@ the future; unrecognized @event values should be ignored. - + - + @@ -107851,7 +112321,7 @@ the future; unrecognized @event values should be ignored. - + @@ -107859,7 +112329,7 @@ the future; unrecognized @event values should be ignored. - + @@ -107867,7 +112337,7 @@ the future; unrecognized @event values should be ignored. - + @@ -107875,7 +112345,7 @@ the future; unrecognized @event values should be ignored. - + @@ -107888,8 +112358,8 @@ the future; unrecognized @event values should be ignored. glib:get-type="g_socket_client_event_get_type" c:type="GSocketClientEvent"> Describes an event occurring on a #GSocketClient. See the + filename="gio/gioenums.h" + line="1933">Describes an event occurring on a #GSocketClient. See the #GSocketClient::event signal for more details. Additional values may be added to this type in the future. @@ -107899,8 +112369,8 @@ Additional values may be added to this type in the future. glib:nick="resolving" glib:name="G_SOCKET_CLIENT_RESOLVING"> The client is doing a DNS lookup. + filename="gio/gioenums.h" + line="1935">The client is doing a DNS lookup. glib:nick="resolved" glib:name="G_SOCKET_CLIENT_RESOLVED"> The client has completed a DNS lookup. + filename="gio/gioenums.h" + line="1936">The client has completed a DNS lookup. glib:nick="connecting" glib:name="G_SOCKET_CLIENT_CONNECTING"> The client is connecting to a remote + filename="gio/gioenums.h" + line="1937">The client is connecting to a remote host (either a proxy or the destination server). glib:nick="connected" glib:name="G_SOCKET_CLIENT_CONNECTED"> The client has connected to a remote + filename="gio/gioenums.h" + line="1939">The client has connected to a remote host. glib:nick="proxy-negotiating" glib:name="G_SOCKET_CLIENT_PROXY_NEGOTIATING"> The client is negotiating + filename="gio/gioenums.h" + line="1941">The client is negotiating with a proxy to connect to the destination server. glib:nick="proxy-negotiated" glib:name="G_SOCKET_CLIENT_PROXY_NEGOTIATED"> The client has negotiated + filename="gio/gioenums.h" + line="1943">The client has negotiated with the proxy server. glib:nick="tls-handshaking" glib:name="G_SOCKET_CLIENT_TLS_HANDSHAKING"> The client is performing a + filename="gio/gioenums.h" + line="1945">The client is performing a TLS handshake. glib:nick="tls-handshaked" glib:name="G_SOCKET_CLIENT_TLS_HANDSHAKED"> The client has performed a + filename="gio/gioenums.h" + line="1947">The client has performed a TLS handshake. glib:nick="complete" glib:name="G_SOCKET_CLIENT_COMPLETE"> The client is done with a particular + filename="gio/gioenums.h" + line="1949">The client is done with a particular #GSocketConnectable. @@ -107986,7 +112456,7 @@ Additional values may be added to this type in the future. c:type="GSocketClientPrivate" disguised="1" opaque="1"> - + glib:get-type="g_socket_connectable_get_type" glib:type-struct="SocketConnectableIface"> Objects that describe one or more potential socket endpoints -implement #GSocketConnectable. Callers can then use -g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator -to try out each socket address in turn until one succeeds, as shown -in the sample code below. + filename="gio/gsocketconnectable.c" + line="26">Objects that describe one or more potential socket endpoints +implement `GSocketConnectable`. Callers can then use +[method@Gio.SocketConnectable.enumerate] to get a +[class@Gio.SocketAddressEnumerator] to try out each socket address in turn +until one succeeds, as shown in the sample code below. -|[<!-- language="C" --> +```c MyConnectionType * connect_to_host (const char *hostname, guint16 port, @@ -108052,25 +112522,25 @@ connect_to_host (const char *hostname, return NULL; } } -]| - +``` + Creates a #GSocketAddressEnumerator for @connectable. - + filename="gio/gsocketconnectable.c" + line="97">Creates a #GSocketAddressEnumerator for @connectable. + a new #GSocketAddressEnumerator. + filename="gio/gsocketconnectable.c" + line="103">a new #GSocketAddressEnumerator. a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="99">a #GSocketConnectable @@ -108079,53 +112549,53 @@ connect_to_host (const char *hostname, invoker="proxy_enumerate" version="2.26"> Creates a #GSocketAddressEnumerator for @connectable that will + filename="gio/gsocketconnectable.c" + line="119">Creates a #GSocketAddressEnumerator for @connectable that will return a #GProxyAddress for each of its addresses that you must connect to via a proxy. If @connectable does not implement g_socket_connectable_proxy_enumerate(), this will fall back to calling g_socket_connectable_enumerate(). - + a new #GSocketAddressEnumerator. + filename="gio/gsocketconnectable.c" + line="131">a new #GSocketAddressEnumerator. a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="121">a #GSocketConnectable Format a #GSocketConnectable as a string. This is a human-readable format for + filename="gio/gsocketconnectable.c" + line="150">Format a #GSocketConnectable as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user. If the #GSocketConnectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback. - + the formatted string + filename="gio/gsocketconnectable.c" + line="162">the formatted string a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="152">a #GSocketConnectable @@ -108134,21 +112604,21 @@ the implementation’s type name will be returned as a fallback. c:identifier="g_socket_connectable_enumerate" version="2.22"> Creates a #GSocketAddressEnumerator for @connectable. - + filename="gio/gsocketconnectable.c" + line="97">Creates a #GSocketAddressEnumerator for @connectable. + a new #GSocketAddressEnumerator. + filename="gio/gsocketconnectable.c" + line="103">a new #GSocketAddressEnumerator. a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="99">a #GSocketConnectable @@ -108157,27 +112627,27 @@ the implementation’s type name will be returned as a fallback. c:identifier="g_socket_connectable_proxy_enumerate" version="2.26"> Creates a #GSocketAddressEnumerator for @connectable that will + filename="gio/gsocketconnectable.c" + line="119">Creates a #GSocketAddressEnumerator for @connectable that will return a #GProxyAddress for each of its addresses that you must connect to via a proxy. If @connectable does not implement g_socket_connectable_proxy_enumerate(), this will fall back to calling g_socket_connectable_enumerate(). - + a new #GSocketAddressEnumerator. + filename="gio/gsocketconnectable.c" + line="131">a new #GSocketAddressEnumerator. a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="121">a #GSocketConnectable @@ -108186,26 +112656,26 @@ calling g_socket_connectable_enumerate(). c:identifier="g_socket_connectable_to_string" version="2.48"> Format a #GSocketConnectable as a string. This is a human-readable format for + filename="gio/gsocketconnectable.c" + line="150">Format a #GSocketConnectable as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user. If the #GSocketConnectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback. - + the formatted string + filename="gio/gsocketconnectable.c" + line="162">the formatted string a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="152">a #GSocketConnectable @@ -108215,70 +112685,80 @@ the implementation’s type name will be returned as a fallback. c:type="GSocketConnectableIface" glib:is-gtype-struct-for="SocketConnectable"> Provides an interface for returning a #GSocketAddressEnumerator + filename="gio/gsocketconnectable.h" + line="39">Provides an interface for returning a #GSocketAddressEnumerator and #GProxyAddressEnumerator - + The parent interface. + filename="gio/gsocketconnectable.h" + line="41">The parent interface. + Creates a #GSocketAddressEnumerator - + a new #GSocketAddressEnumerator. + filename="gio/gsocketconnectable.c" + line="103">a new #GSocketAddressEnumerator. a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="99">a #GSocketConnectable + Creates a #GProxyAddressEnumerator - + a new #GSocketAddressEnumerator. + filename="gio/gsocketconnectable.c" + line="131">a new #GSocketAddressEnumerator. a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="121">a #GSocketConnectable + Format the connectable’s address as a string for debugging. + Implementing this is optional. (Since: 2.48) - + the formatted string + filename="gio/gsocketconnectable.c" + line="162">the formatted string a #GSocketConnectable + filename="gio/gsocketconnectable.c" + line="152">a #GSocketConnectable @@ -108294,57 +112774,57 @@ and #GProxyAddressEnumerator glib:get-type="g_socket_connection_get_type" glib:type-struct="SocketConnectionClass"> #GSocketConnection is a #GIOStream for a connected socket. They -can be created either by #GSocketClient when connecting to a host, -or by #GSocketListener when accepting a new client. + filename="gio/gsocketconnection.c" + line="42">`GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They +can be created either by [class@Gio.SocketClient] when connecting to a host, +or by [class@Gio.SocketListener] when accepting a new client. -The type of the #GSocketConnection object returned from these calls +The type of the `GSocketConnection` object returned from these calls depends on the type of the underlying socket that is in use. For -instance, for a TCP/IP connection it will be a #GTcpConnection. +instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection]. Choosing what type of object to construct is done with the socket -connection factory, and it is possible for 3rd parties to register +connection factory, and it is possible for third parties to register custom socket connection types for specific combination of socket -family/type/protocol using g_socket_connection_factory_register_type(). +family/type/protocol using [func@Gio.SocketConnection.factory_register_type]. -To close a #GSocketConnection, use g_io_stream_close(). Closing both -substreams of the #GIOStream separately will not close the underlying -#GSocket. - +To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both +substreams of the [class@Gio.IOStream] separately will not close the +underlying [class@Gio.Socket]. + Looks up the #GType to be used when creating socket connections on + filename="gio/gsocketconnection.c" + line="630">Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol_id. If no type is registered, the #GSocketConnection base type is returned. - + a #GType + filename="gio/gsocketconnection.c" + line="641">a #GType a #GSocketFamily + filename="gio/gsocketconnection.c" + line="632">a #GSocketFamily a #GSocketType + filename="gio/gsocketconnection.c" + line="633">a #GSocketType a protocol id + filename="gio/gsocketconnection.c" + line="634">a protocol id @@ -108353,38 +112833,38 @@ If no type is registered, the #GSocketConnection base type is returned. c:identifier="g_socket_connection_factory_register_type" version="2.22"> Looks up the #GType to be used when creating socket connections on + filename="gio/gsocketconnection.c" + line="579">Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol. If no type is registered, the #GSocketConnection base type is returned. - + a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION + filename="gio/gsocketconnection.c" + line="581">a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION a #GSocketFamily + filename="gio/gsocketconnection.c" + line="582">a #GSocketFamily a #GSocketType + filename="gio/gsocketconnection.c" + line="583">a #GSocketType a protocol id + filename="gio/gsocketconnection.c" + line="584">a protocol id @@ -108392,28 +112872,29 @@ If no type is registered, the #GSocketConnection base type is returned. + throws="1" + glib:async-func="connect_async"> Connect @connection to the specified remote address. - + filename="gio/gsocketconnection.c" + line="137">Connect @connection to the specified remote address. + %TRUE if the connection succeeded, %FALSE on error + filename="gio/gsocketconnection.c" + line="146">%TRUE if the connection succeeded, %FALSE on error a #GSocketConnection + filename="gio/gsocketconnection.c" + line="139">a #GSocketConnection a #GSocketAddress specifying the remote address. + filename="gio/gsocketconnection.c" + line="140">a #GSocketAddress specifying the remote address. nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocketconnection.c" + line="141">a %GCancellable or %NULL + version="2.32" + glib:finish-func="connect_finish" + glib:sync-func="connect"> Asynchronously connect @connection to the specified remote address. + filename="gio/gsocketconnection.c" + line="167">Asynchronously connect @connection to the specified remote address. This clears the #GSocket:blocking flag on @connection's underlying socket if it is currently set. +If #GSocket:timeout is set, the operation will time out and return +%G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue +indefinitely until operating system timeouts (if any) are hit. + Use g_socket_connection_connect_finish() to retrieve the result. - + a #GSocketConnection + filename="gio/gsocketconnection.c" + line="169">a #GSocketConnection a #GSocketAddress specifying the remote address. + filename="gio/gsocketconnection.c" + line="170">a #GSocketAddress specifying the remote address. nullable="1" allow-none="1"> a %GCancellable or %NULL + filename="gio/gsocketconnection.c" + line="171">a %GCancellable or %NULL scope="async" closure="3"> a #GAsyncReadyCallback + filename="gio/gsocketconnection.c" + line="172">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketconnection.c" + line="173">user data for the callback @@ -108491,26 +112978,26 @@ Use g_socket_connection_connect_finish() to retrieve the result. version="2.32" throws="1"> Gets the result of a g_socket_connection_connect_async() call. - + filename="gio/gsocketconnection.c" + line="248">Gets the result of a g_socket_connection_connect_async() call. + %TRUE if the connection succeeded, %FALSE on error + filename="gio/gsocketconnection.c" + line="256">%TRUE if the connection succeeded, %FALSE on error a #GSocketConnection + filename="gio/gsocketconnection.c" + line="250">a #GSocketConnection the #GAsyncResult + filename="gio/gsocketconnection.c" + line="251">the #GAsyncResult @@ -108520,21 +113007,21 @@ Use g_socket_connection_connect_finish() to retrieve the result. version="2.22" throws="1"> Try to get the local address of a socket connection. - + filename="gio/gsocketconnection.c" + line="291">Try to get the local address of a socket connection. + a #GSocketAddress or %NULL on error. + filename="gio/gsocketconnection.c" + line="298">a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocketConnection + filename="gio/gsocketconnection.c" + line="293">a #GSocketConnection @@ -108544,8 +113031,8 @@ Use g_socket_connection_connect_finish() to retrieve the result. version="2.22" throws="1"> Try to get the remote address of a socket connection. + filename="gio/gsocketconnection.c" + line="310">Try to get the remote address of a socket connection. Since GLib 2.40, when used with g_socket_client_connect() or g_socket_client_connect_async(), during emission of @@ -108553,19 +113040,19 @@ g_socket_client_connect_async(), during emission of address that will be used for the connection. This allows applications to print e.g. "Connecting to example.com (10.42.77.3)...". - + a #GSocketAddress or %NULL on error. + filename="gio/gsocketconnection.c" + line="324">a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). a #GSocketConnection + filename="gio/gsocketconnection.c" + line="312">a #GSocketConnection @@ -108575,22 +113062,22 @@ applications to print e.g. "Connecting to example.com glib:get-property="socket" version="2.22"> Gets the underlying #GSocket object of the connection. + filename="gio/gsocketconnection.c" + line="271">Gets the underlying #GSocket object of the connection. This can be useful if you want to do something unusual on it not supported by the #GSocketConnection APIs. - + a #GSocket or %NULL on error. + filename="gio/gsocketconnection.c" + line="279">a #GSocket or %NULL on error. a #GSocketConnection + filename="gio/gsocketconnection.c" + line="273">a #GSocketConnection @@ -108599,30 +113086,34 @@ not supported by the #GSocketConnection APIs. c:identifier="g_socket_connection_is_connected" version="2.32"> Checks if @connection is connected. This is equivalent to calling + filename="gio/gsocketconnection.c" + line="120">Checks if @connection is connected. This is equivalent to calling g_socket_is_connected() on @connection's underlying #GSocket. - + whether @connection is connected + filename="gio/gsocketconnection.c" + line="127">whether @connection is connected a #GSocketConnection + filename="gio/gsocketconnection.c" + line="122">a #GSocketConnection + The underlying [class@Gio.Socket]. @@ -108636,13 +113127,13 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + - + @@ -108650,7 +113141,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + @@ -108658,7 +113149,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + @@ -108666,7 +113157,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + @@ -108674,7 +113165,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + @@ -108682,7 +113173,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + @@ -108693,7 +113184,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. c:type="GSocketConnectionPrivate" disguised="1" opaque="1"> - + glib:get-type="g_socket_control_message_get_type" glib:type-struct="SocketControlMessageClass"> A #GSocketControlMessage is a special-purpose utility message that -can be sent to or received from a #GSocket. These types of -messages are often called "ancillary data". + filename="gio/gsocketcontrolmessage.c" + line="17">A `GSocketControlMessage` is a special-purpose utility message that +can be sent to or received from a [class@Gio.Socket]. These types of +messages are often called ‘ancillary data’. The message can represent some sort of special instruction to or information from the socket or can represent a special kind of transfer to the peer (for example, sending a file descriptor over a UNIX socket). -These messages are sent with g_socket_send_message() and received -with g_socket_receive_message(). +These messages are sent with [method@Gio.Socket.send_message] and received +with [method@Gio.Socket.receive_message]. To extend the set of control message that can be sent, subclass this -class and override the get_size, get_level, get_type and serialize +class and override the `get_size`, `get_level`, `get_type` and `serialize` methods. To extend the set of control messages that can be received, subclass -this class and implement the deserialize method. Also, make sure your -class is registered with the GType typesystem before calling -g_socket_receive_message() to read such a message. - +this class and implement the `deserialize` method. Also, make sure your +class is registered with the [type@GObject.Type] type system before calling +[method@Gio.Socket.receive_message] to read such a message. + Tries to deserialize a socket control message of a given + filename="gio/gsocketcontrolmessage.c" + line="148">Tries to deserialize a socket control message of a given @level and @type. This will ask all known (to GType) subclasses of #GSocketControlMessage if they can understand this kind of message and if so deserialize it into a #GSocketControlMessage. If there is no implementation for this kind of control message, %NULL will be returned. - + the deserialized message or %NULL + filename="gio/gsocketcontrolmessage.c" + line="163">the deserialized message or %NULL a socket level + filename="gio/gsocketcontrolmessage.c" + line="150">a socket level a socket control message type for the given @level + filename="gio/gsocketcontrolmessage.c" + line="151">a socket control message type for the given @level the size of the data in bytes + filename="gio/gsocketcontrolmessage.c" + line="152">the size of the data in bytes pointer to the message data + filename="gio/gsocketcontrolmessage.c" + line="153">pointer to the message data @@ -108777,48 +113268,51 @@ will be returned. Returns the "level" (i.e. the originating protocol) of the control message. + filename="gio/gsocketcontrolmessage.c" + line="76">Returns the "level" (i.e. the originating protocol) of the control message. This is often SOL_SOCKET. - + an integer describing the level + filename="gio/gsocketcontrolmessage.c" + line="83">an integer describing the level a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="78">a #GSocketControlMessage Returns the space required for the control message, not including + filename="gio/gsocketcontrolmessage.c" + line="57">Returns the space required for the control message, not including headers or alignment. - + The number of bytes required. + filename="gio/gsocketcontrolmessage.c" + line="64">The number of bytes required. a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="59">a #GSocketControlMessage - + gets the protocol specific type of the message. + @@ -108830,28 +113324,28 @@ headers or alignment. Converts the data in the message to bytes placed in the + filename="gio/gsocketcontrolmessage.c" + line="114">Converts the data in the message to bytes placed in the message. @data is guaranteed to have enough space to fit the size returned by g_socket_control_message_get_size() on this object. - + a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="116">a #GSocketControlMessage A buffer to write data to + filename="gio/gsocketcontrolmessage.c" + line="117">A buffer to write data to @@ -108860,21 +113354,21 @@ object. c:identifier="g_socket_control_message_get_level" version="2.22"> Returns the "level" (i.e. the originating protocol) of the control message. + filename="gio/gsocketcontrolmessage.c" + line="76">Returns the "level" (i.e. the originating protocol) of the control message. This is often SOL_SOCKET. - + an integer describing the level + filename="gio/gsocketcontrolmessage.c" + line="83">an integer describing the level a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="78">a #GSocketControlMessage @@ -108883,21 +113377,21 @@ This is often SOL_SOCKET. c:identifier="g_socket_control_message_get_msg_type" version="2.22"> Returns the protocol specific type of the control message. + filename="gio/gsocketcontrolmessage.c" + line="95">Returns the protocol specific type of the control message. For instance, for UNIX fd passing this would be SCM_RIGHTS. - + an integer describing the type of control message + filename="gio/gsocketcontrolmessage.c" + line="102">an integer describing the type of control message a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="97">a #GSocketControlMessage @@ -108906,21 +113400,21 @@ For instance, for UNIX fd passing this would be SCM_RIGHTS. c:identifier="g_socket_control_message_get_size" version="2.22"> Returns the space required for the control message, not including + filename="gio/gsocketcontrolmessage.c" + line="57">Returns the space required for the control message, not including headers or alignment. - + The number of bytes required. + filename="gio/gsocketcontrolmessage.c" + line="64">The number of bytes required. a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="59">a #GSocketControlMessage @@ -108929,28 +113423,28 @@ headers or alignment. c:identifier="g_socket_control_message_serialize" version="2.22"> Converts the data in the message to bytes placed in the + filename="gio/gsocketcontrolmessage.c" + line="114">Converts the data in the message to bytes placed in the message. @data is guaranteed to have enough space to fit the size returned by g_socket_control_message_get_size() on this object. - + a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="116">a #GSocketControlMessage A buffer to write data to + filename="gio/gsocketcontrolmessage.c" + line="117">A buffer to write data to @@ -108967,26 +113461,29 @@ object. c:type="GSocketControlMessageClass" glib:is-gtype-struct-for="SocketControlMessage"> Class structure for #GSocketControlMessage. - + + gets the size of the message. - + The number of bytes required. + filename="gio/gsocketcontrolmessage.c" + line="64">The number of bytes required. a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="59">a #GSocketControlMessage @@ -108994,19 +113491,22 @@ object. + gets the protocol of the message. - + an integer describing the level + filename="gio/gsocketcontrolmessage.c" + line="83">an integer describing the level a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="78">a #GSocketControlMessage @@ -109014,8 +113514,11 @@ object. + gets the protocol specific type of the message. - + @@ -109028,31 +113531,37 @@ object. + Writes out the message data. - + a #GSocketControlMessage + filename="gio/gsocketcontrolmessage.c" + line="116">a #GSocketControlMessage A buffer to write data to + filename="gio/gsocketcontrolmessage.c" + line="117">A buffer to write data to + Tries to deserialize a message. - + @@ -109074,7 +113583,7 @@ object. - + @@ -109082,7 +113591,7 @@ object. - + @@ -109090,7 +113599,7 @@ object. - + @@ -109098,7 +113607,7 @@ object. - + @@ -109106,7 +113615,7 @@ object. - + @@ -109117,7 +113626,7 @@ object. c:type="GSocketControlMessagePrivate" disguised="1" opaque="1"> - + glib:get-type="g_socket_family_get_type" c:type="GSocketFamily"> The protocol family of a #GSocketAddress. (These values are + filename="gio/gioenums.h" + line="822">The protocol family of a #GSocketAddress. (These values are identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, if available.) glib:nick="invalid" glib:name="G_SOCKET_FAMILY_INVALID"> no address family + filename="gio/gioenums.h" + line="824">no address family glib:nick="unix" glib:name="G_SOCKET_FAMILY_UNIX"> the UNIX domain family + filename="gio/gioenums.h" + line="827">the UNIX domain family glib:nick="ipv4" glib:name="G_SOCKET_FAMILY_IPV4"> the IPv4 family + filename="gio/gioenums.h" + line="825">the IPv4 family glib:nick="ipv6" glib:name="G_SOCKET_FAMILY_IPV6"> the IPv6 family + filename="gio/gioenums.h" + line="826">the IPv6 family glib:get-type="g_socket_listener_get_type" glib:type-struct="SocketListenerClass"> A #GSocketListener is an object that keeps track of a set + filename="gio/gsocketlistener.c" + line="44">A `GSocketListener` is an object that keeps track of a set of server sockets and helps you accept sockets from any of the socket, either sync or async. -Add addresses and ports to listen on using g_socket_listener_add_address() -and g_socket_listener_add_inet_port(). These will be listened on until -g_socket_listener_close() is called. Dropping your final reference to the -#GSocketListener will not cause g_socket_listener_close() to be called -implicitly, as some references to the #GSocketListener may be held +Add addresses and ports to listen on using +[method@Gio.SocketListener.add_address] and +[method@Gio.SocketListener.add_inet_port]. These will be listened on until +[method@Gio.SocketListener.close] is called. Dropping your final reference to +the `GSocketListener` will not cause [method@Gio.SocketListener.close] to be +called implicitly, as some references to the `GSocketListener` may be held internally. -If you want to implement a network server, also look at #GSocketService -and #GThreadedSocketService which are subclasses of #GSocketListener -that make this even easier. - +If you want to implement a network server, also look at +[class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are +subclasses of `GSocketListener` that make this even easier. + Creates a new #GSocketListener with no sockets to listen for. + filename="gio/gsocketlistener.c" + line="211">Creates a new #GSocketListener with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port(). - + a new #GSocketListener. + filename="gio/gsocketlistener.c" + line="218">a new #GSocketListener. - + virtual method called when the set of socket listened to changes + @@ -109219,7 +113732,7 @@ or g_socket_listener_add_inet_port(). - + @@ -109238,10 +113751,11 @@ or g_socket_listener_add_inet_port(). + throws="1" + glib:async-func="accept_async"> Blocks waiting for a client to connect to any of the sockets added + filename="gio/gsocketlistener.c" + line="741">Blocks waiting for a client to connect to any of the sockets added to the listener. Returns a #GSocketConnection for the socket that was accepted. @@ -109252,18 +113766,18 @@ to the listener. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketlistener.c" + line="760">a #GSocketConnection on success, %NULL on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="743">a #GSocketListener optional="1" allow-none="1"> location where #GObject pointer will be stored, or %NULL + filename="gio/gsocketlistener.c" + line="744">location where #GObject pointer will be stored, or %NULL nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketlistener.c" + line="745">optional #GCancellable object, %NULL to ignore. + version="2.22" + glib:finish-func="accept_finish" + glib:sync-func="accept"> This is the asynchronous version of g_socket_listener_accept(). + filename="gio/gsocketlistener.c" + line="911">This is the asynchronous version of g_socket_listener_accept(). When the operation is finished @callback will be called. You can then call g_socket_listener_accept_finish() to get the result of the operation. - + a #GSocketListener + filename="gio/gsocketlistener.c" + line="913">a #GSocketListener nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketlistener.c" + line="914">a #GCancellable, or %NULL scope="async" closure="2"> a #GAsyncReadyCallback + filename="gio/gsocketlistener.c" + line="915">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketlistener.c" + line="916">user data for the callback @@ -109346,26 +113862,26 @@ to get the result of the operation. version="2.22" throws="1"> Finishes an async accept operation. See g_socket_listener_accept_async() - + filename="gio/gsocketlistener.c" + line="938">Finishes an async accept operation. See g_socket_listener_accept_async() + a #GSocketConnection on success, %NULL on error. + filename="gio/gsocketlistener.c" + line="948">a #GSocketConnection on success, %NULL on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="940">a #GSocketListener a #GAsyncResult. + filename="gio/gsocketlistener.c" + line="941">a #GAsyncResult. optional="1" allow-none="1"> Optional #GObject identifying this source + filename="gio/gsocketlistener.c" + line="942">Optional #GObject identifying this source @@ -109385,10 +113901,11 @@ to get the result of the operation. + throws="1" + glib:async-func="accept_socket_async"> Blocks waiting for a client to connect to any of the sockets added + filename="gio/gsocketlistener.c" + line="664">Blocks waiting for a client to connect to any of the sockets added to the listener. Returns the #GSocket that was accepted. If you want to accept the high-level #GSocketConnection, not a #GSocket, @@ -109402,18 +113919,18 @@ to the listener. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - + a #GSocket on success, %NULL on error. + filename="gio/gsocketlistener.c" + line="686">a #GSocket on success, %NULL on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="666">a #GSocketListener optional="1" allow-none="1"> location where #GObject pointer will be stored, or %NULL. + filename="gio/gsocketlistener.c" + line="667">location where #GObject pointer will be stored, or %NULL. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gsocketlistener.c" + line="668">optional #GCancellable object, %NULL to ignore. + version="2.22" + glib:finish-func="accept_socket_finish" + glib:sync-func="accept_socket"> This is the asynchronous version of g_socket_listener_accept_socket(). + filename="gio/gsocketlistener.c" + line="836">This is the asynchronous version of g_socket_listener_accept_socket(). When the operation is finished @callback will be called. You can then call g_socket_listener_accept_socket_finish() to get the result of the operation. - + a #GSocketListener + filename="gio/gsocketlistener.c" + line="838">a #GSocketListener nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsocketlistener.c" + line="839">a #GCancellable, or %NULL scope="async" closure="2"> a #GAsyncReadyCallback + filename="gio/gsocketlistener.c" + line="840">a #GAsyncReadyCallback nullable="1" allow-none="1"> user data for the callback + filename="gio/gsocketlistener.c" + line="841">user data for the callback @@ -109496,26 +114015,26 @@ to get the result of the operation. version="2.22" throws="1"> Finishes an async accept operation. See g_socket_listener_accept_socket_async() - + filename="gio/gsocketlistener.c" + line="882">Finishes an async accept operation. See g_socket_listener_accept_socket_async() + a #GSocket on success, %NULL on error. + filename="gio/gsocketlistener.c" + line="892">a #GSocket on success, %NULL on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="884">a #GSocketListener a #GAsyncResult. + filename="gio/gsocketlistener.c" + line="885">a #GAsyncResult. optional="1" allow-none="1"> Optional #GObject identifying this source + filename="gio/gsocketlistener.c" + line="886">Optional #GObject identifying this source @@ -109537,8 +114056,8 @@ to get the result of the operation. version="2.22" throws="1"> Creates a socket of type @type and protocol @protocol, binds + filename="gio/gsocketlistener.c" + line="299">Creates a socket of type @type and protocol @protocol, binds it to @address and adds it to the set of sockets we're accepting sockets from. @@ -109561,36 +114080,36 @@ requested, belongs to the caller and must be freed. Call g_socket_listener_close() to stop listening on @address; this will not be done automatically when you drop your final reference to @listener, as references may be held internally. - + %TRUE on success, %FALSE on error. + filename="gio/gsocketlistener.c" + line="333">%TRUE on success, %FALSE on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="301">a #GSocketListener a #GSocketAddress + filename="gio/gsocketlistener.c" + line="302">a #GSocketAddress a #GSocketType + filename="gio/gsocketlistener.c" + line="303">a #GSocketType a #GSocketProtocol + filename="gio/gsocketlistener.c" + line="304">a #GSocketProtocol nullable="1" allow-none="1"> Optional #GObject identifying this source + filename="gio/gsocketlistener.c" + line="305">Optional #GObject identifying this source optional="1" allow-none="1"> location to store the address that was bound to, or %NULL. + filename="gio/gsocketlistener.c" + line="306">location to store the address that was bound to, or %NULL. @@ -109620,8 +114139,8 @@ references may be held internally. version="2.24" throws="1"> Listens for TCP connections on any available port number for both + filename="gio/gsocketlistener.c" + line="1032">Listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available). This is useful if you need to have a socket for incoming connections @@ -109631,18 +114150,18 @@ but don't care about the specific port number. to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. - + the port number, or 0 in case of failure. + filename="gio/gsocketlistener.c" + line="1050">the port number, or 0 in case of failure. a #GSocketListener + filename="gio/gsocketlistener.c" + line="1034">a #GSocketListener nullable="1" allow-none="1"> Optional #GObject identifying this source + filename="gio/gsocketlistener.c" + line="1035">Optional #GObject identifying this source @@ -109661,8 +114180,8 @@ different things depending on what address is connected to. version="2.22" throws="1"> Helper function for g_socket_listener_add_address() that + filename="gio/gsocketlistener.c" + line="412">Helper function for g_socket_listener_add_address() that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces. @@ -109674,24 +114193,24 @@ different things depending on what address is connected to. Call g_socket_listener_close() to stop listening on @port; this will not be done automatically when you drop your final reference to @listener, as references may be held internally. - + %TRUE on success, %FALSE on error. + filename="gio/gsocketlistener.c" + line="432">%TRUE on success, %FALSE on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="414">a #GSocketListener an IP port number (non-zero) + filename="gio/gsocketlistener.c" + line="415">an IP port number (non-zero) nullable="1" allow-none="1"> Optional #GObject identifying this source + filename="gio/gsocketlistener.c" + line="416">Optional #GObject identifying this source @@ -109710,8 +114229,8 @@ references may be held internally. version="2.22" throws="1"> Adds @socket to the set of sockets that we try to accept + filename="gio/gsocketlistener.c" + line="242">Adds @socket to the set of sockets that we try to accept new clients from. The socket must be bound to a local address and listened to. @@ -109724,24 +114243,24 @@ The @socket will not be automatically closed when the @listener is finalized unless the listener held the final reference to the socket. Before GLib 2.42, the @socket was automatically closed on finalization of the @listener, even if references to it were held elsewhere. - + %TRUE on success, %FALSE on error. + filename="gio/gsocketlistener.c" + line="263">%TRUE on success, %FALSE on error. a #GSocketListener + filename="gio/gsocketlistener.c" + line="244">a #GSocketListener a listening #GSocket + filename="gio/gsocketlistener.c" + line="245">a listening #GSocket nullable="1" allow-none="1"> Optional #GObject identifying this source + filename="gio/gsocketlistener.c" + line="246">Optional #GObject identifying this source @@ -109759,17 +114278,17 @@ if references to it were held elsewhere. c:identifier="g_socket_listener_close" version="2.22"> Closes all the sockets in the listener. - + filename="gio/gsocketlistener.c" + line="1005">Closes all the sockets in the listener. + a #GSocketListener + filename="gio/gsocketlistener.c" + line="1007">a #GSocketListener @@ -109778,36 +114297,40 @@ if references to it were held elsewhere. c:identifier="g_socket_listener_set_backlog" version="2.22"> Sets the listen backlog on the sockets in the listener. This must be called + filename="gio/gsocketlistener.c" + line="973">Sets the listen backlog on the sockets in the listener. This must be called before adding any sockets, addresses or ports to the #GSocketListener (for example, by calling g_socket_listener_add_inet_port()) to be effective. See g_socket_set_listen_backlog() for details - + a #GSocketListener + filename="gio/gsocketlistener.c" + line="975">a #GSocketListener an integer + filename="gio/gsocketlistener.c" + line="976">an integer + The number of outstanding connections in the listen queue. @@ -109818,8 +114341,8 @@ See g_socket_set_listen_backlog() for details Emitted when @listener's activity on @socket changes state. + filename="gio/gsocketlistener.c" + line="172">Emitted when @listener's activity on @socket changes state. Note that when @listener is used to listen on both IPv4 and IPv6, a separate set of signals will be emitted for each, and the order they happen in is undefined. @@ -109829,14 +114352,14 @@ the order they happen in is undefined. the event that is occurring + filename="gio/gsocketlistener.c" + line="175">the event that is occurring the #GSocket the event is occurring on + filename="gio/gsocketlistener.c" + line="176">the #GSocket the event is occurring on @@ -109846,15 +114369,18 @@ the order they happen in is undefined. c:type="GSocketListenerClass" glib:is-gtype-struct-for="SocketListener"> Class structure for #GSocketListener. - + + virtual method called when the set of socket listened to changes - + @@ -109867,7 +114393,7 @@ the order they happen in is undefined. - + @@ -109886,7 +114412,7 @@ the order they happen in is undefined. - + @@ -109894,7 +114420,7 @@ the order they happen in is undefined. - + @@ -109902,7 +114428,7 @@ the order they happen in is undefined. - + @@ -109910,7 +114436,7 @@ the order they happen in is undefined. - + @@ -109918,7 +114444,7 @@ the order they happen in is undefined. - + @@ -109931,8 +114457,8 @@ the order they happen in is undefined. glib:get-type="g_socket_listener_event_get_type" c:type="GSocketListenerEvent"> Describes an event occurring on a #GSocketListener. See the + filename="gio/gioenums.h" + line="1971">Describes an event occurring on a #GSocketListener. See the #GSocketListener::event signal for more details. Additional values may be added to this type in the future. @@ -109942,8 +114468,8 @@ Additional values may be added to this type in the future. glib:nick="binding" glib:name="G_SOCKET_LISTENER_BINDING"> The listener is about to bind a socket. + filename="gio/gioenums.h" + line="1973">The listener is about to bind a socket. glib:nick="bound" glib:name="G_SOCKET_LISTENER_BOUND"> The listener has bound a socket. + filename="gio/gioenums.h" + line="1974">The listener has bound a socket. glib:nick="listening" glib:name="G_SOCKET_LISTENER_LISTENING"> The listener is about to start + filename="gio/gioenums.h" + line="1975">The listener is about to start listening on this socket. glib:nick="listened" glib:name="G_SOCKET_LISTENER_LISTENED"> The listener is now listening on + filename="gio/gioenums.h" + line="1977">The listener is now listening on this socket. @@ -109979,7 +114505,7 @@ Additional values may be added to this type in the future. c:type="GSocketListenerPrivate" disguised="1" opaque="1"> - + glib:get-type="g_socket_msg_flags_get_type" c:type="GSocketMsgFlags"> Flags used in g_socket_receive_message() and g_socket_send_message(). + filename="gio/gioenums.h" + line="864">Flags used in g_socket_receive_message() and g_socket_send_message(). The flags listed in the enum are some commonly available flags, but the values used for them are the same as on the platform, and any other flags are passed in/out as is. So to use a platform specific flag, just include @@ -109999,8 +114525,8 @@ the right system header and pass in the flag. glib:nick="none" glib:name="G_SOCKET_MSG_NONE"> No flags. + filename="gio/gioenums.h" + line="866">No flags. glib:nick="oob" glib:name="G_SOCKET_MSG_OOB"> Request to send/receive out of band data. + filename="gio/gioenums.h" + line="867">Request to send/receive out of band data. glib:nick="peek" glib:name="G_SOCKET_MSG_PEEK"> Read data from the socket without removing it from + filename="gio/gioenums.h" + line="868">Read data from the socket without removing it from the queue. glib:nick="dontroute" glib:name="G_SOCKET_MSG_DONTROUTE"> Don't use a gateway to send out the packet, + filename="gio/gioenums.h" + line="870">Don't use a gateway to send out the packet, only send to hosts on directly connected networks. @@ -110036,7 +114562,7 @@ the right system header and pass in the flag. c:type="GSocketPrivate" disguised="1" opaque="1"> - + glib:get-type="g_socket_protocol_get_type" c:type="GSocketProtocol"> A protocol identifier is specified when creating a #GSocket, which is a + filename="gio/gioenums.h" + line="889">A protocol identifier is specified when creating a #GSocket, which is a family/type specific identifier, where 0 means the default protocol for the particular family/type. @@ -110058,8 +114584,8 @@ use protocols not listed here. glib:nick="unknown" glib:name="G_SOCKET_PROTOCOL_UNKNOWN"> The protocol type is unknown + filename="gio/gioenums.h" + line="891">The protocol type is unknown glib:nick="default" glib:name="G_SOCKET_PROTOCOL_DEFAULT"> The default protocol for the family/type + filename="gio/gioenums.h" + line="892">The default protocol for the family/type glib:nick="tcp" glib:name="G_SOCKET_PROTOCOL_TCP"> TCP over IP + filename="gio/gioenums.h" + line="893">TCP over IP glib:nick="udp" glib:name="G_SOCKET_PROTOCOL_UDP"> UDP over IP + filename="gio/gioenums.h" + line="894">UDP over IP glib:nick="sctp" glib:name="G_SOCKET_PROTOCOL_SCTP"> SCTP over IP + filename="gio/gioenums.h" + line="895">SCTP over IP glib:get-type="g_socket_service_get_type" glib:type-struct="SocketServiceClass"> A #GSocketService is an object that represents a service that + filename="gio/gsocketservice.c" + line="25">A `GSocketService` is an object that represents a service that is provided to the network or over local sockets. When a new -connection is made to the service the #GSocketService::incoming +connection is made to the service the [signal@Gio.SocketService::incoming] signal is emitted. -A #GSocketService is a subclass of #GSocketListener and you need +A `GSocketService` is a subclass of [class@Gio.SocketListener] and you need to add the addresses you want to accept connections on with the -#GSocketListener APIs. +[class@Gio.SocketListener] APIs. There are two options for implementing a network service based on -#GSocketService. The first is to create the service using -g_socket_service_new() and to connect to the #GSocketService::incoming -signal. The second is to subclass #GSocketService and override the -default signal handler implementation. +`GSocketService`. The first is to create the service using +[ctor@Gio.SocketService.new] and to connect to the +[signal@Gio.SocketService::incoming] signal. The second is to subclass +`GSocketService` and override the default signal handler implementation. In either case, the handler must immediately return, or else it will block additional incoming connections from being serviced. If you are interested in writing connection handlers that contain -blocking code then see #GThreadedSocketService. +blocking code then see [class@Gio.ThreadedSocketService]. The socket service runs on the main loop of the -[thread-default context][g-main-context-push-thread-default-context] -of the thread it is created in, and is not -threadsafe in general. However, the calls to start and stop the -service are thread-safe so these can be used from threads that +thread-default context (see +[method@GLib.MainContext.push_thread_default]) of the thread it is +created in, and is not threadsafe in general. However, the calls to start and +stop the service are thread-safe so these can be used from threads that handle incoming clients. - + Creates a new #GSocketService with no sockets to listen for. + filename="gio/gsocketservice.c" + line="404">Creates a new #GSocketService with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port(). New services are created active, there is no need to call g_socket_service_start(), unless g_socket_service_stop() has been called before. - + a new #GSocketService. + filename="gio/gsocketservice.c" + line="415">a new #GSocketService. - + signal emitted when new connections are accepted + @@ -110174,25 +114703,26 @@ called before. Check whether the service is active or not. An active + filename="gio/gsocketservice.c" + line="228">Check whether the service is active or not. An active service will accept new clients that connect, while a non-active service will let connecting clients queue up until the service is started. - + %TRUE if the service is active, %FALSE otherwise + filename="gio/gsocketservice.c" + line="237">%TRUE if the service is active, %FALSE otherwise a #GSocketService + filename="gio/gsocketservice.c" + line="230">a #GSocketService @@ -110201,31 +114731,31 @@ up until the service is started. c:identifier="g_socket_service_start" version="2.22"> Restarts the service, i.e. start accepting connections + filename="gio/gsocketservice.c" + line="249">Restarts the service, i.e. start accepting connections from the added sockets when the mainloop runs. This only needs to be called after the service has been stopped from g_socket_service_stop(). This call is thread-safe, so it may be called from a thread handling an incoming client request. - + a #GSocketService + filename="gio/gsocketservice.c" + line="251">a #GSocketService Stops the service, i.e. stops accepting connections + filename="gio/gsocketservice.c" + line="271">Stops the service, i.e. stops accepting connections from the added sockets when the mainloop runs. This call is thread-safe, so it may be called from a thread @@ -110240,15 +114770,15 @@ will happen automatically when the #GSocketService is finalized.) This must be called before calling g_socket_listener_close() as the socket service will start accepting connections immediately when a new socket is added. - + a #GSocketService + filename="gio/gsocketservice.c" + line="273">a #GSocketService @@ -110258,10 +114788,11 @@ when a new socket is added. writable="1" construct="1" transfer-ownership="none" + getter="is_active" default-value="TRUE"> Whether the service is currently accepting connections. + filename="gio/gsocketservice.c" + line="355">Whether the service is currently accepting connections. @@ -110272,8 +114803,8 @@ when a new socket is added. The ::incoming signal is emitted when a new incoming connection + filename="gio/gsocketservice.c" + line="325">The ::incoming signal is emitted when a new incoming connection to @service needs to be handled. The handler must initiate the handling of @connection, but may not block; in essence, asynchronous operations must be used. @@ -110282,15 +114813,15 @@ asynchronous operations must be used. so you need to ref it yourself if you are planning to use it. %TRUE to stop other handlers from being called + filename="gio/gsocketservice.c" + line="340">%TRUE to stop other handlers from being called a new #GSocketConnection object + filename="gio/gsocketservice.c" + line="328">a new #GSocketConnection object nullable="1" allow-none="1"> the source_object passed to + filename="gio/gsocketservice.c" + line="329">the source_object passed to g_socket_listener_add_address() @@ -110310,15 +114841,18 @@ so you need to ref it yourself if you are planning to use it. c:type="GSocketServiceClass" glib:is-gtype-struct-for="SocketService"> Class structure for #GSocketService. - + + signal emitted when new connections are accepted - + @@ -110337,7 +114871,7 @@ so you need to ref it yourself if you are planning to use it. - + @@ -110345,7 +114879,7 @@ so you need to ref it yourself if you are planning to use it. - + @@ -110353,7 +114887,7 @@ so you need to ref it yourself if you are planning to use it. - + @@ -110361,7 +114895,7 @@ so you need to ref it yourself if you are planning to use it. - + @@ -110369,7 +114903,7 @@ so you need to ref it yourself if you are planning to use it. - + @@ -110377,7 +114911,7 @@ so you need to ref it yourself if you are planning to use it. - + @@ -110388,33 +114922,33 @@ so you need to ref it yourself if you are planning to use it. c:type="GSocketServicePrivate" disguised="1" opaque="1"> - + This is the function type of the callback used for the #GSource + filename="gio/giotypes.h" + line="302">This is the function type of the callback used for the #GSource returned by g_socket_create_source(). - + it should return %FALSE if the source should be removed. + filename="gio/giotypes.h" + line="311">it should return %FALSE if the source should be removed. the #GSocket + filename="gio/giotypes.h" + line="304">the #GSocket the current condition at the source fired. + filename="gio/giotypes.h" + line="305">the current condition at the source fired. nullable="1" allow-none="1"> data passed in by the user. + filename="gio/giotypes.h" + line="306">data passed in by the user. @@ -110434,8 +114968,8 @@ returned by g_socket_create_source(). glib:get-type="g_socket_type_get_type" c:type="GSocketType"> Flags used when creating a #GSocket. Some protocols may not implement + filename="gio/gioenums.h" + line="842">Flags used when creating a #GSocket. Some protocols may not implement all the socket types. glib:nick="invalid" glib:name="G_SOCKET_TYPE_INVALID"> Type unknown or wrong + filename="gio/gioenums.h" + line="844">Type unknown or wrong glib:nick="stream" glib:name="G_SOCKET_TYPE_STREAM"> Reliable connection-based byte streams (e.g. TCP). + filename="gio/gioenums.h" + line="845">Reliable connection-based byte streams (e.g. TCP). glib:nick="datagram" glib:name="G_SOCKET_TYPE_DATAGRAM"> Connectionless, unreliable datagram passing. + filename="gio/gioenums.h" + line="846">Connectionless, unreliable datagram passing. (e.g. UDP) glib:nick="seqpacket" glib:name="G_SOCKET_TYPE_SEQPACKET"> Reliable connection-based passing of datagrams + filename="gio/gioenums.h" + line="848">Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). @@ -110483,96 +115017,98 @@ all the socket types. glib:get-type="g_srv_target_get_type" c:symbol-prefix="srv_target"> SRV (service) records are used by some network protocols to provide + filename="gio/gsrvtarget.c" + line="33">A single target host/port that a network service is running on. + +SRV (service) records are used by some network protocols to provide service-specific aliasing and load-balancing. For example, XMPP (Jabber) uses SRV records to locate the XMPP server for a domain; -rather than connecting directly to "example.com" or assuming a -specific server hostname like "xmpp.example.com", an XMPP client -would look up the "xmpp-client" SRV record for "example.com", and +rather than connecting directly to ‘example.com’ or assuming a +specific server hostname like ‘xmpp.example.com’, an XMPP client +would look up the `xmpp-client` SRV record for ‘example.com’, and then connect to whatever host was pointed to by that record. -You can use g_resolver_lookup_service() or -g_resolver_lookup_service_async() to find the #GSrvTargets +You can use [method@Gio.Resolver.lookup_service] or +[method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s for a given service. However, if you are simply planning to connect -to the remote service, you can use #GNetworkService's -#GSocketConnectable interface and not need to worry about -#GSrvTarget at all. - +to the remote service, you can use [class@Gio.NetworkService]’s +[iface@Gio.SocketConnectable] interface and not need to worry about +`GSrvTarget` at all. + Creates a new #GSrvTarget with the given parameters. + filename="gio/gsrvtarget.c" + line="65">Creates a new #GSrvTarget with the given parameters. You should not need to use this; normally #GSrvTargets are created by #GResolver. - + a new #GSrvTarget. + filename="gio/gsrvtarget.c" + line="77">a new #GSrvTarget. the host that the service is running on + filename="gio/gsrvtarget.c" + line="67">the host that the service is running on the port that the service is running on + filename="gio/gsrvtarget.c" + line="68">the port that the service is running on the target's priority + filename="gio/gsrvtarget.c" + line="69">the target's priority the target's weight + filename="gio/gsrvtarget.c" + line="70">the target's weight Copies @target - + filename="gio/gsrvtarget.c" + line="97">Copies @target + a copy of @target + filename="gio/gsrvtarget.c" + line="103">a copy of @target a #GSrvTarget + filename="gio/gsrvtarget.c" + line="99">a #GSrvTarget Frees @target - + filename="gio/gsrvtarget.c" + line="114">Frees @target + a #GSrvTarget + filename="gio/gsrvtarget.c" + line="116">a #GSrvTarget @@ -110581,23 +115117,23 @@ created by #GResolver. c:identifier="g_srv_target_get_hostname" version="2.22"> Gets @target's hostname (in ASCII form; if you are going to present + filename="gio/gsrvtarget.c" + line="129">Gets @target's hostname (in ASCII form; if you are going to present this to the user, you should use g_hostname_is_ascii_encoded() to check if it contains encoded Unicode segments, and use g_hostname_to_unicode() to convert it if it does.) - + @target's hostname + filename="gio/gsrvtarget.c" + line="138">@target's hostname a #GSrvTarget + filename="gio/gsrvtarget.c" + line="131">a #GSrvTarget @@ -110606,20 +115142,20 @@ g_hostname_to_unicode() to convert it if it does.) c:identifier="g_srv_target_get_port" version="2.22"> Gets @target's port - + filename="gio/gsrvtarget.c" + line="148">Gets @target's port + @target's port + filename="gio/gsrvtarget.c" + line="154">@target's port a #GSrvTarget + filename="gio/gsrvtarget.c" + line="150">a #GSrvTarget @@ -110628,22 +115164,22 @@ g_hostname_to_unicode() to convert it if it does.) c:identifier="g_srv_target_get_priority" version="2.22"> Gets @target's priority. You should not need to look at this; + filename="gio/gsrvtarget.c" + line="164">Gets @target's priority. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782. - + @target's priority + filename="gio/gsrvtarget.c" + line="172">@target's priority a #GSrvTarget + filename="gio/gsrvtarget.c" + line="166">a #GSrvTarget @@ -110652,22 +115188,22 @@ RFC 2782. c:identifier="g_srv_target_get_weight" version="2.22"> Gets @target's weight. You should not need to look at this; + filename="gio/gsrvtarget.c" + line="182">Gets @target's weight. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782. - + @target's weight + filename="gio/gsrvtarget.c" + line="190">@target's weight a #GSrvTarget + filename="gio/gsrvtarget.c" + line="184">a #GSrvTarget @@ -110677,13 +115213,13 @@ RFC 2782. version="2.22" introspectable="0"> Sorts @targets in place according to the algorithm in RFC 2782. - + filename="gio/gsrvtarget.c" + line="218">Sorts @targets in place according to the algorithm in RFC 2782. + the head of the sorted list. + filename="gio/gsrvtarget.c" + line="224">the head of the sorted list. @@ -110691,8 +115227,8 @@ RFC 2782. a #GList of #GSrvTarget + filename="gio/gsrvtarget.c" + line="220">a #GList of #GSrvTarget @@ -110702,10 +115238,10 @@ RFC 2782. #GStaticResource is an opaque data structure and can only be accessed + filename="gio/gresource.c" + line="218">`GStaticResource` is an opaque data structure and can only be accessed using the following functions. - + @@ -110723,21 +115259,22 @@ using the following functions. Finalized a GResource initialized by g_static_resource_init(). + filename="gio/gresource.c" + line="1544">Finalizes a [struct@Gio.Resource] initialized by +[method@Gio.StaticResource.init]. This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] +[`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. - + pointer to a static #GStaticResource + filename="gio/gresource.c" + line="1546">pointer to a static [struct@Gio.StaticResource] @@ -110746,46 +115283,47 @@ and is not typically used by other code. c:identifier="g_static_resource_get_resource" version="2.32"> Gets the GResource that was registered by a call to g_static_resource_init(). + filename="gio/gresource.c" + line="1580">Gets the [struct@Gio.Resource] that was registered by a call to +[method@Gio.StaticResource.init]. This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] +[`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. - + a #GResource + filename="gio/gresource.c" + line="1591">a [struct@Gio.Resource] pointer to a static #GStaticResource + filename="gio/gresource.c" + line="1582">pointer to a static [struct@Gio.StaticResource] Initializes a GResource from static data using a -GStaticResource. + filename="gio/gresource.c" + line="1514">Initializes a [struct@Gio.Resource] from static data using a +[struct@Gio.StaticResource]. This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] +[`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. - + pointer to a static #GStaticResource + filename="gio/gresource.c" + line="1516">pointer to a static [struct@Gio.StaticResource] @@ -110799,13 +115337,13 @@ and is not typically used by other code. glib:type-name="GSubprocess" glib:get-type="g_subprocess_get_type"> #GSubprocess allows the creation of and interaction with child + filename="gio/gsubprocess.c" + line="19">`GSubprocess` allows the creation of and interaction with child processes. Processes can be communicated with using standard GIO-style APIs (ie: -#GInputStream, #GOutputStream). There are GIO-style APIs to wait for -process termination (ie: cancellable and with an asynchronous +[class@Gio.InputStream], [class@Gio.OutputStream]). There are GIO-style APIs +to wait for process termination (ie: cancellable and with an asynchronous variant). There is an API to force a process to terminate, as well as a @@ -110813,50 +115351,56 @@ race-free API for sending UNIX signals to a subprocess. One major advantage that GIO brings over the core GLib library is comprehensive API for asynchronous I/O, such -g_output_stream_splice_async(). This makes GSubprocess +[method@Gio.OutputStream.splice_async]. This makes `GSubprocess` significantly more powerful and flexible than equivalent APIs in some other languages such as the `subprocess.py` -included with Python. For example, using #GSubprocess one could +included with Python. For example, using `GSubprocess` one could create two child processes, reading standard output from the first, processing it, and writing to the input stream of the second, all without blocking the main loop. -A powerful g_subprocess_communicate() API is provided similar to the +A powerful [method@Gio.Subprocess.communicate] API is provided similar to the `communicate()` method of `subprocess.py`. This enables very easy interaction with a subprocess that has been opened with pipes. -#GSubprocess defaults to tight control over the file descriptors open -in the child process, avoiding dangling-fd issues that are caused by -a simple fork()/exec(). The only open file descriptors in the +`GSubprocess` defaults to tight control over the file descriptors open +in the child process, avoiding dangling-FD issues that are caused by +a simple `fork()`/`exec()`. The only open file descriptors in the spawned process are ones that were explicitly specified by the -#GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was +`GSubprocess` API (unless `G_SUBPROCESS_FLAGS_INHERIT_FDS` was specified). -#GSubprocess will quickly reap all child processes as they exit, -avoiding "zombie processes" remaining around for long periods of -time. g_subprocess_wait() can be used to wait for this to happen, +`GSubprocess` will quickly reap all child processes as they exit, +avoiding ‘zombie processes’ remaining around for long periods of +time. [method@Gio.Subprocess.wait] can be used to wait for this to happen, but it will happen even without the call being explicitly made. -As a matter of principle, #GSubprocess has no API that accepts +As a matter of principle, `GSubprocess` has no API that accepts shell-style space-separated strings. It will, however, match the -typical shell behaviour of searching the PATH for executables that do +typical shell behaviour of searching the `PATH` for executables that do not contain a directory separator in their name. By default, the `PATH` of the current process is used. You can specify -%G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP to use the `PATH` of the +`G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP` to use the `PATH` of the launcher environment instead. -#GSubprocess attempts to have a very simple API for most uses (ie: +`GSubprocess` attempts to have a very simple API for most uses (ie: spawning a subprocess with arguments and support for most typical -kinds of input and output redirection). See g_subprocess_new(). The -#GSubprocessLauncher API is provided for more complicated cases +kinds of input and output redirection). See [ctor@Gio.Subprocess.new]. The +[class@Gio.SubprocessLauncher] API is provided for more complicated cases (advanced types of redirection, environment variable manipulation, change of working directory, child setup functions, etc). -A typical use of #GSubprocess will involve calling -g_subprocess_new(), followed by g_subprocess_wait_async() or -g_subprocess_wait(). After the process exits, the status can be -checked using functions such as g_subprocess_get_if_exited() (which -are similar to the familiar WIFEXITED-style POSIX macros). +A typical use of `GSubprocess` will involve calling +[ctor@Gio.Subprocess.new], followed by [method@Gio.Subprocess.wait_async] or +[method@Gio.Subprocess.wait]. After the process exits, the status can be +checked using functions such as [method@Gio.Subprocess.get_if_exited] (which +are similar to the familiar `WIFEXITED`-style POSIX macros). + +Note that as of GLib 2.82, creating a `GSubprocess` causes the signal +`SIGPIPE` to be ignored for the remainder of the program. If you are writing +a command-line utility that uses `GSubprocess`, you may need to take into +account the fact that your program will not automatically be killed +if it tries to write to `stdout` after it has been closed. version="2.40" introspectable="0"> Create a new process with the given flags and varargs argument + filename="gio/gsubprocess.c" + line="551">Create a new process with the given flags and varargs argument list. By default, matching the g_spawn_async() defaults, the child's stdin will be set to the system null device, and stdout/stderr will be inherited from the parent. You can use @flags to control this behavior. The argument list must be terminated with %NULL. - + A newly created #GSubprocess, or %NULL on error (and @error + filename="gio/gsubprocess.c" + line="566">A newly created #GSubprocess, or %NULL on error (and @error will be set) flags that define the behaviour of the subprocess + filename="gio/gsubprocess.c" + line="553">flags that define the behaviour of the subprocess nullable="1" allow-none="1"> return location for an error, or %NULL + filename="gio/gsubprocess.c" + line="554">return location for an error, or %NULL first commandline argument to pass to the subprocess + filename="gio/gsubprocess.c" + line="555">first commandline argument to pass to the subprocess more commandline arguments, followed by %NULL + filename="gio/gsubprocess.c" + line="556">more commandline arguments, followed by %NULL @@ -110916,31 +115460,31 @@ The argument list must be terminated with %NULL. version="2.40" throws="1"> Create a new process with the given flags and argument list. + filename="gio/gsubprocess.c" + line="601">Create a new process with the given flags and argument list. The argument list is expected to be %NULL-terminated. - + A newly created #GSubprocess, or %NULL on error (and @error + filename="gio/gsubprocess.c" + line="611">A newly created #GSubprocess, or %NULL on error (and @error will be set) commandline arguments for the subprocess + filename="gio/gsubprocess.c" + line="603">commandline arguments for the subprocess flags that define the behaviour of the subprocess + filename="gio/gsubprocess.c" + line="604">flags that define the behaviour of the subprocess @@ -110948,10 +115492,11 @@ The argument list is expected to be %NULL-terminated. + throws="1" + glib:async-func="communicate_async"> Communicate with the subprocess until it terminates, and all input + filename="gio/gsubprocess.c" + line="1614">Communicate with the subprocess until it terminates, and all input and output has been completed. If @stdin_buf is given, the subprocess must have been created with @@ -110992,18 +115537,18 @@ starting this function, since they may be left in strange states, even if the operation was cancelled. You should especially not attempt to interact with the pipes while the operation is in progress (either from another thread or if using the asynchronous version). - + %TRUE if successful + filename="gio/gsubprocess.c" + line="1665">%TRUE if successful a #GSubprocess + filename="gio/gsubprocess.c" + line="1616">a #GSubprocess data to send to the stdin of the subprocess, or %NULL + filename="gio/gsubprocess.c" + line="1617">data to send to the stdin of the subprocess, or %NULL a #GCancellable + filename="gio/gsubprocess.c" + line="1618">a #GCancellable data read from the subprocess stdout + filename="gio/gsubprocess.c" + line="1619">data read from the subprocess stdout data read from the subprocess stderr + filename="gio/gsubprocess.c" + line="1620">data read from the subprocess stderr + c:identifier="g_subprocess_communicate_async" + glib:finish-func="communicate_finish" + glib:sync-func="communicate"> Asynchronous version of g_subprocess_communicate(). Complete + filename="gio/gsubprocess.c" + line="1695">Asynchronous version of g_subprocess_communicate(). Complete invocation with g_subprocess_communicate_finish(). - + Self + filename="gio/gsubprocess.c" + line="1697">Self nullable="1" allow-none="1"> Input data, or %NULL + filename="gio/gsubprocess.c" + line="1698">Input data, or %NULL nullable="1" allow-none="1"> Cancellable + filename="gio/gsubprocess.c" + line="1699">Cancellable scope="async" closure="3"> Callback + filename="gio/gsubprocess.c" + line="1700">Callback nullable="1" allow-none="1"> User data + filename="gio/gsubprocess.c" + line="1701">User data @@ -111111,23 +115658,23 @@ invocation with g_subprocess_communicate_finish(). c:identifier="g_subprocess_communicate_finish" throws="1"> Complete an invocation of g_subprocess_communicate_async(). - + filename="gio/gsubprocess.c" + line="1720">Complete an invocation of g_subprocess_communicate_async(). + Self + filename="gio/gsubprocess.c" + line="1722">Self Result + filename="gio/gsubprocess.c" + line="1723">Result optional="1" allow-none="1"> Return location for stdout data + filename="gio/gsubprocess.c" + line="1724">Return location for stdout data optional="1" allow-none="1"> Return location for stderr data + filename="gio/gsubprocess.c" + line="1725">Return location for stderr data + throws="1" + glib:async-func="communicate_utf8_async"> Like g_subprocess_communicate(), but validates the output of the + filename="gio/gsubprocess.c" + line="1761">Like g_subprocess_communicate(), but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string. On error, @stdout_buf and @stderr_buf will be set to undefined values and should not be used. - + a #GSubprocess + filename="gio/gsubprocess.c" + line="1763">a #GSubprocess nullable="1" allow-none="1"> data to send to the stdin of the subprocess, or %NULL + filename="gio/gsubprocess.c" + line="1764">data to send to the stdin of the subprocess, or %NULL nullable="1" allow-none="1"> a #GCancellable + filename="gio/gsubprocess.c" + line="1765">a #GCancellable optional="1" allow-none="1"> data read from the subprocess stdout + filename="gio/gsubprocess.c" + line="1766">data read from the subprocess stdout optional="1" allow-none="1"> data read from the subprocess stderr + filename="gio/gsubprocess.c" + line="1767">data read from the subprocess stderr + c:identifier="g_subprocess_communicate_utf8_async" + glib:finish-func="communicate_utf8_finish" + glib:sync-func="communicate_utf8"> Asynchronous version of g_subprocess_communicate_utf8(). Complete + filename="gio/gsubprocess.c" + line="1809">Asynchronous version of g_subprocess_communicate_utf8(). Complete invocation with g_subprocess_communicate_utf8_finish(). - + Self + filename="gio/gsubprocess.c" + line="1811">Self nullable="1" allow-none="1"> Input data, or %NULL + filename="gio/gsubprocess.c" + line="1812">Input data, or %NULL nullable="1" allow-none="1"> Cancellable + filename="gio/gsubprocess.c" + line="1813">Cancellable scope="async" closure="3"> Callback + filename="gio/gsubprocess.c" + line="1814">Callback nullable="1" allow-none="1"> User data + filename="gio/gsubprocess.c" + line="1815">User data @@ -111282,23 +115832,23 @@ invocation with g_subprocess_communicate_utf8_finish(). c:identifier="g_subprocess_communicate_utf8_finish" throws="1"> Complete an invocation of g_subprocess_communicate_utf8_async(). - + filename="gio/gsubprocess.c" + line="1873">Complete an invocation of g_subprocess_communicate_utf8_async(). + Self + filename="gio/gsubprocess.c" + line="1875">Self Result + filename="gio/gsubprocess.c" + line="1876">Result optional="1" allow-none="1"> Return location for stdout data + filename="gio/gsubprocess.c" + line="1877">Return location for stdout data optional="1" allow-none="1"> Return location for stderr data + filename="gio/gsubprocess.c" + line="1878">Return location for stderr data @@ -111331,23 +115881,23 @@ invocation with g_subprocess_communicate_utf8_finish(). c:identifier="g_subprocess_force_exit" version="2.40"> Use an operating-system specific method to attempt an immediate, + filename="gio/gsubprocess.c" + line="1092">Use an operating-system specific method to attempt an immediate, forceful termination of the process. There is no mechanism to determine whether or not the request itself was successful; however, you can use g_subprocess_wait() to monitor the status of the process after calling this function. On Unix, this function sends %SIGKILL. - + a #GSubprocess + filename="gio/gsubprocess.c" + line="1094">a #GSubprocess @@ -111356,8 +115906,8 @@ On Unix, this function sends %SIGKILL. c:identifier="g_subprocess_get_exit_status" version="2.40"> Check the exit status of the subprocess, given that it exited + filename="gio/gsubprocess.c" + line="1233">Check the exit status of the subprocess, given that it exited normally. This is the value passed to the exit() system call or the return value from main. @@ -111365,18 +115915,18 @@ This is equivalent to the system WEXITSTATUS macro. It is an error to call this function before g_subprocess_wait() and unless g_subprocess_get_if_exited() returned %TRUE. - + the exit status + filename="gio/gsubprocess.c" + line="1246">the exit status a #GSubprocess + filename="gio/gsubprocess.c" + line="1235">a #GSubprocess @@ -111385,23 +115935,23 @@ unless g_subprocess_get_if_exited() returned %TRUE. c:identifier="g_subprocess_get_identifier" version="2.40"> On UNIX, returns the process ID as a decimal string. + filename="gio/gsubprocess.c" + line="629">On UNIX, returns the process ID as a decimal string. On Windows, returns the result of GetProcessId() also as a string. If the subprocess has terminated, this will return %NULL. - + the subprocess identifier, or %NULL if the subprocess + filename="gio/gsubprocess.c" + line="637">the subprocess identifier, or %NULL if the subprocess has terminated a #GSubprocess + filename="gio/gsubprocess.c" + line="631">a #GSubprocess @@ -111410,26 +115960,26 @@ If the subprocess has terminated, this will return %NULL. c:identifier="g_subprocess_get_if_exited" version="2.40"> Check if the given subprocess exited normally (ie: by way of exit() + filename="gio/gsubprocess.c" + line="1195">Check if the given subprocess exited normally (ie: by way of exit() or return from main()). This is equivalent to the system WIFEXITED macro. It is an error to call this function before g_subprocess_wait() has returned. - + %TRUE if the case of a normal exit + filename="gio/gsubprocess.c" + line="1207">%TRUE if the case of a normal exit a #GSubprocess + filename="gio/gsubprocess.c" + line="1197">a #GSubprocess @@ -111438,25 +115988,25 @@ returned. c:identifier="g_subprocess_get_if_signaled" version="2.40"> Check if the given subprocess terminated in response to a signal. + filename="gio/gsubprocess.c" + line="1274">Check if the given subprocess terminated in response to a signal. This is equivalent to the system WIFSIGNALED macro. It is an error to call this function before g_subprocess_wait() has returned. - + %TRUE if the case of termination due to a signal + filename="gio/gsubprocess.c" + line="1285">%TRUE if the case of termination due to a signal a #GSubprocess + filename="gio/gsubprocess.c" + line="1276">a #GSubprocess @@ -111465,8 +116015,8 @@ returned. c:identifier="g_subprocess_get_status" version="2.40"> Gets the raw status code of the process, as from waitpid(). + filename="gio/gsubprocess.c" + line="1120">Gets the raw status code of the process, as from waitpid(). This value has no particular meaning, but it can be used with the macros defined by the system headers such as WIFEXITED. It can also @@ -111477,18 +116027,18 @@ followed by g_subprocess_get_exit_status(). It is an error to call this function before g_subprocess_wait() has returned. - + the (meaningless) waitpid() exit status from the kernel + filename="gio/gsubprocess.c" + line="1136">the (meaningless) waitpid() exit status from the kernel a #GSubprocess + filename="gio/gsubprocess.c" + line="1122">a #GSubprocess @@ -111497,24 +116047,24 @@ returned. c:identifier="g_subprocess_get_stderr_pipe" version="2.40"> Gets the #GInputStream from which to read the stderr output of + filename="gio/gsubprocess.c" + line="699">Gets the #GInputStream from which to read the stderr output of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE, otherwise %NULL will be returned. - + the stderr pipe + filename="gio/gsubprocess.c" + line="709">the stderr pipe a #GSubprocess + filename="gio/gsubprocess.c" + line="701">a #GSubprocess @@ -111523,24 +116073,24 @@ otherwise %NULL will be returned. c:identifier="g_subprocess_get_stdin_pipe" version="2.40"> Gets the #GOutputStream that you can write to in order to give data + filename="gio/gsubprocess.c" + line="655">Gets the #GOutputStream that you can write to in order to give data to the stdin of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned. - + the stdout pipe + filename="gio/gsubprocess.c" + line="665">the stdout pipe a #GSubprocess + filename="gio/gsubprocess.c" + line="657">a #GSubprocess @@ -111549,24 +116099,24 @@ not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned. c:identifier="g_subprocess_get_stdout_pipe" version="2.40"> Gets the #GInputStream from which to read the stdout output of + filename="gio/gsubprocess.c" + line="677">Gets the #GInputStream from which to read the stdout output of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, otherwise %NULL will be returned. - + the stdout pipe + filename="gio/gsubprocess.c" + line="687">the stdout pipe a #GSubprocess + filename="gio/gsubprocess.c" + line="679">a #GSubprocess @@ -111575,25 +116125,25 @@ otherwise %NULL will be returned. c:identifier="g_subprocess_get_successful" version="2.40"> Checks if the process was "successful". A process is considered + filename="gio/gsubprocess.c" + line="1158">Checks if the process was "successful". A process is considered successful if it exited cleanly with an exit status of 0, either by way of the exit() system call or return from main(). It is an error to call this function before g_subprocess_wait() has returned. - + %TRUE if the process exited cleanly with a exit status of 0 + filename="gio/gsubprocess.c" + line="1169">%TRUE if the process exited cleanly with a exit status of 0 a #GSubprocess + filename="gio/gsubprocess.c" + line="1160">a #GSubprocess @@ -111602,26 +116152,26 @@ returned. c:identifier="g_subprocess_get_term_sig" version="2.40"> Get the signal number that caused the subprocess to terminate, given + filename="gio/gsubprocess.c" + line="1311">Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal. This is equivalent to the system WTERMSIG macro. It is an error to call this function before g_subprocess_wait() and unless g_subprocess_get_if_signaled() returned %TRUE. - + the signal causing termination + filename="gio/gsubprocess.c" + line="1323">the signal causing termination a #GSubprocess + filename="gio/gsubprocess.c" + line="1313">a #GSubprocess @@ -111630,29 +116180,29 @@ unless g_subprocess_get_if_signaled() returned %TRUE. c:identifier="g_subprocess_send_signal" version="2.40"> Sends the UNIX signal @signal_num to the subprocess, if it is still + filename="gio/gsubprocess.c" + line="1067">Sends the UNIX signal @signal_num to the subprocess, if it is still running. This API is race-free. If the subprocess has terminated, it will not be signalled. This API is not available on Windows. - + a #GSubprocess + filename="gio/gsubprocess.c" + line="1069">a #GSubprocess the signal number to send + filename="gio/gsubprocess.c" + line="1070">the signal number to send @@ -111660,10 +116210,11 @@ This API is not available on Windows. + throws="1" + glib:async-func="wait_async"> Synchronously wait for the subprocess to terminate. + filename="gio/gsubprocess.c" + line="869">Synchronously wait for the subprocess to terminate. After the process terminates you can query its exit status with functions such as g_subprocess_get_if_exited() and @@ -111674,18 +116225,18 @@ abnormal termination. See g_subprocess_wait_check() for that. Cancelling @cancellable doesn't kill the subprocess. Call g_subprocess_force_exit() if it is desirable. - + %TRUE on success, %FALSE if @cancellable was cancelled + filename="gio/gsubprocess.c" + line="887">%TRUE on success, %FALSE if @cancellable was cancelled a #GSubprocess + filename="gio/gsubprocess.c" + line="871">a #GSubprocess nullable="1" allow-none="1"> a #GCancellable + filename="gio/gsubprocess.c" + line="872">a #GCancellable + version="2.40" + glib:finish-func="wait_finish" + glib:sync-func="wait"> Wait for the subprocess to terminate. + filename="gio/gsubprocess.c" + line="768">Wait for the subprocess to terminate. This is the asynchronous version of g_subprocess_wait(). - + a #GSubprocess + filename="gio/gsubprocess.c" + line="770">a #GSubprocess nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsubprocess.c" + line="771">a #GCancellable, or %NULL scope="async" closure="2"> a #GAsyncReadyCallback to call when the operation is complete + filename="gio/gsubprocess.c" + line="772">a #GAsyncReadyCallback to call when the operation is complete nullable="1" allow-none="1"> user_data for @callback + filename="gio/gsubprocess.c" + line="773">user_data for @callback @@ -111752,23 +116305,24 @@ This is the asynchronous version of g_subprocess_wait(). + throws="1" + glib:async-func="wait_check_async"> Combines g_subprocess_wait() with g_spawn_check_wait_status(). - + filename="gio/gsubprocess.c" + line="932">Combines g_subprocess_wait() with g_spawn_check_wait_status(). + %TRUE on success, %FALSE if process exited abnormally, or + filename="gio/gsubprocess.c" + line="940">%TRUE on success, %FALSE if process exited abnormally, or @cancellable was cancelled a #GSubprocess + filename="gio/gsubprocess.c" + line="934">a #GSubprocess nullable="1" allow-none="1"> a #GCancellable + filename="gio/gsubprocess.c" + line="935">a #GCancellable + version="2.40" + glib:finish-func="wait_check_finish" + glib:sync-func="wait_check"> Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). + filename="gio/gsubprocess.c" + line="962">Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). This is the asynchronous version of g_subprocess_wait_check(). - + a #GSubprocess + filename="gio/gsubprocess.c" + line="964">a #GSubprocess nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gsubprocess.c" + line="965">a #GCancellable, or %NULL scope="async" closure="2"> a #GAsyncReadyCallback to call when the operation is complete + filename="gio/gsubprocess.c" + line="966">a #GAsyncReadyCallback to call when the operation is complete nullable="1" allow-none="1"> user_data for @callback + filename="gio/gsubprocess.c" + line="967">user_data for @callback @@ -111837,27 +116393,27 @@ This is the asynchronous version of g_subprocess_wait_check(). version="2.40" throws="1"> Collects the result of a previous call to + filename="gio/gsubprocess.c" + line="984">Collects the result of a previous call to g_subprocess_wait_check_async(). - + %TRUE if successful, or %FALSE with @error set + filename="gio/gsubprocess.c" + line="993">%TRUE if successful, or %FALSE with @error set a #GSubprocess + filename="gio/gsubprocess.c" + line="986">a #GSubprocess the #GAsyncResult passed to your #GAsyncReadyCallback + filename="gio/gsubprocess.c" + line="987">the #GAsyncResult passed to your #GAsyncReadyCallback @@ -111867,46 +116423,54 @@ g_subprocess_wait_check_async(). version="2.40" throws="1"> Collects the result of a previous call to + filename="gio/gsubprocess.c" + line="817">Collects the result of a previous call to g_subprocess_wait_async(). - + %TRUE if successful, or %FALSE with @error set + filename="gio/gsubprocess.c" + line="826">%TRUE if successful, or %FALSE with @error set a #GSubprocess + filename="gio/gsubprocess.c" + line="819">a #GSubprocess the #GAsyncResult passed to your #GAsyncReadyCallback + filename="gio/gsubprocess.c" + line="820">the #GAsyncResult passed to your #GAsyncReadyCallback + Argument vector. + Subprocess flags. @@ -111916,8 +116480,8 @@ g_subprocess_wait_async(). glib:get-type="g_subprocess_flags_get_type" c:type="GSubprocessFlags"> Flags to define the behaviour of a #GSubprocess. + filename="gio/gioenums.h" + line="2006">Flags to define the behaviour of a #GSubprocess. Note that the default for stdin is to redirect from `/dev/null`. For stdout and stderr the default are for them to inherit the @@ -111932,8 +116496,8 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:nick="none" glib:name="G_SUBPROCESS_FLAGS_NONE"> No flags. + filename="gio/gioenums.h" + line="2008">No flags. create a pipe for the stdin of the + filename="gio/gioenums.h" + line="2009">create a pipe for the stdin of the spawned process that can be accessed with g_subprocess_get_stdin_pipe(). @@ -111952,8 +116516,8 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:nick="stdin-inherit" glib:name="G_SUBPROCESS_FLAGS_STDIN_INHERIT"> stdin is inherited from the + filename="gio/gioenums.h" + line="2012">stdin is inherited from the calling process. create a pipe for the stdout of the + filename="gio/gioenums.h" + line="2014">create a pipe for the stdout of the spawned process that can be accessed with g_subprocess_get_stdout_pipe(). @@ -111973,8 +116537,8 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:nick="stdout-silence" glib:name="G_SUBPROCESS_FLAGS_STDOUT_SILENCE"> silence the stdout of the spawned + filename="gio/gioenums.h" + line="2017">silence the stdout of the spawned process (ie: redirect to `/dev/null`). create a pipe for the stderr of the + filename="gio/gioenums.h" + line="2019">create a pipe for the stderr of the spawned process that can be accessed with g_subprocess_get_stderr_pipe(). @@ -111994,8 +116558,8 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:nick="stderr-silence" glib:name="G_SUBPROCESS_FLAGS_STDERR_SILENCE"> silence the stderr of the spawned + filename="gio/gioenums.h" + line="2022">silence the stderr of the spawned process (ie: redirect to `/dev/null`). merge the stderr of the spawned + filename="gio/gioenums.h" + line="2024">merge the stderr of the spawned process with whatever the stdout happens to be. This is a good way of directing both streams to a common log file, for example. @@ -112015,8 +116579,8 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:nick="inherit-fds" glib:name="G_SUBPROCESS_FLAGS_INHERIT_FDS"> spawned processes will inherit the + filename="gio/gioenums.h" + line="2027">spawned processes will inherit the file descriptors of their parent, unless those descriptors have been explicitly marked as close-on-exec. This flag has no effect over the "standard" file descriptors (stdin, stdout, stderr). @@ -112027,8 +116591,8 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:nick="search-path-from-envp" glib:name="G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP"> if path searching is + filename="gio/gioenums.h" + line="2031">if path searching is needed when spawning the subprocess, use the `PATH` in the launcher environment. (Since: 2.72) @@ -112041,12 +116605,12 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and glib:type-name="GSubprocessLauncher" glib:get-type="g_subprocess_launcher_get_type"> This class contains a set of options for launching child processes, + filename="gio/gsubprocesslauncher.c" + line="19">This class contains a set of options for launching child processes, such as where its standard input and output will be directed, the argument list, the environment, and more. -While the #GSubprocess class has high level functions covering +While the [class@Gio.Subprocess] class has high level functions covering popular cases, use of this class allows access to more advanced options. It can also be used to launch multiple subprocesses with a similar configuration. @@ -112054,21 +116618,21 @@ a similar configuration. c:identifier="g_subprocess_launcher_new" version="2.40"> Creates a new #GSubprocessLauncher. + filename="gio/gsubprocesslauncher.c" + line="192">Creates a new #GSubprocessLauncher. The launcher is created with the default options. A copy of the environment of the calling process is made at the time of this call and will be used as the environment that the process is launched in. - + #GSubprocessFlags + filename="gio/gsubprocesslauncher.c" + line="194">#GSubprocessFlags @@ -112077,8 +116641,8 @@ and will be used as the environment that the process is launched in. c:identifier="g_subprocess_launcher_close" version="2.68"> Closes all the file descriptors previously passed to the object with + filename="gio/gsubprocesslauncher.c" + line="629">Closes all the file descriptors previously passed to the object with g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc. After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will @@ -112088,15 +116652,15 @@ called more than once. This function is called automatically when the #GSubprocessLauncher is disposed, but is provided separately so that garbage collected language bindings can call it earlier to guarantee when FDs are closed. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="631">a #GSubprocessLauncher @@ -112105,31 +116669,31 @@ language bindings can call it earlier to guarantee when FDs are closed. c:identifier="g_subprocess_launcher_getenv" version="2.40"> Returns the value of the environment variable @variable in the + filename="gio/gsubprocesslauncher.c" + line="301">Returns the value of the environment variable @variable in the environment of processes launched from this launcher. On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8. - + the value of the environment variable, + filename="gio/gsubprocesslauncher.c" + line="312">the value of the environment variable, %NULL if unset a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="303">a #GSubprocessLauncher the environment variable to get + filename="gio/gsubprocesslauncher.c" + line="304">the environment variable to get @@ -112139,8 +116703,8 @@ On Windows, it will be UTF-8. version="2.40" introspectable="0"> Sets up a child setup function. + filename="gio/gsubprocesslauncher.c" + line="682">Sets up a child setup function. The child setup function will be called after fork() but before exec() on the child's side. @@ -112153,15 +116717,15 @@ given. %NULL can be given as @child_setup to disable the functionality. Child setup functions are only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="684">a #GSubprocessLauncher closure="1" destroy="2"> a #GSpawnChildSetupFunc to use as the child setup function + filename="gio/gsubprocesslauncher.c" + line="685">a #GSpawnChildSetupFunc to use as the child setup function @@ -112180,16 +116744,16 @@ Child setup functions are only available on UNIX. nullable="1" allow-none="1"> user data for @child_setup + filename="gio/gsubprocesslauncher.c" + line="686">user data for @child_setup a #GDestroyNotify for @user_data + filename="gio/gsubprocesslauncher.c" + line="687">a #GDestroyNotify for @user_data @@ -112198,27 +116762,27 @@ Child setup functions are only available on UNIX. c:identifier="g_subprocess_launcher_set_cwd" version="2.40"> Sets the current working directory that processes will be launched + filename="gio/gsubprocesslauncher.c" + line="324">Sets the current working directory that processes will be launched with. By default processes are launched with the current working directory of the launching process at the time of launch. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="326">a #GSubprocessLauncher the cwd for launched processes + filename="gio/gsubprocesslauncher.c" + line="327">the cwd for launched processes @@ -112227,8 +116791,8 @@ of the launching process at the time of launch. c:identifier="g_subprocess_launcher_set_environ" version="2.40"> Replace the entire environment of processes launched from this + filename="gio/gsubprocesslauncher.c" + line="215">Replace the entire environment of processes launched from this launcher with the given 'environ' variable. Typically you will build this variable by using g_listenv() to copy @@ -112247,21 +116811,21 @@ etc.) before launching the subprocess. On UNIX, all strings in this array can be arbitrary byte strings. On Windows, they should be in UTF-8. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="217">a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="218"> the replacement environment @@ -112273,8 +116837,8 @@ On Windows, they should be in UTF-8. c:identifier="g_subprocess_launcher_set_flags" version="2.40"> Sets the flags on the launcher. + filename="gio/gsubprocesslauncher.c" + line="345">Sets the flags on the launcher. The default flags are %G_SUBPROCESS_FLAGS_NONE. @@ -112286,21 +116850,21 @@ handle a particular stdio stream (eg: specifying both You may also not set a flag that conflicts with a previous call to a function like g_subprocess_launcher_set_stdin_file_path() or g_subprocess_launcher_take_stdout_fd(). - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="347">a #GSubprocessLauncher #GSubprocessFlags + filename="gio/gsubprocesslauncher.c" + line="348">#GSubprocessFlags @@ -112309,8 +116873,8 @@ g_subprocess_launcher_take_stdout_fd(). c:identifier="g_subprocess_launcher_set_stderr_file_path" version="2.40"> Sets the file path to use as the stderr for spawned processes. + filename="gio/gsubprocesslauncher.c" + line="533">Sets the file path to use as the stderr for spawned processes. If @path is %NULL then any previously given path is unset. @@ -112324,15 +116888,15 @@ You may not set a stderr file path if a stderr fd is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="535">a #GSubprocessLauncher nullable="1" allow-none="1"> a filename or %NULL + filename="gio/gsubprocesslauncher.c" + line="536">a filename or %NULL @@ -112350,8 +116914,8 @@ This feature is only available on UNIX. c:identifier="g_subprocess_launcher_set_stdin_file_path" version="2.40"> Sets the file path to use as the stdin for spawned processes. + filename="gio/gsubprocesslauncher.c" + line="407">Sets the file path to use as the stdin for spawned processes. If @path is %NULL then any previously given path is unset. @@ -112361,19 +116925,25 @@ You may not set a stdin file path if a stdin fd is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="409">a #GSubprocessLauncher - - + + a filename or %NULL + @@ -112381,8 +116951,8 @@ This feature is only available on UNIX. c:identifier="g_subprocess_launcher_set_stdout_file_path" version="2.40"> Sets the file path to use as the stdout for spawned processes. + filename="gio/gsubprocesslauncher.c" + line="470">Sets the file path to use as the stdout for spawned processes. If @path is %NULL then any previously given path is unset. @@ -112393,15 +116963,15 @@ You may not set a stdout file path if a stdout fd is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="472">a #GSubprocessLauncher nullable="1" allow-none="1"> a filename or %NULL + filename="gio/gsubprocesslauncher.c" + line="473">a filename or %NULL @@ -112419,41 +116989,41 @@ This feature is only available on UNIX. c:identifier="g_subprocess_launcher_setenv" version="2.40"> Sets the environment variable @variable in the environment of + filename="gio/gsubprocesslauncher.c" + line="254">Sets the environment variable @variable in the environment of processes launched from this launcher. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="256">a #GSubprocessLauncher the environment variable to set, + filename="gio/gsubprocesslauncher.c" + line="257">the environment variable to set, must not contain '=' the new value for the variable + filename="gio/gsubprocesslauncher.c" + line="259">the new value for the variable whether to change the variable if it already exists + filename="gio/gsubprocesslauncher.c" + line="260">whether to change the variable if it already exists @@ -112463,38 +117033,38 @@ On Windows, they should be in UTF-8. version="2.40" introspectable="0"> Creates a #GSubprocess given a provided varargs list of arguments. - + filename="gio/gsubprocesslauncher.c" + line="720">Creates a #GSubprocess given a provided varargs list of arguments. + A new #GSubprocess, or %NULL on error (and @error will be set) + filename="gio/gsubprocesslauncher.c" + line="730">A new #GSubprocess, or %NULL on error (and @error will be set) a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="722">a #GSubprocessLauncher Error + filename="gio/gsubprocesslauncher.c" + line="723">Error Command line arguments + filename="gio/gsubprocesslauncher.c" + line="724">Command line arguments Continued arguments, %NULL terminated + filename="gio/gsubprocesslauncher.c" + line="725">Continued arguments, %NULL terminated @@ -112504,26 +117074,26 @@ On Windows, they should be in UTF-8. version="2.40" throws="1"> Creates a #GSubprocess given a provided array of arguments. - + filename="gio/gsubprocesslauncher.c" + line="764">Creates a #GSubprocess given a provided array of arguments. + A new #GSubprocess, or %NULL on error (and @error will be set) + filename="gio/gsubprocesslauncher.c" + line="773">A new #GSubprocess, or %NULL on error (and @error will be set) a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="766">a #GSubprocessLauncher Command line arguments + filename="gio/gsubprocesslauncher.c" + line="767">Command line arguments @@ -112532,8 +117102,8 @@ On Windows, they should be in UTF-8. Transfer an arbitrary file descriptor from parent process to the + filename="gio/gsubprocesslauncher.c" + line="598">Transfer an arbitrary file descriptor from parent process to the child. This function takes ownership of the @source_fd; it will be closed in the parent when @self is freed. @@ -112545,27 +117115,27 @@ descriptor in the child. An example use case is GNUPG, which has a command line argument `--passphrase-fd` providing a file descriptor number where it expects the passphrase to be written. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="600">a #GSubprocessLauncher File descriptor in parent process + filename="gio/gsubprocesslauncher.c" + line="601">File descriptor in parent process Target descriptor for child process + filename="gio/gsubprocesslauncher.c" + line="602">Target descriptor for child process @@ -112574,8 +117144,8 @@ the passphrase to be written. c:identifier="g_subprocess_launcher_take_stderr_fd" version="2.40"> Sets the file descriptor to use as the stderr for spawned processes. + filename="gio/gsubprocesslauncher.c" + line="566">Sets the file descriptor to use as the stderr for spawned processes. If @fd is -1 then any previously given fd is unset. @@ -112591,21 +117161,21 @@ You may not set a stderr fd if a stderr file path is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="568">a #GSubprocessLauncher a file descriptor, or -1 + filename="gio/gsubprocesslauncher.c" + line="569">a file descriptor, or -1 @@ -112614,8 +117184,8 @@ This feature is only available on UNIX. c:identifier="g_subprocess_launcher_take_stdin_fd" version="2.40"> Sets the file descriptor to use as the stdin for spawned processes. + filename="gio/gsubprocesslauncher.c" + line="436">Sets the file descriptor to use as the stdin for spawned processes. If @fd is -1 then any previously given fd is unset. @@ -112633,21 +117203,21 @@ You may not set a stdin fd if a stdin file path is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="438">a #GSubprocessLauncher a file descriptor, or -1 + filename="gio/gsubprocesslauncher.c" + line="439">a file descriptor, or -1 @@ -112656,8 +117226,8 @@ This feature is only available on UNIX. c:identifier="g_subprocess_launcher_take_stdout_fd" version="2.40"> Sets the file descriptor to use as the stdout for spawned processes. + filename="gio/gsubprocesslauncher.c" + line="500">Sets the file descriptor to use as the stdout for spawned processes. If @fd is -1 then any previously given fd is unset. @@ -112674,21 +117244,21 @@ You may not set a stdout fd if a stdout file path is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="502">a #GSubprocessLauncher a file descriptor, or -1 + filename="gio/gsubprocesslauncher.c" + line="503">a file descriptor, or -1 @@ -112697,43 +117267,47 @@ This feature is only available on UNIX. c:identifier="g_subprocess_launcher_unsetenv" version="2.40"> Removes the environment variable @variable from the environment of + filename="gio/gsubprocesslauncher.c" + line="280">Removes the environment variable @variable from the environment of processes launched from this launcher. On UNIX, the variable's name can be an arbitrary byte string not containing '='. On Windows, it should be in UTF-8. - + a #GSubprocessLauncher + filename="gio/gsubprocesslauncher.c" + line="282">a #GSubprocessLauncher the environment variable to unset, + filename="gio/gsubprocesslauncher.c" + line="283">the environment variable to unset, must not contain '=' + [flags@Gio.SubprocessFlags] for launched processes. - + @@ -112742,7 +117316,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112751,7 +117325,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112760,7 +117334,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112769,7 +117343,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112778,7 +117352,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112787,7 +117361,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112796,7 +117370,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112805,7 +117379,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112814,7 +117388,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112823,7 +117397,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112832,7 +117406,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112841,7 +117415,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112850,7 +117424,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112859,7 +117433,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112868,7 +117442,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112877,7 +117451,7 @@ containing '='. On Windows, it should be in UTF-8. - + @@ -112887,16 +117461,16 @@ containing '='. On Windows, it should be in UTF-8. value="gio-tls-backend" c:type="G_TLS_BACKEND_EXTENSION_POINT_NAME"> Extension point for TLS functionality via #GTlsBackend. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -112905,7 +117479,7 @@ See [Extending GIO][extending-gio]. - + @@ -112914,7 +117488,7 @@ See [Extending GIO][extending-gio]. - + @@ -112923,7 +117497,7 @@ See [Extending GIO][extending-gio]. - + @@ -112932,7 +117506,7 @@ See [Extending GIO][extending-gio]. - + @@ -112941,7 +117515,7 @@ See [Extending GIO][extending-gio]. - + @@ -112950,7 +117524,7 @@ See [Extending GIO][extending-gio]. - + @@ -112959,7 +117533,7 @@ See [Extending GIO][extending-gio]. - + @@ -112968,7 +117542,7 @@ See [Extending GIO][extending-gio]. - + @@ -112977,7 +117551,7 @@ See [Extending GIO][extending-gio]. - + @@ -112986,7 +117560,7 @@ See [Extending GIO][extending-gio]. - + @@ -112995,7 +117569,7 @@ See [Extending GIO][extending-gio]. - + @@ -113005,26 +117579,26 @@ See [Extending GIO][extending-gio]. value="1.3.6.1.5.5.7.3.2" c:type="G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT"> The purpose used to verify the client certificate in a TLS connection. + filename="gio/gtlsdatabase.c" + line="102">The purpose used to verify the client certificate in a TLS connection. Used by TLS servers. - + The purpose used to verify the server certificate in a TLS connection. This + filename="gio/gtlsdatabase.c" + line="95">The purpose used to verify the server certificate in a TLS connection. This is the most common purpose in use. Used by TLS clients. - + - + @@ -113033,7 +117607,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113042,7 +117616,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113051,7 +117625,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113060,7 +117634,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113069,7 +117643,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113078,7 +117652,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113087,7 +117661,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113096,7 +117670,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113105,7 +117679,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113114,7 +117688,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113123,7 +117697,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113132,7 +117706,7 @@ is the most common purpose in use. Used by TLS clients. - + @@ -113146,515 +117720,517 @@ is the most common purpose in use. Used by TLS clients. glib:get-type="g_task_get_type" glib:type-struct="TaskClass"> A #GTask represents and manages a cancellable "task". + filename="gio/gtask.c" + line="35">A `GTask` represents and manages a cancellable ‘task’. ## Asynchronous operations -The most common usage of #GTask is as a #GAsyncResult, to +The most common usage of `GTask` is as a [iface@Gio.AsyncResult], to manage data during an asynchronous operation. You call -g_task_new() in the "start" method, followed by -g_task_set_task_data() and the like if you need to keep some +[ctor@Gio.Task.new] in the ‘start’ method, followed by +[method@Gio.Task.set_task_data] and the like if you need to keep some additional data associated with the task, and then pass the task object around through your asynchronous operation. Eventually, you will call a method such as -g_task_return_pointer() or g_task_return_error(), which will -save the value you give it and then invoke the task's callback -function in the -[thread-default main context][g-main-context-push-thread-default] +[method@Gio.Task.return_pointer] or [method@Gio.Task.return_error], which +will save the value you give it and then invoke the task’s callback +function in the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) where it was created (waiting until the next iteration of the main -loop first, if necessary). The caller will pass the #GTask back to -the operation's finish function (as a #GAsyncResult), and you can -use g_task_propagate_pointer() or the like to extract the +loop first, if necessary). The caller will pass the `GTask` back to +the operation’s finish function (as a [iface@Gio.AsyncResult]), and you can +use [method@Gio.Task.propagate_pointer] or the like to extract the return value. -Using #GTask requires the thread-default #GMainContext from when the -#GTask was constructed to be running at least until the task has completed -and its data has been freed. +Using `GTask` requires the thread-default [struct@GLib.MainContext] from when +the `GTask` was constructed to be running at least until the task has +completed and its data has been freed. -If a #GTask has been constructed and its callback set, it is an error to +If a `GTask` has been constructed and its callback set, it is an error to not call `g_task_return_*()` on it. GLib will warn at runtime if this happens (since 2.76). -Here is an example for using GTask as a GAsyncResult: -|[<!-- language="C" --> - typedef struct { - CakeFrostingType frosting; - char *message; - } DecorationData; +Here is an example for using `GTask` as a [iface@Gio.AsyncResult]: +```c +typedef struct { + CakeFrostingType frosting; + char *message; +} DecorationData; + +static void +decoration_data_free (DecorationData *decoration) +{ + g_free (decoration->message); + g_slice_free (DecorationData, decoration); +} + +static void +baked_cb (Cake *cake, + gpointer user_data) +{ + GTask *task = user_data; + DecorationData *decoration = g_task_get_task_data (task); + GError *error = NULL; - static void - decoration_data_free (DecorationData *decoration) + if (cake == NULL) { - g_free (decoration->message); - g_slice_free (DecorationData, decoration); + g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + "Go to the supermarket"); + g_object_unref (task); + return; } - static void - baked_cb (Cake *cake, - gpointer user_data) + if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) { - GTask *task = user_data; - DecorationData *decoration = g_task_get_task_data (task); - GError *error = NULL; + g_object_unref (cake); + // g_task_return_error() takes ownership of error + g_task_return_error (task, error); + g_object_unref (task); + return; + } - if (cake == NULL) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - g_object_unref (task); - return; - } + g_task_return_pointer (task, cake, g_object_unref); + g_object_unref (task); +} - if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) - { - g_object_unref (cake); - // g_task_return_error() takes ownership of error - g_task_return_error (task, error); - g_object_unref (task); - return; - } +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + GTask *task; + DecorationData *decoration; + Cake *cake; - g_task_return_pointer (task, cake, g_object_unref); + task = g_task_new (self, cancellable, callback, user_data); + if (radius < 3) + { + g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, + "%ucm radius cakes are silly", + radius); g_object_unref (task); + return; } - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); + if (cake != NULL) { - GTask *task; - DecorationData *decoration; - Cake *cake; - - task = g_task_new (self, cancellable, callback, user_data); - if (radius < 3) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, - "%ucm radius cakes are silly", - radius); - g_object_unref (task); - return; - } - - cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); - if (cake != NULL) - { - // _baker_get_cached_cake() returns a reffed cake - g_task_return_pointer (task, cake, g_object_unref); - g_object_unref (task); - return; - } + // _baker_get_cached_cake() returns a reffed cake + g_task_return_pointer (task, cake, g_object_unref); + g_object_unref (task); + return; + } - decoration = g_slice_new (DecorationData); - decoration->frosting = frosting; - decoration->message = g_strdup (message); - g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); + decoration = g_slice_new (DecorationData); + decoration->frosting = frosting; + decoration->message = g_strdup (message); + g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); - _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); - } + _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); +} - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); +Cake * +baker_bake_cake_finish (Baker *self, + GAsyncResult *result, + GError **error) +{ + g_return_val_if_fail (g_task_is_valid (result, self), NULL); - return g_task_propagate_pointer (G_TASK (result), error); - } -]| + return g_task_propagate_pointer (G_TASK (result), error); +} +``` ## Chained asynchronous operations -#GTask also tries to simplify asynchronous operations that +`GTask` also tries to simplify asynchronous operations that internally chain together several smaller asynchronous -operations. g_task_get_cancellable(), g_task_get_context(), -and g_task_get_priority() allow you to get back the task's -#GCancellable, #GMainContext, and [I/O priority][io-priority] -when starting a new subtask, so you don't have to keep track -of them yourself. g_task_attach_source() simplifies the case +operations. [method@Gio.Task.get_cancellable], [method@Gio.Task.get_context], +and [method@Gio.Task.get_priority] allow you to get back the task’s +[class@Gio.Cancellable], [struct@GLib.MainContext], and +[I/O priority](iface.AsyncResult.html#io-priority) +when starting a new subtask, so you don’t have to keep track +of them yourself. [method@Gio.Task.attach_source] simplifies the case of waiting for a source to fire (automatically using the correct -#GMainContext and priority). +[struct@GLib.MainContext] and priority). Here is an example for chained asynchronous operations: - |[<!-- language="C" --> - typedef struct { - Cake *cake; - CakeFrostingType frosting; - char *message; - } BakingData; - - static void - decoration_data_free (BakingData *bd) - { - if (bd->cake) - g_object_unref (bd->cake); - g_free (bd->message); - g_slice_free (BakingData, bd); - } +```c +typedef struct { + Cake *cake; + CakeFrostingType frosting; + char *message; +} BakingData; - static void - decorated_cb (Cake *cake, - GAsyncResult *result, - gpointer user_data) - { - GTask *task = user_data; - GError *error = NULL; +static void +decoration_data_free (BakingData *bd) +{ + if (bd->cake) + g_object_unref (bd->cake); + g_free (bd->message); + g_slice_free (BakingData, bd); +} - if (!cake_decorate_finish (cake, result, &error)) - { - g_object_unref (cake); - g_task_return_error (task, error); - g_object_unref (task); - return; - } +static void +decorated_cb (Cake *cake, + GAsyncResult *result, + gpointer user_data) +{ + GTask *task = user_data; + GError *error = NULL; - // baking_data_free() will drop its ref on the cake, so we have to - // take another here to give to the caller. - g_task_return_pointer (task, g_object_ref (cake), g_object_unref); + if (!cake_decorate_finish (cake, result, &error)) + { + g_object_unref (cake); + g_task_return_error (task, error); g_object_unref (task); + return; } - static gboolean - decorator_ready (gpointer user_data) - { - GTask *task = user_data; - BakingData *bd = g_task_get_task_data (task); - - cake_decorate_async (bd->cake, bd->frosting, bd->message, - g_task_get_cancellable (task), - decorated_cb, task); + // baking_data_free() will drop its ref on the cake, so we have to + // take another here to give to the caller. + g_task_return_pointer (task, g_object_ref (cake), g_object_unref); + g_object_unref (task); +} - return G_SOURCE_REMOVE; - } +static gboolean +decorator_ready (gpointer user_data) +{ + GTask *task = user_data; + BakingData *bd = g_task_get_task_data (task); - static void - baked_cb (Cake *cake, - gpointer user_data) - { - GTask *task = user_data; - BakingData *bd = g_task_get_task_data (task); - GError *error = NULL; + cake_decorate_async (bd->cake, bd->frosting, bd->message, + g_task_get_cancellable (task), + decorated_cb, task); - if (cake == NULL) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - g_object_unref (task); - return; - } + return G_SOURCE_REMOVE; +} - bd->cake = cake; +static void +baked_cb (Cake *cake, + gpointer user_data) +{ + GTask *task = user_data; + BakingData *bd = g_task_get_task_data (task); + GError *error = NULL; - // Bail out now if the user has already cancelled - if (g_task_return_error_if_cancelled (task)) - { - g_object_unref (task); - return; - } + if (cake == NULL) + { + g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + "Go to the supermarket"); + g_object_unref (task); + return; + } - if (cake_decorator_available (cake)) - decorator_ready (task); - else - { - GSource *source; + bd->cake = cake; - source = cake_decorator_wait_source_new (cake); - // Attach @source to @task's GMainContext and have it call - // decorator_ready() when it is ready. - g_task_attach_source (task, source, decorator_ready); - g_source_unref (source); - } + // Bail out now if the user has already cancelled + if (g_task_return_error_if_cancelled (task)) + { + g_object_unref (task); + return; } - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - gint priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + if (cake_decorator_available (cake)) + decorator_ready (task); + else { - GTask *task; - BakingData *bd; + GSource *source; - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_priority (task, priority); + source = cake_decorator_wait_source_new (cake); + // Attach @source to @task’s GMainContext and have it call + // decorator_ready() when it is ready. + g_task_attach_source (task, source, decorator_ready); + g_source_unref (source); + } +} - bd = g_slice_new0 (BakingData); - bd->frosting = frosting; - bd->message = g_strdup (message); - g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + gint priority, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + GTask *task; + BakingData *bd; - _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); - } + task = g_task_new (self, cancellable, callback, user_data); + g_task_set_priority (task, priority); - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); + bd = g_slice_new0 (BakingData); + bd->frosting = frosting; + bd->message = g_strdup (message); + g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); - return g_task_propagate_pointer (G_TASK (result), error); - } -]| + _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); +} + +Cake * +baker_bake_cake_finish (Baker *self, + GAsyncResult *result, + GError **error) +{ + g_return_val_if_fail (g_task_is_valid (result, self), NULL); + + return g_task_propagate_pointer (G_TASK (result), error); +} +``` ## Asynchronous operations from synchronous ones -You can use g_task_run_in_thread() to turn a synchronous +You can use [method@Gio.Task.run_in_thread] to turn a synchronous operation into an asynchronous one, by running it in a thread. -When it completes, the result will be dispatched to the -[thread-default main context][g-main-context-push-thread-default] -where the #GTask was created. +When it completes, the result will be dispatched to the thread-default +main context (see [method@GLib.MainContext.push_thread_default]) +where the `GTask` was created. Running a task in a thread: - |[<!-- language="C" --> - typedef struct { - guint radius; - CakeFlavor flavor; - CakeFrostingType frosting; - char *message; - } CakeData; - - static void - cake_data_free (CakeData *cake_data) - { - g_free (cake_data->message); - g_slice_free (CakeData, cake_data); - } +```c +typedef struct { + guint radius; + CakeFlavor flavor; + CakeFrostingType frosting; + char *message; +} CakeData; - static void - bake_cake_thread (GTask *task, - gpointer source_object, - gpointer task_data, - GCancellable *cancellable) - { - Baker *self = source_object; - CakeData *cake_data = task_data; - Cake *cake; - GError *error = NULL; - - cake = bake_cake (baker, cake_data->radius, cake_data->flavor, - cake_data->frosting, cake_data->message, - cancellable, &error); - if (cake) - g_task_return_pointer (task, cake, g_object_unref); - else - g_task_return_error (task, error); - } +static void +cake_data_free (CakeData *cake_data) +{ + g_free (cake_data->message); + g_slice_free (CakeData, cake_data); +} - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) - { - CakeData *cake_data; - GTask *task; - - cake_data = g_slice_new (CakeData); - cake_data->radius = radius; - cake_data->flavor = flavor; - cake_data->frosting = frosting; - cake_data->message = g_strdup (message); - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_run_in_thread (task, bake_cake_thread); - g_object_unref (task); - } +static void +bake_cake_thread (GTask *task, + gpointer source_object, + gpointer task_data, + GCancellable *cancellable) +{ + Baker *self = source_object; + CakeData *cake_data = task_data; + Cake *cake; + GError *error = NULL; + + cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + cake_data->frosting, cake_data->message, + cancellable, &error); + if (cake) + g_task_return_pointer (task, cake, g_object_unref); + else + g_task_return_error (task, error); +} - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + CakeData *cake_data; + GTask *task; - return g_task_propagate_pointer (G_TASK (result), error); - } -]| + cake_data = g_slice_new (CakeData); + cake_data->radius = radius; + cake_data->flavor = flavor; + cake_data->frosting = frosting; + cake_data->message = g_strdup (message); + task = g_task_new (self, cancellable, callback, user_data); + g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + g_task_run_in_thread (task, bake_cake_thread); + g_object_unref (task); +} + +Cake * +baker_bake_cake_finish (Baker *self, + GAsyncResult *result, + GError **error) +{ + g_return_val_if_fail (g_task_is_valid (result, self), NULL); + + return g_task_propagate_pointer (G_TASK (result), error); +} +``` ## Adding cancellability to uncancellable tasks -Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() -can be used to turn an uncancellable operation into a -cancellable one. If you call g_task_set_return_on_cancel(), -passing %TRUE, then if the task's #GCancellable is cancelled, -it will return control back to the caller immediately, while -allowing the task thread to continue running in the background -(and simply discarding its result when it finally does finish). +Finally, [method@Gio.Task.run_in_thread] and +[method@Gio.Task.run_in_thread_sync] can be used to turn an uncancellable +operation into a cancellable one. If you call +[method@Gio.Task.set_return_on_cancel], passing `TRUE`, then if the task’s +[class@Gio.Cancellable] is cancelled, it will return control back to the +caller immediately, while allowing the task thread to continue running in the +background (and simply discarding its result when it finally does finish). Provided that the task thread is careful about how it uses locks and other externally-visible resources, this allows you -to make "GLib-friendly" asynchronous and cancellable +to make ‘GLib-friendly’ asynchronous and cancellable synchronous variants of blocking APIs. Cancelling a task: - |[<!-- language="C" --> - static void - bake_cake_thread (GTask *task, - gpointer source_object, - gpointer task_data, - GCancellable *cancellable) +```c +static void +bake_cake_thread (GTask *task, + gpointer source_object, + gpointer task_data, + GCancellable *cancellable) +{ + Baker *self = source_object; + CakeData *cake_data = task_data; + Cake *cake; + GError *error = NULL; + + cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + cake_data->frosting, cake_data->message, + &error); + if (error) { - Baker *self = source_object; - CakeData *cake_data = task_data; - Cake *cake; - GError *error = NULL; - - cake = bake_cake (baker, cake_data->radius, cake_data->flavor, - cake_data->frosting, cake_data->message, - &error); - if (error) - { - g_task_return_error (task, error); - return; - } - - // If the task has already been cancelled, then we don't want to add - // the cake to the cake cache. Likewise, we don't want to have the - // task get cancelled in the middle of updating the cache. - // g_task_set_return_on_cancel() will return %TRUE here if it managed - // to disable return-on-cancel, or %FALSE if the task was cancelled - // before it could. - if (g_task_set_return_on_cancel (task, FALSE)) - { - // If the caller cancels at this point, their - // GAsyncReadyCallback won't be invoked until we return, - // so we don't have to worry that this code will run at - // the same time as that code does. But if there were - // other functions that might look at the cake cache, - // then we'd probably need a GMutex here as well. - baker_add_cake_to_cache (baker, cake); - g_task_return_pointer (task, cake, g_object_unref); - } + g_task_return_error (task, error); + return; } - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + // If the task has already been cancelled, then we don’t want to add + // the cake to the cake cache. Likewise, we don’t want to have the + // task get cancelled in the middle of updating the cache. + // g_task_set_return_on_cancel() will return %TRUE here if it managed + // to disable return-on-cancel, or %FALSE if the task was cancelled + // before it could. + if (g_task_set_return_on_cancel (task, FALSE)) { - CakeData *cake_data; - GTask *task; + // If the caller cancels at this point, their + // GAsyncReadyCallback won’t be invoked until we return, + // so we don’t have to worry that this code will run at + // the same time as that code does. But if there were + // other functions that might look at the cake cache, + // then we’d probably need a GMutex here as well. + baker_add_cake_to_cache (baker, cake); + g_task_return_pointer (task, cake, g_object_unref); + } +} - cake_data = g_slice_new (CakeData); +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + CakeData *cake_data; + GTask *task; - ... + cake_data = g_slice_new (CakeData); - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_set_return_on_cancel (task, TRUE); - g_task_run_in_thread (task, bake_cake_thread); - } + ... - Cake * - baker_bake_cake_sync (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GError **error) - { - CakeData *cake_data; - GTask *task; - Cake *cake; + task = g_task_new (self, cancellable, callback, user_data); + g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + g_task_set_return_on_cancel (task, TRUE); + g_task_run_in_thread (task, bake_cake_thread); +} - cake_data = g_slice_new (CakeData); +Cake * +baker_bake_cake_sync (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GError **error) +{ + CakeData *cake_data; + GTask *task; + Cake *cake; - ... + cake_data = g_slice_new (CakeData); - task = g_task_new (self, cancellable, NULL, NULL); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_set_return_on_cancel (task, TRUE); - g_task_run_in_thread_sync (task, bake_cake_thread); + ... - cake = g_task_propagate_pointer (task, error); - g_object_unref (task); - return cake; - } -]| + task = g_task_new (self, cancellable, NULL, NULL); + g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + g_task_set_return_on_cancel (task, TRUE); + g_task_run_in_thread_sync (task, bake_cake_thread); -## Porting from GSimpleAsyncResult + cake = g_task_propagate_pointer (task, error); + g_object_unref (task); + return cake; +} +``` + +## Porting from [class@Gio.SimpleAsyncResult] -#GTask's API attempts to be simpler than #GSimpleAsyncResult's +`GTask`’s API attempts to be simpler than [class@Gio.SimpleAsyncResult]’s in several ways: -- You can save task-specific data with g_task_set_task_data(), and - retrieve it later with g_task_get_task_data(). This replaces the - abuse of g_simple_async_result_set_op_res_gpointer() for the same - purpose with #GSimpleAsyncResult. -- In addition to the task data, #GTask also keeps track of the - [priority][io-priority], #GCancellable, and - #GMainContext associated with the task, so tasks that consist of - a chain of simpler asynchronous operations will have easy access + +- You can save task-specific data with [method@Gio.Task.set_task_data], and + retrieve it later with [method@Gio.Task.get_task_data]. This replaces the + abuse of [method@Gio.SimpleAsyncResult.set_op_res_gpointer] for the same + purpose with [class@Gio.SimpleAsyncResult]. +- In addition to the task data, `GTask` also keeps track of the + [priority](iface.AsyncResult.html#io-priority), [class@Gio.Cancellable], + and [struct@GLib.MainContext] associated with the task, so tasks that + consist of a chain of simpler asynchronous operations will have easy access to those values when starting each sub-task. -- g_task_return_error_if_cancelled() provides simplified +- [method@Gio.Task.return_error_if_cancelled] provides simplified handling for cancellation. In addition, cancellation - overrides any other #GTask return value by default, like - #GSimpleAsyncResult does when - g_simple_async_result_set_check_cancellable() is called. - (You can use g_task_set_check_cancellable() to turn off that - behavior.) On the other hand, g_task_run_in_thread() + overrides any other `GTask` return value by default, like + [class@Gio.SimpleAsyncResult] does when + [method@Gio.SimpleAsyncResult.set_check_cancellable] is called. + (You can use [method@Gio.Task.set_check_cancellable] to turn off that + behavior.) On the other hand, [method@Gio.Task.run_in_thread] guarantees that it will always run your - `task_func`, even if the task's #GCancellable + `task_func`, even if the task’s [class@Gio.Cancellable] is already cancelled before the task gets a chance to run; you can start your `task_func` with a - g_task_return_error_if_cancelled() check if you need the + [method@Gio.Task.return_error_if_cancelled] check if you need the old behavior. -- The "return" methods (eg, g_task_return_pointer()) - automatically cause the task to be "completed" as well, and - there is no need to worry about the "complete" vs "complete - in idle" distinction. (#GTask automatically figures out - whether the task's callback can be invoked directly, or - if it needs to be sent to another #GMainContext, or delayed - until the next iteration of the current #GMainContext.) -- The "finish" functions for #GTask based operations are generally - much simpler than #GSimpleAsyncResult ones, normally consisting - of only a single call to g_task_propagate_pointer() or the like. - Since g_task_propagate_pointer() "steals" the return value from - the #GTask, it is not necessary to juggle pointers around to +- The ‘return’ methods (eg, [method@Gio.Task.return_pointer]) + automatically cause the task to be ‘completed’ as well, and + there is no need to worry about the ‘complete’ vs ‘complete in idle’ + distinction. (`GTask` automatically figures out + whether the task’s callback can be invoked directly, or + if it needs to be sent to another [struct@GLib.MainContext], or delayed + until the next iteration of the current [struct@GLib.MainContext].) +- The ‘finish’ functions for `GTask` based operations are generally + much simpler than [class@Gio.SimpleAsyncResult] ones, normally consisting + of only a single call to [method@Gio.Task.propagate_pointer] or the like. + Since [method@Gio.Task.propagate_pointer] ‘steals’ the return value from + the `GTask`, it is not necessary to juggle pointers around to prevent it from being freed twice. -- With #GSimpleAsyncResult, it was common to call - g_simple_async_result_propagate_error() from the +- With [class@Gio.SimpleAsyncResult], it was common to call + [method@Gio.SimpleAsyncResult.propagate_error] from the `_finish()` wrapper function, and have virtual method implementations only deal with successful returns. This behavior is deprecated, because it makes it - difficult for a subclass to chain to a parent class's async + difficult for a subclass to chain to a parent class’s async methods. Instead, the wrapper function should just be a simple wrapper, and the virtual method should call an appropriate `g_task_propagate_` function. Note that wrapper methods can now use - g_async_result_legacy_propagate_error() to do old-style - #GSimpleAsyncResult error-returning behavior, and - g_async_result_is_tagged() to check if a result is tagged as + [method@Gio.AsyncResult.legacy_propagate_error] to do old-style + [class@Gio.SimpleAsyncResult] error-returning behavior, and + [method@Gio.AsyncResult.is_tagged] to check if a result is tagged as having come from the `_async()` wrapper - function (for "short-circuit" results, such as when passing - 0 to g_input_stream_read_async()). + function (for ‘short-circuit’ results, such as when passing + `0` to [method@Gio.InputStream.read_async]). ## Thread-safety considerations Due to some infelicities in the API design, there is a -thread-safety concern that users of GTask have to be aware of: +thread-safety concern that users of `GTask` have to be aware of: If the `main` thread drops its last reference to the source object or the task data before the task is finalized, then the finalizers @@ -113664,18 +118240,17 @@ This is a problem if the finalizers use non-threadsafe API, and can lead to hard-to-debug crashes. Possible workarounds include: - Clear task data in a signal handler for `notify::completed` - - Keep iterating a main context in the main thread and defer dropping the reference to the source object to that main context when the task is finalized - + Creates a #GTask acting on @source_object, which will eventually be -used to invoke @callback in the current -[thread-default main context][g-main-context-push-thread-default]. + filename="gio/gtask.c" + line="790">Creates a #GTask acting on @source_object, which will eventually be +used to invoke @callback in the current thread-default main context +(see [method@GLib.MainContext.push_thread_default]). Call this in the "start" method of your asynchronous method, and pass the #GTask around throughout the asynchronous operation. You @@ -113689,11 +118264,11 @@ simplified handling in cases where cancellation may imply that other objects that the task depends on have been destroyed. If you do not want this behavior, you can use g_task_set_check_cancellable() to change it. - + a #GTask. + filename="gio/gtask.c" + line="815">a #GTask. @@ -113702,8 +118277,8 @@ g_task_set_check_cancellable() to change it. nullable="1" allow-none="1"> the #GObject that owns + filename="gio/gtask.c" + line="792">the #GObject that owns this task, or %NULL. @@ -113712,8 +118287,8 @@ g_task_set_check_cancellable() to change it. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gtask.c" + line="794">optional #GCancellable object, %NULL to ignore. scope="async" closure="3"> a #GAsyncReadyCallback. + filename="gio/gtask.c" + line="795">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gtask.c" + line="796">user data passed to @callback. Checks that @result is a #GTask, and that @source_object is its + filename="gio/gtask.c" + line="2337">Checks that @result is a #GTask, and that @source_object is its source object (or that @source_object is %NULL and @result has no source object). This can be used in g_return_if_fail() checks. - + %TRUE if @result and @source_object are valid, %FALSE + filename="gio/gtask.c" + line="2347">%TRUE if @result and @source_object are valid, %FALSE if not A #GAsyncResult + filename="gio/gtask.c" + line="2339">A #GAsyncResult nullable="1" allow-none="1"> the source object + filename="gio/gtask.c" + line="2340">the source object expected to be associated with the task @@ -113775,8 +118350,8 @@ if not c:identifier="g_task_report_error" version="2.36"> Creates a #GTask and then immediately calls g_task_return_error() + filename="gio/gtask.c" + line="845">Creates a #GTask and then immediately calls g_task_return_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the finish method wrapper to @@ -113784,7 +118359,7 @@ check if the result there is tagged as having been created by the wrapper method, and deal with it appropriately if so. See also g_task_report_new_error(). - + @@ -113794,8 +118369,8 @@ See also g_task_report_new_error(). nullable="1" allow-none="1"> the #GObject that owns + filename="gio/gtask.c" + line="847">the #GObject that owns this task, or %NULL. @@ -113806,8 +118381,8 @@ See also g_task_report_new_error(). scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gtask.c" + line="849">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gtask.c" + line="850">user data passed to @callback. nullable="1" allow-none="1"> an opaque pointer indicating the source of this task + filename="gio/gtask.c" + line="851">an opaque pointer indicating the source of this task error to report + filename="gio/gtask.c" + line="852">error to report @@ -113841,8 +118416,8 @@ See also g_task_report_new_error(). version="2.36" introspectable="0"> Creates a #GTask and then immediately calls + filename="gio/gtask.c" + line="881">Creates a #GTask and then immediately calls g_task_return_new_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the @@ -113851,7 +118426,7 @@ having been created by the wrapper method, and deal with it appropriately if so. See also g_task_report_error(). - + @@ -113861,8 +118436,8 @@ See also g_task_report_error(). nullable="1" allow-none="1"> the #GObject that owns + filename="gio/gtask.c" + line="883">the #GObject that owns this task, or %NULL. @@ -113873,8 +118448,8 @@ See also g_task_report_error(). scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gtask.c" + line="885">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gtask.c" + line="886">user data passed to @callback. nullable="1" allow-none="1"> an opaque pointer indicating the source of this task + filename="gio/gtask.c" + line="887">an opaque pointer indicating the source of this task a #GQuark. + filename="gio/gtask.c" + line="888">a #GQuark. an error code. + filename="gio/gtask.c" + line="889">an error code. a string with format characters. + filename="gio/gtask.c" + line="890">a string with format characters. a list of values to insert into @format. + filename="gio/gtask.c" + line="891">a list of values to insert into @format. @@ -113926,38 +118501,39 @@ See also g_task_report_error(). version="2.36" introspectable="0"> A utility function for dealing with async operations where you need + filename="gio/gtask.c" + line="1774">A utility function for dealing with async operations where you need to wait for a #GSource to trigger. Attaches @source to @task's -#GMainContext with @task's [priority][io-priority], and sets @source's -callback to @callback, with @task as the callback's `user_data`. +#GMainContext with @task's [priority](iface.AsyncResult.html#io-priority), +and sets @source's callback to @callback, with @task as the callback's +`user_data`. It will set the @source’s name to the task’s name (as set with g_task_set_name()), if one has been set on the task and the source doesn’t yet have a name. This takes a reference on @task until @source is destroyed. - + a #GTask + filename="gio/gtask.c" + line="1776">a #GTask the source to attach + filename="gio/gtask.c" + line="1777">the source to attach the callback to invoke when @source triggers + filename="gio/gtask.c" + line="1778">the callback to invoke when @source triggers @@ -113966,20 +118542,20 @@ This takes a reference on @task until @source is destroyed. c:identifier="g_task_get_cancellable" version="2.36"> Gets @task's #GCancellable - + filename="gio/gtask.c" + line="1264">Gets @task's #GCancellable + @task's #GCancellable + filename="gio/gtask.c" + line="1270">@task's #GCancellable a #GTask + filename="gio/gtask.c" + line="1266">a #GTask @@ -113988,18 +118564,18 @@ This takes a reference on @task until @source is destroyed. c:identifier="g_task_get_check_cancellable" version="2.36"> Gets @task's check-cancellable flag. See + filename="gio/gtask.c" + line="1282">Gets @task's check-cancellable flag. See g_task_set_check_cancellable() for more details. - + the #GTask + filename="gio/gtask.c" + line="1284">the #GTask @@ -114009,22 +118585,22 @@ g_task_set_check_cancellable() for more details. glib:get-property="completed" version="2.44"> Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after + filename="gio/gtask.c" + line="2316">Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after the task’s callback is invoked, and will return %FALSE if called from inside the callback. - + %TRUE if the task has completed, %FALSE otherwise. + filename="gio/gtask.c" + line="2324">%TRUE if the task has completed, %FALSE otherwise. a #GTask. + filename="gio/gtask.c" + line="2318">a #GTask. @@ -114033,46 +118609,46 @@ the callback. c:identifier="g_task_get_context" version="2.36"> Gets the #GMainContext that @task will return its result in (that -is, the context that was the -[thread-default main context][g-main-context-push-thread-default] + filename="gio/gtask.c" + line="1240">Gets the #GMainContext that @task will return its result in (that +is, the context that was the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) at the point when @task was created). This will always return a non-%NULL value, even if the task's context is the default #GMainContext. - + @task's #GMainContext + filename="gio/gtask.c" + line="1252">@task's #GMainContext a #GTask + filename="gio/gtask.c" + line="1242">a #GTask Gets @task’s name. See g_task_set_name(). - + filename="gio/gtask.c" + line="1336">Gets @task’s name. See g_task_set_name(). + @task’s name, or %NULL + filename="gio/gtask.c" + line="1342">@task’s name, or %NULL a #GTask + filename="gio/gtask.c" + line="1338">a #GTask @@ -114081,20 +118657,20 @@ context is the default #GMainContext. c:identifier="g_task_get_priority" version="2.36"> Gets @task's priority - + filename="gio/gtask.c" + line="1222">Gets @task's priority + @task's priority + filename="gio/gtask.c" + line="1228">@task's priority a #GTask + filename="gio/gtask.c" + line="1224">a #GTask @@ -114103,18 +118679,18 @@ context is the default #GMainContext. c:identifier="g_task_get_return_on_cancel" version="2.36"> Gets @task's return-on-cancel flag. See + filename="gio/gtask.c" + line="1300">Gets @task's return-on-cancel flag. See g_task_set_return_on_cancel() for more details. - + the #GTask + filename="gio/gtask.c" + line="1302">the #GTask @@ -114123,21 +118699,21 @@ g_task_set_return_on_cancel() for more details. c:identifier="g_task_get_source_object" version="2.36"> Gets the source object from @task. Like + filename="gio/gtask.c" + line="1174">Gets the source object from @task. Like g_async_result_get_source_object(), but does not ref the object. - + @task's source object, or %NULL + filename="gio/gtask.c" + line="1181">@task's source object, or %NULL a #GTask + filename="gio/gtask.c" + line="1176">a #GTask @@ -114146,20 +118722,20 @@ g_async_result_get_source_object(), but does not ref the object. c:identifier="g_task_get_source_tag" version="2.36"> Gets @task's source tag. See g_task_set_source_tag(). - + filename="gio/gtask.c" + line="1318">Gets @task's source tag. See g_task_set_source_tag(). + @task's source tag + filename="gio/gtask.c" + line="1324">@task's source tag a #GTask + filename="gio/gtask.c" + line="1320">a #GTask @@ -114168,40 +118744,40 @@ g_async_result_get_source_object(), but does not ref the object. c:identifier="g_task_get_task_data" version="2.36"> Gets @task's `task_data`. - + filename="gio/gtask.c" + line="1204">Gets @task's `task_data`. + @task's `task_data`. + filename="gio/gtask.c" + line="1210">@task's `task_data`. a #GTask + filename="gio/gtask.c" + line="1206">a #GTask Tests if @task resulted in an error. - + filename="gio/gtask.c" + line="2198">Tests if @task resulted in an error. + %TRUE if the task resulted in an error, %FALSE otherwise. + filename="gio/gtask.c" + line="2204">%TRUE if the task resulted in an error, %FALSE otherwise. a #GTask. + filename="gio/gtask.c" + line="2200">a #GTask. @@ -114211,26 +118787,26 @@ g_async_result_get_source_object(), but does not ref the object. version="2.36" throws="1"> Gets the result of @task as a #gboolean. + filename="gio/gtask.c" + line="1989">Gets the result of @task as a #gboolean. If the task resulted in an error, or was cancelled, then this will instead return %FALSE and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. - + the task result, or %FALSE on error + filename="gio/gtask.c" + line="2002">the task result, or %FALSE on error a #GTask. + filename="gio/gtask.c" + line="1991">a #GTask. @@ -114240,26 +118816,26 @@ error) to the caller, you may only call it once. version="2.36" throws="1"> Gets the result of @task as an integer (#gssize). + filename="gio/gtask.c" + line="1934">Gets the result of @task as an integer (#gssize). If the task resulted in an error, or was cancelled, then this will instead return -1 and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. - + the task result, or -1 on error + filename="gio/gtask.c" + line="1947">the task result, or -1 on error a #GTask. + filename="gio/gtask.c" + line="1936">a #GTask. @@ -114269,8 +118845,8 @@ error) to the caller, you may only call it once. version="2.36" throws="1"> Gets the result of @task as a pointer, and transfers ownership + filename="gio/gtask.c" + line="1877">Gets the result of @task as a pointer, and transfers ownership of that value to the caller. If the task resulted in an error, or was cancelled, then this will @@ -114278,18 +118854,18 @@ instead return %NULL and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. - + the task result, or %NULL on error + filename="gio/gtask.c" + line="1891">the task result, or %NULL on error a #GTask + filename="gio/gtask.c" + line="1879">a #GTask @@ -114299,8 +118875,8 @@ error) to the caller, you may only call it once. version="2.64" throws="1"> Gets the result of @task as a #GValue, and transfers ownership of + filename="gio/gtask.c" + line="2271">Gets the result of @task as a #GValue, and transfers ownership of that value to the caller. As with g_task_return_value(), this is a generic low-level method; g_task_propagate_pointer() and the like will usually be more useful for C code. @@ -114310,18 +118886,18 @@ instead set @error and return %FALSE. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. - + %TRUE if @task succeeded, %FALSE on error. + filename="gio/gtask.c" + line="2288">%TRUE if @task succeeded, %FALSE on error. a #GTask + filename="gio/gtask.c" + line="2273">a #GTask caller-allocates="1" transfer-ownership="none"> return location for the #GValue + filename="gio/gtask.c" + line="2274">return location for the #GValue @@ -114339,25 +118915,25 @@ error) to the caller, you may only call it once. c:identifier="g_task_return_boolean" version="2.36"> Sets @task's result to @result and completes the task (see + filename="gio/gtask.c" + line="1966">Sets @task's result to @result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). - + a #GTask. + filename="gio/gtask.c" + line="1968">a #GTask. the #gboolean result of a task function. + filename="gio/gtask.c" + line="1969">the #gboolean result of a task function. @@ -114366,8 +118942,8 @@ means). c:identifier="g_task_return_error" version="2.36"> Sets @task's result to @error (which @task assumes ownership of) + filename="gio/gtask.c" + line="2021">Sets @task's result to @error (which @task assumes ownership of) and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). @@ -114377,22 +118953,23 @@ you cannot assume that @error is still valid after calling this. Call g_error_copy() on the error if you need to keep a local copy as well. -See also g_task_return_new_error(). - +See also [method@Gio.Task.return_new_error], +[method@Gio.Task.return_new_error_literal]. + a #GTask. + filename="gio/gtask.c" + line="2023">a #GTask. the #GError result of a task function. + filename="gio/gtask.c" + line="2024">the #GError result of a task function. @@ -114401,23 +118978,23 @@ See also g_task_return_new_error(). c:identifier="g_task_return_error_if_cancelled" version="2.36"> Checks if @task's #GCancellable has been cancelled, and if so, sets + filename="gio/gtask.c" + line="2162">Checks if @task's #GCancellable has been cancelled, and if so, sets @task's error accordingly and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). - + %TRUE if @task has been cancelled, %FALSE if not + filename="gio/gtask.c" + line="2171">%TRUE if @task has been cancelled, %FALSE if not a #GTask + filename="gio/gtask.c" + line="2164">a #GTask @@ -114426,25 +119003,25 @@ means). c:identifier="g_task_return_int" version="2.36"> Sets @task's result to @result and completes the task (see + filename="gio/gtask.c" + line="1911">Sets @task's result to @result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). - + a #GTask. + filename="gio/gtask.c" + line="1913">a #GTask. the integer (#gssize) result of a task function. + filename="gio/gtask.c" + line="1914">the integer (#gssize) result of a task function. @@ -114454,56 +119031,99 @@ means). version="2.36" introspectable="0"> Sets @task's result to a new #GError created from @domain, @code, + filename="gio/gtask.c" + line="2102">Sets @task's result to a new #GError created from @domain, @code, @format, and the remaining arguments, and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). See also g_task_return_error(). - + a #GTask. + filename="gio/gtask.c" + line="2104">a #GTask. a #GQuark. + filename="gio/gtask.c" + line="2105">a #GQuark. an error code. + filename="gio/gtask.c" + line="2106">an error code. a string with format characters. + filename="gio/gtask.c" + line="2107">a string with format characters. a list of values to insert into @format. + filename="gio/gtask.c" + line="2108">a list of values to insert into @format. + + Sets @task’s result to a new [type@GLib.Error] created from @domain, @code, +@message and completes the task. + +See [method@Gio.Task.return_pointer] for more discussion of exactly what +‘completing the task’ means. + +See also [method@Gio.Task.return_new_error]. + + + + + + + a #GTask. + + + + a #GQuark. + + + + an error code. + + + + an error message + + + + Sets @task's result to @result and completes the task. If @result + filename="gio/gtask.c" + line="1835">Sets @task's result to @result and completes the task. If @result is not %NULL, then @result_destroy will be used to free @result if the caller does not take ownership of it with g_task_propagate_pointer(). @@ -114521,15 +119141,15 @@ Note that since the task may be completed before returning from g_task_return_pointer(), you cannot assume that @result is still valid after calling this, unless you are still holding another reference on it. - + a #GTask + filename="gio/gtask.c" + line="1837">a #GTask nullable="1" allow-none="1"> the pointer result of a task + filename="gio/gtask.c" + line="1838">the pointer result of a task function @@ -114548,18 +119168,67 @@ reference on it. allow-none="1" scope="async"> a #GDestroyNotify function. + filename="gio/gtask.c" + line="1840">a #GDestroyNotify function. + + Sets @task's result to @error (which @task assumes ownership of), with +the message prefixed according to @format, and completes the task +(see g_task_return_pointer() for more discussion of exactly what this +means). + +Note that since the task takes ownership of @error, and since the +task may be completed before returning from g_task_return_prefixed_error(), +you cannot assume that @error is still valid after calling this. +Call g_error_copy() on the error if you need to keep a local copy +as well. + +See also g_task_return_error(), g_prefix_error(). + + + + + + + a #GTask. + + + + the #GError result of a task function. + + + + a string with format characters. + + + + a list of values to insert into @format. + + + + Sets @task's result to @result (by copying it) and completes the task. + filename="gio/gtask.c" + line="2229">Sets @task's result to @result (by copying it) and completes the task. If @result is %NULL then a #GValue of type %G_TYPE_POINTER with a value of %NULL will be used for the result. @@ -114567,15 +119236,15 @@ with a value of %NULL will be used for the result. This is a very generic low-level method intended primarily for use by language bindings; for C code, g_task_return_pointer() and the like will normally be much easier to use. - + a #GTask + filename="gio/gtask.c" + line="2231">a #GTask nullable="1" allow-none="1"> the #GValue result of + filename="gio/gtask.c" + line="2232">the #GValue result of a task function @@ -114594,8 +119263,8 @@ like will normally be much easier to use. c:identifier="g_task_run_in_thread" version="2.36"> Runs @task_func in another thread. When @task_func returns, @task's + filename="gio/gtask.c" + line="1673">Runs @task_func in another thread. When @task_func returns, @task's #GAsyncReadyCallback will be invoked in @task's #GMainContext. This takes a ref on @task until the task completes. @@ -114614,21 +119283,21 @@ and enough of them (around 10) execute in a dependency chain, as that will exhaust the thread pool. If this situation is possible, consider using a separate worker thread or thread pool explicitly, rather than using g_task_run_in_thread(). - + a #GTask + filename="gio/gtask.c" + line="1675">a #GTask a #GTaskThreadFunc + filename="gio/gtask.c" + line="1676">a #GTaskThreadFunc @@ -114637,8 +119306,8 @@ g_task_run_in_thread(). c:identifier="g_task_run_in_thread_sync" version="2.36"> Runs @task_func in another thread, and waits for it to return or be + filename="gio/gtask.c" + line="1723">Runs @task_func in another thread, and waits for it to return or be cancelled. You can use g_task_propagate_pointer(), etc, afterward to get the result of @task_func. @@ -114654,21 +119323,21 @@ g_task_run_in_thread_sync(), you should not assume that it will always do this. If you have a very large number of tasks to run, but don't want them to all run at once, you should only queue a limited number of them at a time. - + a #GTask + filename="gio/gtask.c" + line="1725">a #GTask a #GTaskThreadFunc + filename="gio/gtask.c" + line="1726">a #GTaskThreadFunc @@ -114677,8 +119346,8 @@ limited number of them at a time. c:identifier="g_task_set_check_cancellable" version="2.36"> Sets or clears @task's check-cancellable flag. If this is %TRUE + filename="gio/gtask.c" + line="978">Sets or clears @task's check-cancellable flag. If this is %TRUE (the default), then g_task_propagate_pointer(), etc, and g_task_had_error() will check the task's #GCancellable first, and if it has been cancelled, then they will consider the task to have @@ -114692,21 +119361,21 @@ via g_task_return_error_if_cancelled()). If you are using g_task_set_return_on_cancel() as well, then you must leave check-cancellable set %TRUE. - + the #GTask + filename="gio/gtask.c" + line="980">the #GTask whether #GTask will check the state of + filename="gio/gtask.c" + line="981">whether #GTask will check the state of its #GCancellable for you. @@ -114714,8 +119383,8 @@ you must leave check-cancellable set %TRUE. Sets @task’s name, used in debugging and profiling. The name defaults to + filename="gio/gtask.c" + line="1116">Sets @task’s name, used in debugging and profiling. The name defaults to %NULL. The task name should describe in a human readable way what the task does. @@ -114723,17 +119392,16 @@ For example, ‘Open file’ or ‘Connect to network host’. It is used to set name of the #GSource used for idle completion of the task. This function may only be called before the @task is first used in a thread -other than the one it was constructed in. It is called automatically by -g_task_set_source_tag() if not called already. - +other than the one it was constructed in. + a #GTask + filename="gio/gtask.c" + line="1118">a #GTask nullable="1" allow-none="1"> a human readable name for the task, or %NULL to unset it + filename="gio/gtask.c" + line="1119">a human readable name for the task, or %NULL to unset it @@ -114751,29 +119419,29 @@ g_task_set_source_tag() if not called already. c:identifier="g_task_set_priority" version="2.36"> Sets @task's priority. If you do not call this, it will default to + filename="gio/gtask.c" + line="952">Sets @task's priority. If you do not call this, it will default to %G_PRIORITY_DEFAULT. This will affect the priority of #GSources created with g_task_attach_source() and the scheduling of tasks run in threads, and can also be explicitly retrieved later via g_task_get_priority(). - + the #GTask + filename="gio/gtask.c" + line="954">the #GTask the [priority][io-priority] of the request + filename="gio/gtask.c" + line="955">the [priority](iface.AsyncResult.html#io-priority) of the request @@ -114782,8 +119450,8 @@ g_task_get_priority(). c:identifier="g_task_set_return_on_cancel" version="2.36"> Sets or clears @task's return-on-cancel flag. This is only + filename="gio/gtask.c" + line="1013">Sets or clears @task's return-on-cancel flag. This is only meaningful for tasks run via g_task_run_in_thread() or g_task_run_in_thread_sync(). @@ -114811,11 +119479,11 @@ If the task's #GCancellable is already cancelled before you call g_task_run_in_thread()/g_task_run_in_thread_sync(), then the #GTaskThreadFunc will still be run (for consistency), but the task will also be completed right away. - + %TRUE if @task's return-on-cancel flag was changed to + filename="gio/gtask.c" + line="1048">%TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled. @@ -114823,14 +119491,14 @@ will also be completed right away. the #GTask + filename="gio/gtask.c" + line="1015">the #GTask whether the task returns automatically when + filename="gio/gtask.c" + line="1016">whether the task returns automatically when it is cancelled. @@ -114840,8 +119508,8 @@ will also be completed right away. c:identifier="g_task_set_source_tag" version="2.36"> Sets @task's source tag. + filename="gio/gtask.c" + line="1085">Sets @task's source tag. You can use this to tag a task return value with a particular pointer (usually a pointer to the function @@ -114853,15 +119521,15 @@ particular place. A macro wrapper around this function will automatically set the task’s name to the string form of @source_tag if it’s not already set, for convenience. - + the #GTask + filename="gio/gtask.c" + line="1087">the #GTask nullable="1" allow-none="1"> an opaque pointer indicating the source of this task + filename="gio/gtask.c" + line="1088">an opaque pointer indicating the source of this task @@ -114879,19 +119547,22 @@ set, for convenience. c:identifier="g_task_set_static_name" version="2.76"> Sets @task’s name, used in debugging and profiling. + filename="gio/gtask.c" + line="1148">Sets @task’s name, used in debugging and profiling. -This is a variant of g_task_set_name() that avoids copying @name. - +This is a variant of g_task_set_name() that avoids copying @name. + +This function is called automatically by [method@Gio.Task.set_source_tag] +unless a name is set. + a #GTask + filename="gio/gtask.c" + line="1150">a #GTask nullable="1" allow-none="1"> a human readable name for the task. Must be a string literal + filename="gio/gtask.c" + line="1151">a human readable name for the task. Must be a string literal @@ -114909,17 +119580,17 @@ This is a variant of g_task_set_name() that avoids copying @name. c:identifier="g_task_set_task_data" version="2.36"> Sets @task's task data (freeing the existing task data, if any). - + filename="gio/gtask.c" + line="926">Sets @task's task data (freeing the existing task data, if any). + the #GTask + filename="gio/gtask.c" + line="928">the #GTask nullable="1" allow-none="1"> task-specific data + filename="gio/gtask.c" + line="929">task-specific data allow-none="1" scope="async"> #GDestroyNotify for @task_data + filename="gio/gtask.c" + line="930">#GDestroyNotify for @task_data @@ -114949,11 +119620,20 @@ This is a variant of g_task_set_name() that avoids copying @name. getter="get_completed" default-value="FALSE"> Whether the task has completed, meaning its callback (if set) has been -invoked. This can only happen after g_task_return_pointer(), + filename="gio/gtask.c" + line="2455">Whether the task has completed, meaning its callback (if set) has been +invoked. + +This can only happen after g_task_return_pointer(), g_task_return_error() or one of the other return functions have been called -on the task. +on the task. However, it is not guaranteed to happen immediately after +those functions are called, as the task’s callback may need to be scheduled +to run in a different thread. + +That means it is **not safe** to use this property to track whether a +return function has been called on the #GTask. Callers must do that +tracking themselves, typically by linking the lifetime of the #GTask to the +control flow of their code. This property is guaranteed to change from %FALSE to %TRUE exactly once. @@ -114967,12 +119647,12 @@ context as the task’s callback, immediately after that callback is invoked. - + The prototype for a task function to be run in a thread via + filename="gio/gtask.c" + line="1462">The prototype for a task function to be run in a thread via g_task_run_in_thread() or g_task_run_in_thread_sync(). If the return-on-cancel flag is set on @task, and @cancellable gets @@ -114987,21 +119667,21 @@ g_task_set_return_on_cancel() for more details. Other than in that case, @task will be completed when the #GTaskThreadFunc returns, not when it calls a `g_task_return_` function. - + the #GTask + filename="gio/gtask.c" + line="1464">the #GTask @task's source object + filename="gio/gtask.c" + line="1465">@task's source object @task's task data + filename="gio/gtask.c" + line="1466">@task's task data @task's #GCancellable, or %NULL + filename="gio/gtask.c" + line="1467">@task's #GCancellable, or %NULL @@ -115033,30 +119713,30 @@ Other than in that case, @task will be completed when the glib:get-type="g_tcp_connection_get_type" glib:type-struct="TcpConnectionClass"> This is the subclass of #GSocketConnection that is created + filename="gio/gtcpconnection.c" + line="15">This is the subclass of [class@Gio.SocketConnection] that is created for TCP/IP sockets. - + Checks if graceful disconnects are used. See + filename="gio/gtcpconnection.c" + line="321">Checks if graceful disconnects are used. See g_tcp_connection_set_graceful_disconnect(). - + %TRUE if graceful disconnect is used on close, %FALSE otherwise + filename="gio/gtcpconnection.c" + line="328">%TRUE if graceful disconnect is used on close, %FALSE otherwise a #GTcpConnection + filename="gio/gtcpconnection.c" + line="323">a #GTcpConnection @@ -115066,8 +119746,8 @@ g_tcp_connection_set_graceful_disconnect(). glib:set-property="graceful-disconnect" version="2.22"> This enables graceful disconnects on close. A graceful disconnect + filename="gio/gtcpconnection.c" + line="292">This enables graceful disconnects on close. A graceful disconnect means that we signal the receiving end that the connection is terminated and wait for it to close the connection before closing the connection. @@ -115076,31 +119756,35 @@ all the outstanding data to the other end, or get an error reported. However, it also means we have to wait for all the data to reach the other side and for it to acknowledge this by closing the socket, which may take a while. For this reason it is disabled by default. - + a #GTcpConnection + filename="gio/gtcpconnection.c" + line="294">a #GTcpConnection Whether to do graceful disconnects or not + filename="gio/gtcpconnection.c" + line="295">Whether to do graceful disconnects or not + Whether [method@Gio.IOStream.close] does a graceful disconnect. @@ -115113,7 +119797,7 @@ take a while. For this reason it is disabled by default. - + @@ -115122,7 +119806,7 @@ take a while. For this reason it is disabled by default. c:type="GTcpConnectionPrivate" disguised="1" opaque="1"> - + glib:get-type="g_tcp_wrapper_connection_get_type" glib:type-struct="TcpWrapperConnectionClass"> A #GTcpWrapperConnection can be used to wrap a #GIOStream that is -based on a #GSocket, but which is not actually a -#GSocketConnection. This is used by #GSocketClient so that it can -always return a #GSocketConnection, even when the connection it has -actually created is not directly a #GSocketConnection. - + filename="gio/gtcpwrapperconnection.c" + line="23">A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is +based on a [class@Gio.Socket], but which is not actually a +[class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so +that it can always return a [class@Gio.SocketConnection], even when the +connection it has actually created is not directly a +[class@Gio.SocketConnection]. + Wraps @base_io_stream and @socket together as a #GSocketConnection. - + filename="gio/gtcpwrapperconnection.c" + line="156">Wraps @base_io_stream and @socket together as a #GSocketConnection. + the new #GSocketConnection. + filename="gio/gtcpwrapperconnection.c" + line="163">the new #GSocketConnection. the #GIOStream to wrap + filename="gio/gtcpwrapperconnection.c" + line="158">the #GIOStream to wrap the #GSocket associated with @base_io_stream + filename="gio/gtcpwrapperconnection.c" + line="159">the #GSocket associated with @base_io_stream @@ -115172,29 +119857,33 @@ actually created is not directly a #GSocketConnection. c:identifier="g_tcp_wrapper_connection_get_base_io_stream" glib:get-property="base-io-stream"> Gets @conn's base #GIOStream - + filename="gio/gtcpwrapperconnection.c" + line="183">Gets @conn's base #GIOStream + @conn's base #GIOStream + filename="gio/gtcpwrapperconnection.c" + line="189">@conn's base #GIOStream a #GTcpWrapperConnection + filename="gio/gtcpwrapperconnection.c" + line="185">a #GTcpWrapperConnection + The wrapped [class@Gio.IOStream]. @@ -115208,7 +119897,7 @@ actually created is not directly a #GSocketConnection. - + @@ -115217,7 +119906,7 @@ actually created is not directly a #GSocketConnection. c:type="GTcpWrapperConnectionPrivate" disguised="1" opaque="1"> - + glib:type-name="GTestDBus" glib:get-type="g_test_dbus_get_type"> A helper class for testing code which uses D-Bus without touching the user's + filename="gio/gtestdbus.c" + line="335">A helper class for testing code which uses D-Bus without touching the user’s session bus. -Note that #GTestDBus modifies the user’s environment, calling setenv(). -This is not thread-safe, so all #GTestDBus calls should be completed before -threads are spawned, or should have appropriate locking to ensure no access -conflicts to environment variables shared between #GTestDBus and other -threads. +Note that `GTestDBus` modifies the user’s environment, calling +[`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus` +calls should be completed before threads are spawned, or should have +appropriate locking to ensure no access conflicts to environment variables +shared between `GTestDBus` and other threads. -## Creating unit tests using GTestDBus +## Creating unit tests using `GTestDBus` Testing of D-Bus services can be tricky because normally we only ever run D-Bus services over an existing instance of the D-Bus daemon thus we -usually don't activate D-Bus services that are not yet installed into the -target system. The #GTestDBus object makes this easier for us by taking care +usually don’t activate D-Bus services that are not yet installed into the +target system. The `GTestDBus` object makes this easier for us by taking care of the lower level tasks such as running a private D-Bus daemon and looking up uninstalled services in customizable locations, typically in your source code tree. @@ -115255,20 +119944,24 @@ The service file should list your service along with an absolute path to the uninstalled service executable in your source tree. Using autotools we would achieve this by adding a file such as `my-server.service.in` in the services directory and have it processed by configure. -|[ - [D-BUS Service] - Name=org.gtk.GDBus.Examples.ObjectManager - Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server -]| + +``` +[D-BUS Service] +Name=org.gtk.GDBus.Examples.ObjectManager +Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server +``` + You will also need to indicate this service directory in your test fixtures, so you will need to pass the path while compiling your test cases. Typically this is done with autotools with an added preprocessor flag specified to compile your tests such as: -|[ - -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" -]| - Once you have a service definition file which is local to your source tree, -you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. + +``` +-DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" +``` + +Once you have a service definition file which is local to your source tree, +you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding. An example of a test fixture for D-Bus services can be found here: @@ -115277,59 +119970,62 @@ here: Note that these examples only deal with isolating the D-Bus aspect of your service. To successfully run isolated unit tests on your service you may need some additional modifications to your test case fixture. For example; if your -service uses GSettings and installs a schema then it is important that your test service -not load the schema in the ordinary installed location (chances are that your service -and schema files are not yet installed, or worse; there is an older version of the -schema file sitting in the install location). +service uses [class@Gio.Settings] and installs a schema then it is important +that your test service not load the schema in the ordinary installed location +(chances are that your service and schema files are not yet installed, or +worse; there is an older version of the schema file sitting in the install +location). Most of the time we can work around these obstacles using the environment. Since the environment is inherited by the D-Bus daemon -created by #GTestDBus and then in turn inherited by any services the +created by `GTestDBus` and then in turn inherited by any services the D-Bus daemon activates, using the setup routine for your fixture is a practical place to help sandbox your runtime environment. For the rather typical GSettings case we can work around this by setting `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas -in the above fixture_setup() routine. +in the above `fixture_setup()` routine. -The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved -by compiling the schemas locally as a step before running test cases, an autotools setup might -do the following in the directory holding schemas: -|[ +The GSettings schemas need to be locally pre-compiled for this to work. This +can be achieved by compiling the schemas locally as a step before running +test cases, an autotools setup might do the following in the directory +holding schemas: + +``` all-am: $(GLIB_COMPILE_SCHEMAS) . CLEANFILES += gschemas.compiled -]| +``` Create a new #GTestDBus object. - + filename="gio/gtestdbus.c" + line="722">Create a new #GTestDBus object. + a new #GTestDBus. + filename="gio/gtestdbus.c" + line="728">a new #GTestDBus. a #GTestDBusFlags + filename="gio/gtestdbus.c" + line="724">a #GTestDBusFlags Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test + filename="gio/gtestdbus.c" + line="871">Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test won't use user's session bus. This is useful for unit tests that want to verify behaviour when no session bus is running. It is not necessary to call this if unit test already calls g_test_dbus_up() before acquiring the session bus. - + @@ -115337,45 +120033,45 @@ g_test_dbus_up() before acquiring the session bus. Add a path where dbus-daemon will look up .service files. This can't be + filename="gio/gtestdbus.c" + line="772">Add a path where dbus-daemon will look up .service files. This can't be called after g_test_dbus_up(). - + a #GTestDBus + filename="gio/gtestdbus.c" + line="774">a #GTestDBus path to a directory containing .service files + filename="gio/gtestdbus.c" + line="775">path to a directory containing .service files Stop the session bus started by g_test_dbus_up(). + filename="gio/gtestdbus.c" + line="838">Stop the session bus started by g_test_dbus_up(). This will wait for the singleton returned by g_bus_get() or g_bus_get_sync() to be destroyed. This is done to ensure that the next unit test won't get a leaked singleton from this test. - + a #GTestDBus + filename="gio/gtestdbus.c" + line="840">a #GTestDBus @@ -115383,22 +120079,22 @@ leaked singleton from this test. Get the address on which dbus-daemon is running. If g_test_dbus_up() has not + filename="gio/gtestdbus.c" + line="754">Get the address on which dbus-daemon is running. If g_test_dbus_up() has not been called yet, %NULL is returned. This can be used with g_dbus_connection_new_for_address(). - + the address of the bus, or %NULL. + filename="gio/gtestdbus.c" + line="762">the address of the bus, or %NULL. a #GTestDBus + filename="gio/gtestdbus.c" + line="756">a #GTestDBus @@ -115407,50 +120103,50 @@ g_dbus_connection_new_for_address(). c:identifier="g_test_dbus_get_flags" glib:get-property="flags"> Get the flags of the #GTestDBus object. - + filename="gio/gtestdbus.c" + line="738">Get the flags of the #GTestDBus object. + the value of #GTestDBus:flags property + filename="gio/gtestdbus.c" + line="744">the value of #GTestDBus:flags property a #GTestDBus + filename="gio/gtestdbus.c" + line="740">a #GTestDBus Stop the session bus started by g_test_dbus_up(). + filename="gio/gtestdbus.c" + line="818">Stop the session bus started by g_test_dbus_up(). Unlike g_test_dbus_down(), this won't verify the #GDBusConnection singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit tests wanting to verify behaviour after the session bus has been stopped can use this function but should still call g_test_dbus_down() when done. - + a #GTestDBus + filename="gio/gtestdbus.c" + line="820">a #GTestDBus Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this + filename="gio/gtestdbus.c" + line="790">Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this call, it is safe for unit tests to start sending messages on the session bus. If this function is called from setup callback of g_test_add(), @@ -115458,15 +120154,15 @@ g_test_dbus_down() must be called in its teardown callback. If this function is called from unit test's main(), then g_test_dbus_down() must be called after g_test_run(). - + a #GTestDBus + filename="gio/gtestdbus.c" + line="792">a #GTestDBus @@ -115479,8 +120175,8 @@ must be called after g_test_run(). getter="get_flags" default-value="G_TEST_DBUS_NONE"> #GTestDBusFlags specifying the behaviour of the D-Bus session. + filename="gio/gtestdbus.c" + line="528">#GTestDBusFlags specifying the behaviour of the D-Bus session. @@ -115490,16 +120186,16 @@ must be called after g_test_run(). glib:get-type="g_test_dbus_flags_get_type" c:type="GTestDBusFlags"> Flags to define future #GTestDBus behaviour. + filename="gio/gioenums.h" + line="1994">Flags to define future #GTestDBus behaviour. No flags. + filename="gio/gioenums.h" + line="1996">No flags. glib:get-type="g_themed_icon_get_type" glib:type-struct="ThemedIconClass"> #GThemedIcon is an implementation of #GIcon that supports icon themes. -#GThemedIcon contains a list of all of the icons present in an icon -theme, so that icons can be looked up quickly. #GThemedIcon does + filename="gio/gthemedicon.c" + line="33">`GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon +themes. + +`GThemedIcon` contains a list of all of the icons present in an icon +theme, so that icons can be looked up quickly. `GThemedIcon` does not provide actual pixmaps for icons, just the icon names. -Ideally something like gtk_icon_theme_choose_icon() should be used to +Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to resolve the list of names so that fallback icons work nicely with themes that inherit other themes. - + Creates a new themed icon for @iconname. - + filename="gio/gthemedicon.c" + line="356">Creates a new themed icon for @iconname. + a new #GThemedIcon. + filename="gio/gthemedicon.c" + line="362">a new #GThemedIcon. a string containing an icon name. + filename="gio/gthemedicon.c" + line="358">a string containing an icon name. @@ -115543,28 +120241,28 @@ themes that inherit other themes. Creates a new themed icon for @iconnames. - + filename="gio/gthemedicon.c" + line="372">Creates a new themed icon for @iconnames. + a new #GThemedIcon + filename="gio/gthemedicon.c" + line="380">a new #GThemedIcon an array of strings containing icon names. + filename="gio/gthemedicon.c" + line="374">an array of strings containing icon names. the length of the @iconnames array, or -1 if @iconnames is + filename="gio/gthemedicon.c" + line="375">the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated @@ -115573,8 +120271,8 @@ themes that inherit other themes. Creates a new themed icon for @iconname, and all the names + filename="gio/gthemedicon.c" + line="412">Creates a new themed icon for @iconname, and all the names that can be created by shortening @iconname at '-' characters. In the following example, @icon1 and @icon2 are equivalent: @@ -115589,44 +120287,44 @@ const char *names[] = { icon1 = g_themed_icon_new_from_names (names, 4); icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); ]| - + a new #GThemedIcon. + filename="gio/gthemedicon.c" + line="432">a new #GThemedIcon. a string containing an icon name + filename="gio/gthemedicon.c" + line="414">a string containing an icon name Append a name to the list of icons from within @icon. + filename="gio/gthemedicon.c" + line="458">Append a name to the list of icons from within @icon. Note that doing so invalidates the hash computed by prior calls to g_icon_hash(). - + a #GThemedIcon + filename="gio/gthemedicon.c" + line="460">a #GThemedIcon name of icon to append to list of icons from within @icon. + filename="gio/gthemedicon.c" + line="461">name of icon to append to list of icons from within @icon. @@ -115635,13 +120333,13 @@ to g_icon_hash(). c:identifier="g_themed_icon_get_names" glib:get-property="names"> Gets the names of icons from within @icon. - + filename="gio/gthemedicon.c" + line="443">Gets the names of icons from within @icon. + a list of icon names. + filename="gio/gthemedicon.c" + line="449">a list of icon names. @@ -115649,8 +120347,8 @@ to g_icon_hash(). a #GThemedIcon. + filename="gio/gthemedicon.c" + line="445">a #GThemedIcon. @@ -115659,26 +120357,26 @@ to g_icon_hash(). c:identifier="g_themed_icon_prepend_name" version="2.18"> Prepend a name to the list of icons from within @icon. + filename="gio/gthemedicon.c" + line="485">Prepend a name to the list of icons from within @icon. Note that doing so invalidates the hash computed by prior calls to g_icon_hash(). - + a #GThemedIcon + filename="gio/gthemedicon.c" + line="487">a #GThemedIcon name of icon to prepend to list of icons from within @icon. + filename="gio/gthemedicon.c" + line="488">name of icon to prepend to list of icons from within @icon. @@ -115690,8 +120388,8 @@ to g_icon_hash(). transfer-ownership="none" default-value="NULL"> The icon name. + filename="gio/gthemedicon.c" + line="176">The icon name. transfer-ownership="none" getter="get_names"> A %NULL-terminated array of icon names. + filename="gio/gthemedicon.c" + line="186">A %NULL-terminated array of icon names. @@ -115712,8 +120410,8 @@ to g_icon_hash(). transfer-ownership="none" default-value="FALSE"> Whether to use the default fallbacks found by shortening the icon name + filename="gio/gthemedicon.c" + line="196">Whether to use the default fallbacks found by shortening the icon name at '-' characters. If the "names" array has more than one element, ignores any past the first. @@ -115736,7 +120434,29 @@ would become disguised="1" opaque="1" glib:is-gtype-struct-for="ThemedIcon"> - + + + + #GThreadedResolver is an implementation of #GResolver which calls the libc +lookup functions in threads to allow them to run asynchronously. + + + + + + + A #GThreadedSocketService is a simple subclass of #GSocketService + filename="gio/gthreadedsocketservice.c" + line="25">A `GThreadedSocketService` is a simple subclass of [class@Gio.SocketService] that handles incoming connections by creating a worker thread and dispatching the connection to it by emitting the -#GThreadedSocketService::run signal in the new thread. +[signal@Gio.ThreadedSocketService::run signal] in the new thread. -The signal handler may perform blocking IO and need not return +The signal handler may perform blocking I/O and need not return until the connection is closed. The service is implemented using a thread pool, so there is a limited amount of threads available to serve incoming requests. -The service automatically stops the #GSocketService from accepting +The service automatically stops the [class@Gio.SocketService] from accepting new connections when all threads are busy. -As with #GSocketService, you may connect to #GThreadedSocketService::run, -or subclass and override the default handler. - +As with [class@Gio.SocketService], you may connect to +[signal@Gio.ThreadedSocketService::run], or subclass and override the default +handler. + Creates a new #GThreadedSocketService with no listeners. Listeners + filename="gio/gthreadedsocketservice.c" + line="265">Creates a new #GThreadedSocketService with no listeners. Listeners must be added with one of the #GSocketListener "add" methods. - + a new #GSocketService. + filename="gio/gthreadedsocketservice.c" + line="273">a new #GSocketService. the maximal number of threads to execute concurrently + filename="gio/gthreadedsocketservice.c" + line="267">the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit - + @@ -115807,10 +120528,14 @@ must be added with one of the #GSocketListener "add" methods. + The maximum number of threads handling clients for this service. @@ -115822,22 +120547,22 @@ must be added with one of the #GSocketListener "add" methods. The ::run signal is emitted in a worker thread in response to an + filename="gio/gthreadedsocketservice.c" + line="226">The ::run signal is emitted in a worker thread in response to an incoming connection. This thread is dedicated to handling @connection and may perform blocking IO. The signal handler need not return until the connection is closed. %TRUE to stop further signal handlers from being called + filename="gio/gthreadedsocketservice.c" + line="237">%TRUE to stop further signal handlers from being called a new #GSocketConnection object. + filename="gio/gthreadedsocketservice.c" + line="229">a new #GSocketConnection object. nullable="1" allow-none="1"> the source_object passed to g_socket_listener_add_address(). + filename="gio/gthreadedsocketservice.c" + line="230">the source_object passed to g_socket_listener_add_address(). @@ -115855,13 +120580,13 @@ not return until the connection is closed. - + - + @@ -115881,7 +120606,7 @@ not return until the connection is closed. - + @@ -115889,7 +120614,7 @@ not return until the connection is closed. - + @@ -115897,7 +120622,7 @@ not return until the connection is closed. - + @@ -115905,7 +120630,7 @@ not return until the connection is closed. - + @@ -115913,7 +120638,7 @@ not return until the connection is closed. - + @@ -115924,7 +120649,7 @@ not return until the connection is closed. c:type="GThreadedSocketServicePrivate" disguised="1" opaque="1"> - + glib:get-type="g_tls_authentication_mode_get_type" c:type="GTlsAuthenticationMode"> The client authentication mode for a #GTlsServerConnection. + filename="gio/gioenums.h" + line="1657">The client authentication mode for a #GTlsServerConnection. client authentication not required + filename="gio/gioenums.h" + line="1659">client authentication not required glib:nick="requested" glib:name="G_TLS_AUTHENTICATION_REQUESTED"> client authentication is requested + filename="gio/gioenums.h" + line="1660">client authentication is requested glib:nick="required" glib:name="G_TLS_AUTHENTICATION_REQUIRED"> client authentication is required + filename="gio/gioenums.h" + line="1661">client authentication is required glib:get-type="g_tls_backend_get_type" glib:type-struct="TlsBackendInterface"> TLS (Transport Layer Security, aka SSL) and DTLS backend. - + filename="gio/gtlsbackend.c" + line="31">TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an +internal type used to coordinate the different classes implemented +by a TLS backend. + Gets the default #GTlsBackend for the system. - + filename="gio/gtlsbackend.c" + line="53">Gets the default #GTlsBackend for the system. + a #GTlsBackend, which will be a + filename="gio/gtlsbackend.c" + line="58">a #GTlsBackend, which will be a dummy object if no TLS backend is available @@ -115992,21 +120719,21 @@ not return until the connection is closed. invoker="get_default_database" version="2.30"> Gets the default #GTlsDatabase used to verify TLS connections. - + filename="gio/gtlsbackend.c" + line="122">Gets the default #GTlsDatabase used to verify TLS connections. + the default database, which should be + filename="gio/gtlsbackend.c" + line="128">the default database, which should be unreffed when done. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="124">the #GTlsBackend @@ -116015,21 +120742,21 @@ not return until the connection is closed. invoker="supports_dtls" version="2.48"> Checks if DTLS is supported. DTLS support may not be available even if TLS + filename="gio/gtlsbackend.c" + line="102">Checks if DTLS is supported. DTLS support may not be available even if TLS support is available, and vice-versa. - + whether DTLS is supported + filename="gio/gtlsbackend.c" + line="109">whether DTLS is supported the #GTlsBackend + filename="gio/gtlsbackend.c" + line="104">the #GTlsBackend @@ -116038,21 +120765,21 @@ support is available, and vice-versa. invoker="supports_tls" version="2.28"> Checks if TLS is supported; if this returns %FALSE for the default + filename="gio/gtlsbackend.c" + line="80">Checks if TLS is supported; if this returns %FALSE for the default #GTlsBackend, it means no "real" TLS backend is available. - + whether or not TLS is supported + filename="gio/gtlsbackend.c" + line="87">whether or not TLS is supported the #GTlsBackend + filename="gio/gtlsbackend.c" + line="82">the #GTlsBackend @@ -116061,21 +120788,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_certificate_type" version="2.28"> Gets the #GType of @backend's #GTlsCertificate implementation. - + filename="gio/gtlsbackend.c" + line="182">Gets the #GType of @backend's #GTlsCertificate implementation. + the #GType of @backend's #GTlsCertificate + filename="gio/gtlsbackend.c" + line="188">the #GType of @backend's #GTlsCertificate implementation. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="184">the #GTlsBackend @@ -116084,21 +120811,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_client_connection_type" version="2.28"> Gets the #GType of @backend's #GTlsClientConnection implementation. - + filename="gio/gtlsbackend.c" + line="199">Gets the #GType of @backend's #GTlsClientConnection implementation. + the #GType of @backend's #GTlsClientConnection + filename="gio/gtlsbackend.c" + line="205">the #GType of @backend's #GTlsClientConnection implementation. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="201">the #GTlsBackend @@ -116107,21 +120834,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_default_database" version="2.30"> Gets the default #GTlsDatabase used to verify TLS connections. - + filename="gio/gtlsbackend.c" + line="122">Gets the default #GTlsDatabase used to verify TLS connections. + the default database, which should be + filename="gio/gtlsbackend.c" + line="128">the default database, which should be unreffed when done. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="124">the #GTlsBackend @@ -116130,21 +120857,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_dtls_client_connection_type" version="2.48"> Gets the #GType of @backend’s #GDtlsClientConnection implementation. - + filename="gio/gtlsbackend.c" + line="233">Gets the #GType of @backend’s #GDtlsClientConnection implementation. + the #GType of @backend’s #GDtlsClientConnection + filename="gio/gtlsbackend.c" + line="239">the #GType of @backend’s #GDtlsClientConnection implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="235">the #GTlsBackend @@ -116153,21 +120880,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_dtls_server_connection_type" version="2.48"> Gets the #GType of @backend’s #GDtlsServerConnection implementation. - + filename="gio/gtlsbackend.c" + line="258">Gets the #GType of @backend’s #GDtlsServerConnection implementation. + the #GType of @backend’s #GDtlsServerConnection + filename="gio/gtlsbackend.c" + line="264">the #GType of @backend’s #GDtlsServerConnection implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="260">the #GTlsBackend @@ -116176,20 +120903,20 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_file_database_type" version="2.30"> Gets the #GType of @backend's #GTlsFileDatabase implementation. - + filename="gio/gtlsbackend.c" + line="283">Gets the #GType of @backend's #GTlsFileDatabase implementation. + the #GType of backend's #GTlsFileDatabase implementation. + filename="gio/gtlsbackend.c" + line="289">the #GType of backend's #GTlsFileDatabase implementation. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="285">the #GTlsBackend @@ -116198,21 +120925,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_get_server_connection_type" version="2.28"> Gets the #GType of @backend's #GTlsServerConnection implementation. - + filename="gio/gtlsbackend.c" + line="216">Gets the #GType of @backend's #GTlsServerConnection implementation. + the #GType of @backend's #GTlsServerConnection + filename="gio/gtlsbackend.c" + line="222">the #GType of @backend's #GTlsServerConnection implementation. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="218">the #GTlsBackend @@ -116221,8 +120948,8 @@ support is available, and vice-versa. c:identifier="g_tls_backend_set_default_database" version="2.60"> Set the default #GTlsDatabase used to verify TLS connections + filename="gio/gtlsbackend.c" + line="154">Set the default #GTlsDatabase used to verify TLS connections Any subsequent call to g_tls_backend_get_default_database() will return the database set in this call. Existing databases and connections are not @@ -116230,15 +120957,15 @@ modified. Setting a %NULL default database will reset to using the system default database as if g_tls_backend_set_default_database() had never been called. - + the #GTlsBackend + filename="gio/gtlsbackend.c" + line="156">the #GTlsBackend nullable="1" allow-none="1"> the #GTlsDatabase + filename="gio/gtlsbackend.c" + line="157">the #GTlsDatabase @@ -116256,21 +120983,21 @@ database as if g_tls_backend_set_default_database() had never been called. c:identifier="g_tls_backend_supports_dtls" version="2.48"> Checks if DTLS is supported. DTLS support may not be available even if TLS + filename="gio/gtlsbackend.c" + line="102">Checks if DTLS is supported. DTLS support may not be available even if TLS support is available, and vice-versa. - + whether DTLS is supported + filename="gio/gtlsbackend.c" + line="109">whether DTLS is supported the #GTlsBackend + filename="gio/gtlsbackend.c" + line="104">the #GTlsBackend @@ -116279,21 +121006,21 @@ support is available, and vice-versa. c:identifier="g_tls_backend_supports_tls" version="2.28"> Checks if TLS is supported; if this returns %FALSE for the default + filename="gio/gtlsbackend.c" + line="80">Checks if TLS is supported; if this returns %FALSE for the default #GTlsBackend, it means no "real" TLS backend is available. - + whether or not TLS is supported + filename="gio/gtlsbackend.c" + line="87">whether or not TLS is supported the #GTlsBackend + filename="gio/gtlsbackend.c" + line="82">the #GTlsBackend @@ -116304,116 +121031,143 @@ support is available, and vice-versa. glib:is-gtype-struct-for="TlsBackend" version="2.28"> Provides an interface for describing TLS-related types. - + The parent interface. + returns whether the backend supports TLS. - + whether or not TLS is supported + filename="gio/gtlsbackend.c" + line="87">whether or not TLS is supported the #GTlsBackend + filename="gio/gtlsbackend.c" + line="82">the #GTlsBackend + returns the #GTlsCertificate implementation type - + + returns the #GTlsClientConnection implementation type - + + returns the #GTlsServerConnection implementation type - + + returns the #GTlsFileDatabase implementation type. - + + returns a default #GTlsDatabase instance. - + the default database, which should be + filename="gio/gtlsbackend.c" + line="128">the default database, which should be unreffed when done. the #GTlsBackend + filename="gio/gtlsbackend.c" + line="124">the #GTlsBackend + returns whether the backend supports DTLS - + whether DTLS is supported + filename="gio/gtlsbackend.c" + line="109">whether DTLS is supported the #GTlsBackend + filename="gio/gtlsbackend.c" + line="104">the #GTlsBackend + returns the #GDtlsClientConnection implementation type - + + returns the #GDtlsServerConnection implementation type - + @@ -116430,20 +121184,20 @@ support is available, and vice-versa. glib:get-type="g_tls_certificate_get_type" glib:type-struct="TlsCertificateClass"> A certificate used for TLS authentication and encryption. + filename="gio/gtlscertificate.c" + line="31">A certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a -#GTlsServerConnection). - +[iface@Gio.TlsServerConnection]). + Creates a #GTlsCertificate from the data in @file. + filename="gio/gtlscertificate.c" + line="814">Creates a #GTlsCertificate from the data in @file. As of 2.72, if the filename ends in `.p12` or `.pfx` the data is loaded by g_tls_certificate_new_from_pkcs12() otherwise it is loaded by @@ -116452,18 +121206,18 @@ exact details. If @file cannot be read or parsed, the function will return %NULL and set @error. - + the new certificate, or %NULL on error + filename="gio/gtlscertificate.c" + line="829">the new certificate, or %NULL on error file containing a certificate to import + filename="gio/gtlscertificate.c" + line="816">file containing a certificate to import @@ -116473,8 +121227,8 @@ set @error. version="2.72" throws="1"> Creates a #GTlsCertificate from the data in @file. + filename="gio/gtlscertificate.c" + line="766">Creates a #GTlsCertificate from the data in @file. If @file cannot be read or parsed, the function will return %NULL and set @error. @@ -116482,24 +121236,24 @@ set @error. Any unknown file types will error with %G_IO_ERROR_NOT_SUPPORTED. Currently only `.p12` and `.pfx` files are supported. See g_tls_certificate_new_from_pkcs12() for more details. - + the new certificate, or %NULL on error + filename="gio/gtlscertificate.c" + line="781">the new certificate, or %NULL on error file containing a certificate to import + filename="gio/gtlscertificate.c" + line="768">file containing a certificate to import password for PKCS #12 files + filename="gio/gtlscertificate.c" + line="769">password for PKCS #12 files @@ -116509,8 +121263,8 @@ See g_tls_certificate_new_from_pkcs12() for more details. version="2.28" throws="1"> Creates a #GTlsCertificate from the PEM-encoded data in @cert_file + filename="gio/gtlscertificate.c" + line="856">Creates a #GTlsCertificate from the PEM-encoded data in @cert_file and @key_file. The returned certificate will be the first certificate found in @cert_file. As of GLib 2.44, if @cert_file contains more certificates it will try to load a certificate chain. All @@ -116524,25 +121278,25 @@ still be returned. If either file cannot be read or parsed, the function will return %NULL and set @error. Otherwise, this behaves like g_tls_certificate_new_from_pem(). - + the new certificate, or %NULL on error + filename="gio/gtlscertificate.c" + line="879">the new certificate, or %NULL on error file containing one or more PEM-encoded + filename="gio/gtlscertificate.c" + line="858">file containing one or more PEM-encoded certificates to import file containing a PEM-encoded private key + filename="gio/gtlscertificate.c" + line="860">file containing a PEM-encoded private key to import @@ -116553,8 +121307,8 @@ g_tls_certificate_new_from_pem(). version="2.28" throws="1"> Creates a #GTlsCertificate from the PEM-encoded data in @data. If + filename="gio/gtlscertificate.c" + line="642">Creates a #GTlsCertificate from the PEM-encoded data in @data. If @data includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the #GTlsCertificate:private-key-pem property for information about @@ -116568,24 +121322,24 @@ file) and the #GTlsCertificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. - + the new certificate, or %NULL if @data is invalid + filename="gio/gtlscertificate.c" + line="663">the new certificate, or %NULL if @data is invalid PEM-encoded certificate data + filename="gio/gtlscertificate.c" + line="644">PEM-encoded certificate data the length of @data, or -1 if it's 0-terminated. + filename="gio/gtlscertificate.c" + line="645">the length of @data, or -1 if it's 0-terminated. @@ -116595,8 +121349,8 @@ the file will still be returned. version="2.68" throws="1"> Creates a #GTlsCertificate from a + filename="gio/gtlscertificate.c" + line="913">Creates a #GTlsCertificate from a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI. An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` @@ -116620,18 +121374,18 @@ In this case the certificate and private key would both be detected and used as @private_key_pkcs11_uri allows using a private key exposed under a different URI. Note that the private key is not accessed until usage and may fail or require a PIN later. - + the new certificate, or %NULL on error + filename="gio/gtlscertificate.c" + line="944">the new certificate, or %NULL on error A PKCS \#11 URI + filename="gio/gtlscertificate.c" + line="915">A PKCS \#11 URI A PKCS \#11 URI + filename="gio/gtlscertificate.c" + line="916">A PKCS \#11 URI @@ -116650,8 +121404,8 @@ Note that the private key is not accessed until usage and may fail or require a version="2.72" throws="1"> Creates a #GTlsCertificate from the data in @data. It must contain + filename="gio/gtlscertificate.c" + line="695">Creates a #GTlsCertificate from the data in @data. It must contain a certificate and matching private key. If extra certificates are included they will be verified as a chain @@ -116668,26 +121422,26 @@ If support is missing it will error with %G_IO_ERROR_NOT_SUPPORTED. Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE. - + the new certificate, or %NULL if @data is invalid + filename="gio/gtlscertificate.c" + line="720">the new certificate, or %NULL if @data is invalid DER-encoded PKCS #12 format certificate data + filename="gio/gtlscertificate.c" + line="697">DER-encoded PKCS #12 format certificate data the length of @data + filename="gio/gtlscertificate.c" + line="698">the length of @data nullable="1" allow-none="1"> optional password for encrypted certificate data + filename="gio/gtlscertificate.c" + line="699">optional password for encrypted certificate data @@ -116706,17 +121460,17 @@ Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE. version="2.28" throws="1"> Creates one or more #GTlsCertificates from the PEM-encoded + filename="gio/gtlscertificate.c" + line="985">Creates one or more #GTlsCertificates from the PEM-encoded data in @file. If @file cannot be read or parsed, the function will return %NULL and set @error. If @file does not contain any PEM-encoded certificates, this will return an empty list and not set @error. - + a + filename="gio/gtlscertificate.c" + line="996">a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it. @@ -116726,16 +121480,16 @@ and its contents when you are done with it. file containing PEM-encoded certificates to import + filename="gio/gtlscertificate.c" + line="987">file containing PEM-encoded certificates to import This verifies @cert and returns a set of #GTlsCertificateFlags + filename="gio/gtlscertificate.c" + line="1070">This verifies @cert and returns a set of #GTlsCertificateFlags indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system @@ -116768,18 +121522,18 @@ For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. - + the appropriate #GTlsCertificateFlags + filename="gio/gtlscertificate.c" + line="1110">the appropriate #GTlsCertificateFlags a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1072">a #GTlsCertificate nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlscertificate.c" + line="1073">the expected peer identity nullable="1" allow-none="1"> the certificate of a trusted authority + filename="gio/gtlscertificate.c" + line="1074">the certificate of a trusted authority @@ -116807,13 +121561,13 @@ handle the verification. glib:get-property="dns-names" version="2.70"> Gets the value of #GTlsCertificate:dns-names. - + filename="gio/gtlscertificate.c" + line="1248">Gets the value of #GTlsCertificate:dns-names. + A #GPtrArray of + filename="gio/gtlscertificate.c" + line="1254">A #GPtrArray of #GBytes elements, or %NULL if it's not available. @@ -116822,8 +121576,8 @@ handle the verification. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1250">a #GTlsCertificate @@ -116833,13 +121587,13 @@ handle the verification. glib:get-property="ip-addresses" version="2.70"> Gets the value of #GTlsCertificate:ip-addresses. - + filename="gio/gtlscertificate.c" + line="1271">Gets the value of #GTlsCertificate:ip-addresses. + A #GPtrArray + filename="gio/gtlscertificate.c" + line="1277">A #GPtrArray of #GInetAddress elements, or %NULL if it's not available. @@ -116848,8 +121602,8 @@ of #GInetAddress elements, or %NULL if it's not available. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1273">a #GTlsCertificate @@ -116859,13 +121613,13 @@ of #GInetAddress elements, or %NULL if it's not available. glib:get-property="issuer" version="2.28"> Gets the #GTlsCertificate representing @cert's issuer, if known - + filename="gio/gtlscertificate.c" + line="1046">Gets the #GTlsCertificate representing @cert's issuer, if known + The certificate of @cert's issuer, + filename="gio/gtlscertificate.c" + line="1052">The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. @@ -116873,8 +121627,8 @@ certificate. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1048">a #GTlsCertificate @@ -116884,20 +121638,20 @@ certificate. glib:get-property="issuer-name" version="2.70"> Returns the issuer name from the certificate. - + filename="gio/gtlscertificate.c" + line="1226">Returns the issuer name from the certificate. + The issuer name, or %NULL if it's not available. + filename="gio/gtlscertificate.c" + line="1232">The issuer name, or %NULL if it's not available. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1228">a #GTlsCertificate @@ -116907,20 +121661,20 @@ certificate. glib:get-property="not-valid-after" version="2.70"> Returns the time at which the certificate became or will become invalid. - + filename="gio/gtlscertificate.c" + line="1182">Returns the time at which the certificate became or will become invalid. + The not-valid-after date, or %NULL if it's not available. + filename="gio/gtlscertificate.c" + line="1188">The not-valid-after date, or %NULL if it's not available. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1184">a #GTlsCertificate @@ -116930,20 +121684,20 @@ certificate. glib:get-property="not-valid-before" version="2.70"> Returns the time at which the certificate became or will become valid. - + filename="gio/gtlscertificate.c" + line="1160">Returns the time at which the certificate became or will become valid. + The not-valid-before date, or %NULL if it's not available. + filename="gio/gtlscertificate.c" + line="1166">The not-valid-before date, or %NULL if it's not available. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1162">a #GTlsCertificate @@ -116953,20 +121707,20 @@ certificate. glib:get-property="subject-name" version="2.70"> Returns the subject name from the certificate. - + filename="gio/gtlscertificate.c" + line="1204">Returns the subject name from the certificate. + The subject name, or %NULL if it's not available. + filename="gio/gtlscertificate.c" + line="1210">The subject name, or %NULL if it's not available. a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1206">a #GTlsCertificate @@ -116975,30 +121729,30 @@ certificate. c:identifier="g_tls_certificate_is_same" version="2.34"> Check if two #GTlsCertificate objects represent the same certificate. + filename="gio/gtlscertificate.c" + line="1122">Check if two #GTlsCertificate objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or #GTlsCertificate:private-key-pem properties differ. - + whether the same or not + filename="gio/gtlscertificate.c" + line="1133">whether the same or not first certificate to compare + filename="gio/gtlscertificate.c" + line="1124">first certificate to compare second certificate to compare + filename="gio/gtlscertificate.c" + line="1125">second certificate to compare @@ -117007,8 +121761,8 @@ their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or c:identifier="g_tls_certificate_verify" version="2.28"> This verifies @cert and returns a set of #GTlsCertificateFlags + filename="gio/gtlscertificate.c" + line="1070">This verifies @cert and returns a set of #GTlsCertificateFlags indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system @@ -117041,18 +121795,18 @@ For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. - + the appropriate #GTlsCertificateFlags + filename="gio/gtlscertificate.c" + line="1110">the appropriate #GTlsCertificateFlags a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1072">a #GTlsCertificate nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlscertificate.c" + line="1073">the expected peer identity nullable="1" allow-none="1"> the certificate of a trusted authority + filename="gio/gtlscertificate.c" + line="1074">the certificate of a trusted authority @@ -117081,8 +121835,8 @@ handle the verification. construct-only="1" transfer-ownership="none"> The DER (binary) encoded representation of the certificate. + filename="gio/gtlscertificate.c" + line="157">The DER (binary) encoded representation of the certificate. This property and the #GTlsCertificate:certificate-pem property represent the same data, just in different forms. @@ -117096,8 +121850,8 @@ represent the same data, just in different forms. transfer-ownership="none" default-value="NULL"> The PEM (ASCII) encoded representation of the certificate. + filename="gio/gtlscertificate.c" + line="172">The PEM (ASCII) encoded representation of the certificate. This property and the #GTlsCertificate:certificate property represent the same data, just in different forms. @@ -117107,8 +121861,8 @@ property represent the same data, just in different forms. transfer-ownership="container" getter="get_dns_names"> The DNS names from the certificate's Subject Alternative Names (SANs), + filename="gio/gtlscertificate.c" + line="363">The DNS names from the certificate's Subject Alternative Names (SANs), %NULL if unavailable. @@ -117119,8 +121873,8 @@ property represent the same data, just in different forms. transfer-ownership="container" getter="get_ip_addresses"> The IP addresses from the certificate's Subject Alternative Names (SANs), + filename="gio/gtlscertificate.c" + line="377">The IP addresses from the certificate's Subject Alternative Names (SANs), %NULL if unavailable. @@ -117133,8 +121887,8 @@ property represent the same data, just in different forms. transfer-ownership="none" getter="get_issuer"> A #GTlsCertificate representing the entity that issued this + filename="gio/gtlscertificate.c" + line="246">A #GTlsCertificate representing the entity that issued this certificate. If %NULL, this means that the certificate is either self-signed, or else the certificate of the issuer is not available. @@ -117158,8 +121912,8 @@ GLib itself should make security decisions about TLS certificates. getter="get_issuer_name" default-value="NULL"> The issuer from the certificate, + filename="gio/gtlscertificate.c" + line="349">The issuer from the certificate, %NULL if unavailable. @@ -117168,8 +121922,8 @@ GLib itself should make security decisions about TLS certificates. transfer-ownership="none" getter="get_not_valid_after"> The time at which this cert is no longer valid, + filename="gio/gtlscertificate.c" + line="322">The time at which this cert is no longer valid, %NULL if unavailable. @@ -117178,8 +121932,8 @@ GLib itself should make security decisions about TLS certificates. transfer-ownership="none" getter="get_not_valid_before"> The time at which this cert is considered to be valid, + filename="gio/gtlscertificate.c" + line="308">The time at which this cert is considered to be valid, %NULL if unavailable. @@ -117191,8 +121945,8 @@ GLib itself should make security decisions about TLS certificates. transfer-ownership="none" default-value="NULL"> An optional password used when constructed with GTlsCertificate:pkcs12-data. + filename="gio/gtlscertificate.c" + line="144">An optional password used when constructed with GTlsCertificate:pkcs12-data. transfer-ownership="none" default-value="NULL"> A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) + filename="gio/gtlscertificate.c" + line="275">A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) objects containing an X.509 certificate and optionally a private key. If %NULL, the certificate is either not backed by PKCS \#11 or the @@ -117217,8 +121971,8 @@ If %NULL, the certificate is either not backed by PKCS \#11 or the construct-only="1" transfer-ownership="none"> The PKCS #12 formatted data used to construct the object. + filename="gio/gtlscertificate.c" + line="128">The PKCS #12 formatted data used to construct the object. See also: g_tls_certificate_new_from_pkcs12() @@ -117231,8 +121985,8 @@ See also: g_tls_certificate_new_from_pkcs12() construct-only="1" transfer-ownership="none"> The DER (binary) encoded representation of the certificate's + filename="gio/gtlscertificate.c" + line="187">The DER (binary) encoded representation of the certificate's private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208) PKCS \#8 format is supported since 2.32; earlier releases only @@ -117260,8 +122014,8 @@ PKCS \#8. transfer-ownership="none" default-value="NULL"> The PEM (ASCII) encoded representation of the certificate's + filename="gio/gtlscertificate.c" + line="216">The PEM (ASCII) encoded representation of the certificate's private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) ("`BEGIN RSA PRIVATE KEY`") or unencrypted [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208) @@ -117288,8 +122042,8 @@ PKCS \#8. transfer-ownership="none" default-value="NULL"> A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) + filename="gio/gtlscertificate.c" + line="293">A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) object containing a private key. @@ -117299,8 +122053,8 @@ object containing a private key. getter="get_subject_name" default-value="NULL"> The subject from the cert, + filename="gio/gtlscertificate.c" + line="336">The subject from the cert, %NULL if unavailable. @@ -117314,24 +122068,24 @@ object containing a private key. - + - + the appropriate #GTlsCertificateFlags + filename="gio/gtlscertificate.c" + line="1110">the appropriate #GTlsCertificateFlags a #GTlsCertificate + filename="gio/gtlscertificate.c" + line="1072">a #GTlsCertificate nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlscertificate.c" + line="1073">the expected peer identity nullable="1" allow-none="1"> the certificate of a trusted authority + filename="gio/gtlscertificate.c" + line="1074">the certificate of a trusted authority @@ -117367,8 +122121,8 @@ object containing a private key. glib:get-type="g_tls_certificate_flags_get_type" c:type="GTlsCertificateFlags"> A set of flags describing TLS certification validation. This can be + filename="gio/gioenums.h" + line="1611">A set of flags describing TLS certification validation. This can be used to describe why a particular certificate was rejected (for example, in #GTlsConnection::accept-certificate). @@ -117385,8 +122139,8 @@ other problems exist with the certificate. glib:nick="no-flags" glib:name="G_TLS_CERTIFICATE_NO_FLAGS"> No flags set. Since: 2.74 + filename="gio/gioenums.h" + line="1613">No flags set. Since: 2.74 glib:nick="unknown-ca" glib:name="G_TLS_CERTIFICATE_UNKNOWN_CA"> The signing certificate authority is + filename="gio/gioenums.h" + line="1614">The signing certificate authority is not known. glib:nick="bad-identity" glib:name="G_TLS_CERTIFICATE_BAD_IDENTITY"> The certificate does not match the + filename="gio/gioenums.h" + line="1616">The certificate does not match the expected identity of the site that it was retrieved from. glib:nick="not-activated" glib:name="G_TLS_CERTIFICATE_NOT_ACTIVATED"> The certificate's activation time + filename="gio/gioenums.h" + line="1618">The certificate's activation time is still in the future glib:nick="expired" glib:name="G_TLS_CERTIFICATE_EXPIRED"> The certificate has expired + filename="gio/gioenums.h" + line="1620">The certificate has expired glib:nick="revoked" glib:name="G_TLS_CERTIFICATE_REVOKED"> The certificate has been revoked + filename="gio/gioenums.h" + line="1621">The certificate has been revoked according to the #GTlsConnection's certificate revocation list. glib:nick="insecure" glib:name="G_TLS_CERTIFICATE_INSECURE"> The certificate's algorithm is + filename="gio/gioenums.h" + line="1623">The certificate's algorithm is considered insecure. glib:nick="generic-error" glib:name="G_TLS_CERTIFICATE_GENERIC_ERROR"> Some other error occurred validating + filename="gio/gioenums.h" + line="1625">Some other error occurred validating the certificate glib:nick="validate-all" glib:name="G_TLS_CERTIFICATE_VALIDATE_ALL"> the combination of all of the above + filename="gio/gioenums.h" + line="1627">the combination of all of the above flags @@ -117472,7 +122226,7 @@ other problems exist with the certificate. c:type="GTlsCertificatePrivate" disguised="1" opaque="1"> - + glib:get-type="g_tls_certificate_request_flags_get_type" c:type="GTlsCertificateRequestFlags"> Flags for g_tls_interaction_request_certificate(), + filename="gio/gioenums.h" + line="1869">Flags for g_tls_interaction_request_certificate(), g_tls_interaction_request_certificate_async(), and g_tls_interaction_invoke_request_certificate(). glib:nick="none" glib:name="G_TLS_CERTIFICATE_REQUEST_NONE"> No flags + filename="gio/gioenums.h" + line="1871">No flags c:type="GTlsChannelBindingError" glib:error-domain="g-tls-channel-binding-error-quark"> An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to + filename="gio/gioenums.h" + line="1699">An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to indicate a TLS channel binding retrieval error. glib:nick="not-implemented" glib:name="G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED"> Either entire binding + filename="gio/gioenums.h" + line="1701">Either entire binding retrieval facility or specific binding type is not implemented in the TLS backend. @@ -117521,8 +122275,8 @@ indicate a TLS channel binding retrieval error. glib:nick="invalid-state" glib:name="G_TLS_CHANNEL_BINDING_ERROR_INVALID_STATE"> The handshake is not yet + filename="gio/gioenums.h" + line="1704">The handshake is not yet complete on the connection which is a strong requirement for any existing binding type. @@ -117532,8 +122286,8 @@ indicate a TLS channel binding retrieval error. glib:nick="not-available" glib:name="G_TLS_CHANNEL_BINDING_ERROR_NOT_AVAILABLE"> Handshake is complete but + filename="gio/gioenums.h" + line="1707">Handshake is complete but binding data is not available. That normally indicates the TLS implementation failed to provide the binding data. For example, some implementations do not provide a peer certificate for resumed connections. @@ -117544,8 +122298,8 @@ indicate a TLS channel binding retrieval error. glib:nick="not-supported" glib:name="G_TLS_CHANNEL_BINDING_ERROR_NOT_SUPPORTED"> Binding type is not supported + filename="gio/gioenums.h" + line="1711">Binding type is not supported on the current connection. This error could be triggered when requesting `tls-server-end-point` binding data for a certificate which has no hash function or uses multiple hash functions. @@ -117556,20 +122310,20 @@ indicate a TLS channel binding retrieval error. glib:nick="general-error" glib:name="G_TLS_CHANNEL_BINDING_ERROR_GENERAL_ERROR"> Any other backend error + filename="gio/gioenums.h" + line="1715">Any other backend error preventing binding data retrieval. Gets the TLS channel binding error quark. + filename="gio/gtlsconnection.c" + line="868">Gets the TLS channel binding error quark. a #GQuark. + filename="gio/gtlsconnection.c" + line="873">a #GQuark. @@ -117580,8 +122334,8 @@ indicate a TLS channel binding retrieval error. glib:get-type="g_tls_channel_binding_type_get_type" c:type="GTlsChannelBindingType"> The type of TLS channel binding data to retrieve from #GTlsConnection + filename="gio/gioenums.h" + line="1673">The type of TLS channel binding data to retrieve from #GTlsConnection or #GDtlsConnection, as documented by RFC 5929 or RFC 9266. The [`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5) binding type is not currently implemented. @@ -117591,8 +122345,8 @@ binding type is not currently implemented. glib:nick="unique" glib:name="G_TLS_CHANNEL_BINDING_TLS_UNIQUE"> [`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding + filename="gio/gioenums.h" + line="1675">[`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding type glib:nick="server-end-point" glib:name="G_TLS_CHANNEL_BINDING_TLS_SERVER_END_POINT"> [`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) + filename="gio/gioenums.h" + line="1678">[`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) binding type glib:nick="exporter" glib:name="G_TLS_CHANNEL_BINDING_TLS_EXPORTER"> [`tls-exporter`](https://www.rfc-editor.org/rfc/rfc9266.html) binding + filename="gio/gioenums.h" + line="1681">[`tls-exporter`](https://www.rfc-editor.org/rfc/rfc9266.html) binding type. Since: 2.74 @@ -117624,37 +122378,37 @@ binding type is not currently implemented. glib:get-type="g_tls_client_connection_get_type" glib:type-struct="TlsClientConnectionInterface"> #GTlsClientConnection is the client-side subclass of -#GTlsConnection, representing a client-side TLS connection. - + filename="gio/gtlsclientconnection.c" + line="33">`GTlsClientConnection` is the client-side subclass of +[class@Gio.TlsConnection], representing a client-side TLS connection. + Creates a new #GTlsClientConnection wrapping @base_io_stream (which + filename="gio/gtlsclientconnection.c" + line="144">Creates a new #GTlsClientConnection wrapping @base_io_stream (which must have pollable input and output streams) which is assumed to communicate with the server identified by @server_identity. See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. - + the new + filename="gio/gtlsclientconnection.c" + line="158">the new #GTlsClientConnection, or %NULL on error the #GIOStream to wrap + filename="gio/gtlsclientconnection.c" + line="146">the #GIOStream to wrap nullable="1" allow-none="1"> the expected identity of the server + filename="gio/gtlsclientconnection.c" + line="147">the expected identity of the server @@ -117672,8 +122426,8 @@ this function has returned. invoker="copy_session_state" version="2.46"> Possibly copies session state from one connection to another, for use + filename="gio/gtlsclientconnection.c" + line="361">Possibly copies session state from one connection to another, for use in TLS session resumption. This is not normally needed, but may be used when the same session needs to be used between different endpoints, as is required by some protocols, such as FTP over TLS. @@ -117701,21 +122455,21 @@ from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations. - + a #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="363">a #GTlsClientConnection a #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="364">a #GTlsClientConnection @@ -117724,8 +122478,8 @@ ticket to be copied without regard for privacy considerations. c:identifier="g_tls_client_connection_copy_session_state" version="2.46"> Possibly copies session state from one connection to another, for use + filename="gio/gtlsclientconnection.c" + line="361">Possibly copies session state from one connection to another, for use in TLS session resumption. This is not normally needed, but may be used when the same session needs to be used between different endpoints, as is required by some protocols, such as FTP over TLS. @@ -117753,21 +122507,21 @@ from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations. - + a #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="363">a #GTlsClientConnection a #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="364">a #GTlsClientConnection @@ -117777,19 +122531,19 @@ ticket to be copied without regard for privacy considerations. glib:get-property="accepted-cas" version="2.28"> Gets the list of distinguished names of the Certificate Authorities + filename="gio/gtlsclientconnection.c" + line="332">Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be %NULL. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. - + the list of + filename="gio/gtlsclientconnection.c" + line="344">the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free(). @@ -117801,8 +122555,8 @@ the free the list with g_list_free(). the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="334">the #GTlsClientConnection @@ -117812,13 +122566,13 @@ the free the list with g_list_free(). glib:get-property="server-identity" version="2.28"> Gets @conn's expected server identity - + filename="gio/gtlsclientconnection.c" + line="233">Gets @conn's expected server identity + a #GSocketConnectable describing the + filename="gio/gtlsclientconnection.c" + line="239">a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. @@ -117826,8 +122580,8 @@ known. the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="235">the #GTlsClientConnection @@ -117839,22 +122593,22 @@ known. deprecated="1" deprecated-version="2.56"> SSL 3.0 is no longer supported. See + filename="gio/gtlsclientconnection.c" + line="279">SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. SSL 3.0 is insecure. - + %FALSE + filename="gio/gtlsclientconnection.c" + line="286">%FALSE the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="281">the #GTlsClientConnection @@ -117866,25 +122620,25 @@ g_tls_client_connection_set_use_ssl3() for details. deprecated="1" deprecated-version="2.72"> Gets @conn's validation flags + filename="gio/gtlsclientconnection.c" + line="180">Gets @conn's validation flags This function does not work as originally designed and is impossible to use correctly. See #GTlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. - + the validation flags + filename="gio/gtlsclientconnection.c" + line="190">the validation flags the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="182">the #GTlsClientConnection @@ -117894,26 +122648,26 @@ information. glib:set-property="server-identity" version="2.28"> Sets @conn's expected server identity, which is used both to tell + filename="gio/gtlsclientconnection.c" + line="258">Sets @conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let @conn know what name to look for in the certificate when performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - + the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="260">the #GTlsClientConnection a #GSocketConnectable describing the expected server identity + filename="gio/gtlsclientconnection.c" + line="261">a #GSocketConnectable describing the expected server identity @@ -117925,8 +122679,8 @@ performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. deprecated="1" deprecated-version="2.56"> Since GLib 2.42.1, SSL 3.0 is no longer supported. + filename="gio/gtlsclientconnection.c" + line="303">Since GLib 2.42.1, SSL 3.0 is no longer supported. From GLib 2.42.1 through GLib 2.62, this function could be used to force use of TLS 1.0, the lowest-supported TLS protocol version at @@ -117937,21 +122691,21 @@ acceptable. Since GLib 2.64, this function does nothing. SSL 3.0 is insecure. - + the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="305">the #GTlsClientConnection a #gboolean, ignored + filename="gio/gtlsclientconnection.c" + line="306">a #gboolean, ignored @@ -117963,8 +122717,8 @@ Since GLib 2.64, this function does nothing. deprecated="1" deprecated-version="2.72"> Sets @conn's validation flags, to override the default set of + filename="gio/gtlsclientconnection.c" + line="207">Sets @conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, %G_TLS_CERTIFICATE_VALIDATE_ALL is used. @@ -117972,21 +122726,21 @@ This function does not work as originally designed and is impossible to use correctly. See #GTlsClientConnection:validation-flags for more information. Do not attempt to ignore validation errors. - + the #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="209">the #GTlsClientConnection the #GTlsCertificateFlags to use + filename="gio/gtlsclientconnection.c" + line="210">the #GTlsCertificateFlags to use @@ -117996,8 +122750,8 @@ information. transfer-ownership="none" getter="get_accepted_cas"> A list of the distinguished names of the Certificate Authorities + filename="gio/gtlsclientconnection.c" + line="125">A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. @@ -118016,8 +122770,8 @@ subject DN of the certificate authority. setter="set_server_identity" getter="get_server_identity"> A #GSocketConnectable describing the identity of the server that + filename="gio/gtlsclientconnection.c" + line="80">A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in @@ -118044,8 +122798,8 @@ virtual hosts. getter="get_use_ssl3" default-value="FALSE"> SSL 3.0 is no longer supported. See + filename="gio/gtlsclientconnection.c" + line="107">SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. SSL 3.0 is insecure. @@ -118061,8 +122815,8 @@ g_tls_client_connection_set_use_ssl3() for details. getter="get_validation_flags" default-value="G_TLS_CERTIFICATE_UNKNOWN_CA | G_TLS_CERTIFICATE_BAD_IDENTITY | G_TLS_CERTIFICATE_NOT_ACTIVATED | G_TLS_CERTIFICATE_EXPIRED | G_TLS_CERTIFICATE_REVOKED | G_TLS_CERTIFICATE_INSECURE | G_TLS_CERTIFICATE_GENERIC_ERROR"> What steps to perform when validating a certificate received from + filename="gio/gtlsclientconnection.c" + line="47">What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GTlsConnection::accept-certificate. @@ -118087,32 +122841,35 @@ connect to #GTlsConnection::accept-certificate. glib:is-gtype-struct-for="TlsClientConnection" version="2.26"> vtable for a #GTlsClientConnection implementation. - + The parent interface. + Copies session state from one #GTlsClientConnection to another. - + a #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="363">a #GTlsClientConnection a #GTlsClientConnection + filename="gio/gtlsclientconnection.c" + line="364">a #GTlsClientConnection @@ -118129,16 +122886,20 @@ connect to #GTlsConnection::accept-certificate. glib:get-type="g_tls_connection_get_type" glib:type-struct="TlsConnectionClass"> #GTlsConnection is the base TLS connection class type, which wraps -a #GIOStream and provides TLS encryption on top of it. Its -subclasses, #GTlsClientConnection and #GTlsServerConnection, -implement client-side and server-side TLS, respectively. + filename="gio/gtlsconnection.c" + line="36">`GTlsConnection` is the base TLS connection class type, which wraps +a [class@Gio.IOStream] and provides TLS encryption on top of it. Its +subclasses, [iface@Gio.TlsClientConnection] and +[iface@Gio.TlsServerConnection], implement client-side and server-side TLS, +respectively. -For DTLS (Datagram TLS) support, see #GDtlsConnection. - +For DTLS (Datagram TLS) support, see [iface@Gio.DtlsConnection]. + - + Check whether to accept a certificate. + @@ -118155,7 +122916,10 @@ For DTLS (Datagram TLS) support, see #GDtlsConnection. - + Retrieve TLS channel binding data (Since: 2.66) + @@ -118178,26 +122942,26 @@ For DTLS (Datagram TLS) support, see #GDtlsConnection. invoker="get_negotiated_protocol" version="2.60"> Gets the name of the application-layer protocol negotiated during + filename="gio/gtlsconnection.c" + line="838">Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_tls_connection_set_advertised_protocols(). - + the negotiated protocol, or %NULL + filename="gio/gtlsconnection.c" + line="850">the negotiated protocol, or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="840">a #GTlsConnection @@ -118205,10 +122969,11 @@ g_tls_connection_set_advertised_protocols(). + throws="1" + glib:async-func="handshake_async"> Attempts a TLS handshake on @conn. + filename="gio/gtlsconnection.c" + line="928">Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after @@ -118239,18 +123004,18 @@ function manually is not recommended. #GTlsConnection::accept_certificate may be emitted during the handshake. - + success or failure + filename="gio/gtlsconnection.c" + line="966">success or failure a #GTlsConnection + filename="gio/gtlsconnection.c" + line="930">a #GTlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsconnection.c" + line="931">a #GCancellable, or %NULL + version="2.28" + glib:finish-func="handshake_finish" + glib:sync-func="handshake"> Asynchronously performs a TLS handshake on @conn. See + filename="gio/gtlsconnection.c" + line="980">Asynchronously performs a TLS handshake on @conn. See g_tls_connection_handshake() for more information. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="982">a #GTlsConnection the [I/O priority][io-priority] of the request + filename="gio/gtlsconnection.c" + line="983">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsconnection.c" + line="984">a #GCancellable, or %NULL scope="async" closure="3"> callback to call when the handshake is complete + filename="gio/gtlsconnection.c" + line="985">callback to call when the handshake is complete allow-none="1" closure="3"> the data to pass to the callback function + filename="gio/gtlsconnection.c" + line="986">the data to pass to the callback function @@ -118325,28 +123092,28 @@ g_tls_connection_handshake() for more information. version="2.28" throws="1"> Finish an asynchronous TLS handshake operation. See + filename="gio/gtlsconnection.c" + line="1007">Finish an asynchronous TLS handshake operation. See g_tls_connection_handshake() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gtlsconnection.c" + line="1016">%TRUE on success, %FALSE on failure, in which case @error will be set. a #GTlsConnection + filename="gio/gtlsconnection.c" + line="1009">a #GTlsConnection a #GAsyncResult. + filename="gio/gtlsconnection.c" + line="1010">a #GAsyncResult. @@ -118355,34 +123122,34 @@ case @error will be set. c:identifier="g_tls_connection_emit_accept_certificate" version="2.28"> Used by #GTlsConnection implementations to emit the + filename="gio/gtlsconnection.c" + line="1105">Used by #GTlsConnection implementations to emit the #GTlsConnection::accept-certificate signal. - + %TRUE if one of the signal handlers has returned + filename="gio/gtlsconnection.c" + line="1114">%TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert a #GTlsConnection + filename="gio/gtlsconnection.c" + line="1107">a #GTlsConnection the peer's #GTlsCertificate + filename="gio/gtlsconnection.c" + line="1108">the peer's #GTlsCertificate the problems with @peer_cert + filename="gio/gtlsconnection.c" + line="1109">the problems with @peer_cert @@ -118392,21 +123159,21 @@ case @error will be set. glib:get-property="certificate" version="2.28"> Gets @conn's certificate, as set by + filename="gio/gtlsconnection.c" + line="548">Gets @conn's certificate, as set by g_tls_connection_set_certificate(). - + @conn's certificate, or %NULL + filename="gio/gtlsconnection.c" + line="555">@conn's certificate, or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="550">a #GTlsConnection @@ -118416,8 +123183,8 @@ g_tls_connection_set_certificate(). version="2.66" throws="1"> Query the TLS backend for TLS channel binding data of @type for @conn. + filename="gio/gtlsconnection.c" + line="879">Query the TLS backend for TLS channel binding data of @type for @conn. This call retrieves TLS channel binding data as specified in RFC [5056](https://tools.ietf.org/html/rfc5056), RFC @@ -118430,24 +123197,24 @@ is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support @type or the binding data is not available yet due to additional negotiation or input required. - + %TRUE on success, %FALSE otherwise + filename="gio/gtlsconnection.c" + line="901">%TRUE on success, %FALSE otherwise a #GTlsConnection + filename="gio/gtlsconnection.c" + line="881">a #GTlsConnection #GTlsChannelBindingType type of data to fetch + filename="gio/gtlsconnection.c" + line="882">#GTlsChannelBindingType type of data to fetch @@ -118458,8 +123225,8 @@ negotiation or input required. optional="1" allow-none="1"> #GByteArray is + filename="gio/gtlsconnection.c" + line="883">#GByteArray is filled with the binding data, or %NULL @@ -118472,8 +123239,8 @@ negotiation or input required. glib:get-property="ciphersuite-name" version="2.70"> Returns the name of the current TLS ciphersuite, or %NULL if the + filename="gio/gtlsconnection.c" + line="1063">Returns the name of the current TLS ciphersuite, or %NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that @@ -118481,18 +123248,18 @@ are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended. - + The name of the current TLS ciphersuite, or %NULL + filename="gio/gtlsconnection.c" + line="1076">The name of the current TLS ciphersuite, or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="1065">a #GTlsConnection @@ -118502,21 +123269,21 @@ is not recommended. glib:get-property="database" version="2.30"> Gets the certificate database that @conn uses to verify + filename="gio/gtlsconnection.c" + line="486">Gets the certificate database that @conn uses to verify peer certificates. See g_tls_connection_set_database(). - + the certificate database that @conn uses or %NULL + filename="gio/gtlsconnection.c" + line="493">the certificate database that @conn uses or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="488">a #GTlsConnection @@ -118526,22 +123293,22 @@ peer certificates. See g_tls_connection_set_database(). glib:get-property="interaction" version="2.30"> Get the object that will be used to interact with the user. It will be used + filename="gio/gtlsconnection.c" + line="597">Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. - + The interaction object. + filename="gio/gtlsconnection.c" + line="605">The interaction object. a connection + filename="gio/gtlsconnection.c" + line="599">a connection @@ -118551,26 +123318,26 @@ no user interaction will occur for this connection. glib:get-property="negotiated-protocol" version="2.60"> Gets the name of the application-layer protocol negotiated during + filename="gio/gtlsconnection.c" + line="838">Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_tls_connection_set_advertised_protocols(). - + the negotiated protocol, or %NULL + filename="gio/gtlsconnection.c" + line="850">the negotiated protocol, or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="840">a #GTlsConnection @@ -118580,22 +123347,22 @@ g_tls_connection_set_advertised_protocols(). glib:get-property="peer-certificate" version="2.28"> Gets @conn's peer's certificate after the handshake has completed + filename="gio/gtlsconnection.c" + line="623">Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) - + @conn's peer's certificate, or %NULL + filename="gio/gtlsconnection.c" + line="631">@conn's peer's certificate, or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="625">a #GTlsConnection @@ -118605,24 +123372,24 @@ or failed. (It is not set during the emission of glib:get-property="peer-certificate-errors" version="2.28"> Gets the errors associated with validating @conn's peer's + filename="gio/gtlsconnection.c" + line="649">Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) See #GTlsConnection:peer-certificate-errors for more information. - + @conn's peer's certificate errors + filename="gio/gtlsconnection.c" + line="659">@conn's peer's certificate errors a #GTlsConnection + filename="gio/gtlsconnection.c" + line="651">a #GTlsConnection @@ -118632,23 +123399,23 @@ See #GTlsConnection:peer-certificate-errors for more information. glib:get-property="protocol-version" version="2.70"> Returns the current TLS protocol version, which may be + filename="gio/gtlsconnection.c" + line="1031">Returns the current TLS protocol version, which may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized #GTlsProtocolVersion. - + The current TLS protocol version + filename="gio/gtlsconnection.c" + line="1040">The current TLS protocol version a #GTlsConnection + filename="gio/gtlsconnection.c" + line="1033">a #GTlsConnection @@ -118660,24 +123427,24 @@ that is not a recognized #GTlsProtocolVersion. deprecated="1" deprecated-version="2.60."> Gets @conn rehandshaking mode. See + filename="gio/gtlsconnection.c" + line="775">Gets @conn rehandshaking mode. See g_tls_connection_set_rehandshake_mode() for details. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. - + %G_TLS_REHANDSHAKE_SAFELY + filename="gio/gtlsconnection.c" + line="782">%G_TLS_REHANDSHAKE_SAFELY a #GTlsConnection + filename="gio/gtlsconnection.c" + line="777">a #GTlsConnection @@ -118687,23 +123454,23 @@ g_tls_connection_set_rehandshake_mode() for details. glib:get-property="require-close-notify" version="2.28"> Tests whether or not @conn expects a proper TLS close notification + filename="gio/gtlsconnection.c" + line="720">Tests whether or not @conn expects a proper TLS close notification when the connection is closed. See g_tls_connection_set_require_close_notify() for details. - + %TRUE if @conn requires a proper TLS close + filename="gio/gtlsconnection.c" + line="728">%TRUE if @conn requires a proper TLS close notification. a #GTlsConnection + filename="gio/gtlsconnection.c" + line="722">a #GTlsConnection @@ -118714,22 +123481,22 @@ notification. deprecated="1" deprecated-version="2.30"> Gets whether @conn uses the system certificate database to verify + filename="gio/gtlsconnection.c" + line="431">Gets whether @conn uses the system certificate database to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Use g_tls_connection_get_database() instead - + whether @conn uses the system certificate database + filename="gio/gtlsconnection.c" + line="438">whether @conn uses the system certificate database a #GTlsConnection + filename="gio/gtlsconnection.c" + line="433">a #GTlsConnection @@ -118737,10 +123504,11 @@ peer certificates. See g_tls_connection_set_use_system_certdb(). + throws="1" + glib:async-func="handshake_async"> Attempts a TLS handshake on @conn. + filename="gio/gtlsconnection.c" + line="928">Attempts a TLS handshake on @conn. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after @@ -118771,18 +123539,18 @@ function manually is not recommended. #GTlsConnection::accept_certificate may be emitted during the handshake. - + success or failure + filename="gio/gtlsconnection.c" + line="966">success or failure a #GTlsConnection + filename="gio/gtlsconnection.c" + line="930">a #GTlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsconnection.c" + line="931">a #GCancellable, or %NULL + version="2.28" + glib:finish-func="handshake_finish" + glib:sync-func="handshake"> Asynchronously performs a TLS handshake on @conn. See + filename="gio/gtlsconnection.c" + line="980">Asynchronously performs a TLS handshake on @conn. See g_tls_connection_handshake() for more information. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="982">a #GTlsConnection the [I/O priority][io-priority] of the request + filename="gio/gtlsconnection.c" + line="983">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsconnection.c" + line="984">a #GCancellable, or %NULL scope="async" closure="3"> callback to call when the handshake is complete + filename="gio/gtlsconnection.c" + line="985">callback to call when the handshake is complete nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gtlsconnection.c" + line="986">the data to pass to the callback function @@ -118856,28 +123626,28 @@ g_tls_connection_handshake() for more information. version="2.28" throws="1"> Finish an asynchronous TLS handshake operation. See + filename="gio/gtlsconnection.c" + line="1007">Finish an asynchronous TLS handshake operation. See g_tls_connection_handshake() for more information. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gtlsconnection.c" + line="1016">%TRUE on success, %FALSE on failure, in which case @error will be set. a #GTlsConnection + filename="gio/gtlsconnection.c" + line="1009">a #GTlsConnection a #GAsyncResult. + filename="gio/gtlsconnection.c" + line="1010">a #GAsyncResult. @@ -118887,8 +123657,8 @@ case @error will be set. glib:set-property="advertised-protocols" version="2.60"> Sets the list of application-layer protocols to advertise that the + filename="gio/gtlsconnection.c" + line="808">Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use @@ -118898,15 +123668,15 @@ of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="810">a #GTlsConnection nullable="1" allow-none="1"> a %NULL-terminated + filename="gio/gtlsconnection.c" + line="811">a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL @@ -118928,8 +123698,8 @@ for a list of registered protocol IDs. glib:set-property="certificate" version="2.28"> This sets the certificate that @conn will present to its peer + filename="gio/gtlsconnection.c" + line="512">This sets the certificate that @conn will present to its peer during the TLS handshake. For a #GTlsServerConnection, it is mandatory to set this, and that will normally be done at construct time. @@ -118947,21 +123717,21 @@ or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that g_tls_client_connection_get_accepted_cas() will return non-%NULL.) - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="514">a #GTlsConnection the certificate to use for @conn + filename="gio/gtlsconnection.c" + line="515">the certificate to use for @conn @@ -118971,8 +123741,8 @@ non-%NULL.) glib:set-property="database" version="2.30"> Sets the certificate database that is used to verify peer certificates. + filename="gio/gtlsconnection.c" + line="455">Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to %NULL, then peer certificate validation will always set the @@ -118983,15 +123753,15 @@ client-side connections, unless that bit is not set in There are nonintuitive security implications when using a non-default database. See #GTlsConnection:database for details. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="457">a #GTlsConnection nullable="1" allow-none="1"> a #GTlsDatabase + filename="gio/gtlsconnection.c" + line="458">a #GTlsDatabase @@ -119010,22 +123780,22 @@ database. See #GTlsConnection:database for details. glib:set-property="interaction" version="2.30"> Set the object that will be used to interact with the user. It will be used + filename="gio/gtlsconnection.c" + line="573">Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. The @interaction argument will normally be a derived subclass of #GTlsInteraction. %NULL can also be provided if no user interaction should occur for this connection. - + a connection + filename="gio/gtlsconnection.c" + line="575">a connection nullable="1" allow-none="1"> an interaction object, or %NULL + filename="gio/gtlsconnection.c" + line="576">an interaction object, or %NULL @@ -119046,29 +123816,29 @@ should occur for this connection. deprecated="1" deprecated-version="2.60."> Since GLib 2.64, changing the rehandshake mode is no longer supported + filename="gio/gtlsconnection.c" + line="746">Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="748">a #GTlsConnection the rehandshaking mode + filename="gio/gtlsconnection.c" + line="749">the rehandshaking mode @@ -119078,8 +123848,8 @@ rekey operations. glib:set-property="require-close-notify" version="2.28"> Sets whether or not @conn expects a proper TLS close notification + filename="gio/gtlsconnection.c" + line="674">Sets whether or not @conn expects a proper TLS close notification before the connection is closed. If this is %TRUE (the default), then @conn will expect to receive a TLS close notification from its peer before the connection is closed, and will return a @@ -119106,21 +123876,21 @@ setting of this property. If you explicitly want to do an unclean close, you can close @conn's #GTlsConnection:base-io-stream rather than closing @conn itself, but note that this may only be done when no other operations are pending on @conn or the base I/O stream. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="676">a #GTlsConnection whether or not to require close notification + filename="gio/gtlsconnection.c" + line="677">whether or not to require close notification @@ -119131,8 +123901,8 @@ operations are pending on @conn or the base I/O stream. deprecated="1" deprecated-version="2.30"> Sets whether @conn uses the system certificate database to verify + filename="gio/gtlsconnection.c" + line="405">Sets whether @conn uses the system certificate database to verify peer certificates. This is %TRUE by default. If set to %FALSE, then peer certificate validation will always set the %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning @@ -119140,21 +123910,21 @@ peer certificate validation will always set the client-side connections, unless that bit is not set in #GTlsClientConnection:validation-flags). Use g_tls_connection_set_database() instead - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="407">a #GTlsConnection whether to use the system certificate database + filename="gio/gtlsconnection.c" + line="408">whether to use the system certificate database @@ -119165,8 +123935,8 @@ client-side connections, unless that bit is not set in transfer-ownership="none" setter="set_advertised_protocols"> The list of application-layer protocols that the connection + filename="gio/gtlsconnection.c" + line="256">The list of application-layer protocols that the connection advertises that it is willing to speak. See g_tls_connection_set_advertised_protocols(). @@ -119179,8 +123949,8 @@ g_tls_connection_set_advertised_protocols(). construct-only="1" transfer-ownership="none"> The #GIOStream that the connection wraps. The connection holds a reference + filename="gio/gtlsconnection.c" + line="94">The #GIOStream that the connection wraps. The connection holds a reference to this stream, and may run operations on the stream from other threads throughout its lifetime. Consequently, after the #GIOStream has been constructed, application code may only run its own operations on this @@ -119194,8 +123964,8 @@ stream when no #GIOStream operations are running. setter="set_certificate" getter="get_certificate"> The connection's certificate; see + filename="gio/gtlsconnection.c" + line="200">The connection's certificate; see g_tls_connection_set_certificate(). @@ -119205,8 +123975,8 @@ g_tls_connection_set_certificate(). getter="get_ciphersuite_name" default-value="NULL"> The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). + filename="gio/gtlsconnection.c" + line="298">The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). setter="set_database" getter="get_database"> The certificate database to use when verifying this TLS connection. + filename="gio/gtlsconnection.c" + line="127">The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). @@ -119242,8 +124012,8 @@ unusual security requirements. setter="set_interaction" getter="get_interaction"> A #GTlsInteraction object to be used when the connection or certificate + filename="gio/gtlsconnection.c" + line="154">A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. @@ -119254,8 +124024,8 @@ user for passwords where necessary. getter="get_negotiated_protocol" default-value="NULL"> The application-layer protocol negotiated during the TLS + filename="gio/gtlsconnection.c" + line="270">The application-layer protocol negotiated during the TLS handshake. See g_tls_connection_get_negotiated_protocol(). @@ -119264,8 +124034,8 @@ handshake. See g_tls_connection_get_negotiated_protocol(). transfer-ownership="none" getter="get_peer_certificate"> The connection's peer's certificate, after the TLS handshake has + filename="gio/gtlsconnection.c" + line="213">The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GTlsConnection::accept-certificate. @@ -119279,8 +124049,8 @@ detect when a handshake has occurred.) getter="get_peer_certificate_errors" default-value="G_TLS_CERTIFICATE_NO_FLAGS"> The errors noticed while verifying + filename="gio/gtlsconnection.c" + line="230">The errors noticed while verifying #GTlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GTlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -119302,8 +124072,8 @@ error flag set even if other problems exist with the certificate. getter="get_protocol_version" default-value="G_TLS_PROTOCOL_VERSION_UNKNOWN"> The TLS protocol version in use. See g_tls_connection_get_protocol_version(). + filename="gio/gtlsconnection.c" + line="284">The TLS protocol version in use. See g_tls_connection_get_protocol_version(). getter="get_rehandshake_mode" default-value="G_TLS_REHANDSHAKE_SAFELY"> The rehandshaking mode. See + filename="gio/gtlsconnection.c" + line="182">The rehandshaking mode. See g_tls_connection_set_rehandshake_mode(). The rehandshake mode is ignored. @@ -119332,8 +124102,8 @@ g_tls_connection_set_rehandshake_mode(). getter="get_require_close_notify" default-value="TRUE"> Whether or not proper TLS close notification is required. + filename="gio/gtlsconnection.c" + line="168">Whether or not proper TLS close notification is required. See g_tls_connection_set_require_close_notify(). @@ -119347,8 +124117,8 @@ See g_tls_connection_set_require_close_notify(). getter="get_use_system_certdb" default-value="TRUE"> Whether or not the system certificate database will be used to + filename="gio/gtlsconnection.c" + line="111">Whether or not the system certificate database will be used to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Use GTlsConnection:database instead @@ -119362,8 +124132,8 @@ g_tls_connection_set_use_system_certdb(). Emitted during the TLS handshake after the peer certificate has + filename="gio/gtlsconnection.c" + line="311">Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert's certification path by calling g_tls_certificate_get_issuer() on it. @@ -119407,8 +124177,8 @@ need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. %TRUE to accept @peer_cert (which will also + filename="gio/gtlsconnection.c" + line="360">%TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. @@ -119417,14 +124187,14 @@ no one else overrides it. the peer's #GTlsCertificate + filename="gio/gtlsconnection.c" + line="314">the peer's #GTlsCertificate the problems with @peer_cert. + filename="gio/gtlsconnection.c" + line="315">the problems with @peer_cert. @@ -119435,18 +124205,21 @@ no one else overrides it. glib:is-gtype-struct-for="TlsConnection" version="2.28"> The class structure for the #GTlsConnection type. - + The parent class. + Check whether to accept a certificate. - + @@ -119464,19 +124237,22 @@ no one else overrides it. + Perform a handshake operation. - + success or failure + filename="gio/gtlsconnection.c" + line="966">success or failure a #GTlsConnection + filename="gio/gtlsconnection.c" + line="930">a #GTlsConnection nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsconnection.c" + line="931">a #GCancellable, or %NULL + Start an asynchronous handshake operation. - + a #GTlsConnection + filename="gio/gtlsconnection.c" + line="982">a #GTlsConnection the [I/O priority][io-priority] of the request + filename="gio/gtlsconnection.c" + line="983">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsconnection.c" + line="984">a #GCancellable, or %NULL scope="async" closure="4"> callback to call when the handshake is complete + filename="gio/gtlsconnection.c" + line="985">callback to call when the handshake is complete allow-none="1" closure="4"> the data to pass to the callback function + filename="gio/gtlsconnection.c" + line="986">the data to pass to the callback function + Finish an asynchronous handshake operation. - + %TRUE on success, %FALSE on failure, in which + filename="gio/gtlsconnection.c" + line="1016">%TRUE on success, %FALSE on failure, in which case @error will be set. a #GTlsConnection + filename="gio/gtlsconnection.c" + line="1009">a #GTlsConnection a #GAsyncResult. + filename="gio/gtlsconnection.c" + line="1010">a #GAsyncResult. + Retrieve TLS channel binding data (Since: 2.66) - + @@ -119592,19 +124377,22 @@ case @error will be set. + Get ALPN-negotiated protocol (Since: 2.70) - + the negotiated protocol, or %NULL + filename="gio/gtlsconnection.c" + line="850">the negotiated protocol, or %NULL a #GTlsConnection + filename="gio/gtlsconnection.c" + line="840">a #GTlsConnection @@ -119620,7 +124408,7 @@ case @error will be set. c:type="GTlsConnectionPrivate" disguised="1" opaque="1"> - + glib:get-type="g_tls_database_get_type" glib:type-struct="TlsDatabaseClass"> #GTlsDatabase is used to look up certificates and other information + filename="gio/gtlsdatabase.c" + line="35">`GTlsDatabase` is used to look up certificates and other information from a certificate or key store. It is an abstract base class which TLS library specific subtypes override. -A #GTlsDatabase may be accessed from multiple threads by the TLS backend. +A `GTlsDatabase` may be accessed from multiple threads by the TLS backend. All implementations are required to be fully thread-safe. Most common client applications will not directly interact with -#GTlsDatabase. It is used internally by #GTlsConnection. - +`GTlsDatabase`. It is used internally by [class@Gio.TlsConnection]. + Create a handle string for the certificate. The database will only be able + filename="gio/gtlsdatabase.c" + line="643">Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, %NULL will be returned. @@ -119656,25 +124444,25 @@ will be returned. This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it. - + a newly allocated string containing the + filename="gio/gtlsdatabase.c" + line="657">a newly allocated string containing the handle. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="645">a #GTlsDatabase certificate for which to create a handle. + filename="gio/gtlsdatabase.c" + line="646">certificate for which to create a handle. @@ -119682,10 +124470,11 @@ handle. + throws="1" + glib:async-func="lookup_certificate_for_handle_async"> Look up a certificate by its handle. + filename="gio/gtlsdatabase.c" + line="673">Look up a certificate by its handle. The handle should have been created by calling g_tls_database_create_certificate_handle() on a #GTlsDatabase object of @@ -119697,25 +124486,25 @@ this database, then %NULL will be returned. This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform the lookup operation asynchronously. - + a newly allocated + filename="gio/gtlsdatabase.c" + line="695">a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="675">a #GTlsDatabase a certificate handle + filename="gio/gtlsdatabase.c" + line="676">a certificate handle nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="677">used to interact with the user if necessary Flags which affect the lookup. + filename="gio/gtlsdatabase.c" + line="678">Flags which affect the lookup. @@ -119739,34 +124528,36 @@ the lookup operation asynchronously. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="679">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="lookup_certificate_for_handle_finish" + glib:sync-func="lookup_certificate_for_handle"> Asynchronously look up a certificate by its handle in the database. See + filename="gio/gtlsdatabase.c" + line="723">Asynchronously look up a certificate by its handle in the database. See g_tls_database_lookup_certificate_for_handle() for more information. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="725">a #GTlsDatabase a certificate handle + filename="gio/gtlsdatabase.c" + line="726">a certificate handle nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="727">used to interact with the user if necessary Flags which affect the lookup. + filename="gio/gtlsdatabase.c" + line="728">Flags which affect the lookup. @@ -119790,8 +124581,8 @@ g_tls_database_lookup_certificate_for_handle() for more information. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="729">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="730">callback to call when the operation completes allow-none="1" closure="5"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="731">the data to pass to the callback function @@ -119822,31 +124613,31 @@ g_tls_database_lookup_certificate_for_handle() for more information. version="2.30" throws="1"> Finish an asynchronous lookup of a certificate by its handle. See + filename="gio/gtlsdatabase.c" + line="761">Finish an asynchronous lookup of a certificate by its handle. See g_tls_database_lookup_certificate_for_handle() for more information. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. - + a newly allocated #GTlsCertificate object. + filename="gio/gtlsdatabase.c" + line="773">a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="763">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="764">a #GAsyncResult. @@ -119854,10 +124645,11 @@ Use g_object_unref() to release the certificate. + throws="1" + glib:async-func="lookup_certificate_issuer_async"> Look up the issuer of @certificate in the database. The + filename="gio/gtlsdatabase.c" + line="792">Look up the issuer of @certificate in the database. The #GTlsCertificate:issuer property of @certificate is not modified, and the two certificates are not hooked into a chain. @@ -119877,25 +124669,25 @@ which certification path will actually be used when verifying a TLS certificate. Accordingly, this function cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. - + a newly allocated issuer #GTlsCertificate, + filename="gio/gtlsdatabase.c" + line="822">a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="794">a #GTlsDatabase a #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="795">a #GTlsCertificate nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="796">used to interact with the user if necessary flags which affect the lookup operation + filename="gio/gtlsdatabase.c" + line="797">flags which affect the lookup operation @@ -119919,34 +124711,36 @@ or %NULL. Use g_object_unref() to release the certificate. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="798">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="lookup_certificate_issuer_finish" + glib:sync-func="lookup_certificate_issuer"> Asynchronously look up the issuer of @certificate in the database. See + filename="gio/gtlsdatabase.c" + line="849">Asynchronously look up the issuer of @certificate in the database. See g_tls_database_lookup_certificate_issuer() for more information. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="851">a #GTlsDatabase a #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="852">a #GTlsCertificate nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="853">used to interact with the user if necessary flags which affect the lookup operation + filename="gio/gtlsdatabase.c" + line="854">flags which affect the lookup operation @@ -119970,8 +124764,8 @@ g_tls_database_lookup_certificate_issuer() for more information. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="855">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="856">callback to call when the operation completes allow-none="1" closure="5"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="857">the data to pass to the callback function @@ -120002,28 +124796,28 @@ g_tls_database_lookup_certificate_issuer() for more information. version="2.30" throws="1"> Finish an asynchronous lookup issuer operation. See + filename="gio/gtlsdatabase.c" + line="888">Finish an asynchronous lookup issuer operation. See g_tls_database_lookup_certificate_issuer() for more information. - + a newly allocated issuer #GTlsCertificate, + filename="gio/gtlsdatabase.c" + line="897">a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="890">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="891">a #GAsyncResult. @@ -120031,18 +124825,19 @@ or %NULL. Use g_object_unref() to release the certificate. + throws="1" + glib:async-func="lookup_certificates_issued_by_async"> Look up certificates issued by this issuer in the database. + filename="gio/gtlsdatabase.c" + line="916">Look up certificates issued by this issuer in the database. This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform the lookup operation asynchronously. - + a newly allocated list of #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="930">a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. @@ -120051,14 +124846,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="918">a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. + filename="gio/gtlsdatabase.c" + line="919">a #GByteArray which holds the DER encoded issuer DN. @@ -120068,14 +124863,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="920">used to interact with the user if necessary Flags which affect the lookup operation. + filename="gio/gtlsdatabase.c" + line="921">Flags which affect the lookup operation. @@ -120084,38 +124879,40 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="922">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="lookup_certificates_issued_by_finish" + glib:sync-func="lookup_certificates_issued_by"> Asynchronously look up certificates issued by this issuer in the database. See + filename="gio/gtlsdatabase.c" + line="957">Asynchronously look up certificates issued by this issuer in the database. See g_tls_database_lookup_certificates_issued_by() for more information. The database may choose to hold a reference to the issuer byte array for the duration of this asynchronous operation. The byte array should not be modified during this time. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="959">a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. + filename="gio/gtlsdatabase.c" + line="960">a #GByteArray which holds the DER encoded issuer DN. @@ -120125,14 +124922,14 @@ this time. nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="961">used to interact with the user if necessary Flags which affect the lookup operation. + filename="gio/gtlsdatabase.c" + line="962">Flags which affect the lookup operation. @@ -120141,8 +124938,8 @@ this time. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="963">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="964">callback to call when the operation completes allow-none="1" closure="5"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="965">the data to pass to the callback function @@ -120173,14 +124970,14 @@ this time. version="2.30" throws="1"> Finish an asynchronous lookup of certificates. See + filename="gio/gtlsdatabase.c" + line="1000">Finish an asynchronous lookup of certificates. See g_tls_database_lookup_certificates_issued_by() for more information. - + a newly allocated list of #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="1009">a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. @@ -120189,14 +124986,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="1002">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="1003">a #GAsyncResult. @@ -120204,10 +125001,11 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele + throws="1" + glib:async-func="verify_chain_async"> Determines the validity of a certificate chain, outside the context + filename="gio/gtlsdatabase.c" + line="446">Determines the validity of a certificate chain, outside the context of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next @@ -120267,31 +125065,31 @@ certificates. This function can block. Use g_tls_database_verify_chain_async() to perform the verification operation asynchronously. - + the appropriate #GTlsCertificateFlags which represents the + filename="gio/gtlsdatabase.c" + line="518">the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="448">a #GTlsDatabase a #GTlsCertificate chain + filename="gio/gtlsdatabase.c" + line="449">a #GTlsCertificate chain the purpose that this certificate chain will be used for. + filename="gio/gtlsdatabase.c" + line="450">the purpose that this certificate chain will be used for. nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlsdatabase.c" + line="451">the expected peer identity nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="452">used to interact with the user if necessary additional verify flags + filename="gio/gtlsdatabase.c" + line="453">additional verify flags @@ -120324,41 +125122,43 @@ result of verification. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="454">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="verify_chain_finish" + glib:sync-func="verify_chain"> Asynchronously determines the validity of a certificate chain after + filename="gio/gtlsdatabase.c" + line="556">Asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See g_tls_database_verify_chain() for more information. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="558">a #GTlsDatabase a #GTlsCertificate chain + filename="gio/gtlsdatabase.c" + line="559">a #GTlsCertificate chain the purpose that this certificate chain will be used for. + filename="gio/gtlsdatabase.c" + line="560">the purpose that this certificate chain will be used for. nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlsdatabase.c" + line="561">the expected peer identity nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="562">used to interact with the user if necessary additional verify flags + filename="gio/gtlsdatabase.c" + line="563">additional verify flags @@ -120391,8 +125191,8 @@ g_tls_database_verify_chain() for more information. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="564">a #GCancellable, or %NULL scope="async" closure="7"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="565">callback to call when the operation completes allow-none="1" closure="7"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="566">the data to pass to the callback function @@ -120423,8 +125223,8 @@ g_tls_database_verify_chain() for more information. version="2.30" throws="1"> Finish an asynchronous verify chain operation. See + filename="gio/gtlsdatabase.c" + line="605">Finish an asynchronous verify chain operation. See g_tls_database_verify_chain() for more information. If @chain is found to be valid, then the return value will be 0. If @@ -120435,25 +125235,25 @@ before it completes) then the return value will be %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. - + the appropriate #GTlsCertificateFlags which represents the + filename="gio/gtlsdatabase.c" + line="623">the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="607">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="608">a #GAsyncResult. @@ -120462,8 +125262,8 @@ result of verification. c:identifier="g_tls_database_create_certificate_handle" version="2.30"> Create a handle string for the certificate. The database will only be able + filename="gio/gtlsdatabase.c" + line="643">Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, %NULL will be returned. @@ -120471,25 +125271,25 @@ will be returned. This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it. - + a newly allocated string containing the + filename="gio/gtlsdatabase.c" + line="657">a newly allocated string containing the handle. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="645">a #GTlsDatabase certificate for which to create a handle. + filename="gio/gtlsdatabase.c" + line="646">certificate for which to create a handle. @@ -120497,10 +125297,11 @@ handle. + throws="1" + glib:async-func="lookup_certificate_for_handle_async"> Look up a certificate by its handle. + filename="gio/gtlsdatabase.c" + line="673">Look up a certificate by its handle. The handle should have been created by calling g_tls_database_create_certificate_handle() on a #GTlsDatabase object of @@ -120512,25 +125313,25 @@ this database, then %NULL will be returned. This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform the lookup operation asynchronously. - + a newly allocated + filename="gio/gtlsdatabase.c" + line="695">a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="675">a #GTlsDatabase a certificate handle + filename="gio/gtlsdatabase.c" + line="676">a certificate handle nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="677">used to interact with the user if necessary Flags which affect the lookup. + filename="gio/gtlsdatabase.c" + line="678">Flags which affect the lookup. @@ -120554,34 +125355,36 @@ the lookup operation asynchronously. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="679">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="lookup_certificate_for_handle_finish" + glib:sync-func="lookup_certificate_for_handle"> Asynchronously look up a certificate by its handle in the database. See + filename="gio/gtlsdatabase.c" + line="723">Asynchronously look up a certificate by its handle in the database. See g_tls_database_lookup_certificate_for_handle() for more information. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="725">a #GTlsDatabase a certificate handle + filename="gio/gtlsdatabase.c" + line="726">a certificate handle nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="727">used to interact with the user if necessary Flags which affect the lookup. + filename="gio/gtlsdatabase.c" + line="728">Flags which affect the lookup. @@ -120605,8 +125408,8 @@ g_tls_database_lookup_certificate_for_handle() for more information. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="729">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="730">callback to call when the operation completes nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="731">the data to pass to the callback function @@ -120636,31 +125439,31 @@ g_tls_database_lookup_certificate_for_handle() for more information. version="2.30" throws="1"> Finish an asynchronous lookup of a certificate by its handle. See + filename="gio/gtlsdatabase.c" + line="761">Finish an asynchronous lookup of a certificate by its handle. See g_tls_database_lookup_certificate_for_handle() for more information. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. - + a newly allocated #GTlsCertificate object. + filename="gio/gtlsdatabase.c" + line="773">a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="763">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="764">a #GAsyncResult. @@ -120668,10 +125471,11 @@ Use g_object_unref() to release the certificate. + throws="1" + glib:async-func="lookup_certificate_issuer_async"> Look up the issuer of @certificate in the database. The + filename="gio/gtlsdatabase.c" + line="792">Look up the issuer of @certificate in the database. The #GTlsCertificate:issuer property of @certificate is not modified, and the two certificates are not hooked into a chain. @@ -120691,25 +125495,25 @@ which certification path will actually be used when verifying a TLS certificate. Accordingly, this function cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. - + a newly allocated issuer #GTlsCertificate, + filename="gio/gtlsdatabase.c" + line="822">a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="794">a #GTlsDatabase a #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="795">a #GTlsCertificate nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="796">used to interact with the user if necessary flags which affect the lookup operation + filename="gio/gtlsdatabase.c" + line="797">flags which affect the lookup operation @@ -120733,34 +125537,36 @@ or %NULL. Use g_object_unref() to release the certificate. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="798">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="lookup_certificate_issuer_finish" + glib:sync-func="lookup_certificate_issuer"> Asynchronously look up the issuer of @certificate in the database. See + filename="gio/gtlsdatabase.c" + line="849">Asynchronously look up the issuer of @certificate in the database. See g_tls_database_lookup_certificate_issuer() for more information. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="851">a #GTlsDatabase a #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="852">a #GTlsCertificate nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="853">used to interact with the user if necessary flags which affect the lookup operation + filename="gio/gtlsdatabase.c" + line="854">flags which affect the lookup operation @@ -120784,8 +125590,8 @@ g_tls_database_lookup_certificate_issuer() for more information. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="855">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="856">callback to call when the operation completes nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="857">the data to pass to the callback function @@ -120815,28 +125621,28 @@ g_tls_database_lookup_certificate_issuer() for more information. version="2.30" throws="1"> Finish an asynchronous lookup issuer operation. See + filename="gio/gtlsdatabase.c" + line="888">Finish an asynchronous lookup issuer operation. See g_tls_database_lookup_certificate_issuer() for more information. - + a newly allocated issuer #GTlsCertificate, + filename="gio/gtlsdatabase.c" + line="897">a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="890">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="891">a #GAsyncResult. @@ -120844,18 +125650,19 @@ or %NULL. Use g_object_unref() to release the certificate. + throws="1" + glib:async-func="lookup_certificates_issued_by_async"> Look up certificates issued by this issuer in the database. + filename="gio/gtlsdatabase.c" + line="916">Look up certificates issued by this issuer in the database. This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform the lookup operation asynchronously. - + a newly allocated list of #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="930">a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. @@ -120864,14 +125671,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="918">a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. + filename="gio/gtlsdatabase.c" + line="919">a #GByteArray which holds the DER encoded issuer DN. @@ -120881,14 +125688,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="920">used to interact with the user if necessary Flags which affect the lookup operation. + filename="gio/gtlsdatabase.c" + line="921">Flags which affect the lookup operation. @@ -120897,38 +125704,40 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="922">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="lookup_certificates_issued_by_finish" + glib:sync-func="lookup_certificates_issued_by"> Asynchronously look up certificates issued by this issuer in the database. See + filename="gio/gtlsdatabase.c" + line="957">Asynchronously look up certificates issued by this issuer in the database. See g_tls_database_lookup_certificates_issued_by() for more information. The database may choose to hold a reference to the issuer byte array for the duration of this asynchronous operation. The byte array should not be modified during this time. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="959">a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. + filename="gio/gtlsdatabase.c" + line="960">a #GByteArray which holds the DER encoded issuer DN. @@ -120938,14 +125747,14 @@ this time. nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="961">used to interact with the user if necessary Flags which affect the lookup operation. + filename="gio/gtlsdatabase.c" + line="962">Flags which affect the lookup operation. @@ -120954,8 +125763,8 @@ this time. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="963">a #GCancellable, or %NULL scope="async" closure="5"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="964">callback to call when the operation completes nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="965">the data to pass to the callback function @@ -120985,14 +125794,14 @@ this time. version="2.30" throws="1"> Finish an asynchronous lookup of certificates. See + filename="gio/gtlsdatabase.c" + line="1000">Finish an asynchronous lookup of certificates. See g_tls_database_lookup_certificates_issued_by() for more information. - + a newly allocated list of #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="1009">a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. @@ -121001,14 +125810,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="1002">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="1003">a #GAsyncResult. @@ -121016,10 +125825,11 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele + throws="1" + glib:async-func="verify_chain_async"> Determines the validity of a certificate chain, outside the context + filename="gio/gtlsdatabase.c" + line="446">Determines the validity of a certificate chain, outside the context of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next @@ -121079,31 +125889,31 @@ certificates. This function can block. Use g_tls_database_verify_chain_async() to perform the verification operation asynchronously. - + the appropriate #GTlsCertificateFlags which represents the + filename="gio/gtlsdatabase.c" + line="518">the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="448">a #GTlsDatabase a #GTlsCertificate chain + filename="gio/gtlsdatabase.c" + line="449">a #GTlsCertificate chain the purpose that this certificate chain will be used for. + filename="gio/gtlsdatabase.c" + line="450">the purpose that this certificate chain will be used for. nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlsdatabase.c" + line="451">the expected peer identity nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="452">used to interact with the user if necessary additional verify flags + filename="gio/gtlsdatabase.c" + line="453">additional verify flags @@ -121136,41 +125946,43 @@ result of verification. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="454">a #GCancellable, or %NULL + version="2.30" + glib:finish-func="verify_chain_finish" + glib:sync-func="verify_chain"> Asynchronously determines the validity of a certificate chain after + filename="gio/gtlsdatabase.c" + line="556">Asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See g_tls_database_verify_chain() for more information. - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="558">a #GTlsDatabase a #GTlsCertificate chain + filename="gio/gtlsdatabase.c" + line="559">a #GTlsCertificate chain the purpose that this certificate chain will be used for. + filename="gio/gtlsdatabase.c" + line="560">the purpose that this certificate chain will be used for. nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlsdatabase.c" + line="561">the expected peer identity nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="562">used to interact with the user if necessary additional verify flags + filename="gio/gtlsdatabase.c" + line="563">additional verify flags @@ -121203,8 +126015,8 @@ g_tls_database_verify_chain() for more information. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="564">a #GCancellable, or %NULL scope="async" closure="7"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="565">callback to call when the operation completes nullable="1" allow-none="1"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="566">the data to pass to the callback function @@ -121234,8 +126046,8 @@ g_tls_database_verify_chain() for more information. version="2.30" throws="1"> Finish an asynchronous verify chain operation. See + filename="gio/gtlsdatabase.c" + line="605">Finish an asynchronous verify chain operation. See g_tls_database_verify_chain() for more information. If @chain is found to be valid, then the return value will be 0. If @@ -121246,25 +126058,25 @@ before it completes) then the return value will be %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. - + the appropriate #GTlsCertificateFlags which represents the + filename="gio/gtlsdatabase.c" + line="623">the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="607">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="608">a #GAsyncResult. @@ -121281,41 +126093,45 @@ result of verification. glib:is-gtype-struct-for="TlsDatabase" version="2.30"> The class for #GTlsDatabase. Derived classes should implement the various + filename="gio/gtlsdatabase.c" + line="51">The class for #GTlsDatabase. Derived classes should implement the various virtual methods. _async and _finish methods have a default implementation that runs the corresponding sync method in a thread. - + + Virtual method implementing + g_tls_database_verify_chain(). - + the appropriate #GTlsCertificateFlags which represents the + filename="gio/gtlsdatabase.c" + line="518">the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="448">a #GTlsDatabase a #GTlsCertificate chain + filename="gio/gtlsdatabase.c" + line="449">a #GTlsCertificate chain the purpose that this certificate chain will be used for. + filename="gio/gtlsdatabase.c" + line="450">the purpose that this certificate chain will be used for. nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlsdatabase.c" + line="451">the expected peer identity nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="452">used to interact with the user if necessary additional verify flags + filename="gio/gtlsdatabase.c" + line="453">additional verify flags @@ -121348,36 +126164,40 @@ result of verification. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="454">a #GCancellable, or %NULL + Virtual method implementing + g_tls_database_verify_chain_async(). - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="558">a #GTlsDatabase a #GTlsCertificate chain + filename="gio/gtlsdatabase.c" + line="559">a #GTlsCertificate chain the purpose that this certificate chain will be used for. + filename="gio/gtlsdatabase.c" + line="560">the purpose that this certificate chain will be used for. nullable="1" allow-none="1"> the expected peer identity + filename="gio/gtlsdatabase.c" + line="561">the expected peer identity nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="562">used to interact with the user if necessary additional verify flags + filename="gio/gtlsdatabase.c" + line="563">additional verify flags @@ -121410,8 +126230,8 @@ result of verification. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="564">a #GCancellable, or %NULL scope="async" closure="8"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="565">callback to call when the operation completes allow-none="1" closure="8"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="566">the data to pass to the callback function + Virtual method implementing + g_tls_database_verify_chain_finish(). - + the appropriate #GTlsCertificateFlags which represents the + filename="gio/gtlsdatabase.c" + line="623">the appropriate #GTlsCertificateFlags which represents the result of verification. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="607">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="608">a #GAsyncResult. + Virtual method implementing + g_tls_database_create_certificate_handle(). - + a newly allocated string containing the + filename="gio/gtlsdatabase.c" + line="657">a newly allocated string containing the handle. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="645">a #GTlsDatabase certificate for which to create a handle. + filename="gio/gtlsdatabase.c" + line="646">certificate for which to create a handle. + Virtual method implementing + g_tls_database_lookup_certificate_for_handle(). - + a newly allocated + filename="gio/gtlsdatabase.c" + line="695">a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="675">a #GTlsDatabase a certificate handle + filename="gio/gtlsdatabase.c" + line="676">a certificate handle nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="677">used to interact with the user if necessary Flags which affect the lookup. + filename="gio/gtlsdatabase.c" + line="678">Flags which affect the lookup. @@ -121534,30 +126366,34 @@ handle. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="679">a #GCancellable, or %NULL + Virtual method implementing + g_tls_database_lookup_certificate_for_handle_async(). - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="725">a #GTlsDatabase a certificate handle + filename="gio/gtlsdatabase.c" + line="726">a certificate handle nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="727">used to interact with the user if necessary Flags which affect the lookup. + filename="gio/gtlsdatabase.c" + line="728">Flags which affect the lookup. @@ -121581,8 +126417,8 @@ handle. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="729">a #GCancellable, or %NULL scope="async" closure="6"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="730">callback to call when the operation completes allow-none="1" closure="6"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="731">the data to pass to the callback function + Virtual method implementing + g_tls_database_lookup_certificate_for_handle_finish(). - + a newly allocated #GTlsCertificate object. + filename="gio/gtlsdatabase.c" + line="773">a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="763">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="764">a #GAsyncResult. + Virtual method implementing + g_tls_database_lookup_certificate_issuer(). - + a newly allocated issuer #GTlsCertificate, + filename="gio/gtlsdatabase.c" + line="822">a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="794">a #GTlsDatabase a #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="795">a #GTlsCertificate nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="796">used to interact with the user if necessary flags which affect the lookup operation + filename="gio/gtlsdatabase.c" + line="797">flags which affect the lookup operation @@ -121679,30 +126523,34 @@ or %NULL. Use g_object_unref() to release the certificate. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="798">a #GCancellable, or %NULL + Virtual method implementing + g_tls_database_lookup_certificate_issuer_async(). - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="851">a #GTlsDatabase a #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="852">a #GTlsCertificate nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="853">used to interact with the user if necessary flags which affect the lookup operation + filename="gio/gtlsdatabase.c" + line="854">flags which affect the lookup operation @@ -121726,8 +126574,8 @@ or %NULL. Use g_object_unref() to release the certificate. nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="855">a #GCancellable, or %NULL scope="async" closure="6"> callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="856">callback to call when the operation completes allow-none="1" closure="6"> the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="857">the data to pass to the callback function + Virtual method implementing + g_tls_database_lookup_certificate_issuer_finish(). - + a newly allocated issuer #GTlsCertificate, + filename="gio/gtlsdatabase.c" + line="897">a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="890">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="891">a #GAsyncResult. + Virtual method implementing + g_tls_database_lookup_certificates_issued_by(). - + a newly allocated list of #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="930">a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. @@ -121795,14 +126651,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="918">a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. + filename="gio/gtlsdatabase.c" + line="919">a #GByteArray which holds the DER encoded issuer DN. @@ -121812,14 +126668,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="920">used to interact with the user if necessary Flags which affect the lookup operation. + filename="gio/gtlsdatabase.c" + line="921">Flags which affect the lookup operation. @@ -121828,30 +126684,34 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="922">a #GCancellable, or %NULL + Virtual method implementing + g_tls_database_lookup_certificates_issued_by_async(). - + a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="959">a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. + filename="gio/gtlsdatabase.c" + line="960">a #GByteArray which holds the DER encoded issuer DN. @@ -121861,14 +126721,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> used to interact with the user if necessary + filename="gio/gtlsdatabase.c" + line="961">used to interact with the user if necessary Flags which affect the lookup operation. + filename="gio/gtlsdatabase.c" + line="962">Flags which affect the lookup operation. @@ -121877,8 +126737,8 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele nullable="1" allow-none="1"> a #GCancellable, or %NULL + filename="gio/gtlsdatabase.c" + line="963">a #GCancellable, or %NULL callback to call when the operation completes + filename="gio/gtlsdatabase.c" + line="964">callback to call when the operation completes the data to pass to the callback function + filename="gio/gtlsdatabase.c" + line="965">the data to pass to the callback function + Virtual method implementing + g_tls_database_lookup_certificates_issued_by_finish(). - + a newly allocated list of #GTlsCertificate + filename="gio/gtlsdatabase.c" + line="1009">a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. @@ -121920,14 +126784,14 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele a #GTlsDatabase + filename="gio/gtlsdatabase.c" + line="1002">a #GTlsDatabase a #GAsyncResult. + filename="gio/gtlsdatabase.c" + line="1003">a #GAsyncResult. @@ -121945,8 +126809,8 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele glib:get-type="g_tls_database_lookup_flags_get_type" c:type="GTlsDatabaseLookupFlags"> Flags for g_tls_database_lookup_certificate_for_handle(), + filename="gio/gioenums.h" + line="1852">Flags for g_tls_database_lookup_certificate_for_handle(), g_tls_database_lookup_certificate_issuer(), and g_tls_database_lookup_certificates_issued_by(). glib:nick="none" glib:name="G_TLS_DATABASE_LOOKUP_NONE"> No lookup flags + filename="gio/gioenums.h" + line="1854">No lookup flags glib:nick="keypair" glib:name="G_TLS_DATABASE_LOOKUP_KEYPAIR"> Restrict lookup to certificates that have + filename="gio/gioenums.h" + line="1855">Restrict lookup to certificates that have a private key. @@ -121973,7 +126837,7 @@ and g_tls_database_lookup_certificates_issued_by(). c:type="GTlsDatabasePrivate" disguised="1" opaque="1"> - + glib:get-type="g_tls_database_verify_flags_get_type" c:type="GTlsDatabaseVerifyFlags"> Flags for g_tls_database_verify_chain(). + filename="gio/gioenums.h" + line="1840">Flags for g_tls_database_verify_chain(). No verification flags + filename="gio/gioenums.h" + line="1842">No verification flags c:type="GTlsError" glib:error-domain="g-tls-error-quark"> An error code used with %G_TLS_ERROR in a #GError returned from a + filename="gio/gioenums.h" + line="1572">An error code used with %G_TLS_ERROR in a #GError returned from a TLS-related routine. glib:nick="unavailable" glib:name="G_TLS_ERROR_UNAVAILABLE"> No TLS provider is available + filename="gio/gioenums.h" + line="1574">No TLS provider is available glib:nick="misc" glib:name="G_TLS_ERROR_MISC"> Miscellaneous TLS error + filename="gio/gioenums.h" + line="1575">Miscellaneous TLS error glib:nick="bad-certificate" glib:name="G_TLS_ERROR_BAD_CERTIFICATE"> The certificate presented could not + filename="gio/gioenums.h" + line="1576">The certificate presented could not be parsed or failed validation. glib:nick="not-tls" glib:name="G_TLS_ERROR_NOT_TLS"> The TLS handshake failed because the + filename="gio/gioenums.h" + line="1578">The TLS handshake failed because the peer does not seem to be a TLS server. glib:nick="handshake" glib:name="G_TLS_ERROR_HANDSHAKE"> The TLS handshake failed because the + filename="gio/gioenums.h" + line="1580">The TLS handshake failed because the peer's certificate was not acceptable. glib:nick="certificate-required" glib:name="G_TLS_ERROR_CERTIFICATE_REQUIRED"> The TLS handshake failed because + filename="gio/gioenums.h" + line="1582">The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate(). @@ -122068,8 +126932,8 @@ TLS-related routine. glib:nick="eof" glib:name="G_TLS_ERROR_EOF"> The TLS connection was closed without proper + filename="gio/gioenums.h" + line="1585">The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify(). @@ -122079,8 +126943,8 @@ TLS-related routine. glib:nick="inappropriate-fallback" glib:name="G_TLS_ERROR_INAPPROPRIATE_FALLBACK"> The TLS handshake failed + filename="gio/gioenums.h" + line="1588">The TLS handshake failed because the client sent the fallback SCSV, indicating a protocol downgrade attack. Since: 2.60 @@ -122090,18 +126954,18 @@ TLS-related routine. glib:nick="bad-certificate-password" glib:name="G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD"> The certificate failed + filename="gio/gioenums.h" + line="1591">The certificate failed to load because a password was incorrect. Since: 2.72 Gets the TLS error quark. + filename="gio/gtlsconnection.c" + line="1094">Gets the TLS error quark. a #GQuark. + filename="gio/gtlsconnection.c" + line="1099">a #GQuark. @@ -122114,35 +126978,35 @@ TLS-related routine. glib:get-type="g_tls_file_database_get_type" glib:type-struct="TlsFileDatabaseInterface"> #GTlsFileDatabase is implemented by #GTlsDatabase objects which load -their certificate information from a file. It is an interface which + filename="gio/gtlsfiledatabase.c" + line="32">`GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which +load their certificate information from a file. It is an interface which TLS library specific subtypes implement. - + Creates a new #GTlsFileDatabase which uses anchor certificate authorities + filename="gio/gtlsfiledatabase.c" + line="65">Creates a new #GTlsFileDatabase which uses anchor certificate authorities in @anchors to verify certificate chains. The certificates in @anchors must be PEM encoded. - + the new + filename="gio/gtlsfiledatabase.c" + line="75">the new #GTlsFileDatabase, or %NULL on error filename of anchor certificate authorities. + filename="gio/gtlsfiledatabase.c" + line="67">filename of anchor certificate authorities. @@ -122154,8 +127018,8 @@ The certificates in @anchors must be PEM encoded. transfer-ownership="none" default-value="NULL"> The path to a file containing PEM encoded certificate authority + filename="gio/gtlsfiledatabase.c" + line="47">The path to a file containing PEM encoded certificate authority root anchors. The certificates in this file will be treated as root authorities for the purpose of verifying other certificates via the g_tls_database_verify_chain() operation. @@ -122166,12 +127030,12 @@ via the g_tls_database_verify_chain() operation. c:type="GTlsFileDatabaseInterface" glib:is-gtype-struct-for="TlsFileDatabase"> Provides an interface for #GTlsFileDatabase implementations. - + The parent interface. @@ -122190,35 +127054,36 @@ via the g_tls_database_verify_chain() operation. glib:get-type="g_tls_interaction_get_type" glib:type-struct="TlsInteractionClass"> #GTlsInteraction provides a mechanism for the TLS connection and database + filename="gio/gtlsinteraction.c" + line="38">`GTlsInteraction` provides a mechanism for the TLS connection and database code to interact with the user. It can be used to ask the user for passwords. -To use a #GTlsInteraction with a TLS connection use -g_tls_connection_set_interaction(). +To use a `GTlsInteraction` with a TLS connection use +[method@Gio.TlsConnection.set_interaction]. Callers should instantiate a derived class that implements the various interaction methods to show the required dialogs. Callers should use the 'invoke' functions like -g_tls_interaction_invoke_ask_password() to run interaction methods. These -functions make sure that the interaction is invoked in the main loop +[method@Gio.TlsInteraction.invoke_ask_password] to run interaction methods. +These functions make sure that the interaction is invoked in the main loop and not in the current thread, if the current thread is not running the main loop. -Derived classes can choose to implement whichever interactions methods they'd +Derived classes can choose to implement whichever interactions methods they’d like to support by overriding those virtual methods in their class initialization function. Any interactions not implemented will return -%G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, +`G_TLS_INTERACTION_UNHANDLED`. If a derived class implements an async method, it must also implement the corresponding finish method. - + + throws="1" + glib:async-func="ask_password_async"> Run synchronous interaction to ask the user for a password. In general, + filename="gio/gtlsinteraction.c" + line="404">Run synchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. @@ -122231,24 +127096,24 @@ If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="425">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="406">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="407">a #GTlsPassword object nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="408">an optional #GCancellable cancellation object + version="2.30" + glib:finish-func="ask_password_finish" + glib:sync-func="ask_password"> Run asynchronous interaction to ask the user for a password. In general, + filename="gio/gtlsinteraction.c" + line="448">Run asynchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. @@ -122282,21 +127149,21 @@ contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Certain implementations may not support immediate cancellation. - + a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="450">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="451">a #GTlsPassword object nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="452">an optional #GCancellable cancellation object scope="async" closure="3"> will be called when the interaction completes + filename="gio/gtlsinteraction.c" + line="453">will be called when the interaction completes allow-none="1" closure="3"> data to pass to the @callback + filename="gio/gtlsinteraction.c" + line="454">data to pass to the @callback @@ -122336,8 +127203,8 @@ Certain implementations may not support immediate cancellation. version="2.30" throws="1"> Complete an ask password user interaction request. This should be once + filename="gio/gtlsinteraction.c" + line="504">Complete an ask password user interaction request. This should be once the g_tls_interaction_ask_password_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed @@ -122346,24 +127213,24 @@ to g_tls_interaction_ask_password() will have its password filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="520">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="506">a #GTlsInteraction object the result passed to the callback + filename="gio/gtlsinteraction.c" + line="507">the result passed to the callback @@ -122371,10 +127238,11 @@ contains a %G_IO_ERROR_CANCELLED error code. + throws="1" + glib:async-func="request_certificate_async"> Run synchronous interaction to ask the user to choose a certificate to use + filename="gio/gtlsinteraction.c" + line="695">Run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. @@ -122390,30 +127258,30 @@ If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. - + The status of the request certificate interaction. + filename="gio/gtlsinteraction.c" + line="720">The status of the request certificate interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="697">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="698">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="699">flags providing more information about the request @@ -122422,18 +127290,20 @@ not support immediate cancellation. nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="700">an optional #GCancellable cancellation object + version="2.40" + glib:finish-func="request_certificate_finish" + glib:sync-func="request_certificate"> Run asynchronous interaction to ask the user for a certificate to use with + filename="gio/gtlsinteraction.c" + line="744">Run asynchronous interaction to ask the user for a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. @@ -122441,27 +127311,27 @@ Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. @callback will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. - + a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="746">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="747">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="748">flags providing more information about the request @@ -122470,8 +127340,8 @@ request, which will usually abort the TLS connection. nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="749">an optional #GCancellable cancellation object scope="async" closure="4"> will be called when the interaction completes + filename="gio/gtlsinteraction.c" + line="750">will be called when the interaction completes allow-none="1" closure="4"> data to pass to the @callback + filename="gio/gtlsinteraction.c" + line="751">data to pass to the @callback @@ -122502,8 +127372,8 @@ request, which will usually abort the TLS connection. version="2.40" throws="1"> Complete a request certificate user interaction request. This should be once + filename="gio/gtlsinteraction.c" + line="795">Complete a request certificate user interaction request. This should be once the g_tls_interaction_request_certificate_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection @@ -122513,24 +127383,24 @@ passed to g_tls_interaction_request_certificate_async() will have had its If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. - + The status of the request certificate interaction. + filename="gio/gtlsinteraction.c" + line="812">The status of the request certificate interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="797">a #GTlsInteraction object the result passed to the callback + filename="gio/gtlsinteraction.c" + line="798">the result passed to the callback @@ -122538,10 +127408,11 @@ contains a %G_IO_ERROR_CANCELLED error code. + throws="1" + glib:async-func="ask_password_async"> Run synchronous interaction to ask the user for a password. In general, + filename="gio/gtlsinteraction.c" + line="404">Run synchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. @@ -122554,24 +127425,24 @@ If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="425">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="406">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="407">a #GTlsPassword object nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="408">an optional #GCancellable cancellation object + version="2.30" + glib:finish-func="ask_password_finish" + glib:sync-func="ask_password"> Run asynchronous interaction to ask the user for a password. In general, + filename="gio/gtlsinteraction.c" + line="448">Run asynchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function. @@ -122605,21 +127478,21 @@ contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Certain implementations may not support immediate cancellation. - + a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="450">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="451">a #GTlsPassword object nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="452">an optional #GCancellable cancellation object scope="async" closure="3"> will be called when the interaction completes + filename="gio/gtlsinteraction.c" + line="453">will be called when the interaction completes nullable="1" allow-none="1"> data to pass to the @callback + filename="gio/gtlsinteraction.c" + line="454">data to pass to the @callback @@ -122658,8 +127531,8 @@ Certain implementations may not support immediate cancellation. version="2.30" throws="1"> Complete an ask password user interaction request. This should be once + filename="gio/gtlsinteraction.c" + line="504">Complete an ask password user interaction request. This should be once the g_tls_interaction_ask_password_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed @@ -122668,24 +127541,24 @@ to g_tls_interaction_ask_password() will have its password filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="520">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="506">a #GTlsInteraction object the result passed to the callback + filename="gio/gtlsinteraction.c" + line="507">the result passed to the callback @@ -122695,8 +127568,8 @@ contains a %G_IO_ERROR_CANCELLED error code. version="2.30" throws="1"> Invoke the interaction to ask the user for a password. It invokes this + filename="gio/gtlsinteraction.c" + line="332">Invoke the interaction to ask the user for a password. It invokes this interaction in the main loop, specifically the #GMainContext returned by g_main_context_get_thread_default() when the interaction is created. This is called by called by #GTlsConnection or #GTlsDatabase to ask the user @@ -122715,24 +127588,24 @@ If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="359">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="334">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="335">a #GTlsPassword object nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="336">an optional #GCancellable cancellation object @@ -122751,8 +127624,8 @@ not support immediate cancellation. version="2.40" throws="1"> Invoke the interaction to ask the user to choose a certificate to + filename="gio/gtlsinteraction.c" + line="620">Invoke the interaction to ask the user to choose a certificate to use with the connection. It invokes this interaction in the main loop, specifically the #GMainContext returned by g_main_context_get_thread_default() when the interaction is @@ -122772,30 +127645,30 @@ If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. - + The status of the certificate request interaction. + filename="gio/gtlsinteraction.c" + line="649">The status of the certificate request interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="622">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="623">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="624">flags providing more information about the request @@ -122804,8 +127677,8 @@ not support immediate cancellation. nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="625">an optional #GCancellable cancellation object @@ -122813,10 +127686,11 @@ not support immediate cancellation. + throws="1" + glib:async-func="request_certificate_async"> Run synchronous interaction to ask the user to choose a certificate to use + filename="gio/gtlsinteraction.c" + line="695">Run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. @@ -122832,30 +127706,30 @@ If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. - + The status of the request certificate interaction. + filename="gio/gtlsinteraction.c" + line="720">The status of the request certificate interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="697">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="698">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="699">flags providing more information about the request @@ -122864,18 +127738,20 @@ not support immediate cancellation. nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="700">an optional #GCancellable cancellation object + version="2.40" + glib:finish-func="request_certificate_finish" + glib:sync-func="request_certificate"> Run asynchronous interaction to ask the user for a certificate to use with + filename="gio/gtlsinteraction.c" + line="744">Run asynchronous interaction to ask the user for a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. @@ -122883,27 +127759,27 @@ Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. @callback will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. - + a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="746">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="747">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="748">flags providing more information about the request @@ -122912,8 +127788,8 @@ request, which will usually abort the TLS connection. nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="749">an optional #GCancellable cancellation object scope="async" closure="4"> will be called when the interaction completes + filename="gio/gtlsinteraction.c" + line="750">will be called when the interaction completes nullable="1" allow-none="1"> data to pass to the @callback + filename="gio/gtlsinteraction.c" + line="751">data to pass to the @callback @@ -122943,8 +127819,8 @@ request, which will usually abort the TLS connection. version="2.40" throws="1"> Complete a request certificate user interaction request. This should be once + filename="gio/gtlsinteraction.c" + line="795">Complete a request certificate user interaction request. This should be once the g_tls_interaction_request_certificate_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection @@ -122954,24 +127830,24 @@ passed to g_tls_interaction_request_certificate_async() will have had its If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. - + The status of the request certificate interaction. + filename="gio/gtlsinteraction.c" + line="812">The status of the request certificate interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="797">a #GTlsInteraction object the result passed to the callback + filename="gio/gtlsinteraction.c" + line="798">the result passed to the callback @@ -122988,8 +127864,8 @@ contains a %G_IO_ERROR_CANCELLED error code. glib:is-gtype-struct-for="TlsInteraction" version="2.30"> The class for #GTlsInteraction. Derived classes implement the various + filename="gio/gtlsinteraction.c" + line="65">The class for #GTlsInteraction. Derived classes implement the various virtual interaction methods to handle TLS interactions. Derived classes can choose to implement whichever interactions methods they'd @@ -123003,30 +127879,36 @@ and the asynchronous methods to display modeless dialogs. If the user cancels an interaction, then the result should be %G_TLS_INTERACTION_FAILED and the error should be set with a domain of %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED. - + + ask for a password synchronously. If the implementation + returns %G_TLS_INTERACTION_HANDLED, then the password argument should + have been filled in by using g_tls_password_set_value() or a similar + function. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="425">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="406">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="407">a #GTlsPassword object an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="408">an optional #GCancellable cancellation object + ask for a password asynchronously. - + a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="450">a #GTlsInteraction object a #GTlsPassword object + filename="gio/gtlsinteraction.c" + line="451">a #GTlsPassword object an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="452">an optional #GCancellable cancellation object will be called when the interaction completes + filename="gio/gtlsinteraction.c" + line="453">will be called when the interaction completes data to pass to the @callback + filename="gio/gtlsinteraction.c" + line="454">data to pass to the @callback + complete operation to ask for a password asynchronously. + If the implementation returns %G_TLS_INTERACTION_HANDLED, then the + password argument of the async method should have been filled in by using + g_tls_password_set_value() or a similar function. - + The status of the ask password interaction. + filename="gio/gtlsinteraction.c" + line="520">The status of the ask password interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="506">a #GTlsInteraction object the result passed to the callback + filename="gio/gtlsinteraction.c" + line="507">the result passed to the callback + ask for a certificate synchronously. If the + implementation returns %G_TLS_INTERACTION_HANDLED, then the connection + argument should have been filled in by using + g_tls_connection_set_certificate(). - + The status of the request certificate interaction. + filename="gio/gtlsinteraction.c" + line="720">The status of the request certificate interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="697">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="698">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="699">flags providing more information about the request @@ -123152,36 +128049,39 @@ If the user cancels an interaction, then the result should be nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="700">an optional #GCancellable cancellation object + ask for a certificate asynchronously. - + a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="746">a #GTlsInteraction object a #GTlsConnection object + filename="gio/gtlsinteraction.c" + line="747">a #GTlsConnection object flags providing more information about the request + filename="gio/gtlsinteraction.c" + line="748">flags providing more information about the request @@ -123190,8 +128090,8 @@ If the user cancels an interaction, then the result should be nullable="1" allow-none="1"> an optional #GCancellable cancellation object + filename="gio/gtlsinteraction.c" + line="749">an optional #GCancellable cancellation object will be called when the interaction completes + filename="gio/gtlsinteraction.c" + line="750">will be called when the interaction completes data to pass to the @callback + filename="gio/gtlsinteraction.c" + line="751">data to pass to the @callback + complete operation to ask for a certificate + asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, + then the connection argument of the async method should have been + filled in by using g_tls_connection_set_certificate(). - + The status of the request certificate interaction. + filename="gio/gtlsinteraction.c" + line="812">The status of the request certificate interaction. a #GTlsInteraction object + filename="gio/gtlsinteraction.c" + line="797">a #GTlsInteraction object the result passed to the callback + filename="gio/gtlsinteraction.c" + line="798">the result passed to the callback @@ -123253,7 +128159,7 @@ If the user cancels an interaction, then the result should be c:type="GTlsInteractionPrivate" disguised="1" opaque="1"> - + #GTlsInteractionResult is returned by various functions in #GTlsInteraction + filename="gio/gioenums.h" + line="1784">#GTlsInteractionResult is returned by various functions in #GTlsInteraction when finishing an interaction request. glib:nick="unhandled" glib:name="G_TLS_INTERACTION_UNHANDLED"> The interaction was unhandled (i.e. not + filename="gio/gioenums.h" + line="1786">The interaction was unhandled (i.e. not implemented). glib:nick="handled" glib:name="G_TLS_INTERACTION_HANDLED"> The interaction completed, and resulting data + filename="gio/gioenums.h" + line="1788">The interaction completed, and resulting data is available. glib:nick="failed" glib:name="G_TLS_INTERACTION_FAILED"> The interaction has failed, or was cancelled. + filename="gio/gioenums.h" + line="1790">The interaction has failed, or was cancelled. and the operation should be aborted. @@ -123304,37 +128210,42 @@ when finishing an interaction request. glib:get-type="g_tls_password_get_type" glib:type-struct="TlsPasswordClass"> Holds a password used in TLS. - + filename="gio/gtlspassword.c" + line="32">An abstract interface representing a password used in TLS. Often used in +user interaction such as unlocking a key storage token. + Create a new #GTlsPassword object. - + filename="gio/gtlspassword.c" + line="232">Create a new #GTlsPassword object. + The newly allocated password object + filename="gio/gtlspassword.c" + line="239">The newly allocated password object the password flags + filename="gio/gtlspassword.c" + line="234">the password flags description of what the password is for + filename="gio/gtlspassword.c" + line="235">description of what the password is for - + virtual method for g_tls_password_get_warning() if no + value has been set using g_tls_password_set_warning() + @@ -123346,17 +128257,17 @@ when finishing an interaction request. Get the password value. If @length is not %NULL then it will be + filename="gio/gtlspassword.c" + line="251">Get the password value. If @length is not %NULL then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass %NULL for @length in contexts where you know the password will have a certain fixed length.) - + The password value (owned by the password object). + filename="gio/gtlspassword.c" + line="262">The password value (owned by the password object). @@ -123364,25 +128275,27 @@ certain fixed length.) a #GTlsPassword object + filename="gio/gtlspassword.c" + line="253">a #GTlsPassword object + caller-allocates="1" + transfer-ownership="full" + optional="1" + allow-none="1"> location to place the length of the password. + filename="gio/gtlspassword.c" + line="254">location to place the length of the password. Provide the value for this password. + filename="gio/gtlspassword.c" + line="308">Provide the value for this password. The @value will be owned by the password object, and later freed using the @destroy function callback. @@ -123391,29 +128304,29 @@ Specify the @length, for a non-nul-terminated password. Pass -1 as @length if using a nul-terminated password, and @length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) - + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="310">a #GTlsPassword object the value for the password + filename="gio/gtlspassword.c" + line="311">the value for the password the length of the password, or -1 + filename="gio/gtlspassword.c" + line="312">the length of the password, or -1 allow-none="1" scope="async"> a function to use to free the password. + filename="gio/gtlspassword.c" + line="313">a function to use to free the password. @@ -123433,20 +128346,20 @@ considered part of the password in this case.) glib:get-property="description" version="2.30"> Get a description string about what the password will be used for. - + filename="gio/gtlspassword.c" + line="375">Get a description string about what the password will be used for. + The description of the password. + filename="gio/gtlspassword.c" + line="381">The description of the password. a #GTlsPassword object + filename="gio/gtlspassword.c" + line="377">a #GTlsPassword object @@ -123456,20 +128369,20 @@ considered part of the password in this case.) glib:get-property="flags" version="2.30"> Get flags about the password. - + filename="gio/gtlspassword.c" + line="338">Get flags about the password. + The flags about the password. + filename="gio/gtlspassword.c" + line="344">The flags about the password. a #GTlsPassword object + filename="gio/gtlspassword.c" + line="340">a #GTlsPassword object @@ -123478,17 +128391,17 @@ considered part of the password in this case.) c:identifier="g_tls_password_get_value" version="2.30"> Get the password value. If @length is not %NULL then it will be + filename="gio/gtlspassword.c" + line="251">Get the password value. If @length is not %NULL then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass %NULL for @length in contexts where you know the password will have a certain fixed length.) - + The password value (owned by the password object). + filename="gio/gtlspassword.c" + line="262">The password value (owned by the password object). @@ -123496,17 +128409,19 @@ certain fixed length.) a #GTlsPassword object + filename="gio/gtlspassword.c" + line="253">a #GTlsPassword object + caller-allocates="1" + transfer-ownership="full" + optional="1" + allow-none="1"> location to place the length of the password. + filename="gio/gtlspassword.c" + line="254">location to place the length of the password. @@ -123516,22 +128431,22 @@ certain fixed length.) glib:get-property="warning" version="2.30"> Get a user readable translated warning. Usually this warning is a + filename="gio/gtlspassword.c" + line="416">Get a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). - + The warning. + filename="gio/gtlspassword.c" + line="424">The warning. a #GTlsPassword object + filename="gio/gtlspassword.c" + line="418">a #GTlsPassword object @@ -123541,23 +128456,23 @@ g_tls_password_get_flags(). glib:set-property="description" version="2.30"> Set a description string about what the password will be used for. - + filename="gio/gtlspassword.c" + line="392">Set a description string about what the password will be used for. + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="394">a #GTlsPassword object The description of the password + filename="gio/gtlspassword.c" + line="395">The description of the password @@ -123567,23 +128482,23 @@ g_tls_password_get_flags(). glib:set-property="flags" version="2.30"> Set flags about the password. - + filename="gio/gtlspassword.c" + line="355">Set flags about the password. + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="357">a #GTlsPassword object The flags about the password + filename="gio/gtlspassword.c" + line="358">The flags about the password @@ -123592,37 +128507,37 @@ g_tls_password_get_flags(). c:identifier="g_tls_password_set_value" version="2.30"> Set the value for this password. The @value will be copied by the password + filename="gio/gtlspassword.c" + line="274">Set the value for this password. The @value will be copied by the password object. Specify the @length, for a non-nul-terminated password. Pass -1 as @length if using a nul-terminated password, and @length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) - + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="276">a #GTlsPassword object the new password value + filename="gio/gtlspassword.c" + line="277">the new password value the length of the password, or -1 + filename="gio/gtlspassword.c" + line="278">the length of the password, or -1 @@ -123631,8 +128546,8 @@ considered part of the password in this case.) c:identifier="g_tls_password_set_value_full" version="2.30"> Provide the value for this password. + filename="gio/gtlspassword.c" + line="308">Provide the value for this password. The @value will be owned by the password object, and later freed using the @destroy function callback. @@ -123641,29 +128556,29 @@ Specify the @length, for a non-nul-terminated password. Pass -1 as @length if using a nul-terminated password, and @length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) - + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="310">a #GTlsPassword object the value for the password + filename="gio/gtlspassword.c" + line="311">the value for the password the length of the password, or -1 + filename="gio/gtlspassword.c" + line="312">the length of the password, or -1 allow-none="1" scope="async"> a function to use to free the password. + filename="gio/gtlspassword.c" + line="313">a function to use to free the password. @@ -123683,51 +128598,63 @@ considered part of the password in this case.) glib:set-property="warning" version="2.30"> Set a user readable translated warning. Usually this warning is a + filename="gio/gtlspassword.c" + line="439">Set a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). - + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="441">a #GTlsPassword object The user readable warning + filename="gio/gtlspassword.c" + line="442">The user readable warning + Description of what the password is for. + Flags about the password. + Warning about the password. @@ -123741,19 +128668,22 @@ g_tls_password_get_flags(). c:type="GTlsPasswordClass" glib:is-gtype-struct-for="TlsPassword"> Class structure for #GTlsPassword. - + + virtual method for g_tls_password_get_value() - + The password value (owned by the password object). + filename="gio/gtlspassword.c" + line="262">The password value (owned by the password object). @@ -123761,47 +128691,52 @@ g_tls_password_get_flags(). a #GTlsPassword object + filename="gio/gtlspassword.c" + line="253">a #GTlsPassword object + caller-allocates="1" + transfer-ownership="full" + optional="1" + allow-none="1"> location to place the length of the password. + filename="gio/gtlspassword.c" + line="254">location to place the length of the password. + virtual method for g_tls_password_set_value() - + a #GTlsPassword object + filename="gio/gtlspassword.c" + line="310">a #GTlsPassword object the value for the password + filename="gio/gtlspassword.c" + line="311">the value for the password the length of the password, or -1 + filename="gio/gtlspassword.c" + line="312">the length of the password, or -1 allow-none="1" scope="async"> a function to use to free the password. + filename="gio/gtlspassword.c" + line="313">a function to use to free the password. + virtual method for g_tls_password_get_warning() if no + value has been set using g_tls_password_set_warning() - + @@ -123842,16 +128781,16 @@ g_tls_password_get_flags(). glib:get-type="g_tls_password_flags_get_type" c:type="GTlsPasswordFlags"> Various flags for the password. + filename="gio/gioenums.h" + line="1753">Various flags for the password. No flags + filename="gio/gioenums.h" + line="1755">No flags glib:nick="retry" glib:name="G_TLS_PASSWORD_RETRY"> The password was wrong, and the user should retry. + filename="gio/gioenums.h" + line="1756">The password was wrong, and the user should retry. glib:nick="many-tries" glib:name="G_TLS_PASSWORD_MANY_TRIES"> Hint to the user that the password has been + filename="gio/gioenums.h" + line="1757">Hint to the user that the password has been wrong many times, and the user may not have many chances left. glib:nick="final-try" glib:name="G_TLS_PASSWORD_FINAL_TRY"> Hint to the user that this is the last try to get + filename="gio/gioenums.h" + line="1759">Hint to the user that this is the last try to get this password right. glib:nick="pkcs11-user" glib:name="G_TLS_PASSWORD_PKCS11_USER"> For PKCS #11, the user PIN is required. + filename="gio/gioenums.h" + line="1761">For PKCS #11, the user PIN is required. Since: 2.70. glib:nick="pkcs11-security-officer" glib:name="G_TLS_PASSWORD_PKCS11_SECURITY_OFFICER"> For PKCS #11, the security officer + filename="gio/gioenums.h" + line="1763">For PKCS #11, the security officer PIN is required. Since: 2.70. glib:nick="pkcs11-context-specific" glib:name="G_TLS_PASSWORD_PKCS11_CONTEXT_SPECIFIC"> For PKCS #11, the context-specific + filename="gio/gioenums.h" + line="1765">For PKCS #11, the context-specific PIN is required. Since: 2.70. @@ -123917,7 +128856,7 @@ g_tls_password_get_flags(). c:type="GTlsPasswordPrivate" disguised="1" opaque="1"> - + glib:get-type="g_tls_protocol_version_get_type" c:type="GTlsProtocolVersion"> The TLS or DTLS protocol version used by a #GTlsConnection or + filename="gio/gioenums.h" + line="1883">The TLS or DTLS protocol version used by a #GTlsConnection or #GDtlsConnection. The integer values of these versions are sequential to ensure newer known protocol versions compare greater than older known versions. Any known DTLS protocol version will compare greater @@ -123941,8 +128880,8 @@ than the TLS protocol versions. glib:nick="unknown" glib:name="G_TLS_PROTOCOL_VERSION_UNKNOWN"> No protocol version or unknown protocol version + filename="gio/gioenums.h" + line="1885">No protocol version or unknown protocol version glib:nick="ssl-3-0" glib:name="G_TLS_PROTOCOL_VERSION_SSL_3_0"> SSL 3.0, which is insecure and should not be used + filename="gio/gioenums.h" + line="1886">SSL 3.0, which is insecure and should not be used glib:nick="tls-1-0" glib:name="G_TLS_PROTOCOL_VERSION_TLS_1_0"> TLS 1.0, which is insecure and should not be used + filename="gio/gioenums.h" + line="1887">TLS 1.0, which is insecure and should not be used glib:nick="tls-1-1" glib:name="G_TLS_PROTOCOL_VERSION_TLS_1_1"> TLS 1.1, which is insecure and should not be used + filename="gio/gioenums.h" + line="1888">TLS 1.1, which is insecure and should not be used glib:nick="tls-1-2" glib:name="G_TLS_PROTOCOL_VERSION_TLS_1_2"> TLS 1.2, defined by [RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) + filename="gio/gioenums.h" + line="1889">TLS 1.2, defined by [RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) glib:nick="tls-1-3" glib:name="G_TLS_PROTOCOL_VERSION_TLS_1_3"> TLS 1.3, defined by [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) + filename="gio/gioenums.h" + line="1890">TLS 1.3, defined by [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) glib:nick="dtls-1-0" glib:name="G_TLS_PROTOCOL_VERSION_DTLS_1_0"> DTLS 1.0, which is insecure and should not be used + filename="gio/gioenums.h" + line="1891">DTLS 1.0, which is insecure and should not be used glib:nick="dtls-1-2" glib:name="G_TLS_PROTOCOL_VERSION_DTLS_1_2"> DTLS 1.2, defined by [RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347) + filename="gio/gioenums.h" + line="1892">DTLS 1.2, defined by [RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347) glib:get-type="g_tls_rehandshake_mode_get_type" c:type="GTlsRehandshakeMode"> When to allow rehandshaking. See + filename="gio/gioenums.h" + line="1732">When to allow rehandshaking. See g_tls_connection_set_rehandshake_mode(). Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed @@ -124028,8 +128967,8 @@ g_tls_connection_set_rehandshake_mode(). glib:nick="never" glib:name="G_TLS_REHANDSHAKE_NEVER"> Never allow rehandshaking + filename="gio/gioenums.h" + line="1734">Never allow rehandshaking glib:nick="safely" glib:name="G_TLS_REHANDSHAKE_SAFELY"> Allow safe rehandshaking only + filename="gio/gioenums.h" + line="1735">Allow safe rehandshaking only glib:nick="unsafely" glib:name="G_TLS_REHANDSHAKE_UNSAFELY"> Allow unsafe rehandshaking + filename="gio/gioenums.h" + line="1736">Allow unsafe rehandshaking glib:get-type="g_tls_server_connection_get_type" glib:type-struct="TlsServerConnectionInterface"> #GTlsServerConnection is the server-side subclass of #GTlsConnection, -representing a server-side TLS connection. - + filename="gio/gtlsserverconnection.c" + line="32">`GTlsServerConnection` is the server-side subclass of +[class@Gio.TlsConnection], representing a server-side TLS connection. + Creates a new #GTlsServerConnection wrapping @base_io_stream (which + filename="gio/gtlsserverconnection.c" + line="63">Creates a new #GTlsServerConnection wrapping @base_io_stream (which must have pollable input and output streams). See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. - + the new + filename="gio/gtlsserverconnection.c" + line="76">the new #GTlsServerConnection, or %NULL on error the #GIOStream to wrap + filename="gio/gtlsserverconnection.c" + line="65">the #GIOStream to wrap nullable="1" allow-none="1"> the default server certificate, or %NULL + filename="gio/gtlsserverconnection.c" + line="66">the default server certificate, or %NULL @@ -124107,8 +129046,8 @@ this function has returned. transfer-ownership="none" default-value="G_TLS_AUTHENTICATION_NONE"> The #GTlsAuthenticationMode for the server. This can be changed + filename="gio/gtlsserverconnection.c" + line="46">The #GTlsAuthenticationMode for the server. This can be changed before calling g_tls_connection_handshake() if you want to rehandshake with a different mode from the initial handshake. @@ -124119,20 +129058,42 @@ rehandshake with a different mode from the initial handshake. glib:is-gtype-struct-for="TlsServerConnection" version="2.26"> vtable for a #GTlsServerConnection implementation. - + filename="gio/gtlsserverconnection.h" + line="39">vtable for a #GTlsServerConnection implementation. + The parent interface. + filename="gio/gtlsserverconnection.h" + line="41">The parent interface. + + + + + + + + + + + + + + + + + + - + @@ -124141,7 +129102,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124150,7 +129111,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124159,7 +129120,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124168,7 +129129,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124177,7 +129138,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124186,7 +129147,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124195,7 +129156,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124204,7 +129165,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124213,7 +129174,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124222,7 +129183,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124231,7 +129192,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124240,7 +129201,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124249,7 +129210,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124258,7 +129219,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124267,7 +129228,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124276,7 +129237,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124285,7 +129246,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124294,7 +129255,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124303,7 +129264,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124312,7 +129273,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124321,7 +129282,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124330,7 +129291,7 @@ rehandshake with a different mode from the initial handshake. - + @@ -124345,27 +129306,28 @@ rehandshake with a different mode from the initial handshake. glib:get-type="g_unix_connection_get_type" glib:type-struct="UnixConnectionClass"> This is the subclass of #GSocketConnection that is created + filename="gio/gunixconnection.c" + line="33">This is the subclass of [class@Gio.SocketConnection] that is created for UNIX domain sockets. It contains functions to do some of the UNIX socket specific functionality like passing file descriptors. -Since GLib 2.72, #GUnixConnection is available on all platforms. It requires +Since GLib 2.72, `GUnixConnection` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixconnection.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72. - + + throws="1" + glib:async-func="receive_credentials_async"> Receives credentials from the sending end of the connection. The + filename="gio/gunixconnection.c" + line="458">Receives credentials from the sending end of the connection. The sending end has to call g_unix_connection_send_credentials() (or similar) for this to work. @@ -124383,19 +129345,19 @@ This method can be expected to be available on the following platforms: Other ways to exchange credentials with a foreign peer includes the #GUnixCredentialsMessage type and g_socket_get_credentials() function. - + Received credentials on success (free with + filename="gio/gunixconnection.c" + line="483">Received credentials on success (free with g_object_unref()), %NULL if @error is set. A #GUnixConnection. + filename="gio/gunixconnection.c" + line="460">A #GUnixConnection. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gunixconnection.c" + line="461">A #GCancellable or %NULL. + version="2.32" + glib:finish-func="receive_credentials_finish" + glib:sync-func="receive_credentials"> Asynchronously receive credentials. + filename="gio/gunixconnection.c" + line="678">Asynchronously receive credentials. For more details, see g_unix_connection_receive_credentials() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_unix_connection_receive_credentials_finish() to get the result of the operation. - + A #GUnixConnection. + filename="gio/gunixconnection.c" + line="680">A #GUnixConnection. optional #GCancellable object, %NULL to ignore. + filename="gio/gunixconnection.c" + line="681">optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback + filename="gio/gunixconnection.c" + line="682">a #GAsyncReadyCallback to call when the request is satisfied @@ -124458,8 +129422,8 @@ g_unix_connection_receive_credentials_finish() to get the result of the operatio nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gunixconnection.c" + line="684">the data to pass to callback function @@ -124469,28 +129433,28 @@ g_unix_connection_receive_credentials_finish() to get the result of the operatio version="2.32" throws="1"> Finishes an asynchronous receive credentials operation started with + filename="gio/gunixconnection.c" + line="709">Finishes an asynchronous receive credentials operation started with g_unix_connection_receive_credentials_async(). - + a #GCredentials, or %NULL on error. + filename="gio/gunixconnection.c" + line="718">a #GCredentials, or %NULL on error. Free the returned object with g_object_unref(). A #GUnixConnection. + filename="gio/gunixconnection.c" + line="711">A #GUnixConnection. a #GAsyncResult. + filename="gio/gunixconnection.c" + line="712">a #GAsyncResult. @@ -124500,26 +129464,26 @@ g_unix_connection_receive_credentials_async(). version="2.22" throws="1"> Receives a file descriptor from the sending end of the connection. + filename="gio/gunixconnection.c" + line="121">Receives a file descriptor from the sending end of the connection. The sending end has to call g_unix_connection_send_fd() for this to work. As well as reading the fd this also reads a single byte from the stream, as this is required for fd passing to work on some implementations. - + a file descriptor on success, -1 on error. + filename="gio/gunixconnection.c" + line="135">a file descriptor on success, -1 on error. a #GUnixConnection + filename="gio/gunixconnection.c" + line="123">a #GUnixConnection nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gunixconnection.c" + line="124">optional #GCancellable object, %NULL to ignore @@ -124536,10 +129500,11 @@ implementations. + throws="1" + glib:async-func="send_credentials_async"> Passes the credentials of the current user the receiving side + filename="gio/gunixconnection.c" + line="298">Passes the credentials of the current user the receiving side of the connection. The receiving end has to call g_unix_connection_receive_credentials() (or similar) to accept the credentials. @@ -124558,18 +129523,18 @@ This method can be expected to be available on the following platforms: Other ways to exchange credentials with a foreign peer includes the #GUnixCredentialsMessage type and g_socket_get_credentials() function. - + %TRUE on success, %FALSE if @error is set. + filename="gio/gunixconnection.c" + line="324">%TRUE on success, %FALSE if @error is set. A #GUnixConnection. + filename="gio/gunixconnection.c" + line="300">A #GUnixConnection. A #GCancellable or %NULL. + filename="gio/gunixconnection.c" + line="301">A #GCancellable or %NULL. + version="2.32" + glib:finish-func="send_credentials_finish" + glib:sync-func="send_credentials"> Asynchronously send credentials. + filename="gio/gunixconnection.c" + line="404">Asynchronously send credentials. For more details, see g_unix_connection_send_credentials() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_unix_connection_send_credentials_finish() to get the result of the operation. - + A #GUnixConnection. + filename="gio/gunixconnection.c" + line="406">A #GUnixConnection. optional #GCancellable object, %NULL to ignore. + filename="gio/gunixconnection.c" + line="407">optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback + filename="gio/gunixconnection.c" + line="408">a #GAsyncReadyCallback to call when the request is satisfied @@ -124632,8 +129599,8 @@ g_unix_connection_send_credentials_finish() to get the result of the operation.< nullable="1" allow-none="1"> the data to pass to callback function + filename="gio/gunixconnection.c" + line="410">the data to pass to callback function @@ -124643,27 +129610,27 @@ g_unix_connection_send_credentials_finish() to get the result of the operation.< version="2.32" throws="1"> Finishes an asynchronous send credentials operation started with + filename="gio/gunixconnection.c" + line="435">Finishes an asynchronous send credentials operation started with g_unix_connection_send_credentials_async(). - + %TRUE if the operation was successful, otherwise %FALSE. + filename="gio/gunixconnection.c" + line="444">%TRUE if the operation was successful, otherwise %FALSE. A #GUnixConnection. + filename="gio/gunixconnection.c" + line="437">A #GUnixConnection. a #GAsyncResult. + filename="gio/gunixconnection.c" + line="438">a #GAsyncResult. @@ -124673,32 +129640,32 @@ g_unix_connection_send_credentials_async(). version="2.22" throws="1"> Passes a file descriptor to the receiving side of the + filename="gio/gunixconnection.c" + line="60">Passes a file descriptor to the receiving side of the connection. The receiving end has to call g_unix_connection_receive_fd() to accept the file descriptor. As well as sending the fd this also writes a single byte to the stream, as this is required for fd passing to work on some implementations. - + a %TRUE on success, %NULL on error. + filename="gio/gunixconnection.c" + line="75">a %TRUE on success, %NULL on error. a #GUnixConnection + filename="gio/gunixconnection.c" + line="62">a #GUnixConnection a file descriptor + filename="gio/gunixconnection.c" + line="63">a file descriptor nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gunixconnection.c" + line="64">optional #GCancellable object, %NULL to ignore. @@ -124722,7 +129689,7 @@ implementations. - + @@ -124731,7 +129698,7 @@ implementations. c:type="GUnixConnectionPrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_credentials_message_get_type" glib:type-struct="UnixCredentialsMessageClass"> This #GSocketControlMessage contains a #GCredentials instance. It -may be sent using g_socket_send_message() and received using -g_socket_receive_message() over UNIX sockets (ie: sockets in the -%G_SOCKET_FAMILY_UNIX family). + filename="gio/gunixcredentialsmessage.c" + line="18">This [class@Gio.SocketControlMessage] contains a [class@Gio.Credentials] +instance. It may be sent using [method@Gio.Socket.send_message] and received +using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in +the `G_SOCKET_FAMILY_UNIX` family). For an easier way to send and receive credentials over stream-oriented UNIX sockets, see -g_unix_connection_send_credentials() and -g_unix_connection_receive_credentials(). To receive credentials of +[method@Gio.UnixConnection.send_credentials] and +[method@Gio.UnixConnection.receive_credentials]. To receive credentials of a foreign process connected to a socket, use -g_socket_get_credentials(). +[method@Gio.Socket.get_credentials]. -Since GLib 2.72, #GUnixCredentialMessage is available on all platforms. It +Since GLib 2.72, `GUnixCredentialMessage` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixcredentialsmessage.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72. - + Creates a new #GUnixCredentialsMessage with credentials matching the current processes. - + filename="gio/gunixcredentialsmessage.c" + line="301">Creates a new #GUnixCredentialsMessage with credentials matching the current processes. + a new #GUnixCredentialsMessage + filename="gio/gunixcredentialsmessage.c" + line="306">a new #GUnixCredentialsMessage @@ -124781,20 +129748,20 @@ when using it. This is no longer necessary since GLib 2.72. c:identifier="g_unix_credentials_message_new_with_credentials" version="2.26"> Creates a new #GUnixCredentialsMessage holding @credentials. - + filename="gio/gunixcredentialsmessage.c" + line="318">Creates a new #GUnixCredentialsMessage holding @credentials. + a new #GUnixCredentialsMessage + filename="gio/gunixcredentialsmessage.c" + line="324">a new #GUnixCredentialsMessage A #GCredentials object. + filename="gio/gunixcredentialsmessage.c" + line="320">A #GCredentials object. @@ -124803,13 +129770,13 @@ when using it. This is no longer necessary since GLib 2.72. c:identifier="g_unix_credentials_message_is_supported" version="2.26"> Checks if passing #GCredentials on a #GSocket is supported on this platform. - + filename="gio/gunixcredentialsmessage.c" + line="280">Checks if passing #GCredentials on a #GSocket is supported on this platform. + %TRUE if supported, %FALSE otherwise + filename="gio/gunixcredentialsmessage.c" + line="285">%TRUE if supported, %FALSE otherwise @@ -124818,20 +129785,20 @@ when using it. This is no longer necessary since GLib 2.72. glib:get-property="credentials" version="2.26"> Gets the credentials stored in @message. - + filename="gio/gunixcredentialsmessage.c" + line="338">Gets the credentials stored in @message. + A #GCredentials instance. Do not free, it is owned by @message. + filename="gio/gunixcredentialsmessage.c" + line="344">A #GCredentials instance. Do not free, it is owned by @message. A #GUnixCredentialsMessage. + filename="gio/gunixcredentialsmessage.c" + line="340">A #GUnixCredentialsMessage. @@ -124844,8 +129811,8 @@ when using it. This is no longer necessary since GLib 2.72. transfer-ownership="none" getter="get_credentials"> The credentials stored in the message. + filename="gio/gunixcredentialsmessage.c" + line="258">The credentials stored in the message. @@ -124861,16 +129828,16 @@ when using it. This is no longer necessary since GLib 2.72. glib:is-gtype-struct-for="UnixCredentialsMessage" version="2.26"> Class structure for #GUnixCredentialsMessage. - + - + @@ -124878,7 +129845,7 @@ when using it. This is no longer necessary since GLib 2.72. - + @@ -124889,7 +129856,7 @@ when using it. This is no longer necessary since GLib 2.72. c:type="GUnixCredentialsMessagePrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_fd_list_get_type" glib:type-struct="UnixFDListClass"> A #GUnixFDList contains a list of file descriptors. It owns the file + filename="gio/gunixfdlist.c" + line="17">A `GUnixFDList` contains a list of file descriptors. It owns the file descriptors that it contains, closing them when finalized. -It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in -the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() -and received using g_socket_receive_message(). +It may be wrapped in a +[`GUnixFDMessage`](../gio-unix/class.UnixFDMessage.html) and sent over a +[class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using +[method@Gio.Socket.send_message] and received using +[method@Gio.Socket.receive_message]. Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. Since 2.74, the API is available for Windows. - + Creates a new #GUnixFDList containing no file descriptors. - + filename="gio/gunixfdlist.c" + line="151">Creates a new #GUnixFDList containing no file descriptors. + a new #GUnixFDList + filename="gio/gunixfdlist.c" + line="156">a new #GUnixFDList @@ -124929,8 +129898,8 @@ Since 2.74, the API is available for Windows. c:identifier="g_unix_fd_list_new_from_array" version="2.24"> Creates a new #GUnixFDList containing the file descriptors given in + filename="gio/gunixfdlist.c" + line="166">Creates a new #GUnixFDList containing the file descriptors given in @fds. The file descriptors become the property of the new list and may no longer be used by the caller. The array itself is owned by the caller. @@ -124938,26 +129907,26 @@ the caller. Each file descriptor in the array should be set to close-on-exec. If @n_fds is -1 then @fds must be terminated with -1. - + a new #GUnixFDList + filename="gio/gunixfdlist.c" + line="180">a new #GUnixFDList the initial list of file descriptors + filename="gio/gunixfdlist.c" + line="168">the initial list of file descriptors the length of #fds, or -1 + filename="gio/gunixfdlist.c" + line="169">the length of #fds, or -1 @@ -124967,8 +129936,8 @@ If @n_fds is -1 then @fds must be terminated with -1. version="2.24" throws="1"> Adds a file descriptor to @list. + filename="gio/gunixfdlist.c" + line="307">Adds a file descriptor to @list. The file descriptor is duplicated using dup(). You keep your copy of the descriptor and the copy contained in @list will be closed @@ -124980,25 +129949,25 @@ system-wide file descriptor limit. The index of the file descriptor in the list is returned. If you use this index with g_unix_fd_list_get() then you will receive back a duplicated copy of the same file descriptor. - + the index of the appended fd in case of success, else -1 + filename="gio/gunixfdlist.c" + line="326">the index of the appended fd in case of success, else -1 (and @error is set) a #GUnixFDList + filename="gio/gunixfdlist.c" + line="309">a #GUnixFDList a valid open file descriptor + filename="gio/gunixfdlist.c" + line="310">a valid open file descriptor @@ -125008,8 +129977,8 @@ duplicated copy of the same file descriptor. version="2.24" throws="1"> Gets a file descriptor out of @list. + filename="gio/gunixfdlist.c" + line="354">Gets a file descriptor out of @list. @index_ specifies the index of the file descriptor to get. It is a programmer error for @index_ to be out of range; see @@ -125021,24 +129990,24 @@ when you are done. A possible cause of failure is exceeding the per-process or system-wide file descriptor limit. - + the file descriptor, or -1 in case of error + filename="gio/gunixfdlist.c" + line="373">the file descriptor, or -1 in case of error a #GUnixFDList + filename="gio/gunixfdlist.c" + line="356">a #GUnixFDList the index into the list + filename="gio/gunixfdlist.c" + line="357">the index into the list @@ -125047,21 +130016,21 @@ system-wide file descriptor limit. c:identifier="g_unix_fd_list_get_length" version="2.24"> Gets the length of @list (ie: the number of file descriptors + filename="gio/gunixfdlist.c" + line="389">Gets the length of @list (ie: the number of file descriptors contained within). - + the length of @list + filename="gio/gunixfdlist.c" + line="396">the length of @list a #GUnixFDList + filename="gio/gunixfdlist.c" + line="391">a #GUnixFDList @@ -125070,8 +130039,8 @@ contained within). c:identifier="g_unix_fd_list_peek_fds" version="2.24"> Returns the array of file descriptors that is contained in this + filename="gio/gunixfdlist.c" + line="262">Returns the array of file descriptors that is contained in this object. After this call, the descriptors remain the property of @list. The @@ -125084,11 +130053,11 @@ terminated with -1. This function never returns %NULL. In case there are no file descriptors contained in @list, an empty array is returned. - + an array of file + filename="gio/gunixfdlist.c" + line="282">an array of file descriptors @@ -125097,8 +130066,8 @@ descriptors contained in @list, an empty array is returned. a #GUnixFDList + filename="gio/gunixfdlist.c" + line="264">a #GUnixFDList optional="1" allow-none="1"> pointer to the length of the returned + filename="gio/gunixfdlist.c" + line="265">pointer to the length of the returned array, or %NULL @@ -125119,8 +130088,8 @@ descriptors contained in @list, an empty array is returned. c:identifier="g_unix_fd_list_steal_fds" version="2.24"> Returns the array of file descriptors that is contained in this + filename="gio/gunixfdlist.c" + line="206">Returns the array of file descriptors that is contained in this object. After this call, the descriptors are no longer contained in @@ -125138,11 +130107,11 @@ terminated with -1. This function never returns %NULL. In case there are no file descriptors contained in @list, an empty array is returned. - + an array of file + filename="gio/gunixfdlist.c" + line="231">an array of file descriptors @@ -125151,8 +130120,8 @@ descriptors contained in @list, an empty array is returned. a #GUnixFDList + filename="gio/gunixfdlist.c" + line="208">a #GUnixFDList optional="1" allow-none="1"> pointer to the length of the returned + filename="gio/gunixfdlist.c" + line="209">pointer to the length of the returned array, or %NULL @@ -125179,13 +130148,13 @@ descriptors contained in @list, an empty array is returned. - + - + @@ -125193,7 +130162,7 @@ descriptors contained in @list, an empty array is returned. - + @@ -125201,7 +130170,7 @@ descriptors contained in @list, an empty array is returned. - + @@ -125209,7 +130178,7 @@ descriptors contained in @list, an empty array is returned. - + @@ -125217,7 +130186,7 @@ descriptors contained in @list, an empty array is returned. - + @@ -125228,7 +130197,7 @@ descriptors contained in @list, an empty array is returned. c:type="GUnixFDListPrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_fd_message_get_type" glib:type-struct="UnixFDMessageClass"> This #GSocketControlMessage contains a #GUnixFDList. -It may be sent using g_socket_send_message() and received using -g_socket_receive_message() over UNIX sockets (ie: sockets in the -%G_SOCKET_FAMILY_UNIX family). The file descriptors are copied + filename="gio/gunixfdmessage.c" + line="17">This [class@Gio.SocketControlMessage] contains a [class@Gio.UnixFDList]. +It may be sent using [method@Gio.Socket.send_message] and received using +[method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in the +`G_SOCKET_FAMILY_UNIX` family). The file descriptors are copied between processes by the kernel. For an easier way to send and receive file descriptors over -stream-oriented UNIX sockets, see g_unix_connection_send_fd() and -g_unix_connection_receive_fd(). +stream-oriented UNIX sockets, see [method@Gio.UnixConnection.send_fd] and +[method@Gio.UnixConnection.receive_fd]. Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - +file or the `GioUnix-2.0` GIR namespace when using it. + Creates a new #GUnixFDMessage containing an empty file descriptor + filename="gio/gunixfdmessage.c" + line="229">Creates a new #GUnixFDMessage containing an empty file descriptor list. - + a new #GUnixFDMessage + filename="gio/gunixfdmessage.c" + line="235">a new #GUnixFDMessage @@ -125272,20 +130241,20 @@ list. c:identifier="g_unix_fd_message_new_with_fd_list" version="2.24"> Creates a new #GUnixFDMessage containing @list. - + filename="gio/gunixfdmessage.c" + line="245">Creates a new #GUnixFDMessage containing @list. + a new #GUnixFDMessage + filename="gio/gunixfdmessage.c" + line="251">a new #GUnixFDMessage a #GUnixFDList + filename="gio/gunixfdmessage.c" + line="247">a #GUnixFDList @@ -125295,8 +130264,8 @@ list. version="2.22" throws="1"> Adds a file descriptor to @message. + filename="gio/gunixfdmessage.c" + line="301">Adds a file descriptor to @message. The file descriptor is duplicated using dup(). You keep your copy of the descriptor and the copy contained in @message will be closed @@ -125304,24 +130273,24 @@ when @message is finalized. A possible cause of failure is exceeding the per-process or system-wide file descriptor limit. - + %TRUE in case of success, else %FALSE (and @error is set) + filename="gio/gunixfdmessage.c" + line="316">%TRUE in case of success, else %FALSE (and @error is set) a #GUnixFDMessage + filename="gio/gunixfdmessage.c" + line="303">a #GUnixFDMessage a valid open file descriptor + filename="gio/gunixfdmessage.c" + line="304">a valid open file descriptor @@ -125331,22 +130300,22 @@ system-wide file descriptor limit. glib:get-property="fd-list" version="2.24"> Gets the #GUnixFDList contained in @message. This function does not + filename="gio/gunixfdmessage.c" + line="155">Gets the #GUnixFDList contained in @message. This function does not return a reference to the caller, but the returned list is valid for the lifetime of @message. - + the #GUnixFDList from @message + filename="gio/gunixfdmessage.c" + line="163">the #GUnixFDList from @message a #GUnixFDMessage + filename="gio/gunixfdmessage.c" + line="157">a #GUnixFDMessage @@ -125355,8 +130324,8 @@ the lifetime of @message. c:identifier="g_unix_fd_message_steal_fds" version="2.22"> Returns the array of file descriptors that is contained in this + filename="gio/gunixfdmessage.c" + line="263">Returns the array of file descriptors that is contained in this object. After this call, the descriptors are no longer contained in @@ -125373,11 +130342,11 @@ terminated with -1. This function never returns %NULL. In case there are no file descriptors contained in @message, an empty array is returned. - + an array of file + filename="gio/gunixfdmessage.c" + line="287">an array of file descriptors @@ -125386,8 +130355,8 @@ descriptors contained in @message, an empty array is returned. a #GUnixFDMessage + filename="gio/gunixfdmessage.c" + line="265">a #GUnixFDMessage optional="1" allow-none="1"> pointer to the length of the returned + filename="gio/gunixfdmessage.c" + line="266">pointer to the length of the returned array, or %NULL + The [class@Gio.UnixFDList] object to send with the message. @@ -125421,14 +130394,14 @@ descriptors contained in @message, an empty array is returned. - + - + @@ -125436,7 +130409,7 @@ descriptors contained in @message, an empty array is returned. - + @@ -125447,7 +130420,7 @@ descriptors contained in @message, an empty array is returned. c:type="GUnixFDMessagePrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_input_stream_get_type" glib:type-struct="UnixInputStreamClass"> #GUnixInputStream implements #GInputStream for reading from a UNIX + filename="gio/gunixinputstream.c" + line="41">`GUnixInputStream` implements [class@Gio.InputStream] for reading from a UNIX file descriptor, including asynchronous operations. (If the file -descriptor refers to a socket or pipe, this will use poll() to do +descriptor refers to a socket or pipe, this will use `poll()` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - +file or the `GioUnix-2.0` GIR namespace when using it. + Creates a new #GUnixInputStream for the given @fd. + filename="gio/gunixinputstream.c" + line="224">Creates a new #GUnixInputStream for the given @fd. If @close_fd is %TRUE, the file descriptor will be closed when the stream is closed. - + a new #GUnixInputStream + filename="gio/gunixinputstream.c" + line="234">a new #GUnixInputStream a UNIX file descriptor + filename="gio/gunixinputstream.c" + line="226">a UNIX file descriptor %TRUE to close the file descriptor when done + filename="gio/gunixinputstream.c" + line="227">%TRUE to close the file descriptor when done @@ -125504,21 +130477,21 @@ when the stream is closed. glib:get-property="close-fd" version="2.20"> Returns whether the file descriptor of @stream will be + filename="gio/gunixinputstream.c" + line="276">Returns whether the file descriptor of @stream will be closed when the stream is closed. - + %TRUE if the file descriptor is closed when done + filename="gio/gunixinputstream.c" + line="283">%TRUE if the file descriptor is closed when done a #GUnixInputStream + filename="gio/gunixinputstream.c" + line="278">a #GUnixInputStream @@ -125528,20 +130501,20 @@ closed when the stream is closed. glib:get-property="fd" version="2.20"> Return the UNIX file descriptor that the stream reads from. - + filename="gio/gunixinputstream.c" + line="295">Return the UNIX file descriptor that the stream reads from. + The file descriptor of @stream + filename="gio/gunixinputstream.c" + line="301">The file descriptor of @stream a #GUnixInputStream + filename="gio/gunixinputstream.c" + line="297">a #GUnixInputStream @@ -125551,24 +130524,24 @@ closed when the stream is closed. glib:set-property="close-fd" version="2.20"> Sets whether the file descriptor of @stream shall be closed + filename="gio/gunixinputstream.c" + line="252">Sets whether the file descriptor of @stream shall be closed when the stream is closed. - + a #GUnixInputStream + filename="gio/gunixinputstream.c" + line="254">a #GUnixInputStream %TRUE to close the file descriptor when done + filename="gio/gunixinputstream.c" + line="255">%TRUE to close the file descriptor when done @@ -125581,8 +130554,8 @@ when the stream is closed. getter="get_close_fd" default-value="TRUE"> Whether to close the file descriptor when the stream is closed. + filename="gio/gunixinputstream.c" + line="140">Whether to close the file descriptor when the stream is closed. getter="get_fd" default-value="-1"> The file descriptor that the stream reads from. + filename="gio/gunixinputstream.c" + line="127">The file descriptor that the stream reads from. @@ -125607,13 +130580,13 @@ when the stream is closed. - + - + @@ -125621,7 +130594,7 @@ when the stream is closed. - + @@ -125629,7 +130602,7 @@ when the stream is closed. - + @@ -125637,7 +130610,7 @@ when the stream is closed. - + @@ -125645,7 +130618,7 @@ when the stream is closed. - + @@ -125656,7 +130629,7 @@ when the stream is closed. c:type="GUnixInputStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_mount_entry_get_type" c:symbol-prefix="unix_mount_entry"> Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). + filename="gio/gunixmounts.h" + line="31">Defines a Unix mount entry (e.g. `/media/cdrom`). This corresponds roughly to a mtab entry. - + + + Compares two Unix mounts. + + + `1`, `0` or `-1` if @mount1 is greater than, equal to, + or less than @mount2, respectively + + + + + first [struct@GioUnix.MountEntry] to compare + + + + second [struct@GioUnix.MountEntry] to compare + + + + + + Makes a copy of @mount_entry. + + + a new [struct@GioUnix.MountEntry] + + + + + a [struct@GioUnix.MountEntry] + + + + + + Frees a Unix mount. + + + + + + + a [struct@GioUnix.MountEntry] + + + + + + Gets the device path for a Unix mount. + + + a string containing the device path + + + + + a [struct@GioUnix.MountEntry] + + + + + + Gets the filesystem type for the Unix mount. + + + a string containing the file system type + + + + + a [struct@GioUnix.MountEntry] + + + + + + Gets the mount path for a Unix mount. + + + the mount path for @mount_entry + + + + + a [struct@GioUnix.MountEntry] to get the mount path for + + + + + + Gets a comma separated list of mount options for the Unix mount. + +For example: `rw,relatime,seclabel,data=ordered`. + +This is similar to [func@GioUnix.MountPoint.get_options], but it takes +a [struct@GioUnix.MountEntry] as an argument. + + + a string containing the options, or `NULL` if not + available. + + + + + a [struct@GioUnix.MountEntry] + + + + + + Gets the root of the mount within the filesystem. This is useful e.g. for +mounts created by bind operation, or btrfs subvolumes. + +For example, the root path is equal to `/` for a mount created by +`mount /dev/sda1 /mnt/foo` and `/bar` for +`mount --bind /mnt/foo/bar /mnt/bar`. + + + a string containing the root, or `NULL` if not supported + + + + + a [struct@GioUnix.MountEntry] + + + + + + Guesses whether a Unix mount entry can be ejected. + + + true if @mount_entry is deemed to be ejectable; false otherwise + + + + + a [struct@GioUnix.MountEntry] + + + + + + Guesses the icon of a Unix mount entry. + + + a [iface@Gio.Icon] + + + + + a [struct@GioUnix.MountEntry] + + + + + + Guesses the name of a Unix mount entry. + +The result is a translated string. + + + a newly allocated translated string + + + + + a [struct@GioUnix.MountEntry] + + + + + + Guesses whether a Unix mount entry should be displayed in the UI. + + + true if @mount_entry is deemed to be displayable; false otherwise + + + + + a [struct@GioUnix.MountEntry] + + + + + + Guesses the symbolic icon of a Unix mount entry. + + + a [iface@Gio.Icon] + + + + + a [struct@GioUnix.MountEntry] + + + + + + Checks if a Unix mount is mounted read only. + + + true if @mount_entry is read only; false otherwise + + + + + a [struct@GioUnix.MountEntry] + + + + + + Checks if a Unix mount is a system mount. + +This is the Boolean OR of +[func@GioUnix.is_system_fs_type], [func@GioUnix.is_system_device_path] and +[func@GioUnix.is_mount_path_system_internal] on @mount_entry’s properties. + +The definition of what a ‘system’ mount entry is may change over time as new +file system types and device paths are ignored. + + + true if the Unix mount is for a system path; false otherwise + + + + + a [struct@GioUnix.MountEntry] + + + + + + Gets a [struct@GioUnix.MountEntry] for a given mount path. + +If @time_read is set, it will be filled with a Unix timestamp for checking +if the mounts have changed since with +[func@GioUnix.mount_entries_changed_since]. + +If more mounts have the same mount path, the last matching mount +is returned. + +This will return `NULL` if there is no mount point at @mount_path. + + + a [struct@GioUnix.MountEntry] + + + + + path for a possible Unix mount + + + + return location for a timestamp + + + + + + Gets a [struct@GioUnix.MountEntry] for a given file path. + +If @time_read is set, it will be filled with a Unix timestamp for checking +if the mounts have changed since with +[func@GioUnix.mount_entries_changed_since]. + +If more mounts have the same mount path, the last matching mount +is returned. + +This will return `NULL` if looking up the mount entry fails, if +@file_path doesn’t exist or there is an I/O error. + + + a [struct@GioUnix.MountEntry] + + + + + file path on some Unix mount + + + + return location for a timestamp + + + + glib:get-type="g_unix_mount_monitor_get_type" glib:type-struct="UnixMountMonitorClass"> Watches #GUnixMounts for changes. - + filename="gio/gunixmounts.h" + line="55">Watches for changes to the set of mount entries and mount points in the +system. + +Connect to the [signal@GioUnix.MountMonitor::mounts-changed] signal to be +notified of changes to the [struct@GioUnix.MountEntry] list. + +Connect to the [signal@GioUnix.MountMonitor::mountpoints-changed] signal to +be notified of changes to the [struct@GioUnix.MountPoint] list. + Deprecated alias for g_unix_mount_monitor_get(). + filename="gio/gunixmounts.c" + line="2700">Deprecated alias for [func@GioUnix.MountMonitor.get]. This function was never a true constructor, which is why it was renamed. - Use g_unix_mount_monitor_get() instead. - + Use [func@GioUnix.MountMonitor.get] instead. + a #GUnixMountMonitor. + filename="gio/gunixmounts.c" + line="2708">a [class@GioUnix.MountMonitor] @@ -125704,21 +131121,21 @@ renamed. c:identifier="g_unix_mount_monitor_get" version="2.44"> Gets the #GUnixMountMonitor for the current thread-default main + filename="gio/gunixmounts.c" + line="2675">Gets the [class@GioUnix.MountMonitor] for the current thread-default main context. The mount monitor can be used to monitor for changes to the list of mounted filesystems as well as the list of mount points (ie: fstab entries). -You must only call g_object_unref() on the return value from under -the same main context as you called this function. - +You must only call [method@GObject.Object.unref] on the return value from +under the same main context as you called this function. + the #GUnixMountMonitor. + filename="gio/gunixmounts.c" + line="2688">the [class@GioUnix.MountMonitor] @@ -125728,47 +131145,46 @@ the same main context as you called this function. deprecated="1" deprecated-version="2.44"> This function does nothing. + filename="gio/gunixmounts.c" + line="2653">This function does nothing. Before 2.44, this was a partially-effective way of controlling the rate at which events would be reported under some uncommon circumstances. Since @mount_monitor is a singleton, it also meant that calling this function would have side effects for other users of the monitor. - This function does nothing. Don't call it. - + This function does nothing. Don’t call it. + a #GUnixMountMonitor + filename="gio/gunixmounts.c" + line="2655">a [class@GioUnix.MountMonitor] a integer with the limit in milliseconds to - poll for changes. + filename="gio/gunixmounts.c" + line="2656">a integer with the limit (in milliseconds) to poll for changes Emitted when the unix mount points have changed. + filename="gio/gunixmounts.c" + line="2632">Emitted when the Unix mount points have changed. Emitted when the unix mounts have changed. + filename="gio/gunixmounts.c" + line="2617">Emitted when the Unix mount entries have changed. @@ -125779,7 +131195,7 @@ the monitor. disguised="1" opaque="1" glib:is-gtype-struct-for="UnixMountMonitor"> - + glib:get-type="g_unix_mount_point_get_type" c:symbol-prefix="unix_mount_point"> Defines a Unix mount point (e.g. <filename>/dev</filename>). + filename="gio/gunixmounts.h" + line="43">Defines a Unix mount point (e.g. `/dev`). This corresponds roughly to a fstab entry. - + Compares two unix mount points. - + filename="gio/gunixmounts.c" + line="3170">Compares two Unix mount points. + 1, 0 or -1 if @mount1 is greater than, equal to, -or less than @mount2, respectively. + filename="gio/gunixmounts.c" + line="3177">`1`, `0` or `-1` if @mount1 is greater than, equal to, + or less than @mount2, respectively a #GUnixMount. + filename="gio/gunixmounts.c" + line="3172">a [struct@GioUnix.MountPoint] a #GUnixMount. + filename="gio/gunixmounts.c" + line="3173">a [struct@GioUnix.MountPoint] @@ -125823,37 +131239,37 @@ or less than @mount2, respectively. c:identifier="g_unix_mount_point_copy" version="2.54"> Makes a copy of @mount_point. - + filename="gio/gunixmounts.c" + line="2815">Makes a copy of @mount_point. + a new #GUnixMountPoint + filename="gio/gunixmounts.c" + line="2821">a new [struct@GioUnix.MountPoint] a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="2817">a [struct@GioUnix.MountPoint] Frees a unix mount point. - + filename="gio/gunixmounts.c" + line="2797">Frees a Unix mount point. + unix mount point to free. + filename="gio/gunixmounts.c" + line="2799">Unix mount point to free. @@ -125861,40 +131277,40 @@ or less than @mount2, respectively. Gets the device path for a unix mount point. - + filename="gio/gunixmounts.c" + line="3235">Gets the device path for a Unix mount point. + a string containing the device path. + filename="gio/gunixmounts.c" + line="3241">a string containing the device path a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3237">a [struct@GioUnix.MountPoint] Gets the file system type for the mount point. - + filename="gio/gunixmounts.c" + line="3251">Gets the file system type for the mount point. + a string containing the file system type. + filename="gio/gunixmounts.c" + line="3257">a string containing the file system type a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3253">a [struct@GioUnix.MountPoint] @@ -125902,20 +131318,20 @@ or less than @mount2, respectively. Gets the mount path for a unix mount point. - + filename="gio/gunixmounts.c" + line="3219">Gets the mount path for a Unix mount point. + a string containing the mount path. + filename="gio/gunixmounts.c" + line="3225">a string containing the mount path a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3221">a [struct@GioUnix.MountPoint] @@ -125924,20 +131340,20 @@ or less than @mount2, respectively. c:identifier="g_unix_mount_point_get_options" version="2.32"> Gets the options for the mount point. - + filename="gio/gunixmounts.c" + line="3267">Gets the options for the mount point. + a string containing the options. + filename="gio/gunixmounts.c" + line="3273">a string containing the options a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3269">a [struct@GioUnix.MountPoint] @@ -125945,62 +131361,62 @@ or less than @mount2, respectively. Guesses whether a Unix mount point can be ejected. - + filename="gio/gunixmounts.c" + line="3814">Guesses whether a Unix mount point can be ejected. + %TRUE if @mount_point is deemed to be ejectable. + filename="gio/gunixmounts.c" + line="3820">true if @mount_point is deemed to be ejectable; false otherwise a #GUnixMountPoint + filename="gio/gunixmounts.c" + line="3816">a [struct@GioUnix.MountPoint] Guesses the icon of a Unix mount point. - + filename="gio/gunixmounts.c" + line="3645">Guesses the icon of a Unix mount point. + a #GIcon + filename="gio/gunixmounts.c" + line="3651">a [iface@Gio.Icon] a #GUnixMountPoint + filename="gio/gunixmounts.c" + line="3647">a [struct@GioUnix.MountPoint] Guesses the name of a Unix mount point. + filename="gio/gunixmounts.c" + line="3622">Guesses the name of a Unix mount point. + The result is a translated string. - + A newly allocated string that must - be freed with g_free() + filename="gio/gunixmounts.c" + line="3630">a newly allocated translated string a #GUnixMountPoint + filename="gio/gunixmounts.c" + line="3624">a [struct@GioUnix.MountPoint] @@ -126009,60 +131425,60 @@ The result is a translated string. c:identifier="g_unix_mount_point_guess_symbolic_icon" version="2.34"> Guesses the symbolic icon of a Unix mount point. - + filename="gio/gunixmounts.c" + line="3659">Guesses the symbolic icon of a Unix mount point. + a #GIcon + filename="gio/gunixmounts.c" + line="3665">a [iface@Gio.Icon] a #GUnixMountPoint + filename="gio/gunixmounts.c" + line="3661">a [struct@GioUnix.MountPoint] Checks if a unix mount point is a loopback device. - + filename="gio/gunixmounts.c" + line="3316">Checks if a Unix mount point is a loopback device. + %TRUE if the mount point is a loopback. %FALSE otherwise. + filename="gio/gunixmounts.c" + line="3322">true if the mount point is a loopback device; false otherwise a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3318">a [struct@GioUnix.MountPoint] Checks if a unix mount point is read only. - + filename="gio/gunixmounts.c" + line="3284">Checks if a Unix mount point is read only. + %TRUE if a mount point is read only. + filename="gio/gunixmounts.c" + line="3290">true if a mount point is read only; false otherwise a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3286">a [struct@GioUnix.MountPoint] @@ -126070,46 +131486,48 @@ The result is a translated string. Checks if a unix mount point is mountable by the user. - + filename="gio/gunixmounts.c" + line="3300">Checks if a Unix mount point is mountable by the user. + %TRUE if the mount point is user mountable. + filename="gio/gunixmounts.c" + line="3306">true if the mount point is user mountable; false otherwise a #GUnixMountPoint. + filename="gio/gunixmounts.c" + line="3302">a [struct@GioUnix.MountPoint] Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it -will be filled with a unix timestamp for checking if the mount points have -changed since with g_unix_mount_points_changed_since(). + filename="gio/gunixmounts.c" + line="2151">Gets a [struct@GioUnix.MountPoint] for a given mount path. + +If @time_read is set, it will be filled with a Unix timestamp for checking if +the mount points have changed since with +[func@GioUnix.mount_points_changed_since]. If more mount points have the same mount path, the last matching mount point is returned. - + a #GUnixMountPoint, or %NULL if no match -is found. + filename="gio/gunixmounts.c" + line="2165">a [struct@GioUnix.MountPoint], or `NULL` + if no match is found path for a possible unix mount point. + filename="gio/gunixmounts.c" + line="2153">path for a possible Unix mount point optional="1" allow-none="1"> guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="2154">return location for a timestamp @@ -126134,44 +131552,44 @@ is found. glib:get-type="g_unix_output_stream_get_type" glib:type-struct="UnixOutputStreamClass"> #GUnixOutputStream implements #GOutputStream for writing to a UNIX + filename="gio/gunixoutputstream.c" + line="43">`GUnixOutputStream` implements [class@Gio.OutputStream] for writing to a UNIX file descriptor, including asynchronous operations. (If the file -descriptor refers to a socket or pipe, this will use poll() to do +descriptor refers to a socket or pipe, this will use `poll()` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file -when using it. - +file or the `GioUnix-2.0` GIR namespace when using it. + Creates a new #GUnixOutputStream for the given @fd. + filename="gio/gunixoutputstream.c" + line="224">Creates a new #GUnixOutputStream for the given @fd. If @close_fd, is %TRUE, the file descriptor will be closed when the output stream is destroyed. - + a new #GOutputStream + filename="gio/gunixoutputstream.c" + line="234">a new #GOutputStream a UNIX file descriptor + filename="gio/gunixoutputstream.c" + line="226">a UNIX file descriptor %TRUE to close the file descriptor when done + filename="gio/gunixoutputstream.c" + line="227">%TRUE to close the file descriptor when done @@ -126181,21 +131599,21 @@ the output stream is destroyed. glib:get-property="close-fd" version="2.20"> Returns whether the file descriptor of @stream will be + filename="gio/gunixoutputstream.c" + line="276">Returns whether the file descriptor of @stream will be closed when the stream is closed. - + %TRUE if the file descriptor is closed when done + filename="gio/gunixoutputstream.c" + line="283">%TRUE if the file descriptor is closed when done a #GUnixOutputStream + filename="gio/gunixoutputstream.c" + line="278">a #GUnixOutputStream @@ -126205,20 +131623,20 @@ closed when the stream is closed. glib:get-property="fd" version="2.20"> Return the UNIX file descriptor that the stream writes to. - + filename="gio/gunixoutputstream.c" + line="295">Return the UNIX file descriptor that the stream writes to. + The file descriptor of @stream + filename="gio/gunixoutputstream.c" + line="301">The file descriptor of @stream a #GUnixOutputStream + filename="gio/gunixoutputstream.c" + line="297">a #GUnixOutputStream @@ -126228,24 +131646,24 @@ closed when the stream is closed. glib:set-property="close-fd" version="2.20"> Sets whether the file descriptor of @stream shall be closed + filename="gio/gunixoutputstream.c" + line="252">Sets whether the file descriptor of @stream shall be closed when the stream is closed. - + a #GUnixOutputStream + filename="gio/gunixoutputstream.c" + line="254">a #GUnixOutputStream %TRUE to close the file descriptor when done + filename="gio/gunixoutputstream.c" + line="255">%TRUE to close the file descriptor when done @@ -126258,8 +131676,8 @@ when the stream is closed. getter="get_close_fd" default-value="TRUE"> Whether to close the file descriptor when the stream is closed. + filename="gio/gunixoutputstream.c" + line="139">Whether to close the file descriptor when the stream is closed. getter="get_fd" default-value="-1"> The file descriptor that the stream writes to. + filename="gio/gunixoutputstream.c" + line="126">The file descriptor that the stream writes to. @@ -126285,13 +131703,13 @@ when the stream is closed. - + - + @@ -126299,7 +131717,7 @@ when the stream is closed. - + @@ -126307,7 +131725,7 @@ when the stream is closed. - + @@ -126315,7 +131733,7 @@ when the stream is closed. - + @@ -126323,7 +131741,7 @@ when the stream is closed. - + @@ -126334,7 +131752,7 @@ when the stream is closed. c:type="GUnixOutputStreamPrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_socket_address_get_type" glib:type-struct="UnixSocketAddressClass"> Support for UNIX-domain (also known as local) sockets. + filename="gio/gunixsocketaddress.c" + line="37">Support for UNIX-domain (also known as local) sockets, corresponding to +`struct sockaddr_un`. UNIX domain sockets are generally visible in the filesystem. However, some systems support abstract socket names which are not visible in the filesystem and not affected by the filesystem permissions, visibility, etc. Currently this is only supported under Linux. If you attempt to use abstract sockets on other -systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED -errors. You can use g_unix_socket_address_abstract_names_supported() +systems, function calls may return `G_IO_ERROR_NOT_SUPPORTED` +errors. You can use [func@Gio.UnixSocketAddress.abstract_names_supported] to see if abstract names are supported. -Since GLib 2.72, #GUnixSocketAddress is available on all platforms. It +Since GLib 2.72, `GUnixSocketAddress` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixsocketaddress.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72. - + Creates a new #GUnixSocketAddress for @path. + filename="gio/gunixsocketaddress.c" + line="384">Creates a new #GUnixSocketAddress for @path. To create abstract socket addresses, on systems that support that, use g_unix_socket_address_new_abstract(). - + a new #GUnixSocketAddress + filename="gio/gunixsocketaddress.c" + line="393">a new #GUnixSocketAddress the socket path + filename="gio/gunixsocketaddress.c" + line="386">the socket path @@ -126394,30 +131813,30 @@ use g_unix_socket_address_new_abstract(). c:identifier="g_unix_socket_address_new_abstract" deprecated="1"> Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED + filename="gio/gunixsocketaddress.c" + line="406">Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED #GUnixSocketAddress for @path. Use g_unix_socket_address_new_with_type(). - + a new #GUnixSocketAddress + filename="gio/gunixsocketaddress.c" + line="414">a new #GUnixSocketAddress the abstract name + filename="gio/gunixsocketaddress.c" + line="408">the abstract name the length of @path, or -1 + filename="gio/gunixsocketaddress.c" + line="409">the length of @path, or -1 @@ -126426,8 +131845,8 @@ use g_unix_socket_address_new_abstract(). c:identifier="g_unix_socket_address_new_with_type" version="2.26"> Creates a new #GUnixSocketAddress of type @type with name @path. + filename="gio/gunixsocketaddress.c" + line="426">Creates a new #GUnixSocketAddress of type @type with name @path. If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to calling g_unix_socket_address_new(). @@ -126458,32 +131877,32 @@ length of @path. when connecting to a server created by another process, you must use the appropriate type corresponding to how that process created its listening socket. - + a new #GUnixSocketAddress + filename="gio/gunixsocketaddress.c" + line="464">a new #GUnixSocketAddress the name + filename="gio/gunixsocketaddress.c" + line="428">the name the length of @path, or -1 + filename="gio/gunixsocketaddress.c" + line="429">the length of @path, or -1 a #GUnixSocketAddressType + filename="gio/gunixsocketaddress.c" + line="430">a #GUnixSocketAddressType @@ -126493,13 +131912,13 @@ its listening socket. c:identifier="g_unix_socket_address_abstract_names_supported" version="2.22"> Checks if abstract UNIX domain socket names are supported. - + filename="gio/gunixsocketaddress.c" + line="575">Checks if abstract UNIX domain socket names are supported. + %TRUE if supported, %FALSE otherwise + filename="gio/gunixsocketaddress.c" + line="580">%TRUE if supported, %FALSE otherwise @@ -126508,20 +131927,20 @@ its listening socket. glib:get-property="address-type" version="2.26"> Gets @address's type. - + filename="gio/gunixsocketaddress.c" + line="540">Gets @address's type. + a #GUnixSocketAddressType + filename="gio/gunixsocketaddress.c" + line="546">a #GUnixSocketAddressType a #GInetSocketAddress + filename="gio/gunixsocketaddress.c" + line="542">a #GInetSocketAddress @@ -126531,21 +131950,21 @@ its listening socket. version="2.22" deprecated="1"> Tests if @address is abstract. + filename="gio/gunixsocketaddress.c" + line="556">Tests if @address is abstract. Use g_unix_socket_address_get_address_type() - + %TRUE if the address is abstract, %FALSE otherwise + filename="gio/gunixsocketaddress.c" + line="562">%TRUE if the address is abstract, %FALSE otherwise a #GInetSocketAddress + filename="gio/gunixsocketaddress.c" + line="558">a #GInetSocketAddress @@ -126555,25 +131974,25 @@ its listening socket. glib:get-property="path" version="2.22"> Gets @address's path, or for abstract sockets the "name". + filename="gio/gunixsocketaddress.c" + line="501">Gets @address's path, or for abstract sockets the "name". Guaranteed to be zero-terminated, but an abstract socket may contain embedded zeros, and thus you should use g_unix_socket_address_get_path_len() to get the true length of this string. - + the path for @address + filename="gio/gunixsocketaddress.c" + line="512">the path for @address a #GInetSocketAddress + filename="gio/gunixsocketaddress.c" + line="503">a #GInetSocketAddress @@ -126582,22 +132001,22 @@ of this string. c:identifier="g_unix_socket_address_get_path_len" version="2.22"> Gets the length of @address's path. + filename="gio/gunixsocketaddress.c" + line="522">Gets the length of @address's path. For details, see g_unix_socket_address_get_path(). - + the length of the path + filename="gio/gunixsocketaddress.c" + line="530">the length of the path a #GInetSocketAddress + filename="gio/gunixsocketaddress.c" + line="524">a #GInetSocketAddress @@ -126609,33 +132028,45 @@ For details, see g_unix_socket_address_get_path(). transfer-ownership="none" default-value="FALSE"> Whether or not this is an abstract address + filename="gio/gunixsocketaddress.c" + line="299">Whether or not this is an abstract address Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses. + The type of Unix socket address. + Unix socket path. + Unix socket path, as a byte array. @@ -126651,7 +132082,7 @@ abstract addresses. - + @@ -126660,7 +132091,7 @@ abstract addresses. c:type="GUnixSocketAddressPrivate" disguised="1" opaque="1"> - + glib:get-type="g_unix_socket_address_type_get_type" c:type="GUnixSocketAddressType"> The type of name used by a #GUnixSocketAddress. + filename="gio/gioenums.h" + line="932">The type of name used by a #GUnixSocketAddress. %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS indicates a socket not bound to any name (eg, a client-side socket, @@ -126688,8 +132119,8 @@ pass an appropriate smaller length to bind() or connect(). This is glib:nick="invalid" glib:name="G_UNIX_SOCKET_ADDRESS_INVALID"> invalid + filename="gio/gioenums.h" + line="934">invalid anonymous + filename="gio/gioenums.h" + line="935">anonymous a filesystem path + filename="gio/gioenums.h" + line="936">a filesystem path an abstract name + filename="gio/gioenums.h" + line="937">an abstract name an abstract name, 0-padded + filename="gio/gioenums.h" + line="938">an abstract name, 0-padded to the full length of a unix socket name - + @@ -126739,7 +132170,7 @@ pass an appropriate smaller length to bind() or connect(). This is - + @@ -126749,23 +132180,23 @@ pass an appropriate smaller length to bind() or connect(). This is value="gio-vfs" c:type="G_VFS_EXTENSION_POINT_NAME"> Extension point for #GVfs functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + - + @@ -126774,7 +132205,7 @@ See [Extending GIO][extending-gio]. - + @@ -126784,7 +132215,7 @@ See [Extending GIO][extending-gio]. value="class" c:type="G_VOLUME_IDENTIFIER_KIND_CLASS"> The string used to obtain the volume class with g_volume_get_identifier(). Known volume classes include `device`, `network`, and `loop`. Other @@ -126794,7 +132225,7 @@ This is intended to be used by applications to classify #GVolume instances into different sections - for example a file manager or file chooser can use this information to show `network` volumes under a "Network" heading and `device` volumes under a "Devices" heading. - + deprecated="1" deprecated-version="2.58"> The string used to obtain a Hal UDI with g_volume_get_identifier(). Do not use, HAL is deprecated. - + The string used to obtain a filesystem label with g_volume_get_identifier(). - + The string used to obtain a NFS mount with g_volume_get_identifier(). - + The string used to obtain a Unix device path with g_volume_get_identifier(). - + The string used to obtain a UUID with g_volume_get_identifier(). - + - + @@ -126857,7 +132288,7 @@ a "Network" heading and `device` volumes under a "Devices" heading. - + @@ -126867,16 +132298,16 @@ a "Network" heading and `device` volumes under a "Devices" heading. value="gio-volume-monitor" c:type="G_VOLUME_MONITOR_EXTENSION_POINT_NAME"> Extension point for volume monitor functionality. -See [Extending GIO][extending-gio]. - +See [Extending GIO](overview.html#extending-gio). + - + @@ -126890,36 +132321,36 @@ See [Extending GIO][extending-gio]. glib:get-type="g_vfs_get_type" glib:type-struct="VfsClass"> Entry point for using GIO functionality. - + filename="gio/gvfs.c" + line="33">Entry point for using GIO functionality. + Gets the default #GVfs for the system. - + filename="gio/gvfs.c" + line="341">Gets the default #GVfs for the system. + a #GVfs, which will be the local + filename="gio/gvfs.c" + line="346">a #GVfs, which will be the local file system #GVfs if no other implementation is available. Gets the local #GVfs for the system. - + filename="gio/gvfs.c" + line="369">Gets the local #GVfs for the system. + a #GVfs. + filename="gio/gvfs.c" + line="374">a #GVfs. - + @@ -126934,7 +132365,7 @@ See [Extending GIO][extending-gio]. - + @@ -126949,58 +132380,58 @@ See [Extending GIO][extending-gio]. Gets a #GFile for @path. - + filename="gio/gvfs.c" + line="144">Gets a #GFile for @path. + a #GFile. + filename="gio/gvfs.c" + line="151">a #GFile. Free the returned object with g_object_unref(). a #GVfs. + filename="gio/gvfs.c" + line="146">a #GVfs. a string containing a VFS path. + filename="gio/gvfs.c" + line="147">a string containing a VFS path. Gets a #GFile for @uri. + filename="gio/gvfs.c" + line="219">Gets a #GFile for @uri. This operation never fails, but the returned object might not support any I/O operation if the URI is malformed or if the URI scheme is not supported. - + a #GFile. + filename="gio/gvfs.c" + line="230">a #GFile. Free the returned object with g_object_unref(). a#GVfs. + filename="gio/gvfs.c" + line="221">a#GVfs. a string containing a URI + filename="gio/gvfs.c" + line="222">a string containing a URI @@ -127008,13 +132439,13 @@ is malformed or if the URI scheme is not supported. Gets a list of URI schemes supported by @vfs. - + filename="gio/gvfs.c" + line="254">Gets a list of URI schemes supported by @vfs. + a %NULL-terminated array of strings. + filename="gio/gvfs.c" + line="260">a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. @@ -127024,35 +132455,35 @@ is malformed or if the URI scheme is not supported. a #GVfs. + filename="gio/gvfs.c" + line="256">a #GVfs. Checks if the VFS is active. - + filename="gio/gvfs.c" + line="122">Checks if the VFS is active. + %TRUE if construction of the @vfs was successful + filename="gio/gvfs.c" + line="128">%TRUE if construction of the @vfs was successful and it is now active. a #GVfs. + filename="gio/gvfs.c" + line="124">a #GVfs. - + @@ -127092,7 +132523,7 @@ is malformed or if the URI scheme is not supported. - + @@ -127109,7 +132540,7 @@ is malformed or if the URI scheme is not supported. - + @@ -127123,7 +132554,7 @@ is malformed or if the URI scheme is not supported. - + @@ -127150,87 +132581,87 @@ is malformed or if the URI scheme is not supported. This operation never fails, but the returned object might + filename="gio/gvfs.c" + line="308">This operation never fails, but the returned object might not support any I/O operations if the @parse_name cannot be parsed by the #GVfs module. - + a #GFile for the given @parse_name. + filename="gio/gvfs.c" + line="317">a #GFile for the given @parse_name. Free the returned object with g_object_unref(). a #GVfs. + filename="gio/gvfs.c" + line="310">a #GVfs. a string to be parsed by the VFS module. + filename="gio/gvfs.c" + line="311">a string to be parsed by the VFS module. Gets a #GFile for @path. - + filename="gio/gvfs.c" + line="144">Gets a #GFile for @path. + a #GFile. + filename="gio/gvfs.c" + line="151">a #GFile. Free the returned object with g_object_unref(). a #GVfs. + filename="gio/gvfs.c" + line="146">a #GVfs. a string containing a VFS path. + filename="gio/gvfs.c" + line="147">a string containing a VFS path. Gets a #GFile for @uri. + filename="gio/gvfs.c" + line="219">Gets a #GFile for @uri. This operation never fails, but the returned object might not support any I/O operation if the URI is malformed or if the URI scheme is not supported. - + a #GFile. + filename="gio/gvfs.c" + line="230">a #GFile. Free the returned object with g_object_unref(). a#GVfs. + filename="gio/gvfs.c" + line="221">a#GVfs. a string containing a URI + filename="gio/gvfs.c" + line="222">a string containing a URI @@ -127238,13 +132669,13 @@ is malformed or if the URI scheme is not supported. Gets a list of URI schemes supported by @vfs. - + filename="gio/gvfs.c" + line="254">Gets a list of URI schemes supported by @vfs. + a %NULL-terminated array of strings. + filename="gio/gvfs.c" + line="260">a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. @@ -127254,58 +132685,58 @@ is malformed or if the URI scheme is not supported. a #GVfs. + filename="gio/gvfs.c" + line="256">a #GVfs. Checks if the VFS is active. - + filename="gio/gvfs.c" + line="122">Checks if the VFS is active. + %TRUE if construction of the @vfs was successful + filename="gio/gvfs.c" + line="128">%TRUE if construction of the @vfs was successful and it is now active. a #GVfs. + filename="gio/gvfs.c" + line="124">a #GVfs. This operation never fails, but the returned object might + filename="gio/gvfs.c" + line="308">This operation never fails, but the returned object might not support any I/O operations if the @parse_name cannot be parsed by the #GVfs module. - + a #GFile for the given @parse_name. + filename="gio/gvfs.c" + line="317">a #GFile for the given @parse_name. Free the returned object with g_object_unref(). a #GVfs. + filename="gio/gvfs.c" + line="310">a #GVfs. a string to be parsed by the VFS module. + filename="gio/gvfs.c" + line="311">a string to be parsed by the VFS module. @@ -127314,8 +132745,8 @@ be parsed by the #GVfs module. c:identifier="g_vfs_register_uri_scheme" version="2.50"> Registers @uri_func and @parse_name_func as the #GFile URI and parse name + filename="gio/gvfs.c" + line="387">Registers @uri_func and @parse_name_func as the #GFile URI and parse name lookup functions for URIs with a scheme matching @scheme. Note that @scheme is registered only within the running application, as opposed to desktop-wide as it happens with GVfs backends. @@ -127335,25 +132766,25 @@ g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). It's an error to call this function twice with the same scheme. To unregister a custom URI scheme, use g_vfs_unregister_uri_scheme(). - + %TRUE if @scheme was successfully registered, or %FALSE if a handler + filename="gio/gvfs.c" + line="424">%TRUE if @scheme was successfully registered, or %FALSE if a handler for @scheme already exists. a #GVfs + filename="gio/gvfs.c" + line="389">a #GVfs an URI scheme, e.g. "http" + filename="gio/gvfs.c" + line="390">an URI scheme, e.g. "http" closure="2" destroy="3"> a #GVfsFileLookupFunc + filename="gio/gvfs.c" + line="391">a #GVfsFileLookupFunc nullable="1" allow-none="1"> custom data passed to be passed to @uri_func, or %NULL + filename="gio/gvfs.c" + line="392">custom data passed to be passed to @uri_func, or %NULL allow-none="1" scope="async"> function to be called when unregistering the + filename="gio/gvfs.c" + line="393">function to be called when unregistering the URI scheme, or when @vfs is disposed, to free the resources used by the URI lookup function @@ -127397,8 +132828,8 @@ a custom URI scheme, use g_vfs_unregister_uri_scheme(). closure="5" destroy="6"> a #GVfsFileLookupFunc + filename="gio/gvfs.c" + line="396">a #GVfsFileLookupFunc nullable="1" allow-none="1"> custom data passed to be passed to + filename="gio/gvfs.c" + line="397">custom data passed to be passed to @parse_name_func, or %NULL @@ -127417,8 +132848,8 @@ a custom URI scheme, use g_vfs_unregister_uri_scheme(). allow-none="1" scope="async"> function to be called when unregistering the + filename="gio/gvfs.c" + line="399">function to be called when unregistering the URI scheme, or when @vfs is disposed, to free the resources used by the parse name lookup function @@ -127429,28 +132860,28 @@ a custom URI scheme, use g_vfs_unregister_uri_scheme(). c:identifier="g_vfs_unregister_uri_scheme" version="2.50"> Unregisters the URI handler for @scheme previously registered with + filename="gio/gvfs.c" + line="472">Unregisters the URI handler for @scheme previously registered with g_vfs_register_uri_scheme(). - + %TRUE if @scheme was successfully unregistered, or %FALSE if a + filename="gio/gvfs.c" + line="480">%TRUE if @scheme was successfully unregistered, or %FALSE if a handler for @scheme does not exist. a #GVfs + filename="gio/gvfs.c" + line="474">a #GVfs an URI scheme, e.g. "http" + filename="gio/gvfs.c" + line="475">an URI scheme, e.g. "http" @@ -127460,25 +132891,25 @@ g_vfs_register_uri_scheme(). - + - + %TRUE if construction of the @vfs was successful + filename="gio/gvfs.c" + line="128">%TRUE if construction of the @vfs was successful and it is now active. a #GVfs. + filename="gio/gvfs.c" + line="124">a #GVfs. @@ -127486,25 +132917,25 @@ g_vfs_register_uri_scheme(). - + a #GFile. + filename="gio/gvfs.c" + line="151">a #GFile. Free the returned object with g_object_unref(). a #GVfs. + filename="gio/gvfs.c" + line="146">a #GVfs. a string containing a VFS path. + filename="gio/gvfs.c" + line="147">a string containing a VFS path. @@ -127512,25 +132943,25 @@ g_vfs_register_uri_scheme(). - + a #GFile. + filename="gio/gvfs.c" + line="230">a #GFile. Free the returned object with g_object_unref(). a#GVfs. + filename="gio/gvfs.c" + line="221">a#GVfs. a string containing a URI + filename="gio/gvfs.c" + line="222">a string containing a URI @@ -127538,11 +132969,11 @@ g_vfs_register_uri_scheme(). - + a %NULL-terminated array of strings. + filename="gio/gvfs.c" + line="260">a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. @@ -127552,8 +132983,8 @@ g_vfs_register_uri_scheme(). a #GVfs. + filename="gio/gvfs.c" + line="256">a #GVfs. @@ -127561,25 +132992,25 @@ g_vfs_register_uri_scheme(). - + a #GFile for the given @parse_name. + filename="gio/gvfs.c" + line="317">a #GFile for the given @parse_name. Free the returned object with g_object_unref(). a #GVfs. + filename="gio/gvfs.c" + line="310">a #GVfs. a string to be parsed by the VFS module. + filename="gio/gvfs.c" + line="311">a string to be parsed by the VFS module. @@ -127587,7 +133018,7 @@ g_vfs_register_uri_scheme(). - + @@ -127630,7 +133061,7 @@ g_vfs_register_uri_scheme(). - + @@ -127647,7 +133078,7 @@ g_vfs_register_uri_scheme(). - + @@ -127675,7 +133106,7 @@ g_vfs_register_uri_scheme(). - + @@ -127691,7 +133122,7 @@ g_vfs_register_uri_scheme(). - + @@ -127710,7 +133141,7 @@ g_vfs_register_uri_scheme(). - + @@ -127726,7 +133157,7 @@ g_vfs_register_uri_scheme(). - + @@ -127734,7 +133165,7 @@ g_vfs_register_uri_scheme(). - + @@ -127742,7 +133173,7 @@ g_vfs_register_uri_scheme(). - + @@ -127750,7 +133181,7 @@ g_vfs_register_uri_scheme(). - + @@ -127758,7 +133189,7 @@ g_vfs_register_uri_scheme(). - + @@ -127766,7 +133197,7 @@ g_vfs_register_uri_scheme(). - + @@ -127777,30 +133208,32 @@ g_vfs_register_uri_scheme(). c:type="GVfsFileLookupFunc" version="2.50"> This function type is used by g_vfs_register_uri_scheme() to make it -possible for a client to associate an URI scheme to a different #GFile +possible for a client to associate a URI scheme to a different #GFile implementation. The client should return a reference to the new file that has been created for @uri, or %NULL to continue with the default implementation. - - + + a #GFile for @identifier. - a #GVfs + a #GVfs the identifier to look up a #GFile for. This can either - be an URI or a parse name as returned by g_file_get_parse_name() + be a URI or a parse name as returned by g_file_get_parse_name() allow-none="1" closure="2"> user data passed to the function + filename="gio/gvfs.h" + line="46">user data passed to the function, or %NULL @@ -127822,91 +133255,100 @@ created for @uri, or %NULL to continue with the default implementation. glib:get-type="g_volume_get_type" glib:type-struct="VolumeIface"> The #GVolume interface represents user-visible objects that can be -mounted. Note, when porting from GnomeVFS, #GVolume is the moral -equivalent of #GnomeVFSDrive. + filename="gio/gvolume.c" + line="34">The `GVolume` interface represents user-visible objects that can be +mounted. For example, a file system partition on a USB flash drive, or an +optical disc inserted into a disc drive. -Mounting a #GVolume instance is an asynchronous operation. For more -information about asynchronous operations, see #GAsyncResult and -#GTask. To mount a #GVolume, first call g_volume_mount() with (at -least) the #GVolume instance, optionally a #GMountOperation object -and a #GAsyncReadyCallback. +If a `GVolume` is currently mounted, the corresponding [iface@Gio.Mount] can +be retrieved using [method@Gio.Volume.get_mount]. -Typically, one will only want to pass %NULL for the -#GMountOperation if automounting all volumes when a desktop session -starts since it's not desirable to put up a lot of dialogs asking +Mounting a `GVolume` instance is an asynchronous operation. For more +information about asynchronous operations, see [iface@Gio.AsyncResult] and +[class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount] +with (at least) the `GVolume` instance, optionally a +[class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback]. + +Typically, one will only want to pass `NULL` for the +[class@Gio.MountOperation] if automounting all volumes when a desktop session +starts since it’s not desirable to put up a lot of dialogs asking for credentials. The callback will be fired when the operation has resolved (either -with success or failure), and a #GAsyncResult instance will be +with success or failure), and a [iface@Gio.AsyncResult] instance will be passed to the callback. That callback should then call -g_volume_mount_finish() with the #GVolume instance and the -#GAsyncResult data to see if the operation was completed -successfully. If an @error is present when g_volume_mount_finish() -is called, then it will be filled with any error information. +[method@Gio.Volume.mount_finish] with the `GVolume` instance and the +[iface@Gio.AsyncResult] data to see if the operation was completed +successfully. If a [type@GLib.Error] is present when +[method@Gio.Volume.mount_finish] is called, then it will be filled with any +error information. + +Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), +`GVolume` is the moral equivalent of `GnomeVFSDrive`. -## Volume Identifiers # {#volume-identifier} +## Volume Identifiers It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume -to an application via the commandline). For this purpose, GIO -allows to obtain an 'identifier' for the volume. There can be +to an application via the command line). For this purpose, GIO +allows to obtain an ‘identifier’ for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: -%G_VOLUME_IDENTIFIER_KIND_UUID, %G_VOLUME_IDENTIFIER_KIND_LABEL, etc. -Use g_volume_get_identifier() to obtain an identifier for a volume. +`G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc. +Use [method@Gio.Volume.get_identifier] to obtain an identifier for a volume. - -Note that %G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available -when the gvfs hal volume monitor is in use. Other volume monitors -will generally be able to provide the %G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE +Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available +when the GVFS hal volume monitor is in use. Other volume monitors +will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` identifier, which can be used to obtain a hal device by means of -libhal_manager_find_device_string_match(). - +`libhal_manager_find_device_string_match()`. + Checks if a volume can be ejected. - + filename="gio/gvolume.c" + line="289">Checks if a volume can be ejected. + %TRUE if the @volume can be ejected. %FALSE otherwise + filename="gio/gvolume.c" + line="295">%TRUE if the @volume can be ejected. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="291">a #GVolume Checks if a volume can be mounted. - + filename="gio/gvolume.c" + line="266">Checks if a volume can be mounted. + %TRUE if the @volume can be mounted. %FALSE otherwise + filename="gio/gvolume.c" + line="272">%TRUE if the @volume can be mounted. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="268">a #GVolume - + Changed signal that is emitted when the volume's state has changed. + @@ -127919,28 +133361,29 @@ libhal_manager_find_device_string_match(). + deprecated-version="2.22" + glib:finish-func="eject_finish"> Ejects a volume. This is an asynchronous operation, and is + filename="gio/gvolume.c" + line="410">Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the @volume and #GAsyncResult returned in the @callback. Use g_volume_eject_with_operation() instead. - + a #GVolume + filename="gio/gvolume.c" + line="412">a #GVolume flags affecting the unmount if required for eject + filename="gio/gvolume.c" + line="413">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="414">optional #GCancellable object, %NULL to ignore scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="415">a #GAsyncReadyCallback, or %NULL allow-none="1" closure="3"> user data that gets passed to @callback + filename="gio/gvolume.c" + line="416">user data that gets passed to @callback @@ -127981,55 +133424,56 @@ and #GAsyncResult returned in the @callback. deprecated-version="2.22" throws="1"> Finishes ejecting a volume. If any errors occurred during the operation, + filename="gio/gvolume.c" + line="449">Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_volume_eject_with_operation_finish() instead. - + %TRUE, %FALSE if operation failed + filename="gio/gvolume.c" + line="458">%TRUE, %FALSE if operation failed pointer to a #GVolume + filename="gio/gvolume.c" + line="451">pointer to a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="452">a #GAsyncResult + version="2.22" + glib:finish-func="eject_with_operation_finish"> Ejects a volume. This is an asynchronous operation, and is + filename="gio/gvolume.c" + line="481">Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the @volume and #GAsyncResult data returned in the @callback. - + a #GVolume + filename="gio/gvolume.c" + line="483">a #GVolume flags affecting the unmount if required for eject + filename="gio/gvolume.c" + line="484">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to + filename="gio/gvolume.c" + line="485">a #GMountOperation or %NULL to avoid user interaction @@ -128047,8 +133491,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="487">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="488">a #GAsyncReadyCallback, or %NULL allow-none="1" closure="4"> user data passed to @callback + filename="gio/gvolume.c" + line="489">user data passed to @callback @@ -128079,27 +133523,27 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes ejecting a volume. If any errors occurred during the operation, + filename="gio/gvolume.c" + line="529">Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the volume was successfully ejected. %FALSE otherwise + filename="gio/gvolume.c" + line="538">%TRUE if the volume was successfully ejected. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="531">a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="532">a #GAsyncResult @@ -128107,14 +133551,14 @@ and #GAsyncResult data returned in the @callback. Gets the kinds of [identifiers][volume-identifier] that @volume has. + filename="gio/gvolume.c" + line="594">Gets the kinds of [identifiers](#volume-identifiers) that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. - + a %NULL-terminated array + filename="gio/gvolume.c" + line="601">a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -128123,8 +133567,8 @@ Use g_volume_get_identifier() to obtain the identifiers themselves. a #GVolume + filename="gio/gvolume.c" + line="596">a #GVolume @@ -128133,8 +133577,8 @@ Use g_volume_get_identifier() to obtain the identifiers themselves. invoker="get_activation_root" version="2.18"> Gets the activation root for a #GVolume if it is known ahead of + filename="gio/gvolume.c" + line="618">Gets the activation root for a #GVolume if it is known ahead of mount time. Returns %NULL otherwise. If not %NULL and if @volume is mounted, then the result of g_mount_get_root() on the #GMount object obtained from g_volume_get_mount() will always @@ -128160,32 +133604,32 @@ will always be %TRUE. Activation roots are typically used in #GVolumeMonitor implementations to find the underlying mount to shadow, see g_mount_is_shadowed() for more details. - + the activation root of @volume + filename="gio/gvolume.c" + line="649">the activation root of @volume or %NULL. Use g_object_unref() to free. a #GVolume + filename="gio/gvolume.c" + line="620">a #GVolume Gets the drive for the @volume. - + filename="gio/gvolume.c" + line="221">Gets the drive for the @volume. + a #GDrive or %NULL if @volume is not + filename="gio/gvolume.c" + line="227">a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128193,21 +133637,21 @@ g_mount_is_shadowed() for more details. a #GVolume + filename="gio/gvolume.c" + line="223">a #GVolume Gets the icon for @volume. - + filename="gio/gvolume.c" + line="142">Gets the icon for @volume. + a #GIcon. + filename="gio/gvolume.c" + line="148">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128215,23 +133659,23 @@ g_mount_is_shadowed() for more details. a #GVolume + filename="gio/gvolume.c" + line="144">a #GVolume Gets the identifier of the given kind for @volume. -See the [introduction][volume-identifier] for more + filename="gio/gvolume.c" + line="564">Gets the identifier of the given kind for @volume. +See the [introduction](#volume-identifiers) for more information about volume identifiers. - + a newly allocated string containing the + filename="gio/gvolume.c" + line="573">a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier @@ -128239,27 +133683,27 @@ information about volume identifiers. a #GVolume + filename="gio/gvolume.c" + line="566">a #GVolume the kind of identifier to return + filename="gio/gvolume.c" + line="567">the kind of identifier to return Gets the mount for the @volume. - + filename="gio/gvolume.c" + line="243">Gets the mount for the @volume. + a #GMount or %NULL if @volume isn't mounted. + filename="gio/gvolume.c" + line="249">a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128267,29 +133711,29 @@ information about volume identifiers. a #GVolume + filename="gio/gvolume.c" + line="245">a #GVolume Gets the name of @volume. - + filename="gio/gvolume.c" + line="121">Gets the name of @volume. + the name for the given @volume. The returned string should + filename="gio/gvolume.c" + line="127">the name for the given @volume. The returned string should be freed with g_free() when no longer needed. a #GVolume + filename="gio/gvolume.c" + line="123">a #GVolume @@ -128298,20 +133742,20 @@ information about volume identifiers. invoker="get_sort_key" version="2.32"> Gets the sort key for @volume, if any. - + filename="gio/gvolume.c" + line="668">Gets the sort key for @volume, if any. + Sorting key for @volume or %NULL if no such key is available + filename="gio/gvolume.c" + line="674">Sorting key for @volume or %NULL if no such key is available a #GVolume + filename="gio/gvolume.c" + line="670">a #GVolume @@ -128320,13 +133764,13 @@ information about volume identifiers. invoker="get_symbolic_icon" version="2.34"> Gets the symbolic icon for @volume. - + filename="gio/gvolume.c" + line="164">Gets the symbolic icon for @volume. + a #GIcon. + filename="gio/gvolume.c" + line="170">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128334,24 +133778,24 @@ information about volume identifiers. a #GVolume + filename="gio/gvolume.c" + line="166">a #GVolume Gets the UUID for the @volume. The reference is typically based on + filename="gio/gvolume.c" + line="195">Gets the UUID for the @volume. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - + the UUID for @volume or %NULL if no UUID + filename="gio/gvolume.c" + line="204">the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. @@ -128360,65 +133804,65 @@ available. a #GVolume + filename="gio/gvolume.c" + line="197">a #GVolume Finishes mounting a volume. If any errors occurred during the operation, + filename="gio/gvolume.c" + line="375">Finishes mounting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. If the mount operation succeeded, g_volume_get_mount() on @volume is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on #GVolumeMonitor. - + %TRUE, %FALSE if operation failed + filename="gio/gvolume.c" + line="389">%TRUE, %FALSE if operation failed a #GVolume + filename="gio/gvolume.c" + line="377">a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="378">a #GAsyncResult Mounts a volume. This is an asynchronous operation, and is + filename="gio/gvolume.c" + line="336">Mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the @volume and #GAsyncResult returned in the @callback. - + a #GVolume + filename="gio/gvolume.c" + line="338">a #GVolume flags affecting the operation + filename="gio/gvolume.c" + line="339">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid user interaction + filename="gio/gvolume.c" + line="340">a #GMountOperation or %NULL to avoid user interaction nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="341">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="342">a #GAsyncReadyCallback, or %NULL allow-none="1" closure="4"> user data that gets passed to @callback + filename="gio/gvolume.c" + line="343">user data that gets passed to @callback - + The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. + @@ -128475,60 +133922,60 @@ and #GAsyncResult returned in the @callback. Returns whether the volume should be automatically mounted. - + filename="gio/gvolume.c" + line="312">Returns whether the volume should be automatically mounted. + %TRUE if the volume should be automatically mounted + filename="gio/gvolume.c" + line="318">%TRUE if the volume should be automatically mounted a #GVolume + filename="gio/gvolume.c" + line="314">a #GVolume Checks if a volume can be ejected. - + filename="gio/gvolume.c" + line="289">Checks if a volume can be ejected. + %TRUE if the @volume can be ejected. %FALSE otherwise + filename="gio/gvolume.c" + line="295">%TRUE if the @volume can be ejected. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="291">a #GVolume Checks if a volume can be mounted. - + filename="gio/gvolume.c" + line="266">Checks if a volume can be mounted. + %TRUE if the @volume can be mounted. %FALSE otherwise + filename="gio/gvolume.c" + line="272">%TRUE if the @volume can be mounted. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="268">a #GVolume @@ -128536,28 +133983,29 @@ and #GAsyncResult returned in the @callback. + deprecated-version="2.22" + glib:finish-func="eject_finish"> Ejects a volume. This is an asynchronous operation, and is + filename="gio/gvolume.c" + line="410">Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the @volume and #GAsyncResult returned in the @callback. Use g_volume_eject_with_operation() instead. - + a #GVolume + filename="gio/gvolume.c" + line="412">a #GVolume flags affecting the unmount if required for eject + filename="gio/gvolume.c" + line="413">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="414">optional #GCancellable object, %NULL to ignore scope="async" closure="3"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="415">a #GAsyncReadyCallback, or %NULL nullable="1" allow-none="1"> user data that gets passed to @callback + filename="gio/gvolume.c" + line="416">user data that gets passed to @callback @@ -128597,55 +134045,56 @@ and #GAsyncResult returned in the @callback. deprecated-version="2.22" throws="1"> Finishes ejecting a volume. If any errors occurred during the operation, + filename="gio/gvolume.c" + line="449">Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Use g_volume_eject_with_operation_finish() instead. - + %TRUE, %FALSE if operation failed + filename="gio/gvolume.c" + line="458">%TRUE, %FALSE if operation failed pointer to a #GVolume + filename="gio/gvolume.c" + line="451">pointer to a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="452">a #GAsyncResult + version="2.22" + glib:finish-func="eject_with_operation_finish"> Ejects a volume. This is an asynchronous operation, and is + filename="gio/gvolume.c" + line="481">Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the @volume and #GAsyncResult data returned in the @callback. - + a #GVolume + filename="gio/gvolume.c" + line="483">a #GVolume flags affecting the unmount if required for eject + filename="gio/gvolume.c" + line="484">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to + filename="gio/gvolume.c" + line="485">a #GMountOperation or %NULL to avoid user interaction @@ -128663,8 +134112,8 @@ and #GAsyncResult data returned in the @callback. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="487">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="488">a #GAsyncReadyCallback, or %NULL nullable="1" allow-none="1"> user data passed to @callback + filename="gio/gvolume.c" + line="489">user data passed to @callback @@ -128694,27 +134143,27 @@ and #GAsyncResult data returned in the @callback. version="2.22" throws="1"> Finishes ejecting a volume. If any errors occurred during the operation, + filename="gio/gvolume.c" + line="529">Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. - + %TRUE if the volume was successfully ejected. %FALSE otherwise + filename="gio/gvolume.c" + line="538">%TRUE if the volume was successfully ejected. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="531">a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="532">a #GAsyncResult @@ -128722,14 +134171,14 @@ and #GAsyncResult data returned in the @callback. Gets the kinds of [identifiers][volume-identifier] that @volume has. + filename="gio/gvolume.c" + line="594">Gets the kinds of [identifiers](#volume-identifiers) that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. - + a %NULL-terminated array + filename="gio/gvolume.c" + line="601">a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -128738,8 +134187,8 @@ Use g_volume_get_identifier() to obtain the identifiers themselves. a #GVolume + filename="gio/gvolume.c" + line="596">a #GVolume @@ -128748,8 +134197,8 @@ Use g_volume_get_identifier() to obtain the identifiers themselves. c:identifier="g_volume_get_activation_root" version="2.18"> Gets the activation root for a #GVolume if it is known ahead of + filename="gio/gvolume.c" + line="618">Gets the activation root for a #GVolume if it is known ahead of mount time. Returns %NULL otherwise. If not %NULL and if @volume is mounted, then the result of g_mount_get_root() on the #GMount object obtained from g_volume_get_mount() will always @@ -128775,32 +134224,32 @@ will always be %TRUE. Activation roots are typically used in #GVolumeMonitor implementations to find the underlying mount to shadow, see g_mount_is_shadowed() for more details. - + the activation root of @volume + filename="gio/gvolume.c" + line="649">the activation root of @volume or %NULL. Use g_object_unref() to free. a #GVolume + filename="gio/gvolume.c" + line="620">a #GVolume Gets the drive for the @volume. - + filename="gio/gvolume.c" + line="221">Gets the drive for the @volume. + a #GDrive or %NULL if @volume is not + filename="gio/gvolume.c" + line="227">a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128808,21 +134257,21 @@ g_mount_is_shadowed() for more details. a #GVolume + filename="gio/gvolume.c" + line="223">a #GVolume Gets the icon for @volume. - + filename="gio/gvolume.c" + line="142">Gets the icon for @volume. + a #GIcon. + filename="gio/gvolume.c" + line="148">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128830,23 +134279,23 @@ g_mount_is_shadowed() for more details. a #GVolume + filename="gio/gvolume.c" + line="144">a #GVolume Gets the identifier of the given kind for @volume. -See the [introduction][volume-identifier] for more + filename="gio/gvolume.c" + line="564">Gets the identifier of the given kind for @volume. +See the [introduction](#volume-identifiers) for more information about volume identifiers. - + a newly allocated string containing the + filename="gio/gvolume.c" + line="573">a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier @@ -128854,27 +134303,27 @@ information about volume identifiers. a #GVolume + filename="gio/gvolume.c" + line="566">a #GVolume the kind of identifier to return + filename="gio/gvolume.c" + line="567">the kind of identifier to return Gets the mount for the @volume. - + filename="gio/gvolume.c" + line="243">Gets the mount for the @volume. + a #GMount or %NULL if @volume isn't mounted. + filename="gio/gvolume.c" + line="249">a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128882,29 +134331,29 @@ information about volume identifiers. a #GVolume + filename="gio/gvolume.c" + line="245">a #GVolume Gets the name of @volume. - + filename="gio/gvolume.c" + line="121">Gets the name of @volume. + the name for the given @volume. The returned string should + filename="gio/gvolume.c" + line="127">the name for the given @volume. The returned string should be freed with g_free() when no longer needed. a #GVolume + filename="gio/gvolume.c" + line="123">a #GVolume @@ -128913,20 +134362,20 @@ information about volume identifiers. c:identifier="g_volume_get_sort_key" version="2.32"> Gets the sort key for @volume, if any. - + filename="gio/gvolume.c" + line="668">Gets the sort key for @volume, if any. + Sorting key for @volume or %NULL if no such key is available + filename="gio/gvolume.c" + line="674">Sorting key for @volume or %NULL if no such key is available a #GVolume + filename="gio/gvolume.c" + line="670">a #GVolume @@ -128935,13 +134384,13 @@ information about volume identifiers. c:identifier="g_volume_get_symbolic_icon" version="2.34"> Gets the symbolic icon for @volume. - + filename="gio/gvolume.c" + line="164">Gets the symbolic icon for @volume. + a #GIcon. + filename="gio/gvolume.c" + line="170">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -128949,24 +134398,24 @@ information about volume identifiers. a #GVolume + filename="gio/gvolume.c" + line="166">a #GVolume Gets the UUID for the @volume. The reference is typically based on + filename="gio/gvolume.c" + line="195">Gets the UUID for the @volume. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - + the UUID for @volume or %NULL if no UUID + filename="gio/gvolume.c" + line="204">the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. @@ -128975,33 +134424,35 @@ available. a #GVolume + filename="gio/gvolume.c" + line="197">a #GVolume - + Mounts a volume. This is an asynchronous operation, and is + filename="gio/gvolume.c" + line="336">Mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the @volume and #GAsyncResult returned in the @callback. - + a #GVolume + filename="gio/gvolume.c" + line="338">a #GVolume flags affecting the operation + filename="gio/gvolume.c" + line="339">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid user interaction + filename="gio/gvolume.c" + line="340">a #GMountOperation or %NULL to avoid user interaction nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="341">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="342">a #GAsyncReadyCallback, or %NULL nullable="1" allow-none="1"> user data that gets passed to @callback + filename="gio/gvolume.c" + line="343">user data that gets passed to @callback @@ -129048,68 +134499,68 @@ and #GAsyncResult returned in the @callback. c:identifier="g_volume_mount_finish" throws="1"> Finishes mounting a volume. If any errors occurred during the operation, + filename="gio/gvolume.c" + line="375">Finishes mounting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. If the mount operation succeeded, g_volume_get_mount() on @volume is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on #GVolumeMonitor. - + %TRUE, %FALSE if operation failed + filename="gio/gvolume.c" + line="389">%TRUE, %FALSE if operation failed a #GVolume + filename="gio/gvolume.c" + line="377">a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="378">a #GAsyncResult Returns whether the volume should be automatically mounted. - + filename="gio/gvolume.c" + line="312">Returns whether the volume should be automatically mounted. + %TRUE if the volume should be automatically mounted + filename="gio/gvolume.c" + line="318">%TRUE if the volume should be automatically mounted a #GVolume + filename="gio/gvolume.c" + line="314">a #GVolume Emitted when the volume has been changed. + filename="gio/gvolume.c" + line="92">Emitted when the volume has been changed. This signal is emitted when the #GVolume have been removed. If + filename="gio/gvolume.c" + line="105">This signal is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. @@ -129121,18 +134572,21 @@ release them so the object can be finalized. c:type="GVolumeIface" glib:is-gtype-struct-for="Volume"> Interface for implementing operations for mountable volumes. - + The parent interface. + Changed signal that is emitted when the volume's state has changed. - + @@ -129144,8 +134598,11 @@ release them so the object can be finalized. + The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. - + @@ -129157,32 +134614,38 @@ release them so the object can be finalized. + Gets a string containing the name of the #GVolume. - + the name for the given @volume. The returned string should + filename="gio/gvolume.c" + line="127">the name for the given @volume. The returned string should be freed with g_free() when no longer needed. a #GVolume + filename="gio/gvolume.c" + line="123">a #GVolume + Gets a #GIcon for the #GVolume. - + a #GIcon. + filename="gio/gvolume.c" + line="148">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -129190,20 +134653,23 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="144">a #GVolume + Gets the UUID for the #GVolume. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - + the UUID for @volume or %NULL if no UUID + filename="gio/gvolume.c" + line="204">the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. @@ -129212,20 +134678,23 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="197">a #GVolume + Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive. - + a #GDrive or %NULL if @volume is not + filename="gio/gvolume.c" + line="227">a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -129233,20 +134702,23 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="223">a #GVolume + Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted. - + a #GMount or %NULL if @volume isn't mounted. + filename="gio/gvolume.c" + line="249">a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -129254,68 +134726,80 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="245">a #GVolume + Returns %TRUE if the #GVolume can be mounted. - + %TRUE if the @volume can be mounted. %FALSE otherwise + filename="gio/gvolume.c" + line="272">%TRUE if the @volume can be mounted. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="268">a #GVolume + Checks if a #GVolume can be ejected. - + %TRUE if the @volume can be ejected. %FALSE otherwise + filename="gio/gvolume.c" + line="295">%TRUE if the @volume can be ejected. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="291">a #GVolume + Mounts a given #GVolume. + #GVolume implementations must emit the #GMountOperation::aborted + signal before completing a mount operation that is aborted while + awaiting input from the user through a #GMountOperation instance. - + a #GVolume + filename="gio/gvolume.c" + line="338">a #GVolume flags affecting the operation + filename="gio/gvolume.c" + line="339">flags affecting the operation nullable="1" allow-none="1"> a #GMountOperation or %NULL to avoid user interaction + filename="gio/gvolume.c" + line="340">a #GMountOperation or %NULL to avoid user interaction nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="341">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="342">a #GAsyncReadyCallback, or %NULL allow-none="1" closure="5"> user data that gets passed to @callback + filename="gio/gvolume.c" + line="343">user data that gets passed to @callback + Finishes a mount operation. - + %TRUE, %FALSE if operation failed + filename="gio/gvolume.c" + line="389">%TRUE, %FALSE if operation failed a #GVolume + filename="gio/gvolume.c" + line="377">a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="378">a #GAsyncResult + Ejects a given #GVolume. - + a #GVolume + filename="gio/gvolume.c" + line="412">a #GVolume flags affecting the unmount if required for eject + filename="gio/gvolume.c" + line="413">flags affecting the unmount if required for eject nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="414">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="415">a #GAsyncReadyCallback, or %NULL allow-none="1" closure="4"> user data that gets passed to @callback + filename="gio/gvolume.c" + line="416">user data that gets passed to @callback + Finishes an eject operation. - + %TRUE, %FALSE if operation failed + filename="gio/gvolume.c" + line="458">%TRUE, %FALSE if operation failed pointer to a #GVolume + filename="gio/gvolume.c" + line="451">pointer to a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="452">a #GAsyncResult + Returns the [identifier](#volume-identifiers) of the given kind, or %NULL if + the #GVolume doesn't have one. - + a newly allocated string containing the + filename="gio/gvolume.c" + line="573">a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier @@ -129476,26 +134973,30 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="566">a #GVolume the kind of identifier to return + filename="gio/gvolume.c" + line="567">the kind of identifier to return + Returns an array strings listing the kinds + of [identifiers](#volume-identifiers) which the #GVolume has. - + a %NULL-terminated array + filename="gio/gvolume.c" + line="601">a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -129504,69 +135005,79 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="596">a #GVolume + Returns %TRUE if the #GVolume should be automatically mounted. - + %TRUE if the volume should be automatically mounted + filename="gio/gvolume.c" + line="318">%TRUE if the volume should be automatically mounted a #GVolume + filename="gio/gvolume.c" + line="314">a #GVolume + Returns the activation root for the #GVolume if it is known in advance or %NULL if + it is not known. - + the activation root of @volume + filename="gio/gvolume.c" + line="649">the activation root of @volume or %NULL. Use g_object_unref() to free. a #GVolume + filename="gio/gvolume.c" + line="620">a #GVolume + Starts ejecting a #GVolume using a #GMountOperation. Since 2.22. - + a #GVolume + filename="gio/gvolume.c" + line="483">a #GVolume flags affecting the unmount if required for eject + filename="gio/gvolume.c" + line="484">flags affecting the unmount if required for eject nullable="1" allow-none="1"> a #GMountOperation or %NULL to + filename="gio/gvolume.c" + line="485">a #GMountOperation or %NULL to avoid user interaction @@ -129584,8 +135095,8 @@ release them so the object can be finalized. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gvolume.c" + line="487">optional #GCancellable object, %NULL to ignore scope="async" closure="5"> a #GAsyncReadyCallback, or %NULL + filename="gio/gvolume.c" + line="488">a #GAsyncReadyCallback, or %NULL allow-none="1" closure="5"> user data passed to @callback + filename="gio/gvolume.c" + line="489">user data passed to @callback + Finishes an eject operation using a #GMountOperation. Since 2.22. - + %TRUE if the volume was successfully ejected. %FALSE otherwise + filename="gio/gvolume.c" + line="538">%TRUE if the volume was successfully ejected. %FALSE otherwise a #GVolume + filename="gio/gvolume.c" + line="531">a #GVolume a #GAsyncResult + filename="gio/gvolume.c" + line="532">a #GAsyncResult + Gets a key used for sorting #GVolume instance or %NULL if no such key exists. Since 2.32. - + Sorting key for @volume or %NULL if no such key is available + filename="gio/gvolume.c" + line="674">Sorting key for @volume or %NULL if no such key is available a #GVolume + filename="gio/gvolume.c" + line="670">a #GVolume + Gets a symbolic #GIcon for the #GVolume. Since 2.34. - + a #GIcon. + filename="gio/gvolume.c" + line="170">a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. @@ -129670,8 +135190,8 @@ release them so the object can be finalized. a #GVolume + filename="gio/gvolume.c" + line="166">a #GVolume @@ -129686,26 +135206,26 @@ release them so the object can be finalized. glib:get-type="g_volume_monitor_get_type" glib:type-struct="VolumeMonitorClass"> #GVolumeMonitor is for listing the user interesting devices and volumes + filename="gio/gvolumemonitor.c" + line="34">`GVolumeMonitor` is for listing the user interesting devices and volumes on the computer. In other words, what a file selector or file manager would show in a sidebar. -#GVolumeMonitor is not -[thread-default-context aware][g-main-context-push-thread-default], -and so should not be used other than from the main thread, with no -thread-default-context active. +`GVolumeMonitor` is not +thread-default-context aware (see +[method@GLib.MainContext.push_thread_default]), and so should not be used +other than from the main thread, with no thread-default-context active. In order to receive updates about volumes and mounts monitored through GVFS, a main loop must be running. - + This function should be called by any #GVolumeMonitor + filename="gio/gunionvolumemonitor.c" + line="562">This function should be called by any #GVolumeMonitor implementation when a new #GMount object is created that is not associated with a #GVolume object. It must be called just before emitting the @mount_added signal. @@ -129738,38 +135258,38 @@ implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions. - + the #GVolume object that is the parent for @mount or %NULL + filename="gio/gunionvolumemonitor.c" + line="595">the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount. a #GMount object to find a parent for + filename="gio/gunionvolumemonitor.c" + line="564">a #GMount object to find a parent for Gets the volume monitor used by gio. - + filename="gio/gunionvolumemonitor.c" + line="504">Gets the volume monitor used by gio. + a reference to the #GVolumeMonitor used by gio. Call - g_object_unref() when done with it. + filename="gio/gunionvolumemonitor.c" + line="509">a reference to the #GVolumeMonitor used by gio. Call + g_object_unref() when done with it, after disconnecting any signal handlers. - + @@ -129783,7 +135303,7 @@ if no wants to adopt the #GMount. - + @@ -129797,7 +135317,7 @@ if no wants to adopt the #GMount. - + @@ -129811,7 +135331,7 @@ if no wants to adopt the #GMount. - + @@ -129825,7 +135345,7 @@ if no wants to adopt the #GMount. - + @@ -129841,16 +135361,16 @@ if no wants to adopt the #GMount. Gets a list of drives connected to the system. + filename="gio/gvolumemonitor.c" + line="279">Gets a list of drives connected to the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + a #GList of connected #GDrive objects. + filename="gio/gvolumemonitor.c" + line="288">a #GList of connected #GDrive objects. @@ -129858,51 +135378,51 @@ its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="281">a #GVolumeMonitor. Finds a #GMount object by its UUID (see g_mount_get_uuid()) - + filename="gio/gvolumemonitor.c" + line="372">Finds a #GMount object by its UUID (see g_mount_get_uuid()) + a #GMount or %NULL if no such mount is available. + filename="gio/gvolumemonitor.c" + line="379">a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="374">a #GVolumeMonitor. the UUID to look for + filename="gio/gvolumemonitor.c" + line="375">the UUID to look for Gets a list of the mounts on the system. + filename="gio/gvolumemonitor.c" + line="325">Gets a list of the mounts on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + a #GList of #GMount objects. + filename="gio/gvolumemonitor.c" + line="334">a #GList of #GMount objects. @@ -129910,51 +135430,51 @@ its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="327">a #GVolumeMonitor. Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - + filename="gio/gvolumemonitor.c" + line="348">Finds a #GVolume object by its UUID (see g_volume_get_uuid()) + a #GVolume or %NULL if no such volume is available. + filename="gio/gvolumemonitor.c" + line="355">a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="350">a #GVolumeMonitor. the UUID to look for + filename="gio/gvolumemonitor.c" + line="351">the UUID to look for Gets a list of the volumes on the system. + filename="gio/gvolumemonitor.c" + line="302">Gets a list of the volumes on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + a #GList of #GVolume objects. + filename="gio/gvolumemonitor.c" + line="311">a #GList of #GVolume objects. @@ -129962,14 +135482,14 @@ its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="304">a #GVolumeMonitor. - + @@ -129983,7 +135503,7 @@ its elements have been unreffed with g_object_unref(). - + @@ -129997,7 +135517,7 @@ its elements have been unreffed with g_object_unref(). - + @@ -130011,7 +135531,7 @@ its elements have been unreffed with g_object_unref(). - + @@ -130025,7 +135545,7 @@ its elements have been unreffed with g_object_unref(). - + @@ -130039,7 +135559,7 @@ its elements have been unreffed with g_object_unref(). - + @@ -130053,7 +135573,7 @@ its elements have been unreffed with g_object_unref(). - + @@ -130069,16 +135589,16 @@ its elements have been unreffed with g_object_unref(). Gets a list of drives connected to the system. + filename="gio/gvolumemonitor.c" + line="279">Gets a list of drives connected to the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + a #GList of connected #GDrive objects. + filename="gio/gvolumemonitor.c" + line="288">a #GList of connected #GDrive objects. @@ -130086,8 +135606,8 @@ its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="281">a #GVolumeMonitor. @@ -130095,43 +135615,43 @@ its elements have been unreffed with g_object_unref(). Finds a #GMount object by its UUID (see g_mount_get_uuid()) - + filename="gio/gvolumemonitor.c" + line="372">Finds a #GMount object by its UUID (see g_mount_get_uuid()) + a #GMount or %NULL if no such mount is available. + filename="gio/gvolumemonitor.c" + line="379">a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="374">a #GVolumeMonitor. the UUID to look for + filename="gio/gvolumemonitor.c" + line="375">the UUID to look for Gets a list of the mounts on the system. + filename="gio/gvolumemonitor.c" + line="325">Gets a list of the mounts on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + a #GList of #GMount objects. + filename="gio/gvolumemonitor.c" + line="334">a #GList of #GMount objects. @@ -130139,8 +135659,8 @@ its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="327">a #GVolumeMonitor. @@ -130148,43 +135668,43 @@ its elements have been unreffed with g_object_unref(). Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - + filename="gio/gvolumemonitor.c" + line="348">Finds a #GVolume object by its UUID (see g_volume_get_uuid()) + a #GVolume or %NULL if no such volume is available. + filename="gio/gvolumemonitor.c" + line="355">a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="350">a #GVolumeMonitor. the UUID to look for + filename="gio/gvolumemonitor.c" + line="351">the UUID to look for Gets a list of the volumes on the system. + filename="gio/gvolumemonitor.c" + line="302">Gets a list of the volumes on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). - + a #GList of #GVolume objects. + filename="gio/gvolumemonitor.c" + line="311">a #GList of #GVolume objects. @@ -130192,8 +135712,8 @@ its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="304">a #GVolumeMonitor. @@ -130206,120 +135726,120 @@ its elements have been unreffed with g_object_unref(). Emitted when a drive changes. + filename="gio/gvolumemonitor.c" + line="222">Emitted when a drive changes. the drive that changed + filename="gio/gvolumemonitor.c" + line="225">the drive that changed Emitted when a drive is connected to the system. + filename="gio/gvolumemonitor.c" + line="192">Emitted when a drive is connected to the system. a #GDrive that was connected. + filename="gio/gvolumemonitor.c" + line="195">a #GDrive that was connected. Emitted when a drive is disconnected from the system. + filename="gio/gvolumemonitor.c" + line="207">Emitted when a drive is disconnected from the system. a #GDrive that was disconnected. + filename="gio/gvolumemonitor.c" + line="210">a #GDrive that was disconnected. Emitted when the eject button is pressed on @drive. + filename="gio/gvolumemonitor.c" + line="237">Emitted when the eject button is pressed on @drive. the drive where the eject button was pressed + filename="gio/gvolumemonitor.c" + line="240">the drive where the eject button was pressed Emitted when the stop button is pressed on @drive. + filename="gio/gvolumemonitor.c" + line="254">Emitted when the stop button is pressed on @drive. the drive where the stop button was pressed + filename="gio/gvolumemonitor.c" + line="257">the drive where the stop button was pressed Emitted when a mount is added. + filename="gio/gvolumemonitor.c" + line="129">Emitted when a mount is added. a #GMount that was added. + filename="gio/gvolumemonitor.c" + line="132">a #GMount that was added. Emitted when a mount changes. + filename="gio/gvolumemonitor.c" + line="177">Emitted when a mount changes. a #GMount that changed. + filename="gio/gvolumemonitor.c" + line="180">a #GMount that changed. May be emitted when a mount is about to be removed. + filename="gio/gvolumemonitor.c" + line="159">May be emitted when a mount is about to be removed. This signal depends on the backend and is only emitted if GIO was used to unmount. @@ -130329,72 +135849,72 @@ GIO was used to unmount. a #GMount that is being unmounted. + filename="gio/gvolumemonitor.c" + line="162">a #GMount that is being unmounted. Emitted when a mount is removed. + filename="gio/gvolumemonitor.c" + line="144">Emitted when a mount is removed. a #GMount that was removed. + filename="gio/gvolumemonitor.c" + line="147">a #GMount that was removed. Emitted when a mountable volume is added to the system. + filename="gio/gvolumemonitor.c" + line="84">Emitted when a mountable volume is added to the system. a #GVolume that was added. + filename="gio/gvolumemonitor.c" + line="87">a #GVolume that was added. Emitted when mountable volume is changed. + filename="gio/gvolumemonitor.c" + line="114">Emitted when mountable volume is changed. a #GVolume that changed. + filename="gio/gvolumemonitor.c" + line="117">a #GVolume that changed. Emitted when a mountable volume is removed from the system. + filename="gio/gvolumemonitor.c" + line="99">Emitted when a mountable volume is removed from the system. a #GVolume that was removed. + filename="gio/gvolumemonitor.c" + line="102">a #GVolume that was removed. @@ -130403,13 +135923,13 @@ GIO was used to unmount. - + - + @@ -130425,7 +135945,7 @@ GIO was used to unmount. - + @@ -130441,7 +135961,7 @@ GIO was used to unmount. - + @@ -130457,7 +135977,7 @@ GIO was used to unmount. - + @@ -130473,7 +135993,7 @@ GIO was used to unmount. - + @@ -130489,7 +136009,7 @@ GIO was used to unmount. - + @@ -130505,7 +136025,7 @@ GIO was used to unmount. - + @@ -130521,7 +136041,7 @@ GIO was used to unmount. - + @@ -130537,7 +136057,7 @@ GIO was used to unmount. - + @@ -130553,7 +136073,7 @@ GIO was used to unmount. - + @@ -130569,7 +136089,7 @@ GIO was used to unmount. - + @@ -130577,11 +136097,11 @@ GIO was used to unmount. - + a #GList of connected #GDrive objects. + filename="gio/gvolumemonitor.c" + line="288">a #GList of connected #GDrive objects. @@ -130589,8 +136109,8 @@ GIO was used to unmount. a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="281">a #GVolumeMonitor. @@ -130598,11 +136118,11 @@ GIO was used to unmount. - + a #GList of #GVolume objects. + filename="gio/gvolumemonitor.c" + line="311">a #GList of #GVolume objects. @@ -130610,8 +136130,8 @@ GIO was used to unmount. a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="304">a #GVolumeMonitor. @@ -130619,11 +136139,11 @@ GIO was used to unmount. - + a #GList of #GMount objects. + filename="gio/gvolumemonitor.c" + line="334">a #GList of #GMount objects. @@ -130631,8 +136151,8 @@ GIO was used to unmount. a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="327">a #GVolumeMonitor. @@ -130640,25 +136160,25 @@ GIO was used to unmount. - + a #GVolume or %NULL if no such volume is available. + filename="gio/gvolumemonitor.c" + line="355">a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="350">a #GVolumeMonitor. the UUID to look for + filename="gio/gvolumemonitor.c" + line="351">the UUID to look for @@ -130666,25 +136186,25 @@ GIO was used to unmount. - + a #GMount or %NULL if no such mount is available. + filename="gio/gvolumemonitor.c" + line="379">a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). a #GVolumeMonitor. + filename="gio/gvolumemonitor.c" + line="374">a #GVolumeMonitor. the UUID to look for + filename="gio/gvolumemonitor.c" + line="375">the UUID to look for @@ -130692,7 +136212,7 @@ GIO was used to unmount. - + @@ -130708,7 +136228,7 @@ GIO was used to unmount. - + @@ -130724,7 +136244,7 @@ GIO was used to unmount. - + @@ -130740,7 +136260,7 @@ GIO was used to unmount. - + @@ -130748,7 +136268,7 @@ GIO was used to unmount. - + @@ -130756,7 +136276,7 @@ GIO was used to unmount. - + @@ -130764,7 +136284,7 @@ GIO was used to unmount. - + @@ -130772,7 +136292,7 @@ GIO was used to unmount. - + @@ -130780,7 +136300,7 @@ GIO was used to unmount. - + @@ -130790,7 +136310,7 @@ GIO was used to unmount. - + @@ -130799,7 +136319,7 @@ GIO was used to unmount. - + @@ -130808,7 +136328,7 @@ GIO was used to unmount. - + @@ -130817,7 +136337,7 @@ GIO was used to unmount. - + @@ -130826,7 +136346,7 @@ GIO was used to unmount. - + @@ -130835,7 +136355,7 @@ GIO was used to unmount. - + @@ -130849,35 +136369,35 @@ GIO was used to unmount. glib:get-type="g_zlib_compressor_get_type" glib:type-struct="ZlibCompressorClass"> #GZlibCompressor is an implementation of #GConverter that + filename="gio/gzlibcompressor.c" + line="45">`GZlibCompressor` is an implementation of [iface@Gio.Converter] that compresses data using zlib. - + Creates a new #GZlibCompressor. - + filename="gio/gzlibcompressor.c" + line="273">Creates a new #GZlibCompressor. + a new #GZlibCompressor + filename="gio/gzlibcompressor.c" + line="280">a new #GZlibCompressor The format to use for the compressed data + filename="gio/gzlibcompressor.c" + line="275">The format to use for the compressed data compression level (0-9), -1 for default + filename="gio/gzlibcompressor.c" + line="276">compression level (0-9), -1 for default @@ -130887,20 +136407,20 @@ compresses data using zlib. glib:get-property="file-info" version="2.26"> Returns the #GZlibCompressor:file-info property. - + filename="gio/gzlibcompressor.c" + line="298">Returns the #GZlibCompressor:file-info property. + a #GFileInfo, or %NULL + filename="gio/gzlibcompressor.c" + line="304">a #GFileInfo, or %NULL a #GZlibCompressor + filename="gio/gzlibcompressor.c" + line="300">a #GZlibCompressor @@ -130910,8 +136430,8 @@ compresses data using zlib. glib:set-property="file-info" version="2.26"> Sets @file_info in @compressor. If non-%NULL, and @compressor's + filename="gio/gzlibcompressor.c" + line="316">Sets @file_info in @compressor. If non-%NULL, and @compressor's #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, it will be used to set the file name and modification time in the GZIP header of the compressed data. @@ -130919,15 +136439,15 @@ the GZIP header of the compressed data. Note: it is an error to call this function while a compression is in progress; it may only be called immediately after creation of @compressor, or after resetting it with g_converter_reset(). - + a #GZlibCompressor + filename="gio/gzlibcompressor.c" + line="318">a #GZlibCompressor nullable="1" allow-none="1"> a #GFileInfo + filename="gio/gzlibcompressor.c" + line="319">a #GFileInfo @@ -130948,31 +136468,40 @@ or after resetting it with g_converter_reset(). setter="set_file_info" getter="get_file_info"> If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is + filename="gio/gzlibcompressor.c" + line="256">If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name and modification time from the file info to the GZIP header. + The format of the compressed data. + The level of compression from `0` (no compression) to `9` (most +compression). `-1` for the default level. - + @@ -130983,8 +136512,8 @@ and modification time from the file info to the GZIP header. glib:get-type="g_zlib_compressor_format_get_type" c:type="GZlibCompressorFormat"> Used to select the type of data format to use for #GZlibDecompressor + filename="gio/gioenums.h" + line="915">Used to select the type of data format to use for #GZlibDecompressor and #GZlibCompressor. glib:nick="zlib" glib:name="G_ZLIB_COMPRESSOR_FORMAT_ZLIB"> deflate compression with zlib header + filename="gio/gioenums.h" + line="917">deflate compression with zlib header glib:nick="gzip" glib:name="G_ZLIB_COMPRESSOR_FORMAT_GZIP"> gzip file format + filename="gio/gioenums.h" + line="918">gzip file format glib:nick="raw" glib:name="G_ZLIB_COMPRESSOR_FORMAT_RAW"> deflate compression with no header + filename="gio/gioenums.h" + line="919">deflate compression with no header glib:get-type="g_zlib_decompressor_get_type" glib:type-struct="ZlibDecompressorClass"> #GZlibDecompressor is an implementation of #GConverter that + filename="gio/gzlibdecompressor.c" + line="44">`GZlibDecompressor` is an implementation of [iface@Gio.Converter] that decompresses data compressed with zlib. - + Creates a new #GZlibDecompressor. - + filename="gio/gzlibdecompressor.c" + line="251">Creates a new #GZlibDecompressor. + a new #GZlibDecompressor + filename="gio/gzlibdecompressor.c" + line="257">a new #GZlibDecompressor The format to use for the compressed data + filename="gio/gzlibdecompressor.c" + line="253">The format to use for the compressed data @@ -131054,24 +136583,24 @@ decompresses data compressed with zlib. glib:get-property="file-info" version="2.26"> Retrieves the #GFileInfo constructed from the GZIP header data + filename="gio/gzlibdecompressor.c" + line="273">Retrieves the #GFileInfo constructed from the GZIP header data of compressed data processed by @compressor, or %NULL if @decompressor's #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, or the header data was not fully processed yet, or it not present in the data stream at all. - + a #GFileInfo, or %NULL + filename="gio/gzlibdecompressor.c" + line="283">a #GFileInfo, or %NULL a #GZlibDecompressor + filename="gio/gzlibdecompressor.c" + line="275">a #GZlibDecompressor @@ -131081,25 +136610,29 @@ data stream at all. transfer-ownership="none" getter="get_file_info"> A #GFileInfo containing the information found in the GZIP header + filename="gio/gzlibdecompressor.c" + line="233">A #GFileInfo containing the information found in the GZIP header of the data stream processed, or %NULL if the header was not yet fully processed, is not present at all, or the compressor's #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. + The format of the compressed data. - + @@ -131109,26 +136642,26 @@ fully processed, is not present at all, or the compressor's moved-to="Action.name_is_valid" version="2.38"> Checks if @action_name is valid. + filename="gio/gaction.c" + line="387">Checks if @action_name is valid. @action_name is valid if it consists only of alphanumeric characters, -plus '-' and '.'. The empty string is not a valid action name. +plus `-` and `.`. The empty string is not a valid action name. -It is an error to call this function with a non-utf8 @action_name. -@action_name must not be %NULL. - +It is an error to call this function with a non-UTF-8 @action_name. +@action_name must not be `NULL`. + %TRUE if @action_name is valid + filename="gio/gaction.c" + line="399">`TRUE` if @action_name is valid a potential action name + filename="gio/gaction.c" + line="389">a potential action name @@ -131139,8 +136672,8 @@ It is an error to call this function with a non-utf8 @action_name. version="2.38" throws="1"> Parses a detailed action name into its separate name and target + filename="gio/gaction.c" + line="418">Parses a detailed action name into its separate name and target components. Detailed action names can have three formats. @@ -131158,30 +136691,30 @@ separated by a double colon (`::`). For example: The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: `app.action(42)`. The -target value is parsed using g_variant_parse(). If a tuple-typed +target value is parsed using [func@GLib.Variant.parse]. If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: `app.action((1,2,3))`. A string target can be specified this way as well: `app.action('target')`. For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, `-` and `.`. -If this function returns %TRUE, a non-%NULL value is guaranteed to be returned -in @action_name (if a pointer is passed in). A %NULL value may still be +If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned +in @action_name (if a pointer is passed in). A `NULL` value may still be returned in @target_value, as the @detailed_name may not contain a target. -If returned, the #GVariant in @target_value is guaranteed to not be floating. - +If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating. + %TRUE if successful, else %FALSE with @error set + filename="gio/gaction.c" + line="457">`TRUE` if successful, else `FALSE` with @error set a detailed action name + filename="gio/gaction.c" + line="420">a detailed action name the action name + filename="gio/gaction.c" + line="421">the action name the target value, - or %NULL for no target + filename="gio/gaction.c" + line="422">the target value, + or `NULL` for no target @@ -131215,29 +136748,29 @@ If returned, the #GVariant in @target_value is guaranteed to not be floating. Formats a detailed action name from @action_name and @target_value. + filename="gio/gaction.c" + line="532">Formats a detailed action name from @action_name and @target_value. It is an error to call this function with an invalid action name. -This function is the opposite of g_action_parse_detailed_name(). +This function is the opposite of [func@Gio.Action.parse_detailed_name]. It will produce a string that can be parsed back to the @action_name and @target_value by that function. See that function for the types of strings that will be printed by this function. - + a detailed format string + filename="gio/gaction.c" + line="548">a detailed format string a valid action name + filename="gio/gaction.c" + line="534">a valid action name nullable="1" allow-none="1"> a #GVariant target value, or %NULL + filename="gio/gaction.c" + line="535">a [type@GLib.Variant] target value, or `NULL` @@ -131256,26 +136789,28 @@ this function. moved-to="AppInfo.create_from_commandline" throws="1"> Creates a new #GAppInfo from the given information. + filename="gio/gappinfo.c" + line="120">Creates a new [iface@Gio.AppInfo] from the given information. -Note that for @commandline, the quoting rules of the Exec key of the +Note that for @commandline, the quoting rules of the `Exec` key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the @commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from -being swallowed by Exec key unquoting. See the specification for exact quoting rules. - +being swallowed by `Exec` key unquoting. See +[the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) +for exact quoting rules. + new #GAppInfo for given command. + filename="gio/gappinfo.c" + line="138">new [iface@Gio.AppInfo] for given command. the commandline to use + filename="gio/gappinfo.c" + line="122">the command line to use the application name, or %NULL to use @commandline + filename="gio/gappinfo.c" + line="123">the application name, or `NULL` to use @commandline flags that can specify details of the created #GAppInfo + filename="gio/gappinfo.c" + line="124">flags that can specify details of the created [iface@Gio.AppInfo] @@ -131299,20 +136834,26 @@ being swallowed by Exec key unquoting. See the specification for exact quoting r c:identifier="g_app_info_get_all" moved-to="AppInfo.get_all"> Gets a list of all of the applications currently registered + filename="gio/gappinfo.c" + line="410">Gets a list of all of the applications currently registered on this system. For desktop files, this includes applications that have -`NoDisplay=true` set or are excluded from display by means -of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). -The returned list does not include applications which have -the `Hidden` key set. - +[`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) +set or are excluded from display by means of +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). +See [method@Gio.AppInfo.should_show]. + +The returned list does not include applications which have the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +set. + a newly allocated #GList of references to #GAppInfos. + filename="gio/gappinfo.c" + line="427">a newly allocated + list of references to [iface@Gio.AppInfo]s. @@ -131322,17 +136863,17 @@ the `Hidden` key set. c:identifier="g_app_info_get_all_for_type" moved-to="AppInfo.get_all_for_type"> Gets a list of all #GAppInfos for a given content type, -including the recommended and fallback #GAppInfos. See -g_app_info_get_recommended_for_type() and -g_app_info_get_fallback_for_type(). - + filename="gio/gappinfo.c" + line="482">Gets a list of all [iface@Gio.AppInfo]s for a given content type, +including the recommended and fallback [iface@Gio.AppInfo]s. See +[func@Gio.AppInfo.get_recommended_for_type] and +[func@Gio.AppInfo.get_fallback_for_type]. + #GList of #GAppInfos - for given @content_type or %NULL on error. + filename="gio/gappinfo.c" + line="491">list of + [iface@Gio.AppInfo]s for given @content_type. @@ -131340,38 +136881,39 @@ g_app_info_get_fallback_for_type(). the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="484">the content type to find a [iface@Gio.AppInfo] for + moved-to="AppInfo.get_default_for_type" + glib:async-func="app_info_get_default_for_type_async"> Gets the default #GAppInfo for a given content type. - + filename="gio/gappinfo.c" + line="520">Gets the default [iface@Gio.AppInfo] for a given content type. + #GAppInfo for given @content_type or - %NULL on error. + filename="gio/gappinfo.c" + line="528">[iface@Gio.AppInfo] for given + @content_type or `NULL` on error. the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="522">the content type to find a [iface@Gio.AppInfo] for if %TRUE, the #GAppInfo is expected to - support URIs + filename="gio/gappinfo.c" + line="523">if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs @@ -131379,26 +136921,29 @@ g_app_info_get_fallback_for_type(). + version="2.74" + glib:finish-func="app_info_get_default_for_type_finish" + glib:sync-func="app_info_get_default_for_type"> Asynchronously gets the default #GAppInfo for a given content type. - + filename="gio/gappinfo.c" + line="1002">Asynchronously gets the default [iface@Gio.AppInfo] for a given content +type. + the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="1004">the content type to find a [iface@Gio.AppInfo] for if %TRUE, the #GAppInfo is expected to - support URIs + filename="gio/gappinfo.c" + line="1005">if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gappinfo.c" + line="1007">a [class@Gio.Cancellable] scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="1008">a [type@Gio.AsyncReadyCallback] to call + when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gappinfo.c" + line="1010">data to pass to @callback @@ -131438,50 +136984,52 @@ g_app_info_get_fallback_for_type(). version="2.74" throws="1"> Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_type_async(). + filename="gio/gappinfo.c" + line="1125">Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_type_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. - +If no #[iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. + #GAppInfo for given @content_type or - %NULL on error. + filename="gio/gappinfo.c" + line="1135">[iface@Gio.AppInfo] for given @content_type or + `NULL` on error. a #GAsyncResult + filename="gio/gappinfo.c" + line="1127">the async result + moved-to="AppInfo.get_default_for_uri_scheme" + glib:async-func="app_info_get_default_for_uri_scheme_async"> Gets the default application for handling URIs with -the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". - + filename="gio/gappinfo.c" + line="540">Gets the default application for handling URIs with the given URI scheme. + +A URI scheme is the initial part of the URI, up to but not including the `:`. +For example, `http`, `ftp` or `sip`. + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gappinfo.c" + line="549">[iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. a string containing a URI scheme. + filename="gio/gappinfo.c" + line="542">a string containing a URI scheme. @@ -131489,22 +137037,24 @@ of the URI, up to but not including the ':', e.g. "http", + version="2.74" + glib:finish-func="app_info_get_default_for_uri_scheme_finish" + glib:sync-func="app_info_get_default_for_uri_scheme"> Asynchronously gets the default application for handling URIs with + filename="gio/gappinfo.c" + line="1064">Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". - +of the URI, up to but not including the `:`, e.g. `http`, +`ftp` or `sip`. + a string containing a URI scheme. + filename="gio/gappinfo.c" + line="1066">a string containing a URI scheme. optional #GCancellable object, %NULL to ignore + filename="gio/gappinfo.c" + line="1067">a [class@Gio.Cancellable] a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="1068">a [type@Gio.AsyncReadyCallback] to call + when the request is done data to pass to @callback + filename="gio/gappinfo.c" + line="1070">data to pass to @callback @@ -131544,24 +137095,25 @@ of the URI, up to but not including the ':', e.g. "http", version="2.74" throws="1"> Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_uri_scheme_async(). + filename="gio/gappinfo.c" + line="1098">Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_uri_scheme_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. - +If no [iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. + #GAppInfo for given @uri_scheme or - %NULL on error. + filename="gio/gappinfo.c" + line="1108">[iface@Gio.AppInfo] for given @uri_scheme or + `NULL` on error. a #GAsyncResult + filename="gio/gappinfo.c" + line="1100">the async result @@ -131571,16 +137123,16 @@ If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. Gets a list of fallback #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type -by MIME type subclassing and not directly. - + filename="gio/gappinfo.c" + line="461">Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. +those applications which claim to support the given content type by MIME +type subclassing and not directly. + #GList of #GAppInfos - for given @content_type or %NULL on error. + filename="gio/gappinfo.c" + line="469">list of [iface@Gio.AppInfo]s + for given @content_type or `NULL` on error. @@ -131588,8 +137140,8 @@ by MIME type subclassing and not directly. the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="463">the content type to find a [iface@Gio.AppInfo] for @@ -131599,19 +137151,20 @@ by MIME type subclassing and not directly. moved-to="AppInfo.get_recommended_for_type" version="2.28"> Gets a list of recommended #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type exactly, -and not by MIME type subclassing. + filename="gio/gappinfo.c" + line="436">Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, +i.e. those applications which claim to support the given content type +exactly, and not by MIME type subclassing. + Note that the first application of the list is the last used one, i.e. -the last one for which g_app_info_set_as_last_used_for_type() has been -called. - +the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has +been called. + #GList of #GAppInfos - for given @content_type or %NULL on error. + filename="gio/gappinfo.c" + line="448">list of + [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. @@ -131619,8 +137172,8 @@ called. the content type to find a #GAppInfo for + filename="gio/gappinfo.c" + line="438">the content type to find a [iface@Gio.AppInfo] for @@ -131628,29 +137181,29 @@ called. + throws="1" + glib:async-func="app_info_launch_default_for_uri_async"> Utility function that launches the default application -registered to handle the specified uri. Synchronous I/O -is done on the uri to detect the type of the file if -required. + filename="gio/gappinfo.c" + line="1152">Utility function that launches the default application registered to handle +the specified uri. Synchronous I/O is done on the uri to detect the type of +the file if required. -The D-Bus–activated applications don't have to be started if your application +The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use -g_app_info_launch_default_for_uri_async() instead. - +[func@Gio.AppInfo.launch_default_for_uri_async] instead. + %TRUE on success, %FALSE on error. + filename="gio/gappinfo.c" + line="1165">`TRUE` on success, `FALSE` on error. the uri to show + filename="gio/gappinfo.c" + line="1154">the uri to show nullable="1" allow-none="1"> an optional #GAppLaunchContext + filename="gio/gappinfo.c" + line="1155">optional launch context @@ -131667,28 +137220,29 @@ g_app_info_launch_default_for_uri_async() instead. + version="2.50" + glib:finish-func="app_info_launch_default_for_uri_finish" + glib:sync-func="app_info_launch_default_for_uri"> Async version of g_app_info_launch_default_for_uri(). + filename="gio/gappinfo.c" + line="1417">Async version of [func@Gio.AppInfo.launch_default_for_uri]. -This version is useful if you are interested in receiving -error information in the case where the application is -sandboxed and the portal may present an application chooser -dialog to the user. +This version is useful if you are interested in receiving error information +in the case where the application is sandboxed and the portal may present an +application chooser dialog to the user. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation. - + the uri to show + filename="gio/gappinfo.c" + line="1419">the uri to show nullable="1" allow-none="1"> an optional #GAppLaunchContext + filename="gio/gappinfo.c" + line="1420">optional launch context nullable="1" allow-none="1"> a #GCancellable + filename="gio/gappinfo.c" + line="1421">a [class@Gio.Cancellable] scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gappinfo.c" + line="1422">a [type@Gio.AsyncReadyCallback] to call + when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gappinfo.c" + line="1424">data to pass to @callback @@ -131737,20 +137292,20 @@ in receiving error information from their activation. version="2.50" throws="1"> Finishes an asynchronous launch-default-for-uri operation. - + filename="gio/gappinfo.c" + line="1479">Finishes an asynchronous launch-default-for-uri operation. + %TRUE if the launch was successful, %FALSE if @error is set + filename="gio/gappinfo.c" + line="1485">`TRUE` if the launch was successful, `FALSE` if @error is set a #GAsyncResult + filename="gio/gappinfo.c" + line="1481">the async result @@ -131760,21 +137315,21 @@ in receiving error information from their activation. moved-to="AppInfo.reset_type_associations" version="2.20"> Removes all changes to the type associations done by -g_app_info_set_as_default_for_type(), -g_app_info_set_as_default_for_extension(), -g_app_info_add_supports_type() or -g_app_info_remove_supports_type(). - + filename="gio/gappinfo.c" + line="502">Removes all changes to the type associations done by +[method@Gio.AppInfo.set_as_default_for_type], +[method@Gio.AppInfo.set_as_default_for_extension], +[method@Gio.AppInfo.add_supports_type] or +[method@Gio.AppInfo.remove_supports_type]. + a content type + filename="gio/gappinfo.c" + line="504">a content type @@ -131786,8 +137341,8 @@ g_app_info_remove_supports_type(). deprecated="1" deprecated-version="2.54"> Helper function for constructing #GAsyncInitable object. This is + filename="gio/gasyncinitable.c" + line="354">Helper function for constructing #GAsyncInitable object. This is similar to g_object_newv() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can @@ -131795,33 +137350,33 @@ then call g_async_initable_new_finish() to get the new object and check for any errors. Use g_object_new_with_properties() and g_async_initable_init_async() instead. See #GParameter for more information. - + a #GType supporting #GAsyncInitable. + filename="gio/gasyncinitable.c" + line="356">a #GType supporting #GAsyncInitable. the number of parameters in @parameters + filename="gio/gasyncinitable.c" + line="357">the number of parameters in @parameters the parameters to use to construct the object + filename="gio/gasyncinitable.c" + line="358">the parameters to use to construct the object the [I/O priority][io-priority] of the operation + filename="gio/gasyncinitable.c" + line="359">the [I/O priority](iface.AsyncResult.html#io-priority) of the operation optional #GCancellable object, %NULL to ignore. + filename="gio/gasyncinitable.c" + line="360">optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is + filename="gio/gasyncinitable.c" + line="361">a #GAsyncReadyCallback to call when the initialization is finished @@ -131850,31 +137405,35 @@ g_async_initable_init_async() instead. See #GParameter for more information. the data to pass to callback function + filename="gio/gasyncinitable.c" + line="363">the data to pass to callback function - + Asynchronously connects to the message bus specified by @bus_type. + filename="gio/gdbusconnection.c" + line="8116">Asynchronously connects to the message bus specified by @bus_type. When the operation is finished, @callback will be invoked. You can then call g_bus_get_finish() to get the result of the operation. This is an asynchronous failable function. See g_bus_get_sync() for the synchronous version. - + a #GBusType + filename="gio/gdbusconnection.c" + line="8118">a #GBusType nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="8119">a #GCancellable or %NULL scope="async" closure="3"> a #GAsyncReadyCallback to call when the request is satisfied + filename="gio/gdbusconnection.c" + line="8120">a #GAsyncReadyCallback to call when the request is satisfied nullable="1" allow-none="1"> the data to pass to @callback + filename="gio/gdbusconnection.c" + line="8121">the data to pass to @callback @@ -131913,8 +137472,8 @@ the synchronous version. version="2.26" throws="1"> Finishes an operation started with g_bus_get(). + filename="gio/gdbusconnection.c" + line="8165">Finishes an operation started with g_bus_get(). The returned object is a singleton, that is, shared with other callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the @@ -131926,19 +137485,19 @@ G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned #GDBusConnection object will (usually) have the #GDBusConnection:exit-on-close property set to %TRUE. - + a #GDBusConnection or %NULL if @error is set. + filename="gio/gdbusconnection.c" + line="8184">a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GAsyncResult obtained from the #GAsyncReadyCallback passed + filename="gio/gdbusconnection.c" + line="8167">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get() @@ -131947,10 +137506,11 @@ the #GDBusConnection:exit-on-close property set to %TRUE. + throws="1" + glib:async-func="bus_get"> Synchronously connects to the message bus specified by @bus_type. + filename="gio/gdbusconnection.c" + line="8038">Synchronously connects to the message bus specified by @bus_type. Note that the returned object may shared with other callers, e.g. if two separate parts of a process calls this function with the same @bus_type, they will share the same object. @@ -131968,19 +137528,19 @@ G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned #GDBusConnection object will (usually) have the #GDBusConnection:exit-on-close property set to %TRUE. - + a #GDBusConnection or %NULL if @error is set. + filename="gio/gdbusconnection.c" + line="8063">a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). a #GBusType + filename="gio/gdbusconnection.c" + line="8040">a #GBusType nullable="1" allow-none="1"> a #GCancellable or %NULL + filename="gio/gdbusconnection.c" + line="8041">a #GCancellable or %NULL @@ -131997,14 +137557,13 @@ the #GDBusConnection:exit-on-close property set to %TRUE. + version="2.26"> Starts acquiring @name on the bus specified by @bus_type and calls + filename="gio/gdbusnameowning.c" + line="567">Starts acquiring @name on the bus specified by @bus_type and calls @name_acquired_handler and @name_lost_handler when the name is -acquired respectively lost. Callbacks will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +acquired respectively lost. Callbacks will be invoked in the thread-default +main context (see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this function from. You are guaranteed that one of the @name_acquired_handler and @name_lost_handler @@ -132047,52 +137606,56 @@ in @bus_acquired_handler since you are guaranteed that this will run before @name is requested from the bus. This behavior makes it very simple to write applications that wants -to [own names][gdbus-owning-names] and export objects. +to [own names](dbus-name-owning.html#d-bus-name-owning) and export objects. Simply register objects to be exported in @bus_acquired_handler and unregister the objects (if any) in @name_lost_handler. - + an identifier (never 0) that can be used with + filename="gio/gdbusnameowning.c" + line="631">an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name. the type of bus to own a name on + filename="gio/gdbusnameowning.c" + line="569">the type of bus to own a name on the well-known name to own + filename="gio/gdbusnameowning.c" + line="570">the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration + filename="gio/gdbusnameowning.c" + line="571">a set of flags from the #GBusNameOwnerFlags enumeration + allow-none="1" + scope="notified"> handler to invoke when connected to the bus of type @bus_type or %NULL + filename="gio/gdbusnameowning.c" + line="572">handler to invoke when + connected to the bus of type @bus_type or %NULL + allow-none="1" + scope="notified"> handler to invoke when @name is acquired or %NULL + filename="gio/gdbusnameowning.c" + line="574">handler to invoke when + @name is acquired or %NULL @@ -132104,8 +137667,9 @@ unregister the objects (if any) in @name_lost_handler. closure="6" destroy="7"> handler to invoke when @name is lost or %NULL + filename="gio/gdbusnameowning.c" + line="576">handler to invoke when @name + is lost or %NULL nullable="1" allow-none="1"> user data to pass to handlers + filename="gio/gdbusnameowning.c" + line="578">user data to pass to handlers allow-none="1" scope="async"> function for freeing @user_data or %NULL + filename="gio/gdbusnameowning.c" + line="579">function for freeing @user_data or %NULL @@ -132132,46 +137696,47 @@ unregister the objects (if any) in @name_lost_handler. + version="2.26"> Like g_bus_own_name() but takes a #GDBusConnection instead of a + filename="gio/gdbusnameowning.c" + line="503">Like g_bus_own_name() but takes a #GDBusConnection instead of a #GBusType. - + an identifier (never 0) that can be used with + filename="gio/gdbusnameowning.c" + line="518">an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name a #GDBusConnection + filename="gio/gdbusnameowning.c" + line="505">a #GDBusConnection the well-known name to own + filename="gio/gdbusnameowning.c" + line="506">the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration + filename="gio/gdbusnameowning.c" + line="507">a set of flags from the #GBusNameOwnerFlags enumeration + allow-none="1" + scope="notified"> handler to invoke when @name is acquired or %NULL + filename="gio/gdbusnameowning.c" + line="508">handler to invoke when + @name is acquired or %NULL @@ -132183,8 +137748,9 @@ unregister the objects (if any) in @name_lost_handler. closure="5" destroy="6"> handler to invoke when @name is lost or %NULL + filename="gio/gdbusnameowning.c" + line="510">handler to invoke when @name + is lost or %NULL nullable="1" allow-none="1"> user data to pass to handlers + filename="gio/gdbusnameowning.c" + line="512">user data to pass to handlers allow-none="1" scope="async"> function for freeing @user_data or %NULL + filename="gio/gdbusnameowning.c" + line="513">function for freeing @user_data or %NULL @@ -132213,34 +137779,34 @@ unregister the objects (if any) in @name_lost_handler. shadows="bus_own_name_on_connection" version="2.26"> Version of g_bus_own_name_on_connection() using closures instead of + filename="gio/gdbusnameowning.c" + line="841">Version of g_bus_own_name_on_connection() using closures instead of callbacks for easier binding in other languages. - + an identifier (never 0) that can be used with + filename="gio/gdbusnameowning.c" + line="854">an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name. a #GDBusConnection + filename="gio/gdbusnameowning.c" + line="843">a #GDBusConnection the well-known name to own + filename="gio/gdbusnameowning.c" + line="844">the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration + filename="gio/gdbusnameowning.c" + line="845">a set of flags from the #GBusNameOwnerFlags enumeration nullable="1" allow-none="1"> #GClosure to invoke when @name is + filename="gio/gdbusnameowning.c" + line="846">#GClosure to invoke when @name is acquired or %NULL @@ -132258,8 +137824,8 @@ callbacks for easier binding in other languages. nullable="1" allow-none="1"> #GClosure to invoke when @name is lost + filename="gio/gdbusnameowning.c" + line="848">#GClosure to invoke when @name is lost or %NULL @@ -132270,34 +137836,34 @@ callbacks for easier binding in other languages. shadows="bus_own_name" version="2.26"> Version of g_bus_own_name() using closures instead of callbacks for + filename="gio/gdbusnameowning.c" + line="801">Version of g_bus_own_name() using closures instead of callbacks for easier binding in other languages. - + an identifier (never 0) that can be used with + filename="gio/gdbusnameowning.c" + line="816">an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name. the type of bus to own a name on + filename="gio/gdbusnameowning.c" + line="803">the type of bus to own a name on the well-known name to own + filename="gio/gdbusnameowning.c" + line="804">the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration + filename="gio/gdbusnameowning.c" + line="805">a set of flags from the #GBusNameOwnerFlags enumeration nullable="1" allow-none="1"> #GClosure to invoke when connected to + filename="gio/gdbusnameowning.c" + line="806">#GClosure to invoke when connected to the bus of type @bus_type or %NULL @@ -132315,8 +137881,8 @@ easier binding in other languages. nullable="1" allow-none="1"> #GClosure to invoke when @name is + filename="gio/gdbusnameowning.c" + line="808">#GClosure to invoke when @name is acquired or %NULL @@ -132325,8 +137891,8 @@ easier binding in other languages. nullable="1" allow-none="1"> #GClosure to invoke when @name is lost or + filename="gio/gdbusnameowning.c" + line="810">#GClosure to invoke when @name is lost or %NULL @@ -132336,8 +137902,8 @@ easier binding in other languages. c:identifier="g_bus_unown_name" version="2.26"> Stops owning a name. + filename="gio/gdbusnameowning.c" + line="877">Stops owning a name. Note that there may still be D-Bus traffic to process (relating to owning and unowning the name) in the current thread-default #GMainContext after @@ -132345,15 +137911,15 @@ this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_bus_own_name() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. - + an identifier obtained from g_bus_own_name() + filename="gio/gdbusnameowning.c" + line="879">an identifier obtained from g_bus_own_name() @@ -132362,8 +137928,8 @@ after it’s stopped being iterated. c:identifier="g_bus_unwatch_name" version="2.26"> Stops watching a name. + filename="gio/gdbusnamewatching.c" + line="872">Stops watching a name. Note that there may still be D-Bus traffic to process (relating to watching and unwatching the name) in the current thread-default #GMainContext after @@ -132371,15 +137937,15 @@ this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_bus_watch_name() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. - + An identifier obtained from g_bus_watch_name() + filename="gio/gdbusnamewatching.c" + line="874">An identifier obtained from g_bus_watch_name() @@ -132387,15 +137953,14 @@ after it’s stopped being iterated. + version="2.26"> Starts watching @name on the bus specified by @bus_type and calls + filename="gio/gdbusnamewatching.c" + line="561">Starts watching @name on the bus specified by @bus_type and calls @name_appeared_handler and @name_vanished_handler when the name is known to have an owner respectively known to lose its -owner. Callbacks will be invoked in the -[thread-default main context][g-main-context-push-thread-default] +owner. Callbacks will be invoked in the thread-default main context +(see [method@GLib.MainContext.push_thread_default]) of the thread you are calling this function from. You are guaranteed that one of the handlers will be invoked after @@ -132416,44 +137981,46 @@ guaranteed that the next time one of the handlers is invoked, it will be @name_vanished_handler. The reverse is also true. This behavior makes it very simple to write applications that want -to take action when a certain [name exists][gdbus-watching-names]. +to take action when a certain [name exists](dbus-name-watching.html#d-bus-name-watching). Basically, the application should create object proxies in @name_appeared_handler and destroy them again (if any) in @name_vanished_handler. - + An identifier (never 0) that can be used with + filename="gio/gdbusnamewatching.c" + line="603">An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. The type of bus to watch a name on. + filename="gio/gdbusnamewatching.c" + line="563">The type of bus to watch a name on. The name (well-known or unique) to watch. + filename="gio/gdbusnamewatching.c" + line="564">The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. + filename="gio/gdbusnamewatching.c" + line="565">Flags from the #GBusNameWatcherFlags enumeration. + allow-none="1" + scope="notified"> Handler to invoke when @name is known to exist or %NULL. + filename="gio/gdbusnamewatching.c" + line="566">Handler to invoke when + @name is known to exist or %NULL. @@ -132465,8 +138032,9 @@ g_bus_unwatch_name() to stop watching the name. closure="5" destroy="6"> Handler to invoke when @name is known to not exist or %NULL. + filename="gio/gdbusnamewatching.c" + line="568">Handler to invoke when + @name is known to not exist or %NULL. @@ -132475,8 +138043,8 @@ g_bus_unwatch_name() to stop watching the name. nullable="1" allow-none="1"> User data to pass to handlers. + filename="gio/gdbusnamewatching.c" + line="570">User data to pass to handlers. allow-none="1" scope="async"> Function for freeing @user_data or %NULL. + filename="gio/gdbusnamewatching.c" + line="571">Function for freeing @user_data or %NULL. @@ -132494,46 +138062,47 @@ g_bus_unwatch_name() to stop watching the name. + version="2.26"> Like g_bus_watch_name() but takes a #GDBusConnection instead of a + filename="gio/gdbusnamewatching.c" + line="652">Like g_bus_watch_name() but takes a #GDBusConnection instead of a #GBusType. - + An identifier (never 0) that can be used with + filename="gio/gdbusnamewatching.c" + line="667">An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. A #GDBusConnection. + filename="gio/gdbusnamewatching.c" + line="654">A #GDBusConnection. The name (well-known or unique) to watch. + filename="gio/gdbusnamewatching.c" + line="655">The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. + filename="gio/gdbusnamewatching.c" + line="656">Flags from the #GBusNameWatcherFlags enumeration. + allow-none="1" + scope="notified"> Handler to invoke when @name is known to exist or %NULL. + filename="gio/gdbusnamewatching.c" + line="657">Handler to invoke when + @name is known to exist or %NULL. @@ -132545,8 +138114,9 @@ g_bus_unwatch_name() to stop watching the name. closure="5" destroy="6"> Handler to invoke when @name is known to not exist or %NULL. + filename="gio/gdbusnamewatching.c" + line="659">Handler to invoke when + @name is known to not exist or %NULL. @@ -132555,8 +138125,8 @@ g_bus_unwatch_name() to stop watching the name. nullable="1" allow-none="1"> User data to pass to handlers. + filename="gio/gdbusnamewatching.c" + line="661">User data to pass to handlers. allow-none="1" scope="async"> Function for freeing @user_data or %NULL. + filename="gio/gdbusnamewatching.c" + line="662">Function for freeing @user_data or %NULL. @@ -132576,34 +138146,34 @@ g_bus_unwatch_name() to stop watching the name. shadows="bus_watch_name_on_connection" version="2.26"> Version of g_bus_watch_name_on_connection() using closures instead of callbacks for + filename="gio/gdbusnamewatching.c" + line="838">Version of g_bus_watch_name_on_connection() using closures instead of callbacks for easier binding in other languages. - + An identifier (never 0) that can be used with + filename="gio/gdbusnamewatching.c" + line="851">An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. A #GDBusConnection. + filename="gio/gdbusnamewatching.c" + line="840">A #GDBusConnection. The name (well-known or unique) to watch. + filename="gio/gdbusnamewatching.c" + line="841">The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. + filename="gio/gdbusnamewatching.c" + line="842">Flags from the #GBusNameWatcherFlags enumeration. nullable="1" allow-none="1"> #GClosure to invoke when @name is known + filename="gio/gdbusnamewatching.c" + line="843">#GClosure to invoke when @name is known to exist or %NULL. @@ -132621,8 +138191,8 @@ to exist or %NULL. nullable="1" allow-none="1"> #GClosure to invoke when @name is known + filename="gio/gdbusnamewatching.c" + line="845">#GClosure to invoke when @name is known to not exist or %NULL. @@ -132633,34 +138203,34 @@ to not exist or %NULL. shadows="bus_watch_name" version="2.26"> Version of g_bus_watch_name() using closures instead of callbacks for + filename="gio/gdbusnamewatching.c" + line="804">Version of g_bus_watch_name() using closures instead of callbacks for easier binding in other languages. - + An identifier (never 0) that can be used with + filename="gio/gdbusnamewatching.c" + line="817">An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. The type of bus to watch a name on. + filename="gio/gdbusnamewatching.c" + line="806">The type of bus to watch a name on. The name (well-known or unique) to watch. + filename="gio/gdbusnamewatching.c" + line="807">The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. + filename="gio/gdbusnamewatching.c" + line="808">Flags from the #GBusNameWatcherFlags enumeration. nullable="1" allow-none="1"> #GClosure to invoke when @name is known + filename="gio/gdbusnamewatching.c" + line="809">#GClosure to invoke when @name is known to exist or %NULL. @@ -132678,59 +138248,100 @@ to exist or %NULL. nullable="1" allow-none="1"> #GClosure to invoke when @name is known + filename="gio/gdbusnamewatching.c" + line="811">#GClosure to invoke when @name is known to not exist or %NULL. + + If @subscription_id_pointer points to a nonzero subscription ID, +unsubscribe from that D-Bus signal subscription as if via +[method@Gio.DBusConnection.signal_unsubscribe]. + +Also set the value pointed to by @subscription_id_pointer to zero, +which signifies it’s no longer a valid subscription ID. + +This convenience function for C code helps to ensure that each signal +subscription is unsubscribed exactly once, similar to +[func@GObject.clear_object] and [func@GObject.clear_signal_handler]. + + + + + + + A pointer to either a + subscription ID obtained from [method@Gio.DBusConnection.signal_subscribe], + or zero. + + + + The connection from which the subscription ID was obtained. + This pointer may be `NULL` or invalid, if the subscription ID is zero. + + + + Checks if a content type can be executable. Note that for instance + filename="gio/gcontenttype.c" + line="261">Checks if a content type can be executable. Note that for instance things like text files can be executables (i.e. scripts and batch files). - + %TRUE if the file type corresponds to a type that + filename="gio/gcontenttype.c" + line="268">%TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise. a content type string + filename="gio/gcontenttype.c" + line="263">a content type string Compares two content types for equality. - + filename="gio/gcontenttype.c" + line="86">Compares two content types for equality. + %TRUE if the two strings are identical or equivalent, + filename="gio/gcontenttype.c" + line="93">%TRUE if the two strings are identical or equivalent, %FALSE otherwise. a content type string + filename="gio/gcontenttype.c" + line="88">a content type string a content type string + filename="gio/gcontenttype.c" + line="89">a content type string @@ -132739,21 +138350,21 @@ things like text files can be executables (i.e. scripts and batch files). c:identifier="g_content_type_from_mime_type" version="2.18"> Tries to find a content type based on the mime type name. - + filename="gio/gcontenttype.c" + line="279">Tries to find a content type based on the mime type name. + Newly allocated string with content type or + filename="gio/gcontenttype.c" + line="285">Newly allocated string with content type or %NULL. Free with g_free() a mime type string + filename="gio/gcontenttype.c" + line="281">a mime type string @@ -132761,21 +138372,21 @@ things like text files can be executables (i.e. scripts and batch files). Gets the human readable description of the content type. - + filename="gio/gcontenttype.c" + line="168">Gets the human readable description of the content type. + a short description of the content type @type. Free the + filename="gio/gcontenttype.c" + line="174">a short description of the content type @type. Free the returned string with g_free() a content type string + filename="gio/gcontenttype.c" + line="170">a content type string @@ -132784,25 +138395,25 @@ things like text files can be executables (i.e. scripts and batch files). c:identifier="g_content_type_get_generic_icon_name" version="2.34"> Gets the generic icon name for a content type. + filename="gio/gcontenttype.c" + line="238">Gets the generic icon name for a content type. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on the generic icon name. - + the registered generic icon name for the given @type, + filename="gio/gcontenttype.c" + line="248">the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free() a content type string + filename="gio/gcontenttype.c" + line="240">a content type string @@ -132810,21 +138421,21 @@ specification for more on the generic icon name. Gets the icon for a content type. - + filename="gio/gcontenttype.c" + line="202">Gets the icon for a content type. + #GIcon corresponding to the content type. Free the returned + filename="gio/gcontenttype.c" + line="208">#GIcon corresponding to the content type. Free the returned object with g_object_unref() a content type string + filename="gio/gcontenttype.c" + line="204">a content type string @@ -132833,14 +138444,14 @@ specification for more on the generic icon name. c:identifier="g_content_type_get_mime_dirs" version="2.60"> Get the list of directories which MIME data is loaded from. See + filename="gio/gcontenttype.c" + line="69">Get the list of directories which MIME data is loaded from. See g_content_type_set_mime_dirs() for details. - + %NULL-terminated list of + filename="gio/gcontenttype.c" + line="75">%NULL-terminated list of directories to load MIME data from, including any `mime/` subdirectory, and with the first directory to try listed first @@ -132851,21 +138462,21 @@ g_content_type_set_mime_dirs() for details. Gets the mime type for the content type, if one is registered. - + filename="gio/gcontenttype.c" + line="185">Gets the mime type for the content type, if one is registered. + the registered mime type for the + filename="gio/gcontenttype.c" + line="191">the registered mime type for the given @type, or %NULL if unknown; free with g_free(). a content type string + filename="gio/gcontenttype.c" + line="187">a content type string @@ -132874,37 +138485,37 @@ g_content_type_set_mime_dirs() for details. c:identifier="g_content_type_get_symbolic_icon" version="2.34"> Gets the symbolic icon for a content type. - + filename="gio/gcontenttype.c" + line="219">Gets the symbolic icon for a content type. + symbolic #GIcon corresponding to the content type. + filename="gio/gcontenttype.c" + line="225">symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref() a content type string + filename="gio/gcontenttype.c" + line="221">a content type string Guesses the content type based on example data. If the function is + filename="gio/gcontenttype.c" + line="298">Guesses the content type based on example data. If the function is uncertain, @result_uncertain will be set to %TRUE. Either @filename or @data may be %NULL, in which case the guess will be based solely on the other argument. - + a string indicating a guessed content type for the + filename="gio/gcontenttype.c" + line="311">a string indicating a guessed content type for the given data. Free with g_free() @@ -132914,8 +138525,8 @@ on the other argument. nullable="1" allow-none="1"> a path, or %NULL + filename="gio/gcontenttype.c" + line="300">a path, or %NULL nullable="1" allow-none="1"> a stream of data, or %NULL + filename="gio/gcontenttype.c" + line="301">a stream of data, or %NULL the size of @data + filename="gio/gcontenttype.c" + line="302">the size of @data optional="1" allow-none="1"> return location for the certainty + filename="gio/gcontenttype.c" + line="303">return location for the certainty of the result, or %NULL @@ -132953,8 +138564,8 @@ on the other argument. c:identifier="g_content_type_guess_for_tree" version="2.18"> Tries to guess the type of the tree with root @root, by + filename="gio/gcontenttype.c" + line="339">Tries to guess the type of the tree with root @root, by looking at the files it contains. The result is an array of content types, with the best guess coming first. @@ -132966,11 +138577,11 @@ specification for more on x-content types. This function is useful in the implementation of g_mount_guess_content_type(). - + an %NULL-terminated + filename="gio/gcontenttype.c" + line="356">an %NULL-terminated array of zero or more content types. Free with g_strfreev() @@ -132979,35 +138590,35 @@ g_mount_guess_content_type(). the root of the tree to guess a type for + filename="gio/gcontenttype.c" + line="341">the root of the tree to guess a type for Determines if @type is a subset of @supertype. - + filename="gio/gcontenttype.c" + line="106">Determines if @type is a subset of @supertype. + %TRUE if @type is a kind of @supertype, + filename="gio/gcontenttype.c" + line="113">%TRUE if @type is a kind of @supertype, %FALSE otherwise. a content type string + filename="gio/gcontenttype.c" + line="108">a content type string a content type string + filename="gio/gcontenttype.c" + line="109">a content type string @@ -133016,28 +138627,28 @@ g_mount_guess_content_type(). c:identifier="g_content_type_is_mime_type" version="2.52"> Determines if @type is a subset of @mime_type. + filename="gio/gcontenttype.c" + line="126">Determines if @type is a subset of @mime_type. Convenience wrapper around g_content_type_is_a(). - + %TRUE if @type is a kind of @mime_type, + filename="gio/gcontenttype.c" + line="134">%TRUE if @type is a kind of @mime_type, %FALSE otherwise. a content type string + filename="gio/gcontenttype.c" + line="128">a content type string a mime type string + filename="gio/gcontenttype.c" + line="129">a mime type string @@ -133045,23 +138656,23 @@ Convenience wrapper around g_content_type_is_a(). Checks if the content type is the generic "unknown" type. + filename="gio/gcontenttype.c" + line="149">Checks if the content type is the generic "unknown" type. On UNIX this is the "application/octet-stream" mimetype, while on win32 it is "*" and on OSX it is a dynamic type or octet-stream. - + %TRUE if the type is the unknown type. + filename="gio/gcontenttype.c" + line="158">%TRUE if the type is the unknown type. a content type string + filename="gio/gcontenttype.c" + line="151">a content type string @@ -133070,8 +138681,8 @@ or octet-stream. c:identifier="g_content_type_set_mime_dirs" version="2.60"> Set the list of directories used by GIO to load the MIME database. + filename="gio/gcontenttype.c" + line="31">Set the list of directories used by GIO to load the MIME database. If @dirs is %NULL, the directories used are the default: - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` @@ -133094,7 +138705,7 @@ with @dirs set to %NULL before calling g_test_init(), for instance: return g_test_run (); ]| - + @@ -133104,8 +138715,8 @@ with @dirs set to %NULL before calling g_test_init(), for instance: nullable="1" allow-none="1"> %NULL-terminated list of + filename="gio/gcontenttype.c" + line="33">%NULL-terminated list of directories to load MIME data from, including any `mime/` subdirectory, and with the first directory to try listed first @@ -133117,15 +138728,15 @@ with @dirs set to %NULL before calling g_test_init(), for instance: Gets a list of strings containing all the registered content types + filename="gio/gcontenttype.c" + line="323">Gets a list of strings containing all the registered content types known to the system. The list and its data should be freed using `g_list_free_full (list, g_free)`. - + list of the registered + filename="gio/gcontenttype.c" + line="330">list of the registered content types @@ -133136,27 +138747,27 @@ known to the system. The list and its data should be freed using c:identifier="g_dbus_address_escape_value" version="2.36"> Escape @string so it can appear in a D-Bus address as the value + filename="gio/gdbusaddress.c" + line="1432">Escape @string so it can appear in a D-Bus address as the value part of a key-value pair. For instance, if @string is `/run/bus-for-:0`, this function would return `/run/bus-for-%3A0`, which could be used in a D-Bus address like `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`. - + a copy of @string with all + filename="gio/gdbusaddress.c" + line="1445">a copy of @string with all non-optionally-escaped bytes escaped an unescaped string to be included in a D-Bus address + filename="gio/gdbusaddress.c" + line="1434">an unescaped string to be included in a D-Bus address as the value in a key-value pair @@ -133167,26 +138778,26 @@ which could be used in a D-Bus address like version="2.26" throws="1"> Synchronously looks up the D-Bus address for the well-known message + filename="gio/gdbusaddress.c" + line="1269">Synchronously looks up the D-Bus address for the well-known message bus instance specified by @bus_type. This may involve using various platform specific mechanisms. The returned address will be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - + a valid D-Bus address string for @bus_type or + filename="gio/gdbusaddress.c" + line="1282">a valid D-Bus address string for @bus_type or %NULL if @error is set a #GBusType + filename="gio/gdbusaddress.c" + line="1271">a #GBusType a #GCancellable or %NULL + filename="gio/gdbusaddress.c" + line="1272">a #GCancellable or %NULL + version="2.26" + glib:finish-func="dbus_address_get_stream_finish" + glib:sync-func="dbus_address_get_stream_sync"> Asynchronously connects to an endpoint specified by @address and + filename="gio/gdbusaddress.c" + line="865">Asynchronously connects to an endpoint specified by @address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. @address must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). @@ -133216,15 +138829,15 @@ the operation. This is an asynchronous failable function. See g_dbus_address_get_stream_sync() for the synchronous version. - + A valid D-Bus address. + filename="gio/gdbusaddress.c" + line="867">A valid D-Bus address. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusaddress.c" + line="868">A #GCancellable or %NULL. scope="async" closure="3"> A #GAsyncReadyCallback to call when the request is satisfied. + filename="gio/gdbusaddress.c" + line="869">A #GAsyncReadyCallback to call when the request is satisfied. nullable="1" allow-none="1"> Data to pass to @callback. + filename="gio/gdbusaddress.c" + line="870">Data to pass to @callback. @@ -133263,23 +138876,23 @@ g_dbus_address_get_stream_sync() for the synchronous version. version="2.26" throws="1"> Finishes an operation started with g_dbus_address_get_stream(). + filename="gio/gdbusaddress.c" + line="907">Finishes an operation started with g_dbus_address_get_stream(). A server is not required to set a GUID, so @out_guid may be set to %NULL even on success. - + A #GIOStream or %NULL if @error is set. + filename="gio/gdbusaddress.c" + line="918">A #GIOStream or %NULL if @error is set. A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). + filename="gio/gdbusaddress.c" + line="909">A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). optional="1" allow-none="1"> %NULL or return location to store the GUID extracted from @address, if any. + filename="gio/gdbusaddress.c" + line="910">%NULL or return location to store the GUID extracted from @address, if any. @@ -133299,10 +138912,11 @@ even on success. + throws="1" + glib:async-func="dbus_address_get_stream"> Synchronously connects to an endpoint specified by @address and + filename="gio/gdbusaddress.c" + line="947">Synchronously connects to an endpoint specified by @address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. @address must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). @@ -133312,18 +138926,18 @@ even on success. This is a synchronous failable function. See g_dbus_address_get_stream() for the asynchronous version. - + A #GIOStream or %NULL if @error is set. + filename="gio/gdbusaddress.c" + line="965">A #GIOStream or %NULL if @error is set. A valid D-Bus address. + filename="gio/gdbusaddress.c" + line="949">A valid D-Bus address. optional="1" allow-none="1"> %NULL or return location to store the GUID extracted from @address, if any. + filename="gio/gdbusaddress.c" + line="950">%NULL or return location to store the GUID extracted from @address, if any. nullable="1" allow-none="1"> A #GCancellable or %NULL. + filename="gio/gdbusaddress.c" + line="951">A #GCancellable or %NULL. @@ -133354,15 +138968,15 @@ g_dbus_address_get_stream() for the asynchronous version. moved-to="DBusAnnotationInfo.lookup" version="2.26"> Looks up the value of an annotation. + filename="gio/gdbusintrospection.c" + line="1829">Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. - + The value or %NULL if not found. Do not free, it is owned by @annotations. + filename="gio/gdbusintrospection.c" + line="1838">The value or %NULL if not found. Do not free, it is owned by @annotations. @@ -133371,16 +138985,16 @@ The cost of this function is O(n) in number of annotations. nullable="1" allow-none="1"> A %NULL-terminated array of annotations or %NULL. + filename="gio/gdbusintrospection.c" + line="1831">A %NULL-terminated array of annotations or %NULL. The name of the annotation to look up. + filename="gio/gdbusintrospection.c" + line="1832">The name of the annotation to look up. @@ -133390,8 +139004,8 @@ The cost of this function is O(n) in number of annotations. moved-to="DBusError.encode_gerror" version="2.26"> Creates a D-Bus error name to use for @error. If @error matches + filename="gio/gdbuserror.c" + line="723">Creates a D-Bus error name to use for @error. If @error matches a registered error (cf. g_dbus_error_register_error()), the corresponding D-Bus error name will be returned. @@ -133402,19 +139016,19 @@ on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). This function is typically only used in object mappings to put a #GError on the wire. Regular applications should not use it. - + A D-Bus error name (never %NULL). + filename="gio/gdbuserror.c" + line="739">A D-Bus error name (never %NULL). Free with g_free(). A #GError. + filename="gio/gdbuserror.c" + line="725">A #GError. @@ -133424,26 +139038,26 @@ This function is typically only used in object mappings to put a moved-to="DBusError.get_remote_error" version="2.26"> Gets the D-Bus error name used for @error, if any. + filename="gio/gdbuserror.c" + line="430">Gets the D-Bus error name used for @error, if any. This function is guaranteed to return a D-Bus error name for all #GErrors returned from functions handling remote method calls (e.g. g_dbus_connection_call_finish()) unless g_dbus_error_strip_remote_error() has been used on @error. - + an allocated string or %NULL if the + filename="gio/gdbuserror.c" + line="441">an allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). a #GError + filename="gio/gdbuserror.c" + line="432">a #GError @@ -133453,22 +139067,22 @@ g_dbus_error_strip_remote_error() has been used on @error. moved-to="DBusError.is_remote_error" version="2.26"> Checks if @error represents an error received via D-Bus from a remote peer. If so, + filename="gio/gdbuserror.c" + line="410">Checks if @error represents an error received via D-Bus from a remote peer. If so, use g_dbus_error_get_remote_error() to get the name of the error. - + %TRUE if @error represents an error from a remote peer, + filename="gio/gdbuserror.c" + line="417">%TRUE if @error represents an error from a remote peer, %FALSE otherwise. A #GError. + filename="gio/gdbuserror.c" + line="412">A #GError. @@ -133478,8 +139092,8 @@ use g_dbus_error_get_remote_error() to get the name of the error. moved-to="DBusError.new_for_dbus_error" version="2.26"> Creates a #GError based on the contents of @dbus_error_name and + filename="gio/gdbuserror.c" + line="497">Creates a #GError based on the contents of @dbus_error_name and @dbus_error_message. Errors registered with g_dbus_error_register_error() will be looked @@ -133505,24 +139119,24 @@ returned #GError using the g_dbus_error_get_remote_error() function This function is typically only used in object mappings to prepare #GError instances for applications. Regular applications should not use it. - + An allocated #GError. Free with g_error_free(). + filename="gio/gdbuserror.c" + line="529">An allocated #GError. Free with g_error_free(). D-Bus error name. + filename="gio/gdbuserror.c" + line="499">D-Bus error name. D-Bus error message. + filename="gio/gdbuserror.c" + line="500">D-Bus error message. @@ -133539,37 +139153,37 @@ it. moved-to="DBusError.register_error" version="2.26"> Creates an association to map between @dbus_error_name and + filename="gio/gdbuserror.c" + line="271">Creates an association to map between @dbus_error_name and #GErrors specified by @error_domain and @error_code. This is typically done in the routine that returns the #GQuark for an error domain. - + %TRUE if the association was created, %FALSE if it already + filename="gio/gdbuserror.c" + line="283">%TRUE if the association was created, %FALSE if it already exists. A #GQuark for an error domain. + filename="gio/gdbuserror.c" + line="273">A #GQuark for an error domain. An error code. + filename="gio/gdbuserror.c" + line="274">An error code. A D-Bus error name. + filename="gio/gdbuserror.c" + line="275">A D-Bus error name. @@ -133579,32 +139193,32 @@ exists. moved-to="DBusError.register_error_domain" version="2.26"> Helper function for associating a #GError error domain with D-Bus error names. + filename="gio/gdbuserror.c" + line="97">Helper function for associating a #GError error domain with D-Bus error names. While @quark_volatile has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. - + The error domain name. + filename="gio/gdbuserror.c" + line="99">The error domain name. A pointer where to store the #GQuark. + filename="gio/gdbuserror.c" + line="100">A pointer where to store the #GQuark. A pointer to @num_entries #GDBusErrorEntry struct items. + filename="gio/gdbuserror.c" + line="101">A pointer to @num_entries #GDBusErrorEntry struct items. @@ -133613,8 +139227,8 @@ artifact and the argument passed to it should not be `volatile`. Number of items to register. + filename="gio/gdbuserror.c" + line="102">Number of items to register. @@ -133624,25 +139238,25 @@ artifact and the argument passed to it should not be `volatile`. moved-to="DBusError.strip_remote_error" version="2.26"> Looks for extra information in the error message used to recover + filename="gio/gdbuserror.c" + line="679">Looks for extra information in the error message used to recover the D-Bus error name and strips it if found. If stripped, the message field in @error will correspond exactly to what was received on the wire. This is typically used when presenting errors to the end user. - + %TRUE if information was stripped, %FALSE otherwise. + filename="gio/gdbuserror.c" + line="690">%TRUE if information was stripped, %FALSE otherwise. A #GError. + filename="gio/gdbuserror.c" + line="681">A #GError. @@ -133652,32 +139266,32 @@ This is typically used when presenting errors to the end user. moved-to="DBusError.unregister_error" version="2.26"> Destroys an association previously set up with g_dbus_error_register_error(). - + filename="gio/gdbuserror.c" + line="337">Destroys an association previously set up with g_dbus_error_register_error(). + %TRUE if the association was destroyed, %FALSE if it wasn't found. + filename="gio/gdbuserror.c" + line="345">%TRUE if the association was destroyed, %FALSE if it wasn't found. A #GQuark for an error domain. + filename="gio/gdbuserror.c" + line="339">A #GQuark for an error domain. An error code. + filename="gio/gdbuserror.c" + line="340">An error code. A D-Bus error name. + filename="gio/gdbuserror.c" + line="341">A D-Bus error name. @@ -133686,20 +139300,20 @@ This is typically used when presenting errors to the end user. c:identifier="g_dbus_escape_object_path" version="2.68"> This is a language binding friendly version of g_dbus_escape_object_path_bytestring(). - + filename="gio/gdbusutils.c" + line="767">This is a language binding friendly version of g_dbus_escape_object_path_bytestring(). + an escaped version of @s. Free with g_free(). + filename="gio/gdbusutils.c" + line="773">an escaped version of @s. Free with g_free(). the string to escape + filename="gio/gdbusutils.c" + line="769">the string to escape @@ -133708,8 +139322,8 @@ This is typically used when presenting errors to the end user. c:identifier="g_dbus_escape_object_path_bytestring" version="2.68"> Escapes @bytes for use in a D-Bus object path component. + filename="gio/gdbusutils.c" + line="718">Escapes @bytes for use in a D-Bus object path component. @bytes is an array of zero or more nonzero bytes in an unspecified encoding, followed by a single zero byte. @@ -133725,18 +139339,18 @@ Other escaping algorithms are also valid to use with D-Bus object paths. This can be reversed with g_dbus_unescape_object_path(). - + an escaped version of @bytes. Free with g_free(). + filename="gio/gdbusutils.c" + line="739">an escaped version of @bytes. Free with g_free(). the string of bytes to escape + filename="gio/gdbusutils.c" + line="720">the string of bytes to escape @@ -133747,8 +139361,8 @@ This can be reversed with g_dbus_unescape_object_path(). c:identifier="g_dbus_generate_guid" version="2.26"> Generate a D-Bus GUID that can be used with + filename="gio/gdbusutils.c" + line="292">Generate a D-Bus GUID that can be used with e.g. g_dbus_connection_new(). See the @@ -133759,11 +139373,11 @@ these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as Note that D-Bus GUIDs do not follow [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). - + A valid D-Bus GUID. Free with g_free(). + filename="gio/gdbusutils.c" + line="307">A valid D-Bus GUID. Free with g_free(). @@ -133771,8 +139385,8 @@ Note that D-Bus GUIDs do not follow c:identifier="g_dbus_gvalue_to_gvariant" version="2.30"> Converts a #GValue to a #GVariant of the type indicated by the @type + filename="gio/gdbusutils.c" + line="523">Converts a #GValue to a #GVariant of the type indicated by the @type parameter. The conversion is using the following rules: @@ -133800,11 +139414,11 @@ returned (e.g. 0 for scalar types, the empty string for string types, See the g_dbus_gvariant_to_gvalue() function for how to convert a #GVariant to a #GValue. - + A #GVariant (never floating) of + filename="gio/gdbusutils.c" + line="557">A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or an empty #GVariant in case of failure. Free with g_variant_unref(). @@ -133812,14 +139426,14 @@ See the g_dbus_gvariant_to_gvalue() function for how to convert a A #GValue to convert to a #GVariant + filename="gio/gdbusutils.c" + line="525">A #GValue to convert to a #GVariant A #GVariantType + filename="gio/gdbusutils.c" + line="526">A #GVariantType @@ -133828,8 +139442,8 @@ See the g_dbus_gvariant_to_gvalue() function for how to convert a c:identifier="g_dbus_gvariant_to_gvalue" version="2.30"> Converts a #GVariant to a #GValue. If @value is floating, it is consumed. + filename="gio/gdbusutils.c" + line="374">Converts a #GVariant to a #GValue. If @value is floating, it is consumed. The rules specified in the g_dbus_gvalue_to_gvariant() function are used - this function is essentially its reverse form. So, a #GVariant @@ -133840,15 +139454,15 @@ variant, tuple, dict entry) will be converted to a #GValue containing that The conversion never fails - a valid #GValue is always returned in @out_gvalue. - + A #GVariant. + filename="gio/gdbusutils.c" + line="376">A #GVariant. Return location pointing to a zero-filled (uninitialized) #GValue. + filename="gio/gdbusutils.c" + line="377">Return location pointing to a zero-filled (uninitialized) #GValue. @@ -133866,25 +139480,25 @@ The conversion never fails - a valid #GValue is always returned in c:identifier="g_dbus_is_address" version="2.26"> Checks if @string is a + filename="gio/gdbusaddress.c" + line="84">Checks if @string is a [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). This doesn't check if @string is actually supported by #GDBusServer or #GDBusConnection - use g_dbus_is_supported_address() to do more checks. - + %TRUE if @string is a valid D-Bus address, %FALSE otherwise. + filename="gio/gdbusaddress.c" + line="95">%TRUE if @string is a valid D-Bus address, %FALSE otherwise. A string. + filename="gio/gdbusaddress.c" + line="86">A string. @@ -133893,47 +139507,47 @@ checks. c:identifier="g_dbus_is_error_name" version="2.70"> Check whether @string is a valid D-Bus error name. + filename="gio/gdbusutils.c" + line="264">Check whether @string is a valid D-Bus error name. This function returns the same result as g_dbus_is_interface_name(), because D-Bus error names are defined to have exactly the same syntax as interface names. - + %TRUE if valid, %FALSE otherwise. + filename="gio/gdbusutils.c" + line="274">%TRUE if valid, %FALSE otherwise. The string to check. + filename="gio/gdbusutils.c" + line="266">The string to check. Checks if @string is a D-Bus GUID. + filename="gio/gdbusutils.c" + line="335">Checks if @string is a D-Bus GUID. See the documentation for g_dbus_generate_guid() for more information about the format of a GUID. - + %TRUE if @string is a GUID, %FALSE otherwise. + filename="gio/gdbusutils.c" + line="344">%TRUE if @string is a GUID, %FALSE otherwise. The string to check. + filename="gio/gdbusutils.c" + line="337">The string to check. @@ -133942,20 +139556,20 @@ the format of a GUID. c:identifier="g_dbus_is_interface_name" version="2.26"> Checks if @string is a valid D-Bus interface name. - + filename="gio/gdbusutils.c" + line="224">Checks if @string is a valid D-Bus interface name. + %TRUE if valid, %FALSE otherwise. + filename="gio/gdbusutils.c" + line="230">%TRUE if valid, %FALSE otherwise. The string to check. + filename="gio/gdbusutils.c" + line="226">The string to check. @@ -133964,40 +139578,40 @@ the format of a GUID. c:identifier="g_dbus_is_member_name" version="2.26"> Checks if @string is a valid D-Bus member (e.g. signal or method) name. - + filename="gio/gdbusutils.c" + line="187">Checks if @string is a valid D-Bus member (e.g. signal or method) name. + %TRUE if valid, %FALSE otherwise. + filename="gio/gdbusutils.c" + line="193">%TRUE if valid, %FALSE otherwise. The string to check. + filename="gio/gdbusutils.c" + line="189">The string to check. Checks if @string is a valid D-Bus bus name (either unique or well-known). - + filename="gio/gdbusutils.c" + line="103">Checks if @string is a valid D-Bus bus name (either unique or well-known). + %TRUE if valid, %FALSE otherwise. + filename="gio/gdbusutils.c" + line="109">%TRUE if valid, %FALSE otherwise. The string to check. + filename="gio/gdbusutils.c" + line="105">The string to check. @@ -134007,24 +139621,24 @@ the format of a GUID. version="2.26" throws="1"> Like g_dbus_is_address() but also checks if the library supports the + filename="gio/gdbusaddress.c" + line="368">Like g_dbus_is_address() but also checks if the library supports the transports in @string and that key/value pairs for each transport are valid. See the specification of the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - + %TRUE if @string is a valid D-Bus address that is + filename="gio/gdbusaddress.c" + line="378">%TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set. A string. + filename="gio/gdbusaddress.c" + line="370">A string. @@ -134033,20 +139647,20 @@ supported by this library, %FALSE if @error is set. c:identifier="g_dbus_is_unique_name" version="2.26"> Checks if @string is a valid D-Bus unique bus name. - + filename="gio/gdbusutils.c" + line="151">Checks if @string is a valid D-Bus unique bus name. + %TRUE if valid, %FALSE otherwise. + filename="gio/gdbusutils.c" + line="157">%TRUE if valid, %FALSE otherwise. The string to check. + filename="gio/gdbusutils.c" + line="153">The string to check. @@ -134055,8 +139669,8 @@ supported by this library, %FALSE if @error is set. c:identifier="g_dbus_unescape_object_path" version="2.68"> Unescapes an string that was previously escaped with + filename="gio/gdbusutils.c" + line="783">Unescapes an string that was previously escaped with g_dbus_escape_object_path(). If the string is in a format that could not have been returned by g_dbus_escape_object_path(), this function returns %NULL. @@ -134064,11 +139678,11 @@ returns %NULL. Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g `_63` is not valid, the string should contain `c` instead). - + an + filename="gio/gdbusutils.c" + line="796">an unescaped version of @s, or %NULL if @s is not a string returned from g_dbus_escape_object_path(). Free with g_free(). @@ -134078,8 +139692,8 @@ should contain `c` instead). the string to unescape + filename="gio/gdbusutils.c" + line="785">the string to unescape @@ -134090,22 +139704,22 @@ should contain `c` instead). version="2.48" throws="1"> Creates a new #GDtlsClientConnection wrapping @base_socket which is + filename="gio/gdtlsclientconnection.c" + line="126">Creates a new #GDtlsClientConnection wrapping @base_socket which is assumed to communicate with the server identified by @server_identity. - + the new + filename="gio/gdtlsclientconnection.c" + line="135">the new #GDtlsClientConnection, or %NULL on error the #GDatagramBased to wrap + filename="gio/gdtlsclientconnection.c" + line="128">the #GDatagramBased to wrap nullable="1" allow-none="1"> the expected identity of the server + filename="gio/gdtlsclientconnection.c" + line="129">the expected identity of the server @@ -134125,21 +139739,21 @@ assumed to communicate with the server identified by @server_identity. version="2.48" throws="1"> Creates a new #GDtlsServerConnection wrapping @base_socket. - + filename="gio/gdtlsserverconnection.c" + line="64">Creates a new #GDtlsServerConnection wrapping @base_socket. + the new + filename="gio/gdtlsserverconnection.c" + line="72">the new #GDtlsServerConnection, or %NULL on error the #GDatagramBased to wrap + filename="gio/gdtlsserverconnection.c" + line="66">the #GDatagramBased to wrap nullable="1" allow-none="1"> the default server certificate, or %NULL + filename="gio/gdtlsserverconnection.c" + line="67">the default server certificate, or %NULL - - #GIOExtensionPoint provides a mechanism for modules to extend the -functionality of the library or application that loaded it in an -organized fashion. - -An extension point is identified by a name, and it may optionally -require that any implementation must be of a certain type (or derived -thereof). Use g_io_extension_point_register() to register an -extension point, and g_io_extension_point_set_required_type() to -set a required type. - -A module can implement an extension point by specifying the #GType -that implements the functionality. Additionally, each implementation -of an extension point has a name, and a priority. Use -g_io_extension_point_implement() to implement an extension point. - - |[<!-- language="C" --> - GIOExtensionPoint *ep; - - // Register an extension point - ep = g_io_extension_point_register ("my-extension-point"); - g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); - ]| - - |[<!-- language="C" --> - // Implement an extension point - G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) - g_io_extension_point_implement ("my-extension-point", - my_example_impl_get_type (), - "my-example", - 10); - ]| - - It is up to the code that registered the extension point how - it uses the implementations that have been associated with it. - Depending on the use case, it may use all implementations, or - only the one with the highest priority, or pick a specific - one by name. - - To avoid opening all modules just to find out what extension - points they implement, GIO makes use of a caching mechanism, - see [gio-querymodules][gio-querymodules]. - You are expected to run this command after installing a - GIO module. - - The `GIO_EXTRA_MODULES` environment variable can be used to - specify additional directories to automatically load modules - from. This environment variable has the same syntax as the - `PATH`. If two modules have the same base name in different - directories, then the latter one will be ignored. If additional - directories are specified GIO will load modules from the built-in - directory last. - Constructs a #GFile from a vector of elements using the correct + filename="gio/gfile.c" + line="7581">Constructs a #GFile from a vector of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filenamev(), followed by g_file_new_for_path() on the result. - + a new #GFile + filename="gio/gfile.c" + line="7592">a new #GFile %NULL-terminated + filename="gio/gfile.c" + line="7583">%NULL-terminated array of strings containing the path elements. @@ -134242,8 +139801,8 @@ followed by g_file_new_for_path() on the result. c:identifier="g_file_new_for_commandline_arg" moved-to="File.new_for_commandline_arg"> Creates a #GFile with the given argument from the command line. + filename="gio/gfile.c" + line="7665">Creates a #GFile with the given argument from the command line. The value of @arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not @@ -134257,19 +139816,19 @@ the commandline. #GApplication also uses UTF-8 but g_application_command_line_create_file_for_arg() may be more useful for you there. It is also always possible to use this function with #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. - + a new #GFile. + filename="gio/gfile.c" + line="7684">a new #GFile. Free the returned object with g_object_unref(). a command line string + filename="gio/gfile.c" + line="7667">a command line string @@ -134279,8 +139838,8 @@ for you there. It is also always possible to use this function with moved-to="File.new_for_commandline_arg_and_cwd" version="2.36"> Creates a #GFile with the given argument from the command line. + filename="gio/gfile.c" + line="7695">Creates a #GFile with the given argument from the command line. This function is similar to g_file_new_for_commandline_arg() except that it allows for passing the current working directory as an @@ -134291,24 +139850,24 @@ This is useful if the commandline argument was given in a context other than the invocation of the current process. See also g_application_command_line_create_file_for_arg(). - + a new #GFile + filename="gio/gfile.c" + line="7712">a new #GFile a command line string + filename="gio/gfile.c" + line="7697">a command line string the current working directory of the commandline + filename="gio/gfile.c" + line="7698">the current working directory of the commandline @@ -134317,23 +139876,23 @@ See also g_application_command_line_create_file_for_arg(). c:identifier="g_file_new_for_path" moved-to="File.new_for_path"> Constructs a #GFile for a given path. This operation never + filename="gio/gfile.c" + line="7190">Constructs a #GFile for a given path. This operation never fails, but the returned object might not support any I/O operation if @path is malformed. - + a new #GFile for the given @path. + filename="gio/gfile.c" + line="7199">a new #GFile for the given @path. Free the returned object with g_object_unref(). a string containing a relative or absolute path. + filename="gio/gfile.c" + line="7192">a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. @@ -134343,24 +139902,24 @@ operation if @path is malformed. c:identifier="g_file_new_for_uri" moved-to="File.new_for_uri"> Constructs a #GFile for a given URI. This operation never + filename="gio/gfile.c" + line="7210">Constructs a #GFile for a given URI. This operation never fails, but the returned object might not support any I/O operation if @uri is malformed or if the uri type is not supported. - + a new #GFile for the given @uri. + filename="gio/gfile.c" + line="7219">a new #GFile for the given @uri. Free the returned object with g_object_unref(). a UTF-8 string containing a URI + filename="gio/gfile.c" + line="7212">a UTF-8 string containing a URI @@ -134369,10 +139928,11 @@ not supported. c:identifier="g_file_new_tmp" moved-to="File.new_tmp" version="2.32" - throws="1"> + throws="1" + glib:async-func="file_new_tmp_async"> Opens a file in the preferred directory for temporary files (as + filename="gio/gfile.c" + line="7230">Opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) and returns a #GFile and #GFileIOStream pointing to it. @@ -134382,11 +139942,11 @@ directory components. If it is %NULL, a default template is used. Unlike the other #GFile constructors, this will return %NULL if a temporary file could not be created. - + a new #GFile. + filename="gio/gfile.c" + line="7248">a new #GFile. Free the returned object with g_object_unref(). @@ -134396,8 +139956,8 @@ a temporary file could not be created. nullable="1" allow-none="1"> Template for the file + filename="gio/gfile.c" + line="7232">Template for the file name, as in g_file_open_tmp(), or %NULL for a default template @@ -134406,8 +139966,8 @@ a temporary file could not be created. caller-allocates="0" transfer-ownership="full"> on return, a #GFileIOStream for the created file + filename="gio/gfile.c" + line="7234">on return, a #GFileIOStream for the created file @@ -134415,16 +139975,18 @@ a temporary file could not be created. + version="2.74" + glib:finish-func="file_new_tmp_finish" + glib:sync-func="file_new_tmp"> Asynchronously opens a file in the preferred directory for temporary files + filename="gio/gfile.c" + line="7340">Asynchronously opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_file_new_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. - + @@ -134434,15 +139996,15 @@ directory components. If it is %NULL, a default template is used. nullable="1" allow-none="1"> Template for the file + filename="gio/gfile.c" + line="7342">Template for the file name, as in g_file_open_tmp(), or %NULL for a default template the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="7344">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="7345">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gfile.c" + line="7346">a #GAsyncReadyCallback to call when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gfile.c" + line="7347">data to pass to @callback @@ -134479,16 +140041,17 @@ directory components. If it is %NULL, a default template is used. + version="2.74" + glib:finish-func="file_new_tmp_dir_finish"> Asynchronously creates a directory in the preferred directory for + filename="gio/gfile.c" + line="7463">Asynchronously creates a directory in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp(). @tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is %NULL, a default template is used. - + @@ -134498,15 +140061,15 @@ directory components. If it is %NULL, a default template is used. nullable="1" allow-none="1"> Template for the file + filename="gio/gfile.c" + line="7465">Template for the file name, as in g_dir_make_tmp(), or %NULL for a default template the [I/O priority][io-priority] of the request + filename="gio/gfile.c" + line="7467">the [I/O priority](iface.AsyncResult.html#io-priority) of the request nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore + filename="gio/gfile.c" + line="7468">optional #GCancellable object, %NULL to ignore scope="async" closure="4"> a #GAsyncReadyCallback to call when the request is done + filename="gio/gfile.c" + line="7469">a #GAsyncReadyCallback to call when the request is done nullable="1" allow-none="1"> data to pass to @callback + filename="gio/gfile.c" + line="7470">data to pass to @callback @@ -134546,22 +140109,22 @@ directory components. If it is %NULL, a default template is used. version="2.74" throws="1"> Finishes a temporary directory creation started by + filename="gio/gfile.c" + line="7501">Finishes a temporary directory creation started by g_file_new_tmp_dir_async(). - + a new #GFile. + filename="gio/gfile.c" + line="7509">a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult + filename="gio/gfile.c" + line="7503">a #GAsyncResult @@ -134572,21 +140135,21 @@ g_file_new_tmp_dir_async(). version="2.74" throws="1"> Finishes a temporary file creation started by g_file_new_tmp_async(). - + filename="gio/gfile.c" + line="7378">Finishes a temporary file creation started by g_file_new_tmp_async(). + a new #GFile. + filename="gio/gfile.c" + line="7386">a new #GFile. Free the returned object with g_object_unref(). a #GAsyncResult + filename="gio/gfile.c" + line="7380">a #GAsyncResult caller-allocates="0" transfer-ownership="full"> on return, a #GFileIOStream for the created file + filename="gio/gfile.c" + line="7381">on return, a #GFileIOStream for the created file @@ -134604,437 +140167,46 @@ g_file_new_tmp_dir_async(). c:identifier="g_file_parse_name" moved-to="File.parse_name"> Constructs a #GFile with the given @parse_name (i.e. something + filename="gio/gfile.c" + line="7526">Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()). This operation never fails, but the returned object might not support any I/O operation if the @parse_name cannot be parsed. - + a new #GFile. + filename="gio/gfile.c" + line="7535">a new #GFile. a file name or path to be parsed + filename="gio/gfile.c" + line="7528">a file name or path to be parsed - - These functions support exporting a #GActionGroup on D-Bus. -The D-Bus interface that is used is a private implementation -detail. - -To access an exported #GActionGroup remotely, use -g_dbus_action_group_get() to obtain a #GDBusActionGroup. - - - A content type is a platform specific string that defines the type -of a file. On UNIX it is a -[MIME type](http://www.wikipedia.org/wiki/Internet_media_type) -like `text/plain` or `image/png`. -On Win32 it is an extension string like `.doc`, `.txt` or a perceived -string like `audio`. Such strings can be looked up in the registry at -`HKEY_CLASSES_ROOT`. -On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) -such as `com.apple.application`. - - - Routines for working with D-Bus addresses. A D-Bus address is a string -like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses -is explained in detail in the -[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - -TCP D-Bus connections are supported, but accessing them via a proxy is -currently not supported. - -Since GLib 2.72, `unix:` addresses are supported on Windows with `AF_UNIX` -support (Windows 10). - - - All facilities that return errors from remote methods (such as -g_dbus_connection_call_sync()) use #GError to represent both D-Bus -errors (e.g. errors returned from the other peer) and locally -in-process generated errors. - -To check if a returned #GError is an error from a remote peer, use -g_dbus_error_is_remote_error(). To get the actual D-Bus error name, -use g_dbus_error_get_remote_error(). Before presenting an error, -always use g_dbus_error_strip_remote_error(). - -In addition, facilities used to return errors to a remote peer also -use #GError. See g_dbus_method_invocation_return_error() for -discussion about how the D-Bus error name is set. - -Applications can associate a #GError error domain with a set of D-Bus errors in order to -automatically map from D-Bus errors to #GError and back. This -is typically done in the function returning the #GQuark for the -error domain: -|[<!-- language="C" --> -// foo-bar-error.h: - -#define FOO_BAR_ERROR (foo_bar_error_quark ()) -GQuark foo_bar_error_quark (void); - -typedef enum -{ - FOO_BAR_ERROR_FAILED, - FOO_BAR_ERROR_ANOTHER_ERROR, - FOO_BAR_ERROR_SOME_THIRD_ERROR, - FOO_BAR_N_ERRORS / *< skip >* / -} FooBarError; - -// foo-bar-error.c: - -static const GDBusErrorEntry foo_bar_error_entries[] = -{ - {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, - {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, - {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, -}; - -// Ensure that every error code has an associated D-Bus error name -G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); - -GQuark -foo_bar_error_quark (void) -{ - static gsize quark = 0; - g_dbus_error_register_error_domain ("foo-bar-error-quark", - &quark, - foo_bar_error_entries, - G_N_ELEMENTS (foo_bar_error_entries)); - return (GQuark) quark; -} -]| -With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and -other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError. - -If the other peer is using GDBus, and has registered the association with -g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark -generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead -of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover -org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). - -Note that the %G_DBUS_ERROR error domain is intended only -for returning errors from a remote message bus process. Errors -generated locally in-process by e.g. #GDBusConnection should use the -%G_IO_ERROR domain. - - - Various data structures and convenience routines to parse and -generate D-Bus introspection XML. Introspection information is -used when registering objects with g_dbus_connection_register_object(). - -The format of D-Bus introspection XML is specified in the -[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) - - - Convenience API for owning bus names. - -A simple example for owning a name can be found in -[gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c) - - - Convenience API for watching bus names. - -A simple example for watching a name can be found in -[gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c) - - - Various utility routines related to D-Bus. - - - File attributes in GIO consist of a list of key-value pairs. - -Keys are strings that contain a key namespace and a key name, separated -by a colon, e.g. "namespace::keyname". Namespaces are included to sort -key-value pairs by namespaces for relevance. Keys can be retrieved -using wildcards, e.g. "standard::*" will return all of the keys in the -"standard" namespace. - -The list of possible attributes for a filesystem (pointed to by a #GFile) is -available as a #GFileAttributeInfoList. This list is queryable by key names -as indicated earlier. - -Information is stored within the list in #GFileAttributeInfo structures. -The info structure can store different types, listed in the enum -#GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will -be set to %G_FILE_ATTRIBUTE_TYPE_INVALID. - -Classes that implement #GFileIface will create a #GFileAttributeInfoList and -install default keys and values for their given file system, architecture, -and other possible implementation details (e.g., on a UNIX system, a file -attribute key will be registered for the user id for a given file). - -## Default Namespaces - -- `"standard"`: The "Standard" namespace. General file information that - any application may need should be put in this namespace. Examples - include the file's name, type, and size. -- `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key - in this namespace is "value", which contains the value of the current - entity tag. -- `"id"`: The "Identification" namespace. This namespace is used by file - managers and applications that list directories to check for loops and - to uniquely identify files. -- `"access"`: The "Access" namespace. Used to check if a user has the - proper privileges to access files and perform file operations. Keys in - this namespace are made to be generic and easily understood, e.g. the - "can_read" key is %TRUE if the current user has permission to read the - file. UNIX permissions and NTFS ACLs in Windows should be mapped to - these values. -- `"mountable"`: The "Mountable" namespace. Includes simple boolean keys - for checking if a file or path supports mount operations, e.g. mount, - unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. -- `"time"`: The "Time" namespace. Includes file access, changed, created - times. -- `"unix"`: The "Unix" namespace. Includes UNIX-specific information and - may not be available for all files. Examples include the UNIX "UID", - "GID", etc. -- `"dos"`: The "DOS" namespace. Includes DOS-specific information and may - not be available for all files. Examples include "is_system" for checking - if a file is marked as a system file, and "is_archive" for checking if a - file is marked as an archive file. -- `"owner"`: The "Owner" namespace. Includes information about who owns a - file. May not be available for all file systems. Examples include "user" - for getting the user name of the file owner. This information is often - mapped from some backend specific data such as a UNIX UID. -- `"thumbnail"`: The "Thumbnail" namespace. Includes information about file - thumbnails and their location within the file system. Examples of keys in - this namespace include "path" to get the location of a thumbnail, "failed" - to check if thumbnailing of the file failed, and "is-valid" to check if - the thumbnail is outdated. -- `"filesystem"`: The "Filesystem" namespace. Gets information about the - file system where a file is located, such as its type, how much space is - left available, and the overall size of the file system. -- `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information - about the current GVFS backend in use. -- `"xattr"`: The "xattr" namespace. Gets information about extended - user attributes. See attr(5). The "user." prefix of the extended user - attribute name is stripped away when constructing keys in this namespace, - e.g. "xattr::mime_type" for the extended attribute with the name - "user.mime_type". Note that this information is only available if - GLib has been built with extended attribute support. -- `"xattr-sys"`: The "xattr-sys" namespace. Gets information about - extended attributes which are not user-specific. See attr(5). Note - that this information is only available if GLib has been built with - extended attribute support. -- `"selinux"`: The "SELinux" namespace. Includes information about the - SELinux context of files. Note that this information is only available - if GLib has been built with SELinux support. - -Please note that these are not all of the possible namespaces. -More namespaces can be added from GIO modules or by individual applications. -For more information about writing GIO modules, see #GIOModule. - -<!-- TODO: Implementation note about using extended attributes on supported -file systems --> - -## Default Keys - -For a list of the built-in keys and their types, see the -[GFileInfo][GFileInfo] documentation. - -Note that there are no predefined keys in the "xattr" and "xattr-sys" -namespaces. Keys for the "xattr" namespace are constructed by stripping -away the "user." prefix from the extended user attribute, and prepending -"xattr::". Keys for the "xattr-sys" namespace are constructed by -concatenating "xattr-sys::" with the extended attribute name. All extended -attribute values are returned as hex-encoded strings in which bytes outside -the ASCII range are encoded as escape sequences of the form \x`nn` -where `nn` is a 2-digit hexadecimal number. - - - Contains helper functions for reporting errors to the user. - - - As of GLib 2.36, #GIOScheduler is deprecated in favor of -#GThreadPool and #GTask. - -Schedules asynchronous I/O operations. #GIOScheduler integrates -into the main event loop (#GMainLoop) and uses threads. - - - These functions support exporting a #GMenuModel on D-Bus. -The D-Bus interface that is used is a private implementation -detail. - -To access an exported #GMenuModel remotely, use -g_dbus_menu_model_get() to obtain a #GDBusMenuModel. - - - The `<gio/gnetworking.h>` header can be included to get -various low-level networking-related system headers, automatically -taking care of certain portability issues for you. - -This can be used, for example, if you want to call setsockopt() -on a #GSocket. - -Note that while WinSock has many of the same APIs as the -traditional UNIX socket API, most of them behave at least slightly -differently (particularly with respect to error handling). If you -want your code to work under both UNIX and Windows, you will need -to take these differences into account. - -Also, under GNU libc, certain non-portable functions are only visible -in the headers if you define %_GNU_SOURCE before including them. Note -that this symbol must be defined before including any headers, or it -may not take effect. - - - Utility functions for #GPollableInputStream and -#GPollableOutputStream implementations. - - - #GTlsConnection and related classes provide TLS (Transport Layer -Security, previously known as SSL, Secure Sockets Layer) support for -gio-based network streams. - -#GDtlsConnection and related classes provide DTLS (Datagram TLS) support for -GIO-based network sockets, using the #GDatagramBased interface. The TLS and -DTLS APIs are almost identical, except TLS is stream-based and DTLS is -datagram-based. They share certificate and backend infrastructure. - -In the simplest case, for a client TLS connection, you can just set the -#GSocketClient:tls flag on a #GSocketClient, and then any -connections created by that client will have TLS negotiated -automatically, using appropriate default settings, and rejecting -any invalid or self-signed certificates (unless you change that -default by setting the #GSocketClient:tls-validation-flags -property). The returned object will be a #GTcpWrapperConnection, -which wraps the underlying #GTlsClientConnection. - -For greater control, you can create your own #GTlsClientConnection, -wrapping a #GSocketConnection (or an arbitrary #GIOStream with -pollable input and output streams) and then connect to its signals, -such as #GTlsConnection::accept-certificate, before starting the -handshake. - -Server-side TLS is similar, using #GTlsServerConnection. At the -moment, there is no support for automatically wrapping server-side -connections in the way #GSocketClient does for client-side -connections. - - - Routines for managing mounted UNIX mount points and paths. - -Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - #GWin32InputStream implements #GInputStream for reading from a -Windows file handle. - -Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO -interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file -when using it. - - - #GWin32OutputStream implements #GOutputStream for writing to a -Windows file handle. - -Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO -interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file -when using it. - - - #GWin32RegistryKey represents a single Windows Registry key. - -#GWin32RegistryKey is used by a number of helper functions that read -Windows Registry. All keys are opened with read-only access, and at -the moment there is no API for writing into registry keys or creating -new ones. - -#GWin32RegistryKey implements the #GInitable interface, so if it is manually -constructed by e.g. g_object_new() you must call g_initable_init() and check -the results before using the object. This is done automatically -in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these -functions can return %NULL. - -To increase efficiency, a UTF-16 variant is available for all functions -that deal with key or value names in the registry. Use these to perform -deep registry queries or other operations that require querying a name -of a key or a value and then opening it (or querying its data). The use -of UTF-16 functions avoids the overhead of converting names to UTF-8 and -back. - -All functions operate in current user's context (it is not possible to -access registry tree of a different user). - -Key paths must use '\\' as a separator, '/' is not supported. Key names -must not include '\\', because it's used as a separator. Value names -can include '\\'. - -Key and value names are not case sensitive. - -Full key name (excluding the pre-defined ancestor's name) can't exceed -255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 -characters. Tree depth is limited to 512 levels. - Deserializes a #GIcon previously serialized using g_icon_serialize(). - + filename="gio/gicon.c" + line="559">Deserializes a #GIcon previously serialized using g_icon_serialize(). + a #GIcon, or %NULL when deserialization fails. + filename="gio/gicon.c" + line="565">a #GIcon, or %NULL when deserialization fails. a #GVariant created with g_icon_serialize() + filename="gio/gicon.c" + line="561">a #GVariant created with g_icon_serialize() @@ -135045,26 +140217,26 @@ characters. Tree depth is limited to 512 levels. version="2.20" throws="1"> Generate a #GIcon instance from @str. This function can fail if + filename="gio/gicon.c" + line="425">Generate a #GIcon instance from @str. This function can fail if @str is not valid - see g_icon_to_string() for discussion. If your application or library provides one or more #GIcon implementations you need to ensure that each #GType is registered with the type system prior to calling g_icon_new_for_string(). - + An object implementing the #GIcon + filename="gio/gicon.c" + line="437">An object implementing the #GIcon interface or %NULL if @error is set. A string obtained via g_icon_to_string(). + filename="gio/gicon.c" + line="427">A string obtained via g_icon_to_string(). @@ -135077,37 +140249,37 @@ with the type system prior to calling g_icon_new_for_string(). deprecated-version="2.54" throws="1"> Helper function for constructing #GInitable object. This is + filename="gio/ginitable.c" + line="171">Helper function for constructing #GInitable object. This is similar to g_object_newv() but also initializes the object and returns %NULL, setting an error on failure. Use g_object_new_with_properties() and g_initable_init() instead. See #GParameter for more information. - + a newly allocated + filename="gio/ginitable.c" + line="184">a newly allocated #GObject, or %NULL on error a #GType supporting #GInitable. + filename="gio/ginitable.c" + line="173">a #GType supporting #GInitable. the number of parameters in @parameters + filename="gio/ginitable.c" + line="174">the number of parameters in @parameters the parameters to use to construct the object + filename="gio/ginitable.c" + line="175">the parameters to use to construct the object @@ -135117,34 +140289,46 @@ g_initable_init() instead. See #GParameter for more information. optional #GCancellable object, %NULL to ignore. + filename="gio/ginitable.c" + line="176">optional #GCancellable object, %NULL to ignore. Converts errno.h error codes into GIO error codes. The fallback -value %G_IO_ERROR_FAILED is returned for error codes not currently -handled (but note that future GLib releases may return a more + filename="gio/gioerror.c" + line="42">Converts `errno.h` error codes into GIO error codes. + +The fallback value %G_IO_ERROR_FAILED is returned for error codes not +currently handled (but note that future GLib releases may return a more specific value instead). -As %errno is global and may be modified by intermediate function -calls, you should save its value as soon as the call which sets it - +As `errno` is global and may be modified by intermediate function +calls, you should save its value immediately after the call returns, +and use the saved value instead of `errno`: + + +|[<!-- language="C" --> + int saved_errno; + + ret = read (blah); + saved_errno = errno; + + g_io_error_from_errno (saved_errno); +]| + #GIOErrorEnum value for the given errno.h error number. + filename="gio/gioerror.c" + line="66">#GIOErrorEnum value for the given `errno.h` error number Error number as defined in errno.h. + filename="gio/gioerror.c" + line="44">Error number as defined in errno.h. @@ -135153,32 +140337,32 @@ calls, you should save its value as soon as the call which sets it c:identifier="g_io_error_from_file_error" version="2.74"> Converts #GFileError error codes into GIO error codes. - + filename="gio/gioerror.c" + line="253">Converts #GFileError error codes into GIO error codes. + #GIOErrorEnum value for the given #GFileError error value. + filename="gio/gioerror.c" + line="259">#GIOErrorEnum value for the given #GFileError error value. a #GFileError. + filename="gio/gioerror.c" + line="255">a #GFileError. Gets the GIO Error Quark. + filename="gio/gioerror.c" + line="33">Gets the GIO Error Quark. a #GQuark. + filename="gio/gioerror.c" + line="38">a #GQuark. @@ -135186,42 +140370,42 @@ calls, you should save its value as soon as the call which sets it c:identifier="g_io_extension_point_implement" moved-to="IOExtensionPoint.implement"> Registers @type as extension for the extension point with name + filename="gio/giomodule.c" + line="1582">Registers @type as extension for the extension point with name @extension_point_name. If @type has already been registered as an extension for this extension point, the existing #GIOExtension object is returned. - + a #GIOExtension object for #GType + filename="gio/giomodule.c" + line="1595">a #GIOExtension object for #GType the name of the extension point + filename="gio/giomodule.c" + line="1584">the name of the extension point the #GType to register as extension + filename="gio/giomodule.c" + line="1585">the #GType to register as extension the name for the extension + filename="gio/giomodule.c" + line="1586">the name for the extension the priority for the extension + filename="gio/giomodule.c" + line="1587">the priority for the extension @@ -135230,21 +140414,21 @@ extension point, the existing #GIOExtension object is returned. c:identifier="g_io_extension_point_lookup" moved-to="IOExtensionPoint.lookup"> Looks up an existing extension point. - + filename="gio/giomodule.c" + line="1440">Looks up an existing extension point. + the #GIOExtensionPoint, or %NULL if there + filename="gio/giomodule.c" + line="1446">the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. the name of the extension point + filename="gio/giomodule.c" + line="1442">the name of the extension point @@ -135253,21 +140437,21 @@ extension point, the existing #GIOExtension object is returned. c:identifier="g_io_extension_point_register" moved-to="IOExtensionPoint.register"> Registers an extension point. - + filename="gio/giomodule.c" + line="1402">Registers an extension point. + the new #GIOExtensionPoint. This object is + filename="gio/giomodule.c" + line="1408">the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. The name of the extension point + filename="gio/giomodule.c" + line="1404">The name of the extension point @@ -135275,17 +140459,17 @@ extension point, the existing #GIOExtension object is returned. Loads all the modules in the specified directory. + filename="gio/giomodule.c" + line="692">Loads all the modules in the specified directory. If don't require all modules to be initialized (and thus registering all gtypes) then you can use g_io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules. - + a list of #GIOModules loaded + filename="gio/giomodule.c" + line="703">a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call @@ -135298,8 +140482,8 @@ which allows delayed/lazy loading of modules. pathname for a directory containing modules + filename="gio/giomodule.c" + line="694">pathname for a directory containing modules to load. @@ -135309,17 +140493,17 @@ which allows delayed/lazy loading of modules. c:identifier="g_io_modules_load_all_in_directory_with_scope" version="2.30"> Loads all the modules in the specified directory. + filename="gio/giomodule.c" + line="626">Loads all the modules in the specified directory. If don't require all modules to be initialized (and thus registering all gtypes) then you can use g_io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules. - + a list of #GIOModules loaded + filename="gio/giomodule.c" + line="638">a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call @@ -135332,15 +140516,15 @@ which allows delayed/lazy loading of modules. pathname for a directory containing modules + filename="gio/giomodule.c" + line="628">pathname for a directory containing modules to load. a scope to use when scanning the modules. + filename="gio/giomodule.c" + line="630">a scope to use when scanning the modules. @@ -135349,8 +140533,8 @@ which allows delayed/lazy loading of modules. c:identifier="g_io_modules_scan_all_in_directory" version="2.24"> Scans all the modules in the specified directory, ensuring that + filename="gio/giomodule.c" + line="601">Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered. This may not actually load and initialize all the types in each @@ -135361,15 +140545,15 @@ g_io_extension_point_get_extension_by_name(). If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory(). - + pathname for a directory containing modules + filename="gio/giomodule.c" + line="603">pathname for a directory containing modules to scan. @@ -135379,8 +140563,8 @@ use g_io_modules_load_all_in_directory(). c:identifier="g_io_modules_scan_all_in_directory_with_scope" version="2.30"> Scans all the modules in the specified directory, ensuring that + filename="gio/giomodule.c" + line="448">Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered. This may not actually load and initialize all the types in each @@ -135391,49 +140575,51 @@ g_io_extension_point_get_extension_by_name(). If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory(). - + pathname for a directory containing modules + filename="gio/giomodule.c" + line="450">pathname for a directory containing modules to scan. a scope to use when scanning the modules + filename="gio/giomodule.c" + line="452">a scope to use when scanning the modules + deprecated="1" + deprecated-version="2.36"> Cancels all cancellable I/O jobs. + filename="gio/gioscheduler.c" + line="140">Cancels all cancellable I/O jobs. A job is cancellable if a #GCancellable was passed into g_io_scheduler_push_job(). You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler. - + + deprecated="1" + deprecated-version="2.36"> Schedules the I/O job to run in another thread. + filename="gio/gioscheduler.c" + line="83">Schedules the I/O job to run in another thread. @notify will be called on @user_data after @job_func has returned, regardless whether the job was cancelled or has run to completion. @@ -135442,7 +140628,7 @@ If @cancellable is not %NULL, it can be used to cancel the I/O job by calling g_cancellable_cancel() or by calling g_io_scheduler_cancel_all_jobs(). use #GThreadPool or g_task_run_in_thread() - + @@ -135453,8 +140639,8 @@ g_io_scheduler_cancel_all_jobs(). closure="1" destroy="2"> a #GIOSchedulerJobFunc. + filename="gio/gioscheduler.c" + line="85">a #GIOSchedulerJobFunc. nullable="1" allow-none="1"> data to pass to @job_func + filename="gio/gioscheduler.c" + line="86">data to pass to @job_func allow-none="1" scope="async"> a #GDestroyNotify for @user_data, or %NULL + filename="gio/gioscheduler.c" + line="87">a #GDestroyNotify for @user_data, or %NULL the [I/O priority][io-priority] + filename="gio/gioscheduler.c" + line="88">the [I/O priority](iface.AsyncResult.html#io-priority) of the request. @@ -135488,8 +140674,8 @@ of the request. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gioscheduler.c" + line="90">optional #GCancellable object, %NULL to ignore. @@ -135497,74 +140683,74 @@ of the request. Creates a keyfile-backed #GSettingsBackend. + filename="gio/gkeyfilesettingsbackend.c" + line="954">Creates a keyfile-backed [class@Gio.SettingsBackend]. The filename of the keyfile to use is given by @filename. All settings read to or written from the backend must fall under the path given in @root_path (which must start and end with a slash and -not contain two consecutive slashes). @root_path may be "/". +not contain two consecutive slashes). @root_path may be `"/"`. -If @root_group is non-%NULL then it specifies the name of the keyfile +If @root_group is non-`NULL` then it specifies the name of the keyfile group used for keys that are written directly below @root_path. For -example, if @root_path is "/apps/example/" and @root_group is -"toplevel", then settings the key "/apps/example/enabled" to a value -of %TRUE will cause the following to appear in the keyfile: +example, if @root_path is `"/apps/example/"` and @root_group is +`"toplevel"`, then setting the key `"/apps/example/enabled"` to true will +cause the following to appear in the keyfile: -|[ - [toplevel] - enabled=true -]| +``` +[toplevel] +enabled=true +``` -If @root_group is %NULL then it is not permitted to store keys +If @root_group is `NULL` then it is not permitted to store keys directly below the @root_path. For keys not stored directly below @root_path (ie: in a sub-path), the name of the subpath (with the final slash stripped) is used as the name of the keyfile group. To continue the example, if -"/apps/example/profiles/default/font-size" were set to -12 then the following would appear in the keyfile: +`"/apps/example/profiles/default/font-size"` were set to +`12` then the following would appear in the keyfile: -|[ - [profiles/default] - font-size=12 -]| +``` +[profiles/default] +font-size=12 +``` The backend will refuse writes (and return writability as being -%FALSE) for keys outside of @root_path and, in the event that -@root_group is %NULL, also for keys directly under @root_path. +false) for keys outside of @root_path and, in the event that +@root_group is `NULL`, also for keys directly under @root_path. Writes will also be refused if the backend detects that it has the inability to rewrite the keyfile (ie: the containing directory is not writable). There is no checking done for your key namespace clashing with the -syntax of the key file format. For example, if you have '[' or ']' -characters in your path names or '=' in your key names you may be in +syntax of the key file format. For example, if you have `[` or `]` +characters in your path names or `=` in your key names you may be in trouble. The backend reads default values from a keyfile called `defaults` in -the directory specified by the #GKeyfileSettingsBackend:defaults-dir property, -and a list of locked keys from a text file with the name `locks` in +the directory specified by the `GKeyfileSettingsBackend:defaults-dir` +property, and a list of locked keys from a text file with the name `locks` in the same location. - + a keyfile-backed #GSettingsBackend + filename="gio/gkeyfilesettingsbackend.c" + line="1011">a keyfile-backed [class@Gio.SettingsBackend] the filename of the keyfile + filename="gio/gkeyfilesettingsbackend.c" + line="956">the filename of the keyfile the path under which all settings keys appear + filename="gio/gkeyfilesettingsbackend.c" + line="957">the path under which all settings keys appear nullable="1" allow-none="1"> the group name corresponding to - @root_path, or %NULL + filename="gio/gkeyfilesettingsbackend.c" + line="958">the group name corresponding to @root_path, or + `NULL` to disallow storing keys directly beneath @root_path @@ -135584,13 +140770,13 @@ the same location. moved-to="MemoryMonitor.dup_default" version="2.64"> Gets a reference to the default #GMemoryMonitor for the system. - + filename="gio/gmemorymonitor.c" + line="109">Gets a reference to the default #GMemoryMonitor for the system. + a new reference to the default #GMemoryMonitor + filename="gio/gmemorymonitor.c" + line="114">a new reference to the default #GMemoryMonitor @@ -135598,17 +140784,17 @@ the same location. c:identifier="g_memory_settings_backend_new" version="2.28"> Creates a memory-backed #GSettingsBackend. + filename="gio/gmemorysettingsbackend.c" + line="178">Creates a memory-backed #GSettingsBackend. This backend allows changes to settings, but does not write them to any backing storage, so the next time you run your application, the memory backend will start out with the default values again. - + a newly created #GSettingsBackend + filename="gio/gmemorysettingsbackend.c" + line="187">a newly created #GSettingsBackend @@ -135617,13 +140803,13 @@ the memory backend will start out with the default values again. moved-to="NetworkMonitor.get_default" version="2.32"> Gets the default #GNetworkMonitor for the system. - + filename="gio/gnetworkmonitor.c" + line="74">Gets the default #GNetworkMonitor for the system. + a #GNetworkMonitor, which will be + filename="gio/gnetworkmonitor.c" + line="79">a #GNetworkMonitor, which will be a dummy object if no network monitor is available @@ -135632,12 +140818,12 @@ the memory backend will start out with the default values again. c:identifier="g_networking_init" version="2.36"> Initializes the platform networking libraries (eg, on Windows, this + filename="gio/gnetworking.c" + line="28">Initializes the platform networking libraries (eg, on Windows, this calls WSAStartup()). GLib will call this itself if it is needed, so you only need to call it if you directly call system networking functions (without calling any GLib networking functions first). - + @@ -135646,16 +140832,16 @@ functions (without calling any GLib networking functions first). c:identifier="g_null_settings_backend_new" version="2.28"> Creates a readonly #GSettingsBackend. + filename="gio/gnullsettingsbackend.c" + line="123">Creates a readonly #GSettingsBackend. This backend does not allow changes to settings, so all settings will always have their default values. - + a newly created #GSettingsBackend + filename="gio/gnullsettingsbackend.c" + line="132">a newly created #GSettingsBackend @@ -135663,24 +140849,24 @@ will always have their default values. c:identifier="g_pollable_source_new" version="2.28"> Utility method for #GPollableInputStream and #GPollableOutputStream + filename="gio/gpollableutils.c" + line="88">Utility method for #GPollableInputStream and #GPollableOutputStream implementations. Creates a new #GSource that expects a callback of type #GPollableSourceFunc. The new source does not actually do anything on its own; use g_source_add_child_source() to add other sources to it to cause it to trigger. - + the new #GSource. + filename="gio/gpollableutils.c" + line="98">the new #GSource. the stream associated with the new source + filename="gio/gpollableutils.c" + line="90">the stream associated with the new source @@ -135689,23 +140875,23 @@ sources to it to cause it to trigger. c:identifier="g_pollable_source_new_full" version="2.34"> Utility method for #GPollableInputStream and #GPollableOutputStream + filename="gio/gpollableutils.c" + line="119">Utility method for #GPollableInputStream and #GPollableOutputStream implementations. Creates a new #GSource, as with g_pollable_source_new(), but also attaching @child_source (with a dummy callback), and @cancellable, if they are non-%NULL. - + the new #GSource. + filename="gio/gpollableutils.c" + line="131">the new #GSource. the stream associated with the + filename="gio/gpollableutils.c" + line="121">the stream associated with the new source @@ -135714,8 +140900,8 @@ dummy callback), and @cancellable, if they are non-%NULL. nullable="1" allow-none="1"> optional child source to attach + filename="gio/gpollableutils.c" + line="123">optional child source to attach nullable="1" allow-none="1"> optional #GCancellable to attach + filename="gio/gpollableutils.c" + line="124">optional #GCancellable to attach @@ -135734,8 +140920,8 @@ dummy callback), and @cancellable, if they are non-%NULL. version="2.34" throws="1"> Tries to read from @stream, as with g_input_stream_read() (if + filename="gio/gpollableutils.c" + line="163">Tries to read from @stream, as with g_input_stream_read() (if @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking() (if @blocking is %FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method. @@ -135744,24 +140930,24 @@ If @blocking is %FALSE, then @stream must be a #GPollableInputStream for which g_pollable_input_stream_can_poll() returns %TRUE, or else the behavior is undefined. If @blocking is %TRUE, then @stream does not need to be a #GPollableInputStream. - + the number of bytes read, or -1 on error. + filename="gio/gpollableutils.c" + line="183">the number of bytes read, or -1 on error. a #GInputStream + filename="gio/gpollableutils.c" + line="165">a #GInputStream a buffer to + filename="gio/gpollableutils.c" + line="166">a buffer to read data into @@ -135769,14 +140955,14 @@ returns %TRUE, or else the behavior is undefined. If @blocking is the number of bytes to read + filename="gio/gpollableutils.c" + line="168">the number of bytes to read whether to do blocking I/O + filename="gio/gpollableutils.c" + line="169">whether to do blocking I/O optional #GCancellable object, %NULL to ignore. + filename="gio/gpollableutils.c" + line="170">optional #GCancellable object, %NULL to ignore. @@ -135795,8 +140981,8 @@ returns %TRUE, or else the behavior is undefined. If @blocking is version="2.34" throws="1"> Tries to write to @stream, as with g_output_stream_write() (if + filename="gio/gpollableutils.c" + line="209">Tries to write to @stream, as with g_output_stream_write() (if @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking() (if @blocking is %FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method. @@ -135806,24 +140992,24 @@ If @blocking is %FALSE, then @stream must be a g_pollable_output_stream_can_poll() returns %TRUE or else the behavior is undefined. If @blocking is %TRUE, then @stream does not need to be a #GPollableOutputStream. - + the number of bytes written, or -1 on error. + filename="gio/gpollableutils.c" + line="230">the number of bytes written, or -1 on error. a #GOutputStream. + filename="gio/gpollableutils.c" + line="211">a #GOutputStream. the buffer + filename="gio/gpollableutils.c" + line="212">the buffer containing the data to write. @@ -135831,14 +141017,14 @@ need to be a #GPollableOutputStream. the number of bytes to write + filename="gio/gpollableutils.c" + line="214">the number of bytes to write whether to do blocking I/O + filename="gio/gpollableutils.c" + line="215">whether to do blocking I/O nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gpollableutils.c" + line="216">optional #GCancellable object, %NULL to ignore. @@ -135857,8 +141043,8 @@ need to be a #GPollableOutputStream. version="2.34" throws="1"> Tries to write @count bytes to @stream, as with + filename="gio/gpollableutils.c" + line="256">Tries to write @count bytes to @stream, as with g_output_stream_write_all(), but using g_pollable_stream_write() rather than g_output_stream_write(). @@ -135876,24 +141062,24 @@ As with g_pollable_stream_write(), if @blocking is %FALSE, then g_pollable_output_stream_can_poll() returns %TRUE or else the behavior is undefined. If @blocking is %TRUE, then @stream does not need to be a #GPollableOutputStream. - + %TRUE on success, %FALSE if there was an error + filename="gio/gpollableutils.c" + line="287">%TRUE on success, %FALSE if there was an error a #GOutputStream. + filename="gio/gpollableutils.c" + line="258">a #GOutputStream. the buffer + filename="gio/gpollableutils.c" + line="259">the buffer containing the data to write. @@ -135901,14 +141087,14 @@ need to be a #GPollableOutputStream. the number of bytes to write + filename="gio/gpollableutils.c" + line="261">the number of bytes to write whether to do blocking I/O + filename="gio/gpollableutils.c" + line="262">whether to do blocking I/O caller-allocates="0" transfer-ownership="full"> location to store the number of bytes that was + filename="gio/gpollableutils.c" + line="263">location to store the number of bytes that was written to the stream @@ -135926,8 +141112,8 @@ need to be a #GPollableOutputStream. nullable="1" allow-none="1"> optional #GCancellable object, %NULL to ignore. + filename="gio/gpollableutils.c" + line="265">optional #GCancellable object, %NULL to ignore. @@ -135937,13 +141123,13 @@ need to be a #GPollableOutputStream. moved-to="PowerProfileMonitor.dup_default" version="2.70"> Gets a reference to the default #GPowerProfileMonitor for the system. - + filename="gio/gpowerprofilemonitor.c" + line="78">Gets a reference to the default #GPowerProfileMonitor for the system. + a new reference to the default #GPowerProfileMonitor + filename="gio/gpowerprofilemonitor.c" + line="83">a new reference to the default #GPowerProfileMonitor @@ -135952,22 +141138,22 @@ need to be a #GPollableOutputStream. moved-to="Proxy.get_default_for_protocol" version="2.26"> Find the `gio-proxy` extension point for a proxy implementation that supports + filename="gio/gproxy.c" + line="51">Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. - + return a #GProxy or NULL if protocol + filename="gio/gproxy.c" + line="58">return a #GProxy or NULL if protocol is not supported. the proxy protocol name (e.g. http, socks, etc) + filename="gio/gproxy.c" + line="53">the proxy protocol name (e.g. http, socks, etc) @@ -135977,13 +141163,13 @@ the specified protocol. moved-to="ProxyResolver.get_default" version="2.26"> Gets the default #GProxyResolver for the system. - + filename="gio/gproxyresolver.c" + line="75">Gets the default #GProxyResolver for the system. + the default #GProxyResolver, which + filename="gio/gproxyresolver.c" + line="80">the default #GProxyResolver, which will be a dummy object if no proxy resolver is available @@ -135993,12 +141179,12 @@ the specified protocol. moved-to="ResolverError.quark" version="2.22"> Gets the #GResolver Error Quark. + filename="gio/gresolver.c" + line="1360">Gets the #GResolver Error Quark. a #GQuark. + filename="gio/gresolver.c" + line="1365">a #GQuark. @@ -136007,12 +141193,12 @@ the specified protocol. moved-to="ResourceError.quark" version="2.32"> Gets the #GResource Error Quark. + filename="gio/gresource.c" + line="509">Gets the [struct@Gio.Resource] Error Quark. a #GQuark + filename="gio/gresource.c" + line="514">a [type@GLib.Quark] @@ -136022,29 +141208,29 @@ the specified protocol. version="2.32" throws="1"> Loads a binary resource bundle and creates a #GResource representation of it, allowing -you to query it for data. + filename="gio/gresource.c" + line="644">Loads a binary resource bundle and creates a [struct@Gio.Resource] +representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). +to register it with [func@Gio.resources_register]. If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or -there is an error in reading it, an error from g_mapped_file_new() will be -returned. - +there is an error in reading it, an error from [ctor@GLib.MappedFile.new] +will be returned. + a new #GResource, or %NULL on error + filename="gio/gresource.c" + line="660">a new [struct@Gio.Resource], or `NULL` on error the path of a filename to load, in the GLib filename encoding + filename="gio/gresource.c" + line="646">the path of a filename to load, in the GLib filename encoding @@ -136054,18 +141240,19 @@ returned. version="2.32" throws="1"> Returns all the names of children at the specified @path in the set of + filename="gio/gresource.c" + line="1286">Returns all the names of children at the specified @path in the set of globally registered resources. -The return result is a %NULL terminated list of strings which should -be released with g_strfreev(). + +The return result is a `NULL` terminated list of strings which should +be released with [func@GLib.strfreev]. @lookup_flags controls the behaviour of the lookup. - + an array of constant strings + filename="gio/gresource.c" + line="1300">an array of constant strings @@ -136073,14 +141260,14 @@ be released with g_strfreev(). A pathname inside the resource + filename="gio/gresource.c" + line="1288">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="1289">A [flags@Gio.ResourceLookupFlags] @@ -136090,29 +141277,29 @@ be released with g_strfreev(). version="2.32" throws="1"> Looks for a file at the specified @path in the set of + filename="gio/gresource.c" + line="1397">Looks for a file at the specified @path in the set of globally registered resources and if found returns information about it. @lookup_flags controls the behaviour of the lookup. - + %TRUE if the file was found. %FALSE if there were errors + filename="gio/gresource.c" + line="1412">`TRUE` if the file was found, `FALSE` if there were errors A pathname inside the resource + filename="gio/gresource.c" + line="1399">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="1400">A [flags@Gio.ResourceLookupFlags] a location to place the length of the contents of the file, - or %NULL if the length is not needed + filename="gio/gresource.c" + line="1401">a location to place the length of the contents of the file, + or `NULL` if the length is not needed a location to place the #GResourceFlags about the file, - or %NULL if the flags are not needed + filename="gio/gresource.c" + line="1403">a location to place the [flags@Gio.ResourceFlags] about the file, + or `NULL` if the flags are not needed + + Returns whether the specified @path in the set of +globally registered resources has children. + + + %TRUE if @patch has children + + + + + A pathname + + + + Looks for a file at the specified @path in the set of -globally registered resources and returns a #GBytes that + filename="gio/gresource.c" + line="1221">Looks for a file at the specified @path in the set of +globally registered resources and returns a [struct@GLib.Bytes] that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte -is not included in the size of the GBytes. +is not included in the size of the [struct@GLib.Bytes]. For uncompressed resource files this is a pointer directly into -the resource bundle, which is typically in some readonly data section +the resource bundle, which is typically in some read-only data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data. @lookup_flags controls the behaviour of the lookup. - + #GBytes or %NULL on error. - Free the returned object with g_bytes_unref() + filename="gio/gresource.c" + line="1242">[struct@GLib.Bytes] or `NULL` on error A pathname inside the resource + filename="gio/gresource.c" + line="1223">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="1224">A [flags@Gio.ResourceLookupFlags] @@ -136189,31 +141398,30 @@ the heap and automatically uncompress the data. version="2.32" throws="1"> Looks for a file at the specified @path in the set of -globally registered resources and returns a #GInputStream + filename="gio/gresource.c" + line="1164">Looks for a file at the specified @path in the set of +globally registered resources and returns a [class@Gio.InputStream] that lets you read the data. @lookup_flags controls the behaviour of the lookup. - + #GInputStream or %NULL on error. - Free the returned object with g_object_unref() + filename="gio/gresource.c" + line="1176">[class@Gio.InputStream] or `NULL` on error A pathname inside the resource + filename="gio/gresource.c" + line="1166">A path name inside the resource A #GResourceLookupFlags + filename="gio/gresource.c" + line="1167">A [flags@Gio.ResourceLookupFlags] @@ -136222,19 +141430,21 @@ that lets you read the data. c:identifier="g_resources_register" version="2.32"> Registers the resource with the process-global set of resources. + filename="gio/gresource.c" + line="1128">Registers the resource with the process-global set of resources. + Once a resource is registered the files in it can be accessed -with the global resource lookup functions like g_resources_lookup_data(). - +with the global resource lookup functions like +[func@Gio.resources_lookup_data]. + A #GResource + filename="gio/gresource.c" + line="1130">A [struct@Gio.Resource] @@ -136243,17 +141453,17 @@ with the global resource lookup functions like g_resources_lookup_data(). c:identifier="g_resources_unregister" version="2.32"> Unregisters the resource from the process-global set of resources. - + filename="gio/gresource.c" + line="1148">Unregisters the resource from the process-global set of resources. + A #GResource + filename="gio/gresource.c" + line="1150">A [struct@Gio.Resource] @@ -136263,8 +141473,8 @@ with the global resource lookup functions like g_resources_lookup_data(). moved-to="SettingsSchemaSource.get_default" version="2.32"> Gets the default system schema source. + filename="gio/gsettingsschema.c" + line="376">Gets the default system schema source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who @@ -136277,11 +141487,11 @@ from different directories, depending on which directories were given in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all lookups performed against the default source should probably be done recursively. - + the default schema source + filename="gio/gsettingsschema.c" + line="393">the default schema source @@ -136291,12 +141501,12 @@ recursively. deprecated="1" deprecated-version="2.46"> Reports an error in an asynchronous function in an idle function by + filename="gio/gsimpleasyncresult.c" + line="1005">Reports an error in an asynchronous function in an idle function by directly setting the contents of the #GAsyncResult with the given error information. Use g_task_report_error(). - + @@ -136306,8 +141516,8 @@ information. nullable="1" allow-none="1"> a #GObject, or %NULL. + filename="gio/gsimpleasyncresult.c" + line="1007">a #GObject, or %NULL. scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="1008">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="1009">user data passed to @callback. a #GQuark containing the error domain (usually %G_IO_ERROR). + filename="gio/gsimpleasyncresult.c" + line="1010">a #GQuark containing the error domain (usually %G_IO_ERROR). a specific error code. + filename="gio/gsimpleasyncresult.c" + line="1011">a specific error code. a formatted error reporting string. + filename="gio/gsimpleasyncresult.c" + line="1012">a formatted error reporting string. a list of variables to fill in @format. + filename="gio/gsimpleasyncresult.c" + line="1013">a list of variables to fill in @format. @@ -136361,12 +141571,12 @@ information. deprecated="1" deprecated-version="2.46"> Reports an error in an idle function. Similar to + filename="gio/gsimpleasyncresult.c" + line="1048">Reports an error in an idle function. Similar to g_simple_async_report_error_in_idle(), but takes a #GError rather than building a new one. Use g_task_report_error(). - + @@ -136376,8 +141586,8 @@ than building a new one. nullable="1" allow-none="1"> a #GObject, or %NULL + filename="gio/gsimpleasyncresult.c" + line="1050">a #GObject, or %NULL scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="1051">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="1052">user data passed to @callback. the #GError to report + filename="gio/gsimpleasyncresult.c" + line="1053">the #GError to report @@ -136415,12 +141625,12 @@ than building a new one. deprecated="1" deprecated-version="2.46"> Reports an error in an idle function. Similar to + filename="gio/gsimpleasyncresult.c" + line="1080">Reports an error in an idle function. Similar to g_simple_async_report_gerror_in_idle(), but takes over the caller's ownership of @error, so the caller does not have to free it any more. Use g_task_report_error(). - + @@ -136430,8 +141640,8 @@ ownership of @error, so the caller does not have to free it any more. nullable="1" allow-none="1"> a #GObject, or %NULL + filename="gio/gsimpleasyncresult.c" + line="1082">a #GObject, or %NULL scope="async" closure="2"> a #GAsyncReadyCallback. + filename="gio/gsimpleasyncresult.c" + line="1083">a #GAsyncReadyCallback. nullable="1" allow-none="1"> user data passed to @callback. + filename="gio/gsimpleasyncresult.c" + line="1084">user data passed to @callback. the #GError to report + filename="gio/gsimpleasyncresult.c" + line="1085">the #GError to report @@ -136468,13 +141678,13 @@ ownership of @error, so the caller does not have to free it any more. version="2.22" introspectable="0"> Sorts @targets in place according to the algorithm in RFC 2782. - + filename="gio/gsrvtarget.c" + line="218">Sorts @targets in place according to the algorithm in RFC 2782. + the head of the sorted list. + filename="gio/gsrvtarget.c" + line="224">the head of the sorted list. @@ -136482,8 +141692,8 @@ ownership of @error, so the caller does not have to free it any more. a #GList of #GSrvTarget + filename="gio/gsrvtarget.c" + line="220">a #GList of #GSrvTarget @@ -136495,13 +141705,13 @@ ownership of @error, so the caller does not have to free it any more. moved-to="TlsBackend.get_default" version="2.28"> Gets the default #GTlsBackend for the system. - + filename="gio/gtlsbackend.c" + line="53">Gets the default #GTlsBackend for the system. + a #GTlsBackend, which will be a + filename="gio/gtlsbackend.c" + line="58">a #GTlsBackend, which will be a dummy object if no TLS backend is available @@ -136511,12 +141721,12 @@ ownership of @error, so the caller does not have to free it any more. moved-to="TlsChannelBindingError.quark" version="2.66"> Gets the TLS channel binding error quark. + filename="gio/gtlsconnection.c" + line="868">Gets the TLS channel binding error quark. a #GQuark. + filename="gio/gtlsconnection.c" + line="873">a #GQuark. @@ -136526,27 +141736,27 @@ ownership of @error, so the caller does not have to free it any more. version="2.28" throws="1"> Creates a new #GTlsClientConnection wrapping @base_io_stream (which + filename="gio/gtlsclientconnection.c" + line="144">Creates a new #GTlsClientConnection wrapping @base_io_stream (which must have pollable input and output streams) which is assumed to communicate with the server identified by @server_identity. See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. - + the new + filename="gio/gtlsclientconnection.c" + line="158">the new #GTlsClientConnection, or %NULL on error the #GIOStream to wrap + filename="gio/gtlsclientconnection.c" + line="146">the #GIOStream to wrap nullable="1" allow-none="1"> the expected identity of the server + filename="gio/gtlsclientconnection.c" + line="147">the expected identity of the server @@ -136565,12 +141775,12 @@ this function has returned. moved-to="TlsError.quark" version="2.28"> Gets the TLS error quark. + filename="gio/gtlsconnection.c" + line="1094">Gets the TLS error quark. a #GQuark. + filename="gio/gtlsconnection.c" + line="1099">a #GQuark. @@ -136580,24 +141790,24 @@ this function has returned. version="2.30" throws="1"> Creates a new #GTlsFileDatabase which uses anchor certificate authorities + filename="gio/gtlsfiledatabase.c" + line="65">Creates a new #GTlsFileDatabase which uses anchor certificate authorities in @anchors to verify certificate chains. The certificates in @anchors must be PEM encoded. - + the new + filename="gio/gtlsfiledatabase.c" + line="75">the new #GTlsFileDatabase, or %NULL on error filename of anchor certificate authorities. + filename="gio/gtlsfiledatabase.c" + line="67">filename of anchor certificate authorities. @@ -136608,26 +141818,26 @@ The certificates in @anchors must be PEM encoded. version="2.28" throws="1"> Creates a new #GTlsServerConnection wrapping @base_io_stream (which + filename="gio/gtlsserverconnection.c" + line="63">Creates a new #GTlsServerConnection wrapping @base_io_stream (which must have pollable input and output streams). See the documentation for #GTlsConnection:base-io-stream for restrictions on when application code can run operations on the @base_io_stream after this function has returned. - + the new + filename="gio/gtlsserverconnection.c" + line="76">the new #GTlsServerConnection, or %NULL on error the #GIOStream to wrap + filename="gio/gtlsserverconnection.c" + line="65">the #GIOStream to wrap nullable="1" allow-none="1"> the default server certificate, or %NULL + filename="gio/gtlsserverconnection.c" + line="66">the default server certificate, or %NULL @@ -136644,24 +141854,26 @@ this function has returned. Determines if @mount_path is considered an implementation of the -OS. This is primarily used for hiding mountable and mounted volumes + filename="gio/gunixmounts.c" + line="270">Determines if @mount_path is considered an implementation of the +OS. + +This is primarily used for hiding mountable and mounted volumes that only are used in the OS and has little to no relevance to the casual user. - + %TRUE if @mount_path is considered an implementation detail - of the OS. + filename="gio/gunixmounts.c" + line="281">true if @mount_path is considered an implementation detail + of the OS; false otherwise a mount path, e.g. `/media/disk` or `/usr` + filename="gio/gunixmounts.c" + line="272">a mount path, e.g. `/media/disk` or `/usr` @@ -136670,27 +141882,29 @@ casual user. c:identifier="g_unix_is_system_device_path" version="2.56"> Determines if @device_path is considered a block device path which is only -used in implementation of the OS. This is primarily used for hiding -mounted volumes that are intended as APIs for programs to read, and system -administrators at a shell; rather than something that should, for example, -appear in a GUI. For example, the Linux `/proc` filesystem. + filename="gio/gunixmounts.c" + line="422">Determines if @device_path is considered a block device path which is only +used in implementation of the OS. + +This is primarily used for hiding mounted volumes that are intended as APIs +for programs to read, and system administrators at a shell; rather than +something that should, for example, appear in a GUI. For example, the Linux +`/proc` filesystem. The list of device paths considered ‘system’ ones may change over time. - + %TRUE if @device_path is considered an implementation detail of - the OS. + filename="gio/gunixmounts.c" + line="436">true if @device_path is considered an implementation detail of + the OS; false otherwise a device path, e.g. `/dev/loop0` or `nfsd` + filename="gio/gunixmounts.c" + line="424">a device path, e.g. `/dev/loop0` or `nfsd` @@ -136699,53 +141913,62 @@ The list of device paths considered ‘system’ ones may change over time. Determines if @fs_type is considered a type of file system which is only -used in implementation of the OS. This is primarily used for hiding -mounted volumes that are intended as APIs for programs to read, and system -administrators at a shell; rather than something that should, for example, -appear in a GUI. For example, the Linux `/proc` filesystem. + filename="gio/gunixmounts.c" + line="350">Determines if @fs_type is considered a type of file system which is only +used in implementation of the OS. + +This is primarily used for hiding mounted volumes that are intended as APIs +for programs to read, and system administrators at a shell; rather than +something that should, for example, appear in a GUI. For example, the Linux +`/proc` filesystem. The list of file system types considered ‘system’ ones may change over time. - + %TRUE if @fs_type is considered an implementation detail of the OS. + filename="gio/gunixmounts.c" + line="364">true if @fs_type is considered an implementation detail of the OS; + false otherwise a file system type, e.g. `procfs` or `tmpfs` + filename="gio/gunixmounts.c" + line="352">a file system type, e.g. `procfs` or `tmpfs` - + Gets a #GUnixMountEntry for a given mount path. If @time_read -is set, it will be filled with a unix timestamp for checking -if the mounts have changed since with g_unix_mounts_changed_since(). + filename="gio/gunixmounts.c" + line="1924">Gets a [struct@GioUnix.MountEntry] for a given mount path. + +If @time_read is set, it will be filled with a Unix timestamp for checking +if the mounts have changed since with +[func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. -This will return %NULL if there is no mount point at @mount_path. - +This will return `NULL` if there is no mount point at @mount_path. + Use [func@GioUnix.MountEntry.at] instead. + a #GUnixMountEntry. + filename="gio/gunixmounts.c" + line="1940">a [struct@GioUnix.MountEntry] path for a possible unix mount. + filename="gio/gunixmounts.c" + line="1926">path for a possible Unix mount optional="1" allow-none="1"> guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="1927">return location for a timestamp - + Compares two unix mounts. - + filename="gio/gunixmounts.c" + line="2843">Compares two Unix mounts. + Use [func@GioUnix.MountEntry.compare] instead. + 1, 0 or -1 if @mount1 is greater than, equal to, -or less than @mount2, respectively. + filename="gio/gunixmounts.c" + line="2850">`1`, `0` or `-1` if @mount1 is greater than, equal to, + or less than @mount2, respectively first #GUnixMountEntry to compare. + filename="gio/gunixmounts.c" + line="2845">first [struct@GioUnix.MountEntry] to compare second #GUnixMountEntry to compare. + filename="gio/gunixmounts.c" + line="2846">second [struct@GioUnix.MountEntry] to compare + version="2.54" + deprecated="1" + deprecated-version="2.84"> Makes a copy of @mount_entry. - + filename="gio/gunixmounts.c" + line="2753">Makes a copy of @mount_entry. + Use [func@GioUnix.MountEntry.copy] instead. + a new #GUnixMountEntry + filename="gio/gunixmounts.c" + line="2759">a new [struct@GioUnix.MountEntry] a #GUnixMountEntry. + filename="gio/gunixmounts.c" + line="2755">a [struct@GioUnix.MountEntry] + + Checks if the Unix mounts have changed since a given Unix time. + +This can only work reliably if a [class@GioUnix.MountMonitor] is running in +the process, otherwise changes in the mount entries file (such as +`/proc/self/mountinfo` on Linux) cannot be detected and, as a result, this +function has to conservatively always return `TRUE`. + +It is more efficient to use [signal@GioUnix.MountMonitor::mounts-changed] to +be signalled of changes to the mount entries, rather than polling using this +function. This function is more appropriate for infrequently determining +cache validity. + + + true if the mounts have changed since @time; false otherwise +Since 2.84 + + + + + a timestamp + + + + + + Gets a list of [struct@GioUnix.MountEntry] instances representing the Unix +mounts. + +If @time_read is set, it will be filled with the mount timestamp, allowing +for checking if the mounts have changed with +[func@GioUnix.mount_entries_changed_since]. + + + a list of the + Unix mounts + + + + + + + return location for a timestamp + + + + + + Gets an array of [struct@Gio.UnixMountEntry]s containing the Unix mounts +listed in @table_path. + +This is a generalized version of [func@GioUnix.mount_entries_get], mainly +intended for internal testing use. Note that [func@GioUnix.mount_entries_get] +may parse multiple hierarchical table files, so this function is not a direct +superset of its functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + + + mount + entries, or `NULL` if there was an error loading them + + + + + + + path to the mounts table file (for example `/proc/self/mountinfo`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount entries returned + + + + + + Gets a [struct@GioUnix.MountEntry] for a given mount path. + +If @time_read is set, it will be filled with a Unix timestamp for checking +if the mounts have changed since with +[func@GioUnix.mount_entries_changed_since]. + +If more mounts have the same mount path, the last matching mount +is returned. + +This will return `NULL` if there is no mount point at @mount_path. + + + a [struct@GioUnix.MountEntry] + + + + + path for a possible Unix mount + + + + return location for a timestamp + + + + + + Gets a [struct@GioUnix.MountEntry] for a given file path. + +If @time_read is set, it will be filled with a Unix timestamp for checking +if the mounts have changed since with +[func@GioUnix.mount_entries_changed_since]. + +If more mounts have the same mount path, the last matching mount +is returned. + +This will return `NULL` if looking up the mount entry fails, if +@file_path doesn’t exist or there is an I/O error. + + + a [struct@GioUnix.MountEntry] + + + + + file path on some Unix mount + + + + return location for a timestamp + + + + + version="2.52" + deprecated="1" + deprecated-version="2.84"> Gets a #GUnixMountEntry for a given file path. If @time_read -is set, it will be filled with a unix timestamp for checking -if the mounts have changed since with g_unix_mounts_changed_since(). + filename="gio/gunixmounts.c" + line="1998">Gets a [struct@GioUnix.MountEntry] for a given file path. + +If @time_read is set, it will be filled with a Unix timestamp for checking +if the mounts have changed since with +[func@GioUnix.mount_entries_changed_since]. If more mounts have the same mount path, the last matching mount is returned. -This will return %NULL if looking up the mount entry fails, if +This will return `NULL` if looking up the mount entry fails, if @file_path doesn’t exist or there is an I/O error. - + Use [func@GioUnix.MountEntry.for] instead. + a #GUnixMountEntry. + filename="gio/gunixmounts.c" + line="2015">a [struct@GioUnix.MountEntry] file path on some unix mount. + filename="gio/gunixmounts.c" + line="2000">file path on some Unix mount guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="2001">return location for a timestamp - + Frees a unix mount. - + filename="gio/gunixmounts.c" + line="2718">Frees a Unix mount. + Use [func@GioUnix.MountEntry.free] instead. + a #GUnixMountEntry. + filename="gio/gunixmounts.c" + line="2720">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_get_device_path" + deprecated="1" + deprecated-version="2.84"> Gets the device path for a unix mount. - + filename="gio/gunixmounts.c" + line="2939">Gets the device path for a Unix mount. + Use [func@GioUnix.MountEntry.get_device_path] instead. + a string containing the device path. + filename="gio/gunixmounts.c" + line="2945">a string containing the device path a #GUnixMount. + filename="gio/gunixmounts.c" + line="2941">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_get_fs_type" + deprecated="1" + deprecated-version="2.84"> Gets the filesystem type for the unix mount. - + filename="gio/gunixmounts.c" + line="3014">Gets the filesystem type for the Unix mount. + Use [func@GioUnix.MountEntry.get_fs_type] instead. + a string containing the file system type. + filename="gio/gunixmounts.c" + line="3020">a string containing the file system type a #GUnixMount. + filename="gio/gunixmounts.c" + line="3016">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_get_mount_path" + deprecated="1" + deprecated-version="2.84"> Gets the mount path for a unix mount. - + filename="gio/gunixmounts.c" + line="2907">Gets the mount path for a Unix mount. + Use [func@GioUnix.MountEntry.get_mount_path] instead. + the mount path for @mount_entry. + filename="gio/gunixmounts.c" + line="2913">the mount path for @mount_entry input #GUnixMountEntry to get the mount path for. + filename="gio/gunixmounts.c" + line="2909">a [struct@GioUnix.MountEntry] to get the mount path for + version="2.58" + deprecated="1" + deprecated-version="2.84"> Gets a comma-separated list of mount options for the unix mount. For example, -`rw,relatime,seclabel,data=ordered`. + filename="gio/gunixmounts.c" + line="3046">Gets a comma separated list of mount options for the Unix mount. + +For example: `rw,relatime,seclabel,data=ordered`. -This is similar to g_unix_mount_point_get_options(), but it takes -a #GUnixMountEntry as an argument. - +This is similar to [func@GioUnix.MountPoint.get_options], but it takes +a [struct@GioUnix.MountEntry] as an argument. + Use [func@GioUnix.MountEntry.get_options] instead. + a string containing the options, or %NULL if not -available. + filename="gio/gunixmounts.c" + line="3057">a string containing the options, or `NULL` if not + available. a #GUnixMountEntry. + filename="gio/gunixmounts.c" + line="3048">a [struct@GioUnix.MountEntry] + version="2.60" + deprecated="1" + deprecated-version="2.84"> Gets the root of the mount within the filesystem. This is useful e.g. for + filename="gio/gunixmounts.c" + line="2971">Gets the root of the mount within the filesystem. This is useful e.g. for mounts created by bind operation, or btrfs subvolumes. -For example, the root path is equal to "/" for mount created by -"mount /dev/sda1 /mnt/foo" and "/bar" for -"mount --bind /mnt/foo/bar /mnt/bar". - +For example, the root path is equal to `/` for a mount created by +`mount /dev/sda1 /mnt/foo` and `/bar` for +`mount --bind /mnt/foo/bar /mnt/bar`. + Use [func@GioUnix.MountEntry.get_root_path] instead. + a string containing the root, or %NULL if not supported. + filename="gio/gunixmounts.c" + line="2982">a string containing the root, or `NULL` if not supported a #GUnixMountEntry. + filename="gio/gunixmounts.c" + line="2973">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_guess_can_eject" + deprecated="1" + deprecated-version="2.84"> Guesses whether a Unix mount can be ejected. - + filename="gio/gunixmounts.c" + line="3674">Guesses whether a Unix mount entry can be ejected. + Use [func@GioUnix.MountEntry.guess_can_eject] instead. + %TRUE if @mount_entry is deemed to be ejectable. + filename="gio/gunixmounts.c" + line="3680">true if @mount_entry is deemed to be ejectable; false otherwise a #GUnixMountEntry + filename="gio/gunixmounts.c" + line="3676">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_guess_icon" + deprecated="1" + deprecated-version="2.84"> Guesses the icon of a Unix mount. - + filename="gio/gunixmounts.c" + line="3561">Guesses the icon of a Unix mount entry. + Use [func@GioUnix.MountEntry.guess_icon] instead. + a #GIcon + filename="gio/gunixmounts.c" + line="3567">a [iface@Gio.Icon] a #GUnixMountEntry + filename="gio/gunixmounts.c" + line="3563">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_guess_name" + deprecated="1" + deprecated-version="2.84"> Guesses the name of a Unix mount. + filename="gio/gunixmounts.c" + line="3520">Guesses the name of a Unix mount entry. + The result is a translated string. - + Use [func@GioUnix.MountEntry.guess_name] instead. + A newly allocated string that must - be freed with g_free() + filename="gio/gunixmounts.c" + line="3528">a newly allocated translated string a #GUnixMountEntry + filename="gio/gunixmounts.c" + line="3522">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_guess_should_display" + deprecated="1" + deprecated-version="2.84"> Guesses whether a Unix mount should be displayed in the UI. - + filename="gio/gunixmounts.c" + line="3711">Guesses whether a Unix mount entry should be displayed in the UI. + Use [func@GioUnix.MountEntry.guess_should_display] instead. + %TRUE if @mount_entry is deemed to be displayable. + filename="gio/gunixmounts.c" + line="3717">true if @mount_entry is deemed to be displayable; false otherwise a #GUnixMountEntry + filename="gio/gunixmounts.c" + line="3713">a [struct@GioUnix.MountEntry] + version="2.34" + deprecated="1" + deprecated-version="2.84"> Guesses the symbolic icon of a Unix mount. - + filename="gio/gunixmounts.c" + line="3591">Guesses the symbolic icon of a Unix mount entry. + Use [func@GioUnix.MountEntry.guess_symbolic_icon] instead. + a #GIcon + filename="gio/gunixmounts.c" + line="3597">a [iface@Gio.Icon] a #GUnixMountEntry + filename="gio/gunixmounts.c" + line="3593">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_is_readonly" + deprecated="1" + deprecated-version="2.84"> Checks if a unix mount is mounted read only. - + filename="gio/gunixmounts.c" + line="3091">Checks if a Unix mount is mounted read only. + Use [func@GioUnix.MountEntry.is_readonly] instead. + %TRUE if @mount_entry is read only. + filename="gio/gunixmounts.c" + line="3097">true if @mount_entry is read only; false otherwise a #GUnixMount. + filename="gio/gunixmounts.c" + line="3093">a [struct@GioUnix.MountEntry] + c:identifier="g_unix_mount_is_system_internal" + deprecated="1" + deprecated-version="2.84"> Checks if a Unix mount is a system mount. This is the Boolean OR of -g_unix_is_system_fs_type(), g_unix_is_system_device_path() and -g_unix_is_mount_path_system_internal() on @mount_entry’s properties. + filename="gio/gunixmounts.c" + line="3123">Checks if a Unix mount is a system mount. + +This is the Boolean OR of +[func@GioUnix.is_system_fs_type], [func@GioUnix.is_system_device_path] and +[func@GioUnix.is_mount_path_system_internal] on @mount_entry’s properties. The definition of what a ‘system’ mount entry is may change over time as new file system types and device paths are ignored. - + Use [func@GioUnix.MountEntry.is_system_internal] instead. + %TRUE if the unix mount is for a system path. + filename="gio/gunixmounts.c" + line="3136">true if the Unix mount is for a system path; false otherwise a #GUnixMount. + filename="gio/gunixmounts.c" + line="3125">a [struct@GioUnix.MountEntry] @@ -137145,26 +142635,28 @@ file system types and device paths are ignored. moved-to="UnixMountPoint.at" version="2.66"> Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it -will be filled with a unix timestamp for checking if the mount points have -changed since with g_unix_mount_points_changed_since(). + filename="gio/gunixmounts.c" + line="2151">Gets a [struct@GioUnix.MountPoint] for a given mount path. + +If @time_read is set, it will be filled with a Unix timestamp for checking if +the mount points have changed since with +[func@GioUnix.mount_points_changed_since]. If more mount points have the same mount path, the last matching mount point is returned. - + a #GUnixMountPoint, or %NULL if no match -is found. + filename="gio/gunixmounts.c" + line="2165">a [struct@GioUnix.MountPoint], or `NULL` + if no match is found path for a possible unix mount point. + filename="gio/gunixmounts.c" + line="2153">path for a possible Unix mount point optional="1" allow-none="1"> guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="2154">return location for a timestamp @@ -137183,20 +142675,30 @@ is found. Checks if the unix mount points have changed since a given unix time. - + filename="gio/gunixmounts.c" + line="2238">Checks if the Unix mount points have changed since a given Unix time. + +Unlike [func@GioUnix.mount_entries_changed_since], this function can work +reliably without a [class@GioUnix.MountMonitor] running, as it accesses the +static mount point information (such as `/etc/fstab` on Linux), which has a +valid modification time. + +It is more efficient to use [signal@GioUnix.MountMonitor::mountpoints-changed] +to be signalled of changes to the mount points, rather than polling using +this function. This function is more appropriate for infrequently determining +cache validity. + %TRUE if the mount points have changed since @time. + filename="gio/gunixmounts.c" + line="2254">true if the mount points have changed since @time; false otherwise guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="2240">a timestamp @@ -137204,17 +142706,19 @@ is found. Gets a #GList of #GUnixMountPoint containing the unix mount points. -If @time_read is set, it will be filled with the mount timestamp, -allowing for checking if the mounts have changed with -g_unix_mount_points_changed_since(). - + filename="gio/gunixmounts.c" + line="2078">Gets a list of [struct@GioUnix.MountPoint] instances representing the Unix +mount points. + +If @time_read is set, it will be filled with the mount timestamp, allowing +for checking if the mounts have changed with +[func@GioUnix.mount_points_changed_since]. + - a #GList of the UNIX mountpoints. + filename="gio/gunixmounts.c" + line="2089">a list of the Unix + mount points @@ -137227,46 +142731,113 @@ g_unix_mount_points_changed_since(). optional="1" allow-none="1"> guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="2080">return location for a timestamp + + Gets an array of [struct@Gio.UnixMountPoint]s containing the Unix mount +points listed in @table_path. + +This is a generalized version of [func@GioUnix.mount_points_get], mainly +intended for internal testing use. Note that [func@GioUnix.mount_points_get] +may parse multiple hierarchical table files, so this function is not a direct +superset of its functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + + + mount + points, or `NULL` if there was an error loading them + + + + + + + path to the mount points table file (for example `/etc/fstab`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount points returned + + + + + c:identifier="g_unix_mounts_changed_since" + deprecated="1" + deprecated-version="2.84"> Checks if the unix mounts have changed since a given unix time. - + filename="gio/gunixmounts.c" + line="2198">Checks if the Unix mounts have changed since a given Unix time. + Use [func@GioUnix.mount_entries_changed_since] instead. + %TRUE if the mounts have changed since @time. + filename="gio/gunixmounts.c" + line="2204">true if the mounts have changed since @time; false otherwise guint64 to contain a timestamp. + filename="gio/gunixmounts.c" + line="2200">a timestamp - - Gets a #GList of #GUnixMountEntry containing the unix mounts. -If @time_read is set, it will be filled with the mount -timestamp, allowing for checking if the mounts have changed -with g_unix_mounts_changed_since(). - + + Gets a list of [struct@GioUnix.MountEntry] instances representing the Unix +mounts. + +If @time_read is set, it will be filled with the mount timestamp, allowing +for checking if the mounts have changed with +[func@GioUnix.mount_entries_changed_since]. + Use [func@GioUnix.mount_entries_get] instead. + - a #GList of the UNIX mounts. + filename="gio/gunixmounts.c" + line="1827">a list of the + Unix mounts @@ -137279,11 +142850,72 @@ with g_unix_mounts_changed_since(). optional="1" allow-none="1"> guint64 to contain a timestamp, or %NULL + filename="gio/gunixmounts.c" + line="1818">return location for a timestamp + + Gets an array of [struct@Gio.UnixMountEntry]s containing the Unix mounts +listed in @table_path. + +This is a generalized version of [func@GioUnix.mount_entries_get], mainly +intended for internal testing use. Note that [func@GioUnix.mount_entries_get] +may parse multiple hierarchical table files, so this function is not a direct +superset of its functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + Use [func@GioUnix.mount_entries_get_from_file] instead. + + + mount + entries, or `NULL` if there was an error loading them + + + + + + + path to the mounts table file (for example `/proc/self/mountinfo`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount entries returned + + + + diff --git a/generator/src/main/resources/gir/Gsk-4.0.gir b/generator/src/main/resources/gir/Gsk-4.0.gir index aac6ec8..66fead2 100644 --- a/generator/src/main/resources/gir/Gsk-4.0.gir +++ b/generator/src/main/resources/gir/Gsk-4.0.gir @@ -51,7 +51,7 @@ and/or use gtk-doc annotations. --> c:type="GskBlendMode"> The blend modes available for render nodes. + line="149">The blend modes available for render nodes. The implementation of each blend mode is deferred to the rendering pipeline. @@ -65,7 +65,7 @@ on blending and blend modes. glib:name="GSK_BLEND_MODE_DEFAULT"> The default blend mode, which specifies no blending + line="151">The default blend mode, which specifies no blending glib:name="GSK_BLEND_MODE_MULTIPLY"> The source color is multiplied by the destination + line="152">The source color is multiplied by the destination and replaces the destination glib:name="GSK_BLEND_MODE_SCREEN"> Multiplies the complements of the destination and source + line="154">Multiplies the complements of the destination and source color values, then complements the result. glib:name="GSK_BLEND_MODE_OVERLAY"> Multiplies or screens the colors, depending on the + line="156">Multiplies or screens the colors, depending on the destination color value. This is the inverse of hard-list glib:name="GSK_BLEND_MODE_DARKEN"> Selects the darker of the destination and source colors + line="158">Selects the darker of the destination and source colors glib:name="GSK_BLEND_MODE_LIGHTEN"> Selects the lighter of the destination and source colors + line="159">Selects the lighter of the destination and source colors glib:name="GSK_BLEND_MODE_COLOR_DODGE"> Brightens the destination color to reflect the source color + line="160">Brightens the destination color to reflect the source color glib:name="GSK_BLEND_MODE_COLOR_BURN"> Darkens the destination color to reflect the source color + line="161">Darkens the destination color to reflect the source color glib:name="GSK_BLEND_MODE_HARD_LIGHT"> Multiplies or screens the colors, depending on the source color value + line="162">Multiplies or screens the colors, depending on the source color value glib:name="GSK_BLEND_MODE_SOFT_LIGHT"> Darkens or lightens the colors, depending on the source color value + line="163">Darkens or lightens the colors, depending on the source color value glib:name="GSK_BLEND_MODE_DIFFERENCE"> Subtracts the darker of the two constituent colors from the lighter color + line="164">Subtracts the darker of the two constituent colors from the lighter color glib:name="GSK_BLEND_MODE_EXCLUSION"> Produces an effect similar to that of the difference mode but lower in contrast + line="165">Produces an effect similar to that of the difference mode but lower in contrast glib:name="GSK_BLEND_MODE_COLOR"> Creates a color with the hue and saturation of the source color and the luminosity of the destination color + line="166">Creates a color with the hue and saturation of the source color and the luminosity of the destination color glib:name="GSK_BLEND_MODE_HUE"> Creates a color with the hue of the source color and the saturation and luminosity of the destination color + line="167">Creates a color with the hue of the source color and the saturation and luminosity of the destination color glib:name="GSK_BLEND_MODE_SATURATION"> Creates a color with the saturation of the source color and the hue and luminosity of the destination color + line="168">Creates a color with the saturation of the source color and the hue and luminosity of the destination color glib:name="GSK_BLEND_MODE_LUMINOSITY"> Creates a color with the luminosity of the source color and the hue and saturation of the destination color + line="169">Creates a color with the luminosity of the source color and the hue and saturation of the destination color glib:fundamental="1"> A render node applying a blending function between its two child nodes. + line="6766">A render node applying a blending function between its two child nodes. Creates a `GskRenderNode` that will use @blend_mode to blend the @top + line="6893">Creates a `GskRenderNode` that will use @blend_mode to blend the @top node onto the @bottom node. - + A new `GskRenderNode` + line="6902">A new `GskRenderNode` The bottom node to be drawn + line="6895">The bottom node to be drawn The node to be blended onto the @bottom node + line="6896">The node to be blended onto the @bottom node The blend mode to use + line="6897">The blend mode to use @@ -253,19 +253,19 @@ node onto the @bottom node. c:identifier="gsk_blend_node_get_blend_mode"> Retrieves the blend mode used by @node. - + line="6965">Retrieves the blend mode used by @node. + the blend mode + line="6971">the blend mode a blending `GskRenderNode` + line="6967">a blending `GskRenderNode` @@ -274,19 +274,19 @@ node onto the @bottom node. c:identifier="gsk_blend_node_get_bottom_child"> Retrieves the bottom `GskRenderNode` child of the @node. - + line="6933">Retrieves the bottom `GskRenderNode` child of the @node. + the bottom child node + line="6939">the bottom child node a blending `GskRenderNode` + line="6935">a blending `GskRenderNode` @@ -294,19 +294,19 @@ node onto the @bottom node. Retrieves the top `GskRenderNode` child of the @node. - + line="6949">Retrieves the top `GskRenderNode` child of the @node. + the top child node + line="6955">the top child node a blending `GskRenderNode` + line="6951">a blending `GskRenderNode` @@ -321,29 +321,29 @@ node onto the @bottom node. glib:fundamental="1"> A render node applying a blur effect to its single child. + line="7533">A render node applying a blur effect to its single child. Creates a render node that blurs the child. - + line="7800">Creates a render node that blurs the child. + a new `GskRenderNode` + line="7807">a new `GskRenderNode` the child node to blur + line="7802">the child node to blur the blur radius. Must be positive + line="7803">the blur radius. Must be positive @@ -351,19 +351,19 @@ node onto the @bottom node. Retrieves the child `GskRenderNode` of the blur @node. - + line="7838">Retrieves the child `GskRenderNode` of the blur @node. + the blurred child node + line="7844">the blurred child node a blur `GskRenderNode` + line="7840">a blur `GskRenderNode` @@ -371,19 +371,19 @@ node onto the @bottom node. Retrieves the blur radius of the @node. - + line="7854">Retrieves the blur radius of the @node. + the blur radius + line="7860">the blur radius a blur `GskRenderNode` + line="7856">a blur `GskRenderNode` @@ -398,32 +398,32 @@ node onto the @bottom node. glib:fundamental="1"> A render node for a border. + line="2276">A render node for a border. Creates a `GskRenderNode` that will stroke a border rectangle inside the + line="2569">Creates a `GskRenderNode` that will stroke a border rectangle inside the given @outline. The 4 sides of the border can have different widths and colors. - + A new `GskRenderNode` + line="2582">A new `GskRenderNode` a `GskRoundedRect` describing the outline of the border + line="2571">a `GskRoundedRect` describing the outline of the border the stroke width of the border on + line="2572">the stroke width of the border on the top, right, bottom and left side respectively. @@ -432,7 +432,7 @@ The 4 sides of the border can have different widths and colors. the color used on the top, right, + line="2574">the color used on the top, right, bottom and left side. @@ -443,20 +443,22 @@ The 4 sides of the border can have different widths and colors. Retrieves the colors of the border. - + line="2538">Retrieves the colors of the border. + an array of 4 `GdkRGBA` structs - for the top, right, bottom and left color of the border - + line="2544">an array of 4 `GdkRGBA` + structs for the top, right, bottom and left color of the border + + + a `GskRenderNode` for a border + line="2540">a `GskRenderNode` for a border @@ -464,19 +466,19 @@ The 4 sides of the border can have different widths and colors. Retrieves the outline of the border. - + line="2504">Retrieves the outline of the border. + the outline of the border + line="2510">the outline of the border a `GskRenderNode` for a border + line="2506">a `GskRenderNode` for a border @@ -484,12 +486,12 @@ The 4 sides of the border can have different widths and colors. Retrieves the stroke widths of the border. - + line="2520">Retrieves the stroke widths of the border. + an array of 4 floats + line="2526">an array of 4 floats for the top, right, bottom and left stroke width of the border, respectively @@ -500,7 +502,7 @@ The 4 sides of the border can have different widths and colors. a `GskRenderNode` for a border + line="2522">a `GskRenderNode` for a border @@ -513,12 +515,17 @@ The 4 sides of the border can have different widths and colors. glib:type-name="GskBroadwayRenderer" glib:get-type="gsk_broadway_renderer_get_type" glib:type-struct="BroadwayRendererClass"> + A Broadway based renderer. + +See [class@Gsk.Renderer]. Creates a new Broadway renderer. + line="987">Creates a new Broadway renderer. The Broadway renderer is the default renderer for the broadway backend. It will only work with broadway surfaces, otherwise it will fail the @@ -531,7 +538,7 @@ support. a new Broadway renderer. + line="999">a new Broadway renderer. @@ -547,7 +554,7 @@ support. - + @@ -556,7 +563,7 @@ support. - + @@ -565,7 +572,7 @@ support. - + @@ -580,26 +587,26 @@ support. glib:fundamental="1"> A render node for a Cairo surface. + line="4201">A render node for a Cairo surface. Creates a `GskRenderNode` that will render a cairo surface + line="4288">Creates a `GskRenderNode` that will render a cairo surface into the area given by @bounds. You can draw to the cairo surface using [method@Gsk.CairoNode.get_draw_context]. - + A new `GskRenderNode` + line="4297">A new `GskRenderNode` the rectangle to render to + line="4290">the rectangle to render to @@ -608,16 +615,16 @@ You can draw to the cairo surface using [method@Gsk.CairoNode.get_draw_context]. c:identifier="gsk_cairo_node_get_draw_context"> Creates a Cairo context for drawing using the surface associated + line="4318">Creates a Cairo context for drawing using the surface associated to the render node. If no surface exists yet, a surface will be created optimized for rendering to @renderer. - + a Cairo context used for drawing; use + line="4328">a Cairo context used for drawing; use cairo_destroy() when done drawing @@ -625,7 +632,7 @@ rendering to @renderer. a `GskRenderNode` for a Cairo surface + line="4320">a `GskRenderNode` for a Cairo surface @@ -633,19 +640,19 @@ rendering to @renderer. Retrieves the Cairo surface used by the render node. - + line="4270">Retrieves the Cairo surface used by the render node. + a Cairo surface + line="4276">a Cairo surface a `GskRenderNode` for a Cairo surface + line="4272">a `GskRenderNode` for a Cairo surface @@ -660,15 +667,15 @@ rendering to @renderer. glib:type-struct="CairoRendererClass"> A GSK renderer that is using cairo. + line="40">A GSK renderer that is using cairo. Since it is using cairo, this renderer cannot support 3D transformations. - + Creates a new Cairo renderer. + line="221">Creates a new Cairo renderer. The Cairo renderer is the fallback renderer drawing in ways similar to how GTK 3 drew its content. Its primary use is as comparison tool. @@ -676,11 +683,11 @@ to how GTK 3 drew its content. Its primary use is as comparison tool. The Cairo renderer is incomplete. It cannot render 3D transformed content and will instead render an error marker. Its usage should be avoided. - + a new Cairo renderer. + line="233">a new Cairo renderer. @@ -690,7 +697,7 @@ avoided. disguised="1" opaque="1" glib:is-gtype-struct-for="CairoRenderer"> - + glib:fundamental="1"> A render node applying a rectangular clip to its single child node. + line="5642">A render node applying a rectangular clip to its single child node. Creates a `GskRenderNode` that will clip the @child to the area + line="5736">Creates a `GskRenderNode` that will clip the @child to the area given by @clip. - + A new `GskRenderNode` + line="5744">A new `GskRenderNode` The node to draw + line="5738">The node to draw The clip to apply + line="5739">The clip to apply @@ -732,19 +739,19 @@ given by @clip. Gets the child node that is getting clipped by the given @node. - + line="5774">Gets the child node that is getting clipped by the given @node. + The child that is getting clipped + line="5780">The child that is getting clipped a clip @GskRenderNode + line="5776">a clip @GskRenderNode @@ -752,19 +759,19 @@ given by @clip. Retrieves the clip rectangle for @node. - + line="5790">Retrieves the clip rectangle for @node. + a clip rectangle + line="5796">a clip rectangle a `GskClipNode` + line="5792">a `GskClipNode` @@ -779,11 +786,11 @@ given by @clip. glib:fundamental="1"> A render node controlling the color matrix of its single child node. + line="5097">A render node controlling the color matrix of its single child node. Creates a `GskRenderNode` that will drawn the @child with + line="5252">Creates a `GskRenderNode` that will drawn the @child with @color_matrix. In particular, the node will transform colors by applying @@ -792,30 +799,30 @@ In particular, the node will transform colors by applying for every pixel. The transformation operates on unpremultiplied colors, with color components ordered R, G, B, A. - + A new `GskRenderNode` + line="5268">A new `GskRenderNode` The node to draw + line="5254">The node to draw The matrix to apply + line="5255">The matrix to apply Values to add to the color + line="5256">Values to add to the color @@ -823,19 +830,19 @@ colors, with color components ordered R, G, B, A. Gets the child node that is getting its colors modified by the given @node. - + line="5296">Gets the child node that is getting its colors modified by the given @node. + The child that is getting its colors modified + line="5302">The child that is getting its colors modified a color matrix `GskRenderNode` + line="5298">a color matrix `GskRenderNode` @@ -844,19 +851,19 @@ colors, with color components ordered R, G, B, A. c:identifier="gsk_color_matrix_node_get_color_matrix"> Retrieves the color matrix used by the @node. - + line="5312">Retrieves the color matrix used by the @node. + a 4x4 color matrix + line="5318">a 4x4 color matrix a color matrix `GskRenderNode` + line="5314">a color matrix `GskRenderNode` @@ -865,19 +872,19 @@ colors, with color components ordered R, G, B, A. c:identifier="gsk_color_matrix_node_get_color_offset"> Retrieves the color offset used by the @node. - + line="5328">Retrieves the color offset used by the @node. + a color vector + line="5334">a color vector a color matrix `GskRenderNode` + line="5330">a color matrix `GskRenderNode` @@ -892,30 +899,30 @@ colors, with color components ordered R, G, B, A. glib:fundamental="1"> A render node for a solid color. + line="154">A render node for a solid color. Creates a `GskRenderNode` that will render the color specified by @rgba into + line="256">Creates a `GskRenderNode` that will render the color specified by @rgba into the area given by @bounds. - + A new `GskRenderNode` + line="264">A new `GskRenderNode` a `GdkRGBA` specifying a color + line="258">a `GdkRGBA` specifying a color the rectangle to render the color into + line="259">the rectangle to render the color into @@ -923,19 +930,22 @@ the area given by @bounds. Retrieves the color of the given @node. - + line="216">Retrieves the color of the given @node. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. + the color of the node + line="225">the color of the node a `GskRenderNode` + line="218">a `GskRenderNode` @@ -944,18 +954,18 @@ the area given by @bounds. A color stop in a gradient node. - + line="41">A color stop in a gradient node. + the offset of the color stop + line="43">the offset of the color stop the color at the given offset + line="44">the color at the given offset @@ -968,45 +978,45 @@ the area given by @bounds. glib:fundamental="1"> A render node for a conic gradient. + line="1691">A render node for a conic gradient. Creates a `GskRenderNode` that draws a conic gradient. + line="1980">Creates a `GskRenderNode` that draws a conic gradient. The conic gradient starts around @center in the direction of @rotation. A rotation of 0 means that the gradient points up. Color stops are then added clockwise. - + A new `GskRenderNode` + line="1997">A new `GskRenderNode` the bounds of the node + line="1982">the bounds of the node the center of the gradient + line="1983">the center of the gradient the rotation of the gradient in degrees + line="1984">the rotation of the gradient in degrees a pointer to an array of + line="1985">a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. @@ -1017,7 +1027,7 @@ that the gradient points up. Color stops are then added clockwise. the number of elements in @color_stops + line="1989">the number of elements in @color_stops @@ -1027,24 +1037,24 @@ that the gradient points up. Color stops are then added clockwise. version="4.2"> Retrieves the angle for the gradient in radians, normalized in [0, 2 * PI]. + line="2250">Retrieves the angle for the gradient in radians, normalized in [0, 2 * PI]. The angle is starting at the top and going clockwise, as expressed in the css specification: angle = 90 - gsk_conic_gradient_node_get_rotation() - + the angle for the gradient + line="2261">the angle for the gradient a `GskRenderNode` for a conic gradient + line="2252">a `GskRenderNode` for a conic gradient @@ -1053,19 +1063,19 @@ in the css specification: c:identifier="gsk_conic_gradient_node_get_center"> Retrieves the center pointer for the gradient. - + line="2218">Retrieves the center pointer for the gradient. + the center point for the gradient + line="2224">the center point for the gradient a `GskRenderNode` for a conic gradient + line="2220">a `GskRenderNode` for a conic gradient @@ -1074,12 +1084,12 @@ in the css specification: c:identifier="gsk_conic_gradient_node_get_color_stops"> Retrieves the color stops in the gradient. - + line="2132">Retrieves the color stops in the gradient. + the color stops in the gradient + line="2139">the color stops in the gradient @@ -1088,7 +1098,7 @@ in the css specification: a `GskRenderNode` for a conic gradient + line="2134">a `GskRenderNode` for a conic gradient the number of color stops in the returned array + line="2135">the number of color stops in the returned array @@ -1108,19 +1118,19 @@ in the css specification: c:identifier="gsk_conic_gradient_node_get_n_color_stops"> Retrieves the number of color stops in the gradient. - + line="2116">Retrieves the number of color stops in the gradient. + the number of color stops + line="2122">the number of color stops a `GskRenderNode` for a conic gradient + line="2118">a `GskRenderNode` for a conic gradient @@ -1129,19 +1139,19 @@ in the css specification: c:identifier="gsk_conic_gradient_node_get_rotation"> Retrieves the rotation for the gradient in degrees. - + line="2234">Retrieves the rotation for the gradient in degrees. + the rotation for the gradient + line="2240">the rotation for the gradient a `GskRenderNode` for a conic gradient + line="2236">a `GskRenderNode` for a conic gradient @@ -1156,25 +1166,25 @@ in the css specification: glib:fundamental="1"> A render node that can contain other render nodes. + line="4374">A render node that can contain other render nodes. Creates a new `GskRenderNode` instance for holding the given @children. + line="4541">Creates a new `GskRenderNode` instance for holding the given @children. The new node will acquire a reference to each of the children. - + the new `GskRenderNode` + line="4550">the new `GskRenderNode` The children of the node + line="4543">The children of the node @@ -1182,7 +1192,7 @@ The new node will acquire a reference to each of the children. Number of children in the @children array + line="4544">Number of children in the @children array @@ -1190,25 +1200,25 @@ The new node will acquire a reference to each of the children. Gets one of the children of @container. - + line="4630">Gets one of the children of @container. + the @idx'th child of @container + line="4637">the @idx'th child of @container a container `GskRenderNode` + line="4632">a container `GskRenderNode` the position of the child to get + line="4633">the position of the child to get @@ -1217,19 +1227,19 @@ The new node will acquire a reference to each of the children. c:identifier="gsk_container_node_get_n_children"> Retrieves the number of direct children of @node. - + line="4614">Retrieves the number of direct children of @node. + the number of children of the `GskRenderNode` + line="4620">the number of children of the `GskRenderNode` a container `GskRenderNode` + line="4616">a container `GskRenderNode` @@ -1241,7 +1251,7 @@ The new node will acquire a reference to each of the children. c:type="GskCorner"> The corner indices used by `GskRoundedRect`. + line="199">The corner indices used by `GskRoundedRect`. glib:name="GSK_CORNER_TOP_LEFT"> The top left corner + line="201">The top left corner glib:name="GSK_CORNER_TOP_RIGHT"> The top right corner + line="202">The top right corner glib:name="GSK_CORNER_BOTTOM_RIGHT"> The bottom right corner + line="203">The bottom right corner glib:name="GSK_CORNER_BOTTOM_LEFT"> The bottom left corner + line="204">The bottom left corner glib:fundamental="1"> A render node cross fading between two child nodes. + line="6984">A render node cross fading between two child nodes. Creates a `GskRenderNode` that will do a cross-fade between @start and @end. - + line="7080">Creates a `GskRenderNode` that will do a cross-fade between @start and @end. + A new `GskRenderNode` + line="7089">A new `GskRenderNode` The start node to be drawn + line="7082">The start node to be drawn The node to be cross_fadeed onto the @start node + line="7083">The node to be cross_fadeed onto the @start node How far the fade has progressed from start to end. The value will + line="7084">How far the fade has progressed from start to end. The value will be clamped to the range [0 ... 1] @@ -1326,19 +1336,19 @@ The new node will acquire a reference to each of the children. c:identifier="gsk_cross_fade_node_get_end_child"> Retrieves the child `GskRenderNode` at the end of the cross-fade. - + line="7138">Retrieves the child `GskRenderNode` at the end of the cross-fade. + a `GskRenderNode` + line="7144">a `GskRenderNode` a cross-fading `GskRenderNode` + line="7140">a cross-fading `GskRenderNode` @@ -1347,19 +1357,19 @@ The new node will acquire a reference to each of the children. c:identifier="gsk_cross_fade_node_get_progress"> Retrieves the progress value of the cross fade. - + line="7154">Retrieves the progress value of the cross fade. + the progress value, between 0 and 1 + line="7160">the progress value, between 0 and 1 a cross-fading `GskRenderNode` + line="7156">a cross-fading `GskRenderNode` @@ -1368,19 +1378,19 @@ The new node will acquire a reference to each of the children. c:identifier="gsk_cross_fade_node_get_start_child"> Retrieves the child `GskRenderNode` at the beginning of the cross-fade. - + line="7122">Retrieves the child `GskRenderNode` at the beginning of the cross-fade. + a `GskRenderNode` + line="7128">a `GskRenderNode` a cross-fading `GskRenderNode` + line="7124">a cross-fading `GskRenderNode` @@ -1395,33 +1405,33 @@ The new node will acquire a reference to each of the children. glib:fundamental="1"> A render node that emits a debugging message when drawing its + line="8137">A render node that emits a debugging message when drawing its child node. Creates a `GskRenderNode` that will add debug information about + line="8218">Creates a `GskRenderNode` that will add debug information about the given @child. Adding this node has no visual effect. - + A new `GskRenderNode` + line="8228">A new `GskRenderNode` The child to add debug info for + line="8220">The child to add debug info for The debug message + line="8221">The debug message @@ -1429,19 +1439,19 @@ Adding this node has no visual effect. Gets the child node that is getting drawn by the given @node. - + line="8255">Gets the child node that is getting drawn by the given @node. + the child `GskRenderNode` + line="8261">the child `GskRenderNode` a debug `GskRenderNode` + line="8257">a debug `GskRenderNode` @@ -1449,41 +1459,205 @@ Adding this node has no visual effect. Gets the debug message that was set on this node - + line="8271">Gets the debug message that was set on this node + The debug message + line="8277">The debug message a debug `GskRenderNode` + line="8273">a debug `GskRenderNode` + + A render node filling the area given by [struct@Gsk.Path] +and [enum@Gsk.FillRule] with the child node. + + Creates a `GskRenderNode` that will fill the @child in the area +given by @path and @fill_rule. + + + A new `GskRenderNode` + + + + + The node to fill the area with + + + + The path describing the area to fill + + + + The fill rule to use + + + + + + Gets the child node that is getting drawn by the given @node. + + + The child that is getting drawn + + + + + a fill `GskRenderNode` + + + + + + Retrieves the fill rule used to determine how the path is filled. + + + a `GskFillRule` + + + + + a fill `GskRenderNode` + + + + + + Retrieves the path used to describe the area filled with the contents of +the @node. + + + a `GskPath` + + + + + a fill `GskRenderNode` + + + + + + + Specifies how paths are filled. + +Whether or not a point is included in the fill is determined by taking +a ray from that point to infinity and looking at intersections with the +path. The ray can be in any direction, as long as it doesn't pass through +the end point of a segment or have a tricky intersection such as +intersecting tangent to the path. + +(Note that filling is not actually implemented in this way. This +is just a description of the rule that is applied.) + +New entries may be added in future versions. + + If the path crosses the ray from + left-to-right, counts +1. If the path crosses the ray + from right to left, counts -1. (Left and right are determined + from the perspective of looking along the ray from the starting + point.) If the total count is non-zero, the point will be filled. + + + Counts the total number of + intersections, without regard to the orientation of the contour. If + the total number of intersections is odd, the point will be + filled. + + - - + A GL based renderer. + +See [class@Gsk.Renderer]. + + Creates a new `GskRenderer` using the new OpenGL renderer. - + filename="gsk/gpu/gskglrenderer.c" + line="177">Creates an instance of the GL renderer. + a new GL renderer + filename="gsk/gpu/gskglrenderer.c" + line="182">a GL renderer @@ -1493,11 +1667,13 @@ Adding this node has no visual effect. disguised="1" opaque="1" glib:is-gtype-struct-for="GLRenderer"> - + - + This feature was deprecated in GTK 4.16 after the new +rendering infrastructure introduced in 4.14 did not support it. The lack +of Vulkan integration would have made it a very hard feature to support. +If you want to use OpenGL directly, you should look at +[GtkGLArea](../gtk4/class.GLArea.html), which uses a different approach +and is still well-supported. + + c:identifier="gsk_gl_shader_new_from_bytes" + deprecated="1" + deprecated-version="4.16"> Creates a `GskGLShader` that will render pixels using the specified code. - + line="484">Creates a `GskGLShader` that will render pixels using the specified code. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A new `GskGLShader` + line="490">A new `GskGLShader` GLSL sourcecode for the shader, as a `GBytes` + line="486">GLSL sourcecode for the shader, as a `GBytes` + c:identifier="gsk_gl_shader_new_from_resource" + deprecated="1" + deprecated-version="4.16"> Creates a `GskGLShader` that will render pixels using the specified code. - + line="506">Creates a `GskGLShader` that will render pixels using the specified code. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A new `GskGLShader` + line="513">A new `GskGLShader` path to a resource that contains the GLSL sourcecode for + line="508">path to a resource that contains the GLSL sourcecode for the shader - + Tries to compile the @shader for the given @renderer. + line="529">Tries to compile the @shader for the given @renderer. If there is a problem, this function returns %FALSE and reports an error. You should use this function before relying on the shader @@ -1676,62 +1872,72 @@ change the current GL context) and requires the renderer to be set up. This means that the widget has to be realized. Commonly you want to call this from the realize signal of a widget, or during widget snapshot. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + %TRUE on success, %FALSE if an error occurred + line="548">%TRUE on success, %FALSE if an error occurred a `GskGLShader` + line="531">a `GskGLShader` a `GskRenderer` + line="532">a `GskRenderer` + c:identifier="gsk_gl_shader_find_uniform_by_name" + deprecated="1" + deprecated-version="4.16"> Looks for a uniform by the name @name, and returns the index + line="675">Looks for a uniform by the name @name, and returns the index of the uniform, or -1 if it was not found. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The index of the uniform, or -1 + line="683">The index of the uniform, or -1 a `GskGLShader` + line="677">a `GskGLShader` uniform name + line="678">uniform name + introspectable="0" + deprecated="1" + deprecated-version="4.16"> Formats the uniform data as needed for feeding the named uniforms + line="1142">Formats the uniform data as needed for feeding the named uniforms values into the shader. The argument list is a list of pairs of names, and values for the types @@ -1740,11 +1946,14 @@ primitive values and `graphene_vecN_t *` for vecN uniforms). Any uniforms of the shader that are not included in the argument list are zero-initialized. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A newly allocated block of data which can be + line="1158">A newly allocated block of data which can be passed to [ctor@Gsk.GLShaderNode.new]. @@ -1752,13 +1961,13 @@ are zero-initialized. a `GskGLShader` + line="1144">a `GskGLShader` name-Value pairs for the uniforms of @shader, ending with + line="1145">name-Value pairs for the uniforms of @shader, ending with a %NULL name @@ -1766,10 +1975,12 @@ are zero-initialized. + introspectable="0" + deprecated="1" + deprecated-version="4.16"> Formats the uniform data as needed for feeding the named uniforms + line="1052">Formats the uniform data as needed for feeding the named uniforms values into the shader. The argument list is a list of pairs of names, and values for the @@ -1780,11 +1991,14 @@ It is an error to pass a uniform name that is not declared by the shader. Any uniforms of the shader that are not included in the argument list are zero-initialized. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A newly allocated block of data which can be + line="1070">A newly allocated block of data which can be passed to [ctor@Gsk.GLShaderNode.new]. @@ -1792,161 +2006,191 @@ are zero-initialized. a `GskGLShader` + line="1054">a `GskGLShader` name-Value pairs for the uniforms of @shader, ending + line="1055">name-Value pairs for the uniforms of @shader, ending with a %NULL name - + Gets the value of the uniform @idx in the @args block. + line="904">Gets the value of the uniform @idx in the @args block. The uniform must be of bool type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The value + line="914">The value a `GskGLShader` + line="906">a `GskGLShader` uniform arguments + line="907">uniform arguments index of the uniform + line="908">index of the uniform - + Gets the value of the uniform @idx in the @args block. + line="793">Gets the value of the uniform @idx in the @args block. The uniform must be of float type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The value + line="803">The value a `GskGLShader` + line="795">a `GskGLShader` uniform arguments + line="796">uniform arguments index of the uniform + line="797">index of the uniform - + Gets the value of the uniform @idx in the @args block. + line="830">Gets the value of the uniform @idx in the @args block. The uniform must be of int type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The value + line="840">The value a `GskGLShader` + line="832">a `GskGLShader` uniform arguments + line="833">uniform arguments index of the uniform + line="834">index of the uniform - + Gets the value of the uniform @idx in the @args block. + line="867">Gets the value of the uniform @idx in the @args block. The uniform must be of uint type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The value + line="877">The value a `GskGLShader` + line="869">a `GskGLShader` uniform arguments + line="870">uniform arguments index of the uniform + line="871">index of the uniform - + Gets the value of the uniform @idx in the @args block. + line="941">Gets the value of the uniform @idx in the @args block. The uniform must be of vec2 type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + @@ -1954,36 +2198,42 @@ The uniform must be of vec2 type. a `GskGLShader` + line="943">a `GskGLShader` uniform arguments + line="944">uniform arguments index of the uniform + line="945">index of the uniform location to store the uniform value in + line="946">location to store the uniform value in - + Gets the value of the uniform @idx in the @args block. + line="978">Gets the value of the uniform @idx in the @args block. The uniform must be of vec3 type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + @@ -1991,36 +2241,42 @@ The uniform must be of vec3 type. a `GskGLShader` + line="980">a `GskGLShader` uniform arguments + line="981">uniform arguments index of the uniform + line="982">index of the uniform location to store the uniform value in + line="983">location to store the uniform value in - + Gets the value of the uniform @idx in the @args block. + line="1015">Gets the value of the uniform @idx in the @args block. The uniform must be of vec4 type. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + @@ -2028,219 +2284,258 @@ The uniform must be of vec4 type. a `GskGLShader` + line="1017">a `GskGLShader` uniform arguments + line="1018">uniform arguments index of the uniform + line="1019">index of the uniform location to store set the uniform value in + line="1020">location to store set the uniform value in - + Get the size of the data block used to specify arguments for this shader. - + line="759">Get the size of the data block used to specify arguments for this shader. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The size of the data block + line="765">The size of the data block a `GskGLShader` + line="761">a `GskGLShader` + c:identifier="gsk_gl_shader_get_n_textures" + deprecated="1" + deprecated-version="4.16"> Returns the number of textures that the shader requires. + line="608">Returns the number of textures that the shader requires. This can be used to check that the a passed shader works in your usecase. It is determined by looking at the highest u_textureN value that the shader defines. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The number of texture inputs required by @shader + line="618">The number of texture inputs required by @shader a `GskGLShader` + line="610">a `GskGLShader` + c:identifier="gsk_gl_shader_get_n_uniforms" + deprecated="1" + deprecated-version="4.16"> Get the number of declared uniforms for this shader. - + line="632">Get the number of declared uniforms for this shader. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The number of declared uniforms + line="638">The number of declared uniforms a `GskGLShader` + line="634">a `GskGLShader` - + glib:get-property="resource" + deprecated="1" + deprecated-version="4.16"> Gets the resource path for the GLSL sourcecode being used + line="587">Gets the resource path for the GLSL sourcecode being used to render this shader. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The resource path for the shader + line="594">The resource path for the shader a `GskGLShader` + line="589">a `GskGLShader` - + glib:get-property="source" + deprecated="1" + deprecated-version="4.16"> Gets the GLSL sourcecode being used to render this shader. - + line="567">Gets the GLSL sourcecode being used to render this shader. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The source code for the shader + line="573">The source code for the shader a `GskGLShader` + line="569">a `GskGLShader` + c:identifier="gsk_gl_shader_get_uniform_name" + deprecated="1" + deprecated-version="4.16"> Get the name of the declared uniform for this shader at index @idx. - + line="652">Get the name of the declared uniform for this shader at index @idx. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The name of the declared uniform + line="659">The name of the declared uniform a `GskGLShader` + line="654">a `GskGLShader` index of the uniform + line="655">index of the uniform + c:identifier="gsk_gl_shader_get_uniform_offset" + deprecated="1" + deprecated-version="4.16"> Get the offset into the data block where data for this uniforms is stored. - + line="728">Get the offset into the data block where data for this uniforms is stored. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The data offset + line="735">The data offset a `GskGLShader` + line="730">a `GskGLShader` index of the uniform + line="731">index of the uniform + c:identifier="gsk_gl_shader_get_uniform_type" + deprecated="1" + deprecated-version="4.16"> Get the type of the declared uniform for this shader at index @idx. - + line="705">Get the type of the declared uniform for this shader at index @idx. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The type of the declared uniform + line="712">The type of the declared uniform a `GskGLShader` + line="707">a `GskGLShader` index of the uniform + line="708">index of the uniform @@ -2251,11 +2546,9 @@ to render this shader. transfer-ownership="none" getter="get_resource" default-value="NULL"> - Resource containing the source code for the shader. + line="460">Resource containing the source code for the shader. If the shader source is not coming from a resource, this will be %NULL. @@ -2266,13 +2559,16 @@ will be %NULL. construct-only="1" transfer-ownership="none" getter="get_source"> + The source code for the shader, as a `GBytes`. - + @@ -2286,11 +2582,14 @@ will be %NULL. glib:fundamental="1"> A render node using a GL shader when drawing its children nodes. - + line="8291">A render node using a GL shader when drawing its children nodes. + Creates a `GskRenderNode` that will render the given @shader into the + line="8374">Creates a `GskRenderNode` that will render the given @shader into the area given by @bounds. The @args is a block of data to use for uniform input, as per types and @@ -2307,30 +2606,33 @@ If the renderer doesn't support GL shaders, or if there is any problem when compiling the shader, then the node will draw pink. You should use [method@Gsk.GLShader.compile] to ensure the @shader will work for the renderer before using it. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A new `GskRenderNode` + line="8402">A new `GskRenderNode` the `GskGLShader` + line="8376">the `GskGLShader` the rectangle to render the shader into + line="8377">the rectangle to render the shader into Arguments for the uniforms + line="8378">Arguments for the uniforms allow-none="1"> array of child nodes, + line="8379">array of child nodes, these will be rendered to textures and used as input. @@ -2348,75 +2650,92 @@ renderer before using it. Length of @children (currently the GL backend supports + line="8381">Length of @children (currently the GL backend supports up to 4 children) - + Gets args for the node. - + line="8510">Gets args for the node. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A `GBytes` with the uniform arguments + line="8516">A `GBytes` with the uniform arguments a `GskRenderNode` for a gl shader + line="8512">a `GskRenderNode` for a gl shader - + Gets one of the children. - + line="8472">Gets one of the children. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + the @idx'th child of @node + line="8479">the @idx'th child of @node a `GskRenderNode` for a gl shader + line="8474">a `GskRenderNode` for a gl shader the position of the child to get + line="8475">the position of the child to get + c:identifier="gsk_gl_shader_node_get_n_children" + deprecated="1" + deprecated-version="4.16"> Returns the number of children - + line="8452">Returns the number of children + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + The number of children + line="8458">The number of children a `GskRenderNode` for a gl shader + line="8454">a `GskRenderNode` for a gl shader @@ -2424,32 +2743,33 @@ renderer before using it. Gets shader code for the node. - + line="8494">Gets shader code for the node. + the `GskGLShader` shader + line="8500">the `GskGLShader` shader a `GskRenderNode` for a gl shader + line="8496">a `GskRenderNode` for a gl shader This defines the types of the uniforms that `GskGLShaders` -declare. + line="427">Defines the types of the uniforms that `GskGLShaders` declare. It defines both what the type is called in the GLSL shader code, and what the corresponding C type is on the Gtk side. @@ -2460,7 +2780,7 @@ code, and what the corresponding C type is on the Gtk side. glib:name="GSK_GL_UNIFORM_TYPE_NONE"> No type, used for uninitialized or unspecified values. + line="429">No type, used for uninitialized or unspecified values. glib:name="GSK_GL_UNIFORM_TYPE_FLOAT"> A float uniform + line="430">A float uniform glib:name="GSK_GL_UNIFORM_TYPE_INT"> A GLSL int / gint32 uniform + line="431">A GLSL int / gint32 uniform glib:name="GSK_GL_UNIFORM_TYPE_UINT"> A GLSL uint / guint32 uniform + line="432">A GLSL uint / guint32 uniform glib:name="GSK_GL_UNIFORM_TYPE_BOOL"> A GLSL bool / gboolean uniform + line="433">A GLSL bool / gboolean uniform glib:name="GSK_GL_UNIFORM_TYPE_VEC2"> A GLSL vec2 / graphene_vec2_t uniform + line="434">A GLSL vec2 / graphene_vec2_t uniform glib:name="GSK_GL_UNIFORM_TYPE_VEC3"> A GLSL vec3 / graphene_vec3_t uniform + line="435">A GLSL vec3 / graphene_vec3_t uniform glib:name="GSK_GL_UNIFORM_TYPE_VEC4"> A GLSL vec4 / graphene_vec4_t uniform + line="436">A GLSL vec4 / graphene_vec4_t uniform - + @@ -2538,7 +2858,7 @@ code, and what the corresponding C type is on the Gtk side. - + @@ -2547,7 +2867,7 @@ code, and what the corresponding C type is on the Gtk side. - + @@ -2576,7 +2896,7 @@ code, and what the corresponding C type is on the Gtk side. - + @@ -2585,7 +2905,7 @@ code, and what the corresponding C type is on the Gtk side. - + @@ -2594,7 +2914,7 @@ code, and what the corresponding C type is on the Gtk side. - + @@ -2603,7 +2923,7 @@ code, and what the corresponding C type is on the Gtk side. - + @@ -2627,6 +2947,24 @@ code, and what the corresponding C type is on the Gtk side. + + + + + + + + + + + + + + glib:fundamental="1"> A render node for an inset shadow. + line="3146">A render node for an inset shadow. Creates a `GskRenderNode` that will render an inset shadow + line="3585">Creates a `GskRenderNode` that will render an inset shadow into the box given by @outline. - + A new `GskRenderNode` + line="3597">A new `GskRenderNode` outline of the region containing the shadow + line="3587">outline of the region containing the shadow color of the shadow + line="3588">color of the shadow horizontal offset of shadow + line="3589">horizontal offset of shadow vertical offset of shadow + line="3590">vertical offset of shadow how far the shadow spreads towards the inside + line="3591">how far the shadow spreads towards the inside how much blur to apply to the shadow + line="3592">how much blur to apply to the shadow @@ -2692,19 +3030,19 @@ into the box given by @outline. c:identifier="gsk_inset_shadow_node_get_blur_radius"> Retrieves the blur radius to apply to the shadow. - + line="3780">Retrieves the blur radius to apply to the shadow. + the blur radius, in pixels + line="3786">the blur radius, in pixels a `GskRenderNode` for an inset shadow + line="3782">a `GskRenderNode` for an inset shadow @@ -2712,19 +3050,22 @@ into the box given by @outline. Retrieves the color of the inset shadow. - + line="3680">Retrieves the color of the inset shadow. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. + the color of the shadow + line="3689">the color of the shadow a `GskRenderNode` for an inset shadow + line="3682">a `GskRenderNode` for an inset shadow @@ -2732,19 +3073,19 @@ into the box given by @outline. Retrieves the horizontal offset of the inset shadow. - + line="3716">Retrieves the horizontal offset of the inset shadow. + an offset, in pixels + line="3722">an offset, in pixels a `GskRenderNode` for an inset shadow + line="3718">a `GskRenderNode` for an inset shadow @@ -2752,19 +3093,19 @@ into the box given by @outline. Retrieves the vertical offset of the inset shadow. - + line="3732">Retrieves the vertical offset of the inset shadow. + an offset, in pixels + line="3738">an offset, in pixels a `GskRenderNode` for an inset shadow + line="3734">a `GskRenderNode` for an inset shadow @@ -2773,19 +3114,19 @@ into the box given by @outline. c:identifier="gsk_inset_shadow_node_get_outline"> Retrieves the outline rectangle of the inset shadow. - + line="3664">Retrieves the outline rectangle of the inset shadow. + a rounded rectangle + line="3670">a rounded rectangle a `GskRenderNode` for an inset shadow + line="3666">a `GskRenderNode` for an inset shadow @@ -2794,24 +3135,126 @@ into the box given by @outline. c:identifier="gsk_inset_shadow_node_get_spread"> Retrieves how much the shadow spreads inwards. - + line="3764">Retrieves how much the shadow spreads inwards. + the size of the shadow, in pixels + line="3770">the size of the shadow, in pixels a `GskRenderNode` for an inset shadow + line="3766">a `GskRenderNode` for an inset shadow + + Specifies how to render the start and end points of contours or +dashes when stroking. + +The default line cap style is `GSK_LINE_CAP_BUTT`. + +New entries may be added in future versions. + +<figure> + <picture> + <source srcset="caps-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Line Cap Styles" src="caps-light.png"> + </picture> + <figcaption>GSK_LINE_CAP_BUTT, GSK_LINE_CAP_ROUND, GSK_LINE_CAP_SQUARE</figcaption> +</figure> + + Start and stop the line exactly at the start + and end point + + + Use a round ending, the center of the circle + is the start or end point + + + use squared ending, the center of the square + is the start or end point + + + + Specifies how to render the junction of two lines when stroking. + +The default line join style is `GSK_LINE_JOIN_MITER`. + +New entries may be added in future versions. + +<figure> + <picture> + <source srcset="join-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Line Join Styles" src="join-light.png"> + </picture> + <figcaption>GSK_LINE_JOINT_MITER, GSK_LINE_JOINT_ROUND, GSK_LINE_JOIN_BEVEL</figcaption> +</figure> + + Use a sharp angled corner + + + Use a round join, the center of the circle is + the join point + + + use a cut-off join, the join is cut off at half + the line width from the joint point + + glib:fundamental="1"> A render node for a linear gradient. + line="324">A render node for a linear gradient. Creates a `GskRenderNode` that will create a linear gradient from the given + line="619">Creates a `GskRenderNode` that will create a linear gradient from the given points and color stops, and render that into the area given by @bounds. - + A new `GskRenderNode` + line="633">A new `GskRenderNode` the rectangle to render the linear gradient into + line="621">the rectangle to render the linear gradient into the point at which the linear gradient will begin + line="622">the point at which the linear gradient will begin the point at which the linear gradient will finish + line="623">the point at which the linear gradient will finish a pointer to an array of + line="624">a pointer to an array of `GskColorStop` defining the gradient. The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1. @@ -2867,7 +3310,7 @@ points and color stops, and render that into the area given by @bounds. the number of elements in @color_stops + line="628">the number of elements in @color_stops @@ -2876,12 +3319,12 @@ points and color stops, and render that into the area given by @bounds. c:identifier="gsk_linear_gradient_node_get_color_stops"> Retrieves the color stops in the gradient. - + line="920">Retrieves the color stops in the gradient. + the color stops in the gradient + line="927">the color stops in the gradient @@ -2890,7 +3333,7 @@ points and color stops, and render that into the area given by @bounds. a `GskRenderNode` for a linear gradient + line="922">a `GskRenderNode` for a linear gradient allow-none="1"> the number of color stops in the returned array + line="923">the number of color stops in the returned array @@ -2909,19 +3352,19 @@ points and color stops, and render that into the area given by @bounds. Retrieves the final point of the linear gradient. - + line="888">Retrieves the final point of the linear gradient. + the final point + line="894">the final point a `GskRenderNode` for a linear gradient + line="890">a `GskRenderNode` for a linear gradient @@ -2930,19 +3373,19 @@ points and color stops, and render that into the area given by @bounds. c:identifier="gsk_linear_gradient_node_get_n_color_stops"> Retrieves the number of color stops in the gradient. - + line="904">Retrieves the number of color stops in the gradient. + the number of color stops + line="910">the number of color stops a `GskRenderNode` for a linear gradient + line="906">a `GskRenderNode` for a linear gradient @@ -2951,19 +3394,19 @@ points and color stops, and render that into the area given by @bounds. c:identifier="gsk_linear_gradient_node_get_start"> Retrieves the initial point of the linear gradient. - + line="872">Retrieves the initial point of the linear gradient. + the initial point + line="878">the initial point a `GskRenderNode` for a linear gradient + line="874">a `GskRenderNode` for a linear gradient @@ -2976,7 +3419,7 @@ points and color stops, and render that into the area given by @bounds. c:type="GskMaskMode"> The mask modes available for mask nodes. + line="457">The mask modes available for mask nodes. glib:name="GSK_MASK_MODE_ALPHA"> Use the alpha channel of the mask + line="459">Use the alpha channel of the mask glib:name="GSK_MASK_MODE_INVERTED_ALPHA"> Use the inverted alpha channel of the mask + line="460">Use the inverted alpha channel of the mask glib:name="GSK_MASK_MODE_LUMINANCE"> Use the luminance of the mask, + line="461">Use the luminance of the mask, multiplied by mask alpha glib:name="GSK_MASK_MODE_INVERTED_LUMINANCE"> Use the inverted luminance of the mask, + line="463">Use the inverted luminance of the mask, multiplied by mask alpha @@ -3026,39 +3469,39 @@ points and color stops, and render that into the area given by @bounds. glib:fundamental="1"> A render node masking one child node with another. + line="7873">A render node masking one child node with another. Creates a `GskRenderNode` that will mask a given node by another. + line="8033">Creates a `GskRenderNode` that will mask a given node by another. The @mask_mode determines how the 'mask values' are derived from the colors of the @mask. Applying the mask consists of multiplying the 'mask value' with the alpha of the source. - + A new `GskRenderNode` + line="8045">A new `GskRenderNode` The source node to be drawn + line="8035">The source node to be drawn The node to be used as mask + line="8036">The node to be used as mask The mask mode to use + line="8037">The mask mode to use @@ -3068,19 +3511,19 @@ the 'mask value' with the alpha of the source. version="4.10"> Retrieves the mask `GskRenderNode` child of the @node. - + line="8096">Retrieves the mask `GskRenderNode` child of the @node. + the mask child node + line="8102">the mask child node a mask `GskRenderNode` + line="8098">a mask `GskRenderNode` @@ -3090,19 +3533,19 @@ the 'mask value' with the alpha of the source. version="4.10"> Retrieves the mask mode used by @node. - + line="8116">Retrieves the mask mode used by @node. + the mask mode + line="8122">the mask mode a blending `GskRenderNode` + line="8118">a blending `GskRenderNode` @@ -3112,19 +3555,19 @@ the 'mask value' with the alpha of the source. version="4.10"> Retrieves the source `GskRenderNode` child of the @node. - + line="8076">Retrieves the source `GskRenderNode` child of the @node. + the source child node + line="8082">the source child node a mask `GskRenderNode` + line="8078">a mask `GskRenderNode` @@ -3135,19 +3578,24 @@ the 'mask value' with the alpha of the source. parent="Renderer" glib:type-name="GskNglRenderer" glib:get-type="gsk_ngl_renderer_get_type"> + A GL based renderer. + +See [class@Gsk.Renderer]. + deprecated-version="4.18"> Same as gsk_gl_renderer_new(). + filename="gsk/gpu/gskglrenderer.c" + line="230">Same as gsk_gl_renderer_new(). Use gsk_gl_renderer_new() - + a new GL renderer + filename="gsk/gpu/gskglrenderer.c" + line="235">a GL renderer @@ -3161,30 +3609,30 @@ the 'mask value' with the alpha of the source. glib:fundamental="1"> A render node controlling the opacity of its single child node. + line="4955">A render node controlling the opacity of its single child node. Creates a `GskRenderNode` that will drawn the @child with reduced + line="5028">Creates a `GskRenderNode` that will drawn the @child with reduced @opacity. - + A new `GskRenderNode` + line="5036">A new `GskRenderNode` The node to draw + line="5030">The node to draw The opacity to apply + line="5031">The opacity to apply @@ -3192,19 +3640,19 @@ the 'mask value' with the alpha of the source. Gets the child node that is getting opacityed by the given @node. - + line="5062">Gets the child node that is getting opacityed by the given @node. + The child that is getting opacityed + line="5068">The child that is getting opacityed a `GskRenderNode` for an opacity + line="5064">a `GskRenderNode` for an opacity @@ -3212,19 +3660,19 @@ the 'mask value' with the alpha of the source. Gets the transparency factor for an opacity node. - + line="5078">Gets the transparency factor for an opacity node. + the opacity factor + line="5084">the opacity factor a `GskRenderNode` for an opacity + line="5080">a `GskRenderNode` for an opacity @@ -3239,54 +3687,54 @@ the 'mask value' with the alpha of the source. glib:fundamental="1"> A render node for an outset shadow. + line="3799">A render node for an outset shadow. Creates a `GskRenderNode` that will render an outset shadow + line="3981">Creates a `GskRenderNode` that will render an outset shadow around the box given by @outline. - + A new `GskRenderNode` + line="3993">A new `GskRenderNode` outline of the region surrounded by shadow + line="3983">outline of the region surrounded by shadow color of the shadow + line="3984">color of the shadow horizontal offset of shadow + line="3985">horizontal offset of shadow vertical offset of shadow + line="3986">vertical offset of shadow how far the shadow spreads towards the inside + line="3987">how far the shadow spreads towards the inside how much blur to apply to the shadow + line="3988">how much blur to apply to the shadow @@ -3295,19 +3743,19 @@ around the box given by @outline. c:identifier="gsk_outset_shadow_node_get_blur_radius"> Retrieves the blur radius of the shadow. - + line="4182">Retrieves the blur radius of the shadow. + the blur radius, in pixels + line="4188">the blur radius, in pixels a `GskRenderNode` for an outset shadow + line="4184">a `GskRenderNode` for an outset shadow @@ -3315,19 +3763,22 @@ around the box given by @outline. Retrieves the color of the outset shadow. - + line="4082">Retrieves the color of the outset shadow. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. + a color + line="4091">a color a `GskRenderNode` for an outset shadow + line="4084">a `GskRenderNode` for an outset shadow @@ -3335,19 +3786,19 @@ around the box given by @outline. Retrieves the horizontal offset of the outset shadow. - + line="4118">Retrieves the horizontal offset of the outset shadow. + an offset, in pixels + line="4124">an offset, in pixels a `GskRenderNode` for an outset shadow + line="4120">a `GskRenderNode` for an outset shadow @@ -3355,19 +3806,19 @@ around the box given by @outline. Retrieves the vertical offset of the outset shadow. - + line="4134">Retrieves the vertical offset of the outset shadow. + an offset, in pixels + line="4140">an offset, in pixels a `GskRenderNode` for an outset shadow + line="4136">a `GskRenderNode` for an outset shadow @@ -3376,19 +3827,19 @@ around the box given by @outline. c:identifier="gsk_outset_shadow_node_get_outline"> Retrieves the outline rectangle of the outset shadow. - + line="4066">Retrieves the outline rectangle of the outset shadow. + a rounded rectangle + line="4072">a rounded rectangle a `GskRenderNode` for an outset shadow + line="4068">a `GskRenderNode` for an outset shadow @@ -3397,19 +3848,19 @@ around the box given by @outline. c:identifier="gsk_outset_shadow_node_get_spread"> Retrieves how much the shadow spreads outwards. - + line="4166">Retrieves how much the shadow spreads outwards. + the size of the shadow, in pixels + line="4172">the size of the shadow, in pixels a `GskRenderNode` for an outset shadow + line="4168">a `GskRenderNode` for an outset shadow @@ -3418,9 +3869,9 @@ around the box given by @outline. Type of callback that is called when an error occurs + line="92">Type of callback that is called when an error occurs during node deserialization. - + @@ -3428,19 +3879,19 @@ during node deserialization. start of the error location + line="94">start of the error location end of the error location + line="95">end of the error location the error + line="96">the error closure="3"> user data + line="97">user data @@ -3458,617 +3909,3311 @@ during node deserialization. A location in a parse buffer. - + line="73">A location in a parse buffer. + the offset of the location in the parse buffer, as bytes + line="75">the offset of the location in the parse buffer, as bytes the offset of the location in the parse buffer, as characters + line="76">the offset of the location in the parse buffer, as characters the line of the location in the parse buffer + line="77">the line of the location in the parse buffer the position in the line, as bytes + line="78">the position in the line, as bytes the position in the line, as characters + line="79">the position in the line, as characters - - - - - - - - - Initializes a `GskRoundedRect` when declaring it. -All corner sizes will be initialized to 0. - - - - the X coordinate of the origin - - - the Y coordinate of the origin - - - the width - - - the height - - - - + A render node for a radial gradient. - + filename="gsk/gskpath.c" + line="29">Describes lines and curves that are more complex than simple rectangles. + +Paths can used for rendering (filling or stroking) and for animations +(e.g. as trajectories). + +`GskPath` is an immutable, opaque, reference-counted struct. +After creation, you cannot change the types it represents. Instead, +new `GskPath` objects have to be created. The [struct@Gsk.PathBuilder] +structure is meant to help in this endeavor. + +Conceptually, a path consists of zero or more contours (continuous, connected +curves), each of which may or may not be closed. Contours are typically +constructed from Bézier segments. + +<picture> + <source srcset="path-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="A Path" src="path-light.png"> +</picture> + + Creates a `GskRenderNode` that draws a radial gradient. + filename="gsk/gskpath.c" + line="609">Calls @func for every operation of the path. -The radial gradient -starts around @center. The size of the gradient is dictated by @hradius -in horizontal orientation and by @vradius in vertical orientation. - - +Note that this may only approximate @self, because paths can contain +optimizations for various specialized contours, and depending on the +@flags, the path may be decomposed into simpler curves than the ones +that it contained originally. + +This function serves two purposes: + +- When the @flags allow everything, it provides access to the raw, + unmodified data of the path. +- When the @flags disallow certain operations, it provides + an approximation of the path using just the allowed operations. + + A new `GskRenderNode` - + filename="gsk/gskpath.c" + line="630">false if @func returned false, true otherwise. + - + the bounds of the node - - - - the center of the gradient - - - - the horizontal radius - - - - the vertical radius - - - - a percentage >= 0 that defines the start of the gradient around @center - - - + filename="gsk/gskpath.c" + line="611">a path + + + a percentage >= 0 that defines the end of the gradient around @center - + filename="gsk/gskpath.c" + line="612">flags to pass to the foreach function + - + a pointer to an array of - `GskColorStop` defining the gradient. The offsets of all color stops - must be increasing. The first stop's offset must be >= 0 and the last - stop's offset must be <= 1. - - - + filename="gsk/gskpath.c" + line="613">the function to call for operations + - + the number of elements in @color_stops - + filename="gsk/gskpath.c" + line="614">user data passed to @func + - - + + Retrieves the center pointer for the gradient. - + filename="gsk/gskpath.c" + line="346">Computes the bounds of the given path. + +The returned bounds may be larger than necessary, because this +function aims to be fast, not accurate. The bounds are guaranteed +to contain the path. + +It is possible that the returned rectangle has 0 width and/or height. +This can happen when the path only describes a point or an +axis-aligned line. + +If the path is empty, false is returned and @bounds are set to +graphene_rect_zero(). This is different from the case where the path +is a single point at the origin, where the @bounds will also be set to +the zero rectangle but true will be returned. + the center point for the gradient - + filename="gsk/gskpath.c" + line="366">true if the path has bounds, false if the path is known + to be empty and have no bounds + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="348">a path + + + return location for the bounds + + - + Retrieves the color stops in the gradient. - + filename="gsk/gskpath.c" + line="553">Computes the closest point on the path to the given point. + +If there is no point closer than the given threshold, +false is returned. + the color stops in the gradient - - - + filename="gsk/gskpath.c" + line="566">true if @point was set to the closest point + on @self, false if no point is closer than @threshold + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="555">a path + - + the point + + + + maximum allowed distance + + + + return location for the closest point + + + the number of color stops in the returned array - + filename="gsk/gskpath.c" + line="559">return location for the distance + - + Retrieves the end value for the gradient. - + filename="gsk/gskpath.c" + line="522">Gets the end point of the path. + +An empty path has no points, so false +is returned in this case. + the end value for the gradient - + filename="gsk/gskpath.c" + line="532">true if @result was filled + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="524">a path + + + return location for point + + - + Retrieves the horizontal radius for the gradient. - + filename="gsk/gskpath.c" + line="487">Gets the start point of the path. + +An empty path has no points, so false +is returned in this case. + the horizontal radius for the gradient - + filename="gsk/gskpath.c" + line="497">true if @result was filled + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="489">a path + + + return location for point + + - + Retrieves the number of color stops in the gradient. - + filename="gsk/gskpath.c" + line="401">Computes the bounds for stroking the given path with the +given parameters. + +The returned bounds may be larger than necessary, because this +function aims to be fast, not accurate. The bounds are guaranteed +to contain the area affected by the stroke, including protrusions +like miters. + the number of color stops - + filename="gsk/gskpath.c" + line="415">true if the path has bounds, false if the path is known + to be empty and have no bounds. + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="403">a path + + + stroke parameters + + + + the bounds to fill in + + - + Retrieves the start value for the gradient. - + filename="gsk/gskpath.c" + line="451">Returns whether a point is inside the fill area of a path. + +Note that this function assumes that filling a contour +implicitly closes it. + the start value for the gradient - + filename="gsk/gskpath.c" + line="462">true if @point is inside + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="453">a path + + + the point to test + + + + the fill rule to follow + + - + Retrieves the vertical radius for the gradient. - + filename="gsk/gskpath.c" + line="324">Returns if the path represents a single closed contour. + the vertical radius for the gradient - + filename="gsk/gskpath.c" + line="330">true if the path is closed + - + a `GskRenderNode` for a radial gradient - + filename="gsk/gskpath.c" + line="326">a path + - - - `GskRenderNode` is the basic block in a scene graph to be -rendered using [class@Gsk.Renderer]. - -Each node has a parent, except the top-level node; each node may have -children nodes. - -Each node has an associated drawing surface, which has the size of -the rectangle set when creating it. - -Render nodes are meant to be transient; once they have been associated -to a [class@Gsk.Renderer] it's safe to release any reference you have on -them. All [class@Gsk.RenderNode]s are immutable, you can only specify their -properties during construction. - + Loads data previously created via [method@Gsk.RenderNode.serialize]. - -For a discussion of the supported format, see that function. - - + filename="gsk/gskpath.c" + line="306">Checks if the path is empty, i.e. contains no lines or curves. + + a new `GskRenderNode` - + filename="gsk/gskpath.c" + line="312">true if the path is empty + - - the bytes containing the data - - - - Callback on parsing errors - - - + user_data for @error_func - - + filename="gsk/gskpath.c" + line="308">a path + + - - + + Draw the contents of @node to the given cairo context. - -Typically, you'll use this function to implement fallback rendering -of `GskRenderNode`s on an intermediate Cairo context, instead of using -the drawing context associated to a [class@Gdk.Surface]'s rendering buffer. + filename="gsk/gskpath.c" + line="182">Converts the path into a human-readable representation. -For advanced nodes that cannot be supported using Cairo, in particular -for nodes doing 3D operations, this function may fail. - +The string is compatible with (a superset of) +[SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData), +see [func@Gsk.Path.parse] for a summary of the syntax. + - + a `GskRenderNode` - + filename="gsk/gskpath.c" + line="184">a path + - + cairo context to draw to - + filename="gsk/gskpath.c" + line="185">the string to print into + - + Retrieves the boundaries of the @node. + filename="gsk/gskpath.c" + line="139">Increases the reference count of a path by one. + + + the passed in `GskPath` + + + + + a path + + + + + + Appends the path to a cairo context for drawing with Cairo. -The node will not draw outside of its boundaries. - +This may cause some suboptimal conversions to be performed as +Cairo does not support all features of `GskPath`. + +This function does not clear the existing Cairo path. Call +cairo_new_path() if you want this. + - + a `GskRenderNode` - + filename="gsk/gskpath.c" + line="279">a path + - + return location for the boundaries - + filename="gsk/gskpath.c" + line="280">a cairo context + - + Returns the type of the @node. - - + filename="gsk/gskpath.c" + line="212">Converts the path into a human-readable string. + +You can use this function in a debugger to get a quick overview +of the path. + +This is a wrapper around [method@Gsk.Path.print], see that function +for details. + + the type of the `GskRenderNode` - + filename="gsk/gskpath.c" + line="224">a new string for @self + - + a `GskRenderNode` - + filename="gsk/gskpath.c" + line="214">a path + - + Acquires a reference on the given `GskRenderNode`. - - - the `GskRenderNode` with an additional reference - + filename="gsk/gskpath.c" + line="159">Decreases the reference count of a path by one. + +If the resulting reference count is zero, frees the path. + + + - + a `GskRenderNode` - + filename="gsk/gskpath.c" + line="161">a path + - + Serializes the @node for later deserialization via -gsk_render_node_deserialize(). No guarantees are made about the format -used other than that the same version of GTK will be able to deserialize -the result of a call to gsk_render_node_serialize() and -gsk_render_node_deserialize() will correctly reject files it cannot open -that were created with previous versions of GTK. + filename="gsk/gskpathparser.c" + line="358">Constructs a path from a serialized form. -The intended use of this functions is testing, benchmarking and debugging. -The format is not meant as a permanent storage format. - +The string is expected to be in (a superset of) +[SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData), +as e.g. produced by [method@Gsk.Path.to_string]. + +A high-level summary of the syntax: + +- `M x y` Move to `(x, y)` +- `L x y` Add a line from the current point to `(x, y)` +- `Q x1 y1 x2 y2` Add a quadratic Bézier from the current point to `(x2, y2)`, with control point `(x1, y1)` +- `C x1 y1 x2 y2 x3 y3` Add a cubic Bézier from the current point to `(x3, y3)`, with control points `(x1, y1)` and `(x2, y2)` +- `Z` Close the contour by drawing a line back to the start point +- `H x` Add a horizontal line from the current point to the given x value +- `V y` Add a vertical line from the current point to the given y value +- `T x2 y2` Add a quadratic Bézier, using the reflection of the previous segments' control point as control point +- `S x2 y2 x3 y3` Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point +- `A rx ry r l s x y` Add an elliptical arc from the current point to `(x, y)` with radii rx and ry. See the SVG documentation for how the other parameters influence the arc. +- `O x1 y1 x2 y2 w` Add a rational quadratic Bézier from the current point to `(x2, y2)` with control point `(x1, y1)` and weight `w`. + +All the commands have lowercase variants that interpret coordinates +relative to the current point. + +The `O` command is an extension that is not supported in SVG. + + + a new `GskPath`, or `NULL` if @string could not be parsed + + + + + a string + + + + + + + Constructs `GskPath` objects. + +A path is constructed like this: + +|[<!-- language="C" --> +GskPath * +construct_path (void) +{ + GskPathBuilder *builder; + + builder = gsk_path_builder_new (); + + // add contours to the path here + + return gsk_path_builder_free_to_path (builder); +]| + +Adding contours to the path can be done in two ways. +The easiest option is to use the `gsk_path_builder_add_*` group +of functions that add predefined contours to the current path, +either common shapes like [method@Gsk.PathBuilder.add_circle] +or by adding from other paths like [method@Gsk.PathBuilder.add_path]. + +The `gsk_path_builder_add_*` methods always add complete contours, +and do not use or modify the current point. + +The other option is to define each line and curve manually with +the `gsk_path_builder_*_to` group of functions. You start with +a call to [method@Gsk.PathBuilder.move_to] to set the starting point +and then use multiple calls to any of the drawing functions to +move the pen along the plane. Once you are done, you can call +[method@Gsk.PathBuilder.close] to close the path by connecting it +back with a line to the starting point. + +This is similar to how paths are drawn in Cairo. + +Note that `GskPathBuilder` will reduce the degree of added Bézier +curves as much as possible, to simplify rendering. + + + Create a new `GskPathBuilder` object. + +The resulting builder would create an empty `GskPath`. +Use addition functions to add types to it. + a `GBytes` representing the node. - + filename="gsk/gskpathbuilder.c" + line="102">a new `GskPathBuilder` + + + + + Adds a Cairo path to the builder. + +You can use cairo_copy_path() to access the path +from a Cairo context. + + + - + a `GskRenderNode` - + filename="gsk/gskpathbuilder.c" + line="388">a path builder + + + a path + + - + Releases a reference on the given `GskRenderNode`. + filename="gsk/gskpathbuilder.c" + line="492">Adds a circle as a new contour. -If the reference was the last, the resources associated to the @node are -freed. - +The path is going around the circle in clockwise direction. + +If @radius is zero, the contour will be a closed point. + - + a `GskRenderNode` - + filename="gsk/gskpathbuilder.c" + line="494">a path builder + + + the center of the circle + + + + the radius of the circle + + - + This function is equivalent to calling [method@Gsk.RenderNode.serialize] -followed by [func@GLib.file_set_contents]. + filename="gsk/gskpathbuilder.c" + line="1610">Adds the outlines for the glyphs in @layout to the builder. + + + + + + + a path builder + + + + the pango layout to add + + + + + + Appends all of @path to the builder. + + + + + + + a path builder + + + + the path to append + + + + + + Adds a rectangle as a new contour. -See those two functions for details on the arguments. +The path is going around the rectangle in clockwise direction. -It is mostly intended for use inside a debugger to quickly dump a render -node to a file for later inspection. - +If the the width or height are 0, the path will be a closed +horizontal or vertical line. If both are 0, it'll be a closed dot. + - %TRUE if saving was successful - + - + a `GskRenderNode` - + filename="gsk/gskpathbuilder.c" + line="446">a path builder + - + the file to save it to. - + filename="gsk/gskpathbuilder.c" + line="447">the rectangle to create a path for + - - - The type of a node determines what the node is rendering. - + Error type. No node will ever have this type. - - + filename="gsk/gskpathbuilder.c" + line="362">Appends all of @path to the builder, in reverse order. + + + + + + + a path builder + + + + the path to append + + + + + A node containing a stack of children - - + filename="gsk/gskpathbuilder.c" + line="471">Adds a rounded rectangle as a new contour. + +The path is going around the rectangle in clockwise direction. + + + + + + + a path builder + + + + the rounded rect + + + + + A node drawing a `cairo_surface_t` - - + filename="gsk/gskpathbuilder.c" + line="1640">Adds a segment of a path to the builder. + +If @start is equal to or after @end, the path will first add the +segment from @start to the end of the path, and then add the segment +from the beginning to @end. If the path is closed, these segments +will be connected. + +Note that this method always adds a path with the given start point +and end point. To add a closed path, use [method@Gsk.PathBuilder.add_path]. + + + + + + + a path builder + + + + the path to take the segment to + + + + the point on @path to start at + + + + the point on @path to end at + + + + + A node drawing a single color rectangle - - Adds an elliptical arc from the current point to @x2, @y2 +with @x1, @y1 determining the tangent directions. + +After this, @x2, @y2 will be the new current point. + +Note: Two points and their tangents do not determine +a unique ellipse, so GSK just picks one. If you need more +precise control, use [method@Gsk.PathBuilder.conic_to] +or [method@Gsk.PathBuilder.svg_arc_to]. + +<picture> + <source srcset="arc-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Arc To" src="arc-light.png"> +</picture> + + + + + + + a path builder + + + + x coordinate of first control point + + + + y coordinate of first control point + + + + x coordinate of second control point + + + + y coordinate of second control point + + + + + + Ends the current contour with a line back to the start point. + +Note that this is different from calling [method@Gsk.PathBuilder.line_to] +with the start point in that the contour will be closed. A closed +contour behaves differently from an open one. When stroking, its +start and end point are considered connected, so they will be +joined via the line join, and not ended with line caps. + + + + + + + a path builder + + + + + + Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline) +from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the +control point. + +The weight determines how strongly the curve is pulled towards the control point. +A conic with weight 1 is identical to a quadratic Bézier curve with the same points. + +Conic curves can be used to draw ellipses and circles. They are also known as +rational quadratic Bézier curves. + +After this, @x2, @y2 will be the new current point. + +<picture> + <source srcset="conic-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Conic To" src="conic-light.png"> +</picture> + + + + + + + a path builder + + + + x coordinate of control point + + + + y coordinate of control point + + + + x coordinate of the end of the curve + + + + y coordinate of the end of the curve + + + + weight of the control point, must be greater than zero + + + + + + Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) +from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control +points. + +After this, @x3, @y3 will be the new current point. + +<picture> + <source srcset="cubic-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Cubic To" src="cubic-light.png"> +</picture> + + + + + + + a path builder + + + + x coordinate of first control point + + + + y coordinate of first control point + + + + x coordinate of second control point + + + + y coordinate of second control point + + + + x coordinate of the end of the curve + + + + y coordinate of the end of the curve + + + + + + Creates a new path from the current state of the +builder, and unrefs the builder. + + + the newly created path + with all the contours added to the builder + + + + + a path builder + + + + + + Gets the current point. + +The current point is used for relative drawing commands and +updated after every operation. + +When the builder is created, the default current point is set +to `0, 0`. Note that this is different from cairo, which starts +out without a current point. + + + the current point + + + + + a path builder + + + + + + Implements arc-to according to the HTML Canvas spec. + +A convenience function that implements the +[HTML arc_to](https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-arcto-dev) +functionality. + +After this, the current point will be the point where +the circle with the given radius touches the line from +@x1, @y1 to @x2, @y2. + + + + + + + a path builder + + + + x coordinate of first control point + + + + y coordinate of first control point + + + + x coordinate of second control point + + + + y coordinate of second control point + + + + radius of the circle + + + + + + Draws a line from the current point to @x, @y and makes it +the new current point. + +<picture> + <source srcset="line-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Line To" src="line-light.png"> +</picture> + + + + + + + a path builder + + + + x coordinate + + + + y coordinate + + + + + + Starts a new contour by placing the pen at @x, @y. + +If this function is called twice in succession, the first +call will result in a contour made up of a single point. +The second call will start a new contour. + + + + + + + a path builder + + + + x coordinate + + + + y coordinate + + + + + + Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) +from the current point to @x2, @y2 with @x1, @y1 as the control point. + +After this, @x2, @y2 will be the new current point. + +<picture> + <source srcset="quad-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Quad To" src="quad-light.png"> +</picture> + + + + + + + a path builder + + + + x coordinate of control point + + + + y coordinate of control point + + + + x coordinate of the end of the curve + + + + y coordinate of the end of the curve + + + + + + Acquires a reference on the given builder. + +This function is intended primarily for language bindings. +`GskPathBuilder` objects should not be kept around. + + + the given path builder with + its reference count increased + + + + + a path builder + + + + + + Adds an elliptical arc from the current point to @x2, @y2 +with @x1, @y1 determining the tangent directions. + +All coordinates are given relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.arc_to]. + + + + + + + a path builder + + + + x coordinate of first control point + + + + y coordinate of first control point + + + + x coordinate of second control point + + + + y coordinate of second control point + + + + + + Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline) +from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the +control point. + +All coordinates are given relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.conic_to]. + + + + + + + a path builder + + + + x offset of control point + + + + y offset of control point + + + + x offset of the end of the curve + + + + y offset of the end of the curve + + + + weight of the curve, must be greater than zero + + + + + + Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) +from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control +points. + +All coordinates are given relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.cubic_to]. + + + + + + + a path builder + + + + x offset of first control point + + + + y offset of first control point + + + + x offset of second control point + + + + y offset of second control point + + + + x offset of the end of the curve + + + + y offset of the end of the curve + + + + + + Implements arc-to according to the HTML Canvas spec. + +All coordinates are given relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.html_arc_to]. + + + + + + + a path builder + + + + x coordinate of first control point + + + + y coordinate of first control point + + + + x coordinate of second control point + + + + y coordinate of second control point + + + + radius of the circle + + + + + + Draws a line from the current point to a point offset from it +by @x, @y and makes it the new current point. + +This is the relative version of [method@Gsk.PathBuilder.line_to]. + + + + + + + a path builder + + + + x offset + + + + y offset + + + + + + Starts a new contour by placing the pen at @x, @y +relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.move_to]. + + + + + + + a path builder + + + + x offset + + + + y offset + + + + + + Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) +from the current point to @x2, @y2 with @x1, @y1 the control point. + +All coordinates are given relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.quad_to]. + + + + + + + a path builder + + + + x offset of control point + + + + y offset of control point + + + + x offset of the end of the curve + + + + y offset of the end of the curve + + + + + + Implements arc-to according to the SVG spec. + +All coordinates are given relative to the current point. + +This is the relative version of [method@Gsk.PathBuilder.svg_arc_to]. + + + + + + + a path builder + + + + x radius + + + + y radius + + + + the rotation of the ellipsis + + + + whether to add the large arc + + + + whether to sweep in the positive direction + + + + x coordinate of the endpoint + + + + y coordinate of the endpoint + + + + + + Implements arc-to according to the SVG spec. + +A convenience function that implements the +[SVG arc_to](https://www.w3.org/TR/SVG11/paths.html#PathDataEllipticalArcCommands) +functionality. + +After this, @x, @y will be the new current point. + + + + + + + a path builder + + + + x radius + + + + y radius + + + + the rotation of the ellipsis + + + + whether to add the large arc + + + + whether to sweep in the positive direction + + + + x coordinate of the endpoint + + + + y coordinate of the endpoint + + + + + + Creates a new path from the given builder. + +The given `GskPathBuilder` is reset once this function returns; +you cannot call this function multiple times on the same builder +instance. + +This function is intended primarily for language bindings. +C code should use [method@Gsk.PathBuilder.free_to_path]. + + + the newly created path + with all the contours added to the builder + + + + + a path builder + + + + + + Releases a reference on the given builder. + + + + + + + a path builder + + + + + + + Used to pick one of the four tangents at a given point on the path. + +Note that the directions for @GSK_PATH_FROM_START/@GSK_PATH_TO_END and +@GSK_PATH_TO_START/@GSK_PATH_FROM_END will coincide for smooth points. +Only sharp turns will exhibit four different directions. + +<picture> + <source srcset="directions-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Path Tangents" src="directions-light.png"> +</picture> + + The tangent in path direction of the incoming side + of the path + + + The tangent against path direction of the incoming side + of the path + + + The tangent in path direction of the outgoing side + of the path + + + The tangent against path direction of the outgoing + side of the path + + + + Flags that can be passed to gsk_path_foreach() to influence what +kinds of operations the path is decomposed into. + +By default, [method@Gsk.Path.foreach] will only emit a path with all +operations flattened to straight lines to allow for maximum compatibility. +The only operations emitted will be `GSK_PATH_MOVE`, `GSK_PATH_LINE` and +`GSK_PATH_CLOSE`. + + The default behavior, only allow lines. + + + Allow emission of `GSK_PATH_QUAD` operations + + + Allow emission of `GSK_PATH_CUBIC` operations. + + + Allow emission of `GSK_PATH_CONIC` operations. + + + + Type of the callback to iterate through the operations of a path. + +For each operation, the callback is given the @op itself, the points +that the operation is applied to in @pts, and a @weight for conic +curves. The @n_pts argument is somewhat redundant, since the number +of points can be inferred from the operation. + +Each contour of the path starts with a @GSK_PATH_MOVE operation. +Closed contours end with a @GSK_PATH_CLOSE operation. + + + %TRUE to continue iterating the path, %FALSE to + immediately abort and not call the function again. + + + + + The operation + + + + The points of the operation + + + + The number of points + + + + The weight for conic curves, or unused if not a conic curve + + + + The user data provided with the function + + + + + + Performs measurements on paths such as determining the length of the path. + +Many measuring operations require sampling the path length +at intermediate points. Therefore, a `GskPathMeasure` has +a tolerance that determines what precision is required +for such approximations. + +A `GskPathMeasure` struct is a reference counted struct +and should be treated as opaque. + + + Creates a measure object for the given @path with the +default tolerance. + + + a new `GskPathMeasure` representing @path + + + + + the path to measure + + + + + + Creates a measure object for the given @path and @tolerance. + + + a new `GskPathMeasure` representing @path + + + + + the path to measure + + + + the tolerance for measuring operations + + + + + + Gets the length of the path being measured. + +The length is cached, so this function does not do any work. + + + the length of the path measured by @self + + + + + a path measure + + + + + + Returns the path that the measure was created for. + + + the path of @self + + + + + a path measure + + + + + + Gets the point at the given distance into the path. + +An empty path has no points, so false is returned in that case. + + + true if @result was set + + + + + a path measure + + + + the distance + + + + return location for the point + + + + + + Returns the tolerance that the measure was created with. + + + the tolerance of @self + + + + + a path measure + + + + + + Increases the reference count of a `GskPathMeasure` by one. + + + the passed in `GskPathMeasure`. + + + + + a path measure + + + + + + Decreases the reference count of a `GskPathMeasure` by one. + +If the resulting reference count is zero, frees the object. + + + + + + + a path measure + + + + + + + Describes the segments of a `GskPath`. + +More values may be added in the future. + + A move-to operation, with 1 point describing the target point. + + + A close operation ending the current contour with a line back + to the starting point. Two points describe the start and end of the line. + + + A line-to operation, with 2 points describing the start and + end point of a straight line. + + + A curve-to operation describing a quadratic Bézier curve + with 3 points describing the start point, the control point and the end + point of the curve. + + + A curve-to operation describing a cubic Bézier curve with 4 + points describing the start point, the two control points and the end point + of the curve. + + + A rational quadratic Bézier curve with 3 points describing + the start point, control point and end point of the curve. A weight for the + curve will be passed, too. + + + + An opaque type representing a point on a path. + +It can be queried for properties of the path at that point, +such as its tangent or its curvature. + +To obtain a `GskPathPoint`, use [method@Gsk.Path.get_closest_point], +[method@Gsk.Path.get_start_point], [method@Gsk.Path.get_end_point] +or [method@Gsk.PathMeasure.get_point]. + +Note that `GskPathPoint` structs are meant to be stack-allocated, +and don't hold a reference to the path object they are obtained from. +It is the callers responsibility to keep a reference to the path +as long as the `GskPathPoint` is used. + + + + + + + + + + + + + + + + + + + + + + + + + + Returns whether @point1 is before or after @point2. + + + -1 if @point1 is before @point2, + 1 if @point1 is after @point2, + 0 if they are equal + + + + + a path point + + + + another path point + + + + + + Copies a path point. + + + the copied point + + + + + a path point + + + + + + Returns whether the two path points refer to the same +location on all paths. + +Note that the start- and endpoint of a closed contour +will compare nonequal according to this definition. +Use [method@Gsk.Path.is_closed] to find out if the +start- and endpoint of a concrete path refer to the +same location. + + + true if @point1 and @point2 are equal + + + + + a path point + + + + another path point + + + + + + Frees a path point copied by [method@Gsk.PathPoint.copy]. + + + + + + + a path point + + + + + + Calculates the curvature of the path at the point. + +Optionally, returns the center of the osculating circle as well. +The curvature is the inverse of the radius of the osculating circle. + +Lines have a curvature of zero (indicating an osculating circle of +infinite radius). In this case, the @center is not modified. + +Circles with a radius of zero have `INFINITY` as curvature + +Note that certain points on a path may not have a single curvature, +such as sharp turns. At such points, there are two curvatures — the +(limit of) the curvature of the path going into the point, and the +(limit of) the curvature of the path coming out of it. The @direction +argument lets you choose which one to get. + +<picture> + <source srcset="curvature-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Osculating circle" src="curvature-light.png"> +</picture> + + + the curvature of the path at the given point + + + + + a path point + + + + the path that @point is on + + + + the direction for which to return the curvature + + + + return location for + the center of the osculating circle + + + + + + Returns the distance from the beginning of the path +to the point. + + + the distance of @point + + + + + a point on the path + + + + a path measure for the path + + + + + + Gets the position of the point. + + + + + + + a path point + + + + the path that @point is on + + + + Return location for + the coordinates of the point + + + + + + Gets the direction of the tangent at a given point. + +This is a convenience variant of [method@Gsk.PathPoint.get_tangent] +that returns the angle between the tangent and the X axis. The angle +can e.g. be used in +[gtk_snapshot_rotate()](../gtk4/method.Snapshot.rotate.html). + + + the angle between the tangent and the X axis, in degrees + + + + + a path point + + + + the path that @point is on + + + + the direction for which to return the rotation + + + + + + Gets the tangent of the path at the point. + +Note that certain points on a path may not have a single +tangent, such as sharp turns. At such points, there are +two tangents — the direction of the path going into the +point, and the direction coming out of it. The @direction +argument lets you choose which one to get. + +If the path is just a single point (e.g. a circle with +radius zero), then the tangent is set to `0, 0`. + +If you want to orient something in the direction of the +path, [method@Gsk.PathPoint.get_rotation] may be more +convenient to use. + + + + + + + a path point + + + + the path that @point is on + + + + the direction for which to return the tangent + + + + Return location for + the tangent at the point + + + + + + + + + + + + + + Initializes a `GskRoundedRect` when declaring it. + +All corner sizes will be initialized to 0. + + + + the X coordinate of the origin + + + the Y coordinate of the origin + + + the width + + + the height + + + + + A render node for a radial gradient. + + Creates a `GskRenderNode` that draws a radial gradient. + +The radial gradient +starts around @center. The size of the gradient is dictated by @hradius +in horizontal orientation and by @vradius in vertical orientation. + + + A new `GskRenderNode` + + + + + the bounds of the node + + + + the center of the gradient + + + + the horizontal radius + + + + the vertical radius + + + + a percentage >= 0 that defines the start of the gradient around @center + + + + a percentage >= 0 that defines the end of the gradient around @center + + + + a pointer to an array of + `GskColorStop` defining the gradient. The offsets of all color stops + must be increasing. The first stop's offset must be >= 0 and the last + stop's offset must be <= 1. + + + + + + the number of elements in @color_stops + + + + + + Retrieves the center pointer for the gradient. + + + the center point for the gradient + + + + + a `GskRenderNode` for a radial gradient + + + + + + Retrieves the color stops in the gradient. + + + the color stops in the gradient + + + + + + + a `GskRenderNode` for a radial gradient + + + + the number of color stops in the returned array + + + + + + Retrieves the end value for the gradient. + + + the end value for the gradient + + + + + a `GskRenderNode` for a radial gradient + + + + + + Retrieves the horizontal radius for the gradient. + + + the horizontal radius for the gradient + + + + + a `GskRenderNode` for a radial gradient + + + + + + Retrieves the number of color stops in the gradient. + + + the number of color stops + + + + + a `GskRenderNode` for a radial gradient + + + + + + Retrieves the start value for the gradient. + + + the start value for the gradient + + + + + a `GskRenderNode` for a radial gradient + + + + + + Retrieves the vertical radius for the gradient. + + + the vertical radius for the gradient + + + + + a `GskRenderNode` for a radial gradient + + + + + + + `GskRenderNode` is the basic block in a scene graph to be +rendered using [class@Gsk.Renderer]. + +Each node has a parent, except the top-level node; each node may have +children nodes. + +Each node has an associated drawing surface, which has the size of +the rectangle set when creating it. + +Render nodes are meant to be transient; once they have been associated +to a [class@Gsk.Renderer] it's safe to release any reference you have on +them. All [class@Gsk.RenderNode]s are immutable, you can only specify their +properties during construction. + + Loads data previously created via [method@Gsk.RenderNode.serialize]. + +For a discussion of the supported format, see that function. + + + a new render node + + + + + the bytes containing the data + + + + callback on parsing errors + + + + user_data for @error_func + + + + + + Draws the contents of a render node on a cairo context. + +Typically, you'll use this function to implement fallback rendering +of render nodes on an intermediate Cairo context, instead of using +the drawing context associated to a [class@Gdk.Surface]'s rendering buffer. + +For advanced nodes that cannot be supported using Cairo, in particular +for nodes doing 3D operations, this function may fail. + + + + + + + a render node + + + + cairo context to draw to + + + + + + Retrieves the boundaries of the @node. + +The node will not draw outside of its boundaries. + + + + + + + a render node + + + + return location for the boundaries + + + + + + Returns the type of the render node. + + + the type of @node + + + + + a render node + + + + + + Gets an opaque rectangle inside the node that GTK can determine to +be fully opaque. + +There is no guarantee that this is indeed the largest opaque rectangle or +that regions outside the rectangle are not opaque. This function is a best +effort with that goal. + +The rectangle will be fully contained in the bounds of the node. + + + true if part or all of the rendernode is opaque, false if no + opaque region could be found. + + + + + a render node + + + + return location for the opaque rect + + + + + + Acquires a reference on the given `GskRenderNode`. + + + the render node with an additional reference + + + + + a render node + + + + + + Serializes the @node for later deserialization via +gsk_render_node_deserialize(). No guarantees are made about the format +used other than that the same version of GTK will be able to deserialize +the result of a call to gsk_render_node_serialize() and +gsk_render_node_deserialize() will correctly reject files it cannot open +that were created with previous versions of GTK. + +The intended use of this functions is testing, benchmarking and debugging. +The format is not meant as a permanent storage format. + + + a `GBytes` representing the node. + + + + + a `GskRenderNode` + + + + + + Releases a reference on the given `GskRenderNode`. + +If the reference was the last, the resources associated to the @node are +freed. + + + + + + + a render node + + + + + + This function is equivalent to calling [method@Gsk.RenderNode.serialize] +followed by [func@GLib.file_set_contents]. + +See those two functions for details on the arguments. + +It is mostly intended for use inside a debugger to quickly dump a render +node to a file for later inspection. + + + true if saving was successful + + + + + a render node + + + + the file to save it to + + + + + + + The type of a node determines what the node is rendering. + + Error type. No node will ever have this type. + + + A node containing a stack of children + + + A node drawing a `cairo_surface_t` + + + A node drawing a single color rectangle + + glib:nick="rounded-clip-node" glib:name="GSK_ROUNDED_CLIP_NODE"> A node that clips its child to a rounded rectangle - - + filename="gsk/gskenums.h" + line="44">A node that clips its child to a rounded rectangle + + + A node that draws a shadow below its child + + + A node that blends two children together + + + A node that cross-fades between two children + + + A node containing a glyph string + + + A node that applies a blur + + + Debug information that does not affect the rendering + + + A node that uses OpenGL fragment shaders to render + + + A node drawing a `GdkTexture` scaled and filtered. + + + A node that masks one child with another. + + + A node that fills a path. + + + A node that strokes a path. + + + A node that possibly redirects part of the scene graph to a subsurface. + + + + A class that renders a scene graph defined via a tree of +[class@Gsk.RenderNode] instances. + +Typically you will use a `GskRenderer` instance to repeatedly call +[method@Gsk.Renderer.render] to update the contents of its associated +[class@Gdk.Surface]. + +It is necessary to realize a `GskRenderer` instance using +[method@Gsk.Renderer.realize] before calling [method@Gsk.Renderer.render], +in order to create the appropriate windowing system resources needed +to render the scene. + + + Creates an appropriate `GskRenderer` instance for the given surface. + +If the `GSK_RENDERER` environment variable is set, GSK will +try that renderer first, before trying the backend-specific +default. The ultimate fallback is the cairo renderer. + +The renderer will be realized before it is returned. + + + the realized renderer + + + + + a surface + + + + + + Retrieves the surface that the renderer is associated with. + +If the renderer has not been realized yet, `NULL` will be returned. + + + the surface + + + + + a renderer + + + + + + Checks whether the renderer is realized or not. + + + true if the renderer was realized, false otherwise + + + + + a renderer + + + + + + Creates the resources needed by the renderer. + +Since GTK 4.6, the surface may be `NULL`, which allows using +renderers without having to create a surface. Since GTK 4.14, +it is recommended to use [method@Gsk.Renderer.realize_for_display] +for this case. + +Note that it is mandatory to call [method@Gsk.Renderer.unrealize] +before destroying the renderer. + + + whether the renderer was successfully realized + + + + + a renderer + + + + the surface that renderer will be used on + + + + + + Creates the resources needed by the renderer. + +Note that it is mandatory to call [method@Gsk.Renderer.unrealize] +before destroying the renderer. + + + whether the renderer was successfully realized + + + + + a renderer + + + + the display that the renderer will be used on + + + + + A node that draws a shadow below its child - - + filename="gsk/gskrenderer.c" + line="420">Renders the scene graph, described by a tree of `GskRenderNode` instances +to the renderer's surface, ensuring that the given region gets redrawn. + +If the renderer has no associated surface, this function does nothing. + +Renderers must ensure that changes of the contents given by the @root +node as well as the area given by @region are redrawn. They are however +free to not redraw any pixel outside of @region if they can guarantee that +it didn't change. + +The renderer will acquire a reference on the `GskRenderNode` tree while +the rendering is in progress. + + + + + + + a realized renderer + + + + the render node to render + + + + the `cairo_region_t` that must be redrawn or `NULL` + for the whole surface + + + + + A node that blends two children together - - + filename="gsk/gskrenderer.c" + line="377">Renders a scene graph, described by a tree of `GskRenderNode` instances, +to a texture. + +The renderer will acquire a reference on the `GskRenderNode` tree while +the rendering is in progress. + +If you want to apply any transformations to @root, you should put it into a +transform node and pass that node instead. + + + a texture with the rendered contents of @root + + + + + a realized renderer + + + + the render node to render + + + + the section to draw or `NULL` to use @root's bounds + + + + + A node that cross-fades between two children - - + filename="gsk/gskrenderer.c" + line="346">Releases all the resources created by [method@Gsk.Renderer.realize]. + + + + + + + a renderer + + + + + A node containing a glyph string - - + filename="gsk/gskrenderer.c" + line="178">Whether the renderer has been associated with a surface or draw context. + + + A node that applies a blur - - + filename="gsk/gskrenderer.c" + line="188">The surface associated with renderer. + + + + + + + + A render node repeating its single child node. + Debug information that does not affect the rendering - - + filename="gsk/gskrendernodeimpl.c" + line="5556">Creates a `GskRenderNode` that will repeat the drawing of @child across +the given @bounds. + + + A new `GskRenderNode` + + + + + The bounds of the area to be painted + + + + The child to repeat + + + + The area of the child to repeat or %NULL to + use the child's bounds + + + + + A node that uses OpenGL fragment shaders to render - - + filename="gsk/gskrendernodeimpl.c" + line="5607">Retrieves the child of @node. + + + a `GskRenderNode` + + + + + a repeat `GskRenderNode` + + + + + A node drawing a `GdkTexture` scaled and filtered (Since: 4.10) - - + filename="gsk/gskrendernodeimpl.c" + line="5623">Retrieves the bounding rectangle of the child of @node. + + + a bounding rectangle + + + + + a repeat `GskRenderNode` + + + + + + + A render node for a repeating linear gradient. + A node that masks one child with another (Since: 4.10) - - - + filename="gsk/gskrendernodeimpl.c" + line="744">Creates a `GskRenderNode` that will create a repeating linear gradient +from the given points and color stops, and render that into the area +given by @bounds. + + + A new `GskRenderNode` + + + + + the rectangle to render the linear gradient into + + + + the point at which the linear gradient will begin + + + + the point at which the linear gradient will finish + + + + a pointer to an array of +`GskColorStop` defining the gradient. The offsets of all color stops + must be increasing. The first stop's offset must be >= 0 and the last + stop's offset must be <= 1. + + + + + + the number of elements in @color_stops + + + + + + `GskRenderer` is a class that renders a scene graph defined via a -tree of [class@Gsk.RenderNode] instances. - -Typically you will use a `GskRenderer` instance to repeatedly call -[method@Gsk.Renderer.render] to update the contents of its associated -[class@Gdk.Surface]. - -It is necessary to realize a `GskRenderer` instance using -[method@Gsk.Renderer.realize] before calling [method@Gsk.Renderer.render], -in order to create the appropriate windowing system resources needed -to render the scene. - - + filename="gsk/gskrendernodeimpl.c" + line="1009">A render node for a repeating radial gradient. + Creates an appropriate `GskRenderer` instance for the given @surface. - -If the `GSK_RENDERER` environment variable is set, GSK will -try that renderer first, before trying the backend-specific -default. The ultimate fallback is the cairo renderer. + filename="gsk/gskrendernodeimpl.c" + line="1350">Creates a `GskRenderNode` that draws a repeating radial gradient. -The renderer will be realized before it is returned. - - +The radial gradient starts around @center. The size of the gradient +is dictated by @hradius in horizontal orientation and by @vradius +in vertical orientation. + + a `GskRenderer` - + filename="gsk/gskrendernodeimpl.c" + line="1370">A new `GskRenderNode` + - + a `GdkSurface` - + filename="gsk/gskrendernodeimpl.c" + line="1352">the bounds of the node + + + + the center of the gradient + + + + the horizontal radius + + + + the vertical radius + + + + a percentage >= 0 that defines the start of the gradient around @center + + + + a percentage >= 0 that defines the end of the gradient around @center + + + + a pointer to an array of + `GskColorStop` defining the gradient. The offsets of all color stops + must be increasing. The first stop's offset must be >= 0 and the last + stop's offset must be <= 1. + + + + + + the number of elements in @color_stops + - - + + + A render node applying a rounded rectangle clip to its single child. + Retrieves the `GdkSurface` set using gsk_enderer_realize(). - -If the renderer has not been realized yet, %NULL will be returned. - - + filename="gsk/gskrendernodeimpl.c" + line="5923">Creates a `GskRenderNode` that will clip the @child to the area +given by @clip. + + a `GdkSurface` - + filename="gsk/gskrendernodeimpl.c" + line="5931">A new `GskRenderNode` + - + a `GskRenderer` - + filename="gsk/gskrendernodeimpl.c" + line="5925">The node to draw + + + + The clip to apply + + + + + + Gets the child node that is getting clipped by the given @node. + + + The child that is getting clipped + + + + + a rounded clip `GskRenderNode` + + + + + + Retrieves the rounded rectangle used to clip the contents of the @node. + + + a rounded rectangle + + + + + a rounded clip `GskRenderNode` + - - + + + A rectangular region with rounded corners. + +Application code should normalize rectangles using +[method@Gsk.RoundedRect.normalize]; this function will ensure that +the bounds of the rectangle are normalized and ensure that the corner +values are positive and the corners do not overlap. + +All functions taking a `GskRoundedRect` as an argument will internally +operate on a normalized copy; all functions returning a `GskRoundedRect` +will always return a normalized one. + +The algorithm used for normalizing corner sizes is described in +[the CSS specification](https://drafts.csswg.org/css-backgrounds-3/#border-radius). + + + the bounds of the rectangle + + + + the size of the 4 rounded corners + + + + + Checks whether the @renderer is realized or not. - + filename="gsk/gskroundedrect.c" + line="483">Checks if the given point is inside the rounded rectangle. + %TRUE if the `GskRenderer` was realized, and %FALSE otherwise + filename="gsk/gskroundedrect.c" + line="490">true if the point is inside the rounded rectangle - + a `GskRenderer` - + filename="gsk/gskroundedrect.c" + line="485">a rounded rectangle + + + the point to check + + - + Creates the resources needed by the @renderer to render the scene -graph. - -Since GTK 4.6, the surface may be `NULL`, which allows using -renderers without having to create a surface. - -Note that it is mandatory to call [method@Gsk.Renderer.unrealize] before -destroying the renderer. - + filename="gsk/gskroundedrect.c" + line="499">Checks if the given rectangle is contained inside the rounded rectangle. + Whether the renderer was successfully realized + filename="gsk/gskroundedrect.c" + line="506">true if the @rect is fully contained inside the rounded rectangle - + a `GskRenderer` - + filename="gsk/gskroundedrect.c" + line="501">a rounded rectangle + - + the `GdkSurface` renderer will be used on - + filename="gsk/gskroundedrect.c" + line="502">the rectangle to check + - + Renders the scene graph, described by a tree of `GskRenderNode` instances -to the renderer's surface, ensuring that the given @region gets redrawn. - -If the renderer has no associated surface, this function does nothing. - -Renderers must ensure that changes of the contents given by the @root -node as well as the area given by @region are redrawn. They are however -free to not redraw any pixel outside of @region if they can guarantee that -it didn't change. + filename="gsk/gskroundedrect.c" + line="95">Initializes a rounded rectangle with the given values. -The @renderer will acquire a reference on the `GskRenderNode` tree while -the rendering is in progress. - +This function will implicitly normalize the rounded rectangle +before returning. + - + the initialized rounded rectangle + - + a realized `GskRenderer` - + filename="gsk/gskroundedrect.c" + line="97">the rounded rectangle to initialize + - + a `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="98">a `graphene_rect_t` describing the bounds + - + the `cairo_region_t` that must be redrawn or %NULL - for the whole window - + filename="gsk/gskroundedrect.c" + line="99">the rounding radius of the top left corner + + + + the rounding radius of the top right corner + + + + the rounding radius of the bottom right corner + + + + the rounding radius of the bottom left corner + - + Renders the scene graph, described by a tree of `GskRenderNode` instances, -to a `GdkTexture`. - -The @renderer will acquire a reference on the `GskRenderNode` tree while -the rendering is in progress. + filename="gsk/gskroundedrect.c" + line="130">Initializes a rounded rectangle with a copy. -If you want to apply any transformations to @root, you should put it into a -transform node and pass that node instead. - - +This function will not normalize the rounded rectangle, +so make sure the source is normalized. + + a `GdkTexture` with the rendered contents of @root. - + filename="gsk/gskroundedrect.c" + line="140">the initialized rounded rectangle + - + a realized `GskRenderer` - + filename="gsk/gskroundedrect.c" + line="132">the rounded rectangle to initialize + - - a `GskRenderNode` - - - + the section to draw or %NULL to use @root's bounds - + filename="gsk/gskroundedrect.c" + line="133">another rounded rectangle + - + Releases all the resources created by gsk_renderer_realize(). - + filename="gsk/gskroundedrect.c" + line="151">Initializes a rounded rectangle to the given bounds +and sets the radius of all four corners equally. + - + the initialized rounded rectangle + - + a `GskRenderer` - + filename="gsk/gskroundedrect.c" + line="153">the rounded rectangle to initialize + + + a `graphene_rect_t` + + + + the border radius + + - - - Whether the renderer has been associated with a surface or draw context. - - - - - The surface associated with renderer. - - - - - - - - A render node repeating its single child node. - + Creates a `GskRenderNode` that will repeat the drawing of @child across -the given @bounds. - - + filename="gsk/gskroundedrect.c" + line="556">Checks if part a rectangle is contained +inside the rounded rectangle. + + A new `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="564">true if the @rect intersects with the rounded rectangle + - - The bounds of the area to be painted - - - + The child to repeat - - - + filename="gsk/gskroundedrect.c" + line="558">a rounded rectangle + + + The area of the child to repeat or %NULL to - use the child's bounds + filename="gsk/gskroundedrect.c" + line="559">the rectangle to check - - + + Retrieves the child of @node. - + filename="gsk/gskroundedrect.c" + line="395">Checks if all corners of a rounded rectangle are right angles +and the rectangle covers all of its bounds. + +This information can be used to decide if [ctor@Gsk.ClipNode.new] +or [ctor@Gsk.RoundedClipNode.new] should be called. + a `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="405">true if the rounded rectangle is rectilinear + - + a repeat `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="397">the rounded rectangle to check + - + Retrieves the bounding rectangle of the child of @node. - + filename="gsk/gskroundedrect.c" + line="172">Normalizes a rounded rectangle. + +This function will ensure that the bounds of the rounded rectangle +are normalized and ensure that the corner values are positive +and the corners do not overlap. + a bounding rectangle - + filename="gsk/gskroundedrect.c" + line="182">the normalized rounded rectangle + - + a repeat `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="174">a rounded rectangle + - - - A render node for a repeating linear gradient. - + Creates a `GskRenderNode` that will create a repeating linear gradient -from the given points and color stops, and render that into the area -given by @bounds. - - + filename="gsk/gskroundedrect.c" + line="192">Offsets the rounded rectangle's origin by @dx and @dy. + +The size and corners of the rounded rectangle are unchanged. + + A new `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="202">the offset rounded rectangle + - - the rectangle to render the linear gradient into - - - - the point at which the linear gradient will begin - - - + the point at which the linear gradient will finish - - - + filename="gsk/gskroundedrect.c" + line="194">a rounded rectangle + + + a pointer to an array of -`GskColorStop` defining the gradient. The offsets of all color stops - must be increasing. The first stop's offset must be >= 0 and the last - stop's offset must be <= 1. - - - + filename="gsk/gskroundedrect.c" + line="195">the horizontal offset + - + the number of elements in @color_stops - + filename="gsk/gskroundedrect.c" + line="196">the vertical offset + - - - - A render node for a repeating radial gradient. - + + Creates a `GskRenderNode` that draws a repeating radial gradient. + filename="gsk/gskroundedrect.c" + line="240">Shrinks (or grows) a rounded rectangle by moving the 4 sides +according to the offsets given. -The radial gradient starts around @center. The size of the gradient -is dictated by @hradius in horizontal orientation and by @vradius -in vertical orientation. - - +The corner radii will be changed in a way that tries to keep +the center of the corner circle intact. This emulates CSS behavior. + +This function also works for growing rounded rectangles +if you pass negative values for the @top, @right, @bottom or @left. + + A new `GskRenderNode` - + filename="gsk/gskroundedrect.c" + line="257">the resized rounded rectangle + - - the bounds of the node - - - + the center of the gradient - - - + filename="gsk/gskroundedrect.c" + line="242">the rounded rectangle to shrink or grow + + + the horizontal radius + filename="gsk/gskroundedrect.c" + line="243">how far to move the top side downwards - + the vertical radius + filename="gsk/gskroundedrect.c" + line="244">how far to move the right side to the left - + a percentage >= 0 that defines the start of the gradient around @center + filename="gsk/gskroundedrect.c" + line="245">how far to move the bottom side upwards - + a percentage >= 0 that defines the end of the gradient around @center + filename="gsk/gskroundedrect.c" + line="246">how far to move the left side to the right - - a pointer to an array of - `GskColorStop` defining the gradient. The offsets of all color stops - must be increasing. The first stop's offset must be >= 0 and the last - stop's offset must be <= 1. - - - - - - the number of elements in @color_stops - - - - - + + + A render node applying a rounded rectangle clip to its single child. - + filename="gsk/gskenums.h" + line="130">The filters used when scaling texture data. + +The actual implementation of each filter is deferred to the +rendering pipeline. + Creates a `GskRenderNode` that will clip the @child to the area -given by @clip. - + filename="gsk/gskenums.h" + line="132">linear interpolation filter + + + nearest neighbor interpolation filter + + + linear interpolation along each axis, + plus mipmap generation, with linear interpolation along the mipmap + levels + + + + Errors that can happen during (de)serialization. + + The format can not be identified + + + The version of the data is not + understood + + + The given data may not exist in + a proper serialization + + + Registers an error quark for [class@Gsk.RenderNode] errors. + + the error quark + + + + + + Builds the uniforms data for a `GskGLShader`. + + + Allocates a builder that can be used to construct a new uniform data +chunk. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + A new `GskRenderNode` - + filename="gsk/gskglshader.c" + line="1198">The newly allocated builder, free with + [method@Gsk.ShaderArgsBuilder.unref] + - + The node to draw - + filename="gsk/gskglshader.c" + line="1192">a `GskGLShader` + - + The clip to apply - + filename="gsk/gskglshader.c" + line="1193">optional `GBytes` with initial values + - + Gets the child node that is getting clipped by the given @node. - - + filename="gsk/gskglshader.c" + line="1256">Creates a new `GBytes` args from the current state of the +given @builder, and frees the @builder instance. + +Any uniforms of the shader that have not been explicitly set +on the @builder are zero-initialized. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + + The child that is getting clipped - + filename="gsk/gskglshader.c" + line="1266">the newly allocated buffer with + all the args added to @builder + - + a rounded clip `GskRenderNode` - + filename="gsk/gskglshader.c" + line="1258">a `GskShaderArgsBuilder` + - + Retrieves the rounded rectangle used to clip the contents of the @node. - - + filename="gsk/gskglshader.c" + line="1316">Increases the reference count of a `GskShaderArgsBuilder` by one. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + + a rounded rectangle - + filename="gsk/gskglshader.c" + line="1322">the passed in `GskShaderArgsBuilder` + - + a rounded clip `GskRenderNode` - + filename="gsk/gskglshader.c" + line="1318">a `GskShaderArgsBuilder` + - - - A rectangular region with rounded corners. - -Application code should normalize rectangles using -[method@Gsk.RoundedRect.normalize]; this function will ensure that -the bounds of the rectangle are normalized and ensure that the corner -values are positive and the corners do not overlap. - -All functions taking a `GskRoundedRect` as an argument will internally -operate on a normalized copy; all functions returning a `GskRoundedRect` -will always return a normalized one. - -The algorithm used for normalizing corner sizes is described in -[the CSS specification](https://drafts.csswg.org/css-backgrounds-3/#border-radius). - - - the bounds of the rectangle - - - + the size of the 4 rounded corners - - - - - - Checks if the given @point is inside the rounded rectangle. - + filename="gsk/gskglshader.c" + line="1429">Sets the value of the uniform @idx. + +The uniform must be of bool type. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + - %TRUE if the @point is inside the rounded rectangle - + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1431">a `GskShaderArgsBuilder` + - + the point to check - + filename="gsk/gskglshader.c" + line="1432">index of the uniform + + + + value to set the uniform to + - + Checks if the given @rect is contained inside the rounded rectangle. - + filename="gsk/gskglshader.c" + line="1337">Sets the value of the uniform @idx. + +The uniform must be of float type. + - %TRUE if the @rect is fully contained inside the rounded rectangle - + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1339">a `GskShaderArgsBuilder` + - + the rectangle to check - + filename="gsk/gskglshader.c" + line="1340">index of the uniform + + + + value to set the uniform to + - + Initializes the given `GskRoundedRect` with the given values. + filename="gsk/gskglshader.c" + line="1365">Sets the value of the uniform @idx. -This function will implicitly normalize the `GskRoundedRect` -before returning. - +The uniform must be of int type. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + - the initialized rectangle - + - + The `GskRoundedRect` to initialize - + filename="gsk/gskglshader.c" + line="1367">a `GskShaderArgsBuilder` + - + a `graphene_rect_t` describing the bounds - + filename="gsk/gskglshader.c" + line="1368">index of the uniform + - + the rounding radius of the top left corner - + filename="gsk/gskglshader.c" + line="1369">value to set the uniform to + - + + + + Sets the value of the uniform @idx. + +The uniform must be of uint type. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + + + + + + the rounding radius of the top right corner - - - + filename="gsk/gskglshader.c" + line="1399">a `GskShaderArgsBuilder` + + + the rounding radius of the bottom right corner - + filename="gsk/gskglshader.c" + line="1400">index of the uniform + - + the rounding radius of the bottom left corner - + filename="gsk/gskglshader.c" + line="1401">value to set the uniform to + - + Initializes @self using the given @src rectangle. + filename="gsk/gskglshader.c" + line="1461">Sets the value of the uniform @idx. -This function will not normalize the `GskRoundedRect`, -so make sure the source is normalized. - +The uniform must be of vec2 type. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + - the initialized rectangle - + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1463">A `GskShaderArgsBuilder` + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1464">index of the uniform + + + + value to set the uniform too + - + Initializes @self to the given @bounds and sets the radius -of all four corners to @radius. - + filename="gsk/gskglshader.c" + line="1493">Sets the value of the uniform @idx. + +The uniform must be of vec3 type. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + - the initialized rectangle - + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1495">a `GskShaderArgsBuilder` + - + a `graphene_rect_t` - + filename="gsk/gskglshader.c" + line="1496">index of the uniform + - + the border radius - + filename="gsk/gskglshader.c" + line="1497">value to set the uniform too + - + Checks if part of the given @rect is contained inside the rounded rectangle. - + filename="gsk/gskglshader.c" + line="1525">Sets the value of the uniform @idx. + +The uniform must be of vec4 type. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + - %TRUE if the @rect intersects with the rounded rectangle - + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1527">a `GskShaderArgsBuilder` + - + the rectangle to check - + filename="gsk/gskglshader.c" + line="1528">index of the uniform + + + + value to set the uniform too + - + Checks if all corners of @self are right angles and the -rectangle covers all of its bounds. + filename="gsk/gskglshader.c" + line="1226">Creates a new `GBytes` args from the current state of the +given @builder. -This information can be used to decide if [ctor@Gsk.ClipNode.new] -or [ctor@Gsk.RoundedClipNode.new] should be called. - - +Any uniforms of the shader that have not been explicitly set on +the @builder are zero-initialized. + +The given `GskShaderArgsBuilder` is reset once this function returns; +you cannot call this function multiple times on the same @builder instance. + +This function is intended primarily for bindings. C code should use +[method@Gsk.ShaderArgsBuilder.free_to_args]. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + + %TRUE if the rectangle is rectilinear - + filename="gsk/gskglshader.c" + line="1242">the newly allocated buffer with + all the args added to @builder + - + the `GskRoundedRect` to check - + filename="gsk/gskglshader.c" + line="1228">a `GskShaderArgsBuilder` + - + Normalizes the passed rectangle. + filename="gsk/gskglshader.c" + line="1288">Decreases the reference count of a `GskShaderArgBuilder` by one. -This function will ensure that the bounds of the rectangle -are normalized and ensure that the corner values are positive -and the corners do not overlap. - +If the resulting reference count is zero, frees the builder. + GTK's new Vulkan-focused rendering + does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html) + for OpenGL rendering. + - the normalized rectangle - + - + a `GskRoundedRect` - + filename="gsk/gskglshader.c" + line="1290">a `GskShaderArgsBuilder` + - + + + The shadow parameters in a shadow node. + + Offsets the bound's origin by @dx and @dy. - -The size and corners of the rectangle are unchanged. - - + filename="gsk/gskrendernode.h" + line="56">the color of the shadow + + + + the horizontal offset of the shadow + + + + the vertical offset of the shadow + + + + the radius of the shadow + + + + + A render node drawing one or more shadows behind its single child node. + + Creates a `GskRenderNode` that will draw a @child with the given +@shadows below it. + + the offset rectangle - + filename="gsk/gskrendernodeimpl.c" + line="6592">A new `GskRenderNode` + - + a `GskRoundedRect` - - - + filename="gsk/gskrendernodeimpl.c" + line="6585">The node to draw + + + the horizontal offset - + filename="gsk/gskrendernodeimpl.c" + line="6586">The shadows to apply + + + - + the vertical offset - + filename="gsk/gskrendernodeimpl.c" + line="6587">number of entries in the @shadows array + - - + + Shrinks (or grows) the given rectangle by moving the 4 sides -according to the offsets given. - -The corner radii will be changed in a way that tries to keep -the center of the corner circle intact. This emulates CSS behavior. - -This function also works for growing rectangles if you pass -negative values for the @top, @right, @bottom or @left. - + filename="gsk/gskrendernodeimpl.c" + line="6674">Retrieves the child `GskRenderNode` of the shadow @node. + the resized `GskRoundedRect` - + filename="gsk/gskrendernodeimpl.c" + line="6680">the child render node + - + The `GskRoundedRect` to shrink or grow - + filename="gsk/gskrendernodeimpl.c" + line="6676">a shadow `GskRenderNode` + - - How far to move the top side downwards - - - - How far to move the right side to the left - - - - How far to move the bottom side upwards - - - - How far to move the left side to the right - - - - - The filters used when scaling texture data. - -The actual implementation of each filter is deferred to the -rendering pipeline. - - linear interpolation filter - - - nearest neighbor interpolation filter - - - linear interpolation along each axis, - plus mipmap generation, with linear interpolation along the mipmap - levels - - - - Errors that can happen during (de)serialization. - - The format can not be identified - - - The version of the data is not - understood - - + The given data may not exist in - a proper serialization - - + filename="gsk/gskrendernodeimpl.c" + line="6747">Retrieves the number of shadows in the @node. + - + the number of shadows. + - - - - An object to build the uniforms data for a `GskGLShader`. - - + + + a shadow `GskRenderNode` + + + + + Allocates a builder that can be used to construct a new uniform data -chunk. - - + filename="gsk/gskrendernodeimpl.c" + line="6690">Retrieves the shadow data at the given index @i. + + The newly allocated builder, free with - [method@Gsk.ShaderArgsBuilder.unref] - + filename="gsk/gskrendernodeimpl.c" + line="6697">the shadow data + - + a `GskGLShader` - + filename="gsk/gskrendernodeimpl.c" + line="6692">a shadow `GskRenderNode` + + + + the given index + - + + + + + Collects the parameters that are needed when stroking a path. + + + Creates a new `GskStroke` with the given @line_width. + + + a new `GskStroke` + + + + optional `GBytes` with initial values - + filename="gsk/gskstroke.c" + line="37">line width of the stroke. Must be > 0 + - + Creates a new `GBytes` args from the current state of the -given @builder, and frees the @builder instance. - -Any uniforms of the shader that have not been explicitly set -on the @builder are zero-initialized. - + filename="gsk/gskstroke.c" + line="62">Creates a copy of a `GskStroke`. + the newly allocated buffer with - all the args added to @builder - + filename="gsk/gskstroke.c" + line="68">a new `GskStroke`. Use [method@Gsk.Stroke.free] to free it + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="64">the stroke to copy + - + Increases the reference count of a `GskShaderArgsBuilder` by one. - - - the passed in `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="86">Frees a `GskStroke`. + + + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="88">a stroke + - + Sets the value of the uniform @idx. - -The uniform must be of bool type. - - - + filename="gsk/gskstroke.c" + line="430">Gets the dash array in use. + + + + the dash array or `NULL` if the dash array is empty + + + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="432">a stroke + - + index of the uniform - + filename="gsk/gskstroke.c" + line="433">number of elements in the array returned + - + + + + Gets the dash offset. + + + the dash offset + + + + value to set the uniform to - - + filename="gsk/gskstroke.c" + line="479">a stroke + + - + Sets the value of the uniform @idx. + filename="gsk/gskstroke.c" + line="264">Gets the line cap used. -The uniform must be of float type. - +See [enum@Gsk.LineCap] for details. + - + the line cap + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="266">a stroke + - - index of the uniform - - - - value to set the uniform to - - - + Sets the value of the uniform @idx. + filename="gsk/gskstroke.c" + line="304">Gets the line join used. -The uniform must be of int type. - +See [enum@Gsk.LineJoin] for details. + - + the line join + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="306">a stroke + - + + + + Gets the line width used. + + + the line width + + + + index of the uniform - - - + filename="gsk/gskstroke.c" + line="228">a stroke + + + + + + Gets the miter limit. + + + the miter limit + + + + value to set the uniform to - - + filename="gsk/gskstroke.c" + line="353">a stroke + + - + Sets the value of the uniform @idx. + filename="gsk/gskstroke.c" + line="369">Sets the dash pattern to use. -The uniform must be of uint type. - +A dash pattern is specified by an array of alternating non-negative +values. Each value provides the length of alternate "on" and "off" +portions of the stroke. + +Each "on" segment will have caps applied as if the segment were a +separate contour. In particular, it is valid to use an "on" length +of 0 with [enum@Gsk.LineCap.round] or [enum@Gsk.LineCap.square] +to draw dots or squares along a path. + +If @n_dash is 0, if all elements in @dash are 0, or if there are +negative values in @dash, then dashing is disabled. + +If @n_dash is 1, an alternating "on" and "off" pattern with the +single dash length provided is assumed. + +If @n_dash is uneven, the dash array will be used with the first +element in @dash defining an "on" or "off" in alternating passes +through the array. + +You can specify a starting offset into the dash with +[method@Gsk.Stroke.set_dash_offset]. + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="371">a stroke + - + index of the uniform - + filename="gsk/gskstroke.c" + line="372"> + the array of dashes + + + - + value to set the uniform to - + filename="gsk/gskstroke.c" + line="374">number of elements in @dash + - + Sets the value of the uniform @idx. + filename="gsk/gskstroke.c" + line="454">Sets the offset into the dash pattern where dashing should begin. -The uniform must be of vec2 type. - +This is an offset into the length of the path, not an index into +the array values of the dash array. + +See [method@Gsk.Stroke.set_dash] for more details on dashing. + - + A `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="456">a stroke + - - index of the uniform - - - + value to set the uniform too - + filename="gsk/gskstroke.c" + line="457">offset into the dash pattern + - + Sets the value of the uniform @idx. + filename="gsk/gskstroke.c" + line="244">Sets the line cap to be used when stroking. -The uniform must be of vec3 type. - +See [enum@Gsk.LineCap] for details. + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="246">a stroke + - - index of the uniform - - - + value to set the uniform too - + filename="gsk/gskstroke.c" + line="247">the line cap + - + Sets the value of the uniform @idx. + filename="gsk/gskstroke.c" + line="284">Sets the line join to be used when stroking. -The uniform must be of vec4 type. - +See [enum@Gsk.LineJoin] for details. + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="286">a stroke + - + index of the uniform - + filename="gsk/gskstroke.c" + line="287">the line join to use + - + + + + Sets the line width to be used when stroking. + +The line width must be > 0. + + + + + + + a stroke + + + value to set the uniform too - + filename="gsk/gskstroke.c" + line="208">width of the line in pixels + - + Creates a new `GBytes` args from the current state of the -given @builder. + filename="gsk/gskstroke.c" + line="324">Sets the miter limit to be used when stroking. -Any uniforms of the shader that have not been explicitly set on -the @builder are zero-initialized. +The miter limit is the distance from the corner where sharp +turns of joins get cut off. -The given `GskShaderArgsBuilder` is reset once this function returns; -you cannot call this function multiple times on the same @builder instance. +The limit is specfied in units of line width and must be non-negative. -This function is intended primarily for bindings. C code should use -[method@Gsk.ShaderArgsBuilder.free_to_args]. - - - the newly allocated buffer with - all the args added to @builder - +For joins of type [enum@Gsk.LineJoin.miter] that exceed the miter limit, +the join gets rendered as if it was of type [enum@Gsk.LineJoin.bevel]. + + + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="326">a stroke + + + the miter limit + + - + Decreases the reference count of a `GskShaderArgBuilder` by one. - -If the resulting reference count is zero, frees the builder. - + filename="gsk/gskstroke.c" + line="105">A helper function that sets the stroke parameters +of a cairo context from a `GskStroke`. + - + a `GskShaderArgsBuilder` - + filename="gsk/gskstroke.c" + line="107">a stroke + + + the cairo context to configure + + - - - The shadow parameters in a shadow node. - - - the color of the shadow - - - - the horizontal offset of the shadow - - - - the vertical offset of the shadow - - - + the radius of the shadow - - + filename="gsk/gskstroke.c" + line="172">Checks if two strokes are identical. + + + true if the two strokes are equal, false otherwise + + + + + the first stroke + + + + the second stroke + + + + - A render node drawing one or more shadows behind its single child node. - + line="6202">A render node that will fill the area determined by stroking the the given +[struct@Gsk.Path] using the [struct@Gsk.Stroke] attributes. + Creates a `GskRenderNode` that will draw a @child with the given -@shadows below it. - - + line="6303">Creates a #GskRenderNode that will fill the outline generated by stroking +the given @path using the attributes defined in @stroke. + +The area is filled with @child. + + A new `GskRenderNode` - + line="6314">A new #GskRenderNode + The node to draw + line="6305">The node to stroke the area with - + The shadows to apply - - - + line="6306">The path describing the area to stroke + - + number of entries in the @shadows array - + line="6307">The stroke attributes to use + - + Retrieves the child `GskRenderNode` of the shadow @node. - + line="6349">Gets the child node that is getting drawn by the given @node. + the child render node + line="6355">The child that is getting drawn a shadow `GskRenderNode` - + line="6351">a stroke #GskRenderNode + - + Retrieves the number of shadows in the @node. - + line="6369">Retrieves the path that will be stroked with the contents of +the @node. + the number of shadows. - + line="6376">a #GskPath + a shadow `GskRenderNode` - + line="6371">a stroke #GskRenderNode + - + Retrieves the shadow data at the given index @i. - + line="6390">Retrieves the stroke attributes used in this @node. + the shadow data - + line="6396">a #GskStroke + a shadow `GskRenderNode` - + line="6392">a stroke #GskRenderNode + - + + + + + A render node that potentially diverts a part of the scene graph to a subsurface. + + Creates a `GskRenderNode` that will possibly divert the child +node to a subsurface. + +Note: Since subsurfaces are currently private, these nodes cannot +currently be created outside of GTK. See +[GtkGraphicsOffload](../gtk4/class.GraphicsOffload.html). + + + A new `GskRenderNode` + + + + the given index - + line="8636">The child to divert to a subsurface + + + + the subsurface to use + + + + + + Gets the subsurface that was set on this node + + + the subsurface + + + + + a debug `GskRenderNode` + + + + Gets the child node that is getting drawn by the given @node. + + + the child `GskRenderNode` + + + + + a debug `GskRenderNode` + + + glib:fundamental="1"> A render node drawing a set of glyphs. + line="7173">A render node drawing a set of glyphs. Creates a render node that renders the given glyphs. + line="7294">Creates a render node that renders the given glyphs. Note that @color may not be used if the font contains color glyphs. - + a new `GskRenderNode` + line="7306">a new `GskRenderNode` the `PangoFont` containing the glyphs + line="7296">the `PangoFont` containing the glyphs the `PangoGlyphString` to render + line="7297">the `PangoGlyphString` to render the foreground color to render with + line="7298">the foreground color to render with offset of the baseline + line="7299">offset of the baseline @@ -5856,19 +9826,22 @@ color glyphs. Retrieves the color used by the text @node. - + line="7399">Retrieves the color used by the text @node. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. + the text color + line="7408">the text color a text `GskRenderNode` + line="7401">a text `GskRenderNode` @@ -5876,19 +9849,19 @@ color glyphs. Returns the font used by the text @node. - + line="7435">Returns the font used by the text @node. + the font + line="7441">the font The `GskRenderNode` + line="7437">The `GskRenderNode` @@ -5896,12 +9869,12 @@ color glyphs. Retrieves the glyph information in the @node. - + line="7493">Retrieves the glyph information in the @node. + the glyph information + line="7500">the glyph information @@ -5910,7 +9883,7 @@ color glyphs. a text `GskRenderNode` + line="7495">a text `GskRenderNode` allow-none="1"> the number of glyphs returned + line="7496">the number of glyphs returned @@ -5930,19 +9903,19 @@ color glyphs. c:identifier="gsk_text_node_get_num_glyphs"> Retrieves the number of glyphs in the text node. - + line="7477">Retrieves the number of glyphs in the text node. + the number of glyphs + line="7483">the number of glyphs a text `GskRenderNode` + line="7479">a text `GskRenderNode` @@ -5950,19 +9923,19 @@ color glyphs. Retrieves the offset applied to the text. - + line="7514">Retrieves the offset applied to the text. + a point with the horizontal and vertical offsets + line="7520">a point with the horizontal and vertical offsets a text `GskRenderNode` + line="7516">a text `GskRenderNode` @@ -5972,19 +9945,19 @@ color glyphs. version="4.2"> Checks whether the text @node has color glyphs. - + line="7459">Checks whether the text @node has color glyphs. + %TRUE if the text node has color glyphs + line="7465">%TRUE if the text node has color glyphs a text `GskRenderNode` + line="7461">a text `GskRenderNode` @@ -5999,34 +9972,34 @@ color glyphs. glib:fundamental="1"> A render node for a `GdkTexture`. + line="2694">A render node for a `GdkTexture`. Creates a `GskRenderNode` that will render the given + line="2880">Creates a `GskRenderNode` that will render the given @texture into the area given by @bounds. Note that GSK applies linear filtering when textures are scaled and transformed. See [class@Gsk.TextureScaleNode] for a way to influence filtering. - + A new `GskRenderNode` + line="2892">A new `GskRenderNode` the `GdkTexture` + line="2882">the `GdkTexture` the rectangle to render the texture into + line="2883">the rectangle to render the texture into @@ -6034,19 +10007,19 @@ for a way to influence filtering. Retrieves the `GdkTexture` used when creating this `GskRenderNode`. - + line="2864">Retrieves the `GdkTexture` used when creating this `GskRenderNode`. + the `GdkTexture` + line="2870">the `GdkTexture` a `GskRenderNode` of type %GSK_TEXTURE_NODE + line="2866">a `GskRenderNode` of type %GSK_TEXTURE_NODE @@ -6062,13 +10035,13 @@ for a way to influence filtering. glib:fundamental="1"> A render node for a `GdkTexture`. + line="2922">A render node for a `GdkTexture`, with control over scaling. Creates a node that scales the texture to the size given by the + line="3091">Creates a node that scales the texture to the size given by the bounds using the filter and then places it at the bounds' position. Note that further scaling and other transformations which are @@ -6080,30 +10053,30 @@ to a texture, such as in image editors and requires the application to be aware of the whole render tree as further transforms may be applied that conflict with the desired effect of this node. - + A new `GskRenderNode` + line="3110">A new `GskRenderNode` the texture to scale + line="3093">the texture to scale the size of the texture to scale to + line="3094">the size of the texture to scale to how to scale the texture + line="3095">how to scale the texture @@ -6113,19 +10086,19 @@ of this node. version="4.10"> Retrieves the `GskScalingFilter` used when creating this `GskRenderNode`. - + line="3073">Retrieves the `GskScalingFilter` used when creating this `GskRenderNode`. + the `GskScalingFilter` + line="3079">the `GskScalingFilter` a `GskRenderNode` of type %GSK_TEXTURE_SCALE_NODE + line="3075">a `GskRenderNode` of type %GSK_TEXTURE_SCALE_NODE @@ -6135,19 +10108,19 @@ of this node. version="4.10"> Retrieves the `GdkTexture` used when creating this `GskRenderNode`. - + line="3055">Retrieves the `GdkTexture` used when creating this `GskRenderNode`. + the `GdkTexture` + line="3061">the `GdkTexture` a `GskRenderNode` of type %GSK_TEXTURE_SCALE_NODE + line="3057">a `GskRenderNode` of type %GSK_TEXTURE_SCALE_NODE @@ -6161,7 +10134,7 @@ of this node. c:symbol-prefix="transform"> `GskTransform` is an object to describe transform matrices. + line="21">Describes a 3D transform. Unlike `graphene_matrix_t`, `GskTransform` retains the steps in how a transform was constructed, and allows inspecting them. It is modeled @@ -6170,22 +10143,31 @@ after the way CSS describes transforms. `GskTransform` objects are immutable and cannot be changed after creation. This means code can safely expose them as properties of objects without having to worry about others changing them. - + + Creates a new identity transform. + +This function is meant to be used by language +bindings. For C code, this is equivalent to using `NULL`. + A new identity transform Checks two transforms for equality. + line="2272">Checks two transforms for equality. %TRUE if the two transforms perform the same operation + line="2279">true if the two transforms perform the same operation @@ -6195,7 +10177,7 @@ having to worry about others changing them. allow-none="1"> the first transform + line="2274">the first transform allow-none="1"> the second transform + line="2275">the second transform @@ -6212,12 +10194,12 @@ having to worry about others changing them. Returns the category this transform belongs to. + line="2303">Returns the category this transform belongs to. The category of the transform + line="2309">The category of the transform @@ -6227,7 +10209,7 @@ having to worry about others changing them. allow-none="1"> A `GskTransform` + line="2305">a transform @@ -6235,18 +10217,21 @@ having to worry about others changing them. Inverts the given transform. + line="2237">Inverts the given transform. -If @self is not invertible, %NULL is returned. -Note that inverting %NULL also returns %NULL, which is -the correct inverse of %NULL. If you need to differentiate -between those cases, you should check @self is not %NULL -before calling this function. +If @self is not invertible, `NULL` is returned. +Note that inverting `NULL` also returns `NULL`, which is +the correct inverse of `NULL`. If you need to differentiate +between those cases, you should check @self is not `NULL` +before calling this function. + +This function consumes @self. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The inverted transform + line="2252">The inverted transform @@ -6256,7 +10241,7 @@ before calling this function. allow-none="1"> Transform to invert + line="2239">transform to invert @@ -6264,12 +10249,15 @@ before calling this function. Multiplies @next with the given @matrix. + line="550">Multiplies @next with the given @matrix. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="560">The new transform @@ -6279,13 +10267,13 @@ before calling this function. allow-none="1"> the next transform + line="552">the next transform the matrix to multiply @next with + line="553">the matrix to multiply @next with @@ -6293,17 +10281,20 @@ before calling this function. Applies a perspective projection transform. + line="1686">Applies a perspective projection transform. This transform scales points in X and Y based on their Z value, scaling points with positive Z values away from the origin, and those with negative Z values towards the origin. Points -on the z=0 plane are unchanged. +on the z=0 plane are unchanged. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="1703">The new transform @@ -6313,13 +10304,13 @@ on the z=0 plane are unchanged. allow-none="1"> the next transform + line="1688">the next transform distance of the z=0 plane. Lower values give a more + line="1689">distance of the z=0 plane. Lower values give a more flattened pyramid and therefore a more pronounced perspective effect. @@ -6329,8 +10320,7 @@ on the z=0 plane are unchanged. Converts @self into a human-readable string representation suitable -for printing. + line="1766">Converts the transform into a human-readable representation. The result of this function can later be parsed with [func@Gsk.Transform.parse]. @@ -6345,13 +10335,13 @@ The result of this function can later be parsed with allow-none="1"> a `GskTransform` + line="1768">a transform The string to print into + line="1769">The string to print into @@ -6359,12 +10349,12 @@ The result of this function can later be parsed with Acquires a reference on the given `GskTransform`. + line="1731">Acquires a reference on the given transform. the `GskTransform` with an additional reference + line="1737">the transform with an additional reference @@ -6374,7 +10364,7 @@ The result of this function can later be parsed with allow-none="1"> a `GskTransform` + line="1733">a transform @@ -6382,13 +10372,17 @@ The result of this function can later be parsed with Rotates @next @angle degrees in 2D - or in 3D-speak, around the Z axis. -The rotation happens around the origin point of (0, 0). + line="987">Rotates @next by an angle around the Z axis. + +The rotation happens around the origin point of (0, 0). + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="999">The new transform @@ -6398,13 +10392,13 @@ The rotation happens around the origin point of (0, 0). allow-none="1"> the next transform + line="989">the next transform the rotation angle, in degrees (clockwise) + line="990">the rotation angle, in degrees (clockwise) @@ -6412,14 +10406,17 @@ The rotation happens around the origin point of (0, 0). Rotates @next @angle degrees around @axis. + line="1120">Rotates @next @angle degrees around @axis. + +For a rotation in 2D space, use [method@Gsk.Transform.rotate] -For a rotation in 2D space, use [method@Gsk.Transform.rotate] +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="1133">The new transform @@ -6429,19 +10426,19 @@ For a rotation in 2D space, use [method@Gsk.Transform.rotate] allow-none="1"> the next transform + line="1122">the next transform the rotation angle, in degrees (clockwise) + line="1123">the rotation angle, in degrees (clockwise) The rotation axis + line="1124">The rotation axis @@ -6449,14 +10446,17 @@ For a rotation in 2D space, use [method@Gsk.Transform.rotate] Scales @next in 2-dimensional space by the given factors. + line="1522">Scales @next in 2-dimensional space by the given factors. -Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. +Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="1535">The new transform @@ -6466,19 +10466,19 @@ Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. allow-none="1"> the next transform + line="1524">the next transform scaling factor on the X axis + line="1525">scaling factor on the X axis scaling factor on the Y axis + line="1526">scaling factor on the Y axis @@ -6486,12 +10486,15 @@ Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. Scales @next by the given factors. + line="1545">Scales @next by the given factors. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="1557">The new transform @@ -6501,25 +10504,25 @@ Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. allow-none="1"> the next transform + line="1547">the next transform scaling factor on the X axis + line="1548">scaling factor on the X axis scaling factor on the Y axis + line="1549">scaling factor on the Y axis scaling factor on the Z axis + line="1550">scaling factor on the Z axis @@ -6527,12 +10530,15 @@ Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. Applies a skew transform. + line="1303">Applies a skew transform. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="1314">The new transform @@ -6542,19 +10548,19 @@ Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. allow-none="1"> the next transform + line="1305">the next transform skew factor, in degrees, on the X axis + line="1306">skew factor, in degrees, on the X axis skew factor, in degrees, on the Y axis + line="1307">skew factor, in degrees, on the Y axis @@ -6562,13 +10568,18 @@ Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions. Converts a `GskTransform` to a 2D transformation matrix. + line="1847">Converts a transform to a 2D transformation matrix. @self must be a 2D transformation. If you are not -sure, use gsk_transform_get_category() >= -%GSK_TRANSFORM_CATEGORY_2D to check. +sure, use -The returned values have the following layout: + gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D + +to check. + +The returned values are a subset of the full 4x4 matrix that +is computed by [method@Gsk.Transform.to_matrix] and have the +following layout: ``` | xx yx | | a b 0 | @@ -6587,7 +10598,7 @@ Cairo. a 2D `GskTransform` + line="1849">a 2D transform transfer-ownership="full"> return location for the xx member + line="1850">return location for the xx member transfer-ownership="full"> return location for the yx member + line="1851">return location for the yx member transfer-ownership="full"> return location for the xy member + line="1852">return location for the xy member transfer-ownership="full"> return location for the yy member + line="1853">return location for the yy member transfer-ownership="full"> return location for the x0 member + line="1854">return location for the x0 member transfer-ownership="full"> return location for the y0 member + line="1855">return location for the y0 member @@ -6651,7 +10662,7 @@ Cairo. version="4.6"> Converts a `GskTransform` to 2D transformation factors. + line="1918">Converts a transform to 2D transformation factors. To recreate an equivalent transform from the factors returned by this function, use @@ -6666,7 +10677,7 @@ by this function, use @self must be a 2D transformation. If you are not sure, use - gsk_transform_get_category() >= %GSK_TRANSFORM_CATEGORY_2D + gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D to check. @@ -6677,7 +10688,7 @@ to check. a `GskTransform` + line="1920">a transform transfer-ownership="full"> return location for the skew factor + line="1921">return location for the skew factor in the x direction @@ -6696,7 +10707,7 @@ to check. transfer-ownership="full"> return location for the skew factor + line="1923">return location for the skew factor in the y direction @@ -6706,7 +10717,7 @@ to check. transfer-ownership="full"> return location for the scale + line="1925">return location for the scale factor in the x direction @@ -6716,7 +10727,7 @@ to check. transfer-ownership="full"> return location for the scale + line="1927">return location for the scale factor in the y direction @@ -6726,7 +10737,7 @@ to check. transfer-ownership="full"> return location for the rotation angle + line="1929">return location for the rotation angle transfer-ownership="full"> return location for the translation + line="1930">return location for the translation in the x direction @@ -6745,7 +10756,7 @@ to check. transfer-ownership="full"> return location for the translation + line="1932">return location for the translation in the y direction @@ -6754,19 +10765,21 @@ to check. Converts a `GskTransform` to 2D affine transformation factors. + line="2007">Converts a transform to 2D affine transformation factors. To recreate an equivalent transform from the factors returned by this function, use - gsk_transform_scale (gsk_transform_translate (NULL, - &GRAPHENE_POINT_T (dx, dy)), - sx, sy) + gsk_transform_scale ( + gsk_transform_translate ( + NULL, + &GRAPHENE_POINT_T (dx, dy)), + sx, sy) @self must be a 2D affine transformation. If you are not sure, use - gsk_transform_get_category() >= %GSK_TRANSFORM_CATEGORY_2D_AFFINE + gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE to check. @@ -6777,7 +10790,7 @@ to check. a `GskTransform` + line="2009">a transform transfer-ownership="full"> return location for the scale + line="2010">return location for the scale factor in the x direction @@ -6796,7 +10809,7 @@ to check. transfer-ownership="full"> return location for the scale + line="2012">return location for the scale factor in the y direction @@ -6806,7 +10819,7 @@ to check. transfer-ownership="full"> return location for the translation + line="2014">return location for the translation in the x direction @@ -6816,7 +10829,7 @@ to check. transfer-ownership="full"> return location for the translation + line="2016">return location for the translation in the y direction @@ -6825,7 +10838,7 @@ to check. Computes the actual value of @self and stores it in @out_matrix. + line="1821">Computes the 4x4 matrix for the transform. The previous value of @out_matrix will be ignored. @@ -6839,7 +10852,7 @@ The previous value of @out_matrix will be ignored. allow-none="1"> a `GskTransform` + line="1823">a transform transfer-ownership="none"> The matrix to set + line="1824">return location for the matrix @@ -6856,7 +10869,7 @@ The previous value of @out_matrix will be ignored. Converts a matrix into a string that is suitable for printing. + line="1797">Converts the transform into a human-readable string. The resulting string can be parsed with [func@Gsk.Transform.parse]. @@ -6865,7 +10878,7 @@ This is a wrapper around [method@Gsk.Transform.print]. A new string for @self + line="1807">A new string for @self @@ -6875,7 +10888,7 @@ This is a wrapper around [method@Gsk.Transform.print]. allow-none="1"> a `GskTransform` + line="1799">a transform @@ -6883,12 +10896,12 @@ This is a wrapper around [method@Gsk.Transform.print]. Converts a `GskTransform` to a translation operation. + line="2161">Converts a transform to a translation operation. @self must be a 2D transformation. If you are not sure, use - gsk_transform_get_category() >= %GSK_TRANSFORM_CATEGORY_2D_TRANSLATE + gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_TRANSLATE to check. @@ -6899,7 +10912,7 @@ to check. a `GskTransform` + line="2163">a transform transfer-ownership="full"> return location for the translation + line="2164">return location for the translation in the x direction @@ -6918,7 +10931,7 @@ to check. transfer-ownership="full"> return location for the translation + line="2166">return location for the translation in the y direction @@ -6927,12 +10940,15 @@ to check. Applies all the operations from @other to @next. + line="2203">Applies all the operations from @other to @next. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="2213">The new transform @@ -6942,7 +10958,7 @@ to check. allow-none="1"> Transform to apply @other to + line="2205">transform to apply @other to allow-none="1"> Transform to apply + line="2206">transform to apply @@ -6960,7 +10976,7 @@ to check. c:identifier="gsk_transform_transform_bounds"> Transforms a `graphene_rect_t` using the given transform @self. + line="2363">Transforms a rectangle using the given transform. The result is the bounding box containing the coplanar quad. @@ -6971,13 +10987,13 @@ The result is the bounding box containing the coplanar quad. a `GskTransform` + line="2365">a transform a `graphene_rect_t` + line="2366">the rectangle to transform transfer-ownership="none"> return location for the bounds + line="2367">return location for the bounds of the transformed rectangle @@ -6996,7 +11012,7 @@ The result is the bounding box containing the coplanar quad. c:identifier="gsk_transform_transform_point"> Transforms a `graphene_point_t` using the given transform @self. + line="2444">Transforms a point using the given transform. @@ -7005,13 +11021,13 @@ The result is the bounding box containing the coplanar quad. a `GskTransform` + line="2446">a transform a `graphene_point_t` + line="2447">the point to transform transfer-ownership="none"> return location for + line="2448">return location for the transformed point @@ -7029,12 +11045,15 @@ The result is the bounding box containing the coplanar quad. Translates @next in 2-dimensional space by @point. + line="727">Translates @next in 2-dimensional space by @point. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="737">The new transform @@ -7044,13 +11063,13 @@ The result is the bounding box containing the coplanar quad. allow-none="1"> the next transform + line="729">the next transform the point to translate the transform by + line="730">the point to translate the transform by @@ -7058,12 +11077,15 @@ The result is the bounding box containing the coplanar quad. Translates @next by @point. + line="750">Translates @next by @point. + +This function consumes @next. Use [method@Gsk.Transform.ref] first +if you want to keep it around. The new transform + line="760">The new transform @@ -7073,13 +11095,13 @@ The result is the bounding box containing the coplanar quad. allow-none="1"> the next transform + line="752">the next transform the point to translate the transform by + line="753">the point to translate the transform by @@ -7087,7 +11109,7 @@ The result is the bounding box containing the coplanar quad. Releases a reference on the given `GskTransform`. + line="1748">Releases a reference on the given transform. If the reference was the last, the resources associated to the @self are freed. @@ -7102,7 +11124,7 @@ freed. allow-none="1"> a `GskTransform` + line="1750">a transform @@ -7110,26 +11132,25 @@ freed. Parses the given @string into a transform and puts it in -@out_transform. + line="2739">Parses a given into a transform. Strings printed via [method@Gsk.Transform.to_string] can be read in again successfully using this function. -If @string does not describe a valid transform, %FALSE is -returned and %NULL is put in @out_transform. +If @string does not describe a valid transform, false +is returned and `NULL` is put in @out_transform. %TRUE if @string described a valid transform. + line="2752">true if @string described a valid transform the string to parse + line="2741">the string to parse transfer-ownership="full"> The location to put the transform in + line="2742">return location for the transform @@ -7150,7 +11171,7 @@ returned and %NULL is put in @out_transform. c:type="GskTransformCategory"> The categories of matrices relevant for GSK and GTK. + line="388">The categories of matrices relevant for GSK and GTK. Note that any category includes matrices of all later categories. So if you want to for example check if a matrix is a 2D matrix, @@ -7167,7 +11188,7 @@ multiplication `C = A * B`, `category(C) = MIN (category(A), category(B))`. The category of the matrix has not been + line="390">The category of the matrix has not been determined. Analyzing the matrix concluded that it does + line="392">Analyzing the matrix concluded that it does not fit in any other category. The matrix is a 3D matrix. This means that + line="394">The matrix is a 3D matrix. This means that the w column (the last column) has the values (0, 0, 0, 1). The matrix is a 2D matrix. This is equivalent + line="396">The matrix is a 2D matrix. This is equivalent to graphene_matrix_is_2d() returning %TRUE. In particular, this means that Cairo can deal with the matrix. @@ -7208,7 +11229,7 @@ multiplication `C = A * B`, `category(C) = MIN (category(A), category(B))`. The matrix is a combination of 2D scale + line="399">The matrix is a combination of 2D scale and 2D translation operations. In particular, this means that any rectangle can be transformed exactly using this matrix. @@ -7219,7 +11240,7 @@ multiplication `C = A * B`, `category(C) = MIN (category(A), category(B))`. The matrix is a 2D translation. + line="402">The matrix is a 2D translation. The matrix is the identity matrix. + line="403">The matrix is the identity matrix. A render node applying a `GskTransform` to its single child node. + line="4683">A render node applying a `GskTransform` to its single child node. Creates a `GskRenderNode` that will transform the given @child + line="4863">Creates a `GskRenderNode` that will transform the given @child with the given @transform. - + A new `GskRenderNode` + line="4871">A new `GskRenderNode` The node to transform + line="4865">The node to transform The transform to apply + line="4866">The transform to apply @@ -7271,19 +11292,19 @@ with the given @transform. Gets the child node that is getting transformed by the given @node. - + line="4909">Gets the child node that is getting transformed by the given @node. + The child that is getting transformed + line="4915">The child that is getting transformed a `GskRenderNode` for a transform + line="4911">a `GskRenderNode` for a transform @@ -7292,19 +11313,19 @@ with the given @transform. c:identifier="gsk_transform_node_get_transform"> Retrieves the `GskTransform` used by the @node. - + line="4925">Retrieves the `GskTransform` used by the @node. + a `GskTransform` + line="4931">a `GskTransform` a `GskRenderNode` for a transform + line="4927">a `GskRenderNode` for a transform @@ -7315,48 +11336,200 @@ with the given @transform. introspectable="0"> Evaluates to %TRUE if @value was initialized with %GSK_TYPE_RENDER_NODE. - + line="613">Evaluates to true if @value was initialized with `GSK_TYPE_RENDER_NODE`. + a `GValue` + line="615">a `GValue` + + + + + + + + + + + + + + + + + + + + + + + A GSK renderer that is using Vulkan. + +This renderer will fail to realize if Vulkan is not supported. + + + Creates a new Vulkan renderer. + +The Vulkan renderer is a renderer that uses the Vulkan library for +rendering. + +This renderer will fail to realize when GTK was not compiled with +Vulkan support. + + + a new Vulkan renderer + + + + + + + + + Constructs a path from a serialized form. + +The string is expected to be in (a superset of) +[SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData), +as e.g. produced by [method@Gsk.Path.to_string]. + +A high-level summary of the syntax: + +- `M x y` Move to `(x, y)` +- `L x y` Add a line from the current point to `(x, y)` +- `Q x1 y1 x2 y2` Add a quadratic Bézier from the current point to `(x2, y2)`, with control point `(x1, y1)` +- `C x1 y1 x2 y2 x3 y3` Add a cubic Bézier from the current point to `(x3, y3)`, with control points `(x1, y1)` and `(x2, y2)` +- `Z` Close the contour by drawing a line back to the start point +- `H x` Add a horizontal line from the current point to the given x value +- `V y` Add a vertical line from the current point to the given y value +- `T x2 y2` Add a quadratic Bézier, using the reflection of the previous segments' control point as control point +- `S x2 y2 x3 y3` Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point +- `A rx ry r l s x y` Add an elliptical arc from the current point to `(x, y)` with radii rx and ry. See the SVG documentation for how the other parameters influence the arc. +- `O x1 y1 x2 y2 w` Add a rational quadratic Bézier from the current point to `(x2, y2)` with control point `(x1, y1)` and weight `w`. + +All the commands have lowercase variants that interpret coordinates +relative to the current point. + +The `O` command is an extension that is not supported in SVG. + + + a new `GskPath`, or `NULL` if @string could not be parsed + + + + + a string + + + + + Registers an error quark for [class@Gsk.RenderNode] errors. + the error quark + + Checks if two strokes are identical. + + + true if the two strokes are equal, false otherwise + + + + + the first stroke + + + + the second stroke + + + + Parses the given @string into a transform and puts it in -@out_transform. + line="2739">Parses a given into a transform. Strings printed via [method@Gsk.Transform.to_string] can be read in again successfully using this function. -If @string does not describe a valid transform, %FALSE is -returned and %NULL is put in @out_transform. +If @string does not describe a valid transform, false +is returned and `NULL` is put in @out_transform. %TRUE if @string described a valid transform. + line="2752">true if @string described a valid transform the string to parse + line="2741">the string to parse transfer-ownership="full"> The location to put the transform in + line="2742">return location for the transform @@ -7375,20 +11548,20 @@ returned and %NULL is put in @out_transform. version="4.6"> Retrieves the `GskRenderNode` stored inside the given `value`, and acquires -a reference to it. - + line="794">Retrieves the render node stored inside a `GValue`, +and acquires a reference to it. + a `GskRenderNode` + line="801">the render node a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` + line="796">a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` @@ -7398,19 +11571,19 @@ a reference to it. version="4.6"> Retrieves the `GskRenderNode` stored inside the given `value`. - + line="776">Retrieves the render node stored inside a `GValue`. + a `GskRenderNode` + line="782">the render node a `GValue` initialized with type `GSK_TYPE_RENDER_NODE` + line="778">a `GValue` initialized with type `GSK_TYPE_RENDER_NODE` @@ -7420,10 +11593,11 @@ a reference to it. version="4.6"> Stores the given `GskRenderNode` inside `value`. + line="702">Stores the given render node inside a `GValue`. -The [struct@GObject.Value] will acquire a reference to the `node`. - +The [struct@GObject.Value] will acquire a reference +to the render node. + @@ -7431,13 +11605,13 @@ The [struct@GObject.Value] will acquire a reference to the `node`. a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` + line="704">a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` a `GskRenderNode` + line="705">a render node @@ -7447,10 +11621,11 @@ The [struct@GObject.Value] will acquire a reference to the `node`. version="4.6"> Stores the given `GskRenderNode` inside `value`. + line="739">Stores the given render node inside a `GValue`. -This function transfers the ownership of the `node` to the `GValue`. - +This function transfers the ownership of the +render node to the `GValue`. + @@ -7458,7 +11633,7 @@ This function transfers the ownership of the `node` to the `GValue`. a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` + line="741">a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` allow-none="1"> a `GskRenderNode` + line="742">a render node diff --git a/generator/src/main/resources/gir/Gst-1.0.gir b/generator/src/main/resources/gir/Gst-1.0.gir index e2b10fb..2f89e5e 100644 --- a/generator/src/main/resources/gir/Gst-1.0.gir +++ b/generator/src/main/resources/gir/Gst-1.0.gir @@ -5,12 +5,14 @@ and/or use gtk-doc annotations. --> + Alias for #GstMapInfo to be used with g_auto(): + line="804">Alias for #GstMapInfo to be used with g_auto(): ```c void my_func(GstBuffer *buf) { @@ -35,7 +37,7 @@ void my_func(GstBuffer *buf) needs to be unmapped using gst_buffer_unmap() or gst_memory_unmap(). See also #GstMemoryMapInfo. - + @@ -133,6 +135,42 @@ See also #GstBufferMapInfo. + + The aggregator function will combine the parameters from @params0 and @param1 +and write the result back into @aggregated_params. + + + %TRUE if the parameters were successfully aggregated, %FALSE otherwise. + + + + + This structure will be updated with the + combined parameters from both @params0 and @params1. + + + + a #GstStructure containing the new parameters to be aggregated. + + + + a #GstStructure containing the new parameters to be aggregated. + + + + version="1.20"> Create a new #GstAllocationParams on the heap. This function is for + line="147">Create a new #GstAllocationParams on the heap. This function is for use in GStreamer language bindings. In your own code, you can just declare a #GstAllocationParams on the stack or in a struct, and call gst_allocation_params_init() to initialize it. You do not need to call gst_allocation_params_init() on the instance returned by this function. - + a new #GstAllocationParams + line="158">a new #GstAllocationParams Create a copy of @params. - + line="186">Create a copy of @params. + a new #GstAllocationParams. + line="192">a new #GstAllocationParams. @@ -209,7 +247,7 @@ returned by this function. allow-none="1"> a #GstAllocationParams + line="188">a #GstAllocationParams @@ -217,8 +255,8 @@ returned by this function. Free @params - + line="207">Free @params + @@ -226,7 +264,7 @@ returned by this function. a #GstAllocationParams + line="209">a #GstAllocationParams @@ -234,8 +272,8 @@ returned by this function. Initialize @params to its default values - + line="172">Initialize @params to its default values + @@ -243,7 +281,7 @@ returned by this function. a #GstAllocationParams + line="174">a #GstAllocationParams @@ -270,17 +308,17 @@ default allocator. New memory can be created with gst_memory_new_wrapped() that wraps the memory allocated elsewhere. - + Find a previously registered allocator with @name. When @name is %NULL, the + line="243">Find a previously registered allocator with @name. When @name is %NULL, the default allocator will be returned. - + a #GstAllocator or %NULL when + line="250">a #GstAllocator or %NULL when the allocator with @name was not registered. @@ -291,7 +329,7 @@ the allocator with @name was not registered. allow-none="1"> the name of the allocator + line="245">the name of the allocator @@ -299,8 +337,8 @@ the allocator with @name was not registered. Registers the memory @allocator with @name. - + line="219">Registers the memory @allocator with @name. + @@ -308,13 +346,13 @@ the allocator with @name was not registered. the name of the allocator + line="221">the name of the allocator #GstAllocator + line="222">#GstAllocator @@ -322,7 +360,7 @@ the allocator with @name was not registered. Use @allocator to allocate a new memory block with memory that is at least + line="293">Use @allocator to allocate a new memory block with memory that is at least @size big. The optional @params can specify the prefix and padding for the memory. If @@ -337,11 +375,11 @@ When @allocator is %NULL, the default allocator will be used. The alignment in @params is given as a bitmask so that @align + 1 equals the amount of bytes to align to. For example, to align to 8 bytes, use an alignment of 7. - + a new #GstMemory. + line="315">a new #GstMemory. @@ -351,13 +389,13 @@ use an alignment of 7. allow-none="1"> a #GstAllocator to use + line="295">a #GstAllocator to use size of the visible memory area + line="296">size of the visible memory area allow-none="1"> optional parameters + line="297">optional parameters @@ -374,8 +412,8 @@ use an alignment of 7. Free @memory that was previously allocated with gst_allocator_alloc(). - + line="343">Free @memory that was previously allocated with gst_allocator_alloc(). + @@ -383,13 +421,13 @@ use an alignment of 7. a #GstAllocator to use + line="345">a #GstAllocator to use the memory to free + line="346">the memory to free @@ -397,7 +435,7 @@ use an alignment of 7. Use @allocator to allocate a new memory block with memory that is at least + line="293">Use @allocator to allocate a new memory block with memory that is at least @size big. The optional @params can specify the prefix and padding for the memory. If @@ -412,11 +450,11 @@ When @allocator is %NULL, the default allocator will be used. The alignment in @params is given as a bitmask so that @align + 1 equals the amount of bytes to align to. For example, to align to 8 bytes, use an alignment of 7. - + a new #GstMemory. + line="315">a new #GstMemory. @@ -426,13 +464,13 @@ use an alignment of 7. allow-none="1"> a #GstAllocator to use + line="295">a #GstAllocator to use size of the visible memory area + line="296">size of the visible memory area allow-none="1"> optional parameters + line="297">optional parameters @@ -449,8 +487,8 @@ use an alignment of 7. Free @memory that was previously allocated with gst_allocator_alloc(). - + line="343">Free @memory that was previously allocated with gst_allocator_alloc(). + @@ -458,13 +496,13 @@ use an alignment of 7. a #GstAllocator to use + line="345">a #GstAllocator to use the memory to free + line="346">the memory to free @@ -472,8 +510,8 @@ use an alignment of 7. Set the default allocator. - + line="271">Set the default allocator. + @@ -481,7 +519,7 @@ use an alignment of 7. a #GstAllocator + line="273">a #GstAllocator @@ -495,44 +533,44 @@ use an alignment of 7. the implementation of the GstMemoryMapFunction + line="117">the implementation of the GstMemoryMapFunction the implementation of the GstMemoryUnmapFunction + line="118">the implementation of the GstMemoryUnmapFunction the implementation of the GstMemoryCopyFunction + line="119">the implementation of the GstMemoryCopyFunction the implementation of the GstMemoryShareFunction + line="120">the implementation of the GstMemoryShareFunction the implementation of the GstMemoryIsSpanFunction + line="121">the implementation of the GstMemoryIsSpanFunction the implementation of the GstMemoryMapFullFunction. + line="122">the implementation of the GstMemoryMapFullFunction. Will be used instead of @mem_map if present. (Since: 1.6) the implementation of the GstMemoryUnmapFullFunction. + line="124">the implementation of the GstMemoryUnmapFullFunction. Will be used instead of @mem_unmap if present. (Since: 1.6) @@ -551,21 +589,24 @@ use an alignment of 7. glib:is-gtype-struct-for="Allocator"> The #GstAllocator is used to create new memory. - + line="152">The #GstAllocator is used to create new memory. + Object parent class + line="154">Object parent class + implementation that acquires memory - + a new #GstMemory. + line="315">a new #GstMemory. @@ -575,13 +616,13 @@ use an alignment of 7. allow-none="1"> a #GstAllocator to use + line="295">a #GstAllocator to use size of the visible memory area + line="296">size of the visible memory area allow-none="1"> optional parameters + line="297">optional parameters + implementation that releases memory - + @@ -606,13 +650,13 @@ use an alignment of 7. a #GstAllocator to use + line="345">a #GstAllocator to use the memory to free + line="346">the memory to free @@ -638,7 +682,23 @@ use an alignment of 7. glib:name="GST_ALLOCATOR_FLAG_CUSTOM_ALLOC"> The allocator has a custom alloc function. + line="86">The allocator has a custom alloc function. + Only elements designed to work with this allocator should be using it, + other elements should ignore it from allocation propositions. + This implies %GST_ALLOCATOR_FLAG_NO_COPY. + + + When copying a #GstMemory allocated with this allocator, the copy will +instead be allocated using the default allocator. Use this when allocating a +new memory is an heavy opperation that should only be done with a +#GstBufferPool for example. glib:name="GST_ALLOCATOR_FLAG_LAST"> first flag that can be used for custom purposes + line="94">first flag that can be used for custom purposes line="2689">Adds a %NULL-terminated list of elements to a bin. This function is equivalent to calling gst_bin_add() for each member of the list. The return value of each gst_bin_add() is ignored. - + @@ -1728,7 +1788,7 @@ direction within the specified bin and returns an unlinked pad if one is found, or %NULL otherwise. If a pad is found, the caller owns a reference to it and should use gst_object_unref() on the pad when it is not needed any longer. - + Looks for an element inside the bin that implements the given + line="4469">Looks for an element inside the bin that implements the given interface. If such an element is found, it returns the element. You can cast this element to the given interface afterwards. If you want all elements that implement the interface, use @@ -1763,7 +1823,7 @@ gst_bin_iterate_all_by_interface(). This function recurses into child bins. A #GstElement inside the bin + line="4480">A #GstElement inside the bin implementing the interface @@ -1771,13 +1831,13 @@ implementing the interface a #GstBin + line="4471">a #GstBin the #GType of an interface + line="4472">the #GType of an interface @@ -1785,13 +1845,13 @@ implementing the interface Gets the element with the given name from a bin. This + line="4379">Gets the element with the given name from a bin. This function recurses into child bins. the #GstElement with the given + line="4387">the #GstElement with the given name @@ -1799,13 +1859,13 @@ name a #GstBin + line="4381">a #GstBin the element name to search for + line="4382">the element name to search for @@ -1814,13 +1874,13 @@ name c:identifier="gst_bin_get_by_name_recurse_up"> Gets the element with the given name from this bin. If the + line="4418">Gets the element with the given name from this bin. If the element is not found, a recursion is performed on the parent bin. the #GstElement with the given + line="4426">the #GstElement with the given name @@ -1828,13 +1888,13 @@ name a #GstBin + line="4420">a #GstBin the element name to search for + line="4421">the element name to search for @@ -1863,14 +1923,14 @@ name version="1.18"> Looks for all elements inside the bin with the given element factory name. + line="4562">Looks for all elements inside the bin with the given element factory name. The function recurses inside child bins. The iterator will yield a series of #GstElement. a #GstIterator of #GstElement + line="4571">a #GstIterator of #GstElement for all elements in the bin with the given element factory name @@ -1878,13 +1938,13 @@ The function recurses inside child bins. The iterator will yield a series of a #GstBin + line="4564">a #GstBin the name of the #GstElementFactory + line="4565">the name of the #GstElementFactory @@ -1893,7 +1953,7 @@ The function recurses inside child bins. The iterator will yield a series of c:identifier="gst_bin_iterate_all_by_interface"> Looks for all elements inside the bin that implements the given + line="4514">Looks for all elements inside the bin that implements the given interface. You can safely cast all returned elements to the given interface. The function recurses inside child bins. The iterator will yield a series of #GstElement. @@ -1901,7 +1961,7 @@ of #GstElement. a #GstIterator of #GstElement + line="4524">a #GstIterator of #GstElement for all elements in the bin implementing the given interface @@ -1909,13 +1969,13 @@ of #GstElement. a #GstBin + line="4516">a #GstBin the #GType of an interface + line="4517">the #GType of an interface @@ -2098,7 +2158,7 @@ the bin does not want to remove the element. filename="gst/gstutils.c" line="2718">Removes a list of elements from a bin. This function is equivalent to calling gst_bin_remove() with each member of the list. - + @@ -2158,7 +2218,7 @@ not be propagated to the bin. filename="gst/gstutils.c" line="3369">Synchronizes the state of every child of @bin with the state of @bin. See also gst_element_sync_state_with_parent(). - + Creates a newly allocated buffer without any data. + line="859">Creates a newly allocated buffer without any data. the new #GstBuffer. + line="864">the new #GstBuffer. Tries to create a newly allocated buffer with data of the given size and + line="879">Tries to create a newly allocated buffer with data of the given size and extra parameters from @allocator. If the requested amount of memory can't be allocated, %NULL will be returned. The allocated buffer memory is not cleared. @@ -2816,7 +2876,7 @@ Note that when @size == 0, the buffer will not have memory associated with it. a new #GstBuffer + line="894">a new #GstBuffer @@ -2826,14 +2886,14 @@ Note that when @size == 0, the buffer will not have memory associated with it. the #GstAllocator to use, or %NULL to use the + line="881">the #GstAllocator to use, or %NULL to use the default allocator the size in bytes of the new buffer's data. + line="883">the size in bytes of the new buffer's data. optional parameters + line="884">optional parameters @@ -2852,19 +2912,19 @@ Note that when @size == 0, the buffer will not have memory associated with it. Creates a new buffer of size @size and fills it with a copy of @data. + line="1063">Creates a new buffer of size @size and fills it with a copy of @data. a new #GstBuffer + line="1070">a new #GstBuffer data to copy into new buffer + line="1065">data to copy into new buffer @@ -2872,7 +2932,7 @@ Note that when @size == 0, the buffer will not have memory associated with it. size of @data in bytes + line="1066">size of @data in bytes @@ -2880,20 +2940,20 @@ Note that when @size == 0, the buffer will not have memory associated with it. Creates a new buffer that wraps the given @data. The memory will be freed + line="1022">Creates a new buffer that wraps the given @data. The memory will be freed with g_free() and will be marked writable. a new #GstBuffer + line="1030">a new #GstBuffer data to wrap + line="1024">data to wrap @@ -2901,7 +2961,7 @@ with g_free() and will be marked writable. allocated size of @data + line="1025">allocated size of @data @@ -2911,20 +2971,20 @@ with g_free() and will be marked writable. version="1.16"> Creates a new #GstBuffer that wraps the given @bytes. The data inside + line="1038">Creates a new #GstBuffer that wraps the given @bytes. The data inside @bytes cannot be %NULL and the resulting buffer will be marked as read only. a new #GstBuffer wrapping @bytes + line="1045">a new #GstBuffer wrapping @bytes a #GBytes to wrap + line="1040">a #GBytes to wrap @@ -2933,7 +2993,7 @@ with g_free() and will be marked writable. c:identifier="gst_buffer_new_wrapped_full"> Allocates a new buffer that wraps the given memory. @data must point to + line="982">Allocates a new buffer that wraps the given memory. @data must point to @maxsize of memory, the wrapped buffer will have the region from @offset and @size visible. @@ -2945,20 +3005,20 @@ The prefix/padding must be filled with 0 if @flags contains a new #GstBuffer + line="1001">a new #GstBuffer #GstMemoryFlags + line="984">#GstMemoryFlags data to wrap + line="985">data to wrap @@ -2966,19 +3026,19 @@ The prefix/padding must be filled with 0 if @flags contains allocated size of @data + line="986">allocated size of @data offset in @data + line="987">offset in @data size of valid data + line="988">size of valid data user_data + line="989">user_data called with @user_data when the memory is freed + line="990">called with @user_data when the memory is freed @@ -3008,26 +3068,26 @@ The prefix/padding must be filled with 0 if @flags contains version="1.20"> Creates and adds a #GstCustomMeta for the desired @name. @name must have + line="2961">Creates and adds a #GstCustomMeta for the desired @name. @name must have been successfully registered with gst_meta_register_custom(). The #GstCustomMeta that was added to the buffer + line="2969">The #GstCustomMeta that was added to the buffer a #GstBuffer + line="2963">a #GstBuffer the registered name of the desired custom meta + line="2964">the registered name of the desired custom meta @@ -3035,25 +3095,25 @@ been successfully registered with gst_meta_register_custom(). Adds metadata for @info to @buffer using the parameters in @params. + line="2294">Adds metadata for @info to @buffer using the parameters in @params. the metadata for the api in @info on @buffer. + line="2302">the metadata for the api in @info on @buffer. a #GstBuffer + line="2296">a #GstBuffer a #GstMetaInfo + line="2297">a #GstMetaInfo allow-none="1"> params for @info + line="2298">params for @info @@ -3072,26 +3132,26 @@ been successfully registered with gst_meta_register_custom(). version="1.6"> Adds a #GstParentBufferMeta to @buffer that holds a reference on + line="2597">Adds a #GstParentBufferMeta to @buffer that holds a reference on @ref until the buffer is freed. The #GstParentBufferMeta that was added to the buffer + line="2605">The #GstParentBufferMeta that was added to the buffer a #GstBuffer + line="2599">a #GstBuffer a #GstBuffer to ref + line="2600">a #GstBuffer to ref @@ -3101,26 +3161,26 @@ been successfully registered with gst_meta_register_custom(). version="1.6"> Attaches protection metadata to a #GstBuffer. + line="136">Attaches protection metadata to a #GstBuffer. a pointer to the added #GstProtectionMeta if successful + line="146">a pointer to the added #GstProtectionMeta if successful #GstBuffer holding an encrypted sample, to which protection + line="138">#GstBuffer holding an encrypted sample, to which protection metadata should be added. a #GstStructure holding cryptographic + line="140">a #GstStructure holding cryptographic information relating to the sample contained in @buffer. This function takes ownership of @info. @@ -3132,14 +3192,14 @@ been successfully registered with gst_meta_register_custom(). version="1.14"> Adds a #GstReferenceTimestampMeta to @buffer that holds a @timestamp and + line="2728">Adds a #GstReferenceTimestampMeta to @buffer that holds a @timestamp and optionally @duration based on a specific timestamp @reference. See the documentation of #GstReferenceTimestampMeta for details. - + The #GstReferenceTimestampMeta that was added to the buffer + line="2739">The #GstReferenceTimestampMeta that was added to the buffer @@ -3147,25 +3207,25 @@ documentation of #GstReferenceTimestampMeta for details. a #GstBuffer + line="2730">a #GstBuffer identifier for the timestamp reference. + line="2731">identifier for the timestamp reference. timestamp + line="2732">timestamp duration, or %GST_CLOCK_TIME_NONE + line="2733">duration, or %GST_CLOCK_TIME_NONE @@ -3173,13 +3233,13 @@ documentation of #GstReferenceTimestampMeta for details. Appends all the memory from @buf2 to @buf1. The result buffer will contain a + line="2176">Appends all the memory from @buf2 to @buf1. The result buffer will contain a concatenation of the memory of @buf1 and @buf2. the new #GstBuffer that contains the memory + line="2184">the new #GstBuffer that contains the memory of the two source buffers. @@ -3187,13 +3247,13 @@ concatenation of the memory of @buf1 and @buf2. the first source #GstBuffer to append. + line="2178">the first source #GstBuffer to append. the second source #GstBuffer to append. + line="2179">the second source #GstBuffer to append. @@ -3201,7 +3261,7 @@ concatenation of the memory of @buf1 and @buf2. Appends the memory block @mem to @buffer. This function takes + line="1116">Appends the memory block @mem to @buffer. This function takes ownership of @mem and thus doesn't increase its refcount. This function is identical to gst_buffer_insert_memory() with an index of -1. @@ -3214,13 +3274,13 @@ See gst_buffer_insert_memory() for more details. a #GstBuffer. + line="1118">a #GstBuffer. a #GstMemory. + line="1119">a #GstMemory. @@ -3228,14 +3288,14 @@ See gst_buffer_insert_memory() for more details. Appends @size bytes at @offset from @buf2 to @buf1. The result buffer will + line="2193">Appends @size bytes at @offset from @buf2 to @buf1. The result buffer will contain a concatenation of the memory of @buf1 and the requested region of @buf2. the new #GstBuffer that contains the memory + line="2204">the new #GstBuffer that contains the memory of the two source buffers. @@ -3243,25 +3303,25 @@ contain a concatenation of the memory of @buf1 and the requested region of the first source #GstBuffer to append. + line="2195">the first source #GstBuffer to append. the second source #GstBuffer to append. + line="2196">the second source #GstBuffer to append. the offset in @buf2 + line="2197">the offset in @buf2 the size or -1 of @buf2 + line="2198">the size or -1 of @buf2 @@ -3271,20 +3331,20 @@ contain a concatenation of the memory of @buf1 and the requested region of version="1.6"> Creates a copy of the given buffer. This will make a newly allocated + line="763">Creates a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains. a new copy of @buf if the copy succeeded, %NULL otherwise. + line="770">a new copy of @buf if the copy succeeded, %NULL otherwise. a #GstBuffer. + line="765">a #GstBuffer. @@ -3292,7 +3352,7 @@ copy of the data the source buffer contains. Copies the information from @src into @dest. + line="529">Copies the information from @src into @dest. If @dest already contains memory and @flags contains GST_BUFFER_COPY_MEMORY, the memory from @src will be appended to @dest. @@ -3302,38 +3362,38 @@ the memory from @src will be appended to @dest. %TRUE if the copying succeeded, %FALSE otherwise. + line="544">%TRUE if the copying succeeded, %FALSE otherwise. a destination #GstBuffer + line="531">a destination #GstBuffer a source #GstBuffer + line="532">a source #GstBuffer flags indicating what metadata fields should be copied. + line="533">flags indicating what metadata fields should be copied. offset to copy from + line="534">offset to copy from total size to copy. If -1, all data is copied. + line="535">total size to copy. If -1, all data is copied. @@ -3341,7 +3401,7 @@ the memory from @src will be appended to @dest. Creates a sub-buffer from @parent at @offset and @size. + line="2135">Creates a sub-buffer from @parent at @offset and @size. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to #GST_CLOCK_TIME_NONE and @@ -3353,7 +3413,7 @@ to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. the new #GstBuffer or %NULL if copying + line="2153">the new #GstBuffer or %NULL if copying failed. @@ -3361,26 +3421,26 @@ to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. a #GstBuffer. + line="2137">a #GstBuffer. the #GstBufferCopyFlags + line="2138">the #GstBufferCopyFlags the offset into parent #GstBuffer at which the new sub-buffer + line="2139">the offset into parent #GstBuffer at which the new sub-buffer begins. the size of the new #GstBuffer sub-buffer, in bytes. If -1, all + line="2141">the size of the new #GstBuffer sub-buffer, in bytes. If -1, all data is copied. @@ -3389,12 +3449,12 @@ to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. Copies @size bytes starting from @offset in @buffer to @dest. + line="1983">Copies @size bytes starting from @offset in @buffer to @dest. The amount of bytes extracted. This value can be lower than @size + line="1993">The amount of bytes extracted. This value can be lower than @size when @buffer did not contain enough data. @@ -3402,13 +3462,13 @@ to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. a #GstBuffer. + line="1985">a #GstBuffer. the offset to extract + line="1986">the offset to extract transfer-ownership="none"> + line="1987"> the destination address - + the size to extract + line="1989">the size to extract @@ -3439,7 +3496,7 @@ to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. version="1.0.10"> Extracts a copy of at most @size bytes the data at @offset into + line="2562">Extracts a copy of at most @size bytes the data at @offset into newly-allocated memory. @dest must be freed using g_free() when done. @@ -3449,19 +3506,19 @@ newly-allocated memory. @dest must be freed using g_free() when done. a #GstBuffer + line="2564">a #GstBuffer the offset to extract + line="2565">the offset to extract the size to extract + line="2566">the size to extract transfer-ownership="full"> A pointer where + line="2567">A pointer where the destination array will be written. Might be %NULL if the size is 0. @@ -3482,7 +3539,7 @@ newly-allocated memory. @dest must be freed using g_free() when done. transfer-ownership="full"> A location where the size of @dest can be written + line="2569">A location where the size of @dest can be written @@ -3490,12 +3547,12 @@ newly-allocated memory. @dest must be freed using g_free() when done. Copies @size bytes from @src to @buffer at @offset. + line="1931">Copies @size bytes from @src to @buffer at @offset. The amount of bytes copied. This value can be lower than @size + line="1940">The amount of bytes copied. This value can be lower than @size when @buffer did not contain enough data. @@ -3503,19 +3560,19 @@ newly-allocated memory. @dest must be freed using g_free() when done. a #GstBuffer. + line="1933">a #GstBuffer. the offset to fill + line="1934">the offset to fill the source address + line="1935">the source address @@ -3523,7 +3580,7 @@ newly-allocated memory. @dest must be freed using g_free() when done. the size to fill + line="1936">the size to fill @@ -3531,7 +3588,7 @@ newly-allocated memory. @dest must be freed using g_free() when done. Finds the memory blocks that span @size bytes starting from @offset + line="1391">Finds the memory blocks that span @size bytes starting from @offset in @buffer. When this function returns %TRUE, @idx will contain the index of the first @@ -3545,7 +3602,7 @@ for @offset. %TRUE when @size bytes starting from @offset could be found in + line="1411">%TRUE when @size bytes starting from @offset could be found in @buffer and @idx, @length and @skip will be filled. @@ -3553,19 +3610,19 @@ for @offset. a #GstBuffer. + line="1393">a #GstBuffer. an offset + line="1394">an offset a size + line="1395">a size pointer to index + line="1396">pointer to index pointer to length + line="1397">pointer to length pointer to skip + line="1398">pointer to skip @@ -3600,7 +3657,7 @@ for @offset. Calls @func with @user_data for each meta in @buffer. + line="2490">Calls @func with @user_data for each meta in @buffer. @func can modify the passed meta pointer or its contents. The return value of @func defines if this function returns or if the remaining metadata items @@ -3609,14 +3666,14 @@ in the buffer should be skipped. %FALSE when @func returned %FALSE for one of the metadata. + line="2502">%FALSE when @func returned %FALSE for one of the metadata. a #GstBuffer + line="2492">a #GstBuffer closure="1"> a #GstBufferForeachMetaFunc to call + line="2493">a #GstBufferForeachMetaFunc to call @@ -3635,7 +3692,7 @@ in the buffer should be skipped. allow-none="1"> user data passed to @func + line="2494">user data passed to @func @@ -3643,20 +3700,20 @@ in the buffer should be skipped. Gets all the memory blocks in @buffer. The memory blocks will be merged + line="1226">Gets all the memory blocks in @buffer. The memory blocks will be merged into one large #GstMemory. a #GstMemory that contains the merged memory. + line="1233">a #GstMemory that contains the merged memory. a #GstBuffer. + line="1228">a #GstBuffer. @@ -3666,25 +3723,25 @@ into one large #GstMemory. version="1.20"> Finds the first #GstCustomMeta on @buffer for the desired @name. + line="2992">Finds the first #GstCustomMeta on @buffer for the desired @name. the #GstCustomMeta + line="2999">the #GstCustomMeta a #GstBuffer + line="2994">a #GstBuffer the registered name of the custom meta to retrieve. + line="2995">the registered name of the custom meta to retrieve. @@ -3694,19 +3751,19 @@ into one large #GstMemory. version="1.10"> Gets the #GstBufferFlags flags set on this buffer. + line="363">Gets the #GstBufferFlags flags set on this buffer. the flags set on this buffer. + line="369">the flags set on this buffer. a #GstBuffer + line="365">a #GstBuffer @@ -3714,12 +3771,12 @@ into one large #GstMemory. Gets the memory block at index @idx in @buffer. + line="1210">Gets the memory block at index @idx in @buffer. a #GstMemory that contains the data of the + line="1217">a #GstMemory that contains the data of the memory block at @idx. @@ -3727,13 +3784,13 @@ memory block at @idx. a #GstBuffer. + line="1212">a #GstBuffer. an index + line="1213">an index @@ -3742,7 +3799,7 @@ memory block at @idx. c:identifier="gst_buffer_get_memory_range"> Gets @length memory blocks in @buffer starting at @idx. The memory blocks will + line="1241">Gets @length memory blocks in @buffer starting at @idx. The memory blocks will be merged into one large #GstMemory. If @length is -1, all memory starting from @idx is merged. @@ -3750,7 +3807,7 @@ If @length is -1, all memory starting from @idx is merged. a #GstMemory that contains the merged data of @length + line="1252">a #GstMemory that contains the merged data of @length blocks starting at @idx. @@ -3758,19 +3815,19 @@ If @length is -1, all memory starting from @idx is merged. a #GstBuffer. + line="1243">a #GstBuffer. an index + line="1244">an index a length + line="1245">a length @@ -3778,7 +3835,7 @@ If @length is -1, all memory starting from @idx is merged. Gets the metadata for @api on buffer. When there is no such metadata, %NULL is + line="2239">Gets the metadata for @api on buffer. When there is no such metadata, %NULL is returned. If multiple metadata with the given @api are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use gst_buffer_iterate_meta() or gst_buffer_foreach_meta() instead @@ -3787,20 +3844,20 @@ and check the `meta->info.api` member for the API type. the metadata for @api on @buffer. + line="2250">the metadata for @api on @buffer. a #GstBuffer + line="2241">a #GstBuffer the #GType of an API + line="2242">the #GType of an API @@ -3812,20 +3869,20 @@ and check the `meta->info.api` member for the API type. number of metas of type @api_type on @buffer. + line="2277">number of metas of type @api_type on @buffer. a #GstBuffer + line="2274">a #GstBuffer the #GType of an API + line="2275">the #GType of an API @@ -3835,16 +3892,16 @@ and check the `meta->info.api` member for the API type. version="1.14"> Finds the first #GstReferenceTimestampMeta on @buffer that conforms to + line="2766">Finds the first #GstReferenceTimestampMeta on @buffer that conforms to @reference. Conformance is tested by checking if the meta's reference is a subset of @reference. Buffers can contain multiple #GstReferenceTimestampMeta metadata items. - + the #GstReferenceTimestampMeta or %NULL when there + line="2777">the #GstReferenceTimestampMeta or %NULL when there is no such metadata on @buffer. @@ -3853,7 +3910,7 @@ is no such metadata on @buffer. a #GstBuffer + line="2768">a #GstBuffer allow-none="1"> a reference #GstCaps + line="2769">a reference #GstCaps @@ -3870,19 +3927,19 @@ is no such metadata on @buffer. Gets the total size of the memory blocks in @buffer. + line="1548">Gets the total size of the memory blocks in @buffer. total size of the memory blocks in @buffer. + line="1554">total size of the memory blocks in @buffer. a #GstBuffer. + line="1550">a #GstBuffer. @@ -3890,7 +3947,7 @@ is no such metadata on @buffer. Gets the total size of the memory blocks in @buffer. + line="1526">Gets the total size of the memory blocks in @buffer. When not %NULL, @offset will contain the offset of the data in the first memory block in @buffer and @maxsize will contain the sum of @@ -3901,14 +3958,14 @@ buffer memory blocks with gst_buffer_resize(). total size of the memory blocks in @buffer. + line="1540">total size of the memory blocks in @buffer. a #GstBuffer. + line="1528">a #GstBuffer. allow-none="1"> a pointer to the offset + line="1529">a pointer to the offset allow-none="1"> a pointer to the maxsize + line="1530">a pointer to the maxsize @@ -3938,7 +3995,7 @@ buffer memory blocks with gst_buffer_resize(). Gets the total size of @length memory blocks stating from @idx in @buffer. + line="1571">Gets the total size of @length memory blocks stating from @idx in @buffer. When not %NULL, @offset will contain the offset of the data in the memory block in @buffer at @idx and @maxsize will contain the sum of the size @@ -3950,26 +4007,26 @@ gst_buffer_resize_range(). total size of @length memory blocks starting at @idx in @buffer. + line="1588">total size of @length memory blocks starting at @idx in @buffer. a #GstBuffer. + line="1573">a #GstBuffer. an index + line="1574">an index a length + line="1575">a length allow-none="1"> a pointer to the offset + line="1576">a pointer to the offset allow-none="1"> a pointer to the maxsize + line="1577">a pointer to the maxsize @@ -4001,25 +4058,25 @@ gst_buffer_resize_range(). version="1.10"> Gives the status of a specific flag on a buffer. + line="379">Gives the status of a specific flag on a buffer. %TRUE if all flags in @flags are found on @buffer. + line="386">%TRUE if all flags in @flags are found on @buffer. a #GstBuffer + line="381">a #GstBuffer the #GstBufferFlags flag to check. + line="382">the #GstBufferFlags flag to check. @@ -4027,7 +4084,7 @@ gst_buffer_resize_range(). Inserts the memory block @mem into @buffer at @idx. This function takes ownership + line="1133">Inserts the memory block @mem into @buffer at @idx. This function takes ownership of @mem and thus doesn't increase its refcount. Only gst_buffer_get_max_memory() can be added to a buffer. If more memory is @@ -4041,19 +4098,19 @@ the new memory. a #GstBuffer. + line="1135">a #GstBuffer. the index to add the memory at, or -1 to append it to the end + line="1136">the index to add the memory at, or -1 to append it to the end a #GstMemory. + line="1137">a #GstMemory. @@ -4063,7 +4120,7 @@ the new memory. version="1.4"> Checks if all memory blocks in @buffer are writable. + line="1507">Checks if all memory blocks in @buffer are writable. Note that this function does not check if @buffer is writable, use gst_buffer_is_writable() to check that if needed. @@ -4071,14 +4128,14 @@ gst_buffer_is_writable() to check that if needed. %TRUE if all memory blocks in @buffer are writable + line="1516">%TRUE if all memory blocks in @buffer are writable a #GstBuffer. + line="1509">a #GstBuffer. @@ -4088,7 +4145,7 @@ gst_buffer_is_writable() to check that if needed. version="1.4"> Checks if @length memory blocks in @buffer starting from @idx are writable. + line="1464">Checks if @length memory blocks in @buffer starting from @idx are writable. @length can be -1 to check all the memory blocks after @idx. @@ -4098,26 +4155,26 @@ gst_buffer_is_writable() to check that if needed. %TRUE if the memory range is writable + line="1477">%TRUE if the memory range is writable a #GstBuffer. + line="1466">a #GstBuffer. an index + line="1467">an index a length, should not be 0 + line="1468">a length, should not be 0 @@ -4127,7 +4184,7 @@ gst_buffer_is_writable() to check that if needed. introspectable="0"> Retrieves the next #GstMeta after @current. If @state points + line="2412">Retrieves the next #GstMeta after @current. If @state points to %NULL, the first metadata is returned. @state will be updated with an opaque state pointer @@ -4135,7 +4192,7 @@ to %NULL, the first metadata is returned. The next #GstMeta or %NULL + line="2422">The next #GstMeta or %NULL when there are no more items. @@ -4143,7 +4200,7 @@ when there are no more items. a #GstBuffer + line="2414">a #GstBuffer nullable="1"> an opaque state pointer + line="2415">an opaque state pointer @@ -4164,7 +4221,7 @@ when there are no more items. introspectable="0"> Retrieves the next #GstMeta of type @meta_api_type after the current one + line="2447">Retrieves the next #GstMeta of type @meta_api_type after the current one according to @state. If @state points to %NULL, the first metadata of type @meta_api_type is returned. @@ -4173,7 +4230,7 @@ type @meta_api_type is returned. The next #GstMeta of type + line="2459">The next #GstMeta of type @meta_api_type or %NULL when there are no more items. @@ -4181,7 +4238,7 @@ type @meta_api_type is returned. a #GstBuffer + line="2449">a #GstBuffer an opaque state pointer + line="2450">an opaque state pointer only return #GstMeta of this type + line="2451">only return #GstMeta of this type @@ -4205,7 +4262,7 @@ type @meta_api_type is returned. Fills @info with the #GstMapInfo of all merged memory blocks in @buffer. + line="1788">Fills @info with the #GstMapInfo of all merged memory blocks in @buffer. @flags describe the desired access of the memory. When @flags is #GST_MAP_WRITE, @buffer should be writable (as returned from @@ -4221,14 +4278,14 @@ usage. %TRUE if the map succeeded and @info contains valid data. + line="1807">%TRUE if the map succeeded and @info contains valid data. a #GstBuffer. + line="1790">a #GstBuffer. transfer-ownership="none"> info about the mapping + line="1791">info about the mapping flags for the mapping + line="1792">flags for the mapping @@ -4251,7 +4308,7 @@ usage. Fills @info with the #GstMapInfo of @length merged memory blocks + line="1815">Fills @info with the #GstMapInfo of @length merged memory blocks starting at @idx in @buffer. When @length is -1, all memory blocks starting from @idx are merged and mapped. @@ -4268,7 +4325,7 @@ The memory in @info should be unmapped with gst_buffer_unmap() after usage. %TRUE if the map succeeded and @info contains valid + line="1837">%TRUE if the map succeeded and @info contains valid data. @@ -4276,19 +4333,19 @@ data. a #GstBuffer. + line="1817">a #GstBuffer. an index + line="1818">an index a length + line="1819">a length transfer-ownership="none"> info about the mapping + line="1820">info about the mapping flags for the mapping + line="1821">flags for the mapping @@ -4311,31 +4368,31 @@ data. Compares @size bytes starting from @offset in @buffer with the memory in @mem. + line="2034">Compares @size bytes starting from @offset in @buffer with the memory in @mem. 0 if the memory is equal. + line="2043">0 if the memory is equal. a #GstBuffer. + line="2036">a #GstBuffer. the offset in @buffer + line="2037">the offset in @buffer the memory to compare + line="2038">the memory to compare @@ -4343,7 +4400,7 @@ data. the size to compare + line="2039">the size to compare @@ -4351,12 +4408,12 @@ data. Fills @buf with @size bytes with @val starting from @offset. + line="2087">Fills @buf with @size bytes with @val starting from @offset. The amount of bytes filled. This value can be lower than @size + line="2096">The amount of bytes filled. This value can be lower than @size when @buffer did not contain enough data. @@ -4364,25 +4421,25 @@ data. a #GstBuffer. + line="2089">a #GstBuffer. the offset in @buffer + line="2090">the offset in @buffer the value to set + line="2091">the value to set the size to set + line="2092">the size to set @@ -4390,20 +4447,20 @@ data. Gets the amount of memory blocks that this buffer has. This amount is never + line="1082">Gets the amount of memory blocks that this buffer has. This amount is never larger than what gst_buffer_get_max_memory() returns. the number of memory blocks this buffer is made of. + line="1089">the number of memory blocks this buffer is made of. a #GstBuffer. + line="1084">a #GstBuffer. @@ -4411,27 +4468,27 @@ larger than what gst_buffer_get_max_memory() returns. Gets the memory block at @idx in @buffer. The memory block stays valid until + line="1190">Gets the memory block at @idx in @buffer. The memory block stays valid until the memory block in @buffer is removed, replaced or merged, typically with any call that modifies the memory in @buffer. the #GstMemory at @idx. + line="1199">the #GstMemory at @idx. a #GstBuffer. + line="1192">a #GstBuffer. an index + line="1193">an index @@ -4439,7 +4496,7 @@ any call that modifies the memory in @buffer. Prepends the memory block @mem to @buffer. This function takes + line="1099">Prepends the memory block @mem to @buffer. This function takes ownership of @mem and thus doesn't increase its refcount. This function is identical to gst_buffer_insert_memory() with an index of 0. @@ -4452,13 +4509,13 @@ See gst_buffer_insert_memory() for more details. a #GstBuffer. + line="1101">a #GstBuffer. a #GstMemory. + line="1102">a #GstMemory. @@ -4467,7 +4524,7 @@ See gst_buffer_insert_memory() for more details. c:identifier="gst_buffer_remove_all_memory"> Removes all the memory blocks in @buffer. + line="1348">Removes all the memory blocks in @buffer. @@ -4476,7 +4533,7 @@ See gst_buffer_insert_memory() for more details. a #GstBuffer. + line="1350">a #GstBuffer. @@ -4484,7 +4541,7 @@ See gst_buffer_insert_memory() for more details. Removes the memory block in @b at index @i. + line="1335">Removes the memory block in @b at index @i. @@ -4493,13 +4550,13 @@ See gst_buffer_insert_memory() for more details. a #GstBuffer. + line="1337">a #GstBuffer. an index + line="1338">an index @@ -4508,7 +4565,7 @@ See gst_buffer_insert_memory() for more details. c:identifier="gst_buffer_remove_memory_range"> Removes @length memory blocks in @buffer starting from @idx. + line="1361">Removes @length memory blocks in @buffer starting from @idx. @length can be -1, in which case all memory starting from @idx is removed. @@ -4519,19 +4576,19 @@ See gst_buffer_insert_memory() for more details. a #GstBuffer. + line="1363">a #GstBuffer. an index + line="1364">an index a length + line="1365">a length @@ -4539,12 +4596,12 @@ See gst_buffer_insert_memory() for more details. Removes the metadata for @meta on @buffer. + line="2358">Removes the metadata for @meta on @buffer. %TRUE if the metadata existed and was removed, %FALSE if no such + line="2365">%TRUE if the metadata existed and was removed, %FALSE if no such metadata was on @buffer. @@ -4552,13 +4609,13 @@ metadata was on @buffer. a #GstBuffer + line="2360">a #GstBuffer a #GstMeta + line="2361">a #GstMeta @@ -4567,7 +4624,7 @@ metadata was on @buffer. c:identifier="gst_buffer_replace_all_memory"> Replaces all memory in @buffer with @mem. + line="1287">Replaces all memory in @buffer with @mem. @@ -4576,13 +4633,13 @@ metadata was on @buffer. a #GstBuffer. + line="1289">a #GstBuffer. a #GstMemory + line="1290">a #GstMemory @@ -4590,7 +4647,7 @@ metadata was on @buffer. Replaces the memory block at index @idx in @buffer with @mem. + line="1273">Replaces the memory block at index @idx in @buffer with @mem. @@ -4599,19 +4656,19 @@ metadata was on @buffer. a #GstBuffer. + line="1275">a #GstBuffer. an index + line="1276">an index a #GstMemory + line="1277">a #GstMemory @@ -4620,7 +4677,7 @@ metadata was on @buffer. c:identifier="gst_buffer_replace_memory_range"> Replaces @length memory blocks in @buffer starting at @idx with @mem. + line="1300">Replaces @length memory blocks in @buffer starting at @idx with @mem. If @length is -1, all memory starting from @idx will be removed and replaced with @mem. @@ -4634,25 +4691,25 @@ replaced with @mem. a #GstBuffer. + line="1302">a #GstBuffer. an index + line="1303">an index a length, should not be 0 + line="1304">a length, should not be 0 a #GstMemory + line="1305">a #GstMemory @@ -4660,7 +4717,7 @@ replaced with @mem. Sets the offset and total size of the memory blocks in @buffer. + line="1653">Sets the offset and total size of the memory blocks in @buffer. @@ -4669,19 +4726,19 @@ replaced with @mem. a #GstBuffer. + line="1655">a #GstBuffer. the offset adjustment + line="1656">the offset adjustment the new size or -1 to just adjust the offset + line="1657">the new size or -1 to just adjust the offset @@ -4689,44 +4746,44 @@ replaced with @mem. Sets the total size of the @length memory blocks starting at @idx in + line="1680">Sets the total size of the @length memory blocks starting at @idx in @buffer %TRUE if resizing succeeded, %FALSE otherwise. + line="1691">%TRUE if resizing succeeded, %FALSE otherwise. a #GstBuffer. + line="1682">a #GstBuffer. an index + line="1683">an index a length + line="1684">a length the offset adjustment + line="1685">the offset adjustment the new size or -1 to just adjust the offset + line="1686">the new size or -1 to just adjust the offset @@ -4736,25 +4793,25 @@ replaced with @mem. version="1.10"> Sets one or more buffer flags on a buffer. + line="396">Sets one or more buffer flags on a buffer. %TRUE if @flags were successfully set on buffer. + line="403">%TRUE if @flags were successfully set on buffer. a #GstBuffer + line="398">a #GstBuffer the #GstBufferFlags to set. + line="399">the #GstBufferFlags to set. @@ -4762,7 +4819,7 @@ replaced with @mem. Sets the total size of the memory blocks in @buffer. + line="1667">Sets the total size of the memory blocks in @buffer. @@ -4771,13 +4828,13 @@ replaced with @mem. a #GstBuffer. + line="1669">a #GstBuffer. the new size + line="1670">the new size @@ -4785,7 +4842,7 @@ replaced with @mem. Releases the memory previously mapped with gst_buffer_map(). + line="1915">Releases the memory previously mapped with gst_buffer_map(). @@ -4794,13 +4851,13 @@ replaced with @mem. a #GstBuffer. + line="1917">a #GstBuffer. a #GstMapInfo + line="1918">a #GstMapInfo @@ -4810,25 +4867,25 @@ replaced with @mem. version="1.10"> Clears one or more buffer flags. + line="414">Clears one or more buffer flags. true if @flags is successfully cleared from buffer. + line="421">true if @flags is successfully cleared from buffer. a #GstBuffer + line="416">a #GstBuffer the #GstBufferFlags to clear + line="417">the #GstBufferFlags to clear @@ -4838,7 +4895,7 @@ replaced with @mem. version="1.2"> Gets the maximum amount of memory blocks that a buffer can hold. This is a + line="510">Gets the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function. When more memory blocks are added, existing memory blocks will be merged @@ -4847,7 +4904,7 @@ together to make room for the new block. the maximum amount of memory blocks that a buffer can hold. + line="519">the maximum amount of memory blocks that a buffer can hold. @@ -5159,32 +5216,32 @@ can reduce the amount of overhead for pushing each buffer individually. Creates a new, empty #GstBufferList. + line="172">Creates a new, empty #GstBufferList. the new #GstBufferList. + line="177">the new #GstBufferList. Creates a new, empty #GstBufferList. The list will have @size space + line="140">Creates a new, empty #GstBufferList. The list will have @size space preallocated so that memory reallocations can be avoided. the new #GstBufferList. + line="147">the new #GstBufferList. an initial reserved size + line="142">an initial reserved size @@ -5194,20 +5251,20 @@ preallocated so that memory reallocations can be avoided. version="1.14"> Calculates the size of the data contained in @list by adding the + line="515">Calculates the size of the data contained in @list by adding the size of all buffers. the size of the data contained in @list in bytes. + line="522">the size of the data contained in @list in bytes. a #GstBufferList + line="517">a #GstBufferList @@ -5217,20 +5274,20 @@ size of all buffers. version="1.6"> Creates a copy of the given buffer list. This will make a newly allocated + line="476">Creates a copy of the given buffer list. This will make a newly allocated copy of the buffers that the source buffer list contains. a new copy of @list. + line="483">a new copy of @list. a #GstBufferList + line="478">a #GstBufferList @@ -5238,7 +5295,7 @@ copy of the buffers that the source buffer list contains. Calls @func with @data for each buffer in @list. + line="223">Calls @func with @data for each buffer in @list. @func can modify the passed buffer pointer or its contents. The return value of @func defines if this function returns or if the remaining buffers in @@ -5247,7 +5304,7 @@ the list should be skipped. %TRUE when @func returned %TRUE for each buffer in @list or when + line="235">%TRUE when @func returned %TRUE for each buffer in @list or when @list is empty. @@ -5255,7 +5312,7 @@ the list should be skipped. a #GstBufferList + line="225">a #GstBufferList closure="1"> a #GstBufferListFunc to call + line="226">a #GstBufferListFunc to call allow-none="1"> user data passed to @func + line="227">user data passed to @func @@ -5281,30 +5338,30 @@ the list should be skipped. Gets the buffer at @idx. + line="325">Gets the buffer at @idx. You must make sure that @idx does not exceed the number of buffers available. - + the buffer at @idx in @group - or %NULL when there is no buffer. The buffer remains valid as - long as @list is valid and buffer is not removed from the list. + line="335">the buffer at @idx in @group. + The returned buffer remains valid as long as @list is valid and + buffer is not removed from the list. a #GstBufferList + line="327">a #GstBufferList the index + line="328">the index @@ -5314,16 +5371,16 @@ buffers available. version="1.14"> Gets the buffer at @idx, ensuring it is a writable buffer. + line="348">Gets the buffer at @idx, ensuring it is a writable buffer. You must make sure that @idx does not exceed the number of buffers available. - + the buffer at @idx in @group. - The returned buffer remains valid as long as @list is valid and + line="358">the buffer at @idx in @group. + The returned buffer remains valid as long as @list is valid and the buffer is not removed from the list. @@ -5331,13 +5388,13 @@ buffers available. a (writable) #GstBufferList + line="350">a (writable) #GstBufferList the index + line="351">the index @@ -5345,7 +5402,7 @@ buffers available. Inserts @buffer at @idx in @list. Other buffers are moved to make room for + line="396">Inserts @buffer at @idx in @list. Other buffers are moved to make room for this new buffer. A -1 value for @idx will append the buffer at the end. @@ -5357,19 +5414,19 @@ A -1 value for @idx will append the buffer at the end. a #GstBufferList + line="398">a #GstBufferList the index + line="399">the index a #GstBuffer + line="400">a #GstBuffer @@ -5377,19 +5434,19 @@ A -1 value for @idx will append the buffer at the end. Returns the number of buffers in @list. + line="185">Returns the number of buffers in @list. the number of buffers in the buffer list + line="191">the number of buffers in the buffer list a #GstBufferList + line="187">a #GstBufferList @@ -5397,7 +5454,7 @@ A -1 value for @idx will append the buffer at the end. Removes @length buffers starting from @idx in @list. The following buffers + line="456">Removes @length buffers starting from @idx in @list. The following buffers are moved to close the gap. @@ -5407,19 +5464,19 @@ are moved to close the gap. a #GstBufferList + line="458">a #GstBufferList the index + line="459">the index the amount to remove + line="460">the amount to remove @@ -5517,16 +5574,16 @@ pool with gst_buffer_pool_release_buffer() when their refcount drops to 0. The bufferpool can be deactivated again with gst_buffer_pool_set_active(). All further gst_buffer_pool_acquire_buffer() calls will return an error. When all buffers are returned to the pool they will be freed. - + Creates a new #GstBufferPool instance. - + line="216">Creates a new #GstBufferPool instance. + a new #GstBufferPool instance + line="221">a new #GstBufferPool instance @@ -5534,11 +5591,11 @@ all buffers are returned to the pool they will be freed. c:identifier="gst_buffer_pool_config_add_option"> Enables the option in @config. This will instruct the @bufferpool to enable + line="870">Enables the option in @config. This will instruct the @bufferpool to enable the specified option on the buffers that it allocates. The options supported by @pool can be retrieved with gst_buffer_pool_get_options(). - + @@ -5546,13 +5603,13 @@ The options supported by @pool can be retrieved with gst_buffer_pool_get_options a #GstBufferPool configuration + line="872">a #GstBufferPool configuration an option to add + line="873">an option to add @@ -5561,19 +5618,19 @@ The options supported by @pool can be retrieved with gst_buffer_pool_get_options c:identifier="gst_buffer_pool_config_get_allocator"> Gets the @allocator and @params from @config. - + line="1020">Gets the @allocator and @params from @config. + %TRUE, if the values are set. + line="1028">%TRUE, if the values are set. a #GstBufferPool configuration + line="1022">a #GstBufferPool configuration a #GstAllocator, or %NULL + line="1023">a #GstAllocator, or %NULL #GstAllocationParams, or %NULL + line="1024">#GstAllocationParams, or %NULL @@ -5605,26 +5662,26 @@ The options supported by @pool can be retrieved with gst_buffer_pool_get_options c:identifier="gst_buffer_pool_config_get_option"> Parses an available @config and gets the option at @index of the options API + line="934">Parses an available @config and gets the option at @index of the options API array. - + the option at @index. + line="942">the option at @index. a #GstBufferPool configuration + line="936">a #GstBufferPool configuration position in the option array to read + line="937">position in the option array to read @@ -5633,19 +5690,19 @@ array. c:identifier="gst_buffer_pool_config_get_params"> Gets the configuration values from @config. - + line="993">Gets the configuration values from @config. + %TRUE if all parameters could be fetched. + line="1003">%TRUE if all parameters could be fetched. a #GstBufferPool configuration + line="995">a #GstBufferPool configuration allow-none="1"> the caps of buffers + line="996">the caps of buffers allow-none="1"> the size of each buffer, not including prefix and padding + line="997">the size of each buffer, not including prefix and padding allow-none="1"> the minimum amount of buffers to allocate. + line="998">the minimum amount of buffers to allocate. allow-none="1"> the maximum amount of buffers to allocate or 0 for unlimited. + line="999">the maximum amount of buffers to allocate or 0 for unlimited. @@ -5699,25 +5756,25 @@ array. c:identifier="gst_buffer_pool_config_has_option"> Checks if @config contains @option. - + line="963">Checks if @config contains @option. + %TRUE if the options array contains @option. + line="970">%TRUE if the options array contains @option. a #GstBufferPool configuration + line="965">a #GstBufferPool configuration an option + line="966">an option @@ -5726,20 +5783,20 @@ array. c:identifier="gst_buffer_pool_config_n_options"> Retrieves the number of values currently stored in the options array of the + line="910">Retrieves the number of values currently stored in the options array of the @config structure. - + the options array size as a #guint. + line="917">the options array size as a #guint. a #GstBufferPool configuration + line="912">a #GstBufferPool configuration @@ -5748,7 +5805,7 @@ array. c:identifier="gst_buffer_pool_config_set_allocator"> Sets the @allocator and @params on @config. + line="839">Sets the @allocator and @params on @config. One of @allocator and @params can be %NULL, but not both. When @allocator is %NULL, the default allocator of the pool will use the values in @param @@ -5760,7 +5817,7 @@ with the values that it is able to do. Some pools are, for example, not able to operate with different allocators or cannot allocate with the values specified in @params. Use gst_buffer_pool_get_config() to get the currently used values. - + @@ -5768,7 +5825,7 @@ used values. a #GstBufferPool configuration + line="841">a #GstBufferPool configuration allow-none="1"> a #GstAllocator + line="842">a #GstAllocator allow-none="1"> #GstAllocationParams + line="843">#GstAllocationParams @@ -5795,8 +5852,8 @@ used values. c:identifier="gst_buffer_pool_config_set_params"> Configures @config with the given parameters. - + line="814">Configures @config with the given parameters. + @@ -5804,7 +5861,7 @@ used values. a #GstBufferPool configuration + line="816">a #GstBufferPool configuration allow-none="1"> caps for the buffers + line="817">caps for the buffers the size of each buffer, not including prefix and padding + line="818">the size of each buffer, not including prefix and padding the minimum amount of buffers to allocate. + line="819">the minimum amount of buffers to allocate. the maximum amount of buffers to allocate or 0 for unlimited. + line="820">the maximum amount of buffers to allocate or 0 for unlimited. @@ -5841,7 +5898,7 @@ used values. version="1.4"> Validates that changes made to @config are still valid in the context of the + line="1052">Validates that changes made to @config are still valid in the context of the expected parameters. This function is a helper that can be used to validate changes made by a pool to a config when gst_buffer_pool_set_config() returns %FALSE. This expects that @caps haven't changed and that @@ -5849,18 +5906,18 @@ returns %FALSE. This expects that @caps haven't changed and that This does not check if options or allocator parameters are still valid, won't check if size have changed, since changing the size is valid to adapt padding. - + %TRUE, if the parameters are valid in this context. + line="1071">%TRUE, if the parameters are valid in this context. a #GstBufferPool configuration + line="1054">a #GstBufferPool configuration allow-none="1"> the excepted caps of buffers + line="1055">the excepted caps of buffers the expected size of each buffer, not including prefix and padding + line="1056">the expected size of each buffer, not including prefix and padding the expected minimum amount of buffers to allocate. + line="1057">the expected minimum amount of buffers to allocate. the expect maximum amount of buffers to allocate or 0 for unlimited. + line="1058">the expect maximum amount of buffers to allocate or 0 for unlimited. @@ -5895,17 +5952,17 @@ padding. Acquires a buffer from @pool. @buffer should point to a memory location that + line="1221">Acquires a buffer from @pool. @buffer should point to a memory location that can hold a pointer to the new buffer. When the pool is empty, this function will by default block until a buffer is released into the pool again or when the pool is set to flushing or deactivated. @params can contain optional parameters to influence the allocation. - + a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is + line="1234">a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is inactive. @@ -5913,7 +5970,7 @@ inactive. a #GstBufferPool + line="1223">a #GstBufferPool nullable="1"> a location for a #GstBuffer + line="1224">a location for a #GstBuffer allow-none="1"> parameters. + line="1225">parameters. @@ -5941,17 +5998,17 @@ inactive. Allocate a buffer. the default implementation allocates + line="195">Allocate a buffer. the default implementation allocates buffers from the configured memory allocator and with the configured parameters. All metadata that is present on the allocated buffer will be marked as #GST_META_FLAG_POOLED and #GST_META_FLAG_LOCKED and will not be removed from the buffer in #GstBufferPoolClass::reset_buffer. The buffer should have the #GST_BUFFER_FLAG_TAG_MEMORY cleared. - + a #GstFlowReturn to indicate whether the allocation was + line="208">a #GstFlowReturn to indicate whether the allocation was successful. @@ -5959,7 +6016,7 @@ successful. the #GstBufferPool + line="197">the #GstBufferPool nullable="1"> a location for a #GstBuffer + line="198">a location for a #GstBuffer allow-none="1"> parameters. + line="199">parameters. @@ -5987,8 +6044,8 @@ successful. Enter the flushing state. - + line="251">Enter the flushing state. + @@ -5996,7 +6053,7 @@ successful. the #GstBufferPool + line="253">the #GstBufferPool @@ -6004,8 +6061,8 @@ successful. Leave the flushing state. - + line="261">Leave the flushing state. + @@ -6013,7 +6070,7 @@ successful. the #GstBufferPool + line="263">the #GstBufferPool @@ -6021,8 +6078,8 @@ successful. Free a buffer. The default implementation unrefs the buffer. - + line="242">Free a buffer. The default implementation unrefs the buffer. + @@ -6030,13 +6087,13 @@ successful. the #GstBufferPool + line="244">the #GstBufferPool the #GstBuffer to free + line="245">the #GstBuffer to free @@ -6044,14 +6101,14 @@ successful. Gets a %NULL terminated array of string with supported bufferpool options for + line="750">Gets a %NULL terminated array of string with supported bufferpool options for @pool. An option would typically be enabled with gst_buffer_pool_config_add_option(). a %NULL terminated array + line="758">a %NULL terminated array of strings. @@ -6061,7 +6118,7 @@ gst_buffer_pool_config_add_option(). a #GstBufferPool + line="752">a #GstBufferPool @@ -6069,12 +6126,12 @@ gst_buffer_pool_config_add_option(). Releases @buffer to @pool. @buffer should have previously been allocated from + line="1328">Releases @buffer to @pool. @buffer should have previously been allocated from @pool with gst_buffer_pool_acquire_buffer(). This function is usually called automatically when the last ref on @buffer disappears. - + @@ -6082,13 +6139,13 @@ disappears. a #GstBufferPool + line="1330">a #GstBufferPool a #GstBuffer + line="1331">a #GstBuffer @@ -6096,13 +6153,13 @@ disappears. Reset the buffer to its state when it was freshly allocated. + line="214">Reset the buffer to its state when it was freshly allocated. The default implementation will clear the flags, timestamps and will remove the metadata without the #GST_META_FLAG_POOLED flag (even the metadata with #GST_META_FLAG_LOCKED). If the #GST_BUFFER_FLAG_TAG_MEMORY was set, this function can also try to restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again. - + @@ -6110,13 +6167,13 @@ restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again. the #GstBufferPool + line="216">the #GstBufferPool the #GstBuffer to reset + line="217">the #GstBuffer to reset @@ -6124,7 +6181,7 @@ restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again. Sets the configuration of the pool. If the pool is already configured, and + line="630">Sets the configuration of the pool. If the pool is already configured, and the configuration hasn't changed, this function will return %TRUE. If the pool is active, this method will return %FALSE and active configuration will remain. Buffers allocated from this pool must be returned or else this @@ -6144,20 +6201,20 @@ This function takes ownership of @config. %TRUE when the configuration could be set. + line="652">%TRUE when the configuration could be set. a #GstBufferPool + line="632">a #GstBufferPool a #GstStructure + line="633">a #GstStructure @@ -6166,12 +6223,15 @@ This function takes ownership of @config. Start the bufferpool. The default implementation will preallocate -min-buffers buffers and put them in the queue. - +min-buffers buffers and put them in the queue. + +Subclasses do not need to chain up to the parent's default implementation +if they don't want min-buffers based preallocation. + whether the pool could be started. + line="163">whether the pool could be started. @@ -6186,21 +6246,21 @@ min-buffers buffers and put them in the queue. Stop the bufferpool. the default implementation will free the + line="167">Stop the bufferpool. the default implementation will free the preallocated buffers. This function is called when all the buffers are returned to the pool. - + whether the pool could be stopped. + line="175">whether the pool could be stopped. the #GstBufferPool + line="169">the #GstBufferPool @@ -6209,17 +6269,17 @@ returned to the pool. c:identifier="gst_buffer_pool_acquire_buffer"> Acquires a buffer from @pool. @buffer should point to a memory location that + line="1221">Acquires a buffer from @pool. @buffer should point to a memory location that can hold a pointer to the new buffer. When the pool is empty, this function will by default block until a buffer is released into the pool again or when the pool is set to flushing or deactivated. @params can contain optional parameters to influence the allocation. - + a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is + line="1234">a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is inactive. @@ -6227,7 +6287,7 @@ inactive. a #GstBufferPool + line="1223">a #GstBufferPool nullable="1"> a location for a #GstBuffer + line="1224">a location for a #GstBuffer allow-none="1"> parameters. + line="1225">parameters. @@ -6255,20 +6315,20 @@ inactive. Gets a copy of the current configuration of the pool. This configuration + line="725">Gets a copy of the current configuration of the pool. This configuration can be modified and used for the gst_buffer_pool_set_config() call. - + a copy of the current configuration of @pool. + line="732">a copy of the current configuration of @pool. a #GstBufferPool + line="727">a #GstBufferPool @@ -6276,14 +6336,14 @@ can be modified and used for the gst_buffer_pool_set_config() call. Gets a %NULL terminated array of string with supported bufferpool options for + line="750">Gets a %NULL terminated array of string with supported bufferpool options for @pool. An option would typically be enabled with gst_buffer_pool_config_add_option(). - + a %NULL terminated array + line="758">a %NULL terminated array of strings. @@ -6293,7 +6353,7 @@ gst_buffer_pool_config_add_option(). a #GstBufferPool + line="752">a #GstBufferPool @@ -6301,25 +6361,25 @@ gst_buffer_pool_config_add_option(). Checks if the bufferpool supports @option. - + line="787">Checks if the bufferpool supports @option. + %TRUE if the buffer pool contains @option. + line="794">%TRUE if the buffer pool contains @option. a #GstBufferPool + line="789">a #GstBufferPool an option + line="790">an option @@ -6327,20 +6387,20 @@ gst_buffer_pool_config_add_option(). Checks if @pool is active. A pool can be activated with the + line="570">Checks if @pool is active. A pool can be activated with the gst_buffer_pool_set_active() call. - + %TRUE when the pool is active. + line="577">%TRUE when the pool is active. a #GstBufferPool + line="572">a #GstBufferPool @@ -6349,12 +6409,12 @@ gst_buffer_pool_set_active() call. c:identifier="gst_buffer_pool_release_buffer"> Releases @buffer to @pool. @buffer should have previously been allocated from + line="1328">Releases @buffer to @pool. @buffer should have previously been allocated from @pool with gst_buffer_pool_acquire_buffer(). This function is usually called automatically when the last ref on @buffer disappears. - + @@ -6362,13 +6422,13 @@ disappears. a #GstBufferPool + line="1330">a #GstBufferPool a #GstBuffer + line="1331">a #GstBuffer @@ -6376,7 +6436,7 @@ disappears. Controls the active state of @pool. When the pool is inactive, new calls to + line="474">Controls the active state of @pool. When the pool is inactive, new calls to gst_buffer_pool_acquire_buffer() will return with %GST_FLOW_FLUSHING. Activating the bufferpool will preallocate all resources in the pool based on @@ -6385,11 +6445,11 @@ the configuration of the pool. Deactivating will free the resources again when there are no outstanding buffers. When there are outstanding buffers, they will be freed as soon as they are all returned to the pool. - + %FALSE when the pool was not configured or when preallocation of the + line="489">%FALSE when the pool was not configured or when preallocation of the buffers failed. @@ -6397,13 +6457,13 @@ buffers failed. a #GstBufferPool + line="476">a #GstBufferPool the new active state + line="477">the new active state @@ -6411,7 +6471,7 @@ buffers failed. Sets the configuration of the pool. If the pool is already configured, and + line="630">Sets the configuration of the pool. If the pool is already configured, and the configuration hasn't changed, this function will return %TRUE. If the pool is active, this method will return %FALSE and active configuration will remain. Buffers allocated from this pool must be returned or else this @@ -6427,24 +6487,24 @@ If the parameters in @config can not be set exactly, this function returns then be retrieved and refined with gst_buffer_pool_get_config(). This function takes ownership of @config. - + %TRUE when the configuration could be set. + line="652">%TRUE when the configuration could be set. a #GstBufferPool + line="632">a #GstBufferPool a #GstStructure + line="633">a #GstStructure @@ -6454,9 +6514,9 @@ This function takes ownership of @config. version="1.4"> Enables or disables the flushing state of a @pool without freeing or + line="1367">Enables or disables the flushing state of a @pool without freeing or allocating buffers. - + @@ -6464,13 +6524,13 @@ allocating buffers. a #GstBufferPool + line="1369">a #GstBufferPool whether to start or stop flushing + line="1370">whether to start or stop flushing @@ -6599,7 +6659,7 @@ return. The #GstBufferPool class. - + a %NULL terminated array + line="758">a %NULL terminated array of strings. @@ -6622,7 +6682,7 @@ return. a #GstBufferPool + line="752">a #GstBufferPool @@ -6634,20 +6694,20 @@ return. %TRUE when the configuration could be set. + line="652">%TRUE when the configuration could be set. a #GstBufferPool + line="632">a #GstBufferPool a #GstStructure + line="633">a #GstStructure @@ -6655,11 +6715,11 @@ return. - + whether the pool could be started. + line="163">whether the pool could be started. @@ -6674,18 +6734,18 @@ return. - + whether the pool could be stopped. + line="175">whether the pool could be stopped. the #GstBufferPool + line="169">the #GstBufferPool @@ -6693,11 +6753,11 @@ return. - + a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is + line="1234">a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is inactive. @@ -6705,7 +6765,7 @@ inactive. a #GstBufferPool + line="1223">a #GstBufferPool nullable="1"> a location for a #GstBuffer + line="1224">a location for a #GstBuffer allow-none="1"> parameters. + line="1225">parameters. @@ -6733,11 +6793,11 @@ inactive. - + a #GstFlowReturn to indicate whether the allocation was + line="208">a #GstFlowReturn to indicate whether the allocation was successful. @@ -6745,7 +6805,7 @@ successful. the #GstBufferPool + line="197">the #GstBufferPool nullable="1"> a location for a #GstBuffer + line="198">a location for a #GstBuffer allow-none="1"> parameters. + line="199">parameters. @@ -6773,7 +6833,7 @@ successful. - + @@ -6781,13 +6841,13 @@ successful. the #GstBufferPool + line="216">the #GstBufferPool the #GstBuffer to reset + line="217">the #GstBuffer to reset @@ -6795,7 +6855,7 @@ successful. - + @@ -6803,13 +6863,13 @@ successful. a #GstBufferPool + line="1330">a #GstBufferPool a #GstBuffer + line="1331">a #GstBuffer @@ -6817,7 +6877,7 @@ successful. - + @@ -6825,13 +6885,13 @@ successful. the #GstBufferPool + line="244">the #GstBufferPool the #GstBuffer to free + line="245">the #GstBuffer to free @@ -6839,7 +6899,7 @@ successful. - + @@ -6847,7 +6907,7 @@ successful. the #GstBufferPool + line="253">the #GstBufferPool @@ -6855,7 +6915,7 @@ successful. - + @@ -6863,7 +6923,7 @@ successful. the #GstBufferPool + line="263">the #GstBufferPool @@ -6977,12 +7037,12 @@ from READY to NULL state. Creates a new #GstBus instance. + line="298">Creates a new #GstBus instance. a new #GstBus instance + line="303">a new #GstBus instance @@ -7035,7 +7095,7 @@ from READY to NULL state. Adds a bus signal watch to the default main context with the default priority + line="1437">Adds a bus signal watch to the default main context with the default priority ( %G_PRIORITY_DEFAULT ). It is also possible to use a non-default main context set up using g_main_context_push_thread_default() (before one had to create a bus watch source and attach it to the desired main @@ -7055,7 +7115,7 @@ function is called. a #GstBus on which you want to receive the "message" signal + line="1439">a #GstBus on which you want to receive the "message" signal @@ -7064,7 +7124,7 @@ function is called. c:identifier="gst_bus_add_signal_watch_full"> Adds a bus signal watch to the default main context with the given @priority + line="1374">Adds a bus signal watch to the default main context with the given @priority (e.g. %G_PRIORITY_DEFAULT). It is also possible to use a non-default main context set up using g_main_context_push_thread_default() (before one had to create a bus watch source and attach it to the desired @@ -7087,13 +7147,13 @@ watch before you can set another type of watch. a #GstBus on which you want to receive the "message" signal + line="1376">a #GstBus on which you want to receive the "message" signal The priority of the watch. + line="1377">The priority of the watch. @@ -7104,7 +7164,7 @@ watch before you can set another type of watch. introspectable="0"> Adds a bus watch to the default main context with the default priority + line="1026">Adds a bus watch to the default main context with the default priority ( %G_PRIORITY_DEFAULT ). It is also possible to use a non-default main context set up using g_main_context_push_thread_default() (before one had to create a bus watch source and attach it to the desired main @@ -7126,20 +7186,20 @@ The bus watch will take its own reference to the @bus, so it is safe to unref The event source id or 0 if @bus already got an event source. + line="1051">The event source id or 0 if @bus already got an event source. a #GstBus to create the watch for + line="1028">a #GstBus to create the watch for A function to call when a message is received. + line="1029">A function to call when a message is received. user data passed to @func. + line="1030">user data passed to @func. @@ -7158,7 +7218,7 @@ The bus watch will take its own reference to the @bus, so it is safe to unref shadows="add_watch"> Adds a bus watch to the default main context with the given @priority (e.g. + line="979">Adds a bus watch to the default main context with the given @priority (e.g. %G_PRIORITY_DEFAULT). It is also possible to use a non-default main context set up using g_main_context_push_thread_default() (before one had to create a bus watch source and attach it to the desired main @@ -7183,20 +7243,20 @@ The bus watch will take its own reference to the @bus, so it is safe to unref The event source id or 0 if @bus already got an event source. + line="1009">The event source id or 0 if @bus already got an event source. a #GstBus to create the watch for. + line="981">a #GstBus to create the watch for. The priority of the watch. + line="982">The priority of the watch. A function to call when a message is received. + line="983">A function to call when a message is received. user data passed to @func. + line="984">user data passed to @func. the function to call when the source is removed. + line="985">the function to call when the source is removed. @@ -7230,26 +7290,26 @@ The bus watch will take its own reference to the @bus, so it is safe to unref c:identifier="gst_bus_async_signal_func"> A helper #GstBusFunc that can be used to convert all asynchronous messages + line="1265">A helper #GstBusFunc that can be used to convert all asynchronous messages into signals. %TRUE + line="1274">%TRUE a #GstBus + line="1267">a #GstBus the #GstMessage received + line="1268">the #GstMessage received allow-none="1"> user data + line="1269">user data @@ -7266,7 +7326,7 @@ into signals. Create watch for this bus. The #GSource will be dispatched whenever + line="913">Create watch for this bus. The #GSource will be dispatched whenever a message is on the bus. After the GSource is dispatched, the message is popped off the bus and unreffed. @@ -7276,14 +7336,14 @@ any signal watch added with #gst_bus_add_signal_watch. a #GSource that can be added to a #GMainLoop. + line="924">a #GSource that can be added to a #GMainLoop. a #GstBus to create the watch for + line="915">a #GstBus to create the watch for @@ -7292,7 +7352,7 @@ any signal watch added with #gst_bus_add_signal_watch. c:identifier="gst_bus_disable_sync_message_emission"> Instructs GStreamer to stop emitting the "sync-message" signal for this bus. + line="1348">Instructs GStreamer to stop emitting the "sync-message" signal for this bus. See gst_bus_enable_sync_message_emission() for more information. In the event that multiple pieces of code have called @@ -7309,7 +7369,7 @@ disable. a #GstBus on which you previously called + line="1350">a #GstBus on which you previously called gst_bus_enable_sync_message_emission() @@ -7319,7 +7379,7 @@ gst_bus_enable_sync_message_emission() c:identifier="gst_bus_enable_sync_message_emission"> Instructs GStreamer to emit the "sync-message" signal after running the bus's + line="1318">Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler. This function is here so that code can ensure that they can synchronously receive messages without having to affect what the bin's sync handler is. @@ -7342,7 +7402,7 @@ signal is marshalled to the main thread via the #GMainLoop. a #GstBus on which you want to receive the "sync-message" signal + line="1320">a #GstBus on which you want to receive the "sync-message" signal @@ -7352,7 +7412,7 @@ signal is marshalled to the main thread via the #GMainLoop. version="1.14"> Gets the file descriptor from the bus which can be used to get notified about + line="771">Gets the file descriptor from the bus which can be used to get notified about messages being available with functions like g_poll(), and allows integration into other event loops based on file descriptors. Whenever a message is available, the POLLIN / %G_IO_IN event is set. @@ -7368,7 +7428,7 @@ GstBus API, e.g. gst_bus_pop(). A #GstBus + line="773">A #GstBus transfer-ownership="none"> A GPollFD to fill + line="774">A GPollFD to fill @@ -7385,13 +7445,13 @@ GstBus API, e.g. gst_bus_pop(). Checks if there are pending messages on the bus that + line="460">Checks if there are pending messages on the bus that should be handled. %TRUE if there are messages on the bus to be handled, %FALSE + line="467">%TRUE if there are messages on the bus to be handled, %FALSE otherwise. @@ -7399,7 +7459,7 @@ otherwise. a #GstBus to check + line="462">a #GstBus to check @@ -7407,13 +7467,13 @@ otherwise. Peeks the message on the top of the bus' queue. The message will remain + line="702">Peeks the message on the top of the bus' queue. The message will remain on the bus' message queue. the #GstMessage that is on the + line="709">the #GstMessage that is on the bus, or %NULL if the bus is empty. @@ -7421,7 +7481,7 @@ on the bus' message queue. a #GstBus + line="704">a #GstBus @@ -7429,7 +7489,7 @@ on the bus' message queue. Polls the bus for messages. Will block while waiting for messages to come. + line="1172">Polls the bus for messages. Will block while waiting for messages to come. You can specify a maximum time to poll with the @timeout parameter. If @timeout is negative, this function will block indefinitely. @@ -7466,7 +7526,7 @@ from there. the message that was received, + line="1214">the message that was received, or %NULL if the poll timed out. @@ -7474,20 +7534,20 @@ from there. a #GstBus + line="1174">a #GstBus a mask of #GstMessageType, representing the set of message types to + line="1175">a mask of #GstMessageType, representing the set of message types to poll for (note special handling of extended message types below) the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll + line="1177">the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll indefinitely. @@ -7496,12 +7556,12 @@ indefinitely. Gets a message from the bus. + line="685">Gets a message from the bus. the #GstMessage that is on the + line="691">the #GstMessage that is on the bus, or %NULL if the bus is empty. @@ -7509,7 +7569,7 @@ indefinitely. a #GstBus to pop + line="687">a #GstBus to pop @@ -7517,7 +7577,7 @@ indefinitely. Gets a message matching @type from the bus. Will discard all messages on + line="661">Gets a message matching @type from the bus. Will discard all messages on the bus that do not match @type and that have been posted before the first message that does match @type. If there is no message matching @type on the bus, all messages will be discarded. It is not possible to use message @@ -7526,7 +7586,7 @@ enums beyond #GST_MESSAGE_EXTENDED in the @events mask. the next #GstMessage matching + line="672">the next #GstMessage matching @type that is on the bus, or %NULL if the bus is empty or there is no message matching @type. @@ -7535,13 +7595,13 @@ enums beyond #GST_MESSAGE_EXTENDED in the @events mask. a #GstBus to pop + line="663">a #GstBus to pop message types to take into account + line="664">message types to take into account @@ -7549,26 +7609,26 @@ enums beyond #GST_MESSAGE_EXTENDED in the @events mask. Posts a message on the given bus. Ownership of the message + line="319">Posts a message on the given bus. Ownership of the message is taken by the bus. %TRUE if the message could be posted, %FALSE if the bus is flushing. + line="327">%TRUE if the message could be posted, %FALSE if the bus is flushing. a #GstBus to post on + line="321">a #GstBus to post on the #GstMessage to post + line="322">the #GstMessage to post @@ -7577,7 +7637,7 @@ is taken by the bus. c:identifier="gst_bus_remove_signal_watch"> Removes a signal watch previously added with gst_bus_add_signal_watch(). + line="1460">Removes a signal watch previously added with gst_bus_add_signal_watch(). @@ -7586,7 +7646,7 @@ is taken by the bus. a #GstBus you previously added a signal watch to + line="1462">a #GstBus you previously added a signal watch to @@ -7596,19 +7656,19 @@ is taken by the bus. version="1.6"> Removes an installed bus watch from @bus. + line="1060">Removes an installed bus watch from @bus. %TRUE on success or %FALSE if @bus has no event source. + line="1066">%TRUE on success or %FALSE if @bus has no event source. a #GstBus to remove the watch from. + line="1062">a #GstBus to remove the watch from. @@ -7616,7 +7676,7 @@ is taken by the bus. If @flushing, flushes out and unrefs any messages queued in the bus. Releases + line="485">If @flushing, flushes out and unrefs any messages queued in the bus. Releases references to the message origin objects. Will flush future messages until gst_bus_set_flushing() sets @flushing to %FALSE. @@ -7627,13 +7687,13 @@ gst_bus_set_flushing() sets @flushing to %FALSE. a #GstBus + line="487">a #GstBus whether or not to flush the bus + line="488">whether or not to flush the bus @@ -7641,7 +7701,7 @@ gst_bus_set_flushing() sets @flushing to %FALSE. Sets the synchronous handler on the bus. The function will be called + line="730">Sets the synchronous handler on the bus. The function will be called every time a new message is posted on the bus. Note that the function will be called in the same thread context as the posting object. This function is usually only called by the creator of the bus. Applications @@ -7658,7 +7718,7 @@ clearing an existing handler with %NULL was not thread-safe. a #GstBus to install the handler on + line="732">a #GstBus to install the handler on destroy="2"> The handler function to install + line="733">The handler function to install allow-none="1"> User data that will be sent to the handler function. + line="734">User data that will be sent to the handler function. called when @user_data becomes unused + line="735">called when @user_data becomes unused @@ -7694,26 +7754,26 @@ clearing an existing handler with %NULL was not thread-safe. c:identifier="gst_bus_sync_signal_handler"> A helper #GstBusSyncHandler that can be used to convert all synchronous + line="1292">A helper #GstBusSyncHandler that can be used to convert all synchronous messages into signals. %GST_BUS_PASS + line="1301">%GST_BUS_PASS a #GstBus + line="1294">a #GstBus the #GstMessage received + line="1295">the #GstMessage received allow-none="1"> user data + line="1296">user data @@ -7730,7 +7790,7 @@ messages into signals. Gets a message from the bus, waiting up to the specified timeout. + line="638">Gets a message from the bus, waiting up to the specified timeout. If @timeout is 0, this function behaves like gst_bus_pop(). If @timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a message was @@ -7739,7 +7799,7 @@ posted on the bus. the #GstMessage that is on the + line="649">the #GstMessage that is on the bus after the specified timeout or %NULL if the bus is empty after the timeout expired. @@ -7748,13 +7808,13 @@ posted on the bus. a #GstBus to pop + line="640">a #GstBus to pop a timeout + line="641">a timeout @@ -7763,7 +7823,7 @@ posted on the bus. c:identifier="gst_bus_timed_pop_filtered"> Gets a message from the bus whose type matches the message type mask @types, + line="521">Gets a message from the bus whose type matches the message type mask @types, waiting up to the specified timeout (and discarding any messages that do not match the mask provided). @@ -7774,7 +7834,7 @@ matching message was posted on the bus. a #GstMessage matching the + line="535">a #GstMessage matching the filter in @types, or %NULL if no matching message was found on the bus until the timeout expired. @@ -7783,19 +7843,19 @@ matching message was posted on the bus. a #GstBus to pop from + line="523">a #GstBus to pop from a timeout in nanoseconds, or %GST_CLOCK_TIME_NONE to wait forever + line="524">a timeout in nanoseconds, or %GST_CLOCK_TIME_NONE to wait forever message types to take into account, %GST_MESSAGE_ANY for any type + line="525">message types to take into account, %GST_MESSAGE_ANY for any type @@ -7808,7 +7868,7 @@ matching message was posted on the bus. default-value="TRUE"> Enables async message delivery support for bus watches, + line="200">Enables async message delivery support for bus watches, gst_bus_pop() and similar API. Without this only the synchronous message handlers are called. @@ -7833,7 +7893,7 @@ in #GstBin. A message has been posted on the bus. This signal is emitted from a + line="233">A message has been posted on the bus. This signal is emitted from a #GSource added to the mainloop. this signal will only be emitted when there is a #GMainLoop running. @@ -7843,7 +7903,7 @@ there is a #GMainLoop running. the message that has been posted asynchronously + line="236">the message that has been posted asynchronously @@ -7851,7 +7911,7 @@ there is a #GMainLoop running. A message has been posted on the bus. This signal is emitted from the + line="216">A message has been posted on the bus. This signal is emitted from the thread that posted the message so one has to be careful with locking. This signal will not be emitted by default, you have to call @@ -7863,7 +7923,7 @@ gst_bus_enable_sync_message_emission() before. the message that has been posted synchronously + line="219">the message that has been posted synchronously @@ -8081,6 +8141,56 @@ message should not be unreffed by the sync handler. line="60">pass message to async queue, continue if message is handled + + Interface for an array of bytes. It is expected to be subclassed to implement +@resize virtual method using language native array implementation, such as +GLib's #GByteArray, C++'s `std::vector<uint8_t>` or Rust's `Vec<u8>`. + +@resize implementation could allocate more than requested to avoid repeated +reallocations. It can return %FALSE, or be set to %NULL, in the case the +array cannot grow. + + + A pointer to an array of bytes. + + + + Number of bytes in @data. + + + + Reallocate @data. + + + + + + + + + + + + + + + + + + + + + @@ -8163,7 +8273,7 @@ evaluates to @def_return. - + @@ -8172,7 +8282,7 @@ evaluates to @def_return. - + @@ -8181,7 +8291,7 @@ evaluates to @def_return. - + introspectable="0"> Output an debugging message in the given category. + line="1009">Output an debugging message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="1011">category to use printf-style message to output + line="1012">printf-style message to output @@ -8332,26 +8442,26 @@ character, a newline character will be added automatically. introspectable="0"> Output an debugging message belonging to the given object in the given category. + line="902">Output an debugging message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="904">category to use the #GObject the message belongs to + line="905">the #GObject the message belongs to printf-style message to output + line="906">printf-style message to output @@ -8360,21 +8470,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an error message in the given category. + line="979">Output an error message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="981">category to use printf-style message to output + line="982">printf-style message to output @@ -8383,26 +8493,26 @@ character, a newline character will be added automatically. introspectable="0"> Output an error message belonging to the given object in the given category. + line="868">Output an error message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="870">category to use the #GObject the message belongs to + line="871">the #GObject the message belongs to printf-style message to output + line="872">printf-style message to output @@ -8411,21 +8521,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an fixme message in the given category. + line="1029">Output an fixme message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="1031">category to use printf-style message to output + line="1032">printf-style message to output @@ -8434,26 +8544,26 @@ character, a newline character will be added automatically. introspectable="0"> Output a fixme message belonging to the given object in the given category. + line="924">Output a fixme message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="926">category to use the #GObject the message belongs to + line="927">the #GObject the message belongs to printf-style message to output + line="928">printf-style message to output @@ -8462,21 +8572,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an informational message in the given category. + line="999">Output an informational message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="1001">category to use printf-style message to output + line="1002">printf-style message to output @@ -8485,27 +8595,27 @@ character, a newline character will be added automatically. introspectable="0"> Output an informational message belonging to the given object in the given + line="890">Output an informational message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="892">category to use the #GObject the message belongs to + line="893">the #GObject the message belongs to printf-style message to output + line="894">printf-style message to output @@ -8514,33 +8624,33 @@ character, a newline character will be added automatically. introspectable="0"> Outputs a debugging message. This is the most general macro for outputting + line="716">Outputs a debugging message. This is the most general macro for outputting debugging messages. You will probably want to use one of the ones described below. There is no need to finish the end of the debug message with a newline character, a newline character will be added automatically. - + category to use + line="718">category to use the severity of the message + line="719">the severity of the message the #GObject the message belongs to or %NULL if none + line="720">the #GObject the message belongs to or %NULL if none A printf-style message to output + line="721">A printf-style message to output @@ -8550,34 +8660,34 @@ character, a newline character will be added automatically. introspectable="0"> Outputs a debugging message. This is the most general macro for outputting + line="769">Outputs a debugging message. This is the most general macro for outputting debugging messages. You will probably want to use one of the ones described below. There is no need to finish the end of the debug message with a newline character, a newline character will be added automatically. - + category to use + line="771">category to use the severity of the message + line="772">the severity of the message the identifier of the object this message + line="773">the identifier of the object this message relates to, or %NULL if none A printf-style message to output + line="775">A printf-style message to output @@ -8586,21 +8696,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an logging message in the given category. + line="1019">Output an logging message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="1021">category to use printf-style message to output + line="1022">printf-style message to output @@ -8609,26 +8719,26 @@ character, a newline character will be added automatically. introspectable="0"> Output an logging message belonging to the given object in the given category. + line="913">Output an logging message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="915">category to use the #GObject the message belongs to + line="916">the #GObject the message belongs to printf-style message to output + line="917">printf-style message to output @@ -8637,31 +8747,31 @@ character, a newline character will be added automatically. introspectable="0"> Output a hexdump of @data in the given category. + line="1049">Output a hexdump of @data in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="1051">category to use message string to log with the data + line="1052">message string to log with the data pointer to the data to output + line="1053">pointer to the data to output length of the data to output + line="1054">length of the data to output @@ -8671,36 +8781,36 @@ character, a newline character will be added automatically. introspectable="0"> Output a hexdump of @data relating to the given @id in the given category. + line="962">Output a hexdump of @data relating to the given @id in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="964">category to use An identifier of the message provider + line="965">An identifier of the message provider message string to log with the data + line="966">message string to log with the data pointer to the data to output + line="967">pointer to the data to output length of the data to output + line="968">length of the data to output @@ -8709,37 +8819,37 @@ character, a newline character will be added automatically. introspectable="0"> Output a hexdump of @data relating to the given object in the given + line="947">Output a hexdump of @data relating to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="949">category to use the #GObject the message belongs to + line="950">the #GObject the message belongs to message string to log with the data + line="951">message string to log with the data pointer to the data to output + line="952">pointer to the data to output length of the data to output + line="953">length of the data to output @@ -8748,21 +8858,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a tracing message in the given category. + line="1039">Output a tracing message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="1041">category to use printf-style message to output + line="1042">printf-style message to output @@ -8771,27 +8881,27 @@ character, a newline character will be added automatically. introspectable="0"> Output a tracing message belonging to the given object in the given + line="935">Output a tracing message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="937">category to use the #GObject the message belongs to + line="938">the #GObject the message belongs to printf-style message to output + line="939">printf-style message to output @@ -8800,21 +8910,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an warning message in the given category. + line="989">Output an warning message in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="991">category to use printf-style message to output + line="992">printf-style message to output @@ -8823,26 +8933,26 @@ character, a newline character will be added automatically. introspectable="0"> Output a warning message belonging to the given object in the given category. + line="879">Output a warning message belonging to the given object in the given category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + category to use + line="881">category to use the #GObject the message belongs to + line="882">the #GObject the message belongs to printf-style message to output + line="883">printf-style message to output @@ -8946,13 +9056,13 @@ The difference is calculated as @e - @s. introspectable="0"> Casts to a clock entry - + line="344">Casts to a clock entry + the entry to cast + line="346">the entry to cast @@ -8962,14 +9072,14 @@ The difference is calculated as @e - @s. deprecated="1"> Gets the owner clock of the entry + line="353">Gets the owner clock of the entry Use gst_clock_id_get_clock() instead. - + the entry to query + line="355">the entry to query @@ -8978,13 +9088,13 @@ The difference is calculated as @e - @s. introspectable="0"> Gets the interval of this periodic entry - + line="377">Gets the interval of this periodic entry + the entry to query + line="379">the entry to query @@ -8993,13 +9103,13 @@ The difference is calculated as @e - @s. introspectable="0"> The status of the entry - + line="384">The status of the entry + the entry to query + line="386">the entry to query @@ -9008,13 +9118,13 @@ The difference is calculated as @e - @s. introspectable="0"> Gets the requested time of this entry - + line="370">Gets the requested time of this entry + the entry to query + line="372">the entry to query @@ -9023,13 +9133,13 @@ The difference is calculated as @e - @s. introspectable="0"> Gets the type of the clock entry - + line="363">Gets the type of the clock entry + the entry to query + line="365">the entry to query @@ -9038,13 +9148,13 @@ The difference is calculated as @e - @s. introspectable="0"> Gets the #GstClockFlags clock flags. - + line="459">Gets the #GstClockFlags clock flags. + the clock to query + line="461">the clock to query @@ -9230,27 +9340,27 @@ gst_value_serialize() and their counterparts. Creates a new #GstCaps that indicates that it is compatible with + line="270">Creates a new #GstCaps that indicates that it is compatible with any media format. the new #GstCaps + line="276">the new #GstCaps Creates a new #GstCaps that is empty. That is, the returned + line="245">Creates a new #GstCaps that is empty. That is, the returned #GstCaps contains no media formats. The #GstCaps is guaranteed to be writable. the new #GstCaps + line="252">the new #GstCaps @@ -9258,20 +9368,20 @@ The #GstCaps is guaranteed to be writable. c:identifier="gst_caps_new_empty_simple"> Creates a new #GstCaps that contains one #GstStructure with name + line="324">Creates a new #GstCaps that contains one #GstStructure with name @media_type. - + the new #GstCaps + line="331">the new #GstCaps the media type of the structure + line="326">the media type of the structure @@ -9281,27 +9391,27 @@ The #GstCaps is guaranteed to be writable. introspectable="0"> Creates a new #GstCaps and adds all the structures listed as + line="504">Creates a new #GstCaps and adds all the structures listed as arguments. The list must be %NULL-terminated. The structures are not copied; the returned #GstCaps owns the structures. - + the new #GstCaps + line="513">the new #GstCaps the first structure to add + line="506">the first structure to add additional structures to add + line="507">additional structures to add @@ -9311,63 +9421,189 @@ are not copied; the returned #GstCaps owns the structures. introspectable="0"> Creates a new #GstCaps and adds all the structures listed as + line="528">Creates a new #GstCaps and adds all the structures listed as arguments. The list must be %NULL-terminated. The structures are not copied; the returned #GstCaps owns the structures. - + the new #GstCaps + line="537">the new #GstCaps the first structure to add + line="530">the first structure to add additional structures to add + line="531">additional structures to add + + Creates a new #GstCaps that contains one #GstStructure with name +@media_type. + + + the new #GstCaps + + + + + the media type of the structure + + + + + + Creates a new #GstCaps that contains one #GstStructure. The +structure is defined by the arguments, which have the same format +as gst_structure_new(). + + + the new #GstCaps + + + + + the media type of the structure + + + + first field to set + + + + additional arguments + + + + Creates a new #GstCaps that contains one #GstStructure. The + line="431">Creates a new #GstCaps that contains one #GstStructure. The structure is defined by the arguments, which have the same format as gst_structure_new(). - + + + the new #GstCaps + + + + + the media type of the structure + + + + first field to set + + + + additional arguments + + + + + + Creates a new #GstCaps that contains one #GstStructure with name +@media_type. + +@media_type needs to be valid for the remaining lifetime of the process, e.g. +has to be a static string. + the new #GstCaps + line="367">the new #GstCaps the media type of the structure + line="359">the media type of the structure + + + + + + Creates a new #GstCaps that contains one #GstStructure. The +structure is defined by the arguments, which have the same format +as gst_structure_new(). + +@media_type, @fieldname and all other fieldnames need to be valid for the +remaining lifetime of the process, e.g. have to be static strings. + + + the new #GstCaps + + + + + the media type of the structure first field to set + line="467">first field to set additional arguments + line="468">additional arguments @@ -9375,10 +9611,10 @@ as gst_structure_new(). Appends the structures contained in @caps2 to @caps1. The structures in + line="709">Appends the structures contained in @caps2 to @caps1. The structures in @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is freed. If either caps is ANY, the resulting caps will be ANY. - + @@ -9386,13 +9622,13 @@ freed. If either caps is ANY, the resulting caps will be ANY. the #GstCaps that will be appended to + line="711">the #GstCaps that will be appended to the #GstCaps to append + line="712">the #GstCaps to append @@ -9400,9 +9636,9 @@ freed. If either caps is ANY, the resulting caps will be ANY. Appends @structure to @caps. The structure is not copied; @caps + line="798">Appends @structure to @caps. The structure is not copied; @caps becomes the owner of @structure. - + @@ -9410,13 +9646,13 @@ becomes the owner of @structure. the #GstCaps that will be appended to + line="800">the #GstCaps that will be appended to the #GstStructure to append + line="801">the #GstStructure to append @@ -9426,9 +9662,9 @@ becomes the owner of @structure. version="1.2"> Appends @structure with @features to @caps. The structure is not copied; @caps + line="824">Appends @structure with @features to @caps. The structure is not copied; @caps becomes the owner of @structure. - + @@ -9436,13 +9672,13 @@ becomes the owner of @structure. the #GstCaps that will be appended to + line="826">the #GstCaps that will be appended to the #GstStructure to append + line="827">the #GstStructure to append allow-none="1"> the #GstCapsFeatures to append + line="828">the #GstCapsFeatures to append @@ -9459,26 +9695,26 @@ becomes the owner of @structure. Tries intersecting @caps1 and @caps2 and reports whether the result would not + line="1879">Tries intersecting @caps1 and @caps2 and reports whether the result would not be empty - + %TRUE if intersection would be not empty + line="1887">%TRUE if intersection would be not empty a #GstCaps to intersect + line="1881">a #GstCaps to intersect a #GstCaps to intersect + line="1882">a #GstCaps to intersect @@ -9486,7 +9722,7 @@ be empty Creates a new #GstCaps as a copy of the old @caps. The new caps will have a + line="3049">Creates a new #GstCaps as a copy of the old @caps. The new caps will have a refcount of 1, owned by the caller. The structures are copied as well. Note that this function is the semantic equivalent of a gst_caps_ref() @@ -9496,14 +9732,14 @@ reference to the data, you should use gst_caps_ref(). the new #GstCaps + line="3060">the new #GstCaps a #GstCaps. + line="3051">a #GstCaps. @@ -9511,26 +9747,26 @@ reference to the data, you should use gst_caps_ref(). Creates a new #GstCaps and appends a copy of the nth structure + line="1170">Creates a new #GstCaps and appends a copy of the nth structure contained in @caps. - + the new #GstCaps + line="1178">the new #GstCaps the #GstCaps to copy + line="1172">the #GstCaps to copy the nth structure to copy + line="1173">the nth structure to copy @@ -9540,13 +9776,12 @@ contained in @caps. version="1.6"> Calls the provided function once for each structure and caps feature in the + line="2991">Calls the provided function once for each structure and caps feature in the #GstCaps. In contrast to gst_caps_foreach(), the function may modify the -structure and features. In contrast to gst_caps_filter_and_map_in_place(), -the structure and features are removed from the caps if %FALSE is returned -from the function. -The caps must be mutable. - +structure and features. In contrast to gst_caps_map_in_place(), the structure +and features are removed from the caps if %FALSE is returned from the +function. The caps must be mutable. + @@ -9554,7 +9789,7 @@ The caps must be mutable. a #GstCaps + line="2993">a #GstCaps closure="1"> a function to call for each field + line="2994">a function to call for each field allow-none="1"> private data + line="2995">private data @@ -9580,7 +9815,7 @@ The caps must be mutable. Modifies the given @caps into a representation with only fixed + line="2588">Modifies the given @caps into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated with gst_structure_fixate(). @@ -9593,18 +9828,18 @@ structure. If @caps are empty caps then the returned caps will be the empty too and contain no structure at all. Calling this function with ANY caps is not allowed. - + the fixated caps + line="2606">the fixated caps a #GstCaps to fixate + line="2590">a #GstCaps to fixate @@ -9612,14 +9847,14 @@ Calling this function with ANY caps is not allowed. Calls the provided function once for each structure and caps feature in the + line="2902">Calls the provided function once for each structure and caps feature in the #GstCaps. The function must not modify the fields. Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place(). - + %TRUE if the supplied function returns %TRUE for each call, + line="2912">%TRUE if the supplied function returns %TRUE for each call, %FALSE otherwise. @@ -9627,7 +9862,7 @@ Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place(). a #GstCaps + line="2904">a #GstCaps closure="1"> a function to call for each field + line="2905">a function to call for each field allow-none="1"> private data + line="2906">private data @@ -9655,7 +9890,7 @@ Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place(). version="1.2"> Finds the features in @caps at @index, and returns it. + line="1043">Finds the features in @caps at @index, and returns it. WARNING: This function takes a `const GstCaps *`, but returns a non-const `GstCapsFeatures *`. This is for programming convenience -- @@ -9665,11 +9900,11 @@ are writable, either because you have just copied them or made them writable with gst_caps_make_writable(), you may modify the features returned in the usual way, e.g. with functions like gst_caps_features_add(). - + a pointer to the #GstCapsFeatures + line="1059">a pointer to the #GstCapsFeatures corresponding to @index @@ -9677,13 +9912,13 @@ gst_caps_features_add(). a #GstCaps + line="1045">a #GstCaps the index of the structure + line="1046">the index of the structure @@ -9691,19 +9926,19 @@ gst_caps_features_add(). Gets the number of structures contained in @caps. - + line="999">Gets the number of structures contained in @caps. + the number of structures that @caps contains + line="1005">the number of structures that @caps contains a #GstCaps + line="1001">a #GstCaps @@ -9711,7 +9946,7 @@ gst_caps_features_add(). Finds the structure in @caps at @index, and returns it. + line="1015">Finds the structure in @caps at @index, and returns it. WARNING: This function takes a `const GstCaps *`, but returns a non-const `GstStructure *`. This is for programming convenience -- @@ -9721,11 +9956,11 @@ are writable, either because you have just copied them or made them writable with gst_caps_make_writable(), you may modify the structure returned in the usual way, e.g. with functions like gst_structure_set(). - + a pointer to the #GstStructure corresponding + line="1031">a pointer to the #GstStructure corresponding to @index @@ -9733,40 +9968,139 @@ gst_structure_set(). a #GstCaps + line="1017">a #GstCaps the index of the structure + line="1018">the index of the structure + + Sets fields in a #GstCaps. The arguments must be passed in the same +manner as gst_structure_id_str_set(), and be %NULL-terminated. + + + + + + + the #GstCaps to set + + + + first field to set + + + + additional parameters + + + + + + Sets fields in a #GstCaps. The arguments must be passed in the same +manner as gst_structure_id_str_set(), and be %NULL-terminated. + + + + + + + the #GstCaps to set + + + + first field to set + + + + additional parameters + + + + + + Sets the given @field on all structures of @caps to the given @value. +This is a convenience function for calling gst_structure_set_value() on +all structures of @caps. + + + + + + + a writable caps + + + + name of the field to set + + + + value to set the field to + + + + Creates a new #GstCaps that contains all the formats that are common + line="2139">Creates a new #GstCaps that contains all the formats that are common to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode. - + the new #GstCaps + line="2147">the new #GstCaps a #GstCaps to intersect + line="2141">a #GstCaps to intersect a #GstCaps to intersect + line="2142">a #GstCaps to intersect @@ -9774,33 +10108,33 @@ to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode. Creates a new #GstCaps that contains all the formats that are common + line="2093">Creates a new #GstCaps that contains all the formats that are common to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode used. - + the new #GstCaps + line="2103">the new #GstCaps a #GstCaps to intersect + line="2095">a #GstCaps to intersect a #GstCaps to intersect + line="2096">a #GstCaps to intersect The intersection algorithm/mode to use + line="2097">The intersection algorithm/mode to use @@ -9809,27 +10143,27 @@ used. c:identifier="gst_caps_is_always_compatible"> A given #GstCaps structure is always compatible with another if + line="1643">A given #GstCaps structure is always compatible with another if every media format that is in the first is also contained in the second. That is, @caps1 is a subset of @caps2. - + %TRUE if @caps1 is a subset of @caps2. + line="1652">%TRUE if @caps1 is a subset of @caps2. the #GstCaps to test + line="1645">the #GstCaps to test the #GstCaps to test + line="1646">the #GstCaps to test @@ -9837,19 +10171,19 @@ second. That is, @caps1 is a subset of @caps2. Determines if @caps represents any media format. - + line="1534">Determines if @caps represents any media format. + %TRUE if @caps represents any format. + line="1540">%TRUE if @caps represents any format. the #GstCaps to test + line="1536">the #GstCaps to test @@ -9857,19 +10191,19 @@ second. That is, @caps1 is a subset of @caps2. Determines if @caps represents no media formats. - + line="1550">Determines if @caps represents no media formats. + %TRUE if @caps represents no formats. + line="1556">%TRUE if @caps represents no formats. the #GstCaps to test + line="1552">the #GstCaps to test @@ -9877,25 +10211,25 @@ second. That is, @caps1 is a subset of @caps2. Checks if the given caps represent the same set of caps. - + line="1803">Checks if the given caps represent the same set of caps. + %TRUE if both caps are equal. + line="1810">%TRUE if both caps are equal. a #GstCaps + line="1805">a #GstCaps another #GstCaps + line="1806">another #GstCaps @@ -9903,26 +10237,26 @@ second. That is, @caps1 is a subset of @caps2. Tests if two #GstCaps are equal. This function only works on fixed + line="1611">Tests if two #GstCaps are equal. This function only works on fixed #GstCaps. - + %TRUE if the arguments represent the same format + line="1619">%TRUE if the arguments represent the same format the #GstCaps to test + line="1613">the #GstCaps to test the #GstCaps to test + line="1614">the #GstCaps to test @@ -9930,21 +10264,21 @@ second. That is, @caps1 is a subset of @caps2. Fixed #GstCaps describe exactly one format, that is, they have exactly + line="1576">Fixed #GstCaps describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type. Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. - + %TRUE if @caps is fixed + line="1584">%TRUE if @caps is fixed the #GstCaps to test + line="1578">the #GstCaps to test @@ -9953,25 +10287,25 @@ Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. c:identifier="gst_caps_is_strictly_equal"> Checks if the given caps are exactly the same set of caps. - + line="1827">Checks if the given caps are exactly the same set of caps. + %TRUE if both caps are strictly equal. + line="1834">%TRUE if both caps are strictly equal. a #GstCaps + line="1829">a #GstCaps another #GstCaps + line="1830">another #GstCaps @@ -9979,25 +10313,25 @@ Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. Checks if all caps represented by @subset are also represented by @superset. - + line="1663">Checks if all caps represented by @subset are also represented by @superset. + %TRUE if @subset is a subset of @superset + line="1670">%TRUE if @subset is a subset of @superset a #GstCaps + line="1665">a #GstCaps a potentially greater #GstCaps + line="1666">a potentially greater #GstCaps @@ -10006,26 +10340,26 @@ Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. c:identifier="gst_caps_is_subset_structure"> Checks if @structure is a subset of @caps. See gst_caps_is_subset() + line="1719">Checks if @structure is a subset of @caps. See gst_caps_is_subset() for more information. - + %TRUE if @structure is a subset of @caps + line="1727">%TRUE if @structure is a subset of @caps a #GstCaps + line="1721">a #GstCaps a potential #GstStructure subset of @caps + line="1722">a potential #GstStructure subset of @caps @@ -10035,26 +10369,26 @@ for more information. version="1.2"> Checks if @structure is a subset of @caps. See gst_caps_is_subset() + line="1755">Checks if @structure is a subset of @caps. See gst_caps_is_subset() for more information. - + %TRUE if @structure is a subset of @caps + line="1764">%TRUE if @structure is a subset of @caps a #GstCaps + line="1757">a #GstCaps a potential #GstStructure subset of @caps + line="1758">a potential #GstStructure subset of @caps allow-none="1"> a #GstCapsFeatures for @structure + line="1759">a #GstCapsFeatures for @structure @@ -10073,14 +10407,14 @@ for more information. version="1.6"> Calls the provided function once for each structure and caps feature in the + line="2943">Calls the provided function once for each structure and caps feature in the #GstCaps. In contrast to gst_caps_foreach(), the function may modify but not delete the structures and features. The caps must be mutable. - + %TRUE if the supplied function returns %TRUE for each call, + line="2953">%TRUE if the supplied function returns %TRUE for each call, %FALSE otherwise. @@ -10088,7 +10422,7 @@ delete the structures and features. The caps must be mutable. a #GstCaps + line="2945">a #GstCaps closure="1"> a function to call for each field + line="2946">a function to call for each field allow-none="1"> private data + line="2947">private data @@ -10114,28 +10448,28 @@ delete the structures and features. The caps must be mutable. Appends the structures contained in @caps2 to @caps1 if they are not yet + line="744">Appends the structures contained in @caps2 to @caps1 if they are not yet expressed by @caps1. The structures in @caps2 are not copied -- they are transferred to a writable copy of @caps1, and then @caps2 is freed. If either caps is ANY, the resulting caps will be ANY. - + the merged caps. + line="754">the merged caps. the #GstCaps that will take the new entries + line="746">the #GstCaps that will take the new entries the #GstCaps to merge in + line="747">the #GstCaps to merge in @@ -10143,25 +10477,25 @@ If either caps is ANY, the resulting caps will be ANY. Appends @structure to @caps if it is not already expressed by @caps. - + line="877">Appends @structure to @caps if it is not already expressed by @caps. + the merged caps. + line="884">the merged caps. the #GstCaps to merge into + line="879">the #GstCaps to merge into the #GstStructure to merge + line="880">the #GstStructure to merge @@ -10171,25 +10505,25 @@ If either caps is ANY, the resulting caps will be ANY. version="1.2"> Appends @structure with @features to @caps if its not already expressed by @caps. - + line="930">Appends @structure with @features to @caps if its not already expressed by @caps. + the merged caps. + line="938">the merged caps. the #GstCaps to merge into + line="932">the #GstCaps to merge into the #GstStructure to merge + line="933">the #GstStructure to merge allow-none="1"> the #GstCapsFeatures to merge + line="934">the #GstCapsFeatures to merge @@ -10206,25 +10540,25 @@ If either caps is ANY, the resulting caps will be ANY. Returns a #GstCaps that represents the same set of formats as + line="2353">Returns a #GstCaps that represents the same set of formats as @caps, but contains no lists. Each list is expanded into separate #GstStructure. This function takes ownership of @caps and will call gst_caps_make_writable() on it so you must not use @caps afterwards unless you keep an additional reference to it with gst_caps_ref(). - + the normalized #GstCaps + line="2365">the normalized #GstCaps a #GstCaps to normalize + line="2355">a #GstCaps to normalize @@ -10232,9 +10566,9 @@ reference to it with gst_caps_ref(). Removes the structure with the given index from the list of structures + line="856">Removes the structure with the given index from the list of structures contained in @caps. - + @@ -10242,13 +10576,13 @@ contained in @caps. the #GstCaps to remove from + line="858">the #GstCaps to remove from Index of the structure to remove + line="859">Index of the structure to remove @@ -10258,7 +10592,7 @@ contained in @caps. version="1.20"> Converts @caps to a string representation. This string representation can be + line="2739">Converts @caps to a string representation. This string representation can be converted back to a #GstCaps by gst_caps_from_string(). This prints the caps in human readable form. @@ -10267,24 +10601,24 @@ This version of the caps serialization function introduces support for nested structures and caps but the resulting strings won't be parsable with GStreamer prior to 1.20 unless #GST_SERIALIZE_FLAG_BACKWARD_COMPAT is passed as @flag. - + a newly allocated string representing @caps. + line="2754">a newly allocated string representing @caps. a #GstCaps + line="2741">a #GstCaps a #GstSerializeFlags + line="2742">a #GstSerializeFlags @@ -10294,8 +10628,8 @@ as @flag. version="1.2"> Sets the @features for the structure at @index. - + line="1097">Sets the @features for the structure at @index. + @@ -10303,13 +10637,13 @@ as @flag. a #GstCaps + line="1099">a #GstCaps the index of the structure + line="1100">the index of the structure allow-none="1"> the #GstCapsFeatures to set + line="1101">the #GstCapsFeatures to set @@ -10328,8 +10662,8 @@ as @flag. version="1.16"> Sets the @features for all the structures of @caps. - + line="1130">Sets the @features for all the structures of @caps. + @@ -10337,7 +10671,7 @@ as @flag. a #GstCaps + line="1132">a #GstCaps allow-none="1"> the #GstCapsFeatures to set + line="1133">the #GstCapsFeatures to set @@ -10356,9 +10690,9 @@ as @flag. introspectable="0"> Sets fields in a #GstCaps. The arguments must be passed in the same + line="1483">Sets fields in a #GstCaps. The arguments must be passed in the same manner as gst_structure_set(), and be %NULL-terminated. - + @@ -10366,31 +10700,103 @@ manner as gst_structure_set(), and be %NULL-terminated. the #GstCaps to set + line="1485">the #GstCaps to set first field to set + line="1486">first field to set additional parameters + line="1487">additional parameters + + Sets fields in a #GstCaps. The arguments must be passed in the same +manner as gst_structure_set(), and be %NULL-terminated. + +@field and all other field names need to be valid for the remaining lifetime +of the process, e.g. have to be static strings. + + + + + + + the #GstCaps to set + + + + first field to set + + + + additional parameters + + + + + + Sets fields in a #GstCaps. The arguments must be passed in the same +manner as gst_structure_set(), and be %NULL-terminated. + +@field and all other field names need to be valid for the remaining lifetime +of the process, e.g. have to be static strings. + + + + + + + the #GstCaps to set + + + + first field to set + + + + additional parameters + + + + Sets fields in a #GstCaps. The arguments must be passed in the same + line="1377">Sets fields in a #GstCaps. The arguments must be passed in the same manner as gst_structure_set(), and be %NULL-terminated. - + @@ -10398,19 +10804,19 @@ manner as gst_structure_set(), and be %NULL-terminated. the #GstCaps to set + line="1379">the #GstCaps to set first field to set + line="1380">first field to set additional parameters + line="1381">additional parameters @@ -10418,10 +10824,46 @@ manner as gst_structure_set(), and be %NULL-terminated. Sets the given @field on all structures of @caps to the given @value. + line="1276">Sets the given @field on all structures of @caps to the given @value. This is a convenience function for calling gst_structure_set_value() on all structures of @caps. - + + + + + + + a writable caps + + + + name of the field to set + + + + value to set the field to + + + + + + Sets the given @field on all structures of @caps to the given @value. +This is a convenience function for calling gst_structure_set_value() on +all structures of @caps. + +@field needs to be valid for the remaining lifetime of the process, e.g. +has to be a static string. + @@ -10429,19 +10871,19 @@ all structures of @caps. a writable caps + line="1305">a writable caps name of the field to set + line="1306">name of the field to set value to set the field to + line="1307">value to set the field to @@ -10449,7 +10891,7 @@ all structures of @caps. Converts the given @caps into a representation that represents the + line="2511">Converts the given @caps into a representation that represents the same set of formats, but in a simpler form. Component structures that are identical are merged. Component structures that have values that can be merged are also merged. @@ -10459,18 +10901,18 @@ on it if necessary, so you must not use @caps afterwards unless you keep an additional reference to it with gst_caps_ref(). This method does not preserve the original order of @caps. - + The simplified caps. + line="2526">The simplified caps. a #GstCaps to simplify + line="2513">a #GstCaps to simplify @@ -10478,13 +10920,13 @@ This method does not preserve the original order of @caps. Retrieves the structure with the given index from the list of structures + line="686">Retrieves the structure with the given index from the list of structures contained in @caps. The caller becomes the owner of the returned structure. - + a pointer to the #GstStructure + line="694">a pointer to the #GstStructure corresponding to @index. @@ -10492,13 +10934,13 @@ contained in @caps. The caller becomes the owner of the returned structure. the #GstCaps to retrieve from + line="688">the #GstCaps to retrieve from Index of the structure to retrieve + line="689">Index of the structure to retrieve @@ -10506,27 +10948,27 @@ contained in @caps. The caller becomes the owner of the returned structure. Subtracts the @subtrahend from the @minuend. + line="2218">Subtracts the @subtrahend from the @minuend. > This function does not work reliably if optional properties for caps > are included on one caps and omitted on the other. - + the resulting caps + line="2227">the resulting caps #GstCaps to subtract from + line="2220">#GstCaps to subtract from #GstCaps to subtract + line="2221">#GstCaps to subtract @@ -10534,7 +10976,7 @@ contained in @caps. The caller becomes the owner of the returned structure. Converts @caps to a string representation. This string representation + line="2713">Converts @caps to a string representation. This string representation can be converted back to a #GstCaps by gst_caps_from_string(). For debugging purposes its easier to do something like this: @@ -10547,18 +10989,18 @@ This prints the caps in human readable form. The implementation of serialization up to 1.20 would lead to unexpected results when there were nested #GstCaps / #GstStructure deeper than one level. - + a newly allocated string representing @caps. + line="2731">a newly allocated string representing @caps. a #GstCaps + line="2715">a #GstCaps @@ -10566,7 +11008,7 @@ when there were nested #GstCaps / #GstStructure deeper than one level. Discards all but the first structure from @caps. Useful when + line="1205">Discards all but the first structure from @caps. Useful when fixating. This function takes ownership of @caps and will call gst_caps_make_writable() @@ -10576,18 +11018,18 @@ additional reference to it with gst_caps_ref(). Note that it is not guaranteed that the returned caps have exactly one structure. If @caps is any or empty caps then the returned caps will be the same and contain no structure at all. - + truncated caps + line="1220">truncated caps the #GstCaps to truncate + line="1207">the #GstCaps to truncate @@ -10595,22 +11037,22 @@ the same and contain no structure at all. Converts @caps from a string representation. + line="2862">Converts @caps from a string representation. The implementation of serialization up to 1.20 would lead to unexpected results when there were nested #GstCaps / #GstStructure deeper than one level. - + a newly allocated #GstCaps + line="2871">a newly allocated #GstCaps a string to convert to #GstCaps + line="2864">a string to convert to #GstCaps @@ -10643,33 +11085,33 @@ Examples for caps features would be the requirement of a specific #GstMemory types or the requirement of having a specific #GstMeta on the buffer. Features are given as a string of the format `memory:GstMemoryTypeName` or `meta:GstMetaAPIName`. - + Creates a new #GstCapsFeatures with the given features. + line="268">Creates a new #GstCapsFeatures with the given features. The last argument must be %NULL. - + a new, empty #GstCapsFeatures + line="276">a new, empty #GstCapsFeatures name of first feature to set + line="270">name of first feature to set additional features + line="271">additional features @@ -10679,14 +11121,14 @@ The last argument must be %NULL. version="1.2"> Creates a new, ANY #GstCapsFeatures. This will be equal + line="201">Creates a new, ANY #GstCapsFeatures. This will be equal to any other #GstCapsFeatures but caps with these are unfixed. - + a new, ANY #GstCapsFeatures + line="208">a new, ANY #GstCapsFeatures @@ -10695,70 +11137,135 @@ unfixed. version="1.2"> Creates a new, empty #GstCapsFeatures. - + line="175">Creates a new, empty #GstCapsFeatures. + a new, empty #GstCapsFeatures + line="180">a new, empty #GstCapsFeatures + introspectable="0" + deprecated="1" + deprecated-version="1.26"> Creates a new #GstCapsFeatures with the given features. + line="385">Creates a new #GstCapsFeatures with the given features. The last argument must be 0. - + Use gst_caps_features_new_id_str(). + a new, empty #GstCapsFeatures + line="393">a new, empty #GstCapsFeatures name of first feature to set + line="387">name of first feature to set additional features + line="388">additional features + + Creates a new #GstCapsFeatures with the given features. +The last argument must be 0. + + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + additional features + + + + + + Creates a new #GstCapsFeatures with the given features. + + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + variable argument list + + + + + introspectable="0" + deprecated="1" + deprecated-version="1.26"> Creates a new #GstCapsFeatures with the given features. - + line="416">Creates a new #GstCapsFeatures with the given features. + Use gst_caps_features_new_id_str_valist(). + a new, empty #GstCapsFeatures + line="423">a new, empty #GstCapsFeatures name of first feature to set + line="418">name of first feature to set variable argument list + line="419">variable argument list @@ -10768,48 +11275,138 @@ The last argument must be 0. version="1.20"> Creates a new #GstCapsFeatures with a single feature. - + line="223">Creates a new #GstCapsFeatures with a single feature. + + + a new #GstCapsFeatures + + + + + The feature + + + + + + Creates a new #GstCapsFeatures with a single feature. + +@feature needs to be valid for the remaining lifetime of the process, e.g. has +to be a static string. + a new #GstCapsFeatures + line="253">a new #GstCapsFeatures The feature + line="246">The feature + + Creates a new #GstCapsFeatures with the given features. +The last argument must be %NULL. + +@feature1 and all other features need to be valid for the remaining lifetime +of the process, e.g. have to be a static string. + + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + additional features + + + + + + Creates a new #GstCapsFeatures with the given features. + +@feature1 and all other features need to be valid for the remaining lifetime +of the process, e.g. have to be a static string. + + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + variable argument list + + + + Creates a new #GstCapsFeatures with the given features. - + line="295">Creates a new #GstCapsFeatures with the given features. + a new, empty #GstCapsFeatures + line="302">a new, empty #GstCapsFeatures name of first feature to set + line="297">name of first feature to set variable argument list + line="298">variable argument list @@ -10817,8 +11414,8 @@ The last argument must be 0. Adds @feature to @features. - + line="1017">Adds @feature to @features. + @@ -10826,24 +11423,27 @@ The last argument must be 0. a #GstCapsFeatures. + line="1019">a #GstCapsFeatures. a feature. + line="1020">a feature. + version="1.2" + deprecated="1" + deprecated-version="1.26"> Adds @feature to @features. - + line="1069">Adds @feature to @features. + Use gst_caps_features_add_id_str(). + @@ -10851,89 +11451,173 @@ The last argument must be 0. a #GstCapsFeatures. + line="1071">a #GstCapsFeatures. a feature. + line="1072">a feature. + + Adds @feature to @features. + + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + + + Adds @feature to @features. + +@feature needs to be valid for the remaining lifetime of the process, e.g. has +to be a static string. + + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + Checks if @features contains @feature. - + line="835">Checks if @features contains @feature. + %TRUE if @features contains @feature. + line="842">%TRUE if @features contains @feature. a #GstCapsFeatures. + line="837">a #GstCapsFeatures. a feature + line="838">a feature + version="1.2" + deprecated="1" + deprecated-version="1.26"> Checks if @features contains @feature. - + line="864">Checks if @features contains @feature. + Use gst_caps_features_contains_id_str(). + %TRUE if @features contains @feature. + line="871">%TRUE if @features contains @feature. a #GstCapsFeatures. + line="866">a #GstCapsFeatures. a feature + line="867">a feature + + Checks if @features contains @feature. + + + %TRUE if @features contains @feature. + + + + + a #GstCapsFeatures. + + + + a feature + + + + Duplicates a #GstCapsFeatures and all its values. - + line="542">Duplicates a #GstCapsFeatures and all its values. + a new #GstCapsFeatures. + line="548">a new #GstCapsFeatures. a #GstCapsFeatures to duplicate + line="544">a #GstCapsFeatures to duplicate @@ -10941,9 +11625,9 @@ The last argument must be 0. Frees a #GstCapsFeatures and all its values. The caps features must not + line="570">Frees a #GstCapsFeatures and all its values. The caps features must not have a parent when this function is called. - + @@ -10951,7 +11635,7 @@ have a parent when this function is called. the #GstCapsFeatures to free + line="572">the #GstCapsFeatures to free @@ -10961,53 +11645,84 @@ have a parent when this function is called. version="1.2"> Returns the @i-th feature of @features. - + line="756">Returns the @i-th feature of @features. + The @i-th feature of @features. + line="763">The @i-th feature of @features. a #GstCapsFeatures. + line="758">a #GstCapsFeatures. index of the feature + line="759">index of the feature + version="1.2" + deprecated="1" + deprecated-version="1.26"> Returns the @i-th feature of @features. - + line="783">Returns the @i-th feature of @features. + Use gst_caps_features_get_nth_id_str(). + The @i-th feature of @features. + line="790">The @i-th feature of @features. a #GstCapsFeatures. + line="785">a #GstCapsFeatures. index of the feature + line="786">index of the feature + + + + + + Returns the @i-th feature of @features. + + + The @i-th feature of @features. + + + + + a #GstCapsFeatures. + + + + index of the feature @@ -11017,19 +11732,19 @@ have a parent when this function is called. version="1.2"> Returns the number of features in @features. - + line="738">Returns the number of features in @features. + The number of features in @features. + line="744">The number of features in @features. a #GstCapsFeatures. + line="740">a #GstCapsFeatures. @@ -11039,19 +11754,19 @@ have a parent when this function is called. version="1.2"> Checks if @features is %GST_CAPS_FEATURES_ANY. - + line="975">Checks if @features is %GST_CAPS_FEATURES_ANY. + %TRUE if @features is %GST_CAPS_FEATURES_ANY. + line="981">%TRUE if @features is %GST_CAPS_FEATURES_ANY. a #GstCapsFeatures. + line="977">a #GstCapsFeatures. @@ -11061,25 +11776,25 @@ have a parent when this function is called. version="1.2"> Checks if @features1 and @features2 are equal. - + line="928">Checks if @features1 and @features2 are equal. + %TRUE if @features1 and @features2 are equal. + line="935">%TRUE if @features1 and @features2 are equal. a #GstCapsFeatures. + line="930">a #GstCapsFeatures. a #GstCapsFeatures. + line="931">a #GstCapsFeatures. @@ -11089,8 +11804,8 @@ have a parent when this function is called. version="1.2"> Removes @feature from @features. - + line="1120">Removes @feature from @features. + @@ -11098,24 +11813,27 @@ have a parent when this function is called. a #GstCapsFeatures. + line="1122">a #GstCapsFeatures. a feature. + line="1123">a feature. + version="1.2" + deprecated="1" + deprecated-version="1.26"> Removes @feature from @features. - + line="1144">Removes @feature from @features. + Use gst_caps_features_remove_id_str(). + @@ -11123,44 +11841,69 @@ have a parent when this function is called. a #GstCapsFeatures. + line="1146">a #GstCapsFeatures. a feature. + line="1147">a feature. + + Removes @feature from @features. + + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + Sets the parent_refcount field of #GstCapsFeatures. This field is used to + line="503">Sets the parent_refcount field of #GstCapsFeatures. This field is used to determine whether a caps features is mutable or not. This function should only be called by code implementing parent objects of #GstCapsFeatures, as described in [the MT refcounting design document](additional/design/MT-refcounting.md). - + %TRUE if the parent refcount could be set. + line="513">%TRUE if the parent refcount could be set. a #GstCapsFeatures + line="505">a #GstCapsFeatures a pointer to the parent's refcount + line="506">a pointer to the parent's refcount @@ -11170,7 +11913,7 @@ called by code implementing parent objects of #GstCapsFeatures, as described in version="1.2"> Converts @features to a human-readable string representation. + line="594">Converts @features to a human-readable string representation. For debugging purposes its easier to do something like this: @@ -11179,18 +11922,18 @@ GST_LOG ("features is %" GST_PTR_FORMAT, features); ``` This prints the features in human readable form. - + a pointer to string allocated by g_malloc(). + line="608">a pointer to string allocated by g_malloc(). a #GstCapsFeatures + line="596">a #GstCapsFeatures @@ -11200,12 +11943,12 @@ This prints the features in human readable form. version="1.2"> Creates a #GstCapsFeatures from a string representation. - + line="649">Creates a #GstCapsFeatures from a string representation. + a new #GstCapsFeatures or + line="655">a new #GstCapsFeatures or %NULL when the string could not be parsed. @@ -11213,7 +11956,7 @@ This prints the features in human readable form. a string representation of a #GstCapsFeatures. + line="651">a string representation of a #GstCapsFeatures. @@ -12025,6 +12768,9 @@ usage. For plain #GObject @target is the same as @object. + Fetch a child object by name @@ -12051,6 +12797,9 @@ usage. For plain #GObject @target is the same as @object. + Fetch a child object by index @@ -12077,6 +12826,9 @@ usage. For plain #GObject @target is the same as @object. + Get the number of children in @parent @@ -12096,6 +12848,9 @@ usage. For plain #GObject @target is the same as @object. + Called when @child is added to @parent @@ -12124,6 +12879,9 @@ usage. For plain #GObject @target is the same as @object. + Called when @child is removed from @parent @@ -12239,14 +12997,14 @@ The #GstClock:timeout property defines the interval to sample the master clock and run the calibration functions. #GstClock:window-size defines the number of samples to use when calibrating and #GstClock:window-threshold defines the minimum number of samples before the calibration is performed. - + Compares the two #GstClockID instances. This function can be used as a GCompareFunc when sorting ids. - + This function returns the underlying clock. - + Gets the time of the clock ID - + Increases the refcount of given @id. - + filename="gst/gstclock.c" line="388">Unrefs given @id. When the refcount reaches 0 the #GstClockID will be freed. - + @@ -12362,7 +13120,7 @@ as a GCompareFunc when sorting ids. be an outstanding async notification or a pending sync notification. After this call, @id cannot be used anymore to receive sync or async notifications, you need to create a new #GstClockID. - + @@ -12384,7 +13142,7 @@ async notifications, you need to create a new #GstClockID. @clock can be NULL, in which case the return value indicates whether the underlying clock has been freed. If this is the case, the @id is no longer usable and should be freed. - + - + - + Change the resolution of the clock. Not all values might + line="495">Change the resolution of the clock. Not all values might be acceptable. - + the new resolution + line="504">the new resolution the #GstClock + line="497">the #GstClock the previous resolution + line="498">the previous resolution the new resolution + line="499">the new resolution @@ -12545,7 +13303,7 @@ be acceptable. filename="gst/gstclock.c" line="1056">Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate. - + filename="gst/gstclock.c" line="859">Gets the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by gst_clock_get_time(). - + Unblock a blocking or async wait operation. - + line="562">Unblock a blocking or async wait operation. + @@ -12595,13 +13353,13 @@ of the values returned by gst_clock_get_time(). the #GstClock + line="564">the #GstClock the entry to unschedule + line="565">the entry to unschedule @@ -12609,13 +13367,13 @@ of the values returned by gst_clock_get_time(). Perform a blocking wait on the given #GstClockEntry and return + line="534">Perform a blocking wait on the given #GstClockEntry and return the jitter. - + the result of the blocking wait. #GST_CLOCK_EARLY will be returned + line="543">the result of the blocking wait. #GST_CLOCK_EARLY will be returned if the current clock time is past the time of @id, #GST_CLOCK_OK if @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was unscheduled with gst_clock_id_unschedule(). @@ -12625,13 +13383,13 @@ unscheduled with gst_clock_id_unschedule(). the #GstClock + line="536">the #GstClock the entry to wait on + line="537">the entry to wait on allow-none="1"> a pointer that will contain the jitter + line="538">a pointer that will contain the jitter @@ -12650,25 +13408,25 @@ unscheduled with gst_clock_id_unschedule(). Perform an asynchronous wait on the given #GstClockEntry. - + line="551">Perform an asynchronous wait on the given #GstClockEntry. + the result of the non blocking wait. + line="558">the result of the non blocking wait. the #GstClock + line="553">the #GstClock the entry to wait on + line="554">the entry to wait on @@ -12676,17 +13434,17 @@ unscheduled with gst_clock_id_unschedule(). The time @master of the master clock and the time @slave of the slave -clock are added to the list of observations. If enough observations -are available, a linear regression algorithm is run on the -observations and @clock is recalibrated. + line="1432">The time @observation_external of the external or master clock and the time +@observation_internal of the internal or slave clock are added to the list of +observations. If enough observations are available, a linear regression +algorithm is run on the observations and @clock is recalibrated. If this functions returns %TRUE, @r_squared will contain the correlation coefficient of the interpolation. A value of 1.0 means a perfect regression was performed. This value can be used to control the sampling frequency of the master and slave clocks. - + line="1434">a #GstClock - + a time on the slave + line="1435">a time on the internal clock - + a time on the master + line="1436">a time on the external clock Add a clock observation to the internal slaving algorithm the same as -gst_clock_add_observation(), and return the result of the master clock -estimation, without updating the internal calibration. +gst_clock_add_observation(), and return the result of the external or master +clock estimation, without updating the internal calibration. The caller can then take the results and call gst_clock_set_calibration() with the values, or some modified version of them. - + line="1471">a #GstClock - + a time on the slave + line="1472">a time on the internal clock - + a time on the master + line="1473">a time on the external clock - + - + - + @@ -12981,7 +13739,7 @@ caller is not interested in the values. filename="gst/gstclock.c" line="1056">Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate. - + filename="gst/gstclock.c" line="1348">Gets the master clock that @clock is slaved to or %NULL when the clock is not slaved to any master clock. - + filename="gst/gstclock.c" line="859">Gets the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by gst_clock_get_time(). - + line="1100">Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate. - + glib:get-property="timeout"> Gets the amount of time that master and slave clocks are sampled. - + line="1580">Gets the amount of time that master and slave clocks are sampled. + the interval between samples. + line="1586">the interval between samples. a #GstClock + line="1582">a #GstClock @@ -13091,20 +13849,20 @@ given invalid input. version="1.6"> Checks if the clock is currently synced, by looking at whether + line="1721">Checks if the clock is currently synced, by looking at whether %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set. - + %TRUE if the clock is currently synced + line="1728">%TRUE if the clock is currently synced a GstClock + line="1723">a GstClock @@ -13115,7 +13873,7 @@ given invalid input. line="430">Gets an ID from @clock to trigger a periodic notification. The periodic notifications will start at time @start_time and will then be fired with the given @interval. - + filename="gst/gstclock.c" line="409">Gets a #GstClockID from @clock to trigger a single shot notification at the requested time. - + filename="gst/gstclock.c" line="322">Reinitializes the provided periodic @id to the provided start time and interval. Does not modify the reference count. - + - + @@ -13289,7 +14047,7 @@ calibration values with gst_clock_get_calibration(). @master can be %NULL in which case @clock will not be slaved anymore. It will however keep reporting its time adjusted with the last configured rate and time offsets. - + - + Sets @clock to synced and emits the #GstClock::synced signal, and wakes up any + line="1741">Sets @clock to synced and emits the #GstClock::synced signal, and wakes up any thread waiting in gst_clock_wait_for_sync(). This function must only be called if %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set on the clock, and is intended to be called by subclasses only. - + @@ -13364,13 +14122,13 @@ is set on the clock, and is intended to be called by subclasses only. a GstClock + line="1743">a GstClock if the clock is synced + line="1744">if the clock is synced @@ -13380,9 +14138,9 @@ is set on the clock, and is intended to be called by subclasses only. glib:set-property="timeout"> Sets the amount of time, in nanoseconds, to sample master and slave + line="1562">Sets the amount of time, in nanoseconds, to sample master and slave clocks - + @@ -13390,13 +14148,13 @@ clocks a #GstClock + line="1564">a #GstClock a timeout + line="1565">a timeout @@ -13407,7 +14165,7 @@ clocks filename="gst/gstclock.c" line="300">Reinitializes the provided single shot @id to the provided time. Does not modify the reference count. - + - + - + version="1.6"> Waits until @clock is synced for reporting the current time. If @timeout + line="1669">Waits until @clock is synced for reporting the current time. If @timeout is %GST_CLOCK_TIME_NONE it will wait forever, otherwise it will time out after @timeout nanoseconds. @@ -13542,24 +14300,24 @@ For asynchronous waiting, the #GstClock::synced signal can be used. This returns immediately with %TRUE if %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock, or if the clock is already synced. - + %TRUE if waiting was successful, or %FALSE on timeout + line="1683">%TRUE if waiting was successful, or %FALSE on timeout a GstClock + line="1671">a GstClock timeout for waiting or %GST_CLOCK_TIME_NONE + line="1672">timeout for waiting or %GST_CLOCK_TIME_NONE @@ -13587,7 +14345,7 @@ is not set on the clock, or if the clock is already synced. the parent structure + line="469">the parent structure @@ -13623,31 +14381,31 @@ the application's main thread. The function prototype of the callback. - + line="294">The function prototype of the callback. + %TRUE or %FALSE (currently unused) + line="303">%TRUE or %FALSE (currently unused) The clock that triggered the callback + line="296">The clock that triggered the callback The time it was triggered + line="297">The time it was triggered The #GstClockID that expired + line="298">The #GstClockID that expired closure="3"> user data passed in the gst_clock_id_wait_async() function + line="299">user data passed in the gst_clock_id_wait_async() function @@ -13667,41 +14425,41 @@ the application's main thread. glib:is-gtype-struct-for="Clock"> GStreamer clock class. Override the vmethods to implement the clock + line="482">GStreamer clock class. Override the vmethods to implement the clock functionality. - + the parent class structure + line="484">the parent class structure - + the new resolution + line="504">the new resolution the #GstClock + line="497">the #GstClock the previous resolution + line="498">the previous resolution the new resolution + line="499">the new resolution @@ -13709,7 +14467,7 @@ functionality. - + - + - + the result of the blocking wait. #GST_CLOCK_EARLY will be returned + line="543">the result of the blocking wait. #GST_CLOCK_EARLY will be returned if the current clock time is past the time of @id, #GST_CLOCK_OK if @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was unscheduled with gst_clock_id_unschedule(). @@ -13762,13 +14520,13 @@ unscheduled with gst_clock_id_unschedule(). the #GstClock + line="536">the #GstClock the entry to wait on + line="537">the entry to wait on allow-none="1"> a pointer that will contain the jitter + line="538">a pointer that will contain the jitter @@ -13787,24 +14545,24 @@ unscheduled with gst_clock_id_unschedule(). - + the result of the non blocking wait. + line="558">the result of the non blocking wait. the #GstClock + line="553">the #GstClock the entry to wait on + line="554">the entry to wait on @@ -13812,7 +14570,7 @@ unscheduled with gst_clock_id_unschedule(). - + @@ -13820,13 +14578,13 @@ unscheduled with gst_clock_id_unschedule(). the #GstClock + line="564">the #GstClock the entry to unschedule + line="565">the entry to unschedule @@ -13841,15 +14599,15 @@ unscheduled with gst_clock_id_unschedule(). All pending timeouts or periodic notifies are converted into + line="392">All pending timeouts or periodic notifies are converted into an entry. Note that GstClockEntry should be treated as an opaque structure. It must not be extended or allocated using a custom allocator. - + reference counter (read-only) + line="394">reference counter (read-only) @@ -13894,7 +14652,7 @@ not be extended or allocated using a custom allocator. c:type="GstClockEntryType"> The type of the clock entry + line="332">The type of the clock entry glib:name="GST_CLOCK_ENTRY_SINGLE"> a single shot timeout + line="334">a single shot timeout glib:name="GST_CLOCK_ENTRY_PERIODIC"> a periodic timeout request + line="335">a periodic timeout request c:type="GstClockFlags"> The capabilities of this clock + line="427">The capabilities of this clock glib:name="GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC"> clock can do a single sync timeout request + line="429">clock can do a single sync timeout request glib:name="GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC"> clock can do a single async timeout request + line="430">clock can do a single async timeout request glib:name="GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC"> clock can do sync periodic timeout requests + line="431">clock can do sync periodic timeout requests glib:name="GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC"> clock can do async periodic timeout callbacks + line="432">clock can do async periodic timeout callbacks glib:name="GST_CLOCK_FLAG_CAN_SET_RESOLUTION"> clock's resolution can be changed + line="433">clock's resolution can be changed glib:name="GST_CLOCK_FLAG_CAN_SET_MASTER"> clock can be slaved to a master clock + line="434">clock can be slaved to a master clock glib:name="GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC"> clock needs to be synced before it can be used + line="447">clock needs to be synced before it can be used glib:name="GST_CLOCK_FLAG_LAST"> subclasses can add additional flags starting from this flag + line="435">subclasses can add additional flags starting from this flag - + c:type="GstClockReturn"> The return value of a clock operation. + line="307">The return value of a clock operation. glib:name="GST_CLOCK_OK"> The operation succeeded. + line="309">The operation succeeded. glib:name="GST_CLOCK_EARLY"> The operation was scheduled too late. + line="310">The operation was scheduled too late. glib:name="GST_CLOCK_UNSCHEDULED"> The clockID was unscheduled + line="311">The clockID was unscheduled glib:name="GST_CLOCK_BUSY"> The ClockID is busy + line="312">The ClockID is busy glib:name="GST_CLOCK_BADTIME"> A bad time was provided to a function. + line="313">A bad time was provided to a function. glib:name="GST_CLOCK_ERROR"> An error occurred + line="314">An error occurred glib:name="GST_CLOCK_UNSUPPORTED"> Operation is not supported + line="315">Operation is not supported glib:name="GST_CLOCK_DONE"> The ClockID is done waiting + line="316">The ClockID is done waiting Creates a new context. - + line="154">Creates a new context. + The new context. + line="161">The new context. Context type + line="156">Context type Persistent context + line="157">Persistent context @@ -14197,19 +14955,19 @@ context set to an element. version="1.2"> Gets the type of @context. - + line="188">Gets the type of @context. + The type of the context. + line="194">The type of the context. The #GstContext. + line="190">The #GstContext. @@ -14219,12 +14977,12 @@ context set to an element. version="1.2"> Accesses the structure of the context. - + line="227">Accesses the structure of the context. + The structure of the context. The structure is + line="233">The structure of the context. The structure is still owned by the context, which means that you should not modify it, free it and that the pointer becomes invalid when you free the context. @@ -14233,7 +14991,7 @@ free it and that the pointer becomes invalid when you free the context. The #GstContext. + line="229">The #GstContext. @@ -14243,25 +15001,25 @@ free it and that the pointer becomes invalid when you free the context. version="1.2"> Checks if @context has @context_type. - + line="206">Checks if @context has @context_type. + %TRUE if @context has @context_type. + line="213">%TRUE if @context has @context_type. The #GstContext. + line="208">The #GstContext. Context type to check. + line="209">Context type to check. @@ -14271,19 +15029,19 @@ free it and that the pointer becomes invalid when you free the context. version="1.2"> Checks if @context is persistent. - + line="269">Checks if @context is persistent. + %TRUE if the context is persistent. + line="275">%TRUE if the context is persistent. The #GstContext. + line="271">The #GstContext. @@ -14293,12 +15051,12 @@ free it and that the pointer becomes invalid when you free the context. version="1.2"> Gets a writable version of the structure. - + line="247">Gets a writable version of the structure. + The structure of the context. The structure is still + line="253">The structure of the context. The structure is still owned by the context, which means that you should not free it and that the pointer becomes invalid when you free the context. This function checks if @context is writable. @@ -14308,7 +15066,7 @@ This function checks if @context is writable. The #GstContext. + line="249">The #GstContext. @@ -15373,23 +16131,37 @@ this functionality yet. Simple typing wrapper around #GstMeta - + line="130">Extra custom metadata. The @structure field is the same as returned by +gst_custom_meta_get_structure(). + +Since 1.24 it can be serialized using gst_meta_serialize() and +gst_meta_deserialize(), but only if the #GstStructure does not contain any +fields that cannot be serialized, see %GST_SERIALIZE_FLAG_STRICT. + + parent #GstMeta + + #GstStructure containing custom metadata. + + Retrieve the #GstStructure backing a custom meta, the structure's mutability + line="238">Retrieve the #GstStructure backing a custom meta, the structure's mutability is conditioned to the writability of the #GstBuffer @meta is attached to. - + the #GstStructure backing @meta + line="244">the #GstStructure backing @meta @@ -15403,12 +16175,12 @@ is conditioned to the writability of the #GstBuffer @meta is attached to. version="1.20"> Checks whether the name of the custom meta is @name - + line="257">Checks whether the name of the custom meta is @name + Whether @name is the name of the custom meta + line="262">Whether @name is the name of the custom meta @@ -15426,43 +16198,43 @@ is conditioned to the writability of the #GstBuffer @meta is attached to. version="1.20"> Function called for each @meta in @buffer as a result of performing a + line="222">Function called for each @meta in @buffer as a result of performing a transformation that yields @transbuf. Additional @type specific transform data is passed to the function as @data. Implementations should check the @type of the transform and parse additional type specific fields in @data that should be used to update the metadata on @transbuf. - + %TRUE if the transform could be performed + line="239">%TRUE if the transform could be performed a #GstBuffer + line="224">a #GstBuffer a #GstCustomMeta + line="225">a #GstCustomMeta a #GstBuffer + line="226">a #GstBuffer the transform type + line="227">the transform type allow-none="1"> transform specific data. + line="228">transform specific data. closure="5"> user data passed when registering the meta + line="229">user data passed when registering the meta @@ -15489,21 +16261,21 @@ the metadata on @transbuf. Output a debugging message in the default category. + line="1277">Output a debugging message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1279">printf-style message to output - + introspectable="0"> Defines a GstDebugCategory variable. + line="609">Defines a GstDebugCategory variable. This macro expands to nothing if debugging is disabled. - + the category + line="611">the category @@ -15595,14 +16367,14 @@ This macro expands to nothing if debugging is disabled. introspectable="0"> Declares a GstDebugCategory variable as extern. Use in header files. + line="617">Declares a GstDebugCategory variable as extern. Use in header files. This macro expands to nothing if debugging is disabled. - + the category + line="619">the category @@ -15611,7 +16383,7 @@ This macro expands to nothing if debugging is disabled. introspectable="0"> Looks up an existing #GstDebugCategory by its @name and sets @cat. If the + line="669">Looks up an existing #GstDebugCategory by its @name and sets @cat. If the category is not found, but GST_CAT_DEFAULT is defined, that is assigned to @cat. Otherwise @cat will be %NULL. @@ -15623,17 +16395,17 @@ GST_DEBUG_CATEGORY_STATIC (GST_CAT_PERFORMANCE); GST_DEBUG_CATEGORY_INIT (gst_myplugin_debug, "myplugin", 0, "nice element"); GST_DEBUG_CATEGORY_GET (GST_CAT_PERFORMANCE, "GST_PERFORMANCE"); ]| - + the category to initialize. + line="671">the category to initialize. log category name + line="672">log category name @@ -15642,7 +16414,7 @@ GST_DEBUG_CATEGORY_GET (GST_CAT_PERFORMANCE, "GST_PERFORMANCE"); introspectable="0"> Initializes a new #GstDebugCategory with the given properties and set to + line="635">Initializes a new #GstDebugCategory with the given properties and set to the default threshold. > This macro expands to nothing if debugging is disabled. @@ -15662,27 +16434,27 @@ the default threshold. > common prefix followed by an underscore for all your categories. GStreamer > uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure > to include uppercase letters. - + the category to initialize. + line="637">the category to initialize. the name of the category. + line="638">the name of the category. the colors to use for a color representation or 0 for no color. + line="639">the colors to use for a color representation or 0 for no color. optional description of the category. + line="640">optional description of the category. @@ -15691,25 +16463,25 @@ the default threshold. introspectable="0"> Defines a static GstDebugCategory variable. + line="626">Defines a static GstDebugCategory variable. This macro expands to nothing if debugging is disabled. - + the category + line="628">the category - + - + introspectable="0"> Register a pointer to a function with its name, so it can later be used by + line="1806">Register a pointer to a function with its name, so it can later be used by GST_DEBUG_FUNCPTR_NAME(). - + pointer to the function to register + line="1808">pointer to the function to register @@ -15733,17 +16505,17 @@ GST_DEBUG_FUNCPTR_NAME(). introspectable="0"> Retrieves the name of the function, if it was previously registered with + line="1818">Retrieves the name of the function, if it was previously registered with GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer. This macro returns a constant string which must not be modified or freed by the caller. - + address of the function of which to look up the name + line="1820">address of the function of which to look up the name @@ -15753,21 +16525,21 @@ freed by the caller. introspectable="0"> Output a debugging message for the given identifier in the default category. + line="1185">Output a debugging message for the given identifier in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1187">An identifier of the message provider printf-style message to output + line="1188">printf-style message to output @@ -15776,22 +16548,22 @@ character, a newline character will be added automatically. introspectable="0"> Output a debugging message belonging to the given object in the default + line="1094">Output a debugging message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1096">the #GObject the message belongs to printf-style message to output + line="1097">printf-style message to output @@ -15800,14 +16572,14 @@ character, a newline character will be added automatically. introspectable="0"> Evaluates to 2 strings, that describe the pad. Often used in debugging + line="244">Evaluates to 2 strings, that describe the pad. Often used in debugging statements. - + The pad to debug. + line="246">The pad to debug. @@ -15816,16 +16588,16 @@ statements. introspectable="0"> Register a pointer to a function with its name, so it can later be used by + line="1795">Register a pointer to a function with its name, so it can later be used by GST_DEBUG_FUNCPTR_NAME(). Use this variant of #GST_DEBUG_FUNCPTR if you do not need to use @ptr. - + pointer to the function to register + line="1797">pointer to the function to register @@ -16099,7 +16871,7 @@ Used to generate `gst_device_provider_register_*(GstPlugin* plugin)`. - + @@ -16117,12 +16889,21 @@ Used to generate `gst_device_provider_register_*(GstPlugin* plugin)`. - + + + + + + + + This is the struct that describes the categories. Once initialized with + line="214">This is the struct that describes the categories. Once initialized with #GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore. - + @@ -16980,9 +17761,9 @@ reference count reaches zero, the structure is freed. deprecated="1"> Removes and frees the category and all associated resources. + line="2175">Removes and frees the category and all associated resources. This function can easily cause memory corruption, don't use it. - + @@ -16990,7 +17771,7 @@ reference count reaches zero, the structure is freed. #GstDebugCategory to free. + line="2177">#GstDebugCategory to free. @@ -16998,20 +17779,20 @@ reference count reaches zero, the structure is freed. Returns the color of a debug category used when printing output in this + line="2259">Returns the color of a debug category used when printing output in this category. - + the color of the category. + line="2266">the color of the category. a #GstDebugCategory to get the color of. + line="2261">a #GstDebugCategory to get the color of. @@ -17020,19 +17801,19 @@ category. c:identifier="gst_debug_category_get_description"> Returns the description of a debug category. - + line="2274">Returns the description of a debug category. + the description of the category. + line="2280">the description of the category. a #GstDebugCategory to get the description of. + line="2276">a #GstDebugCategory to get the description of. @@ -17040,19 +17821,19 @@ category. Returns the name of a debug category. - + line="2245">Returns the name of a debug category. + the name of the category. + line="2251">the name of the category. a #GstDebugCategory to get name of. + line="2247">a #GstDebugCategory to get name of. @@ -17061,19 +17842,19 @@ category. c:identifier="gst_debug_category_get_threshold"> Returns the threshold of a #GstDebugCategory. - + line="2231">Returns the threshold of a #GstDebugCategory. + the #GstDebugLevel that is used as threshold. + line="2237">the #GstDebugLevel that is used as threshold. a #GstDebugCategory to get threshold of. + line="2233">a #GstDebugCategory to get threshold of. @@ -17082,12 +17863,12 @@ category. c:identifier="gst_debug_category_reset_threshold"> Resets the threshold of the category to the default level. Debug information + line="2215">Resets the threshold of the category to the default level. Debug information will only be output if the threshold is lower or equal to the level of the debugging message. Use this function to set the threshold back to where it was after using gst_debug_category_set_threshold(). - + @@ -17095,7 +17876,7 @@ gst_debug_category_set_threshold(). a #GstDebugCategory to reset threshold of. + line="2217">a #GstDebugCategory to reset threshold of. @@ -17104,13 +17885,13 @@ gst_debug_category_set_threshold(). c:identifier="gst_debug_category_set_threshold"> Sets the threshold of the category to the given level. Debug information will + line="2189">Sets the threshold of the category to the given level. Debug information will only be output if the threshold is lower or equal to the level of the debugging message. > Do not use this function in production code, because other functions may > change the threshold of categories as side effect. It is however a nice > function to use when debugging (even from gdb). - + @@ -17118,13 +17899,13 @@ debugging message. a #GstDebugCategory to set threshold of. + line="2191">a #GstDebugCategory to set threshold of. the #GstDebugLevel threshold to set. + line="2192">the #GstDebugLevel threshold to set. @@ -17136,7 +17917,7 @@ debugging message. c:type="GstDebugColorFlags"> These are some terminal style flags you can use when creating your + line="131">These are some terminal style flags you can use when creating your debugging categories to make them stand out in debugging output. glib:name="GST_DEBUG_FG_BLACK"> Use black as foreground color. + line="133">Use black as foreground color. glib:name="GST_DEBUG_FG_RED"> Use red as foreground color. + line="134">Use red as foreground color. glib:name="GST_DEBUG_FG_GREEN"> Use green as foreground color. + line="135">Use green as foreground color. glib:name="GST_DEBUG_FG_YELLOW"> Use yellow as foreground color. + line="136">Use yellow as foreground color. glib:name="GST_DEBUG_FG_BLUE"> Use blue as foreground color. + line="137">Use blue as foreground color. glib:name="GST_DEBUG_FG_MAGENTA"> Use magenta as foreground color. + line="138">Use magenta as foreground color. glib:name="GST_DEBUG_FG_CYAN"> Use cyan as foreground color. + line="139">Use cyan as foreground color. glib:name="GST_DEBUG_FG_WHITE"> Use white as foreground color. + line="140">Use white as foreground color. glib:name="GST_DEBUG_BG_BLACK"> Use black as background color. + line="141">Use black as background color. glib:name="GST_DEBUG_BG_RED"> Use red as background color. + line="142">Use red as background color. glib:name="GST_DEBUG_BG_GREEN"> Use green as background color. + line="143">Use green as background color. glib:name="GST_DEBUG_BG_YELLOW"> Use yellow as background color. + line="144">Use yellow as background color. glib:name="GST_DEBUG_BG_BLUE"> Use blue as background color. + line="145">Use blue as background color. glib:name="GST_DEBUG_BG_MAGENTA"> Use magenta as background color. + line="146">Use magenta as background color. glib:name="GST_DEBUG_BG_CYAN"> Use cyan as background color. + line="147">Use cyan as background color. glib:name="GST_DEBUG_BG_WHITE"> Use white as background color. + line="148">Use white as background color. glib:name="GST_DEBUG_BOLD"> Make the output bold. + line="149">Make the output bold. glib:name="GST_DEBUG_UNDERLINE"> Underline the output. + line="150">Underline the output. glib:name="GST_DEBUG_COLOR_MODE_OFF"> Do not use colors in logs. + line="197">Do not use colors in logs. glib:name="GST_DEBUG_COLOR_MODE_ON"> Paint logs in a platform-specific way. + line="198">Paint logs in a platform-specific way. glib:name="GST_DEBUG_COLOR_MODE_UNIX"> Paint logs with UNIX terminal color codes + line="199">Paint logs with UNIX terminal color codes no matter what platform GStreamer is running on. @@ -17338,10 +18119,10 @@ debugging categories to make them stand out in debugging output. we define this to avoid a compiler warning regarding a cast from a function + line="439">we define this to avoid a compiler warning regarding a cast from a function pointer to a void pointer (see https://bugzilla.gnome.org/show_bug.cgi?id=309253) - + @@ -17427,7 +18208,7 @@ and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(). c:type="GstDebugLevel"> The level defines the importance of a debugging message. The more important a + line="34">The level defines the importance of a debugging message. The more important a message is, the greater the probability that the debugging system outputs it. No debugging level specified or desired. Used to deactivate + line="36">No debugging level specified or desired. Used to deactivate debugging output. Error messages are to be used only when an error occurred + line="38">Error messages are to be used only when an error occurred that stops the application from keeping working correctly. An examples is gst_element_error, which outputs a message with this priority. It does not mean that the application is terminating as with g_error. @@ -17458,7 +18239,7 @@ message is, the greater the probability that the debugging system outputs it. Warning messages are to inform about abnormal behaviour + line="42">Warning messages are to inform about abnormal behaviour that could lead to problems or weird behaviour later on. An example of this would be clocking issues ("your computer is pretty slow") or broken input data ("Can't synchronize to stream.") @@ -17470,7 +18251,7 @@ message is, the greater the probability that the debugging system outputs it. Fixme messages are messages that indicate that something + line="46">Fixme messages are messages that indicate that something in the executed code path is not fully implemented or handled yet. Note that this does not replace proper error handling in any way, the purpose of this message is to make it easier to spot incomplete/unfinished pieces @@ -17483,7 +18264,7 @@ message is, the greater the probability that the debugging system outputs it. Informational messages should be used to keep the developer + line="51">Informational messages should be used to keep the developer updated about what is happening. Examples where this should be used are when a typefind function has successfully determined the type of the stream or when an mp3 plugin detects @@ -17496,7 +18277,7 @@ message is, the greater the probability that the debugging system outputs it. Debugging messages should be used when something common + line="56">Debugging messages should be used when something common happens that is not the expected default behavior, or something that's useful to know but doesn't happen all the time (ie. per loop iteration or buffer processed or event handled). @@ -17510,7 +18291,7 @@ message is, the greater the probability that the debugging system outputs it. Log messages are messages that are very common but might be + line="62">Log messages are messages that are very common but might be useful to know. As a rule of thumb a pipeline that is running as expected should never output anything else but LOG messages whilst processing data. Use this log level to log recurring information in chain functions and @@ -17523,7 +18304,7 @@ message is, the greater the probability that the debugging system outputs it. Tracing-related messages. + line="67">Tracing-related messages. Examples for this are referencing/dereferencing of objects. memory dump messages are used to log (small) chunks of + line="69">memory dump messages are used to log (small) chunks of data as memory dumps in the log. They will be displayed as hexdump with ASCII characters. @@ -17544,24 +18325,24 @@ message is, the greater the probability that the debugging system outputs it. The number of defined debugging levels. + line="72">The number of defined debugging levels. Get the string representation of a debugging level - + line="1703">Get the string representation of a debugging level + the name + line="1709">the name the level to get the name for + line="1705">the level to get the name for @@ -17571,24 +18352,24 @@ message is, the greater the probability that the debugging system outputs it. - + Gets the string representation of a #GstDebugMessage. This function is used + line="778">Gets the string representation of a #GstDebugMessage. This function is used in debug handlers to extract the message. - + the string representation of a #GstDebugMessage. + line="785">the string representation of a #GstDebugMessage. a debug message + line="780">a debug message @@ -17598,20 +18379,20 @@ in debug handlers to extract the message. version="1.22"> Get the id of the object that emitted this message. This function is used in + line="846">Get the id of the object that emitted this message. This function is used in debug handlers. Can be empty. - + The emitter of a #GstDebugMessage. + line="855">The emitter of a #GstDebugMessage. a debug message + line="848">a debug message @@ -17990,6 +18771,10 @@ device in the PLAYING state. + Creates the fully configured element to access this device. + Subclasses need to override this and return a new element. @@ -18020,6 +18805,11 @@ create a unique name. + This only needs to be implemented by subclasses if the + element can be reconfigured to use a different device. See the documentation + for gst_device_reconfigure_element(). @@ -18128,12 +18918,12 @@ The basic use pattern of a device monitor is as follows: version="1.4"> Create a new #GstDeviceMonitor + line="796">Create a new #GstDeviceMonitor a new device monitor. + line="801">a new device monitor. @@ -18142,7 +18932,7 @@ The basic use pattern of a device monitor is as follows: version="1.4"> Adds a filter for which #GstDevice will be monitored, any device that matches + line="619">Adds a filter for which #GstDevice will be monitored, any device that matches all these classes and the #GstCaps will be returned. If this function is called multiple times to add more filters, each will be @@ -18157,7 +18947,7 @@ Filters must be added before the #GstDeviceMonitor is started. The id of the new filter or 0 if no provider matched the filter's + line="637">The id of the new filter or 0 if no provider matched the filter's classes. @@ -18165,7 +18955,7 @@ Filters must be added before the #GstDeviceMonitor is started. a device monitor + line="621">a device monitor allow-none="1"> device classes to use as filter or %NULL for any class + line="622">device classes to use as filter or %NULL for any class allow-none="1"> the #GstCaps to filter or %NULL for ANY + line="623">the #GstCaps to filter or %NULL for ANY @@ -18193,19 +18983,19 @@ Filters must be added before the #GstDeviceMonitor is started. version="1.4"> Gets the #GstBus of this #GstDeviceMonitor + line="818">Gets the #GstBus of this #GstDeviceMonitor a #GstBus + line="824">a #GstBus a #GstDeviceProvider + line="820">a #GstDeviceProvider @@ -18215,13 +19005,13 @@ Filters must be added before the #GstDeviceMonitor is started. version="1.4"> Gets a list of devices from all of the relevant monitors. This may actually + line="379">Gets a list of devices from all of the relevant monitors. This may actually probe the hardware if the monitor is not currently started. a #GList of + line="386">a #GList of #GstDevice @@ -18231,7 +19021,7 @@ probe the hardware if the monitor is not currently started. A #GstDeviceProvider + line="381">A #GstDeviceProvider @@ -18241,14 +19031,14 @@ probe the hardware if the monitor is not currently started. version="1.6"> Get a list of the currently selected device provider factories. + line="836">Get a list of the currently selected device provider factories. This + line="844"> A list of device provider factory names that are currently being monitored by @monitor or %NULL when nothing is being monitored. @@ -18259,7 +19049,7 @@ This a #GstDeviceMonitor + line="838">a #GstDeviceMonitor @@ -18269,20 +19059,20 @@ This version="1.6"> Get if @monitor is currently showing all devices, even those from hidden + line="902">Get if @monitor is currently showing all devices, even those from hidden providers. %TRUE when all devices will be shown. + line="909">%TRUE when all devices will be shown. a #GstDeviceMonitor + line="904">a #GstDeviceMonitor @@ -18292,26 +19082,26 @@ providers. version="1.4"> Removes a filter from the #GstDeviceMonitor using the id that was returned + line="730">Removes a filter from the #GstDeviceMonitor using the id that was returned by gst_device_monitor_add_filter(). %TRUE of the filter id was valid, %FALSE otherwise + line="738">%TRUE of the filter id was valid, %FALSE otherwise a device monitor + line="732">a device monitor the id of the filter + line="733">the id of the filter @@ -18321,7 +19111,7 @@ by gst_device_monitor_add_filter(). version="1.6"> Set if all devices should be visible, even those devices from hidden + line="881">Set if all devices should be visible, even those devices from hidden providers. Setting @show_all to true might show some devices multiple times. @@ -18331,13 +19121,13 @@ providers. Setting @show_all to true might show some devices multiple times. a #GstDeviceMonitor + line="883">a #GstDeviceMonitor show all devices + line="884">show all devices @@ -18347,14 +19137,14 @@ providers. Setting @show_all to true might show some devices multiple times. Starts monitoring the devices, one this has succeeded, the + line="475">Starts monitoring the devices, one this has succeeded, the %GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages will be emitted on the bus when the list of devices changes. %TRUE if the device monitoring could be started, i.e. at least a + line="483">%TRUE if the device monitoring could be started, i.e. at least a single device provider was started successfully. @@ -18362,7 +19152,7 @@ will be emitted on the bus when the list of devices changes. A #GstDeviceMonitor + line="477">A #GstDeviceMonitor @@ -18370,7 +19160,7 @@ will be emitted on the bus when the list of devices changes. Stops monitoring the devices. + line="553">Stops monitoring the devices. @@ -18379,7 +19169,7 @@ will be emitted on the bus when the list of devices changes. A #GstDeviceProvider + line="555">A #GstDeviceProvider @@ -18504,6 +19294,11 @@ from all relevant providers. + Returns a list of devices that are currently available. + This should never block. The devices should not have a parent and should + be floating. @@ -18519,7 +19314,7 @@ from all relevant providers. Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED + line="435">Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus when devices are added or removed from the system. @@ -18535,14 +19330,14 @@ return the same objects that have been received from the %TRUE if the device providering could be started + line="452">%TRUE if the device providering could be started A #GstDeviceProvider + line="437">A #GstDeviceProvider @@ -18550,7 +19345,7 @@ return the same objects that have been received from the Decreases the use-count by one. If the use count reaches zero, this + line="511">Decreases the use-count by one. If the use count reaches zero, this #GstDeviceProvider will stop providering the devices. This needs to be called the same number of times that gst_device_provider_start() was called. @@ -18561,7 +19356,7 @@ called the same number of times that gst_device_provider_start() was called. A #GstDeviceProvider + line="513">A #GstDeviceProvider @@ -18583,7 +19378,7 @@ called the same number of times that gst_device_provider_start() was called. Posts a message on the provider's #GstBus to inform applications that + line="610">Posts a message on the provider's #GstBus to inform applications that a new device has been added. This is for use by subclasses. @@ -18598,13 +19393,13 @@ will be removed (see gst_object_ref_sink()). a #GstDeviceProvider + line="612">a #GstDeviceProvider a #GstDevice that has been added + line="613">a #GstDevice that has been added @@ -18614,7 +19409,7 @@ will be removed (see gst_object_ref_sink()). version="1.16"> This function is used when @changed_device was modified into its new form + line="809">This function is used when @changed_device was modified into its new form @device. This will post a `DEVICE_CHANGED` message on the bus to let the application know that the device was modified. #GstDevice is immutable for MT. safety purposes so this is an "atomic" way of letting the application @@ -18630,13 +19425,13 @@ know when a device was modified. the new version of @changed_device + line="811">the new version of @changed_device the old version of the device that has been updated + line="812">the old version of the device that has been updated @@ -18646,7 +19441,7 @@ know when a device was modified. version="1.4"> Posts a message on the provider's #GstBus to inform applications that + line="653">Posts a message on the provider's #GstBus to inform applications that a device has been removed. This is for use by subclasses. @@ -18658,13 +19453,13 @@ This is for use by subclasses. a #GstDeviceProvider + line="655">a #GstDeviceProvider a #GstDevice that has been removed + line="656">a #GstDevice that has been removed @@ -18674,19 +19469,19 @@ This is for use by subclasses. version="1.4"> Gets the #GstBus of this #GstDeviceProvider + line="592">Gets the #GstBus of this #GstDeviceProvider a #GstBus + line="598">a #GstBus a #GstDeviceProvider + line="594">a #GstDeviceProvider @@ -18696,7 +19491,7 @@ This is for use by subclasses. version="1.4"> Gets a list of devices that this provider understands. This may actually + line="386">Gets a list of devices that this provider understands. This may actually probe the hardware if the provider is not currently started. If the provider has been started, this will returned the same #GstDevice @@ -18705,7 +19500,7 @@ objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages. a #GList of + line="396">a #GList of #GstDevice @@ -18715,7 +19510,7 @@ objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages. A #GstDeviceProvider + line="388">A #GstDeviceProvider @@ -18725,12 +19520,12 @@ objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages. Retrieves the factory that was used to create this device provider. + line="550">Retrieves the factory that was used to create this device provider. the #GstDeviceProviderFactory used for + line="556">the #GstDeviceProviderFactory used for creating this device provider. no refcounting is needed. @@ -18739,7 +19534,7 @@ objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages. a #GstDeviceProvider to request the device provider factory of. + line="552">a #GstDeviceProvider to request the device provider factory of. @@ -18749,13 +19544,13 @@ objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages. Get the provider factory names of the #GstDeviceProvider instances that + line="689">Get the provider factory names of the #GstDeviceProvider instances that are hidden by @provider. + line="696"> a list of hidden providers factory names or %NULL when nothing is hidden by @provider. Free with g_strfreev. @@ -18766,7 +19561,7 @@ are hidden by @provider. a #GstDeviceProvider + line="691">a #GstDeviceProvider @@ -18776,25 +19571,25 @@ are hidden by @provider. version="1.14"> Get metadata with @key in @provider. + line="363">Get metadata with @key in @provider. the metadata for @key. + line="370">the metadata for @key. provider to get metadata for + line="365">provider to get metadata for the key to get + line="366">the key to get @@ -18804,7 +19599,7 @@ are hidden by @provider. version="1.6"> Make @provider hide the devices from the factory with @name. + line="728">Make @provider hide the devices from the factory with @name. This function is used when @provider will also provide the devices reported by provider factory @name. A monitor should stop monitoring the @@ -18817,13 +19612,13 @@ device provider with @name to avoid duplicate devices. a #GstDeviceProvider + line="730">a #GstDeviceProvider a provider factory name + line="731">a provider factory name @@ -18833,7 +19628,7 @@ device provider with @name to avoid duplicate devices. version="1.20"> This function can be used to know if the @provider was successfully started. + line="859">This function can be used to know if the @provider was successfully started. @@ -18842,7 +19637,7 @@ device provider with @name to avoid duplicate devices. a #GstDeviceProvider + line="861">a #GstDeviceProvider @@ -18852,7 +19647,7 @@ device provider with @name to avoid duplicate devices. version="1.4"> Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED + line="435">Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus when devices are added or removed from the system. @@ -18868,14 +19663,14 @@ return the same objects that have been received from the %TRUE if the device providering could be started + line="452">%TRUE if the device providering could be started A #GstDeviceProvider + line="437">A #GstDeviceProvider @@ -18885,7 +19680,7 @@ return the same objects that have been received from the version="1.4"> Decreases the use-count by one. If the use count reaches zero, this + line="511">Decreases the use-count by one. If the use count reaches zero, this #GstDeviceProvider will stop providering the devices. This needs to be called the same number of times that gst_device_provider_start() was called. @@ -18896,7 +19691,7 @@ called the same number of times that gst_device_provider_start() was called. A #GstDeviceProvider + line="513">A #GstDeviceProvider @@ -18906,7 +19701,7 @@ called the same number of times that gst_device_provider_start() was called. Make @provider unhide the devices from factory @name. + line="767">Make @provider unhide the devices from factory @name. This function is used when @provider will no longer provide the devices reported by provider factory @name. A monitor should start @@ -18920,13 +19715,13 @@ all devices again. a #GstDeviceProvider + line="769">a #GstDeviceProvider a provider factory name + line="770">a provider factory name @@ -18996,6 +19791,11 @@ all devices again. + Returns a list of devices that are currently available. + This should never block. The devices should not have a parent and should + be floating. @@ -19011,25 +19811,33 @@ all devices again. + Starts monitoring for new devices. Only subclasses that can know + that devices have been added or remove need to implement this method. %TRUE if the device providering could be started + line="452">%TRUE if the device providering could be started A #GstDeviceProvider + line="437">A #GstDeviceProvider + Stops monitoring for new devices. Only subclasses that implement + the start() method need to implement this method. @@ -19039,7 +19847,7 @@ all devices again. A #GstDeviceProvider + line="513">A #GstDeviceProvider @@ -19058,7 +19866,7 @@ all devices again. version="1.4"> Set @key with @value as metadata in @klass. + line="199">Set @key with @value as metadata in @klass. @@ -19067,19 +19875,19 @@ all devices again. class to set metadata for + line="201">class to set metadata for the key to set + line="202">the key to set the value to set + line="203">the value to set @@ -19089,7 +19897,7 @@ all devices again. version="1.4"> Set @key with @value as metadata in @klass. + line="221">Set @key with @value as metadata in @klass. Same as gst_device_provider_class_add_metadata(), but @value must be a static string or an inlined string, as it will not be copied. (GStreamer plugins will @@ -19103,19 +19911,19 @@ dynamically loaded plugins.) class to set metadata for + line="223">class to set metadata for the key to set + line="224">the key to set the value to set + line="225">the value to set @@ -19125,25 +19933,25 @@ dynamically loaded plugins.) version="1.4"> Get metadata with @key in @klass. + line="342">Get metadata with @key in @klass. the metadata for @key. + line="349">the metadata for @key. class to get metadata for + line="344">class to get metadata for the key to get + line="345">the key to get @@ -19153,7 +19961,7 @@ dynamically loaded plugins.) version="1.4"> Sets the detailed information for a #GstDeviceProviderClass. + line="251">Sets the detailed information for a #GstDeviceProviderClass. > This function is for use in _class_init functions only. @@ -19164,19 +19972,19 @@ dynamically loaded plugins.) class to set metadata for + line="253">class to set metadata for The long English name of the device provider. E.g. "File Sink" + line="254">The long English name of the device provider. E.g. "File Sink" String describing the type of device provider, as an + line="255">String describing the type of device provider, as an unordered list separated with slashes ('/'). See draft-klass.txt of the design docs for more details and common types. E.g: "Sink/File" @@ -19185,14 +19993,14 @@ for more details and common types. E.g: "Sink/File" Sentence describing the purpose of the device provider. + line="259">Sentence describing the purpose of the device provider. E.g: "Write stream to a file" Name and contact details of the author(s). Use \n to separate + line="261">Name and contact details of the author(s). Use \n to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" @@ -19203,7 +20011,7 @@ multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" version="1.4"> Sets the detailed information for a #GstDeviceProviderClass. + line="288">Sets the detailed information for a #GstDeviceProviderClass. > This function is for use in _class_init functions only. @@ -19219,19 +20027,19 @@ loaded, so this function can be used even from dynamically loaded plugins.) class to set metadata for + line="290">class to set metadata for The long English name of the element. E.g. "File Sink" + line="291">The long English name of the element. E.g. "File Sink" String describing the type of element, as + line="292">String describing the type of element, as an unordered list separated with slashes ('/'). See draft-klass.txt of the design docs for more details and common types. E.g: "Sink/File" @@ -19239,14 +20047,14 @@ design docs for more details and common types. E.g: "Sink/File" Sentence describing the purpose of the + line="295">Sentence describing the purpose of the element. E.g: "Write stream to a file" Name and contact details of the author(s). Use \n + line="297">Name and contact details of the author(s). Use \n to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" @@ -19582,7 +20390,7 @@ plugin_init (GstPlugin * plugin) ]| - + @@ -19777,43 +20585,43 @@ application will be requested to stop further media processing. - + - + - + - + - + - + - + version="1.16"> Elements interacting with hardware devices should specify this classifier in + line="252">Elements interacting with hardware devices should specify this classifier in their metadata. You may need to put the element in "READY" state to test if the hardware is present in the system. - + - + - + - + - + - + - + - + - + - + - + c:type="GST_ELEMENT_FACTORY_TYPE_ANY"> Elements of any of the defined GST_ELEMENT_FACTORY_LIST types - + line="185">Elements of any of the defined GST_ELEMENT_FACTORY_LIST types + c:type="GST_ELEMENT_FACTORY_TYPE_AUDIOVIDEO_SINKS"> All sinks handling audio, video or image media types - + line="217">All sinks handling audio, video or image media types + c:type="GST_ELEMENT_FACTORY_TYPE_AUDIO_ENCODER"> All encoders handling audio media types - + line="210">All encoders handling audio media types + c:type="GST_ELEMENT_FACTORY_TYPE_DECODABLE"> All elements used to 'decode' streams (decoders, demuxers, parsers, depayloaders) - + line="224">All elements used to 'decode' streams (decoders, demuxers, parsers, depayloaders) + - + c:type="GST_ELEMENT_FACTORY_TYPE_MEDIA_ANY"> Elements matching any of the defined GST_ELEMENT_FACTORY_TYPE_MEDIA types + line="192">Elements matching any of the defined GST_ELEMENT_FACTORY_TYPE_MEDIA types Note: Do not use this if you wish to not filter against any of the defined media types. If you wish to do this, simply don't specify any GST_ELEMENT_FACTORY_TYPE_MEDIA flag. - + - + - + - + - + - + + + Timestamp correcting elements + + + All encoders handling video or image media types - + line="203">All encoders handling video or image media types + Output an error message in the default category. + line="1250">Output an error message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1252">printf-style message to output @@ -20616,21 +21434,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an error message for the given identifier in the default category. + line="1148">Output an error message for the given identifier in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1150">An identifier of the message provider printf-style message to output + line="1151">printf-style message to output @@ -20639,21 +21457,21 @@ character, a newline character will be added automatically. introspectable="0"> Output an error message belonging to the given object in the default category. + line="1063">Output an error message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1065">the #GObject the message belongs to printf-style message to output + line="1066">printf-style message to output @@ -20902,12 +21720,12 @@ specific situations. throws="1"> Creates an element for handling the given URI. + line="619">Creates an element for handling the given URI. a new element or %NULL if none + line="628">a new element or %NULL if none could be created @@ -20915,13 +21733,13 @@ could be created Whether to create a source or a sink + line="621">Whether to create a source or a sink URI to create an element for + line="622">URI to create an element for allow-none="1"> Name of created element, can be %NULL. + line="623">Name of created element, can be %NULL. @@ -21059,7 +21877,7 @@ gst_element_register (plugin, "my-plugin-feature-name", rank, my_type); Perform @transition on @element. + line="3076">Perform @transition on @element. This function must be called with STATE_LOCK held and is mainly used internally. @@ -21067,20 +21885,20 @@ internally. the #GstStateChangeReturn of the state transition. + line="3086">the #GstStateChangeReturn of the state transition. a #GstElement + line="3078">a #GstElement the requested transition + line="3079">the requested transition @@ -21088,7 +21906,7 @@ internally. Gets the state of the element. + line="2607">Gets the state of the element. For elements that performed an ASYNC state change, as reported by gst_element_set_state(), this function will block up to the @@ -21112,7 +21930,7 @@ element to playing, the preroll will complete and playback will start. %GST_STATE_CHANGE_SUCCESS if the element has no more pending state + line="2638">%GST_STATE_CHANGE_SUCCESS if the element has no more pending state and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the element is still performing a state change or %GST_STATE_CHANGE_FAILURE if the last state change failed. @@ -21124,7 +21942,7 @@ MT safe. a #GstElement to get the state of. + line="2609">a #GstElement to get the state of. allow-none="1"> a pointer to #GstState to hold the state. + line="2610">a pointer to #GstState to hold the state. Can be %NULL. @@ -21147,14 +21965,14 @@ MT safe. allow-none="1"> a pointer to #GstState to hold the pending + line="2612">a pointer to #GstState to hold the pending state. Can be %NULL. a #GstClockTime to specify the timeout for an async + line="2614">a #GstClockTime to specify the timeout for an async state change or %GST_CLOCK_TIME_NONE for infinite timeout. @@ -21163,7 +21981,7 @@ MT safe. Use this function to signal that the element does not expect any more pads + line="947">Use this function to signal that the element does not expect any more pads to show up in the current pipeline. This function should be called whenever pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES pad templates use this in combination with autopluggers to figure out that @@ -21180,7 +21998,7 @@ MT safe. a #GstElement + line="949">a #GstElement @@ -21216,14 +22034,14 @@ MT safe. Post a message on the element's #GstBus. This function takes ownership of the + line="2142">Post a message on the element's #GstBus. This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling. %TRUE if the message was successfully posted. The function returns + line="2151">%TRUE if the message was successfully posted. The function returns %FALSE if the element did not have a bus. MT safe. @@ -21233,13 +22051,13 @@ MT safe. a #GstElement posting the message + line="2144">a #GstElement posting the message a #GstMessage to post + line="2145">a #GstMessage to post @@ -21247,14 +22065,14 @@ MT safe. Get the clock provided by the given element. + line="374">Get the clock provided by the given element. > An element is only required to provide a clock in the PAUSED > state. Some elements can provide a clock in other states. the GstClock provided by the + line="382">the GstClock provided by the element or %NULL if no clock could be provided. Unref after usage. MT safe. @@ -21264,7 +22082,7 @@ MT safe. a #GstElement to query + line="376">a #GstElement to query @@ -21272,7 +22090,7 @@ MT safe. Performs a query on the given element. + line="2067">Performs a query on the given element. For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a @@ -21283,7 +22101,7 @@ Please note that some queries might need a running pipeline to work. %TRUE if the query could be performed. + line="2080">%TRUE if the query could be performed. MT safe. @@ -21292,18 +22110,21 @@ MT safe. a #GstElement to perform the query on. + line="2069">a #GstElement to perform the query on. the #GstQuery. + line="2070">the #GstQuery. + called when a request pad is to be released @@ -21320,7 +22141,7 @@ MT safe. Retrieves a request pad from the element according to the provided template. + line="1278">Retrieves a request pad from the element according to the provided template. Pad templates can be looked up using gst_element_factory_get_static_pad_templates(). @@ -21329,7 +22150,7 @@ The pad should be released with gst_element_release_request_pad(). requested #GstPad if found, + line="1293">requested #GstPad if found, otherwise %NULL. Release after usage. @@ -21337,13 +22158,13 @@ The pad should be released with gst_element_release_request_pad(). a #GstElement to find a request pad of. + line="1280">a #GstElement to find a request pad of. a #GstPadTemplate of which we want a pad of. + line="1281">a #GstPadTemplate of which we want a pad of. allow-none="1"> the name of the request #GstPad + line="1282">the name of the request #GstPad to retrieve. Can be %NULL. @@ -21362,7 +22183,7 @@ to retrieve. Can be %NULL. allow-none="1"> the caps of the pad we want to + line="1284">the caps of the pad we want to request. Can be %NULL. @@ -21371,7 +22192,7 @@ request. Can be %NULL. Sends an event to an element. If the element doesn't implement an + line="1961">Sends an event to an element. If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events. @@ -21383,7 +22204,7 @@ MT safe. %TRUE if the event was handled. Events that trigger a preroll (such + line="1975">%TRUE if the event was handled. Events that trigger a preroll (such as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. @@ -21391,13 +22212,13 @@ as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. a #GstElement to send the event to. + line="1963">a #GstElement to send the event to. the #GstEvent to send to the element. + line="1964">the #GstEvent to send to the element. @@ -21405,7 +22226,7 @@ as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. Sets the bus of the element. Increases the refcount on the bus. + line="3503">Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you're testing elements. MT safe. @@ -21417,7 +22238,7 @@ MT safe. a #GstElement to set the bus of. + line="3505">a #GstElement to set the bus of. allow-none="1"> the #GstBus to set. + line="3506">the #GstBus to set. @@ -21434,14 +22255,14 @@ MT safe. Sets the clock for the element. This function increases the + line="416">Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed. %TRUE if the element accepted the clock. An element can refuse a + line="425">%TRUE if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the @clock or when it requires a specific clock to operate. @@ -21452,7 +22273,7 @@ MT safe. a #GstElement to set the clock for. + line="418">a #GstElement to set the clock for. allow-none="1"> the #GstClock to set for the element. + line="419">the #GstClock to set for the element. @@ -21469,7 +22290,7 @@ MT safe. Sets the context of the element. Increases the refcount of the context. + line="3588">Sets the context of the element. Increases the refcount of the context. MT safe. @@ -21480,13 +22301,13 @@ MT safe. a #GstElement to set the context of. + line="3590">a #GstElement to set the context of. the #GstContext to set. + line="3591">the #GstContext to set. @@ -21494,7 +22315,7 @@ MT safe. Sets the state of the element. This function will try to set the + line="2921">Sets the state of the element. This function will try to set the requested state by going through all the intermediary states and calling the class's state change function for each. @@ -21511,7 +22332,7 @@ State changes to %GST_STATE_READY or %GST_STATE_NULL never return Result of the state change using #GstStateChangeReturn. + line="2940">Result of the state change using #GstStateChangeReturn. MT safe. @@ -21520,18 +22341,21 @@ MT safe. a #GstElement to change state of. + line="2923">a #GstElement to change state of. the element's new #GstState. + line="2924">the element's new #GstState. + called immediately after a new state was set. @@ -21554,7 +22378,7 @@ MT safe. Abort the state change of the element. This function is used + line="2662">Abort the state change of the element. This function is used by elements that do asynchronous state changes and find out something is wrong. @@ -21569,7 +22393,7 @@ MT safe. a #GstElement to abort the state of. + line="2664">a #GstElement to abort the state of. @@ -21577,7 +22401,7 @@ MT safe. Adds a pad (link point) to @element. @pad's parent will be set to @element; + line="723">Adds a pad (link point) to @element. @pad's parent will be set to @element; see gst_object_set_parent() for refcounting information. Pads are automatically activated when added in the PAUSED or PLAYING @@ -21590,7 +22414,7 @@ This function will emit the #GstElement::pad-added signal on the element. %TRUE if the pad could be added. This function can fail when + line="738">%TRUE if the pad could be added. This function can fail when a pad with the same name already existed or the pad already had another parent. @@ -21601,13 +22425,13 @@ MT safe. a #GstElement to add the pad to. + line="725">a #GstElement to add the pad to. the #GstPad to add to the element. + line="726">the #GstPad to add to the element. @@ -21619,7 +22443,7 @@ MT safe. a watch id, which can be used in connection with + line="3788">a watch id, which can be used in connection with gst_element_remove_property_notify_watch() to remove the watch again. @@ -21627,7 +22451,7 @@ MT safe. a #GstElement to watch (recursively) for property changes + line="3783">a #GstElement to watch (recursively) for property changes allow-none="1"> name of property to watch for changes, or + line="3784">name of property to watch for changes, or NULL to watch all properties whether to include the new property value in the message + line="3786">whether to include the new property value in the message @@ -21655,7 +22479,7 @@ MT safe. a watch id, which can be used in connection with + line="3756">a watch id, which can be used in connection with gst_element_remove_property_notify_watch() to remove the watch again. @@ -21663,7 +22487,7 @@ MT safe. a #GstElement to watch for property changes + line="3751">a #GstElement to watch for property changes allow-none="1"> name of property to watch for changes, or + line="3752">name of property to watch for changes, or NULL to watch all properties whether to include the new property value in the message + line="3754">whether to include the new property value in the message @@ -21689,7 +22513,7 @@ MT safe. version="1.10"> Calls @func from another thread and passes @user_data to it. This is to be + line="3846">Calls @func from another thread and passes @user_data to it. This is to be used for cases when a state change has to be performed from a streaming thread, directly via gst_element_set_state() or indirectly e.g. via SEEK events. @@ -21707,7 +22531,7 @@ MT safe. a #GstElement + line="3848">a #GstElement destroy="2"> Function to call asynchronously from another thread + line="3849">Function to call asynchronously from another thread @@ -21727,7 +22551,7 @@ MT safe. allow-none="1"> Data to pass to @func + line="3850">Data to pass to @func scope="async"> GDestroyNotify for @user_data + line="3851">GDestroyNotify for @user_data @@ -21743,7 +22567,7 @@ MT safe. Perform @transition on @element. + line="3076">Perform @transition on @element. This function must be called with STATE_LOCK held and is mainly used internally. @@ -21751,20 +22575,20 @@ internally. the #GstStateChangeReturn of the state transition. + line="3086">the #GstStateChangeReturn of the state transition. a #GstElement + line="3078">a #GstElement the requested transition + line="3079">the requested transition @@ -21772,7 +22596,7 @@ internally. Commit the state change of the element and proceed to the next + line="2737">Commit the state change of the element and proceed to the next pending state if any. This function is used by elements that do asynchronous state changes. The core will normally call this method automatically when an @@ -21789,7 +22613,7 @@ This function must be called with STATE_LOCK held. The result of the commit state change. + line="2756">The result of the commit state change. MT safe. @@ -21798,13 +22622,13 @@ MT safe. a #GstElement to continue the state change of. + line="2739">a #GstElement to continue the state change of. The previous state return value + line="2740">The previous state return value @@ -21813,7 +22637,7 @@ MT safe. c:identifier="gst_element_create_all_pads"> Creates a pad for each pad template that is always available. + line="881">Creates a pad for each pad template that is always available. This function is only useful during object initialization of subclasses of #GstElement. @@ -21824,9 +22648,140 @@ subclasses of #GstElement. a #GstElement to create pads for + line="883">a #GstElement to create pads for + + + + + + Creates a stream-id for @element by combining the upstream information with +the @stream_id. + +This function generates an unique stream-id by getting the upstream +stream-start event stream ID and appending @stream_id to it. If the element +has no sinkpad it will generate an upstream stream-id by doing an URI query +on the element and in the worst case just uses a random number. Source +elements that don't implement the URI handler interface should ideally +generate a unique, deterministic stream-id manually instead. + +Since stream IDs are sorted alphabetically, any numbers in the stream ID +should be printed with a fixed number of characters, preceded by 0's, such as +by using the format \%03u instead of \%u. + + + A stream-id for @element. + + + + + The #GstElement to create a stream-id for + + + + The stream-id + + + + + + Creates a stream-id for @element by combining the upstream information with +the @format. + +This function generates an unique stream-id by getting the upstream +stream-start event stream ID and appending the stream-id to it. If the element +has no sinkpad it will generate an upstream stream-id by doing an URI query +on the element and in the worst case just uses a random number. Source +elements that don't implement the URI handler interface should ideally +generate a unique, deterministic stream-id manually instead. + +Since stream IDs are sorted alphabetically, any numbers in the stream ID +should be printed with a fixed number of characters, preceded by 0's, such as +by using the format \%03u instead of \%u. + + + A stream-id for @element. + + + + + The #GstElement to create a stream-id for + + + + The stream-id + + + + + + + + + Creates a stream-id for @element by combining the upstream information with +the @format. + +This function generates an unique stream-id by getting the upstream +stream-start event stream ID and appending @format to it. If the element +has no sinkpad it will generate an upstream stream-id by doing an URI query +on the element and in the worst case just uses a random number. Source +elements that don't implement the URI handler interface should ideally +generate a unique, deterministic stream-id manually instead. + +Since stream IDs are sorted alphabetically, any numbers in the stream ID +should be printed with a fixed number of characters, preceded by 0's, such as +by using the format \%03u instead of \%u. + + + A stream-id for @element. + + + + + The #GstElement to create a stream-id for + + The stream-id + + + + parameters for the @format string + + version="1.14"> Call @func with @user_data for each of @element's pads. @func will be called + line="1475">Call @func with @user_data for each of @element's pads. @func will be called exactly once for each pad that exists at the time of this call, unless one of the calls to @func returns %FALSE in which case we will stop iterating pads and return early. If new pads are added or pads are removed @@ -21844,7 +22799,7 @@ next time this function is used. %FALSE if @element had no pads or if one of the calls to @func + line="1488">%FALSE if @element had no pads or if one of the calls to @func returned %FALSE. @@ -21852,7 +22807,7 @@ next time this function is used. a #GstElement to iterate pads of + line="1477">a #GstElement to iterate pads of closure="1"> function to call for each pad + line="1478">function to call for each pad @@ -21871,7 +22826,7 @@ next time this function is used. allow-none="1"> user data passed to @func + line="1479">user data passed to @func @@ -21881,7 +22836,7 @@ next time this function is used. version="1.14"> Call @func with @user_data for each of @element's sink pads. @func will be + line="1423">Call @func with @user_data for each of @element's sink pads. @func will be called exactly once for each sink pad that exists at the time of this call, unless one of the calls to @func returns %FALSE in which case we will stop iterating pads and return early. If new sink pads are added or sink pads @@ -21891,7 +22846,7 @@ into account until next time this function is used. %FALSE if @element had no sink pads or if one of the calls to @func + line="1436">%FALSE if @element had no sink pads or if one of the calls to @func returned %FALSE. @@ -21899,7 +22854,7 @@ into account until next time this function is used. a #GstElement to iterate sink pads of + line="1425">a #GstElement to iterate sink pads of closure="1"> function to call for each sink pad + line="1426">function to call for each sink pad @@ -21918,7 +22873,7 @@ into account until next time this function is used. allow-none="1"> user data passed to @func + line="1427">user data passed to @func @@ -21928,7 +22883,7 @@ into account until next time this function is used. version="1.14"> Call @func with @user_data for each of @element's source pads. @func will be + line="1449">Call @func with @user_data for each of @element's source pads. @func will be called exactly once for each source pad that exists at the time of this call, unless one of the calls to @func returns %FALSE in which case we will stop iterating pads and return early. If new source pads are added or source pads @@ -21938,7 +22893,7 @@ into account until next time this function is used. %FALSE if @element had no source pads or if one of the calls + line="1462">%FALSE if @element had no source pads or if one of the calls to @func returned %FALSE. @@ -21946,7 +22901,7 @@ into account until next time this function is used. a #GstElement to iterate source pads of + line="1451">a #GstElement to iterate source pads of closure="1"> function to call for each source pad + line="1452">function to call for each source pad @@ -21965,7 +22920,7 @@ into account until next time this function is used. allow-none="1"> user data passed to @func + line="1453">user data passed to @func @@ -21973,7 +22928,7 @@ into account until next time this function is used. Returns the base time of the element. The base time is the + line="506">Returns the base time of the element. The base time is the absolute time of the clock when this element was last put to PLAYING. Subtracting the base time from the clock time gives the running time of the element. @@ -21981,7 +22936,7 @@ the running time of the element. the base time of the element. + line="515">the base time of the element. MT safe. @@ -21990,7 +22945,7 @@ MT safe. a #GstElement. + line="508">a #GstElement. @@ -21998,13 +22953,13 @@ MT safe. Returns the bus of the element. Note that only a #GstPipeline will provide a + line="3526">Returns the bus of the element. Note that only a #GstPipeline will provide a bus for the application. the element's #GstBus. unref after + line="3533">the element's #GstBus. unref after usage. MT safe. @@ -22014,7 +22969,7 @@ MT safe. a #GstElement to get the bus of. + line="3528">a #GstElement to get the bus of. @@ -22022,7 +22977,7 @@ MT safe. Gets the currently configured clock of the element. This is the clock as was + line="450">Gets the currently configured clock of the element. This is the clock as was last set with gst_element_set_clock(). Elements in a pipeline will only have their clock set when the @@ -22031,7 +22986,7 @@ pipeline is in the PLAYING state. the #GstClock of the element. unref after usage. + line="460">the #GstClock of the element. unref after usage. MT safe. @@ -22040,7 +22995,7 @@ MT safe. a #GstElement to get the clock of. + line="452">a #GstElement to get the clock of. @@ -22049,7 +23004,7 @@ MT safe. c:identifier="gst_element_get_compatible_pad"> Looks for an unlinked pad to which the given pad can link. It is not + line="1116">Looks for an unlinked pad to which the given pad can link. It is not guaranteed that linking the pads will work, though it should work in most cases. @@ -22060,7 +23015,7 @@ at the templates of @element. the #GstPad to which a link + line="1130">the #GstPad to which a link can be made, or %NULL if one cannot be found. gst_object_unref() after usage. @@ -22069,13 +23024,13 @@ at the templates of @element. a #GstElement in which the pad should be found. + line="1118">a #GstElement in which the pad should be found. the #GstPad to find a compatible one for. + line="1119">the #GstPad to find a compatible one for. allow-none="1"> the #GstCaps to use as a filter. + line="1120">the #GstCaps to use as a filter. @@ -22093,13 +23048,13 @@ at the templates of @element. c:identifier="gst_element_get_compatible_pad_template"> Retrieves a pad template from @element that is compatible with @compattempl. + line="914">Retrieves a pad template from @element that is compatible with @compattempl. Pads from compatible templates can be linked together. a compatible #GstPadTemplate, + line="923">a compatible #GstPadTemplate, or %NULL if none was found. No unreferencing is necessary. @@ -22107,13 +23062,13 @@ Pads from compatible templates can be linked together. a #GstElement to get a compatible pad template for + line="916">a #GstElement to get a compatible pad template for the #GstPadTemplate to find a compatible + line="917">the #GstPadTemplate to find a compatible template for @@ -22124,27 +23079,27 @@ Pads from compatible templates can be linked together. version="1.8"> Gets the context with @context_type set on the element or NULL. + line="3680">Gets the context with @context_type set on the element or NULL. MT safe. A #GstContext or NULL + line="3689">A #GstContext or NULL a #GstElement to get the context of. + line="3682">a #GstElement to get the context of. a name of a context to retrieve + line="3683">a name of a context to retrieve @@ -22154,25 +23109,25 @@ MT safe. version="1.8"> Gets the context with @context_type set on the element or NULL. + line="3651">Gets the context with @context_type set on the element or NULL. A #GstContext or NULL + line="3658">A #GstContext or NULL a #GstElement to get the context of. + line="3653">a #GstElement to get the context of. a name of a context to retrieve + line="3654">a name of a context to retrieve @@ -22182,14 +23137,14 @@ MT safe. version="1.8"> Gets the contexts set on the element. + line="3615">Gets the contexts set on the element. MT safe. List of #GstContext + line="3623">List of #GstContext @@ -22198,7 +23153,7 @@ MT safe. a #GstElement to set the context of. + line="3617">a #GstElement to set the context of. @@ -22208,13 +23163,13 @@ MT safe. version="1.18"> Returns the current clock time of the element, as in, the time of the + line="637">Returns the current clock time of the element, as in, the time of the element's clock, or GST_CLOCK_TIME_NONE if there is no clock. the clock time of the element, or GST_CLOCK_TIME_NONE if there is + line="644">the clock time of the element, or GST_CLOCK_TIME_NONE if there is no clock. @@ -22222,7 +23177,7 @@ no clock. a #GstElement. + line="639">a #GstElement. @@ -22232,14 +23187,14 @@ no clock. version="1.18"> Returns the running time of the element. The running time is the + line="596">Returns the running time of the element. The running time is the element's clock time minus its base time. Will return GST_CLOCK_TIME_NONE if the element has no clock, or if its base time has not been set. the running time of the element, or GST_CLOCK_TIME_NONE if the + line="604">the running time of the element, or GST_CLOCK_TIME_NONE if the element has no clock or its base time has not been set. @@ -22247,7 +23202,7 @@ element has no clock or its base time has not been set. a #GstElement. + line="598">a #GstElement. @@ -22255,12 +23210,12 @@ element has no clock or its base time has not been set. Retrieves the factory that was used to create this element. + line="3371">Retrieves the factory that was used to create this element. the #GstElementFactory used for creating this + line="3377">the #GstElementFactory used for creating this element or %NULL if element has not been registered (static element). no refcounting is needed. @@ -22268,7 +23223,7 @@ element has no clock or its base time has not been set. a #GstElement to request the element factory of. + line="3373">a #GstElement to request the element factory of. @@ -22278,25 +23233,25 @@ element has no clock or its base time has not been set. version="1.14"> Get metadata with @key in @klass. + line="1737">Get metadata with @key in @klass. the metadata for @key. + line="1744">the metadata for @key. class to get metadata for + line="1739">class to get metadata for the key to get + line="1740">the key to get @@ -22306,12 +23261,12 @@ element has no clock or its base time has not been set. version="1.14"> Retrieves a padtemplate from @element with the given name. + line="1836">Retrieves a padtemplate from @element with the given name. the #GstPadTemplate with the + line="1843">the #GstPadTemplate with the given name, or %NULL if none was found. No unreferencing is necessary. @@ -22320,13 +23275,13 @@ element has no clock or its base time has not been set. a #GstElement to get the pad template of. + line="1838">a #GstElement to get the pad template of. the name of the #GstPadTemplate to get. + line="1839">the name of the #GstPadTemplate to get. @@ -22336,13 +23291,13 @@ element has no clock or its base time has not been set. version="1.14"> Retrieves a list of the pad templates associated with @element. The + line="1778">Retrieves a list of the pad templates associated with @element. The list must not be modified by the calling code. the #GList of + line="1785">the #GList of pad templates. @@ -22352,7 +23307,7 @@ list must not be modified by the calling code. a #GstElement to get pad templates of. + line="1780">a #GstElement to get pad templates of. @@ -22363,7 +23318,7 @@ list must not be modified by the calling code. deprecated-version="1.20"> The name of this function is confusing to people learning GStreamer. + line="1187">The name of this function is confusing to people learning GStreamer. gst_element_request_pad_simple() aims at making it more explicit it is a simplified gst_element_request_pad(). Prefer using gst_element_request_pad_simple() which @@ -22372,7 +23327,7 @@ provides the exact same functionality. requested #GstPad if found, + line="1199">requested #GstPad if found, otherwise %NULL. Release after usage. @@ -22380,13 +23335,13 @@ provides the exact same functionality. a #GstElement to find a request pad of. + line="1189">a #GstElement to find a request pad of. the name of the request #GstPad to retrieve. + line="1190">the name of the request #GstPad to retrieve. @@ -22394,7 +23349,7 @@ provides the exact same functionality. Returns the start time of the element. The start time is the + line="568">Returns the start time of the element. The start time is the running time of the clock when this element was last put to PAUSED. Usually the start_time is managed by a toplevel element such as @@ -22405,14 +23360,14 @@ MT safe. the start time of the element. + line="580">the start time of the element. a #GstElement. + line="570">a #GstElement. @@ -22420,7 +23375,7 @@ MT safe. Gets the state of the element. + line="2607">Gets the state of the element. For elements that performed an ASYNC state change, as reported by gst_element_set_state(), this function will block up to the @@ -22444,7 +23399,7 @@ element to playing, the preroll will complete and playback will start. %GST_STATE_CHANGE_SUCCESS if the element has no more pending state + line="2638">%GST_STATE_CHANGE_SUCCESS if the element has no more pending state and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the element is still performing a state change or %GST_STATE_CHANGE_FAILURE if the last state change failed. @@ -22456,7 +23411,7 @@ MT safe. a #GstElement to get the state of. + line="2609">a #GstElement to get the state of. allow-none="1"> a pointer to #GstState to hold the state. + line="2610">a pointer to #GstState to hold the state. Can be %NULL. @@ -22479,14 +23434,14 @@ MT safe. allow-none="1"> a pointer to #GstState to hold the pending + line="2612">a pointer to #GstState to hold the pending state. Can be %NULL. a #GstClockTime to specify the timeout for an async + line="2614">a #GstClockTime to specify the timeout for an async state change or %GST_CLOCK_TIME_NONE for infinite timeout. @@ -22495,13 +23450,13 @@ MT safe. Retrieves a pad from @element by name. This version only retrieves + line="981">Retrieves a pad from @element by name. This version only retrieves already-existing (i.e. 'static') pads. the requested #GstPad if + line="989">the requested #GstPad if found, otherwise %NULL. unref after usage. MT safe. @@ -22511,13 +23466,13 @@ MT safe. a #GstElement to find a static pad of. + line="983">a #GstElement to find a static pad of. the name of the static #GstPad to retrieve. + line="984">the name of the static #GstPad to retrieve. @@ -22526,7 +23481,7 @@ MT safe. c:identifier="gst_element_is_locked_state"> Checks if the state of an element is locked. + line="2348">Checks if the state of an element is locked. If the state of an element is locked, state changes of the parent don't affect the element. This way you can leave currently unused elements inside bins. Just lock their @@ -22537,14 +23492,14 @@ MT safe. %TRUE, if the element's state is locked. + line="2360">%TRUE, if the element's state is locked. a #GstElement. + line="2350">a #GstElement. @@ -22552,7 +23507,7 @@ MT safe. Retrieves an iterator of @element's pads. The iterator should + line="1321">Retrieves an iterator of @element's pads. The iterator should be freed after usage. Also more specialized iterators exists such as gst_element_iterate_src_pads() or gst_element_iterate_sink_pads(). @@ -22562,7 +23517,7 @@ the pads were added to the element. the #GstIterator of #GstPad. + line="1332">the #GstIterator of #GstPad. MT safe. @@ -22571,7 +23526,7 @@ MT safe. a #GstElement to iterate pads of. + line="1323">a #GstElement to iterate pads of. @@ -22580,7 +23535,7 @@ MT safe. c:identifier="gst_element_iterate_sink_pads"> Retrieves an iterator of @element's sink pads. + line="1365">Retrieves an iterator of @element's sink pads. The order of pads returned by the iterator will be the order in which the pads were added to the element. @@ -22588,7 +23543,7 @@ the pads were added to the element. the #GstIterator of #GstPad. + line="1374">the #GstIterator of #GstPad. MT safe. @@ -22597,7 +23552,7 @@ MT safe. a #GstElement. + line="1367">a #GstElement. @@ -22606,7 +23561,7 @@ MT safe. c:identifier="gst_element_iterate_src_pads"> Retrieves an iterator of @element's source pads. + line="1344">Retrieves an iterator of @element's source pads. The order of pads returned by the iterator will be the order in which the pads were added to the element. @@ -22614,7 +23569,7 @@ the pads were added to the element. the #GstIterator of #GstPad. + line="1353">the #GstIterator of #GstPad. MT safe. @@ -22623,7 +23578,7 @@ MT safe. a #GstElement. + line="1346">a #GstElement. @@ -22913,7 +23868,7 @@ or %NULL for any pad. Brings the element to the lost state. The current state of the + line="2843">Brings the element to the lost state. The current state of the element is copied to the pending state so that any call to gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC. @@ -22937,7 +23892,7 @@ plugins or applications. a #GstElement the state is lost of + line="2845">a #GstElement the state is lost of @@ -22945,7 +23900,7 @@ plugins or applications. Post an error, warning or info message on the bus from inside an element. + line="2316">Post an error, warning or info message on the bus from inside an element. @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or #GST_MESSAGE_INFO. @@ -22959,25 +23914,25 @@ MT safe. a #GstElement to send message from + line="2318">a #GstElement to send message from the #GstMessageType + line="2319">the #GstMessageType the GStreamer GError domain this message belongs to + line="2320">the GStreamer GError domain this message belongs to the GError code belonging to the domain + line="2321">the GError code belonging to the domain allow-none="1"> an allocated text string to be used + line="2322">an allocated text string to be used as a replacement for the default message connected to code, or %NULL @@ -22997,7 +23952,7 @@ MT safe. allow-none="1"> an allocated debug message to be + line="2325">an allocated debug message to be used as a replacement for the default debugging information, or %NULL @@ -23005,19 +23960,19 @@ MT safe. the source code file where the error was generated + line="2328">the source code file where the error was generated the source code function where the error was generated + line="2329">the source code function where the error was generated the source code line where the error was generated + line="2330">the source code line where the error was generated @@ -23027,7 +23982,7 @@ MT safe. version="1.10"> Post an error, warning or info message on the bus from inside an element. + line="2212">Post an error, warning or info message on the bus from inside an element. @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or #GST_MESSAGE_INFO. @@ -23039,25 +23994,25 @@ MT safe. a #GstElement to send message from + line="2214">a #GstElement to send message from the #GstMessageType + line="2215">the #GstMessageType the GStreamer GError domain this message belongs to + line="2216">the GStreamer GError domain this message belongs to the GError code belonging to the domain + line="2217">the GError code belonging to the domain allow-none="1"> an allocated text string to be used + line="2218">an allocated text string to be used as a replacement for the default message connected to code, or %NULL @@ -23077,7 +24032,7 @@ MT safe. allow-none="1"> an allocated debug message to be + line="2221">an allocated debug message to be used as a replacement for the default debugging information, or %NULL @@ -23085,25 +24040,25 @@ MT safe. the source code file where the error was generated + line="2224">the source code file where the error was generated the source code function where the error was generated + line="2225">the source code function where the error was generated the source code line where the error was generated + line="2226">the source code line where the error was generated optional details structure + line="2227">optional details structure @@ -23111,7 +24066,7 @@ MT safe. Use this function to signal that the element does not expect any more pads + line="947">Use this function to signal that the element does not expect any more pads to show up in the current pipeline. This function should be called whenever pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES pad templates use this in combination with autopluggers to figure out that @@ -23128,7 +24083,7 @@ MT safe. a #GstElement + line="949">a #GstElement @@ -23136,14 +24091,14 @@ MT safe. Post a message on the element's #GstBus. This function takes ownership of the + line="2142">Post a message on the element's #GstBus. This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling. %TRUE if the message was successfully posted. The function returns + line="2151">%TRUE if the message was successfully posted. The function returns %FALSE if the element did not have a bus. MT safe. @@ -23153,13 +24108,13 @@ MT safe. a #GstElement posting the message + line="2144">a #GstElement posting the message a #GstMessage to post + line="2145">a #GstMessage to post @@ -23167,14 +24122,14 @@ MT safe. Get the clock provided by the given element. + line="374">Get the clock provided by the given element. > An element is only required to provide a clock in the PAUSED > state. Some elements can provide a clock in other states. the GstClock provided by the + line="382">the GstClock provided by the element or %NULL if no clock could be provided. Unref after usage. MT safe. @@ -23184,7 +24139,7 @@ MT safe. a #GstElement to query + line="376">a #GstElement to query @@ -23192,7 +24147,7 @@ MT safe. Performs a query on the given element. + line="2067">Performs a query on the given element. For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a @@ -23203,7 +24158,7 @@ Please note that some queries might need a running pipeline to work. %TRUE if the query could be performed. + line="2080">%TRUE if the query could be performed. MT safe. @@ -23212,13 +24167,13 @@ MT safe. a #GstElement to perform the query on. + line="2069">a #GstElement to perform the query on. the #GstQuery. + line="2070">the #GstQuery. @@ -23227,7 +24182,7 @@ MT safe. Queries an element to convert @src_val in @src_format to @dest_format. - + - + - + c:identifier="gst_element_release_request_pad"> Makes the element free the previously requested pad as obtained + line="338">Makes the element free the previously requested pad as obtained with gst_element_request_pad(). This does not unref the pad. If the pad was created by using @@ -23380,13 +24335,13 @@ MT safe. a #GstElement to release the request pad of. + line="340">a #GstElement to release the request pad of. the #GstPad to release. + line="341">the #GstPad to release. @@ -23394,7 +24349,7 @@ MT safe. Removes @pad from @element. @pad will be destroyed if it has not been + line="837">Removes @pad from @element. @pad will be destroyed if it has not been referenced elsewhere using gst_object_unparent(). This function is used by plugin developers and should not be used @@ -23414,7 +24369,7 @@ This function will emit the #GstElement::pad-removed signal on the element. %TRUE if the pad could be removed. Can return %FALSE if the + line="859">%TRUE if the pad could be removed. Can return %FALSE if the pad does not belong to the provided element. MT safe. @@ -23424,13 +24379,13 @@ MT safe. a #GstElement to remove pad from. + line="839">a #GstElement to remove pad from. the #GstPad to remove from the element. + line="840">the #GstPad to remove from the element. @@ -23446,13 +24401,13 @@ MT safe. a #GstElement being watched for property changes + line="3815">a #GstElement being watched for property changes watch id to remove + line="3816">watch id to remove @@ -23460,7 +24415,7 @@ MT safe. Retrieves a request pad from the element according to the provided template. + line="1278">Retrieves a request pad from the element according to the provided template. Pad templates can be looked up using gst_element_factory_get_static_pad_templates(). @@ -23469,7 +24424,7 @@ The pad should be released with gst_element_release_request_pad(). requested #GstPad if found, + line="1293">requested #GstPad if found, otherwise %NULL. Release after usage. @@ -23477,13 +24432,13 @@ The pad should be released with gst_element_release_request_pad(). a #GstElement to find a request pad of. + line="1280">a #GstElement to find a request pad of. a #GstPadTemplate of which we want a pad of. + line="1281">a #GstPadTemplate of which we want a pad of. allow-none="1"> the name of the request #GstPad + line="1282">the name of the request #GstPad to retrieve. Can be %NULL. @@ -23502,7 +24457,7 @@ to retrieve. Can be %NULL. allow-none="1"> the caps of the pad we want to + line="1284">the caps of the pad we want to request. Can be %NULL. @@ -23513,7 +24468,7 @@ request. Can be %NULL. version="1.20"> Retrieves a pad from the element by name (e.g. "src_\%d"). This version only + line="1209">Retrieves a pad from the element by name (e.g. "src_\%d"). This version only retrieves request pads. The pad should be released with gst_element_release_request_pad(). @@ -23529,7 +24484,7 @@ functionality. requested #GstPad if found, + line="1227">requested #GstPad if found, otherwise %NULL. Release after usage. @@ -23537,13 +24492,13 @@ functionality. a #GstElement to find a request pad of. + line="1211">a #GstElement to find a request pad of. the name of the request #GstPad to retrieve. + line="1212">the name of the request #GstPad to retrieve. @@ -23551,7 +24506,7 @@ functionality. Sends a seek event to an element. See gst_event_new_seek() for the details of + line="2002">Sends a seek event to an element. See gst_event_new_seek() for the details of the parameters. The seek event is sent to the element using gst_element_send_event(). @@ -23560,7 +24515,7 @@ MT safe. %TRUE if the event was handled. Flushing seeks will trigger a + line="2019">%TRUE if the event was handled. Flushing seeks will trigger a preroll, which will emit %GST_MESSAGE_ASYNC_DONE. @@ -23568,49 +24523,49 @@ preroll, which will emit %GST_MESSAGE_ASYNC_DONE. a #GstElement to send the event to. + line="2004">a #GstElement to send the event to. The new playback rate + line="2005">The new playback rate The format of the seek values + line="2006">The format of the seek values The optional seek flags. + line="2007">The optional seek flags. The type and flags for the new start position + line="2008">The type and flags for the new start position The value of the new start position + line="2009">The value of the new start position The type and flags for the new stop position + line="2010">The type and flags for the new stop position The value of the new stop position + line="2011">The value of the new stop position @@ -23674,7 +24629,7 @@ preroll, which will emit %GST_MESSAGE_ASYNC_DONE. Sends an event to an element. If the element doesn't implement an + line="1961">Sends an event to an element. If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events. @@ -23686,7 +24641,7 @@ MT safe. %TRUE if the event was handled. Events that trigger a preroll (such + line="1975">%TRUE if the event was handled. Events that trigger a preroll (such as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. @@ -23694,13 +24649,13 @@ as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. a #GstElement to send the event to. + line="1963">a #GstElement to send the event to. the #GstEvent to send to the element. + line="1964">the #GstEvent to send to the element. @@ -23708,7 +24663,7 @@ as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. Set the base time of an element. See gst_element_get_base_time(). + line="479">Set the base time of an element. See gst_element_get_base_time(). MT safe. @@ -23719,13 +24674,13 @@ MT safe. a #GstElement. + line="481">a #GstElement. the base time to set. + line="482">the base time to set. @@ -23733,7 +24688,7 @@ MT safe. Sets the bus of the element. Increases the refcount on the bus. + line="3503">Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you're testing elements. MT safe. @@ -23745,7 +24700,7 @@ MT safe. a #GstElement to set the bus of. + line="3505">a #GstElement to set the bus of. allow-none="1"> the #GstBus to set. + line="3506">the #GstBus to set. @@ -23762,14 +24717,14 @@ MT safe. Sets the clock for the element. This function increases the + line="416">Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed. %TRUE if the element accepted the clock. An element can refuse a + line="425">%TRUE if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the @clock or when it requires a specific clock to operate. @@ -23780,7 +24735,7 @@ MT safe. a #GstElement to set the clock for. + line="418">a #GstElement to set the clock for. allow-none="1"> the #GstClock to set for the element. + line="419">the #GstClock to set for the element. @@ -23797,7 +24752,7 @@ MT safe. Sets the context of the element. Increases the refcount of the context. + line="3588">Sets the context of the element. Increases the refcount of the context. MT safe. @@ -23808,13 +24763,13 @@ MT safe. a #GstElement to set the context of. + line="3590">a #GstElement to set the context of. the #GstContext to set. + line="3591">the #GstContext to set. @@ -23823,7 +24778,7 @@ MT safe. c:identifier="gst_element_set_locked_state"> Locks the state of an element, so state changes of the parent don't affect + line="2376">Locks the state of an element, so state changes of the parent don't affect this element anymore. Note that this is racy if the state lock of the parent bin is not taken. @@ -23835,7 +24790,7 @@ MT safe. %TRUE if the state was changed, %FALSE if bad parameters were given + line="2390">%TRUE if the state was changed, %FALSE if bad parameters were given or the elements state-locking needed no change. @@ -23843,13 +24798,13 @@ or the elements state-locking needed no change. a #GstElement + line="2378">a #GstElement %TRUE to lock the element's state + line="2379">%TRUE to lock the element's state @@ -23857,7 +24812,7 @@ or the elements state-locking needed no change. Set the start time of an element. The start time of the element is the + line="533">Set the start time of an element. The start time of the element is the running time of the element when it last went to the PAUSED state. In READY or after a flushing seek, it is set to 0. @@ -23877,13 +24832,13 @@ MT safe. a #GstElement. + line="535">a #GstElement. the base time to set. + line="536">the base time to set. @@ -23891,7 +24846,7 @@ MT safe. Sets the state of the element. This function will try to set the + line="2921">Sets the state of the element. This function will try to set the requested state by going through all the intermediary states and calling the class's state change function for each. @@ -23908,7 +24863,7 @@ State changes to %GST_STATE_READY or %GST_STATE_NULL never return Result of the state change using #GstStateChangeReturn. + line="2940">Result of the state change using #GstStateChangeReturn. MT safe. @@ -23917,13 +24872,13 @@ MT safe. a #GstElement to change state of. + line="2923">a #GstElement to change state of. the element's new #GstState. + line="2924">the element's new #GstState. @@ -23932,13 +24887,13 @@ MT safe. c:identifier="gst_element_sync_state_with_parent"> Tries to change the state of the element to the same as its parent. + line="2430">Tries to change the state of the element to the same as its parent. If this function returns %FALSE, the state of element is undefined. %TRUE, if the element's state could be synced to the parent's state. + line="2437">%TRUE, if the element's state could be synced to the parent's state. MT safe. @@ -23947,7 +24902,7 @@ MT safe. a #GstElement. + line="2432">a #GstElement. @@ -24193,7 +25148,7 @@ state will yield the running_time against the clock. This signals that the element will not generate more dynamic pads. + line="255">This signals that the element will not generate more dynamic pads. Note that this signal will usually be emitted from the context of the streaming thread. @@ -24203,7 +25158,7 @@ the streaming thread. a new #GstPad has been added to the element. Note that this signal will + line="229">a new #GstPad has been added to the element. Note that this signal will usually be emitted from the context of the streaming thread. Also keep in mind that if you add new elements to the pipeline in the signal handler you will need to set them to the desired target state with @@ -24215,7 +25170,7 @@ gst_element_set_state() or gst_element_sync_state_with_parent(). the pad that has been added + line="232">the pad that has been added @@ -24223,7 +25178,7 @@ gst_element_set_state() or gst_element_sync_state_with_parent(). a #GstPad has been removed from the element + line="244">a #GstPad has been removed from the element @@ -24231,7 +25186,7 @@ gst_element_set_state() or gst_element_sync_state_with_parent(). the pad that has been removed + line="247">the pad that has been removed @@ -24352,19 +25307,22 @@ functionality. a #GstElement + line="949">a #GstElement + called when a new pad is requested requested #GstPad if found, + line="1293">requested #GstPad if found, otherwise %NULL. Release after usage. @@ -24372,13 +25330,13 @@ functionality. a #GstElement to find a request pad of. + line="1280">a #GstElement to find a request pad of. a #GstPadTemplate of which we want a pad of. + line="1281">a #GstPadTemplate of which we want a pad of. allow-none="1"> the name of the request #GstPad + line="1282">the name of the request #GstPad to retrieve. Can be %NULL. @@ -24397,7 +25355,7 @@ to retrieve. Can be %NULL. allow-none="1"> the caps of the pad we want to + line="1284">the caps of the pad we want to request. Can be %NULL. @@ -24405,6 +25363,9 @@ request. Can be %NULL. + called when a request pad is to be released @@ -24421,12 +25382,15 @@ request. Can be %NULL. + get the state of the element %GST_STATE_CHANGE_SUCCESS if the element has no more pending state + line="2638">%GST_STATE_CHANGE_SUCCESS if the element has no more pending state and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the element is still performing a state change or %GST_STATE_CHANGE_FAILURE if the last state change failed. @@ -24438,7 +25402,7 @@ MT safe. a #GstElement to get the state of. + line="2609">a #GstElement to get the state of. allow-none="1"> a pointer to #GstState to hold the state. + line="2610">a pointer to #GstState to hold the state. Can be %NULL. @@ -24461,14 +25425,14 @@ MT safe. allow-none="1"> a pointer to #GstState to hold the pending + line="2612">a pointer to #GstState to hold the pending state. Can be %NULL. a #GstClockTime to specify the timeout for an async + line="2614">a #GstClockTime to specify the timeout for an async state change or %GST_CLOCK_TIME_NONE for infinite timeout. @@ -24476,12 +25440,15 @@ MT safe. + set a new state on the element Result of the state change using #GstStateChangeReturn. + line="2940">Result of the state change using #GstStateChangeReturn. MT safe. @@ -24490,44 +25457,50 @@ MT safe. a #GstElement to change state of. + line="2923">a #GstElement to change state of. the element's new #GstState. + line="2924">the element's new #GstState. + called by @set_state to perform an incremental state change the #GstStateChangeReturn of the state transition. + line="3086">the #GstStateChangeReturn of the state transition. a #GstElement + line="3078">a #GstElement the requested transition + line="3079">the requested transition + called immediately after a new state was set. @@ -24550,6 +25523,9 @@ MT safe. + set a #GstBus on the element @@ -24559,7 +25535,7 @@ MT safe. a #GstElement to set the bus of. + line="3505">a #GstElement to set the bus of. allow-none="1"> the #GstBus to set. + line="3506">the #GstBus to set. + gets the #GstClock provided by the element the GstClock provided by the + line="382">the GstClock provided by the element or %NULL if no clock could be provided. Unref after usage. MT safe. @@ -24590,19 +25569,22 @@ MT safe. a #GstElement to query + line="376">a #GstElement to query + set the #GstClock on the element %TRUE if the element accepted the clock. An element can refuse a + line="425">%TRUE if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the @clock or when it requires a specific clock to operate. @@ -24613,7 +25595,7 @@ MT safe. a #GstElement to set the clock for. + line="418">a #GstElement to set the clock for. allow-none="1"> the #GstClock to set for the element. + line="419">the #GstClock to set for the element. + send a #GstEvent to the element %TRUE if the event was handled. Events that trigger a preroll (such + line="1975">%TRUE if the event was handled. Events that trigger a preroll (such as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. @@ -24642,25 +25627,28 @@ as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. a #GstElement to send the event to. + line="1963">a #GstElement to send the event to. the #GstEvent to send to the element. + line="1964">the #GstEvent to send to the element. + perform a #GstQuery on the element %TRUE if the query could be performed. + line="2080">%TRUE if the query could be performed. MT safe. @@ -24669,25 +25657,29 @@ MT safe. a #GstElement to perform the query on. + line="2069">a #GstElement to perform the query on. the #GstQuery. + line="2070">the #GstQuery. + called when a message is posted on the element. Chain up to + the parent class' handler to have it posted on the bus. %TRUE if the message was successfully posted. The function returns + line="2151">%TRUE if the message was successfully posted. The function returns %FALSE if the element did not have a bus. MT safe. @@ -24697,19 +25689,22 @@ MT safe. a #GstElement posting the message + line="2144">a #GstElement posting the message a #GstMessage to post + line="2145">a #GstMessage to post + set a #GstContext on the element @@ -24719,13 +25714,13 @@ MT safe. a #GstElement to set the context of. + line="3590">a #GstElement to set the context of. the #GstContext to set. + line="3591">the #GstContext to set. @@ -24740,7 +25735,7 @@ MT safe. c:identifier="gst_element_class_add_metadata"> Set @key with @value as metadata in @klass. + line="1587">Set @key with @value as metadata in @klass. @@ -24749,19 +25744,19 @@ MT safe. class to set metadata for + line="1589">class to set metadata for the key to set + line="1590">the key to set the value to set + line="1591">the value to set @@ -24770,7 +25765,7 @@ MT safe. c:identifier="gst_element_class_add_pad_template"> Adds a padtemplate to an element class. This is mainly used in the _class_init + line="1501">Adds a padtemplate to an element class. This is mainly used in the _class_init functions of classes. If a pad template with the same name as an already existing one is added the old one is replaced by the new one. @@ -24784,13 +25779,13 @@ reference will be removed (see gst_object_ref_sink()) the #GstElementClass to add the pad template to. + line="1503">the #GstElementClass to add the pad template to. a #GstPadTemplate to add to the element class. + line="1504">a #GstPadTemplate to add to the element class. @@ -24799,7 +25794,7 @@ reference will be removed (see gst_object_ref_sink()) c:identifier="gst_element_class_add_static_metadata"> Set @key with @value as metadata in @klass. + line="1607">Set @key with @value as metadata in @klass. Same as gst_element_class_add_metadata(), but @value must be a static string or an inlined string, as it will not be copied. (GStreamer plugins will @@ -24813,19 +25808,19 @@ dynamically loaded plugins.) class to set metadata for + line="1609">class to set metadata for the key to set + line="1610">the key to set the value to set + line="1611">the value to set @@ -24835,7 +25830,7 @@ dynamically loaded plugins.) version="1.8"> Adds a pad template to an element class based on the static pad template + line="1545">Adds a pad template to an element class based on the static pad template @templ. This is mainly used in the _class_init functions of element implementations. If a pad template with the same name already exists, the old one is replaced by the new one. @@ -24847,13 +25842,13 @@ the old one is replaced by the new one. the #GstElementClass to add the pad template to. + line="1547">the #GstElementClass to add the pad template to. #GstStaticPadTemplate to add as pad template to the element class. + line="1548">#GstStaticPadTemplate to add as pad template to the element class. @@ -24863,7 +25858,7 @@ the old one is replaced by the new one. version="1.14"> Adds a pad template to an element class based on the static pad template + line="1565">Adds a pad template to an element class based on the static pad template @templ. This is mainly used in the _class_init functions of element implementations. If a pad template with the same name already exists, the old one is replaced by the new one. @@ -24875,19 +25870,19 @@ the old one is replaced by the new one. the #GstElementClass to add the pad template to. + line="1567">the #GstElementClass to add the pad template to. #GstStaticPadTemplate to add as pad template to the element class. + line="1568">#GstStaticPadTemplate to add as pad template to the element class. The #GType of the pad to create + line="1569">The #GType of the pad to create @@ -24896,25 +25891,25 @@ the old one is replaced by the new one. c:identifier="gst_element_class_get_metadata"> Get metadata with @key in @klass. + line="1719">Get metadata with @key in @klass. the metadata for @key. + line="1726">the metadata for @key. class to get metadata for + line="1721">class to get metadata for the key to get + line="1722">the key to get @@ -24923,7 +25918,7 @@ the old one is replaced by the new one. c:identifier="gst_element_class_get_pad_template"> Retrieves a padtemplate from @element_class with the given name. + line="1799">Retrieves a padtemplate from @element_class with the given name. > If you use this function in the GInstanceInitFunc of an object class > that has subclasses, make sure to pass the g_class parameter of the > GInstanceInitFunc here. @@ -24931,7 +25926,7 @@ the old one is replaced by the new one. the #GstPadTemplate with the + line="1809">the #GstPadTemplate with the given name, or %NULL if none was found. No unreferencing is necessary. @@ -24940,13 +25935,13 @@ the old one is replaced by the new one. a #GstElementClass to get the pad template of. + line="1801">a #GstElementClass to get the pad template of. the name of the #GstPadTemplate to get. + line="1802">the name of the #GstPadTemplate to get. @@ -24955,7 +25950,7 @@ the old one is replaced by the new one. c:identifier="gst_element_class_get_pad_template_list"> Retrieves a list of the pad templates associated with @element_class. The + line="1757">Retrieves a list of the pad templates associated with @element_class. The list must not be modified by the calling code. > If you use this function in the GInstanceInitFunc of an object class > that has subclasses, make sure to pass the g_class parameter of the @@ -24964,7 +25959,7 @@ list must not be modified by the calling code. the #GList of + line="1767">the #GList of pad templates. @@ -24974,7 +25969,7 @@ list must not be modified by the calling code. a #GstElementClass to get pad templates of. + line="1759">a #GstElementClass to get pad templates of. @@ -24983,7 +25978,7 @@ list must not be modified by the calling code. c:identifier="gst_element_class_set_metadata"> Sets the detailed information for a #GstElementClass. + line="1635">Sets the detailed information for a #GstElementClass. > This function is for use in _class_init functions only. @@ -24993,19 +25988,19 @@ list must not be modified by the calling code. class to set metadata for + line="1637">class to set metadata for The long English name of the element. E.g. "File Sink" + line="1638">The long English name of the element. E.g. "File Sink" String describing the type of element, as an unordered list + line="1639">String describing the type of element, as an unordered list separated with slashes ('/'). See draft-klass.txt of the design docs for more details and common types. E.g: "Sink/File" @@ -25013,14 +26008,14 @@ for more details and common types. E.g: "Sink/File" Sentence describing the purpose of the element. + line="1642">Sentence describing the purpose of the element. E.g: "Write stream to a file" Name and contact details of the author(s). Use \n to separate + line="1644">Name and contact details of the author(s). Use \n to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" @@ -25030,7 +26025,7 @@ multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" c:identifier="gst_element_class_set_static_metadata"> Sets the detailed information for a #GstElementClass. + line="1668">Sets the detailed information for a #GstElementClass. > This function is for use in _class_init functions only. @@ -25046,19 +26041,19 @@ loaded, so this function can be used even from dynamically loaded plugins.) class to set metadata for + line="1670">class to set metadata for The long English name of the element. E.g. "File Sink" + line="1671">The long English name of the element. E.g. "File Sink" String describing the type of element, as an unordered list + line="1672">String describing the type of element, as an unordered list separated with slashes ('/'). See draft-klass.txt of the design docs for more details and common types. E.g: "Sink/File" @@ -25066,14 +26061,14 @@ for more details and common types. E.g: "Sink/File" Sentence describing the purpose of the element. + line="1675">Sentence describing the purpose of the element. E.g: "Write stream to a file" Name and contact details of the author(s). Use \n to separate + line="1677">Name and contact details of the author(s). Use \n to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" @@ -25141,17 +26136,17 @@ element factory; caller is responsible for unreffing. c:identifier="gst_element_factory_list_filter"> Filter out all the elementfactories in @list that can handle @caps in + line="1182">Filter out all the elementfactories in @list that can handle @caps in the given direction. If @subsetonly is %TRUE, then only the elements whose pads templates are a complete superset of @caps will be returned. Else any element whose pad templates caps can intersect with @caps will be returned. - + a #GList of + line="1197">a #GList of #GstElementFactory elements that match the given requisites. Use #gst_plugin_feature_list_free after usage. @@ -25162,7 +26157,7 @@ whose pad templates caps can intersect with @caps will be returned. a #GList of + line="1184">a #GList of #GstElementFactory to filter @@ -25171,19 +26166,19 @@ whose pad templates caps can intersect with @caps will be returned. a #GstCaps + line="1186">a #GstCaps a #GstPadDirection to filter on + line="1187">a #GstPadDirection to filter on whether to filter on caps subsets or not. + line="1188">whether to filter on caps subsets or not. @@ -25192,14 +26187,14 @@ whose pad templates caps can intersect with @caps will be returned. c:identifier="gst_element_factory_list_get_elements"> Get a list of factories that match the given @type. Only elements + line="1148">Get a list of factories that match the given @type. Only elements with a rank greater or equal to @minrank will be returned. The list of factories is returned by decreasing rank. - + a #GList of + line="1157">a #GList of #GstElementFactory elements. Use gst_plugin_feature_list_free() after usage. @@ -25210,14 +26205,14 @@ The list of factories is returned by decreasing rank. a #GstElementFactoryListType + line="1150">a #GstElementFactoryListType Minimum rank + line="1151">Minimum rank @@ -25399,7 +26394,7 @@ The supplied list of properties, will be passed at object construction. Checks if the factory can sink all possible capabilities. - + Checks if the factory can sink any possible capability. - + Checks if the factory can src all possible capabilities. - + Checks if the factory can src any possible capability. - + Check if @factory is of the given types. - + Create a new buffersize event. The event is sent downstream and notifies + line="1103">Create a new buffersize event. The event is sent downstream and notifies elements that they should provide a buffer of the specified dimensions. When the @async flag is set, a thread boundary is preferred. @@ -26124,32 +27119,32 @@ When the @async flag is set, a thread boundary is preferred. a new #GstEvent + line="1115">a new #GstEvent buffer format + line="1105">buffer format minimum buffer size + line="1106">minimum buffer size maximum buffer size + line="1107">maximum buffer size thread behavior + line="1108">thread behavior @@ -26157,21 +27152,21 @@ When the @async flag is set, a thread boundary is preferred. Create a new CAPS event for @caps. The caps event can only travel downstream + line="894">Create a new CAPS event for @caps. The caps event can only travel downstream synchronized with the buffer flow and contains the format of the buffers that will follow after the event. the new CAPS event. + line="902">the new CAPS event. a #GstCaps + line="896">a #GstCaps @@ -26179,7 +27174,7 @@ that will follow after the event. Create a new custom-typed event. This can be used for anything not + line="310">Create a new custom-typed event. This can be used for anything not handled by other event-specific functions to pass an event to another element. @@ -26193,20 +27188,20 @@ needed. the new custom event. + line="327">the new custom event. The type of the new event + line="312">The type of the new event the structure for the event. The event will + line="313">the structure for the event. The event will take ownership of the structure. @@ -26215,7 +27210,7 @@ needed. Create a new EOS event. The eos event can only travel downstream + line="766">Create a new EOS event. The eos event can only travel downstream synchronized with the buffer flow. Elements that receive the EOS event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn when data after the EOS event arrives. @@ -26232,7 +27227,7 @@ The EOS event itself will not cause any state transitions of the pipeline. the new EOS event. + line="783">the new EOS event. @@ -26240,7 +27235,7 @@ The EOS event itself will not cause any state transitions of the pipeline. c:identifier="gst_event_new_flush_start"> Allocate a new flush start event. The flush start event can be sent + line="557">Allocate a new flush start event. The flush start event can be sent upstream and downstream and travels out-of-bounds with the dataflow. It marks pads as being flushing and will make them return @@ -26258,7 +27253,7 @@ in the pipeline so that the new media is played as soon as possible. a new flush start event. + line="575">a new flush start event. @@ -26266,7 +27261,7 @@ in the pipeline so that the new media is played as soon as possible. c:identifier="gst_event_new_flush_stop"> Allocate a new flush stop event. The flush stop event can be sent + line="583">Allocate a new flush stop event. The flush stop event can be sent upstream and downstream and travels serialized with the dataflow. It is typically sent after sending a FLUSH_START event to make the pads accept data again. @@ -26280,14 +27275,14 @@ dataflow. a new flush stop event. + line="598">a new flush stop event. if time should be reset + line="585">if time should be reset @@ -26295,7 +27290,7 @@ dataflow. Create a new GAP event. A gap event can be thought of as conceptually + line="791">Create a new GAP event. A gap event can be thought of as conceptually equivalent to a buffer to signal that there is no data for a certain amount of time. This is useful to signal a gap to downstream elements which may wait for data, such as muxers or mixers or overlays, especially @@ -26304,20 +27299,20 @@ for sparse streams such as subtitle streams. the new GAP event. + line="802">the new GAP event. the start time (pts) of the gap + line="793">the start time (pts) of the gap the duration of the gap + line="794">the duration of the gap @@ -26327,7 +27322,7 @@ for sparse streams such as subtitle streams. version="1.18"> Create a new instant-rate-change event. This event is sent by seek + line="2247">Create a new instant-rate-change event. This event is sent by seek handlers (e.g. demuxers) when receiving a seek with the %GST_SEEK_FLAG_INSTANT_RATE_CHANGE and signals to downstream elements that the playback rate in the existing segment should be immediately multiplied @@ -26340,20 +27335,20 @@ are ignored and not transferred in the event. the new instant-rate-change event. + line="2262">the new instant-rate-change event. the multiplier to be applied to the playback rate + line="2249">the multiplier to be applied to the playback rate A new subset of segment flags to replace in segments + line="2250">A new subset of segment flags to replace in segments @@ -26363,7 +27358,7 @@ are ignored and not transferred in the event. version="1.18"> Create a new instant-rate-sync-time event. This event is sent by the + line="2313">Create a new instant-rate-sync-time event. This event is sent by the pipeline to notify elements handling the instant-rate-change event about the running-time when the new rate should be applied. The running time may be in the past when elements handle this event, which can lead to @@ -26379,26 +27374,26 @@ different to the one indicated in the playback segments. the new instant-rate-sync-time event. + line="2333">the new instant-rate-sync-time event. the new playback rate multiplier to be applied + line="2315">the new playback rate multiplier to be applied Running time when the rate change should be applied + line="2316">Running time when the rate change should be applied The upstream-centric running-time when the + line="2317">The upstream-centric running-time when the rate change should be applied. @@ -26407,7 +27402,7 @@ different to the one indicated in the playback segments. Create a new latency event. The event is sent upstream from the sinks and + line="1505">Create a new latency event. The event is sent upstream from the sinks and notifies elements that they should add an additional @latency to the running time before synchronising against the clock. @@ -26417,14 +27412,14 @@ the time format. a new #GstEvent + line="1516">a new #GstEvent the new latency value + line="1507">the new latency value @@ -26433,19 +27428,19 @@ the time format. c:identifier="gst_event_new_navigation"> Create a new navigation event from the given description. + line="1487">Create a new navigation event from the given description. a new #GstEvent + line="1495">a new #GstEvent description of the event. The event will take + line="1489">description of the event. The event will take ownership of the structure. See #GstNavigation for more specific constructors. @@ -26457,7 +27452,7 @@ the time format. version="1.6"> Creates a new event containing information specific to a particular + line="2078">Creates a new event containing information specific to a particular protection system (uniquely identified by @system_id), by which that protection system can acquire key(s) to decrypt a protected stream. @@ -26490,28 +27485,28 @@ be stuck to the output pad of the sending element. a #GST_EVENT_PROTECTION event. + line="2118">a #GST_EVENT_PROTECTION event. a string holding a UUID that uniquely + line="2080">a string holding a UUID that uniquely identifies a protection system. a #GstBuffer holding protection system specific + line="2082">a #GstBuffer holding protection system specific information. The reference count of the buffer will be incremented by one. a string indicating where the protection + line="2084">a string indicating where the protection information carried in the event was extracted from. The allowed values of this string will depend upon the protection scheme. @@ -26521,7 +27516,7 @@ of this string will depend upon the protection scheme. Allocate a new qos event with the given values. + line="1171">Allocate a new qos event with the given values. The QOS event is generated in an element that wants an upstream element to either reduce or increase its rate because of high/low CPU load or other resource usage such as network performance or @@ -26567,32 +27562,32 @@ event and implement custom application specific QoS handling. a new QOS event. + line="1221">a new QOS event. the QoS type + line="1173">the QoS type the proportion of the qos message + line="1174">the proportion of the qos message The time difference of the last Clock sync + line="1175">The time difference of the last Clock sync The timestamp of the buffer + line="1176">The timestamp of the buffer @@ -26601,7 +27596,7 @@ event and implement custom application specific QoS handling. c:identifier="gst_event_new_reconfigure"> Create a new reconfigure event. The purpose of the reconfigure event is + line="1639">Create a new reconfigure event. The purpose of the reconfigure event is to travel upstream and make elements renegotiate their caps or reconfigure their buffer pools. This is useful when changing properties on elements or changing the topology of the pipeline. @@ -26609,14 +27604,14 @@ or changing the topology of the pipeline. a new #GstEvent + line="1647">a new #GstEvent Allocate a new seek event with the given parameters. + line="1299">Allocate a new seek event with the given parameters. The seek event configures playback of the pipeline between @start to @stop at the speed given in @rate, also called a playback segment. @@ -26651,50 +27646,50 @@ this, PAUSE the pipeline, query the current playback position with a new seek event. + line="1341">a new seek event. The new playback rate + line="1301">The new playback rate The format of the seek values + line="1302">The format of the seek values The optional seek flags + line="1303">The optional seek flags The type and flags for the new start position + line="1304">The type and flags for the new start position The value of the new start position + line="1305">The value of the new start position The type and flags for the new stop position + line="1306">The type and flags for the new stop position The value of the new stop position + line="1307">The value of the new stop position @@ -26702,7 +27697,7 @@ this, PAUSE the pipeline, query the current playback position with Create a new SEGMENT event for @segment. The segment event can only travel + line="942">Create a new SEGMENT event for @segment. The segment event can only travel downstream synchronized with the buffer flow and contains timing information and playback properties for the buffers that will follow. @@ -26737,14 +27732,14 @@ After a segment event, the buffer stream time is calculated with: the new SEGMENT event. + line="978">the new SEGMENT event. a #GstSegment + line="944">a #GstSegment @@ -26753,26 +27748,26 @@ After a segment event, the buffer stream time is calculated with: c:identifier="gst_event_new_segment_done"> Create a new segment-done event. This event is sent by elements that + line="2190">Create a new segment-done event. This event is sent by elements that finish playback of a segment as a result of a segment seek. a new #GstEvent + line="2198">a new #GstEvent The format of the position being done + line="2192">The format of the position being done The position of the segment being done + line="2193">The position of the segment being done @@ -26782,7 +27777,7 @@ finish playback of a segment as a result of a segment seek. version="1.10"> Allocate a new select-streams event. + line="635">Allocate a new select-streams event. The select-streams event requests the specified @streams to be activated. @@ -26796,14 +27791,14 @@ Note: The list of @streams can not be empty. a new select-streams event. + line="651">a new select-streams event. the list of streams to + line="637">the list of streams to activate @@ -26815,7 +27810,7 @@ activate c:identifier="gst_event_new_sink_message"> Create a new sink-message event. The purpose of the sink-message event is + line="1661">Create a new sink-message event. The purpose of the sink-message event is to instruct a sink to post the message contained in the event synchronized with the stream. @@ -26824,20 +27819,20 @@ with the stream. a new #GstEvent + line="1672">a new #GstEvent a name for the event + line="1663">a name for the event the #GstMessage to be posted + line="1664">the #GstMessage to be posted @@ -26845,7 +27840,7 @@ with the stream. Create a new step event. The purpose of the step event is to instruct a sink + line="1555">Create a new step event. The purpose of the step event is to instruct a sink to skip @amount (expressed in @format) of media. It can be used to implement stepping through the video frame by frame or for doing fast trick modes. @@ -26862,38 +27857,38 @@ part of a larger step operation. a new #GstEvent + line="1577">a new #GstEvent the format of @amount + line="1557">the format of @amount the amount of data to step + line="1558">the amount of data to step the step rate + line="1559">the step rate flushing steps + line="1560">flushing steps intermediate steps + line="1561">intermediate steps @@ -26903,7 +27898,7 @@ part of a larger step operation. version="1.10"> Create a new STREAM_COLLECTION event. The stream collection event can only + line="1916">Create a new STREAM_COLLECTION event. The stream collection event can only travel downstream synchronized with the buffer flow. Source elements, demuxers and other elements that manage collections @@ -26915,14 +27910,14 @@ data flow. the new STREAM_COLLECTION event. + line="1929">the new STREAM_COLLECTION event. Active collection for this data flow + line="1918">Active collection for this data flow @@ -26932,7 +27927,7 @@ data flow. version="1.10"> Create a new Stream Group Done event. The stream-group-done event can + line="713">Create a new Stream Group Done event. The stream-group-done event can only travel downstream synchronized with the buffer flow. Elements that receive the event on a pad should handle it mostly like EOS, and emit any data or pending buffers that would depend on more data @@ -26945,14 +27940,14 @@ new pads can be exposed before sending EOS on the existing pads. the new stream-group-done event. + line="727">the new stream-group-done event. the group id of the stream group which is ending + line="715">the group id of the stream group which is ending @@ -26961,7 +27956,7 @@ new pads can be exposed before sending EOS on the existing pads. c:identifier="gst_event_new_stream_start"> Create a new STREAM_START event. The stream start event can only + line="1715">Create a new STREAM_START event. The stream start event can only travel downstream synchronized with the buffer flow. It is expected to be the first event that is sent for a new stream. @@ -26986,14 +27981,14 @@ stream flags). the new STREAM_START event. + line="1741">the new STREAM_START event. Identifier for this stream + line="1717">Identifier for this stream @@ -27001,7 +27996,7 @@ stream flags). Generates a metadata tag event from the given @taglist. + line="1046">Generates a metadata tag event from the given @taglist. The scope of the taglist specifies if the taglist applies to the complete medium or only to this specific stream. As the tag event @@ -27012,14 +28007,14 @@ scope and create a new tag event from it. a new #GstEvent + line="1059">a new #GstEvent metadata list. The event will take ownership + line="1048">metadata list. The event will take ownership of the taglist. @@ -27028,26 +28023,26 @@ scope and create a new tag event from it. Generate a TOC event from the given @toc. The purpose of the TOC event is to + line="1973">Generate a TOC event from the given @toc. The purpose of the TOC event is to inform elements that some kind of the TOC was found. a new #GstEvent. + line="1981">a new #GstEvent. #GstToc structure. + line="1975">#GstToc structure. whether @toc was updated or not. + line="1976">whether @toc was updated or not. @@ -27056,21 +28051,21 @@ inform elements that some kind of the TOC was found. c:identifier="gst_event_new_toc_select"> Generate a TOC select event with the given @uid. The purpose of the + line="2029">Generate a TOC select event with the given @uid. The purpose of the TOC select event is to start playback based on the TOC's entry with the given @uid. a new #GstEvent. + line="2037">a new #GstEvent. UID in the TOC to start playback from. + line="2031">UID in the TOC to start playback from. @@ -27078,7 +28073,7 @@ given @uid. Parses a segment @event and copies the #GstSegment into the location + line="1024">Parses a segment @event and copies the #GstSegment into the location given by @segment. @@ -27088,13 +28083,13 @@ given by @segment. The event to parse + line="1026">The event to parse a pointer to a #GstSegment + line="1027">a pointer to a #GstSegment @@ -27104,7 +28099,7 @@ given by @segment. version="1.4"> Retrieve the accumulated running time offset of the event. + line="508">Retrieve the accumulated running time offset of the event. Events passing through #GstPads that have a running time offset set via gst_pad_set_offset() will get their offset @@ -27117,7 +28112,7 @@ before usage with this offset. The event's running time offset + line="522">The event's running time offset MT safe. @@ -27126,7 +28121,7 @@ MT safe. A #GstEvent. + line="510">A #GstEvent. @@ -27134,7 +28129,7 @@ MT safe. Retrieve the sequence number of a event. + line="456">Retrieve the sequence number of a event. Events have ever-incrementing sequence numbers, which may also be set explicitly via gst_event_set_seqnum(). Sequence numbers are typically used to @@ -27150,7 +28145,7 @@ that correspondence was made explicitly. The event's sequence number. + line="473">The event's sequence number. MT safe. @@ -27159,7 +28154,7 @@ MT safe. A #GstEvent. + line="458">A #GstEvent. @@ -27167,12 +28162,12 @@ MT safe. Access the structure of the event. + line="361">Access the structure of the event. The structure of the event. The + line="367">The structure of the event. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event. @@ -27183,7 +28178,7 @@ MT safe. The #GstEvent. + line="363">The #GstEvent. @@ -27191,55 +28186,58 @@ MT safe. Checks if @event has the given @name. This function is usually used to + line="415">Checks if @event has the given @name. This function is usually used to check the name of a custom event. %TRUE if @name matches the name of the event structure. + line="423">%TRUE if @name matches the name of the event structure. The #GstEvent. + line="417">The #GstEvent. name to check + line="418">name to check + version="1.18" + deprecated="1" + deprecated-version="1.26"> Checks if @event has the given @name. This function is usually used to + line="436">Checks if @event has the given @name. This function is usually used to check the name of a custom event. + Use gst_event_has_name(). %TRUE if @name matches the name of the event structure. + line="444">%TRUE if @name matches the name of the event structure. The #GstEvent. + line="438">The #GstEvent. name to check as a GQuark + line="439">name to check as a GQuark @@ -27248,7 +28246,7 @@ check the name of a custom event. c:identifier="gst_event_parse_buffer_size"> Get the format, minsize, maxsize and async-flag in the buffersize event. + line="1138">Get the format, minsize, maxsize and async-flag in the buffersize event. @@ -27257,7 +28255,7 @@ check the name of a custom event. The event to query + line="1140">The event to query allow-none="1"> A pointer to store the format in + line="1141">A pointer to store the format in allow-none="1"> A pointer to store the minsize in + line="1142">A pointer to store the minsize in allow-none="1"> A pointer to store the maxsize in + line="1143">A pointer to store the maxsize in allow-none="1"> A pointer to store the async-flag in + line="1144">A pointer to store the async-flag in @@ -27309,7 +28307,7 @@ check the name of a custom event. Get the caps from @event. The caps remains valid as long as @event remains + line="921">Get the caps from @event. The caps remains valid as long as @event remains valid. @@ -27319,7 +28317,7 @@ valid. The event to parse + line="923">The event to parse allow-none="1"> A pointer to the caps + line="924">A pointer to the caps @@ -27339,7 +28337,7 @@ valid. c:identifier="gst_event_parse_flush_stop"> Parse the FLUSH_STOP event and retrieve the @reset_time member. + line="614">Parse the FLUSH_STOP event and retrieve the @reset_time member. @@ -27348,7 +28346,7 @@ valid. The event to parse + line="616">The event to parse allow-none="1"> if time should be reset + line="617">if time should be reset @@ -27367,7 +28365,7 @@ valid. Extract timestamp and duration from a new GAP event. + line="824">Extract timestamp and duration from a new GAP event. @@ -27376,7 +28374,7 @@ valid. a #GstEvent of type #GST_EVENT_GAP + line="826">a #GstEvent of type #GST_EVENT_GAP allow-none="1"> location where to store the + line="827">location where to store the start time (pts) of the gap, or %NULL @@ -27399,7 +28397,7 @@ valid. allow-none="1"> location where to store the duration of + line="829">location where to store the duration of the gap, or %NULL @@ -27410,7 +28408,7 @@ valid. version="1.20"> Retrieve the gap flags that may have been set on a gap event with + line="870">Retrieve the gap flags that may have been set on a gap event with gst_event_set_gap_flags(). @@ -27420,7 +28418,7 @@ gst_event_set_gap_flags(). a #GstEvent of type #GST_EVENT_GAP + line="872">a #GstEvent of type #GST_EVENT_GAP allow-none="1"> a #GstGapFlags or %NULL + line="873">a #GstGapFlags or %NULL @@ -27443,7 +28441,7 @@ gst_event_set_gap_flags(). %TRUE if a group id was set on the event and could be parsed, + line="1895">%TRUE if a group id was set on the event and could be parsed, %FALSE otherwise. @@ -27451,7 +28449,7 @@ gst_event_set_gap_flags(). a stream-start event + line="1892">a stream-start event allow-none="1"> address of variable where to store the group id + line="1893">address of variable where to store the group id @@ -27472,7 +28470,7 @@ gst_event_set_gap_flags(). version="1.18"> Extract rate and flags from an instant-rate-change event. + line="2287">Extract rate and flags from an instant-rate-change event. @@ -27481,7 +28479,7 @@ gst_event_set_gap_flags(). a #GstEvent of type #GST_EVENT_INSTANT_RATE_CHANGE + line="2289">a #GstEvent of type #GST_EVENT_INSTANT_RATE_CHANGE allow-none="1"> location in which to store the rate + line="2290">location in which to store the rate multiplier of the instant-rate-change event, or %NULL @@ -27504,7 +28502,7 @@ gst_event_set_gap_flags(). allow-none="1"> location in which to store the new + line="2292">location in which to store the new segment flags of the instant-rate-change event, or %NULL @@ -27515,7 +28513,7 @@ gst_event_set_gap_flags(). version="1.18"> Extract the rate multiplier and running times from an instant-rate-sync-time event. + line="2362">Extract the rate multiplier and running times from an instant-rate-sync-time event. @@ -27524,7 +28522,7 @@ gst_event_set_gap_flags(). a #GstEvent of type #GST_EVENT_INSTANT_RATE_CHANGE + line="2364">a #GstEvent of type #GST_EVENT_INSTANT_RATE_CHANGE allow-none="1"> location where to store the rate of + line="2365">location where to store the rate of the instant-rate-sync-time event, or %NULL @@ -27547,7 +28545,7 @@ gst_event_set_gap_flags(). allow-none="1"> location in which to store the running time + line="2367">location in which to store the running time of the instant-rate-sync-time event, or %NULL @@ -27559,7 +28557,7 @@ gst_event_set_gap_flags(). allow-none="1"> location in which to store the + line="2369">location in which to store the upstream running time of the instant-rate-sync-time event, or %NULL @@ -27568,7 +28566,7 @@ gst_event_set_gap_flags(). Get the latency in the latency event. + line="1536">Get the latency in the latency event. @@ -27577,7 +28575,7 @@ gst_event_set_gap_flags(). The event to query + line="1538">The event to query allow-none="1"> A pointer to store the latency in. + line="1539">A pointer to store the latency in. @@ -27598,7 +28596,7 @@ gst_event_set_gap_flags(). version="1.6"> Parses an event containing protection system specific information and stores + line="2149">Parses an event containing protection system specific information and stores the results in @system_id, @data and @origin. The data stored in @system_id, @origin and @data are valid until @event is released. @@ -27609,7 +28607,7 @@ the results in @system_id, @data and @origin. The data stored in @system_id, a #GST_EVENT_PROTECTION event. + line="2151">a #GST_EVENT_PROTECTION event. pointer to store the UUID + line="2152">pointer to store the UUID string uniquely identifying a content protection system. @@ -27632,7 +28630,7 @@ string uniquely identifying a content protection system. allow-none="1"> pointer to store a #GstBuffer + line="2154">pointer to store a #GstBuffer holding protection system specific information. @@ -27644,7 +28642,7 @@ holding protection system specific information. allow-none="1"> pointer to store a value that + line="2156">pointer to store a value that indicates where the protection information carried by @event was extracted from. @@ -27654,7 +28652,7 @@ from. Get the type, proportion, diff and timestamp in the qos event. See + line="1247">Get the type, proportion, diff and timestamp in the qos event. See gst_event_new_qos() for more information about the different QoS values. @timestamp will be adjusted for any pad offsets of pads it was passing through. @@ -27666,7 +28664,7 @@ gst_event_new_qos() for more information about the different QoS values. The event to query + line="1249">The event to query A pointer to store the QoS type in + line="1250">A pointer to store the QoS type in A pointer to store the proportion in + line="1251">A pointer to store the proportion in A pointer to store the diff in + line="1252">A pointer to store the diff in A pointer to store the timestamp in + line="1253">A pointer to store the timestamp in @@ -27718,7 +28716,7 @@ gst_event_new_qos() for more information about the different QoS values. Parses a seek @event and stores the results in the given result locations. + line="1398">Parses a seek @event and stores the results in the given result locations. @@ -27727,7 +28725,7 @@ gst_event_new_qos() for more information about the different QoS values. a seek event + line="1400">a seek event result location for the rate + line="1401">result location for the rate result location for the stream format + line="1402">result location for the stream format result location for the #GstSeekFlags + line="1403">result location for the #GstSeekFlags result location for the #GstSeekType of the start position + line="1404">result location for the #GstSeekType of the start position result location for the start position expressed in @format + line="1405">result location for the start position expressed in @format result location for the #GstSeekType of the stop position + line="1406">result location for the #GstSeekType of the stop position result location for the stop position expressed in @format + line="1407">result location for the stop position expressed in @format @@ -27814,7 +28812,7 @@ gst_event_new_qos() for more information about the different QoS values. version="1.16"> Retrieve the trickmode interval that may have been set on a + line="1463">Retrieve the trickmode interval that may have been set on a seek event with gst_event_set_seek_trickmode_interval(). @@ -27832,7 +28830,7 @@ seek event with gst_event_set_seek_trickmode_interval(). allow-none="1"> interval + line="1465">interval @@ -27840,7 +28838,7 @@ seek event with gst_event_set_seek_trickmode_interval(). Parses a segment @event and stores the result in the given @segment location. + line="1000">Parses a segment @event and stores the result in the given @segment location. @segment remains valid only until the @event is freed. Don't modify the segment and make a copy if you want to modify it or store it for later use. @@ -27851,7 +28849,7 @@ and make a copy if you want to modify it or store it for later use. The event to parse + line="1002">The event to parse allow-none="1"> a pointer to a #GstSegment + line="1003">a pointer to a #GstSegment @@ -27871,7 +28869,7 @@ and make a copy if you want to modify it or store it for later use. c:identifier="gst_event_parse_segment_done"> Extracts the position and format from the segment done message. + line="2217">Extracts the position and format from the segment done message. @@ -27880,7 +28878,7 @@ and make a copy if you want to modify it or store it for later use. A valid #GstEvent of type GST_EVENT_SEGMENT_DONE. + line="2219">A valid #GstEvent of type GST_EVENT_SEGMENT_DONE. allow-none="1"> Result location for the format, or %NULL + line="2220">Result location for the format, or %NULL allow-none="1"> Result location for the position, or %NULL + line="2221">Result location for the position, or %NULL @@ -27912,7 +28910,7 @@ and make a copy if you want to modify it or store it for later use. version="1.10"> Parse the SELECT_STREAMS event and retrieve the contained streams. + line="682">Parse the SELECT_STREAMS event and retrieve the contained streams. @@ -27921,7 +28919,7 @@ and make a copy if you want to modify it or store it for later use. The event to parse + line="684">The event to parse allow-none="1"> the streams + line="685">the streams @@ -27943,7 +28941,7 @@ and make a copy if you want to modify it or store it for later use. c:identifier="gst_event_parse_sink_message"> Parse the sink-message event. Unref @msg after usage. + line="1693">Parse the sink-message event. Unref @msg after usage. @@ -27952,7 +28950,7 @@ and make a copy if you want to modify it or store it for later use. The event to query + line="1695">The event to query allow-none="1"> a pointer to store the #GstMessage in. + line="1696">a pointer to store the #GstMessage in. @@ -27971,7 +28969,7 @@ and make a copy if you want to modify it or store it for later use. Parse the step event. + line="1601">Parse the step event. @@ -27980,7 +28978,7 @@ and make a copy if you want to modify it or store it for later use. The event to query + line="1603">The event to query allow-none="1"> a pointer to store the format in + line="1604">a pointer to store the format in allow-none="1"> a pointer to store the amount in + line="1605">a pointer to store the amount in allow-none="1"> a pointer to store the rate in + line="1606">a pointer to store the rate in allow-none="1"> a pointer to store the flush boolean in + line="1607">a pointer to store the flush boolean in allow-none="1"> a pointer to store the intermediate + line="1608">a pointer to store the intermediate boolean in @@ -28046,7 +29044,7 @@ and make a copy if you want to modify it or store it for later use. version="1.10"> Parse a stream-start @event and extract the #GstStream from it. + line="1803">Parse a stream-start @event and extract the #GstStream from it. @@ -28055,7 +29053,7 @@ and make a copy if you want to modify it or store it for later use. a stream-start event + line="1805">a stream-start event allow-none="1"> address of variable to store the stream + line="1806">address of variable to store the stream @@ -28076,7 +29074,7 @@ and make a copy if you want to modify it or store it for later use. version="1.10"> Retrieve new #GstStreamCollection from STREAM_COLLECTION event @event. + line="1947">Retrieve new #GstStreamCollection from STREAM_COLLECTION event @event. @@ -28085,7 +29083,7 @@ and make a copy if you want to modify it or store it for later use. a stream-collection event + line="1949">a stream-collection event allow-none="1"> pointer to store the collection. + line="1950">pointer to store the collection. @@ -28112,7 +29110,7 @@ and make a copy if you want to modify it or store it for later use. a stream-start event + line="1845">a stream-start event allow-none="1"> address of variable where to store the stream flags + line="1846">address of variable where to store the stream flags @@ -28133,7 +29131,7 @@ and make a copy if you want to modify it or store it for later use. version="1.10"> Parse a stream-group-done @event and store the result in the given + line="744">Parse a stream-group-done @event and store the result in the given @group_id location. @@ -28143,7 +29141,7 @@ and make a copy if you want to modify it or store it for later use. a stream-group-done event. + line="746">a stream-group-done event. allow-none="1"> address of variable to store the group id into + line="747">address of variable to store the group id into @@ -28163,7 +29161,7 @@ and make a copy if you want to modify it or store it for later use. c:identifier="gst_event_parse_stream_start"> Parse a stream-id @event and store the result in the given @stream_id + line="1757">Parse a stream-id @event and store the result in the given @stream_id location. The string stored in @stream_id must not be modified and will remain valid only until @event gets freed. Make a copy if you want to modify it or store it for later use. @@ -28175,7 +29173,7 @@ modify it or store it for later use. a stream-start event. + line="1759">a stream-start event. allow-none="1"> pointer to store the stream-id + line="1760">pointer to store the stream-id @@ -28194,7 +29192,7 @@ modify it or store it for later use. Parses a tag @event and stores the results in the given @taglist location. + line="1078">Parses a tag @event and stores the results in the given @taglist location. No reference to the taglist will be returned, it remains valid only until the @event is freed. Don't modify or free the taglist, make a copy if you want to modify it or store it for later use. @@ -28206,7 +29204,7 @@ want to modify it or store it for later use. a tag event + line="1080">a tag event allow-none="1"> pointer to metadata list + line="1081">pointer to metadata list @@ -28225,7 +29223,7 @@ want to modify it or store it for later use. Parse a TOC @event and store the results in the given @toc and @updated locations. + line="2006">Parse a TOC @event and store the results in the given @toc and @updated locations. @@ -28234,7 +29232,7 @@ want to modify it or store it for later use. a TOC event. + line="2008">a TOC event. allow-none="1"> pointer to #GstToc structure. + line="2009">pointer to #GstToc structure. allow-none="1"> pointer to store TOC updated flag. + line="2010">pointer to store TOC updated flag. @@ -28265,7 +29263,7 @@ want to modify it or store it for later use. c:identifier="gst_event_parse_toc_select"> Parse a TOC select @event and store the results in the given @uid location. + line="2054">Parse a TOC select @event and store the results in the given @uid location. @@ -28274,7 +29272,7 @@ want to modify it or store it for later use. a TOC select event. + line="2056">a TOC select event. allow-none="1"> storage for the selection UID. + line="2057">storage for the selection UID. @@ -28295,7 +29293,7 @@ want to modify it or store it for later use. version="1.20"> Sets @flags on @event to give additional information about the reason for + line="849">Sets @flags on @event to give additional information about the reason for the #GST_EVENT_GAP. @@ -28305,13 +29303,13 @@ the #GST_EVENT_GAP. a #GstEvent of type #GST_EVENT_GAP + line="851">a #GstEvent of type #GST_EVENT_GAP a #GstGapFlags + line="852">a #GstGapFlags @@ -28321,7 +29319,7 @@ the #GST_EVENT_GAP. version="1.2"> All streams that have the same group id are supposed to be played + line="1863">All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids @@ -28336,13 +29334,13 @@ Use gst_util_group_id_next() to get a new group id. a stream-start event + line="1865">a stream-start event the group id to set + line="1866">the group id to set @@ -28352,7 +29350,7 @@ Use gst_util_group_id_next() to get a new group id. version="1.4"> Set the running time offset of a event. See + line="536">Set the running time offset of a event. See gst_event_get_running_time_offset() for more information. MT safe. @@ -28364,13 +29362,13 @@ MT safe. A #GstEvent. + line="538">A #GstEvent. A the new running time offset + line="539">A the new running time offset @@ -28380,7 +29378,7 @@ MT safe. version="1.16"> Sets a trickmode interval on a (writable) seek event. Elements + line="1442">Sets a trickmode interval on a (writable) seek event. Elements that support TRICKMODE_KEY_UNITS seeks SHOULD use this as the minimal interval between each frame they may output. @@ -28399,7 +29397,7 @@ interval between each frame they may output. Set the sequence number of a event. + line="485">Set the sequence number of a event. This function might be called by the creator of a event to indicate that the event relates to other events or messages. See gst_event_get_seqnum() for @@ -28414,13 +29412,13 @@ MT safe. A #GstEvent. + line="487">A #GstEvent. A sequence number. + line="488">A sequence number. @@ -28430,7 +29428,7 @@ MT safe. version="1.10"> Set the @stream on the stream-start @event + line="1783">Set the @stream on the stream-start @event @@ -28439,13 +29437,13 @@ MT safe. a stream-start event + line="1785">a stream-start event the stream object to set + line="1786">the stream object to set @@ -28461,13 +29459,13 @@ MT safe. a stream-start event + line="1827">a stream-start event the stream flags to set + line="1828">the stream flags to set @@ -28476,12 +29474,12 @@ MT safe. c:identifier="gst_event_writable_structure"> Get a writable version of the structure. + line="381">Get a writable version of the structure. The structure of the event. The structure + line="387">The structure of the event. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event. This function ensures that @event is writable, and if so, will @@ -28494,7 +29492,7 @@ MT safe. A writable #GstEvent. + line="383">A writable #GstEvent. @@ -28832,19 +29830,19 @@ Specific custom events are distinguished by the name of the structure. Gets the #GstEventTypeFlags associated with @type. + line="197">Gets the #GstEventTypeFlags associated with @type. a #GstEventTypeFlags. + line="203">a #GstEventTypeFlags. a #GstEventType + line="199">a #GstEventType @@ -28852,19 +29850,19 @@ Specific custom events are distinguished by the name of the structure. Get a printable name for the given event type. Do not modify or free. + line="157">Get a printable name for the given event type. Do not modify or free. a reference to the static name of the event. + line="163">a reference to the static name of the event. the event type + line="159">the event type @@ -28872,19 +29870,19 @@ Specific custom events are distinguished by the name of the structure. Get the unique quark for the given event type. + line="177">Get the unique quark for the given event type. the quark associated with the event type + line="183">the quark associated with the event type the event type + line="179">the event type @@ -28894,21 +29892,21 @@ Specific custom events are distinguished by the name of the structure. version="1.22"> Converts the #GstEventType to an unsigned integer that + line="215">Converts the #GstEventType to an unsigned integer that represents the ordering of sticky events when re-sending them. A lower value represents a higher-priority event. an unsigned integer + line="223">an unsigned integer a #GstEventType + line="217">a #GstEventType @@ -28974,16 +29972,16 @@ gst_event_type_get_flags() function. Output a fixme message in the default category. + line="1295">Output a fixme message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1297">printf-style message to output @@ -28993,21 +29991,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a fixme message for the given identifier in the default category. + line="1209">Output a fixme message for the given identifier in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1211">An identifier of the message provider printf-style message to output + line="1212">printf-style message to output @@ -29016,21 +30014,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a fixme message belonging to the given object in the default category. + line="1115">Output a fixme message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1117">the #GObject the message belongs to printf-style message to output + line="1118">printf-style message to output @@ -29110,7 +30108,7 @@ mask indicating which of the bits in the field are explicitly set. version="1.6"> Create a new sub-class of #GST_TYPE_FLAG_SET + line="8674">Create a new sub-class of #GST_TYPE_FLAG_SET which will pretty-print the human-readable flags when serializing, for easier debugging. @@ -29121,7 +30119,7 @@ when serializing, for easier debugging. a #GType of a #G_TYPE_FLAGS type. + line="8676">a #GType of a #G_TYPE_FLAGS type. @@ -29930,16 +30928,16 @@ is unlinked and links to the new target are established. if @newtarget is Output an informational message in the default category. + line="1268">Output an informational message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1270">printf-style message to output @@ -29949,22 +30947,22 @@ character, a newline character will be added automatically. introspectable="0"> Output an informational message for the given identifier the default + line="1172">Output an informational message for the given identifier the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1174">An identifier of the message provider printf-style message to output + line="1175">printf-style message to output @@ -29973,22 +30971,22 @@ character, a newline character will be added automatically. introspectable="0"> Output an informational message belonging to the given object in the default + line="1083">Output an informational message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1085">the #GObject the message belongs to printf-style message to output + line="1086">printf-style message to output @@ -30090,7 +31088,7 @@ character, a newline character will be added automatically. - + @@ -30243,7 +31241,7 @@ character, a newline character will be added automatically. - + @@ -30252,7 +31250,7 @@ character, a newline character will be added automatically. - + @@ -30474,6 +31472,15 @@ character, a newline character will be added automatically. + + + + + + + @@ -30585,7 +31592,7 @@ character, a newline character will be added automatically. - + @@ -30827,6 +31834,415 @@ whenever the datastructure changes. + + A #GstIdStr is string type optimized for short strings and used for structure +names, structure field names and in other places. + +Strings up to 16 bytes (including NUL terminator) are stored inline, other +strings are stored on the heap. + +```cpp +GstIdStr s = GST_ID_STR_INIT; + +gst_id_str_set (&s, "Hello, World!"); +g_print ("%s\n", gst_id_str_as_str (&s)); + +gst_id_str_clear (&s); +``` + + + + + + + + + + + Returns a newly heap allocated empty string. + + + A heap-allocated string. + + + + + + + the NUL-terminated string representation of @s. + + + + + A %GstIdStr + + + + + + Clears @s and sets it to the empty string. + + + + + + + A %GstIdStr + + + + + + Copies @s into newly allocated heap memory. + + + A heap-allocated copy of @s. + + + + + A %GstIdStr + + + + + + Copies @s into @d. + + + + + + + The destination %GstIdStr + + + + The source %GstIdStr + + + + + + Frees @s. This should only be called for heap-allocated #GstIdStr. + + + + + + + A heap allocated %GstIdStr + + + + + + Returns the length of @s, exluding the NUL-terminator. This is equivalent to +calling `strcmp()` but potentially faster. + + + + + + + A %GstIdStr + + + + + + Initializes a (usually stack-allocated) id string @s. The newly-initialized +id string will contain an empty string by default as value. + + + + + + + A %GstIdStr + + + + + + Compares @s1 and @s2 for equality. + + + %TRUE if @s1 and @s2 are equal. + + + + + A %GstIdStr + + + + A %GstIdStr + + + + + + Compares @s1 and @s2 for equality. + + + %TRUE if @s1 and @s2 are equal. + + + + + A %GstIdStr + + + + A string + + + + + + Compares @s1 and @s2 with length @len for equality. @s2 does not have to be +NUL-terminated and @len should not include the NUL-terminator. + +This is generally faster than gst_id_str_is_equal_to_str() if the length is +already known. + + + %TRUE if @s1 and @s2 are equal. + + + + + A %GstIdStr + + + + A string + + + + Length of @s2. + + + + + + Moves @s into @d and resets @s. + + + + + + + The destination %GstIdStr + + + + The source %GstIdStr + + + + + + Sets @s to the string @value. + + + + + + + A %GstIdStr + + + + A NUL-terminated string + + + + + + Sets @s to the string @value. @value needs to be valid for the remaining +lifetime of the process, e.g. has to be a static string. + + + + + + + A %GstIdStr + + + + A NUL-terminated string + + + + + + Sets @s to the string @value of length @len. @value needs to be valid for the +remaining lifetime of the process, e.g. has to be a static string. + +@value must be NUL-terminated and @len should not include the +NUL-terminator. + + + + + + + A %GstIdStr + + + + A string + + + + Length of the string + + + + + + Sets @s to the string @value of length @len. @value does not have to be +NUL-terminated and @len should not include the NUL-terminator. + + + + + + + A %GstIdStr + + + + A string + + + + Length of the string + + + + + Create a new iterator. This function is mainly used for objects + line="121">Create a new iterator. This function is mainly used for objects implementing the next/resync/free function to iterate a data structure. For each item retrieved, the @item function is called with the lock @@ -30978,7 +32394,7 @@ held. The @free function is called when the iterator is freed. the new #GstIterator. + line="140">the new #GstIterator. MT safe. @@ -30987,60 +32403,60 @@ MT safe. the size of the iterator structure + line="123">the size of the iterator structure #GType of children + line="124">#GType of children pointer to a #GMutex. + line="125">pointer to a #GMutex. pointer to a guint32 that is changed when the items in the + line="126">pointer to a guint32 that is changed when the items in the iterator changed. copy function + line="128">copy function function to get next item + line="129">function to get next item function to call on each item retrieved + line="130">function to call on each item retrieved function to resync the iterator + line="131">function to resync the iterator function to free the iterator + line="132">function to free the iterator @@ -31051,7 +32467,7 @@ MT safe. introspectable="0"> Create a new iterator designed for iterating @list. + line="219">Create a new iterator designed for iterating @list. The list you iterate is usually part of a data structure @owner and is protected with @lock. @@ -31067,7 +32483,7 @@ the user of the iterator in the next call to gst_iterator_next(). the new #GstIterator for @list. + line="242">the new #GstIterator for @list. MT safe. @@ -31076,26 +32492,26 @@ MT safe. #GType of elements + line="221">#GType of elements pointer to a #GMutex protecting the list. + line="222">pointer to a #GMutex protecting the list. pointer to a guint32 that is incremented when the list + line="223">pointer to a guint32 that is incremented when the list is changed. pointer to the list + line="225">pointer to the list @@ -31103,13 +32519,13 @@ MT safe. object owning the list + line="226">object owning the list function to call on each item retrieved + line="227">function to call on each item retrieved @@ -31118,7 +32534,7 @@ MT safe. This #GstIterator is a convenient iterator for the common + line="798">This #GstIterator is a convenient iterator for the common case where a #GstIterator needs to be returned but only a single object has to be considered. This happens often for the #GstPadIterIntLinkFunction. @@ -31126,20 +32542,20 @@ for the #GstPadIterIntLinkFunction. the new #GstIterator for @object. + line="808">the new #GstIterator for @object. #GType of the passed object + line="800">#GType of the passed object object that this iterator should return + line="801">object that this iterator should return @@ -31147,19 +32563,19 @@ for the #GstPadIterIntLinkFunction. Copy the iterator and its state. + line="74">Copy the iterator and its state. a new copy of @it. + line="80">a new copy of @it. a #GstIterator + line="76">a #GstIterator @@ -31167,7 +32583,7 @@ for the #GstPadIterIntLinkFunction. Create a new iterator from an existing iterator. The new iterator + line="529">Create a new iterator from an existing iterator. The new iterator will only return those elements that match the given compare function @func. The first parameter that is passed to @func is the #GValue of the current iterator element and the second parameter is @user_data. @func should @@ -31178,7 +32594,7 @@ When this iterator is freed, @it will also be freed. a new #GstIterator. + line="543">a new #GstIterator. MT safe. @@ -31187,19 +32603,19 @@ MT safe. The #GstIterator to filter + line="531">The #GstIterator to filter the compare function to select elements + line="532">the compare function to select elements user data passed to the compare function + line="533">user data passed to the compare function @@ -31207,7 +32623,7 @@ MT safe. Find the first element in @it that matches the compare function @func. + line="699">Find the first element in @it that matches the compare function @func. @func should return 0 when the element is found. The first parameter to @func will be the current element of the iterator and the second parameter will be @user_data. @@ -31221,7 +32637,7 @@ or if the element wasn't found. Returns %TRUE if the element was found, else %FALSE. + line="717">Returns %TRUE if the element was found, else %FALSE. MT safe. @@ -31230,7 +32646,7 @@ MT safe. The #GstIterator to iterate + line="701">The #GstIterator to iterate closure="2"> the compare function to use + line="702">the compare function to use transfer-ownership="none"> pointer to a #GValue where to store the result + line="703">pointer to a #GValue where to store the result allow-none="1"> user data passed to the compare function + line="704">user data passed to the compare function @@ -31265,7 +32681,7 @@ MT safe. Folds @func over the elements of @iter. That is to say, @func will be called + line="579">Folds @func over the elements of @iter. That is to say, @func will be called as @func (object, @ret, @user_data) for each object in @it. The normal use of this procedure is to accumulate the results of operating on the objects in @ret. @@ -31284,7 +32700,7 @@ The iterator will not be freed. A #GstIteratorResult, as described above. + line="602">A #GstIteratorResult, as described above. MT safe. @@ -31293,7 +32709,7 @@ MT safe. The #GstIterator to fold over + line="581">The #GstIterator to fold over closure="2"> the fold function + line="582">the fold function the seed value passed to the fold function + line="583">the seed value passed to the fold function allow-none="1"> user data passed to the fold function + line="584">user data passed to the fold function @@ -31326,13 +32742,13 @@ MT safe. Iterate over all element of @it and call the given function @func for + line="652">Iterate over all element of @it and call the given function @func for each element. the result call to gst_iterator_fold(). The iterator will not be + line="661">the result call to gst_iterator_fold(). The iterator will not be freed. MT safe. @@ -31342,7 +32758,7 @@ MT safe. The #GstIterator to iterate + line="654">The #GstIterator to iterate closure="1"> the function to call for each element. + line="655">the function to call for each element. @@ -31361,7 +32777,7 @@ MT safe. allow-none="1"> user data passed to the function + line="656">user data passed to the function @@ -31369,7 +32785,7 @@ MT safe. Free the iterator. + line="409">Free the iterator. MT safe. @@ -31380,7 +32796,7 @@ MT safe. The #GstIterator to free + line="411">The #GstIterator to free @@ -31388,7 +32804,7 @@ MT safe. Get the next item from the iterator in @elem. + line="296">Get the next item from the iterator in @elem. Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid value. @elem must have been initialized to the type of the iterator or @@ -31408,7 +32824,7 @@ A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error. The result of the iteration. Unset @elem after usage. + line="318">The result of the iteration. Unset @elem after usage. MT safe. @@ -31417,7 +32833,7 @@ MT safe. The #GstIterator to iterate + line="298">The #GstIterator to iterate transfer-ownership="none"> pointer to hold next element + line="299">pointer to hold next element @@ -31434,7 +32850,7 @@ MT safe. Pushes @other iterator onto @it. All calls performed on @it are + line="429">Pushes @other iterator onto @it. All calls performed on @it are forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is popped again and calls are handled by @it again. @@ -31453,13 +32869,13 @@ MT safe. The #GstIterator to use + line="431">The #GstIterator to use The #GstIterator to push + line="432">The #GstIterator to push @@ -31467,7 +32883,7 @@ MT safe. Resync the iterator. this function is mostly called + line="382">Resync the iterator. this function is mostly called after gst_iterator_next() returned %GST_ITERATOR_RESYNC. When an iterator was pushed on @it, it will automatically be popped again @@ -31482,7 +32898,7 @@ MT safe. The #GstIterator to resync + line="384">The #GstIterator to resync @@ -31783,16 +33199,16 @@ The function will be called with the iterator lock held. Output a logging message in the default category. + line="1286">Output a logging message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1288">printf-style message to output @@ -31802,21 +33218,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a logging message for the given identifier in the default category. + line="1197">Output a logging message for the given identifier in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1199">An identifier of the message provider printf-style message to output + line="1200">printf-style message to output @@ -31825,21 +33241,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a logging message belonging to the given object in the default category. + line="1105">Output a logging message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1107">the #GObject the message belongs to printf-style message to output + line="1108">printf-style message to output @@ -31971,10 +33387,10 @@ deciding where to go while developing code. Function prototype for a logging function that can be registered with + line="334">Function prototype for a logging function that can be registered with gst_debug_add_log_function(). Use G_GNUC_NO_INSTRUMENT on that function. - + @@ -31982,43 +33398,43 @@ Use G_GNUC_NO_INSTRUMENT on that function. a #GstDebugCategory + line="336">a #GstDebugCategory a #GstDebugLevel + line="337">a #GstDebugLevel file name + line="338">file name function name + line="339">function name line number + line="340">line number a #GObject + line="341">a #GObject the message + line="342">the message closure="7"> user data for the log function + line="343">user data for the log function @@ -32080,26 +33496,26 @@ guint32 fourcc = GST_MAKE_FOURCC ('M', 'J', 'P', 'G'); introspectable="0"> Output a hexdump of @data. + line="1313">Output a hexdump of @data. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + message string to log with the data + line="1315">message string to log with the data pointer to the data to output + line="1316">pointer to the data to output length of the data to output + line="1317">length of the data to output @@ -32109,31 +33525,31 @@ character, a newline character will be added automatically. introspectable="0"> Output a logging message belonging to the given object in the default category. + line="1233">Output a logging message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1235">An identifier of the message provider message string to log with the data + line="1236">message string to log with the data pointer to the data to output + line="1237">pointer to the data to output length of the data to output + line="1238">length of the data to output @@ -32142,31 +33558,31 @@ character, a newline character will be added automatically. introspectable="0"> Output a logging message belonging to the given object in the default category. + line="1135">Output a logging message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1137">the #GObject the message belongs to message string to log with the data + line="1138">message string to log with the data pointer to the data to output + line="1139">pointer to the data to output length of the data to output + line="1140">length of the data to output @@ -32509,7 +33925,7 @@ was created. - + @@ -32520,13 +33936,13 @@ was created. introspectable="0"> A flags word containing #GstMetaFlags flags set on @meta - + line="57">A flags word containing #GstMetaFlags flags set on @meta + a #GstMeta. + line="59">a #GstMeta. @@ -32535,18 +33951,18 @@ was created. introspectable="0"> Gives the status of a specific flag on a metadata. - + line="64">Gives the status of a specific flag on a metadata. + a #GstMeta. + line="66">a #GstMeta. the #GstMetaFlags to check. + line="67">the #GstMetaFlags to check. @@ -32555,18 +33971,18 @@ was created. introspectable="0"> Sets a metadata flag on a metadata. - + line="72">Sets a metadata flag on a metadata. + a #GstMeta. + line="74">a #GstMeta. the #GstMetaFlags to set. + line="75">the #GstMetaFlags to set. @@ -32575,18 +33991,18 @@ was created. introspectable="0"> Clears a metadata flag. - + line="80">Clears a metadata flag. + a #GstMeta. + line="82">a #GstMeta. the #GstMetaFlags to clear. + line="83">the #GstMetaFlags to clear. @@ -32596,8 +34012,8 @@ was created. version="1.20.4"> This metadata stays relevant until a deep copy is made. - + line="100">This metadata stays relevant until a deep copy is made. + version="1.2"> This metadata stays relevant as long as memory layout is unchanged. + line="90">This metadata stays relevant as long as memory layout is unchanged. In hindsight, this tag should have been called "memory-layout". - + introspectable="0"> Check if the transform type is a copy transform - + line="178">Check if the transform type is a copy transform + a transform type + line="180">a transform type @@ -32977,28 +34393,28 @@ Memory can be efficiently merged when gst_memory_is_span() returns %TRUE. Allocate a new memory block that wraps the given @data. + line="646">Allocate a new memory block that wraps the given @data. The prefix/padding must be filled with 0 if @flags contains #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. - + a new #GstMemory. + line="662">a new #GstMemory. #GstMemoryFlags + line="648">#GstMemoryFlags data to + line="649">data to wrap @@ -33007,19 +34423,19 @@ The prefix/padding must be filled with 0 if @flags contains allocated size of @data + line="651">allocated size of @data offset in @data + line="652">offset in @data size of valid data + line="653">size of valid data user_data + line="654">user_data called with @user_data when the memory is freed + line="655">called with @user_data when the memory is freed @@ -33047,33 +34463,33 @@ The prefix/padding must be filled with 0 if @flags contains Return a copy of @size bytes from @mem starting from @offset. This copy is + line="359">Return a copy of @size bytes from @mem starting from @offset. This copy is guaranteed to be writable. @size can be set to -1 to return a copy from @offset to the end of the memory region. a new copy of @mem if the copy succeeded, %NULL otherwise. + line="369">a new copy of @mem if the copy succeeded, %NULL otherwise. a #GstMemory + line="361">a #GstMemory offset to copy from + line="362">offset to copy from size to copy, or -1 to copy to the end of the memory region + line="363">size to copy, or -1 to copy to the end of the memory region @@ -33081,19 +34497,19 @@ from @offset to the end of the memory region. Get the current @size, @offset and @maxsize of @mem. + line="168">Get the current @size, @offset and @maxsize of @mem. the current size of @mem + line="176">the current size of @mem a #GstMemory + line="170">a #GstMemory allow-none="1"> pointer to offset + line="171">pointer to offset allow-none="1"> pointer to maxsize + line="172">pointer to maxsize @@ -33123,7 +34539,7 @@ from @offset to the end of the memory region. Initializes a newly allocated @mem with the given parameters. This function + line="105">Initializes a newly allocated @mem with the given parameters. This function will call gst_mini_object_init() with the default memory parameters. @@ -33133,49 +34549,49 @@ will call gst_mini_object_init() with the default memory parameters. a #GstMemory + line="107">a #GstMemory #GstMemoryFlags + line="108">#GstMemoryFlags the #GstAllocator + line="109">the #GstAllocator the parent of @mem + line="110">the parent of @mem the total size of the memory + line="111">the total size of the memory the alignment of the memory + line="112">the alignment of the memory The offset in the memory + line="113">The offset in the memory the size of valid data in the memory + line="114">the size of valid data in the memory @@ -33183,7 +34599,7 @@ will call gst_mini_object_init() with the default memory parameters. Check if @mem1 and mem2 share the memory with a common parent memory object + line="430">Check if @mem1 and mem2 share the memory with a common parent memory object and that the memory is contiguous. If this is the case, the memory of @mem1 and @mem2 can be merged @@ -33193,20 +34609,20 @@ the returned @offset. %TRUE if the memory is contiguous and of a common parent. + line="443">%TRUE if the memory is contiguous and of a common parent. a #GstMemory + line="432">a #GstMemory a #GstMemory + line="433">a #GstMemory transfer-ownership="full"> a pointer to a result offset + line="434">a pointer to a result offset @@ -33223,25 +34639,25 @@ the returned @offset. Check if @mem if allocated with an allocator for @mem_type. + line="147">Check if @mem if allocated with an allocator for @mem_type. %TRUE if @mem was allocated from an allocator for @mem_type. + line="154">%TRUE if @mem was allocated from an allocator for @mem_type. a #GstMemory + line="149">a #GstMemory a memory type + line="150">a memory type @@ -33249,7 +34665,7 @@ the returned @offset. Create a #GstMemory object that is mapped with @flags. If @mem is mappable + line="223">Create a #GstMemory object that is mapped with @flags. If @mem is mappable with @flags, this function returns the mapped @mem directly. Otherwise a mapped copy of @mem is returned. @@ -33259,7 +34675,7 @@ This function takes ownership of old @mem and returns a reference to a new a #GstMemory object mapped + line="236">a #GstMemory object mapped with @flags or %NULL when a mapping is not possible. @@ -33267,7 +34683,7 @@ with @flags or %NULL when a mapping is not possible. a #GstMemory + line="225">a #GstMemory transfer-ownership="none"> pointer for info + line="226">pointer for info mapping flags + line="227">mapping flags @@ -33290,7 +34706,7 @@ with @flags or %NULL when a mapping is not possible. Fill @info with the pointer and sizes of the memory in @mem that can be + line="273">Fill @info with the pointer and sizes of the memory in @mem that can be accessed according to @flags. This function can return %FALSE for various reasons: @@ -33306,14 +34722,14 @@ should be done. %TRUE if the map operation was successful. + line="292">%TRUE if the map operation was successful. a #GstMemory + line="275">a #GstMemory transfer-ownership="none"> pointer for info + line="276">pointer for info mapping flags + line="277">mapping flags @@ -33336,7 +34752,7 @@ should be done. Resize the memory region. @mem should be writable and offset + size should be + line="191">Resize the memory region. @mem should be writable and offset + size should be less than the maxsize of @mem. #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be @@ -33349,19 +34765,19 @@ cleared when offset or padding is increased respectively. a #GstMemory + line="193">a #GstMemory a new offset + line="194">a new offset a new size + line="195">a new size @@ -33369,7 +34785,7 @@ cleared when offset or padding is increased respectively. Return a shared copy of @size bytes from @mem starting from @offset. No + line="383">Return a shared copy of @size bytes from @mem starting from @offset. No memory copy is performed and the memory region is simply shared. The result is guaranteed to be non-writable. @size can be set to -1 to return a shared copy from @offset to the end of the memory region. @@ -33377,26 +34793,26 @@ copy from @offset to the end of the memory region. a new #GstMemory. + line="394">a new #GstMemory. a #GstMemory + line="385">a #GstMemory offset to share from + line="386">offset to share from size to share, or -1 to share to the end of the memory region + line="387">size to share, or -1 to share to the end of the memory region @@ -33404,7 +34820,7 @@ copy from @offset to the end of the memory region. Release the memory obtained with gst_memory_map() + line="338">Release the memory obtained with gst_memory_map() @@ -33413,13 +34829,13 @@ copy from @offset to the end of the memory region. a #GstMemory + line="340">a #GstMemory a #GstMapInfo + line="341">a #GstMapInfo @@ -33779,13 +35195,13 @@ container using gst_element_post_message(). c:identifier="gst_message_new_application"> Create a new application-typed message. GStreamer will never create these + line="1132">Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy. - + The new application message. + line="1141">The new application message. MT safe. @@ -33797,13 +35213,13 @@ MT safe. allow-none="1"> The object originating the message. + line="1134">The object originating the message. the structure for the message. The message + line="1135">the structure for the message. The message will take ownership of the structure. @@ -33813,16 +35229,16 @@ MT safe. c:identifier="gst_message_new_async_done"> The message is posted when elements completed an ASYNC state change. + line="1220">The message is posted when elements completed an ASYNC state change. @running_time contains the time of the desired running_time when this elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time means that the element has no clock interaction and thus doesn't care about the running_time of the pipeline. - + The new async_done message. + line="1231">The new async_done message. MT safe. @@ -33834,13 +35250,13 @@ MT safe. allow-none="1"> The object originating the message. + line="1222">The object originating the message. the desired running_time + line="1223">the desired running_time @@ -33849,12 +35265,12 @@ MT safe. c:identifier="gst_message_new_async_start"> This message is posted by elements when they start an ASYNC state change. - + line="1200">This message is posted by elements when they start an ASYNC state change. + The new async_start message. + line="1206">The new async_start message. MT safe. @@ -33866,7 +35282,7 @@ MT safe. allow-none="1"> The object originating the message. + line="1202">The object originating the message. @@ -33875,7 +35291,7 @@ MT safe. c:identifier="gst_message_new_buffering"> Create a new buffering message. This message can be posted by an element that + line="855">Create a new buffering message. This message can be posted by an element that needs to buffer data before it can continue processing. @percent should be a value between 0 and 100. A value of 100 means that the buffering completed. @@ -33887,11 +35303,11 @@ message with @percent set to 100, which can happen after the pipeline completed prerolling. MT safe. - + The new buffering message. + line="873">The new buffering message. @@ -33901,13 +35317,13 @@ MT safe. allow-none="1"> The object originating the message. + line="857">The object originating the message. The buffering percent + line="858">The buffering percent @@ -33916,17 +35332,17 @@ MT safe. c:identifier="gst_message_new_clock_lost"> Create a clock lost message. This message is posted whenever the + line="980">Create a clock lost message. This message is posted whenever the clock is not valid anymore. If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again. - + The new clock lost message. + line="992">The new clock lost message. MT safe. @@ -33938,13 +35354,13 @@ MT safe. allow-none="1"> The object originating the message. + line="982">The object originating the message. the clock that was lost + line="983">the clock that was lost @@ -33953,17 +35369,17 @@ MT safe. c:identifier="gst_message_new_clock_provide"> Create a clock provide message. This message is posted whenever an + line="949">Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS). This message is mainly used internally to manage the clock selection. - + the new provide clock message. + line="962">the new provide clock message. MT safe. @@ -33975,19 +35391,19 @@ MT safe. allow-none="1"> The object originating the message. + line="951">The object originating the message. the clock it provides + line="952">the clock it provides %TRUE if the sender can provide a clock + line="953">%TRUE if the sender can provide a clock @@ -33995,14 +35411,14 @@ MT safe. Create a new custom-typed message. This can be used for anything not + line="276">Create a new custom-typed message. This can be used for anything not handled by other message-specific functions to pass a message to the app. The structure field can be %NULL. The new message. + line="287">The new message. MT safe. @@ -34011,7 +35427,7 @@ MT safe. The #GstMessageType to distinguish messages + line="278">The #GstMessageType to distinguish messages allow-none="1"> The object originating the message. + line="279">The object originating the message. allow-none="1"> the structure for the + line="280">the structure for the message. The message will take ownership of the structure. @@ -34040,14 +35456,14 @@ MT safe. version="1.4"> Creates a new device-added message. The device-added message is produced by + line="2720">Creates a new device-added message. The device-added message is produced by #GstDeviceProvider or a #GstDeviceMonitor. They announce the appearance of monitored devices. - + a newly allocated #GstMessage + line="2729">a newly allocated #GstMessage @@ -34057,13 +35473,13 @@ of monitored devices. allow-none="1"> The #GstObject that created the message + line="2722">The #GstObject that created the message The new #GstDevice + line="2723">The new #GstDevice @@ -34073,14 +35489,14 @@ of monitored devices. version="1.16"> Creates a new device-changed message. The device-changed message is produced + line="2824">Creates a new device-changed message. The device-changed message is produced by #GstDeviceProvider or a #GstDeviceMonitor. They announce that a device properties has changed and @device represent the new modified version of @changed_device. - + a newly allocated #GstMessage + line="2835">a newly allocated #GstMessage @@ -34090,20 +35506,20 @@ properties has changed and @device represent the new modified version of @change allow-none="1"> The #GstObject that created the message + line="2826">The #GstObject that created the message The newly created device representing @changed_device + line="2827">The newly created device representing @changed_device with its new configuration. The old version of the device. + line="2829">The old version of the device. @@ -34113,14 +35529,14 @@ properties has changed and @device represent the new modified version of @change version="1.4"> Creates a new device-removed message. The device-removed message is produced + line="2772">Creates a new device-removed message. The device-removed message is produced by #GstDeviceProvider or a #GstDeviceMonitor. They announce the disappearance of monitored devices. - + a newly allocated #GstMessage + line="2781">a newly allocated #GstMessage @@ -34130,13 +35546,13 @@ disappearance of monitored devices. allow-none="1"> The #GstObject that created the message + line="2774">The #GstObject that created the message The removed #GstDevice + line="2775">The removed #GstDevice @@ -34145,15 +35561,15 @@ disappearance of monitored devices. c:identifier="gst_message_new_duration_changed"> Create a new duration changed message. This message is posted by elements + line="1176">Create a new duration changed message. This message is posted by elements that know the duration of a stream when the duration changes. This message is received by bins and is used to calculate the total duration of a pipeline. - + The new duration-changed message. + line="1185">The new duration-changed message. MT safe. @@ -34165,7 +35581,7 @@ MT safe. allow-none="1"> The object originating the message. + line="1178">The object originating the message. @@ -34173,15 +35589,15 @@ MT safe. Create a new element-specific message. This is meant as a generic way of + line="1153">Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be %NULL. - + The new element message. + line="1164">The new element message. MT safe. @@ -34193,13 +35609,13 @@ MT safe. allow-none="1"> The object originating the message. + line="1155">The object originating the message. The structure for the + line="1156">The structure for the message. The message will take ownership of the structure. @@ -34208,14 +35624,14 @@ MT safe. Create a new eos message. This message is generated and posted in + line="375">Create a new eos message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message. - + The new eos message. + line="383">The new eos message. MT safe. @@ -34227,7 +35643,7 @@ MT safe. allow-none="1"> The object originating the message. + line="377">The object originating the message. @@ -34235,15 +35651,15 @@ MT safe. Create a new error message. The message will copy @error and + line="564">Create a new error message. The message will copy @error and @debug. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. - + the new error message. + line="575">the new error message. MT safe. @@ -34255,19 +35671,19 @@ MT safe. allow-none="1"> The object originating the message. + line="566">The object originating the message. The GError for this message. + line="567">The GError for this message. A debugging string. + line="568">A debugging string. @@ -34277,15 +35693,15 @@ MT safe. version="1.10"> Create a new error message. The message will copy @error and + line="525">Create a new error message. The message will copy @error and @debug. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. - + the new error message. + line="537">the new error message. @@ -34295,19 +35711,19 @@ receiving this message should stop the pipeline. allow-none="1"> The object originating the message. + line="527">The object originating the message. The GError for this message. + line="528">The GError for this message. A debugging string. + line="529">A debugging string. allow-none="1"> A GstStructure with details + line="530">A GstStructure with details @@ -34326,12 +35742,12 @@ receiving this message should stop the pipeline. version="1.2"> This message is posted when an element has a new local #GstContext. - + line="2670">This message is posted when an element has a new local #GstContext. + The new have-context message. + line="2677">The new have-context message. MT safe. @@ -34343,13 +35759,13 @@ MT safe. allow-none="1"> The object originating the message. + line="2672">The object originating the message. the context + line="2673">the context @@ -34357,13 +35773,13 @@ MT safe. Create a new info message. The message will make copies of @error and + line="764">Create a new info message. The message will make copies of @error and @debug. - + the new info message. + line="773">the new info message. MT safe. @@ -34375,19 +35791,19 @@ MT safe. allow-none="1"> The object originating the message. + line="766">The object originating the message. The GError for this message. + line="767">The GError for this message. A debugging string. + line="768">A debugging string. @@ -34397,13 +35813,13 @@ MT safe. version="1.10"> Create a new info message. The message will make copies of @error and + line="727">Create a new info message. The message will make copies of @error and @debug. - + the new warning message. + line="737">the new warning message. @@ -34413,19 +35829,19 @@ MT safe. allow-none="1"> The object originating the message. + line="729">The object originating the message. The GError for this message. + line="730">The GError for this message. A debugging string. + line="731">A debugging string. allow-none="1"> A GstStructure with details + line="732">A GstStructure with details @@ -34444,17 +35860,17 @@ MT safe. version="1.18"> Creates a new instant-rate-request message. Elements handling the + line="3390">Creates a new instant-rate-request message. Elements handling the instant-rate-change event must post this message. The message is handled at the pipeline, and allows the pipeline to select the running time when the rate change should happen and to send an @GST_EVENT_INSTANT_RATE_SYNC_TIME event to notify the elements in the pipeline. - + a newly allocated #GstMessage + line="3402">a newly allocated #GstMessage @@ -34464,13 +35880,13 @@ in the pipeline. allow-none="1"> The #GstObject that posted the message + line="3392">The #GstObject that posted the message the rate multiplier factor that should be applied + line="3393">the rate multiplier factor that should be applied @@ -34478,13 +35894,13 @@ in the pipeline. This message can be posted by elements when their latency requirements have + line="1248">This message can be posted by elements when their latency requirements have changed. - + The new latency message. + line="1255">The new latency message. MT safe. @@ -34496,7 +35912,7 @@ MT safe. allow-none="1"> The object originating the message. + line="1250">The object originating the message. @@ -34506,12 +35922,12 @@ MT safe. version="1.2"> This message is posted when an element needs a specific #GstContext. - + line="2611">This message is posted when an element needs a specific #GstContext. + The new need-context message. + line="2618">The new need-context message. MT safe. @@ -34523,13 +35939,13 @@ MT safe. allow-none="1"> The object originating the message. + line="2613">The object originating the message. The context type that is needed + line="2614">The context type that is needed @@ -34538,13 +35954,13 @@ MT safe. c:identifier="gst_message_new_new_clock"> Create a new clock message. This message is posted whenever the + line="1009">Create a new clock message. This message is posted whenever the pipeline selects a new clock for the pipeline. - + The new new clock message. + line="1017">The new new clock message. MT safe. @@ -34556,13 +35972,13 @@ MT safe. allow-none="1"> The object originating the message. + line="1011">The object originating the message. the new selected clock + line="1012">the new selected clock @@ -34570,16 +35986,16 @@ MT safe. Progress messages are posted by elements when they use an asynchronous task + line="2352">Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change. @code contains a well defined string describing the action. @text should contain a user visible string detailing the current action. - + The new qos message. + line="2365">The new qos message. @@ -34589,25 +36005,25 @@ to perform actions triggered by a state change. allow-none="1"> The object originating the message. + line="2354">The object originating the message. a #GstProgressType + line="2355">a #GstProgressType a progress code + line="2356">a progress code free, user visible text describing the progress + line="2357">free, user visible text describing the progress @@ -34615,24 +36031,24 @@ to perform actions triggered by a state change. - + a newly allocated #GstMessage + line="2894">a newly allocated #GstMessage The #GstObject whose property changed (may or may not be a #GstElement) + line="2890">The #GstObject whose property changed (may or may not be a #GstElement) name of the property that changed + line="2891">name of the property that changed new property value, or %NULL + line="2892">new property value, or %NULL @@ -34649,7 +36065,7 @@ to perform actions triggered by a state change. A QOS message is posted on the bus whenever an element decides to drop a + line="2130">A QOS message is posted on the bus whenever an element decides to drop a buffer because of QoS reasons or whenever it changes its processing strategy because of QoS reasons (quality adjustments such as processing at lower accuracy). @@ -34662,11 +36078,11 @@ events received from a downstream element (!live). respective running-time, stream-time, timestamp and duration of the (dropped) buffer that generated the QoS event. Values can be left to GST_CLOCK_TIME_NONE when unknown. - + The new qos message. + line="2153">The new qos message. MT safe. @@ -34678,37 +36094,37 @@ MT safe. allow-none="1"> The object originating the message. + line="2132">The object originating the message. if the message was generated by a live element + line="2133">if the message was generated by a live element the running time of the buffer that generated the message + line="2134">the running time of the buffer that generated the message the stream time of the buffer that generated the message + line="2135">the stream time of the buffer that generated the message the timestamps of the buffer that generated the message + line="2136">the timestamps of the buffer that generated the message the duration of the buffer that generated the message + line="2137">the duration of the buffer that generated the message @@ -34718,7 +36134,7 @@ MT safe. version="1.10"> Creates a new redirect message and adds a new entry to it. Redirect messages + line="3157">Creates a new redirect message and adds a new entry to it. Redirect messages are posted when an element detects that the actual data has to be retrieved from a different location. This is useful if such a redirection cannot be handled inside a source element, for example when HTTP 302/303 redirects @@ -34743,11 +36159,11 @@ bitrate tag. The specified location string is copied. However, ownership over the tag list and structure are transferred to the message. - + a newly allocated #GstMessage + line="3190">a newly allocated #GstMessage @@ -34757,13 +36173,13 @@ list and structure are transferred to the message. allow-none="1"> The #GstObject whose property changed (may or may not be a #GstElement) + line="3159">The #GstObject whose property changed (may or may not be a #GstElement) location string for the new entry + line="3160">location string for the new entry allow-none="1"> tag list for the new entry + line="3161">tag list for the new entry allow-none="1"> structure for the new entry + line="3162">structure for the new entry @@ -34790,14 +36206,14 @@ list and structure are transferred to the message. c:identifier="gst_message_new_request_state"> This message can be posted by elements when they want to have their state + line="1269">This message can be posted by elements when they want to have their state changed. A typical use case would be an audio server that wants to pause the pipeline because a higher priority stream is being played. - + the new request state message. + line="1278">the new request state message. MT safe. @@ -34809,13 +36225,13 @@ MT safe. allow-none="1"> The object originating the message. + line="1271">The object originating the message. The new requested state + line="1272">The new requested state @@ -34824,13 +36240,13 @@ MT safe. c:identifier="gst_message_new_reset_time"> This message is posted when the pipeline running-time should be reset to + line="2464">This message is posted when the pipeline running-time should be reset to @running_time, like after a flushing seek. - + The new reset_time message. + line="2472">The new reset_time message. MT safe. @@ -34842,13 +36258,13 @@ MT safe. allow-none="1"> The object originating the message. + line="2466">The object originating the message. the requested running-time + line="2467">the requested running-time @@ -34857,15 +36273,15 @@ MT safe. c:identifier="gst_message_new_segment_done"> Create a new segment done message. This message is posted by elements that + line="1102">Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done. - + the new segment done message. + line="1113">the new segment done message. MT safe. @@ -34877,19 +36293,19 @@ MT safe. allow-none="1"> The object originating the message. + line="1104">The object originating the message. The format of the position being done + line="1105">The format of the position being done The position of the segment being done + line="1106">The position of the segment being done @@ -34898,15 +36314,15 @@ MT safe. c:identifier="gst_message_new_segment_start"> Create a new segment message. This message is posted by elements that + line="1072">Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements. - + the new segment start message. + line="1083">the new segment start message. MT safe. @@ -34918,19 +36334,19 @@ MT safe. allow-none="1"> The object originating the message. + line="1074">The object originating the message. The format of the position being played + line="1075">The format of the position being played The position of the segment being played + line="1076">The position of the segment being played @@ -34939,13 +36355,13 @@ MT safe. c:identifier="gst_message_new_state_changed"> Create a state change message. This message is posted whenever an element + line="897">Create a state change message. This message is posted whenever an element changed its state. - + the new state change message. + line="907">the new state change message. MT safe. @@ -34957,25 +36373,25 @@ MT safe. allow-none="1"> The object originating the message. + line="899">The object originating the message. the previous state + line="900">the previous state the new (current) state + line="901">the new (current) state the pending (target) state + line="902">the pending (target) state @@ -34984,14 +36400,14 @@ MT safe. c:identifier="gst_message_new_state_dirty"> Create a state dirty message. This message is posted whenever an element + line="927">Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects. - + the new state dirty message. + line="935">the new state dirty message. MT safe. @@ -35003,7 +36419,7 @@ MT safe. allow-none="1"> The object originating the message + line="929">The object originating the message @@ -35012,16 +36428,16 @@ MT safe. c:identifier="gst_message_new_step_done"> This message is posted by elements when they complete a part, when @intermediate set + line="1976">This message is posted by elements when they complete a part, when @intermediate set to %TRUE, or a complete step operation. @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped @amount of media in format @format. - + the new step_done message. + line="1993">the new step_done message. MT safe. @@ -35033,49 +36449,49 @@ MT safe. allow-none="1"> The object originating the message. + line="1978">The object originating the message. the format of @amount + line="1979">the format of @amount the amount of stepped data + line="1980">the amount of stepped data the rate of the stepped amount + line="1981">the rate of the stepped amount is this an flushing step + line="1982">is this an flushing step is this an intermediate step + line="1983">is this an intermediate step the duration of the data + line="1984">the duration of the data the step caused EOS + line="1985">the step caused EOS @@ -35084,7 +36500,7 @@ MT safe. c:identifier="gst_message_new_step_start"> This message is posted by elements when they accept or activate a new step + line="2052">This message is posted by elements when they accept or activate a new step event for @amount in @format. @active is set to %FALSE when the element accepted the new step event and has @@ -35094,11 +36510,11 @@ queued it for execution in the streaming threads. is now ready to start executing the step in the streaming thread. After this message is emitted, the application can queue a new step operation in the element. - + The new step_start message. + line="2073">The new step_start message. MT safe. @@ -35110,43 +36526,43 @@ MT safe. allow-none="1"> The object originating the message. + line="2054">The object originating the message. if the step is active or queued + line="2055">if the step is active or queued the format of @amount + line="2056">the format of @amount the amount of stepped data + line="2057">the amount of stepped data the rate of the stepped amount + line="2058">the rate of the stepped amount is this an flushing step + line="2059">is this an flushing step is this an intermediate step + line="2060">is this an intermediate step @@ -35156,13 +36572,13 @@ MT safe. version="1.10"> Creates a new stream-collection message. The message is used to announce new + line="2960">Creates a new stream-collection message. The message is used to announce new #GstStreamCollection - + a newly allocated #GstMessage + line="2968">a newly allocated #GstMessage @@ -35172,13 +36588,13 @@ MT safe. allow-none="1"> The #GstObject that created the message + line="2962">The #GstObject that created the message The #GstStreamCollection + line="2963">The #GstStreamCollection @@ -35187,14 +36603,14 @@ MT safe. c:identifier="gst_message_new_stream_start"> Create a new stream_start message. This message is generated and posted in + line="2516">Create a new stream_start message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message. - + The new stream_start message. + line="2524">The new stream_start message. MT safe. @@ -35206,7 +36622,7 @@ MT safe. allow-none="1"> The object originating the message. + line="2518">The object originating the message. @@ -35215,13 +36631,13 @@ MT safe. c:identifier="gst_message_new_stream_status"> Create a new stream status message. This message is posted when a streaming + line="1867">Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed. - + the new stream status message. + line="1876">the new stream status message. MT safe. @@ -35233,19 +36649,19 @@ MT safe. allow-none="1"> The object originating the message. + line="1869">The object originating the message. The stream status type. + line="1870">The stream status type. the owner element of @src. + line="1871">the owner element of @src. @@ -35255,7 +36671,7 @@ MT safe. version="1.10"> Creates a new steams-selected message. The message is used to announce + line="3014">Creates a new steams-selected message. The message is used to announce that an array of streams has been selected. This is generally in response to a #GST_EVENT_SELECT_STREAMS event, or when an element (such as decodebin3) makes an initial selection of streams. @@ -35265,11 +36681,11 @@ belong to. Users of gst_message_new_streams_selected() can add the selected streams with gst_message_streams_selected_add(). - + a newly allocated #GstMessage + line="3030">a newly allocated #GstMessage @@ -35279,13 +36695,13 @@ gst_message_streams_selected_add(). allow-none="1"> The #GstObject that created the message + line="3016">The #GstObject that created the message The #GstStreamCollection + line="3017">The #GstStreamCollection @@ -35294,16 +36710,16 @@ gst_message_streams_selected_add(). c:identifier="gst_message_new_structure_change"> Create a new structure change message. This message is posted when the + line="1034">Create a new structure change message. This message is posted when the structure of a pipeline is in the process of being changed, for example when pads are linked or unlinked. @src should be the sinkpad that unlinked or linked. - + the new structure change message. + line="1047">the new structure change message. MT safe. @@ -35315,25 +36731,25 @@ MT safe. allow-none="1"> The object originating the message. + line="1036">The object originating the message. The change type. + line="1037">The change type. The owner element of @src. + line="1038">The owner element of @src. Whether the structure change is busy. + line="1039">Whether the structure change is busy. @@ -35341,13 +36757,13 @@ MT safe. Create a new tag message. The message will take ownership of the tag list. + line="826">Create a new tag message. The message will take ownership of the tag list. The message is posted by elements that discovered a new taglist. - + the new tag message. + line="834">the new tag message. MT safe. @@ -35359,13 +36775,13 @@ MT safe. allow-none="1"> The object originating the message. + line="828">The object originating the message. the tag list for the message. + line="829">the tag list for the message. @@ -35373,13 +36789,13 @@ MT safe. Create a new TOC message. The message is posted by elements + line="2415">Create a new TOC message. The message is posted by elements that discovered or updated a TOC. - + a new TOC message. + line="2424">a new TOC message. MT safe. @@ -35391,19 +36807,19 @@ MT safe. allow-none="1"> the object originating the message. + line="2417">the object originating the message. #GstToc structure for the message. + line="2418">#GstToc structure for the message. whether TOC was updated or not. + line="2419">whether TOC was updated or not. @@ -35411,13 +36827,13 @@ MT safe. Create a new warning message. The message will make copies of @error and + line="665">Create a new warning message. The message will make copies of @error and @debug. - + the new warning message. + line="674">the new warning message. MT safe. @@ -35429,19 +36845,19 @@ MT safe. allow-none="1"> The object originating the message. + line="667">The object originating the message. The GError for this message. + line="668">The GError for this message. A debugging string. + line="669">A debugging string. @@ -35451,13 +36867,13 @@ MT safe. version="1.10"> Create a new warning message. The message will make copies of @error and + line="628">Create a new warning message. The message will make copies of @error and @debug. - + the new warning message. + line="638">the new warning message. @@ -35467,19 +36883,19 @@ MT safe. allow-none="1"> The object originating the message. + line="630">The object originating the message. The GError for this message. + line="631">The GError for this message. A debugging string. + line="632">A debugging string. allow-none="1"> A GstStructure with details + line="633">A GstStructure with details @@ -35498,11 +36914,11 @@ MT safe. version="1.10"> Creates and appends a new entry. + line="3226">Creates and appends a new entry. The specified location string is copied. However, ownership over the tag list and structure are transferred to the message. - + @@ -35510,13 +36926,13 @@ list and structure are transferred to the message. a #GstMessage of type %GST_MESSAGE_REDIRECT + line="3228">a #GstMessage of type %GST_MESSAGE_REDIRECT location string for the new entry + line="3229">location string for the new entry allow-none="1"> tag list for the new entry + line="3230">tag list for the new entry allow-none="1"> structure for the new entry + line="3231">structure for the new entry @@ -35542,12 +36958,12 @@ list and structure are transferred to the message. Creates a copy of the message. Returns a copy of the message. + line="3491">Creates a copy of the message. Returns a copy of the message. a new copy of @msg. + line="3497">a new copy of @msg. MT safe @@ -35556,26 +36972,50 @@ MT safe the message to copy + line="3493">the message to copy + + Returns the optional details structure of the message. May be NULL if none. + +The returned structure must not be freed. + + + The details, or NULL if none. + + + + + A #GstMessage + + + + - + the number of entries stored in the message + line="3353">the number of entries stored in the message a #GstMessage of type %GST_MESSAGE_REDIRECT + line="3351">a #GstMessage of type %GST_MESSAGE_REDIRECT @@ -35583,7 +37023,7 @@ MT safe Retrieve the sequence number of a message. + line="324">Retrieve the sequence number of a message. Messages have ever-incrementing sequence numbers, which may also be set explicitly via gst_message_set_seqnum(). Sequence numbers are typically used @@ -35595,11 +37035,11 @@ it is not required. Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly. - + The message's sequence number. + line="341">The message's sequence number. MT safe. @@ -35608,7 +37048,7 @@ MT safe. A #GstMessage. + line="326">A #GstMessage. @@ -35617,12 +37057,12 @@ MT safe. c:identifier="gst_message_get_stream_status_object"> Extracts the object managing the streaming thread from @message. - + line="1949">Extracts the object managing the streaming thread from @message. + a GValue containing the object that manages the + line="1955">a GValue containing the object that manages the streaming thread. This object is usually of type GstTask but other types can be added in the future. The object remains valid as long as @message is valid. @@ -35632,7 +37072,7 @@ valid. A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. + line="1951">A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. @@ -35640,12 +37080,12 @@ valid. Access the structure of the message. + line="1295">Access the structure of the message. The structure of the message. The + line="1301">The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. @@ -35656,7 +37096,7 @@ MT safe. The #GstMessage. + line="1297">The #GstMessage. @@ -35664,26 +37104,26 @@ MT safe. Checks if @message has the given @name. This function is usually used to + line="1352">Checks if @message has the given @name. This function is usually used to check the name of a custom message. %TRUE if @name matches the name of the message structure. + line="1360">%TRUE if @name matches the name of the message structure. The #GstMessage. + line="1354">The #GstMessage. name to check + line="1355">name to check @@ -35692,10 +37132,10 @@ check the name of a custom message. c:identifier="gst_message_parse_async_done"> Extract the running_time from the async_done message. + line="1820">Extract the running_time from the async_done message. MT safe. - + @@ -35703,7 +37143,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE. + line="1822">A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE. allow-none="1"> Result location for the running_time or %NULL + line="1823">Result location for the running_time or %NULL @@ -35723,11 +37163,11 @@ MT safe. c:identifier="gst_message_parse_buffering"> Extracts the buffering percent from the GstMessage. see also + line="1415">Extracts the buffering percent from the GstMessage. see also gst_message_new_buffering(). MT safe. - + @@ -35735,7 +37175,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_BUFFERING. + line="1417">A valid #GstMessage of type GST_MESSAGE_BUFFERING. allow-none="1"> Return location for the percent. + line="1418">Return location for the percent. @@ -35755,8 +37195,8 @@ MT safe. c:identifier="gst_message_parse_buffering_stats"> Extracts the buffering stats values from @message. - + line="1461">Extracts the buffering stats values from @message. + @@ -35764,7 +37204,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_BUFFERING. + line="1463">A valid #GstMessage of type GST_MESSAGE_BUFFERING. allow-none="1"> a buffering mode, or %NULL + line="1464">a buffering mode, or %NULL allow-none="1"> the average input rate, or %NULL + line="1465">the average input rate, or %NULL allow-none="1"> the average output rate, or %NULL + line="1466">the average output rate, or %NULL allow-none="1"> amount of buffering time left in + line="1467">amount of buffering time left in milliseconds, or %NULL @@ -35818,11 +37258,11 @@ MT safe. c:identifier="gst_message_parse_clock_lost"> Extracts the lost clock from the GstMessage. + line="1582">Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. - + @@ -35830,7 +37270,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST. + line="1584">A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST. allow-none="1"> a pointer to hold the lost clock + line="1585">a pointer to hold the lost clock @@ -35850,11 +37290,11 @@ MT safe. c:identifier="gst_message_parse_clock_provide"> Extracts the clock and ready flag from the GstMessage. + line="1549">Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. - + @@ -35862,7 +37302,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. + line="1551">A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. allow-none="1"> a pointer to hold a clock + line="1552">a pointer to hold a clock object, or %NULL @@ -35885,7 +37325,7 @@ MT safe. allow-none="1"> a pointer to hold the ready flag, or %NULL + line="1554">a pointer to hold the ready flag, or %NULL @@ -35895,19 +37335,19 @@ MT safe. version="1.2"> Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. - + line="2639">Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. + a #gboolean indicating if the parsing succeeded. + line="2646">a #gboolean indicating if the parsing succeeded. a GST_MESSAGE_NEED_CONTEXT type message + line="2641">a GST_MESSAGE_NEED_CONTEXT type message allow-none="1"> the context type, or %NULL + line="2642">the context type, or %NULL @@ -35928,10 +37368,10 @@ MT safe. version="1.4"> Parses a device-added message. The device-added message is produced by + line="2749">Parses a device-added message. The device-added message is produced by #GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance of monitored devices. - + @@ -35939,7 +37379,7 @@ of monitored devices. a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED + line="2751">a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED allow-none="1"> A location where to store a + line="2752">A location where to store a pointer to the new #GstDevice, or %NULL @@ -35961,11 +37401,11 @@ of monitored devices. version="1.16"> Parses a device-changed message. The device-changed message is produced by + line="2857">Parses a device-changed message. The device-changed message is produced by #GstDeviceProvider or a #GstDeviceMonitor. It announces the disappearance of monitored devices. * It announce that a device properties has changed and @device represents the new modified version of @changed_device. - + @@ -35973,7 +37413,7 @@ changed and @device represents the new modified version of @changed_device. a #GstMessage of type %GST_MESSAGE_DEVICE_CHANGED + line="2859">a #GstMessage of type %GST_MESSAGE_DEVICE_CHANGED A location where to store a + line="2860">A location where to store a pointer to the updated version of the #GstDevice, or %NULL @@ -35996,7 +37436,7 @@ changed and @device represents the new modified version of @changed_device. A location where to store a + line="2862">A location where to store a pointer to the old version of the #GstDevice, or %NULL @@ -36007,10 +37447,10 @@ changed and @device represents the new modified version of @changed_device. Parses a device-removed message. The device-removed message is produced by + line="2801">Parses a device-removed message. The device-removed message is produced by #GstDeviceProvider or a #GstDeviceMonitor. It announces the disappearance of monitored devices. - + @@ -36018,7 +37458,7 @@ disappearance of monitored devices. a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED + line="2803">a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED allow-none="1"> A location where to store a + line="2804">A location where to store a pointer to the removed #GstDevice, or %NULL @@ -36038,7 +37478,7 @@ disappearance of monitored devices. Extracts the GError and debug string from the GstMessage. The values returned + line="1676">Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. Typical usage of this function might be: @@ -36063,7 +37503,7 @@ Typical usage of this function might be: ]| MT safe. - + @@ -36071,7 +37511,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_ERROR. + line="1678">A valid #GstMessage of type GST_MESSAGE_ERROR. allow-none="1"> location for the GError + line="1679">location for the GError allow-none="1"> location for the debug message, + line="1680">location for the debug message, or %NULL @@ -36105,9 +37545,9 @@ MT safe. version="1.10"> Returns the optional details structure, may be NULL if none. + line="585">Returns the optional details structure, may be NULL if none. The returned structure must not be freed. - + @@ -36115,7 +37555,7 @@ The returned structure must not be freed. The message object + line="587">The message object allow-none="1"> A pointer to the returned details + line="588">A pointer to the returned details + + Returns the details structure if present or will create one if not present. +The returned structure must not be freed. + + + + + + + The writable message object + + + + A pointer to the returned details + + + + Extract the group from the STREAM_START message. - + line="2572">Extract the group from the STREAM_START message. + %TRUE if the message had a group id set, %FALSE otherwise + line="2580">%TRUE if the message had a group id set, %FALSE otherwise MT safe. @@ -36151,7 +37623,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_STREAM_START. + line="2574">A valid #GstMessage of type GST_MESSAGE_STREAM_START. allow-none="1"> Result location for the group id or + line="2575">Result location for the group id or %NULL @@ -36173,10 +37645,10 @@ MT safe. version="1.2"> Extract the context from the HAVE_CONTEXT message. + line="2697">Extract the context from the HAVE_CONTEXT message. MT safe. - + @@ -36184,7 +37656,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_HAVE_CONTEXT. + line="2699">A valid #GstMessage of type GST_MESSAGE_HAVE_CONTEXT. allow-none="1"> Result location for the + line="2700">Result location for the context or %NULL @@ -36204,11 +37676,11 @@ MT safe. Extracts the GError and debug string from the GstMessage. The values returned + line="1742">Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe. - + @@ -36216,7 +37688,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_INFO. + line="1744">A valid #GstMessage of type GST_MESSAGE_INFO. allow-none="1"> location for the GError + line="1745">location for the GError allow-none="1"> location for the debug message, + line="1746">location for the debug message, or %NULL @@ -36250,9 +37722,9 @@ MT safe. version="1.10"> Returns the optional details structure, may be NULL if none + line="783">Returns the optional details structure, may be NULL if none The returned structure must not be freed. - + @@ -36260,7 +37732,7 @@ The returned structure must not be freed. The message object + line="785">The message object allow-none="1"> A pointer to the returned details + line="786">A pointer to the returned details + + Returns the details structure if present or will create one if not present. +The returned structure must not be freed. + + + + + + + The writable message object + + + + A pointer to the returned details + + + + Parses the rate_multiplier from the instant-rate-request message. - + line="3422">Parses the rate_multiplier from the instant-rate-request message. + @@ -36291,7 +37795,7 @@ The returned structure must not be freed. a #GstMessage of type %GST_MESSAGE_INSTANT_RATE_REQUEST + line="3424">a #GstMessage of type %GST_MESSAGE_INSTANT_RATE_REQUEST allow-none="1"> return location for the rate, or %NULL + line="3425">return location for the rate, or %NULL @@ -36311,11 +37815,11 @@ The returned structure must not be freed. c:identifier="gst_message_parse_new_clock"> Extracts the new clock from the GstMessage. + line="1610">Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. - + @@ -36323,7 +37827,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK. + line="1612">A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK. allow-none="1"> a pointer to hold the selected + line="1613">a pointer to hold the selected new clock @@ -36343,8 +37847,8 @@ MT safe. Parses the progress @type, @code and @text. - + line="2391">Parses the progress @type, @code and @text. + @@ -36352,7 +37856,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_PROGRESS. + line="2393">A valid #GstMessage of type GST_MESSAGE_PROGRESS. allow-none="1"> location for the type + line="2394">location for the type allow-none="1"> location for the code + line="2395">location for the code allow-none="1"> location for the text + line="2396">location for the text @@ -36395,10 +37899,10 @@ MT safe. version="1.10"> Parses a property-notify message. These will be posted on the bus only + line="2919">Parses a property-notify message. These will be posted on the bus only when set up with gst_element_add_property_notify_watch() or gst_element_add_property_deep_notify_watch(). - + @@ -36406,7 +37910,7 @@ gst_element_add_property_deep_notify_watch(). a #GstMessage of type %GST_MESSAGE_PROPERTY_NOTIFY + line="2921">a #GstMessage of type %GST_MESSAGE_PROPERTY_NOTIFY allow-none="1"> location where to store a + line="2922">location where to store a pointer to the object whose property got changed, or %NULL @@ -36429,7 +37933,7 @@ gst_element_add_property_deep_notify_watch(). allow-none="1"> return location for + line="2924">return location for the name of the property that got changed, or %NULL @@ -36442,7 +37946,7 @@ gst_element_add_property_deep_notify_watch(). allow-none="1"> return location for + line="2926">return location for the new value of the property that got changed, or %NULL. This will only be set if the property notify watch was told to include the value when it was set up @@ -36453,14 +37957,14 @@ gst_element_add_property_deep_notify_watch(). Extract the timestamps and live status from the QoS message. + line="2245">Extract the timestamps and live status from the QoS message. The returned values give the running_time, stream_time, timestamp and duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown values. MT safe. - + @@ -36468,7 +37972,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_QOS. + line="2247">A valid #GstMessage of type GST_MESSAGE_QOS. allow-none="1"> if the message was generated by a live element + line="2248">if the message was generated by a live element allow-none="1"> the running time of the buffer that + line="2249">the running time of the buffer that generated the message @@ -36502,7 +38006,7 @@ MT safe. allow-none="1"> the stream time of the buffer that + line="2251">the stream time of the buffer that generated the message @@ -36514,7 +38018,7 @@ MT safe. allow-none="1"> the timestamps of the buffer that + line="2253">the timestamps of the buffer that generated the message @@ -36526,7 +38030,7 @@ MT safe. allow-none="1"> the duration of the buffer that + line="2255">the duration of the buffer that generated the message @@ -36536,14 +38040,14 @@ MT safe. c:identifier="gst_message_parse_qos_stats"> Extract the QoS stats representing the history of the current continuous + line="2316">Extract the QoS stats representing the history of the current continuous pipeline playback period. When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are invalid. Values of -1 for either @processed or @dropped mean unknown values. MT safe. - + @@ -36551,7 +38055,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_QOS. + line="2318">A valid #GstMessage of type GST_MESSAGE_QOS. allow-none="1"> Units of the 'processed' and 'dropped' fields. + line="2319">Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples). @@ -36576,7 +38080,7 @@ MT safe. allow-none="1"> Total number of units correctly processed + line="2323">Total number of units correctly processed since the last state change to READY or a flushing operation. @@ -36588,7 +38092,7 @@ MT safe. allow-none="1"> Total number of units dropped since the last + line="2325">Total number of units dropped since the last state change to READY or a flushing operation. @@ -36598,10 +38102,10 @@ MT safe. c:identifier="gst_message_parse_qos_values"> Extract the QoS values that have been calculated/analysed from the QoS data + line="2285">Extract the QoS values that have been calculated/analysed from the QoS data MT safe. - + @@ -36609,7 +38113,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_QOS. + line="2287">A valid #GstMessage of type GST_MESSAGE_QOS. allow-none="1"> The difference of the running-time against + line="2288">The difference of the running-time against the deadline. @@ -36632,7 +38136,7 @@ MT safe. allow-none="1"> Long term prediction of the ideal rate + line="2290">Long term prediction of the ideal rate relative to normal rate to get optimal quality. @@ -36644,7 +38148,7 @@ MT safe. allow-none="1"> An element dependent integer value that + line="2292">An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000. @@ -36656,10 +38160,10 @@ MT safe. version="1.10"> Parses the location and/or structure from the entry with the given index. + line="3284">Parses the location and/or structure from the entry with the given index. The index must be between 0 and gst_message_get_num_redirect_entries() - 1. Returned pointers are valid for as long as this message exists. - + @@ -36667,13 +38171,13 @@ Returned pointers are valid for as long as this message exists. a #GstMessage of type %GST_MESSAGE_REDIRECT + line="3286">a #GstMessage of type %GST_MESSAGE_REDIRECT index of the entry to parse + line="3287">index of the entry to parse allow-none="1"> return location for + line="3288">return location for the pointer to the entry's location string, or %NULL @@ -36697,7 +38201,7 @@ Returned pointers are valid for as long as this message exists. allow-none="1"> return location for + line="3290">return location for the pointer to the entry's tag list, or %NULL @@ -36710,7 +38214,7 @@ Returned pointers are valid for as long as this message exists. allow-none="1"> return location + line="3292">return location for the pointer to the entry's structure, or %NULL @@ -36720,10 +38224,10 @@ Returned pointers are valid for as long as this message exists. c:identifier="gst_message_parse_request_state"> Extract the requested state from the request_state message. + line="1844">Extract the requested state from the request_state message. MT safe. - + @@ -36731,7 +38235,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE. + line="1846">A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE. allow-none="1"> Result location for the requested state or %NULL + line="1847">Result location for the requested state or %NULL @@ -36751,10 +38255,10 @@ MT safe. c:identifier="gst_message_parse_reset_time"> Extract the running-time from the RESET_TIME message. + line="2491">Extract the running-time from the RESET_TIME message. MT safe. - + @@ -36762,7 +38266,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_RESET_TIME. + line="2493">A valid #GstMessage of type GST_MESSAGE_RESET_TIME. allow-none="1"> Result location for the running_time or + line="2494">Result location for the running_time or %NULL @@ -36783,10 +38287,10 @@ MT safe. c:identifier="gst_message_parse_segment_done"> Extracts the position and format from the segment done message. + line="1792">Extracts the position and format from the segment done message. MT safe. - + @@ -36794,7 +38298,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE. + line="1794">A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE. allow-none="1"> Result location for the format, or %NULL + line="1795">Result location for the format, or %NULL allow-none="1"> Result location for the position, or %NULL + line="1796">Result location for the position, or %NULL @@ -36825,10 +38329,10 @@ MT safe. c:identifier="gst_message_parse_segment_start"> Extracts the position and format from the segment start message. + line="1764">Extracts the position and format from the segment start message. MT safe. - + @@ -36836,7 +38340,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_SEGMENT_START. + line="1766">A valid #GstMessage of type GST_MESSAGE_SEGMENT_START. allow-none="1"> Result location for the format, or %NULL + line="1767">Result location for the format, or %NULL allow-none="1"> Result location for the position, or %NULL + line="1768">Result location for the position, or %NULL @@ -36867,7 +38371,7 @@ MT safe. c:identifier="gst_message_parse_state_changed"> Extracts the old and new states from the GstMessage. + line="1498">Extracts the old and new states from the GstMessage. Typical usage of this function might be: |[<!-- language="C" --> @@ -36889,7 +38393,7 @@ Typical usage of this function might be: ]| MT safe. - + @@ -36897,7 +38401,7 @@ MT safe. a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED + line="1500">a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED allow-none="1"> the previous state, or %NULL + line="1501">the previous state, or %NULL allow-none="1"> the new (current) state, or %NULL + line="1502">the new (current) state, or %NULL allow-none="1"> the pending (target) state, or %NULL + line="1503">the pending (target) state, or %NULL @@ -36939,10 +38443,10 @@ MT safe. c:identifier="gst_message_parse_step_done"> Extract the values the step_done message. + line="2017">Extract the values the step_done message. MT safe. - + @@ -36950,7 +38454,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_STEP_DONE. + line="2019">A valid #GstMessage of type GST_MESSAGE_STEP_DONE. allow-none="1"> result location for the format + line="2020">result location for the format allow-none="1"> result location for the amount + line="2021">result location for the amount allow-none="1"> result location for the rate + line="2022">result location for the rate allow-none="1"> result location for the flush flag + line="2023">result location for the flush flag allow-none="1"> result location for the intermediate flag + line="2024">result location for the intermediate flag allow-none="1"> result location for the duration + line="2025">result location for the duration allow-none="1"> result location for the EOS flag + line="2026">result location for the EOS flag @@ -37036,10 +38540,10 @@ MT safe. c:identifier="gst_message_parse_step_start"> Extract the values from step_start message. + line="2096">Extract the values from step_start message. MT safe. - + @@ -37047,7 +38551,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_STEP_DONE. + line="2098">A valid #GstMessage of type GST_MESSAGE_STEP_DONE. allow-none="1"> result location for the active flag + line="2099">result location for the active flag allow-none="1"> result location for the format + line="2100">result location for the format allow-none="1"> result location for the amount + line="2101">result location for the amount allow-none="1"> result location for the rate + line="2102">result location for the rate allow-none="1"> result location for the flush flag + line="2103">result location for the flush flag allow-none="1"> result location for the intermediate flag + line="2104">result location for the intermediate flag @@ -37123,8 +38627,8 @@ MT safe. version="1.10"> Parses a stream-collection message. - + line="2991">Parses a stream-collection message. + @@ -37132,7 +38636,7 @@ MT safe. a #GstMessage of type %GST_MESSAGE_STREAM_COLLECTION + line="2993">a #GstMessage of type %GST_MESSAGE_STREAM_COLLECTION allow-none="1"> A location where to store a + line="2994">A location where to store a pointer to the #GstStreamCollection, or %NULL @@ -37153,12 +38657,12 @@ MT safe. c:identifier="gst_message_parse_stream_status"> Extracts the stream status type and owner the GstMessage. The returned + line="1895">Extracts the stream status type and owner the GstMessage. The returned owner remains valid for as long as the reference to @message is valid and should thus not be unreffed. MT safe. - + @@ -37166,7 +38670,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. + line="1897">A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. transfer-ownership="full"> A pointer to hold the status type + line="1898">A pointer to hold the status type transfer-ownership="none"> The owner element of the message source + line="1899">The owner element of the message source @@ -37194,8 +38698,8 @@ MT safe. version="1.10"> Parses a streams-selected message. - + line="3135">Parses a streams-selected message. + @@ -37203,7 +38707,7 @@ MT safe. a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + line="3137">a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED allow-none="1"> A location where to store a + line="3138">A location where to store a pointer to the #GstStreamCollection, or %NULL @@ -37224,10 +38728,10 @@ MT safe. c:identifier="gst_message_parse_structure_change"> Extracts the change type and completion status from the GstMessage. + line="1639">Extracts the change type and completion status from the GstMessage. MT safe. - + @@ -37235,7 +38739,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE. + line="1641">A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE. transfer-ownership="full"> A pointer to hold the change type + line="1642">A pointer to hold the change type allow-none="1"> The owner element of the + line="1643">The owner element of the message source @@ -37267,7 +38771,7 @@ MT safe. allow-none="1"> a pointer to hold whether the change is in + line="1645">a pointer to hold whether the change is in progress or has been completed @@ -37276,7 +38780,7 @@ MT safe. Extracts the tag list from the GstMessage. The tag list returned in the + line="1376">Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done. Typical usage of this function might be: @@ -37298,7 +38802,7 @@ Typical usage of this function might be: ]| MT safe. - + @@ -37306,7 +38810,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_TAG. + line="1378">A valid #GstMessage of type GST_MESSAGE_TAG. transfer-ownership="full"> return location for the tag-list. + line="1379">return location for the tag-list. @@ -37323,12 +38827,12 @@ MT safe. Extract the TOC from the #GstMessage. The TOC returned in the + line="2441">Extract the TOC from the #GstMessage. The TOC returned in the output argument is a copy; the caller must free it with gst_toc_unref() when done. MT safe. - + @@ -37336,7 +38840,7 @@ MT safe. a valid #GstMessage of type GST_MESSAGE_TOC. + line="2443">a valid #GstMessage of type GST_MESSAGE_TOC. transfer-ownership="full"> return location for the TOC. + line="2444">return location for the TOC. transfer-ownership="full"> return location for the updated flag. + line="2445">return location for the updated flag. @@ -37362,11 +38866,11 @@ MT safe. Extracts the GError and debug string from the GstMessage. The values returned + line="1719">Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe. - + @@ -37374,7 +38878,7 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_WARNING. + line="1721">A valid #GstMessage of type GST_MESSAGE_WARNING. allow-none="1"> location for the GError + line="1722">location for the GError allow-none="1"> location for the debug message, + line="1723">location for the debug message, or %NULL @@ -37408,9 +38912,9 @@ MT safe. version="1.10"> Returns the optional details structure, may be NULL if none + line="684">Returns the optional details structure, may be NULL if none The returned structure must not be freed. - + @@ -37418,7 +38922,7 @@ The returned structure must not be freed. The message object + line="686">The message object allow-none="1"> A pointer to the returned details + line="687">A pointer to the returned details + + Returns the details structure if present or will create one if not present. +The returned structure must not be freed. + + + + + + + The writable message object + + + + A pointer to the returned details + + + + Configures the buffering stats values in @message. - + line="1437">Configures the buffering stats values in @message. + @@ -37448,41 +38984,70 @@ The returned structure must not be freed. A valid #GstMessage of type GST_MESSAGE_BUFFERING. + line="1439">A valid #GstMessage of type GST_MESSAGE_BUFFERING. a buffering mode + line="1440">a buffering mode the average input rate + line="1441">the average input rate the average output rate + line="1442">the average output rate amount of buffering time left in milliseconds + line="1443">amount of buffering time left in milliseconds + + Add @details to @message. Will fail if the message already has details set on +it or if it is not writable. + + + + + + + A #GstMessage + + + + A GstStructure with details + + + + Sets the group id on the stream-start message. + line="2541">Sets the group id on the stream-start message. All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the @@ -37491,7 +39056,7 @@ each time the stream is started, resulting in different group ids each time a file is played for example. MT safe. - + @@ -37499,13 +39064,13 @@ MT safe. the message + line="2543">the message the group id + line="2544">the group id @@ -37513,14 +39078,14 @@ MT safe. Set the QoS stats representing the history of the current continuous pipeline + line="2210">Set the QoS stats representing the history of the current continuous pipeline playback period. When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are invalid. Values of -1 for either @processed or @dropped mean unknown values. MT safe. - + @@ -37528,13 +39093,13 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_QOS. + line="2212">A valid #GstMessage of type GST_MESSAGE_QOS. Units of the 'processed' and 'dropped' fields. Video sinks and video + line="2213">Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples). @@ -37542,14 +39107,14 @@ will likely use GST_FORMAT_DEFAULT (samples). Total number of units correctly processed since the last state + line="2216">Total number of units correctly processed since the last state change to READY or a flushing operation. Total number of units dropped since the last state change to READY + line="2218">Total number of units dropped since the last state change to READY or a flushing operation. @@ -37558,10 +39123,10 @@ or a flushing operation. Set the QoS values that have been calculated/analysed from the QoS data + line="2181">Set the QoS values that have been calculated/analysed from the QoS data MT safe. - + @@ -37569,26 +39134,26 @@ MT safe. A valid #GstMessage of type GST_MESSAGE_QOS. + line="2183">A valid #GstMessage of type GST_MESSAGE_QOS. The difference of the running-time against the deadline. + line="2184">The difference of the running-time against the deadline. Long term prediction of the ideal rate relative to normal rate + line="2185">Long term prediction of the ideal rate relative to normal rate to get optimal quality. An element dependent integer value that specifies the current + line="2187">An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000. @@ -37597,14 +39162,14 @@ quality level of the element. The default maximum quality is 1000000. Set the sequence number of a message. + line="353">Set the sequence number of a message. This function might be called by the creator of a message to indicate that the message relates to other messages or events. See gst_message_get_seqnum() for more information. MT safe. - + @@ -37612,13 +39177,13 @@ MT safe. A #GstMessage. + line="355">A #GstMessage. A sequence number. + line="356">A sequence number. @@ -37627,9 +39192,9 @@ MT safe. c:identifier="gst_message_set_stream_status_object"> Configures the object handling the streaming thread. This is usually a + line="1928">Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future. - + @@ -37637,13 +39202,13 @@ GstTask object but other objects might be added in the future. A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. + line="1930">A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. the object controlling the streaming + line="1931">the object controlling the streaming @@ -37653,8 +39218,8 @@ GstTask object but other objects might be added in the future. version="1.10"> Adds the @stream to the @message. - + line="3079">Adds the @stream to the @message. + @@ -37662,13 +39227,13 @@ GstTask object but other objects might be added in the future. a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + line="3081">a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED a #GstStream to add to @message + line="3082">a #GstStream to add to @message @@ -37678,19 +39243,19 @@ GstTask object but other objects might be added in the future. version="1.10"> Returns the number of streams contained in the @message. - + line="3056">Returns the number of streams contained in the @message. + The number of streams contained within. + line="3062">The number of streams contained within. a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + line="3058">a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED @@ -37700,40 +39265,66 @@ GstTask object but other objects might be added in the future. version="1.10"> Retrieves the #GstStream with index @index from the @message. - + line="3106">Retrieves the #GstStream with index @index from the @message. + A #GstStream + line="3113">A #GstStream a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + line="3108">a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED Index of the stream to retrieve + line="3109">Index of the stream to retrieve + + Returns the details structure of the @message. If not present it will be +created. Use this function (instead of gst_message_get_details()) if you +want to write to the @details structure. + +The returned structure must not be freed. + + + The details + + + + + A writable #GstMessage + + + + Get a writable version of the structure. + line="1315">Get a writable version of the structure. The structure of the message. The structure + line="1321">The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. This function ensures that @message is writable, and if so, will @@ -37746,7 +39337,7 @@ MT safe. A writable #GstMessage. + line="1317">A writable #GstMessage. @@ -37756,7 +39347,7 @@ MT safe. introspectable="0"> Modifies a pointer to a #GstMessage to point to a different #GstMessage. The + line="3509">Modifies a pointer to a #GstMessage to point to a different #GstMessage. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old message is unreffed, the new one is reffed). @@ -37766,7 +39357,7 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< %TRUE if @new_message was different from @old_message + line="3523">%TRUE if @new_message was different from @old_message @@ -37778,7 +39369,7 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< allow-none="1"> pointer to a + line="3511">pointer to a pointer to a #GstMessage to be replaced. @@ -37788,7 +39379,7 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< allow-none="1"> pointer to a #GstMessage that will + line="3513">pointer to a #GstMessage that will replace the message pointed to by @old_message. @@ -38238,19 +39829,19 @@ was updated. Get a printable name for the given message type. Do not modify or free. + line="135">Get a printable name for the given message type. Do not modify or free. a reference to the static name of the message. + line="141">a reference to the static name of the message. the message type + line="137">the message type @@ -38258,19 +39849,19 @@ was updated. Get the unique quark for the given message type. + line="155">Get the unique quark for the given message type. the quark associated with the message type + line="161">the quark associated with the message type the message type + line="157">the message type @@ -38298,17 +39889,17 @@ A specific implementation can be retrieved by name with gst_meta_get_info(). See #GstBuffer for how the metadata can be added, retrieved and removed from buffers. - + extra flags for the metadata + line="111">extra flags for the metadata pointer to the #GstMetaInfo + line="112">pointer to the #GstMetaInfo version="1.16"> Meta sequence number compare function. Can be used as #GCompareFunc + line="669">Meta sequence number compare function. Can be used as #GCompareFunc or a #GCompareDataFunc. - + a negative number if @meta1 comes before @meta2, 0 if both metas + line="677">a negative number if @meta1 comes before @meta2, 0 if both metas have an equal sequence number, or a positive integer if @meta1 comes after @meta2. @@ -38331,13 +39922,13 @@ or a #GCompareDataFunc. a #GstMeta + line="671">a #GstMeta a #GstMeta + line="672">a #GstMeta @@ -38347,8 +39938,8 @@ or a #GCompareDataFunc. version="1.16"> Gets seqnum for this meta. - + line="647">Gets seqnum for this meta. + @@ -38356,19 +39947,134 @@ or a #GCompareDataFunc. a #GstMeta + line="649">a #GstMeta + + + + + + Serialize @meta into a format that can be stored or transmitted and later +deserialized by gst_meta_deserialize(). + +This is only supported for meta that implements #GstMetaInfo.serialize_func, +%FALSE is returned otherwise. + +Upon failure, @data->data pointer could have been reallocated, but @data->len +won't be modified. This is intended to be able to append multiple metas +into the same #GByteArray. + +Since serialization size is often the same for every buffer, caller may want +to remember the size of previous data to preallocate the next. + + + %TRUE on success, %FALSE otherwise. + + + + + a #GstMeta + + #GstByteArrayInterface to append serialization data + + + + Same as gst_meta_serialize() but with a #GByteArray instead of +#GstByteArrayInterface. + + + %TRUE on success, %FALSE otherwise. + + + + + a #GstMeta + + + + #GByteArray to append serialization data + + + + + + + + When a element like `tee` decides the allocation, each downstream element may +fill different parameters and pass them to gst_query_add_allocation_meta(). +In order to keep these parameters, a merge operation is needed. This +aggregate function can combine the parameters from @params0 and @param1, and +write the result back into @aggregated_params. + + + %TRUE if the parameters were successfully aggregated, %FALSE otherwise. + + + + + the GType of the API for which the parameters are being aggregated. + + + + This structure will be updated with the + combined parameters from both @params0 and @params1. + + + + a #GstStructure containing the new parameters to be aggregated. + + + + a #GstStructure containing the new parameters to be aggregated. + + + + - + an array of tags as strings. + line="397">an array of tags as strings. @@ -38377,7 +40083,7 @@ or a #GCompareDataFunc. an API + line="395">an API @@ -38386,25 +40092,25 @@ or a #GCompareDataFunc. c:identifier="gst_meta_api_type_has_tag"> Check if @api was registered with @tag. - + line="375">Check if @api was registered with @tag. + %TRUE if @api was registered with @tag. + line="382">%TRUE if @api was registered with @tag. an API + line="377">an API the tag to check + line="378">the tag to check @@ -38413,42 +40119,122 @@ or a #GCompareDataFunc. c:identifier="gst_meta_api_type_register"> Register and return a GType for the @api and associate it with + line="115">Register and return a GType for the @api and associate it with @tags. - + a unique GType for @api. + line="123">a unique GType for @api. an API to register + line="117">an API to register tags for @api + line="118">tags for @api + + This function sets the aggregator function for a specific API type. + + + + + + + the #GType of the API for which the aggregator function is being set. + + + + the aggregator function to be associated with the given API + type. + + + + + + Recreate a #GstMeta from serialized data returned by +gst_meta_serialize() and add it to @buffer. + +Note that the meta must have been previously registered by calling one of +`gst_*_meta_get_info ()` functions. + +@consumed is set to the number of bytes that can be skipped from @data to +find the next meta serialization, if any. In case of parsing error that does +not allow to determine that size, @consumed is set to 0. + + + the metadata owned by @buffer, or %NULL. + + + + + a #GstBuffer + + + + serialization data obtained from gst_meta_serialize() + + + + size of @data + + + + total size used by this meta, could be less than @size + + + + Lookup a previously registered meta info structure by its implementation name + line="623">Lookup a previously registered meta info structure by its implementation name @impl. - + a #GstMetaInfo with @impl, or + line="630">a #GstMetaInfo with @impl, or %NULL when no such metainfo exists. @@ -38456,23 +40242,25 @@ or a #GCompareDataFunc. the name + line="625">the name - + Register a new #GstMeta implementation. + line="497">Register a new #GstMeta implementation. The same @info can be retrieved later with gst_meta_get_info() by using @impl as the key. - + a #GstMetaInfo that can be used to + line="511">a #GstMetaInfo that can be used to access metadata. @@ -38480,39 +40268,37 @@ access metadata. the type of the #GstMeta API + line="499">the type of the #GstMeta API the name of the #GstMeta implementation + line="500">the name of the #GstMeta implementation the size of the #GstMeta structure + line="501">the size of the #GstMeta structure - + a #GstMetaInitFunction + line="502">a #GstMetaInitFunction - + a #GstMetaFreeFunction + line="503">a #GstMetaFreeFunction - + a #GstMetaTransformFunction + line="504">a #GstMetaTransformFunction @@ -38523,7 +40309,7 @@ access metadata. version="1.20"> Register a new custom #GstMeta implementation, backed by an opaque + line="275">Register a new custom #GstMeta implementation, backed by an opaque structure holding a #GstStructure. The registered info can be retrieved later with gst_meta_get_info() by using @@ -38536,11 +40322,11 @@ writability of the buffer the meta is attached to. When @transform_func is %NULL, the meta and its backing #GstStructure will always be copied when the transform operation is copy, other operations are discarded, copy regions are ignored. - + a #GstMetaInfo that can be used to + line="297">a #GstMetaInfo that can be used to access metadata. @@ -38548,13 +40334,13 @@ access metadata. the name of the #GstMeta implementation + line="277">the name of the #GstMeta implementation tags for @api + line="278">tags for @api @@ -38568,7 +40354,7 @@ access metadata. destroy="4"> a #GstMetaTransformFunction + line="279">a #GstMetaTransformFunction @@ -38578,7 +40364,7 @@ access metadata. allow-none="1"> user data passed to @transform_func + line="280">user data passed to @transform_func scope="async"> #GDestroyNotify for user_data + line="281">#GDestroyNotify for user_data + + Simplified version of gst_meta_register_custom(), with no tags and no +transform function. + + + a #GstMetaInfo that can be used to access metadata. + + + + + the name of the #GstMeta implementation + + + + + + Clears the content of the meta. This will be called by the GstBufferPool +when a pooled buffer is returned. + + + + + + + a #GstBuffer + + + + a #GstMeta + + + + + + Recreate a #GstMeta from serialized data returned by +#GstMetaSerializeFunction and add it to @buffer. + + + the metadata owned by @buffer, or %NULL. + + + + + #GstMetaInfo of the meta + + + + a #GstBuffer + + + + data obtained from #GstMetaSerializeFunction + + + + size of data to avoid buffer overflow + + + + + + + Extra metadata flags. + line="38">Extra metadata flags. glib:name="GST_META_FLAG_NONE"> no flags + line="40">no flags glib:name="GST_META_FLAG_READONLY"> metadata should not be modified + line="41">metadata should not be modified glib:name="GST_META_FLAG_POOLED"> metadata is managed by a bufferpool + line="42">metadata is managed by a bufferpool glib:name="GST_META_FLAG_LOCKED"> metadata should not be removed + line="43">metadata should not be removed glib:name="GST_META_FLAG_LAST"> additional flags can be added starting from this flag. + line="44">additional flags can be added starting from this flag. Function called when @meta is freed in @buffer. - + line="161">Function called when @meta is freed in @buffer. + @@ -38657,13 +40536,13 @@ access metadata. a #GstMeta + line="163">a #GstMeta a #GstBuffer + line="164">a #GstBuffer @@ -38671,53 +40550,76 @@ access metadata. The #GstMetaInfo provides information about a specific metadata + line="341">The #GstMetaInfo provides information about a specific metadata structure. - + tag identifying the metadata structure and api + line="343">tag identifying the metadata structure and api type identifying the implementor of the api + line="344">type identifying the implementor of the api size of the metadata + line="345">size of the metadata function for initializing the metadata + line="346">function for initializing the metadata function for freeing the metadata + line="347">function for freeing the metadata function for transforming the metadata + line="348">function for transforming the metadata + + Function for serializing the metadata, or %NULL if not supported by this +meta. + + + + Function for deserializing the metadata, or %NULL if not supported by this +meta. + + + + Function for clearing the metadata, or %NULL if not supported by this +meta. This is called by the buffer pool when a buffer is returned for +pooled metas. + + - + whether @info was registered as a #GstCustomMeta with + line="363">whether @info was registered as a #GstCustomMeta with gst_meta_register_custom() @@ -38727,12 +40629,102 @@ structure. + + Registers a new meta. + +Use the structure returned by gst_meta_info_new(), it consumes it and the +structure shouldnt be used after. The one returned by the function can be +kept. + + + the registered meta + + + + + a new #GstMetaInfo created by gst_meta_info_new() + + + + + + Creates a new structure that needs to be filled before being +registered. This structure should filled and then registered with +gst_meta_info_register(). + +Example: +```c +const GstMetaInfo * +gst_my_meta_get_info (void) +{ + static const GstMetaInfo *meta_info = NULL; + + if (g_once_init_enter ((GstMetaInfo **) & meta_info)) { + GstMetaInfo *info = gst_meta_info_new ( + gst_my_meta_api_get_type (), + "GstMyMeta", + sizeof (GstMyMeta)); + const GstMetaInfo *meta = NULL; + + info->init_func = my_meta_init; + info->free_func = my_meta_free; + info->transform_func = my_meta_transform; + info->serialize_func = my_meta_serialize; + info->deserialize_func = my_meta_deserialize; + meta = gst_meta_info_register (info); + g_once_init_leave ((GstMetaInfo **) & meta_info, (GstMetaInfo *) meta); + } + + return meta_info; +} +``` + + + a new #GstMetaInfo that needs to be filled + + + + + the type of the #GstMeta API + + + + the name of the #GstMeta implementation + + + + the size of the #GstMeta structure + + + + Function called when @meta is initialized in @buffer. - + line="151">Function called when @meta is initialized in @buffer. + @@ -38740,7 +40732,7 @@ structure. a #GstMeta + line="153">a #GstMeta allow-none="1"> parameters passed to the init function + line="154">parameters passed to the init function a #GstBuffer + line="155">a #GstBuffer + + Serialize @meta into a format that can be stored or transmitted and later +deserialized by #GstMetaDeserializeFunction. + +By default version is set to 0, it should be bumped if incompatible changes +are made to the format so %GstMetaDeserializeFunction can deserialize each +version. + + + %TRUE on success, %FALSE otherwise. + + + + + a #GstMeta + + + + #GstByteArrayInterface to append serialization data + + + + version of the serialization format + + + + Extra data passed to a "gst-copy" transform #GstMetaTransformFunction. - + line="186">Extra data passed to a "gst-copy" transform #GstMetaTransformFunction. + %TRUE if only region is copied + line="188">%TRUE if only region is copied the offset to copy, 0 if @region is %FALSE, otherwise > 0 + line="189">the offset to copy, 0 if @region is %FALSE, otherwise > 0 the size to copy, -1 or the buffer size when @region is %FALSE + line="190">the size to copy, -1 or the buffer size when @region is %FALSE Function called for each @meta in @buffer as a result of performing a + line="200">Function called for each @meta in @buffer as a result of performing a transformation on @transbuf. Additional @type specific transform data is passed to the function as @data. Implementations should check the @type of the transform and parse additional type specific fields in @data that should be used to update the metadata on @transbuf. - + %TRUE if the transform could be performed + line="216">%TRUE if the transform could be performed a #GstBuffer + line="202">a #GstBuffer a #GstMeta + line="203">a #GstMeta a #GstBuffer + line="204">a #GstBuffer the transform type + line="205">the transform type allow-none="1"> transform specific data. + line="206">transform specific data. @@ -39655,6 +41689,44 @@ last ref and @obj is about to be freed. + + Declare a #GMutexLocker variable with g_autoptr() and lock the object. The +mutex will be unlocked automatically when leaving the scope. + +``` c +{ + GST_OBJECT_AUTO_LOCK (obj, locker); + + obj->stuff_with_lock(); + if (cond) { + // No need to unlock + return; + } + + // Unlock before end of scope + g_clear_pointer (&locker, g_mutex_locker_free); + obj->stuff_without_lock(); +} +``` + + + + a #GstObject to lock + + + a variable name to be declared + + + @@ -39687,13 +41759,13 @@ last ref and @obj is about to be freed. introspectable="0"> This macro returns the entire set of flags for the object. - + line="176">This macro returns the entire set of flags for the object. + a #GstObject + line="178">a #GstObject @@ -39702,18 +41774,18 @@ last ref and @obj is about to be freed. introspectable="0"> This macro checks to see if the given flag is set. - + line="183">This macro checks to see if the given flag is set. + a #GstObject + line="185">a #GstObject Flag to check for + line="186">Flag to check for @@ -39722,18 +41794,18 @@ last ref and @obj is about to be freed. introspectable="0"> This macro sets the given bits. - + line="191">This macro sets the given bits. + a #GstObject + line="193">a #GstObject Flag to set + line="194">Flag to set @@ -39742,18 +41814,18 @@ last ref and @obj is about to be freed. introspectable="0"> This macro unsets the given bits. - + line="199">This macro unsets the given bits. + a #GstObject + line="201">a #GstObject Flag to set + line="202">Flag to set @@ -39771,13 +41843,13 @@ last ref and @obj is about to be freed. introspectable="0"> Acquire a reference to the mutex of this object. - + line="96">Acquire a reference to the mutex of this object. + a #GstObject + line="98">a #GstObject @@ -39786,14 +41858,14 @@ last ref and @obj is about to be freed. introspectable="0"> This macro will obtain a lock on the object, making serialization possible. + line="103">This macro will obtain a lock on the object, making serialization possible. It blocks until the lock can be obtained. - + a #GstObject to lock + line="105">a #GstObject to lock @@ -39802,15 +41874,15 @@ It blocks until the lock can be obtained. introspectable="0"> Get the name of this object. This is not thread-safe by default + line="156">Get the name of this object. This is not thread-safe by default (i.e. you will have to make sure the object lock is taken yourself). If in doubt use gst_object_get_name() instead. - + a #GstObject + line="158">a #GstObject @@ -39819,15 +41891,15 @@ If in doubt use gst_object_get_name() instead. introspectable="0"> Get the parent of this object. This is not thread-safe by default + line="165">Get the parent of this object. This is not thread-safe by default (i.e. you will have to make sure the object lock is taken yourself). If in doubt use gst_object_get_parent() instead. - + a #GstObject + line="167">a #GstObject @@ -39836,13 +41908,13 @@ If in doubt use gst_object_get_parent() instead. introspectable="0"> Get access to the reference count field of the object. - + line="78">Get access to the reference count field of the object. + a #GstObject + line="80">a #GstObject @@ -39851,13 +41923,13 @@ If in doubt use gst_object_get_parent() instead. introspectable="0"> Get the reference count value of the object. - + line="85">Get the reference count value of the object. + a #GstObject + line="87">a #GstObject @@ -39866,14 +41938,14 @@ If in doubt use gst_object_get_parent() instead. introspectable="0"> This macro will try to obtain a lock on the object, but will return with + line="139">This macro will try to obtain a lock on the object, but will return with %FALSE if it can't get it immediately. - + a #GstObject. + line="141">a #GstObject. @@ -39882,13 +41954,13 @@ If in doubt use gst_object_get_parent() instead. introspectable="0"> This macro releases a lock on the object. - + line="147">This macro releases a lock on the object. + a #GstObject to unlock. + line="149">a #GstObject to unlock. @@ -39951,21 +42023,21 @@ What needs to be done in applications? Again it's not a lot to change. gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); * start your pipeline - + Checks to see if there is any object named @name in @list. This function + line="887">Checks to see if there is any object named @name in @list. This function does not do any locking of any kind. You might want to protect the provided list with the lock of the owner of the list. This function will lock each #GstObject in the list to compare the name, so be careful when passing a list with a locked object. - + %TRUE if a #GstObject named @name does not appear in @list, + line="899">%TRUE if a #GstObject named @name does not appear in @list, %FALSE if it does. MT safe. Grabs and releases the LOCK of each object in the list. @@ -39975,7 +42047,7 @@ MT safe. Grabs and releases the LOCK of each object in the list. a list of #GstObject to + line="889">a list of #GstObject to check through @@ -39984,7 +42056,7 @@ MT safe. Grabs and releases the LOCK of each object in the list. the name to search for + line="891">the name to search for @@ -39993,14 +42065,14 @@ MT safe. Grabs and releases the LOCK of each object in the list. c:identifier="gst_object_default_deep_notify"> A default deep_notify signal callback for an object. The user data + line="490">A default deep_notify signal callback for an object. The user data should contain a pointer to an array of strings that should be excluded from the notify. The default handler will print the new value of the property using g_print. MT safe. This function grabs and releases @object's LOCK for getting its path string. - + @@ -40008,19 +42080,19 @@ MT safe. This function grabs and releases @object's LOCK for getting its the #GObject that signalled the notify. + line="492">the #GObject that signalled the notify. a #GstObject that initiated the notify. + line="493">a #GstObject that initiated the notify. a #GParamSpec of the property. + line="494">a #GParamSpec of the property. + line="495"> a set of user-specified properties to exclude or %NULL to show all changes. @@ -40043,7 +42115,7 @@ MT safe. This function grabs and releases @object's LOCK for getting its introspectable="0"> Increase the reference count of @object, and possibly remove the floating + line="272">Increase the reference count of @object, and possibly remove the floating reference, if @object has a floating reference. In other words, if the object is floating, then this call "assumes ownership" @@ -40054,7 +42126,7 @@ reference count by one. For more background on "floating references" please see the #GObject documentation. - + @@ -40065,7 +42137,7 @@ documentation. allow-none="1"> a #GstObject to sink + line="274">a #GstObject to sink @@ -40073,16 +42145,16 @@ documentation. Atomically modifies a pointer to point to a new object. + line="325">Atomically modifies a pointer to point to a new object. The reference count of @oldobj is decreased and the reference count of @newobj is increased. Either @newobj and the value pointed to by @oldobj may be %NULL. - + %TRUE if @newobj was different from @oldobj + line="337">%TRUE if @newobj was different from @oldobj @@ -40094,7 +42166,7 @@ Either @newobj and the value pointed to by @oldobj may be %NULL. allow-none="1"> pointer to a place of + line="327">pointer to a place of a #GstObject to replace @@ -40104,13 +42176,16 @@ Either @newobj and the value pointed to by @oldobj may be %NULL. allow-none="1"> a new #GstObject + line="329">a new #GstObject - + default signal handler + @@ -40130,16 +42205,16 @@ Either @newobj and the value pointed to by @oldobj may be %NULL. c:identifier="gst_object_add_control_binding"> Attach the #GstControlBinding to the object. If there already was a + line="1241">Attach the #GstControlBinding to the object. If there already was a #GstControlBinding for this property it will be replaced. The object's reference count will be incremented, and any floating reference will be removed (see gst_object_ref_sink()) - + %FALSE if the given @binding has not been setup for this object or + line="1252">%FALSE if the given @binding has not been setup for this object or has been setup for a non suitable property, %TRUE otherwise. @@ -40147,13 +42222,13 @@ has been setup for a non suitable property, %TRUE otherwise. the controller object + line="1243">the controller object the #GstControlBinding that should be used + line="1244">the #GstControlBinding that should be used @@ -40197,13 +42272,13 @@ The default handler will simply print the error string using g_print. c:identifier="gst_object_get_control_binding"> Gets the corresponding #GstControlBinding for the property. This should be + line="1278">Gets the corresponding #GstControlBinding for the property. This should be unreferenced again after use. - + the #GstControlBinding for + line="1286">the #GstControlBinding for @property_name or %NULL if the property is not controlled. @@ -40211,13 +42286,13 @@ unreferenced again after use. the object + line="1280">the object name of the property + line="1281">name of the property @@ -40226,7 +42301,7 @@ unreferenced again after use. c:identifier="gst_object_get_control_rate"> Obtain the control-rate for this @object. Audio processing #GstElement + line="1457">Obtain the control-rate for this @object. Audio processing #GstElement objects will use this rate to sub-divide their processing loop and call gst_object_sync_values() in between. The length of the processing segment should be up to @control-rate nanoseconds. @@ -40236,18 +42311,18 @@ If the @object is not under property control, this will return The control-rate is not expected to change if the element is in %GST_STATE_PAUSED or %GST_STATE_PLAYING. - + the control rate in nanoseconds + line="1472">the control rate in nanoseconds the object that has controlled properties + line="1459">the object that has controlled properties @@ -40256,54 +42331,54 @@ The control-rate is not expected to change if the element is in c:identifier="gst_object_get_g_value_array"> Gets a number of #GValues for the given controlled property starting at the + line="1415">Gets a number of #GValues for the given controlled property starting at the requested time. The array @values need to hold enough space for @n_values of #GValue. This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample. - + %TRUE if the given array could be filled, %FALSE otherwise + line="1431">%TRUE if the given array could be filled, %FALSE otherwise the object that has controlled properties + line="1417">the object that has controlled properties the name of the property to get + line="1418">the name of the property to get the time that should be processed + line="1419">the time that should be processed the time spacing between subsequent values + line="1420">the time spacing between subsequent values the number of values + line="1421">the number of values array to put control-values in + line="1422">array to put control-values in @@ -40315,17 +42390,17 @@ curve or apply a control curve sample by sample. glib:get-property="name"> Returns a copy of the name of @object. + line="660">Returns a copy of the name of @object. Caller should g_free() the return value after usage. For a nameless object, this returns %NULL, which you can safely g_free() as well. Free-function: g_free - + the name of @object. g_free() + line="671">the name of @object. g_free() after usage. MT safe. This function grabs and releases @object's LOCK. @@ -40335,7 +42410,7 @@ MT safe. This function grabs and releases @object's LOCK. a #GstObject + line="662">a #GstObject @@ -40345,13 +42420,13 @@ MT safe. This function grabs and releases @object's LOCK. glib:get-property="parent"> Returns the parent of @object. This function increases the refcount + line="742">Returns the parent of @object. This function increases the refcount of the parent object so you should gst_object_unref() it after usage. - + parent of @object, this can be + line="749">parent of @object, this can be %NULL if @object has no parent. unref after usage. MT safe. Grabs and releases @object's LOCK. @@ -40361,7 +42436,7 @@ MT safe. Grabs and releases @object's LOCK. a #GstObject + line="744">a #GstObject @@ -40369,15 +42444,15 @@ MT safe. Grabs and releases @object's LOCK. Generates a string describing the path of @object in + line="972">Generates a string describing the path of @object in the object hierarchy. Only useful (or used) for debugging. Free-function: g_free - + a string describing the path of @object. You must + line="981">a string describing the path of @object. You must g_free() the string after usage. MT safe. Grabs and releases the #GstObject's LOCK for all objects @@ -40388,7 +42463,7 @@ MT safe. Grabs and releases the #GstObject's LOCK for all objects a #GstObject + line="974">a #GstObject @@ -40396,12 +42471,12 @@ MT safe. Grabs and releases the #GstObject's LOCK for all objects Gets the value for the given controlled property at the requested time. - + line="1339">Gets the value for the given controlled property at the requested time. + the GValue of the property at the given time, + line="1347">the GValue of the property at the given time, or %NULL if the property isn't controlled. @@ -40409,19 +42484,19 @@ or %NULL if the property isn't controlled. the object that has controlled properties + line="1341">the object that has controlled properties the name of the property to get + line="1342">the name of the property to get the time the control-change should be read from + line="1343">the time the control-change should be read from @@ -40431,7 +42506,7 @@ or %NULL if the property isn't controlled. introspectable="0"> Gets a number of values for the given controlled property starting at the + line="1370">Gets a number of values for the given controlled property starting at the requested time. The array @values need to hold enough space for @n_values of the same type as the objects property's type. @@ -40441,48 +42516,48 @@ curve or apply a control curve sample by sample. The values are unboxed and ready to be used. The similar function gst_object_get_g_value_array() returns the array as #GValues and is better suites for bindings. - + %TRUE if the given array could be filled, %FALSE otherwise + line="1390">%TRUE if the given array could be filled, %FALSE otherwise the object that has controlled properties + line="1372">the object that has controlled properties the name of the property to get + line="1373">the name of the property to get the time that should be processed + line="1374">the time that should be processed the time spacing between subsequent values + line="1375">the time spacing between subsequent values the number of values + line="1376">the number of values array to put control-values in + line="1377">array to put control-values in @@ -40493,19 +42568,19 @@ better suites for bindings. c:identifier="gst_object_has_active_control_bindings"> Check if the @object has active controlled properties. - + line="1165">Check if the @object has active controlled properties. + %TRUE if the object has active controlled properties + line="1171">%TRUE if the object has active controlled properties the object that has controlled properties + line="1167">the object that has controlled properties @@ -40515,29 +42590,29 @@ better suites for bindings. deprecated="1"> Check if @object has an ancestor @ancestor somewhere up in + line="865">Check if @object has an ancestor @ancestor somewhere up in the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. Use gst_object_has_as_ancestor() instead. MT safe. Grabs and releases @object's locks. - + %TRUE if @ancestor is an ancestor of @object. + line="873">%TRUE if @ancestor is an ancestor of @object. a #GstObject to check + line="867">a #GstObject to check a #GstObject to check as ancestor + line="868">a #GstObject to check as ancestor @@ -40545,13 +42620,13 @@ MT safe. Grabs and releases @object's locks. Check if @object has an ancestor @ancestor somewhere up in + line="830">Check if @object has an ancestor @ancestor somewhere up in the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. - + %TRUE if @ancestor is an ancestor of @object. + line="838">%TRUE if @ancestor is an ancestor of @object. MT safe. Grabs and releases @object's locks. @@ -40560,13 +42635,13 @@ MT safe. Grabs and releases @object's locks. a #GstObject to check + line="832">a #GstObject to check a #GstObject to check as ancestor + line="833">a #GstObject to check as ancestor @@ -40576,13 +42651,13 @@ MT safe. Grabs and releases @object's locks. version="1.6"> Check if @parent is the parent of @object. + line="802">Check if @parent is the parent of @object. E.g. a #GstElement can check if it owns a given #GstPad. - + %FALSE if either @object or @parent is %NULL. %TRUE if @parent is + line="810">%FALSE if either @object or @parent is %NULL. %TRUE if @parent is the parent of @object. Otherwise %FALSE. MT safe. Grabs and releases @object's locks. @@ -40592,13 +42667,13 @@ MT safe. Grabs and releases @object's locks. a #GstObject to check + line="804">a #GstObject to check a #GstObject to check as parent + line="805">a #GstObject to check as parent @@ -40606,25 +42681,25 @@ MT safe. Grabs and releases @object's locks. Increments the reference count on @object. This function + line="218">Increments the reference count on @object. This function does not take the lock on @object because it relies on atomic refcounting. This object returns the input parameter to ease writing constructs like : result = gst_object_ref (object->parent); - + A pointer to @object + line="230">A pointer to @object a #GstObject to reference + line="220">a #GstObject to reference @@ -40633,26 +42708,26 @@ constructs like : c:identifier="gst_object_remove_control_binding"> Removes the corresponding #GstControlBinding. If it was the + line="1306">Removes the corresponding #GstControlBinding. If it was the last ref of the binding, it will be disposed. - + %TRUE if the binding could be removed. + line="1314">%TRUE if the binding could be removed. the object + line="1308">the object the binding + line="1309">the binding @@ -40661,10 +42736,10 @@ last ref of the binding, it will be disposed. c:identifier="gst_object_set_control_binding_disabled"> This function is used to disable the control bindings on a property for + line="1213">This function is used to disable the control bindings on a property for some time, i.e. gst_object_sync_values() will do nothing for the property. - + @@ -40672,19 +42747,19 @@ property. the object that has controlled properties + line="1215">the object that has controlled properties property to disable + line="1216">property to disable boolean that specifies whether to disable the controller + line="1217">boolean that specifies whether to disable the controller or not. @@ -40694,9 +42769,9 @@ or not. c:identifier="gst_object_set_control_bindings_disabled"> This function is used to disable all controlled properties of the @object for + line="1189">This function is used to disable all controlled properties of the @object for some time, i.e. gst_object_sync_values() will do nothing. - + @@ -40704,13 +42779,13 @@ some time, i.e. gst_object_sync_values() will do nothing. the object that has controlled properties + line="1191">the object that has controlled properties boolean that specifies whether to disable the controller + line="1192">boolean that specifies whether to disable the controller or not. @@ -40720,14 +42795,14 @@ or not. c:identifier="gst_object_set_control_rate"> Change the control-rate for this @object. Audio processing #GstElement + line="1482">Change the control-rate for this @object. Audio processing #GstElement objects will use this rate to sub-divide their processing loop and call gst_object_sync_values() in between. The length of the processing segment should be up to @control-rate nanoseconds. The control-rate should not change if the element is in %GST_STATE_PAUSED or %GST_STATE_PLAYING. - + @@ -40735,13 +42810,13 @@ The control-rate should not change if the element is in %GST_STATE_PAUSED or the object that has controlled properties + line="1484">the object that has controlled properties the new control-rate in nanoseconds. + line="1485">the new control-rate in nanoseconds. @@ -40751,15 +42826,15 @@ The control-rate should not change if the element is in %GST_STATE_PAUSED or glib:set-property="name"> Sets the name of @object, or gives @object a guaranteed unique + line="632">Sets the name of @object, or gives @object a guaranteed unique name (if @name is %NULL). This function makes a copy of the provided name, so the caller retains ownership of the name it sent. - + %TRUE if the name could be set. Since Objects that have + line="642">%TRUE if the name could be set. Since Objects that have a parent cannot be renamed, this function returns %FALSE in those cases. @@ -40770,7 +42845,7 @@ MT safe. This function grabs and releases @object's LOCK. a #GstObject + line="634">a #GstObject allow-none="1"> new name of object + line="635">new name of object @@ -40789,13 +42864,13 @@ MT safe. This function grabs and releases @object's LOCK. glib:set-property="parent"> Sets the parent of @object to @parent. The object's reference count will + line="690">Sets the parent of @object to @parent. The object's reference count will be incremented, and any floating reference will be removed (see gst_object_ref_sink()). - + %TRUE if @parent could be set or %FALSE when @object + line="698">%TRUE if @parent could be set or %FALSE when @object already had a parent or @object and @parent are the same. MT safe. Grabs and releases @object's LOCK. @@ -40805,13 +42880,13 @@ MT safe. Grabs and releases @object's LOCK. a #GstObject + line="692">a #GstObject new parent of object + line="693">new parent of object @@ -40820,13 +42895,13 @@ MT safe. Grabs and releases @object's LOCK. c:identifier="gst_object_suggest_next_sync"> Returns a suggestion for timestamps where buffers should be split + line="1091">Returns a suggestion for timestamps where buffers should be split to get best controller results. - + Returns the suggested timestamp or %GST_CLOCK_TIME_NONE + line="1098">Returns the suggested timestamp or %GST_CLOCK_TIME_NONE if no control-rate was set. @@ -40834,7 +42909,7 @@ if no control-rate was set. the object that has controlled properties + line="1093">the object that has controlled properties @@ -40842,16 +42917,16 @@ if no control-rate was set. Sets the properties of the object, according to the #GstControlSources that + line="1123">Sets the properties of the object, according to the #GstControlSources that (maybe) handle them and for the given timestamp. If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly. - + %TRUE if the controller values could be applied to the object + line="1134">%TRUE if the controller values could be applied to the object properties, %FALSE otherwise @@ -40859,13 +42934,13 @@ properties, %FALSE otherwise the object that has controlled properties + line="1125">the object that has controlled properties the time that should be processed + line="1126">the time that should be processed @@ -40873,11 +42948,11 @@ properties, %FALSE otherwise Clear the parent of @object, removing the associated reference. + line="770">Clear the parent of @object, removing the associated reference. This function decreases the refcount of @object. MT safe. Grabs and releases @object's lock. - + @@ -40885,7 +42960,7 @@ MT safe. Grabs and releases @object's lock. a #GstObject to unparent + line="772">a #GstObject to unparent @@ -40893,13 +42968,13 @@ MT safe. Grabs and releases @object's lock. Decrements the reference count on @object. If reference count hits + line="247">Decrements the reference count on @object. If reference count hits zero, destroy @object. This function does not take the lock on @object as it relies on atomic refcounting. The unref method should never be called with the LOCK held since this might deadlock the dispose function. - + @@ -40907,7 +42982,7 @@ this might deadlock the dispose function. a #GstObject to unreference + line="249">a #GstObject to unreference @@ -40928,7 +43003,7 @@ this might deadlock the dispose function. getter="get_parent"> The parent of the object. Please note, that when changing the 'parent' + line="161">The parent of the object. Please note, that when changing the 'parent' property, we don't emit #GObject::notify and #GstObject::deep-notify signals due to locking issues. In some cases one can use #GstBin::element-added or #GstBin::element-removed signals on the parent to @@ -40941,25 +43016,25 @@ achieve a similar effect. object LOCK + line="213">object LOCK The name of the object + line="214">The name of the object this object's parent, weak ref + line="215">this object's parent, weak ref flags for this object + line="216">flags for this object @@ -40983,7 +43058,7 @@ achieve a similar effect. no-hooks="1"> The deep notify signal is used to be notified of property changes. It is + line="177">The deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin. @@ -40993,13 +43068,13 @@ the elements contained in that bin. the object that originated the signal + line="180">the object that originated the signal the property that changed + line="181">the property that changed @@ -41010,24 +43085,27 @@ the elements contained in that bin. glib:is-gtype-struct-for="Object"> GStreamer base object class. - + line="237">GStreamer base object class. + parent + line="239">parent separator used by gst_object_get_path_string() + line="240">separator used by gst_object_get_path_string() + default signal handler - + @@ -41056,7 +43134,7 @@ the elements contained in that bin. c:type="GstObjectFlags"> The standard flags that an gstobject may have. + line="55">The standard flags that an gstobject may have. glib:name="GST_OBJECT_FLAG_MAY_BE_LEAKED"> the object is expected to stay alive even + line="57">the object is expected to stay alive even after gst_deinit() has been called and so should be ignored by leak detection tools. (Since: 1.10) + + + Flag that's set when the object has been constructed. This can be used by +API such as base class setters to differentiate between the case where +they're called from a subclass's instance init function (and where the +object isn't fully constructed yet, and so one shouldn't do anything but +set values in the instance structure), and the case where the object is +constructed. glib:name="GST_OBJECT_FLAG_LAST"> subclasses can add additional flags starting from this flag + line="66">subclasses can add additional flags starting from this flag @@ -41118,7 +43211,7 @@ detection tools. (Since: 1.10) - + @@ -41127,7 +43220,7 @@ detection tools. (Since: 1.10) - + @@ -41136,7 +43229,7 @@ detection tools. (Since: 1.10) - + @@ -41145,7 +43238,7 @@ detection tools. (Since: 1.10) - + @@ -41556,13 +43649,13 @@ linked @pads instead of discarding them. introspectable="0"> Gets the last flow return on this pad - + line="1295">Gets the last flow return on this pad + a #GstPad + line="1297">a #GstPad @@ -41947,6 +44040,44 @@ queries explicitly if your element supports multiple scheduling modes. + + Declare a #GRecMutexLocker variable with g_autoptr() and lock the pad. The +recursive mutex will be unlocked automatically when leaving the scope. + +``` c +{ + GST_PAD_STREAM_AUTO_LOCK (pad, locker); + + gst_pad_push_event(pad, event1); + if (cond) { + // No need to unlock + return; + } + + // Unlock before end of scope + g_clear_pointer (&locker, g_rec_mutex_locker_free); + gst_pad_push_event(pad, event2); +} +``` + + + + a #GstPad + + + a variable name to be declared + + + @@ -41968,14 +44099,14 @@ when buffers or serialized downstream events are pushed on a pad. introspectable="0"> Try to take the pad's stream lock, and return %TRUE if the lock could be + line="1280">Try to take the pad's stream lock, and return %TRUE if the lock could be taken, and otherwise %FALSE. - + a #GstPad + line="1282">a #GstPad @@ -41984,13 +44115,13 @@ taken, and otherwise %FALSE. introspectable="0"> Release the pad's stream lock. - + line="1288">Release the pad's stream lock. + a #GstPad + line="1290">a #GstPad @@ -42566,7 +44697,7 @@ calls the plugin initialization function. - + @@ -42626,7 +44757,7 @@ received through EME API. introspectable="0"> printf format type used to debug GStreamer types. You can use this in + line="279">printf format type used to debug GStreamer types. You can use this in combination with GStreamer's debug logging system as well as the functions gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() to pretty-print the following types: #GstCaps, #GstStructure, @@ -42636,7 +44767,7 @@ to pretty-print the following types: #GstCaps, #GstStructure, else will simply be printed as pointer address. This can only be used on types whose size is >= sizeof(gpointer). - + Creates a new pad with the given name in the given direction. + line="841">Creates a new pad with the given name in the given direction. If name is %NULL, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name. - + a new #GstPad. + line="851">a new #GstPad. MT safe. @@ -42731,13 +44862,13 @@ MT safe. allow-none="1"> the name of the new pad. + line="843">the name of the new pad. the #GstPadDirection of the pad. + line="844">the #GstPadDirection of the pad. @@ -42746,28 +44877,28 @@ MT safe. c:identifier="gst_pad_new_from_static_template"> Creates a new pad with the given name from the given static template. + line="887">Creates a new pad with the given name from the given static template. If name is %NULL, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name. - + a new #GstPad. + line="897">a new #GstPad. the #GstStaticPadTemplate to use + line="889">the #GstStaticPadTemplate to use the name of the pad + line="890">the name of the pad @@ -42776,22 +44907,22 @@ This function makes a copy of the name so you can safely free the name. c:identifier="gst_pad_new_from_template"> Creates a new pad with the given name from the given template. + line="862">Creates a new pad with the given name from the given template. If name is %NULL, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name. - + a new #GstPad. + line="872">a new #GstPad. the pad template to use + line="864">the pad template to use allow-none="1"> the name of the pad + line="865">the name of the pad @@ -42810,19 +44941,19 @@ This function makes a copy of the name so you can safely free the name. version="1.4"> Gets a string representing the given pad-link return. + line="280">Gets a string representing the given pad-link return. a static string with the name of the pad-link return. + line="286">a static string with the name of the pad-link return. a #GstPadLinkReturn to get the name of. + line="282">a #GstPadLinkReturn to get the name of. @@ -42858,15 +44989,15 @@ This function makes a copy of the name so you can safely free the name. Activates or deactivates the given pad in @mode via dispatching to the + line="1303">Activates or deactivates the given pad in @mode via dispatching to the pad's activatemodefunc. For use from within pad activation functions only. If you don't know what this is, you probably don't want to call it. - + %TRUE if the operation was successful. + line="1314">%TRUE if the operation was successful. MT safe. @@ -42875,19 +45006,19 @@ MT safe. the #GstPad to activate or deactivate. + line="1305">the #GstPad to activate or deactivate. the requested activation mode + line="1306">the requested activation mode whether or not the pad should be active. + line="1307">whether or not the pad should be active. @@ -42895,7 +45026,7 @@ MT safe. Be notified of different states of pads. The provided callback is called for + line="1416">Be notified of different states of pads. The provided callback is called for every state that matches @mask. Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are @@ -42904,11 +45035,11 @@ exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called immediately if the pad is already idle while calling gst_pad_add_probe(). In each of the groups, probes are called in the order in which they were added. - + an id or 0 if no probe is pending. The id can be used to remove the + line="1435">an id or 0 if no probe is pending. The id can be used to remove the probe with gst_pad_remove_probe(). When using GST_PAD_PROBE_TYPE_IDLE it can happen that the probe can be run immediately and if the probe returns GST_PAD_PROBE_REMOVE this functions returns 0. @@ -42920,13 +45051,13 @@ MT safe. the #GstPad to add the probe to + line="1418">the #GstPad to add the probe to the probe mask + line="1419">the probe mask destroy="3"> #GstPadProbeCallback that will be called with notifications of - the pad state + line="1420">#GstPadProbeCallback that will be called with + notifications of the pad state allow-none="1"> user data passed to the callback + line="1422">user data passed to the callback scope="async"> #GDestroyNotify for user_data + line="1423">#GDestroyNotify for user_data @@ -42962,26 +45093,26 @@ MT safe. Checks if the source pad and the sink pad are compatible so they can be + line="2486">Checks if the source pad and the sink pad are compatible so they can be linked. - + %TRUE if the pads can be linked. + line="2494">%TRUE if the pads can be linked. the source #GstPad. + line="2488">the source #GstPad. the sink #GstPad. + line="2489">the sink #GstPad. @@ -42989,7 +45120,7 @@ linked. Chain a buffer to @pad. + line="4635">Chain a buffer to @pad. The function returns #GST_FLOW_FLUSHING if the pad was flushing. @@ -43004,11 +45135,11 @@ chain function. In all cases, success or failure, the caller loses its reference to @buffer after calling this function. - + a #GstFlowReturn from the pad. + line="4657">a #GstFlowReturn from the pad. MT safe. @@ -43017,13 +45148,13 @@ MT safe. a sink #GstPad, returns GST_FLOW_ERROR if not. + line="4637">a sink #GstPad, returns GST_FLOW_ERROR if not. the #GstBuffer to send, return GST_FLOW_ERROR + line="4638">the #GstBuffer to send, return GST_FLOW_ERROR if not. @@ -43032,7 +45163,7 @@ MT safe. Chain a bufferlist to @pad. + line="4716">Chain a bufferlist to @pad. The function returns #GST_FLOW_FLUSHING if the pad was flushing. @@ -43048,24 +45179,24 @@ In all cases, success or failure, the caller loses its reference to @list after calling this function. MT safe. - + a #GstFlowReturn from the pad. + line="4739">a #GstFlowReturn from the pad. a sink #GstPad, returns GST_FLOW_ERROR if not. + line="4718">a sink #GstPad, returns GST_FLOW_ERROR if not. the #GstBufferList to send, return GST_FLOW_ERROR + line="4719">the #GstBufferList to send, return GST_FLOW_ERROR if not. @@ -43075,20 +45206,20 @@ MT safe. c:identifier="gst_pad_check_reconfigure"> Check and clear the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE + line="1676">Check and clear the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE if the flag was set. - + %TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on @pad. + line="1683">%TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on @pad. the #GstPad to check + line="1678">the #GstPad to check @@ -43096,7 +45227,7 @@ if the flag was set. Creates a stream-id for the source #GstPad @pad by combining the + line="4400">Creates a stream-id for the source #GstPad @pad by combining the upstream information with the optional @stream_id of the stream of @pad. @pad must have a parent #GstElement and which must have zero or one sinkpad. @stream_id can only be %NULL if the parent element @@ -43113,24 +45244,24 @@ stream-id manually instead. Since stream IDs are sorted alphabetically, any numbers in the stream ID should be printed with a fixed number of characters, preceded by 0's, such as by using the format \%03u instead of \%u. - + A stream-id for @pad. g_free() after usage. + line="4424">A stream-id for @pad. g_free() after usage. A source #GstPad + line="4402">A source #GstPad Parent #GstElement of @pad + line="4403">Parent #GstElement of @pad allow-none="1"> The stream-id + line="4404">The stream-id @@ -43149,7 +45280,7 @@ preceded by 0's, such as by using the format \%03u instead of \%u. introspectable="0"> Creates a stream-id for the source #GstPad @pad by combining the + line="4362">Creates a stream-id for the source #GstPad @pad by combining the upstream information with the optional @stream_id of the stream of @pad. @pad must have a parent #GstElement and which must have zero or one sinkpad. @stream_id can only be %NULL if the parent element @@ -43162,24 +45293,24 @@ doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead. - + A stream-id for @pad. g_free() after usage. + line="4383">A stream-id for @pad. g_free() after usage. A source #GstPad + line="4364">A source #GstPad Parent #GstElement of @pad + line="4365">Parent #GstElement of @pad allow-none="1"> The stream-id + line="4366">The stream-id parameters for the @stream_id format string + line="4367">parameters for the @stream_id format string @@ -43204,7 +45335,7 @@ stream-id manually instead. introspectable="0"> Creates a stream-id for the source #GstPad @pad by combining the + line="4323">Creates a stream-id for the source #GstPad @pad by combining the upstream information with the optional @stream_id of the stream of @pad. @pad must have a parent #GstElement and which must have zero or one sinkpad. @stream_id can only be %NULL if the parent element @@ -43217,24 +45348,24 @@ doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead. - + A stream-id for @pad. g_free() after usage. + line="4344">A stream-id for @pad. g_free() after usage. A source #GstPad + line="4325">A source #GstPad Parent #GstElement of @pad + line="4326">Parent #GstElement of @pad allow-none="1"> The stream-id + line="4327">The stream-id parameters for the @stream_id format string + line="4328">parameters for the @stream_id format string @@ -43257,25 +45388,25 @@ stream-id manually instead. Invokes the default event handler for the given pad. + line="3173">Invokes the default event handler for the given pad. The EOS event will pause the task associated with @pad before it is forwarded to all internally linked pads, The event is sent to all pads internally linked to @pad. This function takes ownership of @event. - + %TRUE if the event was sent successfully. + line="3187">%TRUE if the event was sent successfully. a #GstPad to call the default event handler on. + line="3175">a #GstPad to call the default event handler on. allow-none="1"> the parent of @pad or %NULL + line="3176">the parent of @pad or %NULL the #GstEvent to handle. + line="3177">the #GstEvent to handle. @@ -43298,23 +45429,23 @@ takes ownership of @event. Calls @forward for all internally linked pads of @pad. This function deals with + line="3074">Calls @forward for all internally linked pads of @pad. This function deals with dynamically changing internal pads and will make sure that the @forward function is only called once for each pad. When @forward returns %TRUE, no further pads will be processed. - + %TRUE if one of the dispatcher functions returned %TRUE. + line="3086">%TRUE if one of the dispatcher functions returned %TRUE. a #GstPad + line="3076">a #GstPad closure="1"> a #GstPadForwardFunction + line="3077">a #GstPadForwardFunction allow-none="1"> user data passed to @forward + line="3078">user data passed to @forward @@ -43340,17 +45471,17 @@ When @forward returns %TRUE, no further pads will be processed. Gets the capabilities of the allowed media types that can flow through + line="2831">Gets the capabilities of the allowed media types that can flow through @pad and its peer. The allowed capabilities is calculated as the intersection of the results of calling gst_pad_query_caps() on @pad and its peer. The caller owns a reference on the resulting caps. - + the allowed #GstCaps of the + line="2842">the allowed #GstCaps of the pad link. Unref the caps when you no longer need it. This function returns %NULL when @pad has no peer. @@ -43361,7 +45492,7 @@ MT safe. a #GstPad. + line="2833">a #GstPad. @@ -43369,13 +45500,13 @@ MT safe. Gets the capabilities currently configured on @pad with the last + line="2757">Gets the capabilities currently configured on @pad with the last #GST_EVENT_CAPS event. - + the current caps of the pad with + line="2764">the current caps of the pad with incremented ref-count or %NULL when pad has no caps. Unref after usage. @@ -43383,7 +45514,7 @@ incremented ref-count or %NULL when pad has no caps. Unref after usage. a #GstPad to get the current capabilities of. + line="2759">a #GstPad to get the current capabilities of. @@ -43393,14 +45524,14 @@ incremented ref-count or %NULL when pad has no caps. Unref after usage. glib:get-property="direction"> Gets the direction of the pad. The direction of the pad is + line="926">Gets the direction of the pad. The direction of the pad is decided at construction time so this function does not take the LOCK. - + the #GstPadDirection of the pad. + line="934">the #GstPadDirection of the pad. MT safe. @@ -43409,7 +45540,7 @@ MT safe. a #GstPad to get the direction of. + line="928">a #GstPad to get the direction of. @@ -43418,20 +45549,20 @@ MT safe. c:identifier="gst_pad_get_element_private"> Gets the private data of a pad. + line="6260">Gets the private data of a pad. No locking is performed in this function. - + a #gpointer to the private data. + line="6267">a #gpointer to the private data. the #GstPad to get the private data of. + line="6262">the #GstPad to get the private data of. @@ -43441,8 +45572,8 @@ No locking is performed in this function. version="1.4"> Gets the #GstFlowReturn return from the last data passed by this pad. - + line="6695">Gets the #GstFlowReturn return from the last data passed by this pad. + @@ -43450,7 +45581,7 @@ No locking is performed in this function. the #GstPad + line="6697">the #GstPad @@ -43460,20 +45591,20 @@ No locking is performed in this function. glib:get-property="offset"> Get the offset applied to the running time of @pad. @pad has to be a source + line="3991">Get the offset applied to the running time of @pad. @pad has to be a source pad. - + the offset. + line="3998">the offset. a #GstPad + line="3993">a #GstPad @@ -43481,12 +45612,12 @@ pad. Gets the template for @pad. - + line="2709">Gets the template for @pad. + the #GstPadTemplate from which + line="2715">the #GstPadTemplate from which this pad was instantiated, or %NULL if this pad has no template. Unref after usage. @@ -43495,7 +45626,7 @@ pad. a #GstPad. + line="2711">a #GstPad. @@ -43504,12 +45635,12 @@ pad. c:identifier="gst_pad_get_pad_template_caps"> Gets the capabilities for @pad's template. - + line="2784">Gets the capabilities for @pad's template. + the #GstCaps of this pad template. + line="2790">the #GstCaps of this pad template. Unref after usage. @@ -43517,7 +45648,7 @@ Unref after usage. a #GstPad to get the template capabilities from. + line="2786">a #GstPad to get the template capabilities from. @@ -43528,7 +45659,7 @@ Unref after usage. filename="gst/gstutils.c" line="2636">Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or its parent is not an element, return %NULL. - + Gets the peer of @pad. This function refs the peer pad so + line="2804">Gets the peer of @pad. This function refs the peer pad so you need to unref it after use. - + the peer #GstPad. Unref after usage. + line="2811">the peer #GstPad. Unref after usage. MT safe. @@ -43566,7 +45697,7 @@ MT safe. a #GstPad to get the peer of. + line="2806">a #GstPad to get the peer of. @@ -43574,7 +45705,7 @@ MT safe. When @pad is flushing this function returns #GST_FLOW_FLUSHING + line="5137">When @pad is flushing this function returns #GST_FLOW_FLUSHING immediately and @buffer is %NULL. Calls the getrange function of @pad, see #GstPadGetRangeFunction for a @@ -43600,11 +45731,11 @@ When this function returns any other result value than #GST_FLOW_OK, @buffer will be unchanged. This is a lowlevel function. Usually gst_pad_pull_range() is used. - + a #GstFlowReturn from the pad. + line="5172">a #GstFlowReturn from the pad. MT safe. @@ -43613,19 +45744,19 @@ MT safe. a src #GstPad, returns #GST_FLOW_ERROR if not. + line="5139">a src #GstPad, returns #GST_FLOW_ERROR if not. The start offset of the buffer + line="5140">The start offset of the buffer The length of the buffer + line="5141">The length of the buffer transfer-ownership="full"> a pointer to hold the #GstBuffer, + line="5142">a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL. @@ -43645,13 +45776,13 @@ MT safe. version="1.18"> If there is a single internal link of the given pad, this function will + line="2898">If there is a single internal link of the given pad, this function will return it. Otherwise, it will return NULL. - + a #GstPad, or %NULL if @pad has none + line="2905">a #GstPad, or %NULL if @pad has none or more than one internal links. Unref returned pad with gst_object_unref(). @@ -43660,7 +45791,7 @@ gst_object_unref(). the #GstPad to get the internal link of. + line="2900">the #GstPad to get the internal link of. @@ -43668,13 +45799,13 @@ gst_object_unref(). Returns a new reference of the sticky event of type @event_type + line="6275">Returns a new reference of the sticky event of type @event_type from the event. - + a #GstEvent of type + line="6284">a #GstEvent of type @event_type or %NULL when no event of @event_type was on @pad. Unref after usage. @@ -43683,19 +45814,19 @@ from the event. the #GstPad to get the event from. + line="6277">the #GstPad to get the event from. the #GstEventType that should be retrieved. + line="6278">the #GstEventType that should be retrieved. the index of the event + line="6279">the index of the event @@ -43705,16 +45836,16 @@ from the event. version="1.10"> Returns the current #GstStream for the @pad, or %NULL if none has been + line="4475">Returns the current #GstStream for the @pad, or %NULL if none has been set yet, i.e. the pad has not received a stream-start event yet. This is a convenience wrapper around gst_pad_get_sticky_event() and gst_event_parse_stream(). - + the current #GstStream for @pad, or %NULL. + line="4485">the current #GstStream for @pad, or %NULL. unref the returned stream when no longer needed. @@ -43722,7 +45853,7 @@ gst_event_parse_stream(). A source #GstPad + line="4477">A source #GstPad @@ -43732,7 +45863,7 @@ gst_event_parse_stream(). version="1.2"> Returns the current stream-id for the @pad, or %NULL if none has been + line="4433">Returns the current stream-id for the @pad, or %NULL if none has been set yet, i.e. the pad has not received a stream-start event yet. This is a convenience wrapper around gst_pad_get_sticky_event() and @@ -43740,11 +45871,11 @@ gst_event_parse_stream_start(). The returned stream-id string should be treated as an opaque string, its contents should not be interpreted. - + a newly-allocated copy of the stream-id for + line="4446">a newly-allocated copy of the stream-id for @pad, or %NULL. g_free() the returned string when no longer needed. @@ -43753,7 +45884,7 @@ contents should not be interpreted. A source #GstPad + line="4435">A source #GstPad @@ -43763,20 +45894,20 @@ contents should not be interpreted. version="1.12"> Get @pad task state. If no task is currently + line="6522">Get @pad task state. If no task is currently set, #GST_TASK_STOPPED is returned. - + The current state of @pad's task. + line="6529">The current state of @pad's task. the #GstPad to get task state from + line="6524">the #GstPad to get task state from @@ -43784,19 +45915,19 @@ set, #GST_TASK_STOPPED is returned. Check if @pad has caps set on it with a #GST_EVENT_CAPS event. - + line="2731">Check if @pad has caps set on it with a #GST_EVENT_CAPS event. + %TRUE when @pad has caps associated with it. + line="2737">%TRUE when @pad has caps associated with it. a #GstPad to check + line="2733">a #GstPad to check @@ -43804,12 +45935,12 @@ set, #GST_TASK_STOPPED is returned. Query if a pad is active - + line="1359">Query if a pad is active + %TRUE if the pad is active. + line="1365">%TRUE if the pad is active. MT safe. @@ -43818,7 +45949,7 @@ MT safe. the #GstPad to query + line="1361">the #GstPad to query @@ -43826,14 +45957,14 @@ MT safe. Checks if the pad is blocked or not. This function returns the + line="1600">Checks if the pad is blocked or not. This function returns the last requested state of the pad. It is not certain that the pad is actually blocking at this point (see gst_pad_is_blocking()). - + %TRUE if the pad is blocked. + line="1608">%TRUE if the pad is blocked. MT safe. @@ -43842,7 +45973,7 @@ MT safe. the #GstPad to query + line="1602">the #GstPad to query @@ -43850,13 +45981,13 @@ MT safe. Checks if the pad is blocking or not. This is a guaranteed state + line="1626">Checks if the pad is blocking or not. This is a guaranteed state of whether the pad is actually blocking on a #GstBuffer or a #GstEvent. - + %TRUE if the pad is blocking. + line="1633">%TRUE if the pad is blocking. MT safe. @@ -43865,7 +45996,7 @@ MT safe. the #GstPad to query + line="1628">the #GstPad to query @@ -43873,12 +46004,12 @@ MT safe. Checks if a @pad is linked to another pad or not. - + line="2235">Checks if a @pad is linked to another pad or not. + %TRUE if the pad is linked, %FALSE otherwise. + line="2241">%TRUE if the pad is linked, %FALSE otherwise. MT safe. @@ -43887,7 +46018,7 @@ MT safe. pad to check + line="2237">pad to check @@ -43896,18 +46027,18 @@ MT safe. c:identifier="gst_pad_iterate_internal_links"> Gets an iterator for the pads to which the given pad is linked to inside + line="3030">Gets an iterator for the pads to which the given pad is linked to inside of the parent element. Each #GstPad element yielded by the iterator will have its refcount increased, so unref after use. Free-function: gst_iterator_free - + a new #GstIterator of #GstPad + line="3042">a new #GstIterator of #GstPad or %NULL when the pad does not have an iterator function configured. Use gst_iterator_free() after usage. @@ -43916,7 +46047,7 @@ Free-function: gst_iterator_free the GstPad to get the internal links of. + line="3032">the GstPad to get the internal links of. @@ -43925,17 +46056,17 @@ Free-function: gst_iterator_free c:identifier="gst_pad_iterate_internal_links_default"> Iterate the list of pads to which the given pad is linked to inside of + line="2964">Iterate the list of pads to which the given pad is linked to inside of the parent element. This is the default handler, and thus returns an iterator of all of the pads inside the parent element with opposite direction. The caller must free this iterator after use with gst_iterator_free(). - + a #GstIterator of #GstPad, or %NULL if @pad + line="2976">a #GstIterator of #GstPad, or %NULL if @pad has no parent. Unref each returned pad with gst_object_unref(). @@ -43943,7 +46074,7 @@ has no parent. Unref each returned pad with gst_object_unref(). the #GstPad to get the internal links of. + line="2966">the #GstPad to get the internal links of. allow-none="1"> the parent of @pad or %NULL + line="2967">the parent of @pad or %NULL @@ -43960,12 +46091,12 @@ has no parent. Unref each returned pad with gst_object_unref(). Links the source pad and the sink pad. - + line="2675">Links the source pad and the sink pad. + A result code indicating if the connection worked or + line="2682">A result code indicating if the connection worked or what went wrong. MT Safe. @@ -43975,13 +46106,13 @@ MT Safe. the source #GstPad to link. + line="2677">the source #GstPad to link. the sink #GstPad to link. + line="2678">the sink #GstPad to link. @@ -43989,7 +46120,7 @@ MT Safe. Links the source pad and the sink pad. + line="2522">Links the source pad and the sink pad. This variant of #gst_pad_link provides a more granular control on the checks being done when linking. While providing some considerable speedups @@ -43998,11 +46129,11 @@ can cause severe issues. Refer to the documentation of #GstPadLinkCheck for more information. MT Safe. - + A result code indicating if the connection worked or + line="2538">A result code indicating if the connection worked or what went wrong. @@ -44010,19 +46141,19 @@ MT Safe. the source #GstPad to link. + line="2524">the source #GstPad to link. the sink #GstPad to link. + line="2525">the sink #GstPad to link. the checks to validate when linking + line="2526">the checks to validate when linking @@ -44039,7 +46170,7 @@ This is a convenience function to save having to create and add intermediate If @src or @sink pads don't have parent elements or do not share a common ancestor, the link will fail. - + - + Mark a pad for needing reconfiguration. The next call to + line="1703">Mark a pad for needing reconfiguration. The next call to gst_pad_check_reconfigure() will return %TRUE after this call. - + @@ -44118,7 +46249,7 @@ gst_pad_check_reconfigure() will return %TRUE after this call. the #GstPad to mark + line="1705">the #GstPad to mark @@ -44127,20 +46258,20 @@ gst_pad_check_reconfigure() will return %TRUE after this call. c:identifier="gst_pad_needs_reconfigure"> Check the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE + line="1652">Check the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE if the flag was set. - + %TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on @pad. + line="1659">%TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on @pad. the #GstPad to check + line="1654">the #GstPad to check @@ -44148,14 +46279,14 @@ if the flag was set. Pause the task of @pad. This function will also wait until the + line="6476">Pause the task of @pad. This function will also wait until the function executed by the task is finished if this function is not called from the task function. - + a %TRUE if the task could be paused or %FALSE when the pad + line="6484">a %TRUE if the task could be paused or %FALSE when the pad has no task. @@ -44163,7 +46294,7 @@ has no task. the #GstPad to pause the task of + line="6478">the #GstPad to pause the task of @@ -44171,15 +46302,15 @@ has no task. Performs gst_pad_query() on the peer of @pad. + line="4330">Performs gst_pad_query() on the peer of @pad. The caller is responsible for both the allocation and deallocation of the query structure. - + %TRUE if the query could be performed. This function returns %FALSE + line="4340">%TRUE if the query could be performed. This function returns %FALSE if @pad has no peer. @@ -44187,13 +46318,13 @@ if @pad has no peer. a #GstPad to invoke the peer query on. + line="4332">a #GstPad to invoke the peer query on. the #GstQuery to perform. + line="4333">the #GstQuery to perform. @@ -44204,7 +46335,7 @@ if @pad has no peer. filename="gst/gstutils.c" line="3209">Check if the peer of @pad accepts @caps. If @pad has no peer, this function returns %TRUE. - + - + filename="gst/gstutils.c" line="3045">Queries the peer pad of a given sink pad to convert @src_val in @src_format to @dest_format. - + Queries the peer pad of a given sink pad for the total stream duration. - + Queries the peer of a given sink pad for the stream position. - + - + - + Pulls a @buffer from the peer pad or fills up a provided buffer. + line="5189">Pulls a @buffer from the peer pad or fills up a provided buffer. This function will first trigger the pad block signal if it was installed. @@ -44485,11 +46616,11 @@ accordingly. Note that less than @size bytes can be returned in @buffer when, for example, an EOS condition is near or when @buffer is not large enough to hold @size bytes. The caller should check the result buffer size to get the result size. - + a #GstFlowReturn from the peer pad. + line="5223">a #GstFlowReturn from the peer pad. MT safe. @@ -44498,19 +46629,19 @@ MT safe. a sink #GstPad, returns GST_FLOW_ERROR if not. + line="5191">a sink #GstPad, returns GST_FLOW_ERROR if not. The start offset of the buffer + line="5192">The start offset of the buffer The length of the buffer + line="5193">The length of the buffer transfer-ownership="full"> a pointer to hold the #GstBuffer, returns + line="5194">a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL. @@ -44528,7 +46659,7 @@ MT safe. Pushes a buffer to the peer of @pad. + line="4898">Pushes a buffer to the peer of @pad. This function will call installed block probes before triggering any installed data probes. @@ -44539,11 +46670,11 @@ be returned. In all cases, success or failure, the caller loses its reference to @buffer after calling this function. - + a #GstFlowReturn from the peer pad. + line="4916">a #GstFlowReturn from the peer pad. MT safe. @@ -44552,13 +46683,13 @@ MT safe. a source #GstPad, returns #GST_FLOW_ERROR if not. + line="4900">a source #GstPad, returns #GST_FLOW_ERROR if not. the #GstBuffer to push returns GST_FLOW_ERROR + line="4901">the #GstBuffer to push returns GST_FLOW_ERROR if not. @@ -44567,17 +46698,17 @@ MT safe. Sends the event to the peer of the given pad. This function is + line="5737">Sends the event to the peer of the given pad. This function is mainly used by elements to send events to their peer elements. This function takes ownership of the provided event so you should gst_event_ref() it if you want to reuse the event after this call. - + %TRUE if the event was handled. + line="5749">%TRUE if the event was handled. MT safe. @@ -44586,13 +46717,13 @@ MT safe. a #GstPad to push the event to. + line="5739">a #GstPad to push the event to. the #GstEvent to send to the pad. + line="5740">the #GstEvent to send to the pad. @@ -44600,7 +46731,7 @@ MT safe. Pushes a buffer list to the peer of @pad. + line="4936">Pushes a buffer list to the peer of @pad. This function will call installed block probes before triggering any installed data probes. @@ -44613,11 +46744,11 @@ chained via gst_pad_chain(). In all cases, success or failure, the caller loses its reference to @list after calling this function. - + a #GstFlowReturn from the peer pad. + line="4956">a #GstFlowReturn from the peer pad. MT safe. @@ -44626,13 +46757,13 @@ MT safe. a source #GstPad, returns #GST_FLOW_ERROR if not. + line="4938">a source #GstPad, returns #GST_FLOW_ERROR if not. the #GstBufferList to push returns GST_FLOW_ERROR + line="4939">the #GstBufferList to push returns GST_FLOW_ERROR if not. @@ -44641,7 +46772,7 @@ MT safe. Dispatches a query to a pad. The query should have been allocated by the + line="4192">Dispatches a query to a pad. The query should have been allocated by the caller via one of the type-specific allocation functions. The element that the pad belongs to is responsible for filling the query with an appropriate response, which should then be parsed with a type-specific query parsing @@ -44651,24 +46782,24 @@ Again, the caller is responsible for both the allocation and deallocation of the query structure. Please also note that some queries might need a running pipeline to work. - + %TRUE if the query could be performed. + line="4208">%TRUE if the query could be performed. a #GstPad to invoke the default query on. + line="4194">a #GstPad to invoke the default query on. the #GstQuery to perform. + line="4195">the #GstQuery to perform. @@ -44678,7 +46809,7 @@ Please also note that some queries might need a running pipeline to work. Check if the given pad accepts the caps. - + - + Queries a pad to convert @src_val in @src_format to @dest_format. - + Invokes the default query handler for the given pad. + line="3501">Invokes the default query handler for the given pad. The query is sent to all pads internally linked to @pad. Note that if there are many possible sink pads that are internally linked to @pad, only one will be sent the query. Multi-sinkpad elements should implement custom query handlers. - + %TRUE if the query was performed successfully. + line="3513">%TRUE if the query was performed successfully. a #GstPad to call the default query handler on. + line="3503">a #GstPad to call the default query handler on. allow-none="1"> the parent of @pad or %NULL + line="3504">the parent of @pad or %NULL the #GstQuery to handle. + line="3505">the #GstQuery to handle. @@ -44833,7 +46964,7 @@ Multi-sinkpad elements should implement custom query handlers. Queries a pad for the total stream duration. - + Queries a pad for the stream position. - + Remove the probe with @id from @pad. + line="1563">Remove the probe with @id from @pad. MT safe. - + @@ -44918,13 +47049,13 @@ MT safe. the #GstPad with the probe + line="1565">the #GstPad with the probe the probe id to remove + line="1566">the probe id to remove @@ -44932,7 +47063,7 @@ MT safe. Sends the event to the pad. This function can be used + line="6174">Sends the event to the pad. This function can be used by applications to send events in the pipeline. If @pad is a source pad, @event should be an upstream event. If @pad is a @@ -44952,24 +47083,24 @@ all necessary locks and checks. This function takes ownership of the provided event so you should gst_event_ref() it if you want to reuse the event after this call. - + %TRUE if the event was handled. + line="6200">%TRUE if the event was handled. a #GstPad to send the event to. + line="6176">a #GstPad to send the event to. the #GstEvent to send to the pad. + line="6177">the #GstEvent to send to the pad. @@ -44978,12 +47109,12 @@ gst_event_ref() it if you want to reuse the event after this call. c:identifier="gst_pad_set_activate_function_full"> Sets the given activate function for @pad. The activate function will + line="1728">Sets the given activate function for @pad. The activate function will dispatch to gst_pad_activate_mode() to perform the actual activation. Only makes sense to set on sink pads. Call this function if your sink pad can start a pull-based task. - + @@ -44991,7 +47122,7 @@ Call this function if your sink pad can start a pull-based task. a #GstPad. + line="1730">a #GstPad. destroy="2"> the #GstPadActivateFunction to set. + line="1731">the #GstPadActivateFunction to set. allow-none="1"> user_data passed to @notify + line="1732">user_data passed to @notify notify called when @activate will not be used anymore. + line="1733">notify called when @activate will not be used anymore. @@ -45025,9 +47156,9 @@ Call this function if your sink pad can start a pull-based task. c:identifier="gst_pad_set_activatemode_function_full"> Sets the given activate_mode function for the pad. An activate_mode function + line="1765">Sets the given activate_mode function for the pad. An activate_mode function prepares the element for data passing. - + @@ -45035,7 +47166,7 @@ prepares the element for data passing. a #GstPad. + line="1767">a #GstPad. destroy="2"> the #GstPadActivateModeFunction to set. + line="1768">the #GstPadActivateModeFunction to set. @@ -45055,13 +47186,13 @@ prepares the element for data passing. allow-none="1"> user_data passed to @notify + line="1769">user_data passed to @notify notify called when @activatemode will not be used anymore. + line="1770">notify called when @activatemode will not be used anymore. @@ -45069,7 +47200,7 @@ prepares the element for data passing. Activates or deactivates the given pad. + line="1080">Activates or deactivates the given pad. Normally called from within core state change functions. If @active, makes sure the pad is active. If it is already active, either in @@ -45078,11 +47209,11 @@ function to perform the actual activation. If not @active, calls gst_pad_activate_mode() with the pad's current mode and a %FALSE argument. - + %TRUE if the operation was successful. + line="1095">%TRUE if the operation was successful. MT safe. @@ -45091,13 +47222,13 @@ MT safe. the #GstPad to activate or deactivate. + line="1082">the #GstPad to activate or deactivate. whether or not the pad should be active. + line="1083">whether or not the pad should be active. @@ -45106,9 +47237,9 @@ MT safe. c:identifier="gst_pad_set_chain_function_full"> Sets the given chain function for the pad. The chain function is called to + line="1800">Sets the given chain function for the pad. The chain function is called to process a #GstBuffer input buffer. see #GstPadChainFunction for more details. - + @@ -45116,7 +47247,7 @@ process a #GstBuffer input buffer. see #GstPadChainFunction for more details. a sink #GstPad. + line="1802">a sink #GstPad. the #GstPadChainFunction to set. + line="1803">the #GstPadChainFunction to set. user_data passed to @notify + line="1804">user_data passed to @notify notify called when @chain will not be used anymore. + line="1805">notify called when @chain will not be used anymore. @@ -45150,10 +47281,10 @@ process a #GstBuffer input buffer. see #GstPadChainFunction for more details. Sets the given chain list function for the pad. The chainlist function is + line="1835">Sets the given chain list function for the pad. The chainlist function is called to process a #GstBufferList input buffer list. See #GstPadChainListFunction for more details. - + @@ -45161,7 +47292,7 @@ called to process a #GstBufferList input buffer list. See a sink #GstPad. + line="1837">a sink #GstPad. the #GstPadChainListFunction to set. + line="1838">the #GstPadChainListFunction to set. @@ -45181,13 +47312,13 @@ called to process a #GstBufferList input buffer list. See allow-none="1"> user_data passed to @notify + line="1839">user_data passed to @notify notify called when @chainlist will not be used anymore. + line="1840">notify called when @chainlist will not be used anymore. @@ -45196,10 +47327,10 @@ called to process a #GstBufferList input buffer list. See c:identifier="gst_pad_set_element_private"> Set the given private data gpointer on the pad. + line="6245">Set the given private data gpointer on the pad. This function can only be used by the element that owns the pad. No locking is performed in this function. - + @@ -45207,7 +47338,7 @@ No locking is performed in this function. the #GstPad to set the private data of. + line="6247">the #GstPad to set the private data of. allow-none="1"> The private data to attach to the pad. + line="6248">The private data to attach to the pad. @@ -45226,8 +47357,8 @@ No locking is performed in this function. version="1.8"> Sets the given event handler for the pad. - + line="1952">Sets the given event handler for the pad. + @@ -45235,7 +47366,7 @@ No locking is performed in this function. a #GstPad of either direction. + line="1954">a #GstPad of either direction. destroy="2"> the #GstPadEventFullFunction to set. + line="1955">the #GstPadEventFullFunction to set. @@ -45255,13 +47386,13 @@ No locking is performed in this function. allow-none="1"> user_data passed to @notify + line="1956">user_data passed to @notify notify called when @event will not be used anymore. + line="1957">notify called when @event will not be used anymore. @@ -45270,8 +47401,8 @@ No locking is performed in this function. c:identifier="gst_pad_set_event_function_full"> Sets the given event handler for the pad. - + line="1908">Sets the given event handler for the pad. + @@ -45279,7 +47410,7 @@ No locking is performed in this function. a #GstPad of either direction. + line="1910">a #GstPad of either direction. destroy="2"> the #GstPadEventFunction to set. + line="1911">the #GstPadEventFunction to set. allow-none="1"> user_data passed to @notify + line="1912">user_data passed to @notify notify called when @event will not be used anymore. + line="1913">notify called when @event will not be used anymore. @@ -45313,10 +47444,10 @@ No locking is performed in this function. c:identifier="gst_pad_set_getrange_function_full"> Sets the given getrange function for the pad. The getrange function is + line="1872">Sets the given getrange function for the pad. The getrange function is called to produce a new #GstBuffer to start the processing pipeline. see #GstPadGetRangeFunction for a description of the getrange function. - + @@ -45324,7 +47455,7 @@ called to produce a new #GstBuffer to start the processing pipeline. see a source #GstPad. + line="1874">a source #GstPad. the #GstPadGetRangeFunction to set. + line="1875">the #GstPadGetRangeFunction to set. user_data passed to @notify + line="1876">user_data passed to @notify notify called when @get will not be used anymore. + line="1877">notify called when @get will not be used anymore. @@ -45358,8 +47489,8 @@ called to produce a new #GstBuffer to start the processing pipeline. see c:identifier="gst_pad_set_iterate_internal_links_function_full"> Sets the given internal link iterator function for the pad. - + line="2021">Sets the given internal link iterator function for the pad. + @@ -45367,7 +47498,7 @@ called to produce a new #GstBuffer to start the processing pipeline. see a #GstPad of either direction. + line="2023">a #GstPad of either direction. the #GstPadIterIntLinkFunction to set. + line="2024">the #GstPadIterIntLinkFunction to set. @@ -45387,13 +47518,13 @@ called to produce a new #GstBuffer to start the processing pipeline. see allow-none="1"> user_data passed to @notify + line="2025">user_data passed to @notify notify called when @iterintlink will not be used anymore. + line="2026">notify called when @iterintlink will not be used anymore. @@ -45402,7 +47533,7 @@ called to produce a new #GstBuffer to start the processing pipeline. see c:identifier="gst_pad_set_link_function_full"> Sets the given link function for the pad. It will be called when + line="2055">Sets the given link function for the pad. It will be called when the pad is linked with another pad. The return value #GST_PAD_LINK_OK should be used when the connection can be @@ -45413,7 +47544,7 @@ cannot be made for some reason. If @link is installed on a source pad, it should call the #GstPadLinkFunction of the peer sink pad, if present. - + @@ -45421,7 +47552,7 @@ of the peer sink pad, if present. a #GstPad. + line="2057">a #GstPad. destroy="2"> the #GstPadLinkFunction to set. + line="2058">the #GstPadLinkFunction to set. allow-none="1"> user_data passed to @notify + line="2059">user_data passed to @notify notify called when @link will not be used anymore. + line="2060">notify called when @link will not be used anymore. @@ -45456,8 +47587,11 @@ of the peer sink pad, if present. glib:set-property="offset"> Set the offset that will be applied to the running time of @pad. - + line="4021">Set the offset that will be applied to the running time of @pad. Upon next +buffer, every sticky events (notably segment) will be pushed again with +their running time adjusted. For that reason this is only reliable on +source pads. + @@ -45465,13 +47599,13 @@ of the peer sink pad, if present. a #GstPad + line="4023">a #GstPad the offset + line="4024">the offset @@ -45480,8 +47614,8 @@ of the peer sink pad, if present. c:identifier="gst_pad_set_query_function_full"> Set the given query function for the pad. - + line="1988">Set the given query function for the pad. + @@ -45489,7 +47623,7 @@ of the peer sink pad, if present. a #GstPad of either direction. + line="1990">a #GstPad of either direction. destroy="2"> the #GstPadQueryFunction to set. + line="1991">the #GstPadQueryFunction to set. allow-none="1"> user_data passed to @notify + line="1992">user_data passed to @notify notify called when @query will not be used anymore. + line="1993">notify called when @query will not be used anymore. @@ -45523,13 +47657,13 @@ of the peer sink pad, if present. c:identifier="gst_pad_set_unlink_function_full"> Sets the given unlink function for the pad. It will be called + line="2098">Sets the given unlink function for the pad. It will be called when the pad is unlinked. Note that the pad's lock is already held when the unlink function is called, so most pad functions cannot be called from within the callback. - + @@ -45537,7 +47671,7 @@ from within the callback. a #GstPad. + line="2100">a #GstPad. destroy="2"> the #GstPadUnlinkFunction to set. + line="2101">the #GstPadUnlinkFunction to set. allow-none="1"> user_data passed to @notify + line="2102">user_data passed to @notify notify called when @unlink will not be used anymore. + line="2103">notify called when @unlink will not be used anymore. @@ -45570,22 +47704,22 @@ from within the callback. Starts a task that repeatedly calls @func with @user_data. This function + line="6410">Starts a task that repeatedly calls @func with @user_data. This function is mostly used in pad activation functions to start the dataflow. The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired before @func is called. - + a %TRUE if the task could be started. + line="6422">a %TRUE if the task could be started. the #GstPad to start the task of + line="6412">the #GstPad to start the task of destroy="2"> the task function to call + line="6413">the task function to call allow-none="1"> user data passed to the task function + line="6414">user data passed to the task function called when @user_data is no longer referenced + line="6415">called when @user_data is no longer referenced @@ -45619,9 +47753,9 @@ before @func is called. c:identifier="gst_pad_sticky_events_foreach"> Iterates all sticky events on @pad and calls @foreach_func for every + line="6329">Iterates all sticky events on @pad and calls @foreach_func for every event. If @foreach_func returns %FALSE the iteration is immediately stopped. - + @@ -45629,7 +47763,7 @@ event. If @foreach_func returns %FALSE the iteration is immediately stopped. the #GstPad that should be used for iteration. + line="6331">the #GstPad that should be used for iteration. the #GstPadStickyEventsForeachFunction that - should be called for every event. + line="6332">the + #GstPadStickyEventsForeachFunction that should be called for every event. @@ -45649,7 +47783,7 @@ event. If @foreach_func returns %FALSE the iteration is immediately stopped. the optional user data. + line="6334">the optional user data. @@ -45657,7 +47791,7 @@ event. If @foreach_func returns %FALSE the iteration is immediately stopped. Stop the task of @pad. This function will also make sure that the + line="6558">Stop the task of @pad. This function will also make sure that the function executed by the task will effectively stop if not called from the GstTaskFunction. @@ -45666,18 +47800,18 @@ the task. Use gst_task_pause() instead. Regardless of whether the pad has a task, the stream lock is acquired and released so as to ensure that streaming through this pad has finished. - + a %TRUE if the task could be stopped or %FALSE on error. + line="6572">a %TRUE if the task could be stopped or %FALSE on error. the #GstPad to stop the task of + line="6560">the #GstPad to stop the task of @@ -45687,12 +47821,12 @@ released so as to ensure that streaming through this pad has finished. version="1.2"> Store the sticky @event on @pad - + line="5509">Store the sticky @event on @pad + #GST_FLOW_OK on success, #GST_FLOW_FLUSHING when the pad + line="5516">#GST_FLOW_OK on success, #GST_FLOW_FLUSHING when the pad was flushing or #GST_FLOW_EOS when the pad was EOS. @@ -45700,13 +47834,13 @@ was flushing or #GST_FLOW_EOS when the pad was EOS. a #GstPad + line="5511">a #GstPad a #GstEvent + line="5512">a #GstEvent @@ -45714,13 +47848,13 @@ was flushing or #GST_FLOW_EOS when the pad was EOS. Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked + line="2128">Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked signal on both pads. - + %TRUE if the pads were unlinked. This function returns %FALSE if + line="2136">%TRUE if the pads were unlinked. This function returns %FALSE if the pads were not linked together. MT safe. @@ -45730,13 +47864,13 @@ MT safe. the source #GstPad to unlink. + line="2130">the source #GstPad to unlink. the sink #GstPad to unlink. + line="2131">the sink #GstPad to unlink. @@ -45751,7 +47885,7 @@ or in case the pad is not negotiated, the padtemplate caps. The negotiated caps are the caps of the last CAPS event that passed on the pad. Use this function on a pad that, once it negotiated to a CAPS, cannot be renegotiated to something else. - + @@ -45784,7 +47918,7 @@ be renegotiated to something else. default-value="0"> The offset that will be applied to the running time of the pad. + line="383">The offset that will be applied to the running time of the pad. @@ -45955,7 +48089,7 @@ be renegotiated to something else. Signals that a pad has been linked to the peer pad. + line="344">Signals that a pad has been linked to the peer pad. @@ -45963,7 +48097,7 @@ be renegotiated to something else. the peer pad that has been connected + line="347">the peer pad that has been connected @@ -45971,7 +48105,7 @@ be renegotiated to something else. Signals that a pad has been unlinked from the peer pad. + line="355">Signals that a pad has been unlinked from the peer pad. @@ -45979,7 +48113,7 @@ be renegotiated to something else. the peer pad that has been disconnected + line="358">the peer pad that has been disconnected @@ -46825,19 +48959,19 @@ pad operates in push or pull mode. Return the name of a pad mode, for use in debug messages mostly. + line="960">Return the name of a pad mode, for use in debug messages mostly. short mnemonic for pad mode @mode + line="966">short mnemonic for pad mode @mode the pad mode + line="962">the pad mode @@ -46978,14 +49112,14 @@ The callback is allowed to modify the data pointer in @info. The #GstBuffer from the probe + line="6669">The #GstBuffer from the probe a #GstPadProbeInfo + line="6667">a #GstPadProbeInfo @@ -46996,14 +49130,14 @@ The callback is allowed to modify the data pointer in @info. The #GstBufferList from the probe + line="6684">The #GstBufferList from the probe a #GstPadProbeInfo + line="6682">a #GstPadProbeInfo @@ -47013,14 +49147,14 @@ The callback is allowed to modify the data pointer in @info. The #GstEvent from the probe + line="6636">The #GstEvent from the probe a #GstPadProbeInfo + line="6634">a #GstPadProbeInfo @@ -47030,14 +49164,14 @@ The callback is allowed to modify the data pointer in @info. The #GstQuery from the probe + line="6653">The #GstQuery from the probe a #GstPadProbeInfo + line="6651">a #GstPadProbeInfo @@ -48016,12 +50150,12 @@ for re-use. version="1.6"> Gets the global #GstMetaInfo describing the #GstParentBufferMeta meta. + line="2698">Gets the global #GstMetaInfo describing the #GstParentBufferMeta meta. The #GstMetaInfo + line="2703">The #GstMetaInfo @@ -48323,12 +50457,12 @@ gst_element_set_start_time() method. Create a new pipeline with the given name. + line="337">Create a new pipeline with the given name. newly created GstPipeline + line="343">newly created GstPipeline MT safe. @@ -48340,7 +50474,7 @@ MT safe. allow-none="1"> name of new pipeline + line="339">name of new pipeline @@ -48348,7 +50482,7 @@ MT safe. Let @pipeline select a clock automatically. This is the default + line="906">Let @pipeline select a clock automatically. This is the default behaviour. Use this function if you previous forced a fixed clock with @@ -48364,7 +50498,7 @@ MT safe. a #GstPipeline + line="908">a #GstPipeline @@ -48374,13 +50508,13 @@ MT safe. glib:get-property="auto-flush-bus"> Check if @pipeline will automatically flush messages when going to + line="1019">Check if @pipeline will automatically flush messages when going to the NULL state. whether the pipeline will automatically flush its bus when + line="1026">whether the pipeline will automatically flush its bus when going from READY to NULL state or not. MT safe. @@ -48390,7 +50524,7 @@ MT safe. a #GstPipeline + line="1021">a #GstPipeline @@ -48398,13 +50532,13 @@ MT safe. Gets the #GstBus of @pipeline. The bus allows applications to receive + line="756">Gets the #GstBus of @pipeline. The bus allows applications to receive #GstMessage packets. a #GstBus, unref after usage. + line="763">a #GstBus, unref after usage. MT safe. @@ -48413,7 +50547,7 @@ MT safe. a #GstPipeline + line="758">a #GstPipeline @@ -48423,7 +50557,7 @@ MT safe. introspectable="0"> Gets the current clock used by @pipeline. Users of object + line="809">Gets the current clock used by @pipeline. Users of object oriented languages should use gst_pipeline_get_pipeline_clock() to avoid confusion with gst_element_get_clock() which has a different behavior. @@ -48433,14 +50567,39 @@ clock, even if the pipeline is not in the PLAYING state. a #GstClock, unref after usage. + line="820">a #GstClock, unref after usage. a #GstPipeline + line="811">a #GstPipeline + + + + + + Return the configured latency on @pipeline. + + + @pipeline configured latency, or %GST_CLOCK_TIME_NONE if none has been configured +because @pipeline did not reach the PLAYING state yet. + +MT safe. + + + + + a #GstPipeline @@ -48450,12 +50609,12 @@ clock, even if the pipeline is not in the PLAYING state. glib:get-property="delay"> Get the configured delay (see gst_pipeline_set_delay()). + line="964">Get the configured delay (see gst_pipeline_set_delay()). The configured delay. + line="970">The configured delay. MT safe. @@ -48464,7 +50623,7 @@ MT safe. a #GstPipeline + line="966">a #GstPipeline @@ -48475,20 +50634,20 @@ MT safe. version="1.6"> Gets the latency that should be configured on the pipeline. See + line="1076">Gets the latency that should be configured on the pipeline. See gst_pipeline_set_latency(). Latency to configure on the pipeline or GST_CLOCK_TIME_NONE + line="1083">Latency to configure on the pipeline or GST_CLOCK_TIME_NONE a #GstPipeline + line="1078">a #GstPipeline @@ -48498,7 +50657,7 @@ gst_pipeline_set_latency(). version="1.6"> Gets the current clock used by @pipeline. + line="828">Gets the current clock used by @pipeline. Unlike gst_element_get_clock(), this function will always return a clock, even if the pipeline is not in the PLAYING state. @@ -48506,14 +50665,38 @@ clock, even if the pipeline is not in the PLAYING state. a #GstClock, unref after usage. + line="837">a #GstClock, unref after usage. a #GstPipeline + line="830">a #GstPipeline + + + + + + Check if @pipeline is live. + + + %TRUE if @pipeline is live, %FALSE if not or if it did not reach the PAUSED state yet. + +MT safe. + + + + + a #GstPipeline @@ -48523,7 +50706,7 @@ clock, even if the pipeline is not in the PLAYING state. glib:set-property="auto-flush-bus"> Usually, when a pipeline goes from READY to NULL state, it automatically + line="988">Usually, when a pipeline goes from READY to NULL state, it automatically flushes all pending messages on the bus, which is done for refcounting purposes, to break circular references. @@ -48545,13 +50728,13 @@ MT safe. a #GstPipeline + line="990">a #GstPipeline whether or not to automatically flush the bus when + line="991">whether or not to automatically flush the bus when the pipeline goes from READY to NULL state @@ -48562,13 +50745,13 @@ the pipeline goes from READY to NULL state introspectable="0"> Set the clock for @pipeline. The clock will be distributed + line="882">Set the clock for @pipeline. The clock will be distributed to all the elements managed by the pipeline. %TRUE if the clock could be set on the pipeline. %FALSE if + line="890">%TRUE if the clock could be set on the pipeline. %FALSE if some element did not accept the clock. MT safe. @@ -48578,7 +50761,7 @@ MT safe. a #GstPipeline + line="884">a #GstPipeline allow-none="1"> the clock to set + line="885">the clock to set @@ -48597,7 +50780,7 @@ MT safe. glib:set-property="delay"> Set the expected delay needed for all elements to perform the + line="937">Set the expected delay needed for all elements to perform the PAUSED to PLAYING state change. @delay will be added to the base time of the elements so that they wait an additional @delay amount of time before starting to process buffers and cannot be @@ -48615,13 +50798,13 @@ MT safe. a #GstPipeline + line="939">a #GstPipeline the delay + line="940">the delay @@ -48632,7 +50815,7 @@ MT safe. version="1.6"> Sets the latency that should be configured on the pipeline. Setting + line="1045">Sets the latency that should be configured on the pipeline. Setting GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum latency from the LATENCY query. Setting this is usually not required and the pipeline will figure out an appropriate latency automatically. @@ -48647,13 +50830,13 @@ the LATENCY query, will most likely cause the pipeline to fail. a #GstPipeline + line="1047">a #GstPipeline latency to configure + line="1048">latency to configure @@ -48661,7 +50844,7 @@ the LATENCY query, will most likely cause the pipeline to fail. Force @pipeline to use the given @clock. The pipeline will + line="850">Force @pipeline to use the given @clock. The pipeline will always use the given clock even if new clock providers are added to this pipeline. @@ -48677,7 +50860,7 @@ MT safe. a #GstPipeline + line="852">a #GstPipeline allow-none="1"> the clock to use + line="853">the clock to use @@ -48699,7 +50882,7 @@ MT safe. default-value="TRUE"> Whether or not to automatically flush all messages on the + line="184">Whether or not to automatically flush all messages on the pipeline's bus when going from READY to NULL state. Please see gst_pipeline_set_auto_flush_bus() for more information on this option. @@ -48712,7 +50895,7 @@ gst_pipeline_set_auto_flush_bus() for more information on this option. default-value="0"> The expected delay needed for elements to spin up to the + line="171">The expected delay needed for elements to spin up to the PLAYING state expressed in nanoseconds. see gst_pipeline_set_delay() for more information on this option. @@ -48726,7 +50909,7 @@ see gst_pipeline_set_delay() for more information on this option. default-value="18446744073709551615"> Latency to configure on the pipeline. See gst_pipeline_set_latency(). + line="197">Latency to configure on the pipeline. See gst_pipeline_set_latency(). @@ -48841,8 +51024,8 @@ into memory. Unrefs each member of @list, then frees the list. - + line="1493">Unrefs each member of @list, then frees the list. + @@ -48850,7 +51033,7 @@ into memory. list of #GstPlugin + line="1495">list of #GstPlugin @@ -48860,12 +51043,12 @@ into memory. Load the named plugin. Refs the plugin. + line="1412">Load the named plugin. Refs the plugin. a reference to a loaded plugin, or + line="1418">a reference to a loaded plugin, or %NULL on error. @@ -48873,7 +51056,7 @@ into memory. name of plugin to load + line="1414">name of plugin to load @@ -48883,12 +51066,12 @@ into memory. throws="1"> Loads the given plugin and refs it. Caller needs to unref after use. + line="688">Loads the given plugin and refs it. Caller needs to unref after use. a reference to the existing loaded GstPlugin, a + line="695">a reference to the existing loaded GstPlugin, a reference to the newly-loaded GstPlugin, or %NULL if an error occurred. @@ -48896,7 +51079,7 @@ reference to the newly-loaded GstPlugin, or %NULL if an error occurred. the plugin filename to load + line="690">the plugin filename to load @@ -48905,7 +51088,7 @@ reference to the newly-loaded GstPlugin, or %NULL if an error occurred. c:identifier="gst_plugin_register_static"> Registers a static plugin, ie. a plugin which is private to an application + line="182">Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file). @@ -48915,28 +51098,28 @@ via gst_init_get_option_group()) before calling this function. %TRUE if the plugin was registered correctly, otherwise %FALSE. + line="207">%TRUE if the plugin was registered correctly, otherwise %FALSE. the major version number of the GStreamer core that the + line="184">the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here the minor version number of the GStreamer core that the + line="186">the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here a unique name of the plugin (ideally prefixed with an application- or + line="188">a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer) @@ -48944,44 +51127,44 @@ via gst_init_get_option_group()) before calling this function. description of the plugin + line="191">description of the plugin pointer to the init function of this plugin. + line="192">pointer to the init function of this plugin. version string of the plugin + line="193">version string of the plugin effective license of plugin. Must be one of the approved licenses + line="194">effective license of plugin. Must be one of the approved licenses (see #GstPluginDesc above) or the plugin will not be registered. source module plugin belongs to + line="196">source module plugin belongs to shipped package plugin belongs to + line="197">shipped package plugin belongs to URL to provider of plugin + line="198">URL to provider of plugin @@ -48990,7 +51173,7 @@ via gst_init_get_option_group()) before calling this function. c:identifier="gst_plugin_register_static_full"> Registers a static plugin, ie. a plugin which is private to an application + line="243">Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file) with a #GstPluginInitFullFunc which allows user data to be passed to the callback function (useful @@ -49002,28 +51185,28 @@ via gst_init_get_option_group()) before calling this function. %TRUE if the plugin was registered correctly, otherwise %FALSE. + line="272">%TRUE if the plugin was registered correctly, otherwise %FALSE. the major version number of the GStreamer core that the + line="245">the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here the minor version number of the GStreamer core that the + line="247">the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here a unique name of the plugin (ideally prefixed with an application- or + line="249">a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer) @@ -49031,7 +51214,7 @@ via gst_init_get_option_group()) before calling this function. description of the plugin + line="252">description of the plugin closure="10"> pointer to the init function with user data + line="253">pointer to the init function with user data of this plugin. version string of the plugin + line="255">version string of the plugin effective license of plugin. Must be one of the approved licenses + line="256">effective license of plugin. Must be one of the approved licenses (see #GstPluginDesc above) or the plugin will not be registered. source module plugin belongs to + line="258">source module plugin belongs to shipped package plugin belongs to + line="259">shipped package plugin belongs to URL to provider of plugin + line="260">URL to provider of plugin allow-none="1"> gpointer to user data + line="261">gpointer to user data @@ -49089,7 +51272,7 @@ via gst_init_get_option_group()) before calling this function. Make GStreamer aware of external dependencies which affect the feature + line="1926">Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it). GStreamer will re-inspect plugins with external dependencies whenever any @@ -49106,7 +51289,7 @@ codec libraries are currently installed. a #GstPlugin + line="1928">a #GstPlugin allow-none="1"> %NULL-terminated array of environment variables affecting the + line="1929">%NULL-terminated array of environment variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or %NULL. Environment variable names may be followed by a path component @@ -49131,7 +51314,7 @@ codec libraries are currently installed. allow-none="1"> %NULL-terminated array of directories/paths where dependent files + line="1935">%NULL-terminated array of directories/paths where dependent files may be, or %NULL. @@ -49143,7 +51326,7 @@ codec libraries are currently installed. allow-none="1"> %NULL-terminated array of file names (or file name suffixes, + line="1937">%NULL-terminated array of file names (or file name suffixes, depending on @flags) to be used in combination with the paths from @paths and/or the paths extracted from the environment variables in @env_vars, or %NULL. @@ -49154,7 +51337,7 @@ codec libraries are currently installed. optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE + line="1941">optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE @@ -49164,7 +51347,7 @@ codec libraries are currently installed. c:identifier="gst_plugin_add_dependency_simple"> Make GStreamer aware of external dependencies which affect the feature + line="1997">Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it). GStreamer will re-inspect plugins with external dependencies whenever any @@ -49185,7 +51368,7 @@ arguments separated by predefined delimiters (see above). the #GstPlugin + line="1999">the #GstPlugin allow-none="1"> one or more environment variables (separated by ':', ';' or ','), + line="2000">one or more environment variables (separated by ':', ';' or ','), or %NULL. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH" @@ -49206,7 +51389,7 @@ arguments separated by predefined delimiters (see above). allow-none="1"> one ore more directory paths (separated by ':' or ';' or ','), + line="2004">one ore more directory paths (separated by ':' or ';' or ','), or %NULL. Example: "/usr/lib/mystuff/plugins" @@ -49216,29 +51399,95 @@ arguments separated by predefined delimiters (see above). allow-none="1"> one or more file names or file name suffixes (separated by commas), + line="2006">one or more file names or file name suffixes (separated by commas), or %NULL optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE + line="2008">optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE + + + + + + + + a #GstPlugin + + + + the status error message + + + + + + + + + + + + a #GstPlugin + + + + the status info message + + + + + + + + + + + + a #GstPlugin + + + + the status warning message + + + + Gets the plugin specific data cache. If it is %NULL there is no cached data + line="1210">Gets the plugin specific data cache. If it is %NULL there is no cached data stored. This is the case when the registry is getting rebuilt. The cached data as a + line="1217">The cached data as a #GstStructure or %NULL. @@ -49246,7 +51495,7 @@ stored. This is the case when the registry is getting rebuilt. a plugin + line="1212">a plugin @@ -49254,19 +51503,19 @@ stored. This is the case when the registry is getting rebuilt. Get the long descriptive name of the plugin + line="1050">Get the long descriptive name of the plugin the long name of the plugin + line="1056">the long name of the plugin plugin to get long name of + line="1052">plugin to get long name of @@ -49274,19 +51523,19 @@ stored. This is the case when the registry is getting rebuilt. get the filename of the plugin + line="1066">get the filename of the plugin the filename of the plugin + line="1072">the filename of the plugin plugin to get the filename of + line="1068">plugin to get the filename of @@ -49294,19 +51543,19 @@ stored. This is the case when the registry is getting rebuilt. get the license of the plugin + line="1098">get the license of the plugin the license of the plugin + line="1104">the license of the plugin plugin to get the license of + line="1100">plugin to get the license of @@ -49314,19 +51563,19 @@ stored. This is the case when the registry is getting rebuilt. Get the short name of the plugin + line="1034">Get the short name of the plugin the name of the plugin + line="1040">the name of the plugin plugin to get the name of + line="1036">plugin to get the name of @@ -49334,19 +51583,19 @@ stored. This is the case when the registry is getting rebuilt. get the URL where the plugin comes from + line="1146">get the URL where the plugin comes from the origin of the plugin + line="1152">the origin of the plugin plugin to get the origin of + line="1148">plugin to get the origin of @@ -49354,19 +51603,19 @@ stored. This is the case when the registry is getting rebuilt. get the package the plugin belongs to. + line="1130">get the package the plugin belongs to. the package of the plugin + line="1136">the package of the plugin plugin to get the package of + line="1132">plugin to get the package of @@ -49375,7 +51624,7 @@ stored. This is the case when the registry is getting rebuilt. c:identifier="gst_plugin_get_release_date_string"> Get the release date (and possibly time) in form of a string, if available. + line="1162">Get the release date (and possibly time) in form of a string, if available. For normal GStreamer plugin releases this will usually just be a date in the form of "YYYY-MM-DD", while pre-releases and builds from git may contain @@ -49387,7 +51636,7 @@ There may be plugins that do not have a valid release date set on them. the date string of the plugin, or %NULL if not + line="1175">the date string of the plugin, or %NULL if not available. @@ -49395,7 +51644,7 @@ available. plugin to get the release date of + line="1164">plugin to get the release date of @@ -49403,19 +51652,82 @@ available. get the source module the plugin belongs to. + line="1114">get the source module the plugin belongs to. the source of the plugin + line="1120">the source of the plugin plugin to get the source of + line="1116">plugin to get the source of + + + + + + + + an array of plugin status error messages, or NULL + + + + + + + a #GstPlugin + + + + + + + + an array of plugin status info messages, or NULL + + + + + + + a #GstPlugin + + + + + + + + an array of plugin status warning messages, or NULL + + + + + + + a #GstPlugin @@ -49423,19 +51735,19 @@ available. get the version of the plugin + line="1082">get the version of the plugin the version of the plugin + line="1088">the version of the plugin plugin to get the version of + line="1084">plugin to get the version of @@ -49443,19 +51755,19 @@ available. queries if the plugin is loaded into memory + line="1186">queries if the plugin is loaded into memory %TRUE is loaded, %FALSE otherwise + line="1192">%TRUE is loaded, %FALSE otherwise plugin to query + line="1188">plugin to query @@ -49463,7 +51775,7 @@ available. Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is + line="1452">Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is untouched. The normal use pattern of this function goes like this: |[ @@ -49477,7 +51789,7 @@ plugin = loaded_plugin; a reference to a loaded plugin, or + line="1467">a reference to a loaded plugin, or %NULL on error. @@ -49485,7 +51797,7 @@ plugin = loaded_plugin; plugin to load + line="1454">plugin to load @@ -49493,7 +51805,7 @@ plugin = loaded_plugin; Adds plugin specific data to cache. Passes the ownership of the structure to + line="1228">Adds plugin specific data to cache. Passes the ownership of the structure to the @plugin. The cache is flushed every time the registry is rebuilt. @@ -49505,13 +51817,13 @@ The cache is flushed every time the registry is rebuilt. a plugin + line="1230">a plugin a structure containing the data to cache + line="1231">a structure containing the data to cache @@ -49529,7 +51841,7 @@ The cache is flushed every time the registry is rebuilt. glib:name="GST_PLUGIN_API_FLAG_IGNORE_ENUM_MEMBERS"> Ignore enum members when generating + line="1187">Ignore enum members when generating the plugins cache. This is useful if the members of the enum are generated dynamically, in order not to expose incorrect documentation to the end user. @@ -49826,13 +52138,13 @@ when done with the list. c:identifier="gst_plugin_feature_rank_compare_func"> Compares the two given #GstPluginFeature instances. This function can be + line="381">Compares the two given #GstPluginFeature instances. This function can be used as a #GCompareFunc when sorting by rank and then by name. negative value if the rank of p1 > the rank of p2 or the ranks are + line="389">negative value if the rank of p1 > the rank of p2 or the ranks are equal but the name of p1 comes before the name of p2; zero if the rank and names are equal; positive value if the rank of p1 < the rank of p2 or the ranks are equal but the name of p2 comes before the name of p1 @@ -49845,7 +52157,7 @@ ranks are equal but the name of p2 comes before the name of p1 allow-none="1"> a #GstPluginFeature + line="383">a #GstPluginFeature allow-none="1"> a #GstPluginFeature + line="384">a #GstPluginFeature @@ -49863,13 +52175,18 @@ ranks are equal but the name of p2 comes before the name of p1 c:identifier="gst_plugin_feature_check_version"> Checks whether the given plugin feature is at least - the required version + line="306">Checks whether the given plugin feature is at least the required version. + +Note: Since version 1.24 this function no longer returns %TRUE if the +version is a git development version (e.g. 1.23.0.1) and the check is +for the "next" micro version, that is it will no longer return %TRUE for +e.g. 1.23.0.1 if the check is for 1.23.1. It is still possible to parse +the nano version from the string and do this check that way if needed. %TRUE if the plugin feature has at least + line="321">%TRUE if the plugin feature has at least the required version, otherwise %FALSE. @@ -50856,13 +53173,13 @@ Presets found in those paths will be considered as "app presets". Gets the directory for application specific presets if set by the + line="1236">Gets the directory for application specific presets if set by the application. the directory or %NULL, don't free or modify + line="1242">the directory or %NULL, don't free or modify the string @@ -50870,21 +53187,21 @@ the string Sets an extra directory as an absolute path that should be considered when + line="1214">Sets an extra directory as an absolute path that should be considered when looking for presets. Any presets in the application dir will shadow the system presets. %TRUE for success, %FALSE if the dir already has been set + line="1222">%TRUE for success, %FALSE if the dir already has been set the application specific preset dir + line="1216">the application specific preset dir @@ -50892,25 +53209,25 @@ system presets. Delete the given preset. + line="1147">Delete the given preset. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1154">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1149">a #GObject that implements #GstPreset preset name to remove + line="1150">preset name to remove @@ -50918,13 +53235,13 @@ system presets. Gets the @value for an existing meta data @tag. Meta data @tag names can be + line="1189">Gets the @value for an existing meta data @tag. Meta data @tag names can be something like e.g. "comment". Returned values need to be released when done. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1199">%TRUE for success, %FALSE if e.g. there is no preset with that @name or no value for the given @tag @@ -50932,19 +53249,19 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1191">a #GObject that implements #GstPreset preset name + line="1192">preset name meta data item name + line="1193">meta data item name transfer-ownership="full"> value + line="1194">value @@ -50961,12 +53278,12 @@ or no value for the given @tag Get a copy of preset names as a %NULL terminated string array. + line="1053">Get a copy of preset names as a %NULL terminated string array. + line="1059"> list with names, use g_strfreev() after usage. @@ -50976,7 +53293,7 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1055">a #GObject that implements #GstPreset @@ -50984,12 +53301,12 @@ or no value for the given @tag Get a the names of the GObject properties that can be used for presets. + line="1070">Get a the names of the GObject properties that can be used for presets. an + line="1076">an array of property names which should be freed with g_strfreev() after use. @@ -50999,7 +53316,7 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1072">a #GObject that implements #GstPreset @@ -51007,25 +53324,25 @@ or no value for the given @tag Load the given preset. + line="1087">Load the given preset. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1094">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1089">a #GObject that implements #GstPreset preset name to load + line="1090">preset name to load @@ -51033,32 +53350,32 @@ or no value for the given @tag Renames a preset. If there is already a preset by the @new_name it will be + line="1124">Renames a preset. If there is already a preset by the @new_name it will be overwritten. %TRUE for success, %FALSE if e.g. there is no preset with @old_name + line="1133">%TRUE for success, %FALSE if e.g. there is no preset with @old_name a #GObject that implements #GstPreset + line="1126">a #GObject that implements #GstPreset current preset name + line="1127">current preset name new preset name + line="1128">new preset name @@ -51066,26 +53383,26 @@ overwritten. Save the current object settings as a preset under the given name. If there + line="1105">Save the current object settings as a preset under the given name. If there is already a preset by this @name it will be overwritten. %TRUE for success, %FALSE + line="1113">%TRUE for success, %FALSE a #GObject that implements #GstPreset + line="1107">a #GObject that implements #GstPreset preset name to save + line="1108">preset name to save @@ -51093,33 +53410,33 @@ is already a preset by this @name it will be overwritten. Sets a new @value for an existing meta data item or adds a new item. Meta + line="1165">Sets a new @value for an existing meta data item or adds a new item. Meta data @tag names can be something like e.g. "comment". Supplying %NULL for the @value will unset an existing value. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1176">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1167">a #GObject that implements #GstPreset preset name + line="1168">preset name meta data item name + line="1169">meta data item name new value + line="1170">new value @@ -51136,25 +53453,25 @@ data @tag names can be something like e.g. "comment". Supplying %NULL for the Delete the given preset. + line="1147">Delete the given preset. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1154">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1149">a #GObject that implements #GstPreset preset name to remove + line="1150">preset name to remove @@ -51162,13 +53479,13 @@ data @tag names can be something like e.g. "comment". Supplying %NULL for the Gets the @value for an existing meta data @tag. Meta data @tag names can be + line="1189">Gets the @value for an existing meta data @tag. Meta data @tag names can be something like e.g. "comment". Returned values need to be released when done. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1199">%TRUE for success, %FALSE if e.g. there is no preset with that @name or no value for the given @tag @@ -51176,19 +53493,19 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1191">a #GObject that implements #GstPreset preset name + line="1192">preset name meta data item name + line="1193">meta data item name transfer-ownership="full"> value + line="1194">value @@ -51206,12 +53523,12 @@ or no value for the given @tag c:identifier="gst_preset_get_preset_names"> Get a copy of preset names as a %NULL terminated string array. + line="1053">Get a copy of preset names as a %NULL terminated string array. + line="1059"> list with names, use g_strfreev() after usage. @@ -51221,7 +53538,7 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1055">a #GObject that implements #GstPreset @@ -51230,12 +53547,12 @@ or no value for the given @tag c:identifier="gst_preset_get_property_names"> Get a the names of the GObject properties that can be used for presets. + line="1070">Get a the names of the GObject properties that can be used for presets. an + line="1076">an array of property names which should be freed with g_strfreev() after use. @@ -51245,7 +53562,7 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1072">a #GObject that implements #GstPreset @@ -51255,19 +53572,19 @@ or no value for the given @tag version="1.6"> Check if one can add new presets, change existing ones and remove presets. + line="1251">Check if one can add new presets, change existing ones and remove presets. %TRUE if presets are editable or %FALSE if they are static + line="1257">%TRUE if presets are editable or %FALSE if they are static a #GObject that implements #GstPreset + line="1253">a #GObject that implements #GstPreset @@ -51275,25 +53592,25 @@ or no value for the given @tag Load the given preset. + line="1087">Load the given preset. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1094">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1089">a #GObject that implements #GstPreset preset name to load + line="1090">preset name to load @@ -51301,32 +53618,32 @@ or no value for the given @tag Renames a preset. If there is already a preset by the @new_name it will be + line="1124">Renames a preset. If there is already a preset by the @new_name it will be overwritten. %TRUE for success, %FALSE if e.g. there is no preset with @old_name + line="1133">%TRUE for success, %FALSE if e.g. there is no preset with @old_name a #GObject that implements #GstPreset + line="1126">a #GObject that implements #GstPreset current preset name + line="1127">current preset name new preset name + line="1128">new preset name @@ -51334,26 +53651,26 @@ overwritten. Save the current object settings as a preset under the given name. If there + line="1105">Save the current object settings as a preset under the given name. If there is already a preset by this @name it will be overwritten. %TRUE for success, %FALSE + line="1113">%TRUE for success, %FALSE a #GObject that implements #GstPreset + line="1107">a #GObject that implements #GstPreset preset name to save + line="1108">preset name to save @@ -51361,33 +53678,33 @@ is already a preset by this @name it will be overwritten. Sets a new @value for an existing meta data item or adds a new item. Meta + line="1165">Sets a new @value for an existing meta data item or adds a new item. Meta data @tag names can be something like e.g. "comment". Supplying %NULL for the @value will unset an existing value. %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1176">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1167">a #GObject that implements #GstPreset preset name + line="1168">preset name meta data item name + line="1169">meta data item name new value + line="1170">new value @@ -51416,12 +53733,15 @@ data @tag names can be something like e.g. "comment". Supplying %NULL for the + virtual method to get list of presets + line="1059"> list with names, use g_strfreev() after usage. @@ -51431,19 +53751,22 @@ data @tag names can be something like e.g. "comment". Supplying %NULL for the a #GObject that implements #GstPreset + line="1055">a #GObject that implements #GstPreset + virtual methods to get properties that are persistent an + line="1076">an array of property names which should be freed with g_strfreev() after use. @@ -51453,144 +53776,159 @@ data @tag names can be something like e.g. "comment". Supplying %NULL for the a #GObject that implements #GstPreset + line="1072">a #GObject that implements #GstPreset + virtual methods to load a preset into properties %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1094">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1089">a #GObject that implements #GstPreset preset name to load + line="1090">preset name to load + virtual methods to save properties into a preset %TRUE for success, %FALSE + line="1113">%TRUE for success, %FALSE a #GObject that implements #GstPreset + line="1107">a #GObject that implements #GstPreset preset name to save + line="1108">preset name to save + virtual methods to rename a preset %TRUE for success, %FALSE if e.g. there is no preset with @old_name + line="1133">%TRUE for success, %FALSE if e.g. there is no preset with @old_name a #GObject that implements #GstPreset + line="1126">a #GObject that implements #GstPreset current preset name + line="1127">current preset name new preset name + line="1128">new preset name + virtual methods to remove a preset %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1154">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1149">a #GObject that implements #GstPreset preset name to remove + line="1150">preset name to remove + virtual methods to set textual meta data to a preset %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1176">%TRUE for success, %FALSE if e.g. there is no preset with that @name a #GObject that implements #GstPreset + line="1167">a #GObject that implements #GstPreset preset name + line="1168">preset name meta data item name + line="1169">meta data item name new value + line="1170">new value + virtual methods to get textual meta data from a preset %TRUE for success, %FALSE if e.g. there is no preset with that @name + line="1199">%TRUE for success, %FALSE if e.g. there is no preset with that @name or no value for the given @tag @@ -51619,19 +53960,19 @@ or no value for the given @tag a #GObject that implements #GstPreset + line="1191">a #GObject that implements #GstPreset preset name + line="1192">preset name meta data item name + line="1193">meta data item name transfer-ownership="full"> value + line="1194">value @@ -51768,19 +54109,19 @@ gst_promise_interrupt() or gst_promise_expire() and can be called from an arbitrary thread. #GstPromise using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses #GstPromise. - + parent #GstMiniObject + line="68">parent #GstMiniObject - + a new #GstPromise + line="367">a new #GstPromise @@ -51789,14 +54130,14 @@ that uses #GstPromise. version="1.14"> @func will be called exactly once when transitioning out of + line="382">@func will be called exactly once when transitioning out of %GST_PROMISE_RESULT_PENDING into any of the other #GstPromiseResult states. - + a new #GstPromise + line="392">a new #GstPromise @@ -51807,7 +54148,7 @@ states. destroy="2"> a #GstPromiseChangeFunc to call + line="384">a #GstPromiseChangeFunc to call allow-none="1"> argument to call @func with + line="385">argument to call @func with notification function that @user_data is no longer needed + line="386">notification function that @user_data is no longer needed @@ -51830,10 +54171,10 @@ states. Expire a @promise. This will wake up any waiters with + line="284">Expire a @promise. This will wake up any waiters with %GST_PROMISE_RESULT_EXPIRED. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered). - + @@ -51841,7 +54182,7 @@ message is handled and/or destroyed (possibly unanswered). a #GstPromise + line="286">a #GstPromise @@ -51851,20 +54192,20 @@ message is handled and/or destroyed (possibly unanswered). version="1.14"> Retrieve the reply set on @promise. @promise must be in + line="216">Retrieve the reply set on @promise. @promise must be in %GST_PROMISE_RESULT_REPLIED and the returned structure is owned by @promise - + The reply set on @promise + line="223">The reply set on @promise a #GstPromise + line="218">a #GstPromise @@ -51874,10 +54215,10 @@ message is handled and/or destroyed (possibly unanswered). version="1.14"> Interrupt waiting for a @promise. This will wake up any waiters with + line="244">Interrupt waiting for a @promise. This will wake up any waiters with %GST_PROMISE_RESULT_INTERRUPTED. Called when the consumer does not want the value produced anymore. - + @@ -51885,7 +54226,7 @@ the value produced anymore. a #GstPromise + line="246">a #GstPromise @@ -51899,7 +54240,7 @@ indicate success (or failure). If @promise has already been interrupted by the consumer, then this reply is not visible to the consumer. - + @@ -51930,7 +54271,7 @@ is not visible to the consumer. line="116">Wait for @promise to move out of the %GST_PROMISE_RESULT_PENDING state. If @promise is not in %GST_PROMISE_RESULT_PENDING then it will return immediately with the current result. - + - + @@ -51958,7 +54299,7 @@ immediately with the current result. a #GstPromise + line="59">a #GstPromise closure="1"> user data + line="60">user data @@ -51980,7 +54321,7 @@ immediately with the current result. c:type="GstPromiseResult"> The result of a #GstPromise + line="35">The result of a #GstPromise glib:name="GST_PROMISE_RESULT_PENDING"> Initial state. Waiting for transition to any + line="37">Initial state. Waiting for transition to any other state. glib:name="GST_PROMISE_RESULT_INTERRUPTED"> Interrupted by the consumer as it doesn't + line="39">Interrupted by the consumer as it doesn't want the value anymore. glib:name="GST_PROMISE_RESULT_REPLIED"> A producer marked a reply + line="41">A producer marked a reply glib:name="GST_PROMISE_RESULT_EXPIRED"> The promise expired (the carrying object + line="42">The promise expired (the carrying object lost all refs) and the promise will never be fulfilled. @@ -52470,21 +54811,21 @@ The following example shows how to query the duration of a pipeline: c:identifier="gst_query_new_accept_caps"> Constructs a new query object for querying if @caps are accepted. + line="2305">Constructs a new query object for querying if @caps are accepted. Free-function: gst_query_unref() a new #GstQuery + line="2313">a new #GstQuery a fixed #GstCaps + line="2307">a fixed #GstCaps @@ -52493,14 +54834,14 @@ Free-function: gst_query_unref() c:identifier="gst_query_new_allocation"> Constructs a new query object for querying the allocation properties. + line="1521">Constructs a new query object for querying the allocation properties. Free-function: gst_query_unref() a new #GstQuery + line="1530">a new #GstQuery @@ -52510,13 +54851,13 @@ Free-function: gst_query_unref() allow-none="1"> the negotiated caps + line="1523">the negotiated caps return a pool + line="1524">return a pool @@ -52526,21 +54867,21 @@ Free-function: gst_query_unref() version="1.16"> Constructs a new query object for querying the bitrate. + line="2630">Constructs a new query object for querying the bitrate. Free-function: gst_query_unref() a new #GstQuery + line="2637">a new #GstQuery Constructs a new query object for querying the buffering status of + line="1024">Constructs a new query object for querying the buffering status of a stream. Free-function: gst_query_unref() @@ -52548,14 +54889,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="1033">a new #GstQuery the default #GstFormat for the new query + line="1026">the default #GstFormat for the new query @@ -52563,7 +54904,7 @@ Free-function: gst_query_unref() Constructs a new query object for querying the caps. + line="2387">Constructs a new query object for querying the caps. The CAPS query should return the allowable caps for a pad in the context of the element's state, its link to other elements, and the devices or files @@ -52587,14 +54928,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="2412">a new #GstQuery a filter + line="2389">a filter @@ -52604,21 +54945,21 @@ Free-function: gst_query_unref() version="1.2"> Constructs a new query object for querying the pipeline-local context. + line="2521">Constructs a new query object for querying the pipeline-local context. Free-function: gst_query_unref() a new #GstQuery + line="2529">a new #GstQuery Context type to query + line="2523">Context type to query @@ -52626,7 +54967,7 @@ Free-function: gst_query_unref() Constructs a new convert query object. Use gst_query_unref() + line="454">Constructs a new convert query object. Use gst_query_unref() when done with it. A convert query is used to ask for a conversion between one format and another. @@ -52635,26 +54976,26 @@ Free-function: gst_query_unref() a #GstQuery + line="466">a #GstQuery the source #GstFormat for the new query + line="456">the source #GstFormat for the new query the value to convert + line="457">the value to convert the target #GstFormat + line="458">the target #GstFormat @@ -52662,7 +55003,7 @@ Free-function: gst_query_unref() Constructs a new custom query object. Use gst_query_unref() + line="653">Constructs a new custom query object. Use gst_query_unref() when done with it. Free-function: gst_query_unref() @@ -52670,14 +55011,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="663">a new #GstQuery the query type + line="655">the query type allow-none="1"> a structure for the query + line="656">a structure for the query @@ -52694,21 +55035,21 @@ Free-function: gst_query_unref() Constructs a new query object for querying the drain state. + line="2500">Constructs a new query object for querying the drain state. Free-function: gst_query_unref() a new #GstQuery + line="2507">a new #GstQuery Constructs a new stream duration query object to query in the given format. + line="296">Constructs a new stream duration query object to query in the given format. Use gst_query_unref() when done with it. A duration query will give the total length of the stream. @@ -52717,14 +55058,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="306">a new #GstQuery the #GstFormat for this duration query + line="298">the #GstFormat for this duration query @@ -52732,7 +55073,7 @@ Free-function: gst_query_unref() Constructs a new query object for querying formats of + line="865">Constructs a new query object for querying formats of the stream. Free-function: gst_query_unref() @@ -52740,14 +55081,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="873">a new #GstQuery Constructs a new latency query object. + line="373">Constructs a new latency query object. Use gst_query_unref() when done with it. A latency query is usually performed by sinks to compensate for additional latency introduced by elements in the pipeline. @@ -52757,14 +55098,14 @@ Free-function: gst_query_unref() a #GstQuery + line="383">a #GstQuery Constructs a new query stream position query object. Use gst_query_unref() + line="219">Constructs a new query stream position query object. Use gst_query_unref() when done with it. A position query is used to query the current position of playback in the streams, in some format. @@ -52773,14 +55114,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="229">a new #GstQuery the default #GstFormat for the new query + line="221">the default #GstFormat for the new query @@ -52789,21 +55130,21 @@ Free-function: gst_query_unref() c:identifier="gst_query_new_scheduling"> Constructs a new query object for querying the scheduling properties. + line="2098">Constructs a new query object for querying the scheduling properties. Free-function: gst_query_unref() a new #GstQuery + line="2105">a new #GstQuery Constructs a new query object for querying seeking properties of + line="748">Constructs a new query object for querying seeking properties of the stream. Free-function: gst_query_unref() @@ -52811,14 +55152,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="757">a new #GstQuery the default #GstFormat for the new query + line="750">the default #GstFormat for the new query @@ -52826,7 +55167,7 @@ Free-function: gst_query_unref() Constructs a new segment query object. Use gst_query_unref() + line="551">Constructs a new segment query object. Use gst_query_unref() when done with it. A segment query is used to discover information about the currently configured segment for playback. @@ -52835,14 +55176,14 @@ Free-function: gst_query_unref() a new #GstQuery + line="561">a new #GstQuery the #GstFormat for the new query + line="553">the #GstFormat for the new query @@ -52852,21 +55193,21 @@ Free-function: gst_query_unref() version="1.22"> Constructs a new query object for querying the stream selection capability. + line="2701">Constructs a new query object for querying the stream selection capability. Free-function: gst_query_unref() a new #GstQuery + line="2708">a new #GstQuery Constructs a new query URI query object. Use gst_query_unref() + line="1355">Constructs a new query URI query object. Use gst_query_unref() when done with it. An URI query is used to query the current URI that is used by the source or sink. @@ -52875,7 +55216,7 @@ Free-function: gst_query_unref() a new #GstQuery + line="1364">a new #GstQuery @@ -52883,7 +55224,7 @@ Free-function: gst_query_unref() c:identifier="gst_query_add_allocation_meta"> Add @api with @params as one of the supported metadata API to @query. + line="1767">Add @api with @params as one of the supported metadata API to @query. @@ -52892,13 +55233,13 @@ Free-function: gst_query_unref() a GST_QUERY_ALLOCATION type query #GstQuery + line="1769">a GST_QUERY_ALLOCATION type query #GstQuery the metadata API + line="1770">the metadata API allow-none="1"> API specific parameters + line="1771">API specific parameters @@ -52916,7 +55257,7 @@ Free-function: gst_query_unref() c:identifier="gst_query_add_allocation_param"> Add @allocator and its @params as a supported memory allocator. + line="1936">Add @allocator and its @params as a supported memory allocator. @@ -52925,7 +55266,7 @@ Free-function: gst_query_unref() a GST_QUERY_ALLOCATION type query #GstQuery + line="1938">a GST_QUERY_ALLOCATION type query #GstQuery allow-none="1"> the memory allocator + line="1939">the memory allocator allow-none="1"> a #GstAllocationParams + line="1940">a #GstAllocationParams @@ -52952,7 +55293,7 @@ Free-function: gst_query_unref() c:identifier="gst_query_add_allocation_pool"> Set the pool parameters in @query. + line="1590">Set the pool parameters in @query. @@ -52961,7 +55302,7 @@ Free-function: gst_query_unref() A valid #GstQuery of type GST_QUERY_ALLOCATION. + line="1592">A valid #GstQuery of type GST_QUERY_ALLOCATION. allow-none="1"> the #GstBufferPool + line="1593">the #GstBufferPool the buffer size + line="1594">the buffer size the min buffers + line="1595">the min buffers the max buffers + line="1596">the max buffers @@ -52997,32 +55338,32 @@ Free-function: gst_query_unref() c:identifier="gst_query_add_buffering_range"> Set the buffering-ranges array field in @query. The current last + line="1247">Set the buffering-ranges array field in @query. The current last start position of the array should be inferior to @start. a #gboolean indicating if the range was added or not. + line="1256">a #gboolean indicating if the range was added or not. a GST_QUERY_BUFFERING type query #GstQuery + line="1249">a GST_QUERY_BUFFERING type query #GstQuery start position of the range + line="1250">start position of the range stop position of the range + line="1251">stop position of the range @@ -53031,7 +55372,7 @@ start position of the array should be inferior to @start. c:identifier="gst_query_add_scheduling_mode"> Add @mode as one of the supported scheduling modes to @query. + line="2173">Add @mode as one of the supported scheduling modes to @query. @@ -53040,13 +55381,13 @@ start position of the array should be inferior to @start. a GST_QUERY_SCHEDULING type query #GstQuery + line="2175">a GST_QUERY_SCHEDULING type query #GstQuery a #GstPadMode + line="2176">a #GstPadMode @@ -53055,27 +55396,27 @@ start position of the array should be inferior to @start. c:identifier="gst_query_find_allocation_meta"> Check if @query has metadata @api set. When this function returns %TRUE, + line="1884">Check if @query has metadata @api set. When this function returns %TRUE, @index will contain the index where the requested API and the parameters can be found. %TRUE when @api is in the list of metadata. + line="1894">%TRUE when @api is in the list of metadata. a GST_QUERY_ALLOCATION type query #GstQuery + line="1886">a GST_QUERY_ALLOCATION type query #GstQuery the metadata API + line="1887">the metadata API allow-none="1"> the index + line="1888">the index @@ -53095,20 +55436,20 @@ can be found. c:identifier="gst_query_get_n_allocation_metas"> Retrieve the number of values currently stored in the + line="1798">Retrieve the number of values currently stored in the meta API array of the query's structure. the metadata API array size as a #guint. + line="1805">the metadata API array size as a #guint. a GST_QUERY_ALLOCATION type query #GstQuery + line="1800">a GST_QUERY_ALLOCATION type query #GstQuery @@ -53117,7 +55458,7 @@ meta API array of the query's structure. c:identifier="gst_query_get_n_allocation_params"> Retrieve the number of values currently stored in the + line="1970">Retrieve the number of values currently stored in the allocator params array of the query's structure. If no memory allocator is specified, the downstream element can handle @@ -53128,14 +55469,14 @@ allocators should be ordered by preference with the preferred one first. the allocator array size as a #guint. + line="1982">the allocator array size as a #guint. a GST_QUERY_ALLOCATION type query #GstQuery + line="1972">a GST_QUERY_ALLOCATION type query #GstQuery @@ -53144,20 +55485,20 @@ allocators should be ordered by preference with the preferred one first. c:identifier="gst_query_get_n_allocation_pools"> Retrieve the number of values currently stored in the + line="1624">Retrieve the number of values currently stored in the pool array of the query's structure. the pool array size as a #guint. + line="1631">the pool array size as a #guint. a GST_QUERY_ALLOCATION type query #GstQuery + line="1626">a GST_QUERY_ALLOCATION type query #GstQuery @@ -53166,20 +55507,20 @@ pool array of the query's structure. c:identifier="gst_query_get_n_buffering_ranges"> Retrieve the number of values currently stored in the + line="1291">Retrieve the number of values currently stored in the buffered-ranges array of the query's structure. the range array size as a #guint. + line="1298">the range array size as a #guint. a GST_QUERY_BUFFERING type query #GstQuery + line="1293">a GST_QUERY_BUFFERING type query #GstQuery @@ -53188,20 +55529,20 @@ buffered-ranges array of the query's structure. c:identifier="gst_query_get_n_scheduling_modes"> Retrieve the number of values currently stored in the + line="2195">Retrieve the number of values currently stored in the scheduling mode array of the query's structure. the scheduling mode array size as a #guint. + line="2202">the scheduling mode array size as a #guint. a GST_QUERY_SCHEDULING type query #GstQuery + line="2197">a GST_QUERY_SCHEDULING type query #GstQuery @@ -53209,12 +55550,12 @@ scheduling mode array of the query's structure. Get the structure of a query. + line="699">Get the structure of a query. the #GstStructure of the query. The + line="705">the #GstStructure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed. @@ -53223,7 +55564,7 @@ scheduling mode array of the query's structure. a #GstQuery + line="701">a #GstQuery @@ -53232,7 +55573,7 @@ scheduling mode array of the query's structure. c:identifier="gst_query_has_scheduling_mode"> Check if @query has scheduling mode set. + line="2244">Check if @query has scheduling mode set. > When checking if upstream supports pull mode, it is usually not > enough to just check for GST_PAD_MODE_PULL with this function, you @@ -53243,20 +55584,20 @@ scheduling mode array of the query's structure. %TRUE when @mode is in the list of scheduling modes. + line="2257">%TRUE when @mode is in the list of scheduling modes. a GST_QUERY_SCHEDULING type query #GstQuery + line="2246">a GST_QUERY_SCHEDULING type query #GstQuery the scheduling mode + line="2247">the scheduling mode @@ -53265,13 +55606,13 @@ scheduling mode array of the query's structure. c:identifier="gst_query_has_scheduling_mode_with_flags"> Check if @query has scheduling mode set and @flags is set in + line="2279">Check if @query has scheduling mode set and @flags is set in query scheduling flags. %TRUE when @mode is in the list of scheduling modes + line="2288">%TRUE when @mode is in the list of scheduling modes and @flags are compatible with query flags. @@ -53279,19 +55620,19 @@ query scheduling flags. a GST_QUERY_SCHEDULING type query #GstQuery + line="2281">a GST_QUERY_SCHEDULING type query #GstQuery the scheduling mode + line="2282">the scheduling mode #GstSchedulingFlags + line="2283">#GstSchedulingFlags @@ -53300,7 +55641,7 @@ query scheduling flags. c:identifier="gst_query_parse_accept_caps"> Get the caps from @query. The caps remains valid as long as @query remains + line="2330">Get the caps from @query. The caps remains valid as long as @query remains valid. @@ -53310,7 +55651,7 @@ valid. The query to parse + line="2332">The query to parse transfer-ownership="none"> A pointer to the caps + line="2333">A pointer to the caps @@ -53328,7 +55669,7 @@ valid. c:identifier="gst_query_parse_accept_caps_result"> Parse the result from @query and store in @result. + line="2369">Parse the result from @query and store in @result. @@ -53337,7 +55678,7 @@ valid. a GST_QUERY_ACCEPT_CAPS type query #GstQuery + line="2371">a GST_QUERY_ACCEPT_CAPS type query #GstQuery nullable="1"> location for the result + line="2372">location for the result @@ -53356,7 +55697,7 @@ valid. c:identifier="gst_query_parse_allocation"> Parse an allocation query, writing the requested caps in @caps and + line="1547">Parse an allocation query, writing the requested caps in @caps and whether a pool is needed in @need_pool, if the respective parameters are non-%NULL. @@ -53370,7 +55711,7 @@ gst_query_parse_nth_allocation_pool(). a #GstQuery + line="1549">a #GstQuery allow-none="1"> The #GstCaps + line="1550">The #GstCaps allow-none="1"> Whether a #GstBufferPool is needed + line="1551">Whether a #GstBufferPool is needed @@ -53403,7 +55744,7 @@ gst_query_parse_nth_allocation_pool(). version="1.16"> Get the results of a bitrate query. See also gst_query_set_bitrate(). + line="2676">Get the results of a bitrate query. See also gst_query_set_bitrate(). @@ -53412,7 +55753,7 @@ gst_query_parse_nth_allocation_pool(). a GST_QUERY_BITRATE type #GstQuery + line="2678">a GST_QUERY_BITRATE type #GstQuery allow-none="1"> The resulting bitrate in bits per second + line="2679">The resulting bitrate in bits per second @@ -53432,7 +55773,7 @@ gst_query_parse_nth_allocation_pool(). c:identifier="gst_query_parse_buffering_percent"> Get the percentage of buffered data. This is a value between 0 and 100. + line="1084">Get the percentage of buffered data. This is a value between 0 and 100. The @busy indicator is %TRUE when the buffering is in progress. @@ -53442,7 +55783,7 @@ The @busy indicator is %TRUE when the buffering is in progress. A valid #GstQuery of type GST_QUERY_BUFFERING. + line="1086">A valid #GstQuery of type GST_QUERY_BUFFERING. allow-none="1"> if buffering is busy, or %NULL + line="1087">if buffering is busy, or %NULL allow-none="1"> a buffering percent, or %NULL + line="1088">a buffering percent, or %NULL @@ -53473,7 +55814,7 @@ The @busy indicator is %TRUE when the buffering is in progress. c:identifier="gst_query_parse_buffering_range"> Parse an available query, writing the format into @format, and + line="1201">Parse an available query, writing the format into @format, and other results into the passed parameters, if the respective parameters are non-%NULL @@ -53484,7 +55825,7 @@ are non-%NULL a GST_QUERY_BUFFERING type query #GstQuery + line="1203">a GST_QUERY_BUFFERING type query #GstQuery allow-none="1"> the format to set for the @segment_start + line="1204">the format to set for the @segment_start and @segment_end values, or %NULL @@ -53507,7 +55848,7 @@ are non-%NULL allow-none="1"> the start to set, or %NULL + line="1206">the start to set, or %NULL allow-none="1"> the stop to set, or %NULL + line="1207">the stop to set, or %NULL allow-none="1"> estimated total amount of download + line="1208">estimated total amount of download time remaining in milliseconds, or %NULL @@ -53539,7 +55880,7 @@ are non-%NULL c:identifier="gst_query_parse_buffering_stats"> Extracts the buffering stats values from @query. + line="1136">Extracts the buffering stats values from @query. @@ -53548,7 +55889,7 @@ are non-%NULL A valid #GstQuery of type GST_QUERY_BUFFERING. + line="1138">A valid #GstQuery of type GST_QUERY_BUFFERING. allow-none="1"> a buffering mode, or %NULL + line="1139">a buffering mode, or %NULL allow-none="1"> the average input rate, or %NULL + line="1140">the average input rate, or %NULL allow-none="1"> the average output rat, or %NULL + line="1141">the average output rat, or %NULL allow-none="1"> amount of buffering time left in + line="1142">amount of buffering time left in milliseconds, or %NULL @@ -53601,7 +55942,7 @@ are non-%NULL Get the filter from the caps @query. The caps remains valid as long as + line="2427">Get the filter from the caps @query. The caps remains valid as long as @query remains valid. @@ -53611,7 +55952,7 @@ are non-%NULL The query to parse + line="2429">The query to parse transfer-ownership="none"> A pointer to the caps filter + line="2430">A pointer to the caps filter @@ -53629,7 +55970,7 @@ are non-%NULL c:identifier="gst_query_parse_caps_result"> Get the caps result from @query. The caps remains valid as long as + line="2466">Get the caps result from @query. The caps remains valid as long as @query remains valid. @@ -53639,7 +55980,7 @@ are non-%NULL The query to parse + line="2468">The query to parse nullable="1"> A pointer to the caps + line="2469">A pointer to the caps @@ -53659,7 +56000,7 @@ are non-%NULL version="1.2"> Get the context from the context @query. The context remains valid as long as + line="2574">Get the context from the context @query. The context remains valid as long as @query remains valid. @@ -53669,7 +56010,7 @@ are non-%NULL The query to parse + line="2576">The query to parse nullable="1"> A pointer to store the #GstContext + line="2577">A pointer to store the #GstContext @@ -53689,19 +56030,19 @@ are non-%NULL version="1.2"> Parse a context type from an existing GST_QUERY_CONTEXT query. + line="2601">Parse a context type from an existing GST_QUERY_CONTEXT query. a #gboolean indicating if the parsing succeeded. + line="2608">a #gboolean indicating if the parsing succeeded. a GST_QUERY_CONTEXT type query + line="2603">a GST_QUERY_CONTEXT type query allow-none="1"> the context type, or %NULL + line="2604">the context type, or %NULL @@ -53720,7 +56061,7 @@ are non-%NULL Parse a convert query answer. Any of @src_format, @src_value, @dest_format, + line="512">Parse a convert query answer. Any of @src_format, @src_value, @dest_format, and @dest_value may be %NULL, in which case that value is omitted. @@ -53730,7 +56071,7 @@ and @dest_value may be %NULL, in which case that value is omitted. a #GstQuery + line="514">a #GstQuery allow-none="1"> the storage for the #GstFormat of the + line="515">the storage for the #GstFormat of the source value, or %NULL @@ -53753,7 +56094,7 @@ and @dest_value may be %NULL, in which case that value is omitted. allow-none="1"> the storage for the source value, or %NULL + line="517">the storage for the source value, or %NULL allow-none="1"> the storage for the #GstFormat of the + line="518">the storage for the #GstFormat of the destination value, or %NULL @@ -53776,7 +56117,7 @@ and @dest_value may be %NULL, in which case that value is omitted. allow-none="1"> the storage for the destination value, + line="520">the storage for the destination value, or %NULL @@ -53785,7 +56126,7 @@ and @dest_value may be %NULL, in which case that value is omitted. Parse a duration query answer. Write the format of the duration into @format, + line="345">Parse a duration query answer. Write the format of the duration into @format, and the value into @duration, if the respective variables are non-%NULL. @@ -53795,7 +56136,7 @@ and the value into @duration, if the respective variables are non-%NULL. a #GstQuery + line="347">a #GstQuery allow-none="1"> the storage for the #GstFormat of the duration + line="348">the storage for the #GstFormat of the duration value, or %NULL. @@ -53818,7 +56159,7 @@ and the value into @duration, if the respective variables are non-%NULL. allow-none="1"> the storage for the total duration, or %NULL. + line="350">the storage for the total duration, or %NULL. @@ -53826,7 +56167,7 @@ and the value into @duration, if the respective variables are non-%NULL. Parse a latency query answer. + line="426">Parse a latency query answer. @@ -53835,7 +56176,7 @@ and the value into @duration, if the respective variables are non-%NULL. a #GstQuery + line="428">a #GstQuery allow-none="1"> storage for live or %NULL + line="429">storage for live or %NULL allow-none="1"> the storage for the min latency or %NULL + line="430">the storage for the min latency or %NULL allow-none="1"> the storage for the max latency or %NULL + line="431">the storage for the max latency or %NULL @@ -53876,7 +56217,7 @@ and the value into @duration, if the respective variables are non-%NULL. Parse the number of formats in the formats @query. + line="964">Parse the number of formats in the formats @query. @@ -53885,7 +56226,7 @@ and the value into @duration, if the respective variables are non-%NULL. a #GstQuery + line="966">a #GstQuery allow-none="1"> the number of formats in this query. + line="967">the number of formats in this query. @@ -53905,26 +56246,26 @@ and the value into @duration, if the respective variables are non-%NULL. c:identifier="gst_query_parse_nth_allocation_meta"> Parse an available query and get the metadata API + line="1823">Parse an available query and get the metadata API at @index of the metadata API array. a #GType of the metadata API at @index. + line="1832">a #GType of the metadata API at @index. a GST_QUERY_ALLOCATION type query #GstQuery + line="1825">a GST_QUERY_ALLOCATION type query #GstQuery position in the metadata API array to read + line="1826">position in the metadata API array to read allow-none="1"> API specific parameters + line="1827">API specific parameters @@ -53944,7 +56285,7 @@ at @index of the metadata API array. c:identifier="gst_query_parse_nth_allocation_param"> Parse an available query and get the allocator and its params + line="1999">Parse an available query and get the allocator and its params at @index of the allocator array. @@ -53954,13 +56295,13 @@ at @index of the allocator array. a GST_QUERY_ALLOCATION type query #GstQuery + line="2001">a GST_QUERY_ALLOCATION type query #GstQuery position in the allocator array to read + line="2002">position in the allocator array to read allow-none="1"> variable to hold the result + line="2003">variable to hold the result allow-none="1"> parameters for the allocator + line="2004">parameters for the allocator @@ -53992,7 +56333,7 @@ at @index of the allocator array. c:identifier="gst_query_parse_nth_allocation_pool"> Get the pool parameters in @query. + line="1648">Get the pool parameters in @query. Unref @pool with gst_object_unref() when it's not needed any more. @@ -54003,13 +56344,13 @@ Unref @pool with gst_object_unref() when it's not needed any more. A valid #GstQuery of type GST_QUERY_ALLOCATION. + line="1650">A valid #GstQuery of type GST_QUERY_ALLOCATION. index to parse + line="1651">index to parse allow-none="1"> the #GstBufferPool + line="1652">the #GstBufferPool allow-none="1"> the buffer size + line="1653">the buffer size allow-none="1"> the min buffers + line="1654">the min buffers allow-none="1"> the max buffers + line="1655">the max buffers @@ -54063,26 +56404,26 @@ Unref @pool with gst_object_unref() when it's not needed any more. c:identifier="gst_query_parse_nth_buffering_range"> Parse an available query and get the start and stop values stored + line="1316">Parse an available query and get the start and stop values stored at the @index of the buffered ranges array. a #gboolean indicating if the parsing succeeded. + line="1326">a #gboolean indicating if the parsing succeeded. a GST_QUERY_BUFFERING type query #GstQuery + line="1318">a GST_QUERY_BUFFERING type query #GstQuery position in the buffered-ranges array to read + line="1319">position in the buffered-ranges array to read allow-none="1"> the start position to set, or %NULL + line="1320">the start position to set, or %NULL allow-none="1"> the stop position to set, or %NULL + line="1321">the stop position to set, or %NULL @@ -54113,7 +56454,7 @@ at the @index of the buffered ranges array. c:identifier="gst_query_parse_nth_format"> Parse the format query and retrieve the @nth format from it into + line="990">Parse the format query and retrieve the @nth format from it into @format. If the list contains less elements than @nth, @format will be set to GST_FORMAT_UNDEFINED. @@ -54124,13 +56465,13 @@ set to GST_FORMAT_UNDEFINED. a #GstQuery + line="992">a #GstQuery the nth format to retrieve. + line="993">the nth format to retrieve. allow-none="1"> a pointer to store the nth format + line="994">a pointer to store the nth format @@ -54150,26 +56491,26 @@ set to GST_FORMAT_UNDEFINED. c:identifier="gst_query_parse_nth_scheduling_mode"> Parse an available query and get the scheduling mode + line="2218">Parse an available query and get the scheduling mode at @index of the scheduling modes array. a #GstPadMode of the scheduling mode at @index. + line="2226">a #GstPadMode of the scheduling mode at @index. a GST_QUERY_SCHEDULING type query #GstQuery + line="2220">a GST_QUERY_SCHEDULING type query #GstQuery position in the scheduling modes array to read + line="2221">position in the scheduling modes array to read @@ -54177,7 +56518,7 @@ at @index of the scheduling modes array. Parse a position query, writing the format into @format, and the position + line="269">Parse a position query, writing the format into @format, and the position into @cur, if the respective parameters are non-%NULL. @@ -54187,7 +56528,7 @@ into @cur, if the respective parameters are non-%NULL. a #GstQuery + line="271">a #GstQuery allow-none="1"> the storage for the #GstFormat of the + line="272">the storage for the #GstFormat of the position values (may be %NULL) @@ -54210,7 +56551,7 @@ into @cur, if the respective parameters are non-%NULL. allow-none="1"> the storage for the current position (may be %NULL) + line="274">the storage for the current position (may be %NULL) @@ -54219,7 +56560,7 @@ into @cur, if the respective parameters are non-%NULL. c:identifier="gst_query_parse_scheduling"> Set the scheduling properties. + line="2148">Set the scheduling properties. @@ -54228,7 +56569,7 @@ into @cur, if the respective parameters are non-%NULL. A valid #GstQuery of type GST_QUERY_SCHEDULING. + line="2150">A valid #GstQuery of type GST_QUERY_SCHEDULING. allow-none="1"> #GstSchedulingFlags + line="2151">#GstSchedulingFlags allow-none="1"> the suggested minimum size of pull requests + line="2152">the suggested minimum size of pull requests allow-none="1"> the suggested maximum size of pull requests: + line="2153">the suggested maximum size of pull requests: allow-none="1"> the suggested alignment of pull requests + line="2154">the suggested alignment of pull requests @@ -54280,7 +56621,7 @@ into @cur, if the respective parameters are non-%NULL. Parse a seeking query, writing the format into @format, and + line="803">Parse a seeking query, writing the format into @format, and other results into the passed parameters, if the respective parameters are non-%NULL @@ -54291,7 +56632,7 @@ are non-%NULL a GST_QUERY_SEEKING type query #GstQuery + line="805">a GST_QUERY_SEEKING type query #GstQuery allow-none="1"> the format to set for the @segment_start + line="806">the format to set for the @segment_start and @segment_end values, or %NULL @@ -54314,7 +56655,7 @@ are non-%NULL allow-none="1"> the seekable flag to set, or %NULL + line="808">the seekable flag to set, or %NULL allow-none="1"> the segment_start to set, or %NULL + line="809">the segment_start to set, or %NULL allow-none="1"> the segment_end to set, or %NULL + line="810">the segment_end to set, or %NULL @@ -54344,7 +56685,7 @@ are non-%NULL Parse a segment query answer. Any of @rate, @format, @start_value, and + line="616">Parse a segment query answer. Any of @rate, @format, @start_value, and @stop_value may be %NULL, which will cause this value to be omitted. See gst_query_set_segment() for an explanation of the function arguments. @@ -54356,7 +56697,7 @@ See gst_query_set_segment() for an explanation of the function arguments. a #GstQuery + line="618">a #GstQuery allow-none="1"> the storage for the rate of the segment, or %NULL + line="619">the storage for the rate of the segment, or %NULL allow-none="1"> the storage for the #GstFormat of the values, + line="620">the storage for the #GstFormat of the values, or %NULL @@ -54390,7 +56731,7 @@ See gst_query_set_segment() for an explanation of the function arguments. allow-none="1"> the storage for the start value, or %NULL + line="622">the storage for the start value, or %NULL allow-none="1"> the storage for the stop value, or %NULL + line="623">the storage for the stop value, or %NULL @@ -54411,7 +56752,7 @@ See gst_query_set_segment() for an explanation of the function arguments. version="1.22"> Get the results of a selectable query. See also gst_query_set_selectable(). + line="2746">Get the results of a selectable query. See also gst_query_set_selectable(). @@ -54420,7 +56761,7 @@ See gst_query_set_segment() for an explanation of the function arguments. a GST_QUERY_SELECTABLE type #GstQuery + line="2748">a GST_QUERY_SELECTABLE type #GstQuery allow-none="1"> The resulting stream selection capability + line="2749">The resulting stream selection capability @@ -54439,7 +56780,7 @@ See gst_query_set_segment() for an explanation of the function arguments. Parse an URI query, writing the URI into @uri as a newly + line="1399">Parse an URI query, writing the URI into @uri as a newly allocated string, if the respective parameters are non-%NULL. Free the string with g_free() after usage. @@ -54450,7 +56791,7 @@ Free the string with g_free() after usage. a #GstQuery + line="1401">a #GstQuery allow-none="1"> the storage for the current URI + line="1402">the storage for the current URI (may be %NULL) @@ -54473,7 +56814,7 @@ Free the string with g_free() after usage. version="1.2"> Parse an URI query, writing the URI into @uri as a newly + line="1442">Parse an URI query, writing the URI into @uri as a newly allocated string, if the respective parameters are non-%NULL. Free the string with g_free() after usage. @@ -54484,7 +56825,7 @@ Free the string with g_free() after usage. a #GstQuery + line="1444">a #GstQuery allow-none="1"> the storage for the redirect URI + line="1445">the storage for the redirect URI (may be %NULL) @@ -54507,7 +56848,7 @@ Free the string with g_free() after usage. version="1.4"> Parse an URI query, and set @permanent to %TRUE if there is a redirection + line="1492">Parse an URI query, and set @permanent to %TRUE if there is a redirection and it should be considered permanent. If a redirection is permanent, applications should update their internal storage of the URI, otherwise they should make all future requests to the original URI. @@ -54519,7 +56860,7 @@ they should make all future requests to the original URI. a #GstQuery + line="1494">a #GstQuery allow-none="1"> if the URI redirection is permanent + line="1495">if the URI redirection is permanent (may be %NULL) @@ -54540,7 +56881,7 @@ they should make all future requests to the original URI. c:identifier="gst_query_remove_nth_allocation_meta"> Remove the metadata API at @index of the metadata API array. + line="1859">Remove the metadata API at @index of the metadata API array. @@ -54549,13 +56890,13 @@ they should make all future requests to the original URI. a GST_QUERY_ALLOCATION type query #GstQuery + line="1861">a GST_QUERY_ALLOCATION type query #GstQuery position in the metadata API array to remove + line="1862">position in the metadata API array to remove @@ -54565,7 +56906,7 @@ they should make all future requests to the original URI. version="1.2"> Remove the allocation param at @index of the allocation param array. + line="2071">Remove the allocation param at @index of the allocation param array. @@ -54574,13 +56915,13 @@ they should make all future requests to the original URI. a GST_QUERY_ALLOCATION type query #GstQuery + line="2073">a GST_QUERY_ALLOCATION type query #GstQuery position in the allocation param array to remove + line="2074">position in the allocation param array to remove @@ -54590,7 +56931,7 @@ they should make all future requests to the original URI. version="1.2"> Remove the allocation pool at @index of the allocation pool array. + line="1727">Remove the allocation pool at @index of the allocation pool array. @@ -54599,13 +56940,13 @@ they should make all future requests to the original URI. a GST_QUERY_ALLOCATION type query #GstQuery + line="1729">a GST_QUERY_ALLOCATION type query #GstQuery position in the allocation pool array to remove + line="1730">position in the allocation pool array to remove @@ -54614,7 +56955,7 @@ they should make all future requests to the original URI. c:identifier="gst_query_set_accept_caps_result"> Set @result as the result for the @query. + line="2350">Set @result as the result for the @query. @@ -54623,13 +56964,13 @@ they should make all future requests to the original URI. a GST_QUERY_ACCEPT_CAPS type query #GstQuery + line="2352">a GST_QUERY_ACCEPT_CAPS type query #GstQuery the result to set + line="2353">the result to set @@ -54639,7 +56980,7 @@ they should make all future requests to the original URI. version="1.16"> Set the results of a bitrate query. The nominal bitrate is the average + line="2653">Set the results of a bitrate query. The nominal bitrate is the average bitrate expected over the length of the stream as advertised in file headers (or similar). @@ -54650,13 +56991,13 @@ headers (or similar). a GST_QUERY_BITRATE type #GstQuery + line="2655">a GST_QUERY_BITRATE type #GstQuery the nominal bitrate in bits per second + line="2656">the nominal bitrate in bits per second @@ -54665,7 +57006,7 @@ headers (or similar). c:identifier="gst_query_set_buffering_percent"> Set the percentage of buffered data. This is a value between 0 and 100. + line="1060">Set the percentage of buffered data. This is a value between 0 and 100. The @busy indicator is %TRUE when the buffering is in progress. @@ -54675,19 +57016,19 @@ The @busy indicator is %TRUE when the buffering is in progress. A valid #GstQuery of type GST_QUERY_BUFFERING. + line="1062">A valid #GstQuery of type GST_QUERY_BUFFERING. if buffering is busy + line="1063">if buffering is busy a buffering percent + line="1064">a buffering percent @@ -54696,7 +57037,7 @@ The @busy indicator is %TRUE when the buffering is in progress. c:identifier="gst_query_set_buffering_range"> Set the available query result fields in @query. + line="1173">Set the available query result fields in @query. @@ -54705,31 +57046,31 @@ The @busy indicator is %TRUE when the buffering is in progress. a #GstQuery + line="1175">a #GstQuery the format to set for the @start and @stop values + line="1176">the format to set for the @start and @stop values the start to set + line="1177">the start to set the stop to set + line="1178">the stop to set estimated total amount of download time remaining in + line="1179">estimated total amount of download time remaining in milliseconds @@ -54739,7 +57080,7 @@ The @busy indicator is %TRUE when the buffering is in progress. c:identifier="gst_query_set_buffering_stats"> Configures the buffering stats values in @query. + line="1109">Configures the buffering stats values in @query. @@ -54748,31 +57089,31 @@ The @busy indicator is %TRUE when the buffering is in progress. A valid #GstQuery of type GST_QUERY_BUFFERING. + line="1111">A valid #GstQuery of type GST_QUERY_BUFFERING. a buffering mode + line="1112">a buffering mode the average input rate + line="1113">the average input rate the average output rate + line="1114">the average output rate amount of buffering time left in milliseconds + line="1115">amount of buffering time left in milliseconds @@ -54780,7 +57121,7 @@ The @busy indicator is %TRUE when the buffering is in progress. Set the @caps result in @query. + line="2447">Set the @caps result in @query. @@ -54789,7 +57130,7 @@ The @busy indicator is %TRUE when the buffering is in progress. The query to use + line="2449">The query to use allow-none="1"> A pointer to the caps + line="2450">A pointer to the caps @@ -54808,7 +57149,7 @@ The @busy indicator is %TRUE when the buffering is in progress. version="1.2"> Answer a context query by setting the requested context. + line="2548">Answer a context query by setting the requested context. @@ -54817,7 +57158,7 @@ The @busy indicator is %TRUE when the buffering is in progress. a #GstQuery with query type GST_QUERY_CONTEXT + line="2550">a #GstQuery with query type GST_QUERY_CONTEXT allow-none="1"> the requested #GstContext + line="2551">the requested #GstContext @@ -54834,7 +57175,7 @@ The @busy indicator is %TRUE when the buffering is in progress. Answer a convert query by setting the requested values. + line="486">Answer a convert query by setting the requested values. @@ -54843,31 +57184,31 @@ The @busy indicator is %TRUE when the buffering is in progress. a #GstQuery + line="488">a #GstQuery the source #GstFormat + line="489">the source #GstFormat the source value + line="490">the source value the destination #GstFormat + line="491">the destination #GstFormat the destination value + line="492">the destination value @@ -54875,7 +57216,7 @@ The @busy indicator is %TRUE when the buffering is in progress. Answer a duration query by setting the requested value in the given format. + line="323">Answer a duration query by setting the requested value in the given format. @@ -54884,19 +57225,19 @@ The @busy indicator is %TRUE when the buffering is in progress. a #GstQuery + line="325">a #GstQuery the #GstFormat for the duration + line="326">the #GstFormat for the duration the duration of the stream + line="327">the duration of the stream @@ -54906,7 +57247,7 @@ The @busy indicator is %TRUE when the buffering is in progress. introspectable="0"> Set the formats query result fields in @query. The number of formats passed + line="898">Set the formats query result fields in @query. The number of formats passed must be equal to @n_formats. @@ -54916,19 +57257,19 @@ must be equal to @n_formats. a #GstQuery + line="900">a #GstQuery the number of formats to set. + line="901">the number of formats to set. A number of @GstFormats equal to @n_formats. + line="902">A number of @GstFormats equal to @n_formats. @@ -54936,7 +57277,7 @@ must be equal to @n_formats. Set the formats query result fields in @query. The number of formats passed + line="933">Set the formats query result fields in @query. The number of formats passed in the @formats array must be equal to @n_formats. @@ -54946,19 +57287,19 @@ in the @formats array must be equal to @n_formats. a #GstQuery + line="935">a #GstQuery the number of formats to set. + line="936">the number of formats to set. an array containing @n_formats + line="937">an array containing @n_formats @GstFormat values. @@ -54969,7 +57310,7 @@ in the @formats array must be equal to @n_formats. Answer a latency query by setting the requested values in the given format. + line="401">Answer a latency query by setting the requested values in the given format. @@ -54978,25 +57319,25 @@ in the @formats array must be equal to @n_formats. a #GstQuery + line="403">a #GstQuery if there is a live element upstream + line="404">if there is a live element upstream the minimal latency of the upstream elements + line="405">the minimal latency of the upstream elements the maximal latency of the upstream elements + line="406">the maximal latency of the upstream elements @@ -55005,7 +57346,7 @@ in the @formats array must be equal to @n_formats. c:identifier="gst_query_set_nth_allocation_param"> Parse an available query and get the allocator and its params + line="2033">Parse an available query and get the allocator and its params at @index of the allocator array. @@ -55015,13 +57356,13 @@ at @index of the allocator array. a GST_QUERY_ALLOCATION type query #GstQuery + line="2035">a GST_QUERY_ALLOCATION type query #GstQuery position in the allocator array to set + line="2036">position in the allocator array to set allow-none="1"> new allocator to set + line="2037">new allocator to set allow-none="1"> parameters for the allocator + line="2038">parameters for the allocator @@ -55048,7 +57389,7 @@ at @index of the allocator array. c:identifier="gst_query_set_nth_allocation_pool"> Set the pool parameters in @query. + line="1690">Set the pool parameters in @query. @@ -55057,13 +57398,13 @@ at @index of the allocator array. A valid #GstQuery of type GST_QUERY_ALLOCATION. + line="1693">A valid #GstQuery of type GST_QUERY_ALLOCATION. index to modify + line="1692">index to modify allow-none="1"> the #GstBufferPool + line="1694">the #GstBufferPool the buffer size + line="1695">the buffer size the min buffers + line="1696">the min buffers the max buffers + line="1697">the max buffers @@ -55098,7 +57439,7 @@ at @index of the allocator array. Answer a position query by setting the requested value in the given format. + line="246">Answer a position query by setting the requested value in the given format. @@ -55107,19 +57448,19 @@ at @index of the allocator array. a #GstQuery with query type GST_QUERY_POSITION + line="248">a #GstQuery with query type GST_QUERY_POSITION the requested #GstFormat + line="249">the requested #GstFormat the position to set + line="250">the position to set @@ -55127,7 +57468,7 @@ at @index of the allocator array. Set the scheduling properties. + line="2122">Set the scheduling properties. @@ -55136,31 +57477,31 @@ at @index of the allocator array. A valid #GstQuery of type GST_QUERY_SCHEDULING. + line="2124">A valid #GstQuery of type GST_QUERY_SCHEDULING. #GstSchedulingFlags + line="2125">#GstSchedulingFlags the suggested minimum size of pull requests + line="2126">the suggested minimum size of pull requests the suggested maximum size of pull requests + line="2127">the suggested maximum size of pull requests the suggested alignment of pull requests + line="2128">the suggested alignment of pull requests @@ -55168,7 +57509,7 @@ at @index of the allocator array. Set the seeking query result fields in @query. + line="776">Set the seeking query result fields in @query. @@ -55177,31 +57518,31 @@ at @index of the allocator array. a #GstQuery + line="778">a #GstQuery the format to set for the @segment_start and @segment_end values + line="779">the format to set for the @segment_start and @segment_end values the seekable flag to set + line="780">the seekable flag to set the segment_start to set + line="781">the segment_start to set the segment_end to set + line="782">the segment_end to set @@ -55209,7 +57550,7 @@ at @index of the allocator array. Answer a segment query by setting the requested values. The normal + line="580">Answer a segment query by setting the requested values. The normal playback segment of a pipeline is 0 to duration at the default rate of 1.0. If a seek was performed on the pipeline to play a different segment, this query will return the range specified in the last seek. @@ -55228,31 +57569,31 @@ negative rates, playback will actually happen from @stop_value to a #GstQuery + line="582">a #GstQuery the rate of the segment + line="583">the rate of the segment the #GstFormat of the segment values (@start_value and @stop_value) + line="584">the #GstFormat of the segment values (@start_value and @stop_value) the start value + line="585">the start value the stop value + line="586">the stop value @@ -55262,7 +57603,7 @@ negative rates, playback will actually happen from @stop_value to version="1.22"> Set the results of a selectable query. If the element answering the query can + line="2724">Set the results of a selectable query. If the element answering the query can handle stream selection, @selectable should be set to %TRUE. @@ -55272,13 +57613,13 @@ handle stream selection, @selectable should be set to %TRUE. a GST_QUERY_SELECTABLE type #GstQuery + line="2726">a GST_QUERY_SELECTABLE type #GstQuery Whether the element can handle stream selection. + line="2727">Whether the element can handle stream selection. @@ -55286,7 +57627,7 @@ handle stream selection, @selectable should be set to %TRUE. Answer a URI query by setting the requested URI. + line="1380">Answer a URI query by setting the requested URI. @@ -55295,7 +57636,7 @@ handle stream selection, @selectable should be set to %TRUE. a #GstQuery with query type GST_QUERY_URI + line="1382">a #GstQuery with query type GST_QUERY_URI allow-none="1"> the URI to set + line="1383">the URI to set @@ -55314,7 +57655,7 @@ handle stream selection, @selectable should be set to %TRUE. version="1.2"> Answer a URI query by setting the requested URI redirection. + line="1421">Answer a URI query by setting the requested URI redirection. @@ -55323,7 +57664,7 @@ handle stream selection, @selectable should be set to %TRUE. a #GstQuery with query type GST_QUERY_URI + line="1423">a #GstQuery with query type GST_QUERY_URI allow-none="1"> the URI to set + line="1424">the URI to set @@ -55342,7 +57683,7 @@ handle stream selection, @selectable should be set to %TRUE. version="1.4"> Answer a URI query by setting the requested URI redirection + line="1469">Answer a URI query by setting the requested URI redirection to permanent or not. @@ -55352,13 +57693,13 @@ to permanent or not. a #GstQuery with query type %GST_QUERY_URI + line="1471">a #GstQuery with query type %GST_QUERY_URI whether the redirect is permanent or not + line="1472">whether the redirect is permanent or not @@ -55367,13 +57708,13 @@ to permanent or not. c:identifier="gst_query_writable_structure"> Get the structure of a query. This method should be called with a writable + line="717">Get the structure of a query. This method should be called with a writable @query so that the returned structure is guaranteed to be writable. the #GstStructure of the query. The structure is + line="724">the #GstStructure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed. @@ -55382,7 +57723,7 @@ to permanent or not. a #GstQuery + line="719">a #GstQuery @@ -55589,19 +57930,19 @@ to permanent or not. Gets the #GstQueryTypeFlags associated with @type. + line="167">Gets the #GstQueryTypeFlags associated with @type. a #GstQueryTypeFlags. + line="173">a #GstQueryTypeFlags. a #GstQueryType + line="169">a #GstQueryType @@ -55609,19 +57950,19 @@ to permanent or not. Get a printable name for the given query type. Do not modify or free. + line="127">Get a printable name for the given query type. Do not modify or free. a reference to the static name of the query. + line="133">a reference to the static name of the query. the query type + line="129">the query type @@ -55629,19 +57970,19 @@ to permanent or not. Get the unique quark for the given query type. + line="147">Get the unique quark for the given query type. the quark associated with the query type + line="153">the quark associated with the query type the query type + line="149">the query type @@ -56173,8 +58514,11 @@ references would be * `timestamp/x-ptp, version=IEEE1588-2008, domain=1`: for timestamps based on a given PTP clock. * `timestamp/x-unix`: for timestamps based on the UNIX epoch according to - the local clock. - + the local clock. + +Since 1.24 it can be serialized using gst_meta_serialize() and +gst_meta_deserialize(). + Gets the global #GstMetaInfo describing the #GstReferenceTimestampMeta meta. - + line="2929">Gets the global #GstMetaInfo describing the #GstReferenceTimestampMeta meta. + The #GstMetaInfo + line="2934">The #GstMetaInfo @@ -56286,17 +58630,17 @@ removed at the end of initialization. c:identifier="gst_registry_fork_is_enabled"> By default GStreamer will perform scanning and rebuilding of the + line="1957">By default GStreamer will perform scanning and rebuilding of the registry file using a helper child process. Applications might want to disable this behaviour with the gst_registry_fork_set_enabled() function, in which case new plugins are scanned (and loaded) into the application process. - + %TRUE if GStreamer will use the child helper process when + line="1967">%TRUE if GStreamer will use the child helper process when rebuilding the registry. @@ -56305,10 +58649,10 @@ rebuilding the registry. c:identifier="gst_registry_fork_set_enabled"> Applications might want to disable/enable spawning of a child helper process + line="1976">Applications might want to disable/enable spawning of a child helper process when rebuilding the registry. See gst_registry_fork_is_enabled() for more information. - + @@ -56316,7 +58660,7 @@ information. whether rebuilding the registry can use a temporary child helper process. + line="1978">whether rebuilding the registry can use a temporary child helper process. @@ -56401,14 +58745,14 @@ MT safe. c:identifier="gst_registry_check_feature_version"> Checks whether a plugin feature by the given name exists in + line="1510">Checks whether a plugin feature by the given name exists in @registry and whether its version is at least the version required. %TRUE if the feature could be found and the version is + line="1522">%TRUE if the feature could be found and the version is the same as the required version or newer, and %FALSE otherwise. @@ -56416,31 +58760,31 @@ the same as the required version or newer, and %FALSE otherwise. a #GstRegistry + line="1512">a #GstRegistry the name of the feature (e.g. "oggdemux") + line="1513">the name of the feature (e.g. "oggdemux") the minimum major version number + line="1514">the minimum major version number the minimum minor version number + line="1515">the minimum minor version number the minimum micro version number + line="1516">the minimum micro version number @@ -56600,12 +58944,12 @@ MT safe. c:identifier="gst_registry_get_feature_list_by_plugin"> Retrieves a #GList of features of the plugin with name @name. + line="1454">Retrieves a #GList of features of the plugin with name @name. a #GList of + line="1461">a #GList of #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. @@ -56615,13 +58959,13 @@ MT safe. a #GstRegistry. + line="1456">a #GstRegistry. a plugin name. + line="1457">a plugin name. @@ -56630,20 +58974,20 @@ MT safe. c:identifier="gst_registry_get_feature_list_cookie"> Returns the registry's feature list cookie. This changes + line="2045">Returns the registry's feature list cookie. This changes every time a feature is added or removed from the registry. the feature list cookie. + line="2052">the feature list cookie. the registry + line="2047">the registry @@ -56838,26 +59182,26 @@ MT safe. Scan the given path for plugins to add to the registry. The syntax of the + line="1418">Scan the given path for plugins to add to the registry. The syntax of the path is specific to the registry. %TRUE if registry changed + line="1426">%TRUE if registry changed the registry to add found plugins to + line="1420">the registry to add found plugins to the path to scan + line="1421">the path to scan @@ -57112,12 +59456,12 @@ both reading and writing, or either (but unspecified which). introspectable="0"> printf format type used to debug GStreamer segments. You can use this in + line="295">printf format type used to debug GStreamer segments. You can use this in combination with GStreamer's debug logging system as well as the functions gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() to pretty-print #GstSegment structures. This can only be used on pointers to GstSegment structures. - + printf format type used to debug GStreamer signed time value pointers. You + line="319">printf format type used to debug GStreamer signed time value pointers. You can use this in combination with GStreamer's debug logging system as well as the functions gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() to pretty-print signed time (pointers to #GstClockTimeDiff or #gint64). - + Formats @t for the #GST_STIME_FORMAT format string. Note: @t will be + line="268">Formats @t for the #GST_STIME_FORMAT format string. Note: @t will be evaluated more than once. - + a #GstClockTimeDiff or #gint64 + line="270">a #GstClockTimeDiff or #gint64 @@ -57500,7 +59844,7 @@ evaluated more than once. introspectable="0"> A string that can be used in printf-like format strings to display a signed + line="252">A string that can be used in printf-like format strings to display a signed #GstClockTimeDiff or #gint64 value in `h:m:s` format. Use GST_TIME_ARGS() to construct the matching arguments. @@ -57509,7 +59853,7 @@ Example: ``` C printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts)); ``` - + @@ -57585,7 +59929,7 @@ printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts)); - + @@ -57594,7 +59938,7 @@ printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts)); - + @@ -57627,17 +59971,17 @@ guint32 fourcc = GST_STR_FOURCC ("MJPG"); introspectable="0"> Macro to use when a string must not be %NULL, but may be %NULL. If the string + line="231">Macro to use when a string must not be %NULL, but may be %NULL. If the string is %NULL, "(NULL)" is printed instead. In GStreamer printf string arguments may not be %NULL, because on some platforms (ie Solaris) the libc crashes in that case. This includes debugging strings. - + The string to check. + line="233">The string to check. @@ -58022,7 +60366,7 @@ and @info must not have a parent set already. c:type="GstSearchMode"> The different search modes. + line="1171">The different search modes. glib:name="GST_SEARCH_MODE_EXACT"> Only search for exact matches. + line="1173">Only search for exact matches. glib:name="GST_SEARCH_MODE_BEFORE"> Search for an exact match or the element just before. + line="1174">Search for an exact match or the element just before. glib:name="GST_SEARCH_MODE_AFTER"> Search for an exact match or the element just after. + line="1175">Search for an exact match or the element just after. c:symbol-prefix="segment"> This helper structure holds the relevant values for tracking the region of + line="30">This helper structure holds the relevant values for tracking the region of interest in a media file, called a segment. The structure can be used for two purposes: @@ -58470,7 +60814,7 @@ info to stream time (which is always between 0 and the duration of the stream).< Allocate a new #GstSegment structure and initialize it using + line="128">Allocate a new #GstSegment structure and initialize it using gst_segment_init(). Free-function: gst_segment_free @@ -58478,14 +60822,14 @@ Free-function: gst_segment_free a new #GstSegment, free with gst_segment_free(). + line="136">a new #GstSegment, free with gst_segment_free(). Clip the given @start and @stop values to the segment boundaries given + line="869">Clip the given @start and @stop values to the segment boundaries given in @segment. @start and @stop are compared and clipped to @segment start and stop values. @@ -58502,7 +60846,7 @@ segment. Depending on the use case, this may or may not be what you want. %TRUE if the given @start and @stop times fall partially or + line="892">%TRUE if the given @start and @stop times fall partially or completely in @segment, %FALSE if the values are completely outside of the segment. @@ -58511,25 +60855,25 @@ segment. Depending on the use case, this may or may not be what you want. a #GstSegment structure. + line="871">a #GstSegment structure. the format of the segment. + line="872">the format of the segment. the start position in the segment + line="873">the start position in the segment the stop position in the segment + line="874">the stop position in the segment allow-none="1"> the clipped start position in the segment + line="875">the clipped start position in the segment allow-none="1"> the clipped stop position in the segment + line="876">the clipped stop position in the segment @@ -58559,21 +60903,21 @@ segment. Depending on the use case, this may or may not be what you want. Create a copy of given @segment. + line="91">Create a copy of given @segment. Free-function: gst_segment_free a new #GstSegment, free with gst_segment_free(). + line="99">a new #GstSegment, free with gst_segment_free(). a #GstSegment + line="93">a #GstSegment @@ -58581,7 +60925,7 @@ Free-function: gst_segment_free Copy the contents of @src into @dest. + line="112">Copy the contents of @src into @dest. @@ -58590,13 +60934,13 @@ Free-function: gst_segment_free a #GstSegment + line="114">a #GstSegment a #GstSegment + line="115">a #GstSegment @@ -58604,7 +60948,7 @@ Free-function: gst_segment_free Update the segment structure with the field values of a seek event (see + line="190">Update the segment structure with the field values of a seek event (see gst_event_new_seek()). After calling this method, the segment field position and time will @@ -58635,56 +60979,56 @@ has been changed but not the playback position. %TRUE if the seek could be performed. + line="230">%TRUE if the seek could be performed. a #GstSegment structure. + line="192">a #GstSegment structure. the rate of the segment. + line="193">the rate of the segment. the format of the segment. + line="194">the format of the segment. the segment flags for the segment + line="195">the segment flags for the segment the seek method + line="196">the seek method the seek start value + line="197">the seek start value the seek method + line="198">the seek method the seek stop value + line="199">the seek stop value allow-none="1"> boolean holding whether position was updated. + line="200">boolean holding whether position was updated. @@ -58703,7 +61047,7 @@ has been changed but not the playback position. Free the allocated segment @segment. + line="149">Free the allocated segment @segment. @@ -58712,7 +61056,7 @@ has been changed but not the playback position. a #GstSegment + line="151">a #GstSegment @@ -58720,7 +61064,7 @@ has been changed but not the playback position. The start/position fields are set to 0 and the stop/duration + line="161">The start/position fields are set to 0 and the stop/duration fields are set to -1 (unknown). The default rate of 1.0 and no flags are set. @@ -58733,13 +61077,13 @@ Initialize @segment to its default values. a #GstSegment structure. + line="163">a #GstSegment structure. the format of the segment. + line="164">the format of the segment. @@ -58749,26 +61093,26 @@ Initialize @segment to its default values. version="1.6"> Checks for two segments being equal. Equality here is defined + line="1217">Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values. %TRUE if the segments are equal, %FALSE otherwise. + line="1227">%TRUE if the segments are equal, %FALSE otherwise. a #GstSegment structure. + line="1219">a #GstSegment structure. a #GstSegment structure. + line="1220">a #GstSegment structure. @@ -58778,13 +61122,13 @@ as perfect equality, including floating point values. version="1.2.3"> Adjust the values in @segment so that @offset is applied to all + line="1168">Adjust the values in @segment so that @offset is applied to all future running-time calculations. %TRUE if the segment could be updated successfully. If %FALSE is + line="1179">%TRUE if the segment could be updated successfully. If %FALSE is returned, @offset is not in @segment. @@ -58792,19 +61136,19 @@ returned, @offset is not in @segment. a #GstSegment structure. + line="1170">a #GstSegment structure. the format of the segment. + line="1171">the format of the segment. the offset to apply in the segment + line="1172">the offset to apply in the segment @@ -58814,13 +61158,13 @@ returned, @offset is not in @segment. version="1.8"> Convert @running_time into a position in the segment so that + line="938">Convert @running_time into a position in the segment so that gst_segment_to_running_time() with that position returns @running_time. the position in the segment for @running_time. This function returns + line="947">the position in the segment for @running_time. This function returns -1 when @running_time is -1 or when it is not inside @segment. @@ -58828,19 +61172,19 @@ gst_segment_to_running_time() with that position returns @running_time. a #GstSegment structure. + line="940">a #GstSegment structure. the format of the segment. + line="941">the format of the segment. the running_time in the segment + line="942">the running_time in the segment @@ -58850,7 +61194,7 @@ gst_segment_to_running_time() with that position returns @running_time. version="1.8"> Translate @running_time to the segment position using the currently configured + line="986">Translate @running_time to the segment position using the currently configured segment. Compared to gst_segment_position_from_running_time() this function can return negative segment position. @@ -58870,26 +61214,26 @@ position. a 1 or -1 on success, 0 on failure. + line="1010">a 1 or -1 on success, 0 on failure. a #GstSegment structure. + line="988">a #GstSegment structure. the format of the segment. + line="989">the format of the segment. the running-time + line="990">the running-time transfer-ownership="full"> the resulting position in the segment + line="991">the resulting position in the segment @@ -58908,13 +61252,13 @@ position. version="1.8"> Convert @stream_time into a position in the segment so that + line="660">Convert @stream_time into a position in the segment so that gst_segment_to_stream_time() with that position returns @stream_time. the position in the segment for @stream_time. This function returns + line="669">the position in the segment for @stream_time. This function returns -1 when @stream_time is -1 or when it is not inside @segment. @@ -58922,19 +61266,19 @@ gst_segment_to_stream_time() with that position returns @stream_time. a #GstSegment structure. + line="662">a #GstSegment structure. the format of the segment. + line="663">the format of the segment. the stream_time in the segment + line="664">the stream_time in the segment @@ -58944,7 +61288,7 @@ gst_segment_to_stream_time() with that position returns @stream_time. version="1.8"> Translate @stream_time to the segment position using the currently configured + line="549">Translate @stream_time to the segment position using the currently configured segment. Compared to gst_segment_position_from_stream_time() this function can return negative segment position. @@ -58963,26 +61307,26 @@ to get the real negative segment position. a 1 or -1 on success, 0 on failure. + line="572">a 1 or -1 on success, 0 on failure. a #GstSegment structure. + line="551">a #GstSegment structure. the format of the segment. + line="552">the format of the segment. the stream-time + line="553">the stream-time transfer-ownership="full"> the resulting position in the segment + line="554">the resulting position in the segment @@ -59000,13 +61344,13 @@ to get the real negative segment position. c:identifier="gst_segment_set_running_time"> Adjust the start/stop and base values of @segment such that the next valid + line="1122">Adjust the start/stop and base values of @segment such that the next valid buffer will be one with @running_time. %TRUE if the segment could be updated successfully. If %FALSE is + line="1131">%TRUE if the segment could be updated successfully. If %FALSE is returned, @running_time is -1 or not in @segment. @@ -59014,19 +61358,19 @@ returned, @running_time is -1 or not in @segment. a #GstSegment structure. + line="1124">a #GstSegment structure. the format of the segment. + line="1125">the format of the segment. the running_time in the segment + line="1126">the running_time in the segment @@ -59036,14 +61380,14 @@ returned, @running_time is -1 or not in @segment. deprecated="1"> Convert @running_time into a position in the segment so that + line="1099">Convert @running_time into a position in the segment so that gst_segment_to_running_time() with that position returns @running_time. Use gst_segment_position_from_running_time() instead. the position in the segment for @running_time. This function returns + line="1108">the position in the segment for @running_time. This function returns -1 when @running_time is -1 or when it is not inside @segment. @@ -59051,19 +61395,19 @@ gst_segment_to_running_time() with that position returns @running_time. a #GstSegment structure. + line="1101">a #GstSegment structure. the format of the segment. + line="1102">the format of the segment. the running_time in the segment + line="1103">the running_time in the segment @@ -59072,7 +61416,7 @@ gst_segment_to_running_time() with that position returns @running_time. c:identifier="gst_segment_to_running_time"> Translate @position to the total running time using the currently configured + line="821">Translate @position to the total running time using the currently configured segment. Position is a value between @segment start and stop time. This function is typically used by elements that need to synchronize to the @@ -59085,7 +61429,7 @@ This function returns -1 if the position is outside of @segment start and stop.< the position as the total running time or -1 when an invalid position + line="837">the position as the total running time or -1 when an invalid position was given. @@ -59093,19 +61437,19 @@ was given. a #GstSegment structure. + line="823">a #GstSegment structure. the format of the segment. + line="824">the format of the segment. the position in the segment + line="825">the position in the segment @@ -59115,7 +61459,7 @@ was given. version="1.6"> Translate @position to the total running time using the currently configured + line="708">Translate @position to the total running time using the currently configured segment. Compared to gst_segment_to_running_time() this function can return negative running-time. @@ -59134,26 +61478,26 @@ to get the real negative running time. a 1 or -1 on success, 0 on failure. + line="731">a 1 or -1 on success, 0 on failure. a #GstSegment structure. + line="710">a #GstSegment structure. the format of the segment. + line="711">the format of the segment. the position in the segment + line="712">the position in the segment allow-none="1"> result running-time + line="713">result running-time @@ -59174,7 +61518,7 @@ to get the real negative running time. version="1.8"> Translate @position to stream time using the currently configured + line="499">Translate @position to stream time using the currently configured segment. The @position value must be between @segment start and stop value. @@ -59188,7 +61532,7 @@ media stream. the position in stream_time or -1 when an invalid position + line="516">the position in stream_time or -1 when an invalid position was given. @@ -59196,19 +61540,19 @@ was given. a #GstSegment structure. + line="501">a #GstSegment structure. the format of the segment. + line="502">the format of the segment. the position in the segment + line="503">the position in the segment @@ -59218,7 +61562,7 @@ was given. version="1.8"> Translate @position to the total stream time using the currently configured + line="391">Translate @position to the total stream time using the currently configured segment. Compared to gst_segment_to_stream_time() this function can return negative stream-time. @@ -59237,26 +61581,26 @@ to get the real negative stream time. a 1 or -1 on success, 0 on failure. + line="414">a 1 or -1 on success, 0 on failure. a #GstSegment structure. + line="393">a #GstSegment structure. the format of the segment. + line="394">the format of the segment. the position in the segment + line="395">the position in the segment transfer-ownership="full"> result stream-time + line="396">result stream-time @@ -59369,7 +61713,7 @@ values of the seek flags. glib:name="GST_SERIALIZE_FLAG_NONE"> No special flags specified. + line="47">No special flags specified. glib:name="GST_SERIALIZE_FLAG_BACKWARD_COMPAT"> Serialize using the old format for + line="48">Serialize using the old format for nested structures. + + Serialization fails if a value cannot be serialized instead of using +placeholder "NULL" value (e.g. pointers, objects). + version="1.20"> Create a new shared task pool. The shared task pool will queue tasks on + line="524">Create a new shared task pool. The shared task pool will queue tasks on a maximum number of threads, 1 by default. Do not use a #GstSharedTaskPool to manage potentially inter-dependent tasks such @@ -59409,7 +61764,7 @@ would cause obvious deadlocks if they happen to share the same thread. a new #GstSharedTaskPool. gst_object_unref() after usage. + line="534">a new #GstSharedTaskPool. gst_object_unref() after usage. @@ -59420,14 +61775,14 @@ would cause obvious deadlocks if they happen to share the same thread. the maximum number of threads @pool is configured to spawn + line="507">the maximum number of threads @pool is configured to spawn a #GstSharedTaskPool + line="505">a #GstSharedTaskPool @@ -59437,7 +61792,7 @@ would cause obvious deadlocks if they happen to share the same thread. version="1.20"> Update the maximal number of threads the @pool may spawn. When + line="473">Update the maximal number of threads the @pool may spawn. When the maximal number of threads is reduced, existing threads are not immediately shut down, see g_thread_pool_set_max_threads(). @@ -59450,13 +61805,13 @@ Setting @max_threads to 0 effectively freezes the pool. a #GstSharedTaskPool + line="475">a #GstSharedTaskPool Maximum number of threads to spawn. + line="476">Maximum number of threads to spawn. @@ -59508,7 +61863,7 @@ Setting @max_threads to 0 effectively freezes the pool. glib:name="GST_STACK_TRACE_SHOW_NONE"> Try to retrieve the minimum information + line="181">Try to retrieve the minimum information available, which may be none on some platforms (Since: 1.18) @@ -59519,7 +61874,7 @@ Setting @max_threads to 0 effectively freezes the pool. glib:name="GST_STACK_TRACE_SHOW_FULL"> Try to retrieve as much information as possible, + line="184">Try to retrieve as much information as possible, including source information when getting the stack trace @@ -59803,7 +62158,11 @@ gst_element_set_state(). Only @GST_STATE_CHANGE_FAILURE is a real failure. This typically happens with live sources. - + Data structure to initialize #GstCaps from a string description usually @@ -59830,8 +62189,8 @@ instantiate a #GstCaps. Cleans up the cached caps contained in @static_caps. - + line="620">Cleans up the cached caps contained in @static_caps. + @@ -59839,7 +62198,7 @@ instantiate a #GstCaps. the #GstStaticCaps to clean + line="622">the #GstStaticCaps to clean @@ -59847,12 +62206,12 @@ instantiate a #GstCaps. Converts a #GstStaticCaps to a #GstCaps. - + line="556">Converts a #GstStaticCaps to a #GstCaps. + a pointer to the #GstCaps. Since the + line="562">a pointer to the #GstCaps. Since the core holds an additional ref to the returned caps, use gst_caps_make_writable() on the returned caps to modify it. @@ -59861,13 +62220,17 @@ instantiate a #GstCaps. the #GstStaticCaps to convert + line="558">the #GstStaticCaps to convert - + Structure describing the #GstStaticPadTemplate. @@ -60378,6 +62741,9 @@ Applications can activate streams from a collection by using the + default signal handler for the stream-notify signal @@ -60399,25 +62765,25 @@ Applications can activate streams from a collection by using the version="1.10"> Add the given @stream to the @collection. + line="279">Add the given @stream to the @collection. %TRUE if the @stream was properly added, else %FALSE + line="286">%TRUE if the @stream was properly added, else %FALSE a #GstStreamCollection + line="281">a #GstStreamCollection the #GstStream to add + line="282">the #GstStream to add @@ -60427,19 +62793,19 @@ Applications can activate streams from a collection by using the version="1.10"> Get the number of streams this collection contains + line="306">Get the number of streams this collection contains The number of streams that @collection contains + line="312">The number of streams that @collection contains a #GstStreamCollection + line="308">a #GstStreamCollection @@ -60449,27 +62815,27 @@ Applications can activate streams from a collection by using the version="1.10"> Retrieve the #GstStream with index @index from the collection. + line="324">Retrieve the #GstStream with index @index from the collection. The caller should not modify the returned #GstStream A #GstStream + line="333">A #GstStream a #GstStreamCollection + line="326">a #GstStreamCollection Index of the stream to retrieve + line="327">Index of the stream to retrieve @@ -60480,19 +62846,19 @@ The caller should not modify the returned #GstStream version="1.10"> Returns the upstream id of the @collection. + line="211">Returns the upstream id of the @collection. The upstream id + line="217">The upstream id a #GstStreamCollection + line="213">a #GstStreamCollection @@ -60503,6 +62869,9 @@ The caller should not modify the returned #GstStream transfer-ownership="none" getter="get_upstream_id" default-value="NULL"> + stream-id @@ -60525,14 +62894,24 @@ The caller should not modify the returned #GstStream no-recurse="1" detailed="1" no-hooks="1"> + The stream notify signal is used to be notified of property changes to +streams within the collection. - + + the #GstStream that originated the signal - + + the property that changed @@ -60552,6 +62931,9 @@ The caller should not modify the returned #GstStream + default signal handler for the stream-notify signal @@ -61015,14 +63397,17 @@ values are explicitly typed. Some types have special delimiters: -- [GstValueArray](GST_TYPE_ARRAY) are inside curly brackets (`{` and `}`). - For example `a-structure, array={1, 2, 3}` +- [GstValueArray](GST_TYPE_ARRAY) are inside "less and greater than" (`<` and + `>`). For example `a-structure, array=<1, 2, 3> - Ranges are inside brackets (`[` and `]`). For example `a-structure, range=[1, 6, 2]` 1 being the min value, 6 the maximum and 2 the step. To specify a #GST_TYPE_INT64_RANGE you need to explicitly specify it like: `a-structure, a-int64-range=(gint64) [1, 5]` -- [GstValueList](GST_TYPE_LIST) are inside "less and greater than" (`<` and - `>`). For example `a-structure, list=<1, 2, 3> +- [GstValueList](GST_TYPE_LIST) are inside curly brackets (`{` and `}`). + For example `a-structure, list={1, 2, 3}` +- [GStrv](G_TYPE_STRV) are inside "less and greater than" (`<` and + `>`) and each string is double-quoted. + For example `a-structure, strv=(GStrv)<"foo", "bar">`. Since 1.26.0. Structures are delimited either by a null character `\0` or a semicolon `;` the latter allowing to store multiple structures in the same string (see @@ -61052,13 +63437,13 @@ a-struct, nested=[nested-struct, nested=true] ``` > *note*: gst_structure_to_string() won't use that syntax for backward -> compatibility reason, gst_structure_serialize() has been added for +> compatibility reason, gst_structure_serialize_full() has been added for > that purpose. - + the GType of a structure + line="175">the GType of a structure @@ -61067,16 +63452,16 @@ a-struct, nested=[nested-struct, nested=true] Creates a #GstStructure from a string representation. + line="3428">Creates a #GstStructure from a string representation. If end is not %NULL, a pointer to the place inside the given string where parsing ended will be returned. Free-function: gst_structure_free - + a new #GstStructure or %NULL + line="3439">a new #GstStructure or %NULL when the string could not be parsed. Free with gst_structure_free() after use. @@ -61085,7 +63470,7 @@ Free-function: gst_structure_free a string representation of a #GstStructure. + line="3430">a string representation of a #GstStructure. skip="1"> pointer to store the end of the string in. + line="3431">pointer to store the end of the string in. @@ -61107,36 +63492,36 @@ Free-function: gst_structure_free introspectable="0"> Creates a new #GstStructure with the given name. Parses the + line="488">Creates a new #GstStructure with the given name. Parses the list of variable arguments and sets fields to the values listed. Variable arguments should be passed as field name, field type, and value. Last variable argument should be %NULL. Free-function: gst_structure_free - + a new #GstStructure + line="501">a new #GstStructure name of new structure + line="490">name of new structure name of first field to set + line="491">name of first field to set additional arguments + line="492">additional arguments @@ -61144,23 +63529,23 @@ Free-function: gst_structure_free Creates a new, empty #GstStructure with the given @name. + line="407">Creates a new, empty #GstStructure with the given @name. See gst_structure_set_name() for constraints on the @name parameter. Free-function: gst_structure_free - + a new, empty #GstStructure + line="417">a new, empty #GstStructure name of new structure + line="409">name of new structure @@ -61170,7 +63555,7 @@ Free-function: gst_structure_free version="1.2"> Creates a #GstStructure from a string representation. + line="3401">Creates a #GstStructure from a string representation. If end is not %NULL, a pointer to the place inside the given string where parsing ended will be returned. @@ -61180,11 +63565,11 @@ the gst_structure_serialize() function is used (without #GST_SERIALIZE_FLAG_BACKWARD_COMPAT) Free-function: gst_structure_free - + a new #GstStructure or %NULL + line="3416">a new #GstStructure or %NULL when the string could not be parsed. Free with gst_structure_free() after use. @@ -61193,17 +63578,19 @@ Free-function: gst_structure_free a string representation of a #GstStructure + line="3403">a string representation of a #GstStructure + introspectable="0" + deprecated="1" + deprecated-version="1.26"> Creates a new #GstStructure with the given name as a GQuark, followed by + line="1494">Creates a new #GstStructure with the given name as a GQuark, followed by fieldname quark, GType, argument(s) "triplets" in the same format as gst_structure_id_set(). Basically a convenience wrapper around gst_structure_new_id_empty() and gst_structure_id_set(). @@ -61211,93 +63598,318 @@ gst_structure_new_id_empty() and gst_structure_id_set(). The last variable argument must be %NULL (or 0). Free-function: gst_structure_free - + Use gst_structure_new_id_str(). + a new #GstStructure + line="1509">a new #GstStructure name of new structure + line="1496">name of new structure the GQuark for the name of the field to set + line="1497">the GQuark for the name of the field to set variable arguments + line="1498">variable arguments + c:identifier="gst_structure_new_id_empty" + deprecated="1" + deprecated-version="1.26"> Creates a new, empty #GstStructure with the given name as a GQuark. + line="327">Creates a new, empty #GstStructure with the given name as a GQuark. Free-function: gst_structure_free - + Use gst_structure_new_id_str_empty(). + a new, empty #GstStructure + line="335">a new, empty #GstStructure name of new structure + line="329">name of new structure + + Creates a new #GstStructure with the given name as a GQuark, followed by +fieldname GstIdStr, GType, argument(s) "triplets" in the same format as +gst_structure_id_str_set(). Basically a convenience wrapper around +gst_structure_new_id_str_empty() and gst_structure_id_str_set(). + +The last variable argument must be %NULL (or 0). + +Free-function: gst_structure_free + + + a new #GstStructure + + + + + name of new structure + + + + the GstIdStr for the name of the field to set + + + + variable arguments + + + + + + Creates a new, empty #GstStructure with the given name. + +Free-function: gst_structure_free + + + a new, empty #GstStructure + + + + + name of new structure + + + + + + Creates a new #GstStructure with the given @name. Structure fields +are set according to the varargs in a manner similar to +gst_structure_new_id_str(). + +Free-function: gst_structure_free + + + a new #GstStructure + + + + + name of new structure + + + + name of first field to set + + + + variable argument list + + + + + + Creates a new #GstStructure with the given name. Parses the +list of variable arguments and sets fields to the values listed. +Variable arguments should be passed as field name, field type, +and value. Last variable argument should be %NULL. + +@name, @firstfield and all field names need to be valid for the remaining +lifetime of the process, e.g. have to be a static string. + +Free-function: gst_structure_free + + + a new #GstStructure + + + + + name of new structure + + + + name of first field to set + + + + additional arguments + + + + + + Creates a new, empty #GstStructure with the given @name. + +See gst_structure_set_name() for constraints on the @name parameter. + +@name needs to be valid for the remaining lifetime of the process, e.g. has +to be a static string. + +Free-function: gst_structure_free + + + a new, empty #GstStructure + + + + + name of new structure + + + + + + Creates a new #GstStructure with the given @name. Structure fields +are set according to the varargs in a manner similar to +gst_structure_new(). + +See gst_structure_set_name() for constraints on the @name parameter. + +@name, @firstfield and all field names need to be valid for the remaining +lifetime of the process, e.g. have to be a static string. + +Free-function: gst_structure_free + + + a new #GstStructure + + + + + name of new structure + + + + name of first field to set + + + + variable argument list + + + + Creates a new #GstStructure with the given @name. Structure fields + line="563">Creates a new #GstStructure with the given @name. Structure fields are set according to the varargs in a manner similar to gst_structure_new(). See gst_structure_set_name() for constraints on the @name parameter. Free-function: gst_structure_free - + a new #GstStructure + line="577">a new #GstStructure name of new structure + line="565">name of new structure name of first field to set + line="566">name of first field to set variable argument list + line="567">variable argument list @@ -61305,26 +63917,26 @@ Free-function: gst_structure_free Tries intersecting @struct1 and @struct2 and reports whether the result + line="4397">Tries intersecting @struct1 and @struct2 and reports whether the result would not be empty. - + %TRUE if intersection would not be empty + line="4405">%TRUE if intersection would not be empty a #GstStructure + line="4399">a #GstStructure a #GstStructure + line="4400">a #GstStructure @@ -61332,36 +63944,39 @@ would not be empty. Duplicates a #GstStructure and all its fields and values. + line="699">Duplicates a #GstStructure and all its fields and values. Free-function: gst_structure_free - + a new #GstStructure. + line="707">a new #GstStructure. a #GstStructure to duplicate + line="701">a #GstStructure to duplicate + version="1.6" + deprecated="1" + deprecated-version="1.26"> Calls the provided function once for each field in the #GstStructure. In + line="2232">Calls the provided function once for each field in the #GstStructure. In contrast to gst_structure_foreach(), the function may modify the fields. In contrast to gst_structure_map_in_place(), the field is removed from the structure if %FALSE is returned from the function. The structure must be mutable. - + Use gst_structure_filter_and_map_in_place_id_str(). + @@ -61369,7 +63984,7 @@ The structure must be mutable. a #GstStructure + line="2234">a #GstStructure closure="1"> a function to call for each field + line="2235">a function to call for each field @@ -61388,7 +64003,49 @@ The structure must be mutable. allow-none="1"> private data + line="2236">private data + + + + + + Calls the provided function once for each field in the #GstStructure. In +contrast to gst_structure_foreach_id_str(), the function may modify the fields. +In contrast to gst_structure_map_in_place_id_str(), the field is removed from +the structure if %FALSE is returned from the function. +The structure must be mutable. + + + + + + + a #GstStructure + + + + a function to call for each field + + + + private data @@ -61396,9 +64053,9 @@ The structure must be mutable. Fixate all values in @structure using gst_value_fixate(). + line="4488">Fixate all values in @structure using gst_value_fixate(). @structure will be modified in-place and should be writable. - + @@ -61406,7 +64063,7 @@ The structure must be mutable. a #GstStructure + line="4490">a #GstStructure @@ -61414,25 +64071,25 @@ The structure must be mutable. Fixates a #GstStructure by changing the given field with its fixated value. - + line="3860">Fixates a #GstStructure by changing the given field with its fixated value. + %TRUE if the structure field could be fixated + line="3867">%TRUE if the structure field could be fixated a #GstStructure + line="3862">a #GstStructure a field in @structure + line="3863">a field in @structure @@ -61441,32 +64098,32 @@ The structure must be mutable. c:identifier="gst_structure_fixate_field_boolean"> Fixates a #GstStructure by changing the given @field_name field to the given + line="3644">Fixates a #GstStructure by changing the given @field_name field to the given @target boolean if that field is not fixed yet. - + %TRUE if the structure could be fixated + line="3653">%TRUE if the structure could be fixated a #GstStructure + line="3646">a #GstStructure a field in @structure + line="3647">a field in @structure the target value of the fixation + line="3648">the target value of the fixation @@ -61475,32 +64132,32 @@ The structure must be mutable. c:identifier="gst_structure_fixate_field_nearest_double"> Fixates a #GstStructure by changing the given field to the nearest + line="3579">Fixates a #GstStructure by changing the given field to the nearest double to @target that is a subset of the existing field. - + %TRUE if the structure could be fixated + line="3588">%TRUE if the structure could be fixated a #GstStructure + line="3581">a #GstStructure a field in @structure + line="3582">a field in @structure the target value of the fixation + line="3583">the target value of the fixation @@ -61509,39 +64166,39 @@ double to @target that is a subset of the existing field. c:identifier="gst_structure_fixate_field_nearest_fraction"> Fixates a #GstStructure by changing the given field to the nearest + line="3750">Fixates a #GstStructure by changing the given field to the nearest fraction to @target_numerator/@target_denominator that is a subset of the existing field. - + %TRUE if the structure could be fixated + line="3761">%TRUE if the structure could be fixated a #GstStructure + line="3752">a #GstStructure a field in @structure + line="3753">a field in @structure The numerator of the target value of the fixation + line="3754">The numerator of the target value of the fixation The denominator of the target value of the fixation + line="3755">The denominator of the target value of the fixation @@ -61550,32 +64207,32 @@ of the existing field. c:identifier="gst_structure_fixate_field_nearest_int"> Fixates a #GstStructure by changing the given field to the nearest + line="3509">Fixates a #GstStructure by changing the given field to the nearest integer to @target that is a subset of the existing field. - + %TRUE if the structure could be fixated + line="3518">%TRUE if the structure could be fixated a #GstStructure + line="3511">a #GstStructure a field in @structure + line="3512">a field in @structure the target value of the fixation + line="3513">the target value of the fixation @@ -61584,47 +64241,51 @@ integer to @target that is a subset of the existing field. c:identifier="gst_structure_fixate_field_string"> Fixates a #GstStructure by changing the given @field_name field to the given + line="3697">Fixates a #GstStructure by changing the given @field_name field to the given @target string if that field is not fixed yet. - + %TRUE if the structure could be fixated + line="3706">%TRUE if the structure could be fixated a #GstStructure + line="3699">a #GstStructure a field in @structure + line="3700">a field in @structure the target value of the fixation + line="3701">the target value of the fixation - + Calls the provided function once for each field in the #GstStructure. The + line="2151">Calls the provided function once for each field in the #GstStructure. The function must not modify the fields. Also see gst_structure_map_in_place() and gst_structure_filter_and_map_in_place(). - + Use gst_structure_foreach_id_str(). + %TRUE if the supplied function returns %TRUE For each of the fields, + line="2161">%TRUE if the supplied function returns %TRUE For each of the fields, %FALSE otherwise. @@ -61632,7 +64293,7 @@ and gst_structure_filter_and_map_in_place(). a #GstStructure + line="2153">a #GstStructure closure="1"> a function to call for each field + line="2154">a function to call for each field @@ -61651,7 +64312,51 @@ and gst_structure_filter_and_map_in_place(). allow-none="1"> private data + line="2155">private data + + + + + + Calls the provided function once for each field in the #GstStructure. The +function must not modify the fields. Also see gst_structure_map_in_place_id_str() +and gst_structure_filter_and_map_in_place_id_str(). + + + %TRUE if the supplied function returns %TRUE For each of the fields, +%FALSE otherwise. + + + + + a #GstStructure + + + + a function to call for each field + + + + private data @@ -61659,9 +64364,9 @@ and gst_structure_filter_and_map_in_place(). Frees a #GstStructure and all its fields and values. The structure must not + line="738">Frees a #GstStructure and all its fields and values. The structure must not have a parent when this function is called. - + @@ -61669,7 +64374,7 @@ have a parent when this function is called. the #GstStructure to free + line="740">the #GstStructure to free @@ -61677,7 +64382,7 @@ have a parent when this function is called. Parses the variable arguments and reads fields from @structure accordingly. + line="4120">Parses the variable arguments and reads fields from @structure accordingly. Variable arguments should be in the form field name, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be %NULL. @@ -61686,11 +64391,11 @@ For refcounted (mini)objects you will receive a new reference which you must release with a suitable _unref\() when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either g_free() or the suitable function for the boxed type. - + %FALSE if there was a problem reading any of the fields (e.g. + line="4136">%FALSE if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other than the type specified), otherwise %TRUE. @@ -61699,19 +64404,19 @@ release with either g_free() or the suitable function for the boxed type. a #GstStructure + line="4122">a #GstStructure the name of the first field to read + line="4123">the name of the first field to read variable arguments + line="4124">variable arguments @@ -61721,15 +64426,15 @@ release with either g_free() or the suitable function for the boxed type. version="1.12"> This is useful in language bindings where unknown #GValue types are not + line="4530">This is useful in language bindings where unknown #GValue types are not supported. This function will convert the %GST_TYPE_ARRAY into a newly allocated #GValueArray and return it through @array. Be aware that this is slower then getting the #GValue directly. - + %TRUE if the value could be set correctly. If there was no field + line="4541">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a %GST_TYPE_ARRAY, this function returns %FALSE. @@ -61738,13 +64443,13 @@ this function returns %FALSE. a #GstStructure + line="4532">a #GstStructure the name of a field + line="4533">the name of a field transfer-ownership="full"> a pointer to a #GValueArray + line="4534">a pointer to a #GValueArray @@ -61761,14 +64466,14 @@ this function returns %FALSE. Sets the boolean pointed to by @value corresponding to the value of the + line="2541">Sets the boolean pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2551">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a boolean, this function returns %FALSE. @@ -61777,13 +64482,13 @@ function returns %FALSE. a #GstStructure + line="2543">a #GstStructure the name of a field + line="2544">the name of a field transfer-ownership="full"> a pointer to a #gboolean to set + line="2545">a pointer to a #gboolean to set @@ -61801,14 +64506,14 @@ function returns %FALSE. c:identifier="gst_structure_get_clock_time"> Sets the clock time pointed to by @value corresponding to the clock time + line="2796">Sets the clock time pointed to by @value corresponding to the clock time of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2806">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a #GstClockTime, this function returns %FALSE. @@ -61817,13 +64522,13 @@ function returns %FALSE. a #GstStructure + line="2798">a #GstStructure the name of a field + line="2799">the name of a field transfer-ownership="full"> a pointer to a #GstClockTime to set + line="2800">a pointer to a #GstClockTime to set @@ -61840,7 +64545,7 @@ function returns %FALSE. Sets the date pointed to by @value corresponding to the date of the + line="2714">Sets the date pointed to by @value corresponding to the date of the given field. Caller is responsible for making sure the field exists and has the correct type. @@ -61848,11 +64553,11 @@ On success @value will point to a newly-allocated copy of the date which should be freed with g_date_free() when no longer needed (note: this is inconsistent with e.g. gst_structure_get_string() which doesn't return a copy of the string). - + %TRUE if the value could be set correctly. If there was no field + line="2729">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a data, this function returns %FALSE. @@ -61861,13 +64566,13 @@ returns %FALSE. a #GstStructure + line="2716">a #GstStructure the name of a field + line="2717">the name of a field transfer-ownership="full"> a pointer to a #GDate to set + line="2718">a pointer to a #GDate to set @@ -61884,7 +64589,7 @@ returns %FALSE. Sets the datetime pointed to by @value corresponding to the datetime of the + line="2754">Sets the datetime pointed to by @value corresponding to the datetime of the given field. Caller is responsible for making sure the field exists and has the correct type. @@ -61892,11 +64597,11 @@ On success @value will point to a reference of the datetime which should be unreffed with gst_date_time_unref() when no longer needed (note: this is inconsistent with e.g. gst_structure_get_string() which doesn't return a copy of the string). - + %TRUE if the value could be set correctly. If there was no field + line="2769">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a data, this function returns %FALSE. @@ -61905,13 +64610,13 @@ returns %FALSE. a #GstStructure + line="2756">a #GstStructure the name of a field + line="2757">the name of a field transfer-ownership="full"> a pointer to a #GstDateTime to set + line="2758">a pointer to a #GstDateTime to set @@ -61928,14 +64633,14 @@ returns %FALSE. Sets the double pointed to by @value corresponding to the value of the + line="2817">Sets the double pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2827">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a double, this function returns %FALSE. @@ -61944,13 +64649,13 @@ function returns %FALSE. a #GstStructure + line="2819">a #GstStructure the name of a field + line="2820">the name of a field transfer-ownership="full"> a pointer to a gdouble to set + line="2821">a pointer to a gdouble to set @@ -61967,14 +64672,14 @@ function returns %FALSE. Sets the int pointed to by @value corresponding to the value of the + line="2883">Sets the int pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists, has the correct type and that the enumtype is correct. - + %TRUE if the value could be set correctly. If there was no field + line="2894">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain an enum of the given type, this function returns %FALSE. @@ -61983,19 +64688,19 @@ type, this function returns %FALSE. a #GstStructure + line="2885">a #GstStructure the name of a field + line="2886">the name of a field the enum type of a field + line="2887">the enum type of a field transfer-ownership="full"> a pointer to an int to set + line="2888">a pointer to an int to set @@ -62013,27 +64718,27 @@ type, this function returns %FALSE. c:identifier="gst_structure_get_field_type"> Finds the field with the given name, and returns the type of the + line="2015">Finds the field with the given name, and returns the type of the value it contains. If the field is not found, G_TYPE_INVALID is returned. - + the #GValue of the field + line="2024">the #GValue of the field a #GstStructure + line="2017">a #GstStructure the name of the field + line="2018">the name of the field @@ -62043,14 +64748,14 @@ returned. version="1.22"> Sets the unsigned int pointed to by @value corresponding to the value of the + line="4648">Sets the unsigned int pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists, has the correct type and that the flagstype is correct. - + %TRUE if the value could be set correctly. If there was no field + line="4659">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain flags or did not contain flags of the given type, this function returns %FALSE. @@ -62059,19 +64764,19 @@ did not contain flags of the given type, this function returns %FALSE. a #GstStructure + line="4650">a #GstStructure the name of a field + line="4651">the name of a field the flags type of a field + line="4652">the flags type of a field transfer-ownership="full"> a pointer to an unsigned int to set + line="4653">a pointer to an unsigned int to set @@ -62090,13 +64795,13 @@ did not contain flags of the given type, this function returns %FALSE. version="1.6"> Read the GstFlagSet flags and mask out of the structure into the + line="2958">Read the GstFlagSet flags and mask out of the structure into the provided pointers. - + %TRUE if the values could be set correctly. If there was no field + line="2968">%TRUE if the values could be set correctly. If there was no field with @fieldname or the existing field did not contain a GstFlagSet, this function returns %FALSE. @@ -62105,13 +64810,13 @@ function returns %FALSE. a #GstStructure + line="2960">a #GstStructure the name of a field + line="2961">the name of a field allow-none="1"> a pointer to a guint for the flags field + line="2962">a pointer to a guint for the flags field allow-none="1"> a pointer to a guint for the mask field + line="2963">a pointer to a guint for the mask field @@ -62141,14 +64846,14 @@ function returns %FALSE. Sets the integers pointed to by @value_numerator and @value_denominator + line="2921">Sets the integers pointed to by @value_numerator and @value_denominator corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the values could be set correctly. If there was no field + line="2932">%TRUE if the values could be set correctly. If there was no field with @fieldname or the existing field did not contain a GstFraction, this function returns %FALSE. @@ -62157,13 +64862,13 @@ function returns %FALSE. a #GstStructure + line="2923">a #GstStructure the name of a field + line="2924">the name of a field transfer-ownership="full"> a pointer to an int to set + line="2925">a pointer to an int to set transfer-ownership="full"> a pointer to an int to set + line="2926">a pointer to an int to set @@ -62189,14 +64894,14 @@ function returns %FALSE. Sets the int pointed to by @value corresponding to the value of the + line="2574">Sets the int pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2584">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain an int, this function returns %FALSE. @@ -62205,13 +64910,13 @@ returns %FALSE. a #GstStructure + line="2576">a #GstStructure the name of a field + line="2577">the name of a field transfer-ownership="full"> a pointer to an int to set + line="2578">a pointer to an int to set @@ -62230,14 +64935,14 @@ returns %FALSE. version="1.4"> Sets the #gint64 pointed to by @value corresponding to the value of the + line="2642">Sets the #gint64 pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2652">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a #gint64, this function returns %FALSE. @@ -62246,13 +64951,13 @@ returns %FALSE. a #GstStructure + line="2644">a #GstStructure the name of a field + line="2645">the name of a field transfer-ownership="full"> a pointer to a #gint64 to set + line="2646">a pointer to a #gint64 to set @@ -62271,15 +64976,15 @@ returns %FALSE. version="1.12"> This is useful in language bindings where unknown #GValue types are not + line="4555">This is useful in language bindings where unknown #GValue types are not supported. This function will convert the %GST_TYPE_LIST into a newly allocated GValueArray and return it through @array. Be aware that this is slower then getting the #GValue directly. - + %TRUE if the value could be set correctly. If there was no field + line="4566">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a %GST_TYPE_LIST, this function returns %FALSE. @@ -62288,13 +64993,13 @@ function returns %FALSE. a #GstStructure + line="4557">a #GstStructure the name of a field + line="4558">the name of a field transfer-ownership="full"> a pointer to a #GValueArray + line="4559">a pointer to a #GValueArray @@ -62311,39 +65016,65 @@ function returns %FALSE. Get the name of @structure as a string. - + line="841">Get the name of @structure as a string. + the name of the structure. + line="847">the name of the structure. a #GstStructure + line="843">a #GstStructure - + Get the name of @structure as a GQuark. - + line="876">Get the name of @structure as a GQuark. + Use gst_structure_get_name_id_str(). + the quark representing the name of the structure. + line="882">the quark representing the name of the structure. a #GstStructure + line="878">a #GstStructure + + + + + + Get the name of @structure as a GstIdStr. + + + the name of the structure. + + + + + a #GstStructure @@ -62351,17 +65082,17 @@ function returns %FALSE. Finds the field corresponding to @fieldname, and returns the string + line="2851">Finds the field corresponding to @fieldname, and returns the string contained in the field's value. Caller is responsible for making sure the field exists and has the correct type. The string should not be modified, and remains valid until the next call to a gst_structure_*() function with the given structure. - + a pointer to the string or %NULL when the + line="2863">a pointer to the string or %NULL when the field did not exist or did not contain a string. @@ -62369,13 +65100,13 @@ field did not exist or did not contain a string. a #GstStructure + line="2853">a #GstStructure the name of a field + line="2854">the name of a field @@ -62383,14 +65114,14 @@ field did not exist or did not contain a string. Sets the uint pointed to by @value corresponding to the value of the + line="2608">Sets the uint pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2618">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a uint, this function returns %FALSE. @@ -62399,13 +65130,13 @@ returns %FALSE. a #GstStructure + line="2610">a #GstStructure the name of a field + line="2611">the name of a field transfer-ownership="full"> a pointer to a uint to set + line="2612">a pointer to a uint to set @@ -62424,14 +65155,14 @@ returns %FALSE. version="1.4"> Sets the #guint64 pointed to by @value corresponding to the value of the + line="2678">Sets the #guint64 pointed to by @value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. - + %TRUE if the value could be set correctly. If there was no field + line="2688">%TRUE if the value could be set correctly. If there was no field with @fieldname or the existing field did not contain a #guint64, this function returns %FALSE. @@ -62440,13 +65171,13 @@ returns %FALSE. a #GstStructure + line="2680">a #GstStructure the name of a field + line="2681">the name of a field transfer-ownership="full"> a pointer to a #guint64 to set + line="2682">a pointer to a #guint64 to set @@ -62465,33 +65196,33 @@ returns %FALSE. introspectable="0"> Parses the variable arguments and reads fields from @structure accordingly. + line="3909">Parses the variable arguments and reads fields from @structure accordingly. valist-variant of gst_structure_get(). Look at the documentation of gst_structure_get() for more details. - + %TRUE, or %FALSE if there was a problem reading any of the fields + line="3919">%TRUE, or %FALSE if there was a problem reading any of the fields a #GstStructure + line="3911">a #GstStructure the name of the first field to read + line="3912">the name of the first field to read variable arguments + line="3913">variable arguments @@ -62499,12 +65230,12 @@ gst_structure_get() for more details. Get the value of the field with name @fieldname. - + line="1735">Get the value of the field with name @fieldname. + the #GValue corresponding to the field with the given + line="1742">the #GValue corresponding to the field with the given name. @@ -62512,13 +65243,13 @@ name. a #GstStructure + line="1737">a #GstStructure the name of the field to get + line="1738">the name of the field to get @@ -62526,25 +65257,25 @@ name. Check if @structure contains a field named @fieldname. - + line="2430">Check if @structure contains a field named @fieldname. + %TRUE if the structure contains a field with the given name + line="2437">%TRUE if the structure contains a field with the given name a #GstStructure + line="2432">a #GstStructure the name of a field + line="2433">the name of a field @@ -62553,31 +65284,31 @@ name. c:identifier="gst_structure_has_field_typed"> Check if @structure contains a field named @fieldname and with GType @type. - + line="2511">Check if @structure contains a field named @fieldname and with GType @type. + %TRUE if the structure contains a field with the given name and type + line="2519">%TRUE if the structure contains a field with the given name and type a #GstStructure + line="2513">a #GstStructure the name of a field + line="2514">the name of a field the type of a value + line="2515">the type of a value @@ -62585,35 +65316,37 @@ name. Checks if the structure has the given name - + line="857">Checks if the structure has the given name + %TRUE if @name matches the name of the structure. + line="864">%TRUE if @name matches the name of the structure. a #GstStructure + line="859">a #GstStructure structure name to check for + line="860">structure name to check for + introspectable="0" + deprecated="1" + deprecated-version="1.26"> Parses the variable arguments and reads fields from @structure accordingly. + line="4196">Parses the variable arguments and reads fields from @structure accordingly. Variable arguments should be in the form field id quark, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be %NULL (technically it should be a @@ -62628,11 +65361,12 @@ For refcounted (mini)objects you will receive a new reference which you must release with a suitable _unref\() when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either g_free() or the suitable function for the boxed type. - + Use gst_structure_id_str_get(). + %FALSE if there was a problem reading any of the fields (e.g. + line="4218">%FALSE if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other than the type specified), otherwise %TRUE. @@ -62641,55 +65375,58 @@ release with either g_free() or the suitable function for the boxed type. a #GstStructure + line="4198">a #GstStructure the quark of the first field to read + line="4199">the quark of the first field to read variable arguments + line="4200">variable arguments + introspectable="0" + deprecated="1" + deprecated-version="1.26"> Parses the variable arguments and reads fields from @structure accordingly. + line="4046">Parses the variable arguments and reads fields from @structure accordingly. valist-variant of gst_structure_id_get(). Look at the documentation of gst_structure_id_get() for more details. - + Use gst_structure_id_str_get_valist(). + %TRUE, or %FALSE if there was a problem reading any of the fields + line="4056">%TRUE, or %FALSE if there was a problem reading any of the fields a #GstStructure + line="4048">a #GstStructure the quark of the first field to read + line="4049">the quark of the first field to read variable arguments + line="4050">variable arguments @@ -62697,12 +65434,12 @@ gst_structure_id_get() for more details. Get the value of the field with GQuark @field. - + line="1789">Get the value of the field with GQuark @field. + the #GValue corresponding to the field with the given + line="1796">the #GValue corresponding to the field with the given name identifier. @@ -62710,87 +65447,97 @@ name identifier. a #GstStructure + line="1791">a #GstStructure the #GQuark of the field to get + line="1792">the #GQuark of the field to get - + Check if @structure contains a field named @field. - + line="2381">Check if @structure contains a field named @field. + Use gst_structure_id_str_has_field(). + %TRUE if the structure contains a field with the given name + line="2388">%TRUE if the structure contains a field with the given name a #GstStructure + line="2383">a #GstStructure #GQuark of the field name + line="2384">#GQuark of the field name + c:identifier="gst_structure_id_has_field_typed" + deprecated="1" + deprecated-version="1.26"> Check if @structure contains a field named @field and with GType @type. - + line="2457">Check if @structure contains a field named @field and with GType @type. + Use gst_structure_id_str_has_field_typed(). + %TRUE if the structure contains a field with the given name and type + line="2465">%TRUE if the structure contains a field with the given name and type a #GstStructure + line="2459">a #GstStructure #GQuark of the field name + line="2460">#GQuark of the field name the type of a value + line="2461">the type of a value + introspectable="0" + deprecated="1" + deprecated-version="1.26"> Identical to gst_structure_set, except that field names are + line="1375">Identical to gst_structure_set, except that field names are passed using the GQuark for the field name. This allows more efficient setting of the structure if the caller already knows the associated quark values. The last variable argument must be %NULL. - + Use gst_structure_id_str_set(). + @@ -62798,30 +65545,33 @@ The last variable argument must be %NULL. a #GstStructure + line="1377">a #GstStructure the GQuark for the name of the field to set + line="1378">the GQuark for the name of the field to set variable arguments + line="1379">variable arguments + introspectable="0" + deprecated="1" + deprecated-version="1.26"> va_list form of gst_structure_id_set(). - + line="1401">va_list form of gst_structure_id_set(). + Use gst_structure_id_str_set_valist(). + @@ -62829,30 +65579,34 @@ The last variable argument must be %NULL. a #GstStructure + line="1403">a #GstStructure the name of the field to set + line="1404">the name of the field to set variable arguments + line="1405">variable arguments - + Sets the field with the given GQuark @field to @value. If the field + line="990">Sets the field with the given GQuark @field to @value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. - + Use gst_structure_id_str_set_value(). + @@ -62860,30 +65614,491 @@ value is replaced and freed. a #GstStructure + line="992">a #GstStructure a #GQuark representing a field + line="993">a #GQuark representing a field the new value of the field + line="994">the new value of the field + + + + + + Parses the variable arguments and reads fields from @structure accordingly. +Variable arguments should be in the form field name (as GstIdStr), field type +(as a GType), pointer(s) to a variable(s) to hold the return value(s). The +last variable argument should be %NULL. + +For refcounted (mini)objects you will receive a new reference which +you must release with a suitable _unref\() when no longer needed. For +strings and boxed types you will receive a copy which you will need to +release with either g_free() or the suitable function for the boxed type. + + + %FALSE if there was a problem reading any of the fields (e.g. + because the field requested did not exist, or was of a type other + than the type specified), otherwise %TRUE. + + + + + a #GstStructure + + + + the name of the first field to read + + + + variable arguments + + + + + + Finds the field with the given name, and returns the type of the +value it contains. If the field is not found, G_TYPE_INVALID is +returned. + + + the #GValue of the field + + + + + a #GstStructure + + + + the name of the field + + + + + + Parses the variable arguments and reads fields from @structure accordingly. +valist-variant of gst_structure_id_str_get(). Look at the documentation of +gst_structure_id_str_get() for more details. + + + %TRUE, or %FALSE if there was a problem reading any of the fields + + + + + a #GstStructure + + + + the name of the first field to read + + + + variable arguments + + + + + + Get the value of the field with name @fieldname. + + + the #GValue corresponding to the field with the given +name. + + + + + a #GstStructure + + + + the name of the field to get + + + + + + Check if @structure contains a field named @fieldname. + + + %TRUE if the structure contains a field with the given name + + + + + a #GstStructure + + + + the name of a field + + + + + + Check if @structure contains a field named @fieldname and with GType @type. + + + %TRUE if the structure contains a field with the given name and type + + + + + a #GstStructure + + + + the name of a field + + + + the type of a value + + + + + + Get the name (as a GstIdStr) of the given field number, +counting from 0 onwards. + + + the name of the given field number + + + + + a #GstStructure + + + + the index to get the name of + + + + + + Removes the field with the given name. If the field with the given +name does not exist, the structure is unchanged. + + + + + + + a #GstStructure + + + + the name of the field to remove + + + + + + Removes the fields with the given names. If a field does not exist, the +argument is ignored. + + + + + + + a #GstStructure + + + + the name of the field to remove + + + + %NULL-terminated list of more fieldnames to remove + + + + + + va_list form of gst_structure_id_str_remove_fields(). + + + + + + + a #GstStructure + + + + the name of the field to remove + + + + %NULL-terminated list of more fieldnames to remove + + + + + + Identical to gst_structure_set, except that field names are +passed using a GstIdStr for the field name. This allows more efficient +setting of the structure if the caller already owns the associated +GstIdStr values or if they can be built from static literals. +The last variable argument must be %NULL. + + + + + + + a #GstStructure + + + + the the name of the field to set + + + + variable arguments + + + + + + va_list form of gst_structure_id_str_set(). + + + + + + + a #GstStructure + + + + the name of the field to set + + + + variable arguments + + + + + + Sets the field with the given name @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. + + + + + + + a #GstStructure + + + + the name of the field to set + + + + the new value of the field - + Sets the field with the given GQuark @field to @value. If the field + line="1199">Sets the field with the given GstIdStr @field to @value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. - + + + + + + + a #GstStructure + + + + the name of the field to set + + + + the new value of the field + + + + + + Sets the field with the given GQuark @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. + Use gst_structure_id_str_take_value(). + @@ -62891,19 +66106,19 @@ value is replaced and freed. a #GstStructure + line="1120">a #GstStructure a #GQuark representing a field + line="1121">a #GQuark representing a field the new value of the field + line="1122">the new value of the field @@ -62911,25 +66126,25 @@ value is replaced and freed. Intersects @struct1 and @struct2 and returns the intersection. - + line="4290">Intersects @struct1 and @struct2 and returns the intersection. + Intersection of @struct1 and @struct2 + line="4297">Intersection of @struct1 and @struct2 a #GstStructure + line="4292">a #GstStructure a #GstStructure + line="4293">a #GstStructure @@ -62937,25 +66152,25 @@ value is replaced and freed. Tests if the two #GstStructure are equal. - + line="4259">Tests if the two #GstStructure are equal. + %TRUE if the two structures have the same name and field. + line="4266">%TRUE if the two structures have the same name and field. a #GstStructure. + line="4261">a #GstStructure. a #GstStructure. + line="4262">a #GstStructure. @@ -62963,42 +66178,46 @@ value is replaced and freed. Checks if @subset is a subset of @superset, i.e. has the same + line="4424">Checks if @subset is a subset of @superset, i.e. has the same structure name and for all fields that are existing in @superset, @subset has a value that is a subset of the value in @superset. - + %TRUE if @subset is a subset of @superset + line="4433">%TRUE if @subset is a subset of @superset a #GstStructure + line="4426">a #GstStructure a potentially greater #GstStructure + line="4427">a potentially greater #GstStructure - + Calls the provided function once for each field in the #GstStructure. In + line="2191">Calls the provided function once for each field in the #GstStructure. In contrast to gst_structure_foreach(), the function may modify but not delete the fields. The structure must be mutable. - + Use gst_structure_map_in_place_id_str(). + %TRUE if the supplied function returns %TRUE For each of the fields, + line="2201">%TRUE if the supplied function returns %TRUE For each of the fields, %FALSE otherwise. @@ -63006,7 +66225,7 @@ fields. The structure must be mutable. a #GstStructure + line="2193">a #GstStructure closure="1"> a function to call for each field + line="2194">a function to call for each field allow-none="1"> private data + line="2195">private data + + + + + + Calls the provided function once for each field in the #GstStructure. In +contrast to gst_structure_foreach_id_str(), the function may modify but not delete the +fields. The structure must be mutable. + + + %TRUE if the supplied function returns %TRUE For each of the fields, +%FALSE otherwise. + + + + + a #GstStructure + + + + a function to call for each field + + + + private data @@ -63032,19 +66295,19 @@ fields. The structure must be mutable. Get the number of fields in the structure. - + line="2071">Get the number of fields in the structure. + the number of fields in the structure + line="2077">the number of fields in the structure a #GstStructure + line="2073">a #GstStructure @@ -63053,25 +66316,25 @@ fields. The structure must be mutable. c:identifier="gst_structure_nth_field_name"> Get the name of the given field number, counting from 0 onwards. - + line="2087">Get the name of the given field number, counting from 0 onwards. + the name of the given field number + line="2094">the name of the given field number a #GstStructure + line="2089">a #GstStructure the index to get the name of + line="2090">the index to get the name of @@ -63080,8 +66343,8 @@ fields. The structure must be mutable. c:identifier="gst_structure_remove_all_fields"> Removes all fields in a GstStructure. - + line="1989">Removes all fields in a GstStructure. + @@ -63089,7 +66352,7 @@ fields. The structure must be mutable. a #GstStructure + line="1991">a #GstStructure @@ -63097,9 +66360,9 @@ fields. The structure must be mutable. Removes the field with the given name. If the field with the given + line="1815">Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged. - + @@ -63107,13 +66370,13 @@ name does not exist, the structure is unchanged. a #GstStructure + line="1817">a #GstStructure the name of the field to remove + line="1818">the name of the field to remove @@ -63123,9 +66386,9 @@ name does not exist, the structure is unchanged. introspectable="0"> Removes the fields with the given names. If a field does not exist, the + line="1853">Removes the fields with the given names. If a field does not exist, the argument is ignored. - + @@ -63133,19 +66396,19 @@ argument is ignored. a #GstStructure + line="1855">a #GstStructure the name of the field to remove + line="1856">the name of the field to remove %NULL-terminated list of more fieldnames to remove + line="1857">%NULL-terminated list of more fieldnames to remove @@ -63155,8 +66418,8 @@ argument is ignored. introspectable="0"> va_list form of gst_structure_remove_fields(). - + line="1877">va_list form of gst_structure_remove_fields(). + @@ -63164,41 +66427,47 @@ argument is ignored. a #GstStructure + line="1879">a #GstStructure the name of the field to remove + line="1880">the name of the field to remove %NULL-terminated list of more fieldnames to remove + line="1881">%NULL-terminated list of more fieldnames to remove + version="1.20" + deprecated="1"> Converts @structure to a human-readable string representation. + line="3214">Converts @structure to a human-readable string representation. This version of the caps serialization function introduces support for nested structures and caps but the resulting strings won't be parsable with GStreamer prior to 1.20 unless #GST_SERIALIZE_FLAG_BACKWARD_COMPAT is passed as @flag. +%GST_SERIALIZE_FLAG_STRICT flags is not allowed because it would make this +function nullable which is an API break for bindings. +Use gst_structure_serialize_full() instead. + Free-function: g_free - + Use gst_structure_serialize_full() instead. + a pointer to string allocated by g_malloc(). + line="3232">a pointer to string allocated by g_malloc(). g_free() after usage. @@ -63206,13 +66475,43 @@ Free-function: g_free a #GstStructure + line="3216">a #GstStructure The flags to use to serialize structure + line="3217">The flags to use to serialize structure + + + + + + Alias for gst_structure_serialize() but with nullable annotation because it +can return %NULL when %GST_SERIALIZE_FLAG_STRICT flag is set. + + + a pointer to string allocated by g_malloc(). + g_free() after usage. + + + + + a #GstStructure + + + + The flags to use to serialize structure @@ -63220,11 +66519,11 @@ Free-function: g_free Parses the variable arguments and sets fields accordingly. Fields that + line="1254">Parses the variable arguments and sets fields accordingly. Fields that weren't already part of the structure are added as needed. Variable arguments should be in the form field name, field type (as a GType), value(s). The last variable argument should be %NULL. - + @@ -63232,19 +66531,19 @@ Variable arguments should be in the form field name, field type a #GstStructure + line="1256">a #GstStructure the name of the field to set + line="1257">the name of the field to set variable arguments + line="1258">variable arguments @@ -63254,11 +66553,11 @@ Variable arguments should be in the form field name, field type version="1.12"> This is useful in language bindings where unknown GValue types are not + line="4608">This is useful in language bindings where unknown GValue types are not supported. This function will convert a @array to %GST_TYPE_ARRAY and set the field specified by @fieldname. Be aware that this is slower then using %GST_TYPE_ARRAY in a #GValue directly. - + @@ -63266,19 +66565,19 @@ the field specified by @fieldname. Be aware that this is slower then using a #GstStructure + line="4610">a #GstStructure the name of a field + line="4611">the name of a field a pointer to a #GValueArray + line="4612">a pointer to a #GValueArray @@ -63288,11 +66587,11 @@ the field specified by @fieldname. Be aware that this is slower then using version="1.12"> This is useful in language bindings where unknown GValue types are not + line="4628">This is useful in language bindings where unknown GValue types are not supported. This function will convert a @array to %GST_TYPE_LIST and set the field specified by @fieldname. Be aware that this is slower then using %GST_TYPE_LIST in a #GValue directly. - + @@ -63300,19 +66599,19 @@ the field specified by @fieldname. Be aware that this is slower then using a #GstStructure + line="4630">a #GstStructure the name of a field + line="4631">the name of a field a pointer to a #GValueArray + line="4632">a pointer to a #GValueArray @@ -63320,10 +66619,37 @@ the field specified by @fieldname. Be aware that this is slower then using Sets the name of the structure to the given @name. The string + line="934">Sets the name of the structure to the given @name. The string +provided is copied before being used. It must not be empty, start with a +letter and can be followed by letters, numbers and any of "/-_.:". + + + + + + + a #GstStructure + + + + the new name of the structure + + + + + + Sets the name of the structure to the given @name. The string provided is copied before being used. It must not be empty, start with a letter and can be followed by letters, numbers and any of "/-_.:". - + @@ -63331,13 +66657,43 @@ letter and can be followed by letters, numbers and any of "/-_.:". a #GstStructure + line="915">a #GstStructure the new name of the structure + line="916">the new name of the structure + + + + + + Sets the name of the structure to the given @name. The string +provided is copied before being used. It must not be empty, start with a +letter and can be followed by letters, numbers and any of "/-_.:". + +@name needs to be valid for the remaining lifetime of the process, e.g. has +to be a static string. + + + + + + + a #GstStructure + + + + the new name of the structure @@ -63346,39 +66702,112 @@ letter and can be followed by letters, numbers and any of "/-_.:". c:identifier="gst_structure_set_parent_refcount"> Sets the parent_refcount field of #GstStructure. This field is used to + line="663">Sets the parent_refcount field of #GstStructure. This field is used to determine whether a structure is mutable or not. This function should only be called by code implementing parent objects of #GstStructure, as described in the MT Refcounting section of the design documents. - + %TRUE if the parent refcount could be set. + line="673">%TRUE if the parent refcount could be set. a #GstStructure + line="665">a #GstStructure a pointer to the parent's refcount + line="666">a pointer to the parent's refcount + + Parses the variable arguments and sets fields accordingly. Fields that +weren't already part of the structure are added as needed. +Variable arguments should be in the form field name, field type +(as a GType), value(s). The last variable argument should be %NULL. + +@fieldname and all other field names needs to be valid for the remaining +lifetime of the process, e.g. has to be a static string. + + + + + + + a #GstStructure + + + + the name of the field to set + + + + variable arguments + + + + + + va_list form of gst_structure_set_static_str(). + +@fieldname and all other field names needs to be valid for the remaining +lifetime of the process, e.g. has to be a static string. + + + + + + + a #GstStructure + + + + the name of the field to set + + + + variable arguments + + + + va_list form of gst_structure_set(). - + line="1308">va_list form of gst_structure_set(). + @@ -63386,19 +66815,19 @@ the MT Refcounting section of the design documents. a #GstStructure + line="1310">a #GstStructure the name of the field to set + line="1311">the name of the field to set variable arguments + line="1312">variable arguments @@ -63406,10 +66835,10 @@ the MT Refcounting section of the design documents. Sets the field with the given name @field to @value. If the field + line="1016">Sets the field with the given name @field to @value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. - + @@ -63417,19 +66846,55 @@ value is replaced and freed. a #GstStructure + line="1018">a #GstStructure the name of the field to set + line="1019">the name of the field to set the new value of the field + line="1020">the new value of the field + + + + + + Sets the field with the given name @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. + +@fieldname needs to be valid for the remaining lifetime of the process, e.g. +has to be a static string. + + + + + + + a #GstStructure + + + + the name of the field to set + + + + the new value of the field @@ -63437,10 +66902,10 @@ value is replaced and freed. Sets the field with the given name @field to @value. If the field + line="1144">Sets the field with the given name @field to @value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. The function will take ownership of @value. - + @@ -63448,19 +66913,55 @@ value is replaced and freed. The function will take ownership of @value. a #GstStructure + line="1146">a #GstStructure the name of the field to set + line="1147">the name of the field to set the new value of the field + line="1148">the new value of the field + + + + + + Sets the field with the given name @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. The function will take ownership of @value. + +@fieldname needs to be valid for the remaining lifetime of the process, e.g. +has to be a static string. + + + + + + + a #GstStructure + + + + the name of the field to set + + + + the new value of the field @@ -63468,7 +66969,7 @@ value is replaced and freed. The function will take ownership of @value. Converts @structure to a human-readable string representation. + line="3188">Converts @structure to a human-readable string representation. For debugging purposes its easier to do something like this: |[<!-- language="C" --> GST_LOG ("structure is %" GST_PTR_FORMAT, structure); @@ -63477,14 +66978,14 @@ This prints the structure in human readable form. This function will lead to unexpected results when there are nested #GstCaps / #GstStructure deeper than one level, you should user -gst_structure_serialize() instead for those cases. +gst_structure_serialize_full() instead for those cases. Free-function: g_free - + a pointer to string allocated by g_malloc(). + line="3205">a pointer to string allocated by g_malloc(). g_free() after usage. @@ -63492,7 +66993,7 @@ Free-function: g_free a #GstStructure + line="3190">a #GstStructure @@ -63500,7 +67001,7 @@ Free-function: g_free Atomically modifies a pointer to point to a new structure. + line="800">Atomically modifies a pointer to point to a new structure. The #GstStructure @oldstr_ptr is pointing to is freed and @newstr is taken ownership over. @@ -63508,11 +67009,11 @@ Either @newstr and the value pointed to by @oldstr_ptr may be %NULL. It is a programming error if both @newstr and the value pointed to by @oldstr_ptr refer to the same, non-%NULL structure. - + %TRUE if @newstr was different from @oldstr_ptr + line="815">%TRUE if @newstr was different from @oldstr_ptr @@ -63524,7 +67025,7 @@ It is a programming error if both @newstr and the value pointed to by allow-none="1"> pointer to a place of + line="802">pointer to a place of a #GstStructure to take @@ -63534,7 +67035,7 @@ It is a programming error if both @newstr and the value pointed to by allow-none="1"> a new #GstStructure + line="804">a new #GstStructure @@ -63569,14 +67070,14 @@ It is a programming error if both @newstr and the value pointed to by A function that will be called in gst_structure_filter_and_map_in_place(). + line="101">A function that will be called in gst_structure_filter_and_map_in_place(). The function may modify @value, and the value will be removed from the structure if %FALSE is returned. - + %TRUE if the field should be preserved, %FALSE if it + line="111">%TRUE if the field should be preserved, %FALSE if it should be removed. @@ -63584,13 +67085,54 @@ should be removed. the #GQuark of the field name + line="103">the #GQuark of the field name the #GValue of the field + line="104">the #GValue of the field + + + + user data + + + + + + A function that will be called in gst_structure_filter_and_map_in_place_id_str(). +The function may modify @value, and the value will be removed from the +structure if %FALSE is returned. + + + %TRUE if the field should be preserved, %FALSE if it +should be removed. + + + + + the #GstIdStr field name + + + + the #GValue of the field closure="2"> user data + line="158">user data @@ -63608,13 +67150,13 @@ should be removed. A function that will be called in gst_structure_foreach(). The function may + line="69">A function that will be called in gst_structure_foreach(). The function may not modify @value. - + %TRUE if the foreach operation should continue, %FALSE if + line="78">%TRUE if the foreach operation should continue, %FALSE if the foreach operation should stop with %FALSE. @@ -63622,13 +67164,53 @@ the foreach operation should stop with %FALSE. the #GQuark of the field name + line="71">the #GQuark of the field name the #GValue of the field + line="72">the #GValue of the field + + + + user data + + + + + + A function that will be called in gst_structure_foreach_id_str(). The +function may not modify @value. + + + %TRUE if the foreach operation should continue, %FALSE if +the foreach operation should stop with %FALSE. + + + + + the #GstIdStr field name + + + + the #GValue of the field closure="2"> user data + line="122">user data @@ -63646,13 +67228,13 @@ the foreach operation should stop with %FALSE. A function that will be called in gst_structure_map_in_place(). The function + line="85">A function that will be called in gst_structure_map_in_place(). The function may modify @value. - + %TRUE if the map operation should continue, %FALSE if + line="94">%TRUE if the map operation should continue, %FALSE if the map operation should stop with %FALSE. @@ -63660,13 +67242,13 @@ the map operation should stop with %FALSE. the #GQuark of the field name + line="87">the #GQuark of the field name the #GValue of the field + line="88">the #GValue of the field closure="2"> user data + line="89">user data + + + + + + A function that will be called in gst_structure_map_in_place_id_str(). The +function may modify @value. + + + %TRUE if the map operation should continue, %FALSE if +the map operation should stop with %FALSE. + + + + + the #GstIdStr field name + + + + the #GValue of the field + + + + user data @@ -63703,14 +67325,14 @@ wait operations. Get a handle to the default system clock. The refcount of the + line="816">Get a handle to the default system clock. The refcount of the clock will be increased so you need to unref the clock after usage. the default clock. + line="823">the default clock. MT safe. @@ -63721,7 +67343,7 @@ MT safe. version="1.4"> Sets the default system clock that can be obtained with + line="777">Sets the default system clock that can be obtained with gst_system_clock_obtain(). This is mostly used for testing and debugging purposes when you @@ -63740,7 +67362,7 @@ MT safe. allow-none="1"> a #GstClock + line="779">a #GstClock @@ -63991,6 +67613,19 @@ attachment) + + Unique identifier for the audio, video or text track this tag is associated +with. The mappings for several container formats are defined in the [Sourcing +In-band Media Resource Tracks from Media Containers into HTML +specification](https://dev.w3.org/html5/html-sourcing-inband-tracks/). + + + @@ -64815,12 +68450,12 @@ The higher the value, the more the user likes this media introspectable="0"> printf format type used to debug GStreamer ClockTime pointers. You can use + line="306">printf format type used to debug GStreamer ClockTime pointers. You can use this in combination with GStreamer's debug logging system as well as the functions gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() to pretty-print #GstClockTime pointers. This can only be used on pointers to GstClockTime values. - + introspectable="0"> Converts a struct timespec (see `man pselect`) to a #GstClockTime. - + line="196">Converts a struct timespec (see `man pselect`) to a #GstClockTime. + the timespec to convert + line="198">the timespec to convert @@ -64858,14 +68493,14 @@ only be used on pointers to GstClockTime values. introspectable="0"> Formats @t for the #GST_TIME_FORMAT format string. Note: @t will be + line="236">Formats @t for the #GST_TIME_FORMAT format string. Note: @t will be evaluated more than once. - + a #GstClockTime + line="238">a #GstClockTime @@ -64935,7 +68570,7 @@ evaluated more than once. introspectable="0"> A string that can be used in printf-like format strings to display a + line="222">A string that can be used in printf-like format strings to display a #GstClockTime value in `h:m:s` format. Use GST_TIME_ARGS() to construct the matching arguments. @@ -64944,7 +68579,7 @@ Example: ``` C printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts)); ``` - + Converts a #GstClockTime to a struct timespec (see `man pselect`) - + line="203">Converts a #GstClockTime to a struct timespec (see `man pselect`) + The #GstClockTime to convert + line="205">The #GstClockTime to convert The target timespec + line="206">The target timespec @@ -64974,10 +68609,11 @@ printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts)); filename="gst/gstclock.h" line="171">Converts a #GstClockTime to a GTimeVal -> on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds, -> which is about 68 years. Expect trouble if you want to schedule stuff -> in your pipeline for 2038. - +> on many 32-bit systems, a timeval has a range of only 2^32 - 1 seconds, +> which is about 68 years. Expect trouble if you want to schedule stuff +> in your pipeline for 2038. This macro asserts that this case does not +> happen. + Output a tracing message in the default category. + line="1304">Output a tracing message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1306">printf-style message to output @@ -65178,21 +68814,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a tracing message for the given identifier in the default category. + line="1221">Output a tracing message for the given identifier in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1223">An identifier of the message provider printf-style message to output + line="1224">printf-style message to output @@ -65201,21 +68837,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a tracing message belonging to the given object in the default category. + line="1125">Output a tracing message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1127">the #GObject the message belongs to printf-style message to output + line="1128">printf-style message to output @@ -65485,7 +69121,7 @@ not allowed. Strings must not be empty or %NULL. introspectable="0"> Creates a new taglist and appends the values for the given tags. It expects + line="763">Creates a new taglist and appends the values for the given tags. It expects tag-value pairs like gst_tag_list_add(), and a %NULL terminator after the last pair. The type of the values is implicit and is documented in the API reference, but can also be queried at runtime with gst_tag_get_type(). It @@ -65502,7 +69138,7 @@ Free-function: gst_tag_list_unref a new #GstTagList. Free with gst_tag_list_unref() + line="782">a new #GstTagList. Free with gst_tag_list_unref() when no longer needed. @@ -65510,13 +69146,13 @@ Free-function: gst_tag_list_unref tag + line="765">tag %NULL-terminated list of values to set + line="766">%NULL-terminated list of values to set @@ -65524,14 +69160,14 @@ Free-function: gst_tag_list_unref Creates a new empty GstTagList. + line="743">Creates a new empty GstTagList. Free-function: gst_tag_list_unref An empty tag list + line="750">An empty tag list @@ -65539,12 +69175,12 @@ Free-function: gst_tag_list_unref c:identifier="gst_tag_list_new_from_string"> Deserializes a tag list. + line="879">Deserializes a tag list. a new #GstTagList, or %NULL in case of an + line="885">a new #GstTagList, or %NULL in case of an error. @@ -65552,7 +69188,7 @@ error. a string created with gst_tag_list_to_string() + line="881">a string created with gst_tag_list_to_string() @@ -65562,7 +69198,7 @@ error. introspectable="0"> Just like gst_tag_list_new(), only that it takes a va_list argument. + line="801">Just like gst_tag_list_new(), only that it takes a va_list argument. Useful mostly for language bindings. Free-function: gst_tag_list_unref @@ -65570,7 +69206,7 @@ Free-function: gst_tag_list_unref a new #GstTagList. Free with gst_tag_list_unref() + line="810">a new #GstTagList. Free with gst_tag_list_unref() when no longer needed. @@ -65578,7 +69214,7 @@ Free-function: gst_tag_list_unref tag / value pairs to set + line="803">tag / value pairs to set @@ -65586,7 +69222,7 @@ Free-function: gst_tag_list_unref Sets the values for the given tags using the specified mode. + line="1217">Sets the values for the given tags using the specified mode. @@ -65595,25 +69231,25 @@ Free-function: gst_tag_list_unref list to set tags in + line="1219">list to set tags in the mode to use + line="1220">the mode to use tag + line="1221">tag %NULL-terminated list of values to set + line="1222">%NULL-terminated list of values to set @@ -65623,7 +69259,7 @@ Free-function: gst_tag_list_unref introspectable="0"> Sets the values for the given tags using the specified mode. + line="1267">Sets the values for the given tags using the specified mode. @@ -65632,25 +69268,25 @@ Free-function: gst_tag_list_unref list to set tags in + line="1269">list to set tags in the mode to use + line="1270">the mode to use tag + line="1271">tag tag / value pairs to set + line="1272">tag / value pairs to set @@ -65660,7 +69296,7 @@ Free-function: gst_tag_list_unref introspectable="0"> Sets the GValues for the given tags using the specified mode. + line="1321">Sets the GValues for the given tags using the specified mode. @@ -65669,25 +69305,25 @@ Free-function: gst_tag_list_unref list to set tags in + line="1323">list to set tags in the mode to use + line="1324">the mode to use tag + line="1325">tag tag / GValue pairs to set + line="1326">tag / GValue pairs to set @@ -65695,7 +69331,7 @@ Free-function: gst_tag_list_unref Sets the GValue for a given tag using the specified mode. + line="1357">Sets the GValue for a given tag using the specified mode. @@ -65704,25 +69340,25 @@ Free-function: gst_tag_list_unref list to set tags in + line="1359">list to set tags in the mode to use + line="1360">the mode to use tag + line="1361">tag GValue for this tag + line="1362">GValue for this tag @@ -65732,7 +69368,7 @@ Free-function: gst_tag_list_unref introspectable="0"> Sets the GValues for the given tags using the specified mode. + line="1242">Sets the GValues for the given tags using the specified mode. @@ -65741,25 +69377,25 @@ Free-function: gst_tag_list_unref list to set tags in + line="1244">list to set tags in the mode to use + line="1245">the mode to use tag + line="1246">tag GValues to set + line="1247">GValues to set @@ -65767,7 +69403,7 @@ Free-function: gst_tag_list_unref Creates a new #GstTagList as a copy of the old @taglist. The new taglist + line="2069">Creates a new #GstTagList as a copy of the old @taglist. The new taglist will have a refcount of 1, owned by the caller, and will be writable as a result. @@ -65780,14 +69416,14 @@ When you are finished with the taglist, call gst_tag_list_unref() on it. the new #GstTagList + line="2083">the new #GstTagList a #GstTagList. + line="2071">a #GstTagList. @@ -65795,7 +69431,7 @@ When you are finished with the taglist, call gst_tag_list_unref() on it. Calls the given function for each tag inside the tag list. Note that if there + line="1413">Calls the given function for each tag inside the tag list. Note that if there is no tag, the function won't be called at all. @@ -65805,7 +69441,7 @@ is no tag, the function won't be called at all. list to iterate over + line="1415">list to iterate over closure="1"> function to be called for each tag + line="1416">function to be called for each tag allow-none="1"> user specified data + line="1417">user specified data @@ -65831,13 +69467,13 @@ is no tag, the function won't be called at all. Copies the contents for the given tag into the value, merging multiple values + line="1567">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1576">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -65845,13 +69481,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1569">a #GstTagList to get the tag from tag to read out + line="1570">tag to read out transfer-ownership="full"> location for the result + line="1571">location for the result @@ -65869,13 +69505,13 @@ into one if multiple values are associated with the tag. c:identifier="gst_tag_list_get_boolean_index"> Gets the value that is at the given index for the given tag in the given + line="1579">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1589">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -65883,19 +69519,19 @@ list. a #GstTagList to get the tag from + line="1581">a #GstTagList to get the tag from tag to read out + line="1582">tag to read out number of entry to read out + line="1583">number of entry to read out transfer-ownership="full"> location for the result + line="1584">location for the result @@ -65912,7 +69548,7 @@ list. Copies the first date for the given tag in the taglist into the variable + line="1868">Copies the first date for the given tag in the taglist into the variable pointed to by @value. Free the date with g_date_free() when it is no longer needed. @@ -65921,7 +69557,7 @@ Free-function: g_date_free %TRUE, if a date was copied, %FALSE if the tag didn't exist in the + line="1881">%TRUE, if a date was copied, %FALSE if the tag didn't exist in the given list or if it was %NULL. @@ -65929,13 +69565,13 @@ Free-function: g_date_free a #GstTagList to get the tag from + line="1870">a #GstTagList to get the tag from tag to read out + line="1871">tag to read out transfer-ownership="full"> address of a GDate pointer + line="1872">address of a GDate pointer variable to store the result into @@ -65953,7 +69589,7 @@ Free-function: g_date_free Gets the date that is at the given index for the given tag in the given + line="1901">Gets the date that is at the given index for the given tag in the given list and copies it into the variable pointed to by @value. Free the date with g_date_free() when it is no longer needed. @@ -65962,7 +69598,7 @@ Free-function: g_date_free %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1914">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list or if it was %NULL. @@ -65970,19 +69606,19 @@ Free-function: g_date_free a #GstTagList to get the tag from + line="1903">a #GstTagList to get the tag from tag to read out + line="1904">tag to read out number of entry to read out + line="1905">number of entry to read out transfer-ownership="full"> location for the result + line="1906">location for the result @@ -65999,7 +69635,7 @@ Free-function: g_date_free Copies the first datetime for the given tag in the taglist into the variable + line="1933">Copies the first datetime for the given tag in the taglist into the variable pointed to by @value. Unref the date with gst_date_time_unref() when it is no longer needed. @@ -66008,7 +69644,7 @@ Free-function: gst_date_time_unref %TRUE, if a datetime was copied, %FALSE if the tag didn't exist in + line="1946">%TRUE, if a datetime was copied, %FALSE if the tag didn't exist in the given list or if it was %NULL. @@ -66016,13 +69652,13 @@ Free-function: gst_date_time_unref a #GstTagList to get the tag from + line="1935">a #GstTagList to get the tag from tag to read out + line="1936">tag to read out transfer-ownership="full"> address of a #GstDateTime + line="1937">address of a #GstDateTime pointer variable to store the result into @@ -66041,7 +69677,7 @@ Free-function: gst_date_time_unref c:identifier="gst_tag_list_get_date_time_index"> Gets the datetime that is at the given index for the given tag in the given + line="1967">Gets the datetime that is at the given index for the given tag in the given list and copies it into the variable pointed to by @value. Unref the datetime with gst_date_time_unref() when it is no longer needed. @@ -66050,7 +69686,7 @@ Free-function: gst_date_time_unref %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1980">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list or if it was %NULL. @@ -66058,19 +69694,19 @@ Free-function: gst_date_time_unref a #GstTagList to get the tag from + line="1969">a #GstTagList to get the tag from tag to read out + line="1970">tag to read out number of entry to read out + line="1971">number of entry to read out transfer-ownership="full"> location for the result + line="1972">location for the result @@ -66087,13 +69723,13 @@ Free-function: gst_date_time_unref Copies the contents for the given tag into the value, merging multiple values + line="1723">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1732">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66101,13 +69737,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1725">a #GstTagList to get the tag from tag to read out + line="1726">tag to read out transfer-ownership="full"> location for the result + line="1727">location for the result @@ -66125,13 +69761,13 @@ into one if multiple values are associated with the tag. c:identifier="gst_tag_list_get_double_index"> Gets the value that is at the given index for the given tag in the given + line="1735">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1745">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66139,19 +69775,19 @@ list. a #GstTagList to get the tag from + line="1737">a #GstTagList to get the tag from tag to read out + line="1738">tag to read out number of entry to read out + line="1739">number of entry to read out transfer-ownership="full"> location for the result + line="1740">location for the result @@ -66168,13 +69804,13 @@ list. Copies the contents for the given tag into the value, merging multiple values + line="1697">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1706">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66182,13 +69818,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1699">a #GstTagList to get the tag from tag to read out + line="1700">tag to read out transfer-ownership="full"> location for the result + line="1701">location for the result @@ -66206,13 +69842,13 @@ into one if multiple values are associated with the tag. c:identifier="gst_tag_list_get_float_index"> Gets the value that is at the given index for the given tag in the given + line="1709">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1719">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66220,19 +69856,19 @@ list. a #GstTagList to get the tag from + line="1711">a #GstTagList to get the tag from tag to read out + line="1712">tag to read out number of entry to read out + line="1713">number of entry to read out transfer-ownership="full"> location for the result + line="1714">location for the result @@ -66249,13 +69885,13 @@ list. Copies the contents for the given tag into the value, merging multiple values + line="1593">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1602">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66263,13 +69899,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1595">a #GstTagList to get the tag from tag to read out + line="1596">tag to read out transfer-ownership="full"> location for the result + line="1597">location for the result @@ -66286,13 +69922,13 @@ into one if multiple values are associated with the tag. Copies the contents for the given tag into the value, merging multiple values + line="1645">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1654">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66300,13 +69936,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1647">a #GstTagList to get the tag from tag to read out + line="1648">tag to read out transfer-ownership="full"> location for the result + line="1649">location for the result @@ -66324,13 +69960,13 @@ into one if multiple values are associated with the tag. c:identifier="gst_tag_list_get_int64_index"> Gets the value that is at the given index for the given tag in the given + line="1657">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1667">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66338,19 +69974,19 @@ list. a #GstTagList to get the tag from + line="1659">a #GstTagList to get the tag from tag to read out + line="1660">tag to read out number of entry to read out + line="1661">number of entry to read out transfer-ownership="full"> location for the result + line="1662">location for the result @@ -66367,13 +70003,13 @@ list. Gets the value that is at the given index for the given tag in the given + line="1605">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1615">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66381,19 +70017,19 @@ list. a #GstTagList to get the tag from + line="1607">a #GstTagList to get the tag from tag to read out + line="1608">tag to read out number of entry to read out + line="1609">number of entry to read out transfer-ownership="full"> location for the result + line="1610">location for the result @@ -66410,13 +70046,13 @@ list. Copies the contents for the given tag into the value, merging multiple values + line="1749">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1758">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66424,13 +70060,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1751">a #GstTagList to get the tag from tag to read out + line="1752">tag to read out nullable="1"> location for the result + line="1753">location for the result @@ -66449,13 +70085,13 @@ into one if multiple values are associated with the tag. c:identifier="gst_tag_list_get_pointer_index"> Gets the value that is at the given index for the given tag in the given + line="1761">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1771">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66463,19 +70099,19 @@ list. a #GstTagList to get the tag from + line="1763">a #GstTagList to get the tag from tag to read out + line="1764">tag to read out number of entry to read out + line="1765">number of entry to read out nullable="1"> location for the result + line="1766">location for the result @@ -66493,7 +70129,7 @@ list. Copies the first sample for the given tag in the taglist into the variable + line="1999">Copies the first sample for the given tag in the taglist into the variable pointed to by @sample. Free the sample with gst_sample_unref() when it is no longer needed. You can retrieve the buffer from the sample using gst_sample_get_buffer() and the associated caps (if any) with @@ -66504,7 +70140,7 @@ Free-function: gst_sample_unref %TRUE, if a sample was returned, %FALSE if the tag didn't exist in + line="2014">%TRUE, if a sample was returned, %FALSE if the tag didn't exist in the given list or if it was %NULL. @@ -66512,13 +70148,13 @@ Free-function: gst_sample_unref a #GstTagList to get the tag from + line="2001">a #GstTagList to get the tag from tag to read out + line="2002">tag to read out transfer-ownership="full"> address of a GstSample + line="2003">address of a GstSample pointer variable to store the result into @@ -66537,7 +70173,7 @@ Free-function: gst_sample_unref c:identifier="gst_tag_list_get_sample_index"> Gets the sample that is at the given index for the given tag in the given + line="2034">Gets the sample that is at the given index for the given tag in the given list and copies it into the variable pointed to by @sample. Free the sample with gst_sample_unref() when it is no longer needed. You can retrieve the buffer from the sample using gst_sample_get_buffer() and the associated @@ -66548,7 +70184,7 @@ Free-function: gst_sample_unref %TRUE, if a sample was copied, %FALSE if the tag didn't exist in the + line="2050">%TRUE, if a sample was copied, %FALSE if the tag didn't exist in the given list or if it was %NULL. @@ -66556,19 +70192,19 @@ Free-function: gst_sample_unref a #GstTagList to get the tag from + line="2036">a #GstTagList to get the tag from tag to read out + line="2037">tag to read out number of entry to read out + line="2038">number of entry to read out transfer-ownership="full"> address of a GstSample + line="2039">address of a GstSample pointer variable to store the result into @@ -66586,19 +70222,19 @@ Free-function: gst_sample_unref Gets the scope of @list. + line="845">Gets the scope of @list. The scope of @list + line="851">The scope of @list a #GstTagList + line="847">a #GstTagList @@ -66606,7 +70242,7 @@ Free-function: gst_sample_unref Copies the contents for the given tag into the value, possibly merging + line="1788">Copies the contents for the given tag into the value, possibly merging multiple values into one if multiple values are associated with the tag. Use gst_tag_list_get_string_index (list, tag, 0, value) if you want @@ -66621,7 +70257,7 @@ Free-function: g_free %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1806">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66629,13 +70265,13 @@ Free-function: g_free a #GstTagList to get the tag from + line="1790">a #GstTagList to get the tag from tag to read out + line="1791">tag to read out transfer-ownership="full"> location for the result + line="1792">location for the result @@ -66653,7 +70289,7 @@ Free-function: g_free c:identifier="gst_tag_list_get_string_index"> Gets the value that is at the given index for the given tag in the given + line="1809">Gets the value that is at the given index for the given tag in the given list. The resulting string in @value will be in UTF-8 encoding and should be @@ -66665,7 +70301,7 @@ Free-function: g_free %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1825">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66673,19 +70309,19 @@ Free-function: g_free a #GstTagList to get the tag from + line="1811">a #GstTagList to get the tag from tag to read out + line="1812">tag to read out number of entry to read out + line="1813">number of entry to read out transfer-ownership="full"> location for the result + line="1814">location for the result @@ -66702,25 +70338,25 @@ Free-function: g_free Checks how many value are stored in this tag list for the given tag. + line="1192">Checks how many value are stored in this tag list for the given tag. The number of tags stored + line="1199">The number of tags stored a taglist + line="1194">a taglist the tag to query + line="1195">the tag to query @@ -66728,13 +70364,13 @@ Free-function: g_free Copies the contents for the given tag into the value, merging multiple values + line="1619">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1628">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66742,13 +70378,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1621">a #GstTagList to get the tag from tag to read out + line="1622">tag to read out transfer-ownership="full"> location for the result + line="1623">location for the result @@ -66765,13 +70401,13 @@ into one if multiple values are associated with the tag. Copies the contents for the given tag into the value, merging multiple values + line="1671">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1680">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66779,13 +70415,13 @@ into one if multiple values are associated with the tag. a #GstTagList to get the tag from + line="1673">a #GstTagList to get the tag from tag to read out + line="1674">tag to read out transfer-ownership="full"> location for the result + line="1675">location for the result @@ -66803,13 +70439,13 @@ into one if multiple values are associated with the tag. c:identifier="gst_tag_list_get_uint64_index"> Gets the value that is at the given index for the given tag in the given + line="1683">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1693">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66817,19 +70453,19 @@ list. a #GstTagList to get the tag from + line="1685">a #GstTagList to get the tag from tag to read out + line="1686">tag to read out number of entry to read out + line="1687">number of entry to read out transfer-ownership="full"> location for the result + line="1688">location for the result @@ -66846,13 +70482,13 @@ list. Gets the value that is at the given index for the given tag in the given + line="1631">Gets the value that is at the given index for the given tag in the given list. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1641">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -66860,19 +70496,19 @@ list. a #GstTagList to get the tag from + line="1633">a #GstTagList to get the tag from tag to read out + line="1634">tag to read out number of entry to read out + line="1635">number of entry to read out transfer-ownership="full"> location for the result + line="1636">location for the result @@ -66890,13 +70526,13 @@ list. c:identifier="gst_tag_list_get_value_index"> Gets the value that is at the given index for the given tag in the given + line="1438">Gets the value that is at the given index for the given tag in the given list. The GValue for the specified + line="1447">The GValue for the specified entry or %NULL if the tag wasn't available or the tag doesn't have as many entries @@ -66905,19 +70541,19 @@ list. a #GstTagList + line="1440">a #GstTagList tag to read out + line="1441">tag to read out number of entry to read out + line="1442">number of entry to read out @@ -66925,7 +70561,7 @@ list. Inserts the tags of the @from list into the first list using the given mode. + line="1123">Inserts the tags of the @from list into the first list using the given mode. @@ -66934,19 +70570,19 @@ list. list to merge into + line="1125">list to merge into list to merge from + line="1126">list to merge from the mode to use + line="1127">the mode to use @@ -66954,19 +70590,19 @@ list. Checks if the given taglist is empty. + line="941">Checks if the given taglist is empty. %TRUE if the taglist is empty, otherwise %FALSE. + line="947">%TRUE if the taglist is empty, otherwise %FALSE. A #GstTagList. + line="943">A #GstTagList. @@ -66974,25 +70610,25 @@ list. Checks if the two given taglists are equal. + line="990">Checks if the two given taglists are equal. %TRUE if the taglists are equal, otherwise %FALSE + line="997">%TRUE if the taglists are equal, otherwise %FALSE a #GstTagList. + line="992">a #GstTagList. a #GstTagList. + line="993">a #GstTagList. @@ -67000,7 +70636,7 @@ list. Merges the two given lists into a new list. If one of the lists is %NULL, a + line="1151">Merges the two given lists into a new list. If one of the lists is %NULL, a copy of the other is returned. If both lists are %NULL, %NULL is returned. Free-function: gst_tag_list_unref @@ -67008,7 +70644,7 @@ Free-function: gst_tag_list_unref the new list + line="1162">the new list @@ -67018,7 +70654,7 @@ Free-function: gst_tag_list_unref allow-none="1"> first list to merge + line="1153">first list to merge allow-none="1"> second list to merge + line="1154">second list to merge the mode to use + line="1155">the mode to use @@ -67041,19 +70677,19 @@ Free-function: gst_tag_list_unref Get the number of tags in @list. + line="906">Get the number of tags in @list. The number of tags in @list. + line="912">The number of tags in @list. A #GstTagList. + line="908">A #GstTagList. @@ -67061,25 +70697,25 @@ Free-function: gst_tag_list_unref Get the name of the tag in @list at @index. + line="923">Get the name of the tag in @list at @index. The name of the tag at @index. + line="930">The name of the tag at @index. A #GstTagList. + line="925">A #GstTagList. the index + line="926">the index @@ -67088,7 +70724,7 @@ Free-function: gst_tag_list_unref c:identifier="gst_tag_list_peek_string_index"> Peeks at the value that is at the given index for the given tag in the given + line="1835">Peeks at the value that is at the given index for the given tag in the given list. The resulting string in @value will be in UTF-8 encoding and doesn't need @@ -67098,7 +70734,7 @@ be non-%NULL and non-empty. %TRUE, if a value was set, %FALSE if the tag didn't exist in the + line="1849">%TRUE, if a value was set, %FALSE if the tag didn't exist in the given list. @@ -67106,19 +70742,19 @@ be non-%NULL and non-empty. a #GstTagList to get the tag from + line="1837">a #GstTagList to get the tag from tag to read out + line="1838">tag to read out number of entry to read out + line="1839">number of entry to read out transfer-ownership="none"> location for the result + line="1840">location for the result @@ -67135,7 +70771,7 @@ be non-%NULL and non-empty. Removes the given tag from the taglist. + line="1378">Removes the given tag from the taglist. @@ -67144,13 +70780,13 @@ be non-%NULL and non-empty. list to remove tag from + line="1380">list to remove tag from tag to remove + line="1381">tag to remove @@ -67158,7 +70794,7 @@ be non-%NULL and non-empty. Sets the scope of @list to @scope. By default the scope + line="827">Sets the scope of @list to @scope. By default the scope of a taglist is stream scope. @@ -67168,13 +70804,13 @@ of a taglist is stream scope. a #GstTagList + line="829">a #GstTagList new scope for @list + line="830">new scope for @list @@ -67182,12 +70818,12 @@ of a taglist is stream scope. Serializes a tag list to a string. + line="861">Serializes a tag list to a string. a newly-allocated string. + line="867">a newly-allocated string. The string must be freed with g_free() when no longer needed. @@ -67196,7 +70832,7 @@ of a taglist is stream scope. a #GstTagList + line="863">a #GstTagList @@ -67204,7 +70840,7 @@ of a taglist is stream scope. Copies the contents for the given tag into the value, + line="1475">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. You must g_value_unset() the value after use. @@ -67212,7 +70848,7 @@ You must g_value_unset() the value after use. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1486">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -67223,19 +70859,19 @@ You must g_value_unset() the value after use. transfer-ownership="none"> uninitialized #GValue to copy into + line="1477">uninitialized #GValue to copy into list to get the tag from + line="1478">list to get the tag from tag to read out + line="1479">tag to read out @@ -67810,7 +71446,7 @@ no effect on the thread name. Create a new Task that will repeatedly call the provided @func + line="466">Create a new Task that will repeatedly call the provided @func with @user_data as a parameter. Typically the task will run in a new thread. @@ -67827,7 +71463,7 @@ gst_task_set_lock() function. This lock will always be acquired while A new #GstTask. + line="486">A new #GstTask. MT safe. @@ -67840,7 +71476,7 @@ MT safe. destroy="2"> The #GstTaskFunction to use + line="468">The #GstTaskFunction to use allow-none="1"> User data to pass to @func + line="469">User data to pass to @func the function to call when @user_data is no longer needed. + line="470">the function to call when @user_data is no longer needed. @@ -67863,7 +71499,7 @@ MT safe. Wait for all tasks to be stopped. This is mainly used internally + line="438">Wait for all tasks to be stopped. This is mainly used internally to ensure proper cleanup of internal data structures in test suites. MT safe. @@ -67875,7 +71511,7 @@ MT safe. Get the #GstTaskPool that this task will use for its streaming + line="545">Get the #GstTaskPool that this task will use for its streaming threads. MT safe. @@ -67883,7 +71519,7 @@ MT safe. the #GstTaskPool used by @task. gst_object_unref() + line="554">the #GstTaskPool used by @task. gst_object_unref() after usage. @@ -67891,7 +71527,7 @@ after usage. a #GstTask + line="547">a #GstTask @@ -67899,12 +71535,12 @@ after usage. Get the current state of the task. + line="683">Get the current state of the task. The #GstTaskState of the task + line="689">The #GstTaskState of the task MT safe. @@ -67913,7 +71549,7 @@ MT safe. The #GstTask to query + line="685">The #GstTask to query @@ -67921,7 +71557,7 @@ MT safe. Joins @task. After this call, it is safe to unref the task + line="896">Joins @task. After this call, it is safe to unref the task and clean up the lock set with gst_task_set_lock(). The task will automatically be stopped with this call. @@ -67933,7 +71569,7 @@ g_warning. %TRUE if the task could be joined. + line="909">%TRUE if the task could be joined. MT safe. @@ -67942,7 +71578,7 @@ MT safe. The #GstTask to join + line="898">The #GstTask to join @@ -67950,7 +71586,7 @@ MT safe. Pauses @task. This method can also be called on a task in the + line="851">Pauses @task. This method can also be called on a task in the stopped state, in which case a thread will be started and will remain in the paused state. This function does not wait for the task to complete the paused state. @@ -67958,7 +71594,7 @@ the paused state. %TRUE if the task could be paused. + line="860">%TRUE if the task could be paused. MT safe. @@ -67967,7 +71603,7 @@ MT safe. The #GstTask to pause + line="853">The #GstTask to pause @@ -67975,13 +71611,13 @@ MT safe. Resume @task in case it was paused. If the task was stopped, it will + line="870">Resume @task in case it was paused. If the task was stopped, it will remain in that state and this function will return %FALSE. %TRUE if the task could be resumed. + line="877">%TRUE if the task could be resumed. MT safe. @@ -67990,7 +71626,7 @@ MT safe. The #GstTask to resume + line="872">The #GstTask to resume @@ -67999,7 +71635,7 @@ MT safe. c:identifier="gst_task_set_enter_callback"> Call @enter_func when the task function of @task is entered. @user_data will + line="607">Call @enter_func when the task function of @task is entered. @user_data will be passed to @enter_func and @notify will be called when @user_data is no longer referenced. @@ -68010,7 +71646,7 @@ longer referenced. The #GstTask to use + line="609">The #GstTask to use destroy="2"> a #GstTaskThreadFunc + line="610">a #GstTaskThreadFunc allow-none="1"> user data passed to @enter_func + line="611">user data passed to @enter_func called when @user_data is no longer referenced + line="612">called when @user_data is no longer referenced @@ -68044,7 +71680,7 @@ longer referenced. c:identifier="gst_task_set_leave_callback"> Call @leave_func when the task function of @task is left. @user_data will + line="645">Call @leave_func when the task function of @task is left. @user_data will be passed to @leave_func and @notify will be called when @user_data is no longer referenced. @@ -68055,7 +71691,7 @@ longer referenced. The #GstTask to use + line="647">The #GstTask to use destroy="2"> a #GstTaskThreadFunc + line="648">a #GstTaskThreadFunc allow-none="1"> user data passed to @leave_func + line="649">user data passed to @leave_func called when @user_data is no longer referenced + line="650">called when @user_data is no longer referenced @@ -68088,7 +71724,7 @@ longer referenced. Set the mutex used by the task. The mutex will be acquired before + line="510">Set the mutex used by the task. The mutex will be acquired before calling the #GstTaskFunction. This function has to be called before calling gst_task_pause() or @@ -68103,13 +71739,13 @@ MT safe. The #GstTask to use + line="512">The #GstTask to use The #GRecMutex to use + line="513">The #GRecMutex to use @@ -68117,7 +71753,7 @@ MT safe. Set @pool as the new GstTaskPool for @task. Any new streaming threads that + line="574">Set @pool as the new GstTaskPool for @task. Any new streaming threads that will be created by @task will now use @pool. MT safe. @@ -68129,13 +71765,13 @@ MT safe. a #GstTask + line="576">a #GstTask a #GstTaskPool + line="577">a #GstTaskPool @@ -68143,7 +71779,7 @@ MT safe. Sets the state of @task to @state. + line="787">Sets the state of @task to @state. The @task must have a lock associated with it using gst_task_set_lock() when going to GST_TASK_STARTED or GST_TASK_PAUSED or @@ -68154,20 +71790,20 @@ MT safe. %TRUE if the state could be changed. + line="800">%TRUE if the state could be changed. a #GstTask + line="789">a #GstTask the new task state + line="790">the new task state @@ -68175,13 +71811,13 @@ MT safe. Starts @task. The @task must have a lock associated with it using + line="816">Starts @task. The @task must have a lock associated with it using gst_task_set_lock() or this function will return %FALSE. %TRUE if the task could be started. + line="823">%TRUE if the task could be started. MT safe. @@ -68190,7 +71826,7 @@ MT safe. The #GstTask to start + line="818">The #GstTask to start @@ -68198,14 +71834,14 @@ MT safe. Stops @task. This method merely schedules the task to stop and + line="833">Stops @task. This method merely schedules the task to stop and will not wait for the task to have completely stopped. Use gst_task_join() to stop and wait for completion. %TRUE if the task could be stopped. + line="841">%TRUE if the task could be stopped. MT safe. @@ -68214,7 +71850,7 @@ MT safe. The #GstTask to stop + line="835">The #GstTask to stop @@ -68331,20 +71967,20 @@ Subclasses can be made to create custom threads. Create a new default task pool. The default task pool will use a regular + line="168">Create a new default task pool. The default task pool will use a regular GThreadPool for threads. a new #GstTaskPool. gst_object_unref() after usage. + line="174">a new #GstTaskPool. gst_object_unref() after usage. Wait for all tasks to be stopped. This is mainly used internally + line="211">Wait for all tasks to be stopped. This is mainly used internally to ensure proper cleanup of internal data structures in test suites. MT safe. @@ -68356,7 +71992,7 @@ MT safe. a #GstTaskPool + line="213">a #GstTaskPool @@ -68366,7 +72002,7 @@ MT safe. version="1.20"> Dispose of the handle returned by gst_task_pool_push(). This does + line="296">Dispose of the handle returned by gst_task_pool_push(). This does not need to be called with the default implementation as the default #GstTaskPoolClass::push implementation always returns %NULL. This does not need to be called either when calling gst_task_pool_join(), but should be called @@ -68383,7 +72019,7 @@ This method should only be called with the same @pool instance that provided a #GstTaskPool + line="298">a #GstTaskPool the id + line="299">the id @@ -68400,7 +72036,7 @@ This method should only be called with the same @pool instance that provided Join a task and/or return it to the pool. @id is the id obtained from + line="271">Join a task and/or return it to the pool. @id is the id obtained from gst_task_pool_push(). The default implementation does nothing, as the default #GstTaskPoolClass::push implementation always returns %NULL. @@ -68414,7 +72050,7 @@ This method should only be called with the same @pool instance that provided a #GstTaskPool + line="273">a #GstTaskPool the id + line="274">the id @@ -68431,7 +72067,7 @@ This method should only be called with the same @pool instance that provided Prepare the taskpool for accepting gst_task_pool_push() operations. + line="189">Prepare the taskpool for accepting gst_task_pool_push() operations. MT safe. @@ -68442,7 +72078,7 @@ MT safe. a #GstTaskPool + line="191">a #GstTaskPool @@ -68450,12 +72086,12 @@ MT safe. Start the execution of a new thread from @pool. + line="233">Start the execution of a new thread from @pool. a pointer that should be used + line="242">a pointer that should be used for the gst_task_pool_join function. This pointer can be %NULL, you must check @error to detect errors. If the pointer is not %NULL and gst_task_pool_join() is not used, call gst_task_pool_dispose_handle() @@ -68466,7 +72102,7 @@ instead. a #GstTaskPool + line="235">a #GstTaskPool closure="1"> the function to call + line="236">the function to call closure="1"> data to pass to @func + line="237">data to pass to @func @@ -68493,7 +72129,7 @@ instead. Wait for all tasks to be stopped. This is mainly used internally + line="211">Wait for all tasks to be stopped. This is mainly used internally to ensure proper cleanup of internal data structures in test suites. MT safe. @@ -68505,7 +72141,7 @@ MT safe. a #GstTaskPool + line="213">a #GstTaskPool @@ -68515,7 +72151,7 @@ MT safe. version="1.20"> Dispose of the handle returned by gst_task_pool_push(). This does + line="296">Dispose of the handle returned by gst_task_pool_push(). This does not need to be called with the default implementation as the default #GstTaskPoolClass::push implementation always returns %NULL. This does not need to be called either when calling gst_task_pool_join(), but should be called @@ -68532,7 +72168,7 @@ This method should only be called with the same @pool instance that provided a #GstTaskPool + line="298">a #GstTaskPool the id + line="299">the id @@ -68549,7 +72185,7 @@ This method should only be called with the same @pool instance that provided Join a task and/or return it to the pool. @id is the id obtained from + line="271">Join a task and/or return it to the pool. @id is the id obtained from gst_task_pool_push(). The default implementation does nothing, as the default #GstTaskPoolClass::push implementation always returns %NULL. @@ -68563,7 +72199,7 @@ This method should only be called with the same @pool instance that provided a #GstTaskPool + line="273">a #GstTaskPool the id + line="274">the id @@ -68580,7 +72216,7 @@ This method should only be called with the same @pool instance that provided Prepare the taskpool for accepting gst_task_pool_push() operations. + line="189">Prepare the taskpool for accepting gst_task_pool_push() operations. MT safe. @@ -68591,7 +72227,7 @@ MT safe. a #GstTaskPool + line="191">a #GstTaskPool @@ -68599,12 +72235,12 @@ MT safe. Start the execution of a new thread from @pool. + line="233">Start the execution of a new thread from @pool. a pointer that should be used + line="242">a pointer that should be used for the gst_task_pool_join function. This pointer can be %NULL, you must check @error to detect errors. If the pointer is not %NULL and gst_task_pool_join() is not used, call gst_task_pool_dispose_handle() @@ -68615,7 +72251,7 @@ instead. a #GstTaskPool + line="235">a #GstTaskPool closure="1"> the function to call + line="236">the function to call allow-none="1"> data to pass to @func + line="237">data to pass to @func @@ -68664,6 +72300,9 @@ instead. + prepare the threadpool @@ -68673,13 +72312,16 @@ instead. a #GstTaskPool + line="191">a #GstTaskPool + make sure all threads are stopped @@ -68689,19 +72331,22 @@ instead. a #GstTaskPool + line="213">a #GstTaskPool + start a new thread a pointer that should be used + line="242">a pointer that should be used for the gst_task_pool_join function. This pointer can be %NULL, you must check @error to detect errors. If the pointer is not %NULL and gst_task_pool_join() is not used, call gst_task_pool_dispose_handle() @@ -68712,7 +72357,7 @@ instead. a #GstTaskPool + line="235">a #GstTaskPool closure="2"> the function to call + line="236">the function to call closure="2"> data to pass to @func + line="237">data to pass to @func + join a thread @@ -68747,7 +72395,7 @@ instead. a #GstTaskPool + line="273">a #GstTaskPool allow-none="1"> the id + line="274">the id @@ -68772,7 +72420,7 @@ instead. a #GstTaskPool + line="298">a #GstTaskPool allow-none="1"> the id + line="299">the id @@ -68963,12 +72611,12 @@ a track listing from different sources). Create a new #GstToc structure. + line="125">Create a new #GstToc structure. newly allocated #GstToc structure, free it + line="131">newly allocated #GstToc structure, free it with gst_toc_unref(). @@ -68976,7 +72624,7 @@ a track listing from different sources). scope of this TOC + line="127">scope of this TOC @@ -68984,7 +72632,7 @@ a track listing from different sources). Appends the #GstTocEntry @entry to @toc. + line="225">Appends the #GstTocEntry @entry to @toc. @@ -68993,13 +72641,13 @@ a track listing from different sources). A #GstToc instance + line="227">A #GstToc instance A #GstTocEntry + line="228">A #GstTocEntry @@ -69018,12 +72666,12 @@ a track listing from different sources). Find #GstTocEntry with given @uid in the @toc. + line="364">Find #GstTocEntry with given @uid in the @toc. #GstTocEntry with specified + line="371">#GstTocEntry with specified @uid from the @toc, or %NULL if not found. @@ -69031,13 +72679,13 @@ a track listing from different sources). #GstToc to search in. + line="366">#GstToc to search in. UID to find #GstTocEntry with. + line="367">UID to find #GstTocEntry with. @@ -69045,12 +72693,12 @@ a track listing from different sources). Gets the list of #GstTocEntry of @toc. + line="250">Gets the list of #GstTocEntry of @toc. A #GList of #GstTocEntry for @entry + line="256">A #GList of #GstTocEntry for @entry @@ -69059,7 +72707,7 @@ a track listing from different sources). A #GstToc instance + line="252">A #GstToc instance @@ -69069,14 +72717,14 @@ a track listing from different sources). scope of @toc + line="158">scope of @toc a #GstToc instance + line="156">a #GstToc instance @@ -69084,19 +72732,19 @@ a track listing from different sources). Gets the tags for @toc. + line="209">Gets the tags for @toc. A #GstTagList for @entry + line="215">A #GstTagList for @entry A #GstToc instance + line="211">A #GstToc instance @@ -69104,7 +72752,7 @@ a track listing from different sources). Merge @tags into the existing tags of @toc using @mode. + line="186">Merge @tags into the existing tags of @toc using @mode. @@ -69113,7 +72761,7 @@ a track listing from different sources). A #GstToc instance + line="188">A #GstToc instance allow-none="1"> A #GstTagList or %NULL + line="189">A #GstTagList or %NULL A #GstTagMergeMode + line="190">A #GstTagMergeMode @@ -69136,7 +72784,7 @@ a track listing from different sources). Set a #GstTagList with tags for the complete @toc. + line="168">Set a #GstTagList with tags for the complete @toc. @@ -69145,7 +72793,7 @@ a track listing from different sources). A #GstToc instance + line="170">A #GstToc instance allow-none="1"> A #GstTagList or %NULL + line="171">A #GstTagList or %NULL @@ -69170,25 +72818,25 @@ a track listing from different sources). Create new #GstTocEntry structure. + line="285">Create new #GstTocEntry structure. newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref(). + line="292">newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref(). entry type. + line="287">entry type. unique ID (UID) in the whole TOC. + line="288">unique ID (UID) in the whole TOC. @@ -69197,7 +72845,7 @@ a track listing from different sources). c:identifier="gst_toc_entry_append_sub_entry"> Appends the #GstTocEntry @subentry to @entry. + line="663">Appends the #GstTocEntry @subentry to @entry. @@ -69206,13 +72854,13 @@ a track listing from different sources). A #GstTocEntry instance + line="665">A #GstTocEntry instance A #GstTocEntry + line="666">A #GstTocEntry @@ -69223,14 +72871,14 @@ a track listing from different sources). @entry's entry type + line="609">@entry's entry type a #GstTocEntry + line="607">a #GstTocEntry @@ -69240,7 +72888,7 @@ a track listing from different sources). version="1.4"> Get @loop_type and @repeat_count values from the @entry and write them into + line="540">Get @loop_type and @repeat_count values from the @entry and write them into appropriate storages. Loops are e.g. used by sampled instruments. GStreamer is not automatically applying the loop. The application can process this meta data and use it e.g. to send a seek-event to loop a section. @@ -69248,7 +72896,7 @@ meta data and use it e.g. to send a seek-event to loop a section. %TRUE if all non-%NULL storage pointers were filled with appropriate + line="553">%TRUE if all non-%NULL storage pointers were filled with appropriate values, %FALSE otherwise. @@ -69256,7 +72904,7 @@ values, %FALSE otherwise. #GstTocEntry to get values from. + line="542">#GstTocEntry to get values from. allow-none="1"> the storage for the loop_type + line="543">the storage for the loop_type value, leave %NULL if not need. @@ -69279,7 +72927,7 @@ values, %FALSE otherwise. allow-none="1"> the storage for the repeat_count + line="545">the storage for the repeat_count value, leave %NULL if not need. @@ -69288,19 +72936,19 @@ values, %FALSE otherwise. Gets the parent #GstTocEntry of @entry. + line="779">Gets the parent #GstTocEntry of @entry. The parent #GstTocEntry of @entry + line="785">The parent #GstTocEntry of @entry A #GstTocEntry instance + line="781">A #GstTocEntry instance @@ -69309,13 +72957,13 @@ values, %FALSE otherwise. c:identifier="gst_toc_entry_get_start_stop_times"> Get @start and @stop values from the @entry and write them into appropriate + line="492">Get @start and @stop values from the @entry and write them into appropriate storages. %TRUE if all non-%NULL storage pointers were filled with appropriate + line="503">%TRUE if all non-%NULL storage pointers were filled with appropriate values, %FALSE otherwise. @@ -69323,7 +72971,7 @@ values, %FALSE otherwise. #GstTocEntry to get values from. + line="494">#GstTocEntry to get values from. allow-none="1"> the storage for the start value, leave + line="495">the storage for the start value, leave %NULL if not need. @@ -69346,7 +72994,7 @@ values, %FALSE otherwise. allow-none="1"> the storage for the stop value, leave + line="497">the storage for the stop value, leave %NULL if not need. @@ -69356,12 +73004,12 @@ values, %FALSE otherwise. c:identifier="gst_toc_entry_get_sub_entries"> Gets the sub-entries of @entry. + line="689">Gets the sub-entries of @entry. A #GList of #GstTocEntry of @entry + line="695">A #GList of #GstTocEntry of @entry @@ -69370,7 +73018,7 @@ values, %FALSE otherwise. A #GstTocEntry instance + line="691">A #GstTocEntry instance @@ -69378,19 +73026,19 @@ values, %FALSE otherwise. Gets the tags for @entry. + line="747">Gets the tags for @entry. A #GstTagList for @entry + line="753">A #GstTagList for @entry A #GstTocEntry instance + line="749">A #GstTocEntry instance @@ -69398,19 +73046,19 @@ values, %FALSE otherwise. Gets the parent #GstToc of @entry. + line="763">Gets the parent #GstToc of @entry. The parent #GstToc of @entry + line="769">The parent #GstToc of @entry A #GstTocEntry instance + line="765">A #GstTocEntry instance @@ -69418,19 +73066,19 @@ values, %FALSE otherwise. Gets the UID of @entry. + line="647">Gets the UID of @entry. The UID of @entry + line="653">The UID of @entry A #GstTocEntry instance + line="649">A #GstTocEntry instance @@ -69441,14 +73089,14 @@ values, %FALSE otherwise. %TRUE if @entry's type is an alternative type, otherwise %FALSE + line="623">%TRUE if @entry's type is an alternative type, otherwise %FALSE a #GstTocEntry + line="621">a #GstTocEntry @@ -69458,14 +73106,14 @@ values, %FALSE otherwise. %TRUE if @entry's type is a sequence type, otherwise %FALSE + line="637">%TRUE if @entry's type is a sequence type, otherwise %FALSE a #GstTocEntry + line="635">a #GstTocEntry @@ -69473,7 +73121,7 @@ values, %FALSE otherwise. Merge @tags into the existing tags of @entry using @mode. + line="723">Merge @tags into the existing tags of @entry using @mode. @@ -69482,7 +73130,7 @@ values, %FALSE otherwise. A #GstTocEntry instance + line="725">A #GstTocEntry instance allow-none="1"> A #GstTagList or %NULL + line="726">A #GstTagList or %NULL A #GstTagMergeMode + line="727">A #GstTagMergeMode @@ -69507,7 +73155,7 @@ values, %FALSE otherwise. version="1.4"> Set @loop_type and @repeat_count values for the @entry. + line="520">Set @loop_type and @repeat_count values for the @entry. @@ -69516,19 +73164,19 @@ values, %FALSE otherwise. #GstTocEntry to set values. + line="522">#GstTocEntry to set values. loop_type value to set. + line="523">loop_type value to set. repeat_count value to set. + line="524">repeat_count value to set. @@ -69537,7 +73185,7 @@ values, %FALSE otherwise. c:identifier="gst_toc_entry_set_start_stop_times"> Set @start and @stop values for the @entry. + line="474">Set @start and @stop values for the @entry. @@ -69546,19 +73194,19 @@ values, %FALSE otherwise. #GstTocEntry to set values. + line="476">#GstTocEntry to set values. start value to set. + line="477">start value to set. stop value to set. + line="478">stop value to set. @@ -69566,7 +73214,7 @@ values, %FALSE otherwise. Set a #GstTagList with tags for the complete @entry. + line="705">Set a #GstTagList with tags for the complete @entry. @@ -69575,7 +73223,7 @@ values, %FALSE otherwise. A #GstTocEntry instance + line="707">A #GstTocEntry instance allow-none="1"> A #GstTagList or %NULL + line="708">A #GstTagList or %NULL @@ -69665,12 +73313,12 @@ There are two types of TOC entries: alternatives or parts in a sequence. Converts @type to a string representation. + line="573">Converts @type to a string representation. Returns a human-readable string for @type. This string is + line="579">Returns a human-readable string for @type. This string is only for debugging purpose and should not be displayed in a user interface. @@ -69679,7 +73327,7 @@ There are two types of TOC entries: alternatives or parts in a sequence. a #GstTocEntryType. + line="575">a #GstTocEntryType. @@ -69888,13 +73536,13 @@ contextual data, which they must not modify. Create a new tracer-factory capable of instantiating objects of the + line="143">Create a new tracer-factory capable of instantiating objects of the @type and add the factory to @plugin. %TRUE, if the registering succeeded, %FALSE on error + line="152">%TRUE, if the registering succeeded, %FALSE on error @@ -69904,19 +73552,19 @@ contextual data, which they must not modify. allow-none="1"> A #GstPlugin, or %NULL for a static typefind function + line="145">A #GstPlugin, or %NULL for a static typefind function The name for registering + line="146">The name for registering GType of tracer to register + line="147">GType of tracer to register @@ -69952,6 +73600,60 @@ contextual data, which they must not modify. + + Sets whether the tracer should use structure parameters for configuration. +This function configures how parameters should be passed when instantiating +the tracer. + +This is typically called in the tracer's class initialization function to +indicate its parameter handling preference. + + + + + + + the #GstTracerFactoryClass to mark as using structure parameters + + + + %TRUE to use structure parameters, %FALSE otherwise + + + + + + If set, the tracer subsystem will consider parameters passed to the +`GST_TRACERS` environment variable as a #GstStructure and use its +fields as properties to instanciate the tracer. + + + %TRUE if the tracer uses structure parameters, %FALSE otherwise + + + + + the #GstTracerClass to to check + + + + version="1.8"> Gets the list of all registered tracer factories. You must free the + line="60">Gets the list of all registered tracer factories. You must free the list using gst_plugin_feature_list_free(). The returned factories are sorted by factory name. @@ -69981,7 +73683,7 @@ Free-function: gst_plugin_feature_list_free the list of all + line="70">the list of all registered #GstTracerFactory. @@ -69993,14 +73695,14 @@ Free-function: gst_plugin_feature_list_free version="1.14"> Get the #GType for elements managed by this factory. The type can + line="82">Get the #GType for elements managed by this factory. The type can only be retrieved if the element factory is loaded, which can be assured with gst_plugin_feature_load(). the #GType for tracers managed by this factory or 0 if + line="90">the #GType for tracers managed by this factory or 0 if the factory is not loaded. @@ -70008,7 +73710,7 @@ the factory is not loaded. factory to get managed #GType from + line="84">factory to get managed #GType from @@ -70046,7 +73748,7 @@ will log and create a log formatter. introspectable="0"> Create a new tracer record. The record instance can be used to efficiently + line="157">Create a new tracer record. The record instance can be used to efficiently log entries using gst_tracer_record_log(). %NULL terminator required after the last argument. @@ -70069,26 +73771,26 @@ handle that right now. a new #GstTracerRecord + line="184">a new #GstTracerRecord name of new record, must end on ".class". + line="159">name of new record, must end on ".class". name of first field to set + line="160">name of first field to set additional arguments + line="161">additional arguments @@ -70099,7 +73801,7 @@ handle that right now. introspectable="0"> Serialzes the trace event into the log. + line="242">Serialzes the trace event into the log. Right now this is using the gstreamer debug log with the level TRACE (7) and the category "GST_TRACER". @@ -70113,13 +73815,13 @@ the category "GST_TRACER". the tracer-record + line="244">the tracer-record the args as described in the spec- + line="245">the args as described in the spec- @@ -70220,13 +73922,20 @@ events may contain values for different #GstPads. line="57">the value is related to a #GstPad - + The following functions allow you to detect the media type of an unknown stream. + Method to peek data. @@ -70246,6 +73955,9 @@ stream. + Method to suggest #GstCaps with a given probability. @@ -70271,6 +73983,9 @@ stream. + Returns the length of current data. @@ -70910,15 +74625,45 @@ that handles the given URI for reading or writing Source and Sink plugins should implement this interface when possible. + + Method to return the list of protocols handled by the element. + + + + + + + + + + + + + + Method to tell whether the element handles source or sink URI. + + + + + + + + + + Gets the currently handled URI. + line="761">Gets the currently handled URI. the URI currently handled by + line="767">the URI currently handled by the @handler. Returns %NULL if there are no URI currently handled. The returned string must be freed with g_free() when no longer needed. @@ -70928,7 +74673,7 @@ Source and Sink plugins should implement this interface when possible. A #GstURIHandler + line="763">A #GstURIHandler @@ -70936,25 +74681,25 @@ Source and Sink plugins should implement this interface when possible. Tries to set the URI of the given handler. + line="790">Tries to set the URI of the given handler. %TRUE if the URI was set successfully, else %FALSE. + line="799">%TRUE if the URI was set successfully, else %FALSE. A #GstURIHandler + line="792">A #GstURIHandler URI to set + line="793">URI to set @@ -70963,13 +74708,13 @@ Source and Sink plugins should implement this interface when possible. c:identifier="gst_uri_handler_get_protocols"> Gets the list of protocols supported by @handler. This list may not be + line="731">Gets the list of protocols supported by @handler. This list may not be modified. the + line="738">the supported protocols. Returns %NULL if the @handler isn't implemented properly, or the @handler doesn't support any protocols. @@ -70981,7 +74726,7 @@ modified. A #GstURIHandler. + line="733">A #GstURIHandler. @@ -70989,12 +74734,12 @@ modified. Gets the currently handled URI. + line="761">Gets the currently handled URI. the URI currently handled by + line="767">the URI currently handled by the @handler. Returns %NULL if there are no URI currently handled. The returned string must be freed with g_free() when no longer needed. @@ -71004,7 +74749,7 @@ modified. A #GstURIHandler + line="763">A #GstURIHandler @@ -71012,12 +74757,12 @@ modified. Gets the type of the given URI handler + line="704">Gets the type of the given URI handler the #GstURIType of the URI handler. + line="710">the #GstURIType of the URI handler. Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. @@ -71025,7 +74770,7 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. A #GstURIHandler. + line="706">A #GstURIHandler. @@ -71033,25 +74778,25 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. Tries to set the URI of the given handler. + line="790">Tries to set the URI of the given handler. %TRUE if the URI was set successfully, else %FALSE. + line="799">%TRUE if the URI was set successfully, else %FALSE. A #GstURIHandler + line="792">A #GstURIHandler URI to set + line="793">URI to set @@ -71071,6 +74816,9 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. + Method to tell whether the element handles source or sink URI. @@ -71084,6 +74832,9 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. + Method to return the list of protocols handled by the element. @@ -71099,12 +74850,15 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. + Method to return the URI currently handled by the element. the URI currently handled by + line="767">the URI currently handled by the @handler. Returns %NULL if there are no URI currently handled. The returned string must be freed with g_free() when no longer needed. @@ -71114,32 +74868,35 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. A #GstURIHandler + line="763">A #GstURIHandler + Method to set a new URI. %TRUE if the URI was set successfully, else %FALSE. + line="799">%TRUE if the URI was set successfully, else %FALSE. A #GstURIHandler + line="792">A #GstURIHandler URI to set + line="793">URI to set @@ -71254,21 +75011,21 @@ Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. c:symbol-prefix="uri"> A #GstUri object can be used to parse and split a URI string into its + line="971">A #GstUri object can be used to parse and split a URI string into its constituent parts. Two #GstUri objects can be joined to make a new #GstUri using the algorithm described in RFC3986. Creates a new #GstUri object with the given URI parts. The path and query + line="1438">Creates a new #GstUri object with the given URI parts. The path and query strings will be broken down into their elements. All strings should not be escaped except where indicated. A new #GstUri object. + line="1455">A new #GstUri object. @@ -71278,7 +75035,7 @@ escaped except where indicated. allow-none="1"> The scheme for the new URI. + line="1440">The scheme for the new URI. allow-none="1"> The user-info for the new URI. + line="1441">The user-info for the new URI. allow-none="1"> The host name for the new URI. + line="1442">The host name for the new URI. The port number for the new URI or %GST_URI_NO_PORT. + line="1443">The port number for the new URI or %GST_URI_NO_PORT. allow-none="1"> The path for the new URI with '/' separating path + line="1444">The path for the new URI with '/' separating path elements. @@ -71321,7 +75078,7 @@ escaped except where indicated. allow-none="1"> The query string for the new URI with '&' separating + line="1446">The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "&percnt;26". @@ -71332,7 +75089,7 @@ escaped except where indicated. allow-none="1"> The fragment name for the new URI. + line="1449">The fragment name for the new URI. @@ -71342,13 +75099,13 @@ escaped except where indicated. version="1.6"> Append a path onto the end of the path in the URI. The path is not + line="2535">Append a path onto the end of the path in the URI. The path is not normalized, call #gst_uri_normalize() to normalize the path. - + %TRUE if the path was appended successfully. + line="2543">%TRUE if the path was appended successfully. @@ -71358,7 +75115,7 @@ normalized, call #gst_uri_normalize() to normalize the path. allow-none="1"> The #GstUri to modify. + line="2537">The #GstUri to modify. allow-none="1"> Relative path to append to the end of the current path. + line="2538">Relative path to append to the end of the current path. @@ -71377,12 +75134,12 @@ normalized, call #gst_uri_normalize() to normalize the path. version="1.6"> Append a single path segment onto the end of the URI path. - + line="2573">Append a single path segment onto the end of the URI path. + %TRUE if the path was appended successfully. + line="2580">%TRUE if the path was appended successfully. @@ -71392,7 +75149,7 @@ normalized, call #gst_uri_normalize() to normalize the path. allow-none="1"> The #GstUri to modify. + line="2575">The #GstUri to modify. allow-none="1"> The path segment string to append to the URI path. + line="2576">The path segment string to append to the URI path. @@ -71409,26 +75166,26 @@ normalized, call #gst_uri_normalize() to normalize the path. Compares two #GstUri objects to see if they represent the same normalized + line="1718">Compares two #GstUri objects to see if they represent the same normalized URI. %TRUE if the normalized versions of the two URI's would be equal. + line="1726">%TRUE if the normalized versions of the two URI's would be equal. First #GstUri to compare. + line="1720">First #GstUri to compare. Second #GstUri to compare. + line="1721">Second #GstUri to compare. @@ -71438,12 +75195,12 @@ URI. version="1.6"> Like gst_uri_from_string() but also joins with a base URI. + line="1689">Like gst_uri_from_string() but also joins with a base URI. A new #GstUri object. + line="1696">A new #GstUri object. @@ -71453,13 +75210,13 @@ URI. allow-none="1"> The base URI to join the new URI with. + line="1691">The base URI to join the new URI with. The URI string to parse. + line="1692">The URI string to parse. @@ -71469,13 +75226,13 @@ URI. version="1.6"> Get the fragment name from the URI or %NULL if it doesn't exist. + line="2934">Get the fragment name from the URI or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. - + The host name from the #GstUri object or %NULL. + line="2941">The host name from the #GstUri object or %NULL. @@ -71485,7 +75242,7 @@ If @uri is %NULL then returns %NULL. allow-none="1"> This #GstUri object. + line="2936">This #GstUri object. @@ -71493,13 +75250,13 @@ If @uri is %NULL then returns %NULL. Get the host name from the URI or %NULL if it doesn't exist. + line="2265">Get the host name from the URI or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. - + The host name from the #GstUri object or %NULL. + line="2272">The host name from the #GstUri object or %NULL. @@ -71509,7 +75266,7 @@ If @uri is %NULL then returns %NULL. allow-none="1"> This #GstUri object. + line="2267">This #GstUri object. @@ -71519,7 +75276,7 @@ If @uri is %NULL then returns %NULL. version="1.12"> Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0". + line="2979">Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0". Hash table returned by this API is a list of "key-value" pairs, and the each pair is generated by splitting "URI fragment" per "&" sub-delims, then "key" and "value" are split by "=" sub-delims. The "key" returned by this API may @@ -71530,11 +75287,11 @@ with #g_hash_table_unref() when it is no longer required. Modifying this hash table does not affect the fragment in the URI. See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/ - + The + line="2995">The fragment hash table from the URI. @@ -71548,7 +75305,7 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag allow-none="1"> The #GstUri to get the fragment table from. + line="2981">The #GstUri to get the fragment table from. @@ -71556,12 +75313,12 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag Extract the path string from the URI object. - + line="2351">Extract the path string from the URI object. + The path from the URI. Once finished + line="2357">The path from the URI. Once finished with the string should be g_free()'d. @@ -71572,7 +75329,7 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag allow-none="1"> The #GstUri to get the path from. + line="2353">The #GstUri to get the path from. @@ -71582,12 +75339,12 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag version="1.6"> Get a list of path segments from the URI. - + line="2479">Get a list of path segments from the URI. + A #GList of path segment + line="2485">A #GList of path segment strings or %NULL if no path segments are available. Free the list when no longer needed with g_list_free_full(list, g_free). @@ -71601,7 +75358,7 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag allow-none="1"> The #GstUri to get the path from. + line="2481">The #GstUri to get the path from. @@ -71611,12 +75368,12 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag version="1.6"> Extract the path string from the URI object as a percent encoded URI path. - + line="2414">Extract the path string from the URI object as a percent encoded URI path. + The path from the URI. Once finished + line="2420">The path from the URI. Once finished with the string should be g_free()'d. @@ -71627,7 +75384,7 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag allow-none="1"> The #GstUri to get the path from. + line="2416">The #GstUri to get the path from. @@ -71635,13 +75392,13 @@ See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frag Get the port number from the URI or %GST_URI_NO_PORT if it doesn't exist. + line="2310">Get the port number from the URI or %GST_URI_NO_PORT if it doesn't exist. If @uri is %NULL then returns %GST_URI_NO_PORT. - + The port number from the #GstUri object or %GST_URI_NO_PORT. + line="2317">The port number from the #GstUri object or %GST_URI_NO_PORT. @@ -71651,7 +75408,7 @@ If @uri is %NULL then returns %GST_URI_NO_PORT. allow-none="1"> This #GstUri object. + line="2312">This #GstUri object. @@ -71661,12 +75418,12 @@ If @uri is %NULL then returns %GST_URI_NO_PORT. version="1.6"> Get a list of the query keys from the URI. - + line="2911">Get a list of the query keys from the URI. + A list of keys from + line="2917">A list of keys from the URI query. Free the list with g_list_free(). @@ -71679,7 +75436,7 @@ If @uri is %NULL then returns %GST_URI_NO_PORT. allow-none="1"> The #GstUri to examine. + line="2913">The #GstUri to examine. @@ -71689,12 +75446,12 @@ If @uri is %NULL then returns %GST_URI_NO_PORT. version="1.6"> Get a percent encoded URI query string from the @uri. - + line="2601">Get a percent encoded URI query string from the @uri. + A percent encoded query string. Use + line="2607">A percent encoded query string. Use g_free() when no longer needed. @@ -71705,27 +75462,69 @@ If @uri is %NULL then returns %GST_URI_NO_PORT. allow-none="1"> The #GstUri to get the query string from. + line="2603">The #GstUri to get the query string from. + + Get a percent encoded URI query string from the @uri, with query parameters +in the order provided by the @keys list. Only parameter keys in the list will +be added to the resulting URI string. This method can be used by retrieving +the keys with gst_uri_get_query_keys() and then sorting the list, for +example. + + + A percent encoded query string. Use +g_free() when no longer needed. + + + + + The #GstUri to get the query string from. + + + + A GList containing the + query argument key strings. + + + + + + Get the query table from the URI. Keys and values in the table are freed + line="2733">Get the query table from the URI. Keys and values in the table are freed with g_free when they are deleted. A value may be %NULL to indicate that the key should appear in the query string in the URI, but does not have a value. Free the returned #GHashTable with #g_hash_table_unref() when it is no longer required. Modifying this hash table will modify the query in the URI. - + The query + line="2744">The query hash table from the URI. @@ -71739,7 +75538,7 @@ URI. allow-none="1"> The #GstUri to get the query table from. + line="2735">The #GstUri to get the query table from. @@ -71749,16 +75548,16 @@ URI. version="1.6"> Get the value associated with the @query_key key. Will return %NULL if the + line="2884">Get the value associated with the @query_key key. Will return %NULL if the key has no value or if the key does not exist in the URI query table. Because %NULL is returned for both missing keys and keys with no value, you should use gst_uri_query_has_key() to determine if a key is present in the URI query. - + The value for the given key, or %NULL if not found. + line="2895">The value for the given key, or %NULL if not found. @@ -71768,13 +75567,13 @@ query. allow-none="1"> The #GstUri to examine. + line="2886">The #GstUri to examine. The key to lookup. + line="2887">The key to lookup. @@ -71782,13 +75581,13 @@ query. Get the scheme name from the URI or %NULL if it doesn't exist. + line="2178">Get the scheme name from the URI or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. - + The scheme from the #GstUri object or %NULL. + line="2185">The scheme from the #GstUri object or %NULL. @@ -71798,7 +75597,7 @@ If @uri is %NULL then returns %NULL. allow-none="1"> This #GstUri object. + line="2180">This #GstUri object. @@ -71808,13 +75607,13 @@ If @uri is %NULL then returns %NULL. version="1.6"> Get the userinfo (usually in the form "username:password") from the URI + line="2221">Get the userinfo (usually in the form "username:password") from the URI or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. - + The userinfo from the #GstUri object or %NULL. + line="2228">The userinfo from the #GstUri object or %NULL. @@ -71824,7 +75623,7 @@ or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. allow-none="1"> This #GstUri object. + line="2223">This #GstUri object. @@ -71834,13 +75633,13 @@ or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. version="1.6"> Tests the @uri to see if it is normalized. A %NULL @uri is considered to be + line="2103">Tests the @uri to see if it is normalized. A %NULL @uri is considered to be normalized. - + TRUE if the URI is normalized or is %NULL. + line="2110">TRUE if the URI is normalized or is %NULL. @@ -71850,7 +75649,7 @@ normalized. allow-none="1"> The #GstUri to test to see if it is normalized. + line="2105">The #GstUri to test to see if it is normalized. @@ -71860,7 +75659,7 @@ normalized. version="1.6"> Check if it is safe to write to this #GstUri. + line="1954">Check if it is safe to write to this #GstUri. Check if the refcount of @uri is exactly 1, meaning that no other reference exists to the #GstUri and that the #GstUri is therefore writable. @@ -71871,14 +75670,14 @@ writable. %TRUE if it is safe to write to the object. + line="1966">%TRUE if it is safe to write to the object. The #GstUri object to test. + line="1956">The #GstUri object to test. @@ -71886,14 +75685,14 @@ writable. Join a reference URI onto a base URI using the method from RFC 3986. + line="1829">Join a reference URI onto a base URI using the method from RFC 3986. If either URI is %NULL then the other URI will be returned with the ref count increased. A #GstUri which represents the base + line="1839">A #GstUri which represents the base with the reference URI joined on. @@ -71904,7 +75703,7 @@ increased. allow-none="1"> The base URI to join another to. + line="1831">The base URI to join another to. allow-none="1"> The reference URI to join onto the + line="1832">The reference URI to join onto the base URI. @@ -71924,7 +75723,7 @@ increased. version="1.6"> Make the #GstUri writable. + line="1977">Make the #GstUri writable. Checks if @uri is writable, and if so the original object is returned. If not, then a writable copy is made and returned. This gives away the @@ -71934,14 +75733,14 @@ If @uri is %NULL then %NULL is returned. A writable version of @uri. + line="1988">A writable version of @uri. The #GstUri object to make writable. + line="1979">The #GstUri object to make writable. @@ -71951,12 +75750,12 @@ If @uri is %NULL then %NULL is returned. version="1.6"> Like gst_uri_new(), but joins the new URI onto a base URI. + line="1479">Like gst_uri_new(), but joins the new URI onto a base URI. The new URI joined onto @base. + line="1495">The new URI joined onto @base. @@ -71966,7 +75765,7 @@ If @uri is %NULL then %NULL is returned. allow-none="1"> The base URI to join the new URI to. + line="1481">The base URI to join the new URI to. allow-none="1"> The scheme for the new URI. + line="1482">The scheme for the new URI. allow-none="1"> The user-info for the new URI. + line="1483">The user-info for the new URI. allow-none="1"> The host name for the new URI. + line="1484">The host name for the new URI. The port number for the new URI or %GST_URI_NO_PORT. + line="1485">The port number for the new URI or %GST_URI_NO_PORT. allow-none="1"> The path for the new URI with '/' separating path + line="1486">The path for the new URI with '/' separating path elements. @@ -72018,7 +75817,7 @@ If @uri is %NULL then %NULL is returned. allow-none="1"> The query string for the new URI with '&' separating + line="1488">The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "&percnt;26". @@ -72029,7 +75828,7 @@ If @uri is %NULL then %NULL is returned. allow-none="1"> The fragment name for the new URI. + line="1491">The fragment name for the new URI. @@ -72037,24 +75836,24 @@ If @uri is %NULL then %NULL is returned. Normalization will remove extra path segments ("." and "..") from the URI. It + line="2150">Normalization will remove extra path segments ("." and "..") from the URI. It will also convert the scheme and host name to lower case and any percent-encoded values to uppercase. The #GstUri object must be writable. Check with gst_uri_is_writable() or use gst_uri_make_writable() first. - + TRUE if the URI was modified. + line="2161">TRUE if the URI was modified. The #GstUri to normalize. + line="2152">The #GstUri to normalize. @@ -72064,12 +75863,12 @@ gst_uri_make_writable() first. version="1.6"> Check if there is a query table entry for the @query_key key. - + line="2861">Check if there is a query table entry for the @query_key key. + %TRUE if @query_key exists in the URI query table. + line="2868">%TRUE if @query_key exists in the URI query table. @@ -72079,13 +75878,13 @@ gst_uri_make_writable() first. allow-none="1"> The #GstUri to examine. + line="2863">The #GstUri to examine. The key to lookup. + line="2864">The key to lookup. @@ -72095,12 +75894,12 @@ gst_uri_make_writable() first. version="1.6"> Remove an entry from the query table by key. - + line="2830">Remove an entry from the query table by key. + %TRUE if the key existed in the table and was removed. + line="2837">%TRUE if the key existed in the table and was removed. @@ -72110,13 +75909,13 @@ gst_uri_make_writable() first. allow-none="1"> The #GstUri to modify. + line="2832">The #GstUri to modify. The key to remove. + line="2833">The key to remove. @@ -72126,13 +75925,13 @@ gst_uri_make_writable() first. version="1.6"> Sets the fragment string in the URI. Use a value of %NULL in @fragment to + line="2952">Sets the fragment string in the URI. Use a value of %NULL in @fragment to unset the fragment string. - + %TRUE if the fragment was set/unset successfully. + line="2960">%TRUE if the fragment was set/unset successfully. @@ -72142,7 +75941,7 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2954">The #GstUri to modify. allow-none="1"> The fragment string to set. + line="2955">The fragment string to set. @@ -72159,12 +75958,12 @@ unset the fragment string. Set or unset the host for the URI. - + line="2283">Set or unset the host for the URI. + %TRUE if the host was set/unset successfully. + line="2290">%TRUE if the host was set/unset successfully. @@ -72174,13 +75973,13 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2285">The #GstUri to modify. The new host string to set or %NULL to unset. + line="2286">The new host string to set or %NULL to unset. @@ -72188,12 +75987,12 @@ unset the fragment string. Sets or unsets the path in the URI. - + line="2389">Sets or unsets the path in the URI. + %TRUE if the path was set successfully. + line="2397">%TRUE if the path was set successfully. @@ -72203,7 +76002,7 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2391">The #GstUri to modify. allow-none="1"> The new path to set with path segments separated by '/', or use %NULL + line="2392">The new path to set with path segments separated by '/', or use %NULL to unset the path. @@ -72223,12 +76022,12 @@ unset the fragment string. version="1.6"> Replace the path segments list in the URI. - + line="2505">Replace the path segments list in the URI. + %TRUE if the path segments were set successfully. + line="2513">%TRUE if the path segments were set successfully. @@ -72238,7 +76037,7 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2507">The #GstUri to modify. allow-none="1"> The new + line="2508">The new path list to set. @@ -72260,12 +76059,12 @@ unset the fragment string. version="1.6"> Sets or unsets the path in the URI. - + line="2455">Sets or unsets the path in the URI. + %TRUE if the path was set successfully. + line="2463">%TRUE if the path was set successfully. @@ -72275,13 +76074,13 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2457">The #GstUri to modify. The new percent encoded path to set with path segments separated by + line="2458">The new percent encoded path to set with path segments separated by '/', or use %NULL to unset the path. @@ -72290,12 +76089,12 @@ unset the fragment string. Set or unset the port number for the URI. - + line="2328">Set or unset the port number for the URI. + %TRUE if the port number was set/unset successfully. + line="2335">%TRUE if the port number was set/unset successfully. @@ -72305,13 +76104,13 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2330">The #GstUri to modify. The new port number to set or %GST_URI_NO_PORT to unset. + line="2331">The new port number to set or %GST_URI_NO_PORT to unset. @@ -72321,12 +76120,12 @@ unset the fragment string. version="1.6"> Sets or unsets the query table in the URI. - + line="2645">Sets or unsets the query table in the URI. + %TRUE if the query table was set successfully. + line="2653">%TRUE if the query table was set successfully. @@ -72336,7 +76135,7 @@ unset the fragment string. allow-none="1"> The #GstUri to modify. + line="2647">The #GstUri to modify. allow-none="1"> The new percent encoded query string to use to populate the query + line="2648">The new percent encoded query string to use to populate the query table, or use %NULL to unset the query table. @@ -72356,14 +76155,14 @@ unset the fragment string. version="1.6"> Set the query table to use in the URI. The old table is unreferenced and a + line="2761">Set the query table to use in the URI. The old table is unreferenced and a reference to the new one is used instead. A value if %NULL for @query_table will remove the query string from the URI. - + %TRUE if the new table was successfully used for the query table. + line="2771">%TRUE if the new table was successfully used for the query table. @@ -72373,7 +76172,7 @@ will remove the query string from the URI. allow-none="1"> The #GstUri to modify. + line="2763">The #GstUri to modify. allow-none="1"> The new + line="2764">The new query table to use. @@ -72396,14 +76195,14 @@ will remove the query string from the URI. version="1.6"> This inserts or replaces a key in the query table. A @query_value of %NULL + line="2798">This inserts or replaces a key in the query table. A @query_value of %NULL indicates that the key has no associated value, but will still be present in the query string. - + %TRUE if the query table was successfully updated. + line="2808">%TRUE if the query table was successfully updated. @@ -72413,13 +76212,13 @@ the query string. allow-none="1"> The #GstUri to modify. + line="2800">The #GstUri to modify. The key for the query entry. + line="2801">The key for the query entry. allow-none="1"> The value for the key. + line="2802">The value for the key. @@ -72438,12 +76237,12 @@ the query string. version="1.6"> Set or unset the scheme for the URI. - + line="2194">Set or unset the scheme for the URI. + %TRUE if the scheme was set/unset successfully. + line="2201">%TRUE if the scheme was set/unset successfully. @@ -72453,13 +76252,13 @@ the query string. allow-none="1"> The #GstUri to modify. + line="2196">The #GstUri to modify. The new scheme to set or %NULL to unset the scheme. + line="2197">The new scheme to set or %NULL to unset the scheme. @@ -72469,12 +76268,12 @@ the query string. version="1.6"> Set or unset the user information for the URI. - + line="2239">Set or unset the user information for the URI. + %TRUE if the user information was set/unset successfully. + line="2246">%TRUE if the user information was set/unset successfully. @@ -72484,13 +76283,13 @@ the query string. allow-none="1"> The #GstUri to modify. + line="2241">The #GstUri to modify. The new user-information string to set or %NULL to unset. + line="2242">The new user-information string to set or %NULL to unset. @@ -72498,7 +76297,7 @@ the query string. Convert the URI to a string. + line="2083">Convert the URI to a string. Returns the URI as held in this object as a #gchar* nul-terminated string. The caller should g_free() the string once they are finished with it. @@ -72507,16 +76306,58 @@ The string is put together as described in RFC 3986. The string version of the URI. + line="2093">The string version of the URI. This #GstUri to convert to a string. + line="2085">This #GstUri to convert to a string. + + + + + + Convert the URI to a string, with the query arguments in a specific order. +Only the keys in the @keys list will be added to the resulting string. + +Returns the URI as held in this object as a #gchar* nul-terminated string. +The caller should g_free() the string once they are finished with it. +The string is put together as described in RFC 3986. + + + The string version of the URI. + + + + + This #GstUri to convert to a string. + + A GList containing + the query argument key strings. + + + + version="1.6"> Parses a URI string into a new #GstUri object. Will return NULL if the URI + line="1644">Parses a URI string into a new #GstUri object. Will return NULL if the URI cannot be parsed. A new #GstUri object, or NULL. + line="1651">A new #GstUri object, or NULL. The URI string to parse. + line="1646">The URI string to parse. @@ -72578,7 +76419,7 @@ cannot be parsed. version="1.18"> Parses a URI string into a new #GstUri object. Will return NULL if the URI + line="1661">Parses a URI string into a new #GstUri object. Will return NULL if the URI cannot be parsed. This is identical to gst_uri_from_string() except that the userinfo and fragment components of the URI will not be unescaped while parsing. @@ -72595,14 +76436,14 @@ https://example.com/path#fragment which may contain a URI-escaped '#'. A new #GstUri object, or NULL. + line="1679">A new #GstUri object, or NULL. The URI string to parse. + line="1663">The URI string to parse. @@ -72707,13 +76548,13 @@ scheme followed by ":" and maybe a string identifying the location. version="1.6"> This is a convenience function to join two URI strings and return the result. + line="1918">This is a convenience function to join two URI strings and return the result. The returned string should be g_free()'d after use. A string representing the percent-encoded join of + line="1926">A string representing the percent-encoded join of the two URIs. @@ -72721,13 +76562,13 @@ The returned string should be g_free()'d after use. The percent-encoded base URI. + line="1920">The percent-encoded base URI. The percent-encoded reference URI to join to the @base_uri. + line="1921">The percent-encoded reference URI to join to the @base_uri. @@ -72736,27 +76577,27 @@ The returned string should be g_free()'d after use. c:identifier="gst_uri_protocol_is_supported"> Checks if an element exists that supports the given URI protocol. Note + line="592">Checks if an element exists that supports the given URI protocol. Note that a positive return value does not imply that a subsequent call to gst_element_make_from_uri() is guaranteed to work. %TRUE + line="601">%TRUE Whether to check for a source or a sink + line="594">Whether to check for a source or a sink Protocol that should be checked for (e.g. "http" or "smb") + line="595">Protocol that should be checked for (e.g. "http" or "smb") @@ -73052,14 +76893,14 @@ determine a order for the two provided values. - + The micro version of GStreamer at compile time: - + The minor version of GStreamer at compile time: @@ -73088,7 +76929,7 @@ Actual releases have 0, GIT versions have 1, prerelease versions have 2-... Appends @append_value to the GstValueArray in @value. + line="1009">Appends @append_value to the GstValueArray in @value. @@ -73097,13 +76938,13 @@ Actual releases have 0, GIT versions have 1, prerelease versions have 2-... a #GValue of type #GST_TYPE_ARRAY + line="1011">a #GValue of type #GST_TYPE_ARRAY the value to append + line="1012">the value to append @@ -73112,7 +76953,7 @@ Actual releases have 0, GIT versions have 1, prerelease versions have 2-... Appends @append_value to the GstValueArray in @value. + line="981">Appends @append_value to the GstValueArray in @value. @@ -73121,13 +76962,13 @@ Actual releases have 0, GIT versions have 1, prerelease versions have 2-... a #GValue of type #GST_TYPE_ARRAY + line="983">a #GValue of type #GST_TYPE_ARRAY the value to append + line="984">the value to append @@ -73135,19 +76976,19 @@ Actual releases have 0, GIT versions have 1, prerelease versions have 2-... Gets the number of values contained in @value. + line="1050">Gets the number of values contained in @value. the number of values + line="1056">the number of values a #GValue of type #GST_TYPE_ARRAY + line="1052">a #GValue of type #GST_TYPE_ARRAY @@ -73155,26 +76996,26 @@ Actual releases have 0, GIT versions have 1, prerelease versions have 2-... Gets the value that is a member of the array contained in @value and + line="1066">Gets the value that is a member of the array contained in @value and has the index @index. the value at the given index + line="1074">the value at the given index a #GValue of type #GST_TYPE_ARRAY + line="1068">a #GValue of type #GST_TYPE_ARRAY index of value to get from the array + line="1069">index of value to get from the array @@ -73182,25 +77023,25 @@ has the index @index. Initializes and pre-allocates a #GValue of type #GST_TYPE_ARRAY. + line="324">Initializes and pre-allocates a #GValue of type #GST_TYPE_ARRAY. The #GValue structure that has been passed in + line="331">The #GValue structure that has been passed in A zero-filled (uninitialized) #GValue structure + line="326">A zero-filled (uninitialized) #GValue structure The number of entries to pre-allocate in the array + line="327">The number of entries to pre-allocate in the array @@ -73209,7 +77050,7 @@ has the index @index. c:identifier="gst_value_array_prepend_value"> Prepends @prepend_value to the GstValueArray in @value. + line="1029">Prepends @prepend_value to the GstValueArray in @value. @@ -73218,13 +77059,13 @@ has the index @index. a #GValue of type #GST_TYPE_ARRAY + line="1031">a #GValue of type #GST_TYPE_ARRAY the value to prepend + line="1032">the value to prepend @@ -73330,7 +77171,7 @@ or GST_VALUE_UNORDERED version="1.2"> Appends @append_value to the GstValueList in @value. + line="680">Appends @append_value to the GstValueList in @value. @@ -73339,13 +77180,13 @@ or GST_VALUE_UNORDERED a #GValue of type #GST_TYPE_LIST + line="682">a #GValue of type #GST_TYPE_LIST the value to append + line="683">the value to append @@ -73353,7 +77194,7 @@ or GST_VALUE_UNORDERED Appends @append_value to the GstValueList in @value. + line="700">Appends @append_value to the GstValueList in @value. @@ -73362,13 +77203,13 @@ or GST_VALUE_UNORDERED a #GValue of type #GST_TYPE_LIST + line="702">a #GValue of type #GST_TYPE_LIST the value to append + line="703">the value to append @@ -73376,7 +77217,7 @@ or GST_VALUE_UNORDERED Concatenates copies of @value1 and @value2 into a list. Values that are not + line="742">Concatenates copies of @value1 and @value2 into a list. Values that are not of type #GST_TYPE_LIST are treated as if they were lists of length 1. @dest will be initialized to the type #GST_TYPE_LIST. @@ -73390,19 +77231,19 @@ of type #GST_TYPE_LIST are treated as if they were lists of length 1. transfer-ownership="none"> an uninitialized #GValue to take the result + line="744">an uninitialized #GValue to take the result a #GValue + line="745">a #GValue a #GValue + line="746">a #GValue @@ -73410,19 +77251,19 @@ of type #GST_TYPE_LIST are treated as if they were lists of length 1. Gets the number of values contained in @value. + line="946">Gets the number of values contained in @value. the number of values + line="952">the number of values a #GValue of type #GST_TYPE_LIST + line="948">a #GValue of type #GST_TYPE_LIST @@ -73430,26 +77271,26 @@ of type #GST_TYPE_LIST are treated as if they were lists of length 1. Gets the value that is a member of the list contained in @value and + line="962">Gets the value that is a member of the list contained in @value and has the index @index. the value at the given index + line="970">the value at the given index a #GValue of type #GST_TYPE_LIST + line="964">a #GValue of type #GST_TYPE_LIST index of value to get from the list + line="965">index of value to get from the list @@ -73457,25 +77298,25 @@ has the index @index. Initializes and pre-allocates a #GValue of type #GST_TYPE_LIST. + line="293">Initializes and pre-allocates a #GValue of type #GST_TYPE_LIST. The #GValue structure that has been passed in + line="300">The #GValue structure that has been passed in A zero-filled (uninitialized) #GValue structure + line="295">A zero-filled (uninitialized) #GValue structure The number of entries to pre-allocate in the list + line="296">The number of entries to pre-allocate in the list @@ -73483,7 +77324,7 @@ has the index @index. Merges copies of @value1 and @value2. Values that are not + line="845">Merges copies of @value1 and @value2. Values that are not of type #GST_TYPE_LIST are treated as if they were lists of length 1. The result will be put into @dest and will either be a list that will not @@ -73500,19 +77341,19 @@ were equal). transfer-ownership="none"> an uninitialized #GValue to take the result + line="847">an uninitialized #GValue to take the result a #GValue + line="848">a #GValue a #GValue + line="849">a #GValue @@ -73521,7 +77362,7 @@ were equal). c:identifier="gst_value_list_prepend_value"> Prepends @prepend_value to the GstValueList in @value. + line="721">Prepends @prepend_value to the GstValueList in @value. @@ -73530,13 +77371,13 @@ were equal). a #GValue of type #GST_TYPE_LIST + line="723">a #GValue of type #GST_TYPE_LIST the value to prepend + line="724">the value to prepend @@ -73606,21 +77447,760 @@ Free-function: g_free + + #GstVecDeque is an object that provides standard double-ended queue (deque) +functionality based on an array instead of linked lists. This reduces the +overhead caused by memory management by a large factor. + + + Clears queue @array and frees all memory associated to it. + + + + + + + a #GstVecDeque object + + + + + + Drops the queue element at position @idx from queue @array. + + + the dropped element + + + + + a #GstVecDeque object + + + + index to drop + + + + + + Drops the queue element at position @idx from queue @array and copies the +data of the element or structure that was removed into @p_struct if +@p_struct is set (not NULL). + + + TRUE on success, or FALSE on error + + + + + a #GstVecDeque object + + + + index to drop + + + + address into which to store the data of the dropped structure, or NULL + + + + + + Finds an element in the queue @array, either by comparing every element +with @func or by looking up @data if no compare function @func is provided, +and returning the index of the found element. + + + Index of the found element or -1 if nothing was found. + + + + + a #GstVecDeque object + + + + comparison function, or %NULL to find @data by value + + + + data for comparison function + + + + + + Frees queue @array and all memory associated to it. + + + + + + + a #GstVecDeque object + + + + + + Returns the length of the queue @array + + + the length of the queue @array. + + + + + a #GstVecDeque object + + + + + + Checks if the queue @array is empty. + + + %TRUE if the queue @array is empty + + + + + a #GstVecDeque object + + + + + + Returns the head of the queue @array and does not +remove it from the queue. + + + The head of the queue + + + + + a #GstVecDeque object + + + + + + Returns the head of the queue @array without removing it from the queue. + + + pointer to element or struct, or NULL if @array was empty. The + data pointed to by the returned pointer stays valid only as long as + the queue array is not modified further! + + + + + a #GstVecDeque object + + + + + + Returns the item at @idx in @array, but does not remove it from the queue. + + + The item, or %NULL if @idx was out of bounds + + + + + + + + + + + + + Returns the item at @idx in @array, but does not remove it from the queue. + + + The item, or %NULL if @idx was out of bounds + + + + + + + + + + + + + Returns the tail of the queue @array, but does not remove it from the queue. + + + The tail of the queue + + + + + a #GstVecDeque object + + + + + + Returns the tail of the queue @array, but does not remove it from the queue. + + + The tail of the queue + + + + + a #GstVecDeque object + + + + + + Returns and head of the queue @array and removes +it from the queue. + + + The head of the queue + + + + + a #GstVecDeque object + + + + + + Returns the head of the queue @array and removes it from the queue. + + + pointer to element or struct, or NULL if @array was empty. The + data pointed to by the returned pointer stays valid only as long as + the queue array is not modified further! + + + + + a #GstVecDeque object + + + + + + Returns the tail of the queue @array and removes +it from the queue. + + + The tail of the queue + + + + + a #GstVecDeque object + + + + + + Returns the tail of the queue @array and removes +it from the queue. + + + The tail of the queue + + + + + a #GstVecDeque object + + + + + + Pushes @data to the queue @array, finding the correct position +by comparing @data with each array element using @func. + +This has a time complexity of O(n), so depending on the size of the queue +and expected access patterns, a different data structure might be better. + +Assumes that the array is already sorted. If it is not, make sure +to call gst_vec_deque_sort() first. + + + + + + + a #GstVecDeque object + + + + object to push + + + + comparison function + + + + data for comparison function + + + + + + Pushes the element at address @p_struct into the queue @array +(copying the contents of a structure of the struct_size specified +when creating the queue into the array), finding the correct position +by comparing the element at @p_struct with each element in the array using @func. + +This has a time complexity of O(n), so depending on the size of the queue +and expected access patterns, a different data structure might be better. + +Assumes that the array is already sorted. If it is not, make sure +to call gst_vec_deque_sort() first. + + + + + + + a #GstVecDeque object + + + + address of element or structure to push into the queue + + + + comparison function + + + + data for comparison function + + + + + + Pushes @data to the tail of the queue @array. + + + + + + + a #GstVecDeque object + + + + object to push + + + + + + Pushes the element at address @p_struct to the tail of the queue @array +(Copies the contents of a structure of the struct_size specified when +creating the queue into the array). + + + + + + + a #GstVecDeque object + + + + address of element or structure to push to the tail of the queue + + + + + + Sets a function to clear an element of @array. + +The @clear_func will be called when an element in the array +data segment is removed and when the array is freed and data +segment is deallocated as well. @clear_func will be passed a +pointer to the element to clear, rather than the element itself. + +Note that in contrast with other uses of #GDestroyNotify +functions, @clear_func is expected to clear the contents of +the array element it is given, but not free the element itself. + + + + + + + a #GstVecDeque object + + + + a function to clear an element of @array + + + + + + Sorts the queue @array by comparing elements against each other using +the provided @compare_func. + + + + + + + a #GstVecDeque object + + + + comparison function + + + + data for comparison function + + + + + + Allocates a new #GstVecDeque object with an initial +queue size of @initial_size. + + + a new #GstVecDeque object + + + + + Initial size of the new queue + + + + + + Allocates a new #GstVecDeque object for elements (e.g. structures) +of size @struct_size, with an initial queue size of @initial_size. + + + a new #GstVecDeque object + + + + + Size of each element (e.g. structure) in the array + + + + Initial size of the new queue + + + + + Output a warning message in the default category. + line="1259">Output a warning message in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + printf-style message to output + line="1261">printf-style message to output @@ -73630,21 +78210,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a warning message for the given identifier in the default category. + line="1160">Output a warning message for the given identifier in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + An identifier of the message provider + line="1162">An identifier of the message provider printf-style message to output + line="1163">printf-style message to output @@ -73653,21 +78233,21 @@ character, a newline character will be added automatically. introspectable="0"> Output a warning message belonging to the given object in the default category. + line="1073">Output a warning message belonging to the given object in the default category. There is no need to finish the end of the message string with a newline character, a newline character will be added automatically. - + the #GObject the message belongs to + line="1075">the #GObject the message belongs to printf-style message to output + line="1076">printf-style message to output @@ -73857,7 +78437,7 @@ character, a newline character will be added automatically. version="1.2"> Gets the maximum amount of memory blocks that a buffer can hold. This is a + line="510">Gets the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function. When more memory blocks are added, existing memory blocks will be merged @@ -73866,7 +78446,7 @@ together to make room for the new block. the maximum amount of memory blocks that a buffer can hold. + line="519">the maximum amount of memory blocks that a buffer can hold. @@ -73917,18 +78497,18 @@ writable, i.e. nobody can see the modifications you will make. introspectable="0"> Append @b at the end of @l. + line="389">Append @b at the end of @l. a #GstBufferList + line="391">a #GstBufferList a #GstBuffer + line="392">a #GstBuffer @@ -74011,7 +78591,7 @@ you have an additional reference to it. introspectable="0"> Calculates the linear regression of the values @xy and places the + line="4646">Calculates the linear regression of the values @xy and places the result in @m_num, @m_denom, @b and @xbase, representing the function y(x) = m_num/m_denom * (x - xbase) + b that has the least-square distance from all points @x and @y. @@ -74027,30 +78607,30 @@ amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). > between them. It will not calculate the exact results if the differences > between neighbouring values are too small due to not being able to > represent sub-integer values during the calculations. - + %TRUE if the linear regression was successfully calculated + line="4674">%TRUE if the linear regression was successfully calculated Pairs of (x,y) values + line="4648">Pairs of (x,y) values Temporary scratch space used by the function + line="4649">Temporary scratch space used by the function number of (x,y) pairs + line="4650">number of (x,y) pairs numerator of calculated slope + line="4651">numerator of calculated slope denominator of calculated slope + line="4652">denominator of calculated slope Offset at Y-axis + line="4653">Offset at Y-axis Offset at X-axis + line="4654">Offset at X-axis R-squared + line="4655">R-squared @@ -74106,12 +78686,12 @@ amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). version="1.2"> Creates a #GstCapsFeatures from a string representation. - + line="649">Creates a #GstCapsFeatures from a string representation. + a new #GstCapsFeatures or + line="655">a new #GstCapsFeatures or %NULL when the string could not be parsed. @@ -74119,7 +78699,7 @@ amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). a string representation of a #GstCapsFeatures. + line="651">a string representation of a #GstCapsFeatures. @@ -74129,22 +78709,22 @@ amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). moved-to="Caps.from_string"> Converts @caps from a string representation. + line="2862">Converts @caps from a string representation. The implementation of serialization up to 1.20 would lead to unexpected results when there were nested #GstCaps / #GstStructure deeper than one level. - + a newly allocated #GstCaps + line="2871">a newly allocated #GstCaps a string to convert to #GstCaps + line="2864">a string to convert to #GstCaps @@ -74225,7 +78805,7 @@ pointer casts. introspectable="0"> Clears a reference to a #GstObject. + line="301">Clears a reference to a #GstObject. @object_ptr must not be %NULL. @@ -74235,7 +78815,7 @@ gst_object_unref() and the pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. - + @@ -74243,7 +78823,7 @@ pointer casts. a pointer to a #GstObject reference + line="303">a pointer to a #GstObject reference @@ -74254,7 +78834,7 @@ pointer casts. introspectable="0"> Clears a reference to a #GstStructure. + line="776">Clears a reference to a #GstStructure. @structure_ptr must not be %NULL. @@ -74264,7 +78844,7 @@ pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. - + @@ -74272,7 +78852,7 @@ pointer casts. a pointer to a #GstStructure reference + line="778">a pointer to a #GstStructure reference @@ -74282,14 +78862,14 @@ pointer casts. introspectable="0"> Tests if you can safely write into a context's structure or validly + line="88">Tests if you can safely write into a context's structure or validly modify the seqnum and timestamp fields. - + a #GstContext + line="90">a #GstContext @@ -74298,14 +78878,14 @@ modify the seqnum and timestamp fields. introspectable="0"> Checks if a context is writable. If not, a writable copy is made and + line="96">Checks if a context is writable. If not, a writable copy is made and returned. - + the context to make writable + line="98">the context to make writable @@ -74321,9 +78901,9 @@ returned. c:identifier="gst_debug_add_log_function"> Adds the logging function to the list of logging functions. + line="1739">Adds the logging function to the list of logging functions. Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. - + @@ -74335,7 +78915,7 @@ Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. destroy="2"> the function to use + line="1741">the function to use allow-none="1"> user data + line="1742">user data called when @user_data is not used anymore + line="1743">called when @user_data is not used anymore @@ -74360,14 +78940,14 @@ Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. version="1.14"> Adds a memory ringbuffer based debug logger that stores up to + line="3730">Adds a memory ringbuffer based debug logger that stores up to @max_size_per_thread bytes of logs per thread and times out threads after @thread_timeout seconds of inactivity. Logs can be fetched with gst_debug_ring_buffer_logger_get_logs() and the logger can be removed again with gst_debug_remove_ring_buffer_logger(). Only one logger at a time is possible. - + @@ -74375,13 +78955,13 @@ Only one logger at a time is possible. Maximum size of log per thread in bytes + line="3732">Maximum size of log per thread in bytes Timeout for threads in seconds + line="3733">Timeout for threads in seconds @@ -74390,14 +78970,14 @@ Only one logger at a time is possible. c:identifier="gst_debug_bin_to_dot_data"> To aid debugging applications one can use this method to obtain the whole + line="810">To aid debugging applications one can use this method to obtain the whole network of gstreamer elements that form the pipeline into a dot file. This data can be processed with graphviz to get an image. a string containing the pipeline in graphviz + line="819">a string containing the pipeline in graphviz dot format. @@ -74405,13 +78985,13 @@ dot format. the top-level pipeline that should be analyzed + line="812">the top-level pipeline that should be analyzed type of #GstDebugGraphDetails to use + line="813">type of #GstDebugGraphDetails to use @@ -74420,7 +79000,7 @@ dot format. c:identifier="gst_debug_bin_to_dot_file"> To aid debugging applications one can use this method to write out the whole + line="838">To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the pipeline into a dot file. This file can be processed with graphviz to get an image. @@ -74435,19 +79015,19 @@ This file can be processed with graphviz to get an image. the top-level pipeline that should be analyzed + line="840">the top-level pipeline that should be analyzed type of #GstDebugGraphDetails to use + line="841">type of #GstDebugGraphDetails to use output base filename (e.g. "myplayer") + line="842">output base filename (e.g. "myplayer") @@ -74456,7 +79036,7 @@ This file can be processed with graphviz to get an image. c:identifier="gst_debug_bin_to_dot_file_with_ts"> This works like gst_debug_bin_to_dot_file(), but adds the current timestamp + line="886">This works like gst_debug_bin_to_dot_file(), but adds the current timestamp to the filename, so that it can be used to take multiple snapshots. @@ -74466,19 +79046,19 @@ to the filename, so that it can be used to take multiple snapshots. the top-level pipeline that should be analyzed + line="888">the top-level pipeline that should be analyzed type of #GstDebugGraphDetails to use + line="889">type of #GstDebugGraphDetails to use output base filename (e.g. "myplayer") + line="890">output base filename (e.g. "myplayer") @@ -74487,14 +79067,14 @@ to the filename, so that it can be used to take multiple snapshots. c:identifier="gst_debug_construct_term_color"> Constructs a string that can be used for getting the desired color in color + line="1309">Constructs a string that can be used for getting the desired color in color terminals. You need to free the string after use. - + a string containing the color + line="1317">a string containing the color definition @@ -74502,7 +79082,7 @@ You need to free the string after use. the color info + line="1311">the color info @@ -74511,23 +79091,23 @@ You need to free the string after use. c:identifier="gst_debug_construct_win_color"> Constructs an integer that can be used for getting the desired color in + line="1330">Constructs an integer that can be used for getting the desired color in windows' terminals (cmd.exe). As there is no mean to underline, we simply ignore this attribute. This function returns 0 on non-windows machines. - + an integer containing the color definition + line="1340">an integer containing the color definition the color info + line="1332">the color info @@ -74536,14 +79116,14 @@ This function returns 0 on non-windows machines. c:identifier="gst_debug_get_all_categories"> Returns a snapshot of a all categories that are currently in use . This list + line="2288">Returns a snapshot of a all categories that are currently in use . This list may change anytime. The caller has to free the list after use. - + the list of + line="2295">the list of debug categories @@ -74555,12 +79135,12 @@ The caller has to free the list after use. version="1.2"> Changes the coloring mode for debug output. - + line="1944">Changes the coloring mode for debug output. + see @GstDebugColorMode for possible values. + line="1949">see @GstDebugColorMode for possible values. @@ -74568,23 +79148,23 @@ The caller has to free the list after use. c:identifier="gst_debug_get_default_threshold"> Returns the default threshold that is used for new categories. - + line="2008">Returns the default threshold that is used for new categories. + the default threshold level + line="2013">the default threshold level - + a stack trace, if libunwind or glibc backtrace are + line="3471">a stack trace, if libunwind or glibc backtrace are present, else %NULL. @@ -74592,7 +79172,7 @@ present, else %NULL. A set of #GstStackTraceFlags to determine how the stack trace should + line="3468">A set of #GstStackTraceFlags to determine how the stack trace should look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. @@ -74601,24 +79181,24 @@ look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. Checks if debugging output is activated. - + line="1979">Checks if debugging output is activated. + %TRUE, if debugging is activated + line="1984">%TRUE, if debugging is activated Checks if the debugging output should be colored. - + line="1930">Checks if the debugging output should be colored. + %TRUE, if the debug output should be colored. + line="1935">%TRUE, if the debug output should be colored. @@ -74627,19 +79207,19 @@ look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. Get the string representation of a debugging level - + line="1703">Get the string representation of a debugging level + the name + line="1709">the name the level to get the name for + line="1705">the level to get the name for @@ -74647,8 +79227,8 @@ look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. Logs the given message using the currently registered debugging handlers. - + line="508">Logs the given message using the currently registered debugging handlers. + @@ -74656,31 +79236,31 @@ look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. category to log + line="510">category to log level of the message is in + line="511">level of the message is in the file that emitted the message, usually the __FILE__ identifier + line="512">the file that emitted the message, usually the __FILE__ identifier the function that emitted the message + line="513">the function that emitted the message the line from that the message was emitted, usually __LINE__ + line="514">the line from that the message was emitted, usually __LINE__ the object this message relates to, + line="515">the object this message relates to, or %NULL if none a printf style format string + line="517">a printf style format string optional arguments for the format + line="518">optional arguments for the format @@ -74710,7 +79290,7 @@ look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. The default logging handler used by GStreamer. Logging functions get called + line="1560">The default logging handler used by GStreamer. Logging functions get called whenever a macro like GST_DEBUG or similar is used. By default this function is setup to output the message and additional info to stderr (or the log file specified via the GST_DEBUG_FILE environment variable) as received via @@ -74719,7 +79299,7 @@ specified via the GST_DEBUG_FILE environment variable) as received via You can add other handlers by using gst_debug_add_log_function(). And you can remove this handler by calling gst_debug_remove_log_function(gst_debug_log_default); - + @@ -74727,31 +79307,31 @@ gst_debug_remove_log_function(gst_debug_log_default); category to log + line="1562">category to log level of the message + line="1563">level of the message the file that emitted the message, usually the __FILE__ identifier + line="1564">the file that emitted the message, usually the __FILE__ identifier the function that emitted the message + line="1565">the function that emitted the message the line from that the message was emitted, usually __LINE__ + line="1566">the line from that the message was emitted, usually __LINE__ allow-none="1"> the object this message relates to, + line="1568">the object this message relates to, or %NULL if none the actual message + line="1567">the actual message allow-none="1"> the FILE* to log to + line="1570">the FILE* to log to @@ -74786,12 +79366,12 @@ gst_debug_remove_log_function(gst_debug_log_default); version="1.18"> Returns the string representation for the specified debug log message + line="1479">Returns the string representation for the specified debug log message formatted in the same way as gst_debug_log_default() (the default handler), without color. The purpose is to make it easy for custom log output handlers to get a log output that is identical to what the default handler would write out. - + @@ -74799,31 +79379,281 @@ would write out. category to log + line="1481">category to log + + + + level of the message + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the object this message relates to, + or %NULL if none + + + + the actual message + + + + + + Logs the given message using the currently registered debugging handlers. + + + + + + + category to log + + + + level of the message is in + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the identifier of the object this message + relates to, or %NULL if none. + + + + a printf style format string + + + + optional arguments for the format + + + + + + Logs the given message using the currently registered debugging handlers. + + + + + + + category to log + + + + level of the message is in + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the identifier of the object this message relates to + or %NULL if none + + + + a message string + + + + + + Logs the given message using the currently registered debugging handlers. + + + + + + + category to log + + + + level of the message is in + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the identifier of the object this message + relates to or %NULL if none. + + + + a printf style format string + + + + optional arguments for the format + + + + + + Logs the given message using the currently registered debugging handlers. + + + + + + + category to log level of the message + line="729">level of the message is in the file that emitted the message, usually the __FILE__ identifier + line="730">the file that emitted the message, usually the __FILE__ identifier the function that emitted the message + line="731">the function that emitted the message the line from that the message was emitted, usually __LINE__ + line="732">the line from that the message was emitted, usually __LINE__ allow-none="1"> the object this message relates to, + line="733">the object this message relates to, or %NULL if none - - the actual message - - - - - - Logs the given message using the currently registered debugging handlers. - - - - - - - category to log - - - - level of the message is in - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - - the identifier of the object this message - relates to, or %NULL if none. - - - - a printf style format string - - - - optional arguments for the format - - - - - - Logs the given message using the currently registered debugging handlers. - - - - - - - category to log - - - - level of the message is in - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - - the identifier of the object this message relates to - or %NULL if none - - a message string + line="735">a message string - Logs the given message using the currently registered debugging handlers. - + line="633">Logs the given message using the currently registered debugging handlers. + @@ -74984,178 +79688,117 @@ would write out. category to log + line="635">category to log level of the message is in + line="636">level of the message is in the file that emitted the message, usually the __FILE__ identifier + line="637">the file that emitted the message, usually the __FILE__ identifier the function that emitted the message + line="638">the function that emitted the message the line from that the message was emitted, usually __LINE__ + line="639">the line from that the message was emitted, usually __LINE__ - the identifier of the object this message - relates to or %NULL if none. - + line="640">the object this message relates to, + or %NULL if none + a printf style format string + line="642">a printf style format string optional arguments for the format + line="643">optional arguments for the format - + Logs the given message using the currently registered debugging handlers. - - - + line="1069">Returns a string that represents @ptr. This is safe to call with +%GstStructure, %GstCapsFeatures, %GstMiniObject s (e.g. %GstCaps, +%GstBuffer or %GstMessage), and %GObjects (e.g. %GstElement or %GstPad). + +The string representation is meant to be used for debugging purposes and +might change between GStreamer versions. + +Passing other kind of pointers might or might not work and is generally +unsafe to do. + + + a string containing a string + representation of the object + - - category to log - - - - level of the message is in - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - the object this message relates to, - or %NULL if none - - - - a message string - + line="1071">the object + - + Logs the given message using the currently registered debugging handlers. - - - + line="1185">Returns a string that represents @segments. + +The string representation is meant to be used for debugging purposes and +might change between GStreamer versions. + + + a string containing a string + representation of the segment + - - category to log - - - - level of the message is in - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - the object this message relates to, - or %NULL if none - - - - a printf style format string - - - - optional arguments for the format - + line="1187">the %GstSegment + @@ -75163,9 +79806,9 @@ would write out. c:identifier="gst_debug_print_stack_trace"> If libunwind, glibc backtrace or DbgHelp are present + line="3501">If libunwind, glibc backtrace or DbgHelp are present a stack trace is printed. - + @@ -75174,12 +79817,12 @@ a stack trace is printed. c:identifier="gst_debug_remove_log_function"> Removes all registered instances of the given logging functions. - + line="1813">Removes all registered instances of the given logging functions. + How many instances of the function were removed + line="1820">How many instances of the function were removed @@ -75190,7 +79833,7 @@ a stack trace is printed. scope="call"> the log function to remove, or %NULL to + line="1815">the log function to remove, or %NULL to remove the default log function @@ -75200,12 +79843,12 @@ a stack trace is printed. c:identifier="gst_debug_remove_log_function_by_data"> Removes all registered instances of log functions with the given user data. - + line="1849">Removes all registered instances of log functions with the given user data. + How many instances of the function were removed + line="1855">How many instances of the function were removed @@ -75215,7 +79858,7 @@ a stack trace is printed. allow-none="1"> user data of the log function to remove + line="1851">user data of the log function to remove @@ -75225,9 +79868,9 @@ a stack trace is printed. version="1.14"> Removes any previously added ring buffer logger with + line="3771">Removes any previously added ring buffer logger with gst_debug_add_ring_buffer_logger(). - + @@ -75237,13 +79880,13 @@ gst_debug_add_ring_buffer_logger(). version="1.14"> Fetches the current logs per thread from the ring buffer logger. See + line="3663">Fetches the current logs per thread from the ring buffer logger. See gst_debug_add_ring_buffer_logger() for details. - + NULL-terminated array of + line="3669">NULL-terminated array of strings with the debug output per thread @@ -75253,12 +79896,12 @@ strings with the debug output per thread If activated, debugging messages are sent to the debugging + line="1959">If activated, debugging messages are sent to the debugging handlers. It makes sense to deactivate it for speed issues. > This function is not threadsafe. It makes sense to only call it during initialization. - + @@ -75266,7 +79909,7 @@ during initialization. Whether to use debugging output or not + line="1961">Whether to use debugging output or not @@ -75276,10 +79919,10 @@ during initialization. version="1.2"> Changes the coloring mode for debug output. + line="1892">Changes the coloring mode for debug output. This function may be called before gst_init(). - + @@ -75287,7 +79930,7 @@ This function may be called before gst_init(). The coloring mode for debug output. See @GstDebugColorMode. + line="1894">The coloring mode for debug output. See @GstDebugColorMode. @@ -75297,10 +79940,10 @@ This function may be called before gst_init(). version="1.2"> Changes the coloring mode for debug output. + line="1908">Changes the coloring mode for debug output. This function may be called before gst_init(). - + @@ -75308,7 +79951,7 @@ This function may be called before gst_init(). The coloring mode for debug output. One of the following: + line="1910">The coloring mode for debug output. One of the following: "on", "auto", "off", "disable", "unix". @@ -75317,12 +79960,12 @@ This function may be called before gst_init(). Sets or unsets the use of coloured debugging output. + line="1874">Sets or unsets the use of coloured debugging output. Same as gst_debug_set_color_mode () with the argument being being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF. This function may be called before gst_init(). - + @@ -75330,7 +79973,7 @@ This function may be called before gst_init(). Whether to use colored output or not + line="1876">Whether to use colored output or not @@ -75339,11 +79982,11 @@ This function may be called before gst_init(). c:identifier="gst_debug_set_default_threshold"> Sets the default threshold to the given level and updates all categories to + line="1992">Sets the default threshold to the given level and updates all categories to use this threshold. This function may be called before gst_init(). - + @@ -75351,7 +79994,7 @@ This function may be called before gst_init(). level to set + line="1994">level to set @@ -75360,9 +80003,9 @@ This function may be called before gst_init(). c:identifier="gst_debug_set_threshold_for_name"> Sets all categories which match the given glob style pattern to the given + line="2075">Sets all categories which match the given glob style pattern to the given level. - + @@ -75370,13 +80013,13 @@ level. name of the categories to set + line="2077">name of the categories to set level to set them to + line="2078">level to set them to @@ -75386,11 +80029,11 @@ level. version="1.2"> Sets the debug logging wanted in the same form as with the GST_DEBUG + line="2396">Sets the debug logging wanted in the same form as with the GST_DEBUG environment variable. You can use wildcards such as `*`, but note that the order matters when you use wild cards, e.g. `foosrc:6,*src:3,*:2` sets everything to log level 2. - + @@ -75398,14 +80041,14 @@ everything to log level 2. comma-separated list of "category:level" pairs to be used + line="2398">comma-separated list of "category:level" pairs to be used as debug logging levels %TRUE to clear all previously-set debug levels before setting + line="2400">%TRUE to clear all previously-set debug levels before setting new thresholds %FALSE if adding the threshold described by @list to the one already set. @@ -75416,8 +80059,8 @@ everything to log level 2. c:identifier="gst_debug_unset_threshold_for_name"> Resets all categories with the given name back to the default level. - + line="2103">Resets all categories with the given name back to the default level. + @@ -75425,7 +80068,7 @@ everything to log level 2. name of the categories to set + line="2105">name of the categories to set @@ -75441,7 +80084,7 @@ be rendered with [graphviz] to multiple formats. Clean up any resources created by GStreamer in gst_init(). + line="1071">Clean up any resources created by GStreamer in gst_init(). It is normally not needed to call this function in a normal application as the resources will automatically be freed when the program terminates. @@ -75449,7 +80092,7 @@ This function is therefore mostly used by testsuites and other memory profiling tools. After this call GStreamer (including this method) should not be used anymore. - + @@ -75460,7 +80103,7 @@ After this call GStreamer (including this method) should not be used anymore.Registers a new #GstDynamicTypeFactory in the registry - + @@ -75671,19 +80314,19 @@ otherwise be made using gst_event_copy(). moved-to="EventType.get_flags"> Gets the #GstEventTypeFlags associated with @type. + line="197">Gets the #GstEventTypeFlags associated with @type. a #GstEventTypeFlags. + line="203">a #GstEventTypeFlags. a #GstEventType + line="199">a #GstEventType @@ -75693,19 +80336,19 @@ otherwise be made using gst_event_copy(). moved-to="EventType.get_name"> Get a printable name for the given event type. Do not modify or free. + line="157">Get a printable name for the given event type. Do not modify or free. a reference to the static name of the event. + line="163">a reference to the static name of the event. the event type + line="159">the event type @@ -75715,19 +80358,19 @@ otherwise be made using gst_event_copy(). moved-to="EventType.to_quark"> Get the unique quark for the given event type. + line="177">Get the unique quark for the given event type. the quark associated with the event type + line="183">the quark associated with the event type the event type + line="179">the event type @@ -75738,21 +80381,21 @@ otherwise be made using gst_event_copy(). version="1.22"> Converts the #GstEventType to an unsigned integer that + line="215">Converts the #GstEventType to an unsigned integer that represents the ordering of sticky events when re-sending them. A lower value represents a higher-priority event. an unsigned integer + line="223">an unsigned integer a #GstEventType + line="217">a #GstEventType @@ -75762,7 +80405,7 @@ A lower value represents a higher-priority event. throws="1"> Similar to g_filename_to_uri(), but attempts to handle relative file paths + line="910">Similar to g_filename_to_uri(), but attempts to handle relative file paths as well. Before converting @filename into an URI, it will be prefixed by the current working directory if it is a relative path, and then the path will be canonicalised so that it doesn't contain any './' or '../' segments. @@ -75772,7 +80415,7 @@ On Windows @filename should be in UTF-8 encoding. newly-allocated URI string, or NULL on error. The caller must + line="922">newly-allocated URI string, or NULL on error. The caller must free the URI string with g_free() when no longer needed. @@ -75780,7 +80423,7 @@ On Windows @filename should be in UTF-8 encoding. absolute or relative file name path + line="912">absolute or relative file name path @@ -75788,19 +80431,19 @@ On Windows @filename should be in UTF-8 encoding. Gets a string representing the given flow return. + line="235">Gets a string representing the given flow return. a static string with the name of the flow return. + line="241">a static string with the name of the flow return. a #GstFlowReturn to get the name of. + line="237">a #GstFlowReturn to get the name of. @@ -75808,12 +80451,12 @@ On Windows @filename should be in UTF-8 encoding. Get the unique quark for the given GstFlowReturn. + line="257">Get the unique quark for the given GstFlowReturn. the quark associated with the flow return or 0 if an + line="263">the quark associated with the flow return or 0 if an invalid return was specified. @@ -75821,7 +80464,7 @@ invalid return was specified. a #GstFlowReturn to get the quark of. + line="259">a #GstFlowReturn to get the quark of. @@ -76015,18 +80658,18 @@ is unknown. version="1.14"> This helper is mostly helpful for plugins that need to + line="358">This helper is mostly helpful for plugins that need to inspect the folder of the main executable to determine their set of features. When a plugin is initialized from the gst-plugin-scanner external process, the returned path will be the same as from the parent process. - + The path of the executable that + line="369">The path of the executable that initialized GStreamer, or %NULL if it could not be determined. @@ -76277,7 +80920,16 @@ which is then encapsulated in a GstProtectionMeta object and attached to the corresponding output buffer using the gst_buffer_add_protection_meta() function. The information in this attached GstProtectionMeta would be used by a downstream decrypter element to recover the original unencrypted -frame. +frame. + +In addition to the #GstProtectionMeta demuxers signal encrypted streams with +specific caps. The caps #GstStructure name will usually depend on the +encryption scheme, for instance Common Encryption will be signaled with +`application/x-cenc`. To prevent loss of information the media type of the +decrypted stream will be stored in a `original-media-type` string field. +Downstream elements can re-use that information, for instance decryptors can +set their source pad caps according to the `original-media-type` received on +their sink pad. introspectable="0"> Allocates, fills and returns a 0-terminated string from the printf style + line="2949">Allocates, fills and returns a 0-terminated string from the printf style @format string and corresponding arguments. See gst_info_vasprintf() for when this function is required. Free with g_free(). - + a newly allocated null terminated string or %NULL on any error + line="2961">a newly allocated null terminated string or %NULL on any error a printf style format string + line="2951">a printf style format string the printf arguments for @format + line="2952">the printf arguments for @format @@ -76373,30 +81025,30 @@ Free with g_free(). introspectable="0"> Allocates, fills and returns a null terminated string from the printf style + line="2922">Allocates, fills and returns a null terminated string from the printf style @format string and @args. See gst_info_vasprintf() for when this function is required. Free with g_free(). - + a newly allocated null terminated string or %NULL on any error + line="2934">a newly allocated null terminated string or %NULL on any error a printf style format string + line="2924">a printf style format string the va_list of printf arguments for @format + line="2925">the va_list of printf arguments for @format @@ -76407,7 +81059,7 @@ Free with g_free(). introspectable="0"> Allocates and fills a string large enough (including the terminating null + line="2896">Allocates and fills a string large enough (including the terminating null byte) to hold the specified printf style @format and @args. This function deals with the GStreamer specific printf specifiers @@ -76416,11 +81068,11 @@ in your @format string, you do not need to use this function and can use alternatives such as g_vasprintf(). Free @result with g_free(). - + the length of the string allocated into @result or -1 on any error + line="2912">the length of the string allocated into @result or -1 on any error @@ -76430,19 +81082,19 @@ Free @result with g_free(). transfer-ownership="full"> the resulting string + line="2898">the resulting string a printf style format string + line="2899">a printf style format string the va_list of printf arguments for @format + line="2900">the va_list of printf arguments for @format @@ -76450,7 +81102,7 @@ Free @result with g_free(). Initializes the GStreamer library, setting up internal path lists, + line="431">Initializes the GStreamer library, setting up internal path lists, registering built-in elements, and loading standard plugins. Unless the plugin registry is disabled at compile time, the registry will be @@ -76463,7 +81115,7 @@ for how to disable automatic registry updates. WARNING: This function will terminate your program if it was unable to initialize GStreamer for some reason. If you want your program to fall back, use gst_init_check() instead. - + @@ -76476,7 +81128,7 @@ use gst_init_check() instead. allow-none="1"> pointer to application's argc + line="433">pointer to application's argc allow-none="1"> pointer to application's argv + line="434">pointer to application's argv @@ -76497,17 +81149,17 @@ use gst_init_check() instead. Initializes the GStreamer library, setting up internal path lists, + line="380">Initializes the GStreamer library, setting up internal path lists, registering built-in elements, and loading standard plugins. This function will return %FALSE if GStreamer could not be initialized for some reason. If you want your program to fail fatally, use gst_init() instead. - + %TRUE if GStreamer could be initialized. + line="393">%TRUE if GStreamer could be initialized. @@ -76519,7 +81171,7 @@ use gst_init() instead. allow-none="1"> pointer to application's argc + line="382">pointer to application's argc allow-none="1"> pointer to application's argv + line="383">pointer to application's argv @@ -76553,7 +81205,7 @@ libraries that use GOption (see g_option_context_add_group() ). If you use this function, you should make sure you initialise the GLib threading system as one of the very first things in your program (see the example at the beginning of this section). - + Checks if @obj is a #GstCapsFeatures - + line="127">Checks if @obj is a #GstCapsFeatures + %TRUE if @obj is a #GstCapsFeatures %FALSE otherwise + line="132">%TRUE if @obj is a #GstCapsFeatures %FALSE otherwise @@ -76584,13 +81236,13 @@ threading system as one of the very first things in your program Use this function to check if GStreamer has been initialized with gst_init() + line="465">Use this function to check if GStreamer has been initialized with gst_init() or gst_init_check(). - + %TRUE if initialization has been done, %FALSE otherwise. + line="471">%TRUE if initialization has been done, %FALSE otherwise. @@ -76608,7 +81260,7 @@ or gst_init_check(). introspectable="0"> Create a #GstStructure to be used with #gst_element_message_full_with_details. + line="3898">Create a #GstStructure to be used with #gst_element_message_full_with_details. %NULL terminator required. @@ -76618,13 +81270,13 @@ or gst_init_check(). Name of the first field to set + line="3900">Name of the first field to set variable arguments in the same form as #GstStructure + line="3901">variable arguments in the same form as #GstStructure @@ -76734,13 +81386,13 @@ returned. - + Modifies a pointer to a #GstMessage to point to a different #GstMessage. The + line="3509">Modifies a pointer to a #GstMessage to point to a different #GstMessage. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old message is unreffed, the new one is reffed). @@ -76750,7 +81402,7 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< %TRUE if @new_message was different from @old_message + line="3523">%TRUE if @new_message was different from @old_message @@ -76762,7 +81414,7 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< allow-none="1"> pointer to a + line="3511">pointer to a pointer to a #GstMessage to be replaced. @@ -76772,30 +81424,30 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< allow-none="1"> pointer to a #GstMessage that will + line="3513">pointer to a #GstMessage that will replace the message pointed to by @old_message. - + Get a printable name for the given message type. Do not modify or free. + line="135">Get a printable name for the given message type. Do not modify or free. a reference to the static name of the message. + line="141">a reference to the static name of the message. the message type + line="137">the message type @@ -76805,32 +81457,78 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< moved-to="MessageType.to_quark"> Get the unique quark for the given message type. + line="155">Get the unique quark for the given message type. the quark associated with the message type + line="161">the quark associated with the message type the message type + line="157">the message type + + When a element like `tee` decides the allocation, each downstream element may +fill different parameters and pass them to gst_query_add_allocation_meta(). +In order to keep these parameters, a merge operation is needed. This +aggregate function can combine the parameters from @params0 and @param1, and +write the result back into @aggregated_params. + + + %TRUE if the parameters were successfully aggregated, %FALSE otherwise. + + + + + the GType of the API for which the parameters are being aggregated. + + + + This structure will be updated with the + combined parameters from both @params0 and @params1. + + + + a #GstStructure containing the new parameters to be aggregated. + + + + a #GstStructure containing the new parameters to be aggregated. + + + + - + an array of tags as strings. + line="397">an array of tags as strings. @@ -76839,7 +81537,7 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< an API + line="395">an API @@ -76849,25 +81547,25 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< moved-to="Meta.api_type_has_tag"> Check if @api was registered with @tag. - + line="375">Check if @api was registered with @tag. + %TRUE if @api was registered with @tag. + line="382">%TRUE if @api was registered with @tag. an API + line="377">an API the tag to check + line="378">the tag to check @@ -76877,44 +81575,124 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< moved-to="Meta.api_type_register"> Register and return a GType for the @api and associate it with + line="115">Register and return a GType for the @api and associate it with @tags. - + a unique GType for @api. + line="123">a unique GType for @api. an API to register + line="117">an API to register tags for @api + line="118">tags for @api + + This function sets the aggregator function for a specific API type. + + + + + + + the #GType of the API for which the aggregator function is being set. + + + + the aggregator function to be associated with the given API + type. + + + + + + Recreate a #GstMeta from serialized data returned by +gst_meta_serialize() and add it to @buffer. + +Note that the meta must have been previously registered by calling one of +`gst_*_meta_get_info ()` functions. + +@consumed is set to the number of bytes that can be skipped from @data to +find the next meta serialization, if any. In case of parsing error that does +not allow to determine that size, @consumed is set to 0. + + + the metadata owned by @buffer, or %NULL. + + + + + a #GstBuffer + + + + serialization data obtained from gst_meta_serialize() + + + + size of @data + + + + total size used by this meta, could be less than @size + + + + Lookup a previously registered meta info structure by its implementation name + line="623">Lookup a previously registered meta info structure by its implementation name @impl. - + a #GstMetaInfo with @impl, or + line="630">a #GstMetaInfo with @impl, or %NULL when no such metainfo exists. @@ -76922,25 +81700,91 @@ Either @new_message or the #GstMessage pointed to by @old_message may be %NULL.< the name + line="625">the name + + Creates a new structure that needs to be filled before being +registered. This structure should filled and then registered with +gst_meta_info_register(). + +Example: +```c +const GstMetaInfo * +gst_my_meta_get_info (void) +{ + static const GstMetaInfo *meta_info = NULL; + + if (g_once_init_enter ((GstMetaInfo **) & meta_info)) { + GstMetaInfo *info = gst_meta_info_new ( + gst_my_meta_api_get_type (), + "GstMyMeta", + sizeof (GstMyMeta)); + const GstMetaInfo *meta = NULL; + + info->init_func = my_meta_init; + info->free_func = my_meta_free; + info->transform_func = my_meta_transform; + info->serialize_func = my_meta_serialize; + info->deserialize_func = my_meta_deserialize; + meta = gst_meta_info_register (info); + g_once_init_leave ((GstMetaInfo **) & meta_info, (GstMetaInfo *) meta); + } + + return meta_info; +} +``` + + + a new #GstMetaInfo that needs to be filled + + + + + the type of the #GstMeta API + + + + the name of the #GstMeta implementation + + + + the size of the #GstMeta structure + + + + + moved-to="Meta.register" + introspectable="0"> Register a new #GstMeta implementation. + line="497">Register a new #GstMeta implementation. The same @info can be retrieved later with gst_meta_get_info() by using @impl as the key. - + a #GstMetaInfo that can be used to + line="511">a #GstMetaInfo that can be used to access metadata. @@ -76948,39 +81792,37 @@ access metadata. the type of the #GstMeta API + line="499">the type of the #GstMeta API the name of the #GstMeta implementation + line="500">the name of the #GstMeta implementation the size of the #GstMeta structure + line="501">the size of the #GstMeta structure - + a #GstMetaInitFunction + line="502">a #GstMetaInitFunction - + a #GstMetaFreeFunction + line="503">a #GstMetaFreeFunction - + a #GstMetaTransformFunction + line="504">a #GstMetaTransformFunction @@ -76992,7 +81834,7 @@ access metadata. version="1.20"> Register a new custom #GstMeta implementation, backed by an opaque + line="275">Register a new custom #GstMeta implementation, backed by an opaque structure holding a #GstStructure. The registered info can be retrieved later with gst_meta_get_info() by using @@ -77005,11 +81847,11 @@ writability of the buffer the meta is attached to. When @transform_func is %NULL, the meta and its backing #GstStructure will always be copied when the transform operation is copy, other operations are discarded, copy regions are ignored. - + a #GstMetaInfo that can be used to + line="297">a #GstMetaInfo that can be used to access metadata. @@ -77017,13 +81859,13 @@ access metadata. the name of the #GstMeta implementation + line="277">the name of the #GstMeta implementation tags for @api + line="278">tags for @api @@ -77037,7 +81879,7 @@ access metadata. destroy="4"> a #GstMetaTransformFunction + line="279">a #GstMetaTransformFunction @@ -77047,17 +81889,41 @@ access metadata. allow-none="1"> user data passed to @transform_func + line="280">user data passed to @transform_func #GDestroyNotify for user_data + line="281">#GDestroyNotify for user_data + + Simplified version of gst_meta_register_custom(), with no tags and no +transform function. + + + a #GstMetaInfo that can be used to access metadata. + + + + + the name of the #GstMeta implementation + + + + @@ -77178,15 +82044,15 @@ Either @newdata and the value pointed to by @olddata may be %NULL. introspectable="0"> Get a copy of the name of the pad. g_free() after usage. + line="1325">Get a copy of the name of the pad. g_free() after usage. MT safe. - + the pad to get the name from + line="1327">the pad to get the name from @@ -77195,17 +82061,17 @@ MT safe. introspectable="0"> Get the parent of @pad. This function increases the refcount + line="1334">Get the parent of @pad. This function increases the refcount of the parent object so you should gst_object_unref() it after usage. Can return %NULL if the pad did not have a parent. MT safe. - + the pad to get the parent of + line="1336">the pad to get the parent of @@ -77214,19 +82080,19 @@ MT safe. moved-to="PadMode.get_name"> Return the name of a pad mode, for use in debug messages mostly. + line="960">Return the name of a pad mode, for use in debug messages mostly. short mnemonic for pad mode @mode + line="966">short mnemonic for pad mode @mode the pad mode + line="962">the pad mode @@ -77245,19 +82111,19 @@ MT safe. introspectable="0"> Calls gst_pad_set_activate_function_full() with %NULL for the user_data and + line="1720">Calls gst_pad_set_activate_function_full() with %NULL for the user_data and notify. - + a #GstPad. + line="1722">a #GstPad. the #GstPadActivateFunction to set. + line="1723">the #GstPadActivateFunction to set. @@ -77266,19 +82132,19 @@ notify. introspectable="0"> Calls gst_pad_set_activatemode_function_full() with %NULL for the user_data and + line="1757">Calls gst_pad_set_activatemode_function_full() with %NULL for the user_data and notify. - + a #GstPad. + line="1759">a #GstPad. the #GstPadActivateModeFunction to set. + line="1760">the #GstPadActivateModeFunction to set. @@ -77287,19 +82153,19 @@ notify. introspectable="0"> Calls gst_pad_set_chain_function_full() with %NULL for the user_data and + line="1792">Calls gst_pad_set_chain_function_full() with %NULL for the user_data and notify. - + a sink #GstPad. + line="1794">a sink #GstPad. the #GstPadChainFunction to set. + line="1795">the #GstPadChainFunction to set. @@ -77308,19 +82174,19 @@ notify. introspectable="0"> Calls gst_pad_set_chain_list_function_full() with %NULL for the user_data and + line="1827">Calls gst_pad_set_chain_list_function_full() with %NULL for the user_data and notify. - + a sink #GstPad. + line="1829">a sink #GstPad. the #GstPadChainListFunction to set. + line="1830">the #GstPadChainListFunction to set. @@ -77329,19 +82195,19 @@ notify. introspectable="0"> Calls gst_pad_set_event_full_function_full() with %NULL for the user_data and + line="1944">Calls gst_pad_set_event_full_function_full() with %NULL for the user_data and notify. - + a #GstPad of either direction. + line="1946">a #GstPad of either direction. the #GstPadEventFullFunction to set. + line="1947">the #GstPadEventFullFunction to set. @@ -77350,19 +82216,19 @@ notify. introspectable="0"> Calls gst_pad_set_event_function_full() with %NULL for the user_data and + line="1900">Calls gst_pad_set_event_function_full() with %NULL for the user_data and notify. - + a #GstPad of either direction. + line="1902">a #GstPad of either direction. the #GstPadEventFunction to set. + line="1903">the #GstPadEventFunction to set. @@ -77371,19 +82237,19 @@ notify. introspectable="0"> Calls gst_pad_set_getrange_function_full() with %NULL for the user_data and + line="1864">Calls gst_pad_set_getrange_function_full() with %NULL for the user_data and notify. - + a source #GstPad. + line="1866">a source #GstPad. the #GstPadGetRangeFunction to set. + line="1867">the #GstPadGetRangeFunction to set. @@ -77392,19 +82258,19 @@ notify. introspectable="0"> Calls gst_pad_set_iterate_internal_links_function_full() with %NULL + line="2013">Calls gst_pad_set_iterate_internal_links_function_full() with %NULL for the user_data and notify. - + a #GstPad of either direction. + line="2015">a #GstPad of either direction. the #GstPadIterIntLinkFunction to set. + line="2016">the #GstPadIterIntLinkFunction to set. @@ -77413,19 +82279,19 @@ for the user_data and notify. introspectable="0"> Calls gst_pad_set_link_function_full() with %NULL + line="2047">Calls gst_pad_set_link_function_full() with %NULL for the user_data and notify. - + a #GstPad. + line="2049">a #GstPad. the #GstPadLinkFunction to set. + line="2050">the #GstPadLinkFunction to set. @@ -77434,19 +82300,19 @@ for the user_data and notify. introspectable="0"> Calls gst_pad_set_query_function_full() with %NULL for the user_data and + line="1980">Calls gst_pad_set_query_function_full() with %NULL for the user_data and notify. - + a #GstPad of either direction. + line="1982">a #GstPad of either direction. the #GstPadQueryFunction to set. + line="1983">the #GstPadQueryFunction to set. @@ -77455,19 +82321,19 @@ notify. introspectable="0"> Calls gst_pad_set_unlink_function_full() with %NULL + line="2090">Calls gst_pad_set_unlink_function_full() with %NULL for the user_data and notify. - + a #GstPad. + line="2092">a #GstPad. the #GstPadUnlinkFunction to set. + line="2093">the #GstPadUnlinkFunction to set. @@ -77612,12 +82478,12 @@ instance_init function. version="1.6"> Gets the global #GstMetaInfo describing the #GstParentBufferMeta meta. + line="2698">Gets the global #GstMetaInfo describing the #GstParentBufferMeta meta. The #GstMetaInfo + line="2703">The #GstMetaInfo @@ -77635,7 +82501,7 @@ one ghost pad for each direction will be created; if you expect multiple unlinked source pads or multiple unlinked sink pads and want them all ghosted, you will have to create the ghost pads yourself). - + - + moved-to="Preset.get_app_dir"> Gets the directory for application specific presets if set by the + line="1236">Gets the directory for application specific presets if set by the application. the directory or %NULL, don't free or modify + line="1242">the directory or %NULL, don't free or modify the string @@ -77996,21 +82862,21 @@ the string moved-to="Preset.set_app_dir"> Sets an extra directory as an absolute path that should be considered when + line="1214">Sets an extra directory as an absolute path that should be considered when looking for presets. Any presets in the application dir will shadow the system presets. %TRUE for success, %FALSE if the dir already has been set + line="1222">%TRUE for success, %FALSE if the dir already has been set the application specific preset dir + line="1216">the application specific preset dir @@ -78021,7 +82887,7 @@ system presets. introspectable="0"> Outputs a formatted message via the GLib print handler. The default print + line="2978">Outputs a formatted message via the GLib print handler. The default print handler simply outputs the message to stdout. This function will not append a new-line character at the end, unlike @@ -78034,7 +82900,7 @@ printf specifiers that are supported by GStreamer's debug logging system, such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. This function is primarily for printing debug output. - + @@ -78042,13 +82908,13 @@ This function is primarily for printing debug output. a printf style format string + line="2980">a printf style format string the printf arguments for @format + line="2981">the printf arguments for @format @@ -78059,7 +82925,7 @@ This function is primarily for printing debug output. introspectable="0"> Outputs a formatted message via the GLib error message handler. The default + line="3064">Outputs a formatted message via the GLib error message handler. The default handler simply outputs the message to stderr. This function will not append a new-line character at the end, unlike @@ -78072,7 +82938,7 @@ printf specifiers that are supported by GStreamer's debug logging system, such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. This function is primarily for printing debug output. - + @@ -78080,13 +82946,13 @@ This function is primarily for printing debug output. a printf style format string + line="3066">a printf style format string the printf arguments for @format + line="3067">the printf arguments for @format @@ -78097,7 +82963,7 @@ This function is primarily for printing debug output. introspectable="0"> Outputs a formatted message via the GLib error message handler. The default + line="3107">Outputs a formatted message via the GLib error message handler. The default handler simply outputs the message to stderr. This function will append a new-line character at the end, unlike @@ -78110,7 +82976,7 @@ printf specifiers that are supported by GStreamer's debug logging system, such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. This function is primarily for printing debug output. - + @@ -78118,13 +82984,13 @@ This function is primarily for printing debug output. a printf style format string + line="3109">a printf style format string the printf arguments for @format + line="3110">the printf arguments for @format @@ -78135,7 +83001,7 @@ This function is primarily for printing debug output. introspectable="0"> Outputs a formatted message via the GLib print handler. The default print + line="3021">Outputs a formatted message via the GLib print handler. The default print handler simply outputs the message to stdout. This function will append a new-line character at the end, unlike @@ -78148,7 +83014,7 @@ printf specifiers that are supported by GStreamer's debug logging system, such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. This function is primarily for printing debug output. - + @@ -78156,13 +83022,13 @@ This function is primarily for printing debug output. a printf style format string + line="3023">a printf style format string the printf arguments for @format + line="3024">the printf arguments for @format @@ -78172,13 +83038,13 @@ This function is primarily for printing debug output. version="1.14"> Iterates the supplied list of UUIDs and checks the GstRegistry for + line="205">Iterates the supplied list of UUIDs and checks the GstRegistry for all the decryptors supporting one of the supplied UUIDs. + line="214"> A null terminated array containing all the @system_identifiers supported by the set of available decryptors, or %NULL if no matches were found. @@ -78190,7 +83056,7 @@ the @system_identifiers supported by the set of available decryptors, or + line="207"> A null terminated array of strings that contains the UUID values of each protection system that is to be checked. @@ -78220,14 +83086,14 @@ protection system that is to be checked. version="1.6"> Iterates the supplied list of UUIDs and checks the GstRegistry for + line="167">Iterates the supplied list of UUIDs and checks the GstRegistry for an element that supports one of the supplied UUIDs. If more than one element matches, the system ID of the highest ranked element is selected. One of the strings from + line="177">One of the strings from @system_identifiers that indicates the highest ranked element that implements the protection system indicated by that system ID, or %NULL if no element has been found. @@ -78237,7 +83103,7 @@ element has been found. A null terminated array of strings + line="169">A null terminated array of strings that contains the UUID values of each protection system that is to be checked. @@ -78281,19 +83147,19 @@ checked. moved-to="QueryType.get_flags"> Gets the #GstQueryTypeFlags associated with @type. + line="167">Gets the #GstQueryTypeFlags associated with @type. a #GstQueryTypeFlags. + line="173">a #GstQueryTypeFlags. a #GstQueryType + line="169">a #GstQueryType @@ -78303,19 +83169,19 @@ checked. moved-to="QueryType.get_name"> Get a printable name for the given query type. Do not modify or free. + line="127">Get a printable name for the given query type. Do not modify or free. a reference to the static name of the query. + line="133">a reference to the static name of the query. the query type + line="129">the query type @@ -78325,19 +83191,19 @@ checked. moved-to="QueryType.to_quark"> Get the unique quark for the given query type. + line="147">Get the unique quark for the given query type. the quark associated with the query type + line="153">the quark associated with the query type the query type + line="149">the query type @@ -78345,7 +83211,7 @@ checked. - + @@ -78356,12 +83222,12 @@ checked. version="1.14"> Gets the global #GstMetaInfo describing the #GstReferenceTimestampMeta meta. - + line="2929">Gets the global #GstMetaInfo describing the #GstReferenceTimestampMeta meta. + The #GstMetaInfo + line="2934">The #GstMetaInfo @@ -78423,18 +83289,18 @@ you have an additional reference to it. Some functions in the GStreamer core might install a custom SIGSEGV handler + line="1302">Some functions in the GStreamer core might install a custom SIGSEGV handler to better catch and report errors to the application. Currently this feature is enabled by default when loading plugins. Applications might want to disable this behaviour with the gst_segtrap_set_enabled() function. This is typically done if the application wants to install its own handler without GStreamer interfering. - + %TRUE if GStreamer is allowed to install a custom SIGSEGV handler. + line="1313">%TRUE if GStreamer is allowed to install a custom SIGSEGV handler. @@ -78442,9 +83308,9 @@ wants to install its own handler without GStreamer interfering. c:identifier="gst_segtrap_set_enabled"> Applications might want to disable/enable the SIGSEGV handling of + line="1322">Applications might want to disable/enable the SIGSEGV handling of the GStreamer core. See gst_segtrap_is_enabled() for more information. - + @@ -78452,7 +83318,7 @@ the GStreamer core. See gst_segtrap_is_enabled() for more information. whether a custom SIGSEGV handler should be installed. + line="1324">whether a custom SIGSEGV handler should be installed. @@ -78481,22 +83347,6 @@ the GStreamer core. See gst_segtrap_is_enabled() for more information. - - - - - - - - - - - - - - @@ -78534,7 +83384,7 @@ the GStreamer core. See gst_segtrap_is_enabled() for more information. version="1.18"> Atomically modifies a pointer to point to a new structure. + line="800">Atomically modifies a pointer to point to a new structure. The #GstStructure @oldstr_ptr is pointing to is freed and @newstr is taken ownership over. @@ -78542,11 +83392,11 @@ Either @newstr and the value pointed to by @oldstr_ptr may be %NULL. It is a programming error if both @newstr and the value pointed to by @oldstr_ptr refer to the same, non-%NULL structure. - + %TRUE if @newstr was different from @oldstr_ptr + line="815">%TRUE if @newstr was different from @oldstr_ptr @@ -78558,7 +83408,7 @@ It is a programming error if both @newstr and the value pointed to by allow-none="1"> pointer to a place of + line="802">pointer to a place of a #GstStructure to take @@ -78568,7 +83418,7 @@ It is a programming error if both @newstr and the value pointed to by allow-none="1"> a new #GstStructure + line="804">a new #GstStructure @@ -78576,19 +83426,19 @@ It is a programming error if both @newstr and the value pointed to by Checks if the given type is already registered. + line="566">Checks if the given type is already registered. %TRUE if the type is already registered + line="572">%TRUE if the type is already registered name of the tag + line="568">name of the tag @@ -78597,20 +83447,20 @@ It is a programming error if both @newstr and the value pointed to by c:identifier="gst_tag_get_description"> Returns the human-readable description of this tag, You must not change or + line="627">Returns the human-readable description of this tag, You must not change or free this string. the human-readable description of this tag + line="634">the human-readable description of this tag the tag + line="629">the tag @@ -78618,19 +83468,19 @@ free this string. Gets the flag of @tag. + line="648">Gets the flag of @tag. the flag of this tag. + line="654">the flag of this tag. the tag + line="650">the tag @@ -78638,20 +83488,20 @@ free this string. Returns the human-readable name of this tag, You must not change or free + line="602">Returns the human-readable name of this tag, You must not change or free this string. the human-readable name of this tag + line="609">the human-readable name of this tag the tag + line="604">the tag @@ -78659,19 +83509,19 @@ this string. Gets the #GType used for this tag. + line="582">Gets the #GType used for this tag. the #GType of this tag + line="588">the #GType of this tag the tag + line="584">the tag @@ -78679,20 +83529,20 @@ this string. Checks if the given tag is fixed. A fixed tag can only contain one value. + line="668">Checks if the given tag is fixed. A fixed tag can only contain one value. Unfixed tags can contain lists of values. %TRUE, if the given tag is fixed. + line="675">%TRUE, if the given tag is fixed. tag to check + line="670">tag to check @@ -78702,7 +83552,7 @@ Unfixed tags can contain lists of values. moved-to="TagList.copy_value"> Copies the contents for the given tag into the value, + line="1475">Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. You must g_value_unset() the value after use. @@ -78710,7 +83560,7 @@ You must g_value_unset() the value after use. %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + line="1486">%TRUE, if a value was copied, %FALSE if the tag didn't exist in the given list. @@ -78721,19 +83571,19 @@ You must g_value_unset() the value after use. transfer-ownership="none"> uninitialized #GValue to copy into + line="1477">uninitialized #GValue to copy into list to get the tag from + line="1478">list to get the tag from tag to read out + line="1479">tag to read out @@ -78793,7 +83643,7 @@ function. See also: gst_tag_list_ref(). c:identifier="gst_tag_merge_strings_with_comma"> This is a convenience function for the func argument of gst_tag_register(). + line="435">This is a convenience function for the func argument of gst_tag_register(). It concatenates all given strings using a comma. The tag must be registered as a G_TYPE_STRING or this function will fail. @@ -78807,13 +83657,13 @@ as a G_TYPE_STRING or this function will fail. transfer-ownership="none"> uninitialized GValue to store result in + line="437">uninitialized GValue to store result in GValue to copy from + line="438">GValue to copy from @@ -78822,7 +83672,7 @@ as a G_TYPE_STRING or this function will fail. c:identifier="gst_tag_merge_use_first"> This is a convenience function for the func argument of gst_tag_register(). + line="418">This is a convenience function for the func argument of gst_tag_register(). It creates a copy of the first value from the list. @@ -78835,13 +83685,13 @@ It creates a copy of the first value from the list. transfer-ownership="none"> uninitialized GValue to store result in + line="420">uninitialized GValue to store result in GValue to copy from + line="421">GValue to copy from @@ -78851,7 +83701,7 @@ It creates a copy of the first value from the list. introspectable="0"> Registers a new tag type for the use with GStreamer's type system. If a type + line="475">Registers a new tag type for the use with GStreamer's type system. If a type with that name is already registered, that one is used. The old registration may have used a different type however. So don't rely on your supplied values. @@ -78880,31 +83730,31 @@ gst_tag_merge_strings_with_comma(). the name or identifier string + line="477">the name or identifier string a flag describing the type of tag info + line="478">a flag describing the type of tag info the type this data is in + line="479">the type this data is in human-readable name + line="480">human-readable name a human-readable description about this tag + line="481">a human-readable description about this tag allow-none="1"> function for merging multiple values of this tag, or %NULL + line="482">function for merging multiple values of this tag, or %NULL @@ -78923,7 +83773,7 @@ gst_tag_merge_strings_with_comma(). introspectable="0"> Registers a new tag type for the use with GStreamer's type system. + line="519">Registers a new tag type for the use with GStreamer's type system. Same as gst_tag_register(), but @name, @nick, and @blurb must be static strings or inlined strings, as they will not be copied. (GStreamer @@ -78937,31 +83787,31 @@ even from dynamically loaded plugins.) the name or identifier string (string constant) + line="521">the name or identifier string (string constant) a flag describing the type of tag info + line="522">a flag describing the type of tag info the type this data is in + line="523">the type this data is in human-readable name or short description (string constant) + line="524">human-readable name or short description (string constant) a human-readable description for this tag (string constant) + line="525">a human-readable description for this tag (string constant) allow-none="1"> function for merging multiple values of this tag, or %NULL + line="526">function for merging multiple values of this tag, or %NULL @@ -78980,13 +83830,13 @@ even from dynamically loaded plugins.) introspectable="0"> Copy #GstToc with all subentries (deep copy). + line="445">Copy #GstToc with all subentries (deep copy). #GstToc to copy. + line="447">#GstToc to copy. @@ -78995,13 +83845,13 @@ even from dynamically loaded plugins.) introspectable="0"> Copy #GstTocEntry with all subentries (deep copy). + line="411">Copy #GstTocEntry with all subentries (deep copy). #GstTocEntry to copy. + line="413">#GstTocEntry to copy. @@ -79028,12 +83878,12 @@ even from dynamically loaded plugins.) moved-to="TocEntryType.get_nick"> Converts @type to a string representation. + line="573">Converts @type to a string representation. Returns a human-readable string for @type. This string is + line="579">Returns a human-readable string for @type. This string is only for debugging purpose and should not be displayed in a user interface. @@ -79042,7 +83892,7 @@ even from dynamically loaded plugins.) a #GstTocEntryType. + line="575">a #GstTocEntryType. @@ -79088,13 +83938,13 @@ even from dynamically loaded plugins.) version="1.18"> Get a list of all active tracer objects owned by the tracing framework for + line="368">Get a list of all active tracer objects owned by the tracing framework for the entirety of the run-time of the process or till gst_deinit() is called. A #GList of + line="374">A #GList of #GstTracer objects @@ -79106,7 +83956,7 @@ the entirety of the run-time of the process or till gst_deinit() is called. Register @func to be called when the trace hook @detail is getting invoked. + line="350">Register @func to be called when the trace hook @detail is getting invoked. Use %NULL for @detail to register to all hooks. @@ -79116,30 +83966,23 @@ Use %NULL for @detail to register to all hooks. the tracer + line="352">the tracer the detailed hook + line="353">the detailed hook the callback + line="354">the callback - - - - - - - @@ -79231,20 +84074,20 @@ This function is typically called during an element's plugin initialization. Checks if @type is plugin API. See gst_type_mark_as_plugin_api() for + line="4929">Checks if @type is plugin API. See gst_type_mark_as_plugin_api() for details. - + %TRUE if @type is plugin API or %FALSE otherwise. + line="4937">%TRUE if @type is plugin API or %FALSE otherwise. a GType + line="4931">a GType allow-none="1"> What #GstPluginAPIFlags the plugin was marked with + line="4932">What #GstPluginAPIFlags the plugin was marked with @@ -79265,7 +84108,7 @@ details. version="1.18"> Marks @type as plugin API. This should be called in `class_init` of + line="4903">Marks @type as plugin API. This should be called in `class_init` of elements that expose new types (i.e. enums, flags or internal GObjects) via properties, signals or pad templates. @@ -79275,7 +84118,7 @@ documented via that library instead. By marking a type as plugin API it will be included in the documentation of the plugin that defines it. - + @@ -79283,13 +84126,13 @@ the plugin that defines it. a GType + line="4905">a GType a set of #GstPluginAPIFlags to further inform cache generation. + line="4906">a set of #GstPluginAPIFlags to further inform cache generation. @@ -79297,7 +84140,7 @@ the plugin that defines it. Forces GStreamer to re-scan its plugin paths and update the default + line="1990">Forces GStreamer to re-scan its plugin paths and update the default plugin registry. Applications will almost never need to call this function, it is only @@ -79313,11 +84156,11 @@ any elements or access the GStreamer registry while the update is in progress. Note that this function may block for a significant amount of time. - + %TRUE if the registry has been updated successfully (does not + line="2010">%TRUE if the registry has been updated successfully (does not imply that there were changes), otherwise %FALSE. @@ -79368,20 +84211,20 @@ Free-function: g_free version="1.6"> Parses a URI string into a new #GstUri object. Will return NULL if the URI + line="1644">Parses a URI string into a new #GstUri object. Will return NULL if the URI cannot be parsed. A new #GstUri object, or NULL. + line="1651">A new #GstUri object, or NULL. The URI string to parse. + line="1646">The URI string to parse. @@ -79392,7 +84235,7 @@ cannot be parsed. version="1.18"> Parses a URI string into a new #GstUri object. Will return NULL if the URI + line="1661">Parses a URI string into a new #GstUri object. Will return NULL if the URI cannot be parsed. This is identical to gst_uri_from_string() except that the userinfo and fragment components of the URI will not be unescaped while parsing. @@ -79409,14 +84252,14 @@ https://example.com/path#fragment which may contain a URI-escaped '#'. A new #GstUri object, or NULL. + line="1679">A new #GstUri object, or NULL. The URI string to parse. + line="1663">The URI string to parse. @@ -79530,13 +84373,13 @@ scheme followed by ":" and maybe a string identifying the location. version="1.6"> This is a convenience function to join two URI strings and return the result. + line="1918">This is a convenience function to join two URI strings and return the result. The returned string should be g_free()'d after use. A string representing the percent-encoded join of + line="1926">A string representing the percent-encoded join of the two URIs. @@ -79544,13 +84387,13 @@ The returned string should be g_free()'d after use. The percent-encoded base URI. + line="1920">The percent-encoded base URI. The percent-encoded reference URI to join to the @base_uri. + line="1921">The percent-encoded reference URI to join to the @base_uri. @@ -79560,27 +84403,27 @@ The returned string should be g_free()'d after use. moved-to="Uri.protocol_is_supported"> Checks if an element exists that supports the given URI protocol. Note + line="592">Checks if an element exists that supports the given URI protocol. Note that a positive return value does not imply that a subsequent call to gst_element_make_from_uri() is guaranteed to work. %TRUE + line="601">%TRUE Whether to check for a source or a sink + line="594">Whether to check for a source or a sink Protocol that should be checked for (e.g. "http" or "smb") + line="595">Protocol that should be checked for (e.g. "http" or "smb") @@ -79613,18 +84456,18 @@ start with a alphabetic character. See RFC 3986 Section 3.1. c:identifier="gst_util_array_binary_search"> Searches inside @array for @search_data by using the comparison function + line="3539">Searches inside @array for @search_data by using the comparison function @search_func. @array must be sorted ascending. As @search_data is always passed as second argument to @search_func it's not required that @search_data has the same type as the array elements. The complexity of this search function is O(log (num_elements)). - + The address of the found + line="3558">The address of the found element or %NULL if nothing was found @@ -79635,19 +84478,19 @@ element or %NULL if nothing was found allow-none="1"> the sorted input array + line="3541">the sorted input array number of elements in the array + line="3542">number of elements in the array size of every element in bytes + line="3543">size of every element in bytes closure="6"> function to compare two elements, @search_data will always be passed as second argument + line="3544">function to compare two + elements, @search_data will always be passed as second argument search mode that should be used + line="3546">search mode that should be used allow-none="1"> element that should be found + line="3547">element that should be found allow-none="1"> data to pass to @search_func + line="3548">data to pass to @search_func + + Returns smallest integral value not less than log2(v). + + + a computed #guint val. + + + + + a #guint32 value. + + + + Transforms a #gdouble to a fraction and simplifies + line="3771">Transforms a #gdouble to a fraction and simplifies the result. - + @@ -79699,7 +84565,7 @@ the result. #gdouble to transform + line="3773">#gdouble to transform transfer-ownership="full"> pointer to a #gint to hold the result numerator + line="3774">pointer to a #gint to hold the result numerator transfer-ownership="full"> pointer to a #gint to hold the result denominator + line="3775">pointer to a #gint to hold the result denominator @@ -79727,7 +84593,7 @@ the result. version="1.14"> Dumps the buffer memory into a hex representation. Useful for debugging. + line="96">Dumps the buffer memory into a hex representation. Useful for debugging. @@ -79736,7 +84602,7 @@ the result. a #GstBuffer whose memory to dump + line="98">a #GstBuffer whose memory to dump @@ -79744,7 +84610,7 @@ the result. Dumps the memory block into a hex representation. Useful for debugging. + line="83">Dumps the memory block into a hex representation. Useful for debugging. @@ -79753,7 +84619,7 @@ the result. a pointer to the memory to dump + line="85">a pointer to the memory to dump @@ -79761,46 +84627,93 @@ the result. the size of the memory block to dump + line="86">the size of the memory block to dump + + Compares the given filenames using natural ordering. + + + + + + + a filename to compare with @b + + + + a filename to compare with @a + + + + + + Returns smallest integral value not bigger than log2(v). + + + a computed #guint val. + + + + + a #guint32 value. + + + + Adds the fractions @a_n/@a_d and @b_n/@b_d and stores + line="4009">Adds the fractions @a_n/@a_d and @b_n/@b_d and stores the result in @res_n and @res_d. - + %FALSE on overflow, %TRUE otherwise. + line="4021">%FALSE on overflow, %TRUE otherwise. Numerator of first value + line="4011">Numerator of first value Denominator of first value + line="4012">Denominator of first value Numerator of second value + line="4013">Numerator of second value Denominator of second value + line="4014">Denominator of second value transfer-ownership="full"> Pointer to #gint to hold the result numerator + line="4015">Pointer to #gint to hold the result numerator transfer-ownership="full"> Pointer to #gint to hold the result denominator + line="4016">Pointer to #gint to hold the result denominator @@ -79827,38 +84740,38 @@ the result in @res_n and @res_d. c:identifier="gst_util_fraction_compare"> Compares the fractions @a_n/@a_d and @b_n/@b_d and returns + line="4074">Compares the fractions @a_n/@a_d and @b_n/@b_d and returns -1 if a < b, 0 if a = b and 1 if a > b. - + -1 if a < b; 0 if a = b; 1 if a > b. + line="4084">-1 if a < b; 0 if a = b; 1 if a > b. Numerator of first value + line="4076">Numerator of first value Denominator of first value + line="4077">Denominator of first value Numerator of second value + line="4078">Numerator of second value Denominator of second value + line="4079">Denominator of second value @@ -79867,38 +84780,38 @@ the result in @res_n and @res_d. c:identifier="gst_util_fraction_multiply"> Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores + line="3865">Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores the result in @res_n and @res_d. - + %FALSE on overflow, %TRUE otherwise. + line="3877">%FALSE on overflow, %TRUE otherwise. Numerator of first value + line="3867">Numerator of first value Denominator of first value + line="3868">Denominator of first value Numerator of second value + line="3869">Numerator of second value Denominator of second value + line="3870">Denominator of second value transfer-ownership="full"> Pointer to #gint to hold the result numerator + line="3871">Pointer to #gint to hold the result numerator transfer-ownership="full"> Pointer to #gint to hold the result denominator + line="3872">Pointer to #gint to hold the result denominator + + Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores +the result in @res_n and @res_d. + + + %FALSE on overflow, %TRUE otherwise. + + + + + Numerator of first value + + + + Denominator of first value + + + + Numerator of second value + + + + Denominator of second value + + + + Pointer to #gint to hold the result numerator + + + + Pointer to #gint to hold the result denominator + + + + Transforms a fraction to a #gdouble. - + line="3745">Transforms a fraction to a #gdouble. + @@ -79934,13 +84906,13 @@ the result in @res_n and @res_d. Fraction numerator as #gint + line="3747">Fraction numerator as #gint Fraction denominator #gint + line="3748">Fraction denominator #gint transfer-ownership="full"> pointer to a #gdouble for the result + line="3749">pointer to a #gdouble for the result @@ -79960,14 +84932,14 @@ the result in @res_n and @res_d. @value casted to #guint64 + line="320">@value casted to #guint64 The #gdouble value to convert guint64 double + line="318">The #gdouble value to convert guint64 double @@ -79977,7 +84949,7 @@ the result in @res_n and @res_d. version="1.12"> Get a property of type %GST_TYPE_ARRAY and transform it into a + line="260">Get a property of type %GST_TYPE_ARRAY and transform it into a #GValueArray. This allow language bindings to get GST_TYPE_ARRAY properties which are otherwise not an accessible type. @@ -79988,13 +84960,13 @@ properties which are otherwise not an accessible type. the object to set the array to + line="262">the object to set the array to the name of the property to set + line="263">the name of the property to set transfer-ownership="full"> a return #GValueArray + line="264">a return #GValueArray @@ -80013,7 +84985,7 @@ properties which are otherwise not an accessible type. filename="gst/gstutils.c" line="3520">Get a timestamp as GstClockTime to be used for interval measurements. The timestamp should not be interpreted in any other way. - + c:identifier="gst_util_greatest_common_divisor"> Calculates the greatest common divisor of @a + line="3631">Calculates the greatest common divisor of @a and @b. - + Greatest common divisor of @a and @b + line="3639">Greatest common divisor of @a and @b First value as #gint + line="3633">First value as #gint Second value as #gint + line="3634">Second value as #gint @@ -80053,26 +85025,26 @@ and @b. c:identifier="gst_util_greatest_common_divisor_int64"> Calculates the greatest common divisor of @a + line="3654">Calculates the greatest common divisor of @a and @b. - + Greatest common divisor of @a and @b + line="3662">Greatest common divisor of @a and @b First value as #gint64 + line="3656">First value as #gint64 Second value as #gint64 + line="3657">Second value as #gint64 @@ -80080,7 +85052,7 @@ and @b. Return a constantly incrementing group id. + line="4511">Return a constantly incrementing group id. This function is used to generate a new group-id for the stream-start event. @@ -80090,7 +85062,7 @@ This function never returns %GST_GROUP_ID_INVALID (which is 0) A constantly incrementing unsigned integer, which might + line="4521">A constantly incrementing unsigned integer, which might overflow back to 0 at some point. @@ -80101,14 +85073,14 @@ overflow back to 0 at some point. @value casted to #gdouble + line="305">@value casted to #gdouble The #guint64 value to convert to double + line="303">The #guint64 value to convert to double @@ -80117,14 +85089,14 @@ overflow back to 0 at some point. c:identifier="gst_util_seqnum_compare"> Compare two sequence numbers, handling wraparound. + line="855">Compare two sequence numbers, handling wraparound. The current implementation just returns (gint32)(@s1 - @s2). A negative number if @s1 is before @s2, 0 if they are equal, or a + line="864">A negative number if @s1 is before @s2, 0 if they are equal, or a positive number if @s1 is after @s2. @@ -80132,13 +85104,13 @@ positive number if @s1 is after @s2. A sequence number. + line="857">A sequence number. Another sequence number. + line="858">Another sequence number. @@ -80146,7 +85118,7 @@ positive number if @s1 is after @s2. Return a constantly incrementing sequence number. + line="826">Return a constantly incrementing sequence number. This function is used internally to GStreamer to be able to determine which events and messages are "the same". For example, elements may set the seqnum @@ -80158,7 +85130,7 @@ This function never returns %GST_SEQNUM_INVALID (which is 0). A constantly incrementing 32-bit unsigned integer, which might + line="838">A constantly incrementing 32-bit unsigned integer, which might overflow at some point. Use gst_util_seqnum_compare() to make sure you handle wraparound correctly. @@ -80168,7 +85140,7 @@ you handle wraparound correctly. c:identifier="gst_util_set_object_arg"> Converts the string value to the type of the objects argument and + line="171">Converts the string value to the type of the objects argument and sets the argument with it. Note that this function silently returns if @object has no property named @@ -80181,19 +85153,19 @@ Note that this function silently returns if @object has no property named the object to set the argument of + line="173">the object to set the argument of the name of the argument to set + line="174">the name of the argument to set the string value to set + line="175">the string value to set @@ -80203,7 +85175,7 @@ Note that this function silently returns if @object has no property named version="1.12"> Transfer a #GValueArray to %GST_TYPE_ARRAY and set this value on the + line="225">Transfer a #GValueArray to %GST_TYPE_ARRAY and set this value on the specified property name. This allow language bindings to set GST_TYPE_ARRAY properties which are otherwise not an accessible type. @@ -80214,19 +85186,19 @@ properties which are otherwise not an accessible type. the object to set the array to + line="227">the object to set the array to the name of the property to set + line="228">the name of the property to set a #GValueArray containing the values + line="229">a #GValueArray containing the values @@ -80235,7 +85207,7 @@ properties which are otherwise not an accessible type. c:identifier="gst_util_set_value_from_string"> Converts the string to the type of the value and + line="140">Converts the string to the type of the value and sets the value with it. Note that this function is dangerous as it does not return any indication @@ -80251,21 +85223,66 @@ if the conversion worked or not. transfer-ownership="none"> the value to set + line="142">the value to set the string to get the value from + line="143">the string to get the value from + + Calculates the simpler representation of @numerator and @denominator and +update both values with the resulting simplified fraction. + +Simplify a fraction using a simple continued fraction decomposition. +The idea here is to convert fractions such as 333333/10000000 to 1/30 +using 32 bit arithmetic only. The algorithm is not perfect and relies +upon two arbitrary parameters to remove non-significative terms from +the simple continued fraction decomposition. Using 8 and 333 for +@n_terms and @threshold respectively seems to give nice results. + + + + + + + First value as #gint + + + + Second value as #gint + + + + non-significative terms (typical value: 8) + + + + threshold (typical value: 333) + + + + Scale @val by the rational number @num / @denom, avoiding overflows and + line="646">Scale @val by the rational number @num / @denom, avoiding overflows and underflows and without loss of precision. This function can potentially be very slow if val and num are both @@ -80274,7 +85291,7 @@ greater than G_MAXUINT32. @val * @num / @denom. In the case of an overflow, this + line="658">@val * @num / @denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer it is truncated. See also gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(), @@ -80286,19 +85303,19 @@ gst_util_uint64_scale_int_ceil(). the number to scale + line="648">the number to scale the numerator of the scale ratio + line="649">the numerator of the scale ratio the denominator of the scale ratio + line="650">the denominator of the scale ratio @@ -80307,7 +85324,7 @@ gst_util_uint64_scale_int_ceil(). c:identifier="gst_util_uint64_scale_ceil"> Scale @val by the rational number @num / @denom, avoiding overflows and + line="696">Scale @val by the rational number @num / @denom, avoiding overflows and underflows and without loss of precision. This function can potentially be very slow if val and num are both @@ -80316,7 +85333,7 @@ greater than G_MAXUINT32. @val * @num / @denom. In the case of an overflow, this + line="708">@val * @num / @denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded up. See also gst_util_uint64_scale(), gst_util_uint64_scale_round(), @@ -80328,19 +85345,19 @@ gst_util_uint64_scale_int_ceil(). the number to scale + line="698">the number to scale the numerator of the scale ratio + line="699">the numerator of the scale ratio the denominator of the scale ratio + line="700">the denominator of the scale ratio @@ -80349,14 +85366,14 @@ gst_util_uint64_scale_int_ceil(). c:identifier="gst_util_uint64_scale_int"> Scale @val by the rational number @num / @denom, avoiding overflows and + line="755">Scale @val by the rational number @num / @denom, avoiding overflows and underflows and without loss of precision. @num must be non-negative and @denom must be positive. @val * @num / @denom. In the case of an overflow, this + line="765">@val * @num / @denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is truncated. See also gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(), @@ -80368,19 +85385,19 @@ gst_util_uint64_scale_ceil(). guint64 (such as a #GstClockTime) to scale. + line="757">guint64 (such as a #GstClockTime) to scale. numerator of the scale factor. + line="758">numerator of the scale factor. denominator of the scale factor. + line="759">denominator of the scale factor. @@ -80389,14 +85406,14 @@ gst_util_uint64_scale_ceil(). c:identifier="gst_util_uint64_scale_int_ceil"> Scale @val by the rational number @num / @denom, avoiding overflows and + line="803">Scale @val by the rational number @num / @denom, avoiding overflows and underflows and without loss of precision. @num must be non-negative and @denom must be positive. @val * @num / @denom. In the case of an overflow, this + line="813">@val * @num / @denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded up. See also gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), @@ -80408,19 +85425,19 @@ gst_util_uint64_scale_ceil(). guint64 (such as a #GstClockTime) to scale. + line="805">guint64 (such as a #GstClockTime) to scale. numerator of the scale factor. + line="806">numerator of the scale factor. denominator of the scale factor. + line="807">denominator of the scale factor. @@ -80429,14 +85446,14 @@ gst_util_uint64_scale_ceil(). c:identifier="gst_util_uint64_scale_int_round"> Scale @val by the rational number @num / @denom, avoiding overflows and + line="778">Scale @val by the rational number @num / @denom, avoiding overflows and underflows and without loss of precision. @num must be non-negative and @denom must be positive. @val * @num / @denom. In the case of an overflow, this + line="788">@val * @num / @denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded to the nearest integer (half-way cases are rounded up). See also gst_util_uint64_scale_int(), @@ -80448,19 +85465,19 @@ gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(). guint64 (such as a #GstClockTime) to scale. + line="780">guint64 (such as a #GstClockTime) to scale. numerator of the scale factor. + line="781">numerator of the scale factor. denominator of the scale factor. + line="782">denominator of the scale factor. @@ -80469,7 +85486,7 @@ gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(). c:identifier="gst_util_uint64_scale_round"> Scale @val by the rational number @num / @denom, avoiding overflows and + line="671">Scale @val by the rational number @num / @denom, avoiding overflows and underflows and without loss of precision. This function can potentially be very slow if val and num are both @@ -80478,7 +85495,7 @@ greater than G_MAXUINT32. @val * @num / @denom. In the case of an overflow, this + line="683">@val * @num / @denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded to the nearest integer (half-way cases are rounded up). See also gst_util_uint64_scale(), @@ -80490,19 +85507,19 @@ gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(). the number to scale + line="673">the number to scale the numerator of the scale ratio + line="674">the numerator of the scale ratio the denominator of the scale ratio + line="675">the denominator of the scale ratio @@ -80510,25 +85527,25 @@ gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(). Determines if @value1 and @value2 can be compared. + line="6022">Determines if @value1 and @value2 can be compared. %TRUE if the values can be compared + line="6029">%TRUE if the values can be compared a value to compare + line="6024">a value to compare another value to compare + line="6025">another value to compare @@ -80537,27 +85554,27 @@ gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(). c:identifier="gst_value_can_intersect"> Determines if intersecting two values will produce a valid result. + line="6304">Determines if intersecting two values will produce a valid result. Two values will produce a valid intersection if they have the same type. %TRUE if the values can intersect + line="6313">%TRUE if the values can intersect a value to intersect + line="6306">a value to intersect another value to intersect + line="6307">another value to intersect @@ -80565,25 +85582,25 @@ type. Checks if it's possible to subtract @subtrahend from @minuend. + line="6568">Checks if it's possible to subtract @subtrahend from @minuend. %TRUE if a subtraction is possible + line="6575">%TRUE if a subtraction is possible the value to subtract from + line="6570">the value to subtract from the value to subtract + line="6571">the value to subtract @@ -80591,7 +85608,7 @@ type. Determines if @value1 and @value2 can be non-trivially unioned. + line="6197">Determines if @value1 and @value2 can be non-trivially unioned. Any two values can be trivially unioned by adding both of them to a GstValueList. However, certain types have the possibility to be unioned in a simpler way. For example, an integer range @@ -80602,7 +85619,7 @@ be unioned, this function returns %TRUE. %TRUE if there is a function allowing the two values to + line="6210">%TRUE if there is a function allowing the two values to be unioned. @@ -80610,13 +85627,13 @@ be unioned. a value to union + line="6199">a value to union another value to union + line="6200">another value to union @@ -80624,7 +85641,7 @@ be unioned. Compares @value1 and @value2. If @value1 and @value2 cannot be + line="6116">Compares @value1 and @value2. If @value1 and @value2 cannot be compared, the function returns GST_VALUE_UNORDERED. Otherwise, if @value1 is greater than @value2, GST_VALUE_GREATER_THAN is returned. If @value1 is less than @value2, GST_VALUE_LESS_THAN is returned. @@ -80633,20 +85650,20 @@ If the values are equal, GST_VALUE_EQUAL is returned. comparison result + line="6127">comparison result a value to compare + line="6118">a value to compare another value to compare + line="6119">another value to compare @@ -80654,13 +85671,13 @@ If the values are equal, GST_VALUE_EQUAL is returned. Tries to deserialize a string into the type specified by the given GValue. + line="6754">Tries to deserialize a string into the type specified by the given GValue. If the operation succeeds, %TRUE is returned, %FALSE otherwise. %TRUE on success + line="6763">%TRUE on success @@ -80670,14 +85687,14 @@ If the operation succeeds, %TRUE is returned, %FALSE otherwise. transfer-ownership="none"> #GValue to fill with contents of + line="6756">#GValue to fill with contents of deserialization string to deserialize + line="6758">string to deserialize @@ -80687,14 +85704,14 @@ If the operation succeeds, %TRUE is returned, %FALSE otherwise. version="1.20"> Tries to deserialize a string into the type specified by the given GValue. + line="6801">Tries to deserialize a string into the type specified by the given GValue. @pspec may be used to guide the deserializing of nested members. If the operation succeeds, %TRUE is returned, %FALSE otherwise. %TRUE on success + line="6812">%TRUE on success @@ -80704,14 +85721,14 @@ If the operation succeeds, %TRUE is returned, %FALSE otherwise. transfer-ownership="none"> #GValue to fill with contents of + line="6803">#GValue to fill with contents of deserialization string to deserialize + line="6805">string to deserialize allow-none="1"> the #GParamSpec describing the expected value + line="6806">the #GParamSpec describing the expected value @@ -80728,7 +85745,7 @@ If the operation succeeds, %TRUE is returned, %FALSE otherwise. Fixate @src into a new value @dest. + line="6911">Fixate @src into a new value @dest. For ranges, the first element is taken. For lists and arrays, the first item is fixated and returned. If @src is already fixed, this function returns %FALSE. @@ -80736,20 +85753,20 @@ If @src is already fixed, this function returns %FALSE. %TRUE if @dest contains a fixated version of @src. + line="6921">%TRUE if @dest contains a fixated version of @src. the #GValue destination + line="6913">the #GValue destination the #GValue to fixate + line="6914">the #GValue to fixate @@ -80758,32 +85775,32 @@ If @src is already fixed, this function returns %FALSE. c:identifier="gst_value_fraction_multiply"> Multiplies the two #GValue items containing a #GST_TYPE_FRACTION and sets + line="7137">Multiplies the two #GValue items containing a #GST_TYPE_FRACTION and sets @product to the product of the two fractions. %FALSE in case of an error (like integer overflow), %TRUE otherwise. + line="7146">%FALSE in case of an error (like integer overflow), %TRUE otherwise. a GValue initialized to #GST_TYPE_FRACTION + line="7139">a GValue initialized to #GST_TYPE_FRACTION a GValue initialized to #GST_TYPE_FRACTION + line="7140">a GValue initialized to #GST_TYPE_FRACTION a GValue initialized to #GST_TYPE_FRACTION + line="7141">a GValue initialized to #GST_TYPE_FRACTION @@ -80792,31 +85809,31 @@ If @src is already fixed, this function returns %FALSE. c:identifier="gst_value_fraction_subtract"> Subtracts the @subtrahend from the @minuend and sets @dest to the result. + line="7172">Subtracts the @subtrahend from the @minuend and sets @dest to the result. %FALSE in case of an error (like integer overflow), %TRUE otherwise. + line="7180">%FALSE in case of an error (like integer overflow), %TRUE otherwise. a GValue initialized to #GST_TYPE_FRACTION + line="7174">a GValue initialized to #GST_TYPE_FRACTION a GValue initialized to #GST_TYPE_FRACTION + line="7175">a GValue initialized to #GST_TYPE_FRACTION a GValue initialized to #GST_TYPE_FRACTION + line="7176">a GValue initialized to #GST_TYPE_FRACTION @@ -80824,19 +85841,19 @@ If @src is already fixed, this function returns %FALSE. Gets the bitmask specified by @value. + line="7657">Gets the bitmask specified by @value. the bitmask. + line="7663">the bitmask. a GValue initialized to #GST_TYPE_BITMASK + line="7659">a GValue initialized to #GST_TYPE_BITMASK @@ -80861,21 +85878,21 @@ a reference to @v. Gets the contents of @value. The reference count of the returned + line="2216">Gets the contents of @value. The reference count of the returned #GstCaps will not be modified, therefore the caller must take one before getting rid of the @value. the contents of @value + line="2224">the contents of @value a GValue initialized to GST_TYPE_CAPS + line="2218">a GValue initialized to GST_TYPE_CAPS @@ -80884,19 +85901,19 @@ before getting rid of the @value. c:identifier="gst_value_get_caps_features"> Gets the contents of @value. + line="3107">Gets the contents of @value. the contents of @value + line="3113">the contents of @value a GValue initialized to GST_TYPE_CAPS_FEATURES + line="3109">a GValue initialized to GST_TYPE_CAPS_FEATURES @@ -80905,19 +85922,19 @@ before getting rid of the @value. c:identifier="gst_value_get_double_range_max"> Gets the maximum of the range specified by @value. + line="1850">Gets the maximum of the range specified by @value. the maximum of the range + line="1856">the maximum of the range a GValue initialized to GST_TYPE_DOUBLE_RANGE + line="1852">a GValue initialized to GST_TYPE_DOUBLE_RANGE @@ -80926,19 +85943,19 @@ before getting rid of the @value. c:identifier="gst_value_get_double_range_min"> Gets the minimum of the range specified by @value. + line="1834">Gets the minimum of the range specified by @value. the minimum of the range + line="1840">the minimum of the range a GValue initialized to GST_TYPE_DOUBLE_RANGE + line="1836">a GValue initialized to GST_TYPE_DOUBLE_RANGE @@ -80948,19 +85965,19 @@ before getting rid of the @value. version="1.6"> Retrieve the flags field of a GstFlagSet @value. + line="7816">Retrieve the flags field of a GstFlagSet @value. the flags field of the flagset instance. + line="7822">the flags field of the flagset instance. a GValue initialized to #GST_TYPE_FLAG_SET + line="7818">a GValue initialized to #GST_TYPE_FLAG_SET @@ -80970,19 +85987,19 @@ before getting rid of the @value. version="1.6"> Retrieve the mask field of a GstFlagSet @value. + line="7834">Retrieve the mask field of a GstFlagSet @value. the mask field of the flagset instance. + line="7840">the mask field of the flagset instance. a GValue initialized to #GST_TYPE_FLAG_SET + line="7836">a GValue initialized to #GST_TYPE_FLAG_SET @@ -80991,19 +86008,19 @@ before getting rid of the @value. c:identifier="gst_value_get_fraction_denominator"> Gets the denominator of the fraction specified by @value. + line="7121">Gets the denominator of the fraction specified by @value. the denominator of the fraction. + line="7127">the denominator of the fraction. a GValue initialized to #GST_TYPE_FRACTION + line="7123">a GValue initialized to #GST_TYPE_FRACTION @@ -81012,19 +86029,19 @@ before getting rid of the @value. c:identifier="gst_value_get_fraction_numerator"> Gets the numerator of the fraction specified by @value. + line="7105">Gets the numerator of the fraction specified by @value. the numerator of the fraction. + line="7111">the numerator of the fraction. a GValue initialized to #GST_TYPE_FRACTION + line="7107">a GValue initialized to #GST_TYPE_FRACTION @@ -81033,19 +86050,19 @@ before getting rid of the @value. c:identifier="gst_value_get_fraction_range_max"> Gets the maximum of the range specified by @value. + line="2114">Gets the maximum of the range specified by @value. the maximum of the range + line="2120">the maximum of the range a GValue initialized to GST_TYPE_FRACTION_RANGE + line="2116">a GValue initialized to GST_TYPE_FRACTION_RANGE @@ -81054,19 +86071,19 @@ before getting rid of the @value. c:identifier="gst_value_get_fraction_range_min"> Gets the minimum of the range specified by @value. + line="2091">Gets the minimum of the range specified by @value. the minimum of the range + line="2097">the minimum of the range a GValue initialized to GST_TYPE_FRACTION_RANGE + line="2093">a GValue initialized to GST_TYPE_FRACTION_RANGE @@ -81075,19 +86092,19 @@ before getting rid of the @value. c:identifier="gst_value_get_int64_range_max"> Gets the maximum of the range specified by @value. + line="1671">Gets the maximum of the range specified by @value. the maximum of the range + line="1677">the maximum of the range a GValue initialized to GST_TYPE_INT64_RANGE + line="1673">a GValue initialized to GST_TYPE_INT64_RANGE @@ -81096,19 +86113,19 @@ before getting rid of the @value. c:identifier="gst_value_get_int64_range_min"> Gets the minimum of the range specified by @value. + line="1655">Gets the minimum of the range specified by @value. the minimum of the range + line="1661">the minimum of the range a GValue initialized to GST_TYPE_INT64_RANGE + line="1657">a GValue initialized to GST_TYPE_INT64_RANGE @@ -81117,19 +86134,19 @@ before getting rid of the @value. c:identifier="gst_value_get_int64_range_step"> Gets the step of the range specified by @value. + line="1687">Gets the step of the range specified by @value. the step of the range + line="1693">the step of the range a GValue initialized to GST_TYPE_INT64_RANGE + line="1689">a GValue initialized to GST_TYPE_INT64_RANGE @@ -81138,19 +86155,19 @@ before getting rid of the @value. c:identifier="gst_value_get_int_range_max"> Gets the maximum of the range specified by @value. + line="1425">Gets the maximum of the range specified by @value. the maximum of the range + line="1431">the maximum of the range a GValue initialized to GST_TYPE_INT_RANGE + line="1427">a GValue initialized to GST_TYPE_INT_RANGE @@ -81159,19 +86176,19 @@ before getting rid of the @value. c:identifier="gst_value_get_int_range_min"> Gets the minimum of the range specified by @value. + line="1409">Gets the minimum of the range specified by @value. the minimum of the range + line="1415">the minimum of the range a GValue initialized to GST_TYPE_INT_RANGE + line="1411">a GValue initialized to GST_TYPE_INT_RANGE @@ -81180,19 +86197,19 @@ before getting rid of the @value. c:identifier="gst_value_get_int_range_step"> Gets the step of the range specified by @value. + line="1441">Gets the step of the range specified by @value. the step of the range + line="1447">the step of the range a GValue initialized to GST_TYPE_INT_RANGE + line="1443">a GValue initialized to GST_TYPE_INT_RANGE @@ -81202,15 +86219,15 @@ before getting rid of the @value. introspectable="0"> Receives a #GstSample as the value of @v. Does not return a reference to + line="187">Receives a #GstSample as the value of @v. Does not return a reference to the sample, so the pointer is only valid for as long as the caller owns a reference to @v. - + a #GValue to query + line="189">a #GValue to query @@ -81218,19 +86235,19 @@ a reference to @v. c:identifier="gst_value_get_structure"> Gets the contents of @value. + line="3009">Gets the contents of @value. the contents of @value + line="3015">the contents of @value a GValue initialized to GST_TYPE_STRUCTURE + line="3011">a GValue initialized to GST_TYPE_STRUCTURE @@ -81239,7 +86256,7 @@ a reference to @v. c:identifier="gst_value_init_and_copy"> Initialises the target value to be of the same type as source and then copies + line="6659">Initialises the target value to be of the same type as source and then copies the contents from source to target. @@ -81252,13 +86269,13 @@ the contents from source to target. transfer-ownership="none"> the target value + line="6661">the target value the source value + line="6662">the source value @@ -81266,7 +86283,7 @@ the contents from source to target. Calculates the intersection of two values. If the values have + line="6385">Calculates the intersection of two values. If the values have a non-empty intersection, the value representing the intersection is placed in @dest, unless %NULL. If the intersection is non-empty, @dest is not modified. @@ -81274,7 +86291,7 @@ is placed in @dest, unless %NULL. If the intersection is non-empty, %TRUE if the intersection is non-empty + line="6399">%TRUE if the intersection is non-empty @@ -81286,7 +86303,7 @@ is placed in @dest, unless %NULL. If the intersection is non-empty, allow-none="1"> + line="6387"> a uninitialized #GValue that will hold the calculated intersection value. May be %NULL if the resulting set if not needed. @@ -81295,13 +86312,13 @@ is placed in @dest, unless %NULL. If the intersection is non-empty, a value to intersect + line="6391">a value to intersect another value to intersect + line="6392">another value to intersect @@ -81309,7 +86326,7 @@ is placed in @dest, unless %NULL. If the intersection is non-empty, Tests if the given GValue, if available in a GstStructure (or any other + line="6863">Tests if the given GValue, if available in a GstStructure (or any other container) contains a "fixed" (which means: one value) or an "unfixed" (which means: multiple possible values, such as data lists or data ranges) value. @@ -81317,14 +86334,14 @@ ranges) value. true if the value is "fixed". + line="6872">true if the value is "fixed". the #GValue to check + line="6865">the #GValue to check @@ -81332,25 +86349,25 @@ ranges) value. Check that @value1 is a subset of @value2. + line="4512">Check that @value1 is a subset of @value2. %TRUE is @value1 is a subset of @value2 + line="4519">%TRUE is @value1 is a subset of @value2 a #GValue + line="4514">a #GValue a #GValue + line="4515">a #GValue @@ -81358,7 +86375,7 @@ ranges) value. Registers functions to perform calculations on #GValue items of a given + line="6634">Registers functions to perform calculations on #GValue items of a given type. Each type can only be added once. @@ -81368,7 +86385,7 @@ type. Each type can only be added once. structure containing functions to register + line="6636">structure containing functions to register @@ -81376,7 +86393,7 @@ type. Each type can only be added once. tries to transform the given @value into a string representation that allows + line="6702">tries to transform the given @value into a string representation that allows getting back this string later on using gst_value_deserialize(). Free-function: g_free @@ -81384,7 +86401,7 @@ Free-function: g_free the serialization for @value + line="6711">the serialization for @value or %NULL if none exists @@ -81392,7 +86409,7 @@ or %NULL if none exists a #GValue to serialize + line="6704">a #GValue to serialize @@ -81400,7 +86417,7 @@ or %NULL if none exists Sets @value to the bitmask specified by @bitmask. + line="7642">Sets @value to the bitmask specified by @bitmask. @@ -81409,13 +86426,13 @@ or %NULL if none exists a GValue initialized to #GST_TYPE_BITMASK + line="7644">a GValue initialized to #GST_TYPE_BITMASK the bitmask + line="7645">the bitmask @@ -81443,7 +86460,7 @@ or %NULL if none exists Sets the contents of @value to @caps. A reference to the + line="2198">Sets the contents of @value to @caps. A reference to the provided @caps will be taken by the @value. @@ -81453,13 +86470,13 @@ provided @caps will be taken by the @value. a GValue initialized to GST_TYPE_CAPS + line="2200">a GValue initialized to GST_TYPE_CAPS the caps to set the value to + line="2201">the caps to set the value to @@ -81468,7 +86485,7 @@ provided @caps will be taken by the @value. c:identifier="gst_value_set_caps_features"> Sets the contents of @value to @features. + line="3090">Sets the contents of @value to @features. @@ -81477,13 +86494,13 @@ provided @caps will be taken by the @value. a GValue initialized to GST_TYPE_CAPS_FEATURES + line="3092">a GValue initialized to GST_TYPE_CAPS_FEATURES the features to set the value to + line="3093">the features to set the value to @@ -81492,7 +86509,7 @@ provided @caps will be taken by the @value. c:identifier="gst_value_set_double_range"> Sets @value to the range specified by @start and @end. + line="1816">Sets @value to the range specified by @start and @end. @@ -81501,19 +86518,19 @@ provided @caps will be taken by the @value. a GValue initialized to GST_TYPE_DOUBLE_RANGE + line="1818">a GValue initialized to GST_TYPE_DOUBLE_RANGE the start of the range + line="1819">the start of the range the end of the range + line="1820">the end of the range @@ -81523,7 +86540,7 @@ provided @caps will be taken by the @value. version="1.6"> Sets @value to the flags and mask values provided in @flags and @mask. + line="7794">Sets @value to the flags and mask values provided in @flags and @mask. The @flags value indicates the values of flags, the @mask represents which bits in the flag value have been set, and which are "don't care" @@ -81534,19 +86551,19 @@ which bits in the flag value have been set, and which are "don't care" a GValue initialized to %GST_TYPE_FLAG_SET + line="7796">a GValue initialized to %GST_TYPE_FLAG_SET The value of the flags set or unset + line="7797">The value of the flags set or unset The mask indicate which flags bits must match for comparisons + line="7798">The mask indicate which flags bits must match for comparisons @@ -81554,7 +86571,7 @@ which bits in the flag value have been set, and which are "don't care" Sets @value to the fraction specified by @numerator over @denominator. + line="7066">Sets @value to the fraction specified by @numerator over @denominator. The fraction gets reduced to the smallest numerator and denominator, and if necessary the sign is moved to the numerator. @@ -81565,19 +86582,19 @@ and if necessary the sign is moved to the numerator. a GValue initialized to #GST_TYPE_FRACTION + line="7068">a GValue initialized to #GST_TYPE_FRACTION the numerator of the fraction + line="7069">the numerator of the fraction the denominator of the fraction + line="7070">the denominator of the fraction @@ -81586,7 +86603,7 @@ and if necessary the sign is moved to the numerator. c:identifier="gst_value_set_fraction_range"> Sets @value to the range specified by @start and @end. + line="2016">Sets @value to the range specified by @start and @end. @@ -81595,19 +86612,19 @@ and if necessary the sign is moved to the numerator. a GValue initialized to GST_TYPE_FRACTION_RANGE + line="2018">a GValue initialized to GST_TYPE_FRACTION_RANGE the start of the range (a GST_TYPE_FRACTION GValue) + line="2019">the start of the range (a GST_TYPE_FRACTION GValue) the end of the range (a GST_TYPE_FRACTION GValue) + line="2020">the end of the range (a GST_TYPE_FRACTION GValue) @@ -81616,7 +86633,7 @@ and if necessary the sign is moved to the numerator. c:identifier="gst_value_set_fraction_range_full"> Sets @value to the range specified by @numerator_start/@denominator_start + line="2045">Sets @value to the range specified by @numerator_start/@denominator_start and @numerator_end/@denominator_end. @@ -81626,31 +86643,31 @@ and @numerator_end/@denominator_end. a GValue initialized to GST_TYPE_FRACTION_RANGE + line="2047">a GValue initialized to GST_TYPE_FRACTION_RANGE the numerator start of the range + line="2048">the numerator start of the range the denominator start of the range + line="2049">the denominator start of the range the numerator end of the range + line="2050">the numerator end of the range the denominator end of the range + line="2051">the denominator end of the range @@ -81659,7 +86676,7 @@ and @numerator_end/@denominator_end. c:identifier="gst_value_set_int64_range"> Sets @value to the range specified by @start and @end. + line="1641">Sets @value to the range specified by @start and @end. @@ -81668,19 +86685,19 @@ and @numerator_end/@denominator_end. a GValue initialized to GST_TYPE_INT64_RANGE + line="1643">a GValue initialized to GST_TYPE_INT64_RANGE the start of the range + line="1644">the start of the range the end of the range + line="1645">the end of the range @@ -81689,7 +86706,7 @@ and @numerator_end/@denominator_end. c:identifier="gst_value_set_int64_range_step"> Sets @value to the range specified by @start, @end and @step. + line="1617">Sets @value to the range specified by @start, @end and @step. @@ -81698,25 +86715,25 @@ and @numerator_end/@denominator_end. a GValue initialized to GST_TYPE_INT64_RANGE + line="1619">a GValue initialized to GST_TYPE_INT64_RANGE the start of the range + line="1620">the start of the range the end of the range + line="1621">the end of the range the step of the range + line="1622">the step of the range @@ -81725,7 +86742,7 @@ and @numerator_end/@denominator_end. c:identifier="gst_value_set_int_range"> Sets @value to the range specified by @start and @end. + line="1395">Sets @value to the range specified by @start and @end. @@ -81734,19 +86751,19 @@ and @numerator_end/@denominator_end. a GValue initialized to GST_TYPE_INT_RANGE + line="1397">a GValue initialized to GST_TYPE_INT_RANGE the start of the range + line="1398">the start of the range the end of the range + line="1399">the end of the range @@ -81755,7 +86772,7 @@ and @numerator_end/@denominator_end. c:identifier="gst_value_set_int_range_step"> Sets @value to the range specified by @start, @end and @step. + line="1369">Sets @value to the range specified by @start, @end and @step. @@ -81764,25 +86781,25 @@ and @numerator_end/@denominator_end. a GValue initialized to GST_TYPE_INT_RANGE + line="1371">a GValue initialized to GST_TYPE_INT_RANGE the start of the range + line="1372">the start of the range the end of the range + line="1373">the end of the range the step of the range + line="1374">the step of the range @@ -81792,18 +86809,18 @@ and @numerator_end/@denominator_end. introspectable="0"> Sets @b as the value of @v. Caller retains reference to sample. - + line="171">Sets @b as the value of @v. Caller retains reference to sample. + a #GValue to receive the data + line="173">a #GValue to receive the data a #GstSample to assign to the GstValue + line="174">a #GstSample to assign to the GstValue @@ -81811,7 +86828,7 @@ and @numerator_end/@denominator_end. c:identifier="gst_value_set_structure"> Sets the contents of @value to @structure. + line="2992">Sets the contents of @value to @structure. @@ -81820,13 +86837,13 @@ and @numerator_end/@denominator_end. a GValue initialized to GST_TYPE_STRUCTURE + line="2994">a GValue initialized to GST_TYPE_STRUCTURE the structure to set the value to + line="2995">the structure to set the value to @@ -81834,13 +86851,13 @@ and @numerator_end/@denominator_end. Subtracts @subtrahend from @minuend and stores the result in @dest. + line="6503">Subtracts @subtrahend from @minuend and stores the result in @dest. Note that this means subtraction as in sets, not as in mathematics. %TRUE if the subtraction is not empty + line="6515">%TRUE if the subtraction is not empty @@ -81852,7 +86869,7 @@ Note that this means subtraction as in sets, not as in mathematics. allow-none="1"> the destination value + line="6505">the destination value for the result if the subtraction is not empty. May be %NULL, in which case the resulting set will not be computed, which can give a fair speedup. @@ -81861,13 +86878,13 @@ Note that this means subtraction as in sets, not as in mathematics. the value to subtract from + line="6509">the value to subtract from the value to subtract + line="6510">the value to subtract @@ -81897,30 +86914,30 @@ Note that this means subtraction as in sets, not as in mathematics. introspectable="0"> Sets @b as the value of @v. Caller gives away reference to sample. - + line="179">Sets @b as the value of @v. Caller gives away reference to sample. + a #GValue to receive the data + line="181">a #GValue to receive the data a #GstSample to assign to the GstValue + line="182">a #GstSample to assign to the GstValue Creates a GValue corresponding to the union of @value1 and @value2. + line="6237">Creates a GValue corresponding to the union of @value1 and @value2. %TRUE if the union succeeded. + line="6245">%TRUE if the union succeeded. @@ -81930,28 +86947,84 @@ Note that this means subtraction as in sets, not as in mathematics. transfer-ownership="none"> the destination value + line="6239">the destination value a value to union + line="6240">a value to union another value to union + line="6241">another value to union + + Allocates a new #GstVecDeque object with an initial +queue size of @initial_size. + + + a new #GstVecDeque object + + + + + Initial size of the new queue + + + + + + Allocates a new #GstVecDeque object for elements (e.g. structures) +of size @struct_size, with an initial queue size of @initial_size. + + + a new #GstVecDeque object + + + + + Size of each element (e.g. structure) in the array + + + + Initial size of the new queue + + + + Gets the version number of the GStreamer library. - + line="1254">Gets the version number of the GStreamer library. + @@ -81962,7 +87035,7 @@ Note that this means subtraction as in sets, not as in mathematics. transfer-ownership="full"> pointer to a guint to store the major version number + line="1256">pointer to a guint to store the major version number transfer-ownership="full"> pointer to a guint to store the minor version number + line="1257">pointer to a guint to store the minor version number transfer-ownership="full"> pointer to a guint to store the micro version number + line="1258">pointer to a guint to store the micro version number transfer-ownership="full"> pointer to a guint to store the nano version number + line="1259">pointer to a guint to store the nano version number @@ -81997,13 +87070,13 @@ Note that this means subtraction as in sets, not as in mathematics. This function returns a string that is useful for describing this version + line="1277">This function returns a string that is useful for describing this version of GStreamer to the outside world: user agent strings, logging, ... - + a newly allocated string describing this version + line="1283">a newly allocated string describing this version of GStreamer. diff --git a/generator/src/main/resources/gir/Gtk-4.0.gir b/generator/src/main/resources/gir/Gtk-4.0.gir index 05a2763..4958aa8 100644 --- a/generator/src/main/resources/gir/Gtk-4.0.gir +++ b/generator/src/main/resources/gir/Gtk-4.0.gir @@ -31,14 +31,402 @@ and/or use gtk-doc annotations. --> + + An attribute for the background color, expressed as an RGB value +encoded in a string using the format: `{r8},{g8},{b8}`. + + + + + An attribute for the font family name. + + + + + An attribute for the foreground color, expressed as an RGB value +encoded in a string using the format: `{r8},{g8},{b8}`. + + + + + An attribute for the overline style. + +Possible values are: + +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE_NONE] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE_SINGLE] + + + + + The "none" overline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE]. + + + + + The "single" overline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE]. + + + + + An attribute for the font size, expressed in points. + + + + + An attribute for the font stretch type. + +Possible values are: + +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_ULTRA_CONDENSED] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_EXTRA_CONDENSED] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_CONDENSED] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_SEMI_CONDENSED] + + + + + The "condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "extra condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "extra expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "normal" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "semi condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "semi expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "ultra condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + The "ultra expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. + + + + + An attribute for strikethrough text. + +Possible values are `true` or `false`. + + + + + An attribute for the font style. + +Possible values are: + +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_NORMAL] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_OBLIQUE] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_ITALIC] + + + + + The "italic" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. + + + + + The "normal" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. + + + + + The "oblique" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. + + + + + An attribute for the underline style. + +Possible values are: + +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_NONE] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_SINGLE] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_DOUBLE] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_ERROR] + + + + + The "double" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. + + + + + The "error" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. + + + + + The "none" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. + + + + + The "single" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. + + + + + An attribute for the font variant. + +Possible values are: + +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_SMALL_CAPS] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_ALL_SMALL_CAPS] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_PETITE_CAPS] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_ALL_PETITE_CAPS] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_UNICASE] +- [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_TITLE_CAPS] + + + + + The "all petite caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. + + + + + The "all small caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. + + + + + The "petite caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. + + + + + The "small caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. + + + + + The "title caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. + + + + + The "unicase" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. + + + + + An attribute for the font weight. + + + An undefined value. The accessible attribute is either unset, or its + line="1577">An undefined value. The accessible attribute is either unset, or its value is undefined. - + - + @@ -225,8 +613,7 @@ value is undefined. glib:type-struct="ATContextClass"> `GtkATContext` is an abstract class provided by GTK to communicate to -platform-specific assistive technologies API. + line="21">Communicates with platform-specific assistive technologies API. Each platform supported by GTK implements a `GtkATContext` subclass, and is responsible for updating the accessible state in response to state @@ -235,7 +622,7 @@ changes in `GtkAccessible`. Creates a new `GtkATContext` instance for the given accessible role, + line="690">Creates a new `GtkATContext` instance for the given accessible role, accessible instance, and display connection. The `GtkATContext` implementation being instantiated will depend on the @@ -244,26 +631,26 @@ platform. the `GtkATContext` + line="702">the `GtkATContext` the accessible role used by the `GtkATContext` + line="692">the accessible role used by the `GtkATContext` the `GtkAccessible` implementation using the `GtkATContext` + line="693">the `GtkAccessible` implementation using the `GtkATContext` the `GdkDisplay` used by the `GtkATContext` + line="694">the `GdkDisplay` used by the `GtkATContext` @@ -271,22 +658,21 @@ platform. - Retrieves the `GtkAccessible` using this context. + line="448">Retrieves the `GtkAccessible` using this context. a `GtkAccessible` + line="454">a `GtkAccessible` a `GtkATContext` + line="450">a `GtkATContext` @@ -294,22 +680,21 @@ platform. - Retrieves the accessible role of this context. + line="488">Retrieves the accessible role of this context. a `GtkAccessibleRole` + line="494">a `GtkAccessibleRole` a `GtkATContext` + line="490">a `GtkATContext` @@ -319,11 +704,9 @@ platform. construct-only="1" transfer-ownership="none" getter="get_accessible"> - The `GtkAccessible` that created the `GtkATContext` instance. + line="266">The `GtkAccessible` that created the `GtkATContext` instance. transfer-ownership="none" getter="get_accessible_role" default-value="GTK_ACCESSIBLE_ROLE_NONE"> - The accessible role used by the AT context. + line="250">The accessible role used by the AT context. Depending on the given role, different states and properties can be set or retrieved. @@ -345,13 +726,13 @@ set or retrieved. The `GdkDisplay` for the `GtkATContext`. + line="278">The `GdkDisplay` for the `GtkATContext`. Emitted when the attributes of the accessible for the + line="290">Emitted when the attributes of the accessible for the `GtkATContext` instance change. @@ -373,8 +754,7 @@ set or retrieved. glib:get-type="gtk_about_dialog_get_type"> The `GtkAboutDialog` offers a simple way to display information about -a program. + line="58">Displays information about a program. The shown information includes the programs' logo, name, copyright, website and license. It is also possible to give credits to the authors, @@ -383,7 +763,10 @@ documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the `About` option from the `Help` menu. All parts of the dialog are optional. -![An example GtkAboutDialog](aboutdialog.png) +<picture> + <source srcset="aboutdialot-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkAboutDialog" src="aboutdialog.png"> +</picture> About dialogs often contain links and email addresses. `GtkAboutDialog` displays these as clickable links. By default, it calls [method@Gtk.FileLauncher.launch] @@ -394,14 +777,14 @@ To specify a person with an email address, use a string like `Edgar Allan Poe <edgar@poe.com>`. To specify a website with a title, use a string like `GTK team https://www.gtk.org`. -To make constructing a `GtkAboutDialog` as convenient as possible, you can +To make constructing an about dialog as convenient as possible, you can use the function [func@Gtk.show_about_dialog] which constructs and shows a dialog and keeps it around so that it can be shown again. Note that GTK sets a default title of `_("About %s")` on the dialog window (where `%s` is replaced by the name of the application, but in order to ensure proper translation of the title, applications should -set the title property explicitly when constructing a `GtkAboutDialog`, +set the title property explicitly when constructing an about dialog, as shown in the following example: ```c @@ -416,6 +799,12 @@ gtk_show_about_dialog (NULL, NULL); ``` +## Shortcuts and Gestures + +`GtkAboutDialog` supports the following keyboard shortcuts: + +- <kbd>Escape</kbd> closes the window. + ## CSS nodes `GtkAboutDialog` has a single CSS node with the name `window` and style @@ -429,12 +818,12 @@ class `.aboutdialog`. Creates a new `GtkAboutDialog`. - + line="2224">Creates a new `GtkAboutDialog`. + a newly created `GtkAboutDialog` + line="2229">a newly created `GtkAboutDialog` @@ -442,8 +831,8 @@ class `.aboutdialog`. c:identifier="gtk_about_dialog_add_credit_section"> Creates a new section in the "Credits" page. - + line="2387">Creates a new section in the "Credits" page. + @@ -451,19 +840,19 @@ class `.aboutdialog`. A `GtkAboutDialog` + line="2389">an about dialog The name of the section + line="2390">The name of the section The people who belong to that section + line="2391">the people who belong to that section @@ -473,16 +862,15 @@ class `.aboutdialog`. - Returns the names of the artists which are displayed + line="1557">Returns the names of the artists which are displayed in the credits page. - + A + line="1564">A `NULL`-terminated string array containing the artists @@ -492,7 +880,7 @@ in the credits page. a `GtkAboutDialog` + line="1559">an about dialog @@ -500,16 +888,15 @@ in the credits page. - Returns the names of the authors which are displayed + line="1470">Returns the names of the authors which are displayed in the credits page. - + A + line="1477">A `NULL`-terminated string array containing the authors @@ -519,7 +906,7 @@ in the credits page. a `GtkAboutDialog` + line="1472">an about dialog @@ -527,22 +914,21 @@ in the credits page. - Returns the comments string. - + line="1202">Returns the comments string. + The comments + line="1208">The comments a `GtkAboutDialog` + line="1204">an about dialog @@ -550,22 +936,21 @@ in the credits page. - Returns the copyright string. - + line="1153">Returns the copyright string. + The copyright string + line="1159">The copyright string a `GtkAboutDialog` + line="1155">an about dialog @@ -573,16 +958,15 @@ in the credits page. - Returns the name of the documenters which are displayed + line="1513">Returns the name of the documenters which are displayed in the credits page. - + A + line="1520">A `NULL`-terminated string array containing the documenters @@ -592,7 +976,7 @@ in the credits page. a `GtkAboutDialog` + line="1515">an about dialog @@ -600,22 +984,21 @@ in the credits page. - Returns the license information. - + line="1252">Returns the license information. + The license information + line="1258">The license information a `GtkAboutDialog` + line="1254">an about dialog @@ -623,22 +1006,21 @@ in the credits page. - Retrieves the license type. - + line="2371">Retrieves the license type. + a [enum@Gtk.License] value + line="2377">a [enum@Gtk.License] value a `GtkAboutDialog` + line="2373">an about dialog @@ -646,15 +1028,14 @@ in the credits page. - Returns the paintable displayed as logo in the about dialog. - + line="1659">Returns the paintable displayed as logo in the about dialog. + the paintable displayed as + line="1665">the paintable displayed as logo or `NULL` if the logo is unset or has been set via [method@Gtk.AboutDialog.set_logo_icon_name] @@ -663,7 +1044,7 @@ in the credits page. a `GtkAboutDialog` + line="1661">an about dialog @@ -671,15 +1052,14 @@ in the credits page. - Returns the icon name displayed as logo in the about dialog. - + line="1706">Returns the icon name displayed as logo in the about dialog. + the icon name displayed as logo, + line="1712">the icon name displayed as logo, or `NULL` if the logo has been set via [method@Gtk.AboutDialog.set_logo] @@ -687,7 +1067,7 @@ in the credits page. a `GtkAboutDialog` + line="1708">an about dialog @@ -695,22 +1075,21 @@ in the credits page. - Returns the program name displayed in the about dialog. - + line="1050">Returns the program name displayed in the about dialog. + The program name + line="1056">the program name a `GtkAboutDialog` + line="1052">an about dialog @@ -718,23 +1097,21 @@ in the credits page. - Returns the system information that is shown in the about dialog. - + line="1307">Returns the system information that is shown in the about dialog. + the system information + line="1313">the system information a `GtkAboutDialog` + line="1309">an about dialog @@ -742,24 +1119,22 @@ in the credits page. - Returns the translator credits string which is displayed + line="1601">Returns the translator credits string which is displayed in the credits page. - + The translator credits string + line="1608">The translator credits string a `GtkAboutDialog` + line="1603">an about dialog @@ -767,22 +1142,21 @@ in the credits page. - Returns the version string. - + line="1113">Returns the version string. + The version string + line="1119">The version string a `GtkAboutDialog` + line="1115">an about dialog @@ -790,22 +1164,21 @@ in the credits page. - Returns the website URL. - + line="1390">Returns the website URL. + The website URL + line="1396">The website URL a `GtkAboutDialog` + line="1392">an about dialog @@ -813,22 +1186,21 @@ in the credits page. - Returns the label used for the website link. - + line="1430">Returns the label used for the website link. + The label used for the website link + line="1436">The label used for the website link a `GtkAboutDialog` + line="1432">an about dialog @@ -836,23 +1208,22 @@ in the credits page. - Returns whether the license text in the about dialog is + line="1349">Returns whether the license text in the about dialog is automatically wrapped. - + `TRUE` if the license text is wrapped + line="1356">`TRUE` if the license text is wrapped a `GtkAboutDialog` + line="1351">an about dialog @@ -860,12 +1231,11 @@ automatically wrapped. - Sets the names of the artists to be displayed + line="1575">Sets the names of the artists to be displayed in the "Credits" page. - + @@ -873,13 +1243,13 @@ in the "Credits" page. a `GtkAboutDialog` + line="1577">an about dialog the authors of the artwork + line="1578">the authors of the artwork of the application @@ -890,12 +1260,11 @@ in the "Credits" page. - Sets the names of the authors which are displayed + line="1488">Sets the names of the authors which are displayed in the "Credits" page of the about dialog. - + @@ -903,13 +1272,13 @@ in the "Credits" page of the about dialog. a `GtkAboutDialog` + line="1490">an about dialog the authors of the application + line="1491">the authors of the application @@ -919,13 +1288,12 @@ in the "Credits" page of the about dialog. - Sets the comments string to display in the about dialog. + line="1218">Sets the comments string to display in the about dialog. This should be a short string of one or two lines. - + @@ -933,7 +1301,7 @@ This should be a short string of one or two lines. a `GtkAboutDialog` + line="1220">an about dialog allow-none="1"> a comments string + line="1221">a comments string @@ -950,13 +1318,12 @@ This should be a short string of one or two lines. - Sets the copyright string to display in the about dialog. + line="1169">Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. - + @@ -964,7 +1331,7 @@ This should be a short string of one or two lines. a `GtkAboutDialog` + line="1171">an about dialog allow-none="1"> the copyright string + line="1172">the copyright string @@ -981,12 +1348,11 @@ This should be a short string of one or two lines. - Sets the names of the documenters which are displayed + line="1531">Sets the names of the documenters which are displayed in the "Credits" page. - + @@ -994,13 +1360,13 @@ in the "Credits" page. a `GtkAboutDialog` + line="1533">an about dialog the authors of the documentation + line="1534">the authors of the documentation of the application @@ -1011,14 +1377,13 @@ in the "Credits" page. - Sets the license information to be displayed in the + line="1268">Sets the license information to be displayed in the about dialog. If `license` is `NULL`, the license page is hidden. - + @@ -1026,7 +1391,7 @@ If `license` is `NULL`, the license page is hidden. a `GtkAboutDialog` + line="1270">an about dialog allow-none="1"> the license information + line="1271">the license information @@ -1043,15 +1408,14 @@ If `license` is `NULL`, the license page is hidden. - Sets the license of the application showing the about dialog from a -list of known licenses. + line="2305">Sets the license of the application showing the about dialog +from a list of known licenses. This function overrides the license set using [method@Gtk.AboutDialog.set_license]. - + @@ -1059,13 +1423,13 @@ This function overrides the license set using a `GtkAboutDialog` + line="2307">an about dialog the type of license + line="2308">the type of license @@ -1073,11 +1437,10 @@ This function overrides the license set using - Sets the logo in the about dialog. - + line="1680">Sets the logo in the about dialog. + @@ -1085,7 +1448,7 @@ This function overrides the license set using a `GtkAboutDialog` + line="1682">an about dialog a `GdkPaintable` + line="1683">a `GdkPaintable` @@ -1102,11 +1465,10 @@ This function overrides the license set using - Sets the icon name to be displayed as logo in the about dialog. - + line="1726">Sets the icon name to be displayed as logo in the about dialog. + @@ -1114,7 +1476,7 @@ This function overrides the license set using a `GtkAboutDialog` + line="1728">an about dialog an icon name + line="1729">an icon name @@ -1131,14 +1493,13 @@ This function overrides the license set using - Sets the name to display in the about dialog. + line="1085">Sets the name to display in the about dialog. If `name` is not set, the string returned by `g_get_application_name()` is used. - + @@ -1146,7 +1507,7 @@ by `g_get_application_name()` is used. a `GtkAboutDialog` + line="1087">an about dialog allow-none="1"> the program name + line="1088">the program name @@ -1163,18 +1524,16 @@ by `g_get_application_name()` is used. - Sets the system information to be displayed in the about + line="1323">Sets the system information to be displayed in the about dialog. If `system_information` is `NULL`, the system information page is hidden. See [property@Gtk.AboutDialog:system-information]. - + @@ -1182,7 +1541,7 @@ See [property@Gtk.AboutDialog:system-information]. a `GtkAboutDialog` + line="1325">an about dialog allow-none="1"> system information + line="1326">system information @@ -1199,11 +1558,9 @@ See [property@Gtk.AboutDialog:system-information]. - Sets the translator credits string which is displayed in + line="1618">Sets the translator credits string which is displayed in the credits page. The intended use for this string is to display the translator @@ -1221,7 +1578,7 @@ It is a good idea to use the customary `msgid` “translator-credits” for this purpose, since translators will already know the purpose of that `msgid`, and since `GtkAboutDialog` will detect if “translator-credits” is untranslated and omit translator credits. - + @@ -1229,7 +1586,7 @@ is untranslated and omit translator credits. a `GtkAboutDialog` + line="1620">an about dialog allow-none="1"> the translator credits + line="1621">the translator credits @@ -1246,11 +1603,10 @@ is untranslated and omit translator credits. - Sets the version string to display in the about dialog. - + line="1129">Sets the version string to display in the about dialog. + @@ -1258,7 +1614,7 @@ is untranslated and omit translator credits. a `GtkAboutDialog` + line="1131">an about dialog allow-none="1"> the version string + line="1132">the version string @@ -1275,11 +1631,10 @@ is untranslated and omit translator credits. - Sets the URL to use for the website link. - + line="1406">Sets the URL to use for the website link. + @@ -1287,7 +1642,7 @@ is untranslated and omit translator credits. a `GtkAboutDialog` + line="1408">an about dialog allow-none="1"> a URL string starting with `http://` + line="1409">a URL string starting with `http://` @@ -1304,11 +1659,10 @@ is untranslated and omit translator credits. - Sets the label to be used for the website link. - + line="1446">Sets the label to be used for the website link. + @@ -1316,13 +1670,13 @@ is untranslated and omit translator credits. a `GtkAboutDialog` + line="1448">an about dialog the label used for the website link + line="1449">the label used for the website link @@ -1330,12 +1684,11 @@ is untranslated and omit translator credits. - Sets whether the license text in the about dialog should be + line="1366">Sets whether the license text in the about dialog should be automatically wrapped. - + @@ -1343,13 +1696,13 @@ automatically wrapped. a `GtkAboutDialog` + line="1368">an about dialog whether to wrap the license + line="1369">whether to wrap the license @@ -1359,14 +1712,9 @@ automatically wrapped. transfer-ownership="none" setter="set_artists" getter="get_artists"> - - The people who contributed artwork to the program, as a `NULL`-terminated -array of strings. + line="547">The people who contributed artwork to the program. Each string may contain email addresses and URLs, which will be displayed as links. @@ -1379,13 +1727,9 @@ as links. transfer-ownership="none" setter="set_authors" getter="get_authors"> - - The authors of the program, as a `NULL`-terminated array of strings. + line="521">The authors of the program. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. @@ -1399,13 +1743,9 @@ as links, see the introduction for more details. setter="set_comments" getter="get_comments" default-value="NULL"> - - Comments about the program. + line="419">Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, @@ -1418,13 +1758,9 @@ not a detailed list of features. setter="set_copyright" getter="get_copyright" default-value="NULL"> - - Copyright information for the program. + line="409">Copyright information for the program. transfer-ownership="none" setter="set_documenters" getter="get_documenters"> - - The people documenting the program, as a `NULL`-terminated array of strings. + line="534">The people documenting the program. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. @@ -1452,13 +1784,9 @@ as links, see the introduction for more details. setter="set_license" getter="get_license" default-value="NULL"> - - The license of the program, as free-form text. + line="433">The license of the program, as free-form text. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only @@ -1467,7 +1795,7 @@ otherwise the text itself must contain the intended linebreaks. When setting this property to a non-`NULL` value, the [property@Gtk.AboutDialog:license-type] property is set to -`GTK_LICENSE_CUSTOM` as a side effect. +[enum@Gtk.License.custom] as a side effect. The text may contain links in this format `<http://www.some.place/>` and email references in the form `<mail-to@some.body>`, and these will @@ -1480,27 +1808,23 @@ be converted into clickable links. setter="set_license_type" getter="get_license_type" default-value="GTK_LICENSE_UNKNOWN"> - - The license of the program. + line="474">The license of the program. The `GtkAboutDialog` will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. -If `GTK_LICENSE_UNKNOWN` is used, the link used will be the same +If [enum@Gtk.License.unknown] is used, the link used will be the same specified in the [property@Gtk.AboutDialog:website] property. -If `GTK_LICENSE_CUSTOM` is used, the current contents of the +If [enum@Gtk.License.custom] is used, the current contents of the [property@Gtk.AboutDialog:license] property are used. For any other [enum@Gtk.License] value, the contents of the -[property@Gtk.AboutDialog:license] property are also set by this property as -a side effect. +[property@Gtk.AboutDialog:license] property are also set by +this property as a side effect. transfer-ownership="none" setter="set_logo" getter="get_logo"> - - A logo for the about box. + line="575">A logo for the about box. If it is `NULL`, the default window icon set with -[id@gtk_window_set_default_icon_name] will be used. +[func@Gtk.Window.set_default_icon_name] will be used. - - A named icon to use as the logo for the about box. + line="588">A named icon to use as the logo for the about box. This property overrides the [property@Gtk.AboutDialog:logo] property. @@ -1543,16 +1859,12 @@ This property overrides the [property@Gtk.AboutDialog:logo] property. setter="set_program_name" getter="get_program_name" default-value="NULL"> - - The name of the program. + line="386">The name of the program. If this is not set, it defaults to the value returned by -`g_get_application_name()`. +[func@GLib.get_application_name]. - - Information about the system on which the program is running. + line="456">Information about the system on which the program is running. This information is displayed in a separate page, therefore it is fine to use a long multi-paragraph text. Note that the text should contain @@ -1584,13 +1892,9 @@ be converted into clickable links. setter="set_translator_credits" getter="get_translator_credits" default-value="NULL"> - - Credits to the translators. + line="560">Credits to the translators. This string should be marked as translatable. @@ -1604,13 +1908,9 @@ as links, see the introduction for more details. setter="set_version" getter="get_version" default-value="NULL"> - - The version of the program. + line="399">The version of the program. setter="set_website" getter="get_website" default-value="NULL"> - - The URL for the link to the website of the program. + line="499">The URL for the link to the website of the program. This should be a string starting with `http://` or `https://`. @@ -1636,13 +1932,9 @@ This should be a string starting with `http://` or `https://`. setter="set_website_label" getter="get_website_label" default-value="NULL"> - - The label for the link to the website of the program. + line="511">The label for the link to the website of the program. setter="set_wrap_license" getter="get_wrap_license" default-value="FALSE"> - - Whether to wrap the text in the license dialog. + line="600">Whether to wrap the text in the license dialog. Emitted every time a URL is activated. + line="362">Emitted every time a URL is activated. Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. `TRUE` if the link has been activated + line="372">`TRUE` if the link has been activated the URI that is activated + line="365">the URI that is activated @@ -1691,13 +1979,12 @@ which is to call [method@Gtk.FileLauncher.launch]. glib:type-struct="AccessibleInterface"> `GtkAccessible` is an interface for describing UI elements for -Assistive Technologies. + line="21">An interface for describing UI elements for Assistive Technologies. Every accessible implementation has: - a “role”, represented by a value of the [enum@Gtk.AccessibleRole] enumeration - - an “attribute”, represented by a set of [enum@Gtk.AccessibleState], + - “attributes”, represented by a set of [enum@Gtk.AccessibleState], [enum@Gtk.AccessibleProperty] and [enum@Gtk.AccessibleRelation] values The role cannot be changed after instantiating a `GtkAccessible` @@ -1713,8 +2000,10 @@ Normally, this tree corresponds to the widget tree, but can be customized by reimplementing the [vfunc@Gtk.Accessible.get_accessible_parent], [vfunc@Gtk.Accessible.get_first_accessible_child] and [vfunc@Gtk.Accessible.get_next_accessible_sibling] virtual functions. + Note that you can not create a top-level accessible object as of now, which means that you must always have a parent accessible object. + Also note that when an accessible object does not correspond to a widget, and it has children, whose implementation you don't control, it is necessary to ensure the correct shape of the a11y tree @@ -1726,21 +2015,21 @@ updating the sibling by [method@Gtk.Accessible.update_next_accessible_sibling].< version="4.10"> Retrieves the accessible parent for an accessible object. + line="109">Retrieves the accessible parent for an accessible object. This function returns `NULL` for top level widgets. the accessible parent + line="117">the accessible parent a `GtkAccessible` + line="111">an accessible object @@ -1750,19 +2039,19 @@ This function returns `NULL` for top level widgets. version="4.10"> Retrieves the accessible implementation for the given `GtkAccessible`. + line="91">Retrieves the implementation for the given accessible object. the accessible implementation object + line="97">the accessible implementation object a `GtkAccessible` + line="93">an accessible object @@ -1770,7 +2059,7 @@ This function returns `NULL` for top level widgets. Queries the coordinates and dimensions of this accessible + line="1239">Queries the coordinates and dimensions of this accessible This functionality can be overridden by `GtkAccessible` implementations, e.g. to get the bounds from an ignored @@ -1779,14 +2068,14 @@ child widget. true if the bounds are valid, and false otherwise + line="1253">true if the bounds are valid, and false otherwise a `GtkAccessible` + line="1241">an accessible object transfer-ownership="full"> the x coordinate of the top left corner of the accessible + line="1242">the x coordinate of the top left corner of the accessible transfer-ownership="full"> the y coordinate of the top left corner of the widget + line="1243">the y coordinate of the top left corner of the widget transfer-ownership="full"> the width of the accessible object + line="1244">the width of the accessible object transfer-ownership="full"> the height of the accessible object + line="1245">the height of the accessible object @@ -1832,19 +2121,19 @@ child widget. version="4.10"> Retrieves the first accessible child of an accessible object. + line="219">Retrieves the first accessible child of an accessible object. the first accessible child + line="225">the first accessible child an accessible object + line="221">an accessible object @@ -1854,19 +2143,19 @@ child widget. version="4.10"> Retrieves the next accessible sibling of an accessible object + line="237">Retrieves the next accessible sibling of an accessible object the next accessible sibling + line="243">the next accessible sibling an accessible object + line="239">an accessible object @@ -1876,9 +2165,7 @@ child widget. version="4.10"> Query a platform state, such as focus. - -See gtk_accessible_platform_changed(). + line="1144">Queries a platform state, such as focus. This functionality can be overridden by `GtkAccessible` implementations, e.g. to get platform state from an ignored @@ -1887,45 +2174,85 @@ child widget, as is the case for `GtkText` wrappers. the value of @state for the accessible + line="1155">the value of state for the accessible a `GtkAccessible` + line="1146">an accessible object platform state to query + line="1147">platform state to query + + Requests the user's screen reader to announce the given message. + +This kind of notification is useful for messages that +either have only a visual representation or that are not +exposed visually at all, e.g. a notification about a +successful operation. + +Also, by using this API, you can ensure that the message +does not interrupts the user's current screen reader output. + + + + + + + an accessible object + + + + the string to announce + + + + the priority of the announcement + + + + Retrieves the accessible parent for an accessible object. + line="109">Retrieves the accessible parent for an accessible object. This function returns `NULL` for top level widgets. - + the accessible parent + line="117">the accessible parent a `GtkAccessible` + line="111">an accessible object @@ -1935,19 +2262,19 @@ This function returns `NULL` for top level widgets. glib:get-property="accessible-role"> Retrieves the accessible role of an accessible object. - + line="270">Retrieves the accessible role of an accessible object. + the accessible role + line="276">the accessible role an accessible object + line="272">an accessible object @@ -1957,19 +2284,19 @@ This function returns `NULL` for top level widgets. version="4.10"> Retrieves the accessible implementation for the given `GtkAccessible`. - + line="91">Retrieves the implementation for the given accessible object. + the accessible implementation object + line="97">the accessible implementation object a `GtkAccessible` + line="93">an accessible object @@ -1979,23 +2306,23 @@ This function returns `NULL` for top level widgets. version="4.10"> Queries the coordinates and dimensions of this accessible + line="1239">Queries the coordinates and dimensions of this accessible This functionality can be overridden by `GtkAccessible` implementations, e.g. to get the bounds from an ignored child widget. - + true if the bounds are valid, and false otherwise + line="1253">true if the bounds are valid, and false otherwise a `GtkAccessible` + line="1241">an accessible object transfer-ownership="full"> the x coordinate of the top left corner of the accessible + line="1242">the x coordinate of the top left corner of the accessible transfer-ownership="full"> the y coordinate of the top left corner of the widget + line="1243">the y coordinate of the top left corner of the widget transfer-ownership="full"> the width of the accessible object + line="1244">the width of the accessible object transfer-ownership="full"> the height of the accessible object + line="1245">the height of the accessible object @@ -2041,19 +2368,19 @@ child widget. version="4.10"> Retrieves the first accessible child of an accessible object. - + line="219">Retrieves the first accessible child of an accessible object. + the first accessible child + line="225">the first accessible child an accessible object + line="221">an accessible object @@ -2063,19 +2390,19 @@ child widget. version="4.10"> Retrieves the next accessible sibling of an accessible object - + line="237">Retrieves the next accessible sibling of an accessible object + the next accessible sibling + line="243">the next accessible sibling an accessible object + line="239">an accessible object @@ -2085,31 +2412,29 @@ child widget. version="4.10"> Query a platform state, such as focus. - -See gtk_accessible_platform_changed(). + line="1144">Queries a platform state, such as focus. This functionality can be overridden by `GtkAccessible` implementations, e.g. to get platform state from an ignored child widget, as is the case for `GtkText` wrappers. - + the value of @state for the accessible + line="1155">the value of state for the accessible a `GtkAccessible` + line="1146">an accessible object platform state to query + line="1147">platform state to query @@ -2119,8 +2444,8 @@ child widget, as is the case for `GtkText` wrappers. c:identifier="gtk_accessible_reset_property"> Resets the accessible @property to its default value. - + line="581">Resets the accessible property to its default value. + @@ -2128,13 +2453,13 @@ child widget, as is the case for `GtkText` wrappers. a `GtkAccessible` + line="583">an accessible object a `GtkAccessibleProperty` + line="584">the accessible property @@ -2143,8 +2468,8 @@ child widget, as is the case for `GtkText` wrappers. c:identifier="gtk_accessible_reset_relation"> Resets the accessible @relation to its default value. - + line="767">Resets the accessible relation to its default value. + @@ -2152,13 +2477,13 @@ child widget, as is the case for `GtkText` wrappers. a `GtkAccessible` + line="769">an accessible object a `GtkAccessibleRelation` + line="770">the accessible relation @@ -2166,8 +2491,8 @@ child widget, as is the case for `GtkText` wrappers. Resets the accessible @state to its default value. - + line="430">Resets the accessible state to its default value. + @@ -2175,13 +2500,13 @@ child widget, as is the case for `GtkText` wrappers. a `GtkAccessible` + line="432">an accessible object a `GtkAccessibleState` + line="433">the accessible state @@ -2191,7 +2516,7 @@ child widget, as is the case for `GtkText` wrappers. version="4.10"> Sets the parent and sibling of an accessible object. + line="142">Sets the parent and sibling of an accessible object. This function is meant to be used by accessible implementations that are not part of the widget hierarchy, and but act as a logical bridge between @@ -2200,7 +2525,7 @@ for each child, and you want that object to implement the `GtkAccessible` interface, you will use this function to ensure that the parent of each child widget is the metadata object, and the parent of each metadata object is the container widget. - + @@ -2208,7 +2533,7 @@ object is the container widget. an accessible object + line="144">an accessible object allow-none="1"> the parent accessible object + line="145">the parent accessible object allow-none="1"> the sibling accessible object + line="146">the sibling accessible object @@ -2236,11 +2561,11 @@ object is the container widget. version="4.10"> Updates the next accessible sibling of @self. + line="180">Updates the next accessible sibling. -That might be useful when a new child of a custom `GtkAccessible` +That might be useful when a new child of a custom accessible is created, and it needs to be linked to a previous child. - + @@ -2248,7 +2573,7 @@ is created, and it needs to be linked to a previous child. a `GtkAccessible` + line="182">an accessible object allow-none="1"> the new next accessible sibling to set + line="183">the new next accessible sibling to set + + Informs ATs that the platform state has changed. + +This function should be used by `GtkAccessible` implementations that +have a platform state but are not widgets. Widgets handle platform +states automatically. + + + + + + + an accessible object + + + + the platform state to update + + + + Updates a list of accessible properties. + line="454">Updates a list of accessible properties. See the [enum@Gtk.AccessibleProperty] documentation for the value types of accessible properties. @@ -2284,7 +2639,7 @@ gtk_accessible_update_property (GTK_ACCESSIBLE (spin_button), GTK_ACCESSIBLE_PROPERTY_VALUE_NOW, value, -1); ``` - + @@ -2292,19 +2647,19 @@ gtk_accessible_update_property (GTK_ACCESSIBLE (spin_button), a `GtkAccessible` + line="456">an accessible object the first `GtkAccessibleProperty` + line="457">the first accessible property a list of property and value pairs, terminated by -1 + line="458">a list of property and value pairs, terminated by -1 @@ -2314,13 +2669,13 @@ gtk_accessible_update_property (GTK_ACCESSIBLE (spin_button), shadows="update_property"> Updates an array of accessible properties. + line="527">Updates an array of accessible properties. This function should be called by `GtkWidget` types whenever an accessible property change must be communicated to assistive technologies. This function is meant to be used by language bindings. - + @@ -2328,19 +2683,19 @@ This function is meant to be used by language bindings. a `GtkAccessible` + line="529">an accessible object the number of accessible properties to set + line="530">the number of accessible properties to set an array of `GtkAccessibleProperty` + line="531">an array of accessible properties @@ -2350,7 +2705,7 @@ This function is meant to be used by language bindings. an array of `GValues`, one for each property + line="532">an array of `GValues`, one for each property @@ -2363,13 +2718,13 @@ This function is meant to be used by language bindings. introspectable="0"> Updates a list of accessible relations. + line="626">Updates a list of accessible relations. This function should be called by `GtkWidget` types whenever an accessible relation change must be communicated to assistive technologies. If the [enum@Gtk.AccessibleRelation] requires a list of references, -you should pass each reference individually, followed by %NULL, e.g. +you should pass each reference individually, followed by `NULL`, e.g. ```c gtk_accessible_update_relation (accessible, @@ -2379,7 +2734,7 @@ gtk_accessible_update_relation (accessible, ref1, ref2, ref3, NULL, -1); ``` - + @@ -2387,19 +2742,19 @@ gtk_accessible_update_relation (accessible, a `GtkAccessible` + line="628">an accessible object the first `GtkAccessibleRelation` + line="629">the first accessible relation a list of relation and value pairs, terminated by -1 + line="630">a list of relation and value pairs, terminated by -1 @@ -2409,13 +2764,13 @@ gtk_accessible_update_relation (accessible, shadows="update_relation"> Updates an array of accessible relations. + line="705">Updates an array of accessible relations. This function should be called by `GtkWidget` types whenever an accessible relation change must be communicated to assistive technologies. This function is meant to be used by language bindings. - + @@ -2423,19 +2778,19 @@ This function is meant to be used by language bindings. a `GtkAccessible` + line="707">an accessible object the number of accessible relations to set + line="708">the number of accessible relations to set an array of `GtkAccessibleRelation` + line="709">an array of accessible relations @@ -2445,7 +2800,7 @@ This function is meant to be used by language bindings. an array of `GValues`, one for each relation + line="710">an array of `GValues`, one for each relation @@ -2458,11 +2813,14 @@ This function is meant to be used by language bindings. introspectable="0"> Updates a list of accessible states. See the [enum@Gtk.AccessibleState] -documentation for the value types of accessible states. + line="302">Updates a list of accessible states. -This function should be called by `GtkWidget` types whenever an accessible -state change must be communicated to assistive technologies. +See the [enum@Gtk.AccessibleState] documentation for the +value types of accessible states. + +This function should be called by `GtkWidget` types whenever +an accessible state change must be communicated to assistive +technologies. Example: @@ -2472,7 +2830,7 @@ gtk_accessible_update_state (GTK_ACCESSIBLE (check_button), GTK_ACCESSIBLE_STATE_CHECKED, value, -1); ``` - + @@ -2480,19 +2838,19 @@ gtk_accessible_update_state (GTK_ACCESSIBLE (check_button), a `GtkAccessible` + line="304">an accessible object the first `GtkAccessibleState` + line="305">the first accessible state a list of state and value pairs, terminated by -1 + line="306">a list of state and value pairs, terminated by -1 @@ -2502,13 +2860,13 @@ gtk_accessible_update_state (GTK_ACCESSIBLE (check_button), shadows="update_state"> Updates an array of accessible states. + line="376">Updates an array of accessible states. This function should be called by `GtkWidget` types whenever an accessible state change must be communicated to assistive technologies. This function is meant to be used by language bindings. - + @@ -2516,19 +2874,19 @@ This function is meant to be used by language bindings. a `GtkAccessible` + line="378">an accessible objedct the number of accessible states to set + line="379">the number of accessible states to set an array of `GtkAccessibleState` + line="380">an array of accessible states @@ -2536,7 +2894,7 @@ This function is meant to be used by language bindings. an array of `GValues`, one for each state + line="381">an array of `GValues`, one for each state @@ -2548,23 +2906,65 @@ This function is meant to be used by language bindings. transfer-ownership="none" getter="get_accessible_role" default-value="GTK_ACCESSIBLE_ROLE_NONE"> - The accessible role of the given `GtkAccessible` implementation. + line="74">The accessible role of the given `GtkAccessible` implementation. The accessible role cannot be changed once set. + + The priority of an accessibility announcement. + + The announcement is low priority, + and might be read only on the user's request. + + + The announcement is of medium + priority, and is usually spoken at the next opportunity, such as at the + end of speaking the current sentence or when the user pauses typing. + + + The announcement is of high + priority, and is usually spoken immediately. Because an interruption + might disorient users or cause them to not complete their current task, + authors SHOULD NOT use high priority announcements unless the + interruption is imperative. An example would be a notification about a + critical battery power level. + + The possible values for the %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE + line="1852">The possible values for the %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE accessible property. glib:name="GTK_ACCESSIBLE_AUTOCOMPLETE_NONE"> Automatic suggestions are not displayed. + line="1854">Automatic suggestions are not displayed. glib:name="GTK_ACCESSIBLE_AUTOCOMPLETE_INLINE"> When a user is providing input, text + line="1855">When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret. @@ -2593,7 +2993,7 @@ accessible property. glib:name="GTK_ACCESSIBLE_AUTOCOMPLETE_LIST"> When a user is providing input, an element + line="1858">When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. @@ -2604,7 +3004,7 @@ accessible property. glib:name="GTK_ACCESSIBLE_AUTOCOMPLETE_BOTH"> When a user is providing input, an element + line="1861">When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value @@ -2623,44 +3023,51 @@ accessible property. + retrieve the platform-specific accessibility context + for the accessible implementation the accessible implementation object + line="97">the accessible implementation object a `GtkAccessible` + line="93">an accessible object + retrieve the accessible state the value of @state for the accessible + line="1155">the value of state for the accessible a `GtkAccessible` + line="1146">an accessible object platform state to query + line="1147">platform state to query @@ -2673,14 +3080,14 @@ accessible property. the accessible parent + line="117">the accessible parent a `GtkAccessible` + line="111">an accessible object @@ -2692,14 +3099,14 @@ accessible property. the first accessible child + line="225">the first accessible child an accessible object + line="221">an accessible object @@ -2711,14 +3118,14 @@ accessible property. the next accessible sibling + line="243">the next accessible sibling an accessible object + line="239">an accessible object @@ -2730,14 +3137,14 @@ accessible property. true if the bounds are valid, and false otherwise + line="1253">true if the bounds are valid, and false otherwise a `GtkAccessible` + line="1241">an accessible object transfer-ownership="full"> the x coordinate of the top left corner of the accessible + line="1242">the x coordinate of the top left corner of the accessible transfer-ownership="full"> the y coordinate of the top left corner of the widget + line="1243">the y coordinate of the top left corner of the widget transfer-ownership="full"> the width of the accessible object + line="1244">the width of the accessible object transfer-ownership="full"> the height of the accessible object + line="1245">the height of the accessible object @@ -2786,7 +3193,7 @@ accessible property. c:type="GtkAccessibleInvalidState"> The possible values for the %GTK_ACCESSIBLE_STATE_INVALID + line="1831">The possible values for the %GTK_ACCESSIBLE_STATE_INVALID accessible state. Note that the %GTK_ACCESSIBLE_INVALID_FALSE and @@ -2799,7 +3206,7 @@ as %FALSE and %TRUE. glib:name="GTK_ACCESSIBLE_INVALID_FALSE"> There are no detected errors in the value + line="1833">There are no detected errors in the value glib:name="GTK_ACCESSIBLE_INVALID_TRUE"> The value entered by the user has failed validation + line="1834">The value entered by the user has failed validation glib:name="GTK_ACCESSIBLE_INVALID_GRAMMAR"> A grammatical error was detected + line="1835">A grammatical error was detected glib:name="GTK_ACCESSIBLE_INVALID_SPELLING"> A spelling error was detected + line="1836">A spelling error was detected + + Wraps a list of references to [iface@Gtk.Accessible] objects. + + + Allocates a new list of accessible objects. + + + the newly created list of accessible objects + + + + + array of accessible objects + + + + + + length of the @accessibles array + + + + + + Allocates a new `GtkAccessibleList`, doing a shallow copy +of the passed list of accessible objects + + + the list of accessible objects + + + + + a list + of accessible objects + + + + + + + + Gets the list of objects this boxed type holds. + + + a shallow copy + of the objects + + + + + + + + + + + c:type="GtkAccessibleProperty"> The possible accessible properties of a [iface@Accessible]. + line="1585">The possible accessible properties of a [iface@Accessible]. glib:name="GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE"> Indicates whether inputting text + line="1587">Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. Value type: [enum@AccessibleAutocomplete] @@ -2892,7 +3389,7 @@ using [method@Gtk.Accessible.get_platform_state]. glib:name="GTK_ACCESSIBLE_PROPERTY_DESCRIPTION"> Defines a string value that describes + line="1591">Defines a string value that describes or annotates the current element. Value type: string glib:name="GTK_ACCESSIBLE_PROPERTY_HAS_POPUP"> Indicates the availability and type of + line="1593">Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. @@ -2913,9 +3410,12 @@ using [method@Gtk.Accessible.get_platform_state]. glib:name="GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS"> Indicates keyboard shortcuts that an + line="1596">Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. Value type: - string + string. The format of the value is a space-separated list of shortcuts, with + each shortcut consisting of one or more modifiers (`Control`, `Alt` or `Shift`), + followed by a non-modifier key, all separated by `+`. + Examples: `F2`, `Alt-F`, `Control+Shift+N` glib:name="GTK_ACCESSIBLE_PROPERTY_LABEL"> Defines a string value that labels the current + line="1602">Defines a string value that labels the current element. Value type: string glib:name="GTK_ACCESSIBLE_PROPERTY_LEVEL"> Defines the hierarchical level of an element + line="1604">Defines the hierarchical level of an element within a structure. Value type: integer glib:name="GTK_ACCESSIBLE_PROPERTY_MODAL"> Indicates whether an element is modal when + line="1606">Indicates whether an element is modal when displayed. Value type: boolean glib:name="GTK_ACCESSIBLE_PROPERTY_MULTI_LINE"> Indicates whether a text box accepts + line="1608">Indicates whether a text box accepts multiple lines of input or only a single line. Value type: boolean glib:name="GTK_ACCESSIBLE_PROPERTY_MULTI_SELECTABLE"> Indicates that the user may select + line="1610">Indicates that the user may select more than one item from the current selectable descendants. Value type: boolean @@ -2975,7 +3475,7 @@ using [method@Gtk.Accessible.get_platform_state]. glib:name="GTK_ACCESSIBLE_PROPERTY_ORIENTATION"> Indicates whether the element's + line="1613">Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. Value type: [enum@Orientation] @@ -2986,7 +3486,7 @@ using [method@Gtk.Accessible.get_platform_state]. glib:name="GTK_ACCESSIBLE_PROPERTY_PLACEHOLDER"> Defines a short hint (a word or short + line="1616">Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. Value type: string @@ -2998,7 +3498,7 @@ using [method@Gtk.Accessible.get_platform_state]. glib:name="GTK_ACCESSIBLE_PROPERTY_READ_ONLY"> Indicates that the element is not editable, + line="1620">Indicates that the element is not editable, but is otherwise operable. Value type: boolean glib:name="GTK_ACCESSIBLE_PROPERTY_REQUIRED"> Indicates that user input is required on + line="1622">Indicates that user input is required on the element before a form may be submitted. Value type: boolean glib:name="GTK_ACCESSIBLE_PROPERTY_ROLE_DESCRIPTION"> Defines a human-readable, + line="1624">Defines a human-readable, author-localized description for the role of an element. Value type: string glib:name="GTK_ACCESSIBLE_PROPERTY_SORT"> Indicates if items in a table or grid are + line="1626">Indicates if items in a table or grid are sorted in ascending or descending order. Value type: [enum@AccessibleSort] glib:name="GTK_ACCESSIBLE_PROPERTY_VALUE_MAX"> Defines the maximum allowed value for a + line="1628">Defines the maximum allowed value for a range widget. Value type: double glib:name="GTK_ACCESSIBLE_PROPERTY_VALUE_MIN"> Defines the minimum allowed value for a + line="1630">Defines the minimum allowed value for a range widget. Value type: double glib:name="GTK_ACCESSIBLE_PROPERTY_VALUE_NOW"> Defines the current value for a range widget. + line="1632">Defines the current value for a range widget. Value type: double glib:name="GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT"> Defines the human readable text alternative + line="1634">Defines the human readable text alternative of aria-valuenow for a range widget. Value type: string + + + Defines a string value that provides a description of non-standard keyboard +interactions of the current element. Value type: string - + Initializes @value with the appropriate type for the @property. + +This function is mostly meant for language bindings, in conjunction +with gtk_accessible_update_property_value(). + + a `GtkAccessibleProperty` + an uninitialized `GValue` @@ -3096,11 +3619,15 @@ using [method@Gtk.Accessible.get_platform_state]. glib:type-struct="AccessibleRangeInterface"> This interface describes ranged controls, e.g. controls which have a single -value within an allowed range and that can optionally be changed by the user. + line="7">An interface for accessible objects containing a numeric value. + +`GtkAccessibleRange` describes ranged controls for Assistive Technologies. + +Ranged controls have a single value within an allowed range that can +optionally be changed by the user. -This interface is expected to be implemented by controls using the following -roles: +This interface is expected to be implemented by controls using the +following roles: - `GTK_ACCESSIBLE_ROLE_METER` - `GTK_ACCESSIBLE_ROLE_PROGRESS_BAR` @@ -3110,7 +3637,7 @@ roles: If that is not the case, a warning will be issued at run time. -In addition to this interface, its implementors are expected to provide the +In addition to this interface, its implementers are expected to provide the correct values for the following properties: - `GTK_ACCESSIBLE_PROPERTY_VALUE_MAX` @@ -3188,7 +3715,7 @@ action. c:type="GtkAccessibleRelation"> The possible accessible relations of a [iface@Accessible]. + line="1671">The possible accessible relations of a [iface@Accessible]. Accessible relations can be references to other widgets, integers or strings. @@ -3199,7 +3726,7 @@ integers or strings. glib:name="GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT"> Identifies the currently active + line="1673">Identifies the currently active element when focus is on a composite widget, combobox, textbox, group, or application. Value type: reference @@ -3210,7 +3737,7 @@ integers or strings. glib:name="GTK_ACCESSIBLE_RELATION_COL_COUNT"> Defines the total number of columns + line="1676">Defines the total number of columns in a table, grid, or treegrid. Value type: integer glib:name="GTK_ACCESSIBLE_RELATION_COL_INDEX"> Defines an element's column index or + line="1678">Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. Value type: integer @@ -3231,7 +3758,7 @@ integers or strings. glib:name="GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT"> Defines a human readable text + line="1681">Defines a human readable text alternative of %GTK_ACCESSIBLE_RELATION_COL_INDEX. Value type: string glib:name="GTK_ACCESSIBLE_RELATION_COL_SPAN"> Defines the number of columns spanned + line="1683">Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer glib:name="GTK_ACCESSIBLE_RELATION_CONTROLS"> Identifies the element (or elements) whose + line="1685">Identifies the element (or elements) whose contents or presence are controlled by the current element. Value type: reference glib:name="GTK_ACCESSIBLE_RELATION_DESCRIBED_BY"> Identifies the element (or elements) + line="1687">Identifies the element (or elements) that describes the object. Value type: reference glib:name="GTK_ACCESSIBLE_RELATION_DETAILS"> Identifies the element (or elements) that + line="1689">Identifies the element (or elements) that provide additional information related to the object. Value type: reference glib:name="GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE"> Identifies the element that provides - an error message for an object. Value type: reference + line="1691">Identifies the element (or elements) that + provide an error message for an object. Value type: reference glib:name="GTK_ACCESSIBLE_RELATION_FLOW_TO"> Identifies the next element (or elements) + line="1693">Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. Value type: reference @@ -3303,7 +3830,7 @@ integers or strings. glib:name="GTK_ACCESSIBLE_RELATION_LABELLED_BY"> Identifies the element (or elements) + line="1697">Identifies the element (or elements) that labels the current element. Value type: reference glib:name="GTK_ACCESSIBLE_RELATION_OWNS"> Identifies an element (or elements) in order + line="1699">Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between elements where the widget hierarchy cannot be used to represent the relationship. Value type: reference @@ -3325,7 +3852,7 @@ integers or strings. glib:name="GTK_ACCESSIBLE_RELATION_POS_IN_SET"> Defines an element's number or position + line="1703">Defines an element's number or position in the current set of listitems or treeitems. Value type: integer glib:name="GTK_ACCESSIBLE_RELATION_ROW_COUNT"> Defines the total number of rows in a table, + line="1705">Defines the total number of rows in a table, grid, or treegrid. Value type: integer glib:name="GTK_ACCESSIBLE_RELATION_ROW_INDEX"> Defines an element's row index or position + line="1707">Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. Value type: integer @@ -3356,7 +3883,7 @@ integers or strings. glib:name="GTK_ACCESSIBLE_RELATION_ROW_INDEX_TEXT"> Defines a human readable text + line="1710">Defines a human readable text alternative of aria-rowindex. Value type: string glib:name="GTK_ACCESSIBLE_RELATION_ROW_SPAN"> Defines the number of rows spanned by a + line="1712">Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer glib:name="GTK_ACCESSIBLE_RELATION_SET_SIZE"> Defines the number of items in the current + line="1714">Defines the number of items in the current set of listitems or treeitems. Value type: integer + + + Identifies the element (or elements) that are labeled by the +current element. Value type: reference + +This relation is managed by GTK and should not be set from application code. + + + Identifies the element (or elements) that are described by +the current element. Value type: reference + +This relation is managed by GTK and should not be set from application code. + + + Identifies the element (or elements) that the current +element is controlled by. Value type: reference + +This relation is managed by GTK and should not be set from application code. + + + Identifies the element (or elements) for which the current +element provides additional information. Value type: reference + +This relation is managed by GTK and should not be set from application code. + + + Identifies the element (or elements) for which the current +element provides an error message. Value type: reference + +This relation is managed by GTK and should not be set from application code. + + + Identifies the previous element (or elements) in an alternate +reading order of content which, at the user's discretion, allows +assistive technology to override the general default of reading in +document source order. Value type: reference + +This relation is managed by GTK and should not be set from application code. - + Initializes @value with the appropriate type for the @relation. + +This function is mostly meant for language bindings, in conjunction +with gtk_accessible_update_relation_value(). + + a `GtkAccessibleRelation` + an uninitialized `GValue` @@ -3401,7 +4020,7 @@ integers or strings. c:type="GtkAccessibleRole"> The accessible role for a [iface@Accessible] implementation. + line="1273">The accessible role for a [iface@Accessible] implementation. Abstract roles are only used as part of the ontology; application developers must not use abstract roles in their code. @@ -3412,7 +4031,7 @@ developers must not use abstract roles in their code. glib:name="GTK_ACCESSIBLE_ROLE_ALERT"> An element with important, and usually + line="1275">An element with important, and usually time-sensitive, information glib:name="GTK_ACCESSIBLE_ROLE_ALERT_DIALOG"> A type of dialog that contains an + line="1277">A type of dialog that contains an alert message glib:name="GTK_ACCESSIBLE_ROLE_BANNER"> Unused + line="1279">Unused glib:name="GTK_ACCESSIBLE_ROLE_BUTTON"> An input element that allows for + line="1280">An input element that allows for user-triggered actions when clicked or pressed glib:name="GTK_ACCESSIBLE_ROLE_CAPTION"> Unused + line="1282">Unused glib:name="GTK_ACCESSIBLE_ROLE_CELL"> Unused + line="1283">Unused glib:name="GTK_ACCESSIBLE_ROLE_CHECKBOX"> A checkable input element that has + line="1284">A checkable input element that has three possible values: `true`, `false`, or `mixed` glib:name="GTK_ACCESSIBLE_ROLE_COLUMN_HEADER"> A header in a columned list. + line="1286">A header in a columned list. glib:name="GTK_ACCESSIBLE_ROLE_COMBO_BOX"> An input that controls another element, + line="1287">An input that controls another element, such as a list or a grid, that can dynamically pop up to help the user set the value of the input @@ -3499,7 +4118,7 @@ developers must not use abstract roles in their code. glib:name="GTK_ACCESSIBLE_ROLE_COMMAND"> Abstract role. + line="1290">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_COMPOSITE"> Abstract role. + line="1291">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_DIALOG"> A dialog is a window that is designed to interrupt + line="1292">A dialog is a window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. @@ -3528,7 +4147,7 @@ developers must not use abstract roles in their code. glib:name="GTK_ACCESSIBLE_ROLE_DOCUMENT"> Content that assistive technology users may want to + line="1295">Content that assistive technology users may want to browse in a reading mode. glib:name="GTK_ACCESSIBLE_ROLE_FEED"> Unused + line="1297">Unused glib:name="GTK_ACCESSIBLE_ROLE_FORM"> Unused + line="1298">Unused glib:name="GTK_ACCESSIBLE_ROLE_GENERIC"> A nameless container that has no semantic meaning + line="1299">A nameless container that has no semantic meaning of its own. This is the role that GTK uses by default for widgets. glib:name="GTK_ACCESSIBLE_ROLE_GRID"> A grid of items. + line="1301">A grid of items. glib:name="GTK_ACCESSIBLE_ROLE_GRID_CELL"> An item in a grid or tree grid. + line="1302">An item in a grid or tree grid. glib:name="GTK_ACCESSIBLE_ROLE_GROUP"> An element that groups multiple related widgets. GTK uses + line="1303">An element that groups multiple related widgets. GTK uses this role for various containers, like [class@Gtk.HeaderBar] or [class@Gtk.Notebook]. glib:name="GTK_ACCESSIBLE_ROLE_HEADING"> Unused + line="1305">Unused glib:name="GTK_ACCESSIBLE_ROLE_IMG"> An image. + line="1306">An image. glib:name="GTK_ACCESSIBLE_ROLE_INPUT"> Abstract role. + line="1307">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_LABEL"> A visible name or caption for a user interface component. + line="1308">A visible name or caption for a user interface component. glib:name="GTK_ACCESSIBLE_ROLE_LANDMARK"> Abstract role. + line="1309">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_LEGEND"> Unused + line="1310">Unused glib:name="GTK_ACCESSIBLE_ROLE_LINK"> A clickable link. + line="1311">A clickable link. glib:name="GTK_ACCESSIBLE_ROLE_LIST"> A list of items. + line="1312">A list of items. glib:name="GTK_ACCESSIBLE_ROLE_LIST_BOX"> Unused. + line="1313">Unused. glib:name="GTK_ACCESSIBLE_ROLE_LIST_ITEM"> An item in a list. + line="1314">An item in a list. glib:name="GTK_ACCESSIBLE_ROLE_LOG"> Unused + line="1315">Unused glib:name="GTK_ACCESSIBLE_ROLE_MAIN"> Unused + line="1316">Unused glib:name="GTK_ACCESSIBLE_ROLE_MARQUEE"> Unused + line="1317">Unused glib:name="GTK_ACCESSIBLE_ROLE_MATH"> Unused + line="1318">Unused glib:name="GTK_ACCESSIBLE_ROLE_METER"> An element that represents a value within a known range. + line="1319">An element that represents a value within a known range. glib:name="GTK_ACCESSIBLE_ROLE_MENU"> A menu. + line="1320">A menu. glib:name="GTK_ACCESSIBLE_ROLE_MENU_BAR"> A menubar. + line="1321">A menubar. glib:name="GTK_ACCESSIBLE_ROLE_MENU_ITEM"> An item in a menu. + line="1322">An item in a menu. glib:name="GTK_ACCESSIBLE_ROLE_MENU_ITEM_CHECKBOX"> A check item in a menu. + line="1323">A check item in a menu. glib:name="GTK_ACCESSIBLE_ROLE_MENU_ITEM_RADIO"> A radio item in a menu. + line="1324">A radio item in a menu. glib:name="GTK_ACCESSIBLE_ROLE_NAVIGATION"> Unused + line="1325">Unused glib:name="GTK_ACCESSIBLE_ROLE_NONE"> An element that is not represented to accessibility technologies. + line="1326">An element that is not represented to accessibility technologies. This role is synonymous to @GTK_ACCESSIBLE_ROLE_PRESENTATION. glib:name="GTK_ACCESSIBLE_ROLE_NOTE"> Unused + line="1328">Unused glib:name="GTK_ACCESSIBLE_ROLE_OPTION"> Unused + line="1329">Unused glib:name="GTK_ACCESSIBLE_ROLE_PRESENTATION"> An element that is not represented to accessibility technologies. + line="1330">An element that is not represented to accessibility technologies. This role is synonymous to @GTK_ACCESSIBLE_ROLE_NONE. glib:name="GTK_ACCESSIBLE_ROLE_PROGRESS_BAR"> An element that displays the progress + line="1332">An element that displays the progress status for tasks that take a long time. glib:name="GTK_ACCESSIBLE_ROLE_RADIO"> A checkable input in a group of radio roles, + line="1334">A checkable input in a group of radio roles, only one of which can be checked at a time. glib:name="GTK_ACCESSIBLE_ROLE_RADIO_GROUP"> Unused + line="1336">Unused glib:name="GTK_ACCESSIBLE_ROLE_RANGE"> Abstract role. + line="1337">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_REGION"> Unused + line="1338">Unused glib:name="GTK_ACCESSIBLE_ROLE_ROW"> A row in a columned list. + line="1339">A row in a columned list. glib:name="GTK_ACCESSIBLE_ROLE_ROW_GROUP"> Unused + line="1340">Unused glib:name="GTK_ACCESSIBLE_ROLE_ROW_HEADER"> Unused + line="1341">Unused glib:name="GTK_ACCESSIBLE_ROLE_SCROLLBAR"> A graphical object that controls the scrolling + line="1342">A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area. @@ -3906,7 +4525,7 @@ developers must not use abstract roles in their code. glib:name="GTK_ACCESSIBLE_ROLE_SEARCH"> Unused + line="1345">Unused glib:name="GTK_ACCESSIBLE_ROLE_SEARCH_BOX"> A type of textbox intended for specifying + line="1346">A type of textbox intended for specifying search criteria. glib:name="GTK_ACCESSIBLE_ROLE_SECTION"> Abstract role. + line="1348">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_SECTION_HEAD"> Abstract role. + line="1349">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_SELECT"> Abstract role. + line="1350">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_SEPARATOR"> A divider that separates and distinguishes + line="1351">A divider that separates and distinguishes sections of content or groups of menuitems. glib:name="GTK_ACCESSIBLE_ROLE_SLIDER"> A user input where the user selects a value + line="1353">A user input where the user selects a value from within a given range. glib:name="GTK_ACCESSIBLE_ROLE_SPIN_BUTTON"> A form of range that expects the user to + line="1355">A form of range that expects the user to select from among discrete choices. glib:name="GTK_ACCESSIBLE_ROLE_STATUS"> Unused + line="1357">Unused glib:name="GTK_ACCESSIBLE_ROLE_STRUCTURE"> Abstract role. + line="1358">Abstract role. glib:name="GTK_ACCESSIBLE_ROLE_SWITCH"> A type of checkbox that represents on/off values, + line="1359">A type of checkbox that represents on/off values, as opposed to checked/unchecked values. glib:name="GTK_ACCESSIBLE_ROLE_TAB"> An item in a list of tab used for switching pages. + line="1361">An item in a list of tab used for switching pages. glib:name="GTK_ACCESSIBLE_ROLE_TABLE"> Unused + line="1362">Unused glib:name="GTK_ACCESSIBLE_ROLE_TAB_LIST"> A list of tabs for switching pages. + line="1363">A list of tabs for switching pages. glib:name="GTK_ACCESSIBLE_ROLE_TAB_PANEL"> A page in a notebook or stack. + line="1364">A page in a notebook or stack. glib:name="GTK_ACCESSIBLE_ROLE_TEXT_BOX"> A type of input that allows free-form text + line="1365">A type of input that allows free-form text as its value. glib:name="GTK_ACCESSIBLE_ROLE_TIME"> Unused + line="1367">Unused glib:name="GTK_ACCESSIBLE_ROLE_TIMER"> Unused + line="1368">Unused glib:name="GTK_ACCESSIBLE_ROLE_TOOLBAR"> Unused + line="1369">Unused glib:name="GTK_ACCESSIBLE_ROLE_TOOLTIP"> Unused + line="1370">Unused glib:name="GTK_ACCESSIBLE_ROLE_TREE"> Unused + line="1371">Unused glib:name="GTK_ACCESSIBLE_ROLE_TREE_GRID"> A treeview-like, columned list. + line="1372">A treeview-like, columned list. glib:name="GTK_ACCESSIBLE_ROLE_TREE_ITEM"> Unused + line="1373">Unused glib:name="GTK_ACCESSIBLE_ROLE_WIDGET"> Abstract role for interactive components of a + line="1374">Abstract role for interactive components of a graphical user interface glib:name="GTK_ACCESSIBLE_ROLE_WINDOW"> Abstract role for windows. + line="1376">Abstract role for windows. A type of push button - which stays pressed until depressed by a second activation. - Since: 4.10 + line="1384">A type of push button which stays pressed until depressed by a second +activation. A toplevel element of a graphical user interface. - This is the role that GTK uses by default for windows. - Since: 4.12 + line="1393">A toplevel element of a graphical user interface. + +This is the role that GTK uses by default for windows. + + + A paragraph of content. + + + A section of content that is quoted from another source. + + + A section of a page that consists of a composition that forms an independent +part of a document, page, or site. + + + A comment contains content expressing reaction to other content. + + + A virtual terminal. c:type="GtkAccessibleSort"> The possible values for the %GTK_ACCESSIBLE_PROPERTY_SORT + line="1877">The possible values for the %GTK_ACCESSIBLE_PROPERTY_SORT accessible property. glib:name="GTK_ACCESSIBLE_SORT_NONE"> There is no defined sort applied to the column. + line="1879">There is no defined sort applied to the column. glib:name="GTK_ACCESSIBLE_SORT_ASCENDING"> Items are sorted in ascending order by this column. + line="1880">Items are sorted in ascending order by this column. glib:name="GTK_ACCESSIBLE_SORT_DESCENDING"> Items are sorted in descending order by this column. + line="1881">Items are sorted in descending order by this column. glib:name="GTK_ACCESSIBLE_SORT_OTHER"> A sort algorithm other than ascending or + line="1882">A sort algorithm other than ascending or descending has been applied. @@ -4206,7 +4877,7 @@ accessible property. c:type="GtkAccessibleState"> The possible accessible states of a [iface@Accessible]. + line="1531">The possible accessible states of a [iface@Accessible]. glib:name="GTK_ACCESSIBLE_STATE_BUSY"> A “busy” state. This state has boolean values + line="1533">A “busy” state. This state has boolean values glib:name="GTK_ACCESSIBLE_STATE_CHECKED"> A “checked” state; indicates the current + line="1534">A “checked” state; indicates the current state of a [class@CheckButton]. Value type: [enum@AccessibleTristate] glib:name="GTK_ACCESSIBLE_STATE_DISABLED"> A “disabled” state; corresponds to the + line="1536">A “disabled” state; corresponds to the [property@Widget:sensitive] property. It indicates a UI element that is perceivable, but not editable or operable. Value type: boolean @@ -4244,7 +4915,7 @@ accessible property. glib:name="GTK_ACCESSIBLE_STATE_EXPANDED"> An “expanded” state; corresponds to the + line="1539">An “expanded” state; corresponds to the [property@Expander:expanded] property. Value type: boolean or undefined @@ -4255,7 +4926,7 @@ accessible property. glib:name="GTK_ACCESSIBLE_STATE_HIDDEN"> A “hidden” state; corresponds to the + line="1542">A “hidden” state; corresponds to the [property@Widget:visible] property. You can use this state explicitly on UI elements that should not be exposed to an assistive technology. Value type: boolean @@ -4268,7 +4939,7 @@ accessible property. glib:name="GTK_ACCESSIBLE_STATE_INVALID"> An “invalid” state; set when a widget + line="1547">An “invalid” state; set when a widget is showing an error. Value type: [enum@AccessibleInvalidState] glib:name="GTK_ACCESSIBLE_STATE_PRESSED"> A “pressed” state; indicates the current + line="1549">A “pressed” state; indicates the current state of a [class@ToggleButton]. Value type: [enum@AccessibleTristate] enumeration @@ -4289,43 +4960,1022 @@ accessible property. glib:name="GTK_ACCESSIBLE_STATE_SELECTED"> A “selected” state; set when a widget + line="1552">A “selected” state; set when a widget is selected. Value type: boolean or undefined Indicates that a widget with the - GTK_ACCESSIBLE_ROLE_LINK has been visited. Value type: boolean. - Since: 4.12 + line="1557">Indicates that a widget with the GTK_ACCESSIBLE_ROLE_LINK has been visited. +Value type: boolean. - + Initializes @value with the appropriate type for the @state. + +This function is mostly meant for language bindings, in conjunction +with gtk_accessible_update_relation_state(). + + a `GtkAccessibleState` + an uninitialized `GValue` + + An interface for accessible objects containing formatted text. + +The `GtkAccessibleText` interfaces is meant to be implemented by accessible +objects that have text formatted with attributes, or non-trivial text contents. + +You should use the [enum@Gtk.AccessibleProperty.LABEL] or the +[enum@Gtk.AccessibleProperty.DESCRIPTION] properties for accessible +objects containing simple, unformatted text. + + + + Retrieves the text attributes inside the accessible object. + +Each attribute is composed by: + +- a range +- a name +- a value + +It is left to the implementation to determine the serialization format +of the value to a string. + +GTK provides support for various text attribute names and values, but +implementations of this interface are free to add their own attributes. + +If this function returns true, `n_ranges` will be set to a value +greater than or equal to one, @ranges will be set to a newly +allocated array of [struct#Gtk.AccessibleTextRange]. + + + true if the accessible object has at least an attribute, + and false otherwise + + + + + the accessible object + + + + the offset, in characters + + + + the number of attributes + + + + the ranges of the attributes + inside the accessible object + + + + + + the + names of the attributes inside the accessible object + + + + + + the + values of the attributes inside the accessible object + + + + + + + + Retrieves the position of the caret inside the accessible object. + + + the position of the caret, in characters + + + + + the accessible object + + + + + + Retrieve the current contents of the accessible object within +the given range. + +If @end is `G_MAXUINT`, the end of the range is the full content +of the accessible object. + + + the requested slice of the contents of the + accessible object, as UTF-8. Note that the slice does not have to + be NUL-terminated + + + + + the accessible object + + + + the beginning of the range, in characters + + + + the end of the range, in characters + + + + + + Retrieve the current contents of the accessible object starting +from the given offset, and using the given granularity. + +The @start and @end values contain the boundaries of the text. + + + the requested slice of the contents of the + accessible object, as UTF-8. Note that the slice does not have to + be NUL-terminated + + + + + the accessible object + + + + the offset, in characters + + + + the granularity of the query + + + + the start of the range, in characters + + + + the end of the range, in characters + + + + + + Retrieves the default text attributes inside the accessible object. + +Each attribute is composed by: + +- a name +- a value + +It is left to the implementation to determine the serialization format +of the value to a string. + +GTK provides support for various text attribute names and values, but +implementations of this interface are free to add their own attributes. + + + + + + + the accessible object + + + + the + names of the default attributes inside the accessible object + + + + + + the + values of the default attributes inside the accessible object + + + + + + + + Obtains the extents of a range of text, in widget coordinates. + + + true if the extents were filled in, false otherwise + + + + + the accessible object + + + + the start offset, in characters + + + + the end offset, in characters, +@extents (out caller-allocates): return location for the extents + + + + + + + + + Gets the text offset at a given point. + + + true if the offset was set, false otherwise + + + + + the accessible object + + + + a point in widget coordinates of @self + + + + return location for the text offset at @point + + + + + + Retrieves the selection ranges in the accessible object. + +If this function returns true, `n_ranges` will be set to a value +greater than or equal to one, and @ranges will be set to a newly +allocated array of [struct#Gtk.AccessibleTextRange]. + + + true if there is at least a selection inside the + accessible object, and false otherwise + + + + + the accessible object + + + + the number of selection ranges + + + + the selection ranges + + + + + + + + Updates the position of the caret. + +Implementations of the `GtkAccessibleText` interface should call this +function every time the caret has moved, in order to notify assistive +technologies. + + + + + + + the accessible object + + + + + + Notifies assistive technologies of a change in contents. + +Implementations of the `GtkAccessibleText` interface should call this +function every time their contents change as the result of an operation, +like an insertion or a removal. + +Note: If the change is a deletion, this function must be called *before* +removing the contents, if it is an insertion, it must be called *after* +inserting the new contents. + + + + + + + the accessible object + + + + the type of change in the contents + + + + the starting offset of the change, in characters + + + + the end offset of the change, in characters + + + + + + Updates the boundary of the selection. + +Implementations of the `GtkAccessibleText` interface should call this +function every time the selection has moved, in order to notify assistive +technologies. + + + + + + + the accessible object + + + + + + + The type of contents change operation. + + contents change as the result of + an insert operation + + + contents change as the result of + a remove operation + + + + The granularity for queries about the text contents of a [iface@Gtk.AccessibleText] +implementation. + + Use the boundary between + characters (including non-printing characters) + + + Use the boundary between words, + starting from the beginning of the current word and ending at the + beginning of the next word + + + Use the boundary between + sentences, starting from the beginning of the current sentence and + ending at the beginning of the next sentence + + + Use the boundary between lines, + starting from the beginning of the current line and ending at the + beginning of the next line + + + Use the boundary between + paragraphs, starting from the beginning of the current paragraph and + ending at the beginning of the next paragraph + + + + The interface vtable for accessible objects containing text. + + + + + + + + + the requested slice of the contents of the + accessible object, as UTF-8. Note that the slice does not have to + be NUL-terminated + + + + + the accessible object + + + + the beginning of the range, in characters + + + + the end of the range, in characters + + + + + + + + + + the requested slice of the contents of the + accessible object, as UTF-8. Note that the slice does not have to + be NUL-terminated + + + + + the accessible object + + + + the offset, in characters + + + + the granularity of the query + + + + the start of the range, in characters + + + + the end of the range, in characters + + + + + + + + + + the position of the caret, in characters + + + + + the accessible object + + + + + + + + + + true if there is at least a selection inside the + accessible object, and false otherwise + + + + + the accessible object + + + + the number of selection ranges + + + + the selection ranges + + + + + + + + + + + + true if the accessible object has at least an attribute, + and false otherwise + + + + + the accessible object + + + + the offset, in characters + + + + the number of attributes + + + + the ranges of the attributes + inside the accessible object + + + + + + the + names of the attributes inside the accessible object + + + + + + the + values of the attributes inside the accessible object + + + + + + + + + + + + + + + + the accessible object + + + + the + names of the default attributes inside the accessible object + + + + + + the + values of the default attributes inside the accessible object + + + + + + + + + + + + true if the extents were filled in, false otherwise + + + + + the accessible object + + + + the start offset, in characters + + + + the end offset, in characters, +@extents (out caller-allocates): return location for the extents + + + + + + + + + + + + + true if the offset was set, false otherwise + + + + + the accessible object + + + + a point in widget coordinates of @self + + + + return location for the text offset at @point + + + + + + + + A range inside the text of an accessible object. + + + the start of the range, in characters + + + + the length of the range, in characters + + + The possible values for the %GTK_ACCESSIBLE_STATE_PRESSED + line="1812">The possible values for the %GTK_ACCESSIBLE_STATE_PRESSED accessible state. Note that the %GTK_ACCESSIBLE_TRISTATE_FALSE and @@ -4338,7 +5988,7 @@ as %FALSE and %TRUE. glib:name="GTK_ACCESSIBLE_TRISTATE_FALSE"> The state is `false` + line="1814">The state is `false` glib:name="GTK_ACCESSIBLE_TRISTATE_TRUE"> The state is `true` + line="1815">The state is `true` glib:name="GTK_ACCESSIBLE_TRISTATE_MIXED"> The state is `mixed` + line="1816">The state is `mixed` glib:get-type="gtk_action_bar_get_type"> `GtkActionBar` is designed to present contextual actions. + line="34">Presents contextual actions. -![An example GtkActionBar](action-bar.png) +<picture> + <source srcset="action-bar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkActionBar" src="action-bar.png"> +</picture> -It is expected to be displayed below the content and expand +`GtkActionBar` is expected to be displayed below the content and expand horizontally to fill the area. It allows placing children at the start or the end. In addition, it @@ -4401,7 +6054,7 @@ actionbar A `GtkActionBar`'s CSS node is called `actionbar`. It contains a `revealer` subnode, which contains a `box` subnode, which contains two `box` subnodes at -the start and end of the action bar, with `start` and `end style classes +the start and end of the action bar, with `start` and `end` style classes respectively, as well as a center node that represents the center child. Each of the boxes contains children packed for that side. @@ -4411,12 +6064,12 @@ Each of the boxes contains children packed for that side. Creates a new `GtkActionBar` widget. + line="328">Creates a new action bar widget. a new `GtkActionBar` + line="333">a new `GtkActionBar` @@ -4424,19 +6077,19 @@ Each of the boxes contains children packed for that side. c:identifier="gtk_action_bar_get_center_widget"> Retrieves the center bar widget of the bar. + line="312">Retrieves the center bar widget of the bar. the center `GtkWidget` + line="318">the center widget a `GtkActionBar` + line="314">an action bsar @@ -4444,15 +6097,14 @@ Each of the boxes contains children packed for that side. - Gets whether the contents of the action bar are revealed. + line="365">Gets whether the contents of the action bar are revealed. the current value of the [property@Gtk.ActionBar:revealed] + line="371">the current value of the [property@Gtk.ActionBar:revealed] property @@ -4460,7 +6112,7 @@ Each of the boxes contains children packed for that side. a `GtkActionBar` + line="367">an action bar @@ -4468,8 +6120,8 @@ Each of the boxes contains children packed for that side. Adds @child to @action_bar, packed with reference to the -end of the @action_bar. + line="261">Adds a child to the action bar, packed with reference to the +end of the action bar. @@ -4478,13 +6130,13 @@ end of the @action_bar. A `GtkActionBar` + line="263">an action bar the `GtkWidget` to be added to @action_bar + line="264">the widget to be added @@ -4492,8 +6144,8 @@ end of the @action_bar. Adds @child to @action_bar, packed with reference to the -start of the @action_bar. + line="246">Adds a child to the action, packed with reference to the +start of the action bar. @@ -4502,13 +6154,13 @@ start of the @action_bar. A `GtkActionBar` + line="248">an action bar the `GtkWidget` to be added to @action_bar + line="249">the widget to be added @@ -4516,7 +6168,7 @@ start of the @action_bar. Removes a child from @action_bar. + line="276">Removes a child from the action bar. @@ -4525,13 +6177,13 @@ start of the @action_bar. a `GtkActionBar` + line="278">an action bar the `GtkWidget` to be removed + line="279">the widget to be removed @@ -4540,7 +6192,7 @@ start of the @action_bar. c:identifier="gtk_action_bar_set_center_widget"> Sets the center widget for the `GtkActionBar`. + line="298">Sets the center widget for the action bar. @@ -4549,7 +6201,7 @@ start of the @action_bar. a `GtkActionBar` + line="300">an action bar allow-none="1"> a widget to use for the center + line="301">a widget to use for the center @@ -4566,12 +6218,11 @@ start of the @action_bar. - Reveals or conceals the content of the action bar. + line="341">Reveals or conceals the content of the action bar. -Note: this does not show or hide @action_bar in the +Note: this does not show or hide the action bar in the [property@Gtk.Widget:visible] sense, so revealing has no effect if the action bar is hidden. @@ -4582,13 +6233,13 @@ no effect if the action bar is hidden. a `GtkActionBar` + line="343">an action bar The new value of the property + line="344">the new value for the property @@ -4599,13 +6250,9 @@ no effect if the action bar is hidden. setter="set_revealed" getter="get_revealed" default-value="TRUE"> - - Controls whether the action bar shows its contents. + line="177">Controls whether the action bar shows its contents. @@ -4617,8 +6264,7 @@ no effect if the action bar is hidden. glib:type-struct="ActionableInterface"> The `GtkActionable` interface provides a convenient way of associating -widgets with actions. + line="26">Provides a way to associate widgets with actions. It primarily consists of two properties: [property@Gtk.Actionable:action-name] and [property@Gtk.Actionable:action-target]. There are also some convenience @@ -4633,53 +6279,50 @@ as well. - Gets the action name for @actionable. + line="78">Gets the action name for @actionable. the action name + line="84">the action name a `GtkActionable` widget + line="80">a `GtkActionable` widget - Gets the current target value of @actionable. + line="124">Gets the current target value of @actionable. the current target value + line="130">the current target value a `GtkActionable` widget + line="126">a `GtkActionable` widget - Specifies the name of the action with which this widget should be + line="95">Specifies the name of the action with which this widget should be associated. If @action_name is %NULL then the widget will be unassociated from @@ -4700,7 +6343,7 @@ associated with the window. a `GtkActionable` widget + line="97">a `GtkActionable` widget allow-none="1"> an action name + line="98">an action name - Sets the target value of an actionable widget. + line="141">Sets the target value of an actionable widget. If @target_value is %NULL then the target value is unset. @@ -4745,7 +6387,7 @@ rendered inactive). a `GtkActionable` widget + line="143">a `GtkActionable` widget allow-none="1"> a [struct@GLib.Variant] to set as the target value + line="144">a [struct@GLib.Variant] to set as the target value @@ -4762,44 +6404,43 @@ rendered inactive). - Gets the action name for @actionable. + line="78">Gets the action name for @actionable. the action name + line="84">the action name a `GtkActionable` widget + line="80">a `GtkActionable` widget - + c:identifier="gtk_actionable_get_action_target_value" + glib:get-property="action-target"> Gets the current target value of @actionable. + line="124">Gets the current target value of @actionable. the current target value + line="130">the current target value a `GtkActionable` widget + line="126">a `GtkActionable` widget @@ -4807,10 +6448,9 @@ rendered inactive). - Specifies the name of the action with which this widget should be + line="95">Specifies the name of the action with which this widget should be associated. If @action_name is %NULL then the widget will be unassociated from @@ -4831,7 +6471,7 @@ associated with the window. a `GtkActionable` widget + line="97">a `GtkActionable` widget allow-none="1"> an action name + line="98">an action name @@ -4851,7 +6491,7 @@ associated with the window. introspectable="0"> Sets the target of an actionable widget. + line="175">Sets the target of an actionable widget. This is a convenience function that calls [ctor@GLib.Variant.new] for @format_string and uses the result to call @@ -4868,29 +6508,29 @@ the action name at the same time, you can use a `GtkActionable` widget + line="177">a `GtkActionable` widget a [struct@GLib.Variant] format string + line="178">a [struct@GLib.Variant] format string arguments appropriate for @format_string + line="179">arguments appropriate for @format_string - + c:identifier="gtk_actionable_set_action_target_value" + glib:set-property="action-target"> Sets the target value of an actionable widget. + line="141">Sets the target value of an actionable widget. If @target_value is %NULL then the target value is unset. @@ -4916,7 +6556,7 @@ rendered inactive). a `GtkActionable` widget + line="143">a `GtkActionable` widget allow-none="1"> a [struct@GLib.Variant] to set as the target value + line="144">a [struct@GLib.Variant] to set as the target value @@ -4934,7 +6574,7 @@ rendered inactive). c:identifier="gtk_actionable_set_detailed_action_name"> Sets the action-name and associated string target value of an + line="203">Sets the action-name and associated string target value of an actionable widget. @detailed_action_name is a string in the format accepted by @@ -4947,13 +6587,13 @@ actionable widget. a `GtkActionable` widget + line="205">a `GtkActionable` widget the detailed action name + line="206">the detailed action name @@ -4964,12 +6604,18 @@ actionable widget. setter="set_action_name" getter="get_action_name" default-value="NULL"> + The name of the action with which this widget should be associated. + The target value of the actionable widget's action. @@ -4978,31 +6624,37 @@ actionable widget. glib:is-gtype-struct-for="Actionable"> The interface vtable for `GtkActionable`. + line="43">The interface vtable for `GtkActionable`. + virtual function for [method@Actionable.get_action_name] the action name + line="84">the action name a `GtkActionable` widget + line="80">a `GtkActionable` widget + virtual function for [method@Actionable.set_action_name] @@ -5012,7 +6664,7 @@ actionable widget. a `GtkActionable` widget + line="97">a `GtkActionable` widget an action name + line="98">an action name + virtual function for [method@Actionable.get_action_target_value] the current target value + line="130">the current target value a `GtkActionable` widget + line="126">a `GtkActionable` widget + virtual function for [method@Actionable.set_action_target_value] @@ -5056,7 +6714,7 @@ actionable widget. a `GtkActionable` widget + line="143">a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value + line="144">a [struct@GLib.Variant] to set as the target value @@ -5081,20 +6739,22 @@ actionable widget. glib:type-struct="ActivateActionClass"> A `GtkShortcutAction` that calls gtk_widget_activate(). - + line="122">Activates a widget. + +Widgets are activated by calling [method@Gtk.Widget.activate]. + Gets the activate action. + line="492">Gets the activate action. This is an action that calls gtk_widget_activate() on the given widget upon activation. - + The activate action + line="500">The activate action @@ -5104,7 +6764,7 @@ on the given widget upon activation. disguised="1" opaque="1" glib:is-gtype-struct-for="ActivateAction"> - + glib:type-struct="AdjustmentClass"> `GtkAdjustment` is a model for a numeric value. + line="32">A model for a numeric value. The `GtkAdjustment` has an associated lower and upper bound. It also contains step and page increments, and a page size. @@ -5130,49 +6790,49 @@ it is left up to the owner of the `GtkAdjustment` to control the value. Creates a new `GtkAdjustment`. + line="374">Creates a new `GtkAdjustment`. a new `GtkAdjustment` + line="385">a new `GtkAdjustment` the initial value + line="376">the initial value the minimum value + line="377">the minimum value the maximum value + line="378">the maximum value the step increment + line="379">the step increment the page increment + line="380">the page increment the page size + line="381">the page size @@ -5202,8 +6862,8 @@ it is left up to the owner of the `GtkAdjustment` to control the value. Updates the value property to ensure that the range -between @lower and @upper is in the current page. + line="863">Updates the value of the adjustment to ensure that the +given range is contained in the current page. The current page goes from `value` to `value` + `page-size`. If the range is larger than the page size, then only the @@ -5219,19 +6879,19 @@ if the value is changed. a `GtkAdjustment` + line="865">an adjustment the lower value + line="866">the lower value the upper value + line="867">the upper value @@ -5239,7 +6899,7 @@ if the value is changed. Sets all properties of the adjustment at once. + line="805">Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the [signal@Gtk.Adjustment::changed] signal. See @@ -5254,43 +6914,43 @@ way of compressing multiple emissions of a `GtkAdjustment` + line="807">an adjustment the new value + line="808">the new value the new minimum value + line="809">the new minimum value the new maximum value + line="810">the new maximum value the new step increment + line="811">the new step increment the new page increment + line="812">the new page increment the new page size + line="813">the new page size @@ -5298,22 +6958,21 @@ way of compressing multiple emissions of - Retrieves the minimum value of the adjustment. + line="574">Retrieves the minimum value of the adjustment. The current minimum value of the adjustment + line="580">the minimum value a `GtkAdjustment` + line="576">an adjustment @@ -5322,19 +6981,19 @@ way of compressing multiple emissions of c:identifier="gtk_adjustment_get_minimum_increment"> Gets the smaller of step increment and page increment. + line="909">Gets the smaller of step increment and page increment. the minimum increment of @adjustment + line="915">the minimum increment a `GtkAdjustment` + line="911">an adjustment @@ -5342,22 +7001,21 @@ way of compressing multiple emissions of - Retrieves the page increment of the adjustment. + line="717">Retrieves the page increment of the adjustment. The current page increment of the adjustment + line="723">the page increment a `GtkAdjustment` + line="719">an adjustment @@ -5365,22 +7023,21 @@ way of compressing multiple emissions of - Retrieves the page size of the adjustment. + line="761">Retrieves the page size of the adjustment. The current page size of the adjustment + line="767">the page size a `GtkAdjustment` + line="763">an adjustment @@ -5388,22 +7045,21 @@ way of compressing multiple emissions of - Retrieves the step increment of the adjustment. + line="673">Retrieves the step increment of the adjustment. The current step increment of the adjustment. + line="679">the step increment a `GtkAdjustment` + line="675">an adjustment @@ -5411,22 +7067,21 @@ way of compressing multiple emissions of - Retrieves the maximum value of the adjustment. + line="626">Retrieves the maximum value of the adjustment. The current maximum value of the adjustment + line="632">the maximum value a `GtkAdjustment` + line="628">an adjustment @@ -5434,22 +7089,21 @@ way of compressing multiple emissions of - Gets the current value of the adjustment. + line="405">Gets the current value of the adjustment. The current value of the adjustment + line="411">the current value a `GtkAdjustment` + line="407">an adjustment @@ -5457,10 +7111,9 @@ way of compressing multiple emissions of - Sets the minimum value of the adjustment. + line="592">Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual setters, multiple [signal@Gtk.Adjustment::changed] signals will @@ -5481,13 +7134,13 @@ to change, or using [method@Gtk.Adjustment.configure] has the same effect. a `GtkAdjustment` + line="594">an adjustment the new minimum value + line="595">the new minimum value @@ -5495,10 +7148,9 @@ to change, or using [method@Gtk.Adjustment.configure] has the same effect. - Sets the page increment of the adjustment. + line="735">Sets the page increment of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] @@ -5511,13 +7163,13 @@ signal when setting multiple adjustment properties. a `GtkAdjustment` + line="737">an adjustment the new page increment + line="738">the new page increment @@ -5525,10 +7177,9 @@ signal when setting multiple adjustment properties. - Sets the page size of the adjustment. + line="779">Sets the page size of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] @@ -5541,13 +7192,13 @@ signal when setting multiple adjustment properties. a `GtkAdjustment` + line="781">an adjustment the new page size + line="782">the new page size @@ -5555,10 +7206,9 @@ signal when setting multiple adjustment properties. - Sets the step increment of the adjustment. + line="691">Sets the step increment of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] @@ -5571,13 +7221,13 @@ signal when setting multiple adjustment properties. a `GtkAdjustment` + line="693">an adjustment the new step increment + line="694">the new step increment @@ -5585,10 +7235,9 @@ signal when setting multiple adjustment properties. - Sets the maximum value of the adjustment. + line="644">Sets the maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. @@ -5604,13 +7253,13 @@ signal when setting multiple adjustment properties. a `GtkAdjustment` + line="646">an adjustment the new maximum value + line="647">the new maximum value @@ -5618,10 +7267,9 @@ signal when setting multiple adjustment properties. - Sets the `GtkAdjustment` value. + line="541">Sets the `GtkAdjustment` value. The value is clamped to lie between [property@Gtk.Adjustment:lower] and [property@Gtk.Adjustment:upper]. @@ -5638,13 +7286,13 @@ the effective range of allowed values goes from a `GtkAdjustment` + line="543">an adjustment the new value + line="544">the new value @@ -5655,10 +7303,6 @@ the effective range of allowed values goes from setter="set_lower" getter="get_lower" default-value="0.000000"> - - The minimum value of the adjustment. @@ -5670,10 +7314,6 @@ the effective range of allowed values goes from setter="set_page_increment" getter="get_page_increment" default-value="0.000000"> - - The page increment of the adjustment. @@ -5685,10 +7325,6 @@ the effective range of allowed values goes from setter="set_page_size" getter="get_page_size" default-value="0.000000"> - - The page size of the adjustment. @@ -5704,10 +7340,6 @@ if the adjustment is used for a simple scalar value, e.g. in a setter="set_step_increment" getter="get_step_increment" default-value="0.000000"> - - The step increment of the adjustment. @@ -5719,10 +7351,6 @@ if the adjustment is used for a simple scalar value, e.g. in a setter="set_upper" getter="get_upper" default-value="0.000000"> - - The maximum value of the adjustment. @@ -5737,10 +7365,6 @@ property is nonzero. setter="set_value" getter="get_value" default-value="0.000000"> - - The value of the adjustment. @@ -5847,12 +7471,10 @@ covered by the [signal@Gtk.Adjustment::value-changed] signal. glib:type-struct="AlertDialogClass"> A `GtkAlertDialog` object collects the arguments that -are needed to present a message to the user. + line="29">Collects the arguments that are needed to present a message to the user. The message is shown with the [method@Gtk.AlertDialog.choose] -function. This API follows the GIO async pattern, and the result can -be obtained by calling [method@Gtk.AlertDialog.choose_finish]. +function. If you don't need to wait for a button to be clicked, you can use [method@Gtk.AlertDialog.show]. @@ -5863,7 +7485,7 @@ If you don't need to wait for a button to be clicked, you can use introspectable="0"> Creates a new `GtkAlertDialog` object. + line="286">Creates a new `GtkAlertDialog` object. The message will be set to the formatted string resulting from the arguments. @@ -5871,34 +7493,31 @@ resulting from the arguments. the new `GtkAlertDialog` + line="296">the new `GtkAlertDialog` printf()-style format string + line="288">`printf()`-style format string arguments for @format + line="289">arguments for @format + version="4.10" + glib:finish-func="choose_finish"> This function shows the alert to the user. - -The @callback will be called when the alert is dismissed. -It should call [method@Gtk.AlertDialog.choose_finish] -to obtain the result. + line="678">Shows the alert to the user. It is ok to pass `NULL` for the callback if the alert does not have more than one button. A simpler API for @@ -5911,7 +7530,7 @@ this case is [method@Gtk.AlertDialog.show]. a `GtkAlertDialog` + line="680">an alert dialog allow-none="1"> the parent `GtkWindow` + line="681">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="682">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="683">a callback to call + when the operation is complete + allow-none="1"> data to pass to @callback + line="685">data to pass to @callback @@ -5961,13 +7580,12 @@ this case is [method@Gtk.AlertDialog.show]. throws="1"> Finishes the [method@Gtk.AlertDialog.choose] call -and returns the index of the button that was clicked. + line="721">Finishes the [method@Gtk.AlertDialog.choose] call. the index of the button that was clicked, or -1 if + line="729">the index of the button that was clicked, or -1 if the dialog was cancelled and [property@Gtk.AlertDialog:cancel-button] is not set @@ -5976,13 +7594,13 @@ and returns the index of the button that was clicked. a `GtkAlertDialog` + line="723">an alert dialog a `GAsyncResult` + line="724">the result @@ -5993,12 +7611,12 @@ and returns the index of the button that was clicked. version="4.10"> Returns the button labels for the alert. + line="458">Returns the button labels for the alert. the button labels + line="464">the button labels @@ -6007,7 +7625,7 @@ and returns the index of the button that was clicked. a `GtkAlertDialog` + line="460">an alert dialog @@ -6018,19 +7636,19 @@ and returns the index of the button that was clicked. version="4.10"> Returns the index of the cancel button. + line="498">Returns the index of the cancel button. the index of the cancel button, or -1 + line="504">the index of the cancel button, or -1 a `GtkAlertDialog` + line="500">an alert dialog @@ -6041,19 +7659,19 @@ and returns the index of the button that was clicked. version="4.10"> Returns the index of the default button. + line="541">Returns the index of the default button. the index of the default button, or -1 + line="547">the index of the default button, or -1 a `GtkAlertDialog` + line="543">an alert dialog @@ -6064,19 +7682,19 @@ and returns the index of the button that was clicked. version="4.10"> Returns the detail text that will be shown in the alert. + line="412">Returns the detail text that will be shown in the alert. the detail text + line="418">the detail text a `GtkAlertDialog` + line="414">an alert dialog @@ -6087,19 +7705,19 @@ and returns the index of the button that was clicked. version="4.10"> Returns the message that will be shown in the alert. + line="366">Returns the message that will be shown in the alert. the message + line="372">the message a `GtkAlertDialog` + line="368">an alert dialog @@ -6110,20 +7728,20 @@ and returns the index of the button that was clicked. version="4.10"> Returns whether the alert blocks interaction + line="323">Returns whether the alert blocks interaction with the parent window while it is presented. `TRUE` if the alert is modal + line="330">true if the alert is modal a `GtkAlertDialog` + line="325">an alert dialog @@ -6134,7 +7752,7 @@ with the parent window while it is presented. version="4.10"> Sets the button labels for the alert. + line="476">Sets the button labels for the alert. @@ -6143,13 +7761,13 @@ with the parent window while it is presented. a `GtkAlertDialog` + line="478">an alert dialog the new button labels + line="479">the new button labels @@ -6162,7 +7780,7 @@ with the parent window while it is presented. version="4.10"> Sets the index of the cancel button. + line="516">Sets the index of the cancel button. See [property@Gtk.AlertDialog:cancel-button] for details of how this value is used. @@ -6174,13 +7792,13 @@ details of how this value is used. a `GtkAlertDialog` + line="518">an alert dialog the new cancel button + line="519">the new cancel button @@ -6191,7 +7809,7 @@ details of how this value is used. version="4.10"> Sets the index of the default button. + line="559">Sets the index of the default button. See [property@Gtk.AlertDialog:default-button] for details of how this value is used. @@ -6203,13 +7821,13 @@ details of how this value is used. a `GtkAlertDialog` + line="561">an alert dialog the new default button + line="562">the new default button @@ -6220,7 +7838,7 @@ details of how this value is used. version="4.10"> Sets the detail text that will be shown in the alert. + line="430">Sets the detail text that will be shown in the alert. @@ -6229,13 +7847,13 @@ details of how this value is used. a `GtkAlertDialog` + line="432">an alert dialog the new detail text + line="433">the new detail text @@ -6246,7 +7864,7 @@ details of how this value is used. version="4.10"> Sets the message that will be shown in the alert. + line="384">Sets the message that will be shown in the alert. @@ -6255,13 +7873,13 @@ details of how this value is used. a `GtkAlertDialog` + line="386">an alert dialog the new message + line="387">the new message @@ -6272,7 +7890,7 @@ details of how this value is used. version="4.10"> Sets whether the alert blocks interaction + line="342">Sets whether the alert blocks interaction with the parent window while it is presented. @@ -6282,13 +7900,13 @@ with the parent window while it is presented. a `GtkAlertDialog` + line="344">an alert dialog the new value + line="345">the new value @@ -6296,13 +7914,14 @@ with the parent window while it is presented. Show the alert to the user. + line="750">Shows the alert to the user. -This function is a simple version of [method@Gtk.AlertDialog.choose] +This function is a simpler version of [method@Gtk.AlertDialog.choose] intended for dialogs with a single button. -If you want to cancel the dialog or if the alert has more than one button, -you should use that function instead and provide it with a #GCancellable or -callback respectively. + +If you want to cancel the dialog or if the alert has more than one +button, you should use that function instead and provide it with a +[class@Gio.Cancellable] and callback respectively. @@ -6311,7 +7930,7 @@ callback respectively. a `GtkAlertDialog` + line="752">an alert dialog allow-none="1"> the parent `GtkWindow` + line="753">the parent window @@ -6331,16 +7950,12 @@ callback respectively. transfer-ownership="none" setter="set_buttons" getter="get_buttons"> - - Labels for buttons to show in the alert. + line="222">Labels for buttons to show in the alert. The labels should be translated and may contain -a _ to indicate the mnemonic character. +a `_` character to indicate the mnemonic character. If this property is not set, then a 'Close' button is automatically created. @@ -6355,14 +7970,10 @@ automatically created. setter="set_cancel_button" getter="get_cancel_button" default-value="-1"> - - This property determines what happens when the Escape key is -pressed while the alert is shown. + line="240">Determines what happens when the <kbd>Escape</kbd> key is pressed +while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Escape is treated as if that button was pressed. If it is -1 @@ -6379,14 +7990,10 @@ is treated as both cancel and default button, so 0 is returned. setter="set_default_button" getter="get_default_button" default-value="-1"> - - This property determines what happens when the Return key is -pressed while the alert is shown. + line="260">Determines what happens when the <kbd>Return</kbd> key is pressed +while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Return is treated as if that button was pressed. If it is -1 @@ -6403,13 +8010,9 @@ is treated as both cancel and default button, so 0 is returned. setter="set_detail" getter="get_detail" default-value="NULL"> - - The detail text for the alert. + line="210">The detail text for the alert. setter="set_message" getter="get_message" default-value="NULL"> - - The message for the alert. + line="198">The message for the alert. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the alert is modal. + line="186">Whether the alert is modal. @@ -6472,7 +8067,7 @@ Note that in horizontal context `GTK_ALIGN_START` and `GTK_ALIGN_END` are interpreted relative to text direction. Baseline support is optional for containers and widgets, and is only available -for vertical alignment. `GTK_ALIGN_BASELINE_CENTER and `GTK_ALIGN_BASELINE_FILL` +for vertical alignment. `GTK_ALIGN_BASELINE_CENTER` and `GTK_ALIGN_BASELINE_FILL` are treated similar to `GTK_ALIGN_CENTER` and `GTK_ALIGN_FILL`, except that it positions the widget to line up the baselines, where that is supported. a different name for `GTK_ALIGN_BASELINE`. Since 4.12 + line="69">a different name for `GTK_ALIGN_BASELINE`. glib:name="GTK_ALIGN_BASELINE"> align the widget according to the baseline. - See [class@Gtk.Widget]. Deprecated: 4.12: Use `GTK_ALIGN_BASELINE_FILL` instead + line="62">align the widget according to the baseline. + Use `GTK_ALIGN_BASELINE_FILL` instead stretch to fill all space, but align the baseline. Since 4.12 + line="76">stretch to fill all space, but align the baseline. glib:type-struct="AlternativeTriggerClass"> A `GtkShortcutTrigger` that combines two triggers. + line="118">Combines two shortcut triggers. -The `GtkAlternativeTrigger` triggers when either of two trigger. +The `GtkAlternativeTrigger` triggers when either of the two trigger. This can be cascaded to combine more than two triggers. @@ -6589,7 +8186,6 @@ alternative, create a new alternative trigger for each option. - Gets the first of the two alternative triggers that may @@ -6616,7 +8212,6 @@ the other one. - Gets the second of the two alternative triggers that may @@ -6645,8 +8240,6 @@ the other one. construct-only="1" transfer-ownership="none" getter="get_first"> - The first `GtkShortcutTrigger` to check. @@ -6657,8 +8250,6 @@ the other one. construct-only="1" transfer-ownership="none" getter="get_second"> - The second `GtkShortcutTrigger` to check. @@ -6681,7 +8272,7 @@ the other one. glib:type-struct="AnyFilterClass"> `GtkAnyFilter` matches an item when at least one of its filters matches. + line="42">Matches an item when at least one of its filters matches. To add filters to a `GtkAnyFilter`, use [method@Gtk.MultiFilter.append]. @@ -6690,7 +8281,7 @@ To add filters to a `GtkAnyFilter`, use [method@Gtk.MultiFilter.append]. Creates a new empty "any" filter. + line="370">Creates a new empty "any" filter. Use [method@Gtk.MultiFilter.append] to add filters to it. @@ -6701,7 +8292,7 @@ has been added to it, the filter matches no item. a new `GtkAnyFilter` + line="381">a new `GtkAnyFilter` @@ -6775,7 +8366,6 @@ use [method@Gtk.AppChooser.get_app_info]. glib:get-property="content-type" deprecated="1" deprecated-version="4.10"> - Returns the content type for which the `GtkAppChooser` @@ -6824,8 +8414,6 @@ shows applications. transfer-ownership="none" getter="get_content_type" default-value="NULL"> - The content type of the `GtkAppChooser` object. @@ -6846,7 +8434,10 @@ See `GContentType` for more information about content types. filename="gtk/deprecated/gtkappchooserbutton.c" line="21">The `GtkAppChooserButton` lets the user select an application. -![An example GtkAppChooserButton](appchooserbutton.png) +<picture> + <source srcset="appchooserbutton-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkAppChooserButton" src="appchooserbutton.png"> +</picture> Initially, a `GtkAppChooserButton` selects the first application in its list, which will either be the most-recently used application @@ -6884,7 +8475,7 @@ To track changes in the selected application, use the deprecated-version="4.10"> Creates a new `GtkAppChooserButton` for applications + line="887">Creates a new `GtkAppChooserButton` for applications that can handle content of the given type. This widget will be removed in GTK 5 a newly created `GtkAppChooserButton` + line="894">a newly created `GtkAppChooserButton` the content type to show applications for + line="889">the content type to show applications for @@ -6910,7 +8501,7 @@ that can handle content of the given type. deprecated-version="4.10"> Appends a custom item to the list of applications that is shown + line="928">Appends a custom item to the list of applications that is shown in the popup. The item name must be unique per-widget. Clients can use the @@ -6929,25 +8520,25 @@ See also [method@Gtk.AppChooserButton.append_separator]. a `GtkAppChooserButton` + line="930">a `GtkAppChooserButton` the name of the custom item + line="931">the name of the custom item the label for the custom item + line="932">the label for the custom item the icon for the custom item + line="933">the icon for the custom item @@ -6958,7 +8549,7 @@ See also [method@Gtk.AppChooserButton.append_separator]. deprecated-version="4.10"> Appends a separator to the list of applications that is shown + line="908">Appends a separator to the list of applications that is shown in the popup. This widget will be removed in GTK 5 a `GtkAppChooserButton` + line="910">a `GtkAppChooserButton` @@ -6980,17 +8571,16 @@ in the popup. glib:get-property="heading" deprecated="1" deprecated-version="4.10"> - Returns the text to display at the top of the dialog. + line="1106">Returns the text to display at the top of the dialog. This widget will be removed in GTK 5 the text to display at the top of the dialog, + line="1112">the text to display at the top of the dialog, or %NULL, in which case a default text is displayed @@ -6998,7 +8588,7 @@ in the popup. a `GtkAppChooserButton` + line="1108">a `GtkAppChooserButton` @@ -7008,24 +8598,23 @@ in the popup. glib:get-property="modal" deprecated="1" deprecated-version="4.10"> - Gets whether the dialog is modal. + line="1148">Gets whether the dialog is modal. This widget will be removed in GTK 5 %TRUE if the dialog is modal + line="1154">%TRUE if the dialog is modal a `GtkAppChooserButton` + line="1150">a `GtkAppChooserButton` @@ -7035,11 +8624,9 @@ in the popup. glib:get-property="show-default-item" deprecated="1" deprecated-version="4.10"> - Returns whether the dropdown menu should show the default + line="1038">Returns whether the dropdown menu should show the default application at the top. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserButton:show-default-item] + line="1045">the value of [property@Gtk.AppChooserButton:show-default-item] a `GtkAppChooserButton` + line="1040">a `GtkAppChooserButton` @@ -7064,11 +8651,9 @@ application at the top. glib:get-property="show-dialog-item" deprecated="1" deprecated-version="4.10"> - Returns whether the dropdown menu shows an item + line="995">Returns whether the dropdown menu shows an item for a `GtkAppChooserDialog`. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserButton:show-dialog-item] + line="1002">the value of [property@Gtk.AppChooserButton:show-dialog-item] a `GtkAppChooserButton` + line="997">a `GtkAppChooserButton` @@ -7094,7 +8679,7 @@ for a `GtkAppChooserDialog`. deprecated-version="4.10"> Selects a custom item. + line="962">Selects a custom item. See [method@Gtk.AppChooserButton.append_custom_item]. @@ -7110,13 +8695,13 @@ to its initial state. a `GtkAppChooserButton` + line="964">a `GtkAppChooserButton` the name of the custom item + line="965">the name of the custom item @@ -7126,10 +8711,9 @@ to its initial state. glib:set-property="heading" deprecated="1" deprecated-version="4.10"> - Sets the text to display at the top of the dialog. + line="1083">Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. This widget will be removed in GTK 5 @@ -7142,13 +8726,13 @@ If the heading is not set, the dialog displays a default text. a `GtkAppChooserButton` + line="1085">a `GtkAppChooserButton` a string containing Pango markup + line="1086">a string containing Pango markup @@ -7158,10 +8742,9 @@ If the heading is not set, the dialog displays a default text. glib:set-property="modal" deprecated="1" deprecated-version="4.10"> - Sets whether the dialog should be modal. + line="1125">Sets whether the dialog should be modal. This widget will be removed in GTK 5 @@ -7172,13 +8755,13 @@ If the heading is not set, the dialog displays a default text. a `GtkAppChooserButton` + line="1127">a `GtkAppChooserButton` %TRUE to make the dialog modal + line="1128">%TRUE to make the dialog modal @@ -7188,11 +8771,9 @@ If the heading is not set, the dialog displays a default text. glib:set-property="show-default-item" deprecated="1" deprecated-version="4.10"> - Sets whether the dropdown menu of this button should show the + line="1057">Sets whether the dropdown menu of this button should show the default application for the given content type at top. This widget will be removed in GTK 5 a `GtkAppChooserButton` + line="1059">a `GtkAppChooserButton` the new value for [property@Gtk.AppChooserButton:show-default-item] + line="1060">the new value for [property@Gtk.AppChooserButton:show-default-item] @@ -7220,11 +8801,9 @@ default application for the given content type at top. glib:set-property="show-dialog-item" deprecated="1" deprecated-version="4.10"> - Sets whether the dropdown menu of this button should show an + line="1014">Sets whether the dropdown menu of this button should show an entry to trigger a `GtkAppChooserDialog`. This widget will be removed in GTK 5 a `GtkAppChooserButton` + line="1016">a `GtkAppChooserButton` the new value for [property@Gtk.AppChooserButton:show-dialog-item] + line="1017">the new value for [property@Gtk.AppChooserButton:show-dialog-item] @@ -7253,13 +8832,9 @@ entry to trigger a `GtkAppChooserDialog`. setter="set_heading" getter="get_heading" default-value="NULL"> - - The text to show at the top of the dialog that can be + line="710">The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. @@ -7272,13 +8847,9 @@ The string may contain Pango markup. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the app chooser dialog should be modal. + line="723">Whether the app chooser dialog should be modal. setter="set_show_default_item" getter="get_show_default_item" default-value="FALSE"> - - Determines whether the dropdown menu shows the default application + line="699">Determines whether the dropdown menu shows the default application on top for the provided content type. @@ -7305,20 +8872,16 @@ on top for the provided content type. setter="set_show_dialog_item" getter="get_show_dialog_item" default-value="FALSE"> - - Determines whether the dropdown menu shows an item to open + line="688">Determines whether the dropdown menu shows an item to open a `GtkAppChooserDialog`. Emitted to when the button is activated. + line="770">Emitted to when the button is activated. The `::activate` signal on `GtkAppChooserButton` is an action signal and emitting it causes the button to pop up its dialog. @@ -7329,7 +8892,7 @@ emitting it causes the button to pop up its dialog. Emitted when the active application changes. + line="734">Emitted when the active application changes. @@ -7337,7 +8900,7 @@ emitting it causes the button to pop up its dialog. Emitted when a custom item is activated. + line="750">Emitted when a custom item is activated. Use [method@Gtk.AppChooserButton.append_custom_item], to add custom items. @@ -7348,7 +8911,7 @@ to add custom items. the name of the activated item + line="753">the name of the activated item @@ -7366,7 +8929,10 @@ to add custom items. filename="gtk/deprecated/gtkappchooserdialog.c" line="25">`GtkAppChooserDialog` shows a `GtkAppChooserWidget` inside a `GtkDialog`. -![An example GtkAppChooserDialog](appchooserdialog.png) +<picture> + <source srcset="appchooserdialog-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkAppChooserDialog" src="appchooserdialog.png"> +</picture> Note that `GtkAppChooserDialog` does not have any interesting methods of its own. Instead, you should get the embedded `GtkAppChooserWidget` @@ -7397,7 +8963,7 @@ class `.appchooser`. deprecated-version="4.10"> Creates a new `GtkAppChooserDialog` for the provided `GFile`. + line="676">Creates a new `GtkAppChooserDialog` for the provided `GFile`. The dialog will show applications that can open the file. This widget will be removed in GTK 5 @@ -7406,7 +8972,7 @@ The dialog will show applications that can open the file. a newly created `GtkAppChooserDialog` + line="686">a newly created `GtkAppChooserDialog` @@ -7416,19 +8982,19 @@ The dialog will show applications that can open the file. allow-none="1"> a `GtkWindow` + line="678">a `GtkWindow` flags for this dialog + line="679">flags for this dialog a `GFile` + line="680">a `GFile` @@ -7439,7 +9005,7 @@ The dialog will show applications that can open the file. deprecated-version="4.10"> Creates a new `GtkAppChooserDialog` for the provided content type. + line="708">Creates a new `GtkAppChooserDialog` for the provided content type. The dialog will show applications that can open the content type. This widget will be removed in GTK 5 @@ -7448,7 +9014,7 @@ The dialog will show applications that can open the content type. a newly created `GtkAppChooserDialog` + line="718">a newly created `GtkAppChooserDialog` @@ -7458,19 +9024,19 @@ The dialog will show applications that can open the content type. allow-none="1"> a `GtkWindow` + line="710">a `GtkWindow` flags for this dialog + line="711">flags for this dialog a content type string + line="712">a content type string @@ -7480,17 +9046,16 @@ The dialog will show applications that can open the content type. glib:get-property="heading" deprecated="1" deprecated-version="4.10"> - Returns the text to display at the top of the dialog. + line="794">Returns the text to display at the top of the dialog. This widget will be removed in GTK 5 the text to display at the top of the dialog, + line="800">the text to display at the top of the dialog, or %NULL, in which case a default text is displayed @@ -7498,7 +9063,7 @@ The dialog will show applications that can open the content type. a `GtkAppChooserDialog` + line="796">a `GtkAppChooserDialog` @@ -7509,21 +9074,21 @@ The dialog will show applications that can open the content type. deprecated-version="4.10"> Returns the `GtkAppChooserWidget` of this dialog. + line="740">Returns the `GtkAppChooserWidget` of this dialog. This widget will be removed in GTK 5 the `GtkAppChooserWidget` of @self + line="746">the `GtkAppChooserWidget` of @self a `GtkAppChooserDialog` + line="742">a `GtkAppChooserDialog` @@ -7533,10 +9098,9 @@ The dialog will show applications that can open the content type. glib:set-property="heading" deprecated="1" deprecated-version="4.10"> - Sets the text to display at the top of the dialog. + line="758">Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. This widget will be removed in GTK 5 @@ -7549,13 +9113,13 @@ If the heading is not set, the dialog displays a default text. a `GtkAppChooserDialog` + line="760">a `GtkAppChooserDialog` a string containing Pango markup + line="761">a string containing Pango markup @@ -7566,7 +9130,7 @@ If the heading is not set, the dialog displays a default text. transfer-ownership="none"> The GFile used by the `GtkAppChooserDialog`. + line="606">The GFile used by the `GtkAppChooserDialog`. The dialog's `GtkAppChooserWidget` content type will be guessed from the file, if present. @@ -7578,13 +9142,9 @@ be guessed from the file, if present. setter="set_heading" getter="get_heading" default-value="NULL"> - - The text to show at the top of the dialog. + line="620">The text to show at the top of the dialog. The string may contain Pango markup. @@ -7661,7 +9221,6 @@ that can handle content of the given type. glib:get-property="default-text" deprecated="1" deprecated-version="4.10"> - Returns the text that is shown if there are not applications @@ -7689,7 +9248,6 @@ that can handle the content type. glib:get-property="show-all" deprecated="1" deprecated-version="4.10"> - Gets whether the app chooser should show all applications @@ -7717,7 +9275,6 @@ in a flat list. glib:get-property="show-default" deprecated="1" deprecated-version="4.10"> - Gets whether the app chooser should show the default handler @@ -7745,7 +9302,6 @@ for the content type in a separate section. glib:get-property="show-fallback" deprecated="1" deprecated-version="4.10"> - Gets whether the app chooser should show related applications @@ -7773,7 +9329,6 @@ for the content type in a separate section. glib:get-property="show-other" deprecated="1" deprecated-version="4.10"> - Gets whether the app chooser should show applications @@ -7801,8 +9356,6 @@ which are unrelated to the content type. glib:get-property="show-recommended" deprecated="1" deprecated-version="4.10"> - Gets whether the app chooser should show recommended applications @@ -7830,7 +9383,6 @@ for the content type in a separate section. glib:set-property="default-text" deprecated="1" deprecated-version="4.10"> - Sets the text that is shown if there are not applications @@ -7861,7 +9413,6 @@ that can handle the content type. glib:set-property="show-all" deprecated="1" deprecated-version="4.10"> - Sets whether the app chooser should show all applications @@ -7892,7 +9443,6 @@ in a flat list. glib:set-property="show-default" deprecated="1" deprecated-version="4.10"> - Sets whether the app chooser should show the default handler @@ -7923,7 +9473,6 @@ for the content type in a separate section. glib:set-property="show-fallback" deprecated="1" deprecated-version="4.10"> - Sets whether the app chooser should show related applications @@ -7954,7 +9503,6 @@ for the content type in a separate section. glib:set-property="show-other" deprecated="1" deprecated-version="4.10"> - Sets whether the app chooser should show applications @@ -7985,8 +9533,6 @@ which are unrelated to the content type. glib:set-property="show-recommended" deprecated="1" deprecated-version="4.10"> - Sets whether the app chooser should show recommended applications @@ -8018,10 +9564,6 @@ for the content type in a separate section. setter="set_default_text" getter="get_default_text" default-value="NULL"> - - The text that appears in the widget when there are no applications @@ -8035,10 +9577,6 @@ for the given content type. setter="set_show_all" getter="get_show_all" default-value="FALSE"> - - If %TRUE, the app chooser presents all applications @@ -8053,10 +9591,6 @@ recommended or related applications. setter="set_show_default" getter="get_show_default" default-value="FALSE"> - - Determines whether the app chooser should show the default @@ -8073,10 +9607,6 @@ applications. setter="set_show_fallback" getter="get_show_fallback" default-value="FALSE"> - - Determines whether the app chooser should show a section @@ -8093,10 +9623,6 @@ other applications. setter="set_show_other" getter="get_show_other" default-value="FALSE"> - - Determines whether the app chooser should show a section @@ -8110,10 +9636,6 @@ for other applications. setter="set_show_recommended" getter="get_show_recommended" default-value="TRUE"> - - Determines whether the app chooser should show a section @@ -8169,19 +9691,18 @@ Return or Enter. glib:type-struct="ApplicationClass"> `GtkApplication` is a high-level API for writing applications. + line="56">A high-level API for writing applications. -It supports many aspects of writing a GTK application in a convenient -fashion, without enforcing a one-size-fits-all model. +`GtkApplication` supports many aspects of writing a GTK application +in a convenient fashion, without enforcing a one-size-fits-all model. -Currently, `GtkApplication` handles GTK initialization, application -uniqueness, session management, provides some basic scriptability and -desktop shell integration by exporting actions and menus and manages a -list of toplevel windows whose life-cycle is automatically tied to the -life-cycle of your application. +Currently, it handles GTK initialization, application uniqueness, session +management, provides some basic scriptability and desktop shell integration +by exporting actions and menus and manages a list of toplevel windows whose +life-cycle is automatically tied to the life-cycle of your application. -While `GtkApplication` works fine with plain [class@Gtk.Window]s, it is -recommended to use it together with [class@Gtk.ApplicationWindow]. +While `GtkApplication` works fine with plain [class@Gtk.Window]s, +it is recommended to use it together with [class@Gtk.ApplicationWindow]. ## Automatic resources @@ -8214,6 +9735,10 @@ each [class@Gtk.ApplicationWindow] and sets up the keyboard accelerator displays the shortcuts window, associate the item with the action `win.show-help-overlay`. +`GtkApplication` will also automatically set the application id as the +default window icon. Use [func@Gtk.Window.set_default_icon_name] or +[property@Gtk.Window:icon-name] to override that behavior. + ## A simple application [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/bp/bloatpad.c) @@ -8234,29 +9759,29 @@ session while inhibitors are present. ## See Also -[HowDoI: Using GtkApplication](https://wiki.gnome.org/HowDoI/GtkApplication), -[Getting Started with GTK: Basics](getting_started.html#basics) +- [Using GtkApplication](https://developer.gnome.org/documentation/tutorials/application.html) +- [Getting Started with GTK: Basics](getting_started.html#basics) Creates a new `GtkApplication` instance. + line="718">Creates a new application instance. When using `GtkApplication`, it is not necessary to call [func@Gtk.init] manually. It is called as soon as the application gets registered as the primary instance. Concretely, [func@Gtk.init] is called in the default handler for the -`GApplication::startup` signal. Therefore, `GtkApplication` subclasses should -always chain up in their `GApplication::startup` handler before using any GTK -API. +`GApplication::tartup` signal. Therefore, `GtkApplication` subclasses +should always chain up in their [vfunc@GIO.Application.startup] handler +before using any GTK API. Note that commandline arguments are not passed to [func@Gtk.init]. -If `application_id` is not %NULL, then it must be valid. See -`g_application_id_is_valid()`. +If `application_id` is not `NULL`, then it must be valid. See +[func@Gio.Application.id_is_valid]. If no application ID is given then some features (most notably application uniqueness) will be disabled. @@ -8264,7 +9789,7 @@ uniqueness) will be disabled. a new `GtkApplication` instance + line="742">a new `GtkApplication` instance @@ -8274,18 +9799,22 @@ uniqueness) will be disabled. allow-none="1"> The application ID + line="720">The application ID the application flags + line="721">the application flags + Signal emitted when a `GtkWindow` is added to + application through gtk_application_add_window(). @@ -8300,6 +9829,11 @@ uniqueness) will be disabled. + Signal emitted when a `GtkWindow` is removed from + application, either as a side-effect of being destroyed or + explicitly through gtk_application_remove_window(). @@ -8316,21 +9850,20 @@ uniqueness) will be disabled. Adds a window to `application`. + line="756">Adds a window to the application. -This call can only happen after the `application` has started; +This call can only happen after the application has started; typically, you should add new application windows in response -to the emission of the `GApplication::activate` signal. +to the emission of the [signal@GIO.Application::activate] signal. This call is equivalent to setting the [property@Gtk.Window:application] -property of `window` to `application`. +property of the window to @application. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with [method@Gtk.Application.remove_window]. -GTK will keep the `application` running as long as it has -any windows. +GTK will keep the application running as long as it has any windows. @@ -8339,13 +9872,13 @@ any windows. a `GtkApplication` + line="758">an application a `GtkWindow` + line="759">a window @@ -8354,14 +9887,14 @@ any windows. c:identifier="gtk_application_get_accels_for_action"> Gets the accelerators that are currently associated with + line="1155">Gets the accelerators that are currently associated with the given action. - accelerators for `detailed_action_name` + line="1164"> + accelerators for @detailed_action_name @@ -8370,13 +9903,13 @@ the given action. a `GtkApplication` + line="1157">an application a detailed action name, specifying an action + line="1158">a detailed action name, specifying an action and target to obtain accelerators for @@ -8386,7 +9919,7 @@ the given action. c:identifier="gtk_application_get_actions_for_accel"> Returns the list of actions (possibly empty) that `accel` maps to. + line="1180">Returns the list of actions (possibly empty) that the accelerator maps to. Each item in the list is a detailed action name in the usual form. @@ -8407,7 +9940,7 @@ If you are unsure, check it with [func@Gtk.accelerator_parse] first. a %NULL-terminated array of actions for `accel` + line="1203">actions for @accel @@ -8416,13 +9949,13 @@ If you are unsure, check it with [func@Gtk.accelerator_parse] first. a `GtkApplication` + line="1182">a application an accelerator that can be parsed by [func@Gtk.accelerator_parse] + line="1183">an accelerator that can be parsed by [func@Gtk.accelerator_parse] @@ -8430,27 +9963,26 @@ If you are unsure, check it with [func@Gtk.accelerator_parse] first. - Gets the “active” window for the application. + line="882">Gets the “active” window for the application. -The active window is the one that was most recently focused (within -the application). This window may not have the focus at the moment -if another application has it — this is just the most -recently-focused window within this application. +The active window is the one that was most recently focused +(within the application). This window may not have the focus +at the moment if another application has it — this is just +the most recently-focused window within this application. the active window + line="893">the active window a `GtkApplication` + line="884">an application @@ -8459,7 +9991,7 @@ recently-focused window within this application. c:identifier="gtk_application_get_menu_by_id"> Gets a menu from automatically loaded resources. + line="1257">Gets a menu from automatically loaded resources. See [the section on Automatic resources](class.Application.html#automatic-resources) for more information. @@ -8467,21 +9999,21 @@ for more information. Gets the menu with the - given id from the automatically loaded resources + line="1267">Gets the menu with the + given ID from the automatically loaded resources a `GtkApplication` + line="1259">an application the id of the menu to look up + line="1260">the ID of the menu to look up @@ -8489,23 +10021,21 @@ for more information. - Returns the menu model that has been set with -[method@Gtk.Application.set_menubar]. + line="958">Returns the menu model for the menu bar of the application. the menubar for windows of `application` + line="964">the menubar for windows of the application a `GtkApplication` + line="960">an application @@ -8514,7 +10044,7 @@ for more information. c:identifier="gtk_application_get_window_by_id"> Returns the [class@Gtk.ApplicationWindow] with the given ID. + line="851">Returns the window with the given ID. The ID of a `GtkApplicationWindow` can be retrieved with [method@Gtk.ApplicationWindow.get_id]. @@ -8522,20 +10052,20 @@ The ID of a `GtkApplicationWindow` can be retrieved with the window for the given `id` + line="861">the window for the given ID a `GtkApplication` + line="853">an application` an identifier number + line="854">an identifier number @@ -8543,7 +10073,7 @@ The ID of a `GtkApplicationWindow` can be retrieved with Gets a list of the [class@Gtk.Window] instances associated with `application`. + line="825">Gets a list of the window associated with the application. The list is sorted by most recently focused window, such that the first element is the currently focused window. (Useful for choosing a parent @@ -8556,8 +10086,7 @@ deletion. a `GList` of `GtkWindow` - instances + line="839">the list of windows @@ -8566,7 +10095,7 @@ deletion. a `GtkApplication` + line="827">an application @@ -8574,7 +10103,7 @@ deletion. Inform the session manager that certain types of actions should be + line="991">Informs the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of @@ -8582,7 +10111,7 @@ actions. Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The -types of actions that may be blocked are specified by the `flags` +types of actions that may be blocked are specified by the @flags parameter. When the application completes the operation it should call [method@Gtk.Application.uninhibit] to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must @@ -8593,25 +10122,28 @@ Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place. -The `reason` message should be short and to the point. +The @reason message should be short and to the point. + +If a window is given, the session manager may point the user to +this window to find out more about why the action is inhibited. -If `window` is given, the session manager may point the user to -this window to find out more about why the action is inhibited. +The cookie that is returned by this function should be used as an +argument to [method@Gtk.Application.uninhibit] in order to remove +the request. A non-zero cookie that is used to uniquely identify this - request. It should be used as an argument to [method@Gtk.Application.uninhibit] - in order to remove the request. If the platform does not support - inhibiting or the request failed for some reason, 0 is returned. + line="1027">A non-zero cookie that is used to uniquely identify this, or + 0 if the platform does not support inhibiting or the request failed + for some reason the `GtkApplication` + line="993">the application allow-none="1"> a `GtkWindow` + line="994">a window what types of actions should be inhibited + line="995">what types of actions should be inhibited @@ -8636,7 +10168,7 @@ this window to find out more about why the action is inhibited. allow-none="1"> a short, human-readable string that explains + line="996">a short, human-readable string that explains why these operations are inhibited @@ -8646,14 +10178,14 @@ this window to find out more about why the action is inhibited. c:identifier="gtk_application_list_action_descriptions"> Lists the detailed action names which have associated accelerators. + line="1092">Lists the detailed action names which have associated accelerators. See [method@Gtk.Application.set_accels_for_action]. the detailed action names + line="1100">the detailed action names @@ -8662,7 +10194,7 @@ See [method@Gtk.Application.set_accels_for_action]. a `GtkApplication` + line="1094">an application @@ -8671,14 +10203,14 @@ See [method@Gtk.Application.set_accels_for_action]. c:identifier="gtk_application_remove_window"> Remove a window from `application`. + line="797">Remove a window from the application. -If `window` belongs to `application` then this call is equivalent to -setting the [property@Gtk.Window:application] property of `window` to -`NULL`. +If the window belongs to the application then this call is +equivalent to setting the [property@Gtk.Window:application] +property of the window to `NULL`. The application may stop running as a result of a call to this -function, if `window` was the last window of the `application`. +function, if the window was the last window of the application. @@ -8687,13 +10219,13 @@ function, if `window` was the last window of the `application`. a `GtkApplication` + line="799">an application a `GtkWindow` + line="800">a window @@ -8702,17 +10234,17 @@ function, if `window` was the last window of the `application`. c:identifier="gtk_application_set_accels_for_action"> Sets zero or more keyboard accelerators that will trigger the + line="1112">Sets zero or more keyboard accelerators that will trigger the given action. -The first item in `accels` will be the primary accelerator, which may be -displayed in the UI. +The first item in @accels will be the primary accelerator, +which may be displayed in the UI. -To remove all accelerators for an action, use an empty, zero-terminated -array for `accels`. +To remove all accelerators for an action, use an empty, +zero-terminated array for @accels. -For the `detailed_action_name`, see `g_action_parse_detailed_name()` and -`g_action_print_detailed_name()`. +For the @detailed_action_name, see [func@Gio.Action.parse_detailed_name] +and [Gio.Action.print_detailed_name]. @@ -8721,20 +10253,20 @@ For the `detailed_action_name`, see `g_action_parse_detailed_name()` and a `GtkApplication` + line="1114">an application a detailed action name, specifying an action + line="1115">a detailed action name, specifying an action and target to associate accelerators with a list of accelerators in the format + line="1117">a list of accelerators in the format understood by [func@Gtk.accelerator_parse] @@ -8745,19 +10277,18 @@ For the `detailed_action_name`, see `g_action_parse_detailed_name()` and - Sets or unsets the menubar for windows of `application`. + line="915">Sets or unsets the menubar for windows of the application. This is a menubar in the traditional sense. This can only be done in the primary instance of the application, -after it has been registered. `GApplication::startup` is a good place -to call this. +after it has been registered. [vfunc@GIO.Application.startup] is +a good place to call this. Depending on the desktop environment, this may appear at the top of -each window, or at the top of the screen. In some environments, if +each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate — for example, @@ -8774,7 +10305,7 @@ user selecting these menu items. a `GtkApplication` + line="917">an application allow-none="1"> a `GMenuModel` + line="918">a menu model @@ -8791,7 +10322,7 @@ user selecting these menu items. Removes an inhibitor that has been previously established. + line="1046">Removes an inhibitor that has been previously established. See [method@Gtk.Application.inhibit]. @@ -8804,13 +10335,13 @@ Inhibitors are also cleared when the application exits. the `GtkApplication` + line="1048">the application a cookie that was returned by [method@Gtk.Application.inhibit] + line="1049">a cookie that was returned by [method@Gtk.Application.inhibit] @@ -8818,11 +10349,9 @@ Inhibitors are also cleared when the application exits. - The currently focused window of the application. + line="705">The currently focused window of the application. transfer-ownership="none" setter="set_menubar" getter="get_menubar"> - - The `GMenuModel` to be used for the application's menu bar. + line="695">The menu model to be used for the application's menu bar. default-value="FALSE"> Set this property to `TRUE` to register with the session manager. + line="665">Set this property to true to register with the session manager. This will make GTK track the session state (such as the [property@Gtk.Application:screensaver-active] property). @@ -8856,11 +10381,11 @@ This will make GTK track the session state (such as the default-value="FALSE"> This property is `TRUE` if GTK believes that the screensaver is -currently active. + line="678">This property is true if GTK believes that the screensaver +is currently active. GTK only tracks session state (including this) when -[property@Gtk.Application:register-session] is set to %TRUE. +[property@Gtk.Application:register-session] is set to true. Tracking the screensaver state is currently only supported on Linux. @@ -8872,11 +10397,11 @@ Linux. Emitted when the session manager is about to end the session. + line="647">Emitted when the session manager is about to end the session. This signal is only emitted if [property@Gtk.Application:register-session] -is `TRUE`. Applications can connect to this signal and call -[method@Gtk.Application.inhibit] with `GTK_APPLICATION_INHIBIT_LOGOUT` +is true. Applications can connect to this signal and call +[method@Gtk.Application.inhibit] with [flags@Gtk.ApplicationInhibitFlags.logout] to delay the end of the session until state has been saved. @@ -8885,8 +10410,9 @@ to delay the end of the session until state has been saved. Emitted when a [class@Gtk.Window] is added to `application` through -[method@Gtk.Application.add_window]. + line="614">Emitted when a window is added to an application. + +See [method@Gtk.Application.add_window]. @@ -8894,7 +10420,7 @@ to delay the end of the session until state has been saved. the newly-added [class@Gtk.Window] + line="617">the newly-added window @@ -8902,7 +10428,7 @@ to delay the end of the session until state has been saved. Emitted when a [class@Gtk.Window] is removed from `application`. + line="630">Emitted when a window is removed from an application. This can happen as a side-effect of the window being destroyed or explicitly through [method@Gtk.Application.remove_window]. @@ -8913,7 +10439,7 @@ or explicitly through [method@Gtk.Application.remove_window]. the [class@Gtk.Window] that is being removed + line="633">the window that is being removed @@ -8930,6 +10456,10 @@ or explicitly through [method@Gtk.Application.remove_window]. + Signal emitted when a `GtkWindow` is added to + application through gtk_application_add_window(). @@ -8946,6 +10476,11 @@ or explicitly through [method@Gtk.Application.remove_window]. + Signal emitted when a `GtkWindow` is removed from + application, either as a side-effect of being destroyed or + explicitly through gtk_application_remove_window(). @@ -8973,7 +10508,7 @@ or explicitly through [method@Gtk.Application.remove_window]. c:type="GtkApplicationInhibitFlags"> Types of user actions that may be blocked by `GtkApplication`. + line="976">Types of user actions that may be blocked by `GtkApplication`. See [method@Gtk.Application.inhibit]. glib:name="GTK_APPLICATION_INHIBIT_LOGOUT"> Inhibit ending the user session + line="978">Inhibit ending the user session by logging out or by shutting down the computer glib:name="GTK_APPLICATION_INHIBIT_SWITCH"> Inhibit user switching + line="980">Inhibit user switching glib:name="GTK_APPLICATION_INHIBIT_SUSPEND"> Inhibit suspending the + line="981">Inhibit suspending the session or computer glib:name="GTK_APPLICATION_INHIBIT_IDLE"> Inhibit the session being + line="983">Inhibit the session being marked as idle (and possibly locked) @@ -9025,18 +10560,17 @@ See [method@Gtk.Application.inhibit]. glib:type-struct="ApplicationWindowClass"> `GtkApplicationWindow` is a `GtkWindow` subclass that integrates with -`GtkApplication`. + line="34">A `GtkWindow` subclass that integrates with `GtkApplication`. Notably, `GtkApplicationWindow` can handle an application menubar. -This class implements the `GActionGroup` and `GActionMap` interfaces, -to let you add window-specific actions that will be exported by the -associated [class@Gtk.Application], together with its application-wide +This class implements the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] +interfaces, to let you add window-specific actions that will be exported +by the associated [class@Gtk.Application], together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when -referring to them from a `GMenuModel`. +referring to them from a menu model. Note that widgets that are placed inside a `GtkApplicationWindow` can also activate these actions, if they implement the @@ -9049,13 +10583,12 @@ models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be. -If the desktop environment does not display the menubar, then -`GtkApplicationWindow` will automatically show a menubar for it. -This behaviour can be overridden with the -[property@Gtk.ApplicationWindow:show-menubar] property. If the -desktop environment does not display the application menu, then -it will automatically be included in the menubar or in the windows -client-side decorations. +If the desktop environment does not display the menubar, it can be shown in +the `GtkApplicationWindow` by setting the +[property@Gtk.ApplicationWindow:show-menubar] property to true. If the +desktop environment does not display the application menu, then it will +automatically be included in the menubar or in the window’s client-side +decorations. See [class@Gtk.PopoverMenu] for information about the XML language used by `GtkBuilder` for menu models. @@ -9108,43 +10641,46 @@ GtkWidget *window = gtk_application_window_new (app); Creates a new `GtkApplicationWindow`. + line="706">Creates a new `GtkApplicationWindow`. a newly created `GtkApplicationWindow` + line="712">a newly created `GtkApplicationWindow` a `GtkApplication` + line="708">an application + c:identifier="gtk_application_window_get_help_overlay" + deprecated="1" + deprecated-version="4.18"> Gets the `GtkShortcutsWindow` that is associated with @window. + line="854">Gets the `GtkShortcutsWindow` that is associated with @window. See [method@Gtk.ApplicationWindow.set_help_overlay]. + `GtkShortcutsWindow` will be removed in GTK 5 the help overlay associated - with @window + line="862">the help overlay associated + with the window a `GtkApplicationWindow` + line="856">an application window @@ -9152,22 +10688,22 @@ See [method@Gtk.ApplicationWindow.set_help_overlay]. Returns the unique ID of the window. + line="767">Returns the unique ID of the window. If the window has not yet been added to a `GtkApplication`, returns `0`. the unique ID for @window, or `0` if the window - has not yet been added to a `GtkApplication` + line="775">the unique ID for the window, or `0` if the window + has not yet been added to an application a `GtkApplicationWindow` + line="769">an application window @@ -9175,37 +10711,39 @@ See [method@Gtk.ApplicationWindow.set_help_overlay]. - Returns whether the window will display a menubar for the app menu + line="724">Returns whether the window will display a menubar for the app menu and menubar as needed. %TRUE if @window will display a menubar when needed + line="731">True if the window will display a menubar when needed a `GtkApplicationWindow` + line="726">an application window + c:identifier="gtk_application_window_set_help_overlay" + deprecated="1" + deprecated-version="4.18"> Associates a shortcuts window with the application window. + line="808">Associates a shortcuts window with the application window. Additionally, sets up an action with the name `win.show-help-overlay` to present it. -@window takes responsibility for destroying @help_overlay. +The window takes responsibility for destroying the help overlay. + `GtkShortcutsWindow` will be removed in GTK 5 @@ -9214,7 +10752,7 @@ Additionally, sets up an action with the name a `GtkApplicationWindow` + line="810">an application window a `GtkShortcutsWindow` + line="811">a shortcuts window @@ -9231,10 +10769,9 @@ Additionally, sets up an action with the name - Sets whether the window will display a menubar for the app menu + line="740">Sets whether the window will display a menubar for the app menu and menubar as needed. @@ -9244,13 +10781,13 @@ and menubar as needed. a `GtkApplicationWindow` + line="742">an application window whether to show a menubar when needed + line="743">whether to show a menubar when needed @@ -9262,18 +10799,14 @@ and menubar as needed. setter="set_show_menubar" getter="get_show_menubar" default-value="FALSE"> - - If this property is %TRUE, the window will display a menubar + line="689">If this property is true, the window will display a menubar unless it is shown by the desktop shell. See [method@Gtk.Application.set_menubar]. -If %FALSE, the window will not display a menubar, regardless +If false, the window will not display a menubar, regardless of whether the desktop shell is showing it or not. @@ -9303,7 +10836,7 @@ of whether the desktop shell is showing it or not. c:type="GtkArrowType"> Used to indicate the direction in which an arrow should point. + line="94">Indicates the direction in which an arrow should point. glib:name="GTK_ARROW_UP"> Represents an upward pointing arrow. + line="96">Represents an upward pointing arrow. glib:name="GTK_ARROW_DOWN"> Represents a downward pointing arrow. + line="97">Represents a downward pointing arrow. glib:name="GTK_ARROW_LEFT"> Represents a left pointing arrow. + line="98">Represents a left pointing arrow. glib:name="GTK_ARROW_RIGHT"> Represents a right pointing arrow. + line="99">Represents a right pointing arrow. glib:name="GTK_ARROW_NONE"> No arrow. + line="100">No arrow. glib:get-type="gtk_aspect_frame_get_type"> `GtkAspectFrame` preserves the aspect ratio of its child. + line="30">Preserves the aspect ratio of its child. The frame can respect the aspect ratio of the child widget, or use its own aspect ratio. # CSS nodes -`GtkAspectFrame` uses a CSS node with name `frame`. +`GtkAspectFrame` uses a CSS node with name `aspectframe`. # Accessibility -Until GTK 4.10, `GtkAspectFrame` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkAspectFrame` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkAspectFrame` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkAspectFrame` uses the [enum@Gtk.AccessibleRole.generic] role. Create a new `GtkAspectFrame`. + line="310">Create a new `GtkAspectFrame`. the new `GtkAspectFrame`. + line="322">the new `GtkAspectFrame`. Horizontal alignment of the child within the parent. + line="312">Horizontal alignment of the child within the parent. Ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the parent. + line="314">Vertical alignment of the child within the parent. Ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. + line="316">The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect + line="317">If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. @@ -9419,22 +10952,21 @@ Starting from GTK 4.12, `GtkAspectFrame` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` - Gets the child widget of @self. + line="672">Gets the child widget of @self. the child widget of @self + line="678">the child widget of @self a `GtkAspectFrame` + line="674">a `GtkAspectFrame` @@ -9442,23 +10974,22 @@ Starting from GTK 4.12, `GtkAspectFrame` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` - Returns whether the child's size request should override + line="492">Returns whether the child's size request should override the set aspect ratio of the `GtkAspectFrame`. whether to obey the child's size request + line="499">whether to obey the child's size request a `GtkAspectFrame` + line="494">a `GtkAspectFrame` @@ -9466,22 +10997,21 @@ the set aspect ratio of the `GtkAspectFrame`. - Returns the desired aspect ratio of the child. + line="450">Returns the desired aspect ratio of the child. the desired aspect ratio + line="456">the desired aspect ratio a `GtkAspectFrame` + line="452">a `GtkAspectFrame` @@ -9489,23 +11019,22 @@ the set aspect ratio of the `GtkAspectFrame`. - Returns the horizontal alignment of the child within the + line="367">Returns the horizontal alignment of the child within the allocation of the `GtkAspectFrame`. the horizontal alignment + line="374">the horizontal alignment a `GtkAspectFrame` + line="369">a `GtkAspectFrame` @@ -9513,23 +11042,22 @@ allocation of the `GtkAspectFrame`. - Returns the vertical alignment of the child within the + line="409">Returns the vertical alignment of the child within the allocation of the `GtkAspectFrame`. the vertical alignment + line="416">the vertical alignment a `GtkAspectFrame` + line="411">a `GtkAspectFrame` @@ -9537,10 +11065,9 @@ allocation of the `GtkAspectFrame`. - Sets the child widget of @self. + line="644">Sets the child widget of @self. @@ -9549,7 +11076,7 @@ allocation of the `GtkAspectFrame`. a `GtkAspectFrame` + line="646">a `GtkAspectFrame` allow-none="1"> the child widget + line="647">the child widget @@ -9566,10 +11093,9 @@ allocation of the `GtkAspectFrame`. - Sets whether the aspect ratio of the child's size + line="466">Sets whether the aspect ratio of the child's size request should override the set aspect ratio of the `GtkAspectFrame`. @@ -9580,13 +11106,13 @@ the `GtkAspectFrame`. a `GtkAspectFrame` + line="468">a `GtkAspectFrame` If %TRUE, @ratio is ignored, and the aspect + line="469">If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requisition of the child. @@ -9595,10 +11121,9 @@ the `GtkAspectFrame`. - Sets the desired aspect ratio of the child. + line="426">Sets the desired aspect ratio of the child. @@ -9607,13 +11132,13 @@ the `GtkAspectFrame`. a `GtkAspectFrame` + line="428">a `GtkAspectFrame` aspect ratio of the child + line="429">aspect ratio of the child @@ -9621,10 +11146,9 @@ the `GtkAspectFrame`. - Sets the horizontal alignment of the child within the allocation + line="342">Sets the horizontal alignment of the child within the allocation of the `GtkAspectFrame`. @@ -9634,13 +11158,13 @@ of the `GtkAspectFrame`. a `GtkAspectFrame` + line="344">a `GtkAspectFrame` horizontal alignment, from 0.0 (left aligned) to 1.0 (right aligned) + line="345">horizontal alignment, from 0.0 (left aligned) to 1.0 (right aligned) @@ -9648,10 +11172,9 @@ of the `GtkAspectFrame`. - Sets the vertical alignment of the child within the allocation + line="384">Sets the vertical alignment of the child within the allocation of the `GtkAspectFrame`. @@ -9661,13 +11184,13 @@ of the `GtkAspectFrame`. a `GtkAspectFrame` + line="386">a `GtkAspectFrame` horizontal alignment, from 0.0 (top aligned) to 1.0 (bottom aligned) + line="387">horizontal alignment, from 0.0 (top aligned) to 1.0 (bottom aligned) @@ -9677,13 +11200,9 @@ of the `GtkAspectFrame`. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="186">The child widget. setter="set_obey_child" getter="get_obey_child" default-value="TRUE"> - - Whether the `GtkAspectFrame` should use the aspect ratio of its child. + line="176">Whether the `GtkAspectFrame` should use the aspect ratio of its child. setter="set_ratio" getter="get_ratio" default-value="1.000000"> - - The aspect ratio to be used by the `GtkAspectFrame`. + line="163">The aspect ratio to be used by the `GtkAspectFrame`. This property is only used if [property@Gtk.AspectFrame:obey-child] is set to %FALSE. @@ -9725,13 +11236,9 @@ This property is only used if setter="set_xalign" getter="get_xalign" default-value="0.500000"> - - The horizontal alignment of the child. + line="143">The horizontal alignment of the child. - - The vertical alignment of the child. + line="153">The vertical alignment of the child. @@ -9762,7 +11265,10 @@ This property is only used if filename="gtk/deprecated/gtkassistant.c" line="24">`GtkAssistant` is used to represent a complex as a series of steps. -![An example GtkAssistant](assistant.png) +<picture> + <source srcset="assistant-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkAssistant" src="assistant.png"> +</picture> Each step consists of one or more pages. `GtkAssistant` guides the user through the pages, and controls the page flow to collect the data needed @@ -9809,13 +11315,13 @@ class .assistant. deprecated-version="4.10"> Creates a new `GtkAssistant`. + line="1459">Creates a new `GtkAssistant`. This widget will be removed in GTK 5 - + a newly created `GtkAssistant` + line="1464">a newly created `GtkAssistant` @@ -9825,9 +11331,9 @@ class .assistant. deprecated-version="4.10"> Adds a widget to the action area of a `GtkAssistant`. + line="1901">Adds a widget to the action area of a `GtkAssistant`. This widget will be removed in GTK 5 - + @@ -9835,13 +11341,13 @@ class .assistant. a `GtkAssistant` + line="1903">a `GtkAssistant` a `GtkWidget` + line="1904">a `GtkWidget` @@ -9852,26 +11358,26 @@ class .assistant. deprecated-version="4.10"> Appends a page to the @assistant. + line="1689">Appends a page to the @assistant. This widget will be removed in GTK 5 - + the index (starting at 0) of the inserted page + line="1696">the index (starting at 0) of the inserted page a `GtkAssistant` + line="1691">a `GtkAssistant` a `GtkWidget` + line="1692">a `GtkWidget` @@ -9882,7 +11388,7 @@ class .assistant. deprecated-version="4.10"> Erases the visited page history. + line="2170">Erases the visited page history. GTK will then hide the back button on the current page, and removes the cancel button from subsequent pages. @@ -9893,7 +11399,7 @@ or undone. For example, showing a progress page to track a long-running, unreversible operation after the user has clicked apply on a confirmation page. This widget will be removed in GTK 5 - + @@ -9901,7 +11407,7 @@ clicked apply on a confirmation page. a `GtkAssistant` + line="2172">a `GtkAssistant` @@ -9912,13 +11418,13 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Returns the page number of the current page. + line="1478">Returns the page number of the current page. This widget will be removed in GTK 5 - + The index (starting from 0) of the current + line="1484">The index (starting from 0) of the current page in the @assistant, or -1 if the @assistant has no pages, or no current page @@ -9927,7 +11433,7 @@ clicked apply on a confirmation page. a `GtkAssistant` + line="1480">a `GtkAssistant` @@ -9938,20 +11444,20 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Returns the number of pages in the @assistant + line="1614">Returns the number of pages in the @assistant This widget will be removed in GTK 5 - + the number of pages in the @assistant + line="1620">the number of pages in the @assistant a `GtkAssistant` + line="1616">a `GtkAssistant` @@ -9962,13 +11468,13 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Returns the child widget contained in page number @page_num. + line="1632">Returns the child widget contained in page number @page_num. This widget will be removed in GTK 5 - + the child widget, or %NULL + line="1640">the child widget, or %NULL if @page_num is out of bounds @@ -9976,13 +11482,13 @@ clicked apply on a confirmation page. a `GtkAssistant` + line="1634">a `GtkAssistant` the index of a page in the @assistant, + line="1635">the index of a page in the @assistant, or -1 to get the last page @@ -9994,26 +11500,26 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Returns the `GtkAssistantPage` object for @child. + line="2255">Returns the `GtkAssistantPage` object for @child. This widget will be removed in GTK 5 - + the `GtkAssistantPage` for @child + line="2262">the `GtkAssistantPage` for @child a `GtkAssistant` + line="2257">a `GtkAssistant` a child of @assistant + line="2258">a child of @assistant @@ -10024,26 +11530,26 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Gets whether @page is complete. + line="2116">Gets whether @page is complete. This widget will be removed in GTK 5 - + %TRUE if @page is complete. + line="2123">%TRUE if @page is complete. a `GtkAssistant` + line="2118">a `GtkAssistant` a page of @assistant + line="2119">a page of @assistant @@ -10054,26 +11560,26 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Gets the title for @page. + line="1991">Gets the title for @page. This widget will be removed in GTK 5 - + the title for @page + line="1998">the title for @page a `GtkAssistant` + line="1993">a `GtkAssistant` a page of @assistant + line="1994">a page of @assistant @@ -10084,26 +11590,26 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Gets the page type of @page. + line="2053">Gets the page type of @page. This widget will be removed in GTK 5 - + the page type of @page + line="2060">the page type of @page a `GtkAssistant` + line="2055">a `GtkAssistant` a page of @assistant + line="2056">a page of @assistant @@ -10115,21 +11621,21 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Gets a list model of the assistant pages. + line="2387">Gets a list model of the assistant pages. This widget will be removed in GTK 5 - + A list model of the pages. + line="2393">A list model of the pages. a `GtkAssistant` + line="2389">a `GtkAssistant` @@ -10140,32 +11646,32 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Inserts a page in the @assistant at a given position. + line="1710">Inserts a page in the @assistant at a given position. This widget will be removed in GTK 5 - + the index (starting from 0) of the inserted page + line="1719">the index (starting from 0) of the inserted page a `GtkAssistant` + line="1712">a `GtkAssistant` a `GtkWidget` + line="1713">a `GtkWidget` the index (starting at 0) at which to insert the page, + line="1714">the index (starting at 0) at which to insert the page, or -1 to append the page to the @assistant @@ -10177,7 +11683,7 @@ clicked apply on a confirmation page. deprecated-version="4.10"> Navigate to the next page. + line="1550">Navigate to the next page. It is a programming error to call this function when there is no next page. @@ -10185,7 +11691,7 @@ there is no next page. This function is for use when creating pages of the %GTK_ASSISTANT_PAGE_CUSTOM type. This widget will be removed in GTK 5 - + @@ -10193,7 +11699,7 @@ This function is for use when creating pages of the a `GtkAssistant` + line="1552">a `GtkAssistant` @@ -10204,26 +11710,26 @@ This function is for use when creating pages of the deprecated-version="4.10"> Prepends a page to the @assistant. + line="1668">Prepends a page to the @assistant. This widget will be removed in GTK 5 - + the index (starting at 0) of the inserted page + line="1675">the index (starting at 0) of the inserted page a `GtkAssistant` + line="1670">a `GtkAssistant` a `GtkWidget` + line="1671">a `GtkWidget` @@ -10234,7 +11740,7 @@ This function is for use when creating pages of the deprecated-version="4.10"> Navigate to the previous visited page. + line="1575">Navigate to the previous visited page. It is a programming error to call this function when no previous page is available. @@ -10242,7 +11748,7 @@ no previous page is available. This function is for use when creating pages of the %GTK_ASSISTANT_PAGE_CUSTOM type. This widget will be removed in GTK 5 - + @@ -10250,7 +11756,7 @@ This function is for use when creating pages of the a `GtkAssistant` + line="1577">a `GtkAssistant` @@ -10261,9 +11767,9 @@ This function is for use when creating pages of the deprecated-version="4.10"> Removes a widget from the action area of a `GtkAssistant`. + line="1931">Removes a widget from the action area of a `GtkAssistant`. This widget will be removed in GTK 5 - + @@ -10271,13 +11777,13 @@ This function is for use when creating pages of the a `GtkAssistant` + line="1933">a `GtkAssistant` a `GtkWidget` + line="1934">a `GtkWidget` @@ -10288,9 +11794,9 @@ This function is for use when creating pages of the deprecated-version="4.10"> Removes the @page_num’s page from @assistant. + line="1813">Removes the @page_num’s page from @assistant. This widget will be removed in GTK 5 - + @@ -10298,13 +11804,13 @@ This function is for use when creating pages of the a `GtkAssistant` + line="1815">a `GtkAssistant` the index of a page in the @assistant, + line="1816">the index of a page in the @assistant, or -1 to remove the last page @@ -10316,13 +11822,13 @@ This function is for use when creating pages of the deprecated-version="4.10"> Switches the page to @page_num. + line="1501">Switches the page to @page_num. Note that this will only be necessary in custom buttons, as the @assistant flow can be set with gtk_assistant_set_forward_page_func(). This widget will be removed in GTK 5 - + @@ -10330,13 +11836,13 @@ gtk_assistant_set_forward_page_func(). a `GtkAssistant` + line="1503">a `GtkAssistant` index of the page to switch to, starting from 0. + line="1504">index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the @assistant, nothing will be done. @@ -10350,7 +11856,7 @@ gtk_assistant_set_forward_page_func(). deprecated-version="4.10"> Sets the page forwarding function to be @page_func. + line="1842">Sets the page forwarding function to be @page_func. This function will be used to determine what will be the next page when the user presses the forward button. @@ -10358,7 +11864,7 @@ Setting @page_func to %NULL will make the assistant to use the default forward function, which just goes to the next visible page. This widget will be removed in GTK 5 - + @@ -10366,7 +11872,7 @@ next visible page. a `GtkAssistant` + line="1844">a `GtkAssistant` destroy="2"> the `GtkAssistantPageFunc`, or %NULL + line="1845">the `GtkAssistantPageFunc`, or %NULL to use the default one @@ -10388,13 +11894,13 @@ next visible page. allow-none="1"> user data for @page_func + line="1847">user data for @page_func destroy notifier for @data + line="1848">destroy notifier for @data @@ -10405,12 +11911,12 @@ next visible page. deprecated-version="4.10"> Sets whether @page contents are complete. + line="2083">Sets whether @page contents are complete. This will make @assistant update the buttons state to be able to continue the task. This widget will be removed in GTK 5 - + @@ -10418,19 +11924,19 @@ to be able to continue the task. a `GtkAssistant` + line="2085">a `GtkAssistant` a page of @assistant + line="2086">a page of @assistant the completeness status of the page + line="2087">the completeness status of the page @@ -10441,12 +11947,12 @@ to be able to continue the task. deprecated-version="4.10"> Sets a title for @page. + line="1958">Sets a title for @page. The title is displayed in the header area of the assistant when @page is the current page. This widget will be removed in GTK 5 - + @@ -10454,19 +11960,19 @@ when @page is the current page. a `GtkAssistant` + line="1960">a `GtkAssistant` a page of @assistant + line="1961">a page of @assistant the new title for @page + line="1962">the new title for @page @@ -10477,11 +11983,11 @@ when @page is the current page. deprecated-version="4.10"> Sets the page type for @page. + line="2021">Sets the page type for @page. The page type determines the page behavior in the @assistant. This widget will be removed in GTK 5 - + @@ -10489,19 +11995,19 @@ The page type determines the page behavior in the @assistant. a `GtkAssistant` + line="2023">a `GtkAssistant` a page of @assistant + line="2024">a page of @assistant the new type for @page + line="2025">the new type for @page @@ -10512,7 +12018,7 @@ The page type determines the page behavior in the @assistant. deprecated-version="4.10"> Forces @assistant to recompute the buttons state. + line="2146">Forces @assistant to recompute the buttons state. GTK automatically takes care of this in most situations, e.g. when the user goes to a different page, or when the @@ -10522,7 +12028,7 @@ One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant. This widget will be removed in GTK 5 - + @@ -10530,7 +12036,7 @@ affects the future page flow of the assistant. a `GtkAssistant` + line="2148">a `GtkAssistant` @@ -10538,7 +12044,7 @@ affects the future page flow of the assistant. `GListModel` containing the pages. + line="655">`GListModel` containing the pages. default-value="-1"> %TRUE if the assistant uses a `GtkHeaderBar` for action buttons + line="638">%TRUE if the assistant uses a `GtkHeaderBar` for action buttons instead of the action-area. For technical reasons, this property is declared as an integer @@ -10564,7 +12070,7 @@ property, but you should only set it to %TRUE or %FALSE. deprecated-version="4.10"> Emitted when the apply button is clicked. + line="570">Emitted when the apply button is clicked. The default behavior of the `GtkAssistant` is to switch to the page after the current page, unless the current page is the last one. @@ -10586,7 +12092,7 @@ the progress page. deprecated-version="4.10"> Emitted when then the cancel button is clicked. + line="531">Emitted when then the cancel button is clicked. This widget will be removed in GTK 5 @@ -10598,7 +12104,7 @@ the progress page. deprecated-version="4.10"> Emitted either when the close button of a summary page is clicked, + line="597">Emitted either when the close button of a summary page is clicked, or when the apply button in the last page in the flow (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. This widget will be removed in GTK 5 @@ -10613,7 +12119,7 @@ or when the apply button in the last page in the flow (of type deprecated-version="4.10"> The action signal for the Escape binding. + line="616">The action signal for the Escape binding. This widget will be removed in GTK 5 @@ -10625,7 +12131,7 @@ or when the apply button in the last page in the flow (of type deprecated-version="4.10"> Emitted when a new page is set as the assistant's current page, + line="548">Emitted when a new page is set as the assistant's current page, before making the new page visible. A handler for this signal can do any preparations which are @@ -10638,7 +12144,7 @@ necessary before showing @page. the current page + line="551">the current page @@ -10654,7 +12160,7 @@ necessary before showing @page. glib:get-type="gtk_assistant_page_get_type"> `GtkAssistantPage` is an auxiliary object used by `GtkAssistant. + line="70">`GtkAssistantPage` is an auxiliary object used by `GtkAssistant`. This object will be removed in GTK 5 deprecated-version="4.10"> Returns the child to which @page belongs. + line="2274">Returns the child to which @page belongs. This widget will be removed in GTK 5 - + the child to which @page belongs + line="2280">the child to which @page belongs a `GtkAssistantPage` + line="2276">a `GtkAssistantPage` @@ -10690,7 +12196,7 @@ necessary before showing @page. getter="get_child"> The child widget. + line="324">The child widget. This object will be removed in GTK 5 @@ -10702,7 +12208,7 @@ necessary before showing @page. default-value="FALSE"> Whether all required fields are filled in. + line="308">Whether all required fields are filled in. GTK uses this information to control the sensitivity of the navigation buttons. @@ -10717,7 +12223,7 @@ of the navigation buttons. default-value="GTK_ASSISTANT_PAGE_CONTENT"> The type of the assistant page. + line="281">The type of the assistant page. This object will be removed in GTK 5 @@ -10729,7 +12235,7 @@ of the navigation buttons. default-value="NULL"> The title of the page. + line="295">The title of the page. This object will be removed in GTK 5 @@ -10737,24 +12243,24 @@ of the navigation buttons. Type of callback used to calculate the next page in a `GtkAssistant`. + line="87">Type of callback used to calculate the next page in a `GtkAssistant`. It’s called both for computing the next page when the user presses the “forward” button and for handling the behavior of the “last” button. See [method@Gtk.Assistant.set_forward_page_func]. - + The next page number + line="99">The next page number The page number used to calculate the next page. + line="89">The page number used to calculate the next page. closure="1"> user data. + line="90">user data. Determines the page role inside a `GtkAssistant`. + line="38">Determines the role of a page inside a `GtkAssistant`. The role is used to handle buttons sensitivity and visibility. @@ -10785,6 +12293,7 @@ Note that an assistant needs to end its page flow with a page of type The Cancel button will only be shown if the page isn’t “committed”. See gtk_assistant_commit() for details. + `GtkAssistant` will be removed in GTK 5 add its own buttons through gtk_assistant_add_action_widget(). - + Like [func@get_binary_age], but from the headers used at @@ -11007,7 +12516,7 @@ in a `GtkBuildable` add_child implementation. c:type="GtkBaselinePosition"> Baseline position in a row of widgets. + line="113">Baseline position in a row of widgets. Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If @@ -11022,7 +12531,7 @@ extra available space. glib:name="GTK_BASELINE_POSITION_TOP"> Align the baseline at the top + line="115">Align the baseline at the top glib:name="GTK_BASELINE_POSITION_CENTER"> Center the baseline + line="116">Center the baseline glib:name="GTK_BASELINE_POSITION_BOTTOM"> Align the baseline at the bottom + line="117">Align the baseline at the bottom glib:type-struct="BinLayoutClass"> `GtkBinLayout` is a `GtkLayoutManager` subclass useful for create "bins" of -widgets. + line="18">A layout manager for widgets with a single child. `GtkBinLayout` will stack each child of a widget on top of each other, using the [property@Gtk.Widget:hexpand], [property@Gtk.Widget:vexpand], @@ -11063,12 +12571,12 @@ of each child to determine where they should be positioned. Creates a new `GtkBinLayout` instance. + line="111">Creates a new `GtkBinLayout` instance. the newly created `GtkBinLayout` + line="116">the newly created `GtkBinLayout` @@ -11089,9 +12597,9 @@ of each child to determine where they should be positioned. c:symbol-prefix="bitset"> A `GtkBitset` represents a set of unsigned integers. + line="26">A set of unsigned integers. -Another name for this data structure is "bitmap". +Another name for this data structure is “bitmap”. The current implementation is based on [roaring bitmaps](https://roaringbitmap.org/). @@ -11146,12 +12654,12 @@ The main use case for `GtkBitset` is implementing complex selections for Adds @value to @self if it wasn't part of it before. + line="343">Adds @value to @self if it wasn't part of it before. %TRUE if @value was not part of @self and @self + line="350">%TRUE if @value was not part of @self and @self was changed @@ -11159,13 +12667,13 @@ The main use case for `GtkBitset` is implementing complex selections for a `GtkBitset` + line="345">a `GtkBitset` value to add + line="346">value to add @@ -11173,7 +12681,7 @@ The main use case for `GtkBitset` is implementing complex selections for Adds all values from @start (inclusive) to @start + @n_items + line="381">Adds all values from @start (inclusive) to @start + @n_items (exclusive) in @self. @@ -11183,19 +12691,19 @@ The main use case for `GtkBitset` is implementing complex selections for a `GtkBitset` + line="383">a `GtkBitset` first value to add + line="384">first value to add number of consecutive values to add + line="385">number of consecutive values to add @@ -11204,7 +12712,7 @@ The main use case for `GtkBitset` is implementing complex selections for c:identifier="gtk_bitset_add_range_closed"> Adds the closed range [@first, @last], so @first, @last and all + line="431">Adds the closed range [@first, @last], so @first, @last and all values in between. @first must be smaller than @last. @@ -11214,19 +12722,19 @@ values in between. @first must be smaller than @last. a `GtkBitset` + line="433">a `GtkBitset` first value to add + line="434">first value to add last value to add + line="435">last value to add @@ -11234,7 +12742,7 @@ values in between. @first must be smaller than @last. Interprets the values as a 2-dimensional boolean grid with the given @stride + line="471">Interprets the values as a 2-dimensional boolean grid with the given @stride and inside that grid, adds a rectangle with the given @width and @height. @@ -11244,31 +12752,31 @@ and inside that grid, adds a rectangle with the given @width and @height. a `GtkBitset` + line="473">a `GtkBitset` first value to add + line="474">first value to add width of the rectangle + line="475">width of the rectangle height of the rectangle + line="476">height of the rectangle row stride of the grid + line="477">row stride of the grid @@ -11323,7 +12831,7 @@ and inside that grid, adds a rectangle with the given @width and @height. Sets @self to be the symmetric difference of @self and @other. + line="611">Sets @self to be the symmetric difference of @self and @other. The symmetric difference is set @self to contain all values that were either contained in @self or in @other, but not in both. @@ -11339,13 +12847,13 @@ will be emptied in that case. a `GtkBitset` + line="613">a `GtkBitset` the `GtkBitset` to compute the difference from + line="614">the `GtkBitset` to compute the difference from @@ -11516,7 +13024,7 @@ happen (it can't with `GListModel`), be sure to use a 64bit type. Sets @self to be the intersection of @self and @other. + line="558">Sets @self to be the intersection of @self and @other. In other words, remove all values from @self that are not part of @other. @@ -11530,13 +13038,13 @@ happen in that case. a `GtkBitset` + line="560">a `GtkBitset` the `GtkBitset` to intersect with + line="561">the `GtkBitset` to intersect with @@ -11587,12 +13095,12 @@ happen in that case. Removes @value from @self if it was part of it before. + line="362">Removes @value from @self if it was part of it before. %TRUE if @value was part of @self and @self + line="369">%TRUE if @value was part of @self and @self was changed @@ -11600,13 +13108,13 @@ happen in that case. a `GtkBitset` + line="364">a `GtkBitset` value to remove + line="365">value to remove @@ -11614,7 +13122,7 @@ happen in that case. Removes all values from the bitset so that it is empty again. + line="329">Removes all values from the bitset so that it is empty again. @@ -11623,7 +13131,7 @@ happen in that case. a `GtkBitset` + line="331">a `GtkBitset` @@ -11631,7 +13139,7 @@ happen in that case. Removes all values from @start (inclusive) to @start + @n_items (exclusive) + line="406">Removes all values from @start (inclusive) to @start + @n_items (exclusive) in @self. @@ -11641,19 +13149,19 @@ in @self. a `GtkBitset` + line="408">a `GtkBitset` first value to remove + line="409">first value to remove number of consecutive values to remove + line="410">number of consecutive values to remove @@ -11662,7 +13170,7 @@ in @self. c:identifier="gtk_bitset_remove_range_closed"> Removes the closed range [@first, @last], so @first, @last and all + line="451">Removes the closed range [@first, @last], so @first, @last and all values in between. @first must be smaller than @last. @@ -11672,19 +13180,19 @@ values in between. @first must be smaller than @last. a `GtkBitset` + line="453">a `GtkBitset` first value to remove + line="454">first value to remove last value to remove + line="455">last value to remove @@ -11693,7 +13201,7 @@ values in between. @first must be smaller than @last. c:identifier="gtk_bitset_remove_rectangle"> Interprets the values as a 2-dimensional boolean grid with the given @stride + line="502">Interprets the values as a 2-dimensional boolean grid with the given @stride and inside that grid, removes a rectangle with the given @width and @height. @@ -11703,31 +13211,31 @@ and inside that grid, removes a rectangle with the given @width and @height. a `GtkBitset` + line="504">a `GtkBitset` first value to remove + line="505">first value to remove width of the rectangle + line="506">width of the rectangle height of the rectangle + line="507">height of the rectangle row stride of the grid + line="508">row stride of the grid @@ -11735,7 +13243,7 @@ and inside that grid, removes a rectangle with the given @width and @height. Shifts all values in @self to the left by @amount. + line="641">Shifts all values in @self to the left by @amount. Values smaller than @amount are discarded. @@ -11746,13 +13254,13 @@ Values smaller than @amount are discarded. a `GtkBitset` + line="643">a `GtkBitset` amount to shift all values to the left + line="644">amount to shift all values to the left @@ -11760,7 +13268,7 @@ Values smaller than @amount are discarded. Shifts all values in @self to the right by @amount. + line="677">Shifts all values in @self to the right by @amount. Values that end up too large to be held in a #guint are discarded. @@ -11771,13 +13279,13 @@ Values that end up too large to be held in a #guint are discarded. a `GtkBitset` + line="679">a `GtkBitset` amount to shift all values to the right + line="680">amount to shift all values to the right @@ -11785,7 +13293,7 @@ Values that end up too large to be held in a #guint are discarded. This is a support function for `GListModel` handling, by mirroring + line="713">This is a support function for `GListModel` handling, by mirroring the `GlistModel::items-changed` signal. First, it "cuts" the values from @position to @removed from @@ -11803,25 +13311,25 @@ up space that can then be filled. a `GtkBitset` + line="715">a `GtkBitset` position at which to slice + line="716">position at which to slice number of values to remove + line="717">number of values to remove number of values to add + line="718">number of values to add @@ -11829,7 +13337,7 @@ up space that can then be filled. Sets @self to be the subtraction of @other from @self. + line="583">Sets @self to be the subtraction of @other from @self. In other words, remove all values from @self that are part of @other. @@ -11843,13 +13351,13 @@ will be emptied in that case. a `GtkBitset` + line="585">a `GtkBitset` the `GtkBitset` to subtract + line="586">the `GtkBitset` to subtract @@ -11857,7 +13365,7 @@ will be emptied in that case. Sets @self to be the union of @self and @other. + line="533">Sets @self to be the union of @self and @other. That is, add all values from @other into @self that weren't part of it. @@ -11871,13 +13379,13 @@ happen in that case. a `GtkBitset` + line="535">a `GtkBitset` the `GtkBitset` to union with + line="536">the `GtkBitset` to union with @@ -11913,13 +13421,14 @@ freed. c:symbol-prefix="bitset_iter"> An opaque, stack-allocated struct for iterating -over the elements of a `GtkBitset`. + line="133">Iterates over the elements of a [struct@Gtk.Bitset]. + +`GtkBitSetIter is an opaque, stack-allocated struct. Before a `GtkBitsetIter` can be used, it needs to be initialized with [func@Gtk.BitsetIter.init_first], [func@Gtk.BitsetIter.init_last] or [func@Gtk.BitsetIter.init_at]. - + @@ -11928,22 +13437,22 @@ or [func@Gtk.BitsetIter.init_at]. Gets the current value that @iter points to. + line="946">Gets the current value that @iter points to. If @iter is not valid and [method@Gtk.BitsetIter.is_valid] returns %FALSE, this function returns 0. - + The current value pointer to by @iter + line="955">The current value pointer to by @iter a `GtkBitsetIter` + line="948">a `GtkBitsetIter` @@ -11951,19 +13460,19 @@ returns %FALSE, this function returns 0. Checks if @iter points to a valid value. - + line="970">Checks if @iter points to a valid value. + %TRUE if @iter points to a valid value + line="976">%TRUE if @iter points to a valid value a `GtkBitsetIter` + line="972">a `GtkBitsetIter` @@ -11971,22 +13480,22 @@ returns %FALSE, this function returns 0. Moves @iter to the next value in the set. + line="880">Moves @iter to the next value in the set. If it was already pointing to the last value in the set, %FALSE is returned and @iter is invalidated. - + %TRUE if a next value existed + line="890">%TRUE if a next value existed a pointer to a valid `GtkBitsetIter` + line="882">a pointer to a valid `GtkBitsetIter` Set to the next value + line="883">Set to the next value @@ -12005,22 +13514,22 @@ If it was already pointing to the last value in the set, Moves @iter to the previous value in the set. + line="913">Moves @iter to the previous value in the set. If it was already pointing to the first value in the set, %FALSE is returned and @iter is invalidated. - + %TRUE if a previous value existed + line="923">%TRUE if a previous value existed a pointer to a valid `GtkBitsetIter` + line="915">a pointer to a valid `GtkBitsetIter` Set to the previous value + line="916">Set to the previous value @@ -12039,15 +13548,15 @@ If it was already pointing to the first value in the set, Initializes @iter to point to @target. + line="841">Initializes @iter to point to @target. If @target is not found, finds the next value after it. If no value >= @target exists in @set, this function returns %FALSE. - + %TRUE if a value was found. + line="853">%TRUE if a value was found. @@ -12057,19 +13566,19 @@ If no value >= @target exists in @set, this function returns %FALSE. transfer-ownership="none"> a pointer to an uninitialized `GtkBitsetIter` + line="843">a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` + line="844">a `GtkBitset` target value to start iterating at + line="845">target value to start iterating at allow-none="1"> Set to the found value in @set + line="846">Set to the found value in @set @@ -12088,15 +13597,15 @@ If no value >= @target exists in @set, this function returns %FALSE. Initializes an iterator for @set and points it to the first + line="779">Initializes an iterator for @set and points it to the first value in @set. If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. - + %TRUE if @set isn't empty. + line="790">%TRUE if @set isn't empty. @@ -12106,13 +13615,13 @@ If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. transfer-ownership="none"> a pointer to an uninitialized `GtkBitsetIter` + line="781">a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` + line="782">a `GtkBitset` allow-none="1"> Set to the first value in @set + line="783">Set to the first value in @set @@ -12131,15 +13640,15 @@ If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. Initializes an iterator for @set and points it to the last + line="810">Initializes an iterator for @set and points it to the last value in @set. If @set is empty, %FALSE is returned. - + %TRUE if @set isn't empty. + line="821">%TRUE if @set isn't empty. @@ -12149,13 +13658,13 @@ If @set is empty, %FALSE is returned. transfer-ownership="none"> a pointer to an uninitialized `GtkBitsetIter` + line="812">a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` + line="813">a `GtkBitset` allow-none="1"> Set to the last value in @set + line="814">Set to the last value in @set @@ -12181,7 +13690,7 @@ If @set is empty, %FALSE is returned. glib:type-struct="BookmarkListClass"> `GtkBookmarkList` is a list model that wraps `GBookmarkFile`. + line="27">A list model that wraps `GBookmarkFile`. It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s returned from that function. @@ -12226,7 +13735,6 @@ namespace added: `recent::private` (boolean) and `recent:applications` - Gets the attributes queried on the children. @@ -12249,7 +13757,6 @@ namespace added: `recent::private` (boolean) and `recent:applications` - Returns the filename of the bookmark file that @@ -12273,7 +13780,6 @@ this list is loading. - Gets the IO priority to use while loading file. @@ -12293,8 +13799,9 @@ this list is loading. - - + Returns %TRUE if the files are currently being loaded. @@ -12321,7 +13828,6 @@ in between runs. - Sets the @attributes to be enumerated and starts the enumeration. @@ -12353,7 +13859,6 @@ of `GFileInfo`s will still be created. - Sets the IO priority to use while loading files. @@ -12384,10 +13889,6 @@ The default IO priority is %G_PRIORITY_DEFAULT. setter="set_attributes" getter="get_attributes" default-value="NULL"> - - The attributes to query. @@ -12399,8 +13900,6 @@ The default IO priority is %G_PRIORITY_DEFAULT. transfer-ownership="none" getter="get_filename" default-value="NULL"> - The bookmark file to load. @@ -12412,10 +13911,6 @@ The default IO priority is %G_PRIORITY_DEFAULT. setter="set_io_priority" getter="get_io_priority" default-value="0"> - - Priority used when loading. @@ -12427,9 +13922,10 @@ The default IO priority is %G_PRIORITY_DEFAULT. line="249">The type of items. See [method@Gio.ListModel.get_item_type]. - - + %TRUE if files are being loaded. @@ -12462,18 +13958,17 @@ The default IO priority is %G_PRIORITY_DEFAULT. glib:type-struct="BoolFilterClass"> `GtkBoolFilter` evaluates a boolean `GtkExpression` -to determine whether to include items. + line="26">Evaluates a boolean expression to determine whether to include items. Creates a new bool filter. + line="181">Creates a new bool filter. a new `GtkBoolFilter` + line="187">a new `GtkBoolFilter` @@ -12483,7 +13978,7 @@ to determine whether to include items. allow-none="1"> The expression to evaluate + line="183">the expression to evaluate @@ -12491,23 +13986,22 @@ to determine whether to include items. - Gets the expression that the filter uses to evaluate if -an item should be filtered. + line="203">Gets the expression that the filter evaluates for +each item. a `GtkExpression` + line="210">the expression a `GtkBoolFilter` + line="205">a bool filter @@ -12515,22 +14009,21 @@ an item should be filtered. - Returns whether the filter inverts the expression. + line="249">Returns whether the filter inverts the expression. %TRUE if the filter inverts + line="255">true if the filter inverts a `GtkBoolFilter` + line="251">a bool filter @@ -12538,13 +14031,12 @@ an item should be filtered. - Sets the expression that the filter uses to check if items + line="220">Sets the expression that the filter uses to check if items should be filtered. -The expression must have a value type of %G_TYPE_BOOLEAN. +The expression must have a value type of `G_TYPE_BOOLEAN`. @@ -12553,7 +14045,7 @@ The expression must have a value type of %G_TYPE_BOOLEAN. a `GtkBoolFilter` + line="222">a bool filter allow-none="1"> a `GtkExpression` + line="223">the expression @@ -12570,10 +14062,9 @@ The expression must have a value type of %G_TYPE_BOOLEAN. - Sets whether the filter should invert the expression. + line="265">Sets whether the filter should invert the expression. @@ -12582,13 +14073,13 @@ The expression must have a value type of %G_TYPE_BOOLEAN. a `GtkBoolFilter` + line="267">a bool filter %TRUE to invert + line="268">true to invert @@ -12598,13 +14089,9 @@ The expression must have a value type of %G_TYPE_BOOLEAN. transfer-ownership="none" setter="set_expression" getter="get_expression"> - - The boolean expression to evaluate on item. + line="154">The boolean expression to evaluate on each item. setter="set_invert" getter="get_invert" default-value="FALSE"> - - If the expression result should be inverted. + line="163">If the expression result should be inverted. @@ -12638,9 +14121,9 @@ The expression must have a value type of %G_TYPE_BOOLEAN. c:symbol-prefix="border"> A struct that specifies a border around a rectangular area. + line="40">Specifies a border around a rectangular area. -Each side can have different width. +Each side can have a different width. c:type="GtkBorderStyle"> Describes how the border of a UI element should be rendered. + line="877">Describes how the border of a UI element should be rendered. glib:name="GTK_BORDER_STYLE_NONE"> No visible border + line="879">No visible border glib:name="GTK_BORDER_STYLE_HIDDEN"> Same as %GTK_BORDER_STYLE_NONE + line="880">Same as %GTK_BORDER_STYLE_NONE glib:name="GTK_BORDER_STYLE_SOLID"> A single line segment + line="881">A single line segment glib:name="GTK_BORDER_STYLE_INSET"> Looks as if the content is sunken into the canvas + line="882">Looks as if the content is sunken into the canvas glib:name="GTK_BORDER_STYLE_OUTSET"> Looks as if the content is coming out of the canvas + line="883">Looks as if the content is coming out of the canvas glib:name="GTK_BORDER_STYLE_DOTTED"> A series of round dots + line="884">A series of round dots glib:name="GTK_BORDER_STYLE_DASHED"> A series of square-ended dashes + line="885">A series of square-ended dashes glib:name="GTK_BORDER_STYLE_DOUBLE"> Two parallel lines with some space between them + line="886">Two parallel lines with some space between them glib:name="GTK_BORDER_STYLE_GROOVE"> Looks as if it were carved in the canvas + line="887">Looks as if it were carved in the canvas glib:name="GTK_BORDER_STYLE_RIDGE"> Looks as if it were coming out of the canvas + line="888">Looks as if it were coming out of the canvas glib:type-struct="BoxClass"> The `GtkBox` widget arranges child widgets into a single row or column. + line="25">Arranges child widgets into a single row or column. -![An example GtkBox](box.png) +<picture> + <source srcset="box-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkBox" src="box.png"> +</picture> Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other -dimension, all children are allocated the same size. Of course, the -[property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties -can be used on the children to influence their allocation. +dimension, all children are allocated the same size. The +[property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] +properties can be used on the children to influence their allocation. Use repeated calls to [method@Gtk.Box.append] to pack widgets into a `GtkBox` from start to end. Use [method@Gtk.Box.remove] to remove widgets @@ -12855,9 +14341,9 @@ place in the box. # Accessibility -Until GTK 4.10, `GtkBox` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkBox` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkBox` uses the [enum@Gtk.AccessibleRole.generic] role. @@ -12866,25 +14352,25 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new `GtkBox`. + line="345">Creates a new box. a new `GtkBox`. + line="352">a new `GtkBox`. the box’s orientation + line="347">the box’s orientation the number of pixels to place by default between children + line="348">the number of pixels to place between children @@ -12892,7 +14378,7 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Adds @child as the last child to @box. + line="631">Adds a child at the end. @@ -12901,13 +14387,13 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. a `GtkBox` + line="633">a box the `GtkWidget` to append + line="634">the widget to append @@ -12916,22 +14402,21 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. - Gets the value set by gtk_box_set_baseline_child(). + line="485">Gets the value set by [method@Gtk.Box.set_baseline_child]. the baseline child + line="491">the baseline child a `GtkBox` + line="487">a box @@ -12939,23 +14424,21 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. - Gets the value set by gtk_box_set_baseline_position(). + line="536">Gets the value set by [method@Gtk.Box.set_baseline_position]. the baseline position + line="542">the baseline position a `GtkBox` + line="538">a box @@ -12963,23 +14446,23 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. - Returns whether the box is homogeneous (all children are the -same size). + line="391">Returns whether the box is homogeneous. + +In a homogeneous box all children are the same size. %TRUE if the box is homogeneous. + line="399">true if the box is homogeneous a `GtkBox` + line="393">a box @@ -12987,22 +14470,21 @@ same size). - Gets the value set by gtk_box_set_spacing(). + line="436">Gets the value set by [method@Gtk.Box.set_spacing]. spacing between children + line="442">spacing between children a `GtkBox` + line="438">a box @@ -13011,10 +14493,11 @@ same size). c:identifier="gtk_box_insert_child_after"> Inserts @child in the position after @sibling in the list -of @box children. + line="556">Inserts a child at a specific position. + +The child is added after @sibling in the list of @box children. -If @sibling is %NULL, insert @child at the first position. +If @sibling is `NULL`, the @child is placed at the beginning. @@ -13023,13 +14506,13 @@ If @sibling is %NULL, insert @child at the first position. a `GtkBox` + line="558">a box the `GtkWidget` to insert + line="559">the widget to insert allow-none="1"> the sibling after which to insert @child + line="560">the sibling after which to insert @child @@ -13046,7 +14529,7 @@ If @sibling is %NULL, insert @child at the first position. Adds @child as the first child to @box. + line="649">Adds a child at the beginning. @@ -13055,13 +14538,13 @@ If @sibling is %NULL, insert @child at the first position. a `GtkBox` + line="651">a box the `GtkWidget` to prepend + line="652">the widget to prepend @@ -13069,7 +14552,7 @@ If @sibling is %NULL, insert @child at the first position. Removes a child widget from @box. + line="667">Removes a child widget from the box. The child must have been added before with [method@Gtk.Box.append], [method@Gtk.Box.prepend], or @@ -13082,13 +14565,13 @@ The child must have been added before with a `GtkBox` + line="669">a box the child to remove + line="670">the child to remove @@ -13097,10 +14580,12 @@ The child must have been added before with c:identifier="gtk_box_reorder_child_after"> Moves @child to the position after @sibling in the list + line="593">Moves a child to a different position. + +The child is moved to the position after @sibling in the list of @box children. -If @sibling is %NULL, move @child to the first position. +If @sibling is `NULL`, the child is placed at the beginning. @@ -13109,13 +14594,13 @@ If @sibling is %NULL, move @child to the first position. a `GtkBox` + line="595">a box the `GtkWidget` to move, must be a child of @box + line="596">the widget to move, must be a child of @box allow-none="1"> the sibling to move @child after + line="597">the sibling to move @child after @@ -13133,10 +14618,9 @@ If @sibling is %NULL, move @child to the first position. c:identifier="gtk_box_set_baseline_child" glib:set-property="baseline-child" version="4.12"> - Sets the baseline child of a box. + line="456">Sets the baseline child of a box. This affects only vertical boxes. @@ -13147,13 +14631,13 @@ This affects only vertical boxes. a `GtkBox` + line="458">a box a child, or -1 + line="459">a child position, or -1 @@ -13161,11 +14645,9 @@ This affects only vertical boxes. - Sets the baseline position of a box. + line="507">Sets the baseline position of a box. This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than @@ -13180,13 +14662,13 @@ extra space available. a `GtkBox` + line="509">a box a `GtkBaselinePosition` + line="510">the baseline position @@ -13194,10 +14676,9 @@ extra space available. - Sets whether or not all children of @box are given equal space + line="364">Sets whether or not all children are given equal space in the box. @@ -13207,14 +14688,14 @@ in the box. a `GtkBox` + line="366">a box a boolean value, %TRUE to create equal allotments, - %FALSE for variable allotments + line="367">true to create equal allotments, + false for variable allotments @@ -13222,10 +14703,9 @@ in the box. - Sets the number of pixels to place between children of @box. + line="413">Sets the number of pixels to place between children. @@ -13234,13 +14714,13 @@ in the box. a `GtkBox` + line="415">a box the number of pixels to put between children + line="416">the number of pixels to put between children @@ -13252,13 +14732,11 @@ in the box. setter="set_baseline_child" getter="get_baseline_child" default-value="-1"> - - The child that determines the baseline, in vertical orientation. + line="285">The position of the child that determines the baseline. + +This is only relevant if the box is in vertical orientation. setter="set_baseline_position" getter="get_baseline_position" default-value="GTK_BASELINE_POSITION_CENTER"> - - The position of the baseline aligned widgets if extra space is available. + line="299">How to position baseline-aligned widgets if extra space is available. setter="set_homogeneous" getter="get_homogeneous" default-value="FALSE"> - - Whether the children should all be the same size. + line="275">Whether the children should all be the same size. setter="set_spacing" getter="get_spacing" default-value="0"> - - The amount of space between children. + line="265">The amount of space between children. @@ -13333,8 +14801,7 @@ in the box. glib:type-struct="BoxLayoutClass"> `GtkBoxLayout` is a layout manager that arranges children in a single -row or column. + line="31">Arranges children in a single row or column. Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other dimension @@ -13352,19 +14819,19 @@ you can use the [property@Gtk.BoxLayout:spacing] property. Creates a new `GtkBoxLayout`. + line="1260">Creates a new `GtkBoxLayout`. a new box layout + line="1266">a new box layout the orientation for the new layout + line="1262">the orientation for the new layout @@ -13375,12 +14842,12 @@ you can use the [property@Gtk.BoxLayout:spacing] property. version="4.12"> Gets the value set by gtk_box_layout_set_baseline_child(). + line="1426">Gets the value set by gtk_box_layout_set_baseline_child(). the index of the child that determines the baseline + line="1432">the index of the child that determines the baseline in vertical layout, or -1 @@ -13388,7 +14855,7 @@ you can use the [property@Gtk.BoxLayout:spacing] property. a `GtkBoxLayout` + line="1428">a `GtkBoxLayout` @@ -13396,23 +14863,21 @@ you can use the [property@Gtk.BoxLayout:spacing] property. - Gets the value set by gtk_box_layout_set_baseline_position(). + line="1383">Gets the value set by gtk_box_layout_set_baseline_position(). the baseline position + line="1389">the baseline position a `GtkBoxLayout` + line="1385">a `GtkBoxLayout` @@ -13420,22 +14885,21 @@ you can use the [property@Gtk.BoxLayout:spacing] property. - Returns whether the layout is set to be homogeneous. + line="1300">Returns whether the layout is set to be homogeneous. %TRUE if the layout is homogeneous + line="1306">%TRUE if the layout is homogeneous a `GtkBoxLayout` + line="1302">a `GtkBoxLayout` @@ -13443,22 +14907,21 @@ you can use the [property@Gtk.BoxLayout:spacing] property. - Returns the space that @box_layout puts between children. + line="1338">Returns the space that @box_layout puts between children. the spacing of the layout + line="1344">the spacing of the layout a `GtkBoxLayout` + line="1340">a `GtkBoxLayout` @@ -13467,10 +14930,9 @@ you can use the [property@Gtk.BoxLayout:spacing] property. c:identifier="gtk_box_layout_set_baseline_child" glib:set-property="baseline-child" version="4.12"> - Sets the index of the child that determines the baseline + line="1399">Sets the index of the child that determines the baseline in vertical layout. @@ -13480,13 +14942,13 @@ in vertical layout. a `GtkBoxLayout` + line="1401">a `GtkBoxLayout` the child position, or -1 + line="1402">the child position, or -1 @@ -13494,11 +14956,9 @@ in vertical layout. - Sets the baseline position of a box layout. + line="1354">Sets the baseline position of a box layout. The baseline position affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than @@ -13513,13 +14973,13 @@ space available. a `GtkBoxLayout` + line="1356">a `GtkBoxLayout` a `GtkBaselinePosition` + line="1357">a `GtkBaselinePosition` @@ -13527,10 +14987,9 @@ space available. - Sets whether the box layout will allocate the same + line="1276">Sets whether the box layout will allocate the same size to all children. @@ -13540,13 +14999,13 @@ size to all children. a `GtkBoxLayout` + line="1278">a `GtkBoxLayout` %TRUE to set the box layout as homogeneous + line="1279">%TRUE to set the box layout as homogeneous @@ -13554,10 +15013,9 @@ size to all children. - Sets how much spacing to put between children. + line="1316">Sets how much spacing to put between children. @@ -13566,13 +15024,13 @@ size to all children. a `GtkBoxLayout` + line="1318">a `GtkBoxLayout` the spacing to apply between children + line="1319">the spacing to apply between children @@ -13584,13 +15042,9 @@ size to all children. setter="set_baseline_child" getter="get_baseline_child" default-value="-1"> - - The child that determines the baseline of the box + line="1212">The child that determines the baseline of the box in vertical layout. If the child does baseline positioning, then its baseline @@ -13604,13 +15058,9 @@ the bottom edge of the child is used. setter="set_baseline_position" getter="get_baseline_position" default-value="GTK_BASELINE_POSITION_CENTER"> - - The position of the allocated baseline within the extra space + line="1230">The position of the allocated baseline within the extra space allocated to each child. This property is only relevant for horizontal layouts containing @@ -13623,13 +15073,9 @@ at least one child with a baseline alignment. setter="set_homogeneous" getter="get_homogeneous" default-value="FALSE"> - - Whether the box layout should distribute the available space + line="1189">Whether the box layout should distribute the available space equally among the children. @@ -13639,13 +15085,9 @@ equally among the children. setter="set_spacing" getter="get_spacing" default-value="0"> - - The space to put between the children. + line="1201">The space to put between the children. @@ -13665,26 +15107,25 @@ equally among the children. glib:type-struct="BuildableIface"> `GtkBuildable` allows objects to extend and customize their deserialization -from ui files. + line="19">Allows objects to extend and customize deserialization from ui files. -The interface includes methods for setting names and properties of objects, -parsing custom tags and constructing child objects. +The `GtkBuildable` interface includes methods for setting names and +properties of objects, parsing custom tags and constructing child objects. -The `GtkBuildable` interface is implemented by all widgets and -many of the non-widget objects that are provided by GTK. The -main user of this interface is [class@Gtk.Builder]. There should be -very little need for applications to call any of these functions directly. +It is implemented by all widgets and many of the non-widget objects that are +provided by GTK. The main user of this interface is [class@Gtk.Builder]. +There should be very little need for applications to call any of these +functions directly. An object only needs to implement this interface if it needs to extend the `GtkBuilder` XML format or run any extra routines at deserialization time. - + Adds a child to @buildable. @type is an optional string + line="148">Adds a child to @buildable. @type is an optional string describing how the child should be added. - + @@ -13692,19 +15133,19 @@ describing how the child should be added. a `GtkBuildable` + line="150">a `GtkBuildable` a `GtkBuilder` + line="151">a `GtkBuilder` child to add + line="152">child to add allow-none="1"> kind of child or %NULL + line="153">kind of child or %NULL - + Constructs a child of a buildable that has been + specified as “constructor” in the UI definition. This can be used to + reference a widget created in a `<ui>` tag which is outside + of the normal GtkBuilder UI definition hierarchy. A reference to the + constructed object is returned and becomes owned by the caller. + @@ -13738,9 +15186,9 @@ describing how the child should be added. Similar to gtk_buildable_parser_finished() but is + line="207">Similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. - + @@ -13748,13 +15196,13 @@ called once for each custom tag handled by the @buildable. a `GtkBuildable` + line="209">a `GtkBuildable` a `GtkBuilder` + line="210">a `GtkBuilder` allow-none="1"> child object or %NULL for non-child tags + line="211">child object or %NULL for non-child tags the name of the tag + line="212">the name of the tag allow-none="1"> user data created in custom_tag_start + line="213">user data created in custom_tag_start @@ -13786,9 +15234,9 @@ called once for each custom tag handled by the @buildable. Called at the end of each custom element handled by + line="191">Called at the end of each custom element handled by the buildable. - + @@ -13796,13 +15244,13 @@ the buildable. A `GtkBuildable` + line="193">A `GtkBuildable` `GtkBuilder` used to construct this object + line="194">`GtkBuilder` used to construct this object allow-none="1"> child object or %NULL for non-child tags + line="195">child object or %NULL for non-child tags name of tag + line="196">name of tag allow-none="1"> user data that will be passed in to parser functions + line="197">user data that will be passed in to parser functions @@ -13834,12 +15282,12 @@ the buildable. Called for each unknown element under `<child>`. - + line="170">Called for each unknown element under `<child>`. + %TRUE if an object has a custom implementation, %FALSE + line="182">%TRUE if an object has a custom implementation, %FALSE if it doesn't. @@ -13847,13 +15295,13 @@ the buildable. a `GtkBuildable` + line="172">a `GtkBuildable` a `GtkBuilder` used to construct this object + line="173">a `GtkBuilder` used to construct this object allow-none="1"> child object or %NULL for non-child tags + line="174">child object or %NULL for non-child tags name of tag + line="175">name of tag transfer-ownership="none"> a `GtkBuildableParser` to fill in + line="176">a `GtkBuildableParser` to fill in nullable="1"> return location for user data that will be passed in + line="177">return location for user data that will be passed in to parser functions - + The getter corresponding to @set_id. Implement this + if you implement @set_id. + @@ -13907,37 +15359,43 @@ the buildable. Retrieves the internal child called @childname of the @buildable object. - + line="226">Retrieves the internal child called @childname of the @buildable object. + the internal child of the buildable object + line="234">the internal child of the buildable object a `GtkBuildable` + line="228">a `GtkBuildable` a `GtkBuilder` + line="229">a `GtkBuilder` name of child + line="230">name of child - + Called when a builder finishes the parsing + of a UI definition. It is normally not necessary to implement this, + unless you need to perform special cleanup actions. `GtkWindow` sets + the `GtkWidget:visible` property here. + @@ -13951,7 +15409,14 @@ the buildable. - + Sets a property of a buildable object. + It is normally not necessary to implement this, g_object_set_property() + is used by default. `GtkWindow` implements this to delay showing itself + (i.e. setting the [property@Gtk.Widget:visible] property) until the whole + interface is created. + @@ -13971,7 +15436,13 @@ the buildable. - + Stores the id attribute given in the `GtkBuilder` UI definition. + `GtkWidget` stores the name as object data. Implement this method if your + object has some notion of “ID” and it makes sense to map the XML id + attribute to it. + @@ -13988,22 +15459,22 @@ the buildable. c:identifier="gtk_buildable_get_buildable_id"> Gets the ID of the @buildable object. + line="75">Gets the ID of the @buildable object. `GtkBuilder` sets the name based on the ID attribute of the `<object>` tag used to construct the @buildable. - + the ID of the buildable object + line="84">the ID of the buildable object a `GtkBuildable` + line="77">a `GtkBuildable` @@ -14014,19 +15485,24 @@ of the `<object>` tag used to construct the @buildable. glib:is-gtype-struct-for="Buildable"> The `GtkBuildableIface` interface contains methods that are -necessary to allow `GtkBuilder` to construct an object from + line="92">Contains methods to let `GtkBuilder` construct an object from a `GtkBuilder` UI definition. - + the parent class + line="94">the parent class + Stores the id attribute given in the `GtkBuilder` UI definition. + `GtkWidget` stores the name as object data. Implement this method if your + object has some notion of “ID” and it makes sense to map the XML id + attribute to it. - + @@ -14041,8 +15517,12 @@ a `GtkBuilder` UI definition. + The getter corresponding to @set_id. Implement this + if you implement @set_id. - + @@ -14054,8 +15534,15 @@ a `GtkBuilder` UI definition. + Adds a child. The @type parameter can be used to + differentiate the kind of child. `GtkWidget` implements this + to add event controllers to the widget, `GtkNotebook` uses + the @type to distinguish between page labels (of type "page-label") + and normal children. - + @@ -14063,19 +15550,19 @@ a `GtkBuilder` UI definition. a `GtkBuildable` + line="150">a `GtkBuildable` a `GtkBuilder` + line="151">a `GtkBuilder` child to add + line="152">child to add allow-none="1"> kind of child or %NULL + line="153">kind of child or %NULL + Sets a property of a buildable object. + It is normally not necessary to implement this, g_object_set_property() + is used by default. `GtkWindow` implements this to delay showing itself + (i.e. setting the [property@Gtk.Widget:visible] property) until the whole + interface is created. - + @@ -14113,8 +15607,15 @@ a `GtkBuilder` UI definition. + Constructs a child of a buildable that has been + specified as “constructor” in the UI definition. This can be used to + reference a widget created in a `<ui>` tag which is outside + of the normal GtkBuilder UI definition hierarchy. A reference to the + constructed object is returned and becomes owned by the caller. - + @@ -14132,12 +15633,20 @@ a `GtkBuilder` UI definition. + Implement this if the buildable needs to parse + content below `<child>`. To handle an element, the implementation + must fill in the @parser and @user_data and return %TRUE. + `GtkWidget` implements this to parse accessible attributes specified + in `<accessibility>` elements. + Note that @user_data must be freed in @custom_tag_end or @custom_finished. - + %TRUE if an object has a custom implementation, %FALSE + line="182">%TRUE if an object has a custom implementation, %FALSE if it doesn't. @@ -14145,13 +15654,13 @@ a `GtkBuilder` UI definition. a `GtkBuildable` + line="172">a `GtkBuildable` a `GtkBuilder` used to construct this object + line="173">a `GtkBuilder` used to construct this object allow-none="1"> child object or %NULL for non-child tags + line="174">child object or %NULL for non-child tags name of tag + line="175">name of tag transfer-ownership="none"> a `GtkBuildableParser` to fill in + line="176">a `GtkBuildableParser` to fill in nullable="1"> return location for user data that will be passed in + line="177">return location for user data that will be passed in to parser functions @@ -14193,8 +15702,12 @@ a `GtkBuilder` UI definition. + Called for the end tag of each custom element that is + handled by the buildable (see @custom_tag_start). - + @@ -14202,13 +15715,13 @@ a `GtkBuilder` UI definition. A `GtkBuildable` + line="193">A `GtkBuildable` `GtkBuilder` used to construct this object + line="194">`GtkBuilder` used to construct this object allow-none="1"> child object or %NULL for non-child tags + line="195">child object or %NULL for non-child tags name of tag + line="196">name of tag allow-none="1"> user data that will be passed in to parser functions + line="197">user data that will be passed in to parser functions + Called for each custom tag handled by the buildable + when the builder finishes parsing (see @custom_tag_start) - + @@ -14248,13 +15765,13 @@ a `GtkBuilder` UI definition. a `GtkBuildable` + line="209">a `GtkBuildable` a `GtkBuilder` + line="210">a `GtkBuilder` allow-none="1"> child object or %NULL for non-child tags + line="211">child object or %NULL for non-child tags the name of the tag + line="212">the name of the tag allow-none="1"> user data created in custom_tag_start + line="213">user data created in custom_tag_start + Called when a builder finishes the parsing + of a UI definition. It is normally not necessary to implement this, + unless you need to perform special cleanup actions. `GtkWindow` sets + the `GtkWidget:visible` property here. - + @@ -14301,31 +15824,38 @@ a `GtkBuilder` UI definition. + Returns an internal child of a buildable. + `GtkDialog` implements this to give access to its @vbox, making + it possible to add children to the vbox in a UI definition. + Implement this if the buildable has internal children that may + need to be accessed from a UI definition. - + the internal child of the buildable object + line="234">the internal child of the buildable object a `GtkBuildable` + line="228">a `GtkBuildable` a `GtkBuilder` + line="229">a `GtkBuilder` name of child + line="230">name of child @@ -14338,7 +15868,9 @@ a `GtkBuilder` UI definition. opaque="1"> An opaque context struct for `GtkBuildableParser`. + line="40">Provides context for parsing GtkBuilder UI files. + +`GtkBuildableParseContext` is an opaque struct. @@ -14349,7 +15881,7 @@ a `GtkBuilder` UI definition. If called from the start_element or end_element handlers this will give the element_name as passed to those functions. For the parent elements, see gtk_buildable_parse_context_get_element_stack(). - + - + that line. Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages." - + @@ -14460,7 +15992,7 @@ This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. - + - + @@ -14542,11 +16074,14 @@ has the same kind of API. A sub-parser for `GtkBuildable` implementations. - + line="48">A sub-parser for `GtkBuildable` implementations. + + function called for open elements - + @@ -14575,8 +16110,11 @@ has the same kind of API. + function called for close elements - + @@ -14599,8 +16137,11 @@ has the same kind of API. + function called for character data - + @@ -14626,8 +16167,11 @@ has the same kind of API. + function called on error - + @@ -14664,8 +16208,7 @@ has the same kind of API. glib:type-struct="BuilderClass"> A `GtkBuilder` reads XML descriptions of a user interface and -instantiates the described objects. + line="21">Reads XML descriptions of a user interface and instantiates the described objects. To create a `GtkBuilder` from a user interface description, call [ctor@Gtk.Builder.new_from_file], [ctor@Gtk.Builder.new_from_resource] @@ -14742,9 +16285,7 @@ Objects are defined as children of the `<interface>` element. Objects are described by `<object>` elements, which can contain `<property>` elements to set properties, `<signal>` elements which connect signals to handlers, and `<child>` elements, which describe -child objects (most often widgets inside a container, but also e.g. -actions in an action group, or columns in a tree model). A `<child>` -element contains an `<object>` element which describes the child object. +child objects. Typically, the specific kind of object represented by an `<object>` element is specified by the “class” attribute. If the type has not @@ -14798,15 +16339,20 @@ property types: - booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as true values, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false values) +- string lists (separated by newlines) - enumeration types (can be specified by their full C identifier their short name used when registering the enumeration type, or their integer value) -- flag types (can be specified by their C identifier, short name, integer - value, and optionally combined with “|” for bitwise OR, e.g. - “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase”) -- colors (in a format understood by [method@Gdk.RGBA.parse]) -- `GVariant` (can be specified in the format understood by - [func@GLib.Variant.parse]) -- pixbufs (can be specified as a filename of an image file to load) +- flag types (can be specified by their C identifier or short name, + optionally combined with “|” for bitwise OR, or a single integer value + e.g., “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase” or 520). +- colors (in the format understood by [method@Gdk.RGBA.parse]) +- transforms (in the format understood by [func@Gsk.Transform.parse]) +- Pango attribute lists (in the format understood by [method@Pango.AttrList.to_string]) +- Pango tab arrays (in the format understood by [method@Pango.TabArray.to_string]) +- Pango font descriptions (in the format understood by [func@Pango.FontDescription.from_string]) +- `GVariant` (in the format understood by [func@GLib.Variant.parse]) +- textures (can be specified as an object id, a resource path or a filename of an image file to load relative to the Builder file or the CWD if [method@Gtk.Builder.add_from_string] was used) +- GFile (like textures, can be specified as an object id, a URI or a filename of a file to load relative to the Builder file or the CWD if [method@Gtk.Builder.add_from_string] was used) Objects can be referred to by their name and by default refer to objects declared in the local XML fragment and objects exposed via @@ -14816,6 +16362,53 @@ doesn’t have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property. +### Child objects + +Many widgets have properties for child widgets, such as +[property@Gtk.Expander:child]. In this case, the preferred way to +specify the child widget in a ui file is to simply set the property: + +```xml +<object class="GtkExpander"> + <property name="child"> + <object class="GtkLabel"> + ... + </object> + </property> +</object> +``` + +Generic containers that can contain an arbitrary number of children, +such as [class@Gtk.Box] instead use the `<child>` element. A `<child>` +element contains an `<object>` element which describes the child object. +Most often, child objects are widgets inside a container, but they can +also be, e.g., actions in an action group, or columns in a tree model. + +Any object type that implements the [iface@Gtk.Buildable] interface can +specify how children may be added to it. Since many objects and widgets that +are included with GTK already implement the `GtkBuildable` interface, +typically child objects can be added using the `<child>` element without +having to be concerned about the underlying implementation. + +See the [`GtkWidget` documentation](class.Widget.html#gtkwidget-as-gtkbuildable) +for many examples of using `GtkBuilder` with widgets, including setting +child objects using the `<child>` element. + +A noteworthy special case to the general rule that only objects implementing +`GtkBuildable` may specify how to handle the `<child>` element is that +`GtkBuilder` provides special support for adding objects to a +[class@Gio.ListStore] by using the `<child>` element. For instance: + +```xml +<object class="GListStore"> + <property name="item-type">MyObject</property> + <child> + <object class="MyObject" /> + </child> + ... +</object> +``` + ### Property bindings It is also possible to bind a property value to another object's @@ -14851,6 +16444,11 @@ For instance, in the example below the “label” property of the For more information, see the documentation of the [method@GObject.Object.bind_property] method. +Please note that another way to set up bindings between objects in .ui files +is to use the `GtkExpression` methodology. See the +[`GtkExpression` documentation](class.Expression.html#gtkexpression-in-ui-files) +for more information. + ### Internal children Sometimes it is necessary to refer to widgets which have implicitly @@ -14944,6 +16542,14 @@ Objects can implement the [iface@Gtk.Buildable] interface to add custom elements and attributes to the XML. Typically, any extension will be documented in each type that implements the interface. +## Menus + +In addition to objects with properties that are created with `<object>` and +`<property>` elements, `GtkBuilder` also allows to parse XML menu definitions +as used by [class@Gio.Menu] when exporting menu models over D-Bus, and as +described in the [class@Gtk.PopoverMenu] documentation. Menus can be defined +as toplevel elements, or as property values for properties of type `GMenuModel`. + ## Templates When describing a [class@Gtk.Widget], you can use the `<template>` tag to @@ -14957,7 +16563,7 @@ for details. Creates a new empty builder object. + line="1345">Creates a new empty builder object. This function is only useful if you intend to make multiple calls to [method@Gtk.Builder.add_from_file], [method@Gtk.Builder.add_from_resource] @@ -14967,7 +16573,7 @@ descriptions into a single builder. a new (empty) `GtkBuilder` object + line="1355">a new (empty) `GtkBuilder` object @@ -14975,7 +16581,7 @@ descriptions into a single builder. c:identifier="gtk_builder_new_from_file"> Parses the UI definition in the file @filename. + line="3142">Parses the UI definition in the file @filename. If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse @@ -14984,14 +16590,14 @@ user interface descriptions that are shipped as part of your program. a `GtkBuilder` containing the described interface + line="3152">a `GtkBuilder` containing the described interface filename of user interface description file + line="3144">filename of user interface description file @@ -15000,7 +16606,7 @@ user interface descriptions that are shipped as part of your program. c:identifier="gtk_builder_new_from_resource"> Parses the UI definition at @resource_path. + line="3167">Parses the UI definition at @resource_path. If there is an error locating the resource or parsing the description, then the program will be aborted. @@ -15008,14 +16614,14 @@ description, then the program will be aborted. a `GtkBuilder` containing the described interface + line="3176">a `GtkBuilder` containing the described interface a `GResource` resource path + line="3169">a `GResource` resource path @@ -15024,7 +16630,7 @@ description, then the program will be aborted. c:identifier="gtk_builder_new_from_string"> Parses the UI definition in @string. + line="3191">Parses the UI definition in @string. If @string is %NULL-terminated, then @length should be -1. If @length is not -1, then it is the length of @string. @@ -15036,20 +16642,20 @@ from untrusted sources. a `GtkBuilder` containing the interface described by @string + line="3205">a `GtkBuilder` containing the interface described by @string a user interface (XML) description + line="3193">a user interface (XML) description the length of @string, or -1 + line="3194">the length of @string, or -1 @@ -15059,7 +16665,7 @@ from untrusted sources. throws="1"> Parses a file containing a UI definition and merges it with + line="1363">Parses a file containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call @@ -15081,20 +16687,20 @@ thing to do when an error is detected is to call `g_error()`. %TRUE on success, %FALSE if an error occurred + line="1388">%TRUE on success, %FALSE if an error occurred a `GtkBuilder` + line="1365">a `GtkBuilder` the name of the file to parse + line="1366">the name of the file to parse @@ -15104,7 +16710,7 @@ thing to do when an error is detected is to call `g_error()`. throws="1"> Parses a resource file containing a UI definition + line="1588">Parses a resource file containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call @@ -15123,20 +16729,20 @@ to call g_error(). %TRUE on success, %FALSE if an error occurred + line="1610">%TRUE on success, %FALSE if an error occurred a `GtkBuilder` + line="1590">a `GtkBuilder` the path of the resource file to parse + line="1591">the path of the resource file to parse @@ -15146,7 +16752,7 @@ to call g_error(). throws="1"> Parses a string containing a UI definition and merges it + line="1740">Parses a string containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call @@ -15165,26 +16771,26 @@ to call g_error(). %TRUE on success, %FALSE if an error occurred + line="1763">%TRUE on success, %FALSE if an error occurred a `GtkBuilder` + line="1742">a `GtkBuilder` the string to parse + line="1743">the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) + line="1744">the length of @buffer (may be -1 if @buffer is nul-terminated) @@ -15194,7 +16800,7 @@ to call g_error(). throws="1"> Parses a file containing a UI definition building only the + line="1433">Parses a file containing a UI definition building only the requested objects and merges them with the current contents of @builder. @@ -15209,26 +16815,26 @@ its child (for instance a `GtkTreeView` that depends on its %TRUE on success, %FALSE if an error occurred + line="1452">%TRUE on success, %FALSE if an error occurred a `GtkBuilder` + line="1435">a `GtkBuilder` the name of the file to parse + line="1436">the name of the file to parse nul-terminated array of objects to build + line="1437">nul-terminated array of objects to build @@ -15240,7 +16846,7 @@ its child (for instance a `GtkTreeView` that depends on its throws="1"> Parses a resource file containing a UI definition, building + line="1665">Parses a resource file containing a UI definition, building only the requested objects and merges them with the current contents of @builder. @@ -15255,26 +16861,26 @@ its child (for instance a `GtkTreeView` that depends on its %TRUE on success, %FALSE if an error occurred + line="1684">%TRUE on success, %FALSE if an error occurred a `GtkBuilder` + line="1667">a `GtkBuilder` the path of the resource file to parse + line="1668">the path of the resource file to parse nul-terminated array of objects to build + line="1669">nul-terminated array of objects to build @@ -15286,7 +16892,7 @@ its child (for instance a `GtkTreeView` that depends on its throws="1"> Parses a string containing a UI definition, building only the + line="1798">Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of @builder. @@ -15300,32 +16906,32 @@ its child (for instance a `GtkTreeView` that depends on its %TRUE on success, %FALSE if an error occurred + line="1817">%TRUE on success, %FALSE if an error occurred a `GtkBuilder` + line="1800">a `GtkBuilder` the string to parse + line="1801">the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) + line="1802">the length of @buffer (may be -1 if @buffer is nul-terminated) nul-terminated array of objects to build + line="1803">nul-terminated array of objects to build @@ -15337,7 +16943,7 @@ its child (for instance a `GtkTreeView` that depends on its throws="1"> Creates a closure to invoke the function called @function_name. + line="3107">Creates a closure to invoke the function called @function_name. This is using the create_closure() implementation of @builder's [iface@Gtk.BuilderScope]. @@ -15348,26 +16954,26 @@ will be set. A new closure for invoking @function_name + line="3123">A new closure for invoking @function_name a `GtkBuilder` + line="3109">a `GtkBuilder` name of the function to look up + line="3110">name of the function to look up closure creation flags + line="3111">closure creation flags allow-none="1"> Object to create the closure with + line="3112">Object to create the closure with @@ -15384,7 +16990,7 @@ will be set. Add @object to the @builder object pool so it can be + line="1951">Add @object to the @builder object pool so it can be referenced just like any other object built by builder. Only a single object may be added using @name. However, @@ -15399,19 +17005,19 @@ if an object has already been added with @name. a `GtkBuilder` + line="1953">a `GtkBuilder` the name of the object exposed to the builder + line="1954">the name of the object exposed to the builder the object to expose + line="1955">the object to expose @@ -15421,7 +17027,7 @@ if an object has already been added with @name. throws="1"> Main private entry point for building composite components + line="1508">Main private entry point for building composite components from template XML. Most likely you do not need to call this function in applications as @@ -15430,38 +17036,38 @@ templates are handled by `GtkWidget`. A positive value on success, 0 if an error occurred + line="1523">A positive value on success, 0 if an error occurred a `GtkBuilder` + line="1510">a `GtkBuilder` the object that is being extended + line="1511">the object that is being extended the type that the template is for + line="1512">the type that the template is for the string to parse + line="1513">the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) + line="1514">the length of @buffer (may be -1 if @buffer is nul-terminated) @@ -15469,22 +17075,21 @@ templates are handled by `GtkWidget`. - Gets the current object set via gtk_builder_set_current_object(). + line="1982">Gets the current object set via gtk_builder_set_current_object(). the current object + line="1988">the current object a `GtkBuilder` + line="1984">a `GtkBuilder` @@ -15492,7 +17097,7 @@ templates are handled by `GtkWidget`. Gets the object named @name. + line="1855">Gets the object named @name. Note that this function does not increment the reference count of the returned object. @@ -15500,20 +17105,20 @@ of the returned object. the object named @name + line="1865">the object named @name a `GtkBuilder` + line="1857">a `GtkBuilder` name of object to get + line="1858">name of object to get @@ -15521,7 +17126,7 @@ of the returned object. Gets all objects that have been constructed by @builder. + line="1879">Gets all objects that have been constructed by @builder. Note that this function does not increment the reference counts of the returned objects. @@ -15529,7 +17134,7 @@ counts of the returned objects. a + line="1888">a newly-allocated `GSList` containing all the objects constructed by the `GtkBuilder instance`. It should be freed by g_slist_free() @@ -15541,7 +17146,7 @@ counts of the returned objects. a `GtkBuilder` + line="1881">a `GtkBuilder` @@ -15549,22 +17154,21 @@ counts of the returned objects. - Gets the scope in use that was set via gtk_builder_set_scope(). + line="2030">Gets the scope in use that was set via gtk_builder_set_scope(). the current scope + line="2036">the current scope a `GtkBuilder` + line="2032">a `GtkBuilder` @@ -15572,23 +17176,21 @@ counts of the returned objects. - Gets the translation domain of @builder. + line="1933">Gets the translation domain of @builder. the translation domain + line="1939">the translation domain a `GtkBuilder` + line="1935">a `GtkBuilder` @@ -15597,7 +17199,7 @@ counts of the returned objects. c:identifier="gtk_builder_get_type_from_name"> Looks up a type by name. + line="3003">Looks up a type by name. This is using the virtual function that `GtkBuilder` has for that purpose. This is mainly used when implementing @@ -15606,7 +17208,7 @@ the `GtkBuildable` interface on a type. the `GType` found for @type_name or %G_TYPE_INVALID + line="3014">the `GType` found for @type_name or %G_TYPE_INVALID if no type was found @@ -15614,13 +17216,13 @@ the `GtkBuildable` interface on a type. a `GtkBuilder` + line="3005">a `GtkBuilder` type name to lookup + line="3006">type name to lookup @@ -15628,10 +17230,9 @@ the `GtkBuildable` interface on a type. - Sets the current object for the @builder. + line="2000">Sets the current object for the @builder. The current object can be thought of as the `this` object that the builder is working for and will often be used as the default object @@ -15648,7 +17249,7 @@ object to the widget the template is inited for. For functions like a `GtkBuilder` + line="2002">a `GtkBuilder` the new current object + line="2003">the new current object @@ -15665,10 +17266,9 @@ object to the widget the template is inited for. For functions like - Sets the scope the builder should operate in. + line="2048">Sets the scope the builder should operate in. If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. @@ -15679,7 +17279,7 @@ If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. a `GtkBuilder` + line="2050">a `GtkBuilder` allow-none="1"> the scope to use + line="2051">the scope to use @@ -15696,11 +17296,9 @@ If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. - Sets the translation domain of @builder. + line="1910">Sets the translation domain of @builder. @@ -15709,7 +17307,7 @@ If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. a `GtkBuilder` + line="1912">a `GtkBuilder` allow-none="1"> the translation domain + line="1913">the translation domain @@ -15728,7 +17326,7 @@ If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. throws="1"> Demarshals a value from a string. + line="2154">Demarshals a value from a string. This function calls g_value_init() on the @value argument, so it need not be initialised beforehand. @@ -15743,26 +17341,26 @@ assigned a `GError` from the %GTK_BUILDER_ERROR domain. %TRUE on success + line="2174">%TRUE on success a `GtkBuilder` + line="2156">a `GtkBuilder` the `GParamSpec` for the property + line="2157">the `GParamSpec` for the property the string representation of the value + line="2158">the string representation of the value transfer-ownership="none"> the `GValue` to store the result in + line="2159">the `GValue` to store the result in @@ -15781,7 +17379,7 @@ assigned a `GError` from the %GTK_BUILDER_ERROR domain. throws="1"> Demarshals a value from a string. + line="2280">Demarshals a value from a string. Unlike [method@Gtk.Builder.value_from_string], this function takes a `GType` instead of `GParamSpec`. @@ -15795,26 +17393,26 @@ assigned a `GError` from the %GTK_BUILDER_ERROR domain. %TRUE on success + line="2299">%TRUE on success a `GtkBuilder` + line="2282">a `GtkBuilder` the `GType` of the value + line="2283">the `GType` of the value the string representation of the value + line="2284">the string representation of the value transfer-ownership="none"> the `GValue` to store the result in + line="2285">the `GValue` to store the result in @@ -15833,13 +17431,9 @@ assigned a `GError` from the %GTK_BUILDER_ERROR domain. transfer-ownership="none" setter="set_current_object" getter="get_current_object"> - - The object the builder is evaluating for. + line="480">The object the builder is evaluating for. transfer-ownership="none" setter="set_scope" getter="get_scope"> - - The scope the builder is operating in + line="490">The scope the builder is operating in setter="set_translation_domain" getter="get_translation_domain" default-value="NULL"> - - The translation domain used when translating property values that + line="466">The translation domain used when translating property values that have been marked as translatable. If the translation domain is %NULL, `GtkBuilder` uses gettext(), @@ -15884,7 +17472,7 @@ otherwise g_dgettext(). glib:type-struct="BuilderCScopeClass"> A `GtkBuilderScope` implementation for the C language. + line="49">A `GtkBuilderScope` implementation for the C language. `GtkBuilderCScope` instances use symbols explicitly added to @builder with prior calls to [method@Gtk.BuilderCScope.add_callback_symbol]. @@ -15905,7 +17493,7 @@ this functionality will require that `GModule` be supported on the platform. Creates a new `GtkBuilderCScope` object to use with future + line="417">Creates a new `GtkBuilderCScope` object to use with future `GtkBuilder` instances. Calling this function is only necessary if you want to add @@ -15914,7 +17502,7 @@ custom callbacks via [method@Gtk.BuilderCScope.add_callback_symbol]. a new `GtkBuilderCScope` + line="426">a new `GtkBuilderCScope` @@ -15922,7 +17510,7 @@ custom callbacks via [method@Gtk.BuilderCScope.add_callback_symbol]. c:identifier="gtk_builder_cscope_add_callback_symbol"> Adds the @callback_symbol to the scope of @builder under the + line="446">Adds the @callback_symbol to the scope of @builder under the given @callback_name. Using this function overrides the behavior of @@ -15938,13 +17526,13 @@ namespace. a `GtkBuilderCScope` + line="448">a `GtkBuilderCScope` The name of the callback, as expected in the XML + line="449">The name of the callback, as expected in the XML scope="async"> The callback pointer + line="450">The callback pointer @@ -15962,7 +17550,7 @@ namespace. introspectable="0"> A convenience function to add many callbacks. + line="479">A convenience function to add many callbacks. This is equivalent to calling [method@Gtk.BuilderCScope.add_callback_symbol] for each symbol. @@ -15974,13 +17562,13 @@ for each symbol. a `GtkBuilderCScope` + line="481">a `GtkBuilderCScope` The name of the callback, as expected in the XML + line="482">The name of the callback, as expected in the XML scope="async"> The callback pointer + line="483">The callback pointer A list of callback name and callback symbol pairs terminated with %NULL + line="484">A list of callback name and callback symbol pairs terminated with %NULL @@ -16004,13 +17592,13 @@ for each symbol. introspectable="0"> Fetches a symbol previously added with + line="524">Fetches a symbol previously added with gtk_builder_cscope_add_callback_symbol(). The callback symbol + line="532">The callback symbol in @builder for @callback_name @@ -16018,13 +17606,13 @@ gtk_builder_cscope_add_callback_symbol(). a `GtkBuilderCScope` + line="526">a `GtkBuilderCScope` The name of the callback + line="527">The name of the callback @@ -16227,7 +17815,13 @@ when they encounter one. `gmodule-export-2.0` pkgconfig module can fix this problem. + Registers an error quark for [class@Gtk.Builder] errors. + the error quark @@ -16241,11 +17835,15 @@ when they encounter one. glib:type-struct="BuilderListItemFactoryClass"> `GtkBuilderListItemFactory` is a `GtkListItemFactory` that creates -widgets by instantiating `GtkBuilder` UI templates. + line="29">A `GtkListItemFactory` that creates widgets by instantiating `GtkBuilder` +UI templates. + +The templates must extend the class that the parent widget expects. +For example, a factory provided to [property@Gtk.ListView:factory] must have +a template that extends [class@Gtk.ListItem]. -The templates must be extending `GtkListItem`, and typically use -`GtkExpression`s to obtain data from the items in the model. +Templates typically use `GtkExpression`s to obtain data from the items +in the model. Example: ```xml @@ -16269,13 +17867,13 @@ Example: c:identifier="gtk_builder_list_item_factory_new_from_bytes"> Creates a new `GtkBuilderListItemFactory` that instantiates widgets + line="305">Creates a new `GtkBuilderListItemFactory` that instantiates widgets using @bytes as the data to pass to `GtkBuilder`. a new `GtkBuilderListItemFactory` + line="313">a new `GtkBuilderListItemFactory` @@ -16285,13 +17883,13 @@ using @bytes as the data to pass to `GtkBuilder`. allow-none="1"> A scope to use when instantiating + line="307">A scope to use when instantiating the `GBytes` containing the ui file to instantiate + line="308">the `GBytes` containing the ui file to instantiate @@ -16300,13 +17898,13 @@ using @bytes as the data to pass to `GtkBuilder`. c:identifier="gtk_builder_list_item_factory_new_from_resource"> Creates a new `GtkBuilderListItemFactory` that instantiates widgets + line="327">Creates a new `GtkBuilderListItemFactory` that instantiates widgets using data read from the given @resource_path to pass to `GtkBuilder`. a new `GtkBuilderListItemFactory` + line="335">a new `GtkBuilderListItemFactory` @@ -16316,13 +17914,13 @@ using data read from the given @resource_path to pass to `GtkBuilder`. allow-none="1"> A scope to use when instantiating + line="329">A scope to use when instantiating valid path to a resource that contains the data + line="330">valid path to a resource that contains the data @@ -16330,23 +17928,22 @@ using data read from the given @resource_path to pass to `GtkBuilder`. - Gets the data used as the `GtkBuilder` UI template for constructing + line="350">Gets the data used as the `GtkBuilder` UI template for constructing listitems. The `GtkBuilder` data + line="357">The `GtkBuilder` data a `GtkBuilderListItemFactory` + line="352">a `GtkBuilderListItemFactory` @@ -16355,22 +17952,21 @@ listitems. - If the data references a resource, gets the path of that resource. + line="367">If the data references a resource, gets the path of that resource. The path to the resource + line="373">The path to the resource a `GtkBuilderListItemFactory` + line="369">a `GtkBuilderListItemFactory` @@ -16379,22 +17975,21 @@ listitems. - Gets the scope used when constructing listitems. + line="383">Gets the scope used when constructing listitems. The scope used when constructing listitems + line="389">The scope used when constructing listitems a `GtkBuilderListItemFactory` + line="385">a `GtkBuilderListItemFactory` @@ -16405,11 +18000,9 @@ listitems. construct-only="1" transfer-ownership="none" getter="get_bytes"> - `GBytes` containing the UI definition. + line="267">`GBytes` containing the UI definition. transfer-ownership="none" getter="get_resource" default-value="NULL"> - Path of the resource containing the UI definition. + line="277">Path of the resource containing the UI definition. construct-only="1" transfer-ownership="none" getter="get_scope"> - `GtkBuilderScope` to use when instantiating listitems + line="287">`GtkBuilderScope` to use when instantiating listitems @@ -16453,8 +18042,7 @@ listitems. glib:type-struct="BuilderScopeInterface"> `GtkBuilderScope` is an interface to provide language binding support -to `GtkBuilder`. + line="27">Provides language binding support to `GtkBuilder`. The goal of `GtkBuilderScope` is to look up programming-language-specific values for strings that are given in a `GtkBuilder` UI file. @@ -16473,6 +18061,13 @@ may want to (partially) derive from or fall back to a [class@Gtk.BuilderCScope], as that class implements support for automatic lookups from C symbols. + Create a closure with the given arguments. See gtk_builder_create_closure() + for more details on those. + The C implementation will try to use dlsym() to locate the function name and then + g_cclosure_new() to create a closure for the symbol. + The default implementation just fails and returns %NULL. @@ -16496,6 +18091,13 @@ as that class implements support for automatic lookups from C symbols. + Try to lookup a `GType` via the given function name, specified + explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag. + This function is very rarely used. + The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`. + The default implementation will fail and just return %G_TYPE_INVALID. @@ -16513,6 +18115,13 @@ as that class implements support for automatic lookups from C symbols. + Try to lookup a `GType` via the its name. See + gtk_builder_get_type_from_name() for more details. + The C implementation will use g_type_from_name() and if that fails try to guess the + correct function name for registering the type and then use dlsym() to load it. + The default implementation just tries g_type_from_name() and otherwise fails. @@ -16543,6 +18152,13 @@ so it is suggested that implementations implement all of them. + Try to lookup a `GType` via the its name. See + gtk_builder_get_type_from_name() for more details. + The C implementation will use g_type_from_name() and if that fails try to guess the + correct function name for registering the type and then use dlsym() to load it. + The default implementation just tries g_type_from_name() and otherwise fails. @@ -16562,6 +18178,13 @@ so it is suggested that implementations implement all of them. + Try to lookup a `GType` via the given function name, specified + explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag. + This function is very rarely used. + The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`. + The default implementation will fail and just return %G_TYPE_INVALID. @@ -16581,6 +18204,13 @@ so it is suggested that implementations implement all of them. + Create a closure with the given arguments. See gtk_builder_create_closure() + for more details on those. + The C implementation will try to use dlsym() to locate the function name and then + g_cclosure_new() to create a closure for the symbol. + The default implementation just fails and returns %NULL. @@ -16616,15 +18246,23 @@ so it is suggested that implementations implement all of them. glib:type-struct="ButtonClass"> The `GtkButton` widget is generally used to trigger a callback function that is -called when the button is pressed. + line="25">Calls a callback function when the button is clicked. -![An example GtkButton](button.png) +<picture> + <source srcset="button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkButton" src="button.png"> +</picture> The `GtkButton` widget can hold any valid child widget. That is, it can hold almost any other standard `GtkWidget`. The most commonly used child is the `GtkLabel`. +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.Button::activate] + # CSS nodes `GtkButton` has a single CSS node with name button. The node will get the @@ -16645,7 +18283,7 @@ or [class@Gtk.FontButton] use style classes such as .toggle, .popup, .scale, # Accessibility -`GtkButton` uses the %GTK_ACCESSIBLE_ROLE_BUTTON role. +`GtkButton` uses the [enum@Gtk.AccessibleRole.button] role. @@ -16654,14 +18292,14 @@ or [class@Gtk.FontButton] use style classes such as .toggle, .popup, .scale, Creates a new `GtkButton` widget. + line="652">Creates a new `GtkButton` widget. To add a child widget to the button, use [method@Gtk.Button.set_child]. The newly created `GtkButton` widget. + line="659">The newly created `GtkButton` widget. @@ -16669,7 +18307,7 @@ To add a child widget to the button, use [method@Gtk.Button.set_child]. c:identifier="gtk_button_new_from_icon_name"> Creates a new button containing an icon from the current icon theme. + line="681">Creates a new button containing an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon @@ -16678,14 +18316,14 @@ will be updated appropriately. a new `GtkButton` displaying the themed icon + line="691">a new `GtkButton` displaying the themed icon an icon name + line="683">an icon name @@ -16694,19 +18332,19 @@ will be updated appropriately. c:identifier="gtk_button_new_with_label"> Creates a `GtkButton` widget with a `GtkLabel` child. + line="667">Creates a `GtkButton` widget with a `GtkLabel` child. The newly created `GtkButton` widget + line="673">The newly created `GtkButton` widget The text you want the `GtkLabel` to hold + line="669">The text you want the `GtkLabel` to hold @@ -16715,7 +18353,7 @@ will be updated appropriately. c:identifier="gtk_button_new_with_mnemonic"> Creates a new `GtkButton` containing a label. + line="705">Creates a new `GtkButton` containing a label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two @@ -16726,20 +18364,25 @@ activates the button. a new `GtkButton` + line="718">a new `GtkButton` The text of the button, with an underscore in front of the + line="707">The text of the button, with an underscore in front of the mnemonic character + Signal that causes the button to animate press then + release. Applications should never connect to this signal, but use + the @clicked signal. @@ -16751,6 +18394,9 @@ activates the button. + Signal emitted when the button has been activated (pressed and released). @@ -16767,20 +18413,20 @@ activates the button. version="4.12"> Retrieves whether the button can be smaller than the natural + line="1165">Retrieves whether the button can be smaller than the natural size of its contents. true if the button can shrink, and false otherwise + line="1172">true if the button can shrink, and false otherwise a button + line="1167">a button @@ -16788,22 +18434,21 @@ size of its contents. - Gets the child widget of @button. + line="1098">Gets the child widget of @button. the child widget of @button + line="1104">the child widget of @button a `GtkButton` + line="1100">a `GtkButton` @@ -16811,22 +18456,21 @@ size of its contents. - Returns whether the button has a frame. + line="753">Returns whether the button has a frame. %TRUE if the button has a frame + line="759">%TRUE if the button has a frame a `GtkButton` + line="755">a `GtkButton` @@ -16834,10 +18478,9 @@ size of its contents. - Returns the icon name of the button. + line="1021">Returns the icon name of the button. If the icon name has not been set with [method@Gtk.Button.set_icon_name] the return value will be %NULL. This will be the case if you create @@ -16846,14 +18489,14 @@ an empty button with [ctor@Gtk.Button.new] to use as a container. The icon name set via [method@Gtk.Button.set_icon_name] + line="1031">The icon name set via [method@Gtk.Button.set_icon_name] A `GtkButton` + line="1023">A `GtkButton` @@ -16861,10 +18504,9 @@ an empty button with [ctor@Gtk.Button.new] to use as a container. - Fetches the text from the label of the button. + line="894">Fetches the text from the label of the button. If the label text has not been set with [method@Gtk.Button.set_label] the return value will be %NULL. This will be the case if you create @@ -16873,7 +18515,7 @@ an empty button with [ctor@Gtk.Button.new] to use as a container. The text of the label widget. This string is owned + line="904">The text of the label widget. This string is owned by the widget and must not be modified or freed. @@ -16881,7 +18523,7 @@ by the widget and must not be modified or freed. a `GtkButton` + line="896">a `GtkButton` @@ -16889,17 +18531,16 @@ by the widget and must not be modified or freed. - gets whether underlines are interpreted as mnemonics. + line="953">gets whether underlines are interpreted as mnemonics. See [method@Gtk.Button.set_use_underline]. %TRUE if an embedded underline in the button label + line="961">%TRUE if an embedded underline in the button label indicates the mnemonic accelerator keys. @@ -16907,7 +18548,7 @@ See [method@Gtk.Button.set_use_underline]. a `GtkButton` + line="955">a `GtkButton` @@ -16918,7 +18559,7 @@ See [method@Gtk.Button.set_use_underline]. version="4.12"> Sets whether the button size can be smaller than the natural size of + line="1116">Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting @can_shrink to true will ellipsize the label. @@ -16932,13 +18573,13 @@ For icons and custom children, this function has no effect. a button + line="1118">a button whether the button can shrink + line="1119">whether the button can shrink @@ -16946,10 +18587,9 @@ For icons and custom children, this function has no effect. - Sets the child widget of @button. + line="1062">Sets the child widget of @button. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for @button. @@ -16964,7 +18604,7 @@ relations from @child to @button. a `GtkButton` + line="1064">a `GtkButton` allow-none="1"> the child widget + line="1065">the child widget @@ -16981,10 +18621,9 @@ relations from @child to @button. - Sets the style of the button. + line="726">Sets the style of the button. Buttons can have a flat appearance or have a frame drawn around them. @@ -16995,13 +18634,13 @@ Buttons can have a flat appearance or have a frame drawn around them. a `GtkButton` + line="728">a `GtkButton` whether the button should have a visible frame + line="729">whether the button should have a visible frame @@ -17009,10 +18648,9 @@ Buttons can have a flat appearance or have a frame drawn around them. - Adds a `GtkImage` with the given icon name as a child. + line="984">Adds a `GtkImage` with the given icon name as a child. If @button already contains a child widget, that child widget will be removed and replaced with the image. @@ -17024,13 +18662,13 @@ be removed and replaced with the image. A `GtkButton` + line="986">A `GtkButton` An icon name + line="987">An icon name @@ -17038,10 +18676,9 @@ be removed and replaced with the image. - Sets the text of the label of the button to @label. + line="849">Sets the text of the label of the button to @label. This will also clear any previously set labels. @@ -17052,13 +18689,13 @@ This will also clear any previously set labels. a `GtkButton` + line="851">a `GtkButton` a string + line="852">a string @@ -17066,10 +18703,9 @@ This will also clear any previously set labels. - Sets whether to use underlines as mnemonics. + line="920">Sets whether to use underlines as mnemonics. If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key. @@ -17081,13 +18717,13 @@ the next character should be used for the mnemonic accelerator key. a `GtkButton` + line="922">a `GtkButton` %TRUE if underlines in the text indicate mnemonics + line="923">%TRUE if underlines in the text indicate mnemonics @@ -17101,7 +18737,7 @@ the next character should be used for the mnemonic accelerator key. default-value="FALSE"> Whether the size of the button can be made smaller than the natural + line="274">Whether the size of the button can be made smaller than the natural size of its contents. For text buttons, setting this property will allow ellipsizing the label. @@ -17115,11 +18751,9 @@ property has no effect. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="264">The child widget. setter="set_has_frame" getter="get_has_frame" default-value="TRUE"> - - Whether the button has a frame. + line="244">Whether the button has a frame. setter="set_icon_name" getter="get_icon_name" default-value="NULL"> - - The name of the icon used to automatically populate the button. + line="254">The name of the icon used to automatically populate the button. setter="set_label" getter="get_label" default-value="NULL"> - - Text of the label inside the button, if the button contains a label widget. + line="223">Text of the label inside the button, if the button contains a label widget. setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - If set, an underline in the text indicates that the following character is + line="233">If set, an underline in the text indicates that the following character is to be used as mnemonic. @@ -17187,7 +18807,7 @@ to be used as mnemonic. Emitted to animate press then release. + line="312">Emitted to animate press then release. This is an action signal. Applications should never connect to this signal, but use the [signal@Gtk.Button::clicked] signal. @@ -17201,7 +18821,7 @@ The default bindings for this signal are all forms of the Emitted when the button has been activated (pressed and released). + line="297">Emitted when the button has been activated (pressed and released). @@ -17218,6 +18838,9 @@ The default bindings for this signal are all forms of the + Signal emitted when the button has been activated (pressed and released). @@ -17231,6 +18854,11 @@ The default bindings for this signal are all forms of the + Signal that causes the button to animate press then + release. Applications should never connect to this signal, but use + the @clicked signal. @@ -17268,7 +18896,7 @@ If none of these choices are appropriate, simply use > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO > and %GTK_BUTTONS_OK_CANCEL are discouraged by the -> [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/). +> [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/). A variant of `GtkClosureExpression` using a C closure. + line="1748">A variant of `GtkClosureExpression` using a C closure. Creates a `GtkExpression` that calls `callback_func` when it is evaluated. + line="1774">Creates a `GtkExpression` that calls `callback_func` when it is evaluated. This function is a variant of [ctor@Gtk.ClosureExpression.new] that creates a `GClosure` by calling g_cclosure_new() with the given @@ -17355,14 +18983,14 @@ creates a `GClosure` by calling g_cclosure_new() with the given a new `GtkExpression` + line="1790">a new `GtkExpression` the type of the value that this expression evaluates to + line="1776">the type of the value that this expression evaluates to marshaller used for creating a closure + line="1777">marshaller used for creating a closure the number of params needed for evaluating @closure + line="1778">the number of params needed for evaluating @closure expressions for each parameter + line="1779">expressions for each parameter @@ -17396,7 +19024,7 @@ creates a `GClosure` by calling g_cclosure_new() with the given destroy="6"> callback used for creating a closure + line="1780">callback used for creating a closure user data used for creating a closure + line="1781">user data used for creating a closure destroy notify for @user_data + line="1782">destroy notify for @user_data @@ -17745,7 +19373,7 @@ properties in set_cell_property() and get_cell_property() implementations. introspectable="0"> Returns %TRUE if the version of the GTK header files + line="81">Returns true if the version of the GTK header files is the same as or newer than the passed-in version. @@ -17920,10 +19548,12 @@ is the same as or newer than the passed-in version. glib:get-type="gtk_calendar_get_type"> `GtkCalendar` is a widget that displays a Gregorian calendar, one month -at a time. + line="28">Displays a Gregorian calendar, one month at a time. -![An example GtkCalendar](calendar.png) +<picture> + <source srcset="calendar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkCalendar" src="calendar.png"> +</picture> A `GtkCalendar` can be created with [ctor@Gtk.Calendar.new]. @@ -17943,6 +19573,13 @@ legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect. +# Shortcuts and Gestures + +`GtkCalendar` supports the following gestures: + +- Scrolling up or down will switch to the previous or next month. +- Date strings can be dropped for setting the current day. + # CSS nodes ``` @@ -17975,19 +19612,19 @@ Marked day labels get the :selected state assigned. Creates a new calendar, with the current date being selected. + line="1532">Creates a new calendar, with the current date being selected. a newly `GtkCalendar` widget + line="1537">a newly `GtkCalendar` widget Remove all visual markers. + line="1562">Remove all visual markers. @@ -17996,7 +19633,7 @@ Marked day labels get the :selected state assigned. a `GtkCalendar` + line="1564">a `GtkCalendar` @@ -18004,22 +19641,45 @@ Marked day labels get the :selected state assigned. Returns a `GDateTime` representing the shown + line="1678">Returns a `GDateTime` representing the shown year, month and the selected day. The returned date is in the local time zone. - + the `GDate` representing the shown date + line="1687">the `GDateTime` representing the shown date a `GtkCalendar` + line="1680">a `GtkCalendar` + + + + + + Gets the day of the selected date. + + + the day of the selected date. + + + + + a `GtkCalendar` @@ -18028,36 +19688,58 @@ The returned date is in the local time zone. c:identifier="gtk_calendar_get_day_is_marked"> Returns if the @day of the @calendar is already marked. - + line="1635">Returns if the @day of the @calendar is already marked. + whether the day is marked. + line="1642">whether the day is marked. a `GtkCalendar` + line="1637">a `GtkCalendar` the day number between 1 and 31. + line="1638">the day number between 1 and 31. + + Gets the month of the selected date. + + + The month of the selected date (as a number between 0 and 11). + + + + + a `GtkCalendar` + + + + - Returns whether @self is currently showing the names + line="1814">Returns whether @self is currently showing the names of the week days. This is the value of the [property@Gtk.Calendar:show-day-names] @@ -18066,14 +19748,14 @@ property. Whether the calendar shows day names. + line="1824">Whether the calendar shows day names. a `GtkCalendar` + line="1816">a `GtkCalendar` @@ -18081,10 +19763,9 @@ property. - Returns whether @self is currently showing the heading. + line="1769">Returns whether @self is currently showing the heading. This is the value of the [property@Gtk.Calendar:show-heading] property. @@ -18092,14 +19773,14 @@ property. Whether the calendar is showing a heading. + line="1778">Whether the calendar is showing a heading. a `GtkCalendar` + line="1771">a `GtkCalendar` @@ -18107,11 +19788,9 @@ property. - Returns whether @self is showing week numbers right + line="1723">Returns whether @self is showing week numbers right now. This is the value of the [property@Gtk.Calendar:show-week-numbers] @@ -18120,14 +19799,37 @@ property. Whether the calendar is showing week numbers. + line="1733">Whether the calendar is showing week numbers. a `GtkCalendar` + line="1725">a `GtkCalendar` + + + + + + Gets the year of the selected date. + + + the year of the selected date. + + + + + a `GtkCalendar` @@ -18135,7 +19837,7 @@ property. Places a visual marker on a particular day of the current month. + line="1613">Places a visual marker on a particular day of the current month. @@ -18144,13 +19846,13 @@ property. a `GtkCalendar` + line="1615">a `GtkCalendar` the day number to mark between 1 and 31. + line="1616">the day number to mark between 1 and 31. @@ -18158,7 +19860,7 @@ property. Switches to @date's year and month and select its day. + line="1545">Switches to @date's year and month and select its day. @@ -18167,24 +19869,81 @@ property. a `GtkCalendar`. + line="1547">a `GtkCalendar`. a `GDateTime` representing the day to select + line="1548">a `GDateTime` representing the day to select + + Sets the day for the selected date. + +The new date must be valid. For example, setting 31 for the day when the +month is February, fails. + + + + + + + a `GtkCalendar` + + + + The desired day for the selected date (as a number between 1 and 31). + + + + + + Sets the month for the selected date. + +The new date must be valid. For example, setting 1 (February) for the month +when the day is 31, fails. + + + + + + + a `GtkCalendar` + + + + The desired month for the selected date (as a number between 0 and 11). + + + + - Sets whether the calendar shows day names. + line="1788">Sets whether the calendar shows day names. @@ -18193,13 +19952,13 @@ property. a `GtkCalendar` + line="1790">a `GtkCalendar` Whether to show day names above the day numbers + line="1791">Whether to show day names above the day numbers @@ -18207,10 +19966,9 @@ property. - Sets whether the calendar should show a heading. + line="1743">Sets whether the calendar should show a heading. The heading contains the current year and month as well as buttons for changing both. @@ -18222,13 +19980,13 @@ buttons for changing both. a `GtkCalendar` + line="1745">a `GtkCalendar` Whether to show the heading in the calendar + line="1746">Whether to show the heading in the calendar @@ -18236,11 +19994,9 @@ buttons for changing both. - Sets whether week numbers are shown in the calendar. + line="1697">Sets whether week numbers are shown in the calendar. @@ -18249,21 +20005,51 @@ buttons for changing both. a `GtkCalendar` + line="1699">a `GtkCalendar` whether to show week numbers on the left of the days + line="1700">whether to show week numbers on the left of the days + + Sets the year for the selected date. + +The new date must be valid. For example, setting 2023 for the year when then +the date is 2024-02-29, fails. + + + + + + + a `GtkCalendar` + + + + The desired year for the selected date (within [struct@GLib.DateTime] + limits, i.e. from 0001 to 9999). + + + + Removes the visual marker from a particular day. + line="1656">Removes the visual marker from a particular day. @@ -18272,13 +20058,13 @@ buttons for changing both. a `GtkCalendar`. + line="1658">a `GtkCalendar`. the day number to unmark between 1 and 31. + line="1659">the day number to unmark between 1 and 31. @@ -18286,19 +20072,23 @@ buttons for changing both. The selected day (as a number between 1 and 31). + line="408">The selected day (as a number between 1 and 31). The selected month (as a number between 0 and 11). + line="395">The selected month (as a number between 0 and 11). This property gets initially set to the current month. @@ -18309,13 +20099,9 @@ This property gets initially set to the current month. setter="set_show_day_names" getter="get_show_day_names" default-value="TRUE"> - - Determines whether day names are displayed. + line="430">Determines whether day names are displayed. setter="set_show_heading" getter="get_show_heading" default-value="TRUE"> - - Determines whether a heading is displayed. + line="419">Determines whether a heading is displayed. setter="set_show_week_numbers" getter="get_show_week_numbers" default-value="FALSE"> - - Determines whether week numbers are displayed. + line="440">Determines whether week numbers are displayed. The selected year. + line="382">The selected year. This property gets initially set to the current year. @@ -18362,7 +20142,7 @@ This property gets initially set to the current year. Emitted when the user selects a day. + line="451">Emitted when the user selects a day. @@ -18370,7 +20150,7 @@ This property gets initially set to the current year. Emitted when the user switched to the next month. + line="481">Emitted when the user switched to the next month. @@ -18378,7 +20158,7 @@ This property gets initially set to the current year. Emitted when user switched to the next year. + line="511">Emitted when user switched to the next year. @@ -18386,7 +20166,7 @@ This property gets initially set to the current year. Emitted when the user switched to the previous month. + line="466">Emitted when the user switched to the previous month. @@ -18394,7 +20174,7 @@ This property gets initially set to the current year. Emitted when user switched to the previous year. + line="496">Emitted when user switched to the previous year. @@ -18409,52 +20189,45 @@ This property gets initially set to the current year. glib:type-struct="CallbackActionClass"> A `GtkShortcutAction` that invokes a callback. + line="92">Invokes a callback. Create a custom action that calls the given @callback when + line="406">Create a custom action that calls the given @callback when activated. A new shortcut action + line="416">A new shortcut action the callback to call + line="408">the callback + to call when the action is activated + allow-none="1"> the data to be passed to @callback + line="410">the data to be passed to @callback - + the function to be called when the - callback action is finalized + line="411">the function to be called when the callback action is finalized @@ -18737,8 +20510,8 @@ normal widget and then passing them to the [method@Gtk.CellArea.event] API as they come in. Usually `GtkCellArea` is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can -trigger the [`signal@Gtk.CellArea::focus-changed`] signal to fire; as well -as [`signal@Gtk.CellArea::add-editable`] in the case that an editable cell +trigger the [signal@Gtk.CellArea::focus-changed] signal to fire; as well +as [signal@Gtk.CellArea::add-editable] in the case that an editable cell was clicked and needs to start editing. You can call [method@Gtk.CellArea.stop_editing] at any time to cancel any cell editing that is currently in progress. @@ -19225,6 +20998,10 @@ allocated rectangle inside @cell_area. + This should be implemented to report the values of + child cell properties for a given child `GtkCellRenderer`. @@ -19585,6 +21362,11 @@ after applying new attributes to @area. + This should be implemented to handle changes in child + cell properties for a given `GtkCellRenderer` that were previously + installed on the `GtkCellAreaClass` with gtk_cell_area_class_install_cell_property(). @@ -21879,6 +23661,9 @@ more than its natural size c:type="GInitiallyUnownedClass"/> + adds a `GtkCellRenderer` to the area. @@ -21901,6 +23686,9 @@ more than its natural size + removes a `GtkCellRenderer` from the area. @@ -21923,6 +23711,10 @@ more than its natural size + calls the `GtkCellCallback` function on every `GtkCellRenderer` in + the area with the provided user data until the callback returns %TRUE. @@ -21957,6 +23749,11 @@ more than its natural size + Calls the `GtkCellAllocCallback` function on every + `GtkCellRenderer` in the area with the allocated area for the cell + and the provided user data until the callback returns %TRUE. @@ -22015,6 +23812,11 @@ more than its natural size + Handle an event in the area, this is generally used to activate + a cell at the event location for button events but can also be used + to generically pass events to `GtkWidget`s drawn onto the area. @@ -22064,6 +23866,11 @@ more than its natural size + Actually snapshot the area’s cells to the specified rectangle, + @background_area should be correctly distributed to the cells + corresponding background areas. @@ -22122,6 +23929,11 @@ more than its natural size + Apply the cell attributes to the cells. This is + implemented as a signal and generally `GtkCellArea` subclasses don't + need to implement it since it is handled by the base class. @@ -22163,6 +23975,11 @@ more than its natural size + Creates and returns a class specific `GtkCellAreaContext` + to store cell alignment and allocation details for a said `GtkCellArea` + class. @@ -22182,6 +23999,10 @@ more than its natural size + Creates a new `GtkCellAreaContext` in the same state as + the passed @context with any cell alignment data and allocations intact. @@ -22207,6 +24028,11 @@ more than its natural size + This allows an area to tell its layouting widget whether + it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or + %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. @@ -22226,6 +24052,14 @@ more than its natural size + Calculates the minimum and natural width of the + areas cells with the current attributes applied while considering + the particular layouting details of the said `GtkCellArea`. While + requests are performed over a series of rows, alignments and overall + minimum and natural sizes should be stored in the corresponding + `GtkCellAreaContext`. @@ -22276,6 +24110,16 @@ more than its natural size + Calculates the minimum and natural height + for the area if the passed @context would be allocated the given width. + When implementing this virtual method it is safe to assume that @context + has already stored the aligned cell widths for every `GtkTreeModel` row + that @context will be allocated for since this information was stored + at `GtkCellAreaClass.get_preferred_width()` time. This virtual method + should also store any necessary alignments of cell heights for the + case that the context is allocated a height. @@ -22332,6 +24176,12 @@ more than its natural size + Calculates the minimum and natural height of the + areas cells with the current attributes applied. Essentially this is + the same as `GtkCellAreaClass.get_preferred_width()` only for areas + that are being requested as %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. @@ -22382,6 +24232,13 @@ more than its natural size + Calculates the minimum and natural width + for the area if the passed @context would be allocated the given + height. The same as `GtkCellAreaClass.get_preferred_height_for_width()` + only for handling requests in the %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT + mode. @@ -22438,6 +24295,11 @@ more than its natural size + This should be implemented to handle changes in child + cell properties for a given `GtkCellRenderer` that were previously + installed on the `GtkCellAreaClass` with gtk_cell_area_class_install_cell_property(). @@ -22463,6 +24325,10 @@ more than its natural size + This should be implemented to report the values of + child cell properties for a given child `GtkCellRenderer`. @@ -22488,6 +24354,16 @@ more than its natural size + This virtual method should be implemented to navigate focus from + cell to cell inside the `GtkCellArea`. The `GtkCellArea` should move + focus from cell to cell inside the area and return %FALSE if focus + logically leaves the area with the following exceptions: When the + area contains no activatable cells, the entire area receives focus. + Focus should not be given to cells that are actually “focus siblings” + of other sibling cells (see gtk_cell_area_get_focus_from_sibling()). + Focus is set by calling gtk_cell_area_set_focus_cell(). @@ -22513,6 +24389,13 @@ more than its natural size + Returns whether the `GtkCellArea` can respond to + `GtkCellAreaClass.activate()`, usually this does not need to be + implemented since the base class takes care of this however it can + be enhanced if the `GtkCellArea` subclass can handle activation in + other ways than activating its `GtkCellRenderers`. @@ -22532,6 +24415,10 @@ more than its natural size + This is called when the layouting widget rendering the + `GtkCellArea` activates the focus cell (see gtk_cell_area_get_focus_cell()). @@ -23439,6 +25326,12 @@ for using gtk_cell_area_get_preferred_width(). + This tells the context that an allocation width or height + (or both) have been decided for a group of rows. The context should + store any allocations for internally aligned cells at this point so + that they dont need to be recalculated at gtk_cell_area_render() time. @@ -23470,6 +25363,10 @@ for using gtk_cell_area_get_preferred_width(). + Clear any previously stored information about requested and + allocated sizes for the context. @@ -23487,6 +25384,10 @@ for using gtk_cell_area_get_preferred_width(). + Returns the aligned height for the given + width that context must store while collecting sizes for it’s rows. @@ -23532,6 +25433,10 @@ for using gtk_cell_area_get_preferred_width(). + Returns the aligned width for the given + height that context must store while collecting sizes for it’s rows. @@ -23853,6 +25758,10 @@ for emitting `GtkCellEditable::remove-widget`. + Signal is a sign for the cell renderer to update its + value from the cell_editable. @@ -23870,6 +25779,10 @@ for emitting `GtkCellEditable::remove-widget`. + Signal is meant to indicate that the cell is + finished editing, and the widget may now be destroyed. @@ -23887,6 +25800,9 @@ for emitting `GtkCellEditable::remove-widget`. + Begins editing on a cell_editable. @@ -24752,6 +26668,9 @@ as appropriate. + Packs the cell into the beginning of cell_layout. @@ -24781,6 +26700,9 @@ as appropriate. + Adds the cell to the end of cell_layout. @@ -24810,6 +26732,10 @@ as appropriate. + Unsets all the mappings on all renderers on cell_layout and + removes all renderers from cell_layout. @@ -24827,6 +26753,10 @@ as appropriate. + Adds an attribute mapping to the list in + cell_layout. @@ -24862,6 +26792,10 @@ as appropriate. + Sets the `GtkCellLayout`DataFunc to use for + cell_layout. @@ -24912,6 +26846,10 @@ as appropriate. + Clears all existing attributes previously set + with gtk_cell_layout_set_attributes(). @@ -24935,6 +26873,9 @@ as appropriate. + Re-inserts cell at position. @@ -24964,6 +26905,10 @@ as appropriate. + Get the cell renderers which have been added to + cell_layout. @@ -24989,6 +26934,11 @@ as appropriate. + Get the underlying `GtkCellArea` which might be + cell_layout if called on a `GtkCellArea` or might be NULL if no + `GtkCellArea` is used by cell_layout. @@ -25125,6 +27075,9 @@ toggles when it gets a mouse click. + Signal gets emitted when the user cancels the process of editing a cell. @@ -25137,6 +27090,9 @@ toggles when it gets a mouse click. + Signal gets emitted when a cell starts to be edited. @@ -26851,7 +28807,7 @@ in the same way as they are in menus. + default-value="GDK_NO_MODIFIER_MASK"> The modifier mask of the accelerator. @@ -26907,7 +28863,7 @@ configuration should assign keyvals to all keys. the new acclerator modifier mask + line="232">the new accelerator modifier mask @@ -26954,6 +28910,10 @@ configuration should assign keyvals to all keys. c:type="GInitiallyUnownedClass"/> + Called to gets whether the cell renderer prefers + a height-for-width layout or a width-for-height layout. @@ -26974,6 +28934,9 @@ configuration should assign keyvals to all keys. + Called to get a renderer’s natural width. @@ -27019,6 +28982,9 @@ configuration should assign keyvals to all keys. + Called to get a renderer’s natural height for width. @@ -27070,6 +29036,9 @@ configuration should assign keyvals to all keys. + Called to get a renderer’s natural height. @@ -27115,6 +29084,9 @@ configuration should assign keyvals to all keys. + Called to get a renderer’s natural width for height. @@ -27166,6 +29138,9 @@ configuration should assign keyvals to all keys. + Called to get the aligned area used by @cell inside @cell_area. @@ -27211,6 +29186,9 @@ configuration should assign keyvals to all keys. + Called to snapshot the content of the `GtkCellRenderer`. @@ -27259,6 +29237,9 @@ configuration should assign keyvals to all keys. + Called to activate the content of the `GtkCellRenderer`. @@ -27316,6 +29297,9 @@ configuration should assign keyvals to all keys. + Called to initiate editing the content of the `GtkCellRenderer`. @@ -27377,6 +29361,9 @@ configuration should assign keyvals to all keys. + Signal gets emitted when the user cancels the process of editing a cell. @@ -27391,6 +29378,9 @@ configuration should assign keyvals to all keys. + Signal gets emitted when a cell starts to be edited. @@ -27607,7 +29597,7 @@ pixbuf, it renders that one. deprecated-version="4.10"> Creates a new `GtkCellRendererPixbuf`. Adjust rendering + line="405">Creates a new `GtkCellRendererPixbuf`. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you @@ -27619,7 +29609,7 @@ in the model, thus rendering a different image in each row of the the new cell renderer + line="416">the new cell renderer @@ -27699,13 +29689,13 @@ Additionally, it can display a text on top of the progress bar. deprecated-version="4.10"> Creates a new `GtkCellRendererProgress`. + line="724">Creates a new `GtkCellRendererProgress`. the new cell renderer + line="729">the new cell renderer @@ -27713,6 +29703,9 @@ Additionally, it can display a text on top of the progress bar. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether progess is inverted. deprecated-version="4.10"> Returns a new cell renderer which will show a spinner to indicate + line="225">Returns a new cell renderer which will show a spinner to indicate activity. a new `GtkCellRenderer` + line="231">a new `GtkCellRenderer` @@ -27890,6 +29883,9 @@ activity. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the spinner is active (ie. shown) in the cell default-value="0"> Pulse of the spinner. Increment this value to draw the next frame of the + line="189">Pulse of the spinner. Increment this value to draw the next frame of the spinner animation. Usually, you would update this value in a timeout. By default, the `GtkSpinner` widget draws one full cycle of the animation, @@ -27911,7 +29907,7 @@ consisting of 12 frames, in 750 milliseconds. default-value="GTK_ICON_SIZE_INHERIT"> The `GtkIconSize` value that specifies the size of the rendered spinner. + line="204">The `GtkIconSize` value that specifies the size of the rendered spinner. @@ -29196,10 +31192,13 @@ since 2.10 glib:type-struct="CenterBoxClass"> `GtkCenterBox` arranges three children in a row, keeping the middle child + line="21">Arranges three children in a row, keeping the middle child centered as well as possible. -![An example GtkCenterBox](centerbox.png) +<picture> + <source srcset="centerbox-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkCenterBox" src="centerbox.png"> +</picture> To add children to `GtkCenterBox`, use [method@Gtk.CenterBox.set_start_widget], [method@Gtk.CenterBox.set_center_widget] and @@ -29227,9 +31226,10 @@ bottom. # Accessibility -Until GTK 4.10, `GtkCenterBox` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkCenterBox` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkCenterBox` uses the [enum@Gtk.AccessibleRole.generic] +role. @@ -29238,35 +31238,35 @@ Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` ro Creates a new `GtkCenterBox`. + line="353">Creates a new `GtkCenterBox`. the new `GtkCenterBox`. + line="358">the new `GtkCenterBox` - Gets the value set by gtk_center_box_set_baseline_position(). + line="542">Gets the baseline position of the center box. + +See [method@Gtk.CenterBox.set_baseline_position]. the baseline position + line="550">the baseline position a `GtkCenterBox` + line="544">a center box @@ -29276,19 +31276,19 @@ Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` ro glib:get-property="center-widget"> Gets the center widget, or %NULL if there is none. + line="482">Gets the center widget. the center widget. + line="488">the center widget a `GtkCenterBox` + line="484">a center box @@ -29298,19 +31298,19 @@ Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` ro glib:get-property="end-widget"> Gets the end widget, or %NULL if there is none. + line="496">Gets the end widget. the end widget. + line="502">the end widget a `GtkCenterBox` + line="498">a center box @@ -29319,23 +31319,21 @@ Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` ro c:identifier="gtk_center_box_get_shrink_center_last" glib:get-property="shrink-center-last" version="4.12"> - Gets whether @self shrinks the center widget after other children. + line="601">Gets whether the center widget shrinks after other children. whether to shrink the center widget after others + line="607">whether to shrink the center widget after others a `GtkCenterBox` + line="603">a center box @@ -29345,19 +31343,19 @@ Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` ro glib:get-property="start-widget"> Gets the start widget, or %NULL if there is none. + line="468">Gets the start widget. the start widget. + line="474">the start widget a `GtkCenterBox` + line="470">a center box @@ -29365,17 +31363,15 @@ Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` ro - Sets the baseline position of a center box. + line="510">Sets the baseline position of a center box. This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then -@position is used to allocate the baseline wrt. the extra space -available. +@position is used to allocate the baseline with respect to the +extra space available. @@ -29384,13 +31380,13 @@ available. a `GtkCenterBox` + line="512">a center box a `GtkBaselinePosition` + line="513">the baseline position @@ -29400,9 +31396,9 @@ available. glib:set-property="center-widget"> Sets the center widget. + line="400">Sets the center widget. -To remove the existing center widget, pass %NULL. +To remove the existing center widget, pass `NULL`. @@ -29411,7 +31407,7 @@ To remove the existing center widget, pass %NULL. a `GtkCenterBox` + line="402">a center box allow-none="1"> the new center widget + line="403">the new center widget @@ -29430,9 +31426,9 @@ To remove the existing center widget, pass %NULL. glib:set-property="end-widget"> Sets the end widget. + line="434">Sets the end widget. -To remove the existing end widget, pass %NULL. +To remove the existing end widget, pass `NULL`. @@ -29441,7 +31437,7 @@ To remove the existing end widget, pass %NULL. a `GtkCenterBox` + line="436">a center box allow-none="1"> the new end widget + line="437">the new end widget @@ -29459,18 +31455,16 @@ To remove the existing end widget, pass %NULL. c:identifier="gtk_center_box_set_shrink_center_last" glib:set-property="shrink-center-last" version="4.12"> - Sets whether to shrink the center widget after other children. + line="564">Sets whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. -If set to `FALSE`, start and end widgets keep natural width and the -center widget starts shrinking instead. +If @shrink_center_last is false, start and end widgets keep natural +width and the center widget starts shrinking instead. @@ -29479,13 +31473,13 @@ center widget starts shrinking instead. a `GtkCenterBox` + line="566">a cener box whether to shrink the center widget after others + line="567">whether to shrink the center widget after others @@ -29495,9 +31489,9 @@ center widget starts shrinking instead. glib:set-property="start-widget"> Sets the start widget. + line="366">Sets the start widget. -To remove the existing start widget, pass %NULL. +To remove the existing start widget, pass `NULL`. @@ -29506,7 +31500,7 @@ To remove the existing start widget, pass %NULL. a `GtkCenterBox` + line="368">a center box allow-none="1"> the new start widget + line="369">the new start widget @@ -29526,13 +31520,9 @@ To remove the existing start widget, pass %NULL. setter="set_baseline_position" getter="get_baseline_position" default-value="GTK_BASELINE_POSITION_CENTER"> - - The position of the baseline aligned widget if extra space is available. + line="264">The position of the baseline aligned widget if extra space is available. transfer-ownership="none" setter="set_center_widget" getter="get_center_widget"> - - The widget that is placed at the center position. + line="291">The widget that is placed at the center position. transfer-ownership="none" setter="set_end_widget" getter="get_end_widget"> - - The widget that is placed at the end position. + line="303">The widget that is placed at the end position. In vertical orientation, the end position is at the bottom. In horizontal orientation, the end position is at the trailing -edge wrt. to the text direction. +edge with respect to the text direction. setter="set_shrink_center_last" getter="get_shrink_center_last" default-value="TRUE"> - - Whether to shrink the center widget after other children. + line="319">Whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. -If set to `FALSE`, start and end widgets keep natural width and the +If false, start and end widgets keep natural width and the center widget starts shrinking instead. @@ -29598,17 +31576,13 @@ center widget starts shrinking instead. transfer-ownership="none" setter="set_start_widget" getter="get_start_widget"> - - The widget that is placed at the start position. + line="275">The widget that is placed at the start position. In vertical orientation, the start position is at the top. In horizontal orientation, the start position is at the leading -edge wrt. to the text direction. +edge with respect to the text direction. @@ -29628,7 +31602,7 @@ edge wrt. to the text direction. glib:type-struct="CenterLayoutClass"> `GtkCenterLayout` is a layout manager that manages up to three children. + line="28">Manages up to three children. The start widget is allocated at the start of the layout (left in left-to-right locales and right in right-to-left ones), and the end @@ -29736,8 +31710,6 @@ The center widget is centered regarding the full width of the layout's. c:identifier="gtk_center_layout_get_shrink_center_last" glib:get-property="shrink-center-last" version="4.12"> - Gets whether @self shrinks the center widget after other children. @@ -29888,8 +31860,6 @@ To remove the existing center widget, pass %NULL. c:identifier="gtk_center_layout_set_shrink_center_last" glib:set-property="shrink-center-last" version="4.12"> - Sets whether to shrink the center widget after other children. @@ -29955,10 +31925,6 @@ To remove the existing start widget, pass %NULL. setter="set_shrink_center_last" getter="get_shrink_center_last" default-value="TRUE"> - - Whether to shrink the center widget after other children. @@ -29989,9 +31955,12 @@ center widget starts shrinking instead. glib:type-struct="CheckButtonClass"> A `GtkCheckButton` places a label next to an indicator. + line="40">Places a label next to an indicator. -![Example GtkCheckButtons](check-button.png) +<picture> + <source srcset="check-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Example GtkCheckButtons" src="check-button.png"> +</picture> A `GtkCheckButton` is created by calling either [ctor@Gtk.CheckButton.new] or [ctor@Gtk.CheckButton.new_with_label]. @@ -30020,7 +31989,10 @@ another one will switch the currently toggled one off. Grouped check buttons use a different indicator, and are commonly referred to as *radio buttons*. -![Example GtkCheckButtons](radio-button.png) +<picture> + <source srcset="radio-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Example GtkRadioButtons" src="radio-button.png"> +</picture> To add a `GtkCheckButton` to a group, use [method@Gtk.CheckButton.set_group]. @@ -30029,10 +32001,16 @@ is recommended to keep track of such state through a stateful `GAction` with a target for each button. Using the `toggled` signals to keep track of the group changes and state is discouraged. +# Shortcuts and Gestures + +`GtkCheckButton` supports the following keyboard shortcuts: + +- <kbd>␣</kbd> or <kbd>Enter</kbd> activates the button. + # CSS nodes ``` -checkbutton[.text-button] +checkbutton[.text-button][.grouped] ├── check ╰── [label] ``` @@ -30045,7 +32023,7 @@ is grouped together with other checkbuttons. # Accessibility -`GtkCheckButton` uses the %GTK_ACCESSIBLE_ROLE_CHECKBOX role. +`GtkCheckButton` uses the [enum@Gtk.AccessibleRole.checkbox] role. @@ -30054,12 +32032,12 @@ is grouped together with other checkbuttons. Creates a new `GtkCheckButton`. + line="788">Creates a new `GtkCheckButton`. a new `GtkCheckButton` + line="793">a new `GtkCheckButton` @@ -30067,12 +32045,12 @@ is grouped together with other checkbuttons. c:identifier="gtk_check_button_new_with_label"> Creates a new `GtkCheckButton` with the given text. + line="801">Creates a new `GtkCheckButton` with the given text. a new `GtkCheckButton` + line="807">a new `GtkCheckButton` @@ -30082,7 +32060,7 @@ is grouped together with other checkbuttons. allow-none="1"> the text for the check button. + line="803">the text for the check button. @@ -30091,12 +32069,12 @@ is grouped together with other checkbuttons. c:identifier="gtk_check_button_new_with_mnemonic"> Creates a new `GtkCheckButton` with the given text and a mnemonic. + line="815">Creates a new `GtkCheckButton` with the given text and a mnemonic. a new `GtkCheckButton` + line="822">a new `GtkCheckButton` @@ -30106,7 +32084,7 @@ is grouped together with other checkbuttons. allow-none="1"> The text of the button, with an underscore + line="817">The text of the button, with an underscore in front of the mnemonic character @@ -30137,22 +32115,21 @@ is grouped together with other checkbuttons. - Returns whether the check button is active. + line="891">Returns whether the check button is active. whether the check button is active + line="897">whether the check button is active a `GtkCheckButton` + line="893">a `GtkCheckButton` @@ -30161,22 +32138,21 @@ is grouped together with other checkbuttons. c:identifier="gtk_check_button_get_child" glib:get-property="child" version="4.8"> - Gets the child widget of @button or `NULL` if [property@CheckButton:label] is set. + line="1207">Gets the child widget of @button or `NULL` if [property@CheckButton:label] is set. the child widget of @button + line="1213">the child widget of @button a `GtkCheckButton` + line="1209">a `GtkCheckButton` @@ -30184,22 +32160,21 @@ is grouped together with other checkbuttons. - Returns whether the check button is in an inconsistent state. + line="873">Returns whether the check button is in an inconsistent state. %TRUE if @check_button is currently in an inconsistent state + line="879">%TRUE if @check_button is currently in an inconsistent state a `GtkCheckButton` + line="875">a `GtkCheckButton` @@ -30207,15 +32182,14 @@ is grouped together with other checkbuttons. - Returns the label of the check button or `NULL` if [property@CheckButton:child] is set. + line="961">Returns the label of the check button or `NULL` if [property@CheckButton:child] is set. The label @self shows next + line="967">The label @self shows next to the indicator. If no label is shown, %NULL will be returned. @@ -30223,7 +32197,7 @@ is grouped together with other checkbuttons. a `GtkCheckButton` + line="963">a `GtkCheckButton` @@ -30231,15 +32205,14 @@ is grouped together with other checkbuttons. - Returns whether underlines in the label indicate mnemonics. + line="1118">Returns whether underlines in the label indicate mnemonics. The value of the [property@Gtk.CheckButton:use-underline] property. + line="1124">The value of the [property@Gtk.CheckButton:use-underline] property. See [method@Gtk.CheckButton.set_use_underline] for details on how to set a new value. @@ -30248,7 +32221,7 @@ is grouped together with other checkbuttons. a `GtkCheckButton` + line="1120">a `GtkCheckButton` @@ -30256,10 +32229,9 @@ is grouped together with other checkbuttons. - Changes the check buttons active state. + line="909">Changes the check buttons active state. @@ -30268,13 +32240,13 @@ is grouped together with other checkbuttons. a `GtkCheckButton` + line="911">a `GtkCheckButton` the new value to set + line="912">the new value to set @@ -30283,10 +32255,9 @@ is grouped together with other checkbuttons. c:identifier="gtk_check_button_set_child" glib:set-property="child" version="4.8"> - Sets the child widget of @button. + line="1169">Sets the child widget of @button. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for @button. @@ -30301,7 +32272,7 @@ relations from @child to @button. a `GtkCheckButton` + line="1171">a `GtkCheckButton` allow-none="1"> the child widget + line="1172">the child widget @@ -30318,10 +32289,9 @@ relations from @child to @button. - Adds @self to the group of @group. + line="1037">Adds @self to the group of @group. In a group of multiple check buttons, only one button can be active at a time. The behavior of a checkbutton in a group is also commonly @@ -30344,7 +32314,7 @@ value. a `GtkCheckButton` + line="1039">a `GtkCheckButton` allow-none="1"> another `GtkCheckButton` to + line="1040">another `GtkCheckButton` to form a group with @@ -30362,10 +32332,9 @@ value. - Sets the `GtkCheckButton` to inconsistent state. + line="833">Sets the `GtkCheckButton` to inconsistent state. You should turn off the inconsistent state again if the user checks the check button. This has to be done manually. @@ -30377,13 +32346,13 @@ the check button. This has to be done manually. a `GtkCheckButton` + line="835">a `GtkCheckButton` %TRUE if state is inconsistent + line="836">%TRUE if state is inconsistent @@ -30391,10 +32360,9 @@ the check button. This has to be done manually. - Sets the text of @self. + line="983">Sets the text of @self. If [property@Gtk.CheckButton:use-underline] is %TRUE, an underscore in @label is interpreted as mnemonic indicator, see @@ -30407,7 +32375,7 @@ in @label is interpreted as mnemonic indicator, see a `GtkCheckButton` + line="985">a `GtkCheckButton` The text shown next to the indicator, or %NULL + line="986">The text shown next to the indicator, or %NULL to show no text @@ -30425,10 +32393,9 @@ in @label is interpreted as mnemonic indicator, see - Sets whether underlines in the label indicate mnemonics. + line="1138">Sets whether underlines in the label indicate mnemonics. If @setting is %TRUE, an underscore character in @self's label indicates a mnemonic accelerator key. This behavior is similar @@ -30441,13 +32408,13 @@ to [property@Gtk.Label:use-underline]. a `GtkCheckButton` + line="1140">a `GtkCheckButton` the new value to set + line="1141">the new value to set @@ -30458,13 +32425,9 @@ to [property@Gtk.Label:use-underline]. setter="set_active" getter="get_active" default-value="FALSE"> - - If the check button is active. + line="629">If the check button is active. Setting `active` to %TRUE will add the `:checked:` state to both the check button and the indicator CSS node. @@ -30476,13 +32439,9 @@ the check button and the indicator CSS node. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="686">The child widget. writable="1" transfer-ownership="none" setter="set_group"> - The check button whose group this widget belongs to. + line="642">The check button whose group this widget belongs to. setter="set_inconsistent" getter="get_inconsistent" default-value="FALSE"> - - If the check button is in an “in between” state. + line="662">If the check button is in an “in between” state. The inconsistent state only affects visual appearance, not the semantics of the button. @@ -30521,13 +32474,9 @@ not the semantics of the button. setter="set_label" getter="get_label" default-value="NULL"> - - Text of the label inside the check button, if it contains a label widget. + line="652">Text of the label inside the check button, if it contains a label widget. setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - If set, an underline in the text indicates that the following + line="675">If set, an underline in the text indicates that the following character is to be used as mnemonic. @@ -30552,7 +32497,7 @@ character is to be used as mnemonic. Emitted to when the check button is activated. + line="718">Emitted to when the check button is activated. The `::activate` signal on `GtkCheckButton` is an action signal and emitting it causes the button to animate press then release. @@ -30569,7 +32514,7 @@ The default bindings for this signal are all forms of the Emitted when the buttons's [property@Gtk.CheckButton:active] + line="703">Emitted when the buttons's [property@Gtk.CheckButton:active] property changes. @@ -30624,12 +32569,12 @@ property changes. glib:fundamental="1"> An expression using a custom `GClosure` to compute the value from + line="1510">An expression using a custom `GClosure` to compute the value from its parameters. Creates a `GtkExpression` that calls `closure` when it is evaluated. + line="1701">Creates a `GtkExpression` that calls `closure` when it is evaluated. `closure` is called with the `this` object and the results of evaluating the `params` expressions. @@ -30637,26 +32582,26 @@ the `params` expressions. a new `GtkExpression` + line="1713">a new `GtkExpression` the type of the value that this expression evaluates to + line="1703">the type of the value that this expression evaluates to closure to call when evaluating this expression. If closure is floating, it is adopted + line="1704">closure to call when evaluating this expression. If closure is floating, it is adopted the number of params needed for evaluating `closure` + line="1705">the number of params needed for evaluating `closure` allow-none="1"> expressions for each parameter + line="1706">expressions for each parameter @@ -30726,7 +32671,10 @@ unless the mode is @GTK_COLLATION_NONE. line="51">The `GtkColorButton` allows to open a color chooser dialog to change the color. -![An example GtkColorButton](color-button.png) +<picture> + <source srcset="color-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkColorButton" src="color-button.png"> +</picture> It is suitable widget for selecting a color in a preference dialog. @@ -30752,7 +32700,7 @@ it gets the .color style class. deprecated-version="4.10"> Creates a new color button. + line="354">Creates a new color button. This returns a widget in the form of a small button containing a swatch representing the current selected color. When the button @@ -30764,7 +32712,7 @@ color when the user finishes. a new color button + line="365">a new color button @@ -30772,19 +32720,19 @@ color when the user finishes. c:identifier="gtk_color_button_new_with_rgba"> Creates a new color button showing the given color. + line="375">Creates a new color button showing the given color. a new color button + line="381">a new color button A `GdkRGBA` to set the current color with + line="377">A `GdkRGBA` to set the current color with @@ -30794,23 +32742,22 @@ color when the user finishes. glib:get-property="modal" deprecated="1" deprecated-version="4.10"> - Gets whether the dialog is modal. + line="641">Gets whether the dialog is modal. Use [class@Gtk.ColorDialogButton] instead %TRUE if the dialog is modal + line="647">%TRUE if the dialog is modal a `GtkColorButton` + line="643">a `GtkColorButton` @@ -30820,23 +32767,22 @@ color when the user finishes. glib:get-property="title" deprecated="1" deprecated-version="4.10"> - Gets the title of the color chooser dialog. + line="597">Gets the title of the color chooser dialog. Use [class@Gtk.ColorDialogButton] instead An internal string, do not free the return value + line="603">An internal string, do not free the return value a `GtkColorButton` + line="599">a `GtkColorButton` @@ -30846,10 +32792,9 @@ color when the user finishes. glib:set-property="modal" deprecated="1" deprecated-version="4.10"> - Sets whether the dialog should be modal. + line="615">Sets whether the dialog should be modal. Use [class@Gtk.ColorDialogButton] instead @@ -30859,13 +32804,13 @@ color when the user finishes. a `GtkColorButton` + line="617">a `GtkColorButton` %TRUE to make the dialog modal + line="618">%TRUE to make the dialog modal @@ -30875,10 +32820,9 @@ color when the user finishes. glib:set-property="title" deprecated="1" deprecated-version="4.10"> - Sets the title for the color chooser dialog. + line="570">Sets the title for the color chooser dialog. Use [class@Gtk.ColorDialogButton] instead @@ -30888,13 +32832,13 @@ color when the user finishes. a `GtkColorButton` + line="572">a `GtkColorButton` String containing new window title + line="573">String containing new window title @@ -30905,13 +32849,9 @@ color when the user finishes. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the color chooser dialog should be modal. + line="248">Whether the color chooser dialog should be modal. default-value="FALSE"> Whether the color chooser should open in editor mode. + line="233">Whether the color chooser should open in editor mode. This property should be used in cases where the palette in the editor would be redundant, such as when the color @@ -30933,19 +32873,15 @@ button is already part of a palette. setter="set_title" getter="get_title" default-value="Pick a Color"> - - The title of the color chooser dialog + line="178">The title of the color chooser dialog Emitted to when the color button is activated. + line="211">Emitted to when the color button is activated. The `::activate` signal on `GtkMenuButton` is an action signal and emitting it causes the button to pop up its dialog. @@ -30956,7 +32892,7 @@ emitting it causes the button to pop up its dialog. Emitted when the user selects a color. + line="190">Emitted when the user selects a color. When handling this signal, use [method@Gtk.ColorChooser.get_rgba] to find out which color was just selected. @@ -31077,7 +33013,6 @@ If @colors is %NULL, removes all previously added palettes. invoker="get_rgba" deprecated="1" deprecated-version="4.10"> - Gets the currently-selected color. @@ -31109,7 +33044,6 @@ If @colors is %NULL, removes all previously added palettes. invoker="set_rgba" deprecated="1" deprecated-version="4.10"> - Sets the color. @@ -31207,7 +33141,6 @@ If @colors is %NULL, removes all previously added palettes. glib:get-property="rgba" deprecated="1" deprecated-version="4.10"> - Gets the currently-selected color. @@ -31240,7 +33173,6 @@ If @colors is %NULL, removes all previously added palettes. glib:get-property="use-alpha" deprecated="1" deprecated-version="4.10"> - Returns whether the color chooser shows the alpha channel. @@ -31268,7 +33200,6 @@ If @colors is %NULL, removes all previously added palettes. glib:set-property="rgba" deprecated="1" deprecated-version="4.10"> - Sets the color. @@ -31298,7 +33229,6 @@ If @colors is %NULL, removes all previously added palettes. glib:set-property="use-alpha" deprecated="1" deprecated-version="4.10"> - Sets whether or not the color chooser should use the alpha channel. @@ -31330,10 +33260,6 @@ If @colors is %NULL, removes all previously added palettes. transfer-ownership="none" setter="set_rgba" getter="get_rgba"> - - The currently selected color, as a `GdkRGBA` struct. @@ -31352,10 +33278,6 @@ programmatically. setter="set_use_alpha" getter="get_use_alpha" default-value="TRUE"> - - Whether colors may have alpha (translucency). @@ -31408,7 +33330,10 @@ Space, Shift+Space, Return or Enter. filename="gtk/gtkcolorchooserdialog.c" line="33">A dialog for choosing a color. -![An example GtkColorChooserDialog](colorchooser.png) +<picture> + <source srcset="colorchooser-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkColorChooserDialog" src="colorchooser.png"> +</picture> `GtkColorChooserDialog` implements the [iface@Gtk.ColorChooser] interface and does not provide much API of its own. @@ -31439,14 +33364,14 @@ class `.colorchooser`. deprecated-version="4.10"> Creates a new `GtkColorChooserDialog`. + line="298">Creates a new `GtkColorChooserDialog`. Use [class@Gtk.ColorDialog] instead a new `GtkColorChooserDialog` + line="305">a new `GtkColorChooserDialog` @@ -31456,7 +33381,7 @@ class `.colorchooser`. allow-none="1"> Title of the dialog + line="300">Title of the dialog allow-none="1"> Transient parent of the dialog + line="301">Transient parent of the dialog @@ -31474,6 +33399,11 @@ class `.colorchooser`. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the color chooser dialog is showing the single-color editor. + +It can be set to switch the color chooser into single-color editing mode. @@ -31634,6 +33564,14 @@ To change the initially selected color, use The `GtkColorChooserWidget` is used in the [class@Gtk.ColorChooserDialog] to provide a dialog for selecting colors. +# Actions + +`GtkColorChooserWidget` defines a set of built-in actions: + +- `color.customize` activates the color editor for the given color. +- `color.select` emits the [signal@Gtk.ColorChooser::color-activated] signal + for the given color. + # CSS names `GtkColorChooserWidget` has a single CSS node with name colorchooser. @@ -31645,13 +33583,13 @@ to provide a dialog for selecting colors. Creates a new `GtkColorChooserWidget`. + line="890">Creates a new `GtkColorChooserWidget`. a new `GtkColorChooserWidget` + line="895">a new `GtkColorChooserWidget` @@ -31661,7 +33599,7 @@ to provide a dialog for selecting colors. default-value="FALSE"> %TRUE when the color chooser is showing the single-color editor. + line="729">%TRUE when the color chooser is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode. @@ -31677,15 +33615,14 @@ It can be set to switch the color chooser into single-color editing mode. glib:type-struct="ColorDialogClass"> A `GtkColorDialog` object collects the arguments that -are needed to present a color chooser dialog to the -user, such as a title for the dialog and whether it -should be modal. + line="30">Asynchronous API to present a color chooser dialog. + +`GtkColorDialog` collects the arguments that are needed to present +the dialog to the user, such as a title for the dialog and whether +it should be modal. The dialog is shown with the [method@Gtk.ColorDialog.choose_rgba] -function. This API follows the GIO async pattern, and the -result can be obtained by calling -[method@Gtk.ColorDialog.choose_rgba_finish]. +function. See [class@Gtk.ColorDialogButton] for a convenient control that uses `GtkColorDialog` and presents the results. @@ -31695,26 +33632,22 @@ that uses `GtkColorDialog` and presents the results. version="4.10"> Creates a new `GtkColorDialog` object. + line="199">Creates a new `GtkColorDialog` object. the new `GtkColorDialog` + line="204">the new `GtkColorDialog` + version="4.10" + glib:finish-func="choose_rgba_finish"> This function initiates a color choice operation by -presenting a color chooser dialog to the user. - -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.ColorDialog.choose_rgba_finish] -to obtain the result. + line="425">Presents a color chooser dialog to the user. @@ -31723,7 +33656,7 @@ to obtain the result. a `GtkColorDialog` + line="427">a color dialog allow-none="1"> the parent `GtkWindow` + line="428">the parent window allow-none="1"> the color to select initially + line="429">the color to select initially allow-none="1"> a `GCancellable` to cancel the operation + line="430">a cancellable to cancel the operation closure="4"> a callback to call when the operation is complete + line="431">a callback to call + when the operation is complete + allow-none="1"> data to pass to @callback + line="433">data to pass to @callback @@ -31782,27 +33715,25 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.ColorDialog.choose_rgba] call and -returns the resulting color. + line="466">Finishes the [method@Gtk.ColorDialog.choose_rgba] call the selected color, or - `NULL` and @error is set + line="474">the selected color a `GtkColorDialog` + line="468">a color dialog a `GAsyncResult` + line="469">the result @@ -31813,21 +33744,21 @@ returns the resulting color. version="4.10"> Returns whether the color chooser dialog + line="265">Returns whether the color chooser dialog blocks interaction with the parent window while it is presented. `TRUE` if the color chooser dialog is modal + line="273">true if the color chooser dialog is modal a `GtkColorDialog` + line="267">a color dialog @@ -31838,20 +33769,20 @@ while it is presented. version="4.10"> Returns the title that will be shown on the + line="217">Returns the title that will be shown on the color chooser dialog. the title + line="224">the title a `GtkColorDialog` + line="219">a color dialog @@ -31862,19 +33793,19 @@ color chooser dialog. version="4.10"> Returns whether colors may have alpha. + line="310">Returns whether colors may have alpha. `TRUE` if colors may have alpha + line="316">true if colors may have alpha a `GtkColorDialog` + line="312">a color dailog @@ -31885,7 +33816,7 @@ color chooser dialog. version="4.10"> Sets whether the color chooser dialog + line="285">Sets whether the color chooser dialog blocks interaction with the parent window while it is presented. @@ -31896,13 +33827,13 @@ while it is presented. a `GtkColorDialog` + line="287">a color dialog the new value + line="288">the new value @@ -31913,7 +33844,7 @@ while it is presented. version="4.10"> Sets the title that will be shown on the + line="236">Sets the title that will be shown on the color chooser dialog. @@ -31923,13 +33854,13 @@ color chooser dialog. a `GtkColorDialog` + line="238">a color dialog the new title + line="239">the new title @@ -31940,7 +33871,7 @@ color chooser dialog. version="4.10"> Sets whether colors may have alpha. + line="328">Sets whether colors may have alpha. @@ -31949,13 +33880,13 @@ color chooser dialog. a `GtkColorDialog` + line="330">a color dialog the new value + line="331">the new value @@ -31967,13 +33898,9 @@ color chooser dialog. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the color chooser dialog is modal. + line="166">Whether the color chooser dialog is modal. setter="set_title" getter="get_title" default-value="NULL"> - - A title that may be shown on the color chooser -dialog that is presented by [method@Gtk.ColorDialog.choose_rgba]. + line="154">A title that may be shown on the color chooser dialog. setter="set_with_alpha" getter="get_with_alpha" default-value="TRUE"> - - Whether colors may have alpha (translucency). + line="178">Whether colors may have alpha (translucency). -When with-alpha is %FALSE, the color that is selected +When with-alpha is false, the color that is selected will be forced to have alpha == 1. @@ -32023,10 +33941,12 @@ will be forced to have alpha == 1. glib:type-struct="ColorDialogButtonClass"> The `GtkColorDialogButton` is a wrapped around a [class@Gtk.ColorDialog] -and allows to open a color chooser dialog to change the color. + line="53">Opens a color chooser dialog to select a color. -![An example GtkColorDialogButton](color-button.png) +<picture> + <source srcset="color-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkColorDialogButton" src="color-button.png"> +</picture> It is suitable widget for selecting a color in a preference dialog. @@ -32050,7 +33970,7 @@ it gets the .color style class. version="4.10"> Creates a new `GtkColorDialogButton` with the + line="431">Creates a new `GtkColorDialogButton` with the given `GtkColorDialog`. You can pass `NULL` to this function and set a `GtkColorDialog` @@ -32059,7 +33979,7 @@ later. The button will be insensitive until that happens. the new `GtkColorDialogButton` + line="441">the new `GtkColorDialogButton` @@ -32069,7 +33989,7 @@ later. The button will be insensitive until that happens. allow-none="1"> the `GtkColorDialog` to use + line="433">the `GtkColorDialog` to use @@ -32080,19 +34000,19 @@ later. The button will be insensitive until that happens. version="4.10"> Returns the `GtkColorDialog` of @self. + line="464">Returns the `GtkColorDialog` of @self. the `GtkColorDialog` + line="470">the `GtkColorDialog` a `GtkColorDialogButton` + line="466">a `GtkColorDialogButton` @@ -32103,23 +34023,23 @@ later. The button will be insensitive until that happens. version="4.10"> Returns the color of the button. + line="508">Returns the color of the button. This function is what should be used to obtain the color that was chosen by the user. To get -informed about changes, listen to "notify::color". +informed about changes, listen to "notify::rgba". the color + line="518">the color a `GtkColorDialogButton` + line="510">a `GtkColorDialogButton` @@ -32130,7 +34050,7 @@ informed about changes, listen to "notify::color". version="4.10"> Sets a `GtkColorDialog` object to use for + line="482">Sets a `GtkColorDialog` object to use for creating the color chooser dialog that is presented when the user clicks the button. @@ -32141,13 +34061,13 @@ presented when the user clicks the button. a `GtkColorDialogButton` + line="484">a `GtkColorDialogButton` the new `GtkColorDialog` + line="485">the new `GtkColorDialog` @@ -32158,7 +34078,7 @@ presented when the user clicks the button. version="4.10"> Sets the color of the button. + line="530">Sets the color of the button. @@ -32167,13 +34087,13 @@ presented when the user clicks the button. a `GtkColorDialogButton` + line="532">a `GtkColorDialogButton` the new color + line="533">the new color @@ -32184,13 +34104,9 @@ presented when the user clicks the button. transfer-ownership="none" setter="set_dialog" getter="get_dialog"> - - The `GtkColorDialog` that contains parameters for + line="261">The `GtkColorDialog` that contains parameters for the color chooser dialog. @@ -32200,13 +34116,9 @@ the color chooser dialog. transfer-ownership="none" setter="set_rgba" getter="get_rgba"> - - The selected color. + line="274">The selected color. This property can be set to give the button its initial color, and it will be updated to reflect the users choice @@ -32219,7 +34131,7 @@ to the buttons color. Emitted when the color dialog button is activated. + line="295">Emitted when the color dialog button is activated. The `::activate` signal on `GtkColorDialogButton` is an action signal and emitting it causes the button to pop up its dialog. @@ -32253,8 +34165,7 @@ and emitting it causes the button to pop up its dialog. glib:type-struct="ColumnViewClass"> `GtkColumnView` presents a large dynamic list of items using multiple columns -with headers. + line="43">Presents a large dynamic list of items using multiple columns with headers. `GtkColumnView` uses the factories of its columns to generate a cell widget for each column, for each visible item and displays them together as the row for @@ -32314,10 +34225,10 @@ the style of [list presentation](section-list-widget.html#list-styles): # Accessibility -`GtkColumnView` uses the %GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title -widgets are using the %GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets -are using the %GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using -the %GTK_ACCESSIBLE_ROLE_GRID_CELL role +`GtkColumnView` uses the [enum@Gtk.AccessibleRole.tree_grid] role, header title +widgets are using the [enum@Gtk.AccessibleRole.column_header] role. The row widgets +are using the [enum@Gtk.AccessibleRole.row] role, and individual cells are using +the [enum@Gtk.AccessibleRole.grid_cell] role @@ -32326,7 +34237,7 @@ the %GTK_ACCESSIBLE_ROLE_GRID_CELL role Creates a new `GtkColumnView`. + line="1516">Creates a new `GtkColumnView`. You most likely want to call [method@Gtk.ColumnView.append_column] to add columns next. @@ -32334,7 +34245,7 @@ to add columns next. a new `GtkColumnView` + line="1525">a new `GtkColumnView` @@ -32344,7 +34255,7 @@ to add columns next. allow-none="1"> the list model to use + line="1518">the list model to use @@ -32353,7 +34264,7 @@ to add columns next. c:identifier="gtk_column_view_append_column"> Appends the @column to the end of the columns in @self. + line="1687">Appends the @column to the end of the columns in @self. @@ -32362,13 +34273,13 @@ to add columns next. a `GtkColumnView` + line="1689">a `GtkColumnView` a `GtkColumnViewColumn` that hasn't been added to a + line="1690">a `GtkColumnViewColumn` that hasn't been added to a `GtkColumnView` yet @@ -32377,10 +34288,9 @@ to add columns next. - Gets the list of columns in this column view. + line="1584">Gets the list of columns in this column view. This list is constant over the lifetime of @self and can be used to monitor changes to the columns of @self by connecting to the @@ -32389,14 +34299,14 @@ monitor changes to the columns of @self by connecting to the The list managing the columns + line="1594">The list managing the columns a `GtkColumnView` + line="1586">a `GtkColumnView` @@ -32404,23 +34314,21 @@ monitor changes to the columns of @self by connecting to the - Returns whether rows can be selected by dragging with the mouse. + line="2060">Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled + line="2066">%TRUE if rubberband selection is enabled a `GtkColumnView` + line="2062">a `GtkColumnView` @@ -32429,22 +34337,21 @@ monitor changes to the columns of @self by connecting to the c:identifier="gtk_column_view_get_header_factory" glib:get-property="header-factory" version="4.12"> - Gets the factory that's currently used to populate section headers. + line="2164">Gets the factory that's currently used to populate section headers. The factory in use + line="2170">The factory in use a `GtkColumnView` + line="2166">a `GtkColumnView` @@ -32452,22 +34359,21 @@ monitor changes to the columns of @self by connecting to the - Gets the model that's currently used to read the items displayed. + line="1544">Gets the model that's currently used to read the items displayed. The model in use + line="1550">The model in use a `GtkColumnView` + line="1546">a `GtkColumnView` @@ -32475,22 +34381,21 @@ monitor changes to the columns of @self by connecting to the - Returns whether columns are reorderable. + line="2023">Returns whether columns are reorderable. %TRUE if columns are reorderable + line="2029">%TRUE if columns are reorderable a `GtkColumnView` + line="2025">a `GtkColumnView` @@ -32499,22 +34404,21 @@ monitor changes to the columns of @self by connecting to the c:identifier="gtk_column_view_get_row_factory" glib:get-property="row-factory" version="4.12"> - Gets the factory set via [method@Gtk.ColumnView.set_row_factory]. + line="2105">Gets the factory set via [method@Gtk.ColumnView.set_row_factory]. The factory + line="2111">The factory a `GtkColumnView` + line="2107">a `GtkColumnView` @@ -32522,24 +34426,22 @@ monitor changes to the columns of @self by connecting to the - Returns whether the list should show separators + line="1670">Returns whether the list should show separators between columns. %TRUE if the list shows column separators + line="1677">%TRUE if the list shows column separators a `GtkColumnView` + line="1672">a `GtkColumnView` @@ -32547,24 +34449,22 @@ between columns. - Returns whether the list should show separators + line="1626">Returns whether the list should show separators between rows. %TRUE if the list shows separators + line="1633">%TRUE if the list shows separators a `GtkColumnView` + line="1628">a `GtkColumnView` @@ -32572,24 +34472,22 @@ between rows. - Returns whether rows will be activated on single click and + line="1985">Returns whether rows will be activated on single click and selected on hover. %TRUE if rows are activated on single click + line="1992">%TRUE if rows are activated on single click a `GtkColumnView` + line="1987">a `GtkColumnView` @@ -32597,10 +34495,9 @@ selected on hover. - Returns a special sorter that reflects the users sorting + line="1893">Returns a special sorter that reflects the users sorting choices in the column view. To allow users to customizable sorting by clicking on column @@ -32623,14 +34520,14 @@ gtk_column_view_set_model (view, selection); the `GtkSorter` of @self + line="1917">the `GtkSorter` of @self a `GtkColumnView` + line="1895">a `GtkColumnView` @@ -32639,22 +34536,21 @@ gtk_column_view_set_model (view, selection); c:identifier="gtk_column_view_get_tab_behavior" glib:get-property="tab-behavior" version="4.12"> - Gets the behavior set for the <kbd>Tab</kbd> key. + line="2146">Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key + line="2152">The behavior of the <kbd>Tab</kbd> key a `GtkColumnView` + line="2148">a `GtkColumnView` @@ -32663,7 +34559,7 @@ gtk_column_view_set_model (view, selection); c:identifier="gtk_column_view_insert_column"> Inserts a column at the given position in the columns of @self. + line="1752">Inserts a column at the given position in the columns of @self. If @column is already a column of @self, it will be repositioned. @@ -32674,19 +34570,19 @@ If @column is already a column of @self, it will be repositioned. a `GtkColumnView` + line="1754">a `GtkColumnView` the position to insert @column at + line="1755">the position to insert @column at the `GtkColumnViewColumn` to insert + line="1756">the `GtkColumnViewColumn` to insert @@ -32695,7 +34591,7 @@ If @column is already a column of @self, it will be repositioned. c:identifier="gtk_column_view_remove_column"> Removes the @column from the list of columns of @self. + line="1707">Removes the @column from the list of columns of @self. @@ -32704,13 +34600,13 @@ If @column is already a column of @self, it will be repositioned. a `GtkColumnView` + line="1709">a `GtkColumnView` a `GtkColumnViewColumn` that's part of @self + line="1710">a `GtkColumnViewColumn` that's part of @self @@ -32720,7 +34616,7 @@ If @column is already a column of @self, it will be repositioned. version="4.12"> Scroll to the row at the given position - or cell if a column is + line="2210">Scroll to the row at the given position - or cell if a column is given - and performs the actions specified in @flags. This function works no matter if the listview is shown or focused. @@ -32733,13 +34629,14 @@ If it isn't, then the changes will take effect once that happens. The columnview to scroll in + line="2212">The columnview to scroll in position of the item + line="2213">position of the item. Must be less than the number of + items in the view. allow-none="1"> The column to scroll to + line="2215">The column to scroll to or %NULL to not scroll columns. actions to perform + line="2217">actions to perform allow-none="1"> details of how to perform + line="2218">details of how to perform the scroll operation or %NULL to scroll into view @@ -32773,11 +34670,9 @@ If it isn't, then the changes will take effect once that happens. - Sets whether selections can be changed by dragging with the mouse. + line="2039">Sets whether selections can be changed by dragging with the mouse. @@ -32786,13 +34681,13 @@ If it isn't, then the changes will take effect once that happens. a `GtkColumnView` + line="2041">a `GtkColumnView` %TRUE to enable rubberband selection + line="2042">%TRUE to enable rubberband selection @@ -32801,10 +34696,9 @@ If it isn't, then the changes will take effect once that happens. c:identifier="gtk_column_view_set_header_factory" glib:set-property="header-factory" version="4.12"> - Sets the `GtkListItemFactory` to use for populating the + line="2182">Sets the `GtkListItemFactory` to use for populating the [class@Gtk.ListHeader] objects used in section headers. If this factory is set to %NULL, the list will not show @@ -32817,7 +34711,7 @@ section headers. a `GtkColumnView` + line="2184">a `GtkColumnView` allow-none="1"> the factory to use + line="2185">the factory to use @@ -32834,10 +34728,9 @@ section headers. - Sets the model to use. + line="1560">Sets the model to use. This must be a [iface@Gtk.SelectionModel]. @@ -32848,7 +34741,7 @@ This must be a [iface@Gtk.SelectionModel]. a `GtkColumnView` + line="1562">a `GtkColumnView` allow-none="1"> the model to use + line="1563">the model to use @@ -32865,10 +34758,9 @@ This must be a [iface@Gtk.SelectionModel]. - Sets whether columns should be reorderable by dragging. + line="2002">Sets whether columns should be reorderable by dragging. @@ -32877,13 +34769,13 @@ This must be a [iface@Gtk.SelectionModel]. a `GtkColumnView` + line="2004">a `GtkColumnView` whether columns should be reorderable + line="2005">whether columns should be reorderable @@ -32892,10 +34784,9 @@ This must be a [iface@Gtk.SelectionModel]. c:identifier="gtk_column_view_set_row_factory" glib:set-property="row-factory" version="4.12"> - Sets the factory used for configuring rows. The factory must be for configuring + line="2076">Sets the factory used for configuring rows. The factory must be for configuring [class@Gtk.ColumnViewRow] objects. If this factory is not set - which is the default - then the defaults will be used. @@ -32910,7 +34801,7 @@ that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. a `GtkColumnView` + line="2078">a `GtkColumnView` The row factory + line="2079">The row factory @@ -32927,11 +34818,9 @@ that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. - Sets whether the list should show separators + line="1643">Sets whether the list should show separators between columns. @@ -32941,13 +34830,13 @@ between columns. a `GtkColumnView` + line="1645">a `GtkColumnView` %TRUE to show column separators + line="1646">%TRUE to show column separators @@ -32955,11 +34844,9 @@ between columns. - Sets whether the list should show separators + line="1604">Sets whether the list should show separators between rows. @@ -32969,13 +34856,13 @@ between rows. a `GtkColumnView` + line="1606">a `GtkColumnView` %TRUE to show row separators + line="1607">%TRUE to show row separators @@ -32983,11 +34870,9 @@ between rows. - Sets whether rows should be activated on single click and + line="1963">Sets whether rows should be activated on single click and selected on hover. @@ -32997,13 +34882,13 @@ selected on hover. a `GtkColumnView` + line="1965">a `GtkColumnView` %TRUE to activate items on single click + line="1966">%TRUE to activate items on single click @@ -33012,10 +34897,9 @@ selected on hover. c:identifier="gtk_column_view_set_tab_behavior" glib:set-property="tab-behavior" version="4.12"> - Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + line="2123">Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. @@ -33024,13 +34908,13 @@ selected on hover. a `GtkColumnView` + line="2125">a `GtkColumnView` The desired tab behavior + line="2126">The desired tab behavior @@ -33039,7 +34923,7 @@ selected on hover. c:identifier="gtk_column_view_sort_by_column"> Sets the sorting of the view. + line="1927">Sets the sorting of the view. This function should be used to set up the initial sorting. At runtime, users can change the sorting of a column view @@ -33059,7 +34943,7 @@ If @column is %NULL, the view will be unsorted. a `GtkColumnView` + line="1929">a `GtkColumnView` allow-none="1"> the `GtkColumnViewColumn` to sort by + line="1930">the `GtkColumnViewColumn` to sort by the direction to sort in + line="1931">the direction to sort in - The list of columns. + line="821">The list of columns. setter="set_enable_rubberband" getter="get_enable_rubberband" default-value="FALSE"> - - Allow rubberband selection. + line="831">Allow rubberband selection. transfer-ownership="none" setter="set_header_factory" getter="get_header_factory"> - - Factory for creating header widgets. + line="928">Factory for creating header widgets. + +The factory must be for configuring [class@Gtk.ListHeader] objects. transfer-ownership="none" setter="set_model" getter="get_model"> - - Model for the items displayed. + line="841">Model for the items displayed. setter="set_reorderable" getter="get_reorderable" default-value="TRUE"> - - Whether columns are reorderable. + line="851">Whether columns are reorderable. transfer-ownership="none" setter="set_row_factory" getter="get_row_factory"> - - The factory used for configuring rows. + line="861">The factory used for configuring rows. + +The factory must be for configuring [class@Gtk.ColumnViewRow] objects. setter="set_show_column_separators" getter="get_show_column_separators" default-value="FALSE"> - - Show separators between columns. + line="885">Show separators between columns. setter="set_show_row_separators" getter="get_show_row_separators" default-value="FALSE"> - - Show separators between rows. + line="875">Show separators between rows. setter="set_single_click_activate" getter="get_single_click_activate" default-value="FALSE"> - - Activate rows on single click and select them on hover. + line="905">Activate rows on single click and select them on hover. - Sorter with the sorting choices of the user. + line="895">Sorter with the sorting choices of the user. setter="set_tab_behavior" getter="get_tab_behavior" default-value="GTK_LIST_TAB_ALL"> - - Behavior of the <kbd>Tab</kbd> key + line="915">Behavior of the <kbd>Tab</kbd> key Emitted when a row has been activated by the user, usually via activating + line="944">Emitted when a row has been activated by the user, usually via activating the GtkListBase|list.activate-item action. This allows for a convenient way to handle activation in a columnview. @@ -33246,7 +35094,7 @@ signal. position of item to activate + line="947">position of item to activate @@ -33262,12 +35110,12 @@ signal. glib:type-struct="ColumnViewCellClass"> `GtkColumnViewCell` is used by [class@Gtk.ColumnViewColumn] to represent items -in a cell in [class@Gtk.ColumnView]. + line="26">Represents items in a cell in [class@Gtk.ColumnView]. -The `GtkColumnViewCell`s are managed by the columnview widget (with its factory) -and cannot be created by applications, but they need to be populated -by application code. This is done by calling [method@Gtk.ColumnViewCell.set_child]. +The `GtkColumnViewCell`s are managed by the [class@Gtk.ColumnView] +widget (with its factory) and cannot be created by applications, but +they need to be populated by application code. This is done by calling +[method@Gtk.ColumnViewCell.set_child]. `GtkColumnViewCell`s exist in 2 stages: @@ -33282,7 +35130,6 @@ by application code. This is done by calling [method@Gtk.ColumnViewCell.set_chil c:identifier="gtk_column_view_cell_get_child" glib:get-property="child" version="4.12"> - Gets the child previously set via gtk_column_view_cell_set_child() or @@ -33307,7 +35154,6 @@ by application code. This is done by calling [method@Gtk.ColumnViewCell.set_chil c:identifier="gtk_column_view_cell_get_focusable" glib:get-property="focusable" version="4.12"> - Checks if a list item has been set to be focusable via @@ -33332,7 +35178,6 @@ gtk_column_view_cell_set_focusable(). c:identifier="gtk_column_view_cell_get_item" glib:get-property="item" version="4.12"> - Gets the model item that associated with @self. @@ -33358,7 +35203,6 @@ If @self is unbound, this function returns %NULL. c:identifier="gtk_column_view_cell_get_position" glib:get-property="position" version="4.12"> - Gets the position in the model that @self currently displays. @@ -33384,12 +35228,11 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. c:identifier="gtk_column_view_cell_get_selected" glib:get-property="selected" version="4.12"> - Checks if the item is displayed as selected. -The selected state is maintained by the liste widget and its model +The selected state is maintained by the list widget and its model and cannot be set otherwise. @@ -33411,7 +35254,6 @@ and cannot be set otherwise. c:identifier="gtk_column_view_cell_set_child" glib:set-property="child" version="4.12"> - Sets the child to be used for this listitem. @@ -33445,7 +35287,6 @@ binding it multiple times. c:identifier="gtk_column_view_cell_set_focusable" glib:set-property="focusable" version="4.12"> - Sets @self to be focusable. @@ -33482,10 +35323,6 @@ By default, list items are focusable. transfer-ownership="none" setter="set_child" getter="get_child"> - - Widget used for display. @@ -33498,10 +35335,6 @@ By default, list items are focusable. setter="set_focusable" getter="get_focusable" default-value="FALSE"> - - If the item can be focused with the keyboard. @@ -33511,8 +35344,6 @@ By default, list items are focusable. version="4.12" transfer-ownership="none" getter="get_item"> - Displayed item. @@ -33523,8 +35354,6 @@ By default, list items are focusable. transfer-ownership="none" getter="get_position" default-value="4294967295"> - Position of the item. @@ -33535,8 +35364,6 @@ By default, list items are focusable. transfer-ownership="none" getter="get_selected" default-value="FALSE"> - If the item is currently selected. @@ -33582,7 +35409,7 @@ by clicking on the column header. Creates a new `GtkColumnViewColumn` that uses the given @factory for + line="369">Creates a new `GtkColumnViewColumn` that uses the given @factory for mapping items to widgets. You most likely want to call [method@Gtk.ColumnView.append_column] next. @@ -33597,7 +35424,7 @@ column = gtk_column_view_column_new (_("Name"), a new `GtkColumnViewColumn` using the given @factory + line="386">a new `GtkColumnViewColumn` using the given @factory @@ -33607,7 +35434,7 @@ column = gtk_column_view_column_new (_("Name"), allow-none="1"> Title to use for this column + line="371">Title to use for this column The factory to populate items with + line="372">The factory to populate items with @@ -33624,24 +35451,23 @@ column = gtk_column_view_column_new (_("Name"), - Gets the column view that's currently displaying this column. + line="595">Gets the column view that's currently displaying this column. If @self has not been added to a column view yet, %NULL is returned. The column view displaying @self. + line="603">The column view displaying @self. a `GtkColumnViewColumn` + line="597">a `GtkColumnViewColumn` @@ -33649,22 +35475,21 @@ If @self has not been added to a column view yet, %NULL is returned. - Returns whether this column should expand. + line="940">Returns whether this column should expand. %TRUE if this column expands + line="946">%TRUE if this column expands a `GtkColumnViewColumn` + line="942">a `GtkColumnViewColumn` @@ -33672,23 +35497,22 @@ If @self has not been added to a column view yet, %NULL is returned. - Gets the factory that's currently used to populate list items for + line="649">Gets the factory that's currently used to populate list items for this column. The factory in use + line="656">The factory in use a `GtkColumnViewColumn` + line="651">a `GtkColumnViewColumn` @@ -33696,22 +35520,21 @@ this column. - Gets the fixed width of the column. + line="1021">Gets the fixed width of the column. the fixed with of the column + line="1027">the fixed with of the column a `GtkColumnViewColumn` + line="1023">a `GtkColumnViewColumn` @@ -33719,23 +35542,22 @@ this column. - Gets the menu model that is used to create the context menu + line="896">Gets the menu model that is used to create the context menu for the column header. the `GMenuModel` + line="903">the `GMenuModel` a `GtkColumnViewColumn` + line="898">a `GtkColumnViewColumn` @@ -33744,22 +35566,21 @@ for the column header. c:identifier="gtk_column_view_column_get_id" glib:get-property="id" version="4.10"> - Returns the ID set with gtk_column_view_column_set_id(). + line="1091">Returns the ID set with gtk_column_view_column_set_id(). The column's ID + line="1097">The column's ID a `GtkColumnViewColumn` + line="1093">a `GtkColumnViewColumn` @@ -33767,22 +35588,21 @@ for the column header. - Returns whether this column is resizable. + line="977">Returns whether this column is resizable. %TRUE if this column is resizable + line="983">%TRUE if this column is resizable a `GtkColumnViewColumn` + line="979">a `GtkColumnViewColumn` @@ -33790,22 +35610,21 @@ for the column header. - Returns the sorter that is associated with the column. + line="804">Returns the sorter that is associated with the column. the `GtkSorter` of @self + line="810">the `GtkSorter` of @self a `GtkColumnViewColumn` + line="806">a `GtkColumnViewColumn` @@ -33813,22 +35632,21 @@ for the column header. - Returns the title set with gtk_column_view_column_set_title(). + line="745">Returns the title set with gtk_column_view_column_set_title(). The column's title + line="751">The column's title a `GtkColumnViewColumn` + line="747">a `GtkColumnViewColumn` @@ -33836,22 +35654,21 @@ for the column header. - Returns whether this column is visible. + line="856">Returns whether this column is visible. %TRUE if this column is visible + line="862">%TRUE if this column is visible a `GtkColumnViewColumn` + line="858">a `GtkColumnViewColumn` @@ -33859,10 +35676,9 @@ for the column header. - Sets the column to take available extra space. + line="913">Sets the column to take available extra space. The extra space is shared equally amongst all columns that have the expand set to %TRUE. @@ -33874,13 +35690,13 @@ have the expand set to %TRUE. a `GtkColumnViewColumn` + line="915">a `GtkColumnViewColumn` %TRUE if this column should expand to fill available sace + line="916">%TRUE if this column should expand to fill available sace @@ -33888,10 +35704,9 @@ have the expand set to %TRUE. - Sets the `GtkListItemFactory` to use for populating list items for this + line="689">Sets the `GtkListItemFactory` to use for populating list items for this column. @@ -33901,7 +35716,7 @@ column. a `GtkColumnViewColumn` + line="691">a `GtkColumnViewColumn` allow-none="1"> the factory to use + line="692">the factory to use @@ -33918,10 +35733,9 @@ column. - If @fixed_width is not -1, sets the fixed width of @column; + line="993">If @fixed_width is not -1, sets the fixed width of @column; otherwise unsets it. Setting a fixed width overrides the automatically calculated @@ -33934,13 +35748,13 @@ width. Interactive resizing also sets the “fixed-width” property. a `GtkColumnViewColumn` + line="995">a `GtkColumnViewColumn` the new fixed width, or -1 + line="996">the new fixed width, or -1 @@ -33948,10 +35762,9 @@ width. Interactive resizing also sets the “fixed-width” property. - Sets the menu model that is used to create the context menu + line="872">Sets the menu model that is used to create the context menu for the column header. @@ -33961,7 +35774,7 @@ for the column header. a `GtkColumnViewColumn` + line="874">a `GtkColumnViewColumn` allow-none="1"> a `GMenuModel` + line="875">a `GMenuModel` @@ -33979,10 +35792,9 @@ for the column header. c:identifier="gtk_column_view_column_set_id" glib:set-property="id" version="4.10"> - Sets the id of this column. + line="1062">Sets the id of this column. GTK makes no use of this, but applications can use it when storing column view configuration. @@ -33996,7 +35808,7 @@ It is up to callers to ensure uniqueness of IDs. a `GtkColumnViewColumn` + line="1064">a `GtkColumnViewColumn` allow-none="1"> ID to use for this column + line="1065">ID to use for this column @@ -34013,10 +35825,9 @@ It is up to callers to ensure uniqueness of IDs. - Sets whether this column should be resizable by dragging. + line="956">Sets whether this column should be resizable by dragging. @@ -34025,13 +35836,13 @@ It is up to callers to ensure uniqueness of IDs. a `GtkColumnViewColumn` + line="958">a `GtkColumnViewColumn` whether this column should be resizable + line="959">whether this column should be resizable @@ -34039,10 +35850,9 @@ It is up to callers to ensure uniqueness of IDs. - Associates a sorter with the column. + line="770">Associates a sorter with the column. If @sorter is %NULL, the column will not let users change the sorting by clicking on its header. @@ -34060,7 +35870,7 @@ for setting up customizable sorting for [class@Gtk.ColumnView]. a `GtkColumnViewColumn` + line="772">a `GtkColumnViewColumn` allow-none="1"> the `GtkSorter` to associate with @column + line="773">the `GtkSorter` to associate with @column @@ -34077,10 +35887,9 @@ for setting up customizable sorting for [class@Gtk.ColumnView]. - Sets the title of this column. + line="716">Sets the title of this column. The title is displayed in the header of a `GtkColumnView` for this column and is therefore user-facing text that should @@ -34093,7 +35902,7 @@ be translated. a `GtkColumnViewColumn` + line="718">a `GtkColumnViewColumn` allow-none="1"> Title to use for this column + line="719">Title to use for this column @@ -34110,10 +35919,9 @@ be translated. - Sets whether this column should be visible in views. + line="827">Sets whether this column should be visible in views. @@ -34122,13 +35930,13 @@ be translated. a `GtkColumnViewColumn` + line="829">a `GtkColumnViewColumn` whether this column should be visible + line="830">whether this column should be visible @@ -34136,8 +35944,6 @@ be translated. - The `GtkColumnView` this column is a part of. @@ -34149,13 +35955,9 @@ be translated. setter="set_expand" getter="get_expand" default-value="FALSE"> - - Column gets share of extra width allocated to the view. + line="316">Column gets share of extra width allocated to the view. transfer-ownership="none" setter="set_factory" getter="get_factory"> - - Factory for populating list items. + line="254">Factory for populating list items. + +The factory must be for configuring [class@Gtk.ColumnViewCell] objects. setter="set_fixed_width" getter="get_fixed_width" default-value="-1"> - - If not -1, this is the width that the column is allocated, + line="326">If not -1, this is the width that the column is allocated, regardless of the size of its content. @@ -34193,13 +35989,9 @@ regardless of the size of its content. transfer-ownership="none" setter="set_header_menu" getter="get_header_menu"> - - Menu model used to create the context menu for the column header. + line="296">Menu model used to create the context menu for the column header. setter="set_id" getter="get_id" default-value="NULL"> - - An ID for the column. + line="337">An ID for the column. GTK is not currently using the ID for anything, but it can be used by applications when saving column view @@ -34230,13 +36018,9 @@ It is up to applications to ensure uniqueness of IDs. setter="set_resizable" getter="get_resizable" default-value="FALSE"> - - Whether this column is resizable. + line="306">Whether this column is resizable. transfer-ownership="none" setter="set_sorter" getter="get_sorter"> - - Sorter for sorting items according to this column. + line="276">Sorter for sorting items according to this column. setter="set_title" getter="get_title" default-value="NULL"> - - Title displayed in the header. + line="266">Title displayed in the header. setter="set_visible" getter="get_visible" default-value="TRUE"> - - Whether this column is visible. + line="286">Whether this column is visible. @@ -34301,8 +36073,7 @@ It is up to applications to ensure uniqueness of IDs. glib:type-struct="ColumnViewRowClass"> `GtkColumnViewRow` is used by [class@Gtk.ColumnView] to allow configuring -how rows are displayed. + line="26">Configures how rows are displayed in a [class@Gtk.ColumnView]. It is not used to set the widgets displayed in the individual cells. For that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. @@ -34313,19 +36084,19 @@ see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. Gets the accessible description of @self. + line="533">Gets the accessible description of @self. the accessible description + line="539">the accessible description a `GtkColumnViewRow` + line="535">a `GtkColumnViewRow` @@ -34336,19 +36107,19 @@ see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. Gets the accessible label of @self. + line="578">Gets the accessible label of @self. the accessible label + line="584">the accessible label a `GtkColumnViewRow` + line="580">a `GtkColumnViewRow` @@ -34357,23 +36128,22 @@ see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. - Checks if the row has been set to be activatable via + line="428">Checks if the row has been set to be activatable via gtk_column_view_row_set_activatable(). %TRUE if the row is activatable + line="435">%TRUE if the row is activatable a `GtkColumnViewRow` + line="430">a `GtkColumnViewRow` @@ -34382,23 +36152,22 @@ gtk_column_view_row_set_activatable(). c:identifier="gtk_column_view_row_get_focusable" glib:get-property="focusable" version="4.12"> - Checks if a row item has been set to be focusable via + line="480">Checks if a row item has been set to be focusable via gtk_column_view_row_set_focusable(). %TRUE if the row is focusable + line="487">%TRUE if the row is focusable a `GtkColumnViewRow` + line="482">a `GtkColumnViewRow` @@ -34407,24 +36176,23 @@ gtk_column_view_row_set_focusable(). c:identifier="gtk_column_view_row_get_item" glib:get-property="item" version="4.12"> - Gets the model item that associated with @self. + line="301">Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed + line="309">The item displayed a `GtkColumnViewRow` + line="303">a `GtkColumnViewRow` @@ -34433,24 +36201,23 @@ If @self is unbound, this function returns %NULL. c:identifier="gtk_column_view_row_get_position" glib:get-property="position" version="4.12"> - Gets the position in the model that @self currently displays. + line="324">Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this row + line="332">The position of this row a `GtkColumnViewRow` + line="326">a `GtkColumnViewRow` @@ -34459,10 +36226,9 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. c:identifier="gtk_column_view_row_get_selectable" glib:get-property="selectable" version="4.12"> - Checks if the row has been set to be selectable via + line="371">Checks if the row has been set to be selectable via gtk_column_view_row_set_selectable(). Do not confuse this function with [method@Gtk.ColumnViewRow.get_selected]. @@ -34470,14 +36236,14 @@ Do not confuse this function with [method@Gtk.ColumnViewRow.get_selected]. %TRUE if the row is selectable + line="380">%TRUE if the row is selectable a `GtkColumnViewRow` + line="373">a `GtkColumnViewRow` @@ -34486,10 +36252,9 @@ Do not confuse this function with [method@Gtk.ColumnViewRow.get_selected]. c:identifier="gtk_column_view_row_get_selected" glib:get-property="selected" version="4.12"> - Checks if the item is selected that this row corresponds to. + line="347">Checks if the item is selected that this row corresponds to. The selected state is maintained by the list widget and its model and cannot be set otherwise. @@ -34497,14 +36262,14 @@ and cannot be set otherwise. %TRUE if the item is selected. + line="356">%TRUE if the item is selected. a `GtkColumnViewRow` + line="349">a `GtkColumnViewRow` @@ -34515,7 +36280,7 @@ and cannot be set otherwise. version="4.12"> Sets the accessible description for the row, + line="551">Sets the accessible description for the row, which may be used by e.g. screen readers. @@ -34525,13 +36290,13 @@ which may be used by e.g. screen readers. a `GtkColumnViewRow` + line="553">a `GtkColumnViewRow` the description + line="554">the description @@ -34542,7 +36307,7 @@ which may be used by e.g. screen readers. version="4.12"> Sets the accessible label for the row, + line="596">Sets the accessible label for the row, which may be used by e.g. screen readers. @@ -34552,13 +36317,13 @@ which may be used by e.g. screen readers. a `GtkColumnViewRow` + line="598">a `GtkColumnViewRow` the label + line="599">the label @@ -34567,10 +36332,9 @@ which may be used by e.g. screen readers. c:identifier="gtk_column_view_row_set_activatable" glib:set-property="activatable" version="4.12"> - Sets @self to be activatable. + line="447">Sets @self to be activatable. If a row is activatable, double-clicking on the row, using the Return key or calling gtk_widget_activate() will activate @@ -34586,13 +36350,13 @@ By default, row are activatable. a `GtkColumnViewRow` + line="449">a `GtkColumnViewRow` if the row should be activatable + line="450">if the row should be activatable @@ -34601,10 +36365,9 @@ By default, row are activatable. c:identifier="gtk_column_view_row_set_focusable" glib:set-property="focusable" version="4.12"> - Sets @self to be focusable. + line="499">Sets @self to be focusable. If a row is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. @@ -34621,13 +36384,13 @@ By default, rows are focusable. a `GtkColumnViewRow` + line="501">a `GtkColumnViewRow` if the row should be focusable + line="502">if the row should be focusable @@ -34636,10 +36399,9 @@ By default, rows are focusable. c:identifier="gtk_column_view_row_set_selectable" glib:set-property="selectable" version="4.12"> - Sets @self to be selectable. + line="392">Sets @self to be selectable. If a row is selectable, clicking on the row or using the keyboard will try to select or unselect the row. Whether this succeeds is up to @@ -34658,13 +36420,13 @@ By default, rows are selectable. a `GtkColumnViewRow` + line="394">a `GtkColumnViewRow` if the row should be selectable + line="395">if the row should be selectable @@ -34676,13 +36438,9 @@ By default, rows are selectable. setter="set_accessible_description" getter="get_accessible_description" default-value="NULL"> - - The accessible description to set on the row. + line="172">The accessible description to set on the row. setter="set_accessible_label" getter="get_accessible_label" default-value="NULL"> - - The accessible label to set on the row. + line="184">The accessible label to set on the row. setter="set_activatable" getter="get_activatable" default-value="TRUE"> - - If the row can be activated by the user. + line="196">If the row can be activated by the user. setter="set_focusable" getter="get_focusable" default-value="TRUE"> - - If the row can be focused with the keyboard. + line="208">If the row can be focused with the keyboard. - The item for this row. + line="220">The item for this row. transfer-ownership="none" getter="get_position" default-value="4294967295"> - Position of the row. + line="232">Position of the row. setter="set_selectable" getter="get_selectable" default-value="TRUE"> - - If the row can be selected by the user. + line="244">If the row can be selected by the user. transfer-ownership="none" getter="get_selected" default-value="FALSE"> - If the item in the row is currently selected. + line="256">If the item in the row is currently selected. @@ -34802,8 +36538,7 @@ By default, rows are selectable. glib:type-struct="ColumnViewSorterClass"> `GtkColumnViewSorter` is a sorter implementation that -is geared towards the needs of `GtkColumnView`. + line="48">Sorts [class@Gtk.ColumnView] columns. The sorter returned by [method@Gtk.ColumnView.get_sorter] is a `GtkColumnViewSorter`. @@ -34840,7 +36575,7 @@ for (i = gtk_column_view_sorter_get_n_sort_columns (sorter) - 1; i >= 0; i--) version="4.10"> Returns the number of columns by which the sorter sorts. + line="522">Returns the number of columns by which the sorter sorts. If the sorter of the primary sort column does not determine a total order, then the secondary sorters are consulted to @@ -34852,14 +36587,14 @@ when the number of sort columns changes. the number of sort columns + line="535">the number of sort columns a `GtkColumnViewSorter` + line="524">a `GtkColumnViewSorter` @@ -34869,7 +36604,7 @@ when the number of sort columns changes. version="4.10"> Gets the @position'th sort column and its associated sort order. + line="547">Gets the @position'th sort column and its associated sort order. Use the [signal@Gtk.Sorter::changed] signal to get notified when sort columns change. @@ -34877,20 +36612,20 @@ when sort columns change. the @positions sort column + line="559">the @positions sort column a `GtkColumnViewSorter` + line="549">a `GtkColumnViewSorter` the position of the sort column to retrieve (0 for the + line="550">the position of the sort column to retrieve (0 for the primary sort column) @@ -34900,7 +36635,7 @@ when sort columns change. transfer-ownership="full"> return location for the sort order + line="552">return location for the sort order @@ -34911,7 +36646,7 @@ when sort columns change. version="4.10"> Returns the primary sort column. + line="458">Returns the primary sort column. The primary sort column is the one that displays the triangle in a column view header. @@ -34919,14 +36654,14 @@ in a column view header. the primary sort column + line="467">the primary sort column a `GtkColumnViewSorter` + line="460">a `GtkColumnViewSorter` @@ -34937,7 +36672,7 @@ in a column view header. version="4.10"> Returns the primary sort order. + line="488">Returns the primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards @@ -34949,14 +36684,14 @@ If there is no primary sort column, then this function returns the primary sort order + line="501">the primary sort order a `GtkColumnViewSorter` + line="490">a `GtkColumnViewSorter` @@ -34965,11 +36700,9 @@ If there is no primary sort column, then this function returns version="4.10" transfer-ownership="none" getter="get_primary_sort_column"> - The primary sort column. + line="215">The primary sort column. The primary sort column is the one that displays the triangle in a column view header. @@ -34980,11 +36713,9 @@ in a column view header. transfer-ownership="none" getter="get_primary_sort_order" default-value="GTK_SORT_ASCENDING"> - The primary sort order. + line="230">The primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards @@ -35014,7 +36745,10 @@ or downwards. line="47">A `GtkComboBox` is a widget that allows the user to choose from a list of valid choices. -![An example GtkComboBox](combo-box.png) +<picture> + <source srcset="combo-box-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkComboBox" src="combo-box.png"> +</picture> The `GtkComboBox` displays the selected choice; when activated, the `GtkComboBox` displays a popup which allows the user to make a new choice. @@ -35070,7 +36804,7 @@ node with name arrow. ## Accessibility -`GtkComboBox` uses the %GTK_ACCESSIBLE_ROLE_COMBO_BOX role. +`GtkComboBox` uses the [enum@Gtk.AccessibleRole.combo_box] role. Use [class@Gtk.DropDown] instead @@ -35084,13 +36818,13 @@ node with name arrow. deprecated-version="4.10"> Creates a new empty `GtkComboBox`. + line="1844">Creates a new empty `GtkComboBox`. Use [class@Gtk.DropDown] A new `GtkComboBox` + line="1849">A new `GtkComboBox` @@ -35100,7 +36834,7 @@ node with name arrow. deprecated-version="4.10"> Creates a new empty `GtkComboBox` with an entry. + line="1859">Creates a new empty `GtkComboBox` with an entry. In order to use a combo box with entry, you need to tell it which column of the model contains the text for the entry @@ -35110,7 +36844,7 @@ by calling [method@Gtk.ComboBox.set_entry_text_column]. A new `GtkComboBox` + line="1868">A new `GtkComboBox` @@ -35120,20 +36854,20 @@ by calling [method@Gtk.ComboBox.set_entry_text_column]. deprecated-version="4.10"> Creates a new `GtkComboBox` with a model. + line="1878">Creates a new `GtkComboBox` with a model. Use [class@Gtk.DropDown] A new `GtkComboBox` + line="1884">A new `GtkComboBox` a `GtkTreeModel` + line="1880">a `GtkTreeModel` @@ -35144,7 +36878,7 @@ by calling [method@Gtk.ComboBox.set_entry_text_column]. deprecated-version="4.10"> Creates a new empty `GtkComboBox` with an entry and a model. + line="1900">Creates a new empty `GtkComboBox` with an entry and a model. See also [ctor@Gtk.ComboBox.new_with_entry]. Use [class@Gtk.DropDown] @@ -35152,14 +36886,14 @@ See also [ctor@Gtk.ComboBox.new_with_entry]. A new `GtkComboBox` + line="1908">A new `GtkComboBox` A `GtkTreeModel` + line="1902">A `GtkTreeModel` @@ -35176,6 +36910,9 @@ See also [ctor@Gtk.ComboBox.new_with_entry]. + Signal is emitted when the active item is changed. @@ -35187,6 +36924,10 @@ See also [ctor@Gtk.ComboBox.new_with_entry]. + Signal which allows you to change how the text + displayed in a combo box’s entry is displayed. @@ -35207,7 +36948,7 @@ See also [ctor@Gtk.ComboBox.new_with_entry]. deprecated-version="4.10"> Returns the index of the currently active item. + line="1921">Returns the index of the currently active item. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this function returns @@ -35218,7 +36959,7 @@ an immediate child of the root of the tree, this function returns An integer which is the index of the currently active item, + line="1932">An integer which is the index of the currently active item, or -1 if there’s no active item @@ -35226,7 +36967,7 @@ an immediate child of the root of the tree, this function returns A `GtkComboBox` + line="1923">A `GtkComboBox` @@ -35236,10 +36977,9 @@ an immediate child of the root of the tree, this function returns glib:get-property="active-id" deprecated="1" deprecated-version="4.10"> - Returns the ID of the active row of @combo_box. + line="2892">Returns the ID of the active row of @combo_box. This value is taken from the active row and the column specified by the [property@Gtk.ComboBox:id-column] property of @combo_box @@ -35257,14 +36997,14 @@ ID value, then %NULL is returned. the ID of the active row + line="2910">the ID of the active row a `GtkComboBox` + line="2894">a `GtkComboBox` @@ -35275,7 +37015,7 @@ ID value, then %NULL is returned. deprecated-version="4.10"> Sets @iter to point to the currently active item. + line="2055">Sets @iter to point to the currently active item. If no item is active, @iter is left unchanged. Use [class@Gtk.DropDown] @@ -35283,14 +37023,14 @@ If no item is active, @iter is left unchanged. %TRUE if @iter was set, %FALSE otherwise + line="2064">%TRUE if @iter was set, %FALSE otherwise A `GtkComboBox` + line="2057">A `GtkComboBox` transfer-ownership="none"> A `GtkTreeIter` + line="2058">A `GtkTreeIter` @@ -35309,18 +37049,16 @@ If no item is active, @iter is left unchanged. glib:get-property="button-sensitivity" deprecated="1" deprecated-version="4.10"> - Returns whether the combo box sets the dropdown button + line="2674">Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. Use [class@Gtk.DropDown] %GTK_SENSITIVITY_ON if the dropdown button + line="2681">%GTK_SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, %GTK_SENSITIVITY_OFF if the button is always insensitive or %GTK_SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to @@ -35331,7 +37069,7 @@ sensitive or not when there are no items in the model. a `GtkComboBox` + line="2676">a `GtkComboBox` @@ -35341,23 +37079,22 @@ sensitive or not when there are no items in the model. glib:get-property="child" deprecated="1" deprecated-version="4.10"> - Gets the child widget of @combo_box. + line="3052">Gets the child widget of @combo_box. Use [class@Gtk.DropDown] the child widget of @combo_box + line="3058">the child widget of @combo_box a `GtkComboBox` + line="3054">a `GtkComboBox` @@ -35369,21 +37106,21 @@ sensitive or not when there are no items in the model. deprecated-version="4.10"> Returns the column which @combo_box is using to get the strings + line="2762">Returns the column which @combo_box is using to get the strings from to display in the internal entry. Use [class@Gtk.DropDown] A column in the data source model of @combo_box. + line="2769">A column in the data source model of @combo_box. A `GtkComboBox` + line="2764">A `GtkComboBox` @@ -35393,23 +37130,22 @@ from to display in the internal entry. glib:get-property="has-entry" deprecated="1" deprecated-version="4.10"> - Returns whether the combo box has an entry. + line="2699">Returns whether the combo box has an entry. Use [class@Gtk.DropDown] whether there is an entry in @combo_box. + line="2705">whether there is an entry in @combo_box. a `GtkComboBox` + line="2701">a `GtkComboBox` @@ -35419,24 +37155,23 @@ from to display in the internal entry. glib:get-property="id-column" deprecated="1" deprecated-version="4.10"> - Returns the column which @combo_box is using to get string IDs + line="2871">Returns the column which @combo_box is using to get string IDs for values from. Use [class@Gtk.DropDown] A column in the data source model of @combo_box. + line="2878">A column in the data source model of @combo_box. A `GtkComboBox` + line="2873">A `GtkComboBox` @@ -35446,16 +37181,15 @@ for values from. glib:get-property="model" deprecated="1" deprecated-version="4.10"> - Returns the `GtkTreeModel` of @combo_box. + line="2182">Returns the `GtkTreeModel` of @combo_box. Use [class@Gtk.DropDown] A `GtkTreeModel` which was passed + line="2188">A `GtkTreeModel` which was passed during construction. @@ -35463,7 +37197,7 @@ for values from. A `GtkComboBox` + line="2184">A `GtkComboBox` @@ -35473,24 +37207,22 @@ for values from. glib:get-property="popup-fixed-width" deprecated="1" deprecated-version="4.10"> - Gets whether the popup uses a fixed width. + line="2568">Gets whether the popup uses a fixed width. Use [class@Gtk.DropDown] %TRUE if the popup uses a fixed width + line="2574">%TRUE if the popup uses a fixed width a `GtkComboBox` + line="2570">a `GtkComboBox` @@ -35502,13 +37234,13 @@ for values from. deprecated-version="4.10"> Returns the current row separator function. + line="2588">Returns the current row separator function. Use [class@Gtk.DropDown] the current row separator function. + line="2594">the current row separator function. @@ -35516,7 +37248,7 @@ for values from. a `GtkComboBox` + line="2590">a `GtkComboBox` @@ -35527,7 +37259,7 @@ for values from. deprecated-version="4.10"> Hides the menu or dropdown list of @combo_box. + line="1438">Hides the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. @@ -35540,7 +37272,7 @@ applications should have little use for it. a `GtkComboBox` + line="1440">a `GtkComboBox` @@ -35551,7 +37283,7 @@ applications should have little use for it. deprecated-version="4.10"> Pops up the menu or dropdown list of @combo_box. + line="1362">Pops up the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. @@ -35566,7 +37298,7 @@ Before calling this, @combo_box must be mapped, or nothing will happen. a `GtkComboBox` + line="1364">a `GtkComboBox` @@ -35577,7 +37309,7 @@ Before calling this, @combo_box must be mapped, or nothing will happen. deprecated-version="4.10"> Pops up the menu of @combo_box. + line="1384">Pops up the menu of @combo_box. Note that currently this does not do anything with the device, as it was previously only used for list-mode combo boxes, and those were removed @@ -35592,13 +37324,13 @@ back later. a `GtkComboBox` + line="1386">a `GtkComboBox` a `GdkDevice` + line="1387">a `GdkDevice` @@ -35608,10 +37340,9 @@ back later. glib:set-property="active" deprecated="1" deprecated-version="4.10"> - Sets the active item of @combo_box to be the item at @index. + line="1959">Sets the active item of @combo_box to be the item at @index. Use [class@Gtk.DropDown] @@ -35621,13 +37352,13 @@ back later. a `GtkComboBox` + line="1961">a `GtkComboBox` An index in the model passed during construction, + line="1962">An index in the model passed during construction, or -1 to have no active item @@ -35638,10 +37369,9 @@ back later. glib:set-property="active-id" deprecated="1" deprecated-version="4.10"> - Changes the active row of @combo_box to the one that has an ID equal to + line="2948">Changes the active row of @combo_box to the one that has an ID equal to @active_id. If @active_id is %NULL, the active row is unset. Rows having @@ -35655,7 +37385,7 @@ and returns %FALSE. %TRUE if a row with a matching ID was found. If a %NULL + line="2963">%TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE. @@ -35664,7 +37394,7 @@ and returns %FALSE. a `GtkComboBox` + line="2950">a `GtkComboBox` allow-none="1"> the ID of the row to select + line="2951">the ID of the row to select @@ -35684,7 +37414,7 @@ and returns %FALSE. deprecated-version="4.10"> Sets the current active item to be the one referenced by @iter. + line="2088">Sets the current active item to be the one referenced by @iter. If @iter is %NULL, the active item is unset. Use [class@Gtk.DropDown] @@ -35696,7 +37426,7 @@ If @iter is %NULL, the active item is unset. A `GtkComboBox` + line="2090">A `GtkComboBox` allow-none="1"> The `GtkTreeIter` + line="2091">The `GtkTreeIter` @@ -35715,11 +37445,9 @@ If @iter is %NULL, the active item is unset. glib:set-property="button-sensitivity" deprecated="1" deprecated-version="4.10"> - Sets whether the dropdown button of the combo box should update + line="2647">Sets whether the dropdown button of the combo box should update its sensitivity depending on the model contents. Use [class@Gtk.DropDown] @@ -35730,13 +37458,13 @@ its sensitivity depending on the model contents. a `GtkComboBox` + line="2649">a `GtkComboBox` specify the sensitivity of the dropdown button + line="2650">specify the sensitivity of the dropdown button @@ -35746,10 +37474,9 @@ its sensitivity depending on the model contents. glib:set-property="child" deprecated="1" deprecated-version="4.10"> - Sets the child widget of @combo_box. + line="3025">Sets the child widget of @combo_box. Use [class@Gtk.DropDown] @@ -35759,7 +37486,7 @@ its sensitivity depending on the model contents. a `GtkComboBox` + line="3027">a `GtkComboBox` allow-none="1"> the child widget + line="3028">the child widget @@ -35780,7 +37507,7 @@ its sensitivity depending on the model contents. deprecated-version="4.10"> Sets the model column which @combo_box should use to get strings + line="2718">Sets the model column which @combo_box should use to get strings from to be @text_column. For this column no separate @@ -35800,13 +37527,13 @@ This is only relevant if @combo_box has been created with A `GtkComboBox` + line="2720">A `GtkComboBox` A column in @model to get the strings from for + line="2721">A column in @model to get the strings from for the internal entry @@ -35817,10 +37544,9 @@ This is only relevant if @combo_box has been created with glib:set-property="id-column" deprecated="1" deprecated-version="4.10"> - Sets the model column which @combo_box should use to get string IDs + line="2838">Sets the model column which @combo_box should use to get string IDs for values from. The column @id_column in the model of @combo_box must be of type @@ -35834,13 +37560,13 @@ The column @id_column in the model of @combo_box must be of type A `GtkComboBox` + line="2840">A `GtkComboBox` A column in @model to get string IDs for values from + line="2841">A column in @model to get string IDs for values from @@ -35850,10 +37576,9 @@ The column @id_column in the model of @combo_box must be of type glib:set-property="model" deprecated="1" deprecated-version="4.10"> - Sets the model used by @combo_box to be @model. + line="2114">Sets the model used by @combo_box to be @model. Will unset a previously set model (if applicable). If model is %NULL, then it will unset the model. @@ -35870,7 +37595,7 @@ cell renderers for the new model. A `GtkComboBox` + line="2116">A `GtkComboBox` allow-none="1"> A `GtkTreeModel` + line="2117">A `GtkTreeModel` @@ -35889,11 +37614,9 @@ cell renderers for the new model. glib:set-property="popup-fixed-width" deprecated="1" deprecated-version="4.10"> - Specifies whether the popup’s width should be a fixed width. + line="2540">Specifies whether the popup’s width should be a fixed width. If @fixed is %TRUE, the popup's width is set to match the allocated width of the combo box. @@ -35906,13 +37629,13 @@ allocated width of the combo box. a `GtkComboBox` + line="2542">a `GtkComboBox` whether to use a fixed popup width + line="2543">whether to use a fixed popup width @@ -35923,7 +37646,7 @@ allocated width of the combo box. deprecated-version="4.10"> Sets the row separator function, which is used to determine + line="2608">Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. @@ -35937,7 +37660,7 @@ This is the default value. a `GtkComboBox` + line="2610">a `GtkComboBox` destroy="2"> a `GtkTreeViewRowSeparatorFunc` + line="2611">a `GtkTreeViewRowSeparatorFunc` @@ -35959,7 +37682,7 @@ This is the default value. allow-none="1"> user data to pass to @func + line="2612">user data to pass to @func scope="async"> destroy notifier for @data + line="2613">destroy notifier for @data @@ -35980,13 +37703,9 @@ This is the default value. setter="set_active" getter="get_active" default-value="-1"> - - The item which is currently active. + line="670">The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value @@ -36000,13 +37719,9 @@ immediate child of the root of the tree, this property has the value setter="set_active_id" getter="get_active_id" default-value="NULL"> - - The value of the ID column of the active row. + line="764">The value of the ID column of the active row. - - Whether the dropdown button is sensitive when + line="714">Whether the dropdown button is sensitive when the model is empty. @@ -36030,13 +37741,9 @@ the model is empty. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="787">The child widget. setter="set_entry_text_column" getter="get_entry_text_column" default-value="-1"> - - The model column to associate with strings from the entry. + line="738">The model column to associate with strings from the entry. This is property only relevant if the combo was created with [property@Gtk.ComboBox:has-entry] is %TRUE. @@ -36063,11 +37766,9 @@ This is property only relevant if the combo was created with transfer-ownership="none" getter="get_has_entry" default-value="FALSE"> - Whether the combo box has an entry. + line="727">Whether the combo box has an entry. The `has-frame` property controls whether a frame is drawn around the entry. + line="688">The `has-frame` property controls whether a frame is drawn around the entry. - - The model column that provides string IDs for the values + line="752">The model column that provides string IDs for the values in the model, if != -1. @@ -36100,13 +37797,9 @@ in the model, if != -1. transfer-ownership="none" setter="set_model" getter="get_model"> - - The model from which the combo box takes its values. + line="658">The model from which the combo box takes its values. setter="set_popup_fixed_width" getter="get_popup_fixed_width" default-value="TRUE"> - - Whether the popup's width should be a fixed width matching the + line="775">Whether the popup's width should be a fixed width matching the allocated width of the combo box. @@ -36130,7 +37819,7 @@ allocated width of the combo box. default-value="FALSE"> Whether the combo boxes dropdown is popped up. + line="699">Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to notify::popup-shown. @@ -36142,7 +37831,7 @@ it allows you to connect to notify::popup-shown. Emitted to when the combo box is activated. + line="431">Emitted to when the combo box is activated. The `::activate` signal on `GtkComboBox` is an action signal and emitting it causes the combo box to pop up its dropdown. @@ -36153,7 +37842,7 @@ emitting it causes the combo box to pop up its dropdown. Emitted when the active item is changed. + line="453">Emitted when the active item is changed. The can be due to the user selecting a different item from the list, or due to a call to [method@Gtk.ComboBox.set_active_iter]. It will @@ -36165,7 +37854,7 @@ also be emitted while typing into the entry of a combo box with an entry. Emitted to allow changing how the text in a combo box's entry is displayed. + line="530">Emitted to allow changing how the text in a combo box's entry is displayed. See [property@Gtk.ComboBox:has-entry]. @@ -36199,7 +37888,7 @@ format_entry_text_callback (GtkComboBox *combo, a newly allocated string representing @path + line="568">a newly allocated string representing @path for the current `GtkComboBox` model. @@ -36207,7 +37896,7 @@ format_entry_text_callback (GtkComboBox *combo, the [struct@Gtk.TreePath] string from the combo box's current model + line="533">the [struct@Gtk.TreePath] string from the combo box's current model to format text for @@ -36216,7 +37905,7 @@ format_entry_text_callback (GtkComboBox *combo, Emitted to move the active selection. + line="472">Emitted to move the active selection. This is an [keybinding signal](class.SignalAction.html). @@ -36226,7 +37915,7 @@ This is an [keybinding signal](class.SignalAction.html). a `GtkScrollType` + line="475">a `GtkScrollType` @@ -36234,19 +37923,22 @@ This is an [keybinding signal](class.SignalAction.html). Emitted to popdown the combo box list. + line="509">Emitted to popdown the combo box list. This is an [keybinding signal](class.SignalAction.html). The default bindings for this signal are Alt+Up and Escape. + whether the combo box was popped down Emitted to popup the combo box list. + line="491">Emitted to popup the combo box list. This is an [keybinding signal](class.SignalAction.html). @@ -36267,6 +37959,9 @@ The default binding for this signal is Alt+Down. + Signal is emitted when the active item is changed. @@ -36280,6 +37975,10 @@ The default binding for this signal is Alt+Down. + Signal which allows you to change how the text + displayed in a combo box’s entry is displayed. @@ -36327,7 +38026,10 @@ The default binding for this signal is Alt+Down. line="33">A `GtkComboBoxText` is a simple variant of `GtkComboBox` for text-only use cases. -![An example GtkComboBoxText](combo-box-text.png) +<picture> + <source srcset="combo-box-text-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkComboBoxText" src="combo-box-text.png"> +</picture> `GtkComboBoxText` hides the model-view complexity of `GtkComboBox`. @@ -36392,14 +38094,14 @@ children, and the .linked class to the node of its internal box. deprecated-version="4.10"> Creates a new `GtkComboBoxText`. + line="355">Creates a new `GtkComboBoxText`. Use [class@Gtk.DropDown] A new `GtkComboBoxText` + line="360">A new `GtkComboBoxText` @@ -36409,14 +38111,14 @@ children, and the .linked class to the node of its internal box. deprecated-version="4.10"> Creates a new `GtkComboBoxText` with an entry. + line="371">Creates a new `GtkComboBoxText` with an entry. Use [class@Gtk.DropDown] a new `GtkComboBoxText` + line="376">a new `GtkComboBoxText` @@ -36426,7 +38128,7 @@ children, and the .linked class to the node of its internal box. deprecated-version="4.10"> Appends @text to the list of strings stored in @combo_box. + line="449">Appends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. @@ -36442,7 +38144,7 @@ with a position of -1. A `GtkComboBoxText` + line="451">A `GtkComboBoxText` allow-none="1"> a string ID for this value + line="452">a string ID for this value A string + line="453">A string @@ -36468,7 +38170,7 @@ with a position of -1. deprecated-version="4.10"> Appends @text to the list of strings stored in @combo_box. + line="388">Appends @text to the list of strings stored in @combo_box. This is the same as calling [method@Gtk.ComboBoxText.insert_text] with a position of -1. @@ -36482,13 +38184,13 @@ with a position of -1. A `GtkComboBoxText` + line="390">A `GtkComboBoxText` A string + line="391">A string @@ -36499,7 +38201,7 @@ with a position of -1. deprecated-version="4.10"> Returns the currently active string in @combo_box. + line="603">Returns the currently active string in @combo_box. If no row is currently selected, %NULL is returned. If @combo_box contains an entry, this function will @@ -36511,7 +38213,7 @@ be an item from the list). a newly allocated + line="614">a newly allocated string containing the currently active text. Must be freed with g_free(). @@ -36520,7 +38222,7 @@ be an item from the list). A `GtkComboBoxText` + line="605">A `GtkComboBoxText` @@ -36531,7 +38233,7 @@ be an item from the list). deprecated-version="4.10"> Inserts @text at @position in the list of strings stored in @combo_box. + line="496">Inserts @text at @position in the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. See [property@Gtk.ComboBox:id-column]. @@ -36547,13 +38249,13 @@ If @position is negative then @text is appended. A `GtkComboBoxText` + line="498">A `GtkComboBoxText` An index to insert @text + line="499">An index to insert @text allow-none="1"> a string ID for this value + line="500">a string ID for this value A string to display + line="501">A string to display @@ -36579,7 +38281,7 @@ If @position is negative then @text is appended. deprecated-version="4.10"> Inserts @text at @position in the list of strings stored in @combo_box. + line="426">Inserts @text at @position in the list of strings stored in @combo_box. If @position is negative then @text is appended. @@ -36595,19 +38297,19 @@ with a %NULL ID string. A `GtkComboBoxText` + line="428">A `GtkComboBoxText` An index to insert @text + line="429">An index to insert @text A string + line="430">A string @@ -36618,7 +38320,7 @@ with a %NULL ID string. deprecated-version="4.10"> Prepends @text to the list of strings stored in @combo_box. + line="472">Prepends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. @@ -36634,7 +38336,7 @@ with a position of 0. A `GtkComboBox` + line="474">A `GtkComboBox` allow-none="1"> a string ID for this value + line="475">a string ID for this value a string + line="476">a string @@ -36660,7 +38362,7 @@ with a position of 0. deprecated-version="4.10"> Prepends @text to the list of strings stored in @combo_box. + line="407">Prepends @text to the list of strings stored in @combo_box. This is the same as calling [method@Gtk.ComboBoxText.insert_text] with a position of 0. @@ -36674,13 +38376,13 @@ with a position of 0. A `GtkComboBox` + line="409">A `GtkComboBox` A string + line="410">A string @@ -36691,7 +38393,7 @@ with a position of 0. deprecated-version="4.10"> Removes the string at @position from @combo_box. + line="556">Removes the string at @position from @combo_box. Use [class@Gtk.DropDown] @@ -36702,13 +38404,13 @@ with a position of 0. A `GtkComboBox` + line="558">A `GtkComboBox` Index of the item to remove + line="559">Index of the item to remove @@ -36719,7 +38421,7 @@ with a position of 0. deprecated-version="4.10"> Removes all the text entries from the combo box. + line="584">Removes all the text entries from the combo box. Use [class@Gtk.DropDown] @@ -36730,7 +38432,7 @@ with a position of 0. A `GtkComboBoxText` + line="586">A `GtkComboBoxText` @@ -36745,32 +38447,32 @@ with a position of 0. glib:fundamental="1"> A constant value in a `GtkExpression`. + line="809">A constant value in a `GtkExpression`. Creates a `GtkExpression` that evaluates to the + line="865">Creates a `GtkExpression` that evaluates to the object given by the arguments. a new `GtkExpression` + line="873">a new `GtkExpression` The type of the object + line="867">The type of the object arguments to create the object from + line="868">arguments to create the object from @@ -36779,19 +38481,19 @@ object given by the arguments. c:identifier="gtk_constant_expression_new_for_value"> Creates an expression that always evaluates to the given `value`. + line="906">Creates an expression that always evaluates to the given `value`. a new `GtkExpression` + line="912">a new `GtkExpression` a `GValue` + line="908">a `GValue` @@ -36800,19 +38502,19 @@ object given by the arguments. c:identifier="gtk_constant_expression_get_value"> Gets the value that a constant expression evaluates to. + line="931">Gets the value that a constant expression evaluates to. the value + line="937">the value a constant `GtkExpression` + line="933">a constant `GtkExpression` @@ -36827,7 +38529,7 @@ object given by the arguments. glib:type-struct="ConstraintClass"> `GtkConstraint` describes a constraint between attributes of two widgets, + line="20">Describes a constraint between attributes of two widgets, expressed as a linear equation. The typical equation for a constraint is: @@ -36964,7 +38666,6 @@ attribute on a target and a constant value. - Retrieves the constant factor added to the source attributes' value. @@ -36987,7 +38688,6 @@ attribute on a target and a constant value. - Retrieves the multiplication factor applied to the source @@ -37011,7 +38711,6 @@ attribute's value. - The order relation between the terms of the constraint. @@ -37034,7 +38733,6 @@ attribute's value. - Retrieves the [iface@Gtk.ConstraintTarget] used as the source for the @@ -37061,8 +38759,6 @@ the widget using the [class@Gtk.ConstraintLayout] as the source. - Retrieves the attribute of the source to be read by the constraint. @@ -37085,7 +38781,6 @@ the widget using the [class@Gtk.ConstraintLayout] as the source. - Retrieves the strength of the constraint. @@ -37108,7 +38803,6 @@ the widget using the [class@Gtk.ConstraintLayout] as the source. - Retrieves the [iface@Gtk.ConstraintTarget] used as the target for @@ -37135,8 +38829,6 @@ the widget using the [class@Gtk.ConstraintLayout] as the target. - Retrieves the attribute of the target to be set by the constraint. @@ -37225,8 +38917,6 @@ constraint layout. transfer-ownership="none" getter="get_constant" default-value="0.000000"> - The constant value to be added to the [property@Gtk.Constraint:source-attribute]. @@ -37238,8 +38928,6 @@ constraint layout. transfer-ownership="none" getter="get_multiplier" default-value="1.000000"> - The multiplication factor to be applied to @@ -37252,8 +38940,6 @@ the [property@Gtk.Constraint:source-attribute]. transfer-ownership="none" getter="get_relation" default-value="GTK_CONSTRAINT_RELATION_EQ"> - The order relation between the terms of the constraint. @@ -37264,8 +38950,6 @@ the [property@Gtk.Constraint:source-attribute]. construct-only="1" transfer-ownership="none" getter="get_source"> - The source of the constraint. @@ -37281,8 +38965,6 @@ property of the source. transfer-ownership="none" getter="get_source_attribute" default-value="GTK_CONSTRAINT_ATTRIBUTE_NONE"> - The attribute of the [property@Gtk.Constraint:source] read by the @@ -37295,8 +38977,6 @@ constraint. transfer-ownership="none" getter="get_strength" default-value="1001001000"> - The strength of the constraint. @@ -37311,8 +38991,6 @@ value. construct-only="1" transfer-ownership="none" getter="get_target"> - The target of the constraint. @@ -37328,8 +39006,6 @@ property of the source widget. transfer-ownership="none" getter="get_target_attribute" default-value="GTK_CONSTRAINT_ATTRIBUTE_NONE"> - The attribute of the [property@Gtk.Constraint:target] set by the constraint. @@ -37342,7 +39018,7 @@ property of the source widget. c:type="GtkConstraintAttribute"> The widget attributes that can be used when creating a [class@Constraint]. + line="1158">The widget attributes that can be used when creating a [class@Constraint]. glib:name="GTK_CONSTRAINT_ATTRIBUTE_NONE"> No attribute, used for constant + line="1160">No attribute, used for constant relations glib:name="GTK_CONSTRAINT_ATTRIBUTE_LEFT"> The left edge of a widget, regardless of + line="1162">The left edge of a widget, regardless of text direction glib:name="GTK_CONSTRAINT_ATTRIBUTE_RIGHT"> The right edge of a widget, regardless + line="1164">The right edge of a widget, regardless of text direction glib:name="GTK_CONSTRAINT_ATTRIBUTE_TOP"> The top edge of a widget + line="1166">The top edge of a widget glib:name="GTK_CONSTRAINT_ATTRIBUTE_BOTTOM"> The bottom edge of a widget + line="1167">The bottom edge of a widget glib:name="GTK_CONSTRAINT_ATTRIBUTE_START"> The leading edge of a widget, depending + line="1168">The leading edge of a widget, depending on text direction; equivalent to %GTK_CONSTRAINT_ATTRIBUTE_LEFT for LTR languages, and %GTK_CONSTRAINT_ATTRIBUTE_RIGHT for RTL ones @@ -37409,7 +39085,7 @@ property of the source widget. glib:name="GTK_CONSTRAINT_ATTRIBUTE_END"> The trailing edge of a widget, depending + line="1171">The trailing edge of a widget, depending on text direction; equivalent to %GTK_CONSTRAINT_ATTRIBUTE_RIGHT for LTR languages, and %GTK_CONSTRAINT_ATTRIBUTE_LEFT for RTL ones @@ -37420,7 +39096,7 @@ property of the source widget. glib:name="GTK_CONSTRAINT_ATTRIBUTE_WIDTH"> The width of a widget + line="1174">The width of a widget glib:name="GTK_CONSTRAINT_ATTRIBUTE_HEIGHT"> The height of a widget + line="1175">The height of a widget glib:name="GTK_CONSTRAINT_ATTRIBUTE_CENTER_X"> The center of a widget, on the + line="1176">The center of a widget, on the horizontal axis glib:name="GTK_CONSTRAINT_ATTRIBUTE_CENTER_Y"> The center of a widget, on the + line="1178">The center of a widget, on the vertical axis glib:name="GTK_CONSTRAINT_ATTRIBUTE_BASELINE"> The baseline of a widget + line="1180">The baseline of a widget glib:type-struct="ConstraintGuideClass"> A `GtkConstraintGuide` is an invisible layout element in a -`GtkConstraintLayout`. + line="20">An invisible layout element in a `GtkConstraintLayout`. The `GtkConstraintLayout` treats guides like widgets. They can be used as the source or target of a `GtkConstraint`. @@ -37495,12 +39170,12 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. Creates a new `GtkConstraintGuide` object. + line="438">Creates a new `GtkConstraintGuide` object. a new `GtkConstraintGuide` object. + line="443">a new `GtkConstraintGuide` object. @@ -37508,7 +39183,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. c:identifier="gtk_constraint_guide_get_max_size"> Gets the maximum size of @guide. + line="586">Gets the maximum size of @guide. @@ -37517,7 +39192,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. a `GtkConstraintGuide` object + line="588">a `GtkConstraintGuide` object allow-none="1"> return location for the maximum width + line="589">return location for the maximum width allow-none="1"> return location for the maximum height + line="590">return location for the maximum height @@ -37548,7 +39223,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. c:identifier="gtk_constraint_guide_get_min_size"> Gets the minimum size of @guide. + line="482">Gets the minimum size of @guide. @@ -37557,7 +39232,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. a `GtkConstraintGuide` object + line="484">a `GtkConstraintGuide` object allow-none="1"> return location for the minimum width + line="485">return location for the minimum width allow-none="1"> return location for the minimum height + line="486">return location for the minimum height @@ -37587,22 +39262,21 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. - Retrieves the name set using gtk_constraint_guide_set_name(). + line="607">Retrieves the name set using gtk_constraint_guide_set_name(). the name of the guide + line="613">the name of the guide a `GtkConstraintGuide` + line="609">a `GtkConstraintGuide` @@ -37611,7 +39285,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. c:identifier="gtk_constraint_guide_get_nat_size"> Gets the natural size of @guide. + line="534">Gets the natural size of @guide. @@ -37620,7 +39294,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. a `GtkConstraintGuide` object + line="536">a `GtkConstraintGuide` object allow-none="1"> return location for the natural width + line="537">return location for the natural width allow-none="1"> return location for the natural height + line="538">return location for the natural height @@ -37650,22 +39324,21 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. - Retrieves the strength set using gtk_constraint_guide_set_strength(). + line="643">Retrieves the strength set using gtk_constraint_guide_set_strength(). the strength of the constraint on the natural size + line="649">the strength of the constraint on the natural size a `GtkConstraintGuide` + line="645">a `GtkConstraintGuide` @@ -37674,7 +39347,7 @@ Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. c:identifier="gtk_constraint_guide_set_max_size"> Sets the maximum size of @guide. + line="555">Sets the maximum size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. @@ -37686,19 +39359,19 @@ the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object + line="557">a `GtkConstraintGuide` object the new maximum width, or -1 to not change it + line="558">the new maximum width, or -1 to not change it the new maximum height, or -1 to not change it + line="559">the new maximum height, or -1 to not change it @@ -37707,7 +39380,7 @@ the constraints will be updated to reflect the new size. c:identifier="gtk_constraint_guide_set_min_size"> Sets the minimum size of @guide. + line="451">Sets the minimum size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. @@ -37719,19 +39392,19 @@ the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object + line="453">a `GtkConstraintGuide` object the new minimum width, or -1 to not change it + line="454">the new minimum width, or -1 to not change it the new minimum height, or -1 to not change it + line="455">the new minimum height, or -1 to not change it @@ -37739,10 +39412,9 @@ the constraints will be updated to reflect the new size. - Sets a name for the given `GtkConstraintGuide`. + line="623">Sets a name for the given `GtkConstraintGuide`. The name is useful for debugging purposes. @@ -37753,7 +39425,7 @@ The name is useful for debugging purposes. a `GtkConstraintGuide` + line="625">a `GtkConstraintGuide` allow-none="1"> a name for the @guide + line="626">a name for the @guide @@ -37771,7 +39443,7 @@ The name is useful for debugging purposes. c:identifier="gtk_constraint_guide_set_nat_size"> Sets the natural size of @guide. + line="503">Sets the natural size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. @@ -37783,19 +39455,19 @@ the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object + line="505">a `GtkConstraintGuide` object the new natural width, or -1 to not change it + line="506">the new natural width, or -1 to not change it the new natural height, or -1 to not change it + line="507">the new natural height, or -1 to not change it @@ -37803,10 +39475,9 @@ the constraints will be updated to reflect the new size. - Sets the strength of the constraint on the natural size of the + line="660">Sets the strength of the constraint on the natural size of the given `GtkConstraintGuide`. @@ -37816,13 +39487,13 @@ given `GtkConstraintGuide`. a `GtkConstraintGuide` + line="662">a `GtkConstraintGuide` the strength of the constraint + line="663">the strength of the constraint @@ -37833,7 +39504,7 @@ given `GtkConstraintGuide`. default-value="2147483647"> The maximum height of the guide. + line="401">The maximum height of the guide. default-value="2147483647"> The maximum width of the guide. + line="390">The maximum width of the guide. default-value="0"> The minimum height of the guide. + line="357">The minimum height of the guide. default-value="0"> The minimum width of the guide. + line="346">The minimum width of the guide. setter="set_name" getter="get_name" default-value="NULL"> - - A name that identifies the `GtkConstraintGuide`, for debugging. + line="425">A name that identifies the `GtkConstraintGuide`, for debugging. default-value="0"> The preferred, or natural, height of the guide. + line="379">The preferred, or natural, height of the guide. default-value="0"> The preferred, or natural, width of the guide. + line="368">The preferred, or natural, width of the guide. setter="set_strength" getter="get_strength" default-value="GTK_CONSTRAINT_STRENGTH_MEDIUM"> - - The `GtkConstraintStrength` to be used for the constraint on + line="412">The `GtkConstraintStrength` to be used for the constraint on the natural size of the guide. @@ -37930,7 +39593,7 @@ the natural size of the guide. glib:type-struct="ConstraintLayoutClass"> A layout manager using constraints to describe relations between widgets. + line="20">Uses constraints to describe relations between widgets. `GtkConstraintLayout` is a layout manager that uses relations between widget attributes, expressed via [class@Gtk.Constraint] instances, to @@ -38098,12 +39761,12 @@ Finally, it's also possible to use simple arithmetic operators: Creates a new `GtkConstraintLayout` layout manager. + line="1724">Creates a new `GtkConstraintLayout` layout manager. the newly created `GtkConstraintLayout` + line="1729">the newly created `GtkConstraintLayout` @@ -38111,7 +39774,7 @@ Finally, it's also possible to use simple arithmetic operators: c:identifier="gtk_constraint_layout_add_constraint"> Adds a constraint to the layout manager. + line="1737">Adds a constraint to the layout manager. The [property@Gtk.Constraint:source] and [property@Gtk.Constraint:target] properties of `constraint` can be: @@ -38132,13 +39795,13 @@ this function. a `GtkConstraintLayout` + line="1739">a `GtkConstraintLayout` a [class@Gtk.Constraint] + line="1740">a [class@Gtk.Constraint] @@ -38149,7 +39812,7 @@ this function. introspectable="0"> Creates a list of constraints from a VFL description. + line="2134">Creates a list of constraints from a VFL description. This function is a convenience wrapper around [method@Gtk.ConstraintLayout.add_constraints_from_descriptionv], using @@ -38158,7 +39821,7 @@ variadic arguments to populate the view/target map. the list of + line="2153">the list of [class@Gtk.Constraint]s that were added to the layout @@ -38168,13 +39831,13 @@ variadic arguments to populate the view/target map. a `GtkConstraintLayout` + line="2136">a `GtkConstraintLayout` an array of Visual Format Language lines + line="2137">an array of Visual Format Language lines defining a set of constraints @@ -38183,38 +39846,38 @@ variadic arguments to populate the view/target map. the number of lines + line="2139">the number of lines default horizontal spacing value, or -1 for the fallback value + line="2140">default horizontal spacing value, or -1 for the fallback value default vertical spacing value, or -1 for the fallback value + line="2141">default vertical spacing value, or -1 for the fallback value return location for a `GError` + line="2142">return location for a `GError` the name of a view in the VFL description, followed by the + line="2143">the name of a view in the VFL description, followed by the [iface@Gtk.ConstraintTarget] to which it maps a `NULL`-terminated list of view names and [iface@Gtk.ConstraintTarget]s + line="2145">a `NULL`-terminated list of view names and [iface@Gtk.ConstraintTarget]s @@ -38225,7 +39888,7 @@ variadic arguments to populate the view/target map. throws="1"> Creates a list of constraints from a VFL description. + line="1940">Creates a list of constraints from a VFL description. The Visual Format Language, VFL, is based on Apple's AutoLayout [VFL](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/AutolayoutPG/VisualFormatLanguage.html). @@ -38306,7 +39969,7 @@ Examples of VFL descriptions are: the list of + line="2032">the list of [class@Gtk.Constraint] instances that were added to the layout @@ -38316,13 +39979,13 @@ Examples of VFL descriptions are: a `GtkConstraintLayout` + line="1942">a `GtkConstraintLayout` an array of Visual Format Language lines + line="1943">an array of Visual Format Language lines defining a set of constraints @@ -38331,25 +39994,25 @@ Examples of VFL descriptions are: the number of lines + line="1945">the number of lines default horizontal spacing value, or -1 for the fallback value + line="1946">default horizontal spacing value, or -1 for the fallback value default vertical spacing value, or -1 for the fallback value + line="1947">default vertical spacing value, or -1 for the fallback value a dictionary of `[ name, target ]` + line="1948">a dictionary of `[ name, target ]` pairs; the `name` keys map to the view names in the VFL lines, while the `target` values map to children of the widget using a `GtkConstraintLayout`, or guides @@ -38363,7 +40026,7 @@ Examples of VFL descriptions are: Adds a guide to `layout`. + line="1845">Adds a guide to `layout`. A guide can be used as the source or target of constraints, like a widget, but it is not visible. @@ -38378,13 +40041,13 @@ this function. a `GtkConstraintLayout` + line="1847">a `GtkConstraintLayout` a [class@Gtk.ConstraintGuide] object + line="1848">a [class@Gtk.ConstraintGuide] object @@ -38393,7 +40056,7 @@ this function. c:identifier="gtk_constraint_layout_observe_constraints"> Returns a `GListModel` to track the constraints that are + line="2210">Returns a `GListModel` to track the constraints that are part of the layout. Calling this function will enable extra internal bookkeeping @@ -38407,7 +40070,7 @@ because of the slowdowns. a + line="2224">a `GListModel` tracking the layout's constraints @@ -38415,7 +40078,7 @@ because of the slowdowns. a `GtkConstraintLayout` + line="2212">a `GtkConstraintLayout` @@ -38424,7 +40087,7 @@ because of the slowdowns. c:identifier="gtk_constraint_layout_observe_guides"> Returns a `GListModel` to track the guides that are + line="2250">Returns a `GListModel` to track the guides that are part of the layout. Calling this function will enable extra internal bookkeeping @@ -38438,7 +40101,7 @@ because of the slowdowns. a + line="2264">a `GListModel` tracking the layout's guides @@ -38446,7 +40109,7 @@ because of the slowdowns. a `GtkConstraintLayout` + line="2252">a `GtkConstraintLayout` @@ -38455,7 +40118,7 @@ because of the slowdowns. c:identifier="gtk_constraint_layout_remove_all_constraints"> Removes all constraints from the layout manager. + line="1817">Removes all constraints from the layout manager. @@ -38464,7 +40127,7 @@ because of the slowdowns. a `GtkConstraintLayout` + line="1819">a `GtkConstraintLayout` @@ -38473,7 +40136,7 @@ because of the slowdowns. c:identifier="gtk_constraint_layout_remove_constraint"> Removes `constraint` from the layout manager, + line="1793">Removes `constraint` from the layout manager, so that it no longer influences the layout. @@ -38483,13 +40146,13 @@ so that it no longer influences the layout. a `GtkConstraintLayout` + line="1795">a `GtkConstraintLayout` a [class@Gtk.Constraint] + line="1796">a [class@Gtk.Constraint] @@ -38498,7 +40161,7 @@ so that it no longer influences the layout. c:identifier="gtk_constraint_layout_remove_guide"> Removes `guide` from the layout manager, + line="1877">Removes `guide` from the layout manager, so that it no longer influences the layout. @@ -38508,13 +40171,13 @@ so that it no longer influences the layout. a `GtkConstraintLayout` + line="1879">a `GtkConstraintLayout` a [class@Gtk.ConstraintGuide] object + line="1880">a [class@Gtk.ConstraintGuide] object @@ -38554,7 +40217,7 @@ so that it no longer influences the layout. c:type="GtkConstraintRelation"> The relation between two terms of a constraint. + line="1125">The relation between two terms of a constraint. glib:name="GTK_CONSTRAINT_RELATION_LE"> Less than, or equal + line="1128">Less than, or equal glib:name="GTK_CONSTRAINT_RELATION_EQ"> Equal + line="1127">Equal glib:name="GTK_CONSTRAINT_RELATION_GE"> Greater than, or equal + line="1129">Greater than, or equal c:type="GtkConstraintStrength"> The strength of a constraint, expressed as a symbolic constant. + line="1139">The strength of a constraint, expressed as a symbolic constant. The strength of a [class@Constraint] can be expressed with any positive integer; the values of this enumeration can be used for readability. @@ -38600,7 +40263,7 @@ integer; the values of this enumeration can be used for readability. glib:name="GTK_CONSTRAINT_STRENGTH_REQUIRED"> The constraint is required towards solving the layout + line="1141">The constraint is required towards solving the layout glib:name="GTK_CONSTRAINT_STRENGTH_STRONG"> A strong constraint + line="1142">A strong constraint glib:name="GTK_CONSTRAINT_STRENGTH_MEDIUM"> A medium constraint + line="1143">A medium constraint glib:name="GTK_CONSTRAINT_STRENGTH_WEAK"> A weak constraint + line="1144">A weak constraint glib:type-struct="ConstraintTargetInterface"> The `GtkConstraintTarget` interface is implemented by objects that -can be used as source or target in `GtkConstraint`s. + line="31">Makes it possible to use an object as source or target in a +[class@Gtk.Constraint]. Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. @@ -38658,7 +40321,7 @@ Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. glib:error-domain="gtk-constraint-vfl-parser-error-quark"> Domain for VFL parsing errors. + line="1199">Domain for VFL parsing errors. glib:name="GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_SYMBOL"> Invalid or unknown symbol + line="1201">Invalid or unknown symbol glib:name="GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_ATTRIBUTE"> Invalid or unknown attribute + line="1202">Invalid or unknown attribute glib:name="GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_VIEW"> Invalid or unknown view + line="1203">Invalid or unknown view glib:name="GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_METRIC"> Invalid or unknown metric + line="1204">Invalid or unknown metric glib:name="GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_PRIORITY"> Invalid or unknown priority + line="1205">Invalid or unknown priority glib:name="GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_RELATION"> Invalid or unknown relation + line="1206">Invalid or unknown relation + Registers an error quark for VFL error parsing. + the error quark @@ -38727,7 +40396,7 @@ Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. c:type="GtkContentFit"> Controls how a content should be made to fit inside an allocation. + line="135">Controls how a content should be made to fit inside an allocation. glib:name="GTK_CONTENT_FIT_FILL"> Make the content fill the entire allocation, + line="137">Make the content fill the entire allocation, without taking its aspect ratio in consideration. The resulting content will appear as stretched if its aspect ratio is different from the allocation aspect ratio. @@ -38747,7 +40416,7 @@ Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. glib:name="GTK_CONTENT_FIT_CONTAIN"> Scale the content to fit the allocation, + line="141">Scale the content to fit the allocation, while taking its aspect ratio in consideration. The resulting content will appear as letterboxed if its aspect ratio is different from the allocation aspect ratio. @@ -38759,7 +40428,7 @@ Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. glib:name="GTK_CONTENT_FIT_COVER"> Cover the entire allocation, while taking + line="145">Cover the entire allocation, while taking the content aspect ratio in consideration. The resulting content will appear as clipped if its aspect ratio is different from the allocation aspect ratio. @@ -38771,7 +40440,7 @@ Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. glib:name="GTK_CONTENT_FIT_SCALE_DOWN"> The content is scaled down to fit the + line="149">The content is scaled down to fit the allocation, if needed, otherwise its original size is used. @@ -38827,7 +40496,10 @@ This is effectively the opposite of where the scroll bars are placed. - + Points at a location inside a CSS stream. + @@ -38929,8 +40601,7 @@ skip any input, but they indicate issues that should be fixed. glib:type-struct="CssProviderClass"> `GtkCssProvider` is an object implementing the `GtkStyleProvider` interface -for CSS. + line="58">A style provider for CSS. It is able to parse CSS-like input in order to style widgets. @@ -38963,12 +40634,12 @@ To track errors while loading CSS, connect to the Returns a newly created `GtkCssProvider`. + line="628">Returns a newly created `GtkCssProvider`. A new `GtkCssProvider` + line="633">A new `GtkCssProvider` @@ -38977,7 +40648,7 @@ To track errors while loading CSS, connect to the version="4.12"> Loads @data into @css_provider. + line="1335">Loads @data into @css_provider. This clears any previously loaded information. @@ -38988,13 +40659,13 @@ This clears any previously loaded information. a `GtkCssProvider` + line="1337">a `GtkCssProvider` `GBytes` containing the data to load + line="1338">`GBytes` containing the data to load @@ -39005,7 +40676,7 @@ This clears any previously loaded information. deprecated-version="4.12"> Loads @data into @css_provider. + line="1275">Loads @data into @css_provider. This clears any previously loaded information. Use [method@Gtk.CssProvider.load_from_string] @@ -39018,19 +40689,19 @@ This clears any previously loaded information. a `GtkCssProvider` + line="1277">a `GtkCssProvider` CSS data to be parsed + line="1278">CSS data to be parsed the length of @data in bytes, or -1 for NUL terminated strings + line="1279">the length of @data in bytes, or -1 for NUL terminated strings @@ -39039,7 +40710,7 @@ This clears any previously loaded information. c:identifier="gtk_css_provider_load_from_file"> Loads the data contained in @file into @css_provider. + line="1360">Loads the data contained in @file into @css_provider. This clears any previously loaded information. @@ -39050,13 +40721,13 @@ This clears any previously loaded information. a `GtkCssProvider` + line="1362">a `GtkCssProvider` `GFile` pointing to a file to load + line="1363">`GFile` pointing to a file to load @@ -39065,7 +40736,7 @@ This clears any previously loaded information. c:identifier="gtk_css_provider_load_from_path"> Loads the data contained in @path into @css_provider. + line="1383">Loads the data contained in @path into @css_provider. This clears any previously loaded information. @@ -39076,13 +40747,13 @@ This clears any previously loaded information. a `GtkCssProvider` + line="1385">a `GtkCssProvider` the path of a filename to load, in the GLib filename encoding + line="1386">the path of a filename to load, in the GLib filename encoding @@ -39091,7 +40762,7 @@ This clears any previously loaded information. c:identifier="gtk_css_provider_load_from_resource"> Loads the data contained in the resource at @resource_path into + line="1408">Loads the data contained in the resource at @resource_path into the @css_provider. This clears any previously loaded information. @@ -39103,13 +40774,13 @@ This clears any previously loaded information. a `GtkCssProvider` + line="1410">a `GtkCssProvider` a `GResource` resource path + line="1411">a `GResource` resource path @@ -39119,7 +40790,7 @@ This clears any previously loaded information. version="4.12"> Loads @string into @css_provider. + line="1308">Loads @string into @css_provider. This clears any previously loaded information. @@ -39130,13 +40801,13 @@ This clears any previously loaded information. a `GtkCssProvider` + line="1310">a `GtkCssProvider` the CSS to load + line="1311">the CSS to load @@ -39144,7 +40815,7 @@ This clears any previously loaded information. Loads a theme from the usual theme paths. + line="1563">Loads a theme from the usual theme paths. The actual process of finding the theme might change between releases, but it is guaranteed that this function uses the same @@ -39157,13 +40828,13 @@ mechanism to load the theme that GTK uses for loading its own theme. a `GtkCssProvider` + line="1565">a `GtkCssProvider` A theme name + line="1566">A theme name allow-none="1"> variant to load, for example, "dark", or + line="1567">variant to load, for example, "dark", or %NULL for the default @@ -39181,10 +40852,10 @@ mechanism to load the theme that GTK uses for loading its own theme. Converts the @provider into a string representation in CSS + line="1798">Converts the @provider into a string representation in CSS format. -Using [method@Gtk.CssProvider.load_from_data] with the return +Using [method@Gtk.CssProvider.load_from_string] with the return value from this function on a new provider created with [ctor@Gtk.CssProvider.new] will basically create a duplicate of this @provider. @@ -39192,14 +40863,14 @@ of this @provider. a new string representing the @provider. + line="1810">a new string representing the @provider. the provider to write to a string + line="1800">the provider to write to a string @@ -39210,7 +40881,10 @@ of this @provider. Signals that a parsing error occurred. + line="217">Signals that a parsing error occurred. + +The expected error values are in the [error@Gtk.CssParserError] +and [enum@Gtk.CssParserWarning] enumerations. The @path, @line and @position describe the actual location of the error as accurately as possible. @@ -39220,6 +40894,9 @@ the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal. +Errors in the [enum@Gtk.CssParserWarning] enumeration should not +be treated as fatal errors. + Note that this signal may be emitted at any time as the css provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called. @@ -39230,13 +40907,13 @@ than when a loading function was called. section the error happened in + line="220">section the error happened in The parsing error + line="221">The parsing error @@ -39271,14 +40948,14 @@ Because sections are nested into one another, you can use Creates a new `GtkCssSection` referring to the section + line="36">Creates a new `GtkCssSection` referring to the section in the given `file` from the `start` location to the `end` location. a new `GtkCssSection` + line="46">a new `GtkCssSection` @@ -39288,33 +40965,104 @@ in the given `file` from the `start` location to the allow-none="1"> The file this section refers to + line="38">The file this section refers to The start location + line="39">The start location The end location + line="40">The end location + + Creates a new `GtkCssSection` referring to the section +in the given `file` or the given `bytes` from the `start` location to the +`end` location. + + + a new `GtkCssSection` + + + + + The file this section refers to + + + + The bytes this sections refers to + + + + The start location + + + + The end location + + + + + + Gets the bytes that @section was parsed from. + + + the `GBytes` from which the `section` + was parsed + + + + + the section + + + + Returns the location in the CSS document where this section ends. - + line="219">Returns the location in the CSS document where this section ends. + The end location of + line="225">The end location of this section @@ -39322,7 +41070,7 @@ in the given `file` from the `start` location to the the section + line="221">the section @@ -39330,15 +41078,15 @@ in the given `file` from the `start` location to the Gets the file that @section was parsed from. + line="163">Gets the file that @section was parsed from. If no such file exists, for example because the CSS was loaded via [method@Gtk.CssProvider.load_from_data], then `NULL` is returned. - + the `GFile` from which the `section` + line="172">the `GFile` from which the `section` was parsed @@ -39346,7 +41094,7 @@ If no such file exists, for example because the CSS was loaded via the section + line="165">the section @@ -39354,26 +41102,26 @@ If no such file exists, for example because the CSS was loaded via Gets the parent section for the given `section`. + line="140">Gets the parent section for the given `section`. The parent section is the section that contains this `section`. A special -case are sections of type `GTK_CSS_SECTION_DOCUMEN`T. Their parent will +case are sections of type `GTK_CSS_SECTION_DOCUMENT`. Their parent will either be `NULL` if they are the original CSS document that was loaded by [method@Gtk.CssProvider.load_from_file] or a section of type `GTK_CSS_SECTION_IMPORT` if it was loaded with an `@import` rule from a different file. - + the parent section + line="153">the parent section the section + line="142">the section @@ -39382,12 +41130,12 @@ a different file. c:identifier="gtk_css_section_get_start_location"> Returns the location in the CSS document where this section starts. - + line="202">Returns the location in the CSS document where this section starts. + The start location of + line="208">The start location of this section @@ -39395,7 +41143,7 @@ a different file. the section + line="204">the section @@ -39403,11 +41151,11 @@ a different file. Prints the `section` into `string` in a human-readable form. + line="236">Prints the `section` into `string` in a human-readable form. This is a form like `gtk.css:32:1-23` to denote line 32, characters 1 to 23 in the file `gtk.css`. - + @@ -39415,13 +41163,13 @@ This is a form like `gtk.css:32:1-23` to denote line 32, characters a section + line="238">a section a `GString` to print to + line="239">a `GString` to print to @@ -39429,19 +41177,19 @@ This is a form like `gtk.css:32:1-23` to denote line 32, characters Increments the reference count on `section`. - + line="96">Increments the reference count on `section`. + the CSS section itself. + line="102">the CSS section itself. a `GtkCssSection` + line="98">a `GtkCssSection` @@ -39449,20 +41197,20 @@ This is a form like `gtk.css:32:1-23` to denote line 32, characters Prints the section into a human-readable text form using + line="284">Prints the section into a human-readable text form using [method@Gtk.CssSection.print]. - + A new string. + line="291">A new string. a `GtkCssSection` + line="286">a `GtkCssSection` @@ -39470,9 +41218,9 @@ This is a form like `gtk.css:32:1-23` to denote line 32, characters Decrements the reference count on `section`, freeing the + line="114">Decrements the reference count on `section`, freeing the structure if the reference count reaches 0. - + @@ -39480,7 +41228,7 @@ structure if the reference count reaches 0. a `GtkCssSection` + line="116">a `GtkCssSection` @@ -39490,7 +41238,10 @@ structure if the reference count reaches 0. c:type="GtkCssStyleChange" disguised="1" opaque="1"> - + A CSS style change. + glib:type-struct="CustomFilterClass"> `GtkCustomFilter` determines whether to include items with a callback. + line="26">Determines whether to include items with a callback. Creates a new filter using the given @match_func to filter -items. + line="93">Creates a new filter using the given function to filter items. -If @match_func is %NULL, the filter matches all items. +If @match_func is `NULL`, the filter matches all items. If the filter func changes its filtering behavior, -gtk_filter_changed() needs to be called. +[method@Gtk.Filter.changed] needs to be called. a new `GtkCustomFilter` + line="106">a new `GtkCustomFilter` @@ -39591,15 +41341,15 @@ gtk_filter_changed() needs to be called. c:identifier="gtk_custom_filter_set_filter_func"> Sets the function used for filtering items. + line="122">Sets the function used for filtering items. -If @match_func is %NULL, the filter matches all items. +If @match_func is `NULL`, the filter matches all items. If the filter func changes its filtering behavior, -gtk_filter_changed() needs to be called. +[method@Gtk.Filter.changed] needs to be called. -If a previous function was set, its @user_destroy will be -called now. +If a previous function was set, its @user_destroy +will be called. @@ -39608,7 +41358,7 @@ called now. a `GtkCustomFilter` + line="124">a custom filter destroy="2"> function to filter items + line="125">function to filter items allow-none="1"> user data to pass to @match_func + line="126">user data to pass to @match_func scope="async"> destroy notify for @user_data + line="127">destroy notify for @user_data @@ -39656,20 +41406,20 @@ called now. filename="gtk/gtkcustomfilter.h" line="30">User function that is called to determine if the @item should be matched. -If the filter matches the item, this function must return %TRUE. If the -item should be filtered out, %FALSE must be returned. +If the filter matches the item, this function must return true. +If the item should be filtered out, false must be returned. %TRUE to keep the item around + line="40">true to keep the item around The item to be matched + line="32">the item to be matched glib:type-struct="CustomLayoutClass"> `GtkCustomLayout` uses closures for size negotiation. + line="1">Uses closures for size negotiation. -A `GtkCustomLayout `uses closures matching to the old `GtkWidget` +A `GtkCustomLayout` uses closures matching to the old `GtkWidget` virtual functions for size negotiation, as a convenience API to -ease the porting towards the corresponding `GtkLayoutManager +ease the porting towards the corresponding `GtkLayoutManager` virtual functions. @@ -39847,13 +41597,12 @@ from layout containers to layout manager delegates. glib:type-struct="CustomSorterClass"> `GtkCustomSorter` is a `GtkSorter` implementation that sorts via a callback -function. + line="26">Sorts items via a callback function. Creates a new `GtkSorter` that works by calling + line="98">Creates a new `GtkSorter` that works by calling @sort_func to compare items. If @sort_func is %NULL, all items are considered equal. @@ -39861,7 +41610,7 @@ If @sort_func is %NULL, all items are considered equal. a new `GtkCustomSorter` + line="109">a new `GtkCustomSorter` @@ -39874,7 +41623,7 @@ If @sort_func is %NULL, all items are considered equal. destroy="2"> the `GCompareDataFunc` to use for sorting + line="100">the `GCompareDataFunc` to use for sorting allow-none="1"> user data to pass to @sort_func + line="101">user data to pass to @sort_func scope="async"> destroy notify for @user_data + line="102">destroy notify for @user_data @@ -39902,7 +41651,7 @@ If @sort_func is %NULL, all items are considered equal. c:identifier="gtk_custom_sorter_set_sort_func"> Sets (or unsets) the function used for sorting items. + line="125">Sets (or unsets) the function used for sorting items. If @sort_func is %NULL, all items are considered equal. @@ -39919,7 +41668,7 @@ called now. a `GtkCustomSorter` + line="127">a `GtkCustomSorter` destroy="2"> function to sort items + line="128">function to sort items allow-none="1"> user data to pass to @match_func + line="129">user data to pass to @match_func scope="async"> destroy notify for @user_data + line="130">destroy notify for @user_data @@ -39965,9 +41714,15 @@ called now. - + Whether the `type` debug flag is set. + + type to check @@ -40205,14 +41960,11 @@ only available when GTK has been configured with `-Ddebug=true`. filename="gtk/gtkdebug.h" line="44">Information about printing - - Trace GtkBuilder operation + c:identifier="GTK_DEBUG_BUILDER_TRACE" + glib:nick="builder-trace" + glib:name="GTK_DEBUG_BUILDER_TRACE"> Information about icon fallback. Since: 4.2 + line="63">Information about icon fallback. + Inverts the default text-direction. + + + Information about deprecated CSS features. + + + Trace GtkBuilder operation c:type="GtkDeleteType"> Passed to various keybinding signals for deleting text. + line="164">Passed to various keybinding signals for deleting text. glib:name="GTK_DELETE_CHARS"> Delete characters. + line="166">Delete characters. glib:name="GTK_DELETE_WORD_ENDS"> Delete only the portion of the word to the + line="167">Delete only the portion of the word to the left/right of cursor if we’re in the middle of a word. glib:name="GTK_DELETE_WORDS"> Delete words. + line="169">Delete words. glib:name="GTK_DELETE_DISPLAY_LINES"> Delete display-lines. Display-lines + line="170">Delete display-lines. Display-lines refers to the visible lines, with respect to the current line breaks. As opposed to paragraphs, which are defined by line breaks in the input. @@ -40365,7 +42141,7 @@ only available when GTK has been configured with `-Ddebug=true`. glib:name="GTK_DELETE_DISPLAY_LINE_ENDS"> Delete only the portion of the + line="174">Delete only the portion of the display-line to the left/right of cursor. glib:name="GTK_DELETE_PARAGRAPH_ENDS"> Delete to the end of the + line="176">Delete to the end of the paragraph. Like C-k in Emacs (or its reverse). glib:name="GTK_DELETE_PARAGRAPHS"> Delete entire line. Like C-k in pico. + line="178">Delete entire line. Like C-k in pico. glib:name="GTK_DELETE_WHITESPACE"> Delete only whitespace. Like M-\ in Emacs. + line="179">Delete only whitespace. Like M-\ in Emacs. line="48">Dialogs are a convenient way to prompt the user for a small amount of input. -![An example GtkDialog](dialog.png) +<picture> + <source srcset="dialog-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkDialog" src="dialog.png"> +</picture> Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part. @@ -40543,7 +42322,7 @@ An example of a `GtkDialog` UI definition fragment: deprecated-version="4.10"> Creates a new dialog box. + line="695">Creates a new dialog box. Widgets should not be packed into the `GtkWindow` directly, but into the @content_area and @action_area, @@ -40553,7 +42332,7 @@ as described above. the new dialog as a `GtkWidget` + line="704">the new dialog as a `GtkWidget` @@ -40564,7 +42343,7 @@ as described above. deprecated-version="4.10"> Creates a new `GtkDialog` with the given title and transient parent. + line="740">Creates a new `GtkDialog` with the given title and transient parent. The @flags argument can be used to make the dialog modal, have it destroyed along with its transient parent, or make it use a headerbar. @@ -40602,7 +42381,7 @@ dialog = gtk_dialog_new_with_buttons ("My dialog", a new `GtkDialog` + line="782">a new `GtkDialog` @@ -40612,7 +42391,7 @@ dialog = gtk_dialog_new_with_buttons ("My dialog", allow-none="1"> Title of the dialog + line="742">Title of the dialog Transient parent of the dialog + line="743">Transient parent of the dialog from `GtkDialogFlags` + line="744">from `GtkDialogFlags` text to go in first button + line="745">text to go in first button response ID for first button, then additional buttons, ending with %NULL + line="746">response ID for first button, then additional buttons, ending with %NULL + Signal emitted when the user uses a keybinding to close the dialog. @@ -40665,7 +42447,7 @@ dialog = gtk_dialog_new_with_buttons ("My dialog", Emits the ::response signal with the given response ID. + line="1058">Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@Gtk.Window] instead @@ -40677,13 +42459,13 @@ Used to indicate that the user has responded to the dialog in some way. a `GtkDialog` + line="1060">a `GtkDialog` response ID + line="1061">response ID @@ -40694,7 +42476,7 @@ Used to indicate that the user has responded to the dialog in some way. deprecated-version="4.10"> Adds an activatable widget to the action area of a `GtkDialog`. + line="861">Adds an activatable widget to the action area of a `GtkDialog`. GTK connects a signal handler that will emit the [signal@Gtk.Dialog::response] signal on the dialog when the widget @@ -40712,19 +42494,19 @@ the @action_area field of the `GtkDialog` struct. a `GtkDialog` + line="863">a `GtkDialog` an activatable widget + line="864">an activatable widget response ID for @child + line="865">response ID for @child @@ -40735,7 +42517,7 @@ the @action_area field of the `GtkDialog` struct. deprecated-version="4.10"> Adds a button with the given text. + line="905">Adds a button with the given text. GTK arranges things so that clicking the button will emit the [signal@Gtk.Dialog::response] signal with the given @response_id. @@ -40746,26 +42528,26 @@ The button widget is returned, but usually you don’t need it. the `GtkButton` widget that was added + line="918">the `GtkButton` widget that was added a `GtkDialog` + line="907">a `GtkDialog` text of button + line="908">text of button response ID for the button + line="909">response ID for the button @@ -40777,7 +42559,7 @@ The button widget is returned, but usually you don’t need it. deprecated-version="4.10"> Adds multiple buttons. + line="967">Adds multiple buttons. This is the same as calling [method@Gtk.Dialog.add_button] repeatedly. The variable argument list should be %NULL-terminated @@ -40792,19 +42574,19 @@ text and response ID. a `GtkDialog` + line="969">a `GtkDialog` button text + line="970">button text response ID for first button, then more text-response_id pairs + line="971">response ID for first button, then more text-response_id pairs @@ -40815,20 +42597,20 @@ text and response ID. deprecated-version="4.10"> Returns the content area of @dialog. + line="1447">Returns the content area of @dialog. Use [class@Gtk.Window] instead the content area `GtkBox`. + line="1453">the content area `GtkBox`. a `GtkDialog` + line="1449">a `GtkDialog` @@ -40839,7 +42621,7 @@ text and response ID. deprecated-version="4.10"> Returns the header bar of @dialog. + line="1424">Returns the header bar of @dialog. Note that the headerbar is only used by the dialog if the [property@Gtk.Dialog:use-header-bar] property is %TRUE. @@ -40848,14 +42630,14 @@ Note that the headerbar is only used by the dialog if the the header bar + line="1433">the header bar a `GtkDialog` + line="1426">a `GtkDialog` @@ -40866,14 +42648,14 @@ Note that the headerbar is only used by the dialog if the deprecated-version="4.10"> Gets the response id of a widget in the action area + line="1112">Gets the response id of a widget in the action area of a dialog. Use [class@Gtk.Window] instead the response id of @widget, or %GTK_RESPONSE_NONE + line="1120">the response id of @widget, or %GTK_RESPONSE_NONE if @widget doesn’t have a response id set. @@ -40881,13 +42663,13 @@ of a dialog. a `GtkDialog` + line="1114">a `GtkDialog` a widget in the action area of @dialog + line="1115">a widget in the action area of @dialog @@ -40898,14 +42680,14 @@ of a dialog. deprecated-version="4.10"> Gets the widget button that uses the given response ID in the action area + line="1081">Gets the widget button that uses the given response ID in the action area of a dialog. Use [class@Gtk.Window] instead the @widget button that uses the given + line="1089">the @widget button that uses the given @response_id @@ -40913,13 +42695,13 @@ of a dialog. a `GtkDialog` + line="1083">a `GtkDialog` the response ID used by the @dialog widget + line="1084">the response ID used by the @dialog widget @@ -40931,7 +42713,7 @@ of a dialog. Emits the ::response signal with the given response ID. + line="1058">Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@Gtk.Window] instead @@ -40943,13 +42725,13 @@ Used to indicate that the user has responded to the dialog in some way. a `GtkDialog` + line="1060">a `GtkDialog` response ID + line="1061">response ID @@ -40960,7 +42742,7 @@ Used to indicate that the user has responded to the dialog in some way. deprecated-version="4.10"> Sets the default widget for the dialog based on the response ID. + line="1028">Sets the default widget for the dialog based on the response ID. Pressing “Enter” normally activates the default widget. Use [class@Gtk.Window] instead @@ -40972,13 +42754,13 @@ Pressing “Enter” normally activates the default widget. a `GtkDialog` + line="1030">a `GtkDialog` a response ID + line="1031">a response ID @@ -40989,7 +42771,7 @@ Pressing “Enter” normally activates the default widget. deprecated-version="4.10"> A convenient way to sensitize/desensitize dialog buttons. + line="998">A convenient way to sensitize/desensitize dialog buttons. Calls `gtk_widget_set_sensitive (widget, @setting)` for each widget in the dialog’s action area with the given @response_id. @@ -41002,19 +42784,19 @@ for each widget in the dialog’s action area with the given @response_id. a `GtkDialog` + line="1000">a `GtkDialog` a response ID + line="1001">a response ID %TRUE for sensitive + line="1002">%TRUE for sensitive @@ -41028,7 +42810,7 @@ for each widget in the dialog’s action area with the given @response_id. default-value="-1"> %TRUE if the dialog uses a headerbar for action buttons + line="553">%TRUE if the dialog uses a headerbar for action buttons instead of the action-area. For technical reasons, this property is declared as an integer @@ -41059,7 +42841,7 @@ dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL); deprecated-version="4.10"> Emitted when the user uses a keybinding to close the dialog. + line="533">Emitted when the user uses a keybinding to close the dialog. This is a [keybinding signal](class.SignalAction.html). @@ -41075,7 +42857,7 @@ The default binding for this signal is the Escape key. deprecated-version="4.10"> Emitted when an action widget is clicked. + line="509">Emitted when an action widget is clicked. The signal is also emitted when the dialog receives a delete event, and when [method@Gtk.Dialog.response] is called. @@ -41089,7 +42871,7 @@ Otherwise, it depends on which action widget was clicked. the response ID + line="512">the response ID @@ -41106,6 +42888,9 @@ Otherwise, it depends on which action widget was clicked. + Signal emitted when an action widget is activated. @@ -41115,19 +42900,22 @@ Otherwise, it depends on which action widget was clicked. a `GtkDialog` + line="1060">a `GtkDialog` response ID + line="1061">response ID + Signal emitted when the user uses a keybinding to close the dialog. @@ -41187,7 +42975,14 @@ by async dialog functions. by the user (via a Cancel or Close button) + Registers an error quark for an operation that requires a dialog if +necessary. + the error quark @@ -41234,7 +43029,7 @@ by async dialog functions. c:type="GtkDirectionType"> Focus movement types. + line="196">Focus movement types. glib:name="GTK_DIR_TAB_FORWARD"> Move forward. + line="198">Move forward. glib:name="GTK_DIR_TAB_BACKWARD"> Move backward. + line="199">Move backward. glib:name="GTK_DIR_UP"> Move up. + line="200">Move up. glib:name="GTK_DIR_DOWN"> Move down. + line="201">Move down. glib:name="GTK_DIR_LEFT"> Move left. + line="202">Move left. glib:name="GTK_DIR_RIGHT"> Move right. + line="203">Move right. glib:type-struct="DirectoryListClass"> `GtkDirectoryList` is a list model that wraps g_file_enumerate_children_async(). + line="26">A list model that wraps [method@Gio.File.enumerate_children_async]. It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s returned from that function. -Enumeration will start automatically when a the +Enumeration will start automatically when the [property@Gtk.DirectoryList:file] property is set. While the `GtkDirectoryList` is being filled, the @@ -41361,22 +43156,21 @@ with the given @attributes. - Gets the attributes queried on the children. + line="892">Gets the attributes queried on the children. The queried attributes + line="898">The queried attributes a `GtkDirectoryList` + line="894">a `GtkDirectoryList` @@ -41384,10 +43178,9 @@ with the given @attributes. - Gets the loading error, if any. + line="974">Gets the loading error, if any. If an error occurs during the loading process, the loading process will finish and this property allows querying the error that happened. @@ -41399,7 +43192,7 @@ successfully queried files will remain in the list. The loading error or %NULL if + line="987">The loading error or %NULL if loading finished successfully @@ -41407,7 +43200,7 @@ successfully queried files will remain in the list. a `GtkDirectoryList` + line="976">a `GtkDirectoryList` @@ -41415,22 +43208,21 @@ successfully queried files will remain in the list. - Gets the file whose children are currently enumerated. + line="845">Gets the file whose children are currently enumerated. The file whose children are enumerated + line="851">The file whose children are enumerated a `GtkDirectoryList` + line="847">a `GtkDirectoryList` @@ -41438,22 +43230,21 @@ successfully queried files will remain in the list. - Gets the IO priority set via gtk_directory_list_set_io_priority(). + line="937">Gets the IO priority set via gtk_directory_list_set_io_priority(). The IO priority. + line="943">The IO priority. a `GtkDirectoryList` + line="939">a `GtkDirectoryList` @@ -41461,32 +43252,32 @@ successfully queried files will remain in the list. - Returns whether the directory list is monitoring + line="1033">Returns whether the directory list is monitoring the directory for changes. %TRUE if the directory is monitored + line="1040">%TRUE if the directory is monitored a `GtkDirectoryList` + line="1035">a `GtkDirectoryList` - - + Returns %TRUE if the children enumeration is currently in + line="953">Returns %TRUE if the children enumeration is currently in progress. Files will be added to @self from time to time while loading is @@ -41496,14 +43287,14 @@ in between runs. %TRUE if @self is loading + line="964">%TRUE if @self is loading a `GtkDirectoryList` + line="955">a `GtkDirectoryList` @@ -41511,10 +43302,9 @@ in between runs. - Sets the @attributes to be enumerated and starts the enumeration. + line="861">Sets the @attributes to be enumerated and starts the enumeration. If @attributes is %NULL, the list of file infos will still be created, it will just not contain any extra attributes. @@ -41526,7 +43316,7 @@ not contain any extra attributes. a `GtkDirectoryList` + line="863">a `GtkDirectoryList` allow-none="1"> the attributes to enumerate + line="864">the attributes to enumerate @@ -41543,10 +43333,9 @@ not contain any extra attributes. - Sets the @file to be enumerated and starts the enumeration. + line="813">Sets the @file to be enumerated and starts the enumeration. If @file is %NULL, the result will be an empty list. @@ -41557,7 +43346,7 @@ If @file is %NULL, the result will be an empty list. a `GtkDirectoryList` + line="815">a `GtkDirectoryList` allow-none="1"> the `GFile` to be enumerated + line="816">the `GFile` to be enumerated @@ -41574,10 +43363,9 @@ If @file is %NULL, the result will be an empty list. - Sets the IO priority to use while loading directories. + line="908">Sets the IO priority to use while loading directories. Setting the priority while @self is loading will reprioritize the ongoing load as soon as possible. @@ -41594,13 +43382,13 @@ may increase responsiveness. a `GtkDirectoryList` + line="910">a `GtkDirectoryList` IO priority to use + line="911">IO priority to use @@ -41608,10 +43396,9 @@ may increase responsiveness. - Sets whether the directory list will monitor the directory + line="998">Sets whether the directory list will monitor the directory for changes. If monitoring is enabled, the ::items-changed signal will @@ -41630,13 +43417,13 @@ and when monitoring was turned on. a `GtkDirectoryList` + line="1000">a `GtkDirectoryList` %TRUE to monitor the directory for changes + line="1001">%TRUE to monitor the directory for changes @@ -41647,18 +43434,12 @@ and when monitoring was turned on. setter="set_attributes" getter="get_attributes" default-value="NULL"> - - The attributes to query. - Error encountered while loading files. @@ -41669,10 +43450,6 @@ and when monitoring was turned on. transfer-ownership="none" setter="set_file" getter="get_file"> - - File to query. @@ -41684,10 +43461,6 @@ and when monitoring was turned on. setter="set_io_priority" getter="get_io_priority" default-value="0"> - - Priority used when loading. @@ -41699,9 +43472,10 @@ and when monitoring was turned on. line="325">The type of items. See [method@Gio.ListModel.get_item_type]. - - + %TRUE if files are being loaded. @@ -41713,10 +43487,6 @@ and when monitoring was turned on. setter="set_monitored" getter="get_monitored" default-value="TRUE"> - - %TRUE if the directory is monitored for changed. @@ -41749,13 +43519,13 @@ and when monitoring was turned on. glib:type-struct="DragIconClass"> `GtkDragIcon` is a `GtkRoot` implementation for drag icons. + line="41">A `GtkRoot` implementation for drag icons. A drag icon moves with the pointer during a Drag-and-Drop operation and is destroyed when the drag ends. To set up a drag icon and associate it with an ongoing drag operation, -use [func@Gtk.DragIcon.get_for_drag] to get the icon for a drag. You can +use [ctor@Gtk.DragIcon.get_for_drag] to get the icon for a drag. You can then use it like any other widget and use [method@Gtk.DragIcon.set_child] to set whatever widget should be used for the drag icon. @@ -41766,6 +43536,30 @@ Keep in mind that drag icons do not allow user input. + + Gets the `GtkDragIcon` in use with @drag. + +If no drag icon exists yet, a new one will be created +and shown. + + + the `GtkDragIcon` + + + + + a `GdkDrag` + + + + - - Gets the `GtkDragIcon` in use with @drag. - -If no drag icon exists yet, a new one will be created -and shown. - - - the `GtkDragIcon` - - - - - a `GdkDrag` - - - - - Gets the widget currently used as drag icon. @@ -41886,7 +43656,6 @@ hotspot of the cursor. - Sets the widget to display as the drag icon. @@ -41917,10 +43686,6 @@ hotspot of the cursor. transfer-ownership="none" setter="set_child" getter="get_child"> - - The widget to display as drag icon. @@ -41944,7 +43709,7 @@ hotspot of the cursor. glib:type-struct="DragSourceClass"> `GtkDragSource` is an event controller to initiate Drag-And-Drop operations. + line="44">An event controller to initiate Drag-And-Drop operations. `GtkDragSource` can be set up with the necessary ingredients for a DND operation ahead of time. This includes @@ -42053,7 +43818,6 @@ data after it has been transferred. - Gets the actions that are currently set on the `GtkDragSource`. @@ -42076,7 +43840,6 @@ data after it has been transferred. - Gets the current content provider of a `GtkDragSource`. @@ -42120,7 +43883,6 @@ data after it has been transferred. - Sets the actions on the `GtkDragSource`. @@ -42154,7 +43916,6 @@ or in a handler for the [signal@Gtk.DragSource::prepare] signal. - Sets a content provider on a `GtkDragSource`. @@ -42242,10 +44003,6 @@ a [signal@Gtk.DragSource::prepare] or setter="set_actions" getter="get_actions" default-value="GDK_ACTION_COPY"> - - The actions that are supported by drag operations from the source. @@ -42259,10 +44016,6 @@ if the actions include %GDK_ACTION_MOVE. transfer-ownership="none" setter="set_content" getter="get_content"> - - The data that is offered by drag operations from this source. @@ -42390,9 +44143,12 @@ property ahead of time, you don't need to connect to this signal. glib:type-struct="DrawingAreaClass"> `GtkDrawingArea` is a widget that allows drawing with cairo. + line="60">Allows drawing with cairo. -![An example GtkDrawingArea](drawingarea.png) +<picture> + <source srcset="drawingarea-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkDrawingArea" src="drawingarea.png"> +</picture> It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to: @@ -42475,12 +44231,12 @@ creating your own `GtkWidget` subclass. Creates a new drawing area. + line="337">Creates a new drawing area. a new `GtkDrawingArea` + line="342">a new `GtkDrawingArea` @@ -42504,22 +44260,21 @@ creating your own `GtkWidget` subclass. - Retrieves the content height of the `GtkDrawingArea`. + line="432">Retrieves the content height of the `GtkDrawingArea`. The height requested for content of the drawing area + line="438">The height requested for content of the drawing area a `GtkDrawingArea` + line="434">a `GtkDrawingArea` @@ -42527,22 +44282,21 @@ creating your own `GtkWidget` subclass. - Retrieves the content width of the `GtkDrawingArea`. + line="382">Retrieves the content width of the `GtkDrawingArea`. The width requested for content of the drawing area + line="388">The width requested for content of the drawing area a `GtkDrawingArea` + line="384">a `GtkDrawingArea` @@ -42550,10 +44304,9 @@ creating your own `GtkWidget` subclass. - Sets the desired height of the contents of the drawing area. + line="400">Sets the desired height of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual height passed to your draw @@ -42569,13 +44322,13 @@ If the height is set to 0 (the default), the drawing area may disappear. a `GtkDrawingArea` + line="402">a `GtkDrawingArea` the height of contents + line="403">the height of contents @@ -42583,10 +44336,9 @@ If the height is set to 0 (the default), the drawing area may disappear. - Sets the desired width of the contents of the drawing area. + line="350">Sets the desired width of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual width passed to your draw @@ -42602,13 +44354,13 @@ If the width is set to 0 (the default), the drawing area may disappear. a `GtkDrawingArea` + line="352">a `GtkDrawingArea` the width of contents + line="353">the width of contents @@ -42617,7 +44369,7 @@ If the width is set to 0 (the default), the drawing area may disappear. c:identifier="gtk_drawing_area_set_draw_func"> Setting a draw function is the main thing you want to do when using + line="450">Setting a draw function is the main thing you want to do when using a drawing area. The draw function is called whenever GTK needs to draw the contents @@ -42639,7 +44391,7 @@ on the drawing area. This will cause a redraw and will call @draw_func again. a `GtkDrawingArea` + line="452">a `GtkDrawingArea` callback that lets you draw - the drawing area's contents + line="453">callback + that lets you draw the drawing area's contents user data passed to @draw_func + line="455">user data passed to @draw_func destroy notifier for @user_data + line="456">destroy notifier for @user_data @@ -42678,13 +44430,9 @@ on the drawing area. This will cause a redraw and will call @draw_func again. - - The content height. + line="294">The content height. - - The content width. + line="284">The content width. @@ -42708,7 +44452,7 @@ on the drawing area. This will cause a redraw and will call @draw_func again. Emitted once when the widget is realized, and then each time the widget + line="306">Emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep state up to date with the widget size, @@ -42720,13 +44464,13 @@ like for instance a backing surface. the width of the viewport + line="309">the width of the viewport the height of the viewport + line="310">the height of the viewport @@ -42823,8 +44567,7 @@ and must not call any widget functions that cause changes. glib:type-struct="DropControllerMotionClass"> `GtkDropControllerMotion` is an event controller tracking -the pointer during Drag-and-Drop operations. + line="20">An event controller tracking the pointer during Drag-and-Drop operations. It is modeled after [class@Gtk.EventControllerMotion] so if you have used that, this should feel really familiar. @@ -42835,37 +44578,35 @@ for that purpose. Creates a new event controller that will handle pointer motion + line="326">Creates a new event controller that will handle pointer motion events during drag and drop. a new `GtkDropControllerMotion` + line="332">a new `GtkDropControllerMotion` - Returns if a Drag-and-Drop operation is within the widget + line="341">Returns if a Drag-and-Drop operation is within the widget @self or one of its children. %TRUE if a dragging pointer is within @self or one of its children. + line="348">%TRUE if a dragging pointer is within @self or one of its children. a `GtkDropControllerMotion` + line="343">a `GtkDropControllerMotion` @@ -42874,16 +44615,15 @@ events during drag and drop. - Returns the `GdkDrop` of a current Drag-and-Drop operation + line="358">Returns the `GdkDrop` of a current Drag-and-Drop operation over the widget of @self. The `GdkDrop` currently + line="365">The `GdkDrop` currently happening within @self @@ -42891,7 +44631,7 @@ over the widget of @self. a `GtkDropControllerMotion` + line="360">a `GtkDropControllerMotion` @@ -42900,16 +44640,15 @@ over the widget of @self. - Returns if a Drag-and-Drop operation is within the widget + line="376">Returns if a Drag-and-Drop operation is within the widget @self, not one of its children. %TRUE if a dragging pointer is within @self but + line="383">%TRUE if a dragging pointer is within @self but not one of its children @@ -42917,7 +44656,7 @@ over the widget of @self. a `GtkDropControllerMotion` + line="378">a `GtkDropControllerMotion` @@ -42927,11 +44666,9 @@ over the widget of @self. transfer-ownership="none" getter="contains_pointer" default-value="FALSE"> - Whether the pointer of a Drag-and-Drop operation is in + line="208">Whether the pointer of a Drag-and-Drop operation is in the controller's widget or a descendant. See also [property@Gtk.DropControllerMotion:is-pointer]. @@ -42942,11 +44679,9 @@ before [signal@Gtk.DropControllerMotion::enter], but after - The ongoing drop operation over the controller's widget or + line="225">The ongoing drop operation over the controller's widget or its descendant. If no drop operation is going on, this property returns %NULL. @@ -42963,11 +44698,9 @@ before [signal@Gtk.DropControllerMotion::enter], but after transfer-ownership="none" getter="is_pointer" default-value="FALSE"> - Whether the pointer is in the controllers widget itself, + line="245">Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.DropControllerMotion:contains-pointer]. @@ -42980,7 +44713,7 @@ before [signal@Gtk.DropControllerMotion::enter], but after Signals that the pointer has entered the widget. + line="264">Signals that the pointer has entered the widget. @@ -42988,13 +44721,13 @@ before [signal@Gtk.DropControllerMotion::enter], but after coordinates of pointer location + line="267">coordinates of pointer location coordinates of pointer location + line="268">coordinates of pointer location @@ -43002,7 +44735,7 @@ before [signal@Gtk.DropControllerMotion::enter], but after Signals that the pointer has left the widget. + line="285">Signals that the pointer has left the widget. @@ -43010,7 +44743,7 @@ before [signal@Gtk.DropControllerMotion::enter], but after Emitted when the pointer moves inside the widget. + line="299">Emitted when the pointer moves inside the widget. @@ -43018,13 +44751,13 @@ before [signal@Gtk.DropControllerMotion::enter], but after the x coordinate + line="302">the x coordinate the y coordinate + line="303">the y coordinate @@ -43046,10 +44779,12 @@ before [signal@Gtk.DropControllerMotion::enter], but after glib:type-struct="DropDownClass"> `GtkDropDown` is a widget that allows the user to choose an item -from a list of options. + line="49">Allows the user to choose an item from a list of options. -![An example GtkDropDown](drop-down.png) +<picture> + <source srcset="drop-down-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkDropDown" src="drop-down.png"> +</picture> The `GtkDropDown` displays the [selected][property@Gtk.DropDown:selected] choice. @@ -43087,6 +44822,10 @@ Here is a UI definition example for `GtkDropDown` with a simple model: </object> ``` +If a `GtkDropDown` is created in this manner, or with +[ctor@Gtk.DropDown.new_from_strings], for instance, the object returned from +[method@Gtk.DropDown.get_selected_item] will be a [class@Gtk.StringObject]. + To learn more about the list widget framework, see the [overview](section-list-widget.html). @@ -43097,7 +44836,7 @@ with the button and popover nodes as children. ## Accessibility -`GtkDropDown` uses the %GTK_ACCESSIBLE_ROLE_COMBO_BOX role. +`GtkDropDown` uses the [enum@Gtk.AccessibleRole.combo_box] role. @@ -43105,7 +44844,7 @@ with the button and popover nodes as children. Creates a new `GtkDropDown`. + line="869">Creates a new `GtkDropDown`. You may want to call [method@Gtk.DropDown.set_factory] to set up a way to map its items to widgets. @@ -43113,7 +44852,7 @@ to set up a way to map its items to widgets. a new `GtkDropDown` + line="879">a new `GtkDropDown` @@ -43123,7 +44862,7 @@ to set up a way to map its items to widgets. allow-none="1"> the model to use + line="871">the model to use allow-none="1"> the expression to use + line="872">the expression to use @@ -43141,20 +44880,20 @@ to set up a way to map its items to widgets. c:identifier="gtk_drop_down_new_from_strings"> Creates a new `GtkDropDown` that is populated with + line="899">Creates a new `GtkDropDown` that is populated with the strings. a new `GtkDropDown` + line="906">a new `GtkDropDown` The strings to put in the dropdown + line="901">The strings to put in the dropdown @@ -43164,22 +44903,21 @@ the strings. - Returns whether search is enabled. + line="1216">Returns whether search is enabled. %TRUE if the popup includes a search entry + line="1222">%TRUE if the popup includes a search entry a `GtkDropDown` + line="1218">a `GtkDropDown` @@ -43187,24 +44925,23 @@ the strings. - Gets the expression set that is used to obtain strings from items. + line="1267">Gets the expression set that is used to obtain strings from items. See [method@Gtk.DropDown.set_expression]. a `GtkExpression` + line="1275">a `GtkExpression` a `GtkDropDown` + line="1269">a `GtkDropDown` @@ -43212,10 +44949,9 @@ See [method@Gtk.DropDown.set_expression]. - Gets the factory that's currently used to populate list items. + line="989">Gets the factory that's currently used to populate list items. The factory returned by this function is always used for the item in the button. It is also used for items in the popup @@ -43224,14 +44960,14 @@ if [property@Gtk.DropDown:list-factory] is not set. The factory in use + line="999">The factory in use a `GtkDropDown` + line="991">a `GtkDropDown` @@ -43240,22 +44976,21 @@ if [property@Gtk.DropDown:list-factory] is not set. c:identifier="gtk_drop_down_get_header_factory" glib:get-property="header-factory" version="4.12"> - Gets the factory that's currently used to create header widgets for the popup. + line="1040">Gets the factory that's currently used to create header widgets for the popup. The factory in use + line="1046">The factory in use a `GtkDropDown` + line="1042">a `GtkDropDown` @@ -43263,22 +44998,21 @@ if [property@Gtk.DropDown:list-factory] is not set. - Gets the factory that's currently used to populate list items in the popup. + line="1082">Gets the factory that's currently used to populate list items in the popup. The factory in use + line="1088">The factory in use a `GtkDropDown` + line="1084">a `GtkDropDown` @@ -43286,22 +45020,21 @@ if [property@Gtk.DropDown:list-factory] is not set. - Gets the model that provides the displayed items. + line="914">Gets the model that provides the displayed items. The model in use + line="920">The model in use a `GtkDropDown` + line="916">a `GtkDropDown` @@ -43310,16 +45043,14 @@ if [property@Gtk.DropDown:list-factory] is not set. c:identifier="gtk_drop_down_get_search_match_mode" glib:get-property="search-match-mode" version="4.12"> - Returns the match mode that the search filter is using. + line="1354">Returns the match mode that the search filter is using. the match mode of the search filter + line="1360">the match mode of the search filter @@ -43327,7 +45058,7 @@ if [property@Gtk.DropDown:list-factory] is not set. a `GtkDropDown` + line="1356">a `GtkDropDown` @@ -43335,23 +45066,22 @@ if [property@Gtk.DropDown:list-factory] is not set. - Gets the position of the selected item. + line="1147">Gets the position of the selected item. the position of the selected item, or %GTK_INVALID_LIST_POSITION - if not item is selected + line="1153">the position of the selected item, or %GTK_INVALID_LIST_POSITION + if no item is selected a `GtkDropDown` + line="1149">a `GtkDropDown` @@ -43359,22 +45089,21 @@ if [property@Gtk.DropDown:list-factory] is not set. - Gets the selected item. If no item is selected, %NULL is returned. + line="1167">Gets the selected item. If no item is selected, %NULL is returned. The selected item + line="1173">The selected item a `GtkDropDown` + line="1169">a `GtkDropDown` @@ -43383,22 +45112,21 @@ if [property@Gtk.DropDown:list-factory] is not set. c:identifier="gtk_drop_down_get_show_arrow" glib:get-property="show-arrow" version="4.6"> - Returns whether to show an arrow within the widget. + line="1311">Returns whether to show an arrow within the widget. %TRUE if an arrow will be shown. + line="1317">%TRUE if an arrow will be shown. a `GtkDropDown` + line="1313">a `GtkDropDown` @@ -43406,10 +45134,9 @@ if [property@Gtk.DropDown:list-factory] is not set. - Sets whether a search entry will be shown in the popup that + line="1186">Sets whether a search entry will be shown in the popup that allows to search for items in the list. Note that [property@Gtk.DropDown:expression] must be set for @@ -43422,13 +45149,13 @@ search to work. a `GtkDropDown` + line="1188">a `GtkDropDown` whether to enable search + line="1189">whether to enable search @@ -43436,10 +45163,9 @@ search to work. - Sets the expression that gets evaluated to obtain strings from items. + line="1232">Sets the expression that gets evaluated to obtain strings from items. This is used for search in the popup. The expression must have a value type of %G_TYPE_STRING. @@ -43451,7 +45177,7 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1234">a `GtkDropDown` allow-none="1"> a `GtkExpression` + line="1235">a `GtkExpression` @@ -43468,10 +45194,9 @@ a value type of %G_TYPE_STRING. - Sets the `GtkListItemFactory` to use for populating list items. + line="1009">Sets the `GtkListItemFactory` to use for populating list items. @@ -43480,7 +45205,7 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1011">a `GtkDropDown` allow-none="1"> the factory to use + line="1012">the factory to use @@ -43498,10 +45223,9 @@ a value type of %G_TYPE_STRING. c:identifier="gtk_drop_down_set_header_factory" glib:set-property="header-factory" version="4.12"> - Sets the `GtkListItemFactory` to use for creating header widgets for the popup. + line="1058">Sets the `GtkListItemFactory` to use for creating header widgets for the popup. @@ -43510,7 +45234,7 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1060">a `GtkDropDown` allow-none="1"> the factory to use + line="1061">the factory to use @@ -43527,10 +45251,9 @@ a value type of %G_TYPE_STRING. - Sets the `GtkListItemFactory` to use for populating list items in the popup. + line="1098">Sets the `GtkListItemFactory` to use for populating list items in the popup. @@ -43539,7 +45262,7 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1100">a `GtkDropDown` allow-none="1"> the factory to use + line="1101">the factory to use @@ -43556,10 +45279,9 @@ a value type of %G_TYPE_STRING. - Sets the `GListModel` to use. + line="930">Sets the `GListModel` to use. @@ -43568,7 +45290,7 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="932">a `GtkDropDown` allow-none="1"> the model to use + line="933">the model to use @@ -43586,11 +45308,9 @@ a value type of %G_TYPE_STRING. c:identifier="gtk_drop_down_set_search_match_mode" glib:set-property="search-match-mode" version="4.12"> - Sets the match mode for the search filter. + line="1329">Sets the match mode for the search filter. @@ -43599,13 +45319,13 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1331">a `GtkDropDown` the new match mode + line="1332">the new match mode @@ -43614,10 +45334,9 @@ a value type of %G_TYPE_STRING. - Selects the item at the given position. + line="1125">Selects the item at the given position. @@ -43626,13 +45345,13 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1127">a `GtkDropDown` the position of the item to select, or %GTK_INVALID_LIST_POSITION + line="1128">the position of the item to select, or %GTK_INVALID_LIST_POSITION @@ -43641,10 +45360,9 @@ a value type of %G_TYPE_STRING. c:identifier="gtk_drop_down_set_show_arrow" glib:set-property="show-arrow" version="4.6"> - Sets whether an arrow will be displayed within the widget. + line="1285">Sets whether an arrow will be displayed within the widget. @@ -43653,13 +45371,13 @@ a value type of %G_TYPE_STRING. a `GtkDropDown` + line="1287">a `GtkDropDown` whether to show an arrow within the widget + line="1288">whether to show an arrow within the widget @@ -43670,13 +45388,9 @@ a value type of %G_TYPE_STRING. setter="set_enable_search" getter="get_enable_search" default-value="FALSE"> - - Whether to show a search entry in the popup. + line="629">Whether to show a search entry in the popup. Note that search requires [property@Gtk.DropDown:expression] to be set. @@ -43687,13 +45401,9 @@ to be set. transfer-ownership="none" setter="set_expression" getter="get_expression"> - - An expression to evaluate to obtain strings to match against the search + line="642">An expression to evaluate to obtain strings to match against the search term. See [property@Gtk.DropDown:enable-search] for how to enable search. @@ -43706,13 +45416,9 @@ used to bind strings to labels produced by a default factory. transfer-ownership="none" setter="set_factory" getter="get_factory"> - - Factory for populating list items. + line="562">Factory for populating list items. transfer-ownership="none" setter="set_header_factory" getter="get_header_factory"> - - The factory for creating header widgets for the popup. + line="572">The factory for creating header widgets for the popup. transfer-ownership="none" setter="set_list_factory" getter="get_list_factory"> - - The factory for populating list items in the popup. + line="584">The factory for populating list items in the popup. If this is not set, [property@Gtk.DropDown:factory] is used. @@ -43751,13 +45449,9 @@ If this is not set, [property@Gtk.DropDown:factory] is used. transfer-ownership="none" setter="set_model" getter="get_model"> - - Model for the displayed items. + line="596">Model for the displayed items. setter="set_search_match_mode" getter="get_search_match_mode" default-value="GTK_STRING_FILTER_MATCH_MODE_PREFIX"> - - The match mode for the search filter. + line="668">The match mode for the search filter. setter="set_selected" getter="get_selected" default-value="4294967295"> - - The position of the selected item. + line="606">The position of the selected item. If no item is selected, the property has the value %GTK_INVALID_LIST_POSITION. @@ -43797,11 +45483,9 @@ If no item is selected, the property has the value - The selected item. + line="619">The selected item. - - Whether to show an arrow within the GtkDropDown widget. + line="656">Whether to show an arrow within the GtkDropDown widget. Emitted to when the drop down is activated. + line="683">Emitted to when the drop down is activated. The `::activate` signal on `GtkDropDown` is an action signal and emitting it causes the drop down to pop up its dropdown. @@ -43849,7 +45529,7 @@ emitting it causes the drop down to pop up its dropdown. glib:type-struct="DropTargetClass"> `GtkDropTarget` is an event controller to receive Drag-and-Drop operations. + line="38">An event controller to receive Drag-and-Drop operations. The most basic way to use a `GtkDropTarget` to receive drops on a widget is to create it via [ctor@Gtk.DropTarget.new], passing in the @@ -43886,7 +45566,7 @@ my_widget_init (MyWidget *self) // This widget accepts two types of drop types: GFile objects // and GdkPixbuf objects - gtk_drop_target_set_gtypes (target, (GTypes [2]) { + gtk_drop_target_set_gtypes (target, (GType [2]) { G_TYPE_FILE, GDK_TYPE_PIXBUF, }, 2); @@ -43954,7 +45634,6 @@ If the drop target should support more than 1 type, pass - Gets the actions that this drop target supports. @@ -43978,7 +45657,6 @@ If the drop target should support more than 1 type, pass c:identifier="gtk_drop_target_get_current_drop" glib:get-property="current-drop" version="4.4"> - Gets the currently handled drop operation. @@ -44005,7 +45683,6 @@ If no drop operation is going on, %NULL is returned. glib:get-property="drop" deprecated="1" deprecated-version="4.4"> - Gets the currently handled drop operation. @@ -44031,7 +45708,6 @@ If no drop operation is going on, %NULL is returned. - Gets the data formats that this drop target accepts. @@ -44094,7 +45770,6 @@ If no types have been set, `NULL` will be returned. - Gets whether data should be preloaded on hover. @@ -44117,7 +45792,6 @@ If no types have been set, `NULL` will be returned. - Gets the current drop data, as a `GValue`. @@ -44164,7 +45838,6 @@ the data. - Sets the actions that this drop target supports. @@ -44190,7 +45863,7 @@ the data. Sets the supported `GTypes` for this drop target. + line="931">Sets the supported `GType`s for this drop target. @@ -44225,7 +45898,6 @@ the data. - Sets whether data should be preloaded on hover. @@ -44254,10 +45926,6 @@ the data. setter="set_actions" getter="get_actions" default-value="0"> - - The `GdkDragActions` that this drop target supports. @@ -44267,21 +45935,16 @@ the data. version="4.4" transfer-ownership="none" getter="get_current_drop"> - The `GdkDrop` that is currently being performed. - The `GdkDrop` that is currently being performed. @@ -44293,8 +45956,6 @@ the data. construct-only="1" transfer-ownership="none" getter="get_formats"> - The `GdkContentFormats` that determine the supported data formats. @@ -44306,10 +45967,6 @@ the data. setter="set_preload" getter="get_preload" default-value="FALSE"> - - Whether the drop data should be preloaded when the pointer is only @@ -44333,8 +45990,6 @@ so enabling it there is free. - The value for this drop operation. @@ -44496,8 +46151,7 @@ Its main purpose it to undo things done in glib:type-struct="DropTargetAsyncClass"> `GtkDropTargetAsync` is an event controller to receive Drag-and-Drop -operations, asynchronously. + line="38">An event controller to receive Drag-and-Drop operations, asynchronously. It is the more complete but also more complex method of handling drop operations compared to [class@Gtk.DropTarget], and you should only use @@ -44534,12 +46188,12 @@ state, which can be used by themes to style the widget as a drop target. Creates a new `GtkDropTargetAsync` object. + line="553">Creates a new `GtkDropTargetAsync` object. the new `GtkDropTargetAsync` + line="560">the new `GtkDropTargetAsync` @@ -44549,13 +46203,13 @@ state, which can be used by themes to style the widget as a drop target. allow-none="1"> the supported data formats + line="555">the supported data formats the supported actions + line="556">the supported actions @@ -44563,22 +46217,21 @@ state, which can be used by themes to style the widget as a drop target. - Gets the actions that this drop target supports. + line="644">Gets the actions that this drop target supports. the actions that this drop target supports + line="650">the actions that this drop target supports a `GtkDropTargetAsync` + line="646">a `GtkDropTargetAsync` @@ -44586,24 +46239,23 @@ state, which can be used by themes to style the widget as a drop target. - Gets the data formats that this drop target accepts. + line="605">Gets the data formats that this drop target accepts. If the result is %NULL, all formats are expected to be supported. the supported data formats + line="613">the supported data formats a `GtkDropTargetAsync` + line="607">a `GtkDropTargetAsync` @@ -44612,7 +46264,7 @@ If the result is %NULL, all formats are expected to be supported. c:identifier="gtk_drop_target_async_reject_drop"> Sets the @drop as not accepted on this drag site. + line="660">Sets the @drop as not accepted on this drag site. This function should be used when delaying the decision on whether to accept a drag or not until after reading @@ -44625,13 +46277,13 @@ the data. a `GtkDropTargetAsync` + line="662">a `GtkDropTargetAsync` the `GdkDrop` of an ongoing drag operation + line="663">the `GdkDrop` of an ongoing drag operation @@ -44639,10 +46291,9 @@ the data. - Sets the actions that this drop target supports. + line="623">Sets the actions that this drop target supports. @@ -44651,13 +46302,13 @@ the data. a `GtkDropTargetAsync` + line="625">a `GtkDropTargetAsync` the supported actions + line="626">the supported actions @@ -44665,10 +46316,9 @@ the data. - Sets the data formats that this drop target will accept. + line="578">Sets the data formats that this drop target will accept. @@ -44677,7 +46327,7 @@ the data. a `GtkDropTargetAsync` + line="580">a `GtkDropTargetAsync` allow-none="1"> the supported data formats or %NULL for any format + line="581">the supported data formats or %NULL for any format @@ -44697,13 +46347,9 @@ the data. setter="set_actions" getter="get_actions" default-value="0"> - - The `GdkDragActions` that this drop target supports. + line="382">The `GdkDragActions` that this drop target supports. transfer-ownership="none" setter="set_formats" getter="get_formats"> - - The `GdkContentFormats` that determines the supported data formats. + line="392">The `GdkContentFormats` that determines the supported data formats. Emitted on the drop site when a drop operation is about to begin. + line="404">Emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, %FALSE will be returned and the drop target will ignore the drop. If %TRUE is returned, the drop is accepted for now @@ -44741,14 +46383,14 @@ reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop].< %TRUE if @drop is accepted + line="425">%TRUE if @drop is accepted the `GdkDrop` + line="407">the `GdkDrop` @@ -44756,32 +46398,32 @@ reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop].< Emitted on the drop site when the pointer enters the widget. + line="440">Emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting. Preferred action for this drag operation. + line="451">Preferred action for this drag operation. the `GdkDrop` + line="443">the `GdkDrop` the x coordinate of the current pointer position + line="444">the x coordinate of the current pointer position the y coordinate of the current pointer position + line="445">the y coordinate of the current pointer position @@ -44789,7 +46431,7 @@ It can be used to set up custom highlighting. Emitted on the drop site when the pointer leaves the widget. + line="490">Emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in `GtkDropTargetAsync`::drag-enter. @@ -44800,7 +46442,7 @@ Its main purpose it to undo things done in the `GdkDrop` + line="493">the `GdkDrop` @@ -44808,30 +46450,30 @@ Its main purpose it to undo things done in Emitted while the pointer is moving over the drop target. + line="466">Emitted while the pointer is moving over the drop target. Preferred action for this drag operation. + line="475">Preferred action for this drag operation. the `GdkDrop` + line="469">the `GdkDrop` the x coordinate of the current pointer position + line="470">the x coordinate of the current pointer position the y coordinate of the current pointer position + line="471">the y coordinate of the current pointer position @@ -44839,7 +46481,7 @@ Its main purpose it to undo things done in Emitted on the drop site when the user drops the data onto the widget. + line="510">Emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no @@ -44856,26 +46498,26 @@ To receive the data, use one of the read functions provided by whether the drop is accepted at the given pointer position + line="532">whether the drop is accepted at the given pointer position the `GdkDrop` + line="513">the `GdkDrop` the x coordinate of the current pointer position + line="514">the x coordinate of the current pointer position the y coordinate of the current pointer position + line="515">the y coordinate of the current pointer position @@ -45190,7 +46832,7 @@ To receive the data, use one of the read functions provided by glib:type-struct="EditableInterface"> `GtkEditable` is an interface for text editing widgets. + line="25">Interface for single-line text editing widgets. Typical examples of editable widgets are [class@Gtk.Entry] and [class@Gtk.SpinButton]. It contains functions for generically manipulating @@ -45324,7 +46966,7 @@ to them on the delegate obtained via [method@Gtk.Editable.get_delegate]. c:identifier="gtk_editable_delegate_get_property"> Gets a property of the `GtkEditable` delegate for @object. + line="1119">Gets a property of the `GtkEditable` delegate for @object. This is helper function that should be called in the `get_property` function of your `GtkEditable` implementation, before handling your @@ -45333,32 +46975,32 @@ own properties. %TRUE if the property was found + line="1132">%TRUE if the property was found a `GObject` + line="1121">a `GObject` a property ID + line="1122">a property ID value to set + line="1123">value to set the `GParamSpec` for the property + line="1124">the `GParamSpec` for the property @@ -45367,7 +47009,7 @@ own properties. c:identifier="gtk_editable_delegate_set_property"> Sets a property on the `GtkEditable` delegate for @object. + line="1053">Sets a property on the `GtkEditable` delegate for @object. This is a helper function that should be called in the `set_property` function of your `GtkEditable` implementation, before handling your @@ -45376,32 +47018,32 @@ own properties. %TRUE if the property was found + line="1066">%TRUE if the property was found a `GObject` + line="1055">a `GObject` a property ID + line="1056">a property ID value to set + line="1057">value to set the `GParamSpec` for the property + line="1058">the `GParamSpec` for the property @@ -45410,7 +47052,7 @@ own properties. c:identifier="gtk_editable_install_properties"> Overrides the `GtkEditable` properties for @class. + line="937">Overrides the `GtkEditable` properties for @class. This is a helper function that should be called in class_init, after installing your own properties. @@ -45429,20 +47071,20 @@ property IDs for these properties. the number of properties that were installed + line="958">the number of properties that were installed a `GObjectClass` + line="939">a `GObjectClass` property ID to use for the first property + line="940">property ID to use for the first property @@ -45461,7 +47103,7 @@ property IDs for these properties. Deletes a sequence of characters. + line="498">Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is @@ -45477,19 +47119,19 @@ Note that the positions are specified in characters, not bytes. a `GtkEditable` + line="500">a `GtkEditable` start position + line="501">start position end position + line="502">end position @@ -45497,7 +47139,7 @@ Note that the positions are specified in characters, not bytes. Deletes a sequence of characters. + line="498">Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is @@ -45513,19 +47155,19 @@ Note that the positions are specified in characters, not bytes. a `GtkEditable` + line="500">a `GtkEditable` start position + line="501">start position end position + line="502">end position @@ -45576,7 +47218,7 @@ inserted text. Gets the `GtkEditable` that @editable is delegating its + line="999">Gets the `GtkEditable` that @editable is delegating its implementation to. Typically, the delegate is a [class@Gtk.Text] widget. @@ -45584,14 +47226,14 @@ Typically, the delegate is a [class@Gtk.Text] widget. the delegate `GtkEditable` + line="1008">the delegate `GtkEditable` a `GtkEditable` + line="1001">a `GtkEditable` @@ -45600,7 +47242,7 @@ Typically, the delegate is a [class@Gtk.Text] widget. invoker="get_selection_bounds"> Retrieves the selection bound of the editable. + line="660">Retrieves the selection bound of the editable. @start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical @@ -45611,14 +47253,14 @@ Note that positions are specified in characters, not bytes. %TRUE if there is a non-empty selection, %FALSE otherwise + line="674">%TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` + line="662">a `GtkEditable` allow-none="1"> location to store the starting position + line="663">location to store the starting position allow-none="1"> location to store the end position + line="664">location to store the end position - Retrieves the contents of @editable. + line="572">Retrieves the contents of @editable. The returned string is owned by GTK and must not be modified or freed. a pointer to the contents of the editable + line="580">a pointer to the contents of the editable a `GtkEditable` + line="574">a `GtkEditable` @@ -45714,7 +47355,7 @@ inserted text. Selects a region of text. + line="715">Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is @@ -45730,19 +47371,19 @@ Note that positions are specified in characters, not bytes. a `GtkEditable` + line="717">a `GtkEditable` start of region + line="718">start of region end of region + line="719">end of region @@ -45752,7 +47393,7 @@ Note that positions are specified in characters, not bytes. version="4.10"> Retrieves the accessible platform state from the editable delegate. + line="1196">Retrieves the accessible platform state from the editable delegate. This is an helper function to retrieve the accessible state for `GtkEditable` interface implementations using a delegate pattern. @@ -45774,22 +47415,34 @@ your_editable_get_accessible_platform_state (GtkAccessible *accessible, { return gtk_editable_delegate_get_accessible_platform_state (GTK_EDITABLE (accessible), state); } -``` +``` + +Note that the widget which is the delegate *must* be a direct child of +this widget, otherwise your implementation of [vfunc@Gtk.Accessible.get_platform_state] +might not even be called, as the platform change will originate from +the parent of the delegate, and, as a result, will not work properly. + +So, if you can't ensure the direct child condition, you should give the +delegate the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role, or you can +change your tree to allow this function to work. + the accessible platform state of the delegate a `GtkEditable` implementation + line="1198">a `GtkEditable` implementation what kind of accessible state to retrieve + line="1199">what kind of accessible state to retrieve @@ -45799,7 +47452,7 @@ your_editable_get_accessible_platform_state (GtkAccessible *accessible, c:identifier="gtk_editable_delete_selection"> Deletes the currently selected text of the editable. + line="696">Deletes the currently selected text of the editable. This call doesn’t do anything if there is no selected text. @@ -45810,7 +47463,7 @@ This call doesn’t do anything if there is no selected text. a `GtkEditable` + line="698">a `GtkEditable` @@ -45818,7 +47471,7 @@ This call doesn’t do anything if there is no selected text. Deletes a sequence of characters. + line="498">Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is @@ -45834,19 +47487,19 @@ Note that the positions are specified in characters, not bytes. a `GtkEditable` + line="500">a `GtkEditable` start position + line="501">start position end position + line="502">end position @@ -45855,7 +47508,7 @@ Note that the positions are specified in characters, not bytes. c:identifier="gtk_editable_finish_delegate"> Undoes the setup done by [method@Gtk.Editable.init_delegate]. + line="1036">Undoes the setup done by [method@Gtk.Editable.init_delegate]. This is a helper function that should be called from dispose, before removing the delegate object. @@ -45867,28 +47520,29 @@ before removing the delegate object. a `GtkEditable` + line="1038">a `GtkEditable` - - + Gets the alignment of the editable. + line="778">Gets the alignment of the editable. the alignment + line="784">the alignment a `GtkEditable` + line="780">a `GtkEditable` @@ -45896,7 +47550,7 @@ before removing the delegate object. Retrieves a sequence of characters. + line="525">Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, @@ -45908,7 +47562,7 @@ Note that positions are specified in characters, not bytes. a pointer to the contents of the widget as a + line="540">a pointer to the contents of the widget as a string. This string is allocated by the `GtkEditable` implementation and should be freed by the caller. @@ -45917,19 +47571,19 @@ Note that positions are specified in characters, not bytes. a `GtkEditable` + line="527">a `GtkEditable` start of text + line="528">start of text end of text + line="529">end of text @@ -45937,7 +47591,7 @@ Note that positions are specified in characters, not bytes. Gets the `GtkEditable` that @editable is delegating its + line="999">Gets the `GtkEditable` that @editable is delegating its implementation to. Typically, the delegate is a [class@Gtk.Text] widget. @@ -45945,14 +47599,14 @@ Typically, the delegate is a [class@Gtk.Text] widget. the delegate `GtkEditable` + line="1008">the delegate `GtkEditable` a `GtkEditable` + line="1001">a `GtkEditable` @@ -45960,22 +47614,21 @@ Typically, the delegate is a [class@Gtk.Text] widget. - Retrieves whether @editable is editable. + line="757">Retrieves whether @editable is editable. %TRUE if @editable is editable. + line="763">%TRUE if @editable is editable. a `GtkEditable` + line="759">a `GtkEditable` @@ -45983,22 +47636,21 @@ Typically, the delegate is a [class@Gtk.Text] widget. - Gets if undo/redo actions are enabled for @editable + line="896">Gets if undo/redo actions are enabled for @editable %TRUE if undo is enabled + line="902">%TRUE if undo is enabled a `GtkEditable` + line="898">a `GtkEditable` @@ -46006,31 +47658,31 @@ Typically, the delegate is a [class@Gtk.Text] widget. - Retrieves the desired maximum width of @editable, in characters. + line="860">Retrieves the desired maximum width of @editable, in characters. the maximum width of the entry, in characters + line="866">the maximum width of the entry, in characters a `GtkEditable` + line="862">a `GtkEditable` - - + Retrieves the current position of the cursor relative + line="637">Retrieves the current position of the cursor relative to the start of the content of the editable. Note that this position is in characters, not in bytes. @@ -46038,14 +47690,14 @@ Note that this position is in characters, not in bytes. the cursor position + line="646">the cursor position a `GtkEditable` + line="639">a `GtkEditable` @@ -46054,7 +47706,7 @@ Note that this position is in characters, not in bytes. c:identifier="gtk_editable_get_selection_bounds"> Retrieves the selection bound of the editable. + line="660">Retrieves the selection bound of the editable. @start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical @@ -46065,14 +47717,14 @@ Note that positions are specified in characters, not bytes. %TRUE if there is a non-empty selection, %FALSE otherwise + line="674">%TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` + line="662">a `GtkEditable` allow-none="1"> location to store the starting position + line="663">location to store the starting position allow-none="1"> location to store the end position + line="664">location to store the end position @@ -46102,24 +47754,23 @@ Note that positions are specified in characters, not bytes. - Retrieves the contents of @editable. + line="572">Retrieves the contents of @editable. The returned string is owned by GTK and must not be modified or freed. a pointer to the contents of the editable + line="580">a pointer to the contents of the editable a `GtkEditable` + line="574">a `GtkEditable` @@ -46127,23 +47778,22 @@ The returned string is owned by GTK and must not be modified or freed. - Gets the number of characters of space reserved + line="818">Gets the number of characters of space reserved for the contents of the editable. number of chars to request space for, or negative if unset + line="825">number of chars to request space for, or negative if unset a `GtkEditable` + line="820">a `GtkEditable` @@ -46151,7 +47801,7 @@ for the contents of the editable. Sets up a delegate for `GtkEditable`. + line="1016">Sets up a delegate for `GtkEditable`. This is assuming that the get_delegate vfunc in the `GtkEditable` interface has been set up for the @editable's type. @@ -46166,7 +47816,7 @@ after creating the delegate object. a `GtkEditable` + line="1018">a `GtkEditable` @@ -46217,7 +47867,7 @@ inserted text. Selects a region of text. + line="715">Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is @@ -46233,28 +47883,29 @@ Note that positions are specified in characters, not bytes. a `GtkEditable` + line="717">a `GtkEditable` start of region + line="718">start of region end of region + line="719">end of region - - + Sets the alignment for the contents of the editable. + line="798">Sets the alignment for the contents of the editable. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the editable. @@ -46266,13 +47917,13 @@ the displayed text is shorter than the width of the editable. a `GtkEditable` + line="800">a `GtkEditable` The horizontal alignment, from 0 (left) to 1 (right). + line="801">The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts @@ -46281,10 +47932,9 @@ the displayed text is shorter than the width of the editable. - Determines if the user can edit the text in the editable widget. + line="740">Determines if the user can edit the text in the editable widget. @@ -46293,13 +47943,13 @@ the displayed text is shorter than the width of the editable. a `GtkEditable` + line="742">a `GtkEditable` %TRUE if the user is allowed to edit the text + line="743">%TRUE if the user is allowed to edit the text in the widget @@ -46308,10 +47958,9 @@ the displayed text is shorter than the width of the editable. - If enabled, changes to @editable will be saved for undo/redo + line="916">If enabled, changes to @editable will be saved for undo/redo actions. This results in an additional copy of text changes and are not @@ -46325,13 +47974,13 @@ when [property@Gtk.Text:visibility] is set to %FALSE. a `GtkEditable` + line="918">a `GtkEditable` if undo/redo should be enabled + line="919">if undo/redo should be enabled @@ -46339,10 +47988,9 @@ when [property@Gtk.Text:visibility] is set to %FALSE. - Sets the desired maximum width in characters of @editable. + line="880">Sets the desired maximum width in characters of @editable. @@ -46351,22 +47999,23 @@ when [property@Gtk.Text:visibility] is set to %FALSE. a `GtkEditable` + line="882">a `GtkEditable` the new desired maximum width, in characters + line="883">the new desired maximum width, in characters - - + Sets the cursor position in the editable to the given value. + line="615">Sets the cursor position in the editable to the given value. The cursor is displayed before the character with the given (base 0) index in the contents of the editable. The value must be less than @@ -46381,13 +48030,13 @@ of the editable. Note that @position is in characters, not in bytes. a `GtkEditable` + line="617">a `GtkEditable` the position of the cursor + line="618">the position of the cursor @@ -46395,10 +48044,9 @@ of the editable. Note that @position is in characters, not in bytes. - Sets the text in the editable to the given value. + line="590">Sets the text in the editable to the given value. This is replacing the current contents. @@ -46409,13 +48057,13 @@ This is replacing the current contents. a `GtkEditable` + line="592">a `GtkEditable` the text to set + line="593">the text to set @@ -46423,10 +48071,9 @@ This is replacing the current contents. - Changes the size request of the editable to be about the + line="839">Changes the size request of the editable to be about the right size for @n_chars characters. Note that it changes the size request, the size can still @@ -46440,24 +48087,22 @@ If @n_chars is -1, the size reverts to the default size. a `GtkEditable` + line="841">a `GtkEditable` width in chars + line="842">width in chars - - The current position of the insertion cursor in chars. @@ -46469,10 +48114,6 @@ If @n_chars is -1, the size reverts to the default size. setter="set_editable" getter="get_editable" default-value="TRUE"> - - Whether the entry contents can be edited. @@ -46484,10 +48125,6 @@ If @n_chars is -1, the size reverts to the default size. setter="set_enable_undo" getter="get_enable_undo" default-value="TRUE"> - - If undo/redo should be enabled for the editable. @@ -46499,10 +48136,6 @@ If @n_chars is -1, the size reverts to the default size. setter="set_max_width_chars" getter="get_max_width_chars" default-value="-1"> - - The desired maximum width of the entry, in characters. @@ -46521,8 +48154,6 @@ If @n_chars is -1, the size reverts to the default size. transfer-ownership="none" setter="set_text" getter="get_text"> - - The contents of the entry. @@ -46534,10 +48165,6 @@ If @n_chars is -1, the size reverts to the default size. setter="set_width_chars" getter="get_width_chars" default-value="-1"> - - Number of characters to leave space for in the entry. @@ -46546,11 +48173,9 @@ If @n_chars is -1, the size reverts to the default size. - - The horizontal alignment, from 0 (left) to 1 (right). @@ -46698,19 +48323,19 @@ to modify the inserted text, or prevent it from being inserted entirely. a `GtkEditable` + line="500">a `GtkEditable` start position + line="501">start position end position + line="502">end position @@ -46735,14 +48360,14 @@ to modify the inserted text, or prevent it from being inserted entirely. a pointer to the contents of the editable + line="580">a pointer to the contents of the editable a `GtkEditable` + line="574">a `GtkEditable` @@ -46795,19 +48420,19 @@ to modify the inserted text, or prevent it from being inserted entirely. a `GtkEditable` + line="500">a `GtkEditable` start position + line="501">start position end position + line="502">end position @@ -46819,14 +48444,14 @@ to modify the inserted text, or prevent it from being inserted entirely. %TRUE if there is a non-empty selection, %FALSE otherwise + line="674">%TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` + line="662">a `GtkEditable` allow-none="1"> location to store the starting position + line="663">location to store the starting position allow-none="1"> location to store the end position + line="664">location to store the end position @@ -46864,19 +48489,19 @@ to modify the inserted text, or prevent it from being inserted entirely. a `GtkEditable` + line="717">a `GtkEditable` start of region + line="718">start of region end of region + line="719">end of region @@ -46888,14 +48513,14 @@ to modify the inserted text, or prevent it from being inserted entirely. the delegate `GtkEditable` + line="1008">the delegate `GtkEditable` a `GtkEditable` + line="1001">a `GtkEditable` @@ -46911,10 +48536,12 @@ to modify the inserted text, or prevent it from being inserted entirely. glib:type-struct="EditableLabelClass"> A `GtkEditableLabel` is a label that allows users to -edit the text by switching to an “edit mode”. + line="38">Allows users to edit the displayed text by switching to an “edit mode”. -![An example GtkEditableLabel](editable-label.png) +<picture> + <source srcset="editable-label-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkEditableLabel" src="editable-label.png"> +</picture> `GtkEditableLabel` does not have API of its own, but it implements the [iface@Gtk.Editable] interface. @@ -46924,6 +48551,20 @@ to click or press the Enter key. The default bindings for leaving the edit mode are the Enter key (to save the results) or the Escape key (to cancel the editing). +# Shortcuts and Gestures + +`GtkEditableLabel` supports the following keyboard shortcuts: + +- <kbd>Enter</kbd> starts editing. +- <kbd>Escape</kbd> stops editing. + +# Actions + +`GtkEditableLabel` defines a set of built-in actions: + +- `editing.starts` switches the widget into editing mode. +- `editing.stop` switches the widget out of editing mode. + # CSS nodes ``` @@ -46947,19 +48588,19 @@ see [class@Gtk.Text]. Creates a new `GtkEditableLabel` widget. + line="581">Creates a new `GtkEditableLabel` widget. the new `GtkEditableLabel` + line="587">the new `GtkEditableLabel` the text for the label + line="583">the text for the label @@ -46967,22 +48608,21 @@ see [class@Gtk.Text]. - Returns whether the label is currently in “editing mode”. + line="597">Returns whether the label is currently in “editing mode”. %TRUE if @self is currently in editing mode + line="603">%TRUE if @self is currently in editing mode a `GtkEditableLabel` + line="599">a `GtkEditableLabel` @@ -46991,7 +48631,7 @@ see [class@Gtk.Text]. c:identifier="gtk_editable_label_start_editing"> Switches the label into “editing mode”. + line="613">Switches the label into “editing mode”. @@ -47000,7 +48640,7 @@ see [class@Gtk.Text]. a `GtkEditableLabel` + line="615">a `GtkEditableLabel` @@ -47009,7 +48649,7 @@ see [class@Gtk.Text]. c:identifier="gtk_editable_label_stop_editing"> Switches the label out of “editing mode”. + line="635">Switches the label out of “editing mode”. If @commit is %TRUE, the resulting text is kept as the [property@Gtk.Editable:text] property value, otherwise the @@ -47023,13 +48663,13 @@ previous [property@Gtk.Editable:text] property value. a `GtkEditableLabel` + line="637">a `GtkEditableLabel` whether to set the edited text on the label + line="638">whether to set the edited text on the label @@ -47039,11 +48679,9 @@ previous [property@Gtk.Editable:text] property value. transfer-ownership="none" getter="get_editing" default-value="FALSE"> - This property is %TRUE while the widget is in edit mode. + line="506">This property is %TRUE while the widget is in edit mode. @@ -47156,14 +48794,29 @@ implement the `GtkEditable` interface. glib:type-struct="EmojiChooserClass"> The `GtkEmojiChooser` is used by text widgets such as `GtkEntry` or -`GtkTextView` to let users insert Emoji characters. + line="40">Used by text widgets to let users insert Emoji characters. -![An example GtkEmojiChooser](emojichooser.png) +<picture> + <source srcset="emojichooser-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkEmojiChooser" src="emojichooser.png"> +</picture> `GtkEmojiChooser` emits the [signal@Gtk.EmojiChooser::emoji-picked] signal when an Emoji is selected. +# Shortcuts and Gestures + +`GtkEmojiChooser` supports the following keyboard shortcuts: + +- <kbd>Ctrl</kbd>+<kbd>N</kbd> scrolls th the next section. +- <kbd>Ctrl</kbd>+<kbd>P</kbd> scrolls th the previous section. + +# Actions + +`GtkEmojiChooser` defines a set of built-in actions: + +- `scroll.section` scrolls to the next or previous section. + # CSS nodes ``` @@ -47193,19 +48846,19 @@ consists of buttons with the .emoji-section style class and gets the Creates a new `GtkEmojiChooser`. + line="1398">Creates a new `GtkEmojiChooser`. a new `GtkEmojiChooser` + line="1403">a new `GtkEmojiChooser` Emitted when the user selects an Emoji. + line="1316">Emitted when the user selects an Emoji. @@ -47213,7 +48866,7 @@ consists of buttons with the .emoji-section style class and gets the the Unicode sequence for the picked Emoji, in UTF-8 + line="1319">the Unicode sequence for the picked Emoji, in UTF-8 @@ -47235,9 +48888,12 @@ consists of buttons with the .emoji-section style class and gets the glib:type-struct="EntryClass"> `GtkEntry` is a single line text entry widget. + line="65">A single-line text entry widget. -![An example GtkEntry](entry.png) +<picture> + <source srcset="entry-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkEntry" src="entry.png"> +</picture> A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget @@ -47321,7 +48977,7 @@ content instead. # Accessibility -`GtkEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role. +`GtkEntry` uses the [enum@Gtk.AccessibleRole.text_box] role. @@ -47331,12 +48987,12 @@ content instead. Creates a new entry. + line="1998">Creates a new entry. a new `GtkEntry`. + line="2003">a new `GtkEntry`. @@ -47344,24 +49000,28 @@ content instead. c:identifier="gtk_entry_new_with_buffer"> Creates a new entry with the specified text buffer. + line="2011">Creates a new entry with the specified text buffer. a new `GtkEntry` + line="2017">a new `GtkEntry` The buffer to use for the new `GtkEntry`. + line="2013">The buffer to use for the new `GtkEntry`. + Class handler for the `GtkEntry::activate` signal. The default + implementation activates the gtk.activate-default action. @@ -47375,23 +49035,21 @@ content instead. - Retrieves the value set by gtk_entry_set_activates_default(). + line="2314">Retrieves the value set by gtk_entry_set_activates_default(). %TRUE if the entry will activate the default widget + line="2320">%TRUE if the entry will activate the default widget a `GtkEntry` + line="2316">a `GtkEntry` @@ -47399,21 +49057,21 @@ content instead. Gets the value set by gtk_entry_set_alignment(). + line="2398">Gets the value set by gtk_entry_set_alignment(). See also: [property@Gtk.Editable:xalign] the alignment + line="2406">the alignment a `GtkEntry` + line="2400">a `GtkEntry` @@ -47421,24 +49079,23 @@ See also: [property@Gtk.Editable:xalign] - Gets the attribute list of the `GtkEntry`. + line="3583">Gets the attribute list of the `GtkEntry`. See [method@Gtk.Entry.set_attributes]. the attribute list + line="3591">the attribute list a `GtkEntry` + line="3585">a `GtkEntry` @@ -47446,23 +49103,22 @@ See [method@Gtk.Entry.set_attributes]. - Get the `GtkEntryBuffer` object which holds the text for + line="2035">Get the `GtkEntryBuffer` object which holds the text for this widget. A `GtkEntryBuffer` object. + line="2042">A `GtkEntryBuffer` object. a `GtkEntry` + line="2037">a `GtkEntry` @@ -47472,17 +49128,16 @@ this widget. glib:get-property="completion" deprecated="1" deprecated-version="4.10"> - Returns the auxiliary completion object currently + line="3260">Returns the auxiliary completion object currently in use by @entry. GtkEntryCompletion will be removed in GTK 5. The auxiliary + line="3267">The auxiliary completion object currently in use by @entry @@ -47490,7 +49145,7 @@ in use by @entry. A `GtkEntry` + line="3262">A `GtkEntry` @@ -47499,13 +49154,13 @@ in use by @entry. c:identifier="gtk_entry_get_current_icon_drag_source"> Returns the index of the icon which is the source of the + line="2901">Returns the index of the icon which is the source of the current DND operation, or -1. index of the icon which is the source of the + line="2908">index of the icon which is the source of the current DND operation, or -1. @@ -47513,7 +49168,7 @@ current DND operation, or -1. a `GtkEntry` + line="2903">a `GtkEntry` @@ -47521,22 +49176,21 @@ current DND operation, or -1. - Gets the menu model set with gtk_entry_set_extra_menu(). + line="3745">Gets the menu model set with gtk_entry_set_extra_menu(). the menu model + line="3751">the menu model a `GtkEntry` + line="3747">a `GtkEntry` @@ -47544,22 +49198,21 @@ current DND operation, or -1. - Gets the value set by gtk_entry_set_has_frame(). + line="2358">Gets the value set by gtk_entry_set_has_frame(). whether the entry has a beveled frame + line="2364">whether the entry has a beveled frame a `GtkEntry` + line="2360">a `GtkEntry` @@ -47568,25 +49221,25 @@ current DND operation, or -1. c:identifier="gtk_entry_get_icon_activatable"> Returns whether the icon is activatable. + line="2619">Returns whether the icon is activatable. %TRUE if the icon is activatable. + line="2626">%TRUE if the icon is activatable. a `GtkEntry` + line="2621">a `GtkEntry` Icon position + line="2622">Icon position @@ -47594,7 +49247,7 @@ current DND operation, or -1. Gets the area where entry’s icon at @icon_pos is drawn. + line="2932">Gets the area where entry’s icon at @icon_pos is drawn. This function is useful when drawing something to the entry in a draw callback. @@ -47611,13 +49264,13 @@ relative to @entry's allocation. A `GtkEntry` + line="2934">A `GtkEntry` Icon position + line="2935">Icon position transfer-ownership="none"> Return location for the icon’s area + line="2936">Return location for the icon’s area @@ -47634,36 +49287,36 @@ relative to @entry's allocation. Finds the icon at the given position and return its index. + line="2826">Finds the icon at the given position and return its index. The position’s coordinates are relative to the @entry’s top left corner. If @x, @y doesn’t lie inside an icon, -1 is returned. This function is intended for use in a - [signal@Gtk.Widget::query-tooltip] signal handler. +[signal@Gtk.Widget::query-tooltip] signal handler. the index of the icon at the given position, or -1 + line="2839">the index of the icon at the given position, or -1 a `GtkEntry` + line="2828">a `GtkEntry` the x coordinate of the position to find, relative to @entry + line="2829">the x coordinate of the position to find, relative to @entry the y coordinate of the position to find, relative to @entry + line="2830">the y coordinate of the position to find, relative to @entry @@ -47671,7 +49324,7 @@ top left corner. If @x, @y doesn’t lie inside an icon, Retrieves the `GIcon` used for the icon. + line="2674">Retrieves the `GIcon` used for the icon. %NULL will be returned if there is no icon or if the icon was set by some other method (e.g., by `GdkPaintable` or icon name). @@ -47679,20 +49332,20 @@ set by some other method (e.g., by `GdkPaintable` or icon name). A `GIcon` + line="2684">A `GIcon` A `GtkEntry` + line="2676">A `GtkEntry` Icon position + line="2677">Icon position @@ -47700,7 +49353,7 @@ set by some other method (e.g., by `GdkPaintable` or icon name). Retrieves the icon name used for the icon. + line="2704">Retrieves the icon name used for the icon. %NULL is returned if there is no icon or if the icon was set by some other method (e.g., by `GdkPaintable` or gicon). @@ -47708,20 +49361,20 @@ by some other method (e.g., by `GdkPaintable` or gicon). An icon name + line="2714">An icon name A `GtkEntry` + line="2706">A `GtkEntry` Icon position + line="2707">Icon position @@ -47730,14 +49383,14 @@ by some other method (e.g., by `GdkPaintable` or gicon). c:identifier="gtk_entry_get_icon_paintable"> Retrieves the `GdkPaintable` used for the icon. + line="2643">Retrieves the `GdkPaintable` used for the icon. If no `GdkPaintable` was used for the icon, %NULL is returned. A `GdkPaintable` + line="2652">A `GdkPaintable` if no icon is set for this position or the icon set is not a `GdkPaintable`. @@ -47746,13 +49399,13 @@ If no `GdkPaintable` was used for the icon, %NULL is returned. A `GtkEntry` + line="2645">A `GtkEntry` Icon position + line="2646">Icon position @@ -47761,25 +49414,25 @@ If no `GdkPaintable` was used for the icon, %NULL is returned. c:identifier="gtk_entry_get_icon_sensitive"> Returns whether the icon appears sensitive or insensitive. + line="2768">Returns whether the icon appears sensitive or insensitive. %TRUE if the icon is sensitive. + line="2775">%TRUE if the icon is sensitive. a `GtkEntry` + line="2770">a `GtkEntry` Icon position + line="2771">Icon position @@ -47788,7 +49441,7 @@ If no `GdkPaintable` was used for the icon, %NULL is returned. c:identifier="gtk_entry_get_icon_storage_type"> Gets the type of representation being used by the icon + line="2795">Gets the type of representation being used by the icon to store image data. If the icon has no image data, the return value will @@ -47797,20 +49450,20 @@ be %GTK_IMAGE_EMPTY. image representation being used + line="2806">image representation being used a `GtkEntry` + line="2797">a `GtkEntry` Icon position + line="2798">Icon position @@ -47819,26 +49472,26 @@ be %GTK_IMAGE_EMPTY. c:identifier="gtk_entry_get_icon_tooltip_markup"> Gets the contents of the tooltip on the icon at the specified + line="3096">Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text + line="3104">the tooltip text a `GtkEntry` + line="3098">a `GtkEntry` the icon position + line="3099">the icon position @@ -47847,26 +49500,26 @@ position in @entry. c:identifier="gtk_entry_get_icon_tooltip_text"> Gets the contents of the tooltip on the icon at the specified + line="3007">Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text + line="3015">the tooltip text a `GtkEntry` + line="3009">a `GtkEntry` the icon position + line="3010">the icon position @@ -47874,22 +49527,21 @@ position in @entry. - Gets the input hints of this `GtkEntry`. + line="3541">Gets the input hints of this `GtkEntry`. the input hints + line="3547">the input hints a `GtkEntry` + line="3543">a `GtkEntry` @@ -47897,22 +49549,21 @@ position in @entry. - Gets the input purpose of the `GtkEntry`. + line="3503">Gets the input purpose of the `GtkEntry`. the input purpose + line="3509">the input purpose a `GtkEntry` + line="3505">a `GtkEntry` @@ -47920,16 +49571,15 @@ position in @entry. - Retrieves the character displayed in place of the actual text + line="2149">Retrieves the character displayed in place of the actual text in “password mode”. the current invisible char, or 0, if the entry does not + line="2156">the current invisible char, or 0, if the entry does not show invisible text at all. @@ -47937,7 +49587,7 @@ in “password mode”. a `GtkEntry` + line="2151">a `GtkEntry` @@ -47945,17 +49595,16 @@ in “password mode”. - Retrieves the maximum allowed length of the text in @entry. + line="2249">Retrieves the maximum allowed length of the text in @entry. See [method@Gtk.Entry.set_max_length]. the maximum allowed number of characters + line="2257">the maximum allowed number of characters in `GtkEntry`, or 0 if there is no maximum. @@ -47963,7 +49612,7 @@ See [method@Gtk.Entry.set_max_length]. a `GtkEntry` + line="2251">a `GtkEntry` @@ -47971,22 +49620,21 @@ See [method@Gtk.Entry.set_max_length]. - Gets whether the `GtkEntry` is in overwrite mode. + line="2204">Gets whether the `GtkEntry` is in overwrite mode. whether the text is overwritten when typing. + line="2210">whether the text is overwritten when typing. a `GtkEntry` + line="2206">a `GtkEntry` @@ -47994,17 +49642,15 @@ See [method@Gtk.Entry.set_max_length]. - Retrieves the text that will be displayed when @entry + line="3460">Retrieves the text that will be displayed when @entry is empty and unfocused a pointer to the + line="3467">a pointer to the placeholder text as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored. If no placeholder @@ -48015,7 +49661,7 @@ is empty and unfocused a `GtkEntry` + line="3462">a `GtkEntry` @@ -48023,25 +49669,23 @@ is empty and unfocused - Returns the current fraction of the task that’s been completed. + line="3336">Returns the current fraction of the task that’s been completed. See [method@Gtk.Entry.set_progress_fraction]. a fraction from 0.0 to 1.0 + line="3344">a fraction from 0.0 to 1.0 a `GtkEntry` + line="3338">a `GtkEntry` @@ -48049,24 +49693,22 @@ See [method@Gtk.Entry.set_progress_fraction]. - Retrieves the pulse step set with + line="3389">Retrieves the pulse step set with gtk_entry_set_progress_pulse_step(). a fraction from 0.0 to 1.0 + line="3396">a fraction from 0.0 to 1.0 a `GtkEntry` + line="3391">a `GtkEntry` @@ -48074,24 +49716,23 @@ gtk_entry_set_progress_pulse_step(). - Gets the tabstops of the `GtkEntry`. + line="3624">Gets the tabstops of the `GtkEntry`. See [method@Gtk.Entry.set_tabs]. the tabstops + line="3632">the tabstops a `GtkEntry` + line="3626">a `GtkEntry` @@ -48099,10 +49740,9 @@ See [method@Gtk.Entry.set_tabs]. - Retrieves the current length of the text in @entry. + line="2270">Retrieves the current length of the text in @entry. This is equivalent to getting @entry's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. @@ -48110,7 +49750,7 @@ and calling [method@Gtk.EntryBuffer.get_length] on it. the current number of characters + line="2279">the current number of characters in `GtkEntry`, or 0 if there are none. @@ -48118,7 +49758,7 @@ and calling [method@Gtk.EntryBuffer.get_length] on it. a `GtkEntry` + line="2272">a `GtkEntry` @@ -48126,24 +49766,23 @@ and calling [method@Gtk.EntryBuffer.get_length] on it. - Retrieves whether the text in @entry is visible. + line="2102">Retrieves whether the text in @entry is visible. See [method@Gtk.Entry.set_visibility]. %TRUE if the text is currently visible + line="2110">%TRUE if the text is currently visible a `GtkEntry` + line="2104">a `GtkEntry` @@ -48152,7 +49791,7 @@ See [method@Gtk.Entry.set_visibility]. c:identifier="gtk_entry_grab_focus_without_selecting"> Causes @entry to have keyboard focus. + line="1823">Causes @entry to have keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't select the contents of the entry. You only want to call this on some @@ -48162,14 +49801,14 @@ in, such as search-as-you-type entries. %TRUE if focus is now inside @self + line="1834">%TRUE if focus is now inside @self a `GtkEntry` + line="1825">a `GtkEntry` @@ -48177,7 +49816,7 @@ in, such as search-as-you-type entries. Indicates that some progress is made, but you don’t + line="3411">Indicates that some progress is made, but you don’t know how much. Causes the entry’s progress indicator to enter “activity @@ -48193,7 +49832,7 @@ by [method@Gtk.Entry.set_progress_pulse_step]). a `GtkEntry` + line="3413">a `GtkEntry` @@ -48202,7 +49841,7 @@ by [method@Gtk.Entry.set_progress_pulse_step]). c:identifier="gtk_entry_reset_im_context"> Reset the input method context of the entry if needed. + line="1919">Reset the input method context of the entry if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. @@ -48214,7 +49853,7 @@ would confuse on-going input method behavior. a `GtkEntry` + line="1921">a `GtkEntry` @@ -48222,11 +49861,9 @@ would confuse on-going input method behavior. - Sets whether pressing Enter in the @entry will activate the default + line="2292">Sets whether pressing Enter in the @entry will activate the default widget for the window containing the entry. This usually means that the dialog containing the entry will be closed, @@ -48239,13 +49876,13 @@ since the default widget is usually one of the dialog buttons. a `GtkEntry` + line="2294">a `GtkEntry` %TRUE to activate window’s default widget on Enter keypress + line="2295">%TRUE to activate window’s default widget on Enter keypress @@ -48253,7 +49890,7 @@ since the default widget is usually one of the dialog buttons. Sets the alignment for the contents of the entry. + line="2374">Sets the alignment for the contents of the entry. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the entry. @@ -48267,13 +49904,13 @@ See also: [property@Gtk.Editable:xalign] a `GtkEntry` + line="2376">a `GtkEntry` The horizontal alignment, from 0 (left) to 1 (right). + line="2377">The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts @@ -48282,10 +49919,9 @@ See also: [property@Gtk.Editable:xalign] - Sets a `PangoAttrList`. + line="3559">Sets a `PangoAttrList`. The attributes in the list are applied to the entry text. @@ -48300,13 +49936,13 @@ with unlimited extent. a `GtkEntry` + line="3561">a `GtkEntry` a `PangoAttrList` + line="3562">a `PangoAttrList` @@ -48314,10 +49950,9 @@ with unlimited extent. - Set the `GtkEntryBuffer` object which holds the text for + line="2052">Set the `GtkEntryBuffer` object which holds the text for this widget. @@ -48327,13 +49962,13 @@ this widget. a `GtkEntry` + line="2054">a `GtkEntry` a `GtkEntryBuffer` + line="2055">a `GtkEntryBuffer` @@ -48343,10 +49978,9 @@ this widget. glib:set-property="completion" deprecated="1" deprecated-version="4.10"> - Sets @completion to be the auxiliary completion object + line="3210">Sets @completion to be the auxiliary completion object to use with @entry. All further configuration of the completion mechanism is @@ -48361,7 +49995,7 @@ Completion is disabled if @completion is set to %NULL. A `GtkEntry` + line="3212">A `GtkEntry` allow-none="1"> The `GtkEntryCompletion` + line="3213">The `GtkEntryCompletion` @@ -48378,10 +50012,9 @@ Completion is disabled if @completion is set to %NULL. - Sets a menu model to add when constructing + line="3724">Sets a menu model to add when constructing the context menu for @entry. @@ -48391,7 +50024,7 @@ the context menu for @entry. a `GtkEntry` + line="3726">a `GtkEntry` allow-none="1"> a `GMenuModel` + line="3727">a `GMenuModel` @@ -48408,10 +50041,9 @@ the context menu for @entry. - Sets whether the entry has a beveled frame around it. + line="2332">Sets whether the entry has a beveled frame around it. @@ -48420,13 +50052,13 @@ the context menu for @entry. a `GtkEntry` + line="2334">a `GtkEntry` new value + line="2335">new value @@ -48435,7 +50067,7 @@ the context menu for @entry. c:identifier="gtk_entry_set_icon_activatable"> Sets whether the icon is activatable. + line="2584">Sets whether the icon is activatable. @@ -48444,19 +50076,19 @@ the context menu for @entry. A `GtkEntry` + line="2586">A `GtkEntry` Icon position + line="2587">Icon position %TRUE if the icon should be activatable + line="2588">%TRUE if the icon should be activatable @@ -48465,7 +50097,7 @@ the context menu for @entry. c:identifier="gtk_entry_set_icon_drag_source"> Sets up the icon at the given position as drag source. + line="2870">Sets up the icon at the given position as drag source. This makes it so that GTK will start a drag operation when the user clicks and drags the icon. @@ -48477,25 +50109,25 @@ operation when the user clicks and drags the icon. a `GtkEntry` + line="2872">a `GtkEntry` icon position + line="2873">icon position a `GdkContentProvider` + line="2874">a `GdkContentProvider` a bitmask of the allowed drag actions + line="2875">a bitmask of the allowed drag actions @@ -48504,7 +50136,7 @@ operation when the user clicks and drags the icon. c:identifier="gtk_entry_set_icon_from_gicon"> Sets the icon shown in the entry at the specified position + line="2529">Sets the icon shown in the entry at the specified position from the current icon theme. If the icon isn’t known, a “broken image” icon will be @@ -48520,13 +50152,13 @@ specified position. A `GtkEntry` + line="2531">A `GtkEntry` The position at which to set the icon + line="2532">The position at which to set the icon allow-none="1"> The icon to set + line="2533">The icon to set @@ -48544,7 +50176,7 @@ specified position. c:identifier="gtk_entry_set_icon_from_icon_name"> Sets the icon shown in the entry at the specified position + line="2473">Sets the icon shown in the entry at the specified position from the current icon theme. If the icon name isn’t known, a “broken image” icon will be @@ -48560,13 +50192,13 @@ specified position. A `GtkEntry` + line="2475">A `GtkEntry` The position at which to set the icon + line="2476">The position at which to set the icon allow-none="1"> An icon name + line="2477">An icon name @@ -48584,7 +50216,7 @@ specified position. c:identifier="gtk_entry_set_icon_from_paintable"> Sets the icon shown in the specified position using a `GdkPaintable`. + line="2418">Sets the icon shown in the specified position using a `GdkPaintable`. If @paintable is %NULL, no icon will be shown in the specified position. @@ -48595,13 +50227,13 @@ If @paintable is %NULL, no icon will be shown in the specified position. a `GtkEntry` + line="2420">a `GtkEntry` Icon position + line="2421">Icon position allow-none="1"> A `GdkPaintable` + line="2422">A `GdkPaintable` @@ -48619,7 +50251,7 @@ If @paintable is %NULL, no icon will be shown in the specified position. c:identifier="gtk_entry_set_icon_sensitive"> Sets the sensitivity for the specified icon. + line="2734">Sets the sensitivity for the specified icon. @@ -48628,19 +50260,19 @@ If @paintable is %NULL, no icon will be shown in the specified position. A `GtkEntry` + line="2736">A `GtkEntry` Icon position + line="2737">Icon position Specifies whether the icon should appear + line="2738">Specifies whether the icon should appear sensitive or insensitive @@ -48650,7 +50282,7 @@ If @paintable is %NULL, no icon will be shown in the specified position. c:identifier="gtk_entry_set_icon_tooltip_markup"> Sets @tooltip as the contents of the tooltip for the icon at + line="3124">Sets @tooltip as the contents of the tooltip for the icon at the specified position. @tooltip is assumed to be marked up with Pango Markup. @@ -48667,13 +50299,13 @@ See also [method@Gtk.Widget.set_tooltip_markup] and a `GtkEntry` + line="3126">a `GtkEntry` the icon position + line="3127">the icon position the contents of the tooltip for the icon + line="3128">the contents of the tooltip for the icon @@ -48691,7 +50323,7 @@ See also [method@Gtk.Widget.set_tooltip_markup] and c:identifier="gtk_entry_set_icon_tooltip_text"> Sets @tooltip as the contents of the tooltip for the icon + line="3040">Sets @tooltip as the contents of the tooltip for the icon at the specified position. Use %NULL for @tooltip to remove an existing tooltip. @@ -48716,13 +50348,13 @@ achieves the same result. a `GtkEntry` + line="3042">a `GtkEntry` the icon position + line="3043">the icon position allow-none="1"> the contents of the tooltip for the icon + line="3044">the contents of the tooltip for the icon @@ -48739,10 +50371,9 @@ achieves the same result. - Set additional hints which allow input methods to + line="3521">Set additional hints which allow input methods to fine-tune their behavior. @@ -48752,13 +50383,13 @@ fine-tune their behavior. a `GtkEntry` + line="3523">a `GtkEntry` the hints + line="3524">the hints @@ -48766,10 +50397,9 @@ fine-tune their behavior. - Sets the input purpose which can be used by input methods + line="3483">Sets the input purpose which can be used by input methods to adjust their behavior. @@ -48779,13 +50409,13 @@ to adjust their behavior. a `GtkEntry` + line="3485">a `GtkEntry` the purpose + line="3486">the purpose @@ -48793,10 +50423,9 @@ to adjust their behavior. - Sets the character to use in place of the actual text + line="2122">Sets the character to use in place of the actual text in “password mode”. See [method@Gtk.Entry.set_visibility] for how to enable @@ -48814,13 +50443,13 @@ on the screen as they type. a `GtkEntry` + line="2124">a `GtkEntry` a Unicode character + line="2125">a Unicode character @@ -48828,10 +50457,9 @@ on the screen as they type. - Sets the maximum allowed length of the contents of the widget. + line="2223">Sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit. The length is in characters. @@ -48846,13 +50474,13 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. a `GtkEntry` + line="2225">a `GtkEntry` the maximum length of the entry, or 0 for no maximum. + line="2226">the maximum length of the entry, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. @@ -48862,10 +50490,9 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. - Sets whether the text is overwritten when typing in the `GtkEntry`. + line="2186">Sets whether the text is overwritten when typing in the `GtkEntry`. @@ -48874,13 +50501,13 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. a `GtkEntry` + line="2188">a `GtkEntry` new value + line="2189">new value @@ -48888,11 +50515,9 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. - Sets text to be displayed in @entry when it is empty. + line="3435">Sets text to be displayed in @entry when it is empty. This can be used to give a visual hint of the expected contents of the `GtkEntry`. @@ -48904,7 +50529,7 @@ contents of the `GtkEntry`. a `GtkEntry` + line="3437">a `GtkEntry` allow-none="1"> a string to be displayed when @entry is empty and unfocused + line="3438">a string to be displayed when @entry is empty and unfocused @@ -48921,11 +50546,9 @@ contents of the `GtkEntry`. - Causes the entry’s progress indicator to “fill in” the given + line="3304">Causes the entry’s progress indicator to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. @@ -48937,13 +50560,13 @@ The fraction should be between 0.0 and 1.0, inclusive. a `GtkEntry` + line="3306">a `GtkEntry` fraction of the task that’s been completed + line="3307">fraction of the task that’s been completed @@ -48951,11 +50574,9 @@ The fraction should be between 0.0 and 1.0, inclusive. - Sets the fraction of total entry width to move the progress + line="3359">Sets the fraction of total entry width to move the progress bouncing block for each pulse. Use [method@Gtk.Entry.progress_pulse] to pulse @@ -48968,13 +50589,13 @@ the progress. a `GtkEntry` + line="3361">a `GtkEntry` fraction between 0.0 and 1.0 + line="3362">fraction between 0.0 and 1.0 @@ -48982,10 +50603,9 @@ the progress. - Sets a `PangoTabArray`. + line="3603">Sets a `PangoTabArray`. The tabstops in the array are applied to the entry text. @@ -48996,7 +50616,7 @@ The tabstops in the array are applied to the entry text. a `GtkEntry` + line="3605">a `GtkEntry` allow-none="1"> a `PangoTabArray` + line="3606">a `PangoTabArray` @@ -49013,10 +50633,9 @@ The tabstops in the array are applied to the entry text. - Sets whether the contents of the entry are visible or not. + line="2071">Sets whether the contents of the entry are visible or not. When visibility is set to %FALSE, characters are displayed as the invisible char, and will also appear that way when @@ -49038,13 +50657,13 @@ in addition to setting visibility to %FALSE. a `GtkEntry` + line="2073">a `GtkEntry` %TRUE if the contents of the entry are displayed as plaintext + line="2074">%TRUE if the contents of the entry are displayed as plaintext @@ -49053,7 +50672,7 @@ in addition to setting visibility to %FALSE. c:identifier="gtk_entry_unset_invisible_char"> Unsets the invisible char, so that the default invisible char + line="2169">Unsets the invisible char, so that the default invisible char is used again. See [method@Gtk.Entry.set_invisible_char]. @@ -49063,7 +50682,7 @@ is used again. See [method@Gtk.Entry.set_invisible_char]. a `GtkEntry` + line="2171">a `GtkEntry` @@ -49074,13 +50693,9 @@ is used again. See [method@Gtk.Entry.set_invisible_char]. setter="set_activates_default" getter="get_activates_default" default-value="FALSE"> - - Whether to activate the default widget when Enter is pressed. + line="514">Whether to activate the default widget when Enter is pressed. transfer-ownership="none" setter="set_attributes" getter="get_attributes"> - - A list of Pango attributes to apply to the text of the entry. + line="869">A list of Pango attributes to apply to the text of the entry. This is mainly useful to change the size or weight of the text. @@ -49108,11 +50719,9 @@ The `PangoAttribute`'s @start_index and @end_index must refer to the transfer-ownership="none" setter="set_buffer" getter="get_buffer"> - - The buffer object which actually stores the text. + line="462">The buffer object which actually stores the text. - - The auxiliary completion object to use with the entry. + line="826">The auxiliary completion object to use with the entry. GtkEntryCompletion will be removed in GTK 5. @@ -49138,7 +50743,7 @@ The `PangoAttribute`'s @start_index and @end_index must refer to the default-value="FALSE"> Whether to suggest Emoji replacements for :-delimited names + line="915">Whether to suggest Emoji replacements for :-delimited names like `:heart:`. @@ -49147,13 +50752,9 @@ like `:heart:`. transfer-ownership="none" setter="set_extra_menu" getter="get_extra_menu"> - - A menu model whose contents will be appended to the context menu. + line="905">A menu model whose contents will be appended to the context menu. setter="set_has_frame" getter="get_has_frame" default-value="TRUE"> - - Whether the entry should draw a frame. + line="494">Whether the entry should draw a frame. default-value="NULL"> Which IM (input method) module should be used for this entry. + line="810">Which IM (input method) module should be used for this entry. See [class@Gtk.IMContext]. @@ -49192,13 +50789,9 @@ property. setter="set_input_hints" getter="get_input_hints" default-value="GTK_INPUT_HINT_NONE"> - - Additional hints that allow input methods to fine-tune their behavior. + line="856">Additional hints that allow input methods to fine-tune their behavior. Also see [property@Gtk.Entry:input-purpose] @@ -49209,13 +50802,9 @@ Also see [property@Gtk.Entry:input-purpose] setter="set_input_purpose" getter="get_input_purpose" default-value="GTK_INPUT_PURPOSE_FREE_FORM"> - - The purpose of this text field. + line="838">The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. @@ -49231,13 +50820,9 @@ Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or setter="set_invisible_char" getter="get_invisible_char" default-value="42"> - - The character to use when masking entry contents (“password mode”). + line="504">The character to use when masking entry contents (“password mode”). Whether the invisible char has been set for the `GtkEntry`. + line="566">Whether the invisible char has been set for the `GtkEntry`. - - Maximum number of characters for this entry. + line="472">Maximum number of characters for this entry. - - If text is overwritten when typing in the `GtkEntry`. + line="545">If text is overwritten when typing in the `GtkEntry`. - - The text that will be displayed in the `GtkEntry` when it is empty + line="601">The text that will be displayed in the `GtkEntry` when it is empty and unfocused. @@ -49301,7 +50874,7 @@ and unfocused. default-value="TRUE"> Whether the primary icon is activatable. + line="694">Whether the primary icon is activatable. GTK emits the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals only on sensitive, @@ -49316,7 +50889,7 @@ informational purposes. transfer-ownership="none"> The `GIcon` to use for the primary icon for the entry. + line="652">The `GIcon` to use for the primary icon for the entry. default-value="NULL"> The icon name to use for the primary icon for the entry. + line="632">The icon name to use for the primary icon for the entry. transfer-ownership="none"> A `GdkPaintable` to use as the primary icon for the entry. + line="612">A `GdkPaintable` to use as the primary icon for the entry. default-value="TRUE"> Whether the primary icon is sensitive. + line="728">Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] @@ -49357,7 +50930,7 @@ when clicked is currently not available. default-value="GTK_IMAGE_EMPTY"> The representation which is used for the primary icon of the entry. + line="672">The representation which is used for the primary icon of the entry. default-value="NULL"> The contents of the tooltip on the primary icon, with markup. + line="786">The contents of the tooltip on the primary icon, with markup. Also see [method@Gtk.Entry.set_icon_tooltip_markup]. @@ -49377,7 +50950,7 @@ Also see [method@Gtk.Entry.set_icon_tooltip_markup]. default-value="NULL"> The contents of the tooltip on the primary icon. + line="762">The contents of the tooltip on the primary icon. Also see [method@Gtk.Entry.set_icon_tooltip_text]. @@ -49388,13 +50961,9 @@ Also see [method@Gtk.Entry.set_icon_tooltip_text]. setter="set_progress_fraction" getter="get_progress_fraction" default-value="0.000000"> - - The current fraction of the task that's been completed. + line="576">The current fraction of the task that's been completed. setter="set_progress_pulse_step" getter="get_progress_pulse_step" default-value="0.000000"> - - The fraction of total entry width to move the progress + line="587">The fraction of total entry width to move the progress bouncing block for each pulse. See [method@Gtk.Entry.progress_pulse]. @@ -49420,7 +50985,7 @@ See [method@Gtk.Entry.progress_pulse]. default-value="0"> Number of pixels of the entry scrolled off the screen to the left. + line="524">Number of pixels of the entry scrolled off the screen to the left. default-value="TRUE"> Whether the secondary icon is activatable. + line="711">Whether the secondary icon is activatable. GTK emits the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals only on sensitive, @@ -49444,7 +51009,7 @@ informational purposes. transfer-ownership="none"> The `GIcon` to use for the secondary icon for the entry. + line="662">The `GIcon` to use for the secondary icon for the entry. default-value="NULL"> The icon name to use for the secondary icon for the entry. + line="642">The icon name to use for the secondary icon for the entry. transfer-ownership="none"> A `GdkPaintable` to use as the secondary icon for the entry. + line="622">A `GdkPaintable` to use as the secondary icon for the entry. default-value="TRUE"> Whether the secondary icon is sensitive. + line="745">Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the [signal@Gtk.Entry::icon-press[ and [signal@Gtk.Entry::icon-release] @@ -49485,7 +51050,7 @@ when clicked is currently not available. default-value="GTK_IMAGE_EMPTY"> The representation which is used for the secondary icon of the entry. + line="683">The representation which is used for the secondary icon of the entry. default-value="NULL"> The contents of the tooltip on the secondary icon, with markup. + line="798">The contents of the tooltip on the secondary icon, with markup. Also see [method@Gtk.Entry.set_icon_tooltip_markup]. @@ -49505,7 +51070,7 @@ Also see [method@Gtk.Entry.set_icon_tooltip_markup]. default-value="NULL"> The contents of the tooltip on the secondary icon. + line="774">The contents of the tooltip on the secondary icon. Also see [method@Gtk.Entry.set_icon_tooltip_text]. @@ -49514,6 +51079,10 @@ Also see [method@Gtk.Entry.set_icon_tooltip_text]. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the entry will show an Emoji icon in the secondary icon position +to open the Emoji chooser. transfer-ownership="none" setter="set_tabs" getter="get_tabs"> + A list of tabstops to apply to the text of the entry. - The length of the text in the `GtkEntry`. + line="555">The length of the text in the `GtkEntry`. default-value="FALSE"> When %TRUE, pasted multi-line text is truncated to the first line. + line="535">When %TRUE, pasted multi-line text is truncated to the first line. setter="set_visibility" getter="get_visibility" default-value="TRUE"> - - Whether the entry should show the “invisible char” instead of the + line="483">Whether the entry should show the “invisible char” instead of the actual text (“password mode”). @@ -49565,7 +51131,7 @@ actual text (“password mode”). Emitted when the entry is activated. + line="930">Emitted when the entry is activated. The keybindings for this signal are all forms of the Enter key. @@ -49575,7 +51141,7 @@ The keybindings for this signal are all forms of the Enter key. Emitted when an activatable icon is clicked. + line="947">Emitted when an activatable icon is clicked. @@ -49583,7 +51149,7 @@ The keybindings for this signal are all forms of the Enter key. The position of the clicked icon + line="950">The position of the clicked icon @@ -49591,7 +51157,7 @@ The keybindings for this signal are all forms of the Enter key. Emitted on the button release from a mouse click + line="964">Emitted on the button release from a mouse click over an activatable icon. @@ -49600,7 +51166,7 @@ over an activatable icon. The position of the clicked icon + line="967">The position of the clicked icon @@ -49615,7 +51181,7 @@ over an activatable icon. glib:type-struct="EntryBufferClass"> A `GtkEntryBuffer` hold the text displayed in a `GtkText` widget. + line="29">Holds the text that is displayed in a single-line text entry widget. A single `GtkEntryBuffer` object can be shared by multiple widgets which will then share the same text content, but not the cursor @@ -49629,14 +51195,14 @@ integrate with an application’s concept of undo/redo. Create a new `GtkEntryBuffer` object. + line="427">Create a new `GtkEntryBuffer` object. Optionally, specify initial text to set in the buffer. A new `GtkEntryBuffer` object. + line="436">A new `GtkEntryBuffer` object. @@ -49646,13 +51212,13 @@ Optionally, specify initial text to set in the buffer. allow-none="1"> initial buffer text + line="429">initial buffer text number of characters in @initial_chars, or -1 + line="430">number of characters in @initial_chars, or -1 @@ -49660,7 +51226,7 @@ Optionally, specify initial text to set in the buffer. Deletes a sequence of characters from the buffer. + line="657">Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the @@ -49675,26 +51241,26 @@ not bytes. The number of characters deleted. + line="675">The number of characters deleted. a `GtkEntryBuffer` + line="659">a `GtkEntryBuffer` position at which to delete text + line="660">position at which to delete text number of characters to delete + line="661">number of characters to delete @@ -49717,22 +51283,21 @@ not bytes. - Retrieves the length in characters of the buffer. + line="448">Retrieves the length in characters of the buffer. The number of characters in the buffer. + line="454">The number of characters in the buffer. a `GtkEntryBuffer` + line="450">a `GtkEntryBuffer` @@ -49754,7 +51319,7 @@ not bytes. Inserts @n_chars characters of @chars into the contents of the + line="599">Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted @@ -49767,32 +51332,32 @@ Note that the position and length are in characters, not in bytes. The number of characters actually inserted. + line="616">The number of characters actually inserted. a `GtkEntryBuffer` + line="601">a `GtkEntryBuffer` the position at which to insert text. + line="602">the position at which to insert text. the text to insert into the buffer. + line="603">the text to insert into the buffer. the length of the text in characters, or -1 + line="604">the length of the text in characters, or -1 @@ -49820,7 +51385,7 @@ Note that the position and length are in characters, not in bytes. Deletes a sequence of characters from the buffer. + line="657">Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the @@ -49835,26 +51400,26 @@ not bytes. The number of characters deleted. + line="675">The number of characters deleted. a `GtkEntryBuffer` + line="659">a `GtkEntryBuffer` position at which to delete text + line="660">position at which to delete text number of characters to delete + line="661">number of characters to delete @@ -49863,7 +51428,7 @@ not bytes. c:identifier="gtk_entry_buffer_emit_deleted_text"> Used when subclassing `GtkEntryBuffer`. + line="720">Used when subclassing `GtkEntryBuffer`. @@ -49872,19 +51437,19 @@ not bytes. a `GtkEntryBuffer` + line="722">a `GtkEntryBuffer` position at which text was deleted + line="723">position at which text was deleted number of characters deleted + line="724">number of characters deleted @@ -49893,7 +51458,7 @@ not bytes. c:identifier="gtk_entry_buffer_emit_inserted_text"> Used when subclassing `GtkEntryBuffer`. + line="701">Used when subclassing `GtkEntryBuffer`. @@ -49902,25 +51467,25 @@ not bytes. a `GtkEntryBuffer` + line="703">a `GtkEntryBuffer` position at which text was inserted + line="704">position at which text was inserted text that was inserted + line="705">text that was inserted number of characters inserted + line="706">number of characters inserted @@ -49928,21 +51493,21 @@ not bytes. Retrieves the length in bytes of the buffer. + line="469">Retrieves the length in bytes of the buffer. See [method@Gtk.EntryBuffer.get_length]. The byte length of the buffer. + line="477">The byte length of the buffer. a `GtkEntryBuffer` + line="471">a `GtkEntryBuffer` @@ -49950,22 +51515,21 @@ See [method@Gtk.EntryBuffer.get_length]. - Retrieves the length in characters of the buffer. + line="448">Retrieves the length in characters of the buffer. The number of characters in the buffer. + line="454">The number of characters in the buffer. a `GtkEntryBuffer` + line="450">a `GtkEntryBuffer` @@ -49973,15 +51537,14 @@ See [method@Gtk.EntryBuffer.get_length]. - Retrieves the maximum allowed length of the text in @buffer. + line="580">Retrieves the maximum allowed length of the text in @buffer. the maximum allowed number of characters + line="586">the maximum allowed number of characters in `GtkEntryBuffer`, or 0 if there is no maximum. @@ -49989,7 +51552,7 @@ See [method@Gtk.EntryBuffer.get_length]. a `GtkEntryBuffer` + line="582">a `GtkEntryBuffer` @@ -49997,10 +51560,9 @@ See [method@Gtk.EntryBuffer.get_length]. - Retrieves the contents of the buffer. + line="494">Retrieves the contents of the buffer. The memory pointer returned by this call will not change unless this object emits a signal, or is finalized. @@ -50008,7 +51570,7 @@ unless this object emits a signal, or is finalized. a pointer to the contents of the widget as a + line="503">a pointer to the contents of the widget as a string. This string points to internally allocated storage in the buffer and must not be freed, modified or stored. @@ -50017,7 +51579,7 @@ unless this object emits a signal, or is finalized. a `GtkEntryBuffer` + line="496">a `GtkEntryBuffer` @@ -50025,7 +51587,7 @@ unless this object emits a signal, or is finalized. Inserts @n_chars characters of @chars into the contents of the + line="599">Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted @@ -50038,32 +51600,32 @@ Note that the position and length are in characters, not in bytes. The number of characters actually inserted. + line="616">The number of characters actually inserted. a `GtkEntryBuffer` + line="601">a `GtkEntryBuffer` the position at which to insert text. + line="602">the position at which to insert text. the text to insert into the buffer. + line="603">the text to insert into the buffer. the length of the text in characters, or -1 + line="604">the length of the text in characters, or -1 @@ -50071,10 +51633,9 @@ Note that the position and length are in characters, not in bytes. - Sets the maximum allowed length of the contents of the buffer. + line="548">Sets the maximum allowed length of the contents of the buffer. If the current contents are longer than the given length, then they will be truncated to fit. @@ -50086,13 +51647,13 @@ they will be truncated to fit. a `GtkEntryBuffer` + line="550">a `GtkEntryBuffer` the maximum length of the entry buffer, or 0 for no maximum. + line="551">the maximum length of the entry buffer, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. @@ -50102,10 +51663,9 @@ they will be truncated to fit. - Sets the text in the buffer. + line="520">Sets the text in the buffer. This is roughly equivalent to calling [method@Gtk.EntryBuffer.delete_text] and @@ -50120,19 +51680,19 @@ Note that @n_chars is in characters, not in bytes. a `GtkEntryBuffer` + line="522">a `GtkEntryBuffer` the new text + line="523">the new text the number of characters in @text, or -1 + line="524">the number of characters in @text, or -1 @@ -50141,11 +51701,9 @@ Note that @n_chars is in characters, not in bytes. transfer-ownership="none" getter="get_length" default-value="0"> - The length (in characters) of the text in buffer. + line="353">The length (in characters) of the text in buffer. setter="set_max_length" getter="get_max_length" default-value="0"> - - The maximum length (in characters) of the text in the buffer. + line="363">The maximum length (in characters) of the text in the buffer. transfer-ownership="none" setter="set_text" getter="get_text"> - - The contents of the buffer. + line="343">The contents of the buffer. @@ -50183,7 +51733,7 @@ Note that @n_chars is in characters, not in bytes. The text is altered in the default handler for this signal. + line="398">The text is altered in the default handler for this signal. If you want access to the text after the text has been modified, use %G_CONNECT_AFTER. @@ -50194,13 +51744,13 @@ use %G_CONNECT_AFTER. the position the text was deleted at. + line="401">the position the text was deleted at. The number of characters that were deleted. + line="402">The number of characters that were deleted. @@ -50208,7 +51758,7 @@ use %G_CONNECT_AFTER. This signal is emitted after text is inserted into the buffer. + line="375">This signal is emitted after text is inserted into the buffer. @@ -50216,19 +51766,19 @@ use %G_CONNECT_AFTER. the position the text was inserted at. + line="378">the position the text was inserted at. The text that was inserted. + line="379">The text that was inserted. The number of characters that were inserted. + line="380">The number of characters that were inserted. @@ -50304,14 +51854,14 @@ use %G_CONNECT_AFTER. The number of characters in the buffer. + line="454">The number of characters in the buffer. a `GtkEntryBuffer` + line="450">a `GtkEntryBuffer` @@ -50323,32 +51873,32 @@ use %G_CONNECT_AFTER. The number of characters actually inserted. + line="616">The number of characters actually inserted. a `GtkEntryBuffer` + line="601">a `GtkEntryBuffer` the position at which to insert text. + line="602">the position at which to insert text. the text to insert into the buffer. + line="603">the text to insert into the buffer. the length of the text in characters, or -1 + line="604">the length of the text in characters, or -1 @@ -50360,26 +51910,26 @@ use %G_CONNECT_AFTER. The number of characters deleted. + line="675">The number of characters deleted. a `GtkEntryBuffer` + line="659">a `GtkEntryBuffer` position at which to delete text + line="660">position at which to delete text number of characters to delete + line="661">number of characters to delete @@ -50468,6 +52018,10 @@ a custom one. + Class handler for the `GtkEntry::activate` signal. The default + implementation activates the gtk.activate-default action. @@ -50542,14 +52096,14 @@ matching iter. deprecated-version="4.10"> Creates a new `GtkEntryCompletion` object. + line="818">Creates a new `GtkEntryCompletion` object. GtkEntryCompletion will be removed in GTK 5. A newly created `GtkEntryCompletion` object + line="823">A newly created `GtkEntryCompletion` object @@ -50559,7 +52113,7 @@ matching iter. deprecated-version="4.10"> Creates a new `GtkEntryCompletion` object using the + line="837">Creates a new `GtkEntryCompletion` object using the specified @area. The `GtkCellArea` is used to layout cells in the underlying @@ -50570,14 +52124,14 @@ The `GtkCellArea` is used to layout cells in the underlying A newly created `GtkEntryCompletion` object + line="847">A newly created `GtkEntryCompletion` object the `GtkCellArea` used to layout cells + line="839">the `GtkCellArea` used to layout cells @@ -50588,7 +52142,7 @@ The `GtkCellArea` is used to layout cells in the underlying deprecated-version="4.10"> Requests a completion operation, or in other words a refiltering of the + line="1027">Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key. The completion list view will be updated accordingly. @@ -50602,7 +52156,7 @@ The completion list view will be updated accordingly. a `GtkEntryCompletion` + line="1029">a `GtkEntryCompletion` @@ -50613,7 +52167,7 @@ The completion list view will be updated accordingly. deprecated-version="4.10"> Computes the common prefix that is shared by all rows in @completion + line="1260">Computes the common prefix that is shared by all rows in @completion that start with @key. If no row matches @key, %NULL will be returned. @@ -50625,7 +52179,7 @@ see [method@Gtk.EntryCompletion.set_text_column] for details. The common prefix all rows + line="1272">The common prefix all rows starting with @key @@ -50633,13 +52187,13 @@ see [method@Gtk.EntryCompletion.set_text_column] for details. the entry completion + line="1262">the entry completion The text to complete for + line="1263">The text to complete for @@ -50650,7 +52204,7 @@ see [method@Gtk.EntryCompletion.set_text_column] for details. deprecated-version="4.10"> Get the original text entered by the user that triggered + line="1374">Get the original text entered by the user that triggered the completion or %NULL if there’s no completion ongoing. GtkEntryCompletion will be removed in GTK 5. the prefix for the current completion + line="1381">the prefix for the current completion a `GtkEntryCompletion` + line="1376">a `GtkEntryCompletion` @@ -50676,21 +52230,21 @@ the completion or %NULL if there’s no completion ongoing. deprecated-version="4.10"> Gets the entry @completion has been attached to. + line="861">Gets the entry @completion has been attached to. GtkEntryCompletion will be removed in GTK 5. The entry @completion has been attached to + line="867">The entry @completion has been attached to a `GtkEntryCompletion` + line="863">a `GtkEntryCompletion` @@ -50700,11 +52254,9 @@ the completion or %NULL if there’s no completion ongoing. glib:get-property="inline-completion" deprecated="1" deprecated-version="4.10"> - Returns whether the common prefix of the possible completions should + line="1498">Returns whether the common prefix of the possible completions should be automatically inserted in the entry. GtkEntryCompletion will be removed in GTK 5. %TRUE if inline completion is turned on + line="1505">%TRUE if inline completion is turned on a `GtkEntryCompletion` + line="1500">a `GtkEntryCompletion` @@ -50729,25 +52281,23 @@ be automatically inserted in the entry. glib:get-property="inline-selection" deprecated="1" deprecated-version="4.10"> - Returns %TRUE if inline-selection mode is turned on. + line="1683">Returns %TRUE if inline-selection mode is turned on. GtkEntryCompletion will be removed in GTK 5. %TRUE if inline-selection mode is on + line="1689">%TRUE if inline-selection mode is on a `GtkEntryCompletion` + line="1685">a `GtkEntryCompletion` @@ -50759,21 +52309,21 @@ be automatically inserted in the entry. deprecated-version="4.10"> Returns the minimum key length as set for @completion. + line="1009">Returns the minimum key length as set for @completion. GtkEntryCompletion will be removed in GTK 5. The currently used minimum key length + line="1015">The currently used minimum key length a `GtkEntryCompletion` + line="1011">a `GtkEntryCompletion` @@ -50783,10 +52333,9 @@ be automatically inserted in the entry. glib:get-property="model" deprecated="1" deprecated-version="4.10"> - Returns the model the `GtkEntryCompletion` is using as data source. + line="926">Returns the model the `GtkEntryCompletion` is using as data source. Returns %NULL if the model is unset. GtkEntryCompletion will be removed in GTK 5. @@ -50795,14 +52344,14 @@ Returns %NULL if the model is unset. A `GtkTreeModel` + line="934">A `GtkTreeModel` a `GtkEntryCompletion` + line="928">a `GtkEntryCompletion` @@ -50812,25 +52361,23 @@ Returns %NULL if the model is unset. glib:get-property="popup-completion" deprecated="1" deprecated-version="4.10"> - Returns whether the completions should be presented in a popup window. + line="1543">Returns whether the completions should be presented in a popup window. GtkEntryCompletion will be removed in GTK 5. %TRUE if popup completion is turned on + line="1549">%TRUE if popup completion is turned on a `GtkEntryCompletion` + line="1545">a `GtkEntryCompletion` @@ -50840,10 +52387,9 @@ Returns %NULL if the model is unset. glib:get-property="popup-set-width" deprecated="1" deprecated-version="4.10"> - Returns whether the completion popup window will be resized to the + line="1587">Returns whether the completion popup window will be resized to the width of the entry. GtkEntryCompletion will be removed in GTK 5. %TRUE if the popup window will be resized to the width of + line="1594">%TRUE if the popup window will be resized to the width of the entry @@ -50859,7 +52405,7 @@ width of the entry. a `GtkEntryCompletion` + line="1589">a `GtkEntryCompletion` @@ -50869,11 +52415,9 @@ width of the entry. glib:get-property="popup-single-match" deprecated="1" deprecated-version="4.10"> - Returns whether the completion popup window will appear even if there is + line="1637">Returns whether the completion popup window will appear even if there is only a single match. GtkEntryCompletion will be removed in GTK 5. %TRUE if the popup window will appear regardless of the + line="1644">%TRUE if the popup window will appear regardless of the number of matches @@ -50889,7 +52433,7 @@ only a single match. a `GtkEntryCompletion` + line="1639">a `GtkEntryCompletion` @@ -50899,24 +52443,23 @@ only a single match. glib:get-property="text-column" deprecated="1" deprecated-version="4.10"> - Returns the column in the model of @completion to get strings from. + line="1109">Returns the column in the model of @completion to get strings from. GtkEntryCompletion will be removed in GTK 5. the column containing the strings + line="1115">the column containing the strings a `GtkEntryCompletion` + line="1111">a `GtkEntryCompletion` @@ -50927,7 +52470,7 @@ only a single match. deprecated-version="4.10"> Requests a prefix insertion. + line="1439">Requests a prefix insertion. GtkEntryCompletion will be removed in GTK 5. @@ -50938,7 +52481,7 @@ only a single match. a `GtkEntryCompletion` + line="1441">a `GtkEntryCompletion` @@ -50948,11 +52491,9 @@ only a single match. glib:set-property="inline-completion" deprecated="1" deprecated-version="4.10"> - Sets whether the common prefix of the possible completions should + line="1472">Sets whether the common prefix of the possible completions should be automatically inserted in the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` + line="1474">a `GtkEntryCompletion` %TRUE to do inline completion + line="1475">%TRUE to do inline completion @@ -50980,11 +52521,9 @@ be automatically inserted in the entry. glib:set-property="inline-selection" deprecated="1" deprecated-version="4.10"> - Sets whether it is possible to cycle through the possible completions + line="1657">Sets whether it is possible to cycle through the possible completions inside the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` + line="1659">a `GtkEntryCompletion` %TRUE to do inline selection + line="1660">%TRUE to do inline selection @@ -51013,7 +52552,7 @@ inside the entry. deprecated-version="4.10"> Sets the match function for @completion to be @func. + line="949">Sets the match function for @completion to be @func. The match function is used to determine if a row should or should not be in the completion list. @@ -51027,7 +52566,7 @@ should not be in the completion list. a `GtkEntryCompletion` + line="951">a `GtkEntryCompletion` destroy="2"> the `GtkEntryCompletion`MatchFunc to use + line="952">the `GtkEntryCompletion`MatchFunc to use @@ -51047,7 +52586,7 @@ should not be in the completion list. allow-none="1"> user data for @func + line="953">user data for @func scope="async"> destroy notify for @func_data. + line="954">destroy notify for @func_data. @@ -51067,7 +52606,7 @@ should not be in the completion list. deprecated-version="4.10"> Requires the length of the search key for @completion to be at least + line="979">Requires the length of the search key for @completion to be at least @length. This is useful for long lists, where completing using a small @@ -51083,13 +52622,13 @@ key takes a lot of time and will come up with meaningless results anyway a `GtkEntryCompletion` + line="981">a `GtkEntryCompletion` the minimum length of the key in order to start completing + line="982">the minimum length of the key in order to start completing @@ -51099,10 +52638,9 @@ key takes a lot of time and will come up with meaningless results anyway glib:set-property="model" deprecated="1" deprecated-version="4.10"> - Sets the model for a `GtkEntryCompletion`. + line="879">Sets the model for a `GtkEntryCompletion`. If @completion already has a model set, it will remove it before setting the new model. If model is %NULL, then it @@ -51117,7 +52655,7 @@ will unset the model. a `GtkEntryCompletion` + line="881">a `GtkEntryCompletion` allow-none="1"> the `GtkTreeModel` + line="882">the `GtkTreeModel` @@ -51136,11 +52674,9 @@ will unset the model. glib:set-property="popup-completion" deprecated="1" deprecated-version="4.10"> - Sets whether the completions should be presented in a popup window. + line="1517">Sets whether the completions should be presented in a popup window. GtkEntryCompletion will be removed in GTK 5. @@ -51151,13 +52687,13 @@ will unset the model. a `GtkEntryCompletion` + line="1519">a `GtkEntryCompletion` %TRUE to do popup completion + line="1520">%TRUE to do popup completion @@ -51167,10 +52703,9 @@ will unset the model. glib:set-property="popup-set-width" deprecated="1" deprecated-version="4.10"> - Sets whether the completion popup window will be resized to be the same + line="1561">Sets whether the completion popup window will be resized to be the same width as the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` + line="1563">a `GtkEntryCompletion` %TRUE to make the width of the popup the same as the entry + line="1564">%TRUE to make the width of the popup the same as the entry @@ -51198,11 +52733,9 @@ width as the entry. glib:set-property="popup-single-match" deprecated="1" deprecated-version="4.10"> - Sets whether the completion popup window will appear even if there is + line="1608">Sets whether the completion popup window will appear even if there is only a single match. You may want to set this to %FALSE if you @@ -51217,13 +52750,13 @@ are using [property@Gtk.EntryCompletion:inline-completion]. a `GtkEntryCompletion` + line="1610">a `GtkEntryCompletion` %TRUE if the popup should appear even for a single match + line="1611">%TRUE if the popup should appear even for a single match @@ -51233,10 +52766,9 @@ are using [property@Gtk.EntryCompletion:inline-completion]. glib:set-property="text-column" deprecated="1" deprecated-version="4.10"> - Convenience function for setting up the most used case of this code: a + line="1066">Convenience function for setting up the most used case of this code: a completion list with just strings. This function will set up @completion @@ -51257,13 +52789,13 @@ renderer, use g_object_set() to set the a `GtkEntryCompletion` + line="1068">a `GtkEntryCompletion` the column in the model of @completion to get strings from + line="1069">the column in the model of @completion to get strings from @@ -51274,7 +52806,7 @@ renderer, use g_object_set() to set the transfer-ownership="none"> The `GtkCellArea` used to layout cell renderers in the treeview column. + line="393">The `GtkCellArea` used to layout cell renderers in the treeview column. If no area is specified when creating the entry completion with [ctor@Gtk.EntryCompletion.new_with_area], a horizontally oriented @@ -51287,13 +52819,9 @@ If no area is specified when creating the entry completion with setter="set_inline_completion" getter="get_inline_completion" default-value="FALSE"> - - Determines whether the common prefix of the possible completions + line="332">Determines whether the common prefix of the possible completions should be inserted automatically in the entry. Note that this requires text-column to be set, even if you are @@ -51306,13 +52834,9 @@ using a custom match function. setter="set_inline_selection" getter="get_inline_selection" default-value="FALSE"> - - Determines whether the possible completions on the popup + line="382">Determines whether the possible completions on the popup will appear in the entry as you navigate through them. @@ -51322,6 +52846,9 @@ will appear in the entry as you navigate through them. setter="set_minimum_key_length" getter="get_minimum_key_length" default-value="1"> + The minimum key length as set for completion. transfer-ownership="none" setter="set_model" getter="get_model"> + The model used as data source. setter="set_popup_completion" getter="get_popup_completion" default-value="TRUE"> - - Determines whether the possible completions should be + line="346">Determines whether the possible completions should be shown in a popup window. @@ -51353,13 +52879,9 @@ shown in a popup window. setter="set_popup_set_width" getter="get_popup_set_width" default-value="TRUE"> - - Determines whether the completions popup window will be + line="357">Determines whether the completions popup window will be resized to the width of the entry. @@ -51369,13 +52891,9 @@ resized to the width of the entry. setter="set_popup_single_match" getter="get_popup_single_match" default-value="TRUE"> - - Determines whether the completions popup window will shown + line="368">Determines whether the completions popup window will shown for a single possible completion. You probably want to set this to %FALSE if you are using @@ -51388,13 +52906,9 @@ You probably want to set this to %FALSE if you are using setter="set_text_column" getter="get_text_column" default-value="-1"> - - The column of the model containing the strings. + line="320">The column of the model containing the strings. Note that the strings must be UTF-8. @@ -51589,7 +53103,7 @@ have access to the unmodified key via glib:type-struct="EventControllerClass"> `GtkEventController` is the base class for event controllers. + line="21">The base class for event controllers. These are ancillary objects associated to widgets, which react to `GdkEvents`, and possibly trigger actions as a consequence. @@ -51606,14 +53120,14 @@ phases of event propagation. c:identifier="gtk_event_controller_get_current_event"> Returns the event that is currently being handled by the controller. + line="631">Returns the event that is currently being handled by the controller. At other times, %NULL is returned. the event that is currently + line="639">the event that is currently handled by @controller @@ -51621,7 +53135,7 @@ At other times, %NULL is returned. a `GtkEventController` + line="633">a `GtkEventController` @@ -51630,7 +53144,7 @@ At other times, %NULL is returned. c:identifier="gtk_event_controller_get_current_event_device"> Returns the device of the event that is currently being + line="672">Returns the device of the event that is currently being handled by the controller. At other times, %NULL is returned. @@ -51638,7 +53152,7 @@ At other times, %NULL is returned. device of the event is + line="681">device of the event is currently handled by @controller @@ -51646,7 +53160,7 @@ At other times, %NULL is returned. a `GtkEventController` + line="674">a `GtkEventController` @@ -51655,7 +53169,7 @@ At other times, %NULL is returned. c:identifier="gtk_event_controller_get_current_event_state"> Returns the modifier state of the event that is currently being + line="695">Returns the modifier state of the event that is currently being handled by the controller. At other times, 0 is returned. @@ -51663,14 +53177,14 @@ At other times, 0 is returned. modifier state of the event is currently handled by @controller + line="704">modifier state of the event is currently handled by @controller a `GtkEventController` + line="697">a `GtkEventController` @@ -51679,7 +53193,7 @@ At other times, 0 is returned. c:identifier="gtk_event_controller_get_current_event_time"> Returns the timestamp of the event that is currently being + line="650">Returns the timestamp of the event that is currently being handled by the controller. At other times, 0 is returned. @@ -51687,14 +53201,14 @@ At other times, 0 is returned. timestamp of the event is currently handled by @controller + line="659">timestamp of the event is currently handled by @controller a `GtkEventController` + line="652">a `GtkEventController` @@ -51702,22 +53216,21 @@ At other times, 0 is returned. - Gets the name of @controller. + line="561">Gets the name of @controller. The controller name + line="567">The controller name a `GtkEventController` + line="563">a `GtkEventController` @@ -51725,23 +53238,21 @@ At other times, 0 is returned. - Gets the propagation limit of the event controller. + line="512">Gets the propagation limit of the event controller. the propagation limit + line="518">the propagation limit a `GtkEventController` + line="514">a `GtkEventController` @@ -51749,23 +53260,21 @@ At other times, 0 is returned. - Gets the propagation phase at which @controller handles events. + line="460">Gets the propagation phase at which @controller handles events. the propagation phase + line="466">the propagation phase a `GtkEventController` + line="462">a `GtkEventController` @@ -51773,22 +53282,21 @@ At other times, 0 is returned. - Returns the `GtkWidget` this controller relates to. + line="421">Returns the `GtkWidget` this controller relates to. - + a `GtkWidget` + line="427">a `GtkWidget` a `GtkEventController` + line="423">a `GtkEventController` @@ -51796,7 +53304,7 @@ At other times, 0 is returned. Resets the @controller to a clean state. + line="441">Resets the @controller to a clean state. @@ -51805,7 +53313,7 @@ At other times, 0 is returned. a `GtkEventController` + line="443">a `GtkEventController` @@ -51813,10 +53321,9 @@ At other times, 0 is returned. - Sets a name on the controller that can be used for debugging. + line="579">Sets a name on the controller that can be used for debugging. @@ -51825,7 +53332,7 @@ At other times, 0 is returned. a `GtkEventController` + line="581">a `GtkEventController` allow-none="1"> a name for @controller + line="582">a name for @controller @@ -51842,11 +53349,9 @@ At other times, 0 is returned. - Sets the event propagation limit on the event controller. + line="532">Sets the event propagation limit on the event controller. If the limit is set to %GTK_LIMIT_SAME_NATIVE, the controller won't handle events that are targeted at widgets on a different @@ -51859,13 +53364,13 @@ surface, such as popovers. a `GtkEventController` + line="534">a `GtkEventController` the propagation limit + line="535">the propagation limit @@ -51873,11 +53378,9 @@ surface, such as popovers. - Sets the propagation phase at which a controller handles events. + line="480">Sets the propagation phase at which a controller handles events. If @phase is %GTK_PHASE_NONE, no automatic event handling will be performed, but other additional gesture maintenance will. @@ -51889,13 +53392,13 @@ performed, but other additional gesture maintenance will. a `GtkEventController` + line="482">a `GtkEventController` a propagation phase + line="483">a propagation phase @@ -51905,7 +53408,7 @@ performed, but other additional gesture maintenance will. version="4.8"> Sets a name on the controller that can be used for debugging. + line="600">Sets a name on the controller that can be used for debugging. @@ -51914,7 +53417,7 @@ performed, but other additional gesture maintenance will. a `GtkEventController` + line="602">a `GtkEventController` allow-none="1"> a name for @controller, must be a static string + line="603">a name for @controller, must be a static string @@ -51934,13 +53437,9 @@ performed, but other additional gesture maintenance will. setter="set_name" getter="get_name" default-value="NULL"> - - The name for this controller, typically used for debugging purposes. + line="231">The name for this controller, typically used for debugging purposes. setter="set_propagation_limit" getter="get_propagation_limit" default-value="GTK_LIMIT_SAME_NATIVE"> - - The limit for which events this controller will handle. + line="220">The limit for which events this controller will handle. setter="set_propagation_phase" getter="get_propagation_phase" default-value="GTK_PHASE_BUBBLE"> - - The propagation phase at which this controller will handle events. + line="209">The propagation phase at which this controller will handle events. - The widget receiving the `GdkEvents` that the controller will handle. + line="199">The widget receiving the `GdkEvents` that the controller will handle. @@ -51998,8 +53487,7 @@ performed, but other additional gesture maintenance will. glib:type-struct="EventControllerFocusClass"> `GtkEventControllerFocus` is an event controller to keep track of -keyboard focus. + line="20">Tracks keyboard focus. The event controller offers [signal@Gtk.EventControllerFocus::enter] and [signal@Gtk.EventControllerFocus::leave] signals, as well as @@ -52011,34 +53499,33 @@ that is rooted at the controllers widget. Creates a new event controller that will handle focus events. + line="275">Creates a new event controller that will handle focus events. a new `GtkEventControllerFocus` + line="280">a new `GtkEventControllerFocus` - Returns %TRUE if focus is within @self or one of its children. + line="288">Returns %TRUE if focus is within @self or one of its children. %TRUE if focus is within @self or one of its children + line="294">%TRUE if focus is within @self or one of its children a `GtkEventControllerFocus` + line="290">a `GtkEventControllerFocus` @@ -52047,22 +53534,21 @@ that is rooted at the controllers widget. - Returns %TRUE if focus is within @self, but not one of its children. + line="304">Returns %TRUE if focus is within @self, but not one of its children. %TRUE if focus is within @self, but not one of its children + line="310">%TRUE if focus is within @self, but not one of its children a `GtkEventControllerFocus` + line="306">a `GtkEventControllerFocus` @@ -52072,11 +53558,9 @@ that is rooted at the controllers widget. transfer-ownership="none" getter="contains_focus" default-value="FALSE"> - %TRUE if focus is contained in the controllers widget. + line="205">%TRUE if focus is contained in the controllers widget. See [property@Gtk.EventControllerFocus:is-focus] for whether the focus is in the widget itself or inside a descendent. @@ -52090,11 +53574,9 @@ before [signal@Gtk.EventControllerFocus::enter] or transfer-ownership="none" getter="is_focus" default-value="FALSE"> - %TRUE if focus is in the controllers widget itself, + line="188">%TRUE if focus is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.EventControllerFocus:contains-focus]. @@ -52107,7 +53589,7 @@ before [signal@Gtk.EventControllerFocus::enter] or Emitted whenever the focus enters into the widget or one + line="224">Emitted whenever the focus enters into the widget or one of its descendents. Note that this means you may not get an ::enter signal @@ -52124,7 +53606,7 @@ property for changes. Emitted whenever the focus leaves the widget hierarchy + line="247">Emitted whenever the focus leaves the widget hierarchy that is rooted at the widget that the controller is attached to. Note that this means you may not get a ::leave signal @@ -52154,25 +53636,24 @@ property for changes. glib:type-struct="EventControllerKeyClass"> `GtkEventControllerKey` is an event controller that provides access -to key events. + line="20">Provides access to key events. Creates a new event controller that will handle key events. + line="279">Creates a new event controller that will handle key events. a new `GtkEventControllerKey` + line="284">a new `GtkEventControllerKey` Forwards the current event of this @controller to a @widget. + line="328">Forwards the current event of this @controller to a @widget. This function can only be used in handlers for the [signal@Gtk.EventControllerKey::key-pressed], @@ -52182,20 +53663,20 @@ or [signal@Gtk.EventControllerKey::modifiers] signals. whether the @widget handled the event + line="340">whether the @widget handled the event a `GtkEventControllerKey` + line="330">a `GtkEventControllerKey` a `GtkWidget` + line="331">a `GtkWidget` @@ -52204,21 +53685,21 @@ or [signal@Gtk.EventControllerKey::modifiers] signals. c:identifier="gtk_event_controller_key_get_group"> Gets the key group of the current event of this @controller. + line="368">Gets the key group of the current event of this @controller. See [method@Gdk.KeyEvent.get_layout]. the key group + line="376">the key group a `GtkEventControllerKey` + line="370">a `GtkEventControllerKey` @@ -52227,19 +53708,19 @@ See [method@Gdk.KeyEvent.get_layout]. c:identifier="gtk_event_controller_key_get_im_context"> Gets the input method context of the key @controller. + line="312">Gets the input method context of the key @controller. the `GtkIMContext` + line="318">the `GtkIMContext` a `GtkEventControllerKey` + line="314">a `GtkEventControllerKey` @@ -52248,7 +53729,7 @@ See [method@Gdk.KeyEvent.get_layout]. c:identifier="gtk_event_controller_key_set_im_context"> Sets the input method context of the key @controller. + line="292">Sets the input method context of the key @controller. @@ -52257,7 +53738,7 @@ See [method@Gdk.KeyEvent.get_layout]. a `GtkEventControllerKey` + line="294">a `GtkEventControllerKey` allow-none="1"> a `GtkIMContext` + line="295">a `GtkIMContext` @@ -52274,7 +53755,7 @@ See [method@Gdk.KeyEvent.get_layout]. Emitted whenever the input method context filters away + line="254">Emitted whenever the input method context filters away a keypress and prevents the @controller receiving it. See [method@Gtk.EventControllerKey.set_im_context] and @@ -52286,30 +53767,30 @@ See [method@Gtk.EventControllerKey.set_im_context] and Emitted whenever a key is pressed. + line="190">Emitted whenever a key is pressed. %TRUE if the key press was handled, %FALSE otherwise. + line="199">%TRUE if the key press was handled, %FALSE otherwise. the pressed key. + line="193">the pressed key. the raw code of the pressed key. + line="194">the raw code of the pressed key. the bitmask, representing the state of modifier keys and pointer buttons. + line="195">the bitmask, representing the state of modifier keys and pointer buttons. @@ -52317,7 +53798,7 @@ See [method@Gtk.EventControllerKey.set_im_context] and Emitted whenever a key is released. + line="212">Emitted whenever a key is released. @@ -52325,19 +53806,19 @@ See [method@Gtk.EventControllerKey.set_im_context] and the released key. + line="215">the released key. the raw code of the released key. + line="216">the raw code of the released key. the bitmask, representing the state of modifier keys and pointer buttons. + line="217">the bitmask, representing the state of modifier keys and pointer buttons. @@ -52345,15 +53826,18 @@ See [method@Gtk.EventControllerKey.set_im_context] and Emitted whenever the state of modifier keys and pointer buttons change. + line="232">Emitted whenever the state of modifier keys and pointer buttons change. + whether to ignore modifiers the bitmask, representing the new state of modifier keys and + line="235">the bitmask, representing the new state of modifier keys and pointer buttons. @@ -52376,8 +53860,7 @@ See [method@Gtk.EventControllerKey.set_im_context] and glib:type-struct="EventControllerLegacyClass"> `GtkEventControllerLegacy` is an event controller that provides raw -access to the event stream. + line="20">Provides raw access to the event stream. It should only be used as a last resort if none of the other event controllers or gestures do the job. @@ -52385,23 +53868,23 @@ controllers or gestures do the job. Creates a new legacy event controller. + line="105">Creates a new legacy event controller. the newly created event controller. + line="110">the newly created event controller. Emitted for each GDK event delivered to @controller. + line="77">Emitted for each GDK event delivered to @controller. %TRUE to stop other handlers from being invoked for the event + line="84">%TRUE to stop other handlers from being invoked for the event and the emission of this signal. %FALSE to propagate the event further. @@ -52409,7 +53892,7 @@ controllers or gestures do the job. the `GdkEvent` which triggered this signal + line="80">the `GdkEvent` which triggered this signal @@ -52431,8 +53914,7 @@ controllers or gestures do the job. glib:type-struct="EventControllerMotionClass"> `GtkEventControllerMotion` is an event controller tracking the pointer -position. + line="20">Tracks the pointer position. The event controller offers [signal@Gtk.EventControllerMotion::enter] and [signal@Gtk.EventControllerMotion::leave] signals, as well as @@ -52444,35 +53926,33 @@ moves over the widget. Creates a new event controller that will handle motion events. + line="290">Creates a new event controller that will handle motion events. a new `GtkEventControllerMotion` + line="295">a new `GtkEventControllerMotion` - Returns if a pointer is within @self or one of its children. + line="304">Returns if a pointer is within @self or one of its children. %TRUE if a pointer is within @self or one of its children + line="310">%TRUE if a pointer is within @self or one of its children a `GtkEventControllerMotion` + line="306">a `GtkEventControllerMotion` @@ -52481,22 +53961,21 @@ moves over the widget. - Returns if a pointer is within @self, but not one of its children. + line="320">Returns if a pointer is within @self, but not one of its children. %TRUE if a pointer is within @self but not one of its children + line="326">%TRUE if a pointer is within @self but not one of its children a `GtkEventControllerMotion` + line="322">a `GtkEventControllerMotion` @@ -52506,11 +53985,9 @@ moves over the widget. transfer-ownership="none" getter="contains_pointer" default-value="FALSE"> - Whether the pointer is in the controllers widget or a descendant. + line="212">Whether the pointer is in the controllers widget or a descendant. See also [property@Gtk.EventControllerMotion:is-pointer]. @@ -52523,11 +54000,9 @@ before [signal@Gtk.EventControllerMotion::enter], but after transfer-ownership="none" getter="is_pointer" default-value="FALSE"> - Whether the pointer is in the controllers widget itself, + line="195">Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.EventControllerMotion:contains-pointer]. @@ -52540,7 +54015,7 @@ before [signal@Gtk.EventControllerMotion::enter], but after Signals that the pointer has entered the widget. + line="230">Signals that the pointer has entered the widget. @@ -52548,13 +54023,13 @@ before [signal@Gtk.EventControllerMotion::enter], but after coordinates of pointer location + line="233">coordinates of pointer location coordinates of pointer location + line="234">coordinates of pointer location @@ -52562,7 +54037,7 @@ before [signal@Gtk.EventControllerMotion::enter], but after Signals that the pointer has left the widget. + line="251">Signals that the pointer has left the widget. @@ -52570,7 +54045,7 @@ before [signal@Gtk.EventControllerMotion::enter], but after Emitted when the pointer moves inside the widget. + line="265">Emitted when the pointer moves inside the widget. @@ -52578,13 +54053,13 @@ before [signal@Gtk.EventControllerMotion::enter], but after the x coordinate + line="268">the x coordinate the y coordinate + line="269">the y coordinate @@ -52606,8 +54081,7 @@ before [signal@Gtk.EventControllerMotion::enter], but after glib:type-struct="EventControllerScrollClass"> `GtkEventControllerScroll` is an event controller that handles scroll -events. + line="20">Handles scroll events. It is capable of handling both discrete and continuous scroll events from mice or touchpads, abstracting them both with the @@ -52644,19 +54118,19 @@ motion that was received. Creates a new event controller that will handle scroll events. + line="626">Creates a new event controller that will handle scroll events. a new `GtkEventControllerScroll` + line="632">a new `GtkEventControllerScroll` flags affecting the controller behavior + line="628">flags affecting the controller behavior @@ -52665,15 +54139,14 @@ motion that was received. - Gets the flags conditioning the scroll controller behavior. + line="662">Gets the flags conditioning the scroll controller behavior. the controller flags. + line="668">the controller flags. @@ -52681,7 +54154,7 @@ motion that was received. a `GtkEventControllerScroll` + line="664">a `GtkEventControllerScroll` @@ -52692,7 +54165,7 @@ motion that was received. version="4.8"> Gets the scroll unit of the last + line="679">Gets the scroll unit of the last [signal@Gtk.EventControllerScroll::scroll] signal received. Always returns %GDK_SCROLL_UNIT_WHEEL if the @@ -52701,14 +54174,14 @@ Always returns %GDK_SCROLL_UNIT_WHEEL if the the scroll unit. + line="689">the scroll unit. a `GtkEventControllerScroll`. + line="681">a `GtkEventControllerScroll`. @@ -52717,10 +54190,9 @@ Always returns %GDK_SCROLL_UNIT_WHEEL if the - Sets the flags conditioning scroll controller behavior. + line="642">Sets the flags conditioning scroll controller behavior. @@ -52729,14 +54201,14 @@ Always returns %GDK_SCROLL_UNIT_WHEEL if the a `GtkEventControllerScroll` + line="644">a `GtkEventControllerScroll` flags affecting the controller behavior + line="645">flags affecting the controller behavior @@ -52748,19 +54220,15 @@ Always returns %GDK_SCROLL_UNIT_WHEEL if the setter="set_flags" getter="get_flags" default-value="GTK_EVENT_CONTROLLER_SCROLL_NONE"> - - The flags affecting event controller behavior. + line="522">The flags affecting event controller behavior. Emitted after scroll is finished if the + line="591">Emitted after scroll is finished if the %GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag is set. @vel_x and @vel_y express the initial velocity that was @@ -52773,13 +54241,13 @@ pixels/ms. X velocity + line="594">X velocity Y velocity + line="595">Y velocity @@ -52787,7 +54255,7 @@ pixels/ms. Signals that the widget should scroll by the + line="549">Signals that the widget should scroll by the amount specified by @dx and @dy. For the representation unit of the deltas, see @@ -52795,7 +54263,7 @@ For the representation unit of the deltas, see %TRUE if the scroll event was handled, + line="561">%TRUE if the scroll event was handled, %FALSE otherwise. @@ -52803,13 +54271,13 @@ For the representation unit of the deltas, see X delta + line="552">X delta Y delta + line="553">Y delta @@ -52817,7 +54285,7 @@ For the representation unit of the deltas, see Signals that a new scrolling operation has begun. + line="533">Signals that a new scrolling operation has begun. It will only be emitted on devices capable of it. @@ -52827,7 +54295,7 @@ It will only be emitted on devices capable of it. Signals that a scrolling operation has finished. + line="575">Signals that a scrolling operation has finished. It will only be emitted on devices capable of it. @@ -52910,7 +54378,7 @@ It will only be emitted on devices capable of it. c:type="GtkEventSequenceState"> Describes the state of a [struct@Gdk.EventSequence] in a [class@Gesture]. + line="1060">Describes the state of a [struct@Gdk.EventSequence] in a [class@Gesture]. glib:name="GTK_EVENT_SEQUENCE_NONE"> The sequence is handled, but not grabbed. + line="1062">The sequence is handled, but not grabbed. glib:name="GTK_EVENT_SEQUENCE_CLAIMED"> The sequence is handled and grabbed. + line="1063">The sequence is handled and grabbed. glib:name="GTK_EVENT_SEQUENCE_DENIED"> The sequence is denied. + line="1064">The sequence is denied. glib:type-struct="EveryFilterClass"> `GtkEveryFilter` matches an item when each of its filters matches. + line="50">Matches an item when each of its filters matches. To add filters to a `GtkEveryFilter`, use [method@Gtk.MultiFilter.append]. @@ -52957,7 +54425,7 @@ To add filters to a `GtkEveryFilter`, use [method@Gtk.MultiFilter.append]. Creates a new empty "every" filter. + line="468">Creates a new empty "every" filter. Use [method@Gtk.MultiFilter.append] to add filters to it. @@ -52968,7 +54436,7 @@ has been added to it, the filter matches every item. a new `GtkEveryFilter` + line="479">a new `GtkEveryFilter` @@ -52988,10 +54456,12 @@ has been added to it, the filter matches every item. glib:get-type="gtk_expander_get_type"> `GtkExpander` allows the user to reveal its child by clicking -on an expander triangle. + line="22">Allows the user to reveal or conceal a child widget. -![An example GtkExpander](expander.png) +<picture> + <source srcset="expander-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkExpander" src="expander.png"> +</picture> This is similar to the triangles used in a `GtkTreeView`. @@ -53079,19 +54549,19 @@ expander that is showing its child gets the `:checked` pseudoclass set on it. # Accessibility -`GtkExpander` uses the %GTK_ACCESSIBLE_ROLE_BUTTON role. +`GtkExpander` uses the [enum@Gtk.AccessibleRole.button] role. Creates a new expander using @label as the text of the label. + line="831">Creates a new expander using @label as the text of the label. a new `GtkExpander` widget. + line="837">a new `GtkExpander` widget. @@ -53101,7 +54571,7 @@ expander that is showing its child gets the `:checked` pseudoclass set on it. allow-none="1"> the text of the label + line="833">the text of the label @@ -53110,7 +54580,7 @@ expander that is showing its child gets the `:checked` pseudoclass set on it. c:identifier="gtk_expander_new_with_mnemonic"> Creates a new expander using @label as the text of the label. + line="845">Creates a new expander using @label as the text of the label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, @@ -53122,7 +54592,7 @@ Pressing Alt and that key activates the button. a new `GtkExpander` widget. + line="859">a new `GtkExpander` widget. @@ -53132,7 +54602,7 @@ Pressing Alt and that key activates the button. allow-none="1"> the text of the label with an underscore + line="847">the text of the label with an underscore in front of the mnemonic character @@ -53141,22 +54611,21 @@ Pressing Alt and that key activates the button. - Gets the child widget of @expander. + line="1250">Gets the child widget of @expander. the child widget of @expander + line="1256">the child widget of @expander a `GtkExpander` + line="1252">a `GtkExpander` @@ -53164,24 +54633,23 @@ Pressing Alt and that key activates the button. - Queries a `GtkExpander` and returns its current state. + line="932">Queries a `GtkExpander` and returns its current state. Returns %TRUE if the child widget is revealed. the current state of the expander + line="940">the current state of the expander a `GtkExpander` + line="934">a `GtkExpander` @@ -53189,10 +54657,9 @@ Returns %TRUE if the child widget is revealed. - Fetches the text from a label widget. + line="983">Fetches the text from a label widget. This is including any embedded underlines indicating mnemonics and Pango markup, as set by [method@Gtk.Expander.set_label]. If the label @@ -53203,7 +54670,7 @@ container. The text of the label widget. This string is owned + line="995">The text of the label widget. This string is owned by the widget and must not be modified or freed. @@ -53211,7 +54678,7 @@ container. a `GtkExpander` + line="985">a `GtkExpander` @@ -53219,22 +54686,21 @@ container. - Retrieves the label widget for the frame. + line="1138">Retrieves the label widget for the frame. the label widget + line="1144">the label widget a `GtkExpander` + line="1140">a `GtkExpander` @@ -53242,23 +54708,22 @@ container. - Returns whether the expander will resize the toplevel widget + line="1175">Returns whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing. the “resize toplevel” setting. + line="1182">the “resize toplevel” setting. a `GtkExpander` + line="1177">a `GtkExpander` @@ -53266,22 +54731,21 @@ containing the expander upon resizing and collapsing. - Returns whether the label’s text is interpreted as Pango markup. + line="1078">Returns whether the label’s text is interpreted as Pango markup. %TRUE if the label’s text will be parsed for markup + line="1084">%TRUE if the label’s text will be parsed for markup a `GtkExpander` + line="1080">a `GtkExpander` @@ -53289,15 +54753,14 @@ containing the expander upon resizing and collapsing. - Returns whether an underline in the text indicates a mnemonic. + line="1035">Returns whether an underline in the text indicates a mnemonic. %TRUE if an embedded underline in the expander + line="1041">%TRUE if an embedded underline in the expander label indicates the mnemonic accelerator keys @@ -53305,7 +54768,7 @@ containing the expander upon resizing and collapsing. a `GtkExpander` + line="1037">a `GtkExpander` @@ -53313,10 +54776,9 @@ containing the expander upon resizing and collapsing. - Sets the child widget of @expander. + line="1192">Sets the child widget of @expander. @@ -53325,7 +54787,7 @@ containing the expander upon resizing and collapsing. a `GtkExpander` + line="1194">a `GtkExpander` allow-none="1"> the child widget + line="1195">the child widget @@ -53342,10 +54804,9 @@ containing the expander upon resizing and collapsing. - Sets the state of the expander. + line="870">Sets the state of the expander. Set to %TRUE, if you want the child widget to be revealed, and %FALSE if you want the child widget to be hidden. @@ -53357,13 +54818,13 @@ and %FALSE if you want the child widget to be hidden. a `GtkExpander` + line="872">a `GtkExpander` whether the child widget is revealed + line="873">whether the child widget is revealed @@ -53371,10 +54832,9 @@ and %FALSE if you want the child widget to be hidden. - Sets the text of the label of the expander to @label. + line="950">Sets the text of the label of the expander to @label. This will also clear any previously set labels. @@ -53385,7 +54845,7 @@ This will also clear any previously set labels. a `GtkExpander` + line="952">a `GtkExpander` allow-none="1"> a string + line="953">a string @@ -53402,10 +54862,9 @@ This will also clear any previously set labels. - Set the label widget for the expander. + line="1094">Set the label widget for the expander. This is the widget that will appear embedded alongside the expander arrow. @@ -53417,7 +54876,7 @@ the expander arrow. a `GtkExpander` + line="1096">a `GtkExpander` allow-none="1"> the new label widget + line="1097">the new label widget @@ -53434,10 +54893,9 @@ the expander arrow. - Sets whether the expander will resize the toplevel widget + line="1154">Sets whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing. @@ -53447,13 +54905,13 @@ containing the expander upon resizing and collapsing. a `GtkExpander` + line="1156">a `GtkExpander` whether to resize the toplevel + line="1157">whether to resize the toplevel @@ -53461,10 +54919,9 @@ containing the expander upon resizing and collapsing. - Sets whether the text of the label contains Pango markup. + line="1052">Sets whether the text of the label contains Pango markup. @@ -53473,13 +54930,13 @@ containing the expander upon resizing and collapsing. a `GtkExpander` + line="1054">a `GtkExpander` %TRUE if the label’s text should be parsed for markup + line="1055">%TRUE if the label’s text should be parsed for markup @@ -53487,10 +54944,9 @@ containing the expander upon resizing and collapsing. - If true, an underline in the text indicates a mnemonic. + line="1009">If true, an underline in the text indicates a mnemonic. @@ -53499,13 +54955,13 @@ containing the expander upon resizing and collapsing. a `GtkExpander` + line="1011">a `GtkExpander` %TRUE if underlines in the text indicate mnemonics + line="1012">%TRUE if underlines in the text indicate mnemonics @@ -53515,11 +54971,9 @@ containing the expander upon resizing and collapsing. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="382">The child widget. setter="set_expanded" getter="get_expanded" default-value="FALSE"> - - Whether the expander has been opened to reveal the child. + line="315">Whether the expander has been opened to reveal the child. setter="set_label" getter="get_label" default-value="NULL"> - - The text of the expanders label. + line="326">The text of the expanders label. transfer-ownership="none" setter="set_label_widget" getter="get_label_widget"> - - A widget to display instead of the usual expander label. + line="359">A widget to display instead of the usual expander label. setter="set_resize_toplevel" getter="get_resize_toplevel" default-value="FALSE"> - - When this property is %TRUE, the expander will resize the toplevel + line="370">When this property is %TRUE, the expander will resize the toplevel widget containing the expander upon expanding and collapsing. @@ -53589,13 +55029,9 @@ widget containing the expander upon expanding and collapsing. setter="set_use_markup" getter="get_use_markup" default-value="FALSE"> - - Whether the text in the label is Pango markup. + line="348">Whether the text in the label is Pango markup. setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - Whether an underline in the text indicates a mnemonic. + line="337">Whether an underline in the text indicates a mnemonic. Activates the `GtkExpander`. + line="393">Activates the `GtkExpander`. @@ -53636,7 +55068,7 @@ widget containing the expander upon expanding and collapsing. glib:get-value-func="gtk_value_get_expression"> `GtkExpression` provides a way to describe references to values. + line="28">Provides a way to describe references to values. An important aspect of expressions is that the value can be obtained from a source that is several steps away. For example, an expression @@ -53697,7 +55129,7 @@ similar to GObject's `GBinding` mechanism, by using [method@Gtk.Expression.bind] ## GtkExpression in GObject properties In order to use a `GtkExpression` as a `GObject` property, you must use the -[id@gtk_param_spec_expression] when creating a `GParamSpec` to install in the +[func@Gtk.param_spec_expression] when creating a `GParamSpec` to install in the `GObject` class being defined; for instance: ```c @@ -53711,8 +55143,8 @@ obj_props[PROP_EXPRESSION] = ``` When implementing the `GObjectClass.set_property` and `GObjectClass.get_property` -virtual functions, you must use [id@gtk_value_get_expression], to retrieve the -stored `GtkExpression` from the `GValue` container, and [id@gtk_value_set_expression], +virtual functions, you must use [func@Gtk.value_get_expression], to retrieve the +stored `GtkExpression` from the `GValue` container, and [func@Gtk.value_set_expression], to store the `GtkExpression` into the `GValue`; for instance: ```c @@ -53735,8 +55167,9 @@ property, or in a `<binding name="property">` tag to bind a property to an To create a property expression, use the `<lookup>` element. It can have a `type` attribute to specify the object type, and a `name` attribute to specify the property -to look up. The content of `<lookup>` can either be an element specfiying the expression -to use the object, or a string that specifies the name of the object to use. +to look up. The content of `<lookup>` can either be a string that specifies the name +of the object to use, an element specifying an expression to provide an object, or +empty to use the `this` object. Example: @@ -53744,6 +55177,11 @@ Example: <lookup name='search'>string_filter</lookup> ``` +Since the `<lookup>` element creates an expression and its element content can +itself be an expression, this means that `<lookup>` tags can also be nested. +This is a common idiom when dealing with `GtkListItem`s. See +[class@Gtk.BuilderListItemFactory] for an example of this technique. + To create a constant expression, use the `<constant>` element. If the type attribute is specified, the element content is interpreted as a value of that type. Otherwise, it is assumed to be an object. For instance: @@ -53753,20 +55191,37 @@ it is assumed to be an object. For instance: <constant type='gchararray'>Hello, world</constant> ``` -To create a closure expression, use the `<closure>` element. The `type` and `function` -attributes specify what function to use for the closure, the content of the element -contains the expressions for the parameters. For instance: +To create a closure expression, use the `<closure>` element. The `function` +attribute specifies what function to use for the closure, and the `type` +attribute specifies its return type. The content of the element contains the +expressions for the parameters. For instance: ```xml <closure type='gchararray' function='combine_args_somehow'> <constant type='gchararray'>File size:</constant> <lookup type='GFile' name='size'>myfile</lookup> </closure> +``` + +To create a property binding, use the `<binding>` element in place of where a +`<property>` tag would ordinarily be used. The `name` and `object` attributes are +supported. The `name` attribute is required, and pertains to the applicable property +name. The `object` attribute is optional. If provided, it will use the specified object +as the `this` object when the expression is evaluated. Here is an example in which the +`label` property of a `GtkLabel` is bound to the `string` property of another arbitrary +object: + +```xml + <object class='GtkLabel'> + <binding name='label'> + <lookup name='string'>some_other_object</lookup> + </binding> + </object> ``` Bind `target`'s property named `property` to `self`. + line="2251">Bind `target`'s property named `property` to `self`. The value that `self` evaluates to is set via `g_object_set()` on `target`. This is repeated whenever `self` changes to ensure that @@ -53782,26 +55237,26 @@ to keep it around, you should [method@Gtk.Expression.ref] it beforehand. a `GtkExpressionWatch` + line="2272">a `GtkExpressionWatch` a `GtkExpression` + line="2253">a `GtkExpression` the target object to bind to + line="2254">the target object to bind to name of the property on `target` to bind to + line="2255">name of the property on `target` to bind to allow-none="1"> the this argument for + line="2256">the this argument for the evaluation of `self` @@ -53819,7 +55274,7 @@ to keep it around, you should [method@Gtk.Expression.ref] it beforehand. Evaluates the given expression and on success stores the result + line="1888">Evaluates the given expression and on success stores the result in @value. The `GType` of `value` will be the type given by @@ -53833,14 +55288,14 @@ will be returned. `TRUE` if the expression could be evaluated + line="1905">`TRUE` if the expression could be evaluated a `GtkExpression` + line="1890">a `GtkExpression` allow-none="1"> the this argument for the evaluation + line="1891">the this argument for the evaluation an empty `GValue` + line="1892">an empty `GValue` @@ -53864,7 +55319,7 @@ will be returned. c:identifier="gtk_expression_get_value_type"> Gets the `GType` that this expression evaluates to. + line="1869">Gets the `GType` that this expression evaluates to. This type is constant and will not change over the lifetime of this expression. @@ -53872,14 +55327,14 @@ of this expression. The type returned from [method@Gtk.Expression.evaluate] + line="1878">The type returned from [method@Gtk.Expression.evaluate] a `GtkExpression` + line="1871">a `GtkExpression` @@ -53887,7 +55342,7 @@ of this expression. Checks if the expression is static. + line="1919">Checks if the expression is static. A static expression will never change its result when [method@Gtk.Expression.evaluate] is called on it with the same arguments. @@ -53898,14 +55353,14 @@ it will never trigger a notify. `TRUE` if the expression is static + line="1931">`TRUE` if the expression is static a `GtkExpression` + line="1921">a `GtkExpression` @@ -53913,19 +55368,19 @@ it will never trigger a notify. Acquires a reference on the given `GtkExpression`. + line="1833">Acquires a reference on the given `GtkExpression`. the `GtkExpression` with an additional reference + line="1839">the `GtkExpression` with an additional reference a `GtkExpression` + line="1835">a `GtkExpression` @@ -53933,7 +55388,7 @@ it will never trigger a notify. Releases a reference on the given `GtkExpression`. + line="1851">Releases a reference on the given `GtkExpression`. If the reference was the last, the resources associated to the `self` are freed. @@ -53945,7 +55400,7 @@ freed. a `GtkExpression` + line="1853">a `GtkExpression` @@ -53953,7 +55408,7 @@ freed. Watch the given `expression` for changes. + line="1977">Watch the given `expression` for changes. The @notify function will be called whenever the evaluation of `self` may have changed. @@ -53965,7 +55420,7 @@ the @notify will be invoked. The newly installed watch. Note that the only + line="1995">The newly installed watch. Note that the only reference held to the watch will be released when the watch is unwatched which can happen automatically, and not just via [method@Gtk.ExpressionWatch.unwatch]. You should call [method@Gtk.ExpressionWatch.ref] @@ -53976,7 +55431,7 @@ the @notify will be invoked. a `GtkExpression` + line="1979">a `GtkExpression` allow-none="1"> the `this` argument to + line="1980">the `this` argument to watch @@ -53996,7 +55451,7 @@ the @notify will be invoked. destroy="3"> callback to invoke when the expression changes + line="1982">callback to invoke when the expression changes allow-none="1"> user data to pass to the `notify` callback + line="1983">user data to pass to the `notify` callback scope="async"> destroy notify for `user_data` + line="1984">destroy notify for `user_data` @@ -54049,7 +55504,7 @@ expression value changes. c:symbol-prefix="expression_watch"> An opaque structure representing a watched `GtkExpression`. + line="279">An opaque structure representing a watched `GtkExpression`. The contents of `GtkExpressionWatch` should only be accessed through the provided API. @@ -54057,7 +55512,7 @@ provided API. Evaluates the watched expression and on success stores the result + line="2115">Evaluates the watched expression and on success stores the result in `value`. This is equivalent to calling [method@Gtk.Expression.evaluate] with the @@ -54066,20 +55521,20 @@ expression and this pointer originally used to create `watch`. `TRUE` if the expression could be evaluated and `value` was set + line="2126">`TRUE` if the expression could be evaluated and `value` was set a `GtkExpressionWatch` + line="2117">a `GtkExpressionWatch` an empty `GValue` to be set + line="2118">an empty `GValue` to be set @@ -54087,19 +55542,19 @@ expression and this pointer originally used to create `watch`. Acquires a reference on the given `GtkExpressionWatch`. + line="2036">Acquires a reference on the given `GtkExpressionWatch`. the `GtkExpressionWatch` with an additional reference + line="2042">the `GtkExpressionWatch` with an additional reference a `GtkExpressionWatch` + line="2038">a `GtkExpressionWatch` @@ -54107,7 +55562,7 @@ expression and this pointer originally used to create `watch`. Releases a reference on the given `GtkExpressionWatch`. + line="2062">Releases a reference on the given `GtkExpressionWatch`. If the reference was the last, the resources associated to `self` are freed. @@ -54119,7 +55574,7 @@ freed. a `GtkExpressionWatch` + line="2064">a `GtkExpressionWatch` @@ -54127,7 +55582,7 @@ freed. Stops watching an expression. + line="2077">Stops watching an expression. See [method@Gtk.Expression.watch] for how the watch was established. @@ -54139,7 +55594,7 @@ was established. watch to release + line="2079">watch to release @@ -54502,7 +55957,6 @@ in a file chooser. glib:get-property="action" deprecated="1" deprecated-version="4.10"> - Gets the type of operation that the file chooser is performing. @@ -54559,7 +56013,6 @@ in a file chooser. glib:get-property="create-folders" deprecated="1" deprecated-version="4.10"> - Gets whether file chooser will offer to create new folders. @@ -54704,7 +56157,6 @@ of @chooser as `GFile`. glib:get-property="filter" deprecated="1" deprecated-version="4.10"> - Gets the current filter. @@ -54731,7 +56183,6 @@ of @chooser as `GFile`. glib:get-property="filters" deprecated="1" deprecated-version="4.10"> - Gets the current set of user-selectable filters, as a list model. @@ -54765,7 +56216,6 @@ You should not modify the returned list model. Future changes to glib:get-property="select-multiple" deprecated="1" deprecated-version="4.10"> - Gets whether multiple files can be selected in the file @@ -54793,8 +56243,6 @@ chooser. glib:get-property="shortcut-folders" deprecated="1" deprecated-version="4.10"> - Queries the list of shortcut folders in the file chooser. @@ -54913,7 +56361,6 @@ You should not modify the returned list model. Future changes to glib:set-property="action" deprecated="1" deprecated-version="4.10"> - Sets the type of operation that the chooser is performing. @@ -54985,7 +56432,6 @@ For a boolean choice, the possible options are "true" and "false". glib:set-property="create-folders" deprecated="1" deprecated-version="4.10"> - Sets whether file chooser will offer to create new folders. @@ -55167,7 +56613,6 @@ prepare_file_chooser (GtkFileChooser *chooser, glib:set-property="filter" deprecated="1" deprecated-version="4.10"> - Sets the current filter. @@ -55205,7 +56650,6 @@ set of files without letting the user change it. glib:set-property="select-multiple" deprecated="1" deprecated-version="4.10"> - Sets whether multiple files can be selected in the file chooser. @@ -55241,10 +56685,6 @@ This is only relevant if the action is set to be setter="set_action" getter="get_action" default-value="GTK_FILE_CHOOSER_ACTION_OPEN"> - - The type of operation that the file chooser is performing. @@ -55259,10 +56699,6 @@ This is only relevant if the action is set to be setter="set_create_folders" getter="get_create_folders" default-value="TRUE"> - - Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode @@ -55277,10 +56713,6 @@ will offer the user to create new folders. transfer-ownership="none" setter="set_filter" getter="get_filter"> - - The current filter for selecting files that are displayed. @@ -55292,8 +56724,6 @@ will offer the user to create new folders. deprecated-version="4.10" transfer-ownership="none" getter="get_filters"> - A `GListModel` containing the filters that have been @@ -55312,10 +56742,6 @@ or may not be updated for later changes. setter="set_select_multiple" getter="get_select_multiple" default-value="FALSE"> - - Whether to allow multiple files to be selected. @@ -55327,8 +56753,6 @@ or may not be updated for later changes. deprecated-version="4.10" transfer-ownership="none" getter="get_shortcut_folders"> - A `GListModel` containing the shortcut folders that have been @@ -55578,7 +57002,7 @@ class `.filechooser`. deprecated-version="4.10"> Creates a new `GtkFileChooserDialog`. + line="719">Creates a new `GtkFileChooserDialog`. This function is analogous to [ctor@Gtk.Dialog.new_with_buttons]. Use [class@Gtk.FileDialog] instead @@ -55587,7 +57011,7 @@ This function is analogous to [ctor@Gtk.Dialog.new_with_buttons]. a new `GtkFileChooserDialog` + line="731">a new `GtkFileChooserDialog` @@ -55597,7 +57021,7 @@ This function is analogous to [ctor@Gtk.Dialog.new_with_buttons]. allow-none="1"> Title of the dialog + line="721">Title of the dialog allow-none="1"> Transient parent of the dialog + line="722">Transient parent of the dialog Open or save mode for the dialog + line="723">Open or save mode for the dialog allow-none="1"> text to go in the first button + line="724">text to go in the first button response ID for the first button, then additional (button, id) pairs, ending with %NULL + line="725">response ID for the first button, then additional (button, id) pairs, ending with %NULL @@ -55859,14 +57283,14 @@ are not supported: deprecated-version="4.10"> Creates a new `GtkFileChooserNative`. + line="531">Creates a new `GtkFileChooserNative`. Use [class@Gtk.FileDialog] instead a new `GtkFileChooserNative` + line="541">a new `GtkFileChooserNative` @@ -55876,7 +57300,7 @@ are not supported: allow-none="1"> Title of the native + line="533">Title of the native Transient parent of the native + line="534">Transient parent of the native Open or save mode for the dialog + line="535">Open or save mode for the dialog text to go in the accept button, or %NULL for the default + line="536">text to go in the accept button, or %NULL for the default text to go in the cancel button, or %NULL for the default + line="537">text to go in the cancel button, or %NULL for the default @@ -55919,24 +57343,23 @@ are not supported: glib:get-property="accept-label" deprecated="1" deprecated-version="4.10"> - Retrieves the custom label text for the accept button. + line="218">Retrieves the custom label text for the accept button. Use [class@Gtk.FileDialog] instead The custom label + line="224">The custom label a `GtkFileChooserNative` + line="220">a `GtkFileChooserNative` @@ -55946,24 +57369,23 @@ are not supported: glib:get-property="cancel-label" deprecated="1" deprecated-version="4.10"> - Retrieves the custom label text for the cancel button. + line="264">Retrieves the custom label text for the cancel button. Use [class@Gtk.FileDialog] instead The custom label + line="270">The custom label a `GtkFileChooserNative` + line="266">a `GtkFileChooserNative` @@ -55973,10 +57395,9 @@ are not supported: glib:set-property="accept-label" deprecated="1" deprecated-version="4.10"> - Sets the custom label text for the accept button. + line="236">Sets the custom label text for the accept button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, @@ -55994,7 +57415,7 @@ Pressing Alt and that key should activate the button. a `GtkFileChooserNative` + line="238">a `GtkFileChooserNative` allow-none="1"> custom label + line="239">custom label @@ -56013,10 +57434,9 @@ Pressing Alt and that key should activate the button. glib:set-property="cancel-label" deprecated="1" deprecated-version="4.10"> - Sets the custom label text for the cancel button. + line="282">Sets the custom label text for the cancel button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, @@ -56034,7 +57454,7 @@ Pressing Alt and that key should activate the button. a `GtkFileChooserNative` + line="284">a `GtkFileChooserNative` allow-none="1"> custom label + line="285">custom label @@ -56054,13 +57474,9 @@ Pressing Alt and that key should activate the button. setter="set_accept_label" getter="get_accept_label" default-value="NULL"> - - The text used for the label on the accept button in the dialog, or + line="786">The text used for the label on the accept button in the dialog, or %NULL to use the default text. @@ -56070,13 +57486,9 @@ Pressing Alt and that key should activate the button. setter="set_cancel_label" getter="get_cancel_label" default-value="NULL"> - - The text used for the label on the cancel button in the dialog, or + line="797">The text used for the label on the cancel button in the dialog, or %NULL to use the default text. @@ -56100,12 +57512,33 @@ Pressing Alt and that key should activate the button. glib:get-type="gtk_file_chooser_widget_get_type"> `GtkFileChooserWidget` is a widget for choosing files. + line="113">`GtkFileChooserWidget` is a widget for choosing files. It exposes the [iface@Gtk.FileChooser] interface, and you should use the methods of this interface to interact with the widget. +# Shortcuts and Gestures + +`GtkFileChooserWidget` supports the following keyboard shortcuts: + +- <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. + +The following signals have default keybindings: + +- [signal@Gtk.FileChooserWidget::desktop-folder] +- [signal@Gtk.FileChooserWidget::down-folder] +- [signal@Gtk.FileChooserWidget::home-folder] +- [signal@Gtk.FileChooserWidget::location-popup] +- [signal@Gtk.FileChooserWidget::location-popup-on-paste] +- [signal@Gtk.FileChooserWidget::location-toggle-popup] +- [signal@Gtk.FileChooserWidget::places-shortcut] +- [signal@Gtk.FileChooserWidget::quick-bookmark] +- [signal@Gtk.FileChooserWidget::recent-shortcut] +- [signal@Gtk.FileChooserWidget::search-shortcut] +- [signal@Gtk.FileChooserWidget::show-hidden] +- [signal@Gtk.FileChooserWidget::up-folder] + # CSS nodes `GtkFileChooserWidget` has a single CSS node with name filechooser. @@ -56120,7 +57553,7 @@ widget. deprecated-version="4.10"> Creates a new `GtkFileChooserWidget`. + line="7531">Creates a new `GtkFileChooserWidget`. This is a file chooser widget that can be embedded in custom windows, and it is the same widget that is used by @@ -56131,14 +57564,14 @@ windows, and it is the same widget that is used by a new `GtkFileChooserWidget` + line="7541">a new `GtkFileChooserWidget` Open or save mode for the widget + line="7533">Open or save mode for the widget @@ -56147,6 +57580,9 @@ windows, and it is the same widget that is used by writable="1" transfer-ownership="none" default-value="FALSE"> + Whether search mode is enabled. Whether to show the time. + line="6727">Whether to show the time. + The subtitle of the file chooser widget. Emitted when the user asks for it. + line="6489">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56179,7 +57618,7 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>D&l Emitted when the user asks for it. + line="6441">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56198,7 +57637,7 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>Dow Emitted when the user asks for it. + line="6467">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56213,7 +57652,7 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>Hom Emitted when the user asks for it. + line="6346">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56233,7 +57672,7 @@ access to home directories. a string that gets put in the text entry for the file name + line="6349">a string that gets put in the text entry for the file name @@ -56241,7 +57680,7 @@ access to home directories. Emitted when the user asks for it. + line="6374">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56256,7 +57695,7 @@ The default binding for this signal is <kbd>Control</kbd>-<kbd> Emitted when the user asks for it. + line="6396">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56272,7 +57711,7 @@ The default binding for this signal is <kbd>Control</kbd>-<kbd> Emitted when the user asks for it. + line="6603">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56286,7 +57725,7 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>P&l Emitted when the user asks for it. + line="6511">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56307,7 +57746,7 @@ successively. the number of the bookmark to switch to + line="6514">the number of the bookmark to switch to @@ -56315,7 +57754,7 @@ successively. Emitted when the user asks for it. + line="6582">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56329,7 +57768,7 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>R&l Emitted when the user asks for it. + line="6561">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56343,7 +57782,7 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>S&l Emitted when the user asks for it. + line="6540">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56357,7 +57796,7 @@ The default binding for this signal is <kbd>Control</kbd>-<kbd> Emitted when the user asks for it. + line="6419">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -56380,28 +57819,26 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>Up& glib:type-struct="FileDialogClass"> A `GtkFileDialog` object collects the arguments that -are needed to present a file chooser dialog to the -user, such as a title for the dialog and whether it -should be modal. + line="32">Asynchronous API to present a file chooser dialog. + +`GtkFileDialog` collects the arguments that are needed to present +the dialog to the user, such as a title for the dialog and whether +it should be modal. The dialog is shown with [method@Gtk.FileDialog.open], -[method@Gtk.FileDialog.save], etc. These APIs follow the -GIO async pattern, and the result can be obtained by calling -the corresponding finish function, for example -[method@Gtk.FileDialog.open_finish]. +[method@Gtk.FileDialog.save], etc. Creates a new `GtkFileDialog` object. + line="352">Creates a new `GtkFileDialog` object. the new `GtkFileDialog` + line="357">the new `GtkFileDialog` @@ -56409,18 +57846,21 @@ the corresponding finish function, for example c:identifier="gtk_file_dialog_get_accept_label" glib:get-property="accept-label" version="4.10"> + Retrieves the text used by the dialog on its accept button. the label shown on the file chooser's accept button. + line="753">the label shown on the file chooser's accept button a `GtkFileDialog` + line="749">a file dialog @@ -56437,14 +57877,14 @@ in the file chooser dialog. the current filter + line="509">the default filter a `GtkFileDialog` + line="504">a file dialog @@ -56461,15 +57901,15 @@ in the file chooser dialog. the filters, as - a `GListModel` of `GtkFileFilters` + line="466">the filters, + as a list model of [class@Gtk.FileFilter] a `GtkFileDialog` + line="461">a file dialog @@ -56480,20 +57920,20 @@ in the file chooser dialog. version="4.10"> Gets the file that will be initially selected in + line="652">Gets the file that will be initially selected in the file chooser dialog. the file + line="659">the file a `GtkFileDialog` + line="654">a file dialog @@ -56517,7 +57957,7 @@ initial folder in the file chooser dialog. a `GtkFileDialog` + line="550">a file dialog @@ -56528,7 +57968,7 @@ initial folder in the file chooser dialog. version="4.10"> Gets the name for the file that should be initially set. + line="598">Gets the filename that will be initially selected. a `GtkFileDialog` + line="600">a file dialog @@ -56551,21 +57991,20 @@ initial folder in the file chooser dialog. version="4.10"> Returns whether the file chooser dialog -blocks interaction with the parent window -while it is presented. + line="416">Returns whether the file chooser dialog blocks interaction +with the parent window while it is presented. `TRUE` if the file chooser dialog is modal + line="423">true if the file chooser dialog is modal a `GtkFileDialog` + line="418">a file dialog @@ -56576,33 +58015,34 @@ while it is presented. version="4.10"> Returns the title that will be shown on the -file chooser dialog. + line="370">Returns the title that will be shown on the file chooser dialog. the title + line="376">the title a `GtkFileDialog` + line="372">a file dialog - + This function initiates a file selection operation by -presenting a file chooser dialog to the user. + line="1001">Presents a file chooser dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.open_finish] -to obtain the result. +The file chooser dialog will be set up to select a single file. + +The @callback will be called when the dialog is dismissed. @@ -56611,7 +58051,305 @@ to obtain the result. a `GtkFileDialog` + line="1003">a file dialog + + + + the parent window + + + + a cancellable to cancel the operation + + + + a callback to call when the + operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.FileDialog.open] call. + + + the file that was selected + + + + + a file dialog + + + + the result + + + + + + Presents a file chooser dialog to the user. + +The file chooser dialog will be set up to select multiple files. + +The file chooser dialog will initially be opened in the directory +[property@Gtk.FileDialog:initial-folder]. + +The @callback will be called when the dialog is dismissed. + + + + + + + a file dialog + + + + the parent window + + + + a cancellable to cancel the operation + + + + a callback to call when the + operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.FileDialog.open] call. + + + the files that were selected, + as a list model of [iface@Gio.File] + + + + + a file dialog + + + + the result + + + + + + Presents a file chooser dialog to the user. + +The file chooser dialog will be set up to select multiple files. + +The file chooser dialog will initially be opened in the directory +[property@Gtk.FileDialog:initial-folder]. + +In contrast to [method@Gtk.FileDialog.open], this function +lets the user select the text encoding for the files, if possible. + +The @callback will be called when the dialog is dismissed. + + + + + + + a file dialog + + + + the parent window + + + + a cancellable to cancel the operation + + + + a callback to call when the + operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.FileDialog.open] call. + + + the files that were selected, + as a list model of [iface@Gio.File] + + + + + a file dialog + + + + the result + + + + return location for the text encoding to use + + + + + + Initiates a file selection operation by presenting a file chooser +dialog to the user. + +In contrast to [method@Gtk.FileDialog.open], this function +lets the user select the text encoding for the file, if possible. + +The @callback will be called when the dialog is dismissed. + + + + + + + a `GtkFileDialog` allow-none="1"> the parent `GtkWindow` + line="1360">the parent `GtkWindow` allow-none="1"> a `GCancellable` to cancel the operation + line="1361">a `GCancellable` to cancel the operation closure="3"> a callback to call when the operation is complete + line="1362">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="1364">data to pass to @callback - Finishes the [method@Gtk.FileDialog.open] call and -returns the resulting file. - + line="1423">Finishes the [method@Gtk.FileDialog.open_text_file] call +and returns the resulting file and text encoding. + +If the user has explicitly selected a text encoding to use +for the file, then @encoding will be set to a codeset name that +is suitable for passing to iconv_open(). Otherwise, it will +be `NULL`. + the file that was selected. - Otherwise, `NULL` is returned and @error is set + line="1438">the file that was selected a `GtkFileDialog` + line="1425">a `GtkFileDialog` a `GAsyncResult` + line="1426">a `GAsyncResult` + + return location for the text encoding to use + + - + This function initiates a multi-file selection operation by -presenting a file chooser dialog to the user. + line="1141">Presents a file chooser dialog to the user. -The file chooser will initially be opened in the directory -[property@Gtk.FileDialog:initial-folder]. +The file chooser dialog will be save mode. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.open_multiple_finish] -to obtain the result. - +The @callback will be called when the dialog is dismissed. + @@ -56708,7 +58456,7 @@ to obtain the result. a `GtkFileDialog` + line="1143">a file dialog allow-none="1"> the parent `GtkWindow` + line="1144">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="1145">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="1146">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="1148">data to pass to @callback - Finishes the [method@Gtk.FileDialog.open] call and -returns the resulting files in a `GListModel`. - + line="1185">Finishes the [method@Gtk.FileDialog.save] call. + the file that was selected, - as a `GListModel` of `GFiles`. Otherwise, `NULL` is returned - and @error is set - + line="1193">the file that was selected + a `GtkFileDialog` + line="1187">a file dialog a `GAsyncResult` + line="1188">the result - + This function initiates a file save operation by -presenting a file chooser dialog to the user. + line="1582">Initiates a file save operation by presenting a file chooser +dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.save_finish] -to obtain the result. - +In contrast to [method@Gtk.FileDialog.save], this function +lets the user select the text encoding and line endings for +the text file, if possible. + +The @callback will be called when the dialog is dismissed. + @@ -56801,7 +58551,7 @@ to obtain the result. a `GtkFileDialog` + line="1584">a `GtkFileDialog` allow-none="1"> the parent `GtkWindow` + line="1585">the parent `GtkWindow` allow-none="1"> a `GCancellable` to cancel the operation + line="1586">a `GCancellable` to cancel the operation closure="3"> a callback to call when the operation is complete + line="1587">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="1589">data to pass to @callback - Finishes the [method@Gtk.FileDialog.save] call and -returns the resulting file. - + line="1663">Finishes the [method@Gtk.FileDialog.save_text_file] call +and returns the resulting file, text encoding and line endings. + +If the user has explicitly selected a text encoding to use +for the file, then @encoding will be set to a codeset name that +is suitable for passing to iconv_open(). Otherwise, it will +be `NULL`. + +The @line_ending will be set to one of "\n", "\r\n", "\r" or "", +where the latter means to preserve existing line endings. + the file that was selected. + line="1682">the file that was selected. Otherwise, `NULL` is returned and @error is set @@ -56865,32 +58623,50 @@ returns the resulting file. a `GtkFileDialog` + line="1665">a `GtkFileDialog` a `GAsyncResult` + line="1666">a `GAsyncResult` + + return location for the text encoding to use + + + + return location for the line endings to use + + + version="4.10" + glib:finish-func="select_folder_finish"> This function initiates a directory selection operation by -presenting a file chooser dialog to the user. + line="1069">Presents a file chooser dialog to the user. -If you pass @initial_folder, the file chooser will initially be -opened in the parent directory of that folder, otherwise, it +The file chooser dialog will be set up to select a single folder. + +If you pass @initial_folder, the file chooser dialog will initially +be opened in the parent directory of that folder, otherwise, it will be in the directory [property@Gtk.FileDialog:initial-folder]. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.select_folder_finish] -to obtain the result. +The @callback will be called when the dialog is dismissed. @@ -56899,7 +58675,7 @@ to obtain the result. a `GtkFileDialog` + line="1071">a file dialog allow-none="1"> the parent `GtkWindow` + line="1072">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="1073">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="1074">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="1076">data to pass to @callback @@ -56949,45 +58725,44 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.FileDialog.select_folder] call and -returns the resulting file. + line="1117">Finishes the [method@Gtk.FileDialog.select_folder] call. the file that was selected. - Otherwise, `NULL` is returned and @error is set + line="1125">the folder that was selected a `GtkFileDialog` + line="1119">a file dialog a `GAsyncResult` + line="1120">the result + version="4.10" + glib:finish-func="select_multiple_folders_finish"> This function initiates a multi-directory selection operation by -presenting a file chooser dialog to the user. + line="1281">Presents a file chooser dialog to the user. -The file chooser will initially be opened in the directory -[property@Gtk.FileDialog:initial-folder]. +The file chooser dialog will be set up to allow selecting +multiple folders. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.select_multiple_folders_finish] -to obtain the result. +The file chooser dialog will initially be opened in the +directory [property@Gtk.FileDialog:initial-folder]. + +The @callback will be called when the dialog is dismissed. @@ -56996,7 +58771,7 @@ to obtain the result. a `GtkFileDialog` + line="1283">a file dialog allow-none="1"> the parent `GtkWindow` + line="1284">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="1285">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="1286">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="1288">data to pass to @callback @@ -57046,28 +58821,26 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.FileDialog.select_multiple_folders] -call and returns the resulting files in a `GListModel`. + line="1329">Finishes the [method@Gtk.FileDialog.select_multiple_folders] call. the file that was selected, - as a `GListModel` of `GFiles`. Otherwise, `NULL` is returned - and @error is set + line="1337">the folders that were selected, + as a list model of [iface@Gio.File] a `GtkFileDialog` + line="1331">a file dialog a `GAsyncResult` + line="1332">the result @@ -57078,10 +58851,11 @@ call and returns the resulting files in a `GListModel`. version="4.10"> Sets the label shown on the file chooser's accept button. + line="765">Sets the label shown on the file chooser's accept button. -Leaving the accept label unset or setting it as `NULL` will fall back to -a default label, depending on what API is used to launch the file dialog. +Leaving the accept label unset or setting it as `NULL` will +fall back to a default label, depending on what API is used +to launch the file dialog. @@ -57090,7 +58864,7 @@ a default label, depending on what API is used to launch the file dialog. a `GtkFileDialog` + line="767">a file dialog allow-none="1"> the new accept label + line="768">the new accept label @@ -57113,7 +58887,7 @@ a default label, depending on what API is used to launch the file dialog. line="521">Sets the filter that will be selected by default in the file chooser dialog. -If set to %NULL, the first item in [property@Gtk.FileDialog:filters] +If set to `NULL`, the first item in [property@Gtk.FileDialog:filters] will be used as the default filter. If that list is empty, the dialog will be unfiltered. @@ -57124,7 +58898,7 @@ will be unfiltered. a `GtkFileDialog` + line="523">a file dialog allow-none="1"> a `GtkFileFilter` + line="524">the file filter @@ -57154,7 +58928,7 @@ in the file chooser dialog. a `GtkFileDialog` + line="481">a file dialog allow-none="1"> a `GListModel` of `GtkFileFilters` + line="482">a list model of [class@Gtk.FileFilter] @@ -57174,13 +58948,13 @@ in the file chooser dialog. version="4.10"> Sets the file that will be initially selected in + line="671">Sets the file that will be initially selected in the file chooser dialog. This function is a shortcut for calling both -gtk_file_dialog_set_initial_folder() and -gtk_file_dialog_set_initial_name() with the directory and -name of @file respectively. +[method@Gtk.FileDialog.set_initial_folder] and +[method@Gtk.FileDialog.set_initial_name] with the +directory and name of @file, respectively. @@ -57189,7 +58963,7 @@ name of @file respectively. a `GtkFileDialog` + line="673">a file dialog allow-none="1"> a `GFile` + line="674">a file @@ -57219,7 +58993,7 @@ initial folder in the file chooser dialog. a `GtkFileDialog` + line="569">a file dialog allow-none="1"> a `GFile` + line="570">a file @@ -57239,11 +59013,14 @@ initial folder in the file chooser dialog. version="4.10"> Sets the name for the file that should be initially set. -For saving dialogs, this will usually be pre-entered into the name field. + line="616">Sets the filename that will be initially selected. + +For save dialogs, @name will usually be pre-entered into the +name field. -If a file with this name already exists in the directory set via -[property@Gtk.FileDialog:initial-folder], the dialog should preselect it. +If a file with this name already exists in the directory set +via [property@Gtk.FileDialog:initial-folder], the dialog will +preselect it. @@ -57252,7 +59029,7 @@ If a file with this name already exists in the directory set via a `GtkFileDialog` + line="618">a file dialog a UTF8 string + line="619">a string @@ -57272,9 +59049,8 @@ If a file with this name already exists in the directory set via version="4.10"> Sets whether the file chooser dialog -blocks interaction with the parent window -while it is presented. + line="435">Sets whether the file chooser dialog blocks interaction +with the parent window while it is presented. @@ -57283,13 +59059,13 @@ while it is presented. a `GtkFileDialog` + line="437">a file dialog the new value + line="438">the new value @@ -57300,8 +59076,7 @@ while it is presented. version="4.10"> Sets the title that will be shown on the -file chooser dialog. + line="388">Sets the title that will be shown on the file chooser dialog. @@ -57310,13 +59085,13 @@ file chooser dialog. a `GtkFileDialog` + line="390">a file dialog the new title + line="391">the new title @@ -57328,13 +59103,9 @@ file chooser dialog. setter="set_accept_label" getter="get_accept_label" default-value="NULL"> - - Label for the file chooser's accept button. + line="314">Label for the file chooser's accept button. transfer-ownership="none" setter="set_default_filter" getter="get_default_filter"> - - The default filter, that is, the filter that is initially -active in the file chooser dialog. + line="248">The default filter. + +This filter is initially active in the file chooser dialog. -If the default filter is %NULL, the first filter of [property@Gtk.FileDialog:filters] +If the default filter is `NULL`, the first filter of [property@Gtk.FileDialog:filters] is used as the default filter. If that property contains no filter, the dialog will be unfiltered. -If [property@Gtk.FileDialog:filters] is not %NULL, the default filter should be part -of the list. If it is not, the dialog may choose to not make it available. +If [property@Gtk.FileDialog:filters] is not `NULL`, the default filter should be +part of the list. If it is not, the dialog may choose to not make it available. transfer-ownership="none" setter="set_filters" getter="get_filters"> - - The list of filters. + line="233">The list of filters. -See [property@Gtk.FileDialog:default-filter] about how those two properties interact. +See [property@Gtk.FileDialog:default-filter] about how these +two properties interact. - - The initial file, that is, the file that is initially selected -in the file chooser dialog + line="269">The initial file. + +This file is initially selected in the file chooser dialog -This is a utility property that sets both [property@Gtk.FileDialog:initial-folder] and -[property@Gtk.FileDialog:initial-name]. +This is a utility property that sets both [property@Gtk.FileDialog:initial-folder] +and [property@Gtk.FileDialog:initial-name]. - - The initial folder, that is, the directory that is initially -opened in the file chooser dialog + line="286">The initial folder. + +This is the directory that is initially opened in the file chooser dialog. setter="set_initial_name" getter="get_initial_name" default-value="NULL"> - - The initial name, that is, the filename that is initially -selected in the file chooser dialog. + line="300">The initial name. + +This is the name of the file that is initially selected in the file chooser dialog. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the file chooser dialog is modal. + line="221">Whether the file chooser dialog is modal. setter="set_title" getter="get_title" default-value="NULL"> - - A title that may be shown on the file chooser dialog. + line="209">A title that may be shown on the file chooser dialog. @@ -57478,10 +59226,10 @@ selected in the file chooser dialog. glib:get-type="gtk_file_filter_get_type"> `GtkFileFilter` filters files by name or mime type. + line="19">Filters files by name or mime type. `GtkFileFilter` can be used to restrict the files being shown in a -`GtkFileChooser`. Files can be filtered based on their name (with +file chooser. Files can be filtered based on their name (with [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]) or on their mime type (with [method@Gtk.FileFilter.add_mime_type]). @@ -57491,8 +59239,8 @@ type application/rtf, since application/rtf is a subclass of text/plain. Note that `GtkFileFilter` allows wildcards for the subtype of a mime type, so you can e.g. filter for image/\*. -Normally, file filters are used by adding them to a `GtkFileChooser` -(see [method@Gtk.FileChooser.add_filter]), but it is also possible to +Normally, file filters are used by adding them to a file chooser +(see [method@Gtk.FileDialog.set_filters]), but it is also possible to manually use a file filter on any [class@Gtk.FilterListModel] containing `GFileInfo` objects. @@ -57528,7 +59276,7 @@ rules: Creates a new `GtkFileFilter` with no rules added to it. + line="520">Creates a new `GtkFileFilter` with no rules added to it. Such a filter doesn’t accept any files, so is not particularly useful until you add rules with @@ -57546,7 +59294,7 @@ gtk_file_filter_add_pattern (filter, "*"); a new `GtkFileFilter` + line="538">a new `GtkFileFilter` @@ -57554,7 +59302,7 @@ gtk_file_filter_add_pattern (filter, "*"); c:identifier="gtk_file_filter_new_from_gvariant"> Deserialize a file filter from a `GVariant`. + line="1091">Deserialize a file filter from a `GVariant`. The variant must be in the format produced by [method@Gtk.FileFilter.to_gvariant]. @@ -57562,14 +59310,14 @@ The variant must be in the format produced by a new `GtkFileFilter` object + line="1100">a new `GtkFileFilter` object an `a{sv}` `GVariant` + line="1093">an `a{sv}` `GVariant` @@ -57578,7 +59326,7 @@ The variant must be in the format produced by c:identifier="gtk_file_filter_add_mime_type"> Adds a rule allowing a given mime type to @filter. + line="618">Adds a rule allowing a given mime type. @@ -57587,13 +59335,13 @@ The variant must be in the format produced by A `GtkFileFilter` + line="620">A file filter name of a MIME type + line="621">name of a MIME type @@ -57601,7 +59349,7 @@ The variant must be in the format produced by Adds a rule allowing a shell style glob to a filter. + line="643">Adds a rule allowing a shell style glob pattern. Note that it depends on the platform whether pattern matching ignores case or not. On Windows, it does, on @@ -57614,13 +59362,13 @@ other platforms, it doesn't. a `GtkFileFilter` + line="645">a file filter a shell style glob + line="646">a shell style glob pattern @@ -57629,8 +59377,7 @@ other platforms, it doesn't. c:identifier="gtk_file_filter_add_pixbuf_formats"> Adds a rule allowing image files in the formats supported -by GdkPixbuf. + line="709">Adds a rule allowing image files in the formats supported by `GdkPixbuf`. This is equivalent to calling [method@Gtk.FileFilter.add_mime_type] for all the supported mime types. @@ -57642,7 +59389,7 @@ for all the supported mime types. a `GtkFileFilter` + line="711">a file filter @@ -57652,10 +59399,16 @@ for all the supported mime types. version="4.4"> Adds a suffix match rule to a filter. + line="671">Adds a suffix match rule to a filter. -This is similar to adding a match for the pattern -"*.@suffix". +This is similar to adding a match for the pattern "*.@suffix" + +An exaple to filter files with the suffix ".sub": +```c +gtk_file_filter_add_suffix (filter, "sub"); +``` + +Filters with multiple dots are allowed. In contrast to pattern matches, suffix matches are *always* case-insensitive. @@ -57667,13 +59420,13 @@ are *always* case-insensitive. a `GtkFileFilter` + line="673">a file filter filename suffix to match + line="674">filename suffix to match @@ -57682,17 +59435,16 @@ are *always* case-insensitive. c:identifier="gtk_file_filter_get_attributes"> Gets the attributes that need to be filled in for the `GFileInfo` + line="755">Gets the attributes that need to be filled in for the `GFileInfo` passed to this filter. This function will not typically be used by applications; -it is intended principally for use in the implementation -of `GtkFileChooser`. +it is intended for use in file chooser implementation. the attributes + line="765">the attributes @@ -57701,7 +59453,7 @@ of `GtkFileChooser`. a `GtkFileFilter` + line="757">a file filter @@ -57709,24 +59461,23 @@ of `GtkFileChooser`. - Gets the human-readable name for the filter. + line="571">Gets the human-readable name for the filter. See [method@Gtk.FileFilter.set_name]. The human-readable name of the filter + line="579">the human-readable name of the filter a `GtkFileFilter` + line="573">a file filter @@ -57734,12 +59485,11 @@ See [method@Gtk.FileFilter.set_name]. - Sets a human-readable name of the filter. + line="546">Sets a human-readable name of the filter. -This is the string that will be displayed in the file chooser +This is the string that will be displayed in the user interface if there is a selectable list of filters. @@ -57749,7 +59499,7 @@ if there is a selectable list of filters. a `GtkFileFilter` + line="548">a file filter allow-none="1"> the human-readable-name for the filter, or %NULL - to remove any existing name. + line="549">the human-readable name for the filter @@ -57767,19 +59516,19 @@ if there is a selectable list of filters. Serialize a file filter to an `a{sv}` variant. + line="1013">Serialize a file filter to an `a{sv}` variant. a new, floating, `GVariant` + line="1019">a new, floating, `GVariant` a `GtkFileFilter` + line="1015">a file filter @@ -57792,7 +59541,7 @@ if there is a selectable list of filters. transfer-ownership="none"> The MIME types that this filter matches. + line="287">The MIME types that this filter matches. @@ -57803,16 +59552,12 @@ if there is a selectable list of filters. setter="set_name" getter="get_name" default-value="NULL"> - - The human-readable name of the filter. + line="262">The human-readable name of the filter. -This is the string that will be displayed in the file chooser -user interface if there is a selectable list of filters. +This is the string that will be displayed in the user interface +if there is a selectable list of filters. transfer-ownership="none"> The patterns that this filter matches. + line="275">The patterns that this filter matches. @@ -57836,7 +59581,7 @@ user interface if there is a selectable list of filters. transfer-ownership="none"> The suffixes that this filter matches. + line="299">The suffixes that this filter matches. @@ -57852,16 +59597,15 @@ user interface if there is a selectable list of filters. glib:type-struct="FileLauncherClass"> A `GtkFileLauncher` object collects the arguments that are needed to open a -file with an application. + line="44">Asynchronous API to open a file with an application. + +`GtkFileLauncher` collects the arguments that are needed to open the file. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.FileLauncher.launch] function. -This API follows the GIO async pattern, and the result can be obtained by -calling [method@Gtk.FileLauncher.launch_finish]. To launch uris that don't represent files, use [class@Gtk.UriLauncher]. @@ -57870,12 +59614,12 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. version="4.10"> Creates a new `GtkFileLauncher` object. + line="208">Creates a new `GtkFileLauncher` object. the new `GtkFileLauncher` + line="214">the new `GtkFileLauncher` @@ -57885,7 +59629,7 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. allow-none="1"> the file to open + line="210">the file to open @@ -57896,19 +59640,19 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. version="4.12"> Returns whether to ask the user to choose an app for opening the file. + line="269">Returns whether to ask the user which app to use. `TRUE` if always asking for app + line="275">true if always asking the user a `GtkFileLauncher` + line="271">a file launcher @@ -57919,36 +59663,56 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. version="4.10"> Gets the file that will be opened. + line="229">Gets the file that will be opened. the file + line="235">the file a `GtkFileLauncher` + line="231">a file launcher + + + + + + Returns whether to make the file writable for the handler. + + + true if the file will be made writable + + + + + a file launcher + version="4.10" + glib:finish-func="launch_finish"> Launch an application to open the file. + line="532">Launches an application to open the file. -This may present an app chooser dialog to the user. - -The @callback will be called when the operation is completed. -It should call [method@Gtk.FileLauncher.launch_finish] to obtain -the result. - +This may present an app chooser dialog to the user. + @@ -57956,7 +59720,7 @@ the result. a `GtkFileLauncher` + line="534">a file launcher allow-none="1"> the parent `GtkWindow` + line="535">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="536">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="537">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="539">data to pass to @callback @@ -58006,45 +59770,41 @@ the result. throws="1"> Finishes the [method@Gtk.FileLauncher.launch] call and + line="617">Finishes the [method@Gtk.FileLauncher.launch] call and returns the result. - + `TRUE` if an application was launched, - or `FALSE` and @error is set + line="626">true if an application was launched a `GtkFileLauncher` + line="619">a file launcher a `GAsyncResult` + line="620">the result + version="4.10" + glib:finish-func="open_containing_folder_finish"> Launch a file manager to show the file in its parent directory. + line="642">Launches a file manager to show the file in its parent directory. -This is only supported native files. It will fail if @file -is e.g. a http:// uri. - -The @callback will be called when the operation is completed. -It should call [method@Gtk.FileLauncher.open_containing_folder_finish] -to obtain the result. - +This is only supported for native files. It will fail if @file +is e.g. a http:// uri. + @@ -58052,7 +59812,7 @@ to obtain the result. a `GtkFileLauncher` + line="644">a file launcher allow-none="1"> the parent `GtkWindow` + line="645">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="646">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="647">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="649">data to pass to @callback @@ -58102,27 +59862,26 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.FileLauncher.open_containing_folder] + line="716">Finishes the [method@Gtk.FileLauncher.open_containing_folder] call and returns the result. - + `TRUE` if an application was launched, - or `FALSE` and @error is set + line="725">true if an application was launched a `GtkFileLauncher` + line="718">a file launcher a `GAsyncResult` + line="719">the result @@ -58133,8 +59892,10 @@ call and returns the result. version="4.12"> Sets whether to awlays ask the user to choose an app for opening the file. -If `FALSE`, the file might be opened with a default app or the previous choice. + line="287">Sets whether to always ask the user which app to use. + +If false, the file might be opened with a default app +or the previous choice. @@ -58143,13 +59904,13 @@ If `FALSE`, the file might be opened with a default app or the previous choice.< a `GtkFileLauncher` + line="289">a file launcher a `gboolean` + line="290">whether to always ask @@ -58160,7 +59921,7 @@ If `FALSE`, the file might be opened with a default app or the previous choice.< version="4.10"> Sets the file that will be opened. + line="247">Sets the file that will be opened. @@ -58169,7 +59930,7 @@ If `FALSE`, the file might be opened with a default app or the previous choice.< a `GtkFileLauncher` + line="249">a file launcher a `GFile` + line="250">the file + + Sets whether to make the file writable for the handler. + + + + + + + a file launcher + + + + whether to make the file writable + + + + - - Whether to ask the user to choose an app for opening the file. If `FALSE`, + line="177">Whether to ask the user to choose an app for opening the file. If `FALSE`, the file might be opened with a default app or the previous choice. @@ -58206,15 +59989,23 @@ the file might be opened with a default app or the previous choice. transfer-ownership="none" setter="set_file" getter="get_file"> - - The file to launch. + line="165">The file to launch. + + Whether to make the file writable for the handler. + + glib:type-struct="FilterClass"> A `GtkFilter` object describes the filtering to be performed by a -[class@Gtk.FilterListModel]. + line="27">Describes the filtering to be performed by a [class@Gtk.FilterListModel]. The model will use the filter to determine if it should include items or not by calling [method@Gtk.Filter.match] for each item and only -keeping the ones that the function returns %TRUE for. +keeping the ones that the function returns true for. Filters may change what items they match through their lifetime. In that case, they will emit the [signal@Gtk.Filter::changed] signal to notify @@ -58255,27 +60045,27 @@ also possible to subclass `GtkFilter` and provide one's own filter. Gets the known strictness of @filters. + line="135">Gets the known strictness of a filter. -If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. +If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. -This function is meant purely for optimization purposes, filters can +This function is meant purely for optimization purposes. Filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self + line="149">the strictness of @self a `GtkFilter` + line="137">a filter @@ -58283,20 +60073,19 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. Checks if the given @item is matched by the filter or not. + line="116">Checks if the given @item is matched by the filter or not. %TRUE if the filter matches the item and a filter model should - keep it, %FALSE if not. + line="123">true if the filter matches the item a `GtkFilter` + line="118">a filter allow-none="1"> The item to check + line="119">The item to check @@ -58313,7 +60102,7 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. Notifies all users of the filter that it has changed. + line="159">Notifies all users of the filter that it has changed. This emits the [signal@Gtk.Filter::changed] signal. Users of the filter should then check items again via @@ -58323,7 +60112,7 @@ Depending on the @change parameter, not all items need to be changed, but only some. Refer to the [enum@Gtk.FilterChange] documentation for details. -This function is intended for implementors of `GtkFilter` +This function is intended for implementers of `GtkFilter` subclasses and should not be called from other functions. @@ -58333,13 +60122,13 @@ subclasses and should not be called from other functions. a `GtkFilter` + line="161">a filter How the filter changed + line="162">how the filter changed @@ -58347,27 +60136,27 @@ subclasses and should not be called from other functions. Gets the known strictness of @filters. + line="135">Gets the known strictness of a filter. -If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. +If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. -This function is meant purely for optimization purposes, filters can +This function is meant purely for optimization purposes. Filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self + line="149">the strictness of @self a `GtkFilter` + line="137">a filter @@ -58375,26 +60164,25 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. Checks if the given @item is matched by the filter or not. + line="116">Checks if the given @item is matched by the filter or not. %TRUE if the filter matches the item and a filter model should - keep it, %FALSE if not. + line="123">true if the filter matches the item a `GtkFilter` + line="118">a filter The item to check + line="119">The item to check @@ -58405,7 +60193,7 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. Emitted whenever the filter changed. + line="81">Emitted whenever the filter changed. Users of the filter should then check items again via [method@Gtk.Filter.match]. @@ -58422,7 +60210,7 @@ documentation for details. how the filter changed + line="84">how the filter changed @@ -58438,7 +60226,7 @@ documentation for details. using the filter to optimize refiltering items. If you are writing an implementation and are not sure which -value to pass, %GTK_FILTER_CHANGE_DIFFERENT is always a correct +value to pass, `GTK_FILTER_CHANGE_DIFFERENT` is always a correct choice. The filter change cannot be - described with any of the other enumeration values. + described with any of the other enumeration values The filter is less strict than - it was before: All items that it used to return %TRUE for - still return %TRUE, others now may, too. + it was before: All items that it used to return true + still return true, others now may, too. The filter is more strict than - it was before: All items that it used to return %FALSE for - still return %FALSE, others now may, too. + it was before: All items that it used to return false + still return false, others now may, too. %TRUE if the filter matches the item and a filter model should - keep it, %FALSE if not. + line="123">true if the filter matches the item a `GtkFilter` + line="118">a filter allow-none="1"> The item to check + line="119">The item to check @@ -58515,14 +60302,14 @@ choice. the strictness of @self + line="149">the strictness of @self a `GtkFilter` + line="137">a filter @@ -58602,10 +60389,9 @@ choice. glib:type-struct="FilterListModelClass"> `GtkFilterListModel` is a list model that filters the elements of -the underlying model according to a `GtkFilter`. + line="28">A list model that filters the elements of another model. -It hides some elements from the other model according to +It hides some elements from the underlying model according to criteria given by a `GtkFilter`. The model can be set up to do incremental filtering, so that @@ -58619,13 +60405,13 @@ filtering long lists doesn't block the UI. See Creates a new `GtkFilterListModel` that will filter @model using the given + line="750">Creates a new `GtkFilterListModel` that will filter @model using the given @filter. a new `GtkFilterListModel` + line="758">a new `GtkFilterListModel` @@ -58635,7 +60421,7 @@ filtering long lists doesn't block the UI. See allow-none="1"> the model to sort + line="752">the model to sort filter + line="753">filter @@ -58652,22 +60438,21 @@ filtering long lists doesn't block the UI. See - Gets the `GtkFilter` currently set on @self. + line="814">Gets the `GtkFilter` currently set on @self. The filter currently in use + line="820">The filter currently in use a `GtkFilterListModel` + line="816">a `GtkFilterListModel` @@ -58675,24 +60460,23 @@ filtering long lists doesn't block the UI. See - Returns whether incremental filtering is enabled. + line="961">Returns whether incremental filtering is enabled. See [method@Gtk.FilterListModel.set_incremental]. %TRUE if incremental filtering is enabled + line="969">%TRUE if incremental filtering is enabled a `GtkFilterListModel` + line="963">a `GtkFilterListModel` @@ -58700,22 +60484,21 @@ See [method@Gtk.FilterListModel.set_incremental]. - Gets the model currently filtered or %NULL if none. + line="895">Gets the model currently filtered or %NULL if none. The model that gets filtered + line="901">The model that gets filtered a `GtkFilterListModel` + line="897">a `GtkFilterListModel` @@ -58723,10 +60506,9 @@ See [method@Gtk.FilterListModel.set_incremental]. - Returns the number of items that have not been filtered yet. + line="979">Returns the number of items that have not been filtered yet. You can use this value to check if @self is busy filtering by comparing the return value to 0 or you can compute the percentage @@ -58746,14 +60528,14 @@ function returns 0. The number of items not yet filtered + line="1000">The number of items not yet filtered a `GtkFilterListModel` + line="981">a `GtkFilterListModel` @@ -58761,10 +60543,9 @@ function returns 0. - Sets the filter used to filter items. + line="781">Sets the filter used to filter items. @@ -58773,7 +60554,7 @@ function returns 0. a `GtkFilterListModel` + line="783">a `GtkFilterListModel` allow-none="1"> filter to use + line="784">filter to use @@ -58790,10 +60571,9 @@ function returns 0. - Sets the filter model to do an incremental sort. + line="911">Sets the filter model to do an incremental sort. When incremental filtering is enabled, the `GtkFilterListModel` will not run filters immediately, but will instead queue an idle handler that @@ -58817,13 +60597,13 @@ about an ongoing incremental filtering operation. a `GtkFilterListModel` + line="913">a `GtkFilterListModel` %TRUE to enable incremental filtering + line="914">%TRUE to enable incremental filtering @@ -58831,10 +60611,9 @@ about an ongoing incremental filtering operation. - Sets the model to be filtered. + line="830">Sets the model to be filtered. Note that GTK makes no effort to ensure that @model conforms to the item type of @self. It assumes that the caller knows what they @@ -58848,7 +60627,7 @@ types match. a `GtkFilterListModel` + line="832">a `GtkFilterListModel` allow-none="1"> The model to be filtered + line="833">The model to be filtered @@ -58867,13 +60646,9 @@ types match. transfer-ownership="none" setter="set_filter" getter="get_filter"> - - The filter for this model. + line="677">The filter for this model. setter="set_incremental" getter="get_incremental" default-value="FALSE"> - - If the model should filter items incrementally. + line="687">If the model should filter items incrementally. The type of items. See [method@Gio.ListModel.get_item_type]. + line="697">The type of items. See [method@Gio.ListModel.get_item_type]. transfer-ownership="none" setter="set_model" getter="get_model"> - - The model being filtered. + line="709">The model being filtered. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="719">The number of items. See [method@Gio.ListModel.get_n_items]. - Number of items not yet filtered. + line="731">Number of items not yet filtered. @@ -58949,7 +60714,7 @@ types match. line="30">Describes the known strictness of a filter. Note that for filters where the strictness is not known, -%GTK_FILTER_MATCH_SOME is always an acceptable value, +`GTK_FILTER_MATCH_SOME` is always an acceptable value, even if a filter does match all or no items. The filter matches some items, - gtk_filter_match() may return %TRUE or %FALSE + [method@Gtk.Filter.match] may return true or false The filter does not match any item, - gtk_filter_match() will always return %FALSE. + [method@Gtk.Filter.match] will always return false The filter matches all items, - gtk_filter_match() will alays return %TRUE. + [method@Gtk.Filter.match] will alays return true glib:type-struct="FixedClass"> `GtkFixed` places its child widgets at fixed positions and with fixed sizes. + line="25">Places its child widgets at fixed positions and with fixed sizes. `GtkFixed` performs no automatic layout management. @@ -59275,8 +61040,7 @@ This is a convenience function that retrieves the glib:type-struct="FixedLayoutClass"> `GtkFixedLayout` is a layout manager which can place child widgets -at fixed positions. + line="21">Places child widgets at fixed positions. Most applications should never use this layout manager; fixed positioning and sizing requires constant recalculations on where children need to be @@ -59310,12 +61074,12 @@ long-term maintenance problem for your application. Creates a new `GtkFixedLayout`. + line="355">Creates a new `GtkFixedLayout`. the newly created `GtkFixedLayout` + line="360">the newly created `GtkFixedLayout` @@ -59329,26 +61093,26 @@ long-term maintenance problem for your application. glib:type-struct="FixedLayoutChildClass"> `GtkLayoutChild` subclass for children in a `GtkFixedLayout`. + line="56">`GtkLayoutChild` subclass for children in a `GtkFixedLayout`. Retrieves the transformation of the child. + line="198">Retrieves the transformation of the child. a `GskTransform` + line="204">a `GskTransform` a `GtkFixedLayoutChild` + line="200">a `GtkFixedLayoutChild` @@ -59356,10 +61120,9 @@ long-term maintenance problem for your application. - Sets the transformation of the child of a `GtkFixedLayout`. + line="174">Sets the transformation of the child of a `GtkFixedLayout`. @@ -59368,13 +61131,13 @@ long-term maintenance problem for your application. a `GtkFixedLayoutChild` + line="176">a `GtkFixedLayoutChild` a `GskTransform` + line="177">a `GskTransform` @@ -59384,13 +61147,9 @@ long-term maintenance problem for your application. transfer-ownership="none" setter="set_transform" getter="get_transform"> - - The transform of the child. + line="154">The transform of the child. @@ -59419,7 +61178,7 @@ long-term maintenance problem for your application. glib:type-struct="FlattenListModelClass"> `GtkFlattenListModel` is a list model that concatenates other list models. + line="27">A list model that concatenates other list models. `GtkFlattenListModel` takes a list model containing list models, and flattens it into a single model. Each list model becomes a section in the single model. @@ -59452,7 +61211,6 @@ it into a single model. Each list model becomes a section in the single model. - Gets the model set via gtk_flatten_list_model_set_model(). @@ -59502,7 +61260,6 @@ it into a single model. Each list model becomes a section in the single model. - Sets a new model to be flattened. @@ -59539,10 +61296,6 @@ it into a single model. Each list model becomes a section in the single model. - - The model being flattened. @@ -59574,7 +61327,12 @@ it into a single model. Each list model becomes a section in the single model. A `GtkFlowBox` puts child widgets in reflowing grid. + line="26">Puts child widgets in a reflowing grid. + +<picture> + <source srcset="flow-box-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkFlowBox" src="flow-box.png"> +</picture> For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous @@ -59600,6 +61358,15 @@ and the widget. Also see [class@Gtk.ListBox]. +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.FlowBox::move-cursor] +- [signal@Gtk.FlowBox::select-all] +- [signal@Gtk.FlowBox::toggle-cursor-child] +- [signal@Gtk.FlowBox::unselect-all] + # CSS nodes ``` @@ -59618,8 +61385,8 @@ a subnode with name rubberband is used. # Accessibility -`GtkFlowBox` uses the %GTK_ACCESSIBLE_ROLE_GRID role, and `GtkFlowBoxChild` -uses the %GTK_ACCESSIBLE_ROLE_GRID_CELL role. +`GtkFlowBox` uses the [enum@Gtk.AccessibleRole.grid] role, and `GtkFlowBoxChild` +uses the [enum@Gtk.AccessibleRole.grid_cell] role. @@ -59627,19 +61394,19 @@ uses the %GTK_ACCESSIBLE_ROLE_GRID_CELL role. Creates a `GtkFlowBox`. + line="4122">Creates a `GtkFlowBox`. a new `GtkFlowBox` + line="4127">a new `GtkFlowBox` Adds @child to the end of @self. + line="4177">Adds @child to the end of @self. If a sort function is set, the widget will actually be inserted at the calculated position. @@ -59653,13 +61420,13 @@ See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox + line="4179">a `GtkFlowBox the `GtkWidget` to add + line="4180">the `GtkWidget` to add @@ -59667,7 +61434,7 @@ See also: [method@Gtk.FlowBox.insert]. Binds @model to @box. + line="4389">Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. @@ -59690,7 +61457,7 @@ should be implemented by the model. a `GtkFlowBox` + line="4391">a `GtkFlowBox` allow-none="1"> the `GListModel` to be bound to @box + line="4392">the `GListModel` to be bound to @box destroy="3"> a function that creates widgets for items + line="4393">a function + that creates widgets for items @@ -59719,7 +61487,7 @@ should be implemented by the model. allow-none="1"> user data passed to @create_widget_func + line="4395">user data passed to @create_widget_func scope="async"> function for freeing @user_data + line="4396">function for freeing @user_data @@ -59735,16 +61503,14 @@ should be implemented by the model. - Returns whether children activate on single clicks. + line="4680">Returns whether children activate on single clicks. %TRUE if children are activated on single click, + line="4686">%TRUE if children are activated on single click, %FALSE otherwise @@ -59752,7 +61518,7 @@ should be implemented by the model. a `GtkFlowBox` + line="4682">a `GtkFlowBox` @@ -59761,12 +61527,12 @@ should be implemented by the model. c:identifier="gtk_flow_box_get_child_at_index"> Gets the nth child in the @box. + line="4256">Gets the nth child in the @box. the child widget, which will + line="4263">the child widget, which will always be a `GtkFlowBoxChild` or %NULL in case no child widget with the given index exists. @@ -59775,13 +61541,13 @@ should be implemented by the model. a `GtkFlowBox` + line="4258">a `GtkFlowBox` the position of the child + line="4259">the position of the child @@ -59790,14 +61556,14 @@ should be implemented by the model. c:identifier="gtk_flow_box_get_child_at_pos"> Gets the child in the (@x, @y) position. + line="4282">Gets the child in the (@x, @y) position. Both @x and @y are assumed to be relative to the origin of @box. the child widget, which will + line="4292">the child widget, which will always be a `GtkFlowBoxChild` or %NULL in case no child widget exists for the given x and y coordinates. @@ -59806,19 +61572,19 @@ Both @x and @y are assumed to be relative to the origin of @box. a `GtkFlowBox` + line="4284">a `GtkFlowBox` the x coordinate of the child + line="4285">the x coordinate of the child the y coordinate of the child + line="4286">the y coordinate of the child @@ -59826,22 +61592,21 @@ Both @x and @y are assumed to be relative to the origin of @box. - Gets the horizontal spacing. + line="4558">Gets the horizontal spacing. the horizontal spacing + line="4564">the horizontal spacing a `GtkFlowBox` + line="4560">a `GtkFlowBox` @@ -59849,22 +61614,21 @@ Both @x and @y are assumed to be relative to the origin of @box. - Returns whether the box is homogeneous. + line="4456">Returns whether the box is homogeneous. %TRUE if the box is homogeneous. + line="4462">%TRUE if the box is homogeneous. a `GtkFlowBox` + line="4458">a `GtkFlowBox` @@ -59872,23 +61636,21 @@ Both @x and @y are assumed to be relative to the origin of @box. - Gets the maximum number of children per line. + line="4641">Gets the maximum number of children per line. the maximum number of children per line + line="4647">the maximum number of children per line a `GtkFlowBox` + line="4643">a `GtkFlowBox` @@ -59896,23 +61658,21 @@ Both @x and @y are assumed to be relative to the origin of @box. - Gets the minimum number of children per line. + line="4597">Gets the minimum number of children per line. the minimum number of children per line + line="4603">the minimum number of children per line a `GtkFlowBox` + line="4599">a `GtkFlowBox` @@ -59920,22 +61680,21 @@ Both @x and @y are assumed to be relative to the origin of @box. - Gets the vertical spacing. + line="4520">Gets the vertical spacing. the vertical spacing + line="4526">the vertical spacing a `GtkFlowBox` + line="4522">a `GtkFlowBox` @@ -59944,12 +61703,12 @@ Both @x and @y are assumed to be relative to the origin of @box. c:identifier="gtk_flow_box_get_selected_children"> Creates a list of all selected children. + line="4710">Creates a list of all selected children. + line="4716"> A `GList` containing the `GtkWidget` for each selected child. Free with g_list_free() when done. @@ -59960,7 +61719,7 @@ Both @x and @y are assumed to be relative to the origin of @box. a `GtkFlowBox` + line="4712">a `GtkFlowBox` @@ -59968,22 +61727,21 @@ Both @x and @y are assumed to be relative to the origin of @box. - Gets the selection mode of @box. + line="4901">Gets the selection mode of @box. the `GtkSelectionMode` + line="4907">the `GtkSelectionMode` a `GtkFlowBox` + line="4903">a `GtkFlowBox` @@ -59991,7 +61749,7 @@ Both @x and @y are assumed to be relative to the origin of @box. Inserts the @widget into @box at @position. + line="4201">Inserts the @widget into @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position. @@ -60006,19 +61764,19 @@ in the @box, then the @widget will be appended to the end. a `GtkFlowBox` + line="4203">a `GtkFlowBox` the `GtkWidget` to add + line="4204">the `GtkWidget` to add the position to insert @child in + line="4205">the position to insert @child in @@ -60027,7 +61785,7 @@ in the @box, then the @widget will be appended to the end. c:identifier="gtk_flow_box_invalidate_filter"> Updates the filtering for all children. + line="4978">Updates the filtering for all children. Call this function when the result of the filter function on the @box is changed due to an external @@ -60042,7 +61800,7 @@ term, and the entry with the string has changed. a `GtkFlowBox` + line="4980">a `GtkFlowBox` @@ -60051,7 +61809,7 @@ term, and the entry with the string has changed. c:identifier="gtk_flow_box_invalidate_sort"> Updates the sorting for all children. + line="5080">Updates the sorting for all children. Call this when the result of the sort function on @box is changed due to an external factor. @@ -60063,7 +61821,7 @@ Call this when the result of the sort function on a `GtkFlowBox` + line="5082">a `GtkFlowBox` @@ -60071,7 +61829,7 @@ Call this when the result of the sort function on Adds @child to the start of @self. + line="4153">Adds @child to the start of @self. If a sort function is set, the widget will actually be inserted at the calculated position. @@ -60085,13 +61843,13 @@ See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox + line="4155">a `GtkFlowBox the `GtkWidget` to add + line="4156">the `GtkWidget` to add @@ -60099,7 +61857,7 @@ See also: [method@Gtk.FlowBox.insert]. Removes a child from @box. + line="3099">Removes a child from @box. @@ -60108,13 +61866,13 @@ See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox` + line="3101">a `GtkFlowBox` the child widget to remove + line="3102">the child widget to remove @@ -60124,7 +61882,7 @@ See also: [method@Gtk.FlowBox.insert]. version="4.12"> Removes all children from @box. + line="3150">Removes all children from @box. This function does nothing if @box is backed by a model. @@ -60135,7 +61893,7 @@ This function does nothing if @box is backed by a model. a `GtkFlowBox` + line="3152">a `GtkFlowBox` @@ -60143,7 +61901,7 @@ This function does nothing if @box is backed by a model. Select all children of @box, if the selection + line="4777">Select all children of @box, if the selection mode allows it. @@ -60153,7 +61911,7 @@ mode allows it. a `GtkFlowBox` + line="4779">a `GtkFlowBox` @@ -60161,7 +61919,7 @@ mode allows it. Selects a single child of @box, if the selection + line="4741">Selects a single child of @box, if the selection mode allows it. @@ -60171,13 +61929,13 @@ mode allows it. a `GtkFlowBox` + line="4743">a `GtkFlowBox` a child of @box + line="4744">a child of @box @@ -60186,7 +61944,7 @@ mode allows it. c:identifier="gtk_flow_box_selected_foreach"> Calls a function for each selected child. + line="4833">Calls a function for each selected child. Note that the selection cannot be modified from within this function. @@ -60198,7 +61956,7 @@ this function. a `GtkFlowBox` + line="4835">a `GtkFlowBox` closure="1"> the function to call for each selected child + line="4836">the function to call for each selected child allow-none="1"> user data to pass to the function + line="4837">user data to pass to the function @@ -60224,11 +61982,9 @@ this function. - If @single is %TRUE, children will be activated when you click + line="4657">If @single is %TRUE, children will be activated when you click on them, otherwise you need to double-click. @@ -60238,13 +61994,13 @@ on them, otherwise you need to double-click. a `GtkFlowBox` + line="4659">a `GtkFlowBox` %TRUE to emit child-activated on a single click + line="4660">%TRUE to emit child-activated on a single click @@ -60252,10 +62008,9 @@ on them, otherwise you need to double-click. - Sets the horizontal space to add between children. + line="4536">Sets the horizontal space to add between children. @@ -60264,13 +62019,13 @@ on them, otherwise you need to double-click. a `GtkFlowBox` + line="4538">a `GtkFlowBox` the spacing to use + line="4539">the spacing to use @@ -60279,7 +62034,7 @@ on them, otherwise you need to double-click. c:identifier="gtk_flow_box_set_filter_func"> By setting a filter function on the @box one can decide dynamically + line="4932">By setting a filter function on the @box one can decide dynamically which of the children to show. For instance, to implement a search function that only shows the @@ -60300,7 +62055,7 @@ Note that using a filter function is incompatible with using a model a `GtkFlowBox` + line="4934">a `GtkFlowBox` callback that - lets you filter which children to show + line="4935">callback + that lets you filter which children to show user data passed to @filter_func + line="4937">user data passed to @filter_func destroy notifier for @user_data + line="4938">destroy notifier for @user_data @@ -60337,7 +62092,7 @@ Note that using a filter function is incompatible with using a model c:identifier="gtk_flow_box_set_hadjustment"> Hooks up an adjustment to focus handling in @box. + line="4309">Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See [method@Gtk.ScrolledWindow.get_hadjustment] @@ -60356,13 +62111,13 @@ of the box. a `GtkFlowBox` + line="4311">a `GtkFlowBox` an adjustment which should be adjusted + line="4312">an adjustment which should be adjusted when the focus is moved among the descendents of @container @@ -60371,10 +62126,9 @@ of the box. - Sets whether or not all children of @box are given + line="4472">Sets whether or not all children of @box are given equal space in the box. @@ -60384,13 +62138,13 @@ equal space in the box. a `GtkFlowBox` + line="4474">a `GtkFlowBox` %TRUE to create equal allotments, + line="4475">%TRUE to create equal allotments, %FALSE for variable allotments @@ -60399,11 +62153,9 @@ equal space in the box. - Sets the maximum number of children to request and + line="4613">Sets the maximum number of children to request and allocate space for in @box’s orientation. Setting the maximum number of children per line @@ -60417,13 +62169,13 @@ than @n_children children long in the given orientation. a `GtkFlowBox` + line="4615">a `GtkFlowBox` the maximum number of children per line + line="4616">the maximum number of children per line @@ -60431,11 +62183,9 @@ than @n_children children long in the given orientation. - Sets the minimum number of children to line up + line="4574">Sets the minimum number of children to line up in @box’s orientation before flowing. @@ -60445,13 +62195,13 @@ in @box’s orientation before flowing. a `GtkFlowBox` + line="4576">a `GtkFlowBox` the minimum number of children per line + line="4577">the minimum number of children per line @@ -60459,10 +62209,9 @@ in @box’s orientation before flowing. - Sets the vertical space to add between children. + line="4498">Sets the vertical space to add between children. @@ -60471,13 +62220,13 @@ in @box’s orientation before flowing. a `GtkFlowBox` + line="4500">a `GtkFlowBox` the spacing to use + line="4501">the spacing to use @@ -60485,10 +62234,9 @@ in @box’s orientation before flowing. - Sets how selection works in @box. + line="4864">Sets how selection works in @box. @@ -60497,13 +62245,13 @@ in @box’s orientation before flowing. a `GtkFlowBox` + line="4866">a `GtkFlowBox` the new selection mode + line="4867">the new selection mode @@ -60511,7 +62259,7 @@ in @box’s orientation before flowing. By setting a sort function on the @box, one can dynamically + line="5014">By setting a sort function on the @box, one can dynamically reorder the children of the box, based on the contents of the children. @@ -60530,7 +62278,7 @@ Note that using a sort function is incompatible with using a model a `GtkFlowBox` + line="5016">a `GtkFlowBox` the sort function + line="5017">the sort function user data passed to @sort_func + line="5018">user data passed to @sort_func destroy notifier for @user_data + line="5019">destroy notifier for @user_data @@ -60566,7 +62314,7 @@ Note that using a sort function is incompatible with using a model c:identifier="gtk_flow_box_set_vadjustment"> Hooks up an adjustment to focus handling in @box. + line="4344">Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See [method@Gtk.ScrolledWindow.get_vadjustment] @@ -60585,13 +62333,13 @@ of the box. a `GtkFlowBox` + line="4346">a `GtkFlowBox` an adjustment which should be adjusted + line="4347">an adjustment which should be adjusted when the focus is moved among the descendents of @container @@ -60600,7 +62348,7 @@ of the box. Unselect all children of @box, if the selection + line="4799">Unselect all children of @box, if the selection mode allows it. @@ -60610,7 +62358,7 @@ mode allows it. a `GtkFlowBox` + line="4801">a `GtkFlowBox` @@ -60618,7 +62366,7 @@ mode allows it. Unselects a single child of @box, if the selection + line="4759">Unselects a single child of @box, if the selection mode allows it. @@ -60628,13 +62376,13 @@ mode allows it. a `GtkFlowBox` + line="4761">a `GtkFlowBox` a child of @box + line="4762">a child of @box @@ -60643,6 +62391,9 @@ mode allows it. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether to accept unpaired release events. setter="set_activate_on_single_click" getter="get_activate_on_single_click" default-value="TRUE"> - - Determines whether children can be activated with a single + line="3712">Determines whether children can be activated with a single click, or require a double-click. @@ -60667,13 +62414,9 @@ click, or require a double-click. setter="set_column_spacing" getter="get_column_spacing" default-value="0"> - - The amount of horizontal space between two children. + line="3780">The amount of horizontal space between two children. setter="set_homogeneous" getter="get_homogeneous" default-value="FALSE"> - - Determines whether all children should be allocated the + line="3733">Determines whether all children should be allocated the same size. @@ -60698,13 +62437,9 @@ same size. setter="set_max_children_per_line" getter="get_max_children_per_line" default-value="7"> - - The maximum amount of children to request space for consecutively + line="3759">The maximum amount of children to request space for consecutively in the given orientation. @@ -60714,13 +62449,9 @@ in the given orientation. setter="set_min_children_per_line" getter="get_min_children_per_line" default-value="0"> - - The minimum number of children to allocate consecutively + line="3744">The minimum number of children to allocate consecutively in the given orientation. Setting the minimum children per line ensures @@ -60734,13 +62465,9 @@ for the overall minimum width of the box. setter="set_row_spacing" getter="get_row_spacing" default-value="0"> - - The amount of vertical space between two children. + line="3770">The amount of vertical space between two children. setter="set_selection_mode" getter="get_selection_mode" default-value="GTK_SELECTION_SINGLE"> - - The selection mode used by the flow box. + line="3701">The selection mode used by the flow box. Emitted when the user activates the @box. + line="3826">Emitted when the user activates the @box. This is a [keybinding signal](class.SignalAction.html). @@ -60771,7 +62494,7 @@ This is a [keybinding signal](class.SignalAction.html). Emitted when a child has been activated by the user. + line="3792">Emitted when a child has been activated by the user. @@ -60779,7 +62502,7 @@ This is a [keybinding signal](class.SignalAction.html). the child that is activated + line="3795">the child that is activated @@ -60787,7 +62510,7 @@ This is a [keybinding signal](class.SignalAction.html). Emitted when the user initiates a cursor movement. + line="3860">Emitted when the user initiates a cursor movement. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with @@ -60806,33 +62529,33 @@ There are too many key combinations to list them all here. %TRUE to stop other handlers from being invoked for the event. -%FALSE to propagate the event further. + line="3885">%TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. the granularity of the move, as a `GtkMovementStep` + line="3863">the granularity of the move, as a `GtkMovementStep` the number of @step units to move + line="3864">the number of @step units to move whether to extend the selection + line="3865">whether to extend the selection whether to modify the selection + line="3866">whether to modify the selection @@ -60840,7 +62563,7 @@ There are too many key combinations to list them all here. Emitted to select all children of the box, + line="3899">Emitted to select all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). @@ -60853,7 +62576,7 @@ The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>a Emitted when the set of selected children changes. + line="3808">Emitted when the set of selected children changes. Use [method@Gtk.FlowBox.selected_foreach] or [method@Gtk.FlowBox.get_selected_children] to obtain the @@ -60865,7 +62588,7 @@ selected children. Emitted to toggle the selection of the child that has the focus. + line="3842">Emitted to toggle the selection of the child that has the focus. This is a [keybinding signal](class.SignalAction.html). @@ -60877,7 +62600,7 @@ The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>Sp Emitted to unselect all children of the box, + line="3918">Emitted to unselect all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). @@ -60897,7 +62620,10 @@ The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>S glib:type-struct="FlowBoxChildClass"> `GtkFlowBoxChild` is the kind of widget that can be added to a `GtkFlowBox`. + line="91">The kind of widget that can be added to a `GtkFlowBox`. + +[class@Gtk.FlowBox] will automatically wrap its children in a `GtkFlowBoxChild` +when necessary. @@ -60905,14 +62631,14 @@ The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>S Creates a new `GtkFlowBoxChild`. + line="582">Creates a new `GtkFlowBoxChild`. This should only be used as a child of a `GtkFlowBox`. a new `GtkFlowBoxChild` + line="589">a new `GtkFlowBoxChild` @@ -60930,7 +62656,7 @@ This should only be used as a child of a `GtkFlowBox`. Marks @child as changed, causing any state that depends on this + line="681">Marks @child as changed, causing any state that depends on this to be updated. This affects sorting and filtering. @@ -60957,7 +62683,7 @@ on any model change, but that is more expensive. a `GtkFlowBoxChild` + line="683">a `GtkFlowBoxChild` @@ -60965,22 +62691,21 @@ on any model change, but that is more expensive. - Gets the child widget of @self. + line="624">Gets the child widget of @self. the child widget of @self + line="630">the child widget of @self a `GtkFlowBoxChild` + line="626">a `GtkFlowBoxChild` @@ -60988,12 +62713,12 @@ on any model change, but that is more expensive. Gets the current index of the @child in its `GtkFlowBox` container. + line="640">Gets the current index of the @child in its `GtkFlowBox` container. the index of the @child, or -1 if the @child is not + line="646">the index of the @child, or -1 if the @child is not in a flow box @@ -61001,7 +62726,7 @@ on any model change, but that is more expensive. a `GtkFlowBoxChild` + line="642">a `GtkFlowBoxChild` @@ -61009,20 +62734,20 @@ on any model change, but that is more expensive. Returns whether the @child is currently selected in its + line="664">Returns whether the @child is currently selected in its `GtkFlowBox` container. %TRUE if @child is selected + line="671">%TRUE if @child is selected a `GtkFlowBoxChild` + line="666">a `GtkFlowBoxChild` @@ -61030,10 +62755,9 @@ on any model change, but that is more expensive. - Sets the child widget of @self. + line="597">Sets the child widget of @self. @@ -61042,7 +62766,7 @@ on any model change, but that is more expensive. a `GtkFlowBoxChild` + line="599">a `GtkFlowBoxChild` allow-none="1"> the child widget + line="600">the child widget @@ -61061,13 +62785,9 @@ on any model change, but that is more expensive. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="534">The child widget. @@ -61076,7 +62796,7 @@ on any model change, but that is more expensive. Emitted when the user activates a child widget in a `GtkFlowBox`. + line="545">Emitted when the user activates a child widget in a `GtkFlowBox`. This can happen either by clicking or double-clicking, or via a keybinding. @@ -61152,7 +62872,7 @@ This function is called for each item that gets added to the model. A function that will be called whenever a child changes + line="4919">A function that will be called whenever a child changes or is added. It lets you control if the child should be visible or not. @@ -61160,14 +62880,14 @@ It lets you control if the child should be visible or not. %TRUE if the row should be visible, %FALSE otherwise + line="4929">%TRUE if the row should be visible, %FALSE otherwise a `GtkFlowBoxChild` that may be filtered + line="4921">a `GtkFlowBoxChild` that may be filtered closure="1"> user data + line="4922">user data @@ -61185,7 +62905,7 @@ It lets you control if the child should be visible or not. A function used by gtk_flow_box_selected_foreach(). + line="4822">A function used by gtk_flow_box_selected_foreach(). It will be called on every selected child of the @box. @@ -61196,13 +62916,13 @@ It will be called on every selected child of the @box. a `GtkFlowBox` + line="4824">a `GtkFlowBox` a `GtkFlowBoxChild` + line="4825">a `GtkFlowBoxChild` closure="2"> user data + line="4826">user data @@ -61220,13 +62940,13 @@ It will be called on every selected child of the @box. A function to compare two children to determine which + line="5001">A function to compare two children to determine which should come first. < 0 if @child1 should be before @child2, 0 if + line="5010">< 0 if @child1 should be before @child2, 0 if they are equal, and > 0 otherwise @@ -61234,13 +62954,13 @@ should come first. the first child + line="5003">the first child the second child + line="5004">the second child closure="2"> user data + line="5005">user data @@ -61268,7 +62988,10 @@ should come first. line="50">The `GtkFontButton` allows to open a font chooser dialog to change the font. -![An example GtkFontButton](font-button.png) +<picture> + <source srcset="font-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkFontButton" src="font-button.png"> +</picture> It is suitable widget for selecting a font in a preference dialog. @@ -61293,13 +63016,13 @@ contains a button node with the .font style class. deprecated-version="4.10"> Creates a new font picker widget. + line="751">Creates a new font picker widget. Use [class@Gtk.FontDialogButton] instead a new font picker widget. + line="756">a new font picker widget. @@ -61309,20 +63032,20 @@ contains a button node with the .font style class. deprecated-version="4.10"> Creates a new font picker widget showing the given font. + line="766">Creates a new font picker widget showing the given font. Use [class@Gtk.FontDialogButton] instead a new font picker widget. + line="772">a new font picker widget. Name of font to display in font chooser dialog + line="768">Name of font to display in font chooser dialog @@ -61332,23 +63055,22 @@ contains a button node with the .font style class. glib:get-property="modal" deprecated="1" deprecated-version="4.10"> - Gets whether the dialog is modal. + line="853">Gets whether the dialog is modal. Use [class@Gtk.FontDialogButton] instead %TRUE if the dialog is modal + line="859">%TRUE if the dialog is modal a `GtkFontButton` + line="855">a `GtkFontButton` @@ -61358,16 +63080,15 @@ contains a button node with the .font style class. glib:get-property="title" deprecated="1" deprecated-version="4.10"> - Retrieves the title of the font chooser dialog. + line="808">Retrieves the title of the font chooser dialog. Use [class@Gtk.FontDialogButton] instead an internal copy of the title string + line="814">an internal copy of the title string which must not be freed. @@ -61375,7 +63096,7 @@ contains a button node with the .font style class. a `GtkFontButton` + line="810">a `GtkFontButton` @@ -61385,23 +63106,22 @@ contains a button node with the .font style class. glib:get-property="use-font" deprecated="1" deprecated-version="4.10"> - Returns whether the selected font is used in the label. + line="871">Returns whether the selected font is used in the label. Use [class@Gtk.FontDialogButton] instead whether the selected font is used in the label. + line="877">whether the selected font is used in the label. a `GtkFontButton` + line="873">a `GtkFontButton` @@ -61411,23 +63131,22 @@ contains a button node with the .font style class. glib:get-property="use-size" deprecated="1" deprecated-version="4.10"> - Returns whether the selected size is used in the label. + line="918">Returns whether the selected size is used in the label. Use [class@Gtk.FontDialogButton] instead whether the selected size is used in the label. + line="924">whether the selected size is used in the label. a `GtkFontButton` + line="920">a `GtkFontButton` @@ -61437,10 +63156,9 @@ contains a button node with the .font style class. glib:set-property="modal" deprecated="1" deprecated-version="4.10"> - Sets whether the dialog should be modal. + line="827">Sets whether the dialog should be modal. Use [class@Gtk.FontDialogButton] instead @@ -61450,13 +63168,13 @@ contains a button node with the .font style class. a `GtkFontButton` + line="829">a `GtkFontButton` %TRUE to make the dialog modal + line="830">%TRUE to make the dialog modal @@ -61466,10 +63184,9 @@ contains a button node with the .font style class. glib:set-property="title" deprecated="1" deprecated-version="4.10"> - Sets the title for the font chooser dialog. + line="782">Sets the title for the font chooser dialog. Use [class@Gtk.FontDialogButton] instead @@ -61479,13 +63196,13 @@ contains a button node with the .font style class. a `GtkFontButton` + line="784">a `GtkFontButton` a string containing the font chooser dialog title + line="785">a string containing the font chooser dialog title @@ -61495,10 +63212,9 @@ contains a button node with the .font style class. glib:set-property="use-font" deprecated="1" deprecated-version="4.10"> - If @use_font is %TRUE, the font name will be written + line="889">If @use_font is %TRUE, the font name will be written using the selected font. Use [class@Gtk.FontDialogButton] instead @@ -61509,13 +63225,13 @@ using the selected font. a `GtkFontButton` + line="891">a `GtkFontButton` If %TRUE, font name will be written using font chosen. + line="892">If %TRUE, font name will be written using font chosen. @@ -61525,10 +63241,9 @@ using the selected font. glib:set-property="use-size" deprecated="1" deprecated-version="4.10"> - If @use_size is %TRUE, the font name will be written using + line="936">If @use_size is %TRUE, the font name will be written using the selected size. Use [class@Gtk.FontDialogButton] instead @@ -61539,13 +63254,13 @@ the selected size. a `GtkFontButton` + line="938">a `GtkFontButton` If %TRUE, font name will be written using the + line="939">If %TRUE, font name will be written using the selected size. @@ -61557,13 +63272,9 @@ the selected size. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the font chooser dialog should be modal. + line="535">Whether the font chooser dialog should be modal. setter="set_title" getter="get_title" default-value="Pick a Font"> - - The title of the font chooser dialog. + line="502">The title of the font chooser dialog. setter="set_use_font" getter="get_use_font" default-value="FALSE"> - - Whether the buttons label will be drawn in the selected font. + line="513">Whether the buttons label will be drawn in the selected font. setter="set_use_size" getter="get_use_size" default-value="FALSE"> - - Whether the buttons label will use the selected font size. + line="524">Whether the buttons label will use the selected font size. Emitted to when the font button is activated. + line="567">Emitted to when the font button is activated. The `::activate` signal on `GtkFontButton` is an action signal and emitting it causes the button to present its dialog. @@ -61625,7 +63324,7 @@ emitting it causes the button to present its dialog. Emitted when the user selects a font. + line="546">Emitted when the user selects a font. When handling this signal, use [method@Gtk.FontChooser.get_font] to find out which font was just selected. @@ -61893,7 +63592,6 @@ instead glib:get-property="font" deprecated="1" deprecated-version="4.10"> - Gets the currently-selected font name. @@ -61931,7 +63629,6 @@ instead glib:get-property="font-desc" deprecated="1" deprecated-version="4.10"> - Gets the currently-selected font. @@ -62030,7 +63727,6 @@ instead glib:get-property="font-features" deprecated="1" deprecated-version="4.10"> - Gets the currently-selected font features. @@ -62116,7 +63812,6 @@ instead glib:get-property="language" deprecated="1" deprecated-version="4.10"> - Gets the language that is used for font features. @@ -62144,7 +63839,6 @@ instead glib:get-property="level" deprecated="1" deprecated-version="4.10"> - Returns the current level of granularity for selecting fonts. @@ -62172,7 +63866,6 @@ instead glib:get-property="preview-text" deprecated="1" deprecated-version="4.10"> - Gets the text displayed in the preview area. @@ -62200,8 +63893,6 @@ instead glib:get-property="show-preview-entry" deprecated="1" deprecated-version="4.10"> - Returns whether the preview entry is shown or not. @@ -62280,7 +63971,6 @@ instead glib:set-property="font" deprecated="1" deprecated-version="4.10"> - Sets the currently-selected font. @@ -62311,7 +64001,6 @@ instead glib:set-property="font-desc" deprecated="1" deprecated-version="4.10"> - Sets the currently-selected font from @font_desc. @@ -62399,7 +64088,6 @@ instead glib:set-property="language" deprecated="1" deprecated-version="4.10"> - Sets the language to use for font features. @@ -62430,7 +64118,6 @@ instead glib:set-property="level" deprecated="1" deprecated-version="4.10"> - Sets the desired level of granularity for selecting fonts. @@ -62461,7 +64148,6 @@ instead glib:set-property="preview-text" deprecated="1" deprecated-version="4.10"> - Sets the text displayed in the preview area. @@ -62494,8 +64180,6 @@ instead glib:set-property="show-preview-entry" deprecated="1" deprecated-version="4.10"> - Shows or hides the editable preview entry. @@ -62529,10 +64213,6 @@ instead setter="set_font" getter="get_font" default-value="Sans 10"> - - The font description as a string, e.g. "Sans Italic 12". @@ -62546,10 +64226,6 @@ instead transfer-ownership="none" setter="set_font_desc" getter="get_font_desc"> - - The font description as a `PangoFontDescription`. @@ -62561,8 +64237,6 @@ instead deprecated-version="4.10" transfer-ownership="none" getter="get_font_features"> - The selected font features. @@ -62579,10 +64253,6 @@ CSS and with Pango attributes. transfer-ownership="none" setter="set_language" getter="get_language"> - - The language for which the font features were selected. @@ -62597,10 +64267,6 @@ CSS and with Pango attributes. setter="set_level" getter="get_level" default-value="GTK_FONT_CHOOSER_LEVEL_STYLE | GTK_FONT_CHOOSER_LEVEL_SIZE"> - - The level of granularity to offer for selecting fonts. @@ -62615,10 +64281,6 @@ CSS and with Pango attributes. setter="set_preview_text" getter="get_preview_text" default-value="The quick brown fox jumps over the lazy dog."> - - The string with which to preview the font. @@ -62633,10 +64295,6 @@ CSS and with Pango attributes. setter="set_show_preview_entry" getter="get_show_preview_entry" default-value="TRUE"> - - Whether to show an entry to change the preview text. @@ -62680,7 +64338,10 @@ Space, Shift+Space, Return or Enter. filename="gtk/gtkfontchooserdialog.c" line="60">The `GtkFontChooserDialog` widget is a dialog for selecting a font. -![An example GtkFontChooserDialog](fontchooser.png) +<picture> + <source srcset="fontchooser-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkFontChooserDialog" src="fontchooser.png"> +</picture> `GtkFontChooserDialog` implements the [iface@Gtk.FontChooser] interface and does not provide much API of its own. @@ -62711,14 +64372,14 @@ class `.fontchooser`. deprecated-version="4.10"> Creates a new `GtkFontChooserDialog`. + line="298">Creates a new `GtkFontChooserDialog`. Use [class@Gtk.FontDialog] instead a new `GtkFontChooserDialog` + line="305">a new `GtkFontChooserDialog` @@ -62728,7 +64389,7 @@ class `.fontchooser`. allow-none="1"> Title of the dialog + line="300">Title of the dialog allow-none="1"> Transient parent of the dialog + line="301">Transient parent of the dialog @@ -62994,7 +64655,7 @@ ignore unknown values. glib:get-type="gtk_font_chooser_widget_get_type"> The `GtkFontChooserWidget` widget lets the user select a font. + line="76">The `GtkFontChooserWidget` widget lets the user select a font. It is used in the `GtkFontChooserDialog` widget to provide a dialog for selecting fonts. @@ -63022,21 +64683,21 @@ To change the text which is shown in the preview area, use deprecated-version="4.10"> Creates a new `GtkFontChooserWidget`. + line="1245">Creates a new `GtkFontChooserWidget`. Direct use of `GtkFontChooserWidget` is deprecated. a new `GtkFontChooserWidget` + line="1250">a new `GtkFontChooserWidget` A toggle action that can be used to switch to the tweak page + line="851">A toggle action that can be used to switch to the tweak page of the font chooser widget, which lets the user tweak the OpenType features and variation axes of the selected font. @@ -63055,15 +64716,14 @@ the selected font has any features or axes. glib:type-struct="FontDialogClass"> A `GtkFontDialog` object collects the arguments that -are needed to present a font chooser dialog to the -user, such as a title for the dialog and whether it -should be modal. + line="31">Asynchronous API to present a font chooser dialog. + +`GtkFontDialog` collects the arguments that are needed to present +the dialog to the user, such as a title for the dialog and whether +it should be modal. The dialog is shown with the [method@Gtk.FontDialog.choose_font] -function or its variants. This API follows the GIO async pattern, -and the result can be obtained by calling the corresponding -finish function, such as [method@Gtk.FontDialog.choose_font_finish]. +function or its variants. See [class@Gtk.FontDialogButton] for a convenient control that uses `GtkFontDialog` and presents the results. @@ -63073,27 +64733,26 @@ that uses `GtkFontDialog` and presents the results. version="4.10"> Creates a new `GtkFontDialog` object. + line="249">Creates a new `GtkFontDialog` object. the new `GtkFontDialog` + line="254">the new `GtkFontDialog` + version="4.10" + glib:finish-func="choose_face_finish"> This function initiates a font selection operation by -presenting a dialog to the user for selecting a font face -(i.e. a font family and style, but not a specific font size). + line="697">Presents a font chooser dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_face_finish] -to obtain the result. +The font chooser dialog will be set up for selecting a font face. + +A font face represents a font family and style, but no specific font size. @@ -63102,7 +64761,7 @@ to obtain the result. a `GtkFontDialog` + line="699">a font dialog allow-none="1"> the parent `GtkWindow` + line="700">the parent window allow-none="1"> the initial value + line="701">the initial value allow-none="1"> a `GCancellable` to cancel the operation + line="702">a cancellable to cancel the operation closure="4"> a callback to call when the operation is complete + line="703">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="705">data to pass to @callback @@ -63161,41 +64820,38 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.FontDialog.choose_face] call -and returns the resulting font face. + line="751">Finishes the [method@Gtk.FontDialog.choose_face] call. the selected font face + line="759">the selected font face a `GtkFontDialog` + line="753">a font dialog a `GAsyncResult` + line="754">the result + version="4.10" + glib:finish-func="choose_family_finish"> This function initiates a font selection operation by -presenting a dialog to the user for selecting a font family. + line="612">Presents a font chooser dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_family_finish] -to obtain the result. +The font chooser dialog will be set up for selecting a font family. @@ -63204,7 +64860,7 @@ to obtain the result. a `GtkFontDialog` + line="614">a font dialog allow-none="1"> the parent `GtkWindow` + line="615">the parent window allow-none="1"> the initial value + line="616">the initial value allow-none="1"> a `GCancellable` to cancel the operation + line="617">a cancellable to cancel the operation closure="4"> a callback to call when the operation is complete + line="618">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="620">data to pass to @callback @@ -63263,8 +64919,7 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.FontDialog.choose_family] call -and returns the resulting family. + line="666">Finishes the [method@Gtk.FontDialog.choose_family] call. This function never returns an error. If the operation is not finished successfully, the value passed as @initial_value @@ -63273,35 +64928,33 @@ to [method@Gtk.FontDialog.choose_family] is returned. the selected family + line="678">the selected family a `GtkFontDialog` + line="668">a font dialog a `GAsyncResult` + line="669">the result + version="4.10" + glib:finish-func="choose_font_finish"> This function initiates a font selection operation by -presenting a dialog to the user for selecting a font. + line="778">Presents a font chooser dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_font_finish] -to obtain the result. +The font chooser dialog will be set up for selecting a font. If you want to let the user select font features as well, use [method@Gtk.FontDialog.choose_font_and_features] instead. @@ -63313,7 +64966,7 @@ use [method@Gtk.FontDialog.choose_font_and_features] instead. a `GtkFontDialog` + line="780">a font dialog allow-none="1"> the parent `GtkWindow` + line="781">the parent window allow-none="1"> the font to select initially + line="782">the font to select initially allow-none="1"> a `GCancellable` to cancel the operation + line="783">a cancellable to cancel the operation closure="4"> a callback to call when the operation is complete + line="784">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="786">data to pass to @callback + version="4.10" + glib:finish-func="choose_font_and_features_finish"> This function initiates a font selection operation by -presenting a dialog to the user for selecting a font and -font features. + line="856">Presents a font chooser dialog to the user. -Font features affect how the font is rendered, for example -enabling glyph variants or ligatures. +The font chooser dialog will be set up for selecting a font +and specify features for the selected font. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_font_and_features_finish] -to obtain the result. +Font features affect how the font is rendered, for example +enabling glyph variants or ligatures. @@ -63389,7 +65040,7 @@ to obtain the result. a `GtkFontDialog` + line="858">a font dialog allow-none="1"> the parent `GtkWindow` + line="859">the parent window allow-none="1"> the font to select initially + line="860">the font to select initially allow-none="1"> a `GCancellable` to cancel the operation + line="861">a cancellable to cancel the operation closure="4"> a callback to call when the operation is complete + line="862">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="864">data to pass to @callback @@ -63448,27 +65099,28 @@ to obtain the result. throws="1"> Finishes the [method@Gtk.FontDialog.choose_font_and_features] -call and returns the resulting font description and font features. + line="909">Finishes the [method@Gtk.FontDialog.choose_font_and_features] call. + +The selected font and features are returned in @font_desc and +@font_features. `TRUE` if a font was selected. Otherwise `FALSE` is returned - and @error is set + line="923">true if a font was selected a `GtkFontDialog` + line="911">a font dialog a `GAsyncResult` + line="912">the result transfer-ownership="full"> return location for font description + line="913">return location for font description @@ -63487,7 +65139,7 @@ call and returns the resulting font description and font features. transfer-ownership="full"> return location for font features + line="914">return location for font features transfer-ownership="full"> return location for the language + line="915">return location for the language @@ -63507,26 +65159,25 @@ call and returns the resulting font description and font features. throws="1"> Finishes the [method@Gtk.FontDialog.choose_font] call -and returns the resulting font description. + line="829">Finishes the [method@Gtk.FontDialog.choose_font] call. the selected font + line="837">the selected font a `GtkFontDialog` + line="831">a font dialog a `GAsyncResult` + line="832">the result @@ -63537,20 +65188,20 @@ and returns the resulting font description. version="4.10"> Returns the filter that decides which fonts to display + line="437">Returns the filter that decides which fonts to display in the font chooser dialog. the filter + line="444">the filter a `GtkFontDialog` + line="439">a font dialog @@ -63561,20 +65212,20 @@ in the font chooser dialog. version="4.10"> Returns the fontmap from which fonts are selected, + line="397">Returns the fontmap from which fonts are selected, or `NULL` for the default fontmap. the fontmap + line="404">the fontmap a `GtkFontDialog` + line="399">a font dialog @@ -63585,19 +65236,19 @@ or `NULL` for the default fontmap. version="4.10"> Returns the language for which font features are applied. + line="356">Returns the language for which font features are applied. the language for font features + line="362">the language for font features a `GtkFontDialog` + line="358">a font dialog @@ -63608,21 +65259,20 @@ or `NULL` for the default fontmap. version="4.10"> Returns whether the font chooser dialog -blocks interaction with the parent window -while it is presented. + line="313">Returns whether the font chooser dialog blocks interaction +with the parent window while it is presented. `TRUE` if the font chooser dialog is modal + line="320">true if the font chooser dialog is modal a `GtkFontDialog` + line="315">a font dialog @@ -63633,20 +65283,19 @@ while it is presented. version="4.10"> Returns the title that will be shown on the -font chooser dialog. + line="267">Returns the title that will be shown on the font chooser dialog. the title + line="273">the title a `GtkFontDialog` + line="269">a font dialog @@ -63657,10 +65306,10 @@ font chooser dialog. version="4.10"> Adds a filter that decides which fonts to display + line="455">Adds a filter that decides which fonts to display in the font chooser dialog. -The `GtkFilter` must be able to handle both `PangoFontFamily` +The filter must be able to handle both `PangoFontFamily` and `PangoFontFace` objects. @@ -63670,7 +65319,7 @@ and `PangoFontFace` objects. a `GtkFontDialog` + line="457">a font dialog allow-none="1"> a `GtkFilter` + line="458">the filter @@ -63690,7 +65339,7 @@ and `PangoFontFace` objects. version="4.10"> Sets the fontmap from which fonts are selected. + line="416">Sets the fontmap from which fonts are selected. If @fontmap is `NULL`, the default fontmap is used. @@ -63701,7 +65350,7 @@ If @fontmap is `NULL`, the default fontmap is used. a `GtkFontDialog` + line="418">a font dialog allow-none="1"> the fontmap + line="419">the fontmap @@ -63721,7 +65370,7 @@ If @fontmap is `NULL`, the default fontmap is used. version="4.10"> Sets the language for which font features are applied. + line="374">Sets the language for which font features are applied. @@ -63730,13 +65379,13 @@ If @fontmap is `NULL`, the default fontmap is used. a `GtkFontDialog` + line="376">a font dialog the language for font features + line="377">the language for font features @@ -63747,9 +65396,8 @@ If @fontmap is `NULL`, the default fontmap is used. version="4.10"> Sets whether the font chooser dialog -blocks interaction with the parent window -while it is presented. + line="332">Sets whether the font chooser dialog blocks interaction +with the parent window while it is presented. @@ -63758,13 +65406,13 @@ while it is presented. a `GtkFontDialog` + line="334">a font dialog the new value + line="335">the new value @@ -63775,8 +65423,7 @@ while it is presented. version="4.10"> Sets the title that will be shown on the -font chooser dialog. + line="285">Sets the title that will be shown on the font chooser dialog. @@ -63785,13 +65432,13 @@ font chooser dialog. a `GtkFontDialog` + line="287">a font dialog the new title + line="288">the new title @@ -63802,14 +65449,9 @@ font chooser dialog. transfer-ownership="none" setter="set_filter" getter="get_filter"> - - Sets a filter to restrict what fonts are shown -in the font chooser dialog. + line="231">A filter to restrict what fonts are shown in the font chooser dialog. transfer-ownership="none" setter="set_font_map" getter="get_font_map"> - - Sets a custom font map to select fonts from. + line="216">A custom font map to select fonts from. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. @@ -63836,13 +65474,9 @@ fonts instead of or in addition to the normal system fonts. transfer-ownership="none" setter="set_language" getter="get_language"> - - The language for which the font features are selected. + line="204">The language for which the font features are selected. setter="set_modal" getter="get_modal" default-value="TRUE"> - - Whether the font chooser dialog is modal. + line="192">Whether the font chooser dialog is modal. setter="set_title" getter="get_title" default-value="NULL"> - - A title that may be shown on the font chooser + line="179">A title that may be shown on the font chooser dialog that is presented by [method@Gtk.FontDialog.choose_font]. @@ -63889,10 +65515,12 @@ dialog that is presented by [method@Gtk.FontDialog.choose_font]. glib:type-struct="FontDialogButtonClass"> The `GtkFontDialogButton` is wrapped around a [class@Gtk.FontDialog] -and allows to open a font chooser dialog to change the font. + line="40">Opens a font chooser dialog to select a font. -![An example GtkFontDialogButton](font-button.png) +<picture> + <source srcset="font-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkFontDialogButton" src="font-button.png"> +</picture> It is suitable widget for selecting a font in a preference dialog. @@ -63915,7 +65543,7 @@ contains a button node with the .font style class. version="4.10"> Creates a new `GtkFontDialogButton` with the + line="729">Creates a new `GtkFontDialogButton` with the given `GtkFontDialog`. You can pass `NULL` to this function and set a `GtkFontDialog` @@ -63924,7 +65552,7 @@ later. The button will be insensitive until that happens. the new `GtkFontDialogButton` + line="739">the new `GtkFontDialogButton` @@ -63934,7 +65562,7 @@ later. The button will be insensitive until that happens. allow-none="1"> the `GtkFontDialog` to use + line="731">the `GtkFontDialog` to use @@ -63945,19 +65573,19 @@ later. The button will be insensitive until that happens. version="4.10"> Returns the `GtkFontDialog` of @self. + line="788">Returns the `GtkFontDialog` of @self. the `GtkFontDialog` + line="794">the `GtkFontDialog` a `GtkFontDialogButton` + line="790">a `GtkFontDialogButton` @@ -63968,7 +65596,7 @@ later. The button will be insensitive until that happens. version="4.10"> Returns the font of the button. + line="882">Returns the font of the button. This function is what should be used to obtain the font that was chosen by the user. To get @@ -63977,14 +65605,14 @@ informed about changes, listen to "notify::font-desc". the font + line="892">the font a `GtkFontDialogButton` + line="884">a `GtkFontDialogButton` @@ -63995,7 +65623,7 @@ informed about changes, listen to "notify::font-desc". version="4.10"> Returns the font features of the button. + line="933">Returns the font features of the button. This function is what should be used to obtain the font features that were chosen by the user. To get informed about changes, listen @@ -64008,14 +65636,14 @@ if [property@Gtk.FontDialogButton:level] is set to the font features + line="947">the font features a `GtkFontDialogButton` + line="935">a `GtkFontDialogButton` @@ -64026,19 +65654,19 @@ if [property@Gtk.FontDialogButton:level] is set to version="4.10"> Returns the language that is used for font features. + line="984">Returns the language that is used for font features. the language + line="990">the language a `GtkFontDialogButton` + line="986">a `GtkFontDialogButton` @@ -64049,20 +65677,20 @@ if [property@Gtk.FontDialogButton:level] is set to version="4.10"> Returns the level of detail at which this dialog + line="806">Returns the level of detail at which this dialog lets the user select fonts. the level of detail + line="813">the level of detail a `GtkFontDialogButton + line="808">a `GtkFontDialogButton @@ -64073,19 +65701,19 @@ lets the user select fonts. version="4.10"> Returns whether the selected font is used in the label. + line="1032">Returns whether the selected font is used in the label. whether the selected font is used in the label + line="1038">whether the selected font is used in the label a `GtkFontDialogButton` + line="1034">a `GtkFontDialogButton` @@ -64096,19 +65724,19 @@ lets the user select fonts. version="4.10"> Returns whether the selected font size is used in the label. + line="1077">Returns whether the selected font size is used in the label. whether the selected font size is used in the label + line="1083">whether the selected font size is used in the label a `GtkFontDialogButton` + line="1079">a `GtkFontDialogButton` @@ -64119,7 +65747,7 @@ lets the user select fonts. version="4.10"> Sets a `GtkFontDialog` object to use for + line="762">Sets a `GtkFontDialog` object to use for creating the font chooser dialog that is presented when the user clicks the button. @@ -64130,13 +65758,13 @@ presented when the user clicks the button. a `GtkFontDialogButton` + line="764">a `GtkFontDialogButton` the new `GtkFontDialog` + line="765">the new `GtkFontDialog` @@ -64147,7 +65775,7 @@ presented when the user clicks the button. version="4.10"> Sets the font of the button. + line="849">Sets the font of the button. @@ -64156,13 +65784,13 @@ presented when the user clicks the button. a `GtkFontDialogButton` + line="851">a `GtkFontDialogButton` the new font + line="852">the new font @@ -64174,7 +65802,7 @@ presented when the user clicks the button. version="4.10"> Sets the font features of the button. + line="904">Sets the font features of the button. @@ -64183,7 +65811,7 @@ presented when the user clicks the button. a `GtkFontDialogButton` + line="906">a `GtkFontDialogButton` allow-none="1"> the font features + line="907">the font features @@ -64203,7 +65831,7 @@ presented when the user clicks the button. version="4.10"> Sets the language to use for font features. + line="959">Sets the language to use for font features. @@ -64212,7 +65840,7 @@ presented when the user clicks the button. a `GtkFontDialogButton` + line="961">a `GtkFontDialogButton` allow-none="1"> the new language + line="962">the new language @@ -64232,7 +65860,7 @@ presented when the user clicks the button. version="4.10"> Sets the level of detail at which this dialog + line="825">Sets the level of detail at which this dialog lets the user select fonts. @@ -64242,13 +65870,13 @@ lets the user select fonts. a `GtkFontDialogButton` + line="827">a `GtkFontDialogButton` the level of detail + line="828">the level of detail @@ -64259,7 +65887,7 @@ lets the user select fonts. version="4.10"> If @use_font is `TRUE`, the font name will be written + line="1005">If @use_font is `TRUE`, the font name will be written using the selected font. @@ -64269,13 +65897,13 @@ using the selected font. a `GtkFontDialogButton` + line="1007">a `GtkFontDialogButton` If `TRUE`, font name will be written using + line="1008">If `TRUE`, font name will be written using the chosen font @@ -64287,7 +65915,7 @@ using the selected font. version="4.10"> If @use_size is `TRUE`, the font name will be written + line="1050">If @use_size is `TRUE`, the font name will be written using the selected font size. @@ -64297,13 +65925,13 @@ using the selected font size. a `GtkFontDialogButton` + line="1052">a `GtkFontDialogButton` If `TRUE`, font name will be written using + line="1053">If `TRUE`, font name will be written using the chosen font size @@ -64315,13 +65943,9 @@ using the selected font size. transfer-ownership="none" setter="set_dialog" getter="get_dialog"> - - The `GtkFontDialog` that contains parameters for + line="298">The `GtkFontDialog` that contains parameters for the font chooser dialog. @@ -64331,13 +65955,9 @@ the font chooser dialog. transfer-ownership="none" setter="set_font_desc" getter="get_font_desc"> - - The selected font. + line="322">The selected font. This property can be set to give the button its initial font, and it will be updated to reflect the users choice @@ -64354,13 +65974,9 @@ to the buttons font. setter="set_font_features" getter="get_font_features" default-value="NULL"> - - The selected font features. + line="341">The selected font features. This property will be updated to reflect the users choice in the font chooser dialog. @@ -64375,13 +65991,9 @@ to the buttons font features. transfer-ownership="none" setter="set_language" getter="get_language"> - - The selected language for font features. + line="359">The selected language for font features. This property will be updated to reflect the users choice in the font chooser dialog. @@ -64396,13 +66008,9 @@ to the buttons language. setter="set_level" getter="get_level" default-value="GTK_FONT_LEVEL_FONT"> - - The level of detail for the font chooser dialog. + line="311">The level of detail for the font chooser dialog. setter="set_use_font" getter="get_use_font" default-value="FALSE"> - - Whether the buttons label will be drawn in the selected font. + line="377">Whether the buttons label will be drawn in the selected font. setter="set_use_size" getter="get_use_size" default-value="FALSE"> - - Whether the buttons label will use the selected font size. + line="387">Whether the buttons label will use the selected font size. Emitted when the font dialog button is activated. + line="399">Emitted when the font dialog button is activated. The `::activate` signal on `GtkFontDialogButton` is an action signal and emitting it causes the button to pop up its dialog. @@ -64551,6 +66151,36 @@ will have more or less fields set. line="51">Select a font and font features + + Values for the [property@Gtk.Settings:gtk-font-rendering] setting +that influence how GTK renders fonts. + + Set up font rendering automatically, + taking factors like screen resolution and scale into account + + + Follow low-level font-related settings + when configuring font rendering + + glib:type-struct="FrameClass"> `GtkFrame` is a widget that surrounds its child with a decorative -frame and an optional label. + line="36">Surrounds its child with a decorative frame and an optional label. -![An example GtkFrame](frame.png) +<picture> + <source srcset="frame-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkFrame" src="frame.png"> +</picture> If present, the label is drawn inside the top edge of the frame. The horizontal position of the label can be controlled with @@ -64605,7 +66237,7 @@ like “border-style” on this node. # Accessibility -`GtkFrame` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. +`GtkFrame` uses the [enum@Gtk.AccessibleRole.group] role. @@ -64613,14 +66245,14 @@ like “border-style” on this node. Creates a new `GtkFrame`, with optional label @label. + line="331">Creates a new `GtkFrame`, with optional label @label. If @label is %NULL, the label is omitted. a new `GtkFrame` widget + line="339">a new `GtkFrame` widget @@ -64630,7 +66262,7 @@ If @label is %NULL, the label is omitted. allow-none="1"> the text to use as the label of the frame + line="333">the text to use as the label of the frame @@ -64652,22 +66284,21 @@ If @label is %NULL, the label is omitted. - Gets the child widget of @frame. + line="705">Gets the child widget of @frame. the child widget of @frame + line="711">the child widget of @frame a `GtkFrame` + line="707">a `GtkFrame` @@ -64675,10 +66306,9 @@ If @label is %NULL, the label is omitted. - Returns the frame labels text. + line="367">Returns the frame labels text. If the frame's label widget is not a `GtkLabel`, %NULL is returned. @@ -64686,7 +66316,7 @@ is returned. the text in the label, or %NULL if there + line="376">the text in the label, or %NULL if there was no label widget or the label widget was not a `GtkLabel`. This string is owned by GTK and must not be modified or freed. @@ -64695,28 +66325,29 @@ is returned. a `GtkFrame` + line="369">a `GtkFrame` - - + Retrieves the X alignment of the frame’s label. + line="497">Retrieves the X alignment of the frame’s label. the frames X alignment + line="503">the frames X alignment a `GtkFrame` + line="499">a `GtkFrame` @@ -64724,22 +66355,21 @@ is returned. - Retrieves the label widget for the frame. + line="451">Retrieves the label widget for the frame. the label widget + line="457">the label widget a `GtkFrame` + line="453">a `GtkFrame` @@ -64747,10 +66377,9 @@ is returned. - Sets the child widget of @frame. + line="673">Sets the child widget of @frame. @@ -64759,7 +66388,7 @@ is returned. a `GtkFrame` + line="675">a `GtkFrame` allow-none="1"> the child widget + line="676">the child widget @@ -64776,10 +66405,9 @@ is returned. - Creates a new `GtkLabel` with the @label and sets it as the frame's + line="347">Creates a new `GtkLabel` with the @label and sets it as the frame's label widget. @@ -64789,7 +66417,7 @@ label widget. a `GtkFrame` + line="349">a `GtkFrame` allow-none="1"> the text to use as the label of the frame + line="350">the text to use as the label of the frame - - + Sets the X alignment of the frame widget’s label. + line="469">Sets the X alignment of the frame widget’s label. The default value for a newly created frame is 0.0. @@ -64818,13 +66447,13 @@ The default value for a newly created frame is 0.0. a `GtkFrame` + line="471">a `GtkFrame` The position of the label along the top edge + line="472">The position of the label along the top edge of the widget. A value of 0.0 represents left alignment; 1.0 represents right alignment. @@ -64834,10 +66463,9 @@ The default value for a newly created frame is 0.0. - Sets the label widget for the frame. + line="410">Sets the label widget for the frame. This is the widget that will appear embedded in the top edge of the frame as a title. @@ -64849,7 +66477,7 @@ of the frame as a title. a `GtkFrame` + line="412">a `GtkFrame` allow-none="1"> the new label widget + line="413">the new label widget @@ -64868,11 +66496,9 @@ of the frame as a title. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="200">The child widget. setter="set_label" getter="get_label" default-value="NULL"> - - Text of the frame's label. + line="169">Text of the frame's label. transfer-ownership="none" setter="set_label_widget" getter="get_label_widget"> - - Widget to display in place of the usual frame label. + line="190">Widget to display in place of the usual frame label. - - The horizontal alignment of the label. + line="179">The horizontal alignment of the label. @@ -65230,9 +66848,12 @@ of the frame as a title. glib:type-struct="GLAreaClass"> `GtkGLArea` is a widget that allows drawing with OpenGL. + line="46">Allows drawing with OpenGL. -![An example GtkGLArea](glarea.png) +<picture> + <source srcset="glarea-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkGLArea" src="glarea.png"> +</picture> `GtkGLArea` sets up its own [class@Gdk.GLContext], and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures @@ -65343,16 +66964,19 @@ you should use the [signal@Gtk.GLArea::create-context] signal. Creates a new `GtkGLArea` widget. + line="1103">Creates a new `GtkGLArea` widget. a new `GtkGLArea` + line="1108">a new `GtkGLArea` + class closure for the `GtkGLArea::create-context` signal @@ -65364,6 +66988,9 @@ you should use the [signal@Gtk.GLArea::create-context] signal. + class closure for the `GtkGLArea::render` signal @@ -65378,6 +67005,9 @@ you should use the [signal@Gtk.GLArea::create-context] signal. + class closeure for the `GtkGLArea::resize` signal @@ -65397,7 +67027,7 @@ you should use the [signal@Gtk.GLArea::create-context] signal. Binds buffers to the framebuffer. + line="561">Binds buffers to the framebuffer. Ensures that the @area framebuffer object is made the current draw and read target, and that all the required buffers for the @area @@ -65414,7 +67044,7 @@ called by application code. a `GtkGLArea` + line="563">a `GtkGLArea` @@ -65425,21 +67055,21 @@ called by application code. version="4.12"> Gets the allowed APIs. + line="1250">Gets the allowed APIs. See [method@Gtk.GLArea.set_allowed_apis]. the allowed APIs + line="1258">the allowed APIs a `GtkGLArea` + line="1252">a `GtkGLArea` @@ -65450,21 +67080,21 @@ See [method@Gtk.GLArea.set_allowed_apis]. version="4.12"> Gets the API that is currently in use. + line="1272">Gets the API that is currently in use. If the GL area has not been realized yet, 0 is returned. the currently used API + line="1280">the currently used API a `GtkGLArea` + line="1274">a `GtkGLArea` @@ -65472,22 +67102,21 @@ If the GL area has not been realized yet, 0 is returned. - Returns whether the area is in auto render mode or not. + line="1471">Returns whether the area is in auto render mode or not. %TRUE if the @area is auto rendering, %FALSE otherwise + line="1477">%TRUE if the @area is auto rendering, %FALSE otherwise a `GtkGLArea` + line="1473">a `GtkGLArea` @@ -65497,19 +67126,19 @@ If the GL area has not been realized yet, 0 is returned. glib:get-property="context"> Retrieves the `GdkGLContext` used by @area. + line="1527">Retrieves the `GdkGLContext` used by @area. the `GdkGLContext` + line="1533">the `GdkGLContext` a `GtkGLArea` + line="1529">a `GtkGLArea` @@ -65517,19 +67146,19 @@ If the GL area has not been realized yet, 0 is returned. Gets the current error set on the @area. + line="1140">Gets the current error set on the @area. the `GError` + line="1146">the `GError` a `GtkGLArea` + line="1142">a `GtkGLArea` @@ -65537,23 +67166,21 @@ If the GL area has not been realized yet, 0 is returned. - Returns whether the area has a depth buffer. + line="1346">Returns whether the area has a depth buffer. %TRUE if the @area has a depth buffer, %FALSE otherwise + line="1352">%TRUE if the @area has a depth buffer, %FALSE otherwise a `GtkGLArea` + line="1348">a `GtkGLArea` @@ -65561,23 +67188,21 @@ If the GL area has not been realized yet, 0 is returned. - Returns whether the area has a stencil buffer. + line="1395">Returns whether the area has a stencil buffer. %TRUE if the @area has a stencil buffer, %FALSE otherwise + line="1401">%TRUE if the @area has a stencil buffer, %FALSE otherwise a `GtkGLArea` + line="1397">a `GtkGLArea` @@ -65586,7 +67211,7 @@ If the GL area has not been realized yet, 0 is returned. c:identifier="gtk_gl_area_get_required_version"> Retrieves the required version of OpenGL. + line="1321">Retrieves the required version of OpenGL. See [method@Gtk.GLArea.set_required_version]. @@ -65597,7 +67222,7 @@ See [method@Gtk.GLArea.set_required_version]. a `GtkGLArea` + line="1323">a `GtkGLArea` transfer-ownership="full"> return location for the required major version + line="1324">return location for the required major version transfer-ownership="full"> return location for the required minor version + line="1325">return location for the required minor version @@ -65625,10 +67250,9 @@ See [method@Gtk.GLArea.set_required_version]. glib:get-property="use-es" deprecated="1" deprecated-version="4.12"> - Returns whether the `GtkGLArea` should use OpenGL ES. + line="1188">Returns whether the `GtkGLArea` should use OpenGL ES. See [method@Gtk.GLArea.set_use_es]. Use [method@Gtk.GLArea.get_api] @@ -65636,7 +67260,7 @@ See [method@Gtk.GLArea.set_use_es]. %TRUE if the `GtkGLArea` should create an OpenGL ES context + line="1196">%TRUE if the `GtkGLArea` should create an OpenGL ES context and %FALSE otherwise @@ -65644,7 +67268,7 @@ See [method@Gtk.GLArea.set_use_es]. a `GtkGLArea` + line="1190">a `GtkGLArea` @@ -65652,7 +67276,7 @@ See [method@Gtk.GLArea.set_use_es]. Ensures that the `GdkGLContext` used by @area is associated with + line="1545">Ensures that the `GdkGLContext` used by @area is associated with the `GtkGLArea`. This function is automatically called before emitting the @@ -65666,7 +67290,7 @@ to be called by application code. a `GtkGLArea` + line="1547">a `GtkGLArea` @@ -65674,7 +67298,7 @@ to be called by application code. Marks the currently rendered data (if any) as invalid, and queues + line="1444">Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget. This ensures that the [signal@Gtk.GLArea::render] signal @@ -65691,7 +67315,7 @@ emit [signal@Gtk.GLArea::render] on each draw. a `GtkGLArea` + line="1446">a `GtkGLArea` @@ -65702,7 +67326,7 @@ emit [signal@Gtk.GLArea::render] on each draw. version="4.12"> Sets the allowed APIs to create a context with. + line="1214">Sets the allowed APIs to create a context with. You should check [property@Gtk.GLArea:api] before drawing with either API. @@ -65716,13 +67340,13 @@ By default, all APIs are allowed. a `GtkGLArea` + line="1216">a `GtkGLArea` the allowed APIs + line="1217">the allowed APIs @@ -65730,10 +67354,9 @@ By default, all APIs are allowed. - Sets whether the `GtkGLArea` is in auto render mode. + line="1489">Sets whether the `GtkGLArea` is in auto render mode. If @auto_render is %TRUE the [signal@Gtk.GLArea::render] signal will be emitted every time the widget draws. This is the default and is @@ -65752,13 +67375,13 @@ useful when the scene changes seldom, but takes a long time to redraw. a `GtkGLArea` + line="1491">a `GtkGLArea` a boolean + line="1492">a boolean @@ -65766,7 +67389,7 @@ useful when the scene changes seldom, but takes a long time to redraw. Sets an error on the area which will be shown instead of the + line="1116">Sets an error on the area which will be shown instead of the GL rendering. This is useful in the [signal@Gtk.GLArea::create-context] @@ -65779,7 +67402,7 @@ signal if GL context creation fails. a `GtkGLArea` + line="1118">a `GtkGLArea` allow-none="1"> a new `GError`, or %NULL to unset the error + line="1119">a new `GError`, or %NULL to unset the error @@ -65796,11 +67419,9 @@ signal if GL context creation fails. - Sets whether the `GtkGLArea` should use a depth buffer. + line="1364">Sets whether the `GtkGLArea` should use a depth buffer. If @has_depth_buffer is %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise @@ -65813,13 +67434,13 @@ there will be none. a `GtkGLArea` + line="1366">a `GtkGLArea` %TRUE to add a depth buffer + line="1367">%TRUE to add a depth buffer @@ -65827,11 +67448,9 @@ there will be none. - Sets whether the `GtkGLArea` should use a stencil buffer. + line="1413">Sets whether the `GtkGLArea` should use a stencil buffer. If @has_stencil_buffer is %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise @@ -65844,13 +67463,13 @@ there will be none. a `GtkGLArea` + line="1415">a `GtkGLArea` %TRUE to add a stencil buffer + line="1416">%TRUE to add a stencil buffer @@ -65859,7 +67478,7 @@ there will be none. c:identifier="gtk_gl_area_set_required_version"> Sets the required version of OpenGL to be used when creating + line="1297">Sets the required version of OpenGL to be used when creating the context for the widget. This function must be called before the area has been realized. @@ -65871,19 +67490,19 @@ This function must be called before the area has been realized. a `GtkGLArea` + line="1299">a `GtkGLArea` the major version + line="1300">the major version the minor version + line="1301">the minor version @@ -65893,10 +67512,9 @@ This function must be called before the area has been realized. glib:set-property="use-es" deprecated="1" deprecated-version="4.12"> - Sets whether the @area should create an OpenGL or an OpenGL ES context. + line="1158">Sets whether the @area should create an OpenGL or an OpenGL ES context. You should check the capabilities of the `GdkGLContext` before drawing with either API. @@ -65909,13 +67527,13 @@ with either API. a `GtkGLArea` + line="1160">a `GtkGLArea` whether to use OpenGL or OpenGL ES + line="1161">whether to use OpenGL or OpenGL ES @@ -65927,13 +67545,9 @@ with either API. setter="set_allowed_apis" getter="get_allowed_apis" default-value="GDK_GL_API_GL | GDK_GL_API_GLES"> - - The allowed APIs. + line="969">The allowed APIs. transfer-ownership="none" getter="get_api" default-value="0"> - The API currently in use. + line="984">The API currently in use. setter="set_auto_render" getter="get_auto_render" default-value="TRUE"> - - If set to %TRUE the ::render signal will be emitted every time + line="903">If set to %TRUE the ::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. @@ -65974,7 +67583,7 @@ to redraw. The `GdkGLContext` used by the `GtkGLArea` widget. + line="888">The `GdkGLContext` used by the `GtkGLArea` widget. The `GtkGLArea` widget is responsible for creating the `GdkGLContext` instance. If you need to render with other kinds of buffers (stencil, @@ -65987,13 +67596,9 @@ depth, etc), use render buffers. setter="set_has_depth_buffer" getter="get_has_depth_buffer" default-value="FALSE"> - - If set to %TRUE the widget will allocate and enable a depth buffer for the + line="924">If set to %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Setting this property will enable GL's depth testing as a side effect. If @@ -66007,13 +67612,9 @@ in your `GtkGLArea::render` handler. setter="set_has_stencil_buffer" getter="get_has_stencil_buffer" default-value="FALSE"> - - If set to %TRUE the widget will allocate and enable a stencil buffer for the + line="941">If set to %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. @@ -66025,11 +67626,9 @@ target framebuffer. setter="set_use_es" getter="get_use_es" default-value="FALSE"> - - If set to %TRUE the widget will try to create a `GdkGLContext` using + line="954">If set to %TRUE the widget will try to create a `GdkGLContext` using OpenGL ES instead of OpenGL. Use [property@Gtk.GLArea:allowed-apis] @@ -66040,7 +67639,7 @@ OpenGL ES instead of OpenGL. Emitted when the widget is being realized. + line="1061">Emitted when the widget is being realized. This allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, @@ -66052,7 +67651,7 @@ of how the construction failed. a newly created `GdkGLContext`; + line="1076">a newly created `GdkGLContext`; the `GtkGLArea` widget will take ownership of the returned value. @@ -66060,14 +67659,14 @@ of how the construction failed. Emitted every time the contents of the `GtkGLArea` should be redrawn. + line="1005">Emitted every time the contents of the `GtkGLArea` should be redrawn. The @context is bound to the @area prior to emitting this function, and the buffers are painted to the window once the emission terminates. %TRUE to stop other handlers from being invoked for the event. + line="1015">%TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. @@ -66075,7 +67674,7 @@ and the buffers are painted to the window once the emission terminates. the `GdkGLContext` used by @area + line="1008">the `GdkGLContext` used by @area @@ -66083,7 +67682,7 @@ and the buffers are painted to the window once the emission terminates. Emitted once when the widget is realized, and then each time the widget + line="1031">Emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, @@ -66101,13 +67700,13 @@ The default handler sets up the GL viewport. the width of the viewport + line="1034">the width of the viewport the height of the viewport + line="1035">the height of the viewport @@ -66124,6 +67723,9 @@ The default handler sets up the GL viewport. + class closure for the `GtkGLArea::render` signal @@ -66140,6 +67742,9 @@ The default handler sets up the GL viewport. + class closeure for the `GtkGLArea::resize` signal @@ -66159,6 +67764,9 @@ The default handler sets up the GL viewport. + class closure for the `GtkGLArea::create-context` signal @@ -66266,7 +67874,7 @@ The default handler sets up the GL viewport. glib:type-struct="GestureClass"> `GtkGesture` is the base class for gesture recognition. + line="21">The base class for gesture recognition. Although `GtkGesture` is quite generalized to serve as a base for multi-touch gestures, it is suitable to implement single-touch and @@ -67115,7 +68723,7 @@ more about the expectable sequence lifetimes. glib:type-struct="GestureClickClass"> `GtkGestureClick` is a `GtkGesture` implementation for clicks. + line="20">Recognizes click gestures. It is able to recognize multiple clicks on a nearby zone, which can be listened for through the [signal@Gtk.GestureClick::pressed] @@ -67264,7 +68872,7 @@ widget voluntarily relinquishes its implicit grab. glib:type-struct="GestureDragClass"> `GtkGestureDrag` is a `GtkGesture` implementation for drags. + line="20">Recognizes drag gestures. The drag operation itself can be tracked throughout the [signal@Gtk.GestureDrag::drag-begin], @@ -67462,7 +69070,7 @@ in widget-relative coordinates. glib:type-struct="GestureLongPressClass"> `GtkGestureLongPress` is a `GtkGesture` for long presses. + line="21">Recognizes long press gestures. This gesture is also known as “Press and Hold”. @@ -67493,7 +69101,6 @@ property. - Returns the delay factor. @@ -67516,7 +69123,6 @@ property. - Applies the given delay factor. @@ -67548,10 +69154,6 @@ Valid values are in the range [0.5..2.0]. setter="set_delay_factor" getter="get_delay_factor" default-value="1.000000"> - - Factor by which to modify the default timeout. @@ -67606,7 +69208,7 @@ what the GTK defaults tell. glib:type-struct="GesturePanClass"> `GtkGesturePan` is a `GtkGesture` for pan gestures. + line="20">Recognizes pan gestures. These are drags that are locked to happen along one axis. The axis that a `GtkGesturePan` handles is defined at construct time, and @@ -67644,7 +69246,6 @@ events are received, containing the offset in the given axis. - Returns the orientation of the pan gestures that this @gesture expects. @@ -67667,7 +69268,6 @@ events are received, containing the offset in the given axis. - Sets the orientation to be expected on pan gestures. @@ -67696,10 +69296,6 @@ events are received, containing the offset in the given axis. setter="set_orientation" getter="get_orientation" default-value="GTK_ORIENTATION_HORIZONTAL"> - - The expected orientation of pan gestures. @@ -67744,7 +69340,7 @@ events are received, containing the offset in the given axis. glib:type-struct="GestureRotateClass"> `GtkGestureRotate` is a `GtkGesture` for 2-finger rotations. + line="21">Recognizes 2-finger rotation gestures. Whenever the angle between both handled sequences changes, the [signal@Gtk.GestureRotate::angle-changed] signal is emitted. @@ -67826,8 +69422,7 @@ not active, 0 is returned. glib:type-struct="GestureSingleClass"> `GtkGestureSingle` is a `GtkGestures` subclass optimized for singe-touch -and mouse gestures. + line="21">A `GtkGesture` subclass optimized for singe-touch and mouse gestures. Under interaction, these gestures stick to the first interacting sequence, which is accessible through [method@Gtk.GestureSingle.get_current_sequence] @@ -67844,24 +69439,23 @@ button being currently pressed can be known through - Returns the button number @gesture listens for. + line="403">Returns the button number @gesture listens for. If this is 0, the gesture reacts to any button press. The button number, or 0 for any button + line="411">The button number, or 0 for any button a `GtkGestureSingle` + line="405">a `GtkGestureSingle` @@ -67870,20 +69464,20 @@ If this is 0, the gesture reacts to any button press. c:identifier="gtk_gesture_single_get_current_button"> Returns the button number currently interacting + line="453">Returns the button number currently interacting with @gesture, or 0 if there is none. The current button number + line="460">The current button number a `GtkGestureSingle` + line="455">a `GtkGestureSingle` @@ -67892,7 +69486,7 @@ with @gesture, or 0 if there is none. c:identifier="gtk_gesture_single_get_current_sequence"> Returns the event sequence currently interacting with @gesture. + line="474">Returns the event sequence currently interacting with @gesture. This is only meaningful if [method@Gtk.Gesture.is_active] returns %TRUE. @@ -67900,14 +69494,14 @@ returns %TRUE. the current sequence + line="483">the current sequence a `GtkGestureSingle` + line="476">a `GtkGestureSingle` @@ -67915,24 +69509,23 @@ returns %TRUE. - Gets whether a gesture is exclusive. + line="352">Gets whether a gesture is exclusive. For more information, see [method@Gtk.GestureSingle.set_exclusive]. Whether the gesture is exclusive + line="360">Whether the gesture is exclusive a `GtkGestureSingle` + line="354">a `GtkGestureSingle` @@ -67940,22 +69533,21 @@ For more information, see [method@Gtk.GestureSingle.set_exclusive]. - Returns %TRUE if the gesture is only triggered by touch events. + line="303">Returns %TRUE if the gesture is only triggered by touch events. %TRUE if the gesture only handles touch events + line="309">%TRUE if the gesture only handles touch events a `GtkGestureSingle` + line="305">a `GtkGestureSingle` @@ -67963,10 +69555,9 @@ For more information, see [method@Gtk.GestureSingle.set_exclusive]. - Sets the button number @gesture listens to. + line="425">Sets the button number @gesture listens to. If non-0, every button press from a different button number will be ignored. Touch events implicitly match @@ -67979,13 +69570,13 @@ with button 1. a `GtkGestureSingle` + line="427">a `GtkGestureSingle` button number to listen to, or 0 for any button + line="428">button number to listen to, or 0 for any button @@ -67993,10 +69584,9 @@ with button 1. - Sets whether @gesture is exclusive. + line="374">Sets whether @gesture is exclusive. An exclusive gesture will only handle pointer and "pointer emulated" touch events, so at any given time, there is only one sequence able @@ -68009,13 +69599,13 @@ to interact with those. a `GtkGestureSingle` + line="376">a `GtkGestureSingle` %TRUE to make @gesture exclusive + line="377">%TRUE to make @gesture exclusive @@ -68023,10 +69613,9 @@ to interact with those. - Sets whether to handle only touch events. + line="323">Sets whether to handle only touch events. If @touch_only is %TRUE, @gesture will only handle events of type %GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE or %GDK_TOUCH_END. If %FALSE, @@ -68039,13 +69628,13 @@ mouse events will be handled too. a `GtkGestureSingle` + line="325">a `GtkGestureSingle` whether @gesture handles only touch events + line="326">whether @gesture handles only touch events @@ -68056,13 +69645,9 @@ mouse events will be handled too. setter="set_button" getter="get_button" default-value="1"> - - Mouse button number to listen to, or 0 to listen for any button. + line="279">Mouse button number to listen to, or 0 to listen for any button. setter="set_exclusive" getter="get_exclusive" default-value="FALSE"> - - Whether the gesture is exclusive. + line="267">Whether the gesture is exclusive. Exclusive gestures only listen to pointer and pointer emulated events. @@ -68088,13 +69669,9 @@ Exclusive gestures only listen to pointer and pointer emulated events. setter="set_touch_only" getter="get_touch_only" default-value="FALSE"> - - Whether the gesture handles only touch events. + line="257">Whether the gesture handles only touch events. @@ -68114,7 +69691,7 @@ Exclusive gestures only listen to pointer and pointer emulated events. glib:type-struct="GestureStylusClass"> `GtkGestureStylus` is a `GtkGesture` specific to stylus input. + line="20">Recognizes tablet stylus input. The provided signals just relay the basic information of the stylus events. @@ -68297,7 +69874,6 @@ signals. c:identifier="gtk_gesture_stylus_get_stylus_only" glib:get-property="stylus-only" version="4.10"> - Checks whether the gesture is for styluses only. @@ -68324,12 +69900,11 @@ input devices. c:identifier="gtk_gesture_stylus_set_stylus_only" glib:set-property="stylus-only" version="4.10"> - Sets the state of stylus-only -If true, the gesture will exclusivly handle events from stylus input deivces, +If true, the gesture will exclusively handle events from stylus input devices, otherwise it'll handle events from any pointing device. @@ -68345,7 +69920,7 @@ otherwise it'll handle events from any pointing device. whether the gesture is used exclusivly for stylus events + line="290">whether the gesture is used exclusively for stylus events @@ -68358,10 +69933,6 @@ otherwise it'll handle events from any pointing device. setter="set_stylus_only" getter="get_stylus_only" default-value="TRUE"> - - If this gesture should exclusively react to stylus input devices. @@ -68472,7 +70043,7 @@ otherwise it'll handle events from any pointing device. glib:type-struct="GestureSwipeClass"> `GtkGestureSwipe` is a `GtkGesture` for swipe gestures. + line="21">Recognizes swipe gestures. After a press/move/.../move/release sequence happens, the [signal@Gtk.GestureSwipe::swipe] signal will be emitted, @@ -68581,7 +70152,7 @@ Velocity and direction are a product of previously recorded events. glib:type-struct="GestureZoomClass"> `GtkGestureZoom` is a `GtkGesture` for 2-finger pinch/zoom gestures. + line="21">Recognizes 2-finger pinch/zoom gestures. Whenever the distance between both tracked sequences changes, the [signal@Gtk.GestureZoom::scale-changed] signal is emitted to report @@ -68650,6 +70221,319 @@ active, 1 is returned. glib:is-gtype-struct-for="GestureZoom"> + + Bypasses gsk rendering by passing the content of its child directly to the compositor. + +Graphics offload is an optimization to reduce overhead and battery use that is +most useful for video content. It only works on some platforms and in certain +situations. GTK will automatically fall back to normal rendering if it doesn't. + +Graphics offload is most efficient if there are no controls drawn on top of the +video content. + +You should consider using graphics offload for your main widget if it shows +frequently changing content (such as a video, or a VM display) and you provide +the content in the form of dmabuf textures (see [class@Gdk.DmabufTextureBuilder]), +in particular if it may be fullscreen. + +Numerous factors can prohibit graphics offload: + +- Unsupported platforms. Currently, graphics offload only works on Linux with Wayland. + +- Clipping, such as rounded corners that cause the video content to not be rectangular + +- Unsupported dmabuf formats (see [method@Gdk.Display.get_dmabuf_formats]) + +- Translucent video content (content with an alpha channel, even if it isn't used) + +- Transforms that are more complex than translations and scales + +- Filters such as opacity, grayscale or similar + +To investigate problems related graphics offload, GTK offers debug flags to print +out information about graphics offload and dmabuf use: + + GDK_DEBUG=offload + GDK_DEBUG=dmabuf + +The GTK inspector provides a visual debugging tool for graphics offload. + + + + + + Creates a new GtkGraphicsOffload widget. + + + the new widget + + + + + the child widget + + + + + + Returns whether the widget draws a black background. + +See [method@Gtk.GraphicsOffload.set_black_background]. + + + `TRUE` if black background is drawn + + + + + a `GtkGraphicsOffload` + + + + + + Gets the child of @self. + + + the child widget + + + + + a `GtkGraphicsOffload` + + + + + + Returns whether offload is enabled for @self. + + + whether offload is enabled + + + + + a `GtkGraphicsOffload` + + + + + + Sets whether this GtkGraphicsOffload widget will draw a black +background. + +A main use case for this is **_letterboxing_** where black bars are +visible next to the content if the aspect ratio of the content does +not match the dimensions of the monitor. + +Using this property for letterboxing instead of CSS allows compositors +to show content with maximum efficiency, using direct scanout to avoid +extra copies in the compositor. + +On Wayland, this is implemented using the +[single-pixel buffer](https://wayland.app/protocols/single-pixel-buffer-v1) +protocol. + + + + + + + a `GtkGraphicsOffload` + + + + whether to draw a black background behind the content + + + + + + Sets the child of @self. + + + + + + + a `GtkGraphicsOffload` + + + + the child widget + + + + + + Sets whether this GtkGraphicsOffload widget will attempt +to offload the content of its child widget. + + + + + + + a `GtkGraphicsOffload` + + + + whether to enable offload + + + + + + Whether to draw a black background. + + + + The child widget. + + + + Whether graphics offload is enabled. + + + + + + + + + + + Represents the state of graphics offloading. + + Graphics offloading is enabled. + + + Graphics offloading is disabled. + + glib:type-struct="GridClass"> `GtkGrid` is a container which arranges its child widgets in -rows and columns. + line="35">Arranges its child widgets in rows and columns. -![An example GtkGrid](grid.png) +<picture> + <source srcset="grid-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkGrid" src="grid.png"> +</picture> It supports arbitrary positions and horizontal/vertical spans. @@ -68740,9 +70626,9 @@ defined by the `column-span` property. # Accessibility -Until GTK 4.10, `GtkGrid` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkGrid` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkGrid` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkGrid` uses the [enum@Gtk.AccessibleRole.generic] role. @@ -68751,19 +70637,19 @@ Starting from GTK 4.12, `GtkGrid` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new grid widget. + line="527">Creates a new grid widget. the new `GtkGrid` + line="532">the new `GtkGrid` Adds a widget to the grid. + line="540">Adds a widget to the grid. The position of @child is determined by @column and @row. The number of “cells” that @child will occupy is determined @@ -68776,37 +70662,37 @@ by @width and @height. a `GtkGrid` + line="542">a `GtkGrid` the widget to add + line="543">the widget to add the column number to attach the left side of @child to + line="544">the column number to attach the left side of @child to the row number to attach the top side of @child to + line="545">the row number to attach the top side of @child to the number of columns that @child will span + line="546">the number of columns that @child will span the number of rows that @child will span + line="547">the number of rows that @child will span @@ -68814,7 +70700,7 @@ by @width and @height. Adds a widget to the grid. + line="572">Adds a widget to the grid. The widget is placed next to @sibling, on the side determined by @side. When @sibling is %NULL, the widget is placed in row (for @@ -68831,13 +70717,13 @@ Attaching widgets labeled `[1]`, `[2]`, `[3]` with `@sibling == %NULL` and a `GtkGrid` + line="574">a `GtkGrid` the widget to add + line="575">the widget to add the child of @grid that @child will be placed + line="576">the child of @grid that @child will be placed next to, or %NULL to place @child at the beginning or end the side of @sibling that @child is positioned next to + line="578">the side of @sibling that @child is positioned next to the number of columns that @child will span + line="579">the number of columns that @child will span the number of rows that @child will span + line="580">the number of rows that @child will span @@ -68873,22 +70759,21 @@ Attaching widgets labeled `[1]`, `[2]`, `[3]` with `@sibling == %NULL` and - Returns which row defines the global baseline of @grid. + line="1211">Returns which row defines the global baseline of @grid. the row index defining the global baseline + line="1217">the row index defining the global baseline a `GtkGrid` + line="1213">a `GtkGrid` @@ -68896,32 +70781,32 @@ Attaching widgets labeled `[1]`, `[2]`, `[3]` with `@sibling == %NULL` and Gets the child of @grid whose area covers the grid + line="669">Gets the child of @grid whose area covers the grid cell at @column, @row. the child at the given position + line="678">the child at the given position a `GtkGrid` + line="671">a `GtkGrid` the left edge of the cell + line="672">the left edge of the cell the top edge of the cell + line="673">the top edge of the cell @@ -68929,23 +70814,21 @@ cell at @column, @row. - Returns whether all columns of @grid have the same width. + line="1032">Returns whether all columns of @grid have the same width. whether all columns of @grid have the same width. + line="1038">whether all columns of @grid have the same width. a `GtkGrid` + line="1034">a `GtkGrid` @@ -68953,22 +70836,21 @@ cell at @column, @row. - Returns the amount of space between the columns of @grid. + line="1118">Returns the amount of space between the columns of @grid. the column spacing of @grid + line="1124">the column spacing of @grid a `GtkGrid` + line="1120">a `GtkGrid` @@ -68977,27 +70859,27 @@ cell at @column, @row. c:identifier="gtk_grid_get_row_baseline_position"> Returns the baseline position of @row. + line="1161">Returns the baseline position of @row. See [method@Gtk.Grid.set_row_baseline_position]. the baseline position of @row + line="1170">the baseline position of @row a `GtkGrid` + line="1163">a `GtkGrid` a row index + line="1164">a row index @@ -69005,22 +70887,21 @@ See [method@Gtk.Grid.set_row_baseline_position]. - Returns whether all rows of @grid have the same height. + line="990">Returns whether all rows of @grid have the same height. whether all rows of @grid have the same height. + line="996">whether all rows of @grid have the same height. a `GtkGrid` + line="992">a `GtkGrid` @@ -69028,22 +70909,21 @@ See [method@Gtk.Grid.set_row_baseline_position]. - Returns the amount of space between the rows of @grid. + line="1075">Returns the amount of space between the rows of @grid. the row spacing of @grid + line="1081">the row spacing of @grid a `GtkGrid` + line="1077">a `GtkGrid` @@ -69051,7 +70931,7 @@ See [method@Gtk.Grid.set_row_baseline_position]. Inserts a column at the specified position. + line="821">Inserts a column at the specified position. Children which are attached at or to the right of this position are moved one column to the right. Children which span across this @@ -69064,13 +70944,13 @@ position are grown to span the new column. a `GtkGrid` + line="823">a `GtkGrid` the position to insert the column at + line="824">the position to insert the column at @@ -69078,7 +70958,7 @@ position are grown to span the new column. Inserts a row or column at the specified position. + line="911">Inserts a row or column at the specified position. The new row or column is placed next to @sibling, on the side determined by @side. If @side is %GTK_POS_TOP or %GTK_POS_BOTTOM, @@ -69092,20 +70972,20 @@ a column is inserted. a `GtkGrid` + line="913">a `GtkGrid` the child of @grid that the new row or column will be + line="914">the child of @grid that the new row or column will be placed next to the side of @sibling that @child is positioned next to + line="916">the side of @sibling that @child is positioned next to @@ -69113,7 +70993,7 @@ a column is inserted. Inserts a row at the specified position. + line="732">Inserts a row at the specified position. Children which are attached at or below this position are moved one row down. Children which span across this @@ -69126,13 +71006,13 @@ position are grown to span the new row. a `GtkGrid` + line="734">a `GtkGrid` the position to insert the row at + line="735">the position to insert the row at @@ -69140,7 +71020,7 @@ position are grown to span the new row. Queries the attach points and spans of @child inside the given `GtkGrid`. + line="1229">Queries the attach points and spans of @child inside the given `GtkGrid`. @@ -69149,13 +71029,13 @@ position are grown to span the new row. a `GtkGrid` + line="1231">a `GtkGrid` a `GtkWidget` child of @grid + line="1232">a `GtkWidget` child of @grid allow-none="1"> the column used to attach the left side of @child + line="1233">the column used to attach the left side of @child allow-none="1"> the row used to attach the top side of @child + line="1234">the row used to attach the top side of @child allow-none="1"> the number of columns @child spans + line="1235">the number of columns @child spans allow-none="1"> the number of rows @child spans + line="1236">the number of rows @child spans @@ -69207,7 +71087,7 @@ position are grown to span the new row. Removes a child from @grid. + line="711">Removes a child from @grid. The child must have been added with [method@Gtk.Grid.attach] or [method@Gtk.Grid.attach_next_to]. @@ -69219,13 +71099,13 @@ The child must have been added with a `GtkGrid` + line="713">a `GtkGrid` the child widget to remove + line="714">the child widget to remove @@ -69233,7 +71113,7 @@ The child must have been added with Removes a column from the grid. + line="859">Removes a column from the grid. Children that are placed in this column are removed, spanning children that overlap this column have their @@ -69247,13 +71127,13 @@ are moved to the left. a `GtkGrid` + line="861">a `GtkGrid` the position of the column to remove + line="862">the position of the column to remove @@ -69261,7 +71141,7 @@ are moved to the left. Removes a row from the grid. + line="770">Removes a row from the grid. Children that are placed in this row are removed, spanning children that overlap this row have their @@ -69275,13 +71155,13 @@ are moved up. a `GtkGrid` + line="772">a `GtkGrid` the position of the row to remove + line="773">the position of the row to remove @@ -69289,10 +71169,9 @@ are moved up. - Sets which row defines the global baseline for the entire grid. + line="1183">Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the @@ -69305,13 +71184,13 @@ parent of the @grid. a `GtkGrid` + line="1185">a `GtkGrid` the row index + line="1186">the row index @@ -69319,11 +71198,9 @@ parent of the @grid. - Sets whether all columns of @grid will have the same width. + line="1008">Sets whether all columns of @grid will have the same width. @@ -69332,13 +71209,13 @@ parent of the @grid. a `GtkGrid` + line="1010">a `GtkGrid` %TRUE to make columns homogeneous + line="1011">%TRUE to make columns homogeneous @@ -69346,10 +71223,9 @@ parent of the @grid. - Sets the amount of space between columns of @grid. + line="1093">Sets the amount of space between columns of @grid. @@ -69358,13 +71234,13 @@ parent of the @grid. a `GtkGrid` + line="1095">a `GtkGrid` the amount of space to insert between columns + line="1096">the amount of space to insert between columns @@ -69373,7 +71249,7 @@ parent of the @grid. c:identifier="gtk_grid_set_row_baseline_position"> Sets how the baseline should be positioned on @row of the + line="1136">Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. The default baseline position is %GTK_BASELINE_POSITION_CENTER. @@ -69385,19 +71261,19 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. a `GtkGrid` + line="1138">a `GtkGrid` a row index + line="1139">a row index a `GtkBaselinePosition` + line="1140">a `GtkBaselinePosition` @@ -69405,10 +71281,9 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. - Sets whether all rows of @grid will have the same height. + line="966">Sets whether all rows of @grid will have the same height. @@ -69417,13 +71292,13 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. a `GtkGrid` + line="968">a `GtkGrid` %TRUE to make rows homogeneous + line="969">%TRUE to make rows homogeneous @@ -69431,10 +71306,9 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. - Sets the amount of space between rows of @grid. + line="1050">Sets the amount of space between rows of @grid. @@ -69443,13 +71317,13 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. a `GtkGrid` + line="1052">a `GtkGrid` the amount of space to insert between rows + line="1053">the amount of space to insert between rows @@ -69460,13 +71334,9 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. setter="set_baseline_row" getter="get_baseline_row" default-value="0"> - - The row to align to the baseline when valign is using baseline alignment. + line="470">The row to align to the baseline when valign is using baseline alignment. setter="set_column_homogeneous" getter="get_column_homogeneous" default-value="FALSE"> - - If %TRUE, the columns are all the same width. + line="460">If %TRUE, the columns are all the same width. setter="set_column_spacing" getter="get_column_spacing" default-value="0"> - - The amount of space between two consecutive columns. + line="440">The amount of space between two consecutive columns. setter="set_row_homogeneous" getter="get_row_homogeneous" default-value="FALSE"> - - If %TRUE, the rows are all the same height. + line="450">If %TRUE, the rows are all the same height. setter="set_row_spacing" getter="get_row_spacing" default-value="0"> - - The amount of space between two consecutive rows. + line="430">The amount of space between two consecutive rows. @@ -69558,8 +71412,7 @@ The default baseline position is %GTK_BASELINE_POSITION_CENTER. glib:type-struct="GridLayoutClass"> `GtkGridLayout` is a layout manager which arranges child widgets in -rows and columns. + line="20">Arranges child widgets in rows and columns. Children have an "attach point" defined by the horizontal and vertical index of the cell they occupy; children can span multiple rows or columns. @@ -69576,34 +71429,33 @@ single row or column, you should consider using `GtkBoxLayout`. Creates a new `GtkGridLayout`. + line="1714">Creates a new `GtkGridLayout`. the newly created `GtkGridLayout` + line="1719">the newly created `GtkGridLayout` - Retrieves the row set with gtk_grid_layout_set_baseline_row(). + line="2019">Retrieves the row set with gtk_grid_layout_set_baseline_row(). the global baseline row + line="2025">the global baseline row a `GtkGridLayout` + line="2021">a `GtkGridLayout` @@ -69611,23 +71463,21 @@ single row or column, you should consider using `GtkBoxLayout`. - Checks whether all columns of @grid should have the same width. + line="1828">Checks whether all columns of @grid should have the same width. %TRUE if the columns are homogeneous, and %FALSE otherwise + line="1834">%TRUE if the columns are homogeneous, and %FALSE otherwise a `GtkGridLayout` + line="1830">a `GtkGridLayout` @@ -69635,22 +71485,21 @@ single row or column, you should consider using `GtkBoxLayout`. - Retrieves the spacing set with gtk_grid_layout_set_column_spacing(). + line="1867">Retrieves the spacing set with gtk_grid_layout_set_column_spacing(). the spacing between consecutive columns + line="1873">the spacing between consecutive columns a `GtkGridLayout` + line="1869">a `GtkGridLayout` @@ -69659,7 +71508,7 @@ single row or column, you should consider using `GtkBoxLayout`. c:identifier="gtk_grid_layout_get_row_baseline_position"> Returns the baseline position of @row. + line="1967">Returns the baseline position of @row. If no value has been set with [method@Gtk.GridLayout.set_row_baseline_position], @@ -69669,20 +71518,20 @@ is returned. the baseline position of @row + line="1979">the baseline position of @row a `GtkGridLayout` + line="1969">a `GtkGridLayout` a row index + line="1970">a row index @@ -69690,22 +71539,21 @@ is returned. - Checks whether all rows of @grid should have the same height. + line="1750">Checks whether all rows of @grid should have the same height. %TRUE if the rows are homogeneous, and %FALSE otherwise + line="1756">%TRUE if the rows are homogeneous, and %FALSE otherwise a `GtkGridLayout` + line="1752">a `GtkGridLayout` @@ -69713,22 +71561,21 @@ is returned. - Retrieves the spacing set with gtk_grid_layout_set_row_spacing(). + line="1789">Retrieves the spacing set with gtk_grid_layout_set_row_spacing(). the spacing between consecutive rows + line="1795">the spacing between consecutive rows a `GtkGridLayout` + line="1791">a `GtkGridLayout` @@ -69736,10 +71583,9 @@ is returned. - Sets which row defines the global baseline for the entire grid. + line="1994">Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the @@ -69752,13 +71598,13 @@ parent of the @grid. a `GtkGridLayout` + line="1996">a `GtkGridLayout` the row index + line="1997">the row index @@ -69766,11 +71612,9 @@ parent of the @grid. - Sets whether all columns of @grid should have the same width. + line="1805">Sets whether all columns of @grid should have the same width. @@ -69779,13 +71623,13 @@ parent of the @grid. a `GtkGridLayout` + line="1807">a `GtkGridLayout` %TRUE to make columns homogeneous + line="1808">%TRUE to make columns homogeneous @@ -69793,10 +71637,9 @@ parent of the @grid. - Sets the amount of space to insert between consecutive columns. + line="1844">Sets the amount of space to insert between consecutive columns. @@ -69805,13 +71648,13 @@ parent of the @grid. a `GtkGridLayout` + line="1846">a `GtkGridLayout` the amount of space between columns, in pixels + line="1847">the amount of space between columns, in pixels @@ -69820,7 +71663,7 @@ parent of the @grid. c:identifier="gtk_grid_layout_set_row_baseline_position"> Sets how the baseline should be positioned on @row of the + line="1940">Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. @@ -69830,19 +71673,19 @@ grid, in case that row is assigned more space than is requested. a `GtkGridLayout` + line="1942">a `GtkGridLayout` a row index + line="1943">a row index a `GtkBaselinePosition` + line="1944">a `GtkBaselinePosition` @@ -69850,10 +71693,9 @@ grid, in case that row is assigned more space than is requested. - Sets whether all rows of @grid should have the same height. + line="1727">Sets whether all rows of @grid should have the same height. @@ -69862,13 +71704,13 @@ grid, in case that row is assigned more space than is requested. a `GtkGridLayout` + line="1729">a `GtkGridLayout` %TRUE to make rows homogeneous + line="1730">%TRUE to make rows homogeneous @@ -69876,10 +71718,9 @@ grid, in case that row is assigned more space than is requested. - Sets the amount of space to insert between consecutive rows. + line="1766">Sets the amount of space to insert between consecutive rows. @@ -69888,13 +71729,13 @@ grid, in case that row is assigned more space than is requested. a `GtkGridLayout` + line="1768">a `GtkGridLayout` the amount of space between rows, in pixels + line="1769">the amount of space between rows, in pixels @@ -69905,13 +71746,9 @@ grid, in case that row is assigned more space than is requested. setter="set_baseline_row" getter="get_baseline_row" default-value="0"> - - The row to align to the baseline, when `GtkWidget:valign` is set + line="1695">The row to align to the baseline, when `GtkWidget:valign` is set to %GTK_ALIGN_BASELINE. @@ -69921,13 +71758,9 @@ to %GTK_ALIGN_BASELINE. setter="set_column_homogeneous" getter="get_column_homogeneous" default-value="FALSE"> - - Whether all the columns in the grid have the same width. + line="1685">Whether all the columns in the grid have the same width. setter="set_column_spacing" getter="get_column_spacing" default-value="0"> - - The amount of space between to consecutive columns. + line="1665">The amount of space between to consecutive columns. setter="set_row_homogeneous" getter="get_row_homogeneous" default-value="FALSE"> - - Whether all the rows in the grid have the same height. + line="1675">Whether all the rows in the grid have the same height. setter="set_row_spacing" getter="get_row_spacing" default-value="0"> - - The amount of space between to consecutive rows. + line="1655">The amount of space between to consecutive rows. @@ -69985,27 +71806,26 @@ to %GTK_ALIGN_BASELINE. glib:type-struct="GridLayoutChildClass"> `GtkLayoutChild` subclass for children in a `GtkGridLayout`. + line="38">`GtkLayoutChild` subclass for children in a `GtkGridLayout`. - Retrieves the column number to which @child attaches its left side. + line="271">Retrieves the column number to which @child attaches its left side. the column number + line="277">the column number a `GtkGridLayoutChild` + line="273">a `GtkGridLayoutChild` @@ -70013,22 +71833,21 @@ to %GTK_ALIGN_BASELINE. - Retrieves the number of columns that @child spans to. + line="310">Retrieves the number of columns that @child spans to. the number of columns + line="316">the number of columns a `GtkGridLayoutChild` + line="312">a `GtkGridLayoutChild` @@ -70036,22 +71855,21 @@ to %GTK_ALIGN_BASELINE. - Retrieves the row number to which @child attaches its top side. + line="232">Retrieves the row number to which @child attaches its top side. the row number + line="238">the row number a `GtkGridLayoutChild` + line="234">a `GtkGridLayoutChild` @@ -70059,22 +71877,21 @@ to %GTK_ALIGN_BASELINE. - Retrieves the number of rows that @child spans to. + line="349">Retrieves the number of rows that @child spans to. the number of row + line="355">the number of row a `GtkGridLayoutChild` + line="351">a `GtkGridLayoutChild` @@ -70082,10 +71899,9 @@ to %GTK_ALIGN_BASELINE. - Sets the column number to attach the left side of @child. + line="248">Sets the column number to attach the left side of @child. @@ -70094,13 +71910,13 @@ to %GTK_ALIGN_BASELINE. a `GtkGridLayoutChild` + line="250">a `GtkGridLayoutChild` the attach point for @child + line="251">the attach point for @child @@ -70108,10 +71924,9 @@ to %GTK_ALIGN_BASELINE. - Sets the number of columns @child spans to. + line="287">Sets the number of columns @child spans to. @@ -70120,13 +71935,13 @@ to %GTK_ALIGN_BASELINE. a `GtkGridLayoutChild` + line="289">a `GtkGridLayoutChild` the span of @child + line="290">the span of @child @@ -70134,10 +71949,9 @@ to %GTK_ALIGN_BASELINE. - Sets the row to place @child in. + line="209">Sets the row to place @child in. @@ -70146,13 +71960,13 @@ to %GTK_ALIGN_BASELINE. a `GtkGridLayoutChild` + line="211">a `GtkGridLayoutChild` the row for @child + line="212">the row for @child @@ -70160,10 +71974,9 @@ to %GTK_ALIGN_BASELINE. - Sets the number of rows @child spans to. + line="326">Sets the number of rows @child spans to. @@ -70172,13 +71985,13 @@ to %GTK_ALIGN_BASELINE. a `GtkGridLayoutChild` + line="328">a `GtkGridLayoutChild` the span of @child + line="329">the span of @child @@ -70189,13 +72002,9 @@ to %GTK_ALIGN_BASELINE. setter="set_column" getter="get_column" default-value="0"> - - The column to place the child in. + line="159">The column to place the child in. setter="set_column_span" getter="get_column_span" default-value="1"> - - The number of columns the child spans to. + line="179">The number of columns the child spans to. setter="set_row" getter="get_row" default-value="0"> - - The row to place the child in. + line="169">The row to place the child in. setter="set_row_span" getter="get_row_span" default-value="1"> - - The number of rows the child spans to. + line="189">The number of rows the child spans to. @@ -70269,7 +72066,7 @@ to %GTK_ALIGN_BASELINE. glib:type-struct="GridViewClass"> `GtkGridView` presents a large dynamic grid of items. + line="44">Presents a large dynamic grid of items. `GtkGridView` uses its factory to generate one child widget for each visible item and shows them in a grid. The orientation of the grid view @@ -70283,6 +72080,13 @@ it is possible to turn on _rubberband selection_, using To learn more about the list widget framework, see the [overview](section-list-widget.html). +# Actions + +`GtkGridView` defines a set of built-in actions: + +- `list.activate-item` activates the item at given position by emitting the + the [signal@Gtk.GridView::activate] signal. + # CSS nodes ``` @@ -70302,8 +72106,8 @@ class. For rubberband selection, a subnode with name `rubberband` is used. # Accessibility -`GtkGridView` uses the %GTK_ACCESSIBLE_ROLE_GRID role, and the items -use the %GTK_ACCESSIBLE_ROLE_GRID_CELL role. +`GtkGridView` uses the [enum@Gtk.AccessibleRole.grid] role, and the items +use the [enum@Gtk.AccessibleRole.grid_cell] role. @@ -70313,7 +72117,7 @@ use the %GTK_ACCESSIBLE_ROLE_GRID_CELL role. Creates a new `GtkGridView` that uses the given @factory for + line="1243">Creates a new `GtkGridView` that uses the given @factory for mapping items to widgets. The function takes ownership of the @@ -70326,7 +72130,7 @@ grid_view = gtk_grid_view_new (create_model (), a new `GtkGridView` using the given @model and @factory + line="1258">a new `GtkGridView` using the given @model and @factory @@ -70336,7 +72140,7 @@ grid_view = gtk_grid_view_new (create_model (), allow-none="1"> the model to use + line="1245">the model to use The factory to populate items with + line="1246">The factory to populate items with @@ -70353,23 +72157,21 @@ grid_view = gtk_grid_view_new (create_model (), - Returns whether rows can be selected by dragging with the mouse. + line="1526">Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled + line="1532">%TRUE if rubberband selection is enabled a `GtkGridView` + line="1528">a `GtkGridView` @@ -70377,22 +72179,21 @@ grid_view = gtk_grid_view_new (create_model (), - Gets the factory that's currently used to populate list items. + line="1323">Gets the factory that's currently used to populate list items. The factory in use + line="1329">The factory in use a `GtkGridView` + line="1325">a `GtkGridView` @@ -70400,22 +72201,21 @@ grid_view = gtk_grid_view_new (create_model (), - Gets the maximum number of columns that the grid will use. + line="1361">Gets the maximum number of columns that the grid will use. The maximum number of columns + line="1367">The maximum number of columns a `GtkGridView` + line="1363">a `GtkGridView` @@ -70423,22 +72223,21 @@ grid_view = gtk_grid_view_new (create_model (), - Gets the minimum number of columns that the grid will use. + line="1410">Gets the minimum number of columns that the grid will use. The minimum number of columns + line="1416">The minimum number of columns a `GtkGridView` + line="1412">a `GtkGridView` @@ -70446,22 +72245,21 @@ grid_view = gtk_grid_view_new (create_model (), - Gets the model that's currently used to read the items displayed. + line="1281">Gets the model that's currently used to read the items displayed. The model in use + line="1287">The model in use a `GtkGridView` + line="1283">a `GtkGridView` @@ -70469,24 +72267,22 @@ grid_view = gtk_grid_view_new (create_model (), - Returns whether items will be activated on single click and + line="1488">Returns whether items will be activated on single click and selected on hover. %TRUE if items are activated on single click + line="1495">%TRUE if items are activated on single click a `GtkGridView` + line="1490">a `GtkGridView` @@ -70495,22 +72291,21 @@ selected on hover. c:identifier="gtk_grid_view_get_tab_behavior" glib:get-property="tab-behavior" version="4.12"> - Gets the behavior set for the <kbd>Tab</kbd> key. + line="1565">Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key + line="1571">The behavior of the <kbd>Tab</kbd> key a `GtkGridView` + line="1567">a `GtkGridView` @@ -70520,7 +72315,7 @@ selected on hover. version="4.12"> Scrolls to the item at the given position and performs the actions + line="1583">Scrolls to the item at the given position and performs the actions specified in @flags. This function works no matter if the gridview is shown or focused. @@ -70533,19 +72328,20 @@ If it isn't, then the changes will take effect once that happens. The gridview to scroll in + line="1585">The gridview to scroll in position of the item + line="1586">position of the item. Must be less than the number of + items in the view. actions to perform + line="1588">actions to perform allow-none="1"> details of how to perform + line="1589">details of how to perform the scroll operation or %NULL to scroll into view @@ -70563,11 +72359,9 @@ If it isn't, then the changes will take effect once that happens. - Sets whether selections can be changed by dragging with the mouse. + line="1505">Sets whether selections can be changed by dragging with the mouse. @@ -70576,13 +72370,13 @@ If it isn't, then the changes will take effect once that happens. a `GtkGridView` + line="1507">a `GtkGridView` %TRUE to enable rubberband selection + line="1508">%TRUE to enable rubberband selection @@ -70590,10 +72384,9 @@ If it isn't, then the changes will take effect once that happens. - Sets the `GtkListItemFactory` to use for populating list items. + line="1339">Sets the `GtkListItemFactory` to use for populating list items. @@ -70602,7 +72395,7 @@ If it isn't, then the changes will take effect once that happens. a `GtkGridView` + line="1341">a `GtkGridView` allow-none="1"> the factory to use + line="1342">the factory to use @@ -70619,10 +72412,9 @@ If it isn't, then the changes will take effect once that happens. - Sets the maximum number of columns to use. + line="1377">Sets the maximum number of columns to use. This number must be at least 1. @@ -70636,13 +72428,13 @@ If @max_columns is smaller than the minimum set via a `GtkGridView` + line="1379">a `GtkGridView` The maximum number of columns + line="1380">The maximum number of columns @@ -70650,10 +72442,9 @@ If @max_columns is smaller than the minimum set via - Sets the minimum number of columns to use. + line="1426">Sets the minimum number of columns to use. This number must be at least 1. @@ -70667,13 +72458,13 @@ If @min_columns is smaller than the minimum set via a `GtkGridView` + line="1428">a `GtkGridView` The minimum number of columns + line="1429">The minimum number of columns @@ -70681,10 +72472,9 @@ If @min_columns is smaller than the minimum set via - Sets the model to use. + line="1297">Sets the model to use. This must be a [iface@Gtk.SelectionModel]. @@ -70695,7 +72485,7 @@ This must be a [iface@Gtk.SelectionModel]. a `GtkGridView` + line="1299">a `GtkGridView` allow-none="1"> the model to use + line="1300">the model to use @@ -70712,11 +72502,9 @@ This must be a [iface@Gtk.SelectionModel]. - Sets whether items should be activated on single click and + line="1455">Sets whether items should be activated on single click and selected on hover. @@ -70726,13 +72514,13 @@ selected on hover. a `GtkGridView` + line="1457">a `GtkGridView` %TRUE to activate items on single click + line="1458">%TRUE to activate items on single click @@ -70741,10 +72529,9 @@ selected on hover. c:identifier="gtk_grid_view_set_tab_behavior" glib:set-property="tab-behavior" version="4.12"> - Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + line="1542">Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. @@ -70753,13 +72540,13 @@ selected on hover. a `GtkGridView` + line="1544">a `GtkGridView` The desired tab behavior + line="1545">The desired tab behavior @@ -70770,13 +72557,9 @@ selected on hover. setter="set_enable_rubberband" getter="get_enable_rubberband" default-value="FALSE"> - - Allow rubberband selection. + line="1105">Allow rubberband selection. transfer-ownership="none" setter="set_factory" getter="get_factory"> - - Factory for populating list items. + line="1115">Factory for populating list items. + +The factory must be for configuring [class@Gtk.ListItem] objects. setter="set_max_columns" getter="get_max_columns" default-value="7"> - - Maximum number of columns per row. + line="1128">Maximum number of columns per row. If this number is smaller than [property@Gtk.GridView:min-columns], that value is used instead. @@ -70817,13 +72594,9 @@ that value is used instead. setter="set_min_columns" getter="get_min_columns" default-value="1"> - - Minimum number of columns per row. + line="1141">Minimum number of columns per row. transfer-ownership="none" setter="set_model" getter="get_model"> - - Model for the items displayed. + line="1151">Model for the items displayed. setter="set_single_click_activate" getter="get_single_click_activate" default-value="FALSE"> - - Activate rows on single click and select them on hover. + line="1161">Activate rows on single click and select them on hover. setter="set_tab_behavior" getter="get_tab_behavior" default-value="GTK_LIST_TAB_ALL"> - - Behavior of the <kbd>Tab</kbd> key + line="1171">Behavior of the <kbd>Tab</kbd> key Emitted when a cell has been activated by the user, + line="1186">Emitted when a cell has been activated by the user, usually via activating the GtkGridView|list.activate-item action. This allows for a convenient way to handle activation in a gridview. @@ -70887,7 +72648,7 @@ this signal. position of item to activate + line="1189">position of item to activate @@ -70917,9 +72678,12 @@ this signal. glib:get-type="gtk_header_bar_get_type"> `GtkHeaderBar` is a widget for creating custom title bars for windows. + line="38">Creates a custom titlebar for a window. -![An example GtkHeaderBar](headerbar.png) +<picture> + <source srcset="headerbar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkHeaderBar" src="headerbar.png"> +</picture> `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows children to be placed at the start or the end. In addition, it allows @@ -70987,42 +72751,40 @@ Each of the boxes contains a `windowcontrols` subnode, see # Accessibility -`GtkHeaderBar` uses the %GTK_ACCESSIBLE_ROLE_GROUP role. +`GtkHeaderBar` uses the [enum@Gtk.AccessibleRole.group] role. Creates a new `GtkHeaderBar` widget. + line="742">Creates a new `GtkHeaderBar` widget. a new `GtkHeaderBar` + line="747">a new `GtkHeaderBar` - Gets the decoration layout of the `GtkHeaderBar`. + line="848">Gets the decoration layout of the header bar. the decoration layout + line="854">the decoration layout a `GtkHeaderBar` + line="850">a header bar @@ -71030,24 +72792,22 @@ Each of the boxes contains a `windowcontrols` subnode, see - Returns whether this header bar shows the standard window + line="755">Returns whether this header bar shows the standard window title buttons. %TRUE if title buttons are shown + line="762">true if title buttons are shown a `GtkHeaderBar` + line="757">a header bar @@ -71057,21 +72817,45 @@ title buttons. glib:get-property="title-widget"> Retrieves the title widget of the header. + line="343">Retrieves the title widget of the header bar. See [method@Gtk.HeaderBar.set_title_widget]. the title widget of the header + line="351">the title widget a `GtkHeaderBar` + line="345">a header bar + + + + + + Returns whether this header bar shows platform +native window controls. + + + true if native window controls are shown + + + + + a header bar @@ -71079,8 +72863,7 @@ See [method@Gtk.HeaderBar.set_title_widget]. Adds @child to @bar, packed with reference to the -end of the @bar. + line="728">Adds a child to the header bar, packed with reference to the end. @@ -71089,13 +72872,13 @@ end of the @bar. A `GtkHeaderBar` + line="730">A header bar the `GtkWidget` to be added to @bar + line="731">the widget to be added to @bar @@ -71103,8 +72886,7 @@ end of the @bar. Adds @child to @bar, packed with reference to the -start of the @bar. + line="714">Adds a child to the header bar, packed with reference to the start. @@ -71113,13 +72895,13 @@ start of the @bar. A `GtkHeaderBar` + line="716">A header bar the `GtkWidget` to be added to @bar + line="717">the widget to be added to @bar @@ -71127,7 +72909,7 @@ start of the @bar. Removes a child from the `GtkHeaderBar`. + line="495">Removes a child from the header bar. The child must have been added with [method@Gtk.HeaderBar.pack_start], @@ -71141,13 +72923,13 @@ The child must have been added with a `GtkHeaderBar` + line="497">a header bar the child to remove + line="498">the child to remove @@ -71155,11 +72937,9 @@ The child must have been added with - Sets the decoration layout for this header bar. + line="813">Sets the decoration layout for this header bar. This property overrides the [property@Gtk.Settings:gtk-decoration-layout] setting. @@ -71184,7 +72964,7 @@ on the left, and minimize, maximize and close buttons on the right. a `GtkHeaderBar` + line="815">a header bar allow-none="1"> a decoration layout, or %NULL to unset the layout + line="816">a decoration layout @@ -71201,11 +72981,9 @@ on the left, and minimize, maximize and close buttons on the right. - Sets whether this header bar shows the standard window + line="772">Sets whether this header bar shows the standard window title buttons. @@ -71215,13 +72993,13 @@ title buttons. a `GtkHeaderBar` + line="774">a header bar %TRUE to show standard title buttons + line="775">true to show standard title buttons @@ -71231,16 +73009,16 @@ title buttons. glib:set-property="title-widget"> Sets the title for the `GtkHeaderBar`. + line="295">Sets the title for the header bar. -When set to %NULL, the headerbar will display the title of +When set to `NULL`, the headerbar will display the title of the window it is contained in. The title should help a user identify the current view. To achieve the same style as the builtin title, use the “title” style class. -You should set the title widget to %NULL, for the window +You should set the title widget to `NULL`, for the window title label to be visible again. @@ -71250,7 +73028,7 @@ title label to be visible again. a `GtkHeaderBar` + line="297">a header bar allow-none="1"> a widget to use for a title + line="298">a widget to use for a title + + Sets whether this header bar shows native window controls. + +This option shows the "stoplight" buttons on macOS. +For Linux, this option has no effect. + +See also [Using GTK on Apple macOS](osx.html?native-window-controls). + + + + + + + a header bar + + + + true to show native window controls + + + + - - The decoration layout for buttons. + line="610">The decoration layout for buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. @@ -71288,13 +73093,9 @@ If this property is not set, the setter="set_show_title_buttons" getter="get_show_title_buttons" default-value="TRUE"> - - Whether to show title buttons like close, minimize, maximize. + line="595">Whether to show title buttons like close, minimize, maximize. Which buttons are actually shown and where is determined by the [property@Gtk.HeaderBar:decoration-layout] property, @@ -71307,8 +73108,30 @@ be shown if the window can't be closed). transfer-ownership="none" setter="set_title_widget" getter="get_title_widget"> + The title widget to display. + + Whether to show platform native close/minimize/maximize buttons. + +For macOS, the [property@Gtk.HeaderBar:decoration-layout] property +can be used to enable/disable controls. + +On Linux, this option has no effect. + +See also [Using GTK on Apple macOS](osx.html?native-window-controls). + + glib:type-struct="IMContextClass"> `GtkIMContext` defines the interface for GTK input methods. + line="27">The interface for GTK input methods. `GtkIMContext` is used by GTK text input widgets like `GtkText` to map from key events to Unicode character strings. @@ -71383,7 +73206,7 @@ provides a `GIOExtension` for the extension point named "gtk-im-module". To connect a widget to the users preferred input method, you should use [class@Gtk.IMMulticontext]. - + @@ -71395,7 +73218,24 @@ To connect a widget to the users preferred input method, you should use + + + + + + + + + + + + + + + Default handler of the [signal@Gtk.IMContext::commit] signal. @@ -71412,7 +73252,7 @@ To connect a widget to the users preferred input method, you should use Asks the widget that the input context is attached to delete + line="914">Asks the widget that the input context is attached to delete characters around the cursor position by emitting the `::delete_surrounding` signal. @@ -71433,27 +73273,27 @@ It is not useful for applications. %TRUE if the signal was handled. + line="939">%TRUE if the signal was handled. a `GtkIMContext` + line="916">a `GtkIMContext` offset from cursor position in chars; + line="917">offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. + line="919">number of characters to delete. @@ -71461,7 +73301,7 @@ It is not useful for applications. Allow an input method to internally handle key press and release + line="509">Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing @@ -71470,20 +73310,20 @@ should be done for this key event. %TRUE if the input method handled the key event. + line="520">%TRUE if the input method handled the key event. a `GtkIMContext` + line="511">a `GtkIMContext` the key event + line="512">the key event @@ -71491,7 +73331,7 @@ should be done for this key event. Notify the input method that the widget to which this + line="620">Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed @@ -71504,7 +73344,7 @@ feedback to reflect this change. a `GtkIMContext` + line="622">a `GtkIMContext` @@ -71512,7 +73352,7 @@ feedback to reflect this change. Notify the input method that the widget to which this + line="642">Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed @@ -71525,7 +73365,7 @@ feedback or reset the contexts state to reflect this change. a `GtkIMContext` + line="644">a `GtkIMContext` @@ -71533,7 +73373,7 @@ feedback or reset the contexts state to reflect this change. Retrieve the current preedit string for the input context, + line="478">Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. @@ -71545,7 +73385,7 @@ This string should be displayed inserted at the insertion point. a `GtkIMContext` + line="480">a `GtkIMContext` transfer-ownership="full"> location to store the retrieved + line="481">location to store the retrieved string. The string retrieved must be freed with g_free(). @@ -71564,7 +73404,7 @@ This string should be displayed inserted at the insertion point. transfer-ownership="full"> location to store the retrieved + line="483">location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. @@ -71575,7 +73415,7 @@ This string should be displayed inserted at the insertion point. transfer-ownership="full"> location to store position of cursor + line="486">location to store position of cursor (in characters) within the preedit string. @@ -71587,7 +73427,7 @@ This string should be displayed inserted at the insertion point. deprecated-version="4.2"> Retrieves context around the insertion point. + line="802">Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai @@ -71607,7 +73447,7 @@ function without context. `TRUE` if surrounding text was provided; in this case + line="828">`TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. @@ -71615,7 +73455,7 @@ function without context. a `GtkIMContext` + line="804">a `GtkIMContext` transfer-ownership="full"> location to store a UTF-8 encoded + line="805">location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). @@ -71636,7 +73476,7 @@ function without context. transfer-ownership="full"> location to store byte index of the insertion + line="809">location to store byte index of the insertion cursor within @text. @@ -71647,7 +73487,7 @@ function without context. version="4.2"> Retrieves context around the insertion point. + line="844">Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such @@ -71666,7 +73506,7 @@ function without context. `TRUE` if surrounding text was provided; in this case + line="872">`TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. @@ -71674,7 +73514,7 @@ function without context. a `GtkIMContext` + line="846">a `GtkIMContext` transfer-ownership="full"> location to store a UTF-8 encoded + line="847">location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). @@ -71695,7 +73535,7 @@ function without context. transfer-ownership="full"> location to store byte index of the insertion + line="851">location to store byte index of the insertion cursor within @text. @@ -71705,13 +73545,17 @@ function without context. transfer-ownership="full"> location to store byte index of the selection + line="853">location to store byte index of the selection bound within @text + Default handler of the [signal@Gtk.IMContext::preedit-changed] + signal. @@ -71723,6 +73567,9 @@ function without context. + Default handler of the [signal@Gtk.IMContext::preedit-end] signal. @@ -71734,6 +73581,9 @@ function without context. + Default handler of the [signal@Gtk.IMContext::preedit-start] signal. @@ -71747,7 +73597,7 @@ function without context. Notify the input method that a change such as a change in cursor + line="664">Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. @@ -71759,12 +73609,16 @@ This will typically cause the input method to clear the preedit state. a `GtkIMContext` + line="666">a `GtkIMContext` + Default handler of the + [signal@Gtk.IMContext::retrieve-surrounding] signal. @@ -71778,7 +73632,7 @@ This will typically cause the input method to clear the preedit state. Set the client widget for the input context. + line="453">Set the client widget for the input context. This is the `GtkWidget` holding the input focus. This widget is used in order to correctly position status windows, and may @@ -71791,7 +73645,7 @@ also be used for purposes internal to the input method. a `GtkIMContext` + line="455">a `GtkIMContext` allow-none="1"> the client widget. This may be %NULL to indicate + line="456">the client widget. This may be %NULL to indicate that the previous client widget no longer exists. @@ -71809,7 +73663,7 @@ also be used for purposes internal to the input method. Notify the input method that a change in cursor + line="686">Notify the input method that a change in cursor position has been made. The location is relative to the client widget. @@ -71821,13 +73675,13 @@ The location is relative to the client widget. a `GtkIMContext` + line="688">a `GtkIMContext` new location + line="689">new location @@ -71838,7 +73692,7 @@ The location is relative to the client widget. deprecated-version="4.2"> Sets surrounding context around the insertion point and preedit + line="734">Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the @@ -71853,26 +73707,26 @@ likely have no effect if called at other times. a `GtkIMContext` + line="736">a `GtkIMContext` text surrounding the insertion point, as UTF-8. + line="737">text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated + line="739">the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. + line="740">the byte index of the insertion cursor within @text. @@ -71882,7 +73736,7 @@ likely have no effect if called at other times. version="4.2"> Sets surrounding context around the insertion point and preedit + line="760">Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely have no effect if called at other times. @@ -71894,32 +73748,32 @@ have no effect if called at other times. a `GtkIMContext` + line="762">a `GtkIMContext` text surrounding the insertion point, as UTF-8. + line="763">text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated + line="765">the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text + line="766">the byte index of the insertion cursor within @text the byte index of the selection bound within @text + line="767">the byte index of the selection bound within @text @@ -71927,7 +73781,7 @@ have no effect if called at other times. Sets whether the IM context should use the preedit string + line="709">Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is %FALSE (default is %TRUE), then the IM context @@ -71941,22 +73795,57 @@ it in a child of the root window. a `GtkIMContext` + line="711">a `GtkIMContext` whether the IM context should use the preedit string. + line="712">whether the IM context should use the preedit string. + + Requests the platform to show an on-screen keyboard for user input. + +This method will return %TRUE if this request was actually performed +to the platform, other environmental factors may result in an on-screen +keyboard effectively not showing up. + + + %TRUE if an on-screen keyboard could be requested to the platform. + + + + + a `GtkIMContext` + + + + a [class@Gdk.Event] + + + + Asks the widget that the input context is attached to delete + line="914">Asks the widget that the input context is attached to delete characters around the cursor position by emitting the `::delete_surrounding` signal. @@ -71973,31 +73862,31 @@ have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make substitutions in the existing text in response to new input. It is not useful for applications. - + %TRUE if the signal was handled. + line="939">%TRUE if the signal was handled. a `GtkIMContext` + line="916">a `GtkIMContext` offset from cursor position in chars; + line="917">offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. + line="919">number of characters to delete. @@ -72005,63 +73894,63 @@ It is not useful for applications. Allow an input method to forward key press and release events + line="535">Allow an input method to forward key press and release events to another input method without necessarily having a `GdkEvent` available. - + %TRUE if the input method handled the key event. + line="550">%TRUE if the input method handled the key event. a `GtkIMContext` + line="537">a `GtkIMContext` whether to forward a key press or release event + line="538">whether to forward a key press or release event the surface the event is for + line="539">the surface the event is for the device that the event is for + line="540">the device that the event is for the timestamp for the event + line="541">the timestamp for the event the keycode for the event + line="542">the keycode for the event modifier state for the event + line="543">modifier state for the event the active keyboard group for the event + line="544">the active keyboard group for the event @@ -72070,29 +73959,29 @@ available. c:identifier="gtk_im_context_filter_keypress"> Allow an input method to internally handle key press and release + line="509">Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. - + %TRUE if the input method handled the key event. + line="520">%TRUE if the input method handled the key event. a `GtkIMContext` + line="511">a `GtkIMContext` the key event + line="512">the key event @@ -72100,12 +73989,12 @@ should be done for this key event. Notify the input method that the widget to which this + line="620">Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. - + @@ -72113,7 +74002,7 @@ feedback to reflect this change. a `GtkIMContext` + line="622">a `GtkIMContext` @@ -72121,12 +74010,12 @@ feedback to reflect this change. Notify the input method that the widget to which this + line="642">Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. - + @@ -72134,7 +74023,7 @@ feedback or reset the contexts state to reflect this change. a `GtkIMContext` + line="644">a `GtkIMContext` @@ -72143,11 +74032,11 @@ feedback or reset the contexts state to reflect this change. c:identifier="gtk_im_context_get_preedit_string"> Retrieve the current preedit string for the input context, + line="478">Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. - + @@ -72155,7 +74044,7 @@ This string should be displayed inserted at the insertion point. a `GtkIMContext` + line="480">a `GtkIMContext` transfer-ownership="full"> location to store the retrieved + line="481">location to store the retrieved string. The string retrieved must be freed with g_free(). @@ -72174,7 +74063,7 @@ This string should be displayed inserted at the insertion point. transfer-ownership="full"> location to store the retrieved + line="483">location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. @@ -72185,7 +74074,7 @@ This string should be displayed inserted at the insertion point. transfer-ownership="full"> location to store position of cursor + line="486">location to store position of cursor (in characters) within the preedit string. @@ -72197,7 +74086,7 @@ This string should be displayed inserted at the insertion point. deprecated-version="4.2"> Retrieves context around the insertion point. + line="802">Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai @@ -72213,11 +74102,11 @@ Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. Use [method@Gtk.IMContext.get_surrounding_with_selection] instead. - + `TRUE` if surrounding text was provided; in this case + line="828">`TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. @@ -72225,7 +74114,7 @@ function without context. a `GtkIMContext` + line="804">a `GtkIMContext` transfer-ownership="full"> location to store a UTF-8 encoded + line="805">location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). @@ -72246,7 +74135,7 @@ function without context. transfer-ownership="full"> location to store byte index of the insertion + line="809">location to store byte index of the insertion cursor within @text. @@ -72257,7 +74146,7 @@ function without context. version="4.2"> Retrieves context around the insertion point. + line="844">Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such @@ -72272,11 +74161,11 @@ is available, up to an entire paragraph, by calling Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. - + `TRUE` if surrounding text was provided; in this case + line="872">`TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. @@ -72284,7 +74173,7 @@ function without context. a `GtkIMContext` + line="846">a `GtkIMContext` transfer-ownership="full"> location to store a UTF-8 encoded + line="847">location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). @@ -72305,7 +74194,7 @@ function without context. transfer-ownership="full"> location to store byte index of the insertion + line="851">location to store byte index of the insertion cursor within @text. @@ -72315,7 +74204,7 @@ function without context. transfer-ownership="full"> location to store byte index of the selection + line="853">location to store byte index of the selection bound within @text @@ -72324,11 +74213,11 @@ function without context. Notify the input method that a change such as a change in cursor + line="664">Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. - + @@ -72336,7 +74225,7 @@ This will typically cause the input method to clear the preedit state. a `GtkIMContext` + line="666">a `GtkIMContext` @@ -72345,12 +74234,12 @@ This will typically cause the input method to clear the preedit state. c:identifier="gtk_im_context_set_client_widget"> Set the client widget for the input context. + line="453">Set the client widget for the input context. This is the `GtkWidget` holding the input focus. This widget is used in order to correctly position status windows, and may also be used for purposes internal to the input method. - + @@ -72358,7 +74247,7 @@ also be used for purposes internal to the input method. a `GtkIMContext` + line="455">a `GtkIMContext` allow-none="1"> the client widget. This may be %NULL to indicate + line="456">the client widget. This may be %NULL to indicate that the previous client widget no longer exists. @@ -72377,11 +74266,11 @@ also be used for purposes internal to the input method. c:identifier="gtk_im_context_set_cursor_location"> Notify the input method that a change in cursor + line="686">Notify the input method that a change in cursor position has been made. The location is relative to the client widget. - + @@ -72389,13 +74278,13 @@ The location is relative to the client widget. a `GtkIMContext` + line="688">a `GtkIMContext` new location + line="689">new location @@ -72406,14 +74295,14 @@ The location is relative to the client widget. deprecated-version="4.2"> Sets surrounding context around the insertion point and preedit + line="734">Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal, and will likely have no effect if called at other times. Use [method@Gtk.IMContext.set_surrounding_with_selection] instead - + @@ -72421,26 +74310,26 @@ likely have no effect if called at other times. a `GtkIMContext` + line="736">a `GtkIMContext` text surrounding the insertion point, as UTF-8. + line="737">text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated + line="739">the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. + line="740">the byte index of the insertion cursor within @text. @@ -72450,11 +74339,11 @@ likely have no effect if called at other times. version="4.2"> Sets surrounding context around the insertion point and preedit + line="760">Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely have no effect if called at other times. - + @@ -72462,32 +74351,32 @@ have no effect if called at other times. a `GtkIMContext` + line="762">a `GtkIMContext` text surrounding the insertion point, as UTF-8. + line="763">text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated + line="765">the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text + line="766">the byte index of the insertion cursor within @text the byte index of the selection bound within @text + line="767">the byte index of the selection bound within @text @@ -72496,13 +74385,13 @@ have no effect if called at other times. c:identifier="gtk_im_context_set_use_preedit"> Sets whether the IM context should use the preedit string + line="709">Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is %FALSE (default is %TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. - + @@ -72510,13 +74399,13 @@ it in a child of the root window. a `GtkIMContext` + line="711">a `GtkIMContext` whether the IM context should use the preedit string. + line="712">whether the IM context should use the preedit string. @@ -72527,7 +74416,7 @@ it in a child of the root window. default-value="GTK_INPUT_HINT_NONE"> Additional hints that allow input methods to fine-tune + line="341">Additional hints that allow input methods to fine-tune their behaviour. @@ -72537,7 +74426,7 @@ their behaviour. default-value="GTK_INPUT_PURPOSE_FREE_FORM"> The purpose of the text field that the `GtkIMContext is connected to. + line="327">The purpose of the text field that the `GtkIMContext is connected to. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. @@ -72549,7 +74438,7 @@ methods to adjust their behaviour. The ::commit signal is emitted when a complete input sequence + line="252">The ::commit signal is emitted when a complete input sequence has been entered by the user. If the commit comes after a preediting sequence, the @@ -72564,7 +74453,7 @@ the final result of preediting. the completed character(s) entered by the user + line="255">the completed character(s) entered by the user @@ -72572,19 +74461,19 @@ the final result of preediting. The ::delete-surrounding signal is emitted when the input method + line="300">The ::delete-surrounding signal is emitted when the input method needs to delete all or part of the context surrounding the cursor. %TRUE if the signal was handled. + line="311">%TRUE if the signal was handled. the character offset from the cursor position of the text + line="303">the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor. @@ -72592,7 +74481,7 @@ needs to delete all or part of the context surrounding the cursor. the number of characters to be deleted + line="306">the number of characters to be deleted @@ -72600,7 +74489,7 @@ needs to delete all or part of the context surrounding the cursor. The ::preedit-changed signal is emitted whenever the preedit sequence + line="233">The ::preedit-changed signal is emitted whenever the preedit sequence currently being entered has changed. It is also emitted at the end of a preedit sequence, in which case @@ -72612,7 +74501,7 @@ It is also emitted at the end of a preedit sequence, in which case The ::preedit-end signal is emitted when a preediting sequence + line="217">The ::preedit-end signal is emitted when a preediting sequence has been completed or canceled. @@ -72621,7 +74510,7 @@ has been completed or canceled. The ::preedit-start signal is emitted when a new preediting sequence + line="201">The ::preedit-start signal is emitted when a new preediting sequence starts. @@ -72630,7 +74519,7 @@ starts. The ::retrieve-surrounding signal is emitted when the input method + line="276">The ::retrieve-surrounding signal is emitted when the input method requires the context surrounding the cursor. The callback should set the input method surrounding context by @@ -72638,7 +74527,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. %TRUE if the signal was handled. + line="286">%TRUE if the signal was handled. @@ -72646,11 +74535,14 @@ calling the [method@Gtk.IMContext.set_surrounding] method. - + + Default handler of the [signal@Gtk.IMContext::preedit-start] signal. @@ -72664,6 +74556,9 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Default handler of the [signal@Gtk.IMContext::preedit-end] signal. @@ -72677,6 +74572,10 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Default handler of the [signal@Gtk.IMContext::preedit-changed] + signal. @@ -72690,6 +74589,9 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Default handler of the [signal@Gtk.IMContext::commit] signal. @@ -72706,6 +74608,10 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Default handler of the + [signal@Gtk.IMContext::retrieve-surrounding] signal. @@ -72719,38 +74625,48 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Default handler of the + [signal@Gtk.IMContext::delete-surrounding] signal. %TRUE if the signal was handled. + line="939">%TRUE if the signal was handled. a `GtkIMContext` + line="916">a `GtkIMContext` offset from cursor position in chars; + line="917">offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. + line="919">number of characters to delete. + Called via [method@Gtk.IMContext.set_client_widget] when + the input window where the entered text will appear changes. Override this + to keep track of the current input window, for instance for the purpose of + positioning a status display of your input method. @@ -72760,7 +74676,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="455">a `GtkIMContext` allow-none="1"> the client widget. This may be %NULL to indicate + line="456">the client widget. This may be %NULL to indicate that the previous client widget no longer exists. @@ -72777,6 +74693,13 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Called via [method@Gtk.IMContext.get_preedit_string] + to retrieve the text currently being preedited for display at the cursor + position. Any input method which composes complex characters or any + other compositions from multiple sequential key presses should override + this method to provide feedback. @@ -72786,7 +74709,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="480">a `GtkIMContext` transfer-ownership="full"> location to store the retrieved + line="481">location to store the retrieved string. The string retrieved must be freed with g_free(). @@ -72805,7 +74728,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. transfer-ownership="full"> location to store the retrieved + line="483">location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. @@ -72816,7 +74739,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. transfer-ownership="full"> location to store position of cursor + line="486">location to store position of cursor (in characters) within the preedit string. @@ -72824,31 +74747,47 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Called via [method@Gtk.IMContext.filter_keypress] on every + key press or release event. Every non-trivial input method needs to + override this in order to implement the mapping from key events to text. + A return value of %TRUE indicates to the caller that the event was + consumed by the input method. In that case, the [signal@Gtk.IMContext::commit] + signal should be emitted upon completion of a key sequence to pass the + resulting text back to the input widget. Alternatively, %FALSE may be + returned to indicate that the event wasn’t handled by the input method. + If a builtin mapping exists for the key, it is used to produce a + character. %TRUE if the input method handled the key event. + line="520">%TRUE if the input method handled the key event. a `GtkIMContext` + line="511">a `GtkIMContext` the key event + line="512">the key event + Called via [method@Gtk.IMContext.focus_in] when the input widget + has gained focus. May be overridden to keep track of the current focus. @@ -72858,13 +74797,17 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="622">a `GtkIMContext` + Called via [method@Gtk.IMContext.focus_out] when the input widget + has lost focus. May be overridden to keep track of the current focus. @@ -72874,13 +74817,18 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="644">a `GtkIMContext` + Called via [method@Gtk.IMContext.reset] to signal a change such as a + change in cursor position. An input method that implements preediting + should override this method to clear the preedit state on reset. @@ -72890,13 +74838,19 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="666">a `GtkIMContext` + Called via [method@Gtk.IMContext.set_cursor_location] + to inform the input method of the current cursor location relative to + the client window. May be overridden to implement the display of popup + windows at the cursor position. @@ -72906,19 +74860,24 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="688">a `GtkIMContext` new location + line="689">new location + Called via [method@Gtk.IMContext.set_use_preedit] to control + the use of the preedit string. Override this to display feedback by some + other means if turned off. @@ -72928,19 +74887,27 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="711">a `GtkIMContext` whether the IM context should use the preedit string. + line="712">whether the IM context should use the preedit string. + Called via [method@Gtk.IMContext.set_surrounding] in + response to [signal@Gtk.IMContext::retrieve-surrounding] signal to update + the input method’s idea of the context around the cursor. It is not necessary + to override this method even with input methods which implement + context-dependent behavior. The base implementation is sufficient for + [method@Gtk.IMContext.get_surrounding] to work. @@ -72950,38 +74917,46 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="736">a `GtkIMContext` text surrounding the insertion point, as UTF-8. + line="737">text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated + line="739">the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. + line="740">the byte index of the insertion cursor within @text. + Called via [method@Gtk.IMContext.get_surrounding] to update + the context around the cursor location. It is not necessary to override this + method even with input methods which implement context-dependent behavior. + The base implementation emits [signal@Gtk.IMContext::retrieve-surrounding] + and records the context received by the subsequent invocation of + [vfunc@Gtk.IMContext.get_surrounding]. `TRUE` if surrounding text was provided; in this case + line="828">`TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. @@ -72989,7 +74964,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="804">a `GtkIMContext` transfer-ownership="full"> location to store a UTF-8 encoded + line="805">location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). @@ -73010,7 +74985,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. transfer-ownership="full"> location to store byte index of the insertion + line="809">location to store byte index of the insertion cursor within @text. @@ -73018,6 +74993,15 @@ calling the [method@Gtk.IMContext.set_surrounding] method. + Called via + [method@Gtk.IMContext.set_surrounding_with_selection] in response to the + [signal@Gtk.IMContext::retrieve-surrounding] signal to update the input + method’s idea of the context around the cursor. It is not necessary to + override this method even with input methods which implement + context-dependent behavior. The base implementation is sufficient for + [method@Gtk.IMContext.get_surrounding] to work. @@ -73027,44 +75011,53 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="762">a `GtkIMContext` text surrounding the insertion point, as UTF-8. + line="763">text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated + line="765">the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text + line="766">the byte index of the insertion cursor within @text the byte index of the selection bound within @text + line="767">the byte index of the selection bound within @text + Called via + [method@Gtk.IMContext.get_surrounding_with_selection] to update the + context around the cursor location. It is not necessary to override + this method even with input methods which implement context-dependent + behavior. The base implementation emits + [signal@Gtk.IMContext::retrieve-surrounding] and records the context + received by the subsequent invocation of [vfunc@Gtk.IMContext.get_surrounding]. `TRUE` if surrounding text was provided; in this case + line="872">`TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. @@ -73072,7 +75065,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. a `GtkIMContext` + line="846">a `GtkIMContext` transfer-ownership="full"> location to store a UTF-8 encoded + line="847">location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). @@ -73093,7 +75086,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. transfer-ownership="full"> location to store byte index of the insertion + line="851">location to store byte index of the insertion cursor within @text. @@ -73103,7 +75096,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. transfer-ownership="full"> location to store byte index of the selection + line="853">location to store byte index of the selection bound within @text @@ -73123,17 +75116,25 @@ calling the [method@Gtk.IMContext.set_surrounding] method. - - - + + + - + + + + + + + + + - + @@ -73141,7 +75142,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. - + @@ -73149,7 +75150,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. - + @@ -73165,7 +75166,7 @@ calling the [method@Gtk.IMContext.set_surrounding] method. glib:type-struct="IMContextSimpleClass"> `GtkIMContextSimple` is an input method supporting table-based input methods. + line="39">Supports compose sequences, dead keys and numeric Unicode input. ## Compose sequences @@ -73203,12 +75204,12 @@ yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ. yields U+00E! LATIN SMALL LETTER_A WITH ACUTE, i.e. á. Note that this depends on the keyboard layout including dead keys. - + Creates a new `GtkIMContextSimple`. - + Adds an additional table from the X11 compose file. - + line="1315">Adds an additional table from the X11 compose file. + @@ -73229,13 +75230,13 @@ yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ. A `GtkIMContextSimple` + line="1317">A `GtkIMContextSimple` The path of compose file + line="1318">The path of compose file @@ -73247,7 +75248,7 @@ yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ. deprecated-version="4.4"> Adds an additional table to search to the input context. + line="1285">Adds an additional table to search to the input context. Each row of the table consists of @max_seq_len key symbols followed by two #guint16 interpreted as the high and low words of a #gunicode value. Tables are searched starting @@ -73257,7 +75258,7 @@ The table must be sorted in dictionary order on the numeric value of the key symbol fields. (Values beyond the length of the sequence should be zero.) Use gtk_im_context_simple_add_compose_file() - + @@ -73265,13 +75266,13 @@ the length of the sequence should be zero.) A `GtkIMContextSimple` + line="1287">A `GtkIMContextSimple` the table + line="1288">the table @@ -73279,13 +75280,13 @@ the length of the sequence should be zero.) Maximum length of a sequence in the table + line="1289">Maximum length of a sequence in the table number of sequences in the table + line="1290">number of sequences in the table @@ -73301,7 +75302,7 @@ the length of the sequence should be zero.) - + @@ -73310,7 +75311,7 @@ the length of the sequence should be zero.) c:type="GtkIMContextSimplePrivate" disguised="1" opaque="1"> - + glib:type-struct="IMMulticontextClass"> `GtkIMMulticontext` is an input method context supporting multiple, -switchable input methods. + line="31">Supports switching between multiple input methods. Text widgets such as `GtkText` or `GtkTextView` use a `GtkIMMultiContext` to implement their `im-module` property for switching between different @@ -73331,12 +75331,12 @@ input methods. Creates a new `GtkIMMulticontext`. + line="151">Creates a new `GtkIMMulticontext`. a new `GtkIMMulticontext`. + line="156">a new `GtkIMMulticontext`. @@ -73344,19 +75344,19 @@ input methods. c:identifier="gtk_im_multicontext_get_context_id"> Gets the id of the currently active delegate of the @context. + line="585">Gets the id of the currently active delegate of the @context. the id of the currently active delegate + line="591">the id of the currently active delegate a `GtkIMMulticontext` + line="587">a `GtkIMMulticontext` @@ -73365,7 +75365,7 @@ input methods. c:identifier="gtk_im_multicontext_set_context_id"> Sets the context id for @context. + line="606">Sets the context id for @context. This causes the currently active delegate of @context to be replaced by the delegate corresponding to the new context id. @@ -73381,7 +75381,7 @@ property. a `GtkIMMulticontext` + line="608">a `GtkIMMulticontext` allow-none="1"> the id to use + line="609">the id to use @@ -73478,7 +75478,7 @@ property. - + @@ -73487,7 +75487,7 @@ property. - + @@ -73496,7 +75496,7 @@ property. - + @@ -73505,7 +75505,10 @@ property. - + The default name of the extension point. + - + Like [func@get_interface_age], but from the headers used at @@ -73568,7 +75571,7 @@ against at application run time. c:type="GTK_INVALID_LIST_POSITION"> The value used to refer to a guaranteed invalid position + line="66">The value used to refer to a guaranteed invalid position in a `GListModel`. This value may be returned from some functions, others may @@ -73577,7 +75580,7 @@ functions. Refer to each function's documentation for if this value is allowed and what it does. - + - + @@ -74889,7 +76892,7 @@ allowed and what it does. - + @@ -74898,7 +76901,7 @@ allowed and what it does. - + @@ -75467,7 +77470,8 @@ allowed and what it does. - + @@ -75476,7 +77480,8 @@ allowed and what it does. - + @@ -75485,7 +77490,8 @@ allowed and what it does. - + @@ -75494,7 +77500,8 @@ allowed and what it does. - + @@ -75521,7 +77528,7 @@ allowed and what it does. - + @@ -75692,7 +77699,7 @@ allowed and what it does. - + @@ -75701,7 +77708,7 @@ allowed and what it does. - + @@ -76005,6 +78012,16 @@ allowed and what it does. Used to specify options for gtk_icon_theme_lookup_icon(). + + Perform a regular lookup. + glib:get-type="gtk_icon_paintable_get_type"> Contains information found when looking up an icon in `GtkIconTheme`. + line="385">Contains information found when looking up an icon in `GtkIconTheme`. `GtkIconPaintable` implements `GdkPaintable`. @@ -76053,14 +78070,14 @@ allowed and what it does. c:identifier="gtk_icon_paintable_new_for_file"> Creates a `GtkIconPaintable` for a file with a given size and scale. + line="3991">Creates a `GtkIconPaintable` for a file with a given size and scale. The icon can then be rendered by using it as a `GdkPaintable`. - + a `GtkIconPaintable` containing + line="4001">a `GtkIconPaintable` containing for the icon. Unref with g_object_unref() @@ -76068,19 +78085,19 @@ The icon can then be rendered by using it as a `GdkPaintable`. a `GFile` + line="3993">a `GFile` desired icon size + line="3994">desired icon size, in application pixels the desired scale + line="3995">the desired scale @@ -76088,24 +78105,23 @@ The icon can then be rendered by using it as a `GdkPaintable`. - Gets the `GFile` that was used to load the icon. + line="3621">Gets the `GFile` that was used to load the icon. Returns %NULL if the icon was not loaded from a file. - + the `GFile` for the icon + line="3629">the `GFile` for the icon a `GtkIconPaintable` + line="3623">a `GtkIconPaintable` @@ -76113,10 +78129,9 @@ Returns %NULL if the icon was not loaded from a file. - Get the icon name being used for this icon. + line="3645">Get the icon name being used for this icon. When an icon looked up in the icon theme was not available, the icon theme may use fallback icons - either those specified to @@ -76125,11 +78140,11 @@ gtk_icon_theme_lookup_icon() or the always-available If the icon was created without an icon theme, this function returns %NULL. - + the themed icon-name for the + line="3660">the themed icon-name for the icon, or %NULL if its not a themed icon. @@ -76137,34 +78152,35 @@ returns %NULL. a `GtkIconPaintable` + line="3647">a `GtkIconPaintable` - - + Checks if the icon is symbolic or not. + line="3671">Checks if the icon is symbolic or not. This currently uses only the file name and not the file contents for determining this. This behaviour may change in the future. Note that to render a symbolic `GtkIconPaintable` properly (with recoloring), you have to set its icon name on a `GtkImage`. - + %TRUE if the icon is symbolic, %FALSE otherwise + line="3683">%TRUE if the icon is symbolic, %FALSE otherwise a `GtkIconPaintable` + line="3673">a `GtkIconPaintable` @@ -76174,11 +78190,9 @@ recoloring), you have to set its icon name on a `GtkImage`. construct-only="1" transfer-ownership="none" getter="get_file"> - The file representing the icon, if any. + line="3576">The file representing the icon, if any. transfer-ownership="none" getter="get_icon_name" default-value="NULL"> - The icon name that was chosen during lookup. + line="3586">The icon name that was chosen during lookup. - Whether the icon is symbolic or not. + line="3596">Whether the icon is symbolic or not. @@ -76213,7 +78224,7 @@ recoloring), you have to set its icon name on a `GtkImage`. c:type="GtkIconSize"> Built-in icon sizes. + line="217">Built-in icon sizes. Icon sizes default to being inherited. Where they cannot be inherited, text size is the default. @@ -76229,7 +78240,7 @@ determine the actual size to be used with the glib:name="GTK_ICON_SIZE_INHERIT"> Keep the size of the parent element + line="219">Keep the size of the parent element Size similar to text size + line="220">Size similar to text size Large size, for example in an icon view + line="221">Large size, for example in an icon view `GtkIconTheme` provides a facility for loading themed icons. + line="66">Loads themed icons. The main reason for using a name rather than simply providing a filename is to allow different icons to be used depending on what “icon theme” is @@ -76293,17 +78304,17 @@ g_object_unref (icon); Creates a new icon theme object. + line="827">Creates a new icon theme object. Icon theme objects are used to lookup up an icon by name in a particular icon theme. Usually, you’ll want to use [func@Gtk.IconTheme.get_for_display] rather than creating a new icon theme object for scratch. - + the newly created `GtkIconTheme` object. + line="837">the newly created `GtkIconTheme` object. @@ -76311,7 +78322,7 @@ a new icon theme object for scratch. c:identifier="gtk_icon_theme_get_for_display"> Gets the icon theme object associated with @display. + line="870">Gets the icon theme object associated with @display. If this function has not previously been called for the given display, a new icon theme object will be created and associated @@ -76319,11 +78330,11 @@ with the display. Icon theme objects are fairly expensive to create, so using this function is usually a better choice than calling [ctor@Gtk.IconTheme.new] and setting the display yourself; by using this function a single icon theme object will be shared between users. - + A unique `GtkIconTheme` associated with + line="883">A unique `GtkIconTheme` associated with the given display. This icon theme is associated with the display and can be used as long as the display is open. Do not ref or unref it. @@ -76332,7 +78343,7 @@ this function a single icon theme object will be shared between users. a `GdkDisplay` + line="872">a `GdkDisplay` @@ -76341,14 +78352,14 @@ this function a single icon theme object will be shared between users. c:identifier="gtk_icon_theme_add_resource_path"> Adds a resource path that will be looked at when looking + line="1626">Adds a resource path that will be looked at when looking for icons, similar to search paths. See [method@Gtk.IconTheme.set_resource_path]. This function should be used to make application-specific icons available as part of the icon theme. - + @@ -76356,13 +78367,13 @@ available as part of the icon theme. a `GtkIconTheme` + line="1628">a `GtkIconTheme` a resource path + line="1629">a resource path @@ -76371,10 +78382,10 @@ available as part of the icon theme. c:identifier="gtk_icon_theme_add_search_path"> Appends a directory to the search path. + line="1529">Appends a directory to the search path. See [method@Gtk.IconTheme.set_search_path]. - + @@ -76382,13 +78393,13 @@ See [method@Gtk.IconTheme.set_search_path]. a `GtkIconTheme` + line="1531">a `GtkIconTheme` directory name to append to the icon path + line="1532">directory name to append to the icon path @@ -76398,20 +78409,20 @@ See [method@Gtk.IconTheme.set_search_path]. glib:get-property="display"> Returns the display that the `GtkIconTheme` object was + line="4111">Returns the display that the `GtkIconTheme` object was created for. - + the display of @icon_theme + line="4118">the display of @icon_theme a `GtkIconTheme` + line="4113">a `GtkIconTheme` @@ -76421,12 +78432,12 @@ created for. glib:get-property="icon-names"> Lists the names of icons in the current icon theme. - + line="2722">Lists the names of icons in the current icon theme. + a string array + line="2728">a string array holding the names of all the icons in the theme. You must free the array using g_strfreev(). @@ -76437,7 +78448,7 @@ created for. a `GtkIconTheme` + line="2724">a `GtkIconTheme` @@ -76446,16 +78457,16 @@ created for. c:identifier="gtk_icon_theme_get_icon_sizes"> Returns an array of integers describing the sizes at which + line="2645">Returns an array of integers describing the sizes at which the icon is available without scaling. A size of -1 means that the icon is available in a scalable format. The array is zero-terminated. - + A newly + line="2656">A newly allocated array describing the sizes at which the icon is available. The array should be freed with g_free() when it is no longer needed. @@ -76467,13 +78478,13 @@ format. The array is zero-terminated. a `GtkIconTheme` + line="2647">a `GtkIconTheme` the name of an icon + line="2648">the name of an icon @@ -76483,14 +78494,14 @@ format. The array is zero-terminated. glib:get-property="resource-path"> Gets the current resource path. + line="1599">Gets the current resource path. See [method@Gtk.IconTheme.set_resource_path]. - + + line="1607"> A list of resource paths @@ -76500,7 +78511,7 @@ See [method@Gtk.IconTheme.set_resource_path]. a `GtkIconTheme` + line="1601">a `GtkIconTheme` @@ -76510,14 +78521,14 @@ See [method@Gtk.IconTheme.set_resource_path]. glib:get-property="search-path"> Gets the current search path. + line="1502">Gets the current search path. See [method@Gtk.IconTheme.set_search_path]. - + + line="1510"> a list of icon theme path directories @@ -76527,7 +78538,7 @@ See [method@Gtk.IconTheme.set_search_path]. a `GtkIconTheme` + line="1504">a `GtkIconTheme` @@ -76537,18 +78548,19 @@ See [method@Gtk.IconTheme.set_search_path]. glib:get-property="theme-name"> Gets the current icon theme name. - -Returns (transfer full): the current icon theme name, - + line="1706">Gets the current icon theme name. + + the current icon theme name, a `GtkIconTheme` + line="1708">a `GtkIconTheme` @@ -76558,26 +78570,26 @@ Returns (transfer full): the current icon theme name, version="4.2"> Checks whether an icon theme includes an icon + line="2589">Checks whether an icon theme includes an icon for a particular `GIcon`. - + %TRUE if @self includes an icon for @gicon + line="2597">%TRUE if @self includes an icon for @gicon a `GtkIconTheme` + line="2591">a `GtkIconTheme` a `GIcon` + line="2592">a `GIcon` @@ -76585,13 +78597,13 @@ for a particular `GIcon`. Checks whether an icon theme includes an icon + line="2552">Checks whether an icon theme includes an icon for a particular name. - + %TRUE if @self includes an + line="2560">%TRUE if @self includes an icon for @icon_name. @@ -76599,13 +78611,13 @@ for a particular name. a `GtkIconTheme` + line="2554">a `GtkIconTheme` the name of an icon + line="2555">the name of an icon @@ -76614,15 +78626,15 @@ for a particular name. c:identifier="gtk_icon_theme_lookup_by_gicon"> Looks up a icon for a desired size and window scale. + line="4034">Looks up a icon for a desired size and window scale. The icon can then be rendered by using it as a `GdkPaintable`, or you can get information such as the filename and size. - + a `GtkIconPaintable` containing + line="4048">a `GtkIconPaintable` containing information about the icon. Unref with g_object_unref() @@ -76630,37 +78642,37 @@ or you can get information such as the filename and size. a `GtkIconTheme` + line="4036">a `GtkIconTheme` the `GIcon` to look up + line="4037">the `GIcon` to look up desired icon size + line="4038">desired icon size, in application pixels the desired scale + line="4039">the desired scale text direction the icon will be displayed in + line="4040">text direction the icon will be displayed in flags modifying the behavior of the icon lookup + line="4041">flags modifying the behavior of the icon lookup @@ -76668,7 +78680,7 @@ or you can get information such as the filename and size. Looks up a named icon for a desired size and window scale, + line="2442">Looks up a named icon for a desired size and window scale, returning a `GtkIconPaintable`. The icon can then be rendered by using it as a `GdkPaintable`, @@ -76684,11 +78696,11 @@ for missing icons you need to use [method@Gtk.IconTheme.has_icon]. Note that you probably want to listen for icon theme changes and update the icon. This is usually done by overriding the GtkWidgetClass.css-changed() function. - + a `GtkIconPaintable` object + line="2469">a `GtkIconPaintable` object containing the icon. @@ -76696,19 +78708,22 @@ GtkWidgetClass.css-changed() function. a `GtkIconTheme` + line="2444">a `GtkIconTheme` the name of the icon to lookup + line="2445">the name of the icon to lookup + fallback names @@ -76716,25 +78731,25 @@ GtkWidgetClass.css-changed() function. desired icon size. + line="2447">desired icon size, in application pixels the window scale this will be displayed on + line="2448">the window scale this will be displayed on text direction the icon will be displayed in + line="2449">text direction the icon will be displayed in flags modifying the behavior of the icon lookup + line="2450">flags modifying the behavior of the icon lookup @@ -76744,7 +78759,7 @@ GtkWidgetClass.css-changed() function. glib:set-property="resource-path"> Sets the resource paths that will be looked at when + line="1559">Sets the resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme @@ -76755,7 +78770,7 @@ or `@path/scalable/actions/run.svg`. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback, but they are treated like unthemed icons. - + @@ -76763,7 +78778,7 @@ but they are treated like unthemed icons. a `GtkIconTheme` + line="1561">a `GtkIconTheme` allow-none="1"> + line="1562"> NULL-terminated array of resource paths that are searched for icons @@ -76786,7 +78801,7 @@ but they are treated like unthemed icons. glib:set-property="search-path"> Sets the search path for the icon theme object. + line="1459">Sets the search path for the icon theme object. When looking for an icon theme, GTK will search for a subdirectory of one or more of the directories in @path with the same name @@ -76801,7 +78816,7 @@ the right name is found directly in one of the elements of (This is legacy feature, and new icons should be put into the fallback icon theme, which is called hicolor, rather than directly on the icon path.) - + @@ -76809,7 +78824,7 @@ rather than directly on the icon path.) a `GtkIconTheme` + line="1461">a `GtkIconTheme` allow-none="1"> NULL-terminated + line="1462">NULL-terminated array of directories that are searched for icon themes @@ -76831,12 +78846,12 @@ rather than directly on the icon path.) glib:set-property="theme-name"> Sets the name of the icon theme that the `GtkIconTheme` object uses + line="1660">Sets the name of the icon theme that the `GtkIconTheme` object uses overriding system configuration. This function cannot be called on the icon theme objects returned from [func@Gtk.IconTheme.get_for_display]. - + @@ -76844,7 +78859,7 @@ from [func@Gtk.IconTheme.get_for_display]. a `GtkIconTheme` + line="1662">a `GtkIconTheme` allow-none="1"> name of icon theme to use instead of + line="1663">name of icon theme to use instead of configured theme, or %NULL to unset a previously set custom theme @@ -76865,7 +78880,7 @@ from [func@Gtk.IconTheme.get_for_display]. getter="get_display"> The display that this icon theme object is attached to. + line="1018">The display that this icon theme object is attached to. getter="get_icon_names"> The icon names that are supported by the icon theme. + line="1028">The icon names that are supported by the icon theme. @@ -76885,7 +78900,7 @@ from [func@Gtk.IconTheme.get_for_display]. getter="get_resource_path"> Resource paths that will be looked at when looking for icons, + line="1054">Resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme @@ -76904,7 +78919,7 @@ of a subdirectory are also considered as ultimate fallback. getter="get_search_path"> The search path for this icon theme. + line="1038">The search path for this icon theme. When looking for icons, GTK will search for a subdirectory of one or more of the directories in the search path with the same @@ -76923,7 +78938,7 @@ to be extended by adding icons in the user’s home directory.) default-value="NULL"> The name of the icon theme that is being used. + line="1071">The name of the icon theme that is being used. Unless set to a different value, this will be the value of the `GtkSettings:gtk-icon-theme-name` property of the `GtkSettings` @@ -76933,7 +78948,7 @@ object associated to the display of the icontheme object. Emitted when the icon theme changes. + line="1000">Emitted when the icon theme changes. This can happen because current icon theme is switched or because GTK detects that a change has occurred in the @@ -76950,7 +78965,7 @@ contents of the current icon theme. glib:error-domain="gtk-icon-theme-error-quark"> Error codes for `GtkIconTheme` operations. + line="73">Error codes for `GtkIconTheme` operations. glib:name="GTK_ICON_THEME_NOT_FOUND"> The icon specified does not exist in the theme + line="75">The icon specified does not exist in the theme glib:name="GTK_ICON_THEME_FAILED"> An unspecified error occurred. + line="76">An unspecified error occurred. + Registers an error quark for [class@Gtk.IconTheme] errors. + the error quark @@ -76987,6 +79008,11 @@ contents of the current icon theme. filename="gtk/deprecated/gtkiconview.c" line="54">`GtkIconView` is a widget which displays data in a grid of icons. +<picture> + <source srcset="icon-view-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkIconView" src="icon-view.png"> +</picture> + `GtkIconView` provides an alternative view on a `GtkTreeModel`. It displays the model as a grid of icons with labels. Like [class@Gtk.TreeView], it allows to select one or multiple items @@ -77020,13 +79046,13 @@ For rubberband selection, a subnode with name rubberband is used. deprecated-version="4.10"> Creates a new `GtkIconView` widget + line="4051">Creates a new `GtkIconView` widget Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget + line="4056">A newly created `GtkIconView` widget @@ -77036,21 +79062,21 @@ For rubberband selection, a subnode with name rubberband is used. deprecated-version="4.10"> Creates a new `GtkIconView` widget using the + line="4066">Creates a new `GtkIconView` widget using the specified @area to layout cells inside the icons. Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget + line="4073">A newly created `GtkIconView` widget the `GtkCellArea` to use to layout cells + line="4068">the `GtkCellArea` to use to layout cells @@ -77061,20 +79087,20 @@ specified @area to layout cells inside the icons. deprecated-version="4.10"> Creates a new `GtkIconView` widget with the model @model. + line="4083">Creates a new `GtkIconView` widget with the model @model. Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget. + line="4089">A newly created `GtkIconView` widget. The model. + line="4085">The model. @@ -77085,27 +79111,27 @@ specified @area to layout cells inside the icons. deprecated-version="4.10"> Creates a `GdkPaintable` representation of the item at @path. + line="6648">Creates a `GdkPaintable` representation of the item at @path. This image is used for a drag icon. Use [class@Gtk.GridView] instead a newly-allocated `GdkPaintable` of the drag icon. + line="6656">a newly-allocated `GdkPaintable` of the drag icon. a `GtkIconView` + line="6650">a `GtkIconView` a `GtkTreePath` in @icon_view + line="6651">a `GtkTreePath` in @icon_view @@ -77116,7 +79142,7 @@ This image is used for a drag icon. deprecated-version="4.10"> Turns @icon_view into a drop destination for automatic DND. Calling this + line="6403">Turns @icon_view into a drop destination for automatic DND. Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead @@ -77127,19 +79153,19 @@ method sets `GtkIconView`:reorderable to %FALSE. a `GtkIconView` + line="6405">a `GtkIconView` the formats that the drag will support + line="6406">the formats that the drag will support the bitmask of possible actions for a drag to this + line="6407">the bitmask of possible actions for a drag to this widget @@ -77151,7 +79177,7 @@ method sets `GtkIconView`:reorderable to %FALSE. deprecated-version="4.10"> Turns @icon_view into a drag source for automatic DND. Calling this + line="6374">Turns @icon_view into a drag source for automatic DND. Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead @@ -77162,25 +79188,25 @@ method sets `GtkIconView`:reorderable to %FALSE. a `GtkIconView` + line="6376">a `GtkIconView` Mask of allowed buttons to start drag + line="6377">Mask of allowed buttons to start drag the formats that the drag will support + line="6378">the formats that the drag will support the bitmask of possible actions for a drag from this + line="6379">the bitmask of possible actions for a drag from this widget @@ -77193,20 +79219,20 @@ method sets `GtkIconView`:reorderable to %FALSE. deprecated-version="4.10"> Gets the setting set by gtk_icon_view_set_activate_on_single_click(). + line="6798">Gets the setting set by gtk_icon_view_set_activate_on_single_click(). Use [class@Gtk.GridView] instead %TRUE if item-activated will be emitted on a single click + line="6804">%TRUE if item-activated will be emitted on a single click a `GtkIconView` + line="6800">a `GtkIconView` @@ -77217,7 +79243,7 @@ method sets `GtkIconView`:reorderable to %FALSE. deprecated-version="4.10"> Fills the bounding rectangle in widget coordinates for the cell specified by + line="4175">Fills the bounding rectangle in widget coordinates for the cell specified by @path and @cell. If @cell is %NULL the main cell area is used. This function is only valid if @icon_view is realized. @@ -77226,20 +79252,20 @@ This function is only valid if @icon_view is realized. %FALSE if there is no such item, %TRUE otherwise + line="4187">%FALSE if there is no such item, %TRUE otherwise a `GtkIconView` + line="4177">a `GtkIconView` a `GtkTreePath` + line="4178">a `GtkTreePath` allow-none="1"> a `GtkCellRenderer` + line="4179">a `GtkCellRenderer` transfer-ownership="none"> rectangle to fill with cell rect + line="4180">rectangle to fill with cell rect @@ -77269,20 +79295,20 @@ This function is only valid if @icon_view is realized. deprecated-version="4.10"> Returns the value of the ::column-spacing property. + line="5555">Returns the value of the ::column-spacing property. Use [class@Gtk.GridView] instead the space between columns + line="5561">the space between columns a `GtkIconView` + line="5557">a `GtkIconView` @@ -77294,20 +79320,20 @@ This function is only valid if @icon_view is realized. deprecated-version="4.10"> Returns the value of the ::columns property. + line="5362">Returns the value of the ::columns property. Use [class@Gtk.GridView] instead the number of columns, or -1 + line="5368">the number of columns, or -1 a `GtkIconView` + line="5364">a `GtkIconView` @@ -77318,7 +79344,7 @@ This function is only valid if @icon_view is realized. deprecated-version="4.10"> Fills in @path and @cell with the current cursor path and cell. + line="2017">Fills in @path and @cell with the current cursor path and cell. If the cursor isn’t currently set, then *@path will be %NULL. If no cell currently has focus, then *@cell will be %NULL. @@ -77328,14 +79354,14 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). %TRUE if the cursor is set. + line="2031">%TRUE if the cursor is set. A `GtkIconView` + line="2019">A `GtkIconView` allow-none="1"> Return location for the current + line="2020">Return location for the current cursor path @@ -77358,7 +79384,7 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). allow-none="1"> Return location the current + line="2022">Return location the current focus cell @@ -77370,32 +79396,32 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). deprecated-version="4.10"> Determines the destination item for a given position. + line="6585">Determines the destination item for a given position. Use [class@Gtk.GridView] instead whether there is an item at the given position. + line="6595">whether there is an item at the given position. a `GtkIconView` + line="6587">a `GtkIconView` the position to determine the destination item for + line="6588">the position to determine the destination item for the position to determine the destination item for + line="6589">the position to determine the destination item for allow-none="1"> Return location for the path of the item + line="6590">Return location for the path of the item allow-none="1"> Return location for the drop position + line="6591">Return location for the drop position @@ -77429,7 +79455,7 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). deprecated-version="4.10"> Gets information about the item that is highlighted for feedback. + line="6555">Gets information about the item that is highlighted for feedback. Use [class@Gtk.GridView] instead @@ -77439,7 +79465,7 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). a `GtkIconView` + line="6557">a `GtkIconView` allow-none="1"> Return location for the path of + line="6558">Return location for the path of the highlighted item @@ -77463,7 +79489,7 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). allow-none="1"> Return location for the drop position + line="6560">Return location for the drop position @@ -77475,32 +79501,32 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). deprecated-version="4.10"> Gets the path and cell for the icon at the given position. + line="4132">Gets the path and cell for the icon at the given position. Use [class@Gtk.GridView] instead %TRUE if an item exists at the specified position + line="4143">%TRUE if an item exists at the specified position A `GtkIconView`. + line="4134">A `GtkIconView`. The x position to be identified + line="4135">The x position to be identified The y position to be identified + line="4136">The y position to be identified allow-none="1"> Return location for the path + line="4137">Return location for the path allow-none="1"> Return location for the renderer + line="4138">Return location for the renderer responsible for the cell at (@x, @y) @@ -77534,27 +79560,27 @@ The returned `GtkTreePath` must be freed with gtk_tree_path_free(). deprecated-version="4.10"> Gets the column in which the item @path is currently + line="5223">Gets the column in which the item @path is currently displayed. Column numbers start at 0. Use [class@Gtk.GridView] instead The column in which the item is displayed + line="5231">The column in which the item is displayed a `GtkIconView` + line="5225">a `GtkIconView` the `GtkTreePath` of the item + line="5226">the `GtkTreePath` of the item @@ -77566,21 +79592,21 @@ displayed. Column numbers start at 0. deprecated-version="4.10"> Returns the value of the ::item-orientation property which determines + line="5311">Returns the value of the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. Use [class@Gtk.GridView] instead the relative position of texts and icons + line="5318">the relative position of texts and icons a `GtkIconView` + line="5313">a `GtkIconView` @@ -77592,20 +79618,20 @@ whether the labels are drawn beside the icons instead of below. deprecated-version="4.10"> Returns the value of the ::item-padding property. + line="5650">Returns the value of the ::item-padding property. Use [class@Gtk.GridView] instead the padding around items + line="5656">the padding around items a `GtkIconView` + line="5652">a `GtkIconView` @@ -77616,27 +79642,27 @@ whether the labels are drawn beside the icons instead of below. deprecated-version="4.10"> Gets the row in which the item @path is currently + line="5192">Gets the row in which the item @path is currently displayed. Row numbers start at 0. Use [class@Gtk.GridView] instead The row in which the item is displayed + line="5200">The row in which the item is displayed a `GtkIconView` + line="5194">a `GtkIconView` the `GtkTreePath` of the item + line="5195">the `GtkTreePath` of the item @@ -77648,20 +79674,20 @@ displayed. Row numbers start at 0. deprecated-version="4.10"> Returns the value of the ::item-width property. + line="5412">Returns the value of the ::item-width property. Use [class@Gtk.GridView] instead the width of a single item, or -1 + line="5418">the width of a single item, or -1 a `GtkIconView` + line="5414">a `GtkIconView` @@ -77673,20 +79699,20 @@ displayed. Row numbers start at 0. deprecated-version="4.10"> Returns the value of the ::margin property. + line="5603">Returns the value of the ::margin property. Use [class@Gtk.GridView] instead the space at the borders + line="5609">the space at the borders a `GtkIconView` + line="5605">a `GtkIconView` @@ -77698,20 +79724,20 @@ displayed. Row numbers start at 0. deprecated-version="4.10"> Returns the column with markup text for @icon_view. + line="4922">Returns the column with markup text for @icon_view. Use [class@Gtk.GridView] instead the markup column, or -1 if it’s unset. + line="4928">the markup column, or -1 if it’s unset. A `GtkIconView`. + line="4924">A `GtkIconView`. @@ -77723,21 +79749,21 @@ displayed. Row numbers start at 0. deprecated-version="4.10"> Returns the model the `GtkIconView` is based on. Returns %NULL if the + line="4709">Returns the model the `GtkIconView` is based on. Returns %NULL if the model is unset. Use [class@Gtk.GridView] instead The currently used `GtkTreeModel` + line="4716">The currently used `GtkTreeModel` a `GtkIconView` + line="4711">a `GtkIconView` @@ -77748,13 +79774,13 @@ model is unset. deprecated-version="4.10"> Gets the path for the icon at the given position. + line="4099">Gets the path for the icon at the given position. Use [class@Gtk.GridView] instead The `GtkTreePath` corresponding + line="4107">The `GtkTreePath` corresponding to the icon or %NULL if no icon exists at that position. @@ -77762,19 +79788,19 @@ to the icon or %NULL if no icon exists at that position. A `GtkIconView`. + line="4101">A `GtkIconView`. The x position to be identified + line="4102">The x position to be identified The y position to be identified + line="4103">The y position to be identified @@ -77786,20 +79812,20 @@ to the icon or %NULL if no icon exists at that position. deprecated-version="4.10"> Returns the column with pixbufs for @icon_view. + line="4980">Returns the column with pixbufs for @icon_view. Use [class@Gtk.GridView] instead the pixbuf column, or -1 if it’s unset. + line="4986">the pixbuf column, or -1 if it’s unset. A `GtkIconView`. + line="4982">A `GtkIconView`. @@ -77811,21 +79837,21 @@ to the icon or %NULL if no icon exists at that position. deprecated-version="4.10"> Retrieves whether the user can reorder the list via drag-and-drop. + line="6700">Retrieves whether the user can reorder the list via drag-and-drop. See gtk_icon_view_set_reorderable(). Use [class@Gtk.GridView] instead %TRUE if the list can be reordered. + line="6707">%TRUE if the list can be reordered. a `GtkIconView` + line="6702">a `GtkIconView` @@ -77837,20 +79863,20 @@ See gtk_icon_view_set_reorderable(). deprecated-version="4.10"> Returns the value of the ::row-spacing property. + line="5508">Returns the value of the ::row-spacing property. Use [class@Gtk.GridView] instead the space between rows + line="5514">the space between rows a `GtkIconView` + line="5510">a `GtkIconView` @@ -77861,7 +79887,7 @@ See gtk_icon_view_set_reorderable(). deprecated-version="4.10"> Creates a list of paths of all selected items. Additionally, if you are + line="5053">Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of `GtkTreeRowReferences`. To do this, you can use gtk_tree_row_reference_new(). @@ -77882,7 +79908,7 @@ g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); A `GList` containing a `GtkTreePath` for each selected row. + line="5074">A `GList` containing a `GtkTreePath` for each selected row. @@ -77891,7 +79917,7 @@ g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); A `GtkIconView`. + line="5055">A `GtkIconView`. @@ -77903,20 +79929,20 @@ g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); deprecated-version="4.10"> Gets the selection mode of the @icon_view. + line="4576">Gets the selection mode of the @icon_view. Use [class@Gtk.GridView] instead the current selection mode + line="4582">the current selection mode A `GtkIconView`. + line="4578">A `GtkIconView`. @@ -77928,20 +79954,20 @@ g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); deprecated-version="4.10"> Returns the value of the ::spacing property. + line="5461">Returns the value of the ::spacing property. Use [class@Gtk.GridView] instead the space between cells + line="5467">the space between cells a `GtkIconView` + line="5463">a `GtkIconView` @@ -77953,20 +79979,20 @@ g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); deprecated-version="4.10"> Returns the column with text for @icon_view. + line="4863">Returns the column with text for @icon_view. Use [class@Gtk.GridView] instead the text column, or -1 if it’s unset. + line="4869">the text column, or -1 if it’s unset. A `GtkIconView`. + line="4865">A `GtkIconView`. @@ -77978,14 +80004,14 @@ g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); deprecated-version="4.10"> Returns the column of @icon_view’s model which is being used for + line="4438">Returns the column of @icon_view’s model which is being used for displaying tooltips on @icon_view’s rows. Use [class@Gtk.GridView] instead the index of the tooltip column that is currently being + line="4445">the index of the tooltip column that is currently being used, or -1 if this is disabled. @@ -77993,7 +80019,7 @@ used, or -1 if this is disabled. a `GtkIconView` + line="4440">a `GtkIconView` @@ -78004,7 +80030,7 @@ used, or -1 if this is disabled. deprecated-version="4.10"> This function is supposed to be used in a `GtkWidget::query-tooltip` + line="4286">This function is supposed to be used in a `GtkWidget::query-tooltip` signal handler for `GtkIconView`. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. @@ -78019,32 +80045,32 @@ that row and the corresponding model. whether or not the given tooltip context points to an item + line="4307">whether or not the given tooltip context points to an item an `GtkIconView` + line="4288">an `GtkIconView` the x coordinate (relative to widget coordinates) + line="4289">the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) + line="4290">the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not + line="4291">whether this is a keyboard tooltip or not allow-none="1"> a pointer to receive a `GtkTreeModel` + line="4292">a pointer to receive a `GtkTreeModel` allow-none="1"> a pointer to receive a `GtkTreePath` + line="4293">a pointer to receive a `GtkTreePath` allow-none="1"> a pointer to receive a `GtkTreeIter` + line="4294">a pointer to receive a `GtkTreeIter` @@ -78088,7 +80114,7 @@ that row and the corresponding model. deprecated-version="4.10"> Sets @start_path and @end_path to be the first and last visible path. + line="4458">Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. Both paths should be freed with gtk_tree_path_free() after use. @@ -78097,14 +80123,14 @@ Both paths should be freed with gtk_tree_path_free() after use. %TRUE, if valid paths were placed in @start_path and @end_path + line="4469">%TRUE, if valid paths were placed in @start_path and @end_path A `GtkIconView` + line="4460">A `GtkIconView` allow-none="1"> Return location for start of region + line="4461">Return location for start of region allow-none="1"> Return location for end of region + line="4462">Return location for end of region @@ -78137,7 +80163,7 @@ Both paths should be freed with gtk_tree_path_free() after use. deprecated-version="4.10"> Activates the item determined by @path. + line="5254">Activates the item determined by @path. Use [class@Gtk.GridView] instead @@ -78147,13 +80173,13 @@ Both paths should be freed with gtk_tree_path_free() after use. A `GtkIconView` + line="5256">A `GtkIconView` The `GtkTreePath` to be activated + line="5257">The `GtkTreePath` to be activated @@ -78164,27 +80190,27 @@ Both paths should be freed with gtk_tree_path_free() after use. deprecated-version="4.10"> Returns %TRUE if the icon pointed to by @path is currently + line="5161">Returns %TRUE if the icon pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned. Use [class@Gtk.GridView] instead %TRUE if @path is selected. + line="5169">%TRUE if @path is selected. A `GtkIconView`. + line="5163">A `GtkIconView`. A `GtkTreePath` to check selection on. + line="5164">A `GtkTreePath` to check selection on. @@ -78195,7 +80221,7 @@ selected. If @path does not point to a valid location, %FALSE is returned. deprecated-version="4.10"> Moves the alignments of @icon_view to the position specified by @path. + line="3841">Moves the alignments of @icon_view to the position specified by @path. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means @@ -78218,31 +80244,31 @@ centered path will be modified to reflect this change. A `GtkIconView` + line="3843">A `GtkIconView` The path of the item to move to. + line="3844">The path of the item to move to. whether to use alignment arguments, or %FALSE. + line="3845">whether to use alignment arguments, or %FALSE. The vertical alignment of the item specified by @path. + line="3846">The vertical alignment of the item specified by @path. The horizontal alignment of the item specified by @path. + line="3847">The horizontal alignment of the item specified by @path. @@ -78253,7 +80279,7 @@ centered path will be modified to reflect this change. deprecated-version="4.10"> Selects all the icons. @icon_view must has its selection mode set + line="5101">Selects all the icons. @icon_view must has its selection mode set to %GTK_SELECTION_MULTIPLE. Use [class@Gtk.GridView] instead @@ -78264,7 +80290,7 @@ to %GTK_SELECTION_MULTIPLE. A `GtkIconView`. + line="5103">A `GtkIconView`. @@ -78275,7 +80301,7 @@ to %GTK_SELECTION_MULTIPLE. deprecated-version="4.10"> Selects the row at @path. + line="4998">Selects the row at @path. Use [class@Gtk.GridView] instead @@ -78285,13 +80311,13 @@ to %GTK_SELECTION_MULTIPLE. A `GtkIconView`. + line="5000">A `GtkIconView`. The `GtkTreePath` to be selected. + line="5001">The `GtkTreePath` to be selected. @@ -78302,7 +80328,7 @@ to %GTK_SELECTION_MULTIPLE. deprecated-version="4.10"> Calls a function for each selected icon. Note that the model or + line="4519">Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function. Use [class@Gtk.GridView] instead @@ -78313,7 +80339,7 @@ selection cannot be modified from within this function. A `GtkIconView`. + line="4521">A `GtkIconView`. closure="1"> The function to call for each selected icon. + line="4522">The function to call for each selected icon. allow-none="1"> User data to pass to the function. + line="4523">User data to pass to the function. @@ -78343,7 +80369,7 @@ selection cannot be modified from within this function. deprecated-version="4.10"> Causes the `GtkIconView`::item-activated signal to be emitted on + line="6773">Causes the `GtkIconView`::item-activated signal to be emitted on a single click instead of a double click. Use [class@Gtk.GridView] instead @@ -78354,13 +80380,13 @@ a single click instead of a double click. a `GtkIconView` + line="6775">a `GtkIconView` %TRUE to emit item-activated on a single click + line="6776">%TRUE to emit item-activated on a single click @@ -78372,7 +80398,7 @@ a single click instead of a double click. deprecated-version="4.10"> Sets the ::column-spacing property which specifies the space + line="5526">Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view. Use [class@Gtk.GridView] instead @@ -78383,13 +80409,13 @@ which is inserted between the columns of the icon view. a `GtkIconView` + line="5528">a `GtkIconView` the column spacing + line="5529">the column spacing @@ -78401,7 +80427,7 @@ which is inserted between the columns of the icon view. deprecated-version="4.10"> Sets the ::columns property which determines in how + line="5331">Sets the ::columns property which determines in how many columns the icons are arranged. If @columns is -1, the number of columns will be chosen automatically to fill the available area. @@ -78414,13 +80440,13 @@ to fill the available area. a `GtkIconView` + line="5333">a `GtkIconView` the number of columns + line="5334">the number of columns @@ -78431,7 +80457,7 @@ to fill the available area. deprecated-version="4.10"> Sets the current keyboard focus to be at @path, and selects it. This is + line="1960">Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular item. If @cell is not %NULL, then focus is given to the cell specified by it. Additionally, if @start_editing is %TRUE, then editing should be @@ -78449,13 +80475,13 @@ Please note that editing can only happen when the widget is realized. A `GtkIconView` + line="1962">A `GtkIconView` A `GtkTreePath` + line="1963">A `GtkTreePath` allow-none="1"> One of the cell renderers of @icon_view + line="1964">One of the cell renderers of @icon_view %TRUE if the specified cell should start being edited. + line="1965">%TRUE if the specified cell should start being edited. @@ -78481,7 +80507,7 @@ Please note that editing can only happen when the widget is realized. deprecated-version="4.10"> Sets the item that is highlighted for feedback. + line="6496">Sets the item that is highlighted for feedback. Use [class@Gtk.GridView] instead @@ -78491,7 +80517,7 @@ Please note that editing can only happen when the widget is realized. a `GtkIconView` + line="6498">a `GtkIconView` allow-none="1"> The path of the item to highlight + line="6499">The path of the item to highlight Specifies where to drop, relative to the item + line="6500">Specifies where to drop, relative to the item @@ -78519,7 +80545,7 @@ Please note that editing can only happen when the widget is realized. deprecated-version="4.10"> Sets the ::item-orientation property which determines whether the labels + line="5273">Sets the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. Use [class@Gtk.GridView] instead @@ -78530,13 +80556,13 @@ are drawn beside the icons instead of below. a `GtkIconView` + line="5275">a `GtkIconView` the relative position of texts and icons + line="5276">the relative position of texts and icons @@ -78548,7 +80574,7 @@ are drawn beside the icons instead of below. deprecated-version="4.10"> Sets the `GtkIconView`:item-padding property which specifies the padding + line="5621">Sets the `GtkIconView`:item-padding property which specifies the padding around each of the icon view’s items. Use [class@Gtk.GridView] instead @@ -78559,13 +80585,13 @@ around each of the icon view’s items. a `GtkIconView` + line="5623">a `GtkIconView` the item padding + line="5624">the item padding @@ -78577,7 +80603,7 @@ around each of the icon view’s items. deprecated-version="4.10"> Sets the ::item-width property which specifies the width + line="5380">Sets the ::item-width property which specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. Use [class@Gtk.GridView] instead @@ -78589,13 +80615,13 @@ automatically determine a suitable item size. a `GtkIconView` + line="5382">a `GtkIconView` the width for each item + line="5383">the width for each item @@ -78607,7 +80633,7 @@ automatically determine a suitable item size. deprecated-version="4.10"> Sets the ::margin property which specifies the space + line="5573">Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view. Use [class@Gtk.GridView] instead @@ -78619,13 +80645,13 @@ of the icon view. a `GtkIconView` + line="5575">a `GtkIconView` the margin + line="5576">the margin @@ -78637,7 +80663,7 @@ of the icon view. deprecated-version="4.10"> Sets the column with markup information for @icon_view to be + line="4881">Sets the column with markup information for @icon_view to be @column. The markup column must be of type `G_TYPE_STRING`. If the markup column is set to something, it overrides the text column set by gtk_icon_view_set_text_column(). @@ -78650,13 +80676,13 @@ the text column set by gtk_icon_view_set_text_column(). A `GtkIconView`. + line="4883">A `GtkIconView`. A column in the currently used model, or -1 to display no text + line="4884">A column in the currently used model, or -1 to display no text @@ -78668,7 +80694,7 @@ the text column set by gtk_icon_view_set_text_column(). deprecated-version="4.10"> Sets the model for a `GtkIconView`. + line="4594">Sets the model for a `GtkIconView`. If the @icon_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. @@ -78681,7 +80707,7 @@ it will unset the old model. A `GtkIconView`. + line="4596">A `GtkIconView`. allow-none="1"> The model. + line="4597">The model. @@ -78702,7 +80728,7 @@ it will unset the old model. deprecated-version="4.10"> Sets the column with pixbufs for @icon_view to be @column. The pixbuf + line="4940">Sets the column with pixbufs for @icon_view to be @column. The pixbuf column must be of type `GDK_TYPE_PIXBUF` Use [class@Gtk.GridView] instead @@ -78713,13 +80739,13 @@ column must be of type `GDK_TYPE_PIXBUF` A `GtkIconView`. + line="4942">A `GtkIconView`. A column in the currently used model, or -1 to disable + line="4943">A column in the currently used model, or -1 to disable @@ -78731,7 +80757,7 @@ column must be of type `GDK_TYPE_PIXBUF` deprecated-version="4.10"> This function is a convenience function to allow you to reorder models that + line="6719">This function is a convenience function to allow you to reorder models that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`. Both `GtkTreeStore` and `GtkListStore` support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The @@ -78752,13 +80778,13 @@ handle drag and drop manually. A `GtkIconView`. + line="6721">A `GtkIconView`. %TRUE, if the list of items can be reordered. + line="6722">%TRUE, if the list of items can be reordered. @@ -78770,7 +80796,7 @@ handle drag and drop manually. deprecated-version="4.10"> Sets the ::row-spacing property which specifies the space + line="5479">Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view. Use [class@Gtk.GridView] instead @@ -78781,13 +80807,13 @@ which is inserted between the rows of the icon view. a `GtkIconView` + line="5481">a `GtkIconView` the row spacing + line="5482">the row spacing @@ -78799,7 +80825,7 @@ which is inserted between the rows of the icon view. deprecated-version="4.10"> Sets the selection mode of the @icon_view. + line="4549">Sets the selection mode of the @icon_view. Use [class@Gtk.GridView] instead @@ -78809,13 +80835,13 @@ which is inserted between the rows of the icon view. A `GtkIconView`. + line="4551">A `GtkIconView`. The selection mode + line="4552">The selection mode @@ -78827,7 +80853,7 @@ which is inserted between the rows of the icon view. deprecated-version="4.10"> Sets the ::spacing property which specifies the space + line="5431">Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. Use [class@Gtk.GridView] instead @@ -78839,13 +80865,13 @@ the text) of an item. a `GtkIconView` + line="5433">a `GtkIconView` the spacing + line="5434">the spacing @@ -78857,7 +80883,7 @@ the text) of an item. deprecated-version="4.10"> Sets the column with text for @icon_view to be @column. The text + line="4824">Sets the column with text for @icon_view to be @column. The text column must be of type `G_TYPE_STRING`. Use [class@Gtk.GridView] instead @@ -78868,13 +80894,13 @@ column must be of type `G_TYPE_STRING`. A `GtkIconView`. + line="4826">A `GtkIconView`. A column in the currently used model, or -1 to display no text + line="4827">A column in the currently used model, or -1 to display no text @@ -78885,7 +80911,7 @@ column must be of type `G_TYPE_STRING`. deprecated-version="4.10"> Sets the tip area of @tooltip to the area which @cell occupies in + line="4253">Sets the tip area of @tooltip to the area which @cell occupies in the item pointed to by @path. See also gtk_tooltip_set_tip_area(). See also gtk_icon_view_set_tooltip_column() for a simpler alternative. @@ -78898,19 +80924,19 @@ See also gtk_icon_view_set_tooltip_column() for a simpler alternative. a `GtkIconView` + line="4255">a `GtkIconView` a `GtkTooltip` + line="4256">a `GtkTooltip` a `GtkTreePath` + line="4257">a `GtkTreePath` allow-none="1"> a `GtkCellRenderer` + line="4258">a `GtkCellRenderer` @@ -78931,7 +80957,7 @@ See also gtk_icon_view_set_tooltip_column() for a simpler alternative. deprecated-version="4.10"> If you only plan to have simple (text-only) tooltips on full items, you + line="4390">If you only plan to have simple (text-only) tooltips on full items, you can use this function to have `GtkIconView` handle these automatically for you. @column should be set to the column in @icon_view’s model containing the tooltip texts, or -1 to disable this feature. @@ -78950,13 +80976,13 @@ so &, <, etc have to be escaped in the text. a `GtkIconView` + line="4392">a `GtkIconView` an integer, which is a valid column number for @icon_view’s model + line="4393">an integer, which is a valid column number for @icon_view’s model @@ -78967,7 +80993,7 @@ so &, <, etc have to be escaped in the text. deprecated-version="4.10"> Sets the tip area of @tooltip to be the area covered by the item at @path. + line="4230">Sets the tip area of @tooltip to be the area covered by the item at @path. See also gtk_icon_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). Use [class@Gtk.GridView] instead @@ -78979,19 +81005,19 @@ See also gtk_tooltip_set_tip_area(). a `GtkIconView` + line="4232">a `GtkIconView` a `GtkTooltip` + line="4233">a `GtkTooltip` a `GtkTreePath` + line="4234">a `GtkTreePath` @@ -79002,7 +81028,7 @@ See also gtk_tooltip_set_tip_area(). deprecated-version="4.10"> Unselects all the icons. + line="5137">Unselects all the icons. Use [class@Gtk.GridView] instead @@ -79012,7 +81038,7 @@ See also gtk_tooltip_set_tip_area(). A `GtkIconView`. + line="5139">A `GtkIconView`. @@ -79023,7 +81049,7 @@ See also gtk_tooltip_set_tip_area(). deprecated-version="4.10"> Unselects the row at @path. + line="5025">Unselects the row at @path. Use [class@Gtk.GridView] instead @@ -79033,13 +81059,13 @@ See also gtk_tooltip_set_tip_area(). A `GtkIconView`. + line="5027">A `GtkIconView`. The `GtkTreePath` to be unselected. + line="5028">The `GtkTreePath` to be unselected. @@ -79050,7 +81076,7 @@ See also gtk_tooltip_set_tip_area(). deprecated-version="4.10"> Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this + line="6468">Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead @@ -79061,7 +81087,7 @@ method sets `GtkIconView`:reorderable to %FALSE. a `GtkIconView` + line="6470">a `GtkIconView` @@ -79072,7 +81098,7 @@ method sets `GtkIconView`:reorderable to %FALSE. deprecated-version="4.10"> Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this + line="6445">Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead @@ -79083,7 +81109,7 @@ method sets `GtkIconView`:reorderable to %FALSE. a `GtkIconView` + line="6447">a `GtkIconView` @@ -79096,7 +81122,7 @@ method sets `GtkIconView`:reorderable to %FALSE. default-value="FALSE"> The activate-on-single-click property specifies whether the "item-activated" signal + line="569">The activate-on-single-click property specifies whether the "item-activated" signal will be emitted after a single click. @@ -79106,7 +81132,7 @@ will be emitted after a single click. transfer-ownership="none"> The `GtkCellArea` used to layout cell renderers for this view. + line="555">The `GtkCellArea` used to layout cell renderers for this view. If no area is specified when creating the icon view with gtk_icon_view_new_with_area() a `GtkCellAreaBox` will be used. @@ -79120,7 +81146,7 @@ a `GtkCellAreaBox` will be used. default-value="6"> The column-spacing property specifies the space which is inserted between + line="480">The column-spacing property specifies the space which is inserted between the columns of the icon view. @@ -79132,7 +81158,7 @@ the columns of the icon view. default-value="-1"> The columns property contains the number of the columns in which the + line="429">The columns property contains the number of the columns in which the items should be displayed. If it is -1, the number of columns will be chosen automatically to fill the available area. @@ -79145,7 +81171,7 @@ be chosen automatically to fill the available area. default-value="GTK_ORIENTATION_VERTICAL"> The item-orientation property specifies how the cells (i.e. the icon and + line="504">The item-orientation property specifies how the cells (i.e. the icon and the text) of the item are positioned relative to each other. @@ -79157,7 +81183,7 @@ the text) of the item are positioned relative to each other. default-value="6"> The item-padding property specifies the padding around each + line="543">The item-padding property specifies the padding around each of the icon view's item. @@ -79169,7 +81195,7 @@ of the icon view's item. default-value="-1"> The item-width property specifies the width to use for each item. + line="443">The item-width property specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. @@ -79182,7 +81208,7 @@ suitable item size. default-value="6"> The margin property specifies the space which is inserted + line="492">The margin property specifies the space which is inserted at the edges of the icon view. @@ -79194,7 +81220,7 @@ at the edges of the icon view. default-value="-1"> The ::markup-column property contains the number of the model column + line="403">The ::markup-column property contains the number of the model column containing markup information to be displayed. The markup column must be of type `G_TYPE_STRING`. If this property and the :text-column property are both set to column numbers, it overrides the text column. @@ -79206,6 +81232,9 @@ If both are set to -1, no texts are displayed. transfer-ownership="none" setter="set_model" getter="get_model"> + The model of the icon view. default-value="-1"> The ::pixbuf-column property contains the number of the model column + line="374">The ::pixbuf-column property contains the number of the model column containing the pixbufs which are displayed. The pixbuf column must be of type `GDK_TYPE_PIXBUF`. Setting this property to -1 turns off the display of pixbufs. @@ -79230,7 +81259,7 @@ display of pixbufs. default-value="FALSE"> The reorderable property specifies if the items can be reordered + line="517">The reorderable property specifies if the items can be reordered by DND. @@ -79242,7 +81271,7 @@ by DND. default-value="6"> The row-spacing property specifies the space which is inserted between + line="468">The row-spacing property specifies the space which is inserted between the rows of the icon view. @@ -79254,7 +81283,7 @@ the rows of the icon view. default-value="GTK_SELECTION_SINGLE"> The ::selection-mode property specifies the selection mode of + line="360">The ::selection-mode property specifies the selection mode of icon view. If the mode is %GTK_SELECTION_MULTIPLE, rubberband selection is enabled, for the other modes, only keyboard selection is possible. @@ -79267,7 +81296,7 @@ is enabled, for the other modes, only keyboard selection is possible. default-value="0"> The spacing property specifies the space which is inserted between + line="456">The spacing property specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. @@ -79279,7 +81308,7 @@ the cells (i.e. the icon and the text) of an item. default-value="-1"> The ::text-column property contains the number of the model column + line="388">The ::text-column property contains the number of the model column containing the texts which are displayed. The text column must be of type `G_TYPE_STRING`. If this property and the :markup-column property are both set to -1, no texts are displayed. @@ -79291,12 +81320,16 @@ property are both set to -1, no texts are displayed. setter="set_tooltip_column" getter="get_tooltip_column" default-value="-1"> + The column of the icon view model which is being used for displaying +tooltips on it's rows. A [keybinding signal][class@Gtk.SignalAction] + line="718">A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user activates the currently focused item. @@ -79306,13 +81339,16 @@ programmatically. The default bindings for this signal are Space, Return and Enter. + whether the item was activated The ::item-activated signal is emitted when the method + line="588">The ::item-activated signal is emitted when the method gtk_icon_view_item_activated() is called, when the user double clicks an item with the "activate-on-single-click" property set to %FALSE, or when the user single clicks an item when the @@ -79326,7 +81362,7 @@ Space, Return or Enter is pressed. the `GtkTreePath` for the activated item + line="591">the `GtkTreePath` for the activated item @@ -79334,7 +81370,7 @@ Space, Return or Enter is pressed. The ::move-cursor signal is a + line="746">The ::move-cursor signal is a [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user initiates a cursor movement. @@ -79349,31 +81385,34 @@ The default bindings for this signal include All of these will extend the selection when combined with the Shift modifier. + whether the cursor was moved the granularity of the move, as a `GtkMovementStep` + line="749">the granularity of the move, as a `GtkMovementStep` the number of @step units to move + line="750">the number of @step units to move whether to extend the selection + line="751">whether to extend the selection whether to modify the selection + line="752">whether to modify the selection @@ -79381,7 +81420,7 @@ the Shift modifier. A [keybinding signal][class@Gtk.SignalAction] + line="627">A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user selects all items. Applications should not connect to it, but may emit it with @@ -79396,7 +81435,7 @@ The default binding for this signal is Ctrl-a. A [keybinding signal][class@Gtk.SignalAction] + line="671">A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user selects the item that is currently focused. @@ -79412,7 +81451,7 @@ There is no default binding for this signal. The ::selection-changed signal is emitted when the selection + line="611">The ::selection-changed signal is emitted when the selection (i.e. the set of selected items) changes. @@ -79421,7 +81460,7 @@ There is no default binding for this signal. A [keybinding signal][class@Gtk.SignalAction] + line="694">A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user toggles whether the currently focused item is selected or not. The exact effect of this depend on the selection mode. @@ -79438,7 +81477,7 @@ There is no default binding for this signal is Ctrl-Space. A [keybinding signal][class@Gtk.SignalAction] + line="649">A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user unselects all items. Applications should not connect to it, but may emit it with @@ -79557,9 +81596,12 @@ It will be called on every selected row in the view. glib:get-type="gtk_image_get_type"> The `GtkImage` widget displays an image. + line="40">Displays an image. -![An example GtkImage](image.png) +picture> + <source srcset="image-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkImage" src="image.png"> +</picture> Various kinds of object can be displayed as an image; most typically, you would load a `GdkTexture` from a file, using the convenience function @@ -79595,26 +81637,26 @@ at is actual size. ## Accessibility -`GtkImage` uses the `GTK_ACCESSIBLE_ROLE_IMG` role. +`GtkImage` uses the [enum@Gtk.AccessibleRole.img] role. Creates a new empty `GtkImage` widget. + line="953">Creates a new empty `GtkImage` widget. a newly created `GtkImage` widget. + line="958">a newly created `GtkImage` widget. Creates a new `GtkImage` displaying the file @filename. + line="399">Creates a new `GtkImage` displaying the file @filename. If the file isn’t found or can’t be loaded, the resulting `GtkImage` will display a “broken image” icon. This function never returns %NULL, @@ -79631,14 +81673,14 @@ is appropriate for displaying the file. a new `GtkImage` + line="417">a new `GtkImage` a filename + line="401">a filename @@ -79647,7 +81689,7 @@ is appropriate for displaying the file. c:identifier="gtk_image_new_from_gicon"> Creates a `GtkImage` displaying an icon from the current icon theme. + line="550">Creates a `GtkImage` displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon @@ -79656,14 +81698,14 @@ will be updated appropriately. a new `GtkImage` displaying the themed icon + line="560">a new `GtkImage` displaying the themed icon an icon + line="552">an icon @@ -79672,7 +81714,7 @@ will be updated appropriately. c:identifier="gtk_image_new_from_icon_name"> Creates a `GtkImage` displaying an icon from the current icon theme. + line="526">Creates a `GtkImage` displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon @@ -79681,7 +81723,7 @@ will be updated appropriately. a new `GtkImage` displaying the themed icon + line="536">a new `GtkImage` displaying the themed icon @@ -79691,7 +81733,7 @@ will be updated appropriately. allow-none="1"> an icon name + line="528">an icon name @@ -79700,7 +81742,7 @@ will be updated appropriately. c:identifier="gtk_image_new_from_paintable"> Creates a new `GtkImage` displaying @paintable. + line="499">Creates a new `GtkImage` displaying @paintable. The `GtkImage` does not assume a reference to the paintable; you still need to unref it if you own references. `GtkImage` will add its own @@ -79712,7 +81754,7 @@ its size and contents in response to it. a new `GtkImage` + line="512">a new `GtkImage` @@ -79722,7 +81764,7 @@ its size and contents in response to it. allow-none="1"> a `GdkPaintable` + line="501">a `GdkPaintable` @@ -79733,7 +81775,7 @@ its size and contents in response to it. deprecated-version="4.12"> Creates a new `GtkImage` displaying @pixbuf. + line="463">Creates a new `GtkImage` displaying @pixbuf. The `GtkImage` does not assume a reference to the pixbuf; you still need to unref it if you own references. `GtkImage` will add its own @@ -79751,7 +81793,7 @@ want that, you should use [ctor@Gtk.Image.new_from_icon_name]. a new `GtkImage` + line="480">a new `GtkImage` @@ -79761,7 +81803,7 @@ want that, you should use [ctor@Gtk.Image.new_from_icon_name]. allow-none="1"> a `GdkPixbuf` + line="465">a `GdkPixbuf` @@ -79770,7 +81812,7 @@ want that, you should use [ctor@Gtk.Image.new_from_icon_name]. c:identifier="gtk_image_new_from_resource"> Creates a new `GtkImage` displaying the resource file @resource_path. + line="431">Creates a new `GtkImage` displaying the resource file @resource_path. If the file isn’t found or can’t be loaded, the resulting `GtkImage` will display a “broken image” icon. This function never returns %NULL, @@ -79787,14 +81829,14 @@ appropriate for displaying the file. a new `GtkImage` + line="449">a new `GtkImage` a resource path + line="433">a resource path @@ -79802,7 +81844,7 @@ appropriate for displaying the file. Resets the image to be empty. + line="1153">Resets the image to be empty. @@ -79811,7 +81853,7 @@ appropriate for displaying the file. a `GtkImage` + line="1155">a `GtkImage` @@ -79819,10 +81861,9 @@ appropriate for displaying the file. - Gets the `GIcon` being displayed by the `GtkImage`. + line="932">Gets the `GIcon` being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see [method@Gtk.Image.get_storage_type]). @@ -79832,14 +81873,14 @@ returned `GIcon`. a `GIcon` + line="943">a `GIcon` a `GtkImage` + line="934">a `GtkImage` @@ -79847,10 +81888,9 @@ returned `GIcon`. - Gets the icon name and size being displayed by the `GtkImage`. + line="911">Gets the icon name and size being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see [method@Gtk.Image.get_storage_type]). @@ -79860,14 +81900,14 @@ be freed. the icon name + line="922">the icon name a `GtkImage` + line="913">a `GtkImage` @@ -79875,22 +81915,21 @@ be freed. - Gets the icon size used by the @image when rendering icons. + line="1277">Gets the icon size used by the @image when rendering icons. the image size used by icons + line="1283">the image size used by icons a `GtkImage` + line="1279">a `GtkImage` @@ -79898,10 +81937,9 @@ be freed. - Gets the image `GdkPaintable` being displayed by the `GtkImage`. + line="890">Gets the image `GdkPaintable` being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PAINTABLE (see [method@Gtk.Image.get_storage_type]). @@ -79911,14 +81949,14 @@ returned paintable. the displayed paintable + line="901">the displayed paintable a `GtkImage` + line="892">a `GtkImage` @@ -79926,22 +81964,21 @@ returned paintable. - Gets the pixel size used for named icons. + line="1240">Gets the pixel size used for named icons. the pixel size used for named icons. + line="1246">the pixel size used for named icons. a `GtkImage` + line="1242">a `GtkImage` @@ -79949,10 +81986,9 @@ returned paintable. - Gets the type of representation being used by the `GtkImage` + line="870">Gets the type of representation being used by the `GtkImage` to store image data. If the `GtkImage` has no image data, the return value will @@ -79961,23 +81997,24 @@ be %GTK_IMAGE_EMPTY. image representation being used + line="880">image representation being used a `GtkImage` + line="872">a `GtkImage` - - + Sets a `GtkImage` to show a file. + line="574">Sets a `GtkImage` to show a file. See [ctor@Gtk.Image.new_from_file] for details. @@ -79988,7 +82025,7 @@ See [ctor@Gtk.Image.new_from_file] for details. a `GtkImage` + line="576">a `GtkImage` allow-none="1"> a filename + line="577">a filename - - + Sets a `GtkImage` to show a `GIcon`. + line="773">Sets a `GtkImage` to show a `GIcon`. See [ctor@Gtk.Image.new_from_gicon] for details. @@ -80017,23 +82055,23 @@ See [ctor@Gtk.Image.new_from_gicon] for details. a `GtkImage` + line="775">a `GtkImage` an icon + line="776">an icon - + c:identifier="gtk_image_set_from_icon_name" + glib:set-property="icon-name"> Sets a `GtkImage` to show a named icon. + line="745">Sets a `GtkImage` to show a named icon. See [ctor@Gtk.Image.new_from_icon_name] for details. @@ -80044,7 +82082,7 @@ See [ctor@Gtk.Image.new_from_icon_name] for details. a `GtkImage` + line="747">a `GtkImage` allow-none="1"> an icon name + line="748">an icon name - + c:identifier="gtk_image_set_from_paintable" + glib:set-property="paintable"> Sets a `GtkImage` to show a `GdkPaintable`. + line="821">Sets a `GtkImage` to show a `GdkPaintable`. See [ctor@Gtk.Image.new_from_paintable] for details. @@ -80074,7 +82112,7 @@ See [ctor@Gtk.Image.new_from_paintable] for details. a `GtkImage` + line="823">a `GtkImage` allow-none="1"> a `GdkPaintable` + line="824">a `GdkPaintable` @@ -80092,10 +82130,9 @@ See [ctor@Gtk.Image.new_from_paintable] for details. c:identifier="gtk_image_set_from_pixbuf" deprecated="1" deprecated-version="4.12"> - Sets a `GtkImage` to show a `GdkPixbuf`. + line="710">Sets a `GtkImage` to show a `GdkPixbuf`. See [ctor@Gtk.Image.new_from_pixbuf] for details. @@ -80111,7 +82148,7 @@ only a paintable. a `GtkImage` + line="712">a `GtkImage` allow-none="1"> a `GdkPixbuf` or `NULL` + line="713">a `GdkPixbuf` or `NULL` - + c:identifier="gtk_image_set_from_resource" + glib:set-property="resource"> Sets a `GtkImage` to show a resource. + line="652">Sets a `GtkImage` to show a resource. See [ctor@Gtk.Image.new_from_resource] for details. @@ -80141,7 +82178,7 @@ See [ctor@Gtk.Image.new_from_resource] for details. a `GtkImage` + line="654">a `GtkImage` allow-none="1"> a resource path + line="655">a resource path @@ -80158,10 +82195,9 @@ See [ctor@Gtk.Image.new_from_resource] for details. - Suggests an icon size to the theme for named icons. + line="1256">Suggests an icon size to the theme for named icons. @@ -80170,13 +82206,13 @@ See [ctor@Gtk.Image.new_from_resource] for details. a `GtkImage` + line="1258">a `GtkImage` the new icon size + line="1259">the new icon size @@ -80184,10 +82220,9 @@ See [ctor@Gtk.Image.new_from_resource] for details. - Sets the pixel size to use for named icons. + line="1216">Sets the pixel size to use for named icons. If the pixel size is set to a value != -1, it is used instead of the icon size set by [method@Gtk.Image.set_from_icon_name]. @@ -80199,13 +82234,13 @@ of the icon size set by [method@Gtk.Image.set_from_icon_name]. a `GtkImage` + line="1218">a `GtkImage` the new pixel size + line="1219">the new pixel size @@ -80218,19 +82253,17 @@ of the icon size set by [method@Gtk.Image.set_from_icon_name]. value="gtk_image_set_from_file"/> The `GFile` to display. + line="184">A path to the file to display. - - The `GIcon` displayed in the GtkImage. + line="232">The `GIcon` displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. @@ -80239,15 +82272,12 @@ automatically. - - The name of the icon in the icon theme. + line="220">The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. @@ -80258,26 +82288,19 @@ If the icon theme is changed, the image will be updated automatically. setter="set_icon_size" getter="get_icon_size" default-value="GTK_ICON_SIZE_INHERIT"> - - The symbolic size to display icons at. + line="194">The symbolic size to display icons at. - - The `GdkPaintable` to display. + line="174">The `GdkPaintable` to display. setter="set_pixel_size" getter="get_pixel_size" default-value="-1"> - - The size in pixels to display icons at. + line="205">The size in pixels to display icons at. If set to a value != -1, this property overrides the [property@Gtk.Image:icon-size] property for images of type @@ -80307,18 +82326,16 @@ If set to a value != -1, this property overrides the value="gtk_image_set_from_resource"/> A path to a resource file to display. + line="245">A path to a resource file to display. - The representation being used for image data. + line="255">The representation being used for image data. Whether the icon displayed in the `GtkImage` will use + line="266">Whether the icon displayed in the `GtkImage` will use standard icon names fallback. The value of this property is only relevant for images of type @@ -80398,7 +82415,10 @@ functions), but they will all return %NULL values. filename="gtk/deprecated/gtkinfobar.c" line="54">`GtkInfoBar` can be used to show messages to the user without a dialog. -![An example GtkInfoBar](info-bar.png) +<picture> + <source srcset="info-bar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkInfoBar" src="info-bar.png"> +</picture> It is often temporarily shown at the top or bottom of a document. In contrast to [class@Gtk.Dialog], which has an action area at the @@ -80482,12 +82502,12 @@ style class applied. deprecated-version="4.10"> Creates a new `GtkInfoBar` object. + line="718">Creates a new `GtkInfoBar` object. a new `GtkInfoBar` object + line="723">a new `GtkInfoBar` object @@ -80498,7 +82518,7 @@ style class applied. deprecated-version="4.10"> Creates a new `GtkInfoBar` with buttons. + line="733">Creates a new `GtkInfoBar` with buttons. Button text/response ID pairs should be listed, with a %NULL pointer ending the list. A response ID can be any positive number, @@ -80510,7 +82530,7 @@ response ID. a new `GtkInfoBar` + line="748">a new `GtkInfoBar` @@ -80520,13 +82540,13 @@ response ID. allow-none="1"> ext to go in first button + line="735">ext to go in first button response ID for first button, then additional buttons, ending + line="736">response ID for first button, then additional buttons, ending with %NULL @@ -80538,7 +82558,7 @@ response ID. deprecated-version="4.10"> Add an activatable widget to the action area of a `GtkInfoBar`. + line="549">Add an activatable widget to the action area of a `GtkInfoBar`. This also connects a signal handler that will emit the [signal@Gtk.InfoBar::response] signal on the message area @@ -80552,19 +82572,19 @@ end of the message areas action area. a `GtkInfoBar` + line="551">a `GtkInfoBar` an activatable widget + line="552">an activatable widget response ID for @child + line="553">response ID for @child @@ -80575,7 +82595,7 @@ end of the message areas action area. deprecated-version="4.10"> Adds a button with the given text. + line="624">Adds a button with the given text. Clicking the button will emit the [signal@Gtk.InfoBar::response] signal with the given response_id. The button is appended to the @@ -80585,7 +82605,7 @@ but usually you don't need it. the `GtkButton` widget + line="637">the `GtkButton` widget that was added @@ -80593,19 +82613,19 @@ that was added a `GtkInfoBar` + line="626">a `GtkInfoBar` text of button + line="627">text of button response ID for the button + line="628">response ID for the button @@ -80617,7 +82637,7 @@ that was added deprecated-version="4.10"> Adds multiple buttons. + line="690">Adds multiple buttons. This is the same as calling [method@Gtk.InfoBar.add_button] repeatedly. The variable argument list should be %NULL-terminated @@ -80631,19 +82651,19 @@ text and response ID. a `GtkInfoBar` + line="692">a `GtkInfoBar` button text + line="693">button text response ID for first button, then more text-response_id pairs, + line="694">response ID for first button, then more text-response_id pairs, ending with %NULL @@ -80655,7 +82675,7 @@ text and response ID. deprecated-version="4.10"> Adds a widget to the content area of the info bar. + line="1258">Adds a widget to the content area of the info bar. @@ -80664,13 +82684,13 @@ text and response ID. a `GtkInfoBar` + line="1260">a `GtkInfoBar` the child to be added + line="1261">the child to be added @@ -80680,22 +82700,21 @@ text and response ID. glib:get-property="message-type" deprecated="1" deprecated-version="4.10"> - Returns the message type of the message area. + line="1150">Returns the message type of the message area. the message type of the message area. + line="1156">the message type of the message area. a `GtkInfoBar` + line="1152">a `GtkInfoBar` @@ -80705,22 +82724,21 @@ text and response ID. glib:get-property="revealed" deprecated="1" deprecated-version="4.10"> - Returns whether the info bar is currently revealed. + line="1240">Returns whether the info bar is currently revealed. the current value of the [property@Gtk.InfoBar:revealed] property + line="1246">the current value of the [property@Gtk.InfoBar:revealed] property a `GtkInfoBar` + line="1242">a `GtkInfoBar` @@ -80730,23 +82748,21 @@ text and response ID. glib:get-property="show-close-button" deprecated="1" deprecated-version="4.10"> - Returns whether the widget will display a standard close button. + line="1193">Returns whether the widget will display a standard close button. %TRUE if the widget displays standard close button + line="1199">%TRUE if the widget displays standard close button a `GtkInfoBar` + line="1195">a `GtkInfoBar` @@ -80757,7 +82773,7 @@ text and response ID. deprecated-version="4.10"> Removes a widget from the action area of @info_bar. + line="599">Removes a widget from the action area of @info_bar. The widget must have been put there by a call to [method@Gtk.InfoBar.add_action_widget] or [method@Gtk.InfoBar.add_button]. @@ -80769,13 +82785,13 @@ The widget must have been put there by a call to a `GtkInfoBar` + line="601">a `GtkInfoBar` an action widget to remove + line="602">an action widget to remove @@ -80786,7 +82802,7 @@ The widget must have been put there by a call to deprecated-version="4.10"> Removes a widget from the content area of the info bar. + line="1277">Removes a widget from the content area of the info bar. @@ -80795,13 +82811,13 @@ The widget must have been put there by a call to a `GtkInfoBar` + line="1279">a `GtkInfoBar` a child that has been added to the content area + line="1280">a child that has been added to the content area @@ -80812,7 +82828,7 @@ The widget must have been put there by a call to deprecated-version="4.10"> Emits the “response” signal with the given @response_id. + line="863">Emits the “response” signal with the given @response_id. @@ -80821,13 +82837,13 @@ The widget must have been put there by a call to a `GtkInfoBar` + line="865">a `GtkInfoBar` a response ID + line="866">a response ID @@ -80838,7 +82854,7 @@ The widget must have been put there by a call to deprecated-version="4.10"> Sets the last widget in the info bar’s action area with + line="819">Sets the last widget in the info bar’s action area with the given response_id as the default widget for the dialog. Pressing “Enter” normally activates the default widget. @@ -80853,13 +82869,13 @@ be added to a widget hierarchy. a `GtkInfoBar` + line="821">a `GtkInfoBar` a response ID + line="822">a response ID @@ -80869,10 +82885,9 @@ be added to a widget hierarchy. glib:set-property="message-type" deprecated="1" deprecated-version="4.10"> - Sets the message type of the message area. + line="1109">Sets the message type of the message area. GTK uses this type to determine how the message is displayed. @@ -80883,13 +82898,13 @@ GTK uses this type to determine how the message is displayed. a `GtkInfoBar` + line="1111">a `GtkInfoBar` a `GtkMessageType` + line="1112">a `GtkMessageType` @@ -80900,7 +82915,7 @@ GTK uses this type to determine how the message is displayed. deprecated-version="4.10"> Sets the sensitivity of action widgets for @response_id. + line="782">Sets the sensitivity of action widgets for @response_id. Calls `gtk_widget_set_sensitive (widget, setting)` for each widget in the info bars’s action area with the given @response_id. @@ -80913,19 +82928,19 @@ A convenient way to sensitize/desensitize buttons. a `GtkInfoBar` + line="784">a `GtkInfoBar` a response ID + line="785">a response ID TRUE for sensitive + line="786">TRUE for sensitive @@ -80935,10 +82950,9 @@ A convenient way to sensitize/desensitize buttons. glib:set-property="revealed" deprecated="1" deprecated-version="4.10"> - Sets whether the `GtkInfoBar` is revealed. + line="1211">Sets whether the `GtkInfoBar` is revealed. Changing this will make @info_bar reveal or conceal itself via a sliding transition. @@ -80954,13 +82968,13 @@ if [property@Gtk.Widget:visible] is %FALSE. a `GtkInfoBar` + line="1213">a `GtkInfoBar` The new value of the property + line="1214">The new value of the property @@ -80970,11 +82984,9 @@ if [property@Gtk.Widget:visible] is %FALSE. glib:set-property="show-close-button" deprecated="1" deprecated-version="4.10"> - If true, a standard close button is shown. + line="1169">If true, a standard close button is shown. When clicked it emits the response %GTK_RESPONSE_CLOSE. @@ -80985,13 +82997,13 @@ When clicked it emits the response %GTK_RESPONSE_CLOSE. a `GtkInfoBar` + line="1171">a `GtkInfoBar` %TRUE to include a close button + line="1172">%TRUE to include a close button @@ -81003,13 +83015,9 @@ When clicked it emits the response %GTK_RESPONSE_CLOSE. setter="set_message_type" getter="get_message_type" default-value="GTK_MESSAGE_INFO"> - - The type of the message. + line="360">The type of the message. The type may be used to determine the appearance of the info bar. @@ -81020,13 +83028,9 @@ The type may be used to determine the appearance of the info bar. setter="set_revealed" getter="get_revealed" default-value="TRUE"> - - Whether the info bar shows its contents. + line="383">Whether the info bar shows its contents. setter="set_show_close_button" getter="get_show_close_button" default-value="FALSE"> - - Whether to include a standard close button. + line="373">Whether to include a standard close button. Gets emitted when the user uses a keybinding to dismiss the info bar. + line="415">Gets emitted when the user uses a keybinding to dismiss the info bar. The ::close signal is a [keybinding signal](class.SignalAction.html). @@ -81060,7 +83060,7 @@ The default binding for this signal is the Escape key. Emitted when an action widget is clicked. + line="395">Emitted when an action widget is clicked. The signal is also emitted when the application programmer calls [method@Gtk.InfoBar.response]. The @response_id depends @@ -81072,7 +83072,7 @@ on which action widget was clicked. the response ID + line="398">the response ID @@ -81084,7 +83084,7 @@ on which action widget was clicked. c:type="GtkInputHints"> Describes hints that might be taken into account by input methods + line="969">Describes hints that might be taken into account by input methods or applications. Note that input methods may already tailor their behaviour according @@ -81102,7 +83102,7 @@ ignore unknown values. glib:name="GTK_INPUT_HINT_NONE"> No special behaviour suggested + line="971">No special behaviour suggested glib:name="GTK_INPUT_HINT_SPELLCHECK"> Suggest checking for typos + line="972">Suggest checking for typos glib:name="GTK_INPUT_HINT_NO_SPELLCHECK"> Suggest not checking for typos + line="973">Suggest not checking for typos glib:name="GTK_INPUT_HINT_WORD_COMPLETION"> Suggest word completion + line="974">Suggest word completion glib:name="GTK_INPUT_HINT_LOWERCASE"> Suggest to convert all text to lowercase + line="975">Suggest to convert all text to lowercase glib:name="GTK_INPUT_HINT_UPPERCASE_CHARS"> Suggest to capitalize all text + line="976">Suggest to capitalize all text glib:name="GTK_INPUT_HINT_UPPERCASE_WORDS"> Suggest to capitalize the first + line="977">Suggest to capitalize the first character of each word glib:name="GTK_INPUT_HINT_UPPERCASE_SENTENCES"> Suggest to capitalize the + line="979">Suggest to capitalize the first word of each sentence glib:name="GTK_INPUT_HINT_INHIBIT_OSK"> Suggest to not show an onscreen keyboard + line="981">Suggest to not show an onscreen keyboard (e.g for a calculator that already has all the keys). glib:name="GTK_INPUT_HINT_VERTICAL_WRITING"> The text is vertical + line="983">The text is vertical glib:name="GTK_INPUT_HINT_EMOJI"> Suggest offering Emoji support + line="984">Suggest offering Emoji support glib:name="GTK_INPUT_HINT_NO_EMOJI"> Suggest not offering Emoji support + line="985">Suggest not offering Emoji support glib:name="GTK_INPUT_HINT_PRIVATE"> Request that the input method should not + line="986">Request that the input method should not update personalized data (like typing history) @@ -81223,7 +83223,7 @@ ignore unknown values. c:type="GtkInputPurpose"> Describes primary purpose of the input widget. + line="920">Describes primary purpose of the input widget. This information is useful for on-screen keyboards and similar input methods to decide which keys should be presented to the user. @@ -81249,7 +83249,7 @@ interpret unknown values as “free form”. glib:name="GTK_INPUT_PURPOSE_FREE_FORM"> Allow any character + line="922">Allow any character glib:name="GTK_INPUT_PURPOSE_ALPHA"> Allow only alphabetic characters + line="923">Allow only alphabetic characters glib:name="GTK_INPUT_PURPOSE_DIGITS"> Allow only digits + line="924">Allow only digits glib:name="GTK_INPUT_PURPOSE_NUMBER"> Edited field expects numbers + line="925">Edited field expects numbers glib:name="GTK_INPUT_PURPOSE_PHONE"> Edited field expects phone number + line="926">Edited field expects phone number glib:name="GTK_INPUT_PURPOSE_URL"> Edited field expects URL + line="927">Edited field expects URL glib:name="GTK_INPUT_PURPOSE_EMAIL"> Edited field expects email address + line="928">Edited field expects email address glib:name="GTK_INPUT_PURPOSE_NAME"> Edited field expects the name of a person + line="929">Edited field expects the name of a person glib:name="GTK_INPUT_PURPOSE_PASSWORD"> Like %GTK_INPUT_PURPOSE_FREE_FORM, but characters are hidden + line="930">Like %GTK_INPUT_PURPOSE_FREE_FORM, but characters are hidden glib:name="GTK_INPUT_PURPOSE_PIN"> Like %GTK_INPUT_PURPOSE_DIGITS, but characters are hidden + line="931">Like %GTK_INPUT_PURPOSE_DIGITS, but characters are hidden glib:name="GTK_INPUT_PURPOSE_TERMINAL"> Allow any character, in addition to control codes + line="932">Allow any character, in addition to control codes glib:type-struct="InscriptionClass"> `GtkInscription` is a widget to show text in a predefined area. + line="35">Shows text in a predefined area. You likely want to use `GtkLabel` instead as this widget is intended only for a small subset of use cases. The main scenario envisaged is inside lists @@ -81363,20 +83363,25 @@ While a `GtkLabel` sizes itself depending on the text that is displayed, space as well as it can. Users of this widget should take care to plan behaviour for the common case -where the text doesn't fit exactly in the allocated space. +where the text doesn't fit exactly in the allocated space. + +## CSS nodes + +`GtkInscription` has a single CSS node with the name label. + Creates a new `GtkInscription` with the given text. + line="806">Creates a new `GtkInscription` with the given text. a new `GtkInscription` + line="812">a new `GtkInscription` @@ -81386,7 +83391,7 @@ where the text doesn't fit exactly in the allocated space. allow-none="1"> The text to display. + line="808">The text to display. @@ -81395,22 +83400,21 @@ where the text doesn't fit exactly in the allocated space. c:identifier="gtk_inscription_get_attributes" glib:get-property="attributes" version="4.8"> - Gets the inscription's attribute list. + line="1200">Gets the inscription's attribute list. the attribute list + line="1206">the attribute list a `GtkInscription` + line="1202">a `GtkInscription` @@ -81419,24 +83423,23 @@ where the text doesn't fit exactly in the allocated space. c:identifier="gtk_inscription_get_min_chars" glib:get-property="min-chars" version="4.8"> - Gets the `min-chars` of the inscription. + line="905">Gets the `min-chars` of the inscription. See the [property@Gtk.Inscription:min-chars] property. the min-chars property + line="913">the min-chars property a `GtkInscription` + line="907">a `GtkInscription` @@ -81445,24 +83448,23 @@ See the [property@Gtk.Inscription:min-chars] property. c:identifier="gtk_inscription_get_min_lines" glib:get-property="min-lines" version="4.8"> - Gets the `min-lines` of the inscription. + line="999">Gets the `min-lines` of the inscription. See the [property@Gtk.Inscription:min-lines] property. the min-lines property + line="1007">the min-lines property a `GtkInscription` + line="1001">a `GtkInscription` @@ -81471,24 +83473,23 @@ See the [property@Gtk.Inscription:min-lines] property. c:identifier="gtk_inscription_get_nat_chars" glib:get-property="nat-chars" version="4.8"> - Gets the `nat-chars` of the inscription. + line="952">Gets the `nat-chars` of the inscription. See the [property@Gtk.Inscription:nat-chars] property. the nat-chars property + line="960">the nat-chars property a `GtkInscription` + line="954">a `GtkInscription` @@ -81497,24 +83498,23 @@ See the [property@Gtk.Inscription:nat-chars] property. c:identifier="gtk_inscription_get_nat_lines" glib:get-property="nat-lines" version="4.8"> - Gets the `nat-lines` of the inscription. + line="1046">Gets the `nat-lines` of the inscription. See the [property@Gtk.Inscription:nat-lines] property. the nat-lines property + line="1054">the nat-lines property a `GtkInscription` + line="1048">a `GtkInscription` @@ -81523,22 +83523,21 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_get_text" glib:get-property="text" version="4.8"> - Gets the text that is displayed. + line="860">Gets the text that is displayed. The displayed text + line="866">The displayed text a `GtkInscription` + line="862">a `GtkInscription` @@ -81547,22 +83546,21 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_get_text_overflow" glib:get-property="text-overflow" version="4.8"> - Gets the inscription's overflow method. + line="1262">Gets the inscription's overflow method. the overflow method + line="1268">the overflow method a `GtkInscription` + line="1264">a `GtkInscription` @@ -81571,24 +83569,23 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_get_wrap_mode" glib:get-property="wrap-mode" version="4.8"> - Returns line wrap mode used by the inscription. + line="1305">Returns line wrap mode used by the inscription. See [method@Gtk.Inscription.set_wrap_mode]. the line wrap mode + line="1313">the line wrap mode a `GtkInscription` + line="1307">a `GtkInscription` @@ -81597,24 +83594,23 @@ See [method@Gtk.Inscription.set_wrap_mode]. c:identifier="gtk_inscription_get_xalign" glib:get-property="xalign" version="4.8"> - Gets the `xalign` of the inscription. + line="1097">Gets the `xalign` of the inscription. See the [property@Gtk.Inscription:xalign] property. the xalign property + line="1105">the xalign property a `GtkInscription` + line="1099">a `GtkInscription` @@ -81623,24 +83619,23 @@ See the [property@Gtk.Inscription:xalign] property. c:identifier="gtk_inscription_get_yalign" glib:get-property="yalign" version="4.8"> - Gets the `yalign` of the inscription. + line="1146">Gets the `yalign` of the inscription. See the [property@Gtk.Inscription:yalign] property. the yalign property + line="1154">the yalign property a `GtkInscription` + line="1148">a `GtkInscription` @@ -81649,10 +83644,9 @@ See the [property@Gtk.Inscription:yalign] property. c:identifier="gtk_inscription_set_attributes" glib:set-property="attributes" version="4.8"> - Apply attributes to the inscription text. + line="1166">Apply attributes to the inscription text. These attributes will not be evaluated for sizing the inscription. @@ -81663,7 +83657,7 @@ These attributes will not be evaluated for sizing the inscription. a `GtkInscription` + line="1168">a `GtkInscription` allow-none="1"> a [struct@Pango.AttrList] + line="1169">a [struct@Pango.AttrList] @@ -81681,10 +83675,9 @@ These attributes will not be evaluated for sizing the inscription. c:identifier="gtk_inscription_set_markup" glib:set-property="markup" version="4.8"> - Utility function to set the text and attributes to be displayed. + line="1325">Utility function to set the text and attributes to be displayed. See the [property@Gtk.Inscription:markup] property. @@ -81695,7 +83688,7 @@ See the [property@Gtk.Inscription:markup] property. a `GtkInscription` + line="1327">a `GtkInscription` allow-none="1"> The markup to display + line="1328">The markup to display @@ -81713,10 +83706,9 @@ See the [property@Gtk.Inscription:markup] property. c:identifier="gtk_inscription_set_min_chars" glib:set-property="min-chars" version="4.8"> - Sets the `min-chars` of the inscription. + line="878">Sets the `min-chars` of the inscription. See the [property@Gtk.Inscription:min-chars] property. @@ -81727,13 +83719,13 @@ See the [property@Gtk.Inscription:min-chars] property. a `GtkInscription` + line="880">a `GtkInscription` the minimum number of characters that should fit, approximately + line="881">the minimum number of characters that should fit, approximately @@ -81742,10 +83734,9 @@ See the [property@Gtk.Inscription:min-chars] property. c:identifier="gtk_inscription_set_min_lines" glib:set-property="min-lines" version="4.8"> - Sets the `min-lines` of the inscription. + line="972">Sets the `min-lines` of the inscription. See the [property@Gtk.Inscription:min-lines] property. @@ -81756,13 +83747,13 @@ See the [property@Gtk.Inscription:min-lines] property. a `GtkInscription` + line="974">a `GtkInscription` the minimum number of lines that should fit, approximately + line="975">the minimum number of lines that should fit, approximately @@ -81771,10 +83762,9 @@ See the [property@Gtk.Inscription:min-lines] property. c:identifier="gtk_inscription_set_nat_chars" glib:set-property="nat-chars" version="4.8"> - Sets the `nat-chars` of the inscription. + line="925">Sets the `nat-chars` of the inscription. See the [property@Gtk.Inscription:nat-chars] property. @@ -81785,13 +83775,13 @@ See the [property@Gtk.Inscription:nat-chars] property. a `GtkInscription` + line="927">a `GtkInscription` the number of characters that should ideally fit, approximately + line="928">the number of characters that should ideally fit, approximately @@ -81800,10 +83790,9 @@ See the [property@Gtk.Inscription:nat-chars] property. c:identifier="gtk_inscription_set_nat_lines" glib:set-property="nat-lines" version="4.8"> - Sets the `nat-lines` of the inscription. + line="1019">Sets the `nat-lines` of the inscription. See the [property@Gtk.Inscription:nat-lines] property. @@ -81814,13 +83803,13 @@ See the [property@Gtk.Inscription:nat-lines] property. a `GtkInscription` + line="1021">a `GtkInscription` the number of lines that should ideally fit + line="1022">the number of lines that should ideally fit @@ -81829,10 +83818,9 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_set_text" glib:set-property="text" version="4.8"> - Sets the text to be displayed. + line="824">Sets the text to be displayed. @@ -81841,7 +83829,7 @@ See the [property@Gtk.Inscription:nat-lines] property. a `GtkInscription` + line="826">a `GtkInscription` allow-none="1"> The text to display + line="827">The text to display @@ -81859,10 +83847,9 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_set_text_overflow" glib:set-property="text-overflow" version="4.8"> - Sets what to do when the text doesn't fit. + line="1218">Sets what to do when the text doesn't fit. @@ -81871,13 +83858,13 @@ See the [property@Gtk.Inscription:nat-lines] property. a `GtkInscription` + line="1220">a `GtkInscription` the overflow method to use + line="1221">the overflow method to use @@ -81886,10 +83873,9 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_set_wrap_mode" glib:set-property="wrap-mode" version="4.8"> - Controls how line wrapping is done. + line="1280">Controls how line wrapping is done. @@ -81898,13 +83884,13 @@ See the [property@Gtk.Inscription:nat-lines] property. a `GtkInscription` + line="1282">a `GtkInscription` the line wrapping mode + line="1283">the line wrapping mode @@ -81913,10 +83899,9 @@ See the [property@Gtk.Inscription:nat-lines] property. c:identifier="gtk_inscription_set_xalign" glib:set-property="xalign" version="4.8"> - Sets the `xalign` of the inscription. + line="1066">Sets the `xalign` of the inscription. See the [property@Gtk.Inscription:xalign] property. @@ -81927,13 +83912,13 @@ See the [property@Gtk.Inscription:xalign] property. a `GtkInscription` + line="1068">a `GtkInscription` the new xalign value, between 0 and 1 + line="1069">the new xalign value, between 0 and 1 @@ -81942,10 +83927,9 @@ See the [property@Gtk.Inscription:xalign] property. c:identifier="gtk_inscription_set_yalign" glib:set-property="yalign" version="4.8"> - Sets the `yalign` of the inscription. + line="1117">Sets the `yalign` of the inscription. See the [property@Gtk.Inscription:yalign] property. @@ -81956,13 +83940,13 @@ See the [property@Gtk.Inscription:yalign] property. a `GtkInscription` + line="1119">a `GtkInscription` the new yalign value, between 0 and 1 + line="1120">the new yalign value, between 0 and 1 @@ -81973,13 +83957,9 @@ See the [property@Gtk.Inscription:yalign] property. transfer-ownership="none" setter="set_attributes" getter="get_attributes"> - - A list of style attributes to apply to the text of the inscription. + line="591">A list of style attributes to apply to the text of the inscription. transfer-ownership="none" setter="set_markup" default-value="NULL"> - Utility property that sets both the [property@Gtk.Inscription:text] and + line="603">Utility property that sets both the [property@Gtk.Inscription:text] and [property@Gtk.Inscription:attributes] properties, mainly intended for use in GtkBuilder ui files to ease translation support and bindings. @@ -82009,13 +83987,9 @@ attributes. The markup must be valid. If you cannot ensure that, consider using setter="set_min_chars" getter="get_min_chars" default-value="3"> - - The number of characters that should fit into the inscription at minimum. + line="621">The number of characters that should fit into the inscription at minimum. This influences the requested width, not the width actually given to the widget, which might turn out to be larger. @@ -82035,13 +84009,9 @@ and its width will be determined entirely by its surroundings. setter="set_min_lines" getter="get_min_lines" default-value="1"> - - The number of lines that should fit into the inscription at minimum. + line="644">The number of lines that should fit into the inscription at minimum. This influences the requested height, not the height actually given to the widget, which might turn out to be larger. @@ -82060,13 +84030,9 @@ and its height will be determined entirely by its surroundings. setter="set_nat_chars" getter="get_nat_chars" default-value="0"> - - The number of characters that should ideally fit into the inscription. + line="666">The number of characters that should ideally fit into the inscription. This influences the requested width, not the width actually given to the widget. The widget might turn out larger as well as smaller. @@ -82083,13 +84049,9 @@ be the case. setter="set_nat_lines" getter="get_nat_lines" default-value="0"> - - The number of lines that should ideally fit into the inscription. + line="686">The number of lines that should ideally fit into the inscription. This influences the requested height, not the height actually given to the widget. The widget might turn out larger as well as smaller. @@ -82106,13 +84068,9 @@ be the case. setter="set_text" getter="get_text" default-value="NULL"> - - The displayed text. + line="706">The displayed text. setter="set_text_overflow" getter="get_text_overflow" default-value="GTK_INSCRIPTION_OVERFLOW_CLIP"> - - The overflow method to use for the text. + line="718">The overflow method to use for the text. setter="set_wrap_mode" getter="get_wrap_mode" default-value="PANGO_WRAP_WORD_CHAR"> - - Controls how the line wrapping is done. + line="731">Controls how the line wrapping is done. Note that unlike `GtkLabel`, the default here is %PANGO_WRAP_WORD_CHAR. @@ -82156,13 +84106,9 @@ Note that unlike `GtkLabel`, the default here is %PANGO_WRAP_WORD_CHAR. setter="set_xalign" getter="get_xalign" default-value="0.000000"> - - The horizontal alignment of the text inside the allocated size. + line="746">The horizontal alignment of the text inside the allocated size. Compare this to [property@Gtk.Widget:halign], which determines how the inscription's size allocation is positioned in the available space. @@ -82175,13 +84121,9 @@ inscription's size allocation is positioned in the available space. setter="set_yalign" getter="get_yalign" default-value="0.500000"> - - The vertical alignment of the text inside the allocated size. + line="762">The vertical alignment of the text inside the allocated size. Compare this to [property@Gtk.Widget:valign], which determines how the inscription's size allocation is positioned in the available space. @@ -82248,7 +84190,7 @@ fit the available space. c:type="GtkJustification"> Used for justifying the text inside a [class@Label] widget. + line="273">Used for justifying the text inside a [class@Label] widget. glib:name="GTK_JUSTIFY_LEFT"> The text is placed at the left edge of the label. + line="275">The text is placed at the left edge of the label. glib:name="GTK_JUSTIFY_RIGHT"> The text is placed at the right edge of the label. + line="276">The text is placed at the right edge of the label. glib:name="GTK_JUSTIFY_CENTER"> The text is placed in the center of the label. + line="277">The text is placed in the center of the label. glib:name="GTK_JUSTIFY_FILL"> The text is placed is distributed across the label. + line="278">The text is placed is distributed across the label. glib:type-struct="KeyvalTriggerClass"> A `GtkShortcutTrigger` that triggers when a specific keyval and modifiers are pressed. + line="81">Triggers when a specific keyval and modifiers are pressed. - Gets the keyval that must be pressed to succeed @@ -82351,7 +84292,6 @@ triggering @self. - Gets the modifiers that must be present to succeed @@ -82378,8 +84318,6 @@ triggering @self. transfer-ownership="none" getter="get_keyval" default-value="0"> - The key value for the trigger. @@ -82390,9 +84328,7 @@ triggering @self. construct-only="1" transfer-ownership="none" getter="get_modifiers" - default-value="0"> - + default-value="GDK_NO_MODIFIER_MASK"> The key modifiers for the trigger. @@ -82619,14 +84555,50 @@ triggering @self. glib:get-type="gtk_label_get_type"> The `GtkLabel` widget displays a small amount of text. + line="66">Displays a small amount of text. -As the name implies, most labels are used to label another widget -such as a [class@Button]. +Most labels are used to label another widget (such as an [class@Entry]). -![An example GtkLabel](label.png) +<picture> + <source srcset="label-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkLabel" src="label.png"> +</picture> -# CSS nodes +## Shortcuts and Gestures + +`GtkLabel` supports the following keyboard shortcuts, when the cursor is +visible: + +- <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. +- <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> + selects all. +- <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or + <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all. + +Additionally, the following signals have default keybindings: + +- [signal@Gtk.Label::activate-current-link] +- [signal@Gtk.Label::copy-clipboard] +- [signal@Gtk.Label::move-cursor] + +## Actions + +`GtkLabel` defines a set of built-in actions: + +- `clipboard.copy` copies the text to the clipboard. +- `clipboard.cut` doesn't do anything, since text in labels can't be deleted. +- `clipboard.paste` doesn't do anything, since text in labels can't be + edited. +- `link.open` opens the link, when activated on a link inside the label. +- `link.copy` copies the link to the clipboard, when activated on a link + inside the label. +- `menu.popup` opens the context menu. +- `selection.delete` doesn't do anything, since text in labels can't be + deleted. +- `selection.select-all` selects all of the text, if the label allows + selection. + +## CSS nodes ``` label @@ -82647,7 +84619,7 @@ If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited. In this case, label node also gets a .link style class. -# GtkLabel as GtkBuildable +## GtkLabel as GtkBuildable The GtkLabel implementation of the GtkBuildable interface supports a custom `<attributes>` element, which supports any number of `<attribute>` @@ -82656,6 +84628,7 @@ elements. The `<attribute>` element has attributes named “name“, “va values for this label. An example of a UI definition fragment specifying Pango attributes: + ```xml <object class="GtkLabel"> <attributes> @@ -82671,11 +84644,11 @@ applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. -# Accessibility +## Accessibility -`GtkLabel` uses the %GTK_ACCESSIBLE_ROLE_LABEL role. +`GtkLabel` uses the [enum@Gtk.AccessibleRole.label] role. -# Mnemonics +## Mnemonics Labels may contain “mnemonics”. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a @@ -82716,11 +84689,10 @@ GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); ``` -# Markup (styled text) +## Markup (styled text) -To make it easy to format text in a label (changing colors, -fonts, etc.), label text can be provided in a simple -markup format: +To make it easy to format text in a label (changing colors, fonts, etc.), +label text can be provided in a simple markup format: Here’s how to create a label with a small font: ```c @@ -82731,7 +84703,7 @@ gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>" (See the Pango manual for complete documentation] of available tags, [func@Pango.parse_markup]) -The markup passed to [method@Gtk.Label.set_markup] must be valid; for example, +The markup passed to [method@Gtk.Label.set_markup] must be valid XML; for example, literal `<`, `>` and `&` characters must be escaped as `&lt;`, `&gt;`, and `&amp;`. If you pass text obtained from the user, file, or a network to [method@Gtk.Label.set_markup], you’ll want to escape it with @@ -82742,18 +84714,18 @@ on a label; [method@Gtk.Label.set_attributes] may be a simpler way to set attributes in some cases. Be careful though; [struct@Pango.AttrList] tends to cause internationalization problems, unless you’re applying attributes to the entire string (i.e. unless you set the range of each attribute -to [0, %G_MAXINT)). The reason is that specifying the start_index and -end_index for a [struct@Pango.Attribute] requires knowledge of the exact +to [0, `G_MAXINT`)). The reason is that specifying the `start_index` and +`end_index` for a [struct@Pango.Attribute] requires knowledge of the exact string being displayed, so translations will cause problems. -# Selectable labels +## Selectable labels Labels can be made selectable with [method@Gtk.Label.set_selectable]. -Selectable labels allow the user to copy the label contents to -the clipboard. Only labels that contain useful-to-copy information -— such as error messages — should be made selectable. +Selectable labels allow the user to copy the label contents to the +clipboard. Only labels that contain useful-to-copy information — such +as error messages — should be made selectable. -# Text layout +## Text layout A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. @@ -82776,16 +84748,16 @@ width-chars is used as the minimum width, if specified, and max-width-chars is used as the natural width. Even if max-width-chars specified, wrapping labels will be rewrapped to use all of the available width. -# Links +## Links GTK supports markup for clickable hyperlinks in addition to regular Pango -markup. The markup for links is borrowed from HTML, using the `<a>` with -“href“, “title“ and “class“ attributes. GTK renders links similar to the -way they appear in web browsers, with colored, underlined text. The “title“ -attribute is displayed as a tooltip on the link. The “class“ attribute is -used as style class on the CSS node for the link. +markup. The markup for links is borrowed from HTML, using the `<a>` tag +with “href“, “title“ and “class“ attributes. GTK renders links similar to +the way they appear in web browsers, with colored, underlined text. The +“title“ attribute is displayed as a tooltip on the link. The “class“ +attribute is used as style class on the CSS node for the link. -An example looks like this: +An example of inline links looks like this: ```c const char *text = @@ -82800,19 +84772,20 @@ It is possible to implement custom handling for links and their tooltips with the [signal@Gtk.Label::activate-link] signal and the [method@Gtk.Label.get_current_uri] function. + Creates a new label with the given text inside it. + line="2958">Creates a new label with the given text inside it. -You can pass %NULL to get an empty label widget. +You can pass `NULL` to get an empty label widget. the new `GtkLabel` + line="2966">the new label @@ -82822,7 +84795,7 @@ You can pass %NULL to get an empty label widget. allow-none="1"> The text of the label + line="2960">the text of the label @@ -82831,7 +84804,7 @@ You can pass %NULL to get an empty label widget. c:identifier="gtk_label_new_with_mnemonic"> Creates a new `GtkLabel`, containing the text in @str. + line="2981">Creates a new label with the given text inside it, and a mnemonic. If characters in @str are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use @@ -82841,7 +84814,7 @@ to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. If [method@Gtk.Label.set_mnemonic_widget] is not called, then the first -activatable ancestor of the `GtkLabel` will be chosen as the mnemonic +activatable ancestor of the label will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic. @@ -82849,7 +84822,7 @@ and be activated by the mnemonic. the new `GtkLabel` + line="3001">the new label @@ -82859,7 +84832,7 @@ and be activated by the mnemonic. allow-none="1"> The text of the label, with an underscore in front of the + line="2983">the text of the label, with an underscore in front of the mnemonic character @@ -82868,10 +84841,9 @@ and be activated by the mnemonic. - Gets the label's attribute list. + line="3408">Gets the label's attribute list. This is the [struct@Pango.AttrList] that was set on the label using [method@Gtk.Label.set_attributes], if any. This function does not @@ -82883,14 +84855,14 @@ attributes for the label, use the attribute list + line="3421">the attribute list a `GtkLabel` + line="3410">a label @@ -82898,7 +84870,7 @@ attributes for the label, use Returns the URI for the currently active link in the label. + line="5975">Returns the URI for the active link in the label. The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently @@ -82910,14 +84882,14 @@ handler or for use in a [signal@Gtk.Widget::query-tooltip] handler. the currently active URI + line="5988">the active URI a `GtkLabel` + line="5977">a label @@ -82925,24 +84897,23 @@ handler or for use in a [signal@Gtk.Widget::query-tooltip] handler. - Returns the ellipsizing position of the label. + line="4112">Returns the ellipsization mode of the label. See [method@Gtk.Label.set_ellipsize]. `PangoEllipsizeMode` + line="4120">the ellipsization mode a `GtkLabel` + line="4114">a label @@ -82950,24 +84921,23 @@ See [method@Gtk.Label.set_ellipsize]. - Gets the extra menu model of @label. + line="6184">Gets the extra menu model of the label. See [method@Gtk.Label.set_extra_menu]. the menu model + line="6192">the menu model a `GtkLabel` + line="6186">a label @@ -82975,24 +84945,23 @@ See [method@Gtk.Label.set_extra_menu]. - Returns the justification of the label. + line="4065">Returns the justification of the label. See [method@Gtk.Label.set_justify]. `GtkJustification` + line="4073">the justification value a `GtkLabel` + line="4067">a label @@ -83000,10 +84969,9 @@ See [method@Gtk.Label.set_justify]. - Fetches the text from a label. + line="3456">Fetches the text from a label. The returned text includes any embedded underlines indicating mnemonics and Pango markup. (See [method@Gtk.Label.get_text]). @@ -83011,15 +84979,14 @@ mnemonics and Pango markup. (See [method@Gtk.Label.get_text]). the text of the label widget. This string is - owned by the widget and must not be modified or freed. + line="3465">the text of the label widget a `GtkLabel` + line="3458">a label @@ -83027,7 +84994,7 @@ mnemonics and Pango markup. (See [method@Gtk.Label.get_text]). Gets the `PangoLayout` used to display the label. + line="5416">Gets the Pango layout used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with [method@Gtk.Label.get_layout_offsets]. @@ -83038,14 +85005,14 @@ at any time, so it should be considered read-only. the [class@Pango.Layout] for this label + line="5428">the [class@Pango.Layout] for this label a `GtkLabel` + line="5418">a label @@ -83054,12 +85021,12 @@ at any time, so it should be considered read-only. c:identifier="gtk_label_get_layout_offsets"> Obtains the coordinates where the label will draw its `PangoLayout`. + line="5440">Obtains the coordinates where the label will draw its Pango layout. The coordinates are useful to convert mouse events into coordinates inside the [class@Pango.Layout], e.g. to take some action if some part of the label is clicked. Remember when using the [class@Pango.Layout] -functions you need to convert to and from pixels using PANGO_PIXELS() +functions you need to convert to and from pixels using `PANGO_PIXELS()` or [const@Pango.SCALE]. @@ -83069,7 +85036,7 @@ or [const@Pango.SCALE]. a `GtkLabel` + line="5442">a label allow-none="1"> location to store X offset of layout + line="5443">location to store X offset of layout allow-none="1"> location to store Y offset of layout + line="5444">location to store Y offset of layout @@ -83099,10 +85066,9 @@ or [const@Pango.SCALE]. - Gets the number of lines to which an ellipsized, wrapping + line="6057">Gets the number of lines to which an ellipsized, wrapping label should be limited. See [method@Gtk.Label.set_lines]. @@ -83110,14 +85076,14 @@ See [method@Gtk.Label.set_lines]. The number of lines + line="6066">the number of lines a `GtkLabel` + line="6059">a label @@ -83125,24 +85091,23 @@ See [method@Gtk.Label.set_lines]. - Retrieves the desired maximum width of @label, in characters. + line="4191">Retrieves the maximum width of the label in characters. See [method@Gtk.Label.set_width_chars]. the maximum width of the label in characters. + line="4199">the maximum width of the label, in characters a `GtkLabel` + line="4193">a label @@ -83150,10 +85115,9 @@ See [method@Gtk.Label.set_width_chars]. - Return the mnemonic accelerator. + line="3198">Return the mnemonic accelerator. If the label has been set so that it has a mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no @@ -83162,14 +85126,14 @@ mnemonic set up it returns `GDK_KEY_VoidSymbol`. GDK keyval usable for accelerators, or `GDK_KEY_VoidSymbol` + line="3208">GDK keyval usable for accelerators, or `GDK_KEY_VoidSymbol` a `GtkLabel` + line="3200">a label @@ -83177,26 +85141,24 @@ mnemonic set up it returns `GDK_KEY_VoidSymbol`. - Retrieves the target of the mnemonic (keyboard shortcut) of this -label. + line="3179">Retrieves the mnemonic target of this label. See [method@Gtk.Label.set_mnemonic_widget]. the target of the label’s mnemonic, - or %NULL if none has been set and the default algorithm will be used. + line="3187">the target of the label’s mnemonic, + or `NULL` if none has been set and the default algorithm will be used. a `GtkLabel` + line="3181">a label @@ -83205,25 +85167,23 @@ See [method@Gtk.Label.set_mnemonic_widget]. c:identifier="gtk_label_get_natural_wrap_mode" glib:get-property="natural-wrap-mode" version="4.6"> - Returns line wrap mode used by the label. + line="4338">Returns natural line wrap mode used by the label. See [method@Gtk.Label.set_natural_wrap_mode]. the natural line wrap mode + line="4346">the natural line wrap mode a `GtkLabel` + line="4340">a label @@ -83231,22 +85191,21 @@ See [method@Gtk.Label.set_natural_wrap_mode]. - Returns whether the label is selectable. + line="5179">Returns whether the label is selectable. %TRUE if the user can copy text from the label + line="5185">true if the user can copy text from the label a `GtkLabel` + line="5181">a label @@ -83255,19 +85214,21 @@ See [method@Gtk.Label.set_natural_wrap_mode]. c:identifier="gtk_label_get_selection_bounds"> Gets the selected range of characters in the label. + line="5347">Gets the selected range of characters in the label. + +The returned @start and @end positions are in characters. %TRUE if selection is non-empty + line="5357">true if selection is non-empty a `GtkLabel` + line="5349">a label allow-none="1"> return location for start of selection, as a character offset + line="5350">return location for start of selection allow-none="1"> return location for end of selection, as a character offset + line="5351">return location for end of selection @@ -83297,23 +85258,21 @@ See [method@Gtk.Label.set_natural_wrap_mode]. - Returns whether the label is in single line mode. + line="5577">Returns whether the label is in single line mode. %TRUE when the label is in single line mode. + line="5583">true if the label is in single line mode a `GtkLabel` + line="5579">a label @@ -83322,27 +85281,24 @@ See [method@Gtk.Label.set_natural_wrap_mode]. c:identifier="gtk_label_get_tabs" glib:get-property="tabs" version="4.8"> - Gets the tabs for @self. + line="6229">Gets the tab stops for the label. -The returned array will be %NULL if “standard” (8-space) tabs are used. -Free the return value with [method@Pango.TabArray.free]. +The returned array will be `NULL` if “standard” (8-space) tabs are used. copy of default tab array, - or %NULL if standard tabs are used; must be freed with - [method@Pango.TabArray.free]. + line="6237">copy of default tab array, + or `NULL` if standard tabs are used a `GtkLabel` + line="6231">a label @@ -83350,7 +85306,7 @@ Free the return value with [method@Pango.TabArray.free]. Fetches the text from a label. + line="4011">Gets the text of the label. The returned text is as it appears on screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See @@ -83359,15 +85315,14 @@ any embedded underlines indicating mnemonics or Pango markup. (See the text in the label widget. This is the internal - string used by the label, and must not be modified. + line="4021">the text in the label widget a `GtkLabel` + line="4013">a label @@ -83375,24 +85330,23 @@ any embedded underlines indicating mnemonics or Pango markup. (See - Returns whether the label’s text is interpreted as Pango markup. + line="5494">Returns whether the label’s text is interpreted as Pango markup. See [method@Gtk.Label.set_use_markup]. %TRUE if the label’s text will be parsed for markup. + line="5502">true if the label’s text will be parsed for markup a `GtkLabel` + line="5496">a label @@ -83400,25 +85354,23 @@ See [method@Gtk.Label.set_use_markup]. - Returns whether an embedded underlines in the label indicate mnemonics. + line="5533">Returns whether underlines in the label indicate mnemonics. See [method@Gtk.Label.set_use_underline]. %TRUE whether an embedded underline in the label indicates - the mnemonic accelerator keys. + line="5541">true if underlines in the label indicate mnemonics a `GtkLabel` + line="5535">a label @@ -83426,24 +85378,23 @@ See [method@Gtk.Label.set_use_underline]. - Retrieves the desired width of @label, in characters. + line="4151">Retrieves the desired width of the label in characters. See [method@Gtk.Label.set_width_chars]. the width of the label in characters. + line="4159">the desired width of the label, in characters a `GtkLabel` + line="4153">a label @@ -83451,24 +85402,23 @@ See [method@Gtk.Label.set_width_chars]. - Returns whether lines in the label are automatically wrapped. + line="4244">Returns whether lines in the label are automatically wrapped. See [method@Gtk.Label.set_wrap]. %TRUE if the lines of the label are automatically wrapped. + line="4252">true if the lines of the label are automatically wrapped a `GtkLabel` + line="4246">a label @@ -83476,24 +85426,23 @@ See [method@Gtk.Label.set_wrap]. - Returns line wrap mode used by the label. + line="4293">Returns line wrap mode used by the label. See [method@Gtk.Label.set_wrap_mode]. the line wrap mode + line="4301">the line wrap mode a `GtkLabel` + line="4295">a label @@ -83501,24 +85450,23 @@ See [method@Gtk.Label.set_wrap_mode]. - Gets the `xalign` of the label. + line="6102">Gets the `xalign` of the label. See the [property@Gtk.Label:xalign] property. the xalign property + line="6110">the xalign value a `GtkLabel` + line="6104">a label @@ -83526,24 +85474,23 @@ See the [property@Gtk.Label:xalign] property. - Gets the `yalign` of the label. + line="6146">Gets the `yalign` of the label. See the [property@Gtk.Label:yalign] property. the yalign property + line="6154">the yalign value a `GtkLabel` + line="6148">a label @@ -83551,7 +85498,7 @@ See the [property@Gtk.Label:yalign] property. Selects a range of characters in the label, if the label is selectable. + line="5314">Selects a range of characters in the label, if the label is selectable. See [method@Gtk.Label.set_selectable]. If the label is not selectable, this function has no effect. If @start_offset or @@ -83564,19 +85511,19 @@ this function has no effect. If @start_offset or a `GtkLabel` + line="5316">a label start offset (in characters not bytes) + line="5317">start offset, in characters end offset (in characters not bytes) + line="5318">end offset, in characters @@ -83584,17 +85531,18 @@ this function has no effect. If @start_offset or - Apply attributes to the label text. + line="3370">Apply attributes to the label text. The attributes set with this function will be applied and merged with any other attributes previously effected by way of the [property@Gtk.Label:use-underline] or [property@Gtk.Label:use-markup] -properties. While it is not recommended to mix markup strings with -manually set attributes, if you must; know that the attributes will -be applied to the label after the markup string is parsed. +properties + +While it is not recommended to mix markup strings with manually set +attributes, if you must; know that the attributes will be applied +to the label after the markup string is parsed. @@ -83603,7 +85551,7 @@ be applied to the label after the markup string is parsed. a `GtkLabel` + line="3372">a label allow-none="1"> a [struct@Pango.AttrList] + line="3373">a list of style attributes @@ -83620,13 +85568,12 @@ be applied to the label after the markup string is parsed. - Sets the mode used to ellipsize the text. + line="4083">Sets the mode used to ellipsize the text. -The text will be ellipsized if there is not enough space -to render the entire string. +The text will be ellipsized if there is not +enough space to render the entire string. @@ -83635,13 +85582,13 @@ to render the entire string. a `GtkLabel` + line="4085">a label a `PangoEllipsizeMode` + line="4086">the ellipsization mode @@ -83649,11 +85596,9 @@ to render the entire string. - Sets a menu model to add when constructing -the context menu for @label. + line="6164">Sets a menu model to add to the context menu of the label. @@ -83662,7 +85607,7 @@ the context menu for @label. a `GtkLabel` + line="6166">a label allow-none="1"> a `GMenuModel` + line="6167">a menu model @@ -83679,17 +85624,17 @@ the context menu for @label. - Sets the alignment of the lines in the text of the label relative to -each other. - -%GTK_JUSTIFY_LEFT is the default value when the widget is first created -with [ctor@Gtk.Label.new]. If you instead want to set the alignment of -the label as a whole, use [method@Gtk.Widget.set_halign] instead. -[method@Gtk.Label.set_justify] has no effect on labels containing -only a single line. + line="4031">Sets the alignment of lines in the label relative to each other. + +This function has no effect on labels containing only a single line. + +[enum@Gtk.Justification.left] is the default value when the widget +is first created with [ctor@Gtk.Label.new]. + +If you instead want to set the alignment of the label as a whole, +use [method@Gtk.Widget.set_halign] instead. @@ -83698,13 +85643,13 @@ only a single line. a `GtkLabel` + line="4033">a label a `GtkJustification` + line="4034">the new justification @@ -83712,10 +85657,9 @@ only a single line. - Sets the text of the label. + line="3431">Sets the text of the label. The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the [property@Gtk.Label:use-underline] @@ -83728,13 +85672,13 @@ and [property@Gtk.Label:use-markup] properties. a `GtkLabel` + line="3433">a label the new text to set for the label + line="3434">the new text to set for the label @@ -83742,10 +85686,9 @@ and [property@Gtk.Label:use-markup] properties. - Sets the number of lines to which an ellipsized, wrapping label + line="6031">Sets the number of lines to which an ellipsized, wrapping label should be limited. This has no effect if the label is not wrapping or ellipsized. @@ -83758,13 +85701,13 @@ Set this to -1 if you don’t want to limit the number of lines. a `GtkLabel` + line="6033">a label the desired number of lines, or -1 + line="6034">the desired number of lines, or -1 @@ -83772,13 +85715,13 @@ Set this to -1 if you don’t want to limit the number of lines. Sets the labels text and attributes from markup. + line="3927">Sets the labels text and attributes from markup. The string must be marked up with Pango markup (see [func@Pango.parse_markup]). -If the @str is external data, you may need to escape it -with g_markup_escape_text() or g_markup_printf_escaped(): +If @str is external data, you may need to escape it +with [func@GLib.markup_escape_text] or [func@GLib.markup_printf_escaped]: ```c GtkWidget *self = gtk_label_new (NULL); @@ -83791,14 +85734,10 @@ gtk_label_set_markup (GTK_LABEL (self), markup); g_free (markup); ``` -This function will set the [property@Gtk.Label:use-markup] property -to %TRUE as a side effect. - -If you set the label contents using the [property@Gtk.Label:label] -property you should also ensure that you set the -[property@Gtk.Label:use-markup] property accordingly. +This function sets the [property@Gtk.Label:use-markup] property +to true. -See also: [method@Gtk.Label.set_text] +Also see [method@Gtk.Label.set_text]. @@ -83807,13 +85746,13 @@ See also: [method@Gtk.Label.set_text] a `GtkLabel` + line="3929">a label a markup string + line="3930">the markup string @@ -83822,7 +85761,7 @@ See also: [method@Gtk.Label.set_text] c:identifier="gtk_label_set_markup_with_mnemonic"> Sets the labels text, attributes and mnemonic from markup. + line="3976">Sets the labels text, attributes and mnemonic from markup. Parses @str which is marked up with Pango markup (see [func@Pango.parse_markup]), setting the label’s text and attribute list based on the parse results. @@ -83839,13 +85778,13 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a `GtkLabel` + line="3978">a label a markup string + line="3979">the markup string @@ -83853,10 +85792,9 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. - Sets the desired maximum width in characters of @label to @n_chars. + line="4169">Sets the maximum width of the label in characters. @@ -83865,13 +85803,13 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a `GtkLabel` + line="4171">a label the new desired maximum width, in characters. + line="4172">the new maximum width, in characters. @@ -83879,26 +85817,25 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. - Associate the label with its mnemonic target. + line="3127">Associate the label with its mnemonic target. If the label has been set so that it has a mnemonic key (using i.e. [method@Gtk.Label.set_markup_with_mnemonic], [method@Gtk.Label.set_text_with_mnemonic], [ctor@Gtk.Label.new_with_mnemonic] -or the [property@Gtk.Label:use_underline] property) the label can be -associated with a widget that is the target of the mnemonic. When the -label is inside a widget (like a [class@Gtk.Button] or a -[class@Gtk.Notebook] tab) it is automatically associated with the correct -widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] next to -the label) you need to set it explicitly using this function. +or the [property@Gtk.Label:use_underline] property) the label can +be associated with a widget that is the target of the mnemonic. +When the label is inside a widget (like a [class@Gtk.Button] or a +[class@Gtk.Notebook] tab) it is automatically associated with the +correct widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] +next to the label) you need to set it explicitly using this function. The target widget will be accelerated by emitting the -[signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler for -this signal will activate the widget if there are no mnemonic collisions -and toggle focus between the colliding widgets otherwise. +[signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler +for this signal will activate the widget if there are no mnemonic +collisions and toggle focus between the colliding widgets otherwise. @@ -83907,7 +85844,7 @@ and toggle focus between the colliding widgets otherwise. a `GtkLabel` + line="3129">a label allow-none="1"> the target `GtkWidget`, or %NULL to unset + line="3130">the target widget @@ -83925,11 +85862,9 @@ and toggle focus between the colliding widgets otherwise. c:identifier="gtk_label_set_natural_wrap_mode" glib:set-property="natural-wrap-mode" version="4.6"> - Select the line wrapping for the natural size request. + line="4311">Selects the line wrapping for the natural size request. This only affects the natural size requested, for the actual wrapping used, see the [property@Gtk.Label:wrap-mode] property. @@ -83941,13 +85876,13 @@ see the [property@Gtk.Label:wrap-mode] property. a `GtkLabel` + line="4313">a label the line wrapping mode + line="4314">the line wrapping mode @@ -83955,10 +85890,9 @@ see the [property@Gtk.Label:wrap-mode] property. - Makes text in the label selectable. + line="5125">Makes text in the label selectable. Selectable labels allow the user to select text from the label, for copy-and-paste. @@ -83970,13 +85904,13 @@ for copy-and-paste. a `GtkLabel` + line="5127">a label %TRUE to allow selecting text in the label + line="5128">true to allow selecting text in the label @@ -83984,11 +85918,9 @@ for copy-and-paste. - Sets whether the label is in single line mode. + line="5551">Sets whether the label is in single line mode. @@ -83997,13 +85929,13 @@ for copy-and-paste. a `GtkLabel` + line="5553">a label %TRUE if the label should be in single line mode + line="5554">true to enable single line mode @@ -84012,10 +85944,9 @@ for copy-and-paste. c:identifier="gtk_label_set_tabs" glib:set-property="tabs" version="4.8"> - Sets the default tab stops for paragraphs in @self. + line="6202">Sets tab stops for the label. @@ -84024,7 +85955,7 @@ for copy-and-paste. a `GtkLabel` + line="6204">a label allow-none="1"> tabs as a `PangoTabArray` + line="6205">tab stops @@ -84041,18 +85972,14 @@ for copy-and-paste. Sets the text within the `GtkLabel` widget. + line="3336">Sets the text for the label. -It overwrites any text that was there before. +It overwrites any text that was there before and clears any +previously set mnemonic accelerators, and sets the +[property@Gtk.Label:use-underline] and +[property@Gtk.Label:use-markup] properties to false. -This function will clear any previously set mnemonic accelerators, -and set the [property@Gtk.Label:use-underline] property to %FALSE as -a side effect. - -This function will set the [property@Gtk.Label:use-markup] property -to %FALSE as a side effect. - -See also: [method@Gtk.Label.set_markup] +Also see [method@Gtk.Label.set_markup]. @@ -84061,13 +85988,13 @@ See also: [method@Gtk.Label.set_markup] a `GtkLabel` + line="3338">a label The text you want to set + line="3339">the text to show in @self @@ -84076,7 +86003,7 @@ See also: [method@Gtk.Label.set_markup] c:identifier="gtk_label_set_text_with_mnemonic"> Sets the label’s text from the string @str. + line="4410">Sets the text for the label, with mnemonics. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. @@ -84090,13 +86017,13 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a `GtkLabel` + line="4412">a label a string + line="4413">the text @@ -84104,10 +86031,9 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. - Sets whether the text of the label contains markup. + line="5471">Sets whether the text of the label contains markup. See [method@Gtk.Label.set_markup]. @@ -84118,13 +86044,13 @@ See [method@Gtk.Label.set_markup]. a `GtkLabel` + line="5473">a label %TRUE if the label’s text should be parsed for markup. + line="5474">true if the label’s text should be parsed for markup. @@ -84132,10 +86058,9 @@ See [method@Gtk.Label.set_markup]. - Sets whether underlines in the text indicate mnemonics. + line="5512">Sets whether underlines in the text indicate mnemonics. @@ -84144,13 +86069,13 @@ See [method@Gtk.Label.set_markup]. a `GtkLabel` + line="5514">a label %TRUE if underlines in the text indicate mnemonics + line="5515">true if underlines in the text indicate mnemonics @@ -84158,10 +86083,9 @@ See [method@Gtk.Label.set_markup]. - Sets the desired width in characters of @label to @n_chars. + line="4130">Sets the desired width in characters of the label. @@ -84170,13 +86094,13 @@ See [method@Gtk.Label.set_markup]. a `GtkLabel` + line="4132">a label the new desired width, in characters. + line="4133">the new desired width, in characters. @@ -84184,20 +86108,19 @@ See [method@Gtk.Label.set_markup]. - Toggles line wrapping within the `GtkLabel` widget. + line="4209">Toggles line wrapping within the label. -%TRUE makes it break lines if text exceeds the widget’s size. -%FALSE lets the text get cut off by the edge of the widget if +True makes it break lines if text exceeds the widget’s size. +false lets the text get cut off by the edge of the widget if it exceeds the widget size. -Note that setting line wrapping to %TRUE does not make the label -wrap at its parent container’s width, because GTK widgets -conceptually can’t make their requisition depend on the parent -container’s size. For a label that wraps at a specific position, -set the label’s width using [method@Gtk.Widget.set_size_request]. +Note that setting line wrapping to true does not make the label +wrap at its parent widget’s width, because GTK widgets conceptually +can’t make their requisition depend on the parent widget’s size. +For a label that wraps at a specific position, set the label’s width +using [method@Gtk.Widget.set_size_request]. @@ -84206,13 +86129,13 @@ set the label’s width using [method@Gtk.Widget.set_size_request]. a `GtkLabel` + line="4211">a label the setting + line="4212">whether to wrap lines @@ -84220,17 +86143,18 @@ set the label’s width using [method@Gtk.Widget.set_size_request]. - Controls how line wrapping is done. + line="4262">Controls how line wrapping is done. This only affects the label if line wrapping is on. (See -[method@Gtk.Label.set_wrap]) The default is %PANGO_WRAP_WORD -which means wrap on word boundaries. +[method@Gtk.Label.set_wrap]) -For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] -property. +The default is [enum@Pango.WrapMode.word], which means +wrap on word boundaries. + +For sizing behavior, also consider the +[property@Gtk.Label:natural-wrap-mode] property. @@ -84239,13 +86163,13 @@ property. a `GtkLabel` + line="4264">a label the line wrapping mode + line="4265">the line wrapping mode @@ -84253,10 +86177,9 @@ property. - Sets the `xalign` of the label. + line="6076">Sets the `xalign` of the label. See the [property@Gtk.Label:xalign] property. @@ -84267,13 +86190,13 @@ See the [property@Gtk.Label:xalign] property. a `GtkLabel` + line="6078">a label the new xalign value, between 0 and 1 + line="6079">the new xalign value, between 0 and 1 @@ -84281,10 +86204,9 @@ See the [property@Gtk.Label:xalign] property. - Sets the `yalign` of the label. + line="6120">Sets the `yalign` of the label. See the [property@Gtk.Label:yalign] property. @@ -84295,13 +86217,13 @@ See the [property@Gtk.Label:yalign] property. a `GtkLabel` + line="6122">a label the new yalign value, between 0 and 1 + line="6123">the new yalign value, between 0 and 1 @@ -84311,13 +86233,9 @@ See the [property@Gtk.Label:yalign] property. transfer-ownership="none" setter="set_attributes" getter="get_attributes"> - - A list of style attributes to apply to the text of the label. + line="2452">A list of style attributes to apply to the text of the label. setter="set_ellipsize" getter="get_ellipsize" default-value="PANGO_ELLIPSIZE_NONE"> - - The preferred place to ellipsize the string, if the label does + line="2605">The preferred place to ellipsize the string, if the label does not have enough room to display the entire string. Note that setting this property to a value other than -%PANGO_ELLIPSIZE_NONE has the side-effect that the label requests +[enum.Pango.EllipsizeMode.none] has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels do not work well in notebook tabs, unless -the [property@Gtk.NotebookPage:tab-expand] child property is set to %TRUE. +the [property@Gtk.NotebookPage:tab-expand] child property is set to true. + Other ways to set a label's width are [method@Gtk.Widget.set_size_request] and [method@Gtk.Label.set_width_chars]. @@ -84349,13 +86264,9 @@ and [method@Gtk.Label.set_width_chars]. transfer-ownership="none" setter="set_extra_menu" getter="get_extra_menu"> - - A menu model whose contents will be appended to the context menu. + line="2691">A menu model whose contents will be appended to the context menu. setter="set_justify" getter="get_justify" default-value="GTK_JUSTIFY_LEFT"> - - The alignment of the lines in the text of the label, relative to each other. + line="2485">The alignment of the lines in the text of the label, relative to each other. This does *not* affect the alignment of the label within its allocation. See [property@Gtk.Label:xalign] for that. @@ -84379,21 +86288,19 @@ See [property@Gtk.Label:xalign] for that. transfer-ownership="none" setter="set_label" getter="get_label"> - - The contents of the label. + line="2431">The contents of the label. If the string contains Pango markup (see [func@Pango.parse_markup]), you will have to set the [property@Gtk.Label:use-markup] property to -%TRUE in order for the label to display the markup attributes. See also +true in order for the label to display the markup attributes. See also [method@Gtk.Label.set_markup] for a convenience function that sets both this property and the [property@Gtk.Label:use-markup] property at the same time. If the string contains underlines acting as mnemonics, you will have to -set the [property@Gtk.Label:use-underline] property to %TRUE in order +set the [property@Gtk.Label:use-underline] property to true in order for the label to display them. @@ -84403,14 +86310,13 @@ for the label to display them. setter="set_lines" getter="get_lines" default-value="-1"> - - The number of lines to which an ellipsized, wrapping label + line="2675">The number of lines to which an ellipsized, wrapping label should be limited. This property has no effect if the label is not wrapping or ellipsized. + Set this property to -1 if you don't want to limit the number of lines. @@ -84420,18 +86326,14 @@ Set this property to -1 if you don't want to limit the number of lines. setter="set_max_width_chars" getter="get_max_width_chars" default-value="-1"> - - The desired maximum width of the label, in characters. + line="2658">The desired maximum width of the label, in characters. If this property is set to -1, the width will be calculated automatically. -See the section on [text layout](class.Label.html#text-layout) for details of how -[property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] +See the section on [text layout](class.Label.html#text-layout) for details +of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. @@ -84439,11 +86341,9 @@ determine the width of ellipsized and wrapped labels. transfer-ownership="none" getter="get_mnemonic_keyval" default-value="16777215"> - The mnemonic accelerator key for the label. + line="2584">The mnemonic accelerator key for the label. transfer-ownership="none" setter="set_mnemonic_widget" getter="get_mnemonic_widget"> - - The widget to be activated when the labels mnemonic key is pressed. + line="2595">The widget to be activated when the labels mnemonic key is pressed. setter="set_natural_wrap_mode" getter="get_natural_wrap_mode" default-value="GTK_NATURAL_WRAP_INHERIT"> - - Select the line wrapping for the natural size request. + line="2555">Select the line wrapping for the natural size request. -This only affects the natural size requested. For the actual wrapping used, -see the [property@Gtk.Label:wrap-mode] property. +This only affects the natural size requested. For the actual wrapping +used, see the [property@Gtk.Label:wrap-mode] property. -The default is %GTK_NATURAL_WRAP_INHERIT, which inherits the behavior of the -[property@Gtk.Label:wrap-mode] property. +The default is [enum@Gtk.NaturalWrapMode.inherit], which inherits +the behavior of the [property@Gtk.Label:wrap-mode] property. - - Whether the label text can be selected with the mouse. + line="2574">Whether the label text can be selected with the mouse. - - Whether the label is in single line mode. + line="2643">Whether the label is in single line mode. In single line mode, the height of the label does not depend on the actual text, it is always set to ascent + descent of the font. This @@ -84523,11 +86407,9 @@ of text changes would be distracting, e.g. in a statusbar. transfer-ownership="none" setter="set_tabs" getter="get_tabs"> - - Custom tabs for this label. + line="2701">Custom tabs for this label. setter="set_use_markup" getter="get_use_markup" default-value="FALSE"> - - %TRUE if the text of the label includes Pango markup. + line="2462">True if the text of the label includes Pango markup. See [func@Pango.parse_markup]. @@ -84553,13 +86431,9 @@ See [func@Pango.parse_markup]. setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - %TRUE if the text of the label indicates a mnemonic with an _ + line="2474">True if the text of the label indicates a mnemonic with an `_` before the mnemonic character. @@ -84569,18 +86443,14 @@ before the mnemonic character. setter="set_width_chars" getter="get_width_chars" default-value="-1"> - - The desired width of the label, in characters. + line="2626">The desired width of the label, in characters. If this property is set to -1, the width will be calculated automatically. -See the section on [text layout](class.Label.html#text-layout) for details of how -[property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] +See the section on [text layout](class.Label.html#text-layout) for details +of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. @@ -84590,11 +86460,9 @@ determine the width of ellipsized and wrapped labels. setter="set_wrap" getter="get_wrap" default-value="FALSE"> - - %TRUE if the label text will wrap if it gets too wide. + line="2527">True if the label text will wrap if it gets too wide. setter="set_wrap_mode" getter="get_wrap_mode" default-value="PANGO_WRAP_WORD"> - - Controls how the line wrapping is done. + line="2537">Controls how the line wrapping is done. This only affects the formatting if line wrapping is on (see the -[property@Gtk.Label:wrap] property). The default is %PANGO_WRAP_WORD, +[property@Gtk.Label:wrap] property). The default is [enum@Pango.WrapMode.word], which means wrap on word boundaries. For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] @@ -84625,11 +86489,9 @@ property. setter="set_xalign" getter="get_xalign" default-value="0.500000"> - - The horizontal alignment of the label text inside its size allocation. + line="2499">The horizontal alignment of the label text inside its size allocation. Compare this to [property@Gtk.Widget:halign], which determines how the labels size allocation is positioned in the space available for the label. @@ -84641,11 +86503,9 @@ labels size allocation is positioned in the space available for the label. setter="set_yalign" getter="get_yalign" default-value="0.500000"> - - The vertical alignment of the label text inside its size allocation. + line="2513">The vertical alignment of the label text inside its size allocation. Compare this to [property@Gtk.Widget:valign], which determines how the labels size allocation is positioned in the space available for the label. @@ -84654,9 +86514,9 @@ labels size allocation is positioned in the space available for the label. Gets emitted when the user activates a link in the label. + line="2385">Gets emitted when the user activates a link in the label. -The ::activate-current-link is a [keybinding signal](class.SignalAction.html). +The `::activate-current-link` is a [keybinding signal](class.SignalAction.html). Applications may also emit the signal with g_signal_emit_by_name() if they need to control activation of URIs programmatically. @@ -84669,21 +86529,21 @@ The default bindings for this signal are all forms of the <kbd>Enter</k Gets emitted to activate a URI. + line="2407">Gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. %TRUE if the link has been activated + line="2417">true if the link has been activated the URI that is activated + line="2410">the URI that is activated @@ -84691,9 +86551,9 @@ which is to call [method@Gtk.FileLauncher.launch]. Gets emitted to copy the selection to the clipboard. + line="2366">Gets emitted to copy the selection to the clipboard. -The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html). +The `::copy-clipboard` signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c</kbd>. @@ -84703,19 +86563,19 @@ The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c& Gets emitted when the user initiates a cursor movement. + line="2324">Gets emitted when the user initiates a cursor movement. -The ::move-cursor signal is a [keybinding signal](class.SignalAction.html). +The `::move-cursor` signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with -g_signal_emit_by_name() if they need to control the cursor -programmatically. +[func@GObject.signal_emit_by_name] if they need to control +the cursor programmatically. -The default bindings for this signal come in two variants, -the variant with the Shift modifier extends the selection, -the variant without the Shift modifier does not. +The default bindings for this signal come in two variants, the +variant with the <kbd>Shift</kbd> modifier extends the selection, +the variant without the <kbd>Shift</kbd> modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> @@ -84729,19 +86589,19 @@ There are too many key combinations to list them all here. the granularity of the move, as a `GtkMovementStep` + line="2327">the granularity of the move, as a `GtkMovementStep` the number of @step units to move + line="2328">the number of @step units to move %TRUE if the move should extend the selection + line="2329">true if the move should extend the selection @@ -84757,8 +86617,7 @@ There are too many key combinations to list them all here. glib:type-struct="LayoutChildClass"> `GtkLayoutChild` is the base class for objects that are meant to hold -layout properties. + line="8">The base class for objects that are meant to hold layout properties. If a `GtkLayoutManager` has per-child properties, like their packing type, or the horizontal and vertical span, or the icon name, then the layout @@ -84770,22 +86629,21 @@ of a layout. - Retrieves the `GtkWidget` associated to the given @layout_child. + line="168">Retrieves the `GtkWidget` associated to the given @layout_child. a `GtkWidget` + line="174">a `GtkWidget` a `GtkLayoutChild` + line="170">a `GtkLayoutChild` @@ -84793,23 +86651,22 @@ of a layout. - Retrieves the `GtkLayoutManager` instance that created the + line="149">Retrieves the `GtkLayoutManager` instance that created the given @layout_child. a `GtkLayoutManager` + line="156">a `GtkLayoutManager` a `GtkLayoutChild` + line="151">a `GtkLayoutChild` @@ -84819,11 +86676,9 @@ given @layout_child. construct-only="1" transfer-ownership="none" getter="get_child_widget"> - The widget that is associated to the `GtkLayoutChild` instance. + line="130">The widget that is associated to the `GtkLayoutChild` instance. construct-only="1" transfer-ownership="none" getter="get_layout_manager"> - The layout manager that created the `GtkLayoutChild` instance. + line="119">The layout manager that created the `GtkLayoutChild` instance. @@ -84860,8 +86713,7 @@ given @layout_child. glib:type-struct="LayoutManagerClass"> Layout managers are delegate classes that handle the preferred size -and the allocation of a widget. + line="20">Handles the preferred size and allocation for children of a widget. You typically subclass `GtkLayoutManager` if you want to implement a layout policy for the children of a widget, or if you want to determine @@ -84912,7 +86764,7 @@ updated, in order to queue a new size measuring and allocation. Assigns the given @width, @height, and @baseline to + line="384">Assigns the given @width, @height, and @baseline to a @widget, and computes the position and sizes of the children of the @widget using the layout management policy of @manager. @@ -84923,31 +86775,31 @@ the @widget using the layout management policy of @manager. a `GtkLayoutManager` + line="386">a `GtkLayoutManager` the `GtkWidget` using @manager + line="387">the `GtkWidget` using @manager the new width of the @widget + line="388">the new width of the @widget the new height of the @widget + line="389">the new height of the @widget the baseline position of the @widget, or -1 + line="390">the baseline position of the @widget, or -1 @@ -84985,6 +86837,11 @@ the @widget using the layout management policy of @manager. + a virtual function, used to return the preferred + request mode for the layout manager; for instance, "width for height" + or "height for width"; see `GtkSizeRequestMode` @@ -85001,7 +86858,7 @@ the @widget using the layout management policy of @manager. Measures the size of the @widget using @manager, for the + line="297">Measures the size of the @widget using @manager, for the given @orientation and size. See the [class@Gtk.Widget] documentation on layout management for @@ -85014,25 +86871,25 @@ more details. a `GtkLayoutManager` + line="299">a `GtkLayoutManager` the `GtkWidget` using @manager + line="300">the `GtkWidget` using @manager the orientation to measure + line="301">the orientation to measure Size for the opposite of @orientation; for instance, if + line="302">Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the @@ -85048,7 +86905,7 @@ more details. allow-none="1"> the minimum size for the given size and + line="308">the minimum size for the given size and orientation @@ -85060,7 +86917,7 @@ more details. allow-none="1"> the natural, or preferred size for the + line="310">the natural, or preferred size for the given size and orientation @@ -85072,7 +86929,7 @@ more details. allow-none="1"> the baseline position for the + line="312">the baseline position for the minimum size @@ -85084,13 +86941,17 @@ more details. allow-none="1"> the baseline position for the + line="314">the baseline position for the natural size + a virtual function, called when the widget using the layout + manager is attached to a `GtkRoot` @@ -85102,6 +86963,10 @@ more details. + a virtual function, called when the widget using the layout + manager is detached from a `GtkRoot` @@ -85115,7 +86980,7 @@ more details. Assigns the given @width, @height, and @baseline to + line="384">Assigns the given @width, @height, and @baseline to a @widget, and computes the position and sizes of the children of the @widget using the layout management policy of @manager. @@ -85126,31 +86991,31 @@ the @widget using the layout management policy of @manager. a `GtkLayoutManager` + line="386">a `GtkLayoutManager` the `GtkWidget` using @manager + line="387">the `GtkWidget` using @manager the new width of the @widget + line="388">the new width of the @widget the new height of the @widget + line="389">the new height of the @widget the baseline position of the @widget, or -1 + line="390">the baseline position of the @widget, or -1 @@ -85159,7 +87024,7 @@ the @widget using the layout management policy of @manager. c:identifier="gtk_layout_manager_get_layout_child"> Retrieves a `GtkLayoutChild` instance for the `GtkLayoutManager`, + line="498">Retrieves a `GtkLayoutChild` instance for the `GtkLayoutManager`, creating one if necessary. The @child widget must be a child of the widget using @manager. @@ -85171,20 +87036,20 @@ and is guaranteed to exist as long as @child is a child of the a `GtkLayoutChild` + line="512">a `GtkLayoutChild` a `GtkLayoutManager` + line="500">a `GtkLayoutManager` a `GtkWidget` + line="501">a `GtkWidget` @@ -85193,19 +87058,19 @@ and is guaranteed to exist as long as @child is a child of the c:identifier="gtk_layout_manager_get_request_mode"> Retrieves the request mode of @manager. + line="416">Retrieves the request mode of @manager. a `GtkSizeRequestMode` + line="422">a `GtkSizeRequestMode` a `GtkLayoutManager` + line="418">a `GtkLayoutManager` @@ -85213,19 +87078,19 @@ and is guaranteed to exist as long as @child is a child of the Retrieves the `GtkWidget` using the given `GtkLayoutManager`. + line="438">Retrieves the `GtkWidget` using the given `GtkLayoutManager`. a `GtkWidget` + line="444">a `GtkWidget` a `GtkLayoutManager` + line="440">a `GtkLayoutManager` @@ -85234,7 +87099,7 @@ and is guaranteed to exist as long as @child is a child of the c:identifier="gtk_layout_manager_layout_changed"> Queues a resize on the `GtkWidget` using @manager, if any. + line="456">Queues a resize on the `GtkWidget` using @manager, if any. This function should be called by subclasses of `GtkLayoutManager` in response to changes to their layout management policies. @@ -85246,7 +87111,7 @@ in response to changes to their layout management policies. a `GtkLayoutManager` + line="458">a `GtkLayoutManager` @@ -85254,7 +87119,7 @@ in response to changes to their layout management policies. Measures the size of the @widget using @manager, for the + line="297">Measures the size of the @widget using @manager, for the given @orientation and size. See the [class@Gtk.Widget] documentation on layout management for @@ -85267,25 +87132,25 @@ more details. a `GtkLayoutManager` + line="299">a `GtkLayoutManager` the `GtkWidget` using @manager + line="300">the `GtkWidget` using @manager the orientation to measure + line="301">the orientation to measure Size for the opposite of @orientation; for instance, if + line="302">Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the @@ -85301,7 +87166,7 @@ more details. allow-none="1"> the minimum size for the given size and + line="308">the minimum size for the given size and orientation @@ -85313,7 +87178,7 @@ more details. allow-none="1"> the natural, or preferred size for the + line="310">the natural, or preferred size for the given size and orientation @@ -85325,7 +87190,7 @@ more details. allow-none="1"> the baseline position for the + line="312">the baseline position for the minimum size @@ -85337,7 +87202,7 @@ more details. allow-none="1"> the baseline position for the + line="314">the baseline position for the natural size @@ -85360,6 +87225,11 @@ should only be accessed through the provided API, or when subclassing + a virtual function, used to return the preferred + request mode for the layout manager; for instance, "width for height" + or "height for width"; see `GtkSizeRequestMode` @@ -85376,6 +87246,10 @@ should only be accessed through the provided API, or when subclassing + a virtual function, used to measure the minimum and preferred + sizes of the widget using the layout manager for a given orientation @@ -85385,25 +87259,25 @@ should only be accessed through the provided API, or when subclassing a `GtkLayoutManager` + line="299">a `GtkLayoutManager` the `GtkWidget` using @manager + line="300">the `GtkWidget` using @manager the orientation to measure + line="301">the orientation to measure Size for the opposite of @orientation; for instance, if + line="302">Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the @@ -85419,7 +87293,7 @@ should only be accessed through the provided API, or when subclassing allow-none="1"> the minimum size for the given size and + line="308">the minimum size for the given size and orientation @@ -85431,7 +87305,7 @@ should only be accessed through the provided API, or when subclassing allow-none="1"> the natural, or preferred size for the + line="310">the natural, or preferred size for the given size and orientation @@ -85443,7 +87317,7 @@ should only be accessed through the provided API, or when subclassing allow-none="1"> the baseline position for the + line="312">the baseline position for the minimum size @@ -85455,7 +87329,7 @@ should only be accessed through the provided API, or when subclassing allow-none="1"> the baseline position for the + line="314">the baseline position for the natural size @@ -85463,6 +87337,10 @@ should only be accessed through the provided API, or when subclassing + a virtual function, used to allocate the size of the widget + using the layout manager @@ -85472,31 +87350,31 @@ should only be accessed through the provided API, or when subclassing a `GtkLayoutManager` + line="386">a `GtkLayoutManager` the `GtkWidget` using @manager + line="387">the `GtkWidget` using @manager the new width of the @widget + line="388">the new width of the @widget the new height of the @widget + line="389">the new height of the @widget the baseline position of the @widget, or -1 + line="390">the baseline position of the @widget, or -1 @@ -85509,6 +87387,10 @@ should only be accessed through the provided API, or when subclassing + a virtual function, used to create a `GtkLayoutChild` + meta object for the layout properties @@ -85540,6 +87422,10 @@ should only be accessed through the provided API, or when subclassing + a virtual function, called when the widget using the layout + manager is attached to a `GtkRoot` @@ -85553,6 +87439,10 @@ should only be accessed through the provided API, or when subclassing + a virtual function, called when the widget using the layout + manager is detached from a `GtkRoot` @@ -85579,12 +87469,15 @@ should only be accessed through the provided API, or when subclassing glib:get-type="gtk_level_bar_get_type"> `GtkLevelBar` is a widget that can be used as a level indicator. + line="21">Shows a level indicator. Typical use cases are displaying the strength of a password, or showing the charge level of a battery. -![An example GtkLevelBar](levelbar.png) +<picture> + <source srcset="levelbar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkLevelBar" src="levelbar.png"> +</picture> Use [method@Gtk.LevelBar.set_value] to set the current value, and [method@Gtk.LevelBar.add_offset_value] to set the value offsets at which @@ -85675,7 +87568,7 @@ regardless of text direction. # Accessibility -`GtkLevelBar` uses the %GTK_ACCESSIBLE_ROLE_METER role. +`GtkLevelBar` uses the [enum@Gtk.AccessibleRole.meter] role. @@ -85684,12 +87577,12 @@ regardless of text direction. Creates a new `GtkLevelBar`. + line="1071">Creates a new `GtkLevelBar`. a `GtkLevelBar`. + line="1076">a `GtkLevelBar`. @@ -85697,25 +87590,25 @@ regardless of text direction. c:identifier="gtk_level_bar_new_for_interval"> Creates a new `GtkLevelBar` for the specified interval. + line="1084">Creates a new `GtkLevelBar` for the specified interval. a `GtkLevelBar` + line="1091">a `GtkLevelBar` a positive value + line="1086">a positive value a positive value + line="1087">a positive value @@ -85724,7 +87617,7 @@ regardless of text direction. c:identifier="gtk_level_bar_add_offset_value"> Adds a new offset marker on @self at the position specified by @value. + line="1369">Adds a new offset marker on @self at the position specified by @value. When the bar value is in the interval topped by @value (or between @value and [property@Gtk.LevelBar:max-value] in case the offset is the last one @@ -85741,19 +87634,19 @@ replaced by @value. a `GtkLevelBar` + line="1371">a `GtkLevelBar` the name of the new offset + line="1372">the name of the new offset the value for the new offset + line="1373">the value for the new offset @@ -85761,22 +87654,21 @@ replaced by @value. - Returns whether the levelbar is inverted. + line="1303">Returns whether the levelbar is inverted. %TRUE if the level bar is inverted + line="1309">%TRUE if the level bar is inverted a `GtkLevelBar` + line="1305">a `GtkLevelBar` @@ -85784,22 +87676,21 @@ replaced by @value. - Returns the `max-value` of the `GtkLevelBar`. + line="1119">Returns the `max-value` of the `GtkLevelBar`. a positive value + line="1125">a positive value a `GtkLevelBar` + line="1121">a `GtkLevelBar` @@ -85807,22 +87698,21 @@ replaced by @value. - Returns the `min-value` of the `GtkLevelBar`. + line="1103">Returns the `min-value` of the `GtkLevelBar`. a positive value + line="1109">a positive value a `GtkLevelBar` + line="1105">a `GtkLevelBar` @@ -85830,22 +87720,21 @@ replaced by @value. - Returns the `mode` of the `GtkLevelBar`. + line="1261">Returns the `mode` of the `GtkLevelBar`. a `GtkLevelBarMode` + line="1267">a `GtkLevelBarMode` a `GtkLevelBar` + line="1263">a `GtkLevelBar` @@ -85854,19 +87743,19 @@ replaced by @value. c:identifier="gtk_level_bar_get_offset_value"> Fetches the value specified for the offset marker @name in @self. + line="1403">Fetches the value specified for the offset marker @name in @self. %TRUE if the specified offset is found + line="1411">%TRUE if the specified offset is found a `GtkLevelBar` + line="1405">a `GtkLevelBar` allow-none="1"> the name of an offset in the bar + line="1406">the name of an offset in the bar transfer-ownership="full"> location where to store the value + line="1407">location where to store the value @@ -85892,15 +87781,14 @@ replaced by @value. - Returns the `value` of the `GtkLevelBar`. + line="1135">Returns the `value` of the `GtkLevelBar`. a value in the interval between + line="1141">a value in the interval between [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] @@ -85908,7 +87796,7 @@ replaced by @value. a `GtkLevelBar` + line="1137">a `GtkLevelBar` @@ -85917,7 +87805,7 @@ replaced by @value. c:identifier="gtk_level_bar_remove_offset_value"> Removes an offset marker from a `GtkLevelBar`. + line="1341">Removes an offset marker from a `GtkLevelBar`. The marker must have been previously added with [method@Gtk.LevelBar.add_offset_value]. @@ -85929,7 +87817,7 @@ The marker must have been previously added with a `GtkLevelBar` + line="1343">a `GtkLevelBar` the name of an offset in the bar + line="1344">the name of an offset in the bar @@ -85946,10 +87834,9 @@ The marker must have been previously added with - Sets whether the `GtkLevelBar` is inverted. + line="1319">Sets whether the `GtkLevelBar` is inverted. @@ -85958,13 +87845,13 @@ The marker must have been previously added with a `GtkLevelBar` + line="1321">a `GtkLevelBar` %TRUE to invert the level bar + line="1322">%TRUE to invert the level bar @@ -85972,10 +87859,9 @@ The marker must have been previously added with - Sets the `max-value` of the `GtkLevelBar`. + line="1199">Sets the `max-value` of the `GtkLevelBar`. You probably want to update preexisting level offsets after calling this function. @@ -85987,13 +87873,13 @@ this function. a `GtkLevelBar` + line="1201">a `GtkLevelBar` a positive value + line="1202">a positive value @@ -86001,10 +87887,9 @@ this function. - Sets the `min-value` of the `GtkLevelBar`. + line="1163">Sets the `min-value` of the `GtkLevelBar`. You probably want to update preexisting level offsets after calling this function. @@ -86016,13 +87901,13 @@ this function. a `GtkLevelBar` + line="1165">a `GtkLevelBar` a positive value + line="1166">a positive value @@ -86030,10 +87915,9 @@ this function. - Sets the `mode` of the `GtkLevelBar`. + line="1277">Sets the `mode` of the `GtkLevelBar`. @@ -86042,13 +87926,13 @@ this function. a `GtkLevelBar` + line="1279">a `GtkLevelBar` a `GtkLevelBarMode` + line="1280">a `GtkLevelBarMode` @@ -86056,10 +87940,9 @@ this function. - Sets the value of the `GtkLevelBar`. + line="1236">Sets the value of the `GtkLevelBar`. @@ -86068,13 +87951,13 @@ this function. a `GtkLevelBar` + line="1238">a `GtkLevelBar` a value in the interval between + line="1239">a value in the interval between [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] @@ -86086,13 +87969,9 @@ this function. setter="set_inverted" getter="get_inverted" default-value="FALSE"> - - Whether the `GtkLeveBar` is inverted. + line="1010">Whether the `GtkLeveBar` is inverted. Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction. @@ -86104,13 +87983,9 @@ Inverted level bars grow in the opposite direction. setter="set_max_value" getter="get_max_value" default-value="1.000000"> - - Determines the maximum value of the interval that can be displayed by the bar. + line="980">Determines the maximum value of the interval that can be displayed by the bar. setter="set_min_value" getter="get_min_value" default-value="0.000000"> - - Determines the minimum value of the interval that can be displayed by the bar. + line="970">Determines the minimum value of the interval that can be displayed by the bar. setter="set_mode" getter="get_mode" default-value="GTK_LEVEL_BAR_MODE_CONTINUOUS"> - - Determines the way `GtkLevelBar` interprets the value properties to draw the + line="990">Determines the way `GtkLevelBar` interprets the value properties to draw the level fill area. Specifically, when the value is %GTK_LEVEL_BAR_MODE_CONTINUOUS, @@ -86156,19 +88025,15 @@ the integral roundings of [property@Gtk.LevelBar:min-value] and setter="set_value" getter="get_value" default-value="0.000000"> - - Determines the currently filled value of the level bar. + line="960">Determines the currently filled value of the level bar. Emitted when an offset specified on the bar changes value. + line="936">Emitted when an offset specified on the bar changes value. This typically is the result of a [method@Gtk.LevelBar.add_offset_value] call. @@ -86183,7 +88048,7 @@ the value of offset "x" changes. the name of the offset that changed value + line="939">the name of the offset that changed value @@ -86195,7 +88060,7 @@ the value of offset "x" changes. c:type="GtkLevelBarMode"> Describes how [class@LevelBar] contents should be rendered. + line="905">Describes how [class@LevelBar] contents should be rendered. Note that this enumeration could be extended with additional modes in the future. @@ -86206,7 +88071,7 @@ in the future. glib:name="GTK_LEVEL_BAR_MODE_CONTINUOUS"> the bar has a continuous mode + line="907">the bar has a continuous mode glib:name="GTK_LEVEL_BAR_MODE_DISCRETE"> the bar has a discrete mode + line="908">the bar has a discrete mode filename="gtk/gtkaboutdialog.h" line="59">The Mozilla Public License, version 2.0 + + Zero-Clause BSD license + glib:get-type="gtk_link_button_get_type"> A `GtkLinkButton` is a button with a hyperlink. + line="24">A button with a hyperlink. -![An example GtkLinkButton](link-button.png) +<picture> + <source srcset="link-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkLinkButton" src="link-button.png"> +</picture> It is useful to show quick links to resources. @@ -86417,6 +88294,19 @@ is clicked. This behaviour can be overridden by connecting to the [signal@Gtk.LinkButton::activate-link] signal and returning %TRUE from the signal handler. +# Shortcuts and Gestures + +`GtkLinkButton` supports the following keyboard shortcuts: + +- <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. + +# Actions + +`GtkLinkButton` defines a set of built-in actions: + +- `clipboard.copy` copies the url to the clipboard. +- `menu.popup` opens the context menu. + # CSS nodes `GtkLinkButton` has a single CSS node with name button. To differentiate @@ -86424,7 +88314,7 @@ it from a plain `GtkButton`, it gets the .link style class. # Accessibility -`GtkLinkButton` uses the %GTK_ACCESSIBLE_ROLE_LINK role. +`GtkLinkButton` uses the [enum@Gtk.AccessibleRole.link] role. @@ -86432,19 +88322,19 @@ it from a plain `GtkButton`, it gets the .link style class. Creates a new `GtkLinkButton` with the URI as its text. + line="572">Creates a new `GtkLinkButton` with the URI as its text. a new link button widget. + line="578">a new link button widget. a valid URI + line="574">a valid URI @@ -86453,19 +88343,19 @@ it from a plain `GtkButton`, it gets the .link style class. c:identifier="gtk_link_button_new_with_label"> Creates a new `GtkLinkButton` containing a label. + line="619">Creates a new `GtkLinkButton` containing a label. a new link button widget. + line="626">a new link button widget. a valid URI + line="621">a valid URI the text of the button + line="622">the text of the button @@ -86482,15 +88372,14 @@ it from a plain `GtkButton`, it gets the .link style class. - Retrieves the URI of the `GtkLinkButton`. + line="699">Retrieves the URI of the `GtkLinkButton`. a valid URI. The returned string is owned by the link button + line="705">a valid URI. The returned string is owned by the link button and should not be modified or freed. @@ -86498,7 +88387,7 @@ it from a plain `GtkButton`, it gets the .link style class. a `GtkLinkButton` + line="701">a `GtkLinkButton` @@ -86506,10 +88395,9 @@ it from a plain `GtkButton`, it gets the .link style class. - Retrieves the “visited” state of the `GtkLinkButton`. + line="756">Retrieves the “visited” state of the `GtkLinkButton`. The button becomes visited when it is clicked. If the URI is changed on the button, the “visited” state is unset again. @@ -86519,14 +88407,14 @@ The state may also be changed using [method@Gtk.LinkButton.set_visited]. %TRUE if the link has been visited, %FALSE otherwise + line="767">%TRUE if the link has been visited, %FALSE otherwise a `GtkLinkButton` + line="758">a `GtkLinkButton` @@ -86534,10 +88422,9 @@ The state may also be changed using [method@Gtk.LinkButton.set_visited]. - Sets @uri as the URI where the `GtkLinkButton` points. + line="675">Sets @uri as the URI where the `GtkLinkButton` points. As a side-effect this unsets the “visited” state of the button. @@ -86548,13 +88435,13 @@ As a side-effect this unsets the “visited” state of the button. a `GtkLinkButton` + line="677">a `GtkLinkButton` a valid URI + line="678">a valid URI @@ -86562,10 +88449,9 @@ As a side-effect this unsets the “visited” state of the button. - Sets the “visited” state of the `GtkLinkButton`. + line="716">Sets the “visited” state of the `GtkLinkButton`. See [method@Gtk.LinkButton.get_visited] for more details. @@ -86576,13 +88462,13 @@ See [method@Gtk.LinkButton.get_visited] for more details. a `GtkLinkButton` + line="718">a `GtkLinkButton` the new “visited” state + line="719">the new “visited” state @@ -86593,13 +88479,9 @@ See [method@Gtk.LinkButton.get_visited] for more details. setter="set_uri" getter="get_uri" default-value="NULL"> - - The URI bound to this button. + line="188">The URI bound to this button. setter="set_visited" getter="get_visited" default-value="FALSE"> - - The 'visited' state of this button. + line="199">The 'visited' state of this button. A visited link is drawn in a different color. @@ -86622,7 +88500,7 @@ A visited link is drawn in a different color. Emitted each time the `GtkLinkButton` is clicked. + line="212">Emitted each time the `GtkLinkButton` is clicked. The default handler will call [method@Gtk.FileLauncher.launch] with the URI stored inside the [property@Gtk.LinkButton:uri] property. @@ -86633,7 +88511,7 @@ by returning %TRUE from your handler. %TRUE if the signal has been handled + line="225">%TRUE if the signal has been handled @@ -86648,8 +88526,51 @@ by returning %TRUE from your handler. glib:type-struct="ListBaseClass"> `GtkListBase` is the abstract base class for GTK's list widgets. - + line="38">The abstract base class for GTK's list widgets. + +# Shortcuts and Gestures + +`GtkListBase` supports the following keyboard shortcuts: + +- <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> + selects all items. +- <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or + <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all items. + +The focused item is controlled by the navigation keys below, combined +with the <kbd>Ctrl</kbd> modifier to prevent moving the selection, +and the <kbd>Shift</kbd> modifier to extend the current selection. + +- <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move the focus + on the next item in the designed direction. +- <kbd>Home</kbd> and <kbd>End</kbd> focus the first or last item. +- <kbd>PgUp</kbd> and <kbd>PgDn</kbd> move the focus one page up or down. + +List item widgets support the following keyboard shortcuts: + +- <kbd>Enter</kbd> activates the item. +- <kbd>␣</kbd> selects the item, with the same <kbd>Ctrl</kbd> and + <kbd>Shift</kbd> modifiers combinations as the navigation keys. + +# Actions + +`GtkListBase` defines a set of built-in actions: + +- `list.scroll-to-item` moves the visible area to the item at given position + with the minimum amount of scrolling required. If the item is already + visible, nothing happens. +- `list.select-item` changes the selection. +- `list.select-all` selects all items in the model, if the selection model + supports it. +- `list.unselect-all` unselects all items in the model, if the selection + model supports it. + +List item widgets install the following actions: + +- `listitem.select` changes selection if the item is selectable. +- `listitem.scroll-to` moves the visible area of the list to this item with + the minimum amount of scrolling required. + @@ -86661,7 +88582,7 @@ by returning %TRUE from your handler. default-value="GTK_ORIENTATION_VERTICAL"> The orientation of the list. See GtkOrientable:orientation + line="1288">The orientation of the list. See GtkOrientable:orientation for details. @@ -86671,7 +88592,7 @@ for details. disguised="1" opaque="1" glib:is-gtype-struct-for="ListBase"> - + glib:get-type="gtk_list_box_get_type"> `GtkListBox` is a vertical list. + line="40">Shows a vertical list. + +<picture> + <source srcset="list-box-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkListBox" src="list-box.png"> +</picture> A `GtkListBox` only contains `GtkListBoxRow` children. These rows can by dynamically sorted and filtered, and headers can be added dynamically @@ -86711,6 +88637,15 @@ setting a child as the placeholder by specifying “placeholder” as the “typ attribute of a `<child>` element. See [method@Gtk.ListBox.set_placeholder] for info. +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.ListBox::move-cursor] +- [signal@Gtk.ListBox::select-all] +- [signal@Gtk.ListBox::toggle-cursor-row] +- [signal@Gtk.ListBox::unselect-all] + # CSS nodes |[<!-- language="plain" --> @@ -86732,27 +88667,27 @@ the style of [list presentation](section-list-widget.html#list-styles): # Accessibility -`GtkListBox` uses the %GTK_ACCESSIBLE_ROLE_LIST role and `GtkListBoxRow` uses -the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role. +`GtkListBox` uses the [enum@Gtk.AccessibleRole.list] role and `GtkListBoxRow` uses +the [enum@Gtk.AccessibleRole.list_item] role. Creates a new `GtkListBox` container. + line="385">Creates a new `GtkListBox` container. a new `GtkListBox` + line="390">a new `GtkListBox` Append a widget to the list. + line="3022">Append a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position. @@ -86764,13 +88699,13 @@ actually be inserted at the calculated position. a `GtkListBox` + line="3024">a `GtkListBox` the `GtkWidget` to add + line="3025">the `GtkWidget` to add @@ -86778,7 +88713,7 @@ actually be inserted at the calculated position. Binds @model to @box. + line="4053">Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. @@ -86801,7 +88736,7 @@ should be implemented by the model. a `GtkListBox` + line="4055">a `GtkListBox` allow-none="1"> the `GListModel` to be bound to @box + line="4056">the `GListModel` to be bound to @box destroy="3"> a function that creates widgets for items - or %NULL in case you also passed %NULL as @model + line="4057">a function + that creates widgets for items or %NULL in case you also passed %NULL as @model @@ -86833,7 +88768,7 @@ should be implemented by the model. allow-none="1"> user data passed to @create_widget_func + line="4059">user data passed to @create_widget_func scope="async"> function for freeing @user_data + line="4060">function for freeing @user_data @@ -86850,7 +88785,7 @@ should be implemented by the model. c:identifier="gtk_list_box_drag_highlight_row"> Add a drag highlight to a row. + line="3126">Add a drag highlight to a row. This is a helper function for implementing DnD onto a `GtkListBox`. The passed in @row will be highlighted by setting the @@ -86867,13 +88802,13 @@ a drag leave event. a `GtkListBox` + line="3128">a `GtkListBox` a `GtkListBoxRow` + line="3129">a `GtkListBoxRow` @@ -86882,7 +88817,7 @@ a drag leave event. c:identifier="gtk_list_box_drag_unhighlight_row"> If a row has previously been highlighted via gtk_list_box_drag_highlight_row(), + line="3107">If a row has previously been highlighted via gtk_list_box_drag_highlight_row(), it will have the highlight removed. @@ -86892,7 +88827,7 @@ it will have the highlight removed. a `GtkListBox` + line="3109">a `GtkListBox` @@ -86900,23 +88835,21 @@ it will have the highlight removed. - Returns whether rows activate on single clicks. + line="1559">Returns whether rows activate on single clicks. %TRUE if rows are activated on single click, %FALSE otherwise + line="1565">%TRUE if rows are activated on single click, %FALSE otherwise a `GtkListBox` + line="1561">a `GtkListBox` @@ -86924,20 +88857,20 @@ it will have the highlight removed. Gets the adjustment (if any) that the widget uses to + line="1154">Gets the adjustment (if any) that the widget uses to for vertical scrolling. the adjustment + line="1161">the adjustment a `GtkListBox` + line="1156">a `GtkListBox` @@ -86946,7 +88879,7 @@ for vertical scrolling. c:identifier="gtk_list_box_get_row_at_index"> Gets the n-th child in the list (not counting headers). + line="853">Gets the n-th child in the list (not counting headers). If @index_ is negative or larger than the number of items in the list, %NULL is returned. @@ -86954,20 +88887,20 @@ list, %NULL is returned. the child `GtkWidget` + line="863">the child `GtkWidget` a `GtkListBox` + line="855">a `GtkListBox` the index of the row + line="856">the index of the row @@ -86975,25 +88908,25 @@ list, %NULL is returned. Gets the row at the @y position. + line="897">Gets the row at the @y position. the row + line="904">the row a `GtkListBox` + line="899">a `GtkListBox` position + line="900">position @@ -87002,7 +88935,7 @@ list, %NULL is returned. c:identifier="gtk_list_box_get_selected_row"> Gets the selected row, or %NULL if no rows are selected. + line="833">Gets the selected row, or %NULL if no rows are selected. Note that the box may allow multiple selection, in which case you should use [method@Gtk.ListBox.selected_foreach] to @@ -87011,14 +88944,14 @@ find all selected rows. the selected row + line="843">the selected row a `GtkListBox` + line="835">a `GtkListBox` @@ -87027,12 +88960,12 @@ find all selected rows. c:identifier="gtk_list_box_get_selected_rows"> Creates a list of all selected children. + line="1062">Creates a list of all selected children. + line="1068"> A `GList` containing the `GtkWidget` for each selected child. Free with g_list_free() when done. @@ -87043,7 +88976,7 @@ find all selected rows. a `GtkListBox` + line="1064">a `GtkListBox` @@ -87051,22 +88984,21 @@ find all selected rows. - Gets the selection mode of the listbox. + line="1253">Gets the selection mode of the listbox. a `GtkSelectionMode` + line="1259">a `GtkSelectionMode` a `GtkListBox` + line="1255">a `GtkListBox` @@ -87074,23 +89006,45 @@ find all selected rows. - Returns whether the list box should show separators + line="4150">Returns whether the list box should show separators between rows. %TRUE if the list box shows separators + line="4157">%TRUE if the list box shows separators a `GtkListBox` + line="4152">a `GtkListBox` + + + + + + Returns the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + + + the tab behavior + + + + + a `GtkListBox` @@ -87098,7 +89052,7 @@ between rows. Insert the @child into the @box at @position. + line="3039">Insert the @child into the @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position. @@ -87113,19 +89067,19 @@ If @position is -1, or larger than the total number of items in the a `GtkListBox` + line="3041">a `GtkListBox` the `GtkWidget` to add + line="3042">the `GtkWidget` to add the position to insert @child in + line="3043">the position to insert @child in @@ -87134,7 +89088,7 @@ If @position is -1, or larger than the total number of items in the c:identifier="gtk_list_box_invalidate_filter"> Update the filtering for all rows. + line="1362">Update the filtering for all rows. Call this when result of the filter function on the @box is changed due @@ -87149,7 +89103,7 @@ string and the entry with the search string has changed. a `GtkListBox` + line="1364">a `GtkListBox` @@ -87158,7 +89112,7 @@ string and the entry with the search string has changed. c:identifier="gtk_list_box_invalidate_headers"> Update the separators for all rows. + line="1446">Update the separators for all rows. Call this when result of the header function on the @box is changed due @@ -87171,7 +89125,7 @@ to an external factor. a `GtkListBox` + line="1448">a `GtkListBox` @@ -87180,7 +89134,7 @@ to an external factor. c:identifier="gtk_list_box_invalidate_sort"> Update the sorting for all rows. + line="1405">Update the sorting for all rows. Call this when result of the sort function on the @box is changed due @@ -87193,7 +89147,7 @@ to an external factor. a `GtkListBox` + line="1407">a `GtkListBox` @@ -87201,7 +89155,7 @@ to an external factor. Prepend a widget to the list. + line="3005">Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position. @@ -87213,13 +89167,13 @@ actually be inserted at the calculated position. a `GtkListBox` + line="3007">a `GtkListBox` the `GtkWidget` to add + line="3008">the `GtkWidget` to add @@ -87227,7 +89181,7 @@ actually be inserted at the calculated position. Removes a child from @box. + line="2412">Removes a child from @box. @@ -87236,13 +89190,13 @@ actually be inserted at the calculated position. a `GtkListBox` + line="2414">a `GtkListBox` the child to remove + line="2415">the child to remove @@ -87252,7 +89206,7 @@ actually be inserted at the calculated position. version="4.12"> Removes all rows from @box. + line="2516">Removes all rows from @box. This function does nothing if @box is backed by a model. @@ -87263,7 +89217,7 @@ This function does nothing if @box is backed by a model. a `GtkListBox` + line="2518">a `GtkListBox` @@ -87271,7 +89225,7 @@ This function does nothing if @box is backed by a model. Select all children of @box, if the selection mode allows it. + line="970">Select all children of @box, if the selection mode allows it. @@ -87280,7 +89234,7 @@ This function does nothing if @box is backed by a model. a `GtkListBox` + line="972">a `GtkListBox` @@ -87288,7 +89242,7 @@ This function does nothing if @box is backed by a model. Make @row the currently selected row. + line="925">Make @row the currently selected row. @@ -87297,7 +89251,7 @@ This function does nothing if @box is backed by a model. a `GtkListBox` + line="927">a `GtkListBox` allow-none="1"> The row to select + line="928">The row to select @@ -87315,7 +89269,7 @@ This function does nothing if @box is backed by a model. c:identifier="gtk_list_box_selected_foreach"> Calls a function for each selected child. + line="1032">Calls a function for each selected child. Note that the selection cannot be modified from within this function. @@ -87326,7 +89280,7 @@ Note that the selection cannot be modified from within this function. a `GtkListBox` + line="1034">a `GtkListBox` closure="1"> the function to call for each selected child + line="1035">the function to call for each selected child allow-none="1"> user data to pass to the function + line="1036">user data to pass to the function @@ -87352,11 +89306,9 @@ Note that the selection cannot be modified from within this function. - If @single is %TRUE, rows will be activated when you click on them, + line="1535">If @single is %TRUE, rows will be activated when you click on them, otherwise you need to double-click. @@ -87366,13 +89318,13 @@ otherwise you need to double-click. a `GtkListBox` + line="1537">a `GtkListBox` a boolean + line="1538">a boolean @@ -87380,7 +89332,7 @@ otherwise you need to double-click. Sets the adjustment (if any) that the widget uses to + line="1124">Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for @@ -87398,7 +89350,7 @@ to manually do that. a `GtkListBox` + line="1126">a `GtkListBox` allow-none="1"> the adjustment + line="1127">the adjustment @@ -87416,7 +89368,7 @@ to manually do that. c:identifier="gtk_list_box_set_filter_func"> By setting a filter function on the @box one can decide dynamically which + line="1269">By setting a filter function on the @box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that @@ -87437,7 +89389,7 @@ Note that using a filter function is incompatible with using a model a `GtkListBox` + line="1271">a `GtkListBox` callback that lets you filter which rows to show + line="1272">callback + that lets you filter which rows to show user data passed to @filter_func + line="1274">user data passed to @filter_func destroy notifier for @user_data + line="1275">destroy notifier for @user_data @@ -87473,7 +89426,7 @@ Note that using a filter function is incompatible with using a model c:identifier="gtk_list_box_set_header_func"> Sets a header function. + line="1311">Sets a header function. By setting a header function on the @box one can dynamically add headers in front of rows, depending on the contents of the row and its position @@ -87506,7 +89459,7 @@ row becomes a different row). It is also called for all rows when a `GtkListBox` + line="1313">a `GtkListBox` callback that lets you add row headers + line="1314">callback + that lets you add row headers @@ -87528,13 +89482,13 @@ row becomes a different row). It is also called for all rows when allow-none="1"> user data passed to @update_header + line="1316">user data passed to @update_header destroy notifier for @user_data + line="1317">destroy notifier for @user_data @@ -87543,7 +89497,7 @@ row becomes a different row). It is also called for all rows when c:identifier="gtk_list_box_set_placeholder"> Sets the placeholder widget that is shown in the list when + line="1093">Sets the placeholder widget that is shown in the list when it doesn't display any visible children. @@ -87553,7 +89507,7 @@ it doesn't display any visible children. a `GtkListBox` + line="1095">a `GtkListBox` allow-none="1"> a `GtkWidget` + line="1096">a `GtkWidget` @@ -87570,10 +89524,9 @@ it doesn't display any visible children. - Sets how selection works in the listbox. + line="1214">Sets how selection works in the listbox. @@ -87582,13 +89535,13 @@ it doesn't display any visible children. a `GtkListBox` + line="1216">a `GtkListBox` The `GtkSelectionMode` + line="1217">The `GtkSelectionMode` @@ -87596,10 +89549,9 @@ it doesn't display any visible children. - Sets whether the list box should show separators + line="4123">Sets whether the list box should show separators between rows. @@ -87609,13 +89561,13 @@ between rows. a `GtkListBox` + line="4125">a `GtkListBox` %TRUE to show separators + line="4126">%TRUE to show separators @@ -87623,7 +89575,7 @@ between rows. Sets a sort function. + line="1467">Sets a sort function. By setting a sort function on the @box one can dynamically reorder the rows of the list, based on the contents of the rows. @@ -87643,7 +89595,7 @@ Note that using a sort function is incompatible with using a model a `GtkListBox` + line="1469">a `GtkListBox` the sort function + line="1470">the sort function user data passed to @sort_func + line="1471">user data passed to @sort_func destroy notifier for @user_data + line="1472">destroy notifier for @user_data + + Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + + + + + + + a `GtkListBox` + + + + the tab behavior + + + + Unselect all children of @box, if the selection mode allows it. + line="991">Unselect all children of @box, if the selection mode allows it. @@ -87687,7 +89665,7 @@ Note that using a sort function is incompatible with using a model a `GtkListBox` + line="993">a `GtkListBox` @@ -87695,7 +89673,7 @@ Note that using a sort function is incompatible with using a model Unselects a single row of @box, if the selection mode allows it. + line="953">Unselects a single row of @box, if the selection mode allows it. @@ -87704,13 +89682,13 @@ Note that using a sort function is incompatible with using a model a `GtkListBox` + line="955">a `GtkListBox` the row to unselect + line="956">the row to unselect @@ -87721,7 +89699,7 @@ Note that using a sort function is incompatible with using a model default-value="FALSE"> Whether to accept unpaired release events. + line="547">Whether to accept unpaired release events. - - Determines whether children can be activated with a single + line="536">Determines whether children can be activated with a single click, or require a double-click. @@ -87746,13 +89720,9 @@ click, or require a double-click. setter="set_selection_mode" getter="get_selection_mode" default-value="GTK_SELECTION_SINGLE"> - - The selection mode used by the list box. + line="525">The selection mode used by the list box. setter="set_show_separators" getter="get_show_separators" default-value="FALSE"> - - Whether to show separators between rows. + line="558">Whether to show separators between rows. + + Behavior of the <kbd>Tab</kbd> key + + + Emitted when the cursor row is activated. + Emitted when the user initiates a cursor movement. + +The default bindings for this signal come in two variants, the variant with +the Shift modifier extends the selection, the variant without the Shift +modifier does not. There are too many key combinations to list them all +here. + +- <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> + move by individual children +- <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the box +- <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages - + + the granularity of the move, as a `GtkMovementStep` - + + the number of @step units to move - + + whether to extend the selection - + + whether to modify the selection @@ -87797,7 +89803,7 @@ click, or require a double-click. Emitted when a row has been activated by the user. + line="658">Emitted when a row has been activated by the user. @@ -87805,7 +89811,7 @@ click, or require a double-click. the activated row + line="661">the activated row @@ -87813,7 +89819,7 @@ click, or require a double-click. Emitted when a new row is selected, or (with a %NULL @row) + line="583">Emitted when a new row is selected, or (with a %NULL @row) when the selection is cleared. When the @box is using %GTK_SELECTION_MULTIPLE, this signal will not @@ -87829,7 +89835,7 @@ the [signal@Gtk.ListBox::selected-rows-changed] signal instead. allow-none="1"> the selected row + line="586">the selected row @@ -87837,7 +89843,7 @@ the [signal@Gtk.ListBox::selected-rows-changed] signal instead. Emitted to select all children of the box, if the selection + line="619">Emitted to select all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). @@ -87850,12 +89856,17 @@ The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>a& Emitted when the set of selected rows changes. + line="605">Emitted when the set of selected rows changes. + Emitted when the cursor row is toggled. + +The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>␣</kbd>. @@ -87863,7 +89874,7 @@ The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>a& Emitted to unselect all children of the box, if the selection + line="638">Emitted to unselect all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). @@ -87944,7 +89955,7 @@ if the row should be visible or not. A function used by gtk_list_box_selected_foreach(). + line="1021">A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the @box. @@ -87955,13 +89966,13 @@ It will be called on every selected child of the @box. a `GtkListBox` + line="1023">a `GtkListBox` a `GtkListBoxRow` + line="1024">a `GtkListBoxRow` closure="2"> user data + line="1025">user data @@ -87985,7 +89996,10 @@ It will be called on every selected child of the @box. glib:type-struct="ListBoxRowClass"> `GtkListBoxRow` is the kind of widget that can be added to a `GtkListBox`. + line="112">The kind of widget that can be added to a `GtkListBox`. + +[class@Gtk.ListBox] will automatically wrap its children in a `GtkListboxRow` +when necessary. @@ -87994,12 +90008,12 @@ It will be called on every selected child of the @box. Creates a new `GtkListBoxRow`. + line="3306">Creates a new `GtkListBoxRow`. a new `GtkListBoxRow` + line="3311">a new `GtkListBoxRow` @@ -88017,7 +90031,7 @@ It will be called on every selected child of the @box. Marks @row as changed, causing any state that depends on this + line="3482">Marks @row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers. @@ -88043,7 +90057,7 @@ but that is more expensive. a `GtkListBoxRow` + line="3484">a `GtkListBoxRow` @@ -88051,22 +90065,21 @@ but that is more expensive. - Gets whether the row is activatable. + line="3677">Gets whether the row is activatable. %TRUE if the row is activatable + line="3683">%TRUE if the row is activatable a `GtkListBoxRow` + line="3679">a `GtkListBoxRow` @@ -88074,22 +90087,21 @@ but that is more expensive. - Gets the child widget of @row. + line="3347">Gets the child widget of @row. the child widget of @row + line="3353">the child widget of @row a `GtkListBoxRow` + line="3349">a `GtkListBoxRow` @@ -88097,7 +90109,7 @@ but that is more expensive. Returns the current header of the @row. + line="3517">Returns the current header of the @row. This can be used in a [callback@Gtk.ListBoxUpdateHeaderFunc] to see if @@ -88107,14 +90119,14 @@ the state of it. the current header + line="3528">the current header a `GtkListBoxRow` + line="3519">a `GtkListBoxRow` @@ -88122,19 +90134,19 @@ the state of it. Gets the current index of the @row in its `GtkListBox` container. + line="3568">Gets the current index of the @row in its `GtkListBox` container. the index of the @row, or -1 if the @row is not in a listbox + line="3574">the index of the @row, or -1 if the @row is not in a listbox a `GtkListBoxRow` + line="3570">a `GtkListBoxRow` @@ -88142,22 +90154,21 @@ the state of it. - Gets whether the row can be selected. + line="3721">Gets whether the row can be selected. %TRUE if the row is selectable + line="3727">%TRUE if the row is selectable a `GtkListBoxRow` + line="3723">a `GtkListBoxRow` @@ -88165,20 +90176,20 @@ the state of it. Returns whether the child is currently selected in its + line="3589">Returns whether the child is currently selected in its `GtkListBox` container. %TRUE if @row is selected + line="3596">%TRUE if @row is selected a `GtkListBoxRow` + line="3591">a `GtkListBoxRow` @@ -88186,10 +90197,9 @@ the state of it. - Set whether the row is activatable. + line="3653">Set whether the row is activatable. @@ -88198,13 +90208,13 @@ the state of it. a `GtkListBoxRow` + line="3655">a `GtkListBoxRow` %TRUE to mark the row as activatable + line="3656">%TRUE to mark the row as activatable @@ -88212,10 +90222,9 @@ the state of it. - Sets the child widget of @self. + line="3319">Sets the child widget of @self. @@ -88224,7 +90233,7 @@ the state of it. a `GtkListBoxRow` + line="3321">a `GtkListBoxRow` allow-none="1"> the child widget + line="3322">the child widget @@ -88241,7 +90250,7 @@ the state of it. Sets the current header of the @row. + line="3538">Sets the current header of the @row. This is only allowed to be called from a [callback@Gtk.ListBoxUpdateHeaderFunc]. @@ -88255,7 +90264,7 @@ and be shown in front of the row in the listbox. a `GtkListBoxRow` + line="3540">a `GtkListBoxRow` allow-none="1"> the header + line="3541">the header @@ -88272,10 +90281,9 @@ and be shown in front of the row in the listbox. - Set whether the row can be selected. + line="3693">Set whether the row can be selected. @@ -88284,13 +90292,13 @@ and be shown in front of the row in the listbox. a `GtkListBoxRow` + line="3695">a `GtkListBoxRow` %TRUE to mark the row as selectable + line="3696">%TRUE to mark the row as selectable @@ -88301,13 +90309,9 @@ and be shown in front of the row in the listbox. setter="set_activatable" getter="get_activatable" default-value="TRUE"> - - Determines whether the ::row-activated + line="3928">Determines whether the ::row-activated signal will be emitted for this row. @@ -88316,13 +90320,9 @@ signal will be emitted for this row. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="3949">The child widget. setter="set_selectable" getter="get_selectable" default-value="TRUE"> - - Determines whether this row can be selected. + line="3939">Determines whether this row can be selected. @@ -88346,7 +90342,7 @@ signal will be emitted for this row. This is a keybinding signal, which will cause this row to be activated. + line="3908">This is a keybinding signal, which will cause this row to be activated. If you want to be notified when the user activates a row (by key or not), use the [signal@Gtk.ListBox::row-activated] signal on the row’s parent @@ -88473,8 +90469,7 @@ or just change the state of the current header widget. glib:type-struct="ListHeaderClass"> `GtkListHeader` is used by list widgets to represent the headers they -display. + line="24">Used by list widgets to represent the headers they display. `GtkListHeader` objects are managed just like [class@Gtk.ListItem] objects via their factory, but provide a different set of properties suitable @@ -88484,23 +90479,22 @@ for managing the header instead of individual items. c:identifier="gtk_list_header_get_child" glib:get-property="child" version="4.12"> - Gets the child previously set via gtk_list_header_set_child() or + line="253">Gets the child previously set via gtk_list_header_set_child() or %NULL if none was set. The child + line="260">The child a `GtkListHeader` + line="255">a `GtkListHeader` @@ -88509,10 +90503,9 @@ for managing the header instead of individual items. c:identifier="gtk_list_header_get_end" glib:get-property="end" version="4.12"> - Gets the end position in the model of the section that @self is + line="333">Gets the end position in the model of the section that @self is currently the header for. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. @@ -88520,14 +90513,14 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The end position of the section + line="342">The end position of the section a `GtkListHeader` + line="335">a `GtkListHeader` @@ -88536,10 +90529,9 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. c:identifier="gtk_list_header_get_item" glib:get-property="item" version="4.12"> - Gets the model item at the start of the section. + line="228">Gets the model item at the start of the section. This is the item that occupies the list model at position [property@Gtk.ListHeader:start]. @@ -88548,14 +90540,14 @@ If @self is unbound, this function returns %NULL. The item displayed + line="238">The item displayed a `GtkListHeader` + line="230">a `GtkListHeader` @@ -88564,24 +90556,23 @@ If @self is unbound, this function returns %NULL. c:identifier="gtk_list_header_get_n_items" glib:get-property="n-items" version="4.12"> - Gets the the number of items in the section. + line="357">Gets the the number of items in the section. If @self is unbound, 0 is returned. The number of items in the section + line="365">The number of items in the section a `GtkListHeader` + line="359">a `GtkListHeader` @@ -88590,10 +90581,9 @@ If @self is unbound, 0 is returned. c:identifier="gtk_list_header_get_start" glib:get-property="start" version="4.12"> - Gets the start position in the model of the section that @self is + line="309">Gets the start position in the model of the section that @self is currently the header for. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. @@ -88601,14 +90591,14 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The start position of the section + line="318">The start position of the section a `GtkListHeader` + line="311">a `GtkListHeader` @@ -88617,10 +90607,9 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. c:identifier="gtk_list_header_set_child" glib:set-property="child" version="4.12"> - Sets the child to be used for this listitem. + line="272">Sets the child to be used for this listitem. This function is typically called by applications when setting up a header so that the widget can be reused when @@ -88633,7 +90622,7 @@ binding it multiple times. a `GtkListHeader` + line="274">a `GtkListHeader` allow-none="1"> The list item's child or %NULL to unset + line="275">The list item's child or %NULL to unset @@ -88653,13 +90642,9 @@ binding it multiple times. transfer-ownership="none" setter="set_child" getter="get_child"> - - Widget used for display. + line="135">Widget used for display. transfer-ownership="none" getter="get_end" default-value="4294967295"> - The first position no longer part of this section. + line="147">The first position no longer part of this section. - The item at the start of the section. + line="159">The item at the start of the section. transfer-ownership="none" getter="get_n_items" default-value="0"> - Number of items in this section. + line="171">Number of items in this section. transfer-ownership="none" getter="get_start" default-value="4294967295"> - First position of items in this section. + line="183">First position of items in this section. @@ -88726,8 +90703,7 @@ binding it multiple times. glib:type-struct="ListItemClass"> `GtkListItem` is used by list widgets to represent items in a -[iface@Gio.ListModel]. + line="27">Used by list widgets to represent items in a [iface@Gio.ListModel]. `GtkListItem` objects are managed by the list widget (with its factory) and cannot be created by applications, but they need to be populated @@ -88748,19 +90724,19 @@ by application code. This is done by calling [method@Gtk.ListItem.set_child]. version="4.12"> Gets the accessible description of @self. + line="639">Gets the accessible description of @self. the accessible description + line="645">the accessible description a `GtkListItem` + line="641">a `GtkListItem` @@ -88771,19 +90747,19 @@ by application code. This is done by calling [method@Gtk.ListItem.set_child]. version="4.12"> Gets the accessible label of @self. + line="684">Gets the accessible label of @self. the accessible label + line="690">the accessible label a `GtkListItem` + line="686">a `GtkListItem` @@ -88791,23 +90767,22 @@ by application code. This is done by calling [method@Gtk.ListItem.set_child]. - Checks if a list item has been set to be activatable via + line="508">Checks if a list item has been set to be activatable via gtk_list_item_set_activatable(). %TRUE if the item is activatable + line="515">%TRUE if the item is activatable a `GtkListItem` + line="510">a `GtkListItem` @@ -88815,23 +90790,22 @@ gtk_list_item_set_activatable(). - Gets the child previously set via gtk_list_item_set_child() or + line="340">Gets the child previously set via gtk_list_item_set_child() or %NULL if none was set. The child + line="347">The child a `GtkListItem` + line="342">a `GtkListItem` @@ -88840,23 +90814,22 @@ gtk_list_item_set_activatable(). c:identifier="gtk_list_item_get_focusable" glib:get-property="focusable" version="4.12"> - Checks if a list item has been set to be focusable via + line="557">Checks if a list item has been set to be focusable via gtk_list_item_set_focusable(). %TRUE if the item is focusable + line="564">%TRUE if the item is focusable a `GtkListItem` + line="559">a `GtkListItem` @@ -88864,24 +90837,23 @@ gtk_list_item_set_focusable(). - Gets the model item that associated with @self. + line="317">Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed + line="325">The item displayed a `GtkListItem` + line="319">a `GtkListItem` @@ -88889,24 +90861,23 @@ If @self is unbound, this function returns %NULL. - Gets the position in the model that @self currently displays. + line="407">Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this item + line="415">The position of this item a `GtkListItem` + line="409">a `GtkListItem` @@ -88914,10 +90885,9 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. - Checks if a list item has been set to be selectable via + line="454">Checks if a list item has been set to be selectable via gtk_list_item_set_selectable(). Do not confuse this function with [method@Gtk.ListItem.get_selected]. @@ -88925,14 +90895,14 @@ Do not confuse this function with [method@Gtk.ListItem.get_selected]. %TRUE if the item is selectable + line="463">%TRUE if the item is selectable a `GtkListItem` + line="456">a `GtkListItem` @@ -88940,25 +90910,24 @@ Do not confuse this function with [method@Gtk.ListItem.get_selected]. - Checks if the item is displayed as selected. + line="430">Checks if the item is displayed as selected. -The selected state is maintained by the liste widget and its model +The selected state is maintained by the list widget and its model and cannot be set otherwise. %TRUE if the item is selected. + line="439">%TRUE if the item is selected. a `GtkListItem` + line="432">a `GtkListItem` @@ -88969,7 +90938,7 @@ and cannot be set otherwise. version="4.12"> Sets the accessible description for the list item, + line="612">Sets the accessible description for the list item, which may be used by e.g. screen readers. @@ -88979,13 +90948,13 @@ which may be used by e.g. screen readers. a `GtkListItem` + line="614">a `GtkListItem` the description + line="615">the description @@ -88996,7 +90965,7 @@ which may be used by e.g. screen readers. version="4.12"> Sets the accessible label for the list item, + line="657">Sets the accessible label for the list item, which may be used by e.g. screen readers. @@ -89006,13 +90975,13 @@ which may be used by e.g. screen readers. a `GtkListItem` + line="659">a `GtkListItem` the label + line="660">the label @@ -89020,10 +90989,9 @@ which may be used by e.g. screen readers. - Sets @self to be activatable. + line="525">Sets @self to be activatable. If an item is activatable, double-clicking on the item, using the Return key or calling gtk_widget_activate() will activate @@ -89040,13 +91008,13 @@ By default, list items are activatable. a `GtkListItem` + line="527">a `GtkListItem` if the item should be activatable + line="528">if the item should be activatable @@ -89054,10 +91022,9 @@ By default, list items are activatable. - Sets the child to be used for this listitem. + line="360">Sets the child to be used for this listitem. This function is typically called by applications when setting up a listitem so that the widget can be reused when @@ -89070,7 +91037,7 @@ binding it multiple times. a `GtkListItem` + line="362">a `GtkListItem` allow-none="1"> The list item's child or %NULL to unset + line="363">The list item's child or %NULL to unset @@ -89088,10 +91055,9 @@ binding it multiple times. c:identifier="gtk_list_item_set_focusable" glib:set-property="focusable" version="4.12"> - Sets @self to be focusable. + line="576">Sets @self to be focusable. If an item is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. @@ -89108,13 +91074,13 @@ By default, list items are focusable. a `GtkListItem` + line="578">a `GtkListItem` if the item should be focusable + line="579">if the item should be focusable @@ -89122,10 +91088,9 @@ By default, list items are focusable. - Sets @self to be selectable. + line="473">Sets @self to be selectable. If an item is selectable, clicking on the item or using the keyboard will try to select or unselect the item. If this succeeds is up to @@ -89145,13 +91110,13 @@ a new item, they will also be reset to be selectable by GTK. a `GtkListItem` + line="475">a `GtkListItem` if the item should be selectable + line="476">if the item should be selectable @@ -89163,13 +91128,9 @@ a new item, they will also be reset to be selectable by GTK. setter="set_accessible_description" getter="get_accessible_description" default-value="NULL"> - - The accessible description to set on the list item. + line="188">The accessible description to set on the list item. setter="set_accessible_label" getter="get_accessible_label" default-value="NULL"> - - The accessible label to set on the list item. + line="200">The accessible label to set on the list item. setter="set_activatable" getter="get_activatable" default-value="TRUE"> - - If the item can be activated by the user. + line="212">If the item can be activated by the user. transfer-ownership="none" setter="set_child" getter="get_child"> - - Widget used for display. + line="222">Widget used for display. setter="set_focusable" getter="get_focusable" default-value="TRUE"> - - If the item can be focused with the keyboard. + line="232">If the item can be focused with the keyboard. - Displayed item. + line="244">Displayed item. - Position of the item. + line="254">Position of the item. setter="set_selectable" getter="get_selectable" default-value="TRUE"> - - If the item can be selected by the user. + line="264">If the item can be selected by the user. - If the item is currently selected. + line="274">If the item is currently selected. @@ -89294,7 +91230,7 @@ a new item, they will also be reset to be selectable by GTK. glib:type-struct="ListItemFactoryClass"> A `GtkListItemFactory` creates widgets for the items taken from a `GListModel`. + line="26">Creates widgets for the items taken from a `GListModel`. This is one of the core concepts of handling list widgets such as [class@Gtk.ListView] or [class@Gtk.GridView]. @@ -89358,7 +91294,7 @@ views is allowed, but very uncommon. c:type="GtkListScrollFlags"> List of actions to perform when scrolling to items in + line="315">List of actions to perform when scrolling to items in a list widget. glib:name="GTK_LIST_SCROLL_NONE"> Don't do anything extra + line="317">Don't do anything extra glib:name="GTK_LIST_SCROLL_FOCUS"> Focus the target item + line="318">Focus the target item glib:name="GTK_LIST_SCROLL_SELECT"> Select the target item and + line="319">Select the target item and unselect all other items. @@ -90440,7 +92376,7 @@ unsorted stores. c:type="GtkListTabBehavior"> Used to configure the focus behavior in the `GTK_DIR_TAB_FORWARD` + line="290">Used to configure the focus behavior in the `GTK_DIR_TAB_FORWARD` and `GTK_DIR_TAB_BACKWARD` direction, like the <kbd>Tab</kbd> key in a [class@Gtk.ListView]. glib:name="GTK_LIST_TAB_ALL"> Cycle through all focusable items of the list + line="292">Cycle through all focusable items of the list glib:name="GTK_LIST_TAB_ITEM"> Cycle through a single list element, then move + line="293">Cycle through a single list element, then move focus out of the list. Moving focus between items needs to be done with the arrow keys. @@ -90470,7 +92406,7 @@ in a [class@Gtk.ListView]. glib:name="GTK_LIST_TAB_CELL"> Cycle only through a single cell, then + line="296">Cycle only through a single cell, then move focus out of the list. Moving focus between cells needs to be done with the arrow keys. This is only relevant for cell-based widgets like #GtkColumnView, otherwise it behaves @@ -90486,7 +92422,7 @@ in a [class@Gtk.ListView]. glib:type-struct="ListViewClass"> `GtkListView` presents a large dynamic list of items. + line="42">Presents a large dynamic list of items. `GtkListView` uses its factory to generate one row widget for each visible item and shows them in a linear display, either vertically or horizontally. @@ -90556,6 +92492,13 @@ activate_cb (GtkListView *list, gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list); ``` +# Actions + +`GtkListView` defines a set of built-in actions: + +- `list.activate-item` activates the item at given position by emitting + the [signal@Gtk.ListView::activate] signal. + # CSS nodes ``` @@ -90581,8 +92524,8 @@ the style of [list presentation](ListContainers.html#list-styles): # Accessibility -`GtkListView` uses the %GTK_ACCESSIBLE_ROLE_LIST role, and the list -items use the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role. +`GtkListView` uses the [enum@Gtk.AccessibleRole.list] role, and the list +items use the [enum@Gtk.AccessibleRole.list_item] role. @@ -90592,7 +92535,7 @@ items use the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role. Creates a new `GtkListView` that uses the given @factory for + line="1011">Creates a new `GtkListView` that uses the given @factory for mapping items to widgets. The function takes ownership of the @@ -90605,7 +92548,7 @@ list_view = gtk_list_view_new (create_model (), a new `GtkListView` using the given @model and @factory + line="1026">a new `GtkListView` using the given @model and @factory @@ -90615,7 +92558,7 @@ list_view = gtk_list_view_new (create_model (), allow-none="1"> the model to use + line="1013">the model to use The factory to populate items with + line="1014">The factory to populate items with @@ -90632,23 +92575,21 @@ list_view = gtk_list_view_new (create_model (), - Returns whether rows can be selected by dragging with the mouse. + line="1306">Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled + line="1312">%TRUE if rubberband selection is enabled a `GtkListView` + line="1308">a `GtkListView` @@ -90656,22 +92597,21 @@ list_view = gtk_list_view_new (create_model (), - Gets the factory that's currently used to populate list items. + line="1091">Gets the factory that's currently used to populate list items. The factory in use + line="1097">The factory in use a `GtkListView` + line="1093">a `GtkListView` @@ -90680,22 +92620,21 @@ list_view = gtk_list_view_new (create_model (), c:identifier="gtk_list_view_get_header_factory" glib:get-property="header-factory" version="4.12"> - Gets the factory that's currently used to populate section headers. + line="1129">Gets the factory that's currently used to populate section headers. The factory in use + line="1135">The factory in use a `GtkListView` + line="1131">a `GtkListView` @@ -90703,22 +92642,21 @@ list_view = gtk_list_view_new (create_model (), - Gets the model that's currently used to read the items displayed. + line="1049">Gets the model that's currently used to read the items displayed. The model in use + line="1055">The model in use a `GtkListView` + line="1051">a `GtkListView` @@ -90726,23 +92664,22 @@ list_view = gtk_list_view_new (create_model (), - Returns whether the list box should show separators + line="1219">Returns whether the list box should show separators between rows. %TRUE if the list box shows separators + line="1226">%TRUE if the list box shows separators a `GtkListView` + line="1221">a `GtkListView` @@ -90750,24 +92687,22 @@ between rows. - Returns whether rows will be activated on single click and + line="1268">Returns whether rows will be activated on single click and selected on hover. %TRUE if rows are activated on single click + line="1275">%TRUE if rows are activated on single click a `GtkListView` + line="1270">a `GtkListView` @@ -90776,22 +92711,21 @@ selected on hover. c:identifier="gtk_list_view_get_tab_behavior" glib:get-property="tab-behavior" version="4.12"> - Gets the behavior set for the <kbd>Tab</kbd> key. + line="1345">Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key + line="1351">The behavior of the <kbd>Tab</kbd> key a `GtkListView` + line="1347">a `GtkListView` @@ -90801,7 +92735,7 @@ selected on hover. version="4.12"> Scrolls to the item at the given position and performs the actions + line="1363">Scrolls to the item at the given position and performs the actions specified in @flags. This function works no matter if the listview is shown or focused. @@ -90814,19 +92748,20 @@ If it isn't, then the changes will take effect once that happens. The listview to scroll in + line="1365">The listview to scroll in position of the item + line="1366">position of the item. Must be less than the number of + items in the view. actions to perform + line="1368">actions to perform allow-none="1"> details of how to perform + line="1369">details of how to perform the scroll operation or %NULL to scroll into view @@ -90844,11 +92779,9 @@ If it isn't, then the changes will take effect once that happens. - Sets whether selections can be changed by dragging with the mouse. + line="1285">Sets whether selections can be changed by dragging with the mouse. @@ -90857,13 +92790,13 @@ If it isn't, then the changes will take effect once that happens. a `GtkListView` + line="1287">a `GtkListView` %TRUE to enable rubberband selection + line="1288">%TRUE to enable rubberband selection @@ -90871,10 +92804,9 @@ If it isn't, then the changes will take effect once that happens. - Sets the `GtkListItemFactory` to use for populating list items. + line="1107">Sets the `GtkListItemFactory` to use for populating list items. @@ -90883,7 +92815,7 @@ If it isn't, then the changes will take effect once that happens. a `GtkListView` + line="1109">a `GtkListView` allow-none="1"> the factory to use + line="1110">the factory to use @@ -90901,10 +92833,9 @@ If it isn't, then the changes will take effect once that happens. c:identifier="gtk_list_view_set_header_factory" glib:set-property="header-factory" version="4.12"> - Sets the `GtkListItemFactory` to use for populating the + line="1147">Sets the `GtkListItemFactory` to use for populating the [class@Gtk.ListHeader] objects used in section headers. If this factory is set to %NULL, the list will not show section headers. @@ -90916,7 +92847,7 @@ If this factory is set to %NULL, the list will not show section headers. a `GtkListView` + line="1149">a `GtkListView` allow-none="1"> the factory to use + line="1150">the factory to use @@ -90933,10 +92864,9 @@ If this factory is set to %NULL, the list will not show section headers. - Sets the model to use. + line="1065">Sets the model to use. This must be a [iface@Gtk.SelectionModel] to use. @@ -90947,7 +92877,7 @@ This must be a [iface@Gtk.SelectionModel] to use. a `GtkListView` + line="1067">a `GtkListView` allow-none="1"> the model to use + line="1068">the model to use @@ -90964,10 +92894,9 @@ This must be a [iface@Gtk.SelectionModel] to use. - Sets whether the list box should show separators + line="1192">Sets whether the list box should show separators between rows. @@ -90977,13 +92906,13 @@ between rows. a `GtkListView` + line="1194">a `GtkListView` %TRUE to show separators + line="1195">%TRUE to show separators @@ -90991,11 +92920,9 @@ between rows. - Sets whether rows should be activated on single click and + line="1236">Sets whether rows should be activated on single click and selected on hover. @@ -91005,13 +92932,13 @@ selected on hover. a `GtkListView` + line="1238">a `GtkListView` %TRUE to activate items on single click + line="1239">%TRUE to activate items on single click @@ -91020,10 +92947,9 @@ selected on hover. c:identifier="gtk_list_view_set_tab_behavior" glib:set-property="tab-behavior" version="4.12"> - Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + line="1322">Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. @@ -91032,13 +92958,13 @@ selected on hover. a `GtkListView` + line="1324">a `GtkListView` The desired tab behavior + line="1325">The desired tab behavior @@ -91049,13 +92975,9 @@ selected on hover. setter="set_enable_rubberband" getter="get_enable_rubberband" default-value="FALSE"> - - Allow rubberband selection. + line="877">Allow rubberband selection. transfer-ownership="none" setter="set_factory" getter="get_factory"> - - Factory for populating list items. + line="887">Factory for populating list items. + +The factory must be for configuring [class@Gtk.ListItem] objects. transfer-ownership="none" setter="set_header_factory" getter="get_header_factory"> - - Factory for creating header widgets. + line="899">Factory for creating header widgets. + +The factory must be for configuring [class@Gtk.ListHeader] objects. transfer-ownership="none" setter="set_model" getter="get_model"> - - Model for the items displayed. + line="913">Model for the items displayed. setter="set_show_separators" getter="get_show_separators" default-value="FALSE"> - - Show separators between rows. + line="923">Show separators between rows. setter="set_single_click_activate" getter="get_single_click_activate" default-value="FALSE"> - - Activate rows on single click and select them on hover. + line="933">Activate rows on single click and select them on hover. setter="set_tab_behavior" getter="get_tab_behavior" default-value="GTK_LIST_TAB_ALL"> - - Behavior of the <kbd>Tab</kbd> key + line="943">Behavior of the <kbd>Tab</kbd> key Emitted when a row has been activated by the user, + line="958">Emitted when a row has been activated by the user, usually via activating the GtkListView|list.activate-item action. This allows for a convenient way to handle activation in a listview. @@ -91163,7 +93065,7 @@ this signal. position of item to activate + line="961">position of item to activate @@ -91189,7 +93091,10 @@ this signal. line="33">`GtkLockButton` is a widget to obtain and revoke authorizations needed to operate the controls. -![An example GtkLockButton](lock-button.png) +<picture> + <source srcset="lockbutton-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkLockButton" src="lockbutton.png"> +</picture> It is typically used in preference dialogs or control panels. @@ -91201,19 +93106,28 @@ other authorization framework. To obtain a PolicyKit-based If the user is not currently allowed to perform the action, but can obtain the permission, the widget looks like this: -![](lockbutton-locked.png) +<picture> + <source srcset="lockbutton-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An locked GtkLockButton" src="lockbutton.png"> +</picture> and the user can click the button to request the permission. Depending on the platform, this may pop up an authentication dialog or ask the user to authenticate in some other way. Once the user has obtained the permission, the widget changes to this: -![](lockbutton-unlocked.png) +<picture> + <source srcset="lockbutton-unlocked-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An unlocked GtkLockButton" src="lockbutton-unlocked.png"> +</picture> and the permission can be dropped again by clicking the button. If the user is not able to obtain the permission at all, the widget looks like this: -![](lockbutton-sorry.png) +<picture> + <source srcset="lockbutton-sorry-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An unobtainable GtkLockButton" src="lockbutton-sorry.png"> +</picture> If the user has the permission and cannot drop it, the button is hidden. @@ -91234,13 +93148,13 @@ with the [property@Gtk.LockButton:text-lock], deprecated-version="4.10"> Creates a new lock button which reflects the @permission. + line="533">Creates a new lock button which reflects the @permission. This widget will be removed in GTK 5 a new `GtkLockButton` + line="539">a new `GtkLockButton` @@ -91250,7 +93164,7 @@ with the [property@Gtk.LockButton:text-lock], allow-none="1"> a `GPermission` + line="535">a `GPermission` @@ -91260,23 +93174,22 @@ with the [property@Gtk.LockButton:text-lock], glib:get-property="permission" deprecated="1" deprecated-version="4.10"> - Obtains the `GPermission` object that controls @button. + line="551">Obtains the `GPermission` object that controls @button. This widget will be removed in GTK 5 the `GPermission` of @button + line="557">the `GPermission` of @button a `GtkLockButton` + line="553">a `GtkLockButton` @@ -91286,10 +93199,9 @@ with the [property@Gtk.LockButton:text-lock], glib:set-property="permission" deprecated="1" deprecated-version="4.10"> - Sets the `GPermission` object that controls @button. + line="569">Sets the `GPermission` object that controls @button. This widget will be removed in GTK 5 @@ -91299,7 +93211,7 @@ with the [property@Gtk.LockButton:text-lock], a `GtkLockButton` + line="571">a `GtkLockButton` a `GPermission` object + line="572">a `GPermission` object @@ -91320,13 +93232,9 @@ with the [property@Gtk.LockButton:text-lock], transfer-ownership="none" setter="set_permission" getter="get_permission"> - - The `GPermission object controlling this button. + line="284">The `GPermission object controlling this button. This widget will be removed in GTK 5 @@ -91339,7 +93247,7 @@ with the [property@Gtk.LockButton:text-lock], default-value="Lock"> The text to display when prompting the user to lock. + line="297">The text to display when prompting the user to lock. This widget will be removed in GTK 5 @@ -91352,7 +93260,7 @@ with the [property@Gtk.LockButton:text-lock], default-value="Unlock"> The text to display when prompting the user to unlock. + line="311">The text to display when prompting the user to unlock. This widget will be removed in GTK 5 @@ -91365,7 +93273,7 @@ with the [property@Gtk.LockButton:text-lock], default-value="Dialog is unlocked.\nClick to prevent further changes"> The tooltip to display when prompting the user to lock. + line="325">The tooltip to display when prompting the user to lock. This widget will be removed in GTK 5 @@ -91378,7 +93286,7 @@ with the [property@Gtk.LockButton:text-lock], default-value="System policy prevents changes.\nContact your system administrator"> The tooltip to display when the user cannot obtain authorization. + line="353">The tooltip to display when the user cannot obtain authorization. This widget will be removed in GTK 5 @@ -91391,7 +93299,7 @@ with the [property@Gtk.LockButton:text-lock], default-value="Dialog is locked.\nClick to make changes"> The tooltip to display when prompting the user to unlock. + line="339">The tooltip to display when prompting the user to unlock. This widget will be removed in GTK 5 @@ -91406,13 +93314,21 @@ against at application run time. - + Evaluates to the maximum length of a compose sequence. + +This macro is longer used by GTK. + - + The default extension point name for media file. + - + Like [func@get_minor_version], but from the headers used at @@ -91487,7 +93403,7 @@ against at application run time. glib:type-struct="MapListModelClass"> A `GtkMapListModel` maps the items in a list model to different items. + line="28">A list model that maps the items in another model to different items. `GtkMapListModel` uses a [callback@Gtk.MapListModelMapFunc]. @@ -91574,7 +93490,6 @@ they are no longer needed and recreate them if necessary. - Gets the model that is currently being mapped or %NULL if none. @@ -91597,7 +93512,6 @@ they are no longer needed and recreate them if necessary. - Checks if a map function is currently set on @self. @@ -91675,7 +93589,6 @@ function returns items of the appropriate type. - Sets the model to be mapped. @@ -91709,8 +93622,6 @@ they are doing and have set up an appropriate map function. transfer-ownership="none" getter="has_map" default-value="FALSE"> - If a map is set for this model @@ -91727,10 +93638,6 @@ they are doing and have set up an appropriate map function. construct-only="1" transfer-ownership="none" getter="get_model"> - - The model being mapped. @@ -91797,9 +93704,12 @@ used with. glib:type-struct="MediaControlsClass"> `GtkMediaControls` is a widget to show controls for a video. + line="31">Shows controls for video playback. -![An example GtkMediaControls](media-controls.png) +<picture> + <source srcset="media-controls-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkMediaControls" src="media-controls.png"> +</picture> Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. @@ -91809,12 +93719,12 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. Creates a new `GtkMediaControls` managing the @stream passed to it. + line="309">Creates a new `GtkMediaControls` managing the @stream passed to it. a new `GtkMediaControls` + line="315">a new `GtkMediaControls` @@ -91824,7 +93734,7 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. allow-none="1"> a `GtkMediaStream` to manage + line="311">a `GtkMediaStream` to manage @@ -91832,22 +93742,21 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. - Gets the media stream managed by @controls or %NULL if none. + line="325">Gets the media stream managed by @controls or %NULL if none. The media stream managed by @controls + line="331">The media stream managed by @controls a `GtkMediaControls` + line="327">a `GtkMediaControls` @@ -91855,10 +93764,9 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. - Sets the stream that is controlled by @controls. + line="490">Sets the stream that is controlled by @controls. @@ -91867,7 +93775,7 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. a `GtkMediaControls` widget + line="492">a `GtkMediaControls` widget allow-none="1"> a `GtkMediaStream` + line="493">a `GtkMediaStream` @@ -91886,13 +93794,9 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. transfer-ownership="none" setter="set_media_stream" getter="get_media_stream"> - - The media-stream managed by this object or %NULL if none. + line="273">The media-stream managed by this object or %NULL if none. @@ -91914,21 +93818,21 @@ Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. glib:type-struct="MediaFileClass"> `GtkMediaFile` implements `GtkMediaStream` for files. + line="30">Implements the `GtkMediaStream` interface for files. This provides a simple way to play back video files with GTK. GTK provides a GIO extension point for `GtkMediaFile` implementations to allow for external implementations using various media frameworks. -GTK itself includes implementations using GStreamer and ffmpeg. - +GTK itself includes an implementation using GStreamer. + Creates a new empty media file. - + Creates a new media file to play @file. - + This is a utility function that converts the given @filename to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. - + If you want the resulting media to be seekable, the stream should implement the `GSeekable` interface. - + This is a utility function that converts the given @resource to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. - + - + @@ -92041,7 +93945,7 @@ to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. - + @@ -92055,7 +93959,7 @@ to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. Resets the media file to be empty. - + @@ -92071,14 +93975,13 @@ to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. - Returns the file that @self is currently playing from. When @self is not playing or not playing from a file, %NULL is returned. - + - Returns the stream that @self is currently playing from. When @self is not playing or not playing from a stream, %NULL is returned. - + - Sets the `GtkMediaFile` to play the given file. If any file is still playing, stop playing it. - + @@ -92154,11 +94055,11 @@ If any file is still playing, stop playing it. Sets the `GtkMediaFile to play the given file. + line="418">Sets the `GtkMediaFile` to play the given file. This is a utility function that converts the given @filename to a `GFile` and calls [method@Gtk.MediaFile.set_file]. - + @@ -92183,7 +94084,6 @@ to a `GFile` and calls [method@Gtk.MediaFile.set_file]. - Sets the `GtkMediaFile` to play the given stream. @@ -92192,7 +94092,7 @@ If anything is still playing, stop playing it. Full control about the @stream is assumed for the duration of playback. The stream will not be closed. - + @@ -92217,11 +94117,11 @@ playback. The stream will not be closed. Sets the `GtkMediaFile to play the given resource. + line="447">Sets the `GtkMediaFile` to play the given resource. This is a utility function that converts the given @resource_path to a `GFile` and calls [method@Gtk.MediaFile.set_file]. - + @@ -92248,10 +94148,6 @@ to a `GFile` and calls [method@Gtk.MediaFile.set_file]. transfer-ownership="none" setter="set_file" getter="get_file"> - - The file being played back or %NULL if not playing a file. @@ -92262,10 +94158,6 @@ to a `GFile` and calls [method@Gtk.MediaFile.set_file]. transfer-ownership="none" setter="set_input_stream" getter="get_input_stream"> - - The stream being played back or %NULL if not playing a stream. @@ -92280,13 +94172,13 @@ This is %NULL when playing a file. - + - + @@ -92299,7 +94191,7 @@ This is %NULL when playing a file. - + @@ -92312,7 +94204,7 @@ This is %NULL when playing a file. - + @@ -92320,7 +94212,7 @@ This is %NULL when playing a file. - + @@ -92328,7 +94220,7 @@ This is %NULL when playing a file. - + @@ -92336,7 +94228,7 @@ This is %NULL when playing a file. - + @@ -92353,7 +94245,7 @@ This is %NULL when playing a file. glib:type-struct="MediaStreamClass"> `GtkMediaStream` is the integration point for media playback inside GTK. + line="25">The integration point for media playback inside GTK. GTK provides an implementation of the `GtkMediaStream` interface that is called [class@Gtk.MediaFile]. @@ -92673,7 +94565,6 @@ To unset an error, the stream must be reset via a call to - Gets the duration of the stream. @@ -92698,7 +94589,6 @@ If the duration is not known, 0 will be returned. - Returns whether the streams playback is finished. @@ -92721,7 +94611,6 @@ If the duration is not known, 0 will be returned. - If the stream is in an error state, returns the `GError` @@ -92758,7 +94647,6 @@ set, e.g. with [method@Gtk.MediaFile.set_file]. - Returns whether the stream is set to loop. @@ -92783,7 +94671,6 @@ See [method@Gtk.MediaStream.set_loop] for details. - Returns whether the audio for the stream is muted. @@ -92808,7 +94695,6 @@ See [method@Gtk.MediaStream.set_muted] for details. - Return whether the stream is currently playing. @@ -92831,7 +94717,6 @@ See [method@Gtk.MediaStream.set_muted] for details. - Returns the current presentation timestamp in microseconds. @@ -92854,7 +94739,6 @@ See [method@Gtk.MediaStream.set_muted] for details. - Returns the volume of the audio for the stream. @@ -92879,7 +94763,6 @@ See [method@Gtk.MediaStream.set_volume] for details. - Returns whether the stream has audio. @@ -92902,7 +94785,6 @@ See [method@Gtk.MediaStream.set_volume] for details. - Returns whether the stream has video. @@ -92922,8 +94804,9 @@ See [method@Gtk.MediaStream.set_volume] for details. - - + Returns whether the stream has finished initializing. @@ -92945,8 +94828,9 @@ At this point the existence of audio and video is known. - - + Checks if a stream may be seekable. @@ -92974,8 +94858,9 @@ stream, though it will not do anything. - - + Checks if there is currently a seek operation going on. @@ -93199,7 +95084,6 @@ ending a seek. - Sets whether the stream should loop. @@ -93232,7 +95116,6 @@ loop setting and just end. - Sets whether the audio stream should be muted. @@ -93265,7 +95148,6 @@ still work but it will not have an audible effect. - Starts or pauses playback of the stream. @@ -93291,7 +95173,6 @@ still work but it will not have an audible effect. - Sets the volume of the audio stream. @@ -93504,8 +95385,6 @@ The media stream must be prepared when this function is called. transfer-ownership="none" getter="get_duration" default-value="0"> - The stream's duration in microseconds or 0 if unknown. @@ -93515,16 +95394,12 @@ The media stream must be prepared when this function is called. transfer-ownership="none" getter="ended" default-value="FALSE"> - Set when playback has finished. - %NULL for a properly working stream or the `GError` @@ -93535,8 +95410,6 @@ that the stream is in. transfer-ownership="none" getter="has_audio" default-value="FALSE"> - Whether the stream contains audio. @@ -93546,8 +95419,6 @@ that the stream is in. transfer-ownership="none" getter="has_video" default-value="FALSE"> - Whether the stream contains video. @@ -93559,10 +95430,6 @@ that the stream is in. setter="set_loop" getter="get_loop" default-value="FALSE"> - - Try to restart the media from the beginning once it ended. @@ -93574,10 +95441,6 @@ that the stream is in. setter="set_muted" getter="get_muted" default-value="FALSE"> - - Whether the audio stream should be muted. @@ -93589,10 +95452,6 @@ that the stream is in. setter="set_playing" getter="get_playing" default-value="FALSE"> - - Whether the stream is currently playing. @@ -93601,26 +95460,27 @@ that the stream is in. - Whether the stream has finished initializing and existence of audio and video is known. - - + Set unless the stream is known to not support seeking. - - + Set while a seek is in progress. @@ -93630,8 +95490,6 @@ audio and video is known. transfer-ownership="none" getter="get_timestamp" default-value="0"> - The current presentation timestamp in microseconds. @@ -93643,10 +95501,6 @@ audio and video is known. setter="set_volume" getter="get_volume" default-value="1.000000"> - - Volume of the audio stream. @@ -93850,9 +95704,12 @@ audio and video is known. glib:get-type="gtk_menu_button_get_type"> The `GtkMenuButton` widget is used to display a popup when clicked. + line="21">Displays a popup when clicked. -![An example GtkMenuButton](menu-button.png) +<picture> + <source srcset="menu-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkMenuButton" src="menu-button.png"> +</picture> This popup can be provided either as a `GtkPopover` or as an abstract `GMenuModel`. @@ -93911,14 +95768,14 @@ to request a round appearance. # Accessibility -`GtkMenuButton` uses the %GTK_ACCESSIBLE_ROLE_BUTTON role. +`GtkMenuButton` uses the [enum@Gtk.AccessibleRole.button] role. Creates a new `GtkMenuButton` widget with downwards-pointing + line="725">Creates a new `GtkMenuButton` widget with downwards-pointing arrow as the only child. You can replace the child widget with another `GtkWidget` @@ -93927,7 +95784,7 @@ should you wish to. The newly created `GtkMenuButton` + line="734">The newly created `GtkMenuButton` @@ -93935,22 +95792,21 @@ should you wish to. c:identifier="gtk_menu_button_get_active" glib:get-property="active" version="4.10"> - Returns whether the menu button is active. + line="1588">Returns whether the menu button is active. TRUE if the button is active + line="1594">TRUE if the button is active a `GtkMenuButton` + line="1590">a `GtkMenuButton` @@ -93959,17 +95815,15 @@ should you wish to. c:identifier="gtk_menu_button_get_always_show_arrow" glib:get-property="always-show-arrow" version="4.4"> - Gets whether to show a dropdown arrow even when using an icon or a custom + line="1124">Gets whether to show a dropdown arrow even when using an icon or a custom child. whether to show a dropdown arrow even when using an icon or a custom + line="1131">whether to show a dropdown arrow even when using an icon or a custom child. @@ -93977,7 +95831,7 @@ child. a `GtkMenuButton` + line="1126">a `GtkMenuButton` @@ -93988,20 +95842,20 @@ child. version="4.12"> Retrieves whether the button can be smaller than the natural + line="1643">Retrieves whether the button can be smaller than the natural size of its contents. true if the button can shrink, and false otherwise + line="1650">true if the button can shrink, and false otherwise a button + line="1645">a button @@ -94010,22 +95864,21 @@ size of its contents. c:identifier="gtk_menu_button_get_child" glib:get-property="child" version="4.6"> - Gets the child widget of @menu_button. + line="1546">Gets the child widget of @menu_button. the child widget of @menu_button + line="1552">the child widget of @menu_button a `GtkMenuButton` + line="1548">a `GtkMenuButton` @@ -94033,22 +95886,21 @@ size of its contents. - Returns the direction the popup will be pointing at when popped up. + line="903">Returns the direction the popup will be pointing at when popped up. a `GtkArrowType` value + line="909">a `GtkArrowType` value a `GtkMenuButton` + line="905">a `GtkMenuButton` @@ -94056,22 +95908,21 @@ size of its contents. - Returns whether the button has a frame. + line="1239">Returns whether the button has a frame. %TRUE if the button has a frame + line="1245">%TRUE if the button has a frame a `GtkMenuButton` + line="1241">a `GtkMenuButton` @@ -94079,22 +95930,21 @@ size of its contents. - Gets the name of the icon shown in the button. + line="1076">Gets the name of the icon shown in the button. the name of the icon shown in the button + line="1082">the name of the icon shown in the button a `GtkMenuButton` + line="1078">a `GtkMenuButton` @@ -94102,22 +95952,21 @@ size of its contents. - Gets the label shown in the button + line="1200">Gets the label shown in the button the label shown in the button + line="1206">the label shown in the button a `GtkMenuButton` + line="1202">a `GtkMenuButton` @@ -94125,22 +95974,21 @@ size of its contents. - Returns the `GMenuModel` used to generate the popup. + line="823">Returns the `GMenuModel` used to generate the popup. a `GMenuModel` + line="829">a `GMenuModel` a `GtkMenuButton` + line="825">a `GtkMenuButton` @@ -94148,10 +95996,9 @@ size of its contents. - Returns the `GtkPopover` that pops out of the button. + line="1001">Returns the `GtkPopover` that pops out of the button. If the button is not using a `GtkPopover`, this function returns %NULL. @@ -94159,14 +96006,14 @@ returns %NULL. a `GtkPopover` or %NULL + line="1010">a `GtkPopover` or %NULL a `GtkMenuButton` + line="1003">a `GtkMenuButton` @@ -94175,22 +96022,21 @@ returns %NULL. c:identifier="gtk_menu_button_get_primary" glib:get-property="primary" version="4.4"> - Returns whether the menu button acts as a primary menu. + line="1457">Returns whether the menu button acts as a primary menu. %TRUE if the button is a primary menu + line="1463">%TRUE if the button is a primary menu a `GtkMenuButton` + line="1459">a `GtkMenuButton` @@ -94198,16 +96044,15 @@ returns %NULL. - Returns whether an embedded underline in the text indicates a + line="1346">Returns whether an embedded underline in the text indicates a mnemonic. %TRUE whether an embedded underline in the text indicates + line="1353">%TRUE whether an embedded underline in the text indicates the mnemonic accelerator keys. @@ -94215,7 +96060,7 @@ mnemonic. a `GtkMenuButton` + line="1348">a `GtkMenuButton` @@ -94223,7 +96068,7 @@ mnemonic. Dismiss the menu. + line="1269">Dismiss the menu. @@ -94232,7 +96077,7 @@ mnemonic. a `GtkMenuButton` + line="1271">a `GtkMenuButton` @@ -94240,7 +96085,7 @@ mnemonic. Pop up the menu. + line="1255">Pop up the menu. @@ -94249,7 +96094,7 @@ mnemonic. a `GtkMenuButton` + line="1257">a `GtkMenuButton` @@ -94258,10 +96103,9 @@ mnemonic. c:identifier="gtk_menu_button_set_active" glib:set-property="active" version="4.10"> - Sets whether the menu button is active. + line="1564">Sets whether the menu button is active. @@ -94270,13 +96114,13 @@ mnemonic. a `GtkMenuButton` + line="1566">a `GtkMenuButton` whether the menu button is active + line="1567">whether the menu button is active @@ -94285,11 +96129,9 @@ mnemonic. c:identifier="gtk_menu_button_set_always_show_arrow" glib:set-property="always-show-arrow" version="4.4"> - Sets whether to show a dropdown arrow even when using an icon or a custom + line="1095">Sets whether to show a dropdown arrow even when using an icon or a custom child. @@ -94299,13 +96141,13 @@ child. a `GtkMenuButton` + line="1097">a `GtkMenuButton` whether to show a dropdown arrow even when using an icon + line="1098">whether to show a dropdown arrow even when using an icon or a custom child @@ -94317,7 +96159,7 @@ or a custom child version="4.12"> Sets whether the button size can be smaller than the natural size of + line="1606">Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting @can_shrink to true will ellipsize the label. @@ -94331,13 +96173,13 @@ For icon buttons, this function has no effect. a menu button + line="1608">a menu button whether the button can shrink + line="1609">whether the button can shrink @@ -94346,10 +96188,9 @@ For icon buttons, this function has no effect. c:identifier="gtk_menu_button_set_child" glib:set-property="child" version="4.6"> - Sets the child widget of @menu_button. + line="1475">Sets the child widget of @menu_button. Setting a child resets [property@Gtk.MenuButton:label] and [property@Gtk.MenuButton:icon-name]. @@ -94365,7 +96206,7 @@ will be shown next to the child. a `GtkMenuButton` + line="1477">a `GtkMenuButton` allow-none="1"> the child widget + line="1478">the child widget @@ -94383,7 +96224,7 @@ will be shown next to the child. c:identifier="gtk_menu_button_set_create_popup_func"> Sets @func to be called when a popup is about to be shown. + line="1283">Sets @func to be called when a popup is about to be shown. @func should use one of @@ -94403,7 +96244,7 @@ Using this function will not reset the menu widget attached to a `GtkMenuButton` + line="1285">a `GtkMenuButton` function to call when a popup is about to - be shown, but none has been provided via other means, or %NULL - to reset to default behavior. + line="1286">function + to call when a popup is about to be shown, but none has been provided via other means, + or %NULL to reset to default behavior @@ -94427,7 +96268,7 @@ Using this function will not reset the menu widget attached to allow-none="1"> user data to pass to @func. + line="1289">user data to pass to @func destroy notify for @user_data + line="1290">destroy notify for @user_data @@ -94445,10 +96286,9 @@ Using this function will not reset the menu widget attached to - Sets the direction in which the popup will be popped up. + line="871">Sets the direction in which the popup will be popped up. If the button is automatically populated with an arrow icon, its direction will be changed to match. @@ -94466,13 +96306,13 @@ as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). a `GtkMenuButton` + line="873">a `GtkMenuButton` a `GtkArrowType` + line="874">a `GtkArrowType` @@ -94480,10 +96320,9 @@ as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). - Sets the style of the button. + line="1219">Sets the style of the button. @@ -94492,13 +96331,13 @@ as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). a `GtkMenuButton` + line="1221">a `GtkMenuButton` whether the button should have a visible frame + line="1222">whether the button should have a visible frame @@ -94506,10 +96345,9 @@ as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). - Sets the name of an icon to show inside the menu button. + line="1020">Sets the name of an icon to show inside the menu button. Setting icon name resets [property@Gtk.MenuButton:label] and [property@Gtk.MenuButton:child]. @@ -94525,13 +96363,13 @@ will be shown next to the icon. a `GtkMenuButton` + line="1022">a `GtkMenuButton` the icon name + line="1023">the icon name @@ -94539,10 +96377,9 @@ will be shown next to the icon. - Sets the label to show inside the menu button. + line="1144">Sets the label to show inside the menu button. Setting a label resets [property@Gtk.MenuButton:icon-name] and [property@Gtk.MenuButton:child]. @@ -94557,13 +96394,13 @@ arrow will be shown next to the label. a `GtkMenuButton` + line="1146">a `GtkMenuButton` the label + line="1147">the label @@ -94571,10 +96408,9 @@ arrow will be shown next to the label. - Sets the `GMenuModel` from which the popup will be constructed. + line="771">Sets the `GMenuModel` from which the popup will be constructed. If @menu_model is %NULL, the button is disabled. @@ -94592,7 +96428,7 @@ dissociated from the @menu_button, and the property is set to %NULL. a `GtkMenuButton` + line="773">a `GtkMenuButton` allow-none="1"> a `GMenuModel`, or %NULL to unset and disable the + line="774">a `GMenuModel`, or %NULL to unset and disable the button @@ -94610,10 +96446,9 @@ dissociated from the @menu_button, and the property is set to %NULL. - Sets the `GtkPopover` that will be popped up when the @menu_button is clicked. + line="945">Sets the `GtkPopover` that will be popped up when the @menu_button is clicked. If @popover is %NULL, the button is disabled. @@ -94627,7 +96462,7 @@ from the @menu_button, and the property is set to %NULL. a `GtkMenuButton` + line="947">a `GtkMenuButton` allow-none="1"> a `GtkPopover`, or %NULL to unset and disable the button + line="948">a `GtkPopover`, or %NULL to unset and disable the button @@ -94645,10 +96480,9 @@ from the @menu_button, and the property is set to %NULL. c:identifier="gtk_menu_button_set_primary" glib:set-property="primary" version="4.4"> - Sets whether menu button acts as a primary menu. + line="1421">Sets whether menu button acts as a primary menu. Primary menus can be opened with the <kbd>F10</kbd> key. @@ -94659,13 +96493,13 @@ Primary menus can be opened with the <kbd>F10</kbd> key. a `GtkMenuButton` + line="1423">a `GtkMenuButton` whether the menubutton should act as a primary menu + line="1424">whether the menubutton should act as a primary menu @@ -94673,10 +96507,9 @@ Primary menus can be opened with the <kbd>F10</kbd> key. - If true, an underline in the text indicates a mnemonic. + line="1323">If true, an underline in the text indicates a mnemonic. @@ -94685,13 +96518,13 @@ Primary menus can be opened with the <kbd>F10</kbd> key. a `GtkMenuButton` + line="1325">a `GtkMenuButton` %TRUE if underlines in the text indicate mnemonics + line="1326">%TRUE if underlines in the text indicate mnemonics @@ -94703,13 +96536,9 @@ Primary menus can be opened with the <kbd>F10</kbd> key. setter="set_active" getter="get_active" default-value="FALSE"> - - Whether the menu button is active. + line="539">Whether the menu button is active. setter="set_always_show_arrow" getter="get_always_show_arrow" default-value="FALSE"> - - Whether to show a dropdown arrow even when using an icon or a custom child. + line="471">Whether to show a dropdown arrow even when using an icon or a custom child. setter="set_can_shrink" getter="get_can_shrink" default-value="FALSE"> - - Whether the size of the button can be made smaller than the natural + line="551">Whether the size of the button can be made smaller than the natural size of its contents. @@ -94751,13 +96572,9 @@ size of its contents. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="527">The child widget. setter="set_direction" getter="get_direction" default-value="GTK_ARROW_DOWN"> - - The `GtkArrowType` representing the direction in which the + line="439">The `GtkArrowType` representing the direction in which the menu or popover will be popped out. @@ -94782,13 +96595,9 @@ menu or popover will be popped out. setter="set_has_frame" getter="get_has_frame" default-value="TRUE"> - - Whether the button has a frame. + line="503">Whether the button has a frame. setter="set_icon_name" getter="get_icon_name" default-value="NULL"> - - The name of the icon used to automatically populate the button. + line="461">The name of the icon used to automatically populate the button. setter="set_label" getter="get_label" default-value="NULL"> - - The label for the button. + line="483">The label for the button. transfer-ownership="none" setter="set_menu_model" getter="get_menu_model"> - - The `GMenuModel` from which the popup will be created. + line="426">The `GMenuModel` from which the popup will be created. See [method@Gtk.MenuButton.set_menu_model] for the interaction with the [property@Gtk.MenuButton:popover] property. @@ -94843,13 +96640,9 @@ with the [property@Gtk.MenuButton:popover] property. transfer-ownership="none" setter="set_popover" getter="get_popover"> - - The `GtkPopover` that will be popped up when the button is clicked. + line="451">The `GtkPopover` that will be popped up when the button is clicked. setter="set_primary" getter="get_primary" default-value="FALSE"> - - Whether the menu button acts as a primary menu. + line="513">Whether the menu button acts as a primary menu. Primary menus can be opened using the <kbd>F10</kbd> key @@ -94876,19 +96665,15 @@ Primary menus can be opened using the <kbd>F10</kbd> key setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - If set an underscore in the text indicates a mnemonic. + line="493">If set an underscore in the text indicates a mnemonic. Emitted to when the menu button is activated. + line="566">Emitted to when the menu button is activated. The `::activate` signal on `GtkMenuButton` is an action signal and emitting it causes the button to pop up its menu. @@ -94943,7 +96728,10 @@ or [method@Gtk.MenuButton.set_menu_model]. filename="gtk/gtkmessagedialog.c" line="42">`GtkMessageDialog` presents a dialog with some message text. -![An example GtkMessageDialog](messagedialog.png) +<picture> + <source srcset="messagedialog-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkMessageDialog" src="messagedialog.png"> +</picture> It’s simply a convenience widget; you could construct the equivalent of `GtkMessageDialog` from `GtkDialog` without too much effort, but @@ -95012,7 +96800,7 @@ the message area as an internal child with the name “message_area”. deprecated-version="4.10"> Creates a new message dialog. + line="476">Creates a new message dialog. This is a simple dialog with some text the user may want to see. When the user clicks a button a “response” signal is emitted with @@ -95024,7 +96812,7 @@ for more details. a new `GtkMessageDialog` + line="492">a new `GtkMessageDialog` @@ -95034,25 +96822,25 @@ for more details. allow-none="1"> transient parent + line="478">transient parent flags + line="479">flags type of message + line="480">type of message set of buttons to use + line="481">set of buttons to use allow-none="1"> printf()-style format string + line="482">printf()-style format string arguments for @message_format + line="483">arguments for @message_format @@ -95079,7 +96867,7 @@ for more details. deprecated-version="4.10"> Creates a new message dialog. + line="542">Creates a new message dialog. This is a simple dialog with some text that is marked up with Pango markup. When the user clicks a button a “response” signal @@ -95113,7 +96901,7 @@ gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog), a new `GtkMessageDialog` + line="580">a new `GtkMessageDialog` @@ -95123,25 +96911,25 @@ gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog), allow-none="1"> transient parent + line="544">transient parent flags + line="545">flags type of message + line="546">type of message set of buttons to use + line="547">set of buttons to use printf()-style format string + line="548">printf()-style format string arguments for @message_format + line="549">arguments for @message_format @@ -95168,7 +96956,7 @@ gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog), deprecated-version="4.10"> Sets the secondary text of the message dialog. + line="678">Sets the secondary text of the message dialog. The @message_format is assumed to contain Pango markup. @@ -95195,19 +96983,19 @@ g_free (msg); a `GtkMessageDialog` + line="680">a `GtkMessageDialog` printf()-style string with Pango markup + line="681">printf()-style string with Pango markup arguments for @message_format + line="682">arguments for @message_format @@ -95219,7 +97007,7 @@ g_free (msg); deprecated-version="4.10"> Sets the secondary text of the message dialog. + line="635">Sets the secondary text of the message dialog. Use [class@Gtk.AlertDialog] instead @@ -95230,7 +97018,7 @@ g_free (msg); a `GtkMessageDialog` + line="637">a `GtkMessageDialog` printf()-style format string + line="638">printf()-style format string arguments for @message_format + line="639">arguments for @message_format @@ -95257,7 +97045,7 @@ g_free (msg); deprecated-version="4.10"> Returns the message area of the dialog. + line="737">Returns the message area of the dialog. This is the box where the dialog’s primary and secondary labels are packed. You can add your own extra content to that box and it @@ -95269,7 +97057,7 @@ for the corresponding function in the parent [class@Gtk.Dialog]. A `GtkBox` corresponding to the + line="748">A `GtkBox` corresponding to the “message area” in the @message_dialog @@ -95277,7 +97065,7 @@ for the corresponding function in the parent [class@Gtk.Dialog]. a `GtkMessageDialog` + line="739">a `GtkMessageDialog` @@ -95288,7 +97076,7 @@ for the corresponding function in the parent [class@Gtk.Dialog]. deprecated-version="4.10"> Sets the text of the message dialog. + line="614">Sets the text of the message dialog. Use [class@Gtk.AlertDialog] instead @@ -95299,13 +97087,13 @@ for the corresponding function in the parent [class@Gtk.Dialog]. a `GtkMessageDialog` + line="616">a `GtkMessageDialog` string with Pango markup + line="617">string with Pango markup @@ -95316,6 +97104,9 @@ for the corresponding function in the parent [class@Gtk.Dialog]. construct-only="1" transfer-ownership="none" default-value="GTK_BUTTONS_NONE"> + Set of buttons to display on the dialog. getter="get_message_area"> The `GtkBox` that corresponds to the message area of this dialog. + line="431">The `GtkBox` that corresponds to the message area of this dialog. See [method@Gtk.MessageDialog.get_message_area] for a detailed description of this area. @@ -95336,7 +97127,7 @@ description of this area. default-value="GTK_MESSAGE_INFO"> The type of the message. + line="363">The type of the message. default-value="NULL"> The secondary text of the message dialog. + line="409">The secondary text of the message dialog. default-value="FALSE"> %TRUE if the secondary text of the dialog includes Pango markup. + line="419">%TRUE if the secondary text of the dialog includes Pango markup. See [func@Pango.parse_markup]. @@ -95362,7 +97153,7 @@ See [func@Pango.parse_markup]. The primary text of the message dialog. + line="385">The primary text of the message dialog. If the dialog has a secondary text, this will appear as the title. @@ -95373,7 +97164,7 @@ If the dialog has a secondary text, this will appear as the title. default-value="FALSE"> %TRUE if the primary text of the dialog includes Pango markup. + line="397">%TRUE if the primary text of the dialog includes Pango markup. See [func@Pango.parse_markup]. @@ -95395,7 +97186,7 @@ See [func@Pango.parse_markup]. c:type="GtkMessageType"> The type of message being displayed in a [class@MessageDialog]. + line="333">The type of message being displayed in a [class@MessageDialog]. glib:name="GTK_MESSAGE_INFO"> Informational message + line="335">Informational message glib:name="GTK_MESSAGE_WARNING"> Non-fatal warning message + line="336">Non-fatal warning message glib:name="GTK_MESSAGE_QUESTION"> Question requiring a choice + line="337">Question requiring a choice glib:name="GTK_MESSAGE_ERROR"> Fatal error message + line="338">Fatal error message glib:name="GTK_MESSAGE_OTHER"> None of the above + line="339">None of the above glib:type-struct="MnemonicActionClass"> A `GtkShortcutAction` that calls gtk_widget_mnemonic_activate(). - + line="107">Activates a widget with a mnemonic. + +This means that [method@Gtk.Widget.mnemonic_activate] is called. + Gets the mnemonic action. + line="569">Gets the mnemonic action. This is an action that calls gtk_widget_mnemonic_activate() on the given widget upon activation. - + The mnemonic action + line="577">The mnemonic action @@ -95474,7 +97267,7 @@ on the given widget upon activation. disguised="1" opaque="1" glib:is-gtype-struct-for="MnemonicAction"> - + glib:type-struct="MnemonicTriggerClass"> A `GtkShortcutTrigger` that triggers when a specific mnemonic is pressed. + line="100">Triggers when a specific mnemonic is pressed. Mnemonics require a *mnemonic modifier* (typically <kbd>Alt</kbd>) to be pressed together with the mnemonic key. @@ -95517,7 +97310,6 @@ modifiers is detected. - Gets the keyval that must be pressed to succeed triggering @self. @@ -95543,8 +97335,6 @@ modifiers is detected. transfer-ownership="none" getter="get_keyval" default-value="0"> - The key value for the trigger. @@ -95567,16 +97357,16 @@ modifiers is detected. glib:type-struct="MountOperationClass"> `GtkMountOperation` is an implementation of `GMountOperation`. - -The functions and objects described here make working with GTK and -GIO more convenient. + line="60">Asks the user for passwords and other information required to +mount a volume. `GtkMountOperation` is needed when mounting volumes: It is an implementation of `GMountOperation` that can be used with GIO functions for mounting volumes such as -g_file_mount_enclosing_volume(), g_file_mount_mountable(), -g_volume_mount(), g_mount_unmount_with_operation() and others. +[method@Gio.File.mount_enclosing_volume], +[method@Gio.File.mount_mountable], +[method@Gio.Volume.mount], +[method@Gio.Mount.unmount_with_operation] and others. When necessary, `GtkMountOperation` shows dialogs to let the user enter passwords, ask questions or show processes blocking unmount. @@ -95607,7 +97397,6 @@ enter passwords, ask questions or show processes blocking unmount. - Gets the display on which windows of the `GtkMountOperation` @@ -95631,7 +97420,6 @@ will be shown. - Gets the transient parent used by the `GtkMountOperation`. @@ -95654,7 +97442,6 @@ will be shown. - Returns whether the `GtkMountOperation` is currently displaying @@ -95678,7 +97465,6 @@ a window. - Sets the display to show windows of the `GtkMountOperation` on. @@ -95704,7 +97490,6 @@ a window. - Sets the transient parent for windows shown by the @@ -95736,10 +97521,6 @@ a window. transfer-ownership="none" setter="set_display" getter="get_display"> - - The display where dialogs will be shown. @@ -95749,8 +97530,6 @@ a window. transfer-ownership="none" getter="is_showing" default-value="FALSE"> - Whether a dialog is currently shown. @@ -95761,10 +97540,6 @@ a window. transfer-ownership="none" setter="set_parent" getter="get_parent"> - - The parent window. @@ -95832,7 +97607,7 @@ a window. c:type="GtkMovementStep"> Passed as argument to various keybinding signals for moving the + line="352">Passed as argument to various keybinding signals for moving the cursor position. glib:name="GTK_MOVEMENT_LOGICAL_POSITIONS"> Move forward or back by graphemes + line="354">Move forward or back by graphemes glib:name="GTK_MOVEMENT_VISUAL_POSITIONS"> Move left or right by graphemes + line="355">Move left or right by graphemes glib:name="GTK_MOVEMENT_WORDS"> Move forward or back by words + line="356">Move forward or back by words glib:name="GTK_MOVEMENT_DISPLAY_LINES"> Move up or down lines (wrapped lines) + line="357">Move up or down lines (wrapped lines) glib:name="GTK_MOVEMENT_DISPLAY_LINE_ENDS"> Move to either end of a line + line="358">Move to either end of a line glib:name="GTK_MOVEMENT_PARAGRAPHS"> Move up or down paragraphs (newline-ended lines) + line="359">Move up or down paragraphs (newline-ended lines) glib:name="GTK_MOVEMENT_PARAGRAPH_ENDS"> Move to either end of a paragraph + line="360">Move to either end of a paragraph glib:name="GTK_MOVEMENT_PAGES"> Move by pages + line="361">Move by pages glib:name="GTK_MOVEMENT_BUFFER_ENDS"> Move to ends of the buffer + line="362">Move to ends of the buffer glib:name="GTK_MOVEMENT_HORIZONTAL_PAGES"> Move horizontally by pages + line="363">Move horizontally by pages glib:type-struct="MultiFilterClass"> `GtkMultiFilter` is the base class for filters that combine multiple filters. + line="36">Base class for filters that combine multiple filters. Adds a @filter to @self to use for matching. + line="237">Adds a filter. @@ -95951,13 +97726,13 @@ cursor position. a `GtkMultiFilter` + line="239">a multi filter A new filter to use + line="240">a filter to add @@ -95965,11 +97740,10 @@ cursor position. Removes the filter at the given @position from the list of filters used -by @self. + line="260">Removes a filter. -If @position is larger than the number of filters, nothing happens and -the function returns. +If @position is larger than the number of filters, +nothing happens. @@ -95978,13 +97752,13 @@ the function returns. a `GtkMultiFilter` + line="262">a multi filter position of filter to remove + line="263">position of filter to remove @@ -95992,7 +97766,9 @@ the function returns. The type of items. See [method@Gio.ListModel.get_item_type]. + line="200">The type of items. + +See [method@Gio.ListModel.get_item_type]. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="214">The number of items. + +See [method@Gio.ListModel.get_n_items]. @@ -96021,8 +97799,7 @@ the function returns. glib:type-struct="MultiSelectionClass"> `GtkMultiSelection` is a `GtkSelectionModel` that allows selecting multiple -elements. + line="28">A selection model that allows selecting multiple elements. @@ -96030,12 +97807,12 @@ elements. Creates a new selection to handle @model. + line="434">Creates a new selection to handle @model. a new `GtkMultiSelection` + line="440">a new `GtkMultiSelection` @@ -96045,7 +97822,7 @@ elements. allow-none="1"> the `GListModel` to manage + line="436">the `GListModel` to manage @@ -96053,22 +97830,21 @@ elements. - Returns the underlying model of @self. + line="459">Returns the underlying model of @self. the underlying model + line="465">the underlying model a `GtkMultiSelection` + line="461">a `GtkMultiSelection` @@ -96076,10 +97852,9 @@ elements. - Sets the model that @self should wrap. + line="475">Sets the model that @self should wrap. If @model is %NULL, @self will be empty. @@ -96090,7 +97865,7 @@ If @model is %NULL, @self will be empty. a `GtkMultiSelection` + line="477">a `GtkMultiSelection` allow-none="1"> A `GListModel` to wrap + line="478">A `GListModel` to wrap @@ -96107,7 +97882,7 @@ If @model is %NULL, @self will be empty. The type of items. See [method@Gio.ListModel.get_item_type]. + line="390">The type of items. See [method@Gio.ListModel.get_item_type]. transfer-ownership="none" setter="set_model" getter="get_model"> - - The list managed by this selection. + line="402">The list managed by this selection. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="412">The number of items. See [method@Gio.ListModel.get_n_items]. @@ -96151,8 +97922,7 @@ If @model is %NULL, @self will be empty. glib:type-struct="MultiSorterClass"> `GtkMultiSorter` combines multiple sorters by trying them -in turn. + line="35">Combines multiple sorters by trying them in turn. If the first sorter compares two items as equal, the second is tried next, and so on. @@ -96162,7 +97932,7 @@ the second is tried next, and so on. Creates a new multi sorter. + line="428">Creates a new multi sorter. This sorter compares items by trying each of the sorters in turn, until one returns non-zero. In particular, if @@ -96172,14 +97942,14 @@ items as equal. a new `GtkMultiSorter` + line="438">a new `GtkMultiSorter` Add @sorter to @self to use for sorting at the end. + line="446">Add @sorter to @self to use for sorting at the end. @self will consult all existing sorters before it will sort with the given @sorter. @@ -96191,13 +97961,13 @@ sort with the given @sorter. a `GtkMultiSorter` + line="448">a `GtkMultiSorter` a sorter to add + line="449">a sorter to add @@ -96205,7 +97975,7 @@ sort with the given @sorter. Removes the sorter at the given @position from the list of sorter + line="473">Removes the sorter at the given @position from the list of sorter used by @self. If @position is larger than the number of sorters, nothing happens. @@ -96217,13 +97987,13 @@ If @position is larger than the number of sorters, nothing happens. a `GtkMultiSorter` + line="475">a `GtkMultiSorter` position of sorter to remove + line="476">position of sorter to remove @@ -96231,7 +98001,7 @@ If @position is larger than the number of sorters, nothing happens. The type of items. See [method@Gio.ListModel.get_item_type]. + line="391">The type of items. See [method@Gio.ListModel.get_item_type]. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="403">The number of items. See [method@Gio.ListModel.get_n_items]. @@ -96279,30 +98049,34 @@ If @position is larger than the number of sorters, nothing happens. glib:type-struct="NamedActionClass"> A `GtkShortcutAction` that activates an action by name. - + line="155">Activates a named action. + +See [method@Gtk.WidgetClass.install_action] and +[method@Gtk.Widget.insert_action_group] for ways +to associate named actions with widgets. + Creates an action that when activated, activates + line="1211">Creates an action that when activated, activates the named action on the widget. It also passes the given arguments to it. See [method@Gtk.Widget.insert_action_group] for how to add actions to widgets. - + a new `GtkShortcutAction` + line="1223">a new `GtkShortcutAction` the detailed name of the action + line="1213">the detailed name of the action @@ -96310,22 +98084,21 @@ how to add actions to widgets. - Returns the name of the action that will be activated. - + line="1235">Returns the name of the action that will be activated. + the name of the action to activate + line="1241">the name of the action to activate a named action + line="1237">a named action @@ -96336,11 +98109,9 @@ how to add actions to widgets. transfer-ownership="none" getter="get_action_name" default-value="NULL"> - The name of the action to activate. + line="1191">The name of the action to activate. @@ -96349,7 +98120,7 @@ how to add actions to widgets. disguised="1" opaque="1" glib:is-gtype-struct-for="NamedAction"> - + glib:type-struct="NativeInterface"> `GtkNative` is the interface implemented by all widgets that have -their own `GdkSurface`. + line="44">An interface for widgets that have their own [class@Gdk.Surface]. The obvious example of a `GtkNative` is `GtkWindow`. @@ -96380,19 +98150,19 @@ renderer, use [method@Gtk.Native.get_renderer]. c:identifier="gtk_native_get_for_surface"> Finds the `GtkNative` associated with the surface. + line="269">Finds the `GtkNative` associated with the surface. the `GtkNative` that is associated with @surface + line="275">the `GtkNative` that is associated with @surface a `GdkSurface` + line="271">a `GdkSurface` @@ -96400,19 +98170,19 @@ renderer, use [method@Gtk.Native.get_renderer]. Returns the renderer that is used for this `GtkNative`. + line="230">Returns the renderer that is used for this `GtkNative`. - + the renderer for @self + line="236">the renderer for @self a `GtkNative` + line="232">a `GtkNative` @@ -96420,19 +98190,19 @@ renderer, use [method@Gtk.Native.get_renderer]. Returns the surface of this `GtkNative`. + line="214">Returns the surface of this `GtkNative`. - + the surface of @self + line="220">the surface of @self a `GtkNative` + line="216">a `GtkNative` @@ -96441,7 +98211,7 @@ renderer, use [method@Gtk.Native.get_renderer]. c:identifier="gtk_native_get_surface_transform"> Retrieves the surface transform of @self. + line="246">Retrieves the surface transform of @self. This is the translation from @self's surface coordinates into @self's widget coordinates. @@ -96453,7 +98223,7 @@ This is the translation from @self's surface coordinates into a `GtkNative` + line="248">a `GtkNative` return location for the x coordinate + line="249">return location for the x coordinate return location for the y coordinate + line="250">return location for the y coordinate @@ -96479,7 +98249,7 @@ This is the translation from @self's surface coordinates into Realizes a `GtkNative`. + line="145">Realizes a `GtkNative`. This should only be used by subclasses. @@ -96490,7 +98260,7 @@ This should only be used by subclasses. a `GtkNative` + line="147">a `GtkNative` @@ -96498,7 +98268,7 @@ This should only be used by subclasses. Unrealizes a `GtkNative`. + line="185">Unrealizes a `GtkNative`. This should only be used by subclasses. @@ -96509,7 +98279,7 @@ This should only be used by subclasses. a `GtkNative` + line="187">a `GtkNative` @@ -96525,10 +98295,10 @@ This should only be used by subclasses. glib:type-struct="NativeDialogClass"> Native dialogs are platform dialogs that don't use `GtkDialog`. + line="32">Base class for platform dialogs that don't use `GtkDialog`. -They are used in order to integrate better with a platform, by -looking the same as other native applications and supporting +Native dialogs are used in order to integrate better with a platform, +by looking the same as other native applications and supporting platform specific features. The [class@Gtk.Dialog] functions cannot be used on such objects, @@ -96567,6 +98337,9 @@ If the dialog is not visible this does nothing. + class handler for the `GtkNativeDialog::response` signal @@ -96633,7 +98406,6 @@ windowing system to the `GtkNativeDialog`. - Returns whether the dialog is modal. @@ -96656,7 +98428,6 @@ windowing system to the `GtkNativeDialog`. - Gets the title of the `GtkNativeDialog`. @@ -96681,7 +98452,6 @@ windowing system to the `GtkNativeDialog`. - Fetches the transient parent for this window. @@ -96705,7 +98475,6 @@ windowing system to the `GtkNativeDialog`. - Determines whether the dialog is visible. @@ -96751,7 +98520,6 @@ If the dialog is not visible this does nothing. - Sets a dialog modal or non-modal. @@ -96783,7 +98551,6 @@ then disallow lowering the dialog below the parent. - Sets the title of the `GtkNativeDialog.` @@ -96809,7 +98576,6 @@ then disallow lowering the dialog below the parent. - Dialog windows should be set transient for the main application @@ -96870,10 +98636,6 @@ Multiple calls while the dialog is visible will be ignored. setter="set_modal" getter="get_modal" default-value="FALSE"> - - Whether the window should be modal with respect to its transient parent. @@ -96885,10 +98647,6 @@ Multiple calls while the dialog is visible will be ignored. setter="set_title" getter="get_title" default-value="NULL"> - - The title of the dialog window @@ -96900,10 +98658,6 @@ Multiple calls while the dialog is visible will be ignored. transfer-ownership="none" setter="set_transient_for" getter="get_transient_for"> - - The transient parent of the dialog, or %NULL for none. @@ -96914,8 +98668,6 @@ Multiple calls while the dialog is visible will be ignored. transfer-ownership="none" getter="get_visible" default-value="FALSE"> - Whether the window is currently visible. @@ -96957,6 +98709,9 @@ responds to the dialog this signal will not be emitted. + class handler for the `GtkNativeDialog::response` signal @@ -97051,7 +98806,7 @@ responds to the dialog this signal will not be emitted. c:type="GtkNaturalWrapMode"> Options for selecting a different wrap mode for natural size + line="382">Options for selecting a different wrap mode for natural size requests. See for example the [property@Gtk.Label:natural-wrap-mode] property. @@ -97062,7 +98817,7 @@ See for example the [property@Gtk.Label:natural-wrap-mode] property. glib:name="GTK_NATURAL_WRAP_INHERIT"> Inherit the minimum size request. + line="384">Inherit the minimum size request. In particular, this should be used with %PANGO_WRAP_CHAR. glib:name="GTK_NATURAL_WRAP_NONE"> Try not to wrap the text. This mode is the + line="386">Try not to wrap the text. This mode is the closest to GTK3's behavior but can lead to a wide label leaving lots of empty space below the text. @@ -97083,7 +98838,7 @@ See for example the [property@Gtk.Label:natural-wrap-mode] property. glib:name="GTK_NATURAL_WRAP_WORD"> Attempt to wrap at word boundaries. This + line="389">Attempt to wrap at word boundaries. This is useful in particular when using %PANGO_WRAP_WORD_CHAR as the wrap mode. @@ -97132,8 +98887,7 @@ all virtual functions. glib:type-struct="NoSelectionClass"> `GtkNoSelection` is a `GtkSelectionModel` that does not allow selecting -anything. + line="28">A selection model that does not allow selecting anything. This model is meant to be used as a simple wrapper around a `GListModel` when a `GtkSelectionModel` is required. @@ -97146,12 +98900,12 @@ when a `GtkSelectionModel` is required. Creates a new selection to handle @model. + line="293">Creates a new selection to handle @model. a new `GtkNoSelection` + line="299">a new `GtkNoSelection` @@ -97161,7 +98915,7 @@ when a `GtkSelectionModel` is required. allow-none="1"> the `GListModel` to manage + line="295">the `GListModel` to manage @@ -97169,22 +98923,21 @@ when a `GtkSelectionModel` is required. - Gets the model that @self is wrapping. + line="318">Gets the model that @self is wrapping. The model being wrapped + line="324">The model being wrapped a `GtkNoSelection` + line="320">a `GtkNoSelection` @@ -97192,10 +98945,9 @@ when a `GtkSelectionModel` is required. - Sets the model that @self should wrap. + line="334">Sets the model that @self should wrap. If @model is %NULL, this model will be empty. @@ -97206,7 +98958,7 @@ If @model is %NULL, this model will be empty. a `GtkNoSelection` + line="336">a `GtkNoSelection` allow-none="1"> A `GListModel` to wrap + line="337">A `GListModel` to wrap @@ -97223,7 +98975,7 @@ If @model is %NULL, this model will be empty. The type of items. See [method@Gio.ListModel.get_item_type]. + line="251">The type of items. See [method@Gio.ListModel.get_item_type]. transfer-ownership="none" setter="set_model" getter="get_model"> - - The model being managed. + line="263">The model being managed. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="273">The number of items. See [method@Gio.ListModel.get_n_items]. @@ -97266,10 +99014,12 @@ If @model is %NULL, this model will be empty. glib:get-type="gtk_notebook_get_type"> `GtkNotebook` is a container whose children are pages switched -between using tabs. + line="61">Switches between children using tabs. -![An example GtkNotebook](notebook.png) +<picture> + <source srcset="notebook-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkNotebook" src="notebook.png"> +</picture> There are many configuration options for `GtkNotebook`. Among other things, you can choose on which edge the tabs appear @@ -97309,6 +99059,31 @@ An example of a UI definition fragment with `GtkNotebook`: </object> ``` +# Shortcuts and Gestures + +`GtkNotebook` supports the following keyboard shortcuts: + +- <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. +- <kbd>Home</kbd> moves the focus to the first tab. +- <kbd>End</kbd> moves the focus to the last tab. + +Additionally, the following signals have default keybindings: + +- [signal@Gtk.Notebook::change-current-page] +- [signal@Gtk.Notebook::focus-tab] +- [signal@Gtk.Notebook::move-focus-out] +- [signal@Gtk.Notebook::reorder-tab] +- [signal@Gtk.Notebook::select-page] + +Tabs support drag-and-drop between notebooks sharing the same `group-name`, +or to new windows by handling the `::create-window` signal. + +# Actions + +`GtkNotebook` defines a set of built-in actions: + +- `menu.popup` opens the tabs context menu. + # CSS nodes ``` @@ -97354,34 +99129,34 @@ The nodes are always arranged from left-to-right, regardless of text direction. `GtkNotebook` uses the following roles: - - %GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget - - %GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs - - %GTK_ACCESSIBLE_ROLE_TAB role for each tab - - %GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page + - [enum@Gtk.AccessibleRole.group] for the notebook widget + - [enum@Gtk.AccessibleRole.tab_list] for the list of tabs + - [enum@Gtk.AccessibleRole.tab] role for each tab + - [enum@Gtk.AccessibleRole.tab_panel] for each page Creates a new `GtkNotebook` widget with no pages. + line="1939">Creates a new `GtkNotebook` widget with no pages. the newly created `GtkNotebook` + line="1944">the newly created `GtkNotebook` Appends a page to @notebook. + line="5735">Appends a page to @notebook. the index (starting from 0) of the appended + line="5744">the index (starting from 0) of the appended page in the notebook, or -1 if function fails @@ -97389,13 +99164,13 @@ The nodes are always arranged from left-to-right, regardless of text direction. a `GtkNotebook` + line="5737">a `GtkNotebook` the `GtkWidget` to use as the contents of the page + line="5738">the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label + line="5739">the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” @@ -97414,13 +99189,13 @@ The nodes are always arranged from left-to-right, regardless of text direction. c:identifier="gtk_notebook_append_page_menu"> Appends a page to @notebook, specifying the widget to use as the + line="5759">Appends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the appended + line="5775">the index (starting from 0) of the appended page in the notebook, or -1 if function fails @@ -97428,13 +99203,13 @@ label in the popup menu. a `GtkNotebook` + line="5761">a `GtkNotebook` the `GtkWidget` to use as the contents of the page + line="5762">the `GtkWidget` to use as the contents of the page allow-none="1"> the `GtkWidget` to be used as the label + line="5763">the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” @@ -97453,7 +99228,7 @@ label in the popup menu. allow-none="1"> the widget to use as a label for the + line="5765">the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label @@ -97466,7 +99241,7 @@ label in the popup menu. Removes the child from the notebook. + line="3481">Removes the child from the notebook. This function is very similar to [method@Gtk.Notebook.remove_page], but additionally informs the notebook that the removal @@ -97480,13 +99255,13 @@ not be cancelled. a `GtkNotebook` + line="3483">a `GtkNotebook` a child + line="3484">a child @@ -97495,14 +99270,14 @@ not be cancelled. c:identifier="gtk_notebook_get_action_widget"> Gets one of the action widgets. + line="7150">Gets one of the action widgets. See [method@Gtk.Notebook.set_action_widget]. The action widget + line="7159">The action widget with the given @pack_type or %NULL when this action widget has not been set @@ -97511,28 +99286,28 @@ See [method@Gtk.Notebook.set_action_widget]. a `GtkNotebook` + line="7152">a `GtkNotebook` pack type of the action widget to receive + line="7153">pack type of the action widget to receive - + c:identifier="gtk_notebook_get_current_page" + glib:get-property="page"> Returns the page number of the current page. + line="5980">Returns the page number of the current page. the index (starting from 0) of the current + line="5986">the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned. @@ -97541,7 +99316,7 @@ See [method@Gtk.Notebook.set_action_widget]. a `GtkNotebook` + line="5982">a `GtkNotebook` @@ -97549,15 +99324,14 @@ See [method@Gtk.Notebook.set_action_widget]. - Gets the current group name for @notebook. + line="6971">Gets the current group name for @notebook. the group name, + line="6977">the group name, or %NULL if none is set @@ -97565,7 +99339,7 @@ See [method@Gtk.Notebook.set_action_widget]. a `GtkNotebook` + line="6973">a `GtkNotebook` @@ -97573,12 +99347,12 @@ See [method@Gtk.Notebook.set_action_widget]. Retrieves the menu label widget of the page containing @child. + line="6715">Retrieves the menu label widget of the page containing @child. the menu label, or %NULL + line="6722">the menu label, or %NULL if the notebook page does not have a menu label other than the default (the tab label). @@ -97587,13 +99361,13 @@ See [method@Gtk.Notebook.set_action_widget]. a `GtkNotebook` + line="6717">a `GtkNotebook` a widget contained in a page of @notebook + line="6718">a widget contained in a page of @notebook @@ -97602,13 +99376,13 @@ See [method@Gtk.Notebook.set_action_widget]. c:identifier="gtk_notebook_get_menu_label_text"> Retrieves the text of the menu label for the page containing + line="6815">Retrieves the text of the menu label for the page containing @child. the text of the tab label, or %NULL if + line="6823">the text of the tab label, or %NULL if the widget does not have a menu label other than the default menu label, or the menu label widget is not a `GtkLabel`. The string is owned by the widget and must not be freed. @@ -97618,13 +99392,13 @@ See [method@Gtk.Notebook.set_action_widget]. a `GtkNotebook` + line="6817">a `GtkNotebook` the child widget of a page of the notebook. + line="6818">the child widget of a page of the notebook. @@ -97632,19 +99406,19 @@ See [method@Gtk.Notebook.set_action_widget]. Gets the number of pages in a notebook. + line="6035">Gets the number of pages in a notebook. the number of pages in the notebook + line="6041">the number of pages in the notebook a `GtkNotebook` + line="6037">a `GtkNotebook` @@ -97652,12 +99426,12 @@ See [method@Gtk.Notebook.set_action_widget]. Returns the child widget contained in page number @page_num. + line="6001">Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num + line="6009">the child widget, or %NULL if @page_num is out of bounds @@ -97665,42 +99439,40 @@ is out of bounds a `GtkNotebook` + line="6003">a `GtkNotebook` the index of a page in the notebook, or -1 + line="6004">the index of a page in the notebook, or -1 to get the last page - + Returns the `GtkNotebookPage` for @child. + line="7211">Returns the `GtkNotebookPage` for @child. the `GtkNotebookPage` for @child + line="7218">the `GtkNotebookPage` for @child a `GtkNotebook` + line="7213">a `GtkNotebook` a child of @notebook + line="7214">a child of @notebook @@ -97708,10 +99480,9 @@ is out of bounds - Returns a `GListModel` that contains the pages of the notebook. + line="7366">Returns a `GListModel` that contains the pages of the notebook. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track @@ -97721,7 +99492,7 @@ and modify the visible page. a + line="7376">a `GListModel` for the notebook's children @@ -97729,7 +99500,7 @@ and modify the visible page. a `GtkNotebook` + line="7368">a `GtkNotebook` @@ -97737,22 +99508,21 @@ and modify the visible page. - Returns whether the tab label area has arrows for scrolling. + line="6453">Returns whether the tab label area has arrows for scrolling. %TRUE if arrows for scrolling are present + line="6459">%TRUE if arrows for scrolling are present a `GtkNotebook` + line="6455">a `GtkNotebook` @@ -97760,22 +99530,21 @@ and modify the visible page. - Returns whether a bevel will be drawn around the notebook pages. + line="6209">Returns whether a bevel will be drawn around the notebook pages. %TRUE if the bevel is drawn + line="6215">%TRUE if the bevel is drawn a `GtkNotebook` + line="6211">a `GtkNotebook` @@ -97783,22 +99552,21 @@ and modify the visible page. - Returns whether the tabs of the notebook are shown. + line="6283">Returns whether the tabs of the notebook are shown. %TRUE if the tabs are shown + line="6289">%TRUE if the tabs are shown a `GtkNotebook` + line="6285">a `GtkNotebook` @@ -97807,25 +99575,25 @@ and modify the visible page. c:identifier="gtk_notebook_get_tab_detachable"> Returns whether the tab contents can be detached from @notebook. + line="7050">Returns whether the tab contents can be detached from @notebook. %TRUE if the tab is detachable. + line="7057">%TRUE if the tab is detachable. a `GtkNotebook` + line="7052">a `GtkNotebook` a child `GtkWidget` + line="7053">a child `GtkWidget` @@ -97833,7 +99601,7 @@ and modify the visible page. Returns the tab label widget for the page @child. + line="6553">Returns the tab label widget for the page @child. %NULL is returned if @child is not in @notebook or if no tab label has specifically been set for @child. @@ -97841,20 +99609,20 @@ if no tab label has specifically been set for @child. the tab label + line="6563">the tab label a `GtkNotebook` + line="6555">a `GtkNotebook` the page + line="6556">the page @@ -97863,13 +99631,13 @@ if no tab label has specifically been set for @child. c:identifier="gtk_notebook_get_tab_label_text"> Retrieves the text of the tab label for the page containing + line="6686">Retrieves the text of the tab label for the page containing @child. the text of the tab label, or %NULL if + line="6694">the text of the tab label, or %NULL if the tab label widget is not a `GtkLabel`. The string is owned by the widget and must not be freed. @@ -97878,13 +99646,13 @@ if no tab label has specifically been set for @child. a `GtkNotebook` + line="6688">a `GtkNotebook` a widget contained in a page of @notebook + line="6689">a widget contained in a page of @notebook @@ -97892,22 +99660,21 @@ if no tab label has specifically been set for @child. - Gets the edge at which the tabs are drawn. + line="6408">Gets the edge at which the tabs are drawn. the edge at which the tabs are drawn + line="6414">the edge at which the tabs are drawn a `GtkNotebook` + line="6410">a `GtkNotebook` @@ -97916,25 +99683,25 @@ if no tab label has specifically been set for @child. c:identifier="gtk_notebook_get_tab_reorderable"> Gets whether the tab can be reordered via drag and drop or not. + line="6988">Gets whether the tab can be reordered via drag and drop or not. %TRUE if the tab is reorderable. + line="6995">%TRUE if the tab is reorderable. a `GtkNotebook` + line="6990">a `GtkNotebook` a child `GtkWidget` + line="6991">a child `GtkWidget` @@ -97942,12 +99709,12 @@ if no tab label has specifically been set for @child. Insert a page into @notebook at the given position. + line="5849">Insert a page into @notebook at the given position. the index (starting from 0) of the inserted + line="5860">the index (starting from 0) of the inserted page in the notebook, or -1 if function fails @@ -97955,13 +99722,13 @@ if no tab label has specifically been set for @child. a `GtkNotebook` + line="5851">a `GtkNotebook` the `GtkWidget` to use as the contents of the page + line="5852">the `GtkWidget` to use as the contents of the page allow-none="1"> the `GtkWidget` to be used as the label + line="5853">the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the index (starting at 0) at which to insert the page, + line="5855">the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages @@ -97987,13 +99754,13 @@ if no tab label has specifically been set for @child. c:identifier="gtk_notebook_insert_page_menu"> Insert a page into @notebook at the given position, specifying + line="5906">Insert a page into @notebook at the given position, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the inserted + line="5924">the index (starting from 0) of the inserted page in the notebook @@ -98001,13 +99768,13 @@ the widget to use as the label in the popup menu. a `GtkNotebook` + line="5908">a `GtkNotebook` the `GtkWidget` to use as the contents of the page + line="5909">the `GtkWidget` to use as the contents of the page allow-none="1"> the `GtkWidget` to be used as the label + line="5910">the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” @@ -98026,7 +99793,7 @@ the widget to use as the label in the popup menu. allow-none="1"> the widget to use as a label for the + line="5912">the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label @@ -98037,7 +99804,7 @@ the widget to use as the label in the popup menu. the index (starting at 0) at which to insert the page, + line="5918">the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages. @@ -98046,7 +99813,7 @@ the widget to use as the label in the popup menu. Switches to the next page. + line="6118">Switches to the next page. Nothing happens if the current page is the last page. @@ -98057,7 +99824,7 @@ Nothing happens if the current page is the last page. a `GtkNotebook` + line="6120">a `GtkNotebook` @@ -98065,13 +99832,13 @@ Nothing happens if the current page is the last page. Finds the index of the page which contains the given child + line="6051">Finds the index of the page which contains the given child widget. the index of the page containing @child, or + line="6059">the index of the page containing @child, or -1 if @child is not in the notebook @@ -98079,13 +99846,13 @@ widget. a `GtkNotebook` + line="6053">a `GtkNotebook` a `GtkWidget` + line="6054">a `GtkWidget` @@ -98093,7 +99860,7 @@ widget. Disables the popup menu. + line="6513">Disables the popup menu. @@ -98102,7 +99869,7 @@ widget. a `GtkNotebook` + line="6515">a `GtkNotebook` @@ -98110,7 +99877,7 @@ widget. Enables the popup menu. + line="6477">Enables the popup menu. If the user clicks with the right mouse button on the tab labels, a menu with all the pages will be popped up. @@ -98122,7 +99889,7 @@ a menu with all the pages will be popped up. a `GtkNotebook` + line="6479">a `GtkNotebook` @@ -98130,12 +99897,12 @@ a menu with all the pages will be popped up. Prepends a page to @notebook. + line="5792">Prepends a page to @notebook. the index (starting from 0) of the prepended + line="5801">the index (starting from 0) of the prepended page in the notebook, or -1 if function fails @@ -98143,13 +99910,13 @@ a menu with all the pages will be popped up. a `GtkNotebook` + line="5794">a `GtkNotebook` the `GtkWidget` to use as the contents of the page + line="5795">the `GtkWidget` to use as the contents of the page allow-none="1"> the `GtkWidget` to be used as the label + line="5796">the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” @@ -98168,13 +99935,13 @@ a menu with all the pages will be popped up. c:identifier="gtk_notebook_prepend_page_menu"> Prepends a page to @notebook, specifying the widget to use as the + line="5816">Prepends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the prepended + line="5832">the index (starting from 0) of the prepended page in the notebook, or -1 if function fails @@ -98182,13 +99949,13 @@ label in the popup menu. a `GtkNotebook` + line="5818">a `GtkNotebook` the `GtkWidget` to use as the contents of the page + line="5819">the `GtkWidget` to use as the contents of the page allow-none="1"> the `GtkWidget` to be used as the label + line="5820">the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” @@ -98207,7 +99974,7 @@ label in the popup menu. allow-none="1"> the widget to use as a label for the + line="5822">the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label @@ -98220,7 +99987,7 @@ label in the popup menu. Switches to the previous page. + line="6144">Switches to the previous page. Nothing happens if the current page is the first page. @@ -98231,7 +99998,7 @@ Nothing happens if the current page is the first page. a `GtkNotebook` + line="6146">a `GtkNotebook` @@ -98239,7 +100006,7 @@ Nothing happens if the current page is the first page. Removes a page from the notebook given its index + line="5946">Removes a page from the notebook given its index in the notebook. @@ -98249,13 +100016,13 @@ in the notebook. a `GtkNotebook` + line="5948">a `GtkNotebook` the index of a notebook page, starting + line="5949">the index of a notebook page, starting from 0. If -1, the last page will be removed. @@ -98264,7 +100031,7 @@ in the notebook. Reorders the page containing @child, so that it appears in position + line="6875">Reorders the page containing @child, so that it appears in position @position. If @position is greater than or equal to the number of children in @@ -98277,19 +100044,19 @@ the list or negative, @child will be moved to the end of the list. a `GtkNotebook` + line="6877">a `GtkNotebook` the child to move + line="6878">the child to move the new position, or -1 to move to the end + line="6879">the new position, or -1 to move to the end @@ -98298,7 +100065,7 @@ the list or negative, @child will be moved to the end of the list. c:identifier="gtk_notebook_set_action_widget"> Sets @widget as one of the action widgets. + line="7172">Sets @widget as one of the action widgets. Depending on the pack type the widget will be placed before or after the tabs. You can use a `GtkBox` if you need to pack @@ -98311,29 +100078,29 @@ more than one widget on the same side. a `GtkNotebook` + line="7174">a `GtkNotebook` a `GtkWidget` + line="7175">a `GtkWidget` pack type of the action widget + line="7176">pack type of the action widget - + c:identifier="gtk_notebook_set_current_page" + glib:set-property="page"> Switches to the page number @page_num. + line="6087">Switches to the page number @page_num. Note that due to historical reasons, GtkNotebook refuses to switch to a page unless the child widget is visible. @@ -98347,13 +100114,13 @@ adding them to a notebook. a `GtkNotebook` + line="6089">a `GtkNotebook` index of the page to switch to, starting from 0. + line="6090">index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the notebook, nothing will be done. @@ -98364,10 +100131,9 @@ adding them to a notebook. - Sets a group name for @notebook. + line="6941">Sets a group name for @notebook. Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a %NULL group name will @@ -98380,7 +100146,7 @@ not be able to exchange tabs with any other notebook. a `GtkNotebook` + line="6943">a `GtkNotebook` allow-none="1"> the name of the notebook group, + line="6944">the name of the notebook group, or %NULL to unset it @@ -98398,7 +100164,7 @@ not be able to exchange tabs with any other notebook. Changes the menu label for the page containing @child. + line="6744">Changes the menu label for the page containing @child. @@ -98407,13 +100173,13 @@ not be able to exchange tabs with any other notebook. a `GtkNotebook` + line="6746">a `GtkNotebook` the child widget + line="6747">the child widget allow-none="1"> the menu label, or %NULL for default + line="6748">the menu label, or %NULL for default @@ -98431,7 +100197,7 @@ not be able to exchange tabs with any other notebook. c:identifier="gtk_notebook_set_menu_label_text"> Creates a new label and sets it as the menu label of @child. + line="6789">Creates a new label and sets it as the menu label of @child. @@ -98440,19 +100206,19 @@ not be able to exchange tabs with any other notebook. a `GtkNotebook` + line="6791">a `GtkNotebook` the child widget + line="6792">the child widget the label text + line="6793">the label text @@ -98460,10 +100226,9 @@ not be able to exchange tabs with any other notebook. - Sets whether the tab label area will have arrows for + line="6424">Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. @@ -98473,13 +100238,13 @@ scrolling if there are too many tabs to fit in the area. a `GtkNotebook` + line="6426">a `GtkNotebook` %TRUE if scroll arrows should be added + line="6427">%TRUE if scroll arrows should be added @@ -98487,10 +100252,9 @@ scrolling if there are too many tabs to fit in the area. - Sets whether a bevel will be drawn around the notebook pages. + line="6181">Sets whether a bevel will be drawn around the notebook pages. This only has a visual effect when the tabs are not shown. @@ -98501,13 +100265,13 @@ This only has a visual effect when the tabs are not shown. a `GtkNotebook` + line="6183">a `GtkNotebook` %TRUE if a bevel should be drawn around the notebook + line="6184">%TRUE if a bevel should be drawn around the notebook @@ -98515,10 +100279,9 @@ This only has a visual effect when the tabs are not shown. - Sets whether to show the tabs for the notebook or not. + line="6225">Sets whether to show the tabs for the notebook or not. @@ -98527,13 +100290,13 @@ This only has a visual effect when the tabs are not shown. a `GtkNotebook` + line="6227">a `GtkNotebook` %TRUE if the tabs should be shown + line="6228">%TRUE if the tabs should be shown @@ -98542,7 +100305,7 @@ This only has a visual effect when the tabs are not shown. c:identifier="gtk_notebook_set_tab_detachable"> Sets whether the tab can be detached from @notebook to another + line="7074">Sets whether the tab can be detached from @notebook to another notebook or widget. Note that two notebooks must share a common group identifier @@ -98551,9 +100314,10 @@ interchange between them. If you want a widget to interact with a notebook through DnD (i.e.: accept dragged tabs from it) it must be set as a drop -destination and accept the target “GTK_NOTEBOOK_TAB”. The notebook -will fill the selection with a GtkWidget** pointing to the child -widget that corresponds to the dropped tab. +destination by adding to it a [class@Gtk.DropTarget] controller that accepts +the GType `GTK_TYPE_NOTEBOOK_PAGE`. The `:value` of said drop target will be +preloaded with a [class@Gtk.NotebookPage] object that corresponds to the +dropped tab, so you can process the value via `::accept` or `::drop` signals. Note that you should use [method@Gtk.Notebook.detach_tab] instead of [method@Gtk.Notebook.remove_page] if you want to remove the tab @@ -98594,19 +100358,19 @@ you will have to set your own DnD code to do it. a `GtkNotebook` + line="7076">a `GtkNotebook` a child `GtkWidget` + line="7077">a child `GtkWidget` whether the tab is detachable or not + line="7078">whether the tab is detachable or not @@ -98614,7 +100378,7 @@ you will have to set your own DnD code to do it. Changes the tab label for @child. + line="6584">Changes the tab label for @child. If %NULL is specified for @tab_label, then the page will have the label “page N”. @@ -98626,13 +100390,13 @@ have the label “page N”. a `GtkNotebook` + line="6586">a `GtkNotebook` the page + line="6587">the page allow-none="1"> the tab label widget to use, or %NULL + line="6588">the tab label widget to use, or %NULL for default tab label @@ -98651,7 +100415,7 @@ have the label “page N”. c:identifier="gtk_notebook_set_tab_label_text"> Creates a new label and sets it as the tab label for the page + line="6663">Creates a new label and sets it as the tab label for the page containing @child. @@ -98661,19 +100425,19 @@ containing @child. a `GtkNotebook` + line="6665">a `GtkNotebook` the page + line="6666">the page the label text + line="6667">the label text @@ -98681,10 +100445,9 @@ containing @child. - Sets the edge at which the tabs are drawn. + line="6384">Sets the edge at which the tabs are drawn. @@ -98693,13 +100456,13 @@ containing @child. a `GtkNotebook`. + line="6386">a `GtkNotebook`. the edge to draw the tabs at + line="6387">the edge to draw the tabs at @@ -98708,7 +100471,7 @@ containing @child. c:identifier="gtk_notebook_set_tab_reorderable"> Sets whether the notebook tab can be reordered + line="7012">Sets whether the notebook tab can be reordered via drag and drop or not. @@ -98718,19 +100481,19 @@ via drag and drop or not. a `GtkNotebook` + line="7014">a `GtkNotebook` a child `GtkWidget` + line="7015">a child `GtkWidget` whether the tab is reorderable or not + line="7016">whether the tab is reorderable or not @@ -98741,7 +100504,7 @@ via drag and drop or not. default-value="FALSE"> If %TRUE, pressing the right mouse button on the notebook shows a page switching menu. + line="1178">If %TRUE, pressing the right mouse button on the notebook shows a page switching menu. setter="set_group_name" getter="get_group_name" default-value="NULL"> - - Group name for tab drag and drop. + line="1188">Group name for tab drag and drop. - - The index of the current page. + line="1126">The index of the current page. - A selection model with the pages. + line="1198">A selection model with the pages. setter="set_scrollable" getter="get_scrollable" default-value="FALSE"> - - If %TRUE, scroll arrows are added if there are too many pages to fit. + line="1168">If %TRUE, scroll arrows are added if there are too many pages to fit. setter="set_show_border" getter="get_show_border" default-value="TRUE"> - - Whether the border should be shown. + line="1158">Whether the border should be shown. setter="set_show_tabs" getter="get_show_tabs" default-value="TRUE"> - - Whether tabs should be shown. + line="1148">Whether tabs should be shown. setter="set_tab_pos" getter="get_tab_pos" default-value="GTK_POS_TOP"> - - Which side of the notebook holds the tabs. + line="1137">Which side of the notebook holds the tabs. + Emitted when the current page should be changed. + +The default bindings for this signal are +<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgUp</kbd>, +<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgDn</kbd>, +<kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>. + whether the page was changed - + + the page index @@ -98853,7 +100606,7 @@ via drag and drop or not. The ::create-window signal is emitted when a detachable + line="1424">The ::create-window signal is emitted when a detachable tab is dropped on the root window. A handler for this signal can create a window containing @@ -98864,7 +100617,7 @@ necessary properties to the notebook (e.g. the a `GtkNotebook` that + line="1438">a `GtkNotebook` that @page should be added to @@ -98872,27 +100625,48 @@ necessary properties to the notebook (e.g. the the tab of @notebook that is being detached + line="1427">the tab of @notebook that is being detached + Emitted when a tab should be focused. + whether the tab has been focused - + + the notebook tab + Emitted when focus was moved out. + +The default bindings for this signal are +<kbd>Ctrl</kbd>+<kbd>Tab</kbd>, +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>, +<kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>Ctrl</kbd>+<kbd>→</kbd>, +<kbd>Ctrl</kbd>+<kbd>↑</kbd> and <kbd>Ctrl</kbd>+<kbd>↓</kbd>. - + + the direction to move the focus @@ -98900,7 +100674,7 @@ necessary properties to the notebook (e.g. the the ::page-added signal is emitted in the notebook + line="1401">the ::page-added signal is emitted in the notebook right after a page is added to the notebook. @@ -98909,13 +100683,13 @@ right after a page is added to the notebook. the child `GtkWidget` affected + line="1404">the child `GtkWidget` affected the new page number for @child + line="1405">the new page number for @child @@ -98923,7 +100697,7 @@ right after a page is added to the notebook. the ::page-removed signal is emitted in the notebook + line="1379">the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook. @@ -98932,13 +100706,13 @@ right after a page is removed from the notebook. the child `GtkWidget` affected + line="1382">the child `GtkWidget` affected the @child page number + line="1383">the @child page number @@ -98946,7 +100720,7 @@ right after a page is removed from the notebook. the ::page-reordered signal is emitted in the notebook + line="1357">the ::page-reordered signal is emitted in the notebook right after a page has been reordered. @@ -98955,36 +100729,65 @@ right after a page has been reordered. the child `GtkWidget` affected + line="1360">the child `GtkWidget` affected the new page number for @child + line="1361">the new page number for @child + Emitted when the tab should be reordered. + +The default bindings for this signal are +<kbd>Alt</kbd>+<kbd>Home</kbd>, <kbd>Alt</kbd>+<kbd>End</kbd>, +<kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Alt</kbd>+<kbd>PgDn</kbd>, +<kbd>Alt</kbd>+<kbd>←</kbd>, <kbd>Alt</kbd>+<kbd>→</kbd>, +<kbd>Alt</kbd>+<kbd>↑</kbd> and <kbd>Alt</kbd>+<kbd>↓</kbd>. + whether the tab was moved. - + + the direction to move the tab - + + whether to move to the last position + Emitted when a page should be selected. + +The default binding for this signal is <kbd>␣</kbd>. + whether the page was selected - + + whether to move focus @@ -98992,7 +100795,7 @@ right after a page has been reordered. Emitted when the user or a function changes the current page. + line="1210">Emitted when the user or a function changes the current page. @@ -99000,13 +100803,13 @@ right after a page has been reordered. the new current page + line="1213">the new current page the index of the page + line="1214">the index of the page @@ -99020,26 +100823,25 @@ right after a page has been reordered. glib:get-type="gtk_notebook_page_get_type"> `GtkNotebookPage` is an auxiliary object used by `GtkNotebook`. + line="185">An auxiliary object used by `GtkNotebook`. - Returns the notebook child to which @page belongs. + line="7237">Returns the notebook child to which @page belongs. the child to which @page belongs + line="7243">the child to which @page belongs a `GtkNotebookPage` + line="7239">a `GtkNotebookPage` @@ -99049,11 +100851,9 @@ right after a page has been reordered. construct-only="1" transfer-ownership="none" getter="get_child"> - The child for this page. + line="605">The child for this page. default-value="FALSE"> Whether the tab is detachable. + line="704">Whether the tab is detachable. transfer-ownership="none"> The label widget displayed in the child's menu entry. + line="627">The label widget displayed in the child's menu entry. default-value="NULL"> The text of the menu widget. + line="649">The text of the menu widget. default-value="0"> The index of the child in the parent. + line="660">The index of the child in the parent. default-value="FALSE"> Whether the tab is reorderable by user action. + line="693">Whether the tab is reorderable by user action. transfer-ownership="none"> The tab widget for this page. + line="616">The tab widget for this page. default-value="FALSE"> Whether to expand the child's tab. + line="671">Whether to expand the child's tab. default-value="TRUE"> Whether the child's tab should fill the allocated area. + line="682">Whether the child's tab should fill the allocated area. default-value="NULL"> The text of the tab widget. + line="638">The text of the tab widget. @@ -99173,12 +100973,12 @@ right after a page has been reordered. glib:type-struct="NothingActionClass"> A `GtkShortcutAction` that does nothing. + line="79">Does nothing. Gets the nothing action. + line="318">Gets the nothing action. This is an action that does nothing and where activating it always fails. @@ -99186,7 +100986,7 @@ activating it always fails. The nothing action + line="326">The nothing action @@ -99204,7 +101004,7 @@ activating it always fails. c:type="GtkNumberUpLayout"> Used to determine the layout of pages on a sheet when printing + line="630">Used to determine the layout of pages on a sheet when printing multiple pages per sheet. glib:name="GTK_NUMBER_UP_LAYOUT_LEFT_TO_RIGHT_TOP_TO_BOTTOM"> ![](layout-lrtb.png) + line="632">![](layout-lrtb.png) glib:name="GTK_NUMBER_UP_LAYOUT_LEFT_TO_RIGHT_BOTTOM_TO_TOP"> ![](layout-lrbt.png) + line="633">![](layout-lrbt.png) glib:name="GTK_NUMBER_UP_LAYOUT_RIGHT_TO_LEFT_TOP_TO_BOTTOM"> ![](layout-rltb.png) + line="634">![](layout-rltb.png) glib:name="GTK_NUMBER_UP_LAYOUT_RIGHT_TO_LEFT_BOTTOM_TO_TOP"> ![](layout-rlbt.png) + line="635">![](layout-rlbt.png) glib:name="GTK_NUMBER_UP_LAYOUT_TOP_TO_BOTTOM_LEFT_TO_RIGHT"> ![](layout-tblr.png) + line="636">![](layout-tblr.png) glib:name="GTK_NUMBER_UP_LAYOUT_TOP_TO_BOTTOM_RIGHT_TO_LEFT"> ![](layout-tbrl.png) + line="637">![](layout-tbrl.png) glib:name="GTK_NUMBER_UP_LAYOUT_BOTTOM_TO_TOP_LEFT_TO_RIGHT"> ![](layout-btlr.png) + line="638">![](layout-btlr.png) glib:name="GTK_NUMBER_UP_LAYOUT_BOTTOM_TO_TOP_RIGHT_TO_LEFT"> ![](layout-btrl.png) + line="639">![](layout-btrl.png) glib:type-struct="NumericSorterClass"> `GtkNumericSorter` is a `GtkSorter` that compares numbers. + line="29">Sorts items numerically. To obtain the numbers to compare, this sorter evaluates a [class@Gtk.Expression]. @@ -99322,7 +101122,6 @@ Smaller numbers will be sorted first. You can call - Gets the expression that is evaluated to obtain numbers from items. @@ -99345,7 +101144,6 @@ Smaller numbers will be sorted first. You can call - Gets whether this sorter will sort smaller numbers first. @@ -99368,7 +101166,6 @@ Smaller numbers will be sorted first. You can call - Sets the expression that is evaluated to obtain numbers from items. @@ -99403,7 +101200,6 @@ numerically, such as %G_TYPE_INT or %G_TYPE_DOUBLE. - Sets whether to sort smaller numbers before larger ones. @@ -99431,10 +101227,6 @@ numerically, such as %G_TYPE_INT or %G_TYPE_DOUBLE. transfer-ownership="none" setter="set_expression" getter="get_expression"> - - The expression to evaluate on items to get a number to compare with. @@ -99446,10 +101238,6 @@ numerically, such as %G_TYPE_INT or %G_TYPE_DOUBLE. setter="set_sort_order" getter="get_sort_order" default-value="GTK_SORT_ASCENDING"> - - Whether the sorter will sort smaller numbers first. @@ -99500,11 +101288,11 @@ numerically, such as %G_TYPE_INT or %G_TYPE_DOUBLE. glib:fundamental="1"> A `GObject` value in a `GtkExpression`. + line="955">A `GObject` value in a `GtkExpression`. Creates an expression evaluating to the given `object` with a weak reference. + line="1098">Creates an expression evaluating to the given `object` with a weak reference. Once the `object` is disposed, it will fail to evaluate. @@ -99515,14 +101303,14 @@ If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.ne a new `GtkExpression` + line="1110">a new `GtkExpression` object to watch + line="1100">object to watch @@ -99531,19 +101319,19 @@ If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.ne c:identifier="gtk_object_expression_get_object"> Gets the object that the expression evaluates to. + line="1133">Gets the object that the expression evaluates to. the object, or `NULL` + line="1139">the object, or `NULL` an object `GtkExpression` + line="1135">an object `GtkExpression` @@ -99555,7 +101343,7 @@ If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.ne c:type="GtkOrdering"> Describes the way two values can be compared. + line="656">Describes the way two values can be compared. These values can be used with a [callback@GLib.CompareFunc]. However, a `GCompareFunc` is allowed to return any integer values. @@ -99568,7 +101356,7 @@ For converting such a value to a `GtkOrdering` value, use glib:name="GTK_ORDERING_SMALLER"> the first value is smaller than the second + line="658">the first value is smaller than the second the two values are equal + line="659">the two values are equal the first value is larger than the second + line="660">the first value is larger than the second Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. - + The `GtkOrientable` interface is implemented by all widgets that can be -oriented horizontally or vertically. + line="31">An interface for widgets that can be oriented horizontally or vertically. `GtkOrientable` is more flexible in that it allows the orientation to be changed at runtime, allowing the widgets to “flip”. @@ -99636,22 +101423,21 @@ the value of the [property@Gtk.Orientable:orientation] property. - Retrieves the orientation of the @orientable. + line="87">Retrieves the orientation of the @orientable. the orientation of the @orientable + line="93">the orientation of the @orientable a `GtkOrientable` + line="89">a `GtkOrientable` @@ -99659,10 +101445,9 @@ the value of the [property@Gtk.Orientable:orientation] property. - Sets the orientation of the @orientable. + line="66">Sets the orientation of the @orientable. @@ -99671,13 +101456,13 @@ the value of the [property@Gtk.Orientable:orientation] property. a `GtkOrientable` + line="68">a `GtkOrientable` the orientable’s new orientation + line="69">the orientable’s new orientation @@ -99688,13 +101473,9 @@ the value of the [property@Gtk.Orientable:orientation] property. setter="set_orientation" getter="get_orientation" default-value="GTK_ORIENTATION_HORIZONTAL"> - - The orientation of the orientable. + line="54">The orientation of the orientable. @@ -99712,7 +101493,7 @@ the value of the [property@Gtk.Orientable:orientation] property. c:type="GtkOrientation"> Represents the orientation of widgets and other objects. + line="428">Represents the orientation of widgets and other objects. Typical examples are [class@Box] or [class@GesturePan]. glib:name="GTK_ORIENTATION_HORIZONTAL"> The element is in horizontal orientation. + line="430">The element is in horizontal orientation. glib:name="GTK_ORIENTATION_VERTICAL"> The element is in vertical orientation. + line="431">The element is in vertical orientation. c:type="GtkOverflow"> Defines how content overflowing a given area should be handled. + line="443">Defines how content overflowing a given area should be handled. This is used in [method@Gtk.Widget.set_overflow]. The [property@Gtk.Widget:overflow] property is modeled after the @@ -99752,7 +101533,7 @@ CSS overflow property, but implements it only partially. glib:name="GTK_OVERFLOW_VISIBLE"> No change is applied. Content is drawn at the specified + line="445">No change is applied. Content is drawn at the specified position. glib:name="GTK_OVERFLOW_HIDDEN"> Content is clipped to the bounds of the area. Content + line="447">Content is clipped to the bounds of the area. Content outside the area is not drawn and cannot be interacted with. @@ -99774,10 +101555,12 @@ CSS overflow property, but implements it only partially. glib:get-type="gtk_overlay_get_type"> `GtkOverlay` is a container which contains a single main child, on top -of which it can place “overlay” widgets. + line="34">Places “overlay” widgets on top of a single main child. -![An example GtkOverlay](overlay.png) +<picture> + <source srcset="overlay-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkOverlay" src="overlay.png"> +</picture> The position of each overlay widget is determined by its [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] @@ -99812,19 +101595,19 @@ whose alignments cause them to be positioned at an edge get the style classes Creates a new `GtkOverlay`. + line="420">Creates a new `GtkOverlay`. a new `GtkOverlay` object. + line="425">a new `GtkOverlay` object. Adds @widget to @overlay. + line="433">Adds @widget to @overlay. The widget will be stacked on top of the main widget added with [method@Gtk.Overlay.set_child]. @@ -99840,13 +101623,13 @@ from its [property@Gtk.Widget:halign] and a `GtkOverlay` + line="435">a `GtkOverlay` a `GtkWidget` to be added to the container + line="436">a `GtkWidget` to be added to the container @@ -99856,19 +101639,19 @@ from its [property@Gtk.Widget:halign] and glib:get-property="child"> Gets the child widget of @overlay. + line="609">Gets the child widget of @overlay. the child widget of @overlay + line="615">the child widget of @overlay a `GtkOverlay` + line="611">a `GtkOverlay` @@ -99877,25 +101660,25 @@ from its [property@Gtk.Widget:halign] and c:identifier="gtk_overlay_get_clip_overlay"> Gets whether @widget should be clipped within the parent. + line="554">Gets whether @widget should be clipped within the parent. whether the widget is clipped within the parent. + line="561">whether the widget is clipped within the parent. a `GtkOverlay` + line="556">a `GtkOverlay` an overlay child of `GtkOverlay` + line="557">an overlay child of `GtkOverlay` @@ -99904,26 +101687,26 @@ from its [property@Gtk.Widget:halign] and c:identifier="gtk_overlay_get_measure_overlay"> Gets whether @widget's size is included in the measurement of + line="505">Gets whether @widget's size is included in the measurement of @overlay. whether the widget is measured + line="513">whether the widget is measured a `GtkOverlay` + line="507">a `GtkOverlay` an overlay child of `GtkOverlay` + line="508">an overlay child of `GtkOverlay` @@ -99931,7 +101714,7 @@ from its [property@Gtk.Widget:halign] and Removes an overlay that was added with gtk_overlay_add_overlay(). + line="458">Removes an overlay that was added with gtk_overlay_add_overlay(). @@ -99940,13 +101723,13 @@ from its [property@Gtk.Widget:halign] and a `GtkOverlay` + line="460">a `GtkOverlay` a `GtkWidget` to be removed + line="461">a `GtkWidget` to be removed @@ -99956,7 +101739,7 @@ from its [property@Gtk.Widget:halign] and glib:set-property="child"> Sets the child widget of @overlay. + line="579">Sets the child widget of @overlay. @@ -99965,7 +101748,7 @@ from its [property@Gtk.Widget:halign] and a `GtkOverlay` + line="581">a `GtkOverlay` the child widget + line="582">the child widget @@ -99983,7 +101766,7 @@ from its [property@Gtk.Widget:halign] and c:identifier="gtk_overlay_set_clip_overlay"> Sets whether @widget should be clipped within the parent. + line="530">Sets whether @widget should be clipped within the parent. @@ -99992,19 +101775,19 @@ from its [property@Gtk.Widget:halign] and a `GtkOverlay` + line="532">a `GtkOverlay` an overlay child of `GtkOverlay` + line="533">an overlay child of `GtkOverlay` whether the child should be clipped + line="534">whether the child should be clipped @@ -100013,7 +101796,7 @@ from its [property@Gtk.Widget:halign] and c:identifier="gtk_overlay_set_measure_overlay"> Sets whether @widget is included in the measured size of @overlay. + line="477">Sets whether @widget is included in the measured size of @overlay. The overlay will request the size of the largest child that has this property set to %TRUE. Children who are not included may @@ -100026,19 +101809,19 @@ be drawn outside of @overlay's allocation if they are too large. a `GtkOverlay` + line="479">a `GtkOverlay` an overlay child of `GtkOverlay` + line="480">an overlay child of `GtkOverlay` whether the child should be measured + line="481">whether the child should be measured @@ -100048,17 +101831,15 @@ be drawn outside of @overlay's allocation if they are too large. transfer-ownership="none" setter="set_child" getter="get_child"> - - The main child widget. + line="323">The main child widget. Emitted to determine the position and size of any overlay + line="334">Emitted to determine the position and size of any overlay child widgets. A handler for this signal should fill @allocation with @@ -100075,14 +101856,14 @@ to its contents. %TRUE if the @allocation has been filled + line="356">%TRUE if the @allocation has been filled the child widget to position + line="337">the child widget to position transfer-ownership="none"> return + line="338">return location for the allocation @@ -100107,7 +101888,7 @@ to its contents. glib:type-struct="OverlayLayoutClass"> `GtkOverlayLayout` is the layout manager used by [class@Gtk.Overlay]. + line="33">The layout manager used by [class@Gtk.Overlay]. It places widgets as overlays on top of the main child. @@ -100142,7 +101923,6 @@ properties get documented. - Retrieves whether the child is clipped. @@ -100165,7 +101945,6 @@ properties get documented. - Retrieves whether the child is measured. @@ -100188,7 +101967,6 @@ properties get documented. - Sets whether to clip this child. @@ -100214,7 +101992,6 @@ properties get documented. - Sets whether to measure this child. @@ -100243,10 +102020,6 @@ properties get documented. setter="set_clip_overlay" getter="get_clip_overlay" default-value="FALSE"> - - Whether the child should be clipped to fit the parent's size. @@ -100258,10 +102031,6 @@ properties get documented. setter="set_measure" getter="get_measure" default-value="FALSE"> - - Whether the child size should contribute to the `GtkOverlayLayout`'s @@ -100542,61 +102311,97 @@ measurement. - + The key used by the “Print to file” printer to store whether to collate the +printed pages. + - + The key used by the “Print to file” printer to store the default source. + - + The key used by the “Print to file” printer to store the dither used. + - + The key used by the “Print to file” printer to store whether to print the +output in duplex. + - + The key used by the “Print to file” printer to store the finishings. + - + The key used by the “Print to file” printer to store the media type. + +The set of media types is defined in PWG 5101.1-2002 PWG. + - + The key used by the “Print to file” printer to store the number of pages per +sheet. + - + The key used by the “Print to file” printer to store the number of pages per +sheet in number-up mode. + - + The key used by the “Print to file” printer to store the number of copies. + - + The key used by the “Print to file” printer to store the orientation. + c:type="GTK_PRINT_SETTINGS_OUTPUT_BASENAME"> The key used by the “Print to file” printer to store the file + line="355">The key used by the “Print to file” printer to store the file name of the output without the path to the directory and the file extension. - + - + The key used by the “Print to file” printer to store the output bin. + c:type="GTK_PRINT_SETTINGS_OUTPUT_DIR"> The key used by the “Print to file” printer to store the + line="347">The key used by the “Print to file” printer to store the directory to which the output should be written. - + c:type="GTK_PRINT_SETTINGS_OUTPUT_FILE_FORMAT"> The key used by the “Print to file” printer to store the format + line="364">The key used by the “Print to file” printer to store the format of the output. The supported values are “PS” and “PDF”. - + c:type="GTK_PRINT_SETTINGS_OUTPUT_URI"> The key used by the “Print to file” printer to store the URI + line="372">The key used by the “Print to file” printer to store the URI to which the output should be written. GTK itself supports only “file://” URIs. - + - + The key used by the “Print to file” printer to store the array of page ranges +to print. + - + The key used by the “Print to file” printer to store the set of pages to print. + - + The key used by the “Print to file” printer to store the page format. + - + The key used by the “Print to file” printer to store the page height. + - + The key used by the “Print to file” printer to store the paper width. + - + The key used by the “Print to file” printer to store the printer name. + - + The key used by the “Print to file” printer to store the resolution in lines +per inch. + - + The key used by the “Print to file” printer to store which pages to print. + - + The key used by the “Print to file” printer to store the printing quality. + - + The key used by the “Print to file” printer to store the resolution in DPI. + - + The key used by the “Print to file” printer to store the horizontal +resolution in DPI. + - + The key used by the “Print to file” printer to store the vertical resolution +in DPI. + - + The key used by the “Print to file” printer to store whether to reverse the +order of the printed pages. + - + The key used by the “Print to file” printer to store the scale. + - + The key used by the “Print to file” printer to store whether to print with +colors. + - + The key used by the “Print to file” printer to store 32-bit Windows extra +driver. + - + The key used by the “Print to file” printer to store the 32-bit Windows +driver version. + c:type="GtkPackType"> Represents the packing location of a children in its parent. + line="462">Represents the packing location of a children in its parent. See [class@WindowControls] for example. glib:name="GTK_PACK_START"> The child is packed into the start of the widget + line="464">The child is packed into the start of the widget glib:name="GTK_PACK_END"> The child is packed into the end of the widget + line="465">The child is packed into the end of the widget @@ -100888,8 +102755,7 @@ See [class@WindowControls] for example. glib:type-struct="PadControllerClass"> `GtkPadController` is an event controller for the pads found in drawing -tablets. + line="20">Handles input from the pads found in drawing tablets. Pads are the collection of buttons and tactile sensors often found around the stylus-sensitive area. @@ -100939,7 +102805,7 @@ is required that those are made stateful and accepting this `GVariantType`. Creates a new `GtkPadController` that will associate events from @pad to + line="396">Creates a new `GtkPadController` that will associate events from @pad to actions. A %NULL pad may be provided so the controller manages all pad devices @@ -100957,14 +102823,14 @@ a pad controller to any other type of widget will not have an effect. A newly created `GtkPadController` + line="416">A newly created `GtkPadController` `GActionGroup` to trigger actions from + line="398">`GActionGroup` to trigger actions from allow-none="1"> A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads + line="399">A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads @@ -100981,7 +102847,7 @@ a pad controller to any other type of widget will not have an effect. Adds an individual action to @controller. + line="499">Adds an individual action to @controller. This action will only be activated if the given button/ring/strip number in @index is interacted while the current mode is @mode. -1 may be used @@ -100998,38 +102864,38 @@ feedback. a `GtkPadController` + line="501">a `GtkPadController` the type of pad feature that will trigger this action + line="502">the type of pad feature that will trigger this action the 0-indexed button/ring/strip number that will trigger this action + line="503">the 0-indexed button/ring/strip number that will trigger this action the mode that will trigger this action, or -1 for all modes. + line="504">the mode that will trigger this action, or -1 for all modes. Human readable description of this action, this string should + line="505">Human readable description of this action, this string should be deemed user-visible. action name that will be activated in the `GActionGroup` + line="507">action name that will be activated in the `GActionGroup` @@ -101038,7 +102904,7 @@ feedback. c:identifier="gtk_pad_controller_set_action_entries"> A convenience function to add a group of action entries on + line="474">A convenience function to add a group of action entries on @controller. See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. @@ -101050,13 +102916,13 @@ See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. a `GtkPadController` + line="476">a `GtkPadController` the action entries to set on @controller + line="477">the action entries to set on @controller @@ -101066,7 +102932,7 @@ See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. the number of elements in @entries + line="478">the number of elements in @entries @@ -101075,12 +102941,18 @@ See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. writable="1" construct-only="1" transfer-ownership="none"> + The action group of the controller. + The pad of the controller. @@ -101097,7 +102969,7 @@ See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. c:type="GtkPageOrientation"> See also gtk_print_settings_set_orientation(). + line="699">See also gtk_print_settings_set_orientation(). glib:name="GTK_PAGE_ORIENTATION_PORTRAIT"> Portrait mode. + line="701">Portrait mode. glib:name="GTK_PAGE_ORIENTATION_LANDSCAPE"> Landscape mode. + line="702">Landscape mode. glib:name="GTK_PAGE_ORIENTATION_REVERSE_PORTRAIT"> Reverse portrait mode. + line="703">Reverse portrait mode. glib:name="GTK_PAGE_ORIENTATION_REVERSE_LANDSCAPE"> Reverse landscape mode. + line="704">Reverse landscape mode. A range of pages to print. + line="50">A range of pages to print. See also [method@Gtk.PrintSettings.set_page_ranges]. - + start of page range. + line="52">start of page range. end of page range. + line="53">end of page range. @@ -101161,7 +103033,7 @@ See also [method@Gtk.PrintSettings.set_page_ranges]. c:type="GtkPageSet"> See also gtk_print_job_set_page_set(). + line="615">See also gtk_print_job_set_page_set(). glib:name="GTK_PAGE_SET_ALL"> All pages. + line="617">All pages. glib:name="GTK_PAGE_SET_EVEN"> Even pages. + line="618">Even pages. glib:name="GTK_PAGE_SET_ODD"> Odd pages. + line="619">Odd pages. glib:get-type="gtk_page_setup_get_type"> A `GtkPageSetup` object stores the page size, orientation and margins. + line="29">Stores page size, orientation and margins for printing. The idea is that you can get one of these from the page setup dialog and then pass it to the `GtkPrintOperation` when printing. @@ -102018,10 +103890,13 @@ is dismissed, and also serves as destroy notify for @data. glib:get-type="gtk_page_setup_unix_dialog_get_type"> `GtkPageSetupUnixDialog` implements a page setup dialog for platforms -which don’t provide a native page setup dialog, like Unix. + line="34">Presents a page setup dialog for platforms which don’t provide +a native page setup dialog, like Unix. -![An example GtkPageSetupUnixDialog](pagesetupdialog.png) +<picture> + <source srcset="pagesetupdialog-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPageSetupUnixDialog" src="pagesetupdialog.png"> +</picture> It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing @@ -102040,13 +103915,13 @@ style class `.pagesetup`. Creates a new page setup dialog. + line="771">Creates a new page setup dialog. the new `GtkPageSetupUnixDialog` + line="778">the new `GtkPageSetupUnixDialog` @@ -102056,7 +103931,7 @@ style class `.pagesetup`. allow-none="1"> the title of the dialog + line="773">the title of the dialog allow-none="1"> transient parent of the dialog + line="774">transient parent of the dialog @@ -102074,20 +103949,20 @@ style class `.pagesetup`. c:identifier="gtk_page_setup_unix_dialog_get_page_setup"> Gets the currently selected page setup from the dialog. + line="853">Gets the currently selected page setup from the dialog. the current page setup + line="859">the current page setup a `GtkPageSetupUnixDialog` + line="855">a `GtkPageSetupUnixDialog` @@ -102096,20 +103971,20 @@ style class `.pagesetup`. c:identifier="gtk_page_setup_unix_dialog_get_print_settings"> Gets the current print settings from the dialog. + line="935">Gets the current print settings from the dialog. the current print settings + line="941">the current print settings a `GtkPageSetupUnixDialog` + line="937">a `GtkPageSetupUnixDialog` @@ -102118,7 +103993,7 @@ style class `.pagesetup`. c:identifier="gtk_page_setup_unix_dialog_set_page_setup"> Sets the `GtkPageSetup` from which the page setup + line="834">Sets the `GtkPageSetup` from which the page setup dialog takes its values. @@ -102129,13 +104004,13 @@ dialog takes its values. a `GtkPageSetupUnixDialog` + line="836">a `GtkPageSetupUnixDialog` a `GtkPageSetup` + line="837">a `GtkPageSetup` @@ -102144,7 +104019,7 @@ dialog takes its values. c:identifier="gtk_page_setup_unix_dialog_set_print_settings"> Sets the `GtkPrintSettings` from which the page setup dialog + line="901">Sets the `GtkPrintSettings` from which the page setup dialog takes its values. @@ -102155,7 +104030,7 @@ takes its values. a `GtkPageSetupUnixDialog` + line="903">a `GtkPageSetupUnixDialog` allow-none="1"> a `GtkPrintSettings` + line="904">a `GtkPrintSettings` @@ -102176,7 +104051,7 @@ takes its values. c:type="GtkPanDirection"> Describes the panning direction of a [class@GesturePan]. + line="1075">Describes the panning direction of a [class@GesturePan]. glib:name="GTK_PAN_DIRECTION_LEFT"> panned towards the left + line="1077">panned towards the left glib:name="GTK_PAN_DIRECTION_RIGHT"> panned towards the right + line="1078">panned towards the right glib:name="GTK_PAN_DIRECTION_UP"> panned upwards + line="1079">panned upwards glib:name="GTK_PAN_DIRECTION_DOWN"> panned downwards + line="1080">panned downwards glib:get-type="gtk_paned_get_type"> A widget with two panes, arranged either horizontally or vertically. + line="45">Arranges its children in two panes, horizontally or vertically. -![An example GtkPaned](panes.png) +<picture> + <source srcset="panes-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPaned" src="panes.png"> +</picture> The division between the two panes is adjustable by the user by dragging a handle. @@ -102252,6 +104130,17 @@ If "resize" is false for both children, then this is treated as if The application can set the position of the slider as if it were set by the user, by calling [method@Gtk.Paned.set_position]. +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.Paned::accept-position] +- [signal@Gtk.Paned::cancel-position] +- [signal@Gtk.Paned::cycle-child-focus] +- [signal@Gtk.Paned::cycle-handle-focus] +- [signal@Gtk.Paned::move-handle] +- [signal@Gtk.Paned::toggle-handle-focus] + # CSS nodes ``` @@ -102297,19 +104186,19 @@ gtk_widget_set_size_request (frame2, 50, -1); Creates a new `GtkPaned` widget. + line="1614">Creates a new `GtkPaned` widget. the newly created paned widget + line="1620">the newly created paned widget the paned’s orientation. + line="1616">the paned’s orientation. @@ -102317,22 +104206,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Retrieves the end child of the given `GtkPaned`. + line="1780">Retrieves the end child of the given `GtkPaned`. the end child widget + line="1786">the end child widget a `GtkPaned` + line="1782">a `GtkPaned` @@ -102340,22 +104228,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Obtains the position of the divider between the two panes. + line="1870">Obtains the position of the divider between the two panes. the position of the divider, in pixels + line="1876">the position of the divider, in pixels a `GtkPaned` widget + line="1872">a `GtkPaned` widget @@ -102363,23 +104250,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Returns whether the [property@Gtk.Paned:end-child] can be resized. + line="1817">Returns whether the [property@Gtk.Paned:end-child] can be resized. true if the end child is resizable + line="1823">true if the end child is resizable a `GtkPaned` + line="1819">a `GtkPaned` @@ -102387,23 +104272,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Returns whether the [property@Gtk.Paned:start-child] can be resized. + line="1697">Returns whether the [property@Gtk.Paned:start-child] can be resized. true if the start child is resizable + line="1703">true if the start child is resizable a `GtkPaned` + line="1699">a `GtkPaned` @@ -102411,23 +104294,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Returns whether the [property@Gtk.Paned:end-child] can shrink. + line="1854">Returns whether the [property@Gtk.Paned:end-child] can shrink. true if the end child is shrinkable + line="1860">true if the end child is shrinkable a `GtkPaned` + line="1856">a `GtkPaned` @@ -102435,23 +104316,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Returns whether the [property@Gtk.Paned:start-child] can shrink. + line="1734">Returns whether the [property@Gtk.Paned:start-child] can shrink. true if the start child is shrinkable + line="1740">true if the start child is shrinkable a `GtkPaned` + line="1736">a `GtkPaned` @@ -102459,22 +104338,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Retrieves the start child of the given `GtkPaned`. + line="1660">Retrieves the start child of the given `GtkPaned`. the start child widget + line="1666">the start child widget a `GtkPaned` + line="1662">a `GtkPaned` @@ -102482,22 +104360,21 @@ gtk_widget_set_size_request (frame2, 50, -1); - Gets whether the separator should be wide. + line="2595">Gets whether the separator should be wide. %TRUE if the paned should have a wide handle + line="2601">%TRUE if the paned should have a wide handle a `GtkPaned` + line="2597">a `GtkPaned` @@ -102505,10 +104382,9 @@ gtk_widget_set_size_request (frame2, 50, -1); - Sets the end child of @paned to @child. + line="1750">Sets the end child of @paned to @child. If @child is `NULL`, the existing child will be removed. @@ -102519,7 +104395,7 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="1752">a `GtkPaned` allow-none="1"> the widget to add + line="1753">the widget to add @@ -102536,10 +104412,9 @@ If @child is `NULL`, the existing child will be removed. - Sets the position of the divider between the two panes. + line="1886">Sets the position of the divider between the two panes. @@ -102548,13 +104423,13 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` widget + line="1888">a `GtkPaned` widget pixel position of divider, a negative value means that the position + line="1889">pixel position of divider, a negative value means that the position is unset @@ -102563,11 +104438,9 @@ If @child is `NULL`, the existing child will be removed. - Sets whether the [property@Gtk.Paned:end-child] can be resized. + line="1796">Sets whether the [property@Gtk.Paned:end-child] can be resized. @@ -102576,13 +104449,13 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="1798">a `GtkPaned` true to let the end child be resized + line="1799">true to let the end child be resized @@ -102590,11 +104463,9 @@ If @child is `NULL`, the existing child will be removed. - Sets whether the [property@Gtk.Paned:start-child] can be resized. + line="1676">Sets whether the [property@Gtk.Paned:start-child] can be resized. @@ -102603,13 +104474,13 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="1678">a `GtkPaned` true to let the start child be resized + line="1679">true to let the start child be resized @@ -102617,11 +104488,9 @@ If @child is `NULL`, the existing child will be removed. - Sets whether the [property@Gtk.Paned:end-child] can shrink. + line="1833">Sets whether the [property@Gtk.Paned:end-child] can shrink. @@ -102630,13 +104499,13 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="1835">a `GtkPaned` true to let the end child be shrunk + line="1836">true to let the end child be shrunk @@ -102644,11 +104513,9 @@ If @child is `NULL`, the existing child will be removed. - Sets whether the [property@Gtk.Paned:start-child] can shrink. + line="1713">Sets whether the [property@Gtk.Paned:start-child] can shrink. @@ -102657,13 +104524,13 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="1715">a `GtkPaned` true to let the start child be shrunk + line="1716">true to let the start child be shrunk @@ -102671,10 +104538,9 @@ If @child is `NULL`, the existing child will be removed. - Sets the start child of @paned to @child. + line="1630">Sets the start child of @paned to @child. If @child is `NULL`, the existing child will be removed. @@ -102685,7 +104551,7 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="1632">a `GtkPaned` allow-none="1"> the widget to add + line="1633">the widget to add @@ -102702,10 +104568,9 @@ If @child is `NULL`, the existing child will be removed. - Sets whether the separator should be wide. + line="2568">Sets whether the separator should be wide. @@ -102714,13 +104579,13 @@ If @child is `NULL`, the existing child will be removed. a `GtkPaned` + line="2570">a `GtkPaned` the new value for the [property@Gtk.Paned:wide-handle] property + line="2571">the new value for the [property@Gtk.Paned:wide-handle] property @@ -102730,13 +104595,9 @@ If @child is `NULL`, the existing child will be removed. transfer-ownership="none" setter="set_end_child" getter="get_end_child"> - - The second child. + line="553">The second child. default-value="2147483647"> The largest possible value for the [property@Gtk.Paned:position] + line="472">The largest possible value for the [property@Gtk.Paned:position] property. This property is derived from the size and shrinkability @@ -102756,7 +104617,7 @@ of the widget's children. default-value="0"> The smallest possible value for the [property@Gtk.Paned:position] + line="458">The smallest possible value for the [property@Gtk.Paned:position] property. This property is derived from the size and shrinkability @@ -102769,11 +104630,9 @@ of the widget's children. setter="set_position" getter="get_position" default-value="0"> - - Position of the separator in pixels, from the left/top. + line="438">Position of the separator in pixels, from the left/top. default-value="FALSE"> Whether the [property@Gtk.Paned:position] property has been set. + line="448">Whether the [property@Gtk.Paned:position] property has been set. setter="set_resize_end_child" getter="get_resize_end_child" default-value="TRUE"> - - Determines whether the second child expands and shrinks + line="510">Determines whether the second child expands and shrinks along with the paned widget. @@ -102807,13 +104662,9 @@ along with the paned widget. setter="set_resize_start_child" getter="get_resize_start_child" default-value="TRUE"> - - Determines whether the first child expands and shrinks + line="499">Determines whether the first child expands and shrinks along with the paned widget. @@ -102823,13 +104674,9 @@ along with the paned widget. setter="set_shrink_end_child" getter="get_shrink_end_child" default-value="TRUE"> - - Determines whether the second child can be made smaller + line="532">Determines whether the second child can be made smaller than its requisition. @@ -102839,13 +104686,9 @@ than its requisition. setter="set_shrink_start_child" getter="get_shrink_start_child" default-value="TRUE"> - - Determines whether the first child can be made smaller + line="521">Determines whether the first child can be made smaller than its requisition. @@ -102854,13 +104697,9 @@ than its requisition. transfer-ownership="none" setter="set_start_child" getter="get_start_child"> - - The first child. + line="543">The first child. setter="set_wide_handle" getter="get_wide_handle" default-value="FALSE"> - - Whether the `GtkPaned` should provide a stronger visual separation. + line="486">Whether the `GtkPaned` should provide a stronger visual separation. For example, this could be set when a paned contains two [class@Gtk.Notebook]s, whose tab rows would otherwise merge visually. @@ -102884,7 +104719,7 @@ For example, this could be set when a paned contains two Emitted to accept the current position of the handle when + line="675">Emitted to accept the current position of the handle when moving it using key bindings. This is a [keybinding signal](class.SignalAction.html). @@ -102892,13 +104727,16 @@ This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Return</kbd> or <kbd>Space</kbd>. + whether the position was accepted Emitted to cancel moving the position of the handle using key + line="701">Emitted to cancel moving the position of the handle using key bindings. The position of the handle will be reset to the value prior to @@ -102908,25 +104746,31 @@ This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Escape</kbd>. + whether the position was canceled Emitted to cycle the focus between the children of the paned. + line="566">Emitted to cycle the focus between the children of the paned. This is a [keybinding signal](class.SignalAction.html). The default binding is <kbd>F6</kbd>. + whether the behavior was cycled whether cycling backward or forward + line="569">whether cycling backward or forward @@ -102934,20 +104778,23 @@ The default binding is <kbd>F6</kbd>. Emitted to cycle whether the paned should grab focus to allow + line="648">Emitted to cycle whether the paned should grab focus to allow the user to change position of the handle by using key bindings. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>F8</kbd>. + whether the behavior was cycled whether cycling backward or forward + line="651">whether cycling backward or forward @@ -102955,17 +104802,27 @@ The default binding for this signal is <kbd>F8</kbd>. Emitted to move the handle with key bindings. + line="617">Emitted to move the handle with key bindings. -This is a [keybinding signal](class.SignalAction.html). +This is a [keybinding signal](class.SignalAction.html). + +The default bindings for this signal are +<kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>←</kbd>, +<kbd>Ctrl</kbd>+<kbd>→</kbd>, <kbd>→</kbd>, +<kbd>Ctrl</kbd>+<kbd>↑</kbd>, <kbd>↑</kbd>, +<kbd>Ctrl</kbd>+<kbd>↓</kbd>, <kbd>↓</kbd>, +<kbd>PgUp</kbd>, <kbd>PgDn</kbd>, <kbd>Home</kbd>, <kbd>End</kbd>. + whether the handle was moved a `GtkScrollType` + line="620">a `GtkScrollType` @@ -102973,13 +104830,16 @@ This is a [keybinding signal](class.SignalAction.html). Emitted to accept the current position of the handle and then + line="592">Emitted to accept the current position of the handle and then move focus to the next widget in the focus chain. This is a [keybinding signal](class.SignalAction.html). The default binding is <kbd>Tab</kbd>. + whether handle focus was toggled @@ -103695,9 +105555,12 @@ is owned by GTK and should not be modified. glib:type-struct="PasswordEntryClass"> `GtkPasswordEntry` is an entry that has been tailored for entering secrets. + line="40">A single-line text entry widget for entering passwords and other secrets. -![An example GtkPasswordEntry](password-entry.png) +<picture> + <source srcset="password-entry-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPasswordEntry" src="password-entry.png"> +</picture> It does not show its contents in clear text, does not allow to copy it to the clipboard, and it shows a warning when Caps Lock is engaged. If @@ -103726,7 +105589,7 @@ icon, and possibly other children. # Accessibility -`GtkPasswordEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role. +`GtkPasswordEntry` uses the [enum@Gtk.AccessibleRole.text_box] role. @@ -103735,34 +105598,33 @@ icon, and possibly other children. Creates a `GtkPasswordEntry`. + line="584">Creates a `GtkPasswordEntry`. a new `GtkPasswordEntry` + line="589">a new `GtkPasswordEntry` - Gets the menu model set with gtk_password_entry_set_extra_menu(). + line="720">Gets the menu model set with gtk_password_entry_set_extra_menu(). the menu model + line="726">the menu model a `GtkPasswordEntry` + line="722">a `GtkPasswordEntry` @@ -103770,23 +105632,22 @@ icon, and possibly other children. - Returns whether the entry is showing an icon to + line="652">Returns whether the entry is showing an icon to reveal the contents. %TRUE if an icon is shown + line="659">%TRUE if an icon is shown a `GtkPasswordEntry` + line="654">a `GtkPasswordEntry` @@ -103794,10 +105655,9 @@ reveal the contents. - Sets a menu model to add when constructing + line="669">Sets a menu model to add when constructing the context menu for @entry. @@ -103807,7 +105667,7 @@ the context menu for @entry. a `GtkPasswordEntry` + line="671">a `GtkPasswordEntry` allow-none="1"> a `GMenuModel` + line="672">a `GMenuModel` @@ -103824,10 +105684,9 @@ the context menu for @entry. - Sets whether the entry should have a clickable icon + line="597">Sets whether the entry should have a clickable icon to reveal the contents. Setting this to %FALSE also hides the text again. @@ -103839,13 +105698,13 @@ Setting this to %FALSE also hides the text again. a `GtkPasswordEntry` + line="599">a `GtkPasswordEntry` whether to show the peek icon + line="600">whether to show the peek icon @@ -103856,7 +105715,7 @@ Setting this to %FALSE also hides the text again. default-value="FALSE"> Whether to activate the default widget when Enter is pressed. + line="484">Whether to activate the default widget when Enter is pressed. transfer-ownership="none" setter="set_extra_menu" getter="get_extra_menu"> - - A menu model whose contents will be appended to + line="504">A menu model whose contents will be appended to the context menu. @@ -103880,7 +105735,7 @@ the context menu. default-value="NULL"> The text that will be displayed in the `GtkPasswordEntry` + line="473">The text that will be displayed in the `GtkPasswordEntry` when it is empty and unfocused. @@ -103890,19 +105745,15 @@ when it is empty and unfocused. setter="set_show_peek_icon" getter="get_show_peek_icon" default-value="FALSE"> - - Whether to show an icon for revealing the content. + line="494">Whether to show an icon for revealing the content. Emitted when the entry is activated. + line="518">Emitted when the entry is activated. The keybindings for this signal are all forms of the Enter key. @@ -103959,7 +105810,7 @@ from being swapped to disk. c:type="GtkPickFlags"> Flags that influence the behavior of [method@Widget.pick]. + line="1111">Flags that influence the behavior of [method@Widget.pick]. The default behavior, include widgets that are receiving events + line="1113">The default behavior, include widgets that are receiving events Include widgets that are insensitive + line="1114">Include widgets that are insensitive Include widgets that are marked as non-targetable. See [property@Widget:can-target] + line="1115">Include widgets that are marked as non-targetable. See [property@Widget:can-target] The `GtkPicture` widget displays a `GdkPaintable`. + line="33">Displays a `GdkPaintable`. -![An example GtkPicture](picture.png) +picture> + <source srcset="picture-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPicture" src="picture.png"> +</picture> Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display @@ -104042,7 +105896,7 @@ fill all available space but is instead displayed at its original size. ## Accessibility -`GtkPicture` uses the `GTK_ACCESSIBLE_ROLE_IMG` role. +`GtkPicture` uses the [enum@Gtk.AccessibleRole.img] role. @@ -104050,19 +105904,19 @@ fill all available space but is instead displayed at its original size. Creates a new empty `GtkPicture` widget. + line="501">Creates a new empty `GtkPicture` widget. a newly created `GtkPicture` widget. + line="506">a newly created `GtkPicture` widget. Creates a new `GtkPicture` displaying the given @file. + line="572">Creates a new `GtkPicture` displaying the given @file. If the file isn’t found or can’t be loaded, the resulting `GtkPicture` is empty. @@ -104074,7 +105928,7 @@ then create the `GtkPicture` from the texture. a new `GtkPicture` + line="585">a new `GtkPicture` @@ -104084,7 +105938,7 @@ then create the `GtkPicture` from the texture. allow-none="1"> a `GFile` + line="574">a `GFile` @@ -104093,7 +105947,7 @@ then create the `GtkPicture` from the texture. c:identifier="gtk_picture_new_for_filename"> Creates a new `GtkPicture` displaying the file @filename. + line="597">Creates a new `GtkPicture` displaying the file @filename. This is a utility function that calls [ctor@Gtk.Picture.new_for_file]. See that function for details. @@ -104101,7 +105955,7 @@ See that function for details. a new `GtkPicture` + line="606">a new `GtkPicture` @@ -104111,7 +105965,7 @@ See that function for details. allow-none="1"> a filename + line="599">a filename @@ -104120,7 +105974,7 @@ See that function for details. c:identifier="gtk_picture_new_for_paintable"> Creates a new `GtkPicture` displaying @paintable. + line="514">Creates a new `GtkPicture` displaying @paintable. The `GtkPicture` will track changes to the @paintable and update its size and contents in response to it. @@ -104128,7 +105982,7 @@ its size and contents in response to it. a new `GtkPicture` + line="523">a new `GtkPicture` @@ -104138,7 +105992,7 @@ its size and contents in response to it. allow-none="1"> a `GdkPaintable` + line="516">a `GdkPaintable` @@ -104149,7 +106003,7 @@ its size and contents in response to it. deprecated-version="4.12"> Creates a new `GtkPicture` displaying @pixbuf. + line="535">Creates a new `GtkPicture` displaying @pixbuf. This is a utility function that calls [ctor@Gtk.Picture.new_for_paintable], See that function for details. @@ -104161,7 +106015,7 @@ The pixbuf must not be modified after passing it to this function. a new `GtkPicture` + line="546">a new `GtkPicture` @@ -104171,7 +106025,7 @@ The pixbuf must not be modified after passing it to this function. allow-none="1"> a `GdkPixbuf` + line="537">a `GdkPixbuf` @@ -104180,7 +106034,7 @@ The pixbuf must not be modified after passing it to this function. c:identifier="gtk_picture_new_for_resource"> Creates a new `GtkPicture` displaying the resource at @resource_path. + line="627">Creates a new `GtkPicture` displaying the resource at @resource_path. This is a utility function that calls [ctor@Gtk.Picture.new_for_file]. See that function for details. @@ -104188,7 +106042,7 @@ See that function for details. a new `GtkPicture` + line="636">a new `GtkPicture` @@ -104198,7 +106052,7 @@ See that function for details. allow-none="1"> resource path to play back + line="629">resource path to play back @@ -104206,25 +106060,23 @@ See that function for details. - Gets the alternative textual description of the picture. + line="1108">Gets the alternative textual description of the picture. The returned string will be %NULL if the picture cannot be described textually. the alternative textual description of @self. + line="1116">the alternative textual description of @self. a `GtkPicture` + line="1110">a `GtkPicture` @@ -104232,22 +106084,21 @@ The returned string will be %NULL if the picture cannot be described textually.< - Returns whether the `GtkPicture` respects its contents size. + line="999">Returns whether the `GtkPicture` respects its contents size. %TRUE if the picture can be made smaller than its contents + line="1005">%TRUE if the picture can be made smaller than its contents a `GtkPicture` + line="1001">a `GtkPicture` @@ -104256,24 +106107,23 @@ The returned string will be %NULL if the picture cannot be described textually.< c:identifier="gtk_picture_get_content_fit" glib:get-property="content-fit" version="4.8"> - Returns the fit mode for the content of the `GtkPicture`. + line="1056">Returns the fit mode for the content of the `GtkPicture`. See [enum@Gtk.ContentFit] for details. the content fit mode + line="1064">the content fit mode a `GtkPicture` + line="1058">a `GtkPicture` @@ -104281,10 +106131,9 @@ See [enum@Gtk.ContentFit] for details. - Gets the `GFile` currently displayed if @self is displaying a file. + line="706">Gets the `GFile` currently displayed if @self is displaying a file. If @self is not displaying a file, for example when [method@Gtk.Picture.set_paintable] was used, then %NULL is returned. @@ -104292,14 +106141,14 @@ If @self is not displaying a file, for example when The `GFile` displayed by @self. + line="715">The `GFile` displayed by @self. a `GtkPicture` + line="708">a `GtkPicture` @@ -104309,11 +106158,9 @@ If @self is not displaying a file, for example when glib:get-property="keep-aspect-ratio" deprecated="1" deprecated-version="4.8"> - Returns whether the `GtkPicture` preserves its contents aspect ratio. + line="947">Returns whether the `GtkPicture` preserves its contents aspect ratio. Use [method@Gtk.Picture.get_content_fit] instead. This will now return `FALSE` only if [property@Gtk.Picture:content-fit] is `GTK_CONTENT_FIT_FILL`. Returns `TRUE` otherwise. @@ -104321,14 +106168,14 @@ If @self is not displaying a file, for example when %TRUE if the self tries to keep the contents' aspect ratio + line="953">%TRUE if the self tries to keep the contents' aspect ratio a `GtkPicture` + line="949">a `GtkPicture` @@ -104336,22 +106183,21 @@ If @self is not displaying a file, for example when - Gets the `GdkPaintable` being displayed by the `GtkPicture`. + line="902">Gets the `GdkPaintable` being displayed by the `GtkPicture`. the displayed paintable + line="908">the displayed paintable a `GtkPicture` + line="904">a `GtkPicture` @@ -104359,11 +106205,9 @@ If @self is not displaying a file, for example when - Sets an alternative textual description for the picture contents. + line="1076">Sets an alternative textual description for the picture contents. It is equivalent to the "alt" attribute for images on websites. @@ -104378,7 +106222,7 @@ If the picture cannot be described textually, set this property to %NULL. a `GtkPicture` + line="1078">a `GtkPicture` allow-none="1"> a textual description of the contents + line="1079">a textual description of the contents @@ -104395,10 +106239,9 @@ If the picture cannot be described textually, set this property to %NULL. - If set to %TRUE, the @self can be made smaller than its contents. + line="967">If set to %TRUE, the @self can be made smaller than its contents. The contents will then be scaled down when rendering. @@ -104416,13 +106259,13 @@ because the grow behavior can be controlled via a `GtkPicture` + line="969">a `GtkPicture` if @self can be made smaller than its contents + line="970">if @self can be made smaller than its contents @@ -104431,10 +106274,9 @@ because the grow behavior can be controlled via c:identifier="gtk_picture_set_content_fit" glib:set-property="content-fit" version="4.8"> - Sets how the content should be resized to fit the `GtkPicture`. + line="1015">Sets how the content should be resized to fit the `GtkPicture`. See [enum@Gtk.ContentFit] for details. @@ -104445,13 +106287,13 @@ See [enum@Gtk.ContentFit] for details. a `GtkPicture` + line="1017">a `GtkPicture` the content fit mode + line="1018">the content fit mode @@ -104459,10 +106301,9 @@ See [enum@Gtk.ContentFit] for details. - Makes @self load and display @file. + line="669">Makes @self load and display @file. See [ctor@Gtk.Picture.new_for_file] for details. @@ -104473,7 +106314,7 @@ See [ctor@Gtk.Picture.new_for_file] for details. a `GtkPicture` + line="671">a `GtkPicture` allow-none="1"> a `GFile` + line="672">a `GFile` @@ -104490,7 +106331,7 @@ See [ctor@Gtk.Picture.new_for_file] for details. Makes @self load and display the given @filename. + line="725">Makes @self load and display the given @filename. This is a utility function that calls [method@Gtk.Picture.set_file]. @@ -104501,7 +106342,7 @@ This is a utility function that calls [method@Gtk.Picture.set_file]. a `GtkPicture` + line="727">a `GtkPicture` allow-none="1"> the filename to play + line="728">the filename to play @@ -104520,11 +106361,9 @@ This is a utility function that calls [method@Gtk.Picture.set_file]. glib:set-property="keep-aspect-ratio" deprecated="1" deprecated-version="4.8"> - If set to %TRUE, the @self will render its contents according to + line="918">If set to %TRUE, the @self will render its contents according to their aspect ratio. That means that empty space may show up at the top/bottom or @@ -104544,13 +106383,13 @@ the contents will be stretched over the picture's whole area. a `GtkPicture` + line="920">a `GtkPicture` whether to keep aspect ratio + line="921">whether to keep aspect ratio @@ -104558,10 +106397,9 @@ the contents will be stretched over the picture's whole area. - Makes @self display the given @paintable. + line="841">Makes @self display the given @paintable. If @paintable is %NULL, nothing will be displayed. @@ -104574,7 +106412,7 @@ See [ctor@Gtk.Picture.new_for_paintable] for details. a `GtkPicture` + line="843">a `GtkPicture` allow-none="1"> a `GdkPaintable` + line="844">a `GdkPaintable` @@ -104594,7 +106432,7 @@ See [ctor@Gtk.Picture.new_for_paintable] for details. deprecated-version="4.12"> Sets a `GtkPicture` to show a `GdkPixbuf`. + line="794">Sets a `GtkPicture` to show a `GdkPixbuf`. See [ctor@Gtk.Picture.new_for_pixbuf] for details. @@ -104608,7 +106446,7 @@ This is a utility function that calls [method@Gtk.Picture.set_paintable]. a `GtkPicture` + line="796">a `GtkPicture` allow-none="1"> a `GdkPixbuf` + line="797">a `GdkPixbuf` @@ -104625,7 +106463,7 @@ This is a utility function that calls [method@Gtk.Picture.set_paintable]. Makes @self load and display the resource at the given + line="753">Makes @self load and display the resource at the given @resource_path. This is a utility function that calls [method@Gtk.Picture.set_file]. @@ -104637,7 +106475,7 @@ This is a utility function that calls [method@Gtk.Picture.set_file]. a `GtkPicture` + line="755">a `GtkPicture` allow-none="1"> the resource to set + line="756">the resource to set @@ -104657,13 +106495,9 @@ This is a utility function that calls [method@Gtk.Picture.set_file]. setter="set_alternative_text" getter="get_alternative_text" default-value="NULL"> - - The alternative textual description for the picture. + line="438">The alternative textual description for the picture. setter="set_can_shrink" getter="get_can_shrink" default-value="TRUE"> - - If the `GtkPicture` can be made smaller than the natural size of its contents. + line="463">If the `GtkPicture` can be made smaller than the natural size of its contents. setter="set_content_fit" getter="get_content_fit" default-value="GTK_CONTENT_FIT_CONTAIN"> - - How the content should be resized to fit inside the `GtkPicture`. + line="473">How the content should be resized to fit inside the `GtkPicture`. transfer-ownership="none" setter="set_file" getter="get_file"> - - The `GFile` that is displayed or %NULL if none. + line="428">The `GFile` that is displayed or %NULL if none. setter="set_keep_aspect_ratio" getter="get_keep_aspect_ratio" default-value="TRUE"> - - Whether the GtkPicture will render its contents trying to preserve the aspect + line="448">Whether the GtkPicture will render its contents trying to preserve the aspect ratio. Use [property@Gtk.Picture:content-fit] instead. @@ -104733,13 +106553,9 @@ ratio. transfer-ownership="none" setter="set_paintable" getter="get_paintable"> - - The `GdkPaintable` to be displayed by this `GtkPicture`. + line="418">The `GdkPaintable` to be displayed by this `GtkPicture`. @@ -104810,9 +106626,12 @@ visibility mode for the scrollbars. glib:type-struct="PopoverClass"> `GtkPopover` is a bubble-like context popup. + line="21">Presents a bubble-like popup. -![An example GtkPopover](popover.png) +<picture> + <source srcset="popover-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPopover" src="popover.png"> +</picture> It is primarily meant to provide context-dependent information or options. Popovers are attached to a parent widget. By default, @@ -104831,7 +106650,7 @@ tweak its behavior. ## GtkPopover as menu replacement -`GtkPopover` is often used to replace menus. The best was to do this +`GtkPopover` is often used to replace menus. The best way to do this is to use the [class@Gtk.PopoverMenu] subclass which supports being populated from a `GMenuModel` with [ctor@Gtk.PopoverMenu.new_from_model]. @@ -104856,6 +106675,17 @@ populated from a `GMenuModel` with [ctor@Gtk.PopoverMenu.new_from_model]. </section> ``` +# Shortcuts and Gestures + +`GtkPopover` supports the following keyboard shortcuts: + +- <kbd>Escape</kbd> closes the popover. +- <kbd>Alt</kbd> makes the mnemonics visible. + +The following signals have default keybindings: + +- [signal@Gtk.Popover::activate-default] + # CSS nodes ``` @@ -104896,12 +106726,12 @@ used) and no box-shadow. Creates a new `GtkPopover`. + line="2036">Creates a new `GtkPopover`. the new `GtkPopover` + line="2041">the new `GtkPopover` @@ -104930,10 +106760,9 @@ used) and no box-shadow. - Returns whether the popover is modal. + line="2348">Returns whether the popover is modal. See [method@Gtk.Popover.set_autohide] for the implications of this. @@ -104941,14 +106770,14 @@ implications of this. %TRUE if @popover is modal + line="2357">%TRUE if @popover is modal a `GtkPopover` + line="2350">a `GtkPopover` @@ -104956,22 +106785,21 @@ implications of this. - Returns whether the popover will close after a modal child is closed. + line="2614">Returns whether the popover will close after a modal child is closed. %TRUE if @popover will close after a modal child. + line="2620">%TRUE if @popover will close after a modal child. a `GtkPopover` + line="2616">a `GtkPopover` @@ -104979,22 +106807,21 @@ implications of this. - Gets the child widget of @popover. + line="2079">Gets the child widget of @popover. the child widget of @popover + line="2085">the child widget of @popover a `GtkPopover` + line="2081">a `GtkPopover` @@ -105002,23 +106829,22 @@ implications of this. - Gets whether this popover is showing an arrow + line="2469">Gets whether this popover is showing an arrow pointing at the widget that it is relative to. whether the popover has an arrow + line="2476">whether the popover has an arrow a `GtkPopover` + line="2471">a `GtkPopover` @@ -105026,16 +106852,14 @@ pointing at the widget that it is relative to. - Gets whether mnemonics are visible. + line="2518">Gets whether mnemonics are visible. %TRUE if mnemonics are supposed to be visible + line="2524">%TRUE if mnemonics are supposed to be visible in this popover @@ -105043,7 +106867,7 @@ pointing at the widget that it is relative to. a `GtkPopover` + line="2520">a `GtkPopover` @@ -105051,7 +106875,7 @@ pointing at the widget that it is relative to. Gets the offset previous set with [method@Gtk.Popover.set_offset()]. + line="2567">Gets the offset previous set with [method@Gtk.Popover.set_offset()]. @@ -105060,7 +106884,7 @@ pointing at the widget that it is relative to. a `GtkPopover` + line="2569">a `GtkPopover` allow-none="1"> a location for the x_offset + line="2570">a location for the x_offset allow-none="1"> a location for the y_offset + line="2571">a location for the y_offset @@ -105090,10 +106914,9 @@ pointing at the widget that it is relative to. - Gets the rectangle that the popover points to. + line="2214">Gets the rectangle that the popover points to. If a rectangle to point to has been set, this function will return %TRUE and fill in @rect with such rectangle, otherwise @@ -105103,14 +106926,14 @@ widget coordinates. %TRUE if a rectangle to point to was set. + line="2226">%TRUE if a rectangle to point to was set. a `GtkPopover` + line="2216">a `GtkPopover` transfer-ownership="none"> location to store the rectangle + line="2217">location to store the rectangle @@ -105127,22 +106950,21 @@ widget coordinates. - Returns the preferred position of @popover. + line="2295">Returns the preferred position of @popover. The preferred position. + line="2301">The preferred position. a `GtkPopover` + line="2297">a `GtkPopover` @@ -105150,7 +106972,7 @@ widget coordinates. Pops @popover down. + line="2414">Pops @popover down. This may have the side-effect of closing a parent popover as well. See [property@Gtk.Popover:cascade-popdown]. @@ -105162,7 +106984,7 @@ as well. See [property@Gtk.Popover:cascade-popdown]. a `GtkPopover` + line="2416">a `GtkPopover` @@ -105170,7 +106992,7 @@ as well. See [property@Gtk.Popover:cascade-popdown]. Pops @popover up. + line="2369">Pops @popover up. @@ -105179,7 +107001,7 @@ as well. See [property@Gtk.Popover:cascade-popdown]. a `GtkPopover` + line="2371">a `GtkPopover` @@ -105187,7 +107009,7 @@ as well. See [property@Gtk.Popover:cascade-popdown]. Allocate a size for the `GtkPopover`. + line="656">Allocate a size for the `GtkPopover`. This function needs to be called in size-allocate by widgets who have a `GtkPopover` as child. When using a layout manager, @@ -105202,7 +107024,7 @@ To make a popover appear on screen, use [method@Gtk.Popover.popup]. a `GtkPopover` + line="658">a `GtkPopover` @@ -105210,10 +107032,9 @@ To make a popover appear on screen, use [method@Gtk.Popover.popup]. - Sets whether @popover is modal. + line="2313">Sets whether @popover is modal. A modal popover will grab the keyboard focus on it when being displayed. Focus will wrap around within the popover. Clicking @@ -105230,13 +107051,13 @@ popup to be hidden. a `GtkPopover` + line="2315">a `GtkPopover` %TRUE to dismiss the popover on outside clicks + line="2316">%TRUE to dismiss the popover on outside clicks @@ -105244,10 +107065,9 @@ popup to be hidden. - If @cascade_popdown is %TRUE, the popover will be + line="2591">If @cascade_popdown is %TRUE, the popover will be closed when a child modal popover is closed. If %FALSE, @popover will stay visible. @@ -105259,13 +107079,13 @@ If %FALSE, @popover will stay visible. A `GtkPopover` + line="2593">A `GtkPopover` %TRUE if the popover should follow a child closing + line="2594">%TRUE if the popover should follow a child closing @@ -105273,10 +107093,9 @@ If %FALSE, @popover will stay visible. - Sets the child widget of @popover. + line="2049">Sets the child widget of @popover. @@ -105285,7 +107104,7 @@ If %FALSE, @popover will stay visible. a `GtkPopover` + line="2051">a `GtkPopover` allow-none="1"> the child widget + line="2052">the child widget @@ -105302,10 +107121,9 @@ If %FALSE, @popover will stay visible. - Sets the default widget of a `GtkPopover`. + line="2098">Sets the default widget of a `GtkPopover`. The default widget is the widget that’s activated when the user presses Enter in a dialog (for example). This function sets or @@ -105318,7 +107136,7 @@ unsets the default widget for a `GtkPopover`. a `GtkPopover` + line="2100">a `GtkPopover` allow-none="1"> a child widget of @popover to set as + line="2101">a child widget of @popover to set as the default, or %NULL to unset the default widget for the popover @@ -105336,10 +107154,9 @@ unsets the default widget for a `GtkPopover`. - Sets whether this popover should draw an arrow + line="2444">Sets whether this popover should draw an arrow pointing at the widget it is relative to. @@ -105349,13 +107166,13 @@ pointing at the widget it is relative to. a `GtkPopover` + line="2446">a `GtkPopover` %TRUE to draw an arrow + line="2447">%TRUE to draw an arrow @@ -105363,11 +107180,9 @@ pointing at the widget it is relative to. - Sets whether mnemonics should be visible. + line="2488">Sets whether mnemonics should be visible. @@ -105376,13 +107191,13 @@ pointing at the widget it is relative to. a `GtkPopover` + line="2490">a `GtkPopover` the new value + line="2491">the new value @@ -105390,7 +107205,7 @@ pointing at the widget it is relative to. Sets the offset to use when calculating the position + line="2537">Sets the offset to use when calculating the position of the popover. These values are used when preparing the [struct@Gdk.PopupLayout] @@ -105403,19 +107218,19 @@ for positioning the popover. a `GtkPopover` + line="2539">a `GtkPopover` the x offset to adjust the position by + line="2540">the x offset to adjust the position by the y offset to adjust the position by + line="2541">the y offset to adjust the position by @@ -105423,10 +107238,9 @@ for positioning the popover. - Sets the rectangle that @popover points to. + line="2181">Sets the rectangle that @popover points to. This is in the coordinate space of the @popover parent. @@ -105437,7 +107251,7 @@ This is in the coordinate space of the @popover parent. a `GtkPopover` + line="2183">a `GtkPopover` allow-none="1"> rectangle to point to + line="2184">rectangle to point to @@ -105454,10 +107268,9 @@ This is in the coordinate space of the @popover parent. - Sets the preferred position for @popover to appear. + line="2259">Sets the preferred position for @popover to appear. If the @popover is currently visible, it will be immediately updated. @@ -105473,13 +107286,13 @@ on lack of space (eg. if close to the window edges), the a `GtkPopover` + line="2261">a `GtkPopover` preferred popover position + line="2262">preferred popover position @@ -105490,13 +107303,9 @@ on lack of space (eg. if close to the window edges), the setter="set_autohide" getter="get_autohide" default-value="TRUE"> - - Whether to dismiss the popover on outside clicks. + line="1916">Whether to dismiss the popover on outside clicks. - - Whether the popover pops down after a child popover. + line="1966">Whether the popover pops down after a child popover. This is used to implement the expected behavior of submenus. @@ -105521,22 +107326,18 @@ This is used to implement the expected behavior of submenus. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="1956">The child widget. - The default widget inside the popover. + line="1926">The default widget inside the popover. setter="set_has_arrow" getter="get_has_arrow" default-value="TRUE"> - - Whether to draw an arrow. + line="1936">Whether to draw an arrow. setter="set_mnemonics_visible" getter="get_mnemonics_visible" default-value="FALSE"> - - Whether mnemonics are currently visible in this popover. + line="1946">Whether mnemonics are currently visible in this popover. transfer-ownership="none" setter="set_pointing_to" getter="get_pointing_to"> - - Rectangle in the parent widget that the popover points to. + line="1896">Rectangle in the parent widget that the popover points to. setter="set_position" getter="get_position" default-value="GTK_POS_BOTTOM"> - - How to place the popover, relative to its parent. + line="1906">How to place the popover, relative to its parent. @@ -105604,9 +107389,11 @@ This is used to implement the expected behavior of submenus. Emitted whend the user activates the default widget. + line="1996">Emitted whend the user activates the default widget. -This is a [keybinding signal](class.SignalAction.html). +This is a [keybinding signal](class.SignalAction.html). + +The default binding for this signal is <kbd>Enter</kbd>. @@ -105614,7 +107401,7 @@ This is a [keybinding signal](class.SignalAction.html). Emitted when the popover is closed. + line="1980">Emitted when the popover is closed. @@ -105667,14 +107454,17 @@ This is a [keybinding signal](class.SignalAction.html). glib:get-type="gtk_popover_menu_get_type"> `GtkPopoverMenu` is a subclass of `GtkPopover` that implements menu -behavior. + line="41">A subclass of `GtkPopover` that implements menu behavior. -![An example GtkPopoverMenu](menu.png) +<picture> + <source srcset="menu-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPopoverMenu" src="menu.png"> +</picture> `GtkPopoverMenu` treats its children like menus and allows switching between them. It can open submenus as traditional, nested submenus, or in a more touch-friendly sliding fashion. +The property [property@Gtk.PopoverMenu:flags] controls this appearance. `GtkPopoverMenu` is meant to be used primarily with menu models, using [ctor@Gtk.PopoverMenu.new_from_model]. If you need to put @@ -105753,9 +107543,15 @@ The following attributes are used when constructing submenus: Menu items will also show accelerators, which are usually associated with actions via [method@Gtk.Application.set_accels_for_action], -[id@gtk_widget_class_add_binding_action] or +[method@WidgetClass.add_binding_action] or [method@Gtk.ShortcutController.add_shortcut]. +# Shortcuts and Gestures + +`GtkPopoverMenu` supports the following keyboard shortcuts: + +- <kbd>Space</kbd> activates the default widget. + # CSS Nodes `GtkPopoverMenu` is just a subclass of `GtkPopover` that adds custom content @@ -105771,11 +107567,10 @@ Other things that may be of interest to style in menus include `label` nodes. # Accessibility -`GtkPopoverMenu` uses the %GTK_ACCESSIBLE_ROLE_MENU role, and its -items use the %GTK_ACCESSIBLE_ROLE_MENU_ITEM, -%GTK_ACCESSIBLE_ROLE_MENU_ITEM_CHECKBOX or -%GTK_ACCESSIBLE_ROLE_MENU_ITEM_RADIO roles, depending on the -action they are connected to. +`GtkPopoverMenu` uses the [enum@Gtk.AccessibleRole.menu] role, and its +items use the [enum@Gtk.AccessibleRole.menu_item], +[enum@Gtk.AccessibleRole.checkbox] or [enum@Gtk.AccessibleRole.menu_item_radio] +roles, depending on the action they are connected to. @@ -105785,7 +107580,7 @@ action they are connected to. c:identifier="gtk_popover_menu_new_from_model"> Creates a `GtkPopoverMenu` and populates it according to @model. + line="769">Creates a `GtkPopoverMenu` and populates it according to @model. The created buttons are connected to actions found in the `GtkApplicationWindow` to which the popover belongs - typically @@ -105802,7 +107597,7 @@ to control this. the new `GtkPopoverMenu` + line="787">the new `GtkPopoverMenu` @@ -105812,7 +107607,7 @@ to control this. allow-none="1"> a `GMenuModel` + line="771">a `GMenuModel` @@ -105821,35 +107616,31 @@ to control this. c:identifier="gtk_popover_menu_new_from_model_full"> Creates a `GtkPopoverMenu` and populates it according to @model. + line="796">Creates a `GtkPopoverMenu` and populates it according to @model. The created buttons are connected to actions found in the action groups that are accessible from the parent widget. This includes the `GtkApplicationWindow` to which the popover belongs. Actions can also be added using [method@Gtk.Widget.insert_action_group] -on the parent widget or on any of its parent widgets. - -The only flag that is supported currently is -%GTK_POPOVER_MENU_NESTED, which makes GTK create traditional, -nested submenus instead of the default sliding submenus. - +on the parent widget or on any of its parent widgets. + the new `GtkPopoverMenu` + line="809">the new `GtkPopoverMenu` a `GMenuModel` + line="798">a `GMenuModel` flags that affect how the menu is created + line="799">flags that affect how the menu is created @@ -105857,57 +107648,79 @@ nested submenus instead of the default sliding submenus. Adds a custom widget to a generated menu. + line="915">Adds a custom widget to a generated menu. For this to work, the menu model of @popover must have an item with a `custom` attribute that matches @id. - + %TRUE if @id was found and the widget added + line="926">%TRUE if @id was found and the widget added a `GtkPopoverMenu` + line="917">a `GtkPopoverMenu` the `GtkWidget` to add + line="918">the `GtkWidget` to add the ID to insert @child at + line="919">the ID to insert @child at + + Returns the flags that @popover uses to create/display a menu from its model. + + + the `GtkPopoverMenuFlags` + + + + + a `GtkPopoverMenu` + + + + - Returns the menu model used to populate the popover. - + line="881">Returns the menu model used to populate the popover. + the menu model of @popover + line="887">the menu model of @popover a `GtkPopoverMenu` + line="883">a `GtkPopoverMenu` @@ -105915,42 +107728,70 @@ an item with a `custom` attribute that matches @id. Removes a widget that has previously been added with + line="941">Removes a widget that has previously been added with [method@Gtk.PopoverMenu.add_child()] - + %TRUE if the widget was removed + line="949">%TRUE if the widget was removed a `GtkPopoverMenu` + line="943">a `GtkPopoverMenu` the `GtkWidget` to remove + line="944">the `GtkWidget` to remove + + Sets the flags that @popover uses to create/display a menu from its model. + +If a model is set and the flags change, contents are rebuilt, so if setting +properties individually, set flags before model to avoid a redundant rebuild. + + + + + + + a `GtkPopoverMenu` + + + + a set of `GtkPopoverMenuFlags` + + + + - Sets a new menu model on @popover. + line="826">Sets a new menu model on @popover. The existing contents of @popover are removed, and the @popover is populated with new contents according to @model. - + @@ -105958,7 +107799,7 @@ to @model. a `GtkPopoverMenu` + line="828">a `GtkPopoverMenu` allow-none="1"> a `GMenuModel` + line="829">a `GMenuModel` + + The flags that @popover uses to create/display a menu from its model. + +If a model is set and the flags change, contents are rebuilt, so if setting +properties individually, set flags before model to avoid a redundant rebuild. + + - - The model from which the menu is made. + line="622">The model from which the menu is made. default-value="NULL"> The name of the visible submenu. + line="611">The name of the visible submenu. @@ -106004,10 +107856,12 @@ to @model. glib:get-type="gtk_popover_menu_bar_get_type"> `GtkPopoverMenuBar` presents a horizontal bar of items that pop -up popover menus when clicked. + line="21">Presents a horizontal bar of items that pop up menus when clicked. -![An example GtkPopoverMenuBar](menubar.png) +<picture> + <source srcset="menubar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPopoverMenuBar" src="menubar.png"> +</picture> The only way to create instances of `GtkPopoverMenuBar` is from a `GMenuModel`. @@ -106030,9 +107884,9 @@ style class. # Accessibility -`GtkPopoverMenuBar` uses the %GTK_ACCESSIBLE_ROLE_MENU_BAR role, -the menu items use the %GTK_ACCESSIBLE_ROLE_MENU_ITEM role and -the menus use the %GTK_ACCESSIBLE_ROLE_MENU role. +`GtkPopoverMenuBar` uses the [enum@Gtk.AccessibleRole.menu_bar] role, +the menu items use the [enum@Gtk.AccessibleRole.menu_item] role and +the menus use the [enum@Gtk.AccessibleRole.menu] role. @@ -106040,12 +107894,12 @@ the menus use the %GTK_ACCESSIBLE_ROLE_MENU role. c:identifier="gtk_popover_menu_bar_new_from_model"> Creates a `GtkPopoverMenuBar` from a `GMenuModel`. + line="685">Creates a `GtkPopoverMenuBar` from a `GMenuModel`. a new `GtkPopoverMenuBar` + line="691">a new `GtkPopoverMenuBar` @@ -106055,7 +107909,7 @@ the menus use the %GTK_ACCESSIBLE_ROLE_MENU role. allow-none="1"> a `GMenuModel` + line="687">a `GMenuModel` @@ -106063,7 +107917,7 @@ the menus use the %GTK_ACCESSIBLE_ROLE_MENU role. Adds a custom widget to a generated menubar. + line="769">Adds a custom widget to a generated menubar. For this to work, the menu model of @bar must have an item with a `custom` attribute that matches @id. @@ -106071,26 +107925,26 @@ item with a `custom` attribute that matches @id. %TRUE if @id was found and the widget added + line="780">%TRUE if @id was found and the widget added a `GtkPopoverMenuBar` + line="771">a `GtkPopoverMenuBar` the `GtkWidget` to add + line="772">the `GtkWidget` to add the ID to insert @child at + line="773">the ID to insert @child at @@ -106098,22 +107952,21 @@ item with a `custom` attribute that matches @id. - Returns the model from which the contents of @bar are taken. + line="744">Returns the model from which the contents of @bar are taken. a `GMenuModel` + line="750">a `GMenuModel` a `GtkPopoverMenuBar` + line="746">a `GtkPopoverMenuBar` @@ -106122,26 +107975,26 @@ item with a `custom` attribute that matches @id. c:identifier="gtk_popover_menu_bar_remove_child"> Removes a widget that has previously been added with + line="806">Removes a widget that has previously been added with gtk_popover_menu_bar_add_child(). %TRUE if the widget was removed + line="814">%TRUE if the widget was removed a `GtkPopoverMenuBar` + line="808">a `GtkPopoverMenuBar` the `GtkWidget` to remove + line="809">the `GtkWidget` to remove @@ -106149,10 +108002,9 @@ gtk_popover_menu_bar_add_child(). - Sets a menu model from which @bar should take + line="701">Sets a menu model from which @bar should take its contents. @@ -106162,7 +108014,7 @@ its contents. a `GtkPopoverMenuBar` + line="703">a `GtkPopoverMenuBar` allow-none="1"> a `GMenuModel` + line="704">a `GMenuModel` @@ -106181,13 +108033,9 @@ its contents. transfer-ownership="none" setter="set_menu_model" getter="get_menu_model"> - - The `GMenuModel` from which the menu bar is created. + line="630">The `GMenuModel` from which the menu bar is created. The model should only contain submenus as toplevel elements. @@ -106198,19 +108046,28 @@ The model should only contain submenus as toplevel elements. glib:get-type="gtk_popover_menu_flags_get_type" c:type="GtkPopoverMenuFlags"> Flags that affect how popover menus are created from -a menu model. + filename="gtk/gtkenums.h" + line="1919">Flags that affect how [class@Gtk.PopoverMenu] widgets built from +a [class@Gio.MenuModel] are created and displayed. + + Submenus are presented as sliding submenus that replace the main menu. + Create submenus as nested - popovers. Without this flag, submenus are created as - sliding pages that replace the main menu. + filename="gtk/gtkenums.h" + line="1921">Submenus are presented as traditional, nested + popovers. c:type="GtkPositionType"> Describes which edge of a widget a certain feature is positioned at. + line="477">Describes which edge of a widget a certain feature is positioned at. For examples, see the tabs of a [class@Notebook], or the label of a [class@Scale]. @@ -106230,7 +108087,7 @@ of a [class@Scale]. glib:name="GTK_POS_LEFT"> The feature is at the left edge. + line="479">The feature is at the left edge. glib:name="GTK_POS_RIGHT"> The feature is at the right edge. + line="480">The feature is at the right edge. glib:name="GTK_POS_TOP"> The feature is at the top edge. + line="481">The feature is at the top edge. glib:name="GTK_POS_BOTTOM"> The feature is at the bottom edge. + line="482">The feature is at the bottom edge. + A print backend. glib:get-type="gtk_print_context_get_type"> A `GtkPrintContext` encapsulates context information that is required when + line="23">Encapsulates context information that is required when drawing pages for printing. This includes the cairo context and important parameters like page size @@ -106741,13 +108601,694 @@ case. + + Asynchronous API to present a print dialog to the user. + +`GtkPrintDialog` collects the arguments that are needed to present + the dialog, such as a title for the dialog and whether it should + be modal. + +The dialog is shown with the [method@Gtk.PrintDialog.setup] function. + +The actual printing can be done with [method@Gtk.PrintDialog.print] or +[method@Gtk.PrintDialog.print_file]. These APIs follows the GIO async pattern, +and the results can be obtained by calling the corresponding finish methods. + + + Creates a new `GtkPrintDialog` object. + + + the new `GtkPrintDialog` + + + + + Returns the label that will be shown on the +accept button of the print dialog. + + + the accept label + + + + + a `GtkPrintDialog` + + + + + + Returns whether the print dialog blocks +interaction with the parent window while +it is presented. + + + whether the print dialog is modal + + + + + a `GtkPrintDialog` + + + + + + Returns the page setup. + + + the page setup + + + + + a `GtkPrintDialog` + + + + + + Returns the print settings for the print dialog. + + + the settings + + + + + a `GtkPrintDialog` + + + + + + Returns the title that will be shown on the +print dialog. + + + the title + + + + + a `GtkPrintDialog` + + + + + + This function prints content from a stream. + +If you pass `NULL` as @setup, then this method will present a print dialog. +Otherwise, it will attempt to print directly, without user interaction. + +The @callback will be called when the printing is done. + + + + + + + a `GtkPrintDialog` + + + + the parent `GtkWindow` + + + + the `GtkPrintSetup` to use + + + + a `GCancellable` to cancel the operation + + + + a callback to call when the + operation is complete + + + + data to pass to @callback + + + + + + This function prints a file. + +If you pass `NULL` as @setup, then this method will present a print dialog. +Otherwise, it will attempt to print directly, without user interaction. + + + + + + + a `GtkPrintDialog` + + + + the parent `GtkWindow` + + + + the `GtkPrintSetup` to use + + + + the `GFile` to print + + + + a `GCancellable` to cancel the operation + + + + a callback to call when the + operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.PrintDialog.print_file] call and +returns the results. + + + Whether the call was successful + + + + + a `GtkPrintDialog` + + + + a `GAsyncResult` + + + + + + Finishes the [method@Gtk.PrintDialog.print] call and +returns the results. + +If the call was successful, the content to be printed should be +written to the returned output stream. Otherwise, `NULL` is returned. + +The overall results of the print operation will be returned in the +[method@Gio.OutputStream.close] call, so if you are interested in the +results, you need to explicitly close the output stream (it will be +closed automatically if you just unref it). Be aware that the close +call may not be instant as it operation will for the printer to finish +printing. + + + a [class@Gio.OutputStream] + + + + + a `GtkPrintDialog` + + + + a `GAsyncResult` + + + + + + Sets the label that will be shown on the +accept button of the print dialog shown for +[method@Gtk.PrintDialog.setup]. + + + + + + + a `GtkPrintDialog` + + + + the new accept label + + + + + + Sets whether the print dialog blocks +interaction with the parent window while +it is presented. + + + + + + + a `GtkPrintDialog` + + + + the new value + + + + + + Set the page setup for the print dialog. + + + + + + + a `GtkPrintDialog` + + + + the new page setup + + + + + + Sets the print settings for the print dialog. + + + + + + + a `GtkPrintDialog` + + + + the new print settings + + + + + + Sets the title that will be shown on the print dialog. + + + + + + + a `GtkPrintDialog` + + + + the new title + + + + + + This function presents a print dialog to let the user select a printer, +and set up print settings and page setup. + +The @callback will be called when the dialog is dismissed. +The obtained [struct@Gtk.PrintSetup] can then be passed +to [method@Gtk.PrintDialog.print] or [method@Gtk.PrintDialog.print_file]. + +One possible use for this method is to have the user select a printer, +then show a page setup UI in the application (e.g. to arrange images +on a page), then call [method@Gtk.PrintDialog.print] on @self +to do the printing without further user interaction. + + + + + + + a `GtkPrintDialog` + + + + the parent `GtkWindow` + + + + a `GCancellable` to cancel the operation + + + + a callback to call when the + operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.PrintDialog.setup] call. + +If the call was successful, it returns a [struct@Gtk.PrintSetup] +which contains the print settings and page setup information that +will be used to print. + + + The `GtkPrintSetup` object that resulted from the call, + or `NULL` if the call was not successful + + + + + a `GtkPrintDialog` + + + + a `GAsyncResult` + + + + + + A label that may be shown on the accept button of a print dialog +that is presented by [method@Gtk.PrintDialog.setup]. + + + + Whether the print dialog is modal. + + + + The page setup to use. + + + + The print settings to use. + + + + A title that may be shown on the print dialog that is +presented by [method@Gtk.PrintDialog.setup]. + + + + + + + + + See also gtk_print_settings_set_duplex(). + line="733">See also gtk_print_settings_set_duplex(). glib:name="GTK_PRINT_DUPLEX_SIMPLEX"> No duplex. + line="735">No duplex. glib:name="GTK_PRINT_DUPLEX_HORIZONTAL"> Horizontal duplex. + line="736">Horizontal duplex. glib:name="GTK_PRINT_DUPLEX_VERTICAL"> Vertical duplex. + line="737">Vertical duplex. Registers an error quark for `GtkPrintOperation` if necessary. + line="165">Registers an error quark for `GtkPrintOperation` if necessary. The error quark used for `GtkPrintOperation` errors. + line="170">The error quark used for `GtkPrintOperation` errors. @@ -106842,7 +109383,7 @@ using the GTK printing support. glib:get-type="gtk_print_job_get_type"> A `GtkPrintJob` object represents a job that is sent to a printer. + line="18">Represents a job that is sent to a printer. You only need to deal directly with print jobs if you use the non-portable [class@Gtk.PrintUnixDialog] API. @@ -106893,19 +109434,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets whether this job is printed collated. + line="945">Gets whether this job is printed collated. whether the job is printed collated + line="951">whether the job is printed collated a `GtkPrintJob` + line="947">a `GtkPrintJob` @@ -106913,19 +109454,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets the n-up setting for this job. + line="861">Gets the n-up setting for this job. the n-up setting + line="867">the n-up setting a `GtkPrintJob` + line="863">a `GtkPrintJob` @@ -106934,19 +109475,19 @@ via [method@Gtk.PrintJob.set_source_file]. c:identifier="gtk_print_job_get_n_up_layout"> Gets the n-up layout setting for this job. + line="889">Gets the n-up layout setting for this job. the n-up layout + line="895">the n-up layout a `GtkPrintJob` + line="891">a `GtkPrintJob` @@ -106955,19 +109496,19 @@ via [method@Gtk.PrintJob.set_source_file]. c:identifier="gtk_print_job_get_num_copies"> Gets the number of copies of this job. + line="802">Gets the number of copies of this job. the number of copies + line="808">the number of copies a `GtkPrintJob` + line="804">a `GtkPrintJob` @@ -106976,12 +109517,12 @@ via [method@Gtk.PrintJob.set_source_file]. c:identifier="gtk_print_job_get_page_ranges"> Gets the page ranges for this job. + line="737">Gets the page ranges for this job. a pointer to an + line="744">a pointer to an array of `GtkPageRange` structs @@ -106991,7 +109532,7 @@ via [method@Gtk.PrintJob.set_source_file]. a `GtkPrintJob` + line="739">a `GtkPrintJob` transfer-ownership="full"> return location for the number of ranges + line="740">return location for the number of ranges @@ -107008,19 +109549,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets the `GtkPageSet` setting for this job. + line="774">Gets the `GtkPageSet` setting for this job. the `GtkPageSet` setting + line="780">the `GtkPageSet` setting a `GtkPrintJob` + line="776">a `GtkPrintJob` @@ -107028,19 +109569,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets the `GtkPrintPages` setting for this job. + line="709">Gets the `GtkPrintPages` setting for this job. the `GtkPrintPages` setting + line="715">the `GtkPrintPages` setting a `GtkPrintJob` + line="711">a `GtkPrintJob` @@ -107048,7 +109589,6 @@ via [method@Gtk.PrintJob.set_source_file]. - Gets the `GtkPrinter` of the print job. @@ -107071,19 +109611,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets whether this job is printed reversed. + line="973">Gets whether this job is printed reversed. whether the job is printed reversed. + line="979">whether the job is printed reversed. a `GtkPrintJob` + line="975">a `GtkPrintJob` @@ -107091,19 +109631,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets whether the job is printed rotated. + line="917">Gets whether the job is printed rotated. whether the job is printed rotated + line="923">whether the job is printed rotated a `GtkPrintJob` + line="919">a `GtkPrintJob` @@ -107111,19 +109651,19 @@ via [method@Gtk.PrintJob.set_source_file]. Gets the scale for this job. + line="830">Gets the scale for this job. the scale + line="836">the scale a `GtkPrintJob` + line="832">a `GtkPrintJob` @@ -107131,7 +109671,6 @@ via [method@Gtk.PrintJob.set_source_file]. - Gets the `GtkPrintSettings` of the print job. @@ -107197,7 +109736,6 @@ the print job should be rendered. - Gets the job title. @@ -107220,25 +109758,23 @@ the print job should be rendered. - Returns whether jobs will be tracked after printing. + line="585">Returns whether jobs will be tracked after printing. For details, see [method@Gtk.PrintJob.set_track_print_status]. %TRUE if print job status will be reported after printing + line="593">%TRUE if print job status will be reported after printing a `GtkPrintJob` + line="587">a `GtkPrintJob` @@ -107246,7 +109782,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sends the print job off to the printer. + line="680">Sends the print job off to the printer. @@ -107255,7 +109791,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="682">a `GtkPrintJob` destroy="2"> function to call when the job completes or an error occurs + line="683">function + to call when the job completes or an error occurs @@ -107275,13 +109812,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. allow-none="1"> user data that gets passed to @callback + line="685">user data that gets passed to @callback destroy notify for @user_data + line="686">destroy notify for @user_data @@ -107289,7 +109826,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets whether this job is printed collated. + line="959">Sets whether this job is printed collated. @@ -107298,13 +109835,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="961">a `GtkPrintJob` whether the job is printed collated + line="962">whether the job is printed collated @@ -107312,7 +109849,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets the n-up setting for this job. + line="875">Sets the n-up setting for this job. @@ -107321,13 +109858,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="877">a `GtkPrintJob` the n-up value + line="878">the n-up value @@ -107336,7 +109873,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. c:identifier="gtk_print_job_set_n_up_layout"> Sets the n-up layout setting for this job. + line="903">Sets the n-up layout setting for this job. @@ -107345,13 +109882,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="905">a `GtkPrintJob` the n-up layout setting + line="906">the n-up layout setting @@ -107360,7 +109897,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. c:identifier="gtk_print_job_set_num_copies"> Sets the number of copies for this job. + line="816">Sets the number of copies for this job. @@ -107369,13 +109906,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="818">a `GtkPrintJob` the number of copies + line="819">the number of copies @@ -107384,7 +109921,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. c:identifier="gtk_print_job_set_page_ranges"> Sets the page ranges for this job. + line="755">Sets the page ranges for this job. @@ -107393,13 +109930,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="757">a `GtkPrintJob` pointer to an array of + line="758">pointer to an array of `GtkPageRange` structs @@ -107408,7 +109945,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. the length of the @ranges array + line="760">the length of the @ranges array @@ -107416,7 +109953,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets the `GtkPageSet` setting for this job. + line="788">Sets the `GtkPageSet` setting for this job. @@ -107425,13 +109962,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="790">a `GtkPrintJob` a `GtkPageSet` setting + line="791">a `GtkPageSet` setting @@ -107439,7 +109976,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets the `GtkPrintPages` setting for this job. + line="723">Sets the `GtkPrintPages` setting for this job. @@ -107448,13 +109985,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="725">a `GtkPrintJob` the `GtkPrintPages` setting + line="726">the `GtkPrintPages` setting @@ -107462,7 +109999,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets whether this job is printed reversed. + line="987">Sets whether this job is printed reversed. @@ -107471,13 +110008,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="989">a `GtkPrintJob` whether the job is printed reversed + line="990">whether the job is printed reversed @@ -107485,7 +110022,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets whether this job is printed rotated. + line="931">Sets whether this job is printed rotated. @@ -107494,13 +110031,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="933">a `GtkPrintJob` whether to print rotated + line="934">whether to print rotated @@ -107508,7 +110045,7 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. Sets the scale for this job. + line="845">Sets the scale for this job. 1.0 means unscaled. @@ -107519,13 +110056,13 @@ For details, see [method@Gtk.PrintJob.set_track_print_status]. a `GtkPrintJob` + line="847">a `GtkPrintJob` the scale + line="848">the scale @@ -107605,11 +110142,9 @@ PDF may work too). See [method@Gtk.Printer.accepts_pdf] and - If track_status is %TRUE, the print job will try to continue report + line="555">If track_status is %TRUE, the print job will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” @@ -107625,13 +110160,13 @@ so it should not be enabled unless needed. a `GtkPrintJob` + line="557">a `GtkPrintJob` %TRUE to track status after printing + line="558">%TRUE to track status after printing @@ -107650,8 +110185,6 @@ so it should not be enabled unless needed. construct-only="1" transfer-ownership="none" getter="get_printer"> - The printer to send the job to. @@ -107662,8 +110195,6 @@ so it should not be enabled unless needed. construct-only="1" transfer-ownership="none" getter="get_settings"> - Printer settings. @@ -107675,8 +110206,6 @@ so it should not be enabled unless needed. transfer-ownership="none" getter="get_title" default-value="NULL"> - The title of the print job. @@ -107688,10 +110217,6 @@ so it should not be enabled unless needed. setter="set_track_print_status" getter="get_track_print_status" default-value="FALSE"> - - %TRUE if the print job will continue to emit status-changed @@ -107755,7 +110280,7 @@ It is called when the print job has been completely sent. glib:type-struct="PrintOperationClass"> `GtkPrintOperation` is the high-level, portable printing API. + line="38">High-level, portable printing API. It looks a bit different than other GTK dialogs such as the `GtkFileChooser`, since some platforms don’t expose enough @@ -107822,16 +110347,20 @@ are useful when implementing a print preview. Creates a new `GtkPrintOperation`. + line="1388">Creates a new `GtkPrintOperation`. a new `GtkPrintOperation` + line="1393">a new `GtkPrintOperation` + Signal emitted after the user has finished changing + print settings in the dialog, before the actual rendering starts. @@ -107846,6 +110375,9 @@ are useful when implementing a print preview. + Signal emitted when displaying the print dialog. @@ -107857,6 +110389,10 @@ are useful when implementing a print preview. + Signal emitted right before “begin-print” if + you added a custom widget in the “create-custom-widget” handler. @@ -107871,6 +110407,10 @@ are useful when implementing a print preview. + Signal emitted when the print operation run has finished + doing everything required for printing. @@ -107886,6 +110426,9 @@ are useful when implementing a print preview. + Signal emitted for every page that is printed. @@ -107903,6 +110446,9 @@ are useful when implementing a print preview. + Signal emitted after all pages have been rendered. @@ -107917,6 +110463,10 @@ are useful when implementing a print preview. + Signal emitted after the “begin-print” signal, but + before the actual rendering starts. @@ -107931,6 +110481,10 @@ are useful when implementing a print preview. + Signal emitted when a preview is requested from the + native dialog. @@ -107952,6 +110506,10 @@ are useful when implementing a print preview. + Emitted once for every page that is printed, + to give the application a chance to modify the page setup. @@ -107972,6 +110530,10 @@ are useful when implementing a print preview. + Emitted at between the various phases of the print + operation. @@ -107983,6 +110545,9 @@ are useful when implementing a print preview. + Emitted after change of selected printer. @@ -108005,7 +110570,7 @@ are useful when implementing a print preview. Cancels a running print operation. + line="3159">Cancels a running print operation. This function may be called from a [signal@Gtk.PrintOperation::begin-print], [signal@Gtk.PrintOperation::paginate] or [signal@Gtk.PrintOperation::draw-page] @@ -108018,7 +110583,7 @@ signal handler to stop the currently running print operation. a `GtkPrintOperation` + line="3161">a `GtkPrintOperation` @@ -108027,7 +110592,7 @@ signal handler to stop the currently running print operation. c:identifier="gtk_print_operation_draw_page_finish"> Signal that drawing of particular page is complete. + line="2334">Signal that drawing of particular page is complete. It is called after completion of page drawing (e.g. drawing in another thread). If [method@Gtk.PrintOperation.set_defer_drawing] @@ -108041,7 +110606,7 @@ Otherwise it is called by GTK itself. a `GtkPrintOperation` + line="2336">a `GtkPrintOperation` @@ -108049,23 +110614,21 @@ Otherwise it is called by GTK itself. - Returns the default page setup. + line="1440">Returns the default page setup. the default page setup + line="1446">the default page setup a `GtkPrintOperation` + line="1442">a `GtkPrintOperation` @@ -108073,23 +110636,21 @@ Otherwise it is called by GTK itself. - Gets whether page setup selection combos are embedded + line="2316">Gets whether page setup selection combos are embedded whether page setup selection combos are embedded + line="2322">whether page setup selection combos are embedded a `GtkPrintOperation` + line="2318">a `GtkPrintOperation` @@ -108099,7 +110660,7 @@ Otherwise it is called by GTK itself. throws="1"> Call this when the result of a print operation is + line="2972">Call this when the result of a print operation is %GTK_PRINT_OPERATION_RESULT_ERROR. It can be called either after [method@Gtk.PrintOperation.run] @@ -108115,7 +110676,7 @@ The returned `GError` will contain more details on what went wrong. a `GtkPrintOperation` + line="2974">a `GtkPrintOperation` @@ -108123,22 +110684,21 @@ The returned `GError` will contain more details on what went wrong. - Gets whether there is a selection. + line="3245">Gets whether there is a selection. whether there is a selection + line="3251">whether there is a selection a `GtkPrintOperation` + line="3247">a `GtkPrintOperation` @@ -108146,11 +110706,9 @@ The returned `GError` will contain more details on what went wrong. - Returns the number of pages that will be printed. + line="3263">Returns the number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this function should never be @@ -108164,14 +110722,14 @@ This is typically used to track the progress of print operation. the number of pages that will be printed + line="3278">the number of pages that will be printed a `GtkPrintOperation` + line="3265">a `GtkPrintOperation` @@ -108179,10 +110737,9 @@ This is typically used to track the progress of print operation. - Returns the current print settings. + line="1491">Returns the current print settings. Note that the return value is %NULL until either [method@Gtk.PrintOperation.set_print_settings] or @@ -108191,14 +110748,14 @@ Note that the return value is %NULL until either the current print settings of @op. + line="1501">the current print settings of @op. a `GtkPrintOperation` + line="1493">a `GtkPrintOperation` @@ -108206,24 +110763,23 @@ Note that the return value is %NULL until either - Returns the status of the print operation. + line="1734">Returns the status of the print operation. Also see [method@Gtk.PrintOperation.get_status_string]. the status of the print operation + line="1742">the status of the print operation a `GtkPrintOperation` + line="1736">a `GtkPrintOperation` @@ -108231,10 +110787,9 @@ Also see [method@Gtk.PrintOperation.get_status_string]. - Returns a string representation of the status of the + line="1753">Returns a string representation of the status of the print operation. The string is translated and suitable for displaying @@ -108246,7 +110801,7 @@ a status value that is suitable for programmatic use. a string representation of the status + line="1766">a string representation of the status of the print operation @@ -108254,7 +110809,7 @@ a status value that is suitable for programmatic use. a `GtkPrintOperation` + line="1755">a `GtkPrintOperation` @@ -108262,23 +110817,21 @@ a status value that is suitable for programmatic use. - Gets whether the application supports print of selection + line="3200">Gets whether the application supports print of selection whether the application supports print of selection + line="3206">whether the application supports print of selection a `GtkPrintOperation` + line="3202">a `GtkPrintOperation` @@ -108287,7 +110840,7 @@ a status value that is suitable for programmatic use. c:identifier="gtk_print_operation_is_finished"> A convenience function to find out if the print operation + line="1777">A convenience function to find out if the print operation is finished. a print operation is finished if its status is either @@ -108300,14 +110853,14 @@ the operation status then tracks the print job status on the printer. %TRUE, if the print operation is finished. + line="1791">%TRUE, if the print operation is finished. a `GtkPrintOperation` + line="1779">a `GtkPrintOperation` @@ -108315,7 +110868,7 @@ the operation status then tracks the print job status on the printer. Runs the print operation. + line="2998">Runs the print operation. Normally that this function does not return until the rendering of all pages is complete. You can connect to the @@ -108374,7 +110927,7 @@ given `GtkPrintOperation`. the result of the print operation. A return value of + line="3061">the result of the print operation. A return value of %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with @@ -108389,13 +110942,13 @@ given `GtkPrintOperation`. a `GtkPrintOperation` + line="3000">a `GtkPrintOperation` the action to start + line="3001">the action to start @@ -108405,7 +110958,7 @@ given `GtkPrintOperation`. allow-none="1"> Transient parent of the dialog + line="3002">Transient parent of the dialog @@ -108413,10 +110966,9 @@ given `GtkPrintOperation`. - Sets whether gtk_print_operation_run() may return + line="1831">Sets whether gtk_print_operation_run() may return before the print operation is completed. Note that some platforms may not allow asynchronous @@ -108429,13 +110981,13 @@ operation. a `GtkPrintOperation` + line="1833">a `GtkPrintOperation` %TRUE to allow asynchronous operation + line="1834">%TRUE to allow asynchronous operation @@ -108443,10 +110995,9 @@ operation. - Sets the current page. + line="1578">Sets the current page. If this is called before [method@Gtk.PrintOperation.run], the user will be able to select to print only the current page. @@ -108460,13 +111011,13 @@ Note that this only makes sense for pre-paginated documents. a `GtkPrintOperation` + line="1580">a `GtkPrintOperation` the current page, 0-based + line="1581">the current page, 0-based @@ -108474,11 +111025,9 @@ Note that this only makes sense for pre-paginated documents. - Sets the label for the tab holding custom widgets. + line="1861">Sets the label for the tab holding custom widgets. @@ -108487,7 +111036,7 @@ Note that this only makes sense for pre-paginated documents. a `GtkPrintOperation` + line="1863">a `GtkPrintOperation` allow-none="1"> the label to use, or %NULL to use the default label + line="1864">the label to use, or %NULL to use the default label @@ -108504,11 +111053,9 @@ Note that this only makes sense for pre-paginated documents. - Makes @default_page_setup the default page setup for @op. + line="1405">Makes @default_page_setup the default page setup for @op. This page setup will be used by [method@Gtk.PrintOperation.run], but it can be overridden on a per-page basis by connecting @@ -108521,7 +111068,7 @@ to the [signal@Gtk.PrintOperation::request-page-setup] signal. a `GtkPrintOperation` + line="1407">a `GtkPrintOperation` allow-none="1"> a `GtkPageSetup` + line="1408">a `GtkPageSetup` @@ -108539,7 +111086,7 @@ to the [signal@Gtk.PrintOperation::request-page-setup] signal. c:identifier="gtk_print_operation_set_defer_drawing"> Sets up the `GtkPrintOperation` to wait for calling of + line="2269">Sets up the `GtkPrintOperation` to wait for calling of [method@Gtk.PrintOperation.draw_page_finish from application. This can be used for drawing page in another thread. @@ -108554,7 +111101,7 @@ This function must be called in the callback of the a `GtkPrintOperation` + line="2271">a `GtkPrintOperation` @@ -108562,11 +111109,9 @@ This function must be called in the callback of the - Embed page size combo box and orientation combo box into page setup page. + line="2291">Embed page size combo box and orientation combo box into page setup page. Selected page setup is stored as default page setup in `GtkPrintOperation`. @@ -108577,13 +111122,13 @@ Selected page setup is stored as default page setup in `GtkPrintOperation`. a `GtkPrintOperation` + line="2293">a `GtkPrintOperation` %TRUE to embed page setup selection in the `GtkPrintUnixDialog` + line="2294">%TRUE to embed page setup selection in the `GtkPrintUnixDialog` @@ -108591,10 +111136,9 @@ Selected page setup is stored as default page setup in `GtkPrintOperation`. - Sets up the `GtkPrintOperation` to generate a file instead + line="1883">Sets up the `GtkPrintOperation` to generate a file instead of showing the print dialog. The intended use of this function is for implementing @@ -108612,13 +111156,13 @@ of printers in the print dialog. a `GtkPrintOperation` + line="1885">a `GtkPrintOperation` the filename for the exported file + line="1886">the filename for the exported file @@ -108626,10 +111170,9 @@ of printers in the print dialog. - Sets whether there is a selection to print. + line="3218">Sets whether there is a selection to print. Application has to set number of pages to which the selection will draw by [method@Gtk.PrintOperation.set_n_pages] in a handler @@ -108642,13 +111185,13 @@ for the [signal@Gtk.PrintOperation::begin-print] signal. a `GtkPrintOperation` + line="3220">a `GtkPrintOperation` %TRUE indicates that a selection exists + line="3221">%TRUE indicates that a selection exists @@ -108656,10 +111199,9 @@ for the [signal@Gtk.PrintOperation::begin-print] signal. - Sets the name of the print job. + line="1511">Sets the name of the print job. The name is used to identify the job (e.g. in monitoring applications like eggcups). @@ -108674,13 +111216,13 @@ numbering successive print jobs. a `GtkPrintOperation` + line="1513">a `GtkPrintOperation` a string that identifies the print job + line="1514">a string that identifies the print job @@ -108688,10 +111230,9 @@ numbering successive print jobs. - Sets the number of pages in the document. + line="1542">Sets the number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] @@ -108710,13 +111251,13 @@ will be for page @n_pages - 1. a `GtkPrintOperation` + line="1544">a `GtkPrintOperation` the number of pages + line="1545">the number of pages @@ -108724,10 +111265,9 @@ will be for page @n_pages - 1. - Sets the print settings for @op. + line="1457">Sets the print settings for @op. This is typically used to re-establish print settings from a previous print operation, see [method@Gtk.PrintOperation.run]. @@ -108739,7 +111279,7 @@ from a previous print operation, see [method@Gtk.PrintOperation.run]. a `GtkPrintOperation` + line="1459">a `GtkPrintOperation` allow-none="1"> `GtkPrintSettings` + line="1460">`GtkPrintSettings` @@ -108756,10 +111296,9 @@ from a previous print operation, see [method@Gtk.PrintOperation.run]. - If @show_progress is %TRUE, the print operation will show + line="1805">If @show_progress is %TRUE, the print operation will show a progress dialog during the print operation. @@ -108769,13 +111308,13 @@ a progress dialog during the print operation. a `GtkPrintOperation` + line="1807">a `GtkPrintOperation` %TRUE to show a progress dialog + line="1808">%TRUE to show a progress dialog @@ -108783,11 +111322,9 @@ a progress dialog during the print operation. - Sets whether selection is supported by `GtkPrintOperation`. + line="3177">Sets whether selection is supported by `GtkPrintOperation`. @@ -108796,13 +111333,13 @@ a progress dialog during the print operation. a `GtkPrintOperation` + line="3179">a `GtkPrintOperation` %TRUE to support selection + line="3180">%TRUE to support selection @@ -108810,11 +111347,9 @@ a progress dialog during the print operation. - If track_status is %TRUE, the print operation will try to continue + line="1665">If track_status is %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” @@ -108830,13 +111365,13 @@ so it should not be enabled unless needed. a `GtkPrintOperation` + line="1667">a `GtkPrintOperation` %TRUE to track status after printing + line="1668">%TRUE to track status after printing @@ -108844,10 +111379,9 @@ so it should not be enabled unless needed. - Sets up the transformation for the cairo context obtained from + line="1640">Sets up the transformation for the cairo context obtained from `GtkPrintContext` in such a way that distances are measured in units of @unit. @@ -108858,13 +111392,13 @@ units of @unit. a `GtkPrintOperation` + line="1642">a `GtkPrintOperation` the unit to use + line="1643">the unit to use @@ -108872,10 +111406,9 @@ units of @unit. - If @full_page is %TRUE, the transformation for the cairo context + line="1609">If @full_page is %TRUE, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page. @@ -108890,13 +111423,13 @@ is at the top left corner of the imageable area (i.e. inside the margins). a `GtkPrintOperation` + line="1611">a `GtkPrintOperation` %TRUE to set up the `GtkPrintContext` for the full page + line="1612">%TRUE to set up the `GtkPrintContext` for the full page @@ -108906,11 +111439,9 @@ is at the top left corner of the imageable area (i.e. inside the margins). transfer-ownership="none" setter="set_allow_async" default-value="FALSE"> - Determines whether the print operation may run asynchronously or not. + line="1240">Determines whether the print operation may run asynchronously or not. Some systems don't support asynchronous printing, but those that do will return %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and @@ -108927,11 +111458,9 @@ is unlikely to change). On other platforms, all actions except for transfer-ownership="none" setter="set_current_page" default-value="-1"> - The current page in the document. + line="1161">The current page in the document. If this is set before [method@Gtk.PrintOperation.run], the user will be able to select to print only the current page. @@ -108944,11 +111473,9 @@ Note that this only makes sense for pre-paginated documents. transfer-ownership="none" setter="set_custom_tab_label" default-value="NULL"> - Used as the label of the tab containing custom widgets. + line="1310">Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. @@ -108960,13 +111487,9 @@ If this is %NULL, GTK uses a default label. transfer-ownership="none" setter="set_default_page_setup" getter="get_default_page_setup"> - - The `GtkPageSetup` used by default. + line="1093">The `GtkPageSetup` used by default. This page setup will be used by [method@Gtk.PrintOperation.run], but it can be overridden on a per-page basis by connecting @@ -108979,13 +111502,9 @@ to the [signal@Gtk.PrintOperation::request-page-setup] signal. setter="set_embed_page_setup" getter="get_embed_page_setup" default-value="FALSE"> - - If %TRUE, page size combo box and orientation combo box + line="1353">If %TRUE, page size combo box and orientation combo box are embedded into page setup page. @@ -108994,11 +111513,9 @@ are embedded into page setup page. transfer-ownership="none" setter="set_export_filename" default-value="NULL"> - The name of a file to generate instead of showing the print dialog. + line="1260">The name of a file to generate instead of showing the print dialog. Currently, PDF is the only supported format. @@ -109016,13 +111533,9 @@ list of printers in the print dialog. setter="set_has_selection" getter="get_has_selection" default-value="FALSE"> - - Determines whether there is a selection in your application. + line="1338">Determines whether there is a selection in your application. This can allow your application to print the selection. This is typically used to make a "Selection" button sensitive. @@ -109032,11 +111545,9 @@ This is typically used to make a "Selection" button sensitive. writable="1" transfer-ownership="none" setter="set_job_name"> - A string used to identify the job (e.g. in monitoring + line="1123">A string used to identify the job (e.g. in monitoring applications like eggcups). If you don't set a job name, GTK picks a default one @@ -109048,11 +111559,9 @@ by numbering successive print jobs. transfer-ownership="none" setter="set_n_pages" default-value="-1"> - The number of pages in the document. + line="1138">The number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] @@ -109069,11 +111578,9 @@ will be for page @n_pages - 1. transfer-ownership="none" getter="get_n_pages_to_print" default-value="-1"> - The number of pages that will be printed. + line="1365">The number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this value should never be @@ -109090,13 +111597,9 @@ This is typically used to track the progress of print operation. transfer-ownership="none" setter="set_print_settings" getter="get_print_settings"> - - The `GtkPrintSettings` used for initializing the dialog. + line="1108">The `GtkPrintSettings` used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see @@ -109108,11 +111611,9 @@ print settings from a previous print operation, see transfer-ownership="none" setter="set_show_progress" default-value="FALSE"> - Determines whether to show a progress dialog during the + line="1228">Determines whether to show a progress dialog during the print operation. @@ -109120,21 +111621,17 @@ print operation. transfer-ownership="none" getter="get_status" default-value="GTK_PRINT_STATUS_INITIAL"> - The status of the print operation. + line="1280">The status of the print operation. - A string representation of the status of the print operation. + line="1292">A string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a `GtkStatusbar`. @@ -109149,13 +111646,9 @@ value that is suitable for programmatic use. setter="set_support_selection" getter="get_support_selection" default-value="FALSE"> - - If %TRUE, the print operation will support print of selection. + line="1325">If %TRUE, the print operation will support print of selection. This allows the print dialog to show a "Selection" button. @@ -109165,11 +111658,9 @@ This allows the print dialog to show a "Selection" button. transfer-ownership="none" setter="set_track_print_status" default-value="FALSE"> - If %TRUE, the print operation will try to continue report on + line="1197">If %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” @@ -109183,11 +111674,9 @@ not be enabled unless needed. transfer-ownership="none" setter="set_unit" default-value="GTK_UNIT_NONE"> - The transformation for the cairo context obtained from + line="1214">The transformation for the cairo context obtained from `GtkPrintContext` is set up in such a way that distances are measured in units of @unit. @@ -109197,11 +111686,9 @@ are measured in units of @unit. transfer-ownership="none" setter="set_use_full_page" default-value="FALSE"> - If %TRUE, the transformation for the cairo context obtained + line="1179">If %TRUE, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page. @@ -109220,7 +111707,7 @@ inside the margins). Emitted after the user has finished changing print settings + line="780">Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. A typical use for ::begin-print is to use the parameters from the @@ -109234,7 +111721,7 @@ and then set the number of pages with the `GtkPrintContext` for the current operation + line="783">the `GtkPrintContext` for the current operation @@ -109242,7 +111729,7 @@ and then set the number of pages with Emitted when displaying the print dialog. + line="975">Emitted when displaying the print dialog. If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a @@ -109256,7 +111743,7 @@ information you need from the widgets. A custom widget that gets embedded in + line="991">A custom widget that gets embedded in the print dialog @@ -109264,7 +111751,7 @@ information you need from the widgets. Emitted right before ::begin-print if you added + line="1030">Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler. When you get this signal you should read the information from the @@ -109277,7 +111764,7 @@ later time. the custom widget added in ::create-custom-widget + line="1033">the custom widget added in ::create-custom-widget @@ -109285,7 +111772,7 @@ later time. Emitted when the print operation run has finished doing + line="755">Emitted when the print operation run has finished doing everything required for printing. @result gives you information about what happened during the run. @@ -109302,7 +111789,7 @@ after the ::done signal was emitted. the result of the print operation + line="758">the result of the print operation @@ -109310,7 +111797,7 @@ after the ::done signal was emitted. Emitted for every page that is printed. + line="864">Emitted for every page that is printed. The signal handler must render the @page_nr's page onto the cairo context obtained from @context using @@ -109368,13 +111855,13 @@ according to your needs. the `GtkPrintContext` for the current operation + line="867">the `GtkPrintContext` for the current operation the number of the currently printed page (0-based) + line="868">the number of the currently printed page (0-based) @@ -109382,7 +111869,7 @@ according to your needs. Emitted after all pages have been rendered. + line="936">Emitted after all pages have been rendered. A handler for this signal can clean up any resources that have been allocated in the [signal@Gtk.PrintOperation::begin-print] handler. @@ -109393,7 +111880,7 @@ been allocated in the [signal@Gtk.PrintOperation::begin-print] handler. the `GtkPrintContext` for the current operation + line="939">the `GtkPrintContext` for the current operation @@ -109401,7 +111888,7 @@ been allocated in the [signal@Gtk.PrintOperation::begin-print] handler. Emitted after the ::begin-print signal, but before the actual rendering + line="802">Emitted after the ::begin-print signal, but before the actual rendering starts. It keeps getting emitted until a connected signal handler returns %TRUE. @@ -109418,14 +111905,14 @@ from there. %TRUE if pagination is complete + line="822">%TRUE if pagination is complete the `GtkPrintContext` for the current operation + line="805">the `GtkPrintContext` for the current operation @@ -109433,7 +111920,7 @@ from there. Gets emitted when a preview is requested from the native dialog. + line="1051">Gets emitted when a preview is requested from the native dialog. The default handler for this signal uses an external viewer application to preview. @@ -109453,20 +111940,20 @@ finished by calling [method@Gtk.PrintOperationPreview.end_preview] %TRUE if the listener wants to take over control of the preview + line="1076">%TRUE if the listener wants to take over control of the preview the `GtkPrintOperationPreview` for the current operation + line="1054">the `GtkPrintOperationPreview` for the current operation the `GtkPrintContext` that will be used + line="1055">the `GtkPrintContext` that will be used the `GtkWindow` to use as window parent + line="1056">the `GtkWindow` to use as window parent @@ -109483,7 +111970,7 @@ finished by calling [method@Gtk.PrintOperationPreview.end_preview] Emitted once for every page that is printed. + line="836">Emitted once for every page that is printed. This gives the application a chance to modify the page setup. Any changes done to @setup will be in force only for printing @@ -109495,19 +111982,19 @@ this page. the `GtkPrintContext` for the current operation + line="839">the `GtkPrintContext` for the current operation the number of the currently printed page (0-based) + line="840">the number of the currently printed page (0-based) the `GtkPageSetup` + line="841">the `GtkPageSetup` @@ -109515,7 +112002,7 @@ this page. Emitted at between the various phases of the print operation. + line="955">Emitted at between the various phases of the print operation. See [enum@Gtk.PrintStatus] for the phases that are being discriminated. Use [method@Gtk.PrintOperation.get_status] to find out the current @@ -109527,7 +112014,7 @@ status. Emitted after change of selected printer. + line="1006">Emitted after change of selected printer. The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change. @@ -109538,19 +112025,19 @@ widget, which can actualize itself according to this change. the custom widget added in ::create-custom-widget + line="1009">the custom widget added in ::create-custom-widget actual page setup + line="1010">actual page setup actual print settings + line="1011">actual print settings @@ -109615,6 +112102,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted when the print operation run has finished + doing everything required for printing. @@ -109633,6 +112124,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted after the user has finished changing + print settings in the dialog, before the actual rendering starts. @@ -109650,6 +112145,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted after the “begin-print” signal, but + before the actual rendering starts. @@ -109667,6 +112166,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Emitted once for every page that is printed, + to give the application a chance to modify the page setup. @@ -109690,6 +112193,9 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted for every page that is printed. @@ -109710,6 +112216,9 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted after all pages have been rendered. @@ -109727,6 +112236,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Emitted at between the various phases of the print + operation. @@ -109741,6 +112254,9 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted when displaying the print dialog. @@ -109755,6 +112271,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted right before “begin-print” if + you added a custom widget in the “create-custom-widget” handler. @@ -109772,6 +112292,10 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Signal emitted when a preview is requested from the + native dialog. @@ -109796,6 +112320,9 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. + Emitted after change of selected printer. @@ -109832,8 +112359,7 @@ A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. glib:type-struct="PrintOperationPreviewIface"> `GtkPrintOperationPreview` is the interface that is used to -implement print preview. + line="28">The interface that is used to implement print preview. A `GtkPrintOperationPreview` object is passed to the [signal@Gtk.PrintOperation::preview] signal by @@ -109843,7 +112369,7 @@ A `GtkPrintOperationPreview` object is passed to the Ends a preview. + line="154">Ends a preview. This function must be called to finish a custom print preview. a `GtkPrintOperationPreview` + line="156">a `GtkPrintOperationPreview` @@ -109883,28 +112409,28 @@ This function must be called to finish a custom print preview. Returns whether the given page is included in the set of pages that + line="170">Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing + line="178">%TRUE if the page has been selected for printing a `GtkPrintOperationPreview` + line="172">a `GtkPrintOperationPreview` a page number + line="173">a page number @@ -109928,7 +112454,7 @@ have been selected for printing. Renders a page to the preview. + line="127">Renders a page to the preview. This is using the print context that was passed to the [signal@Gtk.PrintOperation::preview] handler together @@ -109948,14 +112474,14 @@ be associated with the print context. a `GtkPrintOperationPreview` + line="129">a `GtkPrintOperationPreview` the page to render + line="130">the page to render @@ -109964,7 +112490,7 @@ be associated with the print context. c:identifier="gtk_print_operation_preview_end_preview"> Ends a preview. + line="154">Ends a preview. This function must be called to finish a custom print preview. a `GtkPrintOperationPreview` + line="156">a `GtkPrintOperationPreview` @@ -109986,28 +112512,28 @@ This function must be called to finish a custom print preview. c:identifier="gtk_print_operation_preview_is_selected"> Returns whether the given page is included in the set of pages that + line="170">Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing + line="178">%TRUE if the page has been selected for printing a `GtkPrintOperationPreview` + line="172">a `GtkPrintOperationPreview` a page number + line="173">a page number @@ -110016,7 +112542,7 @@ have been selected for printing. c:identifier="gtk_print_operation_preview_render_page"> Renders a page to the preview. + line="127">Renders a page to the preview. This is using the print context that was passed to the [signal@Gtk.PrintOperation::preview] handler together @@ -110036,14 +112562,14 @@ be associated with the print context. a `GtkPrintOperationPreview` + line="129">a `GtkPrintOperationPreview` the page to render + line="130">the page to render @@ -110051,7 +112577,7 @@ be associated with the print context. Emitted once for each page that gets rendered to the preview. + line="98">Emitted once for each page that gets rendered to the preview. A handler for this signal should update the @context according to @page_setup and set up a suitable cairo @@ -110063,13 +112589,13 @@ context, using [method@Gtk.PrintContext.set_cairo_context]. the current `GtkPrintContext` + line="101">the current `GtkPrintContext` the `GtkPageSetup` for the current page + line="102">the `GtkPageSetup` for the current page @@ -110077,7 +112603,7 @@ context, using [method@Gtk.PrintContext.set_cairo_context]. The ::ready signal gets emitted once per preview operation, + line="79">The ::ready signal gets emitted once per preview operation, before the first page is rendered. A handler for this signal can be used for setup tasks. @@ -110088,7 +112614,7 @@ A handler for this signal can be used for setup tasks. the current `GtkPrintContext` + line="82">the current `GtkPrintContext` @@ -110152,14 +112678,14 @@ A handler for this signal can be used for setup tasks. a `GtkPrintOperationPreview` + line="129">a `GtkPrintOperationPreview` the page to render + line="130">the page to render @@ -110172,21 +112698,21 @@ A handler for this signal can be used for setup tasks. %TRUE if the page has been selected for printing + line="178">%TRUE if the page has been selected for printing a `GtkPrintOperationPreview` + line="172">a `GtkPrintOperationPreview` a page number + line="173">a page number @@ -110203,7 +112729,7 @@ A handler for this signal can be used for setup tasks. a `GtkPrintOperationPreview` + line="156">a `GtkPrintOperationPreview` @@ -110343,7 +112869,7 @@ A value of this type is returned by [method@Gtk.PrintOperation.run]. c:type="GtkPrintPages"> See also gtk_print_job_set_pages() + line="598">See also gtk_print_job_set_pages() glib:name="GTK_PRINT_PAGES_ALL"> All pages. + line="600">All pages. glib:name="GTK_PRINT_PAGES_CURRENT"> Current page. + line="601">Current page. glib:name="GTK_PRINT_PAGES_RANGES"> Range of pages. + line="602">Range of pages. glib:name="GTK_PRINT_PAGES_SELECTION"> Selected pages. + line="603">Selected pages. c:type="GtkPrintQuality"> See also gtk_print_settings_set_quality(). + line="716">See also gtk_print_settings_set_quality(). glib:name="GTK_PRINT_QUALITY_LOW"> Low quality. + line="718">Low quality. glib:name="GTK_PRINT_QUALITY_NORMAL"> Normal quality. + line="719">Normal quality. glib:name="GTK_PRINT_QUALITY_HIGH"> High quality. + line="720">High quality. glib:name="GTK_PRINT_QUALITY_DRAFT"> Draft quality. + line="721">Draft quality. glib:get-type="gtk_print_settings_get_type"> A `GtkPrintSettings` object represents the settings of a print dialog in -a system-independent way. + line="32">Collects the settings of a print dialog in a system-independent way. The main use for this object is that once you’ve printed you can get a settings object that represents the settings the user chose, and the next @@ -110448,12 +112973,12 @@ so that moving such a document between systems still works. Creates a new `GtkPrintSettings` object. - + line="95">Creates a new `GtkPrintSettings` object. + a new `GtkPrintSettings` object + line="100">a new `GtkPrintSettings` object @@ -110462,25 +112987,25 @@ so that moving such a document between systems still works. throws="1"> Reads the print settings from @file_name. + line="1592">Reads the print settings from @file_name. Returns a new `GtkPrintSettings` object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. See [method@Gtk.PrintSettings.to_file]. - + the restored `GtkPrintSettings` + line="1605">the restored `GtkPrintSettings` the filename to read the settings from + line="1594">the filename to read the settings from @@ -110489,22 +113014,22 @@ See [method@Gtk.PrintSettings.to_file]. c:identifier="gtk_print_settings_new_from_gvariant"> Deserialize print settings from an a{sv} variant. + line="1832">Deserialize print settings from an a{sv} variant. The variant must be in the format produced by [method@Gtk.PrintSettings.to_gvariant]. - + a new `GtkPrintSettings` object + line="1841">a new `GtkPrintSettings` object an a{sv} `GVariant` + line="1834">an a{sv} `GVariant` @@ -110514,23 +113039,23 @@ The variant must be in the format produced by throws="1"> Reads the print settings from the group @group_name in @key_file. + line="1683">Reads the print settings from the group @group_name in @key_file. Returns a new `GtkPrintSettings` object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either `GFileError` or `GKeyFileError`. - + the restored `GtkPrintSettings` + line="1696">the restored `GtkPrintSettings` the `GKeyFile` to retrieve the settings from + line="1685">the `GKeyFile` to retrieve the settings from allow-none="1"> the name of the group to use, or %NULL to use + line="1686">the name of the group to use, or %NULL to use the default “Print Settings” @@ -110548,19 +113073,19 @@ error is set to either `GFileError` or `GKeyFileError`. Copies a `GtkPrintSettings` object. - + line="122">Copies a `GtkPrintSettings` object. + a newly allocated copy of @other + line="128">a newly allocated copy of @other a `GtkPrintSettings` + line="124">a `GtkPrintSettings` @@ -110568,8 +113093,8 @@ error is set to either `GFileError` or `GKeyFileError`. Calls @func for each key-value pair of @settings. - + line="459">Calls @func for each key-value pair of @settings. + @@ -110577,7 +113102,7 @@ error is set to either `GFileError` or `GKeyFileError`. a `GtkPrintSettings` + line="461">a `GtkPrintSettings` closure="1"> the function to call + line="462">the function to call allow-none="1"> user data for @func + line="463">user data for @func @@ -110603,25 +113128,25 @@ error is set to either `GFileError` or `GKeyFileError`. Looks up the string value associated with @key. - + line="149">Looks up the string value associated with @key. + the string value for @key + line="156">the string value for @key a `GtkPrintSettings` + line="151">a `GtkPrintSettings` a key + line="152">a key @@ -110629,29 +113154,29 @@ error is set to either `GFileError` or `GKeyFileError`. Returns the boolean represented by the value + line="219">Returns the boolean represented by the value that is associated with @key. The string “true” represents %TRUE, any other string %FALSE. - + %TRUE, if @key maps to a true value. + line="230">%TRUE, if @key maps to a true value. a `GtkPrintSettings` + line="221">a `GtkPrintSettings` a key + line="222">a key @@ -110659,19 +113184,19 @@ string %FALSE. Gets the value of %GTK_PRINT_SETTINGS_COLLATE. - + line="743">Gets the value of %GTK_PRINT_SETTINGS_COLLATE. + whether to collate the printed pages + line="749">whether to collate the printed pages a `GtkPrintSettings` + line="745">a `GtkPrintSettings` @@ -110680,19 +113205,19 @@ string %FALSE. c:identifier="gtk_print_settings_get_default_source"> Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. - + line="1411">Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. + the default source + line="1417">the default source a `GtkPrintSettings` + line="1413">a `GtkPrintSettings` @@ -110700,19 +113225,19 @@ string %FALSE. Gets the value of %GTK_PRINT_SETTINGS_DITHER. - + line="1471">Gets the value of %GTK_PRINT_SETTINGS_DITHER. + the dithering that is used + line="1477">the dithering that is used a `GtkPrintSettings` + line="1473">a `GtkPrintSettings` @@ -110720,25 +113245,25 @@ string %FALSE. Returns the double value associated with @key, or 0. - + line="324">Returns the double value associated with @key, or 0. + the double value of @key + line="331">the double value of @key a `GtkPrintSettings` + line="326">a `GtkPrintSettings` a key + line="327">a key @@ -110747,35 +113272,35 @@ string %FALSE. c:identifier="gtk_print_settings_get_double_with_default"> Returns the floating point number represented by + line="296">Returns the floating point number represented by the value that is associated with @key, or @default_val if the value does not represent a floating point number. Floating point numbers are parsed with g_ascii_strtod(). - + the floating point number associated with @key + line="308">the floating point number associated with @key a `GtkPrintSettings` + line="298">a `GtkPrintSettings` a key + line="299">a key the default value + line="300">the default value @@ -110783,19 +113308,19 @@ Floating point numbers are parsed with g_ascii_strtod(). Gets the value of %GTK_PRINT_SETTINGS_DUPLEX. - + line="806">Gets the value of %GTK_PRINT_SETTINGS_DUPLEX. + whether to print the output in duplex. + line="812">whether to print the output in duplex. a `GtkPrintSettings` + line="808">a `GtkPrintSettings` @@ -110804,19 +113329,19 @@ Floating point numbers are parsed with g_ascii_strtod(). c:identifier="gtk_print_settings_get_finishings"> Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS. - + line="1499">Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS. + the finishings + line="1505">the finishings a `GtkPrintSettings` + line="1501">a `GtkPrintSettings` @@ -110824,25 +113349,25 @@ Floating point numbers are parsed with g_ascii_strtod(). Returns the integer value of @key, or 0. - + line="425">Returns the integer value of @key, or 0. + the integer value of @key + line="432">the integer value of @key a `GtkPrintSettings` + line="427">a `GtkPrintSettings` a key + line="428">a key @@ -110851,32 +113376,32 @@ Floating point numbers are parsed with g_ascii_strtod(). c:identifier="gtk_print_settings_get_int_with_default"> Returns the value of @key, interpreted as + line="400">Returns the value of @key, interpreted as an integer, or the default value. - + the integer value of @key + line="409">the integer value of @key a `GtkPrintSettings` + line="402">a `GtkPrintSettings` a key + line="403">a key the default value + line="404">the default value @@ -110884,34 +113409,34 @@ an integer, or the default value. Returns the value associated with @key, interpreted + line="359">Returns the value associated with @key, interpreted as a length. The returned value is converted to @units. - + the length value of @key, converted to @unit + line="370">the length value of @key, converted to @unit a `GtkPrintSettings` + line="361">a `GtkPrintSettings` a key + line="362">a key the unit of the return value + line="363">the unit of the return value @@ -110920,21 +113445,21 @@ The returned value is converted to @units. c:identifier="gtk_print_settings_get_media_type"> Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. + line="1439">Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. - + the media type + line="1447">the media type a `GtkPrintSettings` + line="1441">a `GtkPrintSettings` @@ -110943,19 +113468,19 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_get_n_copies"> Gets the value of %GTK_PRINT_SETTINGS_N_COPIES. - + line="1046">Gets the value of %GTK_PRINT_SETTINGS_N_COPIES. + the number of copies to print + line="1052">the number of copies to print a `GtkPrintSettings` + line="1048">a `GtkPrintSettings` @@ -110964,19 +113489,19 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_get_number_up"> Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. - + line="1075">Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. + the number of pages per sheet + line="1081">the number of pages per sheet a `GtkPrintSettings` + line="1077">a `GtkPrintSettings` @@ -110985,19 +113510,19 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_get_number_up_layout"> Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. - + line="983">Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. + layout of page in number-up mode + line="989">layout of page in number-up mode a `GtkPrintSettings` + line="985">a `GtkPrintSettings` @@ -111006,20 +113531,20 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_get_orientation"> Get the value of %GTK_PRINT_SETTINGS_ORIENTATION, + line="506">Get the value of %GTK_PRINT_SETTINGS_ORIENTATION, converted to a `GtkPageOrientation`. - + the orientation + line="513">the orientation a `GtkPrintSettings` + line="508">a `GtkPrintSettings` @@ -111028,19 +113553,19 @@ converted to a `GtkPageOrientation`. c:identifier="gtk_print_settings_get_output_bin"> Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. - + line="1527">Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. + the output bin + line="1533">the output bin a `GtkPrintSettings` + line="1529">a `GtkPrintSettings` @@ -111049,12 +113574,12 @@ converted to a `GtkPageOrientation`. c:identifier="gtk_print_settings_get_page_ranges"> Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. - + line="1313">Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. + an array + line="1320">an array of `GtkPageRange`s. Use g_free() to free the array when it is no longer needed. @@ -111065,7 +113590,7 @@ converted to a `GtkPageOrientation`. a `GtkPrintSettings` + line="1315">a `GtkPrintSettings` transfer-ownership="full"> return location for the length of the returned array + line="1316">return location for the length of the returned array @@ -111083,19 +113608,19 @@ converted to a `GtkPageOrientation`. c:identifier="gtk_print_settings_get_page_set"> Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET. - + line="926">Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET. + the set of pages to print + line="932">the set of pages to print a `GtkPrintSettings` + line="928">a `GtkPrintSettings` @@ -111104,26 +113629,26 @@ converted to a `GtkPageOrientation`. c:identifier="gtk_print_settings_get_paper_height"> Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT, + line="674">Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT, converted to @unit. - + the paper height, in units of @unit + line="682">the paper height, in units of @unit a `GtkPrintSettings` + line="676">a `GtkPrintSettings` the unit for the return value + line="677">the unit for the return value @@ -111132,20 +113657,20 @@ converted to @unit. c:identifier="gtk_print_settings_get_paper_size"> Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, + line="569">Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, converted to a `GtkPaperSize`. - + the paper size + line="576">the paper size a `GtkPrintSettings` + line="571">a `GtkPrintSettings` @@ -111154,26 +113679,26 @@ converted to a `GtkPaperSize`. c:identifier="gtk_print_settings_get_paper_width"> Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH, + line="641">Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH, converted to @unit. - + the paper width, in units of @unit + line="649">the paper width, in units of @unit a `GtkPrintSettings` + line="643">a `GtkPrintSettings` the unit for the return value + line="644">the unit for the return value @@ -111182,19 +113707,19 @@ converted to @unit. c:identifier="gtk_print_settings_get_print_pages"> Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. - + line="1250">Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. + which pages to print + line="1256">which pages to print a `GtkPrintSettings` + line="1252">a `GtkPrintSettings` @@ -111202,20 +113727,20 @@ converted to @unit. Convenience function to obtain the value of + line="475">Convenience function to obtain the value of %GTK_PRINT_SETTINGS_PRINTER. - + the printer name + line="482">the printer name a `GtkPrintSettings` + line="477">a `GtkPrintSettings` @@ -111224,19 +113749,19 @@ converted to @unit. c:identifier="gtk_print_settings_get_printer_lpi"> Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. - + line="1190">Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. + the resolution in lpi (lines per inch) + line="1196">the resolution in lpi (lines per inch) a `GtkPrintSettings` + line="1192">a `GtkPrintSettings` @@ -111244,19 +113769,19 @@ converted to @unit. Gets the value of %GTK_PRINT_SETTINGS_QUALITY. - + line="863">Gets the value of %GTK_PRINT_SETTINGS_QUALITY. + the print quality + line="869">the print quality a `GtkPrintSettings` + line="865">a `GtkPrintSettings` @@ -111265,19 +113790,19 @@ converted to @unit. c:identifier="gtk_print_settings_get_resolution"> Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION. - + line="1104">Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION. + the resolution in dpi + line="1110">the resolution in dpi a `GtkPrintSettings` + line="1106">a `GtkPrintSettings` @@ -111286,19 +113811,19 @@ converted to @unit. c:identifier="gtk_print_settings_get_resolution_x"> Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X. - + line="1139">Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X. + the horizontal resolution in dpi + line="1145">the horizontal resolution in dpi a `GtkPrintSettings` + line="1141">a `GtkPrintSettings` @@ -111307,19 +113832,19 @@ converted to @unit. c:identifier="gtk_print_settings_get_resolution_y"> Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y. - + line="1153">Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y. + the vertical resolution in dpi + line="1159">the vertical resolution in dpi a `GtkPrintSettings` + line="1155">a `GtkPrintSettings` @@ -111327,19 +113852,19 @@ converted to @unit. Gets the value of %GTK_PRINT_SETTINGS_REVERSE. - + line="775">Gets the value of %GTK_PRINT_SETTINGS_REVERSE. + whether to reverse the order of the printed pages + line="781">whether to reverse the order of the printed pages a `GtkPrintSettings` + line="777">a `GtkPrintSettings` @@ -111347,19 +113872,19 @@ converted to @unit. Gets the value of %GTK_PRINT_SETTINGS_SCALE. - + line="1219">Gets the value of %GTK_PRINT_SETTINGS_SCALE. + the scale in percent + line="1225">the scale in percent a `GtkPrintSettings` + line="1221">a `GtkPrintSettings` @@ -111368,19 +113893,19 @@ converted to @unit. c:identifier="gtk_print_settings_get_use_color"> Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR. - + line="711">Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR. + whether to use color + line="717">whether to use color a `GtkPrintSettings` + line="713">a `GtkPrintSettings` @@ -111388,25 +113913,25 @@ converted to @unit. Returns %TRUE, if a value is associated with @key. - + line="202">Returns %TRUE, if a value is associated with @key. + %TRUE, if @key has a value + line="209">%TRUE, if @key has a value a `GtkPrintSettings` + line="204">a `GtkPrintSettings` a key + line="205">a key @@ -111416,30 +113941,30 @@ converted to @unit. throws="1"> Reads the print settings from @file_name. + line="1555">Reads the print settings from @file_name. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. See [method@Gtk.PrintSettings.to_file]. - + %TRUE on success + line="1568">%TRUE on success a `GtkPrintSettings` + line="1557">a `GtkPrintSettings` the filename to read the settings from + line="1558">the filename to read the settings from @@ -111449,28 +113974,28 @@ See [method@Gtk.PrintSettings.to_file]. throws="1"> Reads the print settings from the group @group_name in @key_file. + line="1622">Reads the print settings from the group @group_name in @key_file. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. - + %TRUE on success + line="1635">%TRUE on success a `GtkPrintSettings` + line="1624">a `GtkPrintSettings` the `GKeyFile` to retrieve the settings from + line="1625">the `GKeyFile` to retrieve the settings from the name of the group to use, or %NULL + line="1626">the name of the group to use, or %NULL to use the default “Print Settings” @@ -111488,8 +114013,8 @@ If the file could not be loaded then error is set to either a Associates @value with @key. - + line="165">Associates @value with @key. + @@ -111497,13 +114022,13 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="167">a `GtkPrintSettings` a key + line="168">a key a string value + line="169">a string value @@ -111520,8 +114045,8 @@ If the file could not be loaded then error is set to either a Sets @key to a boolean value. - + line="277">Sets @key to a boolean value. + @@ -111529,19 +114054,19 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="279">a `GtkPrintSettings` a key + line="280">a key a boolean + line="281">a boolean @@ -111549,8 +114074,8 @@ If the file could not be loaded then error is set to either a Sets the value of %GTK_PRINT_SETTINGS_COLLATE. - + line="759">Sets the value of %GTK_PRINT_SETTINGS_COLLATE. + @@ -111558,13 +114083,13 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="761">a `GtkPrintSettings` whether to collate the output + line="762">whether to collate the output @@ -111573,8 +114098,8 @@ If the file could not be loaded then error is set to either a c:identifier="gtk_print_settings_set_default_source"> Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. - + line="1425">Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. + @@ -111582,13 +114107,13 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="1427">a `GtkPrintSettings` the default source + line="1428">the default source @@ -111596,8 +114121,8 @@ If the file could not be loaded then error is set to either a Sets the value of %GTK_PRINT_SETTINGS_DITHER. - + line="1485">Sets the value of %GTK_PRINT_SETTINGS_DITHER. + @@ -111605,13 +114130,13 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="1487">a `GtkPrintSettings` the dithering that is used + line="1488">the dithering that is used @@ -111619,8 +114144,8 @@ If the file could not be loaded then error is set to either a Sets @key to a double value. - + line="340">Sets @key to a double value. + @@ -111628,19 +114153,19 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="342">a `GtkPrintSettings` a key + line="343">a key a double value + line="344">a double value @@ -111648,8 +114173,8 @@ If the file could not be loaded then error is set to either a Sets the value of %GTK_PRINT_SETTINGS_DUPLEX. - + line="833">Sets the value of %GTK_PRINT_SETTINGS_DUPLEX. + @@ -111657,13 +114182,13 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="835">a `GtkPrintSettings` a `GtkPrintDuplex` value + line="836">a `GtkPrintDuplex` value @@ -111672,8 +114197,8 @@ If the file could not be loaded then error is set to either a c:identifier="gtk_print_settings_set_finishings"> Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS. - + line="1513">Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS. + @@ -111681,13 +114206,13 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="1515">a `GtkPrintSettings` the finishings + line="1516">the finishings @@ -111695,8 +114220,8 @@ If the file could not be loaded then error is set to either a Sets @key to an integer value. - + line="441">Sets @key to an integer value. + @@ -111704,19 +114229,19 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="443">a `GtkPrintSettings` a key + line="444">a key an integer + line="445">an integer @@ -111724,8 +114249,8 @@ If the file could not be loaded then error is set to either a Associates a length in units of @unit with @key. - + line="381">Associates a length in units of @unit with @key. + @@ -111733,25 +114258,25 @@ If the file could not be loaded then error is set to either a a `GtkPrintSettings` + line="383">a `GtkPrintSettings` a key + line="384">a key a length + line="385">a length the unit of @length + line="386">the unit of @length @@ -111760,10 +114285,10 @@ If the file could not be loaded then error is set to either a c:identifier="gtk_print_settings_set_media_type"> Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. + line="1455">Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. - + @@ -111771,13 +114296,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1457">a `GtkPrintSettings` the media type + line="1458">the media type @@ -111786,8 +114311,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_n_copies"> Sets the value of %GTK_PRINT_SETTINGS_N_COPIES. - + line="1060">Sets the value of %GTK_PRINT_SETTINGS_N_COPIES. + @@ -111795,13 +114320,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1062">a `GtkPrintSettings` the number of copies + line="1063">the number of copies @@ -111810,8 +114335,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_number_up"> Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. - + line="1089">Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. + @@ -111819,13 +114344,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1091">a `GtkPrintSettings` the number of pages per sheet + line="1092">the number of pages per sheet @@ -111834,8 +114359,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_number_up_layout"> Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. - + line="1022">Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. + @@ -111843,13 +114368,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1024">a `GtkPrintSettings` a `GtkNumberUpLayout` value + line="1025">a `GtkNumberUpLayout` value @@ -111858,8 +114383,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_orientation"> Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION. - + line="537">Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION. + @@ -111867,13 +114392,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="539">a `GtkPrintSettings` a page orientation + line="540">a page orientation @@ -111882,8 +114407,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_output_bin"> Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. - + line="1541">Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. + @@ -111891,13 +114416,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1543">a `GtkPrintSettings` the output bin + line="1544">the output bin @@ -111906,8 +114431,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_page_ranges"> Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. - + line="1374">Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. + @@ -111915,13 +114440,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1376">a `GtkPrintSettings` an array of `GtkPageRange`s + line="1377">an array of `GtkPageRange`s @@ -111929,7 +114454,7 @@ The set of media types is defined in PWG 5101.1-2002 PWG. the length of @page_ranges + line="1378">the length of @page_ranges @@ -111938,8 +114463,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_page_set"> Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET. - + line="953">Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET. + @@ -111947,13 +114472,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="955">a `GtkPrintSettings` a `GtkPageSet` value + line="956">a `GtkPageSet` value @@ -111962,8 +114487,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_paper_height"> Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT. - + line="693">Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT. + @@ -111971,19 +114496,19 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="695">a `GtkPrintSettings` the paper height + line="696">the paper height the units of @height + line="697">the units of @height @@ -111992,10 +114517,10 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_paper_size"> Sets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, + line="600">Sets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, %GTK_PRINT_SETTINGS_PAPER_WIDTH and %GTK_PRINT_SETTINGS_PAPER_HEIGHT. - + @@ -112003,13 +114528,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="602">a `GtkPrintSettings` a paper size + line="603">a paper size @@ -112018,8 +114543,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_paper_width"> Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH. - + line="658">Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH. + @@ -112027,19 +114552,19 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="660">a `GtkPrintSettings` the paper width + line="661">the paper width the units of @width + line="662">the units of @width @@ -112048,8 +114573,8 @@ The set of media types is defined in PWG 5101.1-2002 PWG. c:identifier="gtk_print_settings_set_print_pages"> Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. - + line="1280">Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. + @@ -112057,13 +114582,13 @@ The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` + line="1282">a `GtkPrintSettings` a `GtkPrintPages` value + line="1283">a `GtkPrintPages` value @@ -112071,9 +114596,9 @@ The set of media types is defined in PWG 5101.1-2002 PWG. Convenience function to set %GTK_PRINT_SETTINGS_PRINTER + line="491">Convenience function to set %GTK_PRINT_SETTINGS_PRINTER to @printer. - + @@ -112081,13 +114606,13 @@ to @printer. a `GtkPrintSettings` + line="493">a `GtkPrintSettings` the printer name + line="494">the printer name @@ -112096,8 +114621,8 @@ to @printer. c:identifier="gtk_print_settings_set_printer_lpi"> Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. - + line="1204">Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. + @@ -112105,13 +114630,13 @@ to @printer. a `GtkPrintSettings` + line="1206">a `GtkPrintSettings` the resolution in lpi (lines per inch) + line="1207">the resolution in lpi (lines per inch) @@ -112119,8 +114644,8 @@ to @printer. Sets the value of %GTK_PRINT_SETTINGS_QUALITY. - + line="893">Sets the value of %GTK_PRINT_SETTINGS_QUALITY. + @@ -112128,13 +114653,13 @@ to @printer. a `GtkPrintSettings` + line="895">a `GtkPrintSettings` a `GtkPrintQuality` value + line="896">a `GtkPrintQuality` value @@ -112143,10 +114668,10 @@ to @printer. c:identifier="gtk_print_settings_set_resolution"> Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, + line="1118">Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. - + @@ -112154,13 +114679,13 @@ to @printer. a `GtkPrintSettings` + line="1120">a `GtkPrintSettings` the resolution in dpi + line="1121">the resolution in dpi @@ -112169,10 +114694,10 @@ to @printer. c:identifier="gtk_print_settings_set_resolution_xy"> Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, + line="1167">Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. - + @@ -112180,19 +114705,19 @@ to @printer. a `GtkPrintSettings` + line="1169">a `GtkPrintSettings` the horizontal resolution in dpi + line="1170">the horizontal resolution in dpi the vertical resolution in dpi + line="1171">the vertical resolution in dpi @@ -112200,8 +114725,8 @@ to @printer. Sets the value of %GTK_PRINT_SETTINGS_REVERSE. - + line="790">Sets the value of %GTK_PRINT_SETTINGS_REVERSE. + @@ -112209,13 +114734,13 @@ to @printer. a `GtkPrintSettings` + line="792">a `GtkPrintSettings` whether to reverse the output + line="793">whether to reverse the output @@ -112223,8 +114748,8 @@ to @printer. Sets the value of %GTK_PRINT_SETTINGS_SCALE. - + line="1235">Sets the value of %GTK_PRINT_SETTINGS_SCALE. + @@ -112232,13 +114757,13 @@ to @printer. a `GtkPrintSettings` + line="1237">a `GtkPrintSettings` the scale in percent + line="1238">the scale in percent @@ -112247,8 +114772,8 @@ to @printer. c:identifier="gtk_print_settings_set_use_color"> Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR. - + line="727">Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR. + @@ -112256,13 +114781,13 @@ to @printer. a `GtkPrintSettings` + line="729">a `GtkPrintSettings` whether to use color + line="730">whether to use color @@ -112272,28 +114797,28 @@ to @printer. throws="1"> This function saves the print settings from @settings to @file_name. + line="1715">This function saves the print settings from @settings to @file_name. If the file could not be written then error is set to either a `GFileError` or `GKeyFileError`. - + %TRUE on success + line="1726">%TRUE on success a `GtkPrintSettings` + line="1717">a `GtkPrintSettings` the file to save to + line="1718">the file to save to @@ -112301,19 +114826,19 @@ If the file could not be written then error is set to either a Serialize print settings to an a{sv} variant. - + line="1813">Serialize print settings to an a{sv} variant. + a new, floating, `GVariant` + line="1819">a new, floating, `GVariant` a `GtkPrintSettings` + line="1815">a `GtkPrintSettings` @@ -112321,8 +114846,8 @@ If the file could not be written then error is set to either a This function adds the print settings from @settings to @key_file. - + line="1774">This function adds the print settings from @settings to @key_file. + @@ -112330,13 +114855,13 @@ If the file could not be written then error is set to either a a `GtkPrintSettings` + line="1776">a `GtkPrintSettings` the `GKeyFile` to save the print settings to + line="1777">the `GKeyFile` to save the print settings to the group to add the settings to in @key_file, or + line="1778">the group to add the settings to in @key_file, or %NULL to use the default “Print Settings” @@ -112354,10 +114879,10 @@ If the file could not be written then error is set to either a Removes any value associated with @key. + line="186">Removes any value associated with @key. This has the same effect as setting the value to %NULL. - + @@ -112365,28 +114890,38 @@ This has the same effect as setting the value to %NULL. a `GtkPrintSettings` + line="188">a `GtkPrintSettings` a key + line="189">a key - + Function called by [method@Gtk.PrintSettings.foreach] on every key/value pair +inside a [class@Gtk.PrintSettings]. + + the setting key + the setting value nullable="1" allow-none="1" closure="2"> + The user data provided with the function + + An auxiliary object for printing that allows decoupling the setup from the printing. + +A print setup is obtained by calling [method@Gtk.PrintDialog.setup], +and can later be passed to print functions such as [method@Gtk.PrintDialog.print]. + +Print setups can be reused for multiple print calls. + +Applications may wish to store the page_setup and print_settings from the print setup +and copy them to the PrintDialog if they want to keep using them. + + + Returns the page setup of @setup. + +It may be different from the `GtkPrintDialog`'s page setup +if the user changed it during the setup process. + + + the page setup, or `NULL` + + + + + a `GtkPrintSetup` + + + + + + Returns the print settings of @setup. + +They may be different from the `GtkPrintDialog`'s settings +if the user changed them during the setup process. + + + the print settings, or `NULL` + + + + + a `GtkPrintSetup` + + + + + + Increase the reference count of @setup. + + + the print setup + + + + + a `GtkPrintSetup` + + + + + + Decrease the reference count of @setup. + +If the reference count reaches zero, +the object is freed. + + + + + + + a `GtkPrintSetup` + + + + + glib:get-type="gtk_print_unix_dialog_get_type"> `GtkPrintUnixDialog` implements a print dialog for platforms -which don’t provide a native print dialog, like Unix. + line="45">A print dialog for platforms which don’t provide a native +print dialog, like Unix. -![An example GtkPrintUnixDialog](printdialog.png) +<picture> + <source srcset="printdialog-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkPrintUnixDialog" src="printdialog.png"> +</picture> It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API with @@ -112567,12 +115218,12 @@ dialog and print are added. Creates a new `GtkPrintUnixDialog`. + line="2975">Creates a new `GtkPrintUnixDialog`. a new `GtkPrintUnixDialog` + line="2982">a new `GtkPrintUnixDialog` @@ -112582,7 +115233,7 @@ dialog and print are added. allow-none="1"> Title of the dialog + line="2977">Title of the dialog allow-none="1"> Transient parent of the dialog + line="2978">Transient parent of the dialog @@ -112600,7 +115251,7 @@ dialog and print are added. c:identifier="gtk_print_unix_dialog_add_custom_tab"> Adds a custom tab to the print dialog. + line="3275">Adds a custom tab to the print dialog. @@ -112609,19 +115260,19 @@ dialog and print are added. a `GtkPrintUnixDialog` + line="3277">a `GtkPrintUnixDialog` the widget to put in the custom tab + line="3278">the widget to put in the custom tab the widget to use as tab label + line="3279">the widget to use as tab label @@ -112629,22 +115280,21 @@ dialog and print are added. - Gets the current page of the `GtkPrintUnixDialog`. + line="3098">Gets the current page of the `GtkPrintUnixDialog`. the current page of @dialog + line="3104">the current page of @dialog a `GtkPrintUnixDialog` + line="3100">a `GtkPrintUnixDialog` @@ -112652,23 +115302,21 @@ dialog and print are added. - Gets whether to embed the page setup. + line="3476">Gets whether to embed the page setup. whether to embed the page setup + line="3482">whether to embed the page setup a `GtkPrintUnixDialog` + line="3478">a `GtkPrintUnixDialog` @@ -112676,22 +115324,21 @@ dialog and print are added. - Gets whether there is a selection. + line="3416">Gets whether there is a selection. whether there is a selection + line="3422">whether there is a selection a `GtkPrintUnixDialog` + line="3418">a `GtkPrintUnixDialog` @@ -112699,23 +115346,21 @@ dialog and print are added. - Gets the capabilities that have been set on this `GtkPrintUnixDialog`. + line="3326">Gets the capabilities that have been set on this `GtkPrintUnixDialog`. the printing capabilities + line="3332">the printing capabilities a `GtkPrintUnixDialog` + line="3328">a `GtkPrintUnixDialog` @@ -112723,22 +115368,21 @@ dialog and print are added. - Gets the page setup that is used by the `GtkPrintUnixDialog`. + line="3039">Gets the page setup that is used by the `GtkPrintUnixDialog`. the page setup of @dialog. + line="3045">the page setup of @dialog. a `GtkPrintUnixDialog` + line="3041">a `GtkPrintUnixDialog` @@ -112747,19 +115391,19 @@ dialog and print are added. c:identifier="gtk_print_unix_dialog_get_page_setup_set"> Gets whether a page setup was set by the user. + line="3055">Gets whether a page setup was set by the user. whether a page setup was set by user. + line="3061">whether a page setup was set by user. a `GtkPrintUnixDialog` + line="3057">a `GtkPrintUnixDialog` @@ -112767,33 +115411,31 @@ dialog and print are added. - Gets the currently selected printer. + line="2998">Gets the currently selected printer. the currently selected printer + line="3004">the currently selected printer a `GtkPrintUnixDialog` + line="3000">a `GtkPrintUnixDialog` - + c:identifier="gtk_print_unix_dialog_get_settings" + glib:get-property="print-settings"> Gets a new `GtkPrintSettings` object that represents the + line="3207">Gets a new `GtkPrintSettings` object that represents the current values in the print dialog. Note that this creates a new object, and you need to unref @@ -112802,14 +115444,14 @@ it if don’t want to keep it. a new `GtkPrintSettings` object with the values from @dialog + line="3217">a new `GtkPrintSettings` object with the values from @dialog a `GtkPrintUnixDialog` + line="3209">a `GtkPrintUnixDialog` @@ -112817,23 +115459,21 @@ it if don’t want to keep it. - Gets whether the print dialog allows user to print a selection. + line="3370">Gets whether the print dialog allows user to print a selection. whether the application supports print of selection + line="3376">whether the application supports print of selection a `GtkPrintUnixDialog` + line="3372">a `GtkPrintUnixDialog` @@ -112841,10 +115481,9 @@ it if don’t want to keep it. - Sets the current page number. + line="3071">Sets the current page number. If @current_page is not -1, this enables the current page choice for the range of pages to print. @@ -112856,13 +115495,13 @@ for the range of pages to print. a `GtkPrintUnixDialog` + line="3073">a `GtkPrintUnixDialog` the current page number. + line="3074">the current page number. @@ -112870,11 +115509,9 @@ for the range of pages to print. - Embed page size combo box and orientation combo box into page setup page. + line="3432">Embed page size combo box and orientation combo box into page setup page. @@ -112883,13 +115520,13 @@ for the range of pages to print. a `GtkPrintUnixDialog` + line="3434">a `GtkPrintUnixDialog` embed page setup selection + line="3435">embed page setup selection @@ -112897,10 +115534,9 @@ for the range of pages to print. - Sets whether a selection exists. + line="3386">Sets whether a selection exists. @@ -112909,13 +115545,13 @@ for the range of pages to print. a `GtkPrintUnixDialog` + line="3388">a `GtkPrintUnixDialog` %TRUE indicates that a selection exists + line="3389">%TRUE indicates that a selection exists @@ -112923,11 +115559,9 @@ for the range of pages to print. - This lets you specify the printing capabilities your application + line="3294">This lets you specify the printing capabilities your application supports. For instance, if you can handle scaling the output then you pass @@ -112942,13 +115576,13 @@ handles scaling. a `GtkPrintUnixDialog` + line="3296">a `GtkPrintUnixDialog` the printing capabilities of your application + line="3297">the printing capabilities of your application @@ -112956,10 +115590,9 @@ handles scaling. - Sets the page setup of the `GtkPrintUnixDialog`. + line="3014">Sets the page setup of the `GtkPrintUnixDialog`. @@ -112968,23 +115601,23 @@ handles scaling. a `GtkPrintUnixDialog` + line="3016">a `GtkPrintUnixDialog` a `GtkPageSetup` + line="3017">a `GtkPageSetup` - + c:identifier="gtk_print_unix_dialog_set_settings" + glib:set-property="print-settings"> Sets the `GtkPrintSettings` for the `GtkPrintUnixDialog`. + line="3145">Sets the `GtkPrintSettings` for the `GtkPrintUnixDialog`. Typically, this is used to restore saved print settings from a previous print operation before the print dialog @@ -112997,7 +115630,7 @@ is shown. a `GtkPrintUnixDialog` + line="3147">a `GtkPrintUnixDialog` allow-none="1"> a `GtkPrintSettings` + line="3148">a `GtkPrintSettings` @@ -113014,11 +115647,9 @@ is shown. - Sets whether the print dialog allows user to print a selection. + line="3342">Sets whether the print dialog allows user to print a selection. @@ -113027,13 +115658,13 @@ is shown. a `GtkPrintUnixDialog` + line="3344">a `GtkPrintUnixDialog` %TRUE to allow print selection + line="3345">%TRUE to allow print selection @@ -113044,13 +115675,9 @@ is shown. setter="set_current_page" getter="get_current_page" default-value="-1"> - - The current page in the document. + line="417">The current page in the document. setter="set_embed_page_setup" getter="get_embed_page_setup" default-value="FALSE"> - - %TRUE if the page setup controls are embedded. + line="486">%TRUE if the page setup controls are embedded. setter="set_has_selection" getter="get_has_selection" default-value="FALSE"> - - Whether the application has a selection. + line="475">Whether the application has a selection. setter="set_manual_capabilities" getter="get_manual_capabilities" default-value="0"> - - Capabilities the application can handle. + line="452">Capabilities the application can handle. transfer-ownership="none" setter="set_page_setup" getter="get_page_setup"> - - The `GtkPageSetup` object to use. + line="406">The `GtkPageSetup` object to use. - - - + The `GtkPrintSettings` object used for this dialog. + line="430">The `GtkPrintSettings` object used for this dialog. - The `GtkPrinter` which is selected. + line="441">The `GtkPrinter` which is selected. setter="set_support_selection" getter="get_support_selection" default-value="FALSE"> - - Whether the dialog supports selection. + line="464">Whether the dialog supports selection. @@ -113156,7 +115761,7 @@ is shown. glib:get-type="gtk_printer_get_type"> A `GtkPrinter` object represents a printer. + line="34">Represents a printer. You only need to deal directly with printers if you use the non-portable [class@Gtk.PrintUnixDialog] API. @@ -113168,75 +115773,77 @@ a [class@Gtk.PrintJob] object, which lets you print to the printer. Creates a new `GtkPrinter`. + line="404">Creates a new `GtkPrinter`. a new `GtkPrinter` + line="412">a new `GtkPrinter` the name of the printer + line="406">the name of the printer a `GtkPrintBackend` + line="407">a `GtkPrintBackend` whether the printer is virtual + line="408">whether the printer is virtual - - + Returns whether the printer accepts input in + line="789">Returns whether the printer accepts input in PDF format. %TRUE if @printer accepts PDF + line="796">%TRUE if @printer accepts PDF a `GtkPrinter` + line="791">a `GtkPrinter` - - + Returns whether the printer accepts input in + line="819">Returns whether the printer accepts input in PostScript format. %TRUE if @printer accepts PostScript + line="826">%TRUE if @printer accepts PostScript a `GtkPrinter` + line="821">a `GtkPrinter` @@ -113244,12 +115851,12 @@ PostScript format. Compares two printers. + line="1122">Compares two printers. 0 if the printer match, a negative value if @a < @b, + line="1129">0 if the printer match, a negative value if @a < @b, or a positive value if @a > @b @@ -113257,34 +115864,33 @@ PostScript format. a `GtkPrinter` + line="1124">a `GtkPrinter` another `GtkPrinter` + line="1125">another `GtkPrinter` - Returns the backend of the printer. + line="430">Returns the backend of the printer. the backend of @printer + line="436">the backend of @printer a `GtkPrinter` + line="432">a `GtkPrinter` @@ -113293,7 +115899,7 @@ PostScript format. c:identifier="gtk_printer_get_capabilities"> Returns the printer’s capabilities. + line="1094">Returns the printer’s capabilities. This is useful when you’re using `GtkPrintUnixDialog`’s manual-capabilities setting and need to know which settings @@ -113306,14 +115912,14 @@ available, see [method@Gtk.Printer.has_details] and the printer’s capabilities + line="1108">the printer’s capabilities a `GtkPrinter` + line="1096">a `GtkPrinter` @@ -113322,12 +115928,12 @@ available, see [method@Gtk.Printer.has_details] and c:identifier="gtk_printer_get_default_page_size"> Returns default page size of @printer. + line="1006">Returns default page size of @printer. a newly allocated `GtkPageSetup` with default page size + line="1012">a newly allocated `GtkPageSetup` with default page size of the printer. @@ -113335,7 +115941,7 @@ available, see [method@Gtk.Printer.has_details] and a `GtkPrinter` + line="1008">a `GtkPrinter` @@ -113344,19 +115950,19 @@ available, see [method@Gtk.Printer.has_details] and c:identifier="gtk_printer_get_description"> Gets the description of the printer. + line="466">Gets the description of the printer. the description of @printer + line="472">the description of @printer a `GtkPrinter` + line="468">a `GtkPrinter` @@ -113365,7 +115971,7 @@ available, see [method@Gtk.Printer.has_details] and c:identifier="gtk_printer_get_hard_margins"> Retrieve the hard margins of @printer. + line="1028">Retrieve the hard margins of @printer. These are the margins that define the area at the borders of the paper that the printer cannot print to. @@ -113377,14 +115983,14 @@ available, see [method@Gtk.Printer.has_details] and %TRUE iff the hard margins were retrieved + line="1045">%TRUE iff the hard margins were retrieved a `GtkPrinter` + line="1030">a `GtkPrinter` a location to store the top margin in + line="1031">a location to store the top margin in a location to store the bottom margin in + line="1032">a location to store the bottom margin in a location to store the left margin in + line="1033">a location to store the left margin in a location to store the right margin in + line="1034">a location to store the right margin in @@ -113429,7 +116035,7 @@ available, see [method@Gtk.Printer.has_details] and c:identifier="gtk_printer_get_hard_margins_for_paper_size"> Retrieve the hard margins of @printer for @paper_size. + line="1060">Retrieve the hard margins of @printer for @paper_size. These are the margins that define the area at the borders of the paper that the printer cannot print to. @@ -113441,20 +116047,20 @@ available, see [method@Gtk.Printer.has_details] and %TRUE iff the hard margins were retrieved + line="1078">%TRUE iff the hard margins were retrieved a `GtkPrinter` + line="1062">a `GtkPrinter` a `GtkPaperSize` + line="1063">a `GtkPaperSize` a location to store the top margin in + line="1064">a location to store the top margin in a location to store the bottom margin in + line="1065">a location to store the bottom margin in a location to store the left margin in + line="1066">a location to store the left margin in a location to store the right margin in + line="1067">a location to store the right margin in @@ -113498,22 +116104,21 @@ available, see [method@Gtk.Printer.has_details] and - Gets the name of the icon to use for the printer. + line="574">Gets the name of the icon to use for the printer. the icon name for @printer + line="580">the icon name for @printer a `GtkPrinter` + line="576">a `GtkPrinter` @@ -113521,22 +116126,21 @@ available, see [method@Gtk.Printer.has_details] and - Gets the number of jobs currently queued on the printer. + line="605">Gets the number of jobs currently queued on the printer. the number of jobs on @printer + line="611">the number of jobs on @printer a `GtkPrinter` + line="607">a `GtkPrinter` @@ -113544,22 +116148,21 @@ available, see [method@Gtk.Printer.has_details] and - Returns a description of the location of the printer. + line="538">Returns a description of the location of the printer. the location of @printer + line="544">the location of @printer a `GtkPrinter` + line="540">a `GtkPrinter` @@ -113567,22 +116170,21 @@ available, see [method@Gtk.Printer.has_details] and - Returns the name of the printer. + line="448">Returns the name of the printer. the name of @printer + line="454">the name of @printer a `GtkPrinter` + line="450">a `GtkPrinter` @@ -113590,23 +116192,22 @@ available, see [method@Gtk.Printer.has_details] and - Returns the state message describing the current state + line="501">Returns the state message describing the current state of the printer. the state message of @printer + line="508">the state message of @printer a `GtkPrinter` + line="503">a `GtkPrinter` @@ -113614,41 +116215,41 @@ of the printer. Returns whether the printer details are available. + line="641">Returns whether the printer details are available. %TRUE if @printer details are available + line="647">%TRUE if @printer details are available a `GtkPrinter` + line="643">a `GtkPrinter` - + c:identifier="gtk_printer_is_accepting_jobs" + glib:get-property="accepting-jobs"> Returns whether the printer is accepting jobs + line="735">Returns whether the printer is accepting jobs %TRUE if @printer is accepting jobs + line="741">%TRUE if @printer is accepting jobs a `GtkPrinter` + line="737">a `GtkPrinter` @@ -113656,20 +116257,20 @@ of the printer. Returns whether the printer is currently active (i.e. + line="668">Returns whether the printer is currently active (i.e. accepts new jobs). %TRUE if @printer is active + line="675">%TRUE if @printer is active a `GtkPrinter` + line="670">a `GtkPrinter` @@ -113677,28 +116278,29 @@ accepts new jobs). Returns whether the printer is the default printer. + line="871">Returns whether the printer is the default printer. %TRUE if @printer is the default + line="877">%TRUE if @printer is the default a `GtkPrinter` + line="873">a `GtkPrinter` - - + Returns whether the printer is currently paused. + line="698">Returns whether the printer is currently paused. A paused printer still accepts jobs, but it is not printing them. @@ -113706,37 +116308,38 @@ printing them. %TRUE if @printer is paused + line="707">%TRUE if @printer is paused a `GtkPrinter` + line="700">a `GtkPrinter` - - + Returns whether the printer is virtual (i.e. does not + line="769">Returns whether the printer is virtual (i.e. does not represent actual printer hardware, but something like a CUPS class). %TRUE if @printer is virtual + line="777">%TRUE if @printer is virtual a `GtkPrinter` + line="771">a `GtkPrinter` @@ -113744,7 +116347,7 @@ a CUPS class). Lists all the paper sizes @printer supports. + line="981">Lists all the paper sizes @printer supports. This will return and empty list unless the printer’s details are available, see [method@Gtk.Printer.has_details] and @@ -113753,7 +116356,7 @@ are available, see [method@Gtk.Printer.has_details] and a newly + line="991">a newly allocated list of newly allocated `GtkPageSetup`s. @@ -113763,7 +116366,7 @@ are available, see [method@Gtk.Printer.has_details] and a `GtkPrinter` + line="983">a `GtkPrinter` @@ -113772,7 +116375,7 @@ are available, see [method@Gtk.Printer.has_details] and c:identifier="gtk_printer_request_details"> Requests the printer details. + line="900">Requests the printer details. When the details are available, the [signal@Gtk.Printer::details-acquired] signal @@ -113785,42 +116388,40 @@ will be emitted on @printer. a `GtkPrinter` + line="902">a `GtkPrinter` - %TRUE if the printer is accepting jobs. + line="233">%TRUE if the printer is accepting jobs. - %TRUE if this printer can accept PDF. + line="151">%TRUE if this printer can accept PDF. - %TRUE if this printer can accept PostScript. + line="162">%TRUE if this printer can accept PostScript. writable="1" construct-only="1" transfer-ownership="none"> - The backend for the printer. + line="129">The backend for the printer. - Icon name to use for the printer. + line="195">Icon name to use for the printer. - %FALSE if this represents a real hardware device. + line="140">%FALSE if this represents a real hardware device. - Number of jobs queued in the printer. + line="206">Number of jobs queued in the printer. - Information about the location of the printer. + line="184">Information about the location of the printer. construct-only="1" transfer-ownership="none" getter="get_name"> - The name of the printer. + line="118">The name of the printer. - - + %TRUE if this printer is paused. + line="219">%TRUE if this printer is paused. A paused printer still accepts jobs, but it does not print them. @@ -113902,17 +116496,15 @@ not print them. - String giving the current status of the printer. + line="173">String giving the current status of the printer. Emitted in response to a request for detailed information + line="244">Emitted in response to a request for detailed information about a printer from the print backend. The @success parameter indicates if the information was @@ -113924,7 +116516,7 @@ actually obtained. %TRUE if the details were successfully acquired + line="247">%TRUE if the details were successfully acquired @@ -113971,13 +116563,15 @@ a reference to it after the function has returned. glib:get-type="gtk_progress_bar_get_type"> `GtkProgressBar` is typically used to display the progress of a long -running operation. + line="43">Displays the progress of a long-running operation. -It provides a visual clue that processing is underway. `GtkProgressBar` -can be used in two different modes: percentage mode and activity mode. +`GtkProgressBar` provides a visual clue that processing is underway. +It can be used in two different modes: percentage mode and activity mode. -![An example GtkProgressBar](progressbar.png) +<picture> + <source srcset="progressbar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkProgressBar" src="progressbar.png"> +</picture> When an application can determine how much work needs to take place (e.g. read a fixed number of bytes from a file) and can monitor its @@ -114016,7 +116610,7 @@ in overlays like the one Epiphany has for page loading progress. # Accessibility -`GtkProgressBar` uses the %GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role. +`GtkProgressBar` uses the [enum@Gtk.AccessibleRole.progress_bar] role. @@ -114025,36 +116619,35 @@ in overlays like the one Epiphany has for page loading progress. Creates a new `GtkProgressBar`. + line="581">Creates a new `GtkProgressBar`. a `GtkProgressBar`. + line="586">a `GtkProgressBar`. - Returns the ellipsizing position of the progress bar. + line="1142">Returns the ellipsizing position of the progress bar. See [method@Gtk.ProgressBar.set_ellipsize]. `PangoEllipsizeMode` + line="1150">`PangoEllipsizeMode` a `GtkProgressBar` + line="1144">a `GtkProgressBar` @@ -114062,22 +116655,21 @@ See [method@Gtk.ProgressBar.set_ellipsize]. - Returns the current fraction of the task that’s been completed. + line="1063">Returns the current fraction of the task that’s been completed. a fraction from 0.0 to 1.0 + line="1069">a fraction from 0.0 to 1.0 a `GtkProgressBar` + line="1065">a `GtkProgressBar` @@ -114085,22 +116677,21 @@ See [method@Gtk.ProgressBar.set_ellipsize]. - Returns whether the progress bar is inverted. + line="1097">Returns whether the progress bar is inverted. %TRUE if the progress bar is inverted + line="1103">%TRUE if the progress bar is inverted a `GtkProgressBar` + line="1099">a `GtkProgressBar` @@ -114108,24 +116699,23 @@ See [method@Gtk.ProgressBar.set_ellipsize]. - Retrieves the pulse step. + line="1079">Retrieves the pulse step. See [method@Gtk.ProgressBar.set_pulse_step]. a fraction from 0.0 to 1.0 + line="1087">a fraction from 0.0 to 1.0 a `GtkProgressBar` + line="1081">a `GtkProgressBar` @@ -114133,24 +116723,23 @@ See [method@Gtk.ProgressBar.set_pulse_step]. - Returns whether the `GtkProgressBar` shows text. + line="931">Returns whether the `GtkProgressBar` shows text. See [method@Gtk.ProgressBar.set_show_text]. %TRUE if text is shown in the progress bar + line="939">%TRUE if text is shown in the progress bar a `GtkProgressBar` + line="933">a `GtkProgressBar` @@ -114158,10 +116747,9 @@ See [method@Gtk.ProgressBar.set_show_text]. - Retrieves the text that is displayed with the progress bar. + line="1044">Retrieves the text that is displayed with the progress bar. The return value is a reference to the text, not a copy of it, so will become invalid if you change the text in the progress bar. @@ -114169,14 +116757,14 @@ so will become invalid if you change the text in the progress bar. the text + line="1053">the text a `GtkProgressBar` + line="1046">a `GtkProgressBar` @@ -114184,7 +116772,7 @@ so will become invalid if you change the text in the progress bar. Indicates that some progress has been made, but you don’t know how much. + line="825">Indicates that some progress has been made, but you don’t know how much. Causes the progress bar to enter “activity mode,” where a block bounces back and forth. Each call to [method@Gtk.ProgressBar.pulse] @@ -114198,7 +116786,7 @@ per pulse is determined by [method@Gtk.ProgressBar.set_pulse_step]). a `GtkProgressBar` + line="827">a `GtkProgressBar` @@ -114206,10 +116794,9 @@ per pulse is determined by [method@Gtk.ProgressBar.set_pulse_step]). - Sets the mode used to ellipsize the text. + line="1113">Sets the mode used to ellipsize the text. The text is ellipsized if there is not enough space to render the entire string. @@ -114221,13 +116808,13 @@ to render the entire string. a `GtkProgressBar` + line="1115">a `GtkProgressBar` a `PangoEllipsizeMode` + line="1116">a `PangoEllipsizeMode` @@ -114235,10 +116822,9 @@ to render the entire string. - Causes the progress bar to “fill in” the given fraction + line="761">Causes the progress bar to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. @@ -114250,13 +116836,13 @@ The fraction should be between 0.0 and 1.0, inclusive. a `GtkProgressBar` + line="763">a `GtkProgressBar` fraction of the task that’s been completed + line="764">fraction of the task that’s been completed @@ -114264,10 +116850,9 @@ The fraction should be between 0.0 and 1.0, inclusive. - Sets whether the progress bar is inverted. + line="1017">Sets whether the progress bar is inverted. Progress bars normally grow from top to bottom or left to right. Inverted progress bars grow in the opposite direction. @@ -114279,13 +116864,13 @@ Inverted progress bars grow in the opposite direction. a `GtkProgressBar` + line="1019">a `GtkProgressBar` %TRUE to invert the progress bar + line="1020">%TRUE to invert the progress bar @@ -114293,10 +116878,9 @@ Inverted progress bars grow in the opposite direction. - Sets the fraction of total progress bar length to move the + line="949">Sets the fraction of total progress bar length to move the bouncing block. The bouncing block is moved when [method@Gtk.ProgressBar.pulse] @@ -114309,13 +116893,13 @@ is called. a `GtkProgressBar` + line="951">a `GtkProgressBar` fraction between 0.0 and 1.0 + line="952">fraction between 0.0 and 1.0 @@ -114323,10 +116907,9 @@ is called. - Sets whether the progress bar will show text next to the bar. + line="881">Sets whether the progress bar will show text next to the bar. The shown text is either the value of the [property@Gtk.ProgressBar:text] property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value, @@ -114343,13 +116926,13 @@ to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). a `GtkProgressBar` + line="883">a `GtkProgressBar` whether to show text + line="884">whether to show text @@ -114357,10 +116940,9 @@ to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). - Causes the given @text to appear next to the progress bar. + line="845">Causes the given @text to appear next to the progress bar. If @text is %NULL and [property@Gtk.ProgressBar:show-text] is %TRUE, the current value of [property@Gtk.ProgressBar:fraction] will be displayed @@ -114379,7 +116961,7 @@ be styled and sized suitably for containing text, as long as a `GtkProgressBar` + line="847">a `GtkProgressBar` a UTF-8 string + line="848">a UTF-8 string @@ -114399,13 +116981,9 @@ be styled and sized suitably for containing text, as long as setter="set_ellipsize" getter="get_ellipsize" default-value="PANGO_ELLIPSIZE_NONE"> - - The preferred place to ellipsize the string. + line="248">The preferred place to ellipsize the string. The text will be ellipsized if the progress bar does not have enough room to display the entire string, specified as a `PangoEllipsizeMode`. @@ -114422,13 +117000,9 @@ progress bar's width is [method@Gtk.Widget.set_size_request]. setter="set_fraction" getter="get_fraction" default-value="0.000000"> - - The fraction of total work that has been completed. + line="197">The fraction of total work that has been completed. setter="set_inverted" getter="get_inverted" default-value="FALSE"> - - Invert the direction in which the progress bar grows. + line="187">Invert the direction in which the progress bar grows. setter="set_pulse_step" getter="get_pulse_step" default-value="0.100000"> - - The fraction of total progress to move the bounding block when pulsed. + line="208">The fraction of total progress to move the bounding block when pulsed. setter="set_show_text" getter="get_show_text" default-value="FALSE"> - - Sets whether the progress bar will show a text in addition + line="229">Sets whether the progress bar will show a text in addition to the bar itself. The shown text is either the value of the [property@Gtk.ProgressBar:text] @@ -114491,13 +117053,9 @@ to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). - - Text to be displayed in the progress bar. + line="219">Text to be displayed in the progress bar. @@ -114507,7 +117065,7 @@ to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). Describes limits of a [class@EventController] for handling events + line="1042">Describes limits of a [class@EventController] for handling events targeting other widgets. glib:name="GTK_LIMIT_NONE"> Events are handled regardless of what their + line="1044">Events are handled regardless of what their target is. glib:name="GTK_LIMIT_SAME_NATIVE"> Events are only handled if their target - is in the same [iface@Native] as the event controllers widget. Note - that some event types have two targets (origin and destination). + line="1046">Events are only handled if their target is in + the same [iface@Native] (or widget with [property@Gtk.Widget:limit-events] + set) as the event controllers widget. + Note that some event types have two targets (origin and destination). c:type="GtkPropagationPhase"> Describes the stage at which events are fed into a [class@EventController]. + line="1018">Describes the stage at which events are fed into a [class@EventController]. glib:name="GTK_PHASE_NONE"> Events are not delivered. + line="1020">Events are not delivered. glib:name="GTK_PHASE_CAPTURE"> Events are delivered in the capture phase. The + line="1021">Events are delivered in the capture phase. The capture phase happens before the bubble phase, runs from the toplevel down to the event widget. This option should only be used on containers that might possibly handle events before their children do. @@ -114566,7 +117125,7 @@ targeting other widgets. glib:name="GTK_PHASE_BUBBLE"> Events are delivered in the bubble phase. The bubble + line="1025">Events are delivered in the bubble phase. The bubble phase happens after the capture phase, and before the default handlers are run. This phase runs from the event widget, up to the toplevel. @@ -114577,7 +117136,7 @@ targeting other widgets. glib:name="GTK_PHASE_TARGET"> Events are delivered in the default widget event handlers, + line="1028">Events are delivered in the default widget event handlers, note that widget implementations must chain up on button, motion, touch and grab broken handlers for controllers in this phase to be run. @@ -114591,11 +117150,11 @@ targeting other widgets. glib:fundamental="1"> A `GObject` property value in a `GtkExpression`. + line="1162">A `GObject` property value in a `GtkExpression`. Creates an expression that looks up a property. + line="1379">Creates an expression that looks up a property. The object to use is found by evaluating the `expression`, or using the `this` argument when `expression` is `NULL`. @@ -114609,14 +117168,14 @@ The given `this_type` must have a property with `property_name`. a new `GtkExpression` + line="1398">a new `GtkExpression` The type to expect for the this type + line="1381">The type to expect for the this type allow-none="1"> Expression to + line="1382">Expression to evaluate to get the object to query or `NULL` to query the `this` object @@ -114633,7 +117192,7 @@ The given `this_type` must have a property with `property_name`. name of the property + line="1385">name of the property @@ -114642,7 +117201,7 @@ The given `this_type` must have a property with `property_name`. c:identifier="gtk_property_expression_new_for_pspec"> Creates an expression that looks up a property. + line="1434">Creates an expression that looks up a property. The object to use is found by evaluating the `expression`, or using the `this` argument when `expression` is `NULL`. @@ -114654,7 +117213,7 @@ Otherwise, this expression's evaluation will fail. a new `GtkExpression` + line="1450">a new `GtkExpression` @@ -114664,7 +117223,7 @@ Otherwise, this expression's evaluation will fail. allow-none="1"> Expression to + line="1436">Expression to evaluate to get the object to query or `NULL` to query the `this` object @@ -114672,7 +117231,7 @@ Otherwise, this expression's evaluation will fail. the `GParamSpec` for the property to query + line="1439">the `GParamSpec` for the property to query @@ -114681,20 +117240,20 @@ Otherwise, this expression's evaluation will fail. c:identifier="gtk_property_expression_get_expression"> Gets the expression specifying the object of + line="1468">Gets the expression specifying the object of a property expression. the object expression + line="1475">the object expression a property `GtkExpression` + line="1470">a property `GtkExpression` @@ -114703,20 +117262,20 @@ a property expression. c:identifier="gtk_property_expression_get_pspec"> Gets the `GParamSpec` specifying the property of + line="1487">Gets the `GParamSpec` specifying the property of a property expression. the `GParamSpec` for the property + line="1494">the `GParamSpec` for the property a property `GtkExpression` + line="1489">a property `GtkExpression` @@ -114792,15 +117351,20 @@ a property expression. glib:type-struct="RangeClass"> `GtkRange` is the common base class for widgets which visualize an -adjustment. + line="53">Base class for widgets which visualize an adjustment. Widgets that are derived from `GtkRange` include [class@Gtk.Scale] and [class@Gtk.Scrollbar]. Apart from signals for monitoring the parameters of the adjustment, `GtkRange` provides properties and methods for setting a -“fill level” on range widgets. See [method@Gtk.Range.set_fill_level]. +“fill level” on range widgets. See [method@Gtk.Range.set_fill_level]. + +# Shortcuts and Gestures + +The `GtkRange` slider is draggable. Holding the <kbd>Shift</kbd> key while +dragging, or initiating the drag with a long-press will enable the +fine-tuning mode. @@ -114880,22 +117444,21 @@ Apart from signals for monitoring the parameters of the adjustment, - Get the adjustment which is the “model” object for `GtkRange`. + line="636">Get the adjustment which is the “model” object for `GtkRange`. a `GtkAdjustment` + line="642">a `GtkAdjustment` a `GtkRange` + line="638">a `GtkRange` @@ -114903,22 +117466,21 @@ Apart from signals for monitoring the parameters of the adjustment, - Gets the current position of the fill level indicator. + line="1294">Gets the current position of the fill level indicator. The current fill level + line="1300">The current fill level A `GtkRange` + line="1296">A `GtkRange` @@ -114926,21 +117488,21 @@ Apart from signals for monitoring the parameters of the adjustment, Gets whether the `GtkRange` respects text direction. + line="880">Gets whether the `GtkRange` respects text direction. See [method@Gtk.Range.set_flippable]. %TRUE if the range is flippable + line="888">%TRUE if the range is flippable a `GtkRange` + line="882">a `GtkRange` @@ -114948,24 +117510,23 @@ See [method@Gtk.Range.set_flippable]. - Gets whether the range is inverted. + line="828">Gets whether the range is inverted. See [method@Gtk.Range.set_inverted]. %TRUE if the range is inverted + line="836">%TRUE if the range is inverted a `GtkRange` + line="830">a `GtkRange` @@ -114973,7 +117534,7 @@ See [method@Gtk.Range.set_inverted]. This function returns the area that contains the range’s trough, + line="947">This function returns the area that contains the range’s trough, in coordinates relative to @range's origin. This function is useful mainly for `GtkRange` subclasses. @@ -114985,7 +117546,7 @@ This function is useful mainly for `GtkRange` subclasses. a `GtkRange` + line="949">a `GtkRange` transfer-ownership="none"> return location for the range rectangle + line="950">return location for the range rectangle @@ -115002,23 +117563,21 @@ This function is useful mainly for `GtkRange` subclasses. - Gets whether the range is restricted to the fill level. + line="1232">Gets whether the range is restricted to the fill level. %TRUE if @range is restricted to the fill level. + line="1238">%TRUE if @range is restricted to the fill level. A `GtkRange` + line="1234">A `GtkRange` @@ -115026,10 +117585,9 @@ This function is useful mainly for `GtkRange` subclasses. - Gets the number of digits to round the value to when + line="2921">Gets the number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. @@ -115037,14 +117595,14 @@ See [signal@Gtk.Range::change-value]. the number of digits to round to + line="2930">the number of digits to round to a `GtkRange` + line="2923">a `GtkRange` @@ -115052,22 +117610,21 @@ See [signal@Gtk.Range::change-value]. - Gets whether the range displays the fill level graphically. + line="1185">Gets whether the range displays the fill level graphically. %TRUE if @range shows the fill level. + line="1191">%TRUE if @range shows the fill level. A `GtkRange` + line="1187">A `GtkRange` @@ -115076,7 +117633,7 @@ See [signal@Gtk.Range::change-value]. c:identifier="gtk_range_get_slider_range"> This function returns sliders range along the long dimension, + line="982">This function returns sliders range along the long dimension, in widget->window coordinates. This function is useful mainly for `GtkRange` subclasses. @@ -115088,7 +117645,7 @@ This function is useful mainly for `GtkRange` subclasses. a `GtkRange` + line="984">a `GtkRange` allow-none="1"> return location for the slider's start + line="985">return location for the slider's start allow-none="1"> return location for the slider's end + line="986">return location for the slider's end @@ -115119,21 +117676,21 @@ This function is useful mainly for `GtkRange` subclasses. c:identifier="gtk_range_get_slider_size_fixed"> This function is useful mainly for `GtkRange` subclasses. + line="927">This function is useful mainly for `GtkRange` subclasses. See [method@Gtk.Range.set_slider_size_fixed]. whether the range’s slider has a fixed size. + line="935">whether the range’s slider has a fixed size. a `GtkRange` + line="929">a `GtkRange` @@ -115141,19 +117698,19 @@ See [method@Gtk.Range.set_slider_size_fixed]. Gets the current value of the range. + line="1127">Gets the current value of the range. current value of the range. + line="1133">current value of the range. a `GtkRange` + line="1129">a `GtkRange` @@ -115161,10 +117718,9 @@ See [method@Gtk.Range.set_slider_size_fixed]. - Sets the adjustment to be used as the “model” object for the `GtkRange` + line="657">Sets the adjustment to be used as the “model” object for the `GtkRange` The adjustment indicates the current range value, the minimum and maximum range values, the step/page increments used for keybindings @@ -115181,13 +117737,13 @@ The page size affects the size of the scrollbar slider. a `GtkRange` + line="659">a `GtkRange` a `GtkAdjustment` + line="660">a `GtkAdjustment` @@ -115195,10 +117751,9 @@ The page size affects the size of the scrollbar slider. - Set the new position of the fill level indicator. + line="1250">Set the new position of the fill level indicator. The “fill level” is probably best described by its most prominent use case, which is an indicator for the amount of pre-buffering in @@ -115223,13 +117778,13 @@ enabled. a `GtkRange` + line="1252">a `GtkRange` the new position of the fill level indicator + line="1253">the new position of the fill level indicator @@ -115237,7 +117792,7 @@ enabled. Sets whether the `GtkRange` respects text direction. + line="848">Sets whether the `GtkRange` respects text direction. If a range is flippable, it will switch its direction if it is horizontal and its direction is %GTK_TEXT_DIR_RTL. @@ -115251,13 +117806,13 @@ See [method@Gtk.Widget.get_direction]. a `GtkRange` + line="850">a `GtkRange` %TRUE to make the range flippable + line="851">%TRUE to make the range flippable @@ -115265,7 +117820,7 @@ See [method@Gtk.Widget.get_direction]. Sets the step and page sizes for the range. + line="1028">Sets the step and page sizes for the range. The step size is used when the user clicks the `GtkScrollbar` arrows or moves a `GtkScale` via arrow keys. The page size @@ -115278,19 +117833,19 @@ is used for example when moving via Page Up or Page Down keys. a `GtkRange` + line="1030">a `GtkRange` step size + line="1031">step size page size + line="1032">page size @@ -115298,10 +117853,9 @@ is used for example when moving via Page Up or Page Down keys. - Sets whether to invert the range. + line="793">Sets whether to invert the range. Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. Inverted @@ -115315,13 +117869,13 @@ than on the bottom or left. a `GtkRange` + line="795">a `GtkRange` %TRUE to invert the range + line="796">%TRUE to invert the range @@ -115329,7 +117883,7 @@ than on the bottom or left. Sets the allowable values in the `GtkRange`. + line="1061">Sets the allowable values in the `GtkRange`. The range value is clamped to be between @min and @max. (If the range has a non-zero page size, it is clamped @@ -115342,19 +117896,19 @@ between @min and @max - page-size.) a `GtkRange` + line="1063">a `GtkRange` minimum range value + line="1064">minimum range value maximum range value + line="1065">maximum range value @@ -115362,11 +117916,9 @@ between @min and @max - page-size.) - Sets whether the slider is restricted to the fill level. + line="1203">Sets whether the slider is restricted to the fill level. See [method@Gtk.Range.set_fill_level] for a general description of the fill level concept. @@ -115378,13 +117930,13 @@ of the fill level concept. A `GtkRange` + line="1205">A `GtkRange` Whether the fill level restricts slider movement. + line="1206">Whether the fill level restricts slider movement. @@ -115392,10 +117944,9 @@ of the fill level concept. - Sets the number of digits to round the value to when + line="2895">Sets the number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. @@ -115407,13 +117958,13 @@ See [signal@Gtk.Range::change-value]. a `GtkRange` + line="2897">a `GtkRange` the precision in digits, or -1 + line="2898">the precision in digits, or -1 @@ -115421,10 +117972,9 @@ See [signal@Gtk.Range::change-value]. - Sets whether a graphical fill level is show on the trough. + line="1145">Sets whether a graphical fill level is show on the trough. See [method@Gtk.Range.set_fill_level] for a general description of the fill level concept. @@ -115436,13 +117986,13 @@ of the fill level concept. A `GtkRange` + line="1147">A `GtkRange` Whether a fill level indicator graphics is shown. + line="1148">Whether a fill level indicator graphics is shown. @@ -115451,7 +118001,7 @@ of the fill level concept. c:identifier="gtk_range_set_slider_size_fixed"> Sets whether the range’s slider has a fixed size, or a size that + line="900">Sets whether the range’s slider has a fixed size, or a size that depends on its adjustment’s page size. This function is useful mainly for `GtkRange` subclasses. @@ -115463,13 +118013,13 @@ This function is useful mainly for `GtkRange` subclasses. a `GtkRange` + line="902">a `GtkRange` %TRUE to make the slider size constant + line="903">%TRUE to make the slider size constant @@ -115477,7 +118027,7 @@ This function is useful mainly for `GtkRange` subclasses. Sets the current value of the range. + line="1101">Sets the current value of the range. If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The range emits the @@ -115490,13 +118040,13 @@ it will be clamped to fit inside them. The range emits the a `GtkRange` + line="1103">a `GtkRange` new value of the range + line="1104">new value of the range @@ -115507,13 +118057,9 @@ it will be clamped to fit inside them. The range emits the transfer-ownership="none" setter="set_adjustment" getter="get_adjustment"> - - The adjustment that is controlled by the range. + line="379">The adjustment that is controlled by the range. - - The fill level (e.g. prebuffering of a network stream). + line="421">The fill level (e.g. prebuffering of a network stream). - - If %TRUE, the direction in which the slider moves is inverted. + line="389">If %TRUE, the direction in which the slider moves is inverted. - - Controls whether slider movement is restricted to an + line="410">Controls whether slider movement is restricted to an upper boundary set by the fill level. @@ -115566,13 +118102,9 @@ upper boundary set by the fill level. setter="set_round_digits" getter="get_round_digits" default-value="-1"> - - The number of digits to round the value to when + line="432">The number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. @@ -115584,13 +118116,9 @@ See [signal@Gtk.Range::change-value]. setter="set_show_fill_level" getter="get_show_fill_level" default-value="FALSE"> - - Controls whether fill level indicator graphics are displayed + line="399">Controls whether fill level indicator graphics are displayed on the trough. @@ -115600,7 +118128,7 @@ on the trough. Emitted before clamping a value, to give the application a + line="304">Emitted before clamping a value, to give the application a chance to adjust the bounds. @@ -115609,7 +118137,7 @@ chance to adjust the bounds. the value before we clamp + line="307">the value before we clamp @@ -115617,7 +118145,7 @@ chance to adjust the bounds. Emitted when a scroll action is performed on a range. + line="341">Emitted when a scroll action is performed on a range. It allows an application to determine the type of scroll event that occurred and the resultant new value. The application can @@ -115632,7 +118160,7 @@ handler clamps the value based on [property@Gtk.Range:round-digits]. %TRUE to prevent other handlers from being invoked for + line="360">%TRUE to prevent other handlers from being invoked for the signal, %FALSE to propagate the signal further @@ -115640,13 +118168,13 @@ handler clamps the value based on [property@Gtk.Range:round-digits]. the type of scroll action that was performed + line="344">the type of scroll action that was performed the new value resulting from the scroll action + line="345">the new value resulting from the scroll action @@ -115654,7 +118182,7 @@ handler clamps the value based on [property@Gtk.Range:round-digits]. Virtual function that moves the slider. + line="322">Virtual function that moves the slider. Used for keybindings. @@ -115664,7 +118192,7 @@ Used for keybindings. how to move the slider + line="325">how to move the slider @@ -115672,7 +118200,7 @@ Used for keybindings. Emitted when the range value changes. + line="289">Emitted when the range value changes. @@ -115838,7 +118366,7 @@ registering a recently used resource. c:symbol-prefix="recent_info"> `GtkRecentInfo` contains the metadata associated with an item in the + line="124">Contains the metadata associated with an item in the recently used files list. throws="1"> Creates a `GAppInfo` for the specified `GtkRecentInfo` + line="2282">Creates a `GAppInfo` for the specified `GtkRecentInfo` In case of error, @error will be set either with a %GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR @@ -115854,14 +118382,14 @@ In case of error, @error will be set either with a the newly created `GAppInfo` + line="2295">the newly created `GAppInfo` a `GtkRecentInfo` + line="2284">a `GtkRecentInfo` the name of the application that should + line="2285">the name of the application that should be mapped to a `GAppInfo`; if %NULL is used then the default application for the MIME type is used @@ -115880,21 +118408,21 @@ In case of error, @error will be set either with a Checks whether the resource pointed by @info still exists. + line="1931">Checks whether the resource pointed by @info still exists. At the moment this check is done only on resources pointing to local files. %TRUE if the resource exists + line="1939">%TRUE if the resource exists a `GtkRecentInfo` + line="1933">a `GtkRecentInfo` @@ -115902,13 +118430,13 @@ to local files. Gets the time when the resource + line="1652">Gets the time when the resource was added to the recently used resources list. a `GDateTime` for the time + line="1659">a `GDateTime` for the time when the resource was added @@ -115916,7 +118444,7 @@ was added to the recently used resources list. a `GtkRecentInfo` + line="1654">a `GtkRecentInfo` @@ -115924,13 +118452,13 @@ was added to the recently used resources list. Gets the number of days elapsed since the last update + line="2178">Gets the number of days elapsed since the last update of the resource pointed by @info. a positive integer containing the number of days + line="2185">a positive integer containing the number of days elapsed since the time this resource was last modified @@ -115938,7 +118466,7 @@ of the resource pointed by @info. a `GtkRecentInfo` + line="2180">a `GtkRecentInfo` @@ -115947,7 +118475,7 @@ of the resource pointed by @info. c:identifier="gtk_recent_info_get_application_info"> Gets the data regarding the application that has registered the resource + line="1726">Gets the data regarding the application that has registered the resource pointed by @info. If the command line contains any escape characters defined inside the @@ -115956,7 +118484,7 @@ storage specification, they will be expanded. %TRUE if an application with @app_name has registered this + line="1742">%TRUE if an application with @app_name has registered this resource inside the recently used list, or %FALSE otherwise. The @app_exec string is owned by the `GtkRecentInfo` and should not be modified or freed @@ -115966,13 +118494,13 @@ storage specification, they will be expanded. a `GtkRecentInfo` + line="1728">a `GtkRecentInfo` the name of the application that has registered this item + line="1729">the name of the application that has registered this item transfer-ownership="none"> return location for the string containing + line="1730">return location for the string containing the command line @@ -115991,7 +118519,7 @@ storage specification, they will be expanded. transfer-ownership="full"> return location for the number of times this item was registered + line="1732">return location for the number of times this item was registered transfer-ownership="none"> return location for the time this item was last + line="1733">return location for the time this item was last registered for this application @@ -116010,12 +118538,12 @@ storage specification, they will be expanded. c:identifier="gtk_recent_info_get_applications"> Retrieves the list of applications that have registered this resource. + line="1782">Retrieves the list of applications that have registered this resource. a newly + line="1789">a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. @@ -116025,7 +118553,7 @@ storage specification, they will be expanded. a `GtkRecentInfo` + line="1784">a `GtkRecentInfo` allow-none="1"> return location for the length of the returned list + line="1785">return location for the length of the returned list @@ -116045,12 +118573,12 @@ storage specification, they will be expanded. c:identifier="gtk_recent_info_get_description"> Gets the (short) description of the resource. + line="1615">Gets the (short) description of the resource. the description of the resource. The returned string + line="1621">the description of the resource. The returned string is owned by the recent manager, and should not be freed. @@ -116058,7 +118586,7 @@ storage specification, they will be expanded. a `GtkRecentInfo` + line="1617">a `GtkRecentInfo` @@ -116067,7 +118595,7 @@ storage specification, they will be expanded. c:identifier="gtk_recent_info_get_display_name"> Gets the name of the resource. + line="1592">Gets the name of the resource. If none has been defined, the basename of the resource is obtained. @@ -116075,7 +118603,7 @@ of the resource is obtained. the display name of the resource. The returned string + line="1601">the display name of the resource. The returned string is owned by the recent manager, and should not be freed. @@ -116083,7 +118611,7 @@ of the resource is obtained. a `GtkRecentInfo` + line="1594">a `GtkRecentInfo` @@ -116091,19 +118619,19 @@ of the resource is obtained. Retrieves the icon associated to the resource MIME type. + line="1880">Retrieves the icon associated to the resource MIME type. a `GIcon` containing the icon + line="1886">a `GIcon` containing the icon a `GtkRecentInfo` + line="1882">a `GtkRecentInfo` @@ -116111,7 +118639,7 @@ of the resource is obtained. Returns all groups registered for the recently used item @info. + line="2203">Returns all groups registered for the recently used item @info. The array of returned group names will be %NULL terminated, so length might optionally be %NULL. @@ -116119,7 +118647,7 @@ length might optionally be %NULL. + line="2213"> a newly allocated %NULL terminated array of strings. Use g_strfreev() to free it. @@ -116130,7 +118658,7 @@ length might optionally be %NULL. a `GtkRecentInfo` + line="2205">a `GtkRecentInfo` allow-none="1"> return location for the number of groups returned + line="2206">return location for the number of groups returned @@ -116150,12 +118678,12 @@ length might optionally be %NULL. c:identifier="gtk_recent_info_get_mime_type"> Gets the MIME type of the resource. + line="1632">Gets the MIME type of the resource. the MIME type of the resource. The returned string + line="1638">the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed. @@ -116163,7 +118691,7 @@ length might optionally be %NULL. a `GtkRecentInfo` + line="1634">a `GtkRecentInfo` @@ -116171,13 +118699,13 @@ length might optionally be %NULL. Gets the time when the meta-data + line="1670">Gets the time when the meta-data for the resource was last modified. a `GDateTime` for the time + line="1677">a `GDateTime` for the time when the resource was last modified @@ -116185,7 +118713,7 @@ for the resource was last modified. a `GtkRecentInfo` + line="1672">a `GtkRecentInfo` @@ -116194,7 +118722,7 @@ for the resource was last modified. c:identifier="gtk_recent_info_get_private_hint"> Gets the value of the “private” flag. + line="1706">Gets the value of the “private” flag. Resources in the recently used list that have this flag set to %TRUE should only be displayed by the applications @@ -116203,14 +118731,14 @@ that have registered them. %TRUE if the private flag was found, %FALSE otherwise + line="1716">%TRUE if the private flag was found, %FALSE otherwise a `GtkRecentInfo` + line="1708">a `GtkRecentInfo` @@ -116219,7 +118747,7 @@ that have registered them. c:identifier="gtk_recent_info_get_short_name"> Computes a valid UTF-8 string that can be used as the + line="2110">Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For example, calling this function on an item that refers @@ -116228,7 +118756,7 @@ to “file:///foo/bar.txt” will yield “bar.txt”. A newly-allocated string in UTF-8 encoding + line="2120">A newly-allocated string in UTF-8 encoding free it with g_free() @@ -116236,7 +118764,7 @@ to “file:///foo/bar.txt” will yield “bar.txt”. an `GtkRecentInfo` + line="2112">an `GtkRecentInfo` @@ -116244,12 +118772,12 @@ to “file:///foo/bar.txt” will yield “bar.txt”. Gets the URI of the resource. + line="1575">Gets the URI of the resource. the URI of the resource. The returned string is + line="1581">the URI of the resource. The returned string is owned by the recent manager, and should not be freed. @@ -116257,7 +118785,7 @@ to “file:///foo/bar.txt” will yield “bar.txt”. a `tkRecentInfo` + line="1577">a `tkRecentInfo` @@ -116266,7 +118794,7 @@ to “file:///foo/bar.txt” will yield “bar.txt”. c:identifier="gtk_recent_info_get_uri_display"> Gets a displayable version of the resource’s URI. + line="2138">Gets a displayable version of the resource’s URI. If the resource is local, it returns a local path; if the resource is not local, it returns the UTF-8 encoded content @@ -116275,7 +118803,7 @@ of [method@Gtk.RecentInfo.get_uri]. a newly allocated UTF-8 string containing the + line="2148">a newly allocated UTF-8 string containing the resource’s URI or %NULL. Use g_free() when done using it. @@ -116283,7 +118811,7 @@ of [method@Gtk.RecentInfo.get_uri]. a `GtkRecentInfo` + line="2140">a `GtkRecentInfo` @@ -116291,13 +118819,13 @@ of [method@Gtk.RecentInfo.get_uri]. Gets the time when the meta-data + line="1688">Gets the time when the meta-data for the resource was last visited. a `GDateTime` for the time + line="1695">a `GDateTime` for the time when the resource was last visited @@ -116305,7 +118833,7 @@ for the resource was last visited. a `GtkRecentInfo` + line="1690">a `GtkRecentInfo` @@ -116314,12 +118842,12 @@ for the resource was last visited. c:identifier="gtk_recent_info_has_application"> Checks whether an application registered this resource using @app_name. + line="1827">Checks whether an application registered this resource using @app_name. %TRUE if an application with name @app_name was found, + line="1834">%TRUE if an application with name @app_name was found, %FALSE otherwise @@ -116327,13 +118855,13 @@ for the resource was last visited. a `GtkRecentInfo` + line="1829">a `GtkRecentInfo` a string containing an application name + line="1830">a string containing an application name @@ -116341,26 +118869,26 @@ for the resource was last visited. Checks whether @group_name appears inside the groups + line="2249">Checks whether @group_name appears inside the groups registered for the recently used item @info. %TRUE if the group was found + line="2257">%TRUE if the group was found a `GtkRecentInfo` + line="2251">a `GtkRecentInfo` name of a group + line="2252">name of a group @@ -116368,20 +118896,20 @@ registered for the recently used item @info. Checks whether the resource is local or not by looking at the + line="1914">Checks whether the resource is local or not by looking at the scheme of its URI. %TRUE if the resource is local + line="1921">%TRUE if the resource is local a `GtkRecentInfo` + line="1916">a `GtkRecentInfo` @@ -116390,20 +118918,20 @@ scheme of its URI. c:identifier="gtk_recent_info_last_application"> Gets the name of the last application that have registered the + line="1847">Gets the name of the last application that have registered the recently used resource represented by @info. an application name. Use g_free() to free it. + line="1854">an application name. Use g_free() to free it. a `GtkRecentInfo` + line="1849">a `GtkRecentInfo` @@ -116411,12 +118939,12 @@ recently used resource represented by @info. Checks whether two `GtkRecentInfo` point to the same resource. + line="1966">Checks whether two `GtkRecentInfo` point to the same resource. %TRUE if both `GtkRecentInfo` point to the same + line="1973">%TRUE if both `GtkRecentInfo` point to the same resource, %FALSE otherwise @@ -116424,13 +118952,13 @@ recently used resource represented by @info. a `GtkRecentInfo` + line="1968">a `GtkRecentInfo` a `GtkRecentInfo` + line="1969">a `GtkRecentInfo` @@ -116438,12 +118966,12 @@ recently used resource represented by @info. Increases the reference count of @recent_info by one. + line="1534">Increases the reference count of @recent_info by one. the recent info object with its reference count + line="1540">the recent info object with its reference count increased by one @@ -116451,7 +118979,7 @@ recently used resource represented by @info. a `GtkRecentInfo` + line="1536">a `GtkRecentInfo` @@ -116459,7 +118987,7 @@ recently used resource represented by @info. Decreases the reference count of @info by one. + line="1554">Decreases the reference count of @info by one. If the reference count reaches zero, @info is deallocated, and the memory freed. @@ -116471,7 +118999,7 @@ deallocated, and the memory freed. a `GtkRecentInfo` + line="1556">a `GtkRecentInfo` @@ -116486,7 +119014,7 @@ deallocated, and the memory freed. glib:type-struct="RecentManagerClass"> `GtkRecentManager` manages and looks up recently used files. + line="20">Manages and looks up recently used files. Each recently used file is identified by its URI, and has meta-data associated to it, like the names and command lines of the applications @@ -116546,7 +119074,7 @@ property. Creates a new recent manager object. + line="715">Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A `GtkRecentManager` object monitors the recently used @@ -116560,7 +119088,7 @@ instead. A newly created `GtkRecentManager` object + line="729">A newly created `GtkRecentManager` object @@ -116568,13 +119096,13 @@ instead. c:identifier="gtk_recent_manager_get_default"> Gets a unique instance of `GtkRecentManager` that you can share + line="737">Gets a unique instance of `GtkRecentManager` that you can share in your application without caring about memory management. A unique `GtkRecentManager`. Do not ref or + line="743">A unique `GtkRecentManager`. Do not ref or unref it. @@ -116593,7 +119121,7 @@ in your application without caring about memory management. Adds a new resource, pointed by @uri, into the recently used + line="858">Adds a new resource, pointed by @uri, into the recently used resources list, using the metadata specified inside the `GtkRecentData` passed in @recent_data. @@ -116616,7 +119144,7 @@ applications that have registered it. %TRUE if the new item was successfully added to the + line="884">%TRUE if the new item was successfully added to the recently used resources list, %FALSE otherwise @@ -116624,19 +119152,19 @@ applications that have registered it. a `GtkRecentManager` + line="860">a `GtkRecentManager` a valid URI + line="861">a valid URI metadata of the resource + line="862">metadata of the resource @@ -116644,7 +119172,7 @@ applications that have registered it. Adds a new resource, pointed by @uri, into the recently used + line="816">Adds a new resource, pointed by @uri, into the recently used resources list. This function automatically retrieves some of the needed @@ -116657,7 +119185,7 @@ define the metadata for the resource pointed by @uri. %TRUE if the new item was successfully added + line="831">%TRUE if the new item was successfully added to the recently used resources list @@ -116665,13 +119193,13 @@ define the metadata for the resource pointed by @uri. a `GtkRecentManager` + line="818">a `GtkRecentManager` a valid URI + line="819">a valid URI @@ -116679,12 +119207,12 @@ define the metadata for the resource pointed by @uri. Gets the list of recently used resources. + line="1276">Gets the list of recently used resources. a list of + line="1282">a list of newly allocated `GtkRecentInfo objects`. Use [method@Gtk.RecentInfo.unref] on each item inside the list, and then free the list itself using g_list_free(). @@ -116696,7 +119224,7 @@ define the metadata for the resource pointed by @uri. a `GtkRecentManager` + line="1278">a `GtkRecentManager` @@ -116704,26 +119232,26 @@ define the metadata for the resource pointed by @uri. Checks whether there is a recently used resource registered + line="1055">Checks whether there is a recently used resource registered with @uri inside the recent manager. %TRUE if the resource was found, %FALSE otherwise + line="1063">%TRUE if the resource was found, %FALSE otherwise a `GtkRecentManager` + line="1057">a `GtkRecentManager` a URI + line="1058">a URI @@ -116733,14 +119261,14 @@ with @uri inside the recent manager. throws="1"> Searches for a URI inside the recently used resources list, and + line="1146">Searches for a URI inside the recently used resources list, and returns a `GtkRecentInfo` containing information about the resource like its MIME type, or its display name. a `GtkRecentInfo` containing information + line="1156">a `GtkRecentInfo` containing information about the resource pointed by @uri, or %NULL if the URI was not registered in the recently used resources list. Free with [method@Gtk.RecentInfo.unref]. @@ -116750,13 +119278,13 @@ like its MIME type, or its display name. a `GtkRecentManager` + line="1148">a `GtkRecentManager` a URI + line="1149">a URI @@ -116766,7 +119294,7 @@ like its MIME type, or its display name. throws="1"> Changes the location of a recently used resource from @uri to @new_uri. + line="1207">Changes the location of a recently used resource from @uri to @new_uri. Please note that this function will not affect the resource pointed by the URIs, but only the URI used in the recently used resources list. @@ -116774,20 +119302,20 @@ by the URIs, but only the URI used in the recently used resources list. %TRUE on success + line="1220">%TRUE on success a `GtkRecentManager` + line="1209">a `GtkRecentManager` the URI of a recently used resource + line="1210">the URI of a recently used resource allow-none="1"> the new URI of the recently used resource, or + line="1211">the new URI of the recently used resource, or %NULL to remove the item pointed by @uri in the list @@ -116807,12 +119335,12 @@ by the URIs, but only the URI used in the recently used resources list. throws="1"> Purges every item from the recently used resources list. + line="1335">Purges every item from the recently used resources list. the number of items that have been removed from the + line="1342">the number of items that have been removed from the recently used resources list @@ -116820,7 +119348,7 @@ by the URIs, but only the URI used in the recently used resources list. a `GtkRecentManager` + line="1337">a `GtkRecentManager` @@ -116830,13 +119358,13 @@ by the URIs, but only the URI used in the recently used resources list. throws="1"> Removes a resource pointed by @uri from the recently used resources + line="997">Removes a resource pointed by @uri from the recently used resources list handled by a recent manager. %TRUE if the item pointed by @uri has been successfully + line="1006">%TRUE if the item pointed by @uri has been successfully removed by the recently used resources list, and %FALSE otherwise @@ -116844,13 +119372,13 @@ list handled by a recent manager. a `GtkRecentManager` + line="999">a `GtkRecentManager` the URI of the item you wish to remove + line="1000">the URI of the item you wish to remove @@ -116862,14 +119390,14 @@ list handled by a recent manager. default-value="NULL"> The full path to the file to be used to store and read the + line="269">The full path to the file to be used to store and read the recently used resources list The size of the recently used resources list. + line="281">The size of the recently used resources list. @@ -116881,7 +119409,7 @@ recently used resources list Emitted when the current recently used resources manager changes + line="292">Emitted when the current recently used resources manager changes its contents. This can happen either by calling [method@Gtk.RecentManager.add_item] @@ -117024,7 +119552,13 @@ or by another application. line="123">unspecified error. + Registers an error quark for [class@RecentManager] errors. + the error quark @@ -117038,10 +119572,11 @@ or by another application. Represents a request of a screen object in a given orientation. These -are primarily used in container implementations when allocating a natural -size for children calling. See [func@distribute_natural_allocation]. - + line="30">Represents a request of a screen object in a given orientation. + +These are primarily used in container implementations when allocating +a natural size for children. See [func@distribute_natural_allocation]. + c:symbol-prefix="requisition"> A `GtkRequisition` represents the desired size of a widget. See -[GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for -more information. - + line="84">Represents the desired size of a widget. + +See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) +for more information. + the widget’s desired width + line="86">the widget’s desired width the widget’s desired height + line="87">the widget’s desired height Allocates a new `GtkRequisition`. + line="8182">Allocates a new `GtkRequisition`. The struct is initialized to zero. - + a new empty `GtkRequisition`. The newly - allocated `GtkRequisition` should be freed with - [method@Gtk.Requisition.free] + line="8189">a new empty `GtkRequisition` Copies a `GtkRequisition`. - + line="8197">Copies a `GtkRequisition`. + a copy of @requisition + line="8203">a copy of @requisition a `GtkRequisition` + line="8199">a `GtkRequisition` @@ -117123,8 +119657,8 @@ The struct is initialized to zero. Frees a `GtkRequisition`. - + line="8213">Frees a `GtkRequisition`. + @@ -117132,7 +119666,7 @@ The struct is initialized to zero. a `GtkRequisition` + line="8215">a `GtkRequisition` @@ -117257,7 +119791,7 @@ application-defined response ids. glib:get-type="gtk_revealer_get_type"> A `GtkRevealer` animates the transition of its child from invisible to visible. + line="35">Animates the transition of its child from invisible to visible. The style of transition can be controlled with [method@Gtk.Revealer.set_transition_type]. @@ -117274,7 +119808,7 @@ when the [property@Gtk.Revealer:reveal-child] property is set to %FALSE. # Accessibility -`GtkRevealer` uses the %GTK_ACCESSIBLE_ROLE_GROUP role. +`GtkRevealer` uses the [enum@Gtk.AccessibleRole.group] role. The child of `GtkRevealer`, if set, is always available in the accessibility tree, regardless of the state of the revealer widget. @@ -117284,34 +119818,33 @@ tree, regardless of the state of the revealer widget. Creates a new `GtkRevealer`. + line="375">Creates a new `GtkRevealer`. a newly created `GtkRevealer` + line="380">a newly created `GtkRevealer` - Gets the child widget of @revealer. + line="900">Gets the child widget of @revealer. the child widget of @revealer + line="906">the child widget of @revealer a `GtkRevealer` + line="902">a `GtkRevealer` @@ -117319,10 +119852,9 @@ tree, regardless of the state of the revealer widget. - Returns whether the child is fully revealed. + line="725">Returns whether the child is fully revealed. In other words, this returns whether the transition to the revealed state is completed. @@ -117330,14 +119862,14 @@ to the revealed state is completed. %TRUE if the child is fully revealed + line="734">%TRUE if the child is fully revealed a `GtkRevealer` + line="727">a `GtkRevealer` @@ -117345,10 +119877,9 @@ to the revealed state is completed. - Returns whether the child is currently revealed. + line="704">Returns whether the child is currently revealed. This function returns %TRUE as soon as the transition is to the revealed state is started. To learn whether @@ -117358,14 +119889,14 @@ use [method@Gtk.Revealer.get_child_revealed]. %TRUE if the child is revealed. + line="715">%TRUE if the child is revealed. a `GtkRevealer` + line="706">a `GtkRevealer` @@ -117373,24 +119904,22 @@ use [method@Gtk.Revealer.get_child_revealed]. - Returns the amount of time (in milliseconds) that + line="793">Returns the amount of time (in milliseconds) that transitions will take. the transition duration + line="800">the transition duration a `GtkRevealer` + line="795">a `GtkRevealer` @@ -117398,16 +119927,15 @@ transitions will take. - Gets the type of animation that will be used + line="830">Gets the type of animation that will be used for transitions in @revealer. the current transition type of @revealer + line="837">the current transition type of @revealer @@ -117415,7 +119943,7 @@ for transitions in @revealer. a `GtkRevealer` + line="832">a `GtkRevealer` @@ -117423,10 +119951,9 @@ for transitions in @revealer. - Sets the child widget of @revealer. + line="871">Sets the child widget of @revealer. @@ -117435,7 +119962,7 @@ for transitions in @revealer. a `GtkRevealer` + line="873">a `GtkRevealer` allow-none="1"> the child widget + line="874">the child widget @@ -117452,10 +119979,9 @@ for transitions in @revealer. - Tells the `GtkRevealer` to reveal or conceal its child. + line="682">Tells the `GtkRevealer` to reveal or conceal its child. The transition will be animated with the current transition type of @revealer. @@ -117467,13 +119993,13 @@ transition type of @revealer. a `GtkRevealer` + line="684">a `GtkRevealer` %TRUE to reveal the child + line="685">%TRUE to reveal the child @@ -117481,11 +120007,9 @@ transition type of @revealer. - Sets the duration that transitions will take. + line="810">Sets the duration that transitions will take. @@ -117494,13 +120018,13 @@ transition type of @revealer. a `GtkRevealer` + line="812">a `GtkRevealer` the new duration, in milliseconds + line="813">the new duration, in milliseconds @@ -117508,10 +120032,9 @@ transition type of @revealer. - Sets the type of animation that will be used for + line="847">Sets the type of animation that will be used for transitions in @revealer. Available types include various kinds of fades and slides. @@ -117523,13 +120046,13 @@ Available types include various kinds of fades and slides. a `GtkRevealer` + line="849">a `GtkRevealer` the new transition type + line="850">the new transition type @@ -117540,22 +120063,18 @@ Available types include various kinds of fades and slides. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="358">The child widget. - Whether the child is revealed and the animation target reached. + line="348">Whether the child is revealed and the animation target reached. setter="set_reveal_child" getter="get_reveal_child" default-value="FALSE"> - - Whether the revealer should reveal the child. + line="338">Whether the revealer should reveal the child. setter="set_transition_duration" getter="get_transition_duration" default-value="250"> - - The animation duration, in milliseconds. + line="328">The animation duration, in milliseconds. setter="set_transition_type" getter="get_transition_type" default-value="GTK_REVEALER_TRANSITION_TYPE_SLIDE_DOWN"> - - The type of animation used to transition. + line="317">The type of animation used to transition. @@ -117613,7 +120120,7 @@ Available types include various kinds of fades and slides. c:type="GtkRevealerTransitionType"> These enumeration values describe the possible transitions + line="61">These enumeration values describe the possible transitions when the child of a `GtkRevealer` widget is shown or hidden. glib:name="GTK_REVEALER_TRANSITION_TYPE_NONE"> No transition + line="63">No transition glib:name="GTK_REVEALER_TRANSITION_TYPE_CROSSFADE"> Fade in + line="64">Fade in glib:name="GTK_REVEALER_TRANSITION_TYPE_SLIDE_RIGHT"> Slide in from the left + line="65">Slide in from the left glib:name="GTK_REVEALER_TRANSITION_TYPE_SLIDE_LEFT"> Slide in from the right + line="66">Slide in from the right glib:name="GTK_REVEALER_TRANSITION_TYPE_SLIDE_UP"> Slide in from the bottom + line="67">Slide in from the bottom glib:name="GTK_REVEALER_TRANSITION_TYPE_SLIDE_DOWN"> Slide in from the top + line="68">Slide in from the top glib:name="GTK_REVEALER_TRANSITION_TYPE_SWING_RIGHT"> Floop in from the left + line="69">Floop in from the left glib:name="GTK_REVEALER_TRANSITION_TYPE_SWING_LEFT"> Floop in from the right + line="70">Floop in from the right glib:name="GTK_REVEALER_TRANSITION_TYPE_SWING_UP"> Floop in from the bottom + line="71">Floop in from the bottom glib:name="GTK_REVEALER_TRANSITION_TYPE_SWING_DOWN"> Floop in from the top + line="72">Floop in from the top glib:type-struct="RootInterface"> `GtkRoot` is the interface implemented by all widgets that can act as a toplevel -widget. + line="32">An interface for widgets that can act as the root of a widget hierarchy. -The root widget takes care of providing the connection to the windowing system -and manages layout, drawing and event delivery for its widget hierarchy. +The root widget takes care of providing the connection to the windowing +system and manages layout, drawing and event delivery for its widget +hierarchy. The obvious example of a `GtkRoot` is `GtkWindow`. @@ -117944,7 +120451,8 @@ this function. - + @@ -117953,7 +120461,8 @@ this function. - + @@ -117962,7 +120471,8 @@ this function. - + @@ -117971,7 +120481,8 @@ this function. - + @@ -118007,7 +120518,7 @@ this function. - + @@ -118232,9 +120743,12 @@ give the user the last word. glib:type-struct="ScaleClass"> A `GtkScale` is a slider control used to select a numeric value. + line="46">Allows to select a numeric value with a slider control. -![An example GtkScale](scales.png) +<picture> + <source srcset="scales-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkScale" src="scales.png"> +</picture> To use it, you’ll probably want to investigate the methods on its base class, [class@Gtk.Range], in addition to the methods for `GtkScale` itself. @@ -118256,6 +120770,15 @@ the element is not empty, its content is taken as the markup to show at the mark. It can be translated with the usual ”translatable” and “context” attributes. +# Shortcuts and Gestures + +`GtkPopoverMenu` supports the following keyboard shortcuts: + +- Arrow keys, <kbd>+</kbd> and <kbd>-</kbd> will increment or decrement + by step, or by page when combined with <kbd>Ctrl</kbd>. +- <kbd>PgUp</kbd> and <kbd>PgDn</kbd> will increment or decrement by page. +- <kbd>Home</kbd> and <kbd>End</kbd> will set the minimum or maximum value. + # CSS nodes ``` @@ -118311,7 +120834,7 @@ classes similar to the marks node. # Accessibility -`GtkScale` uses the %GTK_ACCESSIBLE_ROLE_SLIDER role. +`GtkScale` uses the [enum@Gtk.AccessibleRole.slider] role. @@ -118321,19 +120844,19 @@ classes similar to the marks node. Creates a new `GtkScale`. - + line="936">Creates a new `GtkScale`. + a new `GtkScale` + line="944">a new `GtkScale` the scale’s orientation. + line="938">the scale’s orientation. the [class@Gtk.Adjustment] which sets + line="939">the [class@Gtk.Adjustment] which sets the range of the scale, or %NULL to create a new adjustment. @@ -118352,7 +120875,7 @@ classes similar to the marks node. c:identifier="gtk_scale_new_with_range"> Creates a new scale widget with a range from @min to @max. + line="959">Creates a new scale widget with a range from @min to @max. The returns scale will have the given orientation and will let the user input a number between @min and @max (including @min and @max) @@ -118363,36 +120886,36 @@ value. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use [method@Gtk.Scale.set_digits] to correct it. - + a new `GtkScale` + line="978">a new `GtkScale` the scale’s orientation. + line="961">the scale’s orientation. minimum value + line="962">minimum value maximum value + line="963">maximum value step increment (tick size) used with keyboard shortcuts + line="964">step increment (tick size) used with keyboard shortcuts @@ -118400,7 +120923,7 @@ for your needs, use [method@Gtk.Scale.set_digits] to correct it. Obtains the coordinates where the scale will draw the + line="1607">Obtains the coordinates where the scale will draw the `PangoLayout` representing the text in the scale. Remember when using the `PangoLayout` function you need to @@ -118416,7 +120939,7 @@ values are undefined. a `GtkScale` + line="1609">a `GtkScale` allow-none="1"> location to store X offset of layout + line="1610">location to store X offset of layout allow-none="1"> location to store Y offset of layout + line="1611">location to store Y offset of layout @@ -118446,7 +120969,7 @@ values are undefined. Adds a mark at @value. + line="1683">Adds a mark at @value. A mark is indicated visually by drawing a tick mark next to the scale, and GTK makes it easy for the user to position the scale exactly at the @@ -118455,7 +120978,7 @@ marks value. If @markup is not %NULL, text is shown next to the tick mark. To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. - + @@ -118463,20 +120986,20 @@ To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. a `GtkScale` + line="1685">a `GtkScale` the value at which the mark is placed, must be between + line="1686">the value at which the mark is placed, must be between the lower and upper limits of the scales’ adjustment where to draw the mark. For a horizontal scale, %GTK_POS_TOP + line="1688">where to draw the mark. For a horizontal scale, %GTK_POS_TOP and %GTK_POS_LEFT are drawn above the scale, anything else below. For a vertical scale, %GTK_POS_LEFT and %GTK_POS_TOP are drawn to the left of the scale, anything else to the right. @@ -118488,7 +121011,7 @@ To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. allow-none="1"> Text to be shown at the mark, using Pango markup + line="1692">Text to be shown at the mark, using Pango markup @@ -118496,8 +121019,8 @@ To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. Removes any marks that have been added. - + line="1656">Removes any marks that have been added. + @@ -118505,7 +121028,7 @@ To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. a `GtkScale` + line="1658">a `GtkScale` @@ -118513,22 +121036,21 @@ To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. - Gets the number of decimal places that are displayed in the value. - + line="1059">Gets the number of decimal places that are displayed in the value. + the number of decimal places that are displayed + line="1065">the number of decimal places that are displayed a `GtkScale` + line="1061">a `GtkScale` @@ -118536,23 +121058,22 @@ To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. - Returns whether the current value is displayed as a string + line="1152">Returns whether the current value is displayed as a string next to the slider. - + whether the current value is displayed as a string + line="1159">whether the current value is displayed as a string a `GtkScale` + line="1154">a `GtkScale` @@ -118560,22 +121081,21 @@ next to the slider. - Returns whether the scale has an origin. - + line="1200">Returns whether the scale has an origin. + %TRUE if the scale has an origin. + line="1206">%TRUE if the scale has an origin. a `GtkScale` + line="1202">a `GtkScale` @@ -118583,15 +121103,15 @@ next to the slider. Gets the `PangoLayout` used to display the scale. + line="1581">Gets the `PangoLayout` used to display the scale. The returned object is owned by the scale so does not need to be freed by the caller. - + the [class@Pango.Layout] + line="1590">the [class@Pango.Layout] for this scale, or %NULL if the [property@Gtk.Scale:draw-value] property is %FALSE. @@ -118600,7 +121120,7 @@ to be freed by the caller. A `GtkScale` + line="1583">A `GtkScale` @@ -118609,7 +121129,7 @@ to be freed by the caller. c:identifier="gtk_scale_get_layout_offsets"> Obtains the coordinates where the scale will draw the + line="1607">Obtains the coordinates where the scale will draw the `PangoLayout` representing the text in the scale. Remember when using the `PangoLayout` function you need to @@ -118617,7 +121137,7 @@ convert to and from pixels using `PANGO_PIXELS()` or `PANGO_SCALE`. If the [property@Gtk.Scale:draw-value] property is %FALSE, the return values are undefined. - + @@ -118625,7 +121145,7 @@ values are undefined. a `GtkScale` + line="1609">a `GtkScale` allow-none="1"> location to store X offset of layout + line="1610">location to store X offset of layout allow-none="1"> location to store Y offset of layout + line="1611">location to store Y offset of layout @@ -118655,22 +121175,21 @@ values are undefined. - Gets the position in which the current value is displayed. - + line="1242">Gets the position in which the current value is displayed. + the position in which the current value is displayed + line="1248">the position in which the current value is displayed a `GtkScale` + line="1244">a `GtkScale` @@ -118678,10 +121197,9 @@ values are undefined. - Sets the number of decimal places that are displayed in the value. + line="1012">Sets the number of decimal places that are displayed in the value. Also causes the value of the adjustment to be rounded to this number of digits, so the retrieved value matches the displayed one, if @@ -118693,7 +121211,7 @@ Note that rounding to a small number of digits can interfere with the smooth autoscrolling that is built into `GtkScale`. As an alternative, you can use [method@Gtk.Scale.set_format_value_func] to format the displayed value yourself. - + @@ -118701,13 +121219,13 @@ value yourself. a `GtkScale` + line="1014">a `GtkScale` the number of decimal places to display, + line="1015">the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00, etc @@ -118716,12 +121234,11 @@ value yourself. - Specifies whether the current value is displayed as a string next + line="1110">Specifies whether the current value is displayed as a string next to the slider. - + @@ -118729,13 +121246,13 @@ to the slider. a `GtkScale` + line="1112">a `GtkScale` %TRUE to draw the value + line="1113">%TRUE to draw the value @@ -118744,7 +121261,7 @@ to the slider. c:identifier="gtk_scale_set_format_value_func"> @func allows you to change how the scale value is displayed. + line="2056">@func allows you to change how the scale value is displayed. The given function will return an allocated string representing @value. That string will then be used to display the scale's value. @@ -118752,7 +121269,7 @@ The given function will return an allocated string representing If #NULL is passed as @func, the value will be displayed on its own, rounded according to the value of the [property@Gtk.Scale:digits] property. - + @@ -118760,7 +121277,7 @@ its own, rounded according to the value of the a `GtkScale` + line="2058">a `GtkScale` function that formats the value + line="2059">function + that formats the value @@ -118782,7 +121300,7 @@ its own, rounded according to the value of the allow-none="1"> user data to pass to @func + line="2061">user data to pass to @func destroy function for @user_data + line="2062">destroy function for @user_data @@ -118800,15 +121318,14 @@ its own, rounded according to the value of the - Sets whether the scale has an origin. + line="1171">Sets whether the scale has an origin. If [property@Gtk.Scale:has-origin] is set to %TRUE (the default), the scale will highlight the part of the trough between the origin (bottom or left side) and the current value. - + @@ -118816,13 +121333,13 @@ the scale will highlight the part of the trough between the origin a `GtkScale` + line="1173">a `GtkScale` %TRUE if the scale has an origin + line="1174">%TRUE if the scale has an origin @@ -118830,11 +121347,10 @@ the scale will highlight the part of the trough between the origin - Sets the position in which the current value is displayed. - + line="1216">Sets the position in which the current value is displayed. + @@ -118842,13 +121358,13 @@ the scale will highlight the part of the trough between the origin a `GtkScale` + line="1218">a `GtkScale` the position in which the current value is displayed + line="1219">the position in which the current value is displayed @@ -118859,11 +121375,9 @@ the scale will highlight the part of the trough between the origin setter="set_digits" getter="get_digits" default-value="1"> - - The number of decimal places that are displayed in the value. + line="693">The number of decimal places that are displayed in the value. - - Whether the current value is displayed as a string next to the slider. + line="704">Whether the current value is displayed as a string next to the slider. - - Whether the scale has an origin. + line="714">Whether the scale has an origin. - - The position in which the current value is displayed. + line="724">The position in which the current value is displayed. @@ -118918,12 +121426,18 @@ the scale will highlight the part of the trough between the origin glib:type-struct="ScaleButtonClass"> `GtkScaleButton` provides a button which pops up a scale widget. + line="63">Provides a button which pops up a scale widget. This kind of widget is commonly used for volume controls in multimedia applications, and GTK provides a [class@Gtk.VolumeButton] subclass that is tailored for this use case. +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.ScaleButton::popup] + # CSS nodes ``` @@ -118943,7 +121457,7 @@ style class, and contains a `button` node with a `.toggle` style class. Creates a `GtkScaleButton`. + line="601">Creates a `GtkScaleButton`. The new scale button has a range between @min and @max, with a stepping of @step. @@ -118951,26 +121465,26 @@ with a stepping of @step. a new `GtkScaleButton` + line="616">a new `GtkScaleButton` the minimum value of the scale (usually 0) + line="603">the minimum value of the scale (usually 0) the maximum value of the scale (usually 100) + line="604">the maximum value of the scale (usually 100) the stepping of value when a scroll-wheel event, + line="605">the stepping of value when a scroll-wheel event, or up/down arrow event occurs (usually 2) @@ -118980,7 +121494,7 @@ with a stepping of @step. allow-none="1"> a %NULL-terminated + line="607">a %NULL-terminated array of icon names, or %NULL if you want to set the list later with gtk_scale_button_set_icons() @@ -119007,10 +121521,9 @@ with a stepping of @step. c:identifier="gtk_scale_button_get_active" glib:get-property="active" version="4.10"> - Queries a `GtkScaleButton` and returns its current state. + line="823">Queries a `GtkScaleButton` and returns its current state. Returns %TRUE if the scale button is pressed in and %FALSE if it is raised. @@ -119018,14 +121531,14 @@ if it is raised. whether the button is pressed + line="832">whether the button is pressed a `GtkScaleButton` + line="825">a `GtkScaleButton` @@ -119033,24 +121546,46 @@ if it is raised. - Gets the `GtkAdjustment` associated with the `GtkScaleButton`’s scale. + line="704">Gets the `GtkAdjustment` associated with the `GtkScaleButton`’s scale. See [method@Gtk.Range.get_adjustment] for details. the adjustment associated with the scale + line="712">the adjustment associated with the scale a `GtkScaleButton` + line="706">a `GtkScaleButton` + + + + + + Returns whether the button has a frame. + + + %TRUE if the button has a frame + + + + + a `GtkScaleButton` @@ -119059,12 +121594,12 @@ See [method@Gtk.Range.get_adjustment] for details. c:identifier="gtk_scale_button_get_minus_button"> Retrieves the minus button of the `GtkScaleButton`. + line="786">Retrieves the minus button of the `GtkScaleButton`. the minus button + line="792">the minus button of the `GtkScaleButton` @@ -119072,7 +121607,7 @@ See [method@Gtk.Range.get_adjustment] for details. a `GtkScaleButton` + line="788">a `GtkScaleButton` @@ -119081,12 +121616,12 @@ See [method@Gtk.Range.get_adjustment] for details. c:identifier="gtk_scale_button_get_plus_button"> Retrieves the plus button of the `GtkScaleButton.` + line="767">Retrieves the plus button of the `GtkScaleButton.` the plus button + line="773">the plus button of the `GtkScaleButton` @@ -119094,7 +121629,7 @@ See [method@Gtk.Range.get_adjustment] for details. a `GtkScaleButton` + line="769">a `GtkScaleButton` @@ -119102,19 +121637,19 @@ See [method@Gtk.Range.get_adjustment] for details. Retrieves the popup of the `GtkScaleButton`. + line="805">Retrieves the popup of the `GtkScaleButton`. the popup of the `GtkScaleButton` + line="811">the popup of the `GtkScaleButton` a `GtkScaleButton` + line="807">a `GtkScaleButton` @@ -119122,22 +121657,21 @@ See [method@Gtk.Range.get_adjustment] for details. - Gets the current value of the scale button. + line="637">Gets the current value of the scale button. current value of the scale button + line="643">current value of the scale button a `GtkScaleButton` + line="639">a `GtkScaleButton` @@ -119145,10 +121679,9 @@ See [method@Gtk.Range.get_adjustment] for details. - Sets the `GtkAdjustment` to be used as a model + line="724">Sets the `GtkAdjustment` to be used as a model for the `GtkScaleButton`’s scale. See [method@Gtk.Range.set_adjustment] for details. @@ -119160,24 +121693,49 @@ See [method@Gtk.Range.set_adjustment] for details. a `GtkScaleButton` + line="726">a `GtkScaleButton` a `GtkAdjustment` + line="727">a `GtkAdjustment` + + Sets the style of the button. + + + + + + + a `GtkScaleButton` + + + + whether the button should have a visible frame + + + + - Sets the icons to be used by the scale button. + line="680">Sets the icons to be used by the scale button. @@ -119186,13 +121744,13 @@ See [method@Gtk.Range.set_adjustment] for details. a `GtkScaleButton` + line="682">a `GtkScaleButton` a %NULL-terminated array of icon names + line="683">a %NULL-terminated array of icon names @@ -119202,10 +121760,9 @@ See [method@Gtk.Range.set_adjustment] for details. - Sets the current value of the scale. + line="655">Sets the current value of the scale. If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. @@ -119220,13 +121777,13 @@ signal if the value changes. a `GtkScaleButton` + line="657">a `GtkScaleButton` new value of the scale button + line="658">new value of the scale button @@ -119236,11 +121793,9 @@ signal if the value changes. transfer-ownership="none" getter="get_active" default-value="FALSE"> - If the scale button should be pressed in. + line="273">If the scale button should be pressed in. transfer-ownership="none" setter="set_adjustment" getter="get_adjustment"> - - The `GtkAdjustment` that is used as the model. + line="236">The `GtkAdjustment` that is used as the model. + + If the scale button has a frame. + + - The names of the icons to be used by the scale button. + line="247">The names of the icons to be used by the scale button. The first item in the array will be used in the button when the current value is the lowest value, the second @@ -119291,13 +121852,9 @@ better for the users. setter="set_value" getter="get_value" default-value="0.000000"> - - The value of the scale. + line="223">The value of the scale. @@ -119306,7 +121863,7 @@ better for the users. Emitted to dismiss the popup. + line="335">Emitted to dismiss the popup. This is a [keybinding signal](class.SignalAction.html). @@ -119318,7 +121875,7 @@ The default binding for this signal is <kbd>Escape</kbd>. Emitted to popup the scale widget. + line="315">Emitted to popup the scale widget. This is a [keybinding signal](class.SignalAction.html). @@ -119331,7 +121888,7 @@ The default bindings for this signal are <kbd>Space</kbd>, Emitted when the value field has changed. + line="299">Emitted when the value field has changed. @@ -119339,7 +121896,7 @@ The default bindings for this signal are <kbd>Space</kbd>, the new value + line="302">the new value @@ -119391,7 +121948,7 @@ The default bindings for this signal are <kbd>Space</kbd>, a `GtkScale` + line="1609">a `GtkScale` location to store X offset of layout + line="1610">location to store X offset of layout location to store Y offset of layout + line="1611">location to store Y offset of layout @@ -119426,11 +121983,16 @@ The default bindings for this signal are <kbd>Space</kbd>, - + Function that formats the value of a scale. + +See [method@Gtk.Scale.set_format_value_func]. + A newly allocated string describing a textual representation + line="77">A newly allocated string describing a textual representation of the given numerical value. @@ -119468,23 +122030,22 @@ The default bindings for this signal are <kbd>Space</kbd>, c:symbol-prefix="scroll_info"> The `GtkScrollInfo` can be used to provide more accurate data on how a scroll -operation should be performed. + line="18">Provides detailed information on how a scroll operation should be performed. -Scrolling functions usually allow passing a %NULL scroll info which will cause -the default values to be used and just scroll the element into view. - +Scrolling functions usually allow passing a `NULL` scroll info which will +cause the default values to be used and just scroll the element into view. + Creates a new scroll info for scrolling an element into view. + line="52">Creates a new scroll info for scrolling an element into view. A new scroll info + line="57">A new scroll info @@ -119493,19 +122054,19 @@ the default values to be used and just scroll the element into view. version="4.12"> Checks if horizontal scrolling is enabled. + line="136">Checks if horizontal scrolling is enabled. %TRUE if horizontal scrolling is enabled. + line="142">%TRUE if horizontal scrolling is enabled. a `GtkScrollInfo` + line="138">a `GtkScrollInfo` @@ -119515,19 +122076,19 @@ the default values to be used and just scroll the element into view. version="4.12"> Checks if vertical scrolling is enabled. + line="173">Checks if vertical scrolling is enabled. %TRUE if vertical scrolling is enabled. + line="179">%TRUE if vertical scrolling is enabled. a `GtkScrollInfo` + line="175">a `GtkScrollInfo` @@ -119535,19 +122096,19 @@ the default values to be used and just scroll the element into view. Increases the reference count of a `GtkScrollInfo` by one. + line="74">Increases the reference count of a `GtkScrollInfo` by one. the passed in `GtkScrollInfo`. + line="80">the passed in `GtkScrollInfo`. a `GtkScrollInfo` + line="76">a `GtkScrollInfo` @@ -119557,7 +122118,7 @@ the default values to be used and just scroll the element into view. version="4.12"> Turns horizontal scrolling on or off. + line="117">Turns horizontal scrolling on or off. @@ -119566,13 +122127,13 @@ the default values to be used and just scroll the element into view. a `GtkScrollInfo` + line="119">a `GtkScrollInfo` if scrolling in the horizontal direction + line="120">if scrolling in the horizontal direction should happen @@ -119583,7 +122144,7 @@ the default values to be used and just scroll the element into view. version="4.12"> Turns vertical scrolling on or off. + line="154">Turns vertical scrolling on or off. @@ -119592,13 +122153,13 @@ the default values to be used and just scroll the element into view. a `GtkScrollInfo` + line="156">a `GtkScrollInfo` if scrolling in the vertical direction + line="157">if scrolling in the vertical direction should happen @@ -119607,7 +122168,7 @@ the default values to be used and just scroll the element into view. Decreases the reference count of a `GtkScrollInfo` by one. + line="94">Decreases the reference count of a `GtkScrollInfo` by one. If the resulting reference count is zero, frees the self. @@ -119618,7 +122179,7 @@ If the resulting reference count is zero, frees the self. a `GtkScrollInfo` + line="96">a `GtkScrollInfo` @@ -119630,7 +122191,7 @@ If the resulting reference count is zero, frees the self. c:type="GtkScrollStep"> Passed as argument to various keybinding signals. + line="407">Passed as argument to various keybinding signals. glib:name="GTK_SCROLL_STEPS"> Scroll in steps. + line="409">Scroll in steps. glib:name="GTK_SCROLL_PAGES"> Scroll by pages. + line="410">Scroll by pages. glib:name="GTK_SCROLL_ENDS"> Scroll to ends. + line="411">Scroll to ends. glib:name="GTK_SCROLL_HORIZONTAL_STEPS"> Scroll in horizontal steps. + line="412">Scroll in horizontal steps. glib:name="GTK_SCROLL_HORIZONTAL_PAGES"> Scroll by horizontal pages. + line="413">Scroll by horizontal pages. glib:name="GTK_SCROLL_HORIZONTAL_ENDS"> Scroll to the horizontal ends. + line="414">Scroll to the horizontal ends. c:type="GtkScrollType"> Scrolling types. + line="497">Scrolling types. glib:name="GTK_SCROLL_NONE"> No scrolling. + line="499">No scrolling. glib:name="GTK_SCROLL_JUMP"> Jump to new location. + line="500">Jump to new location. glib:name="GTK_SCROLL_STEP_BACKWARD"> Step backward. + line="501">Step backward. glib:name="GTK_SCROLL_STEP_FORWARD"> Step forward. + line="502">Step forward. glib:name="GTK_SCROLL_PAGE_BACKWARD"> Page backward. + line="503">Page backward. glib:name="GTK_SCROLL_PAGE_FORWARD"> Page forward. + line="504">Page forward. glib:name="GTK_SCROLL_STEP_UP"> Step up. + line="505">Step up. glib:name="GTK_SCROLL_STEP_DOWN"> Step down. + line="506">Step down. glib:name="GTK_SCROLL_PAGE_UP"> Page up. + line="507">Page up. glib:name="GTK_SCROLL_PAGE_DOWN"> Page down. + line="508">Page down. glib:name="GTK_SCROLL_STEP_LEFT"> Step to the left. + line="509">Step to the left. glib:name="GTK_SCROLL_STEP_RIGHT"> Step to the right. + line="510">Step to the right. glib:name="GTK_SCROLL_PAGE_LEFT"> Page to the left. + line="511">Page to the left. glib:name="GTK_SCROLL_PAGE_RIGHT"> Page to the right. + line="512">Page to the right. glib:name="GTK_SCROLL_START"> Scroll to start. + line="513">Scroll to start. glib:name="GTK_SCROLL_END"> Scroll to end. + line="514">Scroll to end. glib:type-struct="ScrollableInterface"> `GtkScrollable` is an interface for widgets with native scrolling ability. + line="18">An interface for widgets with native scrolling ability. To implement this interface you should override the [property@Gtk.Scrollable:hadjustment] and @@ -119946,7 +122507,6 @@ overshoot indication, at the right position. - Retrieves the `GtkAdjustment` used for horizontal scrolling. @@ -119969,7 +122529,6 @@ overshoot indication, at the right position. - Gets the horizontal `GtkScrollablePolicy`. @@ -119992,7 +122551,6 @@ overshoot indication, at the right position. - Retrieves the `GtkAdjustment` used for vertical scrolling. @@ -120015,7 +122573,6 @@ overshoot indication, at the right position. - Gets the vertical `GtkScrollablePolicy`. @@ -120038,7 +122595,6 @@ overshoot indication, at the right position. - Sets the horizontal adjustment of the `GtkScrollable`. @@ -120067,7 +122623,6 @@ overshoot indication, at the right position. - Sets the `GtkScrollablePolicy`. @@ -120096,7 +122651,6 @@ below the minimum width or below the natural width. - Sets the vertical adjustment of the `GtkScrollable`. @@ -120125,7 +122679,6 @@ below the minimum width or below the natural width. - Sets the `GtkScrollablePolicy`. @@ -120157,10 +122710,6 @@ below the minimum height or below the natural height. transfer-ownership="none" setter="set_hadjustment" getter="get_hadjustment"> - - Horizontal `GtkAdjustment` of the scrollable widget. @@ -120174,10 +122723,6 @@ This adjustment is shared between the scrollable widget and its parent. setter="set_hscroll_policy" getter="get_hscroll_policy" default-value="GTK_SCROLL_MINIMUM"> - - Determines when horizontal scrolling should start. @@ -120189,10 +122734,6 @@ This adjustment is shared between the scrollable widget and its parent. transfer-ownership="none" setter="set_vadjustment" getter="get_vadjustment"> - - Vertical `GtkAdjustment` of the scrollable widget. @@ -120206,10 +122747,6 @@ This adjustment is shared between the scrollable widget and its parent. setter="set_vscroll_policy" getter="get_vscroll_policy" default-value="GTK_SCROLL_MINIMUM"> - - Determines when vertical scrolling should start. @@ -120258,7 +122795,7 @@ This adjustment is shared between the scrollable widget and its parent. c:type="GtkScrollablePolicy"> Defines the policy to be used in a scrollable widget when updating + line="818">Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation. glib:name="GTK_SCROLL_MINIMUM"> Scrollable adjustments are based on the minimum size + line="820">Scrollable adjustments are based on the minimum size glib:name="GTK_SCROLL_NATURAL"> Scrollable adjustments are based on the natural size + line="821">Scrollable adjustments are based on the natural size glib:get-type="gtk_scrollbar_get_type"> The `GtkScrollbar` widget is a horizontal or vertical scrollbar. + line="39">Shows a horizontal or vertical scrollbar. -![An example GtkScrollbar](scrollbar.png) +<picture> + <source srcset="scrollbar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkScrollbar" src="scrollbar.png"> +</picture> Its position and movement are controlled by the adjustment that is passed to or created by [ctor@Gtk.Scrollbar.new]. See [class@Gtk.Adjustment] for more @@ -120328,27 +122868,28 @@ Other style classes that may be added to scrollbars inside # Accessibility -`GtkScrollbar` uses the %GTK_ACCESSIBLE_ROLE_SCROLLBAR role. +`GtkScrollbar` uses the [enum@Gtk.AccessibleRole.scrollbar] role. + Creates a new scrollbar with the given orientation. + line="279">Creates a new scrollbar with the given orientation. the new `GtkScrollbar`. + line="287">the new `GtkScrollbar`. the scrollbar’s orientation. + line="281">the scrollbar’s orientation. the [class@Gtk.Adjustment] to use, or %NULL + line="282">the [class@Gtk.Adjustment] to use, or %NULL to create a new adjustment. @@ -120366,22 +122907,21 @@ Other style classes that may be added to scrollbars inside - Returns the scrollbar's adjustment. + line="371">Returns the scrollbar's adjustment. the scrollbar's adjustment + line="377">the scrollbar's adjustment a `GtkScrollbar` + line="373">a `GtkScrollbar` @@ -120389,10 +122929,9 @@ Other style classes that may be added to scrollbars inside - Makes the scrollbar use the given adjustment. + line="325">Makes the scrollbar use the given adjustment. @@ -120401,7 +122940,7 @@ Other style classes that may be added to scrollbars inside a `GtkScrollbar` + line="327">a `GtkScrollbar` the adjustment to set + line="328">the adjustment to set @@ -120421,13 +122960,9 @@ Other style classes that may be added to scrollbars inside transfer-ownership="none" setter="set_adjustment" getter="get_adjustment"> - - The `GtkAdjustment` controlled by this scrollbar. + line="242">The `GtkAdjustment` controlled by this scrollbar. @@ -120439,7 +122974,12 @@ Other style classes that may be added to scrollbars inside glib:get-type="gtk_scrolled_window_get_type"> `GtkScrolledWindow` is a container that makes its child scrollable. + line="60">Makes its child scrollable. + +<picture> + <source srcset="scrolledwindow-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkScrolledWindow" src="scrolledwindow.png"> +</picture> It does so using either internally added scrollbars or externally associated adjustments, and optionally draws a frame around the child. @@ -120485,6 +123025,12 @@ scrollbars are desired although no mouse is present, this behaviour can be turned off with the [property@Gtk.ScrolledWindow:overlay-scrolling] property. +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.ScrolledWindow::scroll-child] + # CSS nodes `GtkScrolledWindow` has a main CSS node with name scrolledwindow. @@ -120504,31 +123050,31 @@ with a subnode named junction. # Accessibility -Until GTK 4.10, `GtkScrolledWindow` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkScrolledWindow` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkScrolledWindow` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkScrolledWindow` uses the [enum@Gtk.AccessibleRole.generic] +role. Creates a new scrolled window. + line="2194">Creates a new scrolled window. a new scrolled window + line="2199">a new scrolled window - Gets the child widget of @scrolled_window. + line="4359">Gets the child widget of @scrolled_window. If the scrolled window automatically added a [class@Gtk.Viewport], this function will return the viewport widget, and you can retrieve its child @@ -120537,14 +123083,14 @@ using [method@Gtk.Viewport.get_child]. the child widget of @scrolled_window + line="4369">the child widget of @scrolled_window a `GtkScrolledWindow` + line="4361">a `GtkScrolledWindow` @@ -120552,10 +123098,9 @@ using [method@Gtk.Viewport.get_child]. - Returns the horizontal scrollbar’s adjustment. + line="2345">Returns the horizontal scrollbar’s adjustment. This is the adjustment used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality. @@ -120563,14 +123108,14 @@ to the child widget’s horizontal scroll functionality. the horizontal `GtkAdjustment` + line="2354">the horizontal `GtkAdjustment` a `GtkScrolledWindow` + line="2347">a `GtkScrolledWindow` @@ -120578,22 +123123,21 @@ to the child widget’s horizontal scroll functionality. - Gets whether the scrolled window draws a frame. + line="2587">Gets whether the scrolled window draws a frame. %TRUE if the @scrolled_window has a frame + line="2593">%TRUE if the @scrolled_window has a frame a `GtkScrolledWindow` + line="2589">a `GtkScrolledWindow` @@ -120602,19 +123146,19 @@ to the child widget’s horizontal scroll functionality. c:identifier="gtk_scrolled_window_get_hscrollbar"> Returns the horizontal scrollbar of @scrolled_window. + line="2387">Returns the horizontal scrollbar of @scrolled_window. the horizontal scrollbar of the scrolled window. + line="2393">the horizontal scrollbar of the scrolled window. a `GtkScrolledWindow` + line="2389">a `GtkScrolledWindow` @@ -120622,23 +123166,21 @@ to the child widget’s horizontal scroll functionality. - Returns the specified kinetic scrolling behavior. + line="2643">Returns the specified kinetic scrolling behavior. the scrolling behavior flags. + line="2649">the scrolling behavior flags. a `GtkScrolledWindow` + line="2645">a `GtkScrolledWindow` @@ -120646,23 +123188,21 @@ to the child widget’s horizontal scroll functionality. - Returns the maximum content height set. + line="4152">Returns the maximum content height set. the maximum content height, or -1 + line="4158">the maximum content height, or -1 a `GtkScrolledWindow` + line="4154">a `GtkScrolledWindow` @@ -120670,23 +123210,21 @@ to the child widget’s horizontal scroll functionality. - Returns the maximum content width set. + line="4103">Returns the maximum content width set. the maximum content width, or -1 + line="4109">the maximum content width, or -1 a `GtkScrolledWindow` + line="4105">a `GtkScrolledWindow` @@ -120694,23 +123232,21 @@ to the child widget’s horizontal scroll functionality. - Gets the minimal content height of @scrolled_window. + line="3978">Gets the minimal content height of @scrolled_window. the minimal content height + line="3984">the minimal content height a `GtkScrolledWindow` + line="3980">a `GtkScrolledWindow` @@ -120718,23 +123254,21 @@ to the child widget’s horizontal scroll functionality. - Gets the minimum content width of @scrolled_window. + line="3927">Gets the minimum content width of @scrolled_window. the minimum content width + line="3933">the minimum content width a `GtkScrolledWindow` + line="3929">a `GtkScrolledWindow` @@ -120742,46 +123276,43 @@ to the child widget’s horizontal scroll functionality. - Returns whether overlay scrolling is enabled for this scrolled window. + line="4054">Returns whether overlay scrolling is enabled for this scrolled window. %TRUE if overlay scrolling is enabled + line="4060">%TRUE if overlay scrolling is enabled a `GtkScrolledWindow` + line="4056">a `GtkScrolledWindow` - + c:identifier="gtk_scrolled_window_get_placement" + glib:get-property="window-placement"> Gets the placement of the contents with respect to the scrollbars. + line="2524">Gets the placement of the contents with respect to the scrollbars. the current placement value. + line="2530">the current placement value. a `GtkScrolledWindow` + line="2526">a `GtkScrolledWindow` @@ -120789,7 +123320,7 @@ to the child widget’s horizontal scroll functionality. Retrieves the current policy values for the horizontal and vertical + line="2461">Retrieves the current policy values for the horizontal and vertical scrollbars. See [method@Gtk.ScrolledWindow.set_policy]. @@ -120801,7 +123332,7 @@ See [method@Gtk.ScrolledWindow.set_policy]. a `GtkScrolledWindow` + line="2463">a `GtkScrolledWindow` allow-none="1"> location to store the policy + line="2464">location to store the policy for the horizontal scrollbar @@ -120824,7 +123355,7 @@ See [method@Gtk.ScrolledWindow.set_policy]. allow-none="1"> location to store the policy + line="2466">location to store the policy for the vertical scrollbar @@ -120833,24 +123364,22 @@ See [method@Gtk.ScrolledWindow.set_policy]. - Reports whether the natural height of the child will be calculated + line="4241">Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height. whether natural height propagation is enabled. + line="4248">whether natural height propagation is enabled. a `GtkScrolledWindow` + line="4243">a `GtkScrolledWindow` @@ -120858,24 +123387,22 @@ and propagated through the scrolled window’s requested natural height. - Reports whether the natural width of the child will be calculated + line="4196">Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width. whether natural width propagation is enabled. + line="4203">whether natural width propagation is enabled. a `GtkScrolledWindow` + line="4198">a `GtkScrolledWindow` @@ -120883,10 +123410,9 @@ and propagated through the scrolled window’s requested natural width. - Returns the vertical scrollbar’s adjustment. + line="2366">Returns the vertical scrollbar’s adjustment. This is the adjustment used to connect the vertical scrollbar to the child widget’s vertical scroll functionality. @@ -120894,14 +123420,14 @@ scrollbar to the child widget’s vertical scroll functionality. the vertical `GtkAdjustment` + line="2375">the vertical `GtkAdjustment` a `GtkScrolledWindow` + line="2368">a `GtkScrolledWindow` @@ -120910,19 +123436,19 @@ scrollbar to the child widget’s vertical scroll functionality. c:identifier="gtk_scrolled_window_get_vscrollbar"> Returns the vertical scrollbar of @scrolled_window. + line="2405">Returns the vertical scrollbar of @scrolled_window. the vertical scrollbar of the scrolled window. + line="2411">the vertical scrollbar of the scrolled window. a `GtkScrolledWindow` + line="2407">a `GtkScrolledWindow` @@ -120930,10 +123456,9 @@ scrollbar to the child widget’s vertical scroll functionality. - Sets the child widget of @scrolled_window. + line="4260">Sets the child widget of @scrolled_window. If @child does not implement the [iface@Gtk.Scrollable] interface, the scrolled window will add @child to a [class@Gtk.Viewport] instance @@ -120946,7 +123471,7 @@ and then add the viewport as its child widget. a `GtkScrolledWindow` + line="4262">a `GtkScrolledWindow` allow-none="1"> the child widget + line="4263">the child widget @@ -120963,10 +123488,9 @@ and then add the viewport as its child widget. - Sets the `GtkAdjustment` for the horizontal scrollbar. + line="2207">Sets the `GtkAdjustment` for the horizontal scrollbar. @@ -120975,7 +123499,7 @@ and then add the viewport as its child widget. a `GtkScrolledWindow` + line="2209">a `GtkScrolledWindow` allow-none="1"> the `GtkAdjustment` to use, or %NULL to create a new one + line="2210">the `GtkAdjustment` to use, or %NULL to create a new one @@ -120992,10 +123516,9 @@ and then add the viewport as its child widget. - Changes the frame drawn around the contents of @scrolled_window. + line="2559">Changes the frame drawn around the contents of @scrolled_window. @@ -121004,13 +123527,13 @@ and then add the viewport as its child widget. a `GtkScrolledWindow` + line="2561">a `GtkScrolledWindow` whether to draw a frame around scrolled window contents + line="2562">whether to draw a frame around scrolled window contents @@ -121018,11 +123541,9 @@ and then add the viewport as its child widget. - Turns kinetic scrolling on or off. + line="2605">Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. @@ -121034,13 +123555,13 @@ Kinetic scrolling only applies to devices with source a `GtkScrolledWindow` + line="2607">a `GtkScrolledWindow` %TRUE to enable kinetic scrolling + line="2608">%TRUE to enable kinetic scrolling @@ -121048,11 +123569,9 @@ Kinetic scrolling only applies to devices with source - Sets the maximum height that @scrolled_window should keep visible. + line="4121">Sets the maximum height that @scrolled_window should keep visible. The @scrolled_window will grow up to this height before it starts scrolling the content. @@ -121067,13 +123586,13 @@ smaller than [property@Gtk.ScrolledWindow:min-content-height]. a `GtkScrolledWindow` + line="4123">a `GtkScrolledWindow` the maximum content height + line="4124">the maximum content height @@ -121081,11 +123600,9 @@ smaller than [property@Gtk.ScrolledWindow:min-content-height]. - Sets the maximum width that @scrolled_window should keep visible. + line="4072">Sets the maximum width that @scrolled_window should keep visible. The @scrolled_window will grow up to this width before it starts scrolling the content. @@ -121100,13 +123617,13 @@ value smaller than [property@Gtk.ScrolledWindow:min-content-width]. a `GtkScrolledWindow` + line="4074">a `GtkScrolledWindow` the maximum content width + line="4075">the maximum content width @@ -121114,11 +123631,9 @@ value smaller than [property@Gtk.ScrolledWindow:min-content-width]. - Sets the minimum height that @scrolled_window should keep visible. + line="3996">Sets the minimum height that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. @@ -121133,13 +123648,13 @@ value greater than [property@Gtk.ScrolledWindow:max-content-height]. a `GtkScrolledWindow` + line="3998">a `GtkScrolledWindow` the minimal content height + line="3999">the minimal content height @@ -121147,11 +123662,9 @@ value greater than [property@Gtk.ScrolledWindow:max-content-height]. - Sets the minimum width that @scrolled_window should keep visible. + line="3945">Sets the minimum width that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. @@ -121166,13 +123679,13 @@ value greater than [property@Gtk.ScrolledWindow:max-content-width]. a `GtkScrolledWindow` + line="3947">a `GtkScrolledWindow` the minimal content width + line="3948">the minimal content width @@ -121180,11 +123693,9 @@ value greater than [property@Gtk.ScrolledWindow:max-content-width]. - Enables or disables overlay scrolling for this scrolled window. + line="4029">Enables or disables overlay scrolling for this scrolled window. @@ -121193,24 +123704,23 @@ value greater than [property@Gtk.ScrolledWindow:max-content-width]. a `GtkScrolledWindow` + line="4031">a `GtkScrolledWindow` whether to enable overlay scrolling + line="4032">whether to enable overlay scrolling - + c:identifier="gtk_scrolled_window_set_placement" + glib:set-property="window-placement"> Sets the placement of the contents with respect to the scrollbars + line="2489">Sets the placement of the contents with respect to the scrollbars for the scrolled window. The default is %GTK_CORNER_TOP_LEFT, meaning the child is @@ -121228,13 +123738,13 @@ See also [method@Gtk.ScrolledWindow.get_placement] and a `GtkScrolledWindow` + line="2491">a `GtkScrolledWindow` position of the child window + line="2492">position of the child window @@ -121242,7 +123752,7 @@ See also [method@Gtk.ScrolledWindow.get_placement] and Sets the scrollbar policy for the horizontal and vertical scrollbars. + line="2423">Sets the scrollbar policy for the horizontal and vertical scrollbars. The policy determines when the scrollbar should appear; it is a value from the [enum@Gtk.PolicyType] enumeration. If %GTK_POLICY_ALWAYS, the @@ -121258,19 +123768,19 @@ than the trough — the display is larger than the page size). a `GtkScrolledWindow` + line="2425">a `GtkScrolledWindow` policy for horizontal bar + line="2426">policy for horizontal bar policy for vertical bar + line="2427">policy for vertical bar @@ -121278,11 +123788,9 @@ than the trough — the display is larger than the page size). - Sets whether the natural height of the child should be calculated + line="4215">Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. @@ -121292,13 +123800,13 @@ and propagated through the scrolled window’s requested natural height. a `GtkScrolledWindow` + line="4217">a `GtkScrolledWindow` whether to propagate natural height + line="4218">whether to propagate natural height @@ -121306,11 +123814,9 @@ and propagated through the scrolled window’s requested natural height. - Sets whether the natural width of the child should be calculated + line="4170">Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. @@ -121320,13 +123826,13 @@ and propagated through the scrolled window’s requested natural width. a `GtkScrolledWindow` + line="4172">a `GtkScrolledWindow` whether to propagate natural width + line="4173">whether to propagate natural width @@ -121334,10 +123840,9 @@ and propagated through the scrolled window’s requested natural width. - Sets the `GtkAdjustment` for the vertical scrollbar. + line="2276">Sets the `GtkAdjustment` for the vertical scrollbar. @@ -121346,7 +123851,7 @@ and propagated through the scrolled window’s requested natural width. a `GtkScrolledWindow` + line="2278">a `GtkScrolledWindow` allow-none="1"> the `GtkAdjustment` to use, or %NULL to create a new one + line="2279">the `GtkAdjustment` to use, or %NULL to create a new one @@ -121364,7 +123869,7 @@ and propagated through the scrolled window’s requested natural width. c:identifier="gtk_scrolled_window_unset_placement"> Unsets the placement of the contents with respect to the scrollbars. + line="2542">Unsets the placement of the contents with respect to the scrollbars. If no window placement is set for a scrolled window, it defaults to %GTK_CORNER_TOP_LEFT. @@ -121376,7 +123881,7 @@ it defaults to %GTK_CORNER_TOP_LEFT. a `GtkScrolledWindow` + line="2544">a `GtkScrolledWindow` @@ -121386,13 +123891,9 @@ it defaults to %GTK_CORNER_TOP_LEFT. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="781">The child widget. When setting this property, if the child widget does not implement [iface@Gtk.Scrollable], the scrolled window will add the child to @@ -121405,6 +123906,9 @@ a [class@Gtk.Viewport] and then set the viewport as the child. transfer-ownership="none" setter="set_hadjustment" getter="get_hadjustment"> + The `GtkAdjustment` for the horizontal position. setter="set_has_frame" getter="get_has_frame" default-value="FALSE"> - - Whether to draw a frame around the contents. + line="674">Whether to draw a frame around the contents. default-value="GTK_POLICY_AUTOMATIC"> When the horizontal scrollbar is displayed. + line="635">When the horizontal scrollbar is displayed. Use [method@Gtk.ScrolledWindow.set_policy] to set this property. @@ -121440,13 +123940,9 @@ this property. setter="set_kinetic_scrolling" getter="get_kinetic_scrolling" default-value="TRUE"> - - Whether kinetic scrolling is enabled or not. + line="704">Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. @@ -121457,13 +123953,9 @@ Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. - - The maximum content height of @scrolled_window. + line="743">The maximum content height of @scrolled_window. - - The maximum content width of @scrolled_window. + line="733">The maximum content width of @scrolled_window. - - The minimum content height of @scrolled_window. + line="694">The minimum content height of @scrolled_window. - - The minimum content width of @scrolled_window. + line="684">The minimum content width of @scrolled_window. - - Whether overlay scrolling is enabled or not. + line="716">Whether overlay scrolling is enabled or not. If it is, the scrollbars are only added as traditional widgets when a mouse is present. Otherwise, they are overlaid on top of @@ -121539,13 +124015,9 @@ the [property@Gtk.Settings:gtk-overlay-scrolling] setting. setter="set_propagate_natural_height" getter="get_propagate_natural_height" default-value="FALSE"> - - Whether the natural height of the child should be calculated and propagated + line="767">Whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. This is useful in cases where an attempt should be made to allocate exactly @@ -121558,13 +124030,9 @@ enough space for the natural size of the child. setter="set_propagate_natural_width" getter="get_propagate_natural_width" default-value="FALSE"> - - Whether the natural width of the child should be calculated and propagated + line="753">Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. This is useful in cases where an attempt should be made to allocate exactly @@ -121577,6 +124045,9 @@ enough space for the natural size of the child. transfer-ownership="none" setter="set_vadjustment" getter="get_vadjustment"> + The `GtkAdjustment` for the vertical position. default-value="GTK_POLICY_AUTOMATIC"> When the vertical scrollbar is displayed. + line="649">When the vertical scrollbar is displayed. Use [method@Gtk.ScrolledWindow.set_policy] to set this property. @@ -121594,20 +124065,18 @@ this property. - - Where the contents are located with respect to the scrollbars. + line="663">Where the contents are located with respect to the scrollbars. Emitted whenever user initiated scrolling makes the scrolled + line="852">Emitted whenever user initiated scrolling makes the scrolled window firmly surpass the limits defined by the adjustment in that orientation. @@ -121623,7 +124092,7 @@ aware too if intending to provide behavior on horizontal edges. edge side that was hit + line="855">edge side that was hit @@ -121631,7 +124100,7 @@ aware too if intending to provide behavior on horizontal edges. Emitted whenever user-initiated scrolling makes the scrolled + line="874">Emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation. @@ -121647,7 +124116,7 @@ aware too if intending to provide behavior on horizontal edges. edge side that was reached + line="877">edge side that was reached @@ -121655,14 +124124,14 @@ aware too if intending to provide behavior on horizontal edges. Emitted when focus is moved away from the scrolled window by a + line="827">Emitted when focus is moved away from the scrolled window by a keybinding. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are -`Ctrl + Tab` to move forward and `Ctrl + Shift + Tab` to -move backward. +<kbd>Ctrl</kbd>+<kbd>Tab</kbd> to move forward and +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>` to move backward. @@ -121670,7 +124139,7 @@ move backward. either %GTK_DIR_TAB_FORWARD or + line="830">either %GTK_DIR_TAB_FORWARD or %GTK_DIR_TAB_BACKWARD @@ -121679,26 +124148,29 @@ move backward. Emitted when a keybinding that scrolls is pressed. + line="797">Emitted when a keybinding that scrolls is pressed. This is a [keybinding signal](class.SignalAction.html). The horizontal or vertical adjustment is updated which triggers a signal that the scrolled window’s child may listen to and scroll itself. + whether the scroll happened a `GtkScrollType` describing how much to scroll + line="800">a `GtkScrollType` describing how much to scroll whether the keybinding scrolls the child + line="801">whether the keybinding scrolls the child horizontally or not @@ -121713,9 +124185,12 @@ signal that the scrolled window’s child may listen to and scroll itself. glib:get-type="gtk_search_bar_get_type"> `GtkSearchBar` is a container made to have a search entry. + line="45">Reveals a search entry when search is started. -![An example GtkSearchBar](search-bar.png) +<picture> + <source srcset="search-bar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkSearchBar" src="search-bar.png"> +</picture> It can also contain additional widgets, such as drop-down menus, or buttons. The search bar would appear when a search is started @@ -121739,6 +124214,12 @@ entry. [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/search-bar.c) +# Shortcuts and Gestures + +`GtkSearchBar` supports the following keyboard shortcuts: + +- <kbd>Escape</kbd> hides the search bar. + # CSS nodes ``` @@ -121756,14 +124237,14 @@ node which gets the .close style class applied. # Accessibility -`GtkSearchBar` uses the %GTK_ACCESSIBLE_ROLE_SEARCH role. +`GtkSearchBar` uses the [enum@Gtk.AccessibleRole.search] role. Creates a `GtkSearchBar`. + line="389">Creates a `GtkSearchBar`. You will need to tell it about which widget is going to be your text entry using [method@Gtk.SearchBar.connect_entry]. @@ -121771,14 +124252,14 @@ entry using [method@Gtk.SearchBar.connect_entry]. a new `GtkSearchBar` + line="397">a new `GtkSearchBar` Connects the `GtkEditable` widget passed as the one to be used in + line="435">Connects the `GtkEditable` widget passed as the one to be used in this search bar. The entry should be a descendant of the search bar. Calling this @@ -121792,13 +124273,13 @@ child of the search bar (as in our main example). a `GtkSearchBar` + line="437">a `GtkSearchBar` a `GtkEditable` + line="438">a `GtkEditable` @@ -121806,22 +124287,21 @@ child of the search bar (as in our main example). - Gets the child widget of @bar. + line="720">Gets the child widget of @bar. the child widget of @bar + line="726">the child widget of @bar a `GtkSearchBar` + line="722">a `GtkSearchBar` @@ -121829,46 +124309,43 @@ child of the search bar (as in our main example). - Gets the widget that @bar is capturing key events from. + line="666">Gets the widget that @bar is capturing key events from. The key capture widget. + line="672">The key capture widget. a `GtkSearchBar` + line="668">a `GtkSearchBar` - + c:identifier="gtk_search_bar_get_search_mode" + glib:get-property="search-mode-enabled"> Returns whether the search mode is on or off. + line="457">Returns whether the search mode is on or off. whether search mode is toggled on + line="463">whether search mode is toggled on a `GtkSearchBar` + line="459">a `GtkSearchBar` @@ -121876,23 +124353,21 @@ child of the search bar (as in our main example). - Returns whether the close button is shown. + line="489">Returns whether the close button is shown. whether the close button is shown + line="495">whether the close button is shown a `GtkSearchBar` + line="491">a `GtkSearchBar` @@ -121900,10 +124375,9 @@ child of the search bar (as in our main example). - Sets the child widget of @bar. + line="682">Sets the child widget of @bar. @@ -121912,7 +124386,7 @@ child of the search bar (as in our main example). a `GtkSearchBar` + line="684">a `GtkSearchBar` allow-none="1"> the child widget + line="685">the child widget @@ -121929,11 +124403,9 @@ child of the search bar (as in our main example). - Sets @widget as the widget that @bar will capture key events + line="610">Sets @widget as the widget that @bar will capture key events from. If key events are handled by the search bar, the bar will @@ -121953,7 +124425,7 @@ capture and forward the events yourself with a `GtkSearchBar` + line="612">a `GtkSearchBar` a `GtkWidget` + line="613">a `GtkWidget` - + c:identifier="gtk_search_bar_set_search_mode" + glib:set-property="search-mode-enabled"> Switches the search mode on or off. + line="473">Switches the search mode on or off. @@ -121982,13 +124453,13 @@ capture and forward the events yourself with a `GtkSearchBar` + line="475">a `GtkSearchBar` the new state of the search mode + line="476">the new state of the search mode @@ -121996,11 +124467,9 @@ capture and forward the events yourself with - Shows or hides the close button. + line="505">Shows or hides the close button. Applications that already have a “search” toggle button should not show a close button in their search bar, as it duplicates the role @@ -122013,13 +124482,13 @@ of the toggle button. a `GtkSearchBar` + line="507">a `GtkSearchBar` whether the close button will be shown or not + line="508">whether the close button will be shown or not @@ -122030,13 +124499,9 @@ of the toggle button. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="337">The child widget. transfer-ownership="none" setter="set_key_capture_widget" getter="get_key_capture_widget"> - - The key capture widget. + line="346">The key capture widget. - - Whether the search mode is on and the search bar shown. + line="319">Whether the search mode is on and the search bar shown. setter="set_show_close_button" getter="get_show_close_button" default-value="FALSE"> - - Whether to show the close button in the search bar. + line="328">Whether to show the close button in the search bar. @@ -122092,13 +124547,15 @@ of the toggle button. glib:get-type="gtk_search_entry_get_type"> `GtkSearchEntry` is an entry widget that has been tailored for use -as a search entry. + line="47">A single-line text entry widget for use as a search entry. The main API for interacting with a `GtkSearchEntry` as entry is the `GtkEditable` interface. -![An example GtkSearchEntry](search-entry.png) +<picture> + <source srcset="search-entry-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkSearchEntry" src="search-entry.png"> +</picture> It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. @@ -122123,6 +124580,15 @@ let it capture key input from another widget. `GtkSearchEntry` provides only minimal API and should be used with the [iface@Gtk.Editable] API. +## Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.SearchEntry::activate] +- [signal@Gtk.SearchEntry::next-match] +- [signal@Gtk.SearchEntry::previous-match] +- [signal@Gtk.SearchEntry::stop-search] + ## CSS Nodes ``` @@ -122135,7 +124601,7 @@ a `.search` style class, and the text node is a child of that. ## Accessibility -`GtkSearchEntry` uses the %GTK_ACCESSIBLE_ROLE_SEARCH_BOX role. +`GtkSearchEntry` uses the [enum@Gtk.AccessibleRole.search_box] role. @@ -122143,32 +124609,78 @@ a `.search` style class, and the text node is a child of that. Creates a `GtkSearchEntry`. + line="856">Creates a `GtkSearchEntry`. a new `GtkSearchEntry` + line="861">a new `GtkSearchEntry` + + Gets the input purpose for @entry. + + + The input hints + + + + + a `GtkSearchEntry` + + + + + + Gets the input purpose of @entry. + + + The input hints + + + + + a `GtkSearchEntry` + + + + Gets the widget that @entry is capturing key events from. + line="979">Gets the widget that @entry is capturing key events from. The key capture widget. + line="985">The key capture widget. a `GtkSearchEntry` + line="981">a `GtkSearchEntry` @@ -122179,19 +124691,19 @@ a `.search` style class, and the text node is a child of that. version="4.10"> Gets the placeholder text associated with @entry. + line="1047">Gets the placeholder text associated with @entry. The placeholder text. + line="1053">The placeholder text. a `GtkSearchEntry` + line="1049">a `GtkSearchEntry` @@ -122200,32 +124712,83 @@ a `.search` style class, and the text node is a child of that. c:identifier="gtk_search_entry_get_search_delay" glib:get-property="search-delay" version="4.8"> - Get the delay to be used between the last keypress and the + line="1022">Get the delay to be used between the last keypress and the [signal@Gtk.SearchEntry::search-changed] signal being emitted. a delay in milliseconds. + line="1029">a delay in milliseconds. a `GtkSearchEntry` + line="1024">a `GtkSearchEntry` + + Sets the input hints for @entry. + + + + + + + a `GtkSearchEntry` + + + + the new input hints + + + + + + Sets the input purpose of @entry. + + + + + + + a `GtkSearchEntry` + + + + the new input purpose + + + + Sets @widget as the widget that @entry will capture key + line="923">Sets @widget as the widget that @entry will capture key events from. Key events are consumed by the search entry to start or @@ -122250,7 +124813,7 @@ capture and forward the events yourself with a `GtkSearchEntry` + line="925">a `GtkSearchEntry` a `GtkWidget` + line="926">a `GtkWidget` @@ -122270,7 +124833,7 @@ capture and forward the events yourself with version="4.10"> Sets the placeholder text associated with @entry. + line="1065">Sets the placeholder text associated with @entry. @@ -122279,7 +124842,7 @@ capture and forward the events yourself with a `GtkSearchEntry` + line="1067">a `GtkSearchEntry` the text to set as a placeholder + line="1068">the text to set as a placeholder @@ -122297,10 +124860,9 @@ capture and forward the events yourself with c:identifier="gtk_search_entry_set_search_delay" glib:set-property="search-delay" version="4.8"> - Set the delay to be used between the last keypress and the + line="995">Set the delay to be used between the last keypress and the [signal@Gtk.SearchEntry::search-changed] signal being emitted. @@ -122310,13 +124872,13 @@ capture and forward the events yourself with a `GtkSearchEntry` + line="997">a `GtkSearchEntry` a delay in milliseconds + line="998">a delay in milliseconds @@ -122327,9 +124889,35 @@ capture and forward the events yourself with default-value="FALSE"> Whether to activate the default widget when Enter is pressed. + line="510">Whether to activate the default widget when Enter is pressed. + + The hints about input for the `GtkSearchEntry` used to alter the +behaviour of input methods. + + + + The purpose for the `GtkSearchEntry` input used to alter the +behaviour of input methods. + + The text that will be displayed in the `GtkSearchEntry` + line="471">The text that will be displayed in the `GtkSearchEntry` when it is empty and unfocused. @@ -122351,16 +124939,16 @@ when it is empty and unfocused. default-value="150"> The delay in milliseconds from last keypress to the search + line="520">The delay in milliseconds from last keypress to the search changed signal. Emitted when the entry is activated. + line="536">Emitted when the entry is activated. -The keybindings for this signal are all forms of the Enter key. +The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. @@ -122368,7 +124956,7 @@ The keybindings for this signal are all forms of the Enter key. Emitted when the user initiates a move to the next match + line="570">Emitted when the user initiates a move to the next match for the current search string. This is a [keybinding signal](class.SignalAction.html). @@ -122376,7 +124964,7 @@ This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement moving between matches. -The default bindings for this signal is Ctrl-g. +The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>g</kbd>. @@ -122384,7 +124972,7 @@ The default bindings for this signal is Ctrl-g. Emitted when the user initiates a move to the previous match + line="593">Emitted when the user initiates a move to the previous match for the current search string. This is a [keybinding signal](class.SignalAction.html). @@ -122392,7 +124980,8 @@ This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement moving between matches. -The default bindings for this signal is Ctrl-Shift-g. +The default bindings for this signal is +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>g</kbd>. @@ -122400,7 +124989,7 @@ The default bindings for this signal is Ctrl-Shift-g. Emitted with a delay. The length of the delay can be + line="553">Emitted with a delay. The length of the delay can be changed with the [property@Gtk.SearchEntry:search-delay] property. @@ -122410,7 +124999,7 @@ property. Emitted when the user initiated a search on the entry. + line="639">Emitted when the user initiated a search on the entry. @@ -122418,14 +125007,14 @@ property. Emitted when the user stops a search via keyboard input. + line="617">Emitted when the user stops a search via keyboard input. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement hiding the search entry in this case. -The default bindings for this signal is Escape. +The default bindings for this signal is <kbd>Escape</kbd>. @@ -122440,7 +125029,7 @@ The default bindings for this signal is Escape. glib:type-struct="SectionModelInterface"> `GtkSectionModel` is an interface that adds support for sections to list models. + line="26">An interface that adds support for sections to list models. A `GtkSectionModel` groups successive items into so-called sections. List widgets like `GtkListView` and `GtkGridView` then allow displaying section headers for @@ -122460,7 +125049,7 @@ that range are invalidated, too. Query the section that covers the given position. The number of + line="113">Query the section that covers the given position. The number of items in the section can be computed by `out_end - out_start`. If the position is larger than the number of items, a single @@ -122473,13 +125062,13 @@ range from n_items to G_MAXUINT will be returned. a `GtkSectionModel` + line="115">a `GtkSectionModel` the position of the item to query + line="116">the position of the item to query transfer-ownership="full"> the position of the first item in the section + line="117">the position of the first item in the section transfer-ownership="full"> the position of the first item not part of the section + line="118">the position of the first item not part of the section anymore. @@ -122508,7 +125097,7 @@ range from n_items to G_MAXUINT will be returned. version="4.12"> Query the section that covers the given position. The number of + line="113">Query the section that covers the given position. The number of items in the section can be computed by `out_end - out_start`. If the position is larger than the number of items, a single @@ -122521,13 +125110,13 @@ range from n_items to G_MAXUINT will be returned. a `GtkSectionModel` + line="115">a `GtkSectionModel` the position of the item to query + line="116">the position of the item to query transfer-ownership="full"> the position of the first item in the section + line="117">the position of the first item in the section transfer-ownership="full"> the position of the first item not part of the section + line="118">the position of the first item not part of the section anymore. + c:identifier="gtk_section_model_sections_changed" + version="4.12"> + This function emits the [signal@Gtk.SectionModel::sections-changed] +signal to notify about changes to sections. + +It must cover all positions that used to be a section start or that +are now a section start. It does not have to cover all positions for +which the section has changed. + +The [signal@Gio.ListModel::items-changed] implies the effect of the +[signal@Gtk.SectionModel::sections-changed] signal for all the items +it covers. + +It is recommended that when changes to the items cause section changes +in a larger range, that the larger range is included in the emission +of the [signal@Gio.ListModel::items-changed] instead of emitting +two signals. + a `GtkSectionModel` + the first changed item + the number of changed items @@ -122572,7 +125188,7 @@ range from n_items to G_MAXUINT will be returned. Emitted when the start-of-section state of some of the items in @model changes. + line="81">Emitted when the start-of-section state of some of the items in @model changes. Note that this signal does not specify the new section state of the items, they need to be queried manually. It is also not necessary for @@ -122589,13 +125205,13 @@ it covers. The first item that may have changed + line="84">The first item that may have changed number of items with changes + line="85">number of items with changes @@ -122615,6 +125231,11 @@ is implemented, the whole model will just be a single section. + Return the section that covers the given position. If + the position is outside the number of items, returns a single range from + n_items to G_MAXUINT @@ -122624,13 +125245,13 @@ is implemented, the whole model will just be a single section. a `GtkSectionModel` + line="115">a `GtkSectionModel` the position of the item to query + line="116">the position of the item to query transfer-ownership="full"> the position of the first item in the section + line="117">the position of the first item in the section transfer-ownership="full"> the position of the first item not part of the section + line="118">the position of the first item not part of the section anymore. @@ -122665,20 +125286,19 @@ is implemented, the whole model will just be a single section. glib:type-struct="SelectionFilterModelClass"> `GtkSelectionFilterModel` is a list model that presents the selection from -a `GtkSelectionModel`. + line="27">A list model that presents the selection from a `GtkSelectionModel`. Creates a new `GtkSelectionFilterModel` that will include the + line="276">Creates a new `GtkSelectionFilterModel` that will include the selected items from the underlying selection model. a new `GtkSelectionFilterModel` + line="283">a new `GtkSelectionFilterModel` @@ -122688,7 +125308,7 @@ selected items from the underlying selection model. allow-none="1"> the selection model to filter + line="278">the selection model to filter @@ -122696,22 +125316,21 @@ selected items from the underlying selection model. - Gets the model currently filtered or %NULL if none. + line="344">Gets the model currently filtered or %NULL if none. The model that gets filtered + line="350">The model that gets filtered a `GtkSelectionFilterModel` + line="346">a `GtkSelectionFilterModel` @@ -122720,10 +125339,9 @@ selected items from the underlying selection model. - Sets the model to be filtered. + line="293">Sets the model to be filtered. Note that GTK makes no effort to ensure that @model conforms to the item type of @self. It assumes that the caller knows what they @@ -122737,7 +125355,7 @@ types match. a `GtkSelectionFilterModel` + line="295">a `GtkSelectionFilterModel` @@ -122747,7 +125365,7 @@ types match. allow-none="1"> The model to be filtered + line="296">The model to be filtered @@ -122755,7 +125373,7 @@ types match. The type of items. See [method@Gio.ListModel.get_item_type]. + line="234">The type of items. See [method@Gio.ListModel.get_item_type]. transfer-ownership="none" setter="set_model" getter="get_model"> - - The model being filtered. + line="246">The model being filtered. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="256">The number of items. See [method@Gio.ListModel.get_n_items]. @@ -122796,7 +125410,7 @@ types match. c:type="GtkSelectionMode"> Used to control what selections users are allowed to make. + line="538">Used to control what selections users are allowed to make. glib:name="GTK_SELECTION_NONE"> No selection is possible. + line="540">No selection is possible. glib:name="GTK_SELECTION_SINGLE"> Zero or one element may be selected. + line="541">Zero or one element may be selected. glib:name="GTK_SELECTION_BROWSE"> Exactly one element is selected. + line="542">Exactly one element is selected. In some circumstances, such as initially or during a search operation, it’s possible for no element to be selected with %GTK_SELECTION_BROWSE. What is really enforced is that the user @@ -122836,7 +125450,7 @@ types match. glib:name="GTK_SELECTION_MULTIPLE"> Any number of elements may be selected. + line="548">Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements. @@ -122850,7 +125464,7 @@ types match. glib:type-struct="SelectionModelInterface"> `GtkSelectionModel` is an interface that add support for selection to list models. + line="27">An interface that adds support for selection to list models. This support is then used by widgets using list models to add the ability to select and unselect various items. @@ -123620,6 +126234,9 @@ support. + Return if the item at the given position is selected. @@ -123645,6 +126262,11 @@ support. + Return a bitset with all currently selected + items in the given range. By default, this function will call + `GtkSelectionModel::is_selected()` on all items in the given range. @@ -123678,6 +126300,10 @@ support. + Select the item in the given position. If the operation + is known to fail, return %FALSE. @@ -123710,6 +126336,10 @@ support. + Unselect the item in the given position. If the + operation is known to fail, return %FALSE. @@ -123736,6 +126366,10 @@ support. + Select all items in the given range. If the operation + is unsupported or known to fail for all items, return %FALSE. @@ -123774,6 +126408,11 @@ support. + Unselect all items in the given range. If the + operation is unsupported or known to fail for all items, return + %FALSE. @@ -123806,6 +126445,10 @@ support. + Select all items in the model. If the operation is + unsupported or known to fail for all items, return %FALSE. @@ -123826,6 +126469,10 @@ support. + Unselect all items in the model. If the operation is + unsupported or known to fail for all items, return %FALSE. @@ -123846,6 +126493,11 @@ support. + Set selection state of all items in mask to selected. + See gtk_selection_model_set_selection() for a detailed explanation + of this function. @@ -123885,7 +126537,7 @@ support. c:type="GtkSensitivityType"> Determines how GTK handles the sensitivity of various controls, + line="240">Determines how GTK handles the sensitivity of various controls, such as combo box buttons. glib:name="GTK_SENSITIVITY_AUTO"> The control is made insensitive if no + line="242">The control is made insensitive if no action can be triggered glib:name="GTK_SENSITIVITY_ON"> The control is always sensitive + line="244">The control is always sensitive glib:name="GTK_SENSITIVITY_OFF"> The control is always insensitive + line="245">The control is always insensitive glib:get-type="gtk_separator_get_type"> `GtkSeparator` is a horizontal or vertical separator widget. + line="34">Draws a horizontal or vertical line to separate other widgets. -![An example GtkSeparator](separator.png) +<picture> + <source srcset="separator-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkSeparator" src="separator.png"> +</picture> A `GtkSeparator` can be used to group the widgets within a window. It displays a line with a shadow to make it appear sunken into the @@ -123939,7 +126594,7 @@ gets one of the .horizontal or .vertical style classes. # Accessibility -`GtkSeparator` uses the %GTK_ACCESSIBLE_ROLE_SEPARATOR role. +`GtkSeparator` uses the [enum@Gtk.AccessibleRole.separator] role. @@ -123947,19 +126602,19 @@ gets one of the .horizontal or .vertical style classes. Creates a new `GtkSeparator` with the given orientation. + line="162">Creates a new `GtkSeparator` with the given orientation. a new `GtkSeparator`. + line="168">a new `GtkSeparator`. the separator’s orientation. + line="164">the separator’s orientation. @@ -123973,8 +126628,7 @@ gets one of the .horizontal or .vertical style classes. glib:get-type="gtk_settings_get_type"> `GtkSettings` provides a mechanism to share global settings between -applications. + line="64">Provides a mechanism to share global settings between applications. On the X window system, this sharing is realized by an [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec) @@ -123982,7 +126636,9 @@ manager that is usually part of the desktop environment, along with utilities that let the user change these settings. On Wayland, the settings are obtained either via a settings portal, -or by reading desktop settings from DConf. +or by reading desktop settings from [class@Gio.Settings]. + +On macOS, the settings are obtained from `NSUserDefaults`. In the absence of these sharing mechanisms, GTK reads default values for settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0` @@ -124003,7 +126659,7 @@ convenient to use [method@Gtk.Widget.get_settings]. Gets the `GtkSettings` object for the default display, creating + line="1164">Gets the `GtkSettings` object for the default display, creating it if necessary. See [func@Gtk.Settings.get_for_display]. @@ -124011,7 +126667,7 @@ See [func@Gtk.Settings.get_for_display]. a `GtkSettings` object. If there is + line="1172">a `GtkSettings` object. If there is no default display, then returns %NULL. @@ -124020,19 +126676,19 @@ See [func@Gtk.Settings.get_for_display]. c:identifier="gtk_settings_get_for_display"> Gets the `GtkSettings` object for @display, creating it if necessary. + line="1136">Gets the `GtkSettings` object for @display, creating it if necessary. a `GtkSettings` object + line="1142">a `GtkSettings` object a `GdkDisplay` + line="1138">a `GdkDisplay` @@ -124040,7 +126696,7 @@ See [func@Gtk.Settings.get_for_display]. Undoes the effect of calling g_object_set() to install an + line="1902">Undoes the effect of calling g_object_set() to install an application-specific value for a setting. After this call, the setting will again follow the session-wide @@ -124053,13 +126709,13 @@ value for this setting. a `GtkSettings` object + line="1904">a `GtkSettings` object the name of the setting to reset + line="1905">the name of the setting to reset @@ -124070,7 +126726,7 @@ value for this setting. default-value="FALSE"> Whether buttons in dialogs should use the alternative button order. + line="535">Whether buttons in dialogs should use the alternative button order. default-value="FALSE"> Controls the direction of the sort indicators in sorted list and tree + line="544">Controls the direction of the sort indicators in sorted list and tree views. By default an arrow pointing down means the column is sorted @@ -124092,7 +126748,7 @@ in ascending order. When set to %TRUE, this order will be inverted. default-value="FALSE"> Whether the application prefers to use a dark theme. + line="735">Whether the application prefers to use a dark theme. If a GTK theme includes a dark variant, it will be used instead of the configured theme. @@ -124114,7 +126770,7 @@ are white/light and the dark chrome creates too much contrast default-value="0.040000"> The aspect ratio of the text caret. + line="387">The aspect ratio of the text caret. Whether the cursor should blink. + line="342">Whether the cursor should blink. Also see the [property@Gtk.Settings:gtk-cursor-blink-timeout] setting, which allows more flexible control over cursor blinking. @@ -124135,7 +126791,7 @@ which allows more flexible control over cursor blinking. default-value="1200"> Length of the cursor blink cycle, in milliseconds. + line="354">Length of the cursor blink cycle, in milliseconds. default-value="10"> Time after which the cursor stops blinking, in seconds. + line="363">Time after which the cursor stops blinking, in seconds. The timer is reset after each user interaction. @@ -124158,7 +126814,7 @@ Setting this to zero has the same effect as setting default-value="NULL"> Name of the cursor theme to use. + line="513">Name of the cursor theme to use. Use %NULL to use the default theme. @@ -124169,7 +126825,7 @@ Use %NULL to use the default theme. default-value="0"> The size to use for cursors. + line="524">The size to use for cursors. 0 means to use the default size. @@ -124180,7 +126836,7 @@ Use %NULL to use the default theme. default-value="menu:minimize,maximize,close"> Determines which buttons should be put in the + line="820">Determines which buttons should be put in the titlebar of client-side decorated windows, and whether they should be placed on the left or right. @@ -124208,7 +126864,7 @@ Also note that the setting can be overridden with the default-value="FALSE"> Whether builtin GTK dialogs such as the file chooser, the + line="887">Whether builtin GTK dialogs such as the file chooser, the color chooser or the font chooser will use a header bar at the top to show action widgets, or an action area at the bottom. @@ -124222,7 +126878,7 @@ directly, or message dialogs. default-value="8"> The number of pixels the cursor can move before dragging. + line="420">The number of pixels the cursor can move before dragging. default-value="5"> The maximum distance allowed between two clicks for them to be considered + line="332">The maximum distance allowed between two clicks for them to be considered a double click, in pixels. @@ -124241,7 +126897,7 @@ a double click, in pixels. default-value="400"> The maximum time to allow between two clicks for them to be considered + line="322">The maximum time to allow between two clicks for them to be considered a double click, in milliseconds. @@ -124251,7 +126907,7 @@ a double click, in milliseconds. default-value="TRUE"> Whether menu items should have visible accelerators which can be + line="622">Whether menu items should have visible accelerators which can be activated. @@ -124261,7 +126917,7 @@ activated. default-value="TRUE"> Whether to enable toolkit-wide animations. + line="557">Whether to enable toolkit-wide animations. default-value="TRUE"> Whether to play any event sounds at all. + line="702">Whether to play any event sounds at all. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. @@ -124285,7 +126941,7 @@ module like the one that comes with libcanberra. default-value="TRUE"> Whether to play event sounds as feedback to user input. + line="687">Whether to play event sounds as feedback to user input. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. @@ -124300,7 +126956,7 @@ module like the one that comes with libcanberra. default-value="TRUE"> Whether a middle click on a mouse should paste the + line="901">Whether a middle click on a mouse should paste the 'PRIMARY' clipboard content at the cursor location. @@ -124310,7 +126966,7 @@ module like the one that comes with libcanberra. default-value="0"> How long to show the last input character in hidden + line="766">How long to show the last input character in hidden entries. This value is in milliseconds. 0 disables showing the @@ -124323,7 +126979,7 @@ last char. 600 is a good value for enabling it. default-value="TRUE"> Whether to select the contents of an entry when it is focused. + line="757">Whether to select the contents of an entry when it is focused. default-value="TRUE"> When %TRUE, keyboard navigation and other input-related errors + line="566">When %TRUE, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using gdk_surface_beep(), the @@ -124346,28 +127002,47 @@ ways, such as flashing the window or similar visual effects. default-value="Sans 10"> The default font to use. + line="429">The default font to use. GTK uses the family name and size from this string. + + How GTK font rendering is set up. + +When set to [enum@Gtk.FontRendering.MANUAL], GTK respects the low-level +font-related settings ([property@Gtk.Settings:gtk-hint-font-metrics], +[property@Gtk.Settings:gtk-xft-antialias], [property@Gtk.Settings:gtk-xft-hinting], +[property@Gtk.Settings:gtk-xft-hintstyle] and [property@Gtk.Settings:gtk-xft-rgba]) +as much as practical. + +When set to [enum@Gtk.FontRendering.AUTOMATIC], GTK will consider factors such +as screen resolution and scale in deciding how to render fonts. + + Timestamp of the current fontconfig configuration. + line="663">Timestamp of the current fontconfig configuration. + default-value="TRUE"> Whether hinting should be applied to font metrics. + line="499">Whether hinting should be applied to font metrics. Note that this also turns off subpixel positioning of glyphs, since it conflicts with metrics hinting. @@ -124379,7 +127054,7 @@ since it conflicts with metrics hinting. default-value="Adwaita"> Name of the icon theme to use. + line="408">Name of the icon theme to use. See [class@Gtk.IconTheme] for details about how GTK handles icon themes. @@ -124391,7 +127066,7 @@ GTK handles icon themes. default-value="NULL"> Which IM (input method) module should be used by default. + line="632">Which IM (input method) module should be used by default. This is the input method that will be used if the user has not explicitly chosen another input method from the IM context menu. @@ -124407,7 +127082,7 @@ See [class@Gtk.IMContext]. default-value="FALSE"> Whether GTK should make sure that text can be navigated with + line="934">Whether GTK should make sure that text can be navigated with a caret, even if it is not editable. This is useful when using a screen reader. @@ -124419,7 +127094,7 @@ This is useful when using a screen reader. default-value="TRUE"> Whether to select the contents of a selectable + line="780">Whether to select the contents of a selectable label when it is focused. @@ -124429,7 +127104,7 @@ label when it is focused. default-value="500"> The time for a button or touch press to be considered a “long press”. + line="923">The time for a button or touch press to be considered a “long press”. See [class@Gtk.GestureLongPress]. @@ -124440,7 +127115,7 @@ See [class@Gtk.GestureLongPress]. default-value="TRUE"> Whether scrolled windows may use overlaid scrolling indicators. + line="946">Whether scrolled windows may use overlaid scrolling indicators. If this is set to %FALSE, scrolled windows will have permanent scrollbars. @@ -124452,7 +127127,7 @@ scrollbars. default-value="TRUE"> If the value of this setting is %TRUE, clicking the primary button in a + line="717">If the value of this setting is %TRUE, clicking the primary button in a `GtkRange` trough will move the slider, and hence set the range’s value, to the point that you clicked. @@ -124470,7 +127145,7 @@ mouse button. default-value="cups,file"> A comma-separated list of print backends to use in the print + line="591">A comma-separated list of print backends to use in the print dialog. Available print backends depend on the GTK installation, @@ -124483,7 +127158,7 @@ and may include "file", "cups", "lpr" or "papi". default-value="evince --unlink-tempfile --preview --print-settings %s %f"> A command to run for displaying the print preview. + line="604">A command to run for displaying the print preview. The command should contain a `%f` placeholder, which will get replaced by the path to the pdf file. The command may also @@ -124501,7 +127176,7 @@ file and the print settings file when it is done. default-value="TRUE"> Whether GTK should keep track of items inside the recently used + line="911">Whether GTK should keep track of items inside the recently used resources list. If set to %FALSE, the list will always be empty. @@ -124513,7 +127188,7 @@ If set to %FALSE, the list will always be empty. default-value="30"> The maximum age, in days, of the items inside the recently used + line="648">The maximum age, in days, of the items inside the recently used resources list. Items older than this setting will be excised from the list. @@ -124527,7 +127202,7 @@ item will be removed. default-value="FALSE"> Set to %TRUE if the desktop environment is displaying + line="790">Set to %TRUE if the desktop environment is displaying the app menu, %FALSE if the app should display it itself. @@ -124537,7 +127212,7 @@ the app menu, %FALSE if the app should display it itself. default-value="TRUE"> Set to %TRUE if the desktop environment is displaying + line="810">Set to %TRUE if the desktop environment is displaying the desktop folder, %FALSE if not. @@ -124547,17 +127222,27 @@ the desktop folder, %FALSE if not. default-value="FALSE"> Set to %TRUE if the desktop environment is displaying + line="800">Set to %TRUE if the desktop environment is displaying the menubar, %FALSE if the app should display it itself. + + When %TRUE, widgets like switches include shapes to indicate their on/off state. + + The XDG sound theme to use for event sounds. + line="672">The XDG sound theme to use for event sounds. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. @@ -124572,7 +127257,7 @@ a loadable module like the one that comes with libcanberra. default-value="FALSE"> Whether two cursors should be displayed for mixed left-to-right and + line="377">Whether two cursors should be displayed for mixed left-to-right and right-to-left text. @@ -124582,7 +127267,7 @@ right-to-left text. default-value="Default"> Name of the theme to load. + line="396">Name of the theme to load. See [class@Gtk.CssProvider] for details about how GTK finds the CSS stylesheet for a theme. @@ -124594,7 +127279,7 @@ GTK finds the CSS stylesheet for a theme. default-value="toggle-maximize"> Determines the action to take when a double-click + line="848">Determines the action to take when a double-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower @@ -124607,7 +127292,7 @@ or none. default-value="none"> Determines the action to take when a middle-click + line="861">Determines the action to take when a middle-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower @@ -124620,7 +127305,7 @@ or none. default-value="menu"> Determines the action to take when a right-click + line="874">Determines the action to take when a right-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower @@ -124633,7 +127318,7 @@ or none. default-value="-1"> Whether to antialias fonts. + line="440">Whether to antialias fonts. The values are 0 for no, 1 for yes, or -1 for the system default. @@ -124644,7 +127329,7 @@ The values are 0 for no, 1 for yes, or -1 for the system default. default-value="-1"> The font resolution, in 1024 * dots/inch. + line="488">The font resolution, in 1024 * dots/inch. -1 to use the default value. @@ -124655,7 +127340,7 @@ The values are 0 for no, 1 for yes, or -1 for the system default. default-value="-1"> Whether to enable font hinting. + line="451">Whether to enable font hinting. The values are 0 for no, 1 for yes, or -1 for the system default. @@ -124666,7 +127351,7 @@ The values are 0 for no, 1 for yes, or -1 for the system default. default-value="NULL"> What degree of font hinting to use. + line="462">What degree of font hinting to use. The possible vaues are hintnone, hintslight, hintmedium, hintfull. @@ -124678,9 +127363,12 @@ hintmedium, hintfull. default-value="NULL"> The type of subpixel antialiasing to use. + line="474">The type of subpixel antialiasing to use. -The possible values are none, rgb, bgr, vrgb, vbgr. +The possible values are none, rgb, bgr, vrgb, vbgr. + +Note that GSK does not support subpixel antialiasing, and this +setting has no effect on font rendering in GTK. @@ -124693,7 +127381,7 @@ The possible values are none, rgb, bgr, vrgb, vbgr. glib:type-struct="ShortcutClass"> A `GtkShortcut` describes a keyboard shortcut. + line="28">Describes a keyboard shortcut. It contains a description of how to trigger the shortcut via a [class@Gtk.ShortcutTrigger] and a way to activate the shortcut @@ -124798,7 +127486,6 @@ for display purposes or by allowing shortcuts to be configured. - Gets the action that is activated by this shortcut. @@ -124821,7 +127508,6 @@ for display purposes or by allowing shortcuts to be configured. - Gets the arguments that are passed when activating the shortcut. @@ -124844,7 +127530,6 @@ for display purposes or by allowing shortcuts to be configured. - Gets the trigger used to trigger @self. @@ -124867,7 +127552,6 @@ for display purposes or by allowing shortcuts to be configured. - Sets the new action for @self to be @action. @@ -124897,7 +127581,6 @@ for display purposes or by allowing shortcuts to be configured. - Sets the arguments to pass when activating the shortcut. @@ -124926,7 +127609,6 @@ for display purposes or by allowing shortcuts to be configured. - Sets the new trigger for @self to be @trigger. @@ -124958,10 +127640,6 @@ for display purposes or by allowing shortcuts to be configured. transfer-ownership="none" setter="set_action" getter="get_action"> - - The action that gets activated by this shortcut. @@ -124972,10 +127650,6 @@ for display purposes or by allowing shortcuts to be configured. transfer-ownership="none" setter="set_arguments" getter="get_arguments"> - - Arguments passed to activation. @@ -124986,10 +127660,6 @@ for display purposes or by allowing shortcuts to be configured. transfer-ownership="none" setter="set_trigger" getter="get_trigger"> - - The trigger that triggers this shortcut. @@ -125006,8 +127676,7 @@ for display purposes or by allowing shortcuts to be configured. glib:type-struct="ShortcutActionClass"> `GtkShortcutAction` encodes an action that can be triggered by a -keyboard shortcut. + line="20">Encodes an action that can be triggered by a keyboard shortcut. `GtkShortcutActions` contain functions that allow easy presentation to end users as well as being printed for debugging. @@ -125038,7 +127707,7 @@ GTK provides various actions: c:identifier="gtk_shortcut_action_parse_string"> Tries to parse the given string into an action. + line="194">Tries to parse the given string into an action. On success, the parsed action is returned. When parsing failed, %NULL is returned. @@ -125054,14 +127723,14 @@ The accepted strings are: a new `GtkShortcutAction` + line="211">a new `GtkShortcutAction` the string to parse + line="196">the string to parse @@ -125069,7 +127738,7 @@ The accepted strings are: Activates the action on the @widget with the given @args. + line="137">Activates the action on the @widget with the given @args. Note that some actions ignore the passed in @flags, @widget or @args. @@ -125080,26 +127749,26 @@ or if the activation otherwise had no effect, %FALSE will be returned. %TRUE if this action was activated successfully + line="152">%TRUE if this action was activated successfully a `GtkShortcutAction` + line="139">a `GtkShortcutAction` flags to activate with + line="140">flags to activate with Target of the activation + line="141">Target of the activation allow-none="1"> arguments to pass + line="142">arguments to pass @@ -125116,7 +127785,7 @@ or if the activation otherwise had no effect, %FALSE will be returned. Prints the given action into a string for the developer. + line="115">Prints the given action into a string for the developer. This is meant for debugging and logging. @@ -125130,13 +127799,13 @@ not guaranteed to stay identical. a `GtkShortcutAction` + line="117">a `GtkShortcutAction` a `GString` to print into + line="118">a `GString` to print into @@ -125144,7 +127813,7 @@ not guaranteed to stay identical. Prints the given action into a human-readable string. + line="91">Prints the given action into a human-readable string. This is a small wrapper around [method@Gtk.ShortcutAction.print] to help when debugging. @@ -125152,14 +127821,14 @@ to help when debugging. a new string + line="100">a new string a `GtkShortcutAction` + line="93">a `GtkShortcutAction` @@ -125178,7 +127847,7 @@ to help when debugging. c:type="GtkShortcutActionFlags"> List of flags that can be passed to action activation. + line="46">Flags that can be passed to action activation. More flags may be added in the future. glib:type-struct="ShortcutControllerClass"> `GtkShortcutController` is an event controller that manages shortcuts. + line="21">Manages keyboard shortcuts and their activation. Most common shortcuts are using this controller implicitly, e.g. by adding a mnemonic underline to a [class@Gtk.Label], or by installing a key @@ -125256,12 +127925,12 @@ for triggers. Creates a new shortcut controller. + line="739">Creates a new shortcut controller. a newly created shortcut controller + line="744">a newly created shortcut controller @@ -125269,7 +127938,7 @@ for triggers. c:identifier="gtk_shortcut_controller_new_for_model"> Creates a new shortcut controller that takes its shortcuts from + line="753">Creates a new shortcut controller that takes its shortcuts from the given list model. A controller created by this function does not let you add or @@ -125279,14 +127948,14 @@ but you can change the contents of the model. a newly created shortcut controller + line="764">a newly created shortcut controller a `GListModel` containing shortcuts + line="755">a `GListModel` containing shortcuts @@ -125295,7 +127964,7 @@ but you can change the contents of the model. c:identifier="gtk_shortcut_controller_add_shortcut"> Adds @shortcut to the list of shortcuts handled by @self. + line="776">Adds @shortcut to the list of shortcuts handled by @self. If this controller uses an external shortcut list, this function does nothing. @@ -125307,36 +127976,35 @@ function does nothing. the controller + line="778">the controller a `GtkShortcut` + line="779">a `GtkShortcut` - + c:identifier="gtk_shortcut_controller_get_mnemonics_modifiers" + glib:get-property="mnemonic-modifiers"> Gets the mnemonics modifiers for when this controller activates its shortcuts. + line="949">Gets the mnemonics modifiers for when this controller activates its shortcuts. the controller's mnemonics modifiers + line="955">the controller's mnemonics modifiers a `GtkShortcutController` + line="951">a `GtkShortcutController` @@ -125344,24 +128012,23 @@ function does nothing. - Gets the scope for when this controller activates its shortcuts. + line="898">Gets the scope for when this controller activates its shortcuts. See [method@Gtk.ShortcutController.set_scope] for details. the controller's scope + line="906">the controller's scope a `GtkShortcutController` + line="900">a `GtkShortcutController` @@ -125370,7 +128037,7 @@ See [method@Gtk.ShortcutController.set_scope] for details. c:identifier="gtk_shortcut_controller_remove_shortcut"> Removes @shortcut from the list of shortcuts handled by @self. + line="813">Removes @shortcut from the list of shortcuts handled by @self. If @shortcut had not been added to @controller or this controller uses an external shortcut list, this function does nothing. @@ -125382,24 +128049,23 @@ uses an external shortcut list, this function does nothing. the controller + line="815">the controller a `GtkShortcut` + line="816">a `GtkShortcut` - + c:identifier="gtk_shortcut_controller_set_mnemonics_modifiers" + glib:set-property="mnemonic-modifiers"> Sets the controller to use the given modifier for mnemonics. + line="916">Sets the controller to use the given modifier for mnemonics. The mnemonics modifiers determines which modifiers need to be pressed to allow activation of shortcuts with mnemonics triggers. @@ -125420,13 +128086,13 @@ have their own modifiers for activating mnemonics. a `GtkShortcutController` + line="918">a `GtkShortcutController` the new mnemonics_modifiers to use + line="919">the new mnemonics_modifiers to use @@ -125434,10 +128100,9 @@ have their own modifiers for activating mnemonics. - Sets the controller to have the given @scope. + line="859">Sets the controller to have the given @scope. The scope allows shortcuts to be activated outside of the normal event propagation. In particular, it allows installing global @@ -125454,13 +128119,13 @@ when the widget has focus. a `GtkShortcutController` + line="861">a `GtkShortcutController` the new scope to use + line="862">the new scope to use @@ -125468,20 +128133,18 @@ when the widget has focus. The type of items. See [method@Gio.ListModel.get_item_type]. + line="584">The type of items. See [method@Gio.ListModel.get_item_type]. - - The modifiers that need to be pressed to allow mnemonics activation. + line="596">The modifiers that need to be pressed to allow mnemonics activation. transfer-ownership="none"> A list model to take shortcuts from. + line="607">A list model to take shortcuts from. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="617">The number of items. See [method@Gio.ListModel.get_n_items]. setter="set_scope" getter="get_scope" default-value="GTK_SHORTCUT_SCOPE_LOCAL"> - - What scope the shortcuts will be handled in. + line="629">What scope the shortcuts will be handled in. @@ -125529,12 +128188,12 @@ when the widget has focus. Prototype for shortcuts based on user callbacks. + line="32">Type for shortcuts based on user callbacks. %TRUE if the action was successful. + line="40">true if the action was successful @@ -125568,169 +128227,187 @@ when the widget has focus. `GtkShortcutLabel` displays a single keyboard shortcut or gesture. The main use case for `GtkShortcutLabel` is inside a [class@Gtk.ShortcutsWindow]. - + This widget will be removed in GTK 5 + - + Creates a new `GtkShortcutLabel` with @accelerator set. - + filename="gtk/deprecated/gtkshortcutlabel.c" + line="543">Creates a new `GtkShortcutLabel` with @accelerator set. + This widget will be removed in GTK 5 + a newly-allocated `GtkShortcutLabel` + filename="gtk/deprecated/gtkshortcutlabel.c" + line="549">a newly-allocated `GtkShortcutLabel` the initial accelerator + filename="gtk/deprecated/gtkshortcutlabel.c" + line="545">the initial accelerator - + glib:get-property="accelerator" + deprecated="1" + deprecated-version="4.18"> Retrieves the current accelerator of @self. - + filename="gtk/deprecated/gtkshortcutlabel.c" + line="561">Retrieves the current accelerator of @self. + This widget will be removed in GTK 5 + the current accelerator. + filename="gtk/deprecated/gtkshortcutlabel.c" + line="567">the current accelerator. a `GtkShortcutLabel` + filename="gtk/deprecated/gtkshortcutlabel.c" + line="563">a `GtkShortcutLabel` - + glib:get-property="disabled-text" + deprecated="1" + deprecated-version="4.18"> Retrieves the text that is displayed when no accelerator is set. - + filename="gtk/deprecated/gtkshortcutlabel.c" + line="603">Retrieves the text that is displayed when no accelerator is set. + This widget will be removed in GTK 5 + the current text displayed when no + filename="gtk/deprecated/gtkshortcutlabel.c" + line="609">the current text displayed when no accelerator is set. a `GtkShortcutLabel` + filename="gtk/deprecated/gtkshortcutlabel.c" + line="605">a `GtkShortcutLabel` - + glib:set-property="accelerator" + deprecated="1" + deprecated-version="4.18"> Sets the accelerator to be displayed by @self. - + filename="gtk/deprecated/gtkshortcutlabel.c" + line="579">Sets the accelerator to be displayed by @self. + This widget will be removed in GTK 5 + a `GtkShortcutLabel` + filename="gtk/deprecated/gtkshortcutlabel.c" + line="581">a `GtkShortcutLabel` the new accelerator + filename="gtk/deprecated/gtkshortcutlabel.c" + line="582">the new accelerator - + glib:set-property="disabled-text" + deprecated="1" + deprecated-version="4.18"> Sets the text to be displayed by @self when no accelerator is set. - + filename="gtk/deprecated/gtkshortcutlabel.c" + line="622">Sets the text to be displayed by @self when no accelerator is set. + This widget will be removed in GTK 5 + a `GtkShortcutLabel` + filename="gtk/deprecated/gtkshortcutlabel.c" + line="624">a `GtkShortcutLabel` the text to be displayed when no accelerator is set + filename="gtk/deprecated/gtkshortcutlabel.c" + line="625">the text to be displayed when no accelerator is set - - The accelerator that @self displays. + filename="gtk/deprecated/gtkshortcutlabel.c" + line="502">The accelerator that @self displays. See [property@Gtk.ShortcutsShortcut:accelerator] for the accepted syntax. + This widget will be removed in GTK 5 - - The text that is displayed when no accelerator is set. + filename="gtk/deprecated/gtkshortcutlabel.c" + line="517">The text that is displayed when no accelerator is set. + This widget will be removed in GTK 5 @@ -125739,7 +128416,7 @@ for the accepted syntax. disguised="1" opaque="1" glib:is-gtype-struct-for="ShortcutLabel"> - + glib:type-struct="ShortcutManagerInterface"> The `GtkShortcutManager` interface is used to implement -shortcut scopes. + line="26">An interface that is used to implement shortcut scopes. This is important for [iface@Gtk.Native] widgets that have their own surface, since the event controllers that are used to implement @@ -125760,9 +128436,12 @@ Examples for widgets implementing `GtkShortcutManager` are [class@Gtk.Window] and [class@Gtk.Popover]. Every widget that implements `GtkShortcutManager` will be used as a -%GTK_SHORTCUT_SCOPE_MANAGED. +`GTK_SHORTCUT_SCOPE_MANAGED`. + Add a `GtkShortcutController` to be managed. @@ -125777,6 +128456,10 @@ Every widget that implements `GtkShortcutManager` will be used as a + Remove a `GtkShortcutController` that had previously + been added @@ -125806,6 +128489,9 @@ will work fine. + Add a `GtkShortcutController` to be managed. @@ -125822,6 +128508,10 @@ will work fine. + Remove a `GtkShortcutController` that had previously + been added @@ -125844,7 +128534,7 @@ will work fine. c:type="GtkShortcutScope"> Describes where [class@Shortcut]s added to a + line="1092">Describes where [class@Shortcut]s added to a [class@ShortcutController] get handled. glib:name="GTK_SHORTCUT_SCOPE_LOCAL"> Shortcuts are handled inside + line="1094">Shortcuts are handled inside the widget the controller belongs to. glib:name="GTK_SHORTCUT_SCOPE_MANAGED"> Shortcuts are handled by + line="1096">Shortcuts are handled by the first ancestor that is a [iface@ShortcutManager] glib:name="GTK_SHORTCUT_SCOPE_GLOBAL"> Shortcuts are handled by + line="1098">Shortcuts are handled by the root widget. @@ -125887,7 +128577,7 @@ will work fine. glib:type-struct="ShortcutTriggerClass"> `GtkShortcutTrigger` tracks how a `GtkShortcut` should be activated. + line="22">Tracks how a `GtkShortcut` can be activated. To find out if a `GtkShortcutTrigger` triggers, you can call [method@Gtk.ShortcutTrigger.trigger] on a `GdkEvent`. @@ -126202,7 +128892,7 @@ to help when debugging. glib:get-type="gtk_shortcut_type_get_type" c:type="GtkShortcutType"> GtkShortcutType specifies the kind of shortcut that is being described. More values may be added to this enumeration over time. @@ -126212,7 +128902,7 @@ More values may be added to this enumeration over time. glib:nick="accelerator" glib:name="GTK_SHORTCUT_ACCELERATOR"> The shortcut is a keyboard accelerator. The GtkShortcutsShortcut:accelerator property will be used. @@ -126222,7 +128912,7 @@ More values may be added to this enumeration over time. glib:nick="gesture-pinch" glib:name="GTK_SHORTCUT_GESTURE_PINCH"> The shortcut is a pinch gesture. GTK provides an icon and subtitle. glib:nick="gesture-stretch" glib:name="GTK_SHORTCUT_GESTURE_STRETCH"> The shortcut is a stretch gesture. GTK provides an icon and subtitle. glib:nick="gesture-rotate-clockwise" glib:name="GTK_SHORTCUT_GESTURE_ROTATE_CLOCKWISE"> The shortcut is a clockwise rotation gesture. GTK provides an icon and subtitle. glib:nick="gesture-rotate-counterclockwise" glib:name="GTK_SHORTCUT_GESTURE_ROTATE_COUNTERCLOCKWISE"> The shortcut is a counterclockwise rotation gesture. GTK provides an icon and subtitle. glib:nick="gesture-two-finger-swipe-left" glib:name="GTK_SHORTCUT_GESTURE_TWO_FINGER_SWIPE_LEFT"> The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. glib:nick="gesture-two-finger-swipe-right" glib:name="GTK_SHORTCUT_GESTURE_TWO_FINGER_SWIPE_RIGHT"> The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. glib:nick="gesture" glib:name="GTK_SHORTCUT_GESTURE"> The shortcut is a gesture. The GtkShortcutsShortcut:icon property will be used. @@ -126286,7 +128976,7 @@ More values may be added to this enumeration over time. glib:nick="gesture-swipe-left" glib:name="GTK_SHORTCUT_GESTURE_SWIPE_LEFT"> The shortcut is a swipe gesture. GTK provides an icon and subtitle. glib:nick="gesture-swipe-right" glib:name="GTK_SHORTCUT_GESTURE_SWIPE_RIGHT"> The shortcut is a swipe gesture. GTK provides an icon and subtitle. A `GtkShortcutsGroup` represents a group of related keyboard shortcuts + filename="gtk/deprecated/gtkshortcutsgroup.c" + line="34">A `GtkShortcutsGroup` represents a group of related keyboard shortcuts or gestures. The group has a title. It may optionally be associated with a view of the application, which can be used to show only relevant shortcuts depending on the application context. -This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. - +This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. + +The recommended way to construct a `GtkShortcutsGroup` is with +[class@Gtk.Builder], by using the `<child>` tag to populate a +`GtkShortcutsGroup` with one or more [class@Gtk.ShortcutsShortcut] +instances. + +If you need to add a shortcut programmatically, use +[method@Gtk.ShortcutsGroup.add_shortcut]. + This widget will be removed in GTK 5 + + + Adds a shortcut to the shortcuts group. + +This is the programmatic equivalent to using [class@Gtk.Builder] and a +`<child>` tag to add the child. Adding children with other API is not +appropriate as `GtkShortcutsGroup` manages its children internally. + This widget will be removed in GTK 5 + + + + + + + a `GtkShortcutsGroup` + + + + the `GtkShortcutsShortcut` to add + + + + The size group for the accelerator portion of shortcuts in this group. + filename="gtk/deprecated/gtkshortcutsgroup.c" + line="313">The size group for the accelerator portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications. + This widget will be removed in GTK 5 - + A rough measure for the number of lines in this group. + filename="gtk/deprecated/gtkshortcutsgroup.c" + line="341">A rough measure for the number of lines in this group. This is used internally by GTK, and is not useful for applications. + This widget will be removed in GTK 5 - + The title for this group of shortcuts. + filename="gtk/deprecated/gtkshortcutsgroup.c" + line="284">The title for this group of shortcuts. + This widget will be removed in GTK 5 The size group for the textual portion of shortcuts in this group. + filename="gtk/deprecated/gtkshortcutsgroup.c" + line="327">The size group for the textual portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications. + This widget will be removed in GTK 5 An optional view that the shortcuts in this group are relevant for. + filename="gtk/deprecated/gtkshortcutsgroup.c" + line="296">An optional view that the shortcuts in this group are relevant for. The group will be hidden if the [property@Gtk.ShortcutsWindow:view-name] property does not match the view of this group. Set this to %NULL to make the group always visible. + This widget will be removed in GTK 5 @@ -126377,18 +129131,21 @@ Set this to %NULL to make the group always visible. disguised="1" opaque="1" glib:is-gtype-struct-for="ShortcutsGroup"> - + A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures + filename="gtk/deprecated/gtkshortcutssection.c" + line="42">A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures for a major application mode. If your application needs multiple sections, you should give each @@ -126400,72 +129157,156 @@ The [property@Gtk.ShortcutsSection:max-height] property can be used to influence how the groups in the section are distributed over pages and columns. -This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. - +This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. + +The recommended way to construct a `GtkShortcutsSection` is with +[class@Gtk.Builder], by using the `<child>` tag to populate a +`GtkShortcutsSection` with one or more [class@Gtk.ShortcutsGroup] +instances, which in turn contain one or more [class@Gtk.ShortcutsShortcut] +objects. + +If you need to add a group programmatically, use +[method@Gtk.ShortcutsSection.add_group]. + +# Shortcuts and Gestures + +Pan gestures allow to navigate between sections. + +The following signals have default keybindings: + +- [signal@Gtk.ShortcutsSection::change-current-page] + This widget will be removed in GTK 5 + + + Adds a group to the shortcuts section. + +This is the programmatic equivalent to using [class@Gtk.Builder] and a +`<child>` tag to add the child. + +Adding children with the `GtkBox` API is not appropriate, as +`GtkShortcutsSection` manages its children internally. + This widget will be removed in GTK 5 + + + + + + + a `GtkShortcutsSection` + + + + the `GtkShortcutsGroup` to add + + + + The maximum number of lines to allow per column. + filename="gtk/deprecated/gtkshortcutssection.c" + line="355">The maximum number of lines to allow per column. This property can be used to influence how the groups in this section are distributed across pages and columns. The default value of 15 should work in most cases. + This widget will be removed in GTK 5 A unique name to identify this section among the sections + filename="gtk/deprecated/gtkshortcutssection.c" + line="305">A unique name to identify this section among the sections added to the `GtkShortcutsWindow`. Setting the [property@Gtk.ShortcutsWindow:section-name] property to this string will make this section shown in the `GtkShortcutsWindow`. + This widget will be removed in GTK 5 The string to show in the section selector of the `GtkShortcutsWindow` + filename="gtk/deprecated/gtkshortcutssection.c" + line="339">The string to show in the section selector of the `GtkShortcutsWindow` for this section. If there is only one section, you don't need to set a title, since the section selector will not be shown in this case. + This widget will be removed in GTK 5 A view name to filter the groups in this section by. + filename="gtk/deprecated/gtkshortcutssection.c" + line="321">A view name to filter the groups in this section by. See [property@Gtk.ShortcutsGroup:view]. Applications are expected to use the [property@Gtk.ShortcutsWindow:view-name] property for this purpose. + This widget will be removed in GTK 5 - + + Emitted when we change the current page. + +The default bindings for this signal are +<kbd>Ctrl</kbd>+<kbd>PgUp</kbd>, <kbd>PgUp</kbd>, +<kbd>Ctrl</kbd>+<kbd>PgDn</kbd>, <kbd>PgDn</kbd>. + This widget will be removed in GTK 5 + whether the page was changed - + + the offset @@ -126476,43 +129317,53 @@ for this purpose. disguised="1" opaque="1" glib:is-gtype-struct-for="ShortcutsSection"> - + A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="36">A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture with a short text. This widget is only meant to be used with `GtkShortcutsWindow`. - + This widget will be removed in GTK 5 + The size group for the accelerator portion of this shortcut. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="659">The size group for the accelerator portion of this shortcut. This is used internally by GTK, and must not be modified by applications. + This widget will be removed in GTK 5 The accelerator(s) represented by this object. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="549">The accelerator(s) represented by this object. This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type] is set to %GTK_SHORTCUT_ACCELERATOR. @@ -126539,100 +129390,134 @@ sequentially (e.g use "t+t" for 'press the t key twice'). Note that `<`, `>` and `&` need to be escaped as `&lt;`, `&gt`; and `&amp`; when used in .ui files. + This widget will be removed in GTK 5 A detailed action name. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="716">A detailed action name. If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR, then GTK will use the accelerators that are associated with the action via [method@Gtk.Application.set_accels_for_action], and setting [property@Gtk.ShortcutsShortcut:accelerator] is not necessary. + This widget will be removed in GTK 5 The text direction for which this shortcut is active. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="687">The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to %GTK_TEXT_DIR_NONE. + This widget will be removed in GTK 5 - + An icon to represent the shortcut or gesture. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="587">An icon to represent the shortcut or gesture. This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type] is set to %GTK_SHORTCUT_GESTURE. For the other predefined gesture types, GTK provides an icon on its own. + This widget will be removed in GTK 5 %TRUE if an icon has been set. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="604">%TRUE if an icon has been set. + This widget will be removed in GTK 5 The type of shortcut that is represented. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="703">The type of shortcut that is represented. + This widget will be removed in GTK 5 - + The subtitle for the shortcut or gesture. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="631">The subtitle for the shortcut or gesture. This is typically used for gestures and should be a short, one-line text that describes the gesture itself. For the predefined gesture types, GTK provides a subtitle on its own. + This widget will be removed in GTK 5 %TRUE if a subtitle has been set. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="647">%TRUE if a subtitle has been set. + This widget will be removed in GTK 5 - + The textual description for the shortcut or gesture represented by + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="616">The textual description for the shortcut or gesture represented by this object. This should be a short string that can fit in a single line. + This widget will be removed in GTK 5 The size group for the textual portion of this shortcut. + filename="gtk/deprecated/gtkshortcutsshortcut.c" + line="673">The size group for the textual portion of this shortcut. This is used internally by GTK, and must not be modified by applications. + This widget will be removed in GTK 5 @@ -126641,17 +129526,20 @@ This is used internally by GTK, and must not be modified by applications. disguised="1" opaque="1" glib:is-gtype-struct-for="ShortcutsShortcut"> - + A `GtkShortcutsWindow` shows information about the keyboard shortcuts + filename="gtk/deprecated/gtkshortcutswindow.c" + line="48">A `GtkShortcutsWindow` shows information about the keyboard shortcuts and gestures of an application. The shortcuts can be grouped, and you can have multiple sections in this @@ -126661,13 +129549,21 @@ Additionally, the shortcuts can be filtered by the current view, to avoid showing information that is not relevant in the current application context. The recommended way to construct a `GtkShortcutsWindow` is with -[class@Gtk.Builder], by populating a `GtkShortcutsWindow` with one or -more `GtkShortcutsSection` objects, which contain `GtkShortcutsGroups` -that in turn contain objects of class `GtkShortcutsShortcut`. +[class@Gtk.Builder], by using the `<child>` tag to populate a +`GtkShortcutsWindow` with one or more [class@Gtk.ShortcutsSection] objects, +which contain one or more [class@Gtk.ShortcutsGroup] instances, which, in turn, +contain [class@Gtk.ShortcutsShortcut] instances. + +If you need to add a section programmatically, use [method@Gtk.ShortcutsWindow.add_section] +instead of [method@Gtk.Window.set_child], as the shortcuts window manages +its children directly. # A simple example: -![](gedit-shortcuts.png) +<picture> + <source srcset="gedit-shortcuts-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="A simple example" src="gedit-shortcuts.png"> +</picture> This example has as single section. As you can see, the shortcut groups are arranged in columns, and spread across several pages if there are too @@ -126677,79 +129573,144 @@ The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME # An example with multiple views: -![](clocks-shortcuts.png) +<picture> + <source srcset="clocks-shortcuts-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example with multiple views" src="clocks-shortcuts.png"> +</picture> This example shows a `GtkShortcutsWindow` that has been configured to show only -the shortcuts relevant to the "stopwatch" view. +the shortcuts relevant to the “Stopwatch” view. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-clocks.ui). # An example with multiple sections: -![](builder-shortcuts.png) +<picture> + <source srcset="builder-shortcuts-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example with multiple sections" src="builder-shortcuts.png"> +</picture> -This example shows a `GtkShortcutsWindow` with two sections, "Editor Shortcuts" -and "Terminal Shortcuts". +This example shows a `GtkShortcutsWindow` with two sections, “Editor Shortcuts” +and “Terminal Shortcuts”. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-builder.ui). -## CSS nodes +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.ShortcutsWindow::close] +- [signal@Gtk.ShortcutsWindow::search] + +# CSS nodes `GtkShortcutsWindow` has a single CSS node with the name `window` and style class `.shortcuts`. + This widget will be removed in GTK 5 + + Adds a section to the shortcuts window. + +This is the programmatic equivalent to using [class@Gtk.Builder] and a +`<child>` tag to add the child. + +Using [method@Gtk.Window.set_child] is not appropriate as the shortcuts +window manages its children internally. + This widget will be removed in GTK 5 + + + + + + + a `GtkShortcutsWindow` + + + + the `GtkShortcutsSection` to add + + + + The name of the section to show. + filename="gtk/deprecated/gtkshortcutswindow.c" + line="789">The name of the section to show. This should be the section-name of one of the `GtkShortcutsSection` objects that are in this shortcuts window. + This widget will be removed in GTK 5 The view name by which to filter the contents. + filename="gtk/deprecated/gtkshortcutswindow.c" + line="804">The view name by which to filter the contents. This should correspond to the [property@Gtk.ShortcutsGroup:view] property of some of the [class@Gtk.ShortcutsGroup] objects that are inside this shortcuts window. Set this to %NULL to show all groups. + This widget will be removed in GTK 5 - + Emitted when the user uses a keybinding to close the window. + filename="gtk/deprecated/gtkshortcutswindow.c" + line="824">Emitted when the user uses a keybinding to close the window. This is a [keybinding signal](class.SignalAction.html). -The default binding for this signal is the Escape key. +The default binding for this signal is the <kbd>Escape</kbd> key. + This widget will be removed in GTK 5 - + Emitted when the user uses a keybinding to start a search. + filename="gtk/deprecated/gtkshortcutswindow.c" + line="843">Emitted when the user uses a keybinding to start a search. This is a [keybinding signal](class.SignalAction.html). -The default binding for this signal is Control-F. +The default binding for this signal is <kbd>Control</kbd>+<kbd>F</kbd>. + This widget will be removed in GTK 5 @@ -126764,30 +129725,30 @@ The default binding for this signal is Control-F. glib:type-struct="SignalActionClass"> A `GtkShortcut`Action that emits a signal. + line="137">Emits a signal on a widget. Signals that are used in this way are referred to as keybinding signals, -and they are expected to be defined with the %G_SIGNAL_ACTION flag. - +and they are expected to be defined with the `G_SIGNAL_ACTION` flag. + Creates an action that when activated, emits the given action signal + line="961">Creates an action that when activated, emits the given action signal on the provided widget. It will also unpack the args into arguments passed to the signal. - + a new `GtkShortcutAction` + line="970">a new `GtkShortcutAction` name of the signal to emit + line="963">name of the signal to emit @@ -126795,22 +129756,21 @@ It will also unpack the args into arguments passed to the signal. - Returns the name of the signal that will be emitted. - + line="992">Returns the name of the signal that will be emitted. + the name of the signal to emit + line="998">the name of the signal to emit a signal action + line="994">a signal action @@ -126821,11 +129781,9 @@ It will also unpack the args into arguments passed to the signal. transfer-ownership="none" getter="get_signal_name" default-value="NULL"> - The name of the signal to emit. + line="941">The name of the signal to emit. @@ -126834,7 +129792,7 @@ It will also unpack the args into arguments passed to the signal. disguised="1" opaque="1" glib:is-gtype-struct-for="SignalAction"> - + glib:type-struct="SignalListItemFactoryClass"> `GtkSignalListItemFactory` is a `GtkListItemFactory` that emits signals -to manage listitems. + line="28">A `GtkListItemFactory` that emits signals to manage listitems. Signals are emitted for every listitem in the same order: @@ -126873,9 +129830,9 @@ Signals are emitted for every listitem in the same order: make sure to properly clean up the listitem in step 3 so that no information from the previous use leaks into the next use. -5. [signal@Gtk.SignalListItemFactory::teardown] is emitted to allow undoing -the effects of [signal@Gtk.SignalListItemFactory::setup]. After this signal -was emitted on a listitem, the listitem will be destroyed and not be used again. + 5. [signal@Gtk.SignalListItemFactory::teardown] is emitted to allow undoing + the effects of [signal@Gtk.SignalListItemFactory::setup]. After this signal + was emitted on a listitem, the listitem will be destroyed and not be used again. Note that during the signal emissions, changing properties on the listitems passed will not trigger notify signals as the listitem's @@ -126889,21 +129846,21 @@ For tracking changes in other properties in the listitem, the Creates a new `GtkSignalListItemFactory`. + line="269">Creates a new `GtkSignalListItemFactory`. You need to connect signal handlers before you use it. a new `GtkSignalListItemFactory` + line="276">a new `GtkSignalListItemFactory` Emitted when an object has been bound, for example when a + line="184">Emitted when an object has been bound, for example when a new [property@Gtk.ListItem:item] has been set on a listitem and should be bound for use. @@ -126920,7 +129877,7 @@ in this signal. The `GObject` to bind + line="187">The `GObject` to bind @@ -126928,7 +129885,7 @@ in this signal. Emitted when a new listitem has been created and needs to be setup for use. + line="159">Emitted when a new listitem has been created and needs to be setup for use. It is the first signal emitted for every listitem. @@ -126941,7 +129898,7 @@ of this signal and can be used to undo everything done in this signal. The `GObject` to set up + line="162">The `GObject` to set up @@ -126949,7 +129906,7 @@ of this signal and can be used to undo everything done in this signal. Emitted when an object is about to be destroyed. + line="238">Emitted when an object is about to be destroyed. It is the last signal ever emitted for this @object. @@ -126962,7 +129919,7 @@ signal and should be used to undo everything done in that signal. The `GObject` to tear down + line="241">The `GObject` to tear down @@ -126970,7 +129927,7 @@ signal and should be used to undo everything done in that signal. Emitted when an object has been unbound from its item, for example when + line="213">Emitted when an object has been unbound from its item, for example when a listitem was removed from use in a list widget and its [property@Gtk.ListItem:item] is about to be unset. @@ -126983,7 +129940,7 @@ signal and should be used to undo everything done in that signal. The `GObject` to unbind + line="216">The `GObject` to unbind @@ -127005,8 +129962,7 @@ signal and should be used to undo everything done in that signal. glib:type-struct="SingleSelectionClass"> `GtkSingleSelection` is a `GtkSelectionModel` that allows selecting a single -item. + line="28">A selection model that allows selecting a single item. Note that the selection is *persistent* -- if the selected item is removed and re-added in the same [signal@Gio.ListModel::items-changed] emission, it @@ -127019,12 +129975,12 @@ underlying sort model will preserve the selection. Creates a new selection to handle @model. + line="520">Creates a new selection to handle @model. a new `GtkSingleSelection` + line="526">a new `GtkSingleSelection` @@ -127034,7 +129990,7 @@ underlying sort model will preserve the selection. allow-none="1"> the `GListModel` to manage + line="522">the `GListModel` to manage @@ -127042,23 +129998,22 @@ underlying sort model will preserve the selection. - Checks if autoselect has been enabled or disabled via + line="718">Checks if autoselect has been enabled or disabled via gtk_single_selection_set_autoselect(). %TRUE if autoselect is enabled + line="725">%TRUE if autoselect is enabled a `GtkSingleSelection` + line="720">a `GtkSingleSelection` @@ -127066,23 +130021,22 @@ gtk_single_selection_set_autoselect(). - If %TRUE, gtk_selection_model_unselect_item() is supported and allows + line="767">If %TRUE, gtk_selection_model_unselect_item() is supported and allows unselecting the selected item. %TRUE to support unselecting + line="774">%TRUE to support unselecting a `GtkSingleSelection` + line="769">a `GtkSingleSelection` @@ -127090,22 +130044,21 @@ unselecting the selected item. - Gets the model that @self is wrapping. + line="545">Gets the model that @self is wrapping. The model being wrapped + line="551">The model being wrapped a `GtkSingleSelection` + line="547">a `GtkSingleSelection` @@ -127113,24 +130066,23 @@ unselecting the selected item. - Gets the position of the selected item. + line="623">Gets the position of the selected item. If no item is selected, %GTK_INVALID_LIST_POSITION is returned. The position of the selected item + line="631">The position of the selected item a `GtkSingleSelection` + line="625">a `GtkSingleSelection` @@ -127138,24 +130090,23 @@ If no item is selected, %GTK_INVALID_LIST_POSITION is returned. - Gets the selected item. + line="700">Gets the selected item. If no item is selected, %NULL is returned. The selected item + line="708">The selected item a `GtkSingleSelection` + line="702">a `GtkSingleSelection` @@ -127163,10 +130114,9 @@ If no item is selected, %NULL is returned. - Enables or disables autoselect. + line="735">Enables or disables autoselect. If @autoselect is %TRUE, @self will enforce that an item is always selected. It will select a new item when the currently selected @@ -127179,13 +130129,13 @@ item is deleted and it will disallow unselecting the current item. a `GtkSingleSelection` + line="737">a `GtkSingleSelection` %TRUE to always select an item + line="738">%TRUE to always select an item @@ -127193,15 +130143,14 @@ item is deleted and it will disallow unselecting the current item. - If %TRUE, unselecting the current item via + line="784">If %TRUE, unselecting the current item via gtk_selection_model_unselect_item() is supported. Note that setting [property@Gtk.SingleSelection:autoselect] will cause unselecting to not work, so it practically makes no sense -to set both at the same time the same time. +to set both at the same time. @@ -127210,13 +130159,13 @@ to set both at the same time the same time. a `GtkSingleSelection` + line="786">a `GtkSingleSelection` %TRUE to allow unselecting + line="787">%TRUE to allow unselecting @@ -127224,10 +130173,9 @@ to set both at the same time the same time. - Sets the model that @self should wrap. + line="561">Sets the model that @self should wrap. If @model is %NULL, @self will be empty. @@ -127238,7 +130186,7 @@ If @model is %NULL, @self will be empty. a `GtkSingleSelection` + line="563">a `GtkSingleSelection` allow-none="1"> A `GListModel` to wrap + line="564">A `GListModel` to wrap @@ -127255,17 +130203,17 @@ If @model is %NULL, @self will be empty. - Selects the item at the given position. + line="641">Selects the item at the given position. If the list does not have an item at @position or %GTK_INVALID_LIST_POSITION is given, the behavior depends on the value of the [property@Gtk.SingleSelection:autoselect] property: If it is set, no change will occur and the old item will stay selected. If it is unset, the selection will be unset and no item -will be selected. +will be selected. This also applies if [property@Gtk.SingleSelection:can-unselect] +is set to %FALSE. @@ -127274,13 +130222,13 @@ will be selected. a `GtkSingleSelection` + line="643">a `GtkSingleSelection` the item to select or %GTK_INVALID_LIST_POSITION + line="644">the item to select or %GTK_INVALID_LIST_POSITION @@ -127291,13 +130239,9 @@ will be selected. setter="set_autoselect" getter="get_autoselect" default-value="TRUE"> - - If the selection will always select an item. + line="436">If the selection will always select an item. setter="set_can_unselect" getter="get_can_unselect" default-value="FALSE"> - - If unselecting the selected item is allowed. + line="446">If unselecting the selected item is allowed. The type of items. See [method@Gio.ListModel.get_item_type]. + line="456">The type of items. See [method@Gio.ListModel.get_item_type]. transfer-ownership="none" setter="set_model" getter="get_model"> - - The model being managed. + line="468">The model being managed. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="478">The number of items. See [method@Gio.ListModel.get_n_items]. setter="set_selected" getter="get_selected" default-value="4294967295"> - - Position of the selected item. + line="490">Position of the selected item. - The selected item. + line="500">The selected item. @@ -127386,51 +130316,91 @@ will be selected. glib:get-type="gtk_size_group_get_type"> `GtkSizeGroup` groups widgets together so they all request the same size. + line="31">Groups widgets together so they all request the same size. -This is typically useful when you want a column of widgets to have the -same size, but you can’t use a `GtkGrid`. +This is typically useful when you want a column of widgets to have +the same size, but you can’t use a [class@Gtk.Grid] or [class@Gtk.Box]. In detail, the size requested for each widget in a `GtkSizeGroup` is the maximum of the sizes that would have been requested for each -widget in the size group if they were not in the size group. The mode -of the size group (see [method@Gtk.SizeGroup.set_mode]) determines whether -this applies to the horizontal size, the vertical size, or both sizes. +widget in the size group if they were not in the size group. The +[mode][method@Gtk.SizeGroup.set_mode] of the size group determines +whether this applies to the horizontal size, the vertical size, or +both sizes. Note that size groups only affect the amount of space requested, not the size that the widgets finally receive. If you want the widgets in a `GtkSizeGroup` to actually be the same size, you need to pack them in -such a way that they get the size they request and not more. +such a way that they get the size they request and not more. In +particular it doesn't make a lot of sense to set +[the expand flags][method@Gtk.Widget.set_hexpand] on the widgets that +are members of a size group. `GtkSizeGroup` objects are referenced by each widget in the size group, so once you have added all widgets to a `GtkSizeGroup`, you can drop -the initial reference to the size group with g_object_unref(). If the -widgets in the size group are subsequently destroyed, then they will -be removed from the size group and drop their references on the size -group; when all widgets have been removed, the size group will be -freed. +the initial reference to the size group with +[method@GObject.Object.unref]. If the widgets in the size group are +subsequently destroyed, then they will be removed from the size group +and drop their references on the size group; when all widgets have been +removed, the size group will be freed. Widgets can be part of multiple size groups; GTK will compute the -horizontal size of a widget from the horizontal requisition of all -widgets that can be reached from the widget by a chain of size groups -of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the -vertical size from the vertical requisition of all widgets that can be -reached from the widget by a chain of size groups of type -%GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH. - -Note that only non-contextual sizes of every widget are ever consulted -by size groups (since size groups have no knowledge of what size a widget -will be allocated in one dimension, it cannot derive how much height -a widget will receive for a given width). When grouping widgets that -trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH: -the height for the minimum width will be the requested height for all -widgets in the group. The same is of course true when horizontally grouping -width for height widgets. - -Widgets that trade height-for-width should set a reasonably large minimum -width by way of [property@Gtk.Label:width-chars] for instance. Widgets with -static sizes as well as widgets that grow (such as ellipsizing text) need no -such considerations. +horizontal size of a widget from the horizontal requisition of all widgets +that can be reached from the widget by a chain of size groups with mode +[enum@Gtk.SizeGroupMode.HORIZONTAL] or [enum@Gtk.SizeGroupMode.BOTH], and +the vertical size from the vertical requisition of all widgets that can be +reached from the widget by a chain of size groups with mode +[enum@Gtk.SizeGroupMode.VERTICAL] or [enum@Gtk.SizeGroupMode.BOTH]. + +# Size groups and trading height-for-width + +::: warning + Generally, size groups don't interact well with widgets that + trade height for width (or width for height), such as wrappable + labels. Avoid using size groups with such widgets. + +A size group with mode [enum@Gtk.SizeGroupMode.HORIZONTAL] or +[enum@Gtk.SizeGroupMode.VERTICAL] only consults non-contextual sizes +of widgets other than the one being measured, since it has no +knowledge of what size a widget will get allocated in the other +orientation. This can lead to widgets in a group actually requesting +different contextual sizes, contrary to the purpose of +`GtkSizeGroup`. + +In contrast, a size group with mode [enum@Gtk.SizeGroupMode.BOTH] can +properly propagate the available size in the opposite orientation +when measuring widgets in the group, which results in consistent and +accurate measurements. + +In case some mechanism other than a size group is already used to +ensure that widgets in a group all get the same size in one +orientation (for example, some common ancestor is known to allocate +the same width to all its children), and the size group is only +really needed to also make the widgets request the same size in the +other orientation, it is beneficial to still set the group's mode to +[enum@Gtk.SizeGroupMode.BOTH]. This lets the group assume and count +on sizes of the widgets in the former orientation being the same, +which enables it to propagate the available size as described above. + +# Alternatives to size groups + +Size groups have many limitations, such as only influencing size +requests but not allocations, and poor height-for-width support. When +possible, prefer using dedicated mechanisms that can properly ensure +that the widgets get the same size. + +Various container widgets and layout managers support a homogeneous +layout mode, where they will explicitly give the same size to their +children (see [property@Gtk.Box:homogeneous]). Using homogeneous mode +can also have large performance benefits compared to either the same +container in non-homogeneous mode, or to size groups. + +[class@Gtk.Grid] can be used to position widgets into rows and +columns. Members of each column will have the same width among them; +likewise, members of each row will have the same height. On top of +that, the heights can be made equal between all rows with +[property@Gtk.Grid:row-homogeneous], and the widths can be made equal +between all columns with [property@Gtk.Grid:column-homogeneous]. # GtkSizeGroup as GtkBuildable @@ -127454,19 +130424,19 @@ An example of a UI definition fragment with `GtkSizeGroup`: Create a new `GtkSizeGroup`. + line="334">Create a new `GtkSizeGroup`. a newly created `GtkSizeGroup` + line="340">a newly created `GtkSizeGroup` the mode for the new size group. + line="336">the mode for the new size group. @@ -127474,7 +130444,7 @@ An example of a UI definition fragment with `GtkSizeGroup`: Adds a widget to a `GtkSizeGroup`. + line="404">Adds a widget to a `GtkSizeGroup`. In the future, the requisition of the widget will be determined as the maximum of its requisition @@ -127493,13 +130463,13 @@ will be removed from the size group. a `GtkSizeGroup` + line="406">a `GtkSizeGroup` the `GtkWidget` to add + line="407">the `GtkWidget` to add @@ -127507,22 +130477,21 @@ will be removed from the size group. - Gets the current mode of the size group. + line="386">Gets the current mode of the size group. the current mode of the size group. + line="392">the current mode of the size group. a `GtkSizeGroup` + line="388">a `GtkSizeGroup` @@ -127530,12 +130499,12 @@ will be removed from the size group. Returns the list of widgets associated with @size_group. + line="472">Returns the list of widgets associated with @size_group. a `GSList` of + line="478">a `GSList` of widgets. The list is owned by GTK and should not be modified. @@ -127545,7 +130514,7 @@ will be removed from the size group. a `GtkSizeGroup` + line="474">a `GtkSizeGroup` @@ -127553,7 +130522,7 @@ will be removed from the size group. Removes a widget from a `GtkSizeGroup`. + line="445">Removes a widget from a `GtkSizeGroup`. @@ -127562,13 +130531,13 @@ will be removed from the size group. a `GtkSizeGroup` + line="447">a `GtkSizeGroup` the `GtkWidget` to remove + line="448">the `GtkWidget` to remove @@ -127576,10 +130545,9 @@ will be removed from the size group. - Sets the `GtkSizeGroupMode` of the size group. + line="353">Sets the `GtkSizeGroupMode` of the size group. The mode of the size group determines whether the widgets in the size group should all have the same horizontal requisition @@ -127594,13 +130562,13 @@ in both directions (%GTK_SIZE_GROUP_BOTH). a `GtkSizeGroup` + line="355">a `GtkSizeGroup` the mode to set for the size group. + line="356">the mode to set for the size group. @@ -127611,13 +130579,9 @@ in both directions (%GTK_SIZE_GROUP_BOTH). setter="set_mode" getter="get_mode" default-value="GTK_SIZE_GROUP_HORIZONTAL"> - - The direction in which the size group affects requested sizes. + line="264">The direction in which the size group affects requested sizes. @@ -127630,7 +130594,7 @@ in both directions (%GTK_SIZE_GROUP_BOTH). c:type="GtkSizeGroupMode"> The mode of the size group determines the directions in which the size + line="785">The mode of the size group determines the directions in which the size group affects the requested sizes of its component widgets. glib:name="GTK_SIZE_GROUP_NONE"> group has no effect + line="787">group has no effect glib:name="GTK_SIZE_GROUP_HORIZONTAL"> group affects horizontal requisition + line="788">group affects horizontal requisition glib:name="GTK_SIZE_GROUP_VERTICAL"> group affects vertical requisition + line="789">group affects vertical requisition glib:name="GTK_SIZE_GROUP_BOTH"> group affects both horizontal and vertical requisition + line="790">group affects both horizontal and vertical requisition c:type="GtkSizeRequestMode"> Specifies a preference for height-for-width or + line="802">Specifies a preference for height-for-width or width-for-height geometry management. glib:name="GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH"> Prefer height-for-width geometry management + line="804">Prefer height-for-width geometry management glib:name="GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT"> Prefer width-for-height geometry management + line="805">Prefer width-for-height geometry management glib:name="GTK_SIZE_REQUEST_CONSTANT_SIZE"> Don’t trade height-for-width or width-for-height + line="806">Don’t trade height-for-width or width-for-height glib:type-struct="SliceListModelClass"> `GtkSliceListModel` is a list model that presents a slice of another model. + line="27">A list model that presents a slice of another model. This is useful when implementing paging by setting the size to the number of elements per page and updating the offset whenever a different page is @@ -127765,7 +130729,6 @@ of the given @model. - Gets the model that is currently being used or %NULL if none. @@ -127788,7 +130751,6 @@ of the given @model. - Gets the offset set via gtk_slice_list_model_set_offset(). @@ -127811,7 +130773,6 @@ of the given @model. - Gets the size set via gtk_slice_list_model_set_size(). @@ -127834,7 +130795,6 @@ of the given @model. - Sets the model to show a slice of. @@ -127865,7 +130825,6 @@ The model's item type must conform to @self's item type. - Sets the offset into the original model for this slice. @@ -127894,7 +130853,6 @@ If the offset is too large for the sliced model, - Sets the maximum size. @self will never have more items @@ -127932,10 +130890,6 @@ or the model sliced from doesn't have enough items. transfer-ownership="none" setter="set_model" getter="get_model"> - - Child model to take slice from. @@ -127956,10 +130910,6 @@ or the model sliced from doesn't have enough items. setter="set_offset" getter="get_offset" default-value="0"> - - Offset of slice. @@ -127971,10 +130921,6 @@ or the model sliced from doesn't have enough items. setter="set_size" getter="get_size" default-value="10"> - - Maximum size of slice. @@ -127997,7 +130943,7 @@ or the model sliced from doesn't have enough items. glib:type-struct="SnapshotClass"> `GtkSnapshot` assists in creating [class@Gsk.RenderNode]s for widgets. + line="44">Assists in creating [class@Gsk.RenderNode]s for widgets. It functions in a similar way to a cairo context, and maintains a stack of render nodes and their associated transformations. @@ -128013,22 +130959,22 @@ the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own Creates a new `GtkSnapshot`. + line="298">Creates a new `GtkSnapshot`. a newly-allocated `GtkSnapshot` + line="303">a newly-allocated `GtkSnapshot` Appends a stroked border rectangle inside the given @outline. + line="3106">Appends a stroked border rectangle inside the given @outline. The four sides of the border can have different widths and colors. - + @@ -128036,19 +130982,19 @@ The four sides of the border can have different widths and colors. a `GtkSnapshot` + line="3108">a `GtkSnapshot` the outline of the border + line="3109">the outline of the border the stroke width of the border on + line="3110">the stroke width of the border on the top, right, bottom and left side respectively. @@ -128057,7 +131003,7 @@ The four sides of the border can have different widths and colors. the color used on the top, right, + line="3112">the color used on the top, right, bottom and left side. @@ -128068,13 +131014,13 @@ The four sides of the border can have different widths and colors. Creates a new [class@Gsk.CairoNode] and appends it to the current + line="2308">Creates a new [class@Gsk.CairoNode] and appends it to the current render node of @snapshot, without changing the current node. - + a `cairo_t` suitable for drawing the contents of + line="2316">a `cairo_t` suitable for drawing the contents of the newly created render node @@ -128082,13 +131028,13 @@ render node of @snapshot, without changing the current node. a `GtkSnapshot` + line="2310">a `GtkSnapshot` the bounds for the new node + line="2311">the bounds for the new node @@ -128096,13 +131042,13 @@ render node of @snapshot, without changing the current node. Creates a new render node drawing the @color into the + line="2415">Creates a new render node drawing the @color into the given @bounds and appends it to the current render node of @snapshot. You should try to avoid calling this function if @color is transparent. - + @@ -128110,19 +131056,19 @@ You should try to avoid calling this function if a `GtkSnapshot` + line="2417">a `GtkSnapshot` the color to draw + line="2418">the color to draw the bounds for the new node + line="2419">the bounds for the new node @@ -128131,8 +131077,8 @@ You should try to avoid calling this function if c:identifier="gtk_snapshot_append_conic_gradient"> Appends a conic gradient node with the given stops to @snapshot. - + line="2747">Appends a conic gradient node with the given stops to @snapshot. + @@ -128140,32 +131086,32 @@ You should try to avoid calling this function if a `GtkSnapshot` + line="2749">a `GtkSnapshot` the rectangle to render the gradient into + line="2750">the rectangle to render the gradient into the center point of the conic gradient + line="2751">the center point of the conic gradient the clockwise rotation in degrees of the starting angle. + line="2752">the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top. the color stops defining the gradient + line="2754">the color stops defining the gradient @@ -128173,17 +131119,58 @@ You should try to avoid calling this function if the number of elements in @stops + line="2755">the number of elements in @stops + + A convenience method to fill a path with a color. + +See [method@Gtk.Snapshot.push_fill] if you need +to fill a path with more complex content than +a color. + + + + + + + a `GtkSnapshot` + + + + The path describing the area to fill + + + + The fill rule to use + + + + the color to fill the path with + + + + Appends an inset shadow into the box given by @outline. - + line="3179">Appends an inset shadow into the box given by @outline. + @@ -128191,60 +131178,78 @@ You should try to avoid calling this function if a `GtkSnapshot` + line="3181">a `GtkSnapshot` outline of the region surrounded by shadow + line="3182">outline of the region surrounded by shadow color of the shadow + line="3183">color of the shadow horizontal offset of shadow + line="3184">horizontal offset of shadow vertical offset of shadow + line="3185">vertical offset of shadow how far the shadow spreads towards the inside + line="3186">how far the shadow spreads towards the inside how much blur to apply to the shadow + line="3187">how much blur to apply to the shadow - + Creates render nodes for rendering @layout in the given foregound @color +and appends them to the current node of @snapshot without changing the +current node. The current theme's foreground color for a widget can be +obtained with [method@Gtk.Widget.get_color]. + +Note that if the layout does not produce any visible output, then nodes +may not be added to the @snapshot. + + a `GtkSnapshot` + the `PangoLayout` to render + the foreground color to render the layout in @@ -128253,8 +131258,8 @@ You should try to avoid calling this function if c:identifier="gtk_snapshot_append_linear_gradient"> Appends a linear gradient node with the given stops to @snapshot. - + line="2512">Appends a linear gradient node with the given stops to @snapshot. + @@ -128262,31 +131267,31 @@ You should try to avoid calling this function if a `GtkSnapshot` + line="2514">a `GtkSnapshot` the rectangle to render the linear gradient into + line="2515">the rectangle to render the linear gradient into the point at which the linear gradient will begin + line="2516">the point at which the linear gradient will begin the point at which the linear gradient will finish + line="2517">the point at which the linear gradient will finish the color stops defining the gradient + line="2518">the color stops defining the gradient @@ -128294,7 +131299,7 @@ You should try to avoid calling this function if the number of elements in @stops + line="2519">the number of elements in @stops @@ -128302,12 +131307,12 @@ You should try to avoid calling this function if Appends @node to the current render node of @snapshot, + line="2285">Appends @node to the current render node of @snapshot, without changing the current node. If @snapshot does not have a current node yet, @node will become the initial node. - + @@ -128315,13 +131320,13 @@ will become the initial node. a `GtkSnapshot` + line="2287">a `GtkSnapshot` a `GskRenderNode` + line="2288">a `GskRenderNode` @@ -128330,8 +131335,8 @@ will become the initial node. c:identifier="gtk_snapshot_append_outset_shadow"> Appends an outset shadow node around the box given by @outline. - + line="3252">Appends an outset shadow node around the box given by @outline. + @@ -128339,43 +131344,43 @@ will become the initial node. a `GtkSnapshot` + line="3254">a `GtkSnapshot` outline of the region surrounded by shadow + line="3255">outline of the region surrounded by shadow color of the shadow + line="3256">color of the shadow horizontal offset of shadow + line="3257">horizontal offset of shadow vertical offset of shadow + line="3258">vertical offset of shadow how far the shadow spreads towards the outside + line="3259">how far the shadow spreads towards the outside how much blur to apply to the shadow + line="3260">how much blur to apply to the shadow @@ -128384,8 +131389,8 @@ will become the initial node. c:identifier="gtk_snapshot_append_radial_gradient"> Appends a radial gradient node with the given stops to @snapshot. - + line="2857">Appends a radial gradient node with the given stops to @snapshot. + @@ -128393,49 +131398,49 @@ will become the initial node. a `GtkSnapshot` + line="2859">a `GtkSnapshot` the rectangle to render the readial gradient into + line="2860">the rectangle to render the readial gradient into the center point for the radial gradient + line="2861">the center point for the radial gradient the horizontal radius + line="2862">the horizontal radius the vertical radius + line="2863">the vertical radius the start position (on the horizontal axis) + line="2864">the start position (on the horizontal axis) the end position (on the horizontal axis) + line="2865">the end position (on the horizontal axis) the color stops defining the gradient + line="2866">the color stops defining the gradient @@ -128443,7 +131448,7 @@ will become the initial node. the number of elements in @stops + line="2867">the number of elements in @stops @@ -128452,8 +131457,8 @@ will become the initial node. c:identifier="gtk_snapshot_append_repeating_linear_gradient"> Appends a repeating linear gradient node with the given stops to @snapshot. - + line="2631">Appends a repeating linear gradient node with the given stops to @snapshot. + @@ -128461,31 +131466,31 @@ will become the initial node. a `GtkSnapshot` + line="2633">a `GtkSnapshot` the rectangle to render the linear gradient into + line="2634">the rectangle to render the linear gradient into the point at which the linear gradient will begin + line="2635">the point at which the linear gradient will begin the point at which the linear gradient will finish + line="2636">the point at which the linear gradient will finish the color stops defining the gradient + line="2637">the color stops defining the gradient @@ -128493,7 +131498,7 @@ will become the initial node. the number of elements in @stops + line="2638">the number of elements in @stops @@ -128502,8 +131507,8 @@ will become the initial node. c:identifier="gtk_snapshot_append_repeating_radial_gradient"> Appends a repeating radial gradient node with the given stops to @snapshot. - + line="2982">Appends a repeating radial gradient node with the given stops to @snapshot. + @@ -128511,49 +131516,49 @@ will become the initial node. a `GtkSnapshot` + line="2984">a `GtkSnapshot` the rectangle to render the readial gradient into + line="2985">the rectangle to render the readial gradient into the center point for the radial gradient + line="2986">the center point for the radial gradient the horizontal radius + line="2987">the horizontal radius the vertical radius + line="2988">the vertical radius the start position (on the horizontal axis) + line="2989">the start position (on the horizontal axis) the end position (on the horizontal axis) + line="2990">the end position (on the horizontal axis) the color stops defining the gradient + line="2991">the color stops defining the gradient @@ -128561,7 +131566,7 @@ will become the initial node. the number of elements in @stops + line="2992">the number of elements in @stops @@ -128571,14 +131576,14 @@ will become the initial node. version="4.10"> Creates a new render node drawing the @texture + line="2380">Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @snapshot. In contrast to [method@Gtk.Snapshot.append_texture], this function provides control about how the filter that is used when scaling. - + @@ -128586,40 +131591,81 @@ that is used when scaling. a `GtkSnapshot` + line="2382">a `GtkSnapshot` the texture to render + line="2383">the texture to render the filter to use + line="2384">the filter to use the bounds for the new node + line="2385">the bounds for the new node + + A convenience method to stroke a path with a color. + +See [method@Gtk.Snapshot.push_stroke] if you need +to stroke a path with more complex content than +a color. + + + + + + + a `GtkSnapshot` + + + + The path describing the area to fill + + + + The stroke attributes + + + + the color to fill the path with + + + + Creates a new render node drawing the @texture + line="2346">Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @snapshot. If the texture needs to be scaled to fill @bounds, linear filtering is used. See [method@Gtk.Snapshot.append_scaled_texture] if you need other filtering, such as nearest-neighbour. - + @@ -128627,19 +131673,19 @@ if you need other filtering, such as nearest-neighbour. a `GtkSnapshot` + line="2348">a `GtkSnapshot` the texture to render + line="2349">the texture to render the bounds for the new node + line="2350">the bounds for the new node @@ -128649,7 +131695,7 @@ if you need other filtering, such as nearest-neighbour. introspectable="0"> Returns the node that was constructed by @snapshot + line="311">Returns the node that was constructed by @snapshot and frees @snapshot. See also [method@Gtk.Snapshot.to_node]. @@ -128657,14 +131703,14 @@ See also [method@Gtk.Snapshot.to_node]. a newly-created [class@Gsk.RenderNode] + line="320">a newly-created [class@Gsk.RenderNode] a `GtkSnapshot` + line="313">a `GtkSnapshot` @@ -128674,20 +131720,20 @@ See also [method@Gtk.Snapshot.to_node]. introspectable="0"> Returns a paintable for the node that was + line="333">Returns a paintable for the node that was constructed by @snapshot and frees @snapshot. a newly-created [iface@Gdk.Paintable] + line="342">a newly-created [iface@Gdk.Paintable] a `GtkSnapshot` + line="335">a `GtkSnapshot` allow-none="1"> The size of the resulting paintable + line="336">The size of the resulting paintable or %NULL to use the bounds of the snapshot + c:identifier="gtk_snapshot_gl_shader_pop_texture" + deprecated="1" + deprecated-version="4.16"> Removes the top element from the stack of render nodes and + line="2005">Removes the top element from the stack of render nodes and adds it to the nearest [class@Gsk.GLShaderNode] below it. This must be called the same number of times as the number of textures is needed for the shader in [method@Gtk.Snapshot.push_gl_shader]. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [class@Gtk.GLArea] for + OpenGL rendering. + @@ -128720,7 +131771,7 @@ of textures is needed for the shader in a `GtkSnapshot` + line="2007">a `GtkSnapshot` @@ -128728,10 +131779,10 @@ of textures is needed for the shader in Applies a perspective projection transform. + line="2264">Applies a perspective projection transform. See [method@Gsk.Transform.perspective] for a discussion on the details. - + @@ -128739,13 +131790,13 @@ See [method@Gsk.Transform.perspective] for a discussion on the details. a `GtkSnapshot` + line="2266">a `GtkSnapshot` distance of the z=0 plane + line="2267">distance of the z=0 plane @@ -128753,9 +131804,9 @@ See [method@Gsk.Transform.perspective] for a discussion on the details. Removes the top element from the stack of render nodes, + line="1987">Removes the top element from the stack of render nodes, and appends it to the node underneath it. - + @@ -128763,7 +131814,7 @@ and appends it to the node underneath it. a `GtkSnapshot` + line="1989">a `GtkSnapshot` @@ -128771,7 +131822,7 @@ and appends it to the node underneath it. Blends together two images with the given blend mode. + line="1547">Blends together two images with the given blend mode. Until the first call to [method@Gtk.Snapshot.pop], the bottom image for the blend operation will be recorded. @@ -128780,7 +131831,7 @@ recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires two subsequent calls to [method@Gtk.Snapshot.pop]. - + @@ -128788,13 +131839,13 @@ to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="1549">a `GtkSnapshot` blend mode to use + line="1550">blend mode to use @@ -128802,7 +131853,7 @@ to [method@Gtk.Snapshot.pop]. Blurs an image. + line="548">Blurs an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. @@ -128813,13 +131864,13 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="550">a `GtkSnapshot` the blur radius to use. Must be positive + line="551">the blur radius to use. Must be positive @@ -128827,7 +131878,7 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. Clips an image to a rectangle. + line="898">Clips an image to a rectangle. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. @@ -128838,13 +131889,13 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="900">a `GtkSnapshot` the rectangle to clip to + line="901">the rectangle to clip to @@ -128853,7 +131904,7 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. c:identifier="gtk_snapshot_push_color_matrix"> Modifies the colors of an image by applying an affine transformation + line="656">Modifies the colors of an image by applying an affine transformation in RGB space. In particular, the colors will be transformed by applying @@ -128872,19 +131923,19 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="658">a `GtkSnapshot` the color matrix to use + line="659">the color matrix to use the color offset to use + line="660">the color offset to use @@ -128893,7 +131944,7 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. c:identifier="gtk_snapshot_push_cross_fade"> Snapshots a cross-fade operation between two images with the + line="1736">Snapshots a cross-fade operation between two images with the given @progress. Until the first call to [method@Gtk.Snapshot.pop], the start image @@ -128902,7 +131953,7 @@ until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires two subsequent calls to [method@Gtk.Snapshot.pop]. - + @@ -128910,13 +131961,13 @@ to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="1738">a `GtkSnapshot` progress between 0.0 and 1.0 + line="1739">progress between 0.0 and 1.0 @@ -128926,7 +131977,7 @@ to [method@Gtk.Snapshot.pop]. introspectable="0"> Inserts a debug node with a message. + line="419">Inserts a debug node with a message. Debug nodes don't affect the rendering at all, but can be helpful in identifying parts of a render node tree dump, @@ -128939,27 +131990,67 @@ for example in the GTK inspector. a `GtkSnapshot` + line="421">a `GtkSnapshot` a printf-style format string + line="422">a printf-style format string arguments for @message + line="423">arguments for @message - + Push a [class@Gsk.GLShaderNode]. + line="1202">Fills the area given by @path and @fill_rule with an image and discards everything +outside of it. + +The image is recorded until the next call to [method@Gtk.Snapshot.pop]. + +If you want to fill the path with a color, [method@Gtk.Snapshot.append_fill] +may be more convenient. + + + + + + + a `GtkSnapshot` + + + + The path describing the area to fill + + + + The fill rule to use + + + + + + Push a [class@Gsk.GLShaderNode]. The node uses the given [class@Gsk.GLShader] and uniform values Additionally this takes a list of @n_children other nodes @@ -128993,7 +132084,10 @@ push a texture node. These will be used directly rather than being re-rendered. For details on how to write shaders, see [class@Gsk.GLShader]. - + GTK's new Vulkan-focused rendering + does not support this feature. Use [class@Gtk.GLArea] for + OpenGL rendering. + @@ -129001,25 +132095,25 @@ For details on how to write shaders, see [class@Gsk.GLShader]. a `GtkSnapshot` + line="1015">a `GtkSnapshot` The code to run + line="1016">The code to run the rectangle to render into + line="1017">the rectangle to render into Data block with arguments for the shader. + line="1018">Data block with arguments for the shader. @@ -129029,14 +132123,14 @@ For details on how to write shaders, see [class@Gsk.GLShader]. version="4.10"> Until the first call to [method@Gtk.Snapshot.pop], the + line="1627">Until the first call to [method@Gtk.Snapshot.pop], the mask image for the mask operation will be recorded. After that call, the source image will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). - + @@ -129044,13 +132138,13 @@ Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). a #GtkSnapshot + line="1629">a #GtkSnapshot mask mode to use + line="1630">mask mode to use @@ -129058,7 +132152,7 @@ Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). Modifies the opacity of an image. + line="497">Modifies the opacity of an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. @@ -129069,13 +132163,13 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="499">a `GtkSnapshot` the opacity to use + line="500">the opacity to use @@ -129083,7 +132177,7 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. Creates a node that repeats the child node. + line="830">Creates a node that repeats the child node. The child is recorded until the next call to [method@Gtk.Snapshot.pop]. @@ -129094,13 +132188,13 @@ The child is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="832">a `GtkSnapshot` the bounds within which to repeat + line="833">the bounds within which to repeat allow-none="1"> the bounds of the child or %NULL + line="834">the bounds of the child or %NULL to use the full size of the collected child node @@ -129119,7 +132213,7 @@ The child is recorded until the next call to [method@Gtk.Snapshot.pop]. c:identifier="gtk_snapshot_push_rounded_clip"> Clips an image to a rounded rectangle. + line="1141">Clips an image to a rounded rectangle. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. @@ -129130,13 +132224,13 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="1143">a `GtkSnapshot` the rounded rectangle to clip to + line="1144">the rounded rectangle to clip to @@ -129144,10 +132238,10 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. Applies a shadow to an image. + line="1403">Applies a shadow to an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. - + @@ -129155,13 +132249,13 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` + line="1405">a `GtkSnapshot` the first shadow specification + line="1406">the first shadow specification @@ -129169,11 +132263,52 @@ The image is recorded until the next call to [method@Gtk.Snapshot.pop]. number of shadow specifications + line="1407">number of shadow specifications + + Strokes the given @path with the attributes given by @stroke and +an image. + +The image is recorded until the next call to [method@Gtk.Snapshot.pop]. + +Note that the strokes are subject to the same transformation as +everything else, so uneven scaling will cause horizontal and vertical +strokes to have different widths. + +If you want to stroke the path with a color, [method@Gtk.Snapshot.append_stroke] +may be more convenient. + + + + + + + a #GtkSnapshot + + + + The path to stroke + + + + The stroke attributes + + + + Restores @snapshot to the state saved by a preceding call to + line="2058">Restores @snapshot to the state saved by a preceding call to [method@Snapshot.save] and removes that state from the stack of saved states. - + @@ -129446,7 +132581,7 @@ saved states. a `GtkSnapshot` + line="2060">a `GtkSnapshot` @@ -129454,12 +132589,12 @@ saved states. Rotates @@snapshot's coordinate system by @angle degrees in 2D space - + line="2170">Rotates @@snapshot's coordinate system by @angle degrees in 2D space - or in 3D speak, rotates around the Z axis. The rotation happens around the origin point of (0, 0) in the @snapshot's current coordinate system. To rotate around axes other than the Z axis, use [method@Gsk.Transform.rotate_3d]. - + @@ -129467,13 +132602,13 @@ To rotate around axes other than the Z axis, use [method@Gsk.Transform.rotate_3d a `GtkSnapshot` + line="2172">a `GtkSnapshot` the rotation angle, in degrees (clockwise) + line="2173">the rotation angle, in degrees (clockwise) @@ -129481,10 +132616,10 @@ To rotate around axes other than the Z axis, use [method@Gsk.Transform.rotate_3d Rotates @snapshot's coordinate system by @angle degrees around @axis. + line="2193">Rotates @snapshot's coordinate system by @angle degrees around @axis. For a rotation in 2D space, use [method@Gsk.Transform.rotate]. - + @@ -129492,19 +132627,19 @@ For a rotation in 2D space, use [method@Gsk.Transform.rotate]. a `GtkSnapshot` + line="2195">a `GtkSnapshot` the rotation angle, in degrees (clockwise) + line="2196">the rotation angle, in degrees (clockwise) The rotation axis + line="2197">The rotation axis @@ -129512,7 +132647,7 @@ For a rotation in 2D space, use [method@Gsk.Transform.rotate]. Makes a copy of the current state of @snapshot and saves it + line="2030">Makes a copy of the current state of @snapshot and saves it on an internal stack. When [method@Gtk.Snapshot.restore] is called, @snapshot will @@ -129524,7 +132659,7 @@ the matching paired `gtk_snapshot_save()`. It is necessary to clear all saved states with corresponding calls to `gtk_snapshot_restore()`. - + @@ -129532,7 +132667,7 @@ calls to `gtk_snapshot_restore()`. a `GtkSnapshot` + line="2032">a `GtkSnapshot` @@ -129540,11 +132675,11 @@ calls to `gtk_snapshot_restore()`. Scales @snapshot's coordinate system in 2-dimensional space by + line="2217">Scales @snapshot's coordinate system in 2-dimensional space by the given factors. Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. - + @@ -129552,19 +132687,19 @@ Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. a `GtkSnapshot` + line="2219">a `GtkSnapshot` scaling factor on the X axis + line="2220">scaling factor on the X axis scaling factor on the Y axis + line="2221">scaling factor on the Y axis @@ -129572,8 +132707,8 @@ Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. Scales @snapshot's coordinate system by the given factors. - + line="2241">Scales @snapshot's coordinate system by the given factors. + @@ -129581,25 +132716,25 @@ Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. a `GtkSnapshot` + line="2243">a `GtkSnapshot` scaling factor on the X axis + line="2244">scaling factor on the X axis scaling factor on the Y axis + line="2245">scaling factor on the Y axis scaling factor on the Z axis + line="2246">scaling factor on the Z axis @@ -129607,7 +132742,7 @@ Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. Returns the render node that was constructed + line="1901">Returns the render node that was constructed by @snapshot. Note that this function may return %NULL if nothing has been @@ -129621,7 +132756,7 @@ be called after this is [method@GObject.Object.unref]. the constructed `GskRenderNode` or + line="1916">the constructed `GskRenderNode` or %NULL if there are no nodes to render. @@ -129629,7 +132764,7 @@ be called after this is [method@GObject.Object.unref]. a `GtkSnapshot` + line="1903">a `GtkSnapshot` @@ -129637,7 +132772,7 @@ be called after this is [method@GObject.Object.unref]. Returns a paintable encapsulating the render node + line="1939">Returns a paintable encapsulating the render node that was constructed by @snapshot. After calling this function, it is no longer possible to @@ -129647,14 +132782,14 @@ be called after this is [method@GObject.Object.unref]. a new `GdkPaintable` + line="1952">a new `GdkPaintable` a `GtkSnapshot` + line="1941">a `GtkSnapshot` allow-none="1"> The size of the resulting paintable + line="1942">The size of the resulting paintable or %NULL to use the bounds of the snapshot @@ -129672,8 +132807,8 @@ be called after this is [method@GObject.Object.unref]. Transforms @snapshot's coordinate system with the given @transform. - + line="2091">Transforms @snapshot's coordinate system with the given @transform. + @@ -129681,7 +132816,7 @@ be called after this is [method@GObject.Object.unref]. a `GtkSnapshot` + line="2093">a `GtkSnapshot` allow-none="1"> the transform to apply + line="2094">the transform to apply @@ -129699,8 +132834,8 @@ be called after this is [method@GObject.Object.unref]. c:identifier="gtk_snapshot_transform_matrix"> Transforms @snapshot's coordinate system with the given @matrix. - + line="2110">Transforms @snapshot's coordinate system with the given @matrix. + @@ -129708,13 +132843,13 @@ be called after this is [method@GObject.Object.unref]. a `GtkSnapshot` + line="2112">a `GtkSnapshot` the matrix to multiply the transform with + line="2113">the matrix to multiply the transform with @@ -129722,8 +132857,8 @@ be called after this is [method@GObject.Object.unref]. Translates @snapshot's coordinate system by @point in 2-dimensional space. - + line="2130">Translates @snapshot's coordinate system by @point in 2-dimensional space. + @@ -129731,13 +132866,13 @@ be called after this is [method@GObject.Object.unref]. a `GtkSnapshot` + line="2132">a `GtkSnapshot` the point to translate the snapshot by + line="2133">the point to translate the snapshot by @@ -129745,8 +132880,8 @@ be called after this is [method@GObject.Object.unref]. Translates @snapshot's coordinate system by @point. - + line="2150">Translates @snapshot's coordinate system by @point. + @@ -129754,13 +132889,13 @@ be called after this is [method@GObject.Object.unref]. a `GtkSnapshot` + line="2152">a `GtkSnapshot` the point to translate the snapshot by + line="2153">the point to translate the snapshot by @@ -129782,12 +132917,14 @@ be called after this is [method@GObject.Object.unref]. glib:type-struct="SortListModelClass"> A `GListModel` that sorts the elements of an underlying model -according to a `GtkSorter`. + line="56">A list model that sorts the elements of another model. + +The elements are sorted according to a `GtkSorter`. The model is a stable sort. If two items compare equal according to the sorter, the one that appears first in the original model will also appear first after sorting. + Note that if you change the sorter, the previous order will have no influence on the new order. If you want that, consider using a `GtkMultiSorter` and appending the previous sorter to it. @@ -129814,12 +132951,12 @@ inside their sections. Creates a new sort list model that uses the @sorter to sort @model. + line="1114">Creates a new sort list model that uses the @sorter to sort @model. a new `GtkSortListModel` + line="1121">a new `GtkSortListModel` @@ -129829,7 +132966,7 @@ inside their sections. allow-none="1"> the model to sort + line="1116">the model to sort allow-none="1"> the `GtkSorter` to sort @model with, + line="1117">the `GtkSorter` to sort @model with, @@ -129846,24 +132983,23 @@ inside their sections. - Returns whether incremental sorting is enabled. + line="1338">Returns whether incremental sorting is enabled. See [method@Gtk.SortListModel.set_incremental]. %TRUE if incremental sorting is enabled + line="1346">%TRUE if incremental sorting is enabled a `GtkSortListModel` + line="1340">a `GtkSortListModel` @@ -129871,22 +133007,21 @@ See [method@Gtk.SortListModel.set_incremental]. - Gets the model currently sorted or %NULL if none. + line="1192">Gets the model currently sorted or %NULL if none. The model that gets sorted + line="1198">The model that gets sorted a `GtkSortListModel` + line="1194">a `GtkSortListModel` @@ -129894,10 +133029,9 @@ See [method@Gtk.SortListModel.set_incremental]. - Estimates progress of an ongoing sorting operation. + line="1356">Estimates progress of an ongoing sorting operation. The estimate is the number of items that would still need to be sorted to finish the sorting operation if this was a linear @@ -129918,14 +133052,14 @@ function returns 0. a progress estimate of remaining items to sort + line="1378">a progress estimate of remaining items to sort a `GtkSortListModel` + line="1358">a `GtkSortListModel` @@ -129934,23 +133068,22 @@ function returns 0. c:identifier="gtk_sort_list_model_get_section_sorter" glib:get-property="section-sorter" version="4.12"> - Gets the section sorter that is used to sort items of @self into + line="1274">Gets the section sorter that is used to sort items of @self into sections. the sorter of #self + line="1281">the sorter of #self a `GtkSortListModel` + line="1276">a `GtkSortListModel` @@ -129958,22 +133091,21 @@ sections. - Gets the sorter that is used to sort @self. + line="1232">Gets the sorter that is used to sort @self. the sorter of #self + line="1238">the sorter of #self a `GtkSortListModel` + line="1234">a `GtkSortListModel` @@ -129981,10 +133113,9 @@ sections. - Sets the sort model to do an incremental sort. + line="1293">Sets the sort model to do an incremental sort. When incremental sorting is enabled, the `GtkSortListModel` will not do a complete sort immediately, but will instead queue an idle handler that @@ -130008,13 +133139,13 @@ about an ongoing incremental sorting operation. a `GtkSortListModel` + line="1295">a `GtkSortListModel` %TRUE to sort incrementally + line="1296">%TRUE to sort incrementally @@ -130022,10 +133153,9 @@ about an ongoing incremental sorting operation. - Sets the model to be sorted. + line="1144">Sets the model to be sorted. The @model's item type must conform to the item type of @self. @@ -130036,7 +133166,7 @@ The @model's item type must conform to the item type of @self. a `GtkSortListModel` + line="1146">a `GtkSortListModel` allow-none="1"> The model to be sorted + line="1147">The model to be sorted @@ -130054,10 +133184,9 @@ The @model's item type must conform to the item type of @self. c:identifier="gtk_sort_list_model_set_section_sorter" glib:set-property="section-sorter" version="4.12"> - Sets a new section sorter on @self. + line="1248">Sets a new section sorter on @self. @@ -130066,7 +133195,7 @@ The @model's item type must conform to the item type of @self. a `GtkSortListModel` + line="1250">a `GtkSortListModel` allow-none="1"> the `GtkSorter` to sort @model with + line="1251">the `GtkSorter` to sort @model with @@ -130083,10 +133212,9 @@ The @model's item type must conform to the item type of @self. - Sets a new sorter on @self. + line="1208">Sets a new sorter on @self. @@ -130095,7 +133223,7 @@ The @model's item type must conform to the item type of @self. a `GtkSortListModel` + line="1210">a `GtkSortListModel` allow-none="1"> the `GtkSorter` to sort @model with + line="1211">the `GtkSorter` to sort @model with @@ -130115,19 +133243,15 @@ The @model's item type must conform to the item type of @self. setter="set_incremental" getter="get_incremental" default-value="FALSE"> - - If the model should sort items incrementally. + line="1030">If the model should sort items incrementally. The type of items. See [method@Gio.ListModel.get_item_type]. + line="1040">The type of items. See [method@Gio.ListModel.get_item_type]. transfer-ownership="none" setter="set_model" getter="get_model"> - - The model being sorted. + line="1052">The model being sorted. default-value="0"> The number of items. See [method@Gio.ListModel.get_n_items]. + line="1062">The number of items. See [method@Gio.ListModel.get_n_items]. - Estimate of unsorted items remaining. + line="1074">Estimate of unsorted items remaining. transfer-ownership="none" setter="set_section_sorter" getter="get_section_sorter"> - - The section sorter for this model, if one is set. + line="1084">The section sorter for this model, if one is set. transfer-ownership="none" setter="set_sorter" getter="get_sorter"> - - The sorter for this model. + line="1096">The sorter for this model. @@ -130208,7 +133318,7 @@ The @model's item type must conform to the item type of @self. c:type="GtkSortType"> Determines the direction of a sort. + line="585">Determines the direction of a sort. glib:name="GTK_SORT_ASCENDING"> Sorting is in ascending order. + line="587">Sorting is in ascending order. glib:name="GTK_SORT_DESCENDING"> Sorting is in descending order. + line="588">Sorting is in descending order. glib:type-struct="SorterClass"> `GtkSorter` is an object to describe sorting criteria. + line="28">Describes sorting criteria for a [class@Gtk.SortListModel]. Its primary user is [class@Gtk.SortListModel] @@ -130347,7 +133457,7 @@ Depending on the @change parameter, it may be possible to update the sort order without a full resorting. Refer to the [enum@Gtk.SorterChange] documentation for details. -This function is intended for implementors of `GtkSorter` +This function is intended for implementers of `GtkSorter` subclasses and should not be called from other functions. @@ -130528,6 +133638,9 @@ to optimize resorting. + Compare two items. See gtk_sorter_compare() for details. @@ -130567,6 +133680,10 @@ to optimize resorting. + Get the `GtkSorderOrder` that applies to the current sorter. + If unimplemented, it returns %GTK_SORTER_ORDER_PARTIAL. @@ -130696,10 +133813,12 @@ to optimize resorting. glib:get-type="gtk_spin_button_get_type"> A `GtkSpinButton` is an ideal way to allow the user to set the -value of some attribute. + line="69">Allows to enter or change numeric values. -![An example GtkSpinButton](spinbutton.png) +<picture> + <source srcset="spinbutton-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkSpinButton" src="spinbutton.png"> +</picture> Rather than having to directly type a number into a `GtkEntry`, `GtkSpinButton` allows the user to click on one of two arrows @@ -130779,6 +133898,12 @@ create_floating_spin_button (void) } ``` +# Shortcuts and Gestures + +The following signals have default keybindings: + +- [signal@Gtk.SpinButton::change-value] + # CSS nodes ``` @@ -130807,7 +133932,7 @@ the .vertical or .horizontal style class on the main node. # Accessibility -`GtkSpinButton` uses the %GTK_ACCESSIBLE_ROLE_SPIN_BUTTON role. +`GtkSpinButton` uses the [enum@Gtk.AccessibleRole.spin_button] role. @@ -130818,12 +133943,12 @@ the .vertical or .horizontal style class on the main node. Creates a new `GtkSpinButton`. + line="1869">Creates a new `GtkSpinButton`. The new `GtkSpinButton` + line="1878">The new `GtkSpinButton` @@ -130833,20 +133958,20 @@ the .vertical or .horizontal style class on the main node. allow-none="1"> the `GtkAdjustment` that this spin button should use + line="1871">the `GtkAdjustment` that this spin button should use specifies by how much the rate of change in the value will + line="1872">specifies by how much the rate of change in the value will accelerate if you continue to hold down an up/down button or arrow key the number of decimal places to display + line="1874">the number of decimal places to display @@ -130855,7 +133980,7 @@ the .vertical or .horizontal style class on the main node. c:identifier="gtk_spin_button_new_with_range"> Creates a new `GtkSpinButton` with the given properties. + line="1897">Creates a new `GtkSpinButton` with the given properties. This is a convenience constructor that allows creation of a numeric `GtkSpinButton` without manually creating @@ -130872,26 +133997,26 @@ is not suitable for your needs, use The new `GtkSpinButton` + line="1917">The new `GtkSpinButton` Minimum allowable value + line="1899">Minimum allowable value Maximum allowable value + line="1900">Maximum allowable value Increment added or subtracted by spinning the widget + line="1901">Increment added or subtracted by spinning the widget @@ -130899,7 +134024,7 @@ is not suitable for your needs, use Changes the properties of an existing spin button. + line="1800">Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly. @@ -130911,7 +134036,7 @@ are updated accordingly. a `GtkSpinButton` + line="1802">a `GtkSpinButton` allow-none="1"> a `GtkAdjustment` to replace the spin button’s + line="1803">a `GtkAdjustment` to replace the spin button’s existing adjustment, or %NULL to leave its current adjustment unchanged the new climb rate + line="1805">the new climb rate the number of decimal places to display in the spin button + line="1806">the number of decimal places to display in the spin button + + Retrieves the value set by [method@Gtk.SpinButton.set_activates_default]. + + + %TRUE if the spin button will activate the default widget + + + + + a `GtkSpinButton` + + + + - Get the adjustment associated with a `GtkSpinButton`. - + line="2019">Get the adjustment associated with a `GtkSpinButton`. + the `GtkAdjustment` of @spin_button + line="2025">the `GtkAdjustment` of @spin_button a `GtkSpinButton` + line="2021">a `GtkSpinButton` @@ -130964,22 +134111,21 @@ are updated accordingly. - Returns the acceleration rate for repeated changes. - + line="2449">Returns the acceleration rate for repeated changes. + the acceleration rate + line="2455">the acceleration rate a `GtkSpinButton` + line="2451">a `GtkSpinButton` @@ -130987,22 +134133,21 @@ are updated accordingly. - Fetches the precision of @spin_button. - + line="2062">Fetches the precision of @spin_button. + the current precision + line="2068">the current precision a `GtkSpinButton` + line="2064">a `GtkSpinButton` @@ -131011,11 +134156,11 @@ are updated accordingly. c:identifier="gtk_spin_button_get_increments"> Gets the current step and page the increments + line="2105">Gets the current step and page the increments used by @spin_button. See [method@Gtk.SpinButton.set_increments]. - + @@ -131023,7 +134168,7 @@ See [method@Gtk.SpinButton.set_increments]. a `GtkSpinButton` + line="2107">a `GtkSpinButton` allow-none="1"> location to store step increment + line="2108">location to store step increment allow-none="1"> location to store page increment + line="2109">location to store page increment @@ -131053,22 +134198,21 @@ See [method@Gtk.SpinButton.set_increments]. - Returns whether non-numeric text can be typed into the spin button. - + line="2321">Returns whether non-numeric text can be typed into the spin button. + %TRUE if only numeric text can be entered + line="2327">%TRUE if only numeric text can be entered a `GtkSpinButton` + line="2323">a `GtkSpinButton` @@ -131076,10 +134220,10 @@ See [method@Gtk.SpinButton.set_increments]. Gets the range allowed for @spin_button. + line="2160">Gets the range allowed for @spin_button. See [method@Gtk.SpinButton.set_range]. - + @@ -131087,7 +134231,7 @@ See [method@Gtk.SpinButton.set_range]. a `GtkSpinButton` + line="2162">a `GtkSpinButton` allow-none="1"> location to store minimum allowed value + line="2163">location to store minimum allowed value allow-none="1"> location to store maximum allowed value + line="2164">location to store maximum allowed value @@ -131117,22 +134261,21 @@ See [method@Gtk.SpinButton.set_range]. - Returns whether the values are corrected to the nearest step. - + line="2410">Returns whether the values are corrected to the nearest step. + %TRUE if values are snapped to the nearest step + line="2416">%TRUE if values are snapped to the nearest step a `GtkSpinButton` + line="2412">a `GtkSpinButton` @@ -131140,17 +134283,16 @@ See [method@Gtk.SpinButton.set_range]. - Gets the update behavior of a spin button. + line="2272">Gets the update behavior of a spin button. See [method@Gtk.SpinButton.set_update_policy]. - + the current update policy + line="2280">the current update policy @@ -131158,7 +134300,7 @@ See [method@Gtk.SpinButton.set_update_policy]. a `GtkSpinButton` + line="2274">a `GtkSpinButton` @@ -131166,22 +134308,21 @@ See [method@Gtk.SpinButton.set_update_policy]. - Get the value in the @spin_button. - + line="2183">Get the value in the @spin_button. + the value of @spin_button + line="2189">the value of @spin_button a `GtkSpinButton` + line="2185">a `GtkSpinButton` @@ -131190,19 +134331,19 @@ See [method@Gtk.SpinButton.set_update_policy]. c:identifier="gtk_spin_button_get_value_as_int"> Get the value @spin_button represented as an integer. - + line="2199">Get the value @spin_button represented as an integer. + the value of @spin_button + line="2205">the value of @spin_button a `GtkSpinButton` + line="2201">a `GtkSpinButton` @@ -131210,36 +134351,63 @@ See [method@Gtk.SpinButton.set_update_policy]. - Returns whether the spin button’s value wraps around to the + line="2363">Returns whether the spin button’s value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. - + %TRUE if the spin button wraps around + line="2371">%TRUE if the spin button wraps around a `GtkSpinButton` + line="2365">a `GtkSpinButton` + + + + + + Sets whether activating the spin button will activate the default +widget for the window containing the spin button. + +See [signal@Gtk.SpinButton::activate] for what counts as activation. + + + + + + + a `GtkSpinButton` + + %TRUE to activate window’s default widget on activation + + - Replaces the `GtkAdjustment` associated with @spin_button. - + line="1995">Replaces the `GtkAdjustment` associated with @spin_button. + @@ -131247,13 +134415,13 @@ exceeded. a `GtkSpinButton` + line="1997">a `GtkSpinButton` a `GtkAdjustment` to replace the existing adjustment + line="1998">a `GtkAdjustment` to replace the existing adjustment @@ -131261,12 +134429,11 @@ exceeded. - Sets the acceleration rate for repeated changes when you + line="2426">Sets the acceleration rate for repeated changes when you hold down a button or key. - + @@ -131274,13 +134441,13 @@ hold down a button or key. a `GtkSpinButton` + line="2428">a `GtkSpinButton` the rate of acceleration, must be >= 0 + line="2429">the rate of acceleration, must be >= 0 @@ -131288,13 +134455,12 @@ hold down a button or key. - Set the precision to be displayed by @spin_button. + line="2035">Set the precision to be displayed by @spin_button. Up to 20 digit precision is allowed. - + @@ -131302,13 +134468,13 @@ Up to 20 digit precision is allowed. a `GtkSpinButton` + line="2037">a `GtkSpinButton` the number of digits after the decimal point to be + line="2038">the number of digits after the decimal point to be displayed for the spin button’s value @@ -131318,11 +134484,11 @@ Up to 20 digit precision is allowed. c:identifier="gtk_spin_button_set_increments"> Sets the step and page increments for spin_button. + line="2078">Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button’s arrows are activated. - + @@ -131330,19 +134496,19 @@ the spin button’s arrows are activated. a `GtkSpinButton` + line="2080">a `GtkSpinButton` increment applied for a button 1 press. + line="2081">increment applied for a button 1 press. increment applied for a button 2 press. + line="2082">increment applied for a button 2 press. @@ -131350,12 +134516,11 @@ the spin button’s arrows are activated. - Sets the flag that determines if non-numeric text can be typed + line="2290">Sets the flag that determines if non-numeric text can be typed into the spin button. - + @@ -131363,13 +134528,13 @@ into the spin button. a `GtkSpinButton` + line="2292">a `GtkSpinButton` flag indicating if only numeric entry is allowed + line="2293">flag indicating if only numeric entry is allowed @@ -131377,11 +134542,11 @@ into the spin button. Sets the minimum and maximum allowable values for @spin_button. + line="2129">Sets the minimum and maximum allowable values for @spin_button. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. - + @@ -131389,19 +134554,19 @@ to fit within the range, otherwise it will remain unchanged. a `GtkSpinButton` + line="2131">a `GtkSpinButton` minimum allowable value + line="2132">minimum allowable value maximum allowable value + line="2133">maximum allowable value @@ -131409,13 +134574,12 @@ to fit within the range, otherwise it will remain unchanged. - Sets the policy as to whether values are corrected to the + line="2381">Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value. - + @@ -131423,13 +134587,13 @@ providing an invalid value. a `GtkSpinButton` + line="2383">a `GtkSpinButton` a flag indicating if invalid values should be corrected + line="2384">a flag indicating if invalid values should be corrected @@ -131437,14 +134601,13 @@ providing an invalid value. - Sets the update behavior of a spin button. + line="2249">Sets the update behavior of a spin button. This determines whether the spin button is always updated or only when a valid value is set. - + @@ -131452,13 +134615,13 @@ updated or only when a valid value is set. a `GtkSpinButton` + line="2251">a `GtkSpinButton` a `GtkSpinButtonUpdatePolicy` value + line="2252">a `GtkSpinButtonUpdatePolicy` value @@ -131467,11 +134630,10 @@ updated or only when a valid value is set. - Sets the value of @spin_button. - + line="2221">Sets the value of @spin_button. + @@ -131479,13 +134641,13 @@ updated or only when a valid value is set. a `GtkSpinButton` + line="2223">a `GtkSpinButton` the new value + line="2224">the new value @@ -131493,13 +134655,12 @@ updated or only when a valid value is set. - Sets the flag that determines if a spin button value wraps + line="2337">Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. - + @@ -131507,13 +134668,13 @@ of the range is exceeded. a `GtkSpinButton` + line="2339">a `GtkSpinButton` a flag indicating if wrapping behavior is performed + line="2340">a flag indicating if wrapping behavior is performed @@ -131521,9 +134682,9 @@ of the range is exceeded. Increment or decrement a spin button’s value in a specified + line="2465">Increment or decrement a spin button’s value in a specified direction by a specified amount. - + @@ -131531,19 +134692,19 @@ direction by a specified amount. a `GtkSpinButton` + line="2467">a `GtkSpinButton` a `GtkSpinType` indicating the direction to spin + line="2468">a `GtkSpinType` indicating the direction to spin step increment to apply in the specified direction + line="2469">step increment to apply in the specified direction @@ -131551,8 +134712,8 @@ direction by a specified amount. Manually force an update of the spin button. - + line="2543">Manually force an update of the spin button. + @@ -131560,23 +134721,33 @@ direction by a specified amount. a `GtkSpinButton` + line="2545">a `GtkSpinButton` + + Whether to activate the default widget when the spin button is activated. + +See [signal@Gtk.SpinButton::activate] for what counts as activation. + + - - The adjustment that holds the value of the spin button. + line="401">The adjustment that holds the value of the spin button. setter="set_climb_rate" getter="get_climb_rate" default-value="0.000000"> - - The acceleration rate when you hold down a button or key. + line="411">The acceleration rate when you hold down a button or key. setter="set_digits" getter="get_digits" default-value="0"> - - The number of decimal places to display. + line="421">The number of decimal places to display. setter="set_numeric" getter="get_numeric" default-value="FALSE"> - - Whether non-numeric characters should be ignored. + line="442">Whether non-numeric characters should be ignored. setter="set_snap_to_ticks" getter="get_snap_to_ticks" default-value="FALSE"> - - Whether erroneous values are automatically changed to the spin buttons + line="431">Whether erroneous values are automatically changed to the spin buttons nearest step increment. @@ -131646,13 +134801,9 @@ nearest step increment. setter="set_update_policy" getter="get_update_policy" default-value="GTK_UPDATE_ALWAYS"> - - Whether the spin button should update always, or only when the value + line="462">Whether the spin button should update always, or only when the value is acceptable. @@ -131662,13 +134813,9 @@ is acceptable. setter="set_value" getter="get_value" default-value="0.000000"> - - The current value. + line="474">The current value. setter="set_wrap" getter="get_wrap" default-value="FALSE"> - - Whether a spin button should wrap upon reaching its limits. + line="452">Whether a spin button should wrap upon reaching its limits. + + Emitted when the spin button is activated. + +The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. + +If the <kbd>Enter</kbd> key results in the value being committed to the +spin button, then activation does not occur until <kbd>Enter</kbd> is +pressed again. + + + + Emitted when the user initiates a value change. + line="615">Emitted when the user initiates a value change. This is a [keybinding signal](class.SignalAction.html). @@ -131705,7 +134862,7 @@ The default bindings for this signal are Up/Down and PageUp/PageDown. a `GtkScrollType` to specify the speed and amount of change + line="618">a `GtkScrollType` to specify the speed and amount of change @@ -131713,7 +134870,7 @@ The default bindings for this signal are Up/Down and PageUp/PageDown. Emitted to convert the users input into a double value. + line="489">Emitted to convert the users input into a double value. The signal handler is expected to use [method@Gtk.Editable.get_text] to retrieve the text of the spinbutton and set @new_value to the @@ -131723,7 +134880,7 @@ The default conversion uses g_strtod(). %TRUE for a successful conversion, %FALSE if the input + line="502">%TRUE for a successful conversion, %FALSE if the input was not handled, and %GTK_INPUT_ERROR if the conversion failed. @@ -131734,7 +134891,7 @@ The default conversion uses g_strtod(). transfer-ownership="full"> return location for the new value + line="492">return location for the new value @@ -131742,7 +134899,7 @@ The default conversion uses g_strtod(). Emitted to tweak the formatting of the value for display. + line="518">Emitted to tweak the formatting of the value for display. ```c // show leading zeros @@ -131750,12 +134907,10 @@ static gboolean on_output (GtkSpinButton *spin, gpointer data) { - GtkAdjustment *adjustment; char *text; int value; - adjustment = gtk_spin_button_get_adjustment (spin); - value = (int)gtk_adjustment_get_value (adjustment); + value = gtk_spin_button_get_value_as_int (spin); text = g_strdup_printf ("%02d", value); gtk_editable_set_text (GTK_EDITABLE (spin), text): g_free (text); @@ -131766,14 +134921,14 @@ on_output (GtkSpinButton *spin, %TRUE if the value has been displayed + line="542">%TRUE if the value has been displayed Emitted when the value is changed. + line="556">Emitted when the value is changed. Also see the [signal@Gtk.SpinButton::output] signal. @@ -131783,7 +134938,7 @@ Also see the [signal@Gtk.SpinButton::output] signal. Emitted right after the spinbutton wraps from its maximum + line="598">Emitted right after the spinbutton wraps from its maximum to its minimum value or vice-versa. @@ -131902,12 +135057,15 @@ change to make in gtk_spin_button_spin(). glib:get-type="gtk_spinner_get_type"> A `GtkSpinner` widget displays an icon-size spinning animation. + line="42">Displays an icon-size spinning animation. It is often used as an alternative to a [class@Gtk.ProgressBar] for displaying indefinite activity, instead of actual progress. -![An example GtkSpinner](spinner.png) +<picture> + <source srcset="spinner-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkSpinner" src="spinner.png"> +</picture> To start the animation, use [method@Gtk.Spinner.start], to stop it use [method@Gtk.Spinner.stop]. @@ -131923,34 +135081,33 @@ added to this node. Returns a new spinner widget. Not yet started. + line="274">Returns a new spinner widget. Not yet started. a new `GtkSpinner` + line="279">a new `GtkSpinner` - Returns whether the spinner is spinning. + line="165">Returns whether the spinner is spinning. %TRUE if the spinner is active + line="171">%TRUE if the spinner is active a `GtkSpinner` + line="167">a `GtkSpinner` @@ -131958,10 +135115,9 @@ added to this node. - Sets the activity of the spinner. + line="181">Sets the activity of the spinner. @@ -131970,13 +135126,13 @@ added to this node. a `GtkSpinner` + line="183">a `GtkSpinner` whether the spinner should be spinning + line="184">whether the spinner should be spinning @@ -131984,7 +135140,7 @@ added to this node. Starts the animation of the spinner. + line="287">Starts the animation of the spinner. @@ -131993,7 +135149,7 @@ added to this node. a `GtkSpinner` + line="289">a `GtkSpinner` @@ -132001,7 +135157,7 @@ added to this node. Stops the animation of the spinner. + line="301">Stops the animation of the spinner. @@ -132010,7 +135166,7 @@ added to this node. a `GtkSpinner` + line="303">a `GtkSpinner` @@ -132021,13 +135177,9 @@ added to this node. setter="set_spinning" getter="get_spinning" default-value="FALSE"> - - Whether the spinner is spinning + line="255">Whether the spinner is spinning @@ -132039,8 +135191,12 @@ added to this node. glib:get-type="gtk_stack_get_type"> `GtkStack` is a container which only shows one of its children -at a time. + line="39">Shows one of its children at a time. + +<picture> + <source srcset="stack-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkStack" src="stack.png"> +</picture> In contrast to `GtkNotebook`, `GtkStack` does not provide a means for users to change the visible child. Instead, a separate widget @@ -132084,7 +135240,7 @@ objects explicitly, and set the child widget as a property on it: # Accessibility -`GtkStack` uses the %GTK_ACCESSIBLE_ROLE_TAB_PANEL for the stack +`GtkStack` uses the [enum@Gtk.AccessibleRole.tab_panel] role for the stack pages, which are the accessible parent objects of the child widgets. @@ -132092,37 +135248,37 @@ pages, which are the accessible parent objects of the child widgets. Creates a new `GtkStack`. + line="1065">Creates a new `GtkStack`. a new `GtkStack` + line="1070">a new `GtkStack` Adds a child to @stack. + line="1611">Adds a child to @stack. the `GtkStackPage` for @child + line="1618">the `GtkStackPage` for @child a `GtkStack` + line="1613">a `GtkStack` the widget to add + line="1614">the widget to add @@ -132130,27 +135286,27 @@ pages, which are the accessible parent objects of the child widgets. Adds a child to @stack. + line="1630">Adds a child to @stack. The child is identified by the @name. the `GtkStackPage` for @child + line="1640">the `GtkStackPage` for @child a `GtkStack` + line="1632">a `GtkStack` the widget to add + line="1633">the widget to add allow-none="1"> the name for @child + line="1634">the name for @child @@ -132167,7 +135323,7 @@ The child is identified by the @name. Adds a child to @stack. + line="1584">Adds a child to @stack. The child is identified by the @name. The @title will be used by `GtkStackSwitcher` to represent @@ -132176,20 +135332,20 @@ will be used by `GtkStackSwitcher` to represent the `GtkStackPage` for @child + line="1597">the `GtkStackPage` for @child a `GtkStack` + line="1586">a `GtkStack` the widget to add + line="1587">the widget to add the name for @child + line="1588">the name for @child a human-readable title for @child + line="1589">a human-readable title for @child @@ -132213,14 +135369,14 @@ will be used by `GtkStackSwitcher` to represent c:identifier="gtk_stack_get_child_by_name"> Finds the child with the name given as the argument. + line="1832">Finds the child with the name given as the argument. Returns %NULL if there is no child with this name. the requested child + line="1841">the requested child of the `GtkStack` @@ -132228,13 +135384,13 @@ Returns %NULL if there is no child with this name. a `GtkStack` + line="1834">a `GtkStack` the name of the child to find + line="1835">the name of the child to find @@ -132242,22 +135398,21 @@ Returns %NULL if there is no child with this name. - Gets whether @stack is horizontally homogeneous. + line="1911">Gets whether @stack is horizontally homogeneous. whether @stack is horizontally homogeneous. + line="1917">whether @stack is horizontally homogeneous. a `GtkStack` + line="1913">a `GtkStack` @@ -132265,24 +135420,22 @@ Returns %NULL if there is no child with this name. - Returns whether the `GtkStack` is set up to interpolate between + line="2120">Returns whether the `GtkStack` is set up to interpolate between the sizes of children on page switch. %TRUE if child sizes are interpolated + line="2127">%TRUE if child sizes are interpolated A `GtkStack` + line="2122">A `GtkStack` @@ -132290,25 +135443,25 @@ the sizes of children on page switch. Returns the `GtkStackPage` object for @child. + line="1816">Returns the `GtkStackPage` object for @child. the `GtkStackPage` for @child + line="1823">the `GtkStackPage` for @child a `GtkStack` + line="1818">a `GtkStack` a child of @stack + line="1819">a child of @stack @@ -132316,10 +135469,9 @@ the sizes of children on page switch. - Returns a `GListModel` that contains the pages of the stack. + line="2911">Returns a `GListModel` that contains the pages of the stack. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track @@ -132328,14 +135480,14 @@ and modify the visible page. a `GtkSelectionModel` for the stack's children + line="2921">a `GtkSelectionModel` for the stack's children a `GtkStack` + line="2913">a `GtkStack` @@ -132343,24 +135495,22 @@ and modify the visible page. - Returns the amount of time (in milliseconds) that + line="1979">Returns the amount of time (in milliseconds) that transitions between pages in @stack will take. the transition duration + line="1986">the transition duration a `GtkStack` + line="1981">a `GtkStack` @@ -132368,24 +135518,22 @@ transitions between pages in @stack will take. - Returns whether the @stack is currently in a transition from one page to + line="2071">Returns whether the @stack is currently in a transition from one page to another. %TRUE if the transition is currently running, %FALSE otherwise. + line="2078">%TRUE if the transition is currently running, %FALSE otherwise. a `GtkStack` + line="2073">a `GtkStack` @@ -132393,23 +135541,22 @@ another. - Gets the type of animation that will be used + line="2022">Gets the type of animation that will be used for transitions between pages in @stack. the current transition type of @stack + line="2029">the current transition type of @stack a `GtkStack` + line="2024">a `GtkStack` @@ -132417,22 +135564,21 @@ for transitions between pages in @stack. - Gets whether @stack is vertically homogeneous. + line="1961">Gets whether @stack is vertically homogeneous. whether @stack is vertically homogeneous. + line="1967">whether @stack is vertically homogeneous. a `GtkStack` + line="1963">a `GtkStack` @@ -132440,24 +135586,23 @@ for transitions between pages in @stack. - Gets the currently visible child of @stack. + line="2140">Gets the currently visible child of @stack. Returns %NULL if there are no visible children. the visible child of the `GtkStack` + line="2148">the visible child of the `GtkStack` a `GtkStack` + line="2142">a `GtkStack` @@ -132465,18 +135610,16 @@ Returns %NULL if there are no visible children. - Returns the name of the currently visible child of @stack. + line="2160">Returns the name of the currently visible child of @stack. Returns %NULL if there is no visible child. the name of the visible child + line="2168">the name of the visible child of the `GtkStack` @@ -132484,7 +135627,7 @@ Returns %NULL if there is no visible child. a `GtkStack` + line="2162">a `GtkStack` @@ -132492,7 +135635,7 @@ Returns %NULL if there is no visible child. Removes a child widget from @stack. + line="1782">Removes a child widget from @stack. @@ -132501,13 +135644,13 @@ Returns %NULL if there is no visible child. a `GtkStack` + line="1784">a `GtkStack` the child to remove + line="1785">the child to remove @@ -132515,10 +135658,9 @@ Returns %NULL if there is no visible child. - Sets the `GtkStack` to be horizontally homogeneous or not. + line="1879">Sets the `GtkStack` to be horizontally homogeneous or not. If it is homogeneous, the `GtkStack` will request the same width for all its children. If it isn't, the stack @@ -132531,13 +135673,13 @@ may change width when a different child becomes visible. a `GtkStack` + line="1881">a `GtkStack` %TRUE to make @stack horizontally homogeneous + line="1882">%TRUE to make @stack horizontally homogeneous @@ -132545,11 +135687,9 @@ may change width when a different child becomes visible. - Sets whether or not @stack will interpolate its size when + line="2090">Sets whether or not @stack will interpolate its size when changing the visible child. If the [property@Gtk.Stack:interpolate-size] property is set @@ -132564,13 +135704,13 @@ according to the set transition duration. A `GtkStack` + line="2092">A `GtkStack` the new value + line="2093">the new value @@ -132578,11 +135718,9 @@ according to the set transition duration. - Sets the duration that transitions between pages in @stack + line="1998">Sets the duration that transitions between pages in @stack will take. @@ -132592,13 +135730,13 @@ will take. a `GtkStack` + line="2000">a `GtkStack` the new duration, in milliseconds + line="2001">the new duration, in milliseconds @@ -132606,10 +135744,9 @@ will take. - Sets the type of animation that will be used for + line="2041">Sets the type of animation that will be used for transitions between pages in @stack. Available types include various kinds of fades and slides. @@ -132625,13 +135762,13 @@ based on the page that is about to become current. a `GtkStack` + line="2043">a `GtkStack` the new transition type + line="2044">the new transition type @@ -132639,10 +135776,9 @@ based on the page that is about to become current. - Sets the `GtkStack` to be vertically homogeneous or not. + line="1929">Sets the `GtkStack` to be vertically homogeneous or not. If it is homogeneous, the `GtkStack` will request the same height for all its children. If it isn't, the stack @@ -132655,13 +135791,13 @@ may change height when a different child becomes visible. a `GtkStack` + line="1931">a `GtkStack` %TRUE to make @stack vertically homogeneous + line="1932">%TRUE to make @stack vertically homogeneous @@ -132669,10 +135805,9 @@ may change height when a different child becomes visible. - Makes @child the visible child of @stack. + line="2184">Makes @child the visible child of @stack. If @child is different from the currently visible child, the transition between the two will be animated with the @@ -132689,13 +135824,13 @@ child of @stack. a `GtkStack` + line="2186">a `GtkStack` a child of @stack + line="2187">a child of @stack @@ -132704,7 +135839,7 @@ child of @stack. c:identifier="gtk_stack_set_visible_child_full"> Makes the child with the given name visible. + line="2249">Makes the child with the given name visible. Note that the child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible @@ -132717,19 +135852,19 @@ child of @stack. a `GtkStack` + line="2251">a `GtkStack` the name of the child to make visible + line="2252">the name of the child to make visible the transition type to use + line="2253">the transition type to use @@ -132737,11 +135872,9 @@ child of @stack. - Makes the child with the given name visible. + line="2223">Makes the child with the given name visible. If @child is different from the currently visible child, the transition between the two will be animated with the @@ -132758,13 +135891,13 @@ child of @stack. a `GtkStack` + line="2225">a `GtkStack` the name of the child to make visible + line="2226">the name of the child to make visible @@ -132775,13 +135908,9 @@ child of @stack. setter="set_hhomogeneous" getter="get_hhomogeneous" default-value="TRUE"> - - %TRUE if the stack allocates the same width for all children. + line="969">%TRUE if the stack allocates the same width for all children. setter="set_interpolate_size" getter="get_interpolate_size" default-value="FALSE"> - - Whether or not the size should smoothly change during the transition. + line="1039">Whether or not the size should smoothly change during the transition. - A selection model with the stack pages. + line="1049">A selection model with the stack pages. setter="set_transition_duration" getter="get_transition_duration" default-value="200"> - - The animation duration, in milliseconds. + line="1009">The animation duration, in milliseconds. - Whether or not the transition is currently running. + line="1029">Whether or not the transition is currently running. setter="set_transition_type" getter="get_transition_type" default-value="GTK_STACK_TRANSITION_TYPE_NONE"> - - The type of animation used to transition. + line="1019">The type of animation used to transition. setter="set_vhomogeneous" getter="get_vhomogeneous" default-value="TRUE"> - - %TRUE if the stack allocates the same height for all children. + line="979">%TRUE if the stack allocates the same height for all children. transfer-ownership="none" setter="set_visible_child" getter="get_visible_child"> - - The widget currently visible in the stack. + line="989">The widget currently visible in the stack. setter="set_visible_child_name" getter="get_visible_child_name" default-value="NULL"> - - The name of the widget currently visible in the stack. + line="999">The name of the widget currently visible in the stack. @@ -132900,27 +136002,26 @@ child of @stack. glib:get-type="gtk_stack_page_get_type"> `GtkStackPage` is an auxiliary class used by `GtkStack`. + line="126">An auxiliary class used by `GtkStack`. - Returns the stack child to which @self belongs. + line="1865">Returns the stack child to which @self belongs. the child to which @self belongs + line="1871">the child to which @self belongs a `GtkStackPage` + line="1867">a `GtkStackPage` @@ -132928,22 +136029,21 @@ child of @stack. - Returns the icon name of the page. + line="3162">Returns the icon name of the page. The value of the [property@Gtk.StackPage:icon-name] property + line="3168">The value of the [property@Gtk.StackPage:icon-name] property a `GtkStackPage` + line="3164">a `GtkStackPage` @@ -132951,22 +136051,21 @@ child of @stack. - Returns the name of the page. + line="3054">Returns the name of the page. The value of the [property@Gtk.StackPage:name] property + line="3060">The value of the [property@Gtk.StackPage:name] property a `GtkStackPage` + line="3056">a `GtkStackPage` @@ -132974,15 +136073,14 @@ child of @stack. - Returns whether the page is marked as “needs attention”. + line="2984">Returns whether the page is marked as “needs attention”. The value of the [property@Gtk.StackPage:needs-attention] + line="2990">The value of the [property@Gtk.StackPage:needs-attention] property. @@ -132990,7 +136088,7 @@ child of @stack. a `GtkStackPage` + line="2986">a `GtkStackPage` @@ -132998,22 +136096,21 @@ child of @stack. - Gets the page title. + line="3121">Gets the page title. The value of the [property@Gtk.StackPage:title] property + line="3127">The value of the [property@Gtk.StackPage:title] property a `GtkStackPage` + line="3123">a `GtkStackPage` @@ -133021,22 +136118,21 @@ child of @stack. - Gets whether underlines in the page title indicate mnemonics. + line="3019">Gets whether underlines in the page title indicate mnemonics. The value of the [property@Gtk.StackPage:use-underline] property + line="3025">The value of the [property@Gtk.StackPage:use-underline] property a `GtkStackPage` + line="3021">a `GtkStackPage` @@ -133044,10 +136140,9 @@ child of @stack. - Returns whether @page is visible in its `GtkStack`. + line="2939">Returns whether @page is visible in its `GtkStack`. This is independent from the [property@Gtk.Widget:visible] property of its widget. @@ -133055,14 +136150,14 @@ property of its widget. %TRUE if @page is visible + line="2948">%TRUE if @page is visible a `GtkStackPage` + line="2941">a `GtkStackPage` @@ -133070,10 +136165,9 @@ property of its widget. - Sets the icon name of the page. + line="3178">Sets the icon name of the page. @@ -133082,13 +136176,13 @@ property of its widget. a `GtkStackPage` + line="3180">a `GtkStackPage` the new value to set + line="3181">the new value to set @@ -133096,10 +136190,9 @@ property of its widget. - Sets the name of the page. + line="3070">Sets the name of the page. @@ -133108,13 +136201,13 @@ property of its widget. a `GtkStackPage` + line="3072">a `GtkStackPage` the new value to set + line="3073">the new value to set @@ -133122,10 +136215,9 @@ property of its widget. - Sets whether the page is marked as “needs attention”. + line="2999">Sets whether the page is marked as “needs attention”. @@ -133134,13 +136226,13 @@ property of its widget. a `GtkStackPage` + line="3001">a `GtkStackPage` the new value to set + line="3002">the new value to set @@ -133148,10 +136240,9 @@ property of its widget. - Sets the page title. + line="3137">Sets the page title. @@ -133160,13 +136251,13 @@ property of its widget. a `GtkStackPage` + line="3139">a `GtkStackPage` the new value to set + line="3140">the new value to set @@ -133174,10 +136265,9 @@ property of its widget. - Sets whether underlines in the page title indicate mnemonics. + line="3033">Sets whether underlines in the page title indicate mnemonics. @@ -133186,13 +136276,13 @@ property of its widget. a `GtkStackPage` + line="3035">a `GtkStackPage` the new value to set + line="3036">the new value to set @@ -133200,10 +136290,9 @@ property of its widget. - Sets whether @page is visible in its `GtkStack`. + line="2958">Sets whether @page is visible in its `GtkStack`. @@ -133212,13 +136301,13 @@ property of its widget. a `GtkStackPage` + line="2960">a `GtkStackPage` The new property value + line="2961">The new property value @@ -133228,11 +136317,9 @@ property of its widget. construct-only="1" transfer-ownership="none" getter="get_child"> - The child that this page is for. + line="498">The child that this page is for. setter="set_icon_name" getter="get_icon_name" default-value="NULL"> - - The icon name of the child page. + line="528">The icon name of the child page. setter="set_name" getter="get_name" default-value="NULL"> - - The name of the child page. + line="508">The name of the child page. setter="set_needs_attention" getter="get_needs_attention" default-value="FALSE"> - - Whether the page requires the user attention. + line="538">Whether the page requires the user attention. This is used by the [class@Gtk.StackSwitcher] to change the appearance of the corresponding button when a page needs @@ -133290,13 +136365,9 @@ attention and it is not the current one. setter="set_title" getter="get_title" default-value="NULL"> - - The title of the child page. + line="518">The title of the child page. setter="set_use_underline" getter="get_use_underline" default-value="FALSE"> - - If set, an underline in the title indicates a mnemonic. + line="562">If set, an underline in the title indicates a mnemonic. setter="set_visible" getter="get_visible" default-value="TRUE"> - - Whether this page is visible. + line="552">Whether this page is visible. @@ -133338,7 +136401,12 @@ attention and it is not the current one. glib:get-type="gtk_stack_sidebar_get_type"> A `GtkStackSidebar` uses a sidebar to switch between `GtkStack` pages. + line="38">Uses a sidebar to switch between `GtkStack` pages. + +<picture> + <source srcset="sidebar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkStackSidebar" src="sidebar.png"> +</picture> In order to use a `GtkStackSidebar`, you simply use a `GtkStack` to organize your UI flow, and add the sidebar to your sidebar area. You @@ -133359,27 +136427,26 @@ pages. Creates a new `GtkStackSidebar`. + line="398">Creates a new `GtkStackSidebar`. the new `GtkStackSidebar` + line="403">the new `GtkStackSidebar` - Retrieves the stack. + line="440">Retrieves the stack. the associated `GtkStack` or + line="446">the associated `GtkStack` or %NULL if none has been set explicitly @@ -133387,7 +136454,7 @@ pages. a `GtkStackSidebar` + line="442">a `GtkStackSidebar` @@ -133395,10 +136462,9 @@ pages. - Set the `GtkStack` associated with this `GtkStackSidebar`. + line="411">Set the `GtkStack` associated with this `GtkStackSidebar`. The sidebar widget will automatically update according to the order and items within the given `GtkStack`. @@ -133410,13 +136476,13 @@ the order and items within the given `GtkStack`. a `GtkStackSidebar` + line="413">a `GtkStackSidebar` a `GtkStack` + line="414">a `GtkStack` @@ -133426,13 +136492,9 @@ the order and items within the given `GtkStack`. transfer-ownership="none" setter="set_stack" getter="get_stack"> - - The stack. + line="382">The stack. @@ -133444,10 +136506,12 @@ the order and items within the given `GtkStack`. glib:get-type="gtk_stack_switcher_get_type"> The `GtkStackSwitcher` shows a row of buttons to switch between `GtkStack` -pages. + line="35">Shows a row of buttons to switch between `GtkStack` pages. -![An example GtkStackSwitcher](stackswitcher.png) +<picture> + <source srcset="stackswitcher-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkStackSwitcher" src="stackswitcher.png"> +</picture> It acts as a controller for the associated `GtkStack`. @@ -133469,8 +136533,8 @@ stack pages. # Accessibility -`GtkStackSwitcher` uses the %GTK_ACCESSIBLE_ROLE_TAB_LIST role -and uses the %GTK_ACCESSIBLE_ROLE_TAB for its buttons. +`GtkStackSwitcher` uses the [enum@Gtk.AccessibleRole.tab_list] role +and uses the [enum@Gtk.AccessibleRole.tab] role for its buttons. # Orientable @@ -133484,34 +136548,33 @@ the stack switcher to be made vertical with Create a new `GtkStackSwitcher`. + line="565">Create a new `GtkStackSwitcher`. a new `GtkStackSwitcher`. + line="570">a new `GtkStackSwitcher`. - Retrieves the stack. + line="441">Retrieves the stack. the stack + line="447">the stack a `GtkStackSwitcher` + line="443">a `GtkStackSwitcher` @@ -133519,10 +136582,9 @@ the stack switcher to be made vertical with - Sets the stack to control. + line="416">Sets the stack to control. @@ -133531,7 +136593,7 @@ the stack switcher to be made vertical with a `GtkStackSwitcher` + line="418">a `GtkStackSwitcher` a `GtkStack` + line="419">a `GtkStack` @@ -133551,13 +136613,9 @@ the stack switcher to be made vertical with transfer-ownership="none" setter="set_stack" getter="get_stack"> - - The stack. + line="546">The stack. @@ -133567,7 +136625,7 @@ the stack switcher to be made vertical with c:type="GtkStackTransitionType"> Possible transitions between pages in a `GtkStack` widget. + line="95">Possible transitions between pages in a `GtkStack` widget. New values may be added to this enumeration over time. glib:name="GTK_STACK_TRANSITION_TYPE_NONE"> No transition + line="97">No transition glib:name="GTK_STACK_TRANSITION_TYPE_CROSSFADE"> A cross-fade + line="98">A cross-fade glib:name="GTK_STACK_TRANSITION_TYPE_SLIDE_RIGHT"> Slide from left to right + line="99">Slide from left to right glib:name="GTK_STACK_TRANSITION_TYPE_SLIDE_LEFT"> Slide from right to left + line="100">Slide from right to left glib:name="GTK_STACK_TRANSITION_TYPE_SLIDE_UP"> Slide from bottom up + line="101">Slide from bottom up glib:name="GTK_STACK_TRANSITION_TYPE_SLIDE_DOWN"> Slide from top down + line="102">Slide from top down glib:name="GTK_STACK_TRANSITION_TYPE_SLIDE_LEFT_RIGHT"> Slide from left or right according to the children order + line="103">Slide from left or right according to the children order glib:name="GTK_STACK_TRANSITION_TYPE_SLIDE_UP_DOWN"> Slide from top down or bottom up according to the order + line="104">Slide from top down or bottom up according to the order glib:name="GTK_STACK_TRANSITION_TYPE_OVER_UP"> Cover the old page by sliding up + line="105">Cover the old page by sliding up glib:name="GTK_STACK_TRANSITION_TYPE_OVER_DOWN"> Cover the old page by sliding down + line="106">Cover the old page by sliding down glib:name="GTK_STACK_TRANSITION_TYPE_OVER_LEFT"> Cover the old page by sliding to the left + line="107">Cover the old page by sliding to the left glib:name="GTK_STACK_TRANSITION_TYPE_OVER_RIGHT"> Cover the old page by sliding to the right + line="108">Cover the old page by sliding to the right glib:name="GTK_STACK_TRANSITION_TYPE_UNDER_UP"> Uncover the new page by sliding up + line="109">Uncover the new page by sliding up glib:name="GTK_STACK_TRANSITION_TYPE_UNDER_DOWN"> Uncover the new page by sliding down + line="110">Uncover the new page by sliding down glib:name="GTK_STACK_TRANSITION_TYPE_UNDER_LEFT"> Uncover the new page by sliding to the left + line="111">Uncover the new page by sliding to the left glib:name="GTK_STACK_TRANSITION_TYPE_UNDER_RIGHT"> Uncover the new page by sliding to the right + line="112">Uncover the new page by sliding to the right glib:name="GTK_STACK_TRANSITION_TYPE_OVER_UP_DOWN"> Cover the old page sliding up or uncover the new page sliding down, according to order + line="113">Cover the old page sliding up or uncover the new page sliding down, according to order glib:name="GTK_STACK_TRANSITION_TYPE_OVER_DOWN_UP"> Cover the old page sliding down or uncover the new page sliding up, according to order + line="114">Cover the old page sliding down or uncover the new page sliding up, according to order glib:name="GTK_STACK_TRANSITION_TYPE_OVER_LEFT_RIGHT"> Cover the old page sliding left or uncover the new page sliding right, according to order + line="115">Cover the old page sliding left or uncover the new page sliding right, according to order glib:name="GTK_STACK_TRANSITION_TYPE_OVER_RIGHT_LEFT"> Cover the old page sliding right or uncover the new page sliding left, according to order + line="116">Cover the old page sliding right or uncover the new page sliding left, according to order glib:name="GTK_STACK_TRANSITION_TYPE_ROTATE_LEFT"> Pretend the pages are sides of a cube and rotate that cube to the left + line="117">Pretend the pages are sides of a cube and rotate that cube to the left glib:name="GTK_STACK_TRANSITION_TYPE_ROTATE_RIGHT"> Pretend the pages are sides of a cube and rotate that cube to the right + line="118">Pretend the pages are sides of a cube and rotate that cube to the right glib:name="GTK_STACK_TRANSITION_TYPE_ROTATE_LEFT_RIGHT"> Pretend the pages are sides of a cube and rotate that cube to the left or right according to the children order + line="119">Pretend the pages are sides of a cube and rotate that cube to the left or right according to the children order c:type="GtkStateFlags"> Describes a widget state. + line="832">Describes a widget state. Widget states are used to match the widget against CSS pseudo-classes. Note that GTK extends the regular CSS classes and sometimes uses @@ -133796,7 +136854,7 @@ different names. glib:name="GTK_STATE_FLAG_NORMAL"> State during normal operation + line="834">State during normal operation glib:name="GTK_STATE_FLAG_ACTIVE"> Widget is active + line="835">Widget is active glib:name="GTK_STATE_FLAG_PRELIGHT"> Widget has a mouse pointer over it + line="836">Widget has a mouse pointer over it glib:name="GTK_STATE_FLAG_SELECTED"> Widget is selected + line="837">Widget is selected glib:name="GTK_STATE_FLAG_INSENSITIVE"> Widget is insensitive + line="838">Widget is insensitive glib:name="GTK_STATE_FLAG_INCONSISTENT"> Widget is inconsistent + line="839">Widget is inconsistent glib:name="GTK_STATE_FLAG_FOCUSED"> Widget has the keyboard focus + line="840">Widget has the keyboard focus glib:name="GTK_STATE_FLAG_BACKDROP"> Widget is in a background toplevel window + line="841">Widget is in a background toplevel window glib:name="GTK_STATE_FLAG_DIR_LTR"> Widget is in left-to-right text direction + line="842">Widget is in left-to-right text direction glib:name="GTK_STATE_FLAG_DIR_RTL"> Widget is in right-to-left text direction + line="843">Widget is in right-to-left text direction glib:name="GTK_STATE_FLAG_LINK"> Widget is a link + line="844">Widget is a link glib:name="GTK_STATE_FLAG_VISITED"> The location the widget points to has already been visited + line="845">The location the widget points to has already been visited glib:name="GTK_STATE_FLAG_CHECKED"> Widget is checked + line="846">Widget is checked glib:name="GTK_STATE_FLAG_DROP_ACTIVE"> Widget is highlighted as a drop target for DND + line="847">Widget is highlighted as a drop target for DND glib:name="GTK_STATE_FLAG_FOCUS_VISIBLE"> Widget has the visible focus + line="848">Widget has the visible focus glib:name="GTK_STATE_FLAG_FOCUS_WITHIN"> Widget contains the keyboard focus + line="849">Widget contains the keyboard focus line="41">A `GtkStatusbar` widget is usually placed along the bottom of an application's main [class@Gtk.Window]. -![An example GtkStatusbar](statusbar.png) +picture> + <source srcset="statusbar-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkStatusbar" src="statusbar.png"> +</picture> A `GtkStatusBar` may provide a regular commentary of the application's status (as is usually the case in a web browser, for example), or may be @@ -133990,13 +137051,13 @@ using [method@Gtk.Statusbar.remove]. deprecated-version="4.10"> Creates a new `GtkStatusbar` ready for messages. + line="231">Creates a new `GtkStatusbar` ready for messages. This widget will be removed in GTK 5 the new `GtkStatusbar` + line="236">the new `GtkStatusbar` @@ -134006,7 +137067,7 @@ using [method@Gtk.Statusbar.remove]. deprecated-version="4.10"> Returns a new context identifier, given a description + line="259">Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI. @@ -134015,20 +137076,20 @@ Note that the description is not shown in the UI. an integer id + line="270">an integer id a `GtkStatusbar` + line="261">a `GtkStatusbar` textual description of what context + line="262">textual description of what context the new message is being used in @@ -134040,7 +137101,7 @@ Note that the description is not shown in the UI. deprecated-version="4.10"> Removes the first message in the `GtkStatusbar`’s stack + line="358">Removes the first message in the `GtkStatusbar`’s stack with the given context id. Note that this may not change the displayed message, @@ -134055,13 +137116,13 @@ context id. a `GtkStatusbar` + line="360">a `GtkStatusbar` a context identifier + line="361">a context identifier @@ -134072,13 +137133,13 @@ context id. deprecated-version="4.10"> Pushes a new message onto a statusbar’s stack. + line="322">Pushes a new message onto a statusbar’s stack. This widget will be removed in GTK 5 a message id that can be used with + line="331">a message id that can be used with [method@Gtk.Statusbar.remove]. @@ -134086,20 +137147,20 @@ context id. a `GtkStatusbar` + line="324">a `GtkStatusbar` the message’s context id, as returned by + line="325">the message’s context id, as returned by gtk_statusbar_get_context_id() the message to add to the statusbar + line="327">the message to add to the statusbar @@ -134110,7 +137171,7 @@ context id. deprecated-version="4.10"> Forces the removal of a message from a statusbar’s stack. + line="407">Forces the removal of a message from a statusbar’s stack. The exact @context_id and @message_id must be specified. This widget will be removed in GTK 5 @@ -134121,19 +137182,19 @@ The exact @context_id and @message_id must be specified. a `GtkStatusbar` + line="409">a `GtkStatusbar` a context identifier + line="410">a context identifier a message identifier, as returned by [method@Gtk.Statusbar.push] + line="411">a message identifier, as returned by [method@Gtk.Statusbar.push] @@ -134144,7 +137205,7 @@ The exact @context_id and @message_id must be specified. deprecated-version="4.10"> Forces the removal of all messages from a statusbar's + line="458">Forces the removal of all messages from a statusbar's stack with the exact @context_id. This widget will be removed in GTK 5 @@ -134155,13 +137216,13 @@ stack with the exact @context_id. a `GtkStatusbar` + line="460">a `GtkStatusbar` a context identifier + line="461">a context identifier @@ -134172,7 +137233,7 @@ stack with the exact @context_id. deprecated-version="4.10"> Emitted whenever a new message is popped off a statusbar's stack. + line="189">Emitted whenever a new message is popped off a statusbar's stack. This widget will be removed in GTK 5 @@ -134181,13 +137242,13 @@ stack with the exact @context_id. the context id of the relevant message/statusbar + line="192">the context id of the relevant message/statusbar the message that was just popped + line="193">the message that was just popped @@ -134198,7 +137259,7 @@ stack with the exact @context_id. deprecated-version="4.10"> Emitted whenever a new message gets pushed onto a statusbar's stack. + line="168">Emitted whenever a new message gets pushed onto a statusbar's stack. This widget will be removed in GTK 5 @@ -134207,13 +137268,13 @@ stack with the exact @context_id. the context id of the relevant message/statusbar + line="171">the context id of the relevant message/statusbar the message that was pushed + line="172">the message that was pushed @@ -134228,10 +137289,9 @@ stack with the exact @context_id. glib:type-struct="StringFilterClass"> `GtkStringFilter` determines whether to include items by comparing -strings to a fixed search term. + line="26">Determines whether to include items by comparing strings to a fixed search term. -The strings are obtained from the items by evaluating a `GtkExpression` +The strings are obtained from the items by evaluating an expression set with [method@Gtk.StringFilter.set_expression], and they are compared against a search term set with [method@Gtk.StringFilter.set_search]. @@ -134263,7 +137323,7 @@ and by providing a property to look up on the item. allow-none="1"> The expression to evaluate + line="302">the expression to evaluate @@ -134271,23 +137331,22 @@ and by providing a property to look up on the item. - Gets the expression that the string filter uses to + line="381">Gets the expression that the string filter uses to obtain strings from items. a `GtkExpression` + line="388">the expression a `GtkStringFilter` + line="383">a string filter @@ -134295,22 +137354,21 @@ obtain strings from items. - Returns whether the filter ignores case differences. + line="427">Returns whether the filter ignores case differences. %TRUE if the filter ignores case + line="433">true if the filter ignores case a `GtkStringFilter` + line="429">a string filter @@ -134318,15 +137376,14 @@ obtain strings from items. - Returns the match mode that the filter is using. + line="471">Returns the match mode that the filter is using. the match mode of the filter + line="477">the match mode of the filter @@ -134334,7 +137391,7 @@ obtain strings from items. a `GtkStringFilter` + line="473">a string filter @@ -134342,7 +137399,6 @@ obtain strings from items. - Gets the search term. @@ -134350,14 +137406,14 @@ obtain strings from items. The search term + line="331">the search term a `GtkStringFilter` + line="327">a string filter @@ -134365,13 +137421,12 @@ obtain strings from items. - Sets the expression that the string filter uses to + line="398">Sets the expression that the string filter uses to obtain strings from items. -The expression must have a value type of %G_TYPE_STRING. +The expression must have a value type of `G_TYPE_STRING`. @@ -134380,7 +137435,7 @@ The expression must have a value type of %G_TYPE_STRING. a `GtkStringFilter` + line="400">a string filter allow-none="1"> a `GtkExpression` + line="401">the expression @@ -134397,10 +137452,9 @@ The expression must have a value type of %G_TYPE_STRING. - Sets whether the filter ignores case differences. + line="443">Sets whether the filter ignores case differences. @@ -134409,13 +137463,13 @@ The expression must have a value type of %G_TYPE_STRING. a `GtkStringFilter` + line="445">a string filter %TRUE to ignore case + line="446">true to ignore case @@ -134423,10 +137477,9 @@ The expression must have a value type of %G_TYPE_STRING. - Sets the match mode for the filter. + line="487">Sets the match mode for the filter. @@ -134435,13 +137488,13 @@ The expression must have a value type of %G_TYPE_STRING. a `GtkStringFilter` + line="489">a string filter the new match mode + line="490">the new match mode @@ -134450,7 +137503,6 @@ The expression must have a value type of %G_TYPE_STRING. - Sets the string to search for. @@ -134462,7 +137514,7 @@ The expression must have a value type of %G_TYPE_STRING. a `GtkStringFilter` + line="343">a string filter allow-none="1"> The string to search for - or %NULL to clear the search + line="344">the string to search for @@ -134482,13 +137533,10 @@ The expression must have a value type of %G_TYPE_STRING. transfer-ownership="none" setter="set_expression" getter="get_expression"> - - The expression to evaluate on item to get a string to compare with. + line="248">The expression to evaluate on each item to get a +string to compare with. setter="set_ignore_case" getter="get_ignore_case" default-value="TRUE"> - - If matching is case sensitive. @@ -134512,10 +137556,6 @@ The expression must have a value type of %G_TYPE_STRING. setter="set_match_mode" getter="get_match_mode" default-value="GTK_STRING_FILTER_MATCH_MODE_SUBSTRING"> - - If exact matches are necessary or if substrings are allowed. @@ -134527,10 +137567,6 @@ The expression must have a value type of %G_TYPE_STRING. setter="set_search" getter="get_search" default-value="NULL"> - - The search term. @@ -134560,7 +137596,7 @@ The expression must have a value type of %G_TYPE_STRING. The search string and - text must match exactly. + text must match exactly The search string - must be contained as a substring inside the text. + must be contained as a substring inside the text The text must begin - with the search string. + with the search string glib:type-struct="StringListClass"> `GtkStringList` is a list model that wraps an array of strings. + line="28">A list model that wraps an array of strings. The objects in the model are of type [class@Gtk.StringObject] and have a "string" property that can be used inside expressions. @@ -134625,12 +137661,12 @@ Here is a UI definition fragment specifying a `GtkStringList` Creates a new `GtkStringList` with the given @strings. + line="540">Creates a new `GtkStringList` with the given @strings. a new `GtkStringList` + line="546">a new `GtkStringList` @@ -134640,7 +137676,7 @@ Here is a UI definition fragment specifying a `GtkStringList` allow-none="1"> The strings to put in the model + line="542">The strings to put in the model @@ -134650,7 +137686,7 @@ Here is a UI definition fragment specifying a `GtkStringList` Appends @string to @self. + line="607">Appends @string to @self. The @string will be copied. See [method@Gtk.StringList.take] for a way to avoid that. @@ -134662,13 +137698,41 @@ The @string will be copied. See a `GtkStringList` + line="609">a `GtkStringList` + + + + the string to insert + + + + + + Gets the position of the @string in @self. + +If @self does not contain @string item, `G_MAXUINT` is returned. + + + the position of the string + + + + + a `GtkStringList` the string to insert + line="704">the string to find @@ -134676,7 +137740,7 @@ The @string will be copied. See Gets the string that is at @position in @self. + line="675">Gets the string that is at @position in @self. If @self does not contain @position items, %NULL is returned. @@ -134686,20 +137750,20 @@ object wrapping it, use g_list_model_get_item(). the string at the given position + line="687">the string at the given position a `GtkStringList` + line="677">a `GtkStringList` the position to get the string for + line="678">the position to get the string for @@ -134707,7 +137771,7 @@ object wrapping it, use g_list_model_get_item(). Removes the string at @position from @self. + line="656">Removes the string at @position from @self. @position must be smaller than the current length of the list. @@ -134719,13 +137783,13 @@ length of the list. a `GtkStringList` + line="658">a `GtkStringList` the position of the string that is to be removed + line="659">the position of the string that is to be removed @@ -134733,7 +137797,7 @@ length of the list. Changes @self by removing @n_removals strings and adding @additions + line="556">Changes @self by removing @n_removals strings and adding @additions to it. This function is more efficient than [method@Gtk.StringList.append] @@ -134753,19 +137817,19 @@ of the list at the time this function is called). a `GtkStringList` + line="558">a `GtkStringList` the position at which to make the change + line="559">the position at which to make the change the number of strings to remove + line="560">the number of strings to remove allow-none="1"> The strings to add + line="561">The strings to add @@ -134784,7 +137848,7 @@ of the list at the time this function is called). Adds @string to self at the end, and takes + line="629">Adds @string to self at the end, and takes ownership of it. This variant of [method@Gtk.StringList.append] @@ -134801,23 +137865,41 @@ gtk_string_list_take (self, g_strdup_print ("%d dollars", lots)); a `GtkStringList` + line="631">a `GtkStringList` the string to insert + line="632">the string to insert + + The type of items. See [method@Gio.ListModel.get_item_type]. + + + + The number of items. See [method@Gio.ListModel.get_n_items]. + + + The strings in the model. @@ -134840,7 +137922,7 @@ gtk_string_list_take (self, g_strdup_print ("%d dollars", lots)); glib:type-struct="StringObjectClass"> `GtkStringObject` is the type of items in a `GtkStringList`. + line="62">The type of items in a `GtkStringList`. A `GtkStringObject` is a wrapper around a `const char*`; it has a [property@Gtk.StringObject:string] property that can be used @@ -134869,7 +137951,6 @@ for property bindings and expressions. - Returns the string contained in a `GtkStringObject`. @@ -134893,8 +137974,6 @@ for property bindings and expressions. transfer-ownership="none" getter="get_string" default-value="NULL"> - The string. @@ -134918,14 +137997,14 @@ for property bindings and expressions. glib:type-struct="StringSorterClass"> `GtkStringSorter` is a `GtkSorter` that compares strings. + line="27">Sorts items by comparing strings. + +To obtain the strings to compare, this sorter evaluates a +[class@Gtk.Expression]. It does the comparison in a linguistically correct way using the current locale by normalizing Unicode strings and possibly case-folding -them before performing the comparison. - -To obtain the strings to compare, this sorter evaluates a -[class@Gtk.Expression]. +them before performing the comparison. c:identifier="gtk_string_sorter_get_collation" glib:get-property="collation" version="4.10"> - Gets which collation method the sorter uses. @@ -134981,7 +138059,6 @@ compare items as invalid. - Gets the expression that is evaluated to obtain strings from items. @@ -135004,7 +138081,6 @@ compare items as invalid. - Gets whether the sorter ignores case differences. @@ -135028,7 +138104,6 @@ compare items as invalid. c:identifier="gtk_string_sorter_set_collation" glib:set-property="collation" version="4.10"> - Sets the collation method to use for sorting. @@ -135054,7 +138129,6 @@ compare items as invalid. - Sets the expression that is evaluated to obtain strings from items. @@ -135085,7 +138159,6 @@ The expression must have the type %G_TYPE_STRING. - Sets whether the sorter will ignore case differences. @@ -135115,10 +138188,6 @@ The expression must have the type %G_TYPE_STRING. setter="set_collation" getter="get_collation" default-value="GTK_COLLATION_UNICODE"> - - The collation method to use for sorting. @@ -135135,10 +138204,6 @@ to the [Unicode collation algorithm](https://www.unicode.org/reports/tr10/). - - The expression to evaluate on item to get a string to compare with. @@ -135150,10 +138215,6 @@ to the [Unicode collation algorithm](https://www.unicode.org/reports/tr10/). - - If sorting is case sensitive. @@ -135224,7 +138285,7 @@ still take precedence over your changes, as it uses the c:identifier="gtk_style_context_add_provider_for_display"> Adds a global style provider to @display, which will be used + line="190">Adds a global style provider to @display, which will be used in style construction for all `GtkStyleContexts` under @display. GTK uses this to make styling information from `GtkSettings` @@ -135241,19 +138302,19 @@ precedence over another added through this function. a `GdkDisplay` + line="192">a `GdkDisplay` a `GtkStyleProvider` + line="193">a `GtkStyleProvider` the priority of the style provider. The lower + line="194">the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and @@ -135266,7 +138327,7 @@ precedence over another added through this function. c:identifier="gtk_style_context_remove_provider_for_display"> Removes @provider from the global style providers list in @display. + line="225">Removes @provider from the global style providers list in @display. @@ -135275,13 +138336,13 @@ precedence over another added through this function. a `GdkDisplay` + line="227">a `GdkDisplay` a `GtkStyleProvider` + line="228">a `GtkStyleProvider` @@ -135304,7 +138365,7 @@ precedence over another added through this function. deprecated-version="4.10"> Adds a style class to @context, so later uses of the + line="607">Adds a style class to @context, so later uses of the style context will make use of this new class for styling. In the CSS file format, a `GtkEntry` defining a “search” @@ -135329,13 +138390,13 @@ matched by: a `GtkStyleContext` + line="609">a `GtkStyleContext` class name to use in styling + line="610">class name to use in styling @@ -135346,7 +138407,7 @@ matched by: deprecated-version="4.10"> Adds a style provider to @context, to be used in style construction. + line="335">Adds a style provider to @context, to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which @context belongs. If you want @@ -135366,19 +138427,19 @@ through [func@Gtk.StyleContext.add_provider_for_display]. a `GtkStyleContext` + line="337">a `GtkStyleContext` a `GtkStyleProvider` + line="338">a `GtkStyleProvider` the priority of the style provider. The lower + line="339">the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and @@ -135393,7 +138454,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. deprecated-version="4.10"> Gets the border for a given state as a `GtkBorder`. + line="853">Gets the border for a given state as a `GtkBorder`. This api will be removed in GTK 5 @@ -135404,7 +138465,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. a `GtkStyleContext` + line="855">a `GtkStyleContext` transfer-ownership="none"> return value for the border settings + line="856">return value for the border settings @@ -135424,7 +138485,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. deprecated-version="4.10"> Gets the foreground color for a given state. + line="834">Gets the foreground color for a given state. Use [method@Gtk.Widget.get_color] instead @@ -135435,7 +138496,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. a `GtkStyleContext` + line="836">a `GtkStyleContext` transfer-ownership="none"> return value for the foreground color + line="837">return value for the foreground color @@ -135456,21 +138517,21 @@ through [func@Gtk.StyleContext.add_provider_for_display]. deprecated-version="4.10"> Returns the `GdkDisplay` to which @context is attached. + line="754">Returns the `GdkDisplay` to which @context is attached. Use [method@Gtk.Widget.get_display] instead a `GdkDisplay`. + line="760">a `GdkDisplay`. a `GtkStyleContext` + line="756">a `GtkStyleContext` @@ -135481,7 +138542,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. deprecated-version="4.10"> Gets the margin for a given state as a `GtkBorder`. + line="905">Gets the margin for a given state as a `GtkBorder`. This api will be removed in GTK 5 @@ -135492,7 +138553,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. a `GtkStyleContext` + line="907">a `GtkStyleContext` transfer-ownership="none"> return value for the margin settings + line="908">return value for the margin settings @@ -135512,7 +138573,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. deprecated-version="4.10"> Gets the padding for a given state as a `GtkBorder`. + line="879">Gets the padding for a given state as a `GtkBorder`. This api will be removed in GTK 5 @@ -135523,7 +138584,7 @@ through [func@Gtk.StyleContext.add_provider_for_display]. a `GtkStyleContext` + line="881">a `GtkStyleContext` transfer-ownership="none"> return value for the padding settings + line="882">return value for the padding settings - + Returns the scale used for assets. + line="490">Returns the scale used for assets. + Use [method@Gtk.Widget.get_scale_factor] instead the scale - -Deprecated 4.10: Use [method@Gtk.Widget.get_scale_factor] instead + line="496">the scale a `GtkStyleContext` + line="492">a `GtkStyleContext` @@ -135566,7 +138629,7 @@ Deprecated 4.10: Use [method@Gtk.Widget.get_scale_factor] instead deprecated-version="4.10"> Returns the state used for style matching. + line="430">Returns the state used for style matching. This method should only be used to retrieve the `GtkStateFlags` to pass to `GtkStyleContext` methods, like @@ -135579,14 +138642,14 @@ If you need to retrieve the current state of a `GtkWidget`, use the state flags + line="442">the state flags a `GtkStyleContext` + line="432">a `GtkStyleContext` @@ -135597,7 +138660,7 @@ If you need to retrieve the current state of a `GtkWidget`, use deprecated-version="4.10"> Returns %TRUE if @context currently has defined the + line="670">Returns %TRUE if @context currently has defined the given class name. Use [method@Gtk.Widget.has_css_class] instead %TRUE if @context has @class_name defined + line="678">%TRUE if @context has @class_name defined a `GtkStyleContext` + line="672">a `GtkStyleContext` a class name + line="673">a class name @@ -135629,27 +138692,27 @@ given class name. deprecated-version="4.10"> Looks up and resolves a color name in the @context color map. + line="803">Looks up and resolves a color name in the @context color map. This api will be removed in GTK 5 %TRUE if @color_name was found and resolved, %FALSE otherwise + line="811">%TRUE if @color_name was found and resolved, %FALSE otherwise a `GtkStyleContext` + line="805">a `GtkStyleContext` color name to lookup + line="806">color name to lookup transfer-ownership="none"> Return location for the looked up color + line="807">Return location for the looked up color @@ -135669,7 +138732,7 @@ given class name. deprecated-version="4.10"> Removes @class_name from @context. + line="644">Removes @class_name from @context. Use [method@Gtk.Widget.remove_css_class] instead @@ -135680,13 +138743,13 @@ given class name. a `GtkStyleContext` + line="646">a `GtkStyleContext` class name to remove + line="647">class name to remove @@ -135697,7 +138760,7 @@ given class name. deprecated-version="4.10"> Removes @provider from the style providers list in @context. + line="386">Removes @provider from the style providers list in @context. @@ -135707,13 +138770,13 @@ given class name. a `GtkStyleContext` + line="388">a `GtkStyleContext` a `GtkStyleProvider` + line="389">a `GtkStyleProvider` @@ -135724,7 +138787,7 @@ given class name. deprecated-version="4.10"> Restores @context state to a previous stage. + line="581">Restores @context state to a previous stage. See [method@Gtk.StyleContext.save]. This API will be removed in GTK 5 @@ -135737,7 +138800,7 @@ See [method@Gtk.StyleContext.save]. a `GtkStyleContext` + line="583">a `GtkStyleContext` @@ -135748,7 +138811,7 @@ See [method@Gtk.StyleContext.save]. deprecated-version="4.10"> Saves the @context state. + line="542">Saves the @context state. This allows temporary modifications done through [method@Gtk.StyleContext.add_class], @@ -135768,7 +138831,7 @@ must be done before GTK returns to the main loop. a `GtkStyleContext` + line="544">a `GtkStyleContext` @@ -135780,7 +138843,7 @@ must be done before GTK returns to the main loop. deprecated-version="4.10"> Attaches @context to the given display. + line="708">Attaches @context to the given display. The display is used to add style information from “global” style providers, such as the display's `GtkSettings` instance. @@ -135798,13 +138861,13 @@ call this yourself. a `GtkStyleContext` + line="710">a `GtkStyleContext` a `GdkDisplay` + line="711">a `GdkDisplay` @@ -135815,7 +138878,7 @@ call this yourself. deprecated-version="4.10"> Sets the scale to use when getting image assets for the style. + line="456">Sets the scale to use when getting image assets for the style. You should not use this api @@ -135826,13 +138889,13 @@ call this yourself. a `GtkStyleContext` + line="458">a `GtkStyleContext` scale + line="459">scale @@ -135843,7 +138906,7 @@ call this yourself. deprecated-version="4.10"> Sets the state to be used for style matching. + line="410">Sets the state to be used for style matching. You should not use this api @@ -135854,13 +138917,13 @@ call this yourself. a `GtkStyleContext` + line="412">a `GtkStyleContext` state to represent + line="413">state to represent @@ -135871,7 +138934,7 @@ call this yourself. deprecated-version="4.10"> Converts the style context into a string representation. + line="962">Converts the style context into a string representation. The string representation always includes information about the name, state, id, visibility and style classes of the CSS @@ -135887,20 +138950,20 @@ the format of the returned string, it may change. a newly allocated string representing @context + line="978">a newly allocated string representing @context a `GtkStyleContext` + line="964">a `GtkStyleContext` Flags that determine what to print + line="965">Flags that determine what to print @@ -135911,6 +138974,9 @@ the format of the returned string, it may change. transfer-ownership="none" setter="set_display" getter="get_display"> + The display of the style context. @@ -135981,7 +139047,7 @@ the format of the returned string, it may change. c:type="GtkStyleContextPrintFlags"> Flags that modify the behavior of gtk_style_context_to_string(). + line="947">Flags that modify the behavior of gtk_style_context_to_string(). New values may be added to this enumeration. glib:name="GTK_STYLE_CONTEXT_PRINT_NONE"> Default value. + line="949">Default value. glib:name="GTK_STYLE_CONTEXT_PRINT_RECURSE"> Print the entire tree of + line="950">Print the entire tree of CSS nodes starting at the style context's node glib:name="GTK_STYLE_CONTEXT_PRINT_SHOW_STYLE"> Show the values of the + line="952">Show the values of the CSS properties for each node glib:name="GTK_STYLE_CONTEXT_PRINT_SHOW_CHANGE"> Show information about + line="954">Show information about what changes affect the styles @@ -136031,8 +139097,7 @@ New values may be added to this enumeration. glib:get-type="gtk_style_provider_get_type"> `GtkStyleProvider` is an interface for style information used by -`GtkStyleContext`. + line="25">An interface for style information used by [class@Gtk.StyleContext]. See [method@Gtk.StyleContext.add_provider] and [func@Gtk.StyleContext.add_provider_for_display] for @@ -136054,23 +139119,33 @@ GTK uses the `GtkStyleProvider` implementation for CSS in glib:get-type="gtk_switch_get_type"> `GtkSwitch` is a "light switch" that has two states: on or off. + line="26">Shows a "light switch" that has two states: on or off. -![An example GtkSwitch](switch.png) +<picture> + <source srcset="switch-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkSwitch" src="switch.png"> +</picture> The user can control which state should be active by clicking the -empty area, or by dragging the handle. +empty area, or by dragging the slider. -`GtkSwitch` can also handle situations where the underlying state -changes with a delay. In this case, the slider position indicates -the user's recent change (as indicated by the [property@Gtk.Switch:active] -property), and the color indicates whether the underlying state (represented -by the [property@Gtk.Switch:state] property) has been updated yet. +`GtkSwitch` can also express situations where the underlying state changes +with a delay. In this case, the slider position indicates the user's recent +change (represented by the [property@Gtk.Switch:active] property), while the +trough color indicates the present underlying state (represented by the +[property@Gtk.Switch:state] property). -![GtkSwitch with delayed state change](switch-state.png) +<picture> + <source srcset="switch-state-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="GtkSwitch with delayed state change" src="switch-state.png"> +</picture> See [signal@Gtk.Switch::state-set] for details. +# Shortcuts and Gestures + +`GtkSwitch` supports pan and drag gestures to move the slider. + # CSS nodes ``` @@ -136086,7 +139161,7 @@ using any style classes. # Accessibility -`GtkSwitch` uses the %GTK_ACCESSIBLE_ROLE_SWITCH role. +`GtkSwitch` uses the [enum@Gtk.AccessibleRole.switch] role. @@ -136094,34 +139169,33 @@ using any style classes. Creates a new `GtkSwitch` widget. + line="756">Creates a new `GtkSwitch` widget. the newly created `GtkSwitch` instance + line="761">the newly created `GtkSwitch` instance - Gets whether the `GtkSwitch` is in its “on” or “off” state. + line="809">Gets whether the `GtkSwitch` is in its “on” or “off” state. %TRUE if the `GtkSwitch` is active, and %FALSE otherwise + line="815">%TRUE if the `GtkSwitch` is active, and %FALSE otherwise a `GtkSwitch` + line="811">a `GtkSwitch` @@ -136129,22 +139203,21 @@ using any style classes. - Gets the underlying state of the `GtkSwitch`. + line="858">Gets the underlying state of the `GtkSwitch`. the underlying state + line="864">the underlying state a `GtkSwitch` + line="860">a `GtkSwitch` @@ -136152,10 +139225,9 @@ using any style classes. - Changes the state of @self to the desired one. + line="769">Changes the state of @self to the desired one. @@ -136164,13 +139236,13 @@ using any style classes. a `GtkSwitch` + line="771">a `GtkSwitch` %TRUE if @self should be active, and %FALSE otherwise + line="772">%TRUE if @self should be active, and %FALSE otherwise @@ -136178,10 +139250,9 @@ using any style classes. - Sets the underlying state of the `GtkSwitch`. + line="825">Sets the underlying state of the `GtkSwitch`. This function is typically called from a [signal@Gtk.Switch::state-set] signal handler in order to set up delayed state changes. @@ -136195,13 +139266,13 @@ See [signal@Gtk.Switch::state-set] for details. a `GtkSwitch` + line="827">a `GtkSwitch` the new state + line="828">the new state @@ -136212,11 +139283,9 @@ See [signal@Gtk.Switch::state-set] for details. setter="set_active" getter="get_active" default-value="FALSE"> - - Whether the `GtkSwitch` widget is in its on or off state. + line="580">Whether the `GtkSwitch` widget is in its on or off state. setter="set_state" getter="get_state" default-value="FALSE"> - - The backend state that is controlled by the switch. + line="590">The backend state that is controlled by the switch. + +Applications should usually set the [property@Gtk.Switch:active] property, +except when indicating a change to the backend state which occurs +separately from the user's interaction. See [signal@Gtk.Switch::state-set] for details. @@ -136237,7 +139308,7 @@ See [signal@Gtk.Switch::state-set] for details. Emitted to animate the switch. + line="618">Emitted to animate the switch. Applications should never connect to this signal, but use the [property@Gtk.Switch:active] property. @@ -136248,32 +139319,28 @@ but use the [property@Gtk.Switch:active] property. Emitted to change the underlying state. + line="638">Emitted to change the underlying state. The ::state-set signal is emitted when the user changes the switch -position. The default handler keeps the state in sync with the -[property@Gtk.Switch:active] property. +position. The default handler calls [method@Gtk.Switch.set_state] with the +value of @state. To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call [method@Gtk.Switch.set_state] when the underlying state change is complete. The signal handler should return %TRUE to prevent the -default handler from running. - -Visually, the underlying state is represented by the trough color of -the switch, while the [property@Gtk.Switch:active] property is -represented by the position of the switch. +default handler from running. %TRUE to stop the signal emission + line="655">%TRUE to stop the signal emission the new state of the switch + line="641">the new state of the switch @@ -136286,7 +139353,7 @@ represented by the position of the switch. c:type="GtkSymbolicColor"> The indexes of colors passed to symbolic color rendering, such as + line="1252">The indexes of colors passed to symbolic color rendering, such as [vfunc@Gtk.SymbolicPaintable.snapshot_symbolic]. More values may be added over time. @@ -136297,7 +139364,7 @@ More values may be added over time. glib:name="GTK_SYMBOLIC_COLOR_FOREGROUND"> The default foreground color + line="1254">The default foreground color glib:name="GTK_SYMBOLIC_COLOR_ERROR"> Indication color for errors + line="1255">Indication color for errors glib:name="GTK_SYMBOLIC_COLOR_WARNING"> Indication color for warnings + line="1256">Indication color for warnings glib:name="GTK_SYMBOLIC_COLOR_SUCCESS"> Indication color for success + line="1257">Indication color for success glib:type-struct="SymbolicPaintableInterface"> `GtkSymbolicPaintable` is an interface that support symbolic colors in -paintables. + line="26">An interface that supports symbolic colors in paintables. `GdkPaintable`s implementing the interface will have the [vfunc@Gtk.SymbolicPaintable.snapshot_symbolic] function called and @@ -136355,7 +139421,7 @@ More colors may be added in the future. version="4.6"> Snapshots the paintable with the given colors. + line="63">Snapshots the paintable with the given colors. If less than 4 colors are provided, GTK will pad the array with default colors. @@ -136367,31 +139433,31 @@ colors. a `GtkSymbolicPaintable` + line="65">a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to + line="66">a `GdkSnapshot` to snapshot to width to snapshot in + line="67">width to snapshot in height to snapshot in + line="68">height to snapshot in a pointer to an array of colors + line="69">a pointer to an array of colors @@ -136399,7 +139465,7 @@ colors. The number of colors + line="70">The number of colors @@ -136409,7 +139475,7 @@ colors. version="4.6"> Snapshots the paintable with the given colors. + line="63">Snapshots the paintable with the given colors. If less than 4 colors are provided, GTK will pad the array with default colors. @@ -136421,31 +139487,31 @@ colors. a `GtkSymbolicPaintable` + line="65">a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to + line="66">a `GdkSnapshot` to snapshot to width to snapshot in + line="67">width to snapshot in height to snapshot in + line="68">height to snapshot in a pointer to an array of colors + line="69">a pointer to an array of colors @@ -136453,7 +139519,7 @@ colors. The number of colors + line="70">The number of colors @@ -136471,6 +139537,12 @@ No function must be implemented, default implementations exist for each one. + Snapshot the paintable using the given colors. + See `GtkSymbolicPaintable::snapshot_symbolic()` for details. + If this function is not implemented, [vfunc@Gdk.Paintable.snapshot] + will be called. @@ -136480,31 +139552,31 @@ No function must be implemented, default implementations exist for each one. a `GtkSymbolicPaintable` + line="65">a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to + line="66">a `GdkSnapshot` to snapshot to width to snapshot in + line="67">width to snapshot in height to snapshot in + line="68">height to snapshot in a pointer to an array of colors + line="69">a pointer to an array of colors @@ -136512,7 +139584,7 @@ No function must be implemented, default implementations exist for each one. The number of colors + line="70">The number of colors @@ -136525,7 +139597,7 @@ No function must be implemented, default implementations exist for each one. Values that can be passed to the [vfunc@Gtk.Widget.system_setting_changed] + line="1219">Values that can be passed to the [vfunc@Gtk.Widget.system_setting_changed] vfunc. The values indicate which system setting has changed. @@ -136541,7 +139613,7 @@ More values may be added over time. glib:name="GTK_SYSTEM_SETTING_DPI"> the [property@Gtk.Settings:gtk-xft-dpi] setting has changed + line="1221">the [property@Gtk.Settings:gtk-xft-dpi] setting has changed glib:name="GTK_SYSTEM_SETTING_FONT_NAME"> The [property@Gtk.Settings:gtk-font-name] setting has changed + line="1222">The [property@Gtk.Settings:gtk-font-name] setting has changed glib:name="GTK_SYSTEM_SETTING_FONT_CONFIG"> The font configuration has changed in a way that + line="1223">The font configuration has changed in a way that requires text to be redrawn. This can be any of the [property@Gtk.Settings:gtk-xft-antialias], [property@Gtk.Settings:gtk-xft-hinting], @@ -136574,7 +139646,7 @@ More values may be added over time. glib:name="GTK_SYSTEM_SETTING_DISPLAY"> The display has changed + line="1230">The display has changed glib:name="GTK_SYSTEM_SETTING_ICON_THEME"> The icon theme has changed in a way that requires + line="1231">The icon theme has changed in a way that requires icons to be looked up again @@ -136624,7 +139696,7 @@ More values may be added over time. - + @@ -136633,7 +139705,7 @@ More values may be added over time. - + @@ -136642,7 +139714,7 @@ More values may be added over time. - + @@ -137016,29 +140088,72 @@ See also: [method@Gtk.TreeSortable.set_sort_column_id] glib:get-type="gtk_text_get_type"> The `GtkText` widget is a single-line text entry widget. + line="78">A single-line text entry. `GtkText` is the common implementation of single-line text editing that is shared between [class@Gtk.Entry], [class@Gtk.PasswordEntry], -[class@Gtk.SpinButton], and other widgets. In all of these, `GtkText` is -used as the delegate for the [iface@Gtk.Editable] implementation. +[class@Gtk.SpinButton], and other widgets. In all of these, a `GtkText` +instance is used as the delegate for the [iface@Gtk.Editable] implementation. -A fairly large set of key bindings are supported by default. If the -entered text is longer than the allocation of the widget, the widget -will scroll so that the cursor position is visible. +A large number of key bindings s supported by default. If the entered +text is longer than the allocation of the widget, the widget will scroll +so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using [method@Gtk.Text.set_visibility]. -In this mode, entered text is displayed using a “invisible” character. +In this mode, entered text is displayed using an “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. -If you are looking to add icons or progress display in an entry, look -at [class@Gtk.Entry]. There other alternatives for more specialized use -cases, such as [class@Gtk.SearchEntry]. +If you want to add icons or progress display in an entry, look at +[class@Gtk.Entry]. There are other alternatives for more specialized +use cases, such as [class@Gtk.SearchEntry]. + +If you need multi-line editable text, use [class@Gtk.TextView]. + +# Shortcuts and Gestures + +`GtkText` supports the following keyboard shortcuts: + +- <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. +- <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> + selects all the text. +- <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or + <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all. +- <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes the last modification. +- <kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> + redoes the last undone modification. +- <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd> toggles the text direction. -If you need multi-line editable text, look at [class@Gtk.TextView]. +Additionally, the following signals have default keybindings: + +- [signal@Gtk.Text::activate] +- [signal@Gtk.Text::backspace] +- [signal@Gtk.Text::copy-clipboard] +- [signal@Gtk.Text::cut-clipboard] +- [signal@Gtk.Text::delete-from-cursor] +- [signal@Gtk.Text::insert-emoji] +- [signal@Gtk.Text::move-cursor] +- [signal@Gtk.Text::paste-clipboard] +- [signal@Gtk.Text::toggle-overwrite] + +# Actions + +`GtkText` defines a set of built-in actions: + +- `clipboard.copy` copies the contents to the clipboard. +- `clipboard.cut` copies the contents to the clipboard and deletes it from + the widget. +- `clipboard.paste` inserts the contents of the clipboard into the widget. +- `menu.popup` opens the context menu. +- `misc.insert-emoji` opens the Emoji chooser. +- `misc.toggle-visibility` toggles the `GtkText`:visibility property. +- `misc.toggle-direction` toggles the text direction. +- `selection.delete` deletes the current selection. +- `selection.select-all` selects all of the widgets content. +- `text.redo` redoes the last change to the contents. +- `text.undo` undoes the last change to the contents. # CSS nodes @@ -137048,7 +140163,10 @@ text[.read-only] ├── undershoot.left ├── undershoot.right ├── [selection] +├── [cursor-handle[.top] +├── [cursor-handle.bottom] ├── [block-cursor] +├── [cursor-handle[.top/.bottom][.insertion-cursor]] ╰── [window.popup] ``` @@ -137074,23 +140192,24 @@ there is just a single handle for the text cursor, it gets the style class # Accessibility -`GtkText` uses the %GTK_ACCESSIBLE_ROLE_NONE role, which causes it to be +`GtkText` uses the [enum@Gtk.AccessibleRole.none] role, which causes it to be skipped for accessibility. This is because `GtkText` is expected to be used as a delegate for a `GtkEditable` implementation that will be represented to accessibility. + Creates a new `GtkText`. + line="5591">Creates a new `GtkText`. a new `GtkText`. + line="5596">the new `GtkText` @@ -137098,19 +140217,19 @@ to accessibility. c:identifier="gtk_text_new_with_buffer"> Creates a new `GtkText` with the specified text buffer. + line="5604">Creates a new `GtkText` with the specified buffer. a new `GtkText` + line="5610">a new `GtkText` The buffer to use for the new `GtkText`. + line="5606">the buffer to use @@ -137120,8 +140239,8 @@ to accessibility. version="4.4"> Determine the positions of the strong and weak cursors if the -insertion point in the layout is at @position. + line="7422">Determines the positions of the strong and weak cursors for a +given character position. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of @@ -137138,13 +140257,13 @@ The rectangle positions are in widget coordinates. a `GtkText` + line="7424">a text widget the character position + line="7425">the character position allow-none="1"> location to store the strong cursor position + line="7426">location to store the strong cursor position allow-none="1"> location to store the weak cursor position + line="7427">location to store the weak cursor position @@ -137174,26 +140293,24 @@ The rectangle positions are in widget coordinates. - Returns whether pressing Enter will activate -the default widget for the window containing @self. + line="6085">Returns whether pressing <kbd>Enter</kbd> will activate +the default widget for the window containing the widget. See [method@Gtk.Text.set_activates_default]. %TRUE if the `GtkText` will activate the default widget + line="6094">true if @self will activate the default widget a `GtkText` + line="6087">a text widget @@ -137201,24 +140318,23 @@ See [method@Gtk.Text.set_activates_default]. - Gets the attribute list that was set on the `GtkText`. + line="7118">Gets the attribute list that was set on the text widget. See [method@Gtk.Text.set_attributes]. the attribute list + line="7126">the attribute list a `GtkText` + line="7120">a text widget @@ -137226,23 +140342,22 @@ See [method@Gtk.Text.set_attributes]. - Get the `GtkEntryBuffer` object which holds the text for + line="5636">Get the entry buffer object which holds the text for this widget. A `GtkEntryBuffer` object. + line="5643">the entry buffer object a `GtkText` + line="5638">a text widget @@ -137250,24 +140365,21 @@ this widget. - Returns whether Emoji completion is enabled for this -`GtkText` widget. + line="7319">Returns whether Emoji completion is enabled. %TRUE if Emoji completion is enabled + line="7325">true if Emoji completion is enabled a `GtkText` + line="7321">a text widget @@ -137275,24 +140387,23 @@ this widget. - Gets the menu model for extra items in the context menu. + line="7267">Gets the extra menu model of the text widget. See [method@Gtk.Text.set_extra_menu]. the menu model + line="7275">the menu model a `GtkText` + line="7269">a text widget @@ -137300,19 +140411,21 @@ See [method@Gtk.Text.set_extra_menu]. - Gets the input hints of the `GtkText`. + line="7064">Gets the input hints of the text widget. + the input hints a `GtkText` + line="7066">a text widget @@ -137320,19 +140433,21 @@ See [method@Gtk.Text.set_extra_menu]. - Gets the input purpose of the `GtkText`. + line="7014">Gets the input purpose of the text widget. + the input purpose a `GtkText` + line="7016">a text widget @@ -137340,10 +140455,9 @@ See [method@Gtk.Text.set_extra_menu]. - Retrieves the character displayed when visibility is set to false. + line="5892">Retrieves the character displayed when visibility is set to false. Note that GTK does not compute this value unless it needs it, so the value returned by this function is not very useful unless @@ -137352,15 +140466,15 @@ it has been explicitly set with [method@Gtk.Text.set_invisible_char]. the current invisible char, or 0, if @text does not - show invisible text at all. + line="5902">the current invisible char, or 0, if @text does not + show invisible text at all a `GtkText` + line="5894">a text widget @@ -137368,10 +140482,9 @@ it has been explicitly set with [method@Gtk.Text.set_invisible_char]. - Retrieves the maximum allowed length of the text in @self. + line="6014">Retrieves the maximum allowed length of the contents. See [method@Gtk.Text.set_max_length]. @@ -137381,15 +140494,15 @@ calling [method@Gtk.EntryBuffer.get_max_length] on it. the maximum allowed number of characters - in `GtkText`, or 0 if there is no maximum. + line="6025">the maximum allowed number of characters, or 0 if + there is no limit a `GtkText` + line="6016">a text widget @@ -137397,24 +140510,23 @@ calling [method@Gtk.EntryBuffer.get_max_length] on it. - Gets whether text is overwritten when typing in the `GtkText`. + line="5970">Gets whether text is overwritten when typing. See [method@Gtk.Text.set_overwrite_mode]. whether the text is overwritten when typing + line="5978">whether text is overwritten when typing a `GtkText` + line="5972">a text widget @@ -137422,26 +140534,24 @@ See [method@Gtk.Text.set_overwrite_mode]. - Retrieves the text that will be displayed when -@self is empty and unfocused + line="6962">Retrieves the text that will be displayed when the text widget +is empty and unfocused -If no placeholder text has been set, %NULL will be returned. +See [method@Gtk.Text.set_placeholder_text]. the placeholder text + line="6971">the placeholder text a `GtkText` + line="6964">a text widget @@ -137449,24 +140559,22 @@ If no placeholder text has been set, %NULL will be returned. - Returns whether the `GtkText` will grow and shrink + line="7362">Returns whether the text widget will grow and shrink with the content. %TRUE if @self will propagate the text width + line="7369">true if @self will propagate the text width a `GtkText` + line="7364">a text widget @@ -137474,24 +140582,23 @@ with the content. - Gets the tabstops that were set on the `GtkText`. + line="7167">Gets the tab stops for the text widget. See [method@Gtk.Text.set_tabs]. the tabstops + line="7175">the tab stops a `GtkText` + line="7169">a text widget @@ -137499,7 +140606,7 @@ See [method@Gtk.Text.set_tabs]. Retrieves the current length of the text in @self. + line="6036">Retrieves the length of the contents. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. @@ -137507,15 +140614,14 @@ and calling [method@Gtk.EntryBuffer.get_length] on it. the current number of characters - in `GtkText`, or 0 if there are none. + line="6045">the length of the contents, in characters a `GtkText` + line="6038">a text widget @@ -137523,24 +140629,21 @@ and calling [method@Gtk.EntryBuffer.get_length] on it. - Returns whether the `GtkText` will truncate multi-line text -that is pasted into the widget + line="7404">Returns whether pasted text will be truncated to the first line. %TRUE if @self will truncate multi-line text + line="7410">true if @self will truncate pasted multi-line text a `GtkText` + line="7406">a text widget @@ -137548,22 +140651,21 @@ that is pasted into the widget - Retrieves whether the text in @self is visible. + line="5840">Retrieves whether the text is visible. %TRUE if the text is currently visible + line="5846">true if the text is visible a `GtkText` + line="5842">a text widget @@ -137572,25 +140674,26 @@ that is pasted into the widget c:identifier="gtk_text_grab_focus_without_selecting"> Causes @self to have keyboard focus. + line="3489">Causes the text widget to have the keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], -except that it doesn't select the contents of @self. +except that it does not select the contents of @self. + You only want to call this on some special entries -which the user usually doesn't want to replace all text in, -such as search-as-you-type entries. +which the user usually doesn't want to replace all +text in, such as search-as-you-type entries. %TRUE if focus is now inside @self + line="3502">true if focus is now inside @self a `GtkText` + line="3491">a text widget @@ -137598,15 +140701,13 @@ such as search-as-you-type entries. - If @activates is %TRUE, pressing Enter will activate -the default widget for the window containing @self. + line="6055">Sets whether pressing <kbd>Enter</kbd> will activate +the default widget. -This usually means that the dialog containing the `GtkText` -will be closed, since the default widget is usually one of +This usually means that the dialog containing @self will +be closed, since the default widget is usually one of the dialog buttons. @@ -137616,13 +140717,14 @@ the dialog buttons. a `GtkText` + line="6057">a text widget %TRUE to activate window’s default widget on Enter keypress + line="6058">true to activate window’s default widget on + <kbd>Enter</kbd> keypress @@ -137630,10 +140732,9 @@ the dialog buttons. - Sets attributes that are applied to the text. + line="7087">Apply attributes to the contents of the text widget. @@ -137642,7 +140743,7 @@ the dialog buttons. a `GtkText` + line="7089">a text widget allow-none="1"> a `PangoAttrList` + line="7090">a list of style attributes @@ -137659,10 +140760,9 @@ the dialog buttons. - Set the `GtkEntryBuffer` object which holds the text for + line="5653">Set the entry buffer object which holds the text for this widget. @@ -137672,13 +140772,13 @@ this widget. a `GtkText` + line="5655">a text widget a `GtkEntryBuffer` + line="5656">an entry buffer object @@ -137686,11 +140786,9 @@ this widget. - Sets whether Emoji completion is enabled. + line="7287">Sets whether Emoji completion is enabled. If it is, typing ':', followed by a recognized keyword, will pop up a window with suggested Emojis matching the @@ -137703,13 +140801,13 @@ keyword. a `GtkText` + line="7289">a text widget %TRUE to enable Emoji completion + line="7290">true to enable Emoji completion @@ -137717,11 +140815,9 @@ keyword. - Sets a menu model to add when constructing -the context menu for @self. + line="7244">Sets a menu model to add to the context menu of the text widget. @@ -137730,7 +140826,7 @@ the context menu for @self. a `GtkText` + line="7246">a text widget allow-none="1"> a `GMenuModel` + line="7247">a menu model @@ -137747,11 +140843,9 @@ the context menu for @self. - Sets input hints that allow input methods -to fine-tune their behaviour. + line="7037">Sets hints that allow input methods to fine-tune their behaviour. @@ -137760,13 +140854,13 @@ to fine-tune their behaviour. a `GtkText` + line="7039">a text widget the hints + line="7040">input hints @@ -137774,13 +140868,12 @@ to fine-tune their behaviour. - Sets the input purpose of the `GtkText`. + line="6986">Sets the input purpose of the text widget. -This can be used by on-screen keyboards and other -input methods to adjust their behaviour. +The input purpose can be used by on-screen keyboards +and other input methods to adjust their behaviour. @@ -137789,13 +140882,13 @@ input methods to adjust their behaviour. a `GtkText` + line="6988">a text widget the purpose + line="6989">the input purpose @@ -137803,10 +140896,9 @@ input methods to adjust their behaviour. - Sets the character to use when in “password mode”. + line="5858">Sets the character to use when in “password mode”. By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user @@ -137820,13 +140912,13 @@ as they type. a `GtkText` + line="5860">a text widget a Unicode character + line="5861">a Unicode character @@ -137834,12 +140926,11 @@ as they type. - Sets the maximum allowed length of the contents of the widget. + line="5991">Sets the maximum allowed length of the contents. -If the current contents are longer than the given length, then +If the current contents are longer than the given length, they will be truncated to fit. This is equivalent to getting @self's `GtkEntryBuffer` and @@ -137852,15 +140943,15 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. a `GtkText` + line="5993">a text widget the maximum length of the `GtkText`, or 0 for no maximum. + line="5994">the maximum length of the text, or 0 for no maximum. (other than the maximum length of entries.) The value passed - in will be clamped to the range 0-65536. + in will be clamped to the range 0-65536 @@ -137868,11 +140959,9 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. - Sets whether the text is overwritten when typing -in the `GtkText`. + line="5947">Sets whether the text is overwritten when typing. @@ -137881,13 +140970,13 @@ in the `GtkText`. a `GtkText` + line="5949">a text widget new value + line="5950">new value @@ -137895,14 +140984,13 @@ in the `GtkText`. - Sets text to be displayed in @self when it is empty. + line="6920">Sets the text to be displayed when the text widget is +empty and unfocused. This can be used to give a visual hint of the expected -contents of the `GtkText`. +contents of the text widget. @@ -137911,7 +140999,7 @@ contents of the `GtkText`. a `GtkText` + line="6922">a text widget allow-none="1"> a string to be displayed when @self + line="6923">a string to be displayed when @self is empty and unfocused @@ -137929,11 +141017,9 @@ contents of the `GtkText`. - Sets whether the `GtkText` should grow and shrink with the content. + line="7337">Sets whether the text widget should grow and shrink with the content. @@ -137942,13 +141028,13 @@ contents of the `GtkText`. a `GtkText` + line="7339">a text widget %TRUE to propagate the text width + line="7340">true to propagate the text width @@ -137956,10 +141042,9 @@ contents of the `GtkText`. - Sets tabstops that are applied to the text. + line="7138">Sets tab stops for the text widget. @@ -137968,7 +141053,7 @@ contents of the `GtkText`. a `GtkText` + line="7140">a text widget allow-none="1"> a `PangoTabArray` + line="7141">tab stops @@ -137985,12 +141070,9 @@ contents of the `GtkText`. - Sets whether the `GtkText` should truncate multi-line text -that is pasted into the widget. + line="7381">Sets whether pasted text should be truncated to the first line. @@ -137999,13 +141081,13 @@ that is pasted into the widget. a `GtkText` + line="7383">a text widget %TRUE to truncate multi-line text + line="7384">true to truncate multi-line text @@ -138013,13 +141095,12 @@ that is pasted into the widget. - Sets whether the contents of the `GtkText` are visible or not. + line="5794">Sets whether the contents of the text widget are visible or not. -When visibility is set to %FALSE, characters are displayed -as the invisible char, and will also appear that way when +When visibility is set to false, characters are displayed +as the invisible char, and it will also appear that way when the text in the widget is copied to the clipboard. By default, GTK picks the best invisible character available @@ -138027,9 +141108,9 @@ in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. Note that you probably want to set [property@Gtk.Text:input-purpose] -to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to -inform input methods about the purpose of this self, -in addition to setting visibility to %FALSE. +to [enum@Gtk.InputPurpose.password] or [enum@Gtk.InputPurpose.pin] +to inform input methods about the purpose of this widget, in addition +to setting visibility to false. @@ -138038,14 +141119,14 @@ in addition to setting visibility to %FALSE. a `GtkText` + line="5796">a text widget %TRUE if the contents of the `GtkText` are displayed - as plaintext + line="5797">true if the contents of the text widget are displayed + as plain text @@ -138054,10 +141135,9 @@ in addition to setting visibility to %FALSE. c:identifier="gtk_text_unset_invisible_char"> Unsets the invisible char. + line="5915">Unsets the invisible char. -After calling this, the default invisible -char is used again. +After calling this, the default invisible char is used again. @@ -138066,7 +141146,7 @@ char is used again. a `GtkText` + line="5917">a text widget @@ -138077,13 +141157,9 @@ char is used again. setter="set_activates_default" getter="get_activates_default" default-value="FALSE"> - - Whether to activate the default widget when Enter is pressed. + line="856">Whether to activate the default widget when <kbd>Enter</kbd> is pressed. transfer-ownership="none" setter="set_attributes" getter="get_attributes"> - - A list of Pango attributes to apply to the text of the `GtkText`. + line="964">A list of Pango attributes to apply to the text. This is mainly useful to change the size or weight of the text. @@ -138111,11 +141183,9 @@ The `PangoAttribute`'s @start_index and @end_index must refer to the transfer-ownership="none" setter="set_buffer" getter="get_buffer"> - - The `GtkEntryBuffer` object which stores the text. + line="823">The `GtkEntryBuffer` object which stores the text. - - Whether to suggest Emoji replacements. + line="989">Whether to suggest Emoji replacements. - - A menu model whose contents will be appended to -the context menu. + line="1019">A menu model whose contents will be appended to the context menu. default-value="NULL"> Which IM (input method) module should be used for this self. + line="918">Which input method module should be used. See [class@Gtk.IMMulticontext]. -Setting this to a non-%NULL value overrides the system-wide -IM module setting. See the [property@Gtk.Settings:gtk-im-module] -property. +Setting this to a non-`NULL` value overrides the system-wide +input method. See the [property@Gtk.Settings:gtk-im-module] +setting. setter="set_input_hints" getter="get_input_hints" default-value="GTK_INPUT_HINT_NONE"> - - Additional hints that allow input methods to fine-tune + line="952">Additional hints that allow input methods to fine-tune their behaviour. @@ -138185,19 +141242,15 @@ their behaviour. setter="set_input_purpose" getter="get_input_purpose" default-value="GTK_INPUT_PURPOSE_FREE_FORM"> - - The purpose of this text field. + line="934">The purpose of this text field. -This property can be used by on-screen keyboards and other input +This information can be used by on-screen keyboards and other input methods to adjust their behaviour. -Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or -%GTK_INPUT_PURPOSE_PIN is independent from setting +Note that setting the purpose to [enum@Gtk.InputPurpose.password] +or [enum@Gtk.InputPurpose.pin] is independent from setting [property@Gtk.Text:visibility]. @@ -138207,13 +141260,9 @@ Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or setter="set_invisible_char" getter="get_invisible_char" default-value="42"> - - The character to used when masking contents (in “password mode”). + line="846">The character to used when masking contents (in “password mode”). Whether the invisible char has been set for the `GtkText`. + line="897">Whether the invisible char has been set. - - Maximum number of characters that are allowed. + line="833">Maximum number of characters that are allowed. Zero indicates no limit. @@ -138248,13 +141293,9 @@ Zero indicates no limit. setter="set_overwrite_mode" getter="get_overwrite_mode" default-value="FALSE"> - - If text is overwritten when typing in the `GtkText`. + line="887">If text is overwritten when typing. setter="set_placeholder_text" getter="get_placeholder_text" default-value="NULL"> - - The text that will be displayed in the `GtkText` when it is empty + line="907">The text that will be displayed in the `GtkText` when it is empty and unfocused. @@ -138279,13 +141316,9 @@ and unfocused. setter="set_propagate_text_width" getter="get_propagate_text_width" default-value="FALSE"> - - Whether the widget should grow and shrink with the content. + line="1009">Whether the widget should grow and shrink with the content. default-value="0"> Number of pixels scrolled of the screen to the left. + line="866">Number of pixels scrolled of the screen to the left. transfer-ownership="none" setter="set_tabs" getter="get_tabs"> - - A list of tabstops to apply to the text of the `GtkText`. + line="979">Custom tabs for this text widget. setter="set_truncate_multiline" getter="get_truncate_multiline" default-value="FALSE"> - - When %TRUE, pasted multi-line text is truncated to the first line. + line="877">When true, pasted multi-line text is truncated to the first line. setter="set_visibility" getter="get_visibility" default-value="TRUE"> - - If %FALSE, the text is masked with the “invisible char”. + line="999">If false, the text is masked with the “invisible char”. @@ -138344,7 +141367,7 @@ and unfocused. Emitted when the user hits the <kbd>Enter</kbd> key. + line="1035">Emitted when the user hits the <kbd>Enter</kbd> key. The default bindings for this signal are all forms of the <kbd>Enter</kbd> key. @@ -138355,7 +141378,7 @@ of the <kbd>Enter</kbd> key. Emitted when the user asks for it. + line="1150">Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). @@ -138368,7 +141391,7 @@ The default bindings for this signal are Emitted to copy the selection to the clipboard. + line="1191">Emitted to copy the selection to the clipboard. This is a [keybinding signal](class.SignalAction.html). @@ -138382,7 +141405,7 @@ The default bindings for this signal are Emitted to cut the selection to the clipboard. + line="1170">Emitted to cut the selection to the clipboard. This is a [keybinding signal](class.SignalAction.html). @@ -138396,13 +141419,13 @@ The default bindings for this signal are Emitted when the user initiates a text deletion. + line="1118">Emitted when the user initiates a text deletion. This is a [keybinding signal](class.SignalAction.html). -If the @type is %GTK_DELETE_CHARS, GTK deletes the selection -if there is one, otherwise it deletes the requested number -of characters. +If the @type is [enum@Gtk.DeleteType.chars], GTK deletes the +selection if there is one, otherwise it deletes the requested +number of characters. The default bindings for this signal are <kbd>Delete</kbd> for deleting a character and <kbd>Ctrl</kbd>+<kbd>Delete</kbd> @@ -138414,13 +141437,13 @@ for deleting a word. the granularity of the deletion, as a `GtkDeleteType` + line="1121">the granularity of the deletion the number of @type units to delete + line="1122">the number of @type units to delete @@ -138428,7 +141451,7 @@ for deleting a word. Emitted when the user initiates the insertion of a + line="1096">Emitted when the user initiates the insertion of a fixed string at the cursor. This is a [keybinding signal](class.SignalAction.html). @@ -138441,7 +141464,7 @@ This signal has no default bindings. the string to insert + line="1099">the string to insert @@ -138449,7 +141472,7 @@ This signal has no default bindings. Emitted to present the Emoji chooser for the widget. + line="1272">Emitted to present the Emoji chooser. This is a [keybinding signal](class.SignalAction.html). @@ -138463,7 +141486,7 @@ The default bindings for this signal are Emitted when the user initiates a cursor movement. + line="1053">Emitted when the user initiates a cursor movement. If the cursor is not visible in @self, this signal causes the viewport to be moved instead. @@ -138471,8 +141494,8 @@ the viewport to be moved instead. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with -g_signal_emit_by_name() if they need to control the cursor -programmatically. +[func@GObject.signal_emit_by_name] if they need to control +the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the @@ -138490,19 +141513,19 @@ There are too many key combinations to list them all here. the granularity of the move, as a `GtkMovementStep` + line="1056">the granularity of the move the number of @step units to move + line="1057">the number of @step units to move %TRUE if the move should extend the selection + line="1058">true if the move should extend the selection @@ -138510,7 +141533,7 @@ There are too many key combinations to list them all here. Emitted to paste the contents of the clipboard. + line="1212">Emitted to paste the contents of the clipboard. This is a [keybinding signal](class.SignalAction.html). @@ -138523,7 +141546,7 @@ The default bindings for this signal are Emitted when the preedit text changes. + line="1251">Emitted when the preedit text changes. If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, @@ -138535,7 +141558,7 @@ connect to this signal. the current preedit string + line="1254">the current preedit string @@ -138543,7 +141566,7 @@ connect to this signal. Emitted to toggle the overwrite mode of the `GtkText`. + line="1232">Emitted to toggle the overwrite mode. This is a [keybinding signal](class.SignalAction.html). @@ -138571,16 +141594,16 @@ related to the text widget and how they work together. GtkTextBuffer can support undoing changes to the buffer content, see [method@Gtk.TextBuffer.set_enable_undo]. - + Creates a new text buffer. - + line="1120">Creates a new text buffer. + a new text buffer + line="1126">a new text buffer @@ -138590,7 +141613,7 @@ content, see [method@Gtk.TextBuffer.set_enable_undo]. allow-none="1"> a tag table, or %NULL to create a new one + line="1122">a tag table, or %NULL to create a new one @@ -138598,12 +141621,12 @@ content, see [method@Gtk.TextBuffer.set_enable_undo]. Emits the “apply-tag” signal on @buffer. + line="3094">Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. - + @@ -138611,25 +141634,25 @@ not have to be in order. a `GtkTextBuffer` + line="3096">a `GtkTextBuffer` a `GtkTextTag` + line="3097">a `GtkTextTag` one bound of range to be tagged + line="3098">one bound of range to be tagged other bound of range to be tagged + line="3099">other bound of range to be tagged @@ -138637,7 +141660,7 @@ not have to be in order. Called to indicate that the buffer operations between here and a + line="4361">Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. @@ -138655,7 +141678,7 @@ The “interactive” buffer mutation functions, such as begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. - + @@ -138663,13 +141686,16 @@ solely of a single call to one of those functions. a `GtkTextBuffer` + line="4363">a `GtkTextBuffer` - + The class handler for the `GtkTextBuffer::changed` signal. + @@ -138680,7 +141706,10 @@ solely of a single call to one of those functions. - + The class handler for the `GtkTextBuffer::delete-range` signal. + @@ -138699,12 +141728,12 @@ solely of a single call to one of those functions. Ends a user-visible operation. + line="4399">Ends a user-visible operation. Should be paired with a call to [method@Gtk.TextBuffer.begin_user_action]. See that function for a full explanation. - + @@ -138712,7 +141741,7 @@ See that function for a full explanation. a `GtkTextBuffer` + line="4401">a `GtkTextBuffer` @@ -138720,7 +141749,7 @@ See that function for a full explanation. Inserts a child widget anchor into the text buffer at @iter. + line="2422">Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented @@ -138733,7 +141762,7 @@ not. E.g. see [method@Gtk.TextBuffer.get_slice] and Consider [method@Gtk.TextBuffer.create_child_anchor] as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. - + @@ -138741,19 +141770,19 @@ reference to the anchor, so you can unref it after insertion. a `GtkTextBuffer` + line="2424">a `GtkTextBuffer` location to insert the anchor + line="2425">location to insert the anchor a `GtkTextChildAnchor` + line="2426">a `GtkTextChildAnchor` @@ -138761,7 +141790,7 @@ reference to the anchor, so you can unref it after insertion. Inserts an image into the text buffer at @iter. + line="2378">Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be @@ -138770,7 +141799,7 @@ Note that the “slice” variants for obtaining portions of the buffer as a string include this character for paintable, but the “text” variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. - + @@ -138778,25 +141807,28 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and a `GtkTextBuffer` + line="2380">a `GtkTextBuffer` location to insert the paintable + line="2381">location to insert the paintable a `GdkPaintable` + line="2382">a `GdkPaintable` - + The class handler for the `GtkTextBuffer::insert-text` signal. + @@ -138816,7 +141848,10 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and - + The class handler for the `GtkTextBuffer::mark-deleted` signal. + @@ -138830,7 +141865,10 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and - + The class handler for the `GtkTextBuffer::mark-set` signal. + @@ -138847,7 +141885,10 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and - + The class handler for the `GtkTextBuffer::modified-changed` signal. + @@ -138858,7 +141899,10 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and - + The class handler for the `GtkTextBuffer::paste-done` signal. + @@ -138874,8 +141918,8 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and Redoes the next redoable action on the buffer, if there is one. - + line="5110">Redoes the next redoable action on the buffer, if there is one. + @@ -138883,7 +141927,7 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and a `GtkTextBuffer` + line="5112">a `GtkTextBuffer` @@ -138891,12 +141935,12 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and Emits the “remove-tag” signal. + line="3124">Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. - + @@ -138904,25 +141948,25 @@ to be in order. a `GtkTextBuffer` + line="3126">a `GtkTextBuffer` a `GtkTextTag` + line="3127">a `GtkTextTag` one bound of range to be untagged + line="3128">one bound of range to be untagged other bound of range to be untagged + line="3129">other bound of range to be untagged @@ -138930,8 +141974,8 @@ to be in order. Undoes the last undoable action on the buffer, if there is one. - + line="5095">Undoes the last undoable action on the buffer, if there is one. + @@ -138939,15 +141983,82 @@ to be in order. a `GtkTextBuffer` + line="5097">a `GtkTextBuffer` + + Adds a [callback@Gtk.TextBufferCommitNotify] to be called when a change +is to be made to the [type@Gtk.TextBuffer]. + +Functions are explicitly forbidden from making changes to the +[type@Gtk.TextBuffer] from this callback. It is intended for tracking +changes to the buffer only. + +It may be advantageous to use [callback@Gtk.TextBufferCommitNotify] over +connecting to the [signal@Gtk.TextBuffer::insert-text] or +[signal@Gtk.TextBuffer::delete-range] signals to avoid ordering issues with +other signal handlers which may further modify the [type@Gtk.TextBuffer]. + + + a handler id which may be used to remove the commit notify + callback using [method@Gtk.TextBuffer.remove_commit_notify]. + + + + + a [type@Gtk.TextBuffer] + + + + which notifications should be dispatched to @callback + + + + a + [callback@Gtk.TextBufferCommitNotify] to call for commit notifications + + + + closure data for @commit_notify + + + + a callback to free @user_data when @commit_notify is removed + + + + Adds the mark at position @where. + line="2608">Adds the mark at position @where. The mark must not be added to another buffer, and if its name is not %NULL then there must not be another mark in the buffer @@ -138955,7 +142066,7 @@ with the same name. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the mark's initial placement. - + @@ -138963,19 +142074,19 @@ of the mark's initial placement. a `GtkTextBuffer` + line="2610">a `GtkTextBuffer` the mark to add + line="2611">the mark to add location to place mark + line="2612">location to place mark @@ -138984,12 +142095,12 @@ of the mark's initial placement. c:identifier="gtk_text_buffer_add_selection_clipboard"> Adds @clipboard to the list of clipboards in which the selection + line="3959">Adds @clipboard to the list of clipboards in which the selection contents of @buffer are available. In most cases, @clipboard will be the `GdkClipboard` returned by [method@Gtk.Widget.get_primary_clipboard] for a view of @buffer. - + @@ -138997,13 +142108,13 @@ In most cases, @clipboard will be the `GdkClipboard` returned by a `GtkTextBuffer` + line="3961">a `GtkTextBuffer` a `GdkClipboard` + line="3962">a `GdkClipboard` @@ -139011,12 +142122,12 @@ In most cases, @clipboard will be the `GdkClipboard` returned by Emits the “apply-tag” signal on @buffer. + line="3094">Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. - + @@ -139024,25 +142135,25 @@ not have to be in order. a `GtkTextBuffer` + line="3096">a `GtkTextBuffer` a `GtkTextTag` + line="3097">a `GtkTextTag` one bound of range to be tagged + line="3098">one bound of range to be tagged other bound of range to be tagged + line="3099">other bound of range to be tagged @@ -139051,12 +142162,12 @@ not have to be in order. c:identifier="gtk_text_buffer_apply_tag_by_name"> Emits the “apply-tag” signal on @buffer. + line="3155">Emits the “apply-tag” signal on @buffer. Calls [method@Gtk.TextTagTable.lookup] on the buffer’s tag table to get a `GtkTextTag`, then calls [method@Gtk.TextBuffer.apply_tag]. - + @@ -139064,25 +142175,25 @@ tag table to get a `GtkTextTag`, then calls a `GtkTextBuffer` + line="3157">a `GtkTextBuffer` name of a named `GtkTextTag` + line="3158">name of a named `GtkTextTag` one bound of range to be tagged + line="3159">one bound of range to be tagged other bound of range to be tagged + line="3160">other bound of range to be tagged @@ -139090,7 +142201,7 @@ tag table to get a `GtkTextTag`, then calls Performs the appropriate action as if the user hit the delete + line="4144">Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by @iter. In the normal case a single character will be deleted, but when @@ -139101,36 +142212,36 @@ are involved, less than one character will be deleted. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @iter will be re-initialized to point to the location where text was deleted. - + %TRUE if the buffer was modified + line="4163">%TRUE if the buffer was modified a `GtkTextBuffer` + line="4146">a `GtkTextBuffer` a position in @buffer + line="4147">a position in @buffer whether the deletion is caused by user interaction + line="4148">whether the deletion is caused by user interaction whether the buffer is editable by default + line="4149">whether the buffer is editable by default @@ -139139,7 +142250,7 @@ re-initialized to point to the location where text was deleted. c:identifier="gtk_text_buffer_begin_irreversible_action"> Denotes the beginning of an action that may not be undone. + line="5177">Denotes the beginning of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. @@ -139150,7 +142261,7 @@ action has completed. You may nest calls to gtk_text_buffer_begin_irreversible_action() and gtk_text_buffer_end_irreversible_action() pairs. - + @@ -139158,7 +142269,7 @@ and gtk_text_buffer_end_irreversible_action() pairs. a `GtkTextBuffer` + line="5179">a `GtkTextBuffer` @@ -139167,7 +142278,7 @@ and gtk_text_buffer_end_irreversible_action() pairs. c:identifier="gtk_text_buffer_begin_user_action"> Called to indicate that the buffer operations between here and a + line="4361">Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. @@ -139185,7 +142296,7 @@ The “interactive” buffer mutation functions, such as begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. - + @@ -139193,7 +142304,7 @@ solely of a single call to one of those functions. a `GtkTextBuffer` + line="4363">a `GtkTextBuffer` @@ -139202,8 +142313,8 @@ solely of a single call to one of those functions. c:identifier="gtk_text_buffer_copy_clipboard"> Copies the currently-selected text to a clipboard. - + line="4321">Copies the currently-selected text to a clipboard. + @@ -139211,13 +142322,13 @@ solely of a single call to one of those functions. a `GtkTextBuffer` + line="4323">a `GtkTextBuffer` the `GdkClipboard` object to copy to + line="4324">the `GdkClipboard` object to copy to @@ -139226,7 +142337,7 @@ solely of a single call to one of those functions. c:identifier="gtk_text_buffer_create_child_anchor"> Creates and inserts a child anchor. + line="2456">Creates and inserts a child anchor. This is a convenience function which simply creates a child anchor with [ctor@Gtk.TextChildAnchor.new] and inserts it into the buffer @@ -139234,24 +142345,24 @@ with [method@Gtk.TextBuffer.insert_child_anchor]. The new anchor is owned by the buffer; no reference count is returned to the caller of this function. - + the created child anchor + line="2470">the created child anchor a `GtkTextBuffer` + line="2458">a `GtkTextBuffer` location in the buffer + line="2459">location in the buffer @@ -139259,7 +142370,7 @@ returned to the caller of this function. Creates a mark at position @where. + line="2567">Creates a mark at position @where. If @mark_name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using [method@Gtk.TextBuffer.get_mark]. @@ -139278,18 +142389,18 @@ away when the buffer does. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the mark's initial placement. - + the new `GtkTextMark` object + line="2594">the new `GtkTextMark` object a `GtkTextBuffer` + line="2569">a `GtkTextBuffer` allow-none="1"> name for mark + line="2570">name for mark location to place mark + line="2571">location to place mark whether the mark has left gravity + line="2572">whether the mark has left gravity @@ -139320,7 +142431,7 @@ of the mark's initial placement. introspectable="0"> Creates a tag and adds it to the tag table for @buffer. + line="2948">Creates a tag and adds it to the tag table for @buffer. Equivalent to calling [ctor@Gtk.TextTag.new] and then adding the tag to the buffer’s tag table. The returned tag is owned by @@ -139333,18 +142444,18 @@ exist in the tag table for this buffer. The @first_property_name argument and subsequent arguments are a list of properties to set on the tag, as with g_object_set(). - + a new tag + line="2969">a new tag a `GtkTextBuffer` + line="2950">a `GtkTextBuffer` allow-none="1"> name of the new tag + line="2951">name of the new tag allow-none="1"> name of first property to set + line="2952">name of first property to set %NULL-terminated list of property names and values + line="2953">%NULL-terminated list of property names and values @@ -139377,9 +142488,9 @@ of properties to set on the tag, as with g_object_set(). c:identifier="gtk_text_buffer_cut_clipboard"> Copies the currently-selected text to a clipboard, + line="4302">Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. - + @@ -139387,19 +142498,19 @@ then deletes said text if it’s editable. a `GtkTextBuffer` + line="4304">a `GtkTextBuffer` the `GdkClipboard` object to cut to + line="4305">the `GdkClipboard` object to cut to default editability of the buffer + line="4306">default editability of the buffer @@ -139407,7 +142518,7 @@ then deletes said text if it’s editable. Deletes text between @start and @end. + line="2114">Deletes text between @start and @end. The order of @start and @end is not actually relevant; gtk_text_buffer_delete() will reorder them. @@ -139417,7 +142528,7 @@ the default handler of that signal deletes the text. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @start and @end will be re-initialized to point to the location where text was deleted. - + @@ -139425,19 +142536,19 @@ re-initialized to point to the location where text was deleted. a `GtkTextBuffer` + line="2116">a `GtkTextBuffer` a position in @buffer + line="2117">a position in @buffer another position in @buffer + line="2118">another position in @buffer @@ -139446,42 +142557,42 @@ re-initialized to point to the location where text was deleted. c:identifier="gtk_text_buffer_delete_interactive"> Deletes all editable text in the given range. + line="2145">Deletes all editable text in the given range. Calls [method@Gtk.TextBuffer.delete] for each editable sub-range of [@start,@end). @start and @end are revalidated to point to the location of the last deleted range, or left untouched if no text was deleted. - + whether some text was actually deleted + line="2159">whether some text was actually deleted a `GtkTextBuffer` + line="2147">a `GtkTextBuffer` start of range to delete + line="2148">start of range to delete end of range + line="2149">end of range whether the buffer is editable by default + line="2150">whether the buffer is editable by default @@ -139489,7 +142600,7 @@ untouched if no text was deleted. Deletes @mark, so that it’s no longer located anywhere in the + line="2691">Deletes @mark, so that it’s no longer located anywhere in the buffer. Removes the reference the buffer holds to the mark, so if @@ -139501,7 +142612,7 @@ to find out if a mark has been removed from its buffer. The [signal@Gtk.TextBuffer::mark-deleted] signal will be emitted as notification after the mark is deleted. - + @@ -139509,13 +142620,13 @@ notification after the mark is deleted. a `GtkTextBuffer` + line="2693">a `GtkTextBuffer` a `GtkTextMark` in @buffer + line="2694">a `GtkTextMark` in @buffer @@ -139524,10 +142635,10 @@ notification after the mark is deleted. c:identifier="gtk_text_buffer_delete_mark_by_name"> Deletes the mark named @name; the mark must exist. + line="2787">Deletes the mark named @name; the mark must exist. See [method@Gtk.TextBuffer.delete_mark] for details. - + @@ -139535,13 +142646,13 @@ See [method@Gtk.TextBuffer.delete_mark] for details. a `GtkTextBuffer` + line="2789">a `GtkTextBuffer` name of a mark in @buffer + line="2790">name of a mark in @buffer @@ -139550,35 +142661,35 @@ See [method@Gtk.TextBuffer.delete_mark] for details. c:identifier="gtk_text_buffer_delete_selection"> Deletes the range between the “insert” and “selection_bound” marks, + line="4107">Deletes the range between the “insert” and “selection_bound” marks, that is, the currently-selected text. If @interactive is %TRUE, the editability of the selection will be considered (users can’t delete uneditable text). - + whether there was a non-empty selection to delete + line="4119">whether there was a non-empty selection to delete a `GtkTextBuffer` + line="4109">a `GtkTextBuffer` whether the deletion is caused by user interaction + line="4110">whether the deletion is caused by user interaction whether the buffer is editable by default + line="4111">whether the buffer is editable by default @@ -139587,7 +142698,7 @@ considered (users can’t delete uneditable text). c:identifier="gtk_text_buffer_end_irreversible_action"> Denotes the end of an action that may not be undone. + line="5201">Denotes the end of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. @@ -139598,7 +142709,7 @@ was called. You may nest calls to gtk_text_buffer_begin_irreversible_action() and gtk_text_buffer_end_irreversible_action() pairs. - + @@ -139606,7 +142717,7 @@ and gtk_text_buffer_end_irreversible_action() pairs. a `GtkTextBuffer` + line="5203">a `GtkTextBuffer` @@ -139615,12 +142726,12 @@ and gtk_text_buffer_end_irreversible_action() pairs. c:identifier="gtk_text_buffer_end_user_action"> Ends a user-visible operation. + line="4399">Ends a user-visible operation. Should be paired with a call to [method@Gtk.TextBuffer.begin_user_action]. See that function for a full explanation. - + @@ -139628,7 +142739,7 @@ See that function for a full explanation. a `GtkTextBuffer` + line="4401">a `GtkTextBuffer` @@ -139636,9 +142747,9 @@ See that function for a full explanation. Retrieves the first and last iterators in the buffer, i.e. the + line="3557">Retrieves the first and last iterators in the buffer, i.e. the entire buffer lies within the range [@start,@end). - + @@ -139646,7 +142757,7 @@ entire buffer lies within the range [@start,@end). a `GtkTextBuffer` + line="3559">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize with first position in the buffer + line="3560">iterator to initialize with first position in the buffer transfer-ownership="none"> iterator to initialize with the end iterator + line="3561">iterator to initialize with the end iterator @@ -139672,22 +142783,21 @@ entire buffer lies within the range [@start,@end). - Gets whether there is a redoable action in the history. - + line="5008">Gets whether there is a redoable action in the history. + %TRUE if there is a redoable action + line="5014">%TRUE if there is a redoable action a `GtkTextBuffer` + line="5010">a `GtkTextBuffer` @@ -139695,22 +142805,21 @@ entire buffer lies within the range [@start,@end). - Gets whether there is an undoable action in the history. - + line="4992">Gets whether there is an undoable action in the history. + %TRUE if there is an undoable action + line="4998">%TRUE if there is an undoable action a `GtkTextBuffer` + line="4994">a `GtkTextBuffer` @@ -139719,25 +142828,25 @@ entire buffer lies within the range [@start,@end). c:identifier="gtk_text_buffer_get_char_count"> Gets the number of characters in the buffer. + line="3673">Gets the number of characters in the buffer. Note that characters and bytes are not the same, you can’t e.g. expect the contents of the buffer in string form to be this many bytes long. The character count is cached, so this function is very fast. - + number of characters in the buffer + line="3685">number of characters in the buffer a `GtkTextBuffer` + line="3675">a `GtkTextBuffer` @@ -139745,27 +142854,26 @@ The character count is cached, so this function is very fast. - Gets whether the buffer is saving modifications to the buffer + line="5125">Gets whether the buffer is saving modifications to the buffer to allow for undo and redo actions. See [method@Gtk.TextBuffer.begin_irreversible_action] and [method@Gtk.TextBuffer.end_irreversible_action] to create changes to the buffer that cannot be undone. - + %TRUE if undoing and redoing changes to the buffer is allowed. + line="5136">%TRUE if undoing and redoing changes to the buffer is allowed. a `GtkTextBuffer` + line="5127">a `GtkTextBuffer` @@ -139773,7 +142881,7 @@ changes to the buffer that cannot be undone. Initializes @iter with the “end iterator,” one past the last valid + line="3533">Initializes @iter with the “end iterator,” one past the last valid character in the text buffer. If dereferenced with [method@Gtk.TextIter.get_char], the end @@ -139781,7 +142889,7 @@ iterator has a character value of 0. The entire buffer lies in the range from the first position in the buffer (call [method@Gtk.TextBuffer.get_start_iter] to get character position 0) to the end iterator. - + @@ -139789,7 +142897,7 @@ character position 0) to the end iterator. a `GtkTextBuffer` + line="3535">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="3536">iterator to initialize @@ -139808,19 +142916,19 @@ character position 0) to the end iterator. glib:get-property="has-selection"> Indicates whether the buffer has some text currently selected. - + line="3634">Indicates whether the buffer has some text currently selected. + %TRUE if the there is text selected + line="3640">%TRUE if the there is text selected a `GtkTextBuffer` + line="3636">a `GtkTextBuffer` @@ -139828,23 +142936,23 @@ character position 0) to the end iterator. Returns the mark that represents the cursor (insertion point). + line="2816">Returns the mark that represents the cursor (insertion point). Equivalent to calling [method@Gtk.TextBuffer.get_mark] to get the mark named “insert”, but very slightly more efficient, and involves less typing. - + insertion point mark + line="2826">insertion point mark a `GtkTextBuffer` + line="2818">a `GtkTextBuffer` @@ -139853,8 +142961,8 @@ efficient, and involves less typing. c:identifier="gtk_text_buffer_get_iter_at_child_anchor"> Obtains the location of @anchor within @buffer. - + line="2863">Obtains the location of @anchor within @buffer. + @@ -139862,7 +142970,7 @@ efficient, and involves less typing. a `GtkTextBuffer` + line="2865">a `GtkTextBuffer` transfer-ownership="none"> an iterator to be initialized + line="2866">an iterator to be initialized a child anchor that appears in @buffer + line="2867">a child anchor that appears in @buffer @@ -139886,22 +142994,22 @@ efficient, and involves less typing. c:identifier="gtk_text_buffer_get_iter_at_line"> Initializes @iter to the start of the given line. + line="3465">Initializes @iter to the start of the given line. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. - + whether the exact position has been found + line="3476">whether the exact position has been found a `GtkTextBuffer` + line="3467">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="3468">iterator to initialize line number counting from 0 + line="3469">line number counting from 0 @@ -139925,7 +143033,7 @@ in the @buffer, the end iterator is returned. c:identifier="gtk_text_buffer_get_iter_at_line_index"> Obtains an iterator pointing to @byte_index within the given line. + line="3414">Obtains an iterator pointing to @byte_index within the given line. @byte_index must be the start of a UTF-8 character. Note bytes, not characters; UTF-8 may encode one character as multiple bytes. @@ -139933,18 +143041,18 @@ characters; UTF-8 may encode one character as multiple bytes. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. And if @byte_index is off the end of the line, the iterator at the end of the line is returned. - + whether the exact position has been found + line="3430">whether the exact position has been found a `GtkTextBuffer` + line="3416">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="3417">iterator to initialize line number counting from 0 + line="3418">line number counting from 0 byte index from start of line + line="3419">byte index from start of line @@ -139974,7 +143082,7 @@ end of the line, the iterator at the end of the line is returned. c:identifier="gtk_text_buffer_get_iter_at_line_offset"> Obtains an iterator pointing to @char_offset within the given line. + line="3363">Obtains an iterator pointing to @char_offset within the given line. Note characters, not bytes; UTF-8 may encode one character as multiple bytes. @@ -139982,18 +143090,18 @@ bytes. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. And if @char_offset is off the end of the line, the iterator at the end of the line is returned. - + whether the exact position has been found + line="3379">whether the exact position has been found a `GtkTextBuffer` + line="3365">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="3366">iterator to initialize line number counting from 0 + line="3367">line number counting from 0 char offset from start of line + line="3368">char offset from start of line @@ -140023,8 +143131,8 @@ end of the line, the iterator at the end of the line is returned. c:identifier="gtk_text_buffer_get_iter_at_mark"> Initializes @iter with the current position of @mark. - + line="2669">Initializes @iter with the current position of @mark. + @@ -140032,7 +143140,7 @@ end of the line, the iterator at the end of the line is returned. a `GtkTextBuffer` + line="2671">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="2672">iterator to initialize a `GtkTextMark` in @buffer + line="2673">a `GtkTextMark` in @buffer @@ -140056,13 +143164,13 @@ end of the line, the iterator at the end of the line is returned. c:identifier="gtk_text_buffer_get_iter_at_offset"> Initializes @iter to a position @char_offset chars from the start + line="3489">Initializes @iter to a position @char_offset chars from the start of the entire buffer. If @char_offset is -1 or greater than the number of characters in the buffer, @iter is initialized to the end iterator, the iterator one past the last valid character in the buffer. - + @@ -140070,7 +143178,7 @@ the iterator one past the last valid character in the buffer. a `GtkTextBuffer` + line="3491">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="3492">iterator to initialize char offset from start of buffer, counting from 0, or -1 + line="3493">char offset from start of buffer, counting from 0, or -1 @@ -140094,21 +143202,21 @@ the iterator one past the last valid character in the buffer. c:identifier="gtk_text_buffer_get_line_count"> Obtains the number of lines in the buffer. + line="3655">Obtains the number of lines in the buffer. This value is cached, so the function is very fast. - + number of lines in the buffer + line="3663">number of lines in the buffer a `GtkTextBuffer` + line="3657">a `GtkTextBuffer` @@ -140116,26 +143224,26 @@ This value is cached, so the function is very fast. Returns the mark named @name in buffer @buffer, or %NULL if no such + line="2732">Returns the mark named @name in buffer @buffer, or %NULL if no such mark exists in the buffer. - + a `GtkTextMark` + line="2740">a `GtkTextMark` a `GtkTextBuffer` + line="2734">a `GtkTextBuffer` a mark name + line="2735">a mark name @@ -140144,23 +143252,23 @@ mark exists in the buffer. c:identifier="gtk_text_buffer_get_max_undo_levels"> Gets the maximum number of undo levels to perform. + line="5225">Gets the maximum number of undo levels to perform. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer. - + The max number of undo levels allowed (0 indicates unlimited). + line="5235">The max number of undo levels allowed (0 indicates unlimited). a `GtkTextBuffer` + line="5227">a `GtkTextBuffer` @@ -140168,23 +143276,23 @@ copy of the inserted or removed text within the text buffer. Indicates whether the buffer has been modified since the last call + line="3583">Indicates whether the buffer has been modified since the last call to [method@Gtk.TextBuffer.set_modified] set the modification flag to %FALSE. Used for example to enable a “save” function in a text editor. - + %TRUE if the buffer has been modified + line="3593">%TRUE if the buffer has been modified a `GtkTextBuffer` + line="3585">a `GtkTextBuffer` @@ -140193,7 +143301,7 @@ Used for example to enable a “save” function in a text editor. c:identifier="gtk_text_buffer_get_selection_bound"> Returns the mark that represents the selection bound. + line="2836">Returns the mark that represents the selection bound. Equivalent to calling [method@Gtk.TextBuffer.get_mark] to get the mark named “selection_bound”, but very slightly @@ -140205,18 +143313,18 @@ The currently-selected text in @buffer is the region between the [method@Gtk.TextBuffer.get_selection_bounds] is another convenient function for handling the selection, if you just want to know whether there’s a selection and what its bounds are. - + selection bound mark + line="2853">selection bound mark a `GtkTextBuffer` + line="2838">a `GtkTextBuffer` @@ -140225,25 +143333,25 @@ there’s a selection and what its bounds are. c:identifier="gtk_text_buffer_get_selection_bounds"> Returns %TRUE if some text is selected; places the bounds + line="4335">Returns %TRUE if some text is selected; places the bounds of the selection in @start and @end. If the selection has length 0, then @start and @end are filled in with the same value. @start and @end will be in ascending order. If @start and @end are %NULL, then they are not filled in, but the return value still indicates whether text is selected. - + whether the selection has nonzero length + line="4349">whether the selection has nonzero length a `GtkTextBuffer` a `GtkTextBuffer` + line="4337">a `GtkTextBuffer` a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize with selection start + line="4338">iterator to initialize with selection start transfer-ownership="none"> iterator to initialize with selection end + line="4339">iterator to initialize with selection end @@ -140270,22 +143378,22 @@ return value still indicates whether text is selected. c:identifier="gtk_text_buffer_get_selection_content"> Get a content provider for this buffer. + line="4284">Get a content provider for this buffer. It can be used to make the content of @buffer available in a `GdkClipboard`, see [method@Gdk.Clipboard.set_content]. - + a new `GdkContentProvider`. + line="4293">a new `GdkContentProvider`. a `GtkTextBuffer` + line="4286">a `GtkTextBuffer` @@ -140293,7 +143401,7 @@ in a `GdkClipboard`, see [method@Gdk.Clipboard.set_content]. Returns the text in the range [@start,@end). + line="2326">Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. @@ -140303,36 +143411,36 @@ into the returned string do correspond to byte and character indexes into the buffer. Contrast with [method@Gtk.TextBuffer.get_text]. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a paintable or widget is in the buffer. - + an allocated UTF-8 string + line="2344">an allocated UTF-8 string a `GtkTextBuffer` + line="2328">a `GtkTextBuffer` start of a range + line="2329">start of a range end of a range + line="2330">end of a range whether to include invisible text + line="2331">whether to include invisible text @@ -140341,11 +143449,11 @@ reliable indicator that a paintable or widget is in the buffer. c:identifier="gtk_text_buffer_get_start_iter"> Initialized @iter with the first position in the text buffer. + line="3513">Initialized @iter with the first position in the text buffer. This is the same as using [method@Gtk.TextBuffer.get_iter_at_offset] to get the iter at character offset 0. - + @@ -140353,7 +143461,7 @@ to get the iter at character offset 0. a `GtkTextBuffer` + line="3515">a `GtkTextBuffer` transfer-ownership="none"> iterator to initialize + line="3516">iterator to initialize @@ -140370,22 +143478,21 @@ to get the iter at character offset 0. - Get the `GtkTextTagTable` associated with this buffer. - + line="1192">Get the `GtkTextTagTable` associated with this buffer. + the buffer’s tag table + line="1198">the buffer’s tag table a `GtkTextBuffer` + line="1194">a `GtkTextBuffer` @@ -140395,7 +143502,7 @@ to get the iter at character offset 0. glib:get-property="text"> Returns the text in the range [@start,@end). + line="2290">Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. @@ -140403,36 +143510,36 @@ Does not include characters representing embedded images, so byte and character indexes into the returned string do not correspond to byte and character indexes into the buffer. Contrast with [method@Gtk.TextBuffer.get_slice]. - + an allocated UTF-8 string + line="2306">an allocated UTF-8 string a `GtkTextBuffer` + line="2292">a `GtkTextBuffer` start of a range + line="2293">start of a range end of a range + line="2294">end of a range whether to include invisible text + line="2295">whether to include invisible text @@ -140440,7 +143547,7 @@ Contrast with [method@Gtk.TextBuffer.get_slice]. Inserts @len bytes of @text at position @iter. + line="1319">Inserts @len bytes of @text at position @iter. If @len is -1, @text must be nul-terminated and will be inserted in its entirety. Emits the “insert-text” signal; insertion actually occurs @@ -140448,7 +143555,7 @@ in the default handler for the signal. @iter is invalidated when insertion occurs (because the buffer contents change), but the default signal handler revalidates it to point to the end of the inserted text. - + @@ -140456,25 +143563,25 @@ inserted text. a `GtkTextBuffer` + line="1321">a `GtkTextBuffer` a position in the buffer + line="1322">a position in the buffer text in UTF-8 format + line="1323">text in UTF-8 format length of text in bytes, or -1 + line="1324">length of text in bytes, or -1 @@ -140483,11 +143590,11 @@ inserted text. c:identifier="gtk_text_buffer_insert_at_cursor"> Inserts @text in @buffer. + line="1349">Inserts @text in @buffer. Simply calls [method@Gtk.TextBuffer.insert], using the current cursor position as the insertion point. - + @@ -140495,19 +143602,19 @@ using the current cursor position as the insertion point. a `GtkTextBuffer` + line="1351">a `GtkTextBuffer` text in UTF-8 format + line="1352">text in UTF-8 format length of text, in bytes + line="1353">length of text, in bytes @@ -140516,7 +143623,7 @@ using the current cursor position as the insertion point. c:identifier="gtk_text_buffer_insert_child_anchor"> Inserts a child widget anchor into the text buffer at @iter. + line="2422">Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented @@ -140529,7 +143636,7 @@ not. E.g. see [method@Gtk.TextBuffer.get_slice] and Consider [method@Gtk.TextBuffer.create_child_anchor] as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. - + @@ -140537,19 +143644,19 @@ reference to the anchor, so you can unref it after insertion. a `GtkTextBuffer` + line="2424">a `GtkTextBuffer` location to insert the anchor + line="2425">location to insert the anchor a `GtkTextChildAnchor` + line="2426">a `GtkTextChildAnchor` @@ -140558,7 +143665,7 @@ reference to the anchor, so you can unref it after insertion. c:identifier="gtk_text_buffer_insert_interactive"> Inserts @text in @buffer. + line="1376">Inserts @text in @buffer. Like [method@Gtk.TextBuffer.insert], but the insertion will not occur if @iter is at a non-editable location in the buffer. Usually you @@ -140568,42 +143675,42 @@ results from a user action (is interactive). @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. - + whether text was actually inserted + line="1395">whether text was actually inserted a `GtkTextBuffer` + line="1378">a `GtkTextBuffer` a position in @buffer + line="1379">a position in @buffer some UTF-8 text + line="1380">some UTF-8 text length of text in bytes, or -1 + line="1381">length of text in bytes, or -1 default editability of buffer + line="1382">default editability of buffer @@ -140612,7 +143719,7 @@ result of [method@Gtk.TextView.get_editable] is appropriate here. c:identifier="gtk_text_buffer_insert_interactive_at_cursor"> Inserts @text in @buffer. + line="1419">Inserts @text in @buffer. Calls [method@Gtk.TextBuffer.insert_interactive] at the cursor position. @@ -140620,36 +143727,36 @@ at the cursor position. @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. - + whether text was actually inserted + line="1435">whether text was actually inserted a `GtkTextBuffer` + line="1421">a `GtkTextBuffer` text in UTF-8 format + line="1422">text in UTF-8 format length of text in bytes, or -1 + line="1423">length of text in bytes, or -1 default editability of buffer + line="1424">default editability of buffer @@ -140658,13 +143765,13 @@ result of [method@Gtk.TextView.get_editable] is appropriate here. c:identifier="gtk_text_buffer_insert_markup"> Inserts the text in @markup at position @iter. + line="4941">Inserts the text in @markup at position @iter. @markup will be inserted in its entirety and must be nul-terminated and valid UTF-8. Emits the [signal@Gtk.TextBuffer::insert-text] signal, possibly multiple times; insertion actually occurs in the default handler for the signal. @iter will point to the end of the inserted text on return. - + @@ -140672,25 +143779,25 @@ for the signal. @iter will point to the end of the inserted text on return. a `GtkTextBuffer` + line="4943">a `GtkTextBuffer` location to insert the markup + line="4944">location to insert the markup a nul-terminated UTF-8 string containing Pango markup + line="4945">a nul-terminated UTF-8 string containing Pango markup length of @markup in bytes, or -1 + line="4946">length of @markup in bytes, or -1 @@ -140699,7 +143806,7 @@ for the signal. @iter will point to the end of the inserted text on return. Inserts an image into the text buffer at @iter. + line="2378">Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be @@ -140708,7 +143815,7 @@ Note that the “slice” variants for obtaining portions of the buffer as a string include this character for paintable, but the “text” variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. - + @@ -140716,19 +143823,19 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and a `GtkTextBuffer` + line="2380">a `GtkTextBuffer` location to insert the paintable + line="2381">location to insert the paintable a `GdkPaintable` + line="2382">a `GdkPaintable` @@ -140736,7 +143843,7 @@ variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and Copies text, tags, and paintables between @start and @end + line="1806">Copies text, tags, and paintables between @start and @end and inserts the copy at @iter. The order of @start and @end doesn’t matter. @@ -140747,7 +143854,7 @@ images and tags. If @start and @end are in a different buffer from Implemented via emissions of the ::insert-text and ::apply-tag signals, so expect those. - + @@ -140755,25 +143862,25 @@ so expect those. a `GtkTextBuffer` + line="1808">a `GtkTextBuffer` a position in @buffer + line="1809">a position in @buffer a position in a `GtkTextBuffer` + line="1810">a position in a `GtkTextBuffer` another position in the same buffer as @start + line="1811">another position in the same buffer as @start @@ -140782,7 +143889,7 @@ so expect those. c:identifier="gtk_text_buffer_insert_range_interactive"> Copies text, tags, and paintables between @start and @end + line="1844">Copies text, tags, and paintables between @start and @end and inserts the copy at @iter. Same as [method@Gtk.TextBuffer.insert_range], but does nothing @@ -140790,42 +143897,42 @@ if the insertion point isn’t editable. The @default_editable parameter indicates whether the text is editable at @iter if no tags enclosing @iter affect editability. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. - + whether an insertion was possible at @iter + line="1861">whether an insertion was possible at @iter a `GtkTextBuffer` + line="1846">a `GtkTextBuffer` a position in @buffer + line="1847">a position in @buffer a position in a `GtkTextBuffer` + line="1848">a position in a `GtkTextBuffer` another position in the same buffer as @start + line="1849">another position in the same buffer as @start default editability of the buffer + line="1850">default editability of the buffer @@ -140835,14 +143942,14 @@ of [method@Gtk.TextView.get_editable] is appropriate here. introspectable="0"> Inserts @text into @buffer at @iter, applying the list of tags to + line="1888">Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. The last tag specified must be %NULL to terminate the list. Equivalent to calling [method@Gtk.TextBuffer.insert], then [method@Gtk.TextBuffer.apply_tag] on the inserted text; this is just a convenience function. - + @@ -140850,37 +143957,37 @@ this is just a convenience function. a `GtkTextBuffer` + line="1890">a `GtkTextBuffer` an iterator in @buffer + line="1891">an iterator in @buffer UTF-8 text + line="1892">UTF-8 text length of @text, or -1 + line="1893">length of @text, or -1 first tag to apply to @text + line="1894">first tag to apply to @text %NULL-terminated list of tags to apply + line="1895">%NULL-terminated list of tags to apply @@ -140890,12 +143997,12 @@ this is just a convenience function. introspectable="0"> Inserts @text into @buffer at @iter, applying the list of tags to + line="1944">Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. Same as [method@Gtk.TextBuffer.insert_with_tags], but allows you to pass in tag names instead of tag objects. - + @@ -140903,37 +144010,37 @@ to pass in tag names instead of tag objects. a `GtkTextBuffer` + line="1946">a `GtkTextBuffer` position in @buffer + line="1947">position in @buffer UTF-8 text + line="1948">UTF-8 text length of @text, or -1 + line="1949">length of @text, or -1 name of a tag to apply to @text + line="1950">name of a tag to apply to @text more tag names + line="1951">more tag names @@ -140941,11 +144048,11 @@ to pass in tag names instead of tag objects. Moves @mark to the new location @where. + line="2646">Moves @mark to the new location @where. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the move. - + @@ -140953,19 +144060,19 @@ as notification of the move. a `GtkTextBuffer` + line="2648">a `GtkTextBuffer` a `GtkTextMark` + line="2649">a `GtkTextMark` new location for @mark in @buffer + line="2650">new location for @mark in @buffer @@ -140974,10 +144081,10 @@ as notification of the move. c:identifier="gtk_text_buffer_move_mark_by_name"> Moves the mark named @name (which must exist) to location @where. + line="2756">Moves the mark named @name (which must exist) to location @where. See [method@Gtk.TextBuffer.move_mark] for details. - + @@ -140985,19 +144092,19 @@ See [method@Gtk.TextBuffer.move_mark] for details. a `GtkTextBuffer` + line="2758">a `GtkTextBuffer` name of a mark + line="2759">name of a mark new location for mark + line="2760">new location for mark @@ -141006,7 +144113,7 @@ See [method@Gtk.TextBuffer.move_mark] for details. c:identifier="gtk_text_buffer_paste_clipboard"> Pastes the contents of a clipboard. + line="4049">Pastes the contents of a clipboard. If @override_location is %NULL, the pasted text will be inserted at the cursor position, or the buffer selection will be replaced @@ -141015,7 +144122,7 @@ if the selection is non-empty. Note: pasting is asynchronous, that is, we’ll ask for the paste data and return, and at some point later after the main loop runs, the paste data will be inserted. - + @@ -141023,13 +144130,13 @@ data will be inserted. a `GtkTextBuffer` + line="4051">a `GtkTextBuffer` the `GdkClipboard` to paste from + line="4052">the `GdkClipboard` to paste from allow-none="1"> location to insert pasted text + line="4053">location to insert pasted text whether the buffer is editable by default + line="4054">whether the buffer is editable by default @@ -141052,7 +144159,7 @@ data will be inserted. This function moves the “insert” and “selection_bound” marks + line="2886">This function moves the “insert” and “selection_bound” marks simultaneously. If you move them to the same place in two steps with @@ -141061,7 +144168,7 @@ region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. - + @@ -141069,13 +144176,13 @@ be optimized. a `GtkTextBuffer` + line="2888">a `GtkTextBuffer` where to put the cursor + line="2889">where to put the cursor @@ -141083,8 +144190,8 @@ be optimized. Redoes the next redoable action on the buffer, if there is one. - + line="5110">Redoes the next redoable action on the buffer, if there is one. + @@ -141092,7 +144199,7 @@ be optimized. a `GtkTextBuffer` + line="5112">a `GtkTextBuffer` @@ -141101,13 +144208,13 @@ be optimized. c:identifier="gtk_text_buffer_remove_all_tags"> Removes all tags in the range between @start and @end. + line="3247">Removes all tags in the range between @start and @end. Be careful with this function; it could remove tags added in code unrelated to the code you’re currently writing. That is, using this function is probably a bad idea if you have two or more unrelated code sections that add tags. - + @@ -141115,30 +144222,60 @@ code sections that add tags. a `GtkTextBuffer` + line="3249">a `GtkTextBuffer` one bound of range to be untagged + line="3250">one bound of range to be untagged other bound of range to be untagged + line="3251">other bound of range to be untagged + + Removes the `GtkTextBufferCommitNotify` handler previously registered +with [method@Gtk.TextBuffer.add_commit_notify]. + +This may result in the `user_data_destroy` being called that was passed when registering +the commit notify functions. + + + + + + + a `GtkTextBuffer` + + + + the notify handler identifier returned from + [method@Gtk.TextBuffer.add_commit_notify]. + + + + Removes a `GdkClipboard` added with + line="3996">Removes a `GdkClipboard` added with [method@Gtk.TextBuffer.add_selection_clipboard] - + @@ -141146,13 +144283,13 @@ code sections that add tags. a `GtkTextBuffer` + line="3998">a `GtkTextBuffer` a `GdkClipboard` added to @buffer by + line="3999">a `GdkClipboard` added to @buffer by [method@Gtk.TextBuffer.add_selection_clipboard] @@ -141161,12 +144298,12 @@ code sections that add tags. Emits the “remove-tag” signal. + line="3124">Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. - + @@ -141174,25 +144311,25 @@ to be in order. a `GtkTextBuffer` + line="3126">a `GtkTextBuffer` a `GtkTextTag` + line="3127">a `GtkTextTag` one bound of range to be untagged + line="3128">one bound of range to be untagged other bound of range to be untagged + line="3129">other bound of range to be untagged @@ -141201,12 +144338,12 @@ to be in order. c:identifier="gtk_text_buffer_remove_tag_by_name"> Emits the “remove-tag” signal. + line="3195">Emits the “remove-tag” signal. Calls [method@Gtk.TextTagTable.lookup] on the buffer’s tag table to get a `GtkTextTag`, then calls [method@Gtk.TextBuffer.remove_tag]. - + @@ -141214,25 +144351,25 @@ tag table to get a `GtkTextTag`, then calls a `GtkTextBuffer` + line="3197">a `GtkTextBuffer` name of a `GtkTextTag` + line="3198">name of a `GtkTextTag` one bound of range to be untagged + line="3199">one bound of range to be untagged other bound of range to be untagged + line="3200">other bound of range to be untagged @@ -141240,7 +144377,7 @@ tag table to get a `GtkTextTag`, then calls This function moves the “insert” and “selection_bound” marks + line="2908">This function moves the “insert” and “selection_bound” marks simultaneously. If you move them in two steps with @@ -141249,7 +144386,7 @@ region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. - + @@ -141257,19 +144394,19 @@ be optimized. a `GtkTextBuffer` + line="2910">a `GtkTextBuffer` where to put the “insert” mark + line="2911">where to put the “insert” mark where to put the “selection_bound” mark + line="2912">where to put the “selection_bound” mark @@ -141277,10 +144414,9 @@ be optimized. - Sets whether or not to enable undoable actions in the text buffer. + line="5146">Sets whether or not to enable undoable actions in the text buffer. Undoable actions in this context are changes to the text content of the buffer. Changes to tags and marks are not tracked. @@ -141291,7 +144427,7 @@ up to [method@Gtk.TextBuffer.get_max_undo_levels]. See [method@Gtk.TextBuffer.begin_irreversible_action] and [method@Gtk.TextBuffer.end_irreversible_action] to create changes to the buffer that cannot be undone. - + @@ -141299,13 +144435,13 @@ changes to the buffer that cannot be undone. a `GtkTextBuffer` + line="5148">a `GtkTextBuffer` %TRUE to enable undo + line="5149">%TRUE to enable undo @@ -141314,12 +144450,12 @@ changes to the buffer that cannot be undone. c:identifier="gtk_text_buffer_set_max_undo_levels"> Sets the maximum number of undo levels to perform. + line="5245">Sets the maximum number of undo levels to perform. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer. - + @@ -141327,13 +144463,13 @@ copy of the inserted or removed text within the text buffer. a `GtkTextBuffer` + line="5247">a `GtkTextBuffer` the maximum number of undo actions to perform + line="5248">the maximum number of undo actions to perform @@ -141341,7 +144477,7 @@ copy of the inserted or removed text within the text buffer. Used to keep track of whether the buffer has been + line="3603">Used to keep track of whether the buffer has been modified since the last time it was saved. Whenever the buffer is saved to disk, call @@ -141350,7 +144486,7 @@ When the buffer is modified, it will automatically toggle on the modified bit again. When the modified bit flips, the buffer emits the [signal@Gtk.TextBuffer::modified-changed] signal. - + @@ -141358,13 +144494,13 @@ bit flips, the buffer emits the a `GtkTextBuffer` + line="3605">a `GtkTextBuffer` modification flag setting + line="3606">modification flag setting @@ -141372,17 +144508,16 @@ bit flips, the buffer emits the - Deletes current contents of @buffer, and inserts @text instead. This is + line="1208">Deletes current contents of @buffer, and inserts @text instead. This is automatically marked as an irreversible action in the undo stack. If you wish to mark this action as part of a larger undo operation, call [method@TextBuffer.delete] and [method@TextBuffer.insert] directly instead. If @len is -1, @text must be nul-terminated. @text must be valid UTF-8. - + @@ -141390,19 +144525,19 @@ If @len is -1, @text must be nul-terminated. a `GtkTextBuffer` + line="1210">a `GtkTextBuffer` UTF-8 text to insert + line="1211">UTF-8 text to insert length of @text in bytes + line="1212">length of @text in bytes @@ -141410,8 +144545,8 @@ If @len is -1, @text must be nul-terminated. Undoes the last undoable action on the buffer, if there is one. - + line="5095">Undoes the last undoable action on the buffer, if there is one. + @@ -141419,7 +144554,7 @@ If @len is -1, @text must be nul-terminated. a `GtkTextBuffer` + line="5097">a `GtkTextBuffer` @@ -141428,22 +144563,18 @@ If @len is -1, @text must be nul-terminated. transfer-ownership="none" getter="get_can_redo" default-value="FALSE"> - Denotes that the buffer can reapply the last undone action. + line="568">Denotes that the buffer can reapply the last undone action. - Denotes that the buffer can undo the last applied action. + line="558">Denotes that the buffer can undo the last applied action. The position of the insert mark. + line="588">The position of the insert mark. This is an offset from the beginning of the buffer. It is useful for getting notified when the cursor moves. @@ -141463,13 +144594,9 @@ It is useful for getting notified when the cursor moves. setter="set_enable_undo" getter="get_enable_undo" default-value="TRUE"> - - Denotes if support for undoing and redoing changes to the buffer is allowed. + line="578">Denotes if support for undoing and redoing changes to the buffer is allowed. default-value="FALSE"> Whether the buffer has some text currently selected. + line="548">Whether the buffer has some text currently selected. construct-only="1" transfer-ownership="none" getter="get_tag_table"> - The GtkTextTagTable for the buffer. + line="523">The GtkTextTagTable for the buffer. transfer-ownership="none" setter="set_text" getter="get_text"> - The text content of the buffer. + line="535">The text content of the buffer. Without child widgets and images, see [method@Gtk.TextBuffer.get_text] for more information. @@ -141517,7 +144640,7 @@ see [method@Gtk.TextBuffer.get_text] for more information. Emitted to apply a tag to a range of text in a `GtkTextBuffer`. + line="817">Emitted to apply a tag to a range of text in a `GtkTextBuffer`. Applying actually occurs in the default handler. @@ -141536,19 +144659,19 @@ See also: the applied tag + line="820">the applied tag the start of the range the tag is applied to + line="821">the start of the range the tag is applied to the end of the range the tag is applied to + line="822">the end of the range the tag is applied to @@ -141556,7 +144679,7 @@ See also: Emitted at the beginning of a single user-visible + line="887">Emitted at the beginning of a single user-visible operation on a `GtkTextBuffer`. See also: @@ -141573,7 +144696,7 @@ See also: Emitted when the content of a `GtkTextBuffer` has changed. + line="736">Emitted when the content of a `GtkTextBuffer` has changed. @@ -141581,7 +144704,7 @@ See also: Emitted to delete a range from a `GtkTextBuffer`. + line="703">Emitted to delete a range from a `GtkTextBuffer`. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has @@ -141599,13 +144722,13 @@ See also: [method@Gtk.TextBuffer.delete]. the start of the range to be deleted + line="706">the start of the range to be deleted the end of the range to be deleted + line="707">the end of the range to be deleted @@ -141613,7 +144736,7 @@ See also: [method@Gtk.TextBuffer.delete]. Emitted at the end of a single user-visible + line="912">Emitted at the end of a single user-visible operation on the `GtkTextBuffer`. See also: @@ -141631,7 +144754,7 @@ See also: Emitted to insert a `GtkTextChildAnchor` in a `GtkTextBuffer`. + line="671">Emitted to insert a `GtkTextChildAnchor` in a `GtkTextBuffer`. Insertion actually occurs in the default handler. @@ -141648,13 +144771,13 @@ See also: [method@Gtk.TextBuffer.insert_child_anchor]. position to insert @anchor in @textbuffer + line="674">position to insert @anchor in @textbuffer the `GtkTextChildAnchor` to be inserted + line="675">the `GtkTextChildAnchor` to be inserted @@ -141662,7 +144785,7 @@ See also: [method@Gtk.TextBuffer.insert_child_anchor]. Emitted to insert a `GdkPaintable` in a `GtkTextBuffer`. + line="638">Emitted to insert a `GdkPaintable` in a `GtkTextBuffer`. Insertion actually occurs in the default handler. @@ -141679,13 +144802,13 @@ See also: [method@Gtk.TextBuffer.insert_paintable]. position to insert @paintable in @textbuffer + line="641">position to insert @paintable in @textbuffer the `GdkPaintable` to be inserted + line="642">the `GdkPaintable` to be inserted @@ -141693,7 +144816,7 @@ See also: [method@Gtk.TextBuffer.insert_paintable]. Emitted to insert text in a `GtkTextBuffer`. + line="604">Emitted to insert text in a `GtkTextBuffer`. Insertion actually occurs in the default handler. @@ -141711,19 +144834,19 @@ See also: [method@Gtk.TextBuffer.insert], position to insert @text in @textbuffer + line="607">position to insert @text in @textbuffer the UTF-8 text to be inserted + line="608">the UTF-8 text to be inserted length of the inserted text in bytes + line="609">length of the inserted text in bytes @@ -141731,7 +144854,7 @@ See also: [method@Gtk.TextBuffer.insert], Emitted as notification after a `GtkTextMark` is deleted. + line="797">Emitted as notification after a `GtkTextMark` is deleted. See also: [method@Gtk.TextBuffer.delete_mark]. @@ -141741,7 +144864,7 @@ See also: [method@Gtk.TextBuffer.delete_mark]. The mark that was deleted + line="800">The mark that was deleted @@ -141749,7 +144872,7 @@ See also: [method@Gtk.TextBuffer.delete_mark]. Emitted as notification after a `GtkTextMark` is set. + line="770">Emitted as notification after a `GtkTextMark` is set. See also: [method@Gtk.TextBuffer.create_mark], @@ -141761,13 +144884,13 @@ See also: The location of @mark in @textbuffer + line="773">The location of @mark in @textbuffer The mark that is set + line="774">The mark that is set @@ -141775,7 +144898,7 @@ See also: Emitted when the modified bit of a `GtkTextBuffer` flips. + line="752">Emitted when the modified bit of a `GtkTextBuffer` flips. See also: [method@Gtk.TextBuffer.set_modified]. @@ -141785,7 +144908,7 @@ See also: [method@Gtk.TextBuffer.set_modified]. Emitted after paste operation has been completed. + line="938">Emitted after paste operation has been completed. This is useful to properly scroll the view to the end of the pasted text. See [method@Gtk.TextBuffer.paste_clipboard] @@ -141797,7 +144920,7 @@ for more details. the `GdkClipboard` pasted from + line="941">the `GdkClipboard` pasted from @@ -141805,7 +144928,7 @@ for more details. Emitted when a request has been made to redo the + line="960">Emitted when a request has been made to redo the previously undone operation. @@ -141814,7 +144937,7 @@ previously undone operation. Emitted to remove all occurrences of @tag from a range + line="853">Emitted to remove all occurrences of @tag from a range of text in a `GtkTextBuffer`. Removal actually occurs in the default handler. @@ -141831,19 +144954,19 @@ See also: [method@Gtk.TextBuffer.remove_tag]. the tag to be removed + line="856">the tag to be removed the start of the range the tag is removed from + line="857">the start of the range the tag is removed from the end of the range the tag is removed from + line="858">the end of the range the tag is removed from @@ -141851,7 +144974,7 @@ See also: [method@Gtk.TextBuffer.remove_tag]. Emitted when a request has been made to undo the + line="974">Emitted when a request has been made to undo the previous operation or set of operations that have been grouped together. @@ -141864,17 +144987,20 @@ been grouped together. glib:is-gtype-struct-for="TextBuffer"> The class structure for `GtkTextBuffer`. - + line="105">The class structure for `GtkTextBuffer`. + The object class structure needs to be the first. + line="107">The object class structure needs to be the first. + The class handler for the `GtkTextBuffer::insert-text` signal. - + @@ -141895,8 +145021,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::insert-paintable` signal. - + @@ -141904,27 +145033,30 @@ been grouped together. a `GtkTextBuffer` + line="2380">a `GtkTextBuffer` location to insert the paintable + line="2381">location to insert the paintable a `GdkPaintable` + line="2382">a `GdkPaintable` + The class handler for the `GtkTextBuffer::insert-child-anchor` signal. - + @@ -141932,27 +145064,30 @@ been grouped together. a `GtkTextBuffer` + line="2424">a `GtkTextBuffer` location to insert the anchor + line="2425">location to insert the anchor a `GtkTextChildAnchor` + line="2426">a `GtkTextChildAnchor` + The class handler for the `GtkTextBuffer::delete-range` signal. - + @@ -141970,8 +145105,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::changed` signal. - + @@ -141983,8 +145121,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::modified-changed` signal. - + @@ -141996,8 +145137,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::mark-set` signal. - + @@ -142015,8 +145159,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::mark-deleted` signal. - + @@ -142031,8 +145178,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::apply-tag` signal. - + @@ -142040,33 +145190,36 @@ been grouped together. a `GtkTextBuffer` + line="3096">a `GtkTextBuffer` a `GtkTextTag` + line="3097">a `GtkTextTag` one bound of range to be tagged + line="3098">one bound of range to be tagged other bound of range to be tagged + line="3099">other bound of range to be tagged + The class handler for the `GtkTextBuffer::remove-tag` signal. - + @@ -142074,33 +145227,36 @@ been grouped together. a `GtkTextBuffer` + line="3126">a `GtkTextBuffer` a `GtkTextTag` + line="3127">a `GtkTextTag` one bound of range to be untagged + line="3128">one bound of range to be untagged other bound of range to be untagged + line="3129">other bound of range to be untagged + The class handler for the `GtkTextBuffer::begin-user-action` signal. - + @@ -142108,15 +145264,18 @@ been grouped together. a `GtkTextBuffer` + line="4363">a `GtkTextBuffer` + The class handler for the `GtkTextBuffer::end-user-action` signal. - + @@ -142124,15 +145283,18 @@ been grouped together. a `GtkTextBuffer` + line="4401">a `GtkTextBuffer` + The class handler for the `GtkTextBuffer::paste-done` signal. - + @@ -142147,8 +145309,11 @@ been grouped together. + The class handler for the `GtkTextBuffer::undo` signal - + @@ -142156,15 +145321,18 @@ been grouped together. a `GtkTextBuffer` + line="5097">a `GtkTextBuffer` + The class handler for the `GtkTextBuffer::redo` signal - + @@ -142172,7 +145340,7 @@ been grouped together. a `GtkTextBuffer` + line="5112">a `GtkTextBuffer` @@ -142180,7 +145348,7 @@ been grouped together. - + @@ -142188,7 +145356,7 @@ been grouped together. - + @@ -142196,7 +145364,7 @@ been grouped together. - + @@ -142204,13 +145372,142 @@ been grouped together. - + + + A notification callback used by [method@Gtk.TextBuffer.add_commit_notify]. + +You may not modify the [class@Gtk.TextBuffer] from a +[callback@Gtk.TextBufferCommitNotify] callback and that is enforced +by the [class@Gtk.TextBuffer] API. + +[callback@Gtk.TextBufferCommitNotify] may be used to be notified about +changes to the underlying buffer right before-or-after the changes are +committed to the underlying B-Tree. This is useful if you want to observe +changes to the buffer without other signal handlers potentially modifying +state on the way to the default signal handler. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_BEFORE_INSERT`, `position` is set to +the offset in characters from the start of the buffer where the insertion +will occur. `length` is set to the number of characters to be inserted. You +may not yet retrieve the text until it has been inserted. You may access the +text from `GTK_TEXT_BUFFER_NOTIFY_AFTER_INSERT` using +[method@Gtk.TextBuffer.get_slice]. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_AFTER_INSERT`, `position` is set to +offset in characters where the insertion occurred and `length` is set +to the number of characters inserted. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_BEFORE_DELETE`, `position` is set to +offset in characters where the deletion will occur and `length` is set +to the number of characters that will be removed. You may still retrieve +the text from this handler using `position` and `length`. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_AFTER_DELETE`, `length` is set to +zero to denote that the delete-range has already been committed to the +underlying B-Tree. You may no longer retrieve the text that has been +deleted from the [class@Gtk.TextBuffer]. + + + + + + + the text buffer being notified + + + + the type of commit notification + + + + the position of the text operation + + + + the length of the text operation in characters + + + + user data passed to the callback + + + + + + Values for [callback@Gtk.TextBufferCommitNotify] to denote the +point of the notification. + + Be notified before text + is inserted into the underlying buffer. + + + Be notified after text + has been inserted into the underlying buffer. + + + Be notified before text + is deleted from the underlying buffer. + + + Be notified after text + has been deleted from the underlying buffer. + + glib:type-struct="TextChildAnchorClass"> A `GtkTextChildAnchor` is a spot in a `GtkTextBuffer` where child widgets can -be “anchored”. + line="38">Marks a spot in a `GtkTextBuffer` where child widgets can be “anchored”. The anchor can have multiple widgets anchored, to allow for multiple views. - + - + Usually you would then insert it into a `GtkTextBuffer` with [method@Gtk.TextBuffer.insert_child_anchor]. - + a new `GtkTextChildAnchor` + line="424">a new `GtkTextChildAnchor` + a replacement character @@ -142306,7 +145605,7 @@ Usually you would then insert it into a `GtkTextBuffer` with c:identifier="gtk_text_child_anchor_get_deleted"> Determines whether a child anchor has been deleted from + line="521">Determines whether a child anchor has been deleted from the buffer. Keep in mind that the child anchor will be unreferenced @@ -142314,18 +145613,18 @@ when removed from the buffer, so you need to hold your own reference (with g_object_ref()) if you plan to use this function — otherwise all deleted child anchors will also be finalized. - + %TRUE if the child anchor has been deleted from its buffer + line="534">%TRUE if the child anchor has been deleted from its buffer a `GtkTextChildAnchor` + line="523">a `GtkTextChildAnchor` @@ -142334,14 +145633,14 @@ be finalized. c:identifier="gtk_text_child_anchor_get_widgets"> Gets a list of all widgets anchored at this child anchor. + line="473">Gets a list of all widgets anchored at this child anchor. The order in which the widgets are returned is not defined. - + an + line="482">an array of widgets anchored at @anchor @@ -142351,7 +145650,7 @@ The order in which the widgets are returned is not defined. a `GtkTextChildAnchor` + line="475">a `GtkTextChildAnchor` transfer-ownership="full"> return location for the length of the array + line="476">return location for the length of the array @@ -142375,13 +145674,13 @@ The order in which the widgets are returned is not defined. - + - + @@ -142389,7 +145688,7 @@ The order in which the widgets are returned is not defined. - + @@ -142397,7 +145696,7 @@ The order in which the widgets are returned is not defined. - + @@ -142405,7 +145704,7 @@ The order in which the widgets are returned is not defined. - + @@ -142418,7 +145717,7 @@ The order in which the widgets are returned is not defined. c:type="GtkTextDirection"> Reading directions for text. + line="258">Reading directions for text. glib:name="GTK_TEXT_DIR_NONE"> No direction. + line="260">No direction. glib:name="GTK_TEXT_DIR_LTR"> Left to right text direction. + line="261">Left to right text direction. glib:name="GTK_TEXT_DIR_RTL"> Right to left text direction. + line="262">Right to left text direction. c:symbol-prefix="text_iter"> An iterator for the contents of a `GtkTextBuffer`. + line="35">Iterates over the contents of a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), @@ -142535,7 +145834,7 @@ related to the text widget and how they work together. Assigns the value of @other to @iter. + line="449">Assigns the value of @other to @iter. This function is not useful in applications, because iterators can be assigned with `GtkTextIter i = j;`. @@ -142549,13 +145848,13 @@ The function is used by language bindings. a `GtkTextIter` + line="451">a `GtkTextIter` another `GtkTextIter` + line="452">another `GtkTextIter` @@ -142563,7 +145862,7 @@ The function is used by language bindings. Moves backward by one character offset. + line="2262">Moves backward by one character offset. Returns %TRUE if movement was possible; if @iter was the first in the buffer (character offset 0), this function returns %FALSE @@ -142572,14 +145871,14 @@ for convenience when writing loops. whether movement was possible + line="2272">whether movement was possible an iterator + line="2264">an iterator @@ -142588,7 +145887,7 @@ for convenience when writing loops. c:identifier="gtk_text_iter_backward_chars"> Moves @count characters backward, if possible. + line="2373">Moves @count characters backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. @@ -142601,20 +145900,20 @@ the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable + line="2388">whether @iter moved and is dereferenceable an iterator + line="2375">an iterator number of characters to move + line="2376">number of characters to move @@ -142623,19 +145922,19 @@ the function does nothing and returns %FALSE. c:identifier="gtk_text_iter_backward_cursor_position"> Like [method@Gtk.TextIter.forward_cursor_position], but moves backward. + line="3707">Like [method@Gtk.TextIter.forward_cursor_position], but moves backward. %TRUE if we moved + line="3713">%TRUE if we moved a `GtkTextIter` + line="3709">a `GtkTextIter` @@ -142644,27 +145943,27 @@ the function does nothing and returns %FALSE. c:identifier="gtk_text_iter_backward_cursor_positions"> Moves up to @count cursor positions. + line="3741">Moves up to @count cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable + line="3750">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3743">a `GtkTextIter` number of positions to move + line="3744">number of positions to move @@ -142673,20 +145972,20 @@ See [method@Gtk.TextIter.forward_cursor_position] for details. c:identifier="gtk_text_iter_backward_find_char"> Same as [method@Gtk.TextIter.forward_find_char], + line="4472">Same as [method@Gtk.TextIter.forward_find_char], but goes backward from @iter. whether a match was found + line="4482">whether a match was found a `GtkTextIter` + line="4474">a `GtkTextIter` closure="1"> function to be called on each character + line="4475">function to be called on each character allow-none="1"> user data for @pred + line="4476">user data for @pred allow-none="1"> search limit + line="4477">search limit @@ -142721,7 +146020,7 @@ but goes backward from @iter. Moves @iter to the start of the previous line. + line="2585">Moves @iter to the start of the previous line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore, @@ -142734,14 +146033,14 @@ every iteration, if your first iteration is on line 0.) whether @iter moved + line="2599">whether @iter moved an iterator + line="2587">an iterator @@ -142750,7 +146049,7 @@ every iteration, if your first iteration is on line 0.) c:identifier="gtk_text_iter_backward_lines"> Moves @count lines backward, if possible. + line="2719">Moves @count lines backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. @@ -142764,20 +146063,20 @@ moves forward by 0 - @count lines. whether @iter moved and is dereferenceable + line="2735">whether @iter moved and is dereferenceable a `GtkTextIter` + line="2721">a `GtkTextIter` number of lines to move backward + line="2722">number of lines to move backward @@ -142786,7 +146085,7 @@ moves forward by 0 - @count lines. c:identifier="gtk_text_iter_backward_search"> Same as [method@Gtk.TextIter.forward_search], but moves backward. + line="5282">Same as [method@Gtk.TextIter.forward_search], but moves backward. @match_end will never be set to a `GtkTextIter` located after @iter, even if there is a possible @match_start before or at @iter. @@ -142794,26 +146093,26 @@ even if there is a possible @match_start before or at @iter. whether a match was found + line="5296">whether a match was found a `GtkTextIter` where the search begins + line="5284">a `GtkTextIter` where the search begins search string + line="5285">search string bitmask of flags affecting the search + line="5286">bitmask of flags affecting the search allow-none="1"> return location for start of match + line="5287">return location for start of match allow-none="1"> return location for end of match + line="5288">return location for end of match allow-none="1"> location of last possible @match_start, or %NULL for start of buffer + line="5289">location of last possible @match_start, or %NULL for start of buffer @@ -142853,7 +146152,7 @@ even if there is a possible @match_start before or at @iter. c:identifier="gtk_text_iter_backward_sentence_start"> Moves backward to the previous sentence start. + line="3559">Moves backward to the previous sentence start. If @iter is already at the start of a sentence, moves backward to the next one. @@ -142864,14 +146163,14 @@ be correct for nearly any language. %TRUE if @iter moved and is not the end iterator + line="3571">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3561">a `GtkTextIter` @@ -142880,27 +146179,27 @@ be correct for nearly any language. c:identifier="gtk_text_iter_backward_sentence_starts"> Calls [method@Gtk.TextIter.backward_sentence_start] up to @count times. + line="3602">Calls [method@Gtk.TextIter.backward_sentence_start] up to @count times. If @count is negative, moves forward instead of backward. %TRUE if @iter moved and is not the end iterator + line="3611">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3604">a `GtkTextIter` number of sentences to move + line="3605">number of sentences to move @@ -142909,7 +146208,7 @@ If @count is negative, moves forward instead of backward. c:identifier="gtk_text_iter_backward_to_tag_toggle"> Moves backward to the next toggle (on or off) of the + line="4318">Moves backward to the next toggle (on or off) of the @tag, or to the next toggle of any tag if @tag is %NULL. @@ -142922,14 +146221,14 @@ if no toggle is found. whether we found a tag toggle before @iter + line="4333">whether we found a tag toggle before @iter a `GtkTextIter` + line="4320">a `GtkTextIter` allow-none="1"> a `GtkTextTag` + line="4321">a `GtkTextTag` @@ -142947,21 +146246,21 @@ if no toggle is found. c:identifier="gtk_text_iter_backward_visible_cursor_position"> Moves @iter backward to the previous visible cursor position. + line="3777">Moves @iter backward to the previous visible cursor position. See [method@Gtk.TextIter.backward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable + line="3785">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3779">a `GtkTextIter` @@ -142970,27 +146269,27 @@ See [method@Gtk.TextIter.backward_cursor_position] for details. c:identifier="gtk_text_iter_backward_visible_cursor_positions"> Moves up to @count visible cursor positions. + line="3813">Moves up to @count visible cursor positions. See [method@Gtk.TextIter.backward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable + line="3822">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3815">a `GtkTextIter` number of positions to move + line="3816">number of positions to move @@ -142999,7 +146298,7 @@ See [method@Gtk.TextIter.backward_cursor_position] for details. c:identifier="gtk_text_iter_backward_visible_line"> Moves @iter to the start of the previous visible line. + line="2799">Moves @iter to the start of the previous visible line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this @@ -143012,14 +146311,14 @@ every iteration, if your first iteration is on line 0.) whether @iter moved + line="2813">whether @iter moved an iterator + line="2801">an iterator @@ -143028,7 +146327,7 @@ every iteration, if your first iteration is on line 0.) c:identifier="gtk_text_iter_backward_visible_lines"> Moves @count visible lines backward, if possible. + line="2880">Moves @count visible lines backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. @@ -143042,20 +146341,20 @@ moves forward by 0 - @count lines. whether @iter moved and is dereferenceable + line="2896">whether @iter moved and is dereferenceable a `GtkTextIter` + line="2882">a `GtkTextIter` number of lines to move backward + line="2883">number of lines to move backward @@ -143064,7 +146363,7 @@ moves forward by 0 - @count lines. c:identifier="gtk_text_iter_backward_visible_word_start"> Moves backward to the previous visible word start. + line="3374">Moves backward to the previous visible word start. If @iter is currently on a word start, moves backward to the next one after that. @@ -143075,14 +146374,14 @@ for nearly any language. %TRUE if @iter moved and is not the end iterator + line="3386">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3376">a `GtkTextIter` @@ -143091,25 +146390,25 @@ for nearly any language. c:identifier="gtk_text_iter_backward_visible_word_starts"> Calls [method@Gtk.TextIter.backward_visible_word_start] up to @count times. + line="3412">Calls [method@Gtk.TextIter.backward_visible_word_start] up to @count times. %TRUE if @iter moved and is not the end iterator + line="3419">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3414">a `GtkTextIter` number of times to move + line="3415">number of times to move @@ -143118,7 +146417,7 @@ for nearly any language. c:identifier="gtk_text_iter_backward_word_start"> Moves backward to the previous word start. + line="3294">Moves backward to the previous word start. If @iter is currently on a word start, moves backward to the next one after that. @@ -143129,14 +146428,14 @@ for nearly any language %TRUE if @iter moved and is not the end iterator + line="3306">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3296">a `GtkTextIter` @@ -143145,25 +146444,25 @@ for nearly any language c:identifier="gtk_text_iter_backward_word_starts"> Calls [method@Gtk.TextIter.backward_word_start] up to @count times. + line="3336">Calls [method@Gtk.TextIter.backward_word_start] up to @count times. %TRUE if @iter moved and is not the end iterator + line="3343">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3338">a `GtkTextIter` number of times to move + line="3339">number of times to move @@ -143171,7 +146470,7 @@ for nearly any language Considering the default editability of the buffer, and tags that + line="1457">Considering the default editability of the buffer, and tags that affect editability, determines whether text inserted at @iter would be editable. @@ -143183,20 +146482,20 @@ to decide whether insertions are allowed at a given position. whether text inserted at @iter would be editable + line="1471">whether text inserted at @iter would be editable an iterator + line="1459">an iterator %TRUE if text is editable by default + line="1460">%TRUE if text is editable by default @@ -143204,7 +146503,7 @@ to decide whether insertions are allowed at a given position. A qsort()-style function that returns negative if @lhs is less than + line="5493">A qsort()-style function that returns negative if @lhs is less than @rhs, positive if @lhs is greater than @rhs, and 0 if they’re equal. Ordering is in character offset order, i.e. the first character @@ -143213,20 +146512,20 @@ in the buffer is less than the second character in the buffer. -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal + line="5504">-1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal a `GtkTextIter` + line="5495">a `GtkTextIter` another `GtkTextIter` + line="5496">another `GtkTextIter` @@ -143234,7 +146533,7 @@ in the buffer is less than the second character in the buffer. Creates a dynamically-allocated copy of an iterator. + line="403">Creates a dynamically-allocated copy of an iterator. This function is not useful in applications, because iterators can be copied with a simple assignment @@ -143245,14 +146544,14 @@ The function is used by language bindings. a copy of the @iter, free with [method@Gtk.TextIter.free] + line="415">a copy of the @iter, free with [method@Gtk.TextIter.free] an iterator + line="405">an iterator @@ -143260,7 +146559,7 @@ The function is used by language bindings. Returns whether the character at @iter is within an editable region + line="1414">Returns whether the character at @iter is within an editable region of text. Non-editable text is “locked” and can’t be changed by the @@ -143277,20 +146576,20 @@ case. whether @iter is inside an editable range + line="1433">whether @iter is inside an editable range an iterator + line="1416">an iterator %TRUE if text is editable by default + line="1417">%TRUE if text is editable by default @@ -143298,7 +146597,7 @@ case. Returns %TRUE if @iter points to the start of the paragraph + line="1589">Returns %TRUE if @iter points to the start of the paragraph delimiter characters for a line. Delimiters will be either a newline, a carriage return, a carriage @@ -143313,14 +146612,14 @@ are no paragraph delimiter chars there. whether @iter is at the end of a line + line="1605">whether @iter is at the end of a line an iterator + line="1591">an iterator @@ -143328,7 +146627,7 @@ are no paragraph delimiter chars there. Determines whether @iter ends a sentence. + line="3503">Determines whether @iter ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. @@ -143336,14 +146635,14 @@ be correct for nearly any language. %TRUE if @iter is at the end of a sentence. + line="3512">%TRUE if @iter is at the end of a sentence. a `GtkTextIter` + line="3505">a `GtkTextIter` @@ -143351,7 +146650,7 @@ be correct for nearly any language. Returns %TRUE if @tag is toggled off at exactly this point. + line="1234">Returns %TRUE if @tag is toggled off at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled off at this point. @@ -143365,14 +146664,14 @@ returns %TRUE, [method@Gtk.TextIter.has_tag] will return whether @iter is the end of a range tagged with @tag + line="1250">whether @iter is the end of a range tagged with @tag an iterator + line="1236">an iterator a `GtkTextTag` + line="1237">a `GtkTextTag` @@ -143389,7 +146688,7 @@ returns %TRUE, [method@Gtk.TextIter.has_tag] will return Determines whether @iter ends a natural-language word. + line="3447">Determines whether @iter ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language. @@ -143397,14 +146696,14 @@ for nearly any language. %TRUE if @iter is at the end of a word + line="3456">%TRUE if @iter is at the end of a word a `GtkTextIter` + line="3449">a `GtkTextIter` @@ -143412,7 +146711,7 @@ for nearly any language. Tests whether two iterators are equal, using the fastest possible + line="5431">Tests whether two iterators are equal, using the fastest possible mechanism. This function is very fast; you can expect it to perform @@ -143423,20 +146722,20 @@ bit faster than [method@Gtk.TextIter.compare]. %TRUE if the iterators point to the same place in the buffer + line="5444">%TRUE if the iterators point to the same place in the buffer a `GtkTextIter` + line="5433">a `GtkTextIter` another `GtkTextIter` + line="5434">another `GtkTextIter` @@ -143444,7 +146743,7 @@ bit faster than [method@Gtk.TextIter.compare]. Moves @iter forward by one character offset. + line="2230">Moves @iter forward by one character offset. Note that images embedded in the buffer occupy 1 character slot, so this function may actually move onto an image instead of a character, @@ -143455,14 +146754,14 @@ and this function returns %FALSE for convenience when writing loops. whether @iter moved and is dereferenceable + line="2242">whether @iter moved and is dereferenceable an iterator + line="2232">an iterator @@ -143470,7 +146769,7 @@ and this function returns %FALSE for convenience when writing loops. Moves @count characters if possible. + line="2299">Moves @count characters if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. @@ -143483,20 +146782,20 @@ is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable + line="2314">whether @iter moved and is dereferenceable an iterator + line="2301">an iterator number of characters to move, may be negative + line="2302">number of characters to move, may be negative @@ -143505,7 +146804,7 @@ is 0, the function does nothing and returns %FALSE. c:identifier="gtk_text_iter_forward_cursor_position"> Moves @iter forward by a single cursor position. + line="3679">Moves @iter forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Perhaps surprisingly, there may not be @@ -143524,14 +146823,14 @@ function. %TRUE if we moved and the new position is dereferenceable + line="3699">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3681">a `GtkTextIter` @@ -143540,27 +146839,27 @@ function. c:identifier="gtk_text_iter_forward_cursor_positions"> Moves up to @count cursor positions. + line="3721">Moves up to @count cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable + line="3730">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3723">a `GtkTextIter` number of positions to move + line="3724">number of positions to move @@ -143569,7 +146868,7 @@ See [method@Gtk.TextIter.forward_cursor_position] for details. c:identifier="gtk_text_iter_forward_find_char"> Advances @iter, calling @pred on each character. + line="4433">Advances @iter, calling @pred on each character. If @pred returns %TRUE, returns %TRUE and stops scanning. If @pred never returns %TRUE, @iter is set to @limit if @@ -143578,14 +146877,14 @@ If @pred never returns %TRUE, @iter is set to @limit if whether a match was found + line="4446">whether a match was found a `GtkTextIter` + line="4435">a `GtkTextIter` a function to be called on each character + line="4436">a function to be called on each character user data for @pred + line="4437">user data for @pred search limit + line="4438">search limit @@ -143620,7 +146919,7 @@ If @pred never returns %TRUE, @iter is set to @limit if Moves @iter to the start of the next line. + line="2534">Moves @iter to the start of the next line. If the iter is already on the last line of the buffer, moves the iter to the end of the current line. If after @@ -143630,14 +146929,14 @@ dereferenceable, returns %FALSE. Otherwise, returns %TRUE. whether @iter can be dereferenced + line="2545">whether @iter can be dereferenced an iterator + line="2536">an iterator @@ -143645,7 +146944,7 @@ dereferenceable, returns %FALSE. Otherwise, returns %TRUE. Moves @count lines forward, if possible. + line="2665">Moves @count lines forward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. @@ -143659,20 +146958,20 @@ moves backward by 0 - @count lines. whether @iter moved and is dereferenceable + line="2681">whether @iter moved and is dereferenceable a `GtkTextIter` + line="2667">a `GtkTextIter` number of lines to move forward + line="2668">number of lines to move forward @@ -143681,7 +146980,7 @@ moves backward by 0 - @count lines. c:identifier="gtk_text_iter_forward_search"> Searches forward for @str. + line="4952">Searches forward for @str. Any match is returned by setting @match_start to the first character of the match and @match_end to the first character after the match. @@ -143695,26 +146994,26 @@ even if there is a possible @match_end after or at @iter. whether a match was found + line="4972">whether a match was found start of search + line="4954">start of search a search string + line="4955">a search string flags affecting how the search is done + line="4956">flags affecting how the search is done allow-none="1"> return location for start of match + line="4957">return location for start of match allow-none="1"> return location for end of match + line="4958">return location for end of match allow-none="1"> location of last possible @match_end, or %NULL for the end of the buffer + line="4959">location of last possible @match_end, or %NULL for the end of the buffer @@ -143754,7 +147053,7 @@ even if there is a possible @match_end after or at @iter. c:identifier="gtk_text_iter_forward_sentence_end"> Moves forward to the next sentence end. + line="3539">Moves forward to the next sentence end. If @iter is at the end of a sentence, moves to the next end of sentence. @@ -143765,14 +147064,14 @@ be correct for nearly any language. %TRUE if @iter moved and is not the end iterator + line="3551">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3541">a `GtkTextIter` @@ -143781,27 +147080,27 @@ be correct for nearly any language. c:identifier="gtk_text_iter_forward_sentence_ends"> Calls [method@Gtk.TextIter.forward_sentence_end] @count times. + line="3582">Calls [method@Gtk.TextIter.forward_sentence_end] @count times. If @count is negative, moves backward instead of forward. %TRUE if @iter moved and is not the end iterator + line="3591">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3584">a `GtkTextIter` number of sentences to move + line="3585">number of sentences to move @@ -143810,7 +147109,7 @@ If @count is negative, moves backward instead of forward. c:identifier="gtk_text_iter_forward_to_end"> Moves @iter forward to the “end iterator”, which points + line="4120">Moves @iter forward to the “end iterator”, which points one past the last valid character in the buffer. [method@Gtk.TextIter.get_char] called on the end iterator @@ -143823,7 +147122,7 @@ returns 0, which is convenient for writing loops. a `GtkTextIter` + line="4122">a `GtkTextIter` @@ -143832,7 +147131,7 @@ returns 0, which is convenient for writing loops. c:identifier="gtk_text_iter_forward_to_line_end"> Moves the iterator to point to the paragraph delimiter characters. + line="4178">Moves the iterator to point to the paragraph delimiter characters. The possible characters are either a newline, a carriage return, a carriage return/newline in sequence, or the Unicode paragraph @@ -143847,14 +147146,14 @@ the last line), and returns %FALSE. %TRUE if we moved and the new location is not the end iterator + line="4194">%TRUE if we moved and the new location is not the end iterator a `GtkTextIter` + line="4180">a `GtkTextIter` @@ -143863,7 +147162,7 @@ the last line), and returns %FALSE. c:identifier="gtk_text_iter_forward_to_tag_toggle"> Moves forward to the next toggle (on or off) of the + line="4231">Moves forward to the next toggle (on or off) of the @tag, or to the next toggle of any tag if @tag is %NULL. @@ -143876,14 +147175,14 @@ if no toggle is found. whether we found a tag toggle after @iter + line="4246">whether we found a tag toggle after @iter a `GtkTextIter` + line="4233">a `GtkTextIter` allow-none="1"> a `GtkTextTag` + line="4234">a `GtkTextTag` @@ -143901,21 +147200,21 @@ if no toggle is found. c:identifier="gtk_text_iter_forward_visible_cursor_position"> Moves @iter forward to the next visible cursor position. + line="3761">Moves @iter forward to the next visible cursor position. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable + line="3769">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3763">a `GtkTextIter` @@ -143924,27 +147223,27 @@ See [method@Gtk.TextIter.forward_cursor_position] for details. c:identifier="gtk_text_iter_forward_visible_cursor_positions"> Moves up to @count visible cursor positions. + line="3793">Moves up to @count visible cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable + line="3802">%TRUE if we moved and the new position is dereferenceable a `GtkTextIter` + line="3795">a `GtkTextIter` number of positions to move + line="3796">number of positions to move @@ -143953,7 +147252,7 @@ See [method@Gtk.TextIter.forward_cursor_position] for details. c:identifier="gtk_text_iter_forward_visible_line"> Moves @iter to the start of the next visible line. + line="2762">Moves @iter to the start of the next visible line. Returns %TRUE if there was a next line to move to, and %FALSE if @iter was simply moved to @@ -143963,14 +147262,14 @@ already at the end of the buffer. whether @iter can be dereferenced + line="2773">whether @iter can be dereferenced an iterator + line="2764">an iterator @@ -143979,7 +147278,7 @@ already at the end of the buffer. c:identifier="gtk_text_iter_forward_visible_lines"> Moves @count visible lines forward, if possible. + line="2839">Moves @count visible lines forward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. @@ -143993,20 +147292,20 @@ moves backward by 0 - @count lines. whether @iter moved and is dereferenceable + line="2855">whether @iter moved and is dereferenceable a `GtkTextIter` + line="2841">a `GtkTextIter` number of lines to move forward + line="2842">number of lines to move forward @@ -144015,7 +147314,7 @@ moves backward by 0 - @count lines. c:identifier="gtk_text_iter_forward_visible_word_end"> Moves forward to the next visible word end. + line="3354">Moves forward to the next visible word end. If @iter is currently on a word end, moves forward to the next one after that. @@ -144026,14 +147325,14 @@ for nearly any language %TRUE if @iter moved and is not the end iterator + line="3366">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3356">a `GtkTextIter` @@ -144042,25 +147341,25 @@ for nearly any language c:identifier="gtk_text_iter_forward_visible_word_ends"> Calls [method@Gtk.TextIter.forward_visible_word_end] up to @count times. + line="3394">Calls [method@Gtk.TextIter.forward_visible_word_end] up to @count times. %TRUE if @iter moved and is not the end iterator + line="3401">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3396">a `GtkTextIter` number of times to move + line="3397">number of times to move @@ -144069,7 +147368,7 @@ for nearly any language c:identifier="gtk_text_iter_forward_word_end"> Moves forward to the next word end. + line="3274">Moves forward to the next word end. If @iter is currently on a word end, moves forward to the next one after that. @@ -144080,14 +147379,14 @@ for nearly any language. %TRUE if @iter moved and is not the end iterator + line="3286">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3276">a `GtkTextIter` @@ -144096,25 +147395,25 @@ for nearly any language. c:identifier="gtk_text_iter_forward_word_ends"> Calls [method@Gtk.TextIter.forward_word_end] up to @count times. + line="3318">Calls [method@Gtk.TextIter.forward_word_end] up to @count times. %TRUE if @iter moved and is not the end iterator + line="3325">%TRUE if @iter moved and is not the end iterator a `GtkTextIter` + line="3320">a `GtkTextIter` number of times to move + line="3321">number of times to move @@ -144122,7 +147421,7 @@ for nearly any language. Free an iterator allocated on the heap. + line="431">Free an iterator allocated on the heap. This function is intended for use in language bindings, and is not especially useful for applications, because @@ -144135,7 +147434,7 @@ iterators can simply be allocated on the stack. a dynamically-allocated iterator + line="433">a dynamically-allocated iterator @@ -144143,19 +147442,19 @@ iterators can simply be allocated on the stack. Returns the `GtkTextBuffer` this iterator is associated with. + line="378">Returns the `GtkTextBuffer` this iterator is associated with. the buffer + line="384">the buffer an iterator + line="380">an iterator @@ -144164,20 +147463,20 @@ iterators can simply be allocated on the stack. c:identifier="gtk_text_iter_get_bytes_in_line"> Returns the number of bytes in the line containing @iter, + line="1760">Returns the number of bytes in the line containing @iter, including the paragraph delimiters. number of bytes in the line + line="1767">number of bytes in the line an iterator + line="1762">an iterator @@ -144185,7 +147484,7 @@ including the paragraph delimiters. The Unicode character at this iterator is returned. + line="851">The Unicode character at this iterator is returned. Equivalent to operator* on a C++ iterator. If the element at this iterator is a non-character element, such as an image @@ -144198,14 +147497,14 @@ So you can write a loop which ends when this function returns 0. a Unicode character, or 0 if @iter is not dereferenceable + line="865">a Unicode character, or 0 if @iter is not dereferenceable an iterator + line="853">an iterator @@ -144214,20 +147513,20 @@ So you can write a loop which ends when this function returns 0. c:identifier="gtk_text_iter_get_chars_in_line"> Returns the number of characters in the line containing @iter, + line="1708">Returns the number of characters in the line containing @iter, including the paragraph delimiters. number of characters in the line + line="1715">number of characters in the line an iterator + line="1710">an iterator @@ -144236,7 +147535,7 @@ including the paragraph delimiters. c:identifier="gtk_text_iter_get_child_anchor"> If the location at @iter contains a child anchor, the + line="1045">If the location at @iter contains a child anchor, the anchor is returned. Otherwise, %NULL is returned. @@ -144244,14 +147543,14 @@ Otherwise, %NULL is returned. the anchor at @iter + line="1054">the anchor at @iter an iterator + line="1047">an iterator @@ -144259,7 +147558,7 @@ Otherwise, %NULL is returned. Returns the language in effect at @iter. + line="1522">Returns the language in effect at @iter. If no tags affecting language apply to @iter, the return value is identical to that of [func@Gtk.get_default_language]. @@ -144267,14 +147566,14 @@ value is identical to that of [func@Gtk.get_default_language]. language in effect at @iter + line="1531">language in effect at @iter an iterator + line="1524">an iterator @@ -144282,7 +147581,7 @@ value is identical to that of [func@Gtk.get_default_language]. Returns the line number containing the iterator. + line="624">Returns the line number containing the iterator. Lines in a `GtkTextBuffer` are numbered beginning with 0 for the first line in the buffer. @@ -144290,14 +147589,14 @@ with 0 for the first line in the buffer. a line number + line="633">a line number an iterator + line="626">an iterator @@ -144306,7 +147605,7 @@ with 0 for the first line in the buffer. c:identifier="gtk_text_iter_get_line_index"> Returns the byte index of the iterator, counting + line="686">Returns the byte index of the iterator, counting from the start of a newline-terminated line. Remember that `GtkTextBuffer` encodes text in @@ -144316,14 +147615,14 @@ number of bytes to represent. distance from start of line, in bytes + line="697">distance from start of line, in bytes an iterator + line="688">an iterator @@ -144332,7 +147631,7 @@ number of bytes to represent. c:identifier="gtk_text_iter_get_line_offset"> Returns the character offset of the iterator, + line="656">Returns the character offset of the iterator, counting from the start of a newline-terminated line. The first character on the line has offset 0. @@ -144340,14 +147639,14 @@ The first character on the line has offset 0. offset from start of line + line="665">offset from start of line an iterator + line="658">an iterator @@ -144355,7 +147654,7 @@ The first character on the line has offset 0. Returns a list of all `GtkTextMark` at this location. + line="1076">Returns a list of all `GtkTextMark` at this location. Because marks are not iterable (they don’t take up any "space" in the buffer, they are just marks in between iterable locations), @@ -144366,7 +147665,7 @@ The returned list is not in any meaningful order. + line="1088"> list of `GtkTextMark` @@ -144376,7 +147675,7 @@ The returned list is not in any meaningful order. an iterator + line="1078">an iterator @@ -144384,7 +147683,7 @@ The returned list is not in any meaningful order. Returns the character offset of an iterator. + line="583">Returns the character offset of an iterator. Each character in a `GtkTextBuffer` has an offset, starting with 0 for the first character in the buffer. @@ -144394,14 +147693,14 @@ an offset back into an iterator. a character offset + line="594">a character offset an iterator + line="585">an iterator @@ -144409,21 +147708,21 @@ an offset back into an iterator. If the element at @iter is a paintable, the paintable is returned. + line="1015">If the element at @iter is a paintable, the paintable is returned. Otherwise, %NULL is returned. the paintable at @iter + line="1023">the paintable at @iter an iterator + line="1017">an iterator @@ -144431,7 +147730,7 @@ Otherwise, %NULL is returned. Returns the text in the given range. + line="901">Returns the text in the given range. A “slice” is an array of characters encoded in UTF-8 format, including the Unicode “unknown” character 0xFFFC for iterable @@ -144445,20 +147744,20 @@ widget is in the buffer. slice of text from the buffer + line="917">slice of text from the buffer iterator at start of a range + line="903">iterator at start of a range iterator at end of a range + line="904">iterator at end of a range @@ -144466,7 +147765,7 @@ widget is in the buffer. Returns a list of tags that apply to @iter, in ascending order of + line="1370">Returns a list of tags that apply to @iter, in ascending order of priority. The highest-priority tags are last. @@ -144477,7 +147776,7 @@ but you have to free the list itself. list of + line="1382">list of `GtkTextTag` @@ -144487,7 +147786,7 @@ but you have to free the list itself. a `GtkTextIter` + line="1372">a `GtkTextIter` @@ -144495,7 +147794,7 @@ but you have to free the list itself. Returns text in the given range. + line="932">Returns text in the given range. If the range contains non-text elements such as images, the character and byte @@ -144506,20 +147805,20 @@ byte offsets in the buffer. If you want offsets to correspond, see array of characters from the buffer + line="945">array of characters from the buffer iterator at start of a range + line="934">iterator at start of a range iterator at end of a range + line="935">iterator at end of a range @@ -144528,7 +147827,7 @@ byte offsets in the buffer. If you want offsets to correspond, see c:identifier="gtk_text_iter_get_toggled_tags"> Returns a list of `GtkTextTag` that are toggled on or off at this + line="1123">Returns a list of `GtkTextTag` that are toggled on or off at this point. If @toggled_on is %TRUE, the list contains tags that are @@ -144540,7 +147839,7 @@ does not have the tag applied to it. tags + line="1137">tags toggled at this point @@ -144550,13 +147849,13 @@ does not have the tag applied to it. an iterator + line="1125">an iterator %TRUE to get toggled-on tags + line="1126">%TRUE to get toggled-on tags @@ -144565,7 +147864,7 @@ does not have the tag applied to it. c:identifier="gtk_text_iter_get_visible_line_index"> Returns the number of bytes from the start of the + line="783">Returns the number of bytes from the start of the line to the given @iter, not counting bytes that are invisible due to tags with the “invisible” flag toggled on. @@ -144573,14 +147872,14 @@ toggled on. byte index of @iter with respect to the start of the line + line="792">byte index of @iter with respect to the start of the line a `GtkTextIter` + line="785">a `GtkTextIter` @@ -144589,7 +147888,7 @@ toggled on. c:identifier="gtk_text_iter_get_visible_line_offset"> Returns the offset in characters from the start of the + line="718">Returns the offset in characters from the start of the line to the given @iter, not counting characters that are invisible due to tags with the “invisible” flag toggled on. @@ -144597,14 +147896,14 @@ toggled on. offset in visible characters from the start of the line + line="727">offset in visible characters from the start of the line a `GtkTextIter` + line="720">a `GtkTextIter` @@ -144613,7 +147912,7 @@ toggled on. c:identifier="gtk_text_iter_get_visible_slice"> Returns visible text in the given range. + line="960">Returns visible text in the given range. Like [method@Gtk.TextIter.get_slice], but invisible text is not included. Invisible text is usually invisible because @@ -144623,20 +147922,20 @@ been applied to it. slice of text from the buffer + line="972">slice of text from the buffer iterator at start of range + line="962">iterator at start of range iterator at end of range + line="963">iterator at end of range @@ -144645,7 +147944,7 @@ been applied to it. c:identifier="gtk_text_iter_get_visible_text"> Returns visible text in the given range. + line="987">Returns visible text in the given range. Like [method@Gtk.TextIter.get_text], but invisible text is not included. Invisible text is usually invisible because @@ -144655,7 +147954,7 @@ been applied to it. string containing visible text in the + line="999">string containing visible text in the range @@ -144663,13 +147962,13 @@ range iterator at start of range + line="989">iterator at start of range iterator at end of range + line="990">iterator at end of range @@ -144677,7 +147976,7 @@ range Returns %TRUE if @iter points to a character that is part + line="1328">Returns %TRUE if @iter points to a character that is part of a range tagged with @tag. See also [method@Gtk.TextIter.starts_tag] and @@ -144686,20 +147985,20 @@ See also [method@Gtk.TextIter.starts_tag] and whether @iter is tagged with @tag + line="1339">whether @iter is tagged with @tag an iterator + line="1330">an iterator a `GtkTextTag` + line="1331">a `GtkTextTag` @@ -144707,33 +148006,33 @@ See also [method@Gtk.TextIter.starts_tag] and Checks whether @iter falls in the range [@start, @end). + line="5565">Checks whether @iter falls in the range [@start, @end). @start and @end must be in ascending order. %TRUE if @iter is in the range + line="5575">%TRUE if @iter is in the range a `GtkTextIter` + line="5567">a `GtkTextIter` start of range + line="5568">start of range end of range + line="5569">end of range @@ -144742,7 +148041,7 @@ See also [method@Gtk.TextIter.starts_tag] and c:identifier="gtk_text_iter_inside_sentence"> Determines whether @iter is inside a sentence (as opposed to in + line="3520">Determines whether @iter is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). @@ -144752,14 +148051,14 @@ for nearly any language. %TRUE if @iter is inside a sentence. + line="3531">%TRUE if @iter is inside a sentence. a `GtkTextIter` + line="3522">a `GtkTextIter` @@ -144767,7 +148066,7 @@ for nearly any language. Determines whether the character pointed by @iter is part of a + line="3464">Determines whether the character pointed by @iter is part of a natural-language word (as opposed to say inside some whitespace). Word breaks are determined by Pango and should be correct @@ -144780,14 +148079,14 @@ the first character of the word. %TRUE if @iter is inside a word + line="3478">%TRUE if @iter is inside a word a `GtkTextIter` + line="3466">a `GtkTextIter` @@ -144796,7 +148095,7 @@ the first character of the word. c:identifier="gtk_text_iter_is_cursor_position"> Determine if @iter is at a cursor position. + line="3833">Determine if @iter is at a cursor position. See [method@Gtk.TextIter.forward_cursor_position] or [struct@Pango.LogAttr] or [func@Pango.break] for details @@ -144805,14 +148104,14 @@ on what a cursor position is. %TRUE if the cursor can be placed at @iter + line="3843">%TRUE if the cursor can be placed at @iter a `GtkTextIter` + line="3835">a `GtkTextIter` @@ -144820,7 +148119,7 @@ on what a cursor position is. Returns %TRUE if @iter is the end iterator. + line="1653">Returns %TRUE if @iter is the end iterator. This means it is one past the last dereferenceable iterator in the buffer. [method@Gtk.TextIter.is_end] is the most efficient @@ -144829,14 +148128,14 @@ way to check whether an iterator is the end iterator. whether @iter is the end iterator + line="1663">whether @iter is the end iterator an iterator + line="1655">an iterator @@ -144844,19 +148143,19 @@ way to check whether an iterator is the end iterator. Returns %TRUE if @iter is the first iterator in the buffer. + line="1694">Returns %TRUE if @iter is the first iterator in the buffer. whether @iter is the first in the buffer + line="1700">whether @iter is the first in the buffer an iterator + line="1696">an iterator @@ -144864,7 +148163,7 @@ way to check whether an iterator is the end iterator. Swaps the value of @first and @second if @second comes before + line="5591">Swaps the value of @first and @second if @second comes before @first in the buffer. That is, ensures that @first and @second are in sequence. @@ -144881,13 +148180,13 @@ pre-sorted range. a `GtkTextIter` + line="5593">a `GtkTextIter` another `GtkTextIter` + line="5594">another `GtkTextIter` @@ -144895,7 +148194,7 @@ pre-sorted range. Moves iterator @iter to the start of the line @line_number. + line="4038">Moves iterator @iter to the start of the line @line_number. If @line_number is negative or larger than or equal to the number of lines in the buffer, moves @iter to the start of the last line in the buffer. @@ -144907,13 +148206,13 @@ in the buffer, moves @iter to the start of the last line in the buffer. a `GtkTextIter` + line="4040">a `GtkTextIter` line number (counted from 0) + line="4041">line number (counted from 0) @@ -144922,7 +148221,7 @@ in the buffer, moves @iter to the start of the last line in the buffer. c:identifier="gtk_text_iter_set_line_index"> Same as [method@Gtk.TextIter.set_line_offset], but works with a + line="3891">Same as [method@Gtk.TextIter.set_line_offset], but works with a byte index. The given byte index must be at the start of a character, it can’t be in the middle of a UTF-8 encoded character. @@ -144934,13 +148233,13 @@ encoded character. a `GtkTextIter` + line="3893">a `GtkTextIter` a byte index relative to the start of @iter’s current line + line="3894">a byte index relative to the start of @iter’s current line @@ -144949,7 +148248,7 @@ encoded character. c:identifier="gtk_text_iter_set_line_offset"> Moves @iter within a line, to a new character (not byte) offset. + line="3851">Moves @iter within a line, to a new character (not byte) offset. The given character offset must be less than or equal to the number of characters in the line; if equal, @iter moves to the start of the @@ -144963,13 +148262,13 @@ index rather than a character offset. a `GtkTextIter` + line="3853">a `GtkTextIter` a character offset relative to the start of @iter’s current line + line="3854">a character offset relative to the start of @iter’s current line @@ -144977,7 +148276,7 @@ index rather than a character offset. Sets @iter to point to @char_offset. + line="4075">Sets @iter to point to @char_offset. @char_offset counts from the start of the entire text buffer, starting with 0. @@ -144989,13 +148288,13 @@ of the entire text buffer, starting with 0. a `GtkTextIter` + line="4077">a `GtkTextIter` a character number + line="4078">a character number @@ -145004,7 +148303,7 @@ of the entire text buffer, starting with 0. c:identifier="gtk_text_iter_set_visible_line_index"> Like [method@Gtk.TextIter.set_line_index], but the index is in visible + line="3978">Like [method@Gtk.TextIter.set_line_index], but the index is in visible bytes, i.e. text with a tag making it invisible is not counted in the index. @@ -145015,13 +148314,13 @@ in the index. a `GtkTextIter` + line="3980">a `GtkTextIter` a byte index + line="3981">a byte index @@ -145030,7 +148329,7 @@ in the index. c:identifier="gtk_text_iter_set_visible_line_offset"> Like [method@Gtk.TextIter.set_line_offset], but the offset is in visible + line="3937">Like [method@Gtk.TextIter.set_line_offset], but the offset is in visible characters, i.e. text with a tag making it invisible is not counted in the offset. @@ -145041,13 +148340,13 @@ counted in the offset. a `GtkTextIter` + line="3939">a `GtkTextIter` a character offset + line="3940">a character offset @@ -145055,7 +148354,7 @@ counted in the offset. Returns %TRUE if @iter begins a paragraph. + line="1550">Returns %TRUE if @iter begins a paragraph. This is the case if [method@Gtk.TextIter.get_line_offset] would return 0. However this function is potentially more @@ -145066,14 +148365,14 @@ whether it’s 0. whether @iter begins a line + line="1562">whether @iter begins a line an iterator + line="1552">an iterator @@ -145082,7 +148381,7 @@ whether it’s 0. c:identifier="gtk_text_iter_starts_sentence"> Determines whether @iter begins a sentence. + line="3486">Determines whether @iter begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. @@ -145090,14 +148389,14 @@ should be correct for nearly any language. %TRUE if @iter is at the start of a sentence. + line="3495">%TRUE if @iter is at the start of a sentence. a `GtkTextIter` + line="3488">a `GtkTextIter` @@ -145105,7 +148404,7 @@ should be correct for nearly any language. Returns %TRUE if @tag is toggled on at exactly this point. + line="1184">Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. @@ -145119,14 +148418,14 @@ will also return %TRUE for the same parameters. whether @iter is the start of a range tagged with @tag + line="1200">whether @iter is the start of a range tagged with @tag an iterator + line="1186">an iterator allow-none="1"> a `GtkTextTag` + line="1187">a `GtkTextTag` @@ -145143,7 +148442,7 @@ will also return %TRUE for the same parameters. Determines whether @iter begins a natural-language word. + line="3430">Determines whether @iter begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language. @@ -145151,14 +148450,14 @@ for nearly any language. %TRUE if @iter is at the start of a word + line="3439">%TRUE if @iter is at the start of a word a `GtkTextIter` + line="3432">a `GtkTextIter` @@ -145166,7 +148465,7 @@ for nearly any language. Gets whether a range with @tag applied to it begins + line="1284">Gets whether a range with @tag applied to it begins or ends at @iter. This is equivalent to (gtk_text_iter_starts_tag() || @@ -145175,14 +148474,14 @@ gtk_text_iter_ends_tag()) whether @tag is toggled on or off at @iter + line="1295">whether @tag is toggled on or off at @iter an iterator + line="1286">an iterator allow-none="1"> a `GtkTextTag` + line="1287">a `GtkTextTag` @@ -145206,7 +148505,7 @@ gtk_text_iter_ends_tag()) glib:type-struct="TextMarkClass"> A `GtkTextMark` is a position in a `GtkTextbuffer` that is preserved + line="55">Marks a position in a `GtkTextbuffer` that is preserved across modifications. You may wish to begin by reading the @@ -145393,15 +148692,31 @@ A cursor is displayed for visible marks. + Sets the visibility of @mark. + +The insertion point is normally visible, i.e. you can see it as +a vertical bar. Also, the text widget uses a visible mark to +indicate where a drop will occur when dragging-and-dropping text. +Most other marks are not visible. + +Marks are not visible by default. + a GtkTextMark + visibility of mark @@ -145460,9 +148775,9 @@ text, otherwise to the right. filename="gtk/gtktextiter.h" line="36">Flags affecting how a search is done. -If neither %GTK_TEXT_SEARCH_VISIBLE_ONLY nor %GTK_TEXT_SEARCH_TEXT_ONLY are -enabled, the match must be exact; the special 0xFFFC character will match -embedded paintables or child widgets. +If neither `GTK_TEXT_SEARCH_VISIBLE_ONLY` nor `GTK_TEXT_SEARCH_TEXT_ONLY` +are enabled, the match must be exact; the special 0xFFFC character will +match embedded paintables or child widgets. glib:type-struct="TextTagClass"> A tag that can be applied to text contained in a `GtkTextBuffer`. + line="50">Can be applied to text contained in a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), @@ -145525,12 +148840,12 @@ They are maintained by GTK and you should not set them independently. Creates a `GtkTextTag`. + line="1130">Creates a `GtkTextTag`. a new `GtkTextTag` + line="1136">a new `GtkTextTag` @@ -145540,7 +148855,7 @@ They are maintained by GTK and you should not set them independently. allow-none="1"> tag name + line="1132">tag name @@ -145548,7 +148863,7 @@ They are maintained by GTK and you should not set them independently. Emits the [signal@Gtk.TextTagTable::tag-changed] signal on the + line="2547">Emits the [signal@Gtk.TextTagTable::tag-changed] signal on the `GtkTextTagTable` where the tag is included. The signal is already emitted when setting a `GtkTextTag` property. @@ -145561,13 +148876,13 @@ This function is useful for a `GtkTextTag` subclass. a `GtkTextTag` + line="2549">a `GtkTextTag` whether the change affects the `GtkTextView` layout + line="2550">whether the change affects the `GtkTextView` layout @@ -145575,19 +148890,19 @@ This function is useful for a `GtkTextTag` subclass. Get the tag priority. + line="2473">Get the tag priority. The tag’s priority. + line="2479">The tag’s priority. a `GtkTextTag` + line="2475">a `GtkTextTag` @@ -145595,7 +148910,7 @@ This function is useful for a `GtkTextTag` subclass. Sets the priority of a `GtkTextTag`. + line="2489">Sets the priority of a `GtkTextTag`. Valid priorities start at 0 and go to one less than [method@Gtk.TextTagTable.get_size]. Each tag in a table @@ -145617,13 +148932,13 @@ which adds the tag to the buffer’s table automatically. a `GtkTextTag` + line="2491">a `GtkTextTag` the new priority + line="2492">the new priority @@ -145654,6 +148969,9 @@ the margins override one another (the default). writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `allow-breaks` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `background-full-height` property is set. @@ -145692,6 +149013,9 @@ or only the height of the tagged characters. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `background` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `editable` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `fallback` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `family` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `font-features` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `foreground` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `indent` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `insert-hyphens` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `invisible` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `justification` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `language` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `left-margin` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `letter-spacing` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `line-height` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `overline-rgba` property is set. + Whether the `overline` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `paragraph-background` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `pixels-above-lines` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `pixels-below-lines` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `pixels-inside-wrap` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `right-margin` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `rise` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `scale` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `sentence` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `show-spaces` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `size` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `stretch` property is set. default-value="FALSE"> If the `strikethrough-rgba` property has been set. + line="1024">If the `strikethrough-rgba` property has been set. + Whether the `strikethrough` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `style` property is set. @@ -146232,6 +149640,9 @@ If not set, strikeouts will use the foreground color. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `tabs` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `text-transform` property is set. default-value="FALSE"> If the `underline-rgba` property has been set. + line="1003">If the `underline-rgba` property has been set. + Whether the `underline` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `variant` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `weight` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `word` property is set. writable="1" transfer-ownership="none" default-value="FALSE"> + Whether the `wrap-mode` property is set. @@ -146384,7 +149813,7 @@ at character boundaries. glib:get-type="gtk_text_tag_table_get_type"> The collection of tags in a `GtkTextBuffer` + line="39">Collects the tags in a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), @@ -146658,14 +150087,54 @@ to iterate over every `GtkTextTag` inside a `GtkTextTagTable`. glib:type-struct="TextViewClass"> A widget that displays the contents of a [class@Gtk.TextBuffer]. + line="66">Displays the contents of a [class@Gtk.TextBuffer]. -![An example GtkTextview](multiline-text.png) +<picture> + <source srcset="multiline-text-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkTextView" src="multiline-text.png"> +</picture> You may wish to begin by reading the [conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. +## Shortcuts and Gestures + +`GtkTextView` supports the following keyboard shortcuts: + +- <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. +- <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes the last modification. +- <kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> + redoes the last undone modification. + +Additionally, the following signals have default keybindings: + +- [signal@Gtk.TextView::backspace] +- [signal@Gtk.TextView::copy-clipboard] +- [signal@Gtk.TextView::cut-clipboard] +- [signal@Gtk.TextView::delete-from-cursor] +- [signal@Gtk.TextView::insert-emoji] +- [signal@Gtk.TextView::move-cursor] +- [signal@Gtk.TextView::paste-clipboard] +- [signal@Gtk.TextView::select-all] +- [signal@Gtk.TextView::toggle-cursor-visible] +- [signal@Gtk.TextView::toggle-overwrite] + +## Actions + +`GtkTextView` defines a set of built-in actions: + +- `clipboard.copy` copies the contents to the clipboard. +- `clipboard.cut` copies the contents to the clipboard and deletes it from + the widget. +- `clipboard.paste` inserts the contents of the clipboard into the widget. +- `menu.popup` opens the context menu. +- `misc.insert-emoji` opens the Emoji chooser. +- `selection.delete` deletes the current selection. +- `selection.select-all` selects all of the widgets content. +- `text.redo` redoes the last change to the contents. +- `text.undo` undoes the last change to the contents. + ## CSS nodes ``` @@ -146691,16 +150160,17 @@ of the main node. ## Accessibility -`GtkTextView` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role. +`GtkTextView` uses the [enum@Gtk.AccessibleRole.text_box] role. + Creates a new `GtkTextView`. + line="2251">Creates a new `GtkTextView`. If you don’t call [method@Gtk.TextView.set_buffer] before using the text view, an empty default buffer will be created for you. Get the @@ -146710,7 +150180,7 @@ your own buffer, consider [ctor@Gtk.TextView.new_with_buffer]. a new `GtkTextView` + line="2261">a new `GtkTextView` @@ -146718,7 +150188,7 @@ your own buffer, consider [ctor@Gtk.TextView.new_with_buffer]. c:identifier="gtk_text_view_new_with_buffer"> Creates a new `GtkTextView` widget displaying the buffer @buffer. + line="2269">Creates a new `GtkTextView` widget displaying the buffer @buffer. One buffer can be shared among many widgets. @buffer may be %NULL to create a default buffer, in which case this function is equivalent @@ -146728,19 +150198,23 @@ to the buffer; it does not take over an existing reference. a new `GtkTextView`. + line="2280">a new `GtkTextView`. a `GtkTextBuffer` + line="2271">a `GtkTextBuffer` + The class handler for the `GtkTextView::backspace` + keybinding signal. @@ -146752,6 +150226,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::copy-clipboard` + keybinding signal. @@ -146763,6 +150241,11 @@ to the buffer; it does not take over an existing reference. + The create_buffer vfunc is called to create a `GtkTextBuffer` + for the text view. The default implementation is to just call + gtk_text_buffer_new(). @@ -146774,6 +150257,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::cut-clipboard` + keybinding signal @@ -146785,6 +150272,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::delete-from-cursor` + keybinding signal. @@ -146802,6 +150293,9 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::extend-selection` signal. @@ -146825,6 +150319,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::insert-at-cursor` + keybinding signal. @@ -146839,6 +150337,9 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::insert-emoji` signal. @@ -146850,6 +150351,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::move-cursor` + keybinding signal. @@ -146870,6 +150375,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::paste-clipboard` + keybinding signal. @@ -146881,6 +150390,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::set-anchor` + keybinding signal. @@ -146892,6 +150405,13 @@ to the buffer; it does not take over an existing reference. + The snapshot_layer vfunc is called before and after the text + view is drawing its own text. Applications can override this vfunc + in a subclass to draw customized content underneath or above the + text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT + layers the drawing is done in the buffer coordinate space. @@ -146909,6 +150429,10 @@ to the buffer; it does not take over an existing reference. + The class handler for the `GtkTextView::toggle-overwrite` + keybinding signal. @@ -146923,8 +150447,8 @@ to the buffer; it does not take over an existing reference. c:identifier="gtk_text_view_add_child_at_anchor"> Adds a child widget in the text buffer, at the given @anchor. - + line="9975">Adds a child widget in the text buffer, at the given @anchor. + @@ -146932,19 +150456,19 @@ to the buffer; it does not take over an existing reference. a `GtkTextView` + line="9977">a `GtkTextView` a `GtkWidget` + line="9978">a `GtkWidget` a `GtkTextChildAnchor` in the `GtkTextBuffer` for @text_view + line="9979">a `GtkTextChildAnchor` in the `GtkTextBuffer` for @text_view @@ -146952,7 +150476,7 @@ to the buffer; it does not take over an existing reference. Adds @child at a fixed coordinate in the `GtkTextView`'s text window. + line="10024">Adds @child at a fixed coordinate in the `GtkTextView`'s text window. The @xpos and @ypos must be in buffer coordinates (see [method@Gtk.TextView.get_iter_location] to convert to @@ -146962,7 +150486,7 @@ buffer coordinates). If instead you want a widget that will not move with the `GtkTextView` contents see `GtkOverlay`. - + @@ -146970,25 +150494,25 @@ If instead you want a widget that will not move with the a `GtkTextView` + line="10026">a `GtkTextView` a `GtkWidget` + line="10027">a `GtkWidget` X position of child in window coordinates + line="10028">X position of child in window coordinates Y position of child in window coordinates + line="10029">Y position of child in window coordinates @@ -146997,7 +150521,7 @@ If instead you want a widget that will not move with the c:identifier="gtk_text_view_backward_display_line"> Moves the given @iter backward by one display (wrapped) line. + line="10118">Moves the given @iter backward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. @@ -147006,24 +150530,24 @@ wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. - + %TRUE if @iter was moved and is not on the end iterator + line="10133">%TRUE if @iter was moved and is not on the end iterator a `GtkTextView` + line="10120">a `GtkTextView` a `GtkTextIter` + line="10121">a `GtkTextIter` @@ -147032,7 +150556,7 @@ views, since they depend on the contents of the `GtkTextBuffer`. c:identifier="gtk_text_view_backward_display_line_start"> Moves the given @iter backward to the next display line start. + line="10176">Moves the given @iter backward to the next display line start. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. @@ -147041,24 +150565,24 @@ wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. - + %TRUE if @iter was moved and is not on the end iterator + line="10191">%TRUE if @iter was moved and is not on the end iterator a `GtkTextView` + line="10178">a `GtkTextView` a `GtkTextIter` + line="10179">a `GtkTextIter` @@ -147067,8 +150591,8 @@ views, since they depend on the contents of the `GtkTextBuffer`. c:identifier="gtk_text_view_buffer_to_window_coords"> Converts buffer coordinates to window coordinates. - + line="9798">Converts buffer coordinates to window coordinates. + @@ -147076,25 +150600,25 @@ views, since they depend on the contents of the `GtkTextBuffer`. a `GtkTextView` + line="9800">a `GtkTextView` a `GtkTextWindowType` + line="9801">a `GtkTextWindowType` buffer x coordinate + line="9802">buffer x coordinate buffer y coordinate + line="9803">buffer y coordinate allow-none="1"> window x coordinate return location + line="9804">window x coordinate return location allow-none="1"> window y coordinate return location + line="9805">window y coordinate return location @@ -147125,7 +150649,7 @@ views, since they depend on the contents of the `GtkTextBuffer`. c:identifier="gtk_text_view_forward_display_line"> Moves the given @iter forward by one display (wrapped) line. + line="10089">Moves the given @iter forward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. @@ -147134,24 +150658,24 @@ wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. - + %TRUE if @iter was moved and is not on the end iterator + line="10104">%TRUE if @iter was moved and is not on the end iterator a `GtkTextView` + line="10091">a `GtkTextView` a `GtkTextIter` + line="10092">a `GtkTextIter` @@ -147160,7 +150684,7 @@ views, since they depend on the contents of the `GtkTextBuffer`. c:identifier="gtk_text_view_forward_display_line_end"> Moves the given @iter forward to the next display line end. + line="10147">Moves the given @iter forward to the next display line end. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. @@ -147169,24 +150693,24 @@ wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. - + %TRUE if @iter was moved and is not on the end iterator + line="10162">%TRUE if @iter was moved and is not on the end iterator a `GtkTextView` + line="10149">a `GtkTextView` a `GtkTextIter` + line="10150">a `GtkTextIter` @@ -147194,17 +150718,16 @@ views, since they depend on the contents of the `GtkTextBuffer`. - Returns whether pressing the <kbd>Tab</kbd> key inserts a tab characters. + line="7500">Returns whether pressing the <kbd>Tab</kbd> key inserts a tab characters. See [method@Gtk.TextView.set_accepts_tab]. - + %TRUE if pressing the Tab key inserts a tab character, + line="7508">%TRUE if pressing the Tab key inserts a tab character, %FALSE if pressing the Tab key moves the keyboard focus. @@ -147212,7 +150735,7 @@ See [method@Gtk.TextView.set_accepts_tab]. A `GtkTextView` + line="7502">A `GtkTextView` @@ -147220,22 +150743,21 @@ See [method@Gtk.TextView.set_accepts_tab]. - Gets the bottom margin for text in the @text_view. - + line="3859">Gets the bottom margin for text in the @text_view. + bottom margin in pixels + line="3865">bottom margin in pixels a `GtkTextView` + line="3861">a `GtkTextView` @@ -147243,10 +150765,9 @@ See [method@Gtk.TextView.set_accepts_tab]. - Returns the `GtkTextBuffer` being displayed by this text view. + line="2457">Returns the `GtkTextBuffer` being displayed by this text view. The reference count on the buffer is not incremented; the caller of this function won’t own a new reference. @@ -147254,14 +150775,14 @@ of this function won’t own a new reference. a `GtkTextBuffer` + line="2466">a `GtkTextBuffer` a `GtkTextView` + line="2459">a `GtkTextView` @@ -147270,7 +150791,7 @@ of this function won’t own a new reference. c:identifier="gtk_text_view_get_cursor_locations"> Determine the positions of the strong and weak cursors if the + line="2476">Determine the positions of the strong and weak cursors if the insertion point is at @iter. The position of each cursor is stored as a zero-width rectangle. @@ -147290,7 +150811,7 @@ cursor’s offset within the preedit sequence. The rectangle position is in buffer coordinates; use [method@Gtk.TextView.buffer_to_window_coords] to convert these coordinates to coordinates for one of the windows in the text view. - + @@ -147298,7 +150819,7 @@ coordinates to coordinates for one of the windows in the text view. a `GtkTextView` + line="2478">a `GtkTextView` allow-none="1"> a `GtkTextIter` + line="2479">a `GtkTextIter` allow-none="1"> location to store the strong cursor position + line="2480">location to store the strong cursor position allow-none="1"> location to store the weak cursor position + line="2481">location to store the weak cursor position @@ -147337,22 +150858,21 @@ coordinates to coordinates for one of the windows in the text view. - Find out whether the cursor should be displayed. - + line="4035">Find out whether the cursor should be displayed. + whether the insertion mark is visible + line="4041">whether the insertion mark is visible a `GtkTextView` + line="4037">a `GtkTextView` @@ -147360,24 +150880,23 @@ coordinates to coordinates for one of the windows in the text view. - Returns the default editability of the `GtkTextView`. + line="3448">Returns the default editability of the `GtkTextView`. Tags in the buffer may override this setting for some ranges of text. - + whether text is editable by default + line="3456">whether text is editable by default a `GtkTextView` + line="3450">a `GtkTextView` @@ -147385,23 +150904,22 @@ Tags in the buffer may override this setting for some ranges of text. - Gets the menu model that gets added to the context menu + line="10501">Gets the menu model that gets added to the context menu or %NULL if none has been set. - + the menu model + line="10508">the menu model a `GtkTextView` + line="10503">a `GtkTextView` @@ -147409,30 +150927,30 @@ or %NULL if none has been set. Gets a `GtkWidget` that has previously been set as gutter. + line="4744">Gets a `GtkWidget` that has previously been set as gutter. See [method@Gtk.TextView.set_gutter]. @win must be one of %GTK_TEXT_WINDOW_LEFT, %GTK_TEXT_WINDOW_RIGHT, %GTK_TEXT_WINDOW_TOP, or %GTK_TEXT_WINDOW_BOTTOM. - + a `GtkWidget` + line="4756">a `GtkWidget` a `GtkTextView` + line="4746">a `GtkTextView` a `GtkTextWindowType` + line="4747">a `GtkTextWindowType` @@ -147440,25 +150958,24 @@ See [method@Gtk.TextView.set_gutter]. - Gets the default indentation of paragraphs in @text_view. + line="3908">Gets the default indentation of paragraphs in @text_view. Tags in the view’s buffer may override the default. The indentation may be negative. - + number of pixels of indentation + line="3917">number of pixels of indentation a `GtkTextView` + line="3910">a `GtkTextView` @@ -147466,19 +150983,21 @@ The indentation may be negative. - Gets the `input-hints` of the `GtkTextView`. - + line="10341">Gets the `input-hints` of the `GtkTextView`. + + the input hints a `GtkTextView` + line="10343">a `GtkTextView` @@ -147486,19 +151005,21 @@ The indentation may be negative. - Gets the `input-purpose` of the `GtkTextView`. - + line="10291">Gets the `input-purpose` of the `GtkTextView`. + + the input purpose a `GtkTextView` + line="10293">a `GtkTextView` @@ -147507,24 +151028,24 @@ The indentation may be negative. c:identifier="gtk_text_view_get_iter_at_location"> Retrieves the iterator at buffer coordinates @x and @y. + line="2528">Retrieves the iterator at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with [method@Gtk.TextView.window_to_buffer_coords]. - + %TRUE if the position is over text + line="2542">%TRUE if the position is over text a `GtkTextView` + line="2530">a `GtkTextView` a `GtkTextIter` + line="2531">a `GtkTextIter` x position, in buffer coordinates + line="2532">x position, in buffer coordinates y position, in buffer coordinates + line="2533">y position, in buffer coordinates @@ -147554,7 +151075,7 @@ event, you have to convert those to buffer coordinates with c:identifier="gtk_text_view_get_iter_at_position"> Retrieves the iterator pointing to the character at buffer + line="2558">Retrieves the iterator pointing to the character at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just @@ -147564,18 +151085,18 @@ you have to convert those to buffer coordinates with Note that this is different from [method@Gtk.TextView.get_iter_at_location], which returns cursor locations, i.e. positions between characters. - + %TRUE if the position is over text + line="2580">%TRUE if the position is over text a `GtkTextView` + line="2560">a `GtkTextView` transfer-ownership="none"> a `GtkTextIter` + line="2561">a `GtkTextIter` allow-none="1"> if non-%NULL, location to store + line="2562">if non-%NULL, location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the grapheme. @@ -147604,13 +151125,13 @@ which returns cursor locations, i.e. positions between characters. x position, in buffer coordinates + line="2566">x position, in buffer coordinates y position, in buffer coordinates + line="2567">y position, in buffer coordinates @@ -147619,12 +151140,12 @@ which returns cursor locations, i.e. positions between characters. c:identifier="gtk_text_view_get_iter_location"> Gets a rectangle which roughly contains the character at @iter. + line="2597">Gets a rectangle which roughly contains the character at @iter. The rectangle position is in buffer coordinates; use [method@Gtk.TextView.buffer_to_window_coords] to convert these coordinates to coordinates for one of the windows in the text view. - + @@ -147632,13 +151153,13 @@ coordinates to coordinates for one of the windows in the text view. a `GtkTextView` + line="2599">a `GtkTextView` a `GtkTextIter` + line="2600">a `GtkTextIter` transfer-ownership="none"> bounds of the character at @iter + line="2601">bounds of the character at @iter @@ -147655,24 +151176,23 @@ coordinates to coordinates for one of the windows in the text view. - Gets the default justification of paragraphs in @text_view. + line="3655">Gets the default justification of paragraphs in @text_view. Tags in the buffer may override the default. - + default justification + line="3663">default justification a `GtkTextView` + line="3657">a `GtkTextView` @@ -147680,24 +151200,23 @@ Tags in the buffer may override the default. - Gets the default left margin size of paragraphs in the @text_view. + line="3708">Gets the default left margin size of paragraphs in the @text_view. Tags in the buffer may override the default. - + left margin in pixels + line="3716">left margin in pixels a `GtkTextView` + line="3710">a `GtkTextView` @@ -147705,14 +151224,14 @@ Tags in the buffer may override the default. Gets the `GtkTextIter` at the start of the line containing + line="2652">Gets the `GtkTextIter` at the start of the line containing the coordinate @y. @y is in buffer coordinates, convert from window coordinates with [method@Gtk.TextView.window_to_buffer_coords]. If non-%NULL, @line_top will be filled with the coordinate of the top edge of the line. - + @@ -147720,7 +151239,7 @@ of the line. a `GtkTextView` + line="2654">a `GtkTextView` transfer-ownership="none"> a `GtkTextIter` + line="2655">a `GtkTextIter` a y coordinate + line="2656">a y coordinate transfer-ownership="full"> return location for top coordinate of the line + line="2657">return location for top coordinate of the line @@ -147753,12 +151272,12 @@ of the line. c:identifier="gtk_text_view_get_line_yrange"> Gets the y coordinate of the top of the line containing @iter, + line="2622">Gets the y coordinate of the top of the line containing @iter, and the height of the line. The coordinate is a buffer coordinate; convert to window coordinates with [method@Gtk.TextView.buffer_to_window_coords]. - + @@ -147766,13 +151285,13 @@ coordinates with [method@Gtk.TextView.buffer_to_window_coords]. a `GtkTextView` + line="2624">a `GtkTextView` a `GtkTextIter` + line="2625">a `GtkTextIter` transfer-ownership="full"> return location for a y coordinate + line="2626">return location for a y coordinate transfer-ownership="full"> return location for a height + line="2627">return location for a height @@ -147800,22 +151319,22 @@ coordinates with [method@Gtk.TextView.buffer_to_window_coords]. version="4.4"> Gets the `PangoContext` that is used for rendering LTR directed + line="10572">Gets the `PangoContext` that is used for rendering LTR directed text layouts. The context may be replaced when CSS changes occur. - + a `PangoContext` + line="10581">a `PangoContext` a `GtkTextView` + line="10574">a `GtkTextView` @@ -147823,22 +151342,21 @@ The context may be replaced when CSS changes occur. - Gets whether the `GtkTextView` uses monospace styling. - + line="10392">Gets whether the `GtkTextView` uses monospace styling. + %TRUE if monospace fonts are desired + line="10398">%TRUE if monospace fonts are desired a `GtkTextView` + line="10394">a `GtkTextView` @@ -147846,22 +151364,21 @@ The context may be replaced when CSS changes occur. - Returns whether the `GtkTextView` is in overwrite mode or not. - + line="7435">Returns whether the `GtkTextView` is in overwrite mode or not. + whether @text_view is in overwrite mode or not. + line="7441">whether @text_view is in overwrite mode or not. a `GtkTextView` + line="7437">a `GtkTextView` @@ -147869,26 +151386,24 @@ The context may be replaced when CSS changes occur. - Gets the default number of pixels to put above paragraphs. + line="3499">Gets the default number of pixels to put above paragraphs. Adding this function with [method@Gtk.TextView.get_pixels_below_lines] is equal to the line space between each paragraph. - + default number of pixels above paragraphs + line="3508">default number of pixels above paragraphs a `GtkTextView` + line="3501">a `GtkTextView` @@ -147896,26 +151411,24 @@ is equal to the line space between each paragraph. - Gets the default number of pixels to put below paragraphs. + line="3552">Gets the default number of pixels to put below paragraphs. The line space is the sum of the value returned by this function and the value returned by [method@Gtk.TextView.get_pixels_above_lines]. - + default number of blank pixels below paragraphs + line="3561">default number of blank pixels below paragraphs a `GtkTextView` + line="3554">a `GtkTextView` @@ -147923,24 +151436,22 @@ the value returned by [method@Gtk.TextView.get_pixels_above_lines]. - Gets the default number of pixels to put between wrapped lines + line="3605">Gets the default number of pixels to put between wrapped lines inside a paragraph. - + default number of pixels of blank space between wrapped lines + line="3612">default number of pixels of blank space between wrapped lines a `GtkTextView` + line="3607">a `GtkTextView` @@ -147948,24 +151459,23 @@ inside a paragraph. - Gets the default right margin for text in @text_view. + line="3761">Gets the default right margin for text in @text_view. Tags in the buffer may override the default. - + right margin in pixels + line="3769">right margin in pixels a `GtkTextView` + line="3763">a `GtkTextView` @@ -147975,22 +151485,22 @@ Tags in the buffer may override the default. version="4.4"> Gets the `PangoContext` that is used for rendering RTL directed + line="10595">Gets the `PangoContext` that is used for rendering RTL directed text layouts. The context may be replaced when CSS changes occur. - + a `PangoContext` + line="10604">a `PangoContext` a `GtkTextView` + line="10597">a `GtkTextView` @@ -147998,19 +151508,18 @@ The context may be replaced when CSS changes occur. - Gets the default tabs for @text_view. + line="3966">Gets the default tabs for @text_view. Tags in the buffer may override the defaults. The returned array will be %NULL if “standard” (8-space) tabs are used. Free the return value with [method@Pango.TabArray.free]. - + copy of default tab array, + line="3976">copy of default tab array, or %NULL if standard tabs are used; must be freed with [method@Pango.TabArray.free]. @@ -148019,7 +151528,7 @@ return value with [method@Pango.TabArray.free]. a `GtkTextView` + line="3968">a `GtkTextView` @@ -148027,31 +151536,77 @@ return value with [method@Pango.TabArray.free]. - Gets the top margin for text in the @text_view. - + line="3813">Gets the top margin for text in the @text_view. + top margin in pixels + line="3819">top margin in pixels a `GtkTextView` + line="3815">a `GtkTextView` + + Gets the X,Y offset in buffer coordinates of the top-left corner of +the textview's text contents. + +This allows for more-precise positioning than what is provided by +[method@Gtk.TextView.get_visible_rect()] as you can discover what +device pixel is being quantized for text positioning. + +You might want this when making ulterior widgets align with quantized +device pixels of the textview contents such as line numbers. + + + + + + + a `GtkTextView` + + + + a location for the X offset + + + + a location for the Y offset + + + + Fills @visible_rect with the currently-visible + line="3278">Fills @visible_rect with the currently-visible region of the buffer, in buffer coordinates. Convert to window coordinates with @@ -148064,7 +151619,7 @@ Convert to window coordinates with a `GtkTextView` + line="3280">a `GtkTextView` rectangle to fill + line="3281">rectangle to fill @@ -148081,22 +151636,21 @@ Convert to window coordinates with - Gets the line wrapping for the view. - + line="3377">Gets the line wrapping for the view. + the line wrap setting + line="3383">the line wrap setting a `GtkTextView` + line="3379">a `GtkTextView` @@ -148105,7 +151659,7 @@ Convert to window coordinates with c:identifier="gtk_text_view_im_context_filter_keypress"> Allow the `GtkTextView` input method to internally handle key press + line="8361">Allow the `GtkTextView` input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be @@ -148136,24 +151690,24 @@ gtk_foo_bar_key_press_event (GtkWidget *widget, return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class)->key_press_event (widget, event); } ``` - + %TRUE if the input method handled the key event. + line="8398">%TRUE if the input method handled the key event. a `GtkTextView` + line="8363">a `GtkTextView` the key event + line="8364">the key event @@ -148162,26 +151716,26 @@ gtk_foo_bar_key_press_event (GtkWidget *widget, c:identifier="gtk_text_view_move_mark_onscreen"> Moves a mark within the buffer so that it's + line="3248">Moves a mark within the buffer so that it's located within the currently-visible text area. %TRUE if the mark moved (wasn’t already onscreen) + line="3256">%TRUE if the mark moved (wasn’t already onscreen) a `GtkTextView` + line="3250">a `GtkTextView` a `GtkTextMark` + line="3251">a `GtkTextMark` @@ -148189,10 +151743,10 @@ located within the currently-visible text area. Updates the position of a child. + line="10060">Updates the position of a child. See [method@Gtk.TextView.add_overlay]. - + @@ -148200,25 +151754,25 @@ See [method@Gtk.TextView.add_overlay]. a `GtkTextView` + line="10062">a `GtkTextView` a widget already added with [method@Gtk.TextView.add_overlay] + line="10063">a widget already added with [method@Gtk.TextView.add_overlay] new X position in buffer coordinates + line="10064">new X position in buffer coordinates new Y position in buffer coordinates + line="10065">new Y position in buffer coordinates @@ -148226,7 +151780,7 @@ See [method@Gtk.TextView.add_overlay]. Move the iterator a given number of characters visually, treating + line="10229">Move the iterator a given number of characters visually, treating it as the strong cursor position. If @count is positive, then the new strong cursor position will @@ -148238,30 +151792,30 @@ In the presence of bi-directional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run. - + %TRUE if @iter moved and is not on the end iterator + line="10249">%TRUE if @iter moved and is not on the end iterator a `GtkTextView` + line="10231">a `GtkTextView` a `GtkTextIter` + line="10232">a `GtkTextIter` number of characters to move (negative moves left, + line="10233">number of characters to move (negative moves left, positive moves right) @@ -148271,20 +151825,20 @@ is moved off of the end of a run. c:identifier="gtk_text_view_place_cursor_onscreen"> Moves the cursor to the currently visible region of the + line="4073">Moves the cursor to the currently visible region of the buffer. %TRUE if the cursor had to be moved. + line="4080">%TRUE if the cursor had to be moved. a `GtkTextView` + line="4075">a `GtkTextView` @@ -148292,8 +151846,8 @@ buffer. Removes a child widget from @text_view. - + line="6226">Removes a child widget from @text_view. + @@ -148301,13 +151855,13 @@ buffer. a `GtkTextView` + line="6228">a `GtkTextView` the child to remove + line="6229">the child to remove @@ -148316,7 +151870,7 @@ buffer. c:identifier="gtk_text_view_reset_cursor_blink"> Ensures that the cursor is shown. + line="4051">Ensures that the cursor is shown. This also resets the time that it will stay blinking (or visible, in case blinking is disabled). @@ -148324,7 +151878,7 @@ visible, in case blinking is disabled). This function should be called in response to user input (e.g. from derived classes that override the textview's event handlers). - + @@ -148332,7 +151886,7 @@ event handlers). a `GtkTextView` + line="4053">a `GtkTextView` @@ -148341,11 +151895,11 @@ event handlers). c:identifier="gtk_text_view_reset_im_context"> Reset the input method context of the text view if needed. + line="8340">Reset the input method context of the text view if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. - + @@ -148353,7 +151907,7 @@ would confuse on-going input method behavior. a `GtkTextView` + line="8342">a `GtkTextView` @@ -148362,7 +151916,7 @@ would confuse on-going input method behavior. c:identifier="gtk_text_view_scroll_mark_onscreen"> Scrolls @text_view the minimum distance such that @mark is contained + line="3214">Scrolls @text_view the minimum distance such that @mark is contained within the visible area of the widget. @@ -148372,13 +151926,13 @@ within the visible area of the widget. a `GtkTextView` + line="3216">a `GtkTextView` a mark in the buffer for @text_view + line="3217">a mark in the buffer for @text_view @@ -148387,7 +151941,7 @@ within the visible area of the widget. c:identifier="gtk_text_view_scroll_to_iter"> Scrolls @text_view so that @iter is on the screen in the position + line="2899">Scrolls @text_view so that @iter is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or @@ -148406,45 +151960,45 @@ scrolled to after line validation. %TRUE if scrolling occurred + line="2925">%TRUE if scrolling occurred a `GtkTextView` + line="2901">a `GtkTextView` a `GtkTextIter` + line="2902">a `GtkTextIter` margin as a [0.0,0.5) fraction of screen size + line="2903">margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, + line="2904">whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area + line="2906">horizontal alignment of mark within visible area vertical alignment of mark within visible area + line="2907">vertical alignment of mark within visible area @@ -148453,7 +152007,7 @@ scrolled to after line validation. c:identifier="gtk_text_view_scroll_to_mark"> Scrolls @text_view so that @mark is on the screen in the position + line="3162">Scrolls @text_view so that @mark is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or @@ -148469,38 +152023,38 @@ by a margin of size @within_margin. a `GtkTextView` + line="3164">a `GtkTextView` a `GtkTextMark` + line="3165">a `GtkTextMark` margin as a [0.0,0.5) fraction of screen size + line="3166">margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just + line="3167">whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area + line="3169">horizontal alignment of mark within visible area vertical alignment of mark within visible area + line="3170">vertical alignment of mark within visible area @@ -148508,17 +152062,16 @@ by a margin of size @within_margin. - Sets the behavior of the text widget when the <kbd>Tab</kbd> key is pressed. + line="7469">Sets the behavior of the text widget when the <kbd>Tab</kbd> key is pressed. If @accepts_tab is %TRUE, a tab character is inserted. If @accepts_tab is %FALSE the keyboard focus is moved to the next widget in the focus chain. Focus can always be moved using <kbd>Ctrl</kbd>+<kbd>Tab</kbd>. - + @@ -148526,13 +152079,13 @@ Focus can always be moved using <kbd>Ctrl</kbd>+<kbd>Tab</k A `GtkTextView` + line="7471">A `GtkTextView` %TRUE if pressing the Tab key should insert a tab + line="7472">%TRUE if pressing the Tab key should insert a tab character, %FALSE, if pressing the Tab key should move the keyboard focus. @@ -148542,14 +152095,13 @@ Focus can always be moved using <kbd>Ctrl</kbd>+<kbd>Tab</k - Sets the bottom margin for text in @text_view. + line="3829">Sets the bottom margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. - + @@ -148557,13 +152109,13 @@ In CSS terms, the value set here is padding. a `GtkTextView` + line="3831">a `GtkTextView` bottom margin in pixels + line="3832">bottom margin in pixels @@ -148571,10 +152123,9 @@ In CSS terms, the value set here is padding. - Sets @buffer as the buffer being displayed by @text_view. + line="2294">Sets @buffer as the buffer being displayed by @text_view. The previous buffer displayed by the text view is unreferenced, and a reference is added to @buffer. If you owned a reference to @buffer @@ -148588,7 +152139,7 @@ yourself; `GtkTextView` will not “adopt” it. a `GtkTextView` + line="2296">a `GtkTextView` allow-none="1"> a `GtkTextBuffer` + line="2297">a `GtkTextBuffer` @@ -148605,17 +152156,16 @@ yourself; `GtkTextView` will not “adopt” it. - Toggles whether the insertion point should be displayed. + line="3994">Toggles whether the insertion point should be displayed. A buffer with no editable text probably shouldn’t have a visible cursor, so you may want to turn the cursor off. Note that this property may be overridden by the [property@Gtk.Settings:gtk-keynav-use-caret] setting. - + @@ -148623,13 +152173,13 @@ Note that this property may be overridden by the a `GtkTextView` + line="3996">a `GtkTextView` whether to show the insertion cursor + line="3997">whether to show the insertion cursor @@ -148637,14 +152187,13 @@ Note that this property may be overridden by the - Sets the default editability of the `GtkTextView`. + line="3393">Sets the default editability of the `GtkTextView`. You can override this default setting with tags in the buffer, using the “editable” attribute of tags. - + @@ -148652,13 +152201,13 @@ using the “editable” attribute of tags. a `GtkTextView` + line="3395">a `GtkTextView` whether it’s editable + line="3396">whether it’s editable @@ -148666,14 +152215,13 @@ using the “editable” attribute of tags. - Sets a menu model to add when constructing the context + line="10476">Sets a menu model to add when constructing the context menu for @text_view. You can pass %NULL to remove a previously set extra menu. - + @@ -148681,7 +152229,7 @@ You can pass %NULL to remove a previously set extra menu. a `GtkTextView` + line="10478">a `GtkTextView` allow-none="1"> a `GMenuModel` + line="10479">a `GMenuModel` @@ -148698,11 +152246,11 @@ You can pass %NULL to remove a previously set extra menu. Places @widget into the gutter specified by @win. + line="4778">Places @widget into the gutter specified by @win. @win must be one of %GTK_TEXT_WINDOW_LEFT, %GTK_TEXT_WINDOW_RIGHT, %GTK_TEXT_WINDOW_TOP, or %GTK_TEXT_WINDOW_BOTTOM. - + @@ -148710,13 +152258,13 @@ You can pass %NULL to remove a previously set extra menu. a `GtkTextView` + line="4780">a `GtkTextView` a `GtkTextWindowType` + line="4781">a `GtkTextWindowType` allow-none="1"> a `GtkWidget` + line="4782">a `GtkWidget` @@ -148733,13 +152281,12 @@ You can pass %NULL to remove a previously set extra menu. - Sets the default indentation for paragraphs in @text_view. + line="3875">Sets the default indentation for paragraphs in @text_view. Tags in the buffer may override the default. - + @@ -148747,13 +152294,13 @@ Tags in the buffer may override the default. a `GtkTextView` + line="3877">a `GtkTextView` indentation in pixels + line="3878">indentation in pixels @@ -148761,14 +152308,13 @@ Tags in the buffer may override the default. - Sets the `input-hints` of the `GtkTextView`. + line="10313">Sets the `input-hints` of the `GtkTextView`. The `input-hints` allow input methods to fine-tune their behaviour. - + @@ -148776,13 +152322,13 @@ their behaviour. a `GtkTextView` + line="10315">a `GtkTextView` the hints + line="10316">the hints @@ -148790,14 +152336,13 @@ their behaviour. - Sets the `input-purpose` of the `GtkTextView`. + line="10264">Sets the `input-purpose` of the `GtkTextView`. The `input-purpose` can be used by on-screen keyboards and other input methods to adjust their behaviour. - + @@ -148805,13 +152350,13 @@ and other input methods to adjust their behaviour. a `GtkTextView` + line="10266">a `GtkTextView` the purpose + line="10267">the purpose @@ -148819,13 +152364,12 @@ and other input methods to adjust their behaviour. - Sets the default justification of text in @text_view. + line="3622">Sets the default justification of text in @text_view. Tags in the view’s buffer may override the default. - + @@ -148833,13 +152377,13 @@ Tags in the view’s buffer may override the default. a `GtkTextView` + line="3624">a `GtkTextView` justification + line="3625">justification @@ -148847,16 +152391,15 @@ Tags in the view’s buffer may override the default. - Sets the default left margin for text in @text_view. + line="3673">Sets the default left margin for text in @text_view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. - + @@ -148864,13 +152407,13 @@ In CSS terms, the value set here is padding. a `GtkTextView` + line="3675">a `GtkTextView` left margin in pixels + line="3676">left margin in pixels @@ -148878,12 +152421,11 @@ In CSS terms, the value set here is padding. - Sets whether the `GtkTextView` should display text in + line="10363">Sets whether the `GtkTextView` should display text in monospace styling. - + @@ -148891,13 +152433,13 @@ monospace styling. a `GtkTextView` + line="10365">a `GtkTextView` %TRUE to request monospace styling + line="10366">%TRUE to request monospace styling @@ -148905,11 +152447,10 @@ monospace styling. - Changes the `GtkTextView` overwrite mode. - + line="7451">Changes the `GtkTextView` overwrite mode. + @@ -148917,13 +152458,13 @@ monospace styling. a `GtkTextView` + line="7453">a `GtkTextView` %TRUE to turn on overwrite mode, %FALSE to turn it off + line="7454">%TRUE to turn on overwrite mode, %FALSE to turn it off @@ -148931,14 +152472,12 @@ monospace styling. - Sets the default number of blank pixels above paragraphs in @text_view. + line="3466">Sets the default number of blank pixels above paragraphs in @text_view. Tags in the buffer for @text_view may override the defaults. - + @@ -148946,13 +152485,13 @@ Tags in the buffer for @text_view may override the defaults. a `GtkTextView` + line="3468">a `GtkTextView` pixels above paragraphs + line="3469">pixels above paragraphs @@ -148960,15 +152499,13 @@ Tags in the buffer for @text_view may override the defaults. - Sets the default number of pixels of blank space + line="3518">Sets the default number of pixels of blank space to put below paragraphs in @text_view. May be overridden by tags applied to @text_view’s buffer. - + @@ -148976,13 +152513,13 @@ May be overridden by tags applied to @text_view’s buffer. a `GtkTextView` + line="3520">a `GtkTextView` pixels below paragraphs + line="3521">pixels below paragraphs @@ -148990,15 +152527,13 @@ May be overridden by tags applied to @text_view’s buffer. - Sets the default number of pixels of blank space to leave between + line="3571">Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. May be overridden by tags in @text_view’s buffer. - + @@ -149006,13 +152541,13 @@ May be overridden by tags in @text_view’s buffer. a `GtkTextView` + line="3573">a `GtkTextView` default number of pixels between wrapped lines + line="3574">default number of pixels between wrapped lines @@ -149020,16 +152555,15 @@ May be overridden by tags in @text_view’s buffer. - Sets the default right margin for text in the text view. + line="3726">Sets the default right margin for text in the text view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. - + @@ -149037,13 +152571,13 @@ In CSS terms, the value set here is padding. a `GtkTextView` + line="3728">a `GtkTextView` right margin in pixels + line="3729">right margin in pixels @@ -149051,13 +152585,12 @@ In CSS terms, the value set here is padding. - Sets the default tab stops for paragraphs in @text_view. + line="3927">Sets the default tab stops for paragraphs in @text_view. Tags in the buffer may override the default. - + @@ -149065,13 +152598,13 @@ Tags in the buffer may override the default. a `GtkTextView` + line="3929">a `GtkTextView` tabs as a `PangoTabArray` + line="3930">tabs as a `PangoTabArray` @@ -149079,14 +152612,13 @@ Tags in the buffer may override the default. - Sets the top margin for text in @text_view. + line="3779">Sets the top margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. - + @@ -149094,13 +152626,13 @@ In CSS terms, the value set here is padding. a `GtkTextView` + line="3781">a `GtkTextView` top margin in pixels + line="3782">top margin in pixels @@ -149108,11 +152640,10 @@ In CSS terms, the value set here is padding. - Sets the line wrapping for the view. - + line="3347">Sets the line wrapping for the view. + @@ -149120,13 +152651,13 @@ In CSS terms, the value set here is padding. a `GtkTextView` + line="3349">a `GtkTextView` a `GtkWrapMode` + line="3350">a `GtkWrapMode` @@ -149135,28 +152666,28 @@ In CSS terms, the value set here is padding. c:identifier="gtk_text_view_starts_display_line"> Determines whether @iter is at the start of a display line. + line="10205">Determines whether @iter is at the start of a display line. See [method@Gtk.TextView.forward_display_line] for an explanation of display lines vs. paragraphs. - + %TRUE if @iter begins a wrapped line + line="10215">%TRUE if @iter begins a wrapped line a `GtkTextView` + line="10207">a `GtkTextView` a `GtkTextIter` + line="10208">a `GtkTextIter` @@ -149165,9 +152696,9 @@ explanation of display lines vs. paragraphs. c:identifier="gtk_text_view_window_to_buffer_coords"> Converts coordinates on the window identified by @win to buffer + line="9861">Converts coordinates on the window identified by @win to buffer coordinates. - + @@ -149175,25 +152706,25 @@ coordinates. a `GtkTextView` + line="9863">a `GtkTextView` a `GtkTextWindowType` + line="9864">a `GtkTextWindowType` window x coordinate + line="9865">window x coordinate window y coordinate + line="9866">window y coordinate allow-none="1"> buffer x coordinate return location + line="9867">buffer x coordinate return location allow-none="1"> buffer y coordinate return location + line="9868">buffer y coordinate return location @@ -149226,13 +152757,9 @@ coordinates. setter="set_accepts_tab" getter="get_accepts_tab" default-value="TRUE"> - - Whether Tab will result in a tab character being entered. + line="1140">Whether Tab will result in a tab character being entered. setter="set_bottom_margin" getter="get_bottom_margin" default-value="0"> - - The bottom margin for text in the text view. + line="1063">The bottom margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition @@ -149261,13 +152784,9 @@ Don't confuse this property with [property@Gtk.Widget:margin-bottom]. transfer-ownership="none" setter="set_buffer" getter="get_buffer"> - - The buffer which is displayed. + line="1118">The buffer which is displayed. setter="set_cursor_visible" getter="get_cursor_visible" default-value="TRUE"> - - If the insertion cursor is shown. + line="1107">If the insertion cursor is shown. setter="set_editable" getter="get_editable" default-value="TRUE"> + Whether the text can be modified by the user. transfer-ownership="none" setter="set_extra_menu" getter="get_extra_menu"> - - A menu model whose contents will be appended to the context menu. + line="1211">A menu model whose contents will be appended to the context menu. default-value="NULL"> Which IM (input method) module should be used for this text_view. + line="1151">Which IM (input method) module should be used for this text_view. See [class@Gtk.IMMulticontext]. @@ -149327,13 +152841,9 @@ setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module] property. - - Amount to indent the paragraph, in pixels. + line="1080">Amount to indent the paragraph, in pixels. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent @@ -149346,13 +152856,9 @@ lines will be indented by the absolute value of indent. setter="set_input_hints" getter="get_input_hints" default-value="GTK_INPUT_HINT_NONE"> - - Additional hints (beyond [property@Gtk.TextView:input-purpose]) + line="1183">Additional hints (beyond [property@Gtk.TextView:input-purpose]) that allow input methods to fine-tune their behaviour. @@ -149362,13 +152868,9 @@ that allow input methods to fine-tune their behaviour. setter="set_input_purpose" getter="get_input_purpose" default-value="GTK_INPUT_PURPOSE_FREE_FORM"> - - The purpose of this text field. + line="1167">The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. @@ -149380,6 +152882,9 @@ methods to adjust their behaviour. setter="set_justification" getter="get_justification" default-value="GTK_JUSTIFY_LEFT"> + Left, right, or center justification. setter="set_left_margin" getter="get_left_margin" default-value="0"> - - The default left margin for text in the text view. + line="1012">The default left margin for text in the text view. Tags in the buffer may override the default. @@ -149409,13 +152910,9 @@ to the padding from the theme. setter="set_monospace" getter="get_monospace" default-value="FALSE"> - - Whether text should be displayed in a monospace font. + line="1197">Whether text should be displayed in a monospace font. If %TRUE, set the .monospace style class on the text view to indicate that a monospace font is desired. @@ -149427,13 +152924,9 @@ text view to indicate that a monospace font is desired. setter="set_overwrite" getter="get_overwrite" default-value="FALSE"> - - Whether entered text overwrites existing contents. + line="1129">Whether entered text overwrites existing contents. setter="set_pixels_above_lines" getter="get_pixels_above_lines" default-value="0"> + Pixels of blank space above paragraphs. setter="set_pixels_below_lines" getter="get_pixels_below_lines" default-value="0"> + Pixels of blank space below paragraphs. setter="set_pixels_inside_wrap" getter="get_pixels_inside_wrap" default-value="0"> + Pixels of blank space between wrapped lines in a paragraph. setter="set_right_margin" getter="get_right_margin" default-value="0"> - - The default right margin for text in the text view. + line="1029">The default right margin for text in the text view. Tags in the buffer may override the default. @@ -149486,6 +152984,9 @@ to the padding from the theme. transfer-ownership="none" setter="set_tabs" getter="get_tabs"> + Custom tabs for this text. setter="set_top_margin" getter="get_top_margin" default-value="0"> - - The top margin for text in the text view. + line="1046">The top margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition @@ -149515,6 +153012,9 @@ Don't confuse this property with [property@Gtk.Widget:margin-top]. setter="set_wrap_mode" getter="get_wrap_mode" default-value="GTK_WRAP_NONE"> + Whether to wrap lines never, at word boundaries, or at character boundaries. @@ -149526,7 +153026,7 @@ Don't confuse this property with [property@Gtk.Widget:margin-top]. Gets emitted when the user asks for it. + line="1384">Gets emitted when the user asks for it. The ::backspace signal is a [keybinding signal](class.SignalAction.html). @@ -149539,7 +153039,7 @@ The default bindings for this signal are Gets emitted to copy the selection to the clipboard. + line="1425">Gets emitted to copy the selection to the clipboard. The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html). @@ -149553,7 +153053,7 @@ The default bindings for this signal are Gets emitted to cut the selection to the clipboard. + line="1404">Gets emitted to cut the selection to the clipboard. The ::cut-clipboard signal is a [keybinding signal](class.SignalAction.html). @@ -149567,7 +153067,7 @@ The default bindings for this signal are Gets emitted when the user initiates a text deletion. + line="1351">Gets emitted when the user initiates a text deletion. The ::delete-from-cursor signal is a [keybinding signal](class.SignalAction.html). @@ -149586,13 +153086,13 @@ deleting a word backwards. the granularity of the deletion, as a `GtkDeleteType` + line="1354">the granularity of the deletion, as a `GtkDeleteType` the number of @type units to delete + line="1355">the number of @type units to delete @@ -149600,11 +153100,11 @@ deleting a word backwards. Emitted when the selection needs to be extended at @location. + line="1555">Emitted when the selection needs to be extended at @location. %GDK_EVENT_STOP to stop other handlers from being invoked for the + line="1565">%GDK_EVENT_STOP to stop other handlers from being invoked for the event. %GDK_EVENT_PROPAGATE to propagate the event further. @@ -149612,25 +153112,25 @@ deleting a word backwards. the granularity type + line="1558">the granularity type the location where to extend the selection + line="1559">the location where to extend the selection where the selection should start + line="1560">where the selection should start where the selection should end + line="1561">where the selection should end @@ -149638,7 +153138,7 @@ deleting a word backwards. Gets emitted when the user initiates the insertion of a + line="1329">Gets emitted when the user initiates the insertion of a fixed string at the cursor. The ::insert-at-cursor signal is a [keybinding signal](class.SignalAction.html). @@ -149651,7 +153151,7 @@ This signal has no default bindings. the string to insert + line="1332">the string to insert @@ -149659,7 +153159,7 @@ This signal has no default bindings. Gets emitted to present the Emoji chooser for the @text_view. + line="1584">Gets emitted to present the Emoji chooser for the @text_view. The ::insert-emoji signal is a [keybinding signal](class.SignalAction.html). @@ -149673,7 +153173,7 @@ The default bindings for this signal are Gets emitted when the user initiates a cursor movement. + line="1232">Gets emitted when the user initiates a cursor movement. The ::move-cursor signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @text_view, this signal causes @@ -149703,19 +153203,19 @@ There are too many key combinations to list them all here. the granularity of the move, as a `GtkMovementStep` + line="1235">the granularity of the move, as a `GtkMovementStep` the number of @step units to move + line="1236">the number of @step units to move %TRUE if the move should extend the selection + line="1237">%TRUE if the move should extend the selection @@ -149723,7 +153223,7 @@ There are too many key combinations to list them all here. Gets emitted to move the viewport. + line="1278">Gets emitted to move the viewport. The ::move-viewport signal is a [keybinding signal](class.SignalAction.html), which can be bound to key combinations to allow the user to move the viewport, @@ -149738,13 +153238,13 @@ There are no default bindings for this signal. the granularity of the movement, as a `GtkScrollStep` + line="1281">the granularity of the movement, as a `GtkScrollStep` the number of @step units to move + line="1282">the number of @step units to move @@ -149752,7 +153252,7 @@ There are no default bindings for this signal. Gets emitted to paste the contents of the clipboard + line="1446">Gets emitted to paste the contents of the clipboard into the text view. The ::paste-clipboard signal is a [keybinding signal](class.SignalAction.html). @@ -149767,7 +153267,7 @@ The default bindings for this signal are Emitted when preedit text of the active IM changes. + line="1531">Emitted when preedit text of the active IM changes. If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, @@ -149782,7 +153282,7 @@ is actually editable. the current preedit string + line="1534">the current preedit string @@ -149790,7 +153290,7 @@ is actually editable. Gets emitted to select or unselect the complete contents of the text view. + line="1487">Gets emitted to select or unselect the complete contents of the text view. The ::select-all signal is a [keybinding signal](class.SignalAction.html). @@ -149806,7 +153306,7 @@ The default bindings for this signal are %TRUE to select, %FALSE to unselect + line="1490">%TRUE to select, %FALSE to unselect @@ -149814,7 +153314,7 @@ The default bindings for this signal are Gets emitted when the user initiates settings the "anchor" mark. + line="1307">Gets emitted when the user initiates settings the "anchor" mark. The ::set-anchor signal is a [keybinding signal](class.SignalAction.html) which gets emitted when the user initiates setting the "anchor" @@ -149829,7 +153329,7 @@ This signal has no default bindings. Gets emitted to toggle the `cursor-visible` property. + line="1511">Gets emitted to toggle the `cursor-visible` property. The ::toggle-cursor-visible signal is a [keybinding signal](class.SignalAction.html). @@ -149842,7 +153342,7 @@ The default binding for this signal is <kbd>F7</kbd>. Gets emitted to toggle the overwrite mode of the text view. + line="1468">Gets emitted to toggle the overwrite mode of the text view. The ::toggle-overwrite signal is a [keybinding signal](class.SignalAction.html). @@ -149863,6 +153363,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::move-cursor` + keybinding signal. @@ -149885,6 +153389,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::set-anchor` + keybinding signal. @@ -149898,6 +153406,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::insert-at-cursor` + keybinding signal. @@ -149914,6 +153426,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::delete-from-cursor` + keybinding signal. @@ -149933,6 +153449,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::backspace` + keybinding signal. @@ -149946,6 +153466,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::cut-clipboard` + keybinding signal @@ -149959,6 +153483,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::copy-clipboard` + keybinding signal. @@ -149972,6 +153500,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::paste-clipboard` + keybinding signal. @@ -149985,6 +153517,10 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::toggle-overwrite` + keybinding signal. @@ -149998,6 +153534,11 @@ The default binding for this signal is <kbd>Insert</kbd>. + The create_buffer vfunc is called to create a `GtkTextBuffer` + for the text view. The default implementation is to just call + gtk_text_buffer_new(). @@ -150011,6 +153552,13 @@ The default binding for this signal is <kbd>Insert</kbd>. + The snapshot_layer vfunc is called before and after the text + view is drawing its own text. Applications can override this vfunc + in a subclass to draw customized content underneath or above the + text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT + layers the drawing is done in the buffer coordinate space. @@ -150030,6 +153578,9 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::extend-selection` signal. @@ -150056,6 +153607,9 @@ The default binding for this signal is <kbd>Insert</kbd>. + The class handler for the `GtkTextView::insert-emoji` signal. @@ -150172,13 +153726,15 @@ drawing with the ::snapshot_layer vfunc. Callback type for adding a function to update animations. See gtk_widget_add_tick_callback(). - + line="67">Callback type for adding a function to update animations. + +See [method@Gtk.Widget.add_tick_callback]. + %G_SOURCE_CONTINUE if the tick callback should continue to be called, - %G_SOURCE_REMOVE if the tick callback should be removed. + line="77">`G_SOURCE_CONTINUE` if the tick callback should continue + to be called, `G_SOURCE_REMOVE` if it should be removed @@ -150191,7 +153747,7 @@ drawing with the ::snapshot_layer vfunc. the frame clock for the widget (same as calling gtk_widget_get_frame_clock()) + line="70">the frame clock for the widget closure="2"> user data passed to gtk_widget_add_tick_callback(). + line="71">user data passed to [method@Gtk.Widget.add_tick_callback]. @@ -150215,8 +153771,12 @@ drawing with the ::snapshot_layer vfunc. glib:type-struct="ToggleButtonClass"> A `GtkToggleButton` is a button which remains “pressed-in” when -clicked. + line="37">Shows a button which remains “pressed-in” when clicked. + +<picture> + <source srcset="toggle-button-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="Example GtkToggleButtons" src="toggle-button.png"> +</picture> Clicking again will cause the toggle button to return to its normal state. @@ -150229,9 +153789,6 @@ The state of a `GtkToggleButton` can be set specifically using [method@Gtk.ToggleButton.set_active], and retrieved using [method@Gtk.ToggleButton.get_active]. -To simply switch the state of a toggle button, use -[method@Gtk.ToggleButton.toggled]. - ## Grouping Toggle buttons can be grouped together, to form mutually exclusive @@ -150247,7 +153804,7 @@ it from a plain `GtkButton`, it gets the `.toggle` style class. ## Accessibility -`GtkToggleButton` uses the %GTK_ACCESSIBLE_ROLE_TOGGLE_BUTTON role. +`GtkToggleButton` uses the [enum@Gtk.AccessibleRole.toggle_button] role. ## Creating two `GtkToggleButton` widgets. @@ -150298,14 +153855,14 @@ make_toggles (void) Creates a new toggle button. + line="348">Creates a new toggle button. A widget should be packed into the button, as in [ctor@Gtk.Button.new]. a new toggle button. + line="355">a new toggle button. @@ -150313,19 +153870,19 @@ A widget should be packed into the button, as in [ctor@Gtk.Button.new]. c:identifier="gtk_toggle_button_new_with_label"> Creates a new toggle button with a text label. + line="363">Creates a new toggle button with a text label. a new toggle button. + line="369">a new toggle button. a string containing the message to be placed in the toggle button. + line="365">a string containing the message to be placed in the toggle button. @@ -150334,7 +153891,7 @@ A widget should be packed into the button, as in [ctor@Gtk.Button.new]. c:identifier="gtk_toggle_button_new_with_mnemonic"> Creates a new `GtkToggleButton` containing a label. + line="377">Creates a new `GtkToggleButton` containing a label. The label will be created using [ctor@Gtk.Label.new_with_mnemonic], so underscores in @label indicate the mnemonic for the button. @@ -150342,14 +153899,14 @@ so underscores in @label indicate the mnemonic for the button. a new `GtkToggleButton` + line="387">a new `GtkToggleButton` the text of the button, with an underscore in front of the + line="379">the text of the button, with an underscore in front of the mnemonic character @@ -150361,7 +153918,7 @@ so underscores in @label indicate the mnemonic for the button. deprecated-version="4.10"> Emits the ::toggled signal on the `GtkToggleButton`. + line="476">Emits the ::toggled signal on the `GtkToggleButton`. There is no good reason for an application ever to call this function. @@ -150371,7 +153928,7 @@ so underscores in @label indicate the mnemonic for the button. a `GtkToggleButton`. + line="478">a `GtkToggleButton`. @@ -150379,10 +153936,9 @@ so underscores in @label indicate the mnemonic for the button. - Queries a `GtkToggleButton` and returns its current state. + line="455">Queries a `GtkToggleButton` and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. @@ -150390,14 +153946,14 @@ if it is raised. whether the button is pressed + line="464">whether the button is pressed a `GtkToggleButton`. + line="457">a `GtkToggleButton`. @@ -150405,10 +153961,9 @@ if it is raised. - Sets the status of the toggle button. + line="398">Sets the status of the toggle button. Set to %TRUE if you want the `GtkToggleButton` to be “pressed in”, and %FALSE to raise it. @@ -150423,13 +153978,13 @@ If the status of the button changes, this action causes the a `GtkToggleButton`. + line="400">a `GtkToggleButton`. %TRUE or %FALSE. + line="401">%TRUE or %FALSE. @@ -150437,10 +153992,9 @@ If the status of the button changes, this action causes the - Adds @self to the group of @group. + line="492">Adds @self to the group of @group. In a group of multiple toggle buttons, only one button can be active at a time. @@ -150459,7 +154013,7 @@ value. a `GtkToggleButton` + line="494">a `GtkToggleButton` allow-none="1"> another `GtkToggleButton` to + line="495">another `GtkToggleButton` to form a group with @@ -150480,7 +154034,7 @@ value. deprecated-version="4.10"> Emits the ::toggled signal on the `GtkToggleButton`. + line="476">Emits the ::toggled signal on the `GtkToggleButton`. There is no good reason for an application ever to call this function. @@ -150490,7 +154044,7 @@ value. a `GtkToggleButton`. + line="478">a `GtkToggleButton`. @@ -150501,13 +154055,9 @@ value. setter="set_active" getter="get_active" default-value="FALSE"> - - If the toggle button should be pressed in. + line="295">If the toggle button should be pressed in. writable="1" transfer-ownership="none" setter="set_group"> - The toggle button whose group this widget belongs to. + line="305">The toggle button whose group this widget belongs to. @@ -150528,7 +154076,7 @@ value. Emitted whenever the `GtkToggleButton`'s state is changed. + line="317">Emitted whenever the `GtkToggleButton`'s state is changed. @@ -150551,7 +154099,7 @@ value. a `GtkToggleButton`. + line="478">a `GtkToggleButton`. @@ -150571,7 +154119,7 @@ value. glib:get-type="gtk_tooltip_get_type"> `GtkTooltip` is an object representing a widget tooltip. + line="38">Represents a widget tooltip. Basic tooltips can be realized simply by using [method@Gtk.Widget.set_tooltip_text] or @@ -151041,6 +154589,11 @@ parent of @dest_path doesn’t exist, though. + Asks the `GtkTreeDragDest` to insert a row + before the path dest, deriving the contents of the row from + selection_data. @@ -151072,6 +154625,10 @@ parent of @dest_path doesn’t exist, though. + Determines whether a drop is possible before + the given dest_path, at the same depth as dest_path. @@ -151324,6 +154881,10 @@ this interface, the row is assumed draggable. + Asks the `GtkTreeDragSource` whether a particular + row can be used as the source of a DND operation. @@ -151349,6 +154910,10 @@ this interface, the row is assumed draggable. + Asks the `GtkTreeDragSource` to fill in + selection_data with a representation of the row at path. @@ -151375,6 +154940,10 @@ this interface, the row is assumed draggable. + Asks the `GtkTreeDragSource` to delete the row at + path, because it was moved somewhere else via drag-and-drop. @@ -151409,7 +154978,7 @@ this interface, the row is assumed draggable. glib:type-struct="TreeExpanderClass"> `GtkTreeExpander` is a widget that provides an expander for a list. + line="34">Provides an expander for a tree-like list. It is typically placed as a bottommost child into a `GtkListView` to allow users to expand and collapse children in a list with a @@ -151441,6 +155010,28 @@ the [property@Gtk.TreeExpander:hide-expander] property to the item count of the model of the treelistrow, to hide the expander for rows without children, even if the row is expandable. +## Shortcuts and Gestures + +`GtkTreeExpander` supports the following keyboard shortcuts: + +- <kbd>+</kbd> or <kbd>*</kbd> expands the expander. +- <kbd>-</kbd> or <kbd>/</kbd> collapses the expander. +- Left and right arrow keys, when combined with <kbd>Shift</kbd> or + <kbd>Ctrl</kbd>+<kbd>Shift</kbd>, will expand or collapse, depending on + the locale's text direction. +- <kbd>Ctrl</kbd>+<kbd>␣</kbd> toggles the expander state. + +The row can also expand on drag gestures. + +## Actions + +`GtkTreeExpander` defines a set of built-in actions: + +- `listitem.expand` expands the expander if it can be expanded. +- `listitem.collapse` collapses the expander. +- `listitem.toggle-expand` tries to expand the expander if it was collapsed + or collapses it if it was expanded. + ## CSS nodes ``` @@ -151459,9 +155050,9 @@ For every level of depth, another "indent" node is prepended. ## Accessibility -Until GTK 4.10, `GtkTreeExpander` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkTreeExpander` used the [enum@Gtk.AccessibleRole.group] role. -Since GTK 4.12, `GtkTreeExpander` uses the `GTK_ACCESSIBLE_ROLE_BUTTON` role. +Since GTK 4.12, `GtkTreeExpander` uses the [enum@Gtk.AccessibleRole.button] role. Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. @@ -151470,34 +155061,33 @@ Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. Creates a new `GtkTreeExpander` + line="767">Creates a new `GtkTreeExpander` a new `GtkTreeExpander` + line="772">a new `GtkTreeExpander` - Gets the child widget displayed by @self. + line="781">Gets the child widget displayed by @self. The child displayed by @self + line="787">The child displayed by @self a `GtkTreeExpander` + line="783">a `GtkTreeExpander` @@ -151506,22 +155096,21 @@ Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. c:identifier="gtk_tree_expander_get_hide_expander" glib:get-property="hide-expander" version="4.10"> - Gets whether the TreeExpander should be hidden in a GtkTreeListRow. + line="998">Gets whether the TreeExpander should be hidden in a GtkTreeListRow. TRUE if the expander icon should be hidden. Otherwise FALSE. + line="1004">TRUE if the expander icon should be hidden. Otherwise FALSE. a `GtkTreeExpander` + line="1000">a `GtkTreeExpander` @@ -151530,23 +155119,21 @@ Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. c:identifier="gtk_tree_expander_get_indent_for_depth" glib:get-property="indent-for-depth" version="4.10"> - TreeExpander indents each level of depth with an additional indent. + line="912">TreeExpander indents each level of depth with an additional indent. TRUE if the child should be indented . Otherwise FALSE. + line="918">TRUE if the child should be indented . Otherwise FALSE. a `GtkTreeExpander` + line="914">a `GtkTreeExpander` @@ -151555,22 +155142,21 @@ Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. c:identifier="gtk_tree_expander_get_indent_for_icon" glib:get-property="indent-for-icon" version="4.6"> - TreeExpander indents the child by the width of an expander-icon if it is not expandable. + line="955">TreeExpander indents the child by the width of an expander-icon if it is not expandable. TRUE if the child should be indented when not expandable. Otherwise FALSE. + line="961">TRUE if the child should be indented when not expandable. Otherwise FALSE. a `GtkTreeExpander` + line="957">a `GtkTreeExpander` @@ -151578,10 +155164,9 @@ Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. - Forwards the item set on the `GtkTreeListRow` that @self is managing. + line="833">Forwards the item set on the `GtkTreeListRow` that @self is managing. This call is essentially equivalent to calling: @@ -151592,14 +155177,14 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); The item of the row + line="845">The item of the row a `GtkTreeExpander` + line="835">a `GtkTreeExpander` @@ -151607,22 +155192,21 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); - Gets the list row managed by @self. + line="858">Gets the list row managed by @self. The list row displayed by @self + line="864">The list row displayed by @self a `GtkTreeExpander` + line="860">a `GtkTreeExpander` @@ -151630,10 +155214,9 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); - Sets the content widget to display. + line="797">Sets the content widget to display. @@ -151642,7 +155225,7 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); a `GtkTreeExpander` + line="799">a `GtkTreeExpander` a `GtkWidget` + line="800">a `GtkWidget` @@ -151660,10 +155243,9 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); c:identifier="gtk_tree_expander_set_hide_expander" glib:set-property="hide-expander" version="4.10"> - Sets whether the expander icon should be visible in a GtkTreeListRow. + line="1016">Sets whether the expander icon should be visible in a GtkTreeListRow. @@ -151672,13 +155254,13 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); a `GtkTreeExpander` widget + line="1018">a `GtkTreeExpander` widget TRUE if the expander should be hidden. Otherwise FALSE. + line="1019">TRUE if the expander should be hidden. Otherwise FALSE. @@ -151687,11 +155269,9 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); c:identifier="gtk_tree_expander_set_indent_for_depth" glib:set-property="indent-for-depth" version="4.10"> - Sets if the TreeExpander should indent the child according to its depth. + line="930">Sets if the TreeExpander should indent the child according to its depth. @@ -151700,13 +155280,13 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); a `GtkTreeExpander` widget + line="932">a `GtkTreeExpander` widget TRUE if the child should be indented. Otherwise FALSE. + line="933">TRUE if the child should be indented. Otherwise FALSE. @@ -151715,10 +155295,9 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); c:identifier="gtk_tree_expander_set_indent_for_icon" glib:set-property="indent-for-icon" version="4.6"> - Sets if the TreeExpander should indent the child by the width of an expander-icon when it is not expandable. + line="973">Sets if the TreeExpander should indent the child by the width of an expander-icon when it is not expandable. @@ -151727,13 +155306,13 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); a `GtkTreeExpander` widget + line="975">a `GtkTreeExpander` widget TRUE if the child should be indented without expander. Otherwise FALSE. + line="976">TRUE if the child should be indented without expander. Otherwise FALSE. @@ -151741,10 +155320,9 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); - Sets the tree list row that this expander should manage. + line="874">Sets the tree list row that this expander should manage. @@ -151753,7 +155331,7 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); a `GtkTreeExpander` widget + line="876">a `GtkTreeExpander` widget a `GtkTreeListRow` + line="877">a `GtkTreeListRow` @@ -151772,13 +155350,9 @@ gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget with the actual contents. + line="555">The child widget with the actual contents. - - Whether the expander icon should be hidden in a GtkTreeListRow. + line="565">Whether the expander icon should be hidden in a GtkTreeListRow. Note that this property simply hides the icon. The actions and keybinding (i.e. collapse and expand) are not affected by this property. @@ -151809,13 +155379,9 @@ GtkTreeListRow's model in order to hide the expander when a row has no children. setter="set_indent_for_depth" getter="get_indent_for_depth" default-value="TRUE"> - - TreeExpander indents the child according to its depth. + line="582">TreeExpander indents the child according to its depth. - - TreeExpander indents the child by the width of an expander-icon if it is not expandable. + line="594">TreeExpander indents the child by the width of an expander-icon if it is not expandable. - The item held by this expander's row. + line="606">The item held by this expander's row. - - The list row to track for expander state. + line="616">The list row to track for expander state. @@ -151867,39 +155423,41 @@ GtkTreeListRow's model in order to hide the expander when a row has no children. The `GtkTreeIter` is the primary structure + line="81">The `GtkTreeIter` is the primary structure for accessing a `GtkTreeModel`. Models are expected to put a unique integer in the @stamp member, and put model-specific data in the three @user_data members. - + a unique stamp to catch invalid iterators + line="83">a unique stamp to catch invalid iterators model-specific data + line="84">model-specific data model-specific data + line="85">model-specific data model-specific data + line="86">model-specific data deprecated-version="4.10"> Creates a dynamically allocated tree iterator as a copy of @iter. + line="1178">Creates a dynamically allocated tree iterator as a copy of @iter. This function is not intended for use in applications, because you can just copy the structs by value (`GtkTreeIter new_iter = iter;`). You must free this iter with gtk_tree_iter_free(). - + a newly-allocated copy of @iter + line="1189">a newly-allocated copy of @iter a `GtkTreeIter` + line="1180">a `GtkTreeIter` @@ -151936,10 +155494,10 @@ You must free this iter with gtk_tree_iter_free(). deprecated-version="4.10"> Frees an iterator that has been allocated by gtk_tree_iter_copy(). + line="1206">Frees an iterator that has been allocated by gtk_tree_iter_copy(). This function is mainly used for language bindings. - + @@ -151947,7 +155505,7 @@ This function is mainly used for language bindings. a dynamically allocated tree iterator + line="1208">a dynamically allocated tree iterator @@ -152017,7 +155575,7 @@ for the “price” column could be one which returns glib:type-struct="TreeListModelClass"> `GtkTreeListModel` is a list model that can create child models on demand. + line="27">A list model that can create child models on demand. @@ -152058,8 +155616,8 @@ with all rows collapsed. destroy="5"> Function to call to create the `GListModel` for the children - of an item + line="738">function to + call to create the `GListModel` for the children of an item @@ -152085,7 +155643,6 @@ with all rows collapsed. - Gets whether the model is set to automatically expand new rows @@ -152145,7 +155702,6 @@ Do not confuse this function with [method@Gtk.TreeListModel.get_row]. - Gets the root model that @self was created with. @@ -152168,7 +155724,6 @@ Do not confuse this function with [method@Gtk.TreeListModel.get_row]. - Gets whether the model is passing through original row items. @@ -152242,7 +155797,6 @@ Do not confuse this function with [method@Gtk.TreeListModel.get_child_row]. - Sets whether the model should autoexpand. @@ -152275,10 +155829,6 @@ to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. setter="set_autoexpand" getter="get_autoexpand" default-value="FALSE"> - - If all rows should be expanded by default. @@ -152291,8 +155841,6 @@ to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. - The root model displayed. @@ -152313,8 +155861,6 @@ to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. transfer-ownership="none" getter="get_passthrough" default-value="FALSE"> - Gets whether the model is in passthrough mode. @@ -152380,7 +155926,7 @@ children arrive. glib:type-struct="TreeListRowClass"> `GtkTreeListRow` is used by `GtkTreeListModel` to represent items. + line="931">The type of item used by `GtkTreeListModel`. It allows navigating the model as a tree and modify the state of rows. @@ -152423,7 +155969,6 @@ number of children, %NULL is returned. - If the row is expanded, gets the model holding the children of @self. @@ -152451,7 +155996,6 @@ and contains the original items, no matter what value - Gets the depth of this row. @@ -152481,7 +156025,6 @@ at which point it will forever return 0. - Gets if a row is currently expanded. @@ -152504,7 +156047,6 @@ at which point it will forever return 0. - Gets the item corresponding to this row, @@ -152579,8 +156121,8 @@ at the moment. - + c:identifier="gtk_tree_list_row_is_expandable" + glib:get-property="expandable"> Checks if a row can be expanded. @@ -152609,7 +156151,6 @@ from its model at which point it will forever return %FALSE. - Expands or collapses a row. @@ -152642,8 +156183,6 @@ If the row is not expandable, this function does nothing. - The model holding the row's children. @@ -152653,8 +156192,6 @@ If the row is not expandable, this function does nothing. transfer-ownership="none" getter="get_depth" default-value="0"> - The depth in the tree of this row. @@ -152662,9 +156199,8 @@ If the row is not expandable, this function does nothing. - If this row can ever be expanded. @@ -152676,18 +156212,12 @@ If the row is not expandable, this function does nothing. setter="set_expanded" getter="get_expanded" default-value="FALSE"> - - If this row is currently expanded. - The item held in this row. @@ -152711,8 +156241,7 @@ If the row is not expandable, this function does nothing. glib:type-struct="TreeListRowSorterClass"> `GtkTreeListRowSorter` is a special-purpose sorter that will apply a given -sorter to the levels in a tree. + line="29">Applies a gives sorter to the levels in a tree. Here is an example for setting up a column view with a tree model and a `GtkTreeListSorter`: @@ -152728,7 +156257,7 @@ gtk_column_view_set_model (view, G_LIST_MODEL (selection)); Create a special-purpose sorter that applies the sorting + line="556">Create a special-purpose sorter that applies the sorting of @sorter to the levels of a `GtkTreeListModel`. Note that this sorter relies on [property@Gtk.TreeListModel:passthrough] @@ -152737,7 +156266,7 @@ being %FALSE as it can only sort [class@Gtk.TreeListRow]s. a new `GtkTreeListRowSorter` + line="566">a new `GtkTreeListRowSorter` @@ -152747,7 +156276,7 @@ being %FALSE as it can only sort [class@Gtk.TreeListRow]s. allow-none="1"> a `GtkSorter` + line="558">a `GtkSorter` @@ -152757,19 +156286,19 @@ being %FALSE as it can only sort [class@Gtk.TreeListRow]s. glib:get-property="sorter"> Returns the sorter used by @self. + line="617">Returns the sorter used by @self. the sorter used + line="623">the sorter used a `GtkTreeListRowSorter` + line="619">a `GtkTreeListRowSorter` @@ -152779,7 +156308,7 @@ being %FALSE as it can only sort [class@Gtk.TreeListRow]s. glib:set-property="sorter"> Sets the sorter to use for items with the same parent. + line="584">Sets the sorter to use for items with the same parent. This sorter will be passed the [property@Gtk.TreeListRow:item] of the tree list rows passed to @self. @@ -152791,7 +156320,7 @@ the tree list rows passed to @self. a `GtkTreeListRowSorter` + line="586">a `GtkTreeListRowSorter` allow-none="1"> The sorter to use + line="587">The sorter to use @@ -152812,7 +156341,7 @@ the tree list rows passed to @self. getter="get_sorter"> The underlying sorter + line="535">The underlying sorter @@ -153031,32 +156560,32 @@ into account: however, signals must be emitted at all times (however the root level is always referenced when any view is attached). Use [iface@Gio.ListModel] instead - + Returns the type of the column. - + line="1278">Returns the type of the column. + the type of the column + line="1285">the type of the column a `GtkTreeModel` + line="1280">a `GtkTreeModel` the column index + line="1281">the column index @@ -153067,23 +156596,23 @@ into account: deprecated-version="4.10"> Returns a set of flags supported by this interface. + line="1228">Returns a set of flags supported by this interface. The flags are a bitwise combination of `GtkTreeModel`Flags. The flags supported should not change during the lifetime of the @tree_model. - + the flags supported by this interface + line="1238">the flags supported by this interface a `GtkTreeModel` + line="1230">a `GtkTreeModel` @@ -153094,22 +156623,22 @@ of the @tree_model. deprecated-version="4.10"> Sets @iter to a valid iterator pointing to @path. + line="1304">Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. - + %TRUE, if @iter was set + line="1315">%TRUE, if @iter was set a `GtkTreeModel` + line="1306">a `GtkTreeModel` transfer-ownership="none"> the uninitialized `GtkTreeIter` + line="1307">the uninitialized `GtkTreeIter` the `GtkTreePath` + line="1308">the `GtkTreePath` @@ -153135,19 +156664,19 @@ iterator and %FALSE is returned. deprecated-version="4.10"> Returns the number of columns supported by @tree_model. - + line="1256">Returns the number of columns supported by @tree_model. + the number of columns + line="1262">the number of columns a `GtkTreeModel` + line="1258">a `GtkTreeModel` @@ -153158,27 +156687,27 @@ iterator and %FALSE is returned. deprecated-version="4.10"> Returns a newly-created `GtkTreePath` referenced by @iter. + line="1442">Returns a newly-created `GtkTreePath` referenced by @iter. This path should be freed with gtk_tree_path_free(). - + a newly-created `GtkTreePath` + line="1451">a newly-created `GtkTreePath` a `GtkTreeModel` + line="1444">a `GtkTreeModel` the `GtkTreeIter` + line="1445">the `GtkTreeIter` @@ -153189,11 +156718,11 @@ This path should be freed with gtk_tree_path_free(). deprecated-version="4.10"> Initializes and sets @value to that at @column. + line="1470">Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. - + @@ -153201,19 +156730,19 @@ to free any allocated memory. a `GtkTreeModel` + line="1472">a `GtkTreeModel` the `GtkTreeIter` + line="1473">the `GtkTreeIter` the column to lookup the value at + line="1474">the column to lookup the value at transfer-ownership="none"> an empty `GValue` to set + line="1475">an empty `GValue` to set @@ -153233,7 +156762,7 @@ to free any allocated memory. deprecated-version="4.10"> Sets @iter to point to the first child of @parent. + line="1586">Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this @@ -153241,18 +156770,18 @@ function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` - + %TRUE, if @iter has been set to the first child + line="1601">%TRUE, if @iter has been set to the first child a `GtkTreeModel` + line="1588">a `GtkTreeModel` the new `GtkTreeIter` to be set to the child + line="1589">the new `GtkTreeIter` to be set to the child the `GtkTreeIter` + line="1590">the `GtkTreeIter` @@ -153281,25 +156810,25 @@ If @parent is %NULL returns the first node, equivalent to deprecated-version="4.10"> Returns %TRUE if @iter has children, %FALSE otherwise. - + line="1623">Returns %TRUE if @iter has children, %FALSE otherwise. + %TRUE if @iter has children + line="1630">%TRUE if @iter has children a `GtkTreeModel` + line="1625">a `GtkTreeModel` the `GtkTreeIter` to test for children + line="1626">the `GtkTreeIter` to test for children @@ -153310,22 +156839,22 @@ If @parent is %NULL returns the first node, equivalent to deprecated-version="4.10"> Returns the number of children that @iter has. + line="1649">Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. - + the number of children of @iter + line="1659">the number of children of @iter a `GtkTreeModel` + line="1651">a `GtkTreeModel` allow-none="1"> the `GtkTreeIter` + line="1652">the `GtkTreeIter` @@ -153345,28 +156874,28 @@ of toplevel nodes is returned. deprecated-version="4.10"> Sets @iter to point to the node following it at the current level. + line="1502">Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. - + %TRUE if @iter has been changed to the next node + line="1512">%TRUE if @iter has been changed to the next node a `GtkTreeModel` + line="1504">a `GtkTreeModel` the `GtkTreeIter` + line="1505">the `GtkTreeIter` @@ -153377,25 +156906,25 @@ to be invalid. deprecated-version="4.10"> Sets @iter to be the child of @parent, using the given index. + line="1677">Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. - + %TRUE, if @parent has an @n-th child + line="1692">%TRUE, if @parent has an @n-th child a `GtkTreeModel` + line="1679">a `GtkTreeModel` transfer-ownership="none"> the `GtkTreeIter` to set to the nth child + line="1680">the `GtkTreeIter` to set to the nth child allow-none="1"> the `GtkTreeIter` to get the child from + line="1681">the `GtkTreeIter` to get the child from the index of the desired child + line="1682">the index of the desired child @@ -153430,7 +156959,7 @@ is set. deprecated-version="4.10"> Sets @iter to be the parent of @child. + line="1716">Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @@ -153439,18 +156968,18 @@ called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. - + %TRUE, if @iter is set to the parent of @child + line="1732">%TRUE, if @iter is set to the parent of @child a `GtkTreeModel` + line="1718">a `GtkTreeModel` transfer-ownership="none"> the new `GtkTreeIter` to set to the parent + line="1719">the new `GtkTreeIter` to set to the parent the `GtkTreeIter` + line="1720">the `GtkTreeIter` @@ -153476,28 +157005,28 @@ and @iter cannot point to the same memory location. deprecated-version="4.10"> Sets @iter to point to the previous node at the current level. + line="1552">Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. - + %TRUE if @iter has been changed to the previous node + line="1562">%TRUE if @iter has been changed to the previous node a `GtkTreeModel` + line="1554">a `GtkTreeModel` the `GtkTreeIter` + line="1555">the `GtkTreeIter` @@ -153508,7 +157037,7 @@ set to be invalid. deprecated-version="4.10"> Lets the tree ref the node. + line="1755">Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists @@ -153525,7 +157054,7 @@ every current view. A model should be expected to be able to get an iter independent of its reffed state. - + @@ -153533,13 +157062,13 @@ of its reffed state. a `GtkTreeModel` + line="1757">a `GtkTreeModel` the `GtkTreeIter` + line="1758">the `GtkTreeIter` @@ -153550,10 +157079,10 @@ of its reffed state. deprecated-version="4.10"> Emits the ::row-changed signal on @tree_model. + line="1917">Emits the ::row-changed signal on @tree_model. See [signal@Gtk.TreeModel::row-changed]. - + @@ -153561,19 +157090,19 @@ See [signal@Gtk.TreeModel::row-changed]. a `GtkTreeModel` + line="1919">a `GtkTreeModel` a `GtkTreePath` pointing to the changed row + line="1920">a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row + line="1921">a valid `GtkTreeIter` pointing to the changed row @@ -153584,7 +157113,7 @@ See [signal@Gtk.TreeModel::row-changed]. deprecated-version="4.10"> Emits the ::row-deleted signal on @tree_model. + line="1992">Emits the ::row-deleted signal on @tree_model. See [signal@Gtk.TreeModel::row-deleted]. @@ -153594,7 +157123,7 @@ the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. - + @@ -153602,13 +157131,13 @@ outstanding references on the deleted node should not be released. a `GtkTreeModel` + line="1994">a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of + line="1995">a `GtkTreePath` pointing to the previous location of the deleted row @@ -153620,13 +157149,13 @@ outstanding references on the deleted node should not be released. deprecated-version="4.10"> Emits the ::row-has-child-toggled signal on @tree_model. + line="1965">Emits the ::row-has-child-toggled signal on @tree_model. See [signal@Gtk.TreeModel::row-has-child-toggled]. This should be called by models after the child state of a node changes. - + @@ -153634,19 +157163,19 @@ state of a node changes. a `GtkTreeModel` + line="1967">a `GtkTreeModel` a `GtkTreePath` pointing to the changed row + line="1968">a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row + line="1969">a valid `GtkTreeIter` pointing to the changed row @@ -153657,10 +157186,10 @@ state of a node changes. deprecated-version="4.10"> Emits the ::row-inserted signal on @tree_model. + line="1941">Emits the ::row-inserted signal on @tree_model. See [signal@Gtk.TreeModel::row-inserted]. - + @@ -153668,19 +157197,19 @@ See [signal@Gtk.TreeModel::row-inserted]. a `GtkTreeModel` + line="1943">a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row + line="1944">a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row + line="1945">a valid `GtkTreeIter` pointing to the inserted row @@ -153692,13 +157221,13 @@ See [signal@Gtk.TreeModel::row-inserted]. deprecated-version="4.10"> Emits the ::rows-reordered signal on @tree_model. + line="2021">Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. - + @@ -153706,27 +157235,27 @@ reordered. a `GtkTreeModel` + line="2023">a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children + line="2024">a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children + line="2026">a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of + line="2028">an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` @@ -153739,7 +157268,7 @@ reordered. deprecated-version="4.10"> Lets the tree unref the node. + line="1793">Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists @@ -153747,7 +157276,7 @@ primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. - + @@ -153755,13 +157284,13 @@ Please note that nodes that are deleted are not unreffed. a `GtkTreeModel` + line="1795">a `GtkTreeModel` the `GtkTreeIter` + line="1796">the `GtkTreeIter` @@ -153772,21 +157301,21 @@ Please note that nodes that are deleted are not unreffed. deprecated-version="4.10"> Creates a new `GtkTreeModel`, with @child_model as the child_model + line="3764">Creates a new `GtkTreeModel`, with @child_model as the child_model and @root as the virtual root. A new `GtkTreeModel`. + line="3772">A new `GtkTreeModel`. A `GtkTreeModel`. + line="3766">A `GtkTreeModel`. allow-none="1"> A `GtkTreePath` + line="3767">A `GtkTreePath` @@ -153806,11 +157335,11 @@ and @root as the virtual root. deprecated-version="4.10"> Calls @func on each node in model in a depth-first fashion. + line="2129">Calls @func on each node in model in a depth-first fashion. If @func returns %TRUE, then the tree ceases to be walked, and gtk_tree_model_foreach() returns. - + @@ -153818,7 +157347,7 @@ and gtk_tree_model_foreach() returns. a `GtkTreeModel` + line="2131">a `GtkTreeModel` closure="1"> a function to be called on each row + line="2132">a function to be called on each row @@ -153837,7 +157366,7 @@ and gtk_tree_model_foreach() returns. allow-none="1"> user data to passed to @func + line="2133">user data to passed to @func @@ -153849,7 +157378,7 @@ and gtk_tree_model_foreach() returns. deprecated-version="4.10"> Gets the value of one or more cells in the row referenced by @iter. + line="1823">Gets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by a place to store the value being @@ -153862,7 +157391,7 @@ to be filled with the string. Returned values with type %G_TYPE_OBJECT have to be unreferenced, values with type %G_TYPE_STRING or %G_TYPE_BOXED have to be freed. Other values are passed by value. - + @@ -153870,19 +157399,19 @@ Other values are passed by value. a `GtkTreeModel` + line="1825">a `GtkTreeModel` a row in @tree_model + line="1826">a row in @tree_model pairs of column number and value return locations, + line="1827">pairs of column number and value return locations, terminated by -1 @@ -153894,25 +157423,25 @@ Other values are passed by value. deprecated-version="4.10"> Returns the type of the column. - + line="1278">Returns the type of the column. + the type of the column + line="1285">the type of the column a `GtkTreeModel` + line="1280">a `GtkTreeModel` the column index + line="1281">the column index @@ -153923,23 +157452,23 @@ Other values are passed by value. deprecated-version="4.10"> Returns a set of flags supported by this interface. + line="1228">Returns a set of flags supported by this interface. The flags are a bitwise combination of `GtkTreeModel`Flags. The flags supported should not change during the lifetime of the @tree_model. - + the flags supported by this interface + line="1238">the flags supported by this interface a `GtkTreeModel` + line="1230">a `GtkTreeModel` @@ -153950,22 +157479,22 @@ of the @tree_model. deprecated-version="4.10"> Sets @iter to a valid iterator pointing to @path. + line="1304">Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. - + %TRUE, if @iter was set + line="1315">%TRUE, if @iter was set a `GtkTreeModel` + line="1306">a `GtkTreeModel` transfer-ownership="none"> the uninitialized `GtkTreeIter` + line="1307">the uninitialized `GtkTreeIter` the `GtkTreePath` + line="1308">the `GtkTreePath` @@ -153991,22 +157520,22 @@ iterator and %FALSE is returned. deprecated-version="4.10"> Initializes @iter with the first iterator in the tree + line="1411">Initializes @iter with the first iterator in the tree (the one at the path "0"). Returns %FALSE if the tree is empty, %TRUE otherwise. - + %TRUE, if @iter was set + line="1421">%TRUE, if @iter was set a `GtkTreeModel` + line="1413">a `GtkTreeModel` transfer-ownership="none"> the uninitialized `GtkTreeIter` + line="1414">the uninitialized `GtkTreeIter` @@ -154026,22 +157555,22 @@ Returns %FALSE if the tree is empty, %TRUE otherwise. deprecated-version="4.10"> Sets @iter to a valid iterator pointing to @path_string, if it + line="1339">Sets @iter to a valid iterator pointing to @path_string, if it exists. Otherwise, @iter is left invalid and %FALSE is returned. - + %TRUE, if @iter was set + line="1350">%TRUE, if @iter was set a `GtkTreeModel` + line="1341">a `GtkTreeModel` transfer-ownership="none"> an uninitialized `GtkTreeIter` + line="1342">an uninitialized `GtkTreeIter` a string representation of a `GtkTreePath` + line="1343">a string representation of a `GtkTreePath` @@ -154067,19 +157596,19 @@ Otherwise, @iter is left invalid and %FALSE is returned. deprecated-version="4.10"> Returns the number of columns supported by @tree_model. - + line="1256">Returns the number of columns supported by @tree_model. + the number of columns + line="1262">the number of columns a `GtkTreeModel` + line="1258">a `GtkTreeModel` @@ -154090,27 +157619,27 @@ Otherwise, @iter is left invalid and %FALSE is returned. deprecated-version="4.10"> Returns a newly-created `GtkTreePath` referenced by @iter. + line="1442">Returns a newly-created `GtkTreePath` referenced by @iter. This path should be freed with gtk_tree_path_free(). - + a newly-created `GtkTreePath` + line="1451">a newly-created `GtkTreePath` a `GtkTreeModel` + line="1444">a `GtkTreeModel` the `GtkTreeIter` + line="1445">the `GtkTreeIter` @@ -154121,29 +157650,29 @@ This path should be freed with gtk_tree_path_free(). deprecated-version="4.10"> Generates a string representation of the iter. + line="1376">Generates a string representation of the iter. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. - + a newly-allocated string + line="1387">a newly-allocated string a `GtkTreeModel` + line="1378">a `GtkTreeModel` a `GtkTreeIter` + line="1379">a `GtkTreeIter` @@ -154155,11 +157684,11 @@ return value for this string. deprecated-version="4.10"> Gets the value of one or more cells in the row referenced by @iter. + line="1861">Gets the value of one or more cells in the row referenced by @iter. See [method@Gtk.TreeModel.get], this version takes a va_list for language bindings to use. - + @@ -154167,19 +157696,19 @@ for language bindings to use. a `GtkTreeModel` + line="1863">a `GtkTreeModel` a row in @tree_model + line="1864">a row in @tree_model va_list of column/return location pairs + line="1865">va_list of column/return location pairs @@ -154190,11 +157719,11 @@ for language bindings to use. deprecated-version="4.10"> Initializes and sets @value to that at @column. + line="1470">Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. - + @@ -154202,19 +157731,19 @@ to free any allocated memory. a `GtkTreeModel` + line="1472">a `GtkTreeModel` the `GtkTreeIter` + line="1473">the `GtkTreeIter` the column to lookup the value at + line="1474">the column to lookup the value at transfer-ownership="none"> an empty `GValue` to set + line="1475">an empty `GValue` to set @@ -154234,7 +157763,7 @@ to free any allocated memory. deprecated-version="4.10"> Sets @iter to point to the first child of @parent. + line="1586">Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this @@ -154242,18 +157771,18 @@ function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` - + %TRUE, if @iter has been set to the first child + line="1601">%TRUE, if @iter has been set to the first child a `GtkTreeModel` + line="1588">a `GtkTreeModel` the new `GtkTreeIter` to be set to the child + line="1589">the new `GtkTreeIter` to be set to the child the `GtkTreeIter` + line="1590">the `GtkTreeIter` @@ -154282,25 +157811,25 @@ If @parent is %NULL returns the first node, equivalent to deprecated-version="4.10"> Returns %TRUE if @iter has children, %FALSE otherwise. - + line="1623">Returns %TRUE if @iter has children, %FALSE otherwise. + %TRUE if @iter has children + line="1630">%TRUE if @iter has children a `GtkTreeModel` + line="1625">a `GtkTreeModel` the `GtkTreeIter` to test for children + line="1626">the `GtkTreeIter` to test for children @@ -154311,22 +157840,22 @@ If @parent is %NULL returns the first node, equivalent to deprecated-version="4.10"> Returns the number of children that @iter has. + line="1649">Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. - + the number of children of @iter + line="1659">the number of children of @iter a `GtkTreeModel` + line="1651">a `GtkTreeModel` allow-none="1"> the `GtkTreeIter` + line="1652">the `GtkTreeIter` @@ -154346,28 +157875,28 @@ of toplevel nodes is returned. deprecated-version="4.10"> Sets @iter to point to the node following it at the current level. + line="1502">Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. - + %TRUE if @iter has been changed to the next node + line="1512">%TRUE if @iter has been changed to the next node a `GtkTreeModel` + line="1504">a `GtkTreeModel` the `GtkTreeIter` + line="1505">the `GtkTreeIter` @@ -154378,25 +157907,25 @@ to be invalid. deprecated-version="4.10"> Sets @iter to be the child of @parent, using the given index. + line="1677">Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. - + %TRUE, if @parent has an @n-th child + line="1692">%TRUE, if @parent has an @n-th child a `GtkTreeModel` + line="1679">a `GtkTreeModel` transfer-ownership="none"> the `GtkTreeIter` to set to the nth child + line="1680">the `GtkTreeIter` to set to the nth child allow-none="1"> the `GtkTreeIter` to get the child from + line="1681">the `GtkTreeIter` to get the child from the index of the desired child + line="1682">the index of the desired child @@ -154431,7 +157960,7 @@ is set. deprecated-version="4.10"> Sets @iter to be the parent of @child. + line="1716">Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @@ -154440,18 +157969,18 @@ called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. - + %TRUE, if @iter is set to the parent of @child + line="1732">%TRUE, if @iter is set to the parent of @child a `GtkTreeModel` + line="1718">a `GtkTreeModel` transfer-ownership="none"> the new `GtkTreeIter` to set to the parent + line="1719">the new `GtkTreeIter` to set to the parent the `GtkTreeIter` + line="1720">the `GtkTreeIter` @@ -154477,28 +158006,28 @@ and @iter cannot point to the same memory location. deprecated-version="4.10"> Sets @iter to point to the previous node at the current level. + line="1552">Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. - + %TRUE if @iter has been changed to the previous node + line="1562">%TRUE if @iter has been changed to the previous node a `GtkTreeModel` + line="1554">a `GtkTreeModel` the `GtkTreeIter` + line="1555">the `GtkTreeIter` @@ -154509,7 +158038,7 @@ set to be invalid. deprecated-version="4.10"> Lets the tree ref the node. + line="1755">Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists @@ -154526,7 +158055,7 @@ every current view. A model should be expected to be able to get an iter independent of its reffed state. - + @@ -154534,13 +158063,13 @@ of its reffed state. a `GtkTreeModel` + line="1757">a `GtkTreeModel` the `GtkTreeIter` + line="1758">the `GtkTreeIter` @@ -154551,10 +158080,10 @@ of its reffed state. deprecated-version="4.10"> Emits the ::row-changed signal on @tree_model. + line="1917">Emits the ::row-changed signal on @tree_model. See [signal@Gtk.TreeModel::row-changed]. - + @@ -154562,19 +158091,19 @@ See [signal@Gtk.TreeModel::row-changed]. a `GtkTreeModel` + line="1919">a `GtkTreeModel` a `GtkTreePath` pointing to the changed row + line="1920">a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row + line="1921">a valid `GtkTreeIter` pointing to the changed row @@ -154585,7 +158114,7 @@ See [signal@Gtk.TreeModel::row-changed]. deprecated-version="4.10"> Emits the ::row-deleted signal on @tree_model. + line="1992">Emits the ::row-deleted signal on @tree_model. See [signal@Gtk.TreeModel::row-deleted]. @@ -154595,7 +158124,7 @@ the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. - + @@ -154603,13 +158132,13 @@ outstanding references on the deleted node should not be released. a `GtkTreeModel` + line="1994">a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of + line="1995">a `GtkTreePath` pointing to the previous location of the deleted row @@ -154621,13 +158150,13 @@ outstanding references on the deleted node should not be released. deprecated-version="4.10"> Emits the ::row-has-child-toggled signal on @tree_model. + line="1965">Emits the ::row-has-child-toggled signal on @tree_model. See [signal@Gtk.TreeModel::row-has-child-toggled]. This should be called by models after the child state of a node changes. - + @@ -154635,19 +158164,19 @@ state of a node changes. a `GtkTreeModel` + line="1967">a `GtkTreeModel` a `GtkTreePath` pointing to the changed row + line="1968">a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row + line="1969">a valid `GtkTreeIter` pointing to the changed row @@ -154658,10 +158187,10 @@ state of a node changes. deprecated-version="4.10"> Emits the ::row-inserted signal on @tree_model. + line="1941">Emits the ::row-inserted signal on @tree_model. See [signal@Gtk.TreeModel::row-inserted]. - + @@ -154669,19 +158198,19 @@ See [signal@Gtk.TreeModel::row-inserted]. a `GtkTreeModel` + line="1943">a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row + line="1944">a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row + line="1945">a valid `GtkTreeIter` pointing to the inserted row @@ -154694,13 +158223,13 @@ See [signal@Gtk.TreeModel::row-inserted]. deprecated-version="4.10"> Emits the ::rows-reordered signal on @tree_model. + line="2021">Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. - + @@ -154708,27 +158237,27 @@ reordered. a `GtkTreeModel` + line="2023">a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children + line="2024">a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children + line="2026">a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of + line="2028">an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` @@ -154742,13 +158271,13 @@ reordered. deprecated-version="4.10"> Emits the ::rows-reordered signal on @tree_model. + line="2053">Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. - + @@ -154756,13 +158285,13 @@ reordered. a `GtkTreeModel` + line="2055">a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children + line="2056">a `GtkTreePath` pointing to the tree node whose children have been reordered @@ -154772,7 +158301,7 @@ reordered. allow-none="1"> a valid `GtkTreeIter` pointing to the node + line="2058">a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 @@ -154780,7 +158309,7 @@ reordered. an array of integers + line="2061">an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` @@ -154791,7 +158320,7 @@ reordered. length of @new_order array + line="2065">length of @new_order array @@ -154802,7 +158331,7 @@ reordered. deprecated-version="4.10"> Lets the tree unref the node. + line="1793">Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists @@ -154810,7 +158339,7 @@ primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. - + @@ -154818,13 +158347,13 @@ Please note that nodes that are deleted are not unreffed. a `GtkTreeModel` + line="1795">a `GtkTreeModel` the `GtkTreeIter` + line="1796">the `GtkTreeIter` @@ -154832,7 +158361,7 @@ Please note that nodes that are deleted are not unreffed. This signal is emitted when a row in the model has changed. + line="358">This signal is emitted when a row in the model has changed. @@ -154840,13 +158369,13 @@ Please note that nodes that are deleted are not unreffed. a `GtkTreePath` identifying the changed row + line="361">a `GtkTreePath` identifying the changed row a valid `GtkTreeIter` pointing to the changed row + line="362">a valid `GtkTreeIter` pointing to the changed row @@ -154854,7 +158383,7 @@ Please note that nodes that are deleted are not unreffed. This signal is emitted when a row has been deleted. + line="444">This signal is emitted when a row has been deleted. Note that no iterator is passed to the signal handler, since the row is already deleted. @@ -154869,7 +158398,7 @@ the row previously was at. It may not be a valid location anymore. a `GtkTreePath` identifying the row + line="447">a `GtkTreePath` identifying the row @@ -154877,7 +158406,7 @@ the row previously was at. It may not be a valid location anymore. This signal is emitted when a row has gotten the first child + line="421">This signal is emitted when a row has gotten the first child row or lost its last child row. @@ -154886,13 +158415,13 @@ row or lost its last child row. a `GtkTreePath` identifying the row + line="424">a `GtkTreePath` identifying the row a valid `GtkTreeIter` pointing to the row + line="425">a valid `GtkTreeIter` pointing to the row @@ -154900,7 +158429,7 @@ row or lost its last child row. This signal is emitted when a new row has been inserted in + line="393">This signal is emitted when a new row has been inserted in the model. Note that the row may still be empty at this point, since @@ -154913,13 +158442,13 @@ then fill it with the desired values. a `GtkTreePath` identifying the new row + line="396">a `GtkTreePath` identifying the new row a valid `GtkTreeIter` pointing to the new row + line="397">a valid `GtkTreeIter` pointing to the new row @@ -154927,7 +158456,7 @@ then fill it with the desired values. This signal is emitted when the children of a node in the + line="470">This signal is emitted when the children of a node in the `GtkTreeModel` have been reordered. Note that this signal is not emitted @@ -154940,14 +158469,14 @@ by removing and then reinserting the row. a `GtkTreePath` identifying the tree node whose children + line="473">a `GtkTreePath` identifying the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children + line="475">a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 @@ -154957,7 +158486,7 @@ by removing and then reinserting the row. allow-none="1"> an array of integers mapping the current position + line="477">an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` @@ -155096,7 +158625,7 @@ yourself. deprecated-version="4.10"> This function should almost never be called. It clears the @filter + line="4277">This function should almost never be called. It clears the @filter of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being filtered is static (and doesn’t change often) and there has been @@ -155111,7 +158640,7 @@ all unreffed iters will be invalid. A `GtkTreeModelFilter` + line="4279">A `GtkTreeModelFilter` @@ -155122,7 +158651,7 @@ all unreffed iters will be invalid. deprecated-version="4.10"> Sets @filter_iter to point to the row in @filter that corresponds to the + line="3943">Sets @filter_iter to point to the row in @filter that corresponds to the row pointed at by @child_iter. If @filter_iter was not set, %FALSE is returned. %TRUE, if @filter_iter was set, i.e. if @child_iter is a + line="3953">%TRUE, if @filter_iter was set, i.e. if @child_iter is a valid iterator pointing to a visible row in child model. @@ -155138,7 +158667,7 @@ valid iterator pointing to a visible row in child model. A `GtkTreeModelFilter` + line="3945">A `GtkTreeModelFilter` transfer-ownership="none"> An uninitialized `GtkTreeIter` + line="3946">An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on the child model. + line="3947">A valid `GtkTreeIter` pointing to a row on the child model. @@ -155164,7 +158693,7 @@ valid iterator pointing to a visible row in child model. deprecated-version="4.10"> Converts @child_path to a path relative to @filter. That is, @child_path + line="4124">Converts @child_path to a path relative to @filter. That is, @child_path points to a path in the child model. The rerturned path will point to the same row in the filtered model. If @child_path isn’t a valid path on the child model or points to a row which is not visible in @filter, then %NULL @@ -155174,20 +158703,20 @@ is returned. A newly allocated `GtkTreePath` + line="4135">A newly allocated `GtkTreePath` A `GtkTreeModelFilter` + line="4126">A `GtkTreeModelFilter` A `GtkTreePath` to convert. + line="4127">A `GtkTreePath` to convert. @@ -155198,7 +158727,7 @@ is returned. deprecated-version="4.10"> Sets @child_iter to point to the row pointed to by @filter_iter. + line="3990">Sets @child_iter to point to the row pointed to by @filter_iter. @@ -155208,7 +158737,7 @@ is returned. A `GtkTreeModelFilter` + line="3992">A `GtkTreeModelFilter` transfer-ownership="none"> An uninitialized `GtkTreeIter` + line="3993">An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on @filter. + line="3994">A valid `GtkTreeIter` pointing to a row on @filter. @@ -155234,7 +158763,7 @@ is returned. deprecated-version="4.10"> Converts @filter_path to a path on the child model of @filter. That is, + line="4168">Converts @filter_path to a path on the child model of @filter. That is, @filter_path points to a location in @filter. The returned path will point to the same location in the model not being filtered. If @filter_path does not point to a location in the child model, %NULL is returned. @@ -155243,20 +158772,20 @@ does not point to a location in the child model, %NULL is returned. A newly allocated `GtkTreePath` + line="4178">A newly allocated `GtkTreePath` A `GtkTreeModelFilter` + line="4170">A `GtkTreeModelFilter` A `GtkTreePath` to convert. + line="4171">A `GtkTreePath` to convert. @@ -155267,20 +158796,20 @@ does not point to a location in the child model, %NULL is returned. deprecated-version="4.10"> Returns a pointer to the child model of @filter. + line="3788">Returns a pointer to the child model of @filter. A pointer to a `GtkTreeModel` + line="3794">A pointer to a `GtkTreeModel` A `GtkTreeModelFilter` + line="3790">A `GtkTreeModelFilter` @@ -155291,7 +158820,7 @@ does not point to a location in the child model, %NULL is returned. deprecated-version="4.10"> Emits ::row_changed for each row in the child model, which causes + line="4257">Emits ::row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is visible or not. @@ -155302,7 +158831,7 @@ the filter to re-evaluate whether a row is visible or not. A `GtkTreeModelFilter` + line="4259">A `GtkTreeModelFilter` @@ -155313,7 +158842,7 @@ the filter to re-evaluate whether a row is visible or not. deprecated-version="4.10"> With the @n_columns and @types parameters, you give an array of column + line="3868">With the @n_columns and @types parameters, you give an array of column types for this model (which will be exposed to the parent model/view). The @func, @data and @destroy parameters are for specifying the modify function. The modify function will get called for each @@ -155332,19 +158861,19 @@ can only be called once for a given filter model. A `GtkTreeModelFilter` + line="3870">A `GtkTreeModelFilter` The number of columns in the filter model. + line="3871">The number of columns in the filter model. The `GType`s of the columns. + line="3872">The `GType`s of the columns. @@ -155356,7 +158885,7 @@ can only be called once for a given filter model. destroy="4"> A `GtkTreeModelFilterModifyFunc` + line="3873">A `GtkTreeModelFilterModifyFunc` @@ -155366,7 +158895,7 @@ can only be called once for a given filter model. allow-none="1"> User data to pass to the modify function + line="3874">User data to pass to the modify function scope="async"> Destroy notifier of @data + line="3875">Destroy notifier of @data @@ -155387,7 +158916,7 @@ can only be called once for a given filter model. deprecated-version="4.10"> Sets @column of the child_model to be the column where @filter should + line="3912">Sets @column of the child_model to be the column where @filter should look for visibility information. @columns should be a column of type %G_TYPE_BOOLEAN, where %TRUE means that a row is visible, and %FALSE if not. @@ -155404,13 +158933,13 @@ once for a given filter model. A `GtkTreeModelFilter` + line="3914">A `GtkTreeModelFilter` A `int` which is the column containing the visible information + line="3915">A `int` which is the column containing the visible information @@ -155421,7 +158950,7 @@ once for a given filter model. deprecated-version="4.10"> Sets the visible function used when filtering the @filter to be @func. + line="3806">Sets the visible function used when filtering the @filter to be @func. The function should return %TRUE if the given row should be visible and %FALSE otherwise. @@ -155465,7 +158994,7 @@ once for a given filter model. A `GtkTreeModelFilter` + line="3808">A `GtkTreeModelFilter` destroy="2"> A `GtkTreeModelFilterVisibleFunc`, the visible function + line="3809">A `GtkTreeModelFilterVisibleFunc`, the visible function @@ -155485,7 +159014,7 @@ once for a given filter model. allow-none="1"> User data to pass to the visible function + line="3810">User data to pass to the visible function scope="async"> Destroy notifier of @data + line="3811">Destroy notifier of @data @@ -155504,12 +159033,18 @@ once for a given filter model. writable="1" construct-only="1" transfer-ownership="none"> + The child model of the tree model filter. + The virtual root of the tree model filter. @@ -155683,6 +159218,8 @@ particularly efficient operation. @@ -155761,14 +159298,17 @@ iterate over the rows in a tree model. - + + Signal emitted when a row in the model has changed. + line="141"/> @@ -155776,28 +159316,32 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1919">a `GtkTreeModel` a `GtkTreePath` pointing to the changed row + line="1920">a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row + line="1921">a valid `GtkTreeIter` pointing to the changed row + Signal emitted when a new row has been inserted in + the model. + line="144"/> @@ -155805,28 +159349,32 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1943">a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row + line="1944">a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row + line="1945">a valid `GtkTreeIter` pointing to the inserted row + Signal emitted when a row has gotten the + first child row or lost its last child row. + line="147"/> @@ -155834,28 +159382,31 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1967">a `GtkTreeModel` a `GtkTreePath` pointing to the changed row + line="1968">a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row + line="1969">a valid `GtkTreeIter` pointing to the changed row + Signal emitted when a row has been deleted. + line="150"/> @@ -155863,13 +159414,13 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1994">a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of + line="1995">a `GtkTreePath` pointing to the previous location of the deleted row @@ -155877,9 +159428,13 @@ iterate over the rows in a tree model. + Signal emitted when the children of a node in the + GtkTreeModel have been reordered. + line="152"/> @@ -155887,27 +159442,27 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="2023">a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children + line="2024">a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children + line="2026">a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of + line="2028">an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` @@ -155916,86 +159471,98 @@ iterate over the rows in a tree model. + Get `GtkTreeModelFlags` supported by this interface. + line="158"/> the flags supported by this interface + line="1238">the flags supported by this interface a `GtkTreeModel` + line="1230">a `GtkTreeModel` + Get the number of columns supported by the model. + line="160"/> the number of columns + line="1262">the number of columns a `GtkTreeModel` + line="1258">a `GtkTreeModel` + Get the type of the column. + line="161"/> the type of the column + line="1285">the type of the column a `GtkTreeModel` + line="1280">a `GtkTreeModel` the column index + line="1281">the column index + Sets iter to a valid iterator pointing to path. + line="163"/> %TRUE, if @iter was set + line="1315">%TRUE, if @iter was set a `GtkTreeModel` + line="1306">a `GtkTreeModel` transfer-ownership="none"> the uninitialized `GtkTreeIter` + line="1307">the uninitialized `GtkTreeIter` the `GtkTreePath` + line="1308">the `GtkTreePath` + Gets a newly-created `GtkTreePath` referenced by iter. + line="166"/> a newly-created `GtkTreePath` + line="1451">a newly-created `GtkTreePath` a `GtkTreeModel` + line="1444">a `GtkTreeModel` the `GtkTreeIter` + line="1445">the `GtkTreeIter` + Initializes and sets value to that at column. + line="168"/> @@ -156053,19 +159626,19 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1472">a `GtkTreeModel` the `GtkTreeIter` + line="1473">the `GtkTreeIter` the column to lookup the value at + line="1474">the column to lookup the value at transfer-ownership="none"> an empty `GValue` to set + line="1475">an empty `GValue` to set + Sets iter to point to the node following it at the + current level. + line="172"/> %TRUE if @iter has been changed to the next node + line="1512">%TRUE if @iter has been changed to the next node a `GtkTreeModel` + line="1504">a `GtkTreeModel` the `GtkTreeIter` + line="1505">the `GtkTreeIter` + Sets iter to point to the previous node at the + current level. + line="174"/> %TRUE if @iter has been changed to the previous node + line="1562">%TRUE if @iter has been changed to the previous node a `GtkTreeModel` + line="1554">a `GtkTreeModel` the `GtkTreeIter` + line="1555">the `GtkTreeIter` + Sets iter to point to the first child of parent. + line="176"/> %TRUE, if @iter has been set to the first child + line="1601">%TRUE, if @iter has been set to the first child a `GtkTreeModel` + line="1588">a `GtkTreeModel` transfer-ownership="none"> the new `GtkTreeIter` to be set to the child + line="1589">the new `GtkTreeIter` to be set to the child allow-none="1"> the `GtkTreeIter` + line="1590">the `GtkTreeIter` + %TRUE if iter has children, %FALSE otherwise. + line="179"/> %TRUE if @iter has children + line="1630">%TRUE if @iter has children a `GtkTreeModel` + line="1625">a `GtkTreeModel` the `GtkTreeIter` to test for children + line="1626">the `GtkTreeIter` to test for children + Gets the number of children that iter has. + line="181"/> the number of children of @iter + line="1659">the number of children of @iter a `GtkTreeModel` + line="1651">a `GtkTreeModel` allow-none="1"> the `GtkTreeIter` + line="1652">the `GtkTreeIter` + Sets iter to be the child of parent, using the + given index. + line="183"/> %TRUE, if @parent has an @n-th child + line="1692">%TRUE, if @parent has an @n-th child a `GtkTreeModel` + line="1679">a `GtkTreeModel` transfer-ownership="none"> the `GtkTreeIter` to set to the nth child + line="1680">the `GtkTreeIter` to set to the nth child allow-none="1"> the `GtkTreeIter` to get the child from + line="1681">the `GtkTreeIter` to get the child from the index of the desired child + line="1682">the index of the desired child + Sets iter to be the parent of child. + line="187"/> %TRUE, if @iter is set to the parent of @child + line="1732">%TRUE, if @iter is set to the parent of @child a `GtkTreeModel` + line="1718">a `GtkTreeModel` transfer-ownership="none"> the new `GtkTreeIter` to set to the parent + line="1719">the new `GtkTreeIter` to set to the parent the `GtkTreeIter` + line="1720">the `GtkTreeIter` + Lets the tree ref the node. + line="190"/> @@ -156315,22 +159915,25 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1757">a `GtkTreeModel` the `GtkTreeIter` + line="1758">the `GtkTreeIter` + Lets the tree unref the node. + line="192"/> @@ -156338,13 +159941,13 @@ iterate over the rows in a tree model. a `GtkTreeModel` + line="1795">a `GtkTreeModel` the `GtkTreeIter` + line="1796">the `GtkTreeIter` @@ -156467,20 +160070,20 @@ selection_changed (GtkTreeSelection *selection, gpointer data) c:identifier="gtk_tree_model_sort_new_with_model"> Creates a new `GtkTreeModelSort`, with @child_model as the child model. + line="533">Creates a new `GtkTreeModelSort`, with @child_model as the child model. A new `GtkTreeModelSort`. + line="539">A new `GtkTreeModelSort`. A `GtkTreeModel` + line="535">A `GtkTreeModel` @@ -156491,7 +160094,7 @@ selection_changed (GtkTreeSelection *selection, gpointer data) deprecated-version="4.10"> This function should almost never be called. It clears the @tree_model_sort + line="2732">This function should almost never be called. It clears the @tree_model_sort of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being sorted is static (and doesn’t change often) and there has been a lot of @@ -156506,7 +160109,7 @@ iters will be invalid. A `GtkTreeModelSort` + line="2734">A `GtkTreeModelSort` @@ -156517,7 +160120,7 @@ iters will be invalid. deprecated-version="4.10"> Sets @sort_iter to point to the row in @tree_model_sort that corresponds to + line="2306">Sets @sort_iter to point to the row in @tree_model_sort that corresponds to the row pointed at by @child_iter. If @sort_iter was not set, %FALSE is returned. Note: a boolean is only returned since 2.14. %TRUE, if @sort_iter was set, i.e. if @sort_iter is a + line="2316">%TRUE, if @sort_iter was set, i.e. if @sort_iter is a valid iterator pointer to a visible row in the child model. @@ -156533,7 +160136,7 @@ valid iterator pointer to a visible row in the child model. A `GtkTreeModelSort` + line="2308">A `GtkTreeModelSort` transfer-ownership="none"> An uninitialized `GtkTreeIter` + line="2309">An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on the child model + line="2310">A valid `GtkTreeIter` pointing to a row on the child model @@ -156559,7 +160162,7 @@ valid iterator pointer to a visible row in the child model. deprecated-version="4.10"> Converts @child_path to a path relative to @tree_model_sort. That is, + line="2281">Converts @child_path to a path relative to @tree_model_sort. That is, @child_path points to a path in the child model. The returned path will point to the same row in the sorted model. If @child_path isn’t a valid path on the child model, then %NULL is returned. @@ -156568,20 +160171,20 @@ path on the child model, then %NULL is returned. A newly allocated `GtkTreePath` + line="2291">A newly allocated `GtkTreePath` A `GtkTreeModelSort` + line="2283">A `GtkTreeModelSort` A `GtkTreePath` to convert + line="2284">A `GtkTreePath` to convert @@ -156592,7 +160195,7 @@ path on the child model, then %NULL is returned. deprecated-version="4.10"> Sets @child_iter to point to the row pointed to by @sorted_iter. + line="2429">Sets @child_iter to point to the row pointed to by @sorted_iter. @@ -156602,7 +160205,7 @@ path on the child model, then %NULL is returned. A `GtkTreeModelSort` + line="2431">A `GtkTreeModelSort` transfer-ownership="none"> An uninitialized `GtkTreeIter` + line="2432">An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on @tree_model_sort. + line="2433">A valid `GtkTreeIter` pointing to a row on @tree_model_sort. @@ -156628,7 +160231,7 @@ path on the child model, then %NULL is returned. deprecated-version="4.10"> Converts @sorted_path to a path on the child model of @tree_model_sort. + line="2357">Converts @sorted_path to a path on the child model of @tree_model_sort. That is, @sorted_path points to a location in @tree_model_sort. The returned path will point to the same location in the model not being sorted. If @sorted_path does not point to a location in the child model, @@ -156638,20 +160241,20 @@ sorted. If @sorted_path does not point to a location in the child model, A newly allocated `GtkTreePath` + line="2368">A newly allocated `GtkTreePath` A `GtkTreeModelSort` + line="2359">A `GtkTreeModelSort` A `GtkTreePath` to convert + line="2360">A `GtkTreePath` to convert @@ -156661,20 +160264,20 @@ sorted. If @sorted_path does not point to a location in the child model, glib:get-property="model"> Returns the model the `GtkTreeModelSort` is sorting. + line="2203">Returns the model the `GtkTreeModelSort` is sorting. the "child model" being sorted + line="2209">the "child model" being sorted a `GtkTreeModelSort` + line="2205">a `GtkTreeModelSort` @@ -156685,7 +160288,7 @@ sorted. If @sorted_path does not point to a location in the child model, deprecated-version="4.10"> > This function is slow. Only use it for debugging and/or testing + line="2778">> This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this `GtkTreeModelSort`. @@ -156694,20 +160297,20 @@ Checks if the given iter is a valid iter for this `GtkTreeModelSort`. %TRUE if the iter is valid, %FALSE if the iter is invalid. + line="2788">%TRUE if the iter is valid, %FALSE if the iter is invalid. A `GtkTreeModelSort`. + line="2780">A `GtkTreeModelSort`. A `GtkTreeIter` + line="2781">A `GtkTreeIter` @@ -156718,7 +160321,7 @@ Checks if the given iter is a valid iter for this `GtkTreeModelSort`. deprecated-version="4.10"> This resets the default sort function to be in the “unsorted” state. That + line="2697">This resets the default sort function to be in the “unsorted” state. That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the child model only if the `GtkTreeModelSort` is in “unsorted” state. @@ -156731,7 +160334,7 @@ is in “unsorted” state. A `GtkTreeModelSort` + line="2699">A `GtkTreeModelSort` @@ -156741,6 +160344,9 @@ is in “unsorted” state. construct-only="1" transfer-ownership="none" getter="get_model"> + The model of the tree model sort. @@ -156772,6 +160378,8 @@ is in “unsorted” state. @@ -156785,13 +160393,13 @@ is in “unsorted” state. deprecated-version="4.10"> Creates a new `GtkTreePath` + line="602">Creates a new `GtkTreePath` This refers to a row. - + A newly created `GtkTreePath`. + line="608">A newly created `GtkTreePath`. @@ -156801,14 +160409,14 @@ This refers to a row. deprecated-version="4.10"> Creates a new `GtkTreePath`. + line="785">Creates a new `GtkTreePath`. The string representation of this path is “0”. - + A new `GtkTreePath` + line="792">A new `GtkTreePath` @@ -156820,25 +160428,25 @@ The string representation of this path is “0”. deprecated-version="4.10"> Creates a new path with @first_index and @varargs as indices. - + line="679">Creates a new path with @first_index and @varargs as indices. + A newly created `GtkTreePath` + line="686">A newly created `GtkTreePath` first integer + line="681">first integer list of integers terminated by -1 + line="682">list of integers terminated by -1 @@ -156850,19 +160458,19 @@ The string representation of this path is “0”. deprecated-version="4.10"> Creates a new path with the given @indices array of @length. - + line="714">Creates a new path with the given @indices array of @length. + A newly created `GtkTreePath` + line="721">A newly created `GtkTreePath` array of indices + line="716">array of indices @@ -156870,7 +160478,7 @@ The string representation of this path is “0”. length of @indices array + line="717">length of @indices array @@ -156881,25 +160489,25 @@ The string representation of this path is “0”. deprecated-version="4.10"> Creates a new `GtkTreePath` initialized to @path. + line="624">Creates a new `GtkTreePath` initialized to @path. @path is expected to be a colon separated list of numbers. For example, the string “10:4:0” would create a path of depth 3 pointing to the 11th child of the root node, the 5th child of that 11th child, and the 1st child of that 5th child. If an invalid path string is passed in, %NULL is returned. - + A newly-created `GtkTreePath` + line="636">A newly-created `GtkTreePath` The string representation of a path + line="626">The string representation of a path @@ -156910,10 +160518,10 @@ If an invalid path string is passed in, %NULL is returned. deprecated-version="4.10"> Appends a new index to a path. + line="807">Appends a new index to a path. As a result, the depth of the path is increased. - + @@ -156921,13 +160529,13 @@ As a result, the depth of the path is increased. a `GtkTreePath` + line="809">a `GtkTreePath` the index + line="810">the index @@ -156938,29 +160546,29 @@ As a result, the depth of the path is increased. deprecated-version="4.10"> Compares two paths. + line="985">Compares two paths. If @a appears before @b in a tree, then -1 is returned. If @b appears before @a, then 1 is returned. If the two nodes are equal, then 0 is returned. - + the relative positions of @a and @b + line="996">the relative positions of @a and @b a `GtkTreePath` + line="987">a `GtkTreePath` a `GtkTreePath` to compare with + line="988">a `GtkTreePath` to compare with @@ -156971,19 +160579,19 @@ If the two nodes are equal, then 0 is returned. deprecated-version="4.10"> Creates a new `GtkTreePath` as a copy of @path. - + line="955">Creates a new `GtkTreePath` as a copy of @path. + a new `GtkTreePath` + line="961">a new `GtkTreePath` a `GtkTreePath` + line="957">a `GtkTreePath` @@ -156994,8 +160602,8 @@ If the two nodes are equal, then 0 is returned. deprecated-version="4.10"> Moves @path to point to the first child of the current path. - + line="1162">Moves @path to point to the first child of the current path. + @@ -157003,7 +160611,7 @@ If the two nodes are equal, then 0 is returned. a `GtkTreePath` + line="1164">a `GtkTreePath` @@ -157014,8 +160622,8 @@ If the two nodes are equal, then 0 is returned. deprecated-version="4.10"> Frees @path. If @path is %NULL, it simply returns. - + line="937">Frees @path. If @path is %NULL, it simply returns. + @@ -157026,7 +160634,7 @@ If the two nodes are equal, then 0 is returned. allow-none="1"> a `GtkTreePath` + line="939">a `GtkTreePath` @@ -157037,19 +160645,19 @@ If the two nodes are equal, then 0 is returned. deprecated-version="4.10"> Returns the current depth of @path. - + line="867">Returns the current depth of @path. + The depth of @path + line="873">The depth of @path a `GtkTreePath` + line="869">a `GtkTreePath` @@ -157062,24 +160670,24 @@ If the two nodes are equal, then 0 is returned. deprecated-version="4.10"> Returns the current indices of @path. + line="885">Returns the current indices of @path. This is an array of integers, each representing a node in a tree. This value should not be freed. The length of the array can be obtained with gtk_tree_path_get_depth(). - + The current indices + line="896">The current indices a `GtkTreePath` + line="887">a `GtkTreePath` @@ -157091,16 +160699,16 @@ The length of the array can be obtained with gtk_tree_path_get_depth(). deprecated-version="4.10"> Returns the current indices of @path. + line="908">Returns the current indices of @path. This is an array of integers, each representing a node in a tree. It also returns the number of elements in the array. The array should not be freed. - + The current + line="920">The current indices @@ -157110,7 +160718,7 @@ The array should not be freed. a `GtkTreePath` + line="910">a `GtkTreePath` allow-none="1"> return location for number of elements + line="911">return location for number of elements returned in the integer array @@ -157133,25 +160741,25 @@ The array should not be freed. deprecated-version="4.10"> Returns %TRUE if @descendant is a descendant of @path. - + line="1023">Returns %TRUE if @descendant is a descendant of @path. + %TRUE if @descendant is contained inside @path + line="1030">%TRUE if @descendant is contained inside @path a `GtkTreePath` + line="1025">a `GtkTreePath` another `GtkTreePath` + line="1026">another `GtkTreePath` @@ -157162,25 +160770,25 @@ The array should not be freed. deprecated-version="4.10"> Returns %TRUE if @path is a descendant of @ancestor. - + line="1058">Returns %TRUE if @path is a descendant of @ancestor. + %TRUE if @ancestor contains @path somewhere below it + line="1065">%TRUE if @ancestor contains @path somewhere below it a `GtkTreePath` + line="1060">a `GtkTreePath` another `GtkTreePath` + line="1061">another `GtkTreePath` @@ -157191,8 +160799,8 @@ The array should not be freed. deprecated-version="4.10"> Moves the @path to point to the next node at the current depth. - + line="1094">Moves the @path to point to the next node at the current depth. + @@ -157200,7 +160808,7 @@ The array should not be freed. a `GtkTreePath` + line="1096">a `GtkTreePath` @@ -157211,10 +160819,10 @@ The array should not be freed. deprecated-version="4.10"> Prepends a new index to a path. + line="835">Prepends a new index to a path. As a result, the depth of the path is increased. - + @@ -157222,13 +160830,13 @@ As a result, the depth of the path is increased. a `GtkTreePath` + line="837">a `GtkTreePath` the index + line="838">the index @@ -157239,13 +160847,13 @@ As a result, the depth of the path is increased. deprecated-version="4.10"> Moves the @path to point to the previous node at the + line="1111">Moves the @path to point to the previous node at the current depth, if it exists. - + %TRUE if @path has a previous node, and + line="1118">%TRUE if @path has a previous node, and the move was made @@ -157253,7 +160861,7 @@ current depth, if it exists. a `GtkTreePath` + line="1113">a `GtkTreePath` @@ -157264,24 +160872,24 @@ current depth, if it exists. deprecated-version="4.10"> Generates a string representation of the path. + line="742">Generates a string representation of the path. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. If the path has depth 0, %NULL is returned. - + A newly-allocated string + line="753">A newly-allocated string a `GtkTreePath` + line="744">a `GtkTreePath` @@ -157292,19 +160900,19 @@ depth 0, %NULL is returned. deprecated-version="4.10"> Moves the @path to point to its parent node, if it has a parent. - + line="1139">Moves the @path to point to its parent node, if it has a parent. + %TRUE if @path has a parent, and the move was made + line="1145">%TRUE if @path has a parent, and the move was made a `GtkTreePath` + line="1141">a `GtkTreePath` @@ -157318,14 +160926,17 @@ depth 0, %NULL is returned. A GtkTreeRowReference tracks model changes so that it always refers to the + line="252">A GtkTreeRowReference tracks model changes so that it always refers to the same row (a `GtkTreePath` refers to a position, not a fixed row). Create a new GtkTreeRowReference with gtk_tree_row_reference_new(). + Use [iface@Gio.ListModel] instead deprecated-version="4.10"> Creates a row reference based on @path. + line="2405">Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. Any changes that occur on @model are propagated, and the path is updated appropriately. If @path isn’t a valid path in @model, then %NULL is returned. - + a newly allocated `GtkTreeRowReference` + line="2417">a newly allocated `GtkTreeRowReference` a `GtkTreeModel` + line="2407">a `GtkTreeModel` a valid `GtkTreePath` to monitor + line="2408">a valid `GtkTreePath` to monitor @@ -157367,7 +160978,7 @@ propagated, and the path is updated appropriately. If deprecated-version="4.10"> You do not need to use this function. + line="2435">You do not need to use this function. Creates a row reference based on @path. @@ -157391,30 +161002,30 @@ doesn’t work for reasons of internal implementation. This type of row reference is primarily meant by structures that need to carefully monitor exactly when a row reference updates itself, and is not generally needed by most applications. - + a newly allocated `GtkTreeRowReference` + line="2466">a newly allocated `GtkTreeRowReference` a proxy `GObject` + line="2437">a proxy `GObject` a `GtkTreeModel` + line="2438">a `GtkTreeModel` a valid `GtkTreePath` to monitor + line="2439">a valid `GtkTreePath` to monitor @@ -157425,19 +161036,19 @@ itself, and is not generally needed by most applications. deprecated-version="4.10"> Copies a `GtkTreeRowReference`. - + line="2591">Copies a `GtkTreeRowReference`. + a copy of @reference + line="2597">a copy of @reference a `GtkTreeRowReference` + line="2593">a `GtkTreeRowReference` @@ -157448,8 +161059,8 @@ itself, and is not generally needed by most applications. deprecated-version="4.10"> Free’s @reference. @reference may be %NULL - + line="2609">Free’s @reference. @reference may be %NULL + @@ -157460,7 +161071,7 @@ itself, and is not generally needed by most applications. allow-none="1"> a `GtkTreeRowReference` + line="2611">a `GtkTreeRowReference` @@ -157471,19 +161082,19 @@ itself, and is not generally needed by most applications. deprecated-version="4.10"> Returns the model that the row reference is monitoring. - + line="2552">Returns the model that the row reference is monitoring. + the model + line="2558">the model a `GtkTreeRowReference` + line="2554">a `GtkTreeRowReference` @@ -157494,20 +161105,20 @@ itself, and is not generally needed by most applications. deprecated-version="4.10"> Returns a path that the row reference currently points to, + line="2527">Returns a path that the row reference currently points to, or %NULL if the path pointed to is no longer valid. - + a current path + line="2534">a current path a `GtkTreeRowReference` + line="2529">a `GtkTreeRowReference` @@ -157518,13 +161129,13 @@ or %NULL if the path pointed to is no longer valid. deprecated-version="4.10"> Returns %TRUE if the @reference is non-%NULL and refers to + line="2570">Returns %TRUE if the @reference is non-%NULL and refers to a current valid path. - + %TRUE if @reference points to a valid path + line="2577">%TRUE if @reference points to a valid path @@ -157534,7 +161145,7 @@ a current valid path. allow-none="1"> a `GtkTreeRowReference` + line="2572">a `GtkTreeRowReference` @@ -157545,10 +161156,10 @@ a current valid path. deprecated-version="4.10"> Lets a set of row reference created by + line="2673">Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-deleted signal. - + @@ -157556,13 +161167,13 @@ model emitted the ::row-deleted signal. a `GObject` + line="2675">a `GObject` the path position that was deleted + line="2676">the path position that was deleted @@ -157573,10 +161184,10 @@ model emitted the ::row-deleted signal. deprecated-version="4.10"> Lets a set of row reference created by + line="2653">Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-inserted signal. - + @@ -157584,13 +161195,13 @@ model emitted the ::row-inserted signal. a `GObject` + line="2655">a `GObject` the row position that was inserted + line="2656">the row position that was inserted @@ -157602,10 +161213,10 @@ model emitted the ::row-inserted signal. deprecated-version="4.10"> Lets a set of row reference created by + line="2693">Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::rows-reordered signal. - + @@ -157613,25 +161224,25 @@ model emitted the ::rows-reordered signal. a `GObject` + line="2695">a `GObject` the parent path of the reordered signal + line="2696">the parent path of the reordered signal the iter pointing to the parent of the reordered + line="2697">the iter pointing to the parent of the reordered the new order of rows + line="2698">the new order of rows @@ -158977,6 +162588,10 @@ the contents of @sortable are resorted. + Signal emitted when the sort column or sort + order of sortable is changed. @@ -158994,6 +162609,10 @@ the contents of @sortable are resorted. + Fills in sort_column_id and order with the + current sort column and the order. @@ -159033,6 +162652,10 @@ the contents of @sortable are resorted. + Sets the current sort column to be + sort_column_id. @@ -159062,6 +162685,10 @@ the contents of @sortable are resorted. + Sets the comparison function used when sorting to + be sort_func. @@ -159116,6 +162743,10 @@ the contents of @sortable are resorted. + Sets the default comparison function used + when sorting to be sort_func. @@ -159164,6 +162795,10 @@ the contents of @sortable are resorted. + %TRUE if the model has a default sort +function. @@ -159241,7 +162876,7 @@ An example of a UI Definition fragment for a tree store: deprecated-version="4.10"> Creates a new tree store. + line="303">Creates a new tree store. The tree store will have @n_columns, with each column using the corresponding type passed to this function. @@ -159262,20 +162897,20 @@ will create a new `GtkTreeStore` with three columns of type a new `GtkTreeStore` + line="325">a new `GtkTreeStore` number of columns in the tree store + line="305">number of columns in the tree store all `GType` types for the columns, from first to last + line="306">all `GType` types for the columns, from first to last @@ -159287,7 +162922,7 @@ will create a new `GtkTreeStore` with three columns of type deprecated-version="4.10"> Creates a new tree store. + line="360">Creates a new tree store. This constructor is meant for language bindings. Use [class@Gtk.TreeListModel] instead @@ -159295,20 +162930,20 @@ This constructor is meant for language bindings. a new `GtkTreeStore` + line="369">a new `GtkTreeStore` number of columns in the tree store + line="362">number of columns in the tree store an array of `GType` types for the columns, from first to last + line="363">an array of `GType` types for the columns, from first to last @@ -159321,7 +162956,7 @@ This constructor is meant for language bindings. deprecated-version="4.10"> Appends a new row to @tree_store. + line="1803">Appends a new row to @tree_store. If @parent is non-%NULL, then it will append the new row after the last child of @parent, otherwise it will append a row to the top level. @@ -159338,7 +162973,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). A `GtkTreeStore` + line="1805">A `GtkTreeStore` transfer-ownership="none"> An unset `GtkTreeIter` to set to the appended row + line="1806">An unset `GtkTreeIter` to set to the appended row allow-none="1"> A valid `GtkTreeIter` + line="1807">A valid `GtkTreeIter` @@ -159367,7 +163002,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). deprecated-version="4.10"> Removes all rows from @tree_store + line="1969">Removes all rows from @tree_store Use [class@Gtk.TreeListModel] instead @@ -159377,7 +163012,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). a `GtkTreeStore` + line="1971">a `GtkTreeStore` @@ -159388,7 +163023,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). deprecated-version="4.10"> Creates a new row at @position. + line="1321">Creates a new row at @position. If parent is non-%NULL, then the row will be made a child of @parent. Otherwise, the row will be created at the toplevel. @@ -159408,7 +163043,7 @@ need to call gtk_tree_store_set() or gtk_tree_store_set_value(). A `GtkTreeStore` + line="1323">A `GtkTreeStore` transfer-ownership="none"> An unset `GtkTreeIter` to set to the new row + line="1324">An unset `GtkTreeIter` to set to the new row allow-none="1"> A valid `GtkTreeIter` + line="1325">A valid `GtkTreeIter` position to insert the new row, or -1 for last + line="1326">position to insert the new row, or -1 for last @@ -159443,7 +163078,7 @@ need to call gtk_tree_store_set() or gtk_tree_store_set_value(). deprecated-version="4.10"> Inserts a new row after @sibling. + line="1474">Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to @parent’s children. @@ -159465,7 +163100,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). A `GtkTreeStore` + line="1476">A `GtkTreeStore` transfer-ownership="none"> An unset `GtkTreeIter` to set to the new row + line="1477">An unset `GtkTreeIter` to set to the new row allow-none="1"> A valid `GtkTreeIter` + line="1478">A valid `GtkTreeIter` allow-none="1"> A valid `GtkTreeIter` + line="1479">A valid `GtkTreeIter` @@ -159503,7 +163138,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). deprecated-version="4.10"> Inserts a new row before @sibling. + line="1388">Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to @parent’s children. @@ -159525,7 +163160,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). A `GtkTreeStore` + line="1390">A `GtkTreeStore` transfer-ownership="none"> An unset `GtkTreeIter` to set to the new row + line="1391">An unset `GtkTreeIter` to set to the new row allow-none="1"> A valid `GtkTreeIter` + line="1392">A valid `GtkTreeIter` allow-none="1"> A valid `GtkTreeIter` + line="1393">A valid `GtkTreeIter` @@ -159565,7 +163200,7 @@ gtk_tree_store_set() or gtk_tree_store_set_value(). deprecated-version="4.10"> Creates a new row at the given @position. + line="1561">Creates a new row at the given @position. The @iter parameter will be changed to point to this new row. @@ -159600,7 +163235,7 @@ generally be preferred when inserting rows in a sorted tree store. A `GtkTreeStore` + line="1563">A `GtkTreeStore` allow-none="1"> An unset `GtkTreeIter` to set the new row + line="1564">An unset `GtkTreeIter` to set the new row allow-none="1"> A valid `GtkTreeIter` + line="1565">A valid `GtkTreeIter` position to insert the new row, or -1 to append after existing rows + line="1566">position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 + line="1567">pairs of column number and value, terminated with -1 @@ -159644,7 +163279,7 @@ generally be preferred when inserting rows in a sorted tree store. deprecated-version="4.10"> A variant of gtk_tree_store_insert_with_values() which takes + line="1661">A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language bindings. @@ -159657,7 +163292,7 @@ This function is mainly intended for language bindings. A `GtkTreeStore` + line="1663">A `GtkTreeStore` allow-none="1"> An unset `GtkTreeIter` to set the new row + line="1664">An unset `GtkTreeIter` to set the new row allow-none="1"> A valid `GtkTreeIter` + line="1665">A valid `GtkTreeIter` position to insert the new row, or -1 for last + line="1666">position to insert the new row, or -1 for last an array of column numbers + line="1667">an array of column numbers @@ -159697,7 +163332,7 @@ This function is mainly intended for language bindings. an array of GValues + line="1668">an array of GValues @@ -159705,7 +163340,7 @@ This function is mainly intended for language bindings. the length of the @columns and @values arrays + line="1669">the length of the @columns and @values arrays @@ -159716,32 +163351,32 @@ This function is mainly intended for language bindings. deprecated-version="4.10"> Checks if @iter is an ancestor of @descendant. + line="1867">Checks if @iter is an ancestor of @descendant. Use [class@Gtk.TreeListModel] instead true if @iter is an ancestor of @descendant, and false otherwise + line="1875">true if @iter is an ancestor of @descendant, and false otherwise A `GtkTreeStore` + line="1869">A `GtkTreeStore` A valid `GtkTreeIter` + line="1870">A valid `GtkTreeIter` A valid `GtkTreeIter` + line="1871">A valid `GtkTreeIter` @@ -159752,7 +163387,7 @@ This function is mainly intended for language bindings. deprecated-version="4.10"> Returns the depth of the position pointed by the iterator + line="1893">Returns the depth of the position pointed by the iterator The depth will be 0 for anything on the root level, 1 for anything down a level, etc. @@ -159761,20 +163396,20 @@ a level, etc. The depth of the position pointed by the iterator + line="1903">The depth of the position pointed by the iterator A `GtkTreeStore` + line="1895">A `GtkTreeStore` A valid `GtkTreeIter` + line="1896">A valid `GtkTreeIter` @@ -159785,7 +163420,7 @@ a level, etc. deprecated-version="4.10"> Checks if the given iter is a valid iter for this `GtkTreeStore`. + line="2010">Checks if the given iter is a valid iter for this `GtkTreeStore`. This function is slow. Only use it for debugging and/or testing purposes. @@ -159794,20 +163429,20 @@ purposes. true if the iter is valid, and false otherwise + line="2020">true if the iter is valid, and false otherwise a tree store + line="2012">a tree store the iterator to check + line="2013">the iterator to check @@ -159818,7 +163453,7 @@ purposes. deprecated-version="4.10"> Moves @iter in @tree_store to the position after @position. + line="2922">Moves @iter in @tree_store to the position after @position. @iter and @position should be in the same level. @@ -159834,13 +163469,13 @@ If @position is %NULL, @iter will be moved to the start of the level. A `GtkTreeStore` + line="2924">A `GtkTreeStore` A `GtkTreeIter`. + line="2925">A `GtkTreeIter`. allow-none="1"> A `GtkTreeIter`. + line="2926">A `GtkTreeIter`. @@ -159860,7 +163495,7 @@ If @position is %NULL, @iter will be moved to the start of the level. deprecated-version="4.10"> Moves @iter in @tree_store to the position before @position. + line="2898">Moves @iter in @tree_store to the position before @position. @iter and @position should be in the same level. @@ -159876,13 +163511,13 @@ If @position is %NULL, @iter will be moved to the end of the level. A `GtkTreeStore` + line="2900">A `GtkTreeStore` A `GtkTreeIter` + line="2901">A `GtkTreeIter` allow-none="1"> A `GtkTreeIter` + line="2902">A `GtkTreeIter` @@ -159902,7 +163537,7 @@ If @position is %NULL, @iter will be moved to the end of the level. deprecated-version="4.10"> Prepends a new row to @tree_store. + line="1740">Prepends a new row to @tree_store. If @parent is non-%NULL, then it will prepend the new row before the first child of @parent, otherwise it will prepend a row to the top level. The @@ -159918,7 +163553,7 @@ call gtk_tree_store_set() or gtk_tree_store_set_value(). A `GtkTreeStore` + line="1742">A `GtkTreeStore` transfer-ownership="none"> An unset `GtkTreeIter` to set to the prepended row + line="1743">An unset `GtkTreeIter` to set to the prepended row allow-none="1"> A valid `GtkTreeIter` + line="1744">A valid `GtkTreeIter` @@ -159947,7 +163582,7 @@ call gtk_tree_store_set() or gtk_tree_store_set_value(). deprecated-version="4.10"> Removes @iter from @tree_store. + line="1250">Removes @iter from @tree_store. After being removed, @iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one. @@ -159956,20 +163591,20 @@ invalidated if it previously pointed to the last one. true if @iter is still valid, and false otherwise + line="1260">true if @iter is still valid, and false otherwise A `GtkTreeStore` + line="1252">A `GtkTreeStore` A valid `GtkTreeIter` + line="1253">A valid `GtkTreeIter` @@ -159981,7 +163616,7 @@ invalidated if it previously pointed to the last one. deprecated-version="4.10"> Reorders the children of @parent in @tree_store to follow the order + line="2339">Reorders the children of @parent in @tree_store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. @@ -159994,7 +163629,7 @@ Note that this function only works with unsorted stores. A `GtkTreeStore` + line="2341">A `GtkTreeStore` allow-none="1"> the parent of the children to re-order + line="2342">the parent of the children to re-order an array of integers mapping the new position + line="2343">an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. `new_order[newpos] = oldpos` @@ -160026,7 +163661,7 @@ Note that this function only works with unsorted stores. deprecated-version="4.10"> Sets the value of one or more cells in the row referenced by @iter. + line="1213">Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. @@ -160051,19 +163686,19 @@ will be copied if it is a `G_TYPE_STRING` or `G_TYPE_BOXED`. A `GtkTreeStore` + line="1215">A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified + line="1216">A valid `GtkTreeIter` for the row being modified pairs of column number and value, terminated with -1 + line="1217">pairs of column number and value, terminated with -1 @@ -160074,7 +163709,7 @@ will be copied if it is a `G_TYPE_STRING` or `G_TYPE_BOXED`. deprecated-version="4.10"> Sets the type of the columns in a tree store. + line="400">Sets the type of the columns in a tree store. This function is meant primarily for types that inherit from `GtkTreeStore`, and should only be used when constructing a new @@ -160092,19 +163727,19 @@ tree store. A `GtkTreeStore` + line="402">A `GtkTreeStore` Number of columns for the tree store + line="403">Number of columns for the tree store An array of `GType` types, one for each column + line="404">An array of `GType` types, one for each column @@ -160118,7 +163753,7 @@ tree store. deprecated-version="4.10"> A version of gtk_tree_store_set() using `va_list`. + line="1173">A version of gtk_tree_store_set() using `va_list`. Use [class@Gtk.TreeListModel] instead @@ -160128,19 +163763,19 @@ tree store. A `GtkTreeStore` + line="1175">A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified + line="1176">A valid `GtkTreeIter` for the row being modified va_list of column/value pairs + line="1177">va_list of column/value pairs @@ -160151,7 +163786,7 @@ tree store. deprecated-version="4.10"> Sets the data in the cell specified by @iter and @column. + line="977">Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. @@ -160164,25 +163799,25 @@ column. a `GtkTreeStore` + line="979">a `GtkTreeStore` A valid `GtkTreeIter` for the row being modified + line="980">A valid `GtkTreeIter` for the row being modified column number to modify + line="981">column number to modify new value for the cell + line="982">new value for the cell @@ -160194,7 +163829,7 @@ column. deprecated-version="4.10"> A variant of gtk_tree_store_set_valist() which takes + line="1124">A variant of gtk_tree_store_set_valist() which takes the columns and values as two arrays, instead of using variadic arguments. @@ -160209,19 +163844,19 @@ the number of columns to change is not known until run-time. A `GtkTreeStore` + line="1126">A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified + line="1127">A valid `GtkTreeIter` for the row being modified an array of column numbers + line="1128">an array of column numbers @@ -160229,7 +163864,7 @@ the number of columns to change is not known until run-time. an array of GValues + line="1129">an array of GValues @@ -160237,7 +163872,7 @@ the number of columns to change is not known until run-time. the length of the @columns and @values arrays + line="1130">the length of the @columns and @values arrays @@ -160248,7 +163883,7 @@ the number of columns to change is not known until run-time. deprecated-version="4.10"> Swaps @a and @b in the same level of @tree_store. + line="2431">Swaps @a and @b in the same level of @tree_store. Note that this function only works with unsorted stores. Use [class@Gtk.TreeListModel] instead @@ -160260,19 +163895,19 @@ Note that this function only works with unsorted stores. A `GtkTreeStore`. + line="2433">A `GtkTreeStore`. A `GtkTreeIter`. + line="2434">A `GtkTreeIter`. Another `GtkTreeIter`. + line="2435">Another `GtkTreeIter`. @@ -160316,6 +163951,11 @@ Note that this function only works with unsorted stores. filename="gtk/deprecated/gtktreeview.c" line="74">A widget for displaying both trees and lists +<picture> + <source srcset="list-and-tree-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkTreeView" src="list-and-tree.png"> +</picture> + Widget that displays any object that implements the [iface@Gtk.TreeModel] interface. Please refer to the [tree widget conceptual overview](section-tree-widget.html) @@ -160413,13 +164053,13 @@ For the drop target location during DND, a subnode with name `dndtarget` is used deprecated-version="4.10"> Creates a new `GtkTreeView` widget. + line="10171">Creates a new `GtkTreeView` widget. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A newly created `GtkTreeView` widget. + line="10176">A newly created `GtkTreeView` widget. @@ -160429,20 +164069,20 @@ For the drop target location during DND, a subnode with name `dndtarget` is used deprecated-version="4.10"> Creates a new `GtkTreeView` widget with the model initialized to @model. + line="10186">Creates a new `GtkTreeView` widget with the model initialized to @model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A newly created `GtkTreeView` widget. + line="10192">A newly created `GtkTreeView` widget. the model. + line="10188">the model. @@ -160518,7 +164158,7 @@ For the drop target location during DND, a subnode with name `dndtarget` is used deprecated-version="4.10"> Activates the cell determined by @path and @column. + line="11322">Activates the cell determined by @path and @column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160528,13 +164168,13 @@ For the drop target location during DND, a subnode with name `dndtarget` is used A `GtkTreeView` + line="11324">A `GtkTreeView` The `GtkTreePath` to be activated. + line="11325">The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. + line="11326">The `GtkTreeViewColumn` to be activated. @@ -160691,7 +164331,7 @@ For the drop target location during DND, a subnode with name `dndtarget` is used deprecated-version="4.10"> Appends @column to the list of columns. If @tree_view has “fixed_height” + line="10679">Appends @column to the list of columns. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160699,20 +164339,20 @@ GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after appending. + line="10688">The number of columns in @tree_view after appending. A `GtkTreeView`. + line="10681">A `GtkTreeView`. The `GtkTreeViewColumn` to add. + line="10682">The `GtkTreeViewColumn` to add. @@ -160723,7 +164363,7 @@ GTK_TREE_VIEW_COLUMN_FIXED. deprecated-version="4.10"> Recursively collapses all visible, expanded nodes in @tree_view. + line="11407">Recursively collapses all visible, expanded nodes in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160733,7 +164373,7 @@ GTK_TREE_VIEW_COLUMN_FIXED. A `GtkTreeView`. + line="11409">A `GtkTreeView`. @@ -160744,26 +164384,26 @@ GTK_TREE_VIEW_COLUMN_FIXED. deprecated-version="4.10"> Collapses a row (hides its child rows, if they exist). + line="11717">Collapses a row (hides its child rows, if they exist). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the row was collapsed. + line="11724">%TRUE if the row was collapsed. a `GtkTreeView` + line="11719">a `GtkTreeView` path to a row in the @tree_view + line="11720">path to a row in the @tree_view @@ -160774,7 +164414,7 @@ GTK_TREE_VIEW_COLUMN_FIXED. deprecated-version="4.10"> Resizes all columns to their optimal width. Only works after the + line="10539">Resizes all columns to their optimal width. Only works after the treeview has been realized. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160785,7 +164425,7 @@ treeview has been realized. A `GtkTreeView`. + line="10541">A `GtkTreeView`. @@ -160796,7 +164436,7 @@ treeview has been realized. deprecated-version="4.10"> Converts bin_window coordinates to coordinates for the + line="12687">Converts bin_window coordinates to coordinates for the tree (the full scrollable area of the tree). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160807,19 +164447,19 @@ tree (the full scrollable area of the tree). a `GtkTreeView` + line="12689">a `GtkTreeView` X coordinate relative to bin_window + line="12690">X coordinate relative to bin_window Y coordinate relative to bin_window + line="12691">Y coordinate relative to bin_window transfer-ownership="full"> return location for tree X coordinate + line="12692">return location for tree X coordinate transfer-ownership="full"> return location for tree Y coordinate + line="12693">return location for tree Y coordinate @@ -160848,7 +164488,7 @@ tree (the full scrollable area of the tree). deprecated-version="4.10"> Converts bin_window coordinates to widget relative coordinates. + line="12628">Converts bin_window coordinates to widget relative coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160858,19 +164498,19 @@ tree (the full scrollable area of the tree). a `GtkTreeView` + line="12630">a `GtkTreeView` bin_window X coordinate + line="12631">bin_window X coordinate bin_window Y coordinate + line="12632">bin_window Y coordinate transfer-ownership="full"> return location for widget X coordinate + line="12633">return location for widget X coordinate transfer-ownership="full"> return location for widget Y coordinate + line="12634">return location for widget Y coordinate @@ -160899,7 +164539,7 @@ tree (the full scrollable area of the tree). deprecated-version="4.10"> Converts tree coordinates (coordinates in full scrollable area of the tree) + line="12657">Converts tree coordinates (coordinates in full scrollable area of the tree) to bin_window coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160910,19 +164550,19 @@ to bin_window coordinates. a `GtkTreeView` + line="12659">a `GtkTreeView` tree X coordinate + line="12660">tree X coordinate tree Y coordinate + line="12661">tree Y coordinate transfer-ownership="full"> return location for X coordinate relative to bin_window + line="12662">return location for X coordinate relative to bin_window transfer-ownership="full"> return location for Y coordinate relative to bin_window + line="12663">return location for Y coordinate relative to bin_window @@ -160951,7 +164591,7 @@ to bin_window coordinates. deprecated-version="4.10"> Converts tree coordinates (coordinates in full scrollable area of the tree) + line="12567">Converts tree coordinates (coordinates in full scrollable area of the tree) to widget coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -160962,19 +164602,19 @@ to widget coordinates. a `GtkTreeView` + line="12569">a `GtkTreeView` X coordinate relative to the tree + line="12570">X coordinate relative to the tree Y coordinate relative to the tree + line="12571">Y coordinate relative to the tree transfer-ownership="full"> return location for widget X coordinate + line="12572">return location for widget X coordinate transfer-ownership="full"> return location for widget Y coordinate + line="12573">return location for widget Y coordinate @@ -161003,7 +164643,7 @@ to widget coordinates. deprecated-version="4.10"> Converts widget coordinates to coordinates for the bin_window. + line="12599">Converts widget coordinates to coordinates for the bin_window. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161013,19 +164653,19 @@ to widget coordinates. a `GtkTreeView` + line="12601">a `GtkTreeView` X coordinate relative to the widget + line="12602">X coordinate relative to the widget Y coordinate relative to the widget + line="12603">Y coordinate relative to the widget transfer-ownership="full"> return location for bin_window X coordinate + line="12604">return location for bin_window X coordinate transfer-ownership="full"> return location for bin_window Y coordinate + line="12605">return location for bin_window Y coordinate @@ -161054,7 +164694,7 @@ to widget coordinates. deprecated-version="4.10"> Converts widget coordinates to coordinates for the + line="12535">Converts widget coordinates to coordinates for the tree (the full scrollable area of the tree). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161065,19 +164705,19 @@ tree (the full scrollable area of the tree). a `GtkTreeView` + line="12537">a `GtkTreeView` X coordinate relative to the widget + line="12538">X coordinate relative to the widget Y coordinate relative to the widget + line="12539">Y coordinate relative to the widget transfer-ownership="full"> return location for tree X coordinate + line="12540">return location for tree X coordinate transfer-ownership="full"> return location for tree Y coordinate + line="12541">return location for tree Y coordinate @@ -161106,27 +164746,27 @@ tree (the full scrollable area of the tree). deprecated-version="4.10"> Creates a `cairo_surface_t` representation of the row at @path. + line="13282">Creates a `cairo_surface_t` representation of the row at @path. This image is used for a drag icon. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a newly-allocated surface of the drag icon. + line="13290">a newly-allocated surface of the drag icon. a `GtkTreeView` + line="13284">a `GtkTreeView` a `GtkTreePath` in @tree_view + line="13285">a `GtkTreePath` in @tree_view @@ -161137,7 +164777,7 @@ This image is used for a drag icon. deprecated-version="4.10"> Turns @tree_view into a drop destination for automatic DND. Calling + line="12942">Turns @tree_view into a drop destination for automatic DND. Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161148,19 +164788,19 @@ this method sets `GtkTreeView`:reorderable to %FALSE. a `GtkTreeView` + line="12944">a `GtkTreeView` the target formats that the drag will support + line="12945">the target formats that the drag will support the bitmask of possible actions for a drag from this + line="12946">the bitmask of possible actions for a drag from this widget @@ -161172,7 +164812,7 @@ this method sets `GtkTreeView`:reorderable to %FALSE. deprecated-version="4.10"> Turns @tree_view into a drag source for automatic DND. Calling this + line="12907">Turns @tree_view into a drag source for automatic DND. Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161183,25 +164823,25 @@ method sets `GtkTreeView`:reorderable to %FALSE. a `GtkTreeView` + line="12909">a `GtkTreeView` Mask of allowed buttons to start drag + line="12910">Mask of allowed buttons to start drag the target formats that the drag will support + line="12911">the target formats that the drag will support the bitmask of possible actions for a drag from this + line="12912">the bitmask of possible actions for a drag from this widget @@ -161213,7 +164853,7 @@ method sets `GtkTreeView`:reorderable to %FALSE. deprecated-version="4.10"> Recursively expands all nodes in the @tree_view. + line="11373">Recursively expands all nodes in the @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161223,7 +164863,7 @@ method sets `GtkTreeView`:reorderable to %FALSE. A `GtkTreeView`. + line="11375">A `GtkTreeView`. @@ -161234,32 +164874,32 @@ method sets `GtkTreeView`:reorderable to %FALSE. deprecated-version="4.10"> Opens the row so its children are visible. + line="11576">Opens the row so its children are visible. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the row existed and had children + line="11584">%TRUE if the row existed and had children a `GtkTreeView` + line="11578">a `GtkTreeView` path to a row + line="11579">path to a row whether to recursively expand, or just expand immediate children + line="11580">whether to recursively expand, or just expand immediate children @@ -161270,7 +164910,7 @@ method sets `GtkTreeView`:reorderable to %FALSE. deprecated-version="4.10"> Expands the row at @path. This will also expand all parent rows of + line="11447">Expands the row at @path. This will also expand all parent rows of @path as necessary. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161281,13 +164921,13 @@ method sets `GtkTreeView`:reorderable to %FALSE. A `GtkTreeView`. + line="11449">A `GtkTreeView`. path to a row. + line="11450">path to a row. @@ -161299,20 +164939,20 @@ method sets `GtkTreeView`:reorderable to %FALSE. deprecated-version="4.10"> Gets the setting set by gtk_tree_view_set_activate_on_single_click(). + line="10656">Gets the setting set by gtk_tree_view_set_activate_on_single_click(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if row-activated will be emitted on a single click + line="10662">%TRUE if row-activated will be emitted on a single click a `GtkTreeView` + line="10658">a `GtkTreeView` @@ -161323,7 +164963,7 @@ method sets `GtkTreeView`:reorderable to %FALSE. deprecated-version="4.10"> Fills the bounding rectangle in bin_window coordinates for the cell at the + line="12442">Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a node not found in the tree, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width @@ -161341,7 +164981,7 @@ itself, excluding surrounding borders and the tree expander area. a `GtkTreeView` + line="12444">a `GtkTreeView` allow-none="1"> a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates + line="12445">a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates allow-none="1"> a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates + line="12446">a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates transfer-ownership="none"> rectangle to fill with cell background rect + line="12447">rectangle to fill with cell background rect @@ -161379,7 +165019,7 @@ itself, excluding surrounding borders and the tree expander area. deprecated-version="4.10"> Fills the bounding rectangle in bin_window coordinates for the cell at the + line="12314">Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a path not currently displayed, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width @@ -161397,7 +165037,7 @@ realized. a `GtkTreeView` + line="12316">a `GtkTreeView` allow-none="1"> a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates + line="12317">a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates allow-none="1"> a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates + line="12318">a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates transfer-ownership="none"> rectangle to fill with cell rect + line="12319">rectangle to fill with cell rect @@ -161435,13 +165075,13 @@ realized. deprecated-version="4.10"> Gets the `GtkTreeViewColumn` at the given position in the #tree_view. + line="10959">Gets the `GtkTreeViewColumn` at the given position in the #tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The `GtkTreeViewColumn`, or %NULL if the + line="10966">The `GtkTreeViewColumn`, or %NULL if the position is outside the range of columns. @@ -161449,13 +165089,13 @@ position is outside the range of columns. A `GtkTreeView`. + line="10961">A `GtkTreeView`. The position of the column, counting from 0. + line="10962">The position of the column, counting from 0. @@ -161466,14 +165106,14 @@ position is outside the range of columns. deprecated-version="4.10"> Returns a `GList` of all the `GtkTreeViewColumn`s currently in @tree_view. + line="10988">Returns a `GList` of all the `GtkTreeViewColumn`s currently in @tree_view. The returned list must be freed with g_list_free (). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A list of `GtkTreeViewColumn`s + line="10995">A list of `GtkTreeViewColumn`s @@ -161482,7 +165122,7 @@ The returned list must be freed with g_list_free (). A `GtkTreeView` + line="10990">A `GtkTreeView` @@ -161493,7 +165133,7 @@ The returned list must be freed with g_list_free (). deprecated-version="4.10"> Fills in @path and @focus_column with the current path and focus column. If + line="11991">Fills in @path and @focus_column with the current path and focus column. If the cursor isn’t currently set, then *@path will be %NULL. If no column currently has focus, then *@focus_column will be %NULL. @@ -161508,7 +165148,7 @@ you are done with it. A `GtkTreeView` + line="11993">A `GtkTreeView` allow-none="1"> A pointer to be + line="11994">A pointer to be filled with the current cursor path @@ -161533,7 +165173,7 @@ you are done with it. allow-none="1"> A + line="11996">A pointer to be filled with the current focus column @@ -161545,7 +165185,7 @@ you are done with it. deprecated-version="4.10"> Determines the destination row for a given position. @drag_x and + line="13161">Determines the destination row for a given position. @drag_x and @drag_y are expected to be in widget coordinates. This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. @@ -161554,7 +165194,7 @@ return %FALSE if @tree_view is not realized or does not have a model. whether there is a row at the given position, %TRUE if this + line="13176">whether there is a row at the given position, %TRUE if this is indeed the case. @@ -161562,19 +165202,19 @@ is indeed the case. a `GtkTreeView` + line="13163">a `GtkTreeView` the position to determine the destination row for + line="13164">the position to determine the destination row for the position to determine the destination row for + line="13165">the position to determine the destination row for allow-none="1"> Return location for the path of + line="13166">Return location for the path of the highlighted row @@ -161598,7 +165238,7 @@ is indeed the case. allow-none="1"> Return location for the drop position, or + line="13168">Return location for the drop position, or %NULL @@ -161611,7 +165251,7 @@ is indeed the case. deprecated-version="4.10"> Gets information about the row that is highlighted for feedback. + line="13125">Gets information about the row that is highlighted for feedback. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161621,7 +165261,7 @@ is indeed the case. a `GtkTreeView` + line="13127">a `GtkTreeView` allow-none="1"> Return location for the path of the highlighted row + line="13128">Return location for the path of the highlighted row allow-none="1"> Return location for the drop position + line="13129">Return location for the drop position @@ -161657,21 +165297,21 @@ is indeed the case. deprecated-version="4.10"> Returns whether or not the tree allows to start interactive searching + line="13469">Returns whether or not the tree allows to start interactive searching by typing in text. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether or not to let the user search interactively + line="13476">whether or not to let the user search interactively A `GtkTreeView` + line="13471">A `GtkTreeView` @@ -161683,13 +165323,13 @@ by typing in text. deprecated-version="4.10"> Returns whether or not tree lines are drawn in @tree_view. + line="14572">Returns whether or not tree lines are drawn in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if tree lines are drawn in @tree_view, %FALSE + line="14578">%TRUE if tree lines are drawn in @tree_view, %FALSE otherwise. @@ -161697,7 +165337,7 @@ otherwise. a `GtkTreeView`. + line="14574">a `GtkTreeView`. @@ -161709,7 +165349,7 @@ otherwise. deprecated-version="4.10"> Returns the column that is the current expander column, + line="11098">Returns the column that is the current expander column, or %NULL if none has been set. This column has the expander arrow drawn next to it. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -161717,14 +165357,14 @@ This column has the expander arrow drawn next to it. The expander column. + line="11106">The expander column. A `GtkTreeView` + line="11100">A `GtkTreeView` @@ -161736,20 +165376,20 @@ This column has the expander arrow drawn next to it. deprecated-version="4.10"> Returns whether fixed height mode is turned on for @tree_view. + line="7595">Returns whether fixed height mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in fixed height mode + line="7601">%TRUE if @tree_view is in fixed height mode a `GtkTreeView` + line="7597">a `GtkTreeView` @@ -161760,13 +165400,13 @@ This column has the expander arrow drawn next to it. deprecated-version="4.10"> Returns which grid lines are enabled in @tree_view. + line="14521">Returns which grid lines are enabled in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView`GridLines value indicating which grid lines + line="14527">a `GtkTreeView`GridLines value indicating which grid lines are enabled. @@ -161774,7 +165414,7 @@ are enabled. a `GtkTreeView` + line="14523">a `GtkTreeView` @@ -161786,20 +165426,20 @@ are enabled. deprecated-version="4.10"> Returns whether all header columns are clickable. + line="10604">Returns whether all header columns are clickable. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if all header columns are clickable, otherwise %FALSE + line="10610">%TRUE if all header columns are clickable, otherwise %FALSE A `GtkTreeView`. + line="10606">A `GtkTreeView`. @@ -161811,20 +165451,20 @@ are enabled. deprecated-version="4.10"> Returns %TRUE if the headers on the @tree_view are visible. + line="10466">Returns %TRUE if the headers on the @tree_view are visible. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead Whether the headers are visible or not. + line="10472">Whether the headers are visible or not. A `GtkTreeView`. + line="10468">A `GtkTreeView`. @@ -161836,20 +165476,20 @@ are enabled. deprecated-version="4.10"> Returns whether hover expansion mode is turned on for @tree_view. + line="14373">Returns whether hover expansion mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in hover expansion mode + line="14379">%TRUE if @tree_view is in hover expansion mode a `GtkTreeView` + line="14375">a `GtkTreeView` @@ -161861,20 +165501,20 @@ are enabled. deprecated-version="4.10"> Returns whether hover selection mode is turned on for @tree_view. + line="14326">Returns whether hover selection mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in hover selection mode + line="14332">%TRUE if @tree_view is in hover selection mode a `GtkTreeView` + line="14328">a `GtkTreeView` @@ -161886,14 +165526,14 @@ are enabled. deprecated-version="4.10"> Returns the amount, in pixels, of extra indentation for child levels + line="14704">Returns the amount, in pixels, of extra indentation for child levels in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the amount of extra indentation for child levels in + line="14711">the amount of extra indentation for child levels in @tree_view. A return value of 0 means that this feature is disabled. @@ -161901,7 +165541,7 @@ in @tree_view. a `GtkTreeView`. + line="14706">a `GtkTreeView`. @@ -161913,21 +165553,21 @@ in @tree_view. deprecated-version="4.10"> Returns the model the `GtkTreeView` is based on. Returns %NULL if the + line="10205">Returns the model the `GtkTreeView` is based on. Returns %NULL if the model is unset. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeModel` + line="10212">A `GtkTreeModel` a `GtkTreeView` + line="10207">a `GtkTreeView` @@ -161938,20 +165578,20 @@ model is unset. deprecated-version="4.10"> Queries the number of columns in the given @tree_view. + line="10939">Queries the number of columns in the given @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in the @tree_view + line="10945">The number of columns in the @tree_view a `GtkTreeView` + line="10941">a `GtkTreeView` @@ -161962,7 +165602,7 @@ model is unset. deprecated-version="4.10"> Finds the path at the point (@x, @y), relative to bin_window coordinates. + line="12141">Finds the path at the point (@x, @y), relative to bin_window coordinates. That is, @x and @y are relative to an events coordinates. Widget-relative coordinates must be converted using gtk_tree_view_convert_widget_to_bin_window_coords(). It is primarily for @@ -161983,26 +165623,26 @@ gtk_tree_view_convert_widget_to_bin_window_coords(). %TRUE if a row exists at that coordinate. + line="12172">%TRUE if a row exists at that coordinate. A `GtkTreeView`. + line="12143">A `GtkTreeView`. The x position to be identified (relative to bin_window). + line="12144">The x position to be identified (relative to bin_window). The y position to be identified (relative to bin_window). + line="12145">The y position to be identified (relative to bin_window). allow-none="1"> A pointer to a `GtkTreePath` + line="12146">A pointer to a `GtkTreePath` pointer to be filled in @@ -162027,7 +165667,7 @@ gtk_tree_view_convert_widget_to_bin_window_coords(). allow-none="1"> A pointer to + line="12148">A pointer to a `GtkTreeViewColumn` pointer to be filled in @@ -162039,7 +165679,7 @@ gtk_tree_view_convert_widget_to_bin_window_coords(). allow-none="1"> A pointer where the X coordinate + line="12150">A pointer where the X coordinate relative to the cell can be placed @@ -162051,7 +165691,7 @@ gtk_tree_view_convert_widget_to_bin_window_coords(). allow-none="1"> A pointer where the Y coordinate + line="12152">A pointer where the Y coordinate relative to the cell can be placed @@ -162064,21 +165704,21 @@ gtk_tree_view_convert_widget_to_bin_window_coords(). deprecated-version="4.10"> Retrieves whether the user can reorder the tree via drag-and-drop. See + line="11839">Retrieves whether the user can reorder the tree via drag-and-drop. See gtk_tree_view_set_reorderable(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the tree can be reordered. + line="11846">%TRUE if the tree can be reordered. a `GtkTreeView` + line="11841">a `GtkTreeView` @@ -162090,13 +165730,13 @@ gtk_tree_view_set_reorderable(). deprecated-version="4.10"> Returns the current row separator function. + line="14466">Returns the current row separator function. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the current row separator function. + line="14472">the current row separator function. @@ -162104,7 +165744,7 @@ gtk_tree_view_set_reorderable(). a `GtkTreeView` + line="14468">a `GtkTreeView` @@ -162116,7 +165756,7 @@ gtk_tree_view_set_reorderable(). deprecated-version="4.10"> Returns whether rubber banding is turned on for @tree_view. If the + line="14420">Returns whether rubber banding is turned on for @tree_view. If the selection mode is %GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -162124,14 +165764,14 @@ user to select multiple rows by dragging the mouse. %TRUE if rubber banding in @tree_view is enabled. + line="14428">%TRUE if rubber banding in @tree_view is enabled. a `GtkTreeView` + line="14422">a `GtkTreeView` @@ -162143,20 +165783,20 @@ user to select multiple rows by dragging the mouse. deprecated-version="4.10"> Gets the column searched on by the interactive search code. + line="13491">Gets the column searched on by the interactive search code. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the column the interactive search code searches in. + line="13497">the column the interactive search code searches in. A `GtkTreeView` + line="13493">A `GtkTreeView` @@ -162167,7 +165807,7 @@ user to select multiple rows by dragging the mouse. deprecated-version="4.10"> Returns the `GtkEntry` which is currently in use as interactive search + line="13599">Returns the `GtkEntry` which is currently in use as interactive search entry for @tree_view. In case the built-in entry is being used, %NULL will be returned. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -162175,14 +165815,14 @@ will be returned. the entry currently in use as search entry. + line="13607">the entry currently in use as search entry. A `GtkTreeView` + line="13601">A `GtkTreeView` @@ -162194,13 +165834,13 @@ will be returned. deprecated-version="4.10"> Returns the compare function currently in use. + line="13544">Returns the compare function currently in use. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the currently used compare function for the search code. + line="13550">the currently used compare function for the search code. @@ -162208,7 +165848,7 @@ will be returned. A `GtkTreeView` + line="13546">A `GtkTreeView` @@ -162219,20 +165859,20 @@ will be returned. deprecated-version="4.10"> Gets the `GtkTreeSelection` associated with @tree_view. + line="10381">Gets the `GtkTreeSelection` associated with @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeSelection` object. + line="10387">A `GtkTreeSelection` object. A `GtkTreeView`. + line="10383">A `GtkTreeView`. @@ -162244,13 +165884,13 @@ will be returned. deprecated-version="4.10"> Returns whether or not expanders are drawn in @tree_view. + line="14659">Returns whether or not expanders are drawn in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if expanders are drawn in @tree_view, %FALSE + line="14665">%TRUE if expanders are drawn in @tree_view, %FALSE otherwise. @@ -162258,7 +165898,7 @@ otherwise. a `GtkTreeView`. + line="14661">a `GtkTreeView`. @@ -162270,14 +165910,14 @@ otherwise. deprecated-version="4.10"> Returns the column of @tree_view’s model which is being used for + line="15021">Returns the column of @tree_view’s model which is being used for displaying tooltips on @tree_view’s rows. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the index of the tooltip column that is currently being + line="15028">the index of the tooltip column that is currently being used, or -1 if this is disabled. @@ -162285,7 +165925,7 @@ used, or -1 if this is disabled. a `GtkTreeView` + line="15023">a `GtkTreeView` @@ -162296,7 +165936,7 @@ used, or -1 if this is disabled. deprecated-version="4.10"> This function is supposed to be used in a ::query-tooltip + line="14843">This function is supposed to be used in a ::query-tooltip signal handler for `GtkTreeView`. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. @@ -162312,32 +165952,32 @@ to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE. whether or not the given tooltip context points to a row + line="14866">whether or not the given tooltip context points to a row a `GtkTreeView` + line="14845">a `GtkTreeView` the x coordinate (relative to widget coordinates) + line="14846">the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) + line="14847">the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not + line="14848">whether this is a keyboard tooltip or not a pointer to + line="14849">a pointer to receive a `GtkTreeModel` @@ -162361,7 +166001,7 @@ to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE. a pointer to receive a `GtkTreePath` + line="14851">a pointer to receive a `GtkTreePath` a pointer to receive a `GtkTreeIter` + line="14852">a pointer to receive a `GtkTreeIter` @@ -162383,7 +166023,7 @@ to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE. Sets @start_path and @end_path to be the first and last visible path. + line="12719">Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. The paths should be freed with gtk_tree_path_free() after use. @@ -162392,14 +166032,14 @@ The paths should be freed with gtk_tree_path_free() after use. %TRUE, if valid paths were placed in @start_path and @end_path. + line="12730">%TRUE, if valid paths were placed in @start_path and @end_path. A `GtkTreeView` + line="12721">A `GtkTreeView` allow-none="1"> Return location for start of region + line="12722">Return location for start of region allow-none="1"> Return location for end of region + line="12723">Return location for end of region @@ -162432,7 +166072,7 @@ The paths should be freed with gtk_tree_path_free() after use. deprecated-version="4.10"> Fills @visible_rect with the currently-visible region of the + line="12500">Fills @visible_rect with the currently-visible region of the buffer, in tree coordinates. Convert to bin_window coordinates with gtk_tree_view_convert_tree_to_bin_window_coords(). Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire @@ -162446,7 +166086,7 @@ scrollable area of the tree. a `GtkTreeView` + line="12502">a `GtkTreeView` transfer-ownership="none"> rectangle to fill + line="12503">rectangle to fill @@ -162466,7 +166106,7 @@ scrollable area of the tree. deprecated-version="4.10"> This inserts the @column into the @tree_view at @position. If @position is + line="10769">This inserts the @column into the @tree_view at @position. If @position is -1, then the column is inserted at the end. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. @@ -162475,26 +166115,26 @@ set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after insertion. + line="10780">The number of columns in @tree_view after insertion. A `GtkTreeView`. + line="10771">A `GtkTreeView`. The `GtkTreeViewColumn` to be inserted. + line="10772">The `GtkTreeViewColumn` to be inserted. The position to insert @column in. + line="10773">The position to insert @column in. @@ -162506,7 +166146,7 @@ set to be GTK_TREE_VIEW_COLUMN_FIXED. deprecated-version="4.10"> Creates a new `GtkTreeViewColumn` and inserts it into the @tree_view at + line="10837">Creates a new `GtkTreeViewColumn` and inserts it into the @tree_view at @position. If @position is -1, then the newly created column is inserted at the end. The column is initialized with the attributes given. If @tree_view has “fixed_height” mode enabled, then the new column will have its sizing @@ -162516,38 +166156,38 @@ property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after insertion. + line="10851">The number of columns in @tree_view after insertion. A `GtkTreeView` + line="10839">A `GtkTreeView` The position to insert the new column in + line="10840">The position to insert the new column in The title to set the header to + line="10841">The title to set the header to The `GtkCellRenderer` + line="10842">The `GtkCellRenderer` A %NULL-terminated list of attributes + line="10843">A %NULL-terminated list of attributes @@ -162558,7 +166198,7 @@ property set to be GTK_TREE_VIEW_COLUMN_FIXED. deprecated-version="4.10"> Convenience function that inserts a new column into the `GtkTreeView` + line="10893">Convenience function that inserts a new column into the `GtkTreeView` with the given cell renderer and a `GtkTreeCellDataFunc` to set cell renderer attributes (normally using data from the model). See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). @@ -162569,32 +166209,32 @@ If @tree_view has “fixed_height” mode enabled, then the new column will have number of columns in the tree view post-insert + line="10910">number of columns in the tree view post-insert a `GtkTreeView` + line="10895">a `GtkTreeView` Position to insert, -1 for append + line="10896">Position to insert, -1 for append column title + line="10897">column title cell renderer for column + line="10898">cell renderer for column function to set attributes of cell renderer + line="10899">function to set attributes of cell renderer data for @func + line="10900">data for @func destroy notifier for @data + line="10901">destroy notifier for @data @@ -162630,7 +166270,7 @@ If @tree_view has “fixed_height” mode enabled, then the new column will have deprecated-version="4.10"> Determine whether the point (@x, @y) in @tree_view is blank, that is no + line="12781">Determine whether the point (@x, @y) in @tree_view is blank, that is no cell content nor an expander arrow is drawn at the location. If so, the location can be considered as the background. You might wish to take special action on clicks on the background, such as clearing a current @@ -162652,7 +166292,7 @@ gtk_tree_view_get_path_at_pos() for more information. %TRUE if the area at the given coordinates is blank, + line="12813">%TRUE if the area at the given coordinates is blank, %FALSE otherwise. @@ -162660,19 +166300,19 @@ gtk_tree_view_get_path_at_pos() for more information. A `GtkTreeView` + line="12783">A `GtkTreeView` The x position to be identified (relative to bin_window) + line="12784">The x position to be identified (relative to bin_window) The y position to be identified (relative to bin_window) + line="12785">The y position to be identified (relative to bin_window) allow-none="1"> A pointer to a `GtkTreePath` pointer to + line="12786">A pointer to a `GtkTreePath` pointer to be filled in @@ -162697,7 +166337,7 @@ gtk_tree_view_get_path_at_pos() for more information. allow-none="1"> A pointer to a + line="12788">A pointer to a `GtkTreeViewColumn` pointer to be filled in @@ -162709,7 +166349,7 @@ gtk_tree_view_get_path_at_pos() for more information. allow-none="1"> A pointer where the X coordinate relative to the + line="12790">A pointer where the X coordinate relative to the cell can be placed @@ -162721,7 +166361,7 @@ gtk_tree_view_get_path_at_pos() for more information. allow-none="1"> A pointer where the Y coordinate relative to the + line="12792">A pointer where the Y coordinate relative to the cell can be placed @@ -162733,14 +166373,14 @@ gtk_tree_view_get_path_at_pos() for more information. deprecated-version="4.10"> Returns whether a rubber banding operation is currently being done + line="14440">Returns whether a rubber banding operation is currently being done in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if a rubber banding operation is currently being + line="14447">%TRUE if a rubber banding operation is currently being done in @tree_view. @@ -162748,7 +166388,7 @@ done in @tree_view. a `GtkTreeView` + line="14442">a `GtkTreeView` @@ -162759,7 +166399,7 @@ done in @tree_view. deprecated-version="4.10"> Calls @func on all expanded rows. + line="11780">Calls @func on all expanded rows. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -162769,7 +166409,7 @@ done in @tree_view. A `GtkTreeView` + line="11782">A `GtkTreeView` closure="1"> A function to be called + line="11783">A function to be called allow-none="1"> User data to be passed to the function. + line="11784">User data to be passed to the function. @@ -162798,7 +166438,7 @@ done in @tree_view. deprecated-version="4.10"> Moves @column to be after to @base_column. If @base_column is %NULL, then + line="11009">Moves @column to be after to @base_column. If @base_column is %NULL, then @column is placed in the first position. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -162809,13 +166449,13 @@ done in @tree_view. A `GtkTreeView` + line="11011">A `GtkTreeView` The `GtkTreeViewColumn` to be moved. + line="11012">The `GtkTreeViewColumn` to be moved. allow-none="1"> The `GtkTreeViewColumn` to be moved relative to + line="11013">The `GtkTreeViewColumn` to be moved relative to @@ -162835,26 +166475,26 @@ done in @tree_view. deprecated-version="4.10"> Removes @column from @tree_view. + line="10703">Removes @column from @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after removing. + line="10710">The number of columns in @tree_view after removing. A `GtkTreeView`. + line="10705">A `GtkTreeView`. The `GtkTreeViewColumn` to remove. + line="10706">The `GtkTreeViewColumn` to remove. @@ -162865,7 +166505,7 @@ done in @tree_view. deprecated-version="4.10"> Activates the cell determined by @path and @column. + line="11322">Activates the cell determined by @path and @column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -162875,13 +166515,13 @@ done in @tree_view. A `GtkTreeView` + line="11324">A `GtkTreeView` The `GtkTreePath` to be activated. + line="11325">The `GtkTreePath` to be activated. allow-none="1"> The `GtkTreeViewColumn` to be activated. + line="11326">The `GtkTreeViewColumn` to be activated. @@ -162901,26 +166541,26 @@ done in @tree_view. deprecated-version="4.10"> Returns %TRUE if the node pointed to by @path is expanded in @tree_view. + line="11810">Returns %TRUE if the node pointed to by @path is expanded in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if #path is expanded. + line="11817">%TRUE if #path is expanded. A `GtkTreeView`. + line="11812">A `GtkTreeView`. A `GtkTreePath` to test expansion state. + line="11813">A `GtkTreePath` to test expansion state. @@ -162931,7 +166571,7 @@ done in @tree_view. deprecated-version="4.10"> Moves the alignments of @tree_view to the position specified by @column and + line="11199">Moves the alignments of @tree_view to the position specified by @column and @path. If @column is %NULL, then no horizontal scrolling occurs. Likewise, if @path is %NULL no vertical scrolling occurs. At a minimum, one of @column or @path need to be non-%NULL. @row_align determines where the row is @@ -162956,7 +166596,7 @@ path will be modified to reflect this change. A `GtkTreeView`. + line="11201">A `GtkTreeView`. allow-none="1"> The path of the row to move to + line="11202">The path of the row to move to allow-none="1"> The `GtkTreeViewColumn` to move horizontally to + line="11203">The `GtkTreeViewColumn` to move horizontally to whether to use alignment arguments, or %FALSE. + line="11204">whether to use alignment arguments, or %FALSE. The vertical alignment of the row specified by @path. + line="11205">The vertical alignment of the row specified by @path. The horizontal alignment of the column specified by @column. + line="11206">The horizontal alignment of the column specified by @column. @@ -163003,7 +166643,7 @@ path will be modified to reflect this change. deprecated-version="4.10"> Scrolls the tree view such that the top-left corner of the visible + line="11162">Scrolls the tree view such that the top-left corner of the visible area is @tree_x, @tree_y, where @tree_x and @tree_y are specified in tree coordinates. The @tree_view must be realized before this function is called. If it isn't, you probably want to be @@ -163019,19 +166659,19 @@ If either @tree_x or @tree_y are -1, then that direction isn’t scrolled. a `GtkTreeView` + line="11164">a `GtkTreeView` X coordinate of new top-left pixel of visible area, or -1 + line="11165">X coordinate of new top-left pixel of visible area, or -1 Y coordinate of new top-left pixel of visible area, or -1 + line="11166">Y coordinate of new top-left pixel of visible area, or -1 @@ -163043,7 +166683,7 @@ If either @tree_x or @tree_y are -1, then that direction isn’t scrolled. deprecated-version="4.10"> Cause the `GtkTreeView`::row-activated signal to be emitted + line="10629">Cause the `GtkTreeView`::row-activated signal to be emitted on a single click instead of a double click. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163054,13 +166694,13 @@ on a single click instead of a double click. a `GtkTreeView` + line="10631">a `GtkTreeView` %TRUE to emit row-activated on a single click + line="10632">%TRUE to emit row-activated on a single click @@ -163071,7 +166711,7 @@ on a single click instead of a double click. deprecated-version="4.10"> Sets a user function for determining where a column may be dropped when + line="11125">Sets a user function for determining where a column may be dropped when dragged. This function is called on every column pair in turn at the beginning of a column drag to determine where a drop can take place. The arguments passed to @func are: the @tree_view, the `GtkTreeViewColumn` being @@ -163089,7 +166729,7 @@ dropped everywhere. A `GtkTreeView`. + line="11127">A `GtkTreeView`. destroy="2"> A function to determine which columns are reorderable + line="11128">A function to determine which columns are reorderable @@ -163111,7 +166751,7 @@ dropped everywhere. allow-none="1"> User data to be passed to @func + line="11129">User data to be passed to @func scope="async"> Destroy notifier for @user_data + line="11130">Destroy notifier for @user_data @@ -163132,7 +166772,7 @@ dropped everywhere. deprecated-version="4.10"> Sets the current keyboard focus to be at @path, and selects it. This is + line="12032">Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. Additionally, if @focus_column is specified, and @start_editing is @@ -163152,13 +166792,13 @@ and the function will return without failing. A `GtkTreeView` + line="12034">A `GtkTreeView` A `GtkTreePath` + line="12035">A `GtkTreePath` allow-none="1"> A `GtkTreeViewColumn` + line="12036">A `GtkTreeViewColumn` %TRUE if the specified cell should start being edited. + line="12037">%TRUE if the specified cell should start being edited. @@ -163184,7 +166824,7 @@ and the function will return without failing. deprecated-version="4.10"> Sets the current keyboard focus to be at @path, and selects it. This is + line="12063">Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. If @focus_column and @focus_cell are not %NULL, and @focus_column @@ -163207,13 +166847,13 @@ and the function will return without failing. A `GtkTreeView` + line="12065">A `GtkTreeView` A `GtkTreePath` + line="12066">A `GtkTreePath` allow-none="1"> A `GtkTreeViewColumn` + line="12067">A `GtkTreeViewColumn` allow-none="1"> A `GtkCellRenderer` + line="12068">A `GtkCellRenderer` %TRUE if the specified cell should start being edited. + line="12069">%TRUE if the specified cell should start being edited. @@ -163248,7 +166888,7 @@ and the function will return without failing. deprecated-version="4.10"> Sets the row that is highlighted for feedback. + line="13057">Sets the row that is highlighted for feedback. If @path is %NULL, an existing highlight is removed. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163259,7 +166899,7 @@ If @path is %NULL, an existing highlight is removed. a `GtkTreeView` + line="13059">a `GtkTreeView` allow-none="1"> The path of the row to highlight + line="13060">The path of the row to highlight Specifies whether to drop before, after or into the row + line="13061">Specifies whether to drop before, after or into the row @@ -163287,7 +166927,7 @@ If @path is %NULL, an existing highlight is removed. deprecated-version="4.10"> If @enable_search is set, then the user can type in text to search through + line="13439">If @enable_search is set, then the user can type in text to search through the tree interactively (this is sometimes called "typeahead find"). Note that even if this is %FALSE, the user can still initiate a search @@ -163301,13 +166941,13 @@ using the “start-interactive-search” key binding. A `GtkTreeView` + line="13441">A `GtkTreeView` %TRUE, if the user can search interactively + line="13442">%TRUE, if the user can search interactively @@ -163319,7 +166959,7 @@ using the “start-interactive-search” key binding. deprecated-version="4.10"> Sets whether to draw lines interconnecting the expanders in @tree_view. + line="14593">Sets whether to draw lines interconnecting the expanders in @tree_view. This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163330,13 +166970,13 @@ This does not have any visible effects for lists. a `GtkTreeView` + line="14595">a `GtkTreeView` %TRUE to enable tree line drawing, %FALSE otherwise. + line="14596">%TRUE to enable tree line drawing, %FALSE otherwise. @@ -163348,7 +166988,7 @@ This does not have any visible effects for lists. deprecated-version="4.10"> Sets the column to draw the expander arrow at. It must be in @tree_view. + line="11067">Sets the column to draw the expander arrow at. It must be in @tree_view. If @column is %NULL, then the expander arrow is always at the first visible column. @@ -163363,7 +167003,7 @@ expander column to a hidden column. A `GtkTreeView` + line="11069">A `GtkTreeView` @@ -163384,7 +167024,7 @@ expander column to a hidden column. deprecated-version="4.10"> Enables or disables the fixed height mode of @tree_view. + line="7542">Enables or disables the fixed height mode of @tree_view. Fixed height mode speeds up `GtkTreeView` by assuming that all rows have the same height. Only enable this option if all rows are the same height and all @@ -163398,13 +167038,13 @@ columns are of type %GTK_TREE_VIEW_COLUMN_FIXED. a `GtkTreeView` + line="7544">a `GtkTreeView` %TRUE to enable fixed height mode + line="7545">%TRUE to enable fixed height mode @@ -163415,7 +167055,7 @@ columns are of type %GTK_TREE_VIEW_COLUMN_FIXED. deprecated-version="4.10"> Sets which grid lines to draw in @tree_view. + line="14542">Sets which grid lines to draw in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163425,13 +167065,13 @@ columns are of type %GTK_TREE_VIEW_COLUMN_FIXED. a `GtkTreeView` + line="14544">a `GtkTreeView` a `GtkTreeView`GridLines value indicating which grid lines to + line="14545">a `GtkTreeView`GridLines value indicating which grid lines to enable. @@ -163444,7 +167084,7 @@ enable. deprecated-version="4.10"> Allow the column title buttons to be clicked. + line="10571">Allow the column title buttons to be clicked. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163454,13 +167094,13 @@ enable. A `GtkTreeView`. + line="10573">A `GtkTreeView`. %TRUE if the columns are clickable. + line="10574">%TRUE if the columns are clickable. @@ -163472,7 +167112,7 @@ enable. deprecated-version="4.10"> Sets the visibility state of the headers. + line="10486">Sets the visibility state of the headers. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163482,13 +167122,13 @@ enable. A `GtkTreeView`. + line="10488">A `GtkTreeView`. %TRUE if the headers are visible + line="10489">%TRUE if the headers are visible @@ -163500,7 +167140,7 @@ enable. deprecated-version="4.10"> Enables or disables the hover expansion mode of @tree_view. + line="14346">Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163512,13 +167152,13 @@ moves over them. a `GtkTreeView` + line="14348">a `GtkTreeView` %TRUE to enable hover selection mode + line="14349">%TRUE to enable hover selection mode @@ -163530,7 +167170,7 @@ moves over them. deprecated-version="4.10"> Enables or disables the hover selection mode of @tree_view. + line="14298">Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. @@ -163543,13 +167183,13 @@ Currently, this works only for the selection modes a `GtkTreeView` + line="14300">a `GtkTreeView` %TRUE to enable hover selection mode + line="14301">%TRUE to enable hover selection mode @@ -163561,7 +167201,7 @@ Currently, this works only for the selection modes deprecated-version="4.10"> Sets the amount of extra indentation for child levels to use in @tree_view + line="14680">Sets the amount of extra indentation for child levels to use in @tree_view in addition to the default indentation. The value should be specified in pixels, a value of 0 disables this feature and in this case only the default indentation will be used. @@ -163575,13 +167215,13 @@ This does not have any visible effects for lists. a `GtkTreeView` + line="14682">a `GtkTreeView` the amount, in pixels, of extra indentation in @tree_view. + line="14683">the amount, in pixels, of extra indentation in @tree_view. @@ -163593,7 +167233,7 @@ This does not have any visible effects for lists. deprecated-version="4.10"> Sets the model for a `GtkTreeView`. If the @tree_view already has a model + line="10226">Sets the model for a `GtkTreeView`. If the @tree_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163605,7 +167245,7 @@ then it will unset the old model. A `GtkTreeView`. + line="10228">A `GtkTreeView`. allow-none="1"> The model. + line="10229">The model. @@ -163626,7 +167266,7 @@ then it will unset the old model. deprecated-version="4.10"> This function is a convenience function to allow you to reorder + line="11860">This function is a convenience function to allow you to reorder models that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`. Both `GtkTreeStore` and `GtkListStore` support these. If @reorderable is %TRUE, then the user can reorder the @@ -163649,13 +167289,13 @@ handle drag and drop manually. A `GtkTreeView`. + line="11862">A `GtkTreeView`. %TRUE, if the tree can be reordered. + line="11863">%TRUE, if the tree can be reordered. @@ -163666,7 +167306,7 @@ handle drag and drop manually. deprecated-version="4.10"> Sets the row separator function, which is used to determine + line="14486">Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163678,7 +167318,7 @@ function is %NULL, no separators are drawn. This is the default value. a `GtkTreeView` + line="14488">a `GtkTreeView` destroy="2"> a `GtkTreeView`RowSeparatorFunc + line="14489">a `GtkTreeView`RowSeparatorFunc @@ -163700,7 +167340,7 @@ function is %NULL, no separators are drawn. This is the default value. allow-none="1"> user data to pass to @func + line="14490">user data to pass to @func scope="async"> destroy notifier for @data + line="14491">destroy notifier for @data @@ -163722,7 +167362,7 @@ function is %NULL, no separators are drawn. This is the default value. deprecated-version="4.10"> Enables or disables rubber banding in @tree_view. If the selection mode + line="14393">Enables or disables rubber banding in @tree_view. If the selection mode is %GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163734,13 +167374,13 @@ multiple rows by dragging the mouse. a `GtkTreeView` + line="14395">a `GtkTreeView` %TRUE to enable rubber banding + line="14396">%TRUE to enable rubber banding @@ -163752,7 +167392,7 @@ multiple rows by dragging the mouse. deprecated-version="4.10"> Sets @column as the column where the interactive search code should + line="13511">Sets @column as the column where the interactive search code should search in for the current model. If the search column is set, users can use the “start-interactive-search” @@ -163770,13 +167410,13 @@ column is reset to -1 when the model is changed. A `GtkTreeView` + line="13513">A `GtkTreeView` the column of the model to search in, or -1 to disable searching + line="13514">the column of the model to search in, or -1 to disable searching @@ -163787,7 +167427,7 @@ column is reset to -1 when the model is changed. deprecated-version="4.10"> Sets the entry which the interactive search code will use for this + line="13624">Sets the entry which the interactive search code will use for this @tree_view. This is useful when you want to provide a search entry in our interface at all time at a fixed position. Passing %NULL for @entry will make the interactive search code use the built-in popup @@ -163801,7 +167441,7 @@ entry again. A `GtkTreeView` + line="13626">A `GtkTreeView` allow-none="1"> the entry the interactive search code of @tree_view should use + line="13627">the entry the interactive search code of @tree_view should use @@ -163821,7 +167461,7 @@ entry again. deprecated-version="4.10"> Sets the compare function for the interactive search capabilities; note + line="13565">Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 0 for equality `GtkTreeView`SearchEqualFunc returns %FALSE on matches. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -163833,7 +167473,7 @@ that somewhat like strcmp() returning 0 for equality A `GtkTreeView` + line="13567">A `GtkTreeView` the compare function to use during the search + line="13568">the compare function to use during the search @@ -163853,7 +167493,7 @@ that somewhat like strcmp() returning 0 for equality allow-none="1"> user data to pass to @search_equal_func + line="13569">user data to pass to @search_equal_func Destroy notifier for @search_user_data + line="13570">Destroy notifier for @search_user_data @@ -163875,7 +167515,7 @@ that somewhat like strcmp() returning 0 for equality deprecated-version="4.10"> Sets whether to draw and enable expanders and indent child rows in + line="14627">Sets whether to draw and enable expanders and indent child rows in @tree_view. When disabled there will be no expanders visible in trees and there will be no way to expand and collapse rows by default. Also note that hiding the expanders will disable the default indentation. You @@ -163891,13 +167531,13 @@ This does not have any visible effects for lists. a `GtkTreeView` + line="14629">a `GtkTreeView` %TRUE to enable expander drawing, %FALSE otherwise. + line="14630">%TRUE to enable expander drawing, %FALSE otherwise. @@ -163908,7 +167548,7 @@ This does not have any visible effects for lists. deprecated-version="4.10"> Sets the tip area of @tooltip to the area @path, @column and @cell have + line="14749">Sets the tip area of @tooltip to the area @path, @column and @cell have in common. For example if @path is %NULL and @column is set, the tip area will be set to the full area covered by @column. See also gtk_tooltip_set_tip_area(). @@ -163928,13 +167568,13 @@ See also gtk_tree_view_set_tooltip_column() for a simpler alternative. a `GtkTreeView` + line="14751">a `GtkTreeView` a `GtkTooltip` + line="14752">a `GtkTooltip` allow-none="1"> a `GtkTreePath` + line="14753">a `GtkTreePath` allow-none="1"> a `GtkTreeViewColumn` + line="14754">a `GtkTreeViewColumn` allow-none="1"> a `GtkCellRenderer` + line="14755">a `GtkCellRenderer` @@ -163973,7 +167613,7 @@ See also gtk_tree_view_set_tooltip_column() for a simpler alternative. deprecated-version="4.10"> If you only plan to have simple (text-only) tooltips on full rows, you + line="14971">If you only plan to have simple (text-only) tooltips on full rows, you can use this function to have `GtkTreeView` handle these automatically for you. @column should be set to the column in @tree_view’s model containing the tooltip texts, or -1 to disable this feature. @@ -163992,13 +167632,13 @@ so &, <, etc have to be escaped in the text. a `GtkTreeView` + line="14973">a `GtkTreeView` an integer, which is a valid column number for @tree_view’s model + line="14974">an integer, which is a valid column number for @tree_view’s model @@ -164009,7 +167649,7 @@ so &, <, etc have to be escaped in the text. deprecated-version="4.10"> Sets the tip area of @tooltip to be the area covered by the row at @path. + line="14726">Sets the tip area of @tooltip to be the area covered by the row at @path. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -164021,19 +167661,19 @@ See also gtk_tooltip_set_tip_area(). a `GtkTreeView` + line="14728">a `GtkTreeView` a `GtkTooltip` + line="14729">a `GtkTooltip` a `GtkTreePath` + line="14730">a `GtkTreePath` @@ -164044,7 +167684,7 @@ See also gtk_tooltip_set_tip_area(). deprecated-version="4.10"> Undoes the effect of + line="13019">Undoes the effect of gtk_tree_view_enable_model_drag_dest(). Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -164056,7 +167696,7 @@ gtk_tree_view_enable_model_drag_dest(). Calling this method sets a `GtkTreeView` + line="13021">a `GtkTreeView` @@ -164067,7 +167707,7 @@ gtk_tree_view_enable_model_drag_dest(). Calling this method sets deprecated-version="4.10"> Undoes the effect of + line="12985">Undoes the effect of gtk_tree_view_enable_model_drag_source(). Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead @@ -164079,7 +167719,7 @@ gtk_tree_view_enable_model_drag_source(). Calling this method sets a `GtkTreeView` + line="12987">a `GtkTreeView` @@ -164092,7 +167732,7 @@ gtk_tree_view_enable_model_drag_source(). Calling this method sets default-value="FALSE"> The activate-on-single-click property specifies whether the "row-activated" signal + line="1127">The activate-on-single-click property specifies whether the "row-activated" signal will be emitted after a single click. @@ -164133,7 +167773,7 @@ will be emitted after a single click. default-value="FALSE"> Setting the ::fixed-height-mode property to %TRUE speeds up + line="1039">Setting the ::fixed-height-mode property to %TRUE speeds up `GtkTreeView` by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see gtk_tree_view_set_fixed_height_mode() for more @@ -164164,7 +167804,7 @@ information on this option. default-value="FALSE"> Enables or disables the hover expansion mode of @tree_view. + line="1069">Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. @@ -164180,7 +167820,7 @@ in `GtkComboBox` or `GtkEntryCompletion`. default-value="FALSE"> Enables or disables the hover selection mode of @tree_view. + line="1053">Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. @@ -164197,7 +167837,7 @@ in `GtkComboBox` or `GtkEntryCompletion`. default-value="0"> Extra indentation for each level. + line="1094">Extra indentation for each level. default-value="TRUE"> %TRUE if the view has expanders. + line="1084">%TRUE if the view has expanders. The number of columns of the treeview has changed. + line="1270">The number of columns of the treeview has changed. @@ -164264,7 +167904,7 @@ in `GtkComboBox` or `GtkEntryCompletion`. The position of the cursor (focused cell) has changed. + line="1285">The position of the cursor (focused cell) has changed. @@ -164288,7 +167928,7 @@ in `GtkComboBox` or `GtkEntryCompletion`. The `GtkTreeView`::move-cursor signal is a [keybinding + line="1300">The `GtkTreeView`::move-cursor signal is a [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user presses one of the cursor keys. @@ -164300,14 +167940,14 @@ gtk_tree_view_set_cursor_on_cell() when moving horizontally %TRUE if @step is supported, %FALSE otherwise. + line="1324">%TRUE if @step is supported, %FALSE otherwise. the granularity of the move, as a `GtkMovementStep`. + line="1303">the granularity of the move, as a `GtkMovementStep`. %GTK_MOVEMENT_LOGICAL_POSITIONS, %GTK_MOVEMENT_VISUAL_POSITIONS, %GTK_MOVEMENT_DISPLAY_LINES, %GTK_MOVEMENT_PAGES and %GTK_MOVEMENT_BUFFER_ENDS are supported. @@ -164318,20 +167958,20 @@ gtk_tree_view_set_cursor_on_cell() when moving horizontally the direction to move: +1 to move forwards; -1 to move + line="1309">the direction to move: +1 to move forwards; -1 to move backwards. The resulting movement is undefined for all other values. whether to extend the selection + line="1311">whether to extend the selection whether to modify the selection + line="1312">whether to modify the selection @@ -164339,8 +167979,8 @@ gtk_tree_view_set_cursor_on_cell() when moving horizontally The "row-activated" signal is emitted when the method -[`method@Gtk.TreeView.row_activated`] is called. + line="1141">The "row-activated" signal is emitted when the method +[method@Gtk.TreeView.row_activated] is called. This signal is emitted when the user double-clicks a treeview row with the [property@Gtk.TreeView:activate-on-single-click] property set to %FALSE, @@ -164360,7 +168000,7 @@ as well as `GtkTreeSelection`. the `GtkTreePath` for the activated row + line="1144">the `GtkTreePath` for the activated row allow-none="1"> the `GtkTreeViewColumn` in which the activation occurred + line="1145">the `GtkTreeViewColumn` in which the activation occurred @@ -164377,7 +168017,7 @@ as well as `GtkTreeSelection`. The given row has been collapsed (child nodes are hidden). + line="1248">The given row has been collapsed (child nodes are hidden). @@ -164385,13 +168025,13 @@ as well as `GtkTreeSelection`. the tree iter of the collapsed row + line="1251">the tree iter of the collapsed row a tree path that points to the row + line="1252">a tree path that points to the row @@ -164399,7 +168039,7 @@ as well as `GtkTreeSelection`. The given row has been expanded (child nodes are shown). + line="1226">The given row has been expanded (child nodes are shown). @@ -164407,13 +168047,13 @@ as well as `GtkTreeSelection`. the tree iter of the expanded row + line="1229">the tree iter of the expanded row a tree path that points to the row + line="1230">a tree path that points to the row @@ -164446,25 +168086,25 @@ as well as `GtkTreeSelection`. The given row is about to be collapsed (hide its children nodes). Use this + line="1201">The given row is about to be collapsed (hide its children nodes). Use this signal if you need to control the collapsibility of individual rows. %FALSE to allow collapsing, %TRUE to reject + line="1210">%FALSE to allow collapsing, %TRUE to reject the tree iter of the row to collapse + line="1204">the tree iter of the row to collapse a tree path that points to the row + line="1205">a tree path that points to the row @@ -164472,25 +168112,25 @@ signal if you need to control the collapsibility of individual rows. The given row is about to be expanded (show its children nodes). Use this + line="1176">The given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows. %FALSE to allow expansion, %TRUE to reject + line="1185">%FALSE to allow expansion, %TRUE to reject the tree iter of the row to expand + line="1179">the tree iter of the row to expand a tree path that points to the row + line="1180">a tree path that points to the row @@ -164523,13 +168163,13 @@ signal if you need to control the expandability of individual rows. A `GtkTreeView` + line="11324">A `GtkTreeView` The `GtkTreePath` to be activated. + line="11325">The `GtkTreePath` to be activated. allow-none="1"> The `GtkTreeViewColumn` to be activated. + line="11326">The `GtkTreeViewColumn` to be activated. @@ -166800,7 +170440,7 @@ can make columns appear choppy. c:type="GtkTreeViewGridLines"> Used to indicate which grid lines to draw in a tree view. + line="768">Used to indicate which grid lines to draw in a tree view. glib:name="GTK_TREE_VIEW_GRID_LINES_NONE"> No grid lines. + line="770">No grid lines. glib:name="GTK_TREE_VIEW_GRID_LINES_HORIZONTAL"> Horizontal grid lines. + line="771">Horizontal grid lines. glib:name="GTK_TREE_VIEW_GRID_LINES_VERTICAL"> Vertical grid lines. + line="772">Vertical grid lines. glib:name="GTK_TREE_VIEW_GRID_LINES_BOTH"> Horizontal and vertical grid lines. + line="773">Horizontal and vertical grid lines. @@ -166970,7 +170610,7 @@ has some similarity to strcmp() returning 0 for equal strings. c:type="GtkUnit"> See also gtk_print_settings_set_paper_width(). + line="749">See also gtk_print_settings_set_paper_width(). glib:name="GTK_UNIT_NONE"> No units. + line="751">No units. glib:name="GTK_UNIT_POINTS"> Dimensions in points. + line="752">Dimensions in points. glib:name="GTK_UNIT_INCH"> Dimensions in inches. + line="753">Dimensions in inches. glib:name="GTK_UNIT_MM"> Dimensions in millimeters + line="754">Dimensions in millimeters glib:type-struct="UriLauncherClass"> A `GtkUriLauncher` object collects the arguments that are needed to open a uri -with an application. + line="30">Asynchronous API to open a uri with an application. + +`GtkUriLauncher` collects the arguments that are needed to open the uri. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.UriLauncher.launch] function. -This API follows the GIO async pattern, and the result can be obtained by -calling [method@Gtk.UriLauncher.launch_finish]. To launch a file, use [class@Gtk.FileLauncher]. @@ -167074,23 +170713,20 @@ To launch a file, use [class@Gtk.FileLauncher]. a `GtkUriLauncher` + line="172">an uri launcher + version="4.10" + glib:finish-func="launch_finish"> Launch an application to open the uri. + line="261">Launches an application to open the uri. -This may present an app chooser dialog to the user. - -The @callback will be called when the operation is completed. -It should call [method@Gtk.UriLauncher.launch_finish] to obtain -the result. +This may present an app chooser dialog to the user. @@ -167099,7 +170735,7 @@ the result. a `GtkUriLauncher` + line="263">an uri launcher allow-none="1"> the parent `GtkWindow` + line="264">the parent window allow-none="1"> a `GCancellable` to cancel the operation + line="265">a cancellable to cancel the operation closure="3"> a callback to call when the operation is complete + line="266">a callback to call when the + operation is complete + allow-none="1"> data to pass to @callback + line="268">data to pass to @callback @@ -167149,27 +170785,26 @@ the result. throws="1"> Finishes the [method@Gtk.UriLauncher.launch] call and + line="333">Finishes the [method@Gtk.UriLauncher.launch] call and returns the result. `TRUE` if an application was launched, - or `FALSE` and @error is set + line="342">true if an application was launched a `GtkUriLauncher` + line="335">an uri launcher a `GAsyncResult` + line="336">the result @@ -167189,7 +170824,7 @@ returns the result. a `GtkUriLauncher` + line="190">an uri launcher setter="set_uri" getter="get_uri" default-value="NULL"> - - The uri to launch. @@ -167233,7 +170864,7 @@ returns the result. introspectable="0"> Evaluates to %TRUE if @value was initialized with %GTK_TYPE_EXPRESSION. + line="161">Evaluates to true if @value was initialized with `GTK_TYPE_EXPRESSION` @@ -167270,9 +170901,12 @@ returns the result. glib:type-struct="VideoClass"> `GtkVideo` is a widget to show a `GtkMediaStream` with media controls. + line="39">Shows a `GtkMediaStream` with media controls. -![An example GtkVideo](video.png) +<picture> + <source srcset="video-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkVideo" src="video.png"> +</picture> The controls are available separately as [class@Gtk.MediaControls]. If you just want to display a video without controls, you can treat it @@ -167284,31 +170918,31 @@ not have support for video overlays, multichannel audio, device selection, or input. If you are writing a full-fledged video player, you may want to use the [iface@Gdk.Paintable] API and a media framework such as Gstreamer directly. - + Creates a new empty `GtkVideo`. - + line="491">Creates a new empty `GtkVideo`. + a new `GtkVideo` + line="496">a new `GtkVideo` Creates a `GtkVideo` to play back the given @file. - + line="522">Creates a `GtkVideo` to play back the given @file. + a new `GtkVideo` + line="528">a new `GtkVideo` @@ -167318,7 +170952,7 @@ such as Gstreamer directly. allow-none="1"> a `GFile` + line="524">a `GFile` @@ -167327,15 +170961,15 @@ such as Gstreamer directly. c:identifier="gtk_video_new_for_filename"> Creates a `GtkVideo` to play back the given @filename. + line="540">Creates a `GtkVideo` to play back the given @filename. This is a utility function that calls [ctor@Gtk.Video.new_for_file], See that function for details. - + a new `GtkVideo` + line="549">a new `GtkVideo` @@ -167345,7 +170979,7 @@ See that function for details. allow-none="1"> filename to play back + line="542">filename to play back @@ -167354,12 +170988,12 @@ See that function for details. c:identifier="gtk_video_new_for_media_stream"> Creates a `GtkVideo` to play back the given @stream. - + line="504">Creates a `GtkVideo` to play back the given @stream. + a new `GtkVideo` + line="510">a new `GtkVideo` @@ -167369,7 +171003,7 @@ See that function for details. allow-none="1"> a `GtkMediaStream` + line="506">a `GtkMediaStream` @@ -167378,15 +171012,15 @@ See that function for details. c:identifier="gtk_video_new_for_resource"> Creates a `GtkVideo` to play back the resource at the + line="570">Creates a `GtkVideo` to play back the resource at the given @resource_path. This is a utility function that calls [ctor@Gtk.Video.new_for_file]. - + a new `GtkVideo` + line="579">a new `GtkVideo` @@ -167396,7 +171030,7 @@ This is a utility function that calls [ctor@Gtk.Video.new_for_file]. allow-none="1"> resource path to play back + line="572">resource path to play back @@ -167404,22 +171038,21 @@ This is a utility function that calls [ctor@Gtk.Video.new_for_file]. - Returns %TRUE if videos have been set to loop. - + line="903">Returns %TRUE if videos have been set to loop. + %TRUE if streams should autoplay + line="909">%TRUE if streams should autoplay a `GtkVideo` + line="905">a `GtkVideo` @@ -167427,23 +171060,48 @@ This is a utility function that calls [ctor@Gtk.Video.new_for_file]. - Gets the file played by @self or %NULL if not playing back + line="771">Gets the file played by @self or %NULL if not playing back a file. - + The file played by @self + line="778">The file played by @self a `GtkVideo` + line="773">a `GtkVideo` + + + + + + Returns whether graphics offload is enabled. + +See [class@Gtk.GraphicsOffload] for more information on graphics offload. + + + the graphics offload status + + + + + a `GtkVideo` @@ -167451,22 +171109,21 @@ a file. - Returns %TRUE if videos have been set to loop. - + line="941">Returns %TRUE if videos have been set to loop. + %TRUE if streams should loop + line="947">%TRUE if streams should loop a `GtkVideo` + line="943">a `GtkVideo` @@ -167474,22 +171131,21 @@ a file. - Gets the media stream managed by @self or %NULL if none. - + line="612">Gets the media stream managed by @self or %NULL if none. + The media stream managed by @self + line="618">The media stream managed by @self a `GtkVideo` + line="614">a `GtkVideo` @@ -167497,12 +171153,11 @@ a file. - Sets whether @self automatically starts playback when it + line="919">Sets whether @self automatically starts playback when it becomes visible or when a new file gets loaded. - + @@ -167510,13 +171165,13 @@ becomes visible or when a new file gets loaded. a `GtkVideo` + line="921">a `GtkVideo` whether media streams should autoplay + line="922">whether media streams should autoplay @@ -167524,11 +171179,10 @@ becomes visible or when a new file gets loaded. - Makes @self play the given @file. - + line="788">Makes @self play the given @file. + @@ -167536,7 +171190,7 @@ becomes visible or when a new file gets loaded. a `GtkVideo` + line="790">a `GtkVideo` allow-none="1"> the file to play + line="791">the file to play @@ -167553,10 +171207,10 @@ becomes visible or when a new file gets loaded. Makes @self play the given @filename. + line="835">Makes @self play the given @filename. This is a utility function that calls gtk_video_set_file(), - + @@ -167564,7 +171218,7 @@ This is a utility function that calls gtk_video_set_file(), a `GtkVideo` + line="837">a `GtkVideo` allow-none="1"> the filename to play + line="838">the filename to play + + Sets whether to enable graphics offload. + +See [class@Gtk.GraphicsOffload] for more information on graphics offload. + + + + + + + a `GtkVideo` + + + + the new graphics offload status + + + + - Sets whether new files loaded by @self should be set to loop. - + line="957">Sets whether new files loaded by @self should be set to loop. + @@ -167593,13 +171275,13 @@ This is a utility function that calls gtk_video_set_file(), a `GtkVideo` + line="959">a `GtkVideo` whether media streams should loop + line="960">whether media streams should loop @@ -167607,10 +171289,9 @@ This is a utility function that calls gtk_video_set_file(), - Sets the media stream to be played back. + line="700">Sets the media stream to be played back. @self will take full control of managing the media stream. If you want to manage a media stream yourself, consider using a @@ -167618,7 +171299,7 @@ want to manage a media stream yourself, consider using a If you want to display a file, consider using [method@Gtk.Video.set_file] instead. - + @@ -167626,7 +171307,7 @@ instead. a `GtkVideo` + line="702">a `GtkVideo` allow-none="1"> The media stream to play or %NULL to unset + line="703">The media stream to play or %NULL to unset @@ -167643,10 +171324,10 @@ instead. Makes @self play the resource at the given @resource_path. + line="863">Makes @self play the resource at the given @resource_path. This is a utility function that calls [method@Gtk.Video.set_file]. - + @@ -167654,7 +171335,7 @@ This is a utility function that calls [method@Gtk.Video.set_file]. a `GtkVideo` + line="865">a `GtkVideo` allow-none="1"> the resource to set + line="866">the resource to set @@ -167674,11 +171355,9 @@ This is a utility function that calls [method@Gtk.Video.set_file]. setter="set_autoplay" getter="get_autoplay" default-value="FALSE"> - - If the video should automatically begin playing. + line="415">If the video should automatically begin playing. transfer-ownership="none" setter="set_file" getter="get_file"> - - The file played by this video if the video is playing a file. + line="425">The file played by this video if the video is playing a file. + + Whether to enable graphics offload. + + - - If new media files should be set to loop. + line="435">If new media files should be set to loop. transfer-ownership="none" setter="set_media_stream" getter="get_media_stream"> - - The media-stream played + line="445">The media-stream played - + @@ -167737,8 +171420,8 @@ This is a utility function that calls [method@Gtk.Video.set_file]. glib:get-type="gtk_viewport_get_type"> `GtkViewport` implements scrollability for widgets that lack their -own scrolling capabilities. + line="42">Implements scrollability for widgets that don't support scrolling +on their own. Use `GtkViewport` to scroll child widgets such as `GtkGrid`, `GtkBox`, and so on. @@ -167752,9 +171435,9 @@ less than the child widget’s minimum size in a given orientation. # Accessibility -Until GTK 4.10, `GtkViewport` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkViewport` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkViewport` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkViewport` uses the [enum@Gtk.AccessibleRole.generic] role. @@ -167762,7 +171445,7 @@ Starting from GTK 4.12, `GtkViewport` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` rol Creates a new `GtkViewport`. + line="446">Creates a new `GtkViewport`. The new viewport uses the given adjustments, or default adjustments if none are given. @@ -167770,7 +171453,7 @@ adjustments if none are given. a new `GtkViewport` + line="456">a new `GtkViewport` @@ -167780,7 +171463,7 @@ adjustments if none are given. allow-none="1"> horizontal adjustment + line="448">horizontal adjustment allow-none="1"> vertical adjustment + line="449">vertical adjustment @@ -167797,22 +171480,21 @@ adjustments if none are given. - Gets the child widget of @viewport. + line="688">Gets the child widget of @viewport. the child widget of @viewport + line="694">the child widget of @viewport a `GtkViewport` + line="690">a `GtkViewport` @@ -167820,23 +171502,22 @@ adjustments if none are given. - Gets whether the viewport is scrolling to keep the focused + line="566">Gets whether the viewport is scrolling to keep the focused child in view. %TRUE if the viewport keeps the focus child scrolled to view + line="573">%TRUE if the viewport keeps the focus child scrolled to view a `GtkViewport` + line="568">a `GtkViewport` @@ -167846,7 +171527,7 @@ child in view. version="4.12"> Scrolls a descendant of the viewport into view. + line="704">Scrolls a descendant of the viewport into view. The viewport and the descendant must be visible and mapped for this function to work, otherwise no scrolling will be performed. @@ -167858,13 +171539,13 @@ this function to work, otherwise no scrolling will be performed. a `GtkViewport` + line="706">a `GtkViewport` a descendant widget of the viewport + line="707">a descendant widget of the viewport allow-none="1"> details of how to perform + line="708">details of how to perform the scroll operation or NULL to scroll into view @@ -167882,10 +171563,9 @@ this function to work, otherwise no scrolling will be performed. - Sets the child widget of @viewport. + line="660">Sets the child widget of @viewport. @@ -167894,7 +171574,7 @@ this function to work, otherwise no scrolling will be performed. a `GtkViewport` + line="662">a `GtkViewport` allow-none="1"> the child widget + line="663">the child widget @@ -167911,10 +171591,9 @@ this function to work, otherwise no scrolling will be performed. - Sets whether the viewport should automatically scroll + line="583">Sets whether the viewport should automatically scroll to keep the focused child in view. @@ -167924,13 +171603,13 @@ to keep the focused child in view. a `GtkViewport` + line="585">a `GtkViewport` whether to keep the focus widget scrolled to view + line="586">whether to keep the focus widget scrolled to view @@ -167940,11 +171619,9 @@ to keep the focused child in view. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="335">The child widget. setter="set_scroll_to_focus" getter="get_scroll_to_focus" default-value="TRUE"> - - Whether to scroll when the focus changes. + line="320">Whether to scroll when the focus changes. Before 4.6.2, this property was mistakenly defaulting to FALSE, so if your code needs to work with older versions, consider setting it explicitly to @@ -167980,7 +171653,10 @@ TRUE. line="40">`GtkVolumeButton` is a `GtkScaleButton` subclass tailored for volume control. -![An example GtkVolumeButton](volumebutton.png) +<picture> + <source srcset="volumebutton-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkVolumeButton" src="volumebutton.png"> +</picture> This widget will be removed in GTK 5 @@ -167993,7 +171669,7 @@ volume control. deprecated-version="4.10"> Creates a `GtkVolumeButton`. + line="200">Creates a `GtkVolumeButton`. The button has a range between 0.0 and 1.0, with a stepping of 0.02. Volume values can be obtained and modified using the functions from @@ -168004,7 +171680,7 @@ Volume values can be obtained and modified using the functions from a new `GtkVolumeButton` + line="209">a new `GtkVolumeButton` @@ -168017,7 +171693,7 @@ Volume values can be obtained and modified using the functions from default-value="TRUE"> Whether to use symbolic icons as the icons. + line="169">Whether to use symbolic icons as the icons. Note that if the symbolic icons are not available in your installed theme, then the normal (potentially colorful) icons will be used. @@ -168115,10 +171791,9 @@ theme, then the normal (potentially colorful) icons will be used. glib:type-struct="WidgetClass"> The base class for all widgets. + line="91">The base class for all widgets. -`GtkWidget` is the base class all widgets in GTK derive from. It manages the -widget lifecycle, layout, states and style. +It manages the widget lifecycle, layout, states and style. ### Height-for-width Geometry Management @@ -168155,13 +171830,13 @@ in the [enum@Gtk.SizeRequestMode] chosen by the toplevel. For example, when queried in the normal %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: First, the default minimum and natural width for each widget -in the interface will be computed using [id@gtk_widget_measure] with an +in the interface will be computed using [method@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1. Because the preferred widths for each widget depend on the preferred widths of their children, this information propagates up the hierarchy, and finally a minimum and natural width is determined for the entire toplevel. Next, the toplevel will use the minimum width to query for the -minimum height contextual to that width using [id@gtk_widget_measure] with an +minimum height contextual to that width using [method@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_VERTICAL and a for_size of the just computed width. This will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint @@ -168175,7 +171850,7 @@ will be recursively executed while widgets allocate their children. Each widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, -depending. In this way a `GtkWidget` will typically be requested its size +depending. In this way a widget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, `GtkWidget` caches a small number of results @@ -168252,7 +171927,7 @@ twice. GTK therefore does not allow this and will warn if you try to do it. Of course if you are getting the size request for another widget, such -as a child widget, you must use [id@gtk_widget_measure]; otherwise, you +as a child widget, you must use [method@Gtk.Widget.measure]; otherwise, you would not properly consider widget margins, [class@Gtk.SizeGroup], and so forth. @@ -168269,7 +171944,7 @@ both a minimum and natural size. If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was %GTK_ALIGN_FILL, but the selected baseline can be -found via [id@gtk_widget_get_baseline]. If the baseline has a +found via [method@Gtk.Widget.get_baseline]. If the baseline has a value other than -1 you need to align the widget such that the baseline appears at the position. @@ -168364,7 +172039,13 @@ Additionally, `<object>` tags can also be added before and after the initi which might be referenced by other widgets declared as children of the `<template>` tag. -An example of a template definition: +Since, unlike the `<object>` tag, the `<template>` tag does not contain an +“id” attribute, if you need to refer to the instance of the object itself that +the template will create, simply refer to the template class name in an +applicable element content. + +Here is an example of a template definition, which includes an example of +this in the `<signal>` tag: ```xml <interface> @@ -168434,7 +172115,7 @@ foo_widget_dispose (GObject *gobject) ``` You can access widgets defined in the template using the -[id@gtk_widget_get_template_child] function, but you will typically declare +[method@Gtk.Widget.get_template_child] function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call [method@Gtk.WidgetClass.bind_template_child_full] (or one of its wrapper macros @@ -168502,7 +172183,7 @@ foo_widget_class_init (FooWidgetClass *klass) gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked); } ``` - + @@ -168510,14 +172191,14 @@ foo_widget_class_init (FooWidgetClass *klass) c:identifier="gtk_widget_get_default_direction"> Obtains the current default reading direction. + line="7555">Obtains the default reading direction. See [func@Gtk.Widget.set_default_direction]. - + the current default direction. + line="7562">the current default direction @@ -168525,10 +172206,10 @@ See [func@Gtk.Widget.set_default_direction]. c:identifier="gtk_widget_set_default_direction"> Sets the default reading direction for widgets. + line="7520">Sets the default reading direction for widgets. See [method@Gtk.Widget.set_direction]. - + @@ -168536,13 +172217,18 @@ See [method@Gtk.Widget.set_direction]. the new default direction. This cannot be %GTK_TEXT_DIR_NONE. + line="7522">the new default direction, either [enum@Gtk.TextDirection.ltr] + or [enum@Gtk.TextDirection.rtl] - + Computes whether a container should give this + widget extra space when possible. + @@ -168561,40 +172247,46 @@ See [method@Gtk.Widget.set_direction]. Tests if the point at (@x, @y) is contained in @widget. + line="10301">Tests if a given point is contained in the widget. -The coordinates for (@x, @y) must be in widget coordinates, so +The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. - + %TRUE if @widget contains (@x, @y). + line="10312">true if @widget contains the point (x, y) the widget to query + line="10303">the widget to query X coordinate to test, relative to @widget's origin + line="10304">X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin + line="10305">Y coordinate to test, relative to @widget's origin - + Vfunc called when the CSS used by widget was changed. Widgets + should then discard their caches that depend on CSS and queue resizes or + redraws accordingly. The default implementation will take care of this for + all the default CSS properties, so implementations must chain up. + @@ -168608,7 +172300,11 @@ The coordinates for (@x, @y) must be in widget coordinates, so - + Signal emitted when the text direction of a + widget changes. + @@ -168622,7 +172318,10 @@ The coordinates for (@x, @y) must be in widget coordinates, so - + Vfunc for gtk_widget_child_focus() + @@ -168638,25 +172337,25 @@ The coordinates for (@x, @y) must be in widget coordinates, so Gets whether the widget prefers a height-for-width layout + line="573">Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities. - + The `GtkSizeRequestMode` preferred by @widget. + line="585">The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance + line="575">a `GtkWidget` instance @@ -168664,26 +172363,27 @@ allocation capabilities. Causes @widget to have the keyboard focus for the `GtkWindow` it's inside. + line="5025">Causes @widget to have the keyboard focus for the window +that it belongs to. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget -that is focusable, it will not take focus and %FALSE will be returned. +that is focusable, it will not take focus and false will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget -is allowed, should not have an effect, and return %TRUE. - +is allowed, should not have an effect, and return true. + %TRUE if focus is now inside @widget. + line="5039">true if focus is now inside @widget a `GtkWidget` + line="5027">a widget @@ -168694,11 +172394,11 @@ is allowed, should not have an effect, and return %TRUE. deprecated-version="4.10"> Reverses the effects of gtk_widget_show(). + line="2780">Reverses the effects of [method.Gtk.Widget.show]. This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead - + @@ -168706,7 +172406,7 @@ This is causing the widget to be hidden (invisible to the user). a `GtkWidget` + line="2782">a widget @@ -168714,53 +172414,54 @@ This is causing the widget to be hidden (invisible to the user). Emits the `::keynav-failed` signal on the widget. + line="7098">Emits the [signal@Gtk.Widget::keynav-failed] signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of -[method@Gtk.Widget.child_focus]. When %TRUE is returned, -stay in the widget, the failed keyboard navigation is OK +[method@Gtk.Widget.child_focus]. When true is returned, +stay in the widget, the failed keyboard navigation is ok and/or there is nowhere we can/should move the focus to. -When %FALSE is returned, the caller should continue with +When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns -%FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. -For the other values of `GtkDirectionType` it returns %TRUE. +false for [enum@Gtk.DirectionType.tab-forward] and +[enum@Gtk.DirectionType.tab-backward]. For the other values +of [enum@Gtk.DirectionType] it returns true. -Whenever the default handler returns %TRUE, it also calls +Whenever the default handler returns true, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. -A use case for providing an own implementation of ::keynav-failed +A use case for providing an own implementation of `::keynav-failed` (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. - + %TRUE if stopping keyboard navigation is fine, %FALSE + line="7132">true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent container(s). + navigation attempt in its parent widget a `GtkWidget` + line="7100">a widget direction of focus movement + line="7101">direction of focus movement @@ -168768,10 +172469,10 @@ interfaces that require entering license keys. Causes a widget to be mapped if it isn’t already. + line="2866">Causes a widget to be mapped if it isn’t already. This function is only for use in widget implementations. - + @@ -168779,7 +172480,7 @@ This function is only for use in widget implementations. a `GtkWidget` + line="2868">a widget @@ -168787,7 +172488,7 @@ This function is only for use in widget implementations. Measures @widget in the orientation @orientation and for the given @for_size. + line="452">Measures @widget in the orientation @orientation and for the given @for_size. As an example, if @orientation is %GTK_ORIENTATION_HORIZONTAL and @for_size is 300, this functions will compute the minimum and natural width of @widget @@ -168795,7 +172496,7 @@ if it is allocated at a height of 300 pixels. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for a more details on implementing `GtkWidgetClass.measure()`. - + @@ -168803,19 +172504,19 @@ a more details on implementing `GtkWidgetClass.measure()`. A `GtkWidget` instance + line="454">A `GtkWidget` instance the orientation to measure + line="455">the orientation to measure Size for the opposite of @orientation, i.e. + line="456">Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height @@ -168830,7 +172531,7 @@ a more details on implementing `GtkWidgetClass.measure()`. allow-none="1"> location to store the minimum size + line="461">location to store the minimum size allow-none="1"> location to store the natural size + line="462">location to store the natural size allow-none="1"> location to store the baseline + line="463">location to store the baseline position for the minimum size, or -1 to report no baseline @@ -168864,7 +172565,7 @@ a more details on implementing `GtkWidgetClass.measure()`. allow-none="1"> location to store the baseline + line="465">location to store the baseline position for the natural size, or -1 to report no baseline @@ -168873,33 +172574,34 @@ a more details on implementing `GtkWidgetClass.measure()`. Emits the ::mnemonic-activate signal. - -See [signal@Gtk.Widget::mnemonic-activate]. - + line="4584">Emits the [signal@Gtk.Widget::mnemonic-activate] signal. + %TRUE if the signal has been handled + line="4591">true if the signal has been handled a `GtkWidget` + line="4586">a widget %TRUE if there are other widgets with the same mnemonic + line="4587">true if there are other widgets with the same mnemonic - + Signal emitted when a change of focus is requested + @@ -168913,7 +172615,12 @@ See [signal@Gtk.Widget::mnemonic-activate]. - + Signal emitted when “has-tooltip” is %TRUE and the + hover timeout has expired with the cursor hovering “above” + widget; or emitted when widget got focus in keyboard mode. + @@ -168938,7 +172645,7 @@ See [signal@Gtk.Widget::mnemonic-activate]. Creates the GDK resources associated with a widget. + line="3437">Creates the GDK resources associated with a widget. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized @@ -168954,7 +172661,7 @@ isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signal@Gtk.Widget::realize]. - + @@ -168962,13 +172669,17 @@ called after the widget is realized automatically, such as a `GtkWidget` + line="3439">a widget - + Called when the widget gets added to a `GtkRoot` widget. Must + chain up + @@ -168981,12 +172692,12 @@ called after the widget is realized automatically, such as Set @child as the current focus child of @widget. + line="12499">Set the focus child of the widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [method@Gtk.Widget.grab_focus] on it. - + @@ -168994,7 +172705,7 @@ If you want a certain widget to get the input focus, call a `GtkWidget` + line="12501">a widget a direct child widget of @widget or %NULL - to unset the focus child of @widget + line="12502">a direct child widget of @widget + or `NULL` to unset the focus child @@ -169015,18 +172726,18 @@ If you want a certain widget to get the input focus, call deprecated-version="4.10"> Flags a widget to be displayed. + line="2709">Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. -When a toplevel container is shown, it is immediately realized and +When a toplevel widget is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their -toplevel container is realized and mapped. +toplevel widget is realized and mapped. Use [method@Gtk.Widget.set_visible] instead - + @@ -169034,13 +172745,17 @@ toplevel container is realized and mapped. a `GtkWidget` + line="2711">a widget - + Called to set the allocation, if the widget does + not have a layout manager. + @@ -169060,7 +172775,10 @@ toplevel container is realized and mapped. - + Vfunc called when a new snapshot of the widget has to be taken. + @@ -169074,7 +172792,11 @@ toplevel container is realized and mapped. - + Signal emitted when the widget state changes, + see gtk_widget_get_state_flags(). + @@ -169088,7 +172810,10 @@ toplevel container is realized and mapped. - + Emitted when a system setting was changed. Must chain up. + @@ -169104,10 +172829,10 @@ toplevel container is realized and mapped. Causes a widget to be unmapped if it’s currently mapped. + line="2902">Causes a widget to be unmapped if it’s currently mapped. This function is only for use in widget implementations. - + @@ -169115,7 +172840,7 @@ This function is only for use in widget implementations. a `GtkWidget` + line="2904">a widget @@ -169123,11 +172848,12 @@ This function is only for use in widget implementations. Causes a widget to be unrealized (frees all GDK resources -associated with the widget). + line="3495">Causes a widget to be unrealized. + +This frees all GDK resources associated with the widget. This function is only useful in widget implementations. - + @@ -169135,13 +172861,17 @@ This function is only useful in widget implementations. a `GtkWidget` + line="3497">a widget - + Called when the widget is about to be removed from its + `GtkRoot` widget. Must chain up + @@ -169155,9 +172885,9 @@ This function is only useful in widget implementations. c:identifier="gtk_widget_action_set_enabled"> Enable or disable an action installed with -gtk_widget_class_install_action(). - + line="13053">Enables or disables an action installed with +[method@Gtk.WidgetClass.install_action]. + @@ -169165,19 +172895,19 @@ gtk_widget_class_install_action(). a `GtkWidget` + line="13055">a widget action name, such as "clipboard.paste" + line="13056">action name, such as "clipboard.paste" whether the action is now enabled + line="13057">whether the action is now enabled @@ -169185,32 +172915,32 @@ gtk_widget_class_install_action(). For widgets that can be “activated” (buttons, menu items, etc.), -this function activates them. + line="4987">Activates the widget. The activation will emit the signal set using -[method@Gtk.WidgetClass.set_activate_signal] during class initialization. +[method@Gtk.WidgetClass.set_activate_signal] +during class initialization. Activation is what happens when you press <kbd>Enter</kbd> -on a widget during key navigation. +on a widget. -If you wish to handle the activation keybinding yourself, it is -recommended to use [method@Gtk.WidgetClass.add_shortcut] with an action -created with [ctor@Gtk.SignalAction.new]. +If you wish to handle the activation keybinding yourself, +it is recommended to use [method@Gtk.WidgetClass.add_shortcut] +with an action created with [ctor@Gtk.SignalAction.new]. -If @widget isn't activatable, the function returns %FALSE. - +If @widget is not activatable, the function returns false. + %TRUE if the widget was activatable + line="5006">true if the widget was activated a `GtkWidget` that’s activatable + line="4989">a widget that is activatable @@ -169221,30 +172951,31 @@ If @widget isn't activatable, the function returns %FALSE. introspectable="0"> Looks up the action in the action groups associated -with @widget and its ancestors, and activates it. + line="11758">Activates an action for the widget. + +The action is looked up in the action groups associated with +@widget and its ancestors. This is a wrapper around [method@Gtk.Widget.activate_action_variant] that constructs the @args variant according to @format_string. - + %TRUE if the action was activated, %FALSE if the action - does not exist + line="11773">true if the action was activated a `GtkWidget` + line="11760">a widget the name of the action to activate + line="11761">the name of the action to activate allow-none="1"> GVariant format string for arguments + line="11762">`GVariant` format string for arguments arguments, as given by format string + line="11763">arguments, as given by format string @@ -169269,8 +173000,10 @@ that constructs the @args variant according to @format_string. shadows="activate_action"> Looks up the action in the action groups associated with -@widget and its ancestors, and activates it. + line="11718">Activates an action for the widget. + +The action is looked up in the action groups associated with +@widget and its ancestors. If the action is in an action group added with [method@Gtk.Widget.insert_action_group], the @name is expected @@ -169278,26 +173011,25 @@ to be prefixed with the prefix that was used when the group was inserted. The arguments must match the actions expected parameter type, -as returned by `g_action_get_parameter_type()`. - +as returned by [method@Gio.Action.get_parameter_type]. + %TRUE if the action was activated, %FALSE if the - action does not exist. + line="11737">true if the action was activated a `GtkWidget` + line="11720">a widget the name of the action to activate + line="11721">the name of the action to activate allow-none="1"> parameters to use + line="11722">parameters to use @@ -169315,8 +173047,11 @@ as returned by `g_action_get_parameter_type()`. c:identifier="gtk_widget_activate_default"> Activates the `default.activate` action from @widget. - + line="11802">Activates the `default.activate` action for the widget. + +The action is looked up in the same was as for +[method@Gtk.Widget.activate_action]. + @@ -169324,7 +173059,7 @@ as returned by `g_action_get_parameter_type()`. a `GtkWidget` + line="11804">a widget @@ -169332,11 +173067,14 @@ as returned by `g_action_get_parameter_type()`. Adds @controller to @widget so that it will receive events. + line="11855">Adds an event controller to the widget. + +The event controllers of a widget handle the events that are +propagated to the widget. You will usually want to call this function right after creating any kind of [class@Gtk.EventController]. - + @@ -169344,13 +173082,13 @@ creating any kind of [class@Gtk.EventController]. a `GtkWidget` + line="11857">a widget a `GtkEventController` that hasn't been + line="11858">an event controller that hasn't been added to a widget yet @@ -169359,14 +173097,14 @@ creating any kind of [class@Gtk.EventController]. Adds a style class to @widget. + line="13144">Adds a style class to the widget. After calling this function, the widget’s style will match for @css_class, according to CSS matching rules. Use [method@Gtk.Widget.remove_css_class] to remove the style again. - + @@ -169374,14 +173112,13 @@ style again. a `GtkWidget` + line="13146">a widget The style class to add to @widget, without - the leading '.' used for notation of style classes + line="13147">style class to add to @widget, without the leading period @@ -169390,13 +173127,14 @@ style again. c:identifier="gtk_widget_add_mnemonic_label"> Adds a widget to the list of mnemonic labels for this widget. + line="9940">Adds a widget to the list of mnemonic labels for this widget. -See [method@Gtk.Widget.list_mnemonic_labels]. Note the -list of mnemonic labels for the widget is cleared when the -widget is destroyed, so the caller must make sure to update -its internal state at this point as well. - +See [method@Gtk.Widget.list_mnemonic_labels]. + +Note that the list of mnemonic labels for the widget is cleared +when the widget is destroyed, so the caller must make sure +to update its internal state at this point as well. + @@ -169404,13 +173142,13 @@ its internal state at this point as well. a `GtkWidget` + line="9942">a widget a `GtkWidget` that acts as a mnemonic label for @widget + line="9943">a widget that acts as a mnemonic label for @widget @@ -169419,42 +173157,44 @@ its internal state at this point as well. c:identifier="gtk_widget_add_tick_callback"> Queues an animation frame update and adds a callback to be called + line="3042">Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every -frame or every few frames. The tick callback does not automatically -imply a relayout or repaint. If you want a repaint or relayout, and -aren’t changing widget properties that would trigger that (for example, -changing the text of a `GtkLabel`), then you will have to call -[method@Gtk.Widget.queue_resize] or [method@Gtk.Widget.queue_draw] -yourself. +frame or every few frames. + +The tick callback does not automatically imply a relayout or repaint. +If you want a repaint or relayout, and aren’t changing widget properties +that would trigger that (for example, changing the text of a label), +then you will have to call [method@Gtk.Widget.queue_resize] or +[method@Gtk.Widget.queue_draw] yourself. [method@Gdk.FrameClock.get_frame_time] should generally be used for timing continuous animations and -[method@Gdk.FrameTimings.get_predicted_presentation_time] if you are -trying to display isolated frames at particular times. +[method@Gdk.FrameTimings.get_predicted_presentation_time] should be +used if you are trying to display isolated frames at particular times. This is a more convenient alternative to connecting directly to the -[signal@Gdk.FrameClock::update] signal of `GdkFrameClock`, since you -don't have to worry about when a `GdkFrameClock` is assigned to a widget. - +[signal@Gdk.FrameClock::update] signal of the frame clock, since you +don't have to worry about when a frame clock is assigned to a widget. + +To remove a tick callback, pass the ID that is returned by this function +to [method@Gtk.Widget.remove_tick_callback]. + an id for the connection of this callback. Remove the callback - by passing the id returned from this function to - [method@Gtk.Widget.remove_tick_callback] + line="3077">an ID for this callback a `GtkWidget` + line="3044">a widget destroy="2"> function to call for updating animations + line="3045">function + to call for updating animations allow-none="1"> data to pass to @callback + line="3047">data to pass to @callback function to call to free @user_data when the callback is removed. + line="3048">function to call to free @user_data @@ -169487,17 +173228,18 @@ don't have to worry about when a `GdkFrameClock` is assigned to a widget. This function is only used by `GtkWidget` subclasses, to -assign a size, position and (optionally) baseline to their -child widgets. + line="4039">Assigns size, position, (optionally) a baseline and transform +to a child widget. In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size. +This function is only used by widget implementations. + For a version that does not take a transform, see [method@Gtk.Widget.size_allocate]. - + @@ -169505,25 +173247,25 @@ For a version that does not take a transform, see A `GtkWidget` + line="4041">a widget New width of @widget + line="4042">new width New height of @widget + line="4043">new height New baseline of @widget, or -1 + line="4044">new baseline, or -1 Transformation to be applied to @widget + line="4045">transformation to be applied @@ -169540,44 +173282,44 @@ For a version that does not take a transform, see Called by widgets as the user moves around the window using + line="7051">Called by widgets as the user moves around the window using keyboard shortcuts. -The @direction argument indicates what kind of motion is taking place (up, -down, left, right, tab forward, tab backward). +The @direction argument indicates what kind of motion is taking +place (up, down, left, right, tab forward, tab backward). -This function calls the [vfunc@Gtk.Widget.focus] virtual function; widgets -can override the virtual function in order to implement appropriate focus -behavior. +This function calls the [vfunc@Gtk.Widget.focus] virtual function; +widgets can override the virtual function in order to implement +appropriate focus behavior. -The default `focus()` virtual function for a widget should return `TRUE` if -moving in @direction left the focus on a focusable location inside that -widget, and `FALSE` if moving in @direction moved the focus outside the -widget. When returning `TRUE`, widgets normally call [method@Gtk.Widget.grab_focus] -to place the focus accordingly; when returning `FALSE`, they don’t modify -the current focus location. +The default `focus()` virtual function for a widget should return +true if moving in @direction left the focus on a focusable location +inside that widget, and false if moving in @direction moved the focus +outside the widget. When returning true, widgets normally call +[method@Gtk.Widget.grab_focus] to place the focus accordingly; +when returning false, they don’t modify the current focus location. This function is used by custom widget implementations; if you're writing an app, you’d use [method@Gtk.Widget.grab_focus] to move the focus to a particular widget. - + %TRUE if focus ended up inside @widget + line="7077">true if focus ended up inside @widget a `GtkWidget` + line="7053">a widget direction of focus movement + line="7054">direction of focus movement @@ -169585,36 +173327,36 @@ the focus to a particular widget. Computes the bounds for @widget in the coordinate space of @target. + line="10549">Computes the bounds for @widget in the coordinate space of @target. The bounds of widget are (the bounding box of) the region that it is expected to draw in. See the [coordinate system](coordinates.html) overview to learn more. -If the operation is successful, %TRUE is returned. If @widget has no +If the operation is successful, true is returned. If @widget has no bounds or the bounds cannot be expressed in @target's coordinate space -(for example if both widgets are in different windows), %FALSE is +(for example if both widgets are in different windows), false is returned and @bounds is set to the zero rectangle. It is valid for @widget and @target to be the same widget. - + %TRUE if the bounds could be computed + line="10568">true if the bounds could be computed the `GtkWidget` to query + line="10551">the widget to query the `GtkWidget` + line="10552">the target widget transfer-ownership="none"> the rectangle taking the bounds + line="10553">the rectangle taking the bounds @@ -169631,10 +173373,10 @@ It is valid for @widget and @target to be the same widget. Computes whether a container should give this widget + line="8323">Computes whether a parent widget should give this widget extra space when possible. -Containers should check this, rather than looking at +Widgets with children should check this, rather than looking at [method@Gtk.Widget.get_hexpand] or [method@Gtk.Widget.get_vexpand]. This function already checks whether the widget is visible, so @@ -169644,24 +173386,24 @@ widgets are not expanded. The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do. - + whether widget tree rooted here should be expanded + line="8342">whether widget tree rooted here should be expanded the widget + line="8325">a widget expand direction + line="8326">expand direction @@ -169669,36 +173411,37 @@ the widget may expand if some of its children do. Translates the given @point in @widget's coordinates to coordinates -relative to @target’s coordinate system. + line="4368">Translates the given @point in @widget's coordinates to coordinates +in @target’s coordinate system. In order to perform this operation, both widgets must share a -common ancestor. - +a common ancestor. If that is not the case, @out_point is set +to (0, 0) and false is returned. + %TRUE if the point could be determined, %FALSE on failure. - In this case, 0 is stored in @out_point. + line="4383">true if @src_widget and @dest_widget have a common + ancestor, false otherwise the `GtkWidget` to query + line="4370">the widget to query the `GtkWidget` to transform into + line="4371">the widget to transform into a point in @widget's coordinate system + line="4372">a point in @widget's coordinate system transfer-ownership="none"> Set to the corresponding coordinates in + line="4373">set to the corresponding coordinates in @target's coordinate system @@ -169717,7 +173460,7 @@ common ancestor. c:identifier="gtk_widget_compute_transform"> Computes a matrix suitable to describe a transformation from + line="10468">Computes a matrix suitable to describe a transformation from @widget's coordinate system into @target's coordinate system. The transform can not be computed in certain cases, for example @@ -169726,24 +173469,24 @@ case @out_transform gets set to the identity matrix. To learn more about widget coordinate systems, see the coordinate system [overview](coordinates.html). - + %TRUE if the transform could be computed, %FALSE otherwise + line="10485">true if the transform could be computed a `GtkWidget` + line="10470">a widget the target widget that the matrix will transform to + line="10471">the target widget that the matrix will transform to transfer-ownership="none"> location to + line="10472">location to store the final transformation @@ -169761,34 +173504,34 @@ system [overview](coordinates.html). Tests if the point at (@x, @y) is contained in @widget. + line="10301">Tests if a given point is contained in the widget. -The coordinates for (@x, @y) must be in widget coordinates, so +The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. - + %TRUE if @widget contains (@x, @y). + line="10312">true if @widget contains the point (x, y) the widget to query + line="10303">the widget to query X coordinate to test, relative to @widget's origin + line="10304">X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin + line="10305">Y coordinate to test, relative to @widget's origin @@ -169797,23 +173540,24 @@ The coordinates for (@x, @y) must be in widget coordinates, so c:identifier="gtk_widget_create_pango_context"> Creates a new `PangoContext` with the appropriate font map, -font options, font description, and base direction for drawing -text for this widget. + line="6817">Creates a new `PangoContext` that is configured for the widget. + +The `PangoContext` will have the appropriate font map, +font options, font description, and base direction set. See also [method@Gtk.Widget.get_pango_context]. - + the new `PangoContext` + line="6828">the new `PangoContext` a `GtkWidget` + line="6819">a widget @@ -169822,26 +173566,27 @@ See also [method@Gtk.Widget.get_pango_context]. c:identifier="gtk_widget_create_pango_layout"> Creates a new `PangoLayout` with the appropriate font map, -font description, and base direction for drawing text for -this widget. + line="6844">Creates a new `PangoLayout` that is configured for the widget. + +The `PangoLayout` will have the appropriate font map, +font description, and base direction set. If you keep a `PangoLayout` created in this way around, -you need to re-create it when the widget `PangoContext` +you need to re-create it when the widgets `PangoContext` is replaced. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. - + the new `PangoLayout` + line="6859">the new `PangoLayout` a `GtkWidget` + line="6846">a widget allow-none="1"> text to set on the layout + line="6847">text to set on the layout @@ -169860,16 +173605,16 @@ of the [property@Gtk.Widget:root] property on the widget. version="4.8"> Clears the template children for the given widget. + line="11385">Clears the template children for the widget. -This function is the opposite of [method@Gtk.Widget.init_template], and -it is used to clear all the template children from a widget instance. -If you bound a template child to a field in the instance structure, or -in the instance private data structure, the field will be set to `NULL` -after this function returns. +This function is the opposite of [method@Gtk.Widget.init_template], +and it is used to clear all the template children from a widget +instance. If you bound a template child to a field in the instance +structure, or in the instance private data structure, the field will +be set to `NULL` after this function returns. You should call this function inside the `GObjectClass.dispose()` -implementation of any widget that called `gtk_widget_init_template()`. +implementation of any widget that called [method@Gtk.Widget.init_template]. Typically, you will want to call this function last, right before chaining up to the parent type's dispose implementation, e.g. @@ -169885,7 +173630,7 @@ some_widget_dispose (GObject *gobject) G_OBJECT_CLASS (some_widget_parent_class)->dispose (gobject); } ``` - + @@ -169893,13 +173638,13 @@ some_widget_dispose (GObject *gobject) the widget with a template + line="11387">the widget with a template the type of the widget to finalize the template for + line="11388">the type of the widget to finalize the template for @@ -169913,14 +173658,14 @@ some_widget_dispose (GObject *gobject) %TRUE if the drag threshold has been passed. + line="812">true if the drag threshold has been passed a `GtkWidget` + line="804">a widget @@ -169952,15 +173697,15 @@ some_widget_dispose (GObject *gobject) Notifies the user about an input-related error on this widget. + line="7150">Notifies the user about an input-related error on the widget. -If the [property@Gtk.Settings:gtk-error-bell] setting is %TRUE, +If the [property@Gtk.Settings:gtk-error-bell] setting is true, it calls [method@Gdk.Surface.beep], otherwise it does nothing. Note that the effect of [method@Gdk.Surface.beep] can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used. - + @@ -169968,7 +173713,7 @@ environment or window manager that is used. a `GtkWidget` + line="7152">a widget @@ -169979,24 +173724,24 @@ environment or window manager that is used. deprecated-version="4.12"> Returns the baseline that has currently been allocated to @widget. + line="10646">Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers for the `GtkWidget`Class.snapshot() function, and when allocating child widgets in `GtkWidget`Class.size_allocate(). Use [method@Gtk.Widget.get_baseline] instead - + the baseline of the @widget, or -1 if none + line="10656">the baseline of the @widget, or -1 if none the widget to query + line="10648">the widget to query @@ -170007,23 +173752,23 @@ child widgets in `GtkWidget`Class.size_allocate(). deprecated-version="4.12"> Returns the height that has currently been allocated to @widget. + line="10621">Returns the height that has currently been allocated to the widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). Use [method@Gtk.Widget.get_height] instead - + the height of the @widget + line="10630">the height of the @widget the widget to query + line="10623">the widget to query @@ -170034,23 +173779,23 @@ system [overview](coordinates.html). deprecated-version="4.12"> Returns the width that has currently been allocated to @widget. + line="10596">Returns the width that has currently been allocated to the widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). Use [method@Gtk.Widget.get_width] instead - + the width of the @widget + line="10605">the width of the @widget the widget to query + line="10598">the widget to query @@ -170061,9 +173806,9 @@ system [overview](coordinates.html). deprecated-version="4.12"> Retrieves the widget’s allocation. + line="10251">Retrieves the widget’s allocation. -Note, when implementing a layout container: a widget’s allocation +Note, when implementing a layout widget: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent typically calls [method@Gtk.Widget.size_allocate] with an allocation, and that allocation is then adjusted (to handle margin @@ -170073,12 +173818,12 @@ was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the [method@Gtk.Widget.size_allocate] allocation, however. -So a layout container is guaranteed that its children stay inside +So a layout widget is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the -container assigned. +widget assigned. Use [method@Gtk.Widget.compute_bounds], [method@Gtk.Widget.get_width] or [method@Gtk.Widget.get_height] instead. - + @@ -170086,7 +173831,7 @@ container assigned. a `GtkWidget` + line="10253">a widget transfer-ownership="none"> a pointer to a `GtkAllocation` to copy to + line="10254">a pointer to a `GtkAllocation` to copy to @@ -170103,7 +173848,7 @@ container assigned. Gets the first ancestor of @widget with type @widget_type. + line="7318">Gets the first ancestor of the widget with type @widget_type. For example, `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets the first `GtkBox` that’s an ancestor of @widget. No @@ -170112,24 +173857,24 @@ not be unreferenced. Note that unlike [method@Gtk.Widget.is_ancestor], this function considers @widget to be an ancestor of itself. - + the ancestor widget + line="7333">the ancestor widget a `GtkWidget` + line="7320">a widget ancestor type + line="7321">ancestor type @@ -170139,23 +173884,23 @@ considers @widget to be an ancestor of itself. version="4.12"> Returns the baseline that has currently been allocated to @widget. + line="10666">Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers -for the `GtkWidget`Class.snapshot() function, and when allocating -child widgets in `GtkWidget`Class.size_allocate(). - +for the `GtkWidgetClass.snapshot()` function, and when allocating +child widgets in `GtkWidgetClass.size_allocate()`. + the baseline of the @widget, or -1 if none + line="10676">the baseline of the @widget, or -1 if none the widget to query + line="10668">the widget to query @@ -170163,25 +173908,24 @@ child widgets in `GtkWidget`Class.size_allocate(). - Determines whether the input focus can enter @widget or any + line="5328">Determines whether the input focus can enter the widget or any of its children. -See [method@Gtk.Widget.set_focusable]. - +See [method@Gtk.Widget.set_can_focus]. + %TRUE if the input focus can enter @widget, %FALSE otherwise + line="5337">true if the input focus can enter @widget a `GtkWidget` + line="5330">a widget @@ -170189,22 +173933,21 @@ See [method@Gtk.Widget.set_focusable]. - Queries whether @widget can be the target of pointer events. - + line="12667">Queries whether the widget can be the target of pointer events. + %TRUE if @widget can receive pointer events + line="12673">true if @widget can receive pointer events a `GtkWidget` + line="12669">a widget @@ -170213,25 +173956,25 @@ See [method@Gtk.Widget.set_focusable]. c:identifier="gtk_widget_get_child_visible"> Gets the value set with gtk_widget_set_child_visible(). + line="6946">Gets the value set with [method@Gtk.Widget.set_child_visible]. If you feel a need to use this function, your code probably needs reorganization. -This function is only useful for container implementations +This function is only useful for widget implementations and should never be called by an application. - + %TRUE if the widget is mapped with the parent. + line="6958">true if the widget is mapped with the parent a `GtkWidget` + line="6948">a widget @@ -170239,25 +173982,25 @@ and should never be called by an application. Gets the clipboard object for @widget. + line="9863">Gets the clipboard object for the widget. This is a utility function to get the clipboard object for the -`GdkDisplay` that @widget is using. +display that @widget is using. Note that this function always works, even when @widget is not realized yet. - + the appropriate clipboard object + line="9875">the appropriate clipboard object a `GtkWidget` + line="9865">a widget @@ -170267,13 +174010,12 @@ realized yet. version="4.10"> Gets the current foreground color for the widget’s -CSS style. + line="13280">Gets the current foreground color for the widget’s style. This function should only be used in snapshot -implementations that need to do custom -drawing with the foreground color. - +implementations that need to do custom drawing +with the foreground color. + @@ -170281,7 +174023,7 @@ drawing with the foreground color. a `GtkWidget` + line="13282">a widget transfer-ownership="none"> return location for the color + line="13283">return location for the color @@ -170298,17 +174040,15 @@ drawing with the foreground color. - Returns the list of style classes applied to @widget. - + line="13229">Returns the list of style classes applied to the widget. + a %NULL-terminated list of - css classes currently applied to @widget. The returned - list must freed using g_strfreev(). + line="13235">a `NULL`-terminated list of + css classes currently applied to @widget @@ -170317,7 +174057,7 @@ drawing with the foreground color. a `GtkWidget` + line="13231">a widget @@ -170325,22 +174065,21 @@ drawing with the foreground color. - Returns the CSS name that is used for @self. - + line="13126">Returns the CSS name of the widget. + the CSS name + line="13132">the CSS name a `GtkWidget` + line="13128">a widget @@ -170348,25 +174087,24 @@ drawing with the foreground color. - Queries the cursor set on @widget. + line="12622">Gets the cursor set on the widget. See [method@Gtk.Widget.set_cursor] for details. - + the cursor - currently in use or %NULL if the cursor is inherited + line="12630">the cursor + that is set on @widget a `GtkWidget` + line="12624">a widget @@ -170374,21 +174112,21 @@ See [method@Gtk.Widget.set_cursor] for details. Gets the reading direction for a particular widget. + line="7475">Gets the reading direction for the widget. See [method@Gtk.Widget.set_direction]. - + the reading direction for the widget. + line="7483">the reading direction for the widget a `GtkWidget` + line="7477">a widget @@ -170396,28 +174134,26 @@ See [method@Gtk.Widget.set_direction]. Get the `GdkDisplay` for the toplevel window associated with -this widget. + line="7028">Get the display for the window that the widget belongs to. This function can only be called after the widget has been -added to a widget hierarchy with a `GtkWindow` at the top. +added to a widget hierarchy with a `GtkRoot` at the top. -In general, you should only create display specific +In general, you should only create display-specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. - + the `GdkDisplay` for the toplevel - for this widget. + line="7041">the display for this widget a `GtkWidget` + line="7030">a widget @@ -170425,21 +174161,21 @@ free those resources when the widget is unrealized. Returns the widget’s first child. + line="12249">Returns the widget’s first child. -This API is primarily meant for widget implementations. - +This function is primarily meant for widget implementations. + The widget's first child + line="12257">the widget's first child a `GtkWidget` + line="12251">a widget @@ -170447,12 +174183,12 @@ This API is primarily meant for widget implementations. Returns the current focus child of @widget. - + line="12535">Returns the focus child of the widget. + The current focus + line="12541">the current focus child of @widget @@ -170460,7 +174196,7 @@ This API is primarily meant for widget implementations. a `GtkWidget` + line="12537">a widget @@ -170468,18 +174204,17 @@ This API is primarily meant for widget implementations. - Returns whether the widget should grab focus when it is clicked + line="5529">Returns whether the widget should grab focus when it is clicked with the mouse. See [method@Gtk.Widget.set_focus_on_click]. - + %TRUE if the widget should grab focus when it is + line="5538">true if the widget should grab focus when it is clicked with the mouse @@ -170487,7 +174222,7 @@ See [method@Gtk.Widget.set_focus_on_click]. a `GtkWidget` + line="5531">a widget @@ -170495,24 +174230,23 @@ See [method@Gtk.Widget.set_focus_on_click]. - Determines whether @widget can own the input focus. + line="5389">Determines whether the widget can own the input focus. See [method@Gtk.Widget.set_focusable]. - + %TRUE if @widget can own the input focus, %FALSE otherwise + line="5397">true if @widget can own the input focus a `GtkWidget` + line="5391">a widget @@ -170520,45 +174254,46 @@ See [method@Gtk.Widget.set_focusable]. Gets the font map of @widget. + line="6799">Gets the font map of the widget. See [method@Gtk.Widget.set_font_map]. - + A `PangoFontMap` + line="6807">the font map of @widget a `GtkWidget` + line="6801">a widget + c:identifier="gtk_widget_get_font_options" + deprecated="1" + deprecated-version="4.16"> Returns the `cairo_font_options_t` of widget. + line="6732">Returns the `cairo_font_options_t` of the widget. Seee [method@Gtk.Widget.set_font_options]. - + the `cairo_font_options_t` - of widget + line="6740">the `cairo_font_options_t` of widget a `GtkWidget` + line="6734">a widget @@ -170566,7 +174301,7 @@ Seee [method@Gtk.Widget.set_font_options]. Obtains the frame clock for a widget. + line="3674">Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame @@ -170577,29 +174312,29 @@ the start of the animation with an initial value from by calling [method@Gdk.FrameClock.get_frame_time] again during each repaint. [method@Gdk.FrameClock.request_phase] will result in a new frame on the -clock, but won’t necessarily repaint any widgets. To repaint a -widget, you have to use [method@Gtk.Widget.queue_draw] which invalidates -the widget (thus scheduling it to receive a draw on the next -frame). gtk_widget_queue_draw() will also end up requesting a frame +clock, but won’t necessarily repaint any widgets. To repaint a widget, +you have to use [method@Gtk.Widget.queue_draw] which invalidates the +widget (thus scheduling it to receive a draw on the next frame). +[method@Gtk.Widget.queue_draw] will also end up requesting a frame on the appropriate frame clock. -A widget’s frame clock will not change while the widget is -mapped. Reparenting a widget (which implies a temporary unmap) can -change the widget’s frame clock. +A widget’s frame clock will not change while the widget is mapped. +Reparenting a widget (which implies a temporary unmap) can change +the widget’s frame clock. Unrealized widgets do not have a frame clock. - + a `GdkFrameClock` + line="3701">the frame clock a `GtkWidget` + line="3676">a widget @@ -170607,28 +174342,27 @@ Unrealized widgets do not have a frame clock. - Gets the horizontal alignment of @widget. + line="9599">Gets the horizontal alignment of the widget. For backwards compatibility reasons this method will never return one of the baseline alignments, but instead it will convert it to -`GTK_ALIGN_FILL` or `GTK_ALIGN_CENTER`. +[enum@Gtk.Align.fill] or [enum@Gtk.Align.center]. Baselines are not supported for horizontal alignment. - + the horizontal alignment of @widget + line="9611">the horizontal alignment of @widget a `GtkWidget` + line="9601">a widget @@ -170636,22 +174370,21 @@ Baselines are not supported for horizontal alignment. - Returns the current value of the `has-tooltip` property. - + line="10233">Returns the current value of the `has-tooltip` property. + current value of `has-tooltip` on @widget. + line="10239">current value of `has-tooltip` on @widget a `GtkWidget` + line="10235">a widget @@ -170659,7 +174392,7 @@ Baselines are not supported for horizontal alignment. Returns the content height of the widget. + line="12710">Returns the content height of the widget. This function returns the height passed to its size-allocate implementation, which is the height you @@ -170669,18 +174402,18 @@ For pointer events, see [method@Gtk.Widget.contains]. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). - + The height of @widget + line="12725">The height of @widget a `GtkWidget` + line="12712">a widget @@ -170688,37 +174421,35 @@ system [overview](coordinates.html). - Gets whether the widget would like any available extra horizontal + line="8442">Gets whether the widget would like any available extra horizontal space. -When a user resizes a `GtkWindow`, widgets with expand=TRUE -generally receive the extra space. For example, a list or -scrollable area or document in your window would often be set to -expand. +When a user resizes a window, widgets with expand set to true generally +receive the extra space. For example, a list or scrollable area +or document in your window would often be set to expand. -Containers should use [method@Gtk.Widget.compute_expand] rather -than this function, to see whether a widget, or any of its children, +Widgets with children should use [method@Gtk.Widget.compute_expand] +rather than this function, to see whether any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also. This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand. - + whether hexpand flag is set + line="8462">whether hexpand flag is set the widget + line="8444">a widget @@ -170726,11 +174457,9 @@ wants to expand. - Gets whether gtk_widget_set_hexpand() has been used -to explicitly set the expand flag on this widget. + line="8515">Gets whether the `hexpand` flag has been explicitly set. If [property@Gtk.Widget:hexpand] property is set, then it overrides any computed expand value based on child widgets. @@ -170739,18 +174468,18 @@ whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. - + whether hexpand has been explicitly set + line="8529">whether hexpand has been explicitly set the widget + line="8517">a widget @@ -170758,21 +174487,21 @@ for completeness and consistency. Returns the widget’s last child. + line="12269">Returns the widget’s last child. -This API is primarily meant for widget implementations. - +This function is primarily meant for widget implementations. + The widget's last child + line="12277">the widget's last child a `GtkWidget` + line="12271">a widget @@ -170780,24 +174509,43 @@ This API is primarily meant for widget implementations. - Retrieves the layout manager used by @widget. + line="12858">Retrieves the layout manager of the widget. See [method@Gtk.Widget.set_layout_manager]. - + a `GtkLayoutManager` + line="12866">the layout manager of @widget a `GtkWidget` + line="12860">a widget + + + + + + Gets the value of the [property@Gtk.Widget:limit-events] property. + + + + + + + a `GtkWidget` @@ -170805,19 +174553,19 @@ See [method@Gtk.Widget.set_layout_manager]. Whether the widget is mapped. - + line="5978">Returns whether the widget is mapped. + %TRUE if the widget is mapped, %FALSE otherwise. + line="5984">true if the widget is mapped a `GtkWidget` + line="5980">a widget @@ -170825,22 +174573,21 @@ See [method@Gtk.Widget.set_layout_manager]. - Gets the bottom margin of @widget. - + line="9821">Gets the bottom margin of the widget. + The bottom margin of @widget + line="9827">The bottom margin of @widget a `GtkWidget` + line="9823">a widget @@ -170848,22 +174595,21 @@ See [method@Gtk.Widget.set_layout_manager]. - Gets the end margin of @widget. - + line="9735">Gets the end margin of the widget. + The end margin of @widget + line="9741">The end margin of @widget a `GtkWidget` + line="9737">a widget @@ -170871,22 +174617,21 @@ See [method@Gtk.Widget.set_layout_manager]. - Gets the start margin of @widget. - + line="9691">Gets the start margin of the widget. + The start margin of @widget + line="9697">The start margin of @widget a `GtkWidget` + line="9693">a widget @@ -170894,22 +174639,21 @@ See [method@Gtk.Widget.set_layout_manager]. - Gets the top margin of @widget. - + line="9779">Gets the top margin of the widget. + The top margin of @widget + line="9785">The top margin of @widget a `GtkWidget` + line="9781">a widget @@ -170917,25 +174661,23 @@ See [method@Gtk.Widget.set_layout_manager]. - Retrieves the name of a widget. + line="5695">Retrieves the name of a widget. See [method@Gtk.Widget.set_name] for the significance of widget names. - + name of the widget. This string is owned by GTK and - should not be modified or freed + line="5703">name of the widget a `GtkWidget` + line="5697">a widget @@ -170943,24 +174685,24 @@ See [method@Gtk.Widget.set_name] for the significance of widget names. Returns the nearest `GtkNative` ancestor of @widget. + line="6327">Returns the nearest `GtkNative` ancestor of the widget. -This function will return %NULL if the widget is not +This function will return `NULL` if the widget is not contained inside a widget tree with a native ancestor. `GtkNative` widgets will return themselves here. - + the `GtkNative` ancestor of @widget + line="6338">the `GtkNative` ancestor of @widget a `GtkWidget` + line="6329">a widget @@ -170969,21 +174711,21 @@ contained inside a widget tree with a native ancestor. c:identifier="gtk_widget_get_next_sibling"> Returns the widget’s next sibling. + line="12289">Returns the widget’s next sibling. -This API is primarily meant for widget implementations. - +This function is primarily meant for widget implementations. + The widget's next sibling + line="12297">the widget's next sibling a `GtkWidget` + line="12291">a widget @@ -170991,24 +174733,23 @@ This API is primarily meant for widget implementations. - #Fetches the requested opacity for this widget. + line="10752">Fetches the requested opacity for the widget. See [method@Gtk.Widget.set_opacity]. - + the requested opacity for this widget. + line="10760">the requested opacity for this widget a `GtkWidget` + line="10754">a widget @@ -171016,22 +174757,21 @@ See [method@Gtk.Widget.set_opacity]. - Returns the widget’s overflow value. - + line="10805">Returns the widget’s overflow value. + The widget's overflow. + line="10811">The widget's overflow value a `GtkWidget` + line="10807">a widget @@ -171040,8 +174780,10 @@ See [method@Gtk.Widget.set_opacity]. c:identifier="gtk_widget_get_pango_context"> Gets a `PangoContext` with the appropriate font map, font description, -and base direction for this widget. + line="6534">Gets a `PangoContext` that is configured for the widget. + +The `PangoContext` will have the appropriate font map, font description, +and base direction set. Unlike the context returned by [method@Gtk.Widget.create_pango_context], this context is owned by the widget (it can be used until the screen @@ -171049,18 +174791,18 @@ for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. - + the `PangoContext` for the widget. + line="6550">the `PangoContext` for the widget a `GtkWidget` + line="6536">a widget @@ -171068,22 +174810,21 @@ This can be tracked by listening to changes of the - Returns the parent widget of @widget. - + line="6288">Returns the parent widget of the widget. + the parent widget of @widget + line="6294">the parent widget of @widget a `GtkWidget` + line="6290">a widget @@ -171092,7 +174833,7 @@ This can be tracked by listening to changes of the c:identifier="gtk_widget_get_preferred_size"> Retrieves the minimum and natural size of a widget, taking + line="655">Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management. This is used to retrieve a suitable size by container widgets which do @@ -171105,8 +174846,8 @@ widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width. -Use [id@gtk_widget_measure] if you want to support baseline alignment. - +Use [method@Gtk.Widget.measure] if you want to support baseline alignment. + @@ -171114,7 +174855,7 @@ Use [id@gtk_widget_measure] if you want to support baseline alignment. a `GtkWidget` instance + line="657">a `GtkWidget` instance allow-none="1"> location for storing the minimum size + line="658">location for storing the minimum size allow-none="1"> location for storing the natural size + line="659">location for storing the natural size @@ -171145,21 +174886,21 @@ Use [id@gtk_widget_measure] if you want to support baseline alignment. c:identifier="gtk_widget_get_prev_sibling"> Returns the widget’s previous sibling. + line="12309">Returns the widget’s previous sibling. -This API is primarily meant for widget implementations. - +This function is primarily meant for widget implementations. + The widget's previous sibling + line="12317">the widget's previous sibling a `GtkWidget` + line="12311">a widget @@ -171168,25 +174909,25 @@ This API is primarily meant for widget implementations. c:identifier="gtk_widget_get_primary_clipboard"> Gets the primary clipboard of @widget. + line="9885">Gets the primary clipboard of the widget. This is a utility function to get the primary clipboard object -for the `GdkDisplay` that @widget is using. +for the display that @widget is using. Note that this function always works, even when @widget is not realized yet. - + the appropriate clipboard object + line="9897">the appropriate clipboard object a `GtkWidget` + line="9887">a widget @@ -171194,19 +174935,19 @@ realized yet. Determines whether @widget is realized. - + line="5960">Determines whether the widget is realized. + %TRUE if @widget is realized, %FALSE otherwise + line="5966">true if @widget is realized a `GtkWidget` + line="5962">a widget @@ -171214,28 +174955,25 @@ realized yet. - Determines whether @widget is always treated as the default widget + line="5610">Determines whether the widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See [method@Gtk.Widget.set_receives_default]. - + %TRUE if @widget acts as the default widget when focused, - %FALSE otherwise + line="5620">true if @widget acts as the default widget when focused a `GtkWidget` + line="5612">a widget @@ -171244,25 +174982,25 @@ See [method@Gtk.Widget.set_receives_default]. c:identifier="gtk_widget_get_request_mode"> Gets whether the widget prefers a height-for-width layout + line="573">Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities. - + The `GtkSizeRequestMode` preferred by @widget. + line="585">The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance + line="575">a `GtkWidget` instance @@ -171270,27 +175008,26 @@ allocation capabilities. - Returns the `GtkRoot` widget of @widget. + line="6306">Returns the `GtkRoot` widget of the widget. -This function will return %NULL if the widget is not contained +This function will return `NULL` if the widget is not contained inside a widget tree with a root widget. `GtkRoot` widgets will return themselves here. - + the root widget of @widget + line="6317">the root widget of @widget a `GtkWidget` + line="6308">a widget @@ -171298,28 +175035,33 @@ inside a widget tree with a root widget. - Retrieves the internal scale factor that maps from window + line="6989">Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2). -See [method@Gdk.Surface.get_scale_factor]. - +See [method@Gdk.Surface.get_scale_factor]. + +Note that modern systems may support *fractional* scaling, +where the scale factor is not an integer. On such systems, +this function will return the next higher integer value, +but you probably want to use [method@Gdk.Surface.get_scale] +to get the fractional scale value. + the scale factor for @widget + line="7007">the scale factor for @widget a `GtkWidget` + line="6991">a widget @@ -171327,10 +175069,9 @@ See [method@Gdk.Surface.get_scale_factor]. - Returns the widget’s sensitivity. + line="6061">Returns the widget’s sensitivity. This function returns the value that has been set using [method@Gtk.Widget.set_sensitive]). @@ -171338,18 +175079,18 @@ This function returns the value that has been set using The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See [method@Gtk.Widget.is_sensitive]. - + %TRUE if the widget is sensitive + line="6074">true if the widget is sensitive a `GtkWidget` + line="6063">a widget @@ -171357,24 +175098,24 @@ See [method@Gtk.Widget.is_sensitive]. Gets the settings object holding the settings used for this widget. + line="7351">Gets the settings object holding the settings used for the widget. Note that this function can only be called when the `GtkWidget` is attached to a toplevel, since the settings object is specific -to a particular `GdkDisplay`. If you want to monitor the widget for +to a particular display. If you want to monitor the widget for changes in its settings, connect to the `notify::display` signal. - + the relevant `GtkSettings` object + line="7362">the relevant settings object a `GtkWidget` + line="7353">a widget @@ -171382,36 +175123,36 @@ changes in its settings, connect to the `notify::display` signal. Returns the content width or height of the widget. + line="12737">Returns the content width or height of the widget. Which dimension is returned depends on @orientation. This is equivalent to calling [method@Gtk.Widget.get_width] -for %GTK_ORIENTATION_HORIZONTAL or [method@Gtk.Widget.get_height] -for %GTK_ORIENTATION_VERTICAL, but can be used when +for [enum@Gtk.Orientation.horizontal] or [method@Gtk.Widget.get_height] +for [enum@Gtk.Orientation.vertical], but can be used when writing orientation-independent code, such as when implementing [iface@Gtk.Orientable] widgets. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). - + The size of @widget in @orientation. + line="12755">the size of @widget in @orientation a `GtkWidget` + line="12739">a widget the orientation to query + line="12740">the orientation to query @@ -171420,16 +175161,17 @@ system [overview](coordinates.html). c:identifier="gtk_widget_get_size_request"> Gets the size request that was explicitly set for the widget using -gtk_widget_set_size_request(). + line="7271">Gets the size request that was explicitly set for the widget. A value of -1 stored in @width or @height indicates that that dimension has not been set explicitly and the natural requisition -of the widget will be used instead. See -[method@Gtk.Widget.set_size_request]. To get the size a widget will -actually request, call [method@Gtk.Widget.measure] instead of -this function. - +of the widget will be used instead. + +See [method@Gtk.Widget.set_size_request]. + +To get the size a widget will actually request, call +[method@Gtk.Widget.measure] instead of this function. + @@ -171437,7 +175179,7 @@ this function. a `GtkWidget` + line="7273">a widget allow-none="1"> return location for width + line="7274">return location for width allow-none="1"> return location for height + line="7275">return location for height @@ -171467,27 +175209,27 @@ this function. Returns the widget state as a flag set. + line="5811">Returns the widget state as a flag set. -It is worth mentioning that the effective %GTK_STATE_FLAG_INSENSITIVE +It is worth mentioning that the effective [flags@Gtk.StateFlags.insensitive] state will be returned, that is, also based on parent insensitivity, even if @widget itself is sensitive. Also note that if you are looking for a way to obtain the [flags@Gtk.StateFlags] to pass to a [class@Gtk.StyleContext] method, you should look at [method@Gtk.StyleContext.get_state]. - + The state flags for widget + line="5825">the state flags of widget a `GtkWidget` + line="5813">a widget @@ -171498,23 +175240,23 @@ method, you should look at [method@Gtk.StyleContext.get_state]. deprecated-version="4.10"> Returns the style context associated to @widget. + line="11089">Returns the style context associated to the widget. The returned object is guaranteed to be the same for the lifetime of @widget. Style contexts will be removed in GTK 5 - + the widget’s `GtkStyleContext` + line="11098">the widgets style context a `GtkWidget` + line="11091">a widget @@ -171523,8 +175265,8 @@ for the lifetime of @widget. c:identifier="gtk_widget_get_template_child"> Fetch an object build from the template XML for @widget_type in -this @widget instance. + line="11678">Fetches an object build from the template XML for @widget_type in +the widget. This will only report children which were previously declared with [method@Gtk.WidgetClass.bind_template_child_full] or one of its @@ -171533,11 +175275,11 @@ variants. This function is only meant to be called for code which is private to the @widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets. - + The object built in the template XML with + line="11695">the object built in the template XML with the id @name @@ -171545,19 +175287,19 @@ bindings which cannot easily make use of the GObject structure offsets. A `GtkWidget` + line="11680">a widget The `GType` to get a template child for + line="11681">The `GType` to get a template child for The “id” of the child defined in the template XML + line="11682">ID of the child defined in the template XML @@ -171565,26 +175307,25 @@ bindings which cannot easily make use of the GObject structure offsets. - Gets the contents of the tooltip for @widget. + line="10186">Gets the contents of the tooltip for the widget. If the tooltip has not been set using [method@Gtk.Widget.set_tooltip_markup], this -function returns %NULL. - +function returns `NULL`. + the tooltip text + line="10196">the tooltip text a `GtkWidget` + line="10188">a widget @@ -171592,26 +175333,25 @@ function returns %NULL. - Gets the contents of the tooltip for @widget. + line="10098">Gets the contents of the tooltip for the widget. If the @widget's tooltip was set using [method@Gtk.Widget.set_tooltip_markup], this function will return the escaped text. - + the tooltip text + line="10108">the tooltip text a `GtkWidget` + line="10100">a widget @@ -171619,22 +175359,21 @@ this function will return the escaped text. - Gets the vertical alignment of @widget. - + line="9650">Gets the vertical alignment of the widget. + the vertical alignment of @widget + line="9656">the vertical alignment of @widget a `GtkWidget` + line="9652">a widget @@ -171642,25 +175381,24 @@ this function will return the escaped text. - Gets whether the widget would like any available extra vertical + line="8571">Gets whether the widget would like any available extra vertical space. See [method@Gtk.Widget.get_hexpand] for more detail. - + whether vexpand flag is set + line="8580">whether vexpand flag is set the widget + line="8573">a widget @@ -171668,25 +175406,23 @@ See [method@Gtk.Widget.get_hexpand] for more detail. - Gets whether gtk_widget_set_vexpand() has been used to -explicitly set the expand flag on this widget. + line="8611">Gets whether the `vexpand` flag has been explicitly set. See [method@Gtk.Widget.get_hexpand_set] for more detail. - + whether vexpand has been explicitly set + line="8619">whether vexpand has been explicitly set the widget + line="8613">a widget @@ -171694,10 +175430,9 @@ See [method@Gtk.Widget.get_hexpand_set] for more detail. - Determines whether the widget is visible. + line="5882">Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use @@ -171707,18 +175442,18 @@ This function does not check if the widget is obscured in any way. See [method@Gtk.Widget.set_visible]. - + %TRUE if the widget is visible + line="5897">true if the widget is visible a `GtkWidget` + line="5884">a widget @@ -171726,7 +175461,7 @@ See [method@Gtk.Widget.set_visible]. Returns the content width of the widget. + line="12683">Returns the content width of the widget. This function returns the width passed to its size-allocate implementation, which is the width you @@ -171736,18 +175471,18 @@ For pointer events, see [method@Gtk.Widget.contains]. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). - + The width of @widget + line="12698">The width of @widget a `GtkWidget` + line="12685">a widget @@ -171755,26 +175490,27 @@ system [overview](coordinates.html). Causes @widget to have the keyboard focus for the `GtkWindow` it's inside. + line="5025">Causes @widget to have the keyboard focus for the window +that it belongs to. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget -that is focusable, it will not take focus and %FALSE will be returned. +that is focusable, it will not take focus and false will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget -is allowed, should not have an effect, and return %TRUE. - +is allowed, should not have an effect, and return true. + %TRUE if focus is now inside @widget. + line="5039">true if focus is now inside @widget a `GtkWidget` + line="5027">a widget @@ -171782,27 +175518,25 @@ is allowed, should not have an effect, and return %TRUE. Returns whether @css_class is currently applied to @widget. - + line="13201">Returns whether a style class is currently applied to the widget. + %TRUE if @css_class is currently applied to @widget, - %FALSE otherwise. + line="13208">true if @css_class is currently applied to @widget a `GtkWidget` + line="13203">a widget A style class, without the leading '.' - used for notation of style classes + line="13204">style class, without the leading period @@ -171810,24 +175544,23 @@ is allowed, should not have an effect, and return %TRUE. - Determines whether @widget is the current default widget + line="5551">Determines whether the widget is the current default widget within its toplevel. - + %TRUE if @widget is the current default widget - within its toplevel, %FALSE otherwise + line="5558">true if @widget is the current default widget + within its toplevel a `GtkWidget` + line="5553">a widget @@ -171835,26 +175568,25 @@ within its toplevel. - Determines if the widget has the global input focus. + line="5409">Determines if the widget has the global input focus. See [method@Gtk.Widget.is_focus] for the difference between having the global input focus, and only having the focus within a toplevel. - + %TRUE if the widget has the global input focus. + line="5419">true if the widget has the global input focus a `GtkWidget` + line="5411">a widget @@ -171863,7 +175595,7 @@ within a toplevel. c:identifier="gtk_widget_has_visible_focus"> Determines if the widget should show a visible indication that + line="5431">Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function that takes into account whether @@ -171873,18 +175605,18 @@ information about focus indication. To find out if the widget has the global input focus, use [method@Gtk.Widget.has_focus]. - + %TRUE if the widget should display a “focus rectangle” + line="5446">true if the widget should display a “focus rectangle” a `GtkWidget` + line="5433">a widget @@ -171895,11 +175627,11 @@ To find out if the widget has the global input focus, use deprecated-version="4.10"> Reverses the effects of gtk_widget_show(). + line="2780">Reverses the effects of [method.Gtk.Widget.show]. This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead - + @@ -171907,7 +175639,7 @@ This is causing the widget to be hidden (invisible to the user). a `GtkWidget` + line="2782">a widget @@ -171915,22 +175647,22 @@ This is causing the widget to be hidden (invisible to the user). Returns whether the widget is currently being destroyed. + line="10840">Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work. - + %TRUE if @widget is being destroyed + line="10849">true if @widget is being destroyed a `GtkWidget` + line="10842">a widget @@ -171938,14 +175670,14 @@ unnecessary work. Creates and initializes child widgets defined in templates. + line="11278">Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using [method@Gtk.WidgetClass.set_template]. It is important to call this function in the instance initializer -of a `GtkWidget` subclass and not in `GObject.constructed()` or +of a widget subclass and not in `GObject.constructed()` or `GObject.constructor()` for two reasons: - derived widgets will assume that the composite widgets @@ -171958,7 +175690,7 @@ of a `GtkWidget` subclass and not in `GObject.constructed()` or A good rule of thumb is to call this function as the first thing in an instance initialization function. - + @@ -171966,7 +175698,7 @@ an instance initialization function. a `GtkWidget` + line="11280">a widget @@ -171975,7 +175707,7 @@ an instance initialization function. c:identifier="gtk_widget_insert_action_group"> Inserts @group into @widget. + line="11182">Inserts an action group into the widget's actions. Children of @widget that implement [iface@Gtk.Actionable] can then be associated with actions in @group by setting their @@ -171986,9 +175718,9 @@ even if you insert a group with prefix @prefix, actions with the same prefix will still be inherited from the parent, unless the group contains an action with the same name. -If @group is %NULL, a previously inserted group for @name is +If @group is `NULL`, a previously inserted group for @name is removed from @widget. - + @@ -171996,13 +175728,13 @@ removed from @widget. a `GtkWidget` + line="11184">a widget the prefix for actions in @group + line="11185">the prefix for actions in @group allow-none="1"> a `GActionGroup`, or %NULL to remove - the previously inserted group for @name + line="11186">an action group @@ -172020,21 +175751,25 @@ removed from @widget. Inserts @widget into the child widget list of @parent. + line="12329">Sets the parent widget of the widget. + +In contrast to [method@Gtk.Widget.set_parent], this function +inserts @widget at a specific position into the list of children +of the @parent widget. It will be placed after @previous_sibling, or at the beginning if -@previous_sibling is %NULL. +@previous_sibling is `NULL`. -After calling this function, `gtk_widget_get_prev_sibling(widget)` +After calling this function, `gtk_widget_get_prev_sibling (widget)` will return @previous_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. -This API is primarily meant for widget implementations; if you are +This function is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. - + @@ -172042,13 +175777,13 @@ just using a widget, you *must* use its own API for adding children. a `GtkWidget` + line="12331">a widget the parent `GtkWidget` to insert @widget into + line="12332">the parent widget to insert @widget into allow-none="1"> the new previous sibling of @widget + line="12333">the new previous sibling of @widget @@ -172065,20 +175800,24 @@ just using a widget, you *must* use its own API for adding children. Inserts @widget into the child widget list of @parent. + line="12376">Sets the parent widget of the widget. + +In contrast to [method@Gtk.Widget.set_parent], this function +inserts @widget at a specific position into the list of children +of the @parent widget. It will be placed before @next_sibling, or at the end if -@next_sibling is %NULL. +@next_sibling is `NULL`. -After calling this function, `gtk_widget_get_next_sibling(widget)` +After calling this function, `gtk_widget_get_next_sibling (widget)` will return @next_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. -This API is primarily meant for widget implementations; if you are +This function is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. - + @@ -172086,13 +175825,13 @@ just using a widget, you *must* use its own API for adding children. a `GtkWidget` + line="12378">a widget the parent `GtkWidget` to insert @widget into + line="12379">the parent widget to insert @widget into allow-none="1"> the new next sibling of @widget + line="12380">the new next sibling of @widget @@ -172109,27 +175848,26 @@ just using a widget, you *must* use its own API for adding children. Determines whether @widget is somewhere inside @ancestor, -possibly with intermediate containers. - + line="7372">Determines whether the widget is a descendent of @ancestor. + %TRUE if @ancestor contains @widget as a child, - grandchild, great grandchild, etc. + line="7379">true if @ancestor contains @widget as a child, + grandchild, great grandchild, etc a `GtkWidget` + line="7374">a widget another `GtkWidget` + line="7375">another `GtkWidget` @@ -172137,21 +175875,21 @@ possibly with intermediate containers. Determines whether @widget can be drawn to. + line="5941">Determines whether the widget can be drawn to. A widget can be drawn if it is mapped and visible. - + %TRUE if @widget is drawable, %FALSE otherwise + line="5949">true if @widget is drawable a `GtkWidget` + line="5943">a widget @@ -172159,74 +175897,78 @@ A widget can be drawn if it is mapped and visible. Determines if the widget is the focus widget within its + line="5471">Determines if the widget is the focus widget within its toplevel. This does not mean that the [property@Gtk.Widget:has-focus] property is necessarily set; [property@Gtk.Widget:has-focus] will only be set if the toplevel widget additionally has the global input focus. - + %TRUE if the widget is the focus widget. + line="5483">true if the widget is the focus widget a `GtkWidget` + line="5473">a widget - + Returns the widget’s effective sensitivity. + line="6086">Returns the widget’s effective sensitivity. This means it is sensitive itself and also its parent widget is sensitive. - + %TRUE if the widget is effectively sensitive + line="6095">true if the widget is effectively sensitive a `GtkWidget` + line="6088">a widget - + Determines whether the widget and all its parents are marked as + line="5909">Determines whether the widget and all its parents are marked as visible. This function does not check if the widget is obscured in any way. See also [method@Gtk.Widget.get_visible] and [method@Gtk.Widget.set_visible]. - + %TRUE if the widget and all its parents are visible + line="5921">true if the widget and all its parents are visible a `GtkWidget` + line="5911">a widget @@ -172234,53 +175976,54 @@ See also [method@Gtk.Widget.get_visible] and Emits the `::keynav-failed` signal on the widget. + line="7098">Emits the [signal@Gtk.Widget::keynav-failed] signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of -[method@Gtk.Widget.child_focus]. When %TRUE is returned, -stay in the widget, the failed keyboard navigation is OK +[method@Gtk.Widget.child_focus]. When true is returned, +stay in the widget, the failed keyboard navigation is ok and/or there is nowhere we can/should move the focus to. -When %FALSE is returned, the caller should continue with +When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns -%FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. -For the other values of `GtkDirectionType` it returns %TRUE. +false for [enum@Gtk.DirectionType.tab-forward] and +[enum@Gtk.DirectionType.tab-backward]. For the other values +of [enum@Gtk.DirectionType] it returns true. -Whenever the default handler returns %TRUE, it also calls +Whenever the default handler returns true, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. -A use case for providing an own implementation of ::keynav-failed +A use case for providing an own implementation of `::keynav-failed` (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. - + %TRUE if stopping keyboard navigation is fine, %FALSE + line="7132">true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent container(s). + navigation attempt in its parent widget a `GtkWidget` + line="7100">a widget direction of focus movement + line="7101">direction of focus movement @@ -172289,7 +176032,7 @@ interfaces that require entering license keys. c:identifier="gtk_widget_list_mnemonic_labels"> Returns the widgets for which this widget is the target of a + line="9907">Returns the widgets for which this widget is the target of a mnemonic. Typically, these widgets will be labels. See, for example, @@ -172300,13 +176043,12 @@ If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. - + the list - of mnemonic labels; free this list with g_list_free() when you - are done with it. + line="9923">the list + of mnemonic labels @@ -172315,7 +176057,7 @@ first, and then unref all the widgets afterwards. a `GtkWidget` + line="9909">a widget @@ -172323,10 +176065,10 @@ first, and then unref all the widgets afterwards. Causes a widget to be mapped if it isn’t already. + line="2866">Causes a widget to be mapped if it isn’t already. This function is only for use in widget implementations. - + @@ -172334,7 +176076,7 @@ This function is only for use in widget implementations. a `GtkWidget` + line="2868">a widget @@ -172342,7 +176084,7 @@ This function is only for use in widget implementations. Measures @widget in the orientation @orientation and for the given @for_size. + line="452">Measures @widget in the orientation @orientation and for the given @for_size. As an example, if @orientation is %GTK_ORIENTATION_HORIZONTAL and @for_size is 300, this functions will compute the minimum and natural width of @widget @@ -172350,7 +176092,7 @@ if it is allocated at a height of 300 pixels. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for a more details on implementing `GtkWidgetClass.measure()`. - + @@ -172358,19 +176100,19 @@ a more details on implementing `GtkWidgetClass.measure()`. A `GtkWidget` instance + line="454">A `GtkWidget` instance the orientation to measure + line="455">the orientation to measure Size for the opposite of @orientation, i.e. + line="456">Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height @@ -172385,7 +176127,7 @@ a more details on implementing `GtkWidgetClass.measure()`. allow-none="1"> location to store the minimum size + line="461">location to store the minimum size allow-none="1"> location to store the natural size + line="462">location to store the natural size allow-none="1"> location to store the baseline + line="463">location to store the baseline position for the minimum size, or -1 to report no baseline @@ -172419,7 +176161,7 @@ a more details on implementing `GtkWidgetClass.measure()`. allow-none="1"> location to store the baseline + line="465">location to store the baseline position for the natural size, or -1 to report no baseline @@ -172429,27 +176171,25 @@ a more details on implementing `GtkWidgetClass.measure()`. c:identifier="gtk_widget_mnemonic_activate"> Emits the ::mnemonic-activate signal. - -See [signal@Gtk.Widget::mnemonic-activate]. - + line="4584">Emits the [signal@Gtk.Widget::mnemonic-activate] signal. + %TRUE if the signal has been handled + line="4591">true if the signal has been handled a `GtkWidget` + line="4586">a widget %TRUE if there are other widgets with the same mnemonic + line="4587">true if there are other widgets with the same mnemonic @@ -172458,7 +176198,7 @@ See [signal@Gtk.Widget::mnemonic-activate]. c:identifier="gtk_widget_observe_children"> Returns a `GListModel` to track the children of @widget. + line="12140">Returns a list model to track the children of the widget. Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. @@ -172466,20 +176206,20 @@ It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. - + - a `GListModel` tracking @widget's children + line="12153"> + a list model tracking @widget's children a `GtkWidget` + line="12142">a widget @@ -172488,8 +176228,7 @@ because of the slowdowns. c:identifier="gtk_widget_observe_controllers"> Returns a `GListModel` to track the [class@Gtk.EventController]s -of @widget. + line="12212">Returns a list model to track the event controllers of the widget. Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. @@ -172497,20 +176236,20 @@ It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. - + - a `GListModel` tracking @widget's controllers + line="12225"> + a list model tracking @widget's controllers a `GtkWidget` + line="12214">a widget @@ -172518,51 +176257,50 @@ because of the slowdowns. Finds the descendant of @widget closest to the point (@x, @y). + line="10430">Finds the descendant of the widget closest to a point. -The point must be given in widget coordinates, so (0, 0) is assumed -to be the top left of @widget's content area. +The point (x, y) must be given in widget coordinates, so (0, 0) +is assumed to be the top left of @widget's content area. -Usually widgets will return %NULL if the given coordinate is not +Usually widgets will return `NULL` if the given coordinate is not contained in @widget checked via [method@Gtk.Widget.contains]. Otherwise they will recursively try to find a child that does -not return %NULL. Widgets are however free to customize their +not return `NULL`. Widgets are however free to customize their picking algorithm. This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events. - + The widget descendant at - the given point + line="10452">the widget's descendant at (x, y) the widget to query + line="10432">the widget to query X coordinate to test, relative to @widget's origin + line="10433">x coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin + line="10434">y coordinate to test, relative to @widget's origin Flags to influence what is picked + line="10435">flags to influence what is picked @@ -172570,7 +176308,7 @@ delivering events. Flags the widget for a rerun of the [vfunc@Gtk.Widget.size_allocate] + line="3567">Flags the widget for a rerun of the [vfunc@Gtk.Widget.size_allocate] function. Use this function instead of [method@Gtk.Widget.queue_resize] @@ -172580,7 +176318,7 @@ reposition its contents. An example user of this function is [method@Gtk.Widget.set_halign]. This function is only for use in widget implementations. - + @@ -172588,7 +176326,7 @@ This function is only for use in widget implementations. a `GtkWidget` + line="3569">a widget @@ -172596,12 +176334,14 @@ This function is only for use in widget implementations. Schedules this widget to be redrawn in the paint phase + line="3529">Schedules this widget to be redrawn. + +The redraw will happen in the paint phase of the current or the next frame. This means @widget's [vfunc@Gtk.Widget.snapshot] implementation will be called. - + @@ -172609,7 +176349,7 @@ implementation will be called. a `GtkWidget` + line="3531">a widget @@ -172617,7 +176357,7 @@ implementation will be called. Flags a widget to have its size renegotiated. + line="3645">Flags a widget to have its size renegotiated. This should be called when a widget for some reason has a new size request. For example, when you change the text in a @@ -172630,7 +176370,7 @@ virtual method. Calls to gtk_widget_queue_resize() from inside [vfunc@Gtk.Widget.size_allocate] will be silently ignored. This function is only for use in widget implementations. - + @@ -172638,7 +176378,7 @@ This function is only for use in widget implementations. a `GtkWidget` + line="3647">a widget @@ -172646,7 +176386,7 @@ This function is only for use in widget implementations. Creates the GDK resources associated with a widget. + line="3437">Creates the GDK resources associated with a widget. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized @@ -172662,7 +176402,7 @@ isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signal@Gtk.Widget::realize]. - + @@ -172670,7 +176410,7 @@ called after the widget is realized automatically, such as a `GtkWidget` + line="3439">a widget @@ -172679,14 +176419,14 @@ called after the widget is realized automatically, such as c:identifier="gtk_widget_remove_controller"> Removes @controller from @widget, so that it doesn't process -events anymore. + line="11887">Removes an event controller from the widget. -It should not be used again. +The removed event controller will not receive any more events, +and should not be used again. Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function. - + @@ -172694,13 +176434,13 @@ are destroyed, there is normally no need to call this function. a `GtkWidget` + line="11889">a widget a `GtkEventController` + line="11890">an event controller @@ -172709,10 +176449,10 @@ are destroyed, there is normally no need to call this function. c:identifier="gtk_widget_remove_css_class"> Removes a style from @widget. + line="13172">Removes a style from the widget. After this, the style of @widget will stop matching for @css_class. - + @@ -172720,14 +176460,13 @@ After this, the style of @widget will stop matching for @css_class. a `GtkWidget` + line="13174">a widget The style class to remove from @widget, without - the leading '.' used for notation of style classes + line="13175">style class to remove from @widget, without the leading period @@ -172736,12 +176475,13 @@ After this, the style of @widget will stop matching for @css_class. c:identifier="gtk_widget_remove_mnemonic_label"> Removes a widget from the list of mnemonic labels for this widget. + line="9979">Removes a widget from the list of mnemonic labels for this widget. -See [method@Gtk.Widget.list_mnemonic_labels]. The widget must -have previously been added to the list with +See [method@Gtk.Widget.list_mnemonic_labels]. + +The widget must have previously been added to the list with [method@Gtk.Widget.add_mnemonic_label]. - + @@ -172749,14 +176489,13 @@ have previously been added to the list with a `GtkWidget` + line="9981">a widget a `GtkWidget` that was previously set as a mnemonic - label for @widget with [method@Gtk.Widget.add_mnemonic_label] + line="9982">a widget that is a mnemonic label for @widget @@ -172765,9 +176504,9 @@ have previously been added to the list with c:identifier="gtk_widget_remove_tick_callback"> Removes a tick callback previously registered with -gtk_widget_add_tick_callback(). - + line="3118">Removes a tick callback previously registered with +[method@Gtk.Widget.add_tick_callback]. + @@ -172775,13 +176514,13 @@ gtk_widget_add_tick_callback(). a `GtkWidget` + line="3120">a widget an id returned by [method@Gtk.Widget.add_tick_callback] + line="3121">an ID returned by [method@Gtk.Widget.add_tick_callback] @@ -172789,16 +176528,15 @@ gtk_widget_add_tick_callback(). - Specifies whether the input focus can enter the widget -or any of its children. + line="5290">Sets whether the input focus can enter the widget or +any of its children. -Applications should set @can_focus to %FALSE to mark a +Applications should set @can_focus to false to mark a widget as for pointer/touch use only. -Note that having @can_focus be %TRUE is only one of the +Note that having @can_focus be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and focusable and not have an ancestor that is marked as not can-focus in order to receive input @@ -172806,7 +176544,7 @@ focus. See [method@Gtk.Widget.grab_focus] for actually setting the input focus on a widget. - + @@ -172814,13 +176552,13 @@ the input focus on a widget. a `GtkWidget` + line="5292">a widget whether or not the input focus can enter + line="5293">whether the input focus can enter the widget or any of its children @@ -172829,11 +176567,10 @@ the input focus on a widget. - Sets whether @widget can be the target of pointer events. - + line="12643">Sets whether the widget can be the target of pointer events. + @@ -172841,13 +176578,13 @@ the input focus on a widget. a `GtkWidget` + line="12645">a widget whether this widget should be able to + line="12646">whether this widget should be able to receive pointer events @@ -172857,12 +176594,12 @@ the input focus on a widget. c:identifier="gtk_widget_set_child_visible"> Sets whether @widget should be mapped along with its parent. + line="6879">Sets whether the widget should be mapped along with its parent. The child visibility can be set for widget before it is added to a container with [method@Gtk.Widget.set_parent], to avoid mapping children unnecessary before immediately unmapping them. -However it will be reset to its default state of %TRUE when the +However it will be reset to its default state of true when the widget is removed from a container. Note that changing the child visibility of a widget does not @@ -172871,9 +176608,9 @@ a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. -This function is only useful for container implementations +This function is only useful for widget implementations and should never be called by an application. - + @@ -172881,14 +176618,14 @@ and should never be called by an application. a `GtkWidget` + line="6881">a widget if %TRUE, @widget should be mapped along - with its parent. + line="6882">whether @widget should be mapped along + with its parent @@ -172896,12 +176633,10 @@ and should never be called by an application. - Clear all style classes applied to @widget -and replace them with @classes. - + line="13260">Replaces the current style classes of the widget with @classes. + @@ -172909,14 +176644,14 @@ and replace them with @classes. a `GtkWidget` + line="13262">a widget - %NULL-terminated list of style classes to apply to @widget. + line="13263"> + `NULL`-terminated list of style classes @@ -172926,15 +176661,14 @@ and replace them with @classes. - Sets the cursor to be shown when pointer devices point -towards @widget. + line="12554">Sets the cursor to be shown when the pointer hovers over +the widget. -If the @cursor is NULL, @widget will use the cursor -inherited from the parent widget. - +If the @cursor is `NULL`, @widget will use the cursor +inherited from its parent. + @@ -172942,7 +176676,7 @@ inherited from the parent widget. a `GtkWidget` + line="12556">a widget allow-none="1"> the new cursor + line="12557">the new cursor @@ -172960,18 +176694,18 @@ inherited from the parent widget. c:identifier="gtk_widget_set_cursor_from_name"> Sets a named cursor to be shown when pointer devices point -towards @widget. + line="12585">Sets the cursor to be shown when the pointer hovers over +the widget. This is a utility function that creates a cursor via [ctor@Gdk.Cursor.new_from_name] and then sets it on @widget with [method@Gtk.Widget.set_cursor]. See those functions for details. -On top of that, this function allows @name to be %NULL, which +On top of that, this function allows @name to be `NULL`, which will do the same as calling [method@Gtk.Widget.set_cursor] -with a %NULL cursor. - +with a `NULL` cursor. + @@ -172979,7 +176713,7 @@ with a %NULL cursor. a `GtkWidget` + line="12587">a widget allow-none="1"> The name of the cursor + line="12588">the name of the cursor @@ -172996,20 +176730,22 @@ with a %NULL cursor. Sets the reading direction on a particular widget. + line="7436">Sets the reading direction on the widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with -right-to-left reading directions can be done. Generally, applications -will let the default reading direction present, except for containers -where the containers are arranged in an order that is explicitly -visual rather than logical (such as buttons for text justification). +right-to-left reading directions can be done. + +Generally, applications will let the default reading direction +prevail, except for widgets where the children are arranged in +an order that is explicitly visual rather than logical (such as +buttons for text justification). -If the direction is set to %GTK_TEXT_DIR_NONE, then the value -set by [func@Gtk.Widget.set_default_direction] will be used. - +If the direction is set to [enum@Gtk.TextDirection.none], then +the value set by [func@Gtk.Widget.set_default_direction] will be used. + @@ -173017,13 +176753,13 @@ set by [func@Gtk.Widget.set_default_direction] will be used. a `GtkWidget` + line="7438">a widget the new direction + line="7439">the new direction @@ -173031,12 +176767,12 @@ set by [func@Gtk.Widget.set_default_direction] will be used. Set @child as the current focus child of @widget. + line="12499">Set the focus child of the widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [method@Gtk.Widget.grab_focus] on it. - + @@ -173044,7 +176780,7 @@ If you want a certain widget to get the input focus, call a `GtkWidget` + line="12501">a widget a direct child widget of @widget or %NULL - to unset the focus child of @widget + line="12502">a direct child widget of @widget + or `NULL` to unset the focus child @@ -173062,16 +176798,15 @@ If you want a certain widget to get the input focus, call - Sets whether the widget should grab focus when it is clicked + line="5498">Sets whether the widget should grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. - + @@ -173079,13 +176814,13 @@ the main area of the application. a `GtkWidget` + line="5500">a widget whether the widget should grab focus when clicked + line="5501">whether the widget should grab focus when clicked with the mouse @@ -173094,15 +176829,14 @@ the main area of the application. - Specifies whether @widget can own the input focus. + line="5349">Sets whether the widget can own the input focus. -Widget implementations should set @focusable to %TRUE in +Widget implementations should set @focusable to true in their init() function if they want to receive keyboard input. -Note that having @focusable be %TRUE is only one of the +Note that having @focusable be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and can-focus and not have an ancestor that is marked as not can-focus in order to receive input @@ -173110,7 +176844,7 @@ focus. See [method@Gtk.Widget.grab_focus] for actually setting the input focus on a widget. - + @@ -173118,13 +176852,13 @@ the input focus on a widget. a `GtkWidget` + line="5351">a widget whether or not @widget can own the input focus + line="5352">whether or not @widget can own the input focus @@ -173132,7 +176866,7 @@ the input focus on a widget. Sets the font map to use for Pango rendering. + line="6763">Sets the font map to use for text rendering in the widget. The font map is the object that is used to look up fonts. Setting a custom font map can be useful in special situations, @@ -173140,7 +176874,7 @@ e.g. when you need to add application-specific fonts to the set of available fonts. When not set, the widget will inherit the font map from its parent. - + @@ -173148,7 +176882,7 @@ When not set, the widget will inherit the font map from its parent. a `GtkWidget` + line="6765">a widget allow-none="1"> a `PangoFontMap`, or %NULL to unset any - previously set font map + line="6766">a `PangoFontMap` + c:identifier="gtk_widget_set_font_options" + deprecated="1" + deprecated-version="4.16"> Sets the `cairo_font_options_t` used for Pango rendering -in this widget. + line="6698">Sets the `cairo_font_options_t` used for text rendering +in the widget. When not set, the default font options for the `GdkDisplay` will be used. - + @@ -173180,7 +176915,7 @@ will be used. a `GtkWidget` + line="6700">a widget allow-none="1"> a `cairo_font_options_t` + line="6701">a `cairo_font_options_t` struct to unset any previously set default font options @@ -173199,11 +176934,10 @@ will be used. - Sets the horizontal alignment of @widget. - + line="9627">Sets the horizontal alignment of the widget. + @@ -173211,13 +176945,13 @@ will be used. a `GtkWidget` + line="9629">a widget the horizontal alignment + line="9630">the horizontal alignment @@ -173225,11 +176959,10 @@ will be used. - Sets the `has-tooltip` property on @widget to @has_tooltip. - + line="10208">Sets the `has-tooltip` property on the widget. + @@ -173237,13 +176970,13 @@ will be used. a `GtkWidget` + line="10210">a widget whether or not @widget has a tooltip. + line="10211">whether or not @widget has a tooltip @@ -173251,16 +176984,14 @@ will be used. - Sets whether the widget would like any available extra horizontal + line="8474">Sets whether the widget would like any available extra horizontal space. -When a user resizes a `GtkWindow`, widgets with expand=TRUE -generally receive the extra space. For example, a list or -scrollable area or document in your window would often be set to -expand. +When a user resizes a window, widgets with expand set to true generally +receive the extra space. For example, a list or scrollable area +or document in your window would often be set to expand. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra @@ -173269,19 +177000,19 @@ room. By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call [method@Gtk.Widget.compute_expand]. -A container can decide how the expandability of children affects the -expansion of the container by overriding the compute_expand virtual -method on `GtkWidget`.). +A widget can decide how the expandability of children affects its +own expansion by overriding the `compute_expand` virtual method on +`GtkWidget`.). Setting hexpand explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, -regardless of children. The override occurs because +regardless of children. The override occurs because [method@Gtk.Widget.set_hexpand] sets the hexpand-set property (see [method@Gtk.Widget.set_hexpand_set]) which causes the widget’s hexpand value to be used, rather than looking at children and widget state. - + @@ -173289,13 +177020,13 @@ value to be used, rather than looking at children and widget state. the widget + line="8476">a widget whether to expand + line="8477">whether to expand @@ -173303,10 +177034,9 @@ value to be used, rather than looking at children and widget state. - Sets whether the hexpand flag will be used. + line="8541">Sets whether the hexpand flag will be used. The [property@Gtk.Widget:hexpand-set] property will be set automatically when you call [method@Gtk.Widget.set_hexpand] @@ -173320,7 +177050,7 @@ children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. - + @@ -173328,13 +177058,13 @@ for completeness and consistency. the widget + line="8543">a widget value for hexpand-set property + line="8544">value for hexpand-set property @@ -173342,12 +177072,11 @@ for completeness and consistency. - Sets the layout manager delegate instance that provides an -implementation for measuring and allocating the children of @widget. - + line="12822">Sets the layout manager to use for measuring and allocating children +of the widget. + @@ -173355,7 +177084,7 @@ implementation for measuring and allocating the children of @widget. a `GtkWidget` + line="12824">a widget allow-none="1"> a `GtkLayoutManager` + line="12825">a layout manager + + Sets whether the widget acts like a modal dialog, +with respect to event delivery. + + + + + + + a `GtkWidget` + + + + whether to limit events + + + + - Sets the bottom margin of @widget. - + line="9839">Sets the bottom margin of the widget. + @@ -173384,13 +177139,13 @@ implementation for measuring and allocating the children of @widget. a `GtkWidget` + line="9841">a widget the bottom margin + line="9842">the bottom margin @@ -173398,11 +177153,10 @@ implementation for measuring and allocating the children of @widget. - Sets the end margin of @widget. - + line="9753">Sets the end margin of the widget. + @@ -173410,13 +177164,13 @@ implementation for measuring and allocating the children of @widget. a `GtkWidget` + line="9755">a widget the end margin + line="9756">the end margin @@ -173424,11 +177178,10 @@ implementation for measuring and allocating the children of @widget. - Sets the start margin of @widget. - + line="9709">Sets the start margin of the widget. + @@ -173436,13 +177189,13 @@ implementation for measuring and allocating the children of @widget. a `GtkWidget` + line="9711">a widget the start margin + line="9712">the start margin @@ -173450,11 +177203,10 @@ implementation for measuring and allocating the children of @widget. - Sets the top margin of @widget. - + line="9797">Sets the top margin of the widget. + @@ -173462,13 +177214,13 @@ implementation for measuring and allocating the children of @widget. a `GtkWidget` + line="9799">a widget the top margin + line="9800">the top margin @@ -173476,10 +177228,9 @@ implementation for measuring and allocating the children of @widget. - Sets a widgets name. + line="5662">Sets a widgets name. Setting a name allows you to refer to the widget from a CSS file. You can apply a style to widgets with a particular name @@ -173490,7 +177241,7 @@ Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice. - + @@ -173498,13 +177249,13 @@ of alphanumeric symbols, dashes and underscores will suffice. a `GtkWidget` + line="5664">a widget name for the widget + line="5665">name for the widget @@ -173512,10 +177263,9 @@ of alphanumeric symbols, dashes and underscores will suffice. - Request the @widget to be rendered partially transparent. + line="10700">Requests the widget to be rendered partially transparent. An opacity of 0 is fully transparent and an opacity of 1 is fully opaque. @@ -173523,8 +177273,8 @@ is fully opaque. Opacity works on both toplevel widgets and child widgets, although there are some limitations: For toplevel widgets, applying opacity depends on the capabilities of the windowing system. On X11, this -has any effect only on X displays with a compositing manager, -see gdk_display_is_composited(). On Windows and Wayland it should +has any effect only on X displays with a compositing manager, see +[method@Gdk.Display.is_composited]. On Windows and Wayland it will always work, although setting a window’s opacity after the window has been shown may cause some flicker. @@ -173533,11 +177283,12 @@ a toplevel to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel. The opacity value itself is not inherited by child widgets (since that would make widgets deeper in the hierarchy -progressively more translucent). As a consequence, [class@Gtk.Popover]s -and other [iface@Gtk.Native] widgets with their own surface will use their -own opacity value, and thus by default appear non-translucent, -even if they are attached to a toplevel that is translucent. - +progressively more translucent). As a consequence, [class@Gtk.Popover] +instances and other [iface@Gtk.Native] widgets with their own surface +will use their own opacity value, and thus by default appear +non-translucent, even if they are attached to a toplevel that +is translucent. + @@ -173545,13 +177296,13 @@ even if they are attached to a toplevel that is translucent. a `GtkWidget` + line="10702">a widget desired opacity, between 0 and 1 + line="10703">desired opacity, between 0 and 1 @@ -173559,19 +177310,18 @@ even if they are attached to a toplevel that is translucent. - Sets how @widget treats content that is drawn outside the -widget's content area. + line="10772">Sets how the widget treats content that is drawn outside the +it's content area. See the definition of [enum@Gtk.Overflow] for details. This setting is provided for widget implementations and should not be used by application code. -The default value is %GTK_OVERFLOW_VISIBLE. - +The default value is [enum@Gtk.Overflow.visible]. + @@ -173579,22 +177329,21 @@ The default value is %GTK_OVERFLOW_VISIBLE. a `GtkWidget` + line="10774">a widget desired overflow + line="10775">desired overflow value - Sets @parent as the parent widget of @widget. + line="6261">Sets the parent widget of the widget. This takes care of details such as updating the state and style of the child to reflect its new location and resizing the parent. @@ -173602,7 +177351,7 @@ The opposite function is [method@Gtk.Widget.unparent]. This function is useful only when implementing subclasses of `GtkWidget`. - + @@ -173610,13 +177359,13 @@ This function is useful only when implementing subclasses of a `GtkWidget` + line="6263">a widget parent widget + line="6264">parent widget @@ -173624,14 +177373,12 @@ This function is useful only when implementing subclasses of - Specifies whether @widget will be treated as the default + line="5585">Sets whether the widget will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default. - + @@ -173639,13 +177386,13 @@ another widget is the default. a `GtkWidget` + line="5587">a widget whether or not @widget can be a default widget. + line="5588">whether or not @widget can be a default widget @@ -173653,16 +177400,15 @@ another widget is the default. - Sets the sensitivity of a widget. + line="5996">Sets the sensitivity of the widget. A widget is sensitive if the user can interact with it. Insensitive widgets are “grayed out” and the user can’t interact with them. Insensitive widgets are known as “inactive”, “disabled”, or “ghosted” in some other toolkits. - + @@ -173670,13 +177416,13 @@ interact with them. Insensitive widgets are known as a `GtkWidget` + line="5998">a widget %TRUE to make the widget sensitive + line="5999">true to make the widget sensitive @@ -173685,7 +177431,7 @@ interact with them. Insensitive widgets are known as c:identifier="gtk_widget_set_size_request"> Sets the minimum size of a widget. + line="7217">Sets the minimum size of the widget. That is, the widget’s size request will be at least @width by @height. You can use this function to force a widget to @@ -173699,9 +177445,8 @@ the size request. Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action -can all change the appropriate size for a given widget. So, it's -basically impossible to hardcode a size that will always be -correct. +can all change the appropriate size for a given widget. So, it is +basically impossible to hardcode a size that will always work. The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. @@ -173720,7 +177465,7 @@ properties [property@Gtk.Widget:margin-bottom], but it does include pretty much all other padding or border properties set by any subclass of `GtkWidget`. - + @@ -173728,19 +177473,19 @@ of `GtkWidget`. a `GtkWidget` + line="7219">a widget width @widget should request, or -1 to unset + line="7220">width @widget should request, or -1 to unset height @widget should request, or -1 to unset + line="7221">height @widget should request, or -1 to unset @@ -173748,16 +177493,16 @@ of `GtkWidget`. Turns on flag values in the current widget state. + line="5747">Turns on flag values in the current widget state. Typical widget states are insensitive, prelighted, etc. -This function accepts the values %GTK_STATE_FLAG_DIR_LTR and -%GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set +This function accepts the values [flags@Gtk.StateFlags.dir-ltr] and +[flags@Gtk.StateFlags.dir-rtl] but ignores them. If you want to set the widget's direction, use [method@Gtk.Widget.set_direction]. This function is for use in widget implementations. - + @@ -173765,19 +177510,19 @@ This function is for use in widget implementations. a `GtkWidget` + line="5749">a widget State flags to turn on + line="5750">state flags to turn on Whether to clear state before turning on @flags + line="5751">whether to clear state before turning on @flags @@ -173785,18 +177530,18 @@ This function is for use in widget implementations. - Sets @markup as the contents of the tooltip, which is marked -up with Pango markup. + line="10120">Sets the contents of the tooltip for widget. + +@markup must contain Pango markup. This function will take care of setting the [property@Gtk.Widget:has-tooltip] as a side effect, and of the default handler for the [signal@Gtk.Widget::query-tooltip] signal. See also [method@Gtk.Tooltip.set_markup]. - + @@ -173804,7 +177549,7 @@ See also [method@Gtk.Tooltip.set_markup]. a `GtkWidget` + line="10122">a widget allow-none="1"> the contents of the tooltip for @widget + line="10123">the contents of the tooltip for @widget @@ -173821,10 +177566,9 @@ See also [method@Gtk.Tooltip.set_markup]. - Sets @text as the contents of the tooltip. + line="10039">Sets the contents of the tooltip for the widget. If @text contains any markup, it will be escaped. @@ -173834,7 +177578,7 @@ and of the default handler for the [signal@Gtk.Widget::query-tooltip] signal. See also [method@Gtk.Tooltip.set_text]. - + @@ -173842,7 +177586,7 @@ See also [method@Gtk.Tooltip.set_text]. a `GtkWidget` + line="10041">a widget allow-none="1"> the contents of the tooltip for @widget + line="10042">the contents of the tooltip for @widget @@ -173859,11 +177603,10 @@ See also [method@Gtk.Tooltip.set_text]. - Sets the vertical alignment of @widget. - + line="9668">Sets the vertical alignment of the widget. + @@ -173871,13 +177614,13 @@ See also [method@Gtk.Tooltip.set_text]. a `GtkWidget` + line="9670">a widget the vertical alignment + line="9671">the vertical alignment @@ -173885,14 +177628,13 @@ See also [method@Gtk.Tooltip.set_text]. - Sets whether the widget would like any available extra vertical + line="8592">Sets whether the widget would like any available extra vertical space. See [method@Gtk.Widget.set_hexpand] for more detail. - + @@ -173900,13 +177642,13 @@ See [method@Gtk.Widget.set_hexpand] for more detail. the widget + line="8594">a widget whether to expand + line="8595">whether to expand @@ -173914,13 +177656,12 @@ See [method@Gtk.Widget.set_hexpand] for more detail. - Sets whether the vexpand flag will be used. + line="8631">Sets whether the vexpand flag will be used. See [method@Gtk.Widget.set_hexpand_set] for more detail. - + @@ -173928,13 +177669,13 @@ See [method@Gtk.Widget.set_hexpand_set] for more detail. the widget + line="8633">the widget value for vexpand-set property + line="8634">value for vexpand-set property @@ -173942,14 +177683,13 @@ See [method@Gtk.Widget.set_hexpand_set] for more detail. - Sets the visibility state of @widget. + line="5837">Sets the visibility state of @widget. -Note that setting this to %TRUE doesn’t mean the widget is +Note that setting this to true doesn’t mean the widget is actually viewable, see [method@Gtk.Widget.get_visible]. - + @@ -173957,13 +177697,13 @@ actually viewable, see [method@Gtk.Widget.get_visible]. a `GtkWidget` + line="5839">a widget whether the widget should be shown or not + line="5840">whether the widget should be shown or not @@ -173971,16 +177711,17 @@ actually viewable, see [method@Gtk.Widget.get_visible]. Returns whether @widget should contribute to + line="12878">Returns whether the widget should contribute to the measuring and allocation of its parent. -This is %FALSE for invisible children, but also -for children that have their own surface. - +This is false for invisible children, but also +for children that have their own surface, such +as [class@Gtk.Popover] instances. + %TRUE if child should be included in + line="12889">true if child should be included in measuring and allocating @@ -173988,7 +177729,7 @@ for children that have their own surface. a widget + line="12880">a widget @@ -173999,18 +177740,18 @@ for children that have their own surface. deprecated-version="4.10"> Flags a widget to be displayed. + line="2709">Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. -When a toplevel container is shown, it is immediately realized and +When a toplevel widget is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their -toplevel container is realized and mapped. +toplevel widget is realized and mapped. Use [method@Gtk.Widget.set_visible] instead - + @@ -174018,7 +177759,7 @@ toplevel container is realized and mapped. a `GtkWidget` + line="2711">a widget @@ -174026,11 +177767,11 @@ toplevel container is realized and mapped. Allocates widget with a transformation that translates + line="3763">Allocates widget with a transformation that translates the origin to the position in @allocation. This is a simple form of [method@Gtk.Widget.allocate]. - + @@ -174038,19 +177779,19 @@ This is a simple form of [method@Gtk.Widget.allocate]. a `GtkWidget` + line="3765">a widget position and size to be allocated to @widget + line="3766">position and size to be allocated to @widget The baseline of the child, or -1 + line="3767">the baseline of the child, or -1 @@ -174058,7 +177799,7 @@ This is a simple form of [method@Gtk.Widget.allocate]. Snapshot the a child of @widget. + line="12441">Snapshots a child of the widget. When a widget receives a call to the snapshot function, it must send synthetic [vfunc@Gtk.Widget.snapshot] calls @@ -174068,11 +177809,11 @@ of doing this. A widget, when it receives a call to its gtk_widget_snapshot_child() once for each child, passing in the @snapshot the widget received. -gtk_widget_snapshot_child() takes care of translating the origin of -@snapshot, and deciding whether the child needs to be snapshot. +This function takes care of translating the origin of @snapshot, +and deciding whether the child needs to be snapshot. -This function does nothing for children that implement `GtkNative`. - +It does nothing for children that implement `GtkNative`. + @@ -174080,21 +177821,21 @@ This function does nothing for children that implement `GtkNative`. a `GtkWidget` + line="12443">a widget a child of @widget + line="12444">a child of @widget `GtkSnapshot` as passed to the widget. In particular, no - calls to gtk_snapshot_translate() or other transform calls should - have been made. + line="12445">snapshot as passed to the widget. In particular, no + calls to [method@Gtk.Snapshot.translate] or other transform calls + should have been made @@ -174105,44 +177846,44 @@ This function does nothing for children that implement `GtkNative`. deprecated-version="4.12"> Translate coordinates relative to @src_widget’s allocation + line="4323">Translates coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations. In order to perform this operation, both widget must share -a common ancestor. - Use gtk_widget_compute_point() instead - +a common ancestor. If that is not the case, @dest_x and @dest_y +are set to 0 and false is returned. + Use [method@Gtk.Widget.compute_point] instead + %FALSE if @src_widget and @dest_widget have no common - ancestor. In this case, 0 is stored in *@dest_x and *@dest_y. - Otherwise %TRUE. + line="4339">true if @src_widget and @dest_widget have a common + ancestor, false otherwise a `GtkWidget` + line="4325">a widget a `GtkWidget` + line="4326">another widget X position relative to @src_widget + line="4327">X position in widget coordinates of @src_widget Y position relative to @src_widget + line="4328">Y position in widget coordinates of @src_widget allow-none="1"> location to store X position relative to @dest_widget + line="4329">location to store X position in widget coordinates of @dest_widget allow-none="1"> location to store Y position relative to @dest_widget + line="4330">location to store Y position in widget coordinates of @dest_widget @@ -174173,9 +177914,8 @@ a common ancestor. c:identifier="gtk_widget_trigger_tooltip_query"> Triggers a tooltip query on the display where the toplevel -of @widget is located. - + line="10027">Triggers a tooltip query on the display of the widget. + @@ -174183,7 +177923,7 @@ of @widget is located. a `GtkWidget` + line="10029">a widget @@ -174191,10 +177931,10 @@ of @widget is located. Causes a widget to be unmapped if it’s currently mapped. + line="2902">Causes a widget to be unmapped if it’s currently mapped. This function is only for use in widget implementations. - + @@ -174202,7 +177942,7 @@ This function is only for use in widget implementations. a `GtkWidget` + line="2904">a widget @@ -174210,11 +177950,11 @@ This function is only for use in widget implementations. Dissociate @widget from its parent. + line="2566">Removes @widget from its parent. This function is only for use in widget implementations, typically in dispose. - + @@ -174222,7 +177962,7 @@ typically in dispose. a `GtkWidget` + line="2568">a widget @@ -174230,11 +177970,12 @@ typically in dispose. Causes a widget to be unrealized (frees all GDK resources -associated with the widget). + line="3495">Causes a widget to be unrealized. + +This frees all GDK resources associated with the widget. This function is only useful in widget implementations. - + @@ -174242,7 +177983,7 @@ This function is only useful in widget implementations. a `GtkWidget` + line="3497">a widget @@ -174251,12 +177992,12 @@ This function is only useful in widget implementations. c:identifier="gtk_widget_unset_state_flags"> Turns off flag values for the current widget state. + line="5786">Turns off flag values for the current widget state. See [method@Gtk.Widget.set_state_flags]. This function is for use in widget implementations. - + @@ -174264,13 +178005,13 @@ This function is for use in widget implementations. a `GtkWidget` + line="5788">a widget State flags to turn off + line="5789">state flags to turn off @@ -174281,13 +178022,9 @@ This function is for use in widget implementations. setter="set_can_focus" getter="get_can_focus" default-value="TRUE"> - - Whether the widget or any of its descendents can accept + line="1312">Whether the widget or any of its descendents can accept the input focus. This property is meant to be set by widget implementations, @@ -174300,13 +178037,9 @@ typically in their instance init function. setter="set_can_target" getter="get_can_target" default-value="TRUE"> - - Whether the widget can receive pointer events. + line="1346">Whether the widget can receive pointer events. transfer-ownership="none" setter="set_css_classes" getter="get_css_classes"> - - A list of css classes applied to this widget. + line="1633">A list of css classes applied to this widget. @@ -174331,11 +178060,9 @@ typically in their instance init function. transfer-ownership="none" getter="get_css_name" default-value="NULL"> - The name of this widget in the CSS tree. + line="1620">The name of this widget in the CSS tree. This property is meant to be set by widget implementations, typically in their instance init function. @@ -174346,11 +178073,9 @@ typically in their instance init function. transfer-ownership="none" setter="set_cursor" getter="get_cursor"> - - The cursor used by @widget. + line="1388">The cursor used by @widget. setter="set_focus_on_click" getter="get_focus_on_click" default-value="TRUE"> - - Whether the widget should grab focus when it is clicked with the mouse. + line="1356">Whether the widget should grab focus when it is clicked with the mouse. This property is only relevant for widgets that can take focus. @@ -174376,13 +178097,9 @@ This property is only relevant for widgets that can take focus. setter="set_focusable" getter="get_focusable" default-value="FALSE"> - - Whether this widget itself will accept the input focus. + line="1326">Whether this widget itself will accept the input focus. setter="set_halign" getter="get_halign" default-value="GTK_ALIGN_FILL"> - - How to distribute horizontal space if widget gets extra space. + line="1456">How to distribute horizontal space if widget gets extra space. - Whether the widget is the default widget. + line="1368">Whether the widget is the default widget. - Whether the widget has the input focus. + line="1336">Whether the widget has the input focus. setter="set_has_tooltip" getter="get_has_tooltip" default-value="FALSE"> - - Enables or disables the emission of the ::query-tooltip signal on @widget. + line="1398">Enables or disables the emission of the [signal@Gtk.Widget::query-tooltip] +signal on @widget. -A value of %TRUE indicates that @widget can have a tooltip, in this case +A true value indicates that @widget can have a tooltip, in this case the widget will be queried using [signal@Gtk.Widget::query-tooltip] to determine whether it will provide a tooltip or not. @@ -174443,7 +178153,7 @@ determine whether it will provide a tooltip or not. default-value="-1"> Override for height request of the widget. + line="1279">Overrides for height request of the widget. If this is -1, the natural request will be used. @@ -174454,11 +178164,9 @@ If this is -1, the natural request will be used. setter="set_hexpand" getter="get_hexpand" default-value="FALSE"> - - Whether to expand horizontally. + line="1544">Whether to expand horizontally. setter="set_hexpand_set" getter="get_hexpand_set" default-value="FALSE"> - - Whether to use the `hexpand` property. + line="1554">Whether to use the `hexpand` property. transfer-ownership="none" setter="set_layout_manager" getter="get_layout_manager"> - - The `GtkLayoutManager` instance to use to compute the preferred size -of the widget, and allocate its children. + line="1643">The [class@Gtk.LayoutManager] instance to use to compute +the preferred size of the widget, and allocate its children. This property is meant to be set by widget implementations, typically in their instance init function. + + Makes this widget act like a modal dialog, with respect to +event delivery. + +Global event controllers will not handle events with targets +inside the widget, unless they are set up to ignore propagation +limits. See [method@Gtk.EventController.set_propagation_limit]. + + - - Margin on bottom side of widget. + line="1529">Margin on bottom side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from @@ -174519,13 +178232,9 @@ request, the margin will be added in addition to the size from setter="set_margin_end" getter="get_margin_end" default-value="0"> - - Margin on end of widget, horizontally. + line="1496">Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions. @@ -174541,13 +178250,9 @@ request, the margin will be added in addition to the size from setter="set_margin_start" getter="get_margin_start" default-value="0"> - - Margin on start of widget, horizontally. + line="1478">Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions. @@ -174563,13 +178268,9 @@ request, the margin will be added in addition to the size from setter="set_margin_top" getter="get_margin_top" default-value="0"> - - Margin on top side of widget. + line="1514">Margin on top side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from @@ -174582,11 +178283,9 @@ request, the margin will be added in addition to the size from setter="set_name" getter="get_name" default-value="NULL"> - - The name of the widget. + line="1234">The name of the widget. - - The requested opacity of the widget. + line="1584">The requested opacity of the widget. - - How content outside the widget's content area is treated. + line="1595">How content outside the widget's content area is treated. This property is meant to be set by widget implementations, typically in their instance init function. - The parent widget of this widget. + line="1244">The parent widget of this widget. setter="set_receives_default" getter="get_receives_default" default-value="FALSE"> - - Whether the widget will receive the default action when it is focused. + line="1378">Whether the widget will receive the default action when it is focused. - The `GtkRoot` widget of the widget tree containing this widget. + line="1254">The `GtkRoot` widget of the widget tree containing this widget. -This will be %NULL if the widget is not contained in a root widget. +This will be `NULL` if the widget is not contained in a root widget. - The scale factor of the widget. + line="1609">The scale factor of the widget. - - Whether the widget responds to input. + line="1302">Whether the widget responds to input. setter="set_tooltip_markup" getter="get_tooltip_markup" default-value="NULL"> - - Sets the text of tooltip to be the given string, which is marked up + line="1434">Sets the text of tooltip to be the given string, which is marked up with Pango markup. Also see [method@Gtk.Tooltip.set_markup]. This is a convenience property which will take care of getting the -tooltip shown if the given string is not %NULL: -[property@Gtk.Widget:has-tooltip] will automatically be set to %TRUE +tooltip shown if the given string is not `NULL`: +[property@Gtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. @@ -174710,19 +178387,15 @@ Note that if both [property@Gtk.Widget:tooltip-text] and setter="set_tooltip_text" getter="get_tooltip_text" default-value="NULL"> - - Sets the text of tooltip to be the given string. + line="1413">Sets the text of tooltip to be the given string. Also see [method@Gtk.Tooltip.set_text]. This is a convenience property which will take care of getting the -tooltip shown if the given string is not %NULL: -[property@Gtk.Widget:has-tooltip] will automatically be set to %TRUE +tooltip shown if the given string is not `NULL`: +[property@Gtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. @@ -174736,11 +178409,9 @@ Note that if both [property@Gtk.Widget:tooltip-text] and setter="set_valign" getter="get_valign" default-value="GTK_ALIGN_FILL"> - - How to distribute vertical space if widget gets extra space. + line="1467">How to distribute vertical space if widget gets extra space. - - Whether to expand vertically. + line="1564">Whether to expand vertically. - - Whether to use the `vexpand` property. + line="1574">Whether to use the `vexpand` property. - - Whether the widget is visible. + line="1292">Whether the widget is visible. Override for width request of the widget. + line="1266">Overrides for width request of the widget. If this is -1, the natural request will be used. @@ -174804,7 +178467,7 @@ If this is -1, the natural request will be used. Signals that all holders of a reference to the widget should release + line="1678">Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released. @@ -174817,7 +178480,7 @@ This signal is not suitable for saving widget state. Emitted when the text direction of a widget changes. + line="1827">Emitted when the text direction of a widget changes. @@ -174825,7 +178488,7 @@ This signal is not suitable for saving widget state. the previous text direction of @widget + line="1830">the previous text direction @@ -174833,7 +178496,7 @@ This signal is not suitable for saving widget state. Emitted when @widget is hidden. + line="1713">Emitted when @widget is hidden. @@ -174841,22 +178504,22 @@ This signal is not suitable for saving widget state. Emitted if keyboard navigation fails. + line="1893">Emitted if keyboard navigation fails. See [method@Gtk.Widget.keynav_failed] for details. %TRUE if stopping keyboard navigation is fine, %FALSE + line="1902">true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent widget(s). + navigation attempt in its parent widget the direction of movement + line="1896">the direction of movement @@ -174864,13 +178527,13 @@ See [method@Gtk.Widget.keynav_failed] for details. Emitted when @widget is going to be mapped. + line="1728">Emitted when @widget is going to be mapped. A widget is mapped when the widget is visible (which is controlled with [property@Gtk.Widget:visible]) and all its parents up to the toplevel widget are also visible. -The ::map signal can be used to determine whether a widget will be drawn, +The `::map` signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of [signal@Gtk.Widget::unmap]. @@ -174880,22 +178543,22 @@ emission of [signal@Gtk.Widget::unmap]. Emitted when a widget is activated via a mnemonic. + line="1844">Emitted when a widget is activated via a mnemonic. The default handler for this signal activates @widget if @group_cycling -is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. +is false, or just makes @widget grab focus if @group_cycling is true. %TRUE to stop other handlers from being invoked for the event. -%FALSE to propagate the event further. + line="1854">true to stop other handlers from being invoked for the event, + false to propagate the event further %TRUE if there are other widgets with the same mnemonic + line="1847">true if there are other widgets with the same mnemonic @@ -174903,9 +178566,9 @@ is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. Emitted when the focus is moved. + line="1870">Emitted when the focus is moved. -The ::move-focus signal is a [keybinding signal](class.SignalAction.html). +The `::move-focus` signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Tab</kbd> to move forward, and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward. @@ -174916,7 +178579,7 @@ and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward. the direction of the focus move + line="1873">the direction of the focus move @@ -174924,51 +178587,48 @@ and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward. Emitted when the widget’s tooltip is about to be shown. + line="1919">Emitted when the widget’s tooltip is about to be shown. This happens when the [property@Gtk.Widget:has-tooltip] property -is %TRUE and the hover timeout has expired with the cursor hovering -"above" @widget; or emitted when @widget got focus in keyboard mode. +is true and the hover timeout has expired with the cursor hovering +above @widget; or emitted when @widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case -%TRUE should be returned, %FALSE otherwise. Note that if -@keyboard_mode is %TRUE, the values of @x and @y are undefined and -should not be used. +true should be returned, false otherwise. Note that if @keyboard_mode +is true, the values of @x and @y are undefined and should not be used. The signal handler is free to manipulate @tooltip with the therefore destined function calls. %TRUE if @tooltip should be shown right now, %FALSE otherwise. + line="1941">true if @tooltip should be shown right now, false otherwise the x coordinate of the cursor position where the request has - been emitted, relative to @widget's left side + line="1922">the x coordinate of the cursor position in widget coordinates the y coordinate of the cursor position where the request has - been emitted, relative to @widget's top + line="1923">the y coordinate of the cursor position in widget coordinates %TRUE if the tooltip was triggered using the keyboard + line="1924">true if the tooltip was triggered using the keyboard a `GtkTooltip` + line="1925">a `GtkTooltip` @@ -174976,7 +178636,7 @@ destined function calls. Emitted when @widget is associated with a `GdkSurface`. + line="1772">Emitted when @widget is associated with a `GdkSurface`. This means that [method@Gtk.Widget.realize] has been called or the widget has been mapped (that is, it is going to be drawn). @@ -174987,7 +178647,7 @@ or the widget has been mapped (that is, it is going to be drawn). Emitted when @widget is shown. + line="1698">Emitted when @widget is shown. @@ -174995,7 +178655,7 @@ or the widget has been mapped (that is, it is going to be drawn). Emitted when the widget state changes. + line="1808">Emitted when the widget state changes. See [method@Gtk.Widget.get_state_flags]. @@ -175005,7 +178665,7 @@ See [method@Gtk.Widget.get_state_flags]. The previous state flags. + line="1811">the previous state flags @@ -175013,12 +178673,12 @@ See [method@Gtk.Widget.get_state_flags]. Emitted when @widget is going to be unmapped. + line="1751">Emitted when @widget is going to be unmapped. A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden. -As ::unmap indicates that a widget will not be shown any longer, +As `::unmap` indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget. @@ -175027,7 +178687,7 @@ it can be used to, for example, stop an animation on the widget. Emitted when the `GdkSurface` associated with @widget is destroyed. + line="1790">Emitted when the `GdkSurface` associated with @widget is destroyed. This means that [method@Gtk.Widget.unrealize] has been called or the widget has been unmapped (that is, it is going to be hidden). @@ -175040,11 +178700,11 @@ or the widget has been unmapped (that is, it is going to be hidden). c:type="GtkWidgetActionActivateFunc"> The type of the callback functions used for activating -actions installed with gtk_widget_class_install_action(). + line="941">The type of the callback functions used for activating +actions installed with [method@Gtk.WidgetClass.install_action]. The @parameter must match the @parameter_type of the action. - + @@ -175052,13 +178712,13 @@ The @parameter must match the @parameter_type of the action. the widget to which the action belongs + line="943">the widget to which the action belongs the action name + line="944">the action name allow-none="1"> parameter for activation + line="945">parameter for activation @@ -175075,11 +178735,11 @@ The @parameter must match the @parameter_type of the action. - + The object class structure needs to be the first + line="116">The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a GtkWidgetClass pointer to be cast to a GObjectClass pointer. @@ -175087,8 +178747,11 @@ The @parameter must match the @parameter_type of the action. c:type="GInitiallyUnownedClass"/> + Signal emitted when widget is shown - + @@ -175096,15 +178759,18 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="2711">a widget + Signal emitted when widget is hidden. - + @@ -175112,15 +178778,21 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="2782">a widget + Signal emitted when widget is going to be mapped, that is + when the widget is visible (which is controlled with + gtk_widget_set_visible()) and all its parents up to the toplevel + widget are also visible. - + @@ -175128,15 +178800,20 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="2868">a widget + Signal emitted when widget is going to be unmapped, which + means that either it or any of its parents up to the toplevel + widget have been set as hidden. - + @@ -175144,15 +178821,20 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="2904">a widget + Signal emitted when widget is associated with a + `GdkSurface`, which means that gtk_widget_realize() has been called or + the widget has been mapped (that is, it is going to be drawn). - + @@ -175160,15 +178842,21 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="3439">a widget + Signal emitted when the GdkSurface associated with + widget is destroyed, which means that gtk_widget_unrealize() has + been called or the widget has been unmapped (that is, it is going + to be hidden). - + @@ -175176,15 +178864,19 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="3497">a widget + Called when the widget gets added to a `GtkRoot` widget. Must + chain up - + @@ -175196,8 +178888,12 @@ The @parameter must match the @parameter_type of the action. + Called when the widget is about to be removed from its + `GtkRoot` widget. Must chain up - + @@ -175209,8 +178905,12 @@ The @parameter must match the @parameter_type of the action. + Called to set the allocation, if the widget does + not have a layout manager. - + @@ -175231,8 +178931,12 @@ The @parameter must match the @parameter_type of the action. + Signal emitted when the widget state changes, + see gtk_widget_get_state_flags(). - + @@ -175247,8 +178951,12 @@ The @parameter must match the @parameter_type of the action. + Signal emitted when the text direction of a + widget changes. - + @@ -175263,27 +178971,51 @@ The @parameter must match the @parameter_type of the action. + Called to get the request mode, if the widget + does not have a layout manager. + This allows a widget to tell its parent container whether + it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or + %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. + %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH means the widget prefers to have + `GtkWidgetClass.measure()` called first to get the default width (passing + a for_size of -1), then again to get the height for said default width. + %GTK_SIZE_REQUEST_CONSTANT_SIZE disables any height-for-width or + width-for-height geometry management for said widget and is the + default return. + It’s important to note that any widget + which trades height-for-width or width-for-height must respond properly + to a for_size value >= -1 passed to `GtkWidgetClass.measure`, for both + possible orientations. - + The `GtkSizeRequestMode` preferred by @widget. + line="585">The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance + line="575">a `GtkWidget` instance + Called to obtain the minimum and natural size of the widget, + if the widget does not have a layout manager. + Depending on the orientation parameter, the passed for_size can be + interpreted as width or height. A widget will never be allocated less + than its minimum size. - + @@ -175291,19 +179023,19 @@ The @parameter must match the @parameter_type of the action. A `GtkWidget` instance + line="454">A `GtkWidget` instance the orientation to measure + line="455">the orientation to measure Size for the opposite of @orientation, i.e. + line="456">Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height @@ -175318,7 +179050,7 @@ The @parameter must match the @parameter_type of the action. allow-none="1"> location to store the minimum size + line="461">location to store the minimum size allow-none="1"> location to store the natural size + line="462">location to store the natural size allow-none="1"> location to store the baseline + line="463">location to store the baseline position for the minimum size, or -1 to report no baseline @@ -175352,7 +179084,7 @@ The @parameter must match the @parameter_type of the action. allow-none="1"> location to store the baseline + line="465">location to store the baseline position for the natural size, or -1 to report no baseline @@ -175360,52 +179092,63 @@ The @parameter must match the @parameter_type of the action. + Activates the @widget if @group_cycling is + %FALSE, and just grabs the focus if @group_cycling is %TRUE. - + %TRUE if the signal has been handled + line="4591">true if the signal has been handled a `GtkWidget` + line="4586">a widget %TRUE if there are other widgets with the same mnemonic + line="4587">true if there are other widgets with the same mnemonic + Causes @widget to have the keyboard focus for the + `GtkWindow` it’s inside. - + %TRUE if focus is now inside @widget. + line="5039">true if focus is now inside @widget a `GtkWidget` + line="5027">a widget + Vfunc for gtk_widget_child_focus() - + @@ -175420,8 +179163,11 @@ The @parameter must match the @parameter_type of the action. + Sets the focused child of a widget. Must chain up - + @@ -175429,7 +179175,7 @@ The @parameter must match the @parameter_type of the action. a `GtkWidget` + line="12501">a widget allow-none="1"> a direct child widget of @widget or %NULL - to unset the focus child of @widget + line="12502">a direct child widget of @widget + or `NULL` to unset the focus child + Signal emitted when a change of focus is requested - + @@ -175462,35 +179211,43 @@ The @parameter must match the @parameter_type of the action. + Signal emitted if keyboard navigation fails. - + %TRUE if stopping keyboard navigation is fine, %FALSE + line="7132">true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent container(s). + navigation attempt in its parent widget a `GtkWidget` + line="7100">a widget direction of focus movement + line="7101">direction of focus movement + Signal emitted when “has-tooltip” is %TRUE and the + hover timeout has expired with the cursor hovering “above” + widget; or emitted when widget got focus in keyboard mode. - + @@ -175514,8 +179271,12 @@ The @parameter must match the @parameter_type of the action. + Computes whether a container should give this + widget extra space when possible. - + @@ -175533,8 +179294,14 @@ The @parameter must match the @parameter_type of the action. + Vfunc called when the CSS used by widget was changed. Widgets + should then discard their caches that depend on CSS and queue resizes or + redraws accordingly. The default implementation will take care of this for + all the default CSS properties, so implementations must chain up. - + @@ -175549,8 +179316,11 @@ The @parameter must match the @parameter_type of the action. + Emitted when a system setting was changed. Must chain up. - + @@ -175565,8 +179335,11 @@ The @parameter must match the @parameter_type of the action. + Vfunc called when a new snapshot of the widget has to be taken. - + @@ -175581,31 +179354,34 @@ The @parameter must match the @parameter_type of the action. + Vfunc for gtk_widget_contains(). - + %TRUE if @widget contains (@x, @y). + line="10312">true if @widget contains the point (x, y) the widget to query + line="10303">the widget to query X coordinate to test, relative to @widget's origin + line="10304">X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin + line="10305">Y coordinate to test, relative to @widget's origin @@ -175624,18 +179400,18 @@ The @parameter must match the @parameter_type of the action. introspectable="0"> Creates a new shortcut for @widget_class that calls the given @callback -with arguments read according to @format_string. + line="4408">Creates a new shortcut for @widget_class that calls the given @callback +with arguments according to @format_string. The arguments and format string must be provided in the same way as -with g_variant_new(). +with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class -initialization. It does not provide for user_data, if you need that, +initialization. It does not provide for user data, if you need that, you will have to use [method@Gtk.WidgetClass.add_shortcut] with a custom shortcut. - + @@ -175643,25 +179419,25 @@ shortcut. the class to add the binding to + line="4410">the class to add the binding to key value of binding to install + line="4411">key value of binding to install key modifier of binding to install + line="4412">key modifier of binding to install the callback to call upon activation + line="4413">the callback to call upon activation allow-none="1"> GVariant format string for arguments - or %NULL for no arguments + line="4414">`GVariant` format string for arguments arguments, as given by format string + line="4415">arguments, as given by format string @@ -175687,16 +179462,16 @@ shortcut. introspectable="0"> Creates a new shortcut for @widget_class that activates the given + line="4506">Creates a new shortcut for @widget_class that activates the given @action_name with arguments read according to @format_string. The arguments and format string must be provided in the same way as -with g_variant_new(). +with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. - + @@ -175704,25 +179479,25 @@ initialization. the class to add the binding to + line="4508">the class to add the binding to key value of binding to install + line="4509">key value of binding to install key modifier of binding to install + line="4510">key modifier of binding to install the action to activate + line="4511">the action to activate allow-none="1"> GVariant format string for arguments - or %NULL for no arguments + line="4512">`GVariant` format string for arguments arguments, as given by format string + line="4513">arguments, as given by format string @@ -175748,16 +179522,16 @@ initialization. introspectable="0"> Creates a new shortcut for @widget_class that emits the given action + line="4457">Creates a new shortcut for @widget_class that emits the given action @signal with arguments read according to @format_string. The arguments and format string must be provided in the same way as -with g_variant_new(). +with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. - + @@ -175765,25 +179539,25 @@ initialization. the class to add the binding to + line="4459">the class to add the binding to key value of binding to install + line="4460">key value of binding to install key modifier of binding to install + line="4461">key modifier of binding to install the signal to execute + line="4462">the signal to execute allow-none="1"> GVariant format string for arguments - or %NULL for no arguments + line="4463">`GVariant` format string for arguments arguments, as given by format string + line="4464">arguments, as given by format string @@ -175807,17 +179580,17 @@ initialization. Installs a shortcut in @widget_class. + line="4554">Installs a shortcut in @widget_class. Every instance created for @widget_class or its subclasses will inherit this shortcut and trigger it. -Shortcuts added this way will be triggered in the %GTK_PHASE_BUBBLE +Shortcuts added this way will be triggered in the [enum@Gtk.PropagationPhase.bubble] phase, which means they may also trigger if child widgets have focus. This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed. - + @@ -175825,13 +179598,13 @@ otherwise it is not guaranteed that the shortcut will be installed. the class to add the shortcut to + line="4556">the class to add the shortcut to the `GtkShortcut` to add + line="4557">the shortcut to add @@ -175840,15 +179613,16 @@ otherwise it is not guaranteed that the shortcut will be installed. c:identifier="gtk_widget_class_bind_template_callback_full"> Declares a @callback_symbol to handle @callback_name from -the template XML defined for @widget_type. + line="11551">Associates a name to be used in GtkBuilder XML with a symbol. This function is not supported after [method@Gtk.WidgetClass.set_template_scope] -has been used on @widget_class. See [method@Gtk.BuilderCScope.add_callback_symbol]. +has been used on @widget_class. + +See [method@Gtk.BuilderCScope.add_callback_symbol]. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. - + @@ -175856,13 +179630,13 @@ class initializer after calling [method@Gtk.WidgetClass.set_template]. A `GtkWidgetClass` + line="11553">a widget class The name of the callback as expected in the template XML + line="11554">name of the callback as expected in the template XML scope="async"> The callback symbol + line="11555">the callback symbol @@ -175879,8 +179653,8 @@ class initializer after calling [method@Gtk.WidgetClass.set_template]. c:identifier="gtk_widget_class_bind_template_child_full"> Automatically assign an object declared in the class template XML to -be set to a location on a freshly built instance’s private data, or + line="11620">Assigns an object declared in the class template XML to be set to +a location on a freshly built instance’s private data, or alternatively accessible via [method@Gtk.Widget.get_template_child]. The struct can point either into the public instance, then you should @@ -175889,14 +179663,14 @@ private struct, then you should use `G_PRIVATE_OFFSET(WidgetType, member)`. An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when -`GObjectClass.dispose()` runs on your instance and if a @struct_offset -that is `!= 0` is specified, then the automatic location in your instance -public or private data will be set to %NULL. You can however access an -automated child pointer the first time your classes `GObjectClass.dispose()` -runs, or alternatively in [signal@Gtk.Widget::destroy]. +`GObjectClass.dispose()` runs on your instance and if a nonzero @struct_offset +is specified, then the automatic location in your instance public or private +data will be set to `NULL`. You can however access an automated child pointer +the first time your classes `GObjectClass.dispose()` runs, or alternatively +in [signal@Gtk.Widget::destroy]. If @internal_child is specified, [vfunc@Gtk.Buildable.get_internal_child] -will be automatically implemented by the `GtkWidget` class so there is no +will be automatically implemented by the widget class so there is no need to implement it manually. The wrapper macros [func@Gtk.widget_class_bind_template_child], @@ -175907,7 +179681,7 @@ might be more convenient to use. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. - + @@ -175915,28 +179689,28 @@ initializer after calling [method@Gtk.WidgetClass.set_template]. A `GtkWidgetClass` + line="11622">a widget class The “id” of the child defined in the template XML + line="11623">ID of the child defined in the template XML Whether the child should be accessible as an “internal-child” + line="11624">whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML The structure offset into the composite widget’s instance + line="11626">The offset into the composite widget’s instance public or private structure where the automated child pointer should be set, - or 0 to not assign the pointer. + or 0 to not assign the pointer @@ -175945,24 +179719,24 @@ initializer after calling [method@Gtk.WidgetClass.set_template]. c:identifier="gtk_widget_class_get_accessible_role"> Retrieves the accessible role used by the given `GtkWidget` class. + line="13359">Retrieves the accessible role used by the given widget class. Different accessible roles have different states, and are rendered differently by assistive technologies. See also: [method@Gtk.Accessible.get_accessible_role]. - + the accessible role for the widget class + line="13370">the accessible role for the widget class a `GtkWidgetClass` + line="13361">a widget class @@ -175971,15 +179745,15 @@ See also: [method@Gtk.Accessible.get_accessible_role]. c:identifier="gtk_widget_class_get_activate_signal"> Retrieves the signal id for the activation signal. + line="4910">Retrieves the signal id for the activation signal. -the activation signal is set using +The activation signal is set using [method@Gtk.WidgetClass.set_activate_signal]. - + a signal id, or 0 if the widget class does not + line="4919">a signal id, or 0 if the widget class does not specify an activation signal @@ -175987,7 +179761,7 @@ the activation signal is set using a `GtkWidgetClass` + line="4912">a widget class @@ -175995,21 +179769,21 @@ the activation signal is set using Gets the name used by this class for matching in CSS code. + line="11021">Gets the name used by this class for matching in CSS code. See [method@Gtk.WidgetClass.set_css_name] for details. - + the CSS name of the given class + line="11029">the CSS name of the given class class to set the name on + line="11023">class to set the name on @@ -176018,22 +179792,22 @@ See [method@Gtk.WidgetClass.set_css_name] for details. c:identifier="gtk_widget_class_get_layout_manager_type"> Retrieves the type of the [class@Gtk.LayoutManager] + line="12799">Retrieves the type of the [class@Gtk.LayoutManager] used by widgets of class @widget_class. See also: [method@Gtk.WidgetClass.set_layout_manager_type]. - + type of a `GtkLayoutManager` subclass, or %G_TYPE_INVALID + line="12808">type of a `GtkLayoutManager` subclass, or `G_TYPE_INVALID` a `GtkWidgetClass` + line="12801">a widget class @@ -176042,13 +179816,14 @@ See also: [method@Gtk.WidgetClass.set_layout_manager_type]. c:identifier="gtk_widget_class_install_action"> This should be called at class initialization time to specify -actions to be added for all instances of this class. + line="12918">Adds an action for all instances of a widget class. + +This function should be called at class initialization time. Actions installed by this function are stateless. The only state -they have is whether they are enabled or not (which can be changed with -[method@Gtk.Widget.action_set_enabled]). - +they have is whether they are enabled or not (which can be changed +with [method@Gtk.Widget.action_set_enabled]). + @@ -176056,13 +179831,13 @@ they have is whether they are enabled or not (which can be changed with a `GtkWidgetClass` + line="12920">a widget class a prefixed action name, such as "clipboard.paste" + line="12921">a prefixed action name, such as "clipboard.paste" the parameter type + line="12922">the parameter type callback to use when the action is activated + line="12923">callback to use when the action is activated @@ -176089,7 +179864,7 @@ they have is whether they are enabled or not (which can be changed with c:identifier="gtk_widget_class_install_property_action"> Installs an action called @action_name on @widget_class and + line="12984">Installs an action called @action_name on @widget_class and binds its state to the value of the @property_name property. This function will perform a few sanity checks on the property selected @@ -176104,7 +179879,7 @@ The state type of the action matches the property type. If the property is boolean, the action will have no parameter and toggle the property value. Otherwise, the action will have a parameter of the same type as the property. - + @@ -176112,20 +179887,20 @@ of the same type as the property. a `GtkWidgetClass` + line="12986">a widget class name of the action + line="12987">name of the action name of the property in instances of @widget_class - or any parent class. + line="12988">name of a property in instances of @widget_class + or any parent class @@ -176133,8 +179908,8 @@ of the same type as the property. Returns details about the @index_-th action that has been -installed for @widget_class during class initialization. + line="13075">Returns details about an action that has been +installed for @widget_class. See [method@Gtk.WidgetClass.install_action] for details on how to install actions. @@ -176142,25 +179917,24 @@ how to install actions. Note that this function will also return actions defined by parent classes. You can identify those by looking at @owner. - + %TRUE if the action was found, %FALSE if @index_ - is out of range + line="13094">true if the action was found a `GtkWidget` class + line="13077">a widget class position of the action to query + line="13078">position of the action to query transfer-ownership="none"> return location for the type where the action was defined + line="13079">return location for the type where the action was defined transfer-ownership="none"> return location for the action name + line="13080">return location for the action name nullable="1"> return location for the parameter type + line="13081">return location for the parameter type nullable="1"> return location for the property name + line="13082">return location for the property name @@ -176207,11 +179981,11 @@ at @owner. c:identifier="gtk_widget_class_set_accessible_role"> Sets the accessible role used by the given `GtkWidget` class. + line="13336">Sets the accessible role used by the given widget class. Different accessible roles have different states, and are rendered differently by assistive technologies. - + @@ -176219,13 +179993,13 @@ rendered differently by assistive technologies. a `GtkWidgetClass` + line="13338">a widget class the `GtkAccessibleRole` used by the @widget_class + line="13339">the accessible role to use @@ -176234,14 +180008,13 @@ rendered differently by assistive technologies. c:identifier="gtk_widget_class_set_activate_signal"> Sets the `GtkWidgetClass.activate_signal` field with the -given @signal_id. + line="4930">Sets the activation signal for a widget class. The signal will be emitted when calling [method@Gtk.Widget.activate]. -The @signal_id must have been registered with `g_signal_new()` -or g_signal_newv() before calling this function. - +The @signal_id must have been registered with [function.GObject.signal_new] +or [func@GObject.signal_newv] before calling this function. + @@ -176249,13 +180022,13 @@ or g_signal_newv() before calling this function. a `GtkWidgetClass` + line="4932">a widget class the id for the activate signal + line="4933">the id for the activate signal @@ -176264,14 +180037,15 @@ or g_signal_newv() before calling this function. c:identifier="gtk_widget_class_set_activate_signal_from_name"> Sets the `GtkWidgetClass.activate_signal` field with the signal id for -the given @signal_name. + line="4952">Sets the activation signal for a widget class. + +The signal id will by looked up by @signal_name. The signal will be emitted when calling [method@Gtk.Widget.activate]. -The @signal_name of @widget_type must have been registered with -g_signal_new() or g_signal_newv() before calling this function. - +The @signal_name must have been registered with [function.GObject.signal_new] +or [func@GObject.signal_newv] before calling this function. + @@ -176279,13 +180053,13 @@ g_signal_new() or g_signal_newv() before calling this function. a `GtkWidgetClass` + line="4954">a widget class the name of the activate signal of @widget_type + line="4955">the name of the activate signal of @widget_type @@ -176293,12 +180067,12 @@ g_signal_new() or g_signal_newv() before calling this function. Sets the name to be used for CSS matching of widgets. + line="10996">Sets the name to be used for CSS matching of widgets. If this function is not called for a given class, the name set on the parent class is used. By default, `GtkWidget` uses the name "widget". - + @@ -176306,13 +180080,13 @@ uses the name "widget". class to set the name on + line="10998">class to set the name on name to use + line="10999">name to use @@ -176321,14 +180095,14 @@ uses the name "widget". c:identifier="gtk_widget_class_set_layout_manager_type"> Sets the type to be used for creating layout managers for + line="12771">Sets the type to be used for creating layout managers for widgets of @widget_class. The given @type must be a subtype of [class@Gtk.LayoutManager]. This function should only be called from class init functions of widgets. - + @@ -176336,13 +180110,13 @@ of widgets. a `GtkWidgetClass` + line="12773">a widget class The object type that implements the `GtkLayoutManager` + line="12774">the object type that implements the `GtkLayoutManager` for @widget_class @@ -176351,7 +180125,7 @@ of widgets. This should be called at class initialization time to specify + line="11461">This should be called at class initialization time to specify the `GtkBuilder` XML to be used to extend a widget. For convenience, [method@Gtk.WidgetClass.set_template_from_resource] @@ -176359,7 +180133,7 @@ is also provided. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance initializer. - + @@ -176367,13 +180141,13 @@ Note that any class that installs templates must call A `GtkWidgetClass` + line="11463">a widget class A `GBytes` holding the `GtkBuilder` XML + line="11464">`GBytes` holding the `GtkBuilder` XML @@ -176382,13 +180156,13 @@ Note that any class that installs templates must call c:identifier="gtk_widget_class_set_template_from_resource"> A convenience function that calls [method@Gtk.WidgetClass.set_template] -with the contents of a `GResource`. + line="11508">A convenience function that calls [method@Gtk.WidgetClass.set_template] +with the contents of a resource. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance initializer. - + @@ -176396,13 +180170,13 @@ initializer. A `GtkWidgetClass` + line="11510">a widget class The name of the resource to load the template from + line="11511">resource path to load the template from @@ -176411,13 +180185,13 @@ initializer. c:identifier="gtk_widget_class_set_template_scope"> For use in language bindings, this will override the default -`GtkBuilderScope` to be used when parsing GtkBuilder XML from -this class’s template data. + line="11595">Overrides the default scope to be used when parsing the class template. + +This function is intended for language bindings. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. - + @@ -176425,13 +180199,13 @@ initializer after calling [method@Gtk.WidgetClass.set_template]. A `GtkWidgetClass` + line="11597">a widget class The `GtkBuilderScope` to use when loading + line="11598">`GtkBuilderScope` to use when loading the class template @@ -176453,8 +180227,7 @@ initializer after calling [method@Gtk.WidgetClass.set_template]. glib:type-struct="WidgetPaintableClass"> `GtkWidgetPaintable` is a `GdkPaintable` that displays the contents -of a widget. + line="29">A `GdkPaintable` that displays the contents of a widget. `GtkWidgetPaintable` will also take care of the widget not being in a state where it can be drawn (like when it isn't shown) and just draw @@ -176478,12 +180251,12 @@ end up with an infinitely growing widget. Creates a new widget paintable observing the given widget. + line="258">Creates a new widget paintable observing the given widget. a new `GtkWidgetPaintable` + line="264">a new `GtkWidgetPaintable` @@ -176493,7 +180266,7 @@ end up with an infinitely growing widget. allow-none="1"> a `GtkWidget` + line="260">a `GtkWidget` @@ -176501,22 +180274,21 @@ end up with an infinitely growing widget. - Returns the widget that is observed or %NULL if none. + line="293">Returns the widget that is observed or %NULL if none. the observed widget. + line="299">the observed widget. a `GtkWidgetPaintable` + line="295">a `GtkWidgetPaintable` @@ -176524,10 +180296,9 @@ end up with an infinitely growing widget. - Sets the widget that should be observed. + line="309">Sets the widget that should be observed. @@ -176536,7 +180307,7 @@ end up with an infinitely growing widget. a `GtkWidgetPaintable` + line="311">a `GtkWidgetPaintable` allow-none="1"> the widget to observe + line="312">the widget to observe @@ -176555,13 +180326,9 @@ end up with an infinitely growing widget. transfer-ownership="none" setter="set_widget" getter="get_widget"> - - The observed widget or %NULL if none. + line="239">The observed widget or %NULL if none. @@ -176588,9 +180355,12 @@ end up with an infinitely growing widget. glib:type-struct="WindowClass"> A `GtkWindow` is a toplevel window which can contain other widgets. + line="112">A toplevel window which can contain other widgets. -![An example GtkWindow](window.png) +<picture> + <source srcset="window-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkWindow" src="window.png"> +</picture> Windows normally have decorations that are under the control of the windowing system and allow the user to manipulate the window @@ -176602,6 +180372,28 @@ The `GtkWindow` implementation of the [iface@Gtk.Buildable] interface supports setting a child as the titlebar by specifying “titlebar” as the “type” attribute of a `<child>` element. +# Shortcuts and Gestures + +`GtkWindow` supports the following keyboard shortcuts: + +- <kbd>F10</kbd> activates the menubar, if present. +- <kbd>Alt</kbd> makes the mnemonics visible while pressed. + +The following signals have default keybindings: + +- [signal@Gtk.Window::activate-default] +- [signal@Gtk.Window::activate-focus] +- [signal@Gtk.Window::enable-debugging] + +# Actions + +`GtkWindow` defines a set of built-in actions: + +- `default.activate` activates the default widget. +- `window.minimize` minimizes the window. +- `window.toggle-maximized` maximizes or restores the window. +- `window.close` closes the window. + # CSS nodes ``` @@ -176634,18 +180426,10 @@ widget that is added as a titlebar child. # Accessibility -Until GTK 4.10, `GtkWindow` used the `GTK_ACCESSIBLE_ROLE_WINDOW` role. - -Since GTK 4.12, `GtkWindow` uses the `GTK_ACCESSIBLE_ROLE_APPLICATION` role. - -# Actions +`GtkWindow` uses the [enum@Gtk.AccessibleRole.window] role. -`GtkWindow` defines a set of built-in actions: -- `default.activate`: Activate the default widget. -- `window.minimize`: Minimize the window. -- `window.toggle-maximized`: Maximize or restore the window. -- `window.close`: Close the window. - +From GTK 4.12 to 4.18, it used the [enum@Gtk.AccessibleRole.application] role. + @@ -176655,23 +180439,23 @@ Since GTK 4.12, `GtkWindow` uses the `GTK_ACCESSIBLE_ROLE_APPLICATION` role. Creates a new `GtkWindow`. + line="2257">Creates a new `GtkWindow`. -To get an undecorated window (no window borders), use -[method@Gtk.Window.set_decorated]. +To get an undecorated window (without window borders), +use [method@Gtk.Window.set_decorated]. -All top-level windows created by gtk_window_new() are stored +All top-level windows created by this function are stored in an internal top-level window list. This list can be obtained from [func@Gtk.Window.list_toplevels]. Due to GTK keeping a -reference to the window internally, gtk_window_new() does not +reference to the window internally, this function does not return a reference to the caller. To delete a `GtkWindow`, call [method@Gtk.Window.destroy]. - + a new `GtkWindow`. + line="2273">a new `GtkWindow` @@ -176679,33 +180463,33 @@ To delete a `GtkWindow`, call [method@Gtk.Window.destroy]. c:identifier="gtk_window_get_default_icon_name"> Returns the fallback icon name for windows. + line="3579">Returns the fallback icon name for windows. The returned string is owned by GTK and should not be modified. It is only valid until the next call to [func@Gtk.Window.set_default_icon_name]. - + the fallback icon name for windows + line="3588">the fallback icon name for windows Returns a list of all existing toplevel windows. + line="2553">Returns the list of all existing toplevel windows. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets or add new ones, be aware that the list of toplevels will change and emit the "items-changed" signal. - + the list + line="2562">the list of toplevel widgets @@ -176713,18 +180497,18 @@ the list of toplevels will change and emit the "items-changed" signal. Returns a list of all existing toplevel windows. + line="2574">Returns the list of all existing toplevel windows. The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. - + list of + line="2585">list of toplevel widgets @@ -176735,9 +180519,9 @@ and then unref all the widgets afterwards. c:identifier="gtk_window_set_auto_startup_notification"> Sets whether the window should request startup notification. + line="6052">Sets whether the window should request startup notification. -By default, after showing the first `GtkWindow`, GTK calls +By default, after showing the first window, GTK calls [method@Gdk.Toplevel.set_startup_id]. Call this function to disable the automatic startup notification. You might do this if your first window is a splash screen, and you want to delay @@ -176747,7 +180531,7 @@ for example. In that example, you would disable startup notification temporarily, show your splash screen, then re-enable it so that showing the main window would automatically result in notification. - + @@ -176755,7 +180539,7 @@ showing the main window would automatically result in notification. %TRUE to automatically do startup notification + line="6054">true to automatically do startup notification @@ -176764,12 +180548,12 @@ showing the main window would automatically result in notification. c:identifier="gtk_window_set_default_icon_name"> Sets an icon to be used as fallback. + line="3539">Sets an icon to be used as fallback. The fallback icon is used for windows that haven't had [method@Gtk.Window.set_icon_name] called on them. - + @@ -176777,7 +180561,7 @@ called on them. the name of the themed icon + line="3541">the name of the themed icon @@ -176786,11 +180570,19 @@ called on them. c:identifier="gtk_window_set_interactive_debugging"> Opens or closes the [interactive debugger](running.html#interactive-debugging). + line="6350">Opens or closes the [interactive debugger](running.html#interactive-debugging). The debugger offers access to the widget hierarchy of the application -and to useful debugging tools. - +and to useful debugging tools. + +This function allows applications that already use +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> +(or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>) +for their own key shortcuts to add a different shortcut to open the Inspector. + +If you are not overriding the default key shortcuts for the Inspector, +you should not use this function. + @@ -176798,13 +180590,16 @@ and to useful debugging tools. %TRUE to enable interactive debugging + line="6352">true to enable interactive debugging - + Activates the default widget for the window. + @@ -176815,7 +180610,10 @@ and to useful debugging tools. - + Activates the current focused widget within the window. + @@ -176826,8 +180624,14 @@ and to useful debugging tools. - + Class handler for the [signal@Window::close-request] signal. + + Whether the window should be destroyed @@ -176837,7 +180641,11 @@ and to useful debugging tools. - + Class handler for the `GtkWindow::enable-debugging` + keybinding signal. + @@ -176851,7 +180659,11 @@ and to useful debugging tools. - + Signal gets emitted when the set of accelerators or + mnemonics that are associated with window changes. + @@ -176864,14 +180676,14 @@ and to useful debugging tools. Requests that the window is closed. + line="1358">Requests that the window is closed. This is similar to what happens when a window manager close button is clicked. This function can be used with close buttons in custom titlebars. - + @@ -176879,7 +180691,7 @@ titlebars. a `GtkWindow` + line="1360">a window @@ -176887,8 +180699,8 @@ titlebars. Drop the internal reference GTK holds on toplevel windows. - + line="6880">Drops the internal reference GTK holds on toplevel windows. + @@ -176896,7 +180708,7 @@ titlebars. The window to destroy + line="6882">the window to destroy @@ -176904,7 +180716,7 @@ titlebars. Asks to place @window in the fullscreen state. + line="5593">Asks to place the window in the fullscreen state. Note that you shouldn’t assume the window is definitely fullscreen afterward, because other entities (e.g. the user or window manager) @@ -176914,7 +180726,7 @@ to fullscreen windows. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. - + @@ -176922,7 +180734,7 @@ notifications of the [property@Gtk.Window:fullscreened] property. a `GtkWindow` + line="5595">a window @@ -176931,7 +180743,7 @@ notifications of the [property@Gtk.Window:fullscreened] property. c:identifier="gtk_window_fullscreen_on_monitor"> Asks to place @window in the fullscreen state on the given @monitor. + line="5632">Asks to place the window in the fullscreen state on the given monitor. Note that you shouldn't assume the window is definitely fullscreen afterward, or that the windowing system allows fullscreen windows on @@ -176940,7 +180752,7 @@ any given monitor. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. - + @@ -176948,13 +180760,13 @@ notifications of the [property@Gtk.Window:fullscreened] property. a `GtkWindow` + line="5634">a window which monitor to go fullscreen on + line="5635">which monitor to go fullscreen on @@ -176962,22 +180774,21 @@ notifications of the [property@Gtk.Window:fullscreened] property. - Gets the `GtkApplication` associated with the window. - + line="2795">Gets the application object associated with the window. + a `GtkApplication` + line="2801">the application a `GtkWindow` + line="2797">a window @@ -176985,22 +180796,21 @@ notifications of the [property@Gtk.Window:fullscreened] property. - Gets the child widget of @window. - + line="6862">Gets the child widget of the window. + the child widget of @window + line="6868">the child widget of @window a `GtkWindow` + line="6864">a window @@ -177008,22 +180818,21 @@ notifications of the [property@Gtk.Window:fullscreened] property. - Returns whether the window has been set to have decorations. - + line="3185">Returns whether the window has been set to have decorations. + %TRUE if the window has been set to have decorations + line="3191">true if the window has been set to have decorations a `GtkWindow` + line="3187">a window @@ -177032,7 +180841,7 @@ notifications of the [property@Gtk.Window:fullscreened] property. c:identifier="gtk_window_get_default_size"> Gets the default size of the window. + line="3712">Gets the default size of the window. A value of 0 for the width or height indicates that a default size has not been explicitly set for that dimension, so the @@ -177040,7 +180849,7 @@ size has not been explicitly set for that dimension, so the This function is the recommended way for [saving window state across restarts of applications](https://developer.gnome.org/documentation/tutorials/save-state.html). - + @@ -177048,7 +180857,7 @@ across restarts of applications](https://developer.gnome.org/documentation/tutor a `GtkWindow` + line="3714">a window location to store the default width + line="3715">location to store the default width location to store the default height + line="3716">location to store the default height @@ -177078,22 +180887,21 @@ across restarts of applications](https://developer.gnome.org/documentation/tutor - Returns the default widget for @window. - + line="2401">Returns the default widget for @window. + the default widget + line="2407">the default widget a `GtkWindow` + line="2403">a window @@ -177101,22 +180909,21 @@ across restarts of applications](https://developer.gnome.org/documentation/tutor - Returns whether the window has been set to have a close button. - + line="3244">Returns whether the window has been set to have a close button. + %TRUE if the window has been set to have a close button + line="3250">true if the window has been set to have a close button a `GtkWindow` + line="3246">a window @@ -177124,49 +180931,48 @@ across restarts of applications](https://developer.gnome.org/documentation/tutor - Returns whether the window will be destroyed with its transient parent. - + line="2917">Returns whether the window will be destroyed with its transient parent. + %TRUE if the window will be destroyed with its transient parent. + line="2923">true if the window will be destroyed with its transient parent a `GtkWindow` + line="2919">a window - - + Retrieves the current focused widget within the window. + line="2450">Retrieves the current focused widget within the window. Note that this is the widget that would have the focus if the toplevel window focused; if the toplevel window is not focused then `gtk_widget_has_focus (widget)` will -not be %TRUE for the widget. - +not be false for the widget. + the currently focused widget + line="2461">the currently focused widget a `GtkWindow` + line="2452">a window @@ -177174,23 +180980,22 @@ not be %TRUE for the widget. - Gets whether “focus rectangles” are supposed to be visible. - + line="6155">Gets whether “focus rectangles” are supposed to be visible. + %TRUE if “focus rectangles” are supposed to be visible - in this window. + line="6161">true if “focus rectangles” are supposed to be visible + in this window a `GtkWindow` + line="6157">a window @@ -177198,14 +181003,14 @@ not be %TRUE for the widget. Returns the group for @window. + line="5896">Returns the group for the window. If the window has no group, then the default group is returned. - + the `GtkWindowGroup` for a window + line="5904">the window group for @window or the default group @@ -177216,7 +181021,7 @@ If the window has no group, then the default group is returned. allow-none="1"> a `GtkWindow` + line="5898">a window @@ -177225,24 +181030,22 @@ If the window has no group, then the default group is returned. c:identifier="gtk_window_get_handle_menubar_accel" glib:get-property="handle-menubar-accel" version="4.2"> - Returns whether this window reacts to F10 key presses by -activating a menubar it contains. - + line="7076">Returns whether this window reacts to <kbd>F10</kbd> +presses by activating a menubar it contains. + %TRUE if the window handles F10 + line="7083">true if the window handles <kbd>F10</kbd> a `GtkWindow` + line="7078">a window @@ -177250,22 +181053,22 @@ activating a menubar it contains. - Returns whether the window will be hidden when the close button is clicked. - + line="2959">Returns whether the window will be hidden when the close +button is clicked. + %TRUE if the window will be hidden + line="2966">true if the window will be hidden a `GtkWindow` + line="2961">a window @@ -177273,22 +181076,21 @@ activating a menubar it contains. - Returns the name of the themed icon for the window. - + line="3519">Returns the name of the themed icon for the window. + the icon name + line="3525">the icon name a `GtkWindow` + line="3521">a window @@ -177296,24 +181098,22 @@ activating a menubar it contains. - Gets whether mnemonics are supposed to be visible. - + line="6075">Gets whether mnemonics are supposed to be visible. + %TRUE if mnemonics are supposed to be visible - in this window. + line="6081">true if mnemonics are supposed to be visible + in this window a `GtkWindow` + line="6077">a window @@ -177321,15 +181121,14 @@ activating a menubar it contains. - Returns whether the window is modal. - + line="2534">Returns whether the window is modal. + %TRUE if the window is set to be modal and + line="2540">true if the window is set to be modal and establishes a grab when shown @@ -177337,7 +181136,7 @@ activating a menubar it contains. a `GtkWindow` + line="2536">a window @@ -177345,22 +181144,21 @@ activating a menubar it contains. - Gets the value set by gtk_window_set_resizable(). - + line="5756">Gets whether the user can resize the window. + %TRUE if the user can resize the window + line="5762">true if the user can resize the window a `GtkWindow` + line="5758">a window @@ -177368,22 +181166,21 @@ activating a menubar it contains. - Retrieves the title of the window. - + line="2320">Retrieves the title of the window. + the title of the window + line="2326">the title a `GtkWindow` + line="2322">a window @@ -177391,23 +181188,22 @@ activating a menubar it contains. - Returns the custom titlebar that has been set with -gtk_window_set_titlebar(). - + line="3123">Returns the titlebar that has been set with +[method@Gtk.Window.set_titlebar]. + the custom titlebar + line="3130">the titlebar a `GtkWindow` + line="3125">a window @@ -177415,22 +181211,21 @@ gtk_window_set_titlebar(). - Fetches the transient parent for this window. - + line="2777">Fetches the transient parent for this window. + the transient parent for this window + line="2783">the transient parent a `GtkWindow` + line="2779">a window @@ -177438,19 +181233,19 @@ gtk_window_set_titlebar(). Returns whether @window has an explicit window group. - + line="5926">Returns whether the window has an explicit window group. + %TRUE if @window has an explicit window group. + line="5932">true if @window has an explicit window group a `GtkWindow` + line="5928">a window @@ -177458,37 +181253,37 @@ gtk_window_set_titlebar(). - Returns whether the window is part of the current active toplevel. + line="5872">Returns whether the window is part of the current active toplevel. The active toplevel is the window receiving keystrokes. The return value is %TRUE if the window is active toplevel itself. You might use this function if you wanted to draw a widget differently in an active window from a widget in an inactive window. - + %TRUE if the window part of the current active window. + line="5884">true if the window part of the current active window. a `GtkWindow` + line="5874">a window - - + Retrieves the current fullscreen state of @window. + line="1296">Retrieves the current fullscreen state of the window. Note that since fullscreening is ultimately handled by the window manager and happens asynchronously to an application request, you @@ -177498,27 +181293,28 @@ immediately (or at all), as an effect of calling If the window isn't yet mapped, the value returned will whether the initial requested state is fullscreen. - + whether the window has a fullscreen state. + line="1311">whether the window is fullscreen a `GtkWindow` + line="1298">a window - - + Retrieves the current maximized state of @window. + line="1269">Retrieves the current maximized state of the window. Note that since maximization is ultimately handled by the window manager and happens asynchronously to an application request, you @@ -177528,44 +181324,45 @@ immediately (or at all), as an effect of calling If the window isn't yet mapped, the value returned will whether the initial requested state is maximized. - + whether the window has a maximized state. + line="1284">whether the window is maximized a `GtkWindow` + line="1271">a window - Retrieves the current suspended state of @window. + line="1323">Retrieves the current suspended state of the window. -A window being suspended means it's currently not visible to the user, for -example by being on a inactive workspace, minimized, obstructed. - +A window being suspended means it's currently not visible +to the user, for example by being on a inactive workspace, +minimized, obstructed. + whether the window is suspended. + line="1333">whether the window is suspended a `GtkWindow` + line="1325">a window @@ -177573,7 +181370,7 @@ example by being on a inactive workspace, minimized, obstructed. Asks to maximize @window, so that it fills the screen. + line="5501">Asks to maximize the window, so that it fills the screen. Note that you shouldn’t assume the window is definitely maximized afterward, because other entities (e.g. the user or window manager) @@ -177588,7 +181385,7 @@ You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications on the [property@Gtk.Window:maximized] property. - + @@ -177596,7 +181393,7 @@ property. a `GtkWindow` + line="5503">a window @@ -177604,7 +181401,7 @@ property. Asks to minimize the specified @window. + line="5441">Asks to minimize the window. Note that you shouldn’t assume the window is definitely minimized afterward, because the windowing system might not support this @@ -177618,7 +181415,7 @@ onscreen. You can track result of this operation via the [property@Gdk.Toplevel:state] property. - + @@ -177626,7 +181423,7 @@ You can track result of this operation via the a `GtkWindow` + line="5443">a window @@ -177634,7 +181431,7 @@ You can track result of this operation via the Presents a window to the user. + line="5395">Presents a window to the user. This may mean raising the window in the stacking order, unminimizing it, moving it to the current desktop and/or @@ -177642,7 +181439,7 @@ giving it the keyboard focus (possibly dependent on the user’s platform, window manager and preferences). If @window is hidden, this function also makes it visible. - + @@ -177650,23 +181447,26 @@ If @window is hidden, this function also makes it visible. a `GtkWindow` + line="5397">a window + c:identifier="gtk_window_present_with_time" + deprecated="1" + deprecated-version="4.14"> Presents a window to the user in response to an user interaction. + line="5416">Presents a window to the user in response to an user interaction. See [method@Gtk.Window.present] for more details. The timestamp should be gathered when the window was requested to be shown (when clicking a link for example), rather than once the window is ready to be shown. - + Use [method@Gtk.Window.present] + @@ -177674,13 +181474,13 @@ the window is ready to be shown. a `GtkWindow` + line="5418">a window the timestamp of the user interaction (typically a + line="5419">the timestamp of the user interaction (typically a button or key press event) which triggered this call @@ -177689,14 +181489,13 @@ the window is ready to be shown. - Sets or unsets the `GtkApplication` associated with the window. + line="2834">Sets or unsets the application object associated with the window. The application will be kept alive for at least as long as it has -any windows associated with it (see g_application_hold() for a way -to keep it alive without windows). +any windows associated with it (see [method@Gio.Application.hold] +for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove @@ -177705,7 +181504,7 @@ it by setting the @application to %NULL. This is equivalent to calling [method@Gtk.Application.remove_window] and/or [method@Gtk.Application.add_window] on the old/new applications as relevant. - + @@ -177713,7 +181512,7 @@ as relevant. a `GtkWindow` + line="2836">a window allow-none="1"> a `GtkApplication`, or %NULL to unset + line="2837">a `GtkApplication` @@ -177730,11 +181529,10 @@ as relevant. - Sets the child widget of @window. - + line="6832">Sets the child widget of the window. + @@ -177742,7 +181540,7 @@ as relevant. a `GtkWindow` + line="6834">a window allow-none="1"> the child widget + line="6835">the child widget @@ -177759,15 +181557,14 @@ as relevant. - Sets whether the window should be decorated. + line="3142">Sets whether the window should be decorated. By default, windows are decorated with a title bar, resize controls, etc. Some window managers allow GTK to disable these decorations, creating a borderless window. If you set the decorated -property to %FALSE using this function, GTK will do its best to +property to false using this function, GTK will do its best to convince the window manager not to decorate the window. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling @@ -177775,7 +181572,7 @@ window that is already visible, so you should call it before calling On Windows, this function always works, since there’s no window manager policy involved. - + @@ -177783,13 +181580,13 @@ policy involved. a `GtkWindow` + line="3144">a window %TRUE to decorate the window + line="3145">true to decorate the window @@ -177798,9 +181595,10 @@ policy involved. c:identifier="gtk_window_set_default_size"> Sets the default size of a window. + line="3662">Sets the default size of a window. -The default size of a window is the size that will be used if no other constraints apply. +The default size of a window is the size that will be used +if no other constraints apply. The default size will be updated whenever the window is resized to reflect the new size, unless the window is forced to a size, @@ -177827,7 +181625,7 @@ note that the appropriate size to save is the one returned by [method@Gtk.Window.get_default_size]. Using the window allocation directly will not work in all circumstances and can lead to growing or shrinking windows. - + @@ -177835,19 +181633,19 @@ or shrinking windows. a `GtkWindow` + line="3664">a window width in pixels, or -1 to unset the default width + line="3665">width in pixels, or -1 to unset the default width height in pixels, or -1 to unset the default height + line="3666">height in pixels, or -1 to unset the default height @@ -177855,14 +181653,14 @@ or shrinking windows. - Sets the default widget. + line="2338">Sets the default widget. -The default widget is the widget that is activated when the user -presses Enter in a dialog (for example). - +The default widget is the widget that is activated +when the user presses <kbd>Enter</kbd> in a dialog +(for example). + @@ -177870,7 +181668,7 @@ presses Enter in a dialog (for example). a `GtkWindow` + line="2340">a window allow-none="1"> widget to be the default - to unset the default widget for the toplevel + line="2341">widget to be the default @@ -177888,14 +181685,13 @@ presses Enter in a dialog (for example). - Sets whether the window should be deletable. + line="3203">Sets whether the window should be deletable. By default, windows have a close button in the window frame. Some window managers allow GTK to disable this button. If you -set the deletable property to %FALSE using this function, GTK +set the deletable property to false using this function, GTK will do its best to convince the window manager not to show a close button. Depending on the system, this function may not have any effect when called on a window that is already visible, @@ -177903,7 +181699,7 @@ so you should call it before calling [method@Gtk.Widget.show]. On Windows, this function always works, since there’s no window manager policy involved. - + @@ -177911,13 +181707,13 @@ manager policy involved. a `GtkWindow` + line="3205">a window %TRUE to decorate the window as deletable + line="3206">true to decorate the window as deletable @@ -177925,16 +181721,13 @@ manager policy involved. - If @setting is %TRUE, then destroying the transient parent of @window -will also destroy @window itself. + line="2891">Sets whether to destroy the window when the transient parent is destroyed. This is useful for dialogs that shouldn’t persist beyond the lifetime of the main window they are associated with, for example. - + @@ -177942,13 +181735,13 @@ of the main window they are associated with, for example. a `GtkWindow` + line="2893">a window whether to destroy @window with its transient parent + line="2894">whether to destroy the window with its transient parent @@ -177956,14 +181749,13 @@ of the main window they are associated with, for example. - Sets the `GdkDisplay` where the @window is displayed. + line="5774">Sets the display where the window is displayed. If the window is already mapped, it will be unmapped, and then remapped on the new display. - + @@ -177971,29 +181763,30 @@ and then remapped on the new display. a `GtkWindow` + line="5776">a window a `GdkDisplay` + line="5777">a display - - + Sets the focus widget. + line="5223">Sets the focus widget. If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, unsets the focus widget for this window. To set the focus to a particular widget in the toplevel, it is usually more convenient to use [method@Gtk.Widget.grab_focus] instead of this function. - + @@ -178001,7 +181794,7 @@ to use [method@Gtk.Widget.grab_focus] instead of this function. a `GtkWindow` + line="5225">a window allow-none="1"> widget to be the new focus widget, or %NULL to unset - any focus widget for the toplevel window. + line="5226">the new focus widget @@ -178019,14 +181811,13 @@ to use [method@Gtk.Widget.grab_focus] instead of this function. - Sets whether “focus rectangles” are supposed to be visible. + line="6187">Sets whether “focus rectangles” are supposed to be visible. This property is maintained by GTK based on user input, and should not be set by applications. - + @@ -178034,13 +181825,13 @@ and should not be set by applications. a `GtkWindow` + line="6189">a window the new value + line="6190">the new value @@ -178049,13 +181840,11 @@ and should not be set by applications. c:identifier="gtk_window_set_handle_menubar_accel" glib:set-property="handle-menubar-accel" version="4.2"> - Sets whether this window should react to F10 key presses -by activating a menubar it contains. - + line="7047">Sets whether this window should react to <kbd>F10</kbd> +presses by activating a menubar it contains. + @@ -178063,13 +181852,13 @@ by activating a menubar it contains. a `GtkWindow` + line="7049">a window %TRUE to make @window handle F10 + line="7050">true to make @window handle <kbd>F10</kbd> @@ -178077,12 +181866,11 @@ by activating a menubar it contains. - If @setting is %TRUE, then clicking the close button on the window -will not destroy it, but only hide it. - + line="2935">Sets whether clicking the close button will hide the window instead +of destroying it. + @@ -178090,13 +181878,13 @@ will not destroy it, but only hide it. a `GtkWindow` + line="2937">a window whether to hide the window when it is closed + line="2938">whether to hide the window when it is closed @@ -178104,17 +181892,16 @@ will not destroy it, but only hide it. - Sets the icon for the window from a named themed icon. + line="3483">Sets the icon for the window from a named themed icon. See the docs for [class@Gtk.IconTheme] for more details. On some platforms, the window icon is not used at all. Note that this has nothing to do with the WM_ICON_NAME property which is mentioned in the ICCCM. - + @@ -178122,7 +181909,7 @@ property which is mentioned in the ICCCM. a `GtkWindow` + line="3485">a window allow-none="1"> the name of the themed icon + line="3486">the name of the themed icon @@ -178139,15 +181926,13 @@ property which is mentioned in the ICCCM. - Sets whether mnemonics are supposed to be visible. + line="6094">Sets whether mnemonics are supposed to be visible. This property is maintained by GTK based on user input, and should not be set by applications. - + @@ -178155,13 +181940,13 @@ and should not be set by applications. a `GtkWindow` + line="6096">a window the new value + line="6097">the new value @@ -178169,17 +181954,16 @@ and should not be set by applications. - Sets a window modal or non-modal. + line="2485">Sets a window modal or non-modal. Modal windows prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use [method@Gtk.Window.set_transient_for] to make the dialog transient for the parent; most window managers will then disallow lowering the dialog below the parent. - + @@ -178187,13 +181971,13 @@ dialog below the parent. a `GtkWindow` + line="2487">a window whether the window is modal + line="2488">whether the window is modal @@ -178201,13 +181985,12 @@ dialog below the parent. - Sets whether the user can resize a window. + line="5722">Sets whether the user can resize a window. Windows are user resizable by default. - + @@ -178215,13 +181998,13 @@ Windows are user resizable by default. a `GtkWindow` + line="5724">a window %TRUE if the user can resize this window + line="5725">true if the user can resize this window @@ -178229,10 +182012,9 @@ Windows are user resizable by default. - Sets the startup notification ID. + line="5330">Sets the startup notification ID. Startup notification identifiers are used by desktop environment to track application startup, to provide user feedback and other @@ -178246,7 +182028,7 @@ other processes. You should use this function before calling a window map event. This function is only useful on X11, not with other GTK targets. - + @@ -178254,13 +182036,13 @@ This function is only useful on X11, not with other GTK targets. a `GtkWindow` + line="5332">a window a string with startup-notification identifier + line="5333">a string with startup-notification identifier @@ -178268,10 +182050,9 @@ This function is only useful on X11, not with other GTK targets. - Sets the title of the `GtkWindow`. + line="2281">Sets the title of the window. The title of a window will be displayed in its title bar; on the X Window System, the title bar is rendered by the window manager @@ -178280,8 +182061,8 @@ user’s exact configuration. The title should help a user distinguish this window from other windows they may have open. A good title might include the application name and current document filename, for example. -Passing %NULL does the same as setting the title to an empty string. - +Passing `NULL` does the same as setting the title to an empty string. + @@ -178289,7 +182070,7 @@ Passing %NULL does the same as setting the title to an empty string. a `GtkWindow` + line="2283">a window allow-none="1"> title of the window + line="2284">title of the window @@ -178306,10 +182087,9 @@ Passing %NULL does the same as setting the title to an empty string. - Sets a custom titlebar for @window. + line="3054">Sets a custom titlebar for the window. A typical widget used here is [class@Gtk.HeaderBar], as it provides various features expected of a titlebar while allowing @@ -178320,7 +182100,7 @@ the window manager not to put its own titlebar on the window. Depending on the system, this function may not work for a window that is already visible, so you set the titlebar before calling [method@Gtk.Widget.show]. - + @@ -178328,7 +182108,7 @@ that is already visible, so you set the titlebar before calling a `GtkWindow` + line="3056">a window the widget to use as titlebar + line="3057">the widget to use as titlebar @@ -178345,21 +182125,22 @@ that is already visible, so you set the titlebar before calling - Dialog windows should be set transient for the main application + line="2705">Sets a transient parent for the window. + +Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window. [ctor@Gtk.Dialog.new_with_buttons] and other -convenience functions in GTK will sometimes call -gtk_window_set_transient_for() on your behalf. +convenience functions in GTK will sometimes call this function on +your behalf. -Passing %NULL for @parent unsets the current transient window. +Passing `NULL` for @parent unsets the current transient window. On Windows, this function puts the child window on top of the parent, much as the window manager would have done on X. - + @@ -178367,7 +182148,7 @@ much as the window manager would have done on X. a `GtkWindow` + line="2707">a window allow-none="1"> parent window + line="2708">parent window @@ -178384,7 +182165,7 @@ much as the window manager would have done on X. Asks to remove the fullscreen state for @window, and return to + line="5680">Asks to remove the fullscreen state for the window, and return to its previous state. Note that you shouldn’t assume the window is definitely not @@ -178397,7 +182178,7 @@ write code that crashes if not. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. - + @@ -178405,7 +182186,7 @@ notifications of the [property@Gtk.Window:fullscreened] property. a `GtkWindow` + line="5682">a window @@ -178413,7 +182194,7 @@ notifications of the [property@Gtk.Window:fullscreened] property. Asks to unmaximize @window. + line="5543">Asks to unmaximize the window. Note that you shouldn’t assume the window is definitely unmaximized afterward, because other entities (e.g. the user or window manager) @@ -178423,7 +182204,7 @@ unmaximize. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications on the [property@Gtk.Window:maximized] property. - + @@ -178431,7 +182212,7 @@ notifications on the [property@Gtk.Window:maximized] property. a `GtkWindow` + line="5545">a window @@ -178439,7 +182220,7 @@ notifications on the [property@Gtk.Window:maximized] property. Asks to unminimize the specified @window. + line="5473">Asks to unminimize the window. Note that you shouldn’t assume the window is definitely unminimized afterward, because the windowing system might not support this @@ -178449,7 +182230,7 @@ which case minimization isn’t possible, etc. You can track result of this operation via the [property@Gdk.Toplevel:state] property. - + @@ -178457,7 +182238,7 @@ You can track result of this operation via the a `GtkWindow` + line="5475">a window @@ -178467,13 +182248,9 @@ You can track result of this operation via the transfer-ownership="none" setter="set_application" getter="get_application"> - - The `GtkApplication` associated with the window. + line="1011">The `GtkApplication` associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() @@ -178481,7 +182258,7 @@ for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly -remove it by setting the :application property to %NULL. +remove it by setting the this property to `NULL`. transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="1049">The child widget. setter="set_decorated" getter="get_decorated" default-value="TRUE"> - - Whether the window should have a frame (also known as *decorations*). + line="935">Whether the window should have a frame (also known as *decorations*). default-value="0"> The default height of the window. + line="846">The default height of the window. transfer-ownership="none" setter="set_default_widget" getter="get_default_widget"> - - The default widget. + line="1029">The default widget. default-value="0"> The default width of the window. + line="835">The default width of the window. setter="set_deletable" getter="get_deletable" default-value="TRUE"> - - Whether the window frame should have a close button. + line="945">Whether the window frame should have a close button. setter="set_destroy_with_parent" getter="get_destroy_with_parent" default-value="FALSE"> - - If this window should be destroyed when the parent is destroyed. + line="857">If this window should be destroyed when the parent is destroyed. - The display that will display this window. + line="915">The display that will display this window. setter="set_focus_visible" getter="get_focus_visible" default-value="TRUE"> - - Whether 'focus rectangles' are currently visible in this window. + line="890">Whether 'focus rectangles' are currently visible in this window. This property is maintained by GTK based on user input and should not be set by applications. - - - + The focus widget. + line="1039">The focus widget. - Whether the window is fullscreen. + line="981">Whether the window is fullscreen. Setting this property is the equivalent of calling [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen]; @@ -178634,13 +182389,9 @@ operation was successful. setter="set_handle_menubar_accel" getter="get_handle_menubar_accel" default-value="TRUE"> - - Whether the window frame should handle F10 for activating + line="1071">Whether the window frame should handle <kbd>F10</kbd> for activating menubars. @@ -178650,13 +182401,9 @@ menubars. setter="set_hide_on_close" getter="get_hide_on_close" default-value="FALSE"> - - If this window should be hidden when the users clicks the close button. + line="867">If this window should be hidden when the users clicks the close button. setter="set_icon_name" getter="get_icon_name" default-value="NULL"> - - Specifies the name of the themed icon to use as the window icon. + line="903">Specifies the name of the themed icon to use as the window icon. See [class@Gtk.IconTheme] for more details. @@ -178680,22 +182423,20 @@ See [class@Gtk.IconTheme] for more details. transfer-ownership="none" getter="is_active" default-value="FALSE"> - Whether the toplevel is the currently active window. + line="925">Whether the toplevel is the currently active window. - Whether the window is maximized. + line="965">Whether the window is maximized. Setting this property is the equivalent of calling [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize]; @@ -178710,13 +182451,9 @@ operation was successful. setter="set_mnemonics_visible" getter="get_mnemonics_visible" default-value="FALSE"> - - Whether mnemonics are currently visible in this window. + line="877">Whether mnemonics are currently visible in this window. This property is maintained by GTK based on user input, and should not be set by applications. @@ -178728,11 +182465,9 @@ and should not be set by applications. setter="set_modal" getter="get_modal" default-value="FALSE"> - - If %TRUE, the window is modal. + line="825">If true, the window is modal. setter="set_resizable" getter="get_resizable" default-value="TRUE"> - - If %TRUE, users can resize the window. + line="815">If true, users can resize the window. transfer-ownership="none" setter="set_startup_id" default-value="NULL"> - A write-only property for setting window's startup notification identifier. + line="805">A write-only property for setting window's startup notification identifier. - Whether the window is suspended. + line="997">Whether the window is suspended. See [method@Gtk.Window.is_suspended] for details about what suspended means. @@ -178782,11 +182510,9 @@ See [method@Gtk.Window.is_suspended] for details about what suspended means. - - The title of the window. + line="795">The title of the window. - - The titlebar widget. + line="1059">The titlebar widget. - - The transient parent of the window. + line="955">The transient parent of the window. @@ -178825,10 +182543,11 @@ See [method@Gtk.Window.is_suspended] for details about what suspended means. Emitted when the user activates the default widget -of @window. + line="1107">Emitted when the user activates the default widget. -This is a [keybinding signal](class.SignalAction.html). +This is a [keybinding signal](class.SignalAction.html). + +The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. @@ -178836,10 +182555,12 @@ This is a [keybinding signal](class.SignalAction.html). Emitted when the user activates the currently focused + line="1086">Emitted when the user activates the currently focused widget of @window. -This is a [keybinding signal](class.SignalAction.html). +This is a [keybinding signal](class.SignalAction.html). + +The default binding for this signal is <kbd>␣</kbd>. @@ -178847,38 +182568,39 @@ This is a [keybinding signal](class.SignalAction.html). Emitted when the user clicks on the close button of the window. + line="1179">Emitted when the user clicks on the close button of the window. %TRUE to stop other handlers from being invoked for the signal + line="1185">true to stop other handlers from being invoked for the signal Emitted when the user enables or disables interactive debugging. + line="1147">Emitted when the user enables or disables interactive debugging. -When @toggle is %TRUE, interactive debugging is toggled on or off, -when it is %FALSE, the debugger will be pointed at the widget +When @toggle is true, interactive debugging is toggled on or off, +when it is false, the debugger will be pointed at the widget under the pointer. This is a [keybinding signal](class.SignalAction.html). -The default bindings for this signal are Ctrl-Shift-I -and Ctrl-Shift-D. +The default bindings for this signal are +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> and +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>. %TRUE if the key binding was handled + line="1164">true if the key binding was handled toggle the debugger + line="1150">toggle the debugger @@ -178889,10 +182611,10 @@ and Ctrl-Shift-D. deprecated-version="4.10"> emitted when the set of accelerators or mnemonics that -are associated with @window changes. + line="1127">Emitted when the set of accelerators or mnemonics that +are associated with the window changes. Use [class@Gtk.Shortcut] and [class@Gtk.EventController] -to implement keyboard shortcuts + to implement keyboard shortcuts @@ -178901,7 +182623,7 @@ to implement keyboard shortcuts - + + Activates the current focused widget within the window. - + @@ -178922,8 +182647,11 @@ to implement keyboard shortcuts + Activates the default widget for the window. - + @@ -178935,8 +182663,12 @@ to implement keyboard shortcuts + Signal gets emitted when the set of accelerators or + mnemonics that are associated with window changes. - + @@ -178948,8 +182680,12 @@ to implement keyboard shortcuts + Class handler for the `GtkWindow::enable-debugging` + keybinding signal. - + @@ -178965,8 +182701,11 @@ to implement keyboard shortcuts - + + Whether the window should be destroyed @@ -178991,12 +182730,15 @@ to implement keyboard shortcuts glib:type-struct="WindowControlsClass"> `GtkWindowControls` shows window frame controls. + line="39">Shows window frame controls. Typical window frame controls are minimize, maximize and close buttons, and the window icon. -![An example GtkWindowControls](windowcontrols.png) +<picture> + <source srcset="windowcontrols-dark.png" media="(prefers-color-scheme: dark)"> + <img alt="An example GtkWindowControls" src="windowcontrols.png"> +</picture> `GtkWindowControls` only displays start or end side of the controls (see [property@Gtk.WindowControls:side]), so it's intended to be always used @@ -179035,12 +182777,12 @@ subnodes corresponding to each title button. Which of the title buttons exist and where they are placed exactly depends on the desktop environment and [property@Gtk.WindowControls:decoration-layout] value. -When [property@Gtk.WindowControls:empty] is %TRUE, it gets the .empty +When [property@Gtk.WindowControls:empty] is true, it gets the .empty style class. # Accessibility -`GtkWindowControls` uses the %GTK_ACCESSIBLE_ROLE_GROUP role. +`GtkWindowControls` uses the [enum@Gtk.AccessibleRole.group] role. @@ -179048,19 +182790,19 @@ style class. Creates a new `GtkWindowControls`. + line="646">Creates a new `GtkWindowControls`. a new `GtkWindowControls`. + line="652">a new `GtkWindowControls` the side + line="648">the side @@ -179068,23 +182810,21 @@ style class. - Gets the decoration layout of this `GtkWindowControls`. + line="721">Gets the decoration layout of this window controls widget the decoration layout or %NULL if it is unset + line="727">the decoration layout a `GtkWindowControls` + line="723">a window controls widget @@ -179092,22 +182832,21 @@ style class. - Gets whether the widget has any window buttons. - + line="822">Gets whether the widget has any window buttons. + %TRUE if the widget has window buttons, otherwise %FALSE + line="828">true if the widget has window buttons a `GtkWindowControls` + line="824">a window controls widget @@ -179115,22 +182854,44 @@ style class. - Gets the side to which this `GtkWindowControls` instance belongs. + line="662">Gets the side to which this window controls widget belongs. the side + line="668">the side a `GtkWindowControls` + line="664">a window controls widget + + + + + + Returns whether platform native window controls are shown. + + + true if native window controls are shown + + + + + a window controls widget @@ -179138,11 +182899,9 @@ style class. - Sets the decoration layout for the title buttons. + line="737">Sets the decoration layout for the title buttons. This overrides the [property@Gtk.Settings:gtk-decoration-layout] setting. @@ -179155,8 +182914,8 @@ maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies a icon on the left, and minimize, maximize and close buttons on the right. -If [property@Gtk.WindowControls:side] value is @GTK_PACK_START, @self -will display the part before the colon, otherwise after that. +If [property@Gtk.WindowControls:side] value is [enum@Gtk.PackType.start], +@self will display the part before the colon, otherwise after that. @@ -179165,7 +182924,7 @@ will display the part before the colon, otherwise after that. a `GtkWindowControls` + line="739">a window controls widget allow-none="1"> a decoration layout, or %NULL to unset the layout + line="740">a decoration layout, or `NULL` to unset the layout @@ -179182,10 +182941,10 @@ will display the part before the colon, otherwise after that. - Determines which part of decoration layout the `GtkWindowControls` uses. + line="678">Determines which part of decoration layout +the window controls widget uses. See [property@Gtk.WindowControls:decoration-layout]. @@ -179196,30 +182955,57 @@ See [property@Gtk.WindowControls:decoration-layout]. a `GtkWindowControls` + line="680">a window controls widget a side + line="681">a side + + Sets whether platform native window controls are used. + +This option shows the "stoplight" buttons on macOS. +For Linux, this option has no effect. + +See also [Using GTK on Apple macOS](osx.html?native-window-controls). + + + + + + + a window_controls widget + + + + true to show native window controls + + + + - - The decoration layout for window buttons. + line="582">The decoration layout for window buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. @@ -179229,11 +183015,9 @@ If this property is not set, the transfer-ownership="none" getter="get_empty" default-value="TRUE"> - Whether the widget has any window buttons. + line="615">Whether the widget has any window buttons. - - Whether the widget shows start or end side of the decoration layout. + line="569">Whether the widget shows start or end side of the decoration layout. See [property@Gtk.WindowControls:decoration_layout]. + + Whether to show platform native close/minimize/maximize buttons. + +For macOS, the [property@Gtk.HeaderBar:decoration-layout] property +controls the use of native window controls. + +On other platforms, this option has no effect. + +See also [Using GTK on Apple macOS](osx.html?native-window-controls). + + glib:type-struct="WindowGroupClass"> `GtkWindowGroup` makes group of windows behave like separate applications. + line="33">Creates groups of windows that behave like separate applications. It achieves this by limiting the effect of GTK grabs and modality to windows in the same group. @@ -179435,10 +183234,11 @@ within the same `GtkWindowGroup`. glib:type-struct="WindowHandleClass"> `GtkWindowHandle` is a titlebar area widget. + line="40">Implements titlebar functionality for a window. -When added into a window, it can be dragged to move the window, and handles -right click, double click and middle click as expected of a titlebar. +When added into a window, it can be dragged to move the window, +and it implements the right click, double click and middle click +behaviors that are expected of a titlebar. # CSS nodes @@ -179446,9 +183246,10 @@ right click, double click and middle click as expected of a titlebar. # Accessibility -Until GTK 4.10, `GtkWindowHandle` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkWindowHandle` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkWindowHandle` uses the [enum@Gtk.AccessibleRole.generic] +role. @@ -179456,34 +183257,33 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` Creates a new `GtkWindowHandle`. + line="600">Creates a new `GtkWindowHandle`. a new `GtkWindowHandle`. + line="605">a new `GtkWindowHandle`. - Gets the child widget of @self. + line="613">Gets the child widget of @self. the child widget of @self + line="619">the child widget of @self a `GtkWindowHandle` + line="615">a `GtkWindowHandle` @@ -179491,10 +183291,9 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` - Sets the child widget of @self. + line="629">Sets the child widget of @self. @@ -179503,7 +183302,7 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` a `GtkWindowHandle` + line="631">a `GtkWindowHandle` the child widget + line="632">the child widget @@ -179522,13 +183321,9 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` transfer-ownership="none" setter="set_child" getter="get_child"> - - The child widget. + line="541">The child widget. @@ -179546,7 +183341,7 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` c:type="GtkWrapMode"> Describes a type of line wrapping. + line="565">Describes a type of line wrapping. do not wrap lines; just make the text area wider + line="567">do not wrap lines; just make the text area wider wrap text, breaking lines anywhere the cursor can + line="568">wrap text, breaking lines anywhere the cursor can appear (between characters, usually - if you want to be technical, between graphemes, see pango_get_log_attrs()) @@ -179574,7 +183369,7 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` glib:name="GTK_WRAP_WORD"> wrap text, breaking lines in between words + line="571">wrap text, breaking lines in between words wrap text, breaking lines in between words, or if + line="572">wrap text, breaking lines in between words, or if that is not enough, also between graphemes @@ -179591,16 +183386,16 @@ Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` c:identifier="gtk_accelerator_get_default_mod_mask"> Gets the modifier mask. + line="986">Gets the modifier mask. The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except -for %GDK_LOCK_MASK. +for `GDK_LOCK_MASK`. the modifier mask for accelerators + line="995">the modifier mask for accelerators @@ -179608,26 +183403,26 @@ for %GDK_LOCK_MASK. c:identifier="gtk_accelerator_get_label"> Converts an accelerator keyval and modifier mask into a string + line="800">Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user. a newly-allocated string representing the accelerator + line="808">a newly-allocated string representing the accelerator accelerator keyval + line="802">accelerator keyval accelerator modifier mask + line="803">accelerator modifier mask @@ -179636,7 +183431,7 @@ which can be used to represent the accelerator to the user. c:identifier="gtk_accelerator_get_label_with_keycode"> Converts an accelerator keyval and modifier mask + line="635">Converts an accelerator keyval and modifier mask into a string that can be displayed to the user. The string may be translated. @@ -179649,7 +183444,7 @@ instead. a newly-allocated string representing the accelerator + line="652">a newly-allocated string representing the accelerator @@ -179659,25 +183454,25 @@ instead. allow-none="1"> a `GdkDisplay` or %NULL to use the default display + line="637">a `GdkDisplay` accelerator keyval + line="638">accelerator keyval accelerator keycode + line="639">accelerator keycode accelerator modifier mask + line="640">accelerator modifier mask @@ -179685,10 +183480,10 @@ instead. Converts an accelerator keyval and modifier mask into a string -parseable by gtk_accelerator_parse(). + line="556">Converts an accelerator keyval and modifier mask into a string +that can be parsed by [func@Gtk.accelerator_parse]. -For example, if you pass in %GDK_KEY_q and %GDK_CONTROL_MASK, +For example, if you pass in `GDK_KEY_q` and `GDK_CONTROL_MASK`, this function returns `<Control>q`. If you need to display accelerators in the user interface, @@ -179697,20 +183492,20 @@ see [func@Gtk.accelerator_get_label]. a newly-allocated accelerator name + line="570">a newly-allocated accelerator name accelerator keyval + line="558">accelerator keyval accelerator modifier mask + line="559">accelerator modifier mask @@ -179719,8 +183514,8 @@ see [func@Gtk.accelerator_get_label]. c:identifier="gtk_accelerator_name_with_keycode"> Converts an accelerator keyval and modifier mask -into a string parseable by gtk_accelerator_parse_with_keycode(). + line="519">Converts an accelerator keyval and modifier mask +into a string that can be parsed by [func@Gtk.accelerator_parse_with_keycode]. This is similar to [func@Gtk.accelerator_name] but handling keycodes. This is only useful for system-level components, applications @@ -179729,7 +183524,7 @@ should use [func@Gtk.accelerator_name] instead. a newly allocated accelerator name. + line="533">a newly allocated accelerator name. @@ -179739,25 +183534,25 @@ should use [func@Gtk.accelerator_name] instead. allow-none="1"> a `GdkDisplay` or %NULL to use the default display + line="521">a `GdkDisplay` accelerator keyval + line="522">accelerator keyval accelerator keycode + line="523">accelerator keycode accelerator modifier mask + line="524">accelerator modifier mask @@ -179790,6 +183585,9 @@ If the parse operation fails, @accelerator_key and @accelerator_mods will be set to 0 (zero). + whether parsing succeeded @@ -179846,7 +183644,7 @@ If the parse fails, @accelerator_key, @accelerator_mods and %TRUE if parsing succeeded + line="253">true if parsing succeeded @@ -179910,14 +183708,14 @@ If the parse fails, @accelerator_key, @accelerator_mods and line="36">Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. -For example, the %GDK_KEY_a keyval plus %GDK_CONTROL_MASK mark is valid, +For example, the `GDK_KEY_a` keyval plus `GDK_CONTROL_MASK` mask is valid, and matches the “Ctrl+a” accelerator. But, you can't, for instance, use -the %GDK_KEY_Control_L keyval as an accelerator. +the `GDK_KEY_Control_L` keyval as an accelerator. %TRUE if the accelerator is valid + line="48">true if the accelerator is valid @@ -179938,15 +183736,27 @@ the %GDK_KEY_Control_L keyval as an accelerator. - + Initializes @value with the appropriate type for the @property. + +This function is mostly meant for language bindings, in conjunction +with gtk_accessible_update_property_value(). + + a `GtkAccessibleProperty` + an uninitialized `GValue` @@ -179954,15 +183764,27 @@ the %GDK_KEY_Control_L keyval as an accelerator. - + Initializes @value with the appropriate type for the @relation. + +This function is mostly meant for language bindings, in conjunction +with gtk_accessible_update_relation_value(). + + a `GtkAccessibleRelation` + an uninitialized `GValue` @@ -179970,15 +183792,27 @@ the %GDK_KEY_Control_L keyval as an accelerator. - + Initializes @value with the appropriate type for the @state. + +This function is mostly meant for language bindings, in conjunction +with gtk_accessible_update_relation_state(). + + a `GtkAccessibleState` + an uninitialized `GValue` @@ -179988,15 +183822,15 @@ the %GDK_KEY_Control_L keyval as an accelerator. moved-to="BitsetIter.init_at"> Initializes @iter to point to @target. + line="841">Initializes @iter to point to @target. If @target is not found, finds the next value after it. If no value >= @target exists in @set, this function returns %FALSE. - + %TRUE if a value was found. + line="853">%TRUE if a value was found. @@ -180006,19 +183840,19 @@ If no value >= @target exists in @set, this function returns %FALSE. transfer-ownership="none"> a pointer to an uninitialized `GtkBitsetIter` + line="843">a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` + line="844">a `GtkBitset` target value to start iterating at + line="845">target value to start iterating at allow-none="1"> Set to the found value in @set + line="846">Set to the found value in @set @@ -180039,15 +183873,15 @@ If no value >= @target exists in @set, this function returns %FALSE. moved-to="BitsetIter.init_first"> Initializes an iterator for @set and points it to the first + line="779">Initializes an iterator for @set and points it to the first value in @set. If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. - + %TRUE if @set isn't empty. + line="790">%TRUE if @set isn't empty. @@ -180057,13 +183891,13 @@ If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. transfer-ownership="none"> a pointer to an uninitialized `GtkBitsetIter` + line="781">a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` + line="782">a `GtkBitset` allow-none="1"> Set to the first value in @set + line="783">Set to the first value in @set @@ -180084,15 +183918,15 @@ If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. moved-to="BitsetIter.init_last"> Initializes an iterator for @set and points it to the last + line="810">Initializes an iterator for @set and points it to the last value in @set. If @set is empty, %FALSE is returned. - + %TRUE if @set isn't empty. + line="821">%TRUE if @set isn't empty. @@ -180102,13 +183936,13 @@ If @set is empty, %FALSE is returned. transfer-ownership="none"> a pointer to an uninitialized `GtkBitsetIter` + line="812">a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` + line="813">a `GtkBitset` allow-none="1"> Set to the last value in @set + line="814">Set to the last value in @set @@ -180130,22 +183964,33 @@ If @set is empty, %FALSE is returned. introspectable="0"> Adds the @callback_symbol to the scope of @builder under its -own name. + line="434">Adds the @callback to the scope of @builder under its own name. This is a convenience wrapper of [method@Gtk.BuilderCScope.add_callback_symbol]. + a `GtkBuilderCScope` + The callback pointer + Registers an error quark for [class@Gtk.Builder] errors. + the error quark @@ -180209,39 +184054,78 @@ into an application using a newer version of GTK. + Registers an error quark for VFL error parsing. + the error quark + Registers an error quark for CSS parsing errors. + the error quark + Registers an error quark for CSS parsing warnings. + the warning quark + Registers an error quark for an operation that requires a dialog if +necessary. + the error quark + + Prevents GTK from using portals. + +This is equivalent to setting `GDK_DEBUG=no-portals` in the environment. + +This should only be used in portal implementations, apps must not call it. + + + + + Prevents [id@gtk_init] and [id@gtk_init_check] from automatically calling -`setlocale (LC_ALL, "")`. + line="247">Prevents [func@Gtk.init] and [func@Gtk.init_check] from calling `setlocale()`. You would want to use this function if you wanted to set the locale for -your program to something other than the user’s locale, or if -you wanted to set different values for different locale categories. +your program to something other than the user’s locale, or if you wanted +to set different values for different locale categories. Most programs should not need to call this function. @@ -180253,17 +184137,17 @@ Most programs should not need to call this function. c:identifier="gtk_distribute_natural_allocation"> Distributes @extra_space to child @sizes by bringing smaller + line="752">Distributes @extra_space to child @sizes by bringing smaller children up to natural size first. The remaining space will be added to the @minimum_size member of the `GtkRequestedSize` struct. If all sizes reach their natural size then the remaining space is returned. - + The remainder of @extra_space after redistributing space + line="767">The remainder of @extra_space after redistributing space to @sizes. @@ -180271,20 +184155,20 @@ to @sizes. Extra space to redistribute among children after subtracting + line="754">Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation Number of requests to fit into the allocation + line="756">Number of requests to fit into the allocation An array of structs with a client pointer and a minimum/natural size + line="757">An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation. @@ -180297,7 +184181,7 @@ to @sizes. moved-to="Editable.delegate_get_property"> Gets a property of the `GtkEditable` delegate for @object. + line="1119">Gets a property of the `GtkEditable` delegate for @object. This is helper function that should be called in the `get_property` function of your `GtkEditable` implementation, before handling your @@ -180306,32 +184190,32 @@ own properties. %TRUE if the property was found + line="1132">%TRUE if the property was found a `GObject` + line="1121">a `GObject` a property ID + line="1122">a property ID value to set + line="1123">value to set the `GParamSpec` for the property + line="1124">the `GParamSpec` for the property @@ -180341,7 +184225,7 @@ own properties. moved-to="Editable.delegate_set_property"> Sets a property on the `GtkEditable` delegate for @object. + line="1053">Sets a property on the `GtkEditable` delegate for @object. This is a helper function that should be called in the `set_property` function of your `GtkEditable` implementation, before handling your @@ -180350,32 +184234,32 @@ own properties. %TRUE if the property was found + line="1066">%TRUE if the property was found a `GObject` + line="1055">a `GObject` a property ID + line="1056">a property ID value to set + line="1057">value to set the `GParamSpec` for the property + line="1058">the `GParamSpec` for the property @@ -180385,7 +184269,7 @@ own properties. moved-to="Editable.install_properties"> Overrides the `GtkEditable` properties for @class. + line="937">Overrides the `GtkEditable` properties for @class. This is a helper function that should be called in class_init, after installing your own properties. @@ -180404,20 +184288,20 @@ property IDs for these properties. the number of properties that were installed + line="958">the number of properties that were installed a `GObjectClass` + line="939">a `GObjectClass` property ID to use for the first property + line="940">property ID to use for the first property @@ -180425,9 +184309,9 @@ property IDs for these properties. Calls a function for all `GtkPrinter`s. + line="1295">Calls a function for all printers that are known to GTK. -If @func returns %TRUE, the enumeration is stopped. +If @func returns true, the enumeration is stopped. @@ -180440,7 +184324,7 @@ If @func returns %TRUE, the enumeration is stopped. destroy="2"> a function to call for each printer + line="1297">a function to call for each printer allow-none="1"> user data to pass to @func + line="1298">user data to pass to @func function to call if @data is no longer needed + line="1299">function to call if @data is no longer needed if %TRUE, wait in a recursive mainloop until + line="1300">if true, wait in a recursive mainloop until all printers are enumerated; otherwise return early @@ -180497,15 +184381,15 @@ If `libtool` means nothing to you, don't worry about it. Returns the GTK debug flags that are currently active. + line="150">Returns the GTK debug flags that are currently active. This function is intended for GTK modules that want to adjust their debug output based on GTK debug flags. - + the GTK debug flags. + line="158">the GTK debug flags. @@ -180513,7 +184397,7 @@ to adjust their debug output based on GTK debug flags. c:identifier="gtk_get_default_language"> Returns the `PangoLanguage` for the default language + line="832">Returns the `PangoLanguage` for the default language currently in effect. Note that this can change over the life of an @@ -180525,11 +184409,11 @@ the right-to-left or left-to-right text direction. This function is equivalent to [func@Pango.Language.get_default]. See that function for details. - + the default language + line="848">the default language @@ -180551,17 +184435,17 @@ If `libtool` means nothing to you, don't worry about it. c:identifier="gtk_get_locale_direction"> Get the direction of the current locale. This is the expected -reading direction for text and UI. + line="764">Gets the direction of the current locale. + +This is the expected reading direction for text and UI. This function depends on the current locale being set with -setlocale() and will default to setting the %GTK_TEXT_DIR_LTR -direction otherwise. %GTK_TEXT_DIR_NONE will never be returned. +`setlocale()` and will default to setting the `GTK_TEXT_DIR_LTR` +direction otherwise. `GTK_TEXT_DIR_NONE` will never be returned. -GTK sets the default text direction according to the locale -during gtk_init(), and you should normally use -gtk_widget_get_direction() or gtk_widget_get_default_direction() -to obtain the current direction. +GTK sets the default text direction according to the locale during +[func@Gtk.init], and you should normally use [method@Gtk.Widget.get_direction] +or [func@Gtk.Widget.get_default_direction] to obtain the current direction. This function is only needed rare cases when the locale is changed after GTK has already been initialized. In this case, @@ -180577,11 +184461,11 @@ update_locale (const char *new_locale) gtk_widget_set_default_direction (gtk_get_locale_direction ()); } ]| - + the direction of the current locale + line="794">the direction of the current locale @@ -180664,7 +184548,7 @@ and auto-scroll, but your models have to implement the Converts a color from HSV space to RGB. + line="114">Converts a color from HSV space to RGB. Input values must be in the [0.0, 1.0] range; output values will be in the same range. @@ -180676,19 +184560,19 @@ output values will be in the same range. Hue + line="116">Hue Saturation + line="117">Saturation Value + line="118">Value transfer-ownership="full"> Return value for the red component + line="119">Return value for the red component transfer-ownership="full"> Return value for the green component + line="120">Return value for the green component transfer-ownership="full"> Return value for the blue component + line="121">Return value for the blue component @@ -180723,26 +184607,35 @@ output values will be in the same range. + Registers an error quark for [class@Gtk.IconTheme] errors. + the error quark Call this function before using any other GTK functions in your GUI -applications. It will initialize everything needed to operate the -toolkit. + line="650">Initializes GTK. + +This function must be called before using any other GTK functions +in your GUI applications. -If you are using `GtkApplication`, you usually don't have to call this -function; the `GApplication::startup` handler does it for you. Though, -if you are using GApplication methods that will be invoked before `startup`, -such as `local_command_line`, you may need to initialize stuff explicitly. +It will initialize everything needed to operate the toolkit. In particular, +it will open the default display (see [func@Gdk.Display.get_default]). -This function will terminate your program if it was unable to -initialize the windowing system for some reason. If you want -your program to fall back to a textual interface, call -[func@Gtk.init_check] instead. +If you are using [class@Gtk.Application], you usually don't have to call this +function; the [vfunc@Gio.Application.startup] handler does it for you. Though, +if you are using `GApplication` methods that will be invoked before `startup`, +such as `local_command_line`, you may need to initialize GTK explicitly. + +This function will terminate your program if it was unable to initialize +the windowing system for some reason. If you want your program to fall back +to a textual interface, call [func@Gtk.init_check] instead. GTK calls `signal (SIGPIPE, SIG_IGN)` during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical @@ -180757,9 +184650,11 @@ libdbus or gvfs) might do similar things. This function does the same work as gtk_init() with only a single -change: It does not terminate the program if the windowing system -can’t be initialized. Instead it returns %FALSE on failure. + line="603">Initializes GTK. + +This function does the same work as [func@Gtk.init] with only a +single change: It does not terminate the program if the windowing +system can’t be initialized. Instead it returns false on failure. This way the application can fall back to some other means of communication with the user - for example a curses or command line @@ -180768,22 +184663,22 @@ interface. %TRUE if the windowing system has been successfully - initialized, %FALSE otherwise + line="616">true if the windowing system has been successfully + initialized, false otherwise Use this function to check if GTK has been initialized. + line="748">Returns whether GTK has been initialized. See [func@Gtk.init]. the initialization status + line="755">the initialization status @@ -180792,19 +184687,19 @@ See [func@Gtk.init]. moved-to="Native.get_for_surface"> Finds the `GtkNative` associated with the surface. + line="269">Finds the `GtkNative` associated with the surface. the `GtkNative` that is associated with @surface + line="275">the `GtkNative` that is associated with @surface a `GdkSurface` + line="271">a `GdkSurface` @@ -180818,7 +184713,7 @@ See [func@Gtk.init]. filename="gtk/gtksorter.c" line="374">Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. - + c:identifier="gtk_param_spec_expression"> Creates a new `GParamSpec` instance for a property holding a `GtkExpression`. + line="588">Creates a new `GParamSpec` instance for a property holding a `GtkExpression`. See `g_param_spec_internal()` for details on the property strings. a newly created property specification + line="599">a newly created property specification canonical name of the property + line="590">canonical name of the property a user-readable name for the property + line="591">a user-readable name for the property a user-readable description of the property + line="592">a user-readable description of the property flags for the property + line="593">flags for the property @@ -180922,11 +184817,11 @@ See `g_param_spec_internal()` for details on the property strings. moved-to="PrintError.quark"> Registers an error quark for `GtkPrintOperation` if necessary. + line="165">Registers an error quark for `GtkPrintOperation` if necessary. The error quark used for `GtkPrintOperation` errors. + line="170">The error quark used for `GtkPrintOperation` errors. @@ -180934,19 +184829,20 @@ See `g_param_spec_internal()` for details on the property strings. c:identifier="gtk_print_run_page_setup_dialog"> Runs a page setup dialog, letting the user modify the values from -@page_setup. If the user cancels the dialog, the returned `GtkPageSetup` -is identical to the passed in @page_setup, otherwise it contains the -modifications done in the dialog. + line="977">Runs a page setup dialog, letting the user modify the values from @page_setup. + +If the user cancels the dialog, the returned `GtkPageSetup` is identical +to the passed in @page_setup, otherwise it contains the modifications +done in the dialog. Note that this function may use a recursive mainloop to show the page -setup dialog. See gtk_print_run_page_setup_dialog_async() if this is +setup dialog. See [func@Gtk.print_run_page_setup_dialog_async] if this is a problem. a new `GtkPageSetup` + line="993">a new `GtkPageSetup` @@ -180956,7 +184852,7 @@ a problem. allow-none="1"> transient parent + line="979">transient parent allow-none="1"> an existing `GtkPageSetup` + line="980">an existing `GtkPageSetup` a `GtkPrintSettings` + line="981">a `GtkPrintSettings` @@ -180980,11 +184876,11 @@ a problem. c:identifier="gtk_print_run_page_setup_dialog_async"> Runs a page setup dialog, letting the user modify the values from @page_setup. + line="1029">Runs a page setup dialog, letting the user modify the values from @page_setup. -In contrast to gtk_print_run_page_setup_dialog(), this function returns after -showing the page setup dialog on platforms that support this, and calls @done_cb -from a signal handler for the ::response signal of the dialog. +In contrast to [func@Gtk.print_run_page_setup_dialog], this function returns +after showing the page setup dialog on platforms that support this, and calls +@done_cb from a signal handler for the ::response signal of the dialog. @@ -180996,7 +184892,7 @@ from a signal handler for the ::response signal of the dialog. allow-none="1"> transient parent + line="1031">transient parent allow-none="1"> an existing `GtkPageSetup` + line="1032">an existing `GtkPageSetup` a `GtkPrintSettings` + line="1033">a `GtkPrintSettings` closure="4"> a function to call when the user saves + line="1034">a function to call when the user saves the modified page setup @@ -181030,7 +184926,7 @@ from a signal handler for the ::response signal of the dialog. allow-none="1"> user data to pass to @done_cb + line="1036">user data to pass to @done_cb @@ -181038,7 +184934,13 @@ from a signal handler for the ::response signal of the dialog. + Registers an error quark for [class@RecentManager] errors. + the error quark @@ -181682,7 +185584,7 @@ Typical option mark rendering: Converts a color from RGB space to HSV. + line="198">Converts a color from RGB space to HSV. Input values must be in the [0.0, 1.0] range; output values will be in the same range. @@ -181694,19 +185596,19 @@ output values will be in the same range. Red + line="200">Red Green + line="201">Green Blue + line="202">Blue transfer-ownership="full"> Return value for the hue component + line="203">Return value for the hue component transfer-ownership="full"> Return value for the saturation component + line="204">Return value for the saturation component transfer-ownership="full"> Return value for the value component + line="205">Return value for the value component @@ -181741,8 +185643,8 @@ output values will be in the same range. Sets the GTK debug flags. - + line="169">Sets the GTK debug flags. + @@ -181750,7 +185652,7 @@ output values will be in the same range. the debug flags to set + line="171">the debug flags to set @@ -181760,11 +185662,11 @@ output values will be in the same range. introspectable="0"> A convenience function for showing an application’s about dialog. + line="2247">A convenience function for showing an application’s about dialog. The constructed dialog is associated with the parent window and reused for future invocations of this function. - + @@ -181775,19 +185677,19 @@ reused for future invocations of this function. allow-none="1"> the parent top-level window + line="2249">the parent top-level window the name of the first property + line="2250">the name of the first property value of first property, followed by more pairs of property + line="2251">value of first property, followed by more pairs of property name and value, `NULL`-terminated @@ -181799,7 +185701,7 @@ reused for future invocations of this function. deprecated-version="4.10"> This function launches the default application for showing + line="300">This function launches the default application for showing a given uri, or shows an error dialog if that fails. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead @@ -181814,19 +185716,19 @@ a given uri, or shows an error dialog if that fails. allow-none="1"> parent window + line="302">parent window the uri to show + line="303">the uri to show timestamp from the event that triggered this call, or %GDK_CURRENT_TIME + line="304">timestamp from the event that triggered this call, or %GDK_CURRENT_TIME @@ -181837,11 +185739,10 @@ a given uri, or shows an error dialog if that fails. deprecated-version="4.10"> This function launches the default application for showing + line="172">This function launches the default application for showing a given uri. The @callback will be called when the launch is completed. -It should call gtk_show_uri_full_finish() to obtain the result. This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly. @@ -181858,19 +185759,19 @@ necessary for sandbox helpers to parent their dialogs properly. allow-none="1"> parent window + line="174">parent window the uri to show + line="175">the uri to show timestamp from the event that triggered this call, or %GDK_CURRENT_TIME + line="176">timestamp from the event that triggered this call, or %GDK_CURRENT_TIME allow-none="1"> a `GCancellable` to cancel the launch + line="177">a `GCancellable` to cancel the launch closure="5"> a callback to call when the action is complete + line="178">a callback to call when the action is complete + allow-none="1"> data to pass to @callback + line="179">data to pass to @callback @@ -181912,15 +185812,15 @@ necessary for sandbox helpers to parent their dialogs properly. throws="1"> Finishes the gtk_show_uri() call and returns the result + line="252">Finishes the gtk_show_uri() call and returns the result of the operation. - Use [method@Gtk.FileLauncher.launch_finish] or - [method@Gtk.UriLauncher.launch_finish] instead + Use [method@Gtk.FileLauncher.launch] or + [method@Gtk.UriLauncher.launch] instead %TRUE if the URI was shown successfully. + line="261">%TRUE if the URI was shown successfully. Otherwise, %FALSE is returned and @error is set @@ -181928,13 +185828,13 @@ of the operation. the `GtkWindow` passed to gtk_show_uri() + line="254">the `GtkWindow` passed to gtk_show_uri() `GAsyncResult` that was passed to @callback + line="255">`GAsyncResult` that was passed to @callback @@ -182043,33 +185943,60 @@ condition is not satisfied. + Prints an assertion message for gtk_test_accessible_assert_role(). + a domain + a file name + the line in @file + a function name in @file + the expression being tested + a `GtkAccessible` + the expected `GtkAccessibleRole` + the actual `GtkAccessibleRole` @@ -182079,32 +186006,32 @@ condition is not satisfied. introspectable="0"> Checks whether the accessible @property of @accessible is set to + line="267">Checks whether the accessible @property of @accessible is set to a specific value. the value of the accessible property + line="276">the value of the accessible property a `GtkAccessible` + line="269">a `GtkAccessible` a `GtkAccessibleProperty` + line="270">a `GtkAccessibleProperty` the expected value of @property + line="271">the expected value of @property @@ -182114,32 +186041,32 @@ a specific value. introspectable="0"> Checks whether the accessible @relation of @accessible is set to + line="431">Checks whether the accessible @relation of @accessible is set to a specific value. the value of the accessible relation + line="440">the value of the accessible relation a `GtkAccessible` + line="433">a `GtkAccessible` a `GtkAccessibleRelation` + line="434">a `GtkAccessibleRelation` the expected value of @relation + line="435">the expected value of @relation @@ -182149,32 +186076,32 @@ a specific value. introspectable="0"> Checks whether the accessible @state of @accessible is set to + line="349">Checks whether the accessible @state of @accessible is set to a specific value. the value of the accessible state + line="358">the value of the accessible state a `GtkAccessible` + line="351">a `GtkAccessible` a `GtkAccessibleState` + line="352">a `GtkAccessibleState` the expected value of @state + line="353">the expected value of @state @@ -182183,25 +186110,25 @@ a specific value. c:identifier="gtk_test_accessible_has_property"> Checks whether the `GtkAccessible` has @property set. + line="238">Checks whether the `GtkAccessible` has @property set. %TRUE if the @property is set in the @accessible + line="245">%TRUE if the @property is set in the @accessible a `GtkAccessible` + line="240">a `GtkAccessible` a `GtkAccessibleProperty` + line="241">a `GtkAccessibleProperty` @@ -182210,25 +186137,25 @@ a specific value. c:identifier="gtk_test_accessible_has_relation"> Checks whether the `GtkAccessible` has @relation set. + line="402">Checks whether the `GtkAccessible` has @relation set. %TRUE if the @relation is set in the @accessible + line="409">%TRUE if the @relation is set in the @accessible a `GtkAccessible` + line="404">a `GtkAccessible` a `GtkAccessibleRelation` + line="405">a `GtkAccessibleRelation` @@ -182237,26 +186164,26 @@ a specific value. c:identifier="gtk_test_accessible_has_role"> Checks whether the `GtkAccessible:accessible-role` of the accessible + line="219">Checks whether the `GtkAccessible:accessible-role` of the accessible is @role. %TRUE if the role matches + line="227">%TRUE if the role matches a `GtkAccessible` + line="221">a `GtkAccessible` a `GtkAccessibleRole` + line="222">a `GtkAccessibleRole` @@ -182265,25 +186192,25 @@ is @role. c:identifier="gtk_test_accessible_has_state"> Checks whether the `GtkAccessible` has @state set. + line="320">Checks whether the `GtkAccessible` has @state set. %TRUE if the @state is set in the @accessible + line="327">%TRUE if the @state is set in the @accessible a `GtkAccessible` + line="322">a `GtkAccessible` a `GtkAccessibleState` + line="323">a `GtkAccessibleState` @@ -182291,7 +186218,7 @@ is @role. This function is used to initialize a GTK test program. + line="51">This function is used to initialize a GTK test program. It will in turn call g_test_init() and gtk_init() to properly initialize the testing framework and graphical toolkit. It’ll @@ -182311,7 +186238,7 @@ processed and stripped from @argc and @argv. transfer-ownership="none"> Address of the `argc` parameter of the + line="53">Address of the `argc` parameter of the main() function. Changed if any arguments were handled. @@ -182321,7 +186248,7 @@ processed and stripped from @argc and @argv. transfer-ownership="full"> Address of the `argv` + line="55">Address of the `argv` parameter of main(). Any parameters understood by g_test_init() or gtk_init() are stripped before return. @@ -182331,7 +186258,7 @@ processed and stripped from @argc and @argv. currently unused + line="58">currently unused @@ -182340,13 +186267,13 @@ processed and stripped from @argc and @argv. c:identifier="gtk_test_list_all_types"> Return the type ids that have been registered after + line="134">Return the type ids that have been registered after calling gtk_test_register_all_types(). + line="141"> 0-terminated array of type ids @@ -182359,7 +186286,7 @@ calling gtk_test_register_all_types(). transfer-ownership="full"> location to store number of types + line="136">location to store number of types @@ -182368,7 +186295,7 @@ calling gtk_test_register_all_types(). c:identifier="gtk_test_register_all_types"> Force registration of all core GTK object types. + line="152">Force registration of all core GTK object types. This allows to refer to any of those object types via g_type_from_name() after calling this function. @@ -182381,7 +186308,7 @@ g_type_from_name() after calling this function. c:identifier="gtk_test_widget_wait_for_draw"> Enters the main loop and waits for @widget to be “drawn”. + line="99">Enters the main loop and waits for @widget to be “drawn”. In this context that means it waits for the frame clock of @widget to have run a full styling, layout and drawing cycle. @@ -182397,7 +186324,7 @@ server. the widget to wait for + line="101">the widget to wait for @@ -182491,10 +186418,10 @@ The returned path must be freed with gtk_tree_path_free(). deprecated-version="4.10"> Lets a set of row reference created by + line="2673">Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-deleted signal. - + @@ -182502,13 +186429,13 @@ model emitted the ::row-deleted signal. a `GObject` + line="2675">a `GObject` the path position that was deleted + line="2676">the path position that was deleted @@ -182520,10 +186447,10 @@ model emitted the ::row-deleted signal. deprecated-version="4.10"> Lets a set of row reference created by + line="2653">Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-inserted signal. - + @@ -182531,13 +186458,13 @@ model emitted the ::row-inserted signal. a `GObject` + line="2655">a `GObject` the row position that was inserted + line="2656">the row position that was inserted @@ -182550,10 +186477,10 @@ model emitted the ::row-inserted signal. deprecated-version="4.10"> Lets a set of row reference created by + line="2693">Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::rows-reordered signal. - + @@ -182561,25 +186488,25 @@ model emitted the ::rows-reordered signal. a `GObject` + line="2695">a `GObject` the parent path of the reordered signal + line="2696">the parent path of the reordered signal the iter pointing to the parent of the reordered + line="2697">the iter pointing to the parent of the reordered the new order of rows + line="2698">the new order of rows @@ -182590,20 +186517,20 @@ model emitted the ::rows-reordered signal. c:identifier="gtk_value_dup_expression"> Retrieves the `GtkExpression` stored inside the given `value`, and acquires + line="496">Retrieves the `GtkExpression` stored inside the given `value`, and acquires a reference to it. a `GtkExpression` + line="503">a `GtkExpression` a `GValue` initialized with type `GTK_TYPE_EXPRESSION` + line="498">a `GValue` initialized with type `GTK_TYPE_EXPRESSION` @@ -182612,19 +186539,19 @@ a reference to it. c:identifier="gtk_value_get_expression"> Retrieves the `GtkExpression` stored inside the given `value`. + line="480">Retrieves the `GtkExpression` stored inside the given `value`. a `GtkExpression` + line="486">a `GtkExpression` a `GValue` initialized with type `GTK_TYPE_EXPRESSION` + line="482">a `GValue` initialized with type `GTK_TYPE_EXPRESSION` @@ -182633,7 +186560,7 @@ a reference to it. c:identifier="gtk_value_set_expression"> Stores the given `GtkExpression` inside `value`. + line="416">Stores the given `GtkExpression` inside `value`. The `GValue` will acquire a reference to the `expression`. @@ -182644,13 +186571,13 @@ The `GValue` will acquire a reference to the `expression`. a `GValue` initialized with type `GTK_TYPE_EXPRESSION` + line="418">a `GValue` initialized with type `GTK_TYPE_EXPRESSION` a `GtkExpression` + line="419">a `GtkExpression` @@ -182659,7 +186586,7 @@ The `GValue` will acquire a reference to the `expression`. c:identifier="gtk_value_take_expression"> Stores the given `GtkExpression` inside `value`. + line="448">Stores the given `GtkExpression` inside `value`. This function transfers the ownership of the `expression` to the `GValue`. @@ -182670,7 +186597,7 @@ This function transfers the ownership of the `expression` to the `GValue`. a `GValue` initialized with type `GTK_TYPE_EXPRESSION` + line="450">a `GValue` initialized with type `GTK_TYPE_EXPRESSION` allow-none="1"> a `GtkExpression` + line="451">a `GtkExpression` @@ -182689,23 +186616,23 @@ This function transfers the ownership of the `expression` to the `GValue`. introspectable="0"> Binds a callback function defined in a template to the @widget_class. + line="731">Binds a callback function defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_callback_full() function. It is not -supported after gtk_widget_class_set_template_scope() has been used -on @widget_class. - +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_callback_full]. It is not +supported after [method@Gtk.WidgetClass.set_template_scope] has been +called on @widget_class. + a `GtkWidgetClass` + line="733">a widget class the callback symbol + line="734">the callback symbol @@ -182714,29 +186641,29 @@ on @widget_class. introspectable="0"> Binds a child widget defined in a template to the @widget_class. + line="748">Binds a child widget defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName instance structure. - + a `GtkWidgetClass` + line="750">a widget class the type name of this widget + line="751">the type name of this widget name of the instance member in the instance struct for @data_type + line="752">name of the instance member in the instance struct for @data_type @@ -182745,31 +186672,32 @@ instance structure. introspectable="0"> Binds a child widget defined in a template to the @widget_class, and -also makes it available as an internal child in GtkBuilder, under the -name @member_name. + line="768">Binds a child widget defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +Additionally, the child widget is made available as an internal +child in `GtkBuilder`, under the name @member_name. + +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName instance structure. - + a `GtkWidgetClass` + line="770">a widget class the type name, in CamelCase + line="771">the type name, in CamelCase name of the instance member in the instance struct for @data_type + line="772">name of the instance member in the instance struct for @data_type @@ -182778,31 +186706,32 @@ instance structure. introspectable="0"> Binds a child widget defined in a template to the @widget_class, and -also makes it available as an internal child in GtkBuilder, under the -name @member_name. + line="812">Binds a child widget defined in a template to the @widget_class. + +Additionally, the child is made available as an internal child +in `GtkBuilder`, under the name @member_name. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName private data structure. - + a `GtkWidgetClass` + line="814">a widget class the type name, in CamelCase + line="815">the type name, in CamelCase name of the instance private member on the private struct for @data_type + line="816">name of the instance private member on the private struct for @data_type @@ -182811,30 +186740,30 @@ private data structure. introspectable="0"> Binds a child widget defined in a template to the @widget_class. + line="791">Binds a child widget defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@GtkWidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName -private data structure (it uses G_PRIVATE_OFFSET(), so the private struct -must be added with G_ADD_PRIVATE()). - +private data structure (it uses `G_PRIVATE_OFFSET()`, so the private struct +must be added with `G_ADD_PRIVATE())`. + a `GtkWidgetClass` + line="793">a widget class the type name of this widget + line="794">the type name of this widget name of the instance private member in the private struct for @data_type + line="795">name of the instance private member in the private struct for @data_type diff --git a/generator/src/main/resources/gir/Pango-1.0.gir b/generator/src/main/resources/gir/Pango-1.0.gir index c07a7e5..f96c0c8 100644 --- a/generator/src/main/resources/gir/Pango-1.0.gir +++ b/generator/src/main/resources/gir/Pango-1.0.gir @@ -246,6 +246,10 @@ one should use the wrapper functions provided for `PangoAttribute`. + function to duplicate an attribute of this type + (see [method@Pango.Attribute.copy]) @@ -259,6 +263,10 @@ one should use the wrapper functions provided for `PangoAttribute`. + function to free an attribute of this type + (see [method@Pango.Attribute.destroy]) @@ -272,6 +280,10 @@ one should use the wrapper functions provided for `PangoAttribute`. + function to check two attributes of this type for equality + (see [method@Pango.Attribute.equal]) @@ -450,7 +462,7 @@ font features as an attribute. version="1.38"> Create a new font features tag attribute. + line="1224">Create a new font features tag attribute. You can use this attribute to select OpenType font features like small-caps, alternative glyphs, ligatures, etc. for fonts that support them. @@ -458,7 +470,7 @@ alternative glyphs, ligatures, etc. for fonts that support them. the newly allocated + line="1234">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -467,7 +479,7 @@ alternative glyphs, ligatures, etc. for fonts that support them. a string with OpenType font features, with the syntax of the [CSS + line="1226">a string with OpenType font features, with the syntax of the [CSS font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc) @@ -512,12 +524,12 @@ currently in effect can be queried. Copy a `PangoAttrIterator`. + line="3314">Copy a `PangoAttrIterator`. the newly allocated + line="3320">the newly allocated `PangoAttrIterator`, which should be freed with [method@Pango.AttrIterator.destroy] @@ -526,7 +538,7 @@ currently in effect can be queried. a `PangoAttrIterator` + line="3316">a `PangoAttrIterator` @@ -534,7 +546,7 @@ currently in effect can be queried. Destroy a `PangoAttrIterator` and free all associated memory. + line="3350">Destroy a `PangoAttrIterator` and free all associated memory. @@ -543,7 +555,7 @@ currently in effect can be queried. a `PangoAttrIterator` + line="3352">a `PangoAttrIterator` @@ -551,7 +563,7 @@ currently in effect can be queried. Find the current attribute of a particular type + line="3365">Find the current attribute of a particular type at the iterator location. When multiple attributes of the same type overlap, @@ -561,7 +573,7 @@ current location is used. the current + line="3377">the current attribute of the given type, or %NULL if no attribute of that type applies to the current location. @@ -570,13 +582,13 @@ current location is used. a `PangoAttrIterator` + line="3367">a `PangoAttrIterator` the type of attribute to find + line="3368">the type of attribute to find @@ -586,13 +598,13 @@ current location is used. version="1.2"> Gets a list of all attributes at the current position of the + line="3579">Gets a list of all attributes at the current position of the iterator. + line="3586"> a list of all attributes for the current range. To free this value, call [method@Pango.Attribute.destroy] on each value and g_slist_free() on the list. @@ -604,7 +616,7 @@ iterator. a `PangoAttrIterator` + line="3581">a `PangoAttrIterator` @@ -612,7 +624,7 @@ iterator. Get the font and other attributes at the current + line="3403">Get the font and other attributes at the current iterator position. @@ -622,13 +634,13 @@ iterator position. a `PangoAttrIterator` + line="3405">a `PangoAttrIterator` a `PangoFontDescription` to fill in with the current + line="3406">a `PangoFontDescription` to fill in with the current values. The family name in this structure will be set using [method@Pango.FontDescription.set_family_static] using values from an attribute in the `PangoAttrList` associated @@ -645,7 +657,7 @@ iterator position. allow-none="1"> location to store language tag + line="3413">location to store language tag for item, or %NULL if none is found. @@ -657,7 +669,7 @@ iterator position. allow-none="1"> + line="3415"> location in which to store a list of non-font attributes at the the current position; only the highest priority value of each attribute will be added to this list. In @@ -672,12 +684,12 @@ iterator position. Advance the iterator until the next change of style. + line="3243">Advance the iterator until the next change of style. %FALSE if the iterator is at the end + line="3249">%FALSE if the iterator is at the end of the list, otherwise %TRUE @@ -685,7 +697,7 @@ iterator position. a `PangoAttrIterator` + line="3245">a `PangoAttrIterator` @@ -693,7 +705,7 @@ iterator position. Get the range of the current segment. + line="3217">Get the range of the current segment. Note that the stored return values are signed, not unsigned like the values in `PangoAttribute`. To deal with this API @@ -707,7 +719,7 @@ a signed integer are clamped to %G_MAXINT. a PangoAttrIterator + line="3219">a PangoAttrIterator transfer-ownership="full"> location to store the start of the range + line="3220">location to store the start of the range transfer-ownership="full"> location to store the end of the range + line="3221">location to store the end of the range @@ -795,13 +807,13 @@ should not use a single `PangoAttrList` for more than one paragraph of text. Create a new empty attribute list with a reference + line="1856">Create a new empty attribute list with a reference count of one. the newly allocated + line="1862">the newly allocated `PangoAttrList`, which should be freed with [method@Pango.AttrList.unref] @@ -810,7 +822,7 @@ count of one. Insert the given attribute into the `PangoAttrList`. + line="2053">Insert the given attribute into the `PangoAttrList`. It will replace any attributes of the same type on that segment and be merged with any adjoining @@ -830,13 +842,13 @@ never removes or combines existing attributes. a `PangoAttrList` + line="2055">a `PangoAttrList` the attribute to insert + line="2056">the attribute to insert @@ -844,12 +856,12 @@ never removes or combines existing attributes. Copy @list and return an identical new list. + line="1941">Copy @list and return an identical new list. the newly allocated + line="1947">the newly allocated `PangoAttrList`, with a reference count of one, which should be freed with [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL. @@ -862,7 +874,7 @@ never removes or combines existing attributes. allow-none="1"> a `PangoAttrList` + line="1943">a `PangoAttrList` @@ -870,7 +882,7 @@ never removes or combines existing attributes. Checks whether @list and @other_list contain the same + line="2433">Checks whether @list and @other_list contain the same attributes and whether those attributes apply to the same ranges. @@ -880,7 +892,7 @@ contains duplicates. %TRUE if the lists are equal, %FALSE if + line="2445">%TRUE if the lists are equal, %FALSE if they aren't @@ -888,13 +900,13 @@ contains duplicates. a `PangoAttrList` + line="2435">a `PangoAttrList` the other `PangoAttrList` + line="2436">the other `PangoAttrList` @@ -904,14 +916,14 @@ contains duplicates. version="1.2"> Given a `PangoAttrList` and callback function, removes + line="2511">Given a `PangoAttrList` and callback function, removes any elements of @list for which @func returns %TRUE and inserts them into a new list. the new + line="2522">the new `PangoAttrList` or %NULL if no attributes of the given types were found @@ -920,7 +932,7 @@ inserts them into a new list. a `PangoAttrList` + line="2513">a `PangoAttrList` closure="1"> callback function; + line="2514">callback function; returns %TRUE if an attribute should be filtered out @@ -939,7 +951,7 @@ inserts them into a new list. allow-none="1"> Data to be passed to @func + line="2516">Data to be passed to @func @@ -949,12 +961,12 @@ inserts them into a new list. version="1.44"> Gets a list of all attributes in @list. + line="2399">Gets a list of all attributes in @list. + line="2405"> a list of all attributes in @list. To free this value, call [method@Pango.Attribute.destroy] on each value and g_slist_free() on the list. @@ -966,7 +978,7 @@ inserts them into a new list. a `PangoAttrList` + line="2401">a `PangoAttrList` @@ -974,14 +986,14 @@ inserts them into a new list. Create a iterator initialized to the beginning of the list. + line="3192">Create a iterator initialized to the beginning of the list. @list must not be modified until this iterator is freed. the newly allocated + line="3200">the newly allocated `PangoAttrIterator`, which should be freed with [method@Pango.AttrIterator.destroy] @@ -990,7 +1002,7 @@ inserts them into a new list. a `PangoAttrList` + line="3194">a `PangoAttrList` @@ -998,7 +1010,7 @@ inserts them into a new list. Insert the given attribute into the `PangoAttrList`. + line="2013">Insert the given attribute into the `PangoAttrList`. It will be inserted after all other attributes with a matching @start_index. @@ -1010,13 +1022,13 @@ matching @start_index. a `PangoAttrList` + line="2015">a `PangoAttrList` the attribute to insert + line="2016">the attribute to insert @@ -1025,7 +1037,7 @@ matching @start_index. c:identifier="pango_attr_list_insert_before"> Insert the given attribute into the `PangoAttrList`. + line="2033">Insert the given attribute into the `PangoAttrList`. It will be inserted before all other attributes with a matching @start_index. @@ -1037,13 +1049,13 @@ matching @start_index. a `PangoAttrList` + line="2035">a `PangoAttrList` the attribute to insert + line="2036">the attribute to insert @@ -1051,13 +1063,13 @@ matching @start_index. Increase the reference count of the given attribute + line="1876">Increase the reference count of the given attribute list by one. The attribute list passed in + line="1883">The attribute list passed in @@ -1067,7 +1079,7 @@ list by one. allow-none="1"> a `PangoAttrList` + line="1878">a `PangoAttrList` @@ -1075,7 +1087,7 @@ list by one. This function opens up a hole in @list, fills it + line="2299">This function opens up a hole in @list, fills it in with attributes from the left, and then merges @other on top of the hole. @@ -1101,25 +1113,25 @@ This mode is useful for merging two lists of attributes together. a `PangoAttrList` + line="2301">a `PangoAttrList` another `PangoAttrList` + line="2302">another `PangoAttrList` the position in @list at which to insert @other + line="2303">the position in @list at which to insert @other the length of the spliced segment. (Note that this + line="2304">the length of the spliced segment. (Note that this must be specified since the attributes in @other may only be present at some subsection of this range) @@ -1131,17 +1143,19 @@ This mode is useful for merging two lists of attributes together. version="1.50"> Serializes a `PangoAttrList` to a string. + line="2704">Serializes a `PangoAttrList` to a string. In the resulting string, serialized attributes are separated by newlines or commas. Individual attributes are serialized to a string of the form - START END TYPE VALUE + [START END] TYPE VALUE Where START and END are the indices (with -1 being accepted in place of MAXUINT), TYPE is the nickname of the attribute value type, e.g. _weight_ or _stretch_, and the value is serialized according to its type: +Optionally, START and END can be omitted to indicate unlimited extent. + - enum values as nick or numeric value - boolean values as _true_ or _false_ - integers and floats as numbers @@ -1153,14 +1167,12 @@ _weight_ or _stretch_, and the value is serialized according to its type: Examples: -``` -0 10 foreground red, 5 15 weight bold, 0 200 font-desc "Sans 10" -``` + 0 10 foreground red, 5 15 weight bold, 0 200 font-desc "Sans 10" -``` -0 -1 weight 700 -0 100 family Times -``` + 0 -1 weight 700 + 0 100 family Times + + weight bold To parse the returned value, use [func@Pango.AttrList.from_string]. @@ -1169,14 +1181,14 @@ Note that shape attributes can not be serialized. a newly allocated string + line="2743">a newly allocated string a `PangoAttrList` + line="2706">a `PangoAttrList` @@ -1184,7 +1196,7 @@ Note that shape attributes can not be serialized. Decrease the reference count of the given attribute + line="1916">Decrease the reference count of the given attribute list by one. If the result is zero, free the attribute list @@ -1200,7 +1212,7 @@ and the attributes it contains. allow-none="1"> a `PangoAttrList` + line="1918">a `PangoAttrList` @@ -1210,7 +1222,7 @@ and the attributes it contains. version="1.44"> Update indices of attributes in @list for a change in the + line="2216">Update indices of attributes in @list for a change in the text they refer to. The change that this function applies is removing @remove @@ -1232,25 +1244,25 @@ behind @pos + @remove. a `PangoAttrList` + line="2218">a `PangoAttrList` the position of the change + line="2219">the position of the change the number of removed bytes + line="2220">the number of removed bytes the number of added bytes + line="2221">the number of added bytes @@ -1260,7 +1272,7 @@ behind @pos + @remove. version="1.50"> Deserializes a `PangoAttrList` from a string. + line="2819">Deserializes a `PangoAttrList` from a string. This is the counterpart to [method@Pango.AttrList.to_string]. See that functions for details about the format. @@ -1268,14 +1280,14 @@ See that functions for details about the format. a new `PangoAttrList` + line="2828">a new `PangoAttrList` a string + line="2821">a string @@ -1326,7 +1338,7 @@ impose shape restrictions. Create a new shape attribute. + line="1145">Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. @@ -1336,7 +1348,7 @@ or a widget inside a `PangoLayout`. the newly allocated + line="1157">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -1345,13 +1357,13 @@ or a widget inside a `PangoLayout`. ink rectangle to assign to each character + line="1147">ink rectangle to assign to each character logical rectangle to assign to each character + line="1148">logical rectangle to assign to each character @@ -1361,7 +1373,7 @@ or a widget inside a `PangoLayout`. version="1.8"> Creates a new shape attribute. + line="1092">Creates a new shape attribute. Like [func@Pango.AttrShape.new], but a user data pointer is also provided; this pointer can be accessed when later @@ -1370,7 +1382,7 @@ rendering the glyph. the newly allocated + line="1109">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -1379,13 +1391,13 @@ rendering the glyph. ink rectangle to assign to each character + line="1094">ink rectangle to assign to each character logical rectangle to assign to each character + line="1095">logical rectangle to assign to each character allow-none="1"> user data pointer + line="1096">user data pointer destroy="4"> function to copy @data when the + line="1097">function to copy @data when the attribute is copied. If %NULL, @data is simply copied as a pointer @@ -1417,7 +1429,7 @@ rendering the glyph. scope="async"> function to free @data when the + line="1100">function to free @data when the attribute is freed @@ -1965,14 +1977,14 @@ will have an all-inclusive range of [0,%G_MAXUINT]. version="1.50"> Returns the attribute cast to `PangoAttrColor`. + line="1708">Returns the attribute cast to `PangoAttrColor`. This is mainly useful for language bindings. The attribute as `PangoAttrColor`, + line="1716">The attribute as `PangoAttrColor`, or %NULL if it's not a color attribute @@ -1980,7 +1992,7 @@ This is mainly useful for language bindings. A `PangoAttribute` such as foreground + line="1710">A `PangoAttribute` such as foreground @@ -1990,14 +2002,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrFloat`. + line="1628">Returns the attribute cast to `PangoAttrFloat`. This is mainly useful for language bindings. The attribute as `PangoAttrFloat`, + line="1636">The attribute as `PangoAttrFloat`, or %NULL if it's not a floating point attribute @@ -2005,7 +2017,7 @@ This is mainly useful for language bindings. A `PangoAttribute` such as scale + line="1630">A `PangoAttribute` such as scale @@ -2015,14 +2027,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrFontDesc`. + line="1738">Returns the attribute cast to `PangoAttrFontDesc`. This is mainly useful for language bindings. The attribute as `PangoAttrFontDesc`, + line="1746">The attribute as `PangoAttrFontDesc`, or %NULL if it's not a font description attribute @@ -2030,7 +2042,7 @@ This is mainly useful for language bindings. A `PangoAttribute` representing a font description + line="1740">A `PangoAttribute` representing a font description @@ -2040,14 +2052,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrFontFeatures`. + line="1764">Returns the attribute cast to `PangoAttrFontFeatures`. This is mainly useful for language bindings. The attribute as `PangoAttrFontFeatures`, + line="1772">The attribute as `PangoAttrFontFeatures`, or %NULL if it's not a font features attribute @@ -2055,7 +2067,7 @@ This is mainly useful for language bindings. A `PangoAttribute` representing font features + line="1766">A `PangoAttribute` representing font features @@ -2065,14 +2077,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrInt`. + line="1580">Returns the attribute cast to `PangoAttrInt`. This is mainly useful for language bindings. The attribute as `PangoAttrInt`, + line="1588">The attribute as `PangoAttrInt`, or %NULL if it's not an integer attribute @@ -2080,7 +2092,7 @@ This is mainly useful for language bindings. A `PangoAttribute` such as weight + line="1582">A `PangoAttribute` such as weight @@ -2090,14 +2102,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrLanguage`. + line="1790">Returns the attribute cast to `PangoAttrLanguage`. This is mainly useful for language bindings. The attribute as `PangoAttrLanguage`, + line="1798">The attribute as `PangoAttrLanguage`, or %NULL if it's not a language attribute @@ -2105,7 +2117,7 @@ This is mainly useful for language bindings. A `PangoAttribute` representing a language + line="1792">A `PangoAttribute` representing a language @@ -2115,14 +2127,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrShape`. + line="1816">Returns the attribute cast to `PangoAttrShape`. This is mainly useful for language bindings. The attribute as `PangoAttrShape`, + line="1824">The attribute as `PangoAttrShape`, or %NULL if it's not a shape attribute @@ -2130,7 +2142,7 @@ This is mainly useful for language bindings. A `PangoAttribute` representing a shape + line="1818">A `PangoAttribute` representing a shape @@ -2140,14 +2152,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrSize`. + line="1681">Returns the attribute cast to `PangoAttrSize`. This is mainly useful for language bindings. The attribute as `PangoAttrSize`, + line="1689">The attribute as `PangoAttrSize`, or NULL if it's not a size attribute @@ -2155,7 +2167,7 @@ This is mainly useful for language bindings. A `PangoAttribute` representing a size + line="1683">A `PangoAttribute` representing a size @@ -2165,14 +2177,14 @@ This is mainly useful for language bindings. version="1.50"> Returns the attribute cast to `PangoAttrString`. + line="1655">Returns the attribute cast to `PangoAttrString`. This is mainly useful for language bindings. The attribute as `PangoAttrString`, + line="1663">The attribute as `PangoAttrString`, or %NULL if it's not a string attribute @@ -2180,7 +2192,7 @@ This is mainly useful for language bindings. A `PangoAttribute` such as family + line="1657">A `PangoAttribute` such as family @@ -3946,7 +3958,7 @@ public apis. c:type="PangoEllipsizeMode"> `PangoEllipsizeMode` describes what sort of ellipsization + line="97">`PangoEllipsizeMode` describes what sort of ellipsization should be applied to text. In the ellipsization process characters are removed from the @@ -3959,7 +3971,7 @@ with an ellipsis. glib:name="PANGO_ELLIPSIZE_NONE"> No ellipsization + line="99">No ellipsization glib:name="PANGO_ELLIPSIZE_START"> Omit characters at the start of the text + line="100">Omit characters at the start of the text glib:name="PANGO_ELLIPSIZE_MIDDLE"> Omit characters in the middle of the text + line="101">Omit characters in the middle of the text glib:name="PANGO_ELLIPSIZE_END"> Omit characters at the end of the text + line="102">Omit characters at the end of the text - + @@ -4035,7 +4047,7 @@ with an ellipsis. - + @@ -4044,7 +4056,7 @@ with an ellipsis. - + @@ -4053,7 +4065,7 @@ with an ellipsis. - + @@ -4062,7 +4074,7 @@ with an ellipsis. - + @@ -4071,7 +4083,7 @@ with an ellipsis. - + @@ -4080,7 +4092,7 @@ with an ellipsis. - + @@ -4089,7 +4101,7 @@ with an ellipsis. - + @@ -4098,7 +4110,7 @@ with an ellipsis. - + @@ -4141,15 +4153,15 @@ with an ellipsis. glib:type-struct="FontClass"> A `PangoFont` is used to represent a font in a + line="579">A `PangoFont` is used to represent a font in a rendering-system-independent manner. - + Frees an array of font descriptions. - + line="1120">Frees an array of font descriptions. + @@ -4160,7 +4172,7 @@ rendering-system-independent manner. allow-none="1"> a pointer + line="1122">a pointer to an array of `PangoFontDescription`, may be %NULL number of font descriptions in @descs + line="1124">number of font descriptions in @descs @@ -4182,37 +4194,37 @@ rendering-system-independent manner. throws="1"> Loads data previously created via [method@Pango.Font.serialize]. + line="1768">Loads data previously created via [method@Pango.Font.serialize]. For a discussion of the supported format, see that function. Note: to verify that the returned font is identical to the one that was serialized, you can compare @bytes to the result of serializing the font again. - + a new `PangoFont` + line="1782">a new `PangoFont` a `PangoContext` + line="1770">a `PangoContext` the bytes containing the data + line="1771">the bytes containing the data - + @@ -4225,28 +4237,28 @@ result of serializing the font again. Returns a description of the font, with font size set in points. + line="2034">Returns a description of the font, with font size set in points. Use [method@Pango.Font.describe_with_absolute_size] if you want the font size in device units. - + a newly-allocated `PangoFontDescription` object. + line="2043">a newly-allocated `PangoFontDescription` object. a `PangoFont` + line="2036">a `PangoFont` - + @@ -4259,12 +4271,12 @@ the font size in device units. Computes the coverage map for a given font and language tag. - + line="2080">Computes the coverage map for a given font and language tag. + a newly-allocated `PangoCoverage` + line="2087">a newly-allocated `PangoCoverage` object. @@ -4272,13 +4284,13 @@ the font size in device units. a `PangoFont` + line="2082">a `PangoFont` the language tag + line="2083">the language tag @@ -4288,14 +4300,14 @@ the font size in device units. version="1.44"> Obtain the OpenType features that are provided by the font. + line="3058">Obtain the OpenType features that are provided by the font. These are passed to the rendering system, together with features that have been explicitly set via attributes. Note that this does not include OpenType features which the rendering system enables by default. - + @@ -4303,7 +4315,7 @@ rendering system enables by default. a `PangoFont` + line="3060">a `PangoFont` transfer-ownership="none"> Array to features in + line="3061">Array to features in @@ -4320,7 +4332,7 @@ rendering system enables by default. the length of @features + line="3062">the length of @features transfer-ownership="full"> the number of used items in @features + line="3063">the number of used items in @features @@ -4339,7 +4351,7 @@ rendering system enables by default. version="1.10"> Gets the font map for which the font was created. + line="2209">Gets the font map for which the font was created. Note that the font maintains a *weak* reference to the font map, so if all references to font map are @@ -4350,11 +4362,11 @@ In that case this function will return %NULL. It is the responsibility of the user to ensure that the font map is kept alive. In most uses this is not an issue as a `PangoContext` holds a reference to the font map. - + the `PangoFontMap` + line="2225">the `PangoFontMap` for the font @@ -4365,7 +4377,7 @@ as a `PangoContext` holds a reference to the font map. allow-none="1"> a `PangoFont` + line="2211">a `PangoFont` @@ -4373,7 +4385,7 @@ as a `PangoContext` holds a reference to the font map. Gets the logical and ink extents of a glyph within a font. + line="2119">Gets the logical and ink extents of a glyph within a font. The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing @@ -4384,7 +4396,7 @@ of the rectangles are in 1/PANGO_SCALE of a device unit. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. - + @@ -4395,13 +4407,13 @@ output variables and returns. allow-none="1"> a `PangoFont` + line="2121">a `PangoFont` the glyph index + line="2122">the glyph index allow-none="1"> rectangle used to store the extents of the glyph as drawn + line="2123">rectangle used to store the extents of the glyph as drawn allow-none="1"> rectangle used to store the logical extents of the glyph + line="2124">rectangle used to store the logical extents of the glyph @@ -4431,7 +4443,7 @@ output variables and returns. Gets overall metric information for a font. + line="2166">Gets overall metric information for a font. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be @@ -4439,11 +4451,11 @@ retrieved that correspond to the script(s) used by that language. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. - + a `PangoFontMetrics` object. The caller must call + line="2182">a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. @@ -4454,7 +4466,7 @@ output variables and returns. allow-none="1"> a `PangoFont` + line="2168">a `PangoFont` allow-none="1"> language tag used to determine which script + line="2169">language tag used to determine which script to get the metrics for, or %NULL to indicate to get the metrics for the entire font. @@ -4473,22 +4485,22 @@ output variables and returns. Returns a description of the font, with font size set in points. + line="2034">Returns a description of the font, with font size set in points. Use [method@Pango.Font.describe_with_absolute_size] if you want the font size in device units. - + a newly-allocated `PangoFontDescription` object. + line="2043">a newly-allocated `PangoFontDescription` object. a `PangoFont` + line="2036">a `PangoFont` @@ -4498,22 +4510,22 @@ the font size in device units. version="1.14"> Returns a description of the font, with absolute font size set + line="2053">Returns a description of the font, with absolute font size set in device units. Use [method@Pango.Font.describe] if you want the font size in points. - + a newly-allocated `PangoFontDescription` object. + line="2062">a newly-allocated `PangoFontDescription` object. a `PangoFont` + line="2055">a `PangoFont` @@ -4521,12 +4533,12 @@ Use [method@Pango.Font.describe] if you want the font size in points. Computes the coverage map for a given font and language tag. - + line="2080">Computes the coverage map for a given font and language tag. + a newly-allocated `PangoCoverage` + line="2087">a newly-allocated `PangoCoverage` object. @@ -4534,13 +4546,13 @@ Use [method@Pango.Font.describe] if you want the font size in points. a `PangoFont` + line="2082">a `PangoFont` the language tag + line="2083">the language tag @@ -4550,19 +4562,19 @@ Use [method@Pango.Font.describe] if you want the font size in points. version="1.46"> Gets the `PangoFontFace` to which @font belongs. - + line="2242">Gets the `PangoFontFace` to which @font belongs. + the `PangoFontFace` + line="2248">the `PangoFontFace` a `PangoFont` + line="2244">a `PangoFont` @@ -4572,14 +4584,14 @@ Use [method@Pango.Font.describe] if you want the font size in points. version="1.44"> Obtain the OpenType features that are provided by the font. + line="3058">Obtain the OpenType features that are provided by the font. These are passed to the rendering system, together with features that have been explicitly set via attributes. Note that this does not include OpenType features which the rendering system enables by default. - + @@ -4587,7 +4599,7 @@ rendering system enables by default. a `PangoFont` + line="3060">a `PangoFont` transfer-ownership="none"> Array to features in + line="3061">Array to features in @@ -4604,7 +4616,7 @@ rendering system enables by default. the length of @features + line="3062">the length of @features transfer-ownership="full"> the number of used items in @features + line="3063">the number of used items in @features @@ -4623,7 +4635,7 @@ rendering system enables by default. version="1.10"> Gets the font map for which the font was created. + line="2209">Gets the font map for which the font was created. Note that the font maintains a *weak* reference to the font map, so if all references to font map are @@ -4634,11 +4646,11 @@ In that case this function will return %NULL. It is the responsibility of the user to ensure that the font map is kept alive. In most uses this is not an issue as a `PangoContext` holds a reference to the font map. - + the `PangoFontMap` + line="2225">the `PangoFontMap` for the font @@ -4649,7 +4661,7 @@ as a `PangoContext` holds a reference to the font map. allow-none="1"> a `PangoFont` + line="2211">a `PangoFont` @@ -4658,7 +4670,7 @@ as a `PangoContext` holds a reference to the font map. c:identifier="pango_font_get_glyph_extents"> Gets the logical and ink extents of a glyph within a font. + line="2119">Gets the logical and ink extents of a glyph within a font. The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing @@ -4669,7 +4681,7 @@ of the rectangles are in 1/PANGO_SCALE of a device unit. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. - + @@ -4680,13 +4692,13 @@ output variables and returns. allow-none="1"> a `PangoFont` + line="2121">a `PangoFont` the glyph index + line="2122">the glyph index allow-none="1"> rectangle used to store the extents of the glyph as drawn + line="2123">rectangle used to store the extents of the glyph as drawn allow-none="1"> rectangle used to store the logical extents of the glyph + line="2124">rectangle used to store the logical extents of the glyph @@ -4719,16 +4731,16 @@ output variables and returns. introspectable="0"> Get a `hb_font_t` object backing this font. + line="2260">Get a `hb_font_t` object backing this font. Note that the objects returned by this function are cached and immutable. If you need to make changes to the `hb_font_t`, use [hb_font_create_sub_font()](https://harfbuzz.github.io/harfbuzz-hb-font.html#hb-font-create-sub-font). - + the `hb_font_t` object + line="2270">the `hb_font_t` object backing the font @@ -4736,7 +4748,7 @@ use [hb_font_create_sub_font()](https://harfbuzz.github.io/harfbuzz-hb-font.html a `PangoFont` + line="2262">a `PangoFont` @@ -4746,7 +4758,7 @@ use [hb_font_create_sub_font()](https://harfbuzz.github.io/harfbuzz-hb-font.html version="1.50"> Returns the languages that are supported by @font. + line="3085">Returns the languages that are supported by @font. If the font backend does not provide this information, %NULL is returned. For the fontconfig backend, this @@ -4754,11 +4766,11 @@ corresponds to the FC_LANG member of the FcPattern. The returned array is only valid as long as the font and its fontmap are valid. - + an array of `PangoLanguage` + line="3098">an array of `PangoLanguage` @@ -4767,7 +4779,7 @@ and its fontmap are valid. a `PangoFont` + line="3087">a `PangoFont` @@ -4775,7 +4787,7 @@ and its fontmap are valid. Gets overall metric information for a font. + line="2166">Gets overall metric information for a font. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be @@ -4783,11 +4795,11 @@ retrieved that correspond to the script(s) used by that language. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. - + a `PangoFontMetrics` object. The caller must call + line="2182">a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. @@ -4798,7 +4810,7 @@ output variables and returns. allow-none="1"> a `PangoFont` + line="2168">a `PangoFont` allow-none="1"> language tag used to determine which script + line="2169">language tag used to determine which script to get the metrics for, or %NULL to indicate to get the metrics for the entire font. @@ -4819,25 +4831,25 @@ output variables and returns. version="1.44"> Returns whether the font provides a glyph for this character. - + line="3038">Returns whether the font provides a glyph for this character. + `TRUE` if @font can render @wc + line="3045">`TRUE` if @font can render @wc a `PangoFont` + line="3040">a `PangoFont` a Unicode character + line="3041">a Unicode character @@ -4847,7 +4859,7 @@ output variables and returns. version="1.50"> Serializes the @font in a way that can be uniquely identified. + line="1727">Serializes the @font in a way that can be uniquely identified. There are no guarantees about the format of the output across different versions of Pango. @@ -4856,18 +4868,18 @@ The intended use of this function is testing, benchmarking and debugging. The format is not meant as a permanent storage format. To recreate a font from its serialized form, use [func@Pango.Font.deserialize]. - + a `GBytes` containing the serialized form of @font + line="1741">a `GBytes` containing the serialized form of @font a `PangoFont` + line="1729">a `PangoFont` @@ -4879,24 +4891,24 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + - + a newly-allocated `PangoFontDescription` object. + line="2043">a newly-allocated `PangoFontDescription` object. a `PangoFont` + line="2036">a `PangoFont` @@ -4904,11 +4916,11 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + a newly-allocated `PangoCoverage` + line="2087">a newly-allocated `PangoCoverage` object. @@ -4916,13 +4928,13 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< a `PangoFont` + line="2082">a `PangoFont` the language tag + line="2083">the language tag @@ -4930,7 +4942,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + @@ -4941,13 +4953,13 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< allow-none="1"> a `PangoFont` + line="2121">a `PangoFont` the glyph index + line="2122">the glyph index rectangle used to store the extents of the glyph as drawn + line="2123">rectangle used to store the extents of the glyph as drawn rectangle used to store the logical extents of the glyph + line="2124">rectangle used to store the logical extents of the glyph @@ -4977,11 +4989,11 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + a `PangoFontMetrics` object. The caller must call + line="2182">a `PangoFontMetrics` object. The caller must call [method@Pango.FontMetrics.unref] when finished using the object. @@ -4992,7 +5004,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< allow-none="1"> a `PangoFont` + line="2168">a `PangoFont` language tag used to determine which script + line="2169">language tag used to determine which script to get the metrics for, or %NULL to indicate to get the metrics for the entire font. @@ -5011,11 +5023,11 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + the `PangoFontMap` + line="2225">the `PangoFontMap` for the font @@ -5026,7 +5038,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< allow-none="1"> a `PangoFont` + line="2211">a `PangoFont` @@ -5034,7 +5046,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + @@ -5047,7 +5059,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + @@ -5055,7 +5067,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< a `PangoFont` + line="3060">a `PangoFont` Array to features in + line="3061">Array to features in @@ -5072,7 +5084,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< the length of @features + line="3062">the length of @features the number of used items in @features + line="3063">the number of used items in @features @@ -5089,7 +5101,7 @@ To recreate a font from its serialized form, use [func@Pango.Font.deserialize].< - + @@ -5119,12 +5131,12 @@ a font to load. Creates a new font description structure with all fields unset. - + line="81">Creates a new font description structure with all fields unset. + the newly allocated `PangoFontDescription`, + line="86">the newly allocated `PangoFontDescription`, which should be freed using [method@Pango.FontDescription.free]. @@ -5133,7 +5145,7 @@ a font to load. c:identifier="pango_font_description_better_match"> Determines if the style attributes of @new_match are a closer match + line="889">Determines if the style attributes of @new_match are a closer match for @desc than those of @old_match are, or if @old_match is %NULL, determines if @new_match is a match at all. @@ -5144,18 +5156,18 @@ and size-related attributes. Approximate matching for style considers a match as when the styles are equal. Note that @old_match must match @desc. - + %TRUE if @new_match is a better match + line="907">%TRUE if @new_match is a better match a `PangoFontDescription` + line="891">a `PangoFontDescription` allow-none="1"> a `PangoFontDescription`, or %NULL + line="892">a `PangoFontDescription`, or %NULL a `PangoFontDescription` + line="893">a `PangoFontDescription` @@ -5178,12 +5190,12 @@ Note that @old_match must match @desc. Make a copy of a `PangoFontDescription`. - + line="931">Make a copy of a `PangoFontDescription`. + the newly allocated `PangoFontDescription`, + line="937">the newly allocated `PangoFontDescription`, which should be freed with [method@Pango.FontDescription.free], or %NULL if @desc was %NULL. @@ -5195,7 +5207,7 @@ Note that @old_match must match @desc. allow-none="1"> a `PangoFontDescription`, may be %NULL + line="933">a `PangoFontDescription`, may be %NULL @@ -5204,18 +5216,18 @@ Note that @old_match must match @desc. c:identifier="pango_font_description_copy_static"> Make a copy of a `PangoFontDescription`, but don't duplicate + line="968">Make a copy of a `PangoFontDescription`, but don't duplicate allocated fields. This is like [method@Pango.FontDescription.copy], but only a shallow copy is made of the family name and other allocated fields. The result can only be used until @desc is modified or freed. This is meant to be used when the copy is only needed temporarily. - + the newly allocated `PangoFontDescription`, + line="980">the newly allocated `PangoFontDescription`, which should be freed with [method@Pango.FontDescription.free], or %NULL if @desc was %NULL. @@ -5227,7 +5239,7 @@ to be used when the copy is only needed temporarily. allow-none="1"> a `PangoFontDescription`, may be %NULL + line="970">a `PangoFontDescription`, may be %NULL @@ -5235,17 +5247,17 @@ to be used when the copy is only needed temporarily. Compares two font descriptions for equality. + line="1008">Compares two font descriptions for equality. Two font descriptions are considered equal if the fonts they describe are provably identical. This means that their masks do not have to match, as long as other fields are all the same. (Two font descriptions may result in identical fonts being loaded, but still compare %FALSE.) - + %TRUE if the two font descriptions are identical, + line="1020">%TRUE if the two font descriptions are identical, %FALSE otherwise. @@ -5253,13 +5265,13 @@ result in identical fonts being loaded, but still compare %FALSE.) a `PangoFontDescription` + line="1010">a `PangoFontDescription` another `PangoFontDescription` + line="1011">another `PangoFontDescription` @@ -5267,8 +5279,8 @@ result in identical fonts being loaded, but still compare %FALSE.) Frees a font description. - + line="1096">Frees a font description. + @@ -5279,7 +5291,7 @@ result in identical fonts being loaded, but still compare %FALSE.) allow-none="1"> a `PangoFontDescription`, may be %NULL + line="1098">a `PangoFontDescription`, may be %NULL @@ -5288,14 +5300,14 @@ result in identical fonts being loaded, but still compare %FALSE.) c:identifier="pango_font_description_get_family"> Gets the family name field of a font description. + line="162">Gets the family name field of a font description. See [method@Pango.FontDescription.set_family]. - + the family name field for the + line="170">the family name field for the font description, or %NULL if not previously set. This has the same life-time as the font description itself and should not be freed. @@ -5304,7 +5316,33 @@ See [method@Pango.FontDescription.set_family]. a `PangoFontDescription`. + line="164">a `PangoFontDescription`. + + + + + + Gets the features field of a font description. + +See [method@Pango.FontDescription.set_features]. + + + the features field for the font + description, or %NULL if not previously set. This has the same + life-time as the font description itself and should not be freed. + + + + + a `PangoFontDescription` @@ -5314,14 +5352,14 @@ See [method@Pango.FontDescription.set_family]. version="1.16"> Gets the gravity field of a font description. + line="487">Gets the gravity field of a font description. See [method@Pango.FontDescription.set_gravity]. - + the gravity field for the font description. + line="495">the gravity field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. @@ -5330,7 +5368,7 @@ See [method@Pango.FontDescription.set_gravity]. a `PangoFontDescription` + line="489">a `PangoFontDescription` @@ -5339,12 +5377,12 @@ See [method@Pango.FontDescription.set_gravity]. c:identifier="pango_font_description_get_set_fields"> Determines which fields in a font description have been set. - + line="715">Determines which fields in a font description have been set. + a bitmask with bits set corresponding to the + line="721">a bitmask with bits set corresponding to the fields in @desc that have been set. @@ -5352,7 +5390,7 @@ See [method@Pango.FontDescription.set_gravity]. a `PangoFontDescription` + line="717">a `PangoFontDescription` @@ -5360,14 +5398,14 @@ See [method@Pango.FontDescription.set_gravity]. Gets the size field of a font description. + line="379">Gets the size field of a font description. See [method@Pango.FontDescription.set_size]. - + the size field for the font description in points + line="387">the size field for the font description in points or device units. You must call [method@Pango.FontDescription.get_size_is_absolute] to find out which is the case. Returns 0 if the size field has not previously @@ -5380,7 +5418,7 @@ See [method@Pango.FontDescription.set_size]. a `PangoFontDescription` + line="381">a `PangoFontDescription` @@ -5390,16 +5428,16 @@ See [method@Pango.FontDescription.set_size]. version="1.8"> Determines whether the size of the font is in points (not absolute) + line="429">Determines whether the size of the font is in points (not absolute) or device units (absolute). See [method@Pango.FontDescription.set_size] and [method@Pango.FontDescription.set_absolute_size]. - + whether the size for the font description is in + line="439">whether the size for the font description is in points or device units. Use [method@Pango.FontDescription.get_set_fields] to find out if the size field of the font description was explicitly set or not. @@ -5409,7 +5447,7 @@ and [method@Pango.FontDescription.set_absolute_size]. a `PangoFontDescription` + line="431">a `PangoFontDescription` @@ -5418,14 +5456,14 @@ and [method@Pango.FontDescription.set_absolute_size]. c:identifier="pango_font_description_get_stretch"> Gets the stretch field of a font description. + line="330">Gets the stretch field of a font description. See [method@Pango.FontDescription.set_stretch]. - + the stretch field for the font description. + line="338">the stretch field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. @@ -5434,7 +5472,7 @@ See [method@Pango.FontDescription.set_stretch]. a `PangoFontDescription`. + line="332">a `PangoFontDescription`. @@ -5442,14 +5480,14 @@ See [method@Pango.FontDescription.set_stretch]. Gets the style field of a `PangoFontDescription`. + line="208">Gets the style field of a `PangoFontDescription`. See [method@Pango.FontDescription.set_style]. - + the style field for the font description. + line="216">the style field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. @@ -5458,7 +5496,7 @@ See [method@Pango.FontDescription.set_style]. a `PangoFontDescription` + line="210">a `PangoFontDescription` @@ -5467,14 +5505,14 @@ See [method@Pango.FontDescription.set_style]. c:identifier="pango_font_description_get_variant"> Gets the variant field of a `PangoFontDescription`. + line="248">Gets the variant field of a `PangoFontDescription`. See [method@Pango.FontDescription.set_variant]. - + the variant field for the font description. + line="256">the variant field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. @@ -5483,7 +5521,7 @@ See [method@Pango.FontDescription.set_variant]. a `PangoFontDescription`. + line="250">a `PangoFontDescription`. @@ -5493,14 +5531,14 @@ See [method@Pango.FontDescription.set_variant]. version="1.42"> Gets the variations field of a font description. + line="586">Gets the variations field of a font description. See [method@Pango.FontDescription.set_variations]. - + the variations field for the font + line="594">the variations field for the font description, or %NULL if not previously set. This has the same life-time as the font description itself and should not be freed. @@ -5509,7 +5547,7 @@ See [method@Pango.FontDescription.set_variations]. a `PangoFontDescription` + line="588">a `PangoFontDescription` @@ -5518,14 +5556,14 @@ See [method@Pango.FontDescription.set_variations]. c:identifier="pango_font_description_get_weight"> Gets the weight field of a font description. + line="290">Gets the weight field of a font description. See [method@Pango.FontDescription.set_weight]. - + the weight field for the font description. + line="298">the weight field for the font description. Use [method@Pango.FontDescription.get_set_fields] to find out if the field was explicitly set or not. @@ -5534,7 +5572,7 @@ See [method@Pango.FontDescription.set_weight]. a `PangoFontDescription` + line="292">a `PangoFontDescription` @@ -5542,22 +5580,22 @@ See [method@Pango.FontDescription.set_weight]. Computes a hash of a `PangoFontDescription` structure. + line="1061">Computes a hash of a `PangoFontDescription` structure. This is suitable to be used, for example, as an argument to g_hash_table_new(). The hash value is independent of @desc->mask. - + the hash value. + line="1070">the hash value. a `PangoFontDescription` + line="1063">a `PangoFontDescription` @@ -5565,7 +5603,7 @@ to g_hash_table_new(). The hash value is independent of @desc->mask. Merges the fields that are set in @desc_to_merge into the fields in + line="757">Merges the fields that are set in @desc_to_merge into the fields in @desc. If @replace_existing is %FALSE, only fields in @desc that @@ -5573,7 +5611,7 @@ are not already set are affected. If %TRUE, then fields that are already set will be replaced as well. If @desc_to_merge is %NULL, this function performs nothing. - + @@ -5581,7 +5619,7 @@ If @desc_to_merge is %NULL, this function performs nothing. a `PangoFontDescription` + line="759">a `PangoFontDescription` allow-none="1"> the `PangoFontDescription` to merge from, + line="760">the `PangoFontDescription` to merge from, or %NULL if %TRUE, replace fields in @desc with the + line="762">if %TRUE, replace fields in @desc with the corresponding values from @desc_to_merge, even if they are already exist. @@ -5608,14 +5646,14 @@ If @desc_to_merge is %NULL, this function performs nothing. c:identifier="pango_font_description_merge_static"> Merges the fields that are set in @desc_to_merge into the fields in + line="814">Merges the fields that are set in @desc_to_merge into the fields in @desc, without copying allocated fields. This is like [method@Pango.FontDescription.merge], but only a shallow copy is made of the family name and other allocated fields. @desc can only be used until @desc_to_merge is modified or freed. This is meant to be used when the merged font description is only needed temporarily. - + @@ -5623,19 +5661,19 @@ be used when the merged font description is only needed temporarily. a `PangoFontDescription` + line="816">a `PangoFontDescription` the `PangoFontDescription` to merge from + line="817">the `PangoFontDescription` to merge from if %TRUE, replace fields in @desc with the + line="818">if %TRUE, replace fields in @desc with the corresponding values from @desc_to_merge, even if they are already exist. @@ -5647,11 +5685,11 @@ be used when the merged font description is only needed temporarily. version="1.8"> Sets the size field of a font description, in device units. + line="403">Sets the size field of a font description, in device units. This is mutually exclusive with [method@Pango.FontDescription.set_size] which sets the font size in points. - + @@ -5659,13 +5697,13 @@ which sets the font size in points. a `PangoFontDescription` + line="405">a `PangoFontDescription` the new size, in Pango units. There are %PANGO_SCALE Pango units + line="406">the new size, in Pango units. There are %PANGO_SCALE Pango units in one device unit. For an output backend where a device unit is a pixel, a @size value of 10 * PANGO_SCALE gives a 10 pixel font. @@ -5676,14 +5714,14 @@ which sets the font size in points. c:identifier="pango_font_description_set_family"> Sets the family name field of a font description. + line="99">Sets the family name field of a font description. The family name represents a family of related font styles, and will resolve to a particular `PangoFontFamily`. In some uses of `PangoFontDescription`, it is also possible to use a comma separated list of family names for this field. - + @@ -5691,13 +5729,13 @@ separated list of family names for this field. a `PangoFontDescription`. + line="101">a `PangoFontDescription`. a string representing the family name. + line="102">a string representing the family name. @@ -5706,14 +5744,14 @@ separated list of family names for this field. c:identifier="pango_font_description_set_family_static"> Sets the family name field of a font description, without copying the string. + line="123">Sets the family name field of a font description, without copying the string. This is like [method@Pango.FontDescription.set_family], except that no copy of @family is made. The caller must make sure that the string passed in stays around until @desc has been freed or the name is set again. This function can be used if @family is a static string such as a C string literal, or if @desc is only needed temporarily. - + @@ -5721,13 +5759,96 @@ string such as a C string literal, or if @desc is only needed temporarily. a `PangoFontDescription` + line="125">a `PangoFontDescription` a string representing the family name + line="126">a string representing the family name + + + + + + Sets the features field of a font description. + +OpenType font features allow to enable or disable certain optional +features of a font, such as tabular numbers. + +The format of the features string is comma-separated list of +feature assignments, with each assignment being one of these forms: + + FEATURE=n + +where FEATURE must be a 4 character tag that identifies and OpenType +feature, and n an integer (depending on the feature, the allowed +values may be 0, 1 or bigger numbers). Unknown features are ignored. + +Note that font features set in this way are enabled for the entire text +that is using the font, which is not appropriate for all OpenType features. +The intended use case is to select character variations (features cv01 - c99), +style sets (ss01 - ss20) and the like. + +Pango does not currently have a way to find supported OpenType features +of a font. Both harfbuzz and freetype have API for this. See for example +[hb_ot_layout_table_get_feature_tags](https://harfbuzz.github.io/harfbuzz-hb-ot-layout.html#hb-ot-layout-table-get-feature-tags). + +Features that are not supported by the font are silently ignored. + + + + + + + a `PangoFontDescription`. + + + + a string representing the features + + + + + + Sets the features field of a font description. + +This is like [method@Pango.FontDescription.set_features], except +that no copy of @featuresis made. The caller must make sure that +the string passed in stays around until @desc has been freed +or the name is set again. This function can be used if +@features is a static string such as a C string literal, +or if @desc is only needed temporarily. + + + + + + + a `PangoFontDescription` + + + + a string representing the features @@ -5737,7 +5858,7 @@ string such as a C string literal, or if @desc is only needed temporarily. version="1.16"> Sets the gravity field of a font description. + line="454">Sets the gravity field of a font description. The gravity field specifies how the glyphs should be rotated. If @gravity is @@ -5746,7 +5867,7 @@ the font description. This function is seldom useful to the user. Gravity should normally be set on a `PangoContext`. - + @@ -5754,13 +5875,13 @@ be set on a `PangoContext`. a `PangoFontDescription` + line="456">a `PangoFontDescription` the gravity for the font description. + line="457">the gravity for the font description. @@ -5768,11 +5889,11 @@ be set on a `PangoContext`. Sets the size field of a font description in fractional points. + line="350">Sets the size field of a font description in fractional points. This is mutually exclusive with [method@Pango.FontDescription.set_absolute_size]. - + @@ -5780,13 +5901,13 @@ This is mutually exclusive with a `PangoFontDescription` + line="352">a `PangoFontDescription` the size of the font in points, scaled by %PANGO_SCALE. + line="353">the size of the font in points, scaled by %PANGO_SCALE. (That is, a @size value of 10 * PANGO_SCALE is a 10 point font. The conversion factor between points and device units depends on system configuration and the output device. For screen display, a @@ -5802,11 +5923,11 @@ This is mutually exclusive with c:identifier="pango_font_description_set_stretch"> Sets the stretch field of a font description. + line="310">Sets the stretch field of a font description. The [enum@Pango.Stretch] field specifies how narrow or wide the font should be. - + @@ -5814,13 +5935,13 @@ wide the font should be. a `PangoFontDescription` + line="312">a `PangoFontDescription` the stretch for the font description + line="313">the stretch for the font description @@ -5828,7 +5949,7 @@ wide the font should be. Sets the style field of a `PangoFontDescription`. + line="182">Sets the style field of a `PangoFontDescription`. The [enum@Pango.Style] enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either @@ -5838,7 +5959,7 @@ Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found. - + @@ -5846,13 +5967,13 @@ match is not found. a `PangoFontDescription` + line="184">a `PangoFontDescription` the style for the font description + line="185">the style for the font description @@ -5861,11 +5982,11 @@ match is not found. c:identifier="pango_font_description_set_variant"> Sets the variant field of a font description. + line="228">Sets the variant field of a font description. The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL or %PANGO_VARIANT_SMALL_CAPS. - + @@ -5873,13 +5994,13 @@ or %PANGO_VARIANT_SMALL_CAPS. a `PangoFontDescription` + line="230">a `PangoFontDescription` the variant type for the font description. + line="231">the variant type for the font description. @@ -5889,7 +6010,7 @@ or %PANGO_VARIANT_SMALL_CAPS. version="1.42"> Sets the variations field of a font description. + line="551">Sets the variations field of a font description. OpenType font variations allow to select a font instance by specifying values for a number of axes, such as width or weight. @@ -5905,7 +6026,7 @@ and values are clamped to their allowed range. Pango does not currently have a way to find supported axes of a font. Both harfbuzz and freetype have API for this. See for example [hb_ot_var_get_axis_infos](https://harfbuzz.github.io/harfbuzz-hb-ot-var.html#hb-ot-var-get-axis-infos). - + @@ -5913,7 +6034,7 @@ for example [hb_ot_var_get_axis_infos](https://harfbuzz.github.io/harfbuzz-hb-ot a `PangoFontDescription`. + line="553">a `PangoFontDescription`. a string representing the variations + line="554">a string representing the variations @@ -5932,7 +6053,7 @@ for example [hb_ot_var_get_axis_infos](https://harfbuzz.github.io/harfbuzz-hb-ot version="1.42"> Sets the variations field of a font description. + line="509">Sets the variations field of a font description. This is like [method@Pango.FontDescription.set_variations], except that no copy of @variations is made. The caller must make sure that @@ -5940,7 +6061,7 @@ the string passed in stays around until @desc has been freed or the name is set again. This function can be used if @variations is a static string such as a C string literal, or if @desc is only needed temporarily. - + @@ -5948,13 +6069,13 @@ or if @desc is only needed temporarily. a `PangoFontDescription` + line="511">a `PangoFontDescription` a string representing the variations + line="512">a string representing the variations @@ -5963,13 +6084,13 @@ or if @desc is only needed temporarily. c:identifier="pango_font_description_set_weight"> Sets the weight field of a font description. + line="268">Sets the weight field of a font description. The weight field specifies how bold or light the font should be. In addition to the values of the [enum@Pango.Weight] enumeration, other intermediate numeric values are possible. - + @@ -5977,13 +6098,13 @@ intermediate numeric values are possible. a `PangoFontDescription` + line="270">a `PangoFontDescription` the weight for the font description. + line="271">the weight for the font description. @@ -5992,24 +6113,24 @@ intermediate numeric values are possible. c:identifier="pango_font_description_to_filename"> Creates a filename representation of a font description. + line="1739">Creates a filename representation of a font description. The filename is identical to the result from calling [method@Pango.FontDescription.to_string], but with underscores instead of characters that are untypical in filenames, and in lower case only. - + a new string that must be freed with g_free(). + line="1750">a new string that must be freed with g_free(). a `PangoFontDescription` + line="1741">a `PangoFontDescription` @@ -6017,24 +6138,24 @@ lower case only. Creates a string representation of a font description. + line="1646">Creates a string representation of a font description. See [func@Pango.FontDescription.from_string] for a description of the format of the string representation. The family list in the string description will only have a terminating comma if the last word of the list is a valid style option. - + a new string that must be freed with g_free(). + line="1657">a new string that must be freed with g_free(). a `PangoFontDescription` + line="1648">a `PangoFontDescription` @@ -6043,10 +6164,10 @@ the last word of the list is a valid style option. c:identifier="pango_font_description_unset_fields"> Unsets some of the fields in a `PangoFontDescription`. + line="732">Unsets some of the fields in a `PangoFontDescription`. The unset fields will get back to their default values. - + @@ -6054,13 +6175,13 @@ The unset fields will get back to their default values. a `PangoFontDescription` + line="734">a `PangoFontDescription` bitmask of fields in the @desc to unset. + line="735">bitmask of fields in the @desc to unset. @@ -6069,19 +6190,17 @@ The unset fields will get back to their default values. c:identifier="pango_font_description_from_string"> Creates a new font description from a string representation. + line="1401">Creates a new font description from a string representation. The string must have the form - "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", + [FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS] [FEATURES] where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. -VARIATIONS is a comma-separated list of font variation -specifications of the form "\@axis=value" (the = sign is optional). The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic". @@ -6104,6 +6223,12 @@ The following words are understood as gravity values: "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left", "East", "Rotated-Right", "West". +VARIATIONS is a comma-separated list of font variations +of the form @‍axis1=value,axis2=value,... + +FEATURES is a comma-separated list of font features of the form +\#‍feature1=value,feature2=value,... + Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to %NULL. If STYLE-OPTIONS is missing, then all style @@ -6112,19 +6237,19 @@ size in the resulting font description will be set to 0. A typical example: - "Cantarell Italic Light 15 \@wght=200" - + Cantarell Italic Light 15 @‍wght=200 #‍tnum=1 + a new `PangoFontDescription`. + line="1454">a new `PangoFontDescription`. string representation of a font description. + line="1403">string representation of a font description. @@ -6140,22 +6265,22 @@ A typical example: glib:type-struct="FontFaceClass"> A `PangoFontFace` is used to represent a group of fonts with + line="513">A `PangoFontFace` is used to represent a group of fonts with the same family, slant, weight, and width, but varying sizes. - + Returns a font description that matches the face. + line="2914">Returns a font description that matches the face. The resulting font description will have the family, style, variant, weight and stretch of the face, but its size field will be unset. - + a newly-created `PangoFontDescription` structure + line="2924">a newly-created `PangoFontDescription` structure holding the description of the face. Use [method@Pango.FontDescription.free] to free the result. @@ -6164,7 +6289,7 @@ will be unset. a `PangoFontFace` + line="2916">a `PangoFontFace` @@ -6172,16 +6297,16 @@ will be unset. Gets a name representing the style of this face. + line="2961">Gets a name representing the style of this face. Note that a font family may contain multiple faces with the same name (e.g. a variable and a non-variable face for the same style). - + the face name for the face. This string is + line="2971">the face name for the face. This string is owned by the face object and must not be modified or freed. @@ -6189,7 +6314,7 @@ face for the same style). a `PangoFontFace`. + line="2963">a `PangoFontFace`. @@ -6197,19 +6322,19 @@ face for the same style). Gets the `PangoFontFamily` that @face belongs to. - + line="3020">Gets the `PangoFontFamily` that @face belongs to. + the `PangoFontFamily` + line="3026">the `PangoFontFamily` a `PangoFontFace` + line="3022">a `PangoFontFace` @@ -6219,23 +6344,23 @@ face for the same style). version="1.18"> Returns whether a `PangoFontFace` is synthesized. + line="2936">Returns whether a `PangoFontFace` is synthesized. This will be the case if the underlying font rendering engine creates this face from another face, by shearing, emboldening, lightening or modifying it in some other way. - + whether @face is synthesized + line="2946">whether @face is synthesized a `PangoFontFace` + line="2938">a `PangoFontFace` @@ -6243,13 +6368,13 @@ lightening or modifying it in some other way. List the available sizes for a font. + line="2982">List the available sizes for a font. This is only applicable to bitmap fonts. For scalable fonts, stores %NULL at the location pointed to by @sizes and 0 at the location pointed to by @n_sizes. The sizes returned are in Pango units and are sorted in ascending order. - + @@ -6257,7 +6382,7 @@ in ascending order. a `PangoFontFace`. + line="2984">a `PangoFontFace`. allow-none="1"> + line="2985"> location to store a pointer to an array of int. This array should be freed with g_free(). @@ -6282,7 +6407,7 @@ in ascending order. transfer-ownership="full"> location to store the number of elements in @sizes + line="2988">location to store the number of elements in @sizes @@ -6290,16 +6415,16 @@ in ascending order. Returns a font description that matches the face. + line="2914">Returns a font description that matches the face. The resulting font description will have the family, style, variant, weight and stretch of the face, but its size field will be unset. - + a newly-created `PangoFontDescription` structure + line="2924">a newly-created `PangoFontDescription` structure holding the description of the face. Use [method@Pango.FontDescription.free] to free the result. @@ -6308,7 +6433,7 @@ will be unset. a `PangoFontFace` + line="2916">a `PangoFontFace` @@ -6317,16 +6442,16 @@ will be unset. c:identifier="pango_font_face_get_face_name"> Gets a name representing the style of this face. + line="2961">Gets a name representing the style of this face. Note that a font family may contain multiple faces with the same name (e.g. a variable and a non-variable face for the same style). - + the face name for the face. This string is + line="2971">the face name for the face. This string is owned by the face object and must not be modified or freed. @@ -6334,7 +6459,7 @@ face for the same style). a `PangoFontFace`. + line="2963">a `PangoFontFace`. @@ -6344,19 +6469,19 @@ face for the same style). version="1.46"> Gets the `PangoFontFamily` that @face belongs to. - + line="3020">Gets the `PangoFontFamily` that @face belongs to. + the `PangoFontFamily` + line="3026">the `PangoFontFamily` a `PangoFontFace` + line="3022">a `PangoFontFace` @@ -6366,23 +6491,23 @@ face for the same style). version="1.18"> Returns whether a `PangoFontFace` is synthesized. + line="2936">Returns whether a `PangoFontFace` is synthesized. This will be the case if the underlying font rendering engine creates this face from another face, by shearing, emboldening, lightening or modifying it in some other way. - + whether @face is synthesized + line="2946">whether @face is synthesized a `PangoFontFace` + line="2938">a `PangoFontFace` @@ -6392,13 +6517,13 @@ lightening or modifying it in some other way. version="1.4"> List the available sizes for a font. + line="2982">List the available sizes for a font. This is only applicable to bitmap fonts. For scalable fonts, stores %NULL at the location pointed to by @sizes and 0 at the location pointed to by @n_sizes. The sizes returned are in Pango units and are sorted in ascending order. - + @@ -6406,7 +6531,7 @@ in ascending order. a `PangoFontFace`. + line="2984">a `PangoFontFace`. allow-none="1"> + line="2985"> location to store a pointer to an array of int. This array should be freed with g_free(). @@ -6431,7 +6556,7 @@ in ascending order. transfer-ownership="full"> location to store the number of elements in @sizes + line="2988">location to store the number of elements in @sizes @@ -6443,17 +6568,17 @@ in ascending order. - + - + the face name for the face. This string is + line="2971">the face name for the face. This string is owned by the face object and must not be modified or freed. @@ -6461,7 +6586,7 @@ in ascending order. a `PangoFontFace`. + line="2963">a `PangoFontFace`. @@ -6469,11 +6594,11 @@ in ascending order. - + a newly-created `PangoFontDescription` structure + line="2924">a newly-created `PangoFontDescription` structure holding the description of the face. Use [method@Pango.FontDescription.free] to free the result. @@ -6482,7 +6607,7 @@ in ascending order. a `PangoFontFace` + line="2916">a `PangoFontFace` @@ -6490,7 +6615,7 @@ in ascending order. - + @@ -6498,7 +6623,7 @@ in ascending order. a `PangoFontFace`. + line="2984">a `PangoFontFace`. allow-none="1"> + line="2985"> location to store a pointer to an array of int. This array should be freed with g_free(). @@ -6523,7 +6648,7 @@ in ascending order. transfer-ownership="full"> location to store the number of elements in @sizes + line="2988">location to store the number of elements in @sizes @@ -6531,18 +6656,18 @@ in ascending order. - + whether @face is synthesized + line="2946">whether @face is synthesized a `PangoFontFace` + line="2938">a `PangoFontFace` @@ -6550,18 +6675,18 @@ in ascending order. - + the `PangoFontFamily` + line="3026">the `PangoFontFamily` a `PangoFontFace` + line="3022">a `PangoFontFace` @@ -6569,7 +6694,7 @@ in ascending order. - + @@ -6577,7 +6702,7 @@ in ascending order. - + @@ -6594,22 +6719,22 @@ in ascending order. glib:type-struct="FontFamilyClass"> A `PangoFontFamily` is used to represent a family of related + line="440">A `PangoFontFamily` is used to represent a family of related font faces. The font faces in a family share a common design, but differ in slant, weight, width or other aspects. - + Gets the `PangoFontFace` of @family with the given name. - + line="2822">Gets the `PangoFontFace` of @family with the given name. + the `PangoFontFace`, + line="2831">the `PangoFontFace`, or %NULL if no face with the given name exists. @@ -6617,7 +6742,7 @@ slant, weight, width or other aspects. a `PangoFontFamily` + line="2824">a `PangoFontFamily` allow-none="1"> the name of a face. If the name is %NULL, + line="2825">the name of a face. If the name is %NULL, the family's default face (fontconfig calls it "Regular") will be returned. @@ -6636,16 +6761,16 @@ slant, weight, width or other aspects. Gets the name of the family. + line="2738">Gets the name of the family. The name is unique among all fonts for the font backend and can be used in a `PangoFontDescription` to specify that a face from this family is desired. - + the name of the family. This string is owned + line="2748">the name of the family. This string is owned by the family object and must not be modified or freed. @@ -6653,7 +6778,7 @@ this family is desired. a `PangoFontFamily` + line="2740">a `PangoFontFamily` @@ -6661,7 +6786,7 @@ this family is desired. A monospace font is a font designed for text display where the the + line="2845">A monospace font is a font designed for text display where the the characters form a regular grid. For Western languages this would @@ -6675,18 +6800,18 @@ The best way to find out the grid-cell size is to call [method@Pango.FontMetrics.get_approximate_digit_width], since the results of [method@Pango.FontMetrics.get_approximate_char_width] may be affected by double-width characters. - + %TRUE if the family is monospace. + line="2864">%TRUE if the family is monospace. a `PangoFontFamily` + line="2847">a `PangoFontFamily` @@ -6694,23 +6819,23 @@ be affected by double-width characters. A variable font is a font which has axes that can be modified to + line="2876">A variable font is a font which has axes that can be modified to produce different faces. Such axes are also known as _variations_; see [method@Pango.FontDescription.set_variations] for more information. - + %TRUE if the family is variable + line="2886">%TRUE if the family is variable a `PangoFontFamily` + line="2878">a `PangoFontFamily` @@ -6718,7 +6843,7 @@ Such axes are also known as _variations_; see Lists the different font faces that make up @family. + line="2759">Lists the different font faces that make up @family. The faces in a family share a common design, but differ in slant, weight, width and other aspects. @@ -6728,7 +6853,7 @@ multiple faces may have the same name or characteristics. `PangoFontFamily` also implemented the [iface@Gio.ListModel] interface for enumerating faces. - + @@ -6736,7 +6861,7 @@ for enumerating faces. a `PangoFontFamily` + line="2761">a `PangoFontFamily` allow-none="1"> + line="2762"> location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. @@ -6761,7 +6886,7 @@ for enumerating faces. transfer-ownership="full"> location to store number of elements in @faces. + line="2766">location to store number of elements in @faces. @@ -6771,12 +6896,12 @@ for enumerating faces. version="1.46"> Gets the `PangoFontFace` of @family with the given name. - + line="2822">Gets the `PangoFontFace` of @family with the given name. + the `PangoFontFace`, + line="2831">the `PangoFontFace`, or %NULL if no face with the given name exists. @@ -6784,7 +6909,7 @@ for enumerating faces. a `PangoFontFamily` + line="2824">a `PangoFontFamily` allow-none="1"> the name of a face. If the name is %NULL, + line="2825">the name of a face. If the name is %NULL, the family's default face (fontconfig calls it "Regular") will be returned. - + Gets the name of the family. + line="2738">Gets the name of the family. The name is unique among all fonts for the font backend and can be used in a `PangoFontDescription` to specify that a face from this family is desired. - + the name of the family. This string is owned + line="2748">the name of the family. This string is owned by the family object and must not be modified or freed. @@ -6820,17 +6947,18 @@ this family is desired. a `PangoFontFamily` + line="2740">a `PangoFontFamily` A monospace font is a font designed for text display where the the + line="2845">A monospace font is a font designed for text display where the the characters form a regular grid. For Western languages this would @@ -6844,44 +6972,45 @@ The best way to find out the grid-cell size is to call [method@Pango.FontMetrics.get_approximate_digit_width], since the results of [method@Pango.FontMetrics.get_approximate_char_width] may be affected by double-width characters. - + %TRUE if the family is monospace. + line="2864">%TRUE if the family is monospace. a `PangoFontFamily` + line="2847">a `PangoFontFamily` A variable font is a font which has axes that can be modified to + line="2876">A variable font is a font which has axes that can be modified to produce different faces. Such axes are also known as _variations_; see [method@Pango.FontDescription.set_variations] for more information. - + %TRUE if the family is variable + line="2886">%TRUE if the family is variable a `PangoFontFamily` + line="2878">a `PangoFontFamily` @@ -6889,7 +7018,7 @@ Such axes are also known as _variations_; see Lists the different font faces that make up @family. + line="2759">Lists the different font faces that make up @family. The faces in a family share a common design, but differ in slant, weight, width and other aspects. @@ -6899,7 +7028,7 @@ multiple faces may have the same name or characteristics. `PangoFontFamily` also implemented the [iface@Gio.ListModel] interface for enumerating faces. - + @@ -6907,7 +7036,7 @@ for enumerating faces. a `PangoFontFamily` + line="2761">a `PangoFontFamily` allow-none="1"> + line="2762"> location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. @@ -6932,23 +7061,59 @@ for enumerating faces. transfer-ownership="full"> location to store number of elements in @faces. + line="2766">location to store number of elements in @faces. + + + Is this a monospace font + + + + + Is this a variable font + + The type of items contained in this list. + line="2710">The type of items contained in this list. The number of items contained in this list. + line="2719">The number of items contained in this list. + + + The name of the family + + @@ -6956,13 +7121,13 @@ for enumerating faces. - + - + @@ -6970,7 +7135,7 @@ for enumerating faces. a `PangoFontFamily` + line="2761">a `PangoFontFamily` allow-none="1"> + line="2762"> location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. @@ -6995,7 +7160,7 @@ for enumerating faces. transfer-ownership="full"> location to store number of elements in @faces. + line="2766">location to store number of elements in @faces. @@ -7003,11 +7168,11 @@ for enumerating faces. - + the name of the family. This string is owned + line="2748">the name of the family. This string is owned by the family object and must not be modified or freed. @@ -7015,7 +7180,7 @@ for enumerating faces. a `PangoFontFamily` + line="2740">a `PangoFontFamily` @@ -7023,18 +7188,18 @@ for enumerating faces. - + %TRUE if the family is monospace. + line="2864">%TRUE if the family is monospace. a `PangoFontFamily` + line="2847">a `PangoFontFamily` @@ -7042,18 +7207,18 @@ for enumerating faces. - + %TRUE if the family is variable + line="2886">%TRUE if the family is variable a `PangoFontFamily` + line="2878">a `PangoFontFamily` @@ -7061,11 +7226,11 @@ for enumerating faces. - + the `PangoFontFace`, + line="2831">the `PangoFontFace`, or %NULL if no face with the given name exists. @@ -7073,7 +7238,7 @@ for enumerating faces. a `PangoFontFamily` + line="2824">a `PangoFontFamily` allow-none="1"> the name of a face. If the name is %NULL, + line="2825">the name of a face. If the name is %NULL, the family's default face (fontconfig calls it "Regular") will be returned. @@ -7092,7 +7257,7 @@ for enumerating faces. - + @@ -7119,7 +7284,7 @@ particular rendering systems. Forces a change in the context, which will cause any `PangoContext` + line="437">Forces a change in the context, which will cause any `PangoContext` using this fontmap to change. This function is only useful when implementing a new backend @@ -7134,7 +7299,7 @@ context and such data is changed. a `PangoFontMap` + line="439">a `PangoFontMap` @@ -7156,25 +7321,25 @@ context and such data is changed. Gets a font family by name. + line="487">Gets a font family by name. the `PangoFontFamily` + line="494">the `PangoFontFamily` a `PangoFontMap` + line="489">a `PangoFontMap` a family name + line="490">a family name @@ -7182,7 +7347,7 @@ context and such data is changed. Returns the current serial number of @fontmap. + line="391">Returns the current serial number of @fontmap. The serial number is initialized to an small number larger than zero when a new fontmap is created and is increased whenever the fontmap @@ -7198,14 +7363,14 @@ like in `PangoContext`. The current serial number of @fontmap. + line="408">The current serial number of @fontmap. a `PangoFontMap` + line="393">a `PangoFontMap` @@ -7213,7 +7378,7 @@ like in `PangoContext`. List all families for a fontmap. + line="193">List all families for a fontmap. Note that the returned families are not in any particular order. @@ -7227,7 +7392,7 @@ for enumerating families. a `PangoFontMap` + line="195">a `PangoFontMap` transfer-ownership="container"> location to + line="196">location to store a pointer to an array of `PangoFontFamily` *. This array should be freed with g_free(). @@ -7249,7 +7414,7 @@ for enumerating families. transfer-ownership="full"> location to store the number of elements in @families + line="199">location to store the number of elements in @families @@ -7257,12 +7422,12 @@ for enumerating families. Load the font in the fontmap that is the closest match for @desc. + line="172">Load the font in the fontmap that is the closest match for @desc. the newly allocated `PangoFont` + line="180">the newly allocated `PangoFont` loaded, or %NULL if no font matched. @@ -7270,19 +7435,19 @@ for enumerating families. a `PangoFontMap` + line="174">a `PangoFontMap` the `PangoContext` the font will be used with + line="175">the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load + line="176">a `PangoFontDescription` describing the font to load @@ -7290,13 +7455,13 @@ for enumerating families. Load a set of fonts in the fontmap that can be used to render + line="222">Load a set of fonts in the fontmap that can be used to render a font matching @desc. the newly allocated + line="232">the newly allocated `PangoFontset` loaded, or %NULL if no font matched. @@ -7304,35 +7469,68 @@ a font matching @desc. a `PangoFontMap` + line="224">a `PangoFontMap` the `PangoContext` the font will be used with + line="225">the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load + line="226">a `PangoFontDescription` describing the font to load a `PangoLanguage` the fonts will be used for + line="227">a `PangoLanguage` the fonts will be used for + + Loads a font file with one or more fonts into the `PangoFontMap`. + +The added fonts will take precedence over preexisting +fonts with the same name. + + + True if the font file is successfully loaded + into the fontmap, false if an error occurred. + + + + + a `PangoFontMap` + + + + Path to the font file + + + + Forces a change in the context, which will cause any `PangoContext` + line="437">Forces a change in the context, which will cause any `PangoContext` using this fontmap to change. This function is only useful when implementing a new backend @@ -7347,7 +7545,7 @@ context and such data is changed. a `PangoFontMap` + line="439">a `PangoFontMap` @@ -7357,7 +7555,7 @@ context and such data is changed. version="1.22"> Creates a `PangoContext` connected to @fontmap. + line="140">Creates a `PangoContext` connected to @fontmap. This is equivalent to [ctor@Pango.Context.new] followed by [method@Pango.Context.set_font_map]. @@ -7370,7 +7568,7 @@ gtk_widget_get_pango_context(). Use those instead. the newly allocated `PangoContext`, + line="154">the newly allocated `PangoContext`, which should be freed with g_object_unref(). @@ -7378,7 +7576,7 @@ gtk_widget_get_pango_context(). Use those instead. a `PangoFontMap` + line="142">a `PangoFontMap` @@ -7388,25 +7586,25 @@ gtk_widget_get_pango_context(). Use those instead. version="1.46"> Gets a font family by name. + line="487">Gets a font family by name. the `PangoFontFamily` + line="494">the `PangoFontFamily` a `PangoFontMap` + line="489">a `PangoFontMap` a family name + line="490">a family name @@ -7416,7 +7614,7 @@ gtk_widget_get_pango_context(). Use those instead. version="1.32.4"> Returns the current serial number of @fontmap. + line="391">Returns the current serial number of @fontmap. The serial number is initialized to an small number larger than zero when a new fontmap is created and is increased whenever the fontmap @@ -7432,14 +7630,14 @@ like in `PangoContext`. The current serial number of @fontmap. + line="408">The current serial number of @fontmap. a `PangoFontMap` + line="393">a `PangoFontMap` @@ -7447,7 +7645,7 @@ like in `PangoContext`. List all families for a fontmap. + line="193">List all families for a fontmap. Note that the returned families are not in any particular order. @@ -7461,7 +7659,7 @@ for enumerating families. a `PangoFontMap` + line="195">a `PangoFontMap` transfer-ownership="container"> location to + line="196">location to store a pointer to an array of `PangoFontFamily` *. This array should be freed with g_free(). @@ -7483,7 +7681,7 @@ for enumerating families. transfer-ownership="full"> location to store the number of elements in @families + line="199">location to store the number of elements in @families @@ -7491,12 +7689,12 @@ for enumerating families. Load the font in the fontmap that is the closest match for @desc. + line="172">Load the font in the fontmap that is the closest match for @desc. the newly allocated `PangoFont` + line="180">the newly allocated `PangoFont` loaded, or %NULL if no font matched. @@ -7504,19 +7702,19 @@ for enumerating families. a `PangoFontMap` + line="174">a `PangoFontMap` the `PangoContext` the font will be used with + line="175">the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load + line="176">a `PangoFontDescription` describing the font to load @@ -7524,13 +7722,13 @@ for enumerating families. Load a set of fonts in the fontmap that can be used to render + line="222">Load a set of fonts in the fontmap that can be used to render a font matching @desc. the newly allocated + line="232">the newly allocated `PangoFontset` loaded, or %NULL if no font matched. @@ -7538,39 +7736,94 @@ a font matching @desc. a `PangoFontMap` + line="224">a `PangoFontMap` the `PangoContext` the font will be used with + line="225">the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load + line="226">a `PangoFontDescription` describing the font to load a `PangoLanguage` the fonts will be used for + line="227">a `PangoLanguage` the fonts will be used for + + Returns a new font that is like @font, except that its size +is multiplied by @scale, its backend-dependent configuration +(e.g. cairo font options) is replaced by the one in @context, +and its variations are replaced by @variations. + + + the modified font + + + + + a `PangoFontMap` + + + + a font in @fontmap + + + + the scale factor to apply + + + + a `PangoContext` + + + + font variations to use + + + + The type of items contained in this list. + line="114">The type of items contained in this list. The number of items contained in this list. + line="123">The number of items contained in this list. @@ -7592,12 +7845,16 @@ a particular `PangoFontMap` implementation. + a function to load a font with a given description. See +pango_font_map_load_font(). the newly allocated `PangoFont` + line="180">the newly allocated `PangoFont` loaded, or %NULL if no font matched. @@ -7605,19 +7862,19 @@ a particular `PangoFontMap` implementation. a `PangoFontMap` + line="174">a `PangoFontMap` the `PangoContext` the font will be used with + line="175">the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load + line="176">a `PangoFontDescription` describing the font to load @@ -7625,6 +7882,10 @@ a particular `PangoFontMap` implementation. + A function to list available font families. See +pango_font_map_list_families(). @@ -7634,7 +7895,7 @@ a particular `PangoFontMap` implementation. a `PangoFontMap` + line="195">a `PangoFontMap` transfer-ownership="container"> location to + line="196">location to store a pointer to an array of `PangoFontFamily` *. This array should be freed with g_free(). transfer-ownership="full"> location to store the number of elements in @families + line="199">location to store the number of elements in @families + a function to load a fontset with a given given description +suitable for a particular language. See pango_font_map_load_fontset(). the newly allocated + line="232">the newly allocated `PangoFontset` loaded, or %NULL if no font matched. @@ -7678,26 +7943,26 @@ a particular `PangoFontMap` implementation. a `PangoFontMap` + line="224">a `PangoFontMap` the `PangoContext` the font will be used with + line="225">the `PangoContext` the font will be used with a `PangoFontDescription` describing the font to load + line="226">a `PangoFontDescription` describing the font to load a `PangoLanguage` the fonts will be used for + line="227">a `PangoLanguage` the fonts will be used for @@ -7711,25 +7976,32 @@ can handle fonts of this fonts loaded with this fontmap. + a function to get the serial number of the fontmap. +See pango_font_map_get_serial(). The current serial number of @fontmap. + line="408">The current serial number of @fontmap. a `PangoFontMap` + line="393">a `PangoFontMap` + See pango_font_map_changed() @@ -7739,7 +8011,7 @@ can handle fonts of this fonts loaded with this fontmap. a `PangoFontMap` + line="439">a `PangoFontMap` @@ -7751,20 +8023,20 @@ can handle fonts of this fonts loaded with this fontmap. the `PangoFontFamily` + line="494">the `PangoFontFamily` a `PangoFontMap` + line="489">a `PangoFontMap` a family name + line="490">a family name @@ -7852,20 +8124,32 @@ can handle fonts of this fonts loaded with this fontmap. the font gravity is specified (Since: 1.16.) + line="184">The font gravity is specified. OpenType font variations are specified (Since: 1.42) + line="191">OpenType font variations are specified. + + + OpenType font features are specified. - + @@ -7924,23 +8208,23 @@ For an overview of the most important metrics, see: c:identifier="pango_font_metrics_get_approximate_char_width"> Gets the approximate character width for a font metrics structure. + line="2420">Gets the approximate character width for a font metrics structure. This is merely a representative value useful, for example, for determining the initial size for a window. Actual characters in text will be wider and narrower than this. - + the character width, in Pango units. + line="2430">the character width, in Pango units. a `PangoFontMetrics` structure + line="2422">a `PangoFontMetrics` structure @@ -7949,25 +8233,25 @@ text will be wider and narrower than this. c:identifier="pango_font_metrics_get_approximate_digit_width"> Gets the approximate digit width for a font metrics structure. + line="2440">Gets the approximate digit width for a font metrics structure. This is merely a representative value useful, for example, for determining the initial size for a window. Actual digits in text can be wider or narrower than this, though this value is generally somewhat more accurate than the result of pango_font_metrics_get_approximate_char_width() for digits. - + the digit width, in Pango units. + line="2452">the digit width, in Pango units. a `PangoFontMetrics` structure + line="2442">a `PangoFontMetrics` structure @@ -7975,24 +8259,24 @@ pango_font_metrics_get_approximate_char_width() for digits. Gets the ascent from a font metrics structure. + line="2355">Gets the ascent from a font metrics structure. The ascent is the distance from the baseline to the logical top of a line of text. (The logical top may be above or below the top of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.) - + the ascent, in Pango units. + line="2366">the ascent, in Pango units. a `PangoFontMetrics` structure + line="2357">a `PangoFontMetrics` structure @@ -8000,24 +8284,24 @@ figure where the ink will be.) Gets the descent from a font metrics structure. + line="2376">Gets the descent from a font metrics structure. The descent is the distance from the baseline to the logical bottom of a line of text. (The logical bottom may be above or below the bottom of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.) - + the descent, in Pango units. + line="2387">the descent, in Pango units. a `PangoFontMetrics` structure + line="2378">a `PangoFontMetrics` structure @@ -8027,24 +8311,24 @@ to figure where the ink will be.) version="1.44"> Gets the line height from a font metrics structure. + line="2397">Gets the line height from a font metrics structure. The line height is the recommended distance between successive baselines in wrapped text using this font. If the line height is not available, 0 is returned. - + the height, in Pango units + line="2408">the height, in Pango units a `PangoFontMetrics` structure + line="2399">a `PangoFontMetrics` structure @@ -8054,22 +8338,22 @@ If the line height is not available, 0 is returned. version="1.6"> Gets the suggested position to draw the strikethrough. + line="2502">Gets the suggested position to draw the strikethrough. The value returned is the distance *above* the baseline of the top of the strikethrough. - + the suggested strikethrough position, in Pango units. + line="2511">the suggested strikethrough position, in Pango units. a `PangoFontMetrics` structure + line="2504">a `PangoFontMetrics` structure @@ -8079,19 +8363,19 @@ baseline of the top of the strikethrough. version="1.6"> Gets the suggested thickness to draw for the strikethrough. - + line="2523">Gets the suggested thickness to draw for the strikethrough. + the suggested strikethrough thickness, in Pango units. + line="2529">the suggested strikethrough thickness, in Pango units. a `PangoFontMetrics` structure + line="2525">a `PangoFontMetrics` structure @@ -8101,23 +8385,23 @@ baseline of the top of the strikethrough. version="1.6"> Gets the suggested position to draw the underline. + line="2462">Gets the suggested position to draw the underline. The value returned is the distance *above* the baseline of the top of the underline. Since most fonts have underline positions beneath the baseline, this value is typically negative. - + the suggested underline position, in Pango units. + line="2472">the suggested underline position, in Pango units. a `PangoFontMetrics` structure + line="2464">a `PangoFontMetrics` structure @@ -8127,19 +8411,19 @@ the baseline, this value is typically negative. version="1.6"> Gets the suggested thickness to draw for the underline. - + line="2484">Gets the suggested thickness to draw for the underline. + the suggested underline thickness, in Pango units. + line="2490">the suggested underline thickness, in Pango units. a `PangoFontMetrics` structure + line="2486">a `PangoFontMetrics` structure @@ -8147,12 +8431,12 @@ the baseline, this value is typically negative. Increase the reference count of a font metrics structure by one. - + line="2316">Increase the reference count of a font metrics structure by one. + @metrics + line="2322">@metrics @@ -8162,7 +8446,7 @@ the baseline, this value is typically negative. allow-none="1"> a `PangoFontMetrics` structure, may be %NULL + line="2318">a `PangoFontMetrics` structure, may be %NULL @@ -8170,10 +8454,10 @@ the baseline, this value is typically negative. Decrease the reference count of a font metrics structure by one. + line="2335">Decrease the reference count of a font metrics structure by one. If the result is zero, frees the structure and any associated memory. - + @@ -8184,7 +8468,7 @@ If the result is zero, frees the structure and any associated memory. allow-none="1"> a `PangoFontMetrics` structure, may be %NULL + line="2337">a `PangoFontMetrics` structure, may be %NULL @@ -8319,6 +8603,9 @@ glyph for a Unicode character. + a function to get the language of the fontset. @@ -8455,6 +8742,10 @@ a particular `PangoFontset` implementation. + a function to get the font in the fontset that contains the + best glyph for the given Unicode character; see [method@Pango.Fontset.get_font] @@ -8480,6 +8771,10 @@ a particular `PangoFontset` implementation. + a function to get overall metric information for the fonts + in the fontset; see [method@Pango.Fontset.get_metrics] @@ -8499,6 +8794,9 @@ a particular `PangoFontset` implementation. + a function to get the language of the fontset. @@ -8512,6 +8810,10 @@ a particular `PangoFontset` implementation. + a function to loop over the fonts in the fontset. See + [method@Pango.Fontset.foreach] @@ -8712,26 +9014,26 @@ The fontset takes ownership of @font. introspectable="0"> The way this unknown glyphs are rendered is backend specific. For example, + line="699">The way this unknown glyphs are rendered is backend specific. For example, a box with the hexadecimal Unicode code-point of the character written in it is what is done in the most common backends. - + a Unicode character + line="701">a Unicode character A `PangoGlyph` value that indicates a zero-width empty glpyh. + line="669">A `PangoGlyph` value that indicates a zero-width empty glpyh. This is useful for example in shaper modules, to use as the glyph for various zero-width Unicode characters (those passing [func@is_zero_width]). - + A `PangoGlyph` value for invalid input. + line="678">A `PangoGlyph` value for invalid input. `PangoLayout` produces one such glyph per invalid input UTF-8 byte and such a glyph is rendered as a crossed box. Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG set. - + c:type="PANGO_GLYPH_UNKNOWN_FLAG"> Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode + line="691">Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode character into an unknown-character glyph for that `gunichar`. Such unknown-character glyphs may be rendered as a 'hex box'. - + - + @@ -10246,7 +10548,7 @@ See also [enum@Pango.Gravity] - + @@ -10255,7 +10557,7 @@ See also [enum@Pango.Gravity] - + @@ -10264,7 +10566,7 @@ See also [enum@Pango.Gravity] - + @@ -10273,7 +10575,7 @@ See also [enum@Pango.Gravity] - + @@ -10282,7 +10584,7 @@ See also [enum@Pango.Gravity] - + @@ -10309,7 +10611,7 @@ See also [enum@Pango.Gravity] - + @@ -10318,7 +10620,7 @@ See also [enum@Pango.Gravity] - + @@ -10353,7 +10655,7 @@ See also [enum@Pango.Gravity] You typically obtain `PangoItems` by itemizing a piece of text with [func@itemize]. - + analysis results for the item. + line="103">analysis results for the item. Creates a new `PangoItem` structure initialized to default values. - + - + @@ -10430,7 +10732,7 @@ the iter to each call. Copy an existing `PangoItem` structure. - + Free a `PangoItem` and all associated memory. - + @@ -10469,6 +10771,34 @@ the iter to each call. + + Returns the character offset of the item from the beginning +of the itemized text. + +If the item has not been obtained from Pango's itemization +machinery, then the character offset is not available. In +that case, this function returns -1. + + + the character offset of the item from the beginning + of the itemized text, or -1 + + + + + a `PangoItem` + + + + - + - + @@ -10527,7 +10857,7 @@ itself. - + @@ -10536,7 +10866,7 @@ itself. - + @@ -10944,7 +11274,7 @@ and simply treat the results of a `PangoLayout` as a list of lines. filename="pango/pango-layout.c" line="276">Create a new `PangoLayout` object with attributes initialized to default values for a particular `PangoContext`. - + throws="1"> Loads data previously created via [method@Pango.Layout.serialize]. + line="1664">Loads data previously created via [method@Pango.Layout.serialize]. For a discussion of the supported format, see that function. Note: to verify that the returned layout is identical to the one that was serialized, you can compare @bytes to the result of serializing the layout again. - + a new `PangoLayout` + line="1679">a new `PangoLayout` a `PangoContext` + line="1666">a `PangoContext` the bytes containing the data + line="1668">the bytes containing the data `PangoLayoutDeserializeFlags` + line="1667">`PangoLayoutDeserializeFlags` @@ -11006,12 +11336,12 @@ result of serializing the layout again. c:identifier="pango_layout_context_changed"> Forces recomputation of any state in the `PangoLayout` that + line="1491">Forces recomputation of any state in the `PangoLayout` that might depend on the layout's context. This function should be called if you make changes to the context subsequent to creating the layout. - + @@ -11019,7 +11349,7 @@ subsequent to creating the layout. a `PangoLayout` + line="1493">a `PangoLayout` @@ -11031,7 +11361,7 @@ subsequent to creating the layout. The attribute list, tab array, and text from the original layout are all copied by value. - + Gets the alignment for the layout: how partial lines are + line="991">Gets the alignment for the layout: how partial lines are positioned within the horizontal space available. - + the alignment + line="998">the alignment a `PangoLayout` + line="993">a `PangoLayout` @@ -11071,19 +11401,19 @@ positioned within the horizontal space available. Gets the attribute list for the layout, if any. - + line="736">Gets the attribute list for the layout, if any. + a `PangoAttrList` + line="742">a `PangoAttrList` a `PangoLayout` + line="738">a `PangoLayout` @@ -11093,15 +11423,15 @@ positioned within the horizontal space available. version="1.4"> Gets whether to calculate the base direction for the layout + line="946">Gets whether to calculate the base direction for the layout according to its contents. See [method@Pango.Layout.set_auto_dir]. - + %TRUE if the bidirectional base direction + line="955">%TRUE if the bidirectional base direction is computed from the layout's contents, %FALSE otherwise @@ -11109,7 +11439,7 @@ See [method@Pango.Layout.set_auto_dir]. a `PangoLayout` + line="948">a `PangoLayout` @@ -11119,19 +11449,19 @@ See [method@Pango.Layout.set_auto_dir]. version="1.22"> Gets the Y position of baseline of the first line in @layout. - + line="3202">Gets the Y position of baseline of the first line in @layout. + baseline of first line, from top of @layout + line="3208">baseline of first line, from top of @layout a `PangoLayout` + line="3204">a `PangoLayout` @@ -11141,7 +11471,7 @@ See [method@Pango.Layout.set_auto_dir]. version="1.50"> Given an index within a layout, determines the positions that of the + line="2668">Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. This is a variant of [method@Pango.Layout.get_cursor_pos] that applies @@ -11152,7 +11482,7 @@ it returns. <source srcset="caret-metrics-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Caret metrics" src="caret-metrics-light.png"> </picture> - + @@ -11160,13 +11490,13 @@ it returns. a `PangoLayout` + line="2670">a `PangoLayout` the byte index of the cursor + line="2671">the byte index of the cursor location to store the strong cursor position + line="2672">location to store the strong cursor position location to store the weak cursor position + line="2673">location to store the weak cursor position @@ -11198,13 +11528,13 @@ it returns. version="1.30"> Returns the number of Unicode characters in the + line="1314">Returns the number of Unicode characters in the the text of @layout. - + the number of Unicode characters + line="1321">the number of Unicode characters in the text of @layout @@ -11212,7 +11542,7 @@ the text of @layout. a `PangoLayout` + line="1316">a `PangoLayout` @@ -11221,7 +11551,7 @@ the text of @layout. Retrieves the `PangoContext` used for this layout. - + Given an index within a layout, determines the positions that of the + line="2545">Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle @@ -11267,7 +11597,7 @@ The strong cursor has a little arrow pointing to the right, the weak cursor to the left. Typing a 'c' in this situation will insert the character after the 'b', and typing another Hebrew character, like 'ג', will insert it at the end. - + @@ -11275,13 +11605,13 @@ will insert it at the end. a `PangoLayout` + line="2547">a `PangoLayout` the byte index of the cursor + line="2548">the byte index of the cursor allow-none="1"> location to store the strong cursor position + line="2549">location to store the strong cursor position allow-none="1"> location to store the weak cursor position + line="2550">location to store the weak cursor position @@ -11313,25 +11643,25 @@ will insert it at the end. version="1.46"> Gets the text direction at the given character position in @layout. - + line="2520">Gets the text direction at the given character position in @layout. + the text direction at @index + line="2527">the text direction at @index a `PangoLayout` + line="2522">a `PangoLayout` the byte index of the char + line="2523">the byte index of the char @@ -11341,24 +11671,24 @@ will insert it at the end. version="1.6"> Gets the type of ellipsization being performed for @layout. + line="1158">Gets the type of ellipsization being performed for @layout. See [method@Pango.Layout.set_ellipsize]. Use [method@Pango.Layout.is_ellipsized] to query whether any paragraphs were actually ellipsized. - + the current ellipsization mode for @layout + line="1169">the current ellipsization mode for @layout a `PangoLayout` + line="1160">a `PangoLayout` @@ -11366,7 +11696,7 @@ paragraphs were actually ellipsized. Computes the logical and ink extents of @layout. + line="3091">Computes the logical and ink extents of @layout. Logical extents are usually what you want for positioning things. Note that both extents may have non-zero x and y. You may want to use those @@ -11376,7 +11706,7 @@ in a layout with a set width. The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout. - + @@ -11384,7 +11714,7 @@ coordinates begin at the top left corner of the layout. a `PangoLayout` + line="3093">a `PangoLayout` allow-none="1"> rectangle used to store the extents of the + line="3094">rectangle used to store the extents of the layout as drawn @@ -11407,7 +11737,7 @@ coordinates begin at the top left corner of the layout. allow-none="1"> rectangle used to store the logical + line="3096">rectangle used to store the logical extents of the layout @@ -11418,12 +11748,12 @@ coordinates begin at the top left corner of the layout. version="1.8"> Gets the font description for the layout, if any. - + line="782">Gets the font description for the layout, if any. + a pointer to the + line="788">a pointer to the layout's font description, or %NULL if the font description from the layout's context is inherited. @@ -11432,7 +11762,7 @@ coordinates begin at the top left corner of the layout. a `PangoLayout` + line="784">a `PangoLayout` @@ -11445,7 +11775,7 @@ coordinates begin at the top left corner of the layout. line="452">Gets the height of layout used for ellipsization. See [method@Pango.Layout.set_height] for details. - + Gets the paragraph indent width in Pango units. + line="573">Gets the paragraph indent width in Pango units. A negative value indicates a hanging indentation. - + the indent in Pango units + line="581">the indent in Pango units a `PangoLayout` + line="575">a `PangoLayout` @@ -11487,19 +11817,19 @@ A negative value indicates a hanging indentation. Returns an iterator to iterate over the visual extents of the layout. - + line="7199">Returns an iterator to iterate over the visual extents of the layout. + the new `PangoLayoutIter` + line="7205">the new `PangoLayoutIter` a `PangoLayout` + line="7201">a `PangoLayout` @@ -11507,20 +11837,20 @@ A negative value indicates a hanging indentation. Gets whether each complete line should be stretched to fill the entire + line="842">Gets whether each complete line should be stretched to fill the entire width of the layout. - + the justify value + line="849">the justify value a `PangoLayout` + line="844">a `PangoLayout` @@ -11530,20 +11860,20 @@ width of the layout. version="1.50"> Gets whether the last line should be stretched + line="888">Gets whether the last line should be stretched to fill the entire width of the layout. - + the justify value + line="895">the justify value a `PangoLayout` + line="890">a `PangoLayout` @@ -11551,15 +11881,15 @@ to fill the entire width of the layout. Retrieves a particular line from a `PangoLayout`. + line="1688">Retrieves a particular line from a `PangoLayout`. Use the faster [method@Pango.Layout.get_line_readonly] if you do not plan to modify the contents of the line (glyphs, glyph widths, etc.). - + the requested `PangoLayoutLine`, + line="1699">the requested `PangoLayoutLine`, or %NULL if the index is out of range. This layout line can be ref'ed and retained, but will become invalid if changes are made to the `PangoLayout`. @@ -11569,13 +11899,13 @@ plan to modify the contents of the line (glyphs, glyph widths, etc.). a `PangoLayout` + line="1690">a `PangoLayout` the index of a line, which must be between 0 and + line="1691">the index of a line, which must be between 0 and `pango_layout_get_line_count(layout) - 1`, inclusive. @@ -11584,19 +11914,19 @@ plan to modify the contents of the line (glyphs, glyph widths, etc.). Retrieves the count of lines for the @layout. - + line="1611">Retrieves the count of lines for the @layout. + the line count + line="1617">the line count `PangoLayout` + line="1613">`PangoLayout` @@ -11606,16 +11936,16 @@ plan to modify the contents of the line (glyphs, glyph widths, etc.). version="1.16"> Retrieves a particular line from a `PangoLayout`. + line="1729">Retrieves a particular line from a `PangoLayout`. This is a faster alternative to [method@Pango.Layout.get_line], but the user is not expected to modify the contents of the line (glyphs, glyph widths, etc.). - + the requested `PangoLayoutLine`, + line="1741">the requested `PangoLayoutLine`, or %NULL if the index is out of range. This layout line can be ref'ed and retained, but will become invalid if changes are made to the `PangoLayout`. No changes should be made to the line. @@ -11625,13 +11955,13 @@ but the user is not expected to modify the contents of the line a `PangoLayout` + line="1731">a `PangoLayout` the index of a line, which must be between 0 and + line="1732">the index of a line, which must be between 0 and `pango_layout_get_line_count(layout) - 1`, inclusive. @@ -11642,10 +11972,10 @@ but the user is not expected to modify the contents of the line version="1.44"> Gets the line spacing factor of @layout. + line="677">Gets the line spacing factor of @layout. See [method@Pango.Layout.set_line_spacing]. - + @@ -11653,7 +11983,7 @@ See [method@Pango.Layout.set_line_spacing]. a `PangoLayout` + line="679">a `PangoLayout` @@ -11661,15 +11991,15 @@ See [method@Pango.Layout.set_line_spacing]. Returns the lines of the @layout as a list. + line="1628">Returns the lines of the @layout as a list. Use the faster [method@Pango.Layout.get_lines_readonly] if you do not plan to modify the contents of the lines (glyphs, glyph widths, etc.). - + a `GSList` + line="1637">a `GSList` containing the lines in the layout. This points to internal data of the `PangoLayout` and must be used with care. It will become invalid on any change to the layout's text or properties. @@ -11681,7 +12011,7 @@ plan to modify the contents of the lines (glyphs, glyph widths, etc.). a `PangoLayout` + line="1630">a `PangoLayout` @@ -11691,16 +12021,16 @@ plan to modify the contents of the lines (glyphs, glyph widths, etc.). version="1.16"> Returns the lines of the @layout as a list. + line="1662">Returns the lines of the @layout as a list. This is a faster alternative to [method@Pango.Layout.get_lines], but the user is not expected to modify the contents of the lines (glyphs, glyph widths, etc.). - + a `GSList` + line="1672">a `GSList` containing the lines in the layout. This points to internal data of the `PangoLayout` and must be used with care. It will become invalid on any change to the layout's text or properties. No changes should be made to @@ -11713,7 +12043,7 @@ but the user is not expected to modify the contents of the lines a `PangoLayout` + line="1664">a `PangoLayout` @@ -11721,9 +12051,9 @@ but the user is not expected to modify the contents of the lines Retrieves an array of logical attributes for each character in + line="1538">Retrieves an array of logical attributes for each character in the @layout. - + @@ -11731,7 +12061,7 @@ the @layout. a `PangoLayout` + line="1540">a `PangoLayout` transfer-ownership="container"> + line="1541"> location to store a pointer to an array of logical attributes. This value must be freed with g_free(). @@ -11753,7 +12083,7 @@ the @layout. transfer-ownership="full"> location to store the number of the attributes in the + line="1544">location to store the number of the attributes in the array. (The stored value will be one more than the total number of characters in the layout, since there need to be attributes corresponding to both the position before the first character @@ -11767,7 +12097,7 @@ the @layout. version="1.30"> Retrieves an array of logical attributes for each character in + line="1572">Retrieves an array of logical attributes for each character in the @layout. This is a faster alternative to [method@Pango.Layout.get_log_attrs]. @@ -11778,11 +12108,11 @@ The number of attributes returned in @n_attrs will be one more than the total number of characters in the layout, since there need to be attributes corresponding to both the position before the first character and the position after the last character. - + an array of logical attributes + line="1590">an array of logical attributes @@ -11791,7 +12121,7 @@ the first character and the position after the last character. a `PangoLayout` + line="1574">a `PangoLayout` transfer-ownership="full"> location to store the number of the attributes in + line="1575">location to store the number of the attributes in the array @@ -11810,13 +12140,13 @@ the first character and the position after the last character. c:identifier="pango_layout_get_pixel_extents"> Computes the logical and ink extents of @layout in device units. + line="3120">Computes the logical and ink extents of @layout in device units. This function just calls [method@Pango.Layout.get_extents] followed by two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect such that the rounded rectangles fully contain the unrounded one (that is, passes them as first argument to [func@Pango.extents_to_pixels]). - + @@ -11824,7 +12154,7 @@ passes them as first argument to [func@Pango.extents_to_pixels]). a `PangoLayout` + line="3122">a `PangoLayout` allow-none="1"> rectangle used to store the extents of the + line="3123">rectangle used to store the extents of the layout as drawn @@ -11847,7 +12177,7 @@ passes them as first argument to [func@Pango.extents_to_pixels]). allow-none="1"> rectangle used to store the logical + line="3125">rectangle used to store the logical extents of the layout @@ -11856,13 +12186,13 @@ passes them as first argument to [func@Pango.extents_to_pixels]). Determines the logical width and height of a `PangoLayout` in device + line="3173">Determines the logical width and height of a `PangoLayout` in device units. [method@Pango.Layout.get_size] returns the width and height scaled by %PANGO_SCALE. This is simply a convenience function around [method@Pango.Layout.get_pixel_extents]. - + @@ -11870,7 +12200,7 @@ around [method@Pango.Layout.get_pixel_extents]. a `PangoLayout` + line="3175">a `PangoLayout` allow-none="1"> location to store the logical width + line="3176">location to store the logical width allow-none="1"> location to store the logical height + line="3177">location to store the logical height @@ -11902,7 +12232,7 @@ around [method@Pango.Layout.get_pixel_extents]. version="1.32.4"> Returns the current serial number of @layout. + line="1510">Returns the current serial number of @layout. The serial number is initialized to an small number larger than zero when a new layout is created and is increased whenever the layout is @@ -11914,18 +12244,18 @@ This can be used to automatically detect changes to a `PangoLayout`, and is useful for example to decide whether a layout needs redrawing. To force the serial to be increased, use [method@Pango.Layout.context_changed]. - + The current serial number of @layout. + line="1527">The current serial number of @layout. a `PangoLayout` + line="1512">a `PangoLayout` @@ -11934,14 +12264,14 @@ To force the serial to be increased, use c:identifier="pango_layout_get_single_paragraph_mode"> Obtains whether @layout is in single paragraph mode. + line="1101">Obtains whether @layout is in single paragraph mode. See [method@Pango.Layout.set_single_paragraph_mode]. - + %TRUE if the layout does not break paragraphs + line="1109">%TRUE if the layout does not break paragraphs at paragraph separator characters, %FALSE otherwise @@ -11949,7 +12279,7 @@ See [method@Pango.Layout.set_single_paragraph_mode]. a `PangoLayout` + line="1103">a `PangoLayout` @@ -11957,11 +12287,11 @@ See [method@Pango.Layout.set_single_paragraph_mode]. Determines the logical width and height of a `PangoLayout` in Pango + line="3147">Determines the logical width and height of a `PangoLayout` in Pango units. This is simply a convenience function around [method@Pango.Layout.get_extents]. - + @@ -11969,7 +12299,7 @@ This is simply a convenience function around [method@Pango.Layout.get_extents].< a `PangoLayout` + line="3149">a `PangoLayout` location to store the logical width + line="3150">location to store the logical width location to store the logical height + line="3151">location to store the logical height @@ -11999,19 +12329,19 @@ This is simply a convenience function around [method@Pango.Layout.get_extents].< Gets the amount of spacing between the lines of the layout. - + line="625">Gets the amount of spacing between the lines of the layout. + the spacing in Pango units + line="631">the spacing in Pango units a `PangoLayout` + line="627">a `PangoLayout` @@ -12019,24 +12349,24 @@ This is simply a convenience function around [method@Pango.Layout.get_extents].< Gets the current `PangoTabArray` used by this layout. + line="1048">Gets the current `PangoTabArray` used by this layout. If no `PangoTabArray` has been set, then the default tabs are in use and %NULL is returned. Default tabs are every 8 spaces. The return value should be freed with [method@Pango.TabArray.free]. - + a copy of the tabs for this layout + line="1059">a copy of the tabs for this layout a `PangoLayout` + line="1050">a `PangoLayout` @@ -12044,21 +12374,21 @@ The return value should be freed with [method@Pango.TabArray.free]. Gets the text in the layout. + line="1291">Gets the text in the layout. The returned text should not be freed or modified. - + the text in the @layout + line="1299">the text in the @layout a `PangoLayout` + line="1293">a `PangoLayout` @@ -12068,24 +12398,24 @@ The returned text should not be freed or modified. version="1.16"> Counts the number of unknown glyphs in @layout. + line="1414">Counts the number of unknown glyphs in @layout. This function can be used to determine if there are any fonts available to render all characters in a certain string, or when used in combination with %PANGO_ATTR_FALLBACK, to check if a certain font supports all the characters in the string. - + The number of unknown glyphs in @layout + line="1425">The number of unknown glyphs in @layout a `PangoLayout` + line="1416">a `PangoLayout` @@ -12094,7 +12424,7 @@ certain font supports all the characters in the string. Gets the width to which the lines of the `PangoLayout` should wrap. - + Use [method@Pango.Layout.is_wrapped] to query whether any paragraphs were actually wrapped. - + c:identifier="pango_layout_index_to_line_x"> Converts from byte @index_ within the @layout to line and X position. + line="1949">Converts from byte @index_ within the @layout to line and X position. The X position is measured from the left edge of the line. - + @@ -12148,19 +12478,19 @@ The X position is measured from the left edge of the line. a `PangoLayout` + line="1951">a `PangoLayout` the byte index of a grapheme within the layout + line="1952">the byte index of a grapheme within the layout an integer indicating the edge of the grapheme to retrieve the + line="1953">an integer indicating the edge of the grapheme to retrieve the position of. If > 0, the trailing edge of the grapheme, if 0, the leading of the grapheme @@ -12173,7 +12503,7 @@ The X position is measured from the left edge of the line. allow-none="1"> location to store resulting line index. (which will + line="1956">location to store resulting line index. (which will between 0 and pango_layout_get_line_count(layout) - 1) @@ -12185,7 +12515,7 @@ The X position is measured from the left edge of the line. allow-none="1"> location to store resulting position within line + line="1958">location to store resulting position within line (%PANGO_SCALE units per device unit) @@ -12194,14 +12524,14 @@ The X position is measured from the left edge of the line. Converts from an index within a `PangoLayout` to the onscreen position + line="2378">Converts from an index within a `PangoLayout` to the onscreen position corresponding to the grapheme at that index. The returns is represented as rectangle. Note that `pos->x` is always the leading edge of the grapheme and `pos->x + pos->width` the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then `pos->width` will be negative. - + @@ -12209,13 +12539,13 @@ is right-to-left, then `pos->width` will be negative. a `PangoLayout` + line="2380">a `PangoLayout` byte index within @layout + line="2381">byte index within @layout transfer-ownership="none"> rectangle in which to store the position of the grapheme + line="2382">rectangle in which to store the position of the grapheme @@ -12234,17 +12564,17 @@ is right-to-left, then `pos->width` will be negative. version="1.16"> Queries whether the layout had to ellipsize any paragraphs. + line="1181">Queries whether the layout had to ellipsize any paragraphs. This returns %TRUE if the ellipsization mode for @layout is not %PANGO_ELLIPSIZE_NONE, a positive width is set on @layout, and there are paragraphs exceeding that width that have to be ellipsized. - + %TRUE if any paragraphs had to be ellipsized, + line="1192">%TRUE if any paragraphs had to be ellipsized, %FALSE otherwise @@ -12252,7 +12582,7 @@ ellipsized. a `PangoLayout` + line="1183">a `PangoLayout` @@ -12265,14 +12595,13 @@ ellipsized. line="519">Queries whether the layout had to wrap any paragraphs. This returns %TRUE if a positive width is set on @layout, -ellipsization mode of @layout is set to %PANGO_ELLIPSIZE_NONE, and there are paragraphs exceeding the layout width that have to be wrapped. - + %TRUE if any paragraphs had to be wrapped, %FALSE + line="529">%TRUE if any paragraphs had to be wrapped, %FALSE otherwise @@ -12289,7 +12618,7 @@ to be wrapped. c:identifier="pango_layout_move_cursor_visually"> Computes a new cursor position from an old position and a direction. + line="2064">Computes a new cursor position from an old position and a direction. If @direction is positive, then the new position will cause the strong or weak cursor to be displayed one position to right of where it was @@ -12304,7 +12633,7 @@ of a run. Motion here is in cursor positions, not in characters, so a single call to this function may move the cursor over multiple characters when multiple characters combine to form a single grapheme. - + @@ -12312,13 +12641,13 @@ when multiple characters combine to form a single grapheme. a `PangoLayout` + line="2066">a `PangoLayout` whether the moving cursor is the strong cursor or the + line="2067">whether the moving cursor is the strong cursor or the weak cursor. The strong cursor is the cursor corresponding to text insertion in the base direction for the layout. @@ -12326,13 +12655,13 @@ when multiple characters combine to form a single grapheme. the byte index of the current cursor position + line="2070">the byte index of the current cursor position if 0, the cursor was at the leading edge of the + line="2071">if 0, the cursor was at the leading edge of the grapheme indicated by @old_index, if > 0, the cursor was at the trailing edge. @@ -12340,7 +12669,7 @@ when multiple characters combine to form a single grapheme. direction to move cursor. A negative + line="2074">direction to move cursor. A negative value indicates motion to the left @@ -12350,7 +12679,7 @@ when multiple characters combine to form a single grapheme. transfer-ownership="full"> location to store the new cursor byte index. + line="2076">location to store the new cursor byte index. A value of -1 indicates that the cursor has been moved off the beginning of the layout. A value of %G_MAXINT indicates that the cursor has been moved off the end of the layout. @@ -12362,7 +12691,7 @@ when multiple characters combine to form a single grapheme. transfer-ownership="full"> number of characters to move forward from + line="2080">number of characters to move forward from the location returned for @new_index to get the position where the cursor should be displayed. This allows distinguishing the position at the beginning of one line from the position at the @@ -12377,7 +12706,7 @@ when multiple characters combine to form a single grapheme. version="1.50"> Serializes the @layout for later deserialization via [func@Pango.Layout.deserialize]. + line="1575">Serializes the @layout for later deserialization via [func@Pango.Layout.deserialize]. There are no guarantees about the format of the output across different versions of Pango and [func@Pango.Layout.deserialize] will reject data @@ -12385,24 +12714,24 @@ that it cannot parse. The intended use of this function is testing, benchmarking and debugging. The format is not meant as a permanent storage format. - + a `GBytes` containing the serialized form of @layout + line="1589">a `GBytes` containing the serialized form of @layout a `PangoLayout` + line="1577">a `PangoLayout` `PangoLayoutSerializeFlags` + line="1578">`PangoLayoutSerializeFlags` @@ -12411,11 +12740,11 @@ The format is not meant as a permanent storage format. Sets the alignment for the layout: how partial lines are + line="968">Sets the alignment for the layout: how partial lines are positioned within the horizontal space available. The default alignment is %PANGO_ALIGN_LEFT. - + @@ -12423,13 +12752,13 @@ The default alignment is %PANGO_ALIGN_LEFT. a `PangoLayout` + line="970">a `PangoLayout` the alignment + line="971">the alignment @@ -12437,10 +12766,10 @@ The default alignment is %PANGO_ALIGN_LEFT. Sets the text attributes for a layout object. + line="694">Sets the text attributes for a layout object. References @attrs, so the caller can unref its reference. - + @@ -12448,7 +12777,7 @@ References @attrs, so the caller can unref its reference. a `PangoLayout` + line="696">a `PangoLayout` allow-none="1"> a `PangoAttrList` + line="697">a `PangoAttrList` @@ -12467,7 +12796,7 @@ References @attrs, so the caller can unref its reference. version="1.4"> Sets whether to calculate the base direction + line="906">Sets whether to calculate the base direction for the layout according to its contents. When this flag is on (the default), then paragraphs in @layout that @@ -12483,7 +12812,7 @@ layout is done according to the base direction of the layout's When the auto-computed direction of a paragraph differs from the base direction of the context, the interpretation of %PANGO_ALIGN_LEFT and %PANGO_ALIGN_RIGHT are swapped. - + @@ -12491,13 +12820,13 @@ base direction of the context, the interpretation of a `PangoLayout` + line="908">a `PangoLayout` if %TRUE, compute the bidirectional base direction + line="909">if %TRUE, compute the bidirectional base direction from the layout's contents @@ -12508,7 +12837,7 @@ base direction of the context, the interpretation of version="1.6"> Sets the type of ellipsization being performed for @layout. + line="1120">Sets the type of ellipsization being performed for @layout. Depending on the ellipsization mode @ellipsize text is removed from the start, middle, or end of text so they @@ -12523,7 +12852,7 @@ is ellipsized as a whole depends on the set height of the layout. The default value is %PANGO_ELLIPSIZE_NONE. See [method@Pango.Layout.set_height] for details. - + @@ -12531,13 +12860,13 @@ See [method@Pango.Layout.set_height] for details. a `PangoLayout` + line="1122">a `PangoLayout` the new ellipsization mode for @layout + line="1123">the new ellipsization mode for @layout @@ -12546,11 +12875,11 @@ See [method@Pango.Layout.set_height] for details. c:identifier="pango_layout_set_font_description"> Sets the default font description for the layout. + line="752">Sets the default font description for the layout. If no font description is set on the layout, the font description from the layout's context is used. - + @@ -12558,7 +12887,7 @@ font description from the layout's context is used. a `PangoLayout` + line="754">a `PangoLayout` allow-none="1"> the new `PangoFontDescription` + line="755">the new `PangoFontDescription` to unset the current font description @@ -12603,7 +12932,7 @@ Height setting only has effect if a positive width is set on The behavior is undefined if a height other than -1 is set and ellipsization mode is set to %PANGO_ELLIPSIZE_NONE, and may change in the future. - + @@ -12626,7 +12955,7 @@ future. Sets the width in Pango units to indent each paragraph. + line="544">Sets the width in Pango units to indent each paragraph. A negative value of @indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent @@ -12636,7 +12965,7 @@ The indent setting is ignored if layout alignment is set to %PANGO_ALIGN_CENTER. The default value is 0. - + @@ -12644,13 +12973,13 @@ The default value is 0. a `PangoLayout` + line="546">a `PangoLayout` the amount by which to indent + line="547">the amount by which to indent @@ -12658,7 +12987,7 @@ The default value is 0. Sets whether each complete line should be stretched to fill the + line="802">Sets whether each complete line should be stretched to fill the entire width of the layout. Stretching is typically done by adding whitespace, but for some scripts @@ -12675,7 +13004,7 @@ positions. The default value is %FALSE. Also see [method@Pango.Layout.set_justify_last_line]. - + @@ -12683,13 +13012,13 @@ Also see [method@Pango.Layout.set_justify_last_line]. a `PangoLayout` + line="804">a `PangoLayout` whether the lines in the layout should be justified + line="805">whether the lines in the layout should be justified @@ -12699,14 +13028,14 @@ Also see [method@Pango.Layout.set_justify_last_line]. version="1.50"> Sets whether the last line should be stretched to fill the + line="858">Sets whether the last line should be stretched to fill the entire width of the layout. This only has an effect if [method@Pango.Layout.set_justify] has been called as well. The default value is %FALSE. - + @@ -12714,13 +13043,13 @@ The default value is %FALSE. a `PangoLayout` + line="860">a `PangoLayout` whether the last line in the layout should be justified + line="861">whether the last line in the layout should be justified @@ -12730,7 +13059,7 @@ The default value is %FALSE. version="1.44"> Sets a factor for line spacing. + line="640">Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2. The default values is 0. @@ -12746,7 +13075,7 @@ If @factor is zero (the default), spacing is applied as before. Note: for semantics that are closer to the CSS line-height property, see [func@Pango.attr_line_height_new]. - + @@ -12754,13 +13083,13 @@ property, see [func@Pango.attr_line_height_new]. a `PangoLayout` + line="642">a `PangoLayout` the new line spacing factor + line="643">the new line spacing factor @@ -12768,7 +13097,7 @@ property, see [func@Pango.attr_line_height_new]. Sets the layout text and attribute list from marked-up text. + line="1334">Sets the layout text and attribute list from marked-up text. See [Pango Markup](pango_markup.html)). @@ -12776,7 +13105,7 @@ Replaces the current text and attribute list. This is the same as [method@Pango.Layout.set_markup_with_accel], but the markup text isn't scanned for accelerators. - + @@ -12784,19 +13113,19 @@ but the markup text isn't scanned for accelerators. a `PangoLayout` + line="1336">a `PangoLayout` marked-up text + line="1337">marked-up text length of marked-up text in bytes, or -1 if @markup is + line="1338">length of marked-up text in bytes, or -1 if @markup is `NUL`-terminated @@ -12806,7 +13135,7 @@ but the markup text isn't scanned for accelerators. c:identifier="pango_layout_set_markup_with_accel"> Sets the layout text and attribute list from marked-up text. + line="1358">Sets the layout text and attribute list from marked-up text. See [Pango Markup](pango_markup.html)). @@ -12819,7 +13148,7 @@ as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned in @accel_char. Two @accel_marker characters following each other produce a single literal @accel_marker character. - + @@ -12827,26 +13156,26 @@ literal @accel_marker character. a `PangoLayout` + line="1360">a `PangoLayout` marked-up text (see [Pango Markup](pango_markup.html)) + line="1361">marked-up text (see [Pango Markup](pango_markup.html)) length of marked-up text in bytes, or -1 if @markup is + line="1362">length of marked-up text in bytes, or -1 if @markup is `NUL`-terminated marker for accelerators in the text + line="1364">marker for accelerators in the text allow-none="1"> return location + line="1365">return location for first located accelerator @@ -12867,7 +13196,7 @@ literal @accel_marker character. c:identifier="pango_layout_set_single_paragraph_mode"> Sets the single paragraph mode of @layout. + line="1072">Sets the single paragraph mode of @layout. If @setting is %TRUE, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, @@ -12875,7 +13204,7 @@ and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line. The default value is %FALSE. - + @@ -12883,13 +13212,13 @@ The default value is %FALSE. a `PangoLayout` + line="1074">a `PangoLayout` new setting + line="1075">new setting @@ -12897,7 +13226,7 @@ The default value is %FALSE. Sets the amount of spacing in Pango units between + line="590">Sets the amount of spacing in Pango units between the lines of the layout. When placing lines with spacing, Pango arranges things so that @@ -12913,7 +13242,7 @@ In that case, the @spacing set with this function is ignored. Note: for semantics that are closer to the CSS line-height property, see [func@Pango.attr_line_height_new]. - + @@ -12921,13 +13250,13 @@ property, see [func@Pango.attr_line_height_new]. a `PangoLayout` + line="592">a `PangoLayout` the amount of spacing + line="593">the amount of spacing @@ -12935,7 +13264,7 @@ property, see [func@Pango.attr_line_height_new]. Sets the tabs to use for @layout, overriding the default tabs. + line="1008">Sets the tabs to use for @layout, overriding the default tabs. `PangoLayout` will place content at the next tab position whenever it meets a Tab character (U+0009). @@ -12948,7 +13277,7 @@ Note that tabs and justification conflict with each other: Justification will move content away from its tab-aligned positions. The same is true for alignments other than %PANGO_ALIGN_LEFT. - + @@ -12956,7 +13285,7 @@ positions. The same is true for alignments other than a `PangoLayout` + line="1010">a `PangoLayout` a `PangoTabArray` + line="1011">a `PangoTabArray` @@ -12973,7 +13302,7 @@ positions. The same is true for alignments other than Sets the text of the layout. + line="1207">Sets the text of the layout. This function validates @text and renders invalid UTF-8 with a placeholder glyph. @@ -12983,7 +13312,7 @@ Note that if you have used [method@Pango.Layout.set_markup] or may want to call [method@Pango.Layout.set_attributes] to clear the attributes set on the layout from the markup as this function does not clear attributes. - + @@ -12991,19 +13320,19 @@ not clear attributes. a `PangoLayout` + line="1209">a `PangoLayout` the text + line="1210">the text maximum length of @text, in bytes. -1 indicates that + line="1211">maximum length of @text, in bytes. -1 indicates that the string is nul-terminated and the length should be calculated. The text will also be truncated on encountering a nul-termination even when @length is positive. @@ -13015,10 +13344,10 @@ not clear attributes. Sets the width to which the lines of the `PangoLayout` should wrap or -ellipsized. +get ellipsized. The default value is -1: no width set. - + @@ -13048,7 +13377,7 @@ with [method@Pango.Layout.set_width]. To turn off wrapping, set the width to -1. The default value is %PANGO_WRAP_WORD. - + @@ -13073,7 +13402,7 @@ The default value is %PANGO_WRAP_WORD. throws="1"> A convenience method to serialize a layout to a file. + line="1619">A convenience method to serialize a layout to a file. It is equivalent to calling [method@Pango.Layout.serialize] followed by [func@GLib.file_set_contents]. @@ -13082,31 +13411,31 @@ See those two functions for details on the arguments. It is mostly intended for use inside a debugger to quickly dump a layout to a file for later inspection. - + %TRUE if saving was successful + line="1636">%TRUE if saving was successful a `PangoLayout` + line="1621">a `PangoLayout` `PangoLayoutSerializeFlags` + line="1622">`PangoLayoutSerializeFlags` the file to save it to + line="1623">the file to save it to @@ -13114,7 +13443,7 @@ a layout to a file for later inspection. Converts from X and Y position within a layout to the byte index to the + line="2272">Converts from X and Y position within a layout to the byte index to the character at that logical position. If the Y position is not inside the layout, the closest position is @@ -13123,30 +13452,30 @@ is not within the layout, then the start or the end of the line is chosen as described for [method@Pango.LayoutLine.x_to_index]. If either the X or Y positions were not inside the layout, then the function returns %FALSE; on an exact hit, it returns %TRUE. - + %TRUE if the coordinates were inside text, %FALSE otherwise + line="2293">%TRUE if the coordinates were inside text, %FALSE otherwise a `PangoLayout` + line="2274">a `PangoLayout` the X offset (in Pango units) from the left edge of the layout + line="2275">the X offset (in Pango units) from the left edge of the layout the Y offset (in Pango units) from the top edge of the layout + line="2276">the Y offset (in Pango units) from the top edge of the layout location to store calculated byte index + line="2277">location to store calculated byte index location to store a integer indicating where + line="2278">location to store a integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the leading edge of the grapheme. @@ -13188,7 +13517,7 @@ the X or Y positions were not inside the layout, then the function returns glib:error-domain="pango-layout-deserialize-error-quark"> Errors that can be returned by [func@Pango.Layout.deserialize]. + line="394">Errors that can be returned by [func@Pango.Layout.deserialize]. Unspecified error + line="396">Unspecified error A JSon value could not be + line="397">A JSon value could not be interpreted A required JSon member was + line="399">A required JSon member was not found Flags that influence the behavior of [func@Pango.Layout.deserialize]. + line="415">Flags that influence the behavior of [func@Pango.Layout.deserialize]. New members may be added to this enumeration over time. glib:name="PANGO_LAYOUT_DESERIALIZE_DEFAULT"> Default behavior + line="417">Default behavior glib:name="PANGO_LAYOUT_DESERIALIZE_CONTEXT"> Apply context information + line="418">Apply context information from the serialization to the `PangoContext` @@ -13269,24 +13598,24 @@ extents of a `PangoLayout`. To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter]. The `PangoLayoutIter` structure is opaque, and has no user-visible fields. - + Determines whether @iter is on the last line of the layout. - + line="7440">Determines whether @iter is on the last line of the layout. + %TRUE if @iter is on the last line + line="7446">%TRUE if @iter is on the last line a `PangoLayoutIter` + line="7442">a `PangoLayoutIter` @@ -13294,12 +13623,12 @@ The `PangoLayoutIter` structure is opaque, and has no user-visible fields. Copies a `PangoLayoutIter`. - + line="7139">Copies a `PangoLayoutIter`. + the newly allocated `PangoLayoutIter` + line="7145">the newly allocated `PangoLayoutIter` @@ -13309,7 +13638,7 @@ The `PangoLayoutIter` structure is opaque, and has no user-visible fields. allow-none="1"> a `PangoLayoutIter` + line="7141">a `PangoLayoutIter` @@ -13317,8 +13646,8 @@ The `PangoLayoutIter` structure is opaque, and has no user-visible fields. Frees an iterator that's no longer in use. - + line="7284">Frees an iterator that's no longer in use. + @@ -13329,7 +13658,7 @@ The `PangoLayoutIter` structure is opaque, and has no user-visible fields. allow-none="1"> a `PangoLayoutIter`, may be %NULL + line="7286">a `PangoLayoutIter`, may be %NULL @@ -13338,22 +13667,22 @@ The `PangoLayoutIter` structure is opaque, and has no user-visible fields. c:identifier="pango_layout_iter_get_baseline"> Gets the Y position of the current line's baseline, in layout + line="8003">Gets the Y position of the current line's baseline, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. - + baseline of current line + line="8012">baseline of current line a `PangoLayoutIter` + line="8005">a `PangoLayoutIter` @@ -13362,13 +13691,13 @@ Layout coordinates have the origin at the top left of the entire layout. c:identifier="pango_layout_iter_get_char_extents"> Gets the extents of the current character, in layout coordinates. + line="7730">Gets the extents of the current character, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. Only logical extents can sensibly be obtained for characters; ink extents make sense only down to the level of clusters. - + @@ -13376,7 +13705,7 @@ ink extents make sense only down to the level of clusters. a `PangoLayoutIter` + line="7732">a `PangoLayoutIter` transfer-ownership="none"> rectangle to fill with + line="7733">rectangle to fill with logical extents @@ -13395,10 +13724,10 @@ ink extents make sense only down to the level of clusters. c:identifier="pango_layout_iter_get_cluster_extents"> Gets the extents of the current cluster, in layout coordinates. + line="7783">Gets the extents of the current cluster, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. - + @@ -13406,7 +13735,7 @@ Layout coordinates have the origin at the top left of the entire layout. a `PangoLayoutIter` + line="7785">a `PangoLayoutIter` allow-none="1"> rectangle to fill with ink extents + line="7786">rectangle to fill with ink extents allow-none="1"> rectangle to fill with logical extents + line="7787">rectangle to fill with logical extents @@ -13436,24 +13765,24 @@ Layout coordinates have the origin at the top left of the entire layout. Gets the current byte index. + line="7300">Gets the current byte index. Note that iterating forward by char moves in visual order, not logical order, so indexes may not be sequential. Also, the index may be equal to the length of the text in the layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). - + current byte index + line="7311">current byte index a `PangoLayoutIter` + line="7302">a `PangoLayoutIter` @@ -13463,19 +13792,19 @@ layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). version="1.20"> Gets the layout associated with a `PangoLayoutIter`. - + line="7457">Gets the layout associated with a `PangoLayoutIter`. + the layout associated with @iter + line="7463">the layout associated with @iter a `PangoLayoutIter` + line="7459">a `PangoLayoutIter` @@ -13484,8 +13813,8 @@ layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). c:identifier="pango_layout_iter_get_layout_extents"> Obtains the extents of the `PangoLayout` being iterated over. - + line="8049">Obtains the extents of the `PangoLayout` being iterated over. + @@ -13493,7 +13822,7 @@ layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). a `PangoLayoutIter` + line="8051">a `PangoLayoutIter` allow-none="1"> rectangle to fill with ink extents + line="8052">rectangle to fill with ink extents allow-none="1"> rectangle to fill with logical extents + line="8053">rectangle to fill with logical extents @@ -13523,23 +13852,23 @@ layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). Gets the current line. + line="7393">Gets the current line. Use the faster [method@Pango.LayoutIter.get_line_readonly] if you do not plan to modify the contents of the line (glyphs, glyph widths, etc.). - + the current line + line="7403">the current line a `PangoLayoutIter` + line="7395">a `PangoLayoutIter` @@ -13548,13 +13877,13 @@ glyph widths, etc.). c:identifier="pango_layout_iter_get_line_extents"> Obtains the extents of the current line. + line="7907">Obtains the extents of the current line. Extents are in layout coordinates (origin is the top-left corner of the entire `PangoLayout`). Thus the extents returned by this function will be the same width/height but not at the same x/y as the extents returned from [method@Pango.LayoutLine.get_extents]. - + @@ -13562,7 +13891,7 @@ as the extents returned from [method@Pango.LayoutLine.get_extents]. a `PangoLayoutIter` + line="7909">a `PangoLayoutIter` allow-none="1"> rectangle to fill with ink extents + line="7910">rectangle to fill with ink extents allow-none="1"> rectangle to fill with logical extents + line="7911">rectangle to fill with logical extents @@ -13594,16 +13923,16 @@ as the extents returned from [method@Pango.LayoutLine.get_extents]. version="1.16"> Gets the current line for read-only access. + line="7416">Gets the current line for read-only access. This is a faster alternative to [method@Pango.LayoutIter.get_line], but the user is not expected to modify the contents of the line (glyphs, glyph widths, etc.). - + the current line, that should not be + line="7426">the current line, that should not be modified @@ -13611,7 +13940,7 @@ but the user is not expected to modify the contents of the line a `PangoLayoutIter` + line="7418">a `PangoLayoutIter` @@ -13620,7 +13949,7 @@ but the user is not expected to modify the contents of the line c:identifier="pango_layout_iter_get_line_yrange"> Divides the vertical space in the `PangoLayout` being iterated over + line="7946">Divides the vertical space in the `PangoLayout` being iterated over between the lines in the layout, and returns the space belonging to the current line. @@ -13631,7 +13960,7 @@ coordinates (origin at top left of the entire layout). Note: Since 1.44, Pango uses line heights for placing lines, and there may be gaps between the ranges returned by this function. - + @@ -13639,7 +13968,7 @@ may be gaps between the ranges returned by this function. a `PangoLayoutIter` + line="7948">a `PangoLayoutIter` allow-none="1"> start of line + line="7949">start of line allow-none="1"> end of line + line="7950">end of line @@ -13669,7 +13998,7 @@ may be gaps between the ranges returned by this function. Gets the current run. + line="7322">Gets the current run. When iterating by run, at the end of each line, there's a position with a %NULL run, so this function can return %NULL. The %NULL run @@ -13678,18 +14007,18 @@ even lines consisting of only a newline. Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not plan to modify the contents of the run (glyphs, glyph widths, etc.). - + the current run + line="7336">the current run a `PangoLayoutIter` + line="7324">a `PangoLayoutIter` @@ -13699,14 +14028,14 @@ plan to modify the contents of the run (glyphs, glyph widths, etc.). version="1.50"> Gets the Y position of the current run's baseline, in layout + line="8023">Gets the Y position of the current run's baseline, in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. The run baseline can be different from the line baseline, for example due to superscript or subscript positioning. - + @@ -13714,7 +14043,7 @@ example due to superscript or subscript positioning. a `PangoLayoutIter` + line="8025">a `PangoLayoutIter` @@ -13723,10 +14052,10 @@ example due to superscript or subscript positioning. c:identifier="pango_layout_iter_get_run_extents"> Gets the extents of the current run in layout coordinates. + line="7833">Gets the extents of the current run in layout coordinates. Layout coordinates have the origin at the top left of the entire layout. - + @@ -13734,7 +14063,7 @@ Layout coordinates have the origin at the top left of the entire layout. a `PangoLayoutIter` + line="7835">a `PangoLayoutIter` allow-none="1"> rectangle to fill with ink extents + line="7836">rectangle to fill with ink extents allow-none="1"> rectangle to fill with logical extents + line="7837">rectangle to fill with logical extents @@ -13766,7 +14095,7 @@ Layout coordinates have the origin at the top left of the entire layout. version="1.16"> Gets the current run for read-only access. + line="7349">Gets the current run for read-only access. When iterating by run, at the end of each line, there's a position with a %NULL run, so this function can return %NULL. The %NULL run @@ -13776,11 +14105,11 @@ even lines consisting of only a newline. This is a faster alternative to [method@Pango.LayoutIter.get_run], but the user is not expected to modify the contents of the run (glyphs, glyph widths, etc.). - + the current run, that + line="7364">the current run, that should not be modified @@ -13788,7 +14117,7 @@ glyph widths, etc.). a `PangoLayoutIter` + line="7351">a `PangoLayoutIter` @@ -13796,21 +14125,21 @@ glyph widths, etc.). Moves @iter forward to the next character in visual order. + line="7579">Moves @iter forward to the next character in visual order. If @iter was already at the end of the layout, returns %FALSE. - + whether motion was possible + line="7587">whether motion was possible a `PangoLayoutIter` + line="7581">a `PangoLayoutIter` @@ -13819,21 +14148,21 @@ If @iter was already at the end of the layout, returns %FALSE. c:identifier="pango_layout_iter_next_cluster"> Moves @iter forward to the next cluster in visual order. + line="7624">Moves @iter forward to the next cluster in visual order. If @iter was already at the end of the layout, returns %FALSE. - + whether motion was possible + line="7632">whether motion was possible a `PangoLayoutIter` + line="7626">a `PangoLayoutIter` @@ -13841,21 +14170,21 @@ If @iter was already at the end of the layout, returns %FALSE. Moves @iter forward to the start of the next line. + line="7685">Moves @iter forward to the start of the next line. If @iter is already on the last line, returns %FALSE. - + whether motion was possible + line="7693">whether motion was possible a `PangoLayoutIter` + line="7687">a `PangoLayoutIter` @@ -13863,21 +14192,21 @@ If @iter is already on the last line, returns %FALSE. Moves @iter forward to the next run in visual order. + line="7640">Moves @iter forward to the next run in visual order. If @iter was already at the end of the layout, returns %FALSE. - + whether motion was possible + line="7648">whether motion was possible a `PangoLayoutIter` + line="7642">a `PangoLayoutIter` @@ -13890,35 +14219,35 @@ If @iter was already at the end of the layout, returns %FALSE. c:symbol-prefix="layout_line"> A `PangoLayoutLine` represents one of the lines resulting from laying + line="118">A `PangoLayoutLine` represents one of the lines resulting from laying out a paragraph via `PangoLayout`. `PangoLayoutLine` structures are obtained by calling [method@Pango.Layout.get_line] and are only valid until the text, attributes, or settings of the parent `PangoLayout` are modified. - + the layout this line belongs to, might be %NULL + line="120">the layout this line belongs to, might be %NULL start of line as byte index into layout->text + line="121">start of line as byte index into layout->text length of line in bytes + line="122">length of line in bytes list of runs in the + line="123">list of runs in the line, from left to right @@ -13927,23 +14256,23 @@ attributes, or settings of the parent `PangoLayout` are modified. #TRUE if this is the first line of the paragraph + line="125">#TRUE if this is the first line of the paragraph #Resolved PangoDirection of line + line="126">#Resolved PangoDirection of line Computes the logical and ink extents of a layout line. + line="5913">Computes the logical and ink extents of a layout line. See [method@Pango.Font.get_glyph_extents] for details about the interpretation of the rectangles. - + @@ -13951,7 +14280,7 @@ about the interpretation of the rectangles. a `PangoLayoutLine` + line="5915">a `PangoLayoutLine` allow-none="1"> rectangle used to store the extents of + line="5916">rectangle used to store the extents of the glyph string as drawn @@ -13974,7 +14303,7 @@ about the interpretation of the rectangles. allow-none="1"> rectangle used to store the logical + line="5918">rectangle used to store the logical extents of the glyph string @@ -13985,14 +14314,14 @@ about the interpretation of the rectangles. version="1.44"> Computes the height of the line, as the maximum of the heights + line="5934">Computes the height of the line, as the maximum of the heights of fonts used in this line. Note that the actual baseline-to-baseline distance between lines of text is influenced by other factors, such as [method@Pango.Layout.set_spacing] and [method@Pango.Layout.set_line_spacing]. - + @@ -14000,7 +14329,7 @@ of text is influenced by other factors, such as a `PangoLayoutLine` + line="5936">a `PangoLayoutLine` return location for the line height + line="5937">return location for the line height @@ -14021,19 +14350,19 @@ of text is influenced by other factors, such as version="1.50"> Returns the length of the line, in bytes. - + line="5070">Returns the length of the line, in bytes. + the length of the line + line="5076">the length of the line a `PangoLayoutLine` + line="5072">a `PangoLayoutLine` @@ -14042,13 +14371,13 @@ of text is influenced by other factors, such as c:identifier="pango_layout_line_get_pixel_extents"> Computes the logical and ink extents of @layout_line in device units. + line="5973">Computes the logical and ink extents of @layout_line in device units. This function just calls [method@Pango.LayoutLine.get_extents] followed by two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect such that the rounded rectangles fully contain the unrounded one (that is, passes them as first argument to [func@extents_to_pixels]). - + @@ -14056,7 +14385,7 @@ passes them as first argument to [func@extents_to_pixels]). a `PangoLayoutLine` + line="5975">a `PangoLayoutLine` allow-none="1"> rectangle used to store the extents of + line="5976">rectangle used to store the extents of the glyph string as drawn @@ -14079,7 +14408,7 @@ passes them as first argument to [func@extents_to_pixels]). allow-none="1"> rectangle used to store the logical + line="5978">rectangle used to store the logical extents of the glyph string @@ -14090,19 +14419,19 @@ passes them as first argument to [func@extents_to_pixels]). version="1.50"> Returns the resolved direction of the line. - + line="5102">Returns the resolved direction of the line. + the resolved direction of the line + line="5108">the resolved direction of the line a `PangoLayoutLine` + line="5104">a `PangoLayoutLine` @@ -14112,20 +14441,20 @@ passes them as first argument to [func@extents_to_pixels]). version="1.50"> Returns the start index of the line, as byte index + line="5053">Returns the start index of the line, as byte index into the text of the layout. - + the start index of the line + line="5060">the start index of the line a `PangoLayoutLine` + line="5055">a `PangoLayoutLine` @@ -14134,13 +14463,13 @@ into the text of the layout. c:identifier="pango_layout_line_get_x_ranges"> Gets a list of visual ranges corresponding to a given logical range. + line="5337">Gets a list of visual ranges corresponding to a given logical range. This list is not necessarily minimal - there may be consecutive ranges which are adjacent. The ranges will be sorted from left to right. The ranges are with respect to the left edge of the entire layout, not with respect to the line. - + @@ -14148,13 +14477,13 @@ layout, not with respect to the line. a `PangoLayoutLine` + line="5339">a `PangoLayoutLine` Start byte index of the logical range. If this value + line="5340">Start byte index of the logical range. If this value is less than the start index for the line, then the first range will extend all the way to the leading edge of the layout. Otherwise, it will start at the leading edge of the first character. @@ -14163,7 +14492,7 @@ layout, not with respect to the line. Ending byte index of the logical range. If this value is + line="5344">Ending byte index of the logical range. If this value is greater than the end index for the line, then the last range will extend all the way to the trailing edge of the layout. Otherwise, it will end at the trailing edge of the last character. @@ -14175,7 +14504,7 @@ layout, not with respect to the line. transfer-ownership="full"> location to + line="5348">location to store a pointer to an array of ranges. The array will be of length `2*n_ranges`, with each range starting at `(*ranges)[2*n]` and of width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed @@ -14191,7 +14520,7 @@ layout, not with respect to the line. transfer-ownership="full"> The number of ranges stored in @ranges + line="5354">The number of ranges stored in @ranges @@ -14199,8 +14528,8 @@ layout, not with respect to the line. Converts an index within a line to a X position. - + line="1771">Converts an index within a line to a X position. + @@ -14208,19 +14537,19 @@ layout, not with respect to the line. a `PangoLayoutLine` + line="1773">a `PangoLayoutLine` byte offset of a grapheme within the layout + line="1774">byte offset of a grapheme within the layout an integer indicating the edge of the grapheme to retrieve + line="1775">an integer indicating the edge of the grapheme to retrieve the position of. If > 0, the trailing edge of the grapheme, if 0, the leading of the grapheme @@ -14231,7 +14560,7 @@ layout, not with respect to the line. transfer-ownership="full"> location to store the x_offset (in Pango units) + line="1778">location to store the x_offset (in Pango units) @@ -14241,19 +14570,19 @@ layout, not with respect to the line. version="1.50"> Returns whether this is the first line of the paragraph. - + line="5086">Returns whether this is the first line of the paragraph. + %TRUE if this is the first line + line="5092">%TRUE if this is the first line a `PangoLayoutLine` + line="5088">a `PangoLayoutLine` @@ -14261,12 +14590,12 @@ layout, not with respect to the line. Increase the reference count of a `PangoLayoutLine` by one. - + line="4999">Increase the reference count of a `PangoLayoutLine` by one. + the line passed in. + line="5005">the line passed in. @@ -14276,7 +14605,7 @@ layout, not with respect to the line. allow-none="1"> a `PangoLayoutLine` + line="5001">a `PangoLayoutLine` @@ -14284,11 +14613,11 @@ layout, not with respect to the line. Decrease the reference count of a `PangoLayoutLine` by one. + line="5022">Decrease the reference count of a `PangoLayoutLine` by one. If the result is zero, the line and all associated memory will be freed. - + @@ -14296,7 +14625,7 @@ will be freed. a `PangoLayoutLine` + line="5024">a `PangoLayoutLine` @@ -14304,7 +14633,7 @@ will be freed. Converts from x offset to the byte index of the corresponding character + line="5118">Converts from x offset to the byte index of the corresponding character within the text of the layout. If @x_pos is outside the line, @index_ and @trailing will point to the very @@ -14315,24 +14644,24 @@ results in 0 being stored in @index_ and @trailing. An X position to the left of the line results in @index_ pointing to the (logical) last grapheme in the line and @trailing being set to the number of characters in that grapheme. The reverse is true for a left-to-right line. - + %FALSE if @x_pos was outside the line, %TRUE if inside + line="5140">%FALSE if @x_pos was outside the line, %TRUE if inside a `PangoLayoutLine` + line="5120">a `PangoLayoutLine` the X offset (in Pango units) from the left edge of the line. + line="5121">the X offset (in Pango units) from the left edge of the line. transfer-ownership="full"> location to store calculated byte index for the grapheme + line="5122">location to store calculated byte index for the grapheme in which the user clicked @@ -14351,7 +14680,7 @@ grapheme. The reverse is true for a left-to-right line. transfer-ownership="full"> location to store an integer indicating where in the + line="5124">location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the leading edge of the grapheme. @@ -14366,7 +14695,7 @@ grapheme. The reverse is true for a left-to-right line. c:type="PangoLayoutSerializeFlags"> Flags that influence the behavior of [method@Pango.Layout.serialize]. + line="363">Flags that influence the behavior of [method@Pango.Layout.serialize]. New members may be added to this enumeration over time. glib:name="PANGO_LAYOUT_SERIALIZE_DEFAULT"> Default behavior + line="365">Default behavior glib:name="PANGO_LAYOUT_SERIALIZE_CONTEXT"> Include context information + line="366">Include context information glib:name="PANGO_LAYOUT_SERIALIZE_OUTPUT"> Include information about the formatted output + line="367">Include information about the formatted output @@ -15264,6 +15593,9 @@ By subclassing `PangoRenderer` and overriding operations such as backends and destinations can be created. + Do renderer-specific initialization before drawing @@ -15530,6 +15862,11 @@ Use [method@Pango.Renderer.activate] to activate a renderer. + draw content for a glyph shaped with `PangoAttrShape` + @x, @y are the coordinates of the left edge of the baseline, + in user coordinates. @@ -15612,6 +15949,9 @@ using the given `PangoRenderer`; coordinates are in device space. + Do renderer-specific cleanup after drawing @@ -15660,6 +16000,9 @@ changes to colors. (See [method@Pango.Renderer.set_color]) + updates the renderer for a new run @@ -16461,6 +16804,9 @@ and must be implemented: + draws a `PangoGlyphString` @@ -16503,6 +16849,9 @@ and must be implemented: + draws a rectangle @@ -16551,6 +16900,11 @@ and must be implemented: + draws a squiggly line that approximately +covers the given rectangle in the style of an underline used to +indicate a spelling error. @@ -16591,6 +16945,11 @@ and must be implemented: + draw content for a glyph shaped with `PangoAttrShape` + @x, @y are the coordinates of the left edge of the baseline, + in user coordinates. @@ -16613,6 +16972,9 @@ and must be implemented: + draws a trapezoidal filled area @@ -16671,6 +17033,9 @@ and must be implemented: + draws a single glyph @@ -16711,6 +17076,10 @@ and must be implemented: + do renderer specific processing when rendering + attributes change @@ -16733,6 +17102,9 @@ and must be implemented: + Do renderer-specific initialization before drawing @@ -16746,6 +17118,9 @@ and must be implemented: + Do renderer-specific cleanup after drawing @@ -16759,6 +17134,9 @@ and must be implemented: + updates the renderer for a new run @@ -16775,6 +17153,9 @@ and must be implemented: + draws a `PangoGlyphItem` @@ -18567,7 +18948,7 @@ You **must** provide an alignment and position for @size tab stops. version="1.50"> Gets the Unicode character to use as decimal point. + line="589">Gets the Unicode character to use as decimal point. This is only relevant for tabs with %PANGO_TAB_DECIMAL alignment, which align content at the first occurrence of the decimal point @@ -18583,13 +18964,13 @@ decimal point according to the current locale. a `PangoTabArray` + line="591">a `PangoTabArray` the index of a tab stop + line="592">the index of a tab stop @@ -18759,7 +19140,7 @@ that were added as a result of growing the array. version="1.50"> Sets the Unicode character to use as decimal point. + line="558">Sets the Unicode character to use as decimal point. This is only relevant for tabs with %PANGO_TAB_DECIMAL alignment, which align content at the first occurrence of the decimal point @@ -18775,19 +19156,19 @@ to the current locale. a `PangoTabArray` + line="560">a `PangoTabArray` the index of a tab stop + line="561">the index of a tab stop the decimal point to use + line="562">the decimal point to use @@ -18856,7 +19237,7 @@ pixels. Utility function to ensure that the tab stops are in increasing order. + line="625">Utility function to ensure that the tab stops are in increasing order. @@ -18865,7 +19246,7 @@ pixels. a `PangoTabArray` + line="627">a `PangoTabArray` @@ -18877,17 +19258,27 @@ pixels. filename="pango/pango-tabs.c" line="392">Serializes a `PangoTabArray` to a string. -No guarantees are made about the format of the string, -it may change between Pango versions. +In the resulting string, serialized tabs are separated by newlines or commas. + +Individual tabs are serialized to a string of the form + + [ALIGNMENT:]POSITION[:DECIMAL_POINT] + +Where ALIGNMENT is one of _left_, _right_, _center_ or _decimal_, and +POSITION is the position of the tab, optionally followed by the unit _px_. +If ALIGNMENT is omitted, it defaults to _left_. If ALIGNMENT is _decimal_, +the DECIMAL_POINT character may be specified as a Unicode codepoint. + +Note that all tabs in the array must use the same unit. -The intended use of this function is testing and -debugging. The format is not meant as a permanent -storage format. +A typical example: + + 100px 200px center:300px right:400px a newly allocated string + line="416">a newly allocated string @@ -18904,7 +19295,7 @@ storage format. version="1.50"> Deserializes a `PangoTabArray` from a string. + line="458">Deserializes a `PangoTabArray` from a string. This is the counterpart to [method@Pango.TabArray.to_string]. See that functions for details about the format. @@ -18912,14 +19303,14 @@ See that functions for details about the format. a new `PangoTabArray` + line="467">a new `PangoTabArray` a string + line="460">a string @@ -19181,14 +19572,14 @@ Two encoded version numbers can be compared as integers. - + The micro component of the version of Pango available at compile-time. - + The minor component of the version of Pango available at compile-time. @@ -19196,7 +19587,7 @@ Two encoded version numbers can be compared as integers. line="71">wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word. + + do not wrap. + Create a new allow-breaks attribute. + line="1305">Create a new allow-breaks attribute. If breaks are disabled, the range will be kept in a single run, as far as possible. @@ -19457,7 +19858,7 @@ single run, as far as possible. the newly allocated + line="1314">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19466,7 +19867,7 @@ single run, as far as possible. %TRUE if we line breaks are allowed + line="1307">%TRUE if we line breaks are allowed @@ -19476,12 +19877,12 @@ single run, as far as possible. version="1.38"> Create a new background alpha attribute. + line="1280">Create a new background alpha attribute. the newly allocated + line="1286">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19490,7 +19891,7 @@ single run, as far as possible. the alpha value, between 1 and 65536 + line="1282">the alpha value, between 1 and 65536 @@ -19535,7 +19936,7 @@ single run, as far as possible. version="1.50"> Create a new baseline displacement attribute. + line="944">Create a new baseline displacement attribute. The effect of this attribute is to shift the baseline of a run, relative to the run of preceding run. @@ -19548,7 +19949,7 @@ relative to the run of preceding run. the newly allocated + line="960">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19557,7 +19958,7 @@ relative to the run of preceding run. either a `PangoBaselineShift` enumeration value or an absolute value (> 1024) + line="946">either a `PangoBaselineShift` enumeration value or an absolute value (> 1024) in Pango units, relative to the baseline of the previous run. Positive values displace the text upwards. @@ -19567,7 +19968,7 @@ relative to the run of preceding run. Apply customization from attributes to the breaks in @attrs. + line="2542">Apply customization from attributes to the breaks in @attrs. The line breaks are assumed to have been produced by [func@Pango.default_break] and [func@Pango.tailor_break]. @@ -19579,31 +19980,31 @@ by [func@Pango.default_break] and [func@Pango.tailor_break]. text to break. Must be valid UTF-8 + line="2544">text to break. Must be valid UTF-8 length of text in bytes (may be -1 if @text is nul-terminated) + line="2545">length of text in bytes (may be -1 if @text is nul-terminated) `PangoAttrList` to apply + line="2546">`PangoAttrList` to apply Byte offset of @text from the beginning of the paragraph + line="2547">Byte offset of @text from the beginning of the paragraph array with one `PangoLogAttr` + line="2548">array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in @@ -19612,7 +20013,7 @@ by [func@Pango.default_break] and [func@Pango.tailor_break]. length of @attrs array + line="2550">length of @attrs array @@ -19622,7 +20023,7 @@ by [func@Pango.default_break] and [func@Pango.tailor_break]. version="1.4"> Create a new font fallback attribute. + line="1035">Create a new font fallback attribute. If fallback is disabled, characters will only be used from the closest matching font on the system. @@ -19632,7 +20033,7 @@ that might contain the characters in the text. the newly allocated + line="1047">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19641,7 +20042,7 @@ that might contain the characters in the text. %TRUE if we should fall back on other fonts + line="1037">%TRUE if we should fall back on other fonts for characters the active font is missing @@ -19702,7 +20103,7 @@ stretch, and size simultaneously. version="1.38"> Create a new font features tag attribute. + line="1224">Create a new font features tag attribute. You can use this attribute to select OpenType font features like small-caps, alternative glyphs, ligatures, etc. for fonts that support them. @@ -19710,7 +20111,7 @@ alternative glyphs, ligatures, etc. for fonts that support them. the newly allocated + line="1234">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19719,7 +20120,7 @@ alternative glyphs, ligatures, etc. for fonts that support them. a string with OpenType font features, with the syntax of the [CSS + line="1226">a string with OpenType font features, with the syntax of the [CSS font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc) @@ -19730,7 +20131,7 @@ font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-des version="1.50"> Create a new font scale attribute. + line="979">Create a new font scale attribute. The effect of this attribute is to change the font size of a run, relative to the size of preceding run. @@ -19738,7 +20139,7 @@ relative to the size of preceding run. the newly allocated + line="990">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19747,7 +20148,7 @@ relative to the size of preceding run. a `PangoFontScale` value, which indicates font size change relative + line="981">a `PangoFontScale` value, which indicates font size change relative to the size of the previous run. @@ -19758,12 +20159,12 @@ relative to the size of preceding run. version="1.38"> Create a new foreground alpha attribute. + line="1255">Create a new foreground alpha attribute. the newly allocated + line="1261">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19772,7 +20173,7 @@ relative to the size of preceding run. the alpha value, between 1 and 65536 + line="1257">the alpha value, between 1 and 65536 @@ -19817,12 +20218,12 @@ relative to the size of preceding run. version="1.16"> Create a new gravity hint attribute. + line="1199">Create a new gravity hint attribute. the newly allocated + line="1205">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19831,7 +20232,7 @@ relative to the size of preceding run. the gravity hint value + line="1201">the gravity hint value @@ -19841,12 +20242,12 @@ relative to the size of preceding run. version="1.16"> Create a new gravity attribute. + line="1172">Create a new gravity attribute. the newly allocated + line="1178">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19855,7 +20256,7 @@ relative to the size of preceding run. the gravity value; should not be %PANGO_GRAVITY_AUTO + line="1174">the gravity value; should not be %PANGO_GRAVITY_AUTO @@ -19865,7 +20266,7 @@ relative to the size of preceding run. version="1.44"> Create a new insert-hyphens attribute. + line="1333">Create a new insert-hyphens attribute. Pango will insert hyphens when breaking lines in the middle of a word. This attribute can be used @@ -19874,7 +20275,7 @@ to suppress the hyphen. the newly allocated + line="1343">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19883,7 +20284,7 @@ to suppress the hyphen. %TRUE if hyphens should be inserted + line="1335">%TRUE if hyphens should be inserted @@ -19917,12 +20318,12 @@ to suppress the hyphen. version="1.6"> Create a new letter-spacing attribute. + line="1066">Create a new letter-spacing attribute. the newly allocated + line="1073">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -19931,7 +20332,7 @@ to suppress the hyphen. amount of extra space to add between + line="1068">amount of extra space to add between graphemes of the text, in Pango units @@ -19942,7 +20343,7 @@ to suppress the hyphen. version="1.50"> Modify the height of logical line extents by a factor. + line="1499">Modify the height of logical line extents by a factor. This affects the values returned by [method@Pango.LayoutLine.get_extents], @@ -19956,7 +20357,7 @@ This affects the values returned by the scaling factor to apply to the logical height + line="1501">the scaling factor to apply to the logical height @@ -19966,7 +20367,7 @@ This affects the values returned by version="1.50"> Override the height of logical line extents to be @height. + line="1526">Override the height of logical line extents to be @height. This affects the values returned by [method@Pango.LayoutLine.get_extents], @@ -19980,7 +20381,7 @@ This affects the values returned by the line height, in %PANGO_SCALE-ths of a point + line="1528">the line height, in %PANGO_SCALE-ths of a point @@ -19991,7 +20392,7 @@ This affects the values returned by version="1.50"> Deserializes a `PangoAttrList` from a string. + line="2819">Deserializes a `PangoAttrList` from a string. This is the counterpart to [method@Pango.AttrList.to_string]. See that functions for details about the format. @@ -19999,14 +20400,14 @@ See that functions for details about the format. a new `PangoAttrList` + line="2828">a new `PangoAttrList` a string + line="2821">a string @@ -20016,7 +20417,7 @@ See that functions for details about the format. version="1.46"> Create a new overline color attribute. + line="1467">Create a new overline color attribute. This attribute modifies the color of overlines. If not set, overlines will use the foreground color. @@ -20024,7 +20425,7 @@ If not set, overlines will use the foreground color. the newly allocated + line="1478">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20033,19 +20434,19 @@ If not set, overlines will use the foreground color. the red value (ranging from 0 to 65535) + line="1469">the red value (ranging from 0 to 65535) the green value + line="1470">the green value the blue value + line="1471">the blue value @@ -20055,12 +20456,12 @@ If not set, overlines will use the foreground color. version="1.46"> Create a new overline-style attribute. + line="1442">Create a new overline-style attribute. the newly allocated + line="1448">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20069,7 +20470,7 @@ If not set, overlines will use the foreground color. the overline style + line="1444">the overline style @@ -20077,12 +20478,12 @@ If not set, overlines will use the foreground color. Create a new baseline displacement attribute. + line="920">Create a new baseline displacement attribute. the newly allocated + line="927">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20091,7 +20492,7 @@ If not set, overlines will use the foreground color. the amount that the text should be displaced vertically, + line="922">the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards. @@ -20100,7 +20501,7 @@ If not set, overlines will use the foreground color. Create a new font size scale attribute. + line="1009">Create a new font size scale attribute. The base font for the affected text will have its size multiplied by @scale_factor. @@ -20108,7 +20509,7 @@ its size multiplied by @scale_factor. the newly allocated + line="1018">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20117,7 +20518,7 @@ its size multiplied by @scale_factor. factor to scale the font + line="1011">factor to scale the font @@ -20127,7 +20528,7 @@ its size multiplied by @scale_factor. version="1.50"> Marks the range of the attribute as a single sentence. + line="1415">Marks the range of the attribute as a single sentence. Note that this may require adjustments to word and sentence classification around the range. @@ -20135,7 +20536,7 @@ sentence classification around the range. the newly allocated + line="1423">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20146,7 +20547,7 @@ sentence classification around the range. moved-to="AttrShape.new"> Create a new shape attribute. + line="1145">Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. @@ -20156,7 +20557,7 @@ or a widget inside a `PangoLayout`. the newly allocated + line="1157">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20165,13 +20566,13 @@ or a widget inside a `PangoLayout`. ink rectangle to assign to each character + line="1147">ink rectangle to assign to each character logical rectangle to assign to each character + line="1148">logical rectangle to assign to each character @@ -20182,7 +20583,7 @@ or a widget inside a `PangoLayout`. version="1.8"> Creates a new shape attribute. + line="1092">Creates a new shape attribute. Like [func@Pango.AttrShape.new], but a user data pointer is also provided; this pointer can be accessed when later @@ -20191,7 +20592,7 @@ rendering the glyph. the newly allocated + line="1109">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20200,13 +20601,13 @@ rendering the glyph. ink rectangle to assign to each character + line="1094">ink rectangle to assign to each character logical rectangle to assign to each character + line="1095">logical rectangle to assign to each character allow-none="1"> user data pointer + line="1096">user data pointer destroy="4"> function to copy @data when the + line="1097">function to copy @data when the attribute is copied. If %NULL, @data is simply copied as a pointer @@ -20238,7 +20639,7 @@ rendering the glyph. scope="async"> function to free @data when the + line="1100">function to free @data when the attribute is freed @@ -20249,13 +20650,13 @@ rendering the glyph. version="1.44"> Create a new attribute that influences how invisible + line="1362">Create a new attribute that influences how invisible characters are rendered. the newly allocated + line="1369">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20264,7 +20665,7 @@ characters are rendered. `PangoShowFlags` to apply + line="1364">`PangoShowFlags` to apply @@ -20345,7 +20746,7 @@ characters are rendered. version="1.8"> Create a new strikethrough color attribute. + line="888">Create a new strikethrough color attribute. This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color. @@ -20353,7 +20754,7 @@ If not set, strikethrough lines will use the foreground color. the newly allocated + line="899">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20362,19 +20763,19 @@ If not set, strikethrough lines will use the foreground color. the red value (ranging from 0 to 65535) + line="890">the red value (ranging from 0 to 65535) the green value + line="891">the green value the blue value + line="892">the blue value @@ -20383,12 +20784,12 @@ If not set, strikethrough lines will use the foreground color. c:identifier="pango_attr_strikethrough_new"> Create a new strike-through attribute. + line="865">Create a new strike-through attribute. the newly allocated + line="871">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20397,7 +20798,7 @@ If not set, strikethrough lines will use the foreground color. %TRUE if the text should be struck-through + line="867">%TRUE if the text should be struck-through @@ -20429,13 +20830,13 @@ If not set, strikethrough lines will use the foreground color. version="1.50"> Create a new attribute that influences how characters + line="1552">Create a new attribute that influences how characters are transformed during shaping. the newly allocated + line="1559">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20444,7 +20845,7 @@ are transformed during shaping. `PangoTextTransform` to apply + line="1554">`PangoTextTransform` to apply @@ -20512,7 +20913,7 @@ by using [func@Pango.AttrType.get_name]. version="1.8"> Create a new underline color attribute. + line="833">Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color. @@ -20520,7 +20921,7 @@ If not set, underlines will use the foreground color. the newly allocated + line="844">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20529,19 +20930,19 @@ If not set, underlines will use the foreground color. the red value (ranging from 0 to 65535) + line="835">the red value (ranging from 0 to 65535) the green value + line="836">the green value the blue value + line="837">the blue value @@ -20550,12 +20951,12 @@ If not set, underlines will use the foreground color. c:identifier="pango_attr_underline_new"> Create a new underline-style attribute. + line="810">Create a new underline-style attribute. the newly allocated + line="816">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20564,7 +20965,7 @@ If not set, underlines will use the foreground color. the underline style + line="812">the underline style @@ -20617,7 +21018,7 @@ If not set, underlines will use the foreground color. version="1.50"> Marks the range of the attribute as a single word. + line="1388">Marks the range of the attribute as a single word. Note that this may require adjustments to word and sentence classification around the range. @@ -20625,7 +21026,7 @@ sentence classification around the range. the newly allocated + line="1396">the newly allocated `PangoAttribute`, which should be freed with [method@Pango.Attribute.destroy] @@ -20665,7 +21066,7 @@ Unicode bidirectional algorithm. deprecated-version="1.44"> Determines possible line, word, and character breaks + line="2464">Determines possible line, word, and character breaks for a string of Unicode text with a single analysis. For most purposes you may want to use [func@Pango.get_log_attrs]. @@ -20679,25 +21080,25 @@ For most purposes you may want to use [func@Pango.get_log_attrs]. the text to process. Must be valid UTF-8 + line="2466">the text to process. Must be valid UTF-8 length of @text in bytes (may be -1 if @text is nul-terminated) + line="2467">length of @text in bytes (may be -1 if @text is nul-terminated) `PangoAnalysis` structure for @text + line="2468">`PangoAnalysis` structure for @text an array to store character information in + line="2469">an array to store character information in @@ -20705,7 +21106,7 @@ For most purposes you may want to use [func@Pango.get_log_attrs]. size of the array passed as @attrs + line="2470">size of the array passed as @attrs @@ -20713,7 +21114,7 @@ For most purposes you may want to use [func@Pango.get_log_attrs]. This is the default break algorithm. + line="2430">This is the default break algorithm. It applies rules from the [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/) without language-specific tailoring, therefore the @analyis argument is unused @@ -20730,13 +21131,13 @@ See [func@Pango.attr_break] for attribute-based customization. text to break. Must be valid UTF-8 + line="2432">text to break. Must be valid UTF-8 length of text in bytes (may be -1 if @text is nul-terminated) + line="2433">length of text in bytes (may be -1 if @text is nul-terminated) allow-none="1"> a `PangoAnalysis` structure for the @text + line="2434">a `PangoAnalysis` structure for the @text logical attributes to fill in + line="2435">logical attributes to fill in size of the array passed as @attrs + line="2436">size of the array passed as @attrs @@ -20901,19 +21302,17 @@ and @next_paragraph_start are filled with the length of @text moved-to="FontDescription.from_string"> Creates a new font description from a string representation. + line="1401">Creates a new font description from a string representation. The string must have the form - "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", + [FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS] [FEATURES] where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. -VARIATIONS is a comma-separated list of font variation -specifications of the form "\@axis=value" (the = sign is optional). The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic". @@ -20936,6 +21335,12 @@ The following words are understood as gravity values: "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left", "East", "Rotated-Right", "West". +VARIATIONS is a comma-separated list of font variations +of the form @‍axis1=value,axis2=value,... + +FEATURES is a comma-separated list of font features of the form +\#‍feature1=value,feature2=value,... + Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to %NULL. If STYLE-OPTIONS is missing, then all style @@ -20944,19 +21349,19 @@ size in the resulting font description will be set to 0. A typical example: - "Cantarell Italic Light 15 \@wght=200" - + Cantarell Italic Light 15 @‍wght=200 #‍tnum=1 + a new `PangoFontDescription`. + line="1454">a new `PangoFontDescription`. string representation of a font description. + line="1403">string representation of a font description. @@ -20964,7 +21369,7 @@ A typical example: Computes a `PangoLogAttr` for each character in @text. + line="2588">Computes a `PangoLogAttr` for each character in @text. The @attrs array must have one `PangoLogAttr` for each position in @text; if @text contains N characters, @@ -20981,31 +21386,31 @@ a word to know the word is a word). text to process. Must be valid UTF-8 + line="2590">text to process. Must be valid UTF-8 length in bytes of @text + line="2591">length in bytes of @text embedding level, or -1 if unknown + line="2592">embedding level, or -1 if unknown language tag + line="2593">language tag array with one `PangoLogAttr` + line="2594">array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in @@ -21014,7 +21419,7 @@ a word to know the word is a word). length of @attrs array + line="2596">length of @attrs array @@ -21025,7 +21430,7 @@ a word to know the word is a word). deprecated-version="1.30"> Returns the mirrored character of a Unicode character. + line="298">Returns the mirrored character of a Unicode character. Mirror characters are determined by the Unicode mirrored property. Use [func@GLib.unichar_get_mirror_char] instead; @@ -21034,7 +21439,7 @@ Mirror characters are determined by the Unicode mirrored property. %TRUE if @ch has a mirrored character and @mirrored_ch is + line="307">%TRUE if @ch has a mirrored character and @mirrored_ch is filled in, %FALSE otherwise @@ -21042,13 +21447,13 @@ filled in, %FALSE otherwise a Unicode character + line="300">a Unicode character location to store the mirrored character + line="301">location to store the mirrored character @@ -21236,7 +21641,7 @@ This is totally different from [func@GLib.unichar_iszerowidth] and is at best mi Breaks a piece of text into segments with consistent directional + line="1645">Breaks a piece of text into segments with consistent directional level and font. Each byte of @text will be contained in exactly one of the items in the @@ -21248,11 +21653,11 @@ at a range before or containing @start_index; @cached_iter will be advanced to the range covering the position just after @start_index + @length. (i.e. if itemizing in a loop, just keep passing in the same @cached_iter). - + a `GList` of + line="1669">a `GList` of [struct@Pango.Item] structures. The items should be freed using [method@Pango.Item.free] in combination with [func@GLib.List.free_full]. @@ -21263,33 +21668,33 @@ in the same @cached_iter). a structure holding information that affects + line="1647">a structure holding information that affects the itemization process. the text to itemize. Must be valid UTF-8 + line="1649">the text to itemize. Must be valid UTF-8 first byte in @text to process + line="1650">first byte in @text to process the number of bytes (not characters) to process + line="1651">the number of bytes (not characters) to process after @start_index. This must be >= 0. the set of attributes that apply to @text. + line="1653">the set of attributes that apply to @text. allow-none="1"> Cached attribute iterator + line="1654">Cached attribute iterator @@ -21308,16 +21713,16 @@ in the same @cached_iter). version="1.4"> Like `pango_itemize()`, but with an explicitly specified base direction. + line="1597">Like `pango_itemize()`, but with an explicitly specified base direction. The base direction is used when computing bidirectional levels. [func@itemize] gets the base direction from the `PangoContext` (see [method@Pango.Context.set_base_dir]). - + a `GList` of + line="1615">a `GList` of [struct@Pango.Item] structures. The items should be freed using [method@Pango.Item.free] probably in combination with [func@GLib.List.free_full]. @@ -21328,39 +21733,39 @@ The base direction is used when computing bidirectional levels. a structure holding information that affects + line="1599">a structure holding information that affects the itemization process. base direction to use for bidirectional processing + line="1601">base direction to use for bidirectional processing the text to itemize. + line="1602">the text to itemize. first byte in @text to process + line="1603">first byte in @text to process the number of bytes (not characters) to process + line="1604">the number of bytes (not characters) to process after @start_index. This must be >= 0. the set of attributes that apply to @text. + line="1606">the set of attributes that apply to @text. Cached attribute iterator + line="1607">Cached attribute iterator @@ -21495,7 +21900,7 @@ languages returned by this function. version="1.4"> Return the bidirectional embedding levels of the input paragraph. + line="86">Return the bidirectional embedding levels of the input paragraph. The bidirectional embedding levels are defined by the [Unicode Bidirectional Algorithm](http://www.unicode.org/reports/tr9/). @@ -21506,7 +21911,7 @@ characters in the text will determine the final resolved direction. a newly allocated array of embedding levels, one item per + line="101">a newly allocated array of embedding levels, one item per character (not byte), that should be freed using [func@GLib.free]. @@ -21514,20 +21919,20 @@ characters in the text will determine the final resolved direction. the text to itemize. + line="88">the text to itemize. the number of bytes (not characters) to process, or -1 + line="89">the number of bytes (not characters) to process, or -1 if @text is nul-terminated and the length should be calculated. input base direction, and output resolved direction. + line="91">input base direction, and output resolved direction. @@ -21792,7 +22197,7 @@ for @error. Parses a font stretch. + line="1900">Parses a font stretch. The allowed values are "ultra_condensed", "extra_condensed", "condensed", @@ -21803,14 +22208,14 @@ ignored and the '_' characters may be omitted. %TRUE if @str was successfully parsed. + line="1914">%TRUE if @str was successfully parsed. a string to parse. + line="1902">a string to parse. transfer-ownership="full"> a `PangoStretch` to store the result in. + line="1903">a `PangoStretch` to store the result in. if %TRUE, issue a g_warning() on bad input. + line="1904">if %TRUE, issue a g_warning() on bad input. @@ -21833,7 +22238,7 @@ ignored and the '_' characters may be omitted. Parses a font style. + line="1834">Parses a font style. The allowed values are "normal", "italic" and "oblique", case variations being @@ -21842,14 +22247,14 @@ ignored. %TRUE if @str was successfully parsed. + line="1846">%TRUE if @str was successfully parsed. a string to parse. + line="1836">a string to parse. transfer-ownership="full"> a `PangoStyle` to store the result in. + line="1837">a `PangoStyle` to store the result in. if %TRUE, issue a g_warning() on bad input. + line="1838">if %TRUE, issue a g_warning() on bad input. @@ -21872,7 +22277,7 @@ ignored. Parses a font variant. + line="1856">Parses a font variant. The allowed values are "normal", "small-caps", "all-small-caps", "petite-caps", "all-petite-caps", "unicase" and "title-caps", @@ -21881,14 +22286,14 @@ case variations being ignored. %TRUE if @str was successfully parsed. + line="1868">%TRUE if @str was successfully parsed. a string to parse. + line="1858">a string to parse. transfer-ownership="full"> a `PangoVariant` to store the result in. + line="1859">a `PangoVariant` to store the result in. if %TRUE, issue a g_warning() on bad input. + line="1860">if %TRUE, issue a g_warning() on bad input. @@ -21911,7 +22316,7 @@ case variations being ignored. Parses a font weight. + line="1878">Parses a font weight. The allowed values are "heavy", "ultrabold", "bold", "normal", "light", "ultraleight" @@ -21920,14 +22325,14 @@ and integers. Case variations are ignored. %TRUE if @str was successfully parsed. + line="1890">%TRUE if @str was successfully parsed. a string to parse. + line="1880">a string to parse. transfer-ownership="full"> a `PangoWeight` to store the result in. + line="1881">a `PangoWeight` to store the result in. if %TRUE, issue a g_warning() on bad input. + line="1882">if %TRUE, issue a g_warning() on bad input. @@ -22037,7 +22442,7 @@ levels of the items. The original list is unmodified. (Please open a bug if you use this function. It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.) - + version="1.50"> Deserializes a `PangoTabArray` from a string. + line="458">Deserializes a `PangoTabArray` from a string. This is the counterpart to [method@Pango.TabArray.to_string]. See that functions for details about the format. @@ -22589,14 +22994,14 @@ See that functions for details about the format. a new `PangoTabArray` + line="467">a new `PangoTabArray` a string + line="460">a string @@ -22606,7 +23011,7 @@ See that functions for details about the format. version="1.44"> Apply language-specific tailoring to the breaks in @attrs. + line="2494">Apply language-specific tailoring to the breaks in @attrs. The line breaks are assumed to have been produced by [func@Pango.default_break]. @@ -22623,32 +23028,32 @@ to apply attributes to the whole paragraph. text to process. Must be valid UTF-8 + line="2496">text to process. Must be valid UTF-8 length in bytes of @text + line="2497">length in bytes of @text `PangoAnalysis` for @text + line="2498">`PangoAnalysis` for @text Byte offset of @text from the beginning of the + line="2499">Byte offset of @text from the beginning of the paragraph, or -1 to ignore attributes from @analysis array with one `PangoLogAttr` + line="2501">array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in @@ -22657,7 +23062,7 @@ to apply attributes to the whole paragraph. length of @attrs array + line="2503">length of @attrs array @@ -22688,7 +23093,7 @@ to apply attributes to the whole paragraph. Determines the inherent direction of a character. + line="264">Determines the inherent direction of a character. The inherent direction is either `PANGO_DIRECTION_LTR`, `PANGO_DIRECTION_RTL`, or `PANGO_DIRECTION_NEUTRAL`. @@ -22701,14 +23106,14 @@ can be used instead. the direction of the character. + line="278">the direction of the character. a Unicode character + line="266">a Unicode character From d80f072bf954b49415e5850a8c6f7fdb6c8ac19d Mon Sep 17 00:00:00 2001 From: bailuk Date: Mon, 17 Mar 2025 17:28:13 +0100 Subject: [PATCH 5/5] Add autogenerated notice and changelog --- CHANGELOG.md | 1 + doc/gen/README.md | 3 +++ doc/gen/alias_table.md | 3 +++ doc/gen/callback_table.md | 3 +++ doc/gen/enum_table.md | 3 +++ doc/gen/size_table.md | 3 +++ doc/gen/structure_table.md | 3 +++ generator/src/main/kotlin/ch/bailu/gtk/App.kt | 2 ++ 8 files changed, 21 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0371baa..91e6c8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ - Generator: Add markdown summary logs - Generator: Add gstreamer support - Generator: Update Kotlin to 2.1.10 +- Generator: Update gir files (sync with debian testing) - Library: Add PropertyHolder to accesss GObject properties - Library: Update findbugs to spotbugs-annotations:4.9.3 - Library: Update jna to 5.17.0 diff --git a/doc/gen/README.md b/doc/gen/README.md index d3b7244..58778eb 100644 --- a/doc/gen/README.md +++ b/doc/gen/README.md @@ -26,3 +26,6 @@ - [callback_table.md](callback_table.md) - [enum_table.md](enum_table.md) - [size_table.md](size_table.md) + +--- +**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen) diff --git a/doc/gen/alias_table.md b/doc/gen/alias_table.md index 03a6788..ba281f8 100644 --- a/doc/gen/alias_table.md +++ b/doc/gen/alias_table.md @@ -29,3 +29,6 @@ | glib.DateYear | glib.guint16 | glib.RWLockReaderLocker | glib.none | glib.TimeSpan | glib.gint64 + +--- +**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen) diff --git a/doc/gen/callback_table.md b/doc/gen/callback_table.md index e6c4635..b520c41 100644 --- a/doc/gen/callback_table.md +++ b/doc/gen/callback_table.md @@ -330,3 +330,6 @@ | ContentSerializeFunc | (CallbackTag:(ParameterTag:none:void:):ContentSerializeFunc:(ParameterTag:ContentSerializer:GdkContentSerializer*:)) | ContentDeserializeFunc | (CallbackTag:(ParameterTag:none:void:):ContentDeserializeFunc:(ParameterTag:ContentDeserializer:GdkContentDeserializer*:)) | CursorGetTextureCallback | (CallbackTag:(ParameterTag:Texture:GdkTexture*:):CursorGetTextureCallback:(ParameterTag:Cursor:GdkCursor*:):(ParameterTag:gint:int:):(ParameterTag:gdouble:double:):(ParameterTag:gint:int*:):(ParameterTag:gint:int*:):(ParameterTag:gint:int*:):(ParameterTag:gint:int*:):(ParameterTag:gpointer:gpointer:)) + +--- +**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen) diff --git a/doc/gen/enum_table.md b/doc/gen/enum_table.md index 30a349a..2b34865 100644 --- a/doc/gen/enum_table.md +++ b/doc/gen/enum_table.md @@ -1052,3 +1052,6 @@ | GtkScrollablePolicy | GtkPropagationLimit | StringFilterMatchMode + +--- +**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen) diff --git a/doc/gen/size_table.md b/doc/gen/size_table.md index e2a97a5..5e96f81 100644 --- a/doc/gen/size_table.md +++ b/doc/gen/size_table.md @@ -4,3 +4,6 @@ |--------------------------------|----- | gobject.TypeInterface | 16 | gobject.TypeClass | 8 + +--- +**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen) diff --git a/doc/gen/structure_table.md b/doc/gen/structure_table.md index dcb317f..63aa3c8 100644 --- a/doc/gen/structure_table.md +++ b/doc/gen/structure_table.md @@ -1727,3 +1727,6 @@ | MapListModel | true | | ScrollInfo | true | | ComboBoxClass | | ComboBox + +--- +**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen) diff --git a/generator/src/main/kotlin/ch/bailu/gtk/App.kt b/generator/src/main/kotlin/ch/bailu/gtk/App.kt index eed54f3..7720fb5 100644 --- a/generator/src/main/kotlin/ch/bailu/gtk/App.kt +++ b/generator/src/main/kotlin/ch/bailu/gtk/App.kt @@ -57,5 +57,7 @@ private fun logTable(outDir: String, logable: Logable, file: String) { println(" --> $path") BufferedWriter(FileWriter(path)).use { logable.log(it) + it.write("\n---\n") + it.write("**Autogenerated**. Run `./gradlew generate-update-doc` to update in [/doc/gen](/doc/gen)\n") } }